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

package/skills/{lark-vc-agent/references/lark-vc-agent-meeting-list-active.md → lark-vc/references/lark-vc-meeting-list-active.md}

@@ -87,5 +87,5 @@ lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
 
 ## 参考
 
-- [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 让应用机器人真实入会并拿 `meeting.id`
-- [lark-vc-agent-meeting-events](lark-vc-agent-meeting-events.md) — 使用 `meeting_id` 读取会中事件
+- [lark-vc-agent-meeting-join](../../lark-vc-agent/references/lark-vc-agent-meeting-join.md) — 让应用机器人真实入会并拿 `meeting.id`
+- [lark-vc-meeting-events](lark-vc-meeting-events.md) — 使用 `meeting_id` 读取会中事件

package/skills/{lark-vc-agent/references/lark-vc-agent-meeting-message-send.md → lark-vc/references/lark-vc-meeting-message-send.md}

@@ -129,6 +129,6 @@ VC_CanNotSee, VC_NoSound, VC_LooksGood, VC_SoundsClear
 
 ## 相关
 
-- [lark-vc-agent-meeting-list-active](lark-vc-agent-meeting-list-active.md) — 发现当前进行中会议 ID
-- [lark-vc-agent-meeting-events](lark-vc-agent-meeting-events.md) — 读取会中事件
-- [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 应用机器人入会
+- [lark-vc-meeting-list-active](lark-vc-meeting-list-active.md) — 发现当前进行中会议 ID
+- [lark-vc-meeting-events](lark-vc-meeting-events.md) — 读取会中事件
+- [lark-vc-agent-meeting-join](../../lark-vc-agent/references/lark-vc-agent-meeting-join.md) — 应用机器人入会

package/skills/lark-vc/references/lark-vc-recording.md

@@ -40,9 +40,11 @@ lark-cli vc +recording --meeting-ids 69xxxxxxxxxxxxx28 --dry-run
 
 每次只能指定一种输入方式。同时传入会报错。
 
-### 2. 仅支持 user 身份
+### 2. 身份支持
 
-该命令仅支持 `user` 身份，使用前需完成 `lark-cli auth login`。user token 只能查自己有权限的录制。
+`--meeting-ids` 和 `--calendar-event-ids` 两种模式都支持 `--as user` 和 `--as bot`。user token 只能查自己有权限的录制；bot 使用 tenant_access_token，只能查 bot 有权限的录制。
+
+拿到的 `minute_token` 是在某个身份下解析出来的：下一步传给 `minutes minutes get` / `minutes +detail` / `minutes +download` 时必须显式沿用同一个 `--as`，不要省略让身份被 profile 默认值悄悄换掉（完整规则见 [lark-shared](../../lark-shared/SKILL.md) 的「身份延续」）。
 
 ### 3. 批量上限
 
@@ -78,10 +80,10 @@ lark-cli vc +recording --meeting-ids 69xxxxxxxxxxxxx28 --dry-run
 
 ```bash
 # 第 1 步：通过 meeting_id 查询录制，拿到 minute_token
-lark-cli vc +recording --meeting-ids xxx
+lark-cli vc +recording --meeting-ids xxx --as bot
 
-# 第 2 步：使用上一步返回的 minute_token 下载妙记文件
-lark-cli minutes +download --minute-tokens <minute_token>
+# 第 2 步：使用上一步返回的 minute_token 下载妙记文件，沿用第 1 步的身份
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --as bot
 ```
 
 ### 场景 2：知道 meeting_id，想查询妙记基础信息
@@ -136,7 +138,7 @@ lark-cli minutes +download --minute-tokens <minute_token>
 | `no recording available` | 该会议无录制或录制未完成 | 确认会议已结束且开启了录制 |
 | `121005 no permission` | 无权查看该会议录制 | 确认是会议参与者或有录制权限 |
 | `124002 recording generating` | 录制文件仍在生成中 | 等待录制完成后重试 |
-| `missing required scope(s)` | 权限不足 | 按提示运行 `auth login --scope` |
+| `missing required scope(s)` | 权限不足 | `--as user`：按提示运行 `auth login --scope`；`--as bot`：使用错误中的 `console_url` 去开发者后台开通，**禁止**对 bot 执行 `auth login`（见 [lark-shared](../../lark-shared/SKILL.md) 的权限恢复表） |
 
 ## 提示
 

package/skills/lark-vc/references/vc-domain-boundaries.md

@@ -99,6 +99,8 @@ lark-cli vc +search --start "<YYYY-MM-DD>" --end "<YYYY-MM-DD>" --format json
 
 #### Step 2: 根据 meeting_id 查询产物
 
+> **身份延续**：`vc +detail` 支持 `--as user` / `--as bot`。用哪个身份取到 `note_id` / `minute_token`，Step 2、Step 3 后续每一条命令（`note +detail`、`minutes +detail`、`docs +fetch`）都要显式带上**同一个** `--as`；不要省略让身份被 profile 默认值悄悄换掉。完整规则见 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 的「身份延续」。
+
 ##### 获取会议产物
 
 当用户提供 `meeting_id` 并需要会议产物时，先用 `vc +detail` 拿到 `note_id` 和 `minute_token`：
@@ -111,7 +113,7 @@ lark-cli vc +detail --meeting-ids '<meeting_id1>,<meeting_id2>'
 
 **优先路径：通过 `note_id` 获取纪要产物**
 
-如果用户未明确要求使用妙记，且返回了 `note_id`，**优先**使用 `note +detail` 获取纪要文档的 token 信息：
+如果用户未明确要求使用妙记，且返回了 `note_id`，**优先**使用 `note +detail` 获取纪要文档的 token 信息（沿用上一步的 `--as`）：
 
 ```bash
 lark-cli note +detail --note-id <note_id>
@@ -149,6 +151,9 @@ lark-cli docs +fetch --doc <note_doc_token> --doc-format markdown
 lark-cli docs +fetch --doc <verbatim_doc_token> --doc-format markdown
 
 # note_display_type=unified：逐字稿不是独立文档，按 note_id 拉取
+# ⚠️ note +transcript 目前仅支持 --as user；如果上面的 note_id 是通过 --as bot
+#    拿到的，在这一步停下来向用户说明"该纪要逐字稿只能以 user 身份读取"，
+#    只有用户明确同意才切到 --as user，不要静默切换身份重试
 lark-cli note +transcript --note-id <note_id>
 ```
 

package/skills/lark-vc-agent/SKILL.md

@@ -32,8 +32,8 @@ metadata:
 
 本 skill 与 [`lark-vc`](../lark-vc/SKILL.md) 并列：
 
-- **`lark-vc`** **负责"会后查询"**：搜索历史会议、参会人快照、纪要/逐字稿/录制
-- **`lark-vc-agent`** **负责"会中动作"**：机器人入会 / 读取进行中会议的实时事件 / 发送会中文本或会中表情 / 机器人离会
+- **`lark-vc`** **负责会议查询和共享会中能力**：发现进行中会议、读取事件、发送消息，以及搜索历史会议、查询参会人快照和会议产物
+- **`lark-vc-agent`** **负责应用机器人会中编排**：真实入会 / 离会，并复用上述共享能力读取事件或发送消息
 
 按此分工路由，避免两个 skill 语义混淆。
 
@@ -87,7 +87,22 @@ metadata:
 10. **只要你是基于** **`+meeting-events`** **来回答一场正在进行中的会议内容，就不能直接复用旧结果。** 无论用户是在问“现在/刚刚/最新”的状态，还是让你“总结一下这个会议讲什么”，都必须先重新拉一次当前事件流，确认拿到的是最新信息，再基于最新结果回答。只有在用户明确要求基于某次历史快照继续分析时，才可以复用旧结果。
 11. **会中聊天 / 互动转发到 IM 时基于 JSON 事件构造 IM post。** `chat_received_items[].message_type == 3` 表示会中 reaction；构造 IM post 时，先用 [`lark-im` reaction emoji 白名单](../lark-im/references/lark-im-reactions.md) 判断同一 item 的 `content`：白名单内才写成 Feishu post `emotion` 节点，不在白名单内则保留原始 key 并写成文本节点，例如 `[CanNotSee]`。普通聊天按文本发送。不要从 pretty/Markdown 重新拼消息，也不要把整条消息退化成纯文本；只降级非法 reaction key。用户已说“发给我 / 推送给我 / 发到我的单聊”时，默认用 bot 身份直接发当前用户；收件人不明确时只补问收件人。
 12. 用户直接问“这个会议讲了什么 / 现在讲到哪了”且上下文没有明确 `meeting_id` 时，先用用户身份发现当前会议；如果用户明确要求应用机器人视角，或上下文已经是应用机器人参会流程，再用应用身份发现。若返回多个会议，展示候选并让用户选择。
-13. 用户直接提供 **9 位会议号** 并询问会中事件/会议内容时，默认把它当作 active meeting 的筛选条件：先按当前身份查 active meetings，并在返回里匹配 `meeting_no == <9位会议号>`；匹配到唯一会议后取长数字 `meeting_id`，再用同一身份查事件。只有用户明确要求“入会 / 让应用机器人旁听 / 代我参会”时才改用 `+meeting-join`。
+13. 默认用户身份路径未发现当前会议时，改用 [`lark-vc`](../lark-vc/SKILL.md) 的 `+search` 查询当天最近结束的会议；仍无结果时询问会议时间、主题或会议号，不自行扩大时间范围。应用机器人视角未发现当前会议时，按当前身份解释空结果，不自动查询历史会议或真实入会。
+14. 用户直接提供 **9 位会议号** 并询问会中事件/会议内容时，默认把它当作 active meeting 的筛选条件：先按当前身份查 active meetings，并在返回里匹配 `meeting_no == <9位会议号>`；匹配到唯一会议后取长数字 `meeting_id`，再用同一身份查事件。只有用户明确要求“入会 / 让应用机器人旁听 / 代我参会”时才改用 `+meeting-join`。
+
+#### 文档上下文事件
+
+`event_type == "document_context_changed"` 时，结构化消费按 `payload.document_context_changed_items` 原序读取；CLI pretty timeline 与其他事件一致，按 item `time` 排序。每个 item 只接受一个 `comment_focus`、`section_location` 或 `element_preview`；零个、多个、字段缺失或未知值不生成 pretty 条目，但保留事件 `payload` 和原标识，不猜字段别名。
+
+| context | 消费规则 |
+| --- | --- |
+| `comment_focus` | 先按完整事件流中的 `magic_share_started/ended` 维护 `share_id -> share_doc` 共享会话映射，再用当前 item 的 `share_id` 精确关联文档；禁止退化为“最近一次共享”猜测。`document_context_changed` item 自带的 `share_doc` 当前不提供文档信息，只保留在 raw payload，不作为解析来源。仅当 `focused=true`、单个 `comment_id` 和由开始共享事件解析出的有效文档 URL 均存在时，用 `drive +batch-query-comments` 精确查询该 ID；严格匹配、回复分页与失败终止条件见 reference。`focused=false` 表示清除焦点，零评论调用。 |
+| `section_location` | 从当前 item 的 `parent_titles/title` 按原序派生 pretty timeline 中的章节路径；JSON/NDJSON 继续只保留原始 payload，不新增事件顶层 `section_path`。不得根据 `level` 反转、截断或补造路径，也不调用文档 API。 |
+| `element_preview` | 只有用户明确要求预览且 `action=open` 时路由：`element_type=image` 使用 `docs +media-preview --token <element_token> --output <用户选择路径>`；`element_type=whiteboard` 使用 `docs +media-download --type whiteboard --token <element_token> --output <用户选择路径>`。`close`、未知 type/action、缺 token 或无明确预览意图均零调用；禁止把未知 `element_type` 透传给 `--type`，禁止自动选择覆盖路径。 |
+
+`vc +meeting-events` 始终只读，不因评论或元素上下文自动调用 Drive/Docs，也不写文件。`share_id` 无法关联、评论 API/权限失败或 reply 游标为空/重复时，明确标记结果为未解析或 partial，并保留 `share_id`、`share_doc`、`comment_id`、`element_token`、`block_id` 和 raw payload，给出可重试的精确命令；不要用“最近一次共享”、全量评论扫描或自动下载兜底。完整命令与终止条件见 [`+meeting-events` reference](../lark-vc/references/lark-vc-meeting-events.md#文档上下文事件消费)。
+
+JSON/NDJSON 的单事件 envelope 始终只使用既有 `event_id/event_type/event_time/actors/payload` 字段；不得为 `document_context_changed` 单独增加顶层 `summary/section_path` 或新的 `derived` 层。结构化消费从 `payload.document_context_changed_items[]` 读取，pretty 仅作可读派生展示。
 
 ### 3. 发送会中文本或会中表情（写操作）
 
@@ -164,15 +179,15 @@ Shortcut 是对常用操作的高级封装（`lark-cli vc +<verb> [flags]`）。
 | Shortcut                                                        | 类型 | 说明                                                                         |
 | --------------------------------------------------------------- | -- | -------------------------------------------------------------------------- |
 | [`+meeting-join`](references/lark-vc-agent-meeting-join.md)     | 写  | Join an in-progress meeting by 9-digit meeting number                      |
-| [`+meeting-list-active`](references/lark-vc-agent-meeting-list-active.md) | 读  | List active meetings and discover meeting_id for event reads               |
-| [`+meeting-events`](references/lark-vc-agent-meeting-events.md) | 读  | List meeting events visible to the app agent (participant joined/left, transcript, chat, share) |
-| [`+meeting-message-send`](references/lark-vc-agent-meeting-message-send.md) | 写  | Send an in-meeting text message or reaction emoji                          |
+| [`+meeting-list-active`](../lark-vc/references/lark-vc-meeting-list-active.md) | 读  | List active meetings and discover meeting_id for event reads               |
+| [`+meeting-events`](../lark-vc/references/lark-vc-meeting-events.md) | 读  | List meeting events visible to the current identity (participant, transcript, chat, share, document context) |
+| [`+meeting-message-send`](../lark-vc/references/lark-vc-meeting-message-send.md) | 写  | Send an in-meeting text message or reaction emoji                          |
 | [`+meeting-leave`](references/lark-vc-agent-meeting-leave.md)   | 写  | Leave a meeting by meeting\_id                                             |
 
 - [`+meeting-join`](references/lark-vc-agent-meeting-join.md)：入参格式、写操作可见性风险、入会失败排查。
-- [`+meeting-list-active`](references/lark-vc-agent-meeting-list-active.md)：用户身份和应用身份的不同返回范围。
-- [`+meeting-events`](references/lark-vc-agent-meeting-events.md)：`meeting_id` 来源、身份延续、分页和错误码（10005 / 20001 / 20002）。
-- [`+meeting-message-send`](references/lark-vc-agent-meeting-message-send.md)：会中文本、完整 `emoji_type` 列表、身份延续和写操作风险。
+- [`+meeting-list-active`](../lark-vc/references/lark-vc-meeting-list-active.md)：用户身份和应用身份的不同返回范围。
+- [`+meeting-events`](../lark-vc/references/lark-vc-meeting-events.md)：`meeting_id` 来源、身份延续、分页和错误码（10005 / 20001 / 20002）。
+- [`+meeting-message-send`](../lark-vc/references/lark-vc-meeting-message-send.md)：会中文本、完整 `emoji_type` 列表、身份延续和写操作风险。
 - [`+meeting-leave`](references/lark-vc-agent-meeting-leave.md)：`meeting_id` 的来源与写操作可见性。
 
 ## 应用身份权限配置检查

package/skills/lark-vc-agent/references/lark-vc-agent-meeting-join.md

@@ -131,8 +131,8 @@ lark-cli vc +detail --meeting-ids <meeting.id>
 ## 参考
 
 - [lark-vc-agent-meeting-leave](lark-vc-agent-meeting-leave.md) — 对应的离会命令
-- [lark-vc-agent-meeting-list-active](lark-vc-agent-meeting-list-active.md) — 发现当前可读事件的进行中会议 ID
-- [lark-vc-agent-meeting-events](lark-vc-agent-meeting-events.md) — 会中事件流
+- [lark-vc-meeting-list-active](../../lark-vc/references/lark-vc-meeting-list-active.md) — 发现当前可读事件的进行中会议 ID
+- [lark-vc-meeting-events](../../lark-vc/references/lark-vc-meeting-events.md) — 会中事件流
 - [lark-vc-search](../../lark-vc/references/lark-vc-search.md) — 搜索历史会议记录
 - [lark-vc-recording](../../lark-vc/references/lark-vc-recording.md) — 查询 minute_token
 - [lark-vc-detail](../../lark-vc/references/lark-vc-detail.md) — 获取会议详情

package/skills/lark-vc-agent/references/lark-vc-agent-meeting-leave.md

@@ -95,8 +95,8 @@ lark-cli vc +detail --meeting-ids <meeting.id>
 ## 参考
 
 - [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 对应的入会命令
-- [lark-vc-agent-meeting-list-active](lark-vc-agent-meeting-list-active.md) — 发现当前可读事件的进行中会议 ID
-- [lark-vc-agent-meeting-events](lark-vc-agent-meeting-events.md) — 会中事件流
+- [lark-vc-meeting-list-active](../../lark-vc/references/lark-vc-meeting-list-active.md) — 发现当前可读事件的进行中会议 ID
+- [lark-vc-meeting-events](../../lark-vc/references/lark-vc-meeting-events.md) — 会中事件流
 - [lark-vc-search](../../lark-vc/references/lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
 - [lark-vc-recording](../../lark-vc/references/lark-vc-recording.md) — 查询 minute_token
 - [lark-vc-detail](../../lark-vc/references/lark-vc-detail.md) — 获取会议详情

package/skills/lark-wiki/references/lark-wiki-node-create.md

@@ -78,7 +78,7 @@ lark-cli wiki +node-create \
 | `--parent-node-token` | 否 | 父知识库节点 token；传入后会在该节点下创建新节点 |
 | `--title` | 否 | 节点标题 |
 | `--node-type` | 否 | 节点类型，默认 `origin`；可选值：`origin`、`shortcut` |
-| `--obj-type` | 否 | 节点对应对象类型，默认 `docx`；可选值：`sheet`、`mindnote`、`bitable`、`docx`、`slides` |
+| `--obj-type` | 否 | 节点对应对象类型，默认 `docx`；可选值：`sheet`、`mindnote`、`bitable`、`file`、`docx`、`slides`。`file` 仅支持 `shortcut` 节点 |
 | `--origin-node-token` | 否 | 当 `--node-type=shortcut` 时必填，表示快捷方式指向的源节点 token |
 
 ## 空间解析规则
@@ -89,11 +89,27 @@ lark-cli wiki +node-create \
 - **个人知识库回退**：`user` 身份下，如果 `--space-id` 和 `--parent-node-token` 都没传，会自动解析 `my_library`
 - **bot 身份限制**：`bot` 身份既没有“个人知识库”回退语义，也不支持显式传 `--space-id my_library`；请改用真实 `space_id` 或 `--parent-node-token`
 
-## shortcut 节点规则
+## 节点类型与对象类型
+
+| `node_type` | 支持的 `obj_type` |
+|-------------|-------------------|
+| `origin` | `sheet`、`mindnote`、`bitable`、`docx`、`slides` |
+| `shortcut` | `sheet`、`mindnote`、`bitable`、`file`、`docx`、`slides` |
 
 - `--node-type=shortcut` 时，必须同时提供 `--origin-node-token`
 - `--node-type=origin` 时，不能传 `--origin-node-token`
+- `--obj-type=file` 仅支持 `--node-type=shortcut`；实体节点不支持创建 `file` 类型
 - `shortcut` 节点只是知识库中的快捷方式入口；真正被引用的节点由 `--origin-node-token` 指定
+- 如果 `+node-create` 因上述组合返回参数校验错误，禁止改用 raw `wiki nodes create` 或直接调用 OpenAPI 绕过校验；应修正 `node_type`、`obj_type` 或 `origin_node_token`
+
+```bash
+# 创建一个指向文件的快捷方式节点
+lark-cli wiki +node-create \
+  --space-id <SPACE_ID> \
+  --node-type shortcut \
+  --obj-type file \
+  --origin-node-token <ORIGIN_NODE_TOKEN>
+```
 
 ## 一致性校验
 

package/skills/lark-wiki/references/lark-wiki-node-get.md

@@ -52,6 +52,17 @@ lark-cli wiki +node-get \
 - `creator` falls back to `creator` when `node_creator` is absent. `updated_at` is `obj_edit_time` formatted as RFC3339.
 - No `url` is returned: `get_node` does not provide one and a synthesized `www.feishu.cn/wiki/<node_token>` link is non-canonical/misleading for a read command. Use `node_token` / `obj_token` as the identifiers.
 
+## Terminal business errors
+
+These HTTP 200 responses carry a non-zero business code and are not retryable with the same input:
+
+| Code | Meaning | Required action |
+|------|---------|-----------------|
+| `131006` | The current user or app/bot identity lacks access to the Wiki node or space | This is resource access, not app scope authorization. Do not retry the same request, reauthorize, or switch identity as trial and error; ask the node owner or wiki administrator to grant read access, or use an accessible resource |
+| `131012` | The Wiki node has been deleted | Do not retry the same node token; rediscover the node or ask for a current Wiki link |
+| `131013` | The resource token is invalid | Do not switch identity or reauthorize; correct the URL/token |
+| `131014` | The document is not mounted in Wiki | Stop Wiki resolution; use the corresponding docs/sheets/base/drive command, or provide a Wiki URL/node_token |
+
 ## Required Scope
 
 `wiki:node:retrieve`

package/skills/lark-wiki/references/lark-wiki-node-list.md

@@ -87,7 +87,7 @@ lark-cli wiki +node-list --space-id 6946843325487912356 --parent-node-token wikc
 - `--space-id my_library` is a per-user alias and only valid with `--as user`. The shortcut will refuse `--as bot` with `my_library` upfront.
 - `--space-id` is a numeric wiki `space_id`. Do not pass a wiki URL, wiki node token, document token, or title. Use `lark-cli wiki +space-list --as user` to discover it.
 - `--parent-node-token` must resolve to a wiki node token. If you have a docx/sheet/base/file URL, first run `lark-cli wiki +node-get --node-token <url>` and use the returned `node_token`.
-- Treat `invalid_parameters` (`space_id is not int`, `invalid page_token`), `not_found` (`node not found by parent node token`), and `permission_denied` as terminal for the current arguments. Fix the argument or permission before retrying.
+- Treat `invalid_parameters` (`space_id is not int`, `invalid page_token`), `not_found` (`node not found by parent node token`), and `permission_denied` as terminal for the current arguments. For `131006 permission_denied`, the user or app/bot identity lacks access to the target space or parent node; this is resource access, not app scope authorization. Do not retry the same request, reauthorize, or switch identity as trial and error. Ask the resource owner or wiki administrator to grant read access, or use an accessible resource.
 - For `rate_limit`, stop immediate retries and retry later with exponential backoff or a smaller `--page-limit`.
 
 ## Required Scope

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

@@ -1,97 +0,0 @@
-# slides +replace-pages（单页或多页整页重建）
-
-替换已有演示文稿里的一页或多页，保持原 `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 对每页执行“先创建新页到旧页前，再删除旧页”；创建失败时旧页会保留。删除失败时可能出现新旧页同时存在，需要按返回结果继续处理。
-
-## 命令
-
-```bash
-lark-cli slides +replace-pages \
-  --as user \
-  --presentation <slides_url_or_xml_presentation_id> \
-  --pages @pages.json
-```
-
-## 参数
-
-| 参数 | 必需 | 说明 |
-|------|------|------|
-| `--presentation` | 是 | `xml_presentation_id`、`/slides/` URL 或 `/wiki/` URL |
-| `--pages` | 是 | JSON 数组，每项包含 `slide_id` 和 `content`；支持 literal、`@file`、stdin `-` |
-| `--dry-run` | 否 | 基于 `slide_id` 输入输出替换计划，不执行 create/delete |
-| `--continue-on-error` | 否 | 默认失败即停；开启后继续处理后续页，并在结果中标记失败项 |
-| `--validate-only` | 否 | 只校验输入并生成替换计划，不执行 Slides get/create/delete |
-
-## pages.json
-
-```json
-[
-  {
-    "slide_id": "slide_short_id_1",
-    "content": "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\"><data></data></slide>"
-  },
-  {
-    "slide_id": "slide_short_id_2",
-    "content": "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\"><data></data></slide>"
-  }
-]
-```
-
-规则：
-
-- 每项必须提供 `slide_id`；不支持 `slide_number`。
-- `content` 必须是完整 `<slide>...</slide>` XML。
-- 同一批次不能重复 `slide_id`。
-- CLI 不会回读整份 presentation；如果 `slide_id` 已失效，create/delete 阶段会返回对应错误。
-
-## Dry Run
-
-```bash
-lark-cli slides +replace-pages --as user \
-  --presentation "$PID" \
-  --pages @pages.json \
-  --dry-run
-```
-
-输出包含 `xml_presentation_id`、`pages_count`、`plan`，以及每页的 `old_slide_id`、`insert_before_slide_id` 和动作 `create_before_then_delete_old`。Dry-run 只基于输入的 `slide_id` 构造计划，不会调用 `xml_presentations.get`，也不会执行 create/delete。
-
-## 成功输出
-
-```json
-{
-  "xml_presentation_id": "xxx",
-  "pages_count": 2,
-  "status": "completed",
-  "summary": {
-    "replaced": 2,
-    "failed": 0,
-    "total": 2
-  },
-  "results": [
-    {
-      "old_slide_id": "old3",
-      "new_slide_id": "new3",
-      "status": "replaced"
-    }
-  ],
-  "revision_id": 123
-}
-```
-
-如果使用 `--continue-on-error` 且任一页面失败，CLI 会继续处理后续页，但最终以 partial failure 非零退出；stdout 仍保留完整 `results`，顶层 `ok` 为 `false`，`status` 为 `partial_failure`。
-
-`status` 可能为：
-
-- `replaced`：新页创建成功，旧页删除成功。
-- `create_failed`：新页创建失败，旧页保留。
-- `delete_failed`：新页已创建，但旧页删除失败。
-
-## 使用建议
-
-1. 大幅改写前先 `slides +xml-get` 保存当前 XML，并记录要替换页面的 `slide_id`。
-2. 生成只含 `slide_id` 的 `pages.json` 后先跑 `--dry-run` 或 `--validate-only`。
-3. 默认不要开 `--continue-on-error`，除非能接受部分页面已替换。
-4. 替换后再回读全文 XML 并截图检查，确认页序、视觉和文本没有破损。