开发实施指南 (Implementation Plan)

Edgekit：从文档到代码

1 实施概览

本文档旨在指导开发者如何将 需求文档 (PRD) 中定义的数学逻辑和功能需求转化为 Python 模块。

1.1 核心原则

• 纯函数化：所有核心逻辑严禁包含外部 IO 或随机性。
• 可测试性：每个计算步骤都必须有对应的单元测试。
• 类型安全：使用 Python 类型提示 (Type Hinting)。

---

2 模块划分与开发顺序

建议按以下顺序进行开发：

2.1 阶段一：核心引擎 (engine/)

1. sizing.py：实现 Wilson 置信下限、下限代入凯利公式与分数凯利的计算逻辑。
2. rebasing.py：实现双向 x-rebase 逻辑（上行阈值 x、下行阈值 d），处理 base 的离散更新。
3. execution.py：核心入口，整合 sizing、rebasing、risk_multiplier 与 portfolio_cap/gap_multiplier 约束。

2.2 阶段二：风控模块 (risk/)

1. baseline.py：定义基线存储结构（含 CUSUM 参数 k/h、DD_hard、n_min）。
2. cusum.py：实现 R 倍数序列的单侧 CUSUM（累计值显式进出参）。
3. circuit_breaker.py：实现回撤熔断（当前回撤 vs DD_hard）。
4. diagnostics.py：实现诊断（单侧胜率检验、对数 RR 置信上限），不参与判定。

2.3 阶段三：模拟工具 (sim/，离线、显式 seed)

1. monte_carlo.py：提供资本路径模拟（DGP 必须声明并随结果输出）。
2. x_sweep.py：按 requirements §5 联合选定 x 和 d。
3. calibrate_h.py：按目标平均误报间隔（ARL₀）标定 CUSUM 门限 h。

---

3 关键数据结构规格

3.1 Policy (策略配置)

{
  "baseline": { "p0": 0.55, "RR0": 1.5, "n0": 120 },
  "solver":   { "kelly_fraction": 0.5, "risk_cap": 0.02, "confidence": 0.90,
                "risk_fraction": 0.02 },
  "monitor":  { "k": 0.1875, "h": null, "DD_hard": 0.30, "n_min": 20 },
  "rebase":   { "x": 1.6, "d": 0.8 },
  "engine":   { "portfolio_cap": 0.06, "gap_multiplier": 1.0 },
  "provenance": { "sim_seed": 42, "dgp": "iid-lognormal-win",
                  "tool_version": "0.1.0", "policy_version": 2 }
}

（h 无默认值，必须由 calibrate_h 标定后填入；x、d 由 x_sweep 联合选定；示例中的 k = edge₀/2 = (0.55×1.5−0.45)/2。）

3.2 State (状态)

• OK: 正常（risk_multiplier = 1.0）
• DEGRADED: CUSUM 过半程（risk_multiplier = 0.5）
• INVALID: 回撤熔断或 CUSUM 报警（risk_multiplier = 0.0，PAUSE；不自动恢复，需人工启用新版 policy）
• INSUFFICIENT_DATA: 样本不足且无报警（不得宣告 OK，也不得宣告 INVALID）

---

4 验证清单 (Verification)

开发完成后，需通过以下检查：

• 所有公式实现与 requirements.qmd 保持一致（规格以该文档为准）。
• 单元测试覆盖核心计算逻辑与 requirements §10 校验规则的两张清单（抛错 vs 降级）。
• 边界输入（wins=0、losses=0、n=0、p_0 \in \{0,1\}、RR_0 \le 0）行为与契约一致，无除零崩溃。
• CUSUM 在基线参数下的平均误报间隔达到 ARL₀ 目标（模拟校验）。
• 回撤熔断不可被统计信号否决；统计报警不受 n_{min} 限制。
• core 层无随机性；sim 层给定 seed 完全可复现。
• 满足 how.qmd 中定义的所有禁止事项。

---

Tip提示

开发过程中如遇到数学边界问题，请优先查阅 为什么做 Edgekit 中的数学背景。