@amaster.ai/pi-lark 0.1.2-beta.54 → 0.1.2-beta.56

package/skills/lark-drive/references/lark-drive-download.md

@@ -3,7 +3,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-从飞书云空间（云盘/云存储）下载文件到本地。
+从飞书云空间（云盘/云存储）下载文件到本地。下载对象是 Drive **文件**（上传的 PDF/zip/图片/音视频等文件），以及支持 Wiki URL / Wiki token。
 
 ## 命令
 
@@ -13,8 +13,27 @@ lark-cli drive +download --file-token boxbc_xxx --output ./report.pdf
 
 # 只提供 token，默认保存到当前目录
 lark-cli drive +download --file-token boxbc_xxx
+
+# 直接传 URL，CLI 自动解析类型和 token
+lark-cli drive +download --url "https://example.feishu.cn/file/<FILE_TOKEN>" --output ./report.pdf
+
+# Wiki URL 也可直接传，CLI 会先解析到底层 obj_token/obj_type（obj_type 必须是 file）
+lark-cli drive +download --url "https://example.feishu.cn/wiki/<WIKI_NODE_TOKEN>" --output ./report.pdf
+
+# 只有裸 Wiki node token 时，显式传 --wiki-token，让 CLI 先解析底层文件
+lark-cli drive +download --wiki-token "<WIKI_NODE_TOKEN>" --output ./report.pdf
 ```
 
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 条件必填 | Drive 文件 token；与 `--url` / `--wiki-token` 三选一 |
+| `--url` | 条件必填 | 飞书文件 URL 或 Wiki URL；CLI 自动解析类型和 token |
+| `--wiki-token` | 条件必填 | 裸 Wiki node token；CLI 先解析到底层 Drive 文件 |
+| `--output` | 否 | 本地输出路径；不传时默认保存到当前目录 |
+| `--overwrite` | 否 | 覆盖已存在的输出文件；不传时目标已存在会报错 |
+
 ## URL 解析
 
 从飞书文件 URL 提取 token：
@@ -25,9 +44,17 @@ https://xxx.feishu.cn/drive/file/boxbc_xxx
                                   file_token
 ```
 
+Wiki URL / 裸 Wiki node token 会先解析到底层文档，解析后会在输出里附带 `wiki_token` 和 `wiki_node`（含底层 `obj_token`/`obj_type`）。
+
+## 关键约束
+
+- Wiki 节点解析后的 `obj_type` 必须是 `file`；不确定 token 类型时，先用 `lark-cli drive +inspect --url <TOKEN> --type wiki` 检查。
+
 ## 排障
 
-- 如果返回 `HTTP 403`，可以使用 [lark-drive-preview](lark-drive-preview.md) 下载源文件产物。
+- 如果返回 `permission_denied`，或最终下载返回 `HTTP 403`，按错误 `hint` 使用 `lark-cli drive +preview --file-token <FILE_TOKEN> --type source_file --output <path>` 获取预览产物。
+- 如果返回限流错误，停止立即重试，稍后按指数退避重试。
+- 如果目标（或 Wiki 解析出的底层文档）是 `docx` / `sheet` / `bitable` / `slides` 等在线文档，`+download` 无法直接下载，会返回 typed validation error；改用 [lark-drive-export](lark-drive-export.md) 渲染成 pdf / xlsx / pptx / markdown 等格式。
 
 ## 参考
 

package/skills/lark-drive/references/lark-drive-export.md

@@ -147,6 +147,7 @@ lark-cli drive +export \
 | `1069914` | token 非法或 token/type 不匹配；常见原因是把 Wiki node token 当作底层 `docx` / `sheet` / `bitable` token 使用，没有传 `--doc-type wiki` | 优先改用 `--url <Wiki URL>`；只有裸 Wiki token 时，用 `--token <WIKI_NODE_TOKEN> --doc-type wiki`。不确定 token 类型时，先用 `lark-cli drive +inspect --url <TOKEN> --type wiki` 检查是否能解包为 Wiki node；如果不是 Wiki token，再检查 token 来源、`--doc-type` 是否与实际资源类型一致 |
 | `1069902` | 没有当前导出任务所需权限 | 不要直接重试同一命令；先确认当前 `--as` 身份是否能访问该文档、是否有下载/导出权限，以及文档是否受分享、密级或租户策略限制。需要补权限时，让文档 owner 或管理员授权后再执行 |
 | `99991400` / `rate_limit` | OpenAPI 请求频率受限 | 立即停止并按错误 `hint` 处理：没有 `ticket` 时，至少等待 1 分钟后重跑原 `drive +export`；已有 `ticket` 时，只执行 `drive +task_result --scenario export` 续查，不要重复创建任务。持续限频时从 1 分钟开始指数退避 |
+| `9499` + `too many request(s)` | 导出任务接口的另一种限频响应；同一个 `9499` 在其它 Drive 接口也可能表示参数类型错误，CLI 会结合服务端消息区分 | 按 `rate_limit` 处理：立即停止，等待至少 1 分钟并指数退避；已有 `ticket` 时只续查该任务，不要重新创建 |
 | `99991679` | 缺少 OpenAPI scope | 按错误 envelope 中的 `missing_scopes` / `required_scope` / `hint` 补齐授权；常见方式是重新执行 `lark-cli auth login --scope "<缺失 scope>"`。补 scope 前不要反复重试导出命令 |
 
 ## 推荐续跑方式

package/skills/lark-drive/references/lark-drive-member-remove.md

@@ -0,0 +1,59 @@
+# drive +member-remove（移除协作者权限）
+
+> 这是高风险写操作。真实执行会移除权限，需要核对资源和成员后显式加 `--yes`。
+
+## 命令
+
+```bash
+lark-cli drive +member-remove \
+  --token "<bare_token_or_url>" \
+  --type docx \
+  --member-id "ou_xxx" \
+  --member-type openid \
+  --yes
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--token` | 是 | 裸 token 或完整 URL。路径支持 `/drive/folder/`、`/docx/`、`/doc/`、`/sheets/`、`/base/`、`/bitable/`、`/wiki/`、`/file/`、`/mindnotes/`、`/slides/`、`/minutes/`、`/page/`；URL 可从路径推断类型，裸 token 必须同时传 `--type`。 |
+| `--type` | 条件必填 | 资源类型：`docx` / `doc` / `sheet` / `bitable` / `file` / `folder` / `wiki` / `mindnote` / `slides` / `minutes` / `apps`。完整 URL 可省略。 |
+| `--member-id` | 是 | 要移除的单个协作者 ID。逗号分隔的多成员输入会被拒绝；批量场景应逐个调用。 |
+| `--member-type` | 是 | ID 类型：`email` / `openid` / `openchat` / `opendepartmentid` / `userid` / `unionid` / `groupid` / `wikispaceid`。 |
+| `--member-kind` | 条件必填 | 仅 `--member-type=wikispaceid` 使用：未启用知识库成员分组时传 `wiki_space_member`，启用后根据权限传 `wiki_space_viewer` 或 `wiki_space_editor`。 |
+| `--perm-type` | 否 | 仅 wiki 协作者使用：`container`（默认，当前页面及子页面）或 `single_page`（仅当前页面）。 |
+| `--dry-run` | 否 | 只预览 DELETE URL、query 和 body，不调用接口。 |
+| `--yes` | 真实执行时是 | 确认高风险权限移除操作。 |
+
+## 输出
+
+以移除 `openid` 类型的用户协作者为例，成功后返回：
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "removed": true,
+    "resource_token": "doxcnxxx",
+    "resource_type": "docx",
+    "member_id": "ou_xxx",
+    "member_type": "openid",
+    "member_kind": "user"
+  }
+}
+```
+
+Wiki 普通协作者还会返回 `perm_type`；`wikispaceid` 返回所传的 `member_kind`。
+
+`removed: true` 表示删除请求成功完成，不保证该权限此前一定存在。
+
+## 行为说明
+
+- **身份支持**：支持 `--as user` 和 `--as bot`。
+- **部门协作者**：`--member-type=opendepartmentid` 只能配合 `--as user`；bot 身份会在客户端提前拒绝。
+- **安全编码**：资源 token 和 member ID 都作为独立 path segment 编码。
+- **Wiki 范围**：普通 wiki 协作者默认删除 `container` 权限；只删除当前页面权限时显式传 `single_page`。
+- **Wiki 空间成员**：`--member-type=wikispaceid` 仅支持 `--type=wiki`；必须用 `--member-kind` 指明成员角色，并且不能同时传 `--perm-type`。
+- **错误处理**：OpenAPI 返回的 typed error 原样透传，可根据错误信封中的 subtype、code、hint 和权限信息处理。

package/skills/lark-drive/references/lark-drive-preview.md

@@ -2,7 +2,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、权限处理和安全规则。
 
-查看或下载 Drive 文件内容，或列出并获取文件可用的预览产物。这个 shortcut 不猜测默认类型：
+查看或下载 Drive 文件内容，或列出并获取文件可用的预览产物。对象是 Drive **文件**，也支持 Wiki URL / node token（CLI 先把 Wiki 节点解析到底层文件，`obj_type` 必须是 `file`）。这个 shortcut 不猜测默认类型：
 
 - 如果只需要查看或下载文件内容，或不关心 PDF/text/image 等转换预览，优先使用 `--type source_file --output <path>`
 - 只想看候选项时，用 `--list-only`
@@ -20,6 +20,22 @@ lark-cli drive +preview \
   --type source_file \
   --output ./artifacts/source
 
+# 推荐：直接传 URL，CLI 自动解析类型和 token
+lark-cli drive +preview \
+  --url "https://example.feishu.cn/file/<FILE_TOKEN>" \
+  --list-only
+
+# Wiki URL 也可直接传，CLI 会先解析到底层 obj_token/obj_type（obj_type 必须是 file）
+lark-cli drive +preview \
+  --url "https://example.feishu.cn/wiki/<WIKI_NODE_TOKEN>" \
+  --type source_file \
+  --output ./artifacts/source
+
+# 只有裸 Wiki node token 时，显式传 --wiki-token
+lark-cli drive +preview \
+  --wiki-token "<WIKI_NODE_TOKEN>" \
+  --list-only
+
 # 列出可用预览候选项
 lark-cli drive +preview \
   --file-token "<FILE_TOKEN>" \
@@ -50,7 +66,9 @@ lark-cli drive +preview \
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--file-token` | 是 | Drive 文件 token |
+| `--file-token` | 条件必填 | Drive 文件 token；与 `--url` / `--wiki-token` 三选一 |
+| `--url` | 条件必填 | 飞书文件 URL 或 Wiki URL；CLI 自动解析类型和 token |
+| `--wiki-token` | 条件必填 | 裸 Wiki node token；CLI 先解析到底层 Drive 文件 |
 | `--type` | 条件必填 | 预览类型；优先使用 `--list-only` 返回的 `type`，如 `pdf` / `html` / `text` / `png` / `jpg` / `source_file` |
 | `--version` | 否 | 文件版本号 |
 | `--list-only` | 否 | 仅返回候选项，不下载 |
@@ -90,6 +108,7 @@ lark-cli drive +preview \
 - `--type source_file` 用于查看文件内容，不依赖 `--list-only` 返回的候选项；它适合读取或保存源内容，不等同于 PDF/text/image 等转换预览
 - 候选项状态来自后端 `preview_status` 枚举，例如 `READY` / `PROCESSING` / `FAILED` / `NO_SUPPORT`
 - 本地文件名在未显式带扩展名时，会结合响应头自动补扩展名
+- Wiki URL / 裸 Wiki node token 会先解析到底层文档，解析后会在输出里附带 `wiki_token` 和 `wiki_node`（含底层 `obj_token`/`obj_type`）；`obj_type` 必须是 `file`。如果 Wiki 指向 `docx` / `sheet` / `bitable` / `slides` 等在线文档，`+preview` 无法直接处理，CLI 会返回 typed validation error，并在 hint 中提示改用 [lark-drive-export](lark-drive-export.md)
 
 ### 参考
 

package/skills/lark-drive/references/lark-drive-push.md

@@ -134,6 +134,8 @@ lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
 
 `+push` 的失败项带结构化字段，agent 必须优先读 `items[].error_class` / `phase` / `code`，不要只看自然语言 `error` 文本。`summary.aborted=true` 表示命令已经遇到终止性错误并停止后续批处理；这时**不要原样重试**，先修复根因。
 
+`retryable=true` 只表示修复根因或等待后可以再次尝试，不表示应该立即、无限重放整个 push；重试时采用有上限的指数退避和抖动。
+
 常见终止性错误：
 
 | `error_class` | 常见 `code` | 含义 | Agent 应对 |
@@ -144,8 +146,10 @@ lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
 | `invalid_api_parameters` | `1061002` | API 参数被服务端拒绝 | 停止重试，检查 `--folder-token`、覆盖模式、`file_token`、文件名和上传参数；不要对同一参数组合批量重试 |
 | `parent_node_missing` | `1061044` | 上传 / 建目录使用的父文件夹不存在或当前身份不可见 | 停止重试，检查 `--folder-token` 是否仍存在、是否有权限、父目录是否在 push 过程中被删除；不要继续上传同一目录树 |
 | `parent_sibling_limit` | `1062507` | 目标父文件夹单层子节点数量超过上限 | 停止重试，清理目标目录、换一个 `--folder-token`，或把上传内容拆到多个子目录 |
+| `quota_exceeded` | `1061101` / `1061061` | 租户或当前用户的 Drive 容量配额已满 | 停止重试，释放容量、调整目标位置或扩容后再执行 push |
 | `rate_limited` | `99991400` | 触发频控 | 停止当前批次，退避后再重试 |
-| `server_error` | `1061001` / `2200` | Drive 服务端异常 | 停止当前批次，稍后重试；保留 `log_id` 便于排查 |
+| `conflict` | `1061045` | 同一目标发生资源竞争 | 停止当前批次，避免并发操作同一目标；退避后有限重试 |
+| `server_error` | `1663` / `1061001` / `2200` / HTTP 5xx | Drive 服务端或网关异常 | 停止当前批次，稍后有限重试 |
 
 非终止但需要解释的状态：
 

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

@@ -25,6 +25,8 @@
 >
 > **`--query` 最长 30 个字符**：按字符数（Unicode 码点）算，中文每字算 1 个，与 ASCII 同口径；超过 30 会被服务端拒绝（`99992402 field validation failed`，**是报错不是截断**）。长关键词必须先压缩成核心实体 + 主题词（如把整句问题压成「项目名 + 主题」再搜），不要把整句原问塞进 `--query`。
 >
+> **按完整标题定位：** 使用 `--only-title`；标题不超过 30 个字符时直接查询，超长标题使用不超过限制的稳定片段召回，再按返回标题严格匹配。使用相同 query 和过滤条件按 `page_token` 检查，最多 3 页；仅在 `has_more=false` 且跨页恰好一个严格匹配时继续写操作，否则请用户缩小范围或补充信息。`drive files list` 只用于枚举已知文件夹的直接子项。
+>
 > **列表型请求不要硬塞关键词**：如果用户只是要求"我这月创建的所有文档"、"最近半年我编辑过的文档"、"按类型分类统计"这类范围浏览 / 汇总请求，且没有给出标题片段或业务关键词，应使用 `--query ""` 搭配 `--created-by-me`、`--mine`、`--created-*`、`--edited-*`、`--doc-types` 等过滤条件。不要把"查找"、"所有文档"、"最近更新过"、"按类型分类统计"这类动作词或统计意图放进 `--query`，否则会把本来应靠 filter 命中的结果过度收窄。
 >
 > **标题词 + 正文词联合搜索**：如果用户同时给出标题关键词和正文关键词，并要求同一资源同时满足两项条件，优先执行一条普通联合搜索：`lark-cli drive +search --query "标题词 正文词"`，并在同一条命令中叠加用户指定的 `--folder-tokens`、`--doc-types` 等过滤条件。不要把这种联合搜索拆成“标题搜索 + 正文搜索”后自行拼交集；也不要把 `--only-title` 或 `intitle:` 用作主候选路径。只有用户明确只查标题时，才使用 `--only-title` 或 `intitle:`。

package/skills/lark-minutes/SKILL.md

@@ -20,7 +20,9 @@ metadata:
 
 ## 身份
 
-所有 minutes 命令默认使用 `--as user`。
+身份是跨命令工作流的状态：一旦某个 `minute_token` / `note_id` 由某个身份取得，后续消费它的命令必须显式沿用相同 `--as`，不要依赖 profile 默认身份。完整规则见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 的「身份延续」。
+
+所有 minutes 命令默认使用 `--as user`。`+search`、`minutes get`、`+detail`、`+download` 和 `+apply-permission` 也支持 `--as bot`（bot 只能访问 / 操作 bot 有权限的妙记）。精确身份支持以 `<command> --help` 为准。
 
 ## Shortcuts
 
@@ -31,7 +33,7 @@ metadata:
 | [`+download`](references/lark-minutes-download.md) | 下载妙记音视频媒体文件 |
 | [`+upload`](references/lark-minutes-upload.md) | 上传 file_token 生成妙记 |
 | [`+update`](references/lark-minutes-update.md) | 更新妙记标题 |
-| `+apply-permission` | 申请妙记查看或编辑权限 |
+| [`+apply-permission`](references/lark-minutes-apply-permission.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 总结全文 |
@@ -79,17 +81,21 @@ metadata:
 
 ### 3. 申请妙记权限
 
-遇到妙记没有查看或编辑权限时，引导用户申请对应权限；只有用户明确要申请时，才调用 `minutes +apply-permission`。
+遇到妙记没有查看或编辑权限时，引导用户申请对应权限；只有用户明确要申请时，才调用 `minutes +apply-permission`。使用前必读 [`+apply-permission` reference](references/lark-minutes-apply-permission.md)（write 操作，含 user/bot 身份与权限语义）。
 
 只有当用户明确要求"申请查看权限"、"申请编辑权限"、"帮我申请这条妙记权限"时，才调用：
 
 ```bash
-lark-cli minutes +apply-permission --minute-token <token> --perm view|edit
+lark-cli minutes +apply-permission --minute-token <token> --perm view|edit --as user
+lark-cli minutes +apply-permission --minute-token <token> --perm view|edit --as bot
 ```
 
 这是向妙记所有者发起权限申请，不代表立即获得权限。
 
-**安全约束**：遇到无权限错误时，不要自动调用 `+apply-permission`；先把无权限事实告知用户，只有用户明确要求申请权限时才发起申请。
+**安全约束**：
+- 遇到无权限错误时，不要自动调用 `+apply-permission`；先把无权限事实告知用户，只有用户明确要求申请权限时才发起申请。
+- **必须沿用触发无权限错误时的来源身份**：例如 `--as bot` 读取妙记时遇到无权限，申请也要用 `--as bot`，不要切到 user 身份申请。
+- **禁止**用切换身份的方式绕过资源权限（例如 bot 无权限时改用 user 身份重新读取）。
 
 ### 4. 上传音视频文件生成妙记（并可继续获取纪要 / 逐字稿）
 

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

@@ -0,0 +1,95 @@
+# 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」 |
+| 申请后仍无权限 | 所有者尚未同意 | 这是异步申请，需等待所有者处理；不代表命令执行失败 |
+
+## 参考
+
+- [lark-minutes](../SKILL.md) — 妙记全部命令
+- [minutes +detail](lark-minutes-detail.md) — 妙记内容与产物查询
+- [lark-shared](../../lark-shared/SKILL.md) — 身份延续与权限恢复规则

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

@@ -1,7 +1,7 @@
 
 # minutes +detail
 
-通过 `minute_token` 查询妙记详情，按需获取 AI 产物（总结/待办/章节/逐字稿/关键词）。只读。
+通过 `minute_token` 查询妙记详情，按需获取 AI 产物（总结/待办/章节/逐字稿/关键词）。只读，支持 `--as user` / `--as bot`。
 
 > `--summary` / `--todo` / `--chapter` / `--keyword` / `--transcript` 至少一个；不传任何产物 flag 时只返回基础信息（如 `title`），AI 产物字段都不会出现。一次性获取所有产物：`--summary --todo --chapter --keyword --transcript`。
 
@@ -46,17 +46,18 @@ lark-cli minutes +detail --minute-tokens obcxxx --transcript --overwrite --outpu
 
 ## 典型链路：从 minute_token 拿纪要文档 token
 
-只持有 `minute_token`（如妙记 URL 入口），又想拿 AI 智能纪要 / 逐字稿文档时：
+只持有 `minute_token`（如妙记 URL 入口），又想拿 AI 智能纪要 / 逐字稿文档时；每一步都要沿用同一个 `--as`（完整规则见 [lark-shared](../../lark-shared/SKILL.md) 的「身份延续」）：
 
 ```bash
 # 1. 取妙记关联的 note_id，没有关联会议纪要则为空
-lark-cli minutes +detail --minute-tokens <minute_token>
+lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --as bot
 
 # 2. 用 note_id 拿 note_doc_token / verbatim_doc_token / shared_doc_tokens
-lark-cli note +detail --note-id <note_id>
+#    沿用第 1 步的身份，不要省略 --as
+lark-cli note +detail --note-id <note_id> --as bot
 
-# 3. 读纪要 / 逐字稿正文
-lark-cli docs +fetch --api-version v2 --doc <note_doc_token> --doc-format markdown
+# 3. 读纪要 / 逐字稿正文（同样沿用第 1 步的身份）
+lark-cli docs +fetch --api-version v2 --doc <note_doc_token> --doc-format markdown --as bot
 ```
 
 > `minute_token` 不要直接传给 `note +detail`：必须先用本命令拿到 `note_id` 再调用 `note +detail`。

package/skills/lark-minutes/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,7 +121,7 @@ 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) 的权限恢复表） |
 
 ## 提示
 

package/skills/lark-note/SKILL.md

@@ -10,7 +10,7 @@ metadata:
 
 # note (v1)
 
-身份：仅使用 `--as user`。使用前阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。
+身份：`+detail` 支持 `--as user` / `--as bot`；`+transcript` 仅支持 `--as user`。`note_id` 若由某个身份取得（例如 `vc +detail --as bot`），`+detail` 必须显式沿用同一个 `--as`——不要依赖 profile 默认身份。完整身份延续规则见 [`../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、会议产物 & 文档的关联关系和职责划分
@@ -36,13 +36,15 @@ Note 域只接受显式 `note_id`：用户直接提供，或 `docs +fetch` 返
 
 | `note +detail` 结果 | 用户要逐字稿 / 原始记录时 |
 |------|---------------|
-| `normal` + `verbatim_doc_token` 非空 | `docs +fetch --doc <verbatim_doc_token>` |
+| `normal` + `verbatim_doc_token` 非空 | `docs +fetch --doc <verbatim_doc_token>`（沿用 `+detail` 用的身份） |
 | `unknown` + `verbatim_doc_token` 非空 | 先按独立文档处理；不要猜成 unified |
 | `unknown` + 无逐字稿 token | 停止重试并说明无法确定逐字稿入口 |
-| `unified` | `note +transcript --note-id <note_id>` |
+| `unified` | `note +transcript --note-id <note_id>`（仅支持 `--as user`） |
 
 判别键是 `note_display_type`，不是 `verbatim_doc_token` 是否为空：unified 纪要也可能返回非空 `verbatim_doc_token`。
 
+> **bot + unified 的边界**：`+transcript` 目前仅支持 `--as user`。如果 `+detail --as bot` 返回 `unified`，不要静默切到 `--as user` 继续——先停下来向用户说明"该纪要逐字稿只能以 user 身份读取"，只有用户明确同意才切换身份重试。
+
 ## 关键字段
 
 - `note_id`：Note 域唯一入口。
@@ -83,12 +85,12 @@ Note 域只接受显式 `note_id`：用户直接提供，或 `docs +fetch` 返
 3. 获取到文档 Token 后，可使用 `docs +fetch` 读取文档内容，或使用 `drive metas batch_query` 获取文档元信息。
 
 ```bash
-# 1. 从会议获取 note_id
-lark-cli vc +detail --meeting-ids <meeting_id>
+# 1. 从会议获取 note_id（这里以 bot 身份为例）
+lark-cli vc +detail --meeting-ids <meeting_id> --as bot
 
-# 2. 用 note_id 拿文档 Token
-lark-cli note +detail --note-id <note_id>
+# 2. 用 note_id 拿文档 Token；沿用第 1 步的身份，不要省略 --as
+lark-cli note +detail --note-id <note_id> --as bot
 
-# 3. 读取纪要文档内容
-lark-cli docs +fetch --doc <note_doc_token> --doc-format markdown
+# 3. 读取纪要文档内容；同样沿用第 1 步的身份
+lark-cli docs +fetch --doc <note_doc_token> --doc-format markdown --as bot
 ```

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

@@ -1,11 +1,12 @@
 # note +detail
 
-通过 `note_id` 查询会议纪要详情，获取下挂文档 Token（AI 智能纪要、逐字稿、会中共享文档）。只读，仅支持 `--as user`。
+通过 `note_id` 查询会议纪要详情，获取下挂文档 Token（AI 智能纪要、逐字稿、会中共享文档）。只读，支持 `--as user` / `--as bot`。bot 身份下能否读到数据取决于应用对纪要主文档是否有 view 权限。
 
 ## 命令
 
 ```bash
 lark-cli note +detail --note-id <note_id>
+lark-cli note +detail --note-id <note_id> --as bot
 ```
 
 ## `note_id` 来源
@@ -21,6 +22,8 @@ lark-cli note +detail --note-id <note_id>
 | `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` | 读逐字稿 / 原始记录：转 [`note +transcript`](lark-note-transcript.md)（仅支持 `--as user`） |
 
 判别键是 `note_display_type`。即使 unified 纪要返回了非空 `verbatim_doc_token`，逐字稿仍按 unified 路由。
+
+> **bot + unified 的边界**：如果本命令用 `--as bot` 拿到 `note_display_type=unified`，`note +transcript` 只支持 `--as user`，不能直接沿用 bot 身份。停下来向用户说明这个边界，只有用户明确同意才切到 `--as user` 继续，不要静默切换身份。

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

@@ -2,6 +2,8 @@
 
 只在 `note +detail` 已确认 `note_display_type=unified` 时使用。普通纪要逐字稿是独立 Docx 文档，应回到 [lark-doc](../../lark-doc/SKILL.md) 读取 `verbatim_doc_token`。
 
+只支持 `--as user`，不支持 `--as bot`。如果 `note +detail --as bot` 返回 `unified`，不要在这里静默省略 `--as` 或改用 user 身份继续——先停下来向用户说明"该纪要逐字稿只能以 user 身份读取"，只有用户明确同意才切换身份重试。
+
 ```bash
 lark-cli note +transcript --note-id NOTE_ID
 ```

package/skills/lark-shared/SKILL.md

@@ -64,6 +64,32 @@ LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1 LARKSUITE_CLI_NO_SKILLS_NOTIFIER=1 lark-cli a
 - **User 权限**：后台开通 scope + 用户通过 `auth login` 授权，两层都要满足
 
 
+### 身份延续（跨命令工作流）
+
+身份是**整个工作流的状态**，不是单条命令的局部参数。CLI 不会在进程之间继承"上一步用的身份"——省略 `--as` 不代表"保持当前身份"，而是把身份选择交回下面这条优先级链：
+
+```text
+显式 --as > profile default-as > credential auto-detect
+```
+
+因此，只要用户显式选择了身份，或某个 ID / Token 是通过某个身份取得的（例如 `vc +detail --as bot` 返回的 `note_id`），**后续每一条消费该 ID/Token 的命令都必须显式带上相同的 `--as`**，跨 skill 传递也不例外：
+
+- 禁止依赖 profile 默认身份让后续命令"自动"沿用同一身份。
+- 禁止仅仅因为遇到权限错误就切换身份去绕过它——先如实报告，只有用户明确同意才切换。
+- 下游命令根本不支持来源身份时（如 `--as bot` 拿到的 `note_id` 指向 `note_display_type=unified`，而 `note +transcript` 仅支持 `--as user`），停止并向用户说明这个边界，不要静默省略 `--as` 把身份交给默认值。
+- 命令支持的精确身份以 `<command> --help` / `schema` 为准；各 skill 的身份小节只标注会影响路由决策的例外，不重复维护完整矩阵。
+
+```bash
+# GOOD — note_id 来自 bot 链路，下一步显式沿用 bot
+lark-cli vc +detail --meeting-ids <meeting_id> --as bot
+lark-cli note +detail --note-id <note_id> --as bot
+lark-cli docs +fetch --doc <note_doc_token> --as bot
+
+# BAD — 省略 --as，身份可能被 profile 默认值悄悄换成 user
+lark-cli vc +detail --meeting-ids <meeting_id> --as bot
+lark-cli note +detail --note-id <note_id>
+```
+
 ### 权限不足处理
 
 遇到权限相关错误时，**根据当前身份类型采取不同解决方案**。
@@ -73,6 +99,16 @@ LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1 LARKSUITE_CLI_NO_SKILLS_NOTIFIER=1 lark-cli a
 - `console_url`：飞书开发者后台的权限配置链接
 - `hint`：建议的修复命令
 
+**missing_scope 与资源 ACL（无权访问某具体资源）是两类不同问题**，恢复方式也不同：
+
+| 失败类型 | user | bot |
+|---------|---------|---------|
+| missing scope（应用/用户完全没有这个权限） | `auth login --scope ...` | 使用错误中的 `console_url` 去开发者后台开通，**禁止** `auth login` |
+| 资源 ACL（有 scope，但对这一条具体资源没有访问权限） | 请求资源所有者给当前用户授权 | 请求资源所有者给当前应用/bot 授权 |
+| 资源在当前身份下不可见 | 保持当前身份，如实报告不可见，不要切换身份重试 | 保持当前身份，如实报告不可见，不要切换身份重试 |
+
+任何权限恢复完成后，都必须用**触发错误时的原身份**重试，不要在恢复过程中换成另一个身份。
+
 #### Bot 身份（`--as bot`）
 
 将错误中的 `console_url` 原样提供给用户，引导去后台开通 scope。**禁止**对 bot 执行 `auth login`。