@wagemule/daemon 0.1.2 → 0.1.4

package/dist/skills/larksuite/lark-slides/references/examples.md

@@ -0,0 +1,261 @@
+# 完整操作示例
+
+本文档提供与 CLI schema 一致的调用示例，XML 内容均遵循 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)。
+
+> **重要**：创建 PPT 请优先使用 `slides +create`；实际页面内容请使用 `xml_presentation.slide.create` 逐页添加。
+
+## 目录
+
+- [示例 1: 使用 Shortcut 创建空白演示文稿](#示例-1-使用-shortcut-创建空白演示文稿)
+- [示例 2: 创建后添加第一页](#示例-2-创建后添加第一页)
+- [示例 3: 读取 XML 内容](#示例-3-读取-xml-内容)
+- [示例 4: 在指定页面前插入新幻灯片](#示例-4-在指定页面前插入新幻灯片)
+- [示例 5: 删除幻灯片](#示例-5-删除幻灯片)
+- [示例 6: 从文件读取 XML 后添加页面](#示例-6-从文件读取-xml-后添加页面)
+- [示例 7: +replace-slide + block_insert 给已有页加图](#示例-7-replace-slide--block_insert-给已有页加图)
+- [示例 8: +replace-slide + block_replace 替换一个块](#示例-8-replace-slide--block_replace-替换一个块)
+
+## 示例 1: 使用 Shortcut 创建空白演示文稿
+
+```bash
+lark-cli slides +create --title "项目汇报"
+```
+
+预期返回结构：
+
+```json
+{
+  "data": {
+    "xml_presentation_id": "slides_example_presentation_id",
+    "title": "项目汇报",
+    "revision_id": 1
+  }
+}
+```
+
+## 示例 2: 创建后添加第一页
+
+```bash
+PRESENTATION_ID=$(lark-cli slides +create --title "季度复盘" | jq -r '.data.xml_presentation_id')
+
+lark-cli slides xml_presentation.slide create --as user --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" --data '{
+  "slide": {
+    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><style><fill><fillColor color=\"rgb(245, 245, 245)\"/></fill></style><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"72\" width=\"760\" height=\"90\"><content textType=\"title\"><p>2024 Q3 季度复盘</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"190\" width=\"520\" height=\"220\"><content textType=\"body\"><p>关键结论</p><ul><li><p>收入增长 30%</p></li><li><p>重点项目全部上线</p></li><li><p>用户满意度持续提升</p></li></ul></content></shape><shape type=\"rect\" topLeftX=\"660\" topLeftY=\"180\" width=\"180\" height=\"140\"><fill><fillColor color=\"rgba(100, 149, 237, 0.25)\"/></fill><border color=\"rgb(100, 149, 237)\" width=\"2\"/></shape></data><note><content textType=\"body\"><p>讲述时先给结论，再补充数据。</p></content></note></slide>"
+  }
+}'
+```
+
+## 示例 3: 读取 XML 内容
+
+```bash
+lark-cli slides xml_presentations get --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}'
+```
+
+提取 XML 内容：
+
+```bash
+lark-cli slides xml_presentations get --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}' | jq -r '.data.xml_presentation.content'
+```
+
+预期返回结构：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "xml_presentation": {
+      "presentation_id": "slides_example_presentation_id",
+      "revision_id": 3,
+      "content": "<presentation xmlns=\"http://www.larkoffice.com/sml/2.0\" height=\"540\" width=\"960\">...</presentation>"
+    }
+  },
+  "msg": "success"
+}
+```
+
+## 示例 4: 在指定页面前插入新幻灯片
+
+```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>"
+  },
+  "before_slide_id": "sld_before_target"
+}'
+```
+
+预期返回结构：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "slide_id": "slide_example_id",
+    "revision_id": 100
+  },
+  "msg": "success"
+}
+```
+
+## 示例 5: 删除幻灯片
+
+```bash
+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": 101
+  },
+  "msg": "success"
+}
+```
+
+## 示例 6: 从文件读取 XML 后添加页面
+
+先准备 `slide.xml`：
+
+```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>
+```
+
+先创建演示文稿：
+
+```bash
+PRESENTATION_ID=$(lark-cli slides +create --title "从文件添加页面" | jq -r '.data.xml_presentation_id')
+```
+
+再用 `jq` 组装请求体，从文件添加页面：
+
+```bash
+lark-cli slides xml_presentation.slide create --as user \
+  --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" \
+  --data "$(jq -n --arg content "$(cat slide.xml)" '{slide:{content:$content}}')"
+```
+
+## 示例 7: +replace-slide + block_insert 给已有页加图
+
+只想在已有页上加一张图、不动其他元素——走 shortcut `+replace-slide`，`block_insert` 追加到页末（或用 `insert_before_block_id` 指定位置）。
+
+```bash
+PID="slides_example_presentation_id"
+SID="slide_example_id"
+
+# 1. 上传图片拿 file_token
+TOKEN=$(lark-cli slides +media-upload --file ./pic.png --presentation "$PID" --as user \
+  | jq -r '.data.file_token')
+
+# 2. block_insert 到页面末尾（省略 insert_before_block_id）
+# 注：<img .../> 是自闭合标签，CLI 不会展开（只有 <shape/> 会被补 <content/>）
+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\"/>")}]')"
+```
+
+预期返回：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "xml_presentation_id": "slides_example_presentation_id",
+    "slide_id": "slide_example_id",
+    "parts_count": 1,
+    "revision_id": 102
+  }
+}
+```
+
+## 示例 8: +replace-slide + block_replace 替换一个块
+
+已知某块的 3 位 short element ID（从 `slide.get` 返回 XML 里读），整块换掉。`replacement` 根元素的 `id` 会由 CLI 自动注入为 `block_id`，无需手写；若写了 `<shape/>` 自闭合形式，CLI 也会自动补 `<content/>`。
+
+```bash
+lark-cli slides +replace-slide --as user \
+  --presentation slides_example_presentation_id \
+  --slide-id slide_example_id \
+  --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>"
+    }
+  ]'
+# CLI 实际发送的 replacement 根元素会带 id="bab"，即使手写时省略了
+```
+
+失败时（3350001 错误，CLI 在 error 字段中给出 hint）：
+
+```json
+{
+  "ok": false,
+  "error": {
+    "type": "api_error",
+    "code": 3350001,
+    "message": "API error: [3350001] invalid param",
+    "hint": "common causes: (1) block_id not found in current slide ..."
+  }
+}
+```
+
+整批作为原子事务，任一 part 失败则整批不生效；按 `failed_part_index` 定位修正后重发。
+
+## 常见处理技巧
+
+### 获取最新 revision_id
+
+```bash
+lark-cli slides xml_presentations get --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id"
+}' | jq '.data.xml_presentation.revision_id'
+```
+
+### 批量插入多页
+
+```bash
+#!/bin/bash
+
+PRESENTATION_ID="slides_example_presentation_id"
+
+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>'
+)
+
+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
+```
+
+### 本地校验 XML 基本语法
+
+```bash
+xmllint --noout presentation.xml
+```
+
+### 真实示例
+
+- [slides_demo.xml](slides_demo.xml) 提供了更完整的页面示例，包含 `theme`、渐变填充、图片、图标和备注内容。

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

@@ -0,0 +1,137 @@
+
+# slides +create（创建飞书幻灯片）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+创建一个新的飞书幻灯片演示文稿，可选一步添加页面内容。
+
+## 命令
+
+```bash
+# 创建空白 PPT
+lark-cli slides +create --title "项目汇报"
+
+# 创建 PPT + 添加 slide 页面
+lark-cli slides +create --title "项目汇报" --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>封面</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>第二页</p></content></shape></data></slide>"
+]'
+
+# 以应用身份创建（自动授权当前用户）
+lark-cli slides +create --title "项目汇报" --as bot
+
+# 预览（不执行）
+lark-cli slides +create --title "项目汇报" --slides '[...]' --dry-run
+```
+
+## 返回值
+
+工具成功执行后，返回一个 JSON 对象，包含以下字段：
+
+- **`xml_presentation_id`**（string）：演示文稿的唯一标识符，后续添加页面时需要此 ID
+- **`title`**（string）：演示文稿标题
+- **`url`**（string，可选）：演示文稿的在线链接，如有返回则务必展示给用户（需要 drive 相关权限；若获取失败则不返回此字段）
+- **`revision_id`**（integer）：演示文稿版本号
+- **`slide_ids`**（string[]，可选）：仅传 `--slides` 时返回，成功添加的页面 ID 列表
+- **`slides_added`**（integer，可选）：仅传 `--slides` 时返回，成功添加的页面数量
+- **`images_uploaded`**（integer，可选）：仅 `--slides` 中含 `@<本地路径>` 占位符时返回，已上传的去重后图片数量
+- **`permission_grant`**（object，可选）：仅 `--as bot` 时返回，说明是否已自动为当前 CLI 用户授予可管理权限
+
+> [!IMPORTANT]
+> 不传 `--slides` 时，`slides +create` 只创建空白演示文稿。创建后需要使用 `xml_presentation.slide create` 逐页添加 slide 内容。
+>
+> 传了 `--slides` 时，CLI 先创建空白演示文稿，再逐页调用 `xml_presentation.slide create` 添加页面。如果某一页添加失败，CLI 会停止并报错，已创建的演示文稿和已添加的页面会保留。
+>
+> 如果演示文稿是**以应用身份（bot）创建**的，如 `lark-cli slides +create --as bot`，CLI 会**尝试为当前 CLI 用户自动授予该演示文稿的 `full_access`（可管理权限）**。
+>
+> 以应用身份创建时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
+> - `status = granted`：当前 CLI 用户已获得该演示文稿的可管理权限
+> - `status = skipped`：本地没有可用的当前用户 `open_id`，因此不会自动授权
+> - `status = failed`：演示文稿已创建成功，但自动授权用户失败
+>
+> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--title` | 否 | 演示文稿标题（不传则默认 "Untitled"） |
+| `--slides` | 否 | slide 内容 JSON 数组，每个元素是一个 `<slide>` XML 字符串（最多 10 个；超过 10 页请先用 `+create` 创建空白 PPT，再用 `xml_presentation.slide create` 逐页添加） |
+
+## `--slides` 参数格式
+
+```json
+[
+  "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\">...第1页XML...</slide>",
+  "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\">...第2页XML...</slide>"
+]
+```
+
+JSON string 数组，每个元素是一页 slide 的完整 XML。CLI 内部负责包装成 API 所需的 `{"slide": {"content": "..."}}` 格式并逐页调用。
+
+### 本地图片：`@<path>` 占位符
+
+`<img>` 元素的 `src` 属性如果以 `@` 开头，CLI 会把它当作本地文件路径，自动上传到当前演示文稿，并把占位符替换为返回的 `file_token`。
+
+```bash
+lark-cli slides +create --as user --title "图测试" --slides '[
+  "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><img src=\"@./assets/chart.png\" topLeftX=\"100\" topLeftY=\"100\" width=\"320\" height=\"180\"/></data></slide>"
+]'
+```
+
+行为：
+
+- 路径相对于**当前工作目录**（CWD）解析；**必须是 CWD 内的相对路径**（如 `./pic.png`、`./assets/x.png`）
+- 同一份图被多次引用时**只上传一次**（按路径去重）
+- `src` 不以 `@` 开头的会原样保留，但**只允许写 `slides +media-upload` 拿到的 `file_token`**；**禁止写 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 通常显示破图。要用网图必须先下载到 CWD 内、再走上传流程
+- 单张图片最大 20 MB（slides upload API 不支持分片上传）
+- 校验阶段就会检查所有占位符文件存在及大小；缺文件或超限直接报错，不会创建空白 PPT 占位
+- 创空白 PPT → 上传所有图 → 替换 token → 逐页创建 slide，按这个顺序执行
+
+> [!IMPORTANT]
+> **路径必须在 CWD 内**：`@/abs/path/x.png` 或 `@../up/x.png` 这种会被 CLI 拒绝（报 `unsafe file path`）。如果素材在别的目录，先 `cd` 过去再执行。
+
+### 给已有 PPT 加带图新页
+
+`+create --slides` 只在新建 PPT 时使用 `@` 占位符。给已有 PPT 加带图新页要分两步（CLI 没封装这个组合）：
+
+```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=\\\"200\\\" height=\\\"200\\\"/></data></slide>\"}}"
+```
+
+## 创建后续步骤
+
+如果没有使用 `--slides`，`slides +create` 返回的 `xml_presentation_id` 用于后续操作：
+
+```bash
+# 第 1 步：创建空白 PPT
+PRES_ID=$(lark-cli slides +create --title "项目汇报" | jq -r '.data.xml_presentation_id')
+
+# 第 2 步：添加页面（使用返回的 xml_presentation_id）
+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\">...</slide>"
+    }
+  }'
+```
+
+## 常见错误
+
+| 错误码 | 含义 | 解决方案 |
+|--------|------|----------|
+| 400 | 参数错误 | 检查参数格式是否正确 |
+| 403 | 权限不足 | 检查是否拥有 `slides:presentation:create` 和 `slides:presentation:write_only` scope |
+
+## 相关命令
+
+- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) — 添加幻灯片页面
+- [xml_presentations get](lark-slides-xml-presentations-get.md) — 读取 PPT 内容

package/dist/skills/larksuite/lark-slides/references/lark-slides-edit-workflows.md

@@ -0,0 +1,142 @@
+# 编辑已有 PPT：读-改-写闭环
+
+编辑走 **shortcut [`+replace-slide`](lark-slides-replace-slide.md)**（块级替换 / 插入），配合 `xml_presentation.slide.get` 读原页拿 `block_id`。
+
+> 生成 XML 前**必读** [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。
+
+## 决策树：block_replace vs block_insert
+
+| 需求 | 推荐 action | 理由 |
+|------|------------|------|
+| 已知某块的 `block_id`，要换这块内容（改标题、换图、挪坐标） | `block_replace` | 精准替换，原子性好；`replacement` 根 `id` 由 CLI 自动注入为 `block_id` |
+| 只加 1~N 个元素、不动现有布局 | `block_insert` | 新增不覆盖，可选 `insert_before_block_id` 指定位置 |
+| 一次动多个元素（如：换标题 + 加图） | 单次 `--parts` 里拼多条 | 整批作为原子事务，任一失败整批不生效；`block_replace` 和 `block_insert` 可混用 |
+
+> **没有字段级 patch**：即便只想改一个 `shape` 的 `topLeftX`，也得把整个块的新 XML 写出来用 `block_replace`。这不是"微调"，是块级重写。
+
+## 最小读-改-写闭环
+
+```bash
+PID="xml_presentation_id_here"
+SID="slide_id_here"
+
+# 1. 读原页，从 XML 里挑出要改的块的 3 位 short id（如 bUn / bab）
+lark-cli slides xml_presentation.slide get --as user \
+  --params "{\"xml_presentation_id\":\"$PID\",\"slide_id\":\"$SID\"}"
+
+# 2. 用 +replace-slide 直接改那个块（不需要搬原 XML）
+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>"}]'
+```
+
+`slide_id` / 页序不会变。`block_replace` 的 `replacement` 根元素 `id` 会自动注入为 `block_id`，用户手写 XML 时不需要自己加。
+
+## `revision_id` 参数
+
+`--revision-id` 默认 `-1`，表示基于当前最新版执行。传具体版本号时，服务端以该版本为 base 应用变更：
+
+```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')
+
+# 写时传该版本号，服务端以此为 base
+lark-cli slides +replace-slide --as user \
+  --presentation "$PID" --slide-id "$SID" --revision-id "$REV" \
+  --parts '[{"action":"block_replace","block_id":"bUn","replacement":"<shape type=\"rect\" topLeftX=\"100\" topLeftY=\"100\" width=\"200\" height=\"100\"/>"}]'
+```
+
+注意：传不存在的版本号（超过当前 revision）会返回 3350002 not found；不确定时用 `-1` 即可。
+
+## `--tid` 事务锁
+
+跨请求的并发事务 ID，多人协作长事务才用得上。**单人单次调用留空**即可。
+
+## 两种 action 详解
+
+### block_replace — 整块替换
+
+适合"已知块 ID，要换这块整体内容"的场景。`replacement` 根元素的 `id="<block_id>"` 由 CLI 自动注入（用户手写的 XML 如果没带 `id` 直接省略即可；如果带了错的会被覆盖为正确值）。
+
+```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_replace` |
+| `block_id` | 是 | 目标块的 3 位 short element ID（从 `slide.get` 返回的 XML 里读）|
+| `replacement` | 是 | 新 XML 片段；根元素 `id` 会被 CLI 自动注入为 `block_id` |
+
+### block_insert — 整块插入
+
+适合"只想加一个元素，不动现有元素"的场景（典型：给已有页加图）。
+
+```bash
+lark-cli slides +replace-slide --as user \
+  --presentation "$PID" --slide-id "$SID" \
+  --parts "$(jq -n --arg token "$FILE_TOKEN" \
+    '[{action:"block_insert",insertion:("<img src=\""+$token+"\" topLeftX=\"500\" topLeftY=\"100\" width=\"200\" height=\"150\"/>"),insert_before_block_id:"baa"}]')"
+```
+
+字段说明：
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `action` | 是 | 固定为 `block_insert` |
+| `insertion` | 是 | 要插入的完整 XML 片段 |
+| `insert_before_block_id` | 否 | 插到这个块之前；省略（不提供此字段）则追加到页面末尾 |
+
+> **`<img>` 必须用 `file_token`**，不能用外链 URL——先 `slides +media-upload --file ./pic.png --presentation $PID` 拿 token。
+
+### 批量 parts
+
+一次 `--parts` 最多 200 条，按数组顺序串行执行。`block_replace` 和 `block_insert` 可以在同一批次混用。举例：一次性把标题块替换、然后在末尾追加一个装饰图。
+
+```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\"/>"}
+  ]'
+```
+
+整批作为原子事务：任一条失败整批不生效。失败时后端通常返回 3350001；若响应中带 `failed_part_index` / `failed_reason` 字段，shortcut 会原样透传。
+
+## 大 --parts 用 jq 或 stdin 组装
+
+`--parts` 支持 `@file`（读文件）和 `-`（stdin）作为值来源，适合批量 XML 场景：
+
+```bash
+# 从文件读
+lark-cli slides +replace-slide --as user --presentation "$PID" --slide-id "$SID" \
+  --parts @parts.json
+
+# 从 stdin 读
+cat parts.json | lark-cli slides +replace-slide --as user --presentation "$PID" --slide-id "$SID" \
+  --parts -
+```
+
+## 错误排查
+
+| 现象 | 原因 | 对策 |
+|------|------|------|
+| 3350001，hint 含 "block_id not found" | `parts[i].block_id` 在当前页不存在 | 重新 `slide.get` 拿最新 XML，按里面的 short ID 再填 |
+| 3350002 not found | `--revision-id` 传了不存在的版本号 | 用 `-1` 或实际存在的 `revision_id` |
+| `<img>` 不显示 / 显示破图 | `src` 写了外链 URL | 换成通过 `+media-upload` 拿到的 `file_token` |
+| 3350001（block_replace 返回） | 正常情况下 CLI 已自动注入 `id` 和 `<content/>`；如果仍报错，确认 `block_id` 在当前页存在（重新 `slide.get`），检查 XML 结构是否合法；坐标是否超出 960×540 范围 | — |
+
+## 相关文档
+
+- [lark-slides-replace-slide.md](lark-slides-replace-slide.md) — +replace-slide 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
+- [xml-schema-quick-ref.md](xml-schema-quick-ref.md) — XML 元素和属性速查

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

@@ -0,0 +1,128 @@
+
+# slides +media-upload（上传本地图片到飞书幻灯片）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+把本地图片上传到指定演示文稿的 drive 媒体库，返回 `file_token`。**返回的 token 作为 `<img src="...">` 的值塞进 slide XML 即可显示图片。**
+
+## 命令
+
+```bash
+# 直接传 xml_presentation_id
+lark-cli slides +media-upload --as user \
+  --file ./pic.png \
+  --presentation slidesXXXXXXXXXXXXXXXXXXXXXX
+
+# 传 slides URL 也行
+lark-cli slides +media-upload --as user \
+  --file ./chart.png \
+  --presentation "https://xxx.feishu.cn/slides/slidesXXXXXXXXXXXXXXXXXXXXXX"
+
+# 传 wiki URL（CLI 自动 wiki.spaces.get_node 解析为真实 token，校验 obj_type=slides）
+lark-cli slides +media-upload --as user \
+  --file ./pic.png \
+  --presentation "https://xxx.feishu.cn/wiki/wikcnXXXXXX"
+
+# 预览（不实际上传）
+lark-cli slides +media-upload --file ./pic.png --presentation $PRES_ID --dry-run
+```
+
+## 返回值
+
+```json
+{
+  "file_token": "boxcnXXXXXXXXXXXXXXXXXXXXXX",
+  "file_name": "pic.png",
+  "size": 12345,
+  "presentation_id": "slidesXXXXXXXXXXXXXXXXXXXXXX"
+}
+```
+
+- **`file_token`**：把它写进 `<img src="...">`
+- **`file_name` / `size`**：上传文件元信息
+- **`presentation_id`**：解析后的真实 `xml_presentation_id`（wiki URL 解析后会变化）
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file` | 是 | 本地图片路径，**必须是 CWD 内的相对路径**（如 `./pic.png`）。**最大 20 MB**（slides upload API 不支持分片上传） |
+| `--presentation` | 是 | `xml_presentation_id`、`/slides/<token>` URL，或 `/wiki/<token>` URL |
+
+> [!IMPORTANT]
+> **路径必须在 CWD 内**：`--file /abs/path/x.png` 或 `--file ../up/x.png` 会被 CLI 拒绝（报 `unsafe file path`）。如果素材在别的目录，先 `cd` 过去再执行。
+
+## 使用流程
+
+### 给已有 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 的已有页加图
+
+拿到 `file_token` 后走 [`+replace-slide`](lark-slides-replace-slide.md) 的 `block_insert`，不用搬原 XML、不改 `slide_id`、不打乱页序：
+
+```bash
+PRES_ID=xxx
+SID=yyy       # 要加图的那一页
+
+# 1) 上传图片拿 file_token
+TOKEN=$(lark-cli slides +media-upload --as user \
+  --file ./pic.png --presentation $PRES_ID | jq -r '.data.file_token')
+
+# 2) block_insert 到页末（或用 insert_before_block_id 指定插入位置）
+lark-cli slides +replace-slide --as user \
+  --presentation "$PRES_ID" --slide-id "$SID" \
+  --parts "$(jq -n --arg token "$TOKEN" \
+    '[{action:"block_insert",insertion:("<img src=\""+$token+"\" topLeftX=\"500\" topLeftY=\"100\" width=\"200\" height=\"150\"/>")}]')"
+```
+
+注意事项：
+
+1. **`<img>` 坐标避开现有元素** —— 先读现有元素 bbox 挑空白区；空间不够就先用 `block_replace` 挪动/缩小现有元素后再放图
+2. **`<img>` 的 `width:height` 对齐原图比例** —— 比例不一致会被裁剪，参见 [xml-schema-quick-ref.md](xml-schema-quick-ref.md) `<img>` 说明
+
+## 工作原理
+
+`+media-upload` 内部调用 `POST /open-apis/drive/v1/medias/upload_all`（单次上传，最大 20 MB），固定使用：
+
+- `parent_type=slide_file`（slides 后端唯一接受的取值，已实测验证）
+- `parent_node=<xml_presentation_id>`
+
+**不要尝试用 `slides_image`、`slide_image` 等 parent_type**——后端会返回 1061001 / 1061002 错误。这是 slides 的特殊约定。
+
+## 常见错误
+
+| 错误码 | 含义 | 解决方案 |
+|--------|------|----------|
+| 1061002 | params error / 不支持的 parent_type | 不要用原生 API 自己拼 parent_type；用 `+media-upload` 即可 |
+| 1061004 | forbidden：当前身份对该演示文稿无编辑权限 | 确认当前身份（user 或 bot）对目标 PPT 有编辑权限。bot 模式常见原因：PPT 不是该 bot 创建的——可用 `+create --as bot` 新建，或以 user 身份给 bot 授权 `lark-cli drive permission.members create --as user ...` |
+| 1061044 | parent node not exist | `--presentation` 给的 token 不对，或不是 slides 类型 |
+| 403 | 权限不足 | 检查 `docs:document.media:upload` scope；wiki URL 还需要 `wiki:node:read` |
+
+## 相关命令
+
+- [+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）