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`。

方式一：直接配置到 mcpor