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。

```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

```markdown
> [!NOTE]
> 普通提示

> [!WARNING]
> 风险提示
```

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

## 图片与文件

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

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

## 扩展标签

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

```html
<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，避免文档导入耗时过长。


# Mermaid 飞书画板语法规范

本文档是飞书画板 Mermaid 渲染的完整规范，包含 8 种图表类型的正确模板、飞书特有限制、常见错误修复方法和复杂度安全阈值。

---

## 1. 通用规则

### 强制性约束

| 规则 | 说明 | 违反后果 |
|------|------|---------|
| 禁止花括号 `{}` | flowchart 节点标签中的 `{}` 被识别为菱形节点（erDiagram/classDiagram 语法结构不受此限制） | Parse error，降级为代码块 |
| 禁止 `par...and...end` | 飞书画板不支持并行语法 | 错误码 2891001 |
| 方括号冒号加引号 | `[text:xxx]` 中冒号导致解析歧义 | 可能 Parse error |
| Note 跨度 ≤ 2 | `Note over` 最多跨 2 个相邻 participant | 渲染错误 |
| 避免过深嵌套 | 多层 subgraph/alt 嵌套增加失败率 | 服务端超时或错误 |

### 画板 API 映射

- API 端点：`/open-apis/board/v1/whiteboards/{id}/nodes/plantuml`
- `syntax_type = 2`（Mermaid）
- `diagram_type`：根据图表类型自动映射（`0` auto 适用于大多数场景）

---

## 2. 图表类型详解

### 2.1 flowchart（流程图）

**diagram_type**: 6 (flowchart)

#### 正确模板

```mermaid
flowchart TD
    A[开始] --> B[步骤一]
    B --> C{条件判断}
    C -->|是| D[处理A]
    C -->|否| E[处理B]
    D --> F[结束]
    E --> F
```

#### 带 subgraph 模板

```mermaid
flowchart LR
    subgraph 前端
        A[用户界面] --> B[API 调用]
    end
    subgraph 后端
        C[接口层] --> D[业务逻辑]
        D --> E[数据库]
    end
    B --> C
```

#### 支持的方向

| 声明 | 方向 |
|------|------|
| `flowchart TD` / `flowchart TB` | 上到下 |
| `flowchart BT` | 下到上 |
| `flowchart LR` | 左到右 |
| `flowchart RL` | 右到左 |

#### 支持的节点形