DingTalk Document Skill

Minimal DWS Execution Contract

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 Discovery (On Demand)

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 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

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
```
: 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

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

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

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
```
.

dingtalk-doc

NPX Install

Tags

SKILL.md Content (Chinese)