很多团队已经在用钉钉在线表格维护项目进度、周报、客户线索、问题清单或运营数据。
但当我们想把这些数据接入自动化脚本、AI Agent 或内部工作流时，常见问题就来了：
- 表格数据适合人维护，但不适合程序稳定消费；
- 直接复制粘贴给 AI，容易混入隐私数据，也不可追溯；
- 业务人员习惯继续用表格，开发者又希望拿到 JSON / CSV / Markdown；
- AI 工作流需要稳定输入，而不是每次手工整理一遍。
这篇文章用一个非官方 Python CLI 示例，演示如何通过钉钉在线表格 OpenAPI 读取 Sheet，并导出成 JSON、CSV、Markdown。最后再加一点 AI：把钉钉在线表格作为 AI Agent / Hermes 工作流的数据入口，用于周报生成、风险识别和任务摘要。
说明：本文示例只使用钉钉开放平台公开 OpenAPI，不包含任何账号凭证，不绕过权限控制，也不使用真实公司数据。文中的表格、人员、项目名都是合成示例。
一、为什么先做 CLI，而不是直接让 AI 读表格？
AI Agent 最怕两件事：
如果直接把在线表格链接交给 AI，让它自己想办法读，调试和审计都会变得困难。更稳妥的方式是把链路拆开：
钉钉在线表格
-> Python CLI 读取指定 Sheet / Range
-> 导出 JSON / CSV / Markdown
-> 脱敏、清洗、字段归一化
-> AI Agent / Hermes 工作流处理
-> 输出周报、风险摘要、任务提醒或 HTML 报告
这样做的好处是：
- 表格仍然由业务人员维护；
- CLI 只访问授权范围内的数据；
- AI 只消费结构化后的输入；
- 每次运行都可以留下输入文件和输出报告，方便追溯；
- 后续可以把同一份数据接入多个工作流。
二、工具能力概览
这个 CLI 示例工具做了几件最小但实用的事情：
- 从 alidocs.dingtalk.com/i/nodes/… 链接中提取 nodeId；
- 使用钉钉内部应用的 appKey / appSecret 获取访问令牌；
- 列出一个在线表格里的 sheet 页；
- 读取指定 sheet 的单元格区域，例如 A1:E20；
- 将读取结果输出为 JSON、CSV 或 Markdown；
- 写入命令默认拒绝执行，必须显式传入 –yes。
这个边界很重要：默认先读，不默认写。对于自动化和 AI 工作流来说，读写边界越清楚，越不容易误伤生产数据。
三、准备环境变量
建议准备一个 .env 文件：
DINGTALK_CLIENT_ID=your_app_key
DINGTALK_CLIENT_SECRET=your_app_secret
DINGTALK_OPERATOR_UNION_ID=your_operator_union_id
注意不要把 .env 上传到 Git、CSDN、网盘或任何公开位置。
四、提取 nodeId
钉钉在线表格链接里通常会包含 nodes 路径。可以先用命令提取 nodeId：
python3 tools/dingtalk-spreadsheet-cli/dingtalk_spreadsheet_cli.py extract-node-id \\
"https://alidocs.dingtalk.com/i/nodes/yourNodeId"
输出示例：
yourNodeId
这里不要在文章、日志、截图中暴露真实 nodeId。真实文档 ID 本身也可能属于内部信息。
五、列出 Sheet
拿到 nodeId 后，可以列出在线表格中的 sheet：
python3 tools/dingtalk-spreadsheet-cli/dingtalk_spreadsheet_cli.py list-sheets \\
–node-id yourNodeId \\
–format md
示例输出：
| name | id | type |
| — | — | — |
| demo_tasks | s1 | SHEET |
| demo_weekly | s2 | SHEET |
实际使用时，建议先列出 sheet，再确认目标 sheet 的 id，不要凭页面上的中文名称直接猜。
六、读取指定范围并导出 Markdown
读取一个小范围：
python3 tools/dingtalk-spreadsheet-cli/dingtalk_spreadsheet_cli.py read-range \\
–node-id yourNodeId \\
–sheet-id s1 \\
–range A1:E20 \\
–format md
示例输出：
| task_id | title | owner | status | risk |
| — | — | — | — | — |
| T-001 | 示例任务A | 张三 | 进行中 | 依赖外部接口 |
| T-002 | 示例任务B | 李四 | 已完成 | 无 |
| T-003 | 示例任务C | 王五 | 阻塞 | 等待测试环境 |
Markdown 很适合给人看，也适合直接放进日报、周报或人工确认页面。
七、导出 JSON 给 AI 工作流
如果要接 AI Agent，更推荐导出 JSON：
python3 tools/dingtalk-spreadsheet-cli/dingtalk_spreadsheet_cli.py read-range \\
–node-id yourNodeId \\
–sheet-id s1 \\
–range A1:E20 \\
–format json > demo_tasks.json
示例 JSON：
[
["task_id", "title", "owner", "status", "risk"],
["T-001", "示例任务A", "张三", "进行中", "依赖外部接口"],
["T-002", "示例任务B", "李四", "已完成", "无"],
["T-003", "示例任务C", "王五", "阻塞", "等待测试环境"]
]
在真实项目中，建议再做一步归一化，把二维表格转成对象数组：
[
{
"task_id": "T-001",
"title": "示例任务A",
"owner": "张三",
"status": "进行中",
"risk": "依赖外部接口"
}
]
这样后续 prompt、规则检查、报告渲染都会更稳定。
八、接入 AI Agent / Hermes 工作流
上面的 CLI 看起来只是一个导出工具，但在 AI 工作流里，它可以作为“结构化数据入口”。
以 Hermes 这类 AI Agent 工作流为例，可以设计成下面的流程：
1. 业务人员维护钉钉在线表格
2. 定时任务调用 Python CLI 读取指定 Sheet
3. 脚本把二维表格转换成结构化 JSON
4. 脱敏和字段校验
5. Hermes 工作流读取 JSON
6. LLM 生成摘要、风险、下周计划或提醒
7. 结果输出到 Markdown / HTML / 邮件 / 钉钉通知 / 任务看板
一个典型场景是“周报生成”：
- 表格字段：任务、负责人、当前状态、风险、下周计划；
- CLI 读取最新范围并导出 JSON；
- Hermes 工作流把 JSON 交给 LLM；
- LLM 生成：
- 本周完成事项；
- 风险和阻塞项；
- 需要管理者确认的问题；
- 下周计划摘要；
- 可复制到周报的 Markdown。
这比人工复制表格给 AI 更稳，因为数据获取、清洗、脱敏和生成都有明确边界。
九、一个最小 Hermes 输入示例
假设前置脚本已经把表格转成下面的 JSON：
{
"source": "dingtalk_spreadsheet_demo",
"generated_at": "2026-05-26T20:30:00+08:00",
"tasks": [
{
"task_id": "T-001",
"title": "示例任务A",
"owner": "张三",
"status": "进行中",
"risk": "依赖外部接口",
"next_plan": "继续联调"
},
{
"task_id": "T-002",
"title": "示例任务B",
"owner": "李四",
"status": "已完成",
"risk": "无",
"next_plan": "等待验收"
}
]
}
给 Hermes / AI Agent 的输入可以非常简单：
请基于以下任务数据生成一份项目周报摘要。
要求：
1. 只使用输入数据，不编造任务；
2. 输出“本周完成”“风险阻塞”“下周计划”“需要人工确认”四部分；
3. 对 status=阻塞 或 risk 不为空的任务单独列出；
4. 输出 Markdown。
这里的重点不是 prompt 多复杂，而是输入数据足够干净、字段含义明确、来源可追溯。
十、为什么要先脱敏再交给 AI？
在线表格里经常会有人员、客户、项目、金额、合同、故障、系统名称等敏感信息。即使只是内部 AI，也建议做最小必要处理：
- 不读取无关列；
- 不读取无关 sheet；
- 不把真实表格链接写入日志；
- 不把 appKey、appSecret、unionId 放进文章或报告；
- 对人员、客户、项目名做别名化；
- 对金额、手机号、邮箱、身份证、IP、域名做遮蔽；
- 让 AI 只处理需要的字段。
可以把清洗后的数据写成：
{
"project": "项目A",
"owner": "人员1",
"risk": "外部依赖未完成"
}
而不是把整张真实表格原样喂给模型。
十一、写入命令为什么必须加 –yes？
这个 CLI 也支持写入区域，但写入命令默认需要显式确认：
python3 tools/dingtalk-spreadsheet-cli/dingtalk_spreadsheet_cli.py write-range \\
–node-id yourNodeId \\
–sheet-id s1 \\
–range A1:B3 \\
–values-file products/dingtalk-spreadsheet-cli/examples/write-values.sample.json \\
–yes
原因很简单：读操作和写操作风险不同。
如果后续要让 AI Agent 参与写入，建议先采用“人审后写入”的模式：
AI 生成建议
-> 写入本地草稿文件
-> 人工确认
-> CLI 写入测试 Sheet
-> 再进入正式 Sheet
不要一开始就让 AI 直接改生产表格。
十二、适合扩展的方向
这个 CLI 只是一个最小示例，但可以继续扩展成很多实用工作流：
- 每天读取项目进度表，生成日报；
- 每周读取任务表，生成周报；
- 读取问题清单，自动识别高风险项；
- 读取客户线索表，生成跟进提醒；
- 读取测试用例表，生成 Markdown 测试报告；
- 读取故障复盘表，生成 RCA 初稿；
- 读取运营数据表，生成趋势摘要。
这些场景本质上都是同一套模式：
业务表格 -> 结构化读取 -> 脱敏清洗 -> AI 摘要/分类/审计 -> 人工确认/自动分发
十三、边界和免责声明
最后再强调几个边界：
- 这是非官方示例工具，不代表钉钉官方立场；
- 只封装公开 OpenAPI，不绕过权限控制；
- 不包含任何真实凭证、cookie、企业数据或私有接口；
- 使用者需要自行创建钉钉开放平台应用并配置权限；
- 请只访问自己有权限的在线表格；
- 生产写入前务必先在测试表格验证；
- 接入 AI 工作流前，先做字段最小化和数据脱敏。
如果只是学习钉钉在线表格 OpenAPI，可以先从读取 A1:E20、导出 Markdown/JSON 开始。等读取链路稳定后，再接入 Hermes 或其他 AI Agent 工作流做摘要、审计和自动报告。
资源包
我整理了一个 Python CLI 示例资源包，包含：
- CLI 脚本；
- requirements.txt；
- .env.example；
- 中文 README；
- 快速开始文档；
- 写入示例 JSON；
- 安全边界说明。
资源名称：钉钉在线表格OpenAPI命令行示例工具 Python版
资源地址：https://download.csdn.net/download/distantsky/92905259
建议使用时先跑只读命令，确认权限、sheetId 和数据范围后，再考虑写入或接入 AI 工作流。
