@amaster.ai/pi-lark 0.1.2-beta.50 → 0.1.2-beta.52

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

@@ -0,0 +1,65 @@
+# slides +delete-slide（按 slide_id 删除单页）
+
+从演示文稿删除**一页**，按 `slide_id` 指定。只改一页里的局部内容用 [`+replace-slide`](lark-slides-replace-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,6 +1,6 @@
 # 编辑已有 PPT：读-改-写闭环
 
-局部编辑走 **shortcut [`+replace-slide`](lark-slides-replace-slide.md)**（块级替换 / 插入），配合 `xml_presentation.slide.get` 读原页拿 `block_id`。已有 Slides 的多页整页重建走 **[`+replace-pages`](lark-slides-replace-pages.md)**，保持原 presentation 链接不变。
+局部编辑走 **shortcut [`+replace-slide`](lark-slides-replace-slide.md)**（块级替换 / 插入），配合 `xml_presentation.slide.get` 读原页拿 `block_id`。一页改动很多、要改背景或删除若干元素，以及一页或多页的整页重建，走 **[`+replace-pages`](lark-slides-replace-pages.md)**，保持原 presentation 链接不变。
 
 > 生成 XML 前**必读** [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。
 
@@ -11,7 +11,7 @@
 | 已知某块的 `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 链接 |
+| 单页或多页版式重建、整页坐标重排、改页面背景、删除若干元素 | `+replace-pages` | 原 presentation 内按页 create-before/delete-old，不生成新 Slides 链接 |
 
 > **没有字段级 patch**：即便只想改一个 `shape` 的 `topLeftX`，也得把整个块的新 XML 写出来用 `block_replace`。这不是"微调"，是块级重写。
 
@@ -33,6 +33,8 @@ lark-cli slides +replace-slide --as user \
 
 `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 应用变更：
@@ -137,7 +139,7 @@ cat parts.json | lark-cli slides +replace-slide --as user --presentation "$PID"
 ## 相关文档
 
 - [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-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

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

@@ -52,30 +52,8 @@ lark-cli slides +media-upload --file ./pic.png --presentation $PRES_ID --dry-run
 
 ## 使用流程
 
-### 给已有 PPT 加带图新页
-
-```bash
-# 1) 上传图片
-TOKEN=$(lark-cli slides +media-upload --as user \
-  --file ./pic.png \
-  --presentation $PRES_ID | jq -r .data.file_token)
-
-# 2) 用 file_token 创建带图新页
-lark-cli slides xml_presentation.slide create --as user \
-  --params "{\"xml_presentation_id\":\"$PRES_ID\"}" \
-  --data "{\"slide\":{\"content\":\"<slide xmlns=\\\"http://www.larkoffice.com/sml/2.0\\\"><data><img src=\\\"$TOKEN\\\" topLeftX=\\\"100\\\" topLeftY=\\\"100\\\" width=\\\"320\\\" height=\\\"180\\\"/></data></slide>\"}}"
-```
-
-### 新建带图 PPT（推荐用 `+create --slides` 的 `@` 占位符，一步到位）
-
-```bash
-# 不需要单独 +media-upload，写 src="@<本地路径>" 即可
-lark-cli slides +create --as user --title "图测试" --slides '[
-  "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><img src=\"@./pic.png\" topLeftX=\"100\" topLeftY=\"100\" width=\"320\" height=\"180\"/></data></slide>"
-]'
-```
-
-详见 [+create 文档](lark-slides-create.md#本地图片path-占位符)。
+> 新建 PPT（[`+create --slides`](lark-slides-create.md)）或给已有 PPT 加新页（[`+add-slide`](lark-slides-add-slide.md)）都不需要单独上传：XML 里把 `<img src>` 写成 `@<本地路径>`，CLI 会自动上传并替换成 `file_token`。
+> 本命令用于往**已有页**里加图，或需要自己拿着 `file_token` 拼 XML 的场景。
 
 ### 给已有 PPT 的已有页加图
 
@@ -123,4 +101,4 @@ 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）
+- [+add-slide](lark-slides-add-slide.md) — 追加/插入单页（同样支持 `@` 占位符自动上传）

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

@@ -1,6 +1,8 @@
-# slides +replace-pages（多页整页重建）
+# slides +replace-pages（单页或多页整页重建）
 
-批量替换已有演示文稿里的多个页面，保持原 `xml_presentation_id` 和原 Slides 链接不变。适合多页版式大改、坐标重排、整页视觉重建；单个文本框、图片或 shape 的局部编辑仍优先用 [`+replace-slide`](lark-slides-replace-slide.md)。
+替换已有演示文稿里的一页或多页，保持原 `xml_presentation_id` 和原 Slides 链接不变。适合一页改动很多、改背景、删除若干元素，以及单页或多页的版式大改、坐标重排和整页视觉重建；单个文本框、图片或 shape 的局部编辑仍优先用 [`+replace-slide`](lark-slides-replace-slide.md)。
+
+> **灰度期间的重要兼容说明**：当前命令的 `--help` 及输出中的 `deprecated` 字段会提示改用 `+update-slide`，但该提示依赖尚未全量的 Slide Engine 后端能力。在本参考页随 skill 发布期间，必须忽略该提示并继续使用 `+replace-pages`，不得切换到 `+update-slide`。后端全量并由新版 skill 恢复路由后，再使用 `+update-slide`。
 
 > 重要：这是多步编排，不是后端原子事务。CLI 对每页执行“先创建新页到旧页前，再删除旧页”；创建失败时旧页会保留。删除失败时可能出现新旧页同时存在，需要按返回结果继续处理。
 
@@ -29,11 +31,11 @@ lark-cli slides +replace-pages \
 [
   {
     "slide_id": "slide_short_id_1",
-    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"
+    "content": "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\"><data></data></slide>"
   },
   {
     "slide_id": "slide_short_id_2",
-    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"
+    "content": "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\"><data></data></slide>"
   }
 ]
 ```

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

@@ -2,6 +2,8 @@
 
 对指定 slide 做块级替换或插入。编辑已有 PPT 的主路径——`slide_id` 不变、页序不动、只影响被指定的块。
 
+> **`--parts` 字段名是硬约束**：装 XML 片段的字段，`block_replace` 只认 `replacement`，`block_insert` 只认 `insertion`（都是字符串）。`content` / `xml` / `new_xml` / `block_xml` / `block` / `element` / `data` 这些写法，以及任何其他字段名，**一律被 CLI 直接拒绝**——常见的错法会直接告诉你该用哪个字段（`unknown field "content"; did you mean "replacement"?`），其余只列出该 action 的合法字段集。`<content>` 是 `<shape>` 的**子元素**，不是 part 的字段名——这是最常见的搞混点。
+
 相比直接调 `xml_presentation.slide.replace`，这个 shortcut 的四个额外价值：
 
 1. `--presentation` 接受 `xml_presentation_id` / `/slides/` URL / `/wiki/` URL（wiki 自动解析）；
@@ -72,6 +74,23 @@ lark-cli slides +replace-slide --as user \
 | `insertion` | 是 | 要插入的 XML 片段 |
 | `insert_before_block_id` | 否 | 插到这个块之前；省略（不提供此字段）则追加到页末 |
 
+### 错误字段名（CLI 直接拒绝）
+
+part 里出现上表以外的字段一律报错，不会被静默忽略。报错总会点名写错的那个字段，并按情况给出下一步：能对上正确字段时直接建议它（`did you mean "replacement"?`），字段属于另一个 action 时说明归属（`it belongs to block_insert`），都对不上时列出该 action 的合法字段集。无论哪种，**要改的是字段名，不是字段值**。
+
+```jsonc
+// ❌ 全部被拒
+[{"action":"block_replace","block_id":"bUn","content":"<p>...</p>"}]        // unknown field "content"; did you mean "replacement"?
+[{"action":"block_replace","block_id":"bUn","xml":"<shape.../>"}]           // 同上（new_xml / block_xml / element / data 一样）
+[{"action":"block_replace","block_id":"bUn","block":{"content":"..."}}]     // 不能把内容嵌一层 block
+[{"action":"block_replace","block_id":"bUn","insertion":"<shape/>"}]        // insertion 属于 block_insert
+[{"action":"block_replace","block_id":"bUn","replacement":{"type":"..."}}]  // replacement 必须是字符串，报 .replacement must be a string
+
+// ✅ 正确
+[{"action":"block_replace","block_id":"bUn","replacement":"<shape type=\"text\"><content><p>新内容</p></content></shape>"}]
+[{"action":"block_insert","insertion":"<shape type=\"rect\" width=\"100\" height=\"100\"/>"}]
+```
+
 ## 合法根元素速查
 
 `block_replace.replacement` 和 `block_insert.insertion` 必须以 SML 2.0 定义的合法元素为根。完整权威定义看 [`slides_xml_schema_definition.xml`](slides_xml_schema_definition.xml)；这里只列能作为**根**的类型 + 每种类型的最小可工作片段。
@@ -224,7 +243,9 @@ lark-cli slides +replace-slide --as user \
 | 3350002 not found | `--revision-id` 传了不存在的版本号（超过当前 revision） | 用 `-1` 或用 `slide.get` 拿到的有效 `revision_id` |
 | `--parts[i] action "str_replace" is not supported` | CLI 不暴露 `str_replace` | 把替换需求改写成 `block_replace` / `block_insert` |
 | `--parts contains N items, exceeds maximum of 200` | 一次提交 parts 太多 | 拆多次调用 |
-| `--parts[i] (block_replace) requires non-empty block_id` / `replacement` | 字段缺失 | 按 parts 元素结构补齐 |
+| `--parts[i] unknown field "content"; did you mean "replacement"?` | XML 塞进了不存在的字段名（`content` / `xml` / `block` / `data` 等） | 只改字段名：`block_replace` 用 `replacement`，`block_insert` 用 `insertion`；报错自带一行正确写法的 hint |
+| `--parts[i] unknown field "insertion"; it belongs to block_insert` | 字段和 `action` 不配对 | 按 action 取字段：`block_replace` = `block_id` + `replacement`；`block_insert` = `insertion` (+ `insert_before_block_id`) |
+| `--parts[i] (block_replace) requires non-empty block_id` / `replacement` | 字段名对，但值缺失或是空串 | 按 parts 元素结构补齐值 |
 | `<img>` 不显示 / 显示破图 | `src` 写了外链 URL | 换成通过 [`+media-upload`](lark-slides-media-upload.md) 拿到的 `file_token` |
 | 3350001 | `replacement` 不是合法单根 XML 片段，或 `block_id` 不存在 | CLI 已自动注入 `id` 和 `<content/>`；如果仍报错，重新 `slide.get` 拿最新 XML 确认 `block_id` 存在；检查 XML 结构是否合法；坐标是否超出 960×540 |
 | 403 | 权限不足 | 需要 `slides:presentation:update` 或 `slides:presentation:write_only`；wiki URL 还需要 `wiki:node:read` |

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

@@ -21,25 +21,40 @@ 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；多页截图时重复传入，或用逗号分隔一次传多个（如 `--slide-id slide_1,slide_2`）；一次最多 10 页（`--slide-id` + `--slide-number` 合计小于等于 10） |
-| `--slide-number` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面页号；多页截图时重复传入，或用逗号分隔一次传多个（如 `--slide-number 1,2,3`）；一次最多 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
 ```
 
 ### 多页截图
@@ -51,7 +66,7 @@ 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-xml-presentations-get.md

@@ -22,9 +22,9 @@ lark-cli slides +xml-get --as user \
 |------|------|------|------|
 | `--presentation` | string | 是 | 演示文稿的唯一标识符 |
 | `--revision-id` | integer | 否 | 版本号，`-1` 表示最新版本 |
-| `--output` | string | 是 | 本地文件，必须使用相对路径 |
+| `--output` | string | 否 | XML 保存路径，必须使用相对路径；省略时 XML 在 stdout 的 JSON envelope 中返回 |
 | `--remove-attr-id` | flag | 否 | 移除 XML id 属性后读取 |
-| `--json` | flag | 是 | 必须按照 json 格式输出 |
+| `--json` | flag | 否 | `--format json` 的简写，json 为默认输出格式 |
 
 
 ### 基础示例
@@ -96,7 +96,7 @@ lark-cli slides xml_presentations get --as user --params '<json_params>'
     "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>"
     }
   }
 }
@@ -130,5 +130,5 @@ lark-cli slides xml_presentations get --as user --params '<json_params>'
 ## 相关命令
 
 - [slides +create](lark-slides-create.md) - 创建空白 PPT
-- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) - 添加幻灯片页面
-- [xml_presentation.slide delete](lark-slides-xml-presentation-slide-delete.md) - 删除幻灯片页面
+- [slides +add-slide](lark-slides-add-slide.md) - 添加幻灯片页面
+- [slides +delete-slide](lark-slides-delete-slide.md) - 删除幻灯片页面

package/skills/lark-slides/references/slides_chart_demo.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<presentation xmlns="/sml/2.0" width="960" height="540">
+<presentation xmlns="https://www.larkoffice.com/sml/2.0" width="960" height="540">
   <title>原生图表 Chart Demo</title>
   <theme>
     <textStyles>

package/skills/lark-slides/references/slides_xml_schema_definition.xml

@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <xs:schema
         xmlns:xs="http://www.w3.org/2001/XMLSchema"
-        xmlns:sml="http://www.larkoffice.com/sml/2.0"
-        targetNamespace="http://www.larkoffice.com/sml/2.0"
+        xmlns:sml="https://www.larkoffice.com/sml/2.0"
+        targetNamespace="https://www.larkoffice.com/sml/2.0"
         elementFormDefault="qualified"
         attributeFormDefault="unqualified">
     <xs:annotation>
@@ -11,7 +11,7 @@
 
             版本信息：
             - Schema 版本: 2.0.0
-            - 命名空间: http://www.larkoffice.com/sml/2.0
+            - 命名空间: https://www.larkoffice.com/sml/2.0
             - 发布日期: 2025-11-03
         </xs:documentation>
     </xs:annotation>
@@ -1052,7 +1052,7 @@
                 单页幻灯片结构
                 子元素:
                 - style: 页面样式(背景色等), style的fill默认颜色为白色rgba(255, 255, 255, 1)
-                - data: 页面元素容器(shape/line/polyline/img/table/icon/chart/undefined)
+                - data: 页面元素容器(shape/line/polyline/img/table/icon/embed/chart/undefined)
                 - note: 演讲者备注
             </xs:documentation>
         </xs:annotation>
@@ -1076,6 +1076,7 @@
                         <xs:element ref="sml:img"/>
                         <xs:element ref="sml:table"/>
                         <xs:element ref="sml:icon"/>
+                        <xs:element ref="sml:embed"/>
                         <xs:element ref="sml:chart"/>
                         <xs:element ref="sml:undefined"/>
                     </xs:choice>
@@ -1622,6 +1623,49 @@
         </xs:complexType>
     </xs:element>
 
+    <!-- 嵌入内容元素 -->
+    <xs:element name="embed">
+        <xs:annotation>
+            <xs:documentation>
+                嵌入内容容器, 外层承载 Slides 摆放和效果属性, 内层承载外部标准内容。
+                当前内层内容为标准 SVG, 必须使用 http://www.w3.org/2000/svg 命名空间。
+                后续可扩展承载 HTML 等其他外部内容。
+
+                必需属性:
+                - topLeftX/topLeftY: 左上角坐标
+                - width/height: 显示尺寸
+
+                可选属性:
+                - id: 唯一标识符
+                - rotation: 旋转角度[0, 360)
+                - flipX/flipY: 水平/垂直翻转
+                - alpha: 不透明度[0,1]
+
+                子元素:
+                - svg: 标准 SVG 根元素, 仅描述嵌入内容, 不承载 Slides 布局属性
+                - reflection: 倒影样式, 无reflection标签代表无倒影, 空reflection标签代表使用默认样式
+                - shadow: 阴影样式, 无shadow标签代表无阴影, 空shadow标签代表使用默认样式
+            </xs:documentation>
+        </xs:annotation>
+        <xs:complexType>
+            <xs:sequence>
+                <xs:any namespace="http://www.w3.org/2000/svg" processContents="lax" minOccurs="1" maxOccurs="1"/>
+                <xs:element name="reflection" type="sml:ReflectionType" minOccurs="0"/>
+                <xs:element name="shadow" type="sml:ShadowType" minOccurs="0"/>
+            </xs:sequence>
+
+            <xs:attribute name="id" type="xs:string" use="optional"/>
+            <xs:attribute name="topLeftX" type="sml:XType" use="required"/>
+            <xs:attribute name="topLeftY" type="sml:YType" use="required"/>
+            <xs:attribute name="width" type="sml:PositiveSize" use="required"/>
+            <xs:attribute name="height" type="sml:PositiveSize" use="required"/>
+            <xs:attribute name="rotation" type="sml:RotationType" use="optional" default="0"/>
+            <xs:attribute name="flipX" type="xs:boolean" use="optional" default="false"/>
+            <xs:attribute name="flipY" type="xs:boolean" use="optional" default="false"/>
+            <xs:attribute name="alpha" type="sml:AlphaType" use="optional" default="1"/>
+        </xs:complexType>
+    </xs:element>
+
     <!-- 表格元素 -->
     <xs:element name="table">
         <xs:annotation>

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

@@ -49,7 +49,6 @@
 | 403 权限不足 | scope 或文档权限不匹配 | 确认 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 | 当前用户对演示文稿无编辑权限 | 确认当前用户对目标 PPT 有编辑权限 |
 | 3350001 | XML 非 well-formed、XML 结构不符合服务端要求，或 replace 片段问题 | 优先检查未转义字符；replace 场景再看 `block_id` 和 `<content/>` |
@@ -60,4 +59,4 @@
 
 - 图片上传、`@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)。
+- 追加/插入单页、`--before-slide-id` 和 `--slide @file` 绕开转义：见 [lark-slides-add-slide.md](lark-slides-add-slide.md)。

package/skills/lark-slides/references/validation-checklist.md

@@ -47,7 +47,7 @@ python3 "<lark-slides-skill-dir>/scripts/xml_text_overlap_lint.py" --input <pres
 - `element_ids`：相关 XML 元素 ID；
 - `rule`：规则 ID、名称、阈值和比较关系；
 - `measurement`：越界量、交叠面积、覆盖率等实测值；
-- `related_objects`：相关对象的类型与坐标框；
+- `related_objects`：相关对象的类型、坐标框，以及指向当前输入 XML 节点的 XPath-like `xml_path`；
 - `target`、`message`、`hint`：页码、语义说明和处理建议。
 
 当 `sparse_container_content.measurement.content_coverage_ratio < rule.threshold` 时，需要结合同页截图判断留白是否有意设计；不要仅凭 warning 自动扩充内容。
@@ -57,7 +57,7 @@ python3 "<lark-slides-skill-dir>/scripts/xml_text_overlap_lint.py" --input <pres
 | code | 含义 | 处理方式 |
 |------|------|----------|
 | `xml_not_well_formed` | XML 语法错误或文本未转义 | 修复标签闭合、属性引号、`&` / `<` / `>` 转义 |
-| `sml_prefixed_tag` | SML 元素使用了命名空间前缀，如 `<ns0:slide>` 或 `<sml:shape>` | 使用 `<slide xmlns="http://www.larkoffice.com/sml/2.0">` 的默认命名空间，或使用无前缀标签 |
+| `sml_prefixed_tag` | SML 元素使用了命名空间前缀，如 `<ns0:slide>` 或 `<sml:shape>` | 使用 `<slide xmlns="https://www.larkoffice.com/sml/2.0">` 的默认命名空间，或使用无前缀标签 |
 | `sxsd_unsupported_tag` | 使用了 SXSD 不支持的标签 | 按 lint `hint` 替换为受支持标签；常见如 `textbox -> <shape type="text">`、`image -> <img>` |
 | `sxsd_unsupported_attr` | 支持的标签上使用了不支持的属性 | 按 lint `hint` 改为支持的属性；常见如 `x -> topLeftX`、`fontColor -> color` |
 | `iconpark_unsupported_icon_type` | `<icon>` 使用了 `iconpark-index.json` 中不存在的 `iconType` | 按 lint `hint` 改为名单内的 `iconType`，或先用 `scripts/iconpark_tool.py` 搜索 |
@@ -66,7 +66,7 @@ python3 "<lark-slides-skill-dir>/scripts/xml_text_overlap_lint.py" --input <pres
 | `bbox_overlap` | 文本元素的估算绘制区域明显重叠 | 拉开文本坐标、缩小文本框/字号，或改成明确的分栏/分组结构 |
 | `*_out_of_canvas` | 元素边界超出页面画布 | 根据 `measurement.overflow` 移回画布或缩小尺寸 |
 | `blank_slide` | 页面没有画布内可见内容 | 补充主体内容；仅有空背景或空形状不能准出 |
-| `sparse_container_content` | 大卡片内容覆盖率低于阈值 | 按元素 ID 定位卡片，结合截图判断是否补充或放大内容 |
+| `sparse_container_content` | 大卡片内容覆盖率低于阈值 | 按 `related_objects[].xml_path` 定位卡片；`element_id` 存在且唯一时也可按 ID 定位，再结合截图判断是否补充或放大内容 |
 | `sparse_slide_content` | 全页有效内容覆盖率偏低 | 复核截图，确认是否为有意留白 |
 
 ## Screenshot QA

package/skills/lark-slides/references/xml-schema-quick-ref.md

@@ -4,7 +4,7 @@
 
 ## 最重要的规则
 
-1. 协议标准写法应使用 `<presentation xmlns="http://www.larkoffice.com/sml/2.0">`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证
+1. 协议标准写法应使用 `<presentation xmlns="https://www.larkoffice.com/sml/2.0">`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证
 2. `<presentation>` 直接子元素只有 `<title>`、`<theme>`、`<slide>`
 3. `<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`
 4. 页面中的文本通常通过 `<content>` 表达，而不是把 `<title>`、`<body>` 直接挂在 `<slide>` 下
@@ -13,7 +13,7 @@
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
-<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+<presentation xmlns="https://www.larkoffice.com/sml/2.0" width="960" height="540">
   <slide>
     <data>
       <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
@@ -81,7 +81,7 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 **子元素：**
 
 - `<style>?` - 页面样式，目前可放 `<fill>`
-- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`chart`、`undefined`
+- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`embed`、`chart`、`undefined`
 - `<note>?` - 演讲者备注，内部可放 `<content>`
 
 这意味着 `<title>`、`<headline>`、`<body>`、`<caption>` 不能直接放在 `<slide>` 下。
@@ -227,17 +227,17 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 ### img
 
 ```xml
-<img src="file_token_or_url" topLeftX="80" topLeftY="120" width="320" height="180"/>
+<img src="file_token_或_@本地路径" topLeftX="80" topLeftY="120" width="320" height="180"/>
 ```
 
 `img` 使用 `topLeftX` / `topLeftY`，不是 `x` / `y`。
 
-`src` 只支持：`slides +media-upload` 返回的 `file_token`，或 `@<本地路径>` 占位符（仅 `+create --slides` 自动上传并替换）。**禁止使用 http(s) 外链 URL**——飞书 slides 渲染端不会代理外链图，外链 src 在 PPT 里通常不显示。本地图片详见 [lark-slides-create.md](lark-slides-create.md#本地图片path-占位符) / [lark-slides-media-upload.md](lark-slides-media-upload.md)。
+`src` 只支持：`slides +media-upload` 返回的 `file_token`，或 `@<本地路径>` 占位符（`+create --slides` 和 `+add-slide` 会自动上传并替换）。**禁止使用 http(s) 外链 URL**——飞书 slides 渲染端不会代理外链图，外链 src 在 PPT 里通常不显示。本地图片详见 [lark-slides-create.md](lark-slides-create.md#本地图片path-占位符) / [lark-slides-media-upload.md](lark-slides-media-upload.md)。
 
 本地图片的两种姿势：
 
 - 新建带图 PPT：`+create --slides` 里直接写 `src="@./pic.png"`，CLI 在创空白 PPT 后、加 slides 前自动上传并替换 token
-- 给已有 PPT 加带图新页：先 `slides +media-upload --file ./pic.png --presentation $PID` 拿 token，再用 token 写进 `xml_presentation.slide create` 的 XML
+- 给已有 PPT 加带图新页：`+add-slide --slide` 的 XML 里直接写 `src="@./pic.png"`，CLI 上传后替换 token 再提交页面
 
 > **注意**：`width`/`height` 是**裁剪后**的显示尺寸。比例和原图不一致时会自动裁剪（无法靠属性关闭），想避免裁剪就让 `width:height` 对齐原图比例。
 
@@ -355,6 +355,20 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 
 详细用法见 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)。
 
+### embed
+
+嵌入内容容器：外层 `<embed>` 承载 Slides 的摆放和效果属性（`topLeftX`/`topLeftY`/`width`/`height` 必填，`rotation`/`flipX`/`flipY`/`alpha` 可选），内层承载外部标准内容。当前内层内容为标准 SVG，`<svg>` 必须使用 `http://www.w3.org/2000/svg` 命名空间，且仅描述嵌入内容本身，不承载 Slides 布局属性。
+
+```xml
+<embed topLeftX="80" topLeftY="120" width="200" height="120">
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 120">
+    <circle cx="100" cy="60" r="40" fill="rgba(37, 99, 235, 1)"/>
+  </svg>
+</embed>
+```
+
+`<embed>` 直接子元素为一个 `<svg>`（必需），以及可选的 `<reflection>`（倒影）与 `<shadow>`（阴影）。
+
 ## 颜色与样式
 
 ### fill
@@ -418,7 +432,7 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
-<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+<presentation xmlns="https://www.larkoffice.com/sml/2.0" width="960" height="540">
   <title>季度报告</title>
   <theme>
     <textStyles>
@@ -466,7 +480,7 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 
 ## 最佳实践
 
-1. 始终带上命名空间 `xmlns="http://www.larkoffice.com/sml/2.0"`
+1. 始终带上命名空间 `xmlns="https://www.larkoffice.com/sml/2.0"`
 2. 用 `shape type="text"` + `content` 表达页面文本
 3. 用 `topLeftX` / `topLeftY`、`startX` / `startY` 等 schema 中定义的属性名
 4. 优先使用 `rgb` / `rgba` 颜色格式；渐变必须使用 `rgba()` 且带百分比停靠点
@@ -481,5 +495,5 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 ## Schema 版本信息
 
 - **版本**: 2.0.0
-- **命名空间**: http://www.larkoffice.com/sml/2.0
+- **命名空间**: https://www.larkoffice.com/sml/2.0
 - **发布日期**: 2025-11-03