@amaster.ai/pi-lark 0.1.9 → 0.1.11

package/skills/lark-meeting/scenes/create-and-edit-minutes.md

@@ -0,0 +1,147 @@
+# 生成和修改妙记、管理妙记权限
+
+生成妙记和修改妙记都是写操作，必须有用户明确意图。生成成功后保存 `minute_token`；修改前确认唯一 `minute_token` 和目标内容，提供 token 不等于授权修改。除 `minutes +apply-permission` 外，本场景的 Minutes 写命令仅支持用户身份；来源身份为 bot 时停止并说明限制，只有用户明确同意后，才以 `--as user` 重新开始修改流程。`minutes +apply-permission` 支持用户或应用身份，必须沿用触发权限错误时的身份。
+
+## 从本地音视频生成妙记
+
+标准链路是 Drive 上传 → Minutes 创建 → 按需读取产物。不要改用 ffmpeg、Whisper 或其他本地 ASR。
+
+### 上传音视频到 Drive
+
+确认本地媒体路径以及用户最终需要妙记链接、逐字稿、总结、待办还是章节。源文件须符合 [`minutes +upload`](../references/lark-minutes-upload.md) 的格式要求，时长不超过 6 小时，大小不超过 6 GB。
+
+按 [`lark-drive`](../../lark-drive/SKILL.md) 的路径和写操作规则执行 `drive +upload`，取得 `file_token`。上传参数和文件限制见 [`lark-drive-upload`](../../lark-drive/references/lark-drive-upload.md)。
+
+### 使用 file_token 创建妙记
+
+```bash
+lark-cli minutes +upload --file-token <file_token> --as user
+```
+
+从返回的 `minute_url` 路径最后一段提取 `minute_token`，去掉 query 参数。创建参数、支持格式和异步语义见 [`lark-minutes-upload`](../references/lark-minutes-upload.md)。`minutes +upload` 成功仅表示异步创建请求已提交；报告返回的 `minute_url` 和可解析的 `minute_token`。未执行 `minutes +detail` 并确认就绪前，不得声称妙记产物已生成或可用。用户只要求发起创建或返回链接时，到此停止。
+
+### 等待并读取妙记产物
+
+上传后立即读取产物时必须加 `--wait-ready`：
+
+```bash
+lark-cli minutes +detail --minute-tokens <minute_token> --wait-ready --transcript --as user
+```
+
+将 `--transcript` 替换或扩展为用户需要的 `--summary`、`--todo`、`--chapter` 或 `--keyword`。创建任务仍在处理中时，按返回状态和重试提示轮询；不要重复上传或重复创建妙记。
+
+用户要求独立提炼或复盘时，读取 Transcript 并基于原始发言分析，不要复述现成 Summary。产物 flags 和等待行为见 [`lark-minutes-detail`](../references/lark-minutes-detail.md)。
+
+### 从失败阶段恢复
+
+- Drive 上传成功但 Minutes 创建失败：保留并报告 `file_token`，从创建妙记继续，不要重复上传。
+- Minutes 创建成功但产物未就绪：保留 `minute_token` 并重试查询，不要重新创建妙记。
+- 不得把 Drive 上传成功误报为妙记创建成功；明确报告失败发生在上传、创建还是产物生成阶段。
+
+## 修改妙记标题
+
+使用 `minutes +update --minute-token <token> ... --as user`。参数见 [`lark-minutes-update`](../references/lark-minutes-update.md)。
+
+## 替换 AI 总结
+
+使用 `minutes +summary --minute-token <token> ... --as user` 替换总结全文。内容格式与权限见 [`lark-minutes-summary`](../references/lark-minutes-summary.md)。
+
+## 增删改 AI 待办
+
+妙记 AI 待办不是飞书任务。上下文包含妙记 URL / `minute_token` 并要求修改妙记待办时，禁止改走 `lark-task`；用户同时指定了负责人（包括"负责人是我"）也不改变归属。
+
+```bash
+lark-cli minutes +todo --minute-token <token> --operation add|update|delete ... --as user
+```
+
+- 多条新增优先使用 `--todos` 批量提交。
+- 更新或删除前，先执行 `minutes +detail --minute-tokens <token> --todo --as user`，按内容匹配取得精确 `todo_id`；不要用列表顺序代替 ID。
+- 待办 ID、批量结构和部分成功语义见 [`lark-minutes-todo`](../references/lark-minutes-todo.md)。
+
+### 指定负责人
+
+妙记待办表示负责人的既定写法是把 `@姓名` 作为纯文本写进待办内容，不存在独立的负责人字段：
+
+- 用户直接给出姓名时不做任何查找，原文拼成 `@姓名`。
+- 用户说"负责人是我"时，先用 `lark-cli contact +get-user --as user` 取真实姓名再拼接；取不到就不写任何 `@` 提及，不要保留字面的 `@我`。
+- 姓名解析只影响追加的 `@` 文本，绝不能阻塞或取消待办创建；不要为处理负责人改走 `lark-task` 或做进一步通讯录搜索。
+- 不要用"以你的身份创建即归属于你"代替真正的 `@` 文本拼接；`--as` 身份和负责人是两件不相关的事。
+- 回复只陈述结果（妙记、待办内容、负责人、完成状态），不要解释接口字段限制，也不要建议改用 `lark-task` 来"明确负责人"。
+
+完整规则和示例见 [`lark-minutes-todo`](../references/lark-minutes-todo.md) 的「负责人 / `@` 提及」。
+
+## 批量替换逐字稿关键词
+
+```bash
+lark-cli minutes +word-replace --minute-token <token> --replace-words '[{"source_word":"<old>","target_word":"<new>"}]' --as user
+```
+
+多组替换放在同一个 JSON 数组中。具体参数运行 `lark-cli minutes +word-replace --help`。
+
+用户给出原词和目标词后直接替换：不要为了核对写法先读取 Transcript，也不要在替换成功后回读 Transcript 验证。接口逐词返回结果，按结果回报即可。
+
+只要有一个关键词命中就是成功：`data.message` 列出 Succeeded 和 Failed 关键词。重试时只提交 Failed 的词，不要重复提交已成功的词，否则会把新词再替换一遍。
+
+全部关键词都没命中才是失败（`not_found`）。这是参数问题而不是权限问题；如实告知用户哪些词没命中，请用户确认精确写法、大小写和空格后再决定是否重试，不要靠读取 Transcript 自行猜词。
+
+## 替换逐字稿说话人
+
+1. 调用 `lark-cli api GET "/open-apis/minutes/v1/minutes/<token>/transcript/speakerlist"` 取得 `speaker_id`。
+2. 按原说话人的显示名称精确匹配。存在同名候选时，结合 Transcript 展示候选并让用户确认，不要擅选。
+3. 用户只提供目标姓名时，用 [`lark-contact`](../../lark-contact/SKILL.md) 解析为 `ou_` open_id。
+4. 执行 `minutes +speaker-replace --from-speaker-id <speaker_id> --to-user-id <open_id> --as user`；不要把展示名传给 `--from-speaker-id`。
+
+完整流程和参数见 [`lark-minutes-speaker-replace`](../references/lark-minutes-speaker-replace.md)。
+
+## 查看妙记授权列表
+
+用户要查看妙记已授权给哪些成员，或查询某个成员当前的查看 / 编辑权限时，使用 Drive 协作者列表；这不是读取妙记内容，也不是为当前身份申请权限。先读取 [`lark-drive`](../../lark-drive/SKILL.md) 和 [`drive +member-list`](../../lark-drive/references/lark-drive-member-list.md)。
+
+```bash
+lark-cli drive +member-list --token "<minute_url>" --as <source_identity> --format json
+```
+
+完整妙记 URL 可自动推断资源类型为 `minutes`；裸 `minute_token` 必须显式传 `--type minutes`。需要核对指定成员时，按 `member_id` 精确匹配返回的 `items[]`，不要按姓名或列表顺序猜测。
+
+## 分配妙记权限
+
+用户要求“把妙记分享给某人”“让某人可以查看 / 编辑”或“给某人授予权限”时，修改的是目标妙记的协作者权限，使用 `drive +member-add`；禁止使用 `minutes +apply-permission`，后者只为当前调用身份向妙记所有者申请权限。
+
+先读取 [`lark-drive`](../../lark-drive/SKILL.md) 和 [`drive +member-add`](../../lark-drive/references/lark-drive-member-add.md)。目标成员只有展示名时，按 [`lark-contact`](../../lark-contact/SKILL.md) 将其唯一解析为对应 ID；存在多个候选时请用户选择，不得猜测。
+
+```bash
+lark-cli drive +member-add \
+  --token "<minute_url>" \
+  --member-id "<open_id>" \
+  --member-type openid \
+  --perm view \
+  --yes \
+  --as <source_identity> \
+  --format json
+```
+
+完整妙记 URL 可自动推断资源类型为 `minutes`；裸 `minute_token` 必须显式传 `--type minutes`。根据用户要求选择 `view` 或 `edit`；妙记不支持 `full_access`。只有妙记、目标成员和权限档位均已明确，且用户已明确要求执行授权时，才传 `--yes`。
+
+写入后使用 `drive +member-list` 按 `member_id` 回读验证。只有返回的目标成员权限与用户要求一致时，才能声明分配完成；若目标成员已有不同权限，不要仅根据 `member-add` 回执声称权限已被覆盖或降级。
+
+## 为当前身份申请妙记权限
+
+没有查看或编辑权限时，先说明权限事实。只有用户明确要求申请权限时才执行：
+
+```bash
+lark-cli minutes +apply-permission --minute-token <token> --perm view --as <source_identity>
+```
+
+根据用户目标选择 `view` 或 `edit`，并必须沿用触发无权错误时的身份。这只是发起申请，不代表已经获得权限。身份和权限语义见 [`lark-minutes-apply-permission`](../references/lark-minutes-apply-permission.md)。
+
+`permission_denied` 表示对该妙记没有编辑权，不等于 OAuth scope 缺失；请所有者授权，不要误走 `auth login --scope`。
+
+## ASR/AI 额度不足
+
+`minutes +upload`、`+summary`、`+todo` 和 `+word-replace` 都可能返回 `quota_exceeded`，表示 ASR/AI 额度已耗尽。`+upload` 是额度不足以转写这个音视频，妙记根本没有创建；其余三个是该妙记生成时额度就已用尽、AI 产物未完整生成，写操作无法落库。
+
+请用户去妙记详情页查看额度详细信息，不要重试：CLI 无法补充或提升额度，重试同样的请求不会成功。这不是权限问题，也不要误走 `+apply-permission` 或 `auth login --scope`。
+
+## 确认修改结果
+
+修改前只读取目标相关字段，修改后用 `minutes +detail` 或对应读取接口回读。命令自身已逐项返回写入结果时不再回读，例如 `minutes +word-replace` 的 Succeeded / Failed 关键词。批量或多步修改逐项报告写前值、写后结果和失败原因；部分成功时不要回滚已成功项，除非命令明确承诺原子回滚。

package/skills/lark-meeting/scenes/live-meeting-attend.md

@@ -0,0 +1,164 @@
+# 应用机器人参会与会中互动
+
+编排应用机器人的完整会中流程：发现已在参加的会议，或在用户明确授权后发起或加入会议；随后拉取会中事件、发送文本或会中表情、操作倒计时，并仅在用户明确要求时结束会议或离会。
+
+## 选择入口
+
+| 当前条件 | 起点 |
+|---|---|
+| 已有应用身份取得的 `meeting_id` | 直接拉取事件，不重复查询或入会 |
+| 应用机器人可能已在会中 | 已知目标用户 `user_open_id` 时，先用 `+meeting-list-active --as bot --user-id <user_open_id>` 发现会议 |
+| 用户明确要求机器人入会、旁听或代参会 | 使用 `+meeting-join --as bot` |
+| 用户明确要求机器人发起日程会议 | 使用 `+meeting-join --as bot --action start` |
+| 只想查当前用户所在会议 | 使用 [会中事件与会中互动](live-meeting-interact.md) 的用户身份路径，不让应用机器人入会 |
+
+用户只提供 9 位会议号或询问会议内容，不等于授权机器人入会。
+
+## 发现应用机器人已在参加的会议
+
+已知目标用户 `ou_` open_id 时，先查询“目标用户正在参会且应用机器人也在同一会议”的活跃会议：
+
+```bash
+lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
+```
+
+- 返回多个会议时，展示主题、会议号和 `meeting_id` 让用户选择；不擅自取第一个。
+- 返回空不代表目标用户没有在开会，只表示没有找到应用机器人也在会中的可见会议。
+- 用户提供 9 位会议号时，在结果中按 `meeting_no` 匹配；匹配失败时不自动入会。
+- 保存选定的长整数 `meeting_id`，后续事件、消息、倒计时和离会命令都沿用 `--as bot`。
+
+身份可见范围、多会议选择和会议号匹配见 [`lark-vc-meeting-list-active`](../references/lark-vc-meeting-list-active.md)。
+
+## 发起或加入会议
+
+只有用户明确要求应用机器人发起、加入、旁听或代参会时才执行。输入是 9 位会议号，不是长整数 `meeting_id`。
+
+```bash
+# 发起日程会议并加入
+lark-cli vc +meeting-join --as bot --meeting-number <9_digit_meeting_number> --action start
+
+# 加入正在进行的会议
+lark-cli vc +meeting-join --as bot --meeting-number <9_digit_meeting_number>
+```
+
+- 入会前确认目标会议号和用户意图；这是对其他参会人可见的写操作。
+- `--action start` 仅用于发起符合条件的日程会议；未传时保持加入正在进行的会议。
+- 保存返回的 `meeting.id`；后续邀请、拉取事件、发送会中消息、操作倒计时、结束或离会都使用该 ID 与 `--as bot`。
+- 应用机器人可以同时加入多场会议；加入新会议前不需要退出其他会议。
+- 根据返回状态确认入会成功，不要把“请求已发起”当作已入会。
+
+会议密码、等候室、写操作风险和异常恢复见 [`lark-vc-agent-meeting-join`](../references/lark-vc-agent-meeting-join.md)。
+
+## 邀请参会人
+
+只有用户明确要求邀请时才执行。输入是长数字 `meeting_id`，不是 9 位会议号。
+
+```bash
+# 邀请指定用户
+lark-cli vc +meeting-invite --as bot --meeting-id <meeting_id> --type SELECTED --open-ids <open_id>
+
+# 邀请全部合格日程参会人
+lark-cli vc +meeting-invite --as bot --meeting-id <meeting_id> --type ALL_SUGGESTED
+```
+
+- 应用机器人必须已在目标 Calendar VC 中。
+- `SELECTED` 接收用户 `open_id`；`ALL_SUGGESTED` 由服务端筛选合格日程参会人。
+- 以返回结果确认邀请状态，不把请求提交当作参会人已入会。
+
+邀请类型、人数上限和结果语义见 [`lark-vc-agent-meeting-invite`](../references/lark-vc-agent-meeting-invite.md)。
+
+## 拉取会中事件
+
+使用应用身份发现或入会得到的 `meeting_id`：
+
+```bash
+lark-cli vc +meeting-events --as bot --meeting-id <meeting_id> --page-all --format pretty
+```
+
+- 默认使用 `--page-all` 拉取当前完整事件流，并保留返回的 `page_token` 供后续增量查询。
+- 回答“现在、刚刚、最新”或总结当前会议前，重新拉取最新事件；不直接复用旧快照。
+- 应用机器人必须在会中，或在会议结束后的可见宽限窗口内曾经参会；不要用任意 `meeting_id` 尝试读取。
+- 会中事件不能替代已结束会议的参会人快照、纪要、逐字稿或录制。
+
+事件类型、分页、结束后五分钟窗口和文档上下文处理见 [`lark-vc-meeting-events`](../references/lark-vc-meeting-events.md)。
+
+## 发送会中文本或表情
+
+每次发送都是对会中参会人可见的写操作。只有用户明确要求发送，并已确认目标会议和内容时才执行。
+
+```bash
+# 文本消息
+lark-cli vc +meeting-message-send --as bot --meeting-id <meeting_id> --msg-type text --text "<message>"
+
+# 普通会中表情
+lark-cli vc +meeting-message-send --as bot --meeting-id <meeting_id> --msg-type reaction --emoji-type THUMBSUP
+```
+
+- 始终沿用产生 `meeting_id` 的应用身份；不要切换成用户身份。
+- reaction 必须使用 Reference 中大小写敏感的完整 `emoji_type` 列表；不编造 key。
+- 发送失败时停止并报告；不自动重试或换身份，避免产生重复可见消息。
+- 用户要发绑定群或 IM 消息时改用 `lark-im`，不使用会中消息命令。
+
+文本、reaction 语义、完整 emoji key 和幂等参数见 [`lark-vc-meeting-message-send`](../references/lark-vc-meeting-message-send.md)。
+
+## 操作会中倒计时
+
+每次倒计时操作都是对会中参会人可见的写操作。只有用户明确要求设置、延长、提前结束或关闭倒计时时才执行。
+
+```bash
+# 设置倒计时
+lark-cli vc +meeting-countdown --as bot --meeting-id <meeting_id> --action set --duration <minutes>
+
+# 延长倒计时
+lark-cli vc +meeting-countdown --as bot --meeting-id <meeting_id> --action prolong --duration <minutes>
+```
+
+- 始终沿用产生 `meeting_id` 的应用身份；不要切换成用户身份。
+- 用户只给 9 位会议号时，先按应用身份活跃会议列表匹配；匹配失败时不要为了倒计时自动入会，除非用户明确要求机器人入会。
+- `end_in_advance` 和 `close_window` 不携带 `--duration`、提醒点或结束音频参数。
+- 操作失败时停止并报告；不自动重试或换身份，避免重复可见副作用。
+
+动作、提醒点和权限规则见 [`lark-vc-meeting-countdown`](../references/lark-vc-meeting-countdown.md)。
+
+## 结束会议
+
+只有用户明确要求结束整场会议时才执行；不要把结束会议和机器人离会混用。
+
+```bash
+lark-cli vc +meeting-end --as bot --meeting-id <meeting_id> --yes
+```
+
+- 输入是长数字 `meeting_id`。
+- 当前应用机器人必须是 Host；结束成功会结束整场会议。
+- 根据返回状态确认会议已结束。
+
+身份、权限和失败原因见 [`lark-vc-agent-meeting-end`](../references/lark-vc-agent-meeting-end.md)。
+
+## 离开会议
+
+只有用户明确要求机器人退出、离开或结束参会时才执行：
+
+```bash
+lark-cli vc +meeting-leave --as bot --meeting-id <meeting_id>
+```
+
+- 使用入会返回或应用身份活跃会议查询得到的 `meeting_id`，并确认机器人当前在该会议中。
+- 不要因为任务完成而自动离会。
+- 用户只要会后产物时，转入会议产物场景，不为此先执行离会。
+- 根据返回状态确认离会完成。
+
+离会参数、可见副作用和完成判定见 [`lark-vc-agent-meeting-leave`](../references/lark-vc-agent-meeting-leave.md)。
+
+## 应用身份权限配置检查
+
+应用身份返回 `no permission`、`missing required scope(s)` 或 `missing_scopes` 时，不要执行 `auth login`。按顺序检查：
+
+1. 按 CLI 错误中的 `hint` 处理；返回 `console_url` 时将其原样提供给用户。
+2. 确认应用已开通对应权限，已发布并安装到当前租户。入会和应用身份会议查询需要 `vc:meeting.bot.join:write`；会中发消息需要 `vc:meeting.message:write`；会中倒计时需要 `vc:meeting.interaction:write`。
+3. 在开放平台确认“权限可访问的数据范围”已保存为“按条件筛选”，条件为“会议的归属者 包含 与应用的可用范围一致”。
+4. 上述配置均正确仍失败时，保留 CLI 返回的错误码和 `log_id`，按服务端权限异常排查；不要反复登录或改用其他身份重试。
+
+## 会后边界
+
+- 已结束会议的搜索、参会人快照、智能纪要、逐字稿、妙记或录制，转入 [查询会议及其产物](query-meeting-and-artifacts.md)。
+- 会后要把产物发到群或私聊，先使用会议产物场景获取结果，再转 `lark-im`。

package/skills/lark-meeting/scenes/live-meeting-interact.md

@@ -0,0 +1,101 @@
+# 读取会中事件与会中互动
+
+围绕一场正在进行的会议执行只读查询或用户明确授权的会中写操作。真实入会/离会使用应用机器人入会场景；已结束会议和会后产物使用会议查询场景。
+
+如果任务包含“应用机器人入会后继续拉取事件或互动”，只读取并执行 [应用机器人参会与会中互动](live-meeting-attend.md) 的完整流程，不要在两个场景之间来回切换。
+
+## 发现进行中的会议
+
+没有 `meeting_id` 时，按用户需要的视角查询：
+
+```bash
+# 当前登录用户正在参加的会议
+lark-cli vc +meeting-list-active --as user --format json
+
+# 目标用户正在参加、且应用机器人也在会中的会议
+lark-cli vc +meeting-list-active --as bot --user-id <open_id> --format json
+```
+
+- `--user-id` 必须是目标用户的 `ou_` open_id。
+- 应用身份返回空不代表目标用户没有在开会，只代表没有找到目标用户与应用机器人同时在会中的会议。
+- 返回多个会议时，展示标题、会议号和 `meeting_id` 让用户选择，不按“最近”擅选。
+- 用户只给 9 位会议号时，在活跃会议结果中按 `meeting_no` 匹配；匹配失败时不要自动入会。
+- `meeting_id` 从哪种身份取得，后续读取事件、发送消息和操作倒计时就沿用哪种身份。
+
+身份可见范围和会议号匹配见 [`lark-vc-meeting-list-active`](../references/lark-vc-meeting-list-active.md)。
+
+## 读取最新会中事件
+
+```bash
+lark-cli vc +meeting-events --as <same_identity> --meeting-id <meeting_id> --page-all --format pretty
+```
+
+- 默认使用 `--page-all` 获取当前完整事件流，并保留返回的 `page_token` 供下次增量查询。
+- 回答“现在、刚刚、最新”或当前会议总结前，重新查询事件；只有用户明确要求基于历史快照时才复用旧结果。
+- 默认用 pretty 理解时间线；需要精确结构化字段、文档上下文或转发到 IM 时使用 JSON。
+- 不要用会中事件代替已结束会议的参会人快照或会后复盘。
+
+事件类型、分页、五分钟窗口和错误码见 [`lark-vc-meeting-events`](../references/lark-vc-meeting-events.md)。
+
+## 读取共享内容和文档上下文
+
+按事件中的 `share_id`、`share_doc`、`comment_id`、`element_token` 和 `block_id` 精确关联：
+
+- 读取评论时只查询当前 `comment_id`，不要扫描整篇文档评论。
+- 多个共享文档按用户问题选择相关文档；不要用“最近一次共享”替代当前 item 的 `share_id`。
+- 只有用户明确要求预览且事件提供受支持的 `element_type` 与 token 时才下载，并显式选择输出路径。
+- 关联或读取失败时标记 partial，保留原始标识和 raw payload；不要自动下载或猜测文档类型兜底。
+
+精确事件 schema 和后续命令见 [`lark-vc-meeting-events`](../references/lark-vc-meeting-events.md) 的文档上下文部分。
+
+## 读取当前会议画面
+
+仅当用户的问题必须读取当前会议合成画面中的视觉信息，且结构化内容不足以回答时读取画面。适用任务包括识别投屏中实际显示的网页地址、界面状态或报错，理解图表、幻灯片等依赖版式或图像的信息，以及查看摄像头画面。
+
+事件、字幕、聊天或可直接读取的共享文档已经足够回答时，不要截图；会议内容查询、总结或共享文档定位也不以截图兜底，不要仅因为会议正在进行就读取画面。
+
+需要读取时执行：
+
+```bash
+lark-cli vc +meeting-screenshot --as <same_identity> --meeting-id <meeting_id>
+```
+
+身份、会议 ID、输出文件和失败处理见 [`lark-vc-meeting-screenshot`](../references/lark-vc-meeting-screenshot.md)。
+
+## 发送会中文本或表情
+
+只有用户明确要求发送并确认目标会议与内容时执行：
+
+```bash
+lark-cli vc +meeting-message-send --as <same_identity> --meeting-id <meeting_id> --msg-type text --text <message>
+```
+
+- 发送沿用 `meeting_id` 的来源身份；不要为了发送自动入会或先查会议详情。
+- reaction 使用 Reference 中大小写敏感的完整 emoji key；不要编造 key。
+- 发送失败时停止并报告，不自动换身份或重复发送，避免重复可见副作用。
+- 用户要发送绑定群或 IM 消息时改用 `lark-im`，不要把会中消息命令当作群消息能力。
+
+文本、reaction 和权限规则见 [`lark-vc-meeting-message-send`](../references/lark-vc-meeting-message-send.md)。
+
+## 操作会中倒计时
+
+只有用户明确要求设置、延长、提前结束或关闭倒计时时执行：
+
+```bash
+lark-cli vc +meeting-countdown --as <same_identity> --meeting-id <meeting_id> --action set --duration <minutes>
+```
+
+- 这是会中可见的写操作；执行前确认目标会议和动作。
+- 操作沿用 `meeting_id` 的来源身份；不要为了倒计时自动入会或切换身份。
+- 用户只给 9 位会议号时，先用当前身份执行 `+meeting-list-active` 并按 `meeting_no` 匹配。
+- `set` 和 `prolong` 需要 `--duration`；提前结束或关闭时不要携带时长、提醒点或结束音频参数。
+
+动作、提醒点和权限规则见 [`lark-vc-meeting-countdown`](../references/lark-vc-meeting-countdown.md)。
+
+## 处理未发现会议或权限错误
+
+- 用户身份未发现活跃会议时，可以查询当天最近结束的会议；仍无结果再询问时间、主题或会议号，不自行扩大时间范围。
+- 应用身份未发现活跃会议时，只解释当前身份的空结果，不自动查询历史会议或真实入会。
+- 用户身份调用活跃会议或事件查询时，普通 scope 缺失按 CLI hint 申请 `vc:meeting.meetingevent:read`；普通 scope 缺失不表示接口不支持用户身份，只有 CLI 明确说明不支持时才切到应用身份流程。
+- 应用身份缺少权限时不要执行 `auth login`。优先按 CLI 返回的 `missing_scopes`、`hint` 和 `console_url` 处理；手工判断时按能力配置 scope：应用身份活跃会议查询需要 `vc:meeting.bot.join:write`，会中发消息需要 `vc:meeting.message:write`，会中倒计时需要 `vc:meeting.interaction:write`。随后依次检查应用发布、租户安装和“权限可访问的数据范围”；数据范围应为“按条件筛选”，条件为“会议的归属者 包含 与应用的可用范围一致”。
+- scope、安装和数据范围都正确后仍失败时，保留 CLI 返回的错误码和 `log_id`，按服务端权限异常排查；不要反复登录或改用其他身份重试。

package/skills/lark-meeting/scenes/query-meeting-and-artifacts.md

@@ -0,0 +1,90 @@
+# 查询会议及其产物
+
+围绕目标会议执行查询：先取得唯一 `meeting_id`，再按用户目标查询参会人、智能纪要、妙记或录制。已有 `note_id` 或 `minute_token` 时从对应产物直接开始，不要绕回会议搜索。
+
+## 定位会议
+
+在决定批量命令和批次大小之前，必须先规范化全部输入标识：
+
+- 恰好 9 位纯数字是 `meeting_no`，即使用户称其为“会议 ID”。
+- `meeting_no` 必须先逐个通过 `vc +search --query` 转换为搜索结果中的 `id`。
+- `vc +search` 不支持批量会议号；多个 `meeting_no` 按输入顺序逐个解析，也可使用脚本批量转换。
+
+优先复用已有标识，不重复搜索：
+
+| 已有信息 | 操作 |
+|---|---|
+| `meeting_id` | 直接查询会议或关联产物 |
+| `meeting_no` / 9 位会议号 | 用 `vc +search --query "<meeting_no>" --format json --as user` 搜索会议，从结果的 `id` 取得 `meeting_id` |
+| Calendar `event_id` | 用 `calendar +meeting` 获取 `meeting_id` 和用户绑定的 `meeting_note` |
+| `note_id` | 直接进入 [智能纪要场景](query-note-and-artifacts.md) |
+| `minute_token` / 妙记 URL | 直接进入 [妙记场景](query-minutes-and-artifacts.md)；URL 取路径最后一段并去掉 query 参数 |
+
+没有标识时，用 `vc +search` 搜索已经结束的会议：
+
+```bash
+lark-cli vc +search --query <query> --start <start> --end <end> --format json
+```
+
+- 至少提供关键词、时间范围、组织者、参与者或会议室中的一个条件；不要把“总结”“回顾”“所有会议”等动作词当作 `--query`。
+- “今天有哪些会议”需要合并两部分：`vc +search` 查询今天已结束的会议， lark-calendar 查询进行中或未开始的日程。
+- 只有自然语言纪要标题、没有会议 ID、时间、参会人等会议线索时，改用 Drive/Doc 搜索纪要文档，不要把纪要标题当作会议关键词。
+- 根据 `has_more` 和 `page_token` 翻页。未明确要求全量时，累计结果超过 50 条后先确认是否继续；用户明确要求“全部、统计、排序”时直接获取全部结果。
+- 多个候选时展示主题、时间、组织者和 `meeting_id`，让用户选择；不要擅自选择最近的一场。
+
+只需要找到会议时，返回唯一 `meeting_id` 后停止。
+
+搜索参数、日期语义和分页细节见 [`lark-vc-search`](../references/lark-vc-search.md)。
+
+## 选择查询身份
+
+- `vc +search` 仅支持用户身份。`vc +detail`、`vc +recording`、`vc meeting get` 和 `note +detail` 支持用户或应用身份。
+- 已有 `meeting_id`、`note_id` 或 `minute_token` 时，沿用其来源身份；后续 Minutes、Note、Doc 和 Drive 命令都显式传入同一个 `--as`。不要为查询参会人或绕过权限错误擅自切换身份。
+- `note +transcript` 仅支持用户身份。应用身份查到 unified Note 时，先说明限制，只有用户明确同意后才切换身份。
+
+## 获取参会人
+
+查询“谁参加过、何时加入或离开、某人是否参会”时，读取会议的参会人快照：
+
+```bash
+lark-cli vc meeting get --params '{"meeting_id":"<meeting_id>","with_participants":true}' --as <source_identity>
+```
+
+这是服务端快照，不要求应用机器人入会，会议结束后也可以查询。不要用会中事件代替完整参会人快照。
+
+## 获取会议产物标识
+
+使用 `vc +detail` 获取会议关联的 `note_id` 和 `minute_token`：
+
+```bash
+lark-cli vc +detail --meeting-ids <meeting_id> --as <source_identity>
+```
+
+Note 与 Minutes 来自相互独立的 AI 总结和录制链路，可能同时存在、只存在一个或都不存在：
+
+- 用户明确指定“智能纪要”或“妙记”时，沿指定链路处理，不要改道。
+- 只存在一类产物时，使用存在的那一类，不要因默认优先级而把缺失的 Note 或 Minutes 当作错误。
+- 两者都存在且用户未指定时，优先使用 Note。Note 及其逐字稿会后通常直接对参会人可读；Minutes 包含原始音视频并受独立资源 ACL 控制，往往需要所有者授权或由用户明确申请权限。
+- Note 和 Minutes 的总结、待办等 AI 产物可能内容重叠。按上述规则选定一条主链路；除非用户明确要求对照，不要自动拼接、合并或去重两份 AI 产物。
+- 用户只要产物标识时，返回取得的 `note_id` / `minute_token` 后停止；需要产物链接时，进入对应下游场景解析，不继续读取正文。
+- `meeting_note` 是 Calendar 日程上由用户绑定的 Doc，只能从 `event_id` 经 `calendar +meeting` 获取；它与 AI 智能纪要独立，不要从 `meeting_id` 或 `note_id` 推断。
+- 用户询问“有哪些纪要”或“纪要链接”且上下文包含 `event_id` 时，保留 `calendar +meeting` 返回的 `meeting_note`；如存在 `note_id`，进入智能纪要场景取得 `note_doc_token`，再同时返回两者供用户区分选择。
+
+会议详情字段见 [`lark-vc-detail`](../references/lark-vc-detail.md)。
+
+## 转交智能纪要场景
+
+取得 `note_id` 后，进入 [基于 note_id 查询智能纪要及关联产物](query-note-and-artifacts.md)，并传递 `note_id` 与取得该 ID 时使用的 `source_identity`。`note +detail`、正文与封面读取、`note_display_type` 逐字稿路由、共享文档和 Doc 元信息查询全部以该场景为准，不在本场景重复定义。
+
+## 转交妙记场景
+
+取得 `minute_token` 后，进入 [查询妙记及其产物](query-minutes-and-artifacts.md)，并传递 `minute_token` 与取得该 Token 时使用的 `source_identity`。妙记基础信息、AI 产物、Transcript、媒体下载、关联 Note 和资源权限处理全部以该场景为准，不在本场景重复定义。
+
+如果需要从 `meeting_id` 或 Calendar `event_id` 补查录制，先按 [`vc +recording`](../references/lark-vc-recording.md) 取得 `minute_token`，再转入妙记场景。
+
+## 基于会议内容回答或分析
+
+- 用户只要现成的 AI 总结、待办或章节时，直接返回选定链路的对应 AI 产物，不为此额外读取逐字稿。待办通常包含提出人或负责人，章节按话题组织，因此查看待办或会议结构时应优先使用这些结构化 AI 产物。
+- 用户要求提炼、重新总结、复盘、争议分析或“谁说了什么”时，读取 Note 逐字稿或 Minutes Transcript 的原始对话并独立分析；禁止把现成 AI 总结重新排版后冒充独立结论。
+- Note 和 Minutes 都有原始记录且用户未指定时，优先使用 Note 逐字稿；用户明确说“基于妙记”时使用 Minutes Transcript。
+- 如果产物不存在或无权限，如实说明，并保留已经取得的 `meeting_id`、`note_id`、`minute_token` 或文档 token，方便用户继续处理。

package/skills/lark-meeting/scenes/query-minutes-and-artifacts.md

@@ -0,0 +1,70 @@
+# 查询妙记及其产物
+
+围绕目标妙记执行查询：先取得唯一 `minute_token`，再按用户目标查询基础信息、AI 产物、逐字稿、原始媒体或关联的智能纪要。已有会议上下文或 `meeting_id` 时，先从会议链路取得 `minute_token`，不要重复搜索妙记。
+
+## 定位妙记
+
+- 已有 `minute_token` 时直接使用。
+- 妙记 URL 的路径最后一段是 `minute_token`；去掉 query 参数。
+- 没有 token 时，用标题/关键词、所有者、参与者或时间范围执行搜索：
+
+  ```bash
+  lark-cli minutes +search --query <query> --start <start> --end <end> --as user
+  ```
+
+- `minutes +search` 支持用户身份和应用身份。默认使用用户身份；只有用户明确要求应用视角或上下文已经是应用身份时才使用 `--as bot`。
+- `me` 只适用于用户身份；应用身份没有“当前用户”，必须传明确的 `ou_` open_id。应用身份的 token 或 scope 问题不能通过 `auth login` 修复。
+- “我参与的妙记”默认是“我拥有”与“我作为参与者”两次查询的并集，具体过滤语义见 [`lark-minutes-search`](../references/lark-minutes-search.md)。
+- 根据 `has_more` 和 `page_token` 翻页。用户未明确要求全量时，累计结果超过 50 条且仍有更多结果再确认是否继续；用户明确要求“全部、所有、统计、排序”时直接获取全部分页，并按结果中的 `token` 去重后再返回或统计。
+- 多个候选时展示标题、时间、所有者、URL 和 token，让用户选择，不擅自挑选。
+
+只需要搜索结果时，返回命中项后停止。
+
+一旦用某个身份搜索或解析出 `minute_token`，后续妙记详情、产物读取、媒体下载、权限申请及关联 Note / Doc 查询都必须显式沿用同一个 `--as`。不要依赖 profile 默认身份，也不要为绕过资源权限切换身份。
+
+## 查询基础信息
+
+用户只要标题、时长、封面、所有者或 URL 时，使用基础信息命令：
+
+```bash
+lark-cli minutes minutes get --params '{"minute_token":"<minute_token>"}' --as <source_identity>
+```
+
+基础信息已经满足目标时，不继续读取 AI 产物或逐字稿。命令参数不足时运行 `lark-cli minutes minutes get --help`。
+
+## 获取 AI 产物和逐字稿
+
+使用 `minutes +detail`，只传用户需要的产物 flag：
+
+```bash
+lark-cli minutes +detail --minute-tokens <minute_token> --summary --todo --chapter --keyword --transcript --as <source_identity>
+```
+
+- 可选 `--summary`、`--todo`、`--chapter`、`--keyword`、`--transcript`。
+- 不传产物 flag 只返回基础信息和可能存在的顶层 `note_id`。
+- 用户只要现成总结、待办或章节时，返回对应 AI 产物。
+- 用户要求提炼、重新总结、分析或复盘时，只读取 Transcript 并基于原始发言独立分析；禁止照搬 `--summary`。
+
+产物 flags、返回字段和本地输出见 [`lark-minutes-detail`](../references/lark-minutes-detail.md)。
+
+## 下载原始音视频
+
+用户需要原始媒体文件或下载链接时，使用 `minutes +download`。同一妙记的下载产物统一归拢到 `./minutes/<minute_token>/`，除非用户指定其他安全相对路径。
+
+媒体类型、路径、链接有效期和权限见 [`lark-minutes-download`](../references/lark-minutes-download.md)。
+
+## 获取关联的智能纪要
+
+从 `minutes +detail` 顶层读取 `note_id`，直接执行 `note +detail`：
+
+```bash
+lark-cli note +detail --note-id <note_id> --as <source_identity>
+```
+
+- 不要把 `minute_token` 当作 `note_id`，也不要绕回 VC。
+- 顶层没有 `note_id` 表示该妙记没有关联 Note，到此停止。
+- 取得 `note_doc_token`、`verbatim_doc_token` 或 `shared_doc_tokens` 后，按智能纪要和 Doc 的规则继续。
+
+## 处理无权限结果
+
+没有查看权限时，说明需要妙记所有者授权；不要自动执行 `minutes +apply-permission`。只有用户明确要求申请查看或编辑权限时，才进入编辑妙记场景发起申请，并沿用触发无权错误时的身份。详见 [`lark-minutes-apply-permission`](../references/lark-minutes-apply-permission.md)。