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

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`](cli/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_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-xml.md](workflow/validation-xml.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/>`、包含服务端不支持的元素） | 按 [error-handling.md](workflow/error-handling.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-presentation-slide-get.md

@@ -1,110 +1,5 @@
-# lark-slides xml_presentation.slide get
+# lark-slides xml_presentation.slide get（兼容入口）
 
-## 用途
+本文档已迁移至 [`cli/lark-slides-xml-presentation-slide-get.md`](cli/lark-slides-xml-presentation-slide-get.md)。
 
-按 `slide_id` 拉取指定演示文稿单页的 XML 内容（可指定历史版本）。常用于"读-改-写"编辑闭环的第一步。
-
-## 命令
-
-```bash
-lark-cli slides xml_presentation.slide get --as user --params '<json_params>'
-```
-
-## 参数说明
-
-| 参数 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `--params` | JSON string | 是 | 路径参数与查询参数 |
-
-### params JSON 结构
-
-```json
-{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "slide_id": "slide_example_id",
-  "revision_id": -1
-}
-```
-
-| 字段 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `xml_presentation_id` | string | 是 | 目标演示文稿唯一标识 |
-| `slide_id` | string | 是 | 目标页面唯一标识 |
-| `revision_id` | integer | 否 | 版本号，`-1` 表示最新版（默认）|
-
-## 使用示例
-
-### 读最新版本
-
-```bash
-lark-cli slides xml_presentation.slide get --as user --params '{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "slide_id": "slide_example_id"
-}'
-```
-
-### 只提取 XML 内容
-
-```bash
-lark-cli slides xml_presentation.slide get --as user \
-  --params '{"xml_presentation_id":"slides_example_presentation_id","slide_id":"slide_example_id"}' \
-  | jq -r '.data.slide.content'
-```
-
-### 读指定历史版本
-
-```bash
-lark-cli slides xml_presentation.slide get --as user --params '{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "slide_id": "slide_example_id",
-  "revision_id": 42
-}'
-```
-
-## 返回值
-
-```json
-{
-  "ok": true,
-  "identity": "user",
-  "data": {
-    "slide": {
-      "slide_id": "slide_example_id",
-      "content": "<slide id=\"slide_example_id\"><style/><data>...</data></slide>"
-    },
-    "revision_id": 100
-  }
-}
-```
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `data.slide.slide_id` | string | 页面唯一标识 |
-| `data.slide.content` | string | 页面完整 XML（`<slide>` 根节点，不含 xmlns）|
-| `data.revision_id` | integer | 此次读到的版本号，可用于后续 replace 的乐观锁 |
-
-## 常见错误
-
-| 错误码 | 含义 | 解决方案 |
-|--------|------|----------|
-| 404 | 演示文稿或页面不存在 | 检查 `xml_presentation_id` / `slide_id` |
-| 403 | 权限不足 | 需要 `slides:presentation:read` scope，并对该 PPT 有访问权限 |
-| 400 | `revision_id` 不存在 | 传了无效版本号，用 `-1` 或真实存在的版本号 |
-
-## 注意事项
-
-1. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.get` 查看最新参数结构
-2. **block_id 提取**：返回 XML 里每个顶层块（shape、img、table、chart 等）的 `id` 属性即为 `block_id`，通常是 3 字符短码，例如 `<shape id="bUn" ...>`。用以下命令列出当前页所有 block_id：
-
-   ```bash
-   lark-cli slides xml_presentation.slide get --as user \
-     --params "{\"xml_presentation_id\":\"$PID\",\"slide_id\":\"$SID\"}" \
-     | jq -r '.data.slide.content' | grep -oE 'id="[^"]+"' | sed 's/id="//;s/"//'
-   ```
-
-## 相关命令
-
-- [slides +replace-slide](lark-slides-replace-slide.md) — 块级替换 shortcut（推荐）
-- [xml_presentation.slide replace](lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考
-- [slides +xml-get](lark-slides-xml-presentations-get.md) — 读整个 PPT 并保存到本地文件
-- [lark-slides-edit-workflows.md](lark-slides-edit-workflows.md) — 读-改-写闭环
+此文件仅保留旧路径兼容性；后续引用请使用新路径。

package/skills/lark-slides/references/lark-slides-xml-presentation-slide-replace.md

@@ -1,188 +1,5 @@
-# lark-slides xml_presentation.slide replace
+# lark-slides xml_presentation.slide replace（兼容入口）
 
-## 用途
+本文档已迁移至 [`cli/lark-slides-xml-presentation-slide-replace.md`](cli/lark-slides-xml-presentation-slide-replace.md)。
 
-对单页做**块级局部替换**：不覆盖整页，按 patch 列表做 `block_replace`（整块替换）或 `block_insert`（整块插入）。适合"只想加 / 换一个元素、不动其他元素"的场景。
-
-> **推荐**：优先使用 [`+replace-slide`](lark-slides-replace-slide.md) Shortcut——它会自动注入 `id` 和 `<content/>`，直接调本 API 需自己处理这两个约束（见注意事项 5、6）。
-
-## 命令
-
-```bash
-lark-cli slides xml_presentation.slide replace --as user --params '<json_params>' --data '<json_data>'
-```
-
-## 参数说明
-
-| 参数 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `--params` | JSON string | 是 | 路径参数与查询参数 |
-| `--data` | JSON string | 是 | patch 列表 |
-
-### params JSON 结构
-
-```json
-{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "slide_id": "slide_example_id",
-  "revision_id": -1,
-  "tid": "idMock"
-}
-```
-
-| 字段 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `xml_presentation_id` | string | 是 | 演示文稿唯一标识 |
-| `slide_id` | string | 是 | 页面唯一标识 |
-| `revision_id` | integer | 否 | 默认 `-1`（以最新版为基准）；传具体版本号做乐观锁 |
-| `tid` | string | 否 | 事务 ID，一般留空 |
-
-### data JSON 结构
-
-```json
-{
-  "parts": [
-    { "action": "block_replace", "block_id": "bab", "replacement": "<shape .../>" },
-    { "action": "block_insert", "insertion": "<img .../>", "insert_before_block_id": "baa" }
-  ]
-}
-```
-
-| 字段 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `parts` | array | 是 | patch 列表，长度 1~200，顺序执行 |
-
-### parts[] 字段（按 action 不同）
-
-本期 CLI 文档化两种 action：
-
-#### action = "block_replace" — 整块替换
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `action` | 是 | 固定 `block_replace` |
-| `block_id` | 是 | 目标块的 3 位 short element ID（从 `slide.get` 返回的 XML 里读到） |
-| `replacement` | 是 | 新 XML 片段，替换整个目标块 |
-
-#### action = "block_insert" — 整块插入
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `action` | 是 | 固定 `block_insert` |
-| `insertion` | 是 | 要插入的完整 XML 片段 |
-| `insert_before_block_id` | 否 | 插到这个块之前；省略则追加到页面末尾 |
-
-## 使用示例
-
-### block_replace：换一个 shape 的整体内容
-
-```bash
-lark-cli slides xml_presentation.slide replace --as user --params '{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "slide_id": "slide_example_id"
-}' --data '{
-  "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>"
-    }
-  ]
-}'
-```
-
-### block_insert：在已有页上加一张图
-
-```bash
-# 先拿 file_token
-TOKEN=$(lark-cli slides +media-upload --file ./pic.png --presentation "$PID" --as user | jq -r '.data.file_token')
-
-lark-cli slides xml_presentation.slide replace --as user --params "{
-  \"xml_presentation_id\": \"$PID\",
-  \"slide_id\": \"$SID\"
-}" --data "$(jq -n --arg token "$TOKEN" '{
-  parts: [
-    {
-      action: "block_insert",
-      insertion: ("<img src=\"" + $token + "\" topLeftX=\"500\" topLeftY=\"100\" width=\"200\" height=\"150\"/>")
-    }
-  ]
-}')"
-```
-
-### 多条 parts 原子执行
-
-```bash
-lark-cli slides xml_presentation.slide replace --as user --params '{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "slide_id": "slide_example_id"
-}' --data '{
-  "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\"/>"}
-  ]
-}'
-```
-
-## 返回值
-
-### 成功
-
-```json
-{
-  "ok": true,
-  "identity": "user",
-  "data": {
-    "revision_id": 105
-  }
-}
-```
-
-### 失败（任一 part 失败，整批不生效）
-
-失败时命令以非零退出码结束，stderr 返回类型化错误信封（`error.code`（如 3350001）/ `error.message` / `error.hint`），stdout 不会打印后端原始响应：
-
-```json
-{
-  "ok": false,
-  "identity": "user",
-  "error": {
-    "type": "api",
-    "subtype": "...",
-    "code": 3350001,
-    "message": "...",
-    "hint": "..."
-  }
-}
-```
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `data.revision_id` | integer | 成功时返回更新后最新版本号 |
-
-## 常见错误
-
-| 错误码 | 含义 | 解决方案 |
-|--------|------|----------|
-| 3350001 | `block_id` 在当前页不存在，或 XML 格式 / 结构错误 | 重新 `slide.get` 拿最新 XML，确认 `block_id` 存在；检查 `replacement` / `insertion` 是否合法 XML |
-| 400 | `parts` 长度超过 200 | 拆多次调用 |
-| 3350002 | `revision_id` 不存在（超过当前版本号） | 用 `-1` 或实际存在的 `revision_id` |
-| 400 | XML 格式错误 | `replacement` / `insertion` 必须为合法的 XML 片段，标签闭合 + 属性引号 |
-| 403 | 权限不足 | 需要 `slides:presentation:update` 或 `slides:presentation:write_only` |
-
-## 注意事项
-
-1. **parts 原子事务**：任一条失败整批回滚，不会出现"前几条成功、后几条失败"的中间态。
-2. **block_id 的获取**：`slide.get` 返回的 XML 里每个块（shape、img、table、chart 等）会带 3 位 short element ID，用这个值填 `block_id` / `insert_before_block_id`。
-3. **`<img>` 必须用 file_token**：不能用外链 URL——先 [`slides +media-upload`](lark-slides-media-upload.md) 拿 token。
-4. **不能字段级 patch**：要改一个块的某个属性（比如只改 `topLeftX`），得写整块新 XML 走 `block_replace`；API 不支持"只改一个字段"。
-5. **`block_replace` 要求 `replacement` 根元素带 `id="<block_id>"`**：底层 API 的硬约束，缺失会返回 3350001。推荐走 shortcut [`+replace-slide`](lark-slides-replace-slide.md)——它会自动把 `id` 注入到 `replacement` 根元素上，用户写 XML 时不用自己加。
-6. **`<shape>` 必须有 `<content/>` 子元素**：SML 2.0 schema 要求，缺失同样触发 3350001。shortcut [`+replace-slide`](lark-slides-replace-slide.md) 会自动注入 `<content/>`，直接调底层 API 需要自己加。
-7. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.replace` 查看最新参数结构。
-
-## 相关命令
-
-- [slides +replace-slide](lark-slides-replace-slide.md) — 块级替换 shortcut（推荐，自动注入 id）
-- [xml_presentation.slide get](lark-slides-xml-presentation-slide-get.md) — 读原页拿 block short ID
-- [slides +media-upload](lark-slides-media-upload.md) — 上传图片拿 file_token
-- [lark-slides-edit-workflows.md](lark-slides-edit-workflows.md) — 读-改-写闭环 + 决策树
+此文件仅保留旧路径兼容性；后续引用请使用新路径。

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

@@ -1,134 +1,5 @@
-# lark-slides xml_presentations get
+# lark-slides xml_presentations get（兼容入口）
 
-## 用途
+本文档已迁移至 [`cli/lark-slides-xml-presentations-get.md`](cli/lark-slides-xml-presentations-get.md)。
 
-读取飞书幻灯片（PPT）演示文稿的完整 XML 内容信息。
-
-## Shortcut
-
-使用 `slides +xml-get` shortcut，可以把 XML 保存到本地文件，避免终端输出被截断。
-
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "slides_example_presentation_id" \
-  --output .lark-slides/plan/slides_example_presentation_id/readback.xml \
-  --json
-```
-
-### 参数说明
-
-| 参数 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `--presentation` | string | 是 | 演示文稿的唯一标识符 |
-| `--revision-id` | integer | 否 | 版本号，`-1` 表示最新版本 |
-| `--output` | string | 否 | XML 保存路径，必须使用相对路径；省略时 XML 在 stdout 的 JSON envelope 中返回 |
-| `--remove-attr-id` | flag | 否 | 移除 XML id 属性后读取 |
-| `--json` | flag | 否 | `--format json` 的简写，json 为默认输出格式 |
-
-
-### 基础示例
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "slides_example_presentation_id" \
-  --output .lark-slides/plan/slides_example_presentation_id/readback.xml \
-  --json
-```
-
-### 指定版本读取
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "slides_example_presentation_id" \
-  --revision-id 10 \
-  --output .lark-slides/plan/slides_example_presentation_id/readback-r10.xml \
-  --json
-```
-
-### 移除 XML id 属性后读取
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "slides_example_presentation_id" \
-  --remove-attr-id \
-  --output .lark-slides/plan/slides_example_presentation_id/readback-no-id.xml \
-  --json
-```
-
-
-## 底层原生命令形态
-
-```bash
-lark-cli slides xml_presentations get --as user --params '<json_params>'
-```
-
-### 参数说明
-
-| 参数 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `--params` | JSON string | 是 | 路径参数与查询参数，结构以 schema 为准 |
-
-### params JSON 结构
-
-```json
-{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "revision_id": -1
-}
-```
-
-| 字段 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `xml_presentation_id` | string | 是 | 演示文稿的唯一标识符 |
-| `revision_id` | integer | 否 | 版本号，`-1` 表示最新版本 |
-
-
-### 返回值
-
-成功时返回演示文稿的完整信息：
-
-```json
-{
-  "ok": true,
-  "identity": "user",
-  "data": {
-    "xml_presentation": {
-      "presentation_id": "slides_example_presentation_id",
-      "revision_id": 1,
-      "content": "<presentation xmlns=\"https://www.larkoffice.com/sml/2.0\" height=\"540\" width=\"960\">...</presentation>"
-    }
-  }
-}
-```
-
-### 返回字段说明
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `data.xml_presentation.presentation_id` | string | 演示文稿唯一标识 |
-| `data.xml_presentation.revision_id` | integer | 版本号 |
-| `data.xml_presentation.content` | string | XML 格式的完整内容 |
-
-### 常见错误
-
-| 错误码 | 含义 | 解决方案 |
-|--------|------|----------|
-| 404 | 演示文稿不存在 | 检查 `xml_presentation_id` 是否正确 |
-| 403 | 权限不足 | 检查是否拥有 `slides:presentation:read` scope，或是否有访问权限 |
-| 400 | 参数格式错误 | 确保 `--params` 是合法的 JSON 字符串 |
-
-
-### 注意事项
-
-1. lark-slides 工作流默认使用 `slides +xml-get`；只有必须直接调底层 API 时，才使用
-2. 直接调用底层 API 前，使用 `lark-cli schema slides.xml_presentations.get` 查看最新的参数结构
-3. 返回的 XML 在 `data.xml_presentation.content` 字段中
-4. 如果只需要部分信息，可以使用 `jq` 等工具过滤返回结果
-5. 不要在普通工作流中把完整 XML 打到终端；用 `slides +xml-get --output` 保存文件
-
-## 相关命令
-
-- [slides +create](lark-slides-create.md) - 创建空白 PPT
-- [slides +add-slide](lark-slides-add-slide.md) - 添加幻灯片页面
-- [slides +delete-slide](lark-slides-delete-slide.md) - 删除幻灯片页面
+此文件仅保留旧路径兼容性；后续引用请使用新路径。

package/skills/lark-slides/references/planning-layer.md

@@ -10,7 +10,7 @@
 2. 选择唯一 plan 目录：`.lark-slides/plan/<deck-or-task-id>/`。
 3. 先创建目录：`mkdir -p .lark-slides/plan/<deck-or-task-id>`。
 4. 写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
-5. 读取 `xml-schema-quick-ref.md`、`visual-planning.md` 和 `asset-planning.md`。
+5. 读取 `xml/xml-schema-quick-ref.md`、`visual-planning.md` 和 `asset-planning.md`。
 6. 按 plan、visual planning 和 asset planning 规则逐页生成 XML，把 `layout_type`、`visual_focus`、`text_density` 转成具体页面几何和文本量约束，并把缺失素材转成可执行兜底视觉。
 7. 创建 PPT 后用 `slides +xml-get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系，空白 PPT 中没有 slide 元素。