pi-feishu-cli 0.1.0

package/skills/lark-vc/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: lark-vc
+version: 1.0.0
+description: "飞书视频会议：搜索历史会议、查询会议纪要产物（总结、待办、章节、逐字稿）、查询会议参会人快照。1. 查询已经结束的会议数量或详情时使用本技能（如历史日期｜昨天｜上周｜今天已经开过的会议等场景），查询未开始的会议日程使用 lark-calendar 技能。2. 支持通过关键词、时间范围、组织者、参与者、会议室等筛选条件搜索会议。3. 获取或整理会议纪要、逐字稿、录制产物时使用本技能。4. 查询“谁参加过某会议”“参会人列表”等参会人快照信息用 vc meeting get --with-participants（任意时点可查，含已结束会议）。注意：**Agent 真实入会/离会、感知正在进行中会议的实时事件**请使用 lark-vc-agent 技能，本技能不覆盖写操作和会中事件流。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli vc --help"
+---
+
+# vc (v1)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+
+## 核心概念
+
+- **视频会议（Meeting）**：飞书视频会议实例，通过 meeting\_id 标识。已结束的会议支持通过关键词、时间段、参会人、组织者、会议室等条件搜索（见 `+search`）。
+- **会议纪要（Note）**：视频会议结束后生成的结构化文档，包含纪要文档（包含总结、待办、章节）和逐字稿文档。
+- **妙记（Minutes）**：来源于飞书视频会议的录制产物或用户上传的音视频文件，支持视频/音频的转写和会议纪要，通过 minute\_token 标识。
+- **纪要文档（MainDoc）**：AI 智能纪要的主文档，包含 AI 生成的总结和待办，对应 `note_doc_token`。
+- **用户会议纪要（MeetingNotes）**：用户主动绑定到会议的纪要文档，对应 `meeting_notes`。仅通过 `--calendar-event-ids` 路径返回。
+- **逐字稿（VerbatimDoc）**：会议的逐句文字记录，包含说话人和时间戳。
+
+## 核心场景
+
+### 1. 搜索会议记录
+1. 仅支持搜索已结束的会议，对于还未开始的未来会议，需要使用 lark-calendar 技能。
+2. 仅支持使用关键词、时间段、参会人、组织者、会议室等筛选条件搜索会议记录，对于不支持的筛选条件，需要提示用户。
+3. 搜索结果存在多条数据时，务必注意分页数据获取，不要遗漏任何会议记录。
+
+### 2. 整理会议纪要
+1. 整理纪要文档时默认给出纪要文档和逐字稿链接即可，无需读取纪要文档或逐字稿内容。
+2. 用户明确需要获取纪要文档中的总结、待办、章节产物时，再读取文档获取具体内容。
+3. 读取智能纪要（`note_doc_token`）内容时，纪要文档的**第一个 `<whiteboard>`** 标签是封面图（AI 生成的总结可视化），应同时下载展示给用户：
+```bash
+# 1. 读取纪要内容
+lark-cli docs +fetch --api-version v2 --doc <note_doc_token> --doc-format markdown
+# 2. 从返回的 markdown 中提取第一个 <whiteboard token="xxx"/> 的 token
+# 3. 下载封面图到聚合目录（和逐字稿、录像同目录，保持产物归拢）
+#    并非所有纪要都有封面画板，没有 <whiteboard> 标签时跳过即可
+lark-cli docs +media-download --type whiteboard --token <whiteboard_token> --output ./minutes/<minute_token>/cover
+```
+> **产物目录规范**：同一会议的所有下载产物（录像、逐字稿、封面图等）统一放到 `./minutes/{minute_token}/` 目录下。这与 `minutes +download` 和 `vc +notes --minute-tokens` 的默认落点保持一致，便于 Agent 聚合。显式路径（如封面图）需手动对齐到同一目录。
+
+> **纪要相关文档 — 根据用户意图选择：**
+> - `note_doc_token` → **AI 智能纪要**（AI 总结 + 待办 + 章节）
+> - `meeting_notes` → **用户绑定的会议纪要**（用户主动关联到会议的文档，仅 `--calendar-event-ids` 路径返回）
+> - `verbatim_doc_token` → **逐字稿**（完整的逐句文字记录，含说话人和时间戳）— 用户说"逐字稿""完整记录""谁说了什么"时用这个
+> - 用户说"纪要""总结""纪要内容"时，应同时返回 `note_doc_token` 和 `meeting_notes`（如有）
+> - 用户意图不明确时，应展示所有文档链接让用户选择，而不是替用户决定
+> - 如果用户提供的是**本地音视频文件**并说"转纪要""转逐字稿"，不要直接从 `vc +notes` 开始；应先用 [minutes +upload](../lark-minutes/references/lark-minutes-upload.md) 生成 `minute_url`，再提取 `minute_token` 调用 `vc +notes --minute-tokens`
+
+### 3. 纪要文档与逐字稿链接
+1. 纪要文档、逐字稿文档与关联的共享文档默认使用文档 Token 返回。
+2. 仅需要获取文档名称和 URL 等基本信息时，使用 `lark-cli drive metas batch_query` 查询
+```bash
+# 学习命令使用方式
+lark-cli schema drive.metas.batch_query
+
+# 批量获取文档基本信息: 一次最多查询 10 个文档
+lark-cli drive metas batch_query --data '{"request_docs": [{"doc_type": "docx", "doc_token": "<doc_token>"}], "with_url": true}'
+```
+3. 需要获取文档内容时，使用 `lark-cli docs +fetch --api-version v2`。
+```bash
+# 获取文档内容
+lark-cli docs +fetch --api-version v2 --doc <doc_token> --doc-format markdown
+```
+
+### 4. 查询参会人快照（读操作）
+
+用户问"谁参加过这场会议""这个会议有哪些参会人""某某参会了吗"等**参会人快照**类问题时，使用 **`vc meeting get --with-participants`**：这是参会人服务端快照 API，不依赖 bot 身份参会，**已结束会议也可查**：
+
+```bash
+lark-cli vc meeting get --params '{"meeting_id":"<meeting_id>","with_participants":true}'
+```
+
+选型判断表：
+
+| 用户意图 | 推荐命令 | 所在 skill |
+|---------|---------|--------|
+| 参会人快照（谁参加过、何时入/离会，任意时点）| `vc meeting get --with-participants` | 本 skill |
+| 已结束会议的发言内容 | `vc +notes` 取 `verbatim_doc_token` 再 `docs +fetch --api-version v2` | 本 skill |
+| **进行中会议**的实时事件流（转写、聊天、共享、会中加入/离开）| `vc +meeting-events` | [`lark-vc-agent`](../lark-vc-agent/SKILL.md) |
+| **Agent 真实入会 / 离会** | `vc +meeting-join` / `vc +meeting-leave` | [`lark-vc-agent`](../lark-vc-agent/SKILL.md) |
+
+## 资源关系
+
+```
+Meeting (视频会议)
+├── Note (会议纪要)
+│   ├── MainDoc (AI 智能纪要文档, note_doc_token)
+│   ├── MeetingNotes (用户绑定的会议纪要文档, meeting_notes)
+│   ├── VerbatimDoc (逐字稿, verbatim_doc_token)
+│   └── SharedDoc (会中共享文档)
+└── Minutes (妙记) ← minute_token 标识，+recording 从 meeting_id 获取
+    ├── Transcript (文字记录)
+    ├── Summary (总结)
+    ├── Todos (待办)
+    └── Chapters (章节)
+```
+
+> **注意**：`+search` 只能查询已结束的历史会议。查询未来的日程安排请使用 [lark-calendar](../lark-calendar/SKILL.md)。
+>
+> **优先级**：当用户搜索历史会议时，应优先使用 `vc +search` 而非 `calendar events search`。calendar 的搜索面向日程，vc 的搜索面向已结束的会议记录，支持按参会人、组织者、会议室等维度过滤。
+>
+> **路由规则**：如果用户在问“开过的会”“今天开了哪些会”“最近参加过什么会”“已结束的会议”“历史会议记录”，优先使用 `vc +search`。只有在查询未来日程、待开的会、agenda 时才优先使用 [lark-calendar](../lark-calendar/SKILL.md)。
+>
+> **妙记边界**：`+notes` 负责纪要内容、逐字稿和 AI 产物；妙记基础信息请优先看 [`+recording`](references/lark-vc-recording.md) 与 [lark-minutes](../lark-minutes/SKILL.md)。
+>
+> **文件转纪要边界**：如果用户给的是本地音视频文件，并希望得到纪要、逐字稿、总结、待办或章节，入口应先走 [lark-minutes](../lark-minutes/SKILL.md) 的上传流程生成 `minute_url` / `minute_token`，再回到 `vc +notes --minute-tokens` 获取内容产物。
+>
+> **特殊情况**: 当用户查询“今天有哪些会议”时，通过 `vc +search` 查询今天开过的会议记录，同时使用 lark-calendar 技能查询今天还未开始的会议，统一整理后展示给用户。
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`lark-cli vc +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+search`](references/lark-vc-search.md) | Search meeting records (requires at least one filter) |
+| [`+notes`](references/lark-vc-notes.md) | Query meeting notes (via meeting-ids, minute-tokens, or calendar-event-ids) |
+| [`+recording`](references/lark-vc-recording.md) | Query minute_token from meeting-ids or calendar-event-ids |
+
+- 使用 `+search` 命令时，必须阅读 [references/lark-vc-search.md](references/lark-vc-search.md)，了解搜索参数和返回值结构。
+- 使用 `+notes` 命令时，必须阅读 [references/lark-vc-notes.md](references/lark-vc-notes.md)，了解查询参数、产物类型和返回值结构。
+- 使用 `+recording` 命令时，必须阅读 [references/lark-vc-recording.md](references/lark-vc-recording.md)，了解查询参数和返回值结构。
+
+> **Agent 参会相关命令已独立**：`+meeting-join` / `+meeting-leave` / `+meeting-events` 请使用 [`lark-vc-agent`](../lark-vc-agent/SKILL.md) 技能。
+
+## API Resources
+
+```bash
+lark-cli schema vc.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli vc <resource> <method> [flags] # 调用 API
+```
+
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+
+### meeting
+
+  - `get` — 获取会议详情（主题、时间、参会人、note_id）
+
+```bash
+# 获取会议基础信息：不包含参会人列表
+lark-cli vc meeting get --params '{"meeting_id": "<meeting_id>"}'
+
+
+# 获取会议基础信息：包含参会人列表
+lark-cli vc meeting get --params '{"meeting_id": "<meeting_id>", "with_participants": true}'
+```
+
+### minutes（跨域，详见 [lark-minutes](../lark-minutes/SKILL.md)）
+
+  - `get` — 获取妙记基础信息（标题、时长、封面）；查询纪要**内容**请用 `+notes --minute-tokens <minute-token>`
+
+## 权限表
+
+| 方法 | 所需 scope |
+|------|-----------|
+| `+notes --meeting-ids` | `vc:meeting.meetingevent:read`、`vc:note:read` |
+| `+notes --minute-tokens` | `vc:note:read`、`minutes:minutes:readonly`、`minutes:minutes.artifacts:read`、`minutes:minutes.transcript:export` |
+| `+notes --calendar-event-ids` | `calendar:calendar:read`、`calendar:calendar.event:read`、`vc:meeting.meetingevent:read`、`vc:note:read` |
+| `+recording --meeting-ids` | `vc:record:readonly` |
+| `+recording --calendar-event-ids` | `vc:record:readonly`、`calendar:calendar:read`、`calendar:calendar.event:read` |
+| `+search` | `vc:meeting.search:read` |
+| `meeting.get` | `vc:meeting.meetingevent:read` |
+
+> Agent 参会相关 scope（`vc:meeting.bot.join:write` / `vc:meeting.meetingevent:read`）见 [`lark-vc-agent`](../lark-vc-agent/SKILL.md)。

package/skills/lark-vc/references/lark-vc-notes.md

@@ -0,0 +1,126 @@
+
+# vc +notes
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+查询会议纪要，支持通过会议 ID、妙记 Token 或日程事件 ID 获取纪要文档、逐字稿、AI 总结、待办和章节。只读操作。
+
+本 skill 对应 shortcut：`lark-cli vc +notes`。
+
+## 命令
+
+```bash
+# 通过会议 ID 查询（逗号分隔支持批量，最多 50 个）
+lark-cli vc +notes --meeting-ids 69xxxxxxxxxxxxx28
+lark-cli vc +notes --meeting-ids 69xxxxxxxxxxxxx28,69xxxxxxxxxxxxx29
+
+# 通过妙记 Token 查询（从妙记 URL 中提取）
+lark-cli vc +notes --minute-tokens obbxxxxxxxxxxxxxxxxxx
+lark-cli vc +notes --minute-tokens obbxxxxxxxxxxxxxxxxxx,obbyyyyyyyyyyyyyyyyyy
+
+# 指定逐字稿输出目录（仅 --minute-tokens 路径有效）
+lark-cli vc +notes --minute-tokens obbxxxxxxxxxxxxxxxxxx --output-dir ./output
+lark-cli vc +notes --minute-tokens obbxxxxxxxxxxxxxxxxxx --overwrite
+
+# 通过日程事件 ID 查询（从 calendar +agenda 获取 event_id）
+lark-cli vc +notes --calendar-event-ids xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_0
+
+# 输出格式
+lark-cli vc +notes --meeting-ids 69xxxxxxxxxxxxx28 --format json
+
+# 预览 API 调用
+lark-cli vc +notes --meeting-ids 69xxxxxxxxxxxxx28 --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--meeting-ids <ids>` | 三选一 | 会议 ID，逗号分隔支持批量 |
+| `--minute-tokens <tokens>` | 三选一 | 妙记 Token，逗号分隔支持批量 |
+| `--calendar-event-ids <ids>` | 三选一 | 日程事件 ID，逗号分隔支持批量 |
+| `--output-dir <dir>` | 否 | 逐字稿输出目录（默认当前目录），仅 `--minute-tokens` 路径有效 |
+| `--overwrite` | 否 | 覆盖已存在的逐字稿文件，仅 `--minute-tokens` 路径有效 |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 核心约束
+
+### 1. 三种参数互斥
+
+每次只能指定一种输入方式。同时传入多种会报错。
+
+### 2. 仅支持 user 身份
+
+该命令仅支持 `user` 身份，使用前需完成 `lark-cli auth login`。
+
+### 3. 批量上限
+
+每次最多传入 50 个 ID/Token。
+
+### 4. 按路径检查权限
+
+不同输入方式需要不同权限，命令会自动检查对应路径所需的 scope：
+
+| 输入 | 所需权限 |
+|------|---------|
+| `--meeting-ids` | `vc:meeting.meetingevent:read`、`vc:note:read` |
+| `--minute-tokens` | `vc:note:read`、`minutes:minutes:readonly`、`minutes:minutes.artifacts:read`、`minutes:minutes.transcript:export` |
+| `--calendar-event-ids` | `calendar:calendar:read`、`calendar:calendar.event:read`、`vc:meeting.meetingevent:read`、`vc:note:read` |
+
+## 输出结果
+
+### 有纪要文档时
+
+返回 `notes` 数组，每条记录包含：
+
+| 字段 | 说明 |
+|------|------|
+| `note_doc_token` | **AI 智能纪要**文档 Token — AI 生成的总结、待办、章节 |
+| `meeting_notes` | **用户绑定的会议纪要**文档 Token 列表 — 用户主动关联到会议的文档（仅 `--calendar-event-ids` 路径返回） |
+| `verbatim_doc_token` | **逐字稿**文档 Token — 完整的逐句文字记录，含说话人和时间戳 |
+| `shared_doc_tokens` | 会中共享文档 Token 列表 |
+| `creator_id` | 创建者 ID |
+| `create_time` | 创建时间（格式化） |
+
+> **选择哪个 token？** 用户说"会议纪要""总结""待办""纪要内容" → 返回 `note_doc_token` 和 `meeting_notes`（如有）。用户说"逐字稿""完整记录""谁说了什么" → 用 `verbatim_doc_token`。意图不明确时，展示所有文档链接让用户选择。
+
+### minute-tokens 路径的 AI 产物
+
+通过 `--minute-tokens` 查询时，返回的 `artifacts` 字段包含 AI 内置产物：
+
+| 字段 | 说明 |
+|------|------|
+| `artifacts.summary` | AI 总结（JSON 内联） |
+| `artifacts.todos` | 待办事项（JSON 内联） |
+| `artifacts.chapters` | 章节纪要（JSON 内联） |
+| `artifacts.transcript_file` | 逐字稿本地文件路径（下载到 `./artifact-<title>/transcript.txt`） |
+
+## 如何获取输入参数
+
+| 输入参数 | 获取方式 |
+|---------|---------|
+| `meeting_id` | `vc +search` 搜索历史会议 → 结果中的 `id` 字段 |
+| `minute_token` | 从妙记 URL 中提取，如 `https://sample.feishu.cn/minutes/obbyyyyyyyyyyyyyyyyyy` → `obbyyyyyyyyyyyyyyyyyy` |
+| `calendar_event_id` | `calendar +agenda` 查看日程 → 结果中的 `event_id` 字段 |
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| `exactly one of ... is required` | 未传入参数或同时传了多种 | 只指定一种输入方式 |
+| `no notes available for this meeting` | 该会议未生成纪要 | 尝试用 `--minute-tokens` 路径 |
+| `121005 no permission` | 非会议参与者无权查看 | 使用 `--minute-tokens` 降级到内置产物 |
+| `missing required scope(s)` | 权限不足 | 按提示运行 `auth login --scope` |
+| `too many IDs` | 超过批量上限 | 分批查询，每批最多 50 个 |
+
+## 提示
+- 默认使用 `--format json` 输出，你更佳擅长解析 JSON 数据。
+- 排查参数与请求结构时优先使用 `--dry-run`。
+- `--meeting-ids` 和 `--calendar-event-ids` 路径最终都走纪要详情 API，需要 `vc:note:read` 权限。
+- `--minute-tokens` 路径无纪要权限时会自动降级，**不会报错**，而是下载内置产物到本地。
+
+## 参考
+
+- [lark-vc](../SKILL.md) — 视频会议全部命令
+- [lark-vc-search](lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/skills/lark-vc/references/lark-vc-recording.md

@@ -0,0 +1,153 @@
+
+# vc +recording
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+通过 meeting_id 或 calendar_event_id 查询对应的 minute_token。这是 VC 域和 Minutes 域之间的桥梁命令。只读操作。
+
+> **边界提醒：** 如果用户明确要的是"妙记信息""妙记详情""妙记链接""minute_token""标题""时长""owner"这类妙记元信息，先用本命令拿到 `minute_token`，再调用 `minutes minutes get`。不要直接切到 `vc +notes`；`vc +notes` 只用于纪要内容和逐字稿。
+
+本 skill 对应 shortcut：`lark-cli vc +recording`。
+
+## 命令
+
+```bash
+# 通过会议 ID 查询（逗号分隔支持批量，最多 50 个）
+lark-cli vc +recording --meeting-ids 69xxxxxxxxxxxxx28
+lark-cli vc +recording --meeting-ids 69xxxxxxxxxxxxx28,69xxxxxxxxxxxxx29
+
+# 通过日程事件 ID 查询
+lark-cli vc +recording --calendar-event-ids xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_0
+
+# 输出格式
+lark-cli vc +recording --meeting-ids 69xxxxxxxxxxxxx28 --format json
+
+# 预览 API 调用
+lark-cli vc +recording --meeting-ids 69xxxxxxxxxxxxx28 --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--meeting-ids <ids>` | 二选一 | 会议 ID，逗号分隔支持批量 |
+| `--calendar-event-ids <ids>` | 二选一 | 日程事件 ID，逗号分隔支持批量 |
+| `--format <fmt>` | 否 | 输出格式：json (默认) / pretty / table / ndjson / csv |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 核心约束
+
+### 1. 两种参数互斥
+
+每次只能指定一种输入方式。同时传入会报错。
+
+### 2. 仅支持 user 身份
+
+该命令仅支持 `user` 身份，使用前需完成 `lark-cli auth login`。user token 只能查自己有权限的录制。
+
+### 3. 批量上限
+
+每次最多传入 50 个 ID。
+
+### 4. 录制必须已完成
+
+录制必须完成生成后才能查询。时长 < 5 秒的录制可能不会生成文件。
+
+## 输出结果
+
+返回 `recordings` 数组，每条记录包含：
+
+| 字段 | 说明 |
+|------|------|
+| `meeting_id` | 会议 ID |
+| `calendar_event_id` | 日历事件 ID（仅 `--calendar-event-ids` 路径） |
+| `minute_token` | 从录制 URL 中解析的妙记 Token |
+| `recording_url` | 录制 URL |
+| `duration` | 录制时长（毫秒） |
+| `error` | 错误信息（仅查询失败时存在） |
+
+## 如何获取输入参数
+
+| 输入参数 | 获取方式 |
+|---------|---------|
+| `meeting_id` | 使用 `lark-cli vc +search` 搜索历史会议，取结果中的 `id` 字段 |
+| `calendar_event_id` | 使用 `lark-cli calendar +agenda` 查看日程，取结果中的 `event_id` 字段 |
+
+## Agent 组合场景
+
+### 场景 1：知道 meeting_id，想下载录制
+
+```bash
+# 第 1 步：通过 meeting_id 查询录制，拿到 minute_token
+lark-cli vc +recording --meeting-ids xxx
+
+# 第 2 步：使用上一步返回的 minute_token 下载妙记文件
+lark-cli minutes +download --minute-token <minute_token>
+```
+
+### 场景 2：知道 meeting_id，想查询妙记基础信息
+
+```bash
+# 第 1 步：通过 meeting_id 查询录制，拿到 minute_token
+lark-cli vc +recording --meeting-ids xxx
+
+# 第 2 步：使用上一步返回的 minute_token 查询妙记基础信息
+lark-cli minutes minutes get --params '{"minute_token":"<minute_token>"}'
+```
+
+### 场景 3：知道 meeting_id，想获取完整纪要（含 AI 产物）
+
+```bash
+# 第 1 步：通过 meeting_id 查询录制，拿到 minute_token
+lark-cli vc +recording --meeting-ids xxx
+
+# 第 2 步：使用上一步返回的 minute_token 获取完整纪要
+lark-cli vc +notes --minute-tokens <minute_token>
+```
+
+### 场景 4：先搜索会议，再获取录制并下载
+
+```bash
+# 第 1 步：搜索历史会议，拿到 meeting_ids
+lark-cli vc +search --query "周会" --start 2026-03-10
+
+# 第 2 步：使用上一步返回的 meeting_ids 查询录制，拿到 minute_tokens
+lark-cli vc +recording --meeting-ids <ids>
+
+# 第 3 步：使用其中一个 minute_token 下载妙记文件
+lark-cli minutes +download --minute-token <token>
+```
+
+### 场景 5：从日历事件获取录制
+
+```bash
+# 第 1 步：通过日历 event_id 查询录制，拿到 minute_token
+lark-cli vc +recording --calendar-event-ids <event_id>
+
+# 第 2 步：使用上一步返回的 minute_token 下载妙记文件
+lark-cli minutes +download --minute-token <minute_token>
+```
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| `exactly one of ... is required` | 未传入参数或同时传了多种 | 只指定一种输入方式 |
+| `no recording available` | 该会议无录制或录制未完成 | 确认会议已结束且开启了录制 |
+| `121005 no permission` | 无权查看该会议录制 | 确认是会议参与者或有录制权限 |
+| `124002 recording generating` | 录制文件仍在生成中 | 等待录制完成后重试 |
+| `missing required scope(s)` | 权限不足 | 按提示运行 `auth login --scope` |
+
+## 提示
+
+- 默认使用 `--format json` 输出，Agent 更擅长解析 JSON 数据。
+- 排查参数与请求结构时优先使用 `--dry-run`。
+- `minute_token` 从录制 URL 尾段解析（`https://meetings.feishu.cn/minutes/{minute_token}`）。
+- 拿到 `minute_token` 后，如果要妙记基础信息，优先传给 `minutes minutes get`；如果要下载媒体文件，传给 `minutes +download`；如果要逐字稿、总结、待办、章节，再传给 `vc +notes --minute-tokens`。
+
+## 参考
+
+- [lark-vc](../SKILL.md) — 视频会议全部命令
+- [lark-vc-search](lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
+- [lark-vc-notes](lark-vc-notes.md) — 获取会议纪要
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -0,0 +1,193 @@
+
+# vc +search
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+搜索已结束的历史会议记录，支持关键词、时间范围、组织者、参与者以及会议室等多条件过滤。只读操作，不修改任何会议数据。
+
+本 skill 对应 shortcut：`lark-cli vc +search`（调用 `POST /open-apis/vc/v1/meetings/search`）。
+
+## 关键词使用边界
+
+`--query` 只用于真实会议关键词，例如会议主题、项目名、评审名、客户名。用户只是说"我这月参加的所有视频会议"、"最近两周我组织的所有视频会议"、"总结主要议题 / 看看参会情况"时，本质是历史会议列表和后续总结，不要把"回顾"、"所有视频会议"、"总结主要议题"等动作词放进 `--query`。这类请求应先用时间范围 + `--participant-ids` / `--organizer-ids` 搜全量候选，再按结果继续取纪要或录制信息。
+
+列表阶段只负责找会议记录；总结阶段必须继续取证。若用户要求"主要议题"、"主要决策"、"参会情况"，先确认搜索结果的 `meeting_id`、时间、组织者/参与者符合过滤条件，然后用 `vc +notes` 或 `vc +recording` / `minutes` 读取纪要、妙记或录制信息。没有纪要或妙记时，如实说明只能基于会议标题/参会数据汇总，不要编造议题。
+
+## 典型触发表达
+
+以下说法通常应优先使用 `vc +search`：
+
+- 今天开过的会
+- 今天开了哪些会
+- 最近参加过哪些会
+- 我这周开过的会
+- 已结束的会议
+- 历史会议记录
+
+## 命令
+
+```bash
+# 关键词搜索
+lark-cli vc +search --query "周会"
+
+# 查询某一天开过的会（单日查询时，start 和 end 必须填写同一天）
+lark-cli vc +search --start 2026-03-10 --end 2026-03-10
+
+# 按时间范围搜索
+lark-cli vc +search --start "2026-03-10T00:00+08:00" --end "2026-03-17T00:00+08:00"
+lark-cli vc +search --start 2026-03-10 --end 2026-03-17
+
+# 关键词 + 时间范围
+lark-cli vc +search --query "周会" --start "2026-03-10T00:00+08:00" --end "2026-03-17T00:00+08:00"
+lark-cli vc +search --query "周会" --start "2026-03-10T00:00+08:00"
+lark-cli vc +search --query "周会" --end "2026-03-17T00:00+08:00"
+
+# 按组织者过滤（open_id，逗号分隔）
+lark-cli vc +search --organizer-ids "ou_a,ou_b"
+
+# 按参与者过滤（open_id，逗号分隔）
+lark-cli vc +search --participant-ids "ou_x,ou_y"
+
+# 查询我这个月参加过的历史会议，不带关键词
+lark-cli vc +search --start "<YYYY-MM-DD>" --end "<YYYY-MM-DD>" --participant-ids "ou_me"
+
+# 查询最近两周我组织的历史会议，不带关键词
+lark-cli vc +search --start "<YYYY-MM-DD>" --end "<YYYY-MM-DD>" --organizer-ids "ou_me"
+
+# 按会议室过滤
+lark-cli vc +search --room-ids "123,456"
+
+# 多条件组合查询
+lark-cli vc +search --organizer-ids "ou_a" --room-ids "123" --start "2026-03-10T00:00+08:00"
+
+# 分页查询
+lark-cli vc +search --query "周会" --page-size 15
+lark-cli vc +search --query "周会" --page-token "next_page_token"
+
+# 输出为表格/可读格式
+lark-cli vc +search --query "周会" --format json
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--query <text>` | 否 | 搜索关键词 |
+| `--start <time>` | 否 | 开始时间（ISO 8601 或仅日期） |
+| `--end <time>` | 否 | 结束时间（ISO 8601 或仅日期） |
+| `--organizer-ids <ids>` | 否 | 组织者 open_id 列表，逗号分隔 |
+| `--participant-ids <ids>` | 否 | 参与者 open_id 列表，逗号分隔 |
+| `--room-ids <ids>` | 否 | 会议室 ID 列表，逗号分隔 |
+| `--page-size <n>` | 否 | 每页数量，默认 `15`，最大 `30` |
+| `--page-token <token>` | 否 | 翻页标记，用于获取下一页 |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 核心约束
+
+### 1. 至少提供一个过滤条件
+
+所有参数均可选，但必须至少提供一个过滤条件：`--query`、`--start`、`--end`、`--organizer-ids`、`--participant-ids` 或 `--room-ids`。
+
+没有真实关键词时，时间范围或人员过滤已经满足这个约束，`--query` 可以省略。
+
+涉及"本月"、"最近两周"这类相对时间时，先基于执行当天计算 `"<YYYY-MM-DD>"` 占位符，再运行命令；不要沿用文档示例生成时的具体日期。
+
+### 2. 仅搜索历史会议
+
+`vc +search` 只能搜索已结束的历史会议记录，不用于查询未来日程。查询未来会议安排请使用 [lark-calendar](../../lark-calendar/SKILL.md)。
+
+### 3. 仅支持 user 身份
+
+该接口仅支持 `user` 身份，使用前需完成 `lark-cli auth login` 并具备 `vc:meeting.search:read` 权限。
+
+### 4. 支持分页
+
+当返回 `has_more=true` 时，使用响应中的 `page_token` 配合 `--page-token` 获取下一页结果。
+
+### 5. 机器人可同时加入多个会议
+
+机器人支持同时加入多个正在进行中的会议；加入新会议前，不需要先退出已经在会中的其他会议。
+
+这意味着：
+
+- 不要假设 bot 一次只能在一个会议中
+- 如果用户要求 bot 再加入另一场会，可以直接继续执行对应的入会命令
+- 只有在用户明确要求结束某一场会中的 bot 参会时，才调用对应的离会命令
+
+### 6. 日期型 `--end` 包含当天整天
+
+当 `--end` 传入的是仅日期格式（如 `2026-03-10`）时，CLI 会将它解释为当天 `23:59:59`，而不是当天 `00:00:00`。
+
+这意味着：
+
+- `--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` 设成下一天。
+
+## 时间格式
+
+`--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` |
+
+## 输出结果
+
+- 默认输出 JSON，包含 `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 时，先向用户确认是否继续获取全部结果。
+- 用户明确说"所有 / 全部 / 统计 / 按时间排序"时，该全量意图优先于 `total > 50` 的确认门槛；直接完成分页和去重，再排序或统计，不要只用第一页回答。
+
+```bash
+# First page
+lark-cli vc +search --query "周会" --page-size 15
+
+# Next page
+lark-cli vc +search --query "周会" --page-size 15 --page-token "<PAGE_TOKEN>"
+```
+
+## 搜索结果中的下一步
+
+搜索结果中的 `meeting_id` 可直接用于继续查询会议纪要或妙记：
+
+```bash
+# 如果要会议纪要 / 逐字稿 / AI 总结 / 待办 / 章节
+lark-cli vc +notes --meeting-ids <MEETING_ID>
+
+# 如果要会议对应的妙记信息 / minute_token / 妙记链接
+lark-cli vc +recording --meeting-ids <MEETING_ID>
+# 然后再用返回的 minute_token 调用：
+lark-cli minutes minutes get --params '{"minute_token":"<MINUTE_TOKEN>"}'
+```
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| 命令直接报错，要求提供过滤条件 | 没有传入 `--query`、时间范围或任何过滤 ID | 至少补充一个过滤条件后重试 |
+| 时间参数校验失败 | `--start` 或 `--end` 格式不合法 | 改用 ISO 8601 或 `YYYY-MM-DD` |
+| 搜不到未来会议 | `vc +search` 只查历史会议 | 改用 [lark-calendar](../../lark-calendar/SKILL.md) 查询未来日程 |
+| 权限不足 | 未授权 `vc:meeting.search:read` | 使用 `auth login` 完成授权 |
+
+## 提示
+- 必须使用 `--format json` 输出，你更佳擅长解析 JSON 数据。
+- 排查参数与请求结构时优先使用 `--dry-run`。
+- 搜索的时间范围最大为 1 个月，如果需要搜索更长时间范围的会议，需要拆分为多次时间范围为一个月查询。
+- 不要使用 `yesterday`、`today` 这类相对时间字面量；请先转换成明确日期，例如 `2026-03-10`。
+- 用户如果明确问的是“妙记信息”而不是“纪要内容”，不要默认走 `vc +notes`；应先用 `vc +recording`。
+
+## 参考
+
+- [lark-vc](../SKILL.md) -- 视频会议全部命令
+- [lark-vc-recording](lark-vc-recording.md) -- 查询会议对应的 minute_token
+- [lark-vc-notes](lark-vc-notes.md) -- 获取会议纪要
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数