DWS 共享执行契约
本文件只在泛称 DWS、跨产品流程、URL 预检或意图不清时作为入口。明确单产品请求直接使用对应 dingtalk-* skill;已经内嵌最小执行契约的产品根 Skill 不需要先完整读取本文件。
最小 DWS 执行契约
- 只用
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。本地文件、产品边界和跨产品传递规则只在对应任务中加载,避免把全局手册放入每个单产品请求。
渐进加载
只读取当前任务需要的文件,不要一次性加载全部 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 重复维护。
本 skill 作为入口时的路由顺序
- 先识别明确的产品内容意图;明确意图直接选择对应产品。用户直接提供的 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的对应章节。- 仍无法判断时向用户追问,不要猜测产品或命令。
跨 skill 执行
- 正文中的相对
Read链接是运行时依赖;metadata.requires.skills不会自动加载。 - 选择目标产品后,以目标 skill 的命令、参数和风险规则为准。
- 多步骤流程按顺序传递真实返回值;可以并行的只读采集按对应 workflow/reference 执行,写操作默认串行并逐步验证。
- 产品 skill 已内联的清晰操作直接执行;仅在遇到该 skill 未覆盖的参数或边界时读取 更深层 reference。
错误最短路径
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获取诊断并停止,不连续尝试替代命令。 - 明确不支持的能力:说明边界,不通过其他接口绕过。

