@yandy0725/pi-lark 0.1.0

package/skills/lark-whiteboard/elements/typography.md

@@ -0,0 +1,73 @@
+# 排版规则
+
+## 字号层级表
+
+| 层级 | 字号 | 用途 | 对齐 |
+|------|------|------|------|
+| H1 | 24-28 | 图表标题（每图一个） | center |
+| H2 | 18-20 | 分区/层标签 | right（侧标签）或 center（顶部标签） |
+| H3 | 15-16 | 分组标题、卡片标题 | center 或 left |
+| Body | 14 | 正文、节点文字 | center（短标签）或 left（长文本） |
+| Caption | 13 | 辅助说明、注解 | left |
+
+规则：
+- 同张图不超过 3 个字号层级
+- 同级节点 fontSize 必须完全相同
+- 相邻层级字号差 >= 4px
+
+---
+
+## 对齐规则
+
+Shape 节点默认 `textAlign: 'center'` + `verticalAlign: 'middle'`（与 CSS 相反）。如需左对齐须显式声明。
+
+| 内容类型 | 对齐方式 |
+|---------|---------|
+| 短文本（<=15 字） | center |
+| 长文本（>15 字） | left |
+| 侧标签（层名、分区名） | right |
+| 图表标题 | center |
+| 多行描述/段落 | left |
+
+---
+
+## 图表标题
+
+用独立 text 节点，不要用 frame 的 `title` 属性。
+
+- Flex 布局：放在最外层 frame 的第一个 child，`width: "fill-container"`
+- 绝对定位：width 设为图表整体宽度，`textAlign: "center"`
+
+---
+
+## 标题和描述拆成两个节点
+
+一个卡片内展示名称和描述时，用 frame 包两个 text 节点，不要塞进同一个 shape：
+
+```json
+{
+  "type": "frame", "layout": "vertical", "gap": 4, "padding": 12,
+  "width": "fill-container", "height": "fit-content",
+  "borderWidth": 2, "borderRadius": 8,
+  "children": [
+    { "type": "text", "width": "fill-container", "height": "fit-content",
+      "text": "用户服务", "fontSize": 16 },
+    { "type": "text", "width": "fill-container", "height": "fit-content",
+      "text": "处理注册登录和个人信息管理", "fontSize": 13 }
+  ]
+}
+```
+
+---
+
+## 图标+文字组合
+
+icon + text 纵向排列时：icon 宽高 36-48px，下方文字 fontSize 12-13，外层 frame gap 4-8。icon 比文字大 2-3 倍时视觉比例最佳。
+
+---
+
+## 尺寸规则
+
+含文字节点 `height` 必须用 `'fit-content'`。写死高度会截断文字。
+
+所有节点必须显式声明 `width` 和 `height`。

package/skills/lark-whiteboard/references/lark-whiteboard-query.md

@@ -0,0 +1,60 @@
+# whiteboard +query（查询画板）
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+查询画板内容，支持导出为预览图片、SVG 矢量图、提取 PlantUML/Mermaid 代码，或获取飞书 OpenAPI 原生画板节点格式。
+
+## 参数
+
+| 参数                   | 必填 | 说明                                                                     |
+|----------------------|----|------------------------------------------------------------------------|
+| `--whiteboard-token` | 是  | 画板 token，需要拥有画板的读权限                                                    |
+| `--output_as`        | 是  | 输出格式：`image`（预览图片）、`svg`（SVG 矢量图）、`code`（PlantUML/Mermaid 代码）、`raw`（OpenAPI 原生画板节点格式） |
+| `--output`           | 否  | 输出路径。当 `--output_as image` 时必填；当 `--output_as svg/code/raw` 时可选，不填则直接输出到终端 |
+| `--overwrite`        | 否  | 覆盖已存在的文件，默认为 false                                                     |
+
+## 输出格式
+
+- `image`：预览图片
+- `svg`：导出画板为标准 SVG 矢量图。可用于 SVG 编辑后回写画板（见 [`routes/svg-edit.md`](../routes/svg-edit.md)）。注意：导出为纯视觉快照，思维导图层级、表格结构、连接器绑定等语义信息会丢失。
+- `code`：PlantUML/Mermaid 代码。仅限画板内有且仅有一个 PlantUML/Mermaid 图时，才可导出代码，否则会在返回值中告知不存在/有多个节点。
+- `raw`：飞书 OpenAPI 原生画板节点格式。这一 json 格式不适合直接编辑复杂布局或内容，建议仅限于需要修改简单的文本内容/颜色等细节时使用。需要进行更复杂的设计/修改时，建议参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)。
+
+## 示例
+
+### 示例 1：导出画板为预览图片
+
+```bash
+lark-cli whiteboard +query \
+  --whiteboard-token "wbcnxxxxxxxx" \
+  --output_as image \
+  --output ./preview.png
+```
+
+### 示例 2：提取画板中的代码并直接输出
+
+```bash
+lark-cli whiteboard +query \
+  --whiteboard-token "wbcnxxxxxxxx" \
+  --output_as code
+```
+
+### 示例 3：导出画板为 SVG 矢量图
+
+```bash
+lark-cli whiteboard +query \
+  --whiteboard-token "wbcnxxxxxxxx" \
+  --output_as svg \
+  --output ./whiteboard.svg \
+  --as user
+```
+
+### 示例 4：导出画板原始节点结构到文件
+
+```bash
+lark-cli whiteboard +query \
+  --whiteboard-token "wbcnxxxxxxxx" \
+  --output_as raw \
+  --output ./nodes.json \
+  --overwrite
+```

package/skills/lark-whiteboard/references/lark-whiteboard-update.md

@@ -0,0 +1,122 @@
+# whiteboard +update（更新画板）
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+更新画板内容，支持四种输入格式：
+
+- `raw`：飞书 OpenAPI 原生画板节点格式，不推荐直接编辑。
+- `plantuml`：PlantUML 代码
+- `mermaid`：Mermaid 代码
+- `svg`：SVG 文本
+
+输入内容可以通过管道从 stdin 读取，或通过 `--source` 指定文件。
+
+## 参数
+
+| 参数                   | 必填 | 说明                                         |
+|----------------------|----|--------------------------------------------|
+| `--whiteboard-token` | 是  | 画板 token，需要拥有画板的编辑权限                       |
+| `--idempotent-token` | 否  | 幂等 token，确保更新操作幂等，最小长度 10 个字符              |
+| `--overwrite`        | 否  | 覆盖更新，在更新前删除所有现有内容，默认为 false                |
+| `--source`           | 是  | 输入画板内容，支持使用 `@path` 从文件读取，或 `-` 从 stdin 读取 |
+| `--input_format`     | 否  | 输入格式：`raw`、`plantuml`、`mermaid`、`svg`，默认为 `raw`  |
+
+### 以 raw (OpenAPI 原生画板节点格式) 创作
+
+**不要以直接生成 json 语法的方式创作 raw 格式的飞书 OpenAPI 原生画板节点参数**
+
+思维导图，时序图，类图，饼图，流程图等图表推荐使用 Mermaid/PlantUML 语法绘制。
+
+而当需要绘制架构图，组织架构图，泳道图，对比图，鱼骨图，柱状图，折线图，树状图，漏斗图，金字塔图，循环/飞轮图，里程碑或其他较为复杂的图表时，推荐参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板) 使用 whiteboard-cli 工具创作。
+
+## 示例
+
+### 示例 1：使用 PlantUML 代码更新画板（从 stdin 读取）
+
+```bash
+# 编写 PlantUML 代码
+cat > diagram.puml << 'EOF'
+@startuml
+Alice -> Bob: Hello
+Bob -> Alice: Hi
+@enduml
+EOF
+
+# 通过管道传递给命令
+cat diagram.puml | lark-cli whiteboard +update \
+  --whiteboard-token <画板Token> \
+  --input_format plantuml --source -\
+  --overwrite --as user
+```
+
+### 示例 2：使用 Mermaid 代码更新画板（从文件读取）
+
+```bash
+# 编写 Mermaid 代码
+cat > diagram.mmd << 'EOF'
+graph TD
+    A[开始] --> B{判断}
+    B -->|是| C[处理]
+    B -->|否| D[结束]
+    C --> D
+EOF
+
+# 从文件读取并更新
+lark-cli whiteboard +update \
+  --whiteboard-token <画板Token> \
+  --input_format mermaid \
+  --source @./diagram.mmd \
+  --overwrite --as user
+```
+
+### 示例 3：使用 whiteboard-cli 生成 OpenAPI 格式并写入画板
+
+whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)
+
+```bash
+# 使用 whiteboard-cli 生成 OpenAPI 格式并通过管道传递
+npx -y @larksuite/whiteboard-cli@^0.2.12 -i <产物文件> --to openapi --format json \
+  | lark-cli whiteboard +update \
+    --whiteboard-token <画板Token> \
+    --source - --input_format raw \
+    --idempotent-token <10+字符唯一串> \
+    --as user
+```
+
+### 示例 4：先生成产物文件，再从文件读取更新
+
+whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)
+
+```bash
+# 生成 OpenAPI 格式到文件
+npx -y @larksuite/whiteboard-cli@^0.2.12 -i <DSL 文件> --to openapi --format json -o ./temp.json
+
+# 从文件读取并更新
+lark-cli whiteboard +update \
+  --whiteboard-token <画板Token> \
+  --idempotent-token <10+字符唯一串> \
+  --input_format raw \
+  --source @./temp.json \
+  --overwrite --as user
+```
+
+### 示例 5：使用 SVG 写入画板（从文件读取）
+
+适用于从零创建（直接写入 SVG）和编辑现有画板（编辑工作流详见 [`../routes/svg-edit.md`](../routes/svg-edit.md)）。
+
+```bash
+# 编写或导出 SVG 文件
+cat > diagram.svg << 'EOF'
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 100">
+  <rect x="10" y="10" width="80" height="40" fill="#4A90E2"/>
+  <text x="50" y="35" text-anchor="middle" fill="#fff">Hello</text>
+</svg>
+EOF
+
+# 从文件读取并更新
+lark-cli whiteboard +update \
+  --whiteboard-token <画板Token> \
+  --input_format svg \
+  --source @./diagram.svg \
+  --overwrite --as user
+```

package/skills/lark-whiteboard/references/lark-whiteboard-workflow.md

@@ -0,0 +1,94 @@
+# 画板创作/修改工作流
+
+## 创作 Workflow
+
+> 此 workflow 用于**独立创作一个画板**。
+> 需要在文档中批量创建多个画板时，由 lark-doc 负责调度，见 `lark-doc` 技能的 `references/lark-doc-whiteboard.md`。
+
+**Step 1：获取 board_token**
+
+| 用户给了什么 | 怎么获取 |
+|---|---|
+| 直接给了 whiteboard token（`wbcnXXX`）| 直接使用 |
+| 文档 URL 或 doc_id，文档中已有画板 | `lark-cli docs +fetch --doc <URL> --as user`，从返回的 `<whiteboard token="xxx"/>` 提取 |
+| 文档 URL 或 doc_id，需要新建画板 | `lark-cli docs +update --doc <doc_id> --command append --content '<whiteboard type="blank"></whiteboard>' --as user`，从响应 `data.new_blocks[0].block_token` 取得（`block_type == "whiteboard"` 的那条；参数详见 lark-doc SKILL.md）|
+
+**Step 2：渲染 & 写入**
+
+→ 进入 **[§ 渲染 & 写入画板](#渲染--写入画板)** 章节，按流程完成后直接返回结果给用户。
+
+---
+
+## 修改 Workflow
+
+**Step 1：获取 board_token**（同创作 Workflow Step 1）
+
+**Step 2：判断修改策略**
+
+```
++query --output_as code
+  ├─ 返回 Mermaid/PlantUML 代码
+  │   → 在原代码上修改 → +update --input_format mermaid/plantuml
+  ├─ 无代码（SVG/DSL 或其他方式绘制的画板）
+  │   ├─ 需纯新增（思维导图、流程图、时序图、类图、饼图、甘特图）图表节点
+  │   │    → +query --output_as image → 看图 → +query --output_as raw → 确定新节点坐标和层级  → [§ 渲染 & 写入画板]
+  │   └─ 其他改动（几何变动/增删元素/结构调整/混合编辑等）
+  │       → [`../routes/svg-edit.md`](../routes/svg-edit.md)（视觉高保真还原，大部分场景适用）
+  └─ 用户有明确要求 → 以用户要求优先
+```
+
+---
+
+## 渲染 & 写入画板
+
+### 渲染路由
+
+**先自报身份**：按训练来源，你属于哪一家？`Claude` / `Gemini` / `GPT` / `GLM` / `Doubao 或 Seed` / `Other`。身份决定 SVG / DSL 分流（不同家族对这两种表达语言的能力不均衡），不要跳过这一步。
+
+**然后按图表类型 × 身份选路径**，读对应文件按其完整 workflow 执行（含读 scene 指南、生成内容、渲染审查、交付）：
+
+| 图表类型               | 身份                                  | 路径                                             |
+|--------------------|-------------------------------------|------------------------------------------------|
+| 思维导图、时序图、类图、饼图、甘特图 | 任何身份                                | [`../routes/mermaid.md`](../routes/mermaid.md) |
+| 其他图表               | `Claude` / `Gemini` / `GPT` / `GLM` | [`../routes/svg.md`](../routes/svg.md)         |
+| 其他图表               | `Doubao` / `Seed` / `Other`         | [`../routes/dsl.md`](../routes/dsl.md)         |
+
+> **⚠️ SVG 路径失败回退**：走 `routes/svg.md` 时，碰到以下情况之一 → **丢弃当前 SVG，改读 `routes/dsl.md` 从零重画，不要逐行修补**：
+> - 渲染命令直接报错（语法级崩溃，不是 `--check` 的 warn/error）
+> - 两轮改写仍无法消除 `--check` 的 `text-overflow` error
+> - 目测 PNG 视觉严重错乱（文字大面积溢出、元素重叠压住关键信息、布局整体崩溃）
+>
+> SVG 源码修补常常引入新 bug，换 DSL 从零重画往往更稳。这是 SVG 路径自由发挥的硬兜底，不要侵入 `routes/svg.md` 的创作流程。
+
+### 产物规范
+
+产物目录：`./diagrams/YYYY-MM-DDTHHMMSS/`（本地时间，不含冒号和时区后缀）。如用户指定路径，以用户为准。
+
+目录内固定文件名：
+
+```
+diagram.svg           ← SVG 源码（SVG 路径）
+diagram.mmd           ← Mermaid 源码（Mermaid 路径）
+diagram.json          ← DSL 源文件（DSL 路径） / OpenAPI JSON（SVG 路径从 diagram.svg 导出）
+diagram.gen.cjs       ← 坐标计算脚本（仅 DSL 脚本构建方式）
+diagram.png           ← 渲染结果
+```
+
+### 写入画板
+
+> 关于 --overwrite
+> 画板更新命令中，若不携带 --overwrite flag，则是增量更新画板内容，若画板内已有内容的话，新增内容可能会和已有内容重叠，导致问题。
+> 因此，若需要整体更新画板内容，需携带 --overwrite flag 覆盖式更新。
+
+```bash
+npx -y @larksuite/whiteboard-cli@^0.2.12 -i <产物文件> --to openapi --format json \
+  | lark-cli whiteboard +update \
+    --whiteboard-token <Token> \
+    --source - --input_format raw \
+    --idempotent-token <10+字符唯一串> \
+    --as user \
+    --overwrite
+```
+
+> `--idempotent-token` 最少 10 字符，建议用时间戳+标识拼接（如 `1744800000-board-1`），避免重试导致重复写入。
+> 如需应用身份上传，将 `--as user` 替换为 `--as bot`。

package/skills/lark-whiteboard/routes/dsl.md

@@ -0,0 +1,107 @@
+# DSL 路径
+
+> **这是画板，不是网页。** 画板是无限画布上自由放置元素，flex 布局是可选增强。
+
+## Workflow
+
+```
+Step 1: 路由 & 读取知识
+  - 读对应 scene 指南 — 了解结构特征和布局策略
+  - 确定布局策略（见下方快速判断）和构建方式
+  - 读 elements/ 核心模块 — 语法、布局、配色、排版、连线
+
+Step 2: 生成完整 DSL（含颜色）
+  - 按 content.md 规划信息量和分组
+  - 按 layout.md 选择布局模式和间距
+  - 推荐使用图标让图表更直观，运行 `npx -y @larksuite/whiteboard-cli@^0.2.12 --icons` 查看可用图标
+  - 按 style.md 上色（用户没指定时用默认经典色板）
+  - 按 schema.md 语法输出完整 JSON
+  - 连线参考 connectors.md，排版参考 typography.md
+
+  注意：部分图形（鱼骨/飞轮/柱状/折线等）要按 scene 指南的脚本模板写 CommonJS 脚本生成 JSON：
+    1. 创建产物目录 ./diagrams/YYYY-MM-DDTHHMMSS/
+    2. 将脚本保存为 diagram.gen.cjs（必须 .cjs 后缀，脚本用 require() 写，.js 在 ESM 项目下会崩），执行 node diagram.gen.cjs 产出 diagram.json
+    3. 用产出的 diagram.json 进入 Step 3
+
+Step 3: 渲染 & 审查 → 交付
+  - 渲染前自查（见下方检查清单）
+  - 渲染 PNG（仅用于预览验证，不是最终产物）：npx -y @larksuite/whiteboard-cli@^0.2.12 -i diagram.json -o diagram.png
+  - 检查：信息完整？布局合理？配色协调？文字无截断？连线无交叉？
+  - 有问题 → 按症状表修复 → 重新渲染（最多 2 轮）
+  - 2 轮后仍有严重问题 → 考虑走 Mermaid 路径兜底
+  - 写入画板：用 whiteboard-cli 将 diagram.json 转换为 OpenAPI 格式并 pipe 给 +update：
+      npx -y @larksuite/whiteboard-cli@^0.2.12 -i diagram.json --to openapi --format json \
+        | lark-cli whiteboard +update --whiteboard-token <board_token> \
+            --source - --input_format raw --idempotent-token <时间戳+标识> --as user
+      → 完整 dry-run / 确认流程见 SKILL.md [§ 写入画板](../SKILL.md#写入画板)
+  - 交付：向用户报告 board_token 写入成功
+```
+
+**布局策略快速判断**（详见 `elements/layout.md`）：
+
+先定**主布局**，再定子布局：**结构化信息**优先用 Flex，**关系链路**优先用 Dagre，**灵活定位**用绝对布局。
+
+> **构建方式是强约束**：当 scene 指南要求"脚本生成"时，必须先写脚本（`.cjs`，CommonJS）并用 `node` 执行来产出 JSON 文件。
+
+## 模块索引
+
+### 核心参考（必读）
+
+| 模块     | 文件                         | 说明                            |
+| -------- |----------------------------| ------------------------------- |
+| DSL 语法 | `elements/schema.md`       | 节点类型、属性、尺寸值          |
+| 内容规划 | `elements/content.md`    | 信息提取、密度决策、连线预判    |
+| 布局系统 | `elements/layout.md`     | 网格方法论、Flex 映射、间距规则 |
+| 排版规则 | `elements/typography.md` | 字号层级、对齐、行距            |
+| 连线系统 | `elements/connectors.md` | 拓扑规划、锚点选择              |
+| 配色系统 | `elements/style.md`      | 多色板、视觉层级                |
+
+### 场景指南（按类型选读一个）
+
+| 图表类型    | 文件                     | 适用场景                               |
+| ----------- | ------------------------ | -------------------------------------- |
+| 架构图      | `scenes/architecture.md` | 分层架构、微服务架构                   |
+| 组织架构图  | `scenes/organization.md` | 公司组织、树形层级                     |
+| 泳道图      | `scenes/swimlane.md`     | 跨角色流程、跨系统交互流程             |
+| 对比图      | `scenes/comparison.md`   | 方案对比、功能矩阵                     |
+| 鱼骨图      | `scenes/fishbone.md`     | 因果分析、根因分析                     |
+| 柱状图      | `scenes/bar-chart.md`    | 柱状图、条形图                         |
+| 折线图      | `scenes/line-chart.md`   | 折线图、趋势图                         |
+| 树状图      | `scenes/treemap.md`      | 矩形树图、层级占比                     |
+| 漏斗图      | `scenes/funnel.md`       | 转化漏斗、销售漏斗                     |
+| 金字塔图    | `scenes/pyramid.md`      | 层级结构、需求层次                     |
+| 循环/飞轮图 | `scenes/flywheel.md`     | 增长飞轮、闭环链路                     |
+| 里程碑      | `scenes/milestone.md`    | 时间线、版本演进                       |
+| 流程图      | `scenes/flowchart.md`    | 业务流、状态机、带条件判断的链路       |
+| 图片展示    | `scenes/photo-showcase.md` | 用户显式要求图片/配图/插图时（需先完成 `elements/image.md` 的图片准备） |
+
+## 渲染前自查
+
+- [ ] 不同分组用了不同颜色？同组节点样式完全一致？
+- [ ] 外层浅色背景、内层白色节点？
+- [ ] 所有节点有边框（borderWidth=2）？文字在背景上清晰可读？
+- [ ] 连线用灰色（#BBBFC4），不用彩色？
+- [ ] frame 都写了 layout 属性？gap 和 padding 都显式设置了？
+- [ ] 含文字节点 height 用 fit-content？connector 在顶层 nodes 数组？
+
+## 症状→修复表
+
+| 看到的问题         | 改什么                              |
+| ------------------ | ----------------------------------- |
+| 文字被截断         | height 改为 fit-content             |
+| 文字溢出容器右侧   | 增大 width，或缩短文字              |
+| 节点重叠粘连       | 增大 gap                            |
+| 节点挤成一团       | 增大 padding 和 gap                 |
+| 连线穿过节点       | 调整 fromAnchor/toAnchor 或增大间距 |
+| 大面积空白         | 缩小外层 frame 宽度                 |
+| 文字和背景色太接近 | 调整 fillColor 或 textColor         |
+| 布局整体偏左/偏右  | 调整绝对定位的 x 坐标使内容居中     |
+
+## 关键约束速查
+
+1. **含文字节点的 height 必须用 `'fit-content'`** — 写死数值会截断文字
+2. **`fill-container` 仅在 flex 父容器中生效** — `layout: 'none'` 下宽度退化为 0
+3. **`layout: 'none'` 的容器必须有固定宽高** — 不要写成 `fit-content`
+4. **connector 必须放在顶层 nodes 数组** — 不能嵌套在 frame children 里
+5. **flex 容器内的 x/y 会被完全忽略** — 需要自由定位时用 `layout: 'none'`
+6. **Dagre 子容器默认为不透明节点** — 需穿透时声明 `layout: "dagre"` + `layoutOptions: { isCluster: true }`

package/skills/lark-whiteboard/routes/mermaid.md

@@ -0,0 +1,27 @@
+# Mermaid 路径
+
+适用于：思维导图、时序图、类图、饼图、甘特图。
+
+## Workflow
+
+```
+Step 1: 读取知识
+  - 读 scenes/mermaid.md — Mermaid 语法和使用方式
+
+Step 2: 生成 Mermaid
+  - 按 mermaid.md 的语法编写 .mmd 文件
+  - 只输出纯 Mermaid 语法文本
+
+Step 3: 渲染验证 & 写入画板 & 交付
+  1. 创建产物目录 ./diagrams/YYYY-MM-DDTHHMMSS/
+  2. 保存为 diagram.mmd
+  3. 渲染（仅用于预览验证，PNG 不是最终产物）：
+       npx -y @larksuite/whiteboard-cli@^0.2.12 -i diagram.mmd -o diagram.png
+  4. 审查 PNG，有问题修改后重新渲染（最多 2 轮）
+  5. 写入画板：用 whiteboard-cli 将 diagram.mmd 转换为 OpenAPI 格式并 pipe 给 +update：
+       npx -y @larksuite/whiteboard-cli@^0.2.12 -i diagram.mmd --to openapi --format json \
+         | lark-cli whiteboard +update --whiteboard-token <board_token> \
+             --source - --input_format raw --idempotent-token <时间戳+标识> --as user
+       → 完整 dry-run / 确认流程见 SKILL.md [§ 写入画板](../SKILL.md#写入画板)
+  6. 交付：向用户报告 board_token 写入成功
+```

package/skills/lark-whiteboard/routes/svg-edit.md

@@ -0,0 +1,85 @@
+# SVG 编辑路径
+
+通过导出画板的 SVG → 编辑 SVG → 回写画板，实现对已有画板的可视化编辑。
+
+---
+
+## ⚠️ 有损性警告
+
+SVG 导出是**纯视觉快照**，再次导入后画板语义（思维导图层级/表格结构/连线绑定/容器类型/mention/节点 ID/锁定/评论）会丢失。
+
+**保留的信息**：形状几何（位置/大小/路径）、文本内容与基本格式（字号/粗体/斜体/对齐）、填充色/描边色/透明度（线性渐变降级为第一个 stop-color 纯色）、连接器路径形状与箭头样式、`<g>` 嵌套的基本分组关系（≥2 子元素时重建为 DirectFocusGroup）。
+
+---
+
+## Workflow
+
+### 0. 用户确认（强制）
+
+在执行任何编辑前，**必须**向用户说明：
+
+> SVG 编辑只保证视觉层面对齐，画板语义（层级/节点类型/思维导图结构/表格结构/连线绑定/容器类型/mention 等）将不可恢复，是否继续？
+
+**用户未确认前不得执行后续步骤。**
+
+### 1. 导出当前画板 SVG
+
+```bash
+lark-cli whiteboard +query \
+  --whiteboard-token <TOKEN> \
+  --output_as svg \
+  --output <dir>/original.svg \
+  --as user
+```
+
+### 2. 编辑 SVG
+
+在导出的 SVG 上进行修改。参考 [`svg.md` § 画板怎么处理 SVG](./svg.md#画板怎么处理-svg) 了解可识别元素与不支持的装饰特性。
+
+**技术约束**：
+- 新增文字必须用 `<text>`（不是 `<path>`），容器宽度留够（CJK ≈ 1em / Latin ≈ 0.6em）
+- 避免 `skewX` / `skewY` / `matrix(...)` 变换
+- 禁止使用 `<radialGradient>` / `<filter>` / `<pattern>` / `<clipPath>` / `<mask>`
+
+**编辑原则**（区别于从零创作）：
+
+- **风格一致**：新增/修改元素应匹配导出 SVG 中已有的配色、字号、线宽、间距风格，不引入突兀的视觉差异
+- **最小改动**：只修改用户要求的部分，不主动"优化"或重排无关区域
+- **结构稳定**：尽量保留原有 `<g>` 层级结构，避免不必要的重组导致分组关系变化
+- **连线协调**：连接器端点绑定已丢失，若移动了形状，必须手动同步调整视觉上连接到该形状的 connector path 端点坐标，否则连线会"断开"
+- **内部引用完整性**：不要随意删改 `<defs>` 中被 `url(#id)` 引用的元素（`<marker>`/`<linearGradient>` 等）或修改其 `id`，否则引用方会失效
+
+### 3. 渲染审查
+
+```bash
+# 渲染 PNG 预览
+npx -y @larksuite/whiteboard-cli@^0.2.12 -i <dir>/edited.svg -o <dir>/edited.png -f svg
+
+# 几何检查（text-overflow / node-overlap）
+npx -y @larksuite/whiteboard-cli@^0.2.12 -i <dir>/edited.svg -f svg --check
+```
+
+结合 PNG 视觉效果和 `--check` 报告进行调整，有问题则修改 SVG 后重新渲染（最多 2 轮）。
+- SVG 本地渲染预览时，画板中的图片因 session 原因无法正常显示，属于预期内的行为。
+
+### 4. 写回画板
+
+`--overwrite` 会清空原画板内容，确认后再执行
+
+```bash
+# dry-run 探测
+lark-cli whiteboard +update \
+  --whiteboard-token <TOKEN> \
+  --source @<dir>/edited.svg \
+  --input_format svg \
+  --idempotent-token <10+字符唯一串> \
+  --overwrite --dry-run --as user
+
+# 用户确认后执行
+lark-cli whiteboard +update \
+  --whiteboard-token <TOKEN> \
+  --source @<dir>/edited.svg \
+  --input_format svg \
+  --idempotent-token <10+字符唯一串> \
+  --overwrite --as user
+```

package/skills/lark-whiteboard/routes/svg.md

@@ -0,0 +1,54 @@
+# SVG 路径
+
+你在设计一张专业的信息图——内容扎实, 美观漂亮, 具有设计感和视觉张力, 不是枯燥的布局和文字堆砌, **不要做的像普通的网页或者千篇一律的模版**
+最终交付是**画板跨越重排渲染的节点**(你写 SVG → 画板解析)
+
+**核心心智纠正 (重要)**：
+- 大多数 AI 如果只考虑“绝对不报错/完美映射”, 最终给出的都是全篇纯白底色加单层 `<rect>` 的方正卡片网格, 极其死板单调, **这将被视为不及格！**
+- **SVG 给你了完全的设计自由**, 请大胆使用你脑内的图标路径 (`<path>`), 连接指引 (`流畅的 <path>`), 各种环境氛围点缀, 大胆一点, 充分信任你的品味, 发挥出你的顶级艺术创造力！
+
+## Workflow
+
+### 1. 想清楚要画什么
+
+- **核心信息是什么？** 能做到一图胜千言, 绝对不要只生成平平无奇的文字表格, 要有设计感
+- **内容充实度**：如果用户描述稀疏简略, 利用你的领域知识扩展, 保证信息维度和内容充实, 但不要过度堆砌, 淹没重点
+- **视觉层级与隐喻**：这个没有固定的形式, 你自由判断, 比如: 给重要的节点加光环, 加高亮背景；给对比项设计天平或对称结构
+
+### 2. 写 SVG
+
+[!IMPORTANT] 布局, 配色, 信息密度, 装饰物——**全部由你判断**, 打破单调的 `<rect>` 牢笼, 严禁通篇用矩形和文字应付用户
+
+操作边界约束：
+- **语言跟随用户**：图表文字的语言与用户 prompt 保持一致, 技术术语用行业里通用的写法, 不机械翻译
+- 文字用 `<text>`(不是 `<path>`), 容器宽度留够——画板按 CJK ≈ 1em / Latin ≈ 0.6em 重排
+- 连线使用正交折线替代斜直线(`<polyline>` 带水平/垂直折点)视觉效果更好
+- 可自由使用 `translate`, `rotate`, `scale`但请尽量避免使用 `skewX` / `skewY` / `matrix(...)` 发生空间级扭曲
+
+### 3. 渲染审查
+
+```
+建目录   ./diagrams/YYYY-MM-DDTHHMMSS/         (例：./diagrams/2026-04-15T143022/)
+写文件   <dir>/diagram.svg
+渲染     npx -y @larksuite/whiteboard-cli@^0.2.12 -i <dir>/diagram.svg -o <dir>/diagram.png -f svg
+检查     npx -y @larksuite/whiteboard-cli@^0.2.12 -i <dir>/diagram.svg -f svg --check
+导出     npx -y @larksuite/whiteboard-cli@^0.2.12 -i <dir>/diagram.svg -f svg --to openapi --format json > <dir>/diagram.json
+```
+
+`npx -y @larksuite/whiteboard-cli@^0.2.12 --check` 检测 `text-overflow` 和 `node-overlap`, 并结合视觉效果(查看 PNG)进行调整
+
+## 画板怎么处理 SVG
+
+画板的 svg-parser 把可识别元素转成可编辑节点, 其余降级为内嵌图片(渲染没问题, 虽然不可编辑, 但是可以正常显示)；但 `<radialGradient>` / `<filter>` / `<clipPath>` 等装饰特性画板完全不支持，会导致渲染问题（见下方⚠️）
+**不需要所有元素都可编辑, 但必须避免使用不支持的装饰特性, 且要兼顾可编辑和美观漂亮**
+
+**可识别的元素**
+
+- 形状：`<rect>` / `<circle>` / `<ellipse>` / `<polygon>`
+- 连线：`<line>` / `<polyline>` / `<path>`(自动识别为直线 / 折线 / 曲线)
+- 文本：`<text>` / `<tspan>` 画板硬编码 Noto Sans SC **文字必须用 `<text>`**
+- 分组：`<g>` / `<a>` / `<use>` 引用 `<symbol>`
+- 变换：`translate` / `rotate` / `scale` 正常；`skewX` / `skewY` / `matrix(...)` 降级
+
+**⚠️ [!IMPORTANT] 不支持的装饰特性**
+- `<radialGradient>` / `<filter>` / `<pattern>` / `<clipPath>` / `<mask>` → 画板都不支持，**请避免使用，否则会导致画板渲染问题**