@amaster.ai/pi-lark 0.1.2-beta.41 → 0.1.2-beta.42

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

@@ -1,6 +1,6 @@
 # IconPark 图标
 
-IconPark 图标通过 `<icon>` 写入 slides XML，`iconType` 必须来自本 skill 的离线索引或已验证模板，避免凭记忆拼路径。
+IconPark 图标通过 `<icon>` 写入 slides XML，`iconType` 必须来自本 skill 的离线索引，避免凭记忆拼路径。
 
 ## 机器优先流程
 
@@ -25,7 +25,7 @@ python3 skills/lark-slides/scripts/iconpark_tool.py list-categories
 - 默认先检索：语义图标需求必须先用 `iconpark_tool.py search --limit 8` 或 `--limit 10`，让 agent 从候选里结合版面语义二次判断；不要阅读全文索引，也不要编造不存在的 `iconType`。
 - 图标用于概念提示、步骤、状态、指标、角色和导航；不要用无关装饰图标填充版面。
 - 常用尺寸：行内状态图标 16-24px，卡片标题图标 28-40px，主视觉图标 56-96px。
-- 图标必须显式指定颜色并和背景有足够对比；深色背景优先放在浅色圆形/方形底上，或使用 `rgba(255, 255, 255, 1)` 作为图标填充色。
+- 视觉规范要求图标设置非透明 `fillColor`，显式指定颜色并和背景有足够对比；深色背景优先放在浅色圆形/方形底上，或使用 `rgba(255, 255, 255, 1)` 作为图标填充色。
 - 查不到合适图标时，用 shape、line、text 画 XML-native fallback，不留空图标位。
 
 ## 高频示例

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

@@ -5,6 +5,14 @@
 
 创建一个新的飞书幻灯片演示文稿，可选一步添加页面内容。
 
+- 禁止：从完整 <presentation> XML 解析/拆分/重序列化生成提交 payload。
+- 推荐：提交源直接就是单页 <slide> XML；+create --slides 只接受已经人工/程序直接生成的 slide 数组，不接受由
+      presentation 动态拆出来的数组。
+
+- 最稳：复杂 deck 默认空 deck + 单页 slide create，每次只提交一个 <slide>。
+
+- 注意：复杂 XML 不适合直接塞命令行，中文、引号、特殊字符较多时，直接拼接 --slides 容易发生 shell 转义或截断。建议将每页 XML 保存为独立文件，使用 `jq --rawfile` 组装 JSON 数组，避免手动处理 XML 引号和换行。
+
 ## 命令
 
 ```bash
@@ -24,6 +32,18 @@ lark-cli slides +create --title "项目汇报" --as bot
 lark-cli slides +create --title "项目汇报" --slides '[...]' --dry-run
 ```
 
+复杂内容建议按页保存 XML，再用 `jq --rawfile` 组装 `--slides` 参数：
+
+```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 对象，包含以下字段：
@@ -133,5 +153,4 @@ lark-cli slides xml_presentation.slide create --as user \
 
 ## 相关命令
 
-- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) — 添加幻灯片页面
-- [xml_presentations get](lark-slides-xml-presentations-get.md) — 读取 PPT 内容
+- [slides +xml-get](lark-slides-xml-get.md) — 读取 PPT 内容并保存到本地文件

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

@@ -125,4 +125,3 @@ lark-cli slides +replace-slide --as user \
 
 - [+create](lark-slides-create.md) — 新建 PPT（支持 `@` 占位符自动上传图片）
 - [+replace-slide](lark-slides-replace-slide.md) — 给已有页加图 / 换图（`block_insert` / `block_replace`）
-- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) — 创建 slide 页面（拿到 file_token 后塞进 XML）

package/skills/lark-slides/references/lark-slides-pptx-template-workflows.md

@@ -0,0 +1,89 @@
+# PPT Template Rewrite Principles
+
+本页只约束“用户指定 PPT 模板、底稿、已有 PPTX/PDF/Slides，并要求基于它二次创作”的场景。核心原则：模板不是风格参考，而是必须沿用的编辑底稿。
+
+## Import First
+
+用户指定 PPT 模板时，先把模板导入成 Lark Slides。后续写入目标是导入后的 Slides，不是新建一个脱离模板的 deck，也不是先在本地重画 PPTX 再导入。
+
+直接使用以下命令，不需要先加载 `lark-drive` skill：
+
+```bash
+lark-cli drive +import --as user --file "<template.pptx>" --type slides --json
+```
+
+可选参数：用 `--name "<title>"` 指定导入后的 Slides 标题；用 `--folder-token <FOLDER_TOKEN>` 指定目标文件夹。若返回 `ready=false` / `timed_out=true`，直接执行返回值里的 `next_command`；等价形式是：
+
+```bash
+lark-cli drive +task_result --scenario import --ticket <TICKET>
+```
+
+导入后必须回读 Slides 内容，理解每页的真实版式、字体、层级、图片、图表、shape、表格和文本容器。回读结果是模板二创的事实来源。
+
+## Read Before Editing
+
+编辑任何 PPT 页面前，必须先阅读该页面。
+
+如果当前上下文中没有该页内容，必须重新读取页面；这里的“当前上下文”不包含 System Prompt。不能只凭记忆、文件名、缩略图印象或模板整体风格判断来编辑具体页面。
+
+阅读页面时至少判断：
+
+- 该页原本承担的角色，例如封面、章节页、目录、流程、对比、数据、总结。
+- 该页的主要版式结构，例如图文关系、箭头、时间线、节点、表格、图表、左右对照、背景图或产品图。
+- 哪些文本框、shape 标签、表格单元格或图表标签承载内容。
+- 原页面的字体、字号、颜色、对齐、层级和留白关系。
+
+## Edit The Imported Slides Directly
+
+理解页面后，直接在导入后的 Slides 上编辑。允许的操作包括：
+
+- 填写、替换、凝练或删除文字。
+- 替换或补充图片。
+- 更新图表、表格、数字标签或节点标签里的内容。
+- 按需复制、删除或重排模板页。
+- 在源页面没有合适承载位置时，做局部、小范围新增元素。
+
+新增元素只能补足内容缺口，不能成为新的主版式。页面主体仍应由模板原有版式承载。
+
+## Preserve Design
+
+模板二创必须严格沿用原版式和字体，只改内容，不做设计。
+
+默认保留：
+
+- 页面布局、视觉层级、留白和对齐关系。
+- 原字体、字号体系、颜色、文本框位置和 shape 顺序。
+- 背景图、图片、logo、图表、表格、装饰形状、线条、图标和页面结构。
+- 模板中不同页型之间的差异。
+
+不要把模板页改造成统一的通用卡片、白板、标题栏、三栏、2x2 卡片或大面积遮罩。不要把模板当作背景图后另起一套设计系统。
+
+## Content Only
+
+内容必须优先进入原页面已有的文本框、shape 标签、节点、表格单元格、图表标签或注释容器。
+
+如果原容器空间不足，优先：
+
+- 凝练文字。
+- 降低字号但保持原字体体系。
+- 拆分到页面已有的邻近容器。
+- 使用模板已有的注释、标签或补充说明区域。
+- 复制同页或同模板中的原生容器样式做局部补充。
+
+不要为了容纳长文案而重画页面主体结构。不要用新增大卡片遮住原图表、箭头、图片、背景或关键 shape。
+
+## Readback And Tune
+
+完成编辑后必须回读结果，并逐页微调。
+
+回读时重点检查：
+
+- 文字是否溢出、截断、压线或超出容器。
+- 文本是否遮挡图片、图表、shape、箭头、节点或其他文字。
+- shape 顺序是否导致内容被覆盖或遮住。
+- 新内容是否仍然落在模板原有版式中，而不是覆盖模板结构。
+- 字体、字号、颜色、对齐和层级是否仍贴近原页。
+
+发现文字溢出时，优先凝练文字或缩减字号。发现遮挡时，调整 shape 顺序、局部位置或复用原有空白区域解决。只有在这些方法都不能满足内容表达时，才做局部新增或删除。
+
+模板二创的完成标准不是“生成了一套看起来统一的新 PPT”，而是“原模板的版式、字体和视觉结构仍清晰存在，内容已经被准确替换，并且回读后没有溢出和遮挡”。

package/skills/lark-slides/references/lark-slides-replace-pages.md

@@ -89,7 +89,7 @@ lark-cli slides +replace-pages --as user \
 
 ## 使用建议
 
-1. 大幅改写前先 `xml_presentations.get` 保存当前 XML，并记录要替换页面的 `slide_id`。
+1. 大幅改写前先 `slides +xml-get` 保存当前 XML，并记录要替换页面的 `slide_id`。
 2. 生成只含 `slide_id` 的 `pages.json` 后先跑 `--dry-run` 或 `--validate-only`。
 3. 默认不要开 `--continue-on-error`，除非能接受部分页面已替换。
 4. 替换后再回读全文 XML 并截图检查，确认页序、视觉和文本没有破损。

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

@@ -47,7 +47,7 @@ lark-cli slides +replace-slide --as user \
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `--presentation` | 是 | `xml_presentation_id`、`/slides/<token>` URL，或 `/wiki/<token>` URL |
-| `--slide-id` | 是 | 页面 ID（`xml_presentation.slide.get` / `xml_presentations.get` 都能拿到） |
+| `--slide-id` | 是 | 页面 ID（`xml_presentation.slide.get` / `slides +xml-get` 都能拿到） |
 | `--parts` | 是 | JSON 数组（`[{...}, ...]`），单次最多 200 条。支持 `@<file>` 和 `-`（stdin）读取 |
 | `--revision-id` | 否 | 基础版本号；默认 `-1` 表示基于最新版执行；传具体版本号时，服务端以该版本为 base 执行；**传不存在的版本号（超过当前 revision）返回 3350002** |
 | `--tid` | 否 | 并发事务 ID；多人协作长事务才用，单次单人调用留空 |

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

@@ -4,7 +4,7 @@
 
 获取幻灯片页面截图并保存为本地图片文件。默认用于已存在 PPT 页面截图；传入 `--content` 时用于直接渲染单个 `<slide>` XML 片段预览。本 shortcut 会在 CLI 进程内解码并写入文件，stdout 只返回文件路径、大小、页面 ID 等元信息，避免把图片 Base64 输出给模型。
 
-注意：该截图能力受应用白名单限制，绝大多数应用不可用。截图失败时不要引导用户申请 `slides:presentation:screenshot` 权限；记录错误后降级到 XML 读回、结构 lint、文本重叠检查等非截图检查路径。
+注意：该截图能力受应用白名单限制，绝大多数应用不可用。若截图失败，记录错误即可；不要引导用户申请 `slides:presentation:screenshot` 权限。后续按 `validation-checklist.md` 走非截图验证，不要声称已完成截图验收。
 
 ## 命令
 
@@ -26,8 +26,8 @@ lark-cli slides +screenshot --as user \
 | 参数 | 必需 | 说明 |
 |------|------|------|
 | `--presentation` | list 模式必需 | `xml_presentation_id`、`/slides/` URL，或解析后为 slides 的 `/wiki/` URL。传 `--content` 时不能使用 |
-| `--slide-id` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面 short ID；多页截图时重复传入 |
-| `--slide-number` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面页号；多页截图时重复传入 |
+| `--slide-id` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面 short ID；多页截图时重复传入；一次最多 10 页（`--slide-id` + `--slide-number` 合计小于等于 10） |
+| `--slide-number` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面页号；多页截图时重复传入；一次最多 10 页（`--slide-id` + `--slide-number` 合计小于等于 10） |
 | `--content` | render 模式必需 | 要直接渲染的 `<slide>` XML 片段；支持直接传值、`@file`、`-` stdin。传入后不能同时传 `--slide-id` / `--slide-number` |
 | `--output-dir` | 否 | 输出目录，默认 `.lark-slides/screenshots`；必须是当前目录内的相对路径 |
 | `--output-name` | 否 | render 模式的输出文件名 stem；未指定时优先用返回的 `slide_id`，否则用 `rendered-slide`。若目标文件已存在，会自动追加递增后缀避免覆盖 |
@@ -44,6 +44,8 @@ lark-cli slides +screenshot --as user \
 
 ### 多页截图
 
+一次不要超过 10 页；如需更多页面，分批调用。
+
 ```bash
 lark-cli slides +screenshot --as user \
   --presentation slides_example_presentation_id \
@@ -66,7 +68,8 @@ lark-cli slides +screenshot --as user \
 
 ```json
 {
-  "code": 0,
+  "ok": true,
+  "identity": "user",
   "data": {
     "xml_presentation_id": "slides_example_presentation_id",
     "output_dir": ".lark-slides/screenshots",
@@ -79,8 +82,7 @@ lark-cli slides +screenshot --as user \
         "size": 12345
       }
     ]
-  },
-  "msg": "success"
+  }
 }
 ```
 
@@ -90,5 +92,6 @@ lark-cli slides +screenshot --as user \
 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 模式默认文件名包含 presentation ID、页码和/或 slide ID；文件已存在时自动追加 `_2`、`_3` 等后缀，避免覆盖旧截图。
-6. 截图来自服务端渲染结果，适合创建/替换后验证页面是否为空白、破图或布局明显异常。
+5. list 模式一次最多传 10 页（`--slide-id` + `--slide-number` 合计小于等于 10）；更多页面请分批截图。
+6. list 模式默认文件名包含 presentation ID、页码和/或 slide ID；文件已存在时自动追加 `_2`、`_3` 等后缀，避免覆盖旧截图。
+7. 截图来自服务端渲染结果，适合创建/替换后验证页面是否为空白、破图或布局明显异常。

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

@@ -0,0 +1,100 @@
+# slides +xml-get（读取 XML）
+
+读取已有演示文稿的完整 XML，或按 `slide_id` / 页码读取单页 XML。适合创建后验收、编辑前备份、获取 `slide_id` / `revision_id`，以及排查空白页、破图、文本溢出等问题。相比直接调用底层 `xml_presentations.get` / `xml_presentation.slide.get`，本 shortcut 会自动解析 Slides URL / Wiki URL，并可把 XML 保存到本地文件，避免终端输出被截断。
+
+## 命令
+
+
+```bash
+lark-cli slides +xml-get \
+  --as user \
+  --presentation <slides_url_or_xml_presentation_id> \
+  --output .lark-slides/plan/<deck-id>/readback.xml
+```
+
+## 参数
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--presentation` | 是 | `xml_presentation_id`、`/slides/` URL 或 `/wiki/` URL |
+| `--output` | 否 | 本地 XML 保存路径，必须是当前工作目录内的相对路径，不能传绝对路径。传入时 XML 内容保存到文件，stdout 只返回保存后的绝对路径、大小等简短元信息；省略时默认返回 JSON envelope |
+| `--slide-id` | 否 | 页面 short ID；传入后只读取该页 XML。不能和 `--slide-number` 同时使用 |
+| `--slide-number` | 否 | 1-based 页码；传入后只读取该页 XML。不能和 `--slide-id` 同时使用 |
+| `--revision-id` | 否 | 读取指定版本；默认 `-1`，表示最新版本 |
+| `--remove-attr-id` | 否 | 仅全文读取可用。移除返回 XML 中的 `id` 属性；适合只读检查，不适合精确块级编辑 |
+| `--raw` | 否 | 省略 `--output` 时直接把 XML 原文写到 stdout，不包 JSON envelope。不能和 `--output` / `--jq` / 非 json `--format` 同时使用 |
+| `--dry-run` | 否 | 预览将调用的 API 和输出方式，不读取真实 XML |
+
+## 输出到文件
+
+推荐普通工作流都传 `--output`，尤其是中大型 PPT。`--output` 必须是当前工作目录内的相对路径，例如 `.lark-slides/plan/$PID/readback.xml`，不要传 `/tmp/readback.xml` 这类绝对路径。XML 会写入本地文件，stdout 只保留元信息，便于后续脚本读取。
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "$PID" \
+  --output .lark-slides/plan/$PID/readback.xml
+```
+
+成功输出中的 `data` 类似：
+
+```json
+{
+  "xml_presentation_id": "slides_example_presentation_id",
+  "path": "/abs/path/.lark-slides/plan/slides_example_presentation_id/readback.xml",
+  "size": 123456,
+  "content_saved": true,
+  "revision_id": 12
+}
+```
+
+其中 `path` 是 CLI 解析后的绝对路径。
+
+如果传入 `--remove-attr-id`，返回元信息中会包含 `"remove_attr_id": true`。
+
+## 读取单页
+
+已知页面 short ID 时，用 `--slide-id`：
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "$PID" \
+  --slide-id "$SID" \
+  --output .lark-slides/plan/$PID/slide-$SID.xml
+```
+
+已知页码时，用 `--slide-number`（页码从 1 开始）：
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "$PID" \
+  --slide-number 2 \
+  --output .lark-slides/plan/$PID/slide-2.xml
+```
+
+单页模式底层调用 `xml_presentation.slide.get`，返回或保存的是单个 `<slide>` XML 片段。`--slide-id` 和 `--slide-number` 不能同时传；`--remove-attr-id` 只支持全文读取。
+
+## 输出到终端
+
+省略 `--output` 时，CLI 默认输出 JSON envelope，XML 位于 `data.xml_presentation.content`（全文）或 `data.slide.content`（单页）。这个模式适合配合 `--jq` 临时提取：
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "$PID" \
+  --jq '.data.xml_presentation.content'
+```
+
+需要把 XML 原文直接写到 stdout 时，加 `--raw`：
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "$PID" \
+  --slide-number 2 \
+  --raw
+```
+
+## 相关命令
+
+- [slides +screenshot](lark-slides-screenshot.md) - 获取页面截图做视觉验证
+- [slides +replace-slide](lark-slides-replace-slide.md) - 局部替换或插入页面元素
+- [slides +replace-pages](lark-slides-replace-pages.md) - 多页整页重建
+- [xml_presentations get](lark-slides-xml-presentations-get.md) - 底层原生 API 参考

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

@@ -49,7 +49,10 @@ lark-cli slides xml_presentation.slide delete --as user --params '{
 
 ```bash
 # 先读取 XML 内容，确认待删除页面
-lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}' | jq -r '.data.xml_presentation.content'
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --output .lark-slides/plan/slides_example_presentation_id/readback.xml \
+  --json
 
 # 然后按已知 slide_id 删除
 lark-cli slides xml_presentation.slide delete --as user --params '{"xml_presentation_id":"slides_example_presentation_id","slide_id":"slide_example_id"}'
@@ -61,11 +64,11 @@ lark-cli slides xml_presentation.slide delete --as user --params '{"xml_presenta
 
 ```json
 {
-  "code": 0,
+  "ok": true,
+  "identity": "user",
   "data": {
     "revision_id": 100
-  },
-  "msg": "success"
+  }
 }
 ```
 
@@ -118,6 +121,5 @@ done
 
 ## 相关命令
 
-- [slides +create](lark-slides-create.md) - 创建空白 PPT
-- [xml_presentations get](lark-slides-xml-presentations-get.md) - 读取 PPT 内容
-- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) - 添加幻灯片页面
+- [slides +create](lark-slides-create.md) - 创建 PPT / 添加幻灯片页面
+- [slides +xml-get](lark-slides-xml-get.md) - 读取 PPT 内容并保存到本地文件

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

@@ -65,15 +65,15 @@ lark-cli slides xml_presentation.slide get --as user --params '{
 
 ```json
 {
-  "code": 0,
+  "ok": true,
+  "identity": "user",
   "data": {
     "slide": {
       "slide_id": "slide_example_id",
       "content": "<slide id=\"slide_example_id\"><style/><data>...</data></slide>"
     },
     "revision_id": 100
-  },
-  "msg": "success"
+  }
 }
 ```
 
@@ -106,5 +106,5 @@ lark-cli slides xml_presentation.slide get --as user --params '{
 
 - [slides +replace-slide](lark-slides-replace-slide.md) — 块级替换 shortcut（推荐）
 - [xml_presentation.slide replace](lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考
-- [xml_presentations get](lark-slides-xml-presentations-get.md) — 读整个 PPT
+- [slides +xml-get](lark-slides-xml-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

@@ -130,24 +130,28 @@ lark-cli slides xml_presentation.slide replace --as user --params '{
 
 ```json
 {
-  "code": 0,
+  "ok": true,
+  "identity": "user",
   "data": {
     "revision_id": 105
-  },
-  "msg": "success"
+  }
 }
 ```
 
 ### 失败（任一 part 失败，整批不生效）
 
-失败时返回非零错误码（如 3350001）。若后端能定位失败的 part，`data` 中可能附带：
+失败时命令以非零退出码结束，stderr 返回类型化错误信封（`error.code`（如 3350001）/ `error.message` / `error.hint`），stdout 不会打印后端原始响应：
 
 ```json
 {
-  "code": 3350001,
-  "data": {
-    "failed_part_index": 0,
-    "failed_reason": "block not found"
+  "ok": false,
+  "identity": "user",
+  "error": {
+    "type": "api",
+    "subtype": "...",
+    "code": 3350001,
+    "message": "...",
+    "hint": "..."
   }
 }
 ```
@@ -155,8 +159,6 @@ lark-cli slides xml_presentation.slide replace --as user --params '{
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `data.revision_id` | integer | 成功时返回更新后最新版本号 |
-| `data.failed_part_index` | integer | 失败的 part 在 `parts` 数组中的索引（从 0 起） |
-| `data.failed_reason` | string | 失败原因 |
 
 ## 常见错误
 

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

@@ -4,7 +4,7 @@
 
 读取飞书幻灯片（PPT）演示文稿的完整 XML 内容信息。
 
-## 命令
+## 底层原生命令形态
 
 ```bash
 lark-cli slides xml_presentations get --as user --params '<json_params>'
@@ -35,19 +35,22 @@ lark-cli slides xml_presentations get --as user --params '<json_params>'
 ### 基础示例
 
 ```bash
-lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}'
+lark-cli slides xml_presentations get --as user \
+  --params '{"xml_presentation_id":"slides_example_presentation_id","revision_id":-1}'
 ```
 
-### 结合 jq 格式化输出
+### 指定版本读取
 
 ```bash
-lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}' | jq -r '.data.xml_presentation.content'
+lark-cli slides xml_presentations get --as user \
+  --params '{"xml_presentation_id":"slides_example_presentation_id","revision_id":10}'
 ```
 
-### 保存到文件
+### 移除 XML id 属性后读取
 
 ```bash
-lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}' > presentation_data.json
+lark-cli slides xml_presentations get --as user \
+  --params '{"xml_presentation_id":"slides_example_presentation_id","revision_id":-1,"remove_attr_id":true}'
 ```
 
 ## 返回值
@@ -56,15 +59,15 @@ lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id"
 
 ```json
 {
-  "code": 0,
+  "ok": true,
+  "identity": "user",
   "data": {
     "xml_presentation": {
       "presentation_id": "slides_example_presentation_id",
       "revision_id": 1,
       "content": "<presentation xmlns=\"http://www.larkoffice.com/sml/2.0\" height=\"540\" width=\"960\">...</presentation>"
     }
-  },
-  "msg": "success"
+  }
 }
 ```
 
@@ -86,13 +89,11 @@ lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id"
 
 ## 注意事项
 
-1. **执行前必做**: 使用 `lark-cli schema slides.xml_presentations.get` 查看最新的参数结构
+1. 直接调用底层 API 前，使用 `lark-cli schema slides.xml_presentations.get` 查看最新的参数结构
 2. 返回的 XML 在 `data.xml_presentation.content` 字段中
 3. 如果只需要部分信息，可以使用 `jq` 等工具过滤返回结果
-4. 建议将获取的 XML 保存为文件，便于后续编辑或备份
 
 ## 相关命令
 
-- [slides +create](lark-slides-create.md) - 创建空白 PPT
-- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) - 添加幻灯片页面
+- [slides +create](lark-slides-create.md) - 创建 PPT / 添加幻灯片页面
 - [xml_presentation.slide delete](lark-slides-xml-presentation-slide-delete.md) - 删除幻灯片页面

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

@@ -12,7 +12,7 @@
 4. 写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
 5. 读取 `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 后用 `xml_presentations.get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系。
+7. 创建 PPT 后用 `slides +xml-get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系。
 
 ## Plan Path
 

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

@@ -1,27 +1,16 @@
 # Troubleshooting
 
-本文件覆盖 lark-slides 的通用创建前自检、XML 排障和常见失败处理。命令专属问题优先看对应 reference，例如 `+replace-slide`、`+media-upload`、`xml_presentation.slide.create`。
-
-## XML Preflight
-
-在真正创建或替换前，至少检查：
-
-- 特殊字符已转义：正文和标题里的 `&`、`<`、`>` 不能裸写；属性值里的裸 `&` 也必须写成 `&amp;`。
-- 属性引号安全：XML 属性、shell 引号、JSON 字符串包装之间没有互相打断。
-- 结构合法：`<slide>` 下只放 `<style>`、`<data>`、`<note>`，文本都在 `<content>` 内。
-- 图片路径正确：`<img src="@...">` 只在 `+create --slides` 的支持链路中使用；直接调用 `xml_presentation.slide.create` 必须先拿到 `file_token`。
+本文件覆盖 lark-slides 的 XML 排障和常见失败处理。
 
 ## Failure Order
 
 遇到 `invalid param`、某一页创建失败、页面空白或布局错乱时，按顺序处理：
 
-1. 记录 `xml_presentation_id`，不要假设失败代表什么都没创建。
-2. 用 `xml_presentations.get` 回读，确认是否已有部分页面写入。
+1. 先判断是否已有可用的 `xml_presentation_id`：从成功 stdout、错误 hint、用户给定链接或已保存上下文中获取；没有 ID 时不要回读，直接按当前错误处理。
+2. 如果有 `xml_presentation_id`，再用 `slides +xml-get` 尝试回读，确认是否存在演示文稿、是否已有部分页面写入、或是否只是空 presentation。
 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 文本重叠检查，并人工核对越界、截断、图文压盖等视觉风险；工具当前只会报告 `xml_not_well_formed` / `bbox_overlap`。
-6. 如果使用 `--slides '[...]'`，怀疑 shell 截断时直接切到两步创建：先 `slides +create`，再用 `xml_presentation.slide.create` 逐页添加。
-7. 局部问题用 `+replace-slide` 块级修正；整页结构要改时再用 `slide.delete` 旧页 + `slide.create` 新页。
+5. 如果使用 `--slides '[...]'`，怀疑 shell 截断时直接切到两步创建：先 `slides +create`，再用 `xml_presentation.slide create` 逐页添加。
 
 ## Symptom Fixes
 
@@ -34,10 +23,9 @@
 | 表格列宽不合理 | 调整 `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 --slides` 中替换；直接调 `xml_presentation.slide create` 必须先用 `+media-upload` 拿 `file_token` |
 | 新插入的 `<img>` 挡住原有元素 | `slide.get` 读原页，对照已有块坐标挑空白位置；空间不够就在同一批 `--parts` 里先移动/缩小现有块再插图 |
 | 渐变背景变成白色 | 渐变必须用 `rgba()` 格式 + 百分比停靠点，如 `linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)` |
-| 整体风格不统一 | 封面页和结尾页用同一背景，内容页保持一致的配色和字号体系 |
 
 ## Common Errors
 
@@ -46,18 +34,12 @@
 | 400 XML 格式错误 | XML 语法错误 | 检查标签闭合、属性引号、特殊字符转义 |
 | 400 请求包装错误 | `--data` 未按 schema 包装 | 检查是否传入 `xml_presentation.content` 或 `slide.content` |
 | 创建成功但页面空白 / 内容缺失 / 布局错乱 | 常见于 `--slides '[...]'` 的 shell 转义或长参数传递问题 | 改用两步创建，并在创建后立即读取 XML 验证 |
-| 403 权限不足 | 身份或 scope 不匹配 | 先检查是否误用了 bot 身份，再确认 scope 和文档权限 |
+| 403 权限不足 | 身份或 scope 不匹配 | 先检查是否误用了 bot 身份，再确认 scope 和文档权限；无权限时根据错误响应引导用户解决 |
 | 404 演示文稿不存在 | `xml_presentation_id` 不正确或无权限 | 检查 token；wiki URL 需先解析真实 `obj_token` |
 | 404 幻灯片不存在 | `slide_id` 不正确 | 重新读取 presentation 或 slide，确认最新 ID |
 | 400 无法删除唯一幻灯片 | 演示文稿至少保留一页 | 先创建新页，再删除旧页 |
 | 1061002 媒体上传 params error | slides 媒体上传参数不符合约定 | 用 `slides +media-upload`，不要手拼原生 `medias/upload_all`；slides 唯一可用 `parent_type` 是 `slide_file` |
 | 1061004 forbidden | 当前身份对演示文稿无编辑权限 | 确认 user/bot 对目标 PPT 有编辑权限；bot 常见于 PPT 非该 bot 创建 |
 | 3350001 | XML 非 well-formed、XML 结构不符合服务端要求，或 replace 片段问题 | 优先检查未转义字符；replace 场景再看 `block_id` 和 `<content/>` |
-| 3350002 | `revision_id` 大于当前版本 | 用 `-1` 取当前版本，或重新读 `xml_presentations.get` 取最新 `revision_id` |
+| 3350002 | `revision_id` 大于当前版本 | 用 `-1` 取当前版本，或重新用 `slides +xml-get` 取最新 `revision_id` |
 | validation: unsafe file path | `--file` 给了绝对路径或上层路径 | `--file` 必须是 CWD 内相对路径；先 `cd` 到素材目录再执行 |
-
-## Command-Specific References
-
-- 图片上传、`@path` 占位符、`file_token`：见 [lark-slides-media-upload.md](lark-slides-media-upload.md) 和 [lark-slides-create.md](lark-slides-create.md)。
-- 块级替换、`block_id`、3350001 replace 细节：见 [lark-slides-replace-slide.md](lark-slides-replace-slide.md)。
-- 原生 `slide.create` 包装、`before_slide_id` 和 jq 模板：见 [lark-slides-xml-presentation-slide-create.md](lark-slides-xml-presentation-slide-create.md)。