夜雨聆风机器人说用了 Mermaid 代码块，文档里却找不到图。同事一句话点醒：得用「文本绘图」组件。一文理清飞书文档 Block 类型、API 怎么调、流程图怎么落地。
这两天用飞书机器人自动写文档，踩了个很典型的坑。
我让机器人画流程图，它信誓旦旦说：已经用代码块写好了，语言是 Mermaid。
我打开文档——什么都没有。不是空白，是根本没有「图」这个概念，只有一段看起来像代码的文字，甚至有时候连代码块都不明显。
问同事，对方一句话：「得用文本绘图那个组件，不是代码块。」
这一下就对上了。很多 AI 写文档工具（包括一些机器人模板）会把「画流程图」理解成「输出 Mermaid 源码」，但飞书文档里，渲染图和展示代码，是两套完全不同的 Block（块）。
一、先搞懂：飞书文档不是 Markdown 文件
飞书新版文档（docx）底层是一棵 Block 树，不是纯文本。
- 每个段落、标题、表格、图片、流程图，都是一个 Block
- 每个 Block 有唯一 `block_id`，有 `block_type` 类型编号
- 文档根节点是 Page Block，`document_id` 就等于页面块的 ID
所以机器人说「我写了一段 Mermaid」——如果只是 `block_type: 14`（代码块），那飞书只会把它当代码文本展示，不会自动渲染成流程图。
代码块语言枚举里虽然有 Markdown（39），但没有 Mermaid 这个语言类型。就算你把 `graph TD` 塞进代码块，用户看到的仍是代码，不是图。
界面上的「文本绘图」= API 里的 Diagram Block，`block_type: 21`，关键字 `diagram`。
二、飞书文档 API 能操作的 Block 一览（52 种）
官方文档目前定义了 50+ 种 Block 类型（`block_type` 1–52，另有 999 未支持）。按功能分类如下：
文本类
- 2 文本、3–11 标题1–9、12 无序列表、13 有序列表、14 代码块、15 引用、17 待办
结构与容器
- 19 高亮块、24 分栏、25 分栏列、34 引用容器
数据类
- 18 多维表格、30 电子表格、31 表格、32 表格单元格、29 思维笔记（API 不支持创建）
媒体类
- 27 图片、23 文件、26 内嵌网页（B站/ Figma / 地图等）
绘图类（重点）
- 21 流程图 & UML 图（文本绘图） — `diagram_type: 1` 流程图，`2` UML
- 43 画板 — 自由画板，有 `token`
协作 / 嵌入
- 20 会话卡片、35 任务、36–39 OKR 系列、40 文档小组件、41 Jira、48 链接预览
其他
- 22 分割线、28 开放平台小组件、42/51 Wiki 子目录、44–47 议程系列、49–50 同步块、52 AI 模板（只读）
完整枚举见飞书开放平台：块的数据结构 · BlockType
三、文本绘图 vs 代码块：对照表
你在界面里看到的 → API 里是什么
- 普通段落 → `block_type: 2`（text）
- 代码块 → `block_type: 14`（code），只展示源码
- 文本绘图 / 流程图 → `block_type: 21`（diagram）
- 上传的图片 → `block_type: 27`（image）
- 画板 → `block_type: 43`（board）
Mermaid 正确姿势（人工编辑）
1. 输入 `/` 或点击「+」
2. 选择 文本绘图（不是代码块）
3. 在绘图编辑器里选 Mermaid / PlantUML，粘贴语法
4. 文档里出现可渲染的流程图
机器人常犯错误
把 Mermaid 写进 `block_type: 14` 的 code 块 → 用户只能看到代码字符串，看不到图。
四、Open API 怎么调用（最小闭环）
1. 准备
- 在飞书开放平台创建自建应用
- 开通权限：`docx:document`（编辑）或 `docx:document:readonly`（只读）
- 获取 `app_id` + `app_secret`，换 `tenant_access_token`
2. 获取 token
```
POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal
Body: { "app_id": "...", "app_secret": "..." }
```
3. 创建文档
```
POST /open-apis/docx/v1/documents
Header: Authorization: Bearer {token}
Body: { "title": "机器人写的文档" }
```
返回 `document_id`，即根 Page Block 的 ID。
4. 插入内容块（在根块下创建子块）
```
POST /open-apis/docx/v1/documents/{document_id}/blocks/{block_id}/children
```
示例：插入标题 + 正文
```json
{
"children": [
{
"block_type": 3,
"heading1": {
"elements": [{ "text_run": { "content": "方案流程" } }]
}
},
{
"block_type": 2,
"text": {
"elements": [{ "text_run": { "content": "第一步：用户提交请求" } }]
}
}
]
}
```
5. 批量改字
```
PATCH /open-apis/docx/v1/documents/{document_id}/blocks/batch_update
```
用 `update_text_elements` 更新已有文本块内容。
6. 插图（推荐用于流程图兜底）
先调素材上传接口拿到 `image_token`，再创建 `block_type: 27` 的图片块。
官方文档索引：文档概述 · 方法列表
五、流程图 API 的关键限制（必读）
这是最容易踩的第二个坑。
飞书 创建块 接口的参数列表里，确实出现了 `block_type: 21` 和 `diagram` 字段（含 `diagram_type`）。
但在《文档概述》的能力表里，Diagram 块标注为：
- 创建块：不支持
- 读取内容：不支持
- 编辑内容：不支持
也就是说：用 Open API 很难像人工那样，把 Mermaid 源码写进文本绘图并自动渲染。 文档概述还明确：Diagram 不能作为子块嵌套进别的块里。
机器人落地建议（按优先级）
1. 图片兜底（最稳）：本地或云端把 Mermaid 渲染成 PNG/SVG → 上传素材 → 插入图片块（27）
2. 人工补一刀：机器人建好文档骨架，流程图位置留标题「待插入流程图」，人进去用文本绘图粘贴 Mermaid
3. 画板块（43）：API 可创建，适合自由涂鸦，不适合标准 Mermaid 语法
4. 别再用代码块冒充流程图
如果后续飞书开放了 Diagram 内容写入，优先看官方 创建块 文档是否更新能力表。
六、给飞书机器人的检查清单
以后让机器人写带图的文档，可以先过这张表：
- 目标是「用户能看到的图」→ 禁止只用 code 块写 Mermaid
- 能插图就走 `block_type: 27` + 素材上传
- 文档骨架用 2/3/12/13/19（文本、标题、列表、高亮块）组合
- 表格用 31，多维表格用 18，别混用
- 调 API 前确认 `tenant_access_token` 未过期（有效期约 2 小时）
- 频率限制：创建块约 3 次/秒，批量更新注意别对同一块重复提交
- 机器人回复用户时，说清楚：「流程图已生成为图片插入」或「请手动在文本绘图组件粘贴以下 Mermaid」
我这次踩坑的教训就一句：AI 说「写进去了」，你得问清楚——写进的是哪种 Block。
写在最后
飞书文档 API 能力已经很强：标题、列表、高亮、表格、图片、文件、内嵌网页、OKR、画板……都能程序化写入。
但文本绘图（Diagram）目前仍是「界面好用、API 受限」的典型代表。做自动化文档时，要么上图，要么留位让人补，别指望代码块自动变流程图。
如果你也在用飞书机器人写技术方案、会议纪要、项目文档，建议把 `block_type` 这张表贴进机器人 Prompt——比教它背 Mermaid 语法更有用。
参考文档：
- 块的数据结构
- 创建块
- 文档概述
今日一问：你的飞书机器人，现在默认往文档里塞的是 code 块还是 image 块？
— END —
欢迎点赞、在看与留言