Skip to content
Back to search

dingtalk-ai-table

SkillWorks with Claude CodeGitHub

钉钉 AI 表格(多维表)操作技能。使用 mcporter CLI 连接钉钉官方新版 AI 表格 MCP server,基于 baseId / tableId / fieldId / recordId 体系执行 Base、Table、Field、Record 的查询与增删改。适用于创建 AI 表格、搜索表格、读取表结构、批量增删改记录、批量建字段、更新字段配置、按模板建表等场景。需要配置 DINGTALK_MCP_URL 或直接使用 Streamable HTTP URL。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aliramw--dingtalk-ai-table/badge.svg)](/listings/aliramw--dingtalk-ai-table)

HTML

<a href="/listings/aliramw--dingtalk-ai-table"><img src="/api/listings/aliramw--dingtalk-ai-table/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 388 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: dingtalk-ai-table
  3. description: 钉钉 AI 表格(多维表)操作技能。使用 mcporter CLI 连接钉钉官方新版 AI 表格 MCP server,基于 baseId / tableId / fieldId / recordId 体系执行 Base、Table、Field、Record 的查询与增删改。适用于创建 AI 表格、搜索表格、读取表结构、批量增删改记录、批量建字段、更新字段配置、按模板建表等场景。需要配置 DINGTALK_MCP_URL 或直接使用 Streamable HTTP URL。
  4. version: 0.6.0
  5. metadata:
  6. author: Marila@Dingtalk
  7. category: productivity
  8. tags:
  9. - dingtalk
  10. - spreadsheet
  11. - mcp
  12. - automation
  13. - data-management
  14. documentation: https://github.com/aliramw/dingtalk-ai-table
  15. support: https://github.com/aliramw/dingtalk-ai-table/issues
  16. openclaw:
  17. requires:
  18. env:
  19. - DINGTALK_MCP_URL
  20. - OPENCLAW_WORKSPACE
  21. bins:
  22. - mcporter
  23. - python3
  24. primaryEnv: DINGTALK_MCP_URL
  25. homepage: https://github.com/aliramw/dingtalk-ai-table
  26. ---
  27. # 钉钉 AI 表格操作(新版 MCP)
  28. ## 🚀 5 分钟快速开始
  29. ### 1️⃣ 列出我的表格
  30. ```bash
  31. mcporter call '<DINGTALK_MCP_URL>' .list_bases limit=5
  32. ```
  33. ### 2️⃣ 创建新表格
  34. ```bash
  35. mcporter call '<DINGTALK_MCP_URL>' .create_base baseName='我的项目'
  36. ```
  37. ### 3️⃣ 添加记录
  38. ```bash
  39. mcporter call '<DINGTALK_MCP_URL>' .create_records \
  40. --args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_name":"张三"}}]}'
  41. ```
  42. ### 4️⃣ 查询记录
  43. ```bash
  44. mcporter call '<DINGTALK_MCP_URL>' .query_records \
  45. --args '{"baseId":"base_xxx","tableId":"tbl_xxx","limit":10}'
  46. ```
  47. ### 5️⃣ 批量导入
  48. ```bash
  49. python3 scripts/import_records.py base_xxx tbl_xxx data.csv
  50. ```
  51. ---
  52. ## 核心概念
  53. 按 **新版 MCP schema** 工作:
  54. - Base:`baseId`
  55. - Table:`tableId`
  56. - Field:`fieldId`
  57. - Record:`recordId`
  58. 不要再用旧版 `dentryUuid / sheetIdOrName / fieldIdOrName`。
  59. 推荐使用 `mcporter 0.8.1` 及以上版本。
  60. 输出模式兼容说明:
  61. - `mcporter 0.8.1+` 可直接调用
  62. - 更低版本需要显式加 `--output text`
  63. - AI 表格 MCP 无论使用哪种模式,返回体本身都是标准 JSON;差异主要在 `mcporter` 的输出处理方式
  64. ## 版本守门规则(每个 MCP Server 地址只强制检查一次)
  65. 在真正开始任何 AI 表格操作前,必须先检查当前 `mcporter` 注册的 `dingtalk-ai-table` MCP server 实际返回的 tools schema。**但这个检查不该每次都重复做;同一个 MCP Server 地址只需要强制检查一次。**
  66. ### 一次性检查策略
  67. 1. 先读取当前 `mcporter` 里 `dingtalk-ai-table` 对应的 MCP Server 地址。
  68. 2. 用这个地址生成一个本地检查标记(例如基于完整 URL 或其 hash)。
  69. 3. 在工作区保存检查结果,例如放到:
  70. ```text
  71. ~/.openclaw/workspace/.cache/dingtalk-ai-table/
  72. ```
  73. 建议文件名模式:
  74. ```text
  75. schema-check-<url-hash>.json
  76. ```
  77. 4. 如果当前地址对应的检查标记已经存在,并且结果是“已确认新版 schema”,则**跳过重复检查**,直接继续后续 AI 表格操作。
  78. 5. 只有在以下情况才重新强制检查:
  79. - 第一次运行,没有检查标记
  80. - `mcporter` 里的 MCP Server 地址变了
  81. - 之前检查结果是旧版 schema / 检查失败
  82. - 用户明确要求重新验证
  83. ### 强制检查时执行
  84. ```bash
  85. mcporter list dingtalk-ai-table --schema
  86. ```
  87. ### 判断标准
  88. 如果返回的 tools 仍然是旧版这一套,例如出现:
  89. - `get_root_node_of_my_document`
  90. - `create_base_app`
  91. - `list_base_tables`
  92. - `add_base_record`
  93. - `search_base_record`
  94. - `list_base_field`
  95. 或者整体仍然基于:
  96. - `dentryUuid`
  97. - `sheetIdOrName`
  98. - `fieldIdOrName`
  99. 那么说明:**虽然 skill 文件已经是新版,但 mcporter 里注册的 MCP server 地址还是旧的,不能继续操作。**
  100. ### 遇到旧版 schema 时的强制提示
  101. 此时必须明确提示用户:
  102. 1. 打开这个页面:
  103. `https://mcp.dingtalk.com/#/detail?mcpId=9555&detailType=marketMcpDetail`
  104. 2. 点击右侧 **「获取 MCP Server 配置」** 按钮
  105. 3. 复制新的 MCP Server 地址
  106. 4. 用新的地址替换 `mcporter` 里已经注册的 `dingtalk-ai-table` 地址
  107. 5. 替换完成后,再重新执行:
  108. ```bash
  109. mcporter list dingtalk-ai-table --schema
  110. ```
  111. 只有当返回的 tools 已经变成新版 schema,例如出现:
  112. - `list_bases`
  113. - `get_base`
  114. - `get_tables`
  115. - `get_fields`
  116. - `query_records`
  117. - `create_records`
  118. - `update_records`
  119. - `delete_records`
  120. - `prepare_attachment_upload`
  121. 才允许继续真正的 AI 表格操作。
  122. ### 通过检查后的处理
  123. 一旦确认当前 MCP Server 地址返回的是新版 schema,就把结果写入本地检查标记。后续只要 `mcporter` 里的 `dingtalk-ai-table` 地址没变,就不要再重复做这一步守门检查。
  124. ### 用户提示文案(可直接复用)
  125. ```text
  126. 当前 mcporter 里注册的 dingtalk-ai-table 还是旧版 MCP schema,暂时不能按新版技能操作。
  127. 请打开 https://mcp.dingtalk.com/#/detail?mcpId=9555&detailType=marketMcpDetail ,点击右侧“获取 MCP Server 配置”按钮,复制新的 MCP Server 地址,并替换 mcporter 里已注册的 dingtalk-ai-table 地址。替换后重新检查 schema,确认出现 list_bases / get_base / create_records 等新版 tools 后,再继续操作 AI 表格。
  128. ```
  129. ## 前置要求
  130. ### 安装 mcporter CLI
  131. ```bash
  132. npm install -g mcporter
  133. # 或
  134. bun install -g mcporter
  135. ```
  136. 验证:
  137. ```bash
  138. mcporter --version
  139. ```
  140. ### 配置 MCP Server
  141. 在钉钉 MCP 广场 https://mcp.dingtalk.com/#/detail?mcpId=9555&detailType=marketMcpDetail 获取新版钉钉 AI 表格 MCP 的 `Streamable HTTP URL`。
  142. 方式一:直接配置到 mcporter
  143. ```bash
  144. mcporter config add dingtalk-ai-table --url "<Streamable_HTTP_URL>"
  145. ```
  146. 方式二:使用环境变量
  147. ```bash
  148. export DINGTALK_MCP_URL="<Streamable_HTTP_URL>"
  149. ```
  150. > 这个 URL 带访问令牌,等同密码,不要泄露。
  151. ### 工作区沙箱
  152. 脚本读取本地文件时,会优先使用 `OPENCLAW_WORKSPACE` 作为允许根目录:
  153. ```bash
  154. export OPENCLAW_WORKSPACE="$HOME/.openclaw/workspace"
  155. ```
  156. 未设置时默认使用当前工作目录。
  157. ## 核心工具集
  158. ### Base 层
  159. - `list_bases`
  160. - `search_bases`
  161. - `get_base`
  162. - `create_base`
  163. - `update_base`
  164. - `delete_base`
  165. - `search_templates`
  166. ### Table 层
  167. - `get_tables`
  168. - `create_table`
  169. - `update_table`
  170. - `delete_table`
  171. ### Field 层
  172. - `get_fields`
  173. - `create_fields`
  174. - `update_field`
  175. - `delete_field`
  176. ### Record 层
  177. - `query_records`
  178. - `create_records`
  179. - `update_records`
  180. - `delete_records`
  181. ### 附件层
  182. - `prepare_attachment_upload`
  183. ## 推荐工作流
  184. ### 1. 先找 Base
  185. ```bash
  186. mcporter call dingtalk-ai-table list_bases limit=10
  187. mcporter call dingtalk-ai-table search_bases query="销售"
  188. ```
  189. ### 2. 再拿 Table 目录
  190. ```bash
  191. mcporter call dingtalk-ai-table get_base baseId="base_xxx"
  192. ```
  193. ### 3. 再展开表结构
  194. ```bash
  195. mcporter call dingtalk-ai-table get_tables \
  196. --args '{"baseId":"base_xxx","tableIds":["tbl_xxx"]}'
  197. ```
  198. ### 4. 字段复杂时读完整配置
  199. ```bash
  200. mcporter call dingtalk-ai-table get_fields \
  201. --args '{"baseId":"base_xxx","tableId":"tbl_xxx","fieldIds":["fld_xxx"]}'
  202. ```
  203. ### 5. 再查 / 写记录
  204. ```bash
  205. mcporter call dingtalk-ai-table query_records \
  206. --args '{"baseId":"base_xxx","tableId":"tbl_xxx","limit":20}'
  207. mcporter call dingtalk-ai-table create_records \
  208. --args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_name":"张三"}}]}'
  209. ```
  210. ### 6. 写入附件字段
  211. attachment 字段支持三种写法:
  212. **方式一:先上传,再写 fileToken(推荐,可靠)**
  213. ```bash
  214. # Step 1:申请上传地址(返回 uploadUrl 和 fileToken)
  215. mcporter call dingtalk-ai-table prepare_attachment_upload \
  216. --args '{"baseId":"base_xxx","fileName":"report.pdf","size":102400,"mimeType":"application/pdf"}'
  217. # Step 2:把文件 PUT 到 uploadUrl(必须带 Content-Type,值必须与 mimeType 完全一致)
  218. curl -X PUT "<uploadUrl>" \
  219. -H "Content-Type: application/pdf" \
  220. --data-binary @report.pdf
  221. # Step 3:把 fileToken 写入记录
  222. mcporter call dingtalk-ai-table create_records \
  223. --args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_attach":[{"fileToken":"ft_xxx"}]}}]}'
  224. ```
  225. **方式二:直接传外链 URL(异步转存,best-effort)**
  226. ```bash
  227. mcporter call dingtalk-ai-table create_records \
  228. --args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_attach":[{"url":"https://example.com/file.pdf"}]}}]}'
  229. ```
  230. > URL 转存是 best-effort 异步链路,返回成功仅表示已受理,不保证立即可读。可靠写入请用 fileToken 方式。
  231. **方式三:原样回传已有附件数据(保留 / 追加已有附件时使用)**
  232. 从 `query_records` 读出的 attachment 单元格数据是完整对象数组,字段形状如下:
  233. ```json
  234. [
  235. {
  236. "filename": "a.xlsx",
  237. "size": 92250,
  238. "type": "xls",
  239. "resourceId": "<id>",
  240. "resourceUrl": "<resourceUrl>"
  241. }
  242. ]
  243. ```
  244. 其中 `type` 是文件类别枚举,常见值为 `"xls"`、`"image"` 等;`resourceUrl` 通常为有时效的下载链接。
  245. 如需保留已有附件,把读出的值原样塞回即可。如需追加新附件,把新的 `{"fileToken":"ft_xxx"}` 与已有对象合并成一个数组一起传入。
  246. `update_records` 的 attachment 字段格式相同,传入后会整体覆盖该字段。
  247. ## 脚本
  248. ### 批量新增字段
  249. ```bash
  250. python3 scripts/bulk_add_fields.py <baseId> <tableId> fields.json
  251. ```
  252. `fields.json` 示例:
  253. ```json
  254. [
  255. {"fieldName":"任务名","type":"text"},
  256. {"fieldName":"优先级","type":"singleSelect","config":{"options":[{"name":"高"},{"name":"中"},{"name":"低"}]}}
  257. ]
  258. ```
  259. 兼容项:
  260. - `name` 会自动映射为 `fieldName`
  261. - `phone` 会自动映射为 `telephone`
  262. ### 批量导入记录
  263. ```bash
  264. python3 scripts/import_records.py <baseId> <tableId> data.csv
  265. python3 scripts/import_records.py <baseId> <tableId> data.json 50
  266. ```
  267. 说明:
  268. - CSV 表头默认按 `fieldId` 解释
  269. - JSON 支持:
  270. - `[{"cells": {...}}]`
  271. - `[{"fld_xxx": "value"}]`
  272. ## 安全规则
  273. - 文件路径受 `OPENCLAW_WORKSPACE` 沙箱限制
  274. - 仅允许读取工作区内 `.json` / `.csv` 文件
  275. - Base / Table / Field / Record ID 都做格式校验
  276. - 批量上限按 MCP server 实际限制控制:
  277. - `create_fields`:最多 15
  278. - `get_tables / get_fields`:最多 10
  279. - `create_records / update_records / delete_records`:最多 100
  280. ## 调试原则
  281. - 先 `get_base`,再 `get_tables`,必要时 `get_fields`
  282. - 不要猜 `fieldId`
  283. - 复杂参数一律用 `--args` JSON
  284. - `singleSelect / multipleSelect` 过滤时必须传 option ID,不是 option name
  285. ## 参考
  286. - API 参考:`references/api-reference.md`
  287. - 错误排查:`references/error-codes.md`
README.md · README · 67 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # dingtalk-ai-table(官方维护)
  2. 钉钉 AI 表格技能,已适配 **2026-03-10 发布的新版 MCP tools**。
  3. ClawHub 技能地址:https://clawhub.ai/aliramw/dingtalk-ai-table
  4. ## 🚀 快速开始
  5. **5 分钟内完成第一个操作:**
  6. ```bash
  7. # 1. 列出所有表格
  8. mcporter call "$DINGTALK_MCP_URL" .list_bases limit=5
  9. # 2. 创建新表格
  10. mcporter call "$DINGTALK_MCP_URL" .create_base baseName='我的项目'
  11. # 3. 查询记录
  12. mcporter call "$DINGTALK_MCP_URL" .query_records \
  13. --args '{"baseId":"base_xxx","tableId":"tbl_xxx","limit":10}'
  14. ```
  15. 👉 详见 `GETTING_STARTED.md`
  16. ## 📚 文档导航
  17. | 文档 | 用途 |
  18. |------|------|
  19. | `GETTING_STARTED.md` | 新手入门(推荐从这里开始) |
  20. | `SKILL.md` | 技能完整说明 |
  21. | `references/api-reference.md` | API 详细参考 |
  22. | `references/error-codes.md` | 常见错误排查 |
  23. | `examples/` | 7 个实战示例脚本 |
  24. ## 🛠️ 工具与脚本
  25. - `scripts/check-schema.sh` - 自动检查 MCP schema 版本
  26. - `scripts/bulk_add_fields.py` - 批量新增字段
  27. - `scripts/import_records.py` - 批量导入记录
  28. ## ✅ 依赖与环境
  29. - 必需二进制:`mcporter >= 0.8.1`、`python3`
  30. - 必需环境变量:`DINGTALK_MCP_URL`
  31. - 推荐环境变量:`OPENCLAW_WORKSPACE`(脚本文件沙箱)
  32. ## 🧪 测试
  33. ```bash
  34. python3 tests/test_security.py
  35. ```
  36. **测试覆盖**:25 项安全与功能测试,100% 通过
  37. ## 📋 核心特性
  38. - ✅ 新版 MCP schema:`baseId / tableId / fieldId / recordId`
  39. - ✅ 覆盖 20 个 MCP tools
  40. - ✅ 批量操作支持(字段、记录)
  41. - ✅ 完整的安全沙箱
  42. - ✅ 自动 schema 版本检查
  43. - ✅ 7 个实战示例
  44. - ✅ 详细的错误排查指南
  45. ## ⚠️ 注意
  46. 旧版脚本依赖 `dentryUuid / sheetIdOrName`,已废弃。必须使用新版 ID 体系。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.