dingtalk-ai-table

name dingtalk-ai-table description 钉钉 AI 表格（多维表）操作技能。使用 mcporter CLI 连接钉钉官方新版 AI 表格 MCP server，基于 baseId / tableId / fieldId / recordId 体系执行 Base、Table、Field、Record 的查询与增删改。适用于创建 AI 表格、搜索表格、读取表结构、批量增删改记录、批量建字段、更新字段配置、按模板建表等场景。需要配置 DINGTALK_MCP_URL 或直接使用 Streamable HTTP URL。 version 0.6.0 metadata {"author":"Marila@Dingtalk","category":"productivity","tags":["dingtalk","spreadsheet","mcp","automation","data-management"],"documentation":"https://github.com/aliramw/dingtalk-ai-table","support":"https://github.com/aliramw/dingtalk-ai-table/issues","openclaw":{"requires":{"env":"[Truncated]","bins":"[Truncated]"},"primaryEnv":"DINGTALK_MCP_URL","homepage":"https://github.com/aliramw/dingtalk-ai-table"}} 钉钉 AI 表格操作（新版 MCP） 🚀 5 分钟快速开始 1️⃣ 列出我的表格 mcporter call '<DINGTALK_MCP_URL>' .list_bases limit =5 2️⃣ 创建新表格 mcporter call '<DINGTALK_MCP_URL>' .create_base baseName= '我的项目' 3️⃣ 添加记录 mcporter call '<DINGTALK_MCP_URL>' .create_records \ --args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_name":"张三"}}]}' 4️⃣ 查询记录 mcporter call '<DINGTALK_MCP_URL>' .query_records \ --args '{"baseId":"base_xxx","tableId":"tbl_xxx","limit":10}' 5️⃣ 批量导入 python3 scripts/import_records.py base_xxx tbl_xxx data.csv 核心概念 按 新版 MCP schema 工作： Base： baseId Table： tableId Field： fieldId Record： recordId 不要再用旧版 dentryUuid / sheetIdOrName / fieldIdOrName 。 推荐使用 mcporter 0.8.1 及以上版本。 输出模式兼容说明： mcporter 0.8.1+ 可直接调用 更低版本需要显式加 --output text AI 表格 MCP 无论使用哪种模式，返回体本身都是标准 JSON；差异主要在 mcporter 的输出处理方式 版本守门规则（每个 MCP Server 地址只强制检查一次） 在真正开始任何 AI 表格操作前，必须先检查当前 mcporter 注册的 dingtalk-ai-table MCP server 实际返回的 tools schema。 但这个检查不该每次都重复做；同一个 MCP Server 地址只需要强制检查一次。 一次性检查策略 先读取当前 mcporter 里 dingtalk-ai-table 对应的 MCP Server 地址。 用这个地址生成一个本地检查标记（例如基于完整 URL 或其 hash）。 在工作区保存检查结果，例如放到： ~/.openclaw/workspace/.cache/dingtalk-ai-table/ 建议文件名模式： schema-check-<url-hash>.json 如果当前地址对应的检查标记已经存在，并且结果是“已确认新版 schema”，则 跳过重复检查 ，直接继续后续 AI 表格操作。 只有在以下情况才重新强制检查： 第一次运行，没有检查标记 mcporter 里的 MCP Server 地址变了 之前检查结果是旧版 schema / 检查失败 用户明确要求重新验证 强制检查时执行 mcporter list dingtalk-ai-table --schema 判断标准 如果返回的 tools 仍然是旧版这一套，例如出现： get_root_node_of_my_document create_base_app list_base_tables add_base_record search_base_record list_base_field 或者整体仍然基于： dentryUuid sheetIdOrName fieldIdOrName 那么说明： 虽然 skill 文件已经是新版，但 mcporter 里注册的 MCP server 地址还是旧的，不能继续操作。 遇到旧版 schema 时的强制提示 此时必须明确提示用户： 打开这个页面： https://mcp.dingtalk.com/#/detail?mcpId=9555&detailType=marketMcpDetail 点击右侧 「获取 MCP Server 配置」 按钮 复制新的 MCP Server 地址 用新的地址替换 mcporter 里已经注册的 dingtalk-ai-table 地址 替换完成后，再重新执行： mcporter list dingtalk-ai-table --schema 只有当返回的 tools 已经变成新版 schema，例如出现： list_bases get_base get_tables get_fields query_records create_records update_records delete_records prepare_attachment_upload 才允许继续真正的 AI 表格操作。 通过检查后的处理 一旦确认当前 MCP Server 地址返回的是新版 schema，就把结果写入本地检查标记。后续只要 mcporter 里的 dingtalk-ai-table 地址没变，就不要再重复做这一步守门检查。 用户提示文案（可直接复用） 当前 mcporter 里注册的 dingtalk-ai-table 还是旧版 MCP schema，暂时不能按新版技能操作。 请打开 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 表格。 前置要求 安装 mcporter CLI npm install -g mcporter # 或 bun install -g mcporter 验证： mcporter --version 配置 MCP Server 在钉钉 MCP 广场 https://mcp.dingtalk.com/#/detail?mcpId=9555&detailType=marketMcpDetail 获取新版钉钉 AI 表格 MCP 的 Streamable HTTP URL 。 方式一：直接配置到 mcporter mcporter config add dingtalk-ai-table --url "<Streamable_HTTP_URL>" 方式二：使用环境变量 export DINGTALK_MCP_URL= "<Streamable_HTTP_URL>" 这个 URL 带访问令牌，等同密码，不要泄露。 工作区沙箱 脚本读取本地文件时，会优先使用 OPENCLAW_WORKSPACE 作为允许根目录： export OPENCLAW_WORKSPACE= " $HOME /.openclaw/workspace" 未设置时默认使用当前工作目录。 核心工具集 Base 层 list_bases search_bases get_base create_base update_base delete_base search_templates Table 层 get_tables create_table update_table delete_table Field 层 get_fields create_fields update_field delete_field Record 层 query_records create_records update_records delete_records 附件层 prepare_attachment_upload 推荐工作流 1. 先找 Base mcporter call dingtalk-ai-table list_bases limit =10 mcporter call dingtalk-ai-table search_bases query= "销售" 2. 再拿 Table 目录 mcporter call dingtalk-ai-table get_base baseId= "base_xxx" 3. 再展开表结构 mcporter call dingtalk-ai-table get_tables \ --args '{"baseId":"base_xxx","tableIds":["tbl_xxx"]}' 4. 字段复杂时读完整配置 mcporter call dingtalk-ai-table get_fields \ --args '{"baseId":"base_xxx","tableId":"tbl_xxx","fieldIds":["fld_xxx"]}' 5. 再查 / 写记录 mcporter call dingtalk-ai-table query_records \ --args '{"baseId":"base_xxx","tableId":"tbl_xxx","limit":20}' mcporter call dingtalk-ai-table create_records \ --args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_name":"张三"}}]}' 6. 写入附件字段 attachment 字段支持三种写法： 方式一：先上传，再写 fileToken（推荐，可靠） # Step 1：申请上传地址（返回 uploadUrl 和 fileToken） mcporter call dingtalk-ai-table prepare_attachment_upload \ --args '{"baseId":"base_xxx","fileName":"report.pdf","size":102400,"mimeType":"application/pdf"}' # Step 2：把文件 PUT 到 uploadUrl（必须带 Content-Type，值必须与 mimeType 完全一致） curl -X PUT "<uploadUrl>" \ -H "Content-Type: application/pdf" \ --data-binary @report.pdf # Step 3：把 fileToken 写入记录 mcporter call dingtalk-ai-table create_records \ --args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_attach":[{"fileToken":"ft_xxx"}]}}]}' 方式二：直接传外链 URL（异步转存，best-effort） mcporter call dingtalk-ai-table create_records \ --args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_attach":[{"url":"https://example.com/file.pdf"}]}}]}' URL 转存是 best-effort 异步链路，返回成功仅表示已受理，不保证立即可读。可靠写入请用 fileToken 方式。 方式三：原样回传已有附件数据（保留 / 追加已有附件时使用） 从 query_records 读出的 attachment 单元格数据是完整对象数组，字段形状如下： [ { "filename" : "a.xlsx" , "size" : 92250 , "type" : "xls" , "resourceId" : "<id>" , "resourceUrl" : "<resourceUrl>" } ] 其中 type 是文件类别枚举，常见值为 "xls" 、 "image" 等； resourceUrl 通常为有时效的下载链接。 如需保留已有附件，把读出的值原样塞回即可。如需追加新附件，把新的 {"fileToken":"ft_xxx"} 与已有对象合并成一个数组一起传入。 update_records 的 attachment 字段格式相同，传入后会整体覆盖该字段。 脚本 批量新增字段 python3 scripts/bulk_add_fields.py <baseId> <tableId> fields.json fields.json 示例： [ { "fieldName" : "任务名" , "type" : "text" } , { "fieldName" : "优先级" , "type" : "singleSelect" , "config" : { "options" : [ { "name" : "高" } , { "name" : "中" } , { "name" : "低" } ] } } ] 兼容项： name 会自动映射为 fieldName phone 会自动映射为 telephone 批量导入记录 python3 scripts/import_records.py <baseId> <tableId> data.csv python3 scripts/import_records.py <baseId> <tableId> data.json 50 说明： CSV 表头默认按 fieldId 解释 JSON 支持： [{"cells": {...}}] [{"fld_xxx": "value"}] 安全规则 文件路径受 OPENCLAW_WORKSPACE 沙箱限制 仅允许读取工作区内 .json / .csv 文件 Base / Table / Field / Record ID 都做格式校验 批量上限按 MCP server 实际限制控制： create_fields ：最多 15 get_tables / get_fields ：最多 10 create_records / update_records / delete_records ：最多 100 调试原则 先 get_base ，再 get_tables ，必要时 get_fields 不要猜 fieldId 复杂参数一律用 --args JSON singleSelect / multipleSelect 过滤时必须传 option ID，不是 option name 参考 API 参考： references/api-reference.md 错误排查： references/error-codes.md