@amaster.ai/pi-lark 0.1.6 → 0.1.8

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` 权限。后续按 `validation-checklist.md` 走非截图验证，不要声称已完成截图验收。
+截图失败则降级到 XML 读回、结构 lint等非截图检查路径。
 
 ## 命令
 
@@ -21,37 +21,52 @@ 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-id` / `--slide-number` 之一 | 页面 short ID；多页截图时重复传入；一次最多 10 页（`--slide-id` + `--slide-number` 合计小于等于 10） |
-| `--slide-number` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面页号；多页截图时重复传入；一次最多 10 页（`--slide-id` + `--slide-number` 合计小于等于 10） |
+| `--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` | 否 | render 模式的输出文件名 stem；未指定时优先用返回的 `slide_id`，否则用 `rendered-slide`。若目标文件已存在，会自动追加递增后缀避免覆盖 |
+| `--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
+  --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 页；如需更多页面，分批调用。
+一次不要超过 10 页；如需更多页面，分批调用。可以重复传参，也可以用逗号分隔一次传多个：
 
 ```bash
 lark-cli slides +screenshot --as user \
   --presentation slides_example_presentation_id \
   --slide-number 1 \
   --slide-number 2 \
-  --output-dir .lark-slides/screenshots/demo
+  --output-dir .lark-slides/screenshots/example-deck-task
 ```
 
 ### 渲染 XML 预览
@@ -59,7 +74,7 @@ lark-cli slides +screenshot --as user \
 ```bash
 lark-cli slides +screenshot --as user \
   --content @.lark-slides/out/demo/slide.xml \
-  --output-name preview
+  --output .lark-slides/screenshots/example-deck-task/preview
 ```
 
 ## 返回值
@@ -72,13 +87,13 @@ lark-cli slides +screenshot --as user \
   "identity": "user",
   "data": {
     "xml_presentation_id": "slides_example_presentation_id",
-    "output_dir": ".lark-slides/screenshots",
+    "output": "/abs/path/.lark-slides/screenshots/example-deck-task/page-01.jpg",
     "screenshots": [
       {
         "slide_id": "slide_example_id",
         "slide_number": 1,
-        "format": "png",
-        "path": "/abs/path/.lark-slides/screenshots/slides_example_presentation_id_p001_slide_example_id.png",
+        "format": "jpeg",
+        "path": "/abs/path/.lark-slides/screenshots/example-deck-task/page-01.jpg",
         "size": 12345
       }
     ]
@@ -92,6 +107,9 @@ 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 模式一次最多传 10 页（`--slide-id` + `--slide-number` 合计小于等于 10）；更多页面请分批截图。
-6. list 模式默认文件名包含 presentation ID、页码和/或 slide ID；文件已存在时自动追加 `_2`、`_3` 等后缀，避免覆盖旧截图。
-7. 截图来自服务端渲染结果，适合创建/替换后验证页面是否为空白、破图或布局明显异常。
+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. 截图来自服务端渲染结果，适合创建/替换后验证页面是否为空白、破图或布局明显异常。

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`](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_text_overlap_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-checklist.md](validation-checklist.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/>`、包含服务端不支持的元素） | 按 [troubleshooting.md](troubleshooting.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

@@ -94,7 +94,7 @@ lark-cli slides xml_presentation.slide get --as user --params '{
 ## 注意事项
 
 1. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.get` 查看最新参数结构
-2. **block_id 提取**：返回 XML 里每个顶层块（shape、img、table、chart、whiteboard 等）的 `id` 属性即为 `block_id`，通常是 3 字符短码，例如 `<shape id="bUn" ...>`。用以下命令列出当前页所有 block_id：
+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 \
@@ -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 参考
-- [slides +xml-get](lark-slides-xml-get.md) — 读整个 PPT 并保存到本地文件
+- [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

@@ -173,13 +173,12 @@ lark-cli slides xml_presentation.slide replace --as user --params '{
 ## 注意事项
 
 1. **parts 原子事务**：任一条失败整批回滚，不会出现"前几条成功、后几条失败"的中间态。
-2. **block_id 的获取**：`slide.get` 返回的 XML 里每个块（shape、img、table、chart、whiteboard 等）会带 3 位 short element ID，用这个值填 `block_id` / `insert_before_block_id`。
+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. **`<whiteboard>` 返回结构不含内部数据**：`slide.get` 返回的 whiteboard 块只有外层标签和位置属性，SVG / Mermaid 内容不会随 XML 一起返回。但 `block_replace` 仍然可以强行覆盖——直接写入完整新 whiteboard XML 即可。
-8. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.replace` 查看最新参数结构。
+7. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.replace` 查看最新参数结构。
 
 ## 相关命令
 

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

@@ -2,58 +2,112 @@
 
 ## 用途
 
-读取飞书幻灯片（PPT）演示文稿的完整 XML 内容信息。
+读取飞书幻灯片（PPT）的完整演示文稿 XML，或通过 `--slide-id` / `--slide-number` 读取指定单页 XML。
 
-## 底层原生命令形态
+## Shortcut
+
+使用 `slides +xml-get` shortcut，可以把 XML 保存到本地文件，避免终端输出被截断。
 
 ```bash
-lark-cli slides xml_presentations get --as user --params '<json_params>'
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --output .lark-slides/plan/slides_example_presentation_id/readback.xml \
+  --json
 ```
 
-## 参数说明
+### 参数说明
 
 | 参数 | 类型 | 必需 | 说明 |
 |------|------|------|------|
-| `--params` | JSON string | 是 | 路径参数与查询参数，结构以 schema 为准 |
+| `--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 为默认输出格式 |
 
-### params JSON 结构
 
-```json
-{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "revision_id": -1
-}
+### 基础示例
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --output .lark-slides/plan/slides_example_presentation_id/readback.xml \
+  --json
 ```
 
-| 字段 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `xml_presentation_id` | string | 是 | 演示文稿的唯一标识符 |
-| `revision_id` | integer | 否 | 版本号，`-1` 表示最新版本 |
+### 读取单页并保存
 
-## 使用示例
+按页面 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_presentations get --as user \
-  --params '{"xml_presentation_id":"slides_example_presentation_id","revision_id":-1}'
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --slide-number 1 \
+  --raw
 ```
 
 ### 指定版本读取
 
 ```bash
-lark-cli slides xml_presentations get --as user \
-  --params '{"xml_presentation_id":"slides_example_presentation_id","revision_id":10}'
+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_presentations get --as user \
-  --params '{"xml_presentation_id":"slides_example_presentation_id","revision_id":-1,"remove_attr_id":true}'
+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` 表示最新版本 |
+
+
+### 返回值
 
 成功时返回演示文稿的完整信息：
 
@@ -65,7 +119,7 @@ lark-cli slides xml_presentations get --as user \
     "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>"
+      "content": "<presentation xmlns=\"https://www.larkoffice.com/sml/2.0\" height=\"540\" width=\"960\">...</presentation>"
     }
   }
 }
@@ -79,7 +133,7 @@ lark-cli slides xml_presentations get --as user \
 | `data.xml_presentation.revision_id` | integer | 版本号 |
 | `data.xml_presentation.content` | string | XML 格式的完整内容 |
 
-## 常见错误
+### 常见错误
 
 | 错误码 | 含义 | 解决方案 |
 |--------|------|----------|
@@ -87,13 +141,17 @@ lark-cli slides xml_presentations get --as user \
 | 403 | 权限不足 | 检查是否拥有 `slides:presentation:read` scope，或是否有访问权限 |
 | 400 | 参数格式错误 | 确保 `--params` 是合法的 JSON 字符串 |
 
-## 注意事项
 
-1. 直接调用底层 API 前，使用 `lark-cli schema slides.xml_presentations.get` 查看最新的参数结构
-2. 返回的 XML 在 `data.xml_presentation.content` 字段中
-3. 如果只需要部分信息，可以使用 `jq` 等工具过滤返回结果
+### 注意事项
+
+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 / 添加幻灯片页面
-- [xml_presentation.slide delete](lark-slides-xml-presentation-slide-delete.md) - 删除幻灯片页面
+- [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

@@ -12,7 +12,8 @@
 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 后用 `slides +xml-get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系。
+7. 创建 PPT 后用 `slides +xml-get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系，空白 PPT 中没有 slide 元素。
+
 
 ## Plan Path
 
@@ -57,7 +58,7 @@ Exception:
   "theme_style": "Clean business style, light background, restrained blue accent, strong visual hierarchy.",
   "visual_system": {
     "background_strategy": "Content pages use one light base; cover and closing may use a related dark treatment with the same accent system.",
-    "motif": "A reusable left accent bar and consistent card/header treatments.",
+    "motif": "Consistent card style and numbered anchors.",
     "color_roles": {
       "primary": "Used for the dominant structural motif and about 60-70% of visual weight.",
       "secondary": "Used for grouped regions, comparison panels, or supporting categories.",
@@ -87,7 +88,7 @@ Exception:
         "asset_type": "logo",
         "purpose": "Signal product or team identity on the opening page.",
         "suggested_query": "product logo",
-        "fallback_if_missing": "Use a small text badge and abstract shape motif instead of a real logo."
+        "fallback_if_missing": "Create a close-enough image with the image generation tool instead of a real logo."
       },
       "text_density": "low",
       "speaker_intent": "Frame the decision and establish the deck's point of view."
@@ -137,7 +138,7 @@ Optional slide fields:
 }
 ```
 
-When `chart_contract.required == true`, XML generation must produce a `<chart>` element on that slide. A shape, line, polyline, or whiteboard approximation does not satisfy the plan.
+When `chart_contract.required == true`, XML generation must produce a `<chart>` element on that slide. A shape, line, or polyline approximation does not satisfy the plan.
 
 `data_source` must be one of:
 
@@ -181,7 +182,7 @@ Text density must be realistic for the planned geometry. If a page needs long ti
 Before generating XML, define a visual system that can survive the whole deck:
 
 - `background_strategy`: specify the default background for normal content pages, and which page roles may intentionally differ. Do not let pages drift through near-identical but inconsistent background colors.
-- `motif`: choose one or two reusable structural devices, such as a side bar, header rail, numbered node, card treatment, diagram lane, or section band. The motif should appear consistently enough that pages feel related.
+- `motif`: choose one reusable structural device, such as numbered node, card treatment, half-bleed image zone, headline, or footer. The motif should appear consistently enough that pages feel related.
 - `color_roles`: assign primary, secondary, and accent roles. The same color must not mean unrelated things across pages.
 - `cover_content_relationship`: if the cover uses a different dark or image-led treatment, state how it connects to content pages through shared colors, motifs, or geometry.
 - `closing_relationship`: if the closing page mirrors the cover, state that explicitly so it looks intentional rather than like a new theme.
@@ -203,22 +204,22 @@ Do not hard-code a page number just because a previous deck used that pattern. P
 
 ## Asset Planning
 
-`asset_need` is metadata. It can describe a desired figure, diagram, chart, icon, logo, screenshot, or fallback shape-based visual, but it must not require web search, local download, or media upload.
+`asset_need` is metadata. It can describe a desired figure, diagram, chart, icon, logo, screenshot, or fallback visual.
 
 Use an object for one planned asset, an array for multiple real needs, or `asset_type: "none"` when no asset is useful. Each planned asset must include:
 
 - `asset_type`: one of `paper_figure`, `architecture_diagram`, `icon`, `logo`, `chart`, `infographic`, `screenshot`, `flow_diagram`, or `none`.
 - `purpose`: why this asset helps the page's key message.
 - `suggested_query`: short future lookup hint only; do not execute it unless separately requested.
-- `fallback_if_missing`: concrete XML-native visual plan using shapes, labels, tables, whiteboard diagrams, or placeholder panels.
+- `fallback_if_missing`: a plan to create a close-enough image with the image generation tool, or a native `<chart>` for data.
 - `chart_contract`: when `asset_type` is `chart` and the visual is a supported standard data chart, set this optional slide-level field so generation is locked to native `<chart>`.
 
 For detailed rules and examples, read `asset-planning.md`.
 
 Good examples:
 
-- `{"asset_type":"architecture_diagram","purpose":"Explain component relationships.","suggested_query":"service architecture diagram","fallback_if_missing":"Draw a component diagram with grouped boxes, connector arrows, and short labels."}`
-- `{"asset_type":"logo","purpose":"Identify the customer context.","suggested_query":"customer logo","fallback_if_missing":"Use a text label in a small badge."}`
+- `{"asset_type":"architecture_diagram","purpose":"Explain component relationships.","suggested_query":"service architecture diagram","fallback_if_missing":"Render the component diagram with <shape> + <line>."}`
+- `{"asset_type":"logo","purpose":"Identify the customer context.","suggested_query":"customer logo","fallback_if_missing":"Create a close-enough image with the image generation tool instead of a real logo."}`
 - `{"asset_type":"chart","purpose":"Show adoption trend.","suggested_query":"monthly adoption trend chart","fallback_if_missing":"Render a native `<chart>` using the provided series when available; otherwise render a native `<chart>` with mock placeholder values and label it as 模拟数据，仅占位，待替换真实数据."}`
 
 ## XML Generation Contract
@@ -229,7 +230,7 @@ Before writing each slide XML, map the plan fields to concrete decisions:
 - `layout_type` determines the coordinate structure and element types. Use `visual-planning.md` for concrete layout rules.
 - `visual_focus` determines the largest visual region or emphasized object.
 - `text_density` caps visible text volume.
-- `asset_need` informs placeholder diagrams, icons, charts, screenshots, or shape-based fallback visuals only. Missing real assets must use `fallback_if_missing`, not blank regions.
+- `asset_need` informs placeholder diagrams, icons, charts, screenshots, or fallback visuals only. Missing real assets must use `fallback_if_missing`, not blank regions.
 - `chart_contract` locks supported standard data charts to native `<chart>` output. Manual approximations are allowed only when the planned chart type is unsupported by `<chart>` or when the visual is explicitly non-data/decorative.
 
 After creating the PPT, fetch the presentation and verify: