riba2534/feishu-cli-doc-guide

飞书 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 |

强制规则：

1. Flowchart 标签不要写 {}。A{判断} 可以表达菱形，但标签文本里不要包含花括号。
2. sequenceDiagram 不用 par...and...end，改成 Note over A,B: 并行执行。
3. sequenceDiagram 参与者建议 ≤ 8，alt/opt/loop 不要嵌套太深。
4. 长标签换短句，避免 30+ 长消息叠加复杂结构。
5. 状态图必须用 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。

导入前验证

1. 文件必须是 UTF-8，且不包含 U+FFFD 替换字符。
2. Mermaid/PlantUML 先按上方规则扫一遍。
3. 图片路径要能从 Markdown 文件所在目录解析。
4. 超大表格改 Sheet，避免文档导入耗时过长。