飞书文档创建规范指南

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. Markdown 语法全量参考

支持的语法与 Block 类型映射

行内样式

嵌套列表示例

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

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

3. Mermaid 飞书语法规范

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

支持的 8 种图表类型

6 条强制性规则

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

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

<!-- ❌ 错误 -->
flowchart TD
    A["{name: value}"]

<!-- ✅ 正确 -->
flowchart TD
    A["name: value"]

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

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

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

<!-- ❌ 错误 -->
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] 中的冒号可能导致解析歧义。

<!-- ❌ 可能出错 -->
flowchart TD
    A[类型:string]

<!-- ✅ 正确 -->
flowchart TD
    A["类型: string"]

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

规则 4：Note 作用域限制

Note over 最多跨 2 个相邻 participant。

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

<!-- ✅ 正确 -->
sequenceDiagram
    Note over A,B: 说明

规则 5：sequenceDiagram 复杂度阈值

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

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

规则 6：避免过于复杂的嵌套结构

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

生成前检查清单

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

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

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

4. PlantUML 安全子集

全局规则

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

各图类型注意事项

Mermaid vs PlantUML 选择策略

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

5. Callout 高亮块

6 种类型与背景色映射

使用示例

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

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

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

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

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

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

注意事项

• Callout 块不能同时设置 EmojiId，仅通过 BackgroundColor 区分类型
• 支持 Callout 内包含子块（段落、列表等）
• INFO 和 NOTE 等效，都映射为蓝色 (bgColor=6)

6. 表格规范

9 行限制与自动拆分

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

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

列宽自动计算

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

单元格多块支持

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

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

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

表格编写建议

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

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

7. 图片处理

当前限制

飞书 DocX Open API 不支持通过 API 插入实际图片内容。feishu-cli 的处理方式：

1. 遇到 ![alt](url) 时，创建一个空的 Image 占位块（BlockType=27）
2. 导入完成后，报告中显示 跳过的图片数量
3. 用户需要在飞书文档中手动替换图片

建议

• 如果文档中有大量图片，考虑在导入后手动上传
• 可以使用 feishu-cli media upload 上传素材到飞书，获取文件 token
• 图片相关的 alt 文字会作为占位信息保留

8. 公式

行内公式

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

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

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

块级公式

使用双美元符号包裹：

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

注意事项

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

9. API 限制与容错

三阶段并发管道

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

批量操作限制

图表重试与降级策略

降级处理流程：

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

CLI 并发控制参数

画板 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

10. 最佳实践检查清单

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

文档结构

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

Mermaid 图表

• 图表类型在支持的 8 种之内
• 标签无花括号 {}
• 未使用 par...and...end
• 方括号标签内含冒号时已加双引号
• sequenceDiagram：participant ≤ 8，alt ≤ 1 层
• 复杂图表已拆分为多个小图

PlantUML 图表

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

特殊内容

• 图片已标注（导入后需手动替换）
• 公式语法正确（$...$ 行内 / $$...$$ 块级）
• Callout 类型在 6 种之内（NOTE/WARNING/TIP/CAUTION/IMPORTANT/SUCCESS）

性能考虑

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