dingtalk-ai-table by breath57/dingtalk-skills
npx skills add https://github.com/breath57/dingtalk-skills --skill dingtalk-ai-table负责钉钉 AI 表格(.able 格式多维表格)的所有操作,通过钉钉开放平台 Notable API 实现。
核心概念:
.able 文件):多维表格,使用 Notable API(/v1.0/notable),不是 普通电子表格text、number、date 等)API 详情见 references/api.md。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
~/.dingtalk-skills/config(跨会话保留,所有 dingtalk-skills 共用同一文件)
| 键 | 说明 | 来源 |
|---|---|---|
DINGTALK_APP_KEY | 钉钉应用 appKey | 开放平台 → 应用管理 → 凭证信息 |
DINGTALK_APP_SECRET | 钉钉应用 appSecret | 同上 |
DINGTALK_OPERATOR_ID | 操作人 unionId | 见下方"为什么需要 operatorId"章节 |
DINGTALK_AI_TABLE_BASE_ID | AI 表格的 nodeId | 从 AI 表格分享链接提取 |
~/.dingtalk-skills/config 是否存在,解析已有键值需要以下信息才能继续(已有的无需再填):
* 钉钉应用 appKey(钉钉开放平台 → 应用管理 → 凭证信息) * 钉钉应用 appSecret * AI 表格链接(用于提取 base_id) * 你的钉钉 userId 或 unionId(以便以你的身份操作表格)
注意 :
APP_KEY/APP_SECRET/OPERATOR_ID属于凭证,禁止在输出中完整打印,确认时仅显示前 4 位 +****。
每次调用 API 前,用 appKey/appSecret 获取当次的 accessToken(有效期 2 小时):
POST https://api.dingtalk.com/v1.0/oauth2/accessToken
Content-Type: application/json
{ "appKey": "<应用 appKey>", "appSecret": "<应用 appSecret>" }
所有请求需携带:
x-acs-dingtalk-access-token: <accessToken>operatorId=<用户 unionId>(所有写操作及部分读操作必须)钉钉文档系统中每个文件(文档、表格、AI 表格)都有一个全局唯一的 nodeId ,即 base_id。它的作用类似数据库主键——API 通过它定位到具体是哪个 AI 表格文件,因为账号下可能有多个 .able 文件。
从链接提取 base_id:
https://alidocs.dingtalk.com/i/nodes/<base_id>?...
↑ 这一段就是 base_id
请用户提供 AI 表格的分享链接,从 /nodes/ 后截取 ID 片段。首次获取后写入 config,后续无需再问。
钉钉开放平台要求所有写操作 必须代表一个真实用户身份执行,而不是以匿名应用身份操作。operatorId 就是声明"这个操作是谁做的"——它会被记录到变更日志、触发对应用户的通知,并用于权限校验。
unionId (钉钉跨组织唯一 ID),不是 userId(仅组织内唯一)方法一:已知 userId → 换取 unionId(最常用)
userId 通常可从通讯录、免登、消息回调等场景直接获得。
第一步:获取旧式 access_token(与新版 accessToken 不同,此处单独获取):
GET https://oapi.dingtalk.com/gettoken?appkey=<appKey>&appsecret=<appSecret>
返回:{ "access_token": "xxx", "expires_in": 7200 }
第二步:用 userId 查询用户详情,取出 unionId:
POST https://oapi.dingtalk.com/topapi/v2/user/get?access_token=<旧式token>
Content-Type: application/json
{ "userid": "<钉钉 userId>" }
返回字段 result.unionid(无下划线)即为 unionId。
注意:
result.union_id(有下划线)在专属钉钉组织中可能为空,请使用result.unionid。
方法二:机器人/消息场景
用户通过钉钉机器人或消息触发时,消息体中直接包含 senderUnionId 字段,可直接作为 operatorId 使用,无需额外查询。
方法三:直接询问用户
若上述方式不可用,在初始配置阶段询问用户提供 userId 或 unionId(均可在钉钉个人信息页查看)。获取后写入 config,后续操作无需重复获取。
GET https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets?operatorId={operatorId}
x-acs-dingtalk-access-token: <accessToken>
返回:
{
"value": [
{ "id": "HAcL4SD", "name": "项目" },
{ "id": "nr2iEiW", "name": "任务" }
]
}
GET https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}?operatorId={operatorId}
返回:{ "id": "HAcL4SD", "name": "项目" }
POST https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets?operatorId={operatorId}
Content-Type: application/json
{
"name": "新工作表名称",
"fields": [
{ "name": "标题", "type": "text" },
{ "name": "数量", "type": "number" }
]
}
fields 可选(不传则创建空工作表)。
返回:{ "id": "新sheetId", "name": "新工作表名称" }
DELETE https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}?operatorId={operatorId}
返回:{ "success": true }
⚠️ 不可恢复,执行前需用户确认。
GET https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}/fields?operatorId={operatorId}
返回:
{
"value": [
{ "id": "6mNRNHb", "name": "标题", "type": "text" },
{ "id": "BDGLCo2", "name": "截止日期", "type": "date", "property": { "formatter": "YYYY-MM-DD" } },
{ "id": "mr8APlG", "name": "数量", "type": "number", "property": { "formatter": "INT" } }
]
}
POST https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}/fields?operatorId={operatorId}
Content-Type: application/json
{
"name": "字段名称",
"type": "number"
}
type 常用值:text(文本)、number(数字)、date(日期)
返回:{ "id": "新fieldId", "name": "字段名称", "type": "number", "property": { "formatter": "INT" } }
PUT https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}/fields/{field_id}?operatorId={operatorId}
Content-Type: application/json
{
"name": "新字段名称"
}
返回:{ "id": "fieldId" }(通过重新查询列表确认名称已变更)
DELETE https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}/fields/{field_id}?operatorId={operatorId}
返回:{ "success": true }
⚠️ 删除字段会同时删除该列所有数据,执行前需用户确认。
POST https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}/records?operatorId={operatorId}
Content-Type: application/json
{
"records": [
{ "fields": { "标题": "任务一", "数量": 3 } },
{ "fields": { "标题": "任务二", "数量": 5 } }
]
}
fields 中使用字段名称 (非 ID)作为键。
返回:{ "value": [{ "id": "记录ID1" }, { "id": "记录ID2" }] }
POST https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}/records/list?operatorId={operatorId}
Content-Type: application/json
{
"maxResults": 20,
"nextToken": ""
}
返回:
{
"records": [
{
"id": "RNXU1Vm2L2",
"fields": { "标题": "任务一", "数量": 3 },
"createdTime": 1772723541439,
"createdBy": { "unionId": "xxx" },
"lastModifiedTime": 1772723541439,
"lastModifiedBy": { "unionId": "xxx" }
}
],
"hasMore": false,
"nextToken": ""
}
翻页:上次响应 hasMore=true 时,将 nextToken 传入下次请求。
PUT https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}/records?operatorId={operatorId}
Content-Type: application/json
{
"records": [
{ "id": "记录ID", "fields": { "标题": "新标题" } }
]
}
返回:{ "value": [{ "id": "记录ID" }] }
只传需要修改的字段,未传字段保持不变。
POST https://api.dingtalk.com/v1.0/notable/bases/{base_id}/sheets/{sheet_id}/records/delete?operatorId={operatorId}
Content-Type: application/json
{
"recordIds": ["记录ID1", "记录ID2"]
}
返回:{ "success": true }
GET /sheets 获取工作表列表GET /sheets 找到目标工作表的 sheet_idGET /fields 了解现有字段名称和类型POST /records 批量插入,fields 中用字段名称作键GET /sheets 找到 sheet_idPOST /records/list 翻页获取所有记录POST /records/list 定位目标记录(让用户确认)POST /records/delete 传入 recordIdGET /sheets 找到 sheet_idPOST /fields,{ "name": "备注", "type": "text" }| type | 含义 |
|---|---|
text | 纯文本 |
number | 数字(含 property.formatter:INT、PERCENT 等) |
date | 日期(含 property.formatter:如 YYYY-MM-DD) |
| HTTP 状态码 / code | 含义 | 处理方式 |
|---|---|---|
| 401 | token 过期 | 重新获取 accessToken |
| 403 | 权限不足 | 检查应用是否开通 Notable 相关权限 |
invalidRequest.document.notFound | base_id 无效或无权访问 | 确认 AI 表格 nodeId 正确且已授权 |
| 404 | 工作表或字段不存在 | 确认 sheet_id / field_id 正确 |
| 429 | 触发限流 | 等待 1 秒后重试 |
Weekly Installs
20
Repository
GitHub Stars
1
First Seen
4 days ago
Security Audits
Installed on
github-copilot20
gemini-cli19
amp19
cline19
codex19
kimi-cli19
Skills CLI 使用指南:AI Agent 技能包管理器安装与管理教程
33,600 周安装
Plisio自动化集成:通过Rube MCP实现加密货币支付自动化操作
1 周安装
Plain自动化工具包:通过Rube MCP实现客户支持平台Plain的自动化操作
1 周安装
Pipeline CRM自动化工具:通过Rube MCP和Composio实现CRM操作自动化
1 周安装
Supabase Auth 身份验证技能:邮箱密码注册登录、会话管理、用户元数据操作
145 周安装
piggy-automation自动化技能 - Claude AI集成与工作流自动化工具
1 周安装
People Data Labs自动化技能 - 集成Claude AI与数据API的自动化工具
1 周安装