飞书文档创建规范指南

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 条核心规则：

3. Mermaid 飞书语法规范

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

支持的 8 种图表类型

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 复杂度阈值

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

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

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

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

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

✅ 正确：使用

flowchart TD
A[normalizePort
(detect-port)]

✅ 正确：使用

flowchart TD
A[normalizePort
(detect-port)]

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

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

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

生成前检查清单

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

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

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

4. PlantUML 安全子集

全局规则

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

各图类型注意事项