feishu-cli-board

Feishu ホワイトボード · 5 つの描画方法ガイド

前提条件

• feishu-cli：未インストールの場合は、riba2534/feishu-cli からインストールしてください
• 認証：環境変数 FEISHU_APP_ID と FEISHU_APP_SECRET、または ~/.feishu-cli/config.yaml
• 権限：board:whiteboard（ホワイトボードの読み書き）+ docx:document（ドキュメントへのホワイトボード追加）
• whiteboard-cli（方法 B/C で使用）：npm i -g @larksuite/whiteboard-cli

---

選択フローチャート

画什么？
│
├─ 标准图表（思维导图/时序图/类图/饼图/流程图/甘特图）
│  ├─ 图整图展示即可，不需要单独编辑节点 → 路径 A（Mermaid 服务端）
│  └─ 需要单独编辑每个节点 / Mermaid 含 par / 10+ participant / 30+ 长标签
│     → 路径 B（Mermaid 本地引擎）
│
├─ AI 自由作图（飞轮/鱼骨/价值金字塔/转化漏斗/桑基/路线图/Dashboard/海报/
│              Mobile UI/户型图/地铁图/插画/周期表/机芯/赛博朋克城市等）
│  ⭐ → 路径 C（SVG → 原生节点，每个元素可单独点击编辑）
│
├─ 简单 SVG 装饰（图标/印章/小元素，< 2KB SVG）
│  └─ 路径 D（svg-import 单节点）
│
└─ 精排架构图 / 对比矩阵 / 组织树（需要绝对坐标 + 特定配色 + 连接线 ID 引用）
   └─ 路径 E（手写节点 JSON + create-notes）

方法選択早見表：

ユーザーの説明	推奨方法
「マインドマップ／シーケンス図／クラス図を描いて」	A
「フローチャートを描いて」	A
「この mermaid をホワイトボードに反映して」	A
「mermaid のサーバー側でエラーが発生する／par 非対応／複雑すぎる」	B
「成長フライホイール／フィッシュボーン分析／価値ピラミッドを描いて」	C ⭐
「ダッシュボード／モバイル UI／ポスターを描いて」	C ⭐
「イラスト／間取り図／地下鉄路線図を描いて」	C ⭐
「AI が自由にデザインする図（Claude で SVG を直接出力）」	C ⭐
「図の各要素を個別にクリック／色変更／ドラッグできるようにしたい」	C ⭐
「小さなアイコン／印章をホワイトボードにアップロード」	D
「6 つのマイクロサービスのアーキテクチャ図を、正確な座標と接続線付きで描いて」	E

---

方法 A：Mermaid／PlantUML サーバー側

適しています：標準的な図表。図全体を 1 つのノードとして表示します。

クイックスタート

DOC_ID=$(feishu-cli doc create --title "示例" -o json | jq -r .document_id)
BOARD_ID=$(feishu-cli doc add-board $DOC_ID -o json | jq -r .whiteboard_id)

# 从文件导入
feishu-cli board import $BOARD_ID flowchart.mmd --syntax mermaid

# 从字符串导入
feishu-cli board import $BOARD_ID "graph TD; A-->B-->C" --source-type content --syntax mermaid --diagram-type flowchart

# PlantUML
feishu-cli board import $BOARD_ID diagram.puml --syntax plantuml

制限事項（詳しくは references/mermaid-engines.md を参照）

• 図全体が 1 つのノードになるため、個別に分割して編集できません
• par 構文には対応していません
• participant が 10 個以上／alt が 3 層以上／長いラベルが 30 個以上の場合、失敗することがあります
• CLI が複雑さを自動診断し、stderr に警告します

---

方法 B：Mermaid ローカルエンジン

適しています：複雑な Mermaid（サーバー側で失敗するもの）、または各ノードを個別に編集する必要がある場合。

クイックスタート

# 一次性装好本地引擎（仅首次）
npm i -g @larksuite/whiteboard-cli

# 走本地引擎
feishu-cli board import $BOARD_ID complex.mmd --syntax mermaid --engine local

動作原理

feishu-cli board import --engine local
    │
    ├─ whiteboard-cli 把 Mermaid 翻译为节点 JSON（在本地，不调飞书）
    └─ feishu-cli 把节点 JSON 用 create-notes 分批上传

詳細な比較と注意点は references/mermaid-engines.md を参照してください。

---

方法 C：SVG → ネイティブノード ⭐

適しています：AI が自由にデザインするあらゆる図。各要素が個別に編集可能な Feishu ノードになります。

クイックスタート（一括スクリプト）

# Step 0: 定色板（生成 SVG 之前）—— 色值取自统一色板，不自创
#   结构分组用浅底/深边对、数据系列用 categorical 原色，见 references/style.md。
#   原样按序取用统一色板时无需校验（已预校验，结论见 feishu-cli-dataviz palette.md）；
#   仅当改色值/换底色时先跑校验（定位方式见 references/style.md"数据图表的系列色"一节）。

# Step 1: 准备 SVG（手写 / Python 生成 / AI 吐）
# 示例：用 Claude 生成一个增长飞轮 SVG，保存为 flywheel.svg

# Step 2: 创建文档 + 画板
DOC_ID=$(feishu-cli doc create --title "增长飞轮" -o json | jq -r .document_id)
BOARD_ID=$(feishu-cli doc add-board $DOC_ID -o json | jq -r .whiteboard_id)

# Step 3: 一键 SVG → 飞书画板（5 步管道自动执行）
python3 ./skills/feishu-cli-board/scripts/svg_to_board.py flywheel.svg $BOARD_ID

スクリプトは以下の 5 つの手順を自動で実行します。

1. whiteboard-cli による変換：SVG → ノード JSON
2. z_index の修正：配列の順序に従って明示的に値を設定します（落とし穴 1 を解消）
3. viewBox のはみ出しをトリミング：範囲外のノードを削除します（落とし穴 2 を解消）
4. create-notes を複数回に分けて実行：1 回あたり 300 件、間隔 0.3s（レート制限対策）
5. 検証：実際のノード数／種類別の分布を取得して比較します

ワークフローの詳細

references/svg-workflow.md を参照してください。SVG 要素から Feishu ノードへの変換マッピング表、実例 14 点のノード密度の目安、図を分割する境界を掲載しています。

SVG デザインの参考資料

references/examples-real.md を参照してください。実例 14 点のデザインパターンの索引、各図の SVG 要素の組み合わせ、重要な技術ポイント（極座標／三角関数／cubic-bezier など）を掲載しています。

---

方法 D：SVG の単一ノード装飾

適しています：アイコン／印章／小さな要素（SVG が 2 KB 未満）。分割して編集する必要がない場合。

クイックスタート

feishu-cli board svg-import $BOARD_ID icon.svg \
    --x 100 --y 100 --width 60 --height 60

# 自动从 viewBox 推断尺寸
feishu-cli board svg-import $BOARD_ID badge.svg --x 0 --y 0

# 直接传字符串
feishu-cli board svg-import $BOARD_ID '<svg viewBox="0 0 100 100">...</svg>' \
    --source-type content --x 50 --y 50

# 预览不发请求
feishu-cli board svg-import $BOARD_ID drawing.svg --dry-run

方法 C との主な違い

方法	ノード数	編集のしやすさ	適した複雑さ
D（svg-import）	1（図全体で svg ノード 1 個）	❌ 図全体が 1 つのベクター画像になります	SVG が 2 KB 未満
C（svg_to_board.py）	N（要素ごとにノード 1 個）	✅ 各 rect/text/path を個別に選択できます	制限なし

---

方法 E：精密配置のアーキテクチャ図

適しています：アーキテクチャ図／比較マトリクス／組織図。絶対座標、指定の配色、接続線の ID 参照が必要な場合。

クイックスタート

# 1. 创建文档 + 画板
DOC_ID=$(feishu-cli doc create --title "微服务架构" -o json | jq -r .document_id)
BOARD_ID=$(feishu-cli doc add-board $DOC_ID -o json | jq -r .whiteboard_id)

# 2. 写 shapes.json（先形状）
cat > /tmp/shapes.json << 'EOF'
[
  {"type":"composite_shape","x":100,"y":100,"width":160,"height":40,"z_index":10,
   "composite_shape":{"type":"round_rect"},
   "text":{"text":"服务 A","font_size":14,"font_weight":"regular","horizontal_align":"center","vertical_align":"mid"},
   "style":{"fill_color":"#FFFFFF","fill_opacity":100,"border_style":"solid","border_color":"#1446C2","border_width":"medium","border_opacity":100}},
  {"type":"composite_shape","x":400,"y":100,"width":160,"height":40,"z_index":10,
   "composite_shape":{"type":"round_rect"},
   "text":{"text":"服务 B","font_size":14,"font_weight":"regular","horizontal_align":"center","vertical_align":"mid"},
   "style":{"fill_color":"#FFFFFF","fill_opacity":100,"border_style":"solid","border_color":"#0C6800","border_width":"medium","border_opacity":100}}
]
EOF
feishu-cli board create-notes $BOARD_ID /tmp/shapes.json -o json
# → {"node_ids":["o1:1","o1:2"]}

# 3. 写 connectors.json（再连线，引用上面的 node_ids）
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":"#BBBFC4","border_opacity":100,"border_style":"solid","border_width":"narrow"}}
]
EOF
feishu-cli board create-notes $BOARD_ID /tmp/connectors.json -o json

参考資料

• ノード JSON Schema：references/schema.md
• レイアウト戦略：references/layout.md（階層ストリップ／行列揃え／島型／ツリー型）
• 配色システム：references/style.md（統一カラーパレットの使用方法 + 5 つのテーマバリエーション + 構造ルール）
• 接続線の戦略：references/connectors.md（snap_to／shape／間隔）
• タイポグラフィルール：references/typography.md（フォントサイズの階層）
• 情報設計：references/content.md（情報量の目安）

---

全コマンド早見表

コマンド	用途	主なパラメーター
feishu-cli doc add-board <doc_id>	ドキュメントにホワイトボードブロックを追加	--parent-id（親ブロック ID。デフォルトはルート階層）--index（挿入位置、-1=末尾）-o json
feishu-cli board nodes <board_id>	すべてのノードを取得	なし
feishu-cli board image <board_id> out.png	ホワイトボードのサムネイルをダウンロード	なし
feishu-cli board create-notes <board_id> nodes.json	ノードを一括作成	--source-type --client-token
feishu-cli board import <board_id> diagram.mmd --syntax mermaid	方法 A：サーバー側でレンダリング	--engine [server|local] --diagram-type --style --dry-run
feishu-cli board svg-import <board_id> drawing.svg	方法 D：単一の svg ノード	--x --y --width --height --source-type --dry-run
python3 svg_to_board.py drawing.svg <board_id>	方法 C：5 段階のパイプライン	--viewbox WxH（SVG の viewBox を上書き。デフォルトでは自動解析）--keep-overflow（範囲外のノードをトリミングしない）--batch（デフォルトは 300）--interval（デフォルトは 0.3s）--dry-run
feishu-cli board update <board_id> nodes.json	ホワイトボードを更新（上書きモード）	--overwrite --snapshot --dry-run --stdin
feishu-cli board delete <board_id> --all	すべてのノードを削除	--node-ids
feishu-cli board clone <src> <dst>	ホワイトボードを複製	--batch-size --interval --filter-types --dry-run
feishu-cli board upload-image <board_id> photo.png	画像を image ノードに変換	--x --y --width --height --dry-run
feishu-cli board lint <board_id>	ジオメトリの品質チェック	なし
feishu-cli board export-code <board_id>	SVG に逆エクスポート	--output-path --merge

各コマンドの内部動作の詳細は、対応するコード cmd/board_*.go を参照してください。

---

重大な落とし穴 3 つ（早見表）

実際の使用で特に陥りやすい 3 つの問題については、すべて references/pitfalls.md に詳しいトラブルシューティングを掲載しています。

陷阱 1: z_index 错乱 ⭐⭐⭐

• 现象：大背景遮挡前景，画板视觉混乱
• 根因：whiteboard-cli 输出节点不带 z_index，飞书自动分配是乱序
• 修复：上传前按数组 index 显式赋 z_index = i
• 一键修复：scripts/svg_to_board.py Step 2 内置

陷阱 2: viewBox 溢出 ⭐⭐

• 现象：右下角"半截楼"诡异图形
• 根因：节点 x + width > viewBox_w
• 修复：上传前过滤 / 截断溢出节点
• 一键修复：scripts/svg_to_board.py Step 3 内置

陷阱 3: 节点翻倍 ⭐⭐

• 现象：清空重传后节点数 ×2
• 根因：脚本 stdout 解析失败但 API 已成功 → 重传导致翻倍
• 修复：rc=0 一律按成功，已翻倍则 board delete --all 后重传
• 一键修复：scripts/svg_to_board.py Step 4 容错解析内置

---

关键约束速查表

1. 先形状后连线：connector 通过 ID 引用形状节点，必须先创建形状才能创建连线
2. 最小字段集：多余字段触发 2890002 invalid arg，只用 references/schema.md 列出的安全字段
3. 背景色块 fill_opacity ≤ 25：否则完全遮挡上层节点
4. z_index 分层：背景 0-1、次级 2-3、常规节点 10、连线 50
5. 坐标系为绝对坐标：手写节点必须手算 x/y/width/height（路径 E）
6. 节点文字简短：标题 + 简短说明（< 12 字），不写长段落
7. 同组节点视觉一致：同分组用相同 fill_color / border_color
8. 节点数上限：单画板 > 2000 节点时编辑器开始卡顿，考虑拆图或简化
9. 色值取自统一色板：分组/系列色按 references/style.md 按序取用，不自创、不循环；改色值/换底色时才需跑 feishu-cli-dataviz 校验器（默认色板已预校验）

---

症状 → 修复对照表

看到的问题	改什么	详见
文字被截断 / 溢出	增大 width 或 height，或缩短文字	references/typography.md
节点重叠粘连	增大节点间距（同层 ≥ 30px，有连线 ≥ 60px）	references/layout.md
背景色块遮挡节点	降低 fill_opacity（≤ 25），确认 z_index 分层	references/schema.md
连线穿过节点	调整 snap_to 方向或增大间距	references/connectors.md
大背景反而盖住前景	z_index 错乱 → 显式赋值	references/pitfalls.md ⭐
右下角"半截楼"	viewBox 溢出 → 修剪	references/pitfalls.md ⭐
节点数翻倍 / 颜色加深	重传导致翻倍 → board delete --all 后重传	references/pitfalls.md ⭐
文字和背景色太接近	调 fill_color 或 text.text_color，确保对比度	references/style.md
分组看不出来	同分组用同色，跨组换色	references/style.md
数据系列颜色难分辨（色盲/投影）	系列色改按统一色板顺序取用并跑校验器	feishu-cli-dataviz
不确定该画柱状/折线/饼	按数据任务选形式，别按用户口头图表名	feishu-cli-dataviz
2890002 invalid arg	含多余字段（id/locked/children 等只读字段）	references/schema.md
Mermaid 服务端报错	切 --engine local 或改 SVG	references/mermaid-engines.md

---

端到端验证清单

落板后逐项检查：

• 缩略图主元素都在：feishu-cli board image <id> /tmp/check.png
• 节点数对：feishu-cli board nodes <id> | jq '.data.nodes | length'
• z_index 最小是大背景：见 references/pitfalls.md 通用诊断 Step 2
• viewBox 无溢出：max(x+w) ≤ viewBox_w
• lint 质量分 ≥ 0.85：feishu-cli board lint <id>

任何一项不通过，回 references/pitfalls.md 排障。

---

参考文档索引

文件	何时读
references/svg-workflow.md	走路径 C 时必读（5 步管道详解 + 翻译映射表）
references/mermaid-engines.md	走路径 A/B 时必读（服务端 vs 本地引擎选型）
references/pitfalls.md	⭐ 实战必读（z_index / viewBox / 翻倍三大陷阱排障）
references/examples-real.md	设计参考（14 张实战图的模式 + SVG 元素 + 节点密度）
references/schema.md	走路径 E 时必读（节点 JSON 权威参考）
references/layout.md	走路径 E 时必读（5 种布局策略 + 间距规则）
references/style.md	路径 C/E 配色参考（统一色板取用方式 + 5 个主题变体）
references/connectors.md	用连线时参考（snap_to / shape 选择）
references/typography.md	文字排版参考（字号层级）
references/content.md	信息量规划（避免过载）
references/node-api.md	API 端点详解、错误码排障、典型工作流

---

一句话总结

用户描述	命令
"画个增长飞轮 / 鱼骨 / Dashboard"	python3 svg_to_board.py drawing.svg $BOARD
"把这份 mermaid 落到画板"	feishu-cli board import $BOARD diagram.mmd --syntax mermaid
"mermaid 服务端失败 / 太复杂"	加 --engine local
"上传个小图标 / 印章"	feishu-cli board svg-import $BOARD icon.svg
"精排架构图，每个节点要手摆位置"	手写 nodes.json + feishu-cli board create-notes
"克隆这张画板"	feishu-cli board clone <src> <dst>
"把这张图片放到画板"	feishu-cli board upload-image $BOARD photo.png
"检查画板质量"	feishu-cli board lint $BOARD
"把画板里的 SVG 拉回本地"	feishu-cli board export-code $BOARD --output-path design.svg --merge