很多团队已经在用钉钉在线表格维护项目进度、周报、客户线索、问题清单或运营数据。

但当我们想把这些数据接入自动化脚本、AI Agent 或内部工作流时，常见问题就来了：

  • 表格数据适合人维护，但不适合程序稳定消费；
  • 直接复制粘贴给 AI，容易混入隐私数据，也不可追溯；
  • 业务人员习惯继续用表格，开发者又希望拿到 JSON / CSV / Markdown；
  • AI 工作流需要稳定输入，而不是每次手工整理一遍。

这篇文章用一个非官方 Python CLI 示例，演示如何通过钉钉在线表格 OpenAPI 读取 Sheet，并导出成 JSON、CSV、Markdown。最后再加一点 AI：把钉钉在线表格作为 AI Agent / Hermes 工作流的数据入口，用于周报生成、风险识别和任务摘要。

说明：本文示例只使用钉钉开放平台公开 OpenAPI，不包含任何账号凭证，不绕过权限控制，也不使用真实公司数据。文中的表格、人员、项目名都是合成示例。

一、为什么先做 CLI，而不是直接让 AI 读表格？

AI Agent 最怕两件事：

  1. 输入不稳定；
  2. 权限边界不清楚。

如果直接把在线表格链接交给 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 工作流。

# 人工智能 # python
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

圆满落幕｜智驱迭代・昇腾赋能 AI Agent 行业实践 Meetup 上海站，全栈落地干货一次吃透

avatar AtomGit开源社区
cover

AtomGit 2026年6月三方库下载量排行榜重磅发布！双榜格局稳固，生态深耕持续发力

avatar AtomGit开源社区
cover

G-Star 精选开源项目推荐｜第十八期

avatar AtomGit开源社区