dingtalk-drive

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

钉盘

DingTalk Drive

最小 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 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 发现（按需）

Shortcut Discovery (On Demand)

drive

当前有 28 条公开 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 drive --format json

做最后回退；不要为已知高频意图加载完整 Shortcut Catalog 或产品级 Schema。

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

用户意图	唯一推荐入口	关键边界
全局按名称或关键词找文件	`dws drive +search --query <关键词> --page-all --max-pages 20 --max-items 500`	需要完整搜索时自动翻页；只需首批结果时可不加 `--page-all` ；多候选停止；在线文档正文搜索走 `doc +search`
浏览根目录或已知文件夹	`dws drive +list [--folder <dentryUuid>] --page-all --max-pages 20 --max-items 500`	需要完整浏览时自动翻页；只需首批结果时可不加 `--page-all`
发现钉盘企业空间或“我的文件”空间	`dws wiki space list --type <orgSpace\|mySpace> --format json`	Drive 只读前置；orgSpace 按 nextToken 续页，取 spaceId/rootFolderId 后回到 Drive
<!-- dws-intent: drive.recent.documents -->查看最近访问/编辑文档列表	`dws drive +recent [--operate-type 1] --limit <N>`	1=最近编辑；默认最近访问；无主题、人物、方向或动作条件时直接使用
查看节点类型和元数据	`dws drive +inspect --node <dentryUuid>`	按需加 stats/publish/cover，不为普通列表强制调用
下载普通文件	`dws drive +download --node <dentryUuid> --output <相对路径>`	当前 shortcut 接受 ID；在线文档用 `doc +export`
只要临时下载地址不落盘	`dws drive download --node <dentryUuid> --url-only --format json`	Agent 沙箱/外部系统自行下载时用；与 `--output/--overwrite` 等落盘参数互斥
上传普通文件到钉盘或知识库	`dws drive +upload --file <相对路径> [--workspace <ID>]`	默认进钉盘；指定 workspace 时成为知识库/文档空间中的独立文件节点；folder 与 node、workspace 与 space-id 分别互斥
管理普通文件全局评论	`dws drive comment list-v2/create-v2/reply/update/delete/batch-query/list-replies/resolve/restore/react-reply`	复用 Doc/Sheet 新评论链路；旧 `list/create` 已 deprecated；固定全文 `global` ，不支持划词、单元格或 mention
创建文件夹	`dws drive +create-folder --name <名称> [--folder <ID>]`	Shortcut 已提交并读回
创建普通文件的独立副本	`dws drive +download --node <源ID> --output <相对路径>` → `dws drive +upload --file <同一相对路径> [--folder <目标ID>]`	经用户授权后执行；已知是普通文件时不试 `+copy` ；新建上传不传 `--node` ，避免覆盖；完成证据见下方副本规则
复制在线文档节点	`dws drive +copy --node <ID> [--folder <目标ID>]`	普通钉盘文件会被拒绝；Base 结构复制走 AITable `+base-copy --base-id <ID> --target-folder-id <真实ID> --only-struct`
移动节点	`dws drive +move --node <ID> --folder <目标ID>`	破坏性变更，按 Runtime confirmation
重命名节点	`dws drive +rename --node <ID> --name <新名称>`	写后检查最终名称
比较本地与钉盘文件夹	`dws drive status --local-folder <绝对路径> --remote-folder <folderId>`	只读；默认精确 MD5，不先拉取或推送
钉盘文件夹拉到本地	`dws drive pull --local-folder <绝对路径> --remote-folder <folderId> --if-exists skip`	安全默认不覆盖；先以相同参数 `--dry-run` ，再按确认执行
本地文件夹推到钉盘	`dws drive push --local-folder <绝对路径> --remote-folder <folderId> --if-exists skip`	安全默认不覆盖；先 dry-run；不会删除远端多余文件
双向补齐文件夹	`dws drive sync --local-folder <绝对路径> --remote-folder <folderId> --on-conflict skip`	先 dry-run；冲突策略必须显式保留

普通文件副本规则：复用已有可靠回执中的节点类型和源 ID；类型不明时先 inspect，不用失败的 copy 探测类型。下载成功后，按用户授权的目标位置新建上传；确认返回的新节点 ID 与源 ID 不同，并按任务要求核对名称、大小或内容。只给出操作说明不算已创建副本；该路径不承诺复制权限、版本历史或其他在线协作元数据。

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

删除已确认节点：

dws drive +delete --node <dentryUuid>

；恢复：

+recycle-list/+recycle-restore

；版本：

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

。

收藏：
```
+star-*
```
；公开状态：
```
+publish-get/+publish-unset
```
（
```
+publish-set
```
不进入 Agent 路由）；统计/封面用
```
+inspect
```
；快捷方式用
```
+create-shortcut
```
。
目录树只用有界
```
+list
```
逐层遍历。

兼容别名不选路：

+info

→

+inspect

，

+find-file

→

+search

，

+search-docs

→

doc +search

。

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

已知 dentryUuid：直接执行 inspect/download/list/move/rename，禁止先 search；仅确认是受支持的在线文档节点后才执行 copy。
任务若明确要求“在新知识库用本地文件建在线文档，再移到我的文档”，不属于 Drive 根目录整理：禁止预查
```
mySpace/rootFolderId
```
，禁止
```
doc +create
```
后
```
drive +move
```
；应由 Wiki 创建空间，Doc
```
+import --workspace <新workspaceId>
```
，再 Wiki
```
+move-to-drive --workspace <新workspaceId>
```
。
当前命令需要定位空间且缺少目标 ID 时：先明确企业空间
```
orgSpace
```
或“我的文件”
```
mySpace
```
，用
```
dws wiki space list --type <类型> --format json
```
发现空间；
```
orgSpace
```
在
```
nextToken
```
非空时以
```
--cursor <nextToken>
```
续页，
```
mySpace
```
固定单条且不分页。按后续命令取真实 spaceId 或 rootFolderId 后立即回到 Drive；已知这些 ID 时不做空间发现。
只有名称：
```
+search
```
→ 唯一候选的 nodeId → 目标命令；不得自动选择第一项。
只有文件夹层级：从最近的已知 folder ID 开始
```
+list
```
，不要从根目录无界递归。
上传普通文件：单条
```
+upload
```
；知识库/文档空间目标显式加
```
--workspace
```
，不要退回 upload-info + 手写 HTTP + commit。转换为在线文档走 Doc
```
+import
```
，插入正文附件走 Doc
```
+media-insert
```
。
导出后上传：
```
doc +export
```
首次就指定最终本地文件名，直接复用回执
```
localPath
```
，首次正式
```
drive +upload
```
带已获授权的
```
--yes
```
；禁止上传后再 rename。
copy/move/rename/create-folder 已内置写后读取时，不再由 Agent重复执行
```
+inspect
```
。
已知 nodeId 的重命名直接
```
+rename
```
，不先 Catalog、Help 或 search；ALIDOC 的逻辑标题由 shortcut 内部文档读回验证。
文件夹方向已明确时直接
```
status/pull/push/sync
```
，不先 status；写操作先用完全相同参数 dry-run，再正式执行。
搜索结果
```
type=able
```
后按业务动词重路由：结构复制/删除/Base 内操作走 AITable。结构复制按当前 leaf 提供源 Base ID 和真实
```
--target-folder-id
```
；缺少目标 ID 时停止，不猜根 ID或发明
```
--target-root
```
。
```
+inspect/+download/+list
```
只保证 dentryUuid；只有 URL 时先用
```
dws drive info --node <URL> --format json
```
解析并核对
```
result.fileId
```
（即 dentryUuid）。
```
drive info
```
返回
```
extension=dlink
```
时，将
```
result.fileId
```
保存为快捷方式入口 ID，先用
```
dws doc info --node <result.fileId> --format json
```
读取
```
linkSourceInfo
```
。内容读取、编辑、导出和类型路由改用目标
```
linkSourceInfo.nodeId
```
；目标仍为 dlink 时逐跳解析并记录已访问 ID，解析失败、字段缺失或 ID 重复即停。用户明确移动、重命名或删除快捷方式入口本身时仍使用最初的
```
result.fileId
```
。

最短路径不省略类型检查、确认、传输验证或写后校验。

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

```
+list/+search/+recent
```
的完整查询统一使用
```
--page-all --max-pages <N> --max-items <N>
```
，并检查集合、完整性和截断状态；只需首批结果时可不加
```
--page-all
```
。缺少集合不能当空结果，多候选禁止默认第一项。
```
+download
```
验证相对路径存在且 sizeBytes > 0；
```
+upload
```
检查最终 nodeId 和完整名称。普通 Drive 目标必须校验读回大小；指定
```
--workspace
```
时必须验证 workspaceId，并兼容
```
doc/get_document_info
```
将完整名称拆为
```
name + extension
```
且不返回大小的真实契约；若返回大小仍必须与本地一致。只有源端与结果都提供可比哈希时才核对 checksum；缺失时保留现有证据，不虚构端到端校验和。
copy/move/rename/create-folder 检查
```
ok/outcome
```
和读回；
```
partial_success
```
不是完成。
status 检查分类集合；pull/push/sync 检查 summary 和逐项结果，failed/unknown 必须保留。
分页未结束时返回 continuation；目录树或大列表必须有最大深度、页数和条目数。
同一查询续页时，若 nextCursor 重复且没有新增节点，停止继续翻页，保留已取得结果并报告分页未完成，不将重复结果计作新增。
未知写入效果先 inspect/list 回读，不盲目重放写操作。

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
```
、
```
--folder
```
使用 dentryUuid/fileId，不使用数字型 dentryId；回收站 restore 使用 recycleItemId。
```
+list --limit
```
最大 50，
```
+search --limit
```
最大 30；超过时分页，不以非法参数反复试错。
写操作只按精确 leaf Runtime 判定确认；已明确授权具体对象、动作与影响时，首次正式执行直接带
```
--yes
```
，否则先确认。预览不带，参数变化重新确认；禁止用缺少
```
--yes
```
的失败探测。
普通文件覆盖前确认真实类型和原名称；adoc/axls/able 不按普通文件覆盖。
单文件 Shortcut 的本地输入输出使用 cwd 相对路径且禁止
```
..
```
；文件夹
```
status/pull/push/sync
```
按 leaf 契约使用绝对
```
--local-folder
```
。
文件夹同步默认精确 MD5；仅在用户接受时间戳近似时用
```
--quick
```
，且不会删除任一侧多余文件。
参数不确定时只查一次精确 leaf Schema；禁止产品级 Schema。

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

Golden Route 参数足够时禁止读取 reference。其余最多读取一个精确 reference：

触发条件	Reference
URL、文件类型或跨产品边界	intent-guide
文件夹比较、拉取、推送或双向同步	folder-sync
低频权限、版本、回收站、公开状态	drive reference 的对应章节
文档查询、导入和模板保形流程	lite-recipes

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

零/多候选、类型不明或分页不完整：停止写入，返回候选或 continuation；分页读取可在有效游标和预算内继续。
```
unknown flag
```
：只查一次当前 leaf Help；
```
unknown command
```
：只查一次 Drive shortcut 清单。
普通下载遇到在线文档类型：切
```
doc +export
```
，不重复尝试 Drive download。
传输中断：保留本地临时状态或 checkpoint；先判断能否续传。
写入效果未知：按 nodeId 回读；无法证明时报告 unknown。
已知是普通文件且需要独立副本时，直接按 Golden Route 的 download→upload 执行，不以
```
+copy
```
失败作为前置探测。若仍收到普通文件 copy 不支持的错误，不重试或宣称已完成；确认授权与目标后按副本规则继续。AITable 结构复制缺少或无法验证目标文件夹时停止，不猜 ID 或创建测试文件夹。

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

普通文件/文件夹及在线文档节点的存储管理 → Drive；把文件作为附件放进某篇文档正文走 Doc
```
+media-insert
```
，其他正文/内容分别走 Doc、Sheet、AITable。
able 外层移动/重命名走 Drive；结构复制、Base 删除（
```
+base-delete
```
）及 Base 内操作走 AITable。
明确知识库 workspace 层级 → Wiki；泛称“文档空间/我的文档”通常走 Drive，但“Wiki 库内节点移出到我的文档”固定由 Wiki
```
+move-to-drive
```
完成，Drive 不预查
```
mySpace
```
、不接管该移动。
钉盘存储空间发现例外地复用 managed
```
dws wiki space list --type orgSpace|mySpace
```
；只取真实 spaceId/rootFolderId 后回到 Drive。spaceId 用于空间参数，rootFolderId 才可作为空间根目录 folder；
```
orgWikiSpace/myWikiSpace
```
返回 workspaceId，不能混入 Drive 参数。
Word/Markdown/Text 转在线文档用
```
doc +import
```
；Drive upload 只保留原文件。

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.