dingtalk-ai-table
# 钉钉 AI 表格操作（新版 MCP）
## 🚀 5 分钟快速开始
### 1️⃣ 列出我的表格
```bash
mcporter call '<DINGTALK_MCP_URL>' .list_bases limit=5
```
### 2️⃣ 创建新表格
```bash
mcporter call '<DINGTALK_MCP_URL>' .create_base baseName='我的项目'
```
### 3️⃣ 添加记录
```bash
mcporter call '<DINGTALK_MCP_URL>' .create_records \
--args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_name":"张三"}}]}'
```
### 4️⃣ 查询记录
```bash
mcporter call '<DINGTALK_MCP_URL>' .query_records \
--args '{"baseId":"base_xxx","tableId":"tbl_xxx","limit":10}'
```
### 5️⃣ 批量导入
```bash
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 地址只需要强制检查一次。**
### 一次性检查策略
1. 先读取当前 `mcporter` 里 `dingtalk-ai-table` 对应的 MCP Server 地址。
2. 用这个地址生成一个本地检查标记（例如基于完整 URL 或其 hash）。
3. 在工作区保存检查结果，例如放到：
```text
~/.openclaw/workspace/.cache/dingtalk-ai-table/
```
建议文件名模式：
```text
schema-check-<url-hash>.json
```
4. 如果当前地址对应的检查标记已经存在，并且结果是“已确认新版 schema”，则**跳过重复检查**，直接继续后续 AI 表格操作。
5. 只有在以下情况才重新强制检查：
- 第一次运行，没有检查标记
- `mcporter` 里的 MCP Server 地址变了
- 之前检查结果是旧版 schema / 检查失败
- 用户明确要求重新验证
### 强制检查时执行
```bash
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 时的强制提示
此时必须明确提示用户：
1. 打开这个页面：
`https://mcp.dingtalk.com/#/detail?mcpId=9555&detailType=marketMcpDetail`
2. 点击右侧 **「获取 MCP Server 配置」** 按钮
3. 复制新的 MCP Server 地址
4. 用新的地址替换 `mcporter` 里已经注册的 `dingtalk-ai-table` 地址
5. 替换完成后，再重新执行：
```bash
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` 地址没变，就不要再重复做这一步守门检查。
### 用户提示文案（可直接复用）
```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，确认出现 list_bases / get_base / create_records 等新版 tools 后，再继续操作 AI 表格。
```
## 前置要求
### 安装 mcporter CLI
```bash
npm install -g mcporter
# 或
bun 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 "<Streamable_HTTP_URL>"
```
方式二：使用环境变量
```bash
export DINGTALK_MCP_URL="<Streamable_HTTP_URL>"
```
> 这个 URL 带访问令牌，等同密码，不要泄露。
### 工作区沙箱
脚本读取本地文件时，会优先使用 `OPENCLAW_WORKSPACE` 作为允许根目录：
```bash
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
```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 get_base baseId="base_xxx"
```
### 3. 再展开表结构
```bash
mcporter call dingtalk-ai-table get_tables \
--args '{"baseId":"base_xxx","tableIds":["tbl_xxx"]}'
```
### 4. 字段复杂时读完整配置
```bash
mcporter call dingtalk-ai-table get_fields \
--args '{"baseId":"base_xxx","tableId":"tbl_xxx","fieldIds":["fld_xxx"]}'
```
### 5. 再查 / 写记录
```bash
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（推荐，可靠）**
```bash
# 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）**
```bash
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 单元格数据是完整对象数组，字段形状如下：
```json
[
{
"filename": "a.xlsx",
"size": 92250,
"type": "xls",
"resourceId": "<id>",
"resourceUrl": "<resourceUrl>"
}
]
```
其中 `type` 是文件类别枚举，常见值为 `"xls"`、`"image"` 等；`resourceUrl` 通常为有时效的下载链接。
如需保留已有附件，把读出的值原样塞回即可。如需追加新附件，把新的 `{"fileToken":"ft_xxx"}` 与已有对象合并成一个数组一起传入。
`update_records` 的 attachment 字段格式相同，传入后会整体覆盖该字段。
## 脚本
### 批量新增字段
```bash
python3 scripts/bulk_add_fields.py <baseId> <tableId> fields.json
```
`fields.json` 示例：
```json
[
{"fieldName":"任务名","type":"text"},
{"fieldName":"优先级","type":"singleSelect","config":{"options":[{"name":"高"},{"name":"中"},{"name":"低"}]}}
]
```
兼容项：
- `name` 会自动映射为 `fieldName`
- `phone` 会自动映射为 `telephone`
### 批量导入记录
```bash
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`
标签
skill
ai
