--- name: feishu-create-doc description: | 创建飞书云文档。从 Lark-flavored Markdown 内容创建新的飞书云文档，支持指定创建位置（文件夹/知识库/知识空间）。 --- # feishu_mcp_create_doc 通过 MCP 调用 `create-doc`，从 Lark-flavored Markdown 内容创建一个新的飞书云文档。 # 返回值 工具成功执行后，返回一个 JSON 对象，包含以下字段： - **`doc_id`**（string）：文档的唯一标识符（token），格式如 `doxcnXXXXXXXXXXXXXXXXXXX` - **`doc_url`**（string）：文档的访问链接，可直接在浏览器中打开，格式如 `https://bytedance.feishu.cn/docx/doxcnXXXXXXXXXXXXXXXXXXX` - **`message`**（string）：操作结果消息，如"文档创建成功" # 参数 ## markdown（必填） 文档的 Markdown 内容，使用 Lark-flavored Markdown 格式。 调用本工具的markdown内容应当尽量结构清晰,样式丰富, 有很高的可读性. 合理的使用callout高亮块, 分栏,表格等能力,并合理的运用插入图片与mermaid的能力,做到图文并茂.. 你需要遵循以下原则: - **结构清晰**：标题层级 ≤ 4 层，用 Callout 突出关键信息 - **视觉节奏**：用分割线、分栏、表格打破大段纯文字 - **图文交融**：流程和架构优先用 Mermaid/PlantUML 可视化 - **克制留白**：Callout 不过度、加粗只强调核心词 当用户有明确的样式,风格需求时,应当以用户的需求为准!! **重要提示**： - **禁止重复标题**：markdown 内容开头不要写与 title 相同的一级标题！title 参数已经是文档标题，markdown 应直接从正文内容开始 - **目录**：飞书自动生成，无需手动添加 - Markdown 语法必须符合 Lark-flavored Markdown 规范，详见下方"内容格式"章节 - 创建较长的文档时,强烈建议配合update-doc中的append mode, 进行分段的创建,提高成功率. ## title（可选） 文档标题。 ## folder_token（可选） 父文件夹的 token。如果不提供，文档将创建在用户的个人空间根目录。 folder_token 可以从飞书文件夹 URL 中获取，格式如：`https://xxx.feishu.cn/drive/folder/fldcnXXXX`，其中 `fldcnXXXX` 即为 folder_token。 ## wiki_node（可选） 知识库节点 token 或 URL（可选，传入则在该节点下创建文档，与 folder_token 和 wiki_space 互斥） wiki_node 可以从飞书知识库页面 URL 中获取，格式如：`https://xxx.feishu.cn/wiki/wikcnXXXX`，其中 `wikcnXXXX` 即为 wiki_node token。 ## wiki_space（可选） 知识空间 ID（可选，传入则在该空间根目录下创建文档。特殊值 `my_library` 表示用户的个人知识库。与 wiki_node 和 folder_token 互斥） wiki_space 可以从知识空间设置页面 URL 中获取，格式如：`https://xxx.feishu.cn/wiki/settings/7448880953499959300`，其中 `7448880953499959300` 即为 wiki_space ID。 **参数优先级**：wiki_node > wiki_space > folder_token # 示例 ## 示例 1：创建简单文档 ```json { "title": "项目计划", "markdown": "# 项目概述\n\n这是一个新项目。\n\n## 目标\n\n- 目标 1\n- 目标 2" } ``` ## 示例 2：创建到指定文件夹 ```json { "title": "会议纪要", "folder_token": "fldcnXXXXXXXXXXXXXXXXXXXXXX", "markdown": "# 周会 2025-01-15\n\n## 讨论议题\n\n1. 项目进度\n2. 下周计划" } ``` ## 示例 3：使用飞书扩展语法 使用高亮块、表格等飞书特有功能： ```json { "title": "产品需求", "markdown": "\n重要需求说明\n\n\n## 功能列表\n\n\n| 功能 | 优先级 |\n|------|--------|\n| 登录 | P0 |\n| 导出 | P1 |\n" } ``` ## 示例 4：创建到知识库节点下 ```json { "title": "技术文档", "wiki_node": "wikcnXXXXXXXXXXXXXXXXXXXXXX", "markdown": "# API 接口说明\n\n这是一个知识库文档。" } ``` ## 示例 5：创建到知识空间根目录 ```json { "title": "项目概览", "wiki_space": "7448880953499959300", "markdown": "# 项目概览\n\n这是知识空间根目录下的一级文档。" } ``` ## 示例 6：创建到个人知识库 ```json { "title": "学习笔记", "wiki_space": "my_library", "markdown": "# 学习笔记\n\n这是创建在个人知识库中的文档。" } ``` # 内容格式 文档内容使用 **Lark-flavored Markdown** 格式，这是标准 Markdown 的扩展版本，支持飞书文档的所有块类型和富文本格式。 ## 通用规则 - 使用标准 Markdown 语法作为基础 - 使用自定义 XML 标签实现飞书特有功能（具体标签见各功能章节） - 需要显示特殊字符时使用反斜杠转义：`* ~ ` $ [ ] < > { } | ^` --- ## 📝 基础块类型 ### 文本（段落） ```markdown 普通文本段落 段落中的**粗体文字** 多个段落之间用空行分隔。 居中文本 {align="center"} 右对齐文本 {align="right"} ``` **段落对齐**：支持 `{align="left|center|right"}` 语法。可与颜色组合：`{color="blue" align="center"}` ### 标题 飞书支持 9 级标题。H1-H6 使用标准 Markdown 语法，H7-H9 使用 HTML 标签： ```markdown # 一级标题 ## 二级标题 ### 三级标题 #### 四级标题 ##### 五级标题 ###### 六级标题 七级标题 八级标题 九级标题 # 带颜色的标题 {color="blue"} ## 红色标题 {color="red"} # 居中标题 {align="center"} ## 蓝色居中标题 {color="blue" align="center"} ``` **标题属性**：支持 `{color="颜色名"}` 和 `{align="left|center|right"}` 语法，可组合使用。颜色值：red, orange, yellow, green, blue, purple, gray。请谨慎使用该能力. ### 列表 有序列表,无序列表嵌套使用tab或者 2 空格缩进 ```markdown - 无序项1（ - 无序项1.a - 无序项1.b 1. 有序项1 2. 有序项2 - [ ] 待办 - [x] 已完成 ``` ### 引用块 ```markdown > 这是一段引用 > 可以跨多行 > 引用中支持**加粗**和*斜体*等格式 ``` ### 代码块 **⚠️** 只支持围栏代码块（` ``` `），不支持缩进代码块。 ````markdown ```python print("Hello") ``` ```` 支持语言：python, javascript, go, java, sql, json, yaml, shell 等。 ### 分割线 ```markdown --- ``` --- ## 🎨 富文本格式 ### 文本样式 `**粗体**` `*斜体*` `~~删除线~~` `` `行内代码` `` `下划线` ### 文字颜色 `红色` `黄色背景` 支持: red, orange, yellow, green, blue, purple, gray ### 链接 `[链接文字](https://example.com)` （不支持锚点链接） ### 行内公式（LaTeX） `$E = mc^2$`（`$`前后需空格）或 `E = mc^2`（无限制，推荐） --- ## 🚀 高级块类型 ### 高亮块（Callout） ```html 支持**格式化**的内容，可包含多个块 ``` **属性**: emoji (使用emoji 字符如 ✅ ⚠️ 💡), background-color, border-color, text-color **背景色**: light-red/red, light-blue/blue, light-green/green, light-yellow/yellow, light-orange/orange, light-purple/purple, pale-gray/light-gray/dark-gray **常用**: 💡light-blue(提示) ⚠️light-yellow(警告) ❌light-red(危险) ✅light-green(成功) **限制**: callout子块仅支持文本、标题、列表、待办、引用。不支持代码块、表格、图片。 ### 分栏（Grid） 适合对比、并列展示场景。支持 2-5 列： #### 两栏（等宽） ```html 左栏内容 右栏内容 ``` #### 三栏自定义宽度 ```html 左栏(20%) 中栏(60%) 右栏(20%) ``` **属性**: `cols`(列数 2-5), `width`(列宽百分比，总和为100，等宽时可省略) ### 表格 #### 标准 Markdown 表格 ```markdown | 列 1 | 列 2 | 列 3 | |------|------|------| | 单元格 1 | 单元格 2 | 单元格 3 | | 单元格 4 | 单元格 5 | 单元格 6 | ``` #### 飞书增强表格 当单元格需要复杂内容（列表、代码块、高亮块等）时使用。 **层级结构**（必须严格遵守）： ``` ← 表格容器 ← 行（直接子元素只能是 lark-tr） 内容 ← 单元格（直接子元素只能是 lark-td） 内容 ← 每行的 lark-td 数量必须相同！ ``` **属性**： - `column-widths`：列宽，逗号分隔像素值，总宽≈730 - `header-row`：首行是否为表头（`"true"` 或 `"false"`） - `header-column`：首列是否为表头（`"true"` 或 `"false"`） **单元格写法**：内容前后必须空行 ```html 这里写内容 ``` **完整示例**（2行3列）： ```html **表头1** **表头2** **表头3** 普通文本 - 列表项1 - 列表项2 代码内容 ``` **限制**：单元格内不支持 Grid 和嵌套表格 **合并单元格**：读取时返回 `rowspan/colspan` 属性，创建暂不支持 **禁止**： - 混用 Markdown 表格语法（`|---|`） - 使用 `
` 换行 - 遗漏 `` 标签 ### 图片 ```html ``` **属性**: url (必需，系统会自动下载并上传), width, height, align (left/center/right), caption **⚠️ 重要**: 不支持直接使用 `token` 属性（如 ``），只支持 URL 方式。系统会自动下载图片并上传到飞书。 支持 PNG/JPG/GIF/WebP/BMP，最大 10MB **图片/文件插入方式选择**： - **有公开可访问的图片 URL** → 直接在 create-doc / update-doc 的 markdown 中使用 `` 一步到位 - **本地图片或文件**（如用户在聊天中发送的图片/文件） → 先用 create-doc / update-doc 创建或更新文档文本内容，再用 `feishu_doc_media` 工具将本地图片或文件追加到文档末尾。如需媒体出现在文档中间特定位置，可先用 create-doc 写好之前的内容，调用 `feishu_doc_media` 追加图片/文件，最后用 update-doc 的 **append** 模式追加后续内容 ### 文件 ```html ``` **属性**: - url (文件 URL，必需，系统会自动下载并上传) - name (文件名，必需) - view-type (1=卡片视图, 2=预览视图，可选) **⚠️ 重要**: 不支持直接使用 `token` 属性（如 ``） ### 画板（Mermaid / PlantUML 图表） 支持两种图表语法：Mermaid 和 PlantUML。 #### Mermaid 图表 **图表优先选择此格式**. mermaid图表会被渲染为可视化的画板, 如果能用mermaid实现的图表,应当优先选择mermaid. ````markdown ```mermaid graph TD A[开始] --> B{判断} B -->|是| C[处理] B -->|否| D[结束] ``` ```` **支持图表类型**: flowchart, sequenceDiagram, classDiagram, stateDiagram, gantt, mindmap, erDiagram #### PlantUML 图表 PlantUML图表会被渲染为可视化的画板. mermaid满足不了的场景可以选择plantUML进行绘图. ````markdown ```plantuml @startuml Alice -> Bob: Hello Bob --> Alice: Hi! @enduml ``` ```` **支持图表类型**: sequence, usecase, class, activity, component, state, object, deployment #### 读取画板 读取时返回 `` 标签： ```html ``` **属性**: token (画板标识), align (left/center/right), width, height **重要说明**： - create-doc时用 Mermaid/PlantUML 代码块，系统自动转换为画板; 禁止以``的方式写入!! - 读取时只能获取 token，可通过fetch-file工具进行查看内容。无法获取原始源码 ### 多维表格（Bitable） ```html ``` **属性**: view (table/kanban，默认 table) **注意**: token 是只读属性，创建时不能指定只能创建空的多维表格，创建后再手动添加数据。 ### 会话卡片（ChatCard） ```html ``` **属性**: id (格式 oc_xxx, 必需), align (left/center/right) ### 内嵌网页（Iframe） ```html