diff --git a/skills/lark-vc-agent/SKILL.md b/skills/lark-vc-agent/SKILL.md index 162e631b8..5f5596f82 100644 --- a/skills/lark-vc-agent/SKILL.md +++ b/skills/lark-vc-agent/SKILL.md @@ -72,8 +72,8 @@ metadata: - 再根据 `note_id`、`minute_token` 和用户意图，按 [`lark-vc`](../lark-vc/SKILL.md) 的产物决策读取正文、逐字稿或妙记。 - 想看参会人快照：用 `vc meeting get --with-participants`（见 [`lark-vc`](../lark-vc/SKILL.md)） 5. **默认必须使用** **`--page-all`**，除非用户明确要求“只查一页”，或确实需要控制返回体大小。 -6. 命令默认输出结构化事件契约：`meeting`、`identity`、`current_roster`、`events`、`warnings`、`has_more`、`page_token`，参会人含 `participant_type`、`role`、`is_self` 和可读 `label`；事件中的原始细节保留在 `payload/raw`。 -7. 输出格式默认优先 `--format pretty`（时间线更易读，并带当前身份与当前名单标签）；需要结构化处理时用 `--format json`；需要流式消费事件时用 `--format ndjson`。 +6. Agent 默认使用 `--format json`，输出结构化事件契约：`meeting`、`identity`、`current_roster`、`events`、`warnings`、`has_more`、`page_token`；参会人含 `participant_type`、`role`、`is_self` 和可读 `label`，事件细节保留在 `payload`。 +7. 只有直接给人阅读时间线时才用 `--format pretty`；需要流式消费事件时用 `--format ndjson`。 8. **必须识别分页信号**：只要响应里出现 `has_more=true`、pretty 里的 `more available`，或返回了非空 `page_token`，就不能把当前结果当作完整事件流；默认应继续分页，或明确告诉用户当前只是部分结果。 9. 保留响应里的 `page_token`，下次增量拉取直接续，不要从头再拉。 10. **只要你是基于** **`+meeting-events`** **来回答一场正在进行中的会议内容，就不能直接复用旧结果。** 无论用户是在问“现在/刚刚/最新”的状态，还是让你“总结一下这个会议讲什么”，都必须先重新拉一次当前事件流，确认拿到的是最新信息，再基于最新结果回答。只有在用户明确要求基于某次历史快照继续分析时，才可以复用旧结果。 @@ -108,7 +108,7 @@ MID=$(echo "$JOIN" | jq -r '.data.meeting.id') # 2. 会中轮询事件 # 沿用入会身份；默认用 --page-all 拉全当前可见事件；下次增量优先复用 page_token # 典型间隔 10-30 秒 -lark-cli vc +meeting-events --as "$AS" --meeting-id "$MID" --page-all --format pretty +lark-cli vc +meeting-events --as "$AS" --meeting-id "$MID" --page-all --format json # 3. 会后可选：进入 lark-vc 获取会议产物信息，再按 note_id / minute_token 决策读取 lark-cli vc +detail --meeting-ids "$MID" @@ -120,14 +120,14 @@ lark-cli vc +detail --meeting-ids "$MID" ```bash lark-cli vc +meeting-list-active --as bot --user-id --format json -lark-cli vc +meeting-events --as bot --meeting-id --page-all --format pretty +lark-cli vc +meeting-events --as bot --meeting-id --page-all --format json ``` 如果只是回答当前登录用户所在会议发生了什么，使用用户身份一路查： ```bash lark-cli vc +meeting-list-active --as user --format json -lark-cli vc +meeting-events --as user --meeting-id --page-all --format pretty +lark-cli vc +meeting-events --as user --meeting-id --page-all --format json ``` ## Shortcuts diff --git a/skills/lark-vc-agent/references/lark-vc-agent-meeting-events.md b/skills/lark-vc-agent/references/lark-vc-agent-meeting-events.md index 46832f0a9..73f2f7e00 100644 --- a/skills/lark-vc-agent/references/lark-vc-agent-meeting-events.md +++ b/skills/lark-vc-agent/references/lark-vc-agent-meeting-events.md @@ -14,14 +14,14 @@ ## 命令 ```bash -# 默认用法：全量拉取当前身份可见事件；输出结构化事件契约 -lark-cli vc +meeting-events --as --meeting-id --page-all --format pretty +# 默认用法：全量拉取当前身份可见事件；Agent 优先使用结构化 JSON +lark-cli vc +meeting-events --as --meeting-id --page-all --format json # 指定时间范围，并拉全该时间窗内当前可见事件 -lark-cli vc +meeting-events --as --meeting-id --start 2026-04-17T15:00:00+08:00 --end 2026-04-17T16:00:00+08:00 --page-all --format pretty +lark-cli vc +meeting-events --as --meeting-id --start 2026-04-17T15:00:00+08:00 --end 2026-04-17T16:00:00+08:00 --page-all --format json # 基于上一次保存的 page_token 继续查新增事件 -lark-cli vc +meeting-events --as --meeting-id --page-token --page-all --format pretty +lark-cli vc +meeting-events --as --meeting-id --page-token --page-all --format json ``` ## 参数 @@ -72,14 +72,14 @@ lark-cli vc +meeting-events --as bot --meeting-id ```bash lark-cli vc +meeting-list-active --as bot --user-id --format json -lark-cli vc +meeting-events --as bot --meeting-id --page-all --format pretty +lark-cli vc +meeting-events --as bot --meeting-id --page-all --format json ``` 如果要查询当前登录用户所在会议： ```bash lark-cli vc +meeting-list-active --as user --format json -lark-cli vc +meeting-events --as user --meeting-id --page-all --format pretty +lark-cli vc +meeting-events --as user --meeting-id --page-all --format json ``` 若应用机器人已离会、未入会、或会议已经无法再判断身份，后端通常会报： @@ -102,19 +102,19 @@ lark-cli vc +meeting-events --as user --meeting-id --page-all --format pret 执行准则： -- **默认命令模板**：`lark-cli vc +meeting-events --as --meeting-id --page-all --format pretty` +- **默认命令模板**：`lark-cli vc +meeting-events --as --meeting-id --page-all --format json` - 如果你发现自己执行成了不带 `--page-all` 的单页查询，而响应里又出现 `has_more=true` / `more available` / 非空 `page_token`，应立刻意识到这只是部分结果。 -- 遇到上述情况，默认补救方式是继续使用返回的 `page_token` 续拉，例如：`lark-cli vc +meeting-events --as --meeting-id --page-token --page-all --format pretty` +- 遇到上述情况，默认补救方式是继续使用返回的 `page_token` 续拉，例如：`lark-cli vc +meeting-events --as --meeting-id --page-token --page-all --format json` - 只有在用户明确要求“就看第一页”“先不要翻页”时，才不要默认带 `--page-all` - 只要你是基于 `+meeting-events` 来回答一场**正在进行中的会议内容**，就不能直接复用上一次查询结果。无论用户是在问“现在是谁在说话”“刚刚发生了什么”“最新事件有哪些”，还是让你“总结一下这个会议讲什么”，都必须先重新执行一次 `+meeting-events`，确认拿到的是最新事件流，再回答用户。只有在用户明确要求基于某次历史快照继续分析时，才可以复用旧结果。 ### 5. 输出格式差异 -- `--format json`：结构化契约，顶层包含 `meeting`、`identity`、`current_roster`、`events`、`has_more`、`page_token`。参会人身份统一含 `participant_type`、`role`、`is_self`、`label`；每条事件保留 `payload/raw` 便于追溯原始细节。 -- `--format pretty`：输出当前身份、当前名单和逐条时间线，适合快速理解“发生了什么”。 +- `--format json`：Agent 默认格式。结构化契约，顶层包含 `meeting`、`identity`、`current_roster`、`events`、`has_more`、`page_token`。参会人身份统一含 `participant_type`、`role`、`is_self`、`label`；每条事件保留 `payload` 便于追溯细节。 +- `--format pretty`：输出当前身份、当前名单和逐条时间线，只在直接给人阅读“发生了什么”时使用。 - `--format ndjson`：输出事件行，并带 metadata 行，适合流式消费。 -**选型原则**：只在 `pretty`、`json`、`ndjson` 之间选择。目标是告诉用户“发生了什么”时，用 `--page-all --format pretty`；需要稳定字段给 agent 消费时用 `--format json`；需要流式消费时用 `--format ndjson`。 +**选型原则**：只在 `json`、`pretty`、`ndjson` 之间选择。Agent 读取、总结、转发和二次处理时默认用 `--page-all --format json`；只有要把时间线直接展示给人看时才用 `--format pretty`；需要流式消费时用 `--format ndjson`。 > **注意**：pretty 输出中的正文文本会做单行转义，真实换行会显示为 `\n`，避免打乱时间线布局。 @@ -132,7 +132,7 @@ lark-cli vc +meeting-events --as user --meeting-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 pretty`；问“应用机器人可见的目标用户会议”用 `lark-cli vc +meeting-list-active --as bot --user-id --format pretty`。返回多个会议时先让用户选择。 +- 如果上下文没有明确 `meeting_id`，先按用户当前意图选择身份：问“我/当前用户所在会议”用 `lark-cli vc +meeting-list-active --as user --format json`；问“应用机器人可见的目标用户会议”用 `lark-cli vc +meeting-list-active --as bot --user-id --format json`。返回多个会议时先让用户选择。 - 如果上下文只有 9 位会议号，先按当前身份执行 `+meeting-list-active` 并按 `meeting_no` 匹配；匹配到唯一会议后再查事件。不要为了总结会议而自动调用 `+meeting-join`。 - 这类问题拿到 `meeting_id` 后，用同一身份执行 `lark-cli vc +meeting-events --as --meeting-id --page-all --format json` 拉取最新事件流。 - 如果事件中出现共享文档线索，例如： @@ -160,8 +160,8 @@ lark-cli vc +meeting-events --as user --meeting-id --page-all --format pret |------|------| | `meeting` | 会议身份与时间状态，包含 `id/topic/meeting_no/start_time/end_time/status` | | `identity` | 当前读取身份，包含 `id/name/participant_type/role/is_self/label` | -| `current_roster` | 服务端当前名单，不从历史事件 replay 推导 | -| `events` | 结构化事件列表；每条事件含 `actors` 和原始 `payload/raw` | +| `current_roster` | 服务端当前名单；当 roster 缺少姓名或类型为 `unknown` 时，CLI 会用同 ID 的事件 actor 信息补全，不做完整历史 replay | +| `events` | 结构化事件列表；每条事件含 `actors` 和事件细节 `payload` | | `warnings` | 非阻断告警列表，例如当前名单补充信息不可用；事件列表本身仍可使用 | | `has_more` | 是否还有下一页 | | `page_token` | 下一页游标 | @@ -231,21 +231,21 @@ JOIN=$(lark-cli vc +meeting-join --as bot --meeting-number 123456789 --format js 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 +lark-cli vc +meeting-events --as bot --meeting-id "$MID" --page-all --format json ``` ### 场景 1b：应用机器人已在会中，先发现 meeting_id 再读事件 ```bash lark-cli vc +meeting-list-active --as bot --user-id --format json -lark-cli vc +meeting-events --as bot --meeting-id --page-all --format pretty +lark-cli vc +meeting-events --as bot --meeting-id --page-all --format json ``` ### 场景 1c：当前登录用户正在会中，先发现 meeting_id 再读事件 ```bash lark-cli vc +meeting-list-active --as user --format json -lark-cli vc +meeting-events --as user --meeting-id --page-all --format pretty +lark-cli vc +meeting-events --as user --meeting-id --page-all --format json ``` ### 场景 2：过滤某段时间内的事件 @@ -257,7 +257,7 @@ lark-cli vc +meeting-events \ --start 2026-04-17T15:00:00+08:00 \ --end 2026-04-17T16:00:00+08:00 \ --page-all \ - --format pretty + --format json ``` ### 场景 3：基于上一次的 `page_token` 继续查新增事件 @@ -270,7 +270,7 @@ lark-cli vc +meeting-events \ --meeting-id \ --page-token \ --page-all \ - --format pretty + --format json ``` 适用规则： diff --git a/skills/lark-vc-agent/references/lark-vc-agent-meeting-join.md b/skills/lark-vc-agent/references/lark-vc-agent-meeting-join.md index 44b57ba25..6a016218b 100644 --- a/skills/lark-vc-agent/references/lark-vc-agent-meeting-join.md +++ b/skills/lark-vc-agent/references/lark-vc-agent-meeting-join.md @@ -90,7 +90,7 @@ lark-cli vc +meeting-join --as bot --meeting-number 123456789 --dry-run lark-cli vc +meeting-join --as bot --meeting-number 123456789 # 第 2 步：使用返回的 meeting.id 查询会中事件 -lark-cli vc +meeting-events --as bot --meeting-id --page-all --format pretty +lark-cli vc +meeting-events --as bot --meeting-id --page-all --format json ``` 如果 bot 已经在会中，也可以通过 active meeting 找回 `meeting_id`： diff --git a/skills/lark-vc-agent/references/lark-vc-agent-meeting-list-active.md b/skills/lark-vc-agent/references/lark-vc-agent-meeting-list-active.md index f0cd9be08..08f6b9417 100644 --- a/skills/lark-vc-agent/references/lark-vc-agent-meeting-list-active.md +++ b/skills/lark-vc-agent/references/lark-vc-agent-meeting-list-active.md @@ -38,15 +38,15 @@ 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 --page-all --format pretty +lark-cli vc +meeting-events --as bot --meeting-id --page-all --format json # 方式 2：应用机器人已经在会中时，用应用身份发现 meeting_id lark-cli vc +meeting-list-active --as bot --user-id --format json -lark-cli vc +meeting-events --as bot --meeting-id --page-all --format pretty +lark-cli vc +meeting-events --as bot --meeting-id --page-all --format json # 方式 3：查询当前登录用户所在会议发生了什么 lark-cli vc +meeting-list-active --as user --format json -lark-cli vc +meeting-events --as user --meeting-id --page-all --format pretty +lark-cli vc +meeting-events --as user --meeting-id --page-all --format json ``` ## 多会议选择