@amaster.ai/pi-lark 0.1.2-beta.53 → 0.1.2-beta.55

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

@@ -0,0 +1,188 @@
+# lark-slides xml_presentation.slide replace
+
+## 用途
+
+对单页做**块级局部替换**：不覆盖整页，按 patch 列表做 `block_replace`（整块替换）或 `block_insert`（整块插入）。适合"只想加 / 换一个元素、不动其他元素"的场景。
+
+> **推荐**：优先使用 [`+replace-slide`](lark-slides-replace-slide.md) Shortcut——它会自动注入 `id` 和 `<content/>`，直接调本 API 需自己处理这两个约束（见注意事项 5、6）。
+
+## 命令
+
+```bash
+lark-cli slides xml_presentation.slide replace --as user --params '<json_params>' --data '<json_data>'
+```
+
+## 参数说明
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `--params` | JSON string | 是 | 路径参数与查询参数 |
+| `--data` | JSON string | 是 | patch 列表 |
+
+### 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，一般留空 |
+
+### data JSON 结构
+
+```json
+{
+  "parts": [
+    { "action": "block_replace", "block_id": "bab", "replacement": "<shape .../>" },
+    { "action": "block_insert", "insertion": "<img .../>", "insert_before_block_id": "baa" }
+  ]
+}
+```
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `parts` | array | 是 | patch 列表，长度 1~200，顺序执行 |
+
+### parts[] 字段（按 action 不同）
+
+本期 CLI 文档化两种 action：
+
+#### action = "block_replace" — 整块替换
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `action` | 是 | 固定 `block_replace` |
+| `block_id` | 是 | 目标块的 3 位 short element ID（从 `slide.get` 返回的 XML 里读到） |
+| `replacement` | 是 | 新 XML 片段，替换整个目标块 |
+
+#### action = "block_insert" — 整块插入
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `action` | 是 | 固定 `block_insert` |
+| `insertion` | 是 | 要插入的完整 XML 片段 |
+| `insert_before_block_id` | 否 | 插到这个块之前；省略则追加到页面末尾 |
+
+## 使用示例
+
+### block_replace：换一个 shape 的整体内容
+
+```bash
+lark-cli slides xml_presentation.slide replace --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id",
+  "slide_id": "slide_example_id"
+}' --data '{
+  "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>"
+    }
+  ]
+}'
+```
+
+### block_insert：在已有页上加一张图
+
+```bash
+# 先拿 file_token
+TOKEN=$(lark-cli slides +media-upload --file ./pic.png --presentation "$PID" --as user | jq -r '.data.file_token')
+
+lark-cli slides xml_presentation.slide replace --as user --params "{
+  \"xml_presentation_id\": \"$PID\",
+  \"slide_id\": \"$SID\"
+}" --data "$(jq -n --arg token "$TOKEN" '{
+  parts: [
+    {
+      action: "block_insert",
+      insertion: ("<img src=\"" + $token + "\" topLeftX=\"500\" topLeftY=\"100\" width=\"200\" height=\"150\"/>")
+    }
+  ]
+}')"
+```
+
+### 多条 parts 原子执行
+
+```bash
+lark-cli slides xml_presentation.slide replace --as user --params '{
+  "xml_presentation_id": "slides_example_presentation_id",
+  "slide_id": "slide_example_id"
+}' --data '{
+  "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\"/>"}
+  ]
+}'
+```
+
+## 返回值
+
+### 成功
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "revision_id": 105
+  }
+}
+```
+
+### 失败（任一 part 失败，整批不生效）
+
+失败时命令以非零退出码结束，stderr 返回类型化错误信封（`error.code`（如 3350001）/ `error.message` / `error.hint`），stdout 不会打印后端原始响应：
+
+```json
+{
+  "ok": false,
+  "identity": "user",
+  "error": {
+    "type": "api",
+    "subtype": "...",
+    "code": 3350001,
+    "message": "...",
+    "hint": "..."
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data.revision_id` | integer | 成功时返回更新后最新版本号 |
+
+## 常见错误
+
+| 错误码 | 含义 | 解决方案 |
+|--------|------|----------|
+| 3350001 | `block_id` 在当前页不存在，或 XML 格式 / 结构错误 | 重新 `slide.get` 拿最新 XML，确认 `block_id` 存在；检查 `replacement` / `insertion` 是否合法 XML |
+| 400 | `parts` 长度超过 200 | 拆多次调用 |
+| 3350002 | `revision_id` 不存在（超过当前版本号） | 用 `-1` 或实际存在的 `revision_id` |
+| 400 | XML 格式错误 | `replacement` / `insertion` 必须为合法的 XML 片段，标签闭合 + 属性引号 |
+| 403 | 权限不足 | 需要 `slides:presentation:update` 或 `slides:presentation:write_only` |
+
+## 注意事项
+
+1. **parts 原子事务**：任一条失败整批回滚，不会出现"前几条成功、后几条失败"的中间态。
+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. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.replace` 查看最新参数结构。
+
+## 相关命令
+
+- [slides +replace-slide](lark-slides-replace-slide.md) — 块级替换 shortcut（推荐，自动注入 id）
+- [xml_presentation.slide get](lark-slides-xml-presentation-slide-get.md) — 读原页拿 block short ID
+- [slides +media-upload](lark-slides-media-upload.md) — 上传图片拿 file_token
+- [lark-slides-edit-workflows.md](../workflow/slides_editing.md) — 读-改-写闭环 + 决策树

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

@@ -0,0 +1,157 @@
+# lark-slides xml_presentations get
+
+## 用途
+
+读取飞书幻灯片（PPT）的完整演示文稿 XML，或通过 `--slide-id` / `--slide-number` 读取指定单页 XML。
+
+## Shortcut
+
+使用 `slides +xml-get` shortcut，可以把 XML 保存到本地文件，避免终端输出被截断。
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --output .lark-slides/plan/slides_example_presentation_id/readback.xml \
+  --json
+```
+
+### 参数说明
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `--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 为默认输出格式 |
+
+
+### 基础示例
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --output .lark-slides/plan/slides_example_presentation_id/readback.xml \
+  --json
+```
+
+### 读取单页并保存
+
+按页面 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-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --slide-number 1 \
+  --raw
+```
+
+### 指定版本读取
+
+```bash
+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-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` 表示最新版本 |
+
+
+### 返回值
+
+成功时返回演示文稿的完整信息：
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "xml_presentation": {
+      "presentation_id": "slides_example_presentation_id",
+      "revision_id": 1,
+      "content": "<presentation xmlns=\"https://www.larkoffice.com/sml/2.0\" height=\"540\" width=\"960\">...</presentation>"
+    }
+  }
+}
+```
+
+### 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data.xml_presentation.presentation_id` | string | 演示文稿唯一标识 |
+| `data.xml_presentation.revision_id` | integer | 版本号 |
+| `data.xml_presentation.content` | string | XML 格式的完整内容 |
+
+### 常见错误
+
+| 错误码 | 含义 | 解决方案 |
+|--------|------|----------|
+| 404 | 演示文稿不存在 | 检查 `xml_presentation_id` 是否正确 |
+| 403 | 权限不足 | 检查是否拥有 `slides:presentation:read` scope，或是否有访问权限 |
+| 400 | 参数格式错误 | 确保 `--params` 是合法的 JSON 字符串 |
+
+
+### 注意事项
+
+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
+- [slides +add-slide](../xml/lark-slides-add-slide.md) - 添加幻灯片页面
+- [slides +delete-slide](../xml/lark-slides-delete-slide.md) - 删除幻灯片页面