飞书文档创建规范指南#

1. 概述#

本技能是 其他飞书文档技能的参考规范，不可直接调用。整合了以下来源的验证经验：

• feishu-cli 项目代码实现（ converter/、 client/board.go、 cmd/import_markdown.go）
• feishu-cli-write、 feishu-cli-import、 feishu-cli-plantuml 技能的实测数据
• 大规模导入测试：10,000+ 行 / 127 个图表 / 170+ 个表格的验证结果

适用场景：生成将要导入飞书的 Markdown 文档时，参考本规范确保兼容性。

---

2. TL;DR 速查清单#

生成飞书 Markdown 前，快速过一遍这 10 条核心规则：

#规则严重度1❌ Mermaid flowchart 标签禁止 {}（会被解析为菱形节点）必须遵守2❌ Mermaid 禁止 par...and...end（飞书完全不支持）必须遵守3❌ Mermaid 节点标签换行禁止 \n（会原样显示），用 <br/>必须遵守4⚠️ Mermaid sequenceDiagram：participant ≤ 8，alt 嵌套 ≤ 1 层强烈建议5✅ 方括号标签含冒号时加双引号： ["类型: string"]必须遵守6❌ PlantUML 禁止行首缩进、 skinparam、可见性标记（ + - # ~）必须遵守7⚠️ 表格超过 9 行或 9 列会自动拆分，无需手动处理了解即可8✅ Callout 仅 6 种：NOTE / WARNING / TIP / CAUTION / IMPORTANT / SUCCESS必须遵守9⚠️ 块级公式 $$...$$ 会降级为行内 Equation（API 限制）了解即可10✅ 图片默认自动上传，失败时降级为占位块了解即可

---

3. Mermaid 飞书语法规范#

这是最重要的章节。Mermaid 图表导入飞书有严格的语法限制，不遵守会导致渲染失败。

支持的 8 种图表类型#

类型声明飞书 diagram_type说明流程图flowchart TD / flowchart LR6 (flowchart)支持 subgraph时序图sequenceDiagram2 (sequence)复杂度限制最严格类图classDiagram4 (class)状态图stateDiagram-v27 (state)必须用 v2ER 图erDiagram5 (er)甘特图gantt0 (auto)饼图pie0 (auto)思维导图mindmap1 (mindmap)

7 条强制性规则#

规则 1：❌ 禁止在标签中使用花括号 {}

花括号会被 Mermaid 解析器识别为菱形（decision）节点，导致语法错误。此规则针对 flowchart 节点标签，erDiagram/classDiagram 语法结构中的 {} 不受此限制。

markdown

❌ 错误
flowchart TD
    A["{name: value}"]

✅ 正确
flowchart TD
    A["name: value"]

替代方案：移除花括号，或用圆括号/方括号替代。

规则 2：❌ 禁止使用 par...and...end 并行语法

飞书画板完全不支持 par 语法（错误码 2891001）。

markdown

❌ 错误
sequenceDiagram
    par
        A->>B: 请求1
    and
        A->>C: 请求2
    end

✅ 正确：用 Note 替代
sequenceDiagram
    Note over A,C: 并行处理
    A->>B: 请求1
    A->>C: 请求2

规则 3：⚠️ 方括号中避免冒号

方括号 [text:xxx] 中的冒号可能导致解析歧义。

markdown

❌ 可能出错
flowchart TD
    A[类型:string]

✅ 正确
flowchart TD
    A["类型: string"]

修复方法：给含冒号的标签加双引号。

规则 4：⚠️ Note 作用域限制

Note over 最多跨 2 个相邻 participant。

markdown

❌ 错误：跨太多参与者
sequenceDiagram
    Note over A,D: 说明

✅ 正确
sequenceDiagram
    Note over A,B: 说明

规则 5：⚠️ sequenceDiagram 复杂度阈值

维度安全阈值超限风险participant 数量≤ 8超过 10 + 其他因素 → 失败alt/opt 嵌套≤ 1 层超过 2 层 → 失败风险增大消息标签长度简短（≤ 30 字符）长标签 + 多参与者 → 失败总消息数≤ 30需结合其他因素评估

超限组合（实测必定失败）：10+ participant + 2+ alt + 30+ 长消息标签

建议：超过安全阈值时，拆分为多个小图。

规则 6：❌ 节点标签换行禁止 \n，必须用 <br> 或 <br/>

飞书画板不支持 Mermaid 节点标签中的 \n 转义符，会原样显示为 \n 文本。需要使用 <br> 或 <br/> 实现换行，也可以在源码中写真实换行（需用双引号包裹标签）。

markdown

❌ 错误：\n 会原样显示为文本
flowchart TD
    A["normalizePort\n(detect-port)"]

✅ 正确：使用 <br>
flowchart TD
    A["normalizePort<br>(detect-port)"]

✅ 正确：使用 <br/>
flowchart TD
    A["normalizePort<br/>(detect-port)"]

✅ 正确：源码中直接换行（标签必须用双引号）
flowchart TD
    A["normalizePort
(detect-port)"]

规则 7：⚠️ 避免过于复杂的嵌套结构

多层 subgraph 嵌套、大量条件分支等复杂结构会增加渲染失败概率。保持图表简洁。

生成前检查清单#

在生成 Mermaid 代码块前，逐项检查：

• 图表类型是否在支持的 8 种之内？
• 标签中是否存在花括号 {}？→ 移除或替换
• 是否使用了 par...and...end？→ 改用 Note over
• 方括号标签中是否有冒号？→ 加双引号
• sequenceDiagram 参与者是否 ≤ 8？
• sequenceDiagram alt 嵌套是否 ≤ 1 层？
• 节点标签换行是否使用了 \n？→ 改用 <br> 或 <br/>
• 整体复杂度是否可控？→ 考虑拆分

详细的 8 种图表模板和更多正反示例见 references/mermaid-spec.md。

---

4. PlantUML 安全子集#

全局规则#

1. ✅ 使用 @startuml / @enduml 包裹（思维导图用 @startmindmap / @endmindmap）
2. ❌ 不要使用行首缩进（飞书画板将缩进行视为独立行）
3. ❌ 避免 skinparam、 !define、颜色、字体、对齐控制等样式指令
4. ⚠️ 避免方向控制指令（ left to right direction 等在部分场景不可靠）

各图类型注意事项#

图类型安全语法禁忌活动图start/stop、 :动作;、 if/then/else/endif、 repeat、 fork❌ 避免过深嵌套时序图participant、 ->/ -->、 activate/deactivate、 note、 alt/opt/loop❌ 避免样式指令类图class、 interface、 package、关系箭头❌ **避免可见性标记（+ - # ~）**用例图actor、 (用例)、 <<include>>/ <<extend>>❌ 避免复杂布局组件图[Component]、 package/node/cloud/database❌ 避免 ArchiMate spriteER 图entity、关系箭头⚠️ 与 Mermaid ER 语法不同思维导图@startmindmap、 * / + 层级标记✅ 必须用专用包裹标记

Mermaid vs PlantUML 选择策略#

场景推荐原因流程图Mermaid飞书原生支持更好，成功率高时序图（简单）Mermaid语法简洁时序图（复杂）PlantUMLMermaid 复杂度限制严格类图Mermaid两者都可，Mermaid 更简洁ER 图Mermaid语法更直观状态图MermaidstateDiagram-v2 支持好甘特图MermaidPlantUML 甘特图飞书支持差饼图Mermaid简洁思维导图两者均可PlantUML 层级标记更灵活用例图PlantUMLMermaid 不支持组件图PlantUMLMermaid 不支持活动图（复杂分支）PlantUML支持更丰富的分支语法

默认推荐 Mermaid，仅在 Mermaid 不支持的图类型或复杂场景下使用 PlantUML。

---

5. Markdown 语法全量参考#

支持的语法与 Block 类型映射#

Markdown 语法Block Type飞书块名称说明# 标题 ~ ###### 标题3-8Heading1-6最多 6 级（7-9 级导出降级为粗体段落）普通段落2Text纯文本- 无序列表12Bullet支持无限深度嵌套1. 有序列表13Ordered支持无限深度嵌套- [x] / - [ ]17Todo任务列表 ```lang14Code代码块（支持语言标识）> 引用34QuoteContainer引用容器（导入使用 QuoteContainer）> [!NOTE]19Callout高亮块（6 种类型，见第 6 节）---22Divider分割线Markdown 表格31Table超过 9 行或 9 列自动拆分（见第 7 节）![alt](url)27Image默认自动上传（见第 8 节） ```mermaid21→43Diagram→Board自动转飞书画板（见第 3 节） ```plantuml / ```puml21→43Diagram→Board自动转飞书画板（见第 4 节）$$公式$$16Equation块级公式（降级为行内 Equation）$公式$—InlineEquation行内公式

新增块类型（导出支持）#

以下块类型在导出时有对应的处理：

Block Type名称导出结果说明44Agenda展开子块议程块45AgendaItem展开子块议程条目46AgendaItemTitle粗体文本议程标题47AgendaItemContent展开子块议程内容48LinkPreview链接链接预览块49SyncSource展开子块同步源块50SyncReference展开子块同步引用块51WikiCatalogV2[知识库目录 V2]知识库目录 V252AITemplateHTML 注释AI 模板块

行内样式#

Markdown效果说明**粗体**粗体Bold TextStyle*斜体*_斜体_Italic TextStyle`` 行内代码 ```代码InlineCode TextStyle删除线删除线Strikethrough TextStyle下划线下划线Underline TextStyle文字链接Link TextElement==高亮==`高亮Highlight（需启用选项）

嵌套列表示例#

markdown

- 一级无序
  - 二级无序
    - 三级无序
      1. 四级有序
      2. 四级有序
    - 三级无序
  - 二级无序

无序/有序列表支持 无限深度嵌套 和 混合嵌套，导入时自动保留缩进层级。

---

6. Callout 高亮块#

6 种类型与背景色映射#

类型bgColor颜色Markdown 语法适用场景NOTE6蓝色> [!NOTE]补充说明、提示信息WARNING2红色> [!WARNING]警告、危险提醒TIP4黄色> [!TIP]技巧、建议CAUTION3橙色> [!CAUTION]注意事项IMPORTANT7紫色> [!IMPORTANT]重要信息SUCCESS5绿色> [!SUCCESS]成功、通过

⚠️ INFO 与 NOTE 等效（都映射为 bgColor=6 蓝色），统一使用 NOTE。

使用示例#

markdown

> [!NOTE]
> 这是一条补充说明信息。

> [!WARNING]
> 此操作不可逆，请谨慎执行。

> [!TIP]
> 使用 `--verbose` 参数可以查看详细进度。

> [!CAUTION]
> 注意：API 有频率限制。

> [!IMPORTANT]
> 必须在执行前配置环境变量。

> [!SUCCESS]
> 所有测试用例已通过。

注意事项#

• ❌ Callout 块不能同时设置 EmojiId，仅通过 BackgroundColor 区分类型
• ✅ 支持 Callout 内包含子块（段落、列表等）
• ✅ 统一使用 NOTE 而非 INFO（两者等效， NOTE 是 Markdown 标准写法）

---

7. 表格规范#

9 行 × 9 列限制与自动拆分#

飞书 API 限制单个表格最多 9 行（包括表头）× 9 列。超出时 feishu-cli 自动拆分为多个表格。

拆分逻辑（ converter/markdown_to_block.go）：

维度处理方式≤ 9 行 且 ≤ 9 列✅ 直接创建单个表格> 9 行按行拆分为多个表格，每个最多 8 行数据 + 1 行表头> 9 列按列拆分为多个表格，保留首列作为标识列> 9 行 且 > 9 列先列拆分，再行拆分（复合拆分）

列拆分策略：首列通常是标识/名称列，在所有列组中保留，避免拆分后数据行无法识别。每个列组最多 9 列（1 列标识 + 8 列数据）。

列宽自动计算#

列宽根据单元格内容自动计算（ converter/markdown_to_block.go:25-103）：

参数值说明中文字符宽度14px非 ASCII 字符英文字符宽度8pxASCII 字符列内边距16px每列额外边距最小列宽80px不能更窄最大列宽400px不能更宽文档默认宽度700px总宽度不足时按比例扩展

单元格多块支持#

表格单元格内可以包含多种块类型：

• Text（普通文本）
• Bullet（无序列表）
• Heading（标题）

⚠️ 注意：飞书 API 创建表格时会自动在每个单元格内创建空的 Text 块。填充内容时应 更新现有块 而非创建新块。

表格编写建议#

markdown

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 数据 | 数据 | 数据 |

• ✅ 确保每行列数一致
• ✅ 大表格（超过 8 行数据或超过 9 列）会自动拆分，无需手动处理
• ✅ 列宽由内容自动决定，无需手动控制

---

8. 图片处理#

图片上传（v1.8.0+）#

feishu-cli 默认通过 --upload-images 自动上传图片：

1. 遇到 ![alt](url) 时，自动下载网络图片或读取本地图片
2. 通过素材上传 API 上传到飞书，获取 file_token
3. 创建 Image 块并引用 file_token，实现图片插入
4. 上传失败时降级为占位块，导入报告显示失败数量

注意事项#

• ✅ 默认开启图片上传，使用 --no-upload-images 可关闭（创建占位块）
• ⚠️ 图片并发上传数通过 --image-workers 控制（默认 2，API 限制 5 QPS）
• ✅ 支持本地图片路径和网络 URL（HTTP/HTTPS）
• ✅ 图片相关的 alt 文字会作为占位信息保留

---

9. 公式支持#

行内公式#

使用单美元符号包裹： $E = mc^2$

支持一个段落内包含多个行内公式：

markdown

已知 $a^2 + b^2 = c^2$，当 $a = 3, b = 4$ 时，$c = 5$。

块级公式#

使用双美元符号包裹：

markdown

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

注意事项#

• ⚠️ 飞书 API 不支持直接创建块级 Equation（BlockType=16），实际导入时 降级为行内 Equation
• ✅ LaTeX 语法兼容飞书 KaTeX 渲染器
• ✅ 公式中的特殊字符无需额外转义

---

10. API 限制与容错#

三阶段并发管道#

feishu-cli doc import 采用三阶段管道架构（ cmd/import_markdown.go）：

阶段方式处理内容阶段一顺序按文档顺序创建所有块，为图表创建空画板占位块，收集表格任务阶段二并发图表 worker 池（默认 5 并发）+ 表格 worker 池（默认 3 并发）同时处理阶段三逆序处理失败的图表：删除空画板块，在原位置插入代码块（逆序避免索引偏移）

批量操作限制#

限制值处理方式单次创建块数最多 50 个自动分批（ batchSize = 50）单个表格行数最多 9 行自动拆分并复制表头单个表格列数最多 9 列自动拆分并保留首列文件夹子节点不超过 1500超出报错 1062507文档块总数有上限超出报错 1770004文件大小最大 100MB超出直接报错API 频率429 Too Many Requests自动重试 + 线性退避

图表重试与降级策略#

错误类型判断条件处理方式语法错误Parse error、 Invalid request parameter❌ 不重试，直接降级为代码块服务端错误500/502/503、 internal error✅ 重试（最多 10 次，1s 间隔）频率限制429、 rate limit、 frequency limit✅ 重试（归为可重试错误）重试耗尽超过最大重试次数⚠️ 降级为代码块

降级处理流程：

1. 获取文档所有顶层子块
2. 按索引 逆序 处理失败图表（避免删除导致索引偏移）
3. 删除空画板块
4. 在原位置插入代码块（保留原始图表代码）

CLI 并发控制参数#

参数默认值说明--diagram-workers5图表（Mermaid/PlantUML）并发导入数--table-workers3表格并发填充数--diagram-retries10图表最大重试次数--verbosefalse显示详细进度

画板 API 技术细节#

• API 端点： /open-apis/board/v1/whiteboards/{id}/nodes/plantuml
• syntax_type：1 = PlantUML，2 = Mermaid
• diagram_type 映射：0=auto, 1=mindmap, 2=sequence, 3=activity, 4=class, 5=er, 6=flowchart, 7=state, 8=component

---

11. 完整预创建检查清单#

创建将导入飞书的 Markdown 文档前，完成以下检查：

文档结构#

• 标题层级不超过 6 级（H7-H9 会降级为粗体段落）
• 嵌套列表使用 2 或 4 空格缩进
• 表格数据行控制在 8 行以内（避免不必要拆分）
• 文件总大小不超过 100MB

Mermaid 图表#

• 图表类型在支持的 8 种之内
• ❌ 标签无花括号 {}
• ❌ 未使用 par...and...end
• ✅ 方括号标签内含冒号时已加双引号
• ⚠️ sequenceDiagram：participant ≤ 8，alt ≤ 1 层
• ❌ 节点标签换行未使用 \n，已改用 <br> 或 <br/>
• 复杂图表已拆分为多个小图

PlantUML 图表#

• ✅ 使用正确的包裹标记（ @startuml/ @enduml）
• ❌ 无行首缩进
• ❌ 无 skinparam 等样式指令
• ❌ 类图未使用可见性标记（ + - # ~）

特殊内容#

• ✅ 图片路径正确（默认自动上传，失败降级为占位块）
• ✅ 公式语法正确（ $...$ 行内 / $$...$$ 块级）
• ✅ Callout 类型在 6 种之内（NOTE/WARNING/TIP/CAUTION/IMPORTANT/SUCCESS）

性能考虑#

• 大量图表时考虑增加 --diagram-workers
• 大量表格时考虑增加 --table-workers
• 首次导入建议加 --verbose 观察进度