docs(skill): tighten vc agent meeting events workflow

skills/lark-vc-agent/SKILL.md

@@ -47,9 +47,10 @@ metadata:
 2. 输入是 **`meeting_id`**（长数字 ID），不是 9 位会议号。
 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`，下次增量拉取直接续，不要从头再拉。
+5. **默认必须使用 `--page-all`**，除非用户明确要求“只查一页”、明确限制页数，或确实需要控制返回体大小。
+6. 输出格式默认优先 `--format pretty`（时间线更易读）；只有在需要完整保留原始消息流与结构化字段时，才使用 `--format json`。
+7. **必须识别分页信号**：只要响应里出现 `has_more=true`、pretty 里的 `more available`，或返回了非空 `page_token`，就不能把当前结果当作完整事件流；默认应继续分页，或明确告诉用户当前只是部分结果。
+8. 保留响应里的 `page_token`，下次增量拉取直接续，不要从头再拉。
 
 ### 3. 离开会议（写操作）
 
@@ -66,9 +67,9 @@ JOIN=$(lark-cli vc +meeting-join --meeting-number 123456789 --format json)
 MID=$(echo "$JOIN" | jq -r '.data.meeting.id')
 
 # 2. 会中轮询事件
-#    --start 每轮用上一次响应里最新事件的 event_time，避免拉重复事件
+#    默认用 --page-all 拉全当前可见事件；下次增量优先复用 page_token
 #    典型间隔 10-30 秒
-lark-cli vc +meeting-events --meeting-id "$MID" --format pretty
+lark-cli vc +meeting-events --meeting-id "$MID" --page-all --format pretty
 
 # 3. 任务完成或用户要求结束时离会
 lark-cli vc +meeting-leave --meeting-id "$MID"

skills/lark-vc-agent/references/lark-vc-agent-meeting-events.md

@@ -10,20 +10,17 @@
 ## 命令
 
 ```bash
-# 默认建议：全量拉取当前可见事件
+# 默认用法：全量拉取当前可见事件
 lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-all --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 --page-all --format pretty
 
-# pretty 时间线输出
-lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-all --format pretty
+# 基于上一次保存的 page_token 继续查新增事件
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-token <last_page_token> --page-all --format pretty
 
-# 自动翻页（最多 10 页）
-lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-limit 10 --format pretty
-
-# 自动翻到上限
-lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-all --format pretty
+# 调试或控制返回体大小时，显式限制最多翻 10 页
+lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-limit 10 --format json
 
 # 预览 API 调用（不实际请求）
 lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --dry-run
@@ -83,25 +80,34 @@ lark-cli vc +meeting-events --meeting-id <meeting.id>
 
 ### 4. 自动分页规则
 
-- **本 skill 的默认策略**：除非用户明确要求“只查一页”、明确限制页数，或出于调试 / 控制返回体大小的原因指定了别的方式，否则默认应主动带上 `--page-all`，把当前可见事件尽量一次拉全。
-- **Agent 必须学会识别分页状态**：看到响应中的 `has_more=true` 时，要明确知道后面还有页；如果当前任务目标是“拿全当前可见事件”，就应继续分页，而不是把这一页误当成完整结果。
+- **先分清两层默认值**：
+  - shortcut 本身：不传 `--page-all` / `--page-limit` 时，只查 1 页。
+  - 本 skill 的默认策略：除非用户明确要求只看一页、限制页数，或你确实需要控制返回体大小，否则默认**必须主动带 `--page-all`**，把当前可见事件尽量一次拉全。
 - 传 `--page-limit N`：开启自动分页，最多拉 `N` 页。
 - 传 `--page-all`：开启自动分页；若未显式传 `--page-limit`，使用最大页上限。
 - `--page-all` 时，CLI 固定使用最大 `page_size=100`。
 
+执行准则：
+
+- **默认命令模板**：`lark-cli vc +meeting-events --meeting-id <meeting.id> --page-all --format pretty`
+- 如果你发现自己执行成了不带 `--page-all` 的单页查询，而响应里又出现 `has_more=true` / `more available` / 非空 `page_token`，应立刻意识到这只是部分结果。
+- 遇到上述情况，默认补救方式是继续使用返回的 `page_token` 续拉，例如：`lark-cli vc +meeting-events --meeting-id <meeting.id> --page-token <returned_page_token> --page-all --format pretty`
+- 只有在用户明确要求“就看第一页”“先不要翻页”“最多看 N 页”时，才不要默认带 `--page-all`
+
 ### 5. pretty / json 输出差异
 
-- `--format pretty`：每条事件输出一行 `event_id / event_time / event_type / summary`；summary 由 shortcut 按 event_type 本地生成（如 `participant X (name) joined`、`speaker X: text`、`share N started: title`），**紧凑易读**，适合**汇总时间线、快速向用户汇报**
-- `--format json`：保留**完整原始 `events[]` 结构**——参会人 open_id、聊天原文、share_doc token 等都在 `events[].payload` 里，**适合提取字段做进一步处理**（过滤某类事件、联动其他命令）
+- `--format pretty`：输出会议主题、会议时间和逐条时间线，适合快速理解“发生了什么”，也是本 skill 的默认推荐格式。
+- `--format json`：保留完整原始 `events[]` 结构——参会人 open_id、聊天原文、share_doc、分页字段都在原始响应里，适合提取字段、联动其他命令或做进一步程序处理。
 
-**选型**按处理深度：只要告诉用户"发生了什么"→ `--page-all --format pretty` 通常就是默认首选；要拿具体字段→ json。
+**选型原则**：只要目标是告诉用户“发生了什么”，默认就用 `--page-all --format pretty`；只有在需要完整原始消息流和结构化字段时，才改用 `json`。
 
 > **注意**：pretty 输出中的正文文本会做单行转义，真实换行会显示为 `\n`，避免打乱时间线布局。
 
 ### 6. 关于 `page_token` 的返回与续拉
 
 - 不管这次是只查 1 页，还是通过 `--page-limit` / `--page-all` 已经把当前可见事件都拿完，都应把最后拿到的 `page_token` 一并保留下来并返回给用户。
-- 如果没有使用 `--page-all`，但响应里 `has_more=true`，说明这次只拿到了部分事件；此时要么继续用返回的 `page_token` 拉下一页，要么明确告诉用户当前结果并不完整。
+- 只要响应里出现 `has_more=true`、pretty 里出现 `more available`，或返回了非空 `page_token`，就必须先判断当前结果是否完整；默认情况下，这意味着你还需要继续分页。
+- 如果没有使用 `--page-all`，但出现了上述分页信号，默认应继续用返回的 `page_token` 拉下一页，而不是直接结束。只有在用户明确不要继续翻页时，才可以停止并明确说明当前结果不完整。
 - 下次继续“查新增事件”时，应优先复用上一次保存的 `page_token`，而不是从头全量再拉一次。
 - 只有在用户明确要求“从头回放全部事件”时，才忽略历史 `page_token`，重新从第一页开始。
 
@@ -185,7 +191,7 @@ lark-cli vc +meeting-events \
 适用规则：
 
 - 当用户说“继续看新事件”“看上次之后新增了什么”时，优先使用上一次保存的 `page_token`。
-- 如果这次返回里仍有 `has_more=true`，说明新增事件还没拉完，应继续分页，而不是把当前页误当成完整增量结果。
+- 如果这次返回里仍有 `has_more=true`、pretty 里出现 `more available`，或又返回了新的 `page_token`，说明新增事件还没拉完，应继续分页，而不是把当前页误当成完整增量结果。
 - 只有在用户明确要求“从头回放全部事件”时，才忽略已有 `page_token`，重新从第一页开始。
 
 ## 常见错误与排查
@@ -204,8 +210,6 @@ lark-cli vc +meeting-events \
 
 - 这是**会中事件流**查询，不适合拿来搜历史会议记录；搜历史会议请用 `+search`。
 - 如果你只需要最终纪要、录制、逐字稿，不必查事件列表，直接用 `+notes` / `+recording`。
-- 对 Agent 来说，默认应把 `+meeting-events` 当作“尽量拉全当前可见事件”的命令来用，也就是优先带 `--page-all`；只有用户明确要求单页、限页，或你确实需要控制返回体大小时，才改用单页或 `--page-limit`。
-- 如果没有显式使用 `--page-all`，也必须根据返回里的 `has_more` 判断当前结果是不是完整；`has_more=true` 时，不能把这一页直接当作“全部事件”来汇报。
 - 事件列表是否完整，取决于 bot 何时入会、何时离会，以及后端当前可见的会中事件范围。对于已结束会议，通常只在**结束后 5 分钟内**、且 bot **曾经在会中**时还能继续拉到事件。
 - 查询"谁参加过某会议"请用 `vc meeting get --params '{"meeting_id":"<id>","with_participants":true}'`——这是参会人**快照** API，不依赖 bot 是否参会，对已结束会议也可查；**不要** 用 `+meeting-events` 做参会人查询。