面向 AI agent 的国内期货数据 + 回测基础设施。没有 UI——agent 就是交互界面。
在 Claude Code 里打开本项目,你可以直接对话完成:查行情、控制数据同步、 写策略跑回测、记录实盘持仓并获得基于 R 倍数体系的复盘建议。
- 不重复造轮子:看盘有专业软件;本项目只做"AI 能深度参与"的部分—— 数据、回测、记账三件基础设施,全部暴露给 agent。
- 离线优先:历史行情落本地 DuckDB,查询(
get_bars)纯本地零联网; 联网只发生在 agent 显式调用sync_bars时,内置双闸避免重复拉取。 回测因此完全可复现。 - R 倍数体系贯穿:回测与实盘账本共用同一套统计(
r_metrics), 期望值/SQN/R 分布两边直接可比——回测是预期,实盘是执行审计。
Claude Code (agent)
├── MCP server(futures-data,stdio,.mcp.json 自动注册)
│ ├─ 数据:get_bars / get_snapshot / get_contract_info / data_coverage
│ ├─ 同步:sync_bars(唯一联网入口) / sync_status
│ └─ 记账:log_trade / get_positions / get_trade_history / get_performance
└── Skills(.claude/skills/)
├─ backtest:写策略 → 跑回测 → 读结果
├─ research:只读 DuckDB + pandas 数据研究
└─ advise:持仓复盘/建议(信息采集清单 + 分析框架)
两者共用 Python 包 quantlib 与同一个 DuckDB 文件
数据源(只做国内期货五大交易所):
| 能力 | 来源 | 说明 |
|---|---|---|
| 日线 | 新浪 | 免费;主力连续(RB0)回溯到 2009,含持仓量与结算价 |
| 分钟线 | Wind SDK | 可选,默认关闭;需装 Wind 终端并登录后 opt-in(见启用 Wind) |
| 实时快照 | Wind → 新浪兜底 | 未启用 Wind 时自动走新浪 |
前置:Python 3.11+、uv、Claude Code。
git clone https://github.com/YeTianXingShi/QuantPilot.git && cd QuantPilot
uv sync # 安装依赖
uv run pytest # 验证环境(离线用例,应全绿)
claude # 启动 Claude Code,MCP server 会按 .mcp.json 自动拉起然后直接对话即可,例如:
帮我同步螺纹钢主连的日线,然后看看最近的走势结构。
agent 会调 sync_bars(["RB0"], "1d") 落库,再 get_bars 分析。
uv run python -m quantlib.backtest run \
--strategy strategies/_template.py:MyStrategy \
--symbols RB0.SHFE --freq 1d \
--start 2018-01-01 --cash 200000输出到 runs/<时间戳>_<策略名>/:summary.md(绩效表 + R 倍数体系 + 逐年收益 +
最差 5 笔)、result.json(全量)、trades.csv(逐笔)。
策略写法(完整示例见 strategies/_template.py):
from quantlib.backtest import Strategy
class MyStrategy(Strategy):
params = {"n": 20, "risk_pct": 0.01}
def on_bar(self, ctx):
bars = ctx.history("RB0.SHFE", self.p.n + 1)
...
qty = ctx.size_by_risk(sym, entry, stop, self.p.risk_pct) # 风险单位化仓位
ctx.buy(sym, qty) # 下一根开盘价成交
ctx.set_stop(sym, stop) # 引擎托管止损:盘中触发、跳空感知,并锁定 R 分母我今天 3800 开了两手螺纹多单,止损 3740,突破信号。
agent 会用 log_trade 入账并告诉你:每手风险 600 元、1R=1200 元、占账户风险比例。
之后"看看我的持仓"会触发 advise skill:浮盈折 R、止损距离、板块集中度、
该信号类型的历史期望值,逐笔给出建议。
硬规则:开仓必须报止损价——没有止损就没有 R,无法纳入绩效体系 (理论依据见 Van Tharp 的 R 倍数方法)。
Wind 是可选付费源,只多提供分钟线(wsi)和实时快照(wsq);日线、回测、
记账都不依赖它。默认关闭(QL_WIND_ENABLED=0):因为 Wind 终端未登录时,
其 dylib 导入与 w.start()(会等 GUI 登录框)会在 MCP server 启动时的主线程上
无限阻塞,拖过 Claude Code 的 30s 握手预算,导致整个 futures-data 连不上。
把它设成 opt-in 后,没装/没登录 Wind 的环境也能秒连、正常用日线。
需要分钟线时,按两步开启:
-
先登录 Wind 终端(本机装好 Wind 金融终端并保持登录态);
-
在
.mcp.json里把该 server 的QL_WIND_ENABLED改成"1":{ "mcpServers": { "futures-data": { "command": "uv", "args": ["run", "futures-mcp"], "env": { "QL_WIND_ENABLED": "1" } } } } -
在 Claude Code 里执行
/mcp重连(或重启),让新配置生效。
连上后用 sync_status 确认:wind.available 为 true、logged_in 为 true 即就绪;
若 logged_in 为 false,reason 字段会说明原因(通常是终端未登录)。相关环境变量:
| 变量 | 默认 | 作用 |
|---|---|---|
QL_WIND_ENABLED |
0 |
是否启用 Wind 源(1 开启) |
QL_WIND_PYTHON_DIR |
/Applications/Wind API.app/Contents/python |
WindPy 所在目录(非默认安装路径时指定) |
QL_WIND_WARMUP_TIMEOUT |
15 |
启动预热等待秒数(有界,避免拖垮握手) |
├── .mcp.json # MCP server 注册(Claude Code 自动读取)
├── .claude/skills/ # backtest / research / advise 三个工作流
├── CLAUDE.md # agent 工作指引(约定与实测坑,改代码前必读)
├── src/quantlib/
│ ├── data/ # 数据层
│ │ ├── symbol.py # 代码归一化唯一入口(rb2510→RB2510.SHFE)
│ │ ├── contracts.py # 70+ 品种规格:乘数/最小变动/保证金/手续费/板块
│ │ ├── store.py # DuckDB:bars + fetch_ranges 同步台账
│ │ ├── providers/ # sina(日线+快照) / wind(分钟线+快照)
│ │ ├── sync.py # 离线双闸(end 新鲜度 + start 台账覆盖)
│ │ └── hub.py # DataHub 门面
│ ├── backtest/ # 回测库:事件驱动引擎
│ │ ├── engine.py # 时序:撮合挂单→检查止损→标价→on_bar→记净值
│ │ ├── broker.py # 期货规则:净持仓 T+0/保证金/手续费/滑点
│ │ ├── feed.py # 多标的时间对齐(不填充)+ htf 防未来函数
│ │ └── runner.py # run_backtest() + CLI
│ ├── journal/ # 实盘交易日志(R 倍数体系,与回测共用统计)
│ └── mcp/ # MCP server 入口与 10 个工具
├── strategies/_template.py # 策略模板(带详细注释)
├── my/ # 个人目录(gitignore):自己的策略/笔记/资料
├── data/ # DuckDB 数据文件(gitignore)
└── tests/ # 82 离线用例;@network / @wind 标记联网集成用例
- 主力连续的坑:
RB0是新浪原生拼接、换月跳空未复权。看结构/算指标没问题, 但长周期回测的收益结论会被换月污染——结论敏感时用具体合约(RB2510)分段验证。 - 样本量:交易次数 <30 时 R 统计噪音很大,系统会带警告;别用 20 笔回测下重仓结论。
- 保持离线优先的习惯:研究脚本/回测永远读本地库,缺数据回到
sync_bars补, 不要在脚本里私自联网——这是回测可复现的前提。 - 个人内容进
my/:自己的策略、复盘笔记、资料文档都放my/(已 gitignore), 公开仓库不会带出去。同理data/futures.duckdb含你的实盘账本,注意自行备份。 - 定期报账户权益:
log_trade(action="equity", equity=...),开仓时才能自动 算出单笔风险占账户比例(建议单笔 ≤1%~2%)。 - 没有 Wind 也能用:日线研究 + 回测 + 记账全部可用;只有分钟线和更快的快照 依赖 Wind。Wind 默认关闭,需要时按启用 Windopt-in。
uv run pytest # 离线用例(默认)
uv run pytest -m network # 联网用例(实拉新浪)
uv run pytest -m wind # Wind 真连接(需终端登录)本项目仅供研究与学习。回测绩效不代表未来收益;内置合约规格(保证金率/手续费) 为近似值且交易所会调整,实盘前请自行核对。所有交易决策由使用者自行负责。