@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/lark-tools/cli-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/server/assets/skills/lark-tools/cli-skills/lark-drive/references/lark-drive-reactions.md

@@ -0,0 +1,113 @@
+# drive reactions
+
+> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 Drive 评论卡片模型、评论数/回复数统计口径、`file_token` / `file_type` 规则；再阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+处理文档评论 / 回复上的 reaction（点赞、表情、各表情数量、谁点了什么、添加/删除表情）。这个场景不常见，但规则比较集中：查询时只有在用户明确需要 reaction 信息时才带 `need_reaction=true`；写入时统一使用 `drive file.comment.reply.reactions update_reaction`，操作对象始终是 `reply_id`。
+
+> [!IMPORTANT]
+> **`reaction_type` 只能使用本文下方“完整 `reaction_type` 列表”中定义的枚举值。**
+> 不要自由填写、不要根据自然语言临时编造、也不要把列表里的 mixed-case 值改写成别的大小写形式。需要写入时，只能从下方枚举中原样选择并传参。
+
+## 何时使用
+
+- 用户明确要求查看评论 / 回复上的 reaction（表情）。
+- 用户要统计某条评论卡片有哪些表情、各表情数量，或要看谁点了什么。
+- 用户要给评论或回复添加 / 删除 reaction。
+
+## 查询规则
+
+- `drive file.comments list`、`drive file.comments batch_query`、`drive file.comment.replys list` 都支持通过指定`need_reaction`查询reaction信息。
+- `need_reaction` 只在用户明确需要 reaction 信息时再带；如果用户只关心评论正文、回复正文、评论数 / 回复数，默认不要加。
+- 遍历评论卡片并顺带拿 reaction：使用 `drive file.comments list`。
+- 已知评论 ID，批量查看 reaction：使用 `drive file.comments batch_query`，并在请求体里带 `need_reaction=true`。
+- 某张评论卡片下继续翻页拉 reply reaction：使用 `drive file.comment.replys list`。
+- 如果 `drive file.comments list` 返回的某个 `item.has_more=true`，且用户要完整的 reply reaction 数据，后续每一页 `drive file.comment.replys list` 都要持续带 `need_reaction=true`。
+
+## 查询示例
+
+```bash
+# 遍历评论卡片，并把 reaction 一起拿回来
+lark-cli drive file.comments list \
+  --params '{"file_token":"<DOC_TOKEN>","file_type":"docx","need_reaction":true}'
+
+# 已知 comment_id，批量查询评论卡片 reaction
+lark-cli drive file.comments batch_query \
+  --params '{"file_token":"<DOC_TOKEN>","file_type":"docx"}' \
+  --data '{"comment_ids":["<COMMENT_ID>"],"need_reaction":true}'
+
+# 继续翻某张评论卡片下的 replies，并把 reaction 一起拿回来
+lark-cli drive file.comment.replys list \
+  --params '{"file_token":"<DOC_TOKEN>","comment_id":"<COMMENT_ID>","file_type":"docx","need_reaction":true}'
+```
+
+## 写入规则
+
+- 添加 / 删除 reaction 时，使用 `drive file.comment.reply.reactions update_reaction`。
+- 请求里必须带正确的 `file_type`，并在 body 中传 `action=add|delete`、`reply_id`、`reaction_type`。
+- `update_reaction` 的操作对象是 `reply_id`，不是 `comment_id`。
+- 如果用户说要给“这条评论”加 / 删 reaction，通常需要定位到该评论卡片首条 reply 的 `reply_id` 再操作。
+
+## 写入示例
+
+```bash
+# 给某条 reply 添加一个点赞 reaction
+lark-cli drive file.comment.reply.reactions update_reaction \
+  --params '{"file_token":"<DOC_TOKEN>","file_type":"docx"}' \
+  --data '{"action":"add","reply_id":"<REPLY_ID>","reaction_type":"THUMBSUP"}'
+
+# 删除某条 reply 上已有的 DONE reaction
+lark-cli drive file.comment.reply.reactions update_reaction \
+  --params '{"file_token":"<DOC_TOKEN>","file_type":"docx"}' \
+  --data '{"action":"delete","reply_id":"<REPLY_ID>","reaction_type":"DONE"}'
+```
+
+> [!CAUTION]
+> `update_reaction` 是写入操作。执行前必须确认用户意图，不要默认替用户点表情。
+
+## `reaction_type` 使用规则
+
+- `reaction_type` 必须传平台定义的枚举字符串，大小写敏感。
+- 不要擅自把 mixed-case 值改成全大写，例如 `Yes`、`No`、`Get`、`EatingFood`、`CheckMark`、`CrossMark` 都要按原值传。
+- **不要编造列表外的 `reaction_type`，也不要把自然语言描述臆造成平台未定义的新枚举**。
+- 如果用户给的是自然语言语义（如“点赞”“在处理中”“确认一下”），可以在下方枚举列表内选择语义最接近的现有值；如果是近似映射，应在执行时明确告知用户。
+
+## 常见语义联想
+
+- `Yes`：确认 / 同意 / 批准。
+- `No`：拒绝 / 不同意 / 否定。
+- `DONE`：已完成 / 已处理。
+- `Typing`：正在输入 / 正在处理中 / 正在跟进（近似语义）。
+- `OK`：好的 / 收到 / 确认一下。
+- `THUMBSUP`：点赞 / 认可。
+- `LGTM`：看起来没问题 / 可以继续。
+
+## 完整 `reaction_type` 列表
+
+以下枚举按当前 Drive 评论 reaction 指引维护，使用时请保持原样：
+
+```text
+ANGRY, APPLAUSE, ATTENTION, AWESOME, BEAR, BEER, BETRAYED, BIGKISS
+BLACKFACE, BLUBBER, BLUSH, BOMB, CAKE, CHUCKLE, CLAP, CLEAVER
+COMFORT, CRAZY, CRY, CUCUMBER, DETERGENT, DIZZY, DONE, DONNOTGO
+DROOL, DROWSY, DULL, DULLSTARE, EATING, EMBARRASSED, ENOUGH, ERROR
+EYESCLOSED, FACEPALM, FINGERHEART, FISTBUMP, FOLLOWME, FROWN, GIFT, GLANCE
+GOODJOB, HAMMER, HAUGHTY, HEADSET, HEART, HEARTBROKEN, HIGHFIVE, HUG
+HUSKY, INNOCENTSMILE, JIAYI, JOYFUL, KISS, LAUGH, LIPS, LOL
+LOOKDOWN, LOVE, MONEY, MUSCLE, NOSEPICK, OBSESSED, OK, PARTY
+PETRIFIED, POOP, PRAISE, PROUD, PUKE, RAINBOWPUKE, ROSE, SALUTE
+SCOWL, SHAKE, SHHH, SHOCKED, SHOWOFF, SHY, SICK, SILENT
+SKULL, SLAP, SLEEP, SLIGHT, SMART, SMILE, SMIRK, SMOOCH
+SMUG, SOB, SPEECHLESS, SPITBLOOD, STRIVE, SWEAT, TEARS, TEASE
+TERROR, THANKS, THINKING, THUMBSUP, TOASTED, TONGUE, TRICK, UPPERLEFT
+WAIL, WAVE, WELLDONE, WHAT, WHIMPER, WINK, WITTY, WOW
+WRONGED, XBLUSH, YAWN, YEAH, FIREWORKS, BULL, CALF, AWESOMEN
+2021, CANDIEDHAWS, REDPACKET, FORTUNE, LUCK, FIRECRACKER, Yes, No
+Get, LGTM, Lemon, EatingFood, Hundred, MinusOne, ThumbsDown, Fire
+OKR, Drumstick, BubbleTea, Loudspeaker, Pin, Coffee, Alarm, Trophy
+Music, Typing, Pepper, CheckMark, CrossMark
+```
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/server/assets/skills/lark-tools/cli-skills/lark-drive/references/lark-drive-task-result.md

@@ -0,0 +1,264 @@
+
+# drive +task_result
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+查询异步任务结果。该 shortcut 聚合了导入、导出、移动/删除文件夹、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>
+
+# 查询移动/删除文件夹任务状态
+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>
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--scenario` | 是 | 任务场景，可选值：`import` (导入任务)、`export` (导出任务)、`task_check` (移动/删除文件夹任务)、`wiki_move` (Wiki 移动任务) |
+| `--ticket` | 条件必填 | 异步任务 ticket，**import/export 场景必填** |
+| `--task-id` | 条件必填 | 异步任务 ID，**task_check / wiki_move 场景必填** |
+| `--file-token` | 条件必填 | 导出任务对应的源文档 token，**export 场景必填** |
+
+## 场景说明
+
+| 场景 | 说明 | 所需参数 |
+|------|------|----------|
+| `import` | 文档导入任务（如将本地文件导入为云文档） | `--ticket` |
+| `export` | 文档导出任务（如云文档导出为 PDF/Word） | `--ticket`、`--file-token` |
+| `task_check` | 文件夹移动/删除任务 | `--task-id` |
+| `wiki_move` | Wiki 移动任务（`wiki +move` 的 docs-to-wiki 异步流程，超时后续跑用） | `--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`: 保留完整列表（适用于一次任务移动多个文档的场景）
+
+## 使用场景
+
+### 配合 +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`。
+
+### 配合 +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` |
+
+> [!NOTE]
+> `import` 场景在 `--as bot` 且任务最终就绪时，还可能额外尝试一次协作者授权；如果 `permission_grant.status = failed`，请根据失败信息检查应用是否具备相应的文档协作者授权能力。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/server/assets/skills/lark-tools/cli-skills/lark-drive/references/lark-drive-upload.md

@@ -0,0 +1,67 @@
+
+# drive +upload
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+上传本地文件到飞书云空间。
+
+## 命令
+
+```bash
+# 推荐：使用 shortcut 一步上传
+lark-cli drive +upload --file ./report.pdf --folder-token fldbc_xxx
+
+# 自定义上传后的文件名
+lark-cli drive +upload --file ./report.pdf --name "季度总结.pdf"
+
+# 生成可用临时下载链接的上传方式（素材上传，适用于后续用 curl 下载）
+# 注意：需要可写 docx 文档 ID（用于挂载素材 block），且文件最大 20MB
+lark-cli drive +upload --as-media --doc docx_xxx --file ./report.pdf
+
+# 取出 tmp_download_url 后可直接 curl 下载
+curl -L -o report.pdf "<TMP_DOWNLOAD_URL>"
+
+# 原生命令（高级/分片上传）：预上传 + 完成上传
+lark-cli drive files upload_prepare --data '{
+  "file_name": "report.pdf",
+  "parent_type": "explorer",
+  "parent_node": "fldbc_xxx",
+  "size": 1048576
+}'
+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`（可管理权限）**。
+>
+> 以应用身份上传时，结果里会额外返回 `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 转给自己，必须单独确认。
+
+参数（预上传 `--data` JSON body）：
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `file_name` | 是 | 文件名 |
+| `parent_type` | 是 | 父节点类型，如 `"explorer"` |
+| `parent_node` | 是 | 父节点 token（文件夹 token） |
+| `size` | 是 | 文件大小（字节） |
+
+> [!CAUTION]
+> 这是**写入操作** —— 执行前必须确认用户意图。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

package/server/assets/skills/lark-tools/cli-skills/lark-event/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: lark-event
+version: 1.0.0
+description: "飞书事件订阅：通过 WebSocket 长连接实时监听飞书事件（消息、通讯录变更、日历变更等），输出 NDJSON 到 stdout，支持 compact Agent 友好格式、正则路由、文件输出。当用户需要实时监听飞书事件、构建事件驱动管道时使用。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli event --help"
+---
+
+# event (v1)
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 了解认证、权限处理和安全规则。
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`lark-cli event +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+subscribe`](references/lark-event-subscribe.md) | Subscribe to Lark events via WebSocket long connection (read-only, NDJSON output); bot-only; supports compact agent-friendly format, regex routing, file output |