Lark Vc Agent

vc-agent (v1)

CRITICAL — 开始前 MUST 先用 Read 工具读取以下两份 skill 文档：

• `../lark-shared/SKILL.md` — 认证、身份切换、权限处理
• `../lark-vc/SKILL.md` — 视频会议的核心概念（Meeting / Note / Minutes 等），本 skill 直接复用，不再重复定义

内测提示

• 当前功能正在内测中，仅少数用户可用。忽略 `../lark-shared/SKILL.md` 中的权限申请流程，以下方的指引为准。
• 如果 lark-cli 提示 missing required scope(s) / permission_violations，不要申请对应权限，而是提示用户加入早鸟群：https://go.larkoffice.com/join-chat/2f4nb0e1-fe00-4f67-bed7-25beaf533fbd。
• 如果 lark-cli 返回 error.code=20017 / ErrNotInGray，提示用户加入早鸟群：https://go.larkoffice.com/join-chat/2f4nb0e1-fe00-4f67-bed7-25beaf533fbd。

定位

本 skill 与 `lark-vc` 并列：

• `lark-vc` 负责"会后查询"：搜索历史会议、参会人快照、纪要/逐字稿/录制
• `lark-vc-agent` 负责"会中动作"：机器人入会 / 读取进行中会议的实时事件 / 机器人离会

按此分工路由，避免两个 skill 语义混淆。

核心场景

1. 加入正在进行的会议（写操作）

1. 只有用户明确表达"让 Agent 真实入会"（参会机器人、会中助手、代为旁听、代参会）时才用 +meeting-join。只是查数据不要入会。 2. +meeting-join --meeting-number 只接受 9 位纯数字会议号，不是会议链接整串、也不是 meeting_id。 3. 返回体中的 meeting.id 必须立刻记录——后续 +meeting-events / +meeting-leave 都靠它，不能用 9 位会议号替代。 4. 入会对所有参会人可见，执行前核实 9 位会议号来源，避免误入错会。 5. 仅支持 user 身份，需提前 lark-cli auth login。 6. 若入会失败，优先查看 +meeting-join reference 的错误排查段落，重点确认会议号、密码、会议状态、等候室 / 审批以及会议是否禁止当前身份加入。

2. 感知会中事件（读操作）

1. 用户要看"会议里正在发生什么"（参会人加入/离开、聊天、转写、屏幕共享）时，用 +meeting-events。 2. 输入是 `meeting_id`（长数字 ID），不是 9 位会议号。 3. Bot 必须真实参会过（先 +meeting-join），否则事件流通常不可见。具体的状态边界、结束后宽限窗口与错误码（如 10005 / 20001 / 20002）请查看 +meeting-events reference。 4. 不能做会后复盘，不能替代参会人快照查询。如果会议已结束：

• 想拿纪要文档或逐字稿文档 token：用 lark-cli vc +notes --meeting-ids <meeting.id>
• 想拿 AI 产物（summary / todos / chapters）或导出逐字稿文件：先用 lark-cli vc +recording --meeting-ids <meeting.id> 拿 minute_token，再用 lark-cli vc +notes --minute-tokens <minute_token>
• 想看参会人快照：用 vc meeting get --with-participants（见 `lark-vc`）

5. 默认必须使用 `--page-all`，除非用户明确要求“只查一页”，或确实需要控制返回体大小。 6. 输出格式默认优先 --format pretty（时间线更易读）；只有在需要完整保留原始消息流与结构化字段时，才使用 --format json。 7. 必须识别分页信号：只要响应里出现 has_more=true、pretty 里的 more available，或返回了非空 page_token，就不能把当前结果当作完整事件流；默认应继续分页，或明确告诉用户当前只是部分结果。 8. 保留响应里的 page_token，下次增量拉取直接续，不要从头再拉。 9. 只要你是基于 `+meeting-events` 来回答一场正在进行中的会议内容，就不能直接复用旧结果。 无论用户是在问“现在/刚刚/最新”的状态，还是让你“总结一下这个会议讲什么”，都必须先重新拉一次当前事件流，确认拿到的是最新信息，再基于最新结果回答。只有在用户明确要求基于某次历史快照继续分析时，才可以复用旧结果。

3. 离开会议（写操作）

1. 任务完成、或用户要求结束时，用 +meeting-leave --meeting-id <从 +meeting-join 拿到的 meeting.id>。 2. --meeting-id 必须是 +meeting-join 返回的长数字 meeting.id，不接受 9 位会议号。 3. 离会立即生效，机器人从会议的参会人列表中消失，对其他参会人可见；若需要重新入会，再跑一次 +meeting-join 即可（非真正"不可逆"）。 4. 仅支持 user 身份。

4. Agent 参会最小闭环示范

# 1. 入会，捕获 meeting.id
JOIN=$(lark-cli vc +meeting-join --meeting-number 123456789 --format json)
MID=$(echo "$JOIN" | jq -r '.data.meeting.id')

# 2. 会中轮询事件
#    默认用 --page-all 拉全当前可见事件；下次增量优先复用 page_token
#    典型间隔 10-30 秒
lark-cli vc +meeting-events --meeting-id "$MID" --page-all --format pretty

# 3. 任务完成或用户要求结束时离会
lark-cli vc +meeting-leave --meeting-id "$MID"

# 4. 会后可选：取纪要 / 逐字稿（跨到 lark-vc）
lark-cli vc +notes --meeting-ids "$MID"

Shortcuts

Shortcut 是对常用操作的高级封装（lark-cli vc +<verb> [flags]）。

• 使用 +meeting-join 前必须阅读 references/lark-vc-agent-meeting-join.md，了解入参格式与写操作可见性风险。
• 使用 +meeting-events 前必须阅读 references/lark-vc-agent-meeting-events.md，了解 meeting_id 来源、分页、错误码（10005 / 20001 / 20002）与 "bot 仍在会中" 硬约束。
• 使用 +meeting-leave 前必须阅读 references/lark-vc-agent-meeting-leave.md，了解 meeting_id 的来源与写操作可见性。

权限表

延伸

• 查已结束会议、参会人快照、搜索历史会议 → `lark-vc`
• 会议纪要、逐字稿 → `lark-vc` 的 +notes
• 妙记产物（AI 总结 / 转写 / 章节）→ `lark-minutes`
• 会后把产物发到群 / 私聊 → `lark-im`
• 认证、身份切换、scope 管理 → `lark-shared`

vc +meeting-events

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

查询当前 bot 在一场正在进行的视频会议中收到的会中事件列表。该命令是读操作。对进行中会议，要求 bot 当前仍在会中；对已结束会议，存在一个结束后 5 分钟内的宽限窗口，只要 bot 曾经在这场会里出现过，仍可继续拉取事件。

本 skill 对应 shortcut：lark-cli vc +meeting-events（调用 GET /open-apis/vc/v1/bots/events）。

命令

# 默认用法：全量拉取当前可见事件
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

# 基于上一次保存的 page_token 继续查新增事件
lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-token <last_page_token> --page-all --format pretty

# 调试或控制返回体大小时，显式只查一页
lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --page-size 20 --format json

# 预览 API 调用（不实际请求）
lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --dry-run

参数

核心约束

1. 输入必须是 meeting_id，不是 9 位会议号

--meeting-id 必须是会议的长数字 ID。它通常来自：

• +meeting-join 返回体中的 meeting.id
• +search 结果中的 id

不要把 9 位会议号（--meeting-number）传给这个命令。

2. 仅支持 user 身份

该命令仅支持 user 身份。

3. bot 必须在会中，或在会议结束后的 5 分钟宽限窗口内曾经在会中

这是查询“bot 在会中观察到的事件”的接口。若 bot 已离会、未入会、或会议已经无法再判断 bot 身份，后端通常会报：

• bot is not in meeting, no permission

因此，最稳妥的调用顺序通常是：

# 先入会
lark-cli vc +meeting-join --meeting-number 123456789

# 记录返回的 meeting.id

# 再查询事件
lark-cli vc +meeting-events --meeting-id <meeting.id>

更精确地说，后端当前的判断规则是：

• 会议进行中：要求 bot 当前仍在会中
• 会议已结束后的 5 分钟内：只要 bot 曾经在这场会中出现过，仍可拉取事件
• 会议结束超过 5 分钟：按会议结束处理，通常不再返回事件流
• bot 从未真实入会过：即使会议仍在进行或刚结束，也会返回 10005 bot is not in meeting

4. 自动分页规则

• 先分清两层默认值：
• shortcut 本身：不传 --page-all 时，只查 1 页。
• 本 skill 的默认策略：除非用户明确要求只看一页，或你确实需要控制返回体大小，否则默认必须主动带 `--page-all`，把当前可见事件尽量一次拉全。
• 传 --page-all：开启自动分页，直到没有更多页面为止。
• --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
• 只有在用户明确要求“就看第一页”“先不要翻页”时，才不要默认带 --page-all
• 只要你是基于 +meeting-events 来回答一场正在进行中的会议内容，就不能直接复用上一次查询结果。无论用户是在问“现在是谁在说话”“刚刚发生了什么”“最新事件有哪些”，还是让你“总结一下这个会议讲什么”，都必须先重新执行一次 +meeting-events，确认拿到的是最新事件流，再回答用户。只有在用户明确要求基于某次历史快照继续分析时，才可以复用旧结果。

5. pretty / json 输出差异

• --format pretty：输出会议主题、会议时间和逐条时间线，适合快速理解“发生了什么”，也是本 skill 的默认推荐格式。
• --format json：保留完整原始 events[] 结构——参会人 open_id、聊天原文、share_doc、分页字段都在原始响应里，适合提取字段、联动其他命令或做进一步程序处理。

选型原则：只要目标是告诉用户“发生了什么”，默认就用 --page-all --format pretty；只有在需要完整原始消息流和结构化字段时，才改用 json。

注意：pretty 输出中的正文文本会做单行转义，真实换行会显示为 \n，避免打乱时间线布局。

6. 内容理解模式：共享文档不能只看标题

当用户意图是：

• “总结这个会议”
• “这个会议讲了什么”
• “有哪些结论 / 待办 / 关键讨论”
• “共享文档里在讲什么”

不要只基于事件时间线直接回答。此时 +meeting-events 只是线索发现器，不是最终信息源。

执行准则：

• 这类问题默认先用 lark-cli vc +meeting-events --meeting-id <meeting.id> --page-all --format json 拉取最新事件流。
• 如果事件中出现共享文档线索，例如：
• magic_share_started
• share_doc.title
• share_doc.url
• 必须继续读取共享文档内容，再生成总结，不能只根据“开始共享了某文档”这条事件和文档标题来概括会议内容。
• 若存在多个共享文档，优先读取最近一次共享的文档。
• 若文档读取失败，必须明确说明“以下总结仅基于会中事件流，未成功读取共享文档内容”。

7. 关于 page_token 的返回与续拉

• 不管这次是只查 1 页，还是通过 --page-all 已经把当前可见事件都拿完，都应把最后拿到的 page_token 一并保留下来并返回给用户。
• 只要响应里出现 has_more=true、pretty 里出现 more available，或返回了非空 page_token，就必须先判断当前结果是否完整；默认情况下，这意味着你还需要继续分页。
• 如果没有使用 --page-all，但出现了上述分页信号，默认应继续用返回的 page_token 拉下一页，而不是直接结束。只有在用户明确不要继续翻页时，才可以停止并明确说明当前结果不完整。
• 下次继续“查新增事件”时，应优先复用上一次保存的 page_token，而不是从头全量再拉一次。
• 只有在用户明确要求“从头回放全部事件”时，才忽略历史 page_token，重新从第一页开始。
• 但如果用户要你回答的是当前这场会正在讲什么，而不是“上一次之后新增了什么”，也要先做一次新的事件查询，再决定是否需要基于旧 page_token 继续补拉。

返回结构

常见顶层字段：

事件 event_type 常见类型：

pretty 输出示例

会议主题：张三的视频会议
会议时间：2026-04-17 15:28:52（进行中）

[00:00:33] 明日之虾BOE(ou_xxx) 加入了会议
[00:00:41] 张三(ou_xxx): [text] 6666
[00:00:44] 张三(ou_xxx) 开始共享《智能纪要：飞书20251022-140223 2026年3月9日》
           URL: https://...
[00:01:32] 张三(ou_xxx): [reaction] JIAYI

如何获取输入参数

Agent 组合场景

场景 1：入会后查看会中发生了什么

# 第 1 步：加入会议，记录返回的 meeting.id
lark-cli vc +meeting-join --meeting-number 123456789

# 第 2 步：查询事件流
lark-cli vc +meeting-events --meeting-id <meeting.id> --page-all --format pretty

场景 2：过滤某段时间内的事件

lark-cli vc +meeting-events \
  --meeting-id <meeting.id> \
  --start 2026-04-17T15:00:00+08:00 \
  --end 2026-04-17T16:00:00+08:00 \
  --page-all \
  --format pretty

场景 3：基于上一次的 page_token 继续查新增事件

# 上一次查询结束后，保留最后返回的 page_token
# 这次直接从该游标继续拉新增事件
lark-cli vc +meeting-events \
  --meeting-id <meeting.id> \
  --page-token <last_page_token> \
  --page-all \
  --format pretty

适用规则：

• 当用户说“继续看新事件”“看上次之后新增了什么”时，优先使用上一次保存的 page_token。
• 如果这次返回里仍有 has_more=true、pretty 里出现 more available，或又返回了新的 page_token，说明新增事件还没拉完，应继续分页，而不是把当前页误当成完整增量结果。
• 只有在用户明确要求“从头回放全部事件”时，才忽略已有 page_token，重新从第一页开始。

常见错误与排查

提示

• 这是会中事件流查询，不适合拿来搜历史会议记录；搜历史会议请用 +search。
• 如果会议已经结束，不要卡在 +meeting-events：
• 想拿纪要文档或逐字稿 token：用 lark-cli vc +notes --meeting-ids <meeting.id>
• 想拿 AI 产物（summary / todos / chapters）或导出逐字稿文件：先用 lark-cli vc +recording --meeting-ids <meeting.id> 拿 minute_token，再用 lark-cli vc +notes --minute-tokens <minute_token>
• 事件列表是否完整，取决于 bot 何时入会、何时离会，以及后端当前可见的会中事件范围。对于已结束会议，通常只在结束后 5 分钟内、且 bot 曾经在会中时还能继续拉到事件。
• 查询"谁参加过某会议"请用 vc meeting get --params '{"meeting_id":"<id>","with_participants":true}'——这是参会人快照 API，不依赖 bot 是否参会，对已结束会议也可查；不要 用 +meeting-events 做参会人查询。

参考

• lark-vc-agent-meeting-join — 先真实入会
• lark-vc-agent-meeting-leave — 完成任务后离会
• lark-vc-search — 搜索历史会议（获取 meeting_id）
• lark-vc-recording — 查询 minute_token
• lark-vc-notes — 获取会议纪要
• lark-vc-agent — Agent 参会能力（本 skill）
• lark-vc — 视频会议原子域（Meeting / Note 等核心概念）
• lark-shared — 认证和全局参数

vc +meeting-join

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

通过 9 位会议号加入一场正在进行的视频会议（bot join）。这是一次写操作，会实际让当前身份加入会议。

本 skill 对应 shortcut：lark-cli vc +meeting-join（调用 POST /open-apis/vc/v1/bots/join）。

命令

# 仅指定会议号（无密码）
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

参数

核心约束

1. 仅支持 user 身份

该命令仅支持 user 身份。

2. 会议号格式严格校验

--meeting-number 必须是 9 位纯数字，否则本地校验直接报错： --meeting-number must be exactly 9 digits。

常见错误来源：

• 把会议链接整条粘进来（应仅取尾部的 9 位数字）
• 把 meeting_id（长数字 ID）当成会议号传入（两者不是同一个东西）

3. 会议必须已开始且允许入会

• 会议必须处于进行中状态，bot 无法加入尚未开始或已结束的会议。
• 若会议设置了等候室 / 入会审批，bot 可能需要主持人放行后才真正入会。
• 若返回 HTTP 403: no permission（错误码 121003），不要只理解成“账号没权限”。这类报错更常见的原因是：会议参数或会控配置当前不满足入会条件，例如会议号填错、密码未传或错误、会议尚未开始、等候室 / 入会审批未放行、会议禁止外部/特定身份加入等。应先确认这些配置项，再重试。

4. 机器人入会后对其他参会人可见

这是一次真实入会操作，机器人会立即出现在参会人列表中，其他参会人可见，并产生会议日志。误入错会的社交成本高于技术成本——执行前优先确认 9 位会议号的来源（用户输入 / 会议链接末尾），不要臆造。参数格式有疑问时可用 --dry-run 预览请求体。

输出结果

接口返回会议基本信息，字段视具体响应而定，常见字段：

重要：拿到 meeting.id 后务必保留，退出会议（+meeting-leave）需要使用它，而不是会议号。

如何获取输入参数

Agent 组合场景

场景 1：加入会议 → 离开会议（最小闭环）

# 第 1 步：加入会议，记录返回的 meeting.id
lark-cli vc +meeting-join --meeting-number 123456789

# 第 2 步：完成任务后，使用上一步返回的 meeting.id 离开会议
lark-cli vc +meeting-leave --meeting-id <meeting.id>

场景 2：加入会议 → 会后拉取纪要 / 录制

# 第 1 步：加入并参会
lark-cli vc +meeting-join --meeting-number 123456789

# 第 2 步：离会
lark-cli vc +meeting-leave --meeting-id <meeting.id>

# 第 3 步：会议结束后，查询录制（拿到 minute_token）
lark-cli vc +recording --meeting-ids <meeting.id>

# 第 4 步：查询会议纪要（总结 / 待办 / 章节 / 逐字稿）
lark-cli vc +notes --meeting-ids <meeting.id>

常见错误与排查

提示

• 仅在 Agent 需要真实加入会议（例如参会机器人、会中助手）时使用；只拉取会议数据不需要入会。
• 入会会让机器人立即出现在参会列表；若要回退，直接 +meeting-leave 即可。参数格式不确定时可选 --dry-run 预览，但不是必经步骤。
• 执行成功后，立即记录返回的 meeting.id，用于后续 +meeting-leave / +meeting-events。

参考

• lark-vc-agent-meeting-leave — 对应的离会命令
• lark-vc-agent-meeting-events — 会中事件流
• lark-vc-search — 搜索历史会议记录
• lark-vc-recording — 查询 minute_token
• lark-vc-notes — 获取会议纪要
• lark-vc-agent — Agent 参会能力（本 skill）
• lark-vc — 视频会议原子域（Meeting / Note 等核心概念）
• lark-shared — 认证和全局参数

vc +meeting-leave

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

通过 meeting_id 离开当前身份所在的视频会议（bot leave）。这是一次写操作，会实际把当前身份从会议中移出。

本 skill 对应 shortcut：lark-cli vc +meeting-leave（调用 POST /open-apis/vc/v1/bots/leave）。

命令

# 通过 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

参数

核心约束

1. 入参是 meeting_id，不是会议号

--meeting-id 必须是会议的长数字 ID，通常由 +meeting-join 返回体中的 meeting.id 提供，也可从 +search 结果中的 id 字段获取。传 9 位会议号会失败。

2. 仅支持 user 身份

该命令仅支持 user 身份。只能让当前身份自己离会，无法强制移出其他参会人。

3. 当前身份必须在会议中

必须先通过 +meeting-join 或其他方式在该会议中，否则接口会报错。

4. 离会立即生效，对其他参会人可见

机器人会立刻从参会列表消失；若会议启用了录制/纪要，bot 的参会时段到此截止。确认任务完成再调用；如需要重新入会，再跑 +meeting-join 即可（非真正"不可逆"）。

输出结果

接口成功返回时，默认输出：Left meeting <meeting-id> successfully.。 --format json 返回 API 原始响应体。

如何获取输入参数

Agent 组合场景

场景 1：加入 → 完成任务 → 离开（最小闭环）

# 第 1 步：加入会议，记录 meeting.id
lark-cli vc +meeting-join --meeting-number 123456789

# 第 2 步：在会中完成任务（如监听发言、记录信息等）
# ...

# 第 3 步：使用上一步记录的 meeting.id 离会
lark-cli vc +meeting-leave --meeting-id <meeting.id>

场景 2：会后补拉产物

# 第 1 步：离会后会议仍在进行或已结束
lark-cli vc +meeting-leave --meeting-id <meeting.id>

# 第 2 步：会议结束后查询录制
lark-cli vc +recording --meeting-ids <meeting.id>

# 第 3 步：查询会议纪要
lark-cli vc +notes --meeting-ids <meeting.id>

常见错误与排查

提示

• 离会会让机器人从参会列表消失，对其他参会人可见；若需要重新入会直接再 +meeting-join，不是真正的"不可逆"。参数格式不确定时可选 --dry-run 预览。
• 与 +meeting-join 成对使用：能 join 的身份才能 leave。
• meeting_id 必须来自 +meeting-join 的返回值，不要用 9 位会议号。

参考

• lark-vc-agent-meeting-join — 对应的入会命令
• lark-vc-agent-meeting-events — 会中事件流
• lark-vc-search — 搜索历史会议（获取 meeting_id）
• lark-vc-recording — 查询 minute_token
• lark-vc-notes — 获取会议纪要
• lark-vc-agent — Agent 参会能力（本 skill）
• lark-vc — 视频会议原子域（Meeting / Note 等核心概念）
• lark-shared — 认证和全局参数