Edgekit 算法实现评判

截至 v0.1.4 的实现评审：从首版体检到收敛

Author

Edgekit Team

Published

June 14, 2026

Note📝 摘要

本文评判 Edgekit 的 Python 实现（src/edgekit/），不再讨论早期文档草稿。从首个实现 v0.1.0 起做了多轮批判性评审，每条结论都用可复现的脚本实测验证过，不只是读代码的推断。六个维度：数学正确性、统计严谨性、风控逻辑、金融实务、工程一致性、实现保真度（代码是否忠实落地了 需求文档）。截至 v0.1.4，全部高/中 severity 问题已修复并独立验证，复审收敛。 现行规格以需求文档为准，代码与之冲突按缺陷处理。

Important总体判断

数学骨架与三层纯函数架构是真材实料，从一开始就忠实落地；早期的缺陷集中在”把数字变成钱”的最后两层——engine 的换算与 tooling 的标定——它们一度打穿了库立身的两条根本承诺（先保住本金的非对称风控、风险=止损被打掉时的损失）。这些缺陷已逐版修复，并补上了直接断言这两条承诺的契约测试。当前实现可信、可复现、坏输入不裸崩。

1 核心优点

  1. 三层纯度边界守得住：import edgekit 不加载 numpy（实测 'numpy' in sys.modules 为 False）；随机只活在 tooling 且 seed 必填、provenance 随结果输出；policy 是 frozen dataclass。core 在任何调用链上都不触发模拟。
  2. solver 的置信下界链条正确：Wilson 单边下界 → 对数正态 RR 下界 → 下界凯利 → 半凯利 → 风险上限。数值锚点 solve(60,40,1.5) → risk_fraction=0.02（证据链 0.167→0.067→0.02）精确命中 PRD，四个版本改动后仍逐位稳定。
  3. monitor 的非对称风控落地：决策表优先级（回撤硬熔断 > CUSUM 报警 > 降档 > 样本不足 > OK）与 PRD 一致；CUSUM 盯复合优势量 X_t、盈利侧 3\times RR_0 截尾；胜率诊断单边下侧、小样本走精确二项。
  4. 两条根本不变式有契约测试守住：风险=止损损失（notional × stop_distance == risk_budget 对任意杠杆/合约乘子恒成立）、再基准化的相对风险上界（下行规则把单笔相对风险压在 f/d≈1.25 倍内）、calibrate_h 闭环（产出的 h 回喂 monitor 实测 ARL 落在 ARL_0 附近）、x 选择可复现——这四条都从”逐函数测返回值”升级成了”断言 PRD 整体性质”。

2 审计与修复记录

首版体检发现三处高 severity（都打穿根本承诺）加若干中/低；随后逐轮复审，发现一轮比一轮轻，到第三轮归零。全部经实测验证。

2.1 首版 v0.1.0：三处高 severity（已修）

编号 缺陷 实测证据 修复
HIGH-1 rebase 的 d 默认 None，下行再基准化被静默关掉，“越亏下注越重”的反凯利行为复活 rebase(100,70,1.5) 返回 100（base 不跟跌） d 默认 0.8，下行默认开（v0.1.1）
HIGH-2 calibrate_h 把盈亏标准化、抹掉 edge_0，CUSUM 漂移反号；h 标定整体失真 自报 ARL=75 vs monitor 真实口径 ARL≈450，差 6 倍 去标准化、补 3\times RR_0 截尾、加闭环测试（v0.1.1）
HIGH-3 position_size 的 leverage 乘进敞口，击穿”风险=止损损失” leverage=3 时止损实亏 6000，risk_budget 仅报 2000 leverage 移入 margin、contract_multiplier 不进 notional（v0.1.1 / v0.1.2）

中/低 severity（均已修）：solver 敏感度封顶时信息归零（改报未封顶 f_{LB}）、monitor 盈亏比诊断写死 cv（改走入参）、parse_policy 校验有缝（补齐 x/gap/h/n_min/portfolio_cap/risk_fraction）、binding_constraint 误归因（负优势报 zero_floor）、tooling 风险写死 1%（改 risk_fraction 入参）、tooling 未向量化（沿 path 轴向量化，PRD 规格大跑从不可达降到约 3 秒）。

一条撤回：首版曾报”x_sweep 偏离 PRD 选 x 算法”，经核对系比对了旧版规格——现行 requirements.qmd 已写明 x/d 联合选定，代码与之一致，故撤回。

2.2 复审 v0.1.1 → v0.1.4：逐轮收敛

轮次 发现 内容 去向
1 2 × MEDIUM margin 写成 notional × leverage（应 ÷ leverage，保证金随杠杆减少；3 倍杠杆下竟比敞口还大）；tooling tool_version 硬编码 "0.1.0" 谎报版本，砸可复现性 v0.1.3
2 2 × LOW position_size 未校验 leverage/contract_multiplier（leverage=0 除零、<1 让 margin>notional）；_payoff_diagnostic 在 n=0 时除零 v0.1.4
3 无 core 纯度、数值锚点、确定性、风险不变式四版后全部保持；剩余仅退化输入与纯风格项 收敛

收敛判据：一轮全维度实测复审挖不出经验证为真的高/中 severity 问题。严重度 MEDIUM → LOW → 无的单调下降，表明是真收敛而非反复修补。

3 一个系统性观察：测试全绿为什么没拦住

首版 158 个测试全绿，却没拦住三处高 severity——因为测试逐个函数对各自验收标准测，每个零件单独看都对，但缺陷全是跨零件的口径错位：calibrate_h 产出的 h 回喂 monitor 是否真给到 ARL_0、tooling 用的风险比例是否就是 policy 的 risk_fraction、rebase 默认是否保住下行、position_size 是否保住风险不变式——这些都没有对应测试。复审轮 1 的 margin bug 是同一类:它溜过去正因为测试只在 leverage=1 钉了 margin 值。

修复的同时补上了一层契约测试，直接断言 PRD 承诺的整体性质（ARL 闭环、风险不变式、相对风险上界 f/d、x 可复现性），而不只是断言每个函数在锚点上的返回值。这是这套库从”逐件正确”走向”组合正确”的关键一步。

4 维度评分（当前 v0.1.4）

下表是修复收敛后的当前评分。括注里给出曾经的弱项与现状，便于对照首版。

维度 评分 一句话理由
数学正确性 强（4.5/5） solver 置信下界链、monitor 主判定的代数都对，锚点四版后逐位稳定。
统计严谨性 强（4/5） calibrate_h 口径修正后闭环 ARL 对齐（曾是最大弱项）；诊断单边、小样本精确二项。
风控逻辑 强（4/5） 非对称决策表 + 下行保护默认开 + 相对风险上界，均有契约测试（曾被 rebase 默认关下行抵消）。
金融实务 强（4/5） 风险不变式跨杠杆/合约乘子恒成立、margin 方向修正、净口径、并发与跳空缓冲、坏输入校验。
工程一致性 强（4/5） 三层纯函数边界、parse_policy 校验闭门、provenance 版本跟随包版本。
实现保真度 强（4/5） core 与 tooling 现与 PRD 一致，并有跨组件契约测试兜底（曾多处默认值/口径对不上）。

5 刻意未改（非缺陷）

这些在复审中评估过，判定不属于需要修复的”问题”，刻意保留，以免陷入无限抠细节：

  • edge_0 ≤ 0 的退化基线：PRD 校验表未要求 edge_0 > 0，监控一个已知无优势的策略本就无意义；当前行为（最终会报警）可辩护。
  • solver 敏感度可为负：某方向扰动把优势打成负，敏感度如实显示负值是诚实输出，不是 bug。
  • 三处 Provenance dataclass 重复、portfolio_check 的 remaining 可为负：纯风格/信息字段，不影响正确性。

地基（凯利纪律、非对称风控哲学、三层纯函数边界）一直是这个库的真价值，core 主路径从首版就忠实落地。早期的缺陷集中在 engine 换算与 tooling 标定的默认值与口径，且测试是逐件而非组合验收——两者叠加放过了三处要害。逐版修复并补上契约测试后，复审收敛：当前实现可信、可复现、坏输入不裸崩。本文留作从首版到收敛的完整体检记录。