@amaster.ai/pi-lark 0.1.15 → 0.1.16

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

@@ -1,110 +1,5 @@
-# lark-slides xml_presentation.slide get
+# slides +xml-get（单页读取兼容入口）
 
-## 用途
+本文档已合并至 [lark-slides-xml-presentations-get.md](lark-slides-xml-presentations-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 '.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\":\"$PRES_ID\",\"slide_id\":\"$SID\"}" \
-     --jq '.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 并保存到本地文件
-- [slides-editing.md](../workflow/slides-editing.md) — 读-改-写闭环
+此文件保留已发布路径兼容性；后续引用请使用该正式 reference。

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

@@ -1,188 +1,11 @@
-# lark-slides xml_presentation.slide replace
+# slides +replace-slide（块级替换 / 插入）
 
-## 用途
-
-对单页做**块级局部替换**：不覆盖整页，按 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 的整体内容
+对指定页面的已知块做替换或插入。先用 `+xml-get --slide-id` 获取最新 `block_id`，再用 `+replace-slide` 写入；该操作不改变页面顺序。
 
 ```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>"
-    }
-  ]
-}'
+lark-cli slides +replace-slide --as user \
+  --presentation "$PRES_ID" --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\" fontSize=\"32\"><p>新标题</p></content></shape>"}]'
 ```
 
-### block_insert：在已有页上加一张图
-
-```bash
-# 先拿 file_token
-TOKEN=$(lark-cli slides +media-upload --file ./pic.png --presentation "$PRES_ID" --as user --jq '.data.file_token')
-
-lark-cli slides xml_presentation.slide replace --as user --params "{
-  \"xml_presentation_id\": \"$PRES_ID\",
-  \"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
-- [slides-editing.md](../workflow/slides-editing.md) — 读-改-写闭环 + 决策树
+`block_replace` 使用 `block_id` 和 `replacement`；追加元素使用 `block_insert` 和 `insertion`。完整 parts 结构、验证和限制见 [lark-slides-replace-slide.md](lark-slides-replace-slide.md)。

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

@@ -1,157 +1,40 @@
-# lark-slides xml_presentations get
+# slides +xml-get（读取演示文稿 XML）
 
-## 用途
+读取全文或单页 XML。全文验证优先将结果保存到本地文件；局部编辑可读取单页 XML，从顶层块的 `id` 属性取得 `+replace-slide` 所需的 `block_id`。
 
-读取飞书幻灯片（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" \
-  --output .lark-slides/plan/slides_example_presentation_id/readback.xml \
-  --json
-```
-
-### 参数说明
-
-| 参数 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `--presentation` | string | 是 | 演示文稿的唯一标识符 |
-| `--revision-id` | integer | 否 | 版本号，`-1` 表示最新版本 |
-| `--output` | string | 否 | XML 保存路径，必须使用相对路径；省略时 XML 在 stdout 的 JSON envelope 中返回 |
-| `--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 为默认输出格式 |
-
-
-### 基础示例
-
-```bash
-lark-cli slides +xml-get --as user \
-  --presentation "slides_example_presentation_id" \
-  --output .lark-slides/plan/slides_example_presentation_id/readback.xml \
-  --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
-```
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--presentation` | 是 | `xml_presentation_id`、Slides URL，或可解析为 Slides 的 wiki URL |
+| `--revision-id` | 否 | 版本号；`-1` 表示最新版本 |
+| `--output` | 否 | XML 保存路径，必须使用 CWD 内相对路径；省略时返回 JSON |
+| `--raw` | 否 | 将 XML 直接输出到 stdout；不能与 `--output`、`--jq` 或非 JSON `--format` 一起使用 |
+| `--slide-id` | 否 | 只读取指定页面；不能与 `--slide-number` 或 `--remove-attr-id` 一起使用 |
+| `--slide-number` | 否 | 只读取指定的 1-based 页码；不能与 `--slide-id` 或 `--remove-attr-id` 一起使用 |
+| `--remove-attr-id` | 否 | 仅全文读取可用；移除 XML `id` 属性，不适合后续精确块编辑 |
 
-### 指定版本读取
+## 示例
 
 ```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 属性后读取
+  --presentation "$PRES_ID" \
+  --output ".lark-slides/plan/$PRES_ID/readback.xml"
 
-```bash
+# 读取单页以获取 block_id
 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
-```
+  --presentation "$PRES_ID" --slide-id "$SID" --raw
 
-
-## 底层原生命令形态
-
-```bash
-lark-cli slides xml_presentations get --as user --params '<json_params>'
+# 读取单页，同时记录 revision_id 用于后续乐观锁
+REV=$(lark-cli slides +xml-get --as user \
+  --presentation "$PRES_ID" --slide-id "$SID" \
+  --jq '.data.revision_id')
 ```
 
-### 参数说明
-
-| 参数 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `--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` 保存文件
+JSON 输出中，全文 XML 位于 `.data.xml_presentation.content`，单页 XML 位于 `.data.slide.content`；二者的 `.data.revision_id` 都可用于后续写操作。
 
-## 相关命令
+相关命令：
 
-- [slides +create](lark-slides-create.md) - 创建空白 PPT
-- [slides +add-slide](lark-slides-add-slide.md) - 添加幻灯片页面
-- [slides +delete-slide](lark-slides-delete-slide.md) - 删除幻灯片页面
+- [slides +replace-slide](lark-slides-replace-slide.md) — 块级替换 / 插入
+- [slides +update-slide](lark-slides-update-slide.md) — 整页覆盖

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

@@ -1,5 +1,5 @@
-# lark-slides xml_presentation.slide get（兼容入口）
+# slides +xml-get（单页读取兼容入口）
 
-本文档已迁移至 [`cli/lark-slides-xml-presentation-slide-get.md`](cli/lark-slides-xml-presentation-slide-get.md)。
+本文档已合并至 [`cli/lark-slides-xml-presentations-get.md`](cli/lark-slides-xml-presentations-get.md)。
 
-此文件仅保留旧路径兼容性；后续引用请使用新路径。
+此文件保留旧路径兼容性；后续引用请使用 `cli/` 下的正式 reference。

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

@@ -1,5 +1,5 @@
-# lark-slides xml_presentation.slide replace（兼容入口）
+# slides +replace-slide（兼容入口）
 
 本文档已迁移至 [`cli/lark-slides-xml-presentation-slide-replace.md`](cli/lark-slides-xml-presentation-slide-replace.md)。
 
-此文件仅保留旧路径兼容性；后续引用请使用新路径。
+此文件保留旧路径兼容性；后续引用请使用 `cli/` 下的正式 reference。

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

@@ -1,5 +1,5 @@
-# lark-slides xml_presentations get（兼容入口）
+# slides +xml-get（兼容入口）
 
 本文档已迁移至 [`cli/lark-slides-xml-presentations-get.md`](cli/lark-slides-xml-presentations-get.md)。
 
-此文件仅保留旧路径兼容性；后续引用请使用新路径。
+此文件保留旧路径兼容性；后续引用请使用 `cli/` 下的正式 reference。

package/skills/lark-slides/references/workflow/error-handling.md

@@ -35,7 +35,7 @@
 | 图表没有显示 | 检查 `chartPlotArea` 和 `chartData` 是否都包含，`dim1` / `dim2` 数据数量是否匹配 |
 | 图片被裁掉一部分 | `<img>` 的 `width` / `height` 是裁剪后尺寸；要整图显示就让 `width:height` 对齐原图比例 |
 | 图片不显示 / `<img src>` 仍是 `@path` | `@` 占位符由 `+create` 和 `+add-slide` 替换 |
-| 新插入的 `<img>` 挡住原有元素 | `slide.get` 读原页，对照已有块坐标挑空白位置；空间不够就在同一批 `--parts` 里先移动/缩小现有块再插图 |
+| 新插入的 `<img>` 挡住原有元素 | 用 `+xml-get --slide-id` 读原页，对照已有块坐标挑空白位置；空间不够就在同一批 `--parts` 里先移动/缩小现有块再插图 |
 | 渐变背景变成白色 | 渐变必须用 `rgba()` 格式 + 百分比停靠点，如 `linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)` |
 | 整体风格不统一 | 封面页和结尾页用同一背景，内容页保持一致的配色和字号体系 |
 
@@ -44,12 +44,12 @@
 | 错误码 / 信号 | 含义 | 解决方案 |
 |--------------|------|----------|
 | 400 XML 格式错误 | XML 语法错误 | 检查标签闭合、属性引号、特殊字符转义 |
-| 400 请求包装错误 | `--data` 未按 schema 包装 | 检查是否传入 `xml_presentation.content` 或 `slide.content` |
+| 400 XML 输入错误 | XML 未按所用 shortcut 的参数传入 | 按 `+create` / `+add-slide` / `+update-slide` reference 检查 `--slides`、`--slide` 或 `--content` 的值 |
 | 创建成功但页面空白 / 内容缺失 / 布局错乱 | 常见于 `--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 |
-| 1061002 媒体上传 params error | slides 媒体上传参数不符合约定 | 用 `slides +media-upload`，不要手拼原生 `medias/upload_all`；slides 唯一可用 `parent_type` 是 `slide_file` |
+| 1061002 媒体上传 params error | slides 媒体上传参数不符合约定 | 用 `slides +media-upload`，由 shortcut 处理 Slides 所需的媒体参数 |
 | 1061004 forbidden | 当前用户对演示文稿无编辑权限 | 确认当前用户对目标 PPT 有编辑权限 |
 | 3350001 | XML 非 well-formed、XML 结构不符合服务端要求，或 replace 片段问题 | 优先检查未转义字符；replace 场景再看 `block_id` 和 `<content/>` |
 | 3350002 | `revision_id` 大于当前版本 | 用 `-1` 取当前版本，或重新用 `slides +xml-get` 取最新 `revision_id` |

package/skills/lark-slides/references/workflow/slides-editing.md

@@ -1,6 +1,6 @@
 # 编辑已有 PPT：读-改-写闭环
 
-局部编辑走 **shortcut [`+replace-slide`](../cli/lark-slides-replace-slide.md)**（块级替换 / 插入），配合 `xml_presentation.slide.get` 读原页拿 `block_id`。整页重建走 **[`+update-slide`](../cli/lark-slides-update-slide.md)**，多页就每页各跑一次 —— 它原地覆盖并保留 `slide_id` 和页序；只有写进 `--content` 且带原 id 的元素才会保留元素 id，遗漏的元素会被删除。
+局部编辑走 **shortcut [`+replace-slide`](../cli/lark-slides-replace-slide.md)**（块级替换 / 插入），配合 `+xml-get --slide-id` 读原页拿 `block_id`。整页重建走 **[`+update-slide`](../cli/lark-slides-update-slide.md)**，多页就每页各跑一次 —— 它原地覆盖并保留 `slide_id` 和页序；只有写进 `--content` 且带原 id 的元素才会保留元素 id，遗漏的元素会被删除。
 
 > 生成 XML 前**必读** [xml-schema-quick-ref.md](../xml/xml-schema-quick-ref.md)。
 
@@ -22,8 +22,8 @@ PRES_ID="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\":\"$PRES_ID\",\"slide_id\":\"$SID\"}"
+lark-cli slides +xml-get --as user \
+  --presentation "$PRES_ID" --slide-id "$SID" --raw
 
 # 2. 用 +replace-slide 直接改那个块（不需要搬原 XML）
 lark-cli slides +replace-slide --as user \
@@ -41,8 +41,8 @@ lark-cli slides +replace-slide --as user \
 
 ```bash
 # 读时拿当前 revision_id
-REV=$(lark-cli slides xml_presentation.slide get --as user \
-  --params "{\"xml_presentation_id\":\"$PRES_ID\",\"slide_id\":\"$SID\"}" \
+REV=$(lark-cli slides +xml-get --as user \
+  --presentation "$PRES_ID" --slide-id "$SID" \
   --jq '.data.revision_id')
 
 # 写时传该版本号，服务端以此为 base
@@ -74,7 +74,7 @@ lark-cli slides +replace-slide --as user \
 | 字段 | 必填 | 说明 |
 |------|------|------|
 | `action` | 是 | 固定为 `block_replace` |
-| `block_id` | 是 | 目标块的 3 位 short element ID（从 `slide.get` 返回的 XML 里读）|
+| `block_id` | 是 | 目标块的 3 位 short element ID（从 `+xml-get --slide-id` 返回的 XML 里读）|
 | `replacement` | 是 | 新 XML 片段；根元素 `id` 会被 CLI 自动注入为 `block_id` |
 
 ### block_insert — 整块插入
@@ -128,16 +128,15 @@ cat parts.json | lark-cli slides +replace-slide --as user --presentation "$PRES_
 
 | 现象 | 原因 | 对策 |
 |------|------|------|
-| 3350001，hint 含 "block_id not found" | `parts[i].block_id` 在当前页不存在 | 重新 `slide.get` 拿最新 XML，按里面的 short ID 再填 |
-| 3350002 not found | `--revision-id` 传了不存在的版本号 | 用 `-1` 或实际存在的 `revision_id` |
+| 3350001，hint 含 "block_id not found" | `parts[i].block_id` 在当前页不存在 | 重新用 `+xml-get --slide-id` 拿最新 XML，按里面的 short ID 再填 |
+| 3350002 not found | `--revision-id` 传了不存在的版本号 | 用 `-1` 或 `+xml-get --slide-id` 返回的 `revision_id` |
 | `<img>` 不显示 / 显示破图 | `src` 写了外链 URL | 换成通过 `+media-upload` 拿到的 `file_token` |
-| 3350001（block_replace 返回） | 正常情况下 CLI 已自动注入 `id` 和 `<content/>`；如果仍报错，确认 `block_id` 在当前页存在（重新 `slide.get`），检查 XML 结构是否合法；坐标是否超出 960×540 范围 | — |
+| 3350001（block_replace 返回） | 正常情况下 CLI 已自动注入 `id` 和 `<content/>`；如果仍报错，确认 `block_id` 在当前页存在（重新 `+xml-get --slide-id`），检查 XML 结构是否合法；坐标是否超出 960×540 范围 | — |
 
 ## 相关文档
 
 - [lark-slides-replace-slide.md](../cli/lark-slides-replace-slide.md) — +replace-slide shortcut 参数详情
 - [lark-slides-update-slide.md](../cli/lark-slides-update-slide.md) — +update-slide shortcut 参数详情（整页覆盖）
-- [lark-slides-xml-presentation-slide-get.md](../cli/lark-slides-xml-presentation-slide-get.md) — slide.get 参考（拿 `block_id` / `revision_id`）
-- [lark-slides-xml-presentation-slide-replace.md](../cli/lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考（一般直接用 shortcut 即可）
+- [lark-slides-xml-presentations-get.md](../cli/lark-slides-xml-presentations-get.md) — `+xml-get` 参数与单页读取方法
 - [lark-slides-media-upload.md](../cli/lark-slides-media-upload.md) — 上传图片拿 file_token
 - [xml-schema-quick-ref.md](../xml/xml-schema-quick-ref.md) — XML 元素和属性速查

package/skills/lark-task/references/lark-task-assign.md

@@ -1,6 +1,6 @@
 # task +assign
 
-> **Prerequisites:** Please read `../lark-shared/SKILL.md` to understand authentication, global parameters, and security rules.
+> **Prerequisites:** Please read `../../lark-shared/SKILL.md` to understand authentication, global parameters, and security rules.
 
 Assign or remove members (assignees) from a task.
 

package/skills/lark-task/references/lark-task-comment.md

@@ -1,6 +1,6 @@
 # task +comment
 
-> **Prerequisites:** Please read `../lark-shared/SKILL.md` to understand authentication, global parameters, and security rules.
+> **Prerequisites:** Please read `../../lark-shared/SKILL.md` to understand authentication, global parameters, and security rules.
 
 Add a comment to an existing task.
 

package/skills/lark-task/references/lark-task-complete.md

@@ -1,6 +1,6 @@
 # task +complete
 
-> **Prerequisites:** Please read `../lark-shared/SKILL.md` to understand authentication, global parameters, and security rules.
+> **Prerequisites:** Please read `../../lark-shared/SKILL.md` to understand authentication, global parameters, and security rules.
 
 Mark a task as completed.
 

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

@@ -1,6 +1,6 @@
 # task +create
 
-> **Prerequisites:** Please read `../lark-shared/SKILL.md` to understand authentication, global parameters, and security rules.
+> **Prerequisites:** Please read `../../lark-shared/SKILL.md` to understand authentication, global parameters, and security rules.
 
 Create a new task in Lark.
 

package/skills/lark-task/references/lark-task-followers.md

@@ -1,6 +1,6 @@
 # task +followers
 
-> **Prerequisites:** Please read `../lark-shared/SKILL.md` to understand authentication, global parameters, and security rules.
+> **Prerequisites:** Please read `../../lark-shared/SKILL.md` to understand authentication, global parameters, and security rules.
 
 Manage task followers. Add or remove followers from an existing task.