residual-edge-analyzer

残差优势分析器

概述

通过与预先声明的基准收益序列进行明确比较，检验策略表面上的表现是否依然成立。生成可审计的 JSON 文件和简洁的 Markdown 报告，不获取数据，也不改变交易敞口。

将其作为 backtest-expert 之后的证伪关卡，而非交易授权。

前置条件

• 使用 Python 3.9 或更高版本。
• 准备一个 CSV，其中每行包含 ISO 日期、策略收益和所有基准收益。
• 准备一个符合输入约定的 JSON 规范。
• 提供实际期间收益。不要用 CAGR、Sharpe、累计盈亏或其他汇总指标替代。

工作流

1. 在查看结果前定义问题

用一句话说明所声称的独立优势。选择一个合理的策略简单复制作为主要基准，然后至少选择一个备选基准模型。

在配置中记录以下声明：

• baseline_selection: predeclared
• strategy_return_basis 和 baseline_return_basis：两者都为 gross 或都为 net
• analysis_scope：out_of_sample、live 或 in_sample
• universe_data：point_in_time、current_constituents 或 not_applicable

对于可用于决策的结论，每项声明都必须提供。省略任何一项都会被视为未声明，而非无关紧要，并会使报告降级为 REVIEW_REQUIRED。设置 not_applicable 后，可明确声明某个基准没有适用的成分成员资格，而不是将其留空。

不要因为某个基准能带来期望的残差结果而选择它。

2. 验证收益序列约定

要求：

• ISO 日期唯一；
• 收益为大于 -100% 的有限数值；
• 策略与基准的频率和成本口径一致；
• 对于同一投资范围的等权或动量基准，成分成员资格须为时点数据；
• 市场状态标签的定义独立于要解释的亏损期间。

如果输入缺少带日期的策略收益序列，请停止分析。若输入仅包含汇总数据，应报告数据不足，而不是凭空编造观测值。

3. 运行分析器

python3 skills/residual-edge-analyzer/scripts/analyze_residual_edge.py \
  --input reports/strategy_returns.csv \
  --config reports/residual_edge_config.json \
  --output-json reports/residual_edge_report.json \
  --output-markdown reports/residual_edge_report.md

脚本会在一次执行中运行预先声明的主要模型和所有敏感性模型。它使用含截距的 OLS 模型和 HAC/Newey-West 标准误。残差优势比定义为年化 alpha 除以年化残差波动率；不要根据原始 OLS 残差均值计算 Sharpe，因为含截距时该均值为零。

4. 解读证据

将以下四种状态用作诊断标签：

• RESIDUAL_EDGE：alpha、残差优势比和滚动稳定性均达到配置的阈值。
• BASELINE_EXPLAINED：基准的 R-squared 较高，而残差证据较弱。
• RESIDUAL_FRAGILE：结果未通过一个或多个稳健性关卡，或在声明的基准模型之间发生变化。滚动分析已禁用、不可用、不完整或未提供敏感性模型时，也使用此状态。
• INSUFFICIENT_EVIDENCE：样本低于配置的最低要求。

单独查看 decision_eligibility。如果存在关键的数据来源、成本口径、样本或多重共线性警告，滚动证据不可用，或者未测试其他基准，即使统计结果值得关注，结论仍为 REVIEW_REQUIRED。

检查：

1. 主要模型和敏感性模型的状态；
2. 年化 alpha 和 HAC t 统计量；
3. 残差优势比和残差自相关；
4. 滚动 alpha 稳定性；
5. 多因子模型的 VIF；
6. 预先声明的市场状态下主动收益的分解。

5. 移交分析结果

• 将基准选择、OOS 和稳定性分析结果反馈给 backtest-expert。
• 将反复出现的残差失效市场状态反馈给 signal-postmortem。
• 仅向 trade-performance-coach 提供证据和操作限制。
• 切勿自动更改头寸规模、敞口或订单。

边界

• 不要将此分析称为基于持仓的贡献分析。Brinson 配置、选股和交互效应分析需要历史持仓、基准权重和成分股收益。
• 不要根据仅使用市场指数的基准声称存在选股 Alpha。
• 不要使用当前成分股构建等权基准，并将其标记为时点数据。
• 不要将样本内残差优势解读为已确认的 Alpha。
• 不要在看到亏损后挖掘许多市场状态定义。应预先声明少量定义，并在样本外确认发现。
• 不要假设高 R-squared 就意味着策略毫无价值；容量、尾部表现、成本和实施价值需要单独的证据支持。

资源

• scripts/analyze_residual_edge.py — 确定性 CSV 到 JSON/Markdown 的分析器。
• references/input-contract.md — CSV/配置约定及可运行示例。
• references/methodology.md — 统计定义、解读和局限性。