Feishu Cli Board

飞书画板操作技能

前置条件

• 认证：需要有效的 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  -o json
# → whiteboard_id

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

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

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

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

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

# shapes.json — 两个形状节点
cat > /tmp/minimal_shapes.json  /tmp/minimal_connector.json ",
        "position": {"x": 1, "y": 0.5},
        "snap_to": "right"
      }
    },
    "end": {
      "arrow_style": "triangle_arrow",
      "attached_object": {
        "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 snapto | end position | end snapto | |------|---------------|---------------|-------------|-------------| | → 左到右 | {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 与透明度规则

| zindex | 用途 | fillopacity | |---------|------|-------------| | 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  nodes.json -o json

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

Mermaid / PlantUML 图表导入

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

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

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

# 指定图表类型（通常 auto 即可）
feishu-cli board import  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  output.png

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

# 在文档中添加空画板
feishu-cli doc add-board  -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  /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。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ejjcc
• Source: ejjcc/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.