dingtalk-doc

DingTalk Document Skill

Minimal DWS Execution Contract

• Use only dws; for structured reads add --format json, and judge by the actual return.
• Call known commands directly; when parameters/constraints/security are unclear, consult the leaf narrow Schema. Only when the Schema is unavailable, read the known leaf Help once;unknown flag correct once using the same leaf Help.unknown command Do not consult Help: prefer explicit suggestions in errors, then explicit compatible entry points in loaded Skills/references; if neither exists, report drift and stop; the full Catalog is forbidden. Low-frequency references do not default to Help; root/parent/product Help is forbidden. After discovery, execution is mandatory or the blockage must be explained.
• Do not guess commands/flags/fields/IDs/accounts/business facts; IDs come from actual returns. For zero hits/multiple candidates/unclear type on a target, disambiguate first; use contract defaults only for optional time/display scope, and stop when required information is missing.
• Parse/read/write the same profile; IDs do not cross organizations. For multiple accounts, use only the unique isOrgCurrent=true; otherwise the user specifies it, and selecting the first item, most recent login, or most recently used account is forbidden.
• Do not output/record tokens, refresh tokens, appSecret, or webhook tokens; do not request them when authentication is already injected.
• Writes must match explicit intent; confirmation is subject to the final Runtime gate/Schema, and only after confirmation add --yes。
• Verify results after writing; do not claim success based on exit codes. Exit must be the final reply, distinguishing completed, partial, blocked, pending confirmation, and failed; preserve existing data and complete/hasMore/stopReason/failures。
• Display timestamps according to the session time zone, and preserve the original value when necessary.
• For authentication/permission/profile/confirmation/unknown errors, read only the dingtalk-shared corresponding reference; repeatedly guessing substitute commands is forbidden.

Shortcut Discovery (on demand)

doc There are currently 49 public shortcuts; the complete list is kept in the Runtime Catalog and Schema and is not repeatedly expanded in the high-frequency product root Skill. Route known intents according to the section below; when parameters/constraints/security are unclear, read the leaf narrow Schema once. Only when needed and already published result check outcomes/pagination, and for field-level details check data_schema; do not infer missing information from Help/examples. Only when the Schema is unavailable, read a known leaf Help once;unknown flag correct once using the same leaf Help.unknown command Help is forbidden: error suggestion → explicit entry in loaded Skill/reference; if neither exists, report drift. Full Catalog/root/parent/product Help is forbidden; low-frequency references do not default to Help.

Only when the existing routes and references cannot locate a low-frequency capability, execute dws shortcut list --service doc --format json as the last fallback; do not load the complete Shortcut Catalog or product-level Schema for known high-frequency intents.

Golden Route

IDs/URLs are used directly; execute after a unique title match. Order: stable ID → shortcut → partial read → precise write; starting with product Schema/full text/atomic is forbidden.

User intent	Only recommended entry	Key boundaries
Locate documents by title or topic	dws doc +search --query <精确标题>	complete=true,count=0,failures=[] is authoritative zero hits: report truthfully; word abbreviation, cross-product, no query/no endpoint are forbidden --page-all
Recently accessed or recently edited documents	Load dingtalk-drive, execute dws drive +recent [--operate-type 1] --limit <N>	defaults to recently accessed,1 is recently edited; do not use doc +search Replace recent list
Given a known alidocs document directory URL, list the current level	dws doc +list --folder <URL> --page-all	Reuse the full URL; do not switch to drive +list
Given a known ID/URL, read the body or partial content	dws doc +fetch --node <ID或URL>	For terms use keyword; for sections use outline → section; only for the whole document use full
Aggregate-view info, permissions, versions, media, or comments	dws doc +inspect --node <ID或URL>	Basic metadata is returned by default; only for styles, permissions, history, media, or comments use the corresponding --include-*, no --include-info
Create a new document and write to it	dws doc +create --name <标题> --content <文本|-|@文件> [--folder <ID>|--workspace <ID>]	For a specified location reuse a real ID; the two are mutually exclusive;-=stdin, forbid @-; Runtime reads back in chunks and does not split writes
Append, overwrite, or precisely edit a block	dws doc +update --node <ID或URL> --command <动作>	Unique text str_replace; for section/block partial get ID; only for the whole document use overwrite
Important content update that needs a restore 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
Export as docx/markdown/pdf	dws doc +export --export-format <格式>	Format must be explicitly specified; for ordinary file download switch to dingtalk-drive
Convert local file to online document	dws doc +import --file <相对路径> [--folder <ID>|--workspace <ID>] [--name <文档名>]	For a specified location reuse a real ID; the two are mutually exclusive; for knowledge base use workspaceId; only when unspecified does Runtime take the default root and read back;+create Do not replace in-library import; preserve the original file only via Drive
Cover/background	+resource-update/+resource-delete；+background-update/+background-delete	After writing +inspect --include-style; do not query Catalog
Browse templates	dws doc +template-list [--source MY|PUBLIC] [--page-all]	"Mine/on my side" queries only MY; only when explicitly public query PUBLIC; for "what's available/all" add --page-all and check complete
Search templates	dws doc +template-search --query <名称或关键词>	Source can be MY/PUBLIC; stop on zero hits, do not substitute unrelated templates; disambiguate among multiple candidates
Create from template	dws doc +create-from-template --template-id <唯一ID>	Create only when a unique templateId already exists; do not repeat list/search
Create/query comments	dws doc +comment-create --node <ID或URL> --content <文字> [--selection <原文>] / +review --node <ID或URL>	node/content required; for text selection also use +comment-create; for follow-up operations reuse commentKey
Add/adjust/remove collaborator permissions	dws doc +access-grant/+access-change/+access-revoke	--to required;--role defaults to READER (READER|DOWNLOADER|EDITOR|MANAGER); none --user-ids; read permissions first; for ambiguity/profile mismatch do not write
Send link only without changing permissions	dws doc +share --to <姓名[,姓名]> --url <URL> [--note <附言>]	Built-in name resolution; use aisearch only when ambiguous; do not pre-query people; for ordinary private messages use chat
Share link with multiple people after authorization	dws doc +grant-and-share	Use only when permissions need changing (required --node, role defaults to READER); check per-person ledger and partial failures
Use file/PPT/PDF as body attachment	dws doc +media-insert --node <DOC_ID> --file <相对路径>	Body attachments go through Doc;drive +upload is only stored in the repository and will not be inserted into the body

Semantics of key results

• Preserve the real nodeId/URL/type/container; reuse ID, do not re-search by title/DingTalk drive.
• extension=dlink: for content use linkSourceInfo.nodeId; for nesting go hop by hop, stop on failure/missing/cycle; for entry movement/rename/deletion use the top-level ID.
• Reuse Runtime receipt; only for local acceptance,partial_success/commit-unknown then +fetch。
• Resume:partial_success only fills in what is unfinished;unknown Read back first, rewriting is prohibited;retryable Only when it is clearly not started; stop on permission/parameter/authentication failure.
• Report completion only when the readback matches.
• Search/list check complete/hasMore/cursor/failure items; for "all", page through to the end, and the first N items must declare their scope.
• +import Check success/verified=true and taskId/nodeId/documentUrl; reuse the returned ID, do not search again with Drive; for interruptions, check the original task, do not re-import.
• Import to the knowledge base then move to My Documents:doc +import --workspace <Wiki ID> → wiki +move-to-drive, reuse nodeId; creating first in the personal domain is prohibited.
• For export/download use a cwd-relative path;+export has localPath and sizeBytes>0 means terminal state, prohibited ls/stat。

Parameters and safety boundaries

• @file: first stage existing or temporary files to cwd; pass @相对路径, generated text prefers --content -; absolute paths and ..。
• doc +update use --command to specify the action; the block ID must come from +fetch --detail with-ids or a real list.
• Schema gate: when uncertain, query only once with the exact leaf:--fields use_when,avoid_when,parameters,constraints,confirmation; product-level/--allis prohibited. When preparing Help, query only once this round.
• Consume confirmation：user_required of this page or the exact Schema and when the original request/pre-authorization has confirmed the target, action, and parameters, add it on the first call --yes; otherwise preview/ask; probing the gate via failure is prohibited.
• The JSONML top level must be a single non-empty element; prohibiting [[...]] element array wrapping.

Load on demand

When the Golden Route already provides the command and the parameters are sufficient, reading the reference is prohibited; otherwise, read at most one reference only when encountering the semantics in the table below:

Trigger condition	Reference
Low-frequency/no-shortcut intent disambiguation	intent-guide.md / doc.md corresponding section
Pagination,partial_success、status=unknown or recovery	contracts.md
Complex JSONML, long text, or local precise read/write	create / read / update
block/selection comment/media/cover/background advanced parameters	block / comment / media
Export/import failure recovery	export / import

Routine +create、+fetch、+update append/overwrite、+export、+import reading the reference is prohibited; preloading/continuous reading is prohibited.

Shortest error path

1. Zero hits, multiple candidates, unknown type, or incomplete pagination: stop writing, show candidates or continuation; defaulting to the first item is prohibited.
2. +fetch If the target is confirmed to be a directory, the browse request reuses the full URL to execute +list --folder, do not switch to drive +list. Help does not participate in routing; first read the exact leaf Schema once. Only for real unknown flag/contract drift query leaf Help once;unknown command query the shortcut list only once, probing suffixes and dws doc --help | grep/head。
3. REVISION_CONFLICTis prohibited: re-read the current revision and show the differences; without user confirmation, do not change to overwriting without a revision.
4. doc_write_commit_unknown: read back first; automatically retrying creation or appending is prohibited.
5. Authentication, permission, or profile error: read-only dingtalk-shared corresponding reference, bypassing with low-level commands is prohibited.
6. Export/media failure: keep the stable ID and stop; network requests/installing dependencies/local document library fallback are prohibited.

Product boundaries

• Whiteboard creation/drawing/modification → whiteboard（dws whiteboard）；dws doc whiteboard only operates the card container within the document, does not modify graphics.
• Finding people by name/employee ID/department/responsibility or resolving userId → dingtalk-aisearch; only when a complete userId is already available use dingtalk-contact
• Regular file/directory storage and upload/download → dingtalk-drive; retained original files enter the specified knowledge base and become available drive +upload --workspace; "put into/attach to this document" is a body attachment → doc +media-insert; online conversion → doc +import
• Document node copy, move, template save-as → dingtalk-drive +copy/+move; the doc command of the same name is only for compatibility
• Knowledge base space, node hierarchy, and member management → dingtalk-wiki; when a local file enters a specified knowledge base, Doc +import --workspace creates a content node, and subsequent removal uses Wiki +move-to-drive
• Native .md file reading and editing → dingtalk-misc
• axls / able → corresponds to the spreadsheet or multidimensional table Skill
• Continuously listen for document events → dingtalk-misc