ptrade

轻量级本地单品种量化回测系统，默认策略为 BTC/USDT 4H 的 BB-KC Squeeze 波动率挤压破位策略。

设计原则

• DataFetcher：只负责 OKX 公开 K 线获取、缓存和清洗。
• StrategyEngine：只负责计算指标并生成 1、0、-1 信号。
• BacktestSimulator：只负责撮合、止损止盈、资金曲线和绩效统计。

项目没有引入消息队列、任务调度器或复杂事件框架，主流程通过清晰函数调用串联。

快速运行

venv\Scripts\python.exe btc_squeeze_backtest.py

或者使用模块入口：

venv\Scripts\python.exe -m ptrade.main

常用参数

venv\Scripts\python.exe btc_squeeze_backtest.py --since 2018-01-01 --max-bars 20000
venv\Scripts\python.exe btc_squeeze_backtest.py --initial-cash 20000 --fee-rate 0.0005 --slippage-rate 0.001
venv\Scripts\python.exe btc_squeeze_backtest.py --risk-per-trade 0.02 --max-position-fraction 1.0
venv\Scripts\python.exe btc_squeeze_backtest.py --risk-per-trade 0.015 --exit-logic 3R
venv\Scripts\python.exe btc_squeeze_backtest.py --risk-per-trade 0.015 --exit-logic chandelier_2.5
venv\Scripts\python.exe btc_squeeze_backtest.py --start-date 2024-01-01 --end-date 2026-05-16 --risk-per-trade 0.015 --exit-logic chandelier_2.5
venv\Scripts\python.exe btc_squeeze_backtest.py --risk-per-trade 0.015 --chart --chart-bars 1800
venv\Scripts\python.exe -m ptrade.optimizer --ema-lengths 50,100,200 --adx-thresholds 0,15,20 --chandelier-multipliers 2.0,2.5,3.0
venv\Scripts\python.exe -m ptrade.walk_forward
venv\Scripts\python.exe -m ptrade.walk_forward --train-months 24 --test-months 12 --step-months 12 --output-dir output/walk_forward_rolling_24m_12m
venv\Scripts\python.exe -m ptrade.walk_forward --train-months 24 --test-months 12 --step-months 12 --min-adx-threshold 15 --max-ema-length 200
venv\Scripts\python.exe -m ptrade.live_runner --symbol BTC/USDT --demo --dry-run --market spot
venv\Scripts\python.exe btc_squeeze_backtest.py --no-cache

默认历史窗口已设置为 2018-01-01 起、最多 20000 根 4H K 线，用于尽量覆盖 2018 至今的数据，减少样本过少带来的偶然性。控制台会打印信号诊断，包括有效 K 线数、Squeeze 次数、Squeeze Fired 次数、做多/做空信号数。

默认仓位管理采用固定风险比例：每笔交易最多风险账户权益的 2%，并限制最大名义仓位不超过账户权益，避免因 ATR 过小产生隐含杠杆。

离场逻辑

使用 --exit-logic 可以横向对比不同离场方式：

• bb_mid：原始布林带中轨回归离场。
• 3R 或 fixed_r：固定 3R 止盈，止损仍为 2 ATR。
• 2R、4R：也支持其他固定 R 倍数写法。
• chandelier：动态 ATR 吊灯止损，默认 2.5 ATR。
• chandelier_2.5：指定吊灯止损 ATR 倍数。

参数网格搜索

优化器会遍历 EMA 周期、ADX 阈值和动态吊灯 ATR 倍数，输出 CSV 和零依赖 HTML 热力图：

venv\Scripts\python.exe -m ptrade.optimizer --ema-lengths 50,100,200 --adx-thresholds 0,15,20 --chandelier-multipliers 2.0,2.5,3.0
venv\Scripts\python.exe -m ptrade.optimizer --start-date 2018-01-01 --end-date 2023-12-31 --ema-lengths 50,100,200 --adx-thresholds 0,15,20 --chandelier-multipliers 2.0,2.5,3.0

输出文件：

• output/optimizer/grid_results.csv
• output/optimizer/heatmap.html

解读时优先看“参数高原”，而不是孤立最优点。如果一片相邻 EMA、ADX、ATR 倍数组合都能维持较好的夏普和回撤，说明策略对参数扰动更稳健；如果只有一个格子特别好，通常要警惕过拟合。

--start-date 和 --end-date 用于时间序列切分。系统会保留 start-date 之前的数据作为指标 warm-up，只在指定区间内生成诊断和执行回测，避免 EMA/ADX 在样本外开头重新冷启动。

Walk-Forward Analysis

默认使用移动窗口：24 个月训练、6 个月测试、6 个月步长。 为避免 OOS 区间重叠，step-months 不能小于 test-months。 WFA 默认带有参数选择护栏：ADX >= 15 且 EMA <= 200，避免优化器选择违背趋势突破策略基因的参数。

venv\Scripts\python.exe -m ptrade.walk_forward

输出文件：

• output/walk_forward/folds.csv
• output/walk_forward/walk_forward_equity.csv
• output/walk_forward/summary.html

Live State Manager

实盘状态管理器位于 ptrade/live/state_manager.py，使用 Python 标准库 sqlite3，不依赖 ORM。它负责：

• 持久化当前仓位方向、数量、入场价、极值价格、吊灯止损和最后处理 K 线时间戳。
• 防止重启后重复处理同一根 K 线。
• 写入本地交易流水，便于日后对账和滑点分析。

Broker / Execution

执行器骨架位于 ptrade/live/broker.py：

• 使用 ccxt.okx，支持 OKX Demo / simulated trading。
• 使用交易所 amount_to_precision 和 price_to_precision 处理数量与价格精度。
• 支持市价单、交易所侧条件止损单、撤旧挂新的动态吊灯止损流程。
• 当前目标账户模式为单品种、单向持仓；正式接入前应在 OKX 网页端确认账户为 One-way / Net 模式。

Live Smoke Test

只读冒烟测试不会下单，用于验证 OKX Demo 鉴权、market 精度、余额/仓位和挂单接口：

venv\Scripts\python.exe -m ptrade.live_smoke --symbol BTC/USDT --demo --market spot

需要先设置环境变量：

• OKX_API_KEY
• OKX_API_SECRET
• OKX_API_PASSWORD

Dry-run Live Runner

Dry-run 模式会真实拉取行情和只读账户数据，但会拦截所有下单与撤单动作，返回 mock order，并使用独立状态库 dry_run_state.db：

venv\Scripts\python.exe -m ptrade.live_runner --symbol BTC/USDT --demo --dry-run --market spot
venv\Scripts\python.exe -m ptrade.live_runner --symbol BTC/USDT --demo --dry-run --market spot --force-signal 1 --force-process

该入口适合由 Cron/Systemd 每 4 小时整点后延迟 5-15 秒触发。每次运行都会执行：对账、拉取 warm-up K 线、幂等检查、策略计算、状态更新，然后安全退出。

Live Runner 会同时输出控制台日志，并滚动写入 logs/live_runner.log。可以通过 --log-file 指定路径；也可以通过 --alert-webhook 或环境变量 PTRADE_ALERT_WEBHOOK_URL 启用通用 webhook 报警。

--force-signal 和 --force-process 只能在 --dry-run 下使用，用于强制最后一根 K 线信号为 1、0 或 -1，并允许忽略 last_kline_ts 幂等保护，方便演练 mock 开仓和状态流转。

如需在 OKX Demo 中做小额实单演练，--force-signal 需要双确认短语：

venv\Scripts\python.exe -m ptrade.live_runner --symbol BTC/USDT --demo --market spot --force-signal 1 --allow-demo-force-signal I_UNDERSTAND_DEMO_ORDER --state-db demo_force_state.db

不要在真实盘使用强制信号。

如果 Demo 实单开仓成功但本地状态库为空，可用显式接管开关把交易所已有仓位接入 SQLite，并让下一阶段挂载止损：

venv\Scripts\python.exe -m ptrade.live_runner --symbol BTC/USDT --demo --market spot --state-db demo_force_live_state.db --adopt-exchange-position

如果 OKX Demo 里残留多张同标的条件止损单，可显式开启清理，保留本地 stop_order_id 对应的那张：

venv\Scripts\python.exe -m ptrade.live_runner --symbol BTC/USDT --demo --market spot --state-db demo_force_live_state.db --cleanup-stale-stops

可视化对账

使用 --chart 会导出零依赖 HTML/SVG 图表：

• output/backtest_chart.html：K 线、布林带、肯特纳通道、EMA 200、开平仓箭头。

venv\Scripts\python.exe btc_squeeze_backtest.py --risk-per-trade 0.015 --chart --chart-bars 1800

输出文件

默认输出到 output/：

• equity_curve.csv：资金曲线。
• trades.csv：交易明细。

K 线缓存默认保存到 data/，下次相同参数运行会优先读取缓存，减少 API 请求。

测试

venv\Scripts\python.exe -m unittest discover -s tests