feishu-cli-doc-guide by riba2534/feishu-cli
npx skills add https://github.com/riba2534/feishu-cli --skill feishu-cli-doc-guide本技能是 其他飞书文档技能的参考规范 ,不可直接调用。整合了以下来源的验证经验:
feishu-cli 项目代码实现(converter/、client/board.go、cmd/import_markdown.go)feishu-cli-write、feishu-cli-import、feishu-cli-plantuml 技能的实测数据适用场景 :生成将要导入飞书的 Markdown 文档时,参考本规范确保兼容性。
生成飞书 Markdown 前,快速过一遍这 10 条核心规则:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
---|---|---
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 | ✅ 图片默认自动上传,失败时降级为占位块 | 了解即可
这是最重要的章节。Mermaid 图表导入飞书有严格的语法限制,不遵守会导致渲染失败。
| 类型 | 声明 | 飞书 diagram_type | 说明 |
|---|---|---|---|
| 流程图 | flowchart TD / flowchart LR | 6 (flowchart) | 支持 subgraph |
| 时序图 | sequenceDiagram | 2 (sequence) | 复杂度限制最严格 |
| 类图 | classDiagram | 4 (class) | |
| 状态图 | stateDiagram-v2 | 7 (state) | 必须用 v2 |
| ER 图 | erDiagram | 5 (er) | |
| 甘特图 | gantt | 0 (auto) | |
| 饼图 | pie | 0 (auto) | |
| 思维导图 | mindmap | 1 (mindmap) |
{}花括号会被 Mermaid 解析器识别为菱形(decision)节点,导致语法错误。此规则针对 flowchart 节点标签,erDiagram/classDiagram 语法结构中的 {} 不受此限制。
❌ 错误
flowchart TD
A["{name: value}"]
✅ 正确
flowchart TD
A["name: value"]
替代方案 :移除花括号,或用圆括号/方括号替代。
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
方括号 [text:xxx] 中的冒号可能导致解析歧义。
❌ 可能出错
flowchart TD
A[类型:string]
✅ 正确
flowchart TD
A["类型: string"]
修复方法 :给含冒号的标签加双引号。
Note over 最多跨 2 个相邻 participant。
❌ 错误:跨太多参与者
sequenceDiagram
Note over A,D: 说明
✅ 正确
sequenceDiagram
Note over A,B: 说明
| 维度 | 安全阈值 | 超限风险 |
|---|---|---|
| participant 数量 | ≤ 8 | 超过 10 + 其他因素 → 失败 |
| alt/opt 嵌套 | ≤ 1 层 | 超过 2 层 → 失败风险增大 |
| 消息标签长度 | 简短(≤ 30 字符) | 长标签 + 多参与者 → 失败 |
| 总消息数 | ≤ 30 | 需结合其他因素评估 |
超限组合 (实测必定失败):10+ participant + 2+ alt + 30+ 长消息标签
建议 :超过安全阈值时,拆分为多个小图。
\n,必须用 <br> 或 <br/>飞书画板不支持 Mermaid 节点标签中的 \n 转义符,会原样显示为 \n 文本。需要使用 <br> 或 <br/> 实现换行,也可以在源码中写真实换行(需用双引号包裹标签)。
❌ 错误:\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)"]
多层 subgraph 嵌套、大量条件分支等复杂结构会增加渲染失败概率。保持图表简洁。
在生成 Mermaid 代码块前,逐项检查:
{}?→ 移除或替换par...and...end?→ 改用 Note over\n?→ 改用 <br> 或 <br/>详细的 8 种图表模板和更多正反示例见
references/mermaid-spec.md。
@startuml / @enduml 包裹(思维导图用 @startmindmap / @endmindmap)skinparam、!define、颜色、字体、对齐控制等样式指令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 sprite |
| ER 图 | entity、关系箭头 | ⚠️ 与 Mermaid ER 语法不同 |
| 思维导图 | @startmindmap、* / + 层级标记 | ✅ 必须用专用包裹标记 |
| 场景 | 推荐 | 原因 |
|---|---|---|
| 流程图 | Mermaid | 飞书原生支持更好,成功率高 |
| 时序图(简单) | Mermaid | 语法简洁 |
| 时序图(复杂) | PlantUML | Mermaid 复杂度限制严格 |
| 类图 | Mermaid | 两者都可,Mermaid 更简洁 |
| ER 图 | Mermaid | 语法更直观 |
| 状态图 | Mermaid | stateDiagram-v2 支持好 |
| 甘特图 | Mermaid | PlantUML 甘特图飞书支持差 |
| 饼图 | Mermaid | 简洁 |
| 思维导图 | 两者均可 | PlantUML 层级标记更灵活 |
| 用例图 | PlantUML | Mermaid 不支持 |
| 组件图 | PlantUML | Mermaid 不支持 |
| 活动图(复杂分支) | PlantUML | 支持更丰富的分支语法 |
默认推荐 Mermaid ,仅在 Mermaid 不支持的图类型或复杂场景下使用 PlantUML。
| Markdown 语法 | Block Type | 飞书块名称 | 说明 |
|---|---|---|---|
# 标题 ~ ###### 标题 | 3-8 | Heading1-6 | 最多 6 级(7-9 级导出降级为粗体段落) |
| 普通段落 | 2 | Text | 纯文本 |
- 无序列表 | 12 | Bullet | 支持无限深度嵌套 |
1. 有序列表 | 13 | Ordered | 支持无限深度嵌套 |
- [x] / - [ ] | 17 | Todo | 任务列表 |
| ````lang` | 14 | Code | 代码块(支持语言标识) |
> 引用 | 34 | QuoteContainer | 引用容器(导入使用 QuoteContainer) |
> [!NOTE] | 19 | Callout | 高亮块(6 种类型,见第 6 节) |
--- | 22 | Divider | 分割线 |
| Markdown 表格 | 31 | Table | 超过 9 行或 9 列自动拆分(见第 7 节) |
 | 27 | Image | 默认自动上传(见第 8 节) |
| ````mermaid` | 21→43 | Diagram→Board | 自动转飞书画板(见第 3 节) |
plantuml` / puml` | 21→43 | Diagram→Board | 自动转飞书画板(见第 4 节) |
$$公式$$ | 16 | Equation | 块级公式(降级为行内 Equation) |
$公式$ | — | InlineEquation | 行内公式 |
以下块类型在导出时有对应的处理:
| Block Type | 名称 | 导出结果 | 说明 |
|---|---|---|---|
| 44 | Agenda | 展开子块 | 议程块 |
| 45 | AgendaItem | 展开子块 | 议程条目 |
| 46 | AgendaItemTitle | 粗体文本 | 议程标题 |
| 47 | AgendaItemContent | 展开子块 | 议程内容 |
| 48 | LinkPreview | 链接 | 链接预览块 |
| 49 | SyncSource | 展开子块 | 同步源块 |
| 50 | SyncReference | 展开子块 | 同步引用块 |
| 51 | WikiCatalogV2 | [知识库目录 V2] | 知识库目录 V2 |
| 52 | AITemplate | HTML 注释 | AI 模板块 |
| Markdown | 效果 | 说明 |
|---|---|---|
**粗体** | 粗体 | Bold TextStyle |
*斜体* | 斜体 | Italic TextStyle |
行内代码 | 代码 | InlineCode TextStyle |
~~删除线~~ | Strikethrough TextStyle | |
<u>下划线</u> | 下划线 | Underline TextStyle |
[文字](url) | 链接 | Link TextElement |
==高亮== | 高亮 | Highlight(需启用选项) |
- 一级无序
- 二级无序
- 三级无序
1. 四级有序
2. 四级有序
- 三级无序
- 二级无序
无序/有序列表支持 无限深度嵌套 和 混合嵌套 ,导入时自动保留缩进层级。
| 类型 | bgColor | 颜色 | Markdown 语法 | 适用场景 |
|---|---|---|---|---|
| NOTE | 6 | 蓝色 | > [!NOTE] | 补充说明、提示信息 |
| WARNING | 2 | 红色 | > [!WARNING] | 警告、危险提醒 |
| TIP | 4 | 黄色 | > [!TIP] | 技巧、建议 |
| CAUTION | 3 | 橙色 | > [!CAUTION] | 注意事项 |
| IMPORTANT | 7 | 紫色 | > [!IMPORTANT] | 重要信息 |
| SUCCESS | 5 | 绿色 | > [!SUCCESS] | 成功、通过 |
⚠️
INFO与NOTE等效(都映射为 bgColor=6 蓝色),统一使用NOTE。
> [!NOTE]
> 这是一条补充说明信息。
> [!WARNING]
> 此操作不可逆,请谨慎执行。
> [!TIP]
> 使用 `--verbose` 参数可以查看详细进度。
> [!CAUTION]
> 注意:API 有频率限制。
> [!IMPORTANT]
> 必须在执行前配置环境变量。
> [!SUCCESS]
> 所有测试用例已通过。
EmojiId,仅通过 BackgroundColor 区分类型NOTE 而非 INFO(两者等效,NOTE 是 Markdown 标准写法)飞书 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 字符 |
| 英文字符宽度 | 8px | ASCII 字符 |
| 列内边距 | 16px | 每列额外边距 |
| 最小列宽 | 80px | 不能更窄 |
| 最大列宽 | 400px | 不能更宽 |
| 文档默认宽度 | 700px | 总宽度不足时按比例扩展 |
表格单元格内可以包含多种块类型:
⚠️ 注意 :飞书 API 创建表格时会自动在每个单元格内创建空的 Text 块。填充内容时应 更新现有块 而非创建新块。
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 数据 | 数据 | 数据 |
feishu-cli 默认通过 --upload-images 自动上传图片:
 时,自动下载网络图片或读取本地图片--no-upload-images 可关闭(创建占位块)--image-workers 控制(默认 2,API 限制 5 QPS)使用单美元符号包裹:$E = mc^2$
支持一个段落内包含多个行内公式:
已知 $a^2 + b^2 = c^2$,当 $a = 3, b = 4$ 时,$c = 5$。
使用双美元符号包裹:
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$
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 | ✅ 重试(归为可重试错误) |
| 重试耗尽 | 超过最大重试次数 | ⚠️ 降级为代码块 |
降级处理流程:
| 参数 | 默认值 | 说明 |
|---|---|---|
--diagram-workers | 5 | 图表(Mermaid/PlantUML)并发导入数 |
--table-workers | 3 | 表格并发填充数 |
--diagram-retries | 10 | 图表最大重试次数 |
--verbose | false | 显示详细进度 |
/open-apis/board/v1/whiteboards/{id}/nodes/plantumlsyntax_type:1 = PlantUML,2 = Mermaiddiagram_type 映射:0=auto, 1=mindmap, 2=sequence, 3=activity, 4=class, 5=er, 6=flowchart, 7=state, 8=component创建将导入飞书的 Markdown 文档前,完成以下检查:
{}par...and...end\n,已改用 <br> 或 <br/>@startuml/@enduml)skinparam 等样式指令+ - # ~)$...$ 行内 / $$...$$ 块级)--diagram-workers--table-workers--verbose 观察进度Weekly Installs
148
Repository
GitHub Stars
428
First Seen
Feb 8, 2026
Security Audits
Installed on
claude-code120
codex67
kimi-cli63
gemini-cli63
amp63
github-copilot63
Lark Drive API 使用指南:飞书云文档、Wiki、表格 Token 处理与文件管理
37,500 周安装