docs(skill): refine vc agent meeting guidance

2026-07-07 09:11:44 +08:00 · 2026-04-18 17:44:34 +08:00
parent 6e9dc16c95
commit 7d5e0977ac
3 changed files with 30 additions and 22 deletions
--- a/skills/lark-vc-agent/SKILL.md
+++ b/skills/lark-vc-agent/SKILL.md
@@ -34,23 +34,22 @@ metadata:

 ### 1. 加入正在进行的会议（写操作）

-1. 只有当用户明确要求"让机器人真实入会"（参会机器人、会中助手、代为旁听、代为参会）时才调用 `+meeting-join`。**用户只是想查会议数据时不要入会**。
-2. `--meeting-number` 只接受 **9 位纯数字**会议号，不接受会议链接整串，也不接受 `meeting_id`。
-3. 返回体中的 `meeting.id` **必须立刻记录**——后续 `+meeting-events` / `+meeting-leave` 都靠它，不能用 9 位会议号替代。
-4. 入会会让机器人**立即出现在会议的参会人列表中**，对所有参会人可见。误入错会的社交成本高于技术成本——执行前确认 9 位会议号的来源（用户输入或会议链接末尾），不要凭空编造。参数格式有疑问时可用 `--dry-run` 预览请求体。
-5. 仅支持 `user` 身份。需提前 `lark-cli auth login` 并拥有 `vc:meeting.bot.join:write` scope。
+1. 只有用户明确表达"让 Agent **真实入会**"（参会机器人、会中助手、代为旁听、代参会）时才用 `+meeting-join`。只是查数据不要入会。
+2. `+meeting-join --meeting-number` 只接受 **9 位纯数字**会议号，不是会议链接整串、也不是 `meeting_id`。
+3. 返回体中的 `meeting.id` **必须立刻记录**——后续 `+meeting-events` / `+meeting-leave` 都靠它，**不能用 9 位会议号替代**。
+4. 写操作**不支持回放**，执行前优先 `--dry-run` 核对请求体。
+5. 仅支持 `user` 身份，需提前 `lark-cli auth login` 并拥有 `vc:meeting.bot.join:write` scope。
+6. 若入会失败，优先查看 `+meeting-join` reference 的错误排查段落，重点确认会议号、密码、会议状态、等候室 / 审批以及会议是否禁止当前身份加入。

 ### 2. 感知会中事件（读操作）

 1. 用户要看"会议里正在发生什么"（参会人加入/离开、聊天、转写、屏幕共享）时，用 `+meeting-events`。
 2. 输入是 **`meeting_id`**（长数字 ID），不是 9 位会议号。
-3. **硬约束**——调用前必读：
-   - 机器人必须**已通过 `+meeting-join` 真实入会**，否则返回 `10005 bot is not in meeting`。
-   - 会议必须**仍在进行中**，已结束会议返回 `20001 meeting_status_MEETING_END`。
-   - 已结束会议的发言请用 `vc +notes` 取 `verbatim_doc_token`；参会人快照请用 `vc meeting get --with-participants`（均见 [`lark-vc`](../lark-vc/SKILL.md)）。
-4. 默认单页返回；要拿完整事件流用 `--page-all` 或 `--page-limit`。
-5. 输出格式按处理深度选：`--format pretty` 把每条事件压成一行 summary（如 `participant X (name) joined`），适合**汇总时间线、快速向用户汇报**；`--format json` 保留完整 payload（open_id、聊天原文、share_doc 等），适合**提取字段做进一步处理**（过滤某类事件、联动其他命令）。
-6. 响应里的 `page_token` 要保留——下次增量拉取直接续，不要从头再拉。
+3. Bot 必须**真实参会过**（先 `+meeting-join`），否则事件流通常不可见。具体的状态边界、结束后宽限窗口与错误码（如 `10005 / 20001 / 20002`）请查看 `+meeting-events` reference。
+4. **不能做会后复盘**，**不能替代参会人快照查询**。已结束会议的发言请用 `vc +notes` 取 `verbatim_doc_token`；参会人快照请用 `vc meeting get --with-participants`（见 [`lark-vc`](../lark-vc/SKILL.md)）。
+5. 默认单页；需要完整事件流用 `--page-all` 或 `--page-limit`。
+6. 输出格式优先 `--format pretty`（时间线更易读）；需要保证完整消息流才用 `--format json`。
+7. 保留响应里的 `page_token`，下次增量拉取直接续，不要从头再拉。

 ### 3. 离开会议（写操作）

--- a/skills/lark-vc-agent/references/lark-vc-agent-meeting-events.md
+++ b/skills/lark-vc-agent/references/lark-vc-agent-meeting-events.md
@@ -3,7 +3,7 @@

 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。

-查询当前 bot 在一场正在进行的视频会议中收到的会中事件列表。该命令是**读操作**，但只有当 bot 仍在会中时才能成功返回事件。
+查询当前 bot 在一场正在进行的视频会议中收到的会中事件列表。该命令是**读操作**。对进行中会议，要求 bot 当前仍在会中；对已结束会议，存在一个**结束后 5 分钟内的宽限窗口**，只要 bot 曾经在这场会里出现过，仍可继续拉取事件。

 本 skill 对应 shortcut：`lark-cli vc +meeting-events`（调用 `GET /open-apis/vc/v1/bots/events`）。

@@ -11,19 +11,19 @@

 ```bash
 # 查询当前会议的首批事件
-lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --format pretty

 # 指定时间范围
-lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --start 2026-04-17T15:00:00+08:00 --end 2026-04-17T16:00:00+08:00
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --start 2026-04-17T15:00:00+08:00 --end 2026-04-17T16:00:00+08:00 --format pretty

 # pretty 时间线输出
 lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --format pretty

 # 自动翻页（最多 10 页）
-lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-limit 10
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-limit 10 --format pretty

 # 自动翻到上限
-lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-all
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-all --format pretty

 # 预览 API 调用（不实际请求）
 lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --dry-run
@@ -57,7 +57,7 @@ lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --dry-run

 该命令仅支持 `user` 身份，使用前需完成 `lark-cli auth login`。

-### 3. bot 必须仍在会中
+### 3. bot 必须在会中，或在会议结束后的 5 分钟宽限窗口内曾经在会中

 这是查询“bot 在会中观察到的事件”的接口。若 bot 已离会、未入会、或会议已经无法再判断 bot 身份，后端通常会报：
 - `bot is not in meeting, no permission`
@@ -74,6 +74,13 @@ lark-cli vc +meeting-join --meeting-number 123456789
 lark-cli vc +meeting-events --meeting-id <meeting.id>
 ```

+更精确地说，后端当前的判断规则是：
+
+- **会议进行中**：要求 bot **当前仍在会中**
+- **会议已结束后的 5 分钟内**：只要 bot **曾经在这场会中出现过**，仍可拉取事件
+- **会议结束超过 5 分钟**：按会议结束处理，通常不再返回事件流
+- **bot 从未真实入会过**：即使会议仍在进行或刚结束，也会返回 `10005 bot is not in meeting`
+
 ### 4. 自动分页规则

 - 不传 `--page-all` 也不传 `--page-limit`：只查 1 页
@@ -176,9 +183,9 @@ lark-cli vc +meeting-events \
 |---------|---------|---------|
 | `--meeting-id is required` | 未传入 `--meeting-id` | 传入长数字 `meeting.id` |
 | `invalid --page-limit` | `page-limit` 小于 1 或超过上限 | 调整到允许范围内 |
-| `10005 bot is not in meeting` | bot 从未真实入会该会议；或会中已离会 | 先 `+meeting-join --meeting-number <9位号>` 真实入会再查；**如果只是想看参会人快照，改用 `vc meeting get --with-participants`**（不依赖 bot 身份参会） |
-| `20001 meeting_status_MEETING_END` | 会议已结束，本接口不返回已结束会议的事件 | 本接口不支持会后复盘。已结束会议的发言请用 `vc +notes` 取 `verbatim_doc_token`；参会人请用 `vc meeting get --with-participants` |
-| `20002 meeting not exist` | `meeting_id` 错误（常见于把 9 位会议号当 meeting_id 传） | 确认传入的是长数字 `meeting_id`，不是 9 位会议号 |
+| `10005 bot is not in meeting` | bot 从未真实入会该会议；或会议已结束但 bot 从未在会中出现过 | 先 `+meeting-join --meeting-number <9位号>` 真实入会再查；如果会议已经结束且当时 bot 没进过会，本接口也拉不到数据。**如果只是想看参会人快照，改用 `vc meeting get --with-participants`**（不依赖 bot 身份参会） |
+| `20001 meeting_status_MEETING_END` | 会议已结束且已超出后端允许的 5 分钟宽限窗口 | 本接口不再适合继续拉取事件。已结束会议的发言请用 `vc +notes` 取 `verbatim_doc_token`；参会人请用 `vc meeting get --with-participants` |
+| `20002 meeting not exist` | `meeting_id` 错误，或会议实例当前已不可获取（常见于把 9 位会议号当 meeting_id 传） | 确认传入的是长数字 `meeting_id`，不是 9 位会议号 |
 | `HTTP 404` / `HTTP 500` | 服务端当前无法找到或处理该会议实例 | 换一个正在进行且 bot 可见的 meeting_id，或排查后端问题 |
 | `missing required scope(s)` | 未授权 `vc:meeting.meetingevent:read` | 按提示重新 `auth login` 补 scope |

@@ -186,7 +193,7 @@ lark-cli vc +meeting-events \

 - 这是**会中事件流**查询，不适合拿来搜历史会议记录；搜历史会议请用 `+search`。
 - 如果你只需要最终纪要、录制、逐字稿，不必查事件列表，直接用 `+notes` / `+recording`。
- 事件列表是否完整，取决于 bot 何时入会、何时离会，以及后端当前可见的会中事件范围。
+- 事件列表是否完整，取决于 bot 何时入会、何时离会，以及后端当前可见的会中事件范围。对于已结束会议，通常只在**结束后 5 分钟内**、且 bot **曾经在会中**时还能继续拉到事件。
 - 查询"谁参加过某会议"请用 `vc meeting get --params '{"meeting_id":"<id>","with_participants":true}'`——这是参会人**快照** API，不依赖 bot 是否参会，对已结束会议也可查；**不要** 用 `+meeting-events` 做参会人查询。

 ## 参考
--- a/skills/lark-vc-agent/references/lark-vc-agent-meeting-join.md
+++ b/skills/lark-vc-agent/references/lark-vc-agent-meeting-join.md
@@ -51,6 +51,7 @@ lark-cli vc +meeting-join --meeting-number 123456789 --dry-run

 - 会议必须处于**进行中**状态，bot 无法加入尚未开始或已结束的会议。
 - 若会议设置了**等候室 / 入会审批**，bot 可能需要主持人放行后才真正入会。
+- 若返回 `HTTP 403: no permission`（错误码 `121003`），不要只理解成“账号没权限”。这类报错更常见的原因是：会议参数或会控配置当前不满足入会条件，例如会议号填错、密码未传或错误、会议尚未开始、等候室 / 入会审批未放行、会议禁止外部/特定身份加入等。应先确认这些配置项，再重试。

 ### 4. 机器人入会后对其他参会人可见

@@ -112,6 +113,7 @@ lark-cli vc +notes --meeting-ids <meeting.id>
 | `missing required scope(s)` | 未授权 `vc:meeting.bot.join:write` | 按提示运行 `auth login --scope vc:meeting.bot.join:write` |
 | 会议密码错误 | `--password` 错误或未提供 | 向主持人确认会议密码 |
 | 会议不存在 / 已结束 | 会议号错误或会议未进行中 | 确认会议正在进行中 |
+| `HTTP 403: no permission` / `121003` | 入会前置条件不满足，通常不是单纯 scope 问题 | 依次确认：1）会议号正确；2）如有密码已正确传 `--password`；3）会议已开始；4）等候室 / 入会审批已放行；5）会议未禁止当前身份加入（如限制外部、限制 bot、仅特定成员可入会）；确认后重试 |
 | 入会被拒绝 | 等候室 / 入会审批 / 限制外部入会 | 联系主持人放行或调整会议设置 |

 ## 提示