diegosouzapw Feishu Whiteboard Diagram Skill
Draw architecture diagrams on Feishu whiteboards using the arch_vis package.
Quick Start
# 创建节点（从 JSON 文件）
uv run python entry.py nodes.json -o /tmp/board.png
# 仅下载当前画板
uv run python entry.py --download -o /tmp/board.png
# 从 stdin 读取 JSON
echo '[...]' | uv run python entry.py - -o /tmp/board.png
JSON 文件格式（数组或 {"nodes": [...]}）：
[
{"id": "api", "type": "composite_shape", "x": 100, "y": 100, ...},
{"id": "c1", "type": "connector", ...}
]
Node Structure
Shape
{"id": "api", "type": "composite_shape", "x": 100, "y": 100, "width": 140, "height": 55,
"text": {"text": "API Gateway", "horizontal_align": "center", "vertical_align": "mid"},
"style": {"theme_fill_color_code": 3, "theme_border_color_code": 6, "fill_color_type": 0},
"composite_shape": {"type": "round_rect"}}
Shape types: rect, round_rect, ellipse, diamond, cylinder, cloud
Connector
{"id": "c1", "type": "connector", "connector": {
"start": {"attached_object": {"id": "api", "snap_to": "bottom"}, "arrow_style": "none"},
"end": {"attached_object": {"id": "db", "snap_to": "top"}, "arrow_style": "triangle_arrow"},
"shape": "straight"}}
Mind Map
# Root
{"id": "mm:root", "type": "mind_map", "x": 400, "y": 300, "text": {"text": "Topic"},
"mind_map_root": {"layout": "left_right", "type": "mind_map_round_rect", "line_style": "curve"}}
# Child
{"id": "mm:c1", "type": "mind_map", "text": {"text": "Subtopic"},
"mind_map_node": {"parent_id": "mm:root", "type": "mind_map_text", "layout_position": "right"}}
Colors
| Purpose | fill_code | border_code |
|---|---|---|
| Entry/API | 3 | 6 |
| Services | 5 | 8 |
| Core/Alert | 6 | 9 |
| Database | 2 | 5 |
| Start/End | 17 | 11 |
Workflow
- Create nodes (all shapes + connectors in one batch)
- Download image to
/tmp/board.png - Use Read tool to view result
- Iterate if needed
References
- API 文档: references/ 目录包含完整的飞书画板 API 文档
Common Issues
- 403 (code 2890005): Share whiteboard with app ("can edit")
- Color not working: Use
theme_fill_color_code(int), not hex - Connector error: Nodes and connectors must be in same batch