5️⃣ 批量导入

核心概念

按 新版 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 地址只需要强制检查一次。

一次性检查策略

1. 1. 先读取当前 mcporter 里 dingtalk-ai-table 对应的 MCP Server 地址。
2. 用这个地址生成一个本地检查标记（例如基于完整 URL 或其 hash）。
3. 在工作区保存检查结果，例如放到：

text
~/.openclaw/workspace/.cache/dingtalk-ai-table/

建议文件名模式：

text
schema-check-.json

1. 4. 如果当前地址对应的检查标记已经存在，并且结果是“已确认新版 schema”，则跳过重复检查，直接继续后续 AI 表格操作。
2. 只有在以下情况才重新强制检查：

强制检查时执行

bash
mcporter list dingtalk-ai-table --schema

判断标准

如果返回的 tools 仍然是旧版这一套，例如出现：

• - getrootnodeofmydocument
• createbaseapp
• listbasetables
• addbaserecord
• searchbaserecord
• listbase_field

或者整体仍然基于：

• - dentryUuid
• sheetIdOrName
• fieldIdOrName

那么说明：虽然 skill 文件已经是新版，但 mcporter 里注册的 MCP server 地址还是旧的，不能继续操作。

遇到旧版 schema 时的强制提示

此时必须明确提示用户：

1. 1. 打开这个页面：

1. 2. 点击右侧 「获取 MCP Server 配置」 按钮
2. 复制新的 MCP Server 地址
3. 用新的地址替换 mcporter 里已经注册的 dingtalk-ai-table 地址
4. 替换完成后，再重新执行：

bash
mcporter list dingtalk-ai-table --schema

只有当返回的 tools 已经变成新版 schema，例如出现：

• - listbases
• getbase
• gettables
• getfields
• queryrecords
• createrecords
• updaterecords
• deleterecords
• prepareattachmentupload

才允许继续真正的 AI 表格操作。

通过检查后的处理

一旦确认当前 MCP Server 地址返回的是新版 schema，就把结果写入本地检查标记。后续只要 mcporter 里的 dingtalk-ai-table 地址没变，就不要再重复做这一步守门检查。

用户提示文案（可直接复用）

text
当前 mcporter 里注册的 dingtalk-ai-table 还是旧版 MCP schema，暂时不能按新版技能操作。
请打开 https://mcp.dingtalk.com/#/detail?mcpId=9555&detailType=marketMcpDetail ，点击右侧“获取 MCP Server 配置”按钮，复制新的 MCP Server 地址，并替换 mcporter 里已注册的 dingtalk-ai-table 地址。替换后重新检查 schema，确认出现 listbases / getbase / create_records 等新版 tools 后，再继续操作 AI 表格。

前置要求

安装 mcporter CLI

bash
npm install -g mcporter

或

验证：

bash
mcporter --version

配置 MCP Server

在钉钉 MCP 广场 https://mcp.dingtalk.com/#/detail?mcpId=9555&detailType=marketMcpDetail 获取新版钉钉 AI 表格 MCP 的 Streamable HTTP URL。

方式一：直接配置到 mcporter

bash
mcporter config add dingtalk-ai-table --url HTTPURL>

方式二：使用环境变量

bash
export DINGTALKMCPURL=HTTPURL>

这个 URL 带访问令牌，等同密码，不要泄露。

工作区沙箱

脚本读取本地文件时，会优先使用 OPENCLAW_WORKSPACE 作为允许根目录：

bash
export OPENCLAW_WORKSPACE=$HOME/.openclaw/workspace

未设置时默认使用当前工作目录。

核心工具集

Base 层

• - listbases
• searchbases
• getbase
• createbase
• updatebase
• deletebase
• search_templates

Table 层

• - gettables
• createtable
• updatetable
• deletetable

Field 层

• - getfields
• createfields
• updatefield
• deletefield

Record 层

• - queryrecords
• createrecords
• updaterecords
• deleterecords

附件层

• - prepareattachmentupload

推荐工作流

1. 先找 Base

bash
mcporter call dingtalk-ai-table list_bases limit=10
mcporter call dingtalk-ai-table search_bases query=销售

2. 再拿 Table 目录

bash
mcporter call dingtalk-ai-table getbase baseId=basexxx

3. 再展开表结构

bash
mcporter call dingtalk-ai-table get_tables \
--args {baseId:basexxx,tableIds:[tblxxx]}

4. 字段复杂时读完整配置

bash
mcporter call dingtalk-ai-table get_fields \
--args {baseId:basexxx,tableId:tblxxx,fieldIds:[fld_xxx]}

5. 再查 / 写记录

bash
mcporter call dingtalk-ai-table query_records \
--args {baseId:basexxx,tableId:tblxxx,limit:20}

mcporter call dingtalk-ai-table create_records \
--args {baseId:basexxx,tableId:tblxxx,records:[{cells:{fld_name:张三}}]}

6. 写入附件字段

attachment 字段支持三种写法：

方式一：先上传，再写 fileToken（推荐，可靠）

bash

Step 1：申请上传地址（返回 uploadUrl 和 fileToken）

Step 2：把文件 PUT 到 uploadUrl（必须带 Content-Type，值必须与 mimeType 完全一致）