@amaster.ai/pi-lark 0.1.7 → 0.1.9

package/skills/lark-slides/references/cli/lark-slides-history.md

@@ -0,0 +1,132 @@
+# slides history（历史版本与回滚）
+
+用于查看 Slides XML presentation 历史版本、按 `history_version_id` 回滚，以及查询回滚任务状态。
+
+`entries[].edit_time` 是 UTC RFC3339 时间字符串（例如 `2026-06-22T12:24:45Z`）。按时间匹配时先将其解析为时间值，再比较先后关系或时间差。
+
+## 安全流程
+
+1. 先用分页接口 `+history-list` 找到目标版本的 `history_version_id`。
+2. 如果用户指定的是 `revision_id`，不要假设它唯一，也不要把 `revision_id` 直接传给 `+history-revert`。先拉一页并在 `entries[]` 中筛选 `revision_id` 相同的候选；如果未匹配到且 `has_more=true`，继续用 `page_token` 翻页；如果已匹配到候选，最多额外再拉一页补齐可能跨页的相邻候选。最终优先根据用户目标时间与 `edit_time` 的接近程度选择最合适的一条，取同一条的 `history_version_id`；如果没有目标时间，或多个候选无法可靠区分，再向用户展示候选版本（`history_version_id`、`revision_id`、`edit_time`、`name/description`）并确认后回滚。
+3. 如果用户指定的是某一时刻但没有指定 `revision_id`，按 `entries[].edit_time` 匹配；优先选择不晚于目标时刻的最近一条历史记录，无法明确匹配时先向用户确认候选版本。
+4. 使用 `+history-revert` 发起回滚。接口会立即返回 `task_id`，回滚任务在服务端异步执行。
+5. 如果返回 `status: running`，保存 `task_id`，按照返回的 `poll_after_ms` 等待后调用 `+history-revert-status`。任务创建成功后，不得因为状态查询失败而重新发起回滚。
+6. 状态变为 `done`、`partial_failed` 或 `failed` 后停止轮询；达到整体轮询上限时也停止轮询，并向用户返回 `task_id` 和当前状态。
+7. 回滚完成后，用 `slides +xml-get` 或 `slides xml_presentations get` 读取演示文稿确认内容。
+
+## 按 revision_id 或时间点回滚
+
+当用户说“回滚到 revision_id=42”“恢复到昨天下午 3 点的版本”这类需求时，流程是：
+
+1. 执行 `slides +history-list --presentation <presentation>` 获取第一页历史记录；`+history-list` 是分页接口，只有 `has_more=true` 且还需要更多候选时才继续传 `--page-token` 翻页。
+2. 如果用户给出 `revision_id`：先筛选当前页中 `entries[].revision_id == 用户给出的 revision_id`。如果未命中且 `has_more=true`，继续拉下一页；如果已经命中候选，最多额外再拉一页，补齐同一个 `revision_id` 可能跨页出现的相邻 `history_version_id`。若用户同时给出目标时间，在候选里选择 `edit_time` 与目标时间最接近的一条；若未给目标时间但候选只有一条，可直接使用；若多个候选无法可靠区分，不要自行取第一条，向用户展示候选并确认。
+3. 如果用户只给出时间：用 `entries[].edit_time` 匹配，选择目标时刻之前最近的一条；如果用户表达的是“最接近某时刻”，则选择绝对时间差最小的一条。
+4. 从最终匹配条目读取 `history_version_id`。`history_version_id` 对应服务端 `minor_history.version`，这是回滚接口需要的 ID。
+5. 执行 `slides +history-revert --presentation <presentation> --history-version-id <history_version_id>`。
+
+候选确认时使用类似格式：
+
+```text
+同一个 revision_id 命中多个历史版本，请确认要回滚哪一条：
+- history_version_id=11 revision_id=42 edit_time=2026-06-22T12:24:45Z name=...
+- history_version_id=12 revision_id=42 edit_time=2026-06-22T12:25:14Z name=...
+```
+
+## 命令
+
+```bash
+# 列出历史版本
+lark-cli slides +history-list --presentation "<slides_url_or_token>" --page-size 20
+
+# 翻页
+lark-cli slides +history-list --presentation "<slides_url_or_token>" --page-size 20 --page-token "<page_token>"
+
+# 发起回滚任务，立即返回 task_id
+lark-cli slides +history-revert --presentation "<slides_url_or_token>" --history-version-id 42
+
+# 查询回滚任务状态
+lark-cli slides +history-revert-status --presentation "<slides_url_or_token>" --task-id "<task_id>"
+```
+
+## 参数
+
+| 命令 | 参数 | 必填 | 说明 |
+|-|-|-|-|
+| `+history-list` | `--presentation` | 是 | `xml_presentation_id`、Slides URL，或可解析为 Slides 的 wiki URL |
+| `+history-list` | `--page-size` | 否 | 返回条数，范围 `1-20`，默认 `20` |
+| `+history-list` | `--page-token` | 否 | 上一页返回的 `page_token` |
+| `+history-revert` | `--presentation` | 是 | 同一个演示文稿 |
+| `+history-revert` | `--history-version-id` | 是 | `+history-list` 返回的 `history_version_id`，必须大于 0 |
+| `+history-revert-status` | `--presentation` | 是 | 同一个演示文稿 |
+| `+history-revert-status` | `--task-id` | 是 | `+history-revert` 返回的 `task_id` |
+
+## 异步轮询策略
+
+1. `+history-revert` 返回 `task_id` 后，认为回滚任务已经成功创建。
+2. 如果 `status` 不是 `running`，不再调用状态接口。
+3. 如果 `status` 是 `running`，等待响应中的 `poll_after_ms` 后调用 `+history-revert-status`；`poll_after_ms` 缺失、为 `0` 或非法时，默认等待 10 秒。
+4. 状态查询返回 `running` 时继续轮询；返回 `done`、`partial_failed` 或 `failed` 时停止。
+5. 除非用户另有要求，默认最多轮询 5 分钟。达到上限后停止轮询，向用户说明任务仍在运行并返回 `task_id`，不得将其描述为回滚失败。
+6. 状态查询出现临时错误时，按相同间隔最多连续重试 3 次；只重试 `+history-revert-status`，不得重新调用 `+history-revert`。
+7. `done` 后读取当前演示文稿内容进行验证。
+8. `partial_failed` 或 `failed` 时展示 `failed_block_tokens`；除非用户明确确认，不得自动再次发起回滚。
+
+## 返回值要点
+
+`+history-list` 返回：
+
+```json
+{
+  "entries": [
+    {
+      "revision_id": 42,
+      "history_version_id": "11",
+      "edit_time": "2026-06-22T12:24:45Z",
+      "type": 1,
+      "name": "版本名",
+      "description": "版本说明",
+      "editor_ids": ["ou_xxx"]
+    }
+  ],
+  "has_more": true,
+  "page_token": "page_token"
+}
+```
+
+`+history-revert` 返回：
+
+```json
+{
+  "task_id": "task_xxx",
+  "status": "running",
+  "history_version_id": "11",
+  "poll_after_ms": 10000
+}
+```
+
+`+history-revert-status` 返回：
+
+```json
+{
+  "status": "partial_failed",
+  "history_version_id": "11",
+  "failed_block_tokens": ["blk_xxx"]
+}
+```
+
+`status` 可能是 `running`、`done`、`partial_failed`、`failed`。当状态是 `partial_failed` 或 `failed` 时，优先检查 `failed_block_tokens`。
+
+## 回滚后验证
+
+回滚成功后必须读取一次当前内容确认：
+
+```bash
+lark-cli slides +xml-get --presentation "<slides_url_or_token>" --output ./presentation.xml
+```
+
+如果只需要快速检查返回结构，也可以走 raw OpenAPI：
+
+```bash
+lark-cli api get "/open-apis/slides_ai/v1/xml_presentations/<xml_presentation_id>" \
+  --params '{"revision_id":-1}'
+```

package/skills/lark-slides/references/cli/lark-slides-media-upload.md

@@ -0,0 +1,103 @@
+# slides +media-upload（上传本地图片到飞书幻灯片）
+
+把本地图片上传到指定演示文稿的 drive 媒体库，返回 `file_token`。**返回的 token 作为 `<img src="...">` 的值塞进 slide XML 即可显示图片。**
+
+## 命令
+
+```bash
+# 直接传 xml_presentation_id
+lark-cli slides +media-upload --as user \
+  --file ./pic.png \
+  --presentation slidesXXXXXXXXXXXXXXXXXXXXXX
+
+# 传 slides URL 也行
+lark-cli slides +media-upload --as user \
+  --file ./chart.png \
+  --presentation "https://xxx.feishu.cn/slides/slidesXXXXXXXXXXXXXXXXXXXXXX"
+
+# 传 wiki URL（CLI 自动 wiki.spaces.get_node 解析为真实 token，校验 obj_type=slides）
+lark-cli slides +media-upload --as user \
+  --file ./pic.png \
+  --presentation "https://xxx.feishu.cn/wiki/wikcnXXXXXX"
+
+# 预览（不实际上传）
+lark-cli slides +media-upload --file ./pic.png --presentation $PRES_ID --dry-run
+```
+
+## 返回值
+
+```json
+{
+  "file_token": "boxcnXXXXXXXXXXXXXXXXXXXXXX",
+  "file_name": "pic.png",
+  "size": 12345,
+  "presentation_id": "slidesXXXXXXXXXXXXXXXXXXXXXX"
+}
+```
+
+- **`file_token`**：把它写进 `<img src="...">`
+- **`file_name` / `size`**：上传文件元信息
+- **`presentation_id`**：解析后的真实 `xml_presentation_id`（wiki URL 解析后会变化）
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file` | 是 | 本地图片路径，**必须是 CWD 内的相对路径**（如 `./pic.png`）。**最大 20 MB**（slides upload API 不支持分片上传）。**仅支持 png / jpeg / gif / bmp / tiff / webp** |
+| `--presentation` | 是 | `xml_presentation_id`、`/slides/<token>` URL，或 `/wiki/<token>` URL |
+
+> [!IMPORTANT]
+> **路径必须在 CWD 内**：`--file /abs/path/x.png` 或 `--file ../up/x.png` 会被 CLI 拒绝（报 `unsafe file path`）。如果素材在别的目录，先 `cd` 过去再执行。
+
+## 使用流程
+
+> 新建 PPT（[`+create --slides`](lark-slides-create.md)）或给已有 PPT 加新页（[`+add-slide`](lark-slides-add-slide.md)）都不需要单独上传：XML 里把 `<img src>` 写成 `@<本地路径>`，CLI 会自动上传并替换成 `file_token`。
+> 本命令用于往**已有页**里加图，或需要自己拿着 `file_token` 拼 XML 的场景。
+
+### 给已有 PPT 的已有页加图
+
+拿到 `file_token` 后走 [`+replace-slide`](lark-slides-replace-slide.md) 的 `block_insert`，不用搬原 XML、不改 `slide_id`、不打乱页序：
+
+```bash
+PRES_ID=xxx
+SID=yyy       # 要加图的那一页
+
+# 1) 上传图片拿 file_token
+TOKEN=$(lark-cli slides +media-upload --as user \
+  --file ./pic.png --presentation $PRES_ID --jq '.data.file_token')
+
+# 2) block_insert 到页末（或用 insert_before_block_id 指定插入位置）
+lark-cli slides +replace-slide --as user \
+  --presentation "$PRES_ID" --slide-id "$SID" \
+  --parts "$(jq -n --arg token "$TOKEN" \
+    '[{action:"block_insert",insertion:("<img src=\""+$token+"\" topLeftX=\"500\" topLeftY=\"100\" width=\"200\" height=\"150\"/>")}]')"
+```
+
+注意事项：
+
+1. **`<img>` 坐标避开现有元素** —— 先读现有元素 bbox 挑空白区；空间不够就先用 `block_replace` 挪动/缩小现有元素后再放图
+2. **`<img>` 的 `width:height` 对齐原图比例** —— 比例不一致会被裁剪，参见 [xml-schema-quick-ref.md](../xml/xml-schema-quick-ref.md) `<img>` 说明
+
+## 工作原理
+
+`+media-upload` 内部调用 `POST /open-apis/drive/v1/medias/upload_all`（单次上传，最大 20 MB），固定使用：
+
+- `parent_type=slide_file`（slides 后端唯一接受的取值）
+- `parent_node=<xml_presentation_id>`
+
+**不要尝试用 `slides_image`、`slide_image` 等 parent_type**——后端会返回 1061001 / 1061002 错误。这是 slides 的特殊约定。
+
+## 常见错误
+
+| 错误码 | 含义 | 解决方案 |
+|--------|------|----------|
+| 1061002 | params error / 不支持的 parent_type | 不要用原生 API 自己拼 parent_type；用 `+media-upload` 即可 |
+| 1061004 | forbidden：当前身份对该演示文稿无编辑权限 | 确认当前身份（user 或 bot）对目标 PPT 有编辑权限。bot 模式常见原因：PPT 不是该 bot 创建的——可用 `+create --as bot` 新建，或以 user 身份给 bot 授权 `lark-cli drive permission.members create --as user ...` |
+| 1061044 | parent node not exist | `--presentation` 给的 token 不对，或不是 slides 类型 |
+| 403 | 权限不足 | 检查 `docs:document.media:upload` scope；wiki URL 还需要 `wiki:node:read` |
+
+## 相关命令
+
+- [+create](lark-slides-create.md) — 新建 PPT（支持 `@` 占位符自动上传图片）
+- [+replace-slide](lark-slides-replace-slide.md) — 给已有页加图 / 换图（`block_insert` / `block_replace`）
+- [+add-slide](lark-slides-add-slide.md) — 追加/插入单页（同样支持 `@` 占位符自动上传）

package/skills/lark-slides/references/cli/lark-slides-replace-slide.md

@@ -0,0 +1,259 @@
+# slides +replace-slide（块级替换 / 插入）
+
+对指定 slide 做块级替换或插入。编辑已有 PPT 的主路径——`slide_id` 不变、页序不动、只影响被指定的块。
+
+> **编写 `--parts` 时只使用标准 action 和字段**：`block_replace` 使用 `block_id` + `replacement`，`block_insert` 使用 `insertion`（可选 `insert_before_block_id`）。不要根据其他 API 或自然语言猜 action、字段名；具体结构以本文表格为准。
+
+相比直接调 `xml_presentation.slide.replace`，这个 shortcut 的四个额外价值：
+
+1. `--presentation` 接受 `xml_presentation_id` / `/slides/` URL / `/wiki/` URL（wiki 自动解析）；
+2. `block_replace` 的 `replacement` 根元素 `id="<block_id>"` 由 CLI 自动注入——底层 API 的硬约束（不注入返回 3350001）；直接调原生 API 需自己加，用 Shortcut 则自动注入；
+3. `<shape>` 元素缺少 `<content/>` 子元素时由 CLI 自动注入——SML 2.0 schema 要求每个 `<shape>` 必须有 `<content/>` 子元素，缺失同样触发 3350001；自闭合的 `<shape .../>` 也会被自动展开为 `<shape ...><content/></shape>`；
+4. 3350001 错误时提供上下文感知的 hint，帮助 AI agent 和用户快速定位原因。
+
+## 命令
+
+```bash
+# block_insert：在页末追加一个新元素
+lark-cli slides +replace-slide --as user \
+  --presentation slidesXXXXXXXXXXXXXXXXXXXXXX \
+  --slide-id pfG \
+  --parts '[{"action":"block_insert","insertion":"<shape type=\"rect\" topLeftX=\"500\" topLeftY=\"100\" width=\"200\" height=\"100\"/>"}]'
+
+# block_replace：已知某块 id，整块替换（replacement 根 id 自动注入为 bUn）
+lark-cli slides +replace-slide --as user \
+  --presentation slidesXXXXXXXXXXXXXXXXXXXXXX \
+  --slide-id pfG \
+  --parts '[{"action":"block_replace","block_id":"bUn","replacement":"<shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新标题</p></content></shape>"}]'
+
+# 大 --parts 走文件或 stdin（auto-gen 命令不支持 @file，但 shortcut 支持）
+lark-cli slides +replace-slide --as user \
+  --presentation $PID --slide-id $SID --parts @parts.json
+cat parts.json | lark-cli slides +replace-slide --as user \
+  --presentation $PID --slide-id $SID --parts -
+
+# wiki URL 直接传（CLI 自动 get_node → 拿真实 xml_presentation_id）
+lark-cli slides +replace-slide --as user \
+  --presentation "https://xxx.feishu.cn/wiki/wikcnXXXXXX" --slide-id pfG \
+  --parts '[{"action":"block_insert","insertion":"<shape type=\"rect\" width=\"100\" height=\"100\"/>"}]'
+
+# 预览（不实际调用）
+lark-cli slides +replace-slide --as user \
+  --presentation $PID --slide-id $SID --parts "$PARTS" --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--presentation` | 是 | `xml_presentation_id`、`/slides/<token>` URL，或 `/wiki/<token>` URL |
+| `--slide-id` | 是 | 页面 ID（`xml_presentation.slide.get` / `slides +xml-get` 都能拿到） |
+| `--parts` | 是 | JSON 数组（`[{...}, ...]`），单次最多 200 条。支持 `@<file>` 和 `-`（stdin）读取 |
+| `--revision-id` | 否 | 基础版本号；默认 `-1` 表示基于最新版执行；传具体版本号时，服务端以该版本为 base 执行；**传不存在的版本号（超过当前 revision）返回 3350002** |
+| `--tid` | 否 | 并发事务 ID；多人协作长事务才用，单次单人调用留空 |
+
+## parts 元素结构
+
+> **限制**：最多 200 条；`block_replace` 和 `block_insert` 可以在同一批次混用。**其他 action（含 `str_replace`）CLI 会直接报错拒绝**。
+
+每条 part 按 `action` 取不同字段：
+
+### action = `block_replace`
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `action` | 是 | `"block_replace"` |
+| `block_id` | 是 | 目标块的 3 位 short element ID（从 `slide.get` 返回 XML 里读） |
+| `replacement` | 是 | 新 XML 片段；**根元素 `id` 会被 CLI 自动注入为 `block_id`**，用户不用自己加（如果已经加了且不一致会被覆盖为正确值） |
+
+### action = `block_insert`
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `action` | 是 | `"block_insert"` |
+| `insertion` | 是 | 要插入的 XML 片段 |
+| `insert_before_block_id` | 否 | 插到这个块之前；省略（不提供此字段）则追加到页末 |
+
+### 错误字段名（CLI 直接拒绝）
+
+编写 part 时只使用上表中的标准字段。CLI 返回 unknown field 时会点名写错的字段，并按情况给出下一步：能对上正确字段时直接建议它（`did you mean \"replacement\"?`），字段属于另一个 action 时说明归属（`it belongs to block_insert`），都对不上时列出该 action 的合法字段集。无论哪种，**要改的是字段名，不是字段值**。
+
+```jsonc
+// ❌ 全部被拒
+[{"action":"block_replace","block_id":"bUn","xml":"<shape.../>"}]           // unknown field "xml"; did you mean "replacement"?
+[{"action":"block_replace","block_id":"bUn","data":"<shape.../>"}]          // data 不是标准字段
+[{"action":"block_replace","block_id":"bUn","insertion":"<shape/>"}]        // insertion 属于 block_insert
+[{"action":"block_replace","block_id":"bUn","replacement":{"type":"..."}}]  // replacement 必须是字符串，报 .replacement must be a string
+
+// ✅ 正确
+[{"action":"block_replace","block_id":"bUn","replacement":"<shape type=\"text\"><content><p>新内容</p></content></shape>"}]
+[{"action":"block_insert","insertion":"<shape type=\"rect\" width=\"100\" height=\"100\"/>"}]
+```
+
+## 合法根元素速查
+
+`block_replace.replacement` 和 `block_insert.insertion` 必须以 SML 2.0 定义的合法元素为根。完整权威定义看 [`slides_xml_schema_definition.xml`](../xml/slides_xml_schema_definition.xml)；这里只列能作为**根**的类型 + 每种类型的最小可工作片段。
+
+| 元素 | 用途 | 关键点 |
+|---|---|---|
+| `<shape>` | 矩形/椭圆/三角/文本框等所有形状 | `type` 必填；`<content/>` 缺失时 CLI 会自动注入 |
+| `<line>` | 直线 | 需 `startX/startY/endX/endY` |
+| `<polyline>` | 折线 | `points` 读回时被服务端规整丢弃（几何已入库） |
+| `<img>` | 图片 | `src` 必须是 [`+media-upload`](lark-slides-media-upload.md) 返回的 `file_token`，不能是 URL |
+| `<icon>` | 图标 | `iconType` 取自 iconpark 资源；语义图标先用 `scripts/iconpark_tool.py search` 检索 |
+| `<table>` | 表格 | 整表替换会**重建内部 td id**，旧 td block_id 立即失效 |
+| `<td>` | 单元格局部替换 | 只能 `block_replace`，不能 `block_insert`；`block_id` 必须是最新 `slide.get` 拿到的 td id |
+| `<chart>` | 图表（line/bar/column/pie/area/radar/combo） | 必须嵌 `<chartPlotArea>` + `<chartData>` + `<dim1>/<dim2>/<chartField>` |
+
+**不可作为根元素**：
+
+- `<video>` / `<audio>` —— SML 2.0 没有这两个原生元素；`<undefined type="video|audio">` 是**导出时**的占位符（服务端遇到不支持的类型时用它代替），**不能写入**。尝试 insert/replace 都会返回 3350001。
+
+### 最小 XML 片段（JSON 嵌入时记得把 `"` 转义成 `\"`）
+
+`<shape>`（文本框；`type` 还可选 `rect`/`ellipse`/`triangle`/`custom` 等）：
+```xml
+<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
+  <content textType="title"><p>标题</p></content>
+</shape>
+```
+
+`<img>`：
+```xml
+<img src="{file_token}" topLeftX="600" topLeftY="20" width="80" height="80"/>
+```
+
+`<polyline>`：
+```xml
+<polyline topLeftX="10" topLeftY="10" width="100" height="50" points="0,0 50,50 100,0"/>
+```
+
+`<table>`（2×2）：
+```xml
+<table topLeftX="30" topLeftY="80">
+  <colgroup><col span="2" width="110"/></colgroup>
+  <tr><td><content><p>A</p></content></td><td><content><p>B</p></content></td></tr>
+  <tr><td><content><p>C</p></content></td><td><content><p>D</p></content></td></tr>
+</table>
+```
+
+`<td>`（`block_replace` 单元格；`block_id` 必须是最新 `slide.get` 拿到的 td id）：
+```xml
+<td><content><p>新内容</p></content></td>
+```
+
+`<chart>`（`type` 改成 `bar`/`column`/`pie`/`area`/`radar`/`combo` 切换图型）：
+```xml
+<chart topLeftX="30" topLeftY="300" width="300" height="200">
+  <chartPlotArea><chartPlot type="line"/></chartPlotArea>
+  <chartData>
+    <dim1><chartField name="x" valueType="string">Q1,Q2,Q3,Q4</chartField></dim1>
+    <dim2><chartField name="Sales" valueType="number">10,20,15,30</chartField></dim2>
+  </chartData>
+</chart>
+```
+
+## 返回值
+
+```json
+{
+  "xml_presentation_id": "slidesXXXXXXXXXXXXXXXXXXXXXX",
+  "slide_id": "pfG",
+  "parts_count": 1,
+  "revision_id": 102
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `xml_presentation_id` | 解析后的真实 token（wiki URL 解析后会变化） |
+| `slide_id` | 与入参一致 |
+| `parts_count` | 本次提交的 parts 条数 |
+| `revision_id` | 成功后的新版本号，下次做乐观锁时用 |
+| `failed_part_index` | 有部分失败时存在，指向第几条 part 失败 |
+| `failed_reason` | 失败原因文字描述 |
+
+整批作为原子事务：任一 part 失败则整批不生效，服务端通过 `failed_part_index` / `failed_reason` 告诉你是哪条；按此定位修正后重发。
+
+## 使用流程
+
+### 给已有页加图（典型场景）
+
+```bash
+PID=xxx
+SID=yyy
+
+# 1) 上传图片
+TOKEN=$(lark-cli slides +media-upload --as user \
+  --file ./pic.png --presentation "$PID" --jq '.data.file_token')
+
+# 2) block_insert 到页末
+lark-cli slides +replace-slide --as user \
+  --presentation "$PID" --slide-id "$SID" \
+  --parts "$(jq -n --arg token "$TOKEN" \
+    '[{action:"block_insert",insertion:("<img src=\""+$token+"\" topLeftX=\"500\" topLeftY=\"100\" width=\"200\" height=\"150\"/>")}]')"
+```
+
+### 改标题（block_replace）
+
+```bash
+# 先拿原页 XML，从里面找到标题块的 3 位 short id（如 bUn）
+lark-cli slides xml_presentation.slide get --as user \
+  --params "{\"xml_presentation_id\":\"$PID\",\"slide_id\":\"$SID\"}"
+
+# block_replace 换掉整个标题块（id 自动注入）
+lark-cli slides +replace-slide --as user \
+  --presentation "$PID" --slide-id "$SID" \
+  --parts '[{"action":"block_replace","block_id":"bUn","replacement":"<shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新标题</p></content></shape>"}]'
+```
+
+### 批量：一次换标题 + 追加装饰图
+
+`block_replace` 和 `block_insert` 可以在同一个 `--parts` 里混用，整批原子执行。
+
+```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\"/>"}
+  ]'
+```
+
+### 乐观锁
+
+```bash
+# 读时记录 revision_id
+REV=$(lark-cli slides xml_presentation.slide get --as user \
+  --params "{\"xml_presentation_id\":\"$PID\",\"slide_id\":\"$SID\"}" \
+  --jq '.data.revision_id')
+
+# 写时传 --revision-id；传不存在的版本号（超过当前 revision）返回 3350002
+lark-cli slides +replace-slide --as user \
+  --presentation "$PID" --slide-id "$SID" --revision-id "$REV" \
+  --parts "$PARTS"
+```
+
+## 常见错误
+
+| 现象 | 原因 | 对策 |
+|------|------|------|
+| 3350001 + hint "block_id not found" | `parts[i].block_id` 在当前页不存在 | 重新 `slide.get` 拿最新 XML，按里面的 short ID 再填 |
+| 3350002 not found | `--revision-id` 传了不存在的版本号（超过当前 revision） | 用 `-1` 或用 `slide.get` 拿到的有效 `revision_id` |
+| `--parts invalid JSON` | JSON 本身不完整，或被 shell 引号/转义破坏 | 将数组写入 `parts.json` 后传 `--parts @parts.json`，或通过 stdin 传给 `--parts -` |
+| `--parts[i] action "str_replace" is not supported` | CLI 不暴露 `str_replace` | 把替换需求改写成 `block_replace` / `block_insert` |
+| `--parts[i] action "page_replace" / "slide_replace" means whole-page replacement` | 把整页更新意图传给了块级 shortcut | 改用 [`slides +update-slide`](lark-slides-update-slide.md) 整页原地写回 |
+| `--parts contains N items, exceeds maximum of 200` | 一次提交 parts 太多 | 拆多次调用 |
+| `--parts[i] unknown field "xml"; did you mean "replacement"?` | XML 塞进了未支持的字段名（如 `xml` / `new_xml` / `data`） | 使用标准字段：`block_replace` 用 `replacement`，`block_insert` 用 `insertion` |
+| `--parts[i] unknown field "insertion"; it belongs to block_insert` | 字段和 `action` 不配对 | 按 action 取字段：`block_replace` = `block_id` + `replacement`；`block_insert` = `insertion` (+ `insert_before_block_id`) |
+| `--parts[i] (block_replace) requires non-empty block_id` / `replacement` | 字段名对，但值缺失或是空串 | 按 parts 元素结构补齐值 |
+| `<img>` 不显示 / 显示破图 | `src` 写了外链 URL | 换成通过 [`+media-upload`](lark-slides-media-upload.md) 拿到的 `file_token` |
+| 3350001 | `replacement` 不是合法单根 XML 片段，或 `block_id` 不存在 | CLI 已自动注入 `id` 和 `<content/>`；如果仍报错，重新 `slide.get` 拿最新 XML 确认 `block_id` 存在；检查 XML 结构是否合法；坐标是否超出 960×540 |
+| 403 | 权限不足 | 需要 `slides:presentation:update` 或 `slides:presentation:write_only`；wiki URL 还需要 `wiki:node:read` |
+
+## 相关命令
+
+- [xml_presentation.slide get](lark-slides-xml-presentation-slide-get.md) — 读原页拿 `block_id` / `revision_id`
+- [xml_presentation.slide replace](lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考
+- [+media-upload](lark-slides-media-upload.md) — 上传图片拿 `file_token`
+- [slides-editing.md](../workflow/slides-editing.md) — 读-改-写闭环 + 决策树

package/skills/lark-slides/references/cli/lark-slides-screenshot.md

@@ -0,0 +1,115 @@
+# slides +screenshot
+
+## 用途
+
+获取幻灯片页面截图并保存为本地图片文件。默认用于已存在 PPT 页面截图；传入 `--content` 时用于直接渲染单个 `<slide>` XML 片段预览。本 shortcut 会在 CLI 进程内解码并写入文件，stdout 只返回文件路径、大小、页面 ID 等元信息，避免把图片 Base64 输出给模型。
+
+截图失败则降级到 XML 读回、结构 lint等非截图检查路径。
+
+## 命令
+
+```bash
+lark-cli slides +screenshot --as user \
+  --presentation '<xml_presentation_id 或 slides/wiki URL>' \
+  --slide-number 1
+```
+
+渲染本地 XML 内容：
+
+```bash
+lark-cli slides +screenshot --as user \
+  --content @slide.xml
+```
+
+## 截图全部页面
+
+枚举全部页面的 `slide_id` 或页码，按每批最多 10 页分组并串行调用 `slides +screenshot`，复用同一个 `--output-dir`；记录失败批次，已完成批次不重复执行。
+
+## 参数
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--presentation` | list 模式必需 | `xml_presentation_id`、`/slides/` URL，或解析后为 slides 的 `/wiki/` URL。传 `--content` 时不能使用 |
+| `--slide-id` | list 模式与 `--slide-number` 二选一 | 页面 short ID；不能与 `--slide-number` 同时使用；多页截图时重复传入，或用逗号分隔一次传多个（如 `--slide-id slide_1,slide_2`）；一次最多 10 个 ID |
+| `--slide-number` | list 模式与 `--slide-id` 二选一 | 页面页号；不能与 `--slide-id` 同时使用；多页截图时重复传入，或用逗号分隔一次传多个（如 `--slide-number 1,2,3`）；一次最多 10 个页码 |
+| `--content` | render 模式必需 | 要直接渲染的 `<slide>` XML 片段；支持直接传值、`@file`、`-` stdin。传入后不能同时传 `--slide-id` / `--slide-number` |
+| `--output` | 否 | 单张截图的期望相对输出路径，可不写扩展名，显式扩展名只支持 `.png`、`.jpg`、`.jpeg`。只能选择一页，不能与 `--output-dir` / `--output-name` 同时使用；最终路径以返回的 `output` 为准 |
+| `--output-dir` | 否 | 输出目录，默认 `.lark-slides/screenshots`；必须是当前目录内的相对路径 |
+| `--output-name` | 否 | 仅用于 `--content` render 模式设置输出文件名 stem。普通页面截图传入该参数会返回 `validation/invalid_argument`（`param: --output-name`）并提示改用 `--output` |
+
+## 示例
+
+### 单页截图并固定路径
+
+```bash
+lark-cli slides +screenshot --as user \
+  --presentation slides_example_presentation_id \
+  --slide-number 1 \
+  --output .lark-slides/screenshots/example-deck-task/page-01
+```
+
+按 `slide_id` 选择单页时同样使用 `--output`：
+
+```bash
+lark-cli slides +screenshot --as user \
+  --presentation slides_example_presentation_id \
+  --slide-id slide_example_id \
+  --output .lark-slides/screenshots/example-deck-task/page-01
+```
+
+### 多页截图
+
+一次不要超过 10 页；如需更多页面，分批调用。可以重复传参，也可以用逗号分隔一次传多个：
+
+```bash
+lark-cli slides +screenshot --as user \
+  --presentation slides_example_presentation_id \
+  --slide-number 1 \
+  --slide-number 2 \
+  --output-dir .lark-slides/screenshots/example-deck-task
+```
+
+### 渲染 XML 预览
+
+```bash
+lark-cli slides +screenshot --as user \
+  --content @.lark-slides/out/demo/slide.xml \
+  --output .lark-slides/screenshots/example-deck-task/preview
+```
+
+## 返回值
+
+返回 JSON 不包含 Base64 图片内容：
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "xml_presentation_id": "slides_example_presentation_id",
+    "output": "/abs/path/.lark-slides/screenshots/example-deck-task/page-01.jpg",
+    "screenshots": [
+      {
+        "slide_id": "slide_example_id",
+        "slide_number": 1,
+        "format": "jpeg",
+        "path": "/abs/path/.lark-slides/screenshots/example-deck-task/page-01.jpg",
+        "size": 12345
+      }
+    ]
+  }
+}
+```
+
+## 注意事项
+
+1. 优先使用 `slides +screenshot` 保存本地图片，不要把图片 Base64 打到 stdout。
+2. 已存在 PPT 页面截图时，不传 `--content`，用 `--presentation` + `--slide-id` 或 `--slide-number`。
+3. 本地 XML 预览时，传 `--content @file` 或 `--content -`，内容应为单个 `<slide>` XML 片段；此时不要传 `--presentation` / `--slide-id` / `--slide-number`。
+4. `slide_id` 是页面 short ID，页码请用 `--slide-number`。
+5. list 模式下 `--slide-id` 与 `--slide-number` 必须二选一；同一类型 selector 一次最多传 10 个，更多页面请分批截图。
+6. 单张使用 `--output`，多张使用 `--output-dir`，由 CLI 按页面信息生成文件名。新建或大幅改写 Deck 时，截图目录复用 planning 阶段的 `<deck-or-task-id>`；已有 Deck 没有 task ID 时，使用 presentation ID 作为目录名。
+7. CLI 不转换图片格式，也不要求模型预判服务端格式。未写扩展名时自动追加真实扩展名；请求扩展名与真实格式不一致时保留目录和名称、修正扩展名，例如请求 `slide3.png` 而服务端返回 JPEG 时实际保存为 `slide3.jpg`。
+8. 发生扩展名修正或同名避让时会返回原始 `requested_output`、实际绝对路径 `output` 和 `output_adjusted: true`；后续必须使用 `output` / `screenshots[].path`，不要继续猜测请求路径。
+9. list 模式默认文件名包含 presentation ID、页码和/或 slide ID。
+10. 截图来自服务端渲染结果，适合创建/替换后验证页面是否为空白、破图或布局明显异常。