@amaster.ai/pi-lark 0.1.4 → 0.1.6

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

@@ -0,0 +1,189 @@
+
+# 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` 时删除的云端文件数 |
+| `summary.aborted` | 命中终止性错误并停止后续批处理时为 `true` |
+| `items[]` | 每个条目的明细（`rel_path` / `file_token` / `action` / 覆盖时的 `version` / `size_bytes` / 失败时的 `error` / `hint` / `phase` / `error_class` / `code` / `subtype` / `retryable`） |
+
+`items[].action` 取值：`uploaded` / `overwritten` / `skipped` / `folder_created` / `deleted_remote` / `already_deleted` / `failed` / `delete_failed`。
+
+> 本地目录（包括空目录）会被镜像到 Drive；新建的子目录会以 `action: "folder_created"` 出现在 `items[]` 里，但**不计入** `summary.uploaded`（该字段只数文件）。已存在的远端目录复用其 token，不会重复 `create_folder`，也不会出现在 `items[]` 里。
+
+## 远端同名文件冲突
+
+如果 Drive 中多个条目映射到同一个 `rel_path`，默认直接失败（stderr 类型化错误信封：`error.type=validation`、`error.subtype=failed_precondition`，`error.params[]` 逐条列出冲突的 `rel_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 上有提示），命令以非零状态退出，远端不会被破坏。
+- 删除阶段如果服务端返回 `1061007 file has been delete`，说明目标远端文件在本次 DELETE 前已经不存在；这已经满足 `--delete-remote` 的目标状态，输出会记为 `action: "already_deleted"`，不计入 `summary.failed`，也不计入 `summary.deleted_remote`。
+- 远端同名冲突且使用默认 `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,
+    "aborted": false
+  },
+  "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": "...", "hint": "...", "phase": "upload", "error_class": "...", "code": 0, "subtype": "...", "retryable": false},
+    {"rel_path": "...", "file_token": "...", "action": "deleted_remote"},
+    {"rel_path": "...", "file_token": "...", "action": "already_deleted"},
+    {"rel_path": "...", "file_token": "...", "action": "delete_failed",  "error": "...", "hint": "...", "phase": "delete", "error_class": "...", "code": 0, "subtype": "...", "retryable": false}
+  ]
+}
+```
+
+`rel_path` 始终用 `/` 作为分隔符（跨平台一致）。
+
+## 失败处理与 agent 行为
+
+`+push` 的失败项带结构化字段，agent 必须优先读 `items[].error_class` / `phase` / `code`，不要只看自然语言 `error` 文本。`summary.aborted=true` 表示命令已经遇到终止性错误并停止后续批处理；这时**不要原样重试**，先修复根因。
+
+常见终止性错误：
+
+| `error_class` | 常见 `code` | 含义 | Agent 应对 |
+|---|---:|---|---|
+| `app_scope_missing` | `99991672` | 应用身份缺少 Drive / 文件夹相关 scope | 停止重试，引导开通错误里列出的应用身份权限，例如 `space:folder:create` 或 `drive:drive` |
+| `user_scope_missing` | `99991679` | 用户身份缺少授权 | 停止重试，走 `lark-cli auth login --scope ...` 补错误里列出的 scope |
+| `permission_denied` | `1061004` / HTTP 403 | 当前身份无权操作目标资源 | 停止重试，检查目标文件夹权限、身份类型（user / bot）和资源可见性 |
+| `invalid_api_parameters` | `1061002` | API 参数被服务端拒绝 | 停止重试，检查 `--folder-token`、覆盖模式、`file_token`、文件名和上传参数；不要对同一参数组合批量重试 |
+| `parent_node_missing` | `1061044` | 上传 / 建目录使用的父文件夹不存在或当前身份不可见 | 停止重试，检查 `--folder-token` 是否仍存在、是否有权限、父目录是否在 push 过程中被删除；不要继续上传同一目录树 |
+| `parent_sibling_limit` | `1062507` | 目标父文件夹单层子节点数量超过上限 | 停止重试，清理目标目录、换一个 `--folder-token`，或把上传内容拆到多个子目录 |
+| `rate_limited` | `99991400` | 触发频控 | 停止当前批次，退避后再重试 |
+| `server_error` | `1061001` / `2200` | Drive 服务端异常 | 停止当前批次，稍后重试；保留 `log_id` 便于排查 |
+
+非终止但需要解释的状态：
+
+- `file_size_limit` / `1061043`：文件超过 Drive 上传限制。不要继续尝试同一文件；改拆分或换存储方式。
+- `upload_size_mismatch` / `1062009`：本地文件在上传过程中发生变化，或声明大小与实际读取大小不一致。重新扫描本地文件后再 push。
+- `remote_not_found` / `1061007`：一般表示远端文件已不存在。删除阶段的 `1061007` 会被视为 `already_deleted` 成功项；其他阶段需重新列表确认远端状态。
+
+## 性能注意
+
+- 默认 `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/skills/lark-drive/references/lark-drive-reactions.md

@@ -0,0 +1,113 @@
+# drive reactions
+
+> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 Drive 评论入口，再阅读 [`lark-drive-comments-guide.md`](lark-drive-comments-guide.md) 了解评论卡片模型、评论数/回复数统计口径、`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/skills/lark-drive/references/lark-drive-search.md

@@ -0,0 +1,273 @@
+
+# drive +search（云空间/云盘/云存储搜索：扁平 flag，面向自然语言场景）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+基于 Search v2 接口 `POST /open-apis/search/v2/doc_wiki/search`，支持以**用户身份或应用身份**统一搜索云空间（云盘/云存储）对象。
+
+核心特性：
+
+- 把常用过滤条件全部**扁平化为独立 flag**（`--edited-since`、`--created-by-me`、`--mine`、`--doc-types`、`--folder-tokens` 等），不再要求用户或 AI 手写嵌套 `--filter` JSON
+- 额外暴露了 4 个"我"维度：`my_edit_time`（我编辑过）、`my_comment_time`（我评论过）、`open_time`（我打开过）、`create_time`（文档创建时间）——直接对应用户自然语言里的"最近我编辑过的"、"我评论过的"等表达
+- 自动处理 `my_edit_time` / `my_comment_time` 的小时级聚合（服务端存储粒度）：亚小时输入会向整点 snap，并在 stderr 打出提示
+- `--created-by-me` 一键从当前登录用户的 open_id 填 `original_creator_ids`，匹配“我最初创建的”；`--mine` 仍填 `creator_ids`，匹配 owner / 文档归属人
+
+> **资源发现入口统一**：`drive +search` 同样返回 `SHEET` / `Base` / `FOLDER` 等全部云空间（云盘/云存储）对象，不只是文档 / Wiki。用户说"找一个表格"、"找报表"、"最近打开的表格"时，也从这里开始；定位后再切到对应业务 skill（如 `lark-sheets`）做对象内部操作。
+
+> **身份边界**：普通关键词、类型、文件夹、Wiki 空间、owner/open_id 等显式过滤支持 `--as user` 或 `--as bot`。`--mine` / `--created-by-me` 依赖当前登录用户 open_id 自动填充过滤条件；应用身份下如果没有配置用户 open_id，请改用显式 `--creator-ids` / `--original-creator-ids`。
+
+## 命令
+
+> **关键约束：搜索关键词必须通过 `--query` 传递。**
+> 正确：`lark-cli drive +search --query "方案"`
+> 错误：`lark-cli drive +search 方案`
+> `+search` 不接受位置参数；空 `--query` 或省略 `--query` 表示纯靠 filter 浏览（合法）。
+>
+> **`--query` 最长 30 个字符**：按字符数（Unicode 码点）算，中文每字算 1 个，与 ASCII 同口径；超过 30 会被服务端拒绝（`99992402 field validation failed`，**是报错不是截断**）。长关键词必须先压缩成核心实体 + 主题词（如把整句问题压成「项目名 + 主题」再搜），不要把整句原问塞进 `--query`。
+>
+> **列表型请求不要硬塞关键词**：如果用户只是要求"我这月创建的所有文档"、"最近半年我编辑过的文档"、"按类型分类统计"这类范围浏览 / 汇总请求，且没有给出标题片段或业务关键词，应使用 `--query ""` 搭配 `--created-by-me`、`--mine`、`--created-*`、`--edited-*`、`--doc-types` 等过滤条件。不要把"查找"、"所有文档"、"最近更新过"、"按类型分类统计"这类动作词或统计意图放进 `--query`，否则会把本来应靠 filter 命中的结果过度收窄。
+
+### 自然语言 → 命令映射速查
+
+| 用户说 | 命令 |
+|---|---|
+| 我这月创建的所有文档，按类型分类统计 | `lark-cli drive +search --query "" --created-by-me --created-since "<YYYY-MM-DD>" --created-until "<YYYY-MM-DD>"` |
+| 最近半年我编辑过的文档，看看哪些最近更新过 | `lark-cli drive +search --query "" --edited-since 6m --sort edit_time` |
+| 最近一个月我编辑过的文档 | `lark-cli drive +search --query "" --edited-since 1m` |
+| 最近一个月我编辑过 且 我评论过的 | `lark-cli drive +search --query "" --edited-since 1m --commented-since 1m` |
+| 最近一周我打开过的表格 | `lark-cli drive +search --query "" --opened-since 7d --doc-types sheet` |
+| 我 owner 的所有文档（owner 语义，非"我最初创建"） | `lark-cli drive +search --query "" --mine` |
+| 我最初创建、后来转给王五 owner 的文档 | `lark-cli drive +search --query "" --created-by-me --creator-ids ou_wangwu` |
+| 我 owner、30-60 天前创建的文档（粗略"上个月"，按 30 天滑窗算；`--mine` 是 owner，`--created-*` 才是文档创建时间） | `lark-cli drive +search --query "" --mine --created-since 2m --created-until 1m` |
+| 我 owner、2026 年 3 月创建的文档（精确日历月；同上，owner + 创建时间窗两个维度） | `lark-cli drive +search --query "" --mine --created-since 2026-03-01 --created-until 2026-04-01` |
+| 关键词"预算"，最近一周我打开过，按编辑时间降序 | `lark-cli drive +search --query 预算 --opened-since 7d --sort edit_time` |
+| 某个 wiki space 下、我 owner 且 30-60 天前创建的 | `lark-cli drive +search --query "" --mine --space-ids space_xxx --created-since 2m --created-until 1m` |
+| 张三 owner / 负责的文档（注意是 owner 语义，不是张三最初创建的）| `lark-cli drive +search --query "" --creator-ids ou_zhangsan` |
+| 我最近 3 个月评论过的 docx | `lark-cli drive +search --query "" --commented-since 3m --doc-types docx` |
+
+### 更多示例
+
+```bash
+# 纯关键词搜索
+lark-cli drive +search --query "季度总结"
+
+# 使用服务端 query 高级语法
+lark-cli drive +search --query 'intitle:方案'
+lark-cli drive +search --query '"季度 总结"'
+lark-cli drive +search --query '方案 OR 草稿'
+lark-cli drive +search --query '方案 -草稿'
+
+# 只搜某个文件夹下的文档
+lark-cli drive +search --query 方案 --folder-tokens fld_123456
+
+# 只搜某个知识空间下的 Wiki
+lark-cli drive +search --query 研发规范 --space-ids space_1234567890fedcba
+
+# 指定群内分享过的文档
+lark-cli drive +search --query 方案 --chat-ids oc_1234567890abcdef
+
+# 只搜标题 / 只搜评论
+lark-cli drive +search --query 周报 --only-title
+lark-cli drive +search --query 延期原因 --only-comment
+
+# 人类可读格式
+lark-cli drive +search --query OKR --format pretty
+
+# 翻页（--format json 先拿 page_token）
+lark-cli drive +search --query 方案 --format json
+lark-cli drive +search --query 方案 --page-token '<PAGE_TOKEN>'
+```
+
+### 列表 / 统计型请求的执行步骤
+
+对"所有文档"、"按类型分类统计"、"最近更新过"这类请求，不要只跑一次搜索后直接回答。标准流程：
+
+1. 先把自然语言拆成过滤条件：原始创建者（`--created-by-me` / `--original-creator-ids`）、所有权（`--mine` / `--creator-ids`）、时间维度（`--created-*` / `--edited-*` / `--opened-*` / `--commented-*`）、类型（`--doc-types`）、空间或文件夹范围。
+2. 没有真实业务关键词时保持 `--query ""`；不要把"所有文档"、"统计"、"最近更新"放进 query。
+3. 检查返回结果的 `doc_type` / `result_meta.doc_types`、创建/编辑时间和 URL/token 是否与过滤目标一致；明显不符合的结果不要计入答案。
+4. 用户要求"所有 / 全量 / 统计"时按 `has_more` 翻页并累积去重；不要只用第一页推断总量。返回体里的 `total` 不可靠，统计要以实际去重后的结果为准。
+5. 汇总时按真实返回字段分组，例如按 `doc_type` 统计 DOCX、SHEET、BITABLE、WIKI、FILE 等，不要凭标题猜类型。
+
+### 内容检索型请求的 query 扩展
+
+用户问的是原因、结论、方案、对比等内容问题时，`--query` 应保留业务关键词，但不要只用整句原问。先用核心实体 + 主题词搜索，再按结果调整：
+
+- "东南亚服务器成本为何较其他区域贵" → 先搜 `"东南亚 服务器 成本"`，如果召回不足，再搜 `"服务器 成本 区域"`、`"非洲 欧洲 服务器 成本"`、`"机房 成本 费用"` 等同主题扩展词。
+- "某项目发布会重点" → 先搜项目名 + "发布会" + "重点/功能/一览"，再按标题和摘要判断是否需要只搜标题或扩大到正文。
+
+每轮扩展都要保留非污染、可解释的 evidence（URL/token/标题/摘要）；不能因为某个扩展词搜到高相似标题就跳过证据核验。
+
+## 参数
+
+### 核心
+
+| 参数 | 必填 | 说明 |
+|---|---|---|
+| `--query <text>` | 否 | 搜索关键词；支持服务端高级语法（`intitle:`、`""`、`OR`、`-`）。空字符串或省略表示纯 filter 浏览。**长度上限 30 个字符（按 Unicode 码点算，中文每字算 1 个，与 ASCII 同口径）；超过 30 服务端直接报 `99992402 field validation failed`，不会截断** |
+| `--page-size <n>` | 否 | 每页数量，默认 15，最大 20。超过 20 自动 clamp；非正数（≤0）回落 15；**非数字值直接返回 validation 错误** |
+| `--page-token <token>` | 否 | 上一次响应里的 `page_token`，用于翻页 |
+| `--format` | 否 | `json`（默认）/ `pretty` |
+
+### 身份维度
+
+> **语义说明（重要）**：`creator_ids`（含 `--mine` / `--creator-ids`）虽然字段名是 “creator”，但服务端实际按 **owner（文档归属人 / 负责人）** 语义匹配，**不是“最初创建人”**。真正的原始创建者使用 `original_creator_ids`（CLI 为 `--created-by-me` / `--original-creator-ids`）。
+
+| 参数 | 映射 | 说明 |
+|---|---|---|
+| `--mine` | `creator_ids = [当前用户 open_id]` | bool。一键“我 owner 的”（**不是**“我最初创建的”）；从当前登录用户身份（`runtime.UserOpenId()`）解析 open_id，取不到直接报错（提示运行 `lark-cli auth login`） |
+| `--creator-ids ou_x,ou_y` | `creator_ids = [...]` | 显式 open_id 列表，逗号分隔，按 **owner** 匹配；**与 `--mine` 互斥** |
+| `--created-by-me` | `original_creator_ids = [当前用户 open_id]` | bool。一键“我最初创建的”；从当前登录用户身份解析 open_id，取不到直接报错 |
+| `--original-creator-ids ou_x,ou_y` | `original_creator_ids = [...]` | 显式 open_id 列表，逗号分隔，按**原始创建者**匹配；**与 `--created-by-me` 互斥** |
+
+### 时间维度（每个维度一对 since/until）
+
+| 参数 | 映射 API 字段 | 是否小时 snap |
+|---|---|---|
+| `--edited-since` / `--edited-until` | `my_edit_time.start` / `.end` | ✅ start 向下取整，end 向上取整 |
+| `--commented-since` / `--commented-until` | `my_comment_time.start` / `.end` | ✅ 同上 |
+| `--opened-since` / `--opened-until` | `open_time.start` / `.end` | ❌ 原样透传 |
+| `--created-since` / `--created-until` | `create_time.start` / `.end` | ❌ 原样透传（文档创建时间，非"我"语义）|
+
+### 作用域
+
+| 参数 | 映射 | 说明 |
+|---|---|---|
+| `--doc-types docx,sheet` | `doc_types` | 逗号分隔。允许值：`doc,sheet,bitable,mindnote,file,wiki,docx,folder,catalog,slides,shortcut` |
+| `--folder-tokens fld_a,fld_b` | `folder_tokens`（仅 doc_filter） | 存在时只发 `doc_filter`；**与 `--space-ids` 互斥** |
+| `--space-ids sp_x` | `space_ids`（仅 wiki_filter） | 存在时只发 `wiki_filter`；**与 `--folder-tokens` 互斥** |
+| `--chat-ids oc_x` | `chat_ids` | 逗号分隔 |
+| `--sharer-ids ou_x` | `sharer_ids` | 逗号分隔，open_id |
+
+### 其他
+
+| 参数 | 映射 | 说明 |
+|---|---|---|
+| `--only-title` | `only_title: true` | bool |
+| `--only-comment` | `only_comment: true` | bool |
+| `--sort <value>` | `sort_type`（转大写枚举） | 允许值：`default, edit_time, edit_time_asc, open_time, create_time` |
+
+> `--sort`：CLI 只暴露服务端**正式支持**的 5 个值。服务端 enum 里 `CREATE_TIME_ASC` 协议标注"暂不支持"，`ENTITY_CREATE_TIME_ASC` / `ENTITY_CREATE_TIME_DESC` 已废弃，CLI 直接不放出来，传了会被 cobra enum 校验拒掉。
+
+## 时间值格式
+
+所有 `--*-since` / `--*-until` 共用：
+
+| 输入 | 含义 |
+|---|---|
+| `7d` / `30d` | N 天前的当前时刻 |
+| `1m` | 30 天前（固定 30 天，**不是**日历月）|
+| `3m` / `6m` | 90 / 180 天前 |
+| `1y` | 365 天前 |
+| `2026-04-01` | 本地时区 00:00:00 |
+| `2026-04-01 10:00:00` / `2026-04-01T10:00:00` | 本地时区具体时刻 |
+| `2026-04-01T10:00:00+08:00` | RFC3339 带时区 |
+| `1743523200`（≥ 10 位纯数字）| Unix 秒直接透传 |
+
+> `m` 绑定 month（30 天），不支持 minute——因为 `my_edit_time` / `my_comment_time` 在服务端是小时聚合，分钟粒度没意义。
+
+## 小时聚合（my_edit_time / my_comment_time）
+
+服务端对这两个字段按整点聚合，亚小时输入会被 CLI 向整点对齐：
+
+```text
+start: floor 到整点   16:23:45 → 16:00:00
+end:   ceil  到整点   16:23:45 → 17:00:00
+```
+
+发生对齐时，stderr 会打印一条 notice，例如：
+
+```text
+notice: my_edit_time has hour-level granularity server-side;
+        start 2026-04-22 16:23:00 → 2026-04-22 16:00:00
+        end   2026-04-22 16:28:00 → 2026-04-22 17:00:00
+```
+
+stdout 的 JSON 输出不受影响。`open_time` / `create_time` 不做 snap。
+
+## 输出
+
+- `--format json`（默认）：`{ total, has_more, page_token, results: [...] }`；所有 `*_time` 字段递归补 `*_time_iso`
+- `--format pretty`：4 列 table —— `type | title | edit_time | url`
+- `title_highlighted` / `summary_highlighted` 可能包含 `<h>` / `<hb>` 高亮标签，客户端对比前需先剥离
+
+> **注意**：返回体里的 `total` 字段不够准确（官方确认，仅供参考）。需要精确统计的场景，按实际 `results` 做去重和累加，不要把 `total` 当结果数承诺。
+
+## 决策规则
+
+- **身份快捷方式**：用户说“我创建的 / 我新建的 / 我最初创建的”文档，用 `--created-by-me`；用户说“我的 / 我负责的 / 我 owner 的”文档，用 `--mine`。`--mine` 是 owner 语义：转交出去的不算、转交给我的算。
+- **时间维度选择**：
+  - "我编辑的"、"我修改的" → `--edited-since` / `--edited-until`
+  - "我评论的"、"我回复过的" → `--commented-since` / `--commented-until`
+  - "我看过的"、"我打开过的"、"最近看过的" → `--opened-since` / `--opened-until`
+  - "创建于"、"新建的"（文档整体维度，与"我"无关）→ `--created-since` / `--created-until`
+- **作用域选择**：
+  - "某个文件夹下" → `--folder-tokens`（doc-only）
+  - "某个 wiki 空间下" → `--space-ids`（wiki-only）
+  - 两者不能同时使用，混用会报错
+- **身份 flag 互斥**：`--mine` 和 `--creator-ids` 不要同时传；`--created-by-me` 和 `--original-creator-ids` 不要同时传。owner 维度与原始创建者维度可以组合，例如“我创建后转给王五 owner”用 `--created-by-me --creator-ids ou_wangwu`。
+- **实体补全**：
+  - 用户说"某个群里"，先用 `lark-im` 查 `chat_id`
+  - 用户说“某人负责/owner 的 / 某人创建的 / 某人分享的”（非自己），先用 `lark-contact` 查 open_id，再按语义填 `--creator-ids` / `--original-creator-ids` / `--sharer-ids`
+- **查询语义下推**：`--query` 支持的服务端高级语法（`intitle:`、`""`、`OR`、`-`）优先使用，不要先模糊搜再在客户端二次过滤。
+- **query 填写边界**：只有标题片段、业务名词、项目名、会议名、文件内容关键词才应进入 `--query`。仅描述动作、时间范围、所有权、统计方式的词不算关键词，保持 `--query ""` 并依赖 filters。
+- **证据核验**：列表/统计类答案必须来自搜索结果中的实际 URL/token 和类型/时间字段；内容问答必须能指出使用了哪些非污染候选。没有可验证候选时先扩大 query 或翻页，不要直接编总结。
+- **时间表达**：
+  - 模糊相对时间（"最近半年"、"过去 30 天"、"最近一周"）→ `--*-since 6m` / `--*-since 30d` / `--*-since 7d`，不展开成 ISO 时间
+  - **日历表达**（"上个月"、"上周"、"本月"、"前年"、"今年 3 月"等明确日历单位）→ **必须算出绝对 `YYYY-MM-DD` 边界**（如"上个月" = 上一个日历月的 1 号 → 当月 1 号），**不要近似成 `1m`/`2m`**：CLI 里 `m` 是固定 30 天、`y` 固定 365 天，跟日历差 0-3 天，月末月初尤其容易偏出去
+  - 文档中的 `"<YYYY-MM-DD>"` 是运行时占位符：执行命令前按当前日期计算并替换。例如"本月"应替换为本月第一天和下月第一天，不要把示例生成时的月份硬编码进答案
+  - 绝对日期 → 直接 `YYYY-MM-DD` 或 RFC3339
+- **分页策略**：默认只返回第一页，并说明 `has_more` 和下一页命令。只有用户明确要"全部 / 全量 / 继续翻"才继续。单轮翻页上限 5 页。
+- **原始返回**：用户要求"原始数据"、"接口返回"时用 `--format json`，不做客户端精确过滤或摘要重写。
+
+## 权限
+
+| 操作 | 所需 scope |
+|---|---|
+| 搜索云空间（云盘/云存储）对象（文档 / Wiki / 表格等资源发现） | `search:docs:read` |
+
+## 常见错误
+
+| code | 含义 | 处理 |
+|---|---|---|
+| `99992351` | `--creator-ids` / `--original-creator-ids` / `--sharer-ids` 里有 open_id 超出**应用的通讯录可见范围**，服务端拒绝识别 | 让管理员在开发者后台把这些用户加进应用的"通讯录可见性"授权里；或把超出范围的 open_id 从参数里去掉。这和 `search:docs:read` scope 不是一回事 —— 是"应用能看见哪些人"而不是"应用能调用哪个接口" |
+
+## 时间范围自动裁剪（`--opened-*` 专有）
+
+服务端对 `open_time` 过滤**每次请求最多支持 3 个月**（90 天）窗口。其他三个时间维度（`--edited-*` / `--commented-*` / `--created-*`）**不受影响**。
+
+CLI 在发请求前会检查 `--opened-since` 到有效 `--opened-until`（没传则取 `now`）的跨度：
+
+| 跨度 | 行为 |
+|---|---|
+| ≤ 90 天 | 原样透传 |
+| 91 ~ 365 天 | **自动裁剪**到"最近一个 90 天 slice"，stderr 打一条 notice 列出所有剩余 slice 的 `--opened-since` / `--opened-until` 参数值 |
+| > 365 天 | 直接报 validation 错，要求缩小范围或自行拆分多次查询 |
+
+Notice 示例（用户原本要求"过去 8 个月"，会被拆成 3 个 slice）：
+
+```text
+notice: --opened-* window spans 240 days (~8 months), exceeds the server-side 3-month (90-day) limit.
+        this query was narrowed to the most recent slice; 3 slices total:
+          [slice 1/3 current] --opened-since 2026-01-24T21:54:02+08:00 --opened-until 2026-04-24T21:54:02+08:00
+          [slice 2/3]         --opened-since 2025-10-26T21:54:02+08:00 --opened-until 2026-01-24T21:54:02+08:00
+          [slice 3/3]         --opened-since 2025-08-27T21:54:02+08:00 --opened-until 2025-10-26T21:54:02+08:00
+        pagination: paginate within a slice via --page-token using that slice's --opened-since / --opened-until values verbatim (NOT the original relative time like '1y' / '8m' — relative times re-resolve against time.Now() and would mismatch the page_token); switch to the next slice's --opened-* flags only after has_more=false, and do not carry --page-token across slices.
+```
+
+### Agent 看到 notice 时的处理
+
+**标准流程（分页 × slice 的先后顺序）：**
+
+1. **跑 slice 1**（本次请求已自动裁剪到这个窗口），把结果呈现给用户
+2. **先在当前 slice 内翻页**：返回的 `has_more = true` 且用户想看更多时，把 `--opened-since` / `--opened-until` 改成 notice 里 `[slice 1/N current]` 行给出的**具体时间值**（**不要继续用原始的 `--opened-since 1y` 这种相对值**——CLI 每次调用都按 `time.Now()` 重算窗口，相对值 + `--page-token` 一起跑会让 page_token 绑到一个漂移的窗口上、结果静默失真），加 `--page-token` 继续翻，直到 `has_more = false`
+3. **再切换到下一个 slice**：当前 slice 翻完后，如果用户还要"更老的"，用 notice 里列的 slice 2 的 `--opened-since` / `--opened-until` 值，**其他 flag（`--query`、`--doc-types`、`--page-size`、`--sort`……）保持原样，`--page-token` 不带**，重新发请求
+4. **依次递推**：slice 2 翻完后切 slice 3，以此类推
+5. 用户只对最近一段感兴趣时，跳过第 3 步及以后 —— 避免无意义的 API 调用
+
+> `--page-token` 只在单 slice 上下文内有效；切 slice 时不要把上一个 slice 的 `page_token` 带过去。
+
+### 注意事项
+
+- `--sort` 在**单 slice 内部**是正确的。跨 slice 的全局 sort（例如"过去一年我打开过的，按 edit_time desc 排"）不被 CLI 保证，需要 agent 自行拉完多个 slice 后在客户端 re-sort 再呈现
+- 裁剪只改 request 发出去的 `open_time` 范围，`--query` / 其他 filter 不动
+- 最后一个（最老的）slice 常常不足 90 天，这是正常的截断

package/skills/lark-drive/references/lark-drive-secure-label.md

@@ -0,0 +1,52 @@
+# drive +secure-label-list / +secure-label-update（云文档密级标签）
+
+## 何时使用
+
+- `drive +secure-label-list`：查询当前用户可用的密级标签，先拿到目标 `id`。
+- `drive +secure-label-update`：把目标云文档调整为指定密级标签。
+
+这两个 shortcut 都使用用户身份（`--as user`）。修改密级前，通常先执行 `+secure-label-list` 确认可用标签 ID。
+
+## 查询可用密级标签
+
+```bash
+lark-cli drive +secure-label-list --page-size 10 --lang zh
+```
+
+可选参数：
+
+| 参数 | 说明 |
+|------|------|
+| `--page-size` | 分页大小，范围 `1..10`，默认 `10` |
+| `--page-token` | 上一页响应里的 `page_token` |
+| `--lang` | 标签语言：`zh`、`en`、`ja` |
+
+底层接口：`GET /open-apis/drive/v2/my_secure_labels`。
+
+## 修改文档密级
+
+```bash
+lark-cli drive +secure-label-update \
+  --token "https://example.feishu.cn/docx/doxcnxxxx" \
+  --label-id "7217780879644737539"
+```
+
+参数：
+
+| 参数 | 说明 |
+|------|------|
+| `--token` | 目标文档 URL 或 bare token；URL 可自动推断 `--type` |
+| `--type` | bare token 必填；URL 输入时可省略。可选：`doc`、`docx`、`sheet`、`file`、`bitable`、`mindnote`、`slides` |
+| `--label-id` | 要设置的密级标签 ID |
+
+底层接口：`PATCH /open-apis/drive/v2/files/:file_token/secure_label`，query 参数 `type`，请求体 `{ "id": "<label-id>" }`。
+
+## 错误处理
+
+CLI 不会在 shortcut 中为密级错误码追加专用 hint；agent 必须根据返回的 `error.code` 做以下引导。
+
+| 错误码 | 含义 | 引导 |
+|--------|------|------|
+| `1063013` | 密级降级需要审批 | 提示用户打开目标文档，在文档界面完成密级降级审批后重试；如果用户传入的是文档 URL，必须把该 URL 一并给用户作为操作入口 |
+
+遇到 `1063013` 时，不要继续重试 API，也不要提示补 scope；这是文档侧审批流程要求，需要用户到文档里操作。