DingTalk Drive

Minimal DWS Execution Contract

Use only
```
dws
```
; add
```
--format json
```
for structured reads and judge by actual returns.
Call known commands directly; when parameters/constraints/safety are unclear, consult the leaf narrow Schema. Only if the Schema is unavailable, read the known leaf Help once;
```
unknown flag
```
can be corrected once with the same leaf Help. For
```
unknown command
```
, do not consult Help: first use the explicit suggestion in the error, then any clear compatible entry in the loaded Skill/reference; if neither exists, report drift and stop. Full Catalog is forbidden. Low-frequency references do not default to Help; root/parent/product Help is forbidden. Once found, you must execute it or explain the blocker.
Do not guess commands/flags/fields/IDs/accounts/business facts; IDs come from real returns. If the target has zero hits/multiple candidates/ambiguous type, disambiguate first; use contract defaults only for optional time/display scope; stop if required information is missing.
Parse/read/write with the same profile; IDs do not cross organizations. With multiple accounts, use only the unique
```
isOrgCurrent=true
```
account; otherwise the user must specify. Never choose the first item, the most recently logged-in account, or the most recently used account.
Do not output/record token, refresh token, appSecret, or webhook token; if authentication is already injected, do not ask for it.
Writes must match explicit intent; confirmation is determined by the final Runtime gate/Schema; add
```
--yes
```
only after confirmation.
Verify results after writes; never claim success based solely on the exit code. Exit with a final answer that distinguishes completed, partial, blocked, pending confirmation, and failed; preserve existing data and
```
complete/hasMore/stopReason/failures
```
.
Display timestamps in the session timezone, preserving original values when necessary.
For authentication/permission/profile/confirmation/unknown errors, only read the corresponding
```
dingtalk-shared
```
reference; do not keep guessing alternative commands.

Shortcut Discovery (On Demand)

drive

currently has 28 public shortcuts; the full list is kept in the Runtime Catalog and Schema, not repeated in the high-frequency product root Skill. Route known intents as below; when parameters/constraints/safety are unclear, read a leaf narrow Schema once. If only

result

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

data_schema

; do not infer missing fields from Help/examples. If the Schema is unavailable, read the known leaf Help once;

unknown flag

can be corrected once with the same leaf Help. For

unknown command

, Help is forbidden: error suggestion → clear 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 current routes and references cannot locate a low-frequency capability, run

dws shortcut list --service drive --format json

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

Golden Route

User Intent	Unique Recommended Entry	Key Boundaries
Find files globally by name or keyword	`dws drive +search --query <keyword> --page-all --max-pages 20 --max-items 500`	Auto-paginate when a full search is needed; omit `--page-all` if only the first batch is needed; stop on multiple candidates; online document full-text search goes through `doc +search`
Browse root directory or a known folder	`dws drive +list [--folder <dentryUuid>] --page-all --max-pages 20 --max-items 500`	Auto-paginate when full browsing is needed; omit `--page-all` if only the first batch is needed
Discover a DingTalk Drive org space or “My Files” space	`dws wiki space list --type <orgSpace\|mySpace> --format json`	Drive read-only prerequisite; orgSpace paginates by nextToken; return to Drive after taking spaceId/rootFolderId
<!-- dws-intent: drive.recent.documents -->View recently accessed/edited document list	`dws drive +recent [--operate-type 1] --limit <N>`	1=recently edited; default is recently accessed; use directly when there are no topic, person, direction, or action conditions
View node type and metadata	`dws drive +inspect --node <dentryUuid>`	Add stats/publish/cover as needed; do not force for ordinary lists
Download an ordinary file	`dws drive +download --node <dentryUuid> --output <relative path>`	Current shortcut accepts an ID; for online documents use `doc +export`
Get only a temporary download URL without writing to disk	`dws drive download --node <dentryUuid> --url-only --format json`	Use when the Agent sandbox/external system downloads itself; mutually exclusive with disk-writing parameters such as `--output/--overwrite`
Upload an ordinary file to DingTalk Drive or knowledge base	`dws drive +upload --file <relative path> [--workspace <ID>]`	Defaults to DingTalk Drive; with `--workspace` specified, it becomes a standalone file node in the knowledge base/document space; `folder` is mutually exclusive with `node` , and `workspace` is mutually exclusive with `space-id`
Manage global comments on ordinary files	`dws drive comment list-v2/create-v2/reply/update/delete/batch-query/list-replies/resolve/restore/react-reply`	Reuses the new Doc/Sheet comment chain; old `list/create` are deprecated; fixed to whole-file `global` ; does not support selected text, cells, or mentions
Create a folder	`dws drive +create-folder --name <name> [--folder <ID>]`	Shortcut is submitted and read back
Create an independent copy of an ordinary file	`dws drive +download --node <source ID> --output <relative path>` → `dws drive +upload --file <same relative path> [--folder <target ID>]`	Execute after user authorization; do not try `+copy` when the node is known to be an ordinary file; pass no `--node` on the new upload to avoid overwriting; completion evidence follows the copy rule below
Copy an online document node	`dws drive +copy --node <ID> [--folder <target ID>]`	Ordinary DingTalk Drive files are rejected; Base struct copy goes through AITable `+base-copy --base-id <ID> --target-folder-id <actual ID> --only-struct`
Move a node	`dws drive +move --node <ID> --folder <target ID>`	Destructive change; follow Runtime confirmation
Rename a node	`dws drive +rename --node <ID> --name <new name>`	Check the final name after writing
Compare local and DingTalk Drive folders	`dws drive status --local-folder <absolute path> --remote-folder <folderId>`	Read-only; exact MD5 by default; no pull or push first
Pull a DingTalk Drive folder to local	`dws drive pull --local-folder <absolute path> --remote-folder <folderId> --if-exists skip`	Safe default: no overwrite; first run `--dry-run` with the same parameters, then execute after confirmation
Push a local folder to DingTalk Drive	`dws drive push --local-folder <absolute path> --remote-folder <folderId> --if-exists skip`	Safe default: no overwrite; dry-run first; will not delete extra remote files
Two-way reconcile folders	`dws drive sync --local-folder <absolute path> --remote-folder <folderId> --on-conflict skip`	dry-run first; conflict policy must be explicitly retained

Ordinary file copy rule: reuse the node type and source ID from a reliable existing receipt; if the type is unclear, inspect first—do not use a failed copy to probe the type. After a successful download, create a new upload at the user-authorized target location; confirm the returned new node ID differs from the source ID, and verify name, size, or content as required by the task. Merely providing operation instructions does not count as creating a copy; this path does not promise copying permissions, version history, or other online collaboration metadata.

Low-Frequency Entry Points

Delete a confirmed node:

dws drive +delete --node <dentryUuid>

; restore:

+recycle-list/+recycle-restore

; versions:

+version-history/+version-get/+version-download/+version-revert

Star:
```
+star-*
```
; publishing state:
```
+publish-get/+publish-unset
```
(
```
+publish-set
```
is not on the Agent route); stats/cover use
```
+inspect
```
; shortcuts use
```
+create-shortcut
```
.
Directory trees are traversed only with bounded
```
+list
```
, level by level.

Compatibility aliases do not affect routing:

+info

→

+inspect

+find-file

→

+search

+search-docs

→

doc +search

Current Shortest Path

With a known dentryUuid: run inspect/download/list/move/rename directly; never search first; run copy only after confirming the node is a supported online document node.
If the task explicitly asks to create an online document from a local file in a new knowledge base, then move it to My Documents, it is not a Drive root-directory cleanup: do not pre-query
```
mySpace/rootFolderId
```
, and do not use
```
doc +create
```
followed by
```
drive +move
```
; instead, let Wiki create the space, then Doc
```
+import --workspace <new workspaceId>
```
, then Wiki
```
+move-to-drive --workspace <new workspaceId>
```
.
When the current command needs to locate a space and lacks a target ID: first determine whether it is an org space
```
orgSpace
```
or “My Files”
```
mySpace
```
, and discover the space with
```
dws wiki space list --type <type> --format json
```
; continue paginating orgSpace with
```
--cursor <nextToken>
```
when
```
nextToken
```
is non-empty, while mySpace is always a single entry and not paginated. Take the real spaceId or rootFolderId for the subsequent command and immediately return to Drive; do not discover spaces when these IDs are already known.
Name only:
```
+search
```
→ the unique candidate's nodeId → target command; never automatically select the first item.
Folder hierarchy only: start
```
+list
```
from the nearest known folder ID; do not do unbounded recursion from the root.
Upload an ordinary file: a single
```
+upload
```
; explicitly add
```
--workspace
```
for a knowledge base/document space target; do not fall back to upload-info + handwritten HTTP + commit. To convert to an online document, use Doc
```
+import
```
; to insert a body attachment, use Doc
```
+media-insert
```
.
Upload after export: specify the final local file name in the first
```
doc +export
```
, directly reuse the
```
localPath
```
receipt, and run the first formal
```
drive +upload
```
with the pre-authorized
```
--yes
```
; do not rename after upload.
When copy/move/rename/create-folder already include a post-write read-back, the Agent must not run
```
+inspect
```
again.
Rename a known nodeId directly with
```
+rename
```
; don't start with Catalog, Help, or search; ALIDOC logical titles are verified by the shortcut's internal document read-back.
When the folder direction is clear, go directly to
```
status/pull/push/sync
```
; don't run status first. For write operations, first dry-run with identical parameters, then execute formally.
After a search result with
```
type=able
```
, reroute by business verb: struct copy/delete/Base-internal operations go to AITable. For struct copy, provide the source Base ID and the real
```
--target-folder-id
```
per the current leaf; stop if the target ID is missing; do not guess a root ID or invent
```
--target-root
```
.
```
+inspect/+download/+list
```
only guarantee a dentryUuid; when only a URL is available, first parse and verify
```
result.fileId
```
(i.e., dentryUuid) with
```
dws drive info --node <URL> --format json
```
.
When
```
drive info
```
returns
```
extension=dlink
```
, save
```
result.fileId
```
as the shortcut entry ID and first read
```
linkSourceInfo
```
with
```
dws doc info --node <result.fileId> --format json
```
. Content reads, edits, exports, and type routing then use the target
```
linkSourceInfo.nodeId
```
; if the target is still a dlink, resolve hop by hop and record visited IDs, stopping on resolution failure, missing fields, or repeated IDs. Use the original
```
result.fileId
```
when the user explicitly moves, renames, or deletes the shortcut entry itself.

The shortest path does not omit type checks, confirmation, transfer verification, or post-write validation.

Key Result Semantics

Full queries of
```
+list/+search/+recent
```
uniformly use
```
--page-all --max-pages <N> --max-items <N>
```
and check collection, completeness, and truncation state; omit
```
--page-all
```
when only the first batch is needed. A missing collection must not be treated as an empty result; multiple candidates must not default to the first item.
```
+download
```
verifies the relative path exists and
```
sizeBytes > 0
```
;
```
+upload
```
checks the final nodeId and full name. Normal Drive targets must validate the read-back size; when
```
--workspace
```
is specified, verify the workspaceId and tolerate the real contract of
```
doc/get_document_info
```
, which splits the full name into
```
name + extension
```
and does not return size; if it does return size, it must match the local file. Only compare checksums when both the source and result provide comparable hashes; if missing, preserve existing evidence and do not fabricate end-to-end checksums.
copy/move/rename/create-folder check
```
ok/outcome
```
and read-back;
```
partial_success
```
is not completion.
status checks categorized result sets; pull/push/sync check the summary and per-item results;
```
failed
```
/
```
unknown
```
must be preserved.
Return a continuation when pagination is not finished; directory trees or large lists must have max depth, page count, and item count.
When continuing pagination on the same query, if
```
nextCursor
```
repeats and no new nodes are added, stop further paging, keep the acquired results, and report pagination as incomplete; do not count duplicate results as new.
If a write effect is unknown, read back via inspect/list first; do not blindly replay writes.

Parameters and Safety Boundaries

```
--node
```
and
```
--folder
```
use dentryUuid/fileId, not numeric dentryId; recycle bin restore uses
```
recycleItemId
```
.
```
+list --limit
```
has a maximum of 50;
```
+search --limit
```
has a maximum of 30. Exceed by paging, not by repeatedly trying invalid parameters.
Write operations determine confirmation only by the exact leaf Runtime; when a specific object, action, and impact are clearly authorized, include
```
--yes
```
on the first formal execution; otherwise confirm first. Do not include it for previews; reconfirm when parameters change; never use a failure caused by a missing
```
--yes
```
as a probe.
Before overwriting an ordinary file, confirm the real type and original name;
```
adoc
```
/
```
axls
```
/
```
able
```
are not overwritten as ordinary files.
Single-file Shortcut local input/output uses cwd-relative paths and forbids
```
..
```
; folder
```
status/pull/push/sync
```
uses absolute
```
--local-folder
```
per the leaf contract.
Folder sync defaults to exact MD5; use
```
--quick
```
only when the user accepts timestamp approximation, and it will not delete extra files on either side.
When uncertain about parameters, check the exact leaf Schema once; product-level Schema is forbidden.

On-Demand Loading

When Golden Route parameters are sufficient, reading references is forbidden. Otherwise, read at most one exact reference:

Trigger condition	Reference
URL, file type, or cross-product boundary	intent-guide
Folder compare, pull, push, or two-way sync	folder-sync
Low-frequency permissions, versions, recycle bin, publishing state	corresponding section in drive reference
Document queries, import, and template-preserving workflows	lite-recipes

Error Shortest Path

Zero/multiple candidates, unclear type, or incomplete pagination: stop writing and return candidates or continuation; paginated reads may continue within a valid cursor and budget.
```
unknown flag
```
: check the current leaf Help once;
```
unknown command
```
: check the Drive shortcut list once.
An ordinary download hits an online document type: switch to
```
doc +export
```
; do not retry Drive download.
Transfer interrupted: preserve local temporary state or checkpoint; first determine whether resumption is possible.
Unknown write effect: read back by nodeId; report
```
unknown
```
if it cannot be proven.
When the node is known to be an ordinary file and an independent copy is needed, execute the Golden Route download→upload directly; do not use a failed
```
+copy
```
as a prerequisite probe. If an error still says copy is unsupported for ordinary files, do not retry or claim completion; confirm authorization and target, then continue according to the copy rule. Stop AITable struct copy when the target folder is missing or cannot be verified; do not guess IDs or create test folders.

Cross-Product Boundaries

Storage management of ordinary files/folders and online document nodes → Drive; putting a file as an attachment in a document body uses Doc
```
+media-insert
```
; other body/content paths use Doc, Sheet, and AITable respectively.
Outer move/rename of
```
able
```
uses Drive; struct copy, Base deletion (
```
+base-delete
```
), and Base-internal operations use AITable.
Explicit knowledge base workspace hierarchy → Wiki; generic “Document Space/My Documents” usually goes through Drive, but “move a node out of a Wiki library to My Documents” is always completed by Wiki
```
+move-to-drive
```
; Drive does not pre-query
```
mySpace
```
or take over that move.
DingTalk Drive storage space discovery exceptionally reuses managed
```
dws wiki space list --type orgSpace|mySpace
```
; take the real spaceId/rootFolderId and return to Drive. spaceId is used as the space parameter; only rootFolderId can be used as the space root folder.
```
orgWikiSpace/myWikiSpace
```
return workspaceId and must not be mixed into Drive parameters.
Convert Word/Markdown/Text to online documents with
```
doc +import
```
; Drive upload keeps only the original file.

dingtalk-drive

NPX Install

Tags

SKILL.md Content (Chinese)