diff --git a/skills/lark-slides/references/cli/lark-slides-add-slide.md b/skills/lark-slides/references/cli/lark-slides-add-slide.md index 3d94542823..c81d1abdec 100644 --- a/skills/lark-slides/references/cli/lark-slides-add-slide.md +++ b/skills/lark-slides/references/cli/lark-slides-add-slide.md @@ -45,6 +45,7 @@ lark-cli slides +add-slide --presentation "$PRES_ID" --slide @page3.xml --dry-ru | `--slide` | 是 | 一个完整的 `...` 文档；支持字面量、`@file`、stdin `-` | | `--before-slide-id` | 否 | 插到该 `slide_id` 之前；**不传就是追加到末尾** | | `--revision-id` | 否 | 演示文稿版本号，默认 `-1`（最新）；传具体版本号做乐观锁 | +| `--no-lint` | 否 | 跳过服务端版式校验（默认开启）；仅在确认校验误判、该页必须原样发布时使用 | | `--dry-run` | 否 | 打印将要发起的请求（含图片上传步骤），不写入 | `@file` 路径**必须在 CWD 内**（如 `@./plan/page3.xml`）；绝对路径和 `../` 会被拒绝并报 `unsafe file path`。 @@ -73,14 +74,14 @@ lark-cli slides +add-slide --as user \ "revision_id": 42, "before_slide_id": "slide_example_target_id", "images_uploaded": 1, - "issues": "[issue=unsupported_attr tag= attr=style]" + "issues": "<服务端返回的发现>" } ``` | 字段 | 说明 | |------|------| | `slide_id` | 新创建页面的唯一标识 | -| `issues` | 字符串，**只在服务端丢弃过内容时才出现**：页面创建成功，但括号里列出的标签/属性没写进去。出现就必须 `+screenshot` 复核，别当纯警告忽略；干净提交时这个字段不返回 | +| `issues` | 字符串，仅在**页面已写入成功**且服务端有发现时返回，干净提交时不返回，不影响本次调用的成功状态。两种来源：提交的 XML 里有服务端不支持的标签/属性被丢弃（**页面内容与提交的不一致**），或未达阻断级的版式校验发现。格式不固定，不要解析；出现就用 `+screenshot` 复核该页，不要按普通告警忽略 | ## 常见错误 @@ -89,4 +90,5 @@ lark-cli slides +add-slide --as user \ | `--slide is not a single complete document` | 传了 `` 整份 XML，或多个 `` 拼在一起 | 一次只传一页，根元素必须是 `` | | `--slide cannot be empty` | `@file` 指向空文件，或 stdin 没内容 | 检查文件内容 | | 3350001 | XML 结构/转义有问题；**或 `--before-slide-id` 不是有效 `slide_id`** | 优先改用 `--slide @file` 绕开 shell 转义；插页失败先 `+xml-get` 回读确认 `slide_id`；再按 [workflow/error-handling.md](../workflow/error-handling.md) 排查 | +| 4000153 `xml lint blocked` | 服务端版式校验拒绝了这一页，页面未写入 | `error.message` 是完整的校验报告，按其中每条发现给出的修改建议修正后重试 | | 1061004 / 403 | 当前身份对这份 PPT 没有编辑权限 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope；wiki 链接另需 `wiki:node:read`，`@` 占位符另需 `docs:document.media:upload`；`--as bot` 还要求该 bot 对目标 PPT 有编辑权限 | diff --git a/skills/lark-slides/references/cli/lark-slides-create.md b/skills/lark-slides/references/cli/lark-slides-create.md index a2c51a1fe4..50e8816206 100644 --- a/skills/lark-slides/references/cli/lark-slides-create.md +++ b/skills/lark-slides/references/cli/lark-slides-create.md @@ -54,11 +54,12 @@ lark-cli slides +create --title "项目汇报" --slide @./slide-01.xml --dry-run - **`slides_added`**（integer，可选）：带页面创建时返回，成功添加的页面数量 - **`images_uploaded`**（integer，可选）：页面 XML 中含 `@<本地路径>` 占位符时返回，已上传的去重后图片数量 - **`permission_grant`**（object，可选）：仅 `--as bot` 时返回，说明是否已自动为当前 CLI 用户授予可管理权限 +- **`slide_issues`**（数组，可选）：带页面创建时才可能返回，逐项对应一个**已写入成功的页面**（标明页序和 `slide_id`），内容是服务端对该页的发现，不影响本次调用的成功状态。两种来源：页面 XML 里有服务端不支持的标签/属性被丢弃（**页面内容与提交的不一致**），或未达阻断级的版式校验发现。格式不固定，不要解析；出现就用 `+screenshot` 复核对应页 > [!IMPORTANT] > 不带页面参数时，`slides +create` 只创建空白演示文稿。创建后用 [`+add-slide`](lark-slides-add-slide.md) 逐页添加 slide 内容。 > -> 带了页面时，CLI 先创建空白演示文稿，再逐页调用 slide 创建接口添加页面。如果某一页添加失败，CLI 会停止并报错，已创建的演示文稿和已添加的页面会保留。 +> 带了页面时，CLI 先创建空白演示文稿，再逐页调用 slide 创建接口添加页面，每页各过一次服务端版式校验。如果某一页失败，CLI 会停止并报错，已创建的演示文稿和已添加的页面会保留，报错会指明失败页序和此前已成功写入的页数。 > > 如果演示文稿是**以应用身份（bot）创建**的，如 `lark-cli slides +create --as bot`，CLI 会**尝试为当前 CLI 用户自动授予该演示文稿的 `full_access`（可管理权限）**。 > @@ -76,6 +77,7 @@ lark-cli slides +create --title "项目汇报" --slide @./slide-01.xml --dry-run | `--title` | 否 | 演示文稿标题（不传则默认 "Untitled"） | | `--slide` | 否 | 一页 `` XML，或 `@路径`；可重复，最多 10 次。格式见[页面输入形式](#页面输入形式) | | `--slides` | 否 | 页面 XML 的 JSON 字符串数组，最多 10 个；支持 `@文件` 和 `-`（stdin）。格式见[页面输入形式](#页面输入形式) | +| `--no-lint` | 否 | 跳过服务端版式校验（默认开启，每页各校验一次）；仅在确认校验误判、页面必须原样发布时使用 | 10 页是 CLI 的上限，服务端每次只接收一页。超过 10 页时先用 `+create` 创建空白 PPT，再用 [`+add-slide`](lark-slides-add-slide.md) 逐页添加。 @@ -169,6 +171,7 @@ lark-cli slides +add-slide --as user \ |--------|------|----------| | 400 | 参数错误 | 检查参数格式是否正确 | | 403 | 权限不足 | 检查是否拥有 `slides:presentation:create` 和 `slides:presentation:write_only` scope | +| 4000153 `xml lint blocked` | 服务端版式校验拒绝了该页；演示文稿及其之前的页面已写入成功 | `error.message` 是完整的校验报告，按其中每条发现给出的修改建议修正后，用 `+add-slide` 从该页续接，无需重建整份演示文稿 | ## 相关命令 diff --git a/skills/lark-slides/references/cli/lark-slides-replace-slide.md b/skills/lark-slides/references/cli/lark-slides-replace-slide.md index 08dae90306..10982689a8 100644 --- a/skills/lark-slides/references/cli/lark-slides-replace-slide.md +++ b/skills/lark-slides/references/cli/lark-slides-replace-slide.md @@ -51,6 +51,7 @@ lark-cli slides +replace-slide --as user \ | `--parts` | 是 | JSON 数组（`[{...}, ...]`），单次最多 200 条。支持 `@` 和 `-`（stdin）读取 | | `--revision-id` | 否 | 基础版本号；默认 `-1` 表示基于最新版执行；传具体版本号时，服务端以该版本为 base 执行；**传不存在的版本号（超过当前 revision）返回 3350002** | | `--tid` | 否 | 并发事务 ID；多人协作长事务才用，单次单人调用留空 | +| `--no-lint` | 否 | 跳过服务端版式校验（默认开启）。**校验主体是这些 parts 拼装后的整页**，不是片段本身 | ## parts 元素结构 @@ -172,6 +173,7 @@ lark-cli slides +replace-slide --as user \ | `revision_id` | 成功后的新版本号，下次做乐观锁时用 | | `failed_part_index` | 有部分失败时存在，指向第几条 part 失败 | | `failed_reason` | 失败原因文字描述 | +| `issues` | 与 `failed_reason` 相对：parts 已全部生效，服务端只是仍有发现，不影响本次调用的成功状态。内容是未达阻断级的版式校验发现；校验主体是**拼装后的整页**，因此可能报出页面上原有的元素。格式不固定，不要解析；出现就用 `+screenshot` 复核该页 | 整批作为原子事务：任一 part 失败则整批不生效，服务端通过 `failed_part_index` / `failed_reason` 告诉你是哪条；按此定位修正后重发。 @@ -249,6 +251,7 @@ lark-cli slides +replace-slide --as user \ | `--parts[i] (block_replace) requires non-empty block_id` / `replacement` | 字段名对，但值缺失或是空串 | 按 parts 元素结构补齐值 | | `` 不显示 / 显示破图 | `src` 写了外链 URL | 换成通过 [`+media-upload`](lark-slides-media-upload.md) 拿到的 `file_token` | | 3350001 | `replacement` 不是合法单根 XML 片段，或 `block_id` 不存在 | CLI 已自动注入 `id` 和 ``；如果仍报错，重新 `slide.get` 拿最新 XML 确认 `block_id` 存在；检查 XML 结构是否合法；坐标是否超出 960×540 | +| 4000153 `xml lint blocked` | 服务端版式校验拒绝了本次提交，页面维持原状；校验主体是拼装后的整页，因此片段自身合法也可能因与相邻元素重叠、或页面原有元素越界而被拒 | `error.message` 是完整的校验报告，按其中每条发现给出的修改建议修正；需要调整既有元素时，在同一批 `--parts` 内一并提交 | | 403 | 权限不足 | 需要 `slides:presentation:update` 或 `slides:presentation:write_only`；wiki URL 还需要 `wiki:node:read` | ## 相关命令 diff --git a/skills/lark-slides/references/cli/lark-slides-update-slide.md b/skills/lark-slides/references/cli/lark-slides-update-slide.md index 4e9dc6ee0f..7ded368b96 100644 --- a/skills/lark-slides/references/cli/lark-slides-update-slide.md +++ b/skills/lark-slides/references/cli/lark-slides-update-slide.md @@ -34,6 +34,7 @@ lark-cli slides +update-slide --as user \ | `--content` | 是 | 这一页的完整目标 XML，单一 `` 根；支持字面量、`@file`、stdin `-`。别名：`--xml` / `--slide-xml` / `--slide-content` / `--content-xml` | | `--revision-id` | 否 | 默认 `-1`（最新）。它只选择服务端执行所基于的快照，不是“页面有新编辑就拒绝”的乐观锁；传旧版本号会以旧快照重建页面并丢弃其后的编辑 | | `--tid` | 否 | 调用方提供的任务/事务标识，CLI 原样透传；用于关联同一编辑任务或重试，不等同于版本前置条件，不能单独保证并发冲突时拒绝写入。一般留空 | +| `--no-lint` | 否 | 跳过服务端版式校验（默认开启）；仅在确认校验误判、该页必须原样发布时使用 | `@file` 和 `+xml-get --output` 一样**只接受当前目录下的相对路径**，绝对路径会被拒。 命令别名：`slides +update`（隐藏）；服务别名：`lark-cli slide …` 等价于 `lark-cli slides …`。 @@ -147,6 +148,7 @@ lark-cli slides +xml-get --as user \ | `slide_id` | 与传入相同——整页覆盖不换页 id | | `revision_id` | 写入后的新版本号 | | `images_uploaded` | 仅当 `--content` 带 `@` 占位符时出现：本次去重后实际上传的图片张数 | +| `issues` | 仅在**页面已写入成功**且服务端有发现时返回，不影响本次调用的成功状态。内容是未达阻断级的版式校验发现。格式不固定，不要解析；出现就用 `+screenshot` 复核该页 | 服务端拒绝这次写入时（`failed_reason` 非空）**不会**返回成功输出，而是报错并带上原因——单个 part 承载整页，任何失败都意味着页面没被写入。 @@ -160,4 +162,5 @@ lark-cli slides +xml-get --as user \ | 3350001，原因包含 `not found` | `--presentation` 不匹配，或 `--slide-id` 对应的页面已被删除 | 检查 `--presentation` 和 `--slide-id`，再用 `slides +xml-get` 回读当前页面 ID | | 3350001，其他 invalid param | `--content` 的 XML 结构有问题（如 `` 缺 ``、包含服务端不支持的元素） | 按 [error-handling.md](../workflow/error-handling.md) 检查 `--content` 的 XML 结构 | | 3350002 not found | `--revision-id` 传了不存在的版本号 | 用 `-1` 或真实存在的 `revision_id` | +| 4000153 `xml lint blocked` | 服务端版式校验拒绝了本次写回，页面维持原状 | `error.message` 是完整的校验报告，按其中每条发现给出的修改建议修正后重试 | | 1061004 / 403 | 当前身份对这份 PPT 没有编辑权限 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope；wiki 链接另需 `wiki:node:read`，`@` 占位符另需 `docs:document.media:upload`；`--as bot` 还要求该 bot 对目标 PPT 有编辑权限 | diff --git a/skills/lark-slides/references/workflow/error-handling.md b/skills/lark-slides/references/workflow/error-handling.md index f89385d88c..58bb90494b 100644 --- a/skills/lark-slides/references/workflow/error-handling.md +++ b/skills/lark-slides/references/workflow/error-handling.md @@ -53,6 +53,7 @@ | 1061004 forbidden | 当前用户对演示文稿无编辑权限 | 确认当前用户对目标 PPT 有编辑权限 | | 3350001 | XML 非 well-formed、XML 结构不符合服务端要求，或 replace 片段问题 | 优先检查未转义字符；replace 场景再看 `block_id` 和 `` | | 3350002 | `revision_id` 大于当前版本 | 用 `-1` 取当前版本，或重新用 `slides +xml-get` 取最新 `revision_id` | +| 4000153 `xml lint blocked` | 服务端版式校验拒绝了本次写入，被拒的页面未写入（`+create` 逐页提交，之前的页面保留） | 完整的校验报告在 `error.message`；`+replace-pages --continue-on-error` 不中断整批，被拒的那几页改在 `results[]` 里以 `error_code: 4000153` + `error`（同一份报告）+ `hint` 给出。按报告里每条发现的修改建议修正后重试。只有阻断级发现会拦截，未拦截的发现不会丢失——写入成功时通过返回值里的 `issues` 字段给出。确认误判时才用 `--no-lint` | | validation: unsafe file path | `--file` 给了绝对路径或上层路径 | `--file` 必须是 CWD 内相对路径；先 `cd` 到素材目录再执行 | ## Command-Specific References