@amaster.ai/pi-lark 0.1.4 → 0.1.6

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

@@ -0,0 +1,135 @@
+
+# drive +status
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+按 **精确 SHA-256**（默认）或 **快速 modified_time**（`--quick`）比较本地目录与飞书云空间（云盘/云存储）文件夹，输出四类差异：
+
+| 字段 | 含义 |
+|------|------|
+| `new_local` | 仅本地存在 |
+| `new_remote` | 仅云端存在 |
+| `modified` | 双端都存在且本次检测判定为已变更：`detection=exact` 时表示 hash 不一致；`detection=quick` 时表示本地 mtime 与远端 `modified_time` 不一致，或远端时间戳不可可信 |
+| `unchanged` | 双端都存在且本次检测判定为未变更：`detection=exact` 时表示 hash 一致；`detection=quick` 时表示本地 mtime 与远端 `modified_time` 相等 |
+
+只读命令：
+
+- 默认 `detection=exact`：双端都有的文件会从云端拉一份字节流过来在内存里算 hash，不下载落盘，但大目录 / 大文件会有可观的网络流量。
+- 传 `--quick` 后 `detection=quick`：只比较本地 mtime 与远端 `modified_time`，**不下载远端文件内容**，适合先做快速预检查；它是 best-effort，不等同于严格内容一致性判断。
+
+## 远端同名文件冲突
+
+如果 Drive 中多个条目映射到同一个 `rel_path`，`+status` 会在下载/hash 前直接失败，在 stderr 返回类型化错误信封（`error.type=validation`、`error.subtype=failed_precondition`）；`error.params[]` 每条的 `name` 是冲突的 `rel_path`，`reason` 枚举该路径下所有碰撞条目（`type` + `file_token`）。不要把这种情况当成普通 `modified`；它表示同步域本身有歧义，需要先整理云端结构，或在 `+pull` / `+push` 中仅对“duplicate file”场景显式选择冲突策略。
+
+## 命令
+
+```bash
+# 基础用法 —— 两个必填参数
+lark-cli drive +status \
+  --local-dir ./repo \
+  --folder-token fldcnxxxxxxxxx
+
+# 快速模式 —— 只比较 modified_time，不下载远端文件内容
+lark-cli drive +status \
+  --local-dir ./repo \
+  --folder-token fldcnxxxxxxxxx \
+  --quick
+
+# 只看判定为 modified 的项（exact=hash 不一致；quick=mtime 不一致）（结合 --jq 过滤）
+lark-cli drive +status \
+  --local-dir ./repo \
+  --folder-token fldcnxxxxxxxxx \
+  --jq '.modified'
+```
+
+## 参数
+
+| 标志 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--local-dir` | 是 | path | 本地根目录（**必须是 cwd 的相对路径**；绝对路径或逃逸到 cwd 外的相对路径会被 CLI 直接拒绝） |
+| `--folder-token` | 是 | string | Drive 文件夹 token |
+| `--quick` | 否 | bool | 快速模式：只比较本地 mtime 与远端 `modified_time`，跳过远端下载和 SHA-256 计算；输出里的 `detection` 会变成 `quick` |
+
+## 输出 schema
+
+成功时：
+
+```json
+{
+  "detection":  "exact",
+  "new_local":  [{"rel_path": "..."}],
+  "new_remote": [{"rel_path": "...", "file_token": "..."}],
+  "modified":   [{"rel_path": "...", "file_token": "..."}],
+  "unchanged":  [{"rel_path": "...", "file_token": "..."}]
+}
+```
+
+其中：
+
+- `detection=exact`：默认模式，双端都有的文件会下载远端字节流并做 SHA-256 比较。
+- `detection=quick`：`--quick` 模式，只按本地 mtime 与远端 `modified_time` 做 best-effort 判断。
+
+`rel_path` 始终用 `/` 作为分隔符（跨平台一致），相对于 `--local-dir` 或 `--folder-token` 的根。仅本地存在时没有 `file_token` 字段。
+
+远端同名文件冲突时：
+
+```json
+{
+  "ok": false,
+  "identity": "user",
+  "error": {
+    "type": "validation",
+    "subtype": "failed_precondition",
+    "message": "1 rel_path(s) map to multiple Drive entries",
+    "hint": "resolve the duplicate remote files first: re-run +pull with --on-duplicate-remote=rename (downloads each with a hashed suffix), or use --on-duplicate-remote=newest|oldest (supported by +pull/+sync/+push) to pick one, or delete the extra remote files; a plain retry will not help",
+    "params": [
+      {
+        "name": "dup.txt",
+        "reason": "2 Drive entries collide here: file <full_file_token>, folder <folder_token>"
+      }
+    ]
+  }
+}
+```
+
+## 比较范围
+
+- **只比对 Drive `type=file` 的二进制文件**。在线文档（`docx` / `sheet` / `bitable` / `mindnote` / `slides`）和快捷方式（`shortcut`）都被跳过 —— 它们没有等价的本地二进制可对齐，否则会在 `new_remote` 里产生大量误报。
+- 子文件夹会递归遍历；rel_path 形如 `sub1/sub2/file.txt`。
+- 多个远端条目映射到同一个 rel_path 时不做隐式选择，默认失败。
+- 本地侧只比对常规文件（regular file）；符号链接、设备文件等被忽略。
+- `--quick` 模式下，双端都有的文件只在 **远端时间精度** 下比较 `modified_time` / 本地 mtime：相等才记为 `unchanged`，否则记为 `modified`；远端时间戳缺失或非法时，走保守路径记为 `modified`，不会盲判 `unchanged`。
+
+## 范围限制
+
+`+status` 的本地侧只接受 cwd 下的相对路径。如果用户想比对的目录在 cwd 之外，**不要 agent 自己 `cd` 绕过**；让用户在合适的祖先目录重新启动 agent 后再跑。注意：把目标软链接到 cwd 内**也不行**——路径校验会先 `EvalSymlinks` 再判定是否越界，链接最终指向的真实目录如果在 cwd 之外，仍然会被 `unsafe file path` 拒掉。CLI 会在路径越界时直接报错，无需在 skill 这一层提前手动校验。
+
+## 典型用法
+
+把 +status 当作"先看差异、再决定怎么同步"的只读探针。常见接驳场景：
+
+- 想知道云端有什么本地没有的内容 → 看 `new_remote`，按需选择性拉取（`drive +download --file-token <token>`）。
+- 想把本地新增的内容推到云端 → 看 `new_local`，再 `drive +upload --file <path> --folder-token <parent>`（注意 +upload 不接受 0 字节文件）。
+- 想知道哪些文件在云端被同事改过 → 看 `modified`，逐个 `drive +download` 查内容差异。
+
+## 性能注意
+
+- 默认 `detection=exact` 下，`unchanged` + `modified` 的总字节数 = 本次需从云端下载的流量。100GB 的双端共享内容意味着 100GB 网络往返。
+- `--quick` / `detection=quick` 下，不会下载双端共有文件的远端内容，执行时间更接近 `O(文件数量)`，而不是 `O(总文件大小)`。
+- 仅一侧存在的文件不会被下载。
+- 默认模式的 hash 计算在内存里流式做（io.Copy → sha256.New），不会把云端文件落到磁盘。
+
+## 所需 scope
+
+| 操作 | scope |
+|------|-------|
+| 列出文件夹 / 子目录 | `drive:drive.metadata:readonly` |
+| 下载并 hash 文件 | `drive:file:download` |
+
+默认会先要求 `drive:drive.metadata:readonly`。在 `detection=exact` 路径（默认，不传 `--quick`）下，CLI 还会额外要求 `drive:file:download`；传 `--quick` 时不会要求下载 scope。如果当前 token 缺本次执行路径需要的 scope，命令会报 `missing_scope` 并提示重新登录。`drive:drive` 在部分企业被策略禁用，所以 +status 故意只依赖上面这些细粒度 scope。
+
+## 参考
+
+- [lark-drive](../SKILL.md) —— 云空间（云盘/云存储）全部命令
+- [lark-shared](../../lark-shared/SKILL.md) —— 认证和全局参数
+- [lark-drive-upload](lark-drive-upload.md) / [lark-drive-download](lark-drive-download.md) —— 把 +status 输出接到推/拉动作上

package/skills/lark-drive/references/lark-drive-task-result.md

@@ -0,0 +1,355 @@
+
+# drive +task_result
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+查询异步任务结果。该 shortcut 聚合了导入、导出、Drive 文件/文件夹移动/删除、Wiki 节点 / 文档迁入 Wiki、Wiki 节点移出 Wiki、Wiki 删除等多种异步任务的结果查询，统一接口方便调用。
+
+> [!IMPORTANT]
+> 对于 `import` 场景，如果使用 `--as bot` 且这次查询**已经拿到最终在线文档目标**（`ready=true` 且返回了最终 `token` / `url`），CLI 会**再次尝试为当前 CLI 用户自动授予该资源的 `full_access`（可管理权限）**。
+>
+> 此时结果里会额外返回 `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 转给自己，必须单独确认。
+
+## 命令
+
+```bash
+# 查询导入任务结果
+lark-cli drive +task_result \
+  --scenario import \
+  --ticket <IMPORT_TICKET>
+
+# 查询导出任务结果
+lark-cli drive +task_result \
+  --scenario export \
+  --ticket <EXPORT_TICKET> \
+  --file-token <SOURCE_DOC_TOKEN>
+
+# 查询 Drive 文件/文件夹移动/删除任务状态
+lark-cli drive +task_result \
+  --scenario task_check \
+  --task-id <TASK_ID>
+
+# 查询 Wiki 移动任务结果（wiki +move 异步超时后的续跑）
+lark-cli drive +task_result \
+  --scenario wiki_move \
+  --task-id <TASK_ID>
+
+# 查询 Wiki 节点移出知识库任务结果（wiki +move-to-drive 异步超时后的续跑）
+lark-cli drive +task_result \
+  --scenario wiki_move_to_drive \
+  --task-id <TASK_ID>
+
+# 查询 Wiki 删除知识空间任务结果（wiki +delete-space 异步超时后的续跑）
+lark-cli drive +task_result \
+  --scenario wiki_delete_space \
+  --task-id <TASK_ID>
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--scenario` | 是 | 任务场景，可选值：`import` (导入任务)、`export` (导出任务)、`task_check` (Drive 文件/文件夹移动/删除任务)、`wiki_move` (Wiki 移动任务)、`wiki_move_to_drive` (Wiki 节点移出知识库任务)、`wiki_delete_space` (Wiki 删除知识空间任务)、`wiki_delete_node` (Wiki 删除节点任务) |
+| `--ticket` | 条件必填 | 异步任务 ticket，**import/export 场景必填** |
+| `--task-id` | 条件必填 | 异步任务 ID，**task_check 及所有 wiki 场景必填**；必须原样传递完整 ID |
+| `--file-token` | 条件必填 | 导出任务对应的源文档 token，**export 场景必填** |
+
+## 场景说明
+
+| 场景 | 说明 | 所需参数 |
+|------|------|----------|
+| `import` | 文档导入任务（如将本地文件导入为云文档） | `--ticket` |
+| `export` | 文档导出任务（如云文档导出为 PDF/Word） | `--ticket`、`--file-token` |
+| `task_check` | Drive 文件/文件夹移动/删除任务 | `--task-id` |
+| `wiki_move` | Wiki 移动任务（`wiki +move` 的 docs-to-wiki 异步流程，超时后续跑用） | `--task-id` |
+| `wiki_move_to_drive` | Wiki 节点移出知识库任务（`wiki +move-to-drive` 超时后续跑用） | `--task-id` |
+| `wiki_delete_space` | Wiki 删除知识空间任务（`wiki +delete-space` 的异步流程，超时后续跑用） | `--task-id` |
+| `wiki_delete_node` | Wiki 删除节点任务（`wiki +node-delete` 的异步流程，超时后续跑用） | `--task-id` |
+
+## 返回结果
+
+### Import 场景返回
+
+```json
+{
+  "scenario": "import",
+  "ticket": "<IMPORT_TICKET>",
+  "type": "sheet",
+  "ready": true,
+  "failed": false,
+  "job_status": 0,
+  "job_status_label": "success",
+  "job_error_msg": "success",
+  "token": "<IMPORTED_DOC_TOKEN>",
+  "url": "https://example.feishu.cn/sheets/<IMPORTED_DOC_TOKEN>",
+  "extra": ["2000"],
+  "permission_grant": {
+    "status": "granted",
+    "perm": "full_access",
+    "member_type": "openid",
+    "user_open_id": "<CURRENT_USER_OPEN_ID>",
+    "message": "Granted the current CLI user full_access (可管理权限) on the new spreadsheet."
+  }
+}
+```
+
+**字段说明：**
+- `ready`: 是否已经导入完成，可直接使用 `token` / `url`
+- `failed`: 是否已经失败
+- `job_status`: 服务端返回的原始状态码
+- `job_status_label`: 便于阅读的状态标签，例如 `success` / `processing`
+- `token`: 导入后的文档 token
+- `url`: 导入后的文档链接
+- `permission_grant`: 仅 `--as bot` 且这次查询已经拿到最终在线文档目标时返回，用于说明是否已自动为当前 CLI 用户授予可管理权限；如果当前仍是 `ready=false`，则不会返回这个字段
+
+### Export 场景返回
+
+```json
+{
+  "scenario": "export",
+  "ticket": "<EXPORT_TICKET>",
+  "ready": true,
+  "failed": false,
+  "file_extension": "pdf",
+  "type": "doc",
+  "file_name": "docName",
+  "file_token": "<EXPORTED_FILE_TOKEN>",
+  "file_size": 34356,
+  "job_error_msg": "success",
+  "job_status": 0,
+  "job_status_label": "success"
+}
+```
+
+**字段说明：**
+- `ready`: 是否已经完成导出，可直接使用 `file_token`
+- `failed`: 是否已经失败
+- `job_status`: 服务端返回的原始状态码
+- `job_status_label`: 便于阅读的状态标签，例如 `success` / `processing`
+- `file_token`: 导出文件的 token，用于下载
+- `file_extension`: 导出文件扩展名
+- `file_size`: 导出文件大小（字节）
+
+### Task_check 场景返回
+
+```json
+{
+  "scenario": "task_check",
+  "task_id": "<TASK_ID>",
+  "status": "success",
+  "ready": true,
+  "failed": false
+}
+```
+
+**字段说明：**
+- `status`: 任务状态，`success`=成功，`failed`=失败，`pending`=处理中
+- `ready`: 是否已经完成
+- `failed`: 是否已经失败
+
+### Wiki_move 场景返回
+
+```json
+{
+  "scenario": "wiki_move",
+  "task_id": "<TASK_ID>",
+  "ready": true,
+  "failed": false,
+  "status": 0,
+  "status_msg": "success",
+  "wiki_token": "wikcnXXX",
+  "node_token": "wikcnXXX",
+  "space_id": "<TARGET_SPACE_ID>",
+  "obj_token": "<OBJ_TOKEN>",
+  "obj_type": "docx",
+  "parent_node_token": "",
+  "node_type": "origin",
+  "origin_node_token": "",
+  "title": "项目计划",
+  "has_child": false,
+  "node": {
+    "space_id": "<TARGET_SPACE_ID>",
+    "node_token": "wikcnXXX",
+    "obj_token": "<OBJ_TOKEN>",
+    "obj_type": "docx",
+    "parent_node_token": "",
+    "node_type": "origin",
+    "origin_node_token": "",
+    "title": "项目计划",
+    "has_child": false
+  },
+  "move_results": [
+    {
+      "status": 0,
+      "status_msg": "success",
+      "node": { "...": "同上" }
+    }
+  ]
+}
+```
+
+**字段说明：**
+- `ready`: 所有 `move_results[].status` 都为 `0` 时为 `true`
+- `failed`: 任一 `move_results[].status` 小于 `0` 时为 `true`
+- `status` / `status_msg`: 第一个 move_result 的状态码 / 标签（无结果时回退为 `1` / `processing`）
+- `wiki_token` / `node_token`: 移入 Wiki 后的目标节点 token（首个结果有 `node.node_token` 时镜像到顶层，便于下游脚本使用）
+- `space_id`、`obj_token`、`obj_type`、`title` 等：从首个 `move_results[0].node` 平铺到顶层，方便直接引用
+- `move_results`: 保留完整列表（适用于一次任务移动多个文档的场景）
+
+### Wiki_move_to_drive 场景返回
+
+```json
+{
+  "scenario": "wiki_move_to_drive",
+  "task_id": "<OPAQUE_TASK_ID>",
+  "ready": true,
+  "failed": false,
+  "status": 0,
+  "status_msg": "success",
+  "obj_token": "doxcnXXX",
+  "obj_type": "docx",
+  "url": "https://example.feishu.cn/docx/doxcnXXX"
+}
+```
+
+**字段说明：**
+- `ready`: `move_wiki_to_docs_result.status=0` 时为 `true`
+- `failed`: `status<0` 时为 `true`；`status=1` 表示仍在处理
+- `status` / `status_msg`: 协议返回的数值状态与可读消息；不要把字符串状态当作成功值解析
+- `obj_token` / `obj_type` / `url`: 成功后新 Drive 文档的资源信息
+- `task_id`: 签名后的 opaque ID，可能包含多个连字符；服务端响应省略 `task.task_id` 时回退为请求中的完整 ID
+
+### Wiki_delete_space 场景返回
+
+```json
+{
+  "scenario": "wiki_delete_space",
+  "task_id": "<TASK_ID>",
+  "ready": true,
+  "failed": false,
+  "status": "success",
+  "status_msg": "success"
+}
+```
+
+**字段说明：**
+- `ready`: `status=success` 时为 `true`
+- `failed`: `status=failure` 或 `failed` 时为 `true`；未知非成功状态（如 `processing`）视为进行中
+- `status`: 服务端返回的原始 `delete_space_result.status`
+- `status_msg`: 优先使用 `delete_space_result.status_msg`，否则回落到 `status`，再回落到 `processing`
+
+## 使用场景
+
+### 配合 +import 使用
+
+```bash
+# 1. 创建导入任务
+lark-cli drive +import --file ./data.xlsx --type sheet
+# 若任务很快完成：直接返回 token / url
+# 若内置轮询超时：返回 ready=false、ticket 和 next_command
+
+# 2. 轮询导入结果
+lark-cli drive +task_result --scenario import --ticket <IMPORT_TICKET>
+# 如果这里返回 ready=true 且使用 --as bot，结果还会包含 permission_grant
+```
+
+### 配合 +move 使用
+
+```bash
+# 1. 移动文件夹（异步操作）
+lark-cli drive +move --file-token <FOLDER_TOKEN> --type folder --folder-token <TARGET_FOLDER_TOKEN>
+# 若轮询窗口内完成：直接返回 ready=true
+# 若内置轮询结束仍未完成：返回 ready=false、task_id 和 next_command
+
+# 2. 轮询移动结果
+lark-cli drive +task_result --scenario task_check --task-id <TASK_ID>
+```
+
+### 配合 wiki +move 使用
+
+```bash
+# 1. 把 Drive 文档迁入 Wiki（异步任务可能返回 task_id）
+lark-cli wiki +move --obj-type docx --obj-token <DOC_TOKEN> --target-space-id <TARGET_SPACE_ID>
+# 若内置轮询窗口内完成：直接返回 ready=true 和 wiki_token
+# 若轮询窗口结束仍未完成：返回 ready=false、task_id、timed_out=true 和 next_command
+
+# 2. 续跑查询 Wiki 移动结果（next_command 即下面这条）
+lark-cli drive +task_result --scenario wiki_move --task-id <TASK_ID> --as user
+```
+
+> **身份保持一致**：续跑命令的 `--as` 必须与原 `wiki +move` 调用一致；`wiki +move` 的 `next_command` 已自动带上正确的 `--as`。
+
+### 配合 wiki +move-to-drive 使用
+
+```bash
+# 1. 把 Wiki 节点移到 Drive 文件夹；省略 --folder-token 表示当前身份的“我的空间”根目录
+lark-cli wiki +move-to-drive \
+  --node-token <WIKI_NODE_TOKEN> \
+  --folder-token <TARGET_FOLDER_TOKEN> \
+  --as user
+# 若轮询窗口内完成：直接返回 ready=true、obj_token、obj_type 和 url
+# 若轮询窗口结束仍未完成：返回 ready=false、完整 task_id、timed_out=true 和 next_command
+
+# 2. 使用完整 task_id 和相同身份续跑
+lark-cli drive +task_result \
+  --scenario wiki_move_to_drive \
+  --task-id <COMPLETE_TASK_ID> \
+  --as user
+```
+
+> **调用上下文和 ID 都要保持原样**：续跑的 `--profile` 与 `--as` 必须与初始移动一致；`task_id` 可能包含多个连字符，不要拆分或截断。`wiki +move-to-drive` 返回的 `next_command` 会保留 profile 与身份。
+
+### 配合 wiki +delete-space 使用
+
+```bash
+# 1. 删除知识空间（高风险写操作，必须显式带 --yes；接口可能同步返回空 task_id，也可能返回异步 task_id）
+lark-cli wiki +delete-space --space-id <SPACE_ID> --yes
+# 若同步返回：直接 ready=true
+# 若轮询窗口结束仍未完成：返回 ready=false、task_id、timed_out=true 和 next_command
+
+# 2. 续跑查询 Wiki 删除结果（next_command 即下面这条）
+lark-cli drive +task_result --scenario wiki_delete_space --task-id <TASK_ID> --as user
+```
+
+### 配合 +export 使用
+
+```bash
+# 1. 发起导出
+lark-cli drive +export --token <SOURCE_DOC_TOKEN> --doc-type docx --file-extension pdf
+# 若轮询窗口内完成：直接下载本地文件
+# 若内置轮询结束仍未完成：返回 ready=false、ticket 和 next_command
+
+# 2. 继续查询导出结果
+lark-cli drive +task_result --scenario export --ticket <EXPORT_TICKET> --file-token <SOURCE_DOC_TOKEN>
+
+# 3. 拿到 file_token 后下载
+lark-cli drive +export-download --file-token <EXPORTED_FILE_TOKEN>
+```
+
+## 权限要求
+
+| 场景 | 所需 scope |
+|------|-----------|
+| import | `drive:drive.metadata:readonly` |
+| export | `drive:drive.metadata:readonly` |
+| task_check | `drive:drive.metadata:readonly` |
+| wiki_move | `wiki:space:read` |
+| wiki_move_to_drive | `wiki:space:read` |
+| wiki_delete_space | `wiki:space:read` |
+| wiki_delete_node | `wiki:space:read` |
+
+> [!NOTE]
+> `import` 场景在 `--as bot` 且任务最终就绪时，还可能额外尝试一次协作者授权；如果 `permission_grant.status = failed`，请根据失败信息检查应用是否具备相应的文档协作者授权能力。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
+- [wiki +move-to-drive](../../lark-wiki/references/lark-wiki-move-to-drive.md) -- 将 Wiki 节点移出知识库并放入 Drive
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -0,0 +1,101 @@
+
+# drive +upload
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+上传本地文件到飞书云空间（云盘/云存储）。目标位置可以是 Drive 文件夹，也可以是 wiki 节点。
+
+## 快速决策
+- 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](../../lark-markdown/SKILL.md)。
+
+## 命令
+
+```bash
+# 上传到 Drive 文件夹
+lark-cli drive +upload --file ./report.pdf --folder-token fldbc_xxx
+
+# 上传到 wiki 节点
+lark-cli drive +upload --file ./report.pdf --wiki-token wikcn_xxx
+
+# 不指定目标时，上传到调用者的 Drive 根目录
+lark-cli drive +upload --file ./report.pdf
+
+# 自定义上传后的文件名
+lark-cli drive +upload --file ./report.pdf --name "季度总结.pdf"
+
+# 覆盖已存在文件（原地覆盖，保留 file_token）
+lark-cli drive +upload --file ./report.pdf --file-token boxcn_existing_file
+
+# 原生命令（高级/分片上传）：预上传 + 完成上传
+lark-cli drive files upload_prepare --data '{
+  "file_name": "report.pdf",
+  "parent_type": "explorer",
+  "parent_node": "fldbc_xxx",
+  "size": 1048576,
+  "file_token": "boxcn_existing_file"
+}'
+lark-cli drive files upload_finish --data '{
+  "upload_id": "<UPLOAD_ID>",
+  "block_num": 1
+}'
+
+# 查看完整参数定义
+lark-cli schema drive.files.upload_prepare
+```
+
+> [!IMPORTANT]
+> 如果文件是**以应用身份（bot）新建上传**的，如 `lark-cli drive +upload --as bot` 在上传成功后，CLI 会**尝试为当前 CLI 用户自动授予该文件的 `full_access`（可管理权限）**。
+>
+> 如果这次调用传了 `--file-token`，表示是在**覆盖已有文件**，CLI **不会**额外修改该文件权限。
+>
+> 以应用身份上传时，结果里会额外返回 `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 转给自己，必须单独确认。
+
+> [!TIP]
+> 当底层上传接口返回版本号时，shortcut 会在结果里额外透出 `version`。
+
+## 目标位置选择（关键）
+
+- 上传到 Drive 文件夹：传 `--folder-token <folder_token>`，shortcut 会发送 `parent_type=explorer`
+- 上传到 wiki 节点：传 `--wiki-token <wiki_token>`，shortcut 会发送 `parent_type=wiki`
+- 上传到 Drive 根目录：`--folder-token` 和 `--wiki-token` 都不传
+- 覆盖已有文件：额外传 `--file-token <existing_file_token>`；shortcut 会把它原样透传到底层 `upload_all` / `upload_prepare`，让后端按覆盖语义写入
+- bot 模式下，`--file-token` 覆盖只改文件内容；不会额外给当前 CLI 用户补 `full_access`
+- 不要传空目标值：`--folder-token ""` / `--wiki-token ""` 会被视为参数错误；如需上传到 Drive 根目录，应直接省略这两个参数
+- 不要传空 `--file-token`：如需新建上传，直接省略该参数；显式传空字符串会报错
+- `--folder-token` 和 `--wiki-token` 互斥，不要同时传
+- `--wiki-token` 传的是 **wiki node token**，不是 `space_id`
+
+Shortcut 参数：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file` | 是 | 本地文件路径 |
+| `--file-token` | 否 | 已存在文件的 token；传入后按“覆盖已有文件”语义上传 |
+| `--folder-token` | 否 | 目标文件夹 token；与 `--wiki-token` 互斥；省略时默认为 Drive 根目录；显式传空字符串会报错 |
+| `--wiki-token` | 否 | 目标 wiki 节点 token；与 `--folder-token` 互斥；会映射为 `parent_type=wiki`、`parent_node=<wiki_token>`；显式传空字符串会报错 |
+| `--name` | 否 | 上传后的文件名；默认使用本地文件名 |
+
+参数（预上传 `--data` JSON body）：
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `file_name` | 是 | 文件名 |
+| `parent_type` | 是 | 父节点类型；上传到文件夹 / 根目录时用 `"explorer"`，上传到 wiki 节点时用 `"wiki"` |
+| `parent_node` | 是 | 父节点 token；`explorer` 时传文件夹 token（根目录可为空字符串），`wiki` 时传 wiki node token |
+| `size` | 是 | 文件大小（字节） |
+| `file_token` | 否 | 已存在文件 token；传入后覆盖该文件内容 |
+
+> [!CAUTION]
+> 这是**写入操作** —— 执行前必须确认用户意图。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/skills/lark-drive/references/lark-drive-version-delete.md

@@ -0,0 +1,38 @@
+# drive +version-delete
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+删除指定的历史版本。该 shortcut 同时支持 `--as user` 和 `--as bot`；自动化场景推荐使用 `--as bot`。
+
+## 命令
+
+```bash
+lark-cli drive +version-delete \
+  --file-token boxcnxxxxxxxx \
+  --version 7633658129540910621 \
+  --yes \
+  --as bot
+
+lark-cli drive +version-delete \
+  --file-token boxcnxxxxxxxx \
+  --version 7633658129540910621 \
+  --yes \
+  --as user
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | 目标文件 token |
+| `--version` | 是 | `drive +version-history` 返回的长数字 `version` 字段，不是 `tag` |
+| `--yes` | 是 | 确认执行高风险删除操作 |
+
+## 返回值
+
+无额外业务字段，以命令成功 / 失败为准。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数