写入钉钉AI表格 Skill (V1.0)

将数据自动写入钉钉 AI 表格（Notable 多维表格）。支持自定义凭证或使用内置默认值。

凭证配置 (可选输入)

本 Skill 内置了默认的钉钉应用凭证，用户无需提供即可直接使用。

如果用户有自己的凭证（不同的 appKey/appSecret/operatorId），可以在调用时传入自定义值覆盖默认值。

用户必须提供的参数 (必填项)

以下 3 项参数是每次写入操作必须由用户提供的：

1. baseId (必填)

• 含义: 目标多维表格的文档 ID
• 格式: 字符串，例如 "Gl6Pm2Db8D36x0PAt9DNYgv9JxLq0Ee4"
• 获取方式: 从钉钉多维表格的 URL 中提取

2. sheetIdOrName (必填)

• 含义: 目标工作表的 ID 或名称
• 格式: 字符串，可以是工作表名称（如 "数据表 1"）或工作表 ID
• 注意: 如果使用名称，需与钉钉中显示的工作表名完全一致

3. records (必填)

• 含义: 要写入的数据记录列表
• 格式: JSON 数组，每个元素是一个字典，key 为列名，value 为单元格值
• 示例格式:

[
  {
    "文本": "11",
    "违规内容": "22",
    "使用者": "33"
  },
  {
    "文本": "文本内容",
    "违规内容": "无违规",
    "使用者": "张三"
  }
]

• 注意事项:
• 每条记录的 key（列名）必须与钉钉表格中的列名完全一致
• value 的类型应与列的类型匹配（文本/数字/日期等）
• 可以一次写入多条记录

工作流程

当用户触发此 Skill 时，按以下步骤执行：

Step 1: 获取 AccessToken

• API: POST https://api.dingtalk.com/v1.0/oauth2/accessToken
• 请求头: Content-Type: application/json
• 请求体:

{
  "appKey": "<appKey>",
  "appSecret": "<appSecret>"
}

• 响应: 提取 accessToken 字段值

Step 2: 写入记录到表格

• API: POST https://api.dingtalk.com/v1.0/notable/bases/{baseId}/sheets/{sheetIdOrName}/records
• 请求头:
• Content-Type: application/json
• x-acs-dingtalk-access-token: Step 1 获取的 token
• 请求体:

{
  "baseId": "<baseId>",
  "operatorId": "<operatorId>",
  "records": [
    { "fields": "<JSON字符串化的字段字典>" },
    ...
  ],
  "sheetIdOrName": "<sheetIdOrName>"
}

Step 3: 输出结果

• 返回文档链接: https://alidocs.dingtalk.com/i/nodes/{baseId}

使用脚本执行

Skill 核心脚本位于 scripts/write_to_notable.py，支持两种运行方式：

CLI 方式

python scripts/write_to_notable.py \
  --base-id "Gl6Pm2Db8D36x0PAt9DNYgv9JxLq0Ee4" \
  --sheet "数据表 1" \
  --records '[{"文本":"内容","违规内容":"无","使用者":"张三"}]'

Library 方式

from scripts.write_to_notable import write_to_notable
result = write_to_notable(
    base_id="Gl6Pm2Db8D36x0PAt9DNYgv9JxLq0Ee4",
    sheet_id_or_name="数据表 1",
    records=[{"文本": "A", "违规内容": "B", "使用者": "C"}],
)
print(result["url"])

可选参数

错误处理

• Token 过期或无效：自动重新获取
• 网络错误：重试 3 次
• 列名不存在或类型错误：返回具体错误信息
• 权限不足：提示检查 operatorId 是否有该表格权限