dtool v0.3.0：给 AI Agent 的本地 Excel 数据流水线 CLI

• 仓库： https://github.com/dezhishen/dtool
• 版本：v0.3.0 stable （单二进制，Linux / macOS / Windows ）
• 协议：MIT ，零依赖、无云端、无遥测

---

为什么做

现在拿 AI 处理表格的不少——把 Excel 丢给 ChatGPT 、Claude ，让它算个汇总、画张图。实际用下来有四个绕不开的坑：

1. AI 会编数字。 结果对不上时，你不知道它哪一步算错；同一个表问两遍，答案可能不一样。
2. 隐私风险。 客户名单、薪资、订单流水被直接粘进在线对话。AI 厂商的隐私条款再漂亮，数据也已经离开本地了。
3. 不可复核。 AI 的结论没有中间过程。过两周想确认口径，只能重新问，而它可能换一套算法。
4. 上下文有限。 超过一定行数 AI 就开始丢信息或瞎猜。十万行以上的表，纯对话基本没法处理。

dtool 的做法：数据留在本地，AI 负责写 SQL 和出图思路，dtool 负责执行和留痕。效率拿到了，数据没出去。

---

设计

• 本地优先：默认工作区 ./.dtool，数据集、查询结果、图表、Action 记录都在里面，可整体搬走。没有云端，没有遥测。
• 单二进制、零依赖：自带 SQLite 和图表渲染。不装 Python 、Node 、数据库。
• 默认强隐私：结果只写盘，stdout 只给交付清单（路径 + SHA256 ），不打印数据内容。隐私模式只有改配置文件能关，没有命令行开关绕过。
• Action 即台账：每条命令的输入、产物、预览、错误、血缘都记下来。想查”上次怎么算的”直接翻记录。
• Agent 友好：stdout 全是结构化 JSON ，退出码语义明确（ 4 = 跑完但出错，5 = 被中断可重跑），带 SKILL.md 技能包，Agent 可以直接拿它当数据后端。

---

安装

V=$(curl -sSL https://api.github.com/repos/dezhishen/dtool/releases/latest \
  | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p')
base=https://github.com/dezhishen/dtool/releases/download/$V
curl -LO "$base/dtool_${V#v}_linux_amd64.tar.gz"
curl -LO "$base/checksums.txt"
sha256sum -c --ignore-missing checksums.txt
tar -xzf "dtool_${V#v}_linux_amd64.tar.gz"
install -m 0755 dtool ~/.local/bin/
dtool version

Windows 下载 dtool_<版本>_windows_amd64.zip，解压即用 dtool.exe。

---

快速上手

# 1. Excel → 数据集（自动生成 Schema：列类型/可空/唯一/基数/角色）
dtool convert --input sales.xlsx --name sales

# 2. SQL 查询，数据集名直接当表名
dtool query --sql 'SELECT region, SUM(amount) AS total FROM sales GROUP BY region ORDER BY total DESC'

# 3. 出图，直接引用上一次查询结果，不用重跑
dtool visualize --input latest:query --type bar --x region --y total --title "区域销量" --output out/sales.png

# 4. 导出 Excel / CSV / Markdown
dtool query --sql 'SELECT * FROM sales WHERE amount > 60' --format xlsx --output out/filtered.xlsx

# 5. 一条龙
dtool pipeline --excel sales.xlsx \
  --sql 'SELECT region, SUM(amount) AS total FROM data GROUP BY region' \
  --chart bar --x region --y total --output out/summary.png

每步的 stdout 都是结构化 JSON ，含 action_id、产物路径和 SHA256 ；失败时 stdout 仍是 JSON （含 code/detail/hint ），退出码非 0 。

---

进阶示例

多表 JOIN

dtool convert --input sales.xlsx --sheet 订单 --name orders
dtool convert --input sales.xlsx --sheet 客户 --name customers
dtool query --sql 'SELECT c."客户名称", COUNT(*) AS 单数, SUM(o."金额") AS 总额
  FROM orders o JOIN customers c ON o."客户 ID" = c."客户 ID"
  GROUP BY 1 ORDER BY 总额 DESC LIMIT 5'

支持 INNER / LEFT / CROSS JOIN 、CTE （ WITH ）、子查询、UNION ALL 、窗口函数（ RANK / ROW_NUMBER / LAG ）。

多系列图表

# 长表透视：region × quarter 拆多系列
dtool visualize --input latest:query --type bar --x region --y total --group-by quarter

# 宽表直取：多列 → 多折线
dtool visualize --input latest:query --type line --x month --y sales,profit

结果集管理

dtool actions results stat     # 统计查询/图表结果（数量/大小/缺失）
dtool actions results verify   # 校验结果文件存在并核对 SHA256
dtool actions results gc       # 清理过期结果（默认 dry-run ，--apply 才真删）

口径与血缘

dtool actions annotate <id> --text "口径：含税" --by ai-agent
dtool query --sql '...' --from action:<上次的 id>

---

资源与性能（实测）

1 核 2GB 受限环境：

输入	模式	峰值内存	结果
3.4GB / 1830 万行 JSON	自动降档（磁盘档）	~59MB	跑通
37.7MB / 105 万行 Excel （格式上限）	convert 流式	~55MB	跑通
100 万行	默认	~2s 级	跑通
500 万行	默认	1:29	跑通

结论：

• 内存不足时自动降档（ full → stream → disk ），峰值和数据量解耦。
• Excel 转换是流式的，边界是 Excel 单表 1,048,576 行的格式上限，不是内存。
• 内存超预算会快速失败并给数字（预计需 xx / 可用 xx ），不会静默被杀。
• 看门狗按预算中止进程。Windows 上进程级内存限制（ 0x100 ）生效； job 级（ 0x2000 ）在 Win10 19044 读回为 0 ，工具会告警并回退预算来源。

---

已知限制

• SQL 引擎是 SQLite：不支持 ROLLUP / CUBE / GROUPING SETS ，多维小计用 UNION ALL 兜底；多系列展示由图表层 --group-by 实现。
• convert 只支持 .xlsx，不支持 .xls 和 CSV 直接导入。
• 图表单图上限 1000 个数据点。
• 默认沙箱只允许单条 SELECT / WITH ，PRAGMA / ATTACH / 多语句会被拒（--sandbox=false 可关）。
• 强隐私是契约不是沙箱：CLI 保证不打印数据内容，但拦不住调用方直接读落盘文件。

---

适用场景

• AI Agent / 自动化（首要场景）：stdout 全 JSON 、退出码语义明确、带 SKILL.md ，Agent 直接拿它当数据后端。
• 处理 Excel 但不想开在线表格的：本地汇总、出图、导出，数据不出门。
• 折腾本地数据的开发者：可复现的 SQL 流水线、Action 台账、SHA256 可校验。

---

dtool v0.3.0 ，MIT ，单二进制零依赖。