dingtalk-ai-table

# 钉钉 AI 表格操作（新版 MCP）

按 **新版 MCP schema** 工作：
- Base：`baseId`
- Table：`tableId`
- Field：`fieldId`
- Record：`recordId`

不要再用旧版 `dentryUuid / sheetIdOrName / fieldIdOrName`。

## 版本守门规则（每个 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_r...

# dingtalk-ai-table

钉钉 AI 表格技能，已适配 **2026-03-10 发布的新版 MCP tools**。

## 依赖与环境声明

- 必需二进制：`mcporter`、`python3`
- 必需环境变量：`DINGTALK_MCP_URL`
- 推荐环境变量：`OPENCLAW_WORKSPACE`（脚本本地文件沙箱根目录）


## 本次升级重点

- 全面切换到新 schema：`baseId / tableId / fieldId / recordId`
- 覆盖 19 个 MCP tools
- 重写批量字段脚本
- 重写批量导入脚本
- 重写测试，当前 `21 / 21` 通过

## 目录

- `SKILL.md`：技能说明
- `references/api-reference.md`：新版 API 参考
- `references/error-codes.md`：错误排查
- `scripts/bulk_add_fields.py`：批量新增字段
- `scripts/import_records.py`：批量导入记录
- `tests/test_security.py`：安全与构造测试

## 测试

```bash
cd /Users/marila/Skills/dingtalk-ai-table
python3 tests/test_security.py
```

## 注意

旧版脚本依赖 `dentryUuid / sheetIdOrName`，现在已经废弃。后续调用必须使用新版 ID 体系。