dingtalk-aitable

钉钉 AI 表格 Skill

业务操作优先与契约评审边界

默认目标是完成用户明确提出的 AI 表格业务操作，包括查询、创建、更新、同步和其他已授权写入。契约评审是辅助场景，仅在用户明确要求核对合成 JSON、dry-run、参数合法性、Help/Schema 或恢复方案时启用；这类请求默认只读，不把评审要求扩展成线上业务操作。用户同时提出业务操作和契约核对时，先按真实业务目标执行必要的契约校验，再继续执行已明确授权的业务操作。

先区分操作、用法与契约评审

用户只要求评审返回值或恢复方案时，不执行业务操作，也不按业务任务扩展到上游写入命令。发现目标以用户原始消息为准，Agent 自行摘要或传入 Skill 的参数不是新增请求，不能将“核对该对账命令”改写成“比较对账与原创建命令”。保留用户正在核对的完整原子路径或 + Shortcut 名，不做同义替换。背景里提到的原创建命令不是额外发现目标。

只评审一个命令时，先取得一次该入口的 compact Schema，再依据本次结果回答；不要并行或顺序查询背景命令，也不要追加同义入口、完整 Schema 或 Help。未发布 result 时说明该结构未公开，不靠重复查询或示例推断字段。用户明确要求比较多个命令时，才分别查询各自契约。Help/Schema 是本机离线查询，“不要执行线上业务”不禁止它；用户明确禁止任何命令时则不查询，并说明契约未核对。

评审中用户要求下一步只读命令时，回答先给出有当前契约依据、使用原 ID/核对键的完整命令，并说明尚未执行；紧接着给出关键判断与禁止动作，再简要解释依据。不先展开工具过程、Schema 字段表或长篇引用，不把下一步埋在分析末尾；无法确定只读入口或参数时说明缺口，不能猜测。没有索要命令时，先用简短结论回答用户的全部安全问题：是否允许重放写入、哪些结果应保留或丢弃、只读恢复有什么前提，再按需解释；不能把关键禁止动作留到分节解释或末尾总结。明确区分本机离线契约核对、用户提供的回执和仍未验证的线上状态：本机 Schema 只能证明命令契约，不能证明业务已经执行或远端状态已经核实。

仅评审失效游标恢复时，读取 record-query 开头的“只评审失效游标恢复”段，集中说明丢弃旧结果、UNAVAILABLE 等待前提和禁止重放写入这三项边界；不转入该 Reference 后面的实际查询流程，也不从新旧结果差异推导补写许可。

以下意图路由优先于下方通用 Schema 导航。表单分享的用法询问与返回值评审不能共用发现路径：

请求意图	本次唯一契约查询
评审返回值、恢复方案、故障或 dry-run 样本	把正在核对的完整入口原样放入 dws schema --cli-path "aitable <原入口>" --compact --format json；保留 +，不改查 Help，也不切换原子/Shortcut
仅问原子 form share update 的写法	只查询 dws schema --cli-path "aitable form share update" --compact --format json
仅问 Shortcut 的写法	只查该 Shortcut 的 compact Schema

最小 DWS 执行契约

• 钉钉业务操作只通过 dws CLI；本 Skill 明确发布的脚本可编排 dws 并完成预签名文件上传。结构化读取使用 --format json，按真实返回判断结果。
• 已知 leaf 直接执行。只有参数或安全语义不确定时，最多读取一次 dws schema --cli-path "aitable <leaf>" --compact --format json；仅当该 compact leaf Schema 与 Cobra 实际不一致时，才读取同一 leaf 的 dws aitable <leaf> --help。禁止通过父级 Help、产品 Help 或完整 Catalog 探索命令。
• 不猜命令、flag、字段、ID、账号或时间。后续 ID 必须来自真实返回；零命中、多候选或类型不明时停止并消歧。
• 解析目标、读取上下文和最终执行必须使用同一 profile；不得跨组织复用 userId、openDingTalkId 或 openConversationId。多账号组织只使用明确的 isOrgCurrent=true 默认账号；没有默认账号时要求用户指定，禁止选择第一项、最近登录或最近使用账号。
• 不输出或记录 token、refresh token、appSecret、webhook token 等凭据；宿主已注入认证时不要索要凭据。
• 写操作必须符合用户明确意图。是否需要确认以最终 Runtime gate 和 Schema 为准；本轮用户已明确要求执行、目标与影响无歧义的非破坏性写操作时，该明确指令就是本次确认，首次调用直接携带 Runtime 所需的 --yes，不先制造 confirmation_required。文件导入是非幂等操作，仍按 Golden Route 先触发 Runtime 确认门禁，确认后再追加 --yes。删除、停用自动化等破坏性或高风险动作仍须先说明对象、动作与影响并取得独立确认。
• 写后按任务结果契约验证；不能仅凭退出码宣称成功。部分结果、未知投递状态和失败项必须如实保留。
• Runtime Schema 是当前能力与安全语义的权威来源；同一 leaf 任务内只读一次并复用。只有 Schema 缺字段、含义不清或与真实执行冲突时才读 leaf Help；版本、profile 变化或出现契约错误时立即作废缓存。
• mutation 返回、HTTP 200 和退出码 0 都只是调用回执，不是最终对象状态。写后必须清除受影响的读取缓存，用返回的真实 ID/唯一键发起独立读回，不复用写前结果。
• 同一 Base 的写入默认串行；只有不同 Base、无数据/ID/顺序依赖且失败可独立回读时，才允许受控并发写。无依赖只读调用默认最多 4 路并发。
• 写调用超时、连接中断或返回结果未知时，禁止原样自动重放；先查真实状态。只读调用可对瞬态错误做有上限重试。
• 结构化结果可能是统一 ok/outcome、旧 status 或 boolean success 信封；不固定假设 data 层级。partial_failure 可以在 stdout 中并返回退出码 7，必须先解析信封再判断执行结果。
• 文件上传返回的 uploadUrl、token、authorization、signature 等是凭据；不输出、不写日志，结构化错误也要递归脱敏。
• 时间戳面向用户展示时转换为带时区的可读时间；默认使用当前会话时区，必要时同时保留原值。
• 遇到认证、权限、profile、confirmation 或未知错误时，只加载 dingtalk-shared 中对应 reference；不要连续猜测替代命令。