飞书画板操作技能

前置条件

• 认证：需要有效的 App Access Token（环境变量 FEISHU_APP_ID + FEISHU_APP_SECRET，或 ~/.feishu-cli/config.yaml）
• 权限：应用需开通 board:whiteboard（画板读写）和 docx:document（文档中添加画板）
• 验证：feishu-cli auth status 确认认证状态正常

两种模式

在飞书文档中创建画板并绘制可视化图表。支持两种模式：

模式	方式	适用场景
精排绘图	board create-notes — JSON 描述节点坐标、颜色、连线	架构图、看板、自定义布局
图表导入	board import — Mermaid/PlantUML 代码自动渲染	标准流程图、时序图等 8 种图表

何时使用哪种方式

需求	推荐方式	说明
精确控制节点位置、颜色、坐标	board create-notes（本技能）	完全自定义布局，适合架构图、看板
从 Mermaid/PlantUML 代码快速生成图	board import 或 doc import	服务端自动排版，无需手动计算坐标
在文档中内嵌简单图表	feishu-cli-write / feishu-cli-import 的 Mermaid 支持	Markdown 中写 Mermaid 代码块，导入时自动转画板

简单判断：如果你只需要"画个流程图"且不关心精确坐标，优先用 Mermaid；如果需要"精排"或"自定义配色布局"，用 create-notes。

精排绘图工作流（create-notes）

这是画板的核心能力，通过 JSON 精确控制每个节点的位置、大小、颜色和连线。

标准四步流程

# 1. 创建文档（或使用已有文档）
feishu-cli doc create --title "架构图" -o json
# → document_id

# 2. 在文档中添加画板
feishu-cli doc add-board <document_id> -o json
# → whiteboard_id

# 3. 创建节点（先形状，再连接线）
feishu-cli board create-notes <whiteboard_id> shapes.json -o json
# → node_ids（用于连接线引用）
feishu-cli board create-notes <whiteboard_id> connectors.json -o json

# 4. 截图验证
feishu-cli board image <whiteboard_id> output.png

关键原则：先创建所有形状节点获取 ID，再创建连接线引用这些 ID。

最小示例：2 个节点 + 1 条连线

在深入 JSON 格式细节之前，先看一个最小的完整示例——两个矩形节点通过一条箭头连接：

# shapes.json — 两个形状节点
cat > /tmp/minimal_shapes.json << 'EOF'
[
  {"type":"composite_shape","x":100,"y":100,"width":160,"height":40,
   "composite_shape":{"type":"round_rect"},
   "text":{"text":"服务 A","font_size":14,"font_weight":"regular","horizontal_align":"center","vertical_align":"mid"},
   "style":{"fill_color":"#3399ff","fill_opacity":100,"border_style":"none"},
   "z_index":10},
  {"type":"composite_shape","x":400,"y":100,"width":160,"height":40,
   "composite_shape":{"type":"round_rect"},
   "text":{"text":"服务 B","font_size":14,"font_weight":"regular","horizontal_align":"center","vertical_align":"mid"},
   "style":{"fill_color":"#509863","fill_opacity":100,"border_style":"none"},
   "z_index":10}
]
EOF
feishu-cli board create-notes $BOARD_ID /tmp/minimal_shapes.json -o json
# → 返回 node_ids: ["o1:1", "o1:2"]

# connector.json — 一条从服务 A 指向服务 B 的连线
cat > /tmp/minimal_connector.json << 'EOF'
[
  {"type":"connector","width":1,"height":1,"z_index":50,
   "connector":{"shape":"polyline",
     "start":{"arrow_style":"none","attached_object":{"id":"o1:1","position":{"x":1,"y":0.5},"snap_to":"right"}},
     "end":{"arrow_style":"triangle_arrow","attached_object":{"id":"o1:2","position":{"x":0,"y":0.5},"snap_to":"left"}}},
   "style":{"border_color":"#646a73","border_opacity":100,"border_style":"solid","border_width":"narrow"}}
]
EOF
feishu-cli board create-notes $BOARD_ID /tmp/minimal_connector.json -o json

这就是 create-notes 的基本模式：形状定义位置和样式 → 连接线通过 ID 引用形状。下面是各字段的详细说明。

节点 JSON 格式

形状节点（composite_shape）

最常用的节点类型，支持矩形、圆角矩形等：

{
  "type": "composite_shape",
  "x": 100, "y": 100, "width": 200, "height": 50,
  "composite_shape": {"type": "round_rect"},
  "text": {
    "text": "节点文本",
    "font_size": 14,
    "font_weight": "regular",
    "horizontal_align": "center",
    "vertical_align": "mid"
  },
  "style": {
    "fill_color": "#8569cb",
    "fill_opacity": 100,
    "border_style": "none"
  },
  "z_index": 10
}

注意：多余字段会导致 2890002 invalid arg 错误，保持最小格式。

连接线（connector）

连接两个已创建的形状节点：

{
  "type": "connector",
  "width": 1, "height": 1, "z_index": 50,
  "connector": {
    "shape": "polyline",
    "start": {
      "arrow_style": "none",
      "attached_object": {
        "id": "<source_node_id>",
        "position": {"x": 1, "y": 0.5},
        "snap_to": "right"
      }
    },
    "end": {
      "arrow_style": "triangle_arrow",
      "attached_object": {
        "id": "<target_node_id>",
        "position": {"x": 0, "y": 0.5},
        "snap_to": "left"
      }
    }
  },
  "style": {
    "border_color": "#646a73",
    "border_opacity": 100,
    "border_style": "solid",
    "border_width": "narrow"
  }
}

连接方向速查

方向	start position	start snap_to	end position	end snap_to
→ 左到右	{x:1, y:0.5}	right	{x:0, y:0.5}	left
↓ 上到下	{x:0.5, y:1}	bottom	{x:0.5, y:0}	top
← 右到左	{x:0, y:0.5}	left	{x:1, y:0.5}	right
↑ 下到上	{x:0.5, y:0}	top	{x:0.5, y:1}	bottom

position 是归一化坐标（0-1），表示节点边缘上的连接点位置。一个节点连多条线时，调整 position 避免重叠（如扇出：x:0.25、x:0.5、x:0.75）。

配色方案

为不同实体类型使用不同颜色，让图表一目了然：

用途	填充色	边框色	适用对象
强调/标题	#8569cb	—	核心服务、标题栏
紫色辅助	#eae2fe	#8569cb	API、中间层
绿色正向	#509863	—	成功、输出、完成
绿色辅助	#d5e8d4	#509863	处理步骤
蓝色服务	#3399ff	—	主服务、入口
蓝色辅助	#cce5ff	#3399ff	子服务、组件
橙色并发	#ffc285	—	并发处理、Worker
橙色辅助	#fff0e3	#ffc285	并发子任务
红色告警	#ef4444	—	错误、降级、告警
红色辅助	#ffe0e0	#ef4444	容错处理
灰色输入	#f5f5f5	#616161	用户、外部输入
连接线	—	#646a73	普通连线

z_index 与透明度规则

z_index	用途	fill_opacity
0-1	背景色带（分区底色）	≤25%
2-3	次级区域	≤60%
10	常规形状节点	100%
50	连接线	border_opacity=100

背景色带 fill_opacity 必须 ≤60%，否则遮挡上层节点。

布局设计建议

绘制复杂图表时的布局规划方法：

1. 确定画布尺寸 — 宽 800px 左右，高度按行数估算（每行 ~80px 间距）
2. 按行分区 — 标题行、输入行、处理行、输出行，每行 y 坐标递增
3. 对齐网格 — 同层节点 y 坐标相同，节点间 x 间距 ≥30px
4. 背景色带 — 用低透明度矩形作为分区视觉标记（z_index=0）
5. 先画再连 — 所有形状一个批次创建，拿到 ID 后再创建连接线

传参方式

# 从 JSON 文件（推荐，复杂图表）
feishu-cli board create-notes <whiteboard_id> nodes.json -o json

# 内联 JSON（简单场景）
feishu-cli board create-notes <whiteboard_id> '<json_array>' --source-type content -o json

Mermaid / PlantUML 图表导入

将 Mermaid 或 PlantUML 代码自动渲染为飞书画板（服务端排版）：

# 从内容导入 Mermaid
feishu-cli board import <whiteboard_id> \
  --source-type content \
  -c "graph TD; A-->B-->C" \
  --syntax mermaid

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

# 指定图表类型（通常 auto 即可）
feishu-cli board import <whiteboard_id> diagram.mmd --syntax mermaid --diagram-type 6

支持的 Mermaid 类型（8 种，全部验证通过）

类型	声明	diagram-type
流程图	flowchart TD	6
时序图	sequenceDiagram	2
类图	classDiagram	4
状态图	stateDiagram-v2	0 (auto)
ER 图	erDiagram	5
甘特图	gantt	0 (auto)
饼图	pie	0 (auto)
思维导图	mindmap	1

Mermaid 限制

• 禁止花括号 {text}（被识别为菱形节点）
• 禁止 par...and...end（飞书不支持）
• 参与者建议 ≤8（过多会渲染失败）
• 复杂图表失败时会降级为代码块

其他画板命令

# 下载画板为 PNG 图片
feishu-cli board image <whiteboard_id> output.png

# 获取画板所有节点（JSON）
feishu-cli board nodes <whiteboard_id>

# 在文档中添加空画板
feishu-cli doc add-board <document_id> -o json

复制/修改画板（Redraw 模式）

画板 API 不支持修改或删除已有节点，修改需要重建：

1. board nodes 导出原始节点
2. 清洗数据 — 移除只读字段（id、locked、children、text_color_type、fill_color_type、border_color_type、start_object/end_object）
3. 分离形状和连接线
4. 新画板中先创建形状 → 映射旧 ID 到新 ID → 再创建连接线

详细的清洗字段列表和 Redraw 流程见 references/node-api.md。

权限要求

权限	说明
board:whiteboard	画板读写
docx:document	文档中添加画板

错误排障

错误码速查

错误码	含义	常见原因
2890001	invalid format	JSON 格式错误
2890002	invalid arg	包含未公开字段（如 sticky_note 类型）或格式不对
2890003	record missing	whiteboard_id 不存在
2890006	rate limited	超过 50 req/s

排障指引

2890002 invalid arg（最常见）：

JSON 中包含了 API 不支持的字段。只使用以下安全字段：

• composite_shape 节点：type, x, y, width, height, composite_shape, text, style, z_index
• connector 节点：type, width, height, z_index, connector, style
• text 对象：text, font_size, font_weight, horizontal_align, vertical_align
• style 对象：fill_color, fill_opacity, border_style, border_color, border_width, border_opacity

排查步骤：逐步删减 JSON 字段，定位导致错误的多余字段。常见陷阱包括 id、locked、children、text_color_type 等只读字段。

画板创建失败：

• 检查应用是否已开通 board:whiteboard 权限
• 确认 whiteboard_id 来自 doc add-board 的返回值，而非 document_id
• 运行 feishu-cli auth status 确认 Token 有效

Mermaid 导入降级为代码块：

• 飞书服务端解析失败时会自动降级，属于预期行为
• 使用 --verbose 查看具体的服务端错误信息
• 常见原因：花括号 {text}、par...and...end 语法、参与者过多（>8）
• 解决方案：简化图表语法，或拆分为多个小图表

完整示例：绘制简单架构图

# 1. 创建文档和画板
DOC_ID=$(feishu-cli doc create --title "架构图" -o json | python3 -c "import sys,json;print(json.load(sys.stdin)['document_id'])")
BOARD_ID=$(feishu-cli doc add-board $DOC_ID -o json | python3 -c "import sys,json;print(json.load(sys.stdin)['whiteboard_id'])")

# 2. 创建形状节点
cat > /tmp/shapes.json << 'EOF'
[
  {"type":"composite_shape","x":50,"y":50,"width":150,"height":40,
   "composite_shape":{"type":"round_rect"},
   "text":{"text":"客户端","font_size":14,"font_weight":"regular","horizontal_align":"center","vertical_align":"mid"},
   "style":{"fill_color":"#f5f5f5","fill_opacity":100,"border_style":"solid","border_color":"#616161","border_width":"narrow"},
   "z_index":10},
  {"type":"composite_shape","x":300,"y":50,"width":150,"height":40,
   "composite_shape":{"type":"round_rect"},
   "text":{"text":"API 网关","font_size":14,"font_weight":"bold","horizontal_align":"center","vertical_align":"mid"},
   "style":{"fill_color":"#3399ff","fill_opacity":100,"border_style":"none"},
   "z_index":10},
  {"type":"composite_shape","x":550,"y":50,"width":150,"height":40,
   "composite_shape":{"type":"round_rect"},
   "text":{"text":"数据库","font_size":14,"font_weight":"regular","horizontal_align":"center","vertical_align":"mid"},
   "style":{"fill_color":"#509863","fill_opacity":100,"border_style":"none"},
   "z_index":10}
]
EOF
feishu-cli board create-notes $BOARD_ID /tmp/shapes.json -o json
# → 返回 node_ids: ["o1:1", "o1:2", "o1:3"]

# 3. 创建连接线（引用上面返回的 ID）
cat > /tmp/connectors.json << 'EOF'
[
  {"type":"connector","width":1,"height":1,"z_index":50,
   "connector":{"shape":"polyline",
     "start":{"arrow_style":"none","attached_object":{"id":"o1:1","position":{"x":1,"y":0.5},"snap_to":"right"}},
     "end":{"arrow_style":"triangle_arrow","attached_object":{"id":"o1:2","position":{"x":0,"y":0.5},"snap_to":"left"}}},
   "style":{"border_color":"#646a73","border_opacity":100,"border_style":"solid","border_width":"narrow"}},
  {"type":"connector","width":1,"height":1,"z_index":50,
   "connector":{"shape":"polyline",
     "start":{"arrow_style":"none","attached_object":{"id":"o1:2","position":{"x":1,"y":0.5},"snap_to":"right"}},
     "end":{"arrow_style":"triangle_arrow","attached_object":{"id":"o1:3","position":{"x":0,"y":0.5},"snap_to":"left"}}},
   "style":{"border_color":"#646a73","border_opacity":100,"border_style":"solid","border_width":"narrow"}}
]
EOF
feishu-cli board create-notes $BOARD_ID /tmp/connectors.json -o json

# 4. 截图验证
feishu-cli board image $BOARD_ID /tmp/architecture.png

详细 API 参考

节点类型完整字段、connector 高级参数、Redraw 清洗字段等详细信息见 references/node-api.md。