钉钉文档 Skill

最小 DWS 执行契约

• 只通过 dws CLI 操作钉钉；结构化读取使用 --format json，按真实返回判断结果。
• 已知命令直接执行。只有 leaf 参数或安全语义不确定时读取精确 Schema，只有 Cobra flag 不确定时读取精确 leaf Help；不要加载产品级 Catalog 代替选路。
• 不猜命令、flag、字段、ID、账号或时间。后续 ID 必须来自真实返回；零命中、多候选或类型不明时停止并消歧。
• 解析目标、读取上下文和最终执行必须使用同一 profile；不得跨组织复用 userId、openDingTalkId 或 openConversationId。多账号组织只使用明确的 isOrgCurrent=true 默认账号；没有默认账号时要求用户指定，禁止选择第一项、最近登录或最近使用账号。
• 不输出或记录 token、refresh token、appSecret、webhook token 等凭据；宿主已注入认证时不要索要凭据。
• 写操作必须符合用户明确意图。是否需要确认以最终 Runtime gate 和 Schema 为准；需要确认时先说明对象、动作与影响，再追加 --yes。
• 写后按任务结果契约验证；不能仅凭退出码宣称成功。部分结果、未知投递状态和失败项必须如实保留。
• 时间戳面向用户展示时转换为带时区的可读时间；默认使用当前会话时区，必要时同时保留原值。
• 遇到认证、权限、profile、confirmation 或未知错误时，只加载 dingtalk-shared 中对应 reference；不要连续猜测替代命令。

Shortcut 发现（按需）

doc 当前有 45 条公开 shortcut，完整清单保留在 Runtime Catalog 与 Schema，不在高频产品根 Skill 中重复展开。已知意图按下方路由。

仅当现有路由和 reference 都无法定位低频能力时，才执行 dws shortcut list --service doc --format json 做最后回退；不要为已知高频意图加载完整 Shortcut Catalog 或产品级 Schema。

Golden Route

走最小入口：ID/URL 直用；标题先搜索，唯一命中再执行。成本顺序：稳定 ID → shortcut → 局部读 → 精确写；禁以产品 Schema、全文或原子命令起步。

关键结果语义

• 保留真实 nodeId、URL、资源类型和容器；同轮创建后直接复用返回 ID，禁止再按标题或钉盘搜索。
• 先消费完整回执；Runtime 已分片/回读时不重复读取。只有局部验收、partial_success 或 commit-unknown 才再 +fetch。
• 状态恢复：partial_success 只补未完成步骤；unknown 先回读、不重试写；retryable 仅限明确未开始；权限/参数/认证失败停止。
• 仅在结果明确且关键内容回读匹配后报告写入完成。
• 搜索/列表检查 complete、hasMore、cursor 和失败项。“有哪些/列出/全部”逐页至完整；只有示例/前 N 条可提前停止并声明范围。
• +import 已含上传、转换、轮询和落点回读；成功检查 success=true、verified=true、taskId、nodeId、documentUrl。超时或中断保留 taskId、查询原任务，禁止重导。
• 导出/下载仅用工作目录相对路径，默认不覆盖并原子落盘。

参数与安全边界

• @file：已有或临时文件先暂存到 cwd；传 @相对路径，禁绝对路径和 ..。
• doc +update 的动作由 --command 指定；block 操作的 ID 必须来自 +fetch --detail with-ids 或真实 block 列表。
• Schema 门禁：不确定时仅查一次精确 leaf：--fields use_when,avoid_when,parameters,constraints,confirmation；禁用产品级/--all。准备 Help 时，本轮仅查一次。
• 消费本页或精确 Schema 的 confirmation：user_required 且原请求/预授权已确认目标、动作、参数时，首调即加 --yes；否则预览/询问；禁止靠失败探测门禁。
• JSONML 顶层必须是单个非空元素；禁止 [[...]] 元素数组包裹。

按需加载

Golden Route 已给出命令且参数足够时，禁止读取 reference。其余仅在下列语义不明确时，才最多读取一个 reference：

常规 +create、+fetch、+update append/overwrite、+export、+import 禁止读取 reference；需策略时仅读上表一项，禁预加载/连读。

错误最短路径

1. 零命中、多候选、类型不明或分页不完整：停止后续写入，展示候选或 continuation；禁止默认第一项。
2. Help 不参与选路；按上方门禁先消费一次精确 leaf Schema。只有真实 unknown flag/契约漂移后才查一次 leaf Help；unknown command 只查一次 shortcut 清单，禁止试探后缀和 dws doc --help | grep/head。
3. REVISION_CONFLICT：重新读取当前 revision，展示差异；未经用户确认不得改成无 revision 覆盖。
4. doc_write_commit_unknown：先回读；禁止自动重试创建或追加。
5. 认证、权限或 profile 错误：只读 dingtalk-shared 对应 reference，不用底层命令绕过。
6. 导出/媒体失败：保留稳定 ID 后停止；禁止网络请求、安装依赖或本地文档库兜底。

跨产品边界

• 普通文件/目录/纯上传下载/节点权限 → dingtalk-drive；保留原文件用原子命令 dws drive upload --workspace，在线转换用 doc +import --workspace
• 知识库空间、节点层级和成员管理 → dingtalk-wiki
• 原生 .md 文件读取和编辑 → dingtalk-misc
• axls / able → 对应电子表格或多维表 Skill
• 持续监听文档事件 → dingtalk-misc