dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-contact/references/recipes/conventions.md

@@ -0,0 +1,44 @@
+# 业务域通用规范
+
+> 仅服务本 skill 已迁入的行动指南。安全门控、危险操作确认、`--format json` 等已在本 skill 的 `SKILL.md` 中定义，此处不重复。
+
+## 批量查询规范
+
+| # | 规范 |
+|---|------|
+| 1 | **并行查详情**：拿到多个 ID 后，用 `&` 合并到同一条 Shell 命令并行执行 + `wait`，**严禁逐条串行** |
+| 2 | **翻页**：分页接口须拉全直至无更多 |
+| 3 | **优先批量 API**：有批量接口则用批量；无则按 #1 并行 |
+| 4 | **群消息**：必须先 `chat search --query` 得 `openConversationId`，再 `chat message list --group <openConversationId> --time "<yyyy-MM-dd HH:mm:ss>" --direction older`；多群同条命令并行 |
+| 5 | **列表少轮次**：带条件搜索/列表 → 一次采全详情；**禁止**无新参数时重复同一 `list` / `search` |
+
+## 多源并行采集（公共模式）
+
+> recipe 引用方式：`按「多源并行采集」执行（关键词=<X>，时间=<Y>至<Z>）`。
+
+- 同条 Shell：`&` 并行 + `wait`；分页须采全。
+- 只保留与主题相关的数据，无关丢弃。
+- 有批量详情接口优先；否则并行拉详情（见上表 #1）。
+- 具体采哪些产品列表由对应 **行动指南 recipe** 与当前产品参考决定；不要引入本文档未覆盖的产品路线。
+
+## 字段术语与 ID 传递
+
+> list 返回 JSON 后，必须提取下表字段传给后续命令。**禁止用其他字段替代。**
+
+| 字段 | 来源 | 传递给 |
+|------|------|--------|
+| `taskUuid` | `minutes list` | `minutes get summary/info/batch --id(s)` |
+| `userId` | `aisearch person` / `contact user search` / `contact dept list-members` | `contact user get --ids`、`todo --executors`、`calendar --users` |
+| `deptId` | `contact dept search` | `contact dept list-members --ids <deptId1,deptId2...>`；多子部门时对每个子部门分别 `dept search` 取 id |
+| `nodeId` | `drive search` / `wiki node search` | `doc read/update --node`、`drive copy/move/rename/delete --node` |
+| `nodeId` | `wiki node list` 中的 folder 类型节点 / `wiki node create --type folder` | `wiki node list --folder`、`wiki node create --folder`、`drive upload --folder`、`drive copy/move --folder` |
+| `eventId` | `calendar event list` | `calendar event get/update --id` |
+| `processInstanceId` | `oa approval list-*` | `oa approval detail/approve --instance-id` |
+| `openConversationId` | `chat search` | `chat message list/send --group` |
+| `todoTaskId` | `todo task list` | `todo task update/done --task-id` |
+| `reportId` | `report inbox list` / `report outbox list` | `report entry get/stats --report-id` |
+| `baseId` / `tableId` | `aitable base search` | `aitable record query --base-id --table-id` |
+| `dentryUuid` | `drive list` / `drive mkdir` | `drive info/download/copy/move/rename/delete --node`、`drive list/mkdir/upload/copy/move --folder` |
+| `dentryId` | `drive info` 的数字字段 | 仅用于 `chat message send --dentry-id` |
+
+**ID 边界硬约束**：`dentryId` 通常是纯数字，只表示聊天文件消息需要的钉盘条目数字 ID；它不是父目录 ID。遇到 `drive --node/--folder`、`doc --node`、`wiki node --folder` 时，只能使用 `dentryUuid` / `nodeId` / 文档 URL。若当前上下文只有数字型 `dentryId`，必须先重新 `drive list` / `drive search` / `wiki node list` 获取正确 ID，不能把该数字直接代入后续命令。

package/skills/dws/dingtalk-contact/scripts/contact_dept_members.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""
+按部门名称搜索并列出所有成员（自动 deptId 解析）
+
+用法:
+    python contact_dept_members.py --query "技术部"
+    python contact_dept_members.py --query "产品" --dry-run
+"""
+
+import sys
+import json
+import subprocess
+import argparse
+from typing import List, Any, Optional
+
+
+def run_dws(
+    args: List[str], dry_run: bool = False,
+) -> Optional[Any]:
+    cmd = ['dws'] + args
+    if dry_run:
+        print(f"[dry-run] {' '.join(cmd)}")
+        return None
+    try:
+        result = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=60
+        )
+        if result.returncode != 0:
+            print(f"错误：{result.stderr.strip()}", file=sys.stderr)
+            return None
+        return json.loads(result.stdout)
+    except (subprocess.TimeoutExpired, json.JSONDecodeError,
+            FileNotFoundError) as e:
+        print(f"错误：{e}", file=sys.stderr)
+        return None
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='按部门名称搜索并列出所有成员'
+    )
+    parser.add_argument(
+        '--query', required=True, help='部门名称关键词'
+    )
+    parser.add_argument('--dry-run', action='store_true')
+    args = parser.parse_args()
+
+    print(f'🔍 搜索部门: {args.query}')
+    dept_data = run_dws([
+        'contact', 'dept', 'search',
+        '--query', args.query, '--format', 'json',
+    ], dry_run=args.dry_run)
+
+    if args.dry_run:
+        run_dws([
+            'contact', 'dept', 'list-members',
+            '--ids', '<DEPT_ID>', '--format', 'json',
+        ], dry_run=True)
+        return
+
+    if not dept_data:
+        print('未找到匹配部门')
+        sys.exit(1)
+
+    if isinstance(dept_data, list):
+        depts = dept_data
+    elif isinstance(dept_data, dict):
+        inner = dept_data.get('result', dept_data)
+        if isinstance(inner, dict):
+            depts = inner.get('items', inner.get('depts', []))
+        elif isinstance(inner, list):
+            depts = inner
+        else:
+            depts = []
+    else:
+        depts = []
+    if not depts:
+        print('未找到匹配部门')
+        sys.exit(1)
+
+    for dept in depts:
+        dept_id = dept.get('id') or dept.get('deptId')
+        dept_name = dept.get('name') or dept.get('deptName', '未知')
+        if not dept_id:
+            continue
+
+        print(f"\n📂 {dept_name} (ID: {dept_id})")
+        print('-' * 40)
+
+        members_data = run_dws([
+            'contact', 'dept', 'list-members',
+            '--ids', str(dept_id), '--format', 'json',
+        ])
+        if not members_data:
+            print('  无法获取成员列表')
+            continue
+
+        if isinstance(members_data, list):
+            members = members_data
+        elif isinstance(members_data, dict):
+            inner = members_data.get('result', members_data)
+            if isinstance(inner, dict):
+                members = inner.get('userlist',
+                                    inner.get('list', []))
+            elif isinstance(inner, list):
+                members = inner
+            else:
+                members = []
+        else:
+            members = []
+        if not members:
+            print('  (暂无成员)')
+            continue
+
+        for m in members:
+            name = m.get('name') or m.get('userName', '未知')
+            title = m.get('title') or m.get('position', '')
+            uid = m.get('userId') or m.get('userid', '')
+            line = f"  👤 {name}"
+            if title:
+                line += f" ({title})"
+            if uid:
+                line += f"  [ID: {uid}]"
+            print(line)
+
+        print(f"  共 {len(members)} 人")
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,112 @@
+---
+name: dingtalk-doc
+description: 钉钉在线文字文档（adoc）本体及其内容的操作：查找、创建、读取、文档信息、编辑、块、评论、附件与媒体、白板卡片容器插入删除、导入、导出(docx/markdown/pdf)、版本、模板、协作者权限、分享及Markdown/JSONML写入。不包括：白板/画布内的 OpenNodes 图形、文本、分组、连线、Vector 和布局读写（归 dingtalk-misc 的 Whiteboard）、文档空间与钉盘的文件管理（归 dingtalk-drive，doc 同名原子命令已弃用）、知识库空间与节点管理（归 dingtalk-wiki）、原生 .md 文件读写（归 dingtalk-misc）、电子表格 axls（归 dingtalk-misc）、AI 表格 able（归 dingtalk-aitable）。命令前缀：dws doc。
+metadata:
+  cli_version: ">=0.2.14"
+  category: product
+  requires:
+    bins:
+      - dws
+---
+
+# 钉钉文档 Skill
+
+<!-- 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 发现（按需）
+
+`doc` 当前有 45 条公开 shortcut，完整清单保留在 Runtime Catalog 与 Schema，不在高频产品根 Skill 中重复展开。已知意图按下方路由。
+
+仅当现有路由和 reference 都无法定位低频能力时，才执行 `dws shortcut list --service doc --format json` 做最后回退；不要为已知高频意图加载完整 Shortcut Catalog 或产品级 Schema。
+<!-- VISIBLE_SHORTCUTS_END -->
+
+## Golden Route
+
+ID/URL 直用;标题先搜索,唯一命中再执行.顺序:稳定 ID → shortcut → 局部读 → 精确写;禁以产品 Schema、全文或原子命令起步.
+
+| 用户意图 | 唯一推荐入口 | 关键边界 |
+|---|---|---|
+| <!-- dws-intent: doc.search.by_title -->按标题或主题定位文档 | `dws doc +search --query <精确标题>` | `complete=true,count=0,failures=[]` 即权威零命中：如实报告；禁缩词、跨产品、无 query/无端 `--page-all` |
+| 最近访问或最近编辑文档 | 加载 `dingtalk-drive`，执行 `dws drive +recent [--operate-type 1] --limit <N>` | 默认最近访问，`1` 为最近编辑；不要用 `doc +search` 替代最近列表 |
+| <!-- dws-intent: doc.content.read -->已知 ID/URL 读取正文或局部内容 | `dws doc +fetch --node <ID或URL>` | 术语用 `keyword`;章节 `outline` → `section`;整篇才用 `full` |
+| 聚合查看信息、权限、版本、媒体或评论 | `dws doc +inspect --node <ID或URL>` | 基础元信息默认返回；样式、权限、历史、媒体、评论才用对应 `--include-*`，无 `--include-info` |
+| 新建在线文字文档并写入内容 | `dws doc +create --name <标题> --content <文本\|-\|@文件> [--folder <ID>\|--workspace <ID>]` | 指定位置复用真实 ID，二者互斥;`-`=stdin,禁 `@-`;Runtime 分片回读,不拆写 |
+| <!-- dws-intent: doc.content.update -->追加、覆盖或精确编辑 block | `dws doc +update --node <ID或URL> --command <动作>` | 唯一文本 `str_replace`;章节/block 局部取 ID;整篇才 overwrite |
+| 重要内容更新且需要恢复点 | `dws doc +checkpoint-update` | 自动保存版本,更新并回读;检查 `steps` 和 `compensation` |
+| 版本操作 | `dws doc +version-save --node` / `dws doc +version-list --node` / `dws doc +version-revert --node --version` | 快照/列表/回滚 |
+| <!-- dws-intent: doc.export.format -->导出为 docx/markdown/pdf | `dws doc +export --export-format <格式>` | 格式必须显式指定;普通文件下载切 `dingtalk-drive` |
+| <!-- dws-intent: doc.import.local_file -->本地文件转在线文档 | `dws doc +import --file <相对路径> [--folder <ID>\|--workspace <ID>] [--name <用户指定文档名>]` | 指定位置复用真实 ID，二者互斥；目标是已创建知识库时必须带其 workspaceId；未指定才由 Runtime 取默认根并回读验证落点；`doc +create` 不能替代知识库内导入；仅保留原文件走 `dingtalk-drive` |
+| 封面/背景 | `+resource-update/+resource-delete`；`+background-update/+background-delete` | 写后 `+inspect --include-style`；禁查 Catalog |
+| 浏览模板 | `dws doc +template-list [--source MY\|PUBLIC] [--page-all]` | “我的/我这边”只查 MY；明确公开才查 PUBLIC；“有哪些/全部”加 `--page-all` 并检查 `complete` |
+| 搜索模板 | `dws doc +template-search --query <名称或关键词>` | 来源可选 MY/PUBLIC；零命中停止，禁止拿无关模板替代；多候选消歧 |
+| 从模板创建 | `dws doc +create-from-template --template-id <唯一ID>` | 已有唯一 templateId 才创建；不重复 list/search |
+| 创建/查评论 | `dws doc +comment-create --node <ID或URL> --content <文字> [--selection <原文>]` / `+review --node <ID或URL>` | node/content 必填；划词也用 `+comment-create`；续操作复用 `commentKey` |
+| <!-- dws-intent: doc.access.grant -->添加/调整/移除协作者权限 | `dws doc +access-grant/+access-change/+access-revoke` | `--to` 必填；`--role` 默认 READER（READER\|DOWNLOADER\|EDITOR\|MANAGER）；无 `--user-ids`；先读权限，歧义/profile 不一致禁写 |
+| <!-- dws-intent: doc.share.link_only -->只发链接不改权限 | `dws doc +share --to <姓名[,姓名]> --url <URL> [--note <附言>]` | 内置姓名解析；仅歧义时 aisearch，禁预查人；普通私信用 chat |
+| 授权后向多人分享链接 | `dws doc +grant-and-share` | 仅需改权限时用（必填 `--node`，role 默认 READER）；检查逐人账本和部分失败 |
+| <!-- dws-intent: doc.media.insert -->把文件/PPT/PDF 作为正文附件 | `dws doc +media-insert --node <DOC_ID> --file <相对路径>` | 正文附件走 Doc；`drive +upload` 仅入库存储，不会插入正文 |
+
+## 关键结果语义
+
+- 保留真实 `nodeId`/URL/类型/容器；复用 ID，禁标题/钉盘重搜。
+- 用完整回执；Runtime 回读后不复读；仅局部验收、`partial_success`/commit-unknown 再 `+fetch`。
+- 恢复：`partial_success` 只补未完成；`unknown` 先回读、禁重写；`retryable` 仅限明确未开始；权限/参数/认证失败即停。
+- 结果明确且回读匹配才报完成。
+- 搜索/列表检查 `complete`/`hasMore`/cursor/失败项；“全部”翻完页，前 N 条须声明范围。
+- `+import` 检查 `success=true`、`verified=true`、`taskId/nodeId/documentUrl`；复用返回 ID，禁 Drive 重找；中断查原任务，禁重导。
+- 跨产品任务“新知识库内导入后再移到我的文档”：先用 Wiki 创建返回的 workspaceId 执行 `doc +import --workspace`，再把导入 nodeId 交给 `wiki +move-to-drive --workspace`；禁止在个人域创建后用 Drive 移动伪造入库步骤。
+- 导出/下载用 cwd 相对路径；`+export` 有 `localPath` 且 `sizeBytes>0` 即终态，禁 `ls/stat`。
+
+## 参数与安全边界
+
+- `@file`：已有或临时文件先暂存到 cwd；传 `@相对路径`，生成文本优先 `--content -`；禁绝对路径和 `..`。
+- `doc +update` 用 `--command` 指定动作；block ID 必须来自 `+fetch --detail with-ids` 或真实列表。
+- Schema 门禁：不确定时仅查一次精确 leaf：`--fields use_when,avoid_when,parameters,constraints,confirmation`；禁用产品级/`--all`。准备 Help 时，本轮仅查一次。
+- 消费本页或精确 Schema 的 `confirmation`：`user_required` 且原请求/预授权已确认目标、动作、参数时，首调即加 `--yes`；否则预览/询问；禁止靠失败探测门禁。
+- JSONML 顶层必须是单个非空元素；禁止 `[[...]]` 元素数组包裹。
+
+## 按需加载
+
+Golden Route 已给出命令且参数足够时，禁止读取 reference；其余仅遇下表语义时才最多读取一个 reference：
+
+| 触发条件 | Reference |
+|---|---|
+| 低频/无 shortcut 意图消歧 | [intent-guide.md](references/intent-guide.md) / [doc.md](references/doc.md) 对应章节 |
+| 分页、`partial_success`、`status=unknown` 或恢复 | [contracts.md](references/contracts.md) |
+| 复杂 JSONML、长文或局部精准读写 | [create](references/doc/doc-create.md) / [read](references/doc/doc-read.md) / [update](references/doc/doc-update.md) |
+| block/划词评论/媒体/封面/背景高级参数 | [block](references/doc/doc-block.md) / [comment](references/doc/doc-comment.md) / [media](references/doc/doc-media.md) |
+| 导出/导入失败恢复 | [export](references/doc/doc-export.md) / [import](references/doc/doc-import.md) |
+
+常规 `+create`、`+fetch`、`+update` append/overwrite、`+export`、`+import` 禁止读取 reference；禁预加载/连读。
+
+## 错误最短路径
+
+1. 零命中、多候选、类型不明或分页不完整：停止写入，展示候选或 continuation；禁止默认第一项。
+2. Help 不参与选路；先读一次精确 leaf Schema。仅真实 `unknown flag`/契约漂移查一次 leaf Help；`unknown command` 只查一次 shortcut 清单，禁止试探后缀和 `dws doc --help | grep/head`。
+3. `REVISION_CONFLICT`：重新读取当前 revision，展示差异；未经用户确认不得改成无 revision 覆盖。
+4. `doc_write_commit_unknown`：先回读；禁止自动重试创建或追加。
+5. 认证、权限或 profile 错误：只读 `dingtalk-shared` 对应 reference，禁底层命令绕过。
+6. 导出/媒体失败：保留稳定 ID 后停止；禁网络请求/安装依赖/本地文档库兜底。
+
+## 产品边界
+
+- 姓名/工号/部门/职责找人或解析 userId → `dingtalk-aisearch`；已有完整 userId 补详情才用 `dingtalk-contact`
+- 普通文件/目录存储与上传下载 → `dingtalk-drive`；保留原文件进入明确知识库可用 `drive +upload --workspace`；“放进/附到这篇文档”是正文附件 → `doc +media-insert`；在线转换 → `doc +import`
+- 文档节点复制、移动、模板另存 → `dingtalk-drive +copy/+move`；doc 同名命令仅兼容
+- 知识库空间、节点层级和成员管理 → `dingtalk-wiki`；本地文件进入明确知识库时由 Doc `+import --workspace` 创建内容节点，后续移出使用 Wiki `+move-to-drive`
+- 原生 `.md` 文件读取和编辑 → `dingtalk-misc`
+- `axls` / `able` → 对应电子表格或多维表 Skill
+- 持续监听文档事件 → `dingtalk-misc`

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

@@ -0,0 +1,57 @@
+# 文档组合任务
+
+本页只描述跨步骤组合任务。单一创建、读取、更新、导出或媒体操作直接使用根 Skill Golden Route，不要加载本页。
+
+## 创建成稿
+
+1. 把最终正文写到工作目录内的 `body.md` 或 `body.json`。
+2. 执行一次 `dws doc +create --name "<标题>" --content @body.md --format json`。
+3. 使用返回的 `verified/nodeId` 判断完成；只有用户明确要求额外结构验收时再做局部 `+fetch`。
+
+复杂排版才按需读取 style/JSONML Reference；执行入口仍使用 `+create`。禁止调用已删除的创建脚本。
+
+## 导入文件
+
+```bash
+dws doc +import --file ./report.docx --folder <FOLDER_ID> --format json
+```
+
+导入是服务端格式转换。禁止先读文件内容再走 `create + update`。单纯保存普通文件切换到 `dingtalk-drive` 上传。
+
+## 查找并读取
+
+```bash
+dws doc +fetch --query "<唯一标题>" --format json
+```
+
+`+fetch --query` 会跨页解析唯一在线文字文档。零命中、多候选或类型不是 `adoc` 时停止并按返回候选消歧；不要继续调用 drive/wiki/aisearch 做无界穷举。
+
+## 更新章节
+
+1. `+fetch --node <ID> --scope section|keyword` 读取最小必要上下文。
+2. 普通编辑用 `+update`；重要覆盖用 `+checkpoint-update`。
+3. 使用 shortcut 的验证结果；`partial_success/unknown` 时只恢复缺失步骤。
+
+## 从模板创建
+
+1. `+template-search --query <名称>`。
+2. 唯一命中才取得 `templateId`；多候选要求用户选择。
+3. `+create-from-template --template-id <ID>` 只执行一次。
+
+模板保形复制已有文档是另一种任务：使用 drive copy 复制源文档，再只修改副本。禁止 `doc read → doc create` 重建富格式模板。
+
+## 导出并归档
+
+1. 在线文字文档使用 `+export` 导出到工作目录。
+2. 检查 `localPath/sizeBytes`。
+3. 用户要求归档到钉盘时，再用 `dingtalk-drive` 上传该文件。
+
+导出失败不得安装本地转换依赖或直接下载临时 URL。
+
+## 文档转消息/待办
+
+1. 使用局部 `+fetch` 提取必要内容。
+2. 在目标产品中解析真实用户/群/任务标识。
+3. 根据目标产品 Runtime gate 确认后写入。
+
+跨产品步骤必须复用稳定 ID；失败后不能重放已经成功的文档写入步骤。

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

@@ -0,0 +1,40 @@
+# Doc Runtime Contracts
+
+本文只定义 Agent 需要稳定消费的文档运行时语义。字段以 leaf Schema 和实际 JSON 返回为准；不要从终端展示文本反推状态。
+
+## 目标
+
+文档目标至少保留 `nodeId`、资源类型、canonical URL（服务返回时）和容器信息。名称或标题不是稳定身份。按自然标题解析出现零命中、多候选或分页不完整时，写操作必须停止。
+
+## 写操作状态
+
+| status | 含义 | 后续动作 |
+|---|---|---|
+| `success` | 所有计划步骤完成，且需要验证的内容已经回读 | 可以向用户报告完成 |
+| `partial_success` | 已发生部分副作用，后续步骤失败 | 检查 `steps` 与 `compensation`，不得重放成功步骤 |
+| `unknown` | 请求已发出但无法确定服务端是否提交 | 先回读目标；创建和追加禁止自动重试 |
+| `retryable` | 服务端明确业务执行尚未开始，且允许重试 | 遵循 `retry_after_seconds`，最多有界重试一次 |
+| `failed` | 已确认没有完成目标动作 | 根据 `retryable`、`actions` 和 details 决定是否重试 |
+
+进程退出码为零不能替代业务证据。采用 `doc.operation.v1` 的 shortcut 回执固定提供 `contractVersion/ok/status/complete/operation/steps/data/warnings/compensation`；`target/failures/verification` 只有实际操作返回时才能消费，不是通用字段。`+import` 使用现有导入回执，成功时检查 `success=true`、`taskId`、`documentUrl`、`documentName` 与 `documentType`，不要要求不存在的 `status/steps`。业务 `status` 不应与框架外层 `outcome` 混为一谈。
+
+稳定返回 ID/任务 ID 只用于定位目标、恢复流程或继续查询，不能单独证明写操作成功。成功证据优先级从高到低为：与该操作匹配的明确服务端成功终态 → 契约要求的写后读回匹配 → 仅 transport/退出码；异步任务必须使用返回的任务 ID 查询到成功终态。只有成功终态成立且所有必要回读均匹配时才报告成功；`partial_success`、`unknown`、未完成任务或仅返回资源/任务 ID 都不得报告完成。Runtime 已给出充分回读证据时，不为“再确认一次”重复请求。
+
+## 分页与完整性
+
+列表和搜索结果需要区分：
+
+- `complete=true`：已证明覆盖请求范围；
+- `hasMore=true`：仍有后续页，必须保留有效 continuation；
+- `truncated=true`：成功返回因 `max_pages` 或 `max_items` 边界停止，并通过 `stopReason` 说明原因；
+- 后续页请求失败、cursor 缺失/停滞/循环时返回 typed error；部分结果位于 `details.items`，并保留 `details.status=partial_success`、`complete=false`、`reason/page/nextCursor/count`。不要期待成功回执的空 `failures[]` 承载这类错误，也不要把 timeout 写成 `truncated`。
+
+只有 `complete=true` 且没有未处理失败时，才能把结果描述为完整集合。用户问“有哪些”“全部”或要求“列出结果”时，使用返回的 cursor/continuation 继续取页直至完整；只有用户明确要示例、前 N 条或接受部分结果时才可提前停止，并说明已覆盖范围。分页应复用原查询与过滤条件，不得换命令或放宽关键词。
+
+## 错误
+
+结构化错误至少区分 validation、not_found、ambiguous、type_mismatch、revision_conflict、confirmation_required、permission_denied、partial_success 和 commit_unknown，并提供 failure stage、retryable 与已有的 `actions`/details。权限、认证和参数错误直接进入 `failed`；写请求只有明确 `execution_started=false` 才能进入 `retryable`，其余传输异常进入 `unknown`。`retryable=false` 表示自动重放不安全，不代表用户检查状态后永远不能重新发起。不要发明 `suggestedAction` 或顶层 `nextCommand` 字段。
+
+## 安全落盘
+
+导出、下载和媒体预览只使用工作目录内相对路径。完成条件包括临时文件写入成功、内容校验、文件关闭和原子发布；失败时不得留下看似最终产物的半成品。默认 no-clobber，覆盖必须由用户显式选择。

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

@@ -0,0 +1,39 @@
+# 块级编辑 Golden Route
+
+## 普通路径
+
+先读取最小必要范围并取得稳定 block ID：
+
+```bash
+dws doc +fetch --node <DOC_ID> --detail with-ids --scope section --start-block-id <KNOWN_BLOCK_ID> --format json
+```
+
+再按意图使用统一更新入口：
+
+```bash
+dws doc +update --node <DOC_ID> --command block_replace --block-id <BLOCK_ID> --content "新内容"
+dws doc +update --node <DOC_ID> --command block_insert_after --after-block-id <BLOCK_ID> --content "补充内容"
+dws doc +update --node <DOC_ID> --command block_delete --block-id <BLOCK_ID>
+```
+
+`block-id` 必须来自真实 `+fetch --detail with-ids`、`+review` 或原子 block 列表返回。确认、写入与验证统一由 `+update` 处理，正常成功不追加整篇回读。
+
+## 标题块例外
+
+新增 heading 必须使用结构化插入，不能把 `# 标题` 作为 Markdown 传给 `block_replace`。例如在首块前新增一级标题：
+
+```bash
+dws doc block insert --node <DOC_ID> --heading "发布说明 v1.0" --level 1 --ref-block <FIRST_BLOCK_ID> --where before --format json
+```
+
+插入回执有稳定新 block ID 时，用 `dws doc block list --node <DOC_ID> --block-id <NEW_BLOCK_ID> --format json` 定点验证；回执只有插入 index 时，只执行一次 `dws doc block list --node <DOC_ID> --content-format jsonml --format json`，按该 index 验证 `blockType=heading`、`heading.level="heading-1"` 和标题文字。`block list` 没有 `--limit`，禁止 Help/试错；一次完整 JSONML 列表已满足结构验收时立即终止。CLI 写入仍使用数值参数 `--level 1`。修改现有标题才使用 `doc block update --block-id ... --heading ... --level ...`；不要用普通文字替换改变块类型。
+
+## 富结构专家路径
+
+只有需要 shortcut 未公开的 callout、分栏、复杂表格或 JSONML element 参数时：
+
+1. 按需读取 [JSONML schema](format/doc-jsonml-schema.md) 或 [cookbook](format/doc-jsonml-cookbook.md)，不要两者都预加载；用户已明确结构时优先 cookbook 的可执行样例。
+2. 读取精确 `doc block` leaf Schema，确认当前 flags。
+3. 用原子 block 命令只改目标块；JSONML update 的 uuid 必须等于目标 block ID。
+
+图片和附件不得手写临时 URL 或 OSS 请求，统一走 [`doc-media.md`](doc-media.md) 的 `+media-insert/+media-download`。删除与覆盖的确认以 Runtime gate 为准，示例不得预填 `--yes`。

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

@@ -0,0 +1,29 @@
+# 文档评论 Golden Route
+
+## Review 聚合
+
+```bash
+dws doc +review --node <DOC_ID_OR_URL> --format json
+```
+
+需要一次看到未解决评论、引用原文和 block 上下文时优先使用 `+review`。从真实返回取得 `commentKey` 和 `blockId`，禁止按数组位置或猜测 ID。
+
+## 精确评论动作
+
+```bash
+dws doc +comment-list --node <DOC_ID> --resolve-status unresolved --limit 20 --format json
+dws doc +comment-list --node <DOC_ID> --limit 20 --cursor <NEXT_TOKEN> --format json
+dws doc +comment-create --node <DOC_ID> --content "这里需要补充证据"
+dws doc +comment-create --node <DOC_ID> --selection "计划下周发布" --content "请确认日期"
+dws doc +comment-reply --node <DOC_ID> --comment-key <COMMENT_KEY> --content "已补充"
+dws doc +comment-update --node <DOC_ID> --comment-key <COMMENT_KEY> --content "修订后的意见"
+dws doc +comment-delete --node <DOC_ID> --comment-key <COMMENT_KEY>
+```
+
+- 全文与划词评论统一使用公开的 `+comment-create`：优先传唯一 `--selection`；已知真实 block 时传 `--block-id --start --end`，CLI 自动回读并校验 `selectedText`。不要选用未公开的 `+comment-create-inline`。
+- `--mention` 传单个 uid 或逗号分隔列表，例如 `--mention 550582,123456`；不要传 JSON 数组。
+- 列表用 `--limit` 控制页大小（兼容 `--page-size`），有 `nextToken` 时原样传给 `--cursor`；不能把单页当作全部评论。
+- 创建、回复、删除等写操作执行前消费 leaf Schema `confirmation`；需确认时先询问，示例不得预填 `--yes`。
+- 删除不可恢复，必须核对 node 与 commentKey。部分或未知结果不得自动重试。
+
+只有 shortcut 未公开必要字段时，才读取精确原子 leaf Schema；不要加载整份评论参考或产品 Catalog 来猜参数。

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

@@ -0,0 +1,54 @@
+# 创建在线文字文档
+
+本页只处理钉钉在线文字文档（`adoc`）创建。普通文件上传走 `dingtalk-drive`，表格和多维表分别走对应产品。
+
+## 唯一推荐入口
+
+```bash
+dws doc +create --name "<文档名>" [--content "短文本"] [--folder <ID> | --workspace <ID>] --format json
+dws doc +create --name "<文档名>" --content @body.md --format json
+dws doc +create --name "<文档名>" --content @body.json --doc-format jsonml --format json
+```
+
+- 统一输入协议：已有或临时文件先暂存到当前工作目录后传 `@相对文件`；单次生成文本可用 `--content -` 从 stdin 读取。
+- `@file` 禁止绝对路径和 `..` 逃逸；不要直接引用宿主临时目录。
+- `--name` 是文档名称；默认不要再在正文开头重复同名 H1，只有用户明确要求正文一级标题时才保留。
+- JSONML 顶层必须是数组。用户已经明确要求 callout、代码块、表格等具体富结构时，直接构造一份完整 JSONML 并只调用一次 `+create`；这不是开放式风格设计，不读取 `style/`。字段不确定时只读 [JSONML cookbook](format/doc-jsonml-cookbook.md)，不再连读 create/update/style。
+
+`+create` 负责创建、长 Markdown 分片和最终回读验证。正常成功结果至少包含：
+
+```json
+{
+  "status": "success",
+  "complete": true,
+  "data": {
+    "nodeId": "...",
+    "verified": true
+  }
+}
+```
+
+## 结果处理
+
+- `status=success` 且 `verified=true`：可以报告创建完成，并保留真实 `nodeId`/URL。
+- `status=partial_success`：文档或部分分片已经创建；按 `steps` 回读现状，禁止重跑整条创建。
+- `status=unknown`：服务端可能已经提交；先定位并读取文档，禁止自动重试。
+- 没有真实 `nodeId` 或写回执时，禁止声称“已创建”。
+
+## 创作与执行策略
+
+采用 Plan → Execute → Observe → Iterate，将循环放在本地内容与定点修正上，不把长文拆成一串远程创建/追加：
+
+1. **Plan**：明确受众、目的、范围和结构；正文由一个主上下文串行维护，避免按章节并行生成造成重复、矛盾和语气漂移。
+2. **Draft**：短内容可直接传；多行、长文或含特殊字符时先形成 cwd 内相对文件。用户未要求富结构时优先 Markdown；只有样式/引用/嵌套结构确有必要时才用 JSONML。
+3. **Execute**：只调用一次 `+create`。明确富结构用一份完整 JSONML 一次创建；DWS Runtime 会记录每步并回读验证。Agent 不采用“先骨架、再逐块远程插入”流程，以减少网络次数、顺序错误和 commit-unknown 面。
+4. **Observe**：先检查回执中的 `nodeId`、`verified`、`steps` 和失败状态。回执已证明完整时不重复拉全文；需要内容质量验收时，只用 `+fetch --scope section/keyword` 读取待检查部分。
+5. **Iterate**：后续修正复用同一 `nodeId`，按 [`doc-update.md`](doc-update.md) 做最小 block/文本修改，禁止重新创建整篇。
+
+交付前检查标题是否重复、段落是否连贯、编号是否统一；只有真实行列数据才使用表格，富组件服务于理解而不是装饰。明确字数要求时应在写入前完成本地统计，不能凭模型估算宣称达标。
+
+## 高级通道
+
+只有 shortcut 未公开所需的底层参数或需要原始响应时，才读取精确 leaf Schema 后使用 `dws doc create`。不要因为熟悉旧参数就默认退回原子命令，也不要使用已删除的 Python 创建脚本。
+
+复杂排版按需读取 [doc-style-guideline.md](style/doc-style-guideline.md)；需要 JSONML 起稿判定与起稿前设计规划时读 [doc-create-workflow.md](style/doc-create-workflow.md)；两者只按当前需求选一，命令选路仍以本页的 `+create` 为准。

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

@@ -0,0 +1,30 @@
+# 导出在线文档
+
+## 唯一推荐入口
+
+```bash
+dws doc +export --node <DOC_ID_OR_URL> --export-format docx --output ./exports/ --format json
+dws doc +export --node <DOC_ID_OR_URL> --export-format markdown --output ./document.md --format json
+dws doc +export --node <DOC_ID_OR_URL> --export-format pdf --output ./document.pdf --format json
+```
+
+`+export` 一次完成提交、轮询和原子下载。输出路径必须位于工作目录内，默认 no-clobber；目标已存在时返回 `LOCAL_FILE_EXISTS`，更换 `--output` 路径重试，没有覆盖用 flag。
+
+`--export-format` 必填；全局 `--format json` 只控制 CLI 输出，不能代替业务导出格式。禁止依赖默认 docx，也不要猜测 `--type`。
+
+异步状态 `INIT` 与 `PROCESSING` 都表示任务仍可继续轮询；只有终态失败才停止，不能把 `INIT` 当导出失败。
+
+## 类型边界
+
+- 在线文字文档（`adoc`）转为 docx/markdown/pdf：`+export`。
+- 已存在的普通文件原样下载：切换到 `dingtalk-drive`，使用 drive download。
+- 不要为了导出先把正文读到本地再重新生成文件。
+
+## 失败处理
+
+- 提交前权限/认证失败：原样报告并停止；不要尝试同义底层命令。
+- 已返回 `jobId` 后轮询失败或超时：保留 `jobId`，只用 `+export-get --job-id <JOB_ID>` 恢复查询，禁止重新提交导出。
+- 下载阶段失败：保留 `jobId` 和目标相对路径，用 `+export-get --job-id <JOB_ID> --output ./目标文件` 通过同一安全下载器恢复；不要直接 `curl` 临时 URL。
+- 禁止安装 `pandoc`、`python-docx` 或其他依赖来隐式伪造导出结果。只有用户明确改成“本地生成文件”任务时，才可作为一个新的独立工作流处理。
+
+只有需要显式接管异步 job 的恢复场景才使用 `+export-submit/+export-get`；正常导出不得手工编排它们。

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

@@ -0,0 +1,28 @@
+# 导入本地文件：`+import` Golden Route
+
+## 唯一推荐入口
+
+```bash
+dws doc +import --file ./report.docx --format json
+dws doc +import --file ./report.docx --folder <FOLDER_ID> --format json
+dws doc +import --file ./notes.md --workspace <WORKSPACE_ID> --name "会议纪要" --format json
+```
+
+`+import` 一次完成创建会话、上传、确认转换和终态轮询。支持 `doc/docx/xls/xlsx/md/txt/xmind/mark`，文件大小上限 20MB。转换成功回执包含 `success=true`、`taskId`、`documentUrl`、`documentName` 和 `documentType`，不包含 `status` 或 `steps`；成功返回即表示本次内部轮询已到终态。超时或中断时保留错误中的 `taskId`，只查询原任务。
+
+## 本地文件边界
+
+- `--file` 只接受当前工作目录内已存在的相对路径；禁止绝对路径、`..` 或符号链接逃逸。
+- `--folder` 与 `--workspace` 都是可选位置且互斥。对支持在线转换的格式，两者都不传时，Runtime 先读取当前组织唯一 `orgSpace`，把其 `rootFolderId` 作为 `targetFolderId` 后再创建导入会话；若空间为零个、多个、无权限或缺少 `rootFolderId`，会在写入前停止并要求显式提供目标，禁止选择第一项或猜 ID。`--folder` 取值首选用户提供的 alidocs URL 或真实 `nodeId`；不得使用普通文件 `drive info` 返回的父级 `folderId`。
+- CLI 负责上传和格式转换。不要先用 Python/Office 库解析文件，不要安装本地依赖来伪造在线导入结果，也不要手写 HTTP 上传。
+- 白名单外格式（如 HTML/PDF）自动改走原文件上传，返回 `fallback=upload`、`converted=false`；不得报告成已经转换为可编辑在线文档。
+- “在线改/协作编辑/转在线文档”属于导入转换；“存着/归档/保留原文件/不要转换”属于 `dingtalk-drive` 纯上传。目标为文档空间时，纯上传使用 `drive upload --workspace <WORKSPACE_ID>`，不要因容器叫“文档空间”就误报为在线文档。
+
+## 失败处理
+
+- 发起前的格式、大小或路径校验失败：修正输入后再执行。
+- 已返回 `taskId` 后超时或中断：保留该 `taskId`，读取精确恢复命令 Schema 后只查询原任务；禁止重新提交导入。
+- 返回状态未知时原样报告，不把本地文件内容改走 `+create`，因为这会改变格式保真和任务语义。
+- 白名单外格式如果目标是钉盘而非文档空间，切换到 `dingtalk-drive` 上传。
+
+正常导入不得手工编排原子 `doc import` 子步骤。只有 shortcut 未公开必要的恢复参数时，才按精确 leaf Schema 使用原子查询命令。

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

@@ -0,0 +1,12 @@
+# 查看文档信息：`+inspect` Golden Route
+
+```bash
+dws doc +inspect --node <DOC_ID_OR_URL> --format json
+dws doc +inspect --node <DOC_ID_OR_URL> --include-permissions --include-history --format json
+```
+
+只打开任务需要的 `--include-style/--include-permissions/--include-history/--include-media/--include-comments`，不要默认全取。正文读取使用 `+fetch`，不要用信息查询替代正文接口。
+
+检查返回的真实 `nodeId`、类型、URL 和各可选步骤。若 URL 指向的不是在线文字文档，停止 doc 流程并切换到 drive、sheet、aitable、slides 或 wiki；禁止凭 URL 外形猜类型。
+
+只有 `+inspect` 未公开所需的底层字段或必须获得原始响应时，才读取精确 leaf Schema 后使用原子信息命令。

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

@@ -0,0 +1,46 @@
+# 文档正文媒体
+
+## Golden Route
+
+```bash
+# 列出图片和附件，取得真实 resourceId/blockId
+dws doc +media-list --node <DOC_ID> --format json
+
+# 插入工作目录内的本地文件
+dws doc +media-insert --node <DOC_ID> --file ./image.png --format json
+
+# 下载到工作目录，默认不覆盖
+dws doc +media-download --node <DOC_ID> --resource-id <RESOURCE_ID> --output ./downloads/ --format json
+
+# 只为临时查看下载到受控临时目录
+dws doc +media-preview --node <DOC_ID> --resource-id <RESOURCE_ID> --format json
+```
+
+## 封面与背景 Shortcut
+
+```bash
+dws doc +resource-update --node <DOC_ID> --file ./cover.png --format json
+dws doc +resource-download --node <DOC_ID> --output ./cover.png --format json
+dws doc +resource-delete --node <DOC_ID> --format json
+dws doc +background-update --node <DOC_ID> --color "#E8F2FE" --format json
+dws doc +background-delete --node <DOC_ID> --format json
+```
+
+封面不是正文媒体 block；背景仅接受 `#RRGGBB` 纯色。设置/清除后用一次 `+inspect --include-style` 验证，禁止为这些已知能力查询 shortcut Catalog。
+
+## 稳定 ID 与结果
+
+- `resourceId`、`blockId`、`nodeId` 必须来自真实 media/block 返回，不能从标题或本地文件名猜测。
+- 插入成功回执在 `data.blockId` 返回已回读验证的媒体块 ID；后续定位只复用该 `blockId`。回执不提供相邻空块字段，不得据此猜测或自动删除其他块。插入回执成功后禁止重传媒体。下载必须检查 `localPath`、`sizeBytes > 0`。
+- 下载输出只接受工作目录内相对路径，默认 no-clobber。
+- 删除源文件是独立的破坏性本地操作，不属于媒体下载；只有用户明确要求且下载验证成功后才能执行。
+
+## 失败最短路径
+
+- `download_doc_attachment` 失败：保留 `nodeId/resourceId` 和服务端错误，停止。
+- 临时链接过期：重新调用 `+media-download` 获取新链接，由 CLI 内部下载。
+- 禁止把 `+fetch` 返回的临时 OSS URL 交给 `curl/wget`。
+- 禁止安装图片、Office 或 Python 依赖作为隐式降级。
+- 不得把纯数字 dentryId 当作 drive folder 重试；需要文件树定位时切换到 `dingtalk-drive` 并使用真实 dentryUuid。
+
+只有 shortcut 缺少必要的底层定位参数时，才读取精确原子 leaf Schema；不要把 `doc media insert/download` 作为默认入口。