dingtalk-sheets（钉钉表）

钉钉表格 Skill

Overview

用户可能要求你创建钉钉在线表格、管理工作表、读取单元格范围、写入指定区域、末尾追加行，或在工作表里查找数据。表格操作有明显依赖关系：通常要先拿到 nodeId，再拿到 sheetId，最后才能精准读写。

临时覆盖规则：禁用 append_rows

即使 MCP tools/list 仍然暴露了 append_rows，当前也要把它视为临时不可用。原因是上游服务存在不稳定情况，可能返回成功退出码但实际写入失败，或直接报 provider 错误。

处理“末尾追加几行 / 继续追加流水 / 新增一批记录”时，必须改用下面的回退流程：

1. get_sheet(nodeId, sheetId) 读取 lastNonEmptyRow
2. 根据待写入数据的行列数，计算下一段空白区域的 rangeAddress
3. update_range(nodeId, sheetId, rangeAddress, values) 完成追加效果

只有在明确验证 append_rows 恢复稳定后，才允许恢复直接调用。

严格禁止

1. 禁止编造 nodeId / sheetId -- 必须从工具返回值中提取，不能手写猜测
2. 禁止把钉钉文档当作钉钉表格处理 -- get_range / update_range 只支持在线电子表格，传文档类型会报错
3. 禁止忽略 range 与 sheetId 的覆盖关系 -- 当 range 自带 sheetId!A1:D10 前缀时，应以 range 里的工作表为准
4. 禁止在未确认目标工作表前直接写入 -- 不确定时先 get_all_sheets，必要时再 get_sheet
5. 禁止让 update_range.values 维度与 rangeAddress 不一致 -- 行列不匹配会导致写入失败或错位
6. 禁止直接调用 append_rows -- 当前上游服务不稳定；所有追加请求都必须改走 get_sheet + update_range
7. 禁止在追加行时忽略列对齐 -- 追加写入的列数应与现有表格结构保持一致
8. 禁止暴露敏感 MCP URL -- 凭证 URL 含访问令牌，只能写成占位符或环境变量名

可用方法列表

关键参数规则

1. nodeId 支持两种格式：

- https://alidocs.dingtalk.com/i/nodes/{dentryUuid} - 32 位字母数字 dentryUuid

1. sheetId 可传工作表 ID 或名称；不确定时先调 get_all_sheets
2. range 使用 A1 表示法，如 A1:D10
3. range 也可带工作表前缀，如 Sheet1!A1:D10 或 {sheetId}!A1:D10
4. update_range.hyperlinks 中每个单元格可传对象或 null
5. update_range.numberFormat 常见值：General、@、#,##0、#,##0.00、0%、yyyy/m/d

意图判断

用户说“创建一个表格 / 新建报表 / 建个在线表格”：

• 先用 create_workspace_sheet
• 若还要求建“汇总”“明细”等页签，再用 create_sheet

用户说“这个表格有哪些工作表 / 列一下 sheet”：

• 用 get_all_sheets

用户说“看看这个 sheet 有多少行 / 工作表详情 / 最后有数据的行列”：

• 用 get_sheet

用户说“读取 A1 到 D10 / 导出这个范围 / 看看整张表内容”：

• 用 get_range
• 如果没传 range，默认读取目标工作表全部非空数据

用户说“把这些数据写到 A1:C5 / 改单元格 / 设置百分比格式”：

• 用 update_range
• 先确认目标 sheetId 和 rangeAddress

用户说“在末尾追加几行 / 继续记流水 / 新增一批记录”：

• 先用 get_sheet 读取 lastNonEmptyRow
• 再用 update_range 写入下一段空白区域

用户说“找一下包含 XXX 的单元格 / 在公式里搜 / 忽略大小写查找”：

• 用 find_cells

核心工作流

创建表格并新建工作表：

1. create_workspace_sheet(name, folderId?, workspaceId?) → 提取 nodeId
2. create_sheet(nodeId, name="汇总") → 提取新增工作表标识
3. get_all_sheets(nodeId) → 回显当前工作表列表

读取指定范围：

1. get_all_sheets(nodeId) → 解析 sheetId
2. get_range(nodeId, sheetId, range="A1:D10") → 提取 values / formulas / displayValues

覆盖写入矩形区域：

1. get_all_sheets(nodeId) → 确认目标 sheetId
2. 组织 values 为二维数组，维度与 rangeAddress 保持一致
3. update_range(nodeId, sheetId, rangeAddress, values, hyperlinks?, numberFormat?)

末尾追加数据：

1. get_all_sheets(nodeId) → 确认目标 sheetId
2. get_sheet(nodeId, sheetId) → 提取 lastNonEmptyRow
3. 根据数据维度计算新的 rangeAddress
4. update_range(nodeId, sheetId, rangeAddress, values) → 提取实际写入范围

上下文传递规则

CRITICAL: 参数格式

// [正确] nodeId 可传 URL 或 dentryUuid
{"nodeId": "https://alidocs.dingtalk.com/i/nodes/abc123"}
{"nodeId": "abc123"}

// [正确] rangeAddress 与 values 维度一致
{"rangeAddress": "A1:B2", "values": [["1", "2"], ["3", "4"]]}

// [错误] 2x2 数据写进 1 列范围
{"rangeAddress": "A1:A2", "values": [["1", "2"], ["3", "4"]]}

// [正确] 带工作表前缀的 range
{"range": "Sheet1!A1:D10"}

本地文件脚本说明

scripts/ 目录中的辅助脚本会处理工作区内的本地表格文件：

• create_sheet.py：创建新的钉钉在线表格，可选追加创建一个工作表
• import_sheet.py：读取工作区内 .csv / .tsv，创建新表格或写入已有表格
• export_sheet.py：把钉钉表格指定工作表或范围导出为本地 .csv / .tsv

这些脚本都受以下规则约束：

• 仅允许访问工作区内路径
• 使用 resolve_safe_path() 防止目录遍历
• 限制文件大小、行列规模和扩展名
• 仅通过 mcporter 调用 MCP 服务，不直接发起业务 HTTP 请求

错误处理

1. 遇到错误：原样展示工具报错，不要编造“成功”
2. Invalid credentials：提示用户重新配置 DINGTALK_MCP_SHEETS_URL
3. Permission denied：提示用户确认目标表格或目标位置权限
4. “找不到工作表”：先 get_all_sheets，再根据名称或 ID 重试
5. “维度不匹配”：检查 rangeAddress 与 values / hyperlinks 的行列数
6. “跨组织不支持”：提示用户改为同组织内文档再操作

详细参考（按需读取）

• references/api-reference.md -- 真实工具入参与典型返回说明
• references/error-codes.md -- 常见错误与排查路径