manifoldbt-backtester

manifoldbt 回测技能

目的

执行 backtest-expert 教授的内容。该技能从五个维度评估回测，其前提条件写明“指标由用户提供”：它会为自己从未计算出的数字打分。本技能会计算这些数字。它会在真实 K 线数据上运行策略，并返回评估器所需的 8 项输入。

这两个技能按单向流程衔接：编写规范、运行、评估。

何时使用此技能

• 用户描述了一条规则，并希望对其进行测算
• 即将运行 backtest-expert，但相关数字尚不存在
• 胜率、平均盈利、平均亏损或回撤必须从 K 线数据中计算得出
• 需要确定策略的参数数量以便评分

将结论留给 backtest-expert。它负责设置阈值和识别危险信号，本技能不会重复这些内容。

前提条件

• Python 3.9+
• pip install manifoldbt（Apache 2.0 with Commons Clause；免费层涵盖本技能的所有操作）
• OHLCV K 线数据，格式为 CSV 或 Parquet，包含以下列：timestamp, open, high, low, close, volume
• 无需 API 密钥

工作流

1. 编写策略规范

规范应列出指标和一个入场条件。尽量只保留能阐明假设的最简规则。每增加一个可调参数，都更容易意外地拟合样本内数据，而评估器会对参数数量进行惩罚。

{
  "name": "sma_cross_costed",
  "indicators": {
    "fast": { "type": "sma", "period": 20 },
    "slow": { "type": "sma", "period": 60 }
  },
  "entry": { "left": "fast", "op": ">", "right": "slow" },
  "size": 1.0,
  "stop_loss_pct": 1.5,
  "fees_bps": 5.0,
  "slippage_bps": 2.0
}

字段参考：references/strategy_spec.md。

读取任何结果前，请将 fees_bps 和 slippage_bps 设为合理值。无摩擦运行在执行真实性维度的得分为 0；对于持仓时间较短的交易，成本会决定收益优势能否留存。

2. 运行

python3 scripts/run_backtest.py \
  --spec strategy.json \
  --data bars.csv \
  --symbol BTCUSDT \
  --json-out result.json

脚本会先验证规范，再读取数据，因此你能在一秒内发现规范错误，而不必等数据加载很久之后才发现。

3. 先看警告，再看数字

运行结果会打印一些警告，这些警告会影响你对结果的解读：交易次数少于 30 笔、数据跨度不足一年、未对摩擦成本建模，或引擎胜率与配对胜率之间存在差异。出现任何一种情况，都说明应修正设置并重新运行。

有三种情况会阻止交接，而不是生成分数：没有已完成的往返交易、最大回撤缺失或非有限，以及盈亏为零的交易。评估器没有盈亏为零交易的输入项，因此若传入包含此类交易的样本，推导出的期望收益就会与已完成交易的结果不一致。

4. 交给 backtest-expert

运行结束时会给出一条可直接粘贴的命令。运行该命令，或使用相同数据调用 backtest-expert 技能：

python3 skills/backtest-expert/scripts/evaluate_backtest.py \
  --total-trades 3854 --win-rate 20.24 \
  --avg-win-pct 0.2917 --avg-loss-pct 0.2342 \
  --max-drawdown-pct 99.2893 --years-tested 0 \
  --num-parameters 3 --slippage-tested

四种不会报错的转换错误

从引擎输出到评估器输入之间有四种转换。每一种都会产生看似合理的数字，却会错误地评估策略，而且都不会报错。

一次成交是一次执行，一次往返交易包含两次执行。 原始交易次数大约是往返交易次数的两倍。将成交次数作为样本量维度的输入，会使表面样本量翻倍，可能让样本不足的回测跨过本不应达到的阈值。

只有在最简单的情况下，买入和卖出才会交替出现。 这适用于只做多、只交易单一标的且从不加仓的策略。做空会打破这一规律，因为卖出也可能是开仓。加仓也会打破这一规律，因为一次平仓可能对应多次开仓。多标的交易又会打破这一规律，因为不同标的的成交会交错出现。本技能会按标的跟踪仓位，并在仓位回到零时完成一次往返交易。在整个生命周期内，入场和出场的数量与现金金额会累积；其加权平均价格仅用于展示，盈亏则根据现金流本身计算。

成本会决定小额交易的盈亏。 每边 7 个基点时，价格上涨 0.1% 的交易仍会亏损。期望收益由胜率和平均盈利共同决定，因此将毛胜率与净均值放在一起会错误地反映收益优势。此处的百分比均已扣除费用，并同时提供 gross_return_pct 供检查。

引擎将回撤记为负值。 评估器需要的是正数幅度。若直接传入原始值，38% 的跌幅会被评为完美表现。

范围

支持：对任意 OHLC 列使用 sma、ema、rsi；使用 >、<、>=、<= 与另一个指标、价格列或数字进行比较的单个入场条件；可选的止损和止盈；以基点表示的费用和滑点；仅做多。

不支持：多条件入场、做空、多资产投资组合，以及上述三种指标之外的指标。引擎支持所有这些功能。本技能涵盖一句话假设所能生成的形式，并拒绝其余情况，而不是只处理一部分。

参考文件

• references/strategy_spec.md 涵盖每个规格字段、默认值以及验证会拒绝的内容
• references/metric_bridge.md 涵盖八项输入、每项的推导方式以及每种转换中的陷阱

脚本

• scripts/run_backtest.py 使用行情柱运行规格
• scripts/spec.py 验证规格并统计其参数
• scripts/round_trips.py 将成交配对为往返交易并计算净收益
• scripts/bridge.py 组装评估器的八项输入

spec.py、round_trips.py 和 bridge.py 不依赖任何依赖项，且无需导入引擎即可运行，因此你可以在不运行回测的情况下测试逻辑。