docs: add V5.3 design and implementation checklist

2026-03-03 08:58:54 +00:00 · 2026-03-03 08:58:54 +00:00 · 18a2c95e40
commit 18a2c95e40
parent 4a5d63621f
2 changed files with 210 additions and 0 deletions
--- a/docs/arbitrage-engine/v53-design.md
+++ b/docs/arbitrage-engine/v53-design.md
@ -0,0 +1,124 @@
+---
+title: V5.3 双轨信号系统设计案
+date: 2026-03-03
+---
+
+# V5.3 双轨信号系统设计案
+
+> 目标：让策略从“手工打分规则”升级为“可持续训练和迭代的小模型系统”，并在不放弃 BTC 的前提下，实现按币种环境分轨建模。
+
+## 1. 设计原则
+
+1. **双轨建模**：ALT（ETH/XRP/SOL）与 BTC 分离，不共享权重和阈值。
+2. **先数据、后调参**：先补齐特征与标签落库，再做参数优化。
+3. **反过拟合优先**：任何优化必须先过样本外验证（OOS）。
+4. **信号与执行解耦**：Alpha（信号）与成本（执行）分开归因。
+5. **版本可追溯**：每次信号和交易都可回溯到 `strategy_version + config_hash + engine_instance`。
+
+## 2. 现状问题归纳（V5.1/V5.2）
+
+- V5.1：毛R为正、净R为负，说明有 Alpha 但被手续费和执行摩擦吞噬。
+- V5.2：交易频率下降但毛R转负，说明新增因子未提升预测力，存在噪声与冗余。
+- 评分结构存在共线性：方向层与确认层同源（重复使用 CVD_fast/CVD_mid）。
+- BTC 与 ALT 使用同构逻辑，忽略了市场微结构差异。
+
+## 3. V5.3 总体架构
+
+```
+Market Data -> Feature Snapshot -> Track Router -> Signal Decision -> Execution -> Label Backfill -> Walk-Forward Eval
+```
+
+- **Feature Snapshot**：每次评估时落库原始特征和中间分数。
+- **Track Router**：按 symbol 路由到 ALT/BTC 模型。
+- **Signal Decision**：输出开仓/不开仓/翻转决策和原因。
+- **Execution**：独立处理 maker/taker、TP/SL、BE、flip。
+- **Label Backfill**：按 15/30/60 分钟回填标签。
+- **Walk-Forward Eval**：滚动训练与验证，驱动版本迭代。
+
+## 4. 双轨模型定义
+
+## 4.1 ALT 轨（ETH/XRP/SOL）
+
+- 目标：保留 V5.1 有效微观结构 Alpha，去除冗余。
+- 分层结构（100分）：
+  - Direction: 55
+  - Crowding: 25
+  - Environment: 15
+  - Auxiliary: 5
+- 关键变更：取消独立 Confirmation 层（避免与 Direction 共线性重复计分）。
+- 初始开仓阈值：75（先稳态，不一次改太多）。
+- 翻转阈值：85（高于开仓阈值，减少震荡内耗）。
+
+## 4.2 BTC 轨（独立模型）
+
+- 目标：针对机构主导盘口，提升信号有效性。
+- 首批核心特征：
+  - `tiered_cvd_whale`：按成交额分层后的大单净流（如 >100k）。
+  - `obi_depth_10`：前 10 档订单簿失衡。
+  - `spot_perp_divergence`：现货与永续的价量背离。
+- 决策方式：先用“条件门控 + 否决条件”，暂不强行做线性总分。
+- 原则：BTC 轨独立评估，不与 ALT 汇总后做统一结论。
+
+## 5. 数据基建（ML Ready）
+
+## 5.1 表设计
+
+### `signal_feature_events`
+- 用途：每次信号评估快照（无论是否开仓）。
+- 关键字段：
+  - 元数据：`event_id, ts, symbol, track, side`
+  - 版本：`strategy, strategy_version, config_hash, engine_instance`
+  - 原始特征：`cvd_fast_raw, cvd_mid_raw, p99_flow_raw, accel_raw, ls_ratio_raw, top_pos_raw, oi_delta_raw, coinbase_premium_raw, fr_raw, liq_raw, obi_raw, tiered_cvd_whale_raw`
+  - 决策：`score_total, score_direction, score_crowding, score_environment, score_aux, gate_passed, block_reason`
+
+### `signal_label_events`
+- 用途：延迟回填标签，评估信号纯预测能力。
+- 字段：`event_id, y_binary_30m, y_binary_60m, y_return_15m, y_return_30m, y_return_60m, mfe_r_60m, mae_r_60m`
+
+### `execution_cost_events`
+- 用途：独立归因执行成本。
+- 字段：`trade_id, entry_type, exit_type, fee_bps, slippage_bps, maker_ratio, flip_flag, hold_seconds`
+
+## 5.2 标签定义
+
+- `Y_binary`：固定窗口内是否达到预设收益目标且未先触发风险阈值。
+- `Y_return_t`：固定时间窗（15m/30m/60m）净收益率（含成本估计）。
+
+说明：标签优先评价“信号有效性”，而不是被具体 TP/SL 参数污染的最终交易结果。
+
+## 6. 执行引擎改造
+
+1. **TP 优先 Maker**：入场后预挂 TP1/TP2 限价单，尽量降低 taker 成本。
+2. **Break-Even 费用感知**：BE 触发价需覆盖手续费与滑点缓冲，避免“名义保本、账户实亏”。
+3. **Flip 双门槛**：
+   - 开仓阈值：75
+   - 翻转阈值：85
+4. **执行质量指标化**：持续监控 `maker_ratio / avg_fee_r / flip_loss_r`。
+
+## 7. 反过拟合协议（强制）
+
+1. **Walk-Forward Optimization**：训练窗与验证窗严格时间隔离。
+2. **参数冻结**：一个评估周期内禁止改权重、阈值。
+3. **特征预算**：样本不足时严格限制特征数量，新增特征先 shadow 记录。
+4. **升级门槛**：样本外结果不达标不得进入下一阶段。
+5. **可解释性检查**：无金融逻辑支撑的“高胜率规则”禁止上线。
+
+## 8. 发布与回滚机制
+
+- 每次策略升级必须生成新 `strategy_version` 和 `config_hash`。
+- 发版前必须附带：训练窗结果 + 验证窗（OOS）结果 + 执行成本变化。
+- 任一核心指标触发阈值告警（如净R断崖、回撤超限）立即回滚到上一稳定版本。
+
+## 9. 版本验收标准（V5.3）
+
+- ALT 轨：样本外连续两个窗口净R为正。
+- BTC 轨：样本外净R非负，且胜率不低于随机基线。
+- 执行层：平均手续费R显著低于 V5.1 基线。
+- 稳定性：最大回撤不显著劣化。
+
+## 10. 里程碑
+
+- M1：完成三张新表与事件落库。
+- M2：完成 ALT/BTC 路由与首版决策逻辑。
+- M3：完成执行成本改造（maker/BE/flip）。
+- M4：跑通首轮 Walk-Forward 并产出 V5.3 首次评估报告。
--- a/docs/arbitrage-engine/v53-implementation-checklist.md
+++ b/docs/arbitrage-engine/v53-implementation-checklist.md
@ -0,0 +1,86 @@
+---
+title: V5.3 实施清单
+status: draft
+updated: 2026-03-03
+---
+
+# V5.3 实施清单
+
+## P0（必须先完成）
+
+- [ ] 新增 `signal_feature_events` 表（含索引）
+- [ ] 新增 `signal_label_events` 表（含索引）
+- [ ] 新增 `execution_cost_events` 表（含索引）
+- [ ] 在信号评估循环中落库 feature snapshot（每次评估都写）
+- [ ] 打通统一追溯字段：`strategy_version/config_hash/engine_instance`
+- [ ] 实现 ALT/BTC 路由器（按 symbol 分流）
+- [ ] ALT 轨移除独立 confirmation 层，改为四层结构
+- [ ] 增加 flip 双门槛：`open=75`, `flip=85`
+- [ ] 执行层支持 TP 预挂单（maker 优先）
+- [ ] Break-Even 改为费用感知（含手续费+滑点缓冲）
+
+## P1（强烈建议本期完成）
+
+- [ ] BTC 轨首版特征：`tiered_cvd_whale`, `obi_depth_10`, `spot_perp_divergence`
+- [ ] BTC 轨采用门控逻辑（含 veto 条件）
+- [ ] 新增标签回填任务（15m/30m/60m）
+- [ ] 新增执行成本统计任务（fee/slippage/maker_ratio）
+- [ ] 新增按 `config_hash` 分组报表接口
+- [ ] 新增按 `track` 分组报表接口（ALT/BTC 分开看）
+- [ ] 建立 Walk-Forward 评估脚本（训练窗+验证窗）
+- [ ] 产出首版 V5.3 OOS 报告模板
+
+## P2（优化项）
+
+- [ ] 特征 shadow 机制（新因子先记录不参与决策）
+- [ ] 自动化回滚钩子（核心KPI超阈值触发）
+- [ ] 分层 CVD 桶参数自动校准
+- [ ] OBI 深度档位自适应（5档/10档切换）
+- [ ] 评估 XGBoost/LightGBM 离线实验管道
+
+## 数据库建议（草案）
+
+## `signal_feature_events`
+- 主键：`event_id`
+- 必要索引：
+  - `(ts)`
+  - `(symbol, ts DESC)`
+  - `(track, ts DESC)`
+  - `(strategy_version, config_hash, ts DESC)`
+
+## `signal_label_events`
+- 主键：`event_id`
+- 必要索引：
+  - `(y_binary_60m, ts)`
+  - `(symbol, ts DESC)`
+
+## `execution_cost_events`
+- 主键：`trade_id`
+- 必要索引：
+  - `(ts)`
+  - `(symbol, ts DESC)`
+  - `(entry_type, exit_type, ts DESC)`
+
+## 验证清单（上线前）
+
+- [ ] feature 事件写入无丢失，延迟可接受
+- [ ] label 回填任务无时间错位
+- [ ] ALT/BTC 路由正确（BTC 不落入 ALT）
+- [ ] maker 优先在真实成交中可观测
+- [ ] BE 逻辑覆盖成本后，不再出现“保本但净亏”异常
+- [ ] flip 频次和 flip 损耗下降
+- [ ] OOS 报告通过预设阈值
+
+## 发布闸门（建议）
+
+- [ ] ALT：连续两个 OOS 窗口净R > 0
+- [ ] BTC：OOS 净R >= 0 且胜率 >= 随机基线
+- [ ] 执行成本较 V5.1 明显改善（avg_fee_r 下降）
+- [ ] 最大回撤不高于风险红线
+
+## 任务分配建议
+
+- 后端核心：`signal_engine.py`, `paper_monitor.py`, `main.py`, `db.py`
+- 数据任务：新增 migration + 回填 job
+- 评估任务：新增 `scripts/train_eval_walkforward.py`
+- 文档任务：每次发版补充 `strategy_version` 变更记录