@amaster.ai/pi-lark 0.1.8 → 0.1.10

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

@@ -5,25 +5,13 @@
 
 本 skill 对应 shortcut：`lark-cli vc +meeting-join`（调用 `POST /open-apis/vc/v1/bots/join`）。
 
-> **不要把 9 位会议号等同于入会意图。** 用户给出 9 位会议号并询问“会议讲了什么 / 查会中事件”时，先用 `+meeting-list-active` 查当前 active meetings 并按 `meeting_no` 匹配；只有用户明确要求“入会 / 让应用机器人旁听 / 代我参会”时才调用本命令。
+> **不要把 9 位会议号等同于入会意图。** 用户给出 9 位会议号并询问“会议讲了什么 / 查会中事件”时，先用 `vc +meeting-list-active` 查当前 active meetings 并按 `meeting_no` 匹配；只有用户明确要求“入会 / 让应用机器人旁听 / 代我参会”时才调用本命令。
 
 ## 命令
 
 ```bash
 # 仅指定会议号（无密码）
 lark-cli vc +meeting-join --as bot --meeting-number 123456789
-
-# 指定会议号 + 密码
-lark-cli vc +meeting-join --as bot --meeting-number 123456789 --password 8888
-
-# 从邀请事件透传 call_id（参见「如何获取输入参数」）
-lark-cli vc +meeting-join --as bot --meeting-number 123456789 --call-id a08e06bf-9a41-44e4-a89c-a7871899e783
-
-# 输出格式
-lark-cli vc +meeting-join --as bot --meeting-number 123456789 --format json
-
-# 预览 API 调用（不实际加入会议）
-lark-cli vc +meeting-join --as bot --meeting-number 123456789 --dry-run
 ```
 
 ## 参数
@@ -81,36 +69,6 @@ lark-cli vc +meeting-join --as bot --meeting-number 123456789 --dry-run
 | `password` | 若会议设置了入会密码，由主持人提供 |
 | `call-id` | 由 `vc.bot.meeting_invited_v1` 邀请事件的 `call_id` 字段携带，Agent 收到事件时透传过来；无邀请事件场景（如 Agent 主动入会）不传 |
 
-## Agent 组合场景
-
-### 场景 1：加入会议 → 监听会中事件
-
-```bash
-# 第 1 步：加入会议，记录返回的 meeting.id
-lark-cli vc +meeting-join --as bot --meeting-number 123456789
-
-# 第 2 步：使用返回的 meeting.id 查询会中事件
-lark-cli vc +meeting-events --as bot --meeting-id <meeting.id> --page-all --format pretty
-```
-
-如果 bot 已经在会中，也可以通过 active meeting 找回 `meeting_id`：
-
-```bash
-lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
-```
-
-### 场景 2：加入会议 → 会后进入 lark-vc 获取会议产物信息
-
-```bash
-# 第 1 步：加入并参会
-lark-cli vc +meeting-join --as bot --meeting-number 123456789
-
-# 第 2 步：会议结束后，先查询会议产物
-lark-cli vc +detail --meeting-ids <meeting.id>
-```
-
-后续按 `lark-vc` 的产物决策处理：根据 `note_display_type`、`note_id`、`minute_token` 和用户意图选择纪要正文、逐字稿或妙记。
-
 ## 常见错误与排查
 
 | 错误现象 | 根本原因 | 解决方案 |
@@ -119,7 +77,7 @@ lark-cli vc +detail --meeting-ids <meeting.id>
 | 会议密码错误 | `--password` 错误或未提供 | 向主持人确认会议密码 |
 | 会议不存在 / 已结束 | 会议号错误或会议未进行中 | 确认会议正在进行中 |
 | `HTTP 403: no permission` / `121003` | 入会前置条件不满足，通常不是单纯 scope 问题 | 依次确认：1）会议允许智能体加入；2）会议号正确；3）如有密码，已正确传入 `--password`；4）会议已开始；5）等候室 / 入会审批已放行；6）会议未禁止当前身份加入（如限制外部、限制应用机器人、仅特定成员可入会）；确认后重试 |
-| 应用身份权限不足 | 应用权限、租户安装、权限可访问的数据范围或 VC Agent privilege 未配置完整 | 不要执行 `auth login`。以 CLI 返回的 metadata / error envelope 为准确认缺失权限；检查应用发布/安装，以及开放平台“权限可访问的数据范围”：选择“按条件筛选”，条件为“会议的归属者 包含 与应用的可用范围一致”；仍失败再排查内测 privilege / 灰度 |
+| 应用身份权限不足 | 应用权限、租户安装或权限可访问的数据范围未配置完整 | 不要执行 `auth login`。以 CLI 返回的 metadata / error envelope 为准确认缺失权限；检查应用发布/安装，以及开放平台“权限可访问的数据范围”：选择“按条件筛选”，条件为“会议的归属者 包含 与应用的可用范围一致”；配置正确仍失败时，保留错误码和 `log_id`，按服务端权限异常排查 |
 | 入会被拒绝 | 等候室 / 入会审批 / 限制外部入会 | 联系主持人放行或调整会议设置 |
 
 ## 提示
@@ -128,14 +86,5 @@ lark-cli vc +detail --meeting-ids <meeting.id>
 - 入会会让机器人立即出现在参会列表；若用户要求退出 / 离开 / 结束参会，直接使用 `+meeting-leave --as bot --meeting-id <meeting.id>`。参数格式不确定时可选 `--dry-run` 预览，但不是必经步骤。
 - 执行成功后，立即记录返回的 `meeting.id`，用于后续 `+meeting-leave` / `+meeting-events`。
 
-## 参考
-
-- [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-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) — 获取会议详情
-- [lark-vc-agent](../SKILL.md) — Agent 参会能力（本 skill）
-- [lark-vc](../../lark-vc/SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
-- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
+## 相关场景
+- [应用机器人参会与会中互动](../scenes/live-meeting-attend.md)

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

@@ -10,12 +10,6 @@
 ```bash
 # 通过 meeting_id 离会
 lark-cli vc +meeting-leave --as bot --meeting-id 69xxxxxxxxxxxxx28
-
-# 输出格式
-lark-cli vc +meeting-leave --as bot --meeting-id 69xxxxxxxxxxxxx28 --format json
-
-# 预览 API 调用（不实际离会）
-lark-cli vc +meeting-leave --as bot --meeting-id 69xxxxxxxxxxxxx28 --dry-run
 ```
 
 ## 参数
@@ -54,30 +48,6 @@ lark-cli vc +meeting-leave --as bot --meeting-id 69xxxxxxxxxxxxx28 --dry-run
 |---------|---------|
 | `meeting-id` | `+meeting-join --as bot` 返回的 `meeting.id`；或应用身份 `+meeting-list-active --as bot --user-id <user_open_id>` 返回的 `meeting_id` |
 
-## Agent 组合场景
-
-### 场景 1：加入 → 用户明确要求时离开
-
-```bash
-# 第 1 步：加入会议，记录 meeting.id
-lark-cli vc +meeting-join --as bot --meeting-number 123456789
-
-# 第 2 步：在会中处理用户请求（如监听发言、记录信息等）
-# ...
-
-# 第 3 步：仅在用户明确要求退出 / 离开 / 结束参会时，使用上一步记录的 meeting.id 离会
-lark-cli vc +meeting-leave --as bot --meeting-id <meeting.id>
-```
-
-### 场景 2：会后补拉产物（不需要离会）
-
-如果用户只是要求会议结束后拉录制、纪要或逐字稿，不要先调用 `+meeting-leave`；直接跨到 `lark-vc` 查询会后产物。
-
-```bash
-# 第 1 步：会议结束后进入 lark-vc 获取会议产物信息
-lark-cli vc +detail --meeting-ids <meeting.id>
-```
-
 ## 常见错误与排查
 
 | 错误现象 | 根本原因 | 解决方案 |
@@ -92,14 +62,5 @@ lark-cli vc +detail --meeting-ids <meeting.id>
 - `+meeting-leave` 优先使用 `+meeting-join --as bot` 返回的 `meeting.id`，但不是每次 join 后都必须调用 leave。
 - `meeting_id` 如果来自 `+meeting-list-active`，必须来自应用身份，并确认应用机器人就在该会议中。不要用 9 位会议号。
 
-## 参考
-
-- [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-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-shared](../../lark-shared/SKILL.md) — 认证和全局参数
+## 相关场景
+- [应用机器人参会与会中互动](../scenes/live-meeting-attend.md)

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

@@ -0,0 +1,31 @@
+
+# vc +detail
+
+通过会议 ID 获取会议详情，包括基本信息、关联的纪要 ID（`note_id`）和妙记 Token（`minute_token`）。只读，支持 `--as user` / `--as bot`。
+
+## 命令
+
+```bash
+# 单个 / 批量（逗号分隔，最多 50 个）
+lark-cli vc +detail --meeting-ids <meeting_id1>,<meeting_id2>
+
+# 应用身份（只能查应用有权限的会议）
+lark-cli vc +detail --meeting-ids <meeting_id1>,<meeting_id2> --as bot
+```
+
+## 输出字段
+
+| 字段 | 说明 |
+|------|------|
+| `meeting_id` | 会议 ID |
+| `meeting_no` | 会议 9 位号码 |
+| `topic` | 会议主题 |
+| `start_time` | 开始时间 |
+| `end_time` | 结束时间 |
+| `note_id` | 关联的纪要 ID。 |
+| `minute_token` | 关联的妙记 Token。 |
+
+跨产物选择和后续命令链由 [`query-meeting-and-artifacts`](../scenes/query-meeting-and-artifacts.md) 统一编排。`note_id` / `minute_token` 由本命令取得后，后续 `note +detail`、`minutes +detail` 和 Doc 读取命令必须显式沿用同一个 `--as`。
+
+## 相关场景
+- [查询会议及其产物](../scenes/query-meeting-and-artifacts.md)

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

@@ -56,31 +56,7 @@ lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token
 - 应用身份路径：应用机器人必须在会中或参会过；不要拿任意 `meeting_id` 直接查。
 - 不要在拿到 `meeting_id` 后随意切换身份。身份不一致时，常见结果是空列表、`no permission` 或 `bot is not in meeting`。
 
-### 3. 读取事件前必须先拿到可见的 meeting_id
-
-最稳妥的调用顺序通常是：
-
-```bash
-# 方式 1：先入会，直接记录返回的 meeting.id
-lark-cli vc +meeting-join --as bot --meeting-number 123456789
-
-# 再查询事件
-lark-cli vc +meeting-events --as bot --meeting-id <id>
-```
-
-如果应用机器人已经在会中，也可以先通过 active meeting 找会：
-
-```bash
-lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
-lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
-```
-
-如果要查询当前登录用户所在会议：
-
-```bash
-lark-cli vc +meeting-list-active --as user --format json
-lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pretty
-```
+### 3. 应用身份的可见性窗口
 
 若应用机器人已离会、未入会、或会议已经无法再判断身份，后端通常会报：
 - `bot is not in meeting, no permission`
@@ -110,11 +86,13 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pret
 
 ### 5. 输出格式差异
 
-- `--format json`：结构化契约，顶层包含 `meeting`、`identity`、`events`、`has_more`、`page_token`。`identity` 表示当前读取身份；事件 actor 统一含 `participant_type`、`role`、`label`；每条事件保留 `payload` 便于追溯细节。
 - `--format pretty`：默认推荐格式，输出当前身份和逐条时间线，适合快速理解“发生了什么”。
+- `--format json`：结构化契约，顶层包含 `meeting`、`identity`、`events`、`has_more`、`page_token`。`identity` 表示当前读取身份；事件 actor 统一含 `participant_type`、`role`、`label`；每条事件保留 `payload` 便于追溯细节。
 - `--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 +109,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 +236,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 +251,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
 
@@ -223,74 +300,16 @@ lark-cli vc +meeting-events \
 | `start` / `end` | 用户给出的时间范围；如未给出则默认取全量可见事件 |
 | `page-token` | 上一页或上一次查询结果中保存的 `page_token`；建议持久化保存，便于下次继续拉取新增事件 |
 
-## Agent 组合场景
-
-### 场景 1：入会后读取会中发生了什么
-
-```bash
-# 第 1 步：加入会议，记录返回的 meeting.id
-JOIN=$(lark-cli vc +meeting-join --as bot --meeting-number 123456789 --format json)
-MID=$(echo "$JOIN" | jq -r '.data.meeting.id')
-
-# 第 2 步：用 meeting.id 读取当前可见事件
-lark-cli vc +meeting-events --as bot --meeting-id "$MID" --page-all --format pretty
-```
-
-### 场景 1b：应用机器人已在会中，先发现 meeting_id 再读事件
-
-```bash
-lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
-lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
-```
-
-### 场景 1c：当前登录用户正在会中，先发现 meeting_id 再读事件
-
-```bash
-lark-cli vc +meeting-list-active --as user --format json
-lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pretty
-```
-
-### 场景 2：过滤某段时间内的事件
-
-```bash
-lark-cli vc +meeting-events \
-  --as <same_identity> \
-  --meeting-id <id> \
-  --start 2026-04-17T15:00:00+08:00 \
-  --end 2026-04-17T16:00:00+08:00 \
-  --page-all \
-  --format pretty
-```
-
-### 场景 3：基于上一次的 `page_token` 继续查新增事件
-
-```bash
-# 上一次查询结束后，保留最后返回的 page_token
-# 这次直接从该游标继续拉新增事件
-lark-cli vc +meeting-events \
-  --as <same_identity> \
-  --meeting-id <id> \
-  --page-token <last_page_token> \
-  --page-all \
-  --format pretty
-```
-
-适用规则：
-
-- 当用户说“继续看新事件”“看上次之后新增了什么”时，优先使用上一次保存的 `page_token`。
-- 如果这次返回里仍有 `has_more=true`、pretty 里出现 `more available`，或又返回了新的 `page_token`，说明新增事件还没拉完，应继续分页，而不是把当前页误当成完整增量结果。
-- 只有在用户明确要求“从头回放全部事件”时，才忽略已有 `page_token`，重新从第一页开始。
-
 ## 常见错误与排查
 
 | 错误现象 | 根本原因 | 解决方案 |
 |---------|---------|---------|
 | `--meeting-id is required` | 未传入 `--meeting-id` | 传入长数字 `meeting.id` |
-| `10005 bot is not in meeting` | 使用应用身份读取，但应用机器人从未真实入会该会议；或会议已结束但应用机器人从未在会中出现过 | 如果 `meeting_id` 来自用户身份发现，改回 `--as user`；如果确实要应用身份读取，先让应用机器人入会或确认它曾参会后再用 `--as bot`。**如果只是想看参会人快照，改用 `lark-cli vc meeting get --params '{"meeting_id":"<meeting.id>"}' --with-participants`** |
+| `10005 bot is not in meeting` | 使用应用身份读取，但应用机器人从未真实入会该会议；或会议已结束但应用机器人从未在会中出现过 | 如果 `meeting_id` 来自用户身份发现，改回 `--as user`；如果确实要应用身份读取，先让应用机器人入会或确认它曾参会后再用 `--as bot`。**如果只是想看参会人快照，改用 `lark-cli vc meeting get --params '{"meeting_id":"<meeting.id>","with_participants":true}'`** |
 | 用户身份无权限 / 不可见 | 当前用户不是该会议的可见参与者，或 `meeting_id` 不是从用户身份路径获得 | 不要反复执行 `auth login`。先确认 `meeting_id` 是否来自 `+meeting-list-active --as user`；如果用户明确要切到应用身份，再通过 `+meeting-list-active --as bot --user-id <user_open_id>` 获取应用身份可读的 `meeting_id`，或在用户明确同意后让应用机器人入会，再用 `+meeting-events --as bot` 读取 |
 | `20001 meeting_status_MEETING_END` | 会议已结束且已超出后端允许的 5 分钟宽限窗口 | 本接口不再适合继续拉取事件。先用 `lark-cli vc +detail --meeting-ids <meeting.id>` 获取会议产物信息，再根据 `note_display_type` / `note_id` / `minute_token` 和用户意图选择纪要正文、逐字稿或妙记；参会人请用 `lark-cli vc meeting get --params '{"meeting_id":"<meeting.id>"}' --with-participants` |
 | `20002 meeting not exist` | `meeting_id` 错误，或会议实例当前已不可获取（常见于把 9 位会议号当 meeting_id 传） | 确认传入的是长数字 `meeting_id`，不是 9 位会议号 |
-| 应用身份权限不足 | 应用权限、租户安装、权限可访问的数据范围或 VC Agent privilege 未配置完整 | 不要执行 `auth login`。请应用开发者开通 `vc:meeting.bot.join:write`；再检查应用发布/安装和权限可访问的数据范围，均正确仍失败时再排查内测灰度权限 |
+| 应用身份权限不足 | 应用权限、租户安装或权限可访问的数据范围未配置完整 | 不要执行 `auth login`。请应用开发者开通 `vc:meeting.bot.join:write`；再检查应用发布/安装和权限可访问的数据范围；配置正确仍失败时，保留错误码和 `log_id`，按服务端权限异常排查 |
 | `HTTP 404` / `HTTP 500` | 服务端当前无法找到或处理该会议实例 | 换一个正在进行且 bot 可见的 meeting_id，或排查后端问题 |
 
 ## 提示
@@ -298,18 +317,10 @@ lark-cli vc +meeting-events \
 - 这是**会中事件流**查询，不适合拿来搜历史会议记录；搜历史会议请用 `+search`。
 - 如果会议已经结束，不要卡在 `+meeting-events`：  
   - 先用 `lark-cli vc +detail --meeting-ids <meeting.id>` 获取会议产物信息。
-  - 再根据 `note_display_type`、`note_id`、`minute_token` 和用户意图，按 `lark-vc` 的产物决策读取纪要正文、逐字稿或妙记。
+  - 再根据 `note_display_type`、`note_id`、`minute_token` 和用户意图，按 `lark-meeting` 的产物决策读取纪要正文、逐字稿或妙记。
 - 事件列表是否完整，取决于应用机器人何时入会、何时离会，以及后端当前可见的会中事件范围。对于已结束会议，通常只在**结束后 5 分钟内**、且应用机器人**曾经在会中**时还能继续拉到事件。
 - 查询"谁参加过某会议"请用 `vc meeting get --params '{"meeting_id":"<id>","with_participants":true}'`——这是参会人**快照** API，不依赖 bot 是否参会，对已结束会议也可查；**不要** 用 `+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-shared](../../lark-shared/SKILL.md) — 认证和全局参数
+## 相关场景
+- [会中事件与会中互动](../scenes/live-meeting-interact.md)
+- [应用机器人参会与会中互动](../scenes/live-meeting-attend.md)

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

@@ -33,22 +33,6 @@ lark-cli vc +meeting-list-active --as bot --user-id ou_xxx --format json
 
 应用身份返回空，不代表目标用户不在任何会议中，只能说明没有找到“目标用户在会中且应用机器人也在会中”的当前会。
 
-常见流程：
-
-```bash
-# 方式 1：先让应用机器人入会，直接从 join 响应拿 meeting.id
-lark-cli vc +meeting-join --as bot --meeting-number 123456789 --format json
-lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
-
-# 方式 2：应用机器人已经在会中时，用应用身份发现 meeting_id
-lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
-lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
-
-# 方式 3：查询当前登录用户所在会议发生了什么
-lark-cli vc +meeting-list-active --as user --format json
-lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pretty
-```
-
 ## 多会议选择
 
 - 如果返回多个会议，不要自动挑第一个。
@@ -59,14 +43,6 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pret
 
 用户提供 9 位会议号但没有明确要求应用机器人入会时，把会议号当作 active meeting 的筛选条件，而不是写操作指令。
 
-```bash
-# 用户问“我当前这个会讲了什么”
-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
-```
-
 匹配规则：
 
 - 在返回会议中匹配 `meeting_no == <9位会议号>`。
@@ -83,9 +59,8 @@ lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
 | 用户身份无权限 / 不可见 | 当前登录用户没有可见的进行中会议，或当前身份无法读取该会议 | 不要反复执行 `auth login`。确认用户是否在会中、是否切错 profile；用户明确要查询应用机器人可见的会议时，再拿目标用户 open_id 执行 `+meeting-list-active --as bot --user-id <user_open_id>` |
 | 应用身份返回空列表 | 没有满足“目标用户在会中且应用机器人也在会中”的当前会 | 先让应用机器人入会，或确认 `user_id` 和会议状态 |
 | `--user-id` 格式错误 | 传入了 internal user_id 或其他非 `ou_...` 值 | 改传目标用户 open_id |
-| 应用身份权限不足 | 应用权限、租户安装、权限可访问的数据范围或 VC Agent privilege 未配置完整 | 不要执行 `auth login`。请应用开发者开通 `vc:meeting.bot.join:write`；再检查应用发布/安装和权限可访问的数据范围，均正确仍失败时再排查内测灰度权限 |
-
-## 参考
+| 应用身份权限不足 | 应用权限、租户安装或权限可访问的数据范围未配置完整 | 不要执行 `auth login`。请应用开发者开通 `vc:meeting.bot.join:write`；再检查应用发布/安装和权限可访问的数据范围；配置正确仍失败时，保留错误码和 `log_id`，按服务端权限异常排查 |
 
-- [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` 读取会中事件
+## 相关场景
+- [会中事件与会中互动](../scenes/live-meeting-interact.md)
+- [应用机器人参会与会中互动](../scenes/live-meeting-attend.md)

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

@@ -127,8 +127,6 @@ VC_CanNotSee, VC_NoSound, VC_LooksGood, VC_SoundsClear
 
 应用身份权限错误时，不要引导用户反复 `auth login`。按主 skill 的“应用身份权限配置检查”处理。
 
-## 相关
-
-- [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) — 应用机器人入会
+## 相关场景
+- [会中事件与会中互动](../scenes/live-meeting-interact.md)
+- [应用机器人参会与会中互动](../scenes/live-meeting-attend.md)

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

@@ -40,9 +40,9 @@ 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`。用户身份只能查自己有权限的录制；应用身份只能查应用有权限的录制。拿到 `minute_token` 后，传给 `minutes minutes get`、`minutes +detail` 或 `minutes +download` 时必须显式沿用同一个 `--as`。
 
 ### 3. 批量上限
 
@@ -72,62 +72,6 @@ lark-cli vc +recording --meeting-ids 69xxxxxxxxxxxxx28 --dry-run
 | `meeting_id` | 使用 `lark-cli vc +search` 搜索历史会议，取结果中的 `id` 字段 |
 | `calendar_event_id` | 使用 `lark-cli calendar +agenda` 查看日程，取结果中的 `event_id` 字段 |
 
-## Agent 组合场景
-
-### 场景 1：知道 meeting_id，想下载录制
-
-```bash
-# 第 1 步：通过 meeting_id 查询录制，拿到 minute_token
-lark-cli vc +recording --meeting-ids xxx
-
-# 第 2 步：使用上一步返回的 minute_token 下载妙记文件
-lark-cli minutes +download --minute-tokens <minute_token>
-```
-
-### 场景 2：知道 meeting_id，想查询妙记基础信息
-
-```bash
-# 第 1 步：通过 meeting_id 查询录制，拿到 minute_token
-lark-cli vc +recording --meeting-ids xxx
-
-# 第 2 步：使用上一步返回的 minute_token 查询妙记基础信息
-lark-cli minutes minutes get --params '{"minute_token":"<minute_token>"}'
-```
-
-### 场景 3：知道 meeting_id，想获取完整纪要（含 AI 产物）
-
-```bash
-# 第 1 步：通过 meeting_id 查询录制，拿到 minute_token
-lark-cli vc +recording --meeting-ids xxx
-
-# 第 2 步：使用上一步返回的 minute_token 获取完整纪要
-# ⚠️ 必须显式指定要获取的产物 flag（--summary, --keyword, --todo, --chapter, --transcript）
-lark-cli minutes +detail --minute-tokens <minute_token> --summary --todo --chapter --transcript
-```
-
-### 场景 4：先搜索会议，再获取录制并下载
-
-```bash
-# 第 1 步：搜索历史会议，拿到 meeting_ids
-lark-cli vc +search --query "周会" --start 2026-03-10
-
-# 第 2 步：使用上一步返回的 meeting_ids 查询录制，拿到 minute_tokens
-lark-cli vc +recording --meeting-ids <ids>
-
-# 第 3 步：使用其中一个 minute_token 下载妙记文件
-lark-cli minutes +download --minute-tokens <token>
-```
-
-### 场景 5：从日历事件获取录制
-
-```bash
-# 第 1 步：通过日历 event_id 查询录制，拿到 minute_token
-lark-cli vc +recording --calendar-event-ids <event_id>
-
-# 第 2 步：使用上一步返回的 minute_token 下载妙记文件
-lark-cli minutes +download --minute-tokens <minute_token>
-```
-
 ## 常见错误与排查
 
 | 错误现象 | 根本原因 | 解决方案 |
@@ -136,7 +80,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) 的权限管理） |
 
 ## 提示
 
@@ -145,8 +89,5 @@ lark-cli minutes +download --minute-tokens <minute_token>
 - `minute_token` 从录制 URL 尾段解析（`https://meetings.feishu.cn/minutes/{minute_token}`）。
 - 拿到 `minute_token` 后，如果要妙记基础信息，优先传给 `minutes minutes get`；如果要下载媒体文件，传给 `minutes +download`；如果要逐字稿、总结、待办、章节，再传给 `minutes +detail --minute-tokens`。
 
-## 参考
-
-- [lark-vc](../SKILL.md) — 视频会议全部命令
-- [lark-vc-search](lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
-- [lark-minutes-detail](../../lark-minutes/references/lark-minutes-detail.md) — 获取会议纪要
+## 相关场景
+- [查询会议及其产物](../scenes/query-meeting-and-artifacts.md)