dingtalk-real-ai 钉钉 AI 表格 Skill
最小 DWS 执行契约
- 钉钉业务操作只通过
dwsCLI；本 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。删除、停用自动化等破坏性或高风险动作仍须先说明对象、动作与影响并取得独立确认。 - 写后按任务结果契约验证；不能仅凭退出码宣称成功。部分结果、未知投递状态和失败项必须如实保留。
- 时间戳面向用户展示时转换为带时区的可读时间；默认使用当前会话时区，必要时同时保留原值。
- 遇到认证、权限、profile、confirmation 或未知错误时，只加载
dingtalk-shared中对应 reference；不要连续猜测替代命令。
命令参考：aitable.md；PostgreSQL 只读查询：aitable-psql.md；复杂命令按需加载
references/aitable/*.md；剧本：06-data-analytics.md。
Shortcut 发现（按需）
aitable 当前有 100 条公开 shortcut，完整清单保留在 Runtime Catalog 与 Schema，不在高频产品根 Skill 中重复展开。已知 leaf 直接执行。只有参数不确定时，最多读取一次 dws schema --cli-path "aitable <leaf>" --compact --format json；仅当该 compact leaf Schema 与 Cobra 实际不一致时，才读取同一 leaf 的 dws aitable <leaf> --help。禁止用父级 Help、产品 Help 或完整 Catalog 探索命令；一个 Case 一旦读取 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：先用 dws aitable psql -d <baseId> -l 发现逻辑表，再用 -t <tableId> 查看列类型，最后以 -c <SQL> 执行只读查询；psql 输出 PostgreSQL 表格文本，不添加 --format json。
| 用户意图 | 唯一推荐入口 | 关键边界 |
|---|---|---|
| 从已确认的 AITable URL 解析稳定 ID | dws aitable +url-resolve --url <URL> |
只解析 URL 中已有的 baseId/tableId/viewId/recordId，不远程解析 dlink；原始 /i/nodes/ URL 必须先按上文规范化，dlink 目标 nodeId 直接作为 baseId |
| 按名称唯一定位并操作 Base/Table | dws aitable +resolve-base --name <名称> → dws aitable +resolve-table --base <ID> --name <表名> |
默认精确匹配；只有用户明确接受模糊匹配时才加 --fuzzy |
| 搜索 Base 候选或检查是否存在 | dws aitable +base-search --query <关键词> |
用户说“搜索/找一下/候选/如果没有就创建”时直接走本入口，不先调用 +resolve-base；返回 hasMore/nextCursor，仅 hasMore=true 时续页；AITable Base 名称不得路由到 dws aisearch person |
| 浏览 Base 下的数据表 | dws aitable +list-tables --base <ID> |
只返回 tableId/tableName，不加载字段 |
| 新建 Base 与整套表字段 | dws aitable +base-bootstrap --name <名称> --tables '[{"name":"<表名>","fields":[{"fieldName":"<字段名>","type":"text"}]}]' |
表对象键必须是 name，不是 tableName；字段使用 fieldName/type/config；参数已足够时直接执行 |
| 复制 Base 到文档目录 | dws aitable +base-copy --base-id <B> --target-folder-id <FOLDER_NODE_ID> [--only-struct] [--new-name <名称>]；只有 URL 时先用 dws doc info --node <URL> --format json 解析 nodeId，然后仍传 --target-folder-id <NODE_ID> |
target-folder-id 必须是文件夹 nodeId，不接受 URL、路径、纯数字 dentryId 或 rootFolderId；若 Runtime 返回 target_not_supported/retryable=false，立即报告，不查 Help、不换 ID、不建测试文件夹，也不手工降级复制 |
| 已有 Base 新建一张表与字段 | dws aitable +table-bootstrap --base-id <ID> --name <表名> --fields '<JSON数组>' |
字段使用 fieldName/type/config；自动按 15 个字段分片并读回验证 |
| 读取字段目录或完整配置 | dws aitable field list --base-id <B> --table-id <T> / dws aitable +field-get --base-id <B> --table-id <T> |
只需 fieldId/name/type 用 field list；需要 config 用 +field-get；不存在 +field-list 或 +list-fields |
| 查询记录、记录筛选/排序或字段投影 | dws aitable +record-query --base-id <ID> --table-id <ID> [--record-ids <IDs>] [--field-ids <IDs>] [--filters <JSON>] [--sort <JSON>] [--query <关键词>] |
用户要求“只返回/仅查看”指定字段时必须传对应 --field-ids，不能只在最终文本删列；明确要求全量时改用原子 record query --all --page-limit <N> |
| 新增单条或批量记录 | dws aitable record create --base-id <ID> --table-id <ID> --records <JSON> |
当前无 +record-create；写前取字段定义，写后按新 ID 回读 |
| 更新已知 recordId | dws aitable +record-update --base-id <ID> --table-id <ID> --records <JSON> |
自动分片并读回；只传需修改字段 |
| 查询一条记录的变更历史 | dws aitable +record-history-list --base-id <ID> --table-id <ID> --record-id <ID> |
已知 recordId 时直接执行，不探测 Help、Catalog 或全量 Schema |
| 按业务键同步或按条件批改 | 唯一键用 dws aitable +record-upsert-by-key ...；有界批改用 dws aitable +record-bulk-patch ... --max-matches <N> |
upsert 仅允许 0 条创建、1 条更新；批改必须有 query/filters/record-ids 边界。普通 update/upsert 直接执行；只有历史、分享、删除恢复、空行或特殊字段值才读 record-ops；明确 AND/OR、日期或比较操作符只读 filter-sort |
| 生成记录分享链接并发送给联系人 | dws aitable +record-share-links --base <B> --table <T> --record-ids <IDs> → dws chat +dm --to <姓名> --text <完整链接文本> |
AITable 只生成链接；用户要求“发送”时还必须完成真实发送，不能停在联系人解析 |
| 创建或复制视图 | 创建用 `dws aitable view create --base-id --table-id --view-type <Grid | FormDesigner |
| 创建并验证 Dashboard，按需创建 Chart | dws aitable dashboard create --base-id <B> --name <名称> → dws aitable +dashboard-get --base-id <B> --dashboard-id <D>；需要 Chart 时按下方“按需加载”处理 |
只使用创建返回的真实 dashboardId；失败时不要猜同义命令或更换 dashboardId |
| 管理 AI 表格应用模式 | dws aitable app get --base-id <B> → dws aitable app page list --base-id <B> → 按需 app page create/update/move/delete 或 app widget create/get/list/update/delete |
一个 Base 只有一个面向用户的 App；页面 pageId 同时是对应 Dashboard ID。Widget 的 config/layout 是完整对象，更新前先读回；创建操作未知状态时不得自动重放 |
| Base 内创建 Section 并移动节点 | dws aitable +section-create --base-id <B> --name <名称> → dws aitable +section-move-node --base-id <B> --node-id <N> --new-parent-section-id <S> → dws aitable +section-list-nodes --base-id <B> |
Table、Dashboard、Section 都是 AITable 的 nsheet 节点；禁止改走 Wiki/Drive 文件夹或移动命令 |
| 将本地 CSV/XLSX/XLS 导入新表 | python scripts/aitable_import_via_task.py <BASE_ID> <FILE_PATH> |
首选本 Skill 自带脚本，一次完成申请凭证、空 Content-Type PUT 和 import data；不要猜 +import-csv 或给 import upload 传 --file |
| 接入外部数据源（审批等） | dws aitable +datasource-list-sources --base-id <ID> --datasource-type OA → 解析 result 构造 sourceConfig → dws aitable +datasource-create --base-id <ID> --datasource-type OA --source-config '<JSON>' |
当前仅支持 OA 审批；processCode/name/iconUrl/url 从 list-sources 原样透传，创建后用 +datasource-sync-status 查同步结果 |
简单 leaf
除 aitable psql 外，结构化命令使用 --format json 并从真实返回中提取稳定 ID；aitable psql 输出 PostgreSQL 表格文本且不支持 --format json，按 aitable-psql.md 执行。
意图明确时直接使用；参数不确定才读 leaf Schema：
| 用户意图 | 入口 |
|---|---|
| 查看 / 改名 / 删除 Base | +base-get / +base-update / +base-delete |
| 搜索模板 | +template-search |
| 查看 / 跨 Base 复制 / 改名 / 删除 Table | +table-get / +table-copy / +table-update / +table-delete |
| 创建 / 更新 / 删除普通字段 | field create / field update / field delete |
| 查看 / 删除 View | +view-get / +view-delete |
| 查看 / 改名 / 删除 Dashboard | +dashboard-get / +dashboard-update / +dashboard-delete |
| 查看 / 修改应用模式 App | app get / app update |
| 管理应用页面 | app page create/get/list/update/move/delete |
| 管理页面 Widget | app widget create/get/list/update/delete |
命令接在 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。
执行约束
- 记录 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。
记录稳定约束
查询、写入、筛选或排序前，先用
field get获取目标字段的fieldId、type和config；cells的 key 必须使用fieldId，不是字段中文名。select/multipleSelect 写入传选项名称；过滤时先唯一解析 option ID。对 multipleSelect 或其他数组型字段，第二个 operand 必须是 option ID/稳定 ID 数组，不能传裸字符串。
人员、部门、群组和关联记录等条件先解析为稳定的结构化 ID；零命中、多命中或类型不符时停止，不得把展示名称或原值直接透传。
用户要求全量结果时，使用
record query --all --page-limit 0自动翻页，禁止模型手写循环；手动分页必须透传真实data.nextCursor，且查询条件不变。成功空续页records=[]且nextCursor为空是正常末页，不得报错、重试或判定漏查。新增或更新只使用真实返回的 ID 回读；写入效果未知时回读，不重放成功批次。
全量查询检查
hasMore，批量写检查最终状态；分页未结束或partial_success都不得声称完整完成。记录
cells使用当前 fieldId，按真实字段类型写值，只读字段不得写入。新增或更新只使用真实返回的 ID 回读；写入效果未知时回读，不重放成功批次。
全量查询检查
hasMore，批量写检查最终状态；分页未结束或partial_success都不得声称完整完成。
安全边界
- 删除不可逆，按 Runtime confirmation 核对真实目标；
base list只是最近访问。字段零/多候选、类型不明时停止；多批写保留已完成批次和续跑位置。 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 |
|---|---|
+record-query、upsert、bulk patch 的记录 filters/sort/date/AND/OR/比较操作符 |
filter-sort |
| 记录历史、分享、删除恢复、空行或特殊字段值 | record-ops |
| 记录统计、分组聚合或去重率 | record-stats |
| 查询记录的主键文档，或为记录创建主键文档 | 首次建表前读取 primary-doc；普通 Base/Table/字段/记录创建与导入不读取 |
| AI 字段、关联字段、lookup/filterUp 或其他复杂 config | field |
| formula 字段或公式语法 | formula-guide |
| 导入导出任务恢复 | export-import |
视图列顺序、移到/放到/固定在最左、filter、sort、group（不得转读记录 filter-sort） |
view-config |
| Kanban/Gallery 的 card、Gantt 的 timebar、Grid 的 aggregate | view-types |
| 视图锁定、明确冻结前 N 列、行高或填色 | view-extras |
| Base 内 Section/节点移动或清理 | section |
| Chart 创建或更新所需 config，或 Dashboard 完整 config/arrange；普通 Dashboard CRUD 走上方直达 | dashboard-chart |
| 表单创建、题目或分享 | form |
| 附件上传或移除 | attachment |
| 自动化工作流 | workflow |
| 普通角色或高级权限 | advperm |
| 数据源接入、同步管理、sourceConfig 构造或审批数据同步 | datasource |
| SQL、PostgreSQL、SELECT 或同 Base 多表 JOIN | psql |
| 产品边界不明确 | intent-guide |
| 只有上述 Reference 仍无法定位的低频原子能力 | aitable.md 的对应章节 |
不要预加载这些 Reference。
错误最短路径
- 零/多候选、字段歧义或分页不完整：停止并返回证据；需要后续页时只透传真实
nextCursor。 - 类型错误只复核目标字段，不删字段或丢输入；
partial_success从 checkpoint 续跑，未知写入先回读。 - 错误提供
actions/available_flags时只按其中的next_command修正一次；retryable=false或目标 ID 类型不符时停止。 - 数据源同步
errorCode=4014表示同步运行中重复触发，可稍后重试；非数据源表触发同步前先用+base-get确认sync=true。
跨产品边界
- Excel 式单元格、区域和公式操作 →
dingtalk-misc的 Sheet。 - Base 作为整体在普通文件夹间移动或做外层存储重命名 → Drive；Base 结构复制/删除，以及 Base 内 Table、Dashboard、Section 的创建、复制、移动、重命名、删除 → AITable。
- 记录主键文档正文 → 取得真实 nodeId 后切
dingtalk-doc。