@yandy0725/pi-lark 0.1.0

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

@@ -0,0 +1,170 @@
+# drive +import
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+将本地文件（如 Word、TXT、Markdown、Excel、PPTX 等）导入并转换为飞书在线云文档（docx、sheet、bitable、slides）。底层统一通过 `POST /open-apis/drive/v1/import_tasks` 接口创建导入任务，并在 shortcut 内做有限次数轮询 `GET /open-apis/drive/v1/import_tasks/:ticket`。
+
+> [!IMPORTANT]
+> 当用户说“把本地 Excel / CSV / `.base` 快照导入成 Base / 多维表格 / bitable 文档”时，第一步必须使用 `drive +import --type bitable`。
+> 这是 Drive 导入场景，不是 `lark-base` 的建表 / 写记录场景。
+> 只有导入完成并拿到新文档的 `token` / `url` 后，后续字段、记录、视图等表内操作才切换到 `lark-cli base +...`。
+
+## 导入后标题确认
+
+> [!IMPORTANT]
+> 当用户**未传 `--name`** 时，文档标题默认取源文件名（去掉扩展名）。在执行导入前，先友好提示用户：「当前未指定文档标题，默认将使用"xxx"作为标题。如果文件内容中也包含相同标题，导入后可能造成视觉重复。是否需要重命名？」让用户确认后再继续。
+
+## 命令
+
+```bash
+# 导入 Word 为新版文档 (docx)
+lark-cli drive +import --file ./report.docx --type docx
+lark-cli drive +import --file ./legacy.doc --type docx
+
+# 导入 Markdown 为新版文档 (docx)
+lark-cli drive +import --file ./README.md --type docx
+
+# 导入纯文本为新版文档 (docx)
+lark-cli drive +import --file ./notes.txt --type docx
+
+# 导入 HTML 为新版文档 (docx)
+lark-cli drive +import --file ./page.html --type docx
+
+# 导入 Excel 为电子表格 (sheet)
+lark-cli drive +import --file ./data.xlsx --type sheet
+
+# 导入 Excel 97-2003 (.xls) 为电子表格 (sheet)
+lark-cli drive +import --file ./legacy.xls --type sheet
+
+# 导入 CSV 为电子表格 (sheet)
+lark-cli drive +import --file ./data.csv --type sheet
+
+# 导入 Excel 为多维表格 / Base (bitable)
+lark-cli drive +import --file ./crm.xlsx --type bitable --name "客户台账"
+
+# 导入 .base 快照为多维表格 / Base (bitable)（文件不能超过 20MB）
+lark-cli drive +import --file ./snapshot.base --type bitable --name "快照还原"
+
+# 导入 PPTX 为飞书幻灯片 (slides)（文件不能超过 500MB）
+lark-cli drive +import --file ./deck.pptx --type slides --name "项目汇报"
+
+# 导入到指定文件夹，并指定导入后的文件名
+lark-cli drive +import --file ./data.csv --type bitable --folder-token <FOLDER_TOKEN> --name "导入数据表"
+
+# 导入数据到已有的多维表格（不新建，数据挂载到目标多维表格中）
+lark-cli drive +import --file ./data.xlsx --type bitable --target-token <BASE_TOKEN>
+
+# 预览底层调用链（上传 -> 创建任务 -> 轮询）
+lark-cli drive +import --file ./README.md --type docx --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file` | 是 | 本地文件路径，根据文件后缀名自动推断 `file_extension`；文件需满足对应格式的导入大小限制，超过 20MB 且仍在允许范围内时会自动切换分片上传 |
+| `--type` | 是 | 导入目标云文档格式。可选值：`docx` (新版文档)、`sheet` (电子表格)、`bitable` (多维表格)、`slides` (飞书幻灯片) |
+| `--folder-token` | 否 | 目标文件夹 token，不传则请求中的 `point.mount_key` 为空字符串，Import API 会将其解释为导入到云空间（云盘/云存储）根目录 |
+| `--name` | 否 | 导入后的在线云文档名称，不传默认使用本地文件名去掉扩展名后的结果 |
+| `--target-token` | 否 | 已有的多维表格 token，将数据导入到该多维表格中（**仅支持 `--type bitable`**）；传入后数据会挂载到目标多维表格而非新建一个 |
+
+## 行为说明
+
+- **完整执行流程**：此 shortcut 内部封装了完整流程：
+  1. 自动上传源文件获取 `file_token`：
+     - 20MB 及以下：调用素材上传接口 `POST /open-apis/drive/v1/medias/upload_all`
+     - 超过 20MB：自动切换为分片上传 `upload_prepare -> upload_part -> upload_finish`
+  2. 调用 `import_tasks` 接口发起导入任务，自动根据本地文件提取扩展名并构造挂载点（`mount_point`）参数
+  3. 自动轮询查询导入任务状态；如果在内置轮询窗口内完成，则直接返回导入结果；如果仍未完成，则返回 `ticket`、当前状态和后续查询命令
+- **默认根目录行为**：不传 `--folder-token` 时，shortcut 会保留空的 `point.mount_key`，Lark Import API 会将其视为"导入到调用者根目录"。
+- **导入到已有 bitable**：当 `--type bitable` 且传了 `--target-token` 时，请求 body 中会增加一个 `token` 字段指向目标多维表格的 token，point 挂载点逻辑不变。数据会挂载到该已有多维表格中，而非创建新文档。
+
+### 支持的文件类型转换
+
+本地文件扩展名与目标云文档类型的对应关系如下：
+
+| 本地文件扩展名 | 可导入为 | 说明 |
+|--------------|---------|------|
+| `.docx`, `.doc` | `docx` | Microsoft Word 文档 |
+| `.txt` | `docx` | 纯文本文件 |
+| `.md`, `.markdown`, `.mark` | `docx` | Markdown 文档 |
+| `.html` | `docx` | HTML 文档 |
+| `.xlsx` | `sheet`, `bitable` | Microsoft Excel 表格 |
+| `.xls` | `sheet` | Microsoft Excel 97-2003 表格 |
+| `.csv` | `sheet`, `bitable` | CSV 数据文件 |
+| `.base` | `bitable` | 多维表格快照文件 |
+| `.pptx` | `slides` | Microsoft PowerPoint 演示文稿 |
+
+> [!IMPORTANT]
+> 用户口头说的 “Base” / “多维表格” / “bitable”，在命令里统一对应 `--type bitable`。
+>
+> 文件扩展名与目标文档类型必须匹配，否则会返回验证错误：
+> - 文档类文件（.docx, .doc, .txt, .md, .html）**只能**导入为 `docx`
+> - `.xlsx` / `.csv` 文件**只能**导入为 `sheet` 或 `bitable`
+> - `.xls` 文件**只能**导入为 `sheet`
+> - `.base` 文件**只能**导入为 `bitable`
+> - `.pptx` 文件**只能**导入为 `slides`
+> - 例如：`.csv` 文件不能导入为 `docx`，`.md` 文件不能导入为 `sheet`
+
+> [!IMPORTANT]
+> 如果在线文档是**以应用身份（bot）导入创建**的，如 `lark-cli drive +import --as bot`，当某次结果**已经返回最终在线文档目标**后，CLI 会**尝试为当前 CLI 用户自动授予该资源的 `full_access`（可管理权限）**。
+>
+> 这个自动授权有两种触发时机：
+> - `drive +import` 的内置轮询窗口内已经完成，直接在 `+import` 中进行自动授权
+> - `drive +import` 先返回 `ready=false` / `timed_out=true`，之后你再执行 `lark-cli drive +task_result --scenario import --ticket <TICKET>`，当该查询第一次拿到最终在线文档目标时会自动授权
+>
+> 只有在已经拿到最终在线文档目标的那次结果里，才会返回 `permission_grant` 字段，明确说明授权结果：
+> - `status = granted`：当前 CLI 用户已获得该导入结果的可管理权限
+> - `status = skipped`：本地没有可用的当前用户 `open_id`，或当前结果还没有可授权目标，因此不会自动授权；可提示用户先完成 `lark-cli auth login`，再让 AI / agent 继续使用应用身份（bot）授予当前用户权限
+> - `status = failed`：导入已成功返回最终在线文档，但自动授权用户失败；会带上失败原因，并提示稍后重试或继续使用 bot 身份处理该文档
+>
+> `permission_grant.perm = full_access` 表示该资源已授予“可管理权限”。
+>
+> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
+
+### 文件大小限制
+
+除扩展名与目标类型匹配外，`drive +import` 还会在本地上传前校验格式级大小限制：
+
+| 本地文件扩展名 | 导入目标 | 大小上限 |
+|--------------|---------|---------|
+| `.docx`, `.doc` | `docx` | 600MB |
+| `.txt` | `docx` | 20MB |
+| `.md`, `.mark`, `.markdown` | `docx` | 20MB |
+| `.html` | `docx` | 20MB |
+| `.xlsx` | `sheet`, `bitable` | 800MB |
+| `.csv` | `sheet` | 20MB |
+| `.csv` | `bitable` | 100MB |
+| `.xls` | `sheet` | 20MB |
+| `.base` | `bitable` | 20MB |
+| `.pptx` | `slides` | 500MB |
+
+- 如果文件超出对应上限，shortcut 会在真正上传前直接返回验证错误。
+- “超过 20MB 自动切换分片上传”只表示上传链路会切到 multipart，不代表所有格式都允许导入超过 20MB 的文件。
+
+- 若导入任务执行失败，会返回失败时的 `job_status` 及错误信息。
+- 若内置轮询超时但任务仍在处理中，shortcut 会成功返回，并带上：
+  - `ready=false`
+  - `timed_out=true`
+  - `next_command`：可直接复制执行的后续查询命令，例如 `lark-cli drive +task_result --scenario import --ticket <TICKET>`
+- 若使用 `--as bot` 且内置轮询窗口内已经拿到最终在线文档，输出还会额外带上 `permission_grant`，用于说明是否已自动为当前 CLI 用户授予可管理权限。
+- 若使用 `--as bot` 但当前只返回 `ready=false`，此时还不会返回 `permission_grant`；应继续执行返回值里的 `next_command`，等 `drive +task_result --scenario import` 拿到最终文档后再触发自动授权。
+- 如果文件扩展名不被支持，执行时将抛出验证错误。
+
+### 超时后的继续查询
+
+当 `+import` 的内置轮询窗口结束但任务尚未完成时，使用返回结果中的 `ticket` 继续查询：
+
+```bash
+lark-cli drive +task_result --scenario import --ticket <TICKET>
+```
+
+如果这里最终返回 `ready=true` 且使用的是 `--as bot`，结果还会额外带上 `permission_grant`，用于说明是否已自动为当前 CLI 用户授予可管理权限。
+
+> [!CAUTION]
+> `drive +import` 是**写入操作** —— 执行前必须确认用户意图。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,50 @@
+
+# drive +inspect（文档 URL 检视：类型、标题、Token 解析）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+给定一个飞书文档 URL 或 bare token，返回其类型、标题和 canonical token。对 wiki URL 自动解包到底层文档。
+
+## 命令
+
+```bash
+# 检视一个 docx URL
+lark-cli drive +inspect --url 'https://xxx.feishu.cn/docx/doxcnXXX'
+
+# 检视一个 wiki URL（自动解包到底层文档）
+lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
+
+# bare token 需要指定 --type
+lark-cli drive +inspect --url doxcnXXX --type docx
+
+# 格式化输出
+lark-cli drive +inspect --url 'https://xxx.feishu.cn/base/bascnXXX' --format pretty
+```
+
+## 输出
+
+JSON 输出包含以下字段：
+
+| 字段 | 说明 |
+|------|------|
+| `input_url` | 原始输入 URL |
+| `type` | 文档类型（docx, doc, sheet, bitable, wiki, file, folder, mindnote, slides） |
+| `title` | 文档标题 |
+| `token` | canonical file token |
+| `url` | 重建的 canonical URL |
+| `wiki_node` | 仅 wiki URL：包含 `space_id`, `node_token`, `obj_token`, `obj_type` |
+
+## 典型场景
+
+| 场景 | 命令 |
+|------|------|
+| 用户给了一个 URL，想知道它是什么类型的文档 | `lark-cli drive +inspect --url '<url>'` |
+| wiki 链接需要拿到底层文档的 token 来做后续操作 | `lark-cli drive +inspect --url '<wiki_url>'`，取输出中的 `token` |
+| 只有 token 没有 URL | `lark-cli drive +inspect --url <token> --type <type>` |
+
+## 注意事项
+
+- `--url` 为必填参数
+- 当 `--url` 是 bare token（非完整 URL）时，`--type` 也是必填的
+- wiki URL 会自动调用 `get_node` API 解包，输出中 `type` 和 `token` 是底层文档的类型和 token
+- 支持 `--dry-run` 查看将调用的 API 步骤

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

@@ -0,0 +1,66 @@
+# drive +member-add（添加协作者/授权成员权限）
+
+> 这是高风险写操作。真实执行会修改文档权限，需要显式加 `--yes`
+
+## 命令
+
+```bash
+
+# 批量添加（同一 member-type 和 perm，最多 10 人）
+lark-cli drive +member-add \
+  --token "<bare_token_or_url>" \
+  --type bitable \
+  --member-id "ou_a,ou_b" \
+  --member-type openid \
+  --perm view \
+  --yes
+```
+
+## 参数
+
+| 参数 | 必填 | 说明                                                                                                                                                                                  |
+|------|----|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--token` | 是 | 裸 token 或完整 URL。路径支持 `/drive/folder/`、`/docx/`、`/doc/`、`/sheets/`、`/base/`、`/bitable/`、`/wiki/`、`/file/`、`/mindnotes/`、`/slides/`、`/minutes/`；URL 输入可从路径推断 `--type`，裸 token 不做前缀推断 |
+| `--type` | 必填 | 目标资源类型：`docx` / `doc` / `sheet` / `bitable` / `file` / `folder` / `wiki` / `mindnote` / `slides` / `minutes`。传 URL 时可省略；裸 token 必须显式传；若同时传 URL 和 `--type`，显式 `--type` 覆盖 URL 推断                 |
+| `--member-id` | 是 | 协作者 ID；逗号分隔可批量添加，最多 10 个                                                                                                                                                            |
+| `--member-type` | 是 | member-id 的类型；支持 `email` / `openid` / `unionid` / `openchat` / `opendepartmentid` / `groupid` / `appid` / `wikispaceid`。在实际使用里，给当前应用授权仍优先推荐 bot `open_id` + `openid`。                               |
+| `--member-kind` | 条件必填 | 仅当 `--member-type=wikispaceid` 时填写，映射到请求 body 的 `type` 字段。取值：`wiki_space_member` / `wiki_space_viewer` / `wiki_space_editor`。其他 member-type 禁止传此参数。 |
+| `--perm` | 否 | 授权角色：`view`（默认）/ `edit` / `full_access`                                                                                                                                             |
+| `--perm-type` | 否 | 只作用 wiki 节点权限范围：`container`（默认，当前页面+子页面）/ `single_page`（仅当前页面）                                                                                                                      |
+| `--need-notification` | 否 | 是否通知对方。仅 `--as user` 可用；未传时不会写入 query，`--need-notification=false` 表示显式不通知                                                                                                           |
+| `--dry-run` | 否 | 仅打印请求，不实际授权                                                                                                                                                                         |
+| `--yes` | 真实执行时是 | 确认高风险写操作                                                                                                                                                                            |
+
+## 输出
+
+批量成功：
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "resource_token": "doc_token_or_url",
+    "resource_type": "docx",
+    "requested_count": 2,
+    "succeeded_count": 2,
+    "partial": false,
+    "members": [
+      {"resource_token": "doc_token_or_url", "resource_type": "docx", "member_id": "ou_a", "member_type": "openid", "member_kind": "user", "perm": "view"},
+      {"resource_token": "doc_token_or_url", "resource_type": "docx", "member_id": "ou_b", "member_type": "openid", "member_kind": "user", "perm": "view"}
+    ],
+    "missing_member_ids": []
+  }
+}
+```
+
+批量部分失败时，`partial` 为 `true`，CLI 以非零退出码返回 `error.type=partial_failure`。检查 `error.detail` 中的 `requested_count`、`succeeded_count`、`members`、`missing_member_ids` 和可选的 `mismatched_member_ids`。响应顺序不影响匹配结果。
+
+## 行为说明
+
+- **身份支持**：`--as user` 和 `--as bot` 均可使用。
+- **部门协作者**：`--member-type=opendepartmentid` 必须配合 `--as user`；bot 身份不支持添加部门协作者。
+- **通知**：`--need-notification` 仅 `--as user` 时有效；`--as bot` 时传此参数会被拒绝。
+- **批量约束**：批量请求共享同一 `--member-type`、`--perm` 和 `--perm-type`；混合用户/群组/部门的场景需拆分为多次调用。
+- **Wiki 空间 ID**：`--member-type=wikispaceid` 时必须同时传 `--member-kind`，否则 API 会缺少必填的 body `type` 字段。`wiki_space_member` 对应知识库成员角色；若知识库已将成员拆分为可阅读/可编辑成员组，改用 `wiki_space_viewer` 或 `wiki_space_editor`。
+- **ID 解析**：优先用 `open_id` + `--member-type openid`；仅在无法解析 `open_id` 时使用 `email`。群组优先用 `openchat`，部门用 `opendepartmentid`。

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

@@ -0,0 +1,120 @@
+
+# drive +move
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+将文件或文件夹移动到用户云空间（云盘/云存储）的其他位置。
+
+## 与 `wiki +move` 的区别
+
+- `drive +move` 只处理 **Drive 文件夹树内部** 的位置调整，目标位置用 `--folder-token` 表示
+- `wiki +move` 处理的是 **Wiki 知识空间 / 页面层级**：要么移动已有 Wiki 节点，要么把 Drive 文档迁入 Wiki
+- 如果用户说“移动到某个文件夹”“移动到我的空间根目录”，应使用 `drive +move`
+- 如果用户说“移动到某个知识库 / 页面下”“迁入 Wiki / 知识空间”，应使用 `wiki +move`
+- 如果用户说“移动到我的文档库 / 我的知识库 / 个人知识库 / my_library”，不要使用 `drive +move`；先按 Wiki 目标处理
+- `我的文档库` 不是 Drive root folder，也不是 `--folder-token` 省略后的默认目的地
+- `drive +move` 不支持 wiki 文档；如果目标是 Wiki，不要尝试用 `drive +move` 代替
+
+## 不要误用到 `我的文档库`
+
+下面几种说法都**不应该**触发 `drive +move`：
+
+- `移动到我的文档库`
+- `放到我的知识库`
+- `迁入个人知识库`
+- `move to My Document Library`
+
+这些目标都应该先走 Wiki 解析流程：
+
+```bash
+lark-cli wiki spaces get --params '{"space_id":"my_library"}'
+```
+
+拿到真实 `space_id` 后，再改用 `wiki +move`。不要因为 `drive +move` 可以省略 `--folder-token` 就把它当作“我的文档库”的近似目标。
+
+## 命令
+
+```bash
+# 移动文件到指定文件夹
+lark-cli drive +move \
+  --file-token <FILE_TOKEN> \
+  --type file \
+  --folder-token <TARGET_FOLDER_TOKEN>
+
+# 移动文档到指定文件夹
+lark-cli drive +move \
+  --file-token <DOCX_TOKEN> \
+  --type docx \
+  --folder-token <TARGET_FOLDER_TOKEN>
+
+# 移动文件夹（异步操作，会自动有限轮询任务状态）
+lark-cli drive +move \
+  --file-token <FOLDER_TOKEN> \
+  --type folder \
+  --folder-token <TARGET_FOLDER_TOKEN>
+
+# 移动到根文件夹（不指定 --folder-token）
+lark-cli drive +move \
+  --file-token <FILE_TOKEN> \
+  --type file
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | 需要移动的文件或文件夹 token |
+| `--type` | 是 | 文件类型，可选值：`file` (普通文件)、`docx` (新版文档)、`bitable` (多维表格)、`doc` (旧版文档)、`sheet` (电子表格)、`mindnote` (思维笔记)、`folder` (文件夹)、`slides` (幻灯片) |
+| `--folder-token` | 否 | 目标文件夹 token，不指定则移动到根文件夹 |
+
+## 文件类型说明
+
+| 类型 | 说明 |
+|------|------|
+| `file` | 普通文件 |
+| `docx` | 新版云文档 |
+| `doc` | 旧版云文档 |
+| `sheet` | 电子表格 |
+| `bitable` | 多维表格 |
+| `mindnote` | 思维笔记 |
+| `slides` | 幻灯片 |
+| `folder` | 文件夹（移动文件夹是异步操作） |
+
+## 行为说明
+
+- **普通文件移动**：同步操作，立即完成
+- **文件夹移动**：异步操作，接口返回 `task_id`，shortcut 会先做有限轮询；如果在轮询窗口内完成，则直接返回成功结果
+- **轮询超时不是失败**：文件夹移动内置最多轮询 30 次、每次间隔 2 秒；如果轮询结束任务仍未完成，会返回 `task_id`、`status`、`ready=false`、`timed_out=true` 和 `next_command`
+- **继续查询**：当看到 `next_command` 时，改用 `lark-cli drive +task_result --scenario task_check --task-id <TASK_ID>` 继续查询
+- **目标文件夹**：如果不指定 `--folder-token`，文件将被移动到用户的根文件夹（"我的空间"）
+- **不要混淆产品概念**：这里的“根文件夹 / 我的空间”仅属于 Drive 文件夹树，不等于 Wiki 的“我的文档库”
+- **权限要求**：需要被移动文件的可管理权限、被移动文件所在位置的编辑权限、目标位置的编辑权限
+
+## 推荐续跑方式
+
+```bash
+# 第一步：先直接移动文件夹
+lark-cli drive +move \
+  --file-token <FOLDER_TOKEN> \
+  --type folder \
+  --folder-token <TARGET_FOLDER_TOKEN>
+
+# 如果返回 ready=false / timed_out=true，再继续查
+lark-cli drive +task_result \
+  --scenario task_check \
+  --task-id <TASK_ID>
+```
+
+## 限制
+
+- 被移动的文件不支持 wiki 文档
+- 该接口不支持并发调用
+- 调用频率上限为 5 QPS 且 10000 次/天
+
+> [!CAUTION]
+> 这是**写入操作** —— 执行前必须确认用户意图。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/skills/lark-drive/references/lark-drive-permission-guide.md

@@ -0,0 +1,41 @@
+# Drive 权限与授权指南
+
+> 前置条件：通用认证、scope 与 `--as` 规则见 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。
+
+## 何时读取
+
+- 用户要修改文档公开权限，尤其是 `drive permission.public patch` 返回 `91009` / `91010` / `91011` / `91012`。
+- 用户要给文档、文件、文件夹、Wiki 或 slides 增加协作者权限，或把访问权限授予当前应用（bot）自身。
+- 用户遇到 `permission denied`，但错误表现更像租户对外分享、安全策略或密级拦截，而不是普通 scope 缺失。
+
+如果用户只是想向文档 owner 申请访问权限，优先使用 [`lark-drive-apply-permission.md`](lark-drive-apply-permission.md)。
+
+## 公开权限错误码
+
+调用 `lark-cli drive permission.public patch` 更新文档公开权限失败时，如果返回以下错误码，按表格给用户明确下一步。不要把这些错误简单归类为缺少 scope；它们通常表示租户、对外分享或文档密级策略拦截。
+
+| 错误码 | 含义 | 给用户的引导 |
+|--------|------|--------------|
+| `91009` | 对外分享被租户安全策略管控，当前用户无法开启 | 提示用户：对外分享能力被租户安全策略统一管控，无法通过 API 或当前用户直接开启；需要联系租户管理员调整组织级对外分享策略。 |
+| `91010` | 文档对外分享未打开 | 提示用户：当前文档尚未打开对外分享，请先在文档权限设置中打开对外分享，再重试 `permission.public.patch`。 |
+| `91011` | 对外分享被文档密级管控 | 提示用户：对外分享被密级策略拦截，需要打开目标文档，在文档内发起密级豁免或进行密级降级后再重试；回复中必须给出目标文档 URL。 |
+| `91012` | 权限设置被文档密级管控 | 提示用户：该权限设置被密级策略拦截，需要打开目标文档，在文档内发起密级豁免或进行密级降级后再重试；回复中必须给出目标文档 URL。 |
+
+当用户最初提供的是文档 URL，遇到 `91011` 或 `91012` 时直接把该 URL 原样返回给用户作为操作入口；如果上下文只有 token，需要先尽量通过已有上下文、搜索结果或元数据恢复目标文档 URL，再给出可点击的文档 URL。
+
+## 授权当前应用访问文档
+
+需要将文档权限授予当前应用（bot）自身时：
+
+1. 先执行 `lark-cli api GET /open-apis/bot/v3/info --as bot`，从返回值取 `bot.open_id`。
+2. 再调用 `lark-cli drive permission.members create`，用 `member_type=openid`、`member_id=<bot_open_id>` 授权。
+
+```bash
+lark-cli drive permission.members create \
+  --params '{"token":"<doc_token>","type":"<resource_type>"}' \
+  --data '{"member_type":"openid","member_id":"<bot_open_id>","perm":"view","type":"user"}'
+```
+
+此方式仅适用于授权给当前应用。授权给其他用户时，直接使用对方的 open_id，无需调用 bot info 接口。
+
+`<resource_type>` 可选值：`doc`、`docx`、`sheet`、`bitable`、`file`、`folder`、`wiki`、`slides`。

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

@@ -0,0 +1,87 @@
+## `drive +preview`
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、权限处理和安全规则。
+
+列出或下载 Drive 文件可用的预览产物。这个 shortcut 不猜测默认类型：
+
+- 只想看候选项时，用 `--list-only`
+- 想下载时，必须显式传 `--type` 和 `--output`
+- 如果某个候选项还在生成中，会返回结构化错误并提示先重新 `--list-only`
+
+### 命令
+
+```bash
+# 列出可用预览候选项
+lark-cli drive +preview \
+  --file-token "<FILE_TOKEN>" \
+  --list-only
+
+# 下载 PDF 预览
+lark-cli drive +preview \
+  --file-token "<FILE_TOKEN>" \
+  --type pdf \
+  --output ./artifacts/report
+
+# 下载文本预览，并在目标已存在时自动改名
+lark-cli drive +preview \
+  --file-token "<FILE_TOKEN>" \
+  --type text \
+  --output ./artifacts/report \
+  --if-exists rename
+
+# 指定版本号查询/下载
+lark-cli drive +preview \
+  --file-token "<FILE_TOKEN>" \
+  --version "12" \
+  --type html \
+  --output ./artifacts/report.html
+```
+
+### 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | Drive 文件 token |
+| `--type` | 条件必填 | 预览类型；优先使用 `--list-only` 返回的 `type`，如 `pdf` / `html` / `text` / `png` / `jpg` / `source_file` |
+| `--version` | 否 | 文件版本号 |
+| `--list-only` | 否 | 仅返回候选项，不下载 |
+| `--output` | 条件必填 | 下载到本地的输出路径 |
+| `--if-exists` | 否 | 输出冲突策略：`error`（默认）/ `overwrite` / `rename` |
+
+### 输出约定
+
+- 查询态返回：
+  - `mode=list`
+  - `file_token`
+  - `candidates[]`
+  - `next_action`
+- 下载态返回：
+  - `mode=download`
+  - `file_token`
+  - `selected_type`
+  - `output_path`
+  - `status`
+
+### 候选项字段
+
+`candidates[]` 中每个对象包含：
+
+- `type`
+- `type_code`
+- `label`
+- `status`
+- `status_code`
+- `downloadable`
+- `reason`（可选）
+
+### 关键约束
+
+- 不传 `--list-only` 时，必须显式传 `--type` 和 `--output`
+- 不会隐式选择“第一个候选项”作为默认下载目标
+- 候选项状态来自后端 `preview_status` 枚举，例如 `READY` / `PROCESSING` / `FAILED` / `NO_SUPPORT`
+- 本地文件名在未显式带扩展名时，会结合响应头自动补扩展名
+
+### 参考
+
+- [lark-drive](../SKILL.md) -- Drive 总入口
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数