@amaster.ai/pi-lark 0.1.9 → 0.1.10

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

@@ -117,19 +117,6 @@ CLI 会先按输入的本地日历日语义解析，再标准化为 RFC3339 时
 
 如果用户说“昨天的妙记”“今天的妙记”“某一天内的妙记”，应把 `--start` 和 `--end` 都设置为同一天，而不是把 `--end` 设成下一天。
 
-### 7. 会议的妙记先定位会议
-
-如果用户明确要找某场会议的妙记，或同时提到“会议 / 开会 / 会”和“妙记”，应优先使用 `vc +search` 先定位会议，再按需通过 `vc +recording` 获取 `minute_token`，不要直接按妙记时间范围或关键词搜索。
-只有在无法通过会议搜索定位目标会议，或用户明确要求按妙记维度检索时，才回退到 `minutes +search`。
-
-如果用户要的是"某场会议的妙记信息""某个日程对应的妙记详情""minute\_token""妙记链接""标题""时长""owner"，正确链路是：
-
-1. `vc +search` 或 `calendar +agenda` 先定位会议 / 日程
-2. `vc +recording` 获取 `minute_token`
-3. `minutes minutes get` 查询妙记基础信息
-
-<br />
-
 ## 时间格式
 
 `--start` 和 `--end` 支持以下时间格式：
@@ -149,7 +136,8 @@ CLI 会先按输入的本地日历日语义解析，再标准化为 RFC3339 时
 - 当结果中返回 `has_more=true` 时，说明还有更多页可继续获取。
 - 继续翻页时，使用响应中的 `page_token` 搭配 `--page-token` 发起下一次查询。
 - 不要假设调大 `--page-size` 就能拿全结果；分页遍历时应以 `has_more` 和 `page_token` 为准。
-- 当 `has_more=true` 时，逐页累计已读取的 `items` 数：累计不到 50 条之前可自动继续翻页；超过 50 条后应停下来向用户确认是否获取全部结果。
+- 用户未明确要求全量时，逐页累计已读取的 `items` 数：累计不到 50 条之前可自动继续翻页；超过 50 条且仍有更多结果时，先向用户确认是否继续获取全部结果。
+- 用户明确说“全部 / 所有 / 统计 / 排序”时，该全量意图优先于 50 条确认门槛；直接按 `has_more` 翻完所有分页，按结果中的 `token` 去重后再返回、排序或统计。
 
 ```bash
 # First page
@@ -159,21 +147,6 @@ lark-cli minutes +search --query "预算复盘" --page-size 20
 lark-cli minutes +search --query "预算复盘" --page-size 20 --page-token '<PAGE_TOKEN>'
 ```
 
-## 搜索结果中的下一步
-
-搜索结果中的 `token` 可直接作为 `minute_token` 用于继续查询妙记产物：
-通常先用搜索结果中的 `token` 获取妙记基础信息，确认描述、链接等元数据是否命中目标；只有需要进一步查看逐字稿、总结、待办、章节时，再继续查询关联的纪要产物。
-
-如果你已经确定目标妙记，优先直接复用搜索结果中的 `token`，避免重复搜索。
-
-```bash
-# 首先查询妙记元信息（标题、时长、封面） → 用本 skill
-lark-cli minutes minutes get --params '{"minute_token": "obcn***************"}'
-
-# 查妙记关联的产物(--summary --todo --chapter --keyword --transcript 按需返回)
-lark-cli minutes +detail --minute-tokens <minute_token> --summary
-```
-
 ## 常见错误与排查
 
 | 错误现象                   | 根本原因                                                  | 解决方案                                         |
@@ -194,8 +167,5 @@ lark-cli minutes +detail --minute-tokens <minute_token> --summary
 - 排查参数与请求结构时优先使用 `--dry-run`。
 - 搜索的时间范围最大为 1 个月，如果需要搜索更长时间范围的妙记，需要拆分为多次时间范围为一个月查询。
 
-## 参考
-
-- [lark-minutes](../SKILL.md) -- 妙记相关命令
-- [lark-minutes-detail](lark-minutes-detail.md) -- 基于 `minute_token` 获取逐字稿、总结、待办、章节等产物
-- [lark-vc](../../lark-vc/SKILL.md) -- 视频会议全部命令
+## 相关场景
+- [查询妙记及其产物](../scenes/query-minutes-and-artifacts.md)

package/skills/{lark-minutes → lark-meeting}/references/lark-minutes-speaker-replace.md

@@ -39,7 +39,7 @@
 3. **解析 `--from-speaker-id`**
    - 根据用户描述的原说话人（展示名，如「说话人1」「张三」），在 `speakers[]` 里按 `name` **精确匹配**，取对应的 **`speaker_id`** 作为 `--from-speaker-id` 的值。
    - **`--from-speaker-id` 只传 `speaker_id`，不传展示名。**
-   - 若同名有多条（`name` 相同、`speaker_id` 不同）：**不要擅自挑选**。可结合 [`vc +notes --minute-tokens`](../../lark-vc/references/lark-vc-notes.md) 对照各人发言内容，请用户确认后再用精确的 `speaker_id`。
+   - 若同名有多条（`name` 相同、`speaker_id` 不同）：**不要擅自挑选**。可用 [`minutes +detail --transcript`](lark-minutes-detail.md) 对照各人发言内容，请用户确认后再用精确的 `speaker_id`。
    - 若列表中无匹配展示名：告知用户并核对拼写，或请用户在妙记页面确认标签。
 
 4. **解析 `--to-user-id`**
@@ -102,6 +102,5 @@ Agent 必须先 `lark-cli api GET .../speakerlist`，再 `+speaker-replace`；`-
 | `from_speaker_id` | 实际用于替换的不透明说话人标识 |
 | `to_user_id` | 替换后的新说话人 open_id，与输入的 `--to-user-id` 一致 |
 
-## 参考
-
-- [lark-minutes](../SKILL.md) -- 妙记相关功能说明
+## 相关场景
+- [生成和修改妙记](../scenes/create-and-edit-minutes.md)

package/skills/{lark-minutes → lark-meeting}/references/lark-minutes-summary.md

@@ -113,8 +113,5 @@ lark-cli minutes +summary --minute-token obcnxxxxxxxxxxxxxxxxxxxx --summary @sum
 | 参数无效 | — | `minute_token` 缺失或格式错误 | 检查 token 是否完整 |
 | 权限不足 | — | 缺少 `minutes:minutes:update` | 运行 `auth login --scope "minutes:minutes:update"` |
 
-## 参考
-
-- [lark-minutes](../SKILL.md) — 妙记全部命令
-- [minutes +todo](lark-minutes-todo.md) — 替换待办项
-- [minutes +detail](lark-minutes-detail.md) — 读取总结、待办等 AI 产物
+## 相关场景
+- [生成和修改妙记](../scenes/create-and-edit-minutes.md)

package/skills/{lark-minutes → lark-meeting}/references/lark-minutes-todo.md

@@ -1,6 +1,6 @@
 # minutes +todo
 
-> **路由**：本命令操作**妙记内的 AI 待办**，不是飞书任务（Task）。用户说「在妙记里新建待办」时**必须**用本命令，**禁止**走 `lark-cli task` / `tasklists list` / `task +create`。详见 [lark-minutes/SKILL.md](../SKILL.md) 第 6 节。
+> **路由**：本命令操作**妙记内的 AI 待办**，不是飞书任务（Task）。用户说「在妙记里新建待办」时**必须**用本命令，**禁止**走 `lark-cli task` / `tasklists list` / `task +create`。详见 [生成和修改妙记](../scenes/create-and-edit-minutes.md)。
 
 
 对妙记中的待办做新增 / 更新 / 删除（单条或批量）。写操作。
@@ -24,17 +24,10 @@
 lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add --todo "跟进预算审批" --is-done=false --as user
 
 # 批量：一次新增两条
-lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --as user --todos '[
-  {"operation":"add","content":"晚上好1","is_done":true},
-  {"operation":"add","content":"晚上好2","is_done":false}
-]'
+lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --as user --todos '[{"operation":"add","content":"晚上好1","is_done":true},{"operation":"add","content":"晚上好2","is_done":false}]'
 
 # 批量：混合增删改
-lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --as user --todos '[
-  {"operation":"add","content":"新待办","is_done":false},
-  {"operation":"update","todo_id":"1234567890","content":"已更新","is_done":true},
-  {"operation":"delete","todo_id":"9876543210"}
-]'
+lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --as user --todos '[{"operation":"add","content":"新待办","is_done":false},{"operation":"update","todo_id":"1234567890","content":"已更新","is_done":true},{"operation":"delete","todo_id":"9876543210"}]'
 
 # 从文件读取
 lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --as user --todos @todos.json
@@ -129,8 +122,5 @@ lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add -
 | `error.subtype` = `permission_denied` | **妙记资源无编辑权**：向妙记所有者申请该妙记的编辑/协作权限；**不要**走 `auth login --scope` |
 | 缺少 OAuth scope（`error.missing_scopes` 含 `minutes:minutes:update`） | `lark-cli auth login --scope "minutes:minutes:update"` |
 
-## 参考
-
-- [lark-minutes](../SKILL.md)
-- [minutes +summary](lark-minutes-summary.md)
-- [minutes +detail](lark-minutes-detail.md)
+## 相关场景
+- [生成和修改妙记](../scenes/create-and-edit-minutes.md)

package/skills/{lark-minutes → lark-meeting}/references/lark-minutes-update.md

@@ -34,6 +34,5 @@ lark-cli minutes +update --minute-token xxx --topic "周会纪要 2026-05-18"
 | `minute_token` | 被修改的妙记 Token，与输入的 `--minute-token` 一致，可继续用于查询妙记信息、下载媒体或获取纪要产物 |
 | `topic` | 修改后的妙记标题，与输入的 `--topic` 一致 |
 
-## 参考
-
-- [lark-minutes](../SKILL.md) -- 妙记相关功能说明
+## 相关场景
+- [生成和修改妙记](../scenes/create-and-edit-minutes.md)

package/skills/lark-meeting/references/lark-minutes-upload.md

@@ -0,0 +1,65 @@
+# minutes +upload
+
+
+上传音视频文件到飞书妙记并生成妙记（Minute）。
+
+本 skill 对应 shortcut：`lark-cli minutes +upload`。
+
+## 典型触发表达
+
+- "把这个音视频文件转成妙记"
+- "把这个音视频文件转成纪要"
+- "把这个音视频文件转成逐字稿、文字稿或撰写文字"
+- "把这个音视频文件转成总结、待办或章节"
+
+## 命令示例
+
+```bash
+# 通过已上传到云空间（云盘/云存储）的 file_token 生成妙记
+lark-cli minutes +upload --file-token boxcnxxxxxxxxxxxxxxxx
+
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token <token>` | 是 | 已经上传到飞书云空间（云盘/云存储）的音视频文件的 file_token |
+
+## 支持的格式与限制
+
+待上传到妙记的原始音视频文件必须满足以下要求：
+
+- 支持音频格式：`wav`、`mp3`、`m4a`、`aac`、`ogg`、`wma`、`amr`
+- 支持视频格式：`avi`、`wmv`、`mov`、`mp4`、`m4v`、`mpeg`、`ogg`、`flv`
+- 音视频时长不能超过 `6` 小时
+- 文件大小不能超过 `6 GB`
+
+> 说明：本 shortcut 只接收 `file_token`，不会直接读取本地文件内容，因此这些格式、时长和大小限制对应的是**原始上传文件**本身。若妙记生成失败，请先回查源文件是否满足上述要求。
+
+## 核心约束
+
+### 1. 必须提供 file_token
+
+本接口不直接处理本地文件的上传，必须先使用 `drive +upload` 将文件上传到云空间（云盘/云存储）获取 `file_token`，然后再调用本接口。
+
+### 2. 异步生成
+
+API 会立即返回 `minute_url`，但妙记可能仍在异步生成中。`minutes +upload` 不返回处理状态，命令成功只表示异步创建请求已提交；只有后续执行 `minutes +detail` 并确认就绪，才能声称妙记产物已生成或可用。上传与后续产物获取由 [`create-and-edit-minutes`](../scenes/create-and-edit-minutes.md) 编排；上传后立即查询产物时，`minutes +detail` 必须使用 `--wait-ready`。
+
+## 输出结果示例
+
+```json
+{
+  "minute_url": "http(s)://<host>/minutes/<minute-token>",
+  "minute_token": "<minute-token>"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `minute_url` | 生成的妙记访问链接 |
+| `minute_token` | 从 `minute_url` 提取出的妙记 Token，可直接传给 `minutes +detail --minute-tokens` |
+
+## 相关场景
+- [生成和修改妙记](../scenes/create-and-edit-minutes.md)

package/skills/lark-meeting/references/lark-note-detail.md

@@ -0,0 +1,15 @@
+# note +detail
+
+通过 `note_id` 查询会议纪要详情，获取下挂文档 Token（AI 智能纪要、逐字稿、会中共享文档）。只读，支持 `--as user` 或 `--as bot`。
+
+## 命令
+
+```bash
+lark-cli note +detail --note-id <note_id>
+lark-cli note +detail --note-id <note_id> --as bot
+```
+
+`note_id` 由其他命令取得时，必须显式沿用来源身份。应用身份能否读到数据取决于应用对纪要主文档的查看权限。若 `--as bot` 返回 `note_display_type=unified`，不要静默切换到用户身份执行 `note +transcript`；先向用户说明该命令仅支持用户身份。
+
+## 相关场景
+- [基于 note_id 查询纪要、逐字稿、共享文档等](../scenes/query-note-and-artifacts.md)

package/skills/lark-meeting/references/lark-note-transcript.md

@@ -0,0 +1,19 @@
+# note +transcript
+
+只在 `note +detail` 已确认 `note_display_type=unified` 时使用。普通纪要逐字稿是独立 Docx 文档，应回到 [lark-doc](../../lark-doc/SKILL.md) 读取 `verbatim_doc_token`。
+
+`note +transcript` 仅支持 `--as user`，不支持 `--as bot`。如果 `note +detail --as bot` 返回 `unified`，不要静默省略 `--as` 或改用用户身份继续；先说明该限制，只有用户明确同意后才切换身份重试。
+
+```bash
+lark-cli note +transcript --note-id <note_id>
+```
+
+## 行为契约
+
+- CLI 会先校验该 Note 是否为 `unified`；不是 unified 时不拉取 transcript。
+- CLI 内部自动翻页并拼接完整内容；任一页失败时整体报错，不保存半截 transcript。
+- 默认保存到 `./notes/{note_id}/unified_transcript.md`；`--transcript-format plain_text` 时保存为 `.txt`。
+- 目标文件已存在时会失败；用户明确要覆盖时才加 `--overwrite`。
+
+## 相关场景
+- [基于 note_id 查询纪要、逐字稿、共享文档等](../scenes/query-note-and-artifacts.md)

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

@@ -5,25 +5,13 @@
 
 本 skill 对应 shortcut：`lark-cli vc +meeting-join`（调用 `POST /open-apis/vc/v1/bots/join`）。
 
-> **不要把 9 位会议号等同于入会意图。** 用户给出 9 位会议号并询问“会议讲了什么 / 查会中事件”时，先用 `+meeting-list-active` 查当前 active meetings 并按 `meeting_no` 匹配；只有用户明确要求“入会 / 让应用机器人旁听 / 代我参会”时才调用本命令。
+> **不要把 9 位会议号等同于入会意图。** 用户给出 9 位会议号并询问“会议讲了什么 / 查会中事件”时，先用 `vc +meeting-list-active` 查当前 active meetings 并按 `meeting_no` 匹配；只有用户明确要求“入会 / 让应用机器人旁听 / 代我参会”时才调用本命令。
 
 ## 命令
 
 ```bash
 # 仅指定会议号（无密码）
 lark-cli vc +meeting-join --as bot --meeting-number 123456789
-
-# 指定会议号 + 密码
-lark-cli vc +meeting-join --as bot --meeting-number 123456789 --password 8888
-
-# 从邀请事件透传 call_id（参见「如何获取输入参数」）
-lark-cli vc +meeting-join --as bot --meeting-number 123456789 --call-id a08e06bf-9a41-44e4-a89c-a7871899e783
-
-# 输出格式
-lark-cli vc +meeting-join --as bot --meeting-number 123456789 --format json
-
-# 预览 API 调用（不实际加入会议）
-lark-cli vc +meeting-join --as bot --meeting-number 123456789 --dry-run
 ```
 
 ## 参数
@@ -81,36 +69,6 @@ lark-cli vc +meeting-join --as bot --meeting-number 123456789 --dry-run
 | `password` | 若会议设置了入会密码，由主持人提供 |
 | `call-id` | 由 `vc.bot.meeting_invited_v1` 邀请事件的 `call_id` 字段携带，Agent 收到事件时透传过来；无邀请事件场景（如 Agent 主动入会）不传 |
 
-## Agent 组合场景
-
-### 场景 1：加入会议 → 监听会中事件
-
-```bash
-# 第 1 步：加入会议，记录返回的 meeting.id
-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
-```
-
-如果 bot 已经在会中，也可以通过 active meeting 找回 `meeting_id`：
-
-```bash
-lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
-```
-
-### 场景 2：加入会议 → 会后进入 lark-vc 获取会议产物信息
-
-```bash
-# 第 1 步：加入并参会
-lark-cli vc +meeting-join --as bot --meeting-number 123456789
-
-# 第 2 步：会议结束后，先查询会议产物
-lark-cli vc +detail --meeting-ids <meeting.id>
-```
-
-后续按 `lark-vc` 的产物决策处理：根据 `note_display_type`、`note_id`、`minute_token` 和用户意图选择纪要正文、逐字稿或妙记。
-
 ## 常见错误与排查
 
 | 错误现象 | 根本原因 | 解决方案 |
@@ -119,7 +77,7 @@ lark-cli vc +detail --meeting-ids <meeting.id>
 | 会议密码错误 | `--password` 错误或未提供 | 向主持人确认会议密码 |
 | 会议不存在 / 已结束 | 会议号错误或会议未进行中 | 确认会议正在进行中 |
 | `HTTP 403: no permission` / `121003` | 入会前置条件不满足，通常不是单纯 scope 问题 | 依次确认：1）会议允许智能体加入；2）会议号正确；3）如有密码，已正确传入 `--password`；4）会议已开始；5）等候室 / 入会审批已放行；6）会议未禁止当前身份加入（如限制外部、限制应用机器人、仅特定成员可入会）；确认后重试 |
-| 应用身份权限不足 | 应用权限、租户安装、权限可访问的数据范围或 VC Agent privilege 未配置完整 | 不要执行 `auth login`。以 CLI 返回的 metadata / error envelope 为准确认缺失权限；检查应用发布/安装，以及开放平台“权限可访问的数据范围”：选择“按条件筛选”，条件为“会议的归属者 包含 与应用的可用范围一致”；仍失败再排查内测 privilege / 灰度 |
+| 应用身份权限不足 | 应用权限、租户安装或权限可访问的数据范围未配置完整 | 不要执行 `auth login`。以 CLI 返回的 metadata / error envelope 为准确认缺失权限；检查应用发布/安装，以及开放平台“权限可访问的数据范围”：选择“按条件筛选”，条件为“会议的归属者 包含 与应用的可用范围一致”；配置正确仍失败时，保留错误码和 `log_id`，按服务端权限异常排查 |
 | 入会被拒绝 | 等候室 / 入会审批 / 限制外部入会 | 联系主持人放行或调整会议设置 |
 
 ## 提示
@@ -128,14 +86,5 @@ lark-cli vc +detail --meeting-ids <meeting.id>
 - 入会会让机器人立即出现在参会列表；若用户要求退出 / 离开 / 结束参会，直接使用 `+meeting-leave --as bot --meeting-id <meeting.id>`。参数格式不确定时可选 `--dry-run` 预览，但不是必经步骤。
 - 执行成功后，立即记录返回的 `meeting.id`，用于后续 `+meeting-leave` / `+meeting-events`。
 
-## 参考
-
-- [lark-vc-agent-meeting-leave](lark-vc-agent-meeting-leave.md) — 对应的离会命令
-- [lark-vc-meeting-list-active](../../lark-vc/references/lark-vc-meeting-list-active.md) — 发现当前可读事件的进行中会议 ID
-- [lark-vc-meeting-events](../../lark-vc/references/lark-vc-meeting-events.md) — 会中事件流
-- [lark-vc-search](../../lark-vc/references/lark-vc-search.md) — 搜索历史会议记录
-- [lark-vc-recording](../../lark-vc/references/lark-vc-recording.md) — 查询 minute_token
-- [lark-vc-detail](../../lark-vc/references/lark-vc-detail.md) — 获取会议详情
-- [lark-vc-agent](../SKILL.md) — Agent 参会能力（本 skill）
-- [lark-vc](../../lark-vc/SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
-- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
+## 相关场景
+- [应用机器人参会与会中互动](../scenes/live-meeting-attend.md)

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

@@ -10,12 +10,6 @@
 ```bash
 # 通过 meeting_id 离会
 lark-cli vc +meeting-leave --as bot --meeting-id 69xxxxxxxxxxxxx28
-
-# 输出格式
-lark-cli vc +meeting-leave --as bot --meeting-id 69xxxxxxxxxxxxx28 --format json
-
-# 预览 API 调用（不实际离会）
-lark-cli vc +meeting-leave --as bot --meeting-id 69xxxxxxxxxxxxx28 --dry-run
 ```
 
 ## 参数
@@ -54,30 +48,6 @@ lark-cli vc +meeting-leave --as bot --meeting-id 69xxxxxxxxxxxxx28 --dry-run
 |---------|---------|
 | `meeting-id` | `+meeting-join --as bot` 返回的 `meeting.id`；或应用身份 `+meeting-list-active --as bot --user-id <user_open_id>` 返回的 `meeting_id` |
 
-## Agent 组合场景
-
-### 场景 1：加入 → 用户明确要求时离开
-
-```bash
-# 第 1 步：加入会议，记录 meeting.id
-lark-cli vc +meeting-join --as bot --meeting-number 123456789
-
-# 第 2 步：在会中处理用户请求（如监听发言、记录信息等）
-# ...
-
-# 第 3 步：仅在用户明确要求退出 / 离开 / 结束参会时，使用上一步记录的 meeting.id 离会
-lark-cli vc +meeting-leave --as bot --meeting-id <meeting.id>
-```
-
-### 场景 2：会后补拉产物（不需要离会）
-
-如果用户只是要求会议结束后拉录制、纪要或逐字稿，不要先调用 `+meeting-leave`；直接跨到 `lark-vc` 查询会后产物。
-
-```bash
-# 第 1 步：会议结束后进入 lark-vc 获取会议产物信息
-lark-cli vc +detail --meeting-ids <meeting.id>
-```
-
 ## 常见错误与排查
 
 | 错误现象 | 根本原因 | 解决方案 |
@@ -92,14 +62,5 @@ lark-cli vc +detail --meeting-ids <meeting.id>
 - `+meeting-leave` 优先使用 `+meeting-join --as bot` 返回的 `meeting.id`，但不是每次 join 后都必须调用 leave。
 - `meeting_id` 如果来自 `+meeting-list-active`，必须来自应用身份，并确认应用机器人就在该会议中。不要用 9 位会议号。
 
-## 参考
-
-- [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 对应的入会命令
-- [lark-vc-meeting-list-active](../../lark-vc/references/lark-vc-meeting-list-active.md) — 发现当前可读事件的进行中会议 ID
-- [lark-vc-meeting-events](../../lark-vc/references/lark-vc-meeting-events.md) — 会中事件流
-- [lark-vc-search](../../lark-vc/references/lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
-- [lark-vc-recording](../../lark-vc/references/lark-vc-recording.md) — 查询 minute_token
-- [lark-vc-detail](../../lark-vc/references/lark-vc-detail.md) — 获取会议详情
-- [lark-vc-agent](../SKILL.md) — Agent 参会能力（本 skill）
-- [lark-vc](../../lark-vc/SKILL.md) — 视频会议原子域（Meeting / Note 等核心概念）
-- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
+## 相关场景
+- [应用机器人参会与会中互动](../scenes/live-meeting-attend.md)

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

@@ -0,0 +1,31 @@
+
+# vc +detail
+
+通过会议 ID 获取会议详情，包括基本信息、关联的纪要 ID（`note_id`）和妙记 Token（`minute_token`）。只读，支持 `--as user` / `--as bot`。
+
+## 命令
+
+```bash
+# 单个 / 批量（逗号分隔，最多 50 个）
+lark-cli vc +detail --meeting-ids <meeting_id1>,<meeting_id2>
+
+# 应用身份（只能查应用有权限的会议）
+lark-cli vc +detail --meeting-ids <meeting_id1>,<meeting_id2> --as bot
+```
+
+## 输出字段
+
+| 字段 | 说明 |
+|------|------|
+| `meeting_id` | 会议 ID |
+| `meeting_no` | 会议 9 位号码 |
+| `topic` | 会议主题 |
+| `start_time` | 开始时间 |
+| `end_time` | 结束时间 |
+| `note_id` | 关联的纪要 ID。 |
+| `minute_token` | 关联的妙记 Token。 |
+
+跨产物选择和后续命令链由 [`query-meeting-and-artifacts`](../scenes/query-meeting-and-artifacts.md) 统一编排。`note_id` / `minute_token` 由本命令取得后，后续 `note +detail`、`minutes +detail` 和 Doc 读取命令必须显式沿用同一个 `--as`。
+
+## 相关场景
+- [查询会议及其产物](../scenes/query-meeting-and-artifacts.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`。
@@ -324,74 +300,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 +317,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)