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 ，让它算个汇总、画张图。实际用下来有四个绕不开的坑：

- AI 会编数字。 结果对不上时，你不知道它哪一步算错；同一个表问两遍，答案可能不一样。

- 隐私风险。 客户名单、薪资、订单流水被直接粘进在线对话。AI 厂商的隐私条款再漂亮，数据也已经离开本地了。

- 不可复核。 AI 的结论没有中间过程。过两周想确认口径，只能重新问，而它可能换一套算法。

- 上下文有限。 超过一定行数 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 ，单二进制零依赖。*