@amaster.ai/pi-lark 0.1.9 → 0.1.11

package/skills/lark-meeting/references/lark-vc-meeting-countdown.md

@@ -0,0 +1,103 @@
+# vc +meeting-countdown
+
+设置、延长、提前结束或关闭会中倒计时窗口。
+
+本 skill 对应 shortcut：`lark-cli vc +meeting-countdown`（调用 `POST /open-apis/vc/v1/bots/countdown`）。
+
+## 适用场景
+
+- 用户要求在正在进行中的会议里设置倒计时，例如“设置 5 分钟倒计时”。
+- 用户要求延长当前倒计时，例如“再延长 2 分钟”。
+- 用户要求提前结束或关闭当前倒计时。
+- 只用于正在进行中的会议；已结束会议不支持。
+
+## 身份规则
+
+`meeting_id` 从哪种身份路径拿到，操作倒计时时就沿用哪种身份：
+
+| meeting_id 来源 | 操作时身份 |
+| --- | --- |
+| `+meeting-list-active --as user` | `+meeting-countdown --as user` |
+| `+meeting-list-active --as bot --user-id <user_open_id>` | `+meeting-countdown --as bot` |
+| `+meeting-join --as bot` 返回的 `meeting.id` | `+meeting-countdown --as bot` |
+
+不要把用户身份发现的 `meeting_id` 改用应用身份操作，也不要把应用身份发现的 `meeting_id` 改用用户身份操作，除非用户明确要求切换。
+
+## 参数
+
+| 参数 | 说明 |
+| --- | --- |
+| `--meeting-id` | 必填，长数字 `meeting_id`，不是 9 位会议号 |
+| `--action` | 必填，`set`、`prolong`、`end_in_advance` 或 `close_window` |
+| `--duration` | 倒计时时长，单位是分钟；`set` 和 `prolong` 必填 |
+| `--need-play-audio-at-end` | 仅 `set` 可用，表示倒计时结束时播放提示音 |
+| `--reminder-before-end` | 仅 `set` 可用，提醒点单位是分钟；只支持传一个值 |
+
+`duration` 和 `reminder_before_end` 都是分钟；提醒时间必须大于 0 且小于 `duration`。
+
+## 设置倒计时
+
+```bash
+lark-cli vc +meeting-countdown --as user \
+  --meeting-id <meeting_id> \
+  --action set \
+  --duration 5 \
+  --need-play-audio-at-end \
+  --reminder-before-end 1
+```
+
+Dry-run 请求体示例：
+
+```json
+{
+  "meeting_id": "<meeting_id>",
+  "action": "set",
+  "duration": 5,
+  "need_play_audio_at_end": true,
+  "reminder_before_end": 1
+}
+```
+
+## 延长倒计时
+
+```bash
+lark-cli vc +meeting-countdown --as bot \
+  --meeting-id <meeting_id> \
+  --action prolong \
+  --duration 2
+```
+
+## 提前结束或关闭倒计时
+
+```bash
+lark-cli vc +meeting-countdown --as user --meeting-id <meeting_id> --action end_in_advance
+lark-cli vc +meeting-countdown --as user --meeting-id <meeting_id> --action close_window
+```
+
+提前结束或关闭倒计时窗口时不要传 `--duration`、`--need-play-audio-at-end` 或 `--reminder-before-end`。
+
+## 9 位会议号处理
+
+如果用户给的是 9 位会议号并要求操作倒计时：
+
+1. 先按当前身份执行 `+meeting-list-active`。
+2. 在返回结果中按 `meeting_no` 匹配该 9 位会议号。
+3. 匹配到唯一会议后取长数字 `meeting_id`。
+4. 用发现该会议时的同一身份执行 `+meeting-countdown`。
+
+匹配失败时不要自动入会。只有用户明确要求“让应用机器人入会/旁听/代参会”时，才改用 `+meeting-join`。
+
+## 权限和前置条件
+
+- 用户身份：当前用户必须正在该会议中。
+- 应用身份：应用机器人必须正在该会议中。
+- 需要 `vc:meeting.interaction:write` 权限；应用身份还需要应用已安装、数据范围已配置。
+
+应用身份权限错误时，不要引导用户反复 `auth login`。按主 skill 的“应用身份权限配置检查”处理。
+
+## 相关
+
+- [lark-vc-meeting-list-active](lark-vc-meeting-list-active.md) — 发现当前进行中会议 ID
+- [lark-vc-meeting-events](lark-vc-meeting-events.md) — 读取会中事件
+- [lark-vc-meeting-message-send](lark-vc-meeting-message-send.md) — 发送会中文本或 reaction
+- [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 应用机器人入会

package/skills/{lark-vc → lark-meeting}/references/lark-vc-meeting-events.md

@@ -56,31 +56,7 @@ lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token
 - 应用身份路径：应用机器人必须在会中或参会过；不要拿任意 `meeting_id` 直接查。
 - 不要在拿到 `meeting_id` 后随意切换身份。身份不一致时，常见结果是空列表、`no permission` 或 `bot is not in meeting`。
 
-### 3. 读取事件前必须先拿到可见的 meeting_id
-
-最稳妥的调用顺序通常是：
-
-```bash
-# 方式 1：先入会，直接记录返回的 meeting.id
-lark-cli vc +meeting-join --as bot --meeting-number 123456789
-
-# 再查询事件
-lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
-```
-
-如果应用机器人已经在会中，也可以先通过 active meeting 找会：
-
-```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
-```
-
-如果要查询当前登录用户所在会议：
-
-```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
-```
+### 3. 应用身份的可见性窗口
 
 若应用机器人已离会、未入会、或会议已经无法再判断身份，后端通常会报：
 - `bot is not in meeting, no permission`
@@ -110,8 +86,8 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pret
 
 ### 5. 输出格式差异
 
-- `--format json`：结构化契约，顶层包含 `meeting`、`identity`、`events`、`has_more`、`page_token`。`identity` 表示当前读取身份；事件 actor 统一含 `participant_type`、`role`、`label`；每条事件保留 `payload` 便于追溯细节。
 - `--format pretty`：默认推荐格式，输出当前身份和逐条时间线，适合快速理解“发生了什么”。
+- `--format json`：结构化契约，顶层包含 `meeting`、`identity`、`events`、`has_more`、`page_token`。`identity` 表示当前读取身份；事件 actor 统一含 `participant_type`、`role`、`label`；每条事件保留 `payload` 便于追溯细节。
 - `--format ndjson`：输出事件行，并带 metadata 行，适合流式消费。
 
 **选型原则**：默认先用 `--format pretty`；仅当 `pretty` 缺少完成任务所必需的结构化字段时，才改用 `--format json`。用户明确要求 JSON 或规则明确要求结构化字段时可直接用 `--format json`；需要流式消费时用 `--format ndjson`。
@@ -276,6 +252,7 @@ lark-cli drive +list-replies \
 | `magic_share_started` | 开始共享内容 / 文档 |
 | `magic_share_ended` | 结束共享 |
 | `document_context_changed` | 评论聚焦、章节定位或元素预览上下文变化 |
+| `countdown_changed` | 会中倒计时被设置、延长、提前结束、关闭窗口，或自然结束、临近提醒 |
 
 ### Forwarding meeting chat and reactions to IM
 
@@ -324,74 +301,16 @@ lark-cli vc +meeting-events \
 | `start` / `end` | 用户给出的时间范围；如未给出则默认取全量可见事件 |
 | `page-token` | 上一页或上一次查询结果中保存的 `page_token`；建议持久化保存，便于下次继续拉取新增事件 |
 
-## Agent 组合场景
-
-### 场景 1：入会后读取会中发生了什么
-
-```bash
-# 第 1 步：加入会议，记录返回的 meeting.id
-JOIN=$(lark-cli vc +meeting-join --as bot --meeting-number 123456789 --format json)
-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
-```
-
-### 场景 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
-```
-
-### 场景 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
-```
-
-### 场景 2：过滤某段时间内的事件
-
-```bash
-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
-```
-
-### 场景 3：基于上一次的 `page_token` 继续查新增事件
-
-```bash
-# 上一次查询结束后，保留最后返回的 page_token
-# 这次直接从该游标继续拉新增事件
-lark-cli vc +meeting-events \
-  --as <same_identity> \
-  --meeting-id <id> \
-  --page-token <last_page_token> \
-  --page-all \
-  --format pretty
-```
-
-适用规则：
-
-- 当用户说“继续看新事件”“看上次之后新增了什么”时，优先使用上一次保存的 `page_token`。
-- 如果这次返回里仍有 `has_more=true`、pretty 里出现 `more available`，或又返回了新的 `page_token`，说明新增事件还没拉完，应继续分页，而不是把当前页误当成完整增量结果。
-- 只有在用户明确要求“从头回放全部事件”时，才忽略已有 `page_token`，重新从第一页开始。
-
 ## 常见错误与排查
 
 | 错误现象 | 根本原因 | 解决方案 |
 |---------|---------|---------|
 | `--meeting-id is required` | 未传入 `--meeting-id` | 传入长数字 `meeting.id` |
-| `10005 bot is not in meeting` | 使用应用身份读取，但应用机器人从未真实入会该会议；或会议已结束但应用机器人从未在会中出现过 | 如果 `meeting_id` 来自用户身份发现，改回 `--as user`；如果确实要应用身份读取，先让应用机器人入会或确认它曾参会后再用 `--as bot`。**如果只是想看参会人快照，改用 `lark-cli vc meeting get --params '{"meeting_id":"<meeting.id>"}' --with-participants`** |
+| `10005 bot is not in meeting` | 使用应用身份读取，但应用机器人从未真实入会该会议；或会议已结束但应用机器人从未在会中出现过 | 如果 `meeting_id` 来自用户身份发现，改回 `--as user`；如果确实要应用身份读取，先让应用机器人入会或确认它曾参会后再用 `--as bot`。**如果只是想看参会人快照，改用 `lark-cli vc meeting get --params '{"meeting_id":"<meeting.id>","with_participants":true}'`** |
 | 用户身份无权限 / 不可见 | 当前用户不是该会议的可见参与者，或 `meeting_id` 不是从用户身份路径获得 | 不要反复执行 `auth login`。先确认 `meeting_id` 是否来自 `+meeting-list-active --as user`；如果用户明确要切到应用身份，再通过 `+meeting-list-active --as bot --user-id <user_open_id>` 获取应用身份可读的 `meeting_id`，或在用户明确同意后让应用机器人入会，再用 `+meeting-events --as bot` 读取 |
 | `20001 meeting_status_MEETING_END` | 会议已结束且已超出后端允许的 5 分钟宽限窗口 | 本接口不再适合继续拉取事件。先用 `lark-cli vc +detail --meeting-ids <meeting.id>` 获取会议产物信息，再根据 `note_display_type` / `note_id` / `minute_token` 和用户意图选择纪要正文、逐字稿或妙记；参会人请用 `lark-cli vc meeting get --params '{"meeting_id":"<meeting.id>"}' --with-participants` |
 | `20002 meeting not exist` | `meeting_id` 错误，或会议实例当前已不可获取（常见于把 9 位会议号当 meeting_id 传） | 确认传入的是长数字 `meeting_id`，不是 9 位会议号 |
-| 应用身份权限不足 | 应用权限、租户安装、权限可访问的数据范围或 VC Agent privilege 未配置完整 | 不要执行 `auth login`。请应用开发者开通 `vc:meeting.bot.join:write`；再检查应用发布/安装和权限可访问的数据范围，均正确仍失败时再排查内测灰度权限 |
+| 应用身份权限不足 | 应用权限、租户安装或权限可访问的数据范围未配置完整 | 不要执行 `auth login`。请应用开发者开通 `vc:meeting.bot.join:write`；再检查应用发布/安装和权限可访问的数据范围；配置正确仍失败时，保留错误码和 `log_id`，按服务端权限异常排查 |
 | `HTTP 404` / `HTTP 500` | 服务端当前无法找到或处理该会议实例 | 换一个正在进行且 bot 可见的 meeting_id，或排查后端问题 |
 
 ## 提示
@@ -399,18 +318,10 @@ lark-cli vc +meeting-events \
 - 这是**会中事件流**查询，不适合拿来搜历史会议记录；搜历史会议请用 `+search`。
 - 如果会议已经结束，不要卡在 `+meeting-events`：  
   - 先用 `lark-cli vc +detail --meeting-ids <meeting.id>` 获取会议产物信息。
-  - 再根据 `note_display_type`、`note_id`、`minute_token` 和用户意图，按 `lark-vc` 的产物决策读取纪要正文、逐字稿或妙记。
+  - 再根据 `note_display_type`、`note_id`、`minute_token` 和用户意图，按 `lark-meeting` 的产物决策读取纪要正文、逐字稿或妙记。
 - 事件列表是否完整，取决于应用机器人何时入会、何时离会，以及后端当前可见的会中事件范围。对于已结束会议，通常只在**结束后 5 分钟内**、且应用机器人**曾经在会中**时还能继续拉到事件。
 - 查询"谁参加过某会议"请用 `vc meeting get --params '{"meeting_id":"<id>","with_participants":true}'`——这是参会人**快照** API，不依赖 bot 是否参会，对已结束会议也可查；**不要** 用 `+meeting-events` 做参会人查询。
 
-## 参考
-
-- [lark-vc-agent-meeting-join](../../lark-vc-agent/references/lark-vc-agent-meeting-join.md) — 先真实入会
-- [lark-vc-meeting-list-active](lark-vc-meeting-list-active.md) — 发现当前可读事件的进行中会议 ID
-- [lark-vc-agent-meeting-leave](../../lark-vc-agent/references/lark-vc-agent-meeting-leave.md) — 用户明确要求时离会
-- [lark-vc-search](lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
-- [lark-vc-recording](lark-vc-recording.md) — 查询 minute_token
-- [lark-vc-detail](lark-vc-detail.md) — 获取会议详情
-- [lark-vc-agent](../../lark-vc-agent/SKILL.md) — Agent 参会能力
-- [lark-vc](../SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
-- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
+## 相关场景
+- [会中事件与会中互动](../scenes/live-meeting-interact.md)
+- [应用机器人参会与会中互动](../scenes/live-meeting-attend.md)

package/skills/{lark-vc → lark-meeting}/references/lark-vc-meeting-list-active.md

@@ -33,22 +33,6 @@ 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
-
-# 方式 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
-
-# 方式 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
-```
-
 ## 多会议选择
 
 - 如果返回多个会议，不要自动挑第一个。
@@ -59,14 +43,6 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pret
 
 用户提供 9 位会议号但没有明确要求应用机器人入会时，把会议号当作 active meeting 的筛选条件，而不是写操作指令。
 
-```bash
-# 用户问“我当前这个会讲了什么”
-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
-```
-
 匹配规则：
 
 - 在返回会议中匹配 `meeting_no == <9位会议号>`。
@@ -83,9 +59,8 @@ lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
 | 用户身份无权限 / 不可见 | 当前登录用户没有可见的进行中会议，或当前身份无法读取该会议 | 不要反复执行 `auth login`。确认用户是否在会中、是否切错 profile；用户明确要查询应用机器人可见的会议时，再拿目标用户 open_id 执行 `+meeting-list-active --as bot --user-id <user_open_id>` |
 | 应用身份返回空列表 | 没有满足“目标用户在会中且应用机器人也在会中”的当前会 | 先让应用机器人入会，或确认 `user_id` 和会议状态 |
 | `--user-id` 格式错误 | 传入了 internal user_id 或其他非 `ou_...` 值 | 改传目标用户 open_id |
-| 应用身份权限不足 | 应用权限、租户安装、权限可访问的数据范围或 VC Agent privilege 未配置完整 | 不要执行 `auth login`。请应用开发者开通 `vc:meeting.bot.join:write`；再检查应用发布/安装和权限可访问的数据范围，均正确仍失败时再排查内测灰度权限 |
-
-## 参考
+| 应用身份权限不足 | 应用权限、租户安装或权限可访问的数据范围未配置完整 | 不要执行 `auth login`。请应用开发者开通 `vc:meeting.bot.join:write`；再检查应用发布/安装和权限可访问的数据范围；配置正确仍失败时，保留错误码和 `log_id`，按服务端权限异常排查 |
 
-- [lark-vc-agent-meeting-join](../../lark-vc-agent/references/lark-vc-agent-meeting-join.md) — 让应用机器人真实入会并拿 `meeting.id`
-- [lark-vc-meeting-events](lark-vc-meeting-events.md) — 使用 `meeting_id` 读取会中事件
+## 相关场景
+- [会中事件与会中互动](../scenes/live-meeting-interact.md)
+- [应用机器人参会与会中互动](../scenes/live-meeting-attend.md)

package/skills/{lark-vc → lark-meeting}/references/lark-vc-meeting-message-send.md

@@ -127,8 +127,6 @@ VC_CanNotSee, VC_NoSound, VC_LooksGood, VC_SoundsClear
 
 应用身份权限错误时，不要引导用户反复 `auth login`。按主 skill 的“应用身份权限配置检查”处理。
 
-## 相关
-
-- [lark-vc-meeting-list-active](lark-vc-meeting-list-active.md) — 发现当前进行中会议 ID
-- [lark-vc-meeting-events](lark-vc-meeting-events.md) — 读取会中事件
-- [lark-vc-agent-meeting-join](../../lark-vc-agent/references/lark-vc-agent-meeting-join.md) — 应用机器人入会
+## 相关场景
+- [会中事件与会中互动](../scenes/live-meeting-interact.md)
+- [应用机器人参会与会中互动](../scenes/live-meeting-attend.md)

package/skills/lark-meeting/references/lark-vc-meeting-screenshot.md

@@ -0,0 +1,34 @@
+# `vc +meeting-screenshot`
+
+获取视频会议截图，并保存为 JPEG。
+
+## 常用用法
+
+使用当前用户身份截图，文件写入默认目录：
+
+```bash
+lark-cli vc +meeting-screenshot --as user --meeting-id <long_meeting_id>
+```
+
+使用机器人身份截图，并指定输出路径：
+
+```bash
+lark-cli vc +meeting-screenshot --as bot --meeting-id <long_meeting_id> --output ./meeting-screenshots/current.jpg
+```
+
+## 参数
+
+| Flag | 含义与用法 |
+| --- | --- |
+| `--as <identity>` | 选择 `user` 或 `bot` 身份。使用发现 `meeting_id` 时的同一身份：`user` 要求当前用户在会中；`bot` 要求机器人已入会并具备会中读取权限。 |
+| `--meeting-id <meeting_id>` | 必填。长数字会议 ID，不接受 9 位会议号；只有会议号时，先用同一身份调用 `vc +meeting-list-active` 获取。 |
+| `--output <relative-path>` | 可选。指定 JPEG 文件名或包含子目录的相对路径；相对于执行命令时的当前工作目录。 |
+| `--overwrite` | 可选。目标文件已存在时允许替换；不传时命令会失败并保留原文件。 |
+
+## 文件路径与结果
+
+- 未指定 `--output` 时，默认写入当前工作目录下的 `meeting-screenshots/<meeting_id>-<UTC timestamp>.jpg`。
+- `--output` 可以只写文件名，也可以包含多级子目录；父目录会自动创建。
+- 不接受绝对路径，也不接受解析后超出当前工作目录的 `..` 或符号链接路径。
+- 成功结果包含绝对文件路径、字节数、JPEG content type、SHA-256 和服务端 `log_id`。
+- 服务端决定截图内容并校验会议是否满足条件；调用方不能指定要截取的区域或共享内容。失败不会替换已有文件。

package/skills/{lark-vc → lark-meeting}/references/lark-vc-recording.md

@@ -42,9 +42,7 @@ lark-cli vc +recording --meeting-ids 69xxxxxxxxxxxxx28 --dry-run
 
 ### 2. 身份支持
 
-`--meeting-ids` 和 `--calendar-event-ids` 两种模式都支持 `--as user` 和 `--as bot`。user token 只能查自己有权限的录制；bot 使用 tenant_access_token，只能查 bot 有权限的录制。
-
-拿到的 `minute_token` 是在某个身份下解析出来的：下一步传给 `minutes minutes get` / `minutes +detail` / `minutes +download` 时必须显式沿用同一个 `--as`，不要省略让身份被 profile 默认值悄悄换掉（完整规则见 [lark-shared](../../lark-shared/SKILL.md) 的「身份延续」）。
+`--meeting-ids` 和 `--calendar-event-ids` 都支持 `--as user` / `--as bot`。用户身份只能查自己有权限的录制；应用身份只能查应用有权限的录制。拿到 `minute_token` 后，传给 `minutes minutes get`、`minutes +detail` 或 `minutes +download` 时必须显式沿用同一个 `--as`。
 
 ### 3. 批量上限
 
@@ -74,62 +72,6 @@ lark-cli vc +recording --meeting-ids 69xxxxxxxxxxxxx28 --dry-run
 | `meeting_id` | 使用 `lark-cli vc +search` 搜索历史会议，取结果中的 `id` 字段 |
 | `calendar_event_id` | 使用 `lark-cli calendar +agenda` 查看日程，取结果中的 `event_id` 字段 |
 
-## Agent 组合场景
-
-### 场景 1：知道 meeting_id，想下载录制
-
-```bash
-# 第 1 步：通过 meeting_id 查询录制，拿到 minute_token
-lark-cli vc +recording --meeting-ids xxx --as bot
-
-# 第 2 步：使用上一步返回的 minute_token 下载妙记文件，沿用第 1 步的身份
-lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --as bot
-```
-
-### 场景 2：知道 meeting_id，想查询妙记基础信息
-
-```bash
-# 第 1 步：通过 meeting_id 查询录制，拿到 minute_token
-lark-cli vc +recording --meeting-ids xxx
-
-# 第 2 步：使用上一步返回的 minute_token 查询妙记基础信息
-lark-cli minutes minutes get --params '{"minute_token":"<minute_token>"}'
-```
-
-### 场景 3：知道 meeting_id，想获取完整纪要（含 AI 产物）
-
-```bash
-# 第 1 步：通过 meeting_id 查询录制，拿到 minute_token
-lark-cli vc +recording --meeting-ids xxx
-
-# 第 2 步：使用上一步返回的 minute_token 获取完整纪要
-# ⚠️ 必须显式指定要获取的产物 flag（--summary, --keyword, --todo, --chapter, --transcript）
-lark-cli minutes +detail --minute-tokens <minute_token> --summary --todo --chapter --transcript
-```
-
-### 场景 4：先搜索会议，再获取录制并下载
-
-```bash
-# 第 1 步：搜索历史会议，拿到 meeting_ids
-lark-cli vc +search --query "周会" --start 2026-03-10
-
-# 第 2 步：使用上一步返回的 meeting_ids 查询录制，拿到 minute_tokens
-lark-cli vc +recording --meeting-ids <ids>
-
-# 第 3 步：使用其中一个 minute_token 下载妙记文件
-lark-cli minutes +download --minute-tokens <token>
-```
-
-### 场景 5：从日历事件获取录制
-
-```bash
-# 第 1 步：通过日历 event_id 查询录制，拿到 minute_token
-lark-cli vc +recording --calendar-event-ids <event_id>
-
-# 第 2 步：使用上一步返回的 minute_token 下载妙记文件
-lark-cli minutes +download --minute-tokens <minute_token>
-```
-
 ## 常见错误与排查
 
 | 错误现象 | 根本原因 | 解决方案 |
@@ -138,7 +80,7 @@ lark-cli minutes +download --minute-tokens <minute_token>
 | `no recording available` | 该会议无录制或录制未完成 | 确认会议已结束且开启了录制 |
 | `121005 no permission` | 无权查看该会议录制 | 确认是会议参与者或有录制权限 |
 | `124002 recording generating` | 录制文件仍在生成中 | 等待录制完成后重试 |
-| `missing required scope(s)` | 权限不足 | `--as user`：按提示运行 `auth login --scope`；`--as bot`：使用错误中的 `console_url` 去开发者后台开通，**禁止**对 bot 执行 `auth login`（见 [lark-shared](../../lark-shared/SKILL.md) 的权限恢复表） |
+| `missing required scope(s)` | 权限不足 | `--as user`：按提示运行 `auth login --scope`；`--as bot`：使用错误中的 `console_url` 去开发者后台开通，**禁止**对 bot 执行 `auth login`（见 [lark-shared](../../lark-shared/SKILL.md) 的权限管理） |
 
 ## 提示
 
@@ -147,8 +89,5 @@ lark-cli minutes +download --minute-tokens <minute_token>
 - `minute_token` 从录制 URL 尾段解析（`https://meetings.feishu.cn/minutes/{minute_token}`）。
 - 拿到 `minute_token` 后，如果要妙记基础信息，优先传给 `minutes minutes get`；如果要下载媒体文件，传给 `minutes +download`；如果要逐字稿、总结、待办、章节，再传给 `minutes +detail --minute-tokens`。
 
-## 参考
-
-- [lark-vc](../SKILL.md) — 视频会议全部命令
-- [lark-vc-search](lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
-- [lark-minutes-detail](../../lark-minutes/references/lark-minutes-detail.md) — 获取会议纪要
+## 相关场景
+- [查询会议及其产物](../scenes/query-meeting-and-artifacts.md)

package/skills/{lark-vc → lark-meeting}/references/lark-vc-search.md

@@ -5,7 +5,7 @@
 
 ## 关键词使用边界
 
-`--query` 只用于真实会议关键词，例如会议主题、项目名、评审名、客户名。用户只是说"我这月参加的所有视频会议"、"最近两周我组织的所有视频会议"、"总结主要议题 / 看看参会情况"时，本质是历史会议列表和后续总结，不要把"回顾"、"所有视频会议"、"总结主要议题"等动作词放进 `--query`。这类请求应先用时间范围 + `--participant-ids` / `--organizer-ids` 搜全量候选，再按结果继续取纪要或录制信息。
+`--query` 只用于 9 位会议号或真实会议关键词，例如会议主题、项目名、评审名、客户名。用户只是说"我这月参加的所有视频会议"、"最近两周我组织的所有视频会议"、"总结主要议题 / 看看参会情况"时，本质是历史会议列表和后续总结，不要把"回顾"、"所有视频会议"、"总结主要议题"等动作词放进 `--query`。这类请求应先用时间范围 + `--participant-ids` / `--organizer-ids` 搜全量候选，再按结果继续取纪要或录制信息。
 
 列表阶段只负责找会议记录；总结阶段必须继续取证。若用户要求"主要议题"、"主要决策"、"参会情况"，先确认搜索结果的 `meeting_id`、时间、组织者/参与者符合过滤条件，然后用 `vc +detail` 或 `minutes` 读取纪要、妙记或录制信息。没有纪要或妙记时，如实说明只能基于会议标题/参会数据汇总，不要编造议题。
 
@@ -26,6 +26,9 @@
 # 关键词搜索
 lark-cli vc +search --query "周会"
 
+# 通过 9 位会议号查询会议 ID
+lark-cli vc +search --query "123456789" --format json --as user
+
 # 查询某一天开过的会（单日查询时，start 和 end 必须填写同一天）
 lark-cli vc +search --start 2026-03-10 --end 2026-03-10
 
@@ -48,7 +51,7 @@ lark-cli vc +search --query "周会" --page-token "<PAGE_TOKEN>"
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--query <text>` | 否 | 搜索关键词 |
+| `--query <text>` | 否 | 9 位会议号或搜索关键词 |
 | `--start <time>` | 否 | 开始时间（ISO 8601 或仅日期） |
 | `--end <time>` | 否 | 结束时间（ISO 8601 或仅日期） |
 | `--organizer-ids <ids>` | 否 | 组织者 open_id 列表，逗号分隔 |
@@ -80,17 +83,7 @@ lark-cli vc +search --query "周会" --page-token "<PAGE_TOKEN>"
 
 当返回 `has_more=true` 时，使用响应中的 `page_token` 配合 `--page-token` 获取下一页结果。
 
-### 5. 机器人可同时加入多个会议
-
-机器人支持同时加入多个正在进行中的会议；加入新会议前，不需要先退出已经在会中的其他会议。
-
-这意味着：
-
-- 不要假设 bot 一次只能在一个会议中
-- 如果用户要求 bot 再加入另一场会，可以直接继续执行对应的入会命令
-- 只有在用户明确要求结束某一场会中的 bot 参会时，才调用对应的离会命令
-
-### 6. 日期型 `--end` 包含当天整天
+### 5. 日期型 `--end` 包含当天整天
 
 当 `--end` 传入的是仅日期格式（如 `2026-03-10`）时，CLI 会将它解释为当天 `23:59:59`，而不是当天 `00:00:00`。
 
@@ -131,20 +124,6 @@ lark-cli vc +search --query "周会" --page-size 15
 lark-cli vc +search --query "周会" --page-size 15 --page-token "<PAGE_TOKEN>"
 ```
 
-## 搜索结果中的下一步
-
-搜索结果中的 `meeting_id` 可直接用于继续查询会议纪要或妙记：
-
-```bash
-# 如果要会议纪要 / 逐字稿 / AI 总结 / 待办 / 章节
-lark-cli vc +detail --meeting-ids <MEETING_ID>
-
-# 如果要会议对应的妙记信息 / minute_token / 妙记链接
-lark-cli vc +recording --meeting-ids <MEETING_ID>
-# 然后再用返回的 minute_token 调用：
-lark-cli minutes minutes get --params '{"minute_token":"<MINUTE_TOKEN>"}'
-```
-
 ## 常见错误与排查
 
 | 错误现象 | 根本原因 | 解决方案 |
@@ -155,9 +134,11 @@ lark-cli minutes minutes get --params '{"minute_token":"<MINUTE_TOKEN>"}'
 | 权限不足 | 未授权 `vc:meeting.search:read` | 使用 `auth login` 完成授权 |
 
 ## 提示
-- 必须使用 `--format json` 输出，你更佳擅长解析 JSON 数据。
+- 必须使用 `--format json` 输出，便于稳定解析。
 - 排查参数与请求结构时优先使用 `--dry-run`。
 - 搜索的时间范围最大为 1 个月，如果需要搜索更长时间范围的会议，需要拆分为多次时间范围为一个月查询。
 - 不要使用 `yesterday`、`today` 这类相对时间字面量；请先转换成明确日期，例如 `2026-03-10`。
 - 用户如果明确问的是“妙记信息”而不是“纪要内容”，不要默认走 `vc +detail`；应先用 `vc +recording`。
 
+## 相关场景
+- [查询会议及其产物](../scenes/query-meeting-and-artifacts.md)