内容
<p align="right">
<strong>English</strong> ｜ <a href="README.zh-CN.md">中文</a>
</p>
<p align="center">
<img src="docs/assets/banner-workflow.png" alt="QuantBench — AI workflow for quantitative research" width="900" />
</p>
<h1 align="center">QuantBench</h1>
<p align="center">
<strong>从想法到审计后的回测。一个命令。</strong>
</p>
<p align="center">
<a href="#快速开始">快速开始</a> ·
<a href="#功能">功能</a> ·
<a href="#网页工作台">网页工作台</a> ·
<a href="#命令行使用">命令行使用</a> ·
<a href="#架构">架构</a> ·
<a href="#路线图">路线图</a>
</p>
<p align="center">
<img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+" />
<img src="https://img.shields.io/badge/license-AGPL--3.0-green" alt="License: AGPL-3.0" />
<img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey" alt="Platform: macOS | Linux" />
<img src="https://img.shields.io/badge/version-0.2.0-orange" alt="Version 0.2.0" />
</p>
---
QuantBench 是一个 **本地优先的AI研究工作台**，适用于量化研究人员。用自然语言描述一个策略想法 — QuantBench将其转化为可重复、审计的研究运行：数据来源、因子代码、回测、质量检查、图表和研究报告，所有内容都保存在本地的工件目录中。
它不是一个自动交易系统。它不是一个聊天机器人。QuantBench 产生 **研究工件** — 您可以审查、复制并交给同事的那种。
<p align="center">
<img src="docs/assets/hero-landing.png" alt="QuantBench landing — from idea to audited backtest" width="850" />
</p>
## 快速开始
### 先决条件
| 工具 | 版本 | 安装 |
|------|---------|---------|
| Python | 3.11+ | [python.org](https://www.python.org/) |
| uv | 最新版 | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| Node.js | 22+ | [nodejs.org](https://nodejs.org/) |
| LLM API 密钥 | — | DeepSeek-compatible 密钥配置为 LiteLLM |
### 三个命令启动您的第一个实验
```bash
# 1. 安装依赖
uv sync
# 2. 种子示例研究会话（免费，无需 API 密钥）
uv run python -m quantbench examples seed
# 3. 启动工作台
uv run python -m quantbench serve
```
打开打印的 URL。四个预生成的研讨会已准备好供您探索 — 包括指标、图表、审查员报告和研究报告。
> 首次启动会自动检测 `uv`/`node`/`npm`，在需要时运行 `npm install`（约 1 分钟），并在缺少任何内容时打印可行的提示。
## 功能
### 协调代理
用自然语言描述您想要研究的内容。协调代理解释您的意图，拉取数据，编写因子代码，运行回测，触发质量检查，并生成完整的研究工件 — 无需样板。
```bash
uv run python -m quantbench "在标普500成分股里测试20日动量因子的截面表现，2022-01-01到2024-12-31"
```
### 审查引擎
每次运行都会自动审计。审查引擎会标记出前瞻性偏差、过拟合、成本敏感性、幸存者偏差、容量约束等 20 多个统计和结构问题。结果会有一个判决：**强**、**有希望**、**弱** 或 **拒绝**。
### 可复制的工件
每次运行都会将所有内容保存到 `runs/<run_id>/`：
```
config.yaml # 完整的实验配置
signal.py # 运行的确切因子/信号代码
backtest_result.json # 指标、bootstrap CI、执行假设
review_report.json # 审查员的发现和判决
equity_curve.png # 交互式权益曲线图
drawdown.png # 回撤可视化
research_note.md # 自动生成的研究摘要
manifest.json # 来源：数据哈希、LLM 使用、技能注入
```
### 实验库和因子库
浏览、筛选和比较过去的运行结果，按判决、资产类别、因子家族或夏普比率排序。保存验证过的因子到可重用的库中。分叉任何运行以迭代不同的参数，同时保留血统。
### 回测引擎
- **单资产** 和 **横截面** 因子回测
- `open_t+1` 默认执行（现实的，而不是乐观的）
- 流动性感知价差/参与度上限成本、借贷成本、融资成本
- 多头/空头贡献分解、beta/大小/板块中和
- 分位数投资组合、换手率跟踪、参数扰动、制度分解
### 宇宙构建
- **美国股票**：标普500当前快照和点位时间成分
- **加密货币**：通过 CCXT/Binance 获取的Top-N USDT 永续合约
- 通过信任层显式标记幸存者/快照偏差
### MCP 和工作流技能
使用 MCP 服务器和工作流技能扩展 QuantBench — 粘贴一个 `mcpServers` JSON 配置，切换服务器开启/关闭，所有内容都热加载，无需重启。完全符合 Claude Code 的 `claude mcp` 体验。
## 网页工作台
用于浏览运行、检查工件和启动新研究的 React + Vite 本地工作台。
<p align="center">
<img src="docs/assets/workbench-run-report.png" alt="QuantBench web workbench — run report with metrics and charts" width="850" />
</p>
<details>
<summary><strong>更多截图</strong></summary>
<br>
**研究工件** — 每次运行都会生成可复制的代码、图表和研究报告：
<p align="center">
<img src="docs/assets/research-artifacts.png" alt="Research artifacts: code, charts, and research notes" width="850" />
</p>
**自定义面板** — 从 UI 管理工作流技能和 MCP 连接器：
<p align="center">
<img src="docs/assets/customize-skills-mcp.png" alt="Customize panel for skills and MCP servers" width="850" />
</p>
**实验库** — 筛选和比较过去的研究运行：
<p align="center">
<img src="docs/assets/experiment-library.png" alt="Experiment Library sidebar" width="340" />
</p>
</details>
### 交互式图表
零依赖的手绘 SVG 图表，带有悬停提示：权益曲线、回撤、换手率、分位数回报、成本敏感性、参数扰动、制度分解、符号集中度和回报相关性矩阵。
## 命令行使用
**运行研究实验：**
```bash
# 标普500横截面因子回测
uv run python -m quantbench "在标普500成分股里测试20日动量因子的截面表现，2022-01-01到2024-12-31，等权十分位多空组合"
# 加密货币永续合约横截面研究
uv run python -m quantbench "构建 top 30 USDT 永续合约的截面 universe，测试20日动量因子，2023-01-01到2024-12-31"
```
**实验库：**
```bash
uv run python -m quantbench library list --verdict PROMISING,STRONG --sort sharpe
uv run python -m quantbench compare run_A run_B
```
**因子库：**
```bash
uv run python -m quantbench factor save run_A --name momentum_20d
uv run python -m quantbench factor list --family momentum --min-verdict PROMISING
uv run python -m quantbench factor use momentum_20d --param lookback=60 --on "在AAPL上测试，2020-2024"
```
**工作流技能：**
```bash
uv run python -m quantbench skill list
uv run python -m quantbench --skill reviewer-weak-triage "我上一个因子被打成 WEAK，帮我看看下一步"
```
**MCP 服务器：**
```bash
uv run python -m quantbench mcp add-json filesystem '{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/data"]}'
uv run python -m quantbench mcp list
uv run python -m quantbench mcp enable fetch
```
## 架构
```
quantbench/
agent/ 协调代理、LLM包装器、提示
api/ FastAPI后端、运行状态管理、工件服务
artifact/ 每运行一次的工件存储
data/ 数据提供者、宇宙构建者、缓存、DuckDB仓库
engine/ 单资产和横截面回测引擎、指标
factors/ 因子库条目、参数提取、本地JSON存储
library/ 实验库索引、筛选、比较、血统、分支
review/ 审查引擎、判决逻辑、结构化报告
skilldocs/ 工作流技能文档解析、匹配、提示注入
skills/ 代码执行、绘图、报告、数据质量技能
skills_docs/ 工作流技能Markdown文档
web/ React + Vite本地工作台
tests/ CLI、API、数据层、回测引擎测试
```
**运行时状态** 默认存储在 `~/.quantbench/`（可通过 `QUANTBENCH_HOME` 重写）：
```
~/.quantbench/
data_cache/ 下载的市场数据
runs/ 研究运行工件
factors/ 保存的因子库
literature/ 导入的论文
api_token 本地API身份验证
```
## 本地API安全
QuantBench 是一个 **单用户本地研究工具**。API绑定到 `127.0.0.1`，使用本地令牌（`QUANTBENCH_API_TOKEN` 或 `~/.quantbench/api_token`）。请勿将端口暴露到网络上。跨源访问仅限于配置的本地主机源。
## 路线图
**研究质量** — 扩展点时间宇宙覆盖、审查员压力测试和统计护栏校准。
**数据和执行** — 更多资产类别（期货、宏观、替代数据）、数据集版本控制、可选沙盒代码执行、可导出实验包。
**产品** — 标签治理、每符号因子IC热图、多因子风险归因、多会话研究工作流。
请参阅 [CHANGELOG.md](CHANGELOG.md) 获取最近的发布信息。
## 免责声明
QuantBench 生成 **研究工件，而非投资建议**。所有回测都可能受到幸存者偏差、前瞻偏差、数据质量限制、交易成本假设、过拟合和制度变化的影响。在告知实际决策之前，必须审查、复制和压力测试结果。
## 许可证
Copyright © 2026 QuantBench contributors.
该项目在 **GNU Affero General Public License v3.0** 下获得许可 — 您可以免费使用、修改和分发此软件，但任何修改版本您分发或部署为服务时，也必须在 AGPL-3.0 下发布，并附上完整的源代码。
请参阅 [LICENSE](LICENSE) 获取完整文本。
