飞书画板操作技能

使用 feishu-cli 操作飞书画板（白板），支持图表导入、图片下载、节点创建等功能。

功能概览

功能	命令	说明
下载图片	board image	将画板导出为图片
导入图表	board import	导入 PlantUML/Mermaid 图表
获取节点	board nodes	获取画板节点列表
创建节点	board create-notes	在画板上创建节点

下载画板图片

将飞书画板导出为 PNG 图片：

# 下载画板图片到指定文件
feishu-cli board image <whiteboard_id> output.png

# 下载到目录（使用画板 ID 作为文件名）
feishu-cli board image <whiteboard_id> ./images/

# JSON 格式输出
feishu-cli board image <whiteboard_id> board.png -o json

导入图表到画板

将 PlantUML 或 Mermaid 图表导入到飞书画板：

# 从文件导入 PlantUML 图表
feishu-cli board import <whiteboard_id> diagram.puml

# 导入 Mermaid 图表
feishu-cli board import <whiteboard_id> diagram.mmd --syntax mermaid

# 直接导入图表代码
feishu-cli board import <whiteboard_id> "@startuml\nA -> B: hello\n@enduml" --source-type content

# 指定图表类型（自动检测失败时使用）
feishu-cli board import <whiteboard_id> diagram.puml --diagram-type sequence

# 使用经典样式
feishu-cli board import <whiteboard_id> diagram.puml --style classic

图表类型

类型	说明
auto	自动检测（默认）
mindmap	思维导图
sequence	时序图
activity	活动图
class	类图
er	ER 图
flowchart	流程图
state	状态图
component	组件图

已验证的 Mermaid 图表类型（8 种）

以下 8 种 Mermaid 图表类型已全部实测通过，可在飞书画板中正常渲染：

Mermaid 声明	diagram_type	说明
flowchart TD / flowchart LR	flowchart	流程图，支持 subgraph
sequenceDiagram	sequence	时序图，参与者建议 ≤ 8
classDiagram	class	类图
stateDiagram-v2	auto	状态图，必须用 v2
erDiagram	er	ER 图
gantt	auto	甘特图
pie	auto	饼图
mindmap	mindmap	思维导图

样式类型

样式	说明
board	画板风格（默认）
classic	经典风格

创建画板节点

在飞书画板上创建便签等节点：

# 从文件创建节点
feishu-cli board create-notes <whiteboard_id> nodes.json

# 直接传入 JSON
feishu-cli board create-notes <whiteboard_id> '[{"type":"sticky_note","x":100,"y":100,"content":"便签内容"}]' --source-type content

# 使用幂等 token
feishu-cli board create-notes <whiteboard_id> nodes.json --client-token abc123

节点 JSON 格式

[
  {
    "type": "sticky_note",
    "x": 100,
    "y": 100,
    "content": "便签内容",
    "width": 200,
    "height": 150
  }
]

支持的节点类型：

• sticky_note - 便签
• text - 文本
• shape - 形状
• line - 线条
• image - 图片

在文档中添加画板

向飞书文档添加画板块：

# 在文档末尾添加画板
feishu-cli doc add-board <document_id>

# 在指定位置添加画板
feishu-cli doc add-board <document_id> --parent-id <block_id> --index 0

# JSON 格式输出
feishu-cli doc add-board <document_id> -o json

添加成功后返回：

• block_id - 画板块 ID
• whiteboard_id - 画板 ID（可用于后续操作）

权限要求

• board:board - 画板读写权限
• docx:document - 文档操作权限（用于 add-board）

获取画板节点

查看画板中的所有节点信息：

# 获取画板节点列表（JSON 格式）
feishu-cli board nodes <whiteboard_id>

最佳实践

1. 图表导入流程：

   • 先用 doc add-board 在文档中创建画板块
   • 获取返回的 whiteboard_id
   • 使用 board import 导入图表到该画板

2. Mermaid 图表：推荐使用 Mermaid 语法，8 种图表类型全部已验证

3. PlantUML 图表：支持时序图、活动图、类图、用例图、组件图、ER 图、思维导图等

4. 导入后查看：使用 board nodes 查看画板中导入的节点数据结构

示例

# 完整流程：在文档中添加画板并导入 Mermaid 图表
# 1. 添加画板到文档
feishu-cli doc add-board DOC_ID -o json
# 返回: {"whiteboard_id": "wb_xxx", "block_id": "blk_xxx"}

# 2. 导入 Mermaid 图表到画板
feishu-cli board import wb_xxx diagram.mmd --syntax mermaid

# 3. 查看画板节点
feishu-cli board nodes wb_xxx

# 4. 下载画板图片
feishu-cli board image wb_xxx output.png