@amaster.ai/pi-lark 0.1.8 → 0.1.10

package/skills/lark-meeting/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: lark-meeting
+version: 1.0.0
+description: "飞书视频会议：查询会议记录与会议产物(纪要/逐字稿/妙记)、妙记搜索/上传/下载/编辑、机器人参与会议；查询进行中的会议、实时会议内容(发言/聊天/共享文档)问答(会上/会里)、发送会中聊天/表情；基于 meeting_id、meeting_no、event_id、note_id、minute_token、vc-node-id 或妙记 URL 查询相关信息。预约会议、忙闲和会议室管理走 lark-calendar。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli vc --help;lark-cli minutes --help;lark-cli note --help"
+---
+
+# lark-meeting
+
+飞书视频会议业务的统一入口，支持查询会议记录、实时会议互动、管理妙记、阅读智能纪要等操作。本技能负责领域关系、任务路由和跨命令编排。
+
+无需预读 [`lark-shared`](../lark-shared/SKILL.md) 或预跑 `auth status --verify`，仅遇到未认证、token / 身份或 scope 错误时读取该 Skill，修复后重试。认证、身份或 scope 管理请求则直接使用该 Skill。
+
+## 身份初始化与延续
+
+把 `source_identity` 作为跨命令工作流的状态：
+
+1. 上下文已有来源身份：严格沿用。用户要求切换时先说明身份连续性和权限影响，不静默切换。
+2. 没有来源身份，用户明确指定身份：使用用户指定的 `--as`。
+3. 没有来源身份且用户未指定：操作语义明确要求应用机器人时使用 `--as bot`，否则显式使用 `--as user`。
+
+确定 `source_identity` 后，再检查目标命令是否支持该身份：
+
+- 支持：显式传入并继续执行。
+- 不支持：说明限制并停止；不要为了让命令成功而替换身份。
+- 只有用户明确同意切换身份后，才以新身份重新开始一条工作流。
+
+## 领域模型与概念
+
+```text
+[会议来源]
+
+Calendar 日程 (event_id) ──预约或关联──┐
+即时会议（无 event_id）────────────────┴──► 会议 (meeting_id)
+
+Calendar 日程 ──meeting_note────────────► Doc（用户纪要，独立于 AI 智能纪要）
+
+[会议产物]
+
+会议 (meeting_id)
+├── AI 总结 ──► Note 智能纪要 (note_id)
+│               ├── 智能纪要文档 ───────────► Doc (note_doc_token)
+│               ├── 逐字稿
+│               │   ├── normal  ──────────► Doc (verbatim_doc_token)
+│               │   └── unified ──────────► note +transcript（非独立 Doc）
+│               └── 共享文档 ──────────────► Doc (shared_doc_tokens)
+│
+└── 录制 ──► Minutes 妙记 (minute_token)
+                 ├── AI 产物：Summary / Todo / Chapter / Keyword
+                 ├── Transcript（文字记录）
+                 └── 原始音视频
+
+本地音视频 ─────────────────────────────► Minutes 妙记 (minute_token)
+```
+
+| 对象 | 主标识 | 概念与关系 |
+|---|---|---|
+| Calendar 日程 | `event_id` | 日历上的日程，包含时间、参与人、会议室和 RSVP，可预约或关联 VC 会议；不是完整的会议记录。日程上的 `meeting_note` 是用户手工绑定的 Doc，与 AI 智能纪要无关。 |
+| Meeting 会议 | `meeting_id` | 实际发生的视频会议，可以来自 Calendar，也可以是没有日程的即时会议。会议主题、时间、参会人快照和会中事件属于会议数据；Note 与 Minutes 是它可能关联的会后产物。 |
+| Note 智能纪要 | `note_id` | 开启 AI 总结后形成的逻辑产物集合。`note_display_type` 决定获取逐字稿中文字记录的不同方式。 |
+| Minutes 妙记 | `minute_token` | 由会议录制或本地音视频上传生成，包含总结、待办、章节、关键词、文字记录和原始音视频；可以关联 VC 会议，也可以独立存在。 |
+| Doc 文档 | Doc token | 内容载体，不是会议标识。`note_doc_token`、`shared_doc_tokens` 和部分 `verbatim_doc_token` 指向 Doc；Doc token 不能当作 `note_id` 或 `meeting_id`。 |
+
+### 核心标识
+
+- `meeting_id`：会议 ID。长数字字符串，不是 9 位会议号。
+- `meeting_no`：会议号。9 位纯数字；CLI 参数名为 `--meeting-number`。
+- `minute_token`：妙记 Token。小写字母数字串，通常取自妙记 URL `/minutes/<minute_token>`。
+
+以上标识均按字符串原样传递，不能相互替代。
+
+### 领域不变量
+
+- Note 与 Minutes 分别来自 AI 总结和录制两条独立链路。一场会议可能同时有两类产物、只有其中一类，也可能都没有；不能根据 `note_id` 推断必然存在 `minute_token`，反之亦然。
+- Minutes 可以由本地音视频直接生成，因此不一定关联 `meeting_id` 或 Calendar `event_id`。
+- Calendar `meeting_note`、Note `note_id`、Minutes `minute_token` 和各类 Doc token 标识不同对象，不能互换、代入其他域的命令或从一者反推另一者。
+
+## 快速行动
+
+### 查询进行中的会议内容
+
+```bash
+# 当前用户所在会议
+lark-cli vc +meeting-list-active --as user
+
+# 应用机器人可见的目标用户会议
+lark-cli vc +meeting-list-active --as bot --user-id <open_id>
+
+# 确定唯一 meeting_id 后沿用来源身份
+lark-cli vc +meeting-events --as <source_identity> --meeting-id <meeting_id> --page-all --format pretty
+```
+
+同时有多场会议时，需要先选择要查询的会议；只有一场会议时，直接查询该场会议的会议事件。
+
+应用身份只返回“目标用户正在参会、且应用机器人也在同一会议中”的会议；返回空不代表目标用户没有在开会。向用户说明结果时使用“用户身份”或“应用身份”，不要暴露 `user` / `bot` 这类内部缩写。
+
+## 场景手册
+
+当任务目标与场景匹配时，阅读对应的场景手册，按流程执行任务。
+
+- [查询会议及其产物](scenes/query-meeting-and-artifacts.md)：按主题、时间、参会人或 `meeting_id` / `meeting_no` / `event_id` 定位历史会议；查询参会人、录像和会议关联的智能纪要或妙记；基于会议记录总结或复盘。
+- [查询妙记及其产物](scenes/query-minutes-and-artifacts.md)：已有妙记 URL / `minute_token`，或按标题、所有者、参与者搜索妙记；读取总结、待办、章节、关键词、逐字稿，下载原始音视频，或查询关联智能纪要。
+- [生成和修改妙记、管理妙记权限](scenes/create-and-edit-minutes.md)：将本地音视频生成妙记、逐字稿、总结、待办或章节；修改妙记标题、总结、待办、关键词或说话人；申请妙记权限，或查看、分配妙记协作者权限。
+- [查询智能纪要及关联产物](scenes/query-note-and-artifacts.md)：已有 `note_id`、智能纪要 Docx URL/token，或需要查询纪要正文、逐字稿、妙记和共享文档等关联产物。
+- [应用机器人参会与会中互动](scenes/live-meeting-attend.md)：完整编排应用机器人的活跃会议发现、真实入会、事件拉取、文本/表情互动和明确授权后的离会。
+- [会中事件与会中互动](scenes/live-meeting-interact.md)：在不触发新的入会/离会操作时，使用用户身份或已在会中的应用身份查询活跃会议、查看发言/聊天/共享内容，或发送文本和表情。
+
+## 命令参考
+
+| 命令 | 用途 | 参考方式 |
+|---|---|---|
+| `vc +search` | 搜索历史会议 | [lark-vc-search](references/lark-vc-search.md) |
+| `vc +detail` | 查询会议信息及关联的 Note、Minutes 标识 | [lark-vc-detail](references/lark-vc-detail.md) |
+| `vc meeting get` | 查询会议基础信息和参会人快照 | `lark-cli vc meeting get --help` |
+| `vc +recording` | 从会议定位录制及妙记 | [lark-vc-recording](references/lark-vc-recording.md) |
+| `vc +meeting-list-active` | 发现当前可见的进行中会议 | [lark-vc-meeting-list-active](references/lark-vc-meeting-list-active.md) |
+| `vc +meeting-events` | 读取会中事件和共享内容 | [lark-vc-meeting-events](references/lark-vc-meeting-events.md) |
+| `vc +meeting-message-send` | 发送会中文本消息或表情 | [lark-vc-meeting-message-send](references/lark-vc-meeting-message-send.md) |
+| `vc +meeting-join` | 让应用机器人加入会议 | [lark-vc-agent-meeting-join](references/lark-vc-agent-meeting-join.md) |
+| `vc +meeting-leave` | 让应用机器人离开会议 | [lark-vc-agent-meeting-leave](references/lark-vc-agent-meeting-leave.md) |
+| `minutes +search` | 搜索妙记 | [lark-minutes-search](references/lark-minutes-search.md) |
+| `minutes minutes get` | 查询妙记基础信息 | `lark-cli minutes minutes get --help` |
+| `minutes +detail` | 读取妙记信息和指定产物 | [lark-minutes-detail](references/lark-minutes-detail.md) |
+| `minutes +download` | 下载妙记原始音视频 | [lark-minutes-download](references/lark-minutes-download.md) |
+| `minutes +upload` | 从云空间音视频生成妙记 | [lark-minutes-upload](references/lark-minutes-upload.md) |
+| `minutes +update` | 修改妙记标题 | [lark-minutes-update](references/lark-minutes-update.md) |
+| `minutes +speaker-replace` | 替换妙记逐字稿说话人 | [lark-minutes-speaker-replace](references/lark-minutes-speaker-replace.md) |
+| `minutes +summary` | 替换妙记 AI 总结 | [lark-minutes-summary](references/lark-minutes-summary.md) |
+| `minutes +todo` | 增删改妙记 AI 待办 | [lark-minutes-todo](references/lark-minutes-todo.md) |
+| `minutes +apply-permission` | 申请妙记查看或编辑权限 | [lark-minutes-apply-permission](references/lark-minutes-apply-permission.md) |
+| `drive +member-list` | 查看妙记协作者及其权限 | [lark-drive-member-list](../lark-drive/references/lark-drive-member-list.md) |
+| `drive +member-add` | 给指定成员分配妙记查看或编辑权限 | [lark-drive-member-add](../lark-drive/references/lark-drive-member-add.md) |
+| `minutes +word-replace` | 批量替换妙记逐字稿关键词 | `lark-cli minutes +word-replace --help` |
+| `note +detail` | 查询智能纪要及关联文档标识 | [lark-note-detail](references/lark-note-detail.md) |
+| `note +transcript` | 获取 unified 智能纪要逐字稿 | [lark-note-transcript](references/lark-note-transcript.md) |
+
+## 渐进加载规则
+
+按“快速行动 → 场景手册 → 命令参考”渐进加载：
+
+1. 用户目标符合“快速行动”的进入条件时，直接执行对应 CLI；不要预读场景手册、命令参考、`--help` 或 schema。
+2. 不符合快速行动条件，或缺少关键标识、需要消歧、涉及写操作时，读取与目标匹配的一个主场景手册；主场景明确转交到下游场景时，只继续读取被引用的场景或章节，并按其中流程执行 CLI。
+3. 仅当缺少具体参数、返回字段、特殊约束或异常处理方式时：有参考手册的命令读取对应文件；没有参考手册的命令运行表中列出的精确 `lark-cli ... --help`。场景或 reference 已给出精确命令时，不再调用 `--help`；仅在参数缺失、命令不识别或文档与运行结果冲突时调用。

package/skills/lark-meeting/references/lark-minutes-apply-permission.md

@@ -0,0 +1,92 @@
+# minutes +apply-permission
+
+向妙记所有者发起查看或编辑权限申请。**写操作**，只在用户明确要求申请权限时才调用；调用后不代表立即获得权限，只是提交了一条申请。
+
+本 skill 对应 shortcut：`lark-cli minutes +apply-permission`（调用 `POST /open-apis/minutes/v1/minutes/{minute_token}/permissions/apply`）。支持 `--as user` / `--as bot`。
+
+## 命令
+
+```bash
+# 以 user 身份申请查看权限
+lark-cli minutes +apply-permission --minute-token obcnxxxxxxxxxxxxxxxxxxxx --perm view --as user
+
+# 以 bot 身份申请编辑权限
+lark-cli minutes +apply-permission --minute-token obcnxxxxxxxxxxxxxxxxxxxx --perm edit --as bot
+
+# 预览 API 调用
+lark-cli minutes +apply-permission --minute-token obcnxxxxxxxxxxxxxxxxxxxx --perm view --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--minute-token <token>` | 是 | 妙记 Token |
+| `--perm <view\|edit>` | 是 | 申请的权限：`view`（查看）或 `edit`（编辑） |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## user / bot 身份与权限语义
+
+- **user**：以当前登录用户身份向妙记所有者申请。所有者在飞书客户端收到申请通知，同意后该用户获得对应权限。
+- **bot**：以应用身份向妙记所有者申请，代表"这个应用"而不是某个用户。同意后应用（bot）获得对应权限，不会让触发申请的用户本人获得权限。
+- 两种身份的申请互不代表：user 身份申请通过后 bot 仍然无权限，反之亦然。
+
+## 核心约束
+
+### 1. 必须继承触发无权限错误的来源身份
+
+`+apply-permission` 不是通用的"求权限"按钮：它申请的是**当前 `--as` 对应身份**的权限。如果是 `--as bot` 读取妙记时遇到无权限，就要用 `--as bot` 申请；如果是 `--as user` 遇到无权限，就用 `--as user` 申请。不要在申请时切换成另一个身份——那申请的是另一个主体的权限，解决不了原来那次调用的问题。
+
+### 2. missing scope 与资源 ACL 是两类不同问题
+
+- **missing scope**（当前身份完全没有 `minutes:permission:apply` / `minutes:minutes.basic:read` 等 scope）：这不是"没有这条妙记的权限"，`+apply-permission` 解决不了。`--as user` 用 `auth login --scope` 补权限；`--as bot` 去开发者后台开通，**禁止**对 bot 执行 `auth login`。完整规则见 [lark-shared](../../lark-shared/SKILL.md)。
+- **资源 ACL**（scope 都有，但对**这一条具体妙记**没有查看/编辑权限）：这才是 `+apply-permission` 要解决的场景。
+
+先看错误的 `error.subtype` 是 `missing_scope` 还是资源级别的权限拒绝，再决定要不要调用本命令。
+
+### 3. 只有用户明确要求才发起申请
+
+遇到无权限错误时，先把"当前身份对这条妙记没有权限"的事实告知用户；只有用户明确说"帮我申请查看/编辑权限"时才调用本命令。不要在检测到无权限后自动发起申请。
+
+### 4. 禁止通过切换身份绕过资源权限
+
+如果 `--as bot` 对某条妙记没有权限，不要改用 `--as user` 重新读取来"绕过"这个限制（除非用户明确同意切换身份继续任务）。申请权限和切换身份是两件不同的事：前者是解决 bot 自身权限不足，后者是换一个完全不同的主体去访问资源。
+
+## 所需权限
+
+| 身份 | 所需权限 |
+|------|---------|
+| user / bot | `minutes:permission:apply` |
+
+## 输出结果
+
+```json
+{
+  "minute_token": "obcnxxxxxxxxxxxxxxxxxxxx",
+  "perm": "view"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `minute_token` | 妙记 Token |
+| `perm` | 申请的权限（`view` / `edit`） |
+
+## 如何获取 minute_token
+
+| 来源 | 获取方式 |
+|------|---------|
+| 妙记 URL | 从 URL 末尾提取，如 `https://sample.feishu.cn/minutes/obcnxxxxxxxxxxxxxxxxxxxx` |
+| 妙记搜索 | `lark-cli minutes +search --query "关键词"` |
+| 会议产物查询 | `lark-cli vc +recording --meeting-ids <id>`，拿到 `minute_token`（沿用同一 `--as`） |
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| `--perm` 不是 `view`/`edit` | 参数值不合法 | 只能传 `view` 或 `edit` |
+| `missing required scope(s)` | 当前身份缺少 `minutes:permission:apply` | 见上方「missing scope 与资源 ACL」 |
+| 申请后仍无权限 | 所有者尚未同意 | 这是异步申请，需等待所有者处理；不代表命令执行失败 |
+
+## 相关场景
+- [生成和修改妙记](../scenes/create-and-edit-minutes.md)

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

@@ -0,0 +1,52 @@
+
+# minutes +detail
+
+通过 `minute_token` 查询妙记详情，按需获取 AI 产物（总结/待办/章节/逐字稿/关键词）。只读，支持 `--as user` / `--as bot`。
+
+`minute_token` 由某个身份取得时，本命令及后续 `note +detail`、`docs +fetch` 都必须显式沿用同一个 `--as`。
+
+> `--summary` / `--todo` / `--chapter` / `--keyword` / `--transcript` 都是可选项；请求相应产物时必须显式传入，不传任何产物 flag 时只返回基础信息（如 `title`），AI 产物字段都不会出现。一次性获取所有产物：`--summary --todo --chapter --keyword --transcript`。
+
+## 命令
+
+```bash
+# 仅基础信息
+lark-cli minutes +detail --as <source_identity> --minute-tokens obcxxxxxxxxxx
+
+# 批量（逗号分隔，最多 50 个）
+lark-cli minutes +detail --as <source_identity> --minute-tokens obcxxx,obcyyy --summary --todo
+
+# 全产物
+lark-cli minutes +detail --as <source_identity> --minute-tokens obcxxx --summary --todo --chapter --keyword --transcript
+
+# 仅逐字稿，覆盖已有文件，指定输出目录
+lark-cli minutes +detail --as <source_identity> --minute-tokens obcxxx --transcript --overwrite --output-dir ./out
+```
+
+## 输出
+
+`minutes` 数组每条含 `minute_token`、`title`、`note_id`、`artifacts`。`note_id` 仅在该妙记关联了会议纪要时返回，可直接传给 [`note +detail`](lark-note-detail.md) 拿纪要文档 token，无需再绕回 `vc +detail`。`artifacts` 中**只包含本次请求的产物**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `artifacts.summary` | string | AI 总结。 |
+| `artifacts.todos` | array | 待办事项列表。 |
+| `artifacts.chapters` | array | 章节列表。 |
+| `artifacts.keywords` | array | 关键词列表。 |
+| `artifacts.transcript_file` | string | 逐字稿本地文件路径。 |
+
+逐字稿默认落地 `./minutes/{minute_token}/transcript.txt`，与 `minutes +download` 同目录便于聚合。指定 `--output-dir <dir>` 时改写到 `<dir>/artifact-{title}-{minute_token}/transcript.txt`。
+
+## minute_token 来源
+
+| 来源 | 取值字段 |
+|------|---------|
+| 妙记 URL `https://*.feishu.cn/minutes/obcxxx` | 截路径最后一段 `obcxxx` |
+| `vc +detail --meeting-ids` | `minute_token` |
+| `vc +recording --meeting-ids` | `minute_token` |
+| `minutes +search` | `minute_token` |
+
+`minute_token` 不要直接传给 `note +detail`：需要关联 Note 时，先从本命令结果读取 `note_id`。跨产物流程由 [`query-minutes-and-artifacts`](../scenes/query-minutes-and-artifacts.md) 编排。
+
+## 相关场景
+- [查询妙记及其产物](../scenes/query-minutes-and-artifacts.md)

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

@@ -2,10 +2,12 @@
 # minutes +download
 
 
-下载妙记的音视频媒体文件到本地，或获取有效期 1 天的下载链接。只读操作。
+下载妙记的音视频媒体文件到本地，或获取有效期 1 天的下载链接。只读操作，支持 `--as user` / `--as bot`。
 
 本 skill 对应 shortcut：`lark-cli minutes +download`。
 
+`minute_token` 是在某个身份下解析出来的（如 `vc +recording --as bot`）：调用本命令时必须显式沿用同一个 `--as`，不要省略让身份被默认值悄悄换掉（完整规则见 [lark-shared](../../lark-shared/SKILL.md) 的「身份延续」）。
+
 ## 命令
 
 ```bash
@@ -119,17 +121,15 @@ API 限流 5 次/秒，批量下载时需注意控制频率。
 | 妙记尚未准备好 | 2091003 | 转写未完成 | 等待转写完成后重试 |
 | 资源已删除 | 2091004 | 妙记已被删除 | 确认妙记文件仍然存在 |
 | 权限不足 | 2091005 | 无阅读权限 | 检查是否有该妙记的访问权限 |
-| `missing required scope(s)` | — | 应用缺少权限 | 运行 `auth login --scope "minutes:minutes.media:export"` |
+| `missing required scope(s)` | — | 当前身份缺少 scope | `--as user`：运行 `auth login --scope "minutes:minutes.media:export"`；`--as bot`：使用错误中的 `console_url` 去开发者后台开通，**禁止**对 bot 执行 `auth login`（见 [lark-shared](../../lark-shared/SKILL.md) 的权限管理） |
 
 ## 提示
 
 - 音视频文件可能较大，下载无固定超时限制（由用户 Ctrl+C 控制取消）。
-- 默认落点 `./minutes/{minute_token}/` 与 `minutes +detail` 的逐字稿共享同一目录，方便 Agent 聚合同一会议的所有产物。
+- 默认落点 `./minutes/{minute_token}/` 与 `minutes +detail` 的逐字稿共享同一目录，方便 Agent 聚合同一妙记的原始音视频和逐字稿。
 - 单 token 模式下 `--output` 若传入已存在目录（如 `--output ./existing-dir`），等价于 `--output-dir`，文件落入该目录（cp 语义）。
 - 批量模式下 `--output` 不接受已存在的文件路径（会报错），应改用 `--output-dir`。
 - 如需获取妙记的纪要内容（逐字稿、AI 总结等），请使用 [minutes +detail](lark-minutes-detail.md)。
 
-## 参考
-
-- [lark-minutes](../SKILL.md) — 妙记全部命令
-- [lark-minutes-detail](lark-minutes-detail.md) — 妙记详情与 AI 产物查询
+## 相关场景
+- [查询妙记及其产物](../scenes/query-minutes-and-artifacts.md)

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-note → lark-meeting}/references/lark-note-transcript.md

@@ -2,8 +2,10 @@
 
 只在 `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
+lark-cli note +transcript --note-id <note_id>
 ```
 
 ## 行为契约
@@ -13,11 +15,5 @@ lark-cli note +transcript --note-id NOTE_ID
 - 默认保存到 `./notes/{note_id}/unified_transcript.md`；`--transcript-format plain_text` 时保存为 `.txt`。
 - 目标文件已存在时会失败；用户明确要覆盖时才加 `--overwrite`。
 
-## 何时不要用
-
-| 场景 | 正确路由 |
-|------|---------|
-| 只有纪要文档标题 | 先文档搜索，再 `docs +fetch`；有 `vc-node-id` 才回 Note 域 |
-| 只有 Docx URL / `doc_token` | 先 `docs +fetch`；不要从 `doc_token` 反推 `note_id` |
-| `note_display_type=normal` | `docs +fetch --doc <verbatim_doc_token>` |
-| `note_display_type=unknown` 且 `verbatim_doc_token` 非空 | 先按独立逐字稿文档读取 |
+## 相关场景
+- [基于 note_id 查询纪要、逐字稿、共享文档等](../scenes/query-note-and-artifacts.md)