first commit

.agents/skills/dingtalk-drive/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: dingtalk-drive
+description: 钉钉文件管理（存储层，覆盖钉盘与文档空间）。Use when 用户说 钉盘/文档空间/我的文档中的普通文件或文件夹、查找/上传/下载/复制/移动/重命名/删除/回收站/权限/评论/元信息，或本地与钉盘文件夹比较、拉取、推送、双向同步；也承接在线文档节点的存储管理。文档正文编辑与导出走 dingtalk-doc；明确的知识库空间及空间内节点组织走 dingtalk-wiki。命令前缀：dws drive。
+metadata:
+  cli_version: ">=0.2.14"
+  category: product
+  requires:
+    bins:
+      - dws
+---
+
+# 钉盘
+
+<!-- DWS_RUNTIME_CONTRACT_START -->
+## 最小 DWS 执行契约
+
+- 只通过 `dws` CLI 操作钉钉；结构化读取使用 `--format json`，按真实返回判断结果。
+- 已知命令直接执行。只有 leaf 参数或安全语义不确定时读取精确 Schema，只有 Cobra flag 不确定时读取精确 leaf Help；不要加载产品级 Catalog 代替选路。
+- 不猜命令、flag、字段、ID、账号或时间。后续 ID 必须来自真实返回；零命中、多候选或类型不明时停止并消歧。
+- 解析目标、读取上下文和最终执行必须使用同一 profile；不得跨组织复用 userId、openDingTalkId 或 openConversationId。多账号组织只使用明确的 `isOrgCurrent=true` 默认账号；没有默认账号时要求用户指定，禁止选择第一项、最近登录或最近使用账号。
+- 不输出或记录 token、refresh token、appSecret、webhook token 等凭据；宿主已注入认证时不要索要凭据。
+- 写操作必须符合用户明确意图。是否需要确认以最终 Runtime gate 和 Schema 为准；需要确认时先说明对象、动作与影响，再追加 `--yes`。
+- 写后按任务结果契约验证；不能仅凭退出码宣称成功。部分结果、未知投递状态和失败项必须如实保留。
+- 时间戳面向用户展示时转换为带时区的可读时间；默认使用当前会话时区，必要时同时保留原值。
+- 遇到认证、权限、profile、confirmation 或未知错误时，只加载 `dingtalk-shared` 中对应 reference；不要连续猜测替代命令。
+<!-- DWS_RUNTIME_CONTRACT_END -->
+
+<!-- VISIBLE_SHORTCUTS_START -->
+## Shortcut 发现（按需）
+
+`drive` 当前有 28 条公开 shortcut，完整清单保留在 Runtime Catalog 与 Schema，不在高频产品根 Skill 中重复展开。已知意图按下方路由。
+
+仅当现有路由和 reference 都无法定位低频能力时，才执行 `dws shortcut list --service drive --format json` 做最后回退；不要为已知高频意图加载完整 Shortcut Catalog 或产品级 Schema。
+<!-- VISIBLE_SHORTCUTS_END -->
+
+## Golden Route
+
+| 用户意图 | 唯一推荐入口 | 关键边界 |
+|---|---|---|
+| 全局按名称或关键词找文件 | `dws drive +search --query <关键词>` | 多候选停止；Drive 搜索没有 Doc 的 `--page-all`，按真实 nextCursor 翻页；在线文档正文搜索走 `doc +search` |
+| 浏览根目录或已知文件夹 | `dws drive +list [--folder <dentryUuid>]` | 默认一页，处理 nextCursor |
+| 发现钉盘企业空间或“我的文件”空间 | `dws wiki space list --type <orgSpace\|mySpace> --format json` | Drive 只读前置；orgSpace 按 nextToken 续页，取 spaceId/rootFolderId 后回到 Drive |
+| 查看最近访问/编辑 | `dws drive +recent [--operate-type 1] --limit <N>` | 1=最近编辑；默认最近访问 |
+| 查看节点类型和元数据 | `dws drive +inspect --node <dentryUuid>` | 按需加 stats/publish/cover，不为普通列表强制调用 |
+| 下载普通文件 | `dws drive +download --node <dentryUuid> --output <相对路径>` | 当前 shortcut 接受 ID；在线文档用 `doc +export` |
+| 上传新文件或覆盖普通文件 | `dws drive +upload --file <相对路径>` | 新建可加 folder；覆盖改加 node，二者互斥 |
+| 管理普通文件全局评论 | `dws drive comment list-v2/create-v2/reply/update/delete/batch-query/list-replies/resolve/restore/react-reply` | 复用 Doc/Sheet 新评论链路；旧 `list/create` 已 deprecated；固定全文 `global`，不支持划词、单元格或 mention |
+| 创建文件夹 | `dws drive +create-folder --name <名称> [--folder <ID>]` | Shortcut 已提交并读回 |
+| 复制在线文档节点 | `dws drive +copy --node <ID> [--folder <目标ID>]` | 普通钉盘文件会被拒绝；Base 结构复制走 AITable `+base-copy --base-id <ID> --target-folder-id <真实ID> --only-struct` |
+| 移动节点 | `dws drive +move --node <ID> --folder <目标ID>` | 破坏性变更，按 Runtime confirmation |
+| 重命名节点 | `dws drive +rename --node <ID> --name <新名称>` | 写后检查最终名称 |
+| 比较本地与钉盘文件夹 | `dws drive status --local-folder <绝对路径> --remote-folder <folderId>` | 只读；默认精确 MD5，不先拉取或推送 |
+| 钉盘文件夹拉到本地 | `dws drive pull --local-folder <绝对路径> --remote-folder <folderId> --if-exists skip` | 安全默认不覆盖；先以相同参数 `--dry-run`，再按确认执行 |
+| 本地文件夹推到钉盘 | `dws drive push --local-folder <绝对路径> --remote-folder <folderId> --if-exists skip` | 安全默认不覆盖；先 dry-run；不会删除远端多余文件 |
+| 双向补齐文件夹 | `dws drive sync --local-folder <绝对路径> --remote-folder <folderId> --on-conflict skip` | 先 dry-run；冲突策略必须显式保留 |
+
+### 低频入口
+
+- 删除已确认节点：`dws drive +delete --node <dentryUuid>`；恢复：`+recycle-list/+recycle-restore`；版本：`+version-history/+version-get/+version-download/+version-revert`。
+- 收藏：`+star-*`；公开状态：`+publish-get/+publish-unset`（`+publish-set` 不进入 Agent 路由）；统计/封面用 `+inspect`；快捷方式用 `+create-shortcut`。
+- 目录树只用有界 `+list` 逐层遍历。
+
+兼容别名不选路：`+info`→`+inspect`，`+find-file`→`+search`，`+search-docs`→`doc +search`。
+
+## 当前最短路径
+
+- 已知 dentryUuid：直接执行 inspect/download/list/move/rename，禁止先 search；仅确认是受支持的在线文档节点后才执行 copy。
+- 目标 Drive 空间未知：先明确企业空间 `orgSpace` 或“我的文件”`mySpace`，用 `dws wiki space list --type <类型> --format json` 发现空间；`orgSpace` 在 `nextToken` 非空时以 `--cursor <nextToken>` 续页，`mySpace` 固定单条且不分页。按后续命令取真实 spaceId 或 rootFolderId 后立即回到 Drive；已知这些 ID 时不做空间发现。
+- 只有名称：`+search` → 唯一候选的 nodeId → 目标命令；不得自动选择第一项。
+- 只有文件夹层级：从最近的已知 folder ID 开始 `+list`，不要从根目录无界递归。
+- 上传新文件：单条 `+upload`；不要退回 upload-info + 手写 HTTP + commit。
+- 导出后上传：`doc +export` 首次就指定最终本地文件名，直接复用回执 `localPath`，首次正式 `drive +upload` 带已获授权的 `--yes`；禁止上传后再 rename。
+- copy/move/rename/create-folder 已内置写后读取时，不再由 Agent重复执行 `+inspect`。
+- 已知 nodeId 的重命名直接 `+rename`，不先 Catalog、Help 或 search；ALIDOC 的逻辑标题由 shortcut 内部文档读回验证。
+- 文件夹方向已明确时直接 `status/pull/push/sync`，不先 status；写操作先用完全相同参数 dry-run，再正式执行。
+- 搜索结果 `type=able` 后按业务动词重路由：结构复制/删除/Base 内操作走 AITable。结构复制按当前 leaf 提供源 Base ID 和真实 `--target-folder-id`；缺少目标 ID 时停止，不猜根 ID或发明 `--target-root`。
+- `+inspect/+download/+list` 只保证 dentryUuid；只有 URL 时先用 `dws drive info --node <URL> --format json` 解析并核对 nodeId。
+
+最短路径不省略类型检查、确认、传输验证或写后校验。
+
+## 关键结果语义
+
+- `+list/+search/+recent` 检查集合、hasMore 和 nextCursor；缺少集合不能当空结果，多候选禁止默认第一项。
+- `+download` 验证相对路径存在且 sizeBytes > 0；`+upload` 检查最终 nodeId、名称、类型和大小。只有源端与结果都提供可比哈希时才核对 checksum；缺失时保留现有证据，不虚构端到端校验和。
+- copy/move/rename/create-folder 检查 `ok/outcome` 和读回；`partial_success` 不是完成。
+- status 检查分类集合；pull/push/sync 检查 summary 和逐项结果，failed/unknown 必须保留。
+- 分页未结束时返回 continuation；目录树或大列表必须有最大深度、页数和条目数。
+- 未知写入效果先 inspect/list 回读，不盲目重放写操作。
+
+## 参数与安全边界
+
+- `--node`、`--folder` 使用 dentryUuid/fileId，不使用数字型 dentryId；回收站 restore 使用 recycleItemId。
+- `+list --limit` 最大 50，`+search --limit` 最大 30；超过时分页，不以非法参数反复试错。
+- 写操作只按精确 leaf Runtime 判定确认；已明确授权具体对象、动作与影响时，首次正式执行直接带 `--yes`，否则先确认。预览不带，参数变化重新确认；禁止用缺少 `--yes` 的失败探测。
+- 普通文件覆盖前确认真实类型和原名称；adoc/axls/able 不按普通文件覆盖。
+- 单文件 Shortcut 的本地输入输出使用 cwd 相对路径且禁止 `..`；文件夹 `status/pull/push/sync` 按 leaf 契约使用绝对 `--local-folder`。
+- 文件夹同步默认精确 MD5；仅在用户接受时间戳近似时用 `--quick`，且不会删除任一侧多余文件。
+- 参数不确定时只查一次精确 leaf Schema；禁止产品级 Schema。
+
+## 按需加载
+
+Golden Route 参数足够时禁止读取 reference。其余最多读取一个精确 reference：
+
+| 触发条件 | Reference |
+|---|---|
+| URL、文件类型或跨产品边界 | [intent-guide](references/intent-guide.md) |
+| 文件夹比较、拉取、推送或双向同步 | [folder-sync](references/folder-sync.md) |
+| 低频权限、版本、回收站、公开状态 | [drive reference](references/drive.md) 的对应章节 |
+| 文档查询、导入和模板保形流程 | [lite-recipes](references/lite-recipes.md) |
+
+## 错误最短路径
+
+1. 零/多候选、类型不明或分页不完整：停止写入，返回候选或 continuation。
+2. `unknown flag`：只查一次当前 leaf Help；`unknown command`：只查一次 Drive shortcut 清单。
+3. 普通下载遇到在线文档类型：切 `doc +export`，不重复尝试 Drive download。
+4. 传输中断：保留本地临时状态或 checkpoint；先判断能否续传。
+5. 写入效果未知：按 nodeId 回读；无法证明时报告 unknown。
+6. 普通文件 `+copy` 被拒绝时不要重试或伪装成功；独立副本改走经用户授权的 download→upload。AITable 结构复制缺少或无法验证目标文件夹时停止，不猜 ID或创建测试文件夹。
+
+## 跨产品边界
+
+- 普通文件/文件夹及在线文档节点的存储管理 → Drive；把文件作为附件放进某篇文档正文走 Doc `+media-insert`，其他正文/内容分别走 Doc、Sheet、AITable。
+- able 外层移动/重命名走 Drive；结构复制、Base 删除（`+base-delete`）及 Base 内操作走 AITable。
+- 明确知识库 workspace 层级 → Wiki；泛称“文档空间/我的文档”仍走 Drive。
+- 钉盘存储空间发现例外地复用 managed `dws wiki space list --type orgSpace|mySpace`；只取真实 spaceId/rootFolderId 后回到 Drive。spaceId 用于空间参数，rootFolderId 才可作为空间根目录 folder；`orgWikiSpace/myWikiSpace` 返回 workspaceId，不能混入 Drive 参数。
+- Word/Markdown/Text 转在线文档用 `doc +import`；Drive upload 只保留原文件。

.agents/skills/dingtalk-drive/references/drive.md

@@ -0,0 +1,114 @@
+# Drive 低频能力参考
+
+仅在根 Skill 的 Golden Route 不足时读取本文件的一个相关章节。高频搜索、列表、检查、单文件传输和文件夹同步直接按根 Skill 执行。
+
+## 身份与目标位置
+
+- `--node`、`--folder`、`--remote-folder` 使用 dentryUuid/fileId；数字 dentryId 不能替代。
+- 回收站恢复使用 `recycleItemId`，不能复用删除前的 nodeId。
+- URL 类型不明时只执行一次 `dws drive info --node <URL> --format json`，按真实 nodeId/nodeType 分流。
+- 普通文件夹目标使用 `--folder`；明确知识库 workspace 才使用 `--workspace`。零命中、多候选或类型不明时停止。
+
+## Runtime 确认与首次执行
+
+- 先解析唯一目标，再以精确 leaf Schema 和 Runtime gate 判断是否需要确认；不要通过一次缺少 `--yes` 的失败调用探测确认要求。
+- Runtime 要求确认且当前请求已明确授权具体节点/文件夹、动作与影响时，首次正式远端写调用直接追加 `--yes`。诸如“整理一下”“处理这些文件”不能视为对删除、覆盖、移动或公开状态变更的精确授权。
+- Runtime 不要求确认时不添加 `--yes`。对象、范围或影响不完整时先询问；确认后必须保持同一 profile、目标、动作、范围和关键参数，任一项变化都要重新确认。
+- `--dry-run`、差异预览和只读检查不加 `--yes`；预览结果符合授权范围后，正式执行才追加。收到 `confirmation_required` 仅表示尚未通过预执行门禁，不代表业务写入成功，也不能据此盲目重放。
+
+## 高级目录列表
+
+普通浏览优先 `+list`。需要递归、名称模式、节点类型或修改时间过滤时使用 managed leaf：
+
+```bash
+dws drive list --folder <dentryUuid> --depth 2 --pattern "*周报*" --format json
+dws drive list --folder <dentryUuid> --type file --start 7d --format json
+```
+
+- `--depth` 最大 5；递归总量上限以结果中的 `truncated/errors` 为准。
+- `--type file|folder` 是节点类型；`search --file-types` 是内容类型，二者不同。
+- `--start/--end` 接受 `24h/7d/2w`、日期或 RFC3339，按修改时间过滤。
+- 过滤模式是客户端有界扫描；`truncated=true` 不能声称全量。需要关键词检索时改用 `+search`。
+- `--latest` 遇到截断或目录读取失败会拒绝给出不完整 Top-N，按错误中的目录和恢复命令缩小范围。
+
+## 回收站
+
+```bash
+dws drive +delete --node <dentryUuid>
+dws drive +recycle-list --limit 20
+dws drive +recycle-restore --id <recycleItemId>
+```
+
+删除前核对名称、类型和 ID；恢复从列表真实返回取 `id`。恢复后使用返回的新 nodeId，不沿用旧 ID。
+
+## 普通文件历史版本
+
+| 意图 | 入口 | 完成证据 |
+|---|---|---|
+| 列版本 | `+version-history` | 版本集合与分页字段 |
+| 查看版本 | `+version-get` | 请求的 version |
+| 下载版本 | `+version-download` | 相对路径存在且 sizeBytes > 0 |
+| 回滚版本 | `+version-revert` | Runtime 确认后读回最新版本 |
+
+这些入口只用于普通文件。adoc 版本走 Doc，axls 版本走 Sheet。
+
+## 收藏、统计与封面
+
+- 收藏列表：`+star-list`；收藏/取消：`+star-add` / `+star-remove`。
+- 节点统计和封面优先并入 `+inspect --include-stats` / `--include-cover`；只取单项才用 `+stats` / `+cover`。
+- 收藏是个人状态，不代表共享或权限变化。
+
+## 普通文件评论
+
+普通 PDF、DOCX、XLSX 等本地文件使用 `dws drive comment`，复用 Doc/Sheet 的新评论服务链路。当前固定为文件级全文评论 `topicId=global`，不支持划词、单元格、页码、anchor 或 mention。
+
+旧 `drive comment list/create` 保留旧评论服务的行为和输出，仅作 deprecated 兼容入口。Agent 必须使用下面的 `list-v2/create-v2` 进入新评论体系。
+
+```bash
+dws drive comment list-v2 --node <dentryUuid> --format json
+dws drive comment create-v2 --node <dentryUuid> --content "请补充结论"
+dws drive comment list-replies --node <dentryUuid> --comment-key <commentKey> --format json
+```
+
+完整生命周期包括 `list-v2/create-v2/reply/update/delete/batch-query/list-replies/resolve/restore/react-reply`。分页游标必须原样回传；`list-v2` 每页上限为 50，超过上限直接报错；写操作按 Runtime confirmation 执行，后续操作的 `commentKey` 必须来自真实返回。
+
+## 公开状态
+
+```bash
+dws drive +publish-get --node <dentryUuid>
+dws drive +publish-unset --node <dentryUuid>
+```
+
+`+publish-get` 只读；`+publish-unset` 为高风险写。Runtime 虽注册了 `+publish-set`，但当前普通文件和在线文档都没有经过验证的开启公开闭环，因此根 Skill 明确不将它开放给 Agent。用户要求开启公开时，说明当前 Agent 路由不支持并停止；不要查询或执行 `+publish-set`、`drive publish set` 或其他替代写入口。只有补齐受支持节点上的真实 set→get→unset 闭环证据并更新 Agent 路由后，才重新开放该能力。
+
+## 权限
+
+| 意图 | managed leaf |
+|---|---|
+| 查看成员权限 | `drive permission list` |
+| 查询节点权限设置（权限模式/分享范围/策略） | `permission get-setting` |
+| 添加、修改、移除成员 | `permission add` / `update` / `remove` |
+| 转移所有者 | `permission transfer-owner` |
+| 查看可申请权限和审批人 | `permission apply-info` |
+| 发起权限申请 | `permission apply` |
+
+只在意图命中时读取一个精确 leaf Schema。成员变更、转移所有者、发起申请和公开状态变更必须明确节点、用户、角色与影响范围。转移所有者时，在构造最终命令前必须让用户分别明确决定 `--reserve-role <MANAGER|EDITOR|DOWNLOADER|READER|NONE>` 和 `--recursive=<true|false>`；Agent 不得根据默认值、对象类型或便捷性自行选择任一项。两项决策与目标、新所有者均明确后，才按 Runtime confirmation 构造首次正式调用。
+
+`permission get-setting` 返回 `permissionMode`（INHERITED/INDEPENDENT，未知时为 null）、`shareScope`（可见范围与链接分享，密码明文不返回；`partnerIncluded`、`defaultRole` 等仅 ORGANIZATION 有意义，`linkShare` 仅开启链接分享时返回）和 `policies[]`（code/name/description/value/disabledValues/allowedValues；name/description 为中文名与值语义说明，随行必带；未下发的策略不返回，`node_spread_scope` 仅文件夹）。`disabledValues` 为不可设置取值列表（恒返回，无被禁档位时为空数组），每项含 `value`（被禁档位取值，与 value 同一值域）与 `reason`（服务端按请求语言返回的禁用原因文案，仅供展示理解，可为 null），与 allowedValues 互斥；示例：`{"value": "READER_AND_ABOVE", "reason": "企业安全策略要求不可低于可下载角色"}`。`value` 按策略分型：开关型为 ENABLED/DISABLED；member_invite、comment 为 READER_AND_ABOVE/DOWNLOADER_AND_ABOVE/EDITOR_AND_ABOVE/MANAGER_AND_ABOVE；node_spread、online_content_copy 为 DOWNLOADER_AND_ABOVE/EDITOR_AND_ABOVE/MANAGER_AND_ABOVE 或 NOBODY；node_spread_scope 为 ALL_NODES（限制对所有文档生效）/ PREVIEWABLE_ONLY（仅对可预览的文档生效）。NOBODY=该操作对所有人禁止；XXX_AND_ABOVE=不低于该角色才允许。name/description 示例（文案与产品权限设置页一致）：external_share「添加企业外协作者」：是否允许添加企业外的人为协作者（ENABLED=允许，DISABLED=禁止）；node_spread「谁可以下载、创建副本、打印」：允许哪些角色及以上的用户下载、创建副本、打印；NOBODY=所有人禁止下载、创建副本、打印；node_move_forbidden「禁止移动」：是否禁止移动到其他知识库或团队共享文件夹（ENABLED=禁止移动，DISABLED=允许移动）。
+
+发起权限申请先只读执行 `permission apply-info`。正式 `permission apply` 会通知审批人；调用前必须向用户逐项回显并确认资源、申请角色、审批人和理由。Agent 不得默认选择第一位审批人、最高/最低角色或代写申请理由；用户未明确同意完整申请内容时停在确认环节。
+
+## 快捷方式节点
+
+`+create-shortcut --node <源ID> [--folder <目标ID>|--workspace <知识库ID>]` 创建链接。在线文档节点需要保留版式的独立副本时使用 `+copy`；普通钉盘文件的独立副本必须经用户授权后走 download→upload，因为当前 `+copy` 会拒绝普通文件。源/目标类型不兼容时停止，不把快捷方式当普通文件继续覆盖。
+
+## 错误恢复
+
+1. `unknown flag` 只查当前 leaf Help；`unknown command` 只查一次 Drive Shortcut 清单。
+2. 分页、递归或过滤未完成时保留 cursor/truncated/errors，不包装成全量成功。
+3. 写入超时或响应丢失先按 nodeId、名称、路径和大小回读，不能盲目重放。
+4. 在线文档误入普通下载/覆盖时切 Doc、Sheet 或 AITable；不要用 Drive 重试改变内容。
+
+## 辅助脚本
+
+- [drive_tree_list.py](../scripts/drive_tree_list.py)：递归列出钉盘目录树；普通浏览仍优先使用 `dws drive +list`。

.agents/skills/dingtalk-drive/references/folder-sync.md

@@ -0,0 +1,40 @@
+# Drive 文件夹比较与同步
+
+仅用于本地目录与钉盘普通文件夹之间的递归文件级比较或镜像。单个文件使用根 Skill 的 `+download/+upload`。
+
+## 选择入口
+
+| 目标 | 唯一入口 |
+|---|---|
+| 只比较，不写任何一侧 | `dws drive status` |
+| 钉盘 → 本地 | `dws drive pull` |
+| 本地 → 钉盘 | `dws drive push` |
+| 两侧互相补齐 | `dws drive sync` |
+
+四个入口都要求 `--local-folder <绝对路径> --remote-folder <dentryUuid>`；`--space-id` 可选。动作已经明确时直接进入对应命令，不先重复执行 status。
+
+## 安全流程
+
+`status` 只读，可直接执行。`pull/push/sync` 会写本地或钉盘，先使用相同参数 `--dry-run` 查看计划；确认目标、方向和冲突策略后，再按 Runtime confirmation 执行。
+
+```bash
+dws drive status --local-folder /abs/local --remote-folder <folderId> --format json
+dws drive pull --local-folder /abs/local --remote-folder <folderId> --if-exists skip --dry-run --format json
+dws drive push --local-folder /abs/local --remote-folder <folderId> --if-exists skip --dry-run --format json
+dws drive sync --local-folder /abs/local --remote-folder <folderId> --on-conflict skip --dry-run --format json
+```
+
+## 策略
+
+- pull/push `--if-exists`: `skip` 是不覆盖的安全默认；`smart` 按修改时间做增量；`overwrite` 以来源侧覆盖目标侧。用户未明确选择覆盖策略时，Agent 必须保留 `skip`，不得代选 `smart/overwrite`；只有回显 dry-run 的覆盖项并得到明确授权后，才使用后两者。
+- sync `--on-conflict`: `skip` 默认保留两侧；`remote-wins` 覆盖本地；`local-wins` 覆盖远端；`keep-both` 先改名本地再拉远端；`ask` 需要交互。
+- 默认 exact 通过 MD5 比较；远端缺少可靠 MD5 时进入 `unknown` 并跳过。只有用户接受时间戳近似时才加 `--quick`。
+- 这些命令只处理普通 `type=file` 和目录；在线文档、快捷方式不会按普通二进制同步。
+- 文件级镜像只新增或覆盖，不删除任一侧多余文件。
+
+## 结果与恢复
+
+- status 检查 `new_local/new_remote/modified/unchanged/unknown`。
+- pull/push/sync 检查 summary 与逐条 items；任何 failed/unknown 必须保留，不把部分结果称为成功。
+- 下载先写临时文件再原子替换；失败时保留原目标。上传在提交前明确失败时直接返回。`push/sync` Runtime 遇到 `commit_upload` 超时、连接中断、空响应或畸形响应会直接返回错误，不会自动恢复，也不能据此断言未提交；Agent 必须把该项保留为 `unknown`，再用只读 list/inspect 按远端路径、名称和大小有限核对，无法证明时报告未知，不能直接重放可能已提交项。服务未同时提供源端与结果的可比哈希时，不虚构 checksum 验证。
+- dry-run 与正式执行必须使用同一 local-folder、remote-folder、space-id 和策略；不要在确认后静默改变方向或冲突策略。

.agents/skills/dingtalk-drive/references/intent-guide.md

@@ -0,0 +1,22 @@
+# Drive 局部意图消歧
+
+| 用户表达 | 应用 | 不应用 | 理由 |
+|---|---|---|---|
+| 全局找文件、最近文件、浏览已知“我的文件”/文档空间目录 | Drive | Wiki node | 未限定知识库 workspace，属于普通存储域 |
+| 列出/发现钉盘企业空间或“我的文件”空间 | managed `dws wiki space list --type orgSpace|mySpace` 发现 spaceId/rootFolderId 后回 Drive | `wiki +space-list` 的 orgWikiSpace/myWikiSpace | Drive 存储空间前置；spaceId、rootFolderId 与知识库 workspaceId 不可互换 |
+| 明确知识库内列节点、移动节点、搜索节点 | Wiki | Drive | workspace 内层级由 Wiki 管理 |
+| 普通文件或文件夹移动、重命名、删除 | Drive | Doc | 节点存储动作不修改正文 |
+| 普通文件创建独立副本 | Drive download→upload | Drive `+copy` | 当前 `+copy` 会拒绝普通钉盘文件，避免把 `.dlink` 快捷方式伪装成副本 |
+| adoc 正文读取、编辑或导出 | Doc | Drive download | Drive 只管理节点；在线文档需要格式转换 |
+| 本地 xlsx/xls/csv 节点下载后分析 | Drive + 本地工具 | Sheet range read | 上传的普通文件不是 axls 在线表格 |
+| axls 在线表格导出为 xlsx | Sheet export | Drive download | export 执行格式转换 |
+| able 记录、字段、视图 | AITable | Drive | 表内业务数据不属于存储节点动作 |
+| able 仅复制结构、删除 Base | AITable `+base-copy --base-id <ID> --target-folder-id <真实ID> --only-struct` / `+base-delete --base-id <ID>` | Drive copy/delete | 当前 main 要求真实目标文件夹 ID；缺少时停止，禁止发明 `--target-root`、完整复制后逐表删数据或用 Drive 猜根 ID |
+| Base 内 Table/Dashboard/Section 节点操作 | AITable `+table-*` / `+section-*` | Drive | nsheet 节点不是独立 Drive dentry |
+| 整个 Base 移到普通文件夹、外层存储重命名 | Drive | AITable 表内命令 | 这是 Base 外层存储位置/名称动作 |
+| PDF、DOCX、XLSX 等普通文件的评论查询或生命周期操作 | Drive `comment list-v2/create-v2/reply/update/delete/batch-query/list-replies/resolve/restore/react-reply` | Doc/Sheet comment | 默认进入新评论体系；普通文件固定使用文件级 global topic，不支持划词或单元格锚点；仅在用户明确要求旧评论兼容行为时使用 deprecated 的 `list/create` |
+| Word/Markdown/Text 转在线文档 | Doc `+import` | Drive upload | import 会创建在线文档；upload 只保留原文件 |
+| “上传文件”但未指定目标 | Drive `+upload` | — | 默认按普通文件上传到钉盘 |
+| “照这个文档做一份同样格式的” | Drive `+copy` + `+rename`，再由 Doc 局部更新副本 | 读取后重建 | 先复制可保留在线文档版式 |
+
+URL 本身不能证明产品类型。当前 Drive shortcut 的公开参数主要接受 ID；只有 URL 时先用 `dws drive info --node <URL> --format json` 预检并取真实 nodeId/nodeType。

.agents/skills/dingtalk-drive/references/lite-recipes.md

@@ -0,0 +1,39 @@
+# Drive 精简流程
+
+只在跨 Drive/Doc/Wiki 的组合任务命中时读取。单一 Drive 操作直接按根 Skill 执行。
+
+## 查找并读取在线文档
+
+1. 未指定空间：`dws drive +search --query "<关键词>" --format json`。
+2. 明确知识库：用 Wiki 在指定 workspace 搜索。
+3. 唯一确定 nodeId 后切 Doc `+fetch` 读取正文；大文档按返回 continuation 继续。
+
+Drive search 找的是节点；正文全文检索优先用 Doc `+search`。
+
+## 列出目录中的文档
+
+- 普通钉盘目录：`dws drive +list --folder <dentryUuid> --format json`
+- 知识库目录：切 Wiki，用 workspace + parent node 定位
+
+处理 nextCursor，并设置最大页数/条目数。不要从根目录无界递归。
+
+## 导入为在线文档
+
+```bash
+dws doc +import --file ./report.docx --format json
+```
+
+- `.doc/.docx/.md/.txt` 通常导入为在线文字文档；`.xls/.xlsx` 导入为在线表格，最终类型以真实返回为准。
+- 目标是“保留原文件”时使用 Drive `+upload`，不是 Doc import。
+- 用户给目标文件夹 URL 时，若命令契约不保证 URL 直传，先用 `dws drive info --node <URL>` 验证它是 folder，并复用当前节点 nodeId；不要误用其父 folderId。
+- 导入超时或返回 task/checkpoint 时按 Doc 返回的 continuation 恢复，不重复创建。
+
+## 模板保形生成
+
+1. `dws drive +copy --node <源nodeId> --folder <目标folderId>` 保形复制。
+2. 用返回的新 nodeId 执行 `dws drive +rename`。
+3. 切 Doc，只对副本执行局部正文更新。
+
+不要用“读取 Markdown → 新建文档”替代复制；该路径会丢失在线文档的版式属性。
+
+本剧本只适用于 `+copy` 支持的在线文档节点（如 adoc）；普通钉盘文件创建独立副本应改走经用户授权的 download→upload。若源节点是 `able` 且用户要“只复制结构”，切 AITable，按当前 leaf 执行 `+base-copy --base-id <ID> --target-folder-id <真实ID> --only-struct`。只有根目录意图但没有真实目标文件夹 ID 时停止；禁止发明 `--target-root`、用 Drive 完整复制后逐表删记录或自建测试文件夹。