dingtalk-shared

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DWS 共享执行契约

DWS Shared Execution Contract

本文件只在泛称 DWS、跨产品流程、URL 预检或意图不清时作为入口。明确单产品请求直接使用对应

dingtalk-*

skill；已经内嵌最小执行契约的产品根 Skill 不需要先完整读取本文件。

This file only serves as an entry point when DWS, cross-product flows, URL pre-check, or ambiguous intent is involved. For clear single-product requests, directly use the corresponding

dingtalk-*

skill; product root skills that already embed a minimal execution contract do not need to fully read this file first.

最小 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，禁连续猜替代命令。

国际版、海外版或

.io

区域登录必须执行

dws auth login --intl

（无头环境再加

--device

）；

--intl

只用于登录，后续业务命令按所选 profile 自动路由。

产品或跨产品规则在最小契约之上增量加载。用户已明确产品内容意图时，意图优先于 URL 形态；多账号选择与跨组织规则读取

../dingtalk-misc/references/profile.md

。本地文件、产品边界和跨产品传递规则只在对应任务中加载，避免把全局手册放入每个单产品请求。

Only use
```
dws
```
; for structured reads add
```
--format json
```
and judge based on the actual response.
Directly invoke known commands; if parameters/constraints/security are unclear, consult the leaf narrow Schema. Only read the known leaf Help once if the Schema is unavailable; fix
```
unknown flag
```
once using the same leaf Help. For
```
unknown command
```
, do not check Help: first prioritize explicit suggestions in the error, then explicit compatible entries in already-loaded Skill/reference; if none, report drift and stop — full Catalog is forbidden. Low-frequency references do not default to Help; root/parent/product Help is forbidden. When discovered, must execute or explain the blocker.
Do not guess commands/flags/fields/IDs/accounts/business facts; IDs come from real responses. If target has zero hits/multiple candidates/unclear type, disambiguate first; only optional time/display scope uses contract defaults; stop if required information is missing.
Parse/read/write the same profile, IDs do not cross organizations. For multiple accounts, only use the unique
```
isOrgCurrent=true
```
; otherwise user specifies — selecting first item, most recent login, or most recently used account is forbidden.
Do not output/log tokens, refresh tokens, appSecret, or webhook tokens; do not ask for injected authentication.
Writes must match explicit intent; confirmation is ultimately determined by the Runtime gate/Schema, and
```
--yes
```
is only added after confirmation.
Verify results after writing; never claim success based on exit code. Exit must include a final response distinguishing completed, partial, blocked, pending confirmation, or failed; preserve existing data and
```
complete/hasMore/stopReason/failures
```
.
Display timestamps in the session timezone, preserve original values if necessary.
For authentication/permission/profile/confirmation/unknown errors, only read the corresponding
```
dingtalk-shared
```
reference; do not consecutively guess alternative commands.

For international, overseas, or

.io

regional logins,

dws auth login --intl

must be executed (add

--device

in headless environments);

--intl

is only for login, subsequent business commands route automatically based on the selected profile.

Product or cross-product rules incrementally load on top of the minimal contract. When the user has clear product-content intent, intent takes precedence over URL form; for multi-account selection and cross-organization rules, read

../dingtalk-misc/references/profile.md

. Local files, product boundaries, and cross-product delivery rules are only loaded in corresponding tasks, preventing the global manual from being included in every single-product request.

渐进加载

Progressive Loading

只读取当前任务需要的文件，不要一次性加载全部 shared references：

当前情况	必读内容
已明确单一产品	对应 `../dingtalk-*/SKILL.md` ；不读路由 reference
泛称 DWS、需要选择产品	routing.md
跨产品、多步骤、汇总或报告	workflow-routing.md
输入含用户直接提供的 alidocs `/i/nodes/` URL 或来源未验证的 nodeId（即使产品意图明确）	url-patterns.md；先规范化 dlink 再进入目标产品
输入含其他 alidocs、shanji 等钉钉 URL 且类型不明	url-patterns.md
产品边界仍然难以判断	intent-guide.md 的相关章节
认证、全局 flag 或输出格式问题	global-reference.md
命令已经返回错误	error-codes.md；只查错误对应章节
`confirmation_required` / 写操作确认	confirmation.md
命令发现、Schema / `--compact` / `--all`	schema-usage.md
怀疑能力不支持	capability-limits.md
批量/多源采集	conventions.md
固定短流程	lite-catalog.md 对应章节

产品命令、脚本和字段细节位于对应产品 skill，不在

dingtalk-shared

重复维护。

Only read the files required for the current task; do not load all shared references at once:

Current Situation	Required Reading
Clear single product	Corresponding `../dingtalk-*/SKILL.md` ; do not read routing references
Generic DWS, product selection needed	routing.md
Cross-product, multi-step, summary, or report	workflow-routing.md
Input contains user-provided alidocs `/i/nodes/` URL or unverified nodeId (even with clear product intent)	url-patterns.md; normalize dlink first, then enter the target product
Input contains other alidocs, shanji, or other DingTalk URLs with unknown type	url-patterns.md
Product boundaries still hard to judge	Relevant sections of intent-guide.md
Authentication, global flags, or output format issues	global-reference.md
Command returned error	error-codes.md; only read the error-related section
`confirmation_required` / write confirmation	confirmation.md
Command discovery, Schema / `--compact` / `--all`	schema-usage.md
Suspected capability not supported	capability-limits.md
Batch/multi-source collection	conventions.md
Fixed short workflows	lite-catalog.md corresponding section

Product commands, scripts, and field details reside in corresponding product skills, not duplicated in

dingtalk-shared

本 skill 作为入口时的路由顺序

Routing Order When This Skill Is the Entry Point

先识别明确的产品内容意图；明确意图直接选择对应产品。用户直接提供的 alidocs
```
/i/nodes/
```
URL 或来源未验证的 nodeId 仍须读取
```
url-patterns.md
```
：先执行节点类型探测，
```
extension=dlink
```
时将
```
drive info
```
的
```
result.fileId
```
保存为入口 ID 并传给
```
dws doc info
```
，再按
```
linkSourceInfo.nodeId
```
逐跳解析目标，把最终目标 ID 交给候选产品。当前调用链已返回真实类型的稳定 ID 可直接复用。
请求包含多个时序步骤、跨产品数据传递或汇总报告：即使 URL 已识别，也要读取
```
workflow-routing.md
```
，按行动指南组合需要的产品 skill；当前发布包不包含独立 scenario skill。
请求是单产品操作但产品不明确：读取
```
routing.md
```
，再显式读取目标产品
```
SKILL.md
```
。

doc/drive/wiki

、

aitable/sheet

、

calendar/minutes

等边界仍不清楚：只读取

intent-guide.md

的对应章节。

仍无法判断时向用户追问，不要猜测产品或命令。

First identify clear product-content intent; clear intent directly selects the corresponding product. For user-provided alidocs
```
/i/nodes/
```
URL or unverified nodeId, still read
```
url-patterns.md
```
: first perform node type probing, and when
```
extension=dlink
```
, save
```
result.fileId
```
from
```
drive info
```
as the entry ID and pass it to
```
dws doc info
```
, then resolve the target hop-by-hop via
```
linkSourceInfo.nodeId
```
, and hand the final target ID to candidate products. Stable IDs already returned with real types in the current call chain can be reused directly.
Request includes multiple time-ordered steps, cross-product data passing, or summary reports: even if URL is identified, also read
```
workflow-routing.md
```
and combine needed product skills according to the action guide; the current release package does not include standalone scenario skills.
Request is single-product but product unclear: read
```
routing.md
```
, then explicitly read target product
```
SKILL.md
```
.
Boundaries like
```
doc/drive/wiki
```
,
```
aitable/sheet
```
,
```
calendar/minutes
```
remain unclear: only read the corresponding sections of
```
intent-guide.md
```
.
If still cannot determine, ask the user for clarification; do not guess product or commands.

跨 skill 执行

Cross-Skill Execution

正文中的相对
```
Read
```
链接是运行时依赖；
```
metadata.requires.skills
```
不会自动加载。
选择目标产品后，以目标 skill 的命令、参数和风险规则为准。
多步骤流程按顺序传递真实返回值；可以并行的只读采集按对应 workflow/reference 执行，写操作默认串行并逐步验证。
产品 skill 已内联的清晰操作直接执行；仅在遇到该 skill 未覆盖的参数或边界时读取更深层 reference。

Relative
```
Read
```
links in the body are runtime dependencies;
```
metadata.requires.skills
```
does not auto-load them.
After selecting the target product, the target skill's commands, parameters, and risk rules take precedence.
Multi-step flows pass real return values in order; parallel read-only collection follows the corresponding workflow/reference, writes are serial by default with step-by-step verification.
Operations already inlined in product skills are executed directly; only read deeper references when encountering parameters or boundaries not covered by that skill.

错误最短路径

Error Shortest Path

```
unknown command
```
/
```
unknown flag
```
：运行对应层级
```
--help
```
，按公开 flag 修正后最多重试一次；命令选择不确定时读 schema-usage.md。
```
reason=confirmation_required
```
：按 confirmation.md 处理，不要当普通校验错误放弃或静默加
```
--yes
```
。
认证或权限错误：读取
```
global-reference.md
```
与
```
error-codes.md
```
对应章节。
其他错误：优先读取 JSON 错误中的
```
retryable
```
、
```
retry_after_seconds
```
、
```
next_retry_at
```
、
```
hint
```
和
```
actions
```
。只有明确
```
retryable=true
```
时才按服务端节奏重试；缺少重试语义时用
```
--verbose
```
获取诊断并停止，不连续尝试替代命令。
明确不支持的能力：说明边界，不通过其他接口绕过。

```
unknown command
```
/
```
unknown flag
```
: run corresponding level
```
--help
```
, fix using public flags, retry at most once; if command selection is uncertain, read schema-usage.md.
```
reason=confirmation_required
```
: handle per confirmation.md; do not treat as ordinary validation error or silently add
```
--yes
```
.
Authentication or permission errors: read corresponding sections of
```
global-reference.md
```
and
```
error-codes.md
```
.
Other errors: prioritize
```
retryable
```
,
```
retry_after_seconds
```
,
```
next_retry_at
```
,
```
hint
```
, and
```
actions
```
in the JSON error. Only retry following server pacing when
```
retryable=true
```
is explicit; if retry semantics are absent, use
```
--verbose
```
for diagnostics and stop — do not keep trying alternative commands.
Explicitly unsupported capability: state the boundary, do not bypass through other interfaces.