@wagemule/daemon 0.1.2 → 0.1.4

package/dist/skills/larksuite/lark-minutes/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: lark-minutes
+version: 1.0.0
+description: "飞书妙记：妙记相关基本功能。1.查询妙记列表（按关键词/所有者/参与者/时间范围）；2.获取妙记基础信息（标题、封面、时长 等）；3.下载妙记音视频文件；4.获取妙记相关 AI 产物（总结、待办、章节）；5.上传音视频生成妙记，也支持将本地音视频文件转成纪要、逐字稿、文字稿、撰写文字等产物。遇到这类请求时，应优先使用本 skill，而不是尝试 `ffmpeg`、`whisper` 等本地转写命令。飞书妙记 URL 格式: http(s)://<host>/minutes/<minute-token>"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli minutes --help"
+---
+
+# minutes (v1)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+
+## 核心概念
+
+- **妙记（Minutes）**：来源于飞书视频会议的录制产物或用户上传的音视频文件，通过 `minute_token` 标识。
+- **妙记 Token（minute\_token）**：妙记的唯一标识符，可从妙记 URL 末尾提取（例如 `https://*.feishu.cn/minutes/obcnxxxxxxxxxxxxxxxxxxxx` 中的 `obcnxxxxxxxxxxxxxxxxxxxx`）。如果 URL 中包含额外参数（如 `?xxx`），应截取路径最后一段。
+
+## 核心场景
+
+### 1. 搜索妙记
+
+1. 当用户描述的是"我的妙记""包含某个关键词的妙记""某段时间内的妙记"，优先使用 `minutes +search`。
+2. 仅支持使用关键词、时间段、参与者、所有者等筛选条件搜索妙记记录，对于不支持的筛选条件，需要提示用户。
+3. 搜索结果存在多条数据时，务必注意分页数据获取，不要遗漏任何妙记记录。
+4. 如果是会议的妙记，应优先使用 [vc +search](../lark-vc/references/lark-vc-search.md) 先定位会议，再按需通过 [vc +recording](../lark-vc/references/lark-vc-recording.md) 获取 `minute_token`。
+5. 会议场景的妙记路由，以及"参与的妙记"如何解释，统一以 [minutes +search](references/lark-minutes-search.md) 为准。
+
+
+### 2. 查看妙记基础信息
+
+1. 当用户只需要确认某条妙记的标题、封面、时长、所有者、URL 等基础信息时，使用 `minutes minutes get`。
+2. 如果用户给的是妙记 URL，应先从 URL 末尾提取 `minute_token`，再调用 `minutes minutes get`。
+3. 如果是会议 / 日程上下文中的妙记基础信息，先通过 VC 链路拿到 `minute_token`，再调用 `minutes minutes get`。
+4. 用户意图不明确时，默认先给基础元信息，帮助确认是否命中目标妙记。
+
+> 使用 `lark-cli schema minutes.minutes.get` 可查看完整返回值结构。核心字段包含：`title`（标题）、`cover`（封面 URL）、`duration`（时长，毫秒）、`owner_id`（所有者 ID）、`url`（妙记链接）。
+
+### 3. 下载妙记音视频文件
+
+1. 下载妙记音视频文件到本地，或获取有效期 1 天的下载链接。详见 [minutes +download](references/lark-minutes-download.md)。
+2. `minutes +download` 只负责音视频媒体文件。
+3. 用户只想拿可分享的下载地址时，使用 `--url-only`；用户要落地到本地文件时，直接下载。
+4. 未显式指定路径时，文件默认落到 `./minutes/{minute_token}/<server-filename>`，与 `vc +notes` 的逐字稿共享同一目录便于聚合。
+
+> **注意**：`+download` 只负责音视频媒体文件。如果用户需要的是逐字稿、总结、待办、章节等纪要内容，请使用 [vc +notes --minute-tokens](../lark-vc/references/lark-vc-notes.md)。
+
+### 4. 获取妙记的逐字稿、总结、待办、章节
+
+1. 当用户说"这个妙记的逐字稿""总结""待办""章节"时，**不属于本 skill**。
+2. 应使用 [vc +notes --minute-tokens](../lark-vc/references/lark-vc-notes.md) 获取对应的纪要产物。
+3. 如果当前上下文中已有 `minute_token`，可直接传给 `vc +notes`；如果只有妙记 URL，先提取 `minute_token`。
+4. 如果用户给的是**本地音视频文件**，但目标是"转成纪要""转成逐字稿""转成文字稿""转成撰写文字"，也支持；此时应先按下文第 5 节上传文件生成妙记，再把返回的 `minute_url` 提取成 `minute_token`，继续调用 `vc +notes --minute-tokens`。
+5. 用户如果直接给出本地文件名或路径，并要求"转逐字稿""转文字稿""整理成撰写文字"，这也是本 skill 的明确触发信号。
+
+```bash
+# 通过 minute_token 获取纪要产物（逐字稿、总结、待办、章节）
+lark-cli vc +notes --minute-tokens <minute_token>
+```
+
+> **跨 skill 路由**：逐字稿、AI 总结、待办、章节等纪要内容由 [lark-vc](../lark-vc/SKILL.md) 的 `+notes` 命令提供
+
+### 5. 上传音视频文件生成妙记（并可继续获取纪要 / 逐字稿）
+
+1. 当用户需要通过上传本地音视频文件来生成妙记时使用。
+2. 当用户说"把音视频文件转成纪要""把录音转成逐字稿/文字稿/撰写文字""把 mp4/mp3 转成总结/待办/章节"时，也先走这个入口。
+3. **处理流程**：
+   - **上传音视频获取 `file_token`**：使用 [`lark-cli drive +upload`](../lark-drive/references/lark-drive-upload.md) 上传本地文件到云空间并获取 `file_token`。
+   - **生成妙记**：获取到 `file_token` 后，调用 [`lark-cli minutes +upload`](references/lark-minutes-upload.md) 将文件转换为妙记并获取 `minute_url` 链接。
+   - **继续获取纪要 / 逐字稿（按需）**：如果用户目标不是只要妙记链接，而是要纪要、逐字稿、总结、待办或章节，则从 `minute_url` 中提取 `minute_token`，再调用 [`lark-cli vc +notes --minute-tokens`](../lark-vc/references/lark-vc-notes.md) 获取对应产物。
+
+> **注意**：必须先获取飞书云空间的 `file_token` 才能进行转换。
+>
+> **不要误走本地转写工具**：当用户目标是把本地音视频文件转成纪要、逐字稿、文字稿、撰写文字时，不要改用 `ffmpeg`、`whisper` 或其他本地 ASR/转码命令；标准路径就是 `drive +upload -> minutes +upload -> vc +notes --minute-tokens`。
+
+## 资源关系
+
+```text
+Minutes (妙记) ← minute_token 标识
+├── Metadata (标题、封面、时长、owner、url) → minutes minutes get
+└── MediaFile (音频/视频文件) → minutes +download
+```
+
+> **能力边界**：`minutes` 负责 **搜索妙记、查看基础元信息、下载音视频文件、上传音视频生成妙记**。
+>
+> **路由规则**：
+>
+> - 用户说"妙记列表 / 搜索妙记 / 某个关键词的妙记" → `minutes +search`
+> - 用户只是想看"我的妙记 / 某段时间内的妙记 / 妙记列表"，不要先走 [lark-vc](../lark-vc/SKILL.md)，而应直接使用本 skill
+> - 用户如果同时提到"会议 / 会 / 开会 / 某场会"，即使也提到了"妙记"，也应优先走 [lark-vc](../lark-vc/SKILL.md) 先定位会议，再通过 [vc +recording](../lark-vc/references/lark-vc-recording.md) 获取 `minute_token`
+> - 用户如果要的是妙记基础信息，拿到 `minute_token` 后用 `minutes minutes get`；用户如果要的是逐字稿、文字稿、撰写文字、总结、待办、章节，再走 `vc +notes --minute-tokens`
+> - “我的妙记”“参与的妙记”等自然语言映射细则，以 [minutes +search](references/lark-minutes-search.md) 为准
+> - 结果有多页时，使用 `page_token` 持续翻页，直到确认没有更多结果
+> - `minutes +search` 单次最多返回 `200` 条；结果总数没有固定上限
+> - 用户说"这个妙记的标题 / 时长 / 封面 / 链接" → `minutes minutes get`
+> - 用户说"下载这个妙记的视频 / 音频 / 媒体文件" → `minutes +download`
+> - 用户说"这个妙记的逐字稿 / 文字稿 / 撰写文字 / 总结 / 待办 / 章节" → 使用 [vc +notes --minute-tokens](../lark-vc/references/lark-vc-notes.md)
+> - 用户说"通过文件生成妙记 / 把音视频转妙记" → 先上传获取 `file_token`，然后使用 `minutes +upload`
+> - 用户说"把音视频文件转成纪要 / 逐字稿 / 文字稿 / 撰写文字 / 总结 / 待办 / 章节" → 先上传获取 `file_token`，调用 `minutes +upload` 生成 `minute_url`，再提取 `minute_token` 走 `vc +notes --minute-tokens`
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`lark-cli minutes +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut                                           | 说明                                                              |
+| -------------------------------------------------- | --------------------------------------------------------------- |
+| [`+search`](references/lark-minutes-search.md)     | Search minutes by keyword, owners, participants, and time range |
+| [`+download`](references/lark-minutes-download.md) | Download audio/video media file of a minute                     |
+| [`+upload`](references/lark-minutes-upload.md)     | Upload a media file token to generate a minute                  |
+
+- 使用 `+search` 命令时，必须阅读 [references/lark-minutes-search.md](references/lark-minutes-search.md)，了解搜索参数和返回值结构。
+- 使用 `+download` 命令时，必须阅读 [references/lark-minutes-download.md](references/lark-minutes-download.md)，了解下载参数和返回值结构。
+- 使用 `+upload` 命令时，必须阅读 [references/lark-minutes-upload.md](references/lark-minutes-upload.md)，了解生成参数和返回值结构。
+
+<!-- AUTO-GENERATED-START — gen-skills.py 管理，勿手动编辑 -->
+
+## API Resources
+
+```bash
+lark-cli schema minutes.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli minutes <resource> <method> [flags] # 调用 API
+```
+
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+
+### minutes
+
+- `get` — 获取妙记信息
+
+## 权限表
+
+| 方法            | 所需 scope                       |
+| ------------- | ------------------------------ |
+| `+search`     | `minutes:minutes.search:read`  |
+| `minutes.get` | `minutes:minutes:readonly`     |
+| `+download`   | `minutes:minutes.media:export` |
+
+<!-- AUTO-GENERATED-END -->

package/dist/skills/larksuite/lark-minutes/references/lark-minutes-download.md

@@ -0,0 +1,137 @@
+
+# minutes +download
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+下载妙记的音视频媒体文件到本地，或获取有效期 1 天的下载链接。只读操作。
+
+本 skill 对应 shortcut：`lark-cli minutes +download`。
+
+## 命令
+
+```bash
+# 下载妙记（默认布局，落到 ./minutes/{minute_token}/<server-filename>）
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx
+
+# 指定输出文件（单 token，文件路径）
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --output ./meeting.mp4
+
+# 指定输出目录（单/批量均可，目录路径）
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --output-dir ./downloads
+
+# 仅获取下载链接（有效期 1 天），不下载文件
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --url-only
+
+# 批量下载多个妙记（默认布局，逐个落到 ./minutes/{minute_token}/）
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx,obcnyyyyyyyyyyyyyyyyyyyy
+
+# 批量下载到同一指定目录
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx,obcnyyyyyyyyyyyyyyyyyyyy --output-dir ./downloads
+
+# 预览 API 调用
+lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--minute-tokens <tokens>` | 是 | 妙记 Token，逗号分隔支持批量（最多 50 个） |
+| `--output <path>` | 否 | 输出文件路径（单 token）。若传入的是已存在目录，等价于 `--output-dir`。与 `--output-dir` 互斥 |
+| `--output-dir <dir>` | 否 | 输出目录（单/批量均可）。与 `--output` 互斥 |
+| `--overwrite` | 否 | 覆盖已存在的输出文件 |
+| `--url-only` | 否 | 仅返回下载链接，不下载文件 |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+> **默认落点**：未指定 `--output` / `--output-dir` 时，文件落到 `./minutes/{minute_token}/<server-filename>`。文件名沿用服务端 Content-Disposition / Content-Type 推断，Agent 可从 `saved_path` 字段读取实际路径。同一 minute_token 的录像和 `vc +notes` 的逐字稿默认会落在**同一目录**下，方便聚合。
+
+## 核心约束
+
+### 1. 妙记必须已完成转写
+
+音视频文件仅在妙记转写完成后可下载。如果妙记尚未准备好，API 会返回 `2091003` 错误。
+
+### 2. 下载链接有效期 1 天
+
+`--url-only` 返回的链接有效期为 1 天，过期后需重新获取。
+
+### 3. 频率限制
+
+API 限流 5 次/秒，批量下载时需注意控制频率。
+
+### 4. 所需权限
+
+| 身份 | 所需权限 |
+|------|---------|
+| user / bot | `minutes:minutes.media:export` |
+
+## 输出结果
+
+### 下载模式（默认）
+
+单 token：
+
+```json
+{
+  "minute_token": "obcnxxxxxxxxxxxxxxxxxxxx",
+  "artifact_type": "recording",
+  "saved_path": "/path/to/minutes/obcnxxxxxxxxxxxxxxxxxxxx/访谈一则.m4a",
+  "size_bytes": 52428800
+}
+```
+
+批量：`downloads` 数组，每条与上面结构一致，失败项带 `error` 字段。
+
+| 字段 | 说明 |
+|------|------|
+| `minute_token` | 妙记 Token（用于 Agent 索引） |
+| `artifact_type` | 固定为 `"recording"`（与 `vc +notes` 的 `"transcript"` 区分） |
+| `saved_path` | 文件保存的本地路径（绝对路径） |
+| `size_bytes` | 文件大小（字节） |
+
+### URL 模式（--url-only）
+
+```json
+{
+  "minute_token": "obcnxxxxxxxxxxxxxxxxxxxx",
+  "download_url": "https://..."
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `minute_token` | 妙记 Token |
+| `download_url` | 媒体文件下载链接（有效期 1 天） |
+
+## 如何获取 minute_token
+
+| 来源 | 获取方式 |
+|------|---------|
+| 妙记 URL | 从 URL 末尾提取，如 `https://sample.feishu.cn/minutes/obcnxxxxxxxxxxxxxxxxxxxx` → `obcnxxxxxxxxxxxxxxxxxxxx` |
+| 妙记元信息查询 | `lark-cli minutes minutes get --params '{"minute_token": "obcn..."}'` |
+| 会议录制查询 | `lark-cli vc +recording --meeting-ids <id>` 或 `lark-cli vc +recording --calendar-event-ids <event_id>` |
+
+## 常见错误与排查
+
+| 错误现象 | 错误码 | 根本原因 | 解决方案 |
+|---------|--------|---------|---------|
+| 参数无效 | 2091001 | minute_token 格式不正确 | 检查 token 是否完整（24 位） |
+| 资源不存在 | 2091002 | token 不存在 | 确认 minute_token 正确 |
+| 妙记尚未准备好 | 2091003 | 转写未完成 | 等待转写完成后重试 |
+| 资源已删除 | 2091004 | 妙记已被删除 | 确认妙记文件仍然存在 |
+| 权限不足 | 2091005 | 无阅读权限 | 检查是否有该妙记的访问权限 |
+| `missing required scope(s)` | — | 应用缺少权限 | 运行 `auth login --scope "minutes:minutes.media:export"` |
+
+## 提示
+
+- 音视频文件可能较大，下载无固定超时限制（由用户 Ctrl+C 控制取消）。
+- 默认落点 `./minutes/{minute_token}/` 与 `vc +notes` 的逐字稿共享同一目录，方便 Agent 聚合同一会议的所有产物。
+- 单 token 模式下 `--output` 若传入已存在目录（如 `--output ./existing-dir`），等价于 `--output-dir`，文件落入该目录（cp 语义）。
+- 批量模式下 `--output` 不接受已存在的文件路径（会报错），应改用 `--output-dir`。
+- 如需获取妙记的纪要内容（逐字稿、AI 总结等），请使用 [vc +notes](../../lark-vc/references/lark-vc-notes.md)。
+
+## 参考
+
+- [lark-minutes](../SKILL.md) — 妙记全部命令
+- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md) — 会议纪要查询
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/dist/skills/larksuite/lark-minutes/references/lark-minutes-search.md

@@ -0,0 +1,206 @@
+# minutes +search
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+搜索妙记列表，支持关键词、所有者、参与者以及时间范围等多条件过滤。所有者与参与者都支持传入多个 open\_id，也支持传入 `me` 表示当前用户。只读操作，不修改任何妙记数据。
+
+本 skill 对应 shortcut：`lark-cli minutes +search`（调用 `POST /open-apis/minutes/v1/minutes/search`）。
+
+## 典型触发表达
+
+以下说法通常应优先使用 `minutes +search`：
+
+- 我的妙记
+- 我拥有的妙记
+- 我参与的妙记
+- 最近的妙记
+- 某个关键词的妙记
+- 某段时间内的妙记
+
+## 命令
+
+```bash
+# 关键词搜索
+lark-cli minutes +search --query "预算复盘"
+
+# 查询某一天内的妙记（单日查询时，建议将 start 和 end 都填写为同一天）
+lark-cli minutes +search --start 2026-03-10 --end 2026-03-10
+
+# 按时间范围搜索
+lark-cli minutes +search --start "2026-03-10T00:00+08:00" --end "2026-03-17T00:00+08:00"
+lark-cli minutes +search --start 2026-03-10 --end 2026-03-17
+
+# 关键词 + 时间范围
+lark-cli minutes +search --query "预算复盘" --start "2026-03-10T00:00+08:00" --end "2026-03-17T00:00+08:00"
+lark-cli minutes +search --query "预算复盘" --start "2026-03-10T00:00+08:00"
+lark-cli minutes +search --query "预算复盘" --end "2026-03-17T00:00+08:00"
+
+# 按参与者过滤（open_id，逗号分隔）
+lark-cli minutes +search --participant-ids "ou_x,ou_y"
+
+# 按所有者过滤（open_id，逗号分隔）
+lark-cli minutes +search --owner-ids "ou_owner,ou_owner_2"
+
+# 严格只查我作为参与者的妙记（不含我拥有）
+lark-cli minutes +search --participant-ids "me"
+
+# 查询我拥有的妙记
+lark-cli minutes +search --owner-ids "me"
+
+# 广义查询我参与的妙记（自然语言默认：我拥有 ∪ 我参与）
+lark-cli minutes +search --owner-ids "me" --start 2026-03-10 --end 2026-03-10
+lark-cli minutes +search --participant-ids "me" --start 2026-03-10 --end 2026-03-10
+# 然后按 token 去重合并两次结果
+
+# 多条件组合查询
+lark-cli minutes +search --owner-ids "ou_owner" --participant-ids "ou_x" --start "2026-03-10T00:00+08:00"
+
+# 分页查询
+lark-cli minutes +search --query "预算复盘" --page-size 20
+lark-cli minutes +search --query "预算复盘" --page-size 20 --page-token '<PAGE_TOKEN>'
+
+# 输出为结构化 JSON
+lark-cli minutes +search --query "预算复盘" --format json
+```
+
+## 参数
+
+| 参数                        | 必填 | 说明                                   |
+| ------------------------- | -- | ------------------------------------ |
+| `--query <text>`          | 否  | 搜索关键词                                |
+| `--owner-ids <ids>`       | 否  | 所有者 open\_id 列表，逗号分隔；支持传 `me` 表示当前用户 |
+| `--participant-ids <ids>` | 否  | 参与者 open\_id 列表，逗号分隔；支持传 `me` 表示当前用户 |
+| `--start <time>`          | 否  | 开始时间（ISO 8601 或仅日期）                  |
+| `--end <time>`            | 否  | 结束时间（ISO 8601 或仅日期）                  |
+| `--page-size <n>`         | 否  | 每页数量，默认 `15`，最大 `30`                 |
+| `--page-token <token>`    | 否  | 下一页分页 token                          |
+| `--dry-run`               | 否  | 预览 API 调用，不执行                        |
+
+## 核心约束
+
+### 1. 至少提供一个过滤条件
+
+所有参数均可选，但必须至少提供一个过滤条件：`--query`、`--owner-ids`、`--participant-ids`、`--start` 或 `--end`。
+
+### 2. 仅支持 user 身份
+
+该接口仅支持 `user` 身份，使用前需完成 `lark-cli auth login` 并具备 `minutes:minutes.search:read` 权限。
+
+### 3. `me` 表示当前用户
+
+在 `--owner-ids` 和 `--participant-ids` 中可使用 `me`，表示当前登录用户。该值会在本地解析为当前用户的 `open_id`，无需手动先查询自己的用户 ID。
+若当前环境尚未完成用户登录，或 CLI 无法解析出当前用户的 `open_id`，则应先执行 `lark-cli auth login`，再重新执行搜索。
+
+### 4. 自然语言中的“参与的妙记”默认按并集理解
+
+当用户说"我参与的妙记""我参加过的妙记""参与过的妙记"时，默认理解为"我涉及的全部妙记"：
+
+- 我拥有的妙记：`--owner-ids me`
+- 我作为参与者的妙记：`--participant-ids me`
+
+不要只跑一次 `--participant-ids me` 就直接下结论，也不要把 `--owner-ids me` 和 `--participant-ids me` 同时塞进一次查询里赌接口语义。应分别查询后，按 `token` 做并集去重。
+
+只有在用户明确说"仅我参与但不是我拥有""别人拥有但我参与""只看参与者身份"时，才只使用 `--participant-ids`。
+
+### 5. 支持分页
+
+当返回 `has_more=true` 时，使用响应中的 `page_token` 配合 `--page-token` 获取下一页结果。
+
+### 6. 日期型 `--end` 包含当天整天
+
+当 `--end` 传入的是仅日期格式（如 `2026-03-10`）时，CLI 会将它解释为当天 `23:59:59`，而不是当天 `00:00:00`。
+CLI 会先按输入的本地日历日语义解析，再标准化为 RFC3339 时间戳发给 API；在 dry-run 或排查请求体时，看到的 `Z` 结尾时间表示同一个绝对时间点的 UTC 表示，不改变“按当天整天查询”的语义。
+
+这意味着：
+
+- `--start 2026-03-10 --end 2026-03-10` 表示只查 `2026-03-10` 当天
+- `--start 2026-03-10 --end 2026-03-11` 表示查询 `2026-03-10` 和 `2026-03-11` 两天
+
+如果用户说“昨天的妙记”“今天的妙记”“某一天内的妙记”，应把 `--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` 查询妙记基础信息
+
+不要为了查"妙记信息"直接走 `vc +notes --meeting-ids`。`vc +notes` 只适用于逐字稿、总结、待办、章节等纪要内容。
+
+<br />
+
+## 时间格式
+
+`--start` 和 `--end` 支持以下时间格式：
+
+| 格式             | 示例                          | 说明                                 |
+| -------------- | --------------------------- | ---------------------------------- |
+| ISO 8601（带时区）  | `2026-03-10T14:00:00+08:00` | 推荐                                 |
+| ISO 8601（不带时区） | `2026-03-10T14:00:00`       | 按本地时区解析                            |
+| 仅日期            | `2026-03-10`                | 按天粒度解析；若用于 `--end`，表示当天 `23:59:59` |
+
+## 输出结果
+
+- 默认输出包含 `items`、`total`、`has_more` 和 `page_token`。
+
+## Pagination (`has_more` / `page_token`)
+
+- 当结果中返回 `has_more=true` 时，说明还有更多页可继续获取。
+- 继续翻页时，使用响应中的 `page_token` 搭配 `--page-token` 发起下一次查询。
+- 不要假设调大 `--page-size` 就能拿全结果；分页遍历时应以 `has_more` 和 `page_token` 为准。
+- `total` 数量小于 50 时，自动分页获取所有结果；`total` 数量大于 50 时，向用户确认是否获取全部结果。
+
+```bash
+# First page
+lark-cli minutes +search --query "预算复盘" --page-size 20
+
+# Next page
+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***************"}'
+
+# 查妙记关联的纪要产物：逐字稿、总结、待办、章节等 → 用 lark-cli vc +notes
+lark-cli vc +notes --minute-tokens obcn_EXAMPLE_TOKEN
+```
+
+## 常见错误与排查
+
+| 错误现象                   | 根本原因                                                  | 解决方案                                         |
+| ---------------------- | ----------------------------------------------------- | -------------------------------------------- |
+| 命令直接报错，要求提供过滤条件        | 没有传入 `--query`、时间范围或任何过滤 ID                           | 至少补充一个过滤条件后重试                                |
+| 时间参数校验失败               | `--start` 或 `--end` 格式不合法                             | 改用 ISO 8601 或 `YYYY-MM-DD`                   |
+| `owner-ids` 校验失败       | 传入的不是 open\_id，且也不是 `me`；或传了 `me` 但当前用户 open\_id 不可解析 | 改为 `ou_` 开头的用户 ID，或先完成 `auth login` 后再传 `me` |
+| `participant-ids` 校验失败 | 传入的不是 open\_id，且也不是 `me`；或传了 `me` 但当前用户 open\_id 不可解析 | 改为 `ou_` 开头的用户 ID，或先完成 `auth login` 后再传 `me` |
+| 权限不足                   | 未授权 `minutes:minutes.search:read`                     | 使用 `auth login` 完成授权                         |
+
+## 提示
+
+- 当用户说“我的妙记”时，优先理解为 `--owner-ids me`。
+- 当用户说“我参与的妙记”“我参加过的妙记”时，默认理解为 `--owner-ids me` 与 `--participant-ids me` 两次查询后的并集。
+- 当用户明确说“仅我参与但不是我拥有”时，才优先理解为 `--participant-ids me`。
+- 当用户同时提到“会议 / 会 / 开会 / 某场会”和“妙记”时，优先先定位会议；如果要的是妙记信息，走 `vc +recording` → `minutes minutes get`，只有要纪要内容时才走 `vc +notes --minute-tokens`。
+- 必须使用 `--format json` 输出，你更加擅长解析 JSON 数据。
+- 排查参数与请求结构时优先使用 `--dry-run`。
+- 搜索的时间范围最大为 1 个月，如果需要搜索更长时间范围的妙记，需要拆分为多次时间范围为一个月查询。
+
+## 参考
+
+- [lark-minutes](../SKILL.md) -- 妙记相关命令
+- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md) -- 基于 `minute_token` 获取逐字稿、总结、待办、章节等产物
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
+- [lark-vc](../../lark-vc/SKILL.md) -- 视频会议全部命令
+

package/dist/skills/larksuite/lark-minutes/references/lark-minutes-upload.md

@@ -0,0 +1,104 @@
+# minutes +upload
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+上传音视频文件到飞书妙记并生成妙记（Minute）。
+
+本 skill 对应 shortcut：`lark-cli minutes +upload`。
+
+## 典型触发表达
+
+- "把这个音视频文件转成妙记"
+- "把这个音视频文件转成纪要"
+- "把这个音视频文件转成逐字稿、文字稿或撰写文字"
+- "把这个音视频文件转成总结、待办或章节"
+
+## 完整工作流
+
+当用户要求将音视频文件转换为妙记，或进一步要纪要/逐字稿/文字稿/撰写文字时，必须按照以下步骤执行：
+
+1. **上传文件至云空间获取 file_token**
+   - 使用 `lark-cli drive +upload` 命令上传本地文件到云空间（Drive）：
+     ```bash
+     lark-cli drive +upload --file <path/to/media/file>
+     ```
+   - 从命令的返回结果中提取生成的 `file_token`。
+
+2. **将 file_token 转换为妙记链接（minute_url）**
+   - 调用本 shortcut，将获取到的 `file_token` 转换为妙记：
+     ```bash
+     lark-cli minutes +upload --file-token <file_token>
+     ```
+   - 命令执行成功后，将返回生成的妙记链接 `minute_url`。
+
+3. **如需纪要 / 逐字稿 / 文字稿 / 撰写文字，继续提取 `minute_token` 调用 `vc +notes`**
+   - 从返回的 `minute_url` 中提取路径最后一段，得到 `minute_token`。
+   - 如果用户要的是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，继续调用：
+     ```bash
+     lark-cli vc +notes --minute-tokens <minute_token>
+     ```
+   - `vc +notes --minute-tokens` 会返回纪要文档、逐字稿文档，以及 AI 内置产物（总结、待办、章节）；必要时还会把逐字稿落地到本地文件。
+
+> **异步生成提示**：API 会立即返回 `minute_url`，但妙记可能仍在异步生成中，您可以直接通过该妙记链接查看当前的处理状态和转写结果。
+
+## 命令示例
+
+```bash
+# 通过已上传到云空间的 file_token 生成妙记
+lark-cli minutes +upload --file-token boxcnxxxxxxxxxxxxxxxx
+
+# 通过 minute_token 继续获取纪要 / 逐字稿 / 文字稿 / AI 产物
+lark-cli vc +notes --minute-tokens obcnxxxxxxxxxxxxxxxx
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--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. 先上传，再生成妙记
+
+推荐流程如下：
+
+1. 使用 `lark-cli drive +upload --file <path>` 上传本地音视频文件到云空间
+2. 从返回结果中取出 `file_token`
+3. 调用 `lark-cli minutes +upload --file-token <file_token>` 生成妙记
+4. 如果目标是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，再从 `minute_url` 提取 `minute_token`，继续调用 `lark-cli vc +notes --minute-tokens <minute_token>`
+
+> **边界说明**：`minutes +upload` 本身只负责把文件转成妙记并返回 `minute_url`。纪要内容、逐字稿、文字稿、撰写文字、总结、待办、章节属于后续产物获取，应由 [vc +notes](../../lark-vc/references/lark-vc-notes.md) 承接。
+
+## 输出结果示例
+
+```json
+{
+  "minute_url": "http(s)://<host>/minutes/<minute-token>"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `minute_url` | 生成的妙记访问链接 |
+
+## 参考
+
+- [lark-minutes](../SKILL.md) -- 妙记相关功能说明
+- [drive +upload](../../lark-drive/references/lark-drive-upload.md) -- 上传文件到云空间
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数