飞书画板操作技能，用于把图表、SVG 或手写节点数据落到飞书画板上。下面按用途、主要能力、使用方式、适用场景和限制分段整理。
一、用途 用于在飞书文档中创建画板并写入图形内容，支持标准图表渲染、SVG 转原生节点、单节点装饰、精排架构图等多种落板方式。
二、前置条件 安装 feishu-cli，来源为 riba2534/feishu-cli。认证方式：环境变量 FEISHU_APP_ID + FEISHU_APP_SECRET，或 ~/.feishu-cli/config.yaml。所需权限：board:whiteboard（画板读写）+ docx:document（文档加画板）。路径 B/C 需要 whiteboard-cli，安装命令：npm i -g @larksuite/whiteboard-cli。
三、五种画图路径 路径 A：Mermaid/PlantUML 服务端渲染。适合标准图表（思维导图/时序图/类图/饼图/流程图/甘特图），整图作为一个节点展示，飞书自动排版。示例命令：feishu-cli board import $BOARD_ID flowchart.mmd --syntax mermaid，或从字符串导入加 --source-type content --syntax mermaid --diagram-type flowchart。限制：整张图作为一个节点无法拆开编辑；不支持 par 语法；≥10 participant / ≥3 层 alt / ≥30 长标签可能失败；CLI 会自动诊断复杂度并向 stderr 警告。 路径 B：Mermaid 本地引擎。适合复杂 Mermaid（服务端会失败）或需要每个节点单独编辑的场景。先执行 npm i -g @larksuite/whiteboard-cli，再执行 feishu-cli board import $BOARD_ID complex.mmd --syntax mermaid --engine local。工作原理：whiteboard-cli 在本地把 Mermaid 翻译为节点 JSON，再由 feishu-cli 用 create-notes 分批上传。 路径 C：SVG → 原生节点。适合所有 AI 自由设计图（飞轮、鱼骨、价值金字塔、转化漏斗、桑基、路线图、Dashboard、海报、Mobile UI、户型图、地铁图、插画、周期表、机芯、赛博朋克城市等），每个元素都是独立可编辑的飞书节点。一键脚本：python3 ./skills/feishu-cli-board/scripts/svg_to_board.py flywheel.svg $BOARD_ID。脚本自动执行 5 步：whiteboard-cli 翻译 SVG → 节点 JSON；修 z_index（按数组顺序显式赋值）；修剪 viewBox 溢出；分批 create-notes（每批 300，间隔 0.3s）；验证节点数与类型分布。先定色板再生成 SVG，色值取自统一色板不自创。 路径 D：SVG 单节点装饰。适合图标/印章/小元素（< 2KB SVG），不需要拆开编辑。命令：feishu-cli board svg-import $BOARD_ID icon.svg --x 100 --y 100 --width 60 --height 60，支持 --dry-run 预览。与路径 C 差异：D 为 1 个 svg 节点、整图作为矢量贴图、适合 < 2KB；C 为 N 个节点、每个 rect/text/path 可单选、复杂度不限。 路径 E：精排架构图。适合架构图/对比矩阵/组织树，需要绝对坐标 + 特定配色 + 连接线 ID 引用。流程：创建文档加画板；写 shapes.json 用 feishu-cli board create-notes 创建形状（返回 node_ids）；再写 connectors.json 引用 node_ids 创建连线。先形状后连线。
四、主要命令 feishu-cli doc add-board <doc_id>（加画板块，--parent-id/--index/-o json）；feishu-cli board nodes <board_id>（拉所有节点）；feishu-cli board image <board_id> out.png（下载缩略图）；feishu-cli board create-notes（批量创建节点）；feishu-cli board import（路径 A，--engine [server|local]）；feishu-cli board svg-import（路径 D）；svg_to_board.py（路径 C，--viewbox/--keep-overflow/--batch/--interval/--dry-run）；feishu-cli board update（覆盖模式）；feishu-cli board delete --all；feishu-cli board clone；feishu-cli board upload-image；feishu-cli board lint（几何质检）；feishu-cli board export-code（反向导出 SVG）。
五、适用场景 标准图表落板、复杂 Mermaid 转换、AI 自由设计图转可编辑节点、图标印章上传、精排架构图绘制、画板克隆、图片转 image 节点、几何质量检查、SVG 导出。
六、限制与注意事项 三大陷阱：z_index 错乱（大背景遮挡前景，需上传前显式赋值 z_index = i）；viewBox 溢出（右下角半截图形，需过滤/截断溢出节点）；节点翻倍（清空重传后节点数 ×2，rc=0 一律按成功，已翻倍则 board delete --all 后重传）。 关键约束：先形状后连线；最小字段集（多余字段触发 2890002 invalid arg）；背景色块 fill_opacity ≤ 25；z_index 分层（背景 0-1、次级 2-3、常规 10、连线 50）；坐标系为绝对坐标（路径 E 需手算 x/y/width/height）；节点文字简短（< 12 字）；同组节点视觉一致；单画板 > 2000 节点编辑器开始卡顿。色值取自统一色板，改色值/换底色时才需跑 feishu-cli-dataviz 校验器。
落板后验证清单：缩略图主元素都在；节点数核对；z_index 最小是大背景；viewBox 无溢出；lint 质量分 ≥ 0.85。