@wagemule/daemon 0.1.2 → 0.1.3

package/dist/skills/larksuite/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/dist/skills/larksuite/lark-drive/references/lark-drive-pull.md

@@ -0,0 +1,137 @@
+
+# drive +pull
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+把飞书云空间的某个文件夹**单向、文件级**镜像到本地目录（Drive → 本地）。命令递归列出 `--folder-token` 下所有 `type=file` 的文件，逐一下载到 `--local-dir` 对应的相对路径，子文件夹自动复刻为本地目录。
+
+> ⚠️ **不是 directory-level mirror**：`--delete-local` 只删除本地"多余"的常规文件，不删除空目录。如果云端把整个子文件夹删了，对应的本地子目录会留空（里面的文件被清掉，目录本身保留）；想精确同步目录结构请自己 `rmdir` 处理空壳。
+
+输出按"动作"分类：
+
+| 字段 | 含义 |
+|------|------|
+| `summary.downloaded` | 成功下载的文件数 |
+| `summary.skipped` | 因 `--if-exists=skip` 或 `--if-exists=smart` 命中“无需下载”而跳过的文件数 |
+| `summary.failed` | 下载或写盘失败的文件数 |
+| `summary.deleted_local` | 启用 `--delete-local --yes` 时删除的本地文件数 |
+| `items[]` | 每个文件的明细（`rel_path` / `file_token` / `source_id` / `action` / 失败时的 `error`） |
+
+`summary.failed > 0` 时命令以 **非零状态码**（`exit=1`，`error.type=partial_failure`）退出，且同一份 `summary + items` 会在 `error.detail` 里返回；脚本/agent 直接通过 exit code 判断成败即可，不需要再去解 `summary.failed`。
+
+## 远端同名文件冲突
+
+如果 Drive 中多个条目映射到同一个 `rel_path`，默认直接失败（`error.type=duplicate_remote_path`），且不会下载、覆盖或删除任何本地文件。只有“多个 `type=file` 同名”的场景支持显式策略；`file-folder` 这类异构冲突始终直接失败。
+
+| 策略 | 行为 |
+|------|------|
+| `fail` | 默认。返回所有冲突条目的完整信息，不写盘 |
+| `rename` | 仅适用于 duplicate file。下载全部重复文件；第一个保留原名，后续文件使用稳定 hash 后缀生成唯一文件名；若短后缀目标已被占用，会自动升级到更强后缀 |
+| `newest` | 只下载 `modified_time` 最新的远端文件 |
+| `oldest` | 只下载 `created_time` 最早的远端文件 |
+
+`rename` 命名规则稳定且可追溯：`report.pdf` 的后续重复项会落盘为 `report__lark_<hash>.pdf`，例如 `report__lark_3a2f4c5d6e7f.pdf`。如果这个短 hash 目标名已经被同目录下的其他远端对象占用，CLI 会自动改用更长的稳定 hash，必要时再追加序号后缀，直到目标名唯一。此模式下 `items[]` 不再返回可直接复用的 Drive `file_token`；CLI 会在 `source_id` 中返回稳定 hash 标识符，供日志、比对和人工排查使用。
+
+## 命令
+
+```bash
+# 基础用法 —— 把云端 fldcXXX 镜像到 ./repo
+lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx
+
+# 推荐的重复同步用法：smart 会按 modified_time 跳过已经对齐的本地文件
+lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx \
+  --if-exists smart
+
+# 已存在的本地文件保持不动
+lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx \
+  --if-exists skip
+
+# 云端有多个同名二进制文件时，显式下载全部并用稳定 hash 后缀改名
+lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx \
+  --on-duplicate-remote rename
+
+# 文件级镜像：下载新文件 + 删除云端没有的本地文件（不删空目录）
+# （--delete-local 必须搭配 --yes，否则会被 Validate 直接拒绝）
+lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx \
+  --delete-local --yes
+```
+
+## 参数
+
+| 标志 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--local-dir` | 是 | path | 本地根目录（**必须是 cwd 的相对路径**；绝对路径或逃出 cwd 的相对路径会被 CLI 直接拒绝） |
+| `--folder-token` | 是 | string | 源 Drive 文件夹 token |
+| `--if-exists` | 否 | enum | 本地文件已存在时的策略：`overwrite`（**默认**，Drive 作为权威源时使用）/ `smart`（**推荐用于重复增量同步**；当本地 mtime 已与远端 `modified_time` 匹配或更新时跳过下载）/ `skip` |
+| `--on-duplicate-remote` | 否 | enum | 云端多个条目映射到同一个 `rel_path` 时的策略：`fail`（默认）；如果冲突全是 `type=file`，还可选 `rename` / `newest` / `oldest` |
+| `--delete-local` | 否 | bool | 删除本地"云端没有的常规文件"（**不删空目录**，因此是 file-level mirror）；**必须配合 `--yes`** |
+| `--yes` | 否 | bool | 确认 `--delete-local`；不传时该破坏性操作在 Validate 阶段被拒绝 |
+
+## 比较与下载范围
+
+- **只下载 Drive `type=file` 的二进制文件**。在线文档（`docx` / `sheet` / `bitable` / `mindnote` / `slides`）和快捷方式（`shortcut`）会被跳过 —— 它们没有等价的本地二进制可写盘，否则会变成产生噪声的"假"下载。
+- 子文件夹会递归遍历；rel_path 形如 `sub1/sub2/file.txt`，本地缺失的父目录会被自动创建。
+- 已存在的本地文件按 `--if-exists` 决定 `overwrite` / `smart` / `skip`。其中 **`smart` 是推荐的重复同步模式**：只要本地 mtime 在远端时间精度下已经等于或晚于远端 `modified_time`，就跳过下载；时间戳缺失/非法时会退回安全路径继续下载，不会盲跳。想做 `keep-both` 这类的仍需自己改名再 pull。
+- 云端同名冲突默认失败；只有“冲突全是 `type=file`”且传了 `--on-duplicate-remote rename|newest|oldest` 时才会继续。
+
+## --delete-local 的安全行为
+
+`--delete-local` 是命令里**唯一的破坏性 flag**，会按"本地有但云端没有"清理本地常规文件。设计上把它跟 `--yes` 强绑定，且与下载阶段的失败联动：
+
+- `--delete-local`（无 `--yes`）→ Validate 直接报错：`--delete-local requires --yes`，没有任何下载、列表请求或删除发生。
+- `--delete-local --yes`，**且下载阶段全部成功** → 扫一遍 `--local-dir` 下所有常规文件，把不在云端清单里的逐个 `os.Remove`。**只删常规文件，不删目录**：远端文件夹被删除后，对应本地目录会保留空壳。
+- `--delete-local --yes`，**但下载阶段有任何条目失败** → **跳过整个删除阶段**，命令以 `partial_failure` 非零退出。设计意图：避免出现"前面下载失败、后面继续删本地文件"的半同步状态；操作者修好下载错误后再重跑即可。
+- 远端同名文件冲突且使用默认 `fail` → 在下载阶段前失败，删除阶段不会运行。
+- 不传 `--delete-local` → `summary.deleted_local` 永远是 0；命令对本地"多余"文件视而不见。
+
+第 6 章里把 `+pull --delete-local` 标了 `high-risk-write`，CLI 这边的实现等价于"未传 `--yes` 时拒绝执行"，符合该约束的精神。
+
+## 输出 schema
+
+```json
+{
+  "summary": {
+    "downloaded": 0,
+    "skipped": 0,
+    "failed": 0,
+    "deleted_local": 0
+  },
+  "items": [
+    {"rel_path": "...", "file_token": "...", "action": "downloaded"},
+    {"rel_path": "...", "source_id": "hash_3a2f4c5d6e7f", "action": "downloaded"},
+    {"rel_path": "...", "source_id": "hash_3a2f4c5d6e7f", "action": "failed", "error": "..."},
+    {"rel_path": "...", "action": "deleted_local"},
+    {"rel_path": "...", "action": "delete_failed", "error": "..."}
+  ]
+}
+```
+
+`rel_path` 始终用 `/` 作为分隔符（跨平台一致）。删除条目（`deleted_local` / `delete_failed`）没有 `file_token`。`rename` 模式下，duplicate 文件条目会返回 `source_id` 而不是可调用 API 的真实 `file_token`；其余模式仍返回真实 `file_token`。
+
+## 性能注意
+
+- 默认 `overwrite` 下，重复跑会重新下载所有命中的同名文件；`skip` 下则完全不碰已存在文件；**`smart` 下才会按 `modified_time` 跳过已经对齐的本地文件**，适合重复增量同步。
+- 想更精细地控制下载量，可以先 `+status` 找出 `new_remote` 和 `modified`，再只对这些文件单独 `+download`；或者直接在整目录同步时使用 `--if-exists smart`。
+- 大文件会用 SDK 的流式下载（不会把整个 body 读进内存），但本地磁盘空间需要够。
+
+## 所需 scope
+
+| 操作 | scope |
+|------|-------|
+| 列出文件夹 / 子目录 | `drive:drive.metadata:readonly` |
+| 下载文件 | `drive:file:download` |
+
+如果当前 token 缺这些 scope，命令会直接报 `missing_scope` 并提示重新登录。`drive:drive` 在部分企业被策略禁用，所以 +pull 故意只声明上面这两个细粒度 scope。
+
+## 范围限制
+
+`--local-dir` 只接受 cwd 内的相对路径。CLI 会先 `EvalSymlinks` 整条路径，再判断它是否仍落在 cwd 内 —— **指向 cwd 外的符号链接也会被拒**，"在 cwd 内放一条软链指向外面" 这条捷径走不通，会直接撞上 `unsafe file path`。
+
+如果用户想 pull 到 cwd 之外的目录，**不要 agent 自己 `cd` 绕过**。可以选：让用户在外部把 agent 工作目录切换到目标的祖先后重启会话；或者把目标整体物理移动 / 拷贝到 cwd 内（不是软链）；或者直接放弃这次同步，改用别的方式。
+
+## 参考
+
+- [lark-drive](../SKILL.md) —— 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) —— 认证和全局参数
+- [lark-drive-status](lark-drive-status.md) —— 下载前先看差异
+- [lark-drive-download](lark-drive-download.md) —— 单文件按需拉取

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

@@ -0,0 +1,162 @@
+
+# drive +push
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+把本地目录**单向、文件级**镜像到飞书云空间的某个文件夹（本地 → Drive）。命令递归列出 `--folder-token` 下的远端清单，遍历 `--local-dir` 的所有常规文件，按相对路径在 Drive 上新建、覆盖或跳过；可选地（`--delete-remote --yes`）删除云端"本地没有"的 `type=file`。
+
+> **"文件级镜像"≠"目录镜像"。** 命令只在文件维度收敛差异：本地多了文件就上传，本地少了文件且开了 `--delete-remote --yes` 就删远端文件。**远端只有的空目录、本地已删除的目录**都不会被收敛，云端目录树的多余结构不会被清理。如果需要"目录也要保持完全一致"，得自行先 `+status` 找差异、再手动处理多余目录。
+
+输出按"动作"分类：
+
+| 字段 | 含义 |
+|------|------|
+| `summary.uploaded` | 成功新建或覆盖的文件数 |
+| `summary.skipped` | 因 `--if-exists=skip` 或 `--if-exists=smart` 命中“无需传输”而跳过的文件数 |
+| `summary.failed` | 上传 / 覆盖 / 建目录 / 删除失败的条目数；**只要不为 0，命令就以非零状态退出**（结构化 `items[]` 仍在 stdout 上） |
+| `summary.deleted_remote` | 启用 `--delete-remote --yes` 时删除的云端文件数 |
+| `items[]` | 每个条目的明细（`rel_path` / `file_token` / `action` / 覆盖时的 `version` / `size_bytes` / 失败时的 `error`） |
+
+`items[].action` 取值：`uploaded` / `overwritten` / `skipped` / `folder_created` / `deleted_remote` / `failed` / `delete_failed`。
+
+> 本地目录（包括空目录）会被镜像到 Drive；新建的子目录会以 `action: "folder_created"` 出现在 `items[]` 里，但**不计入** `summary.uploaded`（该字段只数文件）。已存在的远端目录复用其 token，不会重复 `create_folder`，也不会出现在 `items[]` 里。
+
+## 远端同名文件冲突
+
+如果 Drive 中多个条目映射到同一个 `rel_path`，默认直接失败（`error.type=duplicate_remote_path`），且不会上传、覆盖或进入 `--delete-remote` 删除阶段。只有“多个 `type=file` 同名”的场景支持显式策略；`file-folder` 这类异构冲突始终直接失败。
+
+| 策略 | 行为 |
+|------|------|
+| `fail` | 默认。返回所有冲突条目的完整信息，不写远端 |
+| `newest` | 只把本地文件与 `modified_time` 最新的远端文件对齐 |
+| `oldest` | 只把本地文件与 `created_time` 最早的远端文件对齐 |
+
+`+push` 不提供 `rename`：本地一个文件无法表达要覆盖多个远端对象。若用户想保留多个云端副本，应先显式整理云端文件，再重新 push。
+
+## 命令
+
+```bash
+# 基础用法 —— 把本地 ./repo 推送到云端 fldcXXX
+# 默认 --if-exists=skip：已经存在的远端文件保持不动，只新增、不覆盖。
+lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx
+
+# 重复同步时可用 smart 做增量优化：它会按 modified_time 跳过已对齐的远端文件；但如果远端更旧，仍会继续走覆盖路径
+lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
+  --if-exists smart
+
+# 显式覆盖远端同名文件（依赖 upload_all 的灰度协议字段，详见下文"覆盖语义"）
+lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
+  --if-exists overwrite
+
+# 云端已有多个同名二进制文件时，显式选择一个远端目标再覆盖
+lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
+  --if-exists overwrite --on-duplicate-remote newest
+
+# 文件级镜像同步：上传 / 覆盖 + 删除本地不存在的远端文件
+# （--delete-remote 必须搭配 --yes，否则会被 Validate 直接拒绝；
+#   且 Validate 阶段会动态检查 space:document:delete scope，缺权限会立刻失败，
+#   不会出现"上传成功了但是后面删除阶段挂了"的半同步状态）
+lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
+  --if-exists overwrite --delete-remote --yes
+```
+
+## 参数
+
+| 标志 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| `--local-dir` | 是 | path | 本地根目录（**必须是 cwd 的相对路径**；绝对路径或逃出 cwd 的相对路径会被 CLI 直接拒绝） |
+| `--folder-token` | 是 | string | 目标 Drive 文件夹 token |
+| `--if-exists` | 否 | enum | 远端文件已存在时的策略：`skip`（**默认**，安全）/ `smart`（用于重复增量同步；当远端 `modified_time` 已匹配或更新时跳过上传，否则继续走覆盖路径）/ `overwrite`（依赖灰度后端协议，详见"覆盖语义"） |
+| `--on-duplicate-remote` | 否 | enum | 云端多个条目映射到同一个 `rel_path` 时的策略：`fail`（默认）；如果冲突全是 `type=file`，还可选 `newest` / `oldest` |
+| `--delete-remote` | 否 | bool | 删除云端本地不存在的文件（文件级镜像；**不会**清理远端只有的目录）；**必须配合 `--yes`**，且 Validate 阶段会动态检查 `space:document:delete` scope |
+| `--yes` | 否 | bool | 确认 `--delete-remote`；不传时该破坏性操作在 Validate 阶段被拒绝 |
+
+## 上传与目录复刻范围
+
+- **只上传 / 覆盖 / 删除 Drive `type=file`**。在线文档（`docx` / `sheet` / `bitable` / `mindnote` / `slides`）和快捷方式（`shortcut`）即使在同一 rel_path 下出现，也不会被覆盖或删除 —— 它们没有等价的本地二进制。
+- **本地目录结构整体被镜像**：所有子目录（含**空目录**）会按需在 Drive 上 `create_folder`；同名远端目录复用其 token，不重建。空目录不计入 `summary.uploaded`，但会在 `items[]` 里以 `folder_created` 形式留痕。
+- 已存在的远端文件按 `--if-exists` 决定 `overwrite` / `smart` / `skip`。其中 `smart` 是**增量优化模式**：只要远端 `modified_time` 在同等时间精度下已经等于或晚于本地 mtime，就跳过上传；时间戳缺失/非法时会退回安全路径继续上传，不会盲跳。**但如果远端更旧，`smart` 会继续走和 `overwrite` 相同的覆盖路径，因此也继承同样的 rollout / version 返回 caveat。** 想做 `keep-both` 这类的仍需自行改名再 push。
+- 云端同名冲突默认失败；只有“冲突全是 `type=file`”且传了 `--on-duplicate-remote newest|oldest` 时才会选择一个远端文件继续。启用 `--delete-remote` 时，未被选中的 duplicate sibling 也会被删除，最终远端只保留一个被选中的文件副本；只有在 `--if-exists=overwrite` 成功时，才能保证该副本内容与本地对齐。
+
+## 覆盖语义
+
+`--if-exists=overwrite` 走 `POST /open-apis/drive/v1/files/upload_all`，并在 form 中带上现有文件的 `file_token`，由后端原地更新内容并返回新版本号。`items[].version` 字段会回填该版本号。
+
+`--if-exists=smart` 是给“重复跑同步”的场景增加的增量优化：当远端 `modified_time` 在同等时间精度下已经等于或晚于本地 mtime 时，命令会把该文件计为 `skipped`；时间戳缺失、非法或更旧时，则继续走正常上传/覆盖路径。**也就是说，只要 smart 判定“远端不够新”，它就会进入与 `--if-exists=overwrite` 相同的覆盖实现，因此在未 rollout version 字段的 tenant 上仍可能非零失败。**
+
+> **为什么默认是 `skip` 而不是 `overwrite`：** `upload_all` 接受 `file_token` 字段、并在响应里返回 `version` 是设计文档（Drive 同步盘）规定的协议；此后端尚在灰度发布。在还未开通该字段的 tenant 上，`--if-exists=overwrite` 会因"无 version 返回"而把对应文件标成 `failed`，整次 `+push` 也会因此非零退出。所以默认值故意定为 `skip`：第一次往一个已经有内容的目录里 push，不会因为协议没到位就把整次运行打挂；要真的覆盖远端，必须显式带 `--if-exists overwrite`。新建上传不依赖该字段，不受影响。
+
+大文件（>20MB）会自动切到三段式 `upload_prepare` / `upload_part` / `upload_finish`；该路径下 `version` 暂未在响应中返回，覆盖结果中 `items[].version` 会留空，但 `file_token` 与 `action: overwritten` 仍会正确产出。
+
+## --delete-remote 的安全行为
+
+`--delete-remote` 是命令里**唯一的破坏性 flag**，会按"远端有但本地没有"逐个 `DELETE /open-apis/drive/v1/files/<token>?type=file` 清理云端副本。设计上把它跟 `--yes` 强绑定：
+
+- `--delete-remote`（无 `--yes`）→ Validate 直接报错：`--delete-remote requires --yes`，不会发起任何列表 / 上传 / 删除请求。
+- `--delete-remote --yes` → Validate 阶段还会**动态做一次** `space:document:delete` 的 scope 预检：缺这条 scope 时整次运行立刻失败、不发任何上传请求，避免出现"上传都成功了，但删除阶段才报 missing_scope"的半同步状态。
+- `--delete-remote --yes`（且 scope 已授权）→ 正常执行：先把本地文件 push 上去，再扫一遍远端 `type=file` 列表，把不在本地清单里的逐个删除。**任何上传 / 覆盖 / 建目录失败时，整段 `--delete-remote` 阶段会被跳过**（stderr 上有提示），命令以非零状态退出，远端不会被破坏。
+- 远端同名冲突且使用默认 `fail`，或冲突里混有 folder / 其他非 `type=file` 对象 → 在上传阶段前失败，删除阶段不会运行。
+- 不传 `--delete-remote` → `summary.deleted_remote` 永远是 0；命令对远端"多余"文件视而不见。
+- 在线文档（docx / sheet / bitable / ...）和快捷方式即使本地完全没有同名文件，也**不会**进入删除候选，因为它们从来不进 `summary.uploaded` 的对齐域。
+- **远端只有的空目录、本地已删除的目录**也不会被清理 —— 这是"文件级镜像"的语义边界，命令不会对目录结构做主动收敛。
+
+第 6 章里把 `+push --delete-remote` 标了 `high-risk-write`，CLI 这边的实现等价于"未传 `--yes` 时拒绝执行 + 动态 scope 预检"，符合该约束的精神。
+
+## 输出 schema
+
+```json
+{
+  "summary": {
+    "uploaded": 0,
+    "skipped": 0,
+    "failed": 0,
+    "deleted_remote": 0
+  },
+  "items": [
+    {"rel_path": "...", "file_token": "...", "action": "folder_created"},
+    {"rel_path": "...", "file_token": "...", "action": "uploaded",       "size_bytes": 0},
+    {"rel_path": "...", "file_token": "...", "action": "overwritten",    "version": "...", "size_bytes": 0},
+    {"rel_path": "...", "file_token": "...", "action": "skipped",        "size_bytes": 0},
+    {"rel_path": "...",                       "action": "failed",        "size_bytes": 0, "error": "..."},
+    {"rel_path": "...", "file_token": "...", "action": "deleted_remote"},
+    {"rel_path": "...", "file_token": "...", "action": "delete_failed",  "error": "..."}
+  ]
+}
+```
+
+`rel_path` 始终用 `/` 作为分隔符（跨平台一致）。
+
+## 性能注意
+
+- 默认 `skip` 下，已存在的远端文件一律不碰；`overwrite` 下，重复跑会重传所有命中的同名文件；`smart` 下会按 `modified_time` 跳过已对齐的远端文件，但对“远端更旧”的文件仍会进入覆盖路径，因此它减少的是**不必要的重传**，不是把覆盖风险完全拿掉。
+- 想更精细地控制传输量，可以先 `+status` 找出 `new_local` 和 `modified`，再只对这些文件单独上传 / 覆盖；或者直接在整目录同步时使用 `--if-exists smart`。
+- 大文件会用三段式分片上传（不会把整个 body 读进内存），但本地磁盘和上行带宽需要够。
+
+## 所需 scope
+
+| 操作 | scope | 是否在命令上预声明 |
+|------|-------|-------------------|
+| 列出文件夹 / 子目录 | `drive:drive.metadata:readonly` | ✅ 预声明 |
+| 上传 / 覆盖文件 | `drive:file:upload` | ✅ 预声明 |
+| 新建子目录（`create_folder`） | `space:folder:create` | ✅ 预声明 |
+| 删除文件（仅 `--delete-remote --yes`） | `space:document:delete` | ⚙️ 不在命令默认 Scopes 里，但在 `--delete-remote --yes` 时由 Validate 动态预检 |
+
+`drive:drive` 在部分企业被策略禁用，所以 +push 故意只声明上面这几条细粒度 scope。
+
+> **关于 `space:document:delete`：** 框架的 scope 预检（`runner.go: checkShortcutScopes`）会在 `Validate` 和 `--dry-run` 之前就把命令上声明的 scope 全检查一遍；如果把删除 scope 也预声明，**普通上传或 dry-run** 都会因为没授权删除权限而被拦下来。所以这一项不放在命令的默认 Scopes 里，而是在 Validate 中**条件触发**：只有 `--delete-remote --yes` 同时打开时才会调用 `runtime.EnsureScopes([]string{"space:document:delete"})` 做一次动态前置校验。这样既保留了"普通上传不需要删除权限"的便利，又能在真要做镜像删除前把 scope 缺失暴露出来，避免出现"上传成功 → 删除阶段才挂"的半同步状态。
+>
+> 想一次性把权限补齐：`lark-cli auth login --scope "drive:drive.metadata:readonly drive:file:upload space:folder:create space:document:delete"`。
+
+## 范围限制
+
+`--local-dir` 只接受 cwd 内的相对路径。CLI 会先 `EvalSymlinks` 整条路径，再判断它是否仍落在 cwd 内 —— **指向 cwd 外的符号链接也会被拒**，"在 cwd 内放一条软链指向外面" 这条捷径走不通，会直接撞上 `unsafe file path`。
+
+如果用户想 push cwd 之外的目录，**不要 agent 自己 `cd` 绕过**。可以选：让用户在外部把 agent 工作目录切换到目标的祖先后重启会话；或者把目标整体物理移动 / 拷贝到 cwd 内（不是软链）；或者直接放弃这次同步，改用别的方式。
+
+## 参考
+
+- [lark-drive](../SKILL.md) —— 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) —— 认证和全局参数
+- [lark-drive-status](lark-drive-status.md) —— 上传前先看差异（避免全量回写）
+- [lark-drive-pull](lark-drive-pull.md) —— Drive → 本地的对称命令
+- [lark-drive-upload](lark-drive-upload.md) —— 单文件按需上传

package/dist/skills/larksuite/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) -- 认证和全局参数