backtest-lab

轻量级向量化回测框架 — 输入价格序列和交易信号，输出净值曲线与绩效指标。 A lightweight, vectorized backtesting framework in Python.

核心是一个没有未来函数、按换手计提交易成本的向量化引擎，外加三个经典策略作为示例。

特点

• 分层清晰：data → strategy → engine → metrics，各自独立、易扩展。
• 杜绝未来函数：信号 T+1 生效（signal.shift(1)），并有专门的守护测试。
• 计入交易成本：按换手率（|持仓变化|）计提单边成本，单位 bps。
• 零网络依赖：内置确定性合成数据（带牛熊 regime 切换），开箱即跑、结果可复现。
• CLI 对比：一次输出策略与「买入持有」的全部绩效指标，可导出净值曲线。
• 有测试、有 CI：27 个单元测试 + GitHub Actions。

快速开始

uv sync

# 双均线（20/60）
uv run backtest-lab --strategy dual_ma --fast 20 --slow 60

# 动量（120 日回看），并导出净值曲线
uv run backtest-lab --strategy momentum --lookback 120 --plot docs/equity.png

uv run pytest

输出示例：

策略: dual_ma   样本: 1500 根 K 线   2018-01-01 ~ 2023-09-29
指标                  策略        买入持有
----------------------------------
累计收益          63.69%      56.44%
年化收益           8.64%       7.81%
年化波动          16.13%      20.91%
夏普               0.59        0.46
最大回撤         -26.78%     -44.64%
卡玛               0.32        0.18
持仓胜率          50.80%      53.89%
持仓占比          58.40%      99.93%
交易次数              28           1

结果示例

在内置合成数据（牛熊 regime 切换，固定随机种子，单边成本 1bp）上：

指标	dual_ma (20/60)	momentum (120d)	mean_reversion (20d)	买入持有
累计收益	63.69%	127.05%	21.81%	56.44%
年化收益	8.64%	14.78%	3.37%	7.81%
年化波动	16.13%	16.19%	12.20%	20.91%
夏普	0.59	0.93	0.33	0.46
最大回撤	-26.78%	-18.13%	-26.98%	-44.64%
卡玛	0.32	0.82	0.13	0.18
交易次数	28	27	92	1

⚠️ 数据是合成的：用分段漂移模拟牛熊 regime，目的是让不同策略的差异可被观察。 以上结果仅作框架演示，不构成任何策略有效性或收益的结论。用真实数据请见下文。

内置策略

策略	逻辑
dual_ma	快线上穿慢线做多，下穿平仓
momentum	过去 lookback 日收益为正则持有（时序动量）
mean_reversion	价格 z 分数跌破 -entry_z 买入，回升到 exit_z 以上离场

信号语义：0 = 空仓，1 = 满仓做多（当前不支持做空）。

设计要点

• 信号 T+1 生效：T 日收盘产生的信号，T+1 日才持有 —— 否则会用"当天信号赚当天收益"， 回测结果虚高。见 docs/DECISIONS.md D2。
• 交易成本：成本 = |持仓变化| × cost_bps / 1e4，每次调仓都扣。
• 对照基准：始终同时给出「满仓买入持有」的指标，避免只看绝对收益。
• 指标口径：日频、按 252 交易日年化；最大回撤为负数；夏普按日频超额收益年化。

用真实数据

准备一个含日期列（date/Date）和价格列（默认 close）的 CSV：

date,close
2020-01-02,100.0
2020-01-03,101.2

然后：

uv run backtest-lab --source mydata.csv --strategy dual_ma

数据源可以是任何你合法持有的行情（自行用 yfinance / tushare / akshare 等导出即可， 本仓库不内置、不捆绑任何行情数据）。

项目结构

src/backtest_lab/
├── data.py       # 数据加载：合成 / CSV
├── strategy.py   # 策略：dual_ma / momentum / mean_reversion
├── engine.py     # 回测引擎（T+1 生效 + 成本）
├── metrics.py    # 绩效指标
├── plotting.py   # 净值曲线
└── cli.py        # 命令行入口
tests/            # 27 个单元测试
scripts/          # 生成 README 素材

License

MIT