@yandy0725/pi-lark 0.1.0

package/skills/lark-minutes/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: lark-minutes
+version: 1.0.0
+description: "飞书妙记：搜索妙记、查看妙记基础信息、下载/上传音视频、读取或编辑妙记的产物内容、改标题、替换说话人/关键词。当给出minute_token、本地音视频文件，要查/改/转妙记产物时使用；本地音视频转纪要/逐字稿优先走本 skill，不要用 ffmpeg/whisper 本地转写。不负责：获取会议关联妙记，或仅按自然语言标题定位纪要"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli minutes --help"
+---
+
+# minutes (v1)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-vc/references/vc-domain-boundaries.md`](../lark-vc/references/vc-domain-boundaries.md)**，不读将导致命令使用、会议产物决策、领域边界职责判断错误：
+> 1. 了解日历 & VC、会议产物 & 文档的关联关系和职责划分
+> 2. 了解会议产物（妙记和纪要）之间的关联关系，例如：**妙记和纪要产生条件相互独立**
+> 3. 了解不同会议产物的组成部分，以便根据需求决策使用哪种产物的数据
+> 4. 了解会议总结、分析和信息提取的标准流程
+
+## 身份
+
+所有 minutes 命令默认使用 `--as user`。
+
+## Shortcuts
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+search`](references/lark-minutes-search.md) | 按关键词、所有者、参与者、时间范围搜索妙记 |
+| [`+detail`](references/lark-minutes-detail.md) | 查询妙记详情(标题和关联的纪要note_id)，按需获取 AI 产物（总结、待办、章节、逐字稿、关键词） |
+| [`+download`](references/lark-minutes-download.md) | 下载妙记音视频媒体文件 |
+| [`+upload`](references/lark-minutes-upload.md) | 上传 file_token 生成妙记 |
+| [`+update`](references/lark-minutes-update.md) | 更新妙记标题 |
+| [`+speaker-replace`](references/lark-minutes-speaker-replace.md) | 替换妙记逐字稿中的说话人（须先 `lark-cli api GET .../speakerlist` 取 `speaker_id`） |
+| `+word-replace` | 批量替换逐字稿关键词（详见 `lark-cli minutes +word-replace --help`） |
+| [`+summary`](references/lark-minutes-summary.md) | 替换妙记 AI 总结全文 |
+| [`+todo`](references/lark-minutes-todo.md) | 新建/更新/删除妙记 AI 待办（单条或 `--todos` 批量；不是 lark-task） |
+
+- 使用任何 Shortcut 前，必须先读其对应 reference 文档。
+
+## 意图路由
+
+| 用户意图 | 命令 |
+|---------|------|
+| 我的妙记 / 搜索妙记 / 某段时间的妙记 | `+search` |
+| 妙记基础信息：标题 / 时长 / 封面 / 链接 | `minutes get` |
+| 下载妙记音视频文件、获取媒体下载链接 | `+download`（仅媒体；要妙记内容用 `+detail`） |
+| 妙记总结 / 章节 / 待办 / 关键词 / 逐字稿 | `+detail --minute-tokens <token>` + 显式产物 flag |
+| 基于妙记**提炼/总结/分析/回顾**会议 | `+detail --minute-tokens <token> --transcript`，再独立分析（**禁止照搬 AI 总结**） |
+| 拿这条妙记关联的纪要文档（`note_doc_token` / `verbatim_doc_token` / `shared_doc_tokens`） | `+detail` 取顶层 `note_id` → [`note +detail --note-id`](../lark-note/SKILL.md) |
+| 把本地音视频转纪要 / 逐字稿 / 文字稿 | `drive +upload` 取 `file_token` → `+upload` 生成 `minute_url` → `+detail` 拿产物 |
+| 在妙记里增加 / 更改 / 删除 AI 待办 | `+todo`（**禁止走 lark-task**） |
+| 替换妙记的AI 总结 | `+summary` |
+| 重命名妙记/改妙记标题 | `+update` |
+| 替换说话人/把 A 的发言改成 B/重新归属发言人/把外部（非飞书）说话人改成飞书用户" | 先 `lark-cli api GET .../transcript/speakerlist` 取 `speaker_id`，再 [`minutes +speaker-replace`](references/lark-minutes-speaker-replace.md)；`--from-speaker-id` 只传 id，不传展示名 |
+| 批量替换逐字稿关键词 | `+word-replace` |
+| 用户同时提到"会议/开会"和"妙记" | 先 [lark-vc](../lark-vc/SKILL.md)（`+search` → `+recording`）获取 `minute_token`，再本 skill |
+
+## 核心概念
+
+- **妙记（Minutes）**：来源于飞书视频会议的录制产物或用户上传的音视频文件，通过 `minute_token` 标识。
+- **妙记 Token（minute_token）**：妙记的唯一标识符，可从妙记 URL 末尾提取（如 `https://*.feishu.cn/minutes/obcnxxx` 中的 `obcnxxx`）。如果 URL 中包含额外参数（如 `?xxx`），截取路径最后一段。
+
+## 核心场景
+
+### 1. 搜索妙记
+
+1. 如果是会议的妙记，应优先通过 [lark-vc](../lark-vc/SKILL.md) 定位会议并获取 `minute_token`。
+2. 会议场景的妙记路由，以及"参与的妙记"如何解释，统一以 [minutes +search](references/lark-minutes-search.md) 为准。
+
+
+### 2. 查看妙记基础信息
+
+1. 当用户只需要确认某条妙记的标题、封面、时长、所有者、URL 等基础信息时，使用 `minutes minutes get`。
+2. 如果是会议 / 日程上下文中的妙记基础信息，先通过 VC/Calendar 链路拿到 `minute_token`，再调用 `minutes minutes get`。
+3. 用户意图不明确时，默认先给基础元信息，帮助确认是否命中目标妙记。
+
+
+### 3. 上传音视频文件生成妙记（并可继续获取纪要 / 逐字稿）
+
+1. 当用户说"把音视频文件转成纪要""把录音转成逐字稿/文字稿/撰写文字""把 mp4/mp3 转成总结/待办/章节"时，也先走这个入口。
+2. **处理流程**：
+   - **上传音视频获取 `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 minutes +detail --minute-tokens`](references/lark-minutes-detail.md) 获取对应产物。
+
+> **注意**：必须先获取飞书云空间（云盘/云存储）的 `file_token` 才能进行转换。
+>
+> **不要误走本地转写工具**：当用户目标是把本地音视频文件转成纪要、逐字稿、文字稿、撰写文字时，不要改用 `ffmpeg`、`whisper` 或其他本地 ASR/转码命令；标准路径就是 `drive +upload -> minutes +upload -> minutes +detail --minute-tokens`。
+
+### 5. 编辑妙记的 AI 待办与 AI 总结（写入）
+
+当用户要在**某条妙记内**操作 AI 待办或 AI 总结时使用本节。**不是**飞书任务（Task）清单里的待办。
+
+**触发信号（任一命中即走本 skill，禁止走 lark-task）**：
+
+- "在（某条）妙记里新建 / 添加 / 修改 / 删除待办"
+- "把妙记 A 的待办改成已完成 / 未完成"
+- "妙记里的任务1 / 任务2"（上下文已明确是妙记）
+- 已给出 `minute_token` 或妙记 URL，且要改待办 / 总结
+
+**妙记 AI 待办 vs 飞书任务 Task**：
+
+| 用户意图 | 正确命令 | 错误命令 |
+|---------|---------|---------|
+| 妙记里加待办 | `minutes +todo --operation add` 或 `--todos '[...]'` | `task +create` / `task tasklists list` |
+| 妙记里改待办 | `minutes +todo --operation update --todo-id ...` | `task +update` |
+| 妙记里删待办 | `minutes +todo --operation delete --todo-id ...` | `task tasks delete` |
+| 我的任务清单 | — | 走 [lark-task](../lark-task/SKILL.md) |
+
+**新建多条待办**：优先用 `--todos` 一次提交；单条则用多次 `--operation add`：
+
+```bash
+# 批量：任务1 已完成 + 任务2 未完成
+lark-cli minutes +todo --minute-token <token> --as user --todos '[
+  {"operation":"add","content":"晚上好1","is_done":true},
+  {"operation":"add","content":"晚上好2","is_done":false}
+]'
+```
+
+**更新 / 删除前**：先用 `minutes +detail --minute-tokens <token> --todo` 读取 `todos[].todo_id`（按 `content` 匹配目标条目；列表顺序不保证稳定，**不要**用"第 2 条"代替 `todo_id`）。
+
+**无编辑权限**：若 CLI 返回 `error.type=no_edit_permission`，表示对**这条妙记**没有编辑权，应请所有者授权；**不要**误走 `auth login --scope`。
+
+**逐字稿关键词替换无命中**：`minutes +word-replace` 时，若 CLI 返回 `error.type=words_not_found`，表示传入的 `source_word` 在该妙记逐字稿中**一个都没匹配到**，未做任何替换。这是**参数问题不是权限问题**：先用 `minutes +detail --minute-tokens <token> --transcript` 读取当前逐字稿，核对 `source_word` 的精确写法与大小写后重试。
+
+**替换 AI 总结全文**：见 [minutes +summary](references/lark-minutes-summary.md)。
+
+> 使用 `+todo` 前必须阅读 [references/lark-minutes-todo.md](references/lark-minutes-todo.md)；使用 `+summary` 前必须阅读 [references/lark-minutes-summary.md](references/lark-minutes-summary.md)。
+
+### 7. 替换妙记逐字稿说话人
+
+当用户要把妙记里某说话人的发言改绑到另一位飞书用户时使用。
+
+**触发信号**：「替换说话人」「把 A 的发言改成 B」「说话人识别错了」「把外部说话人改成飞书用户」等。
+
+**Agent 必读流程**（详见 [minutes +speaker-replace](references/lark-minutes-speaker-replace.md)）：
+
+1. 确认 `minute_token`。
+2. **先**用 `lark-cli api GET "/open-apis/minutes/v1/minutes/<token>/transcript/speakerlist"` 查说话人列表（内部 HTTP，无 shortcut、无公开 OpenAPI 文档页）。
+3. 根据用户描述的原说话人展示名，在返回的 `data.speakers[]` 中匹配 `name` → 得到 `speaker_id`；同名多人时结合 `vc +notes` 逐字稿请用户确认，**不要擅自挑选**。
+4. 新说话人姓名用 [lark-contact](../lark-contact/SKILL.md) 解析为 `ou_` open_id。
+5. 调用 `minutes +speaker-replace`，**`--from-speaker-id` 只传步骤 3 的 `speaker_id`，禁止传展示名**。
+
+## 行为规则
+
+### 1. `+detail` 必须显式声明产物 flag
+
+不传 `--summary` / `--todo` / `--chapter` / `--keyword` / `--transcript` 时只返回基础信息（含顶层 `note_id`），AI 产物字段一律不返回。即使产物为空也会返回空值字段，便于程序化处理。
+
+```bash
+# 拿全产物
+lark-cli minutes +detail --minute-tokens <token> --summary --todo --chapter --keyword --transcript
+```
+
+### 2. "提炼 / 总结"必须基于 Transcript，不要照搬 AI 总结
+
+AI 总结是模型对会议的二次压缩，可能遗漏争论过程和隐含决策。用户要求"提炼"或"重新总结"时，期望基于原始发言独立分析，而非搬运 AI 产物。**优先 `--transcript`，再独立写结论**。
+
+### 3. 从妙记反查纪要：不绕 lark-vc
+
+`minutes +detail` 顶层直接返回 `note_id`（仅在该妙记关联纪要时存在）。不需要绕回 [lark-vc](../lark-vc/SKILL.md)，直接：
+
+```bash
+# 1) 取 note_id（顶层 .minutes[0].note_id）
+lark-cli minutes +detail --minute-tokens <minute_token> --format json
+# 2) 用上一步拿到的 note_id 读纪要 token
+lark-cli note +detail --note-id <note_id>   # 拿 note_doc_token / verbatim_doc_token / shared_doc_tokens
+```
+
+顶层无 `note_id` 字段即代表无关联纪要，到此为止——不要继续尝试用 `minute_token` 当 `note_id`。
+
+
+## API Resources
+
+```bash
+lark-cli minutes <resource> <method> [flags]
+```
+
+### minutes
+
+- `get` — 获取妙记信息
+
+> **权限错误**：如果返回 `[2091005] permission deny`，表示用户没有对应妙记文件的阅读权限，需提示用户联系妙记 owner 申请权限。
+
+## 不在本 skill 范围
+
+- 搜索历史会议记录、查参会人快照 → [lark-vc](../lark-vc/SKILL.md)
+- 未来日程 / 日历查询 → [lark-calendar](../lark-calendar/SKILL.md)
+- 已知 `note_id` 直接读纪要详情 → [lark-note](../lark-note/SKILL.md)
+- 飞书任务清单（个人 Todo / 共享清单） → [lark-task](../lark-task/SKILL.md)
+- 只有自然语言纪要标题、没有 `minute_token` / 妙记 URL / 本地音视频时定位逐字稿 → 文档搜索（[lark-drive](../lark-drive/SKILL.md) / [lark-doc](../lark-doc/SKILL.md)）

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

@@ -0,0 +1,62 @@
+
+# minutes +detail
+
+通过 `minute_token` 查询妙记详情，按需获取 AI 产物（总结/待办/章节/逐字稿/关键词）。只读。
+
+> `--summary` / `--todo` / `--chapter` / `--keyword` / `--transcript` 至少一个；不传任何产物 flag 时只返回基础信息（如 `title`），AI 产物字段都不会出现。一次性获取所有产物：`--summary --todo --chapter --keyword --transcript`。
+
+## 命令
+
+```bash
+# 仅基础信息
+lark-cli minutes +detail --minute-tokens obcxxxxxxxxxx
+
+# 批量（逗号分隔，最多 50 个）
+lark-cli minutes +detail --minute-tokens obcxxx,obcyyy --summary --todo
+
+# 全产物
+lark-cli minutes +detail --minute-tokens obcxxx --summary --todo --chapter --keyword --transcript
+
+# 仅逐字稿，覆盖已有文件，指定输出目录
+lark-cli minutes +detail --minute-tokens obcxxx --transcript --overwrite --output-dir ./out
+```
+
+## 输出
+
+`minutes` 数组每条含 `minute_token`、`title`、`note_id`、`artifacts`。`note_id` 仅在该妙记关联了会议纪要时返回，可直接传给 [`note +detail`](../../lark-note/references/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 拿纪要文档 token
+
+只持有 `minute_token`（如妙记 URL 入口），又想拿 AI 智能纪要 / 逐字稿文档时：
+
+```bash
+# 1. 取妙记关联的 note_id，没有关联会议纪要则为空
+lark-cli minutes +detail --minute-tokens <minute_token>
+
+# 2. 用 note_id 拿 note_doc_token / verbatim_doc_token / shared_doc_tokens
+lark-cli note +detail --note-id <note_id>
+
+# 3. 读纪要 / 逐字稿正文
+lark-cli docs +fetch --api-version v2 --doc <note_doc_token> --doc-format markdown
+```
+
+> `minute_token` 不要直接传给 `note +detail`：必须先用本命令拿到 `note_id` 再调用 `note +detail`。

package/skills/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 的录像和 `minutes +detail` 的逐字稿默认会落在**同一目录**下，方便聚合。
+
+## 核心约束
+
+### 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"`（与 `minutes +detail` 的 `"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}/` 与 `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 产物查询
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -0,0 +1,204 @@
+# 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` 查询妙记基础信息
+
+<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`、`has_more` 和 `page_token`。
+
+## Pagination (`has_more` / `page_token`)
+
+- 当结果中返回 `has_more=true` 时，说明还有更多页可继续获取。
+- 继续翻页时，使用响应中的 `page_token` 搭配 `--page-token` 发起下一次查询。
+- 不要假设调大 `--page-size` 就能拿全结果；分页遍历时应以 `has_more` 和 `page_token` 为准。
+- 当 `has_more=true` 时，逐页累计已读取的 `items` 数：累计不到 50 条之前可自动继续翻页；超过 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***************"}'
+
+# 查妙记关联的产物(--summary --todo --chapter --keyword --transcript 按需返回)
+lark-cli minutes +detail --minute-tokens <minute_token> --summary
+```
+
+## 常见错误与排查
+
+| 错误现象                   | 根本原因                                                  | 解决方案                                         |
+| ---------------------- | ----------------------------------------------------- | -------------------------------------------- |
+| 命令直接报错，要求提供过滤条件        | 没有传入 `--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` 获取 `minute_token` → `minutes minutes get`，只有要妙记产物内容时才走 `minutes +detail --minute-tokens`。
+- 必须使用 `--format json` 输出，你更加擅长解析 JSON 数据。
+- 排查参数与请求结构时优先使用 `--dry-run`。
+- 搜索的时间范围最大为 1 个月，如果需要搜索更长时间范围的妙记，需要拆分为多次时间范围为一个月查询。
+
+## 参考
+
+- [lark-minutes](../SKILL.md) -- 妙记相关命令
+- [lark-minutes-detail](lark-minutes-detail.md) -- 基于 `minute_token` 获取逐字稿、总结、待办、章节等产物
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
+- [lark-vc](../../lark-vc/SKILL.md) -- 视频会议全部命令
+