Dingtalk Aitable

钉钉 AI 表格 Skill

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

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

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

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

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

以下意图路由优先于下方通用 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；不要连续猜测替代命令。

表单分享用法回答契约

收到仅询问用法的请求后，第一步必须立即实际执行且仅执行下列对应命令；即使用户提到“help/schema”，也按入口选择，不能自行替换：

• form share update：dws aitable form share update --help
• +form-share-update：dws schema --cli-path "aitable +form-share-update" --compact --format json

Shortcut 名称开头的 + 是命令名不可省略的一部分；不得改写、试探其他拼法或改用 --help/-h。

发现门禁：即使 Skill 或参考文档已提供完整示例，回答前也必须实际执行一次且仅执行一次目标 leaf 的安全 help/schema 查询；不得仅依据 Skill 或参考文档直接作答。本规则优先于下方 reference 导航：命中时不读取任何 reference，不执行其他命令。 用户仅询问用法时，最终回答必须先给出完整命令；缺少必填 ID 时则给出带明确占位符的完整命令模板，禁止猜测。随后明确说明“未传入的分享配置保持原值”；不得执行目标写操作或声称已经执行。上述只读查询是唯一允许的命令。

查询成功后，最终回答只能包含两行纯文本：不要 Markdown 代码围栏、标题、表格、回读命令或其他内容。第一行放用户所问入口的完整命令；已有的必填值必须原样使用，缺少的值必须保留为 <BASE_ID>、<TABLE_ID>、<VIEW_ID> 等明确占位符。第二行先列出需要替换的占位符（没有则省略替换说明），再给出固定的未执行说明，然后立即结束：

textCopy code
dws aitable form share update --base-id <BASE_ID> --table-id <TABLE_ID> --view-id <VIEW_ID> --enabled true
请将 <BASE_ID>、<TABLE_ID>、<VIEW_ID> 替换为真实值；未传入的分享配置保持原值。本次仅查询 help/schema，未执行写操作。

已知 ID 与占位符必须区别处理：用户明确给出的短 ID 也按原值使用，不因其长度或看起来像示例就要求替换。所有 ID 已知时，第二行必须原样为“未传入的分享配置保持原值。本次仅查询 help/schema，未执行写操作。”；只有命令中确实用了占位符时才添加对应替换说明。Shortcut 的命令行必须保留 --format json，固定说明中的 help/schema 不因本次只查 schema 而改写。

两种入口都必须完整保留用户指定的配置值，尤其是表单名对应的 --form-name；不得因精简为两行而只留下 ID 和 --enabled。以下是已知 ID 的 Shortcut 用法回答示例（标题按用户输入替换，不能省略）：

textCopy code
dws aitable +form-share-update --base-id base-123 --table-id table-456 --view-id view-789 --enabled true --form-name "报名表" --format json
未传入的分享配置保持原值。本次仅查询 help/schema，未执行写操作。

返回值评审专用查询（不适用于命令用法询问）

作答前必须有本次实际执行的目标 compact Schema 查询结果；仅加载 Skill 或看到合成样本不满足此条件。先执行下表命令，再解释，不能直接根据 Skill 回答。

Help/Schema 是离线契约查询，不调用线上业务，也不读写用户的表单。因此“只分析合成返回，不要执行线上业务命令”仍允许且需要下表的本机查询，不能将其误判为线上读取而跳过；只有用户明确禁止任何命令或本机查询时才不执行，并说明本机契约未核对。

仅评审返回值/故障结果（而非询问写法）时，不套用两行命令模板，也不适用“优先 Shortcut”规则。用户指定的原子/Shortcut 入口必须原样保留，即使它们共用 Result 契约也不能互换；严格按下表查询一次后解释样本，不搜索源码/reference，不执行业务读写。

不得用搜索源码或 reference 代替本机契约查询。get 只诊断分享配置，不返回 cpSynced；不能建议“通过 get 回读 cpSynced 后确认闭环”。未验证的 CP 应继续标为未确认并交由服务端诊断，不能把 get 的成功或 UUID 非空当作恢复证明。

先选择 Schema 的实际结果分支：data.executed=false 的 dry-run 预览只含 tool/arguments/executed（Shortcut 还含 dry_run=true），不需要服务端状态或 cpSynced，ok=true 只表示预览成功。不要把真实执行成功分支的必填字段套到预览上。字段是否必填只读所选分支的 required；是否允许额外字段只读该对象的 additionalProperties，不能从 arguments 子对象推断父对象。

真实执行结果判断：分享开关依据 enabled，保留 UUID 不代表开启；UUID/封面为空就如实报告，不能推测唯一成因或拼装封面 URL。get 的成功不证明 CP 同步。update 仅在必需字段完整且类型正确、cpSynced=true 时成功；缺失/false/类型异常均不能确认闭环。统一部分失败无顶层 error：原始响应在 data.succeeded[0].response，该阶段仅表示收到回执；失败原因在 data.failed[0].error，含 execution_started=true。不要自行重放写入或补偿 CP。合成样本若不符合该结构，应指出不匹配，不能把 Schema 中的字段补写成样本已有事实。

解释边界：status 未公布枚举含义时保留原始数值，不把 0/1 自行翻译成未发布/已发布；cpSynced=false 只支持“CP 终态未确认”，不证明外部用户必定无法访问。UUID/封面空值不能证明此前从未创建，短 ID 不能仅因长度被判为占位符。

即使外层仍为 ok=true 或返回结构不符合契约，也不得为再次校验 CP 而执行或建议重发 form share update / +form-share-update（包括稍后传相同配置）；诊断不能新增写入，只保留回执并交由服务端排查。

实际执行 form share update 或 +form-share-update 后，成功结果必须同时检查 shareFormUuid、status、formCover、cpSynced；只有 cpSynced=true 才能向用户确认分享闭环完成。部分失败或 cpSynced=false 不得描述为成功。DWS 不自行调用第二个 View 更新命令补偿 CP。formCover 在旧服务端发布窗口内可能为空，应如实说明，不能由 DWS 拼装封面 URL。

命令参考：aitable.md；PostgreSQL 只读查询：aitable-psql.md；复杂命令按需加载 references/aitable/*.md；剧本：06-data-analytics.md。

Shortcut 发现（按需）

aitable 当前有 126 条公开 shortcut，完整清单保留在 Runtime Catalog 与 Schema，不在高频产品根 Skill 中重复展开。已知 leaf 直接执行。参数只查 dws schema --cli-path "aitable <leaf>" --compact --jq '{cli_path,parameters,constraints,confirmation}' -f json；仅需且已发布 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。

仅当根路由、精确 task reference 和 references/aitable.md 的低频原子索引都无法定位能力时，才执行 dws shortcut list --service aitable --format json 做最终回退；不要为已知意图加载完整 Shortcut Catalog 或产品级 Schema。

Golden Route（高频复合任务）

已由当前 AITable 调用返回且类型已确认的 ID 直接使用；名称先唯一解析为稳定 ID。用户直接提供的 /i/nodes/ URL 或来源未验证的 nodeId 先执行 dws drive info；若为 extension=dlink，将返回的 result.fileId 保存为快捷方式入口 ID 并传给 dws doc info，再逐跳读取目标 linkSourceInfo，最终确认 extension=able 后将目标 linkSourceInfo.nodeId 作为 baseId。解析失败、字段缺失、ID 重复或最终类型不是 able 时停止；只有明确移动、改名或删除快捷方式入口本身时才保留最初的 result.fileId 并切到 Drive。零命中或多候选时也停止，不默认选第一项。

数据分析，以及 PostgreSQL/SQL/SELECT/JOIN 或跨表关联查询，先读 aitable-psql.md。原始记录筛选、排序和 Top N 使用 record query；单表直接标量、分组或去重统计使用 record stats / record group-stats；仅同 Base JOIN、字段间算术、CASE、聚合后派生、汇总结果 Top N 或排名、窗口计算等复杂分析使用 psql。选用 psql 时固定同一 DWS 入口，先用 dws aitable psql -d <baseId> -l 发现逻辑表，再用 -t <tableId> 查看列类型，使用返回的 Name 执行 LIMIT 3 最小查询，成功后才以 -c <SQL> 执行正式只读查询；psql 输出 PostgreSQL 表格文本，不添加 --format json。psql 失败后只能从原始意图重新判定：完全属于单表原始记录时重发 record query，完全属于单表直接统计时重发 record stats / record group-stats；必须丢弃 psql 未完成结果并说明切换原因，复杂分析、结果合并和本地等价计算均禁止降级。

简单 leaf

除 aitable psql 外，结构化命令使用 --format json 并从真实返回中提取稳定 ID；aitable psql 输出 PostgreSQL 表格文本且不支持 --format json，按 aitable-psql.md 执行。

意图明确时直接使用；参数不确定才读 leaf Schema：

命令接在 dws aitable 后；资源 ID 使用 --base-id/--table-id/--field-id/--view-id/--dashboard-id/--page-id/--widget-id，改名使用 --name。应用模式所有命令都要求 --base-id；app widget create 另要求包含 chartType 的 --config 和包含 x/y/w/h 的 --layout。+table-copy 参数不规则，执行前只读其 leaf Schema。不读操作 Reference、Help 或产品 Catalog。

数据源查看来源用 +datasource-list-sources，获取字段用 +datasource-get-fields，创建、更新、同步、查状态和查配置用 +datasource-create / +datasource-update / +datasource-sync / +datasource-sync-status / +datasource-get-config。

执行约束

• 已有 ID 直接使用；URL 只解析一次；“唯一定位并操作”用 +resolve-base / +resolve-table，“搜索候选/存在性检查”直接用 +base-search。人员、部门或群组只有显示名称时用 entity search 取得稳定身份；这些路径不要串行探测。filters/sort 缺 fieldId 时才读取字段目录。

• Golden Route 已给出准确命令和参数时直接执行；不预读或默认读取通用 references/aitable.md。只有操作参数、JSON 结构或恢复语义确实缺失时，才读取下方一个精确操作 Reference。

• Shortcut 已含分片或验证时不重复拆步；已有 Base 新建完整表结构直接用 +table-bootstrap。

• 单产品线性任务直接执行，不创建 TodoWrite；只有跨产品或多个独立分支的长任务才建计划，并且只在阶段切换时更新，不在每条 CLI 后刷新状态。

• 用户要求资源名带当前时间戳时只取一次并在 Base、Table、Dashboard 等名称中复用同一值；不要为每个资源分别取时间。

• JSON 已返回所需字段时立即复用；不得为寻找同一字段改用 --verbose、raw、pretty 重复请求。

• 记录 filter/sort 缺 fieldId 时才读取字段目录。

• record filter/sort 与 view filter/sort/group 的协议和 Reference 互斥。普通 record query/create/update/upsert 直达；只有历史、分享、删除恢复、空行或特殊字段值读 record-ops。

• 普通字段 type 使用 text/number/date/singleSelect/currency；singleSelect 的 config 为 {"options":[{"name":"<选项>"}]}，人民币 currency 为 {"currencyType":"CNY","formatter":"FLOAT_2"}。

• 仅任务包含 4 个及以上独立业务步骤或用户明确要求时使用 TodoWrite；不按单条 CLI 拆步，只在阶段切换时更新。

• 多个资源名要求同一时间戳时，只取一次并复用。

• 复用 JSON 已返回字段，不以 --verbose/raw/pretty 重复请求。

• 数据源创建前必须先 +datasource-list-sources 获取 processCode 等透传字段，不凭记忆构造 sourceConfig。

记录稳定约束

• 记录分页报 INVALID_CURSOR、CURSOR_SNAPSHOT_CHANGED 或 CURSOR_SNAPSHOT_UNAVAILABLE 时，必须丢弃全部累计结果与旧 cursor，不存在可续传的新 cursor，也不能保留第一页再去重拼接。前两者核对条件后不传 --cursor 从第一页只读重查；UNAVAILABLE 需先等待服务修复。不得重跑含写入的整条命令。仅普通可恢复错误且实际提供有效断点时可续传，详见 record-query。

• 查询、写入、筛选或排序前，先用 field get 获取目标字段的 fieldId、type 和 config；cells 的 key 必须使用 fieldId，不是字段中文名。

• select/multipleSelect 写入传选项名称；过滤时先唯一解析 option ID。对 multipleSelect 或其他数组型字段，第二个 operand 必须是 option ID/稳定 ID 数组，不能传裸字符串。

• 人员、部门、群组和关联记录等条件先解析为稳定的结构化 ID；零命中、多命中或类型不符时停止，不得把展示名称或原值直接透传。

• 已获用户明确许可的非分析完整逐行明细可直接使用 record query --all --page-limit 0，不需要也不触发 psql 降级门禁；不得用它替代 psql 复杂分析，或在 Agent context、Python、jq、JavaScript、电子表格等本地工具做计算。自动翻页禁止模型手写循环；手动分页必须透传真实 data.nextCursor，且查询条件不变。成功空续页 records=[] 且 nextCursor 为空是正常末页，不得报错、重试或判定漏查。

• 新增或更新只使用真实返回的 ID 回读；写入效果未知时回读，不重放成功批次。

• 全量查询检查 hasMore，批量写检查最终状态；分页未结束或 partial_success 都不得声称完整完成。

• 记录 cells 使用当前 fieldId，按真实字段类型写值，只读字段不得写入。

• 新增或更新只使用真实返回的 ID 回读；写入效果未知时回读，不重放成功批次。

• 全量查询检查 hasMore，批量写检查最终状态；分页未结束或 partial_success 都不得声称完整完成。

安全边界

• 删除不可逆，按 Runtime confirmation 核对真实目标；base list 只是最近访问。字段零/多候选、类型不明时停止；多批写保留已完成批次和续跑位置。
• 评论 create/reply 非幂等，评论写操作未知状态时先 comment list 对账，不自动重放；delete 只删除本人评论且不可恢复，关联回复处理不作保证。
• app get / app page list 在 App 不存在时会初始化默认 App，属于幂等条件写；app page/widget create 非幂等且不自动重试。删除 Page 会级联删除全部 Widget，删除 Widget 会同步清理布局，均需独立确认。
• 数据源 +datasource-create / +datasource-update 会触发真实数据同步；执行前确认目标 Base 和 sourceConfig。+datasource-sync 单次最多 5 张表。

按需加载（复杂 JSON 与恢复语义）

Golden/次级直达覆盖时不读 Reference；否则按最终专有能力读取一个精确 Reference。读取后直接执行，不再读取其他 AITable Reference。

不要预加载这些 Reference。

错误最短路径

1. 零/多候选、字段歧义或分页不完整：停止并返回证据；仅有效分页会话可透传真实 nextCursor。失效游标先执行上方“记录稳定约束”，不能套用普通断点续传。
2. 类型错误只复核目标字段，不删字段或丢输入；partial_success 从 checkpoint 续跑，未知写入先回读。
3. 错误提供 actions / available_flags 时只按其中的 next_command 修正一次；retryable=false 或目标 ID 类型不符时停止。
4. 数据源同步 errorCode=4014 表示同步运行中重复触发，可稍后重试；非数据源表触发同步前先用 +base-get 确认 sync=true。

跨产品边界

• Excel 式单元格、区域和公式操作 → dingtalk-misc 的 Sheet。
• Base 作为整体在普通文件夹间移动或做外层存储重命名 → Drive；Base 结构复制/删除，以及 Base 内 Table、Dashboard、Section 的创建、复制、移动、重命名、删除 → AITable。
• 记录主键文档正文 → 取得真实 nodeId 后切 dingtalk-doc。