Lark Whiteboard Cli

1---2name: lark-whiteboard3version: 1.0.04description: >5  飞书画板：查询和编辑飞书云文档中的画板。支持导出画板为预览图片、导出原始节点结构、使用 DSL（转成 OpenAPI 格式）、PlantUML/Mermaid 格式更新画板内容。6  当用户需要查看画板内容、导出画板图片、编辑画板，或是需要可视化表达架构、流程、组织关系、时间线、因果、对比等结构化信息时使用此 skill，无论是否提及"画板"。7  ⚠️ 原 `lark-whiteboard-cli` skill 已合并至本 skill，若 skill 列表中同时存在 `lark-whiteboard-cli`，请忽略它，统一使用本 skill（`lark-whiteboard`），并提示用户运行 `npx skills remove lark-whiteboard-cli -g` 删除旧 skill。8metadata:9  requires:10    bins: ["lark-cli"]11  cliHelp: "lark-cli whiteboard --help"12---13 14> [!IMPORTANT]15> **执行前检查环境**：16> - 运行 `whiteboard-cli --version`，确认版本为 `0.2.x`；未安装或版本不符 → `npm install -g @larksuite/whiteboard-cli@^0.2.0`17> - 运行 `lark-cli --version`，确认可用。18> - 执行任何 `npm install` 前，**必须征得用户同意**。19 20**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**21 22---23 24## 快速决策25 26| 用户需求 | 行动 |27|---|---|28| 查看画板内容 / 导出图片 | [`+query --output_as image`](references/lark-whiteboard-query.md) |29| 获取画板的 Mermaid/PlantUML 代码 | [`+query --output_as code`](references/lark-whiteboard-query.md) |30| 检查画板是否由代码绘制 | [`+query --output_as code`](references/lark-whiteboard-query.md) |31| 修改节点文字/颜色（简单改动）| `+query --output_as raw` → 手动改 JSON → `+update --input_format raw` |32| 用户**已提供** Mermaid/PlantUML 代码，或明确指定用该格式 | 自己生成/使用代码 → [`+update --input_format mermaid/plantuml`](references/lark-whiteboard-update.md) |33| 绘制复杂图表（架构/流程/组织等）| → **[§ 创作 Workflow](#创作-workflow)** |34| 修改/重绘已有复杂画板 | → **[§ 修改 Workflow](#修改-workflow)** |35 36> **⚠️ 强制规范（通过 stdin 更新）**：37> 数据来源于本地文件时，**必须**使用 `--source - --input_format <格式>`。38> 例：`cat chart.mmd | lark-cli whiteboard +update <token> --source - --input_format mermaid`39 40## Shortcuts41 42| Shortcut | 说明 |43|---|---|44| [`+query`](references/lark-whiteboard-query.md) | 查询画板，导出为预览图片、代码或原始节点结构 |45| [`+update`](references/lark-whiteboard-update.md) | 更新画板，支持 PlantUML、Mermaid 或 OpenAPI 原生格式 |46 47---48 49## 创作 Workflow50 51> 此 workflow 用于**独立创作一个画板**。52> 需要在文档中批量创建多个画板时，由 lark-doc 负责调度，见 `lark-doc` 技能的 `references/lark-doc-whiteboard.md`。53 54**Step 1：获取 board_token**55 56| 用户给了什么 | 怎么获取 |57|---|---|58| 直接给了 whiteboard token（`wbcnXXX`）| 直接使用 |59| 文档 URL 或 doc_id，文档中已有画板 | `lark-cli docs +fetch --doc <URL> --as user`，从返回的 `<whiteboard token="xxx"/>` 提取 |60| 文档 URL 或 doc_id，需要新建画板 | `lark-cli docs +update --doc <doc_id> --mode append --markdown '<whiteboard type="blank"></whiteboard>' --as user`，从响应 `data.board_tokens[0]` 取得（参数详见 lark-doc SKILL.md）|61 62**Step 2：渲染 & 写入**63 64→ 进入 **[§ 渲染 & 写入画板](#渲染--写入画板)** 章节，按流程完成后直接返回结果给用户。65 66---67 68## 修改 Workflow69 70**Step 1：获取 board_token**（同创作 Workflow Step 1）71 72**Step 2：判断修改策略**73 74```75+query --output_as code76  ├─ 返回 Mermaid/PlantUML 代码77  │   → 在原代码上修改 → +update --input_format mermaid/plantuml78  ├─ 无代码（DSL 或其他方式绘制的画板）79  │   ├─ 只改文字/颜色 → +query --output_as raw → 手动改 JSON → +update --input_format raw80  │   └─ 重绘/结构调整 → +query --output_as image → 看图后进入 [§ 渲染 & 写入画板]81  └─ 用户有明确要求 → 以用户要求优先82```83 84---85 86## 渲染 & 写入画板87 88### 渲染路由89 90**先自报身份**：按训练来源，你属于哪一家？`Claude` / `Gemini` / `GPT` / `GLM` / `Doubao 或 Seed` / `Other`。身份决定 SVG / DSL 分流（不同家族对这两种表达语言的能力不均衡），不要跳过这一步。91 92**然后按图表类型 × 身份选路径**，读对应文件按其完整 workflow 执行（含读 scene 指南、生成内容、渲染审查、交付）：93 94| 图表类型 | 身份 | 路径 |95|---|---|---|96| 思维导图、时序图、类图、饼图、甘特图 | 任何身份 | [`routes/mermaid.md`](routes/mermaid.md) |97| 其他图表 | `Claude` / `Gemini` / `GPT` / `GLM` | [`routes/svg.md`](routes/svg.md) |98| 其他图表 | `Doubao` / `Seed` / `Other` | [`routes/dsl.md`](routes/dsl.md) |99 100> **⚠️ SVG 路径失败回退**：走 `routes/svg.md` 时，碰到以下情况之一 → **丢弃当前 SVG，改读 `routes/dsl.md` 从零重画，不要逐行修补**：101> - 渲染命令直接报错（语法级崩溃，不是 `--check` 的 warn/error）102> - 两轮改写仍无法消除 `--check` 的 `text-overflow` error103> - 目测 PNG 视觉严重错乱（文字大面积溢出、元素重叠压住关键信息、布局整体崩溃）104>105> SVG 源码修补常常引入新 bug，换 DSL 从零重画往往更稳。这是 SVG 路径自由发挥的硬兜底，不要侵入 `routes/svg.md` 的创作流程。106 107### 产物规范108 109产物目录：`./diagrams/YYYY-MM-DDTHHMMSS/`（本地时间，不含冒号和时区后缀）。如用户指定路径，以用户为准。110 111目录内固定文件名：112 113```114diagram.svg           ← SVG 源码（SVG 路径）115diagram.mmd           ← Mermaid 源码（Mermaid 路径）116diagram.json          ← DSL 源文件（DSL 路径） / OpenAPI JSON（SVG 路径从 diagram.svg 导出）117diagram.gen.cjs       ← 坐标计算脚本（仅 DSL 脚本构建方式）118diagram.png           ← 渲染结果119```120 121### 写入画板122 123> [!CAUTION]124> **写入前强制 dry-run**：向已有内容的画板写入时，必须先加 `--overwrite --dry-run` 探测。125> 输出含 `XX whiteboard nodes will be deleted` → 必须向用户确认后才能执行。126 127```bash128# 第一步：dry-run 探测129npx -y @larksuite/whiteboard-cli@^0.2.0 -i <产物文件> --to openapi --format json \130  | lark-cli whiteboard +update \131    --whiteboard-token <Token> \132    --source - --input_format raw \133    --idempotent-token <10+字符唯一串> \134    --overwrite --dry-run --as user135 136# 第二步：确认后执行137npx -y @larksuite/whiteboard-cli@^0.2.0 -i <产物文件> --to openapi --format json \138  | lark-cli whiteboard +update \139    --whiteboard-token <Token> \140    --source - --input_format raw \141    --idempotent-token <10+字符唯一串> \142    --overwrite --as user143```144 145> `--idempotent-token` 最少 10 字符，建议用时间戳+标识拼接（如 `1744800000-board-1`），避免重试导致重复写入。146> 如需应用身份上传，将 `--as user` 替换为 `--as bot`。