dingtalk-doc skill by dingtalk-real-ai

钉钉文档 Skill

最小 DWS 执行契约

只用 dws；结构化读取加 --format json，按真实返回判断。
已知命令直调；参数/约束/安全不明查 leaf 窄 Schema。Schema 不可用才读已知 leaf Help 一次；unknown flag 用同 leaf Help 修正一次。unknown command 不查 Help：优先错误中的明确 suggestion，其次已加载 Skill/reference 中的明确兼容入口；均无则报漂移并停，禁全 Catalog。低频 reference 不默认 Help，禁 root/parent/product Help。发现后必须执行或说明阻塞。
不猜命令/flag/字段/ID/账号/业务事实；ID 来自真实返回。目标零命中/多候选/类型不明先消歧；仅可选时间/展示范围用契约默认，缺必需信息即停。
解析/读/写同一 profile，ID 不跨组织。多账号只用唯一 isOrgCurrent=true；否则用户指定，禁止选择第一项、最近登录或最近使用账号。
不输出/记录 token、refresh token、appSecret、webhook token；已注入认证时不索要。
写须符合明确意图；确认以最终 Runtime gate/Schema 为准，确认后才加 --yes。
写后验证结果，不凭退出码宣称成功。退出须最终答复，区分完成、部分、阻塞、待确认、失败；保留已有数据及 complete/hasMore/stopReason/failures。
时间戳按会话时区展示，必要时保留原值。
认证/权限/profile/confirmation/未知错误只读 dingtalk-shared 对应 reference，禁连续猜替代命令。

Shortcut 发现（按需）

doc 当前有 49 条公开 shortcut，完整清单保留在 Runtime Catalog 与 Schema，不在高频产品根 Skill 中重复展开。已知意图按下方路由；参数/约束/安全不明时读一次 leaf 窄 Schema。仅需且已发布 result 时查 outcomes/pagination，字段级再查 data_schema；缺失不以 Help/样例推断。Schema 不可用才读一次已知 leaf Help；unknown flag 用同 leaf Help 修正一次。unknown command 禁 Help：错误 suggestion → 已加载 Skill/reference 明确入口；均无则报漂移。禁全 Catalog/root/parent/product Help；低频 reference 不默认 Help。

仅当现有路由和 reference 都无法定位低频能力时，才执行 dws shortcut list --service doc --format json 做最后回退；不要为已知高频意图加载完整 Shortcut Catalog 或产品级 Schema。

Golden Route

ID/URL 直用；标题唯一命中后执行。顺序：稳定 ID → shortcut → 局部读 → 精确写；禁以产品 Schema/全文/atomic 起步。

用户意图	唯一推荐入口	关键边界
按标题或主题定位文档	`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` 替代最近列表
已知 alidocs 文档目录 URL，列出当前层	`dws doc +list --folder <URL> --page-all`	复用完整 URL；不要改用 `drive +list`
已知 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 分片回读、不拆写
追加、覆盖或精确编辑 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`	快照/列表/回滚
导出为 docx/markdown/pdf	`dws doc +export --export-format <格式>`	格式必须显式指定;普通文件下载切 `dingtalk-drive`
本地文件转在线文档	`dws doc +import --file <相对路径> [--folder <ID>\|--workspace <ID>] [--name <文档名>]`	指定位置复用真实 ID，二者互斥；知识库用 workspaceId；未指定才由 Runtime 取默认根并回读；`+create` 不代替库内导入；仅保原文件走 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 doc +access-grant/+access-change/+access-revoke`	`--to` 必填；`--role` 默认 READER（READER\|DOWNLOADER\|EDITOR\|MANAGER）；无 `--user-ids`；先读权限，歧义/profile 不一致禁写
只发链接不改权限	`dws doc +share --to <姓名[,姓名]> --url <URL> [--note <附言>]`	内置姓名解析；仅歧义时 aisearch，禁预查人；普通私信用 chat
授权后向多人分享链接	`dws doc +grant-and-share`	仅需改权限时用（必填 `--node`，role 默认 READER）；检查逐人账本和部分失败
把文件/PPT/PDF 作为正文附件	`dws doc +media-insert --node <DOC_ID> --file <相对路径>`	正文附件走 Doc；`drive +upload` 仅入库存储，不会插入正文

关键结果语义

保留真实 nodeId/URL/类型/容器；复用 ID，禁标题/钉盘重搜。
extension=dlink：内容用 linkSourceInfo.nodeId；嵌套逐跳，失败/缺失/循环即停；入口移动/改名/删除用顶层 ID。
复用 Runtime 回执；仅局部验收、partial_success/commit-unknown 再 +fetch。
恢复：partial_success 只补未完成；unknown 先回读、禁重写；retryable 仅限明确未开始；权限/参数/认证失败即停。
回读匹配才报完成。
搜索/列表检查 complete/hasMore/cursor/失败项；“全部”翻完页，前 N 条须声明范围。
+import 检查 success/verified=true 及 taskId/nodeId/documentUrl；复用返回 ID，禁 Drive 重找；中断查原任务，禁重导。
知识库导入再移到我的文档：doc +import --workspace <Wiki ID> → wiki +move-to-drive，复用 nodeId；禁先建在个人域。
导出/下载用 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 / doc.md 对应章节
分页、`partial_success`、`status=unknown` 或恢复	contracts.md
复杂 JSONML、长文或局部精准读写	create / read / update
block/划词评论/媒体/封面/背景高级参数	block / comment / media
导出/导入失败恢复	export / import

常规 +create、+fetch、+update append/overwrite、+export、+import 禁止读取 reference；禁预加载/连读。

错误最短路径

零命中、多候选、类型不明或分页不完整：停止写入，展示候选或 continuation；禁止默认第一项。
+fetch 若确认目标是目录，浏览请求复用完整 URL 执行 +list --folder，不要改用 drive +list。Help 不参与选路；先读一次精确 leaf Schema。仅真实 unknown flag/契约漂移查一次 leaf Help；unknown command 只查一次 shortcut 清单，禁止试探后缀和 dws doc --help | grep/head。
REVISION_CONFLICT：重新读取当前 revision，展示差异；未经用户确认不得改成无 revision 覆盖。
doc_write_commit_unknown：先回读；禁止自动重试创建或追加。
认证、权限或 profile 错误：只读 dingtalk-shared 对应 reference，禁底层命令绕过。
导出/媒体失败：保留稳定 ID 后停止；禁网络请求/安装依赖/本地文档库兜底。

产品边界

白板创建/绘图/修改 → 白板（dws whiteboard）；dws doc whiteboard 仅操作文档内卡片容器，不改图形。
姓名/工号/部门/职责找人或解析 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

钉钉文档 Skill

最小 DWS 执行契约

只用 dws；结构化读取加 --format json，按真实返回判断。
已知命令直调；参数/约束/安全不明查 leaf 窄 Schema。Schema 不可用才读已知 leaf Help 一次；unknown flag 用同 leaf Help 修正一次。unknown command 不查 Help：优先错误中的明确 suggestion，其次已加载 Skill/reference 中的明确兼容入口；均无则报漂移并停，禁全 Catalog。低频 reference 不默认 Help，禁 root/parent/product Help。发现后必须执行或说明阻塞。
不猜命令/flag/字段/ID/账号/业务事实；ID 来自真实返回。目标零命中/多候选/类型不明先消歧；仅可选时间/展示范围用契约默认，缺必需信息即停。
解析/读/写同一 profile，ID 不跨组织。多账号只用唯一 isOrgCurrent=true；否则用户指定，禁止选择第一项、最近登录或最近使用账号。
不输出/记录 token、refresh token、appSecret、webhook token；已注入认证时不索要。
写须符合明确意图；确认以最终 Runtime gate/Schema 为准，确认后才加 --yes。
写后验证结果，不凭退出码宣称成功。退出须最终答复，区分完成、部分、阻塞、待确认、失败；保留已有数据及 complete/hasMore/stopReason/failures。
时间戳按会话时区展示，必要时保留原值。
认证/权限/profile/confirmation/未知错误只读 dingtalk-shared 对应 reference，禁连续猜替代命令。

Shortcut 发现（按需）

Golden Route

ID/URL 直用；标题唯一命中后执行。顺序：稳定 ID → shortcut → 局部读 → 精确写；禁以产品 Schema/全文/atomic 起步。

用户意图	唯一推荐入口	关键边界
按标题或主题定位文档	`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` 替代最近列表
已知 alidocs 文档目录 URL，列出当前层	`dws doc +list --folder <URL> --page-all`	复用完整 URL；不要改用 `drive +list`
已知 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 分片回读、不拆写
追加、覆盖或精确编辑 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`	快照/列表/回滚
导出为 docx/markdown/pdf	`dws doc +export --export-format <格式>`	格式必须显式指定;普通文件下载切 `dingtalk-drive`
本地文件转在线文档	`dws doc +import --file <相对路径> [--folder <ID>\|--workspace <ID>] [--name <文档名>]`	指定位置复用真实 ID，二者互斥；知识库用 workspaceId；未指定才由 Runtime 取默认根并回读；`+create` 不代替库内导入；仅保原文件走 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 doc +access-grant/+access-change/+access-revoke`	`--to` 必填；`--role` 默认 READER（READER\|DOWNLOADER\|EDITOR\|MANAGER）；无 `--user-ids`；先读权限，歧义/profile 不一致禁写
只发链接不改权限	`dws doc +share --to <姓名[,姓名]> --url <URL> [--note <附言>]`	内置姓名解析；仅歧义时 aisearch，禁预查人；普通私信用 chat
授权后向多人分享链接	`dws doc +grant-and-share`	仅需改权限时用（必填 `--node`，role 默认 READER）；检查逐人账本和部分失败
把文件/PPT/PDF 作为正文附件	`dws doc +media-insert --node <DOC_ID> --file <相对路径>`	正文附件走 Doc；`drive +upload` 仅入库存储，不会插入正文

关键结果语义

保留真实 nodeId/URL/类型/容器；复用 ID，禁标题/钉盘重搜。
extension=dlink：内容用 linkSourceInfo.nodeId；嵌套逐跳，失败/缺失/循环即停；入口移动/改名/删除用顶层 ID。
复用 Runtime 回执；仅局部验收、partial_success/commit-unknown 再 +fetch。
恢复：partial_success 只补未完成；unknown 先回读、禁重写；retryable 仅限明确未开始；权限/参数/认证失败即停。
回读匹配才报完成。
搜索/列表检查 complete/hasMore/cursor/失败项；“全部”翻完页，前 N 条须声明范围。
+import 检查 success/verified=true 及 taskId/nodeId/documentUrl；复用返回 ID，禁 Drive 重找；中断查原任务，禁重导。
知识库导入再移到我的文档：doc +import --workspace <Wiki ID> → wiki +move-to-drive，复用 nodeId；禁先建在个人域。
导出/下载用 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 / doc.md 对应章节
分页、`partial_success`、`status=unknown` 或恢复	contracts.md
复杂 JSONML、长文或局部精准读写	create / read / update
block/划词评论/媒体/封面/背景高级参数	block / comment / media
导出/导入失败恢复	export / import

常规 +create、+fetch、+update append/overwrite、+export、+import 禁止读取 reference；禁预加载/连读。

错误最短路径

零命中、多候选、类型不明或分页不完整：停止写入，展示候选或 continuation；禁止默认第一项。
+fetch 若确认目标是目录，浏览请求复用完整 URL 执行 +list --folder，不要改用 drive +list。Help 不参与选路；先读一次精确 leaf Schema。仅真实 unknown flag/契约漂移查一次 leaf Help；unknown command 只查一次 shortcut 清单，禁止试探后缀和 dws doc --help | grep/head。
REVISION_CONFLICT：重新读取当前 revision，展示差异；未经用户确认不得改成无 revision 覆盖。
doc_write_commit_unknown：先回读；禁止自动重试创建或追加。
认证、权限或 profile 错误：只读 dingtalk-shared 对应 reference，禁底层命令绕过。
导出/媒体失败：保留稳定 ID 后停止；禁网络请求/安装依赖/本地文档库兜底。

产品边界

白板创建/绘图/修改 → 白板（dws whiteboard）；dws doc whiteboard 仅操作文档内卡片容器，不改图形。
姓名/工号/部门/职责找人或解析 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

dingtalk-doc

Documentation

Documentation

钉钉文档 Skill

最小 DWS 执行契约

Shortcut 发现（按需）

Golden Route

关键结果语义

参数与安全边界

按需加载

错误最短路径

产品边界

Documentation

dingtalk-doc

Documentation

钉钉文档 Skill

最小 DWS 执行契约

Shortcut 发现（按需）

Golden Route

关键结果语义

参数与安全边界

按需加载

错误最短路径

产品边界