@wagemule/daemon 0.1.2 → 0.1.4

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

@@ -0,0 +1,239 @@
+# slides +replace-slide（块级替换 / 插入）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+对指定 slide 做块级替换或插入。编辑已有 PPT 的主路径——`slide_id` 不变、页序不动、只影响被指定的块。
+
+相比直接调 `xml_presentation.slide.replace`，这个 shortcut 的四个额外价值：
+
+1. `--presentation` 接受 `xml_presentation_id` / `/slides/` URL / `/wiki/` URL（wiki 自动解析）；
+2. `block_replace` 的 `replacement` 根元素 `id="<block_id>"` 由 CLI 自动注入——底层 API 的硬约束（不注入返回 3350001）；直接调原生 API 需自己加，用 Shortcut 则自动注入；
+3. `<shape>` 元素缺少 `<content/>` 子元素时由 CLI 自动注入——SML 2.0 schema 要求每个 `<shape>` 必须有 `<content/>` 子元素，缺失同样触发 3350001；自闭合的 `<shape .../>` 也会被自动展开为 `<shape ...><content/></shape>`；
+4. 3350001 错误时提供上下文感知的 hint，帮助 AI agent 和用户快速定位原因。
+
+## 命令
+
+```bash
+# block_insert：在页末追加一个新元素
+lark-cli slides +replace-slide --as user \
+  --presentation slidesXXXXXXXXXXXXXXXXXXXXXX \
+  --slide-id pfG \
+  --parts '[{"action":"block_insert","insertion":"<shape type=\"rect\" topLeftX=\"500\" topLeftY=\"100\" width=\"200\" height=\"100\"/>"}]'
+
+# block_replace：已知某块 id，整块替换（replacement 根 id 自动注入为 bUn）
+lark-cli slides +replace-slide --as user \
+  --presentation slidesXXXXXXXXXXXXXXXXXXXXXX \
+  --slide-id pfG \
+  --parts '[{"action":"block_replace","block_id":"bUn","replacement":"<shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新标题</p></content></shape>"}]'
+
+# 大 --parts 走文件或 stdin（auto-gen 命令不支持 @file，但 shortcut 支持）
+lark-cli slides +replace-slide --as user \
+  --presentation $PID --slide-id $SID --parts @parts.json
+cat parts.json | lark-cli slides +replace-slide --as user \
+  --presentation $PID --slide-id $SID --parts -
+
+# wiki URL 直接传（CLI 自动 get_node → 拿真实 xml_presentation_id）
+lark-cli slides +replace-slide --as user \
+  --presentation "https://xxx.feishu.cn/wiki/wikcnXXXXXX" --slide-id pfG \
+  --parts '[{"action":"block_insert","insertion":"<shape type=\"rect\" width=\"100\" height=\"100\"/>"}]'
+
+# 预览（不实际调用）
+lark-cli slides +replace-slide --as user \
+  --presentation $PID --slide-id $SID --parts "$PARTS" --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--presentation` | 是 | `xml_presentation_id`、`/slides/<token>` URL，或 `/wiki/<token>` URL |
+| `--slide-id` | 是 | 页面 ID（`xml_presentation.slide.get` / `xml_presentations.get` 都能拿到） |
+| `--parts` | 是 | JSON 数组（`[{...}, ...]`），单次最多 200 条。支持 `@<file>` 和 `-`（stdin）读取 |
+| `--revision-id` | 否 | 基础版本号；默认 `-1` 表示基于最新版执行；传具体版本号时，服务端以该版本为 base 执行；**传不存在的版本号（超过当前 revision）返回 3350002** |
+| `--tid` | 否 | 并发事务 ID；多人协作长事务才用，单次单人调用留空 |
+
+## parts 元素结构
+
+> **限制**：最多 200 条；`block_replace` 和 `block_insert` 可以在同一批次混用。**其他 action（含 `str_replace`）CLI 会直接报错拒绝**。
+
+每条 part 按 `action` 取不同字段：
+
+### action = `block_replace`
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `action` | 是 | `"block_replace"` |
+| `block_id` | 是 | 目标块的 3 位 short element ID（从 `slide.get` 返回 XML 里读） |
+| `replacement` | 是 | 新 XML 片段；**根元素 `id` 会被 CLI 自动注入为 `block_id`**，用户不用自己加（如果已经加了且不一致会被覆盖为正确值） |
+
+### action = `block_insert`
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `action` | 是 | `"block_insert"` |
+| `insertion` | 是 | 要插入的 XML 片段 |
+| `insert_before_block_id` | 否 | 插到这个块之前；省略（不提供此字段）则追加到页末 |
+
+## 合法根元素速查
+
+`block_replace.replacement` 和 `block_insert.insertion` 必须以 SML 2.0 定义的合法元素为根。完整权威定义看 [`slides_xml_schema_definition.xml`](slides_xml_schema_definition.xml)；这里只列能作为**根**的类型 + 每种类型的最小可工作片段。
+
+| 元素 | 用途 | 关键点 |
+|---|---|---|
+| `<shape>` | 矩形/椭圆/三角/文本框等所有形状 | `type` 必填；`<content/>` 缺失时 CLI 会自动注入 |
+| `<line>` | 直线 | 需 `startX/startY/endX/endY` |
+| `<polyline>` | 折线 | `points` 读回时被服务端规整丢弃（几何已入库） |
+| `<img>` | 图片 | `src` 必须是 [`+media-upload`](lark-slides-media-upload.md) 返回的 `file_token`，不能是 URL |
+| `<icon>` | 图标 | `iconType` 取自 iconpark 资源 |
+| `<table>` | 表格 | 整表替换会**重建内部 td id**，旧 td block_id 立即失效 |
+| `<td>` | 单元格局部替换 | 只能 `block_replace`，不能 `block_insert`；`block_id` 必须是最新 `slide.get` 拿到的 td id |
+| `<chart>` | 图表（line/bar/column/pie/area/radar/combo） | 必须嵌 `<chartPlotArea>` + `<chartData>` + `<dim1>/<dim2>/<chartField>` |
+
+**不可作为根元素**：
+
+- `<video>` / `<audio>` / `<whiteboard>` —— SML 2.0 没有这三个原生元素；`<undefined type="video|audio|whiteboard">` 是**导出时**的占位符（服务端遇到不支持的类型时用它代替），**不能写入**。尝试 insert/replace 都会返回 3350001。
+
+### 最小 XML 片段（JSON 嵌入时记得把 `"` 转义成 `\"`）
+
+`<shape>`（文本框；`type` 还可选 `rect`/`ellipse`/`triangle`/`custom` 等）：
+```xml
+<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
+  <content textType="title"><p>标题</p></content>
+</shape>
+```
+
+`<img>`：
+```xml
+<img src="{file_token}" topLeftX="600" topLeftY="20" width="80" height="80"/>
+```
+
+`<polyline>`：
+```xml
+<polyline topLeftX="10" topLeftY="10" width="100" height="50" points="0,0 50,50 100,0"/>
+```
+
+`<table>`（2×2）：
+```xml
+<table topLeftX="30" topLeftY="80">
+  <colgroup><col span="2" width="110"/></colgroup>
+  <tr><td><content><p>A</p></content></td><td><content><p>B</p></content></td></tr>
+  <tr><td><content><p>C</p></content></td><td><content><p>D</p></content></td></tr>
+</table>
+```
+
+`<td>`（`block_replace` 单元格；`block_id` 必须是最新 `slide.get` 拿到的 td id）：
+```xml
+<td><content><p>新内容</p></content></td>
+```
+
+`<chart>`（`type` 改成 `bar`/`column`/`pie`/`area`/`radar`/`combo` 切换图型）：
+```xml
+<chart topLeftX="30" topLeftY="300" width="300" height="200">
+  <chartPlotArea><chartPlot type="line"/></chartPlotArea>
+  <chartData>
+    <dim1><chartField name="x" valueType="string">Q1,Q2,Q3,Q4</chartField></dim1>
+    <dim2><chartField name="Sales" valueType="number">10,20,15,30</chartField></dim2>
+  </chartData>
+</chart>
+```
+
+## 返回值
+
+```json
+{
+  "xml_presentation_id": "slidesXXXXXXXXXXXXXXXXXXXXXX",
+  "slide_id": "pfG",
+  "parts_count": 1,
+  "revision_id": 102
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `xml_presentation_id` | 解析后的真实 token（wiki URL 解析后会变化） |
+| `slide_id` | 与入参一致 |
+| `parts_count` | 本次提交的 parts 条数 |
+| `revision_id` | 成功后的新版本号，下次做乐观锁时用 |
+| `failed_part_index` | 有部分失败时存在，指向第几条 part 失败 |
+| `failed_reason` | 失败原因文字描述 |
+
+整批作为原子事务：任一 part 失败则整批不生效，服务端通过 `failed_part_index` / `failed_reason` 告诉你是哪条；按此定位修正后重发。
+
+## 使用流程
+
+### 给已有页加图（典型场景）
+
+```bash
+PID=xxx
+SID=yyy
+
+# 1) 上传图片
+TOKEN=$(lark-cli slides +media-upload --as user \
+  --file ./pic.png --presentation "$PID" | jq -r '.data.file_token')
+
+# 2) block_insert 到页末
+lark-cli slides +replace-slide --as user \
+  --presentation "$PID" --slide-id "$SID" \
+  --parts "$(jq -n --arg token "$TOKEN" \
+    '[{action:"block_insert",insertion:("<img src=\""+$token+"\" topLeftX=\"500\" topLeftY=\"100\" width=\"200\" height=\"150\"/>")}]')"
+```
+
+### 改标题（block_replace）
+
+```bash
+# 先拿原页 XML，从里面找到标题块的 3 位 short id（如 bUn）
+lark-cli slides xml_presentation.slide get --as user \
+  --params "{\"xml_presentation_id\":\"$PID\",\"slide_id\":\"$SID\"}"
+
+# block_replace 换掉整个标题块（id 自动注入）
+lark-cli slides +replace-slide --as user \
+  --presentation "$PID" --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\"><p>新标题</p></content></shape>"}]'
+```
+
+### 批量：一次换标题 + 追加装饰图
+
+`block_replace` 和 `block_insert` 可以在同一个 `--parts` 里混用，整批原子执行。
+
+```bash
+lark-cli slides +replace-slide --as user \
+  --presentation "$PID" --slide-id "$SID" \
+  --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\"/>"}
+  ]'
+```
+
+### 乐观锁
+
+```bash
+# 读时记录 revision_id
+REV=$(lark-cli slides xml_presentation.slide get --as user \
+  --params "{\"xml_presentation_id\":\"$PID\",\"slide_id\":\"$SID\"}" \
+  | jq '.data.revision_id')
+
+# 写时传 --revision-id；传不存在的版本号（超过当前 revision）返回 3350002
+lark-cli slides +replace-slide --as user \
+  --presentation "$PID" --slide-id "$SID" --revision-id "$REV" \
+  --parts "$PARTS"
+```
+
+## 常见错误
+
+| 现象 | 原因 | 对策 |
+|------|------|------|
+| 3350001 + hint "block_id not found" | `parts[i].block_id` 在当前页不存在 | 重新 `slide.get` 拿最新 XML，按里面的 short ID 再填 |
+| 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 元素结构补齐 |
+| `<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` |
+
+## 相关命令
+
+- [xml_presentation.slide get](lark-slides-xml-presentation-slide-get.md) — 读原页拿 `block_id` / `revision_id`
+- [xml_presentation.slide replace](lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考
+- [+media-upload](lark-slides-media-upload.md) — 上传图片拿 `file_token`
+- [lark-slides-edit-workflows.md](lark-slides-edit-workflows.md) — 读-改-写闭环 + 决策树

package/dist/skills/larksuite/lark-slides/references/lark-slides-xml-presentation-slide-create.md

@@ -0,0 +1,221 @@
+# lark-slides xml_presentation.slide create
+
+## 用途
+
+在指定的 XML 演示文稿中创建新的幻灯片页面，通常用于给 `slides +create` 创建出的空白 PPT 逐页补充内容。
+
+## 命令
+
+```bash
+lark-cli slides xml_presentation.slide create --as user --params '<json_params>' --data '<json_data>'
+```
+
+## 参数说明
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `--params` | JSON string | 是 | 路径参数与查询参数 |
+| `--data` | JSON string | 是 | 请求体，包含新页面内容 |
+
+### params JSON 结构
+
+```json
+{
+  "xml_presentation_id": "slides_example_presentation_id",
+  "revision_id": -1,
+  "tid": "idMock"
+}
+```
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `xml_presentation_id` | string | 是 | 目标演示文稿的唯一标识符 |
+| `revision_id` | integer | 否 | 演示文稿版本号，`-1` 表示最新版本 |
+| `tid` | string | 否 | 锁的事务 ID |
+
+### data JSON 结构
+
+```json
+{
+  "slide": {
+    "slide_id": "slide_example_id",
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\">...</slide>"
+  },
+  "before_slide_id": "slide_before_target"
+}
+```
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `slide.slide_id` | string | 否 | 幻灯片页面 short ID |
+| `slide.content` | string | 否 | 新幻灯片的 XML 内容 |
+| `before_slide_id` | string | 否 | 插入到指定页面之前 |
+
+## slide XML 结构
+
+`slide.content` 是一个完整的 `<slide>` 元素，遵循 SML 2.0 Schema：
+
+```xml
+<slide xmlns="http://www.larkoffice.com/sml/2.0">
+  <data>
+    <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
+      <content textType="title">
+        <p>标题</p>
+      </content>
+    </shape>
+  </data>
+</slide>
+```
+
+详细格式请参考 [xml-format-guide.md](xml-format-guide.md) 和 [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。
+
+## 使用示例
+
+### 在末尾添加幻灯片
+
+```bash
+lark-cli slides xml_presentation.slide create --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}' --data '{
+  "slide": {
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新页面标题</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"200\" width=\"800\" height=\"180\"><content textType=\"body\"><p>内容文本</p></content></shape></data></slide>"
+  }
+}'
+```
+
+### 在指定页面前插入幻灯片
+
+```bash
+lark-cli slides xml_presentation.slide create --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}' --data '{
+  "slide": {
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>插入的标题页</p></content></shape></data></slide>"
+  },
+  "before_slide_id": "slide_before_target"
+}'
+```
+
+### 带图形元素的幻灯片
+
+```bash
+lark-cli slides xml_presentation.slide create --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}' --data '{
+  "slide": {
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"520\" height=\"120\"><content textType=\"title\"><p>数据展示</p></content></shape><shape type=\"rect\" topLeftX=\"700\" topLeftY=\"100\" width=\"200\" height=\"150\"><fill><fillColor color=\"rgb(100, 149, 237)\"/></fill></shape></data></slide>"
+  }
+}'
+```
+
+### 从文件读取 XML
+
+```bash
+# 先创建 slide.xml 文件
+cat > slide.xml << 'EOF'
+<slide xmlns="http://www.larkoffice.com/sml/2.0">
+  <data>
+    <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
+      <content textType="title">
+        <p>从文件加载</p>
+      </content>
+    </shape>
+    <shape type="text" topLeftX="80" topLeftY="200" width="800" height="180">
+      <content textType="body">
+        <p>这是从文件读取的幻灯片内容</p>
+      </content>
+    </shape>
+  </data>
+</slide>
+EOF
+
+# 然后创建幻灯片
+lark-cli slides xml_presentation.slide create --as user \
+  --params '{"xml_presentation_id":"slides_example_presentation_id"}' \
+  --data "$(jq -n --arg content "$(cat slide.xml)" '{slide:{content:$content}}')"
+```
+
+## 返回值
+
+成功时返回创建的幻灯片信息：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "slide_id": "slide_example_id",
+    "revision_id": 100
+  },
+  "msg": "success"
+}
+```
+
+### 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data.slide_id` | string | 新幻灯片的唯一标识 |
+| `data.revision_id` | integer | 演示文稿最新版本号 |
+
+## slide 元素可用子元素
+
+| 元素 | 说明 |
+|------|------|
+| `<style>` | 页面样式（背景填充） |
+| `<data>` | 图形元素容器（shape、img、table、chart 等） |
+| `<note>` | 演讲者备注 |
+
+> [!IMPORTANT]
+> **本地图片必须先上传**：`xml_presentation.slide.create` 不识别 `@./local.png` 占位符（那是 `+create --slides` 的语法糖）。直接调本接口添加带图新页时，必须先用 [`slides +media-upload`](lark-slides-media-upload.md) 拿到 `file_token`，再写进 `<img src="<file_token>">`。
+>
+> 如果是从零开始建带图 PPT，**强烈建议改用 [`slides +create --slides '[...]'`](lark-slides-create.md#本地图片path-占位符)** 一步搞定（自动上传 + 替换 token）。
+
+## 常见错误
+
+| 错误码 | 含义 | 解决方案 |
+|--------|------|----------|
+| 404 | 演示文稿不存在 | 检查 `xml_presentation_id` 是否正确 |
+| 400 | XML 格式错误 | 检查 `slide.content` 是否是完整 `<slide>` 元素 |
+| 400 | 请求体结构错误 | 检查是否按 `slide.content` 和 `before_slide_id` 包装 |
+| 403 | 权限不足 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope |
+| 3350001 | XML 非 well-formed 或服务端参数校验失败 | 优先检查未转义字符：文本 `Q&A -> Q&amp;A`，文本 `<` / `>` 写成 `&lt;` / `&gt;`，属性 URL `a=1&b=2 -> a=1&amp;b=2`；创建前运行 `python3 skills/lark-slides/scripts/layout_lint.py --input <file>` 获取行列和上下文 |
+
+## 注意事项
+
+1. **执行前必做**: 使用 `lark-cli schema slides.xml_presentation.slide.create` 查看最新的参数结构
+2. **slide.content 格式**: 必须是完整的 `<slide>` 元素，不是整个 presentation
+3. **命名空间建议**: 协议标准写法应带 `xmlns`，例如 `<slide xmlns="http://www.larkoffice.com/sml/2.0">`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证
+4. **fill / border 写法**: 颜色填充使用 `<fill><fillColor color="..."/></fill>`，边框常用 `<border color="..." width="2"/>`
+5. **插入位置**: 通过 `before_slide_id` 指定插入目标，而不是用 `position`
+6. **JSON 转义**: 如果直接内联 XML，需要正确转义双引号
+7. **本地预检**: 创建前运行 `layout_lint.py --input <file>`；它检查 XML well-formed 和布局风险，不等价于完整 XSD schema 校验
+8. **建议**: 先使用 `xml_presentations.get` 获取现有结构，再添加新页面
+
+## 批量添加建议
+
+如果需要添加多张幻灯片，建议先明确每一页的 `before_slide_id`，或直接按最终顺序逐页追加：
+
+```bash
+#!/bin/bash
+
+PRESENTATION_ID="slides_example_presentation_id"
+
+declare -a slides=(
+  '<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 1</p></content></shape></data></slide>'
+  '<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 2</p></content></shape></data></slide>'
+  '<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 3</p></content></shape></data></slide>'
+)
+
+for slide_xml in "${slides[@]}"; do
+  payload=$(jq -n --arg content "$slide_xml" '{slide:{content:$content}}')
+  lark-cli slides xml_presentation.slide create --as user --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" --data "$payload"
+done
+```
+
+## 相关命令
+
+- [slides +create](lark-slides-create.md) - 创建空白 PPT
+- [xml_presentations get](lark-slides-xml-presentations-get.md) - 读取 PPT 内容
+- [xml_presentation.slide delete](lark-slides-xml-presentation-slide-delete.md) - 删除幻灯片页面
+- [xml-format-guide.md](xml-format-guide.md) - XML 格式详细规范
+- [xml-schema-quick-ref.md](xml-schema-quick-ref.md) - Schema 快速参考

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

@@ -0,0 +1,123 @@
+# lark-slides xml_presentation.slide delete
+
+## 用途
+
+删除指定 XML 演示文稿中的幻灯片页面。
+
+## 命令
+
+```bash
+lark-cli slides xml_presentation.slide delete --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,
+  "tid": "idMock"
+}
+```
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `xml_presentation_id` | string | 是 | 演示文稿的唯一标识符 |
+| `slide_id` | string | 是 | 要删除的幻灯片唯一标识符 |
+| `revision_id` | integer | 否 | 演示文稿版本号，`-1` 表示最新版本 |
+| `tid` | string | 否 | 锁的事务 ID |
+
+## 使用示例
+
+### 删除指定幻灯片
+
+```bash
+lark-cli slides xml_presentation.slide delete --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id",
+  "slide_id": "slide_example_id"
+}'
+```
+
+### 结合查询删除（使用 jq）
+
+```bash
+# 先读取 XML 内容，确认待删除页面
+lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}' | jq -r '.data.xml_presentation.content'
+
+# 然后按已知 slide_id 删除
+lark-cli slides xml_presentation.slide delete --as user --params '{"xml_presentation_id":"slides_example_presentation_id","slide_id":"slide_example_id"}'
+```
+
+## 返回值
+
+成功时返回删除确认信息：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "revision_id": 100
+  },
+  "msg": "success"
+}
+```
+
+### 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data.revision_id` | integer | 删除后的最新版本号 |
+
+## 常见错误
+
+| 错误码 | 含义 | 解决方案 |
+|--------|------|----------|
+| 404 | 演示文稿不存在 | 检查 `xml_presentation_id` 是否正确 |
+| 404 | 幻灯片不存在 | 检查 `slide_id` 是否正确，或该幻灯片已被删除 |
+| 400 | 无法删除唯一幻灯片 | 演示文稿至少保留一页幻灯片 |
+| 403 | 权限不足 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope |
+
+## 注意事项
+
+1. **执行前必做**: 使用 `lark-cli schema slides.xml_presentation.slide.delete` 查看最新的参数结构
+2. **删除不可逆**: 删除操作无法撤销，请确保已备份重要内容
+3. **至少保留一页**: 演示文稿必须至少保留一页幻灯片，删除最后一页会报错
+4. **版本控制**: 如果依赖版本号并发控制，删除前先确认 `revision_id`
+5. **获取 slide_id**: 创建幻灯片时请保存返回值；仅靠 `get` 返回的 XML 无法直接推导服务端 short ID
+
+## 如何获取 slide_id
+
+### 方法 1: 创建时保存
+
+```bash
+lark-cli slides xml_presentation.slide create --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}' --data '{
+  "slide": {
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新页面</p></content></shape></data></slide>"
+  }
+}'
+```
+
+返回结果中的 `slide_id` 就是后续删除所需的值。
+
+## 批量删除建议
+
+如果需要删除多张幻灯片，建议先整理好待删 `slide_id` 列表，再逐个删除：
+
+```bash
+for slide_id in sld_a sld_b sld_c; do
+  lark-cli slides xml_presentation.slide delete --as user --params "{\"xml_presentation_id\":\"slides_example_presentation_id\",\"slide_id\":\"$slide_id\"}"
+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) - 添加幻灯片页面