dtool：面向 AI Agent 的本地数据管道 CLI

简介

dtool 是一个本地数据管道 CLI ，单二进制、无外部依赖，主要面向 AI Agent 处理 Excel / JSON 的场景。

项目开源，地址： https://github.com/dezhishen/dtool
开源协议：MIT

它的核心思路是：不把原始表塞进模型上下文，也不让模型现场写 Python ，而是先把表转成数据集和 Schema ，把计算下推到本地 SQLite ，用 SQL 作为计算层。

SQL 是标准、准确、成熟的数据查询语言。它声明式、语义明确、结果确定，过滤、聚合、连接、窗口函数这些表格计算天然适合用 SQL 表达，而且经过了几十年验证。同一条 SQL 在任何时候执行，结果一致，容易审计，也容易复用。

在 dtool 里，AI 只负责生成 SQL ，执行和结果由本地引擎保证。每次命令落成一条 Action ，可追溯、可复用、可续跑； stdout 固定为结构化 JSON ，退出码固定。

项目背景

dtool 是我在拿 AI 处理 Excel 时做出来的。

最初的做法很直接：把 xlsx 丢给模型。数据量稍微大一点就装不进上下文，模型只能看到抽样，列名和类型靠猜，计算过程也没法核对。

后来改成让模型现场写 Python ，pandas + openpyxl + matplotlib 能跑通，但换个文件又是新脚本，口径和上次未必一致，环境依赖经常翻车，失败后也很难从中间续跑。

再往后是交付问题：结果散在聊天窗口里，图表还得自己复制回 Excel 。

这几条路我都走过。问题最后都指向同一处：AI 可以生成代码，但保证不了计算口径的稳定、准确和可复用。

方案设计

要解决上面这些问题，需要把“AI 直接处理数据”拆成几层，每层各管一件事。

数据入口：先 Schema 化，再交给 AI

AI 不该直接读原始表。原始 Excel 没有类型约束，列名可能重复，空值没有声明，模型只能靠猜。

方案是先把 Excel 转成数据集，并生成明确的 Schema：列类型、可空性、枚举、样例。AI 拿到的是结构化的元信息，不用猜列名，也不用脑补数字。

计算层：用 SQL ，不用现场生成的 Python

计算不能靠模型现场写代码。Python 脚本会随库版本、写法、运行环境漂移，同一条需求两次执行结果未必一致，也没法审计。

SQL 是标准化的数据查询语言，声明式表达，语义明确。过滤、聚合、连接、窗口函数这些表格计算，SQL 天然合适，而且经过了几十年验证。同一条 SQL 在任何时候执行，结果一致，容易审计，也容易复用。

所以计算下推到本地 SQLite 。AI 只负责生成 SQL ，执行和结果由本地引擎保证。

执行层：每一步留痕，可追溯、可续跑

一次数据分析不该只有最终数字。输入是什么、算了什么、产物在哪、失败在哪，都要留下来。

方案是每次命令落成一条 Action ，记录输入、产物、预览、错误、备注和血缘。要复用就引用已有 Action ，不用重跑。失败了也是一条 failed Action ，带着错误详情和修复提示，可以从失败点接着写。

接口层：给 Agent 固定形状

Agent 不该去解析自然语言日志。stdout 永远是结构化 JSON ，退出码固定，失败时 stdout 还是错误 JSON ，人类可读信息走 stderr 。这样 Agent 拿到的永远是确定的东西。

资源边界：流式、可控、失败可解释

xlsx 转换走流式，内存不够立刻失败，并给出“预计需要多少、可用多少”和退出口，不会静默被杀。Agent 能拿这个报错自己调参数。

同时 SQL 沙箱默认开着，只允许单条 SELECT / WITH，文件只能来自工作区、当前目录或 --source。

交付层：产物可导出、可出图、可留痕

结果不只是一段文字。dtool 支持把查询结果导出为 CSV / Excel ，也支持生成图表。产物本身同样作为 Action 留痕，方便后续追溯口径。

功能与用法

数据集与 Schema

dtool convert --input sales.xlsx --name sales
dtool datasets show sales     # 列类型、可空、枚举、样例都在这儿

AI 拿到的是明确的列类型、可空性、枚举和样例，不用猜列名，也不用脑补数字。

SQL 查询

查询不进模型上下文。数据集名直接当表名，JOIN 、CTE 、窗口函数都在本地 SQLite 里算完。

AI 默认只读 Action 的 preview（前 20 行）+ columns + summary，需要全量产物再显式去读。几十万行也不会把对话撑爆。

dtool query --sql 'SELECT c."客户名称", SUM(o."金额") AS 总额
  FROM orders o JOIN customers c ON o."客户 ID" = c."客户 ID"
  GROUP BY 1 ORDER BY 总额 DESC LIMIT 5'

Action 与血缘

每次命令都会落成一条 Action ，里面有输入、产物、预览、错误、备注和血缘。

要复用就引用 dataset:sales 或 latest:query，不用重跑。跑挂了也是一条 failed Action ，带着 detail 和 hint。比如列名写错，它会告诉你可用列有哪些，可以从失败点接着写。

Agent 接口

stdout 永远是结构化 JSON ，退出码固定：

1：通用错误
2：参数错误
3：引用不存在
4：执行失败

失败时 stdout 还是错误 JSON ，人类可读信息走 stderr 。这比让 Agent 去解析一段自然语言日志更可靠。

资源边界

没有外部依赖，Agent 环境里不用装 Python / pandas / 字体那一套，中文字体自动发现。

xlsx 转换是流式的，实测 7.4MB / 15 万行，峰值 47MB 。内存不够会立刻失败，并给出“预计需要多少、可用多少”和退出口，不会静默被杀，Agent 能拿这个报错自己调参数。

SQL 沙箱

SQL 沙箱默认开着，只允许单条 SELECT / WITH，文件只能来自工作区、当前目录或 --source。

使用指南与场景手册

Release 包里有个 skills.md，是写给 AI Agent 的使用指南。丢给 Agent ，它就知道怎么调，不用现写一段 prompt 教它。

README 里有按职业分册的场景手册，销售 / 业务运营、财务 / 会计、HR / 人事、电商 / 仓储运营、市场 / 增长、管理者 / 汇报、数据 / BI 各一份。

每个职业从“一条 SQL 拿到答案”递进到“连表 + 出图 + 导出 + 留痕”，命令都能对着示例数据直接跑。里面“对 AI 说”那一列，就是可以直接粘给 Agent 的提示词，比如：

「按区域汇总 sales.xlsx 的订单销售额并出柱状图，再给我金额 Top 5 客户的 Excel 」
「核对 sales.xlsx 的金额是否等于单价 × 数量，列出退款明细导出 CSV ，再出月度净收入对账表」
「用 pipeline 把 sales.xlsx 一条命令出成月度折线图并标注口径，之后我要能追溯它是怎么算出来的」

pipeline 一条命令

dtool pipeline --excel sales.xlsx --sql 'SELECT ... FROM data GROUP BY ...' --chart bar --x region --y total

适用与不适用

适合

手上主要是 Excel / JSON ，要反复做同一类汇总、出图、导出，并且希望结果可查、口径能复用；尤其是交给 AI Agent 干这类活的时候。

不适合

当 BI 用。它没有看板、权限、定时调度，也不是数据库。

获取

项目开源： https://github.com/dezhishen/dtool

从 Releases 下对应平台的包（ Linux / macOS .tar.gz，Windows .zip），解包即用。