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

package/skills/lark-slides/references/cli/lark-slides-media-upload.md

@@ -1,4 +1,3 @@
-
 # slides +media-upload（上传本地图片到飞书幻灯片）
 
 把本地图片上传到指定演示文稿的 drive 媒体库，返回 `file_token`。**返回的 token 作为 `<img src="...">` 的值塞进 slide XML 即可显示图片。**
@@ -44,7 +43,7 @@ lark-cli slides +media-upload --file ./pic.png --presentation $PRES_ID --dry-run
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--file` | 是 | 本地图片路径，**必须是 CWD 内的相对路径**（如 `./pic.png`）。**最大 20 MB**（slides upload API 不支持分片上传） |
+| `--file` | 是 | 本地图片路径，**必须是 CWD 内的相对路径**（如 `./pic.png`）。**最大 20 MB**（slides upload API 不支持分片上传）。**仅支持 png / jpeg / gif / bmp / tiff / webp** |
 | `--presentation` | 是 | `xml_presentation_id`、`/slides/<token>` URL，或 `/wiki/<token>` URL |
 
 > [!IMPORTANT]
@@ -52,7 +51,7 @@ lark-cli slides +media-upload --file ./pic.png --presentation $PRES_ID --dry-run
 
 ## 使用流程
 
-> 新建 PPT（[`+create --slides`](lark-slides-create.md)）或给已有 PPT 加新页（[`+add-slide`](../xml/lark-slides-add-slide.md)）都不需要单独上传：XML 里把 `<img src>` 写成 `@<本地路径>`，CLI 会自动上传并替换成 `file_token`。
+> 新建 PPT（[`+create --slides`](lark-slides-create.md)）或给已有 PPT 加新页（[`+add-slide`](lark-slides-add-slide.md)）都不需要单独上传：XML 里把 `<img src>` 写成 `@<本地路径>`，CLI 会自动上传并替换成 `file_token`。
 > 本命令用于往**已有页**里加图，或需要自己拿着 `file_token` 拼 XML 的场景。
 
 ### 给已有 PPT 的已有页加图
@@ -65,7 +64,7 @@ SID=yyy       # 要加图的那一页
 
 # 1) 上传图片拿 file_token
 TOKEN=$(lark-cli slides +media-upload --as user \
-  --file ./pic.png --presentation $PRES_ID | jq -r '.data.file_token')
+  --file ./pic.png --presentation $PRES_ID --jq '.data.file_token')
 
 # 2) block_insert 到页末（或用 insert_before_block_id 指定插入位置）
 lark-cli slides +replace-slide --as user \
@@ -101,4 +100,4 @@ lark-cli slides +replace-slide --as user \
 
 - [+create](lark-slides-create.md) — 新建 PPT（支持 `@` 占位符自动上传图片）
 - [+replace-slide](lark-slides-replace-slide.md) — 给已有页加图 / 换图（`block_insert` / `block_replace`）
-- [+add-slide](../xml/lark-slides-add-slide.md) — 追加/插入单页（同样支持 `@` 占位符自动上传）
+- [+add-slide](lark-slides-add-slide.md) — 追加/插入单页（同样支持 `@` 占位符自动上传）

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

@@ -2,7 +2,7 @@
 
 对指定 slide 做块级替换或插入。编辑已有 PPT 的主路径——`slide_id` 不变、页序不动、只影响被指定的块。
 
-> **`--parts` 字段名是硬约束**：装 XML 片段的字段，`block_replace` 只认 `replacement`，`block_insert` 只认 `insertion`（都是字符串）。`content` / `xml` / `new_xml` / `block_xml` / `block` / `element` / `data` 这些写法，以及任何其他字段名，**一律被 CLI 直接拒绝**——常见的错法会直接告诉你该用哪个字段（`unknown field "content"; did you mean "replacement"?`），其余只列出该 action 的合法字段集。`<content>` 是 `<shape>` 的**子元素**，不是 part 的字段名——这是最常见的搞混点。
+> **编写 `--parts` 时只使用标准 action 和字段**：`block_replace` 使用 `block_id` + `replacement`，`block_insert` 使用 `insertion`（可选 `insert_before_block_id`）。不要根据其他 API 或自然语言猜 action、字段名；具体结构以本文表格为准。
 
 相比直接调 `xml_presentation.slide.replace`，这个 shortcut 的四个额外价值：
 
@@ -76,13 +76,12 @@ lark-cli slides +replace-slide --as user \
 
 ### 错误字段名（CLI 直接拒绝）
 
-part 里出现上表以外的字段一律报错，不会被静默忽略。报错总会点名写错的那个字段，并按情况给出下一步：能对上正确字段时直接建议它（`did you mean "replacement"?`），字段属于另一个 action 时说明归属（`it belongs to block_insert`），都对不上时列出该 action 的合法字段集。无论哪种，**要改的是字段名，不是字段值**。
+编写 part 时只使用上表中的标准字段。CLI 返回 unknown field 时会点名写错的字段，并按情况给出下一步：能对上正确字段时直接建议它（`did you mean \"replacement\"?`），字段属于另一个 action 时说明归属（`it belongs to block_insert`），都对不上时列出该 action 的合法字段集。无论哪种，**要改的是字段名，不是字段值**。
 
 ```jsonc
 // ❌ 全部被拒
-[{"action":"block_replace","block_id":"bUn","content":"<p>...</p>"}]        // unknown field "content"; did you mean "replacement"?
-[{"action":"block_replace","block_id":"bUn","xml":"<shape.../>"}]           // 同上（new_xml / block_xml / element / data 一样）
-[{"action":"block_replace","block_id":"bUn","block":{"content":"..."}}]     // 不能把内容嵌一层 block
+[{"action":"block_replace","block_id":"bUn","xml":"<shape.../>"}]           // unknown field "xml"; did you mean "replacement"?
+[{"action":"block_replace","block_id":"bUn","data":"<shape.../>"}]          // data 不是标准字段
 [{"action":"block_replace","block_id":"bUn","insertion":"<shape/>"}]        // insertion 属于 block_insert
 [{"action":"block_replace","block_id":"bUn","replacement":{"type":"..."}}]  // replacement 必须是字符串，报 .replacement must be a string
 
@@ -186,7 +185,7 @@ SID=yyy
 
 # 1) 上传图片
 TOKEN=$(lark-cli slides +media-upload --as user \
-  --file ./pic.png --presentation "$PID" | jq -r '.data.file_token')
+  --file ./pic.png --presentation "$PID" --jq '.data.file_token')
 
 # 2) block_insert 到页末
 lark-cli slides +replace-slide --as user \
@@ -227,7 +226,7 @@ lark-cli slides +replace-slide --as user \
 # 读时记录 revision_id
 REV=$(lark-cli slides xml_presentation.slide get --as user \
   --params "{\"xml_presentation_id\":\"$PID\",\"slide_id\":\"$SID\"}" \
-  | jq '.data.revision_id')
+  --jq '.data.revision_id')
 
 # 写时传 --revision-id；传不存在的版本号（超过当前 revision）返回 3350002
 lark-cli slides +replace-slide --as user \
@@ -241,9 +240,11 @@ lark-cli slides +replace-slide --as user \
 |------|------|------|
 | 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 invalid JSON` | JSON 本身不完整，或被 shell 引号/转义破坏 | 将数组写入 `parts.json` 后传 `--parts @parts.json`，或通过 stdin 传给 `--parts -` |
 | `--parts[i] action "str_replace" is not supported` | CLI 不暴露 `str_replace` | 把替换需求改写成 `block_replace` / `block_insert` |
+| `--parts[i] action "page_replace" / "slide_replace" means whole-page replacement` | 把整页更新意图传给了块级 shortcut | 改用 [`slides +update-slide`](lark-slides-update-slide.md) 整页原地写回 |
 | `--parts contains N items, exceeds maximum of 200` | 一次提交 parts 太多 | 拆多次调用 |
-| `--parts[i] unknown field "content"; did you mean "replacement"?` | XML 塞进了不存在的字段名（`content` / `xml` / `block` / `data` 等） | 只改字段名：`block_replace` 用 `replacement`，`block_insert` 用 `insertion`；报错自带一行正确写法的 hint |
+| `--parts[i] unknown field "xml"; did you mean "replacement"?` | XML 塞进了未支持的字段名（如 `xml` / `new_xml` / `data`） | 使用标准字段：`block_replace` 用 `replacement`，`block_insert` 用 `insertion` |
 | `--parts[i] unknown field "insertion"; it belongs to block_insert` | 字段和 `action` 不配对 | 按 action 取字段：`block_replace` = `block_id` + `replacement`；`block_insert` = `insertion` (+ `insert_before_block_id`) |
 | `--parts[i] (block_replace) requires non-empty block_id` / `replacement` | 字段名对，但值缺失或是空串 | 按 parts 元素结构补齐值 |
 | `<img>` 不显示 / 显示破图 | `src` 写了外链 URL | 换成通过 [`+media-upload`](lark-slides-media-upload.md) 拿到的 `file_token` |
@@ -255,4 +256,4 @@ lark-cli slides +replace-slide --as user \
 - [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](../workflow/slides_editing.md) — 读-改-写闭环 + 决策树
+- [slides-editing.md](../workflow/slides-editing.md) — 读-改-写闭环 + 决策树

package/skills/lark-slides/references/{lark-slides-update-slide.md → cli/lark-slides-update-slide.md}

@@ -88,7 +88,7 @@ lark-cli slides +update-slide --as user \
 
 ## 什么时候不要用它
 
-- **只改一个元素** → 用 [`+replace-slide`](cli/lark-slides-replace-slide.md)，一条 `block_replace` part 更省，也不用带上整页
+- **只改一个元素** → 用 [`+replace-slide`](lark-slides-replace-slide.md)，一条 `block_replace` part 更省，也不用带上整页
 - **要改多个页面** → 对每一页各跑一次本命令
 - **要新建页面** → `slides +create` 或 `xml_presentation.slide create`
 
@@ -109,7 +109,7 @@ lark-cli slides +xml-get --as user \
   --presentation "$PRES" --output readback.xml
 ```
 
-按当前已加载 `lark-slides/SKILL.md` 指向的 [validation-xml.md](workflow/validation-xml.md) 完成验证：核对总页数、目标页和关键元素（包括需要保留的 ID、文本、背景与备注），并对回读 XML 运行同一版式 lint；发现差异时先停止后续写入并重新基于最新版处理。
+按当前已加载 `lark-slides/SKILL.md` 指向的 [validation-xml.md](../workflow/validation-xml.md) 完成验证：核对总页数、目标页和关键元素（包括需要保留的 ID、文本、背景与备注），并对回读 XML 运行同一版式 lint；发现差异时先停止后续写入并重新基于最新版处理。
 
 ## 成功输出
 
@@ -141,6 +141,6 @@ 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 结构有问题（如 `<shape>` 缺 `<content/>`、包含服务端不支持的元素） | 按 [error-handling.md](workflow/error-handling.md) 检查 `--content` 的 XML 结构 |
+| 3350001，其他 invalid param | `--content` 的 XML 结构有问题（如 `<shape>` 缺 `<content/>`、包含服务端不支持的元素） | 按 [error-handling.md](../workflow/error-handling.md) 检查 `--content` 的 XML 结构 |
 | 3350002 not found | `--revision-id` 传了不存在的版本号 | 用 `-1` 或真实存在的 `revision_id` |
 | 1061004 / 403 | 当前身份对这份 PPT 没有编辑权限 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope；wiki 链接另需 `wiki:node:read`；`--as bot` 还要求该 bot 对目标 PPT 有编辑权限 |

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

@@ -48,7 +48,7 @@ lark-cli slides xml_presentation.slide get --as user --params '{
 ```bash
 lark-cli slides xml_presentation.slide get --as user \
   --params '{"xml_presentation_id":"slides_example_presentation_id","slide_id":"slide_example_id"}' \
-  | jq -r '.data.slide.content'
+  --jq '.data.slide.content'
 ```
 
 ### 读指定历史版本
@@ -99,7 +99,7 @@ lark-cli slides xml_presentation.slide get --as user --params '{
    ```bash
    lark-cli slides xml_presentation.slide get --as user \
      --params "{\"xml_presentation_id\":\"$PID\",\"slide_id\":\"$SID\"}" \
-     | jq -r '.data.slide.content' | grep -oE 'id="[^"]+"' | sed 's/id="//;s/"//'
+     --jq '.data.slide.content' | grep -oE 'id="[^"]+"' | sed 's/id="//;s/"//'
    ```
 
 ## 相关命令
@@ -107,4 +107,4 @@ lark-cli slides xml_presentation.slide get --as user --params '{
 - [slides +replace-slide](lark-slides-replace-slide.md) — 块级替换 shortcut（推荐）
 - [xml_presentation.slide replace](lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考
 - [slides +xml-get](lark-slides-xml-presentations-get.md) — 读整个 PPT 并保存到本地文件
-- [lark-slides-edit-workflows.md](../workflow/slides_editing.md) — 读-改-写闭环
+- [slides-editing.md](../workflow/slides-editing.md) — 读-改-写闭环

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

@@ -95,7 +95,7 @@ lark-cli slides xml_presentation.slide replace --as user --params '{
 
 ```bash
 # 先拿 file_token
-TOKEN=$(lark-cli slides +media-upload --file ./pic.png --presentation "$PID" --as user | jq -r '.data.file_token')
+TOKEN=$(lark-cli slides +media-upload --file ./pic.png --presentation "$PID" --as user --jq '.data.file_token')
 
 lark-cli slides xml_presentation.slide replace --as user --params "{
   \"xml_presentation_id\": \"$PID\",
@@ -185,4 +185,4 @@ lark-cli slides xml_presentation.slide replace --as user --params '{
 - [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) — 读-改-写闭环 + 决策树
+- [slides-editing.md](../workflow/slides-editing.md) — 读-改-写闭环 + 决策树

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

@@ -153,5 +153,5 @@ lark-cli slides xml_presentations get --as user --params '<json_params>'
 ## 相关命令
 
 - [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) - 删除幻灯片页面
+- [slides +add-slide](lark-slides-add-slide.md) - 添加幻灯片页面
+- [slides +delete-slide](lark-slides-delete-slide.md) - 删除幻灯片页面

package/skills/lark-slides/references/lark-slides-add-slide.md

@@ -1,5 +1,5 @@
 # slides +add-slide（兼容入口）
 
-本文档已迁移至 [`xml/lark-slides-add-slide.md`](xml/lark-slides-add-slide.md)。
+本文档已迁移至 [`cli/lark-slides-add-slide.md`](cli/lark-slides-add-slide.md)。
 
 此文件仅保留旧路径兼容性；后续引用请使用新路径。

package/skills/lark-slides/references/lark-slides-delete-slide.md

@@ -1,5 +1,5 @@
 # slides +delete-slide（兼容入口）
 
-本文档已迁移至 [`xml/lark-slides-delete-slide.md`](xml/lark-slides-delete-slide.md)。
+本文档已迁移至 [`cli/lark-slides-delete-slide.md`](cli/lark-slides-delete-slide.md)。
 
 此文件仅保留旧路径兼容性；后续引用请使用新路径。

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

@@ -1,5 +1,5 @@
 # 编辑已有 PPT：读-改-写闭环（兼容入口）
 
-本文档已迁移至 [`workflow/slides_editing.md`](workflow/slides_editing.md)。
+本文档已迁移至 [`workflow/slides-editing.md`](workflow/slides-editing.md)。
 
 此文件仅保留旧路径兼容性；后续引用请使用新路径。

package/skills/lark-slides/references/workflow/error-handling.md

@@ -59,4 +59,4 @@
 
 - 图片上传、`@path` 占位符、`file_token`：见 [lark-slides-media-upload.md](../cli/lark-slides-media-upload.md) 和 [lark-slides-create.md](../cli/lark-slides-create.md)。
 - 块级替换、`block_id`、3350001 replace 细节：见 [lark-slides-replace-slide.md](../cli/lark-slides-replace-slide.md)。
-- 追加/插入单页、`--before-slide-id` 和 `--slide @file` 绕开转义：见 [lark-slides-add-slide.md](../xml/lark-slides-add-slide.md)。
+- 追加/插入单页、`--before-slide-id` 和 `--slide @file` 绕开转义：见 [lark-slides-add-slide.md](../cli/lark-slides-add-slide.md)。

package/skills/lark-slides/references/workflow/{slides_editing.md → slides-editing.md}

@@ -1,6 +1,6 @@
 # 编辑已有 PPT：读-改-写闭环
 
-局部编辑走 **shortcut [`+replace-slide`](../cli/lark-slides-replace-slide.md)**（块级替换 / 插入），配合 `xml_presentation.slide.get` 读原页拿 `block_id`。整页重建走 **[`+update-slide`](../lark-slides-update-slide.md)**，多页就每页各跑一次 —— 它原地覆盖并保留 `slide_id` 和页序；只有写进 `--content` 且带原 id 的元素才会保留元素 id，遗漏的元素会被删除。
+局部编辑走 **shortcut [`+replace-slide`](../cli/lark-slides-replace-slide.md)**（块级替换 / 插入），配合 `xml_presentation.slide.get` 读原页拿 `block_id`。整页重建走 **[`+update-slide`](../cli/lark-slides-update-slide.md)**，多页就每页各跑一次 —— 它原地覆盖并保留 `slide_id` 和页序；只有写进 `--content` 且带原 id 的元素才会保留元素 id，遗漏的元素会被删除。
 
 > 生成 XML 前**必读** [xml-schema-quick-ref.md](../xml/xml-schema-quick-ref.md)。
 
@@ -33,7 +33,7 @@ lark-cli slides +replace-slide --as user \
 
 `slide_id` / 页序不会变。`block_replace` 的 `replacement` 根元素 `id` 会自动注入为 `block_id`，用户手写 XML 时不需要自己加。
 
-> **part 的字段名是 `block_id` + `replacement`（XML 字符串）**：写成 `content` / `xml` / `block` 会被 CLI 拒绝（报 `unknown field "content"; did you mean "replacement"?`）。收到这个报错时改字段名，不要改字段值。
+> **编写 `--parts` 时只使用标准字段**：`block_replace` 使用 `action` + `block_id` + `replacement`（XML 字符串），`block_insert` 使用 `action` + `insertion`（可选 `insert_before_block_id`）。收到 unknown field 报错时应按上述结构修改字段名，而不是修改字段值。
 
 ## `revision_id` 参数
 
@@ -43,7 +43,7 @@ lark-cli slides +replace-slide --as user \
 # 读时拿当前 revision_id
 REV=$(lark-cli slides xml_presentation.slide get --as user \
   --params "{\"xml_presentation_id\":\"$PID\",\"slide_id\":\"$SID\"}" \
-  | jq '.data.revision_id')
+  --jq '.data.revision_id')
 
 # 写时传该版本号，服务端以此为 base
 lark-cli slides +replace-slide --as user \
@@ -136,7 +136,7 @@ cat parts.json | lark-cli slides +replace-slide --as user --presentation "$PID"
 ## 相关文档
 
 - [lark-slides-replace-slide.md](../cli/lark-slides-replace-slide.md) — +replace-slide shortcut 参数详情
-- [lark-slides-update-slide.md](../lark-slides-update-slide.md) — +update-slide shortcut 参数详情（整页覆盖）
+- [lark-slides-update-slide.md](../cli/lark-slides-update-slide.md) — +update-slide shortcut 参数详情（整页覆盖）
 - [lark-slides-xml-presentation-slide-get.md](../cli/lark-slides-xml-presentation-slide-get.md) — slide.get 参考（拿 `block_id` / `revision_id`）
 - [lark-slides-xml-presentation-slide-replace.md](../cli/lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考（一般直接用 shortcut 即可）
 - [lark-slides-media-upload.md](../cli/lark-slides-media-upload.md) — 上传图片拿 file_token

package/skills/lark-slides/references/workflow/validation-xml.md

@@ -1,6 +1,6 @@
 # Validation Checklist
 
-创建、大幅改写演示文稿或每次通过 `slides +update-slide` 整页写回后，必须做一次显式验证。目标是发现空白页、XML 损坏、内容截断、明显溢出、弱视觉层级和未验证输出。
+创建、大幅改写演示文稿或整页写回后，必须做一次显式验证。目标是发现空白页、XML 损坏、内容截断、明显溢出、弱视觉层级和未验证输出。
 
 小型已有页编辑也要做对应范围的验证：至少读取被改页面或全文 XML，确认目标元素已更新且未破坏周边结构。
 

package/skills/lark-task/SKILL.md

@@ -12,6 +12,18 @@ metadata:
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
 
+## 命令选择与渐进式发现（必读）
+
+执行任何 Task 命令前，必须先确认能力真实存在，禁止根据用户意图自行拼接或猜测 `+<verb>`：
+
+1. 先将用户意图与下方 Shortcut 表精确匹配。只有表中明确列出的 shortcut 才可直接选择；参数不确定时读取对应 reference 或运行该 shortcut 的 `--help`。
+2. 没有精确匹配、或无法确认当前版本是否支持时，先运行 `lark-cli task --help`，以当前 CLI 输出的命令列表为准。
+3. help 中存在匹配 shortcut 时，使用 help 列出的完整 shortcut token（例如 `+create`）运行 `lark-cli task <shortcut> --help`，再按真实 flag 执行。
+4. help 中没有匹配 shortcut 时，不得尝试相似的 `+<verb>`；从 help 中选择原生 resource，运行 `lark-cli task <resource> --help` 确认 method，再运行 `lark-cli schema task.<resource>.<method>` 获取参数结构，最后调用 `lark-cli task <resource> <method> ...`。
+5. 遇到 `unknown_subcommand` 时必须停止猜测或尝试变体，回到第 2 步重新发现能力。
+
+shortcut 名称只能来自本 Skill 的 Shortcut 表或 `lark-cli task --help`；原生 resource/method 以逐级 help 为准，参数名、类型和嵌套结构以 method schema 为准。
+
 > **任务搜索技巧**：先区分用户是否**特地指定使用搜索 skill**，以及是否真的提供了**查询关键字**（例如任务名称、关键词、片段描述）。如果用户特地指定使用搜索 skill，或明确给出了任务查询关键字，则目标是**任务**时优先使用 `+search`。如果用户没有特地指定使用搜索 skill，且意图里没有查询关键字，只有范围条件（例如“今年以来”“已完成”“由我创建”“我关注的”），并且使用 `+search` 与 `+get-related-tasks` / `+get-my-tasks` 都能达到目的时，应优先使用列表型能力，而不是搜索型能力。其中，“与我相关 / 我关注的 / 由我创建”等优先考虑 `+get-related-tasks`；“我负责的 / 分配给我”的列表优先考虑 `+get-my-tasks`。不要把时间范围词（例如“今年以来”）本身误当成 `query` 去走搜索。
 > **任务搜索相关性提示**：`+search` 当前不会自动判断搜索结果与搜索发起人的相关性。如果用户明确要求搜索“与我相关”的任务，必须先识别具体关系，获取当前用户的 `open_id`，并显式传入对应的 `--assignee`（负责人）、`--creator`（创建人）或 `--follower`（关注人）过滤条件；不能只依赖 `query` 期待自动返回与当前用户相关的任务。
 > **任务清单搜索技巧**：任务清单也遵循同样的判断逻辑。先区分用户是否**特地指定使用搜索 skill**，以及是否真的提供了**清单查询关键字**（例如清单名称、关键词、片段描述）。如果用户特地指定使用搜索 skill，或明确给出了清单查询关键字，则优先使用 `+tasklist-search`。如果用户没有特地指定使用搜索 skill，且意图里没有查询关键字，只有范围条件（例如“由我创建的任务清单”“今年以来创建的清单”），并且使用搜索或原生列取清单都能达到目的时，应优先使用原生 `tasklists.list` 接口列取清单（先 `schema task.tasklists.list`，再 `lark-cli task tasklists list --as user ...`），再按 `creator`、`created_at` 等字段做本地筛选和分页控制。

package/skills/lark-task/references/lark-task-create.md

@@ -48,7 +48,9 @@ lark-cli task +create --summary "Test Task" --dry-run
 | `--data <json>` | No | JSON object merged into the task create request for API fields without dedicated flags, such as `{"is_milestone":true}`. Explicit named flags override same-named fields in this object. |
 | `--dry-run` | No | Preview the API call (JSON payload) without actually creating the task. |
 
-Use `lark-cli schema task.tasks.create` to confirm that an extra field is supported before passing it through `--data`. Prefer this shortcut over the raw `tasks create` command when `--data` can express the request. Do not assume that other shortcuts support `--data`; check each shortcut's `--help` output first.
+> **Required:** If `task +create` has no dedicated flag for a field requested by the user, first inspect `lark-cli schema task.tasks.create`, then add that field to `--data` using the exact field name, type, and nesting from the Meta API request-body schema. Do not omit requested fields or guess their JSON shape. Keep fields already supplied through dedicated flags out of `--data`.
+
+Prefer this shortcut over the raw `tasks create` command when `--data` can express the request. Do not assume that other shortcuts support `--data`; check each shortcut's `--help` output first.
 
 ## Workflow
 

package/skills/lark-vc/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-vc
 version: 1.0.0
-description: "飞书视频会议：搜索历史会议记录、查询会议纪要（总结/待办/章节/逐字稿）、查询参会人快照。当用户查询已结束的会议、获取会议产物（纪要/妙记）、查看参会人时使用；查询未来日程走 lark-calendar。不负责：Agent 真实入会/离会、会中实时事件（走 lark-vc-agent）。"
+description: "飞书视频会议：查询进行中的会议列表（含会议 ID）、读取会中实时内容（发言、聊天、共享等）、发送会中消息，以及搜索历史会议、查询会议纪要（总结/待办/章节/逐字稿）和参会人快照。Agent 真实入会/离会走 lark-vc-agent；查询未来日程走 lark-calendar。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -20,7 +20,9 @@ metadata:
 
 ## 身份
 
-所有 vc 命令默认使用 `--as user`。`+search` 和 `meeting get` 也支持 `--as bot`。
+身份是跨命令工作流的状态，不是单条命令的局部参数：一旦某个 ID（如 `note_id`、`minute_token`）由某个身份取得，后续消费它的命令（包括跨到 lark-minutes / lark-note / lark-doc）必须显式沿用相同 `--as`；不要依赖 profile 默认身份，也不要为绕过权限错误切换身份。完整规则见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 的「身份延续」。
+
+本 skill 默认使用 `--as user`。`+detail`、`+recording`、`meeting get`、`+meeting-list-active`、`+meeting-events` 和 `+meeting-message-send` 也支持 `--as bot`；`+meeting-events` 和 `+meeting-message-send` 必须沿用 `meeting_id` 的来源身份。`+search` 仅支持 `--as user`。
 
 ```bash
 # BAD — 查昨天的会议用 calendar，会漏掉即时会议
@@ -37,6 +39,9 @@ lark-cli vc +search --query "站会" --start <start_time> --end <end_time>
 | [`+search`](references/lark-vc-search.md) | 搜索历史会议记录（需至关键词、时间范围、组织者、参与者、会议室少一个筛选条件） |
 | [`+detail`](references/lark-vc-detail.md) | 通过 meeting-ids 获取会议详情，包括 note_id 和 minute_token |
 | [`+recording`](references/lark-vc-recording.md) | 通过 meeting-ids 或 calendar-event-ids 查询 minute_token |
+| [`+meeting-list-active`](references/lark-vc-meeting-list-active.md) | 查询当前身份可见的进行中会议并获取 `meeting_id` |
+| [`+meeting-events`](references/lark-vc-meeting-events.md) | 读取当前身份可见的会中事件 |
+| [`+meeting-message-send`](references/lark-vc-meeting-message-send.md) | 发送会中文本或 reaction |
 
 - 使用任何 Shortcut 前，必须先读其对应 reference 文档。
 
@@ -47,8 +52,10 @@ lark-cli vc +search --query "站会" --start <start_time> --end <end_time>
 | 查"昨天的会议""上周的会""已结束的会议" | 本 skill（`+search`，含即时会议） |
 | 查日历/日程或未来时间的会议 | [lark-calendar](../lark-calendar/SKILL.md) |
 | 查"今天有哪些会议" | `vc +search`（已结束）+ lark-calendar（未开始），合并展示 |
+| 查询进行中的会议、会中事件或发送会中消息 | 本 skill 的 `+meeting-list-active` / `+meeting-events` / `+meeting-message-send`，也可由 [lark-vc-agent](../lark-vc-agent/SKILL.md) 编排 |
+| 用户询问会议内容，但未提供 `meeting_id`，也未明确指向已结束会议 | 先用 `+meeting-list-active` 查询进行中的会议；无结果时，再用 `+search` 查询当天最近结束的会议；仍无结果时询问会议时间、主题或会议号，不自行扩大时间范围 |
 | 只按自然语言标题查"xx 纪要的逐字稿 / 原始记录 / 谁说了什么" | 先到 [lark-drive](../lark-drive/SKILL.md) / [lark-doc](../lark-doc/SKILL.md)；仅在已拿到 `note_id` / `vc-node-id` 后再到 [lark-note](../lark-note/SKILL.md) |
-| Agent 真实入会/离会、会中实时事件 | [lark-vc-agent](../lark-vc-agent/SKILL.md) |
+| Agent 真实入会/离会 | [lark-vc-agent](../lark-vc-agent/SKILL.md) |
 | 妙记信息/时长/封面/链接 | 先走 `vc +detail` 或 `vc +recording` 获取 `minute_token`，再用 [lark-minutes](../lark-minutes/SKILL.md) 的 `minutes get` |
 | 本地音视频文件转纪要/逐字稿 | 先走 [lark-minutes](../lark-minutes/SKILL.md) 上传，再用 `minutes +detail --minute-tokens` |
 
@@ -142,7 +149,7 @@ lark-cli vc meeting get --params '{"meeting_id":"<meeting_id>","with_participant
 |---------|---------|--------|
 | 参会人快照（谁参加过、何时入/离会，任意时点）| `vc meeting get --with-participants` | 本 skill |
 | 已结束会议的发言内容 | 优先：`vc +detail` 取 `note_id` 再 `note +detail` 取 `verbatim_doc_token` 后 `docs +fetch`；备选：`vc +detail` 取 `minute_token` 再 `minutes +detail --transcript` | [lark-note](../lark-note/SKILL.md) / [lark-minutes](../lark-minutes/SKILL.md) |
-| **进行中会议**的实时事件流（转写、聊天、共享、会中加入/离开）| `vc +meeting-events` | [`lark-vc-agent`](../lark-vc-agent/SKILL.md) |
+| **进行中会议**的实时事件流（转写、聊天、共享、会中加入/离开）| `vc +meeting-events` | 本 skill / [`lark-vc-agent`](../lark-vc-agent/SKILL.md) |
 | **Agent 真实入会 / 离会** | `vc +meeting-join` / `vc +meeting-leave` | [`lark-vc-agent`](../lark-vc-agent/SKILL.md) |
 
 ## 资源关系
@@ -173,6 +180,7 @@ Meeting (视频会议)
 > - 已有 `doc_token` 且目标是读正文 → [lark-doc](../lark-doc/SKILL.md)。
 > - 只有自然语言纪要标题 → 文档搜索 / Docx 正文读取；有显式 `vc-node-id` 才进入 [lark-note](../lark-note/SKILL.md)。
 > - 从日程出发（只有 `event_id`）→ 先走 [`calendar +meeting`](../lark-calendar/references/lark-calendar-meeting.md) 拿到 `meeting_id` 或 `meeting_note`，再按上述路径继续。
+> - **跨到 lark-minutes / lark-note / lark-doc 时必须沿用来源身份**：例如 `vc +detail --as bot` 拿到的 `note_id`，下一步 `note +detail --note-id <note_id>` 也要显式加 `--as bot`；不要省略 `--as` 让身份被 profile 默认值悄悄换成 user（或反过来）。`note +transcript` 目前仅支持 `--as user`——如果 `note +detail --as bot` 返回 `note_display_type=unified`，停在这一步向用户说明"该纪要的逐字稿只能以 user 身份读取"，只有用户明确同意才切到 `--as user`，不要静默切换。
 
 ## API Resources
 
@@ -199,7 +207,7 @@ lark-cli vc meeting get --params '{"meeting_id": "<meeting_id>", "with_participa
 ## 不在本 skill 范围
 
 - 查询未来的会议日程 → [lark-calendar](../lark-calendar/SKILL.md)
-- Agent 真实入会/离会、会中实时事件 → [lark-vc-agent](../lark-vc-agent/SKILL.md)
+- Agent 真实入会/离会 → [lark-vc-agent](../lark-vc-agent/SKILL.md)
 - 只有纪要文档标题的逐字稿查询 → 文档搜索 / Docx 正文读取；有显式 `vc-node-id` 才进入 [lark-note](../lark-note/SKILL.md)
 - 本地音视频文件转纪要/逐字稿、妙记搜索/下载/上传/重命名/替换说话人 → [lark-minutes](../lark-minutes/SKILL.md)
 - 通过 `note_id` 取纪要文档 Token → [lark-note](../lark-note/SKILL.md)

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

@@ -1,13 +1,16 @@
 
 # vc +detail
 
-通过会议 ID 获取会议详情，包括基本信息、关联的纪要 ID（`note_id`）和妙记 Token（`minute_token`）。只读。
+通过会议 ID 获取会议详情，包括基本信息、关联的纪要 ID（`note_id`）和妙记 Token（`minute_token`）。只读，支持 `--as user` / `--as bot`。
 
 ## 命令
 
 ```bash
 # 单个 / 批量（逗号分隔，最多 50 个）
 lark-cli vc +detail --meeting-ids <meeting_id1>,<meeting_id2>
+
+# bot 身份（只能查 bot 有权限的会议）
+lark-cli vc +detail --meeting-ids <meeting_id1>,<meeting_id2> --as bot
 ```
 
 ## 输出字段
@@ -26,19 +29,21 @@ lark-cli vc +detail --meeting-ids <meeting_id1>,<meeting_id2>
 
 ### 场景 1：获取会议的纪要和妙记关联
 
-`vc +detail` 只能拿到 `note_id` 和 `minute_token`，不直接返回纪要文档 token 与妙记产物内容。要获取实际产物，需根据用户诉求继续调用 `note +detail` 或 `minutes +detail`：
+`vc +detail` 只能拿到 `note_id` 和 `minute_token`，不直接返回纪要文档 token 与妙记产物内容。要获取实际产物，需根据用户诉求继续调用 `note +detail` 或 `minutes +detail`，**并沿用第 1 步同一个 `--as`**（完整规则见 [lark-shared](../../lark-shared/SKILL.md) 的「身份延续」）：
 
 ```bash
 # 1. 获取会议详情，拿到 note_id 和 minute_token
-lark-cli vc +detail --meeting-ids <meeting_id>
+lark-cli vc +detail --meeting-ids <meeting_id> --as bot
 
 # 2. 用 note_id 获取纪要文档 Token（note_doc_token / verbatim_doc_token / shared_doc_tokens）
-lark-cli note +detail --note-id <note_id>
+#    显式沿用第 1 步的身份，不要省略 --as
+lark-cli note +detail --note-id <note_id> --as bot
 
-# 3. 用 minute_token 获取妙记产物
+# 3. 用 minute_token 获取妙记产物（同样沿用第 1 步的身份）
 # ⚠️ 必须显式指定 --summary / --todo / --chapter / --keyword / --transcript 中至少一个 flag，
 # 不传任何 flag 则不会返回任何产物内容。
-lark-cli minutes +detail --minute-tokens <minute_token> --todo --transcript
+lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --todo --transcript --as bot
 ```
 
 > **路由建议**：当用户未明确指定使用妙记时，**优先**走 `note +detail` 链路（纪要文档信息更完整、含逐字稿原文），仅在 `note_id` 为空或用户要求妙记产物时才走 `minutes +detail`。
+> **身份边界**：`note +transcript` 目前仅支持 `--as user`。若上面第 2 步用 `--as bot` 拿到 `note_display_type=unified`，停下来向用户说明该纪要逐字稿只能以 user 身份读取，只有用户明确同意才切换身份重试。

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

@@ -65,7 +65,7 @@ lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token
 lark-cli vc +meeting-join --as bot --meeting-number 123456789
 
 # 再查询事件
-lark-cli vc +meeting-events --as bot --meeting-id <id>
+lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
 ```
 
 如果应用机器人已经在会中，也可以先通过 active meeting 找会：
@@ -114,7 +114,9 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pret
 - `--format pretty`：默认推荐格式，输出当前身份和逐条时间线，适合快速理解“发生了什么”。
 - `--format ndjson`：输出事件行，并带 metadata 行，适合流式消费。
 
-**选型原则**：只在 `pretty`、`json`、`ndjson` 之间选择。目标是告诉用户“发生了什么”时，用 `--page-all --format pretty`；需要稳定字段给 agent 做结构化消费、总结、转发或二次处理时用 `--format json`；需要流式消费时用 `--format ndjson`。
+**选型原则**：默认先用 `--format pretty`；仅当 `pretty` 缺少完成任务所必需的结构化字段时，才改用 `--format json`。用户明确要求 JSON 或规则明确要求结构化字段时可直接用 `--format json`；需要流式消费时用 `--format ndjson`。
+
+> **JSON 成本**：JSON 保留完整 payload，输出通常远大于 `pretty`；长会全量拉取时会显著占用上下文空间。
 
 > **注意**：pretty 输出中的正文文本会做单行转义，真实换行会显示为 `\n`，避免打乱时间线布局。
 
@@ -131,19 +133,117 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pret
 
 执行准则：
 
-- 如果上下文已有明确 `meeting_id`，沿用该 `meeting_id` 的来源身份执行 `+meeting-events --page-all --format json`。
 - 如果上下文没有明确 `meeting_id`，先按用户当前意图选择身份：问“我/当前用户所在会议”用 `lark-cli vc +meeting-list-active --as user --format json`；问“应用机器人可见的目标用户会议”用 `lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json`。返回多个会议时先让用户选择。
 - 如果上下文只有 9 位会议号，先按当前身份执行 `+meeting-list-active` 并按 `meeting_no` 匹配；匹配到唯一会议后再查事件。不要为了总结会议而自动调用 `+meeting-join`。
-- 这类问题拿到 `meeting_id` 后，用同一身份执行 `lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-all --format json` 拉取最新事件流。
-- 如果事件中出现共享文档线索，例如：
-  - `magic_share_started`
-  - `share_doc.title`
-  - `share_doc.url`
-- 必须继续读取共享文档内容，再生成总结，不能只根据“开始共享了某文档”这条事件和文档标题来概括会议内容。
-- 若存在多个共享文档，优先读取**最近一次共享**的文档。
+- 确认 `meeting_id` 后，沿用其来源身份执行 `lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-all --format pretty` 拉取最新事件流。
+- 如果事件流显示开始共享内容（JSON 事件类型为 `magic_share_started`，pretty 时间线显示“开始共享”），并包含文档标题或 URL 等线索，必须继续读取共享文档内容后再生成总结，不能只根据共享事件和文档标题概括会议内容。
+- 若存在多个共享文档，按用户问题读取相关文档；处理某条文档上下文事件时必须按该 item 的 `share_id` 精确关联，不能用“最近一次共享”替代。
 - 若文档读取失败，必须明确说明“以下总结仅基于会中事件流，未成功读取共享文档内容”。
 
-### 7. 关于 `page_token` 的返回与续拉
+### 7. 文档上下文事件消费
+
+`document_context_changed` 是只读线索事件。需要根据该事件执行评论、章节或预览等后续处理时，必须用 `+meeting-events --page-all --format json` 读取 `share_id`、`comment_id`、`element_token` 等完整字段；仅向用户展示时间线时仍默认使用 pretty。`vc +meeting-events` 保留原始 payload，并按既有事件输出约定派生 actor 与 pretty timeline；它不会为单个事件类型扩张 JSON/NDJSON 公共 envelope，也不会查询评论、下载素材或写文件。后续 Drive/Docs 命令只能由 Agent 按下表显式选择。
+
+#### 共享会话关联
+
+`share_id` 标识一次共享会话。Agent 按事件时间顺序消费完整事件流，并维护共享会话状态：
+
+1. 从 `payload.magic_share_started_items[]` 读取 `share_id` 和 `share_doc`，建立 `share_id -> share_doc` 映射并标记会话开始。同一 `share_id` 重复携带相同文档时按幂等事件处理；若指向不同文档则停止解析，不覆盖旧映射。
+2. `document_context_changed_items[]` 通过自己的 `share_id` 精确查找该映射。当前契约中 item 自带的 `share_doc` 不提供文档信息；只保留它的原始值，不作为 URL/title 来源，也不做冲突判定。
+3. `payload.magic_share_ended_items[]` 使用相同 `share_id` 标记该会话结束。历史映射可保留用于解释本批次中结束前已发生的上下文事件，但不能再作为新的活动共享会话。
+4. 增量拉取从会话中途开始且本地没有对应映射时，重新拉取包含 `magic_share_started` 的完整事件流；仍无法命中则标记未解析。禁止回退到当前文档、最近一次共享或其他 `share_id`。
+
+#### 字段合同
+
+| 路径 | 含义与处理 |
+| --- | --- |
+| `payload.magic_share_started_items[].share_id/share_doc` | 建立一次共享会话与文档 URL/title 的映射。缺 `share_id` 时不建立映射。 |
+| `payload.magic_share_ended_items[].share_id` | 结束同一 `share_id` 的共享会话；不得结束其他映射。 |
+| `payload.document_context_changed_items[]` | 结构化消费按原序读取；pretty timeline 沿用统一时间排序。每项恰有一个已知 context 才生成 pretty 条目，未知/歧义项只保留 raw。 |
+| `item.operator` | 当前 item 的 actor；缺 ID/name 时不猜共享发起人。 |
+| `item.share_id` | 当前上下文所属共享会话；用它精确查找 `magic_share_started` 建立的 `share_doc` 映射。 |
+| `item.share_doc.url/title` | 当前不作为文档元信息来源；保留在 raw payload 以兼容未来扩展。文档 URL/title 只从同 `share_id` 的 `magic_share_started` 映射取得。 |
+| `item.time` | Unix 毫秒字符串；缺失或非法时 timeline 回退到事件时间。 |
+| `item.comment_focus.comment_id/focused` | `focused=true` 才精确查询一个 comment ID；`false` 是清除焦点，零查询。 |
+| `item.section_location.parent_titles/title/level` | `section_path` 按 parent 原序再追加 title，trim 后丢弃空段，以 ` > ` 连接；`level` 仅作诊断，不参与截断或补层。 |
+| `item.element_preview.action/element_type/element_token/block_id` | 只有 `open + image + token`、`open + whiteboard + token` 可在明确预览意图下路由；其他组合零调用。 |
+| 事件公共 envelope | JSON/NDJSON 只使用既有 `event_id/event_type/event_time/actors/payload`；不新增顶层 `summary/section_path`，也不发明 `derived.document_context`。 |
+| 事件 `payload` | 原始恢复面；未知字段保留，顶层空数组沿用所有会议事件共用的压缩规则，派生字段不会写回 payload。 |
+
+#### 评论聚焦：只查一个 ID
+
+先读取当前 item 的 `share_id` 和 `comment_focus.comment_id`，再按“共享会话关联”取得 `share_doc.url`。优先把完整 URL 传给现有 shortcut，由它解析实际 `file_token/file_type`（含 Wiki 解包）；如果上游只留下裸 token，则必须同时提供已解析且受支持的 `file_type`。
+
+```bash
+# 推荐：share_doc.url 完整可用
+lark-cli drive +batch-query-comments \
+  --as <same_identity> \
+  --url "<share_doc.url>" \
+  --comment-ids "<comment_focus.comment_id>" \
+  --format json
+
+# 只有已经可靠解析出裸 token/type 时使用
+lark-cli drive +batch-query-comments \
+  --as <same_identity> \
+  --token "<file_token>" \
+  --type "<file_type>" \
+  --comment-ids "<comment_focus.comment_id>" \
+  --format json
+```
+
+该 shortcut 对应 `drive.file.comments.batch_query`，请求体必须只有 `comment_ids:["<当前comment_id>"]`。响应处理规则：
+
+1. 整个响应 `items` 长度必须恰为 1，且 `items[0].comment_id` 必须与请求 ID 完全相等。`items` 为空、多于 1 项或唯一项 ID 不同都停止；即使多项中恰有一项匹配，也不得挑选该项继续。失败时保留 `share_doc/comment_id`，禁止改用 `drive +list-comments` 扫描整篇文档。
+2. `item.quote` 是引用位置；评论正文和回复在 `item.reply_list.replies`，其中第一条是根评论。
+3. 完整性看命中评论卡片的 **`item.has_more`**，不是外层评论分页，也不是根据非空 `page_token` 猜测。`item.has_more=false` 时直接使用内嵌列表，零 `+list-replies` 调用。
+4. `item.has_more=true` 时忽略截断列表，从**不带 `--page-token` 的第一页**开始重建完整 replies：
+
+```bash
+lark-cli drive +list-replies \
+  --as <same_identity> \
+  --url "<share_doc.url>" \
+  --comment-id "<comment_focus.comment_id>" \
+  --page-size 100 \
+  --format json
+
+lark-cli drive +list-replies \
+  --as <same_identity> \
+  --url "<share_doc.url>" \
+  --comment-id "<comment_focus.comment_id>" \
+  --page-size 100 \
+  --page-token "<returned_page_token>" \
+  --format json
+```
+
+第一页 `items[0]` 才是根评论；后续页的 `items[0]` 是普通回复。按页原序累积，直到页级 `has_more=false`。如果 `has_more=true` 但 `page_token` 为空、与已用 token 重复、API/权限失败或 comment ID 改变，立即停止并标记为 `partial`；保留已经取得的内容和原始标识，不循环、不重复根评论、不声称完整。
+
+#### 章节定位
+
+结构化消费直接读取当前 `section_location` item。pretty timeline 会按 `parent_titles` 原序追加 `title`，trim 后丢弃空段，并以 ` > ` 连接；多个 section item 分别展示，不选择其中一个覆盖事件级标量；标题全空时不生成 pretty 条目，只保留 raw。该路径是本地展示派生，不写回 JSON/NDJSON，也不需要或允许为它新增 API 查询。
+
+#### 元素预览：显式白名单
+
+只有用户或上层 Agent 明确要求预览，并且 item 命中下表时才执行。两个命令都会写入 `--output`，因此输出路径必须由本次调用显式选择；不得默认覆盖已有文件。
+
+| action | element_type | token 条件 | 精确命令 |
+| --- | --- | --- | --- |
+| `open` | `image` | `element_token` 非空 | `lark-cli docs +media-preview --as <same_identity> --token "<element_token>" --output "<explicit-path>"` |
+| `open` | `whiteboard` | `element_token` 非空 | `lark-cli docs +media-download --as <same_identity> --type whiteboard --token "<element_token>" --output "<explicit-path>"` |
+| `close` | `image`/`whiteboard` | 任意 | 零调用；pretty 只记录预览关闭 |
+| 未知 | 任意 | 任意 | 零调用；不生成 pretty 条目，只保留 raw |
+| `open` | 未知/空 | 任意 | 零调用；禁止把原值透传到 `--type` |
+| `open` | `image`/`whiteboard` | token 为空 | 零调用；保留 `block_id/element_type/action` 并提示缺 token |
+
+#### 失败恢复
+
+- parser 遇到未知字段、歧义 one-of 或单 item 缺字段：保留整个事件 `payload`、`event_id/event_type/event_time` 和可用 sibling；该 item 不生成 pretty 条目，也不合成通用描述。
+- `share_id` 缺失、映射未命中或 `share_doc` 冲突：回显 `share_id`、可用的 `share_doc.url/title` 与 `comment_id`；必要时重新拉取完整事件流，仍无法关联则停止，不用最近一次共享兜底。
+- `share_doc` 无法解析：回显 `share_id`、`share_doc.url/title` 与 `comment_id`，提示需要有效文档 URL 或已确认的 `file_token/file_type`；不要猜 type。
+- Drive API/权限失败：保留精确 batch-query 命令与 `comment_id`，根据 CLI 的 `missing_scopes/hint` 恢复权限后重试；不要扫描全部评论。
+- Docs 预览失败：保留 `action/element_type/element_token/block_id` 和用户选择的输出路径，修复权限或 token 后重试同一白名单命令；不要让 `meeting-events` 自动下载兜底。
+- 未知 context/type/action：保留 raw 并说明当前 CLI 没有安全路由；不得自动调用 overwrite、download 或任何猜测的 shortcut。
+
+### 8. 关于 `page_token` 的返回与续拉
 
 - 不管这次是只查 1 页，还是通过 `--page-all` 已经把当前可见事件都拿完，都应把最后拿到的 `page_token` 一并保留下来并返回给用户。
 - 只要响应里出现 `has_more=true`、pretty 里出现 `more available`，或返回了非空 `page_token`，就必须先判断当前结果是否完整；默认情况下，这意味着你还需要继续分页。
@@ -160,7 +260,7 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pret
 |------|------|
 | `meeting` | 会议身份与时间状态，包含 `id/topic/meeting_no/start_time/end_time/status` |
 | `identity` | 当前读取身份，包含 `id/name/participant_type/label` |
-| `events` | 结构化事件列表；每条事件含参与者 `actors` 和事件细节 `payload` |
+| `events` | 结构化事件列表；每条事件沿用 `event_id/event_type/event_time/actors/payload` 公共 envelope，事件专属数据保留在 `payload` |
 | `warnings` | 非阻断告警列表；事件列表本身仍可使用 |
 | `has_more` | 是否还有下一页 |
 | `page_token` | 下一页游标 |
@@ -175,6 +275,7 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pret
 | `transcript_received` | 收到转写文本 |
 | `magic_share_started` | 开始共享内容 / 文档 |
 | `magic_share_ended` | 结束共享 |
+| `document_context_changed` | 评论聚焦、章节定位或元素预览上下文变化 |
 
 ### Forwarding meeting chat and reactions to IM
 
@@ -304,12 +405,12 @@ lark-cli vc +meeting-events \
 
 ## 参考
 
-- [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-leave](lark-vc-agent-meeting-leave.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) — 获取会议详情
-- [lark-vc-agent](../SKILL.md) — Agent 参会能力（本 skill）
-- [lark-vc](../../lark-vc/SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
+- [lark-vc-agent-meeting-join](../../lark-vc-agent/references/lark-vc-agent-meeting-join.md) — 先真实入会
+- [lark-vc-meeting-list-active](lark-vc-meeting-list-active.md) — 发现当前可读事件的进行中会议 ID
+- [lark-vc-agent-meeting-leave](../../lark-vc-agent/references/lark-vc-agent-meeting-leave.md) — 用户明确要求时离会
+- [lark-vc-search](lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
+- [lark-vc-recording](lark-vc-recording.md) — 查询 minute_token
+- [lark-vc-detail](lark-vc-detail.md) — 获取会议详情
+- [lark-vc-agent](../../lark-vc-agent/SKILL.md) — Agent 参会能力
+- [lark-vc](../SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
 - [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数