基于 NousResearch/Hermes Agent 构建的证据优先数据分析 Agent。它不是“LLM + pandas”演示：每条核心结论都绑定数据版本、SQL、查询结果、指标口径与验证状态，并具备持久化任务、故障恢复和可重复评测。
普通数据分析 Agent 往往只展示最终答案，无法回答三个关键问题：数字怎么算出来的、服务失败后会怎样、模型是否把相关性说成因果。HermesBI 把这三个问题做成产品能力：
- 真实业务闭环：用订单与广告投放数据回答 GMV、ROAS、CPA、Profit ROI 和预算分配问题。
- 可信分析：结构化 Claim Contract 会重新计算数字、变化率、排名和贡献度；无实验依据的因果结论会被拒绝。
- Agent 工程：SQLite 持久化状态机、租约领取、超时回收、取消、有限重试、失败分类和事件审计。
- 受控执行：SQL 只读防护，图表在固定 Docker 运行时生成，数据和产物按任务隔离。
- 可量化质量：20 个固定案例、标准答案、故障实验室和 Eval Board，不用“感觉回答不错”评价 Agent。
flowchart LR
U["问题 / CSV / XLSX"] --> A["Analyst：规划与查询"]
A --> D["Docker + SQLite 数据执行层"]
D --> E["Evidence：SQL、结果、数据哈希"]
E --> V["Verifier：Claim Contract 复算"]
V --> R["Reporter：图表与报告"]
V -->|"矛盾 / 越界"| X["限制说明或人工修正"]
S["SQLite 状态机"] --> A
S --> V
S --> R
F["Failure Lab"] --> S
任务状态：
queued → planning → executing → verifying → reporting → succeeded
↘ degraded_retry ↗
任意阶段 → failed / cancelled
| 路径 | 作用 |
|---|---|
plugins/data-bi/ |
数据导入、只读 SQL、证据记录、Claim 验证、图表和报告工具 |
skills/data-science/insightforge-bi/ |
分析方法、口径和证据约束 |
apps/hermesbi/ |
持久化任务引擎、HTTP API、三栏工作台、Failure Lab、Eval Board |
docker/ |
固定版本的 DuckDB/pandas/matplotlib 分析运行时 |
evals/ |
20 个固定案例、ground truth 和离线评测 |
demo_data/ |
可控合成数据、生成器及 UCI Online Retail 公开样例 |
tests/ |
Claim、SQL 安全、状态机、Skill 和评测契约测试 |
前置条件：Git、Python、Docker Desktop，以及一个已可运行的 Hermes Agent 工作区。
git clone https://github.com/NousResearch/hermes-agent.git E:\hermes-agent\hermes-agent-main
git clone https://github.com/fxl112233/HermesBI.git E:\hermes-agent\HermesBI
Set-Location E:\hermes-agent\HermesBI
.\install.ps1 -HermesPath E:\hermes-agent\hermes-agent-main
Set-Location E:\hermes-agent\hermes-agent-main
docker build -f docker\Dockerfile.bi -t hermes-bi:0.1 .
.\apps\hermesbi\start.ps1然后打开 http://127.0.0.1:8765。模型 Provider、Base URL 和 API Key 继续使用 Hermes 自己的本地配置，本仓库不保存任何凭证。
运行固定 Demo：
.\apps\hermesbi\demo.ps1运行离线标准答案评测：
.\venv\Scripts\python.exe evals\run_hermesbi_offline_eval.py
.\venv\Scripts\python.exe -m pytest tests\apps\test_hermesbi_task_engine.py tests\plugins\test_data_bi_plugin.py tests\skills\test_insightforge_bi_skill.py tests\evals\test_hermesbi_eval_cases.py -q- 导入订单表和广告投放表，自动生成字段画像与数据哈希。
- 提问“Paid Search 是否应该削减预算？”，Agent 比较 2 月与 3 月 ROAS、CPA、Profit ROI。
- 展开结论，查看 SQL、过滤条件、数据版本与复算结果。
- 注入模型超时或 Docker 不可用，观察
degraded_retry、退避和恢复轨迹。 - 注入错误口径、数字矛盾或因果越界，验证系统拒绝伪成功。
- 打开 Eval Board 查看准确率、证据覆盖、恢复率、延迟和真实 token 使用量。
- 这是单机 Windows + Docker 的面试级原型，不是多租户 SaaS。
- 默认演示数据源为 CSV/XLSX；MySQL/PostgreSQL 连接器尚未作为主链路交付。
- 自定义模型代理若不提供价格表，只记录真实 token，不伪造美元成本。
- 离线数值正确率只代表固定 benchmark，不代表所有真实业务数据都能达到 100%。
- 因果结论需要实验设计或外部识别条件；仅凭观察数据只能输出描述性关联。
HermesBI 是独立维护的 Hermes Agent 扩展，并非 Nous Research 官方项目。扩展代码使用 MIT License；上游 Hermes Agent 的版权与许可证归其原作者所有。公开样例的数据来源和许可证见 demo_data/public/README.md。