@amaster.ai/pi-lark 0.1.2-beta.60 → 0.1.2-beta.62

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)。

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

@@ -0,0 +1,127 @@
+# 基于 note_id 查询智能纪要及关联产物
+
+- 身份：`note +detail` 支持 `--as user` / `--as bot`；`note +transcript` 仅支持 `--as user`。`note_id` 若由某个身份取得（例如 `vc +detail --as bot`），`note +detail` 及后续 Doc、Drive 命令必须显式沿用同一个 `--as`。
+- 如果 `note +detail --as bot` 返回 `unified`，不要静默切到 `--as user` 继续。先向用户说明该纪要逐字稿只能以用户身份读取，只有用户明确同意才切换身份重试。
+
+## 从智能纪要 Docx 查询关联链接
+
+当用户提供智能纪要 Docx URL/token，且只需要纪要类型或关联产物链接时，直接执行：
+
+```bash
+lark-cli docs +fetch --doc "<docx_url_or_token>" --doc-format markdown --as <source_identity>
+```
+
+从返回结构中仅提取：
+
+- 输入文档：作为智能纪要主文档，返回用户提供的原始 URL。
+- `<vc-transcribe-tab vc-node-id="...">`：可作为明确的 `note_id`。
+- 标记为“文字记录”的 Docx URL。
+- `/minutes/` 妙记 URL。
+- `<cite type="doc" doc-id="..." file-type="...">` 中的共享文档 token。
+
+如果没有从 `<vc-transcribe-tab>` 取得明确的 `note_id`，但存在妙记 URL，从 URL 路径最后一段提取 `minute_token`，再查询妙记基础信息：
+
+```bash
+lark-cli minutes +detail --minute-tokens "<minute_token>" --as <source_identity>
+```
+
+从对应的 `note_id` 继续 Note 查询；该字段为空或未返回时，继续按 Doc 处理。不要把 Doc token 或 `minute_token` 直接传给 Note 命令。
+
+## 确认 note_id
+
+Note 域只接受明确的 `note_id`：
+
+- 用户直接提供的 `note_id`。
+- `vc +detail` 从 `meeting_id` 返回的 `note_id`。
+- `minutes +detail` 从 `minute_token` 返回的顶层 `note_id`。
+- `docs +fetch` 返回的 `<vc-transcribe-tab vc-node-id="...">` 中的 `vc-node-id`。
+
+不要从 Doc token、Docx URL、文档标题、正文或 backlink 反推 `note_id`。只有自然语言纪要标题或 Docx 链接时，先使用 Drive/Doc 搜索或读取文档；没有明确 `vc-node-id` 时继续按 Doc 处理，不进入 Note 查询。如果文档正文明确给出“逐字稿”或“文字记录”的 Docx 链接，将该链接继续作为 Doc 沿用当前身份读取；该链接仍不是 `note_id`。
+
+如果当前只有 `meeting_id`、`minute_token` 或 Calendar `event_id`，先使用会议、妙记或日程场景取得 `note_id`；不要把这些标识直接传给 Note 命令。
+
+## 查询关联产物标识
+
+```bash
+lark-cli note +detail --note-id <note_id> --as <source_identity>
+```
+
+保留以下字段，并按用户目标选择后续操作：
+
+| 字段 | 含义 | 后续操作 |
+|---|---|---|
+| `note_id` | Note 唯一标识 | 后续 Note 命令继续使用该值 |
+| `note_display_type` | `normal` / `unified` / `unknown` | 决定逐字稿入口 |
+| `note_doc_token` | AI 智能纪要正文 | 交给 Doc 读取正文，或交给 Drive 查询名称和 URL |
+| `verbatim_doc_token` | `normal` 或部分 `unknown` Note 的独立逐字稿 Doc | 仅按下方展示类型规则使用 |
+| `shared_doc_tokens` | 会中共享文档列表 | 按用户目标查询元信息或正文 |
+
+用户只需要关联产物标识时，返回上述可用 token 和 `note_display_type` 后停止，不读取文档正文。
+
+## 读取智能纪要正文
+
+用户需要 AI 智能纪要中的总结、待办、章节或正文时，读取 `note_doc_token`：
+
+```bash
+lark-cli docs +fetch --doc <note_doc_token> --doc-format markdown --as <source_identity>
+```
+
+读取正文后，检查返回 Markdown 中的第一个 `<whiteboard token="...">`。该画板是智能纪要封面；存在时提取 token，沿用同一身份下载到 `./notes/<note_id>/cover`，与 `note +transcript` 的逐字稿归入同一 Note 目录，并随正文一起展示：
+
+```bash
+lark-cli docs +media-download --type whiteboard --token <whiteboard_token> --output ./notes/<note_id>/cover --as <source_identity>
+```
+
+没有 `<whiteboard>` 时直接跳过，不视为失败。只有第一个 `<whiteboard>` 按封面处理；不要自动下载正文中的其他画板。
+
+只需要文档名称或 URL 时不要读取正文，使用 Drive 元信息接口：
+
+```bash
+lark-cli drive metas batch_query --data '{"request_docs":[{"doc_type":"docx","doc_token":"<note_doc_token>"}],"with_url":true}' --as <source_identity>
+```
+
+## 读取逐字稿(文字记录)
+
+逐字稿入口由 `note +detail` 返回的 `note_display_type` 决定，不要只根据 `verbatim_doc_token` 是否为空判断：
+
+normal Note 逐字稿是 Doc 读取结果，unified Note 可由 `note +transcript` 保存为 Markdown 或 plain text，Minutes Transcript 则是妙记产物文本。它们都可作为原始发言记录，但序列化格式不是统一契约；应以实际返回内容为准，不要硬编码“发言人 + 相对时间戳”等固定行格式。
+
+### note_display_type = normal 且 有 verbatim_doc_token
+
+```bash
+lark-cli docs +fetch --doc <verbatim_doc_token> --doc-format markdown --as <source_identity>
+```
+
+### note_display_type = unknown 且 有 verbatim_doc_token
+
+```bash
+lark-cli docs +fetch --doc <verbatim_doc_token> --doc-format markdown --as <source_identity>
+```
+
+### note_display_type = unknown 且 无 verbatim_doc_token
+
+停止并说明无法确定逐字稿入口，不要反复重试或猜成 unified
+
+### note_display_type = unified
+
+```bash
+lark-cli note +transcript --note-id <note_id> --as user
+```
+
+`note +transcript` 会自动获取完整分页并保存文件；目标文件已存在时，只有用户明确要求覆盖才添加 `--overwrite`。
+
+## 查询会中共享文档
+
+`shared_doc_tokens` 是该 Note 关联的会中共享文档，不是逐字稿或 `meeting_note`。按用户目标处理：
+
+- 只要文档名称或 URL：使用 `drive metas batch_query`，每批最多查询 10 个 token。
+- 需要正文：逐个使用 `docs +fetch --doc <shared_doc_token>`。
+- 有多个共享文档时，先返回标题和 URL 让用户选择；用户明确要求全部读取时再逐个读取。
+- 某个共享文档不存在或无权限时，保留该 token 并逐项报告，不把整组结果误报为失败。
+
+## 基于纪要内容回答
+
+- 用户只要现成 AI 总结、待办或章节时，读取智能纪要正文并返回对应内容。
+- 用户要求提炼、重新总结、复盘、争议分析或“谁说了什么”时，按展示类型读取逐字稿原始内容并独立分析；禁止直接改写 AI 智能纪要作为独立结论。
+- 用户只要链接或关联产物清单时，不读取正文或逐字稿。
+- `meeting_note` 是 Calendar 日程上用户手工绑定的文档，不属于 Note 的 `shared_doc_tokens`，也不能通过 `note_id` 查询。