# Dingtalk AI Table > 钉钉 AI 表格（多维表）操作技能。使用 mcporter CLI 连接钉钉 MCP server 执行表格创建、数据表管理、字段操作、记录增删改查。需要配置 DINGTALK_MCP_URL 凭证。使用场景：创建 AI 表格、管理数据表结构、批量导入导出数据、自动化库存/项目管理等表格操作任务。 - Skill: `modbender/dingtalk-ai-table` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add modbender/dingtalk-ai-table` - Raw SKILL.md: https://api.skillmd.com/api/skills/modbender/dingtalk-ai-table/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: modbender (https://skillmd.com/u/modbender) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/modbender/dingtalk-ai-table --- # 钉钉 AI 表格操作 通过 MCP 协议连接钉钉 AI 表格 API，执行表格和数据操作。 ## ⚠️ 安全须知 **安装前请阅读：** 1. **本技能需要外部 CLI 工具** - 需安装 `mcporter` (npm/bun 全局安装) 2. **需要配置认证凭证** - Streamable HTTP URL 包含访问令牌，请妥善保管 3. **脚本审查建议** - `scripts/` 目录包含 Python 辅助脚本，建议先审查再运行 4. **测试环境优先** - 首次使用建议在测试表格中验证，确认无误后再操作生产数据 ### 🔒 安全加固措施（v0.3.4+） 脚本已实施以下安全保护： | 保护措施 | 说明 | |----------|------| | **路径沙箱** | `resolve_safe_path()` 防止目录遍历攻击，限制文件访问在 `OPENCLAW_WORKSPACE` 内 | | **UUID 验证** | 严格验证 dentryUuid 格式，防止无效输入 | | **文件扩展名白名单** | 仅允许 `.json` / `.csv` 文件 | | **文件大小限制** | JSON 最大 10MB，CSV 最大 50MB，防止 DoS | | **字段类型白名单** | 仅允许预定义的字段类型 | | **命令超时** | mcporter 命令超时限制（60-120 秒） | | **输入清理** | 自动去除空白、验证空值 | **配置建议：** ```bash # 设置工作目录限制（推荐） export OPENCLAW_WORKSPACE=/Users/marila/.openclaw/workspace ``` ## 前置要求 ### 安装 mcporter CLI 本技能依赖 `mcporter` 工具。安装前请确认来源可信： - **官方仓库**: https://github.com/mcporter/mcporter (请验证) - **npm 包**: `npm install -g mcporter` ```bash # 使用 npm 安装 npm install -g mcporter # 或使用 bun 安装 bun install -g mcporter ``` 验证安装： ```bash mcporter --version ``` > **注意**: 全局安装的 CLI 工具具有用户级执行权限，请确保从可信来源安装。 ### 配置 MCP Server **获取 Streamable HTTP URL：** 1. 访问钉钉 MCP 广场：https://mcp.dingtalk.com/#/detail?mcpId=1060&detailType=marketMcpDetail 2. 在页面**右侧**点击“获取 MCP Server 配置”按钮，然后找到 `Streamable HTTP URL` 3. 复制该 URL 并用于下方配置 **方式一：使用 mcporter config（推荐）** ```bash # 添加钉钉 AI 表格服务器配置（持久化存储） mcporter config add dingtalk-ai-table --url "" ``` **方式二：使用环境变量** ```bash # 临时设置（当前终端会话有效） export DINGTALK_MCP_URL="" ``` 将 `` 替换为实际获取的完整 URL。 > **⚠️ 凭证安全**: Streamable HTTP URL 包含访问令牌，等同于密码： > - 不要提交到版本控制系统 > - 不要分享给他人 > - 推荐使用 `mcporter config` 持久化存储，避免在命令历史中暴露 ### 基本命令模式 所有操作通过 `mcporter call dingtalk-ai-table ` 执行： ```bash # 获取文档根节点 mcporter call dingtalk-ai-table get_root_node_of_my_document --output json # 创建 AI 表格 mcporter call dingtalk-ai-table create_base_app filename="表格名" target="" --output json # 搜索可访问的表格 mcporter call dingtalk-ai-table search_accessible_ai_tables keyword="关键词" --output json ``` ## 核心工作流 ### 创建表格并初始化 ```bash # 1. 获取根节点 ROOT_UUID=$(mcporter call dingtalk-ai-table get_root_node_of_my_document --output json | jq -r '.rootDentryUuid') # 2. 创建表格 mcporter call dingtalk-ai-table create_base_app filename="我的表格" target="$ROOT_UUID" --output json # 3. 记录返回的 dentryUuid 用于后续操作 ``` ### 数据表操作 ```bash # 创建数据表（可带初始字段） mcporter call dingtalk-ai-table add_base_table \ --args '{"dentryUuid":"<表格 UUID>","name":"新数据表","fields":[{"name":"字段 1","type":"text"},{"name":"字段 2","type":"number"}]}' \ --output json # 列出所有数据表 mcporter call dingtalk-ai-table list_base_tables dentry-uuid="<表格 UUID>" --output json # 重命名数据表 mcporter call dingtalk-ai-table update_base_tables \ --args '{"dentryUuid":"","oldSheetIdOrName":"原表名","newName":"新表名"}' \ --output json # 删除数据表 mcporter call dingtalk-ai-table delete_base_table \ --args '{"dentryUuid":"","sheetIdOrName":"表名"}' \ --output json ``` ### 字段操作 ```bash # 查看字段列表 mcporter call dingtalk-ai-table list_base_field \ --args '{"dentryUuid":"","sheetIdOrName":"表名"}' \ --output json # 添加字段（支持类型：text, number, singleSelect, multipleSelect, date, user, attachment） mcporter call dingtalk-ai-table add_base_field \ --args '{"dentryUuid":"","sheetIdOrName":"表名","addField":{"name":"字段名","type":"text"}}' \ --output json # 删除字段 mcporter call dingtalk-ai-table delete_base_field \ --args '{"dentryUuid":"","sheetIdOrName":"表名","fieldIdOrName":"字段名"}' \ --output json ``` ### 记录操作 ```bash # 查询记录 mcporter call dingtalk-ai-table search_base_record \ --args '{"dentryUuid":"","sheetIdOrName":"表名"}' \ --output json # 添加记录 mcporter call dingtalk-ai-table add_base_record \ --args '{"dentryUuid":"","sheetIdOrName":"表名","records":[{"fields":{"字段 1":"值 1","字段 2":100}}]}' \ --output json # 更新记录 mcporter call dingtalk-ai-table update_records \ --args '{"dentryUuid":"","sheetIdOrName":"表名","records":[{"id":"记录 ID","fields":{"字段":"新值"}}]}' \ --output json # 删除记录 mcporter call dingtalk-ai-table delete_base_record \ --args '{"dentryUuid":"","sheetIdOrName":"表名","recordIds":["记录 ID1","记录 ID2"]}' \ --output json ``` ## 支持的字段类型 | 类型 | 说明 | 示例 | |------|------|------| | `text` | 文本 | `{"name":"姓名","type":"text"}` | | `number` | 数字 | `{"name":"数量","type":"number"}` | | `singleSelect` | 单选 | `{"name":"状态","type":"singleSelect"}` | | `multipleSelect` | 多选 | `{"name":"标签","type":"multipleSelect"}` | | `date` | 日期 | `{"name":"日期","type":"date"}` | | `user` | 人员 | `{"name":"负责人","type":"user"}` | | `attachment` | 附件 | `{"name":"文件","type":"attachment"}` | ## 使用脚本 对于批量操作，使用 `scripts/` 目录中的工具脚本： ```bash # 批量添加字段 python scripts/bulk_add_fields.py fields.json # 批量导入记录（支持 CSV 和 JSON） python scripts/import_records.py data.csv python scripts/import_records.py data.json [batch_size] ``` > **🔒 脚本安全特性**: > - ✅ 路径沙箱：防止目录遍历攻击（`../etc/passwd` 等） > - ✅ UUID 格式验证：严格校验输入格式 > - ✅ 文件扩展名白名单：仅允许 `.json` / `.csv` > - ✅ 文件大小限制：JSON 10MB / CSV 50MB > - ✅ 字段类型白名单：防止无效类型注入 > - ✅ 命令超时保护：60-120 秒自动终止 > > **测试验证**: 运行 `python3 tests/test_security.py` 执行 25 项安全测试 > > **⚠️ 注意事项**: > - 脚本仅调用 `mcporter` 命令和处理本地文件，无网络请求 > - 首次运行前建议审查脚本源码 > - 处理敏感数据时请在受控环境中执行 ## 参考文档 - **API 详情**: 见 [references/api-reference.md](references/api-reference.md) - **错误码说明**: 见 [references/error-codes.md](references/error-codes.md) ## 注意事项 1. **dentryUuid 识别**: 创建表格后返回多个 ID，使用 `uuid` 字段作为 `dentryUuid` 参数 2. **表名匹配**: 默认创建的表名为"数据表"，操作前需确认实际表名 3. **字段值格式**: 单选/多选字段返回对象格式 `{"name":"选项","id":"xxx"}` 4. **日期格式**: 日期字段使用 Unix 时间戳（毫秒）或 `YYYY-MM-DD` 格式 5. **批量操作**: 添加/删除记录支持批量，单次最多 1000 条