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

docs: systematic review of lark-vc-agent SKILL for clarity and precision

Browse Source
This commit is contained in:
renaocheng
2026-04-18 17:43:38 +08:00
committed by houzhicong
parent 39072db90c
commit 13841801f5
1 changed files with 45 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,7 +1,7 @@
---
name: lark-vc-agent
version: 1.0.0
description: "飞书视频会议：让机器人代当前用户加入/离开正在进行的会议，并读取会议期间的实时事件（参会人加入离开、发言、聊天、屏幕共享等）。1. 用户提供 9 位会议号、要求代为入会或离会时使用 +meeting-join / +meeting-leave——会真实产生入会/离会记录。2. 会议进行中用户想知道“谁加入了”、“谁离开了”、“谁在发言”、“有人共享屏幕吗”等会中动态时，机器人入会后用 +meeting-events 读取事件时间线。3. 典型场景：参会机器人、会中助手、代为旁听、代为参会。前提：机器人只能读到它自己参加过的会议的事件，会议必须仍在进行中；查询已结束会议的参会名单、纪要或逐字稿请使用 lark-vc 技能。"
description: "飞书视频会议：让机器人代当前用户加入/离开正在进行的会议，并读取会议期间的实时事件（参会人加入与离开、发言、聊天、屏幕共享等）。1. 用户提供 9 位会议号、要求代为入会或离会时使用 +meeting-join / +meeting-leave——会真实产生入会/离会记录。2. 会议进行中用户想知道“谁加入了”“谁离开了”“谁在发言”“有人共享屏幕吗”等会中动态时，机器人入会后用 +meeting-events 读取事件时间线。3. 典型场景：参会机器人、会中助手、代为旁听、代为参会。前提：机器人只能读到它自己参会过且仍在进行中的会议的事件；查询已结束会议的参会名单、纪要或逐字稿请使用 lark-vc 技能。"
metadata:
requires:
bins: ["lark-cli"]
@@ -10,92 +10,100 @@ metadata:
# vc-agent (v1)
**CRITICAL — 开始前 MUST 先用 Read 工具读取以下两份文档：**
**开始前必须先阅读以下两份 skill 文档：**
- [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — 认证、身份切换、权限处理
- [`../lark-vc/SKILL.md`](../lark-vc/SKILL.md) — 视频会议原子域的**核心概念**（Meeting / meeting_id / Note 等，本 skill 直接复用，不再重复定义）
- [`../lark-vc/SKILL.md`](../lark-vc/SKILL.md) — 视频会议的核心概念（Meeting / Note / Minutes 等），本 skill 直接复用，不再重复定义
## 定位
本 skill 是 `lark-vc` 的**姊妹 skill**，专注 **Agent 参会闭环**（join → events → leave）。把写操作 + 实时事件这类"会中"语义从 `lark-vc` 的"会后查询"语义里切出来，避免混淆。
本 skill 与 [`lark-vc`](../lark-vc/SKILL.md) 并列：
- **`lark-vc` 负责"会后查询"**：搜索历史会议、参会人快照、纪要/逐字稿/录制
- **`lark-vc-agent` 负责"会中动作"**：机器人入会 / 读取进行中会议的实时事件 / 机器人离会
| 用户意图 | 应路由到 |
|---------|---------|
| "帮我入会 123456789"、"作为 agent 参会"、"会中事件"、"谁加入了"（**进行中会议**）| **本 skill** |
| "搜昨天的会"、"查纪要/逐字稿"、"录制"、"参会人快照"（任意时点）| [`lark-vc`](../lark-vc/SKILL.md) |
| "帮我参会并会后发纪要到群里" 这类跨 skill 场景 | 本 skill + [`lark-vc`](../lark-vc/SKILL.md) + [`lark-minutes`](../lark-minutes/SKILL.md) + [`lark-im`](../lark-im/SKILL.md) 按序编排 |
按此分工路由，避免两个 skill 语义混淆。
| 用户意图示例 | 应路由到 |
|---|---|
| "帮我入会 123456789"、"代我参会"、"让机器人进会旁听" | **本 skill** `+meeting-join` |
| "会议现在还开着，谁刚加入了"、"会议里谁在发言"、"有人共享屏幕吗"（**进行中会议**，且**机器人已入会**）| **本 skill** `+meeting-events` |
| "退出会议"、"让机器人离开" | **本 skill** `+meeting-leave` |
| "昨天那场会有谁参加过"、"搜昨天的会"、"查纪要/逐字稿/录制" | [`lark-vc`](../lark-vc/SKILL.md) |
| "帮我参会，结束后把纪要发到群" 等跨阶段场景 | 按序编排：本 skill（入会 → 读事件 → 离会）→ [`lark-vc`](../lark-vc/SKILL.md) / [`lark-minutes`](../lark-minutes/SKILL.md)（拉纪要）→ [`lark-im`](../lark-im/SKILL.md)（发群） |
## 核心场景
### 1. 加入正在进行的会议（写操作）
1. 只有用户明确表达"让 Agent **真实入会**"（参会机器人、会中助手、代为旁听、代参会）时才用 `+meeting-join`。只是查数据不要入会。
2. `+meeting-join --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. 只有当用户明确要求"让机器人真实入会"（参会机器人、会中助手、代为旁听、代为参会）时才调用 `+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。
### 2. 感知会中事件（读操作）
1. 用户要看"会议里正在发生什么"（参会人加入/离开、聊天、转写、屏幕共享）时，用 `+meeting-events`。
2. 输入是 **`meeting_id`**（长数字 ID），不是 9 位会议号。
3. **硬约束**——选型前必读：
- Bot 必须**真实参会过**（先 `+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（`[event_type] 参会人 X joined`），适合**汇总时间线**；`--format json` 保留完整 payload（open_id、聊天原文、share_doc 等），适合**提取字段做进一步处理**（过滤某类事件、联动其他命令）。
6. 保留响应里的 `page_token`，下次增量拉取直接续，不要从头再拉。
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. 离开会议（写操作）
1. 完成任务或用户喊停后用 `+meeting-leave --meeting-id <从 +meeting-join 拿到的 meeting.id>`。
2. **不接受 9 位会议号**，只接受 `meeting_id`。
3. 离会会对其他参会人可见（机器人从参会列表消失），若会议启用了录制/纪要功能，bot 的参会时长到此截止；确认 `meeting_id` 来自上一步 `+meeting-join` 的响应，而不是 9 位会议号。
4. 仅 `user` 身份，同样需要 `vc:meeting.bot.join:write` scope。
1. 任务完成、或用户要求结束时，用 `+meeting-leave --meeting-id <从 +meeting-join 拿到的 meeting.id>`。
2. `--meeting-id` **必须**是 `+meeting-join` 返回的长数字 `meeting.id`，**不接受 9 位会议号**。
3. 离会**立即生效**，机器人从会议的参会人列表中消失，对其他参会人可见；若需要重新入会，再跑一次 `+meeting-join` 即可（非真正"不可逆"）。
4. 仅支持 `user` 身份，scope 同 `+meeting-join`（`vc:meeting.bot.join:write`）。
### 4. Agent 参会最小闭环示范
```bash
# 1. 入会，捕获 meeting.id
JOIN=$(lark-cli vc +meeting-join --meeting-number 123456789 --format json)
MID=$(echo "$JOIN" | jq -r '.meeting.id // .data.meeting.id')
MID=$(echo "$JOIN" | jq -r '.data.meeting.id')
# 2. 会中轮询事件（每隔 N 秒，带递进 --start 避免重复）
# 2. 会中轮询事件
# --start 每轮用上一次响应里最新事件的 event_time，避免拉重复事件
# 典型间隔 10-30 秒
lark-cli vc +meeting-events --meeting-id "$MID" --format pretty
# 3. 任务完成或用户喊停后离会
# 3. 任务完成或用户要求结束时离会
lark-cli vc +meeting-leave --meeting-id "$MID"
# 4. 会后可选：取纪要 / 逐字稿（跨到 lark-vc）
lark-cli vc +notes --meeting-ids "$MID"
```
## Shortcuts（推荐优先使用）
## Shortcuts
Shortcut 是对常用操作的高级封装（`lark-cli vc +<verb> [flags]`）。
| Shortcut | 类型 | 说明 |
|----------|------|------|
| [`+meeting-join`](references/lark-vc-agent-meeting-join.md) | 写 | Join an in-progress meeting by 9-digit meeting number |
| [`+meeting-events`](references/lark-vc-agent-meeting-events.md) | 读 | List bot meeting events (participant joined/left, transcripts, chat, share) |
| [`+meeting-events`](references/lark-vc-agent-meeting-events.md) | 读 | List bot meeting events (participant joined/left, transcript, chat, share) |
| [`+meeting-leave`](references/lark-vc-agent-meeting-leave.md) | 写 | Leave a meeting by meeting_id |
- 使用 `+meeting-join` 前**必须**阅读 [references/lark-vc-agent-meeting-join.md](references/lark-vc-agent-meeting-join.md)，了解入参格式与写操作风险。
- 使用 `+meeting-events` 前**必须**阅读 [references/lark-vc-agent-meeting-events.md](references/lark-vc-agent-meeting-events.md)，了解 `meeting_id` 来源、分页、错误码（10005 / 20001 / 20002）与"bot 仍在会中"限制。
- 使用 `+meeting-leave` 前**必须**阅读 [references/lark-vc-agent-meeting-leave.md](references/lark-vc-agent-meeting-leave.md)，了解 `meeting_id` 的来源与写操作风险。
> **写操作注意**：`+meeting-join` / `+meeting-leave` 会真实入会 / 离会，对其他参会人可见并产生参会记录；执行前核实 9 位会议号 / `meeting_id` 来源。`+meeting-join` 返回的 `meeting.id` 必须保留，后续 `+meeting-leave` / `+meeting-events` 都靠它。
- 使用 `+meeting-join` 前**必须**阅读 [references/lark-vc-agent-meeting-join.md](references/lark-vc-agent-meeting-join.md)，了解入参格式与写操作可见性风险。
- 使用 `+meeting-events` 前**必须**阅读 [references/lark-vc-agent-meeting-events.md](references/lark-vc-agent-meeting-events.md)，了解 `meeting_id` 来源、分页、错误码（10005 / 20001 / 20002）与 "bot 仍在会中" 硬约束。
- 使用 `+meeting-leave` 前**必须**阅读 [references/lark-vc-agent-meeting-leave.md](references/lark-vc-agent-meeting-leave.md)，了解 `meeting_id` 的来源与写操作可见性。
## 权限表
| Shortcut | 所需 scope |
|----------|-----------|
| `+meeting-join` | `vc:meeting.bot.join:write` |
| `+meeting-leave` | `vc:meeting.bot.join:write` |
| `+meeting-events`| `vc:meeting.meetingevent:read` |
| `+meeting-leave` | `vc:meeting.bot.join:write` |
## 延伸
- 查已结束会议 / 会议纪要 / 参会人快照 / 搜索历史会议 → [`lark-vc`](../lark-vc/SKILL.md)
- 查已结束会议、参会人快照、搜索历史会议 → [`lark-vc`](../lark-vc/SKILL.md)
- 会议纪要、逐字稿 → [`lark-vc`](../lark-vc/SKILL.md) 的 `+notes`
- 妙记产物（AI 总结 / 转写 / 章节）→ [`lark-minutes`](../lark-minutes/SKILL.md)
- 会后把产物发到群 / 私聊 → [`lark-im`](../lark-im/SKILL.md)
- 认证、身份切换、scope 管理 → [`lark-shared`](../lark-shared/SKILL.md)