feishu-cli-doc-guide

SKILL.md

飞书 Markdown 兼容指南

生成将导入飞书的 Markdown 前，按本指南检查。执行导入用 feishu-cli-import，编辑已有文档用 feishu-cli-write。

快速检查

内容
必检项

Mermaid
禁花括号标签、禁 par...and...end、sequenceDiagram participant ≤ 8

PlantUML
无行首缩进、无 skinparam/!define、类图不写 + - # ~ 可见性

表格
行 > 9 可导入同一 block；列 > 9 会拆列组；超大表建议 Sheet

图片
doc import 默认上传；doc add/content-update 需传 --upload-images

公式
行内 $...$；块级公式会以 Text+Equation 元素导入

Callout
仅 NOTE/WARNING/TIP/CAUTION/IMPORTANT/SUCCESS

Mermaid

推荐 Mermaid；飞书服务端支持 8 类常见图。

类型
声明
导入策略

流程图
flowchart TD / flowchart LR
doc import 自动；board import --diagram-type flowchart

时序图
sequenceDiagram
doc import 自动；复杂图建议拆分

类图
classDiagram
board import --diagram-type class

状态图
stateDiagram-v2
doc import auto；board import --diagram-type state

ER 图
erDiagram
board import --diagram-type er

甘特图
gantt
auto

饼图
pie
auto

思维导图
mindmap
board import --diagram-type mindmap

强制规则：

Flowchart 标签不要写 {}。A{判断} 可以表达菱形，但标签文本里不要包含花括号。

sequenceDiagram 不用 par...and...end，改成 Note over A,B: 并行执行。

sequenceDiagram 参与者建议 ≤ 8，alt/opt/loop 不要嵌套太深。

长标签换短句，避免 30+ 长消息叠加复杂结构。

状态图必须用 stateDiagram-v2。

更多细节见 references/mermaid-spec.md。

PlantUML

仅在 Mermaid 不覆盖的图类型使用 PlantUML。

@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi
@enduml

规则：

必须有 @startuml / @enduml。

不要使用行首缩进。

避免 skinparam、宏、颜色、字体、方向控制。

类图成员写 field : type、method()，不要写 +field、-method()。

表格

普通 Markdown 表格可以导入 docx：

行数 > 9：CLI 用 insert_table_row 追加到同一个 table block。

列数 > 9：按列组拆分，保留首列用于识别行。

数据表、长表和需要排序筛选的内容优先生成 Sheet：feishu-cli sheet import-md。

Callout

> [!NOTE]
> 普通提示

> [!WARNING]
> 风险提示

支持：NOTE、WARNING、TIP、CAUTION、IMPORTANT、SUCCESS。Callout 内可包含段落和列表。

图片与文件

![说明](./image.png)
![远程图](https://example.com/image.png)

doc import 默认上传本地和网络图片。doc add/content-update 要显式传 --upload-images。视频/文件类精确插入用 feishu-cli doc media-insert。

扩展标签

导出再导入时会出现这些标签，导入端支持 roundtrip：

<mention-user id="ou_xxx"/>
<mention-doc token="doc_token_xxx" type="docx">标题</mention-doc>
<callout type="NOTE">内容</callout>
<grid cols="2"><column>左</column><column>右</column></grid>
<sheet rows="5" cols="5"/>

手写时只使用自己确实需要的标签；普通内容优先标准 Markdown。

导入前验证

文件必须是 UTF-8，且不包含 U+FFFD 替换字符。

Mermaid/PlantUML 先按上方规则扫一遍。

图片路径要能从 Markdown 文件所在目录解析。

超大表格改 Sheet，避免文档导入耗时过长。