arch-vis

name	arch-vis
description	Draw architecture diagrams on Feishu whiteboards via API. Use when user asks to create system architecture diagrams, flowcharts, module relationship diagrams, or visualize code structure on Feishu/Lark whiteboards. Supports shapes, connectors, mind maps, and iterative visual refinement by downloading and viewing results.

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

1. Create nodes (all shapes + connectors in one batch)
2. Download image to /tmp/board.png
3. Use Read tool to view result
4. 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