@amaster.ai/pi-lark 0.1.2-beta.52 → 0.1.2-beta.54

package/skills/lark-slides/references/lark-slides-edit-workflows.md

@@ -1,6 +1,6 @@
 # 编辑已有 PPT：读-改-写闭环
 
-局部编辑走 **shortcut [`+replace-slide`](lark-slides-replace-slide.md)**（块级替换 / 插入），配合 `xml_presentation.slide.get` 读原页拿 `block_id`。一页改动很多、要改背景或删除若干元素，以及一页或多页的整页重建，走 **[`+replace-pages`](lark-slides-replace-pages.md)**，保持原 presentation 链接不变。
+局部编辑走 **shortcut [`+replace-slide`](lark-slides-replace-slide.md)**（块级替换 / 插入），配合 `xml_presentation.slide.get` 读原页拿 `block_id`。整页重建走 **[`+update-slide`](lark-slides-update-slide.md)**，多页就每页各跑一次 —— 它原地覆盖并保留 `slide_id` 和页序；只有写进 `--content` 且带原 id 的元素才会保留元素 id，遗漏的元素会被删除。
 
 > 生成 XML 前**必读** [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。
 
@@ -11,7 +11,7 @@
 | 已知某块的 `block_id`，要换这块内容（改标题、换图、挪坐标） | `block_replace` | 精准替换，原子性好；`replacement` 根 `id` 由 CLI 自动注入为 `block_id` |
 | 只加 1~N 个元素、不动现有布局 | `block_insert` | 新增不覆盖，可选 `insert_before_block_id` 指定位置 |
 | 一次动多个元素（如：换标题 + 加图） | 单次 `--parts` 里拼多条 | 整批作为原子事务，任一失败整批不生效；`block_replace` 和 `block_insert` 可混用 |
-| 单页或多页版式重建、整页坐标重排、改页面背景、删除若干元素 | `+replace-pages` | 原 presentation 内按页 create-before/delete-old，不生成新 Slides 链接 |
+| 整页版式重建、整页坐标重排、改页面背景、删若干元素 | `+update-slide`（每页一次） | 原地整页覆盖，`slide_id` 和页序不变；带原 `id` 的元素保留 id，不带 `id` 的作为新元素插入，遗漏的被删除 |
 
 > **没有字段级 patch**：即便只想改一个 `shape` 的 `topLeftX`，也得把整个块的新 XML 写出来用 `block_replace`。这不是"微调"，是块级重写。
 
@@ -105,10 +105,7 @@ lark-cli slides +replace-slide --as user \
 ```bash
 lark-cli slides +replace-slide --as user \
   --presentation "$PID" --slide-id "$SID" \
-  --parts '[
-    {"action":"block_replace","block_id":"bab","replacement":"<shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新标题</p></content></shape>"},
-    {"action":"block_insert","insertion":"<img src=\"<file_token>\" topLeftX=\"700\" topLeftY=\"400\" width=\"180\" height=\"100\"/>"}
-  ]'
+  --parts '[{"action":"block_replace","block_id":"bab","replacement":"<shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新标题</p></content></shape>"},{"action":"block_insert","insertion":"<img src=\"<file_token>\" topLeftX=\"700\" topLeftY=\"400\" width=\"180\" height=\"100\"/>"}]'
 ```
 
 整批作为原子事务：任一条失败整批不生效。失败时后端通常返回 3350001；若响应中带 `failed_part_index` / `failed_reason` 字段，shortcut 会原样透传。
@@ -139,7 +136,7 @@ cat parts.json | lark-cli slides +replace-slide --as user --presentation "$PID"
 ## 相关文档
 
 - [lark-slides-replace-slide.md](lark-slides-replace-slide.md) — +replace-slide shortcut 参数详情
-- [lark-slides-replace-pages.md](lark-slides-replace-pages.md) — 单页或多页整页重建 shortcut
+- [lark-slides-update-slide.md](lark-slides-update-slide.md) — +update-slide shortcut 参数详情（整页覆盖）
 - [lark-slides-xml-presentation-slide-get.md](lark-slides-xml-presentation-slide-get.md) — slide.get 参考（拿 `block_id` / `revision_id`）
 - [lark-slides-xml-presentation-slide-replace.md](lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考（一般直接用 shortcut 即可）
 - [lark-slides-media-upload.md](lark-slides-media-upload.md) — 上传图片拿 file_token

package/skills/lark-slides/references/lark-slides-update-slide.md

@@ -0,0 +1,146 @@
+# slides +update-slide（整页更新已有页面）
+
+把一整页 XML 交给某个已有页面，页面变成 `--content` 描述的样子。`slide_id` 和页序都不变。
+
+## 命令
+
+```bash
+# 标准用法：整页 XML 从文件读（推荐：避免 shell 转义和长参数截断）
+lark-cli slides +update-slide --as user \
+  --presentation "https://xxx.larkoffice.com/slides/SCtZ...ynae" \
+  --slide-id "piy" \
+  --content @page.xml
+
+# XML 从 stdin 读
+cat page.xml | lark-cli slides +update-slide --as user \
+  --presentation "$PRES" --slide-id "$SLIDE" --content -
+
+# wiki 链接直接传（CLI 自动解析并校验 obj_type=slides）
+lark-cli slides +update-slide --as user \
+  --presentation "https://xxx.larkoffice.com/wiki/wikcn..." \
+  --slide-id "piy" --content @page.xml
+
+# 预览请求，不实际写入
+lark-cli slides +update-slide --as user \
+  --presentation "$PRES" --slide-id "$SLIDE" --content @page.xml --dry-run
+```
+
+## 参数
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--presentation` | 是 | `xml_presentation_id`、`/slides/` URL 或 `/wiki/` URL |
+| `--slide-id` | 是 | 要整页替换的页面 `slide_id` |
+| `--content` | 是 | 这一页的完整目标 XML，单一 `<slide>` 根；支持字面量、`@file`、stdin `-`。别名：`--xml` / `--slide-xml` / `--slide-content` / `--content-xml` |
+| `--revision-id` | 否 | 默认 `-1`（最新）。它只选择服务端执行所基于的快照，不是“页面有新编辑就拒绝”的乐观锁；传旧版本号会以旧快照重建页面并丢弃其后的编辑 |
+| `--tid` | 否 | 调用方提供的任务/事务标识，CLI 原样透传；用于关联同一编辑任务或重试，不等同于版本前置条件，不能单独保证并发冲突时拒绝写入。一般留空 |
+
+`@file` 和 `+xml-get --output` 一样**只接受当前目录下的相对路径**，绝对路径会被拒。
+命令别名：`slides +update`（隐藏）；服务别名：`lark-cli slide …` 等价于 `lark-cli slides …`。
+
+如果要求“从读取之后页面一旦变化就不再写入”，不能只传 `--revision-id` 或 `--tid`。写入前必须再次用 `+xml-get` 回读最新版，比较读取期间是否发生变化；有变化时先基于最新版重新合并本次修改，再执行整页写回。当前 shortcut 不提供严格的 compare-and-swap 保证。
+
+## 语义：`--content` 就是这一页的最终状态
+
+**没写进 `--content` 的东西会从页面上消失。** 这不是补丁，是整页覆盖。
+
+| 你在 `--content` 里怎么写 | 页面上的结果 |
+|---|---|
+| 元素带原来的 `id` | 按新 XML 更新这个元素 |
+| 元素不带 `id` | 作为新元素插入到它所在的位置 |
+| 原来有、`--content` 里没有的元素 | **删除** |
+| `<style>` 改了 | 背景等页面样式跟着改 |
+| 没写 `<note>` | 讲者备注被清空 |
+
+一次请求就能同时做完改样式、插入、删除、换备注、换背景——这是 `+replace-slide` 逐元素 part 做不到的（它没法寻址背景，也没有 move 操作）。
+
+## 标准读-改-写流程
+
+```bash
+# 1. 读回当前页（拿到带 id 的完整 XML）
+lark-cli slides +xml-get --as user \
+  --presentation "$PRES" --slide-id "$SLIDE" --output page.xml
+
+# 2. 编辑 page.xml —— 保留想留下的元素的 id，删掉不要的整段，新元素不写 id
+
+# 3. 整页写回
+lark-cli slides +update-slide --as user \
+  --presentation "$PRES" --slide-id "$SLIDE" --content @page.xml
+```
+
+先 `--dry-run` 看请求，确认无误再执行。
+
+> ⚠️ **第 1 步不要加 `--remove-attr-id`。** 那个参数会把所有元素的 `id` 去掉，再交给 `+update-slide` 的话，每个元素都会被当成新元素插入、原来的全部被删除——页面看起来一样，但所有元素换了新 id，锚在旧 id 上的评论和 block 直达链接全部失效，而且**不会有任何报错**。`--remove-attr-id` 只用于只读查看。
+
+## 命令校验与空页限制
+
+| 情况 | 报错 |
+|---|---|
+| 根元素不是 `<slide>`（例如直接给了 `<shape>`） | `--content root must be <slide>` → 改单个元素请用 `+replace-slide` |
+| 根 `id` 和 `--slide-id` 不一致 | 拒绝。这通常是 A 页的 XML 要写到 B 页 —— 会毁掉 B 页 |
+| 根 `id` 缺失 | 自动补上 `--slide-id`，不报错 |
+| 根标签带命名空间前缀（`<sml:slide>`） | 拒绝。页面 id 没法贴到带前缀的标签上；写成 `<slide>`，需要命名空间就用默认 `xmlns` |
+| `<slide>` 之后还有第二个根元素或多余文本 | 拒绝。服务端解析会静默丢掉它们 |
+| XML 不合法 | 拒绝，带上出错位置 |
+| `<slide/>`（自闭合，空页） | 命令本身可以解析，但提交前的强制版式 lint 会报 `blank_slide`；按本 Skill 不得调用接口提交空页 |
+
+标为“拒绝”的情况由命令校验拦截，**不会发出任何请求**；空页则必须在调用命令前由强制版式 lint 拦截。
+
+## 什么时候不要用它
+
+- **只改一个元素** → 用 [`+replace-slide`](lark-slides-replace-slide.md)，一条 `block_replace` part 更省，也不用带上整页
+- **要改多个页面** → 对每一页各跑一次本命令
+- **要新建页面** → `slides +create` 或 `xml_presentation.slide create`
+
+## 提交前与写入后验证
+
+和其他整页写入一样，把 `--content` 存成本地文件后先跑版式 lint。先取得当前已加载 `lark-slides/SKILL.md` 的父目录，记为 `<lark-slides-skill-dir>`；不要猜测全局安装路径：
+
+```bash
+python3 "<lark-slides-skill-dir>/scripts/xml_text_overlap_lint.py" --input page.xml
+```
+
+`summary.error_count` 必须为 0 才调接口；`warning_count > 0` 时写完要截图复核。
+
+写入成功后，必须回读整份演示文稿的最新 XML，而不是只相信写接口的成功响应：
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "$PRES" --output readback.xml
+```
+
+按当前已加载 `lark-slides/SKILL.md` 指向的 [validation-checklist.md](validation-checklist.md) 完成验证：核对总页数、目标页和关键元素（包括需要保留的 ID、文本、背景与备注），并对回读 XML 运行同一版式 lint；发现差异时先停止后续写入并重新基于最新版处理。
+
+## 成功输出
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "xml_presentation_id": "slides_example_presentation_id",
+    "slide_id": "piy",
+    "revision_id": 43
+  }
+}
+```
+
+| `data` 下的字段 | 说明 |
+|------|------|
+| `xml_presentation_id` | 实际写入的演示文稿 ID |
+| `slide_id` | 与传入相同——整页覆盖不换页 id |
+| `revision_id` | 写入后的新版本号 |
+
+服务端拒绝这次写入时（`failed_reason` 非空）**不会**返回成功输出，而是报错并带上原因——单个 part 承载整页，任何失败都意味着页面没被写入。
+
+- 原因包含 `not found`：先检查 `--presentation` 和 `--slide-id`，再用 `slides +xml-get` 回读当前页面 ID。页面可能已删除，或 ID 来自另一份演示文稿。
+- 其他 invalid-parameter 错误：检查 `--content` 中不支持的元素、缺少 `<content/>` 的 `<shape>`，以及超出 960×540 的坐标。
+
+## 常见错误
+
+| 现象 | 原因 | 解决 |
+|------|------|------|
+| 3350001，原因包含 `not found` | `--presentation` 不匹配，或 `--slide-id` 对应的页面已被删除 | 检查 `--presentation` 和 `--slide-id`，再用 `slides +xml-get` 回读当前页面 ID |
+| 3350001，其他 invalid param | `--content` 的 XML 结构有问题（如 `<shape>` 缺 `<content/>`、包含服务端不支持的元素） | 按 [troubleshooting.md](troubleshooting.md) 检查 `--content` 的 XML 结构 |
+| 3350002 not found | `--revision-id` 传了不存在的版本号 | 用 `-1` 或真实存在的 `revision_id` |
+| 1061004 / 403 | 当前身份对这份 PPT 没有编辑权限 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope；wiki 链接另需 `wiki:node:read`；`--as bot` 还要求该 bot 对目标 PPT 有编辑权限 |

package/skills/lark-slides/references/lark-slides-xml-presentations-get.md

@@ -2,13 +2,12 @@
 
 ## 用途
 
-读取飞书幻灯片（PPT）演示文稿的完整 XML 内容信息。
+读取飞书幻灯片（PPT）的完整演示文稿 XML，或通过 `--slide-id` / `--slide-number` 读取指定单页 XML。
 
 ## Shortcut
 
 使用 `slides +xml-get` shortcut，可以把 XML 保存到本地文件，避免终端输出被截断。
 
-
 ```bash
 lark-cli slides +xml-get --as user \
   --presentation "slides_example_presentation_id" \
@@ -23,7 +22,10 @@ lark-cli slides +xml-get --as user \
 | `--presentation` | string | 是 | 演示文稿的唯一标识符 |
 | `--revision-id` | integer | 否 | 版本号，`-1` 表示最新版本 |
 | `--output` | string | 否 | XML 保存路径，必须使用相对路径；省略时 XML 在 stdout 的 JSON envelope 中返回 |
-| `--remove-attr-id` | flag | 否 | 移除 XML id 属性后读取 |
+| `--raw` | flag | 否 | 直接把 XML 输出到 stdout，不包 JSON envelope；不能与 `--output`、`--jq` 或非 JSON `--format` 同时使用 |
+| `--slide-id` | string | 否 | 只读取指定 `slide_id` 的单页 XML；不能与 `--slide-number` 或 `--remove-attr-id` 同时使用 |
+| `--slide-number` | integer | 否 | 只读取指定的 1-based 页码；不能与 `--slide-id` 或 `--remove-attr-id` 同时使用 |
+| `--remove-attr-id` | flag | 否 | 仅全文读取可用；移除 XML id 属性后读取，不适合后续精确块编辑 |
 | `--json` | flag | 否 | `--format json` 的简写，json 为默认输出格式 |
 
 
@@ -36,6 +38,27 @@ lark-cli slides +xml-get --as user \
   --json
 ```
 
+### 读取单页并保存
+
+按页面 ID 和按页码二选一：
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --slide-id "slide_example_id" \
+  --output .lark-slides/plan/slides_example_presentation_id/slide.xml \
+  --json
+```
+
+### 直接输出 XML 到管道
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --slide-number 1 \
+  --raw
+```
+
 ### 指定版本读取
 
 ```bash

package/skills/lark-slides/references/slides_chart_demo.xml

@@ -1,4 +1,3 @@
-<?xml version="1.0" encoding="UTF-8"?>
 <presentation xmlns="https://www.larkoffice.com/sml/2.0" width="960" height="540">
   <title>原生图表 Chart Demo</title>
   <theme>

package/skills/lark-slides/references/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting
 
-本文件覆盖 lark-slides 的通用创建前自检、XML 排障和常见失败处理。命令专属问题优先看对应 reference，例如 `+replace-slide`、`+media-upload`、`xml_presentation.slide.create`。
+本文件覆盖 lark-slides 的通用创建前自检、XML 排障和常见失败处理。命令专属问题优先看对应 reference，例如 `+replace-slide`、`+media-upload`。
 
 ## XML Preflight
 
@@ -9,7 +9,7 @@
 - 特殊字符已转义：正文和标题里的 `&`、`<`、`>` 不能裸写；属性值里的裸 `&` 也必须写成 `&amp;`。
 - 属性引号安全：XML 属性、shell 引号、JSON 字符串包装之间没有互相打断。
 - 结构合法：`<slide>` 下只放 `<style>`、`<data>`、`<note>`，文本都在 `<content>` 内。
-- 图片路径正确：`<img src="@...">` 只在 `+create --slides` 的支持链路中使用；直接调用 `xml_presentation.slide.create` 必须先拿到 `file_token`。
+- 图片路径正确：`<img src="@...">` 占位符由 `+create` 和 `+add-slide` 处理。
 
 ## Failure Order
 
@@ -20,8 +20,8 @@
 3. 检查失败页是否含未转义字符：`Q&A -> Q&amp;A`，文本 `<` / `>` 写成 `&lt;` / `&gt;`，属性 URL `a=1&b=2 -> a=1&amp;b=2`。
 4. 检查标签闭合、属性引号、`<content>` 结构，以及 `<slide>` 直接子元素。
 5. 页面空白、溢出、重叠或越界时，按 [validation-checklist.md](validation-checklist.md) 运行 `xml_text_overlap_lint.py`；先修复所有 `error`，再对 `warning` 指向的页面和元素做截图复核。
-6. 如果使用 `--slides '[...]'`，怀疑 shell 截断时直接切到两步创建：先 `slides +create`，再用 `xml_presentation.slide.create` 逐页添加。
-7. 局部问题用 `+replace-slide` 块级修正；整页结构要改时再用 `slide.delete` 旧页 + `slide.create` 新页。
+6. 如果使用 `--slides '[...]'` 字面量，怀疑 shell 转义或截断时改用文件输入：`+create --slide @page-01.xml --slide @page-02.xml`。
+7. 局部问题用 `+replace-slide` 块级修正；整页结构要改时用 `+delete-slide` 删旧页 + `+add-slide` 建新页。
 
 ## Symptom Fixes
 
@@ -34,7 +34,7 @@
 | 表格列宽不合理 | 调整 `colgroup` 中 `col` 的 `width` 值 |
 | 图表没有显示 | 检查 `chartPlotArea` 和 `chartData` 是否都包含，`dim1` / `dim2` 数据数量是否匹配 |
 | 图片被裁掉一部分 | `<img>` 的 `width` / `height` 是裁剪后尺寸；要整图显示就让 `width:height` 对齐原图比例 |
-| 图片不显示 / `<img src>` 仍是 `@path` | `@` 占位符只在 `+create --slides` 中替换；直接调 `xml_presentation.slide.create` 必须先用 `+media-upload` 拿 `file_token` |
+| 图片不显示 / `<img src>` 仍是 `@path` | `@` 占位符由 `+create` 和 `+add-slide` 替换 |
 | 新插入的 `<img>` 挡住原有元素 | `slide.get` 读原页，对照已有块坐标挑空白位置；空间不够就在同一批 `--parts` 里先移动/缩小现有块再插图 |
 | 渐变背景变成白色 | 渐变必须用 `rgba()` 格式 + 百分比停靠点，如 `linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)` |
 | 整体风格不统一 | 封面页和结尾页用同一背景，内容页保持一致的配色和字号体系 |
@@ -45,7 +45,7 @@
 |--------------|------|----------|
 | 400 XML 格式错误 | XML 语法错误 | 检查标签闭合、属性引号、特殊字符转义 |
 | 400 请求包装错误 | `--data` 未按 schema 包装 | 检查是否传入 `xml_presentation.content` 或 `slide.content` |
-| 创建成功但页面空白 / 内容缺失 / 布局错乱 | 常见于 `--slides '[...]'` 的 shell 转义或长参数传递问题 | 改用两步创建，并在创建后立即读取 XML 验证 |
+| 创建成功但页面空白 / 内容缺失 / 布局错乱 | 常见于 `--slides '[...]'` 字面量的 shell 转义或长参数传递问题 | 改用 `--slide @file`（每页一个文件）或 `--slides @deck.json`，并在创建后立即读取 XML 验证 |
 | 403 权限不足 | scope 或文档权限不匹配 | 确认 scope 和文档权限；无权限时根据错误响应引导用户解决 |
 | 404 演示文稿不存在 | `xml_presentation_id` 不正确或无权限 | 检查 token；wiki URL 需先解析真实 `obj_token` |
 | 404 幻灯片不存在 | `slide_id` 不正确 | 重新读取 presentation 或 slide，确认最新 ID |

package/skills/lark-slides/references/validation-checklist.md

@@ -1,6 +1,6 @@
 # Validation Checklist
 
-创建或大幅改写演示文稿后，必须做一次显式验证。目标是发现空白页、XML 损坏、内容截断、明显溢出、弱视觉层级和未验证输出。
+创建、大幅改写演示文稿或每次通过 `slides +update-slide` 整页写回后，必须做一次显式验证。目标是发现空白页、XML 损坏、内容截断、明显溢出、弱视觉层级和未验证输出。
 
 小型已有页编辑也要做对应范围的验证：至少读取被改页面或全文 XML，确认目标元素已更新且未破坏周边结构。
 

package/skills/lark-slides/references/xml-schema-quick-ref.md

@@ -12,7 +12,6 @@
 ## 最小可用示例
 
 ```xml
-<?xml version="1.0" encoding="UTF-8"?>
 <presentation xmlns="https://www.larkoffice.com/sml/2.0" width="960" height="540">
   <slide>
     <data>
@@ -431,7 +430,6 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 ## 完整示例
 
 ```xml
-<?xml version="1.0" encoding="UTF-8"?>
 <presentation xmlns="https://www.larkoffice.com/sml/2.0" width="960" height="540">
   <title>季度报告</title>
   <theme>

package/skills/lark-whiteboard/SKILL.md

@@ -22,16 +22,23 @@ metadata:
 
 **身份**：画板操作默认使用 `--as user`。仅当需要以应用身份上传时使用 `--as bot`。
 
-| 用户需求                                    | 行动                                                                                                |
-|-----------------------------------------|---------------------------------------------------------------------------------------------------|
+> 先判断「只读还是写入」，再在对应表内按上到下匹配，**命中即停**。
+
+### A. 只读 · 查看 / 导出（不改画板）
+
+| 用户需求 | 行动 |
+|---|---|
 | 查看画板内容 / 导出图片 | [`+export --output-type preview`](references/lark-whiteboard-export.md)                       |
 | 导出 SVG 矢量图 | [`+export --output-type svg`](references/lark-whiteboard-export.md)                       |
-| 获取画板的 Mermaid/PlantUML 代码               | [`+export --output-type source`](references/lark-whiteboard-export.md)                             |
-| 检查画板是否由代码绘制                             | [`+export --output-type source`](references/lark-whiteboard-export.md)                             |
-| 仅微调节点文字/颜色                         | `+export --output-type raw` → 手动改 JSON → `+update --input_format raw`                             |
-| 用户**已提供** Mermaid/PlantUML/SVG 代码，或明确指定用该格式 | 自己生成/使用代码 → [`+update --input_format mermaid/plantuml/svg`](references/lark-whiteboard-update.md) |
-| 新建/创作复杂图表（架构/流程/组织等）                    | → **[§ 创作 Workflow](references/lark-whiteboard-workflow.md#创作-workflow)**                         |
-| 修改/重绘已有画板                               | → **[§ 修改 Workflow](references/lark-whiteboard-workflow.md#修改-workflow)**                         |
+| 提取画板的 Mermaid/PlantUML 源码 | [`+export --output-type source`](references/lark-whiteboard-export.md) |
+
+### B. 写入 · 创作 / 编辑（会改画板，命中即停）
+
+| 场景 | 行动 | 写入方式 | 对原内容 |
+|---|---|---|---|
+| 用户**已提供** Mermaid/PlantUML/SVG 代码，或明确指定用该格式 | 使用该代码 → [`+update`](references/lark-whiteboard-update.md)，`--input_format` 取单值 `mermaid` / `plantuml` / `svg`；写入非空已有画板并需要 overwrite 时，先确认会整板重建；若 SVG 用于修改已有画板，先走 [`routes/svg-edit.md`](routes/svg-edit.md) 有损确认 | overwrite / append | 按用户要求 |
+| 从零新建复杂图表（架构/流程/组织等） | → **[§ 创作 Workflow](references/lark-whiteboard-workflow.md#创作-workflow)** | 首次写入 | — |
+| 修改 / 增补已有画板 | → **[§ 编辑 Workflow](references/lark-whiteboard-workflow.md#编辑-workflow)** | 见该表 | 见该表 |
 
 ## Shortcuts
 

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

@@ -10,15 +10,16 @@
 |----------------------|----|------------------------------------------------------------------------|
 | `--whiteboard-token` | 是  | 画板 token，需要拥有画板的读权限                                                    |
 | `--output-type`      | 是  | 输出格式：`preview`（预览图片）、`svg`（SVG 矢量图）、`source`（PlantUML/Mermaid 代码）、`raw`（OpenAPI 原生画板节点格式） |
-| `--output`           | 否  | 输出路径。当 `--output-type preview` 时必填，推荐传入无后缀文件路径（如 `./preview`）；当 `--output-type svg/source/raw` 时可选，不填则直接输出到终端 |
+| `--output`           | 否  | 输出路径。当 `--output-type preview` 时必填；当 `--output-type svg/source/raw` 时可选，不填则直接输出到终端 |
 | `--overwrite`        | 否  | 覆盖已存在的文件，默认为 false                                                     |
 
 ## 输出格式
 
-- `preview`：预览图片。推荐 `--output ./preview` 这类无后缀文件路径，CLI 会按实际图片类型保存为 `./preview.png` 或 `./preview.jpg`。如果 `--output` 是目录，会保存为该目录下的 `whiteboard_<whiteboard-token>.png/.jpg`；如果显式写了后缀，需要和实际图片类型匹配。`--overwrite` 检查的是补齐后缀后的最终路径，例如返回 PNG 时 `--output ./preview` 对应覆盖 `./preview.png`。
+- `preview`：预览图片。保存时会根据接口实际返回的 `Content-Type` 决定扩展名，例如 `image/jpeg` 会保存为 `.jpg`。
 - `svg`：导出画板为标准 SVG 矢量图。可用于 SVG 编辑后回写画板（见 [`routes/svg-edit.md`](../routes/svg-edit.md)）。注意：导出为纯视觉快照，思维导图层级、表格结构、连接器绑定等语义信息会丢失。
 - `source`：PlantUML/Mermaid 代码。仅限画板内有且仅有一个 PlantUML/Mermaid 图时，才可导出代码，否则会在返回值中告知不存在/有多个节点。
-- `raw`：飞书 OpenAPI 原生画板节点格式。这一 json 格式不适合直接编辑复杂布局或内容，建议仅限于需要修改简单的文本内容/颜色等细节时使用。需要进行更复杂的设计/修改时，建议参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)。
+- `raw`：飞书 OpenAPI 原生画板节点格式。这一 json 格式不适合直接编辑复杂布局或内容，建议仅限于需要修改简单的文本内容/颜色等细节时使用。需要进行更复杂的设计/修改时，建议参考 [§ 编辑 Workflow](lark-whiteboard-workflow.md#编辑-workflow)。
+  - **需编辑后回写时，导出务必加 `--output <file>` 写入文件**：文件内容可直接作为 `+update` 的输入；直接输出到终端的结果会多一层 `{ ok, identity, data }` 包装，`+update` 无法解析。
 
 ## 示例
 

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

@@ -17,7 +17,7 @@
 |----------------------|----|--------------------------------------------|
 | `--whiteboard-token` | 是  | 画板 token，需要拥有画板的编辑权限                       |
 | `--idempotent-token` | 否  | 幂等 token，确保更新操作幂等；最少 10 个字符，建议使用时间戳 + 场景标识拼接（如 `1744800000-board-1`）。同一次逻辑更新只生成一次该 token，重试时须原样复用；切勿在每次重试时重新生成时间戳或幂等 key，否则会重复写入 |
-| `--overwrite`        | 否  | 覆盖更新，在更新前删除所有现有内容，默认为 false                |
+| `--overwrite`        | 否  | 写入模式：带上则覆盖更新（写入前删除画板所有现有内容再写入）；省略则为增量追加（保留原有内容，新内容叠加写入）。默认 false（增量追加）|
 | `--source`           | 是  | 输入画板内容，支持使用 `@path` 从文件读取，或 `-` 从 stdin 读取 |
 | `--input_format`     | 否  | 输入格式：`raw`、`plantuml`、`mermaid`、`svg`，默认为 `raw`  |
 
@@ -27,7 +27,7 @@
 
 思维导图，时序图，类图，饼图，流程图等图表推荐使用 Mermaid/PlantUML 语法绘制。
 
-而当需要绘制架构图，组织架构图，泳道图，对比图，鱼骨图，柱状图，折线图，树状图，漏斗图，金字塔图，循环/飞轮图，里程碑或其他较为复杂的图表时，推荐参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板) 使用 whiteboard-cli 工具创作。
+而当需要绘制架构图，组织架构图，泳道图，对比图，鱼骨图，柱状图，折线图，树状图，漏斗图，金字塔图，循环/飞轮图，里程碑或其他较为复杂的图表时，推荐参考 [§ 渲染 & 写入画板](lark-whiteboard-workflow.md#渲染--写入画板) 使用 whiteboard-cli 工具创作。
 
 ## 示例
 
@@ -71,7 +71,7 @@ lark-cli whiteboard +update \
 
 ### 示例 3：使用 whiteboard-cli 生成 OpenAPI 格式并写入画板
 
-whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)
+whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](lark-whiteboard-workflow.md#渲染--写入画板)
 
 ```bash
 # 使用 whiteboard-cli 生成 OpenAPI 格式并通过管道传递
@@ -85,7 +85,7 @@ npx -y @larksuite/whiteboard-cli@^0.2.13 -i <产物文件> --to openapi --format
 
 ### 示例 4：先生成产物文件，再从文件读取更新
 
-whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)
+whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](lark-whiteboard-workflow.md#渲染--写入画板)
 
 ```bash
 # 生成 OpenAPI 格式到文件

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

@@ -1,4 +1,4 @@
-# 画板创作/修改工作流
+# 画板创作/编辑工作流
 
 ## 创作 Workflow
 
@@ -19,23 +19,24 @@
 
 ---
 
-## 修改 Workflow
+## 编辑 Workflow
 
 **Step 1：获取 board_token**（同创作 Workflow Step 1）
 
-**Step 2：判断修改策略**
+**Step 2：探测可编辑性 / 是否由代码绘制**
 
-```
-+export --output-type source
-  ├─ 返回 Mermaid/PlantUML 代码
-  │   → 在原代码上修改 → +update --input_format mermaid/plantuml
-  ├─ 无代码（SVG/DSL 或其他方式绘制的画板）
-  │   ├─ 需纯新增（思维导图、流程图、时序图、类图、饼图、甘特图）图表节点
-  │   │    → +export --output-type preview → 看图 → +export --output-type raw → 确定新节点坐标和层级  → [§ 渲染 & 写入画板]
-  │   └─ 其他改动（几何变动/增删元素/结构调整/混合编辑等）
-  │       → [`../routes/svg-edit.md`](../routes/svg-edit.md)（视觉高保真还原，大部分场景适用）
-  └─ 用户有明确要求 → 以用户要求优先
-```
+- `+export --output-type source` — 能返回单一 Mermaid/PlantUML 源码，说明画板由代码绘制、可走路径①；返回无代码/多图则走路径②③④
+
+**Step 3：选编辑路径**（按上到下匹配，命中即停；用户有明确指定则以用户为准）
+
+| 路径 | 命中条件 | 怎么改 | 写入方式 | 是否有损 |
+|---|---|---|---|---|
+| ①源码重构 | `+export source` 返回单一 Mermaid/PlantUML（即画板由代码绘制） | 在源码上改 → 按源码类型用 `+update --input_format mermaid` 或 `+update --input_format plantuml` | overwrite（整板重建） | ⚠️ **非严格无损，执行前确认** |
+| ②属性微调 | 只改已有节点的文字/颜色 | `+export --output-type raw --output <file>`（**必须写入文件**）→ 编辑文件中目标节点字段；如只能用 `+update --input_format raw --source @<file> --overwrite` 写回，先说明会整板重建并等待用户确认 | overwrite（整板重建） | ⚠️ **有损风险，未确认不得执行** |
+| ③增量追加 | 在原图基础上新增图/元素，保留原内容 | `+export --output-type preview` → 理解原图 → `+export --output-type raw` → 确定新节点坐标 → [§ 渲染 & 写入画板](#渲染--写入画板) 创作&写入 | append（**不加 `--overwrite`**） | 无损（原节点不动） |
+| ④结构重绘 | 需几何变动/增删元素/结构调整/混合编辑 | [`../routes/svg-edit.md`](../routes/svg-edit.md) | overwrite（清空重来） | ⚠️ **有损，必须先经用户确认** |
+
+**⚠️ 止损**：一条路径最多试 2 轮，不行就换条路径尝试一次；仍不行就停下，如实告诉用户卡点，不要在各路径间反复横跳。
 
 ---
 
@@ -45,12 +46,13 @@
 
 **先自报身份**：按训练来源，你属于哪一家？`Claude` / `Gemini` / `GPT` / `GLM` / `Doubao 或 Seed` / `Other`。身份决定 SVG / DSL 分流（不同家族对这两种表达语言的能力不均衡），不要跳过这一步。
 
-**然后按图表类型 × 身份选路径**，读对应文件按其完整 workflow 执行（含读 scene 指南、生成内容、渲染审查、交付）：
+**然后按当前产物类型 / 图表类型 × 身份选路径**，读对应文件按其完整 workflow 执行（含读 scene 指南、生成内容、渲染审查、交付）：
 
-按上到下匹配, 命中即停:
+当前产物路由按上到下匹配, 命中即停:
 
 | 图表类型               | 身份                                  | 路径                                             |
 |--------------------|-------------------------------------|------------------------------------------------|
+| 当前要生成/追加的内容包含 @用户提及或图片/配图 | 任何身份                                | [`../routes/dsl.md`](../routes/dsl.md)         |
 | 思维导图、时序图、类图、饼图、甘特图 | 任何身份                                | [`../routes/mermaid.md`](../routes/mermaid.md) |
 | 鱼骨图、金字塔图、流程图    | `Doubao` / `Seed`                   | [`../routes/dsl.md`](../routes/dsl.md)         |
 | 其他图表               | `Claude` / `Gemini` / `GPT` / `GLM` / `Doubao` / `Seed`  | [`../routes/svg.md`](../routes/svg.md)         |
@@ -81,7 +83,7 @@ diagram.png           ← 渲染结果
 
 写入画板时按最终产物类型选择 `+update --input_format`：
 
-- Mermaid / PlantUML / SVG 产物直接用对应的 `mermaid` / `plantuml` / `svg` 写入。
+- Mermaid / PlantUML / SVG 产物直接写入时，`--input_format` 取单值 `mermaid` / `plantuml` / `svg`；写入非空已有画板并需要 overwrite 时，先确认会整板重建；SVG 修改已有画板时先走 [`../routes/svg-edit.md`](../routes/svg-edit.md) 的确认 workflow。
 - 只有 DSL 产物或已明确需要 OpenAPI 原生节点格式时，才先用 `npx -y @larksuite/whiteboard-cli@^0.2.13 --to openapi --format json` 转换，再用 `raw` 写入。
 
 具体命令示例、`--overwrite`、`--idempotent-token` 和 `--as user/bot` 的使用方式，统一参考 [`whiteboard +update`](./lark-whiteboard-update.md)。

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

@@ -33,7 +33,7 @@ Step 3: 渲染 & 审查 → 交付
       npx -y @larksuite/whiteboard-cli@^0.2.13 -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#写入画板)
+      → 完整 dry-run / 确认流程见 [§ 写入画板](../references/lark-whiteboard-workflow.md#写入画板)
   - 交付：向用户报告 board_token 写入成功
 ```
 
@@ -73,7 +73,13 @@ Step 3: 渲染 & 审查 → 交付
 | 循环/飞轮图 | `scenes/flywheel.md`     | 增长飞轮、闭环链路                     |
 | 里程碑      | `scenes/milestone.md`    | 时间线、版本演进                       |
 | 流程图      | `scenes/flowchart.md`    | 业务流、状态机、带条件判断的链路       |
-| 图片展示    | `scenes/photo-showcase.md` | 用户显式要求图片/配图/插图时（需先完成 `elements/image.md` 的图片准备） |
+
+### 插入 @用户提及 / 图片
+
+| 当前内容包含 | 必读指南 |
+|---|---|
+| @用户提及 | [`../scenes/mention.md`](../scenes/mention.md) |
+| 图片 / 配图 | [`../scenes/photo-showcase.md`](../scenes/photo-showcase.md) |
 
 ## 渲染前自查
 

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

@@ -22,6 +22,6 @@ Step 3: 渲染验证 & 写入画板 & 交付
        npx -y @larksuite/whiteboard-cli@^0.2.13 -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#写入画板)
+       → 完整 dry-run / 确认流程见 [§ 写入画板](../references/lark-whiteboard-workflow.md#写入画板)
   6. 交付：向用户报告 board_token 写入成功
 ```

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

@@ -16,11 +16,14 @@ SVG 导出是**纯视觉快照**，再次导入后画板语义（思维导图层
 
 ### 0. 用户确认（强制）
 
-在执行任何编辑前，**必须**向用户说明：
+执行任何编辑前，先判断**紧邻的上一条用户消息**是否已明确确认有损编辑：
+
+- **已确认**（含用户主动预授权，如"我知道有损，直接改"）→ 直接进入 Step 1，不再重复警告。
+- **未确认或回复含糊** → 原样向用户发出下面这句话，**然后立即结束本回合等待回复** —— 同一条消息内不得附带任何导出/编辑/写回命令或工具调用：
 
 > SVG 编辑只保证视觉层面对齐，画板语义（层级/节点类型/思维导图结构/表格结构/连线绑定/容器类型/mention 等）将不可恢复，是否继续？
 
-**用户未确认前不得执行后续步骤。**
+这是**知情确认**（动手前让用户对语义丢失止损）；真正的破坏性写入在 Step 4 还会再经 `--overwrite` dry-run 确认一次，二者职责不同、都不可省。
 
 ### 1. 导出当前画板 SVG
 

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

@@ -54,6 +54,8 @@
 - 阴影：`<filter>` 里放 `<feDropShadow>` 或标准 drop/inner primitive 链 (`<feGaussianBlur in="SourceAlpha">` + `<feOffset>` + `<feFlood>` + `<feComposite>` + `<feMerge>`), 会被识别成节点阴影, drop 至多 1 个, inner 至多 1 个; 其余 filter 效果不识别
 - 渐变：`<linearGradient>` / `<radialGradient>` 在 `<defs>` 中定义, 通过 `fill="url(#id)"` 引用 (载体限 `<rect>` / `<circle>` / `<ellipse>` / `<polygon>` / `<path>`), 需要至少 2 个 `<stop>`, `gradientUnits` 只支持默认的 `objectBoundingBox` (不写即可);
 
-**⚠️ [!IMPORTANT] 不支持的装饰特性**
+> [!IMPORTANT]
+> ⚠️ **不支持的装饰特性**
+
 - `<pattern>` / `<clipPath>` / `<mask>` / 非阴影用途的 `<filter>` (blur / hue-rotate / 复合合成 / `flood-color=url(...)` / 多个 `<feDropShadow>` 等) → 画板不支持，**请避免使用，否则会导致画板渲染问题**
 - 渐变边界：`gradientUnits="userSpaceOnUse"` / `spreadMethod="reflect|repeat"` / stops 少于 2 个 / 复杂 `gradientTransform` 会变成不可编辑图片, 视觉正确但失去可编辑性, 若无必要请沿用默认 `objectBoundingBox`

package/skills/lark-whiteboard/scenes/mention.md

@@ -0,0 +1,71 @@
+# 提及用户 (@用户 / mentionUser)
+
+适用于：文本节点内需要 @ 某个飞书用户（如"负责人：@张三"、"@李四 请跟进"）。mention 不是独立节点，而是文本节点富文本中的一段 run，可与普通文字混排。
+
+> 当用户要插入 @用户提及时阅读本页。
+
+## 取值来源（强约束）
+
+- 本页只讲 @用户（mentionUser）。@文档（mentionDoc）暂不支持。
+- `mentionUserId` 必须是**真实的飞书用户 open_id**（形如 `ou_xxxxxxxx`）。
+- 用户只给出**姓名**时，先用 `lark-contact` skill 把姓名解析成 open_id，再填入 `mentionUserId`。
+- **无法解析出真实 open_id 时，停下向用户确认，禁止臆造 id**。假 id 会写入失败或 @ 到错误的人。
+
+## Content 约束（关键）
+
+- 带 `mentionUserId` 的 run，其 `content` **必须非空**，约定填 `"*"`（单字符占位）。
+  - 原因：转换按字符占位来引用样式，`content` 为空串时该 mention 不会产出任何元素（静默丢失）。
+- `content` 的字面内容**不会显示**：画板上显示的是按 open_id 反查到的用户名，不是 `content` 的文字。因此不要把用户名写进 `content`，填单个 `"*"` 即可。
+- 一个 run 只能是一种类型：`mentionUserId` 与 `hyperlink` **互斥**，不能同时出现在同一个 run（校验会报错）。需要"链接 + @用户"时拆成两个 run。
+
+## 骨架示例
+
+`text` 用 `WBTextRun[]`，把 @用户 拆成独立 run（`content: "*"` + `mentionUserId`），前后再接普通文字 run：
+
+```json
+{
+  "type": "text",
+  "width": "fit-content",
+  "height": "fit-content",
+  "text": [
+    { "content": "负责人：", "fontSize": 14 },
+    { "content": "*", "mentionUserId": "ou_xxxxxxxxxxxxxxxx", "fontSize": 14 },
+    { "content": " 请本周内跟进", "fontSize": 14 }
+  ]
+}
+```
+
+写入画板走标准 DSL 路径（`npx -y @larksuite/whiteboard-cli@^0.2.13 -i diagram.json --to openapi --format json | lark-cli whiteboard +update ... --input_format raw`），无需手写 raw JSON。
+
+## 正反例
+
+正确：
+
+```json
+{ "content": "*", "mentionUserId": "ou_abc123" }
+```
+
+错误（content 空串 → 不产出 @用户）：
+
+```json
+{ "content": "", "mentionUserId": "ou_abc123" }
+```
+
+错误（把用户名写进 content → 多余占位，显示仍由 uid 决定）：
+
+```json
+{ "content": "@张三", "mentionUserId": "ou_abc123" }
+```
+
+错误（与 hyperlink 同 run → 校验报错，须拆两个 run）：
+
+```json
+{ "content": "*", "mentionUserId": "ou_abc123", "hyperlink": "https://xxx.com" }
+```
+
+## 陷阱
+
+- **content 为空**：mention 静默丢失，画板上看不到 @用户。必须填 `"*"`。
+- **把用户名写进 content**：无意义，显示名由 open_id 反查决定；且多字符会占用多个字符位。
+- **mentionUserId + hyperlink 同 run**：一个 run 只能是一种元素类型，会被校验拦截，须拆成两个 run。
+- **用假 id 或用户中文名当 id**：`mentionUserId` 只接受真实 open_id，先经 `lark-contact` 解析。