dingtalk-doc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

钉钉文档 Skill

DingTalk Document Skill

最小 DWS 执行契约

Minimal DWS Execution Contract

只用
```
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，禁连续猜替代命令。

Use only
```
dws
```
; add
```
--format json
```
for structured reads, and judge based on actual returns.
Directly call known commands; if parameters/constraints/security are unclear, consult the leaf narrow Schema. Only read the known leaf Help once if Schema is unavailable; fix
```
unknown flag
```
once with the same leaf Help. For
```
unknown command
```
, do not check Help: prioritize explicit suggestions in the error, then explicit compatible entries in loaded Skills/references; if none, report drift and stop, and prohibit full Catalog searches. Low-frequency references do not default to Help; prohibit root/parent/product Help. Once discovered, execute or explain the blockage.
Do not guess commands/flags/fields/IDs/accounts/business facts; IDs come from actual returns. Disambiguate first for zero hits/multiple candidates/unclear types; use contract defaults only for optional time/display ranges, and stop if required information is missing.
Parse/read/write the same profile; do not cross organizations with IDs. For multiple accounts, use only the unique
```
isOrgCurrent=true
```
; otherwise user-specified, and prohibit selecting the first item, most recently logged-in, or most recently used account.
Do not output/record token, refresh token, appSecret, webhook token; do not request authentication when already injected.
Writes must conform to explicit intent; confirmation is based on the final Runtime gate/Schema; add
```
--yes
```
only after confirmation.
Verify results after writes; do not claim success based on exit codes. Exit with a final response distinguishing completed, partial, blocked, pending confirmation, failed; preserve existing data and
```
complete/hasMore/stopReason/failures
```
.
Display timestamps in the session timezone, preserving original values when necessary.
For authentication/permissions/profile/confirmation/unknown errors, only read the corresponding reference in
```
dingtalk-shared
```
; prohibit guessing alternative commands repeatedly.

Shortcut 发现（按需）

Shortcut Discovery (On Demand)

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。

doc

currently has 49 public shortcuts; the full list is kept in the Runtime Catalog and Schema and is not expanded again in the high-frequency product root Skill. Route known intents as below; read the leaf narrow Schema once when parameters/constraints/security are unclear. Only when needed and

result

is published, check outcomes/pagination; for field-level, check

data_schema

; do not infer from Help/samples if missing. Only read the known leaf Help once if Schema is unavailable; fix

unknown flag

once with the same leaf Help. For

unknown command

, prohibit Help: error suggestion → explicit entry in loaded Skills/references; if none, report drift. Prohibit full Catalog/root/parent/product Help; low-frequency references do not default to Help.

Only when existing routes and references cannot locate a low-frequency capability, execute

dws shortcut list --service doc --format json

as a last resort; do not load the full Shortcut Catalog or product-level Schema for known high-frequency intents.

Golden Route

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

用户意图	唯一推荐入口	关键边界
<!-- 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` 替代最近列表
已知 alidocs 文档目录 URL，列出当前层	`dws doc +list --folder <URL> --page-all`	复用完整 URL；不要改用 `drive +list`
<!-- 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 取默认根并回读； `+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-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` 仅入库存储，不会插入正文

ID/URL direct use; execute after unique title hit. Order: stable ID → shortcut → local read → precise write; do not start with product Schema/full text/atomic.

User Intent	Unique Recommended Entry	Key Boundaries
<!-- dws-intent: doc.search.by_title -->Locate a document by title or topic	`dws doc +search --query <exact title>`	`complete=true,count=0,failures=[]` indicates authoritative zero hits: report as-is; do not narrow terms, cross products, or use `--page-all` without query/justification.
Recently accessed or recently edited documents	Load `dingtalk-drive` , run `dws drive +recent [--operate-type 1] --limit <N>`	Default is recently accessed, `1` for recently edited; do not use `doc +search` to replace the recent list.
Known alidocs folder URL, list current level	`dws doc +list --folder <URL> --page-all`	Reuse the full URL; do not switch to `drive +list` .
<!-- dws-intent: doc.content.read -->Read body or partial content with known ID/URL	`dws doc +fetch --node <ID or URL>`	Use `keyword` for terminology; `outline` for sections → `section` ; use `full` only for the entire document.
Aggregated view of info, permissions, versions, media, or comments	`dws doc +inspect --node <ID or URL>`	Basic metadata is returned by default; use corresponding `--include-*` only for style, permissions, history, media, comments; there is no `--include-info` .
Create a document and write content	`dws doc +create --name <title> --content <text\	-\
<!-- dws-intent: doc.content.update -->Append, overwrite, or precisely edit blocks	`dws doc +update --node <ID or URL> --command <action>`	Unique text `str_replace` ; use IDs for sections/blocks locally; overwrite only for entire document.
Important content update requiring a recovery point	`dws doc +checkpoint-update`	Auto-save version, update and read back; check `steps` and `compensation` .
Version operations	`dws doc +version-save --node` / `dws doc +version-list --node` / `dws doc +version-revert --node --version`	Snapshot/List/Rollback.
<!-- dws-intent: doc.export.format -->Export to docx/markdown/pdf	`dws doc +export --export-format <format>`	Format must be explicitly specified; switch to `dingtalk-drive` for ordinary file downloads.
<!-- dws-intent: doc.import.local_file -->Convert local file to online document	`dws doc +import --file <relative path> [--folder <ID>\	--workspace <ID>] [--name <document name>]`
Cover/background	`+resource-update/+resource-delete` ； `+background-update/+background-delete`	After writing, `+inspect --include-style` ; prohibit Catalog queries.
Browse templates	`dws doc +template-list [--source MY\	PUBLIC] [--page-all]`
Search templates	`dws doc +template-search --query <name or keyword>`	Source optional MY/PUBLIC; stop on zero hits, do not substitute unrelated templates; disambiguate multiple candidates.
Create from template	`dws doc +create-from-template --template-id <unique ID>`	Create only when a unique templateId exists; do not repeat list/search.
Create/view comments	`dws doc +comment-create --node <ID or URL> --content <text> [--selection <original text>]` / `+review --node <ID or URL>`	node/content required; use `+comment-create` for selection comments; reuse `commentKey` for follow-up operations.
<!-- dws-intent: doc.access.grant -->Add/adjust/remove collaborator permissions	`dws doc +access-grant/+access-change/+access-revoke`	`--to` required; `--role` defaults to READER (READER\
<!-- dws-intent: doc.share.link_only -->Share link only without changing permissions	`dws doc +share --to <name[,name]> --url <URL> [--note <note>]`	Built-in name resolution; use aisearch only for ambiguity, do not pre-query people; use chat for ordinary private messages.
Share link with multiple people after granting permissions	`dws doc +grant-and-share`	Use when only permission changes are needed ( `--node` required, role defaults to READER); check per-person ledger and partial failures.
<!-- dws-intent: doc.media.insert -->Insert file/PPT/PDF as body attachment	`dws doc +media-insert --node <DOC_ID> --file <relative path>`	Body attachments go through Doc; `drive +upload` only stores in Drive, does not insert into body.

关键结果语义

Key Result Semantics

保留真实
```
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
```
。

Preserve the real
```
nodeId
```
/URL/type/container; reuse IDs, do not re-search by title or DingTalk Drive.
```
extension=dlink
```
: use
```
linkSourceInfo.nodeId
```
for content; nested traversal, stop on failure/missing/loop; use top-level ID for entry moves/renames/deletes.
Reuse Runtime receipts; only perform
```
+fetch
```
again for partial acceptance,
```
partial_success
```
/commit-unknown.
Recovery:
```
partial_success
```
only completes unfinished items;
```
unknown
```
reads back first, prohibits rewriting;
```
retryable
```
only for explicitly not started; stop on permission/parameter/authentication failures.
Report completion only when read-back matches.
For search/list, check
```
complete
```
/
```
hasMore
```
/cursor/failures; for "all", page through, and declare scope for the first N items.
For
```
+import
```
, check
```
success/verified=true
```
and
```
taskId/nodeId/documentUrl
```
; reuse returned IDs, do not re-find via Drive; if interrupted, check the original task, do not re-import.
For knowledge base import then move to My Documents:
```
doc +import --workspace <Wiki ID>
```
→
```
wiki +move-to-drive
```
, reusing nodeId; do not create in personal domain first.
Use cwd relative paths for export/download;
```
+export
```
with
```
localPath
```
and
```
sizeBytes>0
```
is final, do not use
```
ls/stat
```
.

参数与安全边界

Parameter and Security Boundaries

```
@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 顶层必须是单个非空元素；禁止
```
[[...]]
```
元素数组包裹。

```
@file
```
: stage existing or temporary files to cwd first; pass
```
@relative path
```
, prefer
```
--content -
```
for generated text; prohibit absolute paths and
```
..
```
.
```
doc +update
```
uses
```
--command
```
to specify the action; block IDs must come from
```
+fetch --detail with-ids
```
or actual lists.
Schema gate: only query the precise leaf once when uncertain:
```
--fields use_when,avoid_when,parameters,constraints,confirmation
```
; disable product-level/
```
--all
```
. When preparing Help, query only once in this turn.
Consume
```
confirmation
```
from this page or precise Schema: if
```
user_required
```
and the original request/pre-authorization has confirmed the target, action, and parameters, add
```
--yes
```
on the first call; otherwise preview/ask; do not probe the gate via failures.
JSONML top-level must be a single non-empty element; prohibit wrapping with
```
[[...]]
```
element arrays.

按需加载

On-Demand Loading

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；禁预加载/连读。

When the Golden Route has provided commands and parameters, reading references is prohibited; otherwise, read at most one reference only when encountering the following semantics:

Trigger Condition	Reference
Low-frequency/no shortcut intent disambiguation	intent-guide.md / doc.md corresponding sections
Pagination, `partial_success` , `status=unknown` , or recovery	contracts.md
Complex JSONML, long texts, or precise local read/write	create / read / update
Advanced parameters for block/selection comments/media/cover/background	block / comment / media
Export/import failure recovery	export / import

For routine

+create

+fetch

+update

append/overwrite,

+export

+import

, reading references is prohibited; do not preload/chain-read.

错误最短路径

Shortest Error Path

零命中、多候选、类型不明或分页不完整：停止写入，展示候选或 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 后停止；禁网络请求/安装依赖/本地文档库兜底。

Zero hits, multiple candidates, unclear types, or incomplete pagination: stop writing, show candidates or continuation; prohibit defaulting to the first item.
If
```
+fetch
```
confirms the target is a folder, for browse requests reuse the full URL and run
```
+list --folder
```
, do not switch to
```
drive +list
```
. Help does not participate in routing; read the precise leaf Schema once first. Only for real
```
unknown flag
```
/contract drift, check leaf Help once; for
```
unknown command
```
, check the shortcut list only once, and do not probe suffixes or
```
dws doc --help | grep/head
```
.
```
REVISION_CONFLICT
```
: re-read the current revision, show differences; do not change to overwriting without revision without user confirmation.
```
doc_write_commit_unknown
```
: read back first; do not automatically retry creation or append.
Authentication, permission, or profile errors: only read the corresponding
```
dingtalk-shared
```
reference, do not bypass with low-level commands.
Export/media failure: preserve stable ID and stop; do not use network requests/install dependencies/local document library as fallback.

产品边界

Product Boundaries

姓名/工号/部门/职责找人或解析 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
```

For finding people or resolving userId by name/employee ID/department/role →
```
dingtalk-aisearch
```
; use
```
dingtalk-contact
```
only when a full userId exists and details are needed.
For ordinary file/directory storage and upload/download →
```
dingtalk-drive
```
; when keeping original files into a specific knowledge base, use
```
drive +upload --workspace
```
; "put into/attach to this document" means body attachment →
```
doc +media-insert
```
; online conversion →
```
doc +import
```
.
For copying, moving document nodes, saving templates →
```
dingtalk-drive +copy/+move
```
; doc's same-name commands are only for compatibility.
For knowledge base spaces, node hierarchy, and member management →
```
dingtalk-wiki
```
; when local files enter a specific knowledge base, Doc
```
+import --workspace
```
creates the content node, and use Wiki
```
+move-to-drive
```
for later removal.
For native
```
.md
```
file reading and editing →
```
dingtalk-misc
```
.
```
axls
```
/
```
able
```
→ corresponding spreadsheet or multidimensional table Skills.
For continuous monitoring of document events →
```
dingtalk-misc
```
.