From d5327aa7e9968ad8090141c65f1e545ff9bb128e Mon Sep 17 00:00:00 2001 From: renaocheng Date: Fri, 17 Apr 2026 12:08:32 +0800 Subject: [PATCH] docs: add skill references for vc +meeting-join and +meeting-leave --- skills/lark-vc/SKILL.md | 19 ++- .../references/lark-vc-meeting-join.md | 130 ++++++++++++++++++ .../references/lark-vc-meeting-leave.md | 110 +++++++++++++++ 3 files changed, 257 insertions(+), 2 deletions(-) create mode 100644 skills/lark-vc/references/lark-vc-meeting-join.md create mode 100644 skills/lark-vc/references/lark-vc-meeting-leave.md diff --git a/skills/lark-vc/SKILL.md b/skills/lark-vc/SKILL.md index 350ff05aa..99a226ebc 100644 --- a/skills/lark-vc/SKILL.md +++ b/skills/lark-vc/SKILL.md @@ -1,7 +1,7 @@ --- name: lark-vc version: 1.0.0 -description: "飞书视频会议：查询会议记录、获取会议纪要产物（总结、待办、章节、逐字稿）。1. 查询已经结束的会议数量或详情时使用本技能(如历史日期｜ 昨天 | 上周 | 今天已经开过的会议等场景)，查询未开始的会议日程使用 lark-calendar 技能。2. 支持通过关键词、时间范围、组织者、参与者、会议室等筛选条件搜索会议记录。3. 获取或整理会议纪要时使用本技能。" +description: "飞书视频会议：查询会议记录、获取会议纪要产物（总结、待办、章节、逐字稿），以及通过会议号加入/离开正在进行的会议。1. 查询已经结束的会议数量或详情时使用本技能(如历史日期｜ 昨天 | 上周 | 今天已经开过的会议等场景)，查询未开始的会议日程使用 lark-calendar 技能。2. 支持通过关键词、时间范围、组织者、参与者、会议室等筛选条件搜索会议记录。3. 获取或整理会议纪要时使用本技能。4. Agent 需要真实入会/离会（如会中助手、参会机器人）时使用本技能的 +meeting-join / +meeting-leave。" metadata: requires: bins: ["lark-cli"] @@ -51,7 +51,14 @@ lark-cli docs +media-download --type whiteboard --token --out > - 用户意图不明确时，应展示所有文档链接让用户选择，而不是替用户决定 > - 如果用户提供的是**本地音视频文件**并说"转纪要""转逐字稿"，不要直接从 `vc +notes` 开始；应先用 [minutes +upload](../lark-minutes/references/lark-minutes-upload.md) 生成 `minute_url`，再提取 `minute_token` 调用 `vc +notes --minute-tokens` -### 3. 纪要文档与逐字稿链接 +### 3. 加入 / 离开正在进行的会议（写操作） +1. 用户要求 Agent **真实入会**（如参会机器人、会中助手、代为旁听）时，使用 `+meeting-join`；只拉数据不需要入会。 +2. `+meeting-join` 仅接受 **9 位纯数字**的会议号（`--meeting-number`），不要把会议链接整条或 `meeting_id` 当会议号传入。 +3. `+meeting-join` 返回体中的 `meeting.id` **必须立刻记录**，离会时 `+meeting-leave --meeting-id` 用的就是它——不是会议号。 +4. 两个命令都是**写操作**，不支持回放；执行前优先 `--dry-run` 核对请求体。 +5. 仅支持 `user` 身份，需提前完成 `lark-cli auth login` 并拥有 `vc:meeting.bot.join:write` scope。 + +### 4. 纪要文档与逐字稿链接 1. 纪要文档、逐字稿文档与关联的共享文档默认使用文档 Token 返回。 2. 仅需要获取文档名称和 URL 等基本信息时，使用 `lark-cli drive metas batch_query` 查询 ```bash @@ -104,10 +111,16 @@ Shortcut 是对常用操作的高级封装（`lark-cli vc + [flags]`）。 | [`+search`](references/lark-vc-search.md) | Search meeting records (requires at least one filter) | | [`+notes`](references/lark-vc-notes.md) | Query meeting notes (via meeting-ids, minute-tokens, or calendar-event-ids) | | [`+recording`](references/lark-vc-recording.md) | Query minute_token from meeting-ids or calendar-event-ids | +| [`+meeting-join`](references/lark-vc-meeting-join.md) | Join an in-progress meeting by 9-digit meeting number (write) | +| [`+meeting-leave`](references/lark-vc-meeting-leave.md) | Leave a meeting by meeting_id (write) | - 使用 `+search` 命令时，必须阅读 [references/lark-vc-search.md](references/lark-vc-search.md)，了解搜索参数和返回值结构。 - 使用 `+notes` 命令时，必须阅读 [references/lark-vc-notes.md](references/lark-vc-notes.md)，了解查询参数、产物类型和返回值结构。 - 使用 `+recording` 命令时，必须阅读 [references/lark-vc-recording.md](references/lark-vc-recording.md)，了解查询参数和返回值结构。 +- 使用 `+meeting-join` 命令时，必须阅读 [references/lark-vc-meeting-join.md](references/lark-vc-meeting-join.md)，了解入参格式与写操作风险。 +- 使用 `+meeting-leave` 命令时，必须阅读 [references/lark-vc-meeting-leave.md](references/lark-vc-meeting-leave.md)，了解 `meeting_id` 的来源与写操作风险。 + +> **写操作提示**：`+meeting-join` / `+meeting-leave` 是**写操作**，会真实入会 / 离会。执行前优先 `--dry-run` 核对请求体；`+meeting-join` 返回的 `meeting.id` 必须保留，用于后续 `+meeting-leave`。 ## API Resources @@ -145,4 +158,6 @@ lark-cli vc meeting get --params '{"meeting_id": "", "with_participa | `+recording --meeting-ids` | `vc:record:readonly` | | `+recording --calendar-event-ids` | `vc:record:readonly`、`calendar:calendar:read`、`calendar:calendar.event:read` | | `+search` | `vc:meeting.search:read` | +| `+meeting-join` | `vc:meeting.bot.join:write` | +| `+meeting-leave` | `vc:meeting.bot.join:write` | | `meeting.get` | `vc:meeting.meetingevent:read` | diff --git a/skills/lark-vc/references/lark-vc-meeting-join.md b/skills/lark-vc/references/lark-vc-meeting-join.md new file mode 100644 index 000000000..ead9dc759 --- /dev/null +++ b/skills/lark-vc/references/lark-vc-meeting-join.md @@ -0,0 +1,130 @@ + +# vc +meeting-join + +> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 + +通过 9 位会议号加入一场正在进行的视频会议（bot join）。这是一次**写操作**，会实际让当前身份加入会议。 + +本 skill 对应 shortcut：`lark-cli vc +meeting-join`（调用 `POST /open-apis/vc/v1/bots/join`）。 + +## 命令 + +```bash +# 仅指定会议号（无密码） +lark-cli vc +meeting-join --meeting-number 123456789 + +# 指定会议号 + 密码 +lark-cli vc +meeting-join --meeting-number 123456789 --password 8888 + +# 输出格式 +lark-cli vc +meeting-join --meeting-number 123456789 --format json + +# 预览 API 调用（不实际加入会议） +lark-cli vc +meeting-join --meeting-number 123456789 --dry-run +``` + +## 参数 + +| 参数 | 必填 | 说明 | +|------|------|------| +| `--meeting-number ` | 是 | 会议号，必须为 **9 位纯数字** | +| `--password ` | 否 | 会议密码，仅在该会议设置了入会密码时传入 | +| `--format ` | 否 | 输出格式：json (默认) / pretty / table / ndjson / csv | +| `--dry-run` | 否 | 预览 API 调用，不执行 | + +## 核心约束 + +### 1. 仅支持 user 身份 + +该命令仅支持 `user` 身份，使用前需完成 `lark-cli auth login`。 + +### 2. 会议号格式严格校验 + +`--meeting-number` 必须是 9 位纯数字，否则本地校验直接报错： +`--meeting-number must be exactly 9 digits`。 + +常见错误来源： +- 把会议链接整条粘进来（应仅取尾部的 9 位数字） +- 把 `meeting_id`（长数字 ID）当成会议号传入（两者不是同一个东西） + +### 3. 会议必须已开始且允许入会 + +- 会议必须处于**进行中**状态，bot 无法加入尚未开始或已结束的会议。 +- 若会议设置了**等候室 / 入会审批**，bot 可能需要主持人放行后才真正入会。 + +### 4. 写操作不可回放 + +这是一次真实入会操作，执行即产生会议内事件（参会人变化、会议日志等）。需要确认会议号再执行，或先 `--dry-run` 核对请求体。 + +## 输出结果 + +接口返回会议基本信息，字段视具体响应而定，常见字段： + +| 字段 | 说明 | +|------|------| +| `meeting.id` | 会议 ID（可后续传给 `+meeting-leave --meeting-id`） | +| `meeting.meeting_no` | 会议号（与入参一致） | +| `meeting.topic` | 会议主题 | +| `meeting.start_time` | 会议开始时间 | + +> **重要**：拿到 `meeting.id` 后务必保留，退出会议（`+meeting-leave`）需要使用它，而不是会议号。 + +## 如何获取输入参数 + +| 输入参数 | 获取方式 | +|---------|---------| +| `meeting-number` | 会议号由主持人分享；也可从会议链接尾部解析 9 位数字 | +| `password` | 若会议设置了入会密码，由主持人提供 | + +## Agent 组合场景 + +### 场景 1：加入会议 → 离开会议（最小闭环） + +```bash +# 第 1 步：加入会议，记录返回的 meeting.id +lark-cli vc +meeting-join --meeting-number 123456789 + +# 第 2 步：完成任务后，使用上一步返回的 meeting.id 离开会议 +lark-cli vc +meeting-leave --meeting-id +``` + +### 场景 2：加入会议 → 会后拉取纪要 / 录制 + +```bash +# 第 1 步：加入并参会 +lark-cli vc +meeting-join --meeting-number 123456789 + +# 第 2 步：离会 +lark-cli vc +meeting-leave --meeting-id + +# 第 3 步：会议结束后，查询录制（拿到 minute_token） +lark-cli vc +recording --meeting-ids + +# 第 4 步：查询会议纪要（总结 / 待办 / 章节 / 逐字稿） +lark-cli vc +notes --meeting-ids +``` + +## 常见错误与排查 + +| 错误现象 | 根本原因 | 解决方案 | +|---------|---------|---------| +| `--meeting-number must be exactly 9 digits` | 会议号不是 9 位纯数字 | 检查是否误传了会议链接或 meeting_id | +| `missing required scope(s)` | 未授权 `vc:meeting.bot.join:write` | 按提示运行 `auth login --scope vc:meeting.bot.join:write` | +| 会议密码错误 | `--password` 错误或未提供 | 向主持人确认会议密码 | +| 会议不存在 / 已结束 | 会议号错误或会议未进行中 | 确认会议正在进行中 | +| 入会被拒绝 | 等候室 / 入会审批 / 限制外部入会 | 联系主持人放行或调整会议设置 | + +## 提示 + +- 仅在 Agent 需要**真实加入**会议（例如参会机器人、会中助手）时使用；只拉取会议数据不需要入会。 +- 写操作**不可撤销**，先 `--dry-run` 确认请求体再执行。 +- 执行成功后，立即记录返回的 `meeting.id`，用于后续 `+meeting-leave`。 + +## 参考 + +- [lark-vc-meeting-leave](lark-vc-meeting-leave.md) — 对应的离会命令 +- [lark-vc-search](lark-vc-search.md) — 搜索历史会议记录 +- [lark-vc-recording](lark-vc-recording.md) — 查询 minute_token +- [lark-vc-notes](lark-vc-notes.md) — 获取会议纪要 +- [lark-vc](../SKILL.md) — 视频会议全部命令 +- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数 diff --git a/skills/lark-vc/references/lark-vc-meeting-leave.md b/skills/lark-vc/references/lark-vc-meeting-leave.md new file mode 100644 index 000000000..10071dc33 --- /dev/null +++ b/skills/lark-vc/references/lark-vc-meeting-leave.md @@ -0,0 +1,110 @@ + +# vc +meeting-leave + +> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 + +通过 `meeting_id` 离开当前身份所在的视频会议（bot leave）。这是一次**写操作**，会实际把当前身份从会议中移出。 + +本 skill 对应 shortcut：`lark-cli vc +meeting-leave`（调用 `POST /open-apis/vc/v1/bots/leave`）。 + +## 命令 + +```bash +# 通过 meeting_id 离会 +lark-cli vc +meeting-leave --meeting-id 69xxxxxxxxxxxxx28 + +# 输出格式 +lark-cli vc +meeting-leave --meeting-id 69xxxxxxxxxxxxx28 --format json + +# 预览 API 调用（不实际离会） +lark-cli vc +meeting-leave --meeting-id 69xxxxxxxxxxxxx28 --dry-run +``` + +## 参数 + +| 参数 | 必填 | 说明 | +|------|------|------| +| `--meeting-id ` | 是 | 会议 ID（**不是 9 位会议号**） | +| `--format ` | 否 | 输出格式：json (默认) / pretty / table / ndjson / csv | +| `--dry-run` | 否 | 预览 API 调用，不执行 | + +## 核心约束 + +### 1. 入参是 meeting_id，不是会议号 + +`--meeting-id` 必须是会议的长数字 ID，通常由 `+meeting-join` 返回体中的 `meeting.id` 提供，也可从 `+search` 结果中的 `id` 字段获取。**传 9 位会议号会失败**。 + +### 2. 仅支持 user 身份 + +该命令仅支持 `user` 身份，使用前需完成 `lark-cli auth login`。只能让当前身份自己离会，无法强制移出其他参会人。 + +### 3. 当前身份必须在会议中 + +必须先通过 `+meeting-join` 或其他方式在该会议中，否则接口会报错。 + +### 4. 写操作不可回放 + +离会会立刻生效，会议录制、纪要的完整性可能受影响。建议会议任务完成后再调用。 + +## 输出结果 + +接口成功返回时，默认输出：`Left meeting successfully.`。 +`--format json` 返回 API 原始响应体。 + +## 如何获取输入参数 + +| 输入参数 | 获取方式 | +|---------|---------| +| `meeting-id` | `+meeting-join` 返回的 `meeting.id`；或 `+search` 结果中的 `id` 字段 | + +## Agent 组合场景 + +### 场景 1：加入 → 完成任务 → 离开（最小闭环） + +```bash +# 第 1 步：加入会议，记录 meeting.id +lark-cli vc +meeting-join --meeting-number 123456789 + +# 第 2 步：在会中完成任务（如监听发言、记录信息等） +# ... + +# 第 3 步：使用上一步记录的 meeting.id 离会 +lark-cli vc +meeting-leave --meeting-id +``` + +### 场景 2：会后补拉产物 + +```bash +# 第 1 步：离会后会议仍在进行或已结束 +lark-cli vc +meeting-leave --meeting-id + +# 第 2 步：会议结束后查询录制 +lark-cli vc +recording --meeting-ids + +# 第 3 步：查询会议纪要 +lark-cli vc +notes --meeting-ids +``` + +## 常见错误与排查 + +| 错误现象 | 根本原因 | 解决方案 | +|---------|---------|---------| +| `--meeting-id is required` | 未传入 `--meeting-id` | 传入从 `+meeting-join` 得到的 `meeting.id` | +| `meeting not found` / `invalid meeting_id` | 误传了 9 位会议号 | 必须使用 `meeting.id`，不是会议号 | +| `not in meeting` | 当前身份并不在该会议中 | 确认先 `+meeting-join` 成功 | +| `missing required scope(s)` | 未授权 `vc:meeting.bot.join:write` | 按提示运行 `auth login --scope vc:meeting.bot.join:write` | + +## 提示 + +- 写操作**不可撤销**，执行前先 `--dry-run` 核对请求体。 +- 与 `+meeting-join` 成对使用：能 join 的身份才能 leave。 +- 若需要重新入会，再次调用 `+meeting-join`。 + +## 参考 + +- [lark-vc-meeting-join](lark-vc-meeting-join.md) — 对应的入会命令 +- [lark-vc-search](lark-vc-search.md) — 搜索历史会议（获取 meeting_id） +- [lark-vc-recording](lark-vc-recording.md) — 查询 minute_token +- [lark-vc-notes](lark-vc-notes.md) — 获取会议纪要 +- [lark-vc](../SKILL.md) — 视频会议全部命令 +- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数