@yandy0725/pi-lark 0.1.0

package/skills/lark-minutes/references/lark-minutes-speaker-replace.md

@@ -0,0 +1,107 @@
+# minutes +speaker-replace
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+替换妙记逐字稿中的说话人身份：把妙记逐字稿里"原说话人"对应的所有发言段，重新归属到"新说话人"。常用于解决妙记自动识别错说话人，或需要把外部/非飞书说话人改绑到正确飞书用户的场景。
+
+本 skill 对应 shortcut：`lark-cli minutes +speaker-replace`。
+
+## 典型触发表达
+
+- "把这条妙记里 A 的发言改成 B"
+- "妙记说话人识别错了，帮我把张三的部分换成李四"
+- "把妙记里外部说话人 / 非飞书说话人的发言改成某个飞书用户"
+- "妙记说话人修改 / 替换 / 重新归属"
+
+## 完整工作流
+
+识别到「修改妙记说话人」需求后，**必须**按以下顺序执行；**禁止**把展示名直接传给 `--from-speaker-id`。
+
+1. **确认 `minute_token`**
+   - 从妙记 URL、搜索或 VC 链路取得 `minute_token`。
+
+2. **查说话人列表（必须先做）**
+   - 用 **`lark-cli api`** 直接调用内部 HTTP 接口：
+     ```bash
+     lark-cli api GET "/open-apis/minutes/v1/minutes/<minute_token>/transcript/speakerlist" --as user
+     ```
+   - 返回 `data.speakers[]`，每项含 `speaker_id`（不透明 id）与 `name`（逐字稿展示名）。示例：
+     ```json
+     {
+       "data": {
+         "speakers": [
+           {"speaker_id": "ENCRYPTED_TOKEN_ABC", "name": "说话人1"},
+           {"speaker_id": "ENCRYPTED_TOKEN_DEF", "name": "说话人2"}
+         ]
+       }
+     }
+     ```
+
+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`。
+   - 若列表中无匹配展示名：告知用户并核对拼写，或请用户在妙记页面确认标签。
+
+4. **解析 `--to-user-id`**
+   - 新说话人必须是 `ou_` 开头的 open_id。用户只给姓名时，先用 [lark-contact](../../lark-contact/SKILL.md) 解析。
+
+5. **执行替换**
+   ```bash
+   lark-cli minutes +speaker-replace \
+     --minute-token obcnxxxxxxxxxxxxxxxxxxxx \
+     --from-speaker-id ENCRYPTED_TOKEN_ABC \
+     --to-user-id ou_new_speaker_open_id
+   ```
+
+## 命令示例
+
+```bash
+# 1. 先查列表（裸调 HTTP）
+lark-cli api GET "/open-apis/minutes/v1/minutes/obcnxxxxxxxxxxxxxxxxxxxx/transcript/speakerlist" --as user
+
+# 2. 再替换（from-speaker-id 来自上一步的 speaker_id）
+lark-cli minutes +speaker-replace \
+  --minute-token obcnxxxxxxxxxxxxxxxxxxxx \
+  --from-speaker-id ENCRYPTED_TOKEN_ABC \
+  --to-user-id ou_new_speaker_open_id
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--minute-token <token>` | 是 | 妙记的唯一标识，可从妙记 URL 末尾路径提取 |
+| `--from-speaker-id <id>` | 是 | 被替换的原说话人 **`speaker_id`**（来自 speakerlist API 的 `data.speakers[].speaker_id`） |
+| `--to-user-id <ou_xxx>` | 是 | 新的说话人，**必须是 `ou_` 开头的 open_id**，不支持用户名 |
+
+## 核心约束
+
+### 1. 必须先查 speakerlist，再替换
+
+Agent 必须先 `lark-cli api GET .../speakerlist`，再 `+speaker-replace`；`--from-speaker-id` 只接受 `speaker_id`。
+
+### 2. 新说话人必须是 open_id
+
+`--to-user-id` 仅支持 `ou_` 开头的 open_id，**不支持直接传姓名**；如果用户只给了姓名，请先用 [lark-contact](../../lark-contact/SKILL.md) 把姓名解析成 `open_id`。
+
+### 3. 历史参数
+
+存在一个隐藏的历史参数 `--from-user-id`（飞书说话人的 open_id），仅为向后兼容保留；新流程请一律使用 `--from-speaker-id` + `speaker_id`。
+
+## 认证与权限
+
+- 所需 scope：`minutes:minutes:readonly`（内部解析说话人）、`minutes:minutes:update`（执行替换）。
+
+## 输出结果
+
+| 字段 | 说明 |
+|------|------|
+| `minute_token` | 被修改的妙记 Token，与输入的 `--minute-token` 一致 |
+| `from_speaker_id` | 实际用于替换的不透明说话人标识 |
+| `to_user_id` | 替换后的新说话人 open_id，与输入的 `--to-user-id` 一致 |
+
+## 参考
+
+- [lark-minutes](../SKILL.md) -- 妙记相关功能说明
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,122 @@
+# minutes +summary
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+替换妙记的 AI 总结内容。写操作，会覆盖当前总结。
+
+本 skill 对应 shortcut：`lark-cli minutes +summary`（调用 `PUT /open-apis/minutes/v1/minutes/{minute_token}/summary`）。
+
+## 典型触发表达
+
+- "把这条妙记的总结改成……"
+- "更新 / 替换妙记的 AI 总结"
+- "修正总结内容后写回妙记"
+
+## 命令
+
+```bash
+# 直接传入总结内容（Markdown 子集）
+lark-cli minutes +summary --minute-token obcnxxxxxxxxxxxxxxxxxxxx --summary "**会议结论**\n- 方案 A 通过\n- 下周跟进排期"
+
+# 从文件读取总结内容
+lark-cli minutes +summary --minute-token obcnxxxxxxxxxxxxxxxxxxxx --summary @summary.md
+
+# 从 stdin 读取
+echo "**结论**" | lark-cli minutes +summary --minute-token obcnxxxxxxxxxxxxxxxxxxxx --summary @-
+
+# 预览 API 调用
+lark-cli minutes +summary --minute-token obcnxxxxxxxxxxxxxxxxxxxx --summary @summary.md --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--minute-token <token>` | 是 | 妙记 Token |
+| `--summary <text>` | 是 | 替换后的总结内容，支持 `@file` / `@-`（stdin） |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 核心约束
+
+### 1. 先读后写
+
+替换前建议先用 `lark-cli minutes +detail --minute-tokens <token> --summary` 读取当前总结，确认 `minute_token` 与待替换内容无误。
+
+### 2. Markdown 展示说明
+
+接口接受任意总结文本，**不会因 Markdown 格式校验失败而拒绝请求**。妙记客户端通常只能良好渲染以下 Markdown 子集；不支持的语法（如链接、代码块、四级标题等）会**按原始文本展示**（保留 Markdown 标记字符，不会渲染成对应样式）。Agent 写入时应优先使用可展示语法，避免用户在妙记里看到字面量的 `[链接](url)`、`` `code` `` 等：
+
+| 支持 | 写法 | 示例 |
+|------|------|------|
+| 纯文本 | 普通段落 | `本次会议讨论了 Q2 预算` |
+| 换行 | `\n` 或空行 | 分段落书写 |
+| 一级标题 | `# ` + 标题文字 | `# 会议结论` |
+| 二级标题 | `## ` + 标题文字 | `## 行动项` |
+| 三级标题 | `### ` + 标题文字 | `### 跟进事项` |
+| 加粗 | `**文字**` | `**重点结论**` |
+| 无序列表 | `- ` 或 `* ` | `- 跟进预算审批` |
+| 有序列表 | `1. ` | `1. 确认需求` |
+
+> 标题语法建议：`#` 后保留空格，并优先使用 1～3 级（`#` / `##` / `###`）。四级及以上（`####`）无法渲染，会以原始文本形式展示。
+
+**不建议使用**（会按原始文本展示）：链接、图片、代码块、表格、引用块、斜体、删除线、四级及以上标题等。
+
+合法示例：
+
+```markdown
+# 会议结论
+
+## 核心讨论
+
+**方案 A 通过**，下周启动排期。
+
+### 待跟进
+- 预算审批
+- 排期确认
+
+1. 张三负责预算
+2. 李四负责排期
+```
+
+### 3. 所需权限
+
+| 身份 | 所需权限 |
+|------|---------|
+| user | `minutes:minutes:update` |
+
+## 输出结果
+
+```json
+{
+  "minute_token": "obcnxxxxxxxxxxxxxxxxxxxx",
+  "updated": true
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `minute_token` | 妙记 Token |
+| `updated` | 是否已成功更新 |
+
+## 如何获取 minute_token
+
+| 来源 | 获取方式 |
+|------|---------|
+| 妙记 URL | 从 URL 末尾提取，如 `https://sample.feishu.cn/minutes/obcnxxxxxxxxxxxxxxxxxxxx` |
+| 妙记搜索 | `lark-cli minutes +search --query "关键词"` |
+| 会议产物查询 | `lark-cli vc +detail --meeting-ids <id>` 或 `vc +recording`, 拿到 `minute_token`, 然后走 `minutes +detail` |
+
+## 常见错误与排查
+
+| 错误现象 | 错误码 | 根本原因 | 解决方案 |
+|---------|--------|---------|---------|
+| 总结展示为原始 Markdown 文本 | — | 总结含链接、四级标题等妙记端无法渲染的语法 | 改用标题（#～###）、加粗、列表等可展示格式；接口不会因此报错 |
+| 参数无效 | — | `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 产物
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -0,0 +1,138 @@
+# minutes +todo
+
+> **路由**：本命令操作**妙记内的 AI 待办**，不是飞书任务（Task）。用户说「在妙记里新建待办」时**必须**用本命令，**禁止**走 `lark-cli task` / `tasklists list` / `task +create`。详见 [lark-minutes/SKILL.md](../SKILL.md) 第 6 节。
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+对妙记中的待办做新增 / 更新 / 删除（单条或批量）。写操作。
+
+本 skill 对应 shortcut：`lark-cli minutes +todo`（调用 `POST /open-apis/minutes/v1/minutes/{minute_token}/todo`）。
+
+## 典型触发表达
+
+- "给这条妙记加一条/多条待办"
+- "把某条待办改成……"
+- "标记某条待办为已完成 / 取消完成"
+- "删除某条待办"
+
+## 命令
+
+**单条模式**：`--operation` + 对应字段。  
+**批量模式**：`--todos` JSON 数组（与单条 flags 互斥），一次请求可混合 `add` / `update` / `delete`。
+
+```bash
+# 单条：新增
+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":"新待办","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
+
+# 单条：更新 / 删除
+lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation update --todo-id 1234567890 --todo "整理会议纪要" --is-done --as user
+lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation delete --todo-id 1234567890 --as user
+
+# 预览
+lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add --todo "新待办" --is-done --dry-run --as user
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--minute-token <token>` | 是 | 妙记 Token |
+| `--operation <op>` | 单条模式 | `add` / `update` / `delete`；与 `--todos` 互斥 |
+| `--todo <text>` | 单条 add/update | 待办纯文本 |
+| `--is-done` | 单条 add/update | `--is-done` = true，`--is-done=false` = false |
+| `--todo-id <id>` | 单条 update/delete | 已有待办 id |
+| `--todos <json>` | 批量模式 | JSON 数组，支持 `@file` / `@-`；与单条 flags 互斥 |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 单条模式
+
+| `--operation` | 必填参数 | 禁止参数 |
+|---------------|----------|----------|
+| `add` | `--todo` + `--is-done` | `--todo-id` |
+| `update` | `--todo-id` + `--todo` + `--is-done` | — |
+| `delete` | `--todo-id` | `--todo`、`--is-done` |
+
+## 批量模式：`--todos`
+
+每条元素字段与 API `todo_items[]` 一致：
+
+| JSON 字段 | add | update | delete |
+|-----------|-----|--------|--------|
+| `operation` | 必填 | 必填 | 必填 |
+| `content` | 必填 | 必填 | 禁止 |
+| `is_done` | 必填 | 必填 | 禁止 |
+| `todo_id` | 禁止 | 必填 | 必填 |
+
+示例 `todos.json`：
+
+```json
+[
+  {"operation": "add", "content": "晚上好1", "is_done": true},
+  {"operation": "add", "content": "晚上好2", "is_done": false}
+]
+```
+
+数组顺序会原样写入请求体；端上展示顺序仍可能受完成状态分组影响。
+
+## 核心约束
+
+### 1. 先读后写，待办 id 如何获取
+
+更新 / 删除前先用 `lark-cli minutes +detail --minute-tokens <token> --todo` 读取当前待办。返回的每条待办带 `todo_id` 字段。
+
+> 待办 id 仅用于程序内部定位，不必展示给用户。
+
+### 2. 待办内容为纯文本
+
+`content` **不是 Markdown**，请直接传入待办描述文字。
+
+### 3. 所需权限
+
+| 身份 | 所需 scope |
+|------|-----------|
+| user | `minutes:minutes:update` |
+
+## 输出结果
+
+```json
+{
+  "minute_token": "obcnxxxxxxxxxxxxxxxxxxxx",
+  "count": 2,
+  "updated": true
+}
+```
+
+单条模式额外包含 `"operation": "add"`。
+
+## 常见错误与排查
+
+| 错误现象 | 解决方案 |
+|---------|---------|
+| 未指定操作 | 单条模式传 `--operation`，或批量传 `--todos` |
+| `--todos` 与单条 flags 冲突 | 二选一 |
+| `todos[i]` 校验失败 | 检查该条 `operation` 与字段组合 |
+| `error.type` = `no_edit_permission` | **妙记资源无编辑权**：向妙记所有者申请该妙记的编辑/协作权限；**不要**走 `auth login --scope` |
+| 缺少 OAuth scope（`permission_violations` 含 `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)
+- [lark-shared](../../lark-shared/SKILL.md)

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

@@ -0,0 +1,41 @@
+# minutes +update
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+修改飞书妙记的标题（topic）。
+
+本 skill 对应 shortcut：`lark-cli minutes +update`。
+
+## 典型触发表达
+
+- "把这个妙记的标题改成 xxx"
+- "重命名这条妙记"
+- "修改妙记标题"
+
+## 命令示例
+
+```bash
+lark-cli minutes +update --minute-token xxx --topic "周会纪要 2026-05-18"
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--minute-token <token>` | 是 | 妙记的唯一标识，可从妙记 URL 末尾路径提取 |
+| `--topic <string>` | 是 | 新的妙记标题 |
+
+## 认证与权限
+- 所需 scope：`minutes:minutes:update`。
+
+## 输出结果
+
+| 字段 | 说明 |
+|------|------|
+| `minute_token` | 被修改的妙记 Token，与输入的 `--minute-token` 一致，可继续用于查询妙记信息、下载媒体或获取纪要产物 |
+| `topic` | 修改后的妙记标题，与输入的 `--topic` 一致 |
+
+## 参考
+
+- [lark-minutes](../SKILL.md) -- 妙记相关功能说明
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/skills/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` 调用 `minutes +detail`**
+   - 从返回的 `minute_url` 中提取路径最后一段，得到 `minute_token`。
+   - 如果用户要的是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，继续调用：
+     ```bash
+     lark-cli minutes +detail --minute-tokens <minute_token> --summary --todo --chapter --keyword --transcript
+     ```
+   - `minutes +detail --minute-tokens` 会返回妙记产物（总结、待办、章节、关键词、逐字稿）；必要时还会把逐字稿落地到本地文件。
+
+> **异步生成提示**：API 会立即返回 `minute_url`，但妙记可能仍在异步生成中，您可以直接通过该妙记链接查看当前的处理状态和转写结果。
+
+## 命令示例
+
+```bash
+# 通过已上传到云空间（云盘/云存储）的 file_token 生成妙记
+lark-cli minutes +upload --file-token boxcnxxxxxxxxxxxxxxxx
+
+# 通过 minute_token 继续获取妙记产物（--summary --todo --chapter --keyword --transcript 按需传入）
+lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --summary
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--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 minutes +detail --minute-tokens <minute_token>`
+
+> **边界说明**：`minutes +upload` 本身只负责把文件转成妙记并返回 `minute_url`。纪要内容、逐字稿、文字稿、撰写文字、总结、待办、章节属于后续产物获取，应由 [minutes +detail](lark-minutes-detail.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) -- 认证和全局参数

package/skills/lark-note/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: lark-note
+version: 1.0.0
+description: "飞书会议纪要（Note）直查：已知 note_id 时查询纪要详情、展示类型、关联文档 token，并读取 unified 原始逐字记录。当用户已持有 note_id，或从文档显式 vc-node-id 获得 note_id 时使用。不负责会议/日程/妙记定位、文档标题搜索或 Docx 正文读取。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli note --help"
+---
+
+# note (v1)
+
+身份：仅使用 `--as user`。使用前阅读 [`../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. 了解不同会议产物的组成部分，以便根据需求决策使用哪种产物的数据
+
+Note 域只接受显式 `note_id`：用户直接提供，或 `docs +fetch` 返回的 `<vc-transcribe-tab vc-node-id="...">` 中的 `vc-node-id`。不要从 `doc_token`、标题、正文或 backlink 反推 `note_id`。
+
+## 命令路由
+
+| 用户表达 / 上下文 | 路由 |
+|---------|------|
+| 已知 `note_id`，查纪要类型 / 文档 token | `note +detail --note-id NOTE_ID` |
+| `docs +fetch` 返回 `<vc-transcribe-tab vc-node-id="...">` | 取 `vc-node-id` 作为 `NOTE_ID`，先 `note +detail --note-id NOTE_ID` |
+| 只持有 `meeting_id` | 先 `vc +detail --meeting-ids <id>` 拿 `note_id`，再 `note +detail --note-id NOTE_ID` |
+| 只持有 `minute_token`（妙记 URL） | 先 `minutes +detail --minute-tokens <token>` 顶层取 `note_id`，再 `note +detail --note-id NOTE_ID`（不要把 `minute_token` 当 `note_id`） |
+| 只持有日程 `event_id` | 先 `calendar +meeting --event-ids <id>` 拿 `meeting_id`，再按上一行继续 |
+| 已知 `note_id`，读纪要正文 | `note +detail` → `docs +fetch --doc <note_doc_token>` |
+| 已知 `note_id`，查 unified 原始记录 / 逐字稿 | `note +transcript --note-id NOTE_ID` |
+| 只有自然语言纪要标题，用户要逐字稿 / 原始记录 / 谁说了什么 | 不进本 skill；先走文档搜索与 `docs +fetch`，拿到 `vc-node-id` 后再回来 |
+
+## `note_display_type` 路由
+
+| `note +detail` 结果 | 用户要逐字稿 / 原始记录时 |
+|------|---------------|
+| `normal` + `verbatim_doc_token` 非空 | `docs +fetch --doc <verbatim_doc_token>` |
+| `unknown` + `verbatim_doc_token` 非空 | 先按独立文档处理；不要猜成 unified |
+| `unknown` + 无逐字稿 token | 停止重试并说明无法确定逐字稿入口 |
+| `unified` | `note +transcript --note-id <note_id>` |
+
+判别键是 `note_display_type`，不是 `verbatim_doc_token` 是否为空：unified 纪要也可能返回非空 `verbatim_doc_token`。
+
+## 关键字段
+
+- `note_id`：Note 域唯一入口。
+- `note_display_type`：`unknown` / `normal` / `unified`。
+- `note_doc_token`：纪要正文文档，正文读取交给 [lark-doc](../lark-doc/SKILL.md)。
+- `verbatim_doc_token`：普通纪要逐字稿文档；unified 逐字稿不按这个 token 路由。
+
+## 不在本 Skill 范围
+
+- 通过 `meeting_id` 定位纪要（`note_id`）→ [lark-vc](../lark-vc/SKILL.md)（`vc +detail`）。
+- 通过 `minute_token` 定位纪要（`note_id`）→ [lark-minutes](../lark-minutes/SKILL.md)（`minutes +detail` 顶层返回 `note_id`）。
+- 通过日程 `event_id` 定位会议(`meeting_id`) / 用户绑定纪要(`meeting_note`) → [lark-calendar](../lark-calendar/SKILL.md)（`calendar +meeting`）。
+- 自然语言纪要标题搜索 → [lark-drive](../lark-drive/SKILL.md) / [lark-doc](../lark-doc/SKILL.md)。
+- Docx 正文读取 → [lark-doc](../lark-doc/SKILL.md)。
+- 妙记基础信息与媒体文件 → [lark-minutes](../lark-minutes/SKILL.md)。
+
+## Shortcuts
+
+| Shortcut | 何时读 reference |
+|----------|------|
+| [`+detail`](references/lark-note-detail.md) | 需要解释输出字段或根据展示类型继续路由 |
+| [`+transcript`](references/lark-note-transcript.md) | 需要拉取 unified 原始记录或处理本地输出文件 |
+
+## 核心概念
+
+- **会议纪要（Note）**：视频会议结束后生成的结构化文档，通过 `note_id` 标识。一个 Note 包含 AI 智能纪要文档、逐字稿文档和会中共享文档。
+- **note_id**：纪要的唯一标识符，可通过 `vc +detail --meeting-ids` 获取。
+- **AI 智能纪要（MainDoc）**：AI 生成的会议总结与待办，对应 `note_doc_token`。
+- **逐字稿（VerbatimDoc）**：会议的逐句发言记录，含说话人和时间戳，对应 `verbatim_doc_token`。
+- **共享文档（SharedDoc）**：会中投屏共享的文档，对应 `shared_doc_tokens`。
+
+## 核心场景
+
+### 1. 通过 note_id 获取纪要文档 Token
+
+1. 当用户已有 `note_id`，需要获取对应的 `note_doc_token`、`verbatim_doc_token` 或 `shared_doc_tokens` 时，使用 `note +detail`。
+2. `note_id` 通常来自 `vc +detail` 的返回结果。
+3. 获取到文档 Token 后，可使用 `docs +fetch` 读取文档内容，或使用 `drive metas batch_query` 获取文档元信息。
+
+```bash
+# 1. 从会议获取 note_id
+lark-cli vc +detail --meeting-ids <meeting_id>
+
+# 2. 用 note_id 拿文档 Token
+lark-cli note +detail --note-id <note_id>
+
+# 3. 读取纪要文档内容
+lark-cli docs +fetch --doc <note_doc_token> --doc-format markdown
+```

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

@@ -0,0 +1,26 @@
+# note +detail
+
+通过 `note_id` 查询会议纪要详情，获取下挂文档 Token（AI 智能纪要、逐字稿、会中共享文档）。只读，仅支持 `--as user`。
+
+## 命令
+
+```bash
+lark-cli note +detail --note-id <note_id>
+```
+
+## `note_id` 来源
+
+- 可以来自用户直接给出的 `note_id`。
+- 如果入口是文档，先由 [lark-doc](../../lark-doc/SKILL.md) 读取 Docx；只有 `<vc-transcribe-tab vc-node-id="...">` 的 `vc-node-id` 可以作为 `note_id`。
+- 没有 `vc-node-id` 时，不要从 `doc_token`、标题、正文或 backlink 反推 `note_id`。
+
+## 输出后的路由
+
+| detail 字段 | 后续动作 |
+|---------|---------|
+| `note_doc_token` | 读纪要正文 / 总结 / 待办 / 章节：`docs +fetch --doc <note_doc_token>` |
+| `note_display_type=normal` + `verbatim_doc_token` | 读逐字稿：`docs +fetch --doc <verbatim_doc_token>` |
+| `note_display_type=unknown` + `verbatim_doc_token` | 先按普通独立逐字稿文档读取；不要猜成 unified |
+| `note_display_type=unified` | 读逐字稿 / 原始记录：转 [`note +transcript`](lark-note-transcript.md) |
+
+判别键是 `note_display_type`。即使 unified 纪要返回了非空 `verbatim_doc_token`，逐字稿仍按 unified 路由。

package/skills/lark-note/references/lark-note-transcript.md

@@ -0,0 +1,23 @@
+# note +transcript
+
+只在 `note +detail` 已确认 `note_display_type=unified` 时使用。普通纪要逐字稿是独立 Docx 文档，应回到 [lark-doc](../../lark-doc/SKILL.md) 读取 `verbatim_doc_token`。
+
+```bash
+lark-cli note +transcript --note-id NOTE_ID
+```
+
+## 行为契约
+
+- CLI 会先校验该 Note 是否为 `unified`；不是 unified 时不拉取 transcript。
+- CLI 内部自动翻页并拼接完整内容；任一页失败时整体报错，不保存半截 transcript。
+- 默认保存到 `./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` 非空 | 先按独立逐字稿文档读取 |