first commit

2026-09-02 11:44:52 +08:00
commit 0c8fa2653e
309 changed files with 57278 additions and 0 deletions
@@ -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`。
@@ -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 和策略；不要在确认后静默改变方向或冲突策略。
@@ -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。
@@ -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 完整复制后逐表删记录或自建测试文件夹。