dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-doc/references/doc/style/doc-update-workflow.md

@@ -0,0 +1,316 @@
+# 钉钉文档改写流程
+
+本文只处理已有文档的结构和排版策略。普通执行入口固定为 `+fetch`、`+update` 或 `+checkpoint-update`；这些 shortcut 统一确认、写入与验证。原子 `doc read/update/block` 只保留给 shortcut 未公开参数的 JSONML 专家路径，使用前必须读取精确 leaf Schema。
+
+## 适用边界
+
+进入本文前，必须已经确认用户要改写的是已有钉钉文档 (`adoc`)。如果用户要新建、要操作表格 / AI 表格 / 文件 / 知识库空间 / 发消息，不要套用本文。
+
+本文覆盖：
+
+- 已有文档的局部改写、润色、章节补充
+- 段落 ↔ 列表 ↔ 表格 的形态转换
+- 块级精修（callout、分栏、附件插入）
+- overwrite 整篇改写的风险提示与执行
+- JSONML 无损结构改写的入口
+
+本文不覆盖：
+
+- 新建文档（见 [doc-create-workflow.md](./doc-create-workflow.md)）
+- 知识库空间管理
+- 文档权限、消息分发、待办分派
+
+---
+
+## 一、核心原则
+
+### 1.1 精准手术优于全量覆盖
+
+**默认走精准手术**——只改用户指定的章节或 block，不动其他内容。具体路径见 §3 速查表。
+
+### 1.2 保真约束
+
+改写时必须**原样保留**以下要素，**不许**替换为纯文本/姓名/链接/占位符：
+
+- `@人` 引用（用户、机器人、群）
+- `@文档` / `@群` 等卡片引用
+- 已上传的附件、图片
+- 用户原话引用块
+- 表格表头（除非语义错误且用户确认）
+
+JSONML 模式下这些元素的节点结构见 [doc-jsonml-schema.md](../format/doc-jsonml-schema.md)。
+
+### 1.3 编辑形态优先级
+
+**改写已有文档优先 JSONML，markdown / element 只在 JSONML 不适用时兜底**：
+
+| 优先级 | 形态 | 适用 |
+|--------|------|------|
+| ① 首选 | `--content-format jsonml` | 保真度最高；callout / 分栏 / 表格 / @人 / 附件 / 颜色 / 嵌套结构都能 1:1 round-trip；写入端有 validator 兜底（§4.4） |
+| ② 次选 | `--content-format element`（JSON，老接口） | JSONML 不支持某个块字段时；或快速插入 callout / 分栏不想构造 JSONML 时；不保真改写正文 |
+| ③ 兜底 | markdown（不带 `--content-format` 即默认）| 纯文本追加、整篇重排骨架；callout / 分栏 / 颜色 / 部分属性会被 markdown 还原过程丢失 |
+
+实操判断：
+
+- 用户给已有 nodeId 要「改一段、改属性、加 callout、动结构」——走 §4.4 JSONML 路径
+- 用户要「在末尾追加一节纯文本 / 整篇按新骨架重写」——走 §4.2 / §4.5 markdown 路径
+- 同一次任务里两类需求都有——分别走对应路径，**不要**为了省事全部 markdown overwrite
+
+### 1.4 写入风险提示
+
+`doc update` 在以下场景可能产生**静默失败**（返回 success=true 但实际写入不完整）：
+
+- **overwrite 降级为 append**：大文档 overwrite 被后端静默降级，导致旧内容未清除、新内容追加在末尾
+- **分块 append 内容截断**：超长文档分片写入时部分片段丢失或顺序错乱
+- **编码/通道问题**：特殊终端下 UTF-8 内容传输乱码
+
+因此写入必须通过带确认与验证的 shortcut。`+update/+checkpoint-update` 返回的验证结果是主证据；禁止无条件追加一次原子 `doc read`，只有 partial/unknown 或需要定点结构检查时才用 `+fetch`。
+
+---
+
+## 二、读取策略
+
+改写前必须先读现有内容，但要节省上下文。按粒度选读取方式（按 §1.3 优先级排序，**优先 JSONML**）：
+
+| 用户需求 | 读取方式 | 定位方法 |
+|----------|----------|----------|
+| 单块精修（首选）| `doc block list --node <id> --content-format jsonml` → 拿 uuid → `doc block list --node <id> --content-format jsonml --block-id <uuid>` 读子树 | 节点结构见 [doc-jsonml-schema.md](../format/doc-jsonml-schema.md) |
+| 多处保真改写 / 改 root sectPr | `+fetch --node <id> --detail full` | 解析 JSONML；担心并发覆盖时记下 revision |
+| 整篇按新骨架重写（纯文本场景）| `+fetch --node <id>` | 直接处理 markdown 全文 |
+| 末尾追加纯文本章节 | 不必读全文，直接 §4.2 append | 必要时 `+fetch --scope section` 看末尾衔接 |
+| 老接口快速找 BLOCK_ID（无需 jsonml 时）| `doc block list --node <id>` | 默认输出 JSON；用 `grep -B2 -A2 "<关键词>"` 在 children 里定位（结构 `{"blocks":[{...,"children":[...]}]}`，jq 需 `..\|.text? // empty` 递归查文本） |
+
+读取后，把改写计划告诉用户（要改哪几节、走 JSONML 还是 markdown、改成什么形态），等用户确认后再写。
+
+---
+
+## 三、改写路径速查
+
+按用户请求形态查表，跳到对应详细节执行（**按 §1.3 优先级排序：JSONML 路径在前，markdown / element 兜底在后**）：
+
+| 用户请求 | 推荐路径 | 详细节 |
+|----------|----------|--------|
+| 改某一章 / 某一节（首选） | block list 拿 uuid → block update --content-format jsonml | §4.4 路径 B |
+| 改属性 / 改 mark / 改颜色不动文本 | block update --content-format jsonml | §4.4 路径 B |
+| 插入 callout / 分栏 / 嵌套结构（首选） | block insert --content-format jsonml --element '[...]' | §4.4 路径 B |
+| 多处保真改写 / 改 root sectPr | 整篇 JSONML overwrite（默认不带 --revision；并发敏感时再加） | §4.4 路径 A |
+| 中间插一段纯文本 | block insert（element JSON 或 jsonml） | §4.3 / §4.4 |
+| 末尾追加一节纯文本 | doc update --mode append（markdown） | §4.2 |
+| 整篇按新骨架重写 | overwrite 全文（优先 JSONML；纯文本可用 markdown） | §4.5 |
+| 段落转表格 / 表格转段落 | block update --content-format jsonml；或 markdown overwrite 单段 | §4.4 / §4.1 |
+| 插入附件 / 图片 | doc media insert | §4.3 |
+| 一次追加 >200KB 内容 | 分块 append + 用户风险确认 + 逐片记录 | §4.6 |
+| 兜底：纯文本快速替换某段 | doc update --content overwrite（markdown） | §4.1 |
+
+---
+
+## 四、改写路径详细
+
+> **首选 JSONML（§4.4）**——保真度最高且 validator 兜底；本节其余路径（markdown / element）仅在 §1.3 列出的"次选 / 兜底"场景下使用。
+
+### 4.1 段落级 overwrite（markdown 兜底路径）
+
+> 适用范围：**纯文本**改写一段或替换某节内容。若该段含 callout / 分栏 / 颜色 / @人 / 附件 / 嵌套结构，**改走 §4.4 路径 B**——markdown 还原会丢失这些元素。
+
+```bash
+dws doc +update --node <nodeId> --command overwrite --content "<新内容>" --doc-format markdown
+```
+
+或写入临时文件：
+
+```bash
+dws doc +update --node <nodeId> --command overwrite --content @./drafts/<name>-section.md --doc-format markdown
+```
+
+> ⚠️ **overwrite 须用户确认**——尤其是整篇文档 overwrite。
+
+### 4.2 追加章节（markdown）
+
+> 适用范围：在文档末尾加 X 章 / 补充纯文本段落。追加内容若含 callout / 分栏等富结构，先用本节 append 一个占位段落，再用 §4.4 路径 B 的 `block insert --content-format jsonml` 替换/精修。
+
+```bash
+dws doc +update --node <nodeId> --command append --content @./drafts/<name>-append.md --doc-format markdown
+```
+
+按 [doc-style-guideline.md](./doc-style-guideline.md) 的元素选择规则准备追加内容。
+
+### 4.3 块级精修（element JSON 次选路径）
+
+> 适用范围：JSONML 不支持某个字段时，或快速插入 callout / 分栏不想构造 JSONML 时。**默认优先 §4.4 路径 B**（block update/insert `--content-format jsonml`），本节是老接口次选路径。
+
+```bash
+# 列出所有 block，定位 BLOCK_ID
+dws doc block list --node <nodeId>
+
+# 改一个 block 的文本
+dws doc block update --node <nodeId> --block-id <BLOCK_ID> --content "替换后的内容" --content-format element
+
+# 在某个 block 后插入
+dws doc block insert --node <nodeId> --ref-block <BLOCK_ID> --where after --heading "补充说明" --level 2 --content-format element
+
+# 插入复杂块（callout / 分栏）—— element 默认按 JSON 解析
+dws doc block insert --node <nodeId> --ref-block <BLOCK_ID> --where after --content-format element \
+  --element '{"blockType":"callout","callout":{"emoji":"⚠️","bgColor":"#FDE2E0","content":[{"text":"高风险操作，先备份"}]}}'
+
+# 若改写过程已经在用 JSONML，整段精修也可走 jsonml 路径（uuid 必须 == --block-id）
+dws doc block insert --node <nodeId> --ref-block <BLOCK_ID> --where after --content-format jsonml \
+  --element '["container",{"uuid":"co_new","subType":"colorBlocks","metadata":{"bgcolor":"#FDE2E0","border":"#F5C2C7"}},["p",{"uuid":"co_new_p1"},["span",{"data-type":"text"},["span",{"data-type":"leaf"},"高风险操作，先备份"]]]]'
+```
+
+字段结构以 [doc-block.md](../doc-block.md) 为准，不要猜。callout 字段名不确定时，先用 `doc block list --node <id> --block-type callout` 抓现有 callout 实例看真实字段。整段 JSONML 形态与可复制范例见 §4.4 与 [doc-jsonml-cookbook.md](../format/doc-jsonml-cookbook.md)。
+
+### 4.4 JSONML 无损改写（**首选路径**）
+
+> 改写已有文档**默认走本节**——保真度最高，callout / 分栏 / 表格 / @人 / 附件 / 颜色 / 嵌套都能 1:1 round-trip；写入端有 validator 兜底。其他路径（§4.1/4.2/4.3/4.5 markdown）仅在 §1.3 列出的"次选 / 兜底"场景下使用。
+
+两条子路径：
+
+**路径 B：单 block JSONML 精修（最常用——只动一个 block 时的默认选择）**
+
+```bash
+# 1. 列出所有 block 拿到 uuid
+dws doc block list --node <nodeId> --content-format jsonml
+
+# 2. 读单个 block 完整子树
+dws doc block list --node <nodeId> --content-format jsonml --block-id <BLOCK_UUID>
+
+# 3. 改完后写回（uuid 必须 == --block-id）
+dws doc block update --node <nodeId> --block-id <BLOCK_UUID> --content-format jsonml \
+  --element '["p", {"uuid": "<BLOCK_UUID>"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "新内容"]]]'
+
+# 在某个 block 前/后插入新 block
+dws doc block insert --node <nodeId> --ref-block <BLOCK_UUID> --where after --content-format jsonml \
+  --element '["container", {"uuid": "co1", "subType": "colorBlocks", "metadata": {"bgcolor": "#E8F2FE", "border": "#B3D4FC"}}, ["p", {"uuid": "co1p1"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "提示内容"]]]]'
+```
+
+**路径 A：整篇 JSONML overwrite（一次改多处、改 root 级 sectPr 才用）**
+
+```bash
+# 1. 读出完整 JSONML 结构（输出含 revision，普通改写场景下不需要）
+dws doc +fetch --node <nodeId> --detail full --format json
+
+# 2. 解析 JSON，修改 jsonml 数组中的目标节点
+#    节点结构见 doc-jsonml-schema.md，可复制范例见 doc-jsonml-cookbook.md
+
+# 3. 写回工作目录内相对文件 ./drafts/doc_modified.json，格式 {"jsonml": [...]}
+
+# 4. 提交修改（默认直接覆盖，不做并发检查）
+dws doc +update --node <nodeId> --command overwrite --content @./drafts/doc_modified.json \
+  --doc-format jsonml
+```
+
+> **并发安全模式（担心被并发覆盖时使用）**：如果担心多 agent 同时改这篇文档，可以把第 1 步 read 返回的 `revision` 通过 `--revision <N>` 透传给第 4 步：服务端会做并发检查，版本不一致返回 `VersionConflict`，此时回到第 1 步重读重写即可。普通单 agent 改写场景默认不传 `--revision`。
+
+#### JSONML 写入端的 validator
+
+写入命令（`doc create/update` + `doc block insert/update`）走 **validate** 一步，不做结构修复：
+
+| 行为 | 缺省 | `--fix-jsonml` |
+|------|------|----------------|
+| JSON 语法修复（括号/逗号补全） | ✗ | ✓（打印 `[FIX]`） |
+| validator 阻断（HasErrors → 拒发） | ✓ | ✓ |
+| root 校验（仅 doc create/update） | ✓ | ✓ |
+
+报错格式（agent 友好）：
+
+```
+$[2][2]: paragraph child must be span wrapper, got raw string.
+Suggestion: ["span",{"data-type":"text"},["span",{"data-type":"leaf"},"<your text>"]]
+```
+
+设计要点：
+
+- 缺省为严格模式：不做结构修复，裸字符串、缺 uuid 等错误会被 validator 抦下。
+- `doc create/update` 要求 body 必须以 `["root", ...]` 为根节点，缺少会报错。`doc block insert/update` 不要求 root。
+- `--fix-jsonml`：启用 JSON 语法修复（修复 LLM 遗漏的括号/逗号），推荐 agent 调用。
+
+**何时不走本节、改用 markdown**：纯文本追加章节（§4.2）、整篇按全新骨架重写（§4.5，且无富结构需要保留时）、只在乎"加一段文字"且确认目标段落无 callout / 分栏 / 颜色 / @人 / 附件。其余场景默认本节。
+
+字段细节见 [doc-jsonml-schema.md](../format/doc-jsonml-schema.md)；可复制范例见 [doc-jsonml-cookbook.md](../format/doc-jsonml-cookbook.md)。
+
+### 4.5 整篇 overwrite
+
+适合「按新风格重写整篇」「按新骨架重组结构」。
+
+**形态选择（按 §1.3 优先级）**：
+
+- 若原文档含 callout / 分栏 / 颜色 / @人 / 附件 / 嵌套结构且需要保留——**走 §4.4 路径 A**（整篇 JSONML overwrite；默认不带 `--revision`，担心并发时再加）
+- 若是纯文本骨架重写、原文档没有富结构需要保真——走本节 markdown overwrite
+
+执行前必须先向用户**显式提示**：
+
+> 注意：本次操作将覆盖整篇文档内容（约 {size}）。可能存在以下风险：
+> - 大文档 overwrite 可能被后端静默降级为 append，导致**旧内容残留 + 新内容追加在末尾**
+> - markdown overwrite 会丢失原文档的 callout / 分栏 / 颜色等富结构；如需保真改走 §4.4 路径 A
+> - 写入完成后我会回读校验，发现异常会主动报告
+>
+> 是否继续？
+
+得到确认后执行（markdown 兜底路径）：
+
+```bash
+dws doc +checkpoint-update --node <nodeId> --mode overwrite --content @./drafts/<name>-full.md
+```
+
+读取 `+checkpoint-update` 的 checkpoint、write、verify 步骤；只有 partial/unknown 时才按 §6 恢复。
+
+### 4.6 超长内容追加（分块 append）
+
+当一次性追加内容 **超过 200KB** 时，必须拆分为多片 `--mode append`，并在执行第一片**之前**向用户发出截断风险提示等待确认。
+
+完整规范（提示话术模板、触发条件、失败处理）见 [04-document.md «分块 append 截断风险提示»](../../04-document.md)。
+
+update 场景下的额外约束：
+
+1. 按段落/标题边界切分，**禁止**在表格、代码块、列表内部截断
+2. 每写一片记录已写入的最后一个标题/段落标记，供 §6 回读比对
+3. 与既有内容衔接位置不能产生悬空标题或断列表
+
+---
+
+## 五、改写时的样式约束
+
+按 [doc-style-guideline.md](./doc-style-guideline.md) 处理：
+
+- **文档类型保持不变**；用户明确要求转型时除外（如从「执行型 SOP」改成「说明型接口文档」）
+- **同类信息保持一致**：改写时不要把原本统一的元素改为多种表达
+- **颜色/emoji 语义**：改写后仍满足 style guideline §5「颜色与视觉语义」的一致性
+- **不删除附件/图片**；用户明确要求时除外
+
+---
+
+## 六、回读验收
+
+`+update/+checkpoint-update` 已统一确认与验证。正常成功禁止额外整篇读取；partial/unknown 或确需检查富结构时，使用最小范围 `+fetch`。
+
+校验要点：
+
+- 改写章节的关键标题、段落首句、表格表头是否符合预期
+- overwrite 后旧内容是否真的被清除
+- append 后新内容是否在期望位置
+- 表格、代码块、列表跨块元素是否完整
+- @人、附件、图片等保真要素是否原样保留
+
+### 异常处理
+
+| 现象 | 可能原因 | 处理 |
+|------|----------|------|
+| overwrite 后旧内容残留 + 新内容追加在末尾 | overwrite 被静默降级为 append | 告知用户 overwrite 降级，按下方「先清空再重建」路径修复 |
+| append 后部分片段缺失 | 分块写入丢失 | 定位缺失片段，针对该段单独再 append 一次 |
+| @人 / 附件被替换为纯文本 | 改写时未走保真约束 | 用 JSONML 无损编辑修复（§4.4）|
+| 整篇内容乱序 | 写入顺序异常 | 报告给用户；若可重做，按下方「先清空再重建」路径修复 |
+
+**禁止**在未回读的情况下向用户报告"已完成"。
+
+---
+
+## 七、交付口径
+
+只报告已经验证过的信息：
+
+- 改写涉及的章节范围
+- 改写后的 nodeId 与 docUrl
+- 回读验收结果（哪些章节确认改写成功、保真要素是否完整）
+- 如有缺失或异常，说明具体位置和已采取的修复动作
+
+未回读前，不要说「内容完整」「改写完成」。

package/skills/dws/dingtalk-doc/references/doc.md

@@ -0,0 +1,82 @@
+# dingtalk-doc 低频能力索引
+
+本页只在根 Skill 的 Golden Route 和精确任务 Reference 都无法选路时加载。它不是创建、读取或更新任务的前置必读，也不要求预加载样式、JSONML 或完整产品帮助。
+
+## 高频入口
+
+| 意图 | 推荐命令 | 精确 Reference |
+|---|---|---|
+| 搜索在线文字文档 | `dws doc +search --query <关键词>` | [doc-info.md](doc/doc-info.md) |
+| 读取正文或局部内容 | `dws doc +fetch --node <ID或URL>` | [doc-read.md](doc/doc-read.md) |
+| 创建并写入 | `dws doc +create` | [doc-create.md](doc/doc-create.md) |
+| 追加、覆盖、block 编辑 | `dws doc +update` | [doc-update.md](doc/doc-update.md) |
+| 重要更新与恢复点 | `dws doc +checkpoint-update` | [doc-update.md](doc/doc-update.md) |
+| 导出本地文件 | `dws doc +export` | [doc-export.md](doc/doc-export.md) |
+| 导入为在线对象 | `dws doc +import` | [doc-import.md](doc/doc-import.md) |
+| 列出文档空间/文件夹下的文档 | `dws doc +list --workspace <WS_ID>` | 知识库层级管理切 `dingtalk-wiki` |
+| 评论聚合与操作 | `dws doc +review/+comment-*` | [doc-comment.md](doc/doc-comment.md) |
+| 媒体插入、列表、下载 | `dws doc +media-*` | [doc-media.md](doc/doc-media.md) |
+
+命令已选定但参数不确定时读取精确 leaf Schema；只有 Cobra flag 与 Schema 冲突时读取精确 leaf Help。不要加载 `dws doc --help` 或完整 Catalog 代替选路。
+
+## 模板
+
+只有名称时先只读搜索：
+
+```bash
+dws doc +template-search --query "周报" --source PUBLIC --format json
+```
+
+来源按用户原话守门：“我的模板/我这边”只查 `MY`，明确“公开/钉钉模板库”才查 `PUBLIC`；不得为了凑结果跨来源扩展。未指定来源时保持默认 `MY`。
+
+- `selection.status=resolved`：取唯一候选的 `templateId`。
+- `selection.status=not_found`：报告零命中后停止；不得改用语义不相干的热门模板，更不得擅自创建文档。
+- `selection.status=selection_required`：展示候选并要求用户选择，禁止默认第一项。
+
+若返回 `hasMore=true`，沿原 query/source 使用 cursor 继续搜索；只有服务端返回完整结果后才能判断零命中或完整候选集。
+
+选定后只创建一次：
+
+```bash
+dws doc +create-from-template --template-id <TEMPLATE_ID> --name "我的周报" --format json
+```
+
+禁止通过实际创建多个候选文档来预览模板。`+create-from-template --query` 仅保留兼容，不能作为新的 Agent Golden Route。
+
+## 历史版本
+
+```bash
+dws doc +version-save --node <DOC_ID> --format json
+dws doc +version-list --node <DOC_ID> --limit 20 --format json
+dws doc +version-revert --node <DOC_ID> --version <N> --format json
+```
+
+`+version-save/list/revert` 分别用于快照、浏览和恢复，命中后直接执行，不预读 Help。`+history-*` 仅兼容已有调用，不用于新的 Agent 选路。重要内容更新优先使用 `+checkpoint-update`，不要手工编排保存、写入和回读。回滚必须确认，以 leaf Schema 与 Runtime gate 为准。
+
+只读某个历史版本的内容时，用 `dws doc +fetch --node <DOC_ID> --version <N>`（版本号同样来自 `+version-list`，`0` 表示初始版本，需要文档编辑权限）；整体恢复到历史版本才用 `+version-revert`（危险操作，需确认）。互联网公开文档（含密码保护）的读取见 [doc-read.md](doc/doc-read.md) 的 `--password`。
+
+## 权限与分享
+
+- 查询或聚合权限：`+inspect --include-permissions`。
+- 新增、变更、移除权限：`+access-grant/+access-change/+access-revoke`。
+- 授权后发链接：`+grant-and-share`。
+- 姓名、群聊或组织 profile 多候选时必须停止消歧。
+
+## 高级原子能力
+
+以下能力在 shortcut 未公开所需参数时才使用原子 leaf：
+
+- 特殊 JSONML block、白板或样式字段
+- 需要原始 MCP 响应的诊断
+- shortcut 明确返回 capability unavailable 的低频操作
+
+进入高级通道前只读取对应 leaf Schema 和一个精确 Reference。原子命令不是 shortcut 失败后的自动兜底，不能用来绕过权限、确认、类型或路径检查。
+
+## 本地与跨产品边界
+
+- 普通文件上传、下载、目录和文件树：`dingtalk-drive`
+- 知识库空间与节点层级：`dingtalk-wiki`
+- 原生 Markdown 文件：`dingtalk-misc`
+- `axls` / `able`：对应电子表格或多维表 Skill
+
+导出或媒体错误必须保留稳定 ID 后停止。禁止隐式执行 `curl/wget`、`pip/brew install`、Python Office 库、本地 OCR 或手写 HTTP 来伪造 DWS 任务结果。

package/skills/dws/dingtalk-doc/references/intent-guide.md

@@ -0,0 +1,20 @@
+# doc 局部意图消歧
+
+本文件从单 Skill `intent-guide.md` 拆分而来，仅保留与本产品相关的跨产品消歧规则。
+
+| 用户说... | 真实意图 | 应该用 | 不要用 | 理由 |
+|---|---|---|---|---|
+| "搜一下 OAuth2 接入文档" | 搜索开发文档 | `devdoc` | `doc search` | 搜索开放平台技术文档，不是钉钉内部内容 |
+| "帮我建一个项目跟踪表" | 创建数据表格 | `aitable` | `doc` / `sheet` | 涉及结构化数据/行列操作，不是富文本文档或电子表格 |
+| "帮我写个项目周报" | 创建钉钉文档 | `doc` | `aitable` | 富文本内容创作，不是数据表 |
+| "参照这个生成同样的 / 按模板生成 / 复刻 X / 同样的模板 X 月份的" + 已有 alidocs URL | 模板保形生成同形态变体 | `drive copy + drive rename + doc block update` → 见 [best_practices/04-document.md `template-based-generation`](../../dingtalk-doc/references/04-document.md#template-based-generation) | `doc read + doc create`（重写链） | adoc → markdown 是有损投影，read+create 会丢行高/单元格背景色/字号；copy 在 adoc 层保形复制后只在副本上局部修改 |
+| "复制一份这个文档 / 把这篇文档挂到 X 文件夹"（不涉模板变体） | 在线文档节点的存储层复制/移动 | `dws drive +copy --node <ID> [--folder <目标ID>]` / `dws drive +move --node <ID> --folder <目标ID>` | doc 同名 `+copy`/`+move`；`wiki node copy` | 复制/移动属节点存储管理，归 drive；drive 版先 probe 对象类型并拒绝普通文件，doc 裸版对普通文件会生成 `.dlink` 快捷方式而非副本 |
+| "这个 alidocs 表格链接帮我看下"（粘贴原始 URL） | 先 probe 节点类型 | `dws drive info --node` → 按 `extension` 路由 | 直接调 `sheet` | `alidocs/i/nodes/{id}` 可能是文档/axls/able/xlsx 等，禁止凭 URL 猜类型 |
+| "帮我记一下明天要做的事" | 创建个人待办 | `todo` | `doc` | 个人待办提醒，非文档内容 |
+| "在知识库里创建一个文档" | 创建空文件实体 | `wiki node create --type adoc` | `doc create` | 空间内创建节点归 wiki；doc create 是向已有文档写入内容，不是创建文件节点 |
+| "帮我看看收到的日报" | 收到的日志 | `report` | `doc` | 钉钉日志系统（日报/周报），不是文档 |
+| "整理一下XX项目的所有讨论" | 跨源主题归档 | #5 generate-topic-report | #4 write-doc | #4 侧重单篇文档创作；按主题跨听记/群消息汇总属于工作汇报 |
+| "搜一下智能化方案/最近 OKR 相关邮件/最近发版相关消息" | 搜企业知识内容 | `aisearch enterprise` | `doc search` / `mail search` / `chat message search` | 跨文档、消息、日程、听记、邮件等企业内容语义检索走 enterprise；具体 `queries/types/time-range` 抽槽见 `aisearch.md` |
+| "我发给某人的消息/邮件/文档/今天我干了什么" | 搜行为记录 | `aisearch behavior` | `chat` / `mail` / `doc` / `report` | 关注“谁对什么做过什么”，走 behavior；具体 `behavior-type/direction/chat-scope` 抽槽见 `aisearch.md` |
+| "把这段文字翻译成英文/translate this" | 通用文本翻译 | `chat text translate` | `doc` / `aisearch` | 纯文本翻译，不是文档编辑或语义搜索 |
+| "帮我把这个文档翻译成日文" | 文档内容翻译 | 先 `dws doc +fetch --node` 再 `chat text translate` | `chat text translate` 直接传文件 | translate 仅支持纯文本，需先提取文档内容；普通读取统一走 shortcut |

package/skills/dws/dingtalk-drive/SKILL.md

@@ -0,0 +1,128 @@
+---
+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 <关键词> --page-all --max-pages 20 --max-items 500` | 需要完整搜索时自动翻页；只需首批结果时可不加 `--page-all`；多候选停止；在线文档正文搜索走 `doc +search` |
+| 浏览根目录或已知文件夹 | `dws drive +list [--folder <dentryUuid>] --page-all --max-pages 20 --max-items 500` | 需要完整浏览时自动翻页；只需首批结果时可不加 `--page-all` |
+| 发现钉盘企业空间或“我的文件”空间 | `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 download --node <dentryUuid> --url-only --format json` | Agent 沙箱/外部系统自行下载时用；与 `--output/--overwrite` 等落盘参数互斥 |
+| 上传普通文件到钉盘或知识库 | `dws drive +upload --file <相对路径> [--workspace <ID>]` | 默认进钉盘；指定 workspace 时成为知识库/文档空间中的独立文件节点；folder 与 node、workspace 与 space-id 分别互斥 |
+| 管理普通文件全局评论 | `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 根目录整理：禁止预查 `mySpace/rootFolderId`，禁止 `doc +create` 后 `drive +move`；应由 Wiki 创建空间，Doc `+import --workspace <新workspaceId>`，再 Wiki `+move-to-drive --workspace <新workspaceId>`。
+- 目标 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`；知识库/文档空间目标显式加 `--workspace`，不要退回 upload-info + 手写 HTTP + commit。转换为在线文档走 Doc `+import`，插入正文附件走 Doc `+media-insert`。
+- 导出后上传：`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` 的完整查询统一使用 `--page-all --max-pages <N> --max-items <N>`，并检查集合、完整性和截断状态；只需首批结果时可不加 `--page-all`。缺少集合不能当空结果，多候选禁止默认第一项。
+- `+download` 验证相对路径存在且 sizeBytes > 0；`+upload` 检查最终 nodeId 和完整名称。普通 Drive 目标必须校验读回大小；指定 `--workspace` 时必须验证 workspaceId，并兼容 `doc/get_document_info` 将完整名称拆为 `name + extension` 且不返回大小的真实契约；若返回大小仍必须与本地一致。只有源端与结果都提供可比哈希时才核对 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，但“Wiki 库内节点移出到我的文档”固定由 Wiki `+move-to-drive` 完成，Drive 不预查 `mySpace`、不接管该移动。
+- 钉盘存储空间发现例外地复用 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 只保留原文件。