飞书 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 内可包含段落和列表。
图片与文件
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，避免文档导入耗时过长。
