github/larksuite-cli
1
0
Fork 0
mirror of https://github.com/larksuite/cli.git synced 2026-07-08 02:00:19 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(vc): prefer json for meeting events agents

Browse Source
This commit is contained in:
renaocheng
2026-07-06 14:45:01 +08:00
parent a5259e2743
commit cd2d1b87d5
4 changed files with 28 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
skills/lark-vc-agent/SKILL.md
View File

@@ -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 <user_open_id> --format json
lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
lark-cli vc +meeting-events --as bot --meeting-id <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 <meeting_id> --page-all --format pretty
lark-cli vc +meeting-events --as user --meeting-id <meeting_id> --page-all --format json
```
## Shortcuts

38
skills/lark-vc-agent/references/lark-vc-agent-meeting-events.md
View File

@@ -14,14 +14,14 @@
## 命令
```bash
# 默认用法：全量拉取当前身份可见事件；输出结构化事件契约
lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-all --format pretty
# 默认用法：全量拉取当前身份可见事件；Agent 优先使用结构化 JSON
lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-all --format json
# 指定时间范围，并拉全该时间窗内当前可见事件
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
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 json
# 基于上一次保存的 page_token 继续查新增事件
lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token <last_page_token> --page-all --format pretty
lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token <last_page_token> --page-all --format json
```
## 参数
@@ -72,14 +72,14 @@ lark-cli vc +meeting-events --as bot --meeting-id <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
lark-cli vc +meeting-events --as bot --meeting-id <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 <id> --page-all --format pretty
lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format json
```
若应用机器人已离会、未入会、或会议已经无法再判断身份，后端通常会报：
@@ -102,19 +102,19 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pret
执行准则：
- **默认命令模板**：`lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-all --format pretty`
- **默认命令模板**：`lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-all --format json`
- 如果你发现自己执行成了不带 `--page-all` 的单页查询，而响应里又出现 `has_more=true` / `more available` / 非空 `page_token`，应立刻意识到这只是部分结果。
- 遇到上述情况，默认补救方式是继续使用返回的 `page_token` 续拉，例如：`lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token <returned_page_token> --page-all --format pretty`
- 遇到上述情况，默认补救方式是继续使用返回的 `page_token` 续拉，例如：`lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token <returned_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 <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 <user_open_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 <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` 拉取最新事件流。
- 如果事件中出现共享文档线索，例如：
@@ -160,8 +160,8 @@ 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/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 <user_open_id> --format json
lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
lark-cli vc +meeting-events --as bot --meeting-id <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 <id> --page-all --format pretty
lark-cli vc +meeting-events --as user --meeting-id <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 <id> \
--page-token <last_page_token> \
--page-all \
--format pretty
--format json
```
适用规则：

2
skills/lark-vc-agent/references/lark-vc-agent-meeting-join.md
View File

@@ -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 <meeting.id> --page-all --format pretty
lark-cli vc +meeting-events --as bot --meeting-id <meeting.id> --page-all --format json
```
如果 bot 已经在会中，也可以通过 active meeting 找回 `meeting_id`：

6
skills/lark-vc-agent/references/lark-vc-agent-meeting-list-active.md
View File

@@ -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 <id> --page-all --format pretty
lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format json
# 方式 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
lark-cli vc +meeting-events --as bot --meeting-id <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 <id> --page-all --format pretty
lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format json
```
## 多会议选择