# astock-backtest-engine

**Repository Path**: skingway/astock-backtest-engine

## Basic Information

- **Project Name**: astock-backtest-engine
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-23
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# astock-backtest-engine

可扩展的 A 股回测框架：**85 个信号原子 + 13 个经典策略 + 3 种回测引擎**，向量化实现（含 Numba 加速版），内置 A 股交易细节（T+1、涨跌停、佣金+印花税+滑点三段式费率）。

与姊妹仓 [astock-data-toolkit](https://github.com/tiantianlaolao/astock-data-toolkit) 组成闭环：**toolkit 负责下载和周更数据，本仓负责在这些数据上跑回测**。

> ⚠️ 本项目是回测工具，不构成任何投资建议。历史回测结果不代表未来表现，请勿据此实盘操作。

## 数据从哪来

本仓不含行情数据。用 [astock-data-toolkit](https://github.com/tiantianlaolao/astock-data-toolkit)（[Gitee 镜像](https://gitee.com/skingway/astock-data-toolkit)）下载全 A 股 15 年数据后，把环境变量指向数据目录：

```bash
export ASTOCK_DATA_DIR=/path/to/astock_data
```

引擎启动时加载 6 张 parquet 表（两仓之间的接口契约）：

| 表 | 内容 | 用途 |
|---|---|---|
| `stock_list.parquet` | 全 A 股代码/名称 | 代码校验 |
| `daily_ohlcv.parquet` | 日线行情 OHLCV | 所有引擎的主数据 |
| `index_daily.parquet` | 沪深 300 指数日线 | benchmark 对比 |
| `valuation_daily.parquet` | PE/PB/PS/PCF/总股本/总市值（日粒度） | 估值类原子 |
| `financial_quarterly.parquet` | ROE/营收/利润（季报） | 财务类原子 |
| `dividend_history.parquet` | 分红历史 | 股息类原子 |

只想跑技术面回测的话，有 `stock_list` + `daily_ohlcv` + `index_daily` 三张表就够了。

## 安装

```bash
pip install -r requirements.txt   # numpy / pandas / pyarrow / numba / pydantic
```

## 三种回测引擎

### ① 经典策略回测

13 个内置策略：双均线、均线多头排列、MACD、双重确认、RSI、KDJ、布林带、均值回归、趋势超跌、N 日新高、放量突破、涨停板、买入持有。

```bash
python examples/run_strategy_backtest.py --list                         # 看全部策略
python examples/run_strategy_backtest.py --stock 600519 --strategy dual_ma --start 20230101
```

```python
from astock_backtest import DataStore, run_backtest

store = DataStore()
result = run_backtest(store, stock_code="600519", strategy_id="macd", params={})
```

### ② 信号原子组合回测

从 85 个信号原子里挑 1-2 个做买入条件（AND 关系），配一个持有规则（固定天数 / 止损 / 止盈 / 移动止损 / 指定信号卖出 / 反向信号卖出 / 持有到期末，可组合取先触发者），跑单股回测。

```bash
python examples/run_custom_backtest.py --list-atoms                     # 按类别看全部原子
python examples/run_custom_backtest.py --stock 600519 --atoms macd_golden_cross --hold-days 10
```

原子库构成：技术指标 40 个（MA/MACD/RSI/KDJ/布林穿越与状态）、价格行为 31 个（新高新低/连涨连跌/K 线形态/涨跌停）、量能 12 个（放量缩量/量价配合/换手率）、基本面 2 个。每个原子有专业名和白话名两套描述。

### ③ 网格交易回测

区间划 N 格，下穿格线买、上穿格线卖。实现了容易被简化掉的 A 股细节：底仓建仓、**每个槽位独立 T+1 保护**、格线穿越成交价（而非收盘价）、涨跌停无法成交、组合级止损熔断后 equity 横线延伸对齐 benchmark。

```bash
python examples/run_grid_backtest.py --stock 601398 --lower 4.5 --upper 6.5 --grids 10
```

### Numba 加速版

`services/backtest_engine_numba.py` 和 `services/grid_engine_numba.py` 是对应引擎的 Numba 版，与纯 Python 版 **bit-perfect 对齐**（相同输入逐字段一致），全市场批量跑时用它。策略子类重写 `precompute_signals()` 即可吃到向量化加速。

## ⭐ 扩展性：加一个自己的因子只要三步

本框架的核心设计是"**注册表 + 声明式依赖**"，加因子不需要改任何引擎代码：

```python
import numpy as np
from astock_backtest import SignalAtom, SignalCategory, DataDep, register

# 第 1 步: 写计算函数 — 返回 np.int8 数组, 1=当日触发
def my_signal(ohlcv, n=60, **kwargs):
    close = ohlcv["close"].to_numpy()
    prev_high = ohlcv["close"].rolling(n).max().shift(1).to_numpy()
    return np.nan_to_num(close > prev_high).astype(np.int8)

# 第 2 步: 注册
register(SignalAtom(
    id="my_new_high_60d",
    professional_name="创 60 日新高",
    layman_name="价格突破近三个月高点",
    category=SignalCategory.PRICE_ACTION,
    deps=(DataDep.OHLCV,),   # 声明依赖哪些表, 引擎自动喂数
    min_warmup=61,           # 需要的历史天数, 不足时引擎强制不触发
    compute_fn=my_signal,
    params={"n": 60},        # 工厂模式: 同一函数可注册多个参数版本
))

# 第 3 步: 直接按 id 用于回测
from astock_backtest import BacktestCustomRequest, DataStore, run_backtest_custom
req = BacktestCustomRequest(stock_code="600519", buy_atoms=["my_new_high_60d"], holding_days=10)
result = run_backtest_custom(req, DataStore())
```

完整可运行示例见 `examples/custom_atom_demo.py`。加自定义策略同理：继承 `Strategy` 实现 `generate_signal()`（进阶：重写 `precompute_signals()` 向量化），注册进 `STRATEGY_REGISTRY`。

框架层为扩展做的保护：原子 id 重名注册直接报错；输出长度/类型不符自动校验；`min_warmup` 越界自动清零；数据依赖按 `deps` 声明喂入，不用自己对齐表。

## 能力边界（如实交底）

- **信号原子是"条件触发"型（0/1），不是连续因子值。** 适合回测"KDJ 金叉买入持有 10 天胜率如何"这类条件策略；不做因子研究那套 IC 分析、分层回测、多因子打分。定位是"条件 → 回测"工具，不是因子挖掘平台。
- **单股回测为主。** 输入一只股票 + 一组条件，输出这只股票的 P&L 曲线、指标和逐笔明细。没有全市场自动遍历寻优。
- **数据依赖限于上面 6 张表。** 想加需要新数据源的因子（龙虎榜、北向资金等），需要自行扩展 `data_loader.py` —— 欢迎 PR。
- **日线级。** 不支持分钟线/tick 回测。
- 北交所股票不在数据覆盖范围（上游数据源限制，详见 toolkit 仓说明）。

## 项目结构

```
astock_backtest/
├── config.py             # ASTOCK_DATA_DIR 环境变量
├── data_loader.py        # 6 张 parquet 表加载 + 按股票切片缓存
├── signal_atoms/         # ⭐ 85 个信号原子 (base.py = 基类+注册表)
├── strategies/           # 13 个经典策略 (base.py = 基类, 支持向量化重写)
├── holding_rules/        # 7 种持有规则 (可组合, 先触发者生效)
├── models/               # pydantic 请求模型
└── services/
    ├── backtest_engine.py / backtest_engine_numba.py   # ① 策略引擎
    ├── backtest_custom_engine.py                       # ② 原子组合引擎
    ├── grid_engine.py / grid_engine_numba.py           # ③ 网格引擎
    ├── simulator.py      # 触发信号 → 逐笔成交模拟
    ├── metrics.py        # 收益/回撤/夏普/胜率等指标
    └── board_limits.py   # 主板/创业板/科创板涨跌停阈值
examples/                 # 4 个可运行示例 (含加自定义因子教程)
```

## 关于我们

本仓由 [AIHEY 艾嘿](https://www.tybbtech.com) 团队维护，是我们生产环境量化回测服务的引擎层开源版。我们已经把这套能力包装成了开箱即用的产品——不想自己搭环境的话，到[官网](https://www.tybbtech.com)点击「立即试用」即可直接使用；想深度定制的话，也可以在开源代码上自由修改。更多开源项目见[官网开源社区](https://www.tybbtech.com/zh/opensource)。

## License

MIT © 2026 北京天怡宝宝数字科技有限公司

---

## 关注公众号

关注微信公众号「天怡数智」，获取更新与优惠信息：

<img src="docs/qrcode_wechat.jpg" width="160" alt="公众号「天怡数智」二维码">

（图片加载不出来？微信搜索"天怡数智"即可）