飞书画板全功能操作

前置条件

• feishu-cli：如尚未安装，前往 riba2534/feishu-cli 获取
• 认证：环境变量 FEISHU_APP_ID + FEISHU_APP_SECRET，或 ~/.feishu-cli/config.yaml
• 权限：board:whiteboard（画板读写）+ docx:document（文档中添加画板）
• 验证：feishu-cli auth status 确认认证正常

工作流程（3 步）

Step 1: 路由选择
  判断渲染路径：Mermaid 还是 OpenAPI JSON？

Step 2: 生成节点 JSON 或 Mermaid 代码
  - JSON 路径：参考 schema.md 构建节点数组 → layout.md 计算坐标 → style.md 上色
  - Mermaid 路径：直接生成 .mmd 内容

Step 3: 创建/更新并验证
  - 创建：board create-notes（先形状，再连线）
  - 验证：board image 截图检查
  - 有问题：调整坐标/样式后重新创建

Step 1: 路由选择

路由规则：

1. 思维导图、时序图、类图、饼图、流程图 → 默认走 Mermaid（board import）
2. 用户输入包含 Mermaid 语法 → 走 Mermaid
3. 其他所有类型 → 走 OpenAPI JSON（board create-notes）

Step 2: 生成节点 JSON / Mermaid

JSON 路径（大多数场景）：

1. 按 references/content.md 规划信息量和分组
2. 按 references/layout.md 选择布局模式，计算每个节点的 x/y 坐标
3. 按 references/style.md 上色（未指定时用经典色板）
4. 按 references/schema.md 语法输出完整 JSON
5. 连线参考 references/connectors.md，排版参考 references/typography.md

Mermaid 路径：

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

# 从文件导入
feishu-cli board import <whiteboard_id> diagram.mmd --syntax mermaid

限流处理

• 导入图表时遇到 HTTP 429 自动重试，采用指数退避 + 读取服务端 x-ogw-ratelimit-reset 响应头精确计算退避时间
• 大批量图表导入（如文档中包含 100+ 图表）时，CLI 自动控制并发和重试，默认最多重试 20 次
• verbose 模式下可观察重试日志，便于排查限流问题

Step 3: 创建/更新并验证

# 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. 创建形状节点（先形状）
feishu-cli board create-notes $BOARD_ID shapes.json -o json
# → 返回 node_ids: ["o1:1", "o1:2", ...]

# 3. 创建连接线（引用上面的 ID）
feishu-cli board create-notes $BOARD_ID connectors.json -o json

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

视觉审查：检查信息完整、布局合理、配色协调、文字无截断、连线无交叉。有问题按症状表修复后重新创建。

命令速查

传参方式：

# 从 JSON 文件（推荐）
feishu-cli board create-notes <id> nodes.json -o json

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

关键约束速查表

1. 先形状后连线 -- 连接线通过 ID 引用形状节点，必须在形状创建后再创建连线
2. 最小字段集 -- 多余字段导致 2890002 invalid arg，只用 schema.md 列出的安全字段
3. 背景色块 fill_opacity <= 60 -- 否则完全遮挡上层节点
4. z_index 分层 -- 背景 0-1、次级 2-3、常规节点 10、连线 50
5. 坐标系为绝对坐标 -- 没有自动布局引擎，每个节点必须手算 x/y/width/height
6. 节点文字保持简短 -- 标题 + 简短说明（12 字以内），不写长段落
7. 同组节点视觉一致 -- 同一分组内所有节点使用相同的 fillColor/borderColor

症状 → 修复表

渲染前自查

生成 JSON 后、创建节点前，快速检查：

• 不同分组用了不同颜色？同组节点样式完全一致？
• 外层浅色背景（低 opacity）、内层节点实心填充？
• 所有节点有边框（border_style=solid, border_width=medium）？
• 连线用灰色（#BBBFC4 或 #646A73），不用彩色？
• 背景色块 z_index=0-1 且 fill_opacity <= 25？
• 节点间距充足（同层 >= 30px，有连线 >= 60px）？
• JSON 中没有多余字段（id/locked/children 等）？

board update — 更新画板内容

更新画板节点内容，支持从文件或 stdin 读取节点 JSON。

feishu-cli board update <whiteboard_id> [nodes_json_file] [--overwrite] [--dry-run] [--stdin]

参数说明

使用示例

# 从文件更新（追加模式，保留旧节点）
feishu-cli board update BOARD_ID nodes.json

# 覆盖模式：先创建新节点，再删除旧节点
feishu-cli board update BOARD_ID nodes.json --overwrite

# 从 stdin 管道更新（覆盖模式）
cat nodes.json | feishu-cli board update BOARD_ID --stdin --overwrite

# 预览覆盖操作（不实际执行）
feishu-cli board update BOARD_ID nodes.json --overwrite --dry-run

# JSON 格式输出（返回新节点 ID 列表）
feishu-cli board update BOARD_ID nodes.json --overwrite -o json

覆盖模式流程

1. 获取当前画板所有旧节点 ID
2. 创建新节点
3. 删除不在新节点中的旧节点（先写后删，避免空画板）

board delete — 删除画板节点

批量删除画板中的节点，支持指定节点 ID 或清空整个画板。

feishu-cli board delete <whiteboard_id> [--node-ids id1,id2] [--all]

参数说明

使用示例

# 删除指定节点
feishu-cli board delete BOARD_ID --node-ids o1:1,o1:2,o1:3

# 删除所有节点（清空画板）
feishu-cli board delete BOARD_ID --all

# JSON 格式输出
feishu-cli board delete BOARD_ID --all -o json

参考文档索引