@amaster.ai/pi-lark 0.1.2-beta.53 → 0.1.2-beta.55

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

@@ -1,46 +1,5 @@
-# IconPark 图标
+# IconPark 图标（兼容入口）
 
-IconPark 图标通过 `<icon>` 写入 slides XML，`iconType` 必须来自本 skill 的离线索引，避免凭记忆拼路径。
+本文档已迁移至 [`xml/iconpark.md`](xml/iconpark.md)。
 
-## 机器优先流程
-
-```bash
-python3 skills/lark-slides/scripts/iconpark_tool.py search --query "增长趋势" --limit 8
-python3 skills/lark-slides/scripts/iconpark_tool.py resolve --name chart-line
-python3 skills/lark-slides/scripts/iconpark_tool.py list-categories
-```
-
-`search` 返回 JSON 数组，每项包含 `iconType`、`category`、`name`、`tags`、`score`。直接把选中的 `iconType` 写入 XML，并为图标指定可见颜色：
-
-```xml
-<icon iconType="iconpark/Charts/chart-line.svg" topLeftX="80" topLeftY="120" width="32" height="32">
-  <fill>
-    <fillColor color="rgba(37, 99, 235, 1)"/>
-  </fill>
-</icon>
-```
-
-## 使用规则
-
-- 默认先检索：语义图标需求必须先用 `iconpark_tool.py search --limit 8` 或 `--limit 10`，让 agent 从候选里结合版面语义二次判断；不要阅读全文索引，也不要编造不存在的 `iconType`。
-- 图标用于概念提示、步骤、状态、指标、角色和导航；不要用无关装饰图标填充版面。
-- 常用尺寸：行内状态图标 16-24px，卡片标题图标 28-40px，主视觉图标 56-96px。
-- 图标必须填充颜色并和背景有足够对比；深色背景优先放在浅色圆形/方形底上，或使用 `rgba(255, 255, 255, 1)` 作为图标填充色。
-- 查不到合适图标时，从高频示例里选择替代图标（随机选择，不要千篇一律），不留空图标位。
-
-## 高频示例
-
-| 语义 | iconType |
-|---|---|
-| 设置/配置 | `iconpark/Base/setting.svg` |
-| 目标 | `iconpark/Base/aiming.svg` |
-| 增长趋势 | `iconpark/Charts/positive-dynamics.svg` |
-| 折线趋势 | `iconpark/Charts/chart-line.svg` |
-| 占比 | `iconpark/Charts/chart-proportion.svg` |
-| 数据看板 | `iconpark/Charts/data-screen.svg` |
-| 成功 | `iconpark/Character/check-one.svg` |
-| 失败/风险 | `iconpark/Character/close-one.svg` |
-| 团队/用户 | `iconpark/Peoples/peoples.svg` |
-| 安全防护 | `iconpark/Safe/protect.svg` |
-| 全球/市场 | `iconpark/Travel/world.svg` |
-| 邮件/联系 | `iconpark/Office/envelope-one.svg` |
+此文件仅保留旧路径兼容性；后续引用请使用新路径。

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

@@ -1,92 +1,5 @@
-# slides +add-slide（向已有演示文稿追加/插入单页）
+# slides +add-slide（兼容入口）
 
-向已有演示文稿添加**一页**。这是两步创建流程的第二步：先 `+create` 建空壳，再逐页 `+add-slide`；也用于给已有 PPT 追加新页。
+本文档已迁移至 [`xml/lark-slides-add-slide.md`](xml/lark-slides-add-slide.md)。
 
-`--presentation` 接受 token / `/slides/` URL / `/wiki/` URL（wiki 自动解析），`--slide` 直接收 XML（支持 `@file` 和 stdin，复杂 XML 走文件可绕开 shell 转义），`<img src="@./local.png">` 占位符自动上传并替换成 `file_token`。
-
-**CRITICAL — 提交前必须先跑版式 lint**：把待提交的 `<slide>` XML 存成本地文件，运行 [`scripts/xml_text_overlap_lint.py`](../scripts/xml_text_overlap_lint.py)，`summary.error_count` 必须为 0。
-
-## 命令
-
-```bash
-# 追加到末尾（XML 直接作为参数）
-lark-cli slides +add-slide --as user \
-  --presentation "$PID" \
-  --slide '<slide xmlns="https://www.larkoffice.com/sml/2.0"><data></data></slide>'
-
-# XML 从文件读（推荐：避免 shell 转义和长参数截断）
-lark-cli slides +add-slide --as user \
-  --presentation "$PID" \
-  --slide @page3.xml
-
-# XML 从 stdin 读
-cat page3.xml | lark-cli slides +add-slide --as user --presentation "$PID" --slide -
-
-# 插到某页之前
-lark-cli slides +add-slide --as user \
-  --presentation "$PID" \
-  --slide @cover.xml \
-  --before-slide-id "$SID"
-
-# wiki 链接（CLI 自动 wiki.spaces.get_node 解析，并校验 obj_type=slides）
-lark-cli slides +add-slide --as user \
-  --presentation "https://xxx.feishu.cn/wiki/wikcnXXXXXX" \
-  --slide @page3.xml
-
-# 预览请求，不实际写入
-lark-cli slides +add-slide --presentation "$PID" --slide @page3.xml --dry-run
-```
-
-## 参数
-
-| 参数 | 必需 | 说明 |
-|------|------|------|
-| `--presentation` | 是 | `xml_presentation_id`、`/slides/` URL 或 `/wiki/` URL |
-| `--slide` | 是 | 一个完整的 `<slide>...</slide>` 文档；支持字面量、`@file`、stdin `-` |
-| `--before-slide-id` | 否 | 插到该 `slide_id` 之前；**不传就是追加到末尾** |
-| `--revision-id` | 否 | 演示文稿版本号，默认 `-1`（最新）；传具体版本号做乐观锁 |
-| `--dry-run` | 否 | 打印将要发起的请求（含图片上传步骤），不写入 |
-
-`@file` 路径**必须在 CWD 内**（如 `@./plan/page3.xml`）；绝对路径和 `../` 会被拒绝并报 `unsafe file path`。
-
-## 本地图片：`@路径` 占位符
-
-XML 里写 `<img src="@./chart.png" .../>`，CLI 会：先把每个不重复的本地文件上传到这份演示文稿（`parent_type=slide_file`），再把 `src` 替换成返回的 `file_token`，最后才提交页面。
-
-占位符路径按**执行命令时的 CWD** 解析，跟 `--slide @file` 所在目录无关；`@./assets/x.png` 找的是 `$PWD/assets/x.png`。
-
-```bash
-lark-cli slides +add-slide --as user \
-  --presentation "$PID" \
-  --slide '<slide xmlns="https://www.larkoffice.com/sml/2.0"><data><img src="@./chart.png" topLeftX="100" topLeftY="100" width="320" height="180"/></data></slide>'
-```
-
-- 文件不存在、不是普通文件、超过 20 MB，都在**调用任何接口之前**报错，不会留下半成品。
-- 去重只在**单次调用内**生效：多页共用同一张图时，逐页循环会把它每页重传一次。这种图先用 [`+media-upload`](lark-slides-media-upload.md) 传一次，把 `file_token` 写进各页的 `src`。
-
-## 成功输出
-
-```json
-{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "slide_id": "slide_example_id",
-  "revision_id": 42,
-  "before_slide_id": "slide_example_target_id",
-  "images_uploaded": 1,
-  "issues": "[issue=unsupported_attr tag=<strong> attr=style]"
-}
-```
-
-| 字段 | 说明 |
-|------|------|
-| `slide_id` | 新创建页面的唯一标识 |
-| `issues` | 字符串，**只在服务端丢弃过内容时才出现**：页面创建成功，但括号里列出的标签/属性没写进去。出现就必须 `+screenshot` 复核，别当纯警告忽略；干净提交时这个字段不返回 |
-
-## 常见错误
-
-| 现象 | 原因 | 解决 |
-|------|------|------|
-| `--slide is not a single complete <slide> document` | 传了 `<presentation>` 整份 XML，或多个 `<slide>` 拼在一起 | 一次只传一页，根元素必须是 `<slide>` |
-| `--slide cannot be empty` | `@file` 指向空文件，或 stdin 没内容 | 检查文件内容 |
-| 3350001 | XML 结构/转义有问题；**或 `--before-slide-id` 不是有效 `slide_id`** | 优先改用 `--slide @file` 绕开 shell 转义；插页失败先 `+xml-get` 回读确认 `slide_id`；再按 [troubleshooting.md](troubleshooting.md) 排查 |
-| 1061004 / 403 | 当前身份对这份 PPT 没有编辑权限 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope；wiki 链接另需 `wiki:node:read`，`@` 占位符另需 `docs:document.media:upload`；`--as bot` 还要求该 bot 对目标 PPT 有编辑权限 |
+此文件仅保留旧路径兼容性；后续引用请使用新路径。

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

@@ -1,145 +1,5 @@
+# slides +create（创建飞书幻灯片）（兼容入口）
 
-# slides +create（创建飞书幻灯片）
+本文档已迁移至 [`cli/lark-slides-create.md`](cli/lark-slides-create.md)。
 
-创建一个新的飞书幻灯片演示文稿，可选一步添加页面内容。
-
-提交源必须是直接生成的单页 `<slide>` XML。禁止从完整 `<presentation>` XML 解析、拆分、重序列化出 slide 数组再提交。
-
-本命令只从零创建演示文稿，没有导入本地 PPT 文件的参数。要把已有 PPTX 变成 Slides，用 `drive +import --file <x.pptx> --type slides`，再在导入结果上编辑，流程见 [lark-slides-pptx-template-workflows.md](lark-slides-pptx-template-workflows.md)。
-
-## 创建方式选择
-
-| 场景 | 推荐方式 |
-|------|----------|
-| 简单 XML（1-3 页、结构简单、几乎无复杂中文和特殊字符） | `slides +create --slides '[...]'` 一步创建 |
-| 复杂 XML（多页、含中文、大段文本、复杂布局、嵌套引号、特殊字符较多） | **两步创建**：先 `slides +create` 创建空白 PPT，再用 [`+add-slide`](lark-slides-add-slide.md) 逐页添加（`--slide @file` 可绕开 shell 转义） |
-| 已有 PPT 继续追加或插入页面 | 使用 [`+add-slide`](lark-slides-add-slide.md)，必要时配合 `--before-slide-id` |
-
-> [!WARNING]
-> `--slides '[...]'` 的风险点主要在 shell 参数传递，而不是单纯页数。即使只有 1 页，只要 XML 足够复杂，也建议使用两步创建法。
-> [!IMPORTANT]
-> `slides +create --slides` 底层会逐页创建，不是原子操作。中途失败时先记录 `xml_presentation_id`，回读确认当前状态，再继续修复或追加。
-
-## 命令
-
-```bash
-# 创建空白 PPT
-lark-cli slides +create --title "项目汇报"
-
-# 创建 PPT + 添加 slide 页面
-lark-cli slides +create --title "项目汇报" --slides '[
-  "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>封面</p></content></shape></data></slide>",
-  "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>第二页</p></content></shape></data></slide>"
-]'
-
-# 以应用身份创建（自动授权当前用户）
-lark-cli slides +create --title "项目汇报" --as bot
-
-# 预览（不执行）
-lark-cli slides +create --title "项目汇报" --slides '[...]' --dry-run
-```
-
-用 `--slides` 一步创建时，按页保存 XML，再用 `jq --rawfile` 组装参数，不要手写转义：
-
-```bash
-lark-cli slides +create --as user --title "项目汇报" \
-  --slides "$(jq -n \
-    --rawfile s1 .lark-slides/plan/project/slide-01.xml \
-    --rawfile s2 .lark-slides/plan/project/slide-02.xml \
-    '[$s1, $s2]')"
-```
-
-`--rawfile` 会把文件内容作为字符串读入 JSON，自动处理 XML 中的引号和换行；不要手动拼接带大量转义符的 JSON 字符串。
-
-## 返回值
-
-工具成功执行后，返回一个 JSON 对象，包含以下字段：
-
-- **`xml_presentation_id`**（string）：演示文稿的唯一标识符，后续添加页面时需要此 ID
-- **`title`**（string）：演示文稿标题
-- **`url`**（string，可选）：演示文稿的在线链接，如有返回则务必展示给用户（需要 drive 相关权限；若获取失败则不返回此字段）
-- **`revision_id`**（integer）：演示文稿版本号
-- **`slide_ids`**（string[]，可选）：仅传 `--slides` 时返回，成功添加的页面 ID 列表
-- **`slides_added`**（integer，可选）：仅传 `--slides` 时返回，成功添加的页面数量
-- **`images_uploaded`**（integer，可选）：仅 `--slides` 中含 `@<本地路径>` 占位符时返回，已上传的去重后图片数量
-- **`permission_grant`**（object，可选）：仅 `--as bot` 时返回，说明是否已自动为当前 CLI 用户授予可管理权限
-
-> [!IMPORTANT]
-> 不传 `--slides` 时，`slides +create` 只创建空白演示文稿。创建后用 [`+add-slide`](lark-slides-add-slide.md) 逐页添加 slide 内容。
->
-> 传了 `--slides` 时，CLI 先创建空白演示文稿，再逐页调用 slide 创建接口添加页面。如果某一页添加失败，CLI 会停止并报错，已创建的演示文稿和已添加的页面会保留。
->
-> 如果演示文稿是**以应用身份（bot）创建**的，如 `lark-cli slides +create --as bot`，CLI 会**尝试为当前 CLI 用户自动授予该演示文稿的 `full_access`（可管理权限）**。
->
-> 以应用身份创建时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
-> - `status = granted`：当前 CLI 用户已获得该演示文稿的可管理权限
-> - `status = skipped`：本地没有可用的当前用户 `open_id`，因此不会自动授权
-> - `status = failed`：演示文稿已创建成功，但自动授权用户失败
->
-> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--title` | 否 | 演示文稿标题（不传则默认 "Untitled"） |
-| `--slides` | 否 | slide 内容 JSON 数组，每个元素是一个 `<slide>` XML 字符串（最多 10 个；超过 10 页请先用 `+create` 创建空白 PPT，再用 [`+add-slide`](lark-slides-add-slide.md) 逐页添加） |
-
-## `--slides` 参数格式
-
-```json
-[
-  "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\">...第1页XML...</slide>",
-  "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\">...第2页XML...</slide>"
-]
-```
-
-JSON string 数组，每个元素是一页 slide 的完整 XML。CLI 内部负责包装成 API 所需的 `{"slide": {"content": "..."}}` 格式并逐页调用。
-
-### 本地图片：`@<path>` 占位符
-
-`<img>` 元素的 `src` 属性如果以 `@` 开头，CLI 会把它当作本地文件路径，自动上传到当前演示文稿，并把占位符替换为返回的 `file_token`。
-
-```bash
-lark-cli slides +create --as user --title "图测试" --slides '[
-  "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\"><data><img src=\"@./assets/chart.png\" topLeftX=\"100\" topLeftY=\"100\" width=\"320\" height=\"180\"/></data></slide>"
-]'
-```
-
-行为：
-
-- 路径相对于**当前工作目录**（CWD）解析；**必须是 CWD 内的相对路径**（如 `./pic.png`、`./assets/x.png`）
-- 同一份图被多次引用时**只上传一次**（按路径去重）
-- `src` 不以 `@` 开头的会原样保留，但**只允许写 `slides +media-upload` 拿到的 `file_token`**；**禁止写 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 通常显示破图。要用网图必须先下载到 CWD 内、再走上传流程
-- 单张图片最大 20 MB（slides upload API 不支持分片上传）
-- 校验阶段就会检查所有占位符文件存在及大小；缺文件或超限直接报错，不会创建空白 PPT 占位
-- 创空白 PPT → 上传所有图 → 替换 token → 逐页创建 slide，按这个顺序执行
-
-> [!IMPORTANT]
-> **路径必须在 CWD 内**：`@/abs/path/x.png` 或 `@../up/x.png` 这种会被 CLI 拒绝（报 `unsafe file path`）。如果素材在别的目录，先 `cd` 过去再执行。
-
-## 创建后续步骤
-
-如果没有使用 `--slides`，`slides +create` 返回的 `xml_presentation_id` 用于后续操作：
-
-```bash
-# 第 1 步：创建空白 PPT
-PRES_ID=$(lark-cli slides +create --title "项目汇报" | jq -r '.data.xml_presentation_id')
-
-# 第 2 步：逐页添加（--slide 支持 @file，复杂 XML 优先走文件）
-lark-cli slides +add-slide --as user \
-  --presentation "$PRES_ID" \
-  --slide @.lark-slides/plan/<deck>/page1.xml
-```
-
-## 常见错误
-
-| 错误码 | 含义 | 解决方案 |
-|--------|------|----------|
-| 400 | 参数错误 | 检查参数格式是否正确 |
-| 403 | 权限不足 | 检查是否拥有 `slides:presentation:create` 和 `slides:presentation:write_only` scope |
-
-## 相关命令
-
-- [slides +add-slide](lark-slides-add-slide.md) — 追加/插入单页（两步创建的第二步）
-- [slides +xml-get](lark-slides-xml-presentations-get.md) — 读取 PPT 内容并保存到本地文件
+此文件仅保留旧路径兼容性；后续引用请使用新路径。

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

@@ -1,65 +1,5 @@
-# slides +delete-slide（按 slide_id 删除单页）
+# slides +delete-slide（兼容入口）
 
-从演示文稿删除**一页**，按 `slide_id` 指定。只改一页里的局部内容用 [`+replace-slide`](lark-slides-replace-slide.md)，不要删了重建。
+本文档已迁移至 [`xml/lark-slides-delete-slide.md`](xml/lark-slides-delete-slide.md)。
 
-`--presentation` 接受 token / `/slides/` URL / `/wiki/` URL，ID 是普通 flag 而不是 `--params` JSON 串。
-
-> `--slide-id` 只接受单个 ID —— 不支持逗号分隔的列表（`+screenshot` 的 `--slide-id` 支持，这个不支持），也不支持按页号删。
-
-## 命令
-
-```bash
-# 直接传 xml_presentation_id
-lark-cli slides +delete-slide --as user \
-  --presentation "$PID" \
-  --slide-id "$SID"
-
-# slides URL / wiki URL 都可以（wiki 会自动解析并校验 obj_type=slides）
-lark-cli slides +delete-slide --as user \
-  --presentation "https://xxx.feishu.cn/wiki/wikcnXXXXXX" \
-  --slide-id "$SID"
-
-# 删之前先确认打到哪份 PPT、哪一页
-lark-cli slides +delete-slide --presentation "$PID" --slide-id "$SID" --dry-run
-```
-
-## 参数
-
-| 参数 | 必需 | 说明 |
-|------|------|------|
-| `--presentation` | 是 | `xml_presentation_id`、`/slides/` URL 或 `/wiki/` URL |
-| `--slide-id` | 是 | 要删除的页面 ID |
-| `--revision-id` | 否 | 演示文稿版本号，默认 `-1`（最新）；传具体版本号做乐观锁 |
-| `--dry-run` | 否 | 打印将要发起的请求，不删除 |
-
-## 成功输出
-
-```json
-{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "slide_id": "slide_example_id",
-  "deleted": true,
-  "revision_id": 43
-}
-```
-
-## 怎么拿 `slide_id`
-
-`slide_id` 是服务端短 ID，**不能从 XML 里推导**。两个来源：
-
-1. `+create` / `+add-slide` 的返回值里存下来；
-2. 事后回读：`slides +xml-get --presentation "$PID" --output .lark-slides/plan/<deck>/readback.xml`。
-
-删错页的代价高于多跑一次回读 —— 不确定就先回读 + `+screenshot` 看一眼再删。
-
-## 删错了怎么办
-
-删除在原地不可撤销，但可以走历史版本回滚：`+history-list` 找 `history_version_id` → `+history-revert`（只接受 `history_version_id`，不能传 `revision_id`）→ `+history-revert-status` 轮询。命令用法见 [lark-slides-history.md](lark-slides-history.md)。
-
-## 常见错误
-
-| 现象 | 原因 | 解决 |
-|------|------|------|
-| `--slide-id cannot be empty` | 传了空串或纯空格 | 检查变量有没有取到值 |
-| 3350001 `invalid param` | `slide_id` 写错或该页已被删 | `+xml-get` 回读确认 `slide_id` 还在 |
-| 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-edit-workflows.md

@@ -1,146 +1,5 @@
-# 编辑已有 PPT：读-改-写闭环
+# 编辑已有 PPT：读-改-写闭环（兼容入口）
 
-局部编辑走 **shortcut [`+replace-slide`](lark-slides-replace-slide.md)**（块级替换 / 插入），配合 `xml_presentation.slide.get` 读原页拿 `block_id`。一页改动很多、要改背景或删除若干元素，以及一页或多页的整页重建，走 **[`+replace-pages`](lark-slides-replace-pages.md)**，保持原 presentation 链接不变。
+本文档已迁移至 [`workflow/slides_editing.md`](workflow/slides_editing.md)。
 
-> 生成 XML 前**必读** [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。
-
-## 决策树：block_replace vs block_insert
-
-| 需求 | 推荐 action | 理由 |
-|------|------------|------|
-| 已知某块的 `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 链接 |
-
-> **没有字段级 patch**：即便只想改一个 `shape` 的 `topLeftX`，也得把整个块的新 XML 写出来用 `block_replace`。这不是"微调"，是块级重写。
-
-## 最小读-改-写闭环
-
-```bash
-PID="xml_presentation_id_here"
-SID="slide_id_here"
-
-# 1. 读原页，从 XML 里挑出要改的块的 3 位 short id（如 bUn / bab）
-lark-cli slides xml_presentation.slide get --as user \
-  --params "{\"xml_presentation_id\":\"$PID\",\"slide_id\":\"$SID\"}"
-
-# 2. 用 +replace-slide 直接改那个块（不需要搬原 XML）
-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>"}]'
-```
-
-`slide_id` / 页序不会变。`block_replace` 的 `replacement` 根元素 `id` 会自动注入为 `block_id`，用户手写 XML 时不需要自己加。
-
-> **part 的字段名是 `block_id` + `replacement`（XML 字符串）**：写成 `content` / `xml` / `block` 会被 CLI 拒绝（报 `unknown field "content"; did you mean "replacement"?`）。收到这个报错时改字段名，不要改字段值。
-
-## `revision_id` 参数
-
-`--revision-id` 默认 `-1`，表示基于当前最新版执行。传具体版本号时，服务端以该版本为 base 应用变更：
-
-```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')
-
-# 写时传该版本号，服务端以此为 base
-lark-cli slides +replace-slide --as user \
-  --presentation "$PID" --slide-id "$SID" --revision-id "$REV" \
-  --parts '[{"action":"block_replace","block_id":"bUn","replacement":"<shape type=\"rect\" topLeftX=\"100\" topLeftY=\"100\" width=\"200\" height=\"100\"/>"}]'
-```
-
-注意：传不存在的版本号（超过当前 revision）会返回 3350002 not found；不确定时用 `-1` 即可。
-
-## `--tid` 事务锁
-
-跨请求的并发事务 ID，多人协作长事务才用得上。**单人单次调用留空**即可。
-
-## 两种 action 详解
-
-### block_replace — 整块替换
-
-适合"已知块 ID，要换这块整体内容"的场景。`replacement` 根元素的 `id="<block_id>"` 由 CLI 自动注入（用户手写的 XML 如果没带 `id` 直接省略即可；如果带了错的会被覆盖为正确值）。
-
-```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_replace` |
-| `block_id` | 是 | 目标块的 3 位 short element ID（从 `slide.get` 返回的 XML 里读）|
-| `replacement` | 是 | 新 XML 片段；根元素 `id` 会被 CLI 自动注入为 `block_id` |
-
-### block_insert — 整块插入
-
-适合"只想加一个元素，不动现有元素"的场景（典型：给已有页加图）。
-
-```bash
-lark-cli slides +replace-slide --as user \
-  --presentation "$PID" --slide-id "$SID" \
-  --parts "$(jq -n --arg token "$FILE_TOKEN" \
-    '[{action:"block_insert",insertion:("<img src=\""+$token+"\" topLeftX=\"500\" topLeftY=\"100\" width=\"200\" height=\"150\"/>"),insert_before_block_id:"baa"}]')"
-```
-
-字段说明：
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `action` | 是 | 固定为 `block_insert` |
-| `insertion` | 是 | 要插入的完整 XML 片段 |
-| `insert_before_block_id` | 否 | 插到这个块之前；省略（不提供此字段）则追加到页面末尾 |
-
-> **`<img>` 必须用 `file_token`**，不能用外链 URL——先 `slides +media-upload --file ./pic.png --presentation $PID` 拿 token。
-
-### 批量 parts
-
-一次 `--parts` 最多 200 条，按数组顺序串行执行。`block_replace` 和 `block_insert` 可以在同一批次混用。举例：一次性把标题块替换、然后在末尾追加一个装饰图。
-
-```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\"/>"}
-  ]'
-```
-
-整批作为原子事务：任一条失败整批不生效。失败时后端通常返回 3350001；若响应中带 `failed_part_index` / `failed_reason` 字段，shortcut 会原样透传。
-
-## 大 --parts 用 jq 或 stdin 组装
-
-`--parts` 支持 `@file`（读文件）和 `-`（stdin）作为值来源，适合批量 XML 场景：
-
-```bash
-# 从文件读
-lark-cli slides +replace-slide --as user --presentation "$PID" --slide-id "$SID" \
-  --parts @parts.json
-
-# 从 stdin 读
-cat parts.json | lark-cli slides +replace-slide --as user --presentation "$PID" --slide-id "$SID" \
-  --parts -
-```
-
-## 错误排查
-
-| 现象 | 原因 | 对策 |
-|------|------|------|
-| 3350001，hint 含 "block_id not found" | `parts[i].block_id` 在当前页不存在 | 重新 `slide.get` 拿最新 XML，按里面的 short ID 再填 |
-| 3350002 not found | `--revision-id` 传了不存在的版本号 | 用 `-1` 或实际存在的 `revision_id` |
-| `<img>` 不显示 / 显示破图 | `src` 写了外链 URL | 换成通过 `+media-upload` 拿到的 `file_token` |
-| 3350001（block_replace 返回） | 正常情况下 CLI 已自动注入 `id` 和 `<content/>`；如果仍报错，确认 `block_id` 在当前页存在（重新 `slide.get`），检查 XML 结构是否合法；坐标是否超出 960×540 范围 | — |
-
-## 相关文档
-
-- [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-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
-- [xml-schema-quick-ref.md](xml-schema-quick-ref.md) — XML 元素和属性速查
+此文件仅保留旧路径兼容性；后续引用请使用新路径。

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

@@ -1,132 +1,5 @@
-# slides history（历史版本与回滚）
+# slides history（历史版本与回滚）（兼容入口）
 
-用于查看 Slides XML presentation 历史版本、按 `history_version_id` 回滚，以及查询回滚任务状态。
+本文档已迁移至 [`cli/lark-slides-history.md`](cli/lark-slides-history.md)。
 
-`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}'
-```
+此文件仅保留旧路径兼容性；后续引用请使用新路径。