leakage-audit

泄漏审计

结论与立场

在流水线证明时间安全之前，先假设存在泄漏。给出对抗性且有证据支撑的判定：CLEAN、REVIEW REQUIRED 或 NOT CLEAN，并列出受污染字段、受影响的主张、所需修复和重新测试条件。 强指标绝不是数据干净的证据。

何时使用此技能

适用于：

• 首次信任回测或“良好”指标时；
• 建模前或结果异常强劲后，审查特征表时；
• 审计目标别名、连接、移位、预处理或切分设计时；
• 用户表示模型表现好得不真实／结果出乎意料时。

不要将此技能用作以下任务的替代方案：

• 从头设计合法特征 → feature-rules；
• 设计折和指标 → validation-design；
• 首轮面板 EDA → eda-sports。

需求	请改用
特征构建规则	feature-rules
折／指标章程	validation-design
设计干净后的概率可靠性	calibration-check

锁定审计约定

在检查相关性或指标之前，先写明目标、行粒度、确切的预测决策时间 T、符合条件的总体、来源发布／修订政策，以及预期的验证切分。如果 T 含糊不清，审计就无法通过。

每次审计都要使用审计清单。 追踪故障模式时，请查阅泄漏模式目录；性能或连接看似不合理时，请查阅案例研究。

审计顺序

1. 追踪目标的来源，并找出别名、变换、代理变量和重复标签。
2. 清点每个候选特征、原始来源、事件／发布时间／修订时间，以及其在 T 时是否可用。
3. 检查时间变换是否使用稳定排序，以及是否先移位再滚动／扩展。
4. 追踪对手、阵容、伤病、评级、天气、赔率和赛程的连接。
5. 确认预处理、特征选择、编码和调参只在训练行上拟合。
6. 确认验证按时间向前推进，并将相关行放在一起。
7. 运行自动矩阵启发式检查，然后人工调查每项发现。
8. 根据原始输入复现可疑行和性能跃升。
9. 给出判定，并在修复和重新运行前阻止未经支持的主张。

泄漏目录

模式	示例	要检查的证据	修复
目标别名	won、分差符号、最终排名	血缘关系和精确／近似相关性	从输入中移除
同一事件污染	当前比分、EPA、比赛统计总数	来源／事件时间戳	仅用作目标或重新定义 T
历史值未移位	当前结果进入滚动均值	变换顺序和边界行	先移位，再聚合
赛季信息泄漏	第 2 周使用赛季最终平均值	快照／发布时间政策	使用逐步扩展的历史值
对手信息污染	对手总数据包含当前对阵	连接追踪和配对行	连接安全的对手先验值
修订泄漏	历史数据使用了更正后的统计值	发布时间／修订时间戳	按历史时点重建数据版本
随机行切分	未来比赛进入训练集	折的日期范围	仅按时间向前切分
分组泄漏	同一场比赛的两个视角被拆开	比赛／实体成员关系	将相关行分组
预处理泄漏	缩放器／编码器在全量数据上拟合	已拟合对象的血缘关系	在训练折中拟合
调参泄漏	最终折影响超参数	实验历史	嵌套调参／未触碰的留出集
重复泄漏	同一事件或球员同时出现在两侧	哈希值和键	切分前去重／分组

人工审查

目标与时间

• 按定义，目标是否发生在 T 之后？已取消／打平／未完成的事件如何处理？
• 预测时间戳是有存储或可重建的，还是仅凭假设得出？
• 哪些提供方字段会被修订？使用的是哪个历史版本？
• 特征名称看起来是否无害，但其源表是否为事件发生后的数据？

转换

ordered = df.sort_values(["team", "event_time", "game_id"])
expected = ordered.groupby("team")["won"].transform(
    lambda s: s.shift(1).expanding(min_periods=1).mean()
)
assert expected.equals(ordered["pre_win_pct"])

检查排序的并列处理规则、重置边界、休赛期数据沿用情况、最小周期数，以及首个实体事件是否存在无法解释的经验先验。未来的扰动测试应证明，改变后续结果不会影响较早的特征。

联接

对于每次联接，记录左右两侧的粒度、键、预期基数、发布时间谓词、未匹配率、重复率和保留字段。时间点联接必须按时间向后查找，并满足 right_published_at <= T。显示名称联接和未提示的多对多扩增，在解决之前均视为审计失败。对手特征必须与对手自身的事件前行一致。

划分与预处理

对于每个折，证明 train max time < test min time，且仅允许声明的间隔／隔离期。在估计目标有此要求时，须将成对的团队比赛行、来自同一事件的重复观测以及其他依赖组放在一起。填补器、缩放器、编码器、特征选择器、目标编码器、PCA、提前停止和超参数搜索只能使用训练数据。

结果过于理想时的触发条件

近乎完美的准确率、低得不合常理的对数损失／误差、单个特征出现巨大跃升、训练集与测试集结果相同，或结果远超领域基线，都应触发停止。在讨论结果是否有价值之前，重新检查目标别名、当前事件字段、移位、对手联接、重复项、全局预处理以及测试折调参。

自动化辅助工具

审计辅助工具读取用户自有的 CSV、Parquet、JSON、JSONL 或 NDJSON 表格，要求安装 pandas，验证指定列，并运行名称、精确目标、重复项和近乎完美相关性的启发式检查。

python /path/to/leakage-audit/scripts/audit_pregame_features.py \
  --input modeling_table.csv --target won \
  --features pre_win_rate,rest_diff,rating_diff \
  --entity-col team --time-col event_time --out leakage.json

python /path/to/leakage-audit/scripts/write_audit_stub.py \
  --out data/leakage_audit.md

使用 --banned 为任务提供精确的禁用名称。首个事件的空值率检查始终为 REVIEW，而非 PASS，因为合理的先验可能会填充首个事件。重复行和近乎完美的相关性也会标记为 REVIEW：它们值得怀疑，但本身并非证据。直接禁用或与目标完全相同的特征会返回 NOT CLEAN，状态码为 2。否则，辅助工具会返回 REVIEW REQUIRED，状态码为 1：仅凭启发式检查绝不会返回 CLEAN。只有完成对数据沿袭、转换、联接、划分和折内预处理的人工审计后，才能给出 CLEAN 判定。

退出码（非崩溃）

退出码	判定	Agent 操作
1	REVIEW REQUIRED	继续。 阅读 JSON。完成人工审计。不要将此视为硬性失败。
2	NOT CLEAN	停止预测性声明，直至修复并重新测试。
0	未使用	启发式检查绝不会自动给出 CLEAN。

Stderr 也会打印 exit=1 REVIEW REQUIRED... 或 exit=2 NOT CLEAN...，以免未预先了解情况的 Agent 将审核提示误认为脚本故障。

自动化检查无法证明源数据可用性、转换正确性、联接方向或折的作用范围。它们只能补充，而不能取代数据沿袭和代码审查。

诊断示例

滚动状态未移位： 手动重新计算表明，第 i 行包含其自身结果。标记为 NOT CLEAN，使用 shift(1) 重建，重新生成所有下游产物，并重新运行验证。

赛季早期比赛使用赛季最终效率值： 该值在整个赛季内恒定，并反映了后续比赛。应替换为基于此前事件的扩展式时间点统计值；不要只是删掉最初几周的数据。

合理的首个事件先验： 首行存在非空评级，但数据沿袭表明，该评级是固定的季前评级，且在 T 之前发布。在记录初始化方式和时间戳之前，保持 REVIEW REQUIRED；之后再通过该项检查。

使用随机 K 折且特征干净： 特征检查通过，但未来赛季的数据进入了训练集。该流程仍为 NOT CLEAN；重新设计折划分，并重新运行所有报告的指标。

判定规则

判定	含义
CLEAN	已审查完整清单；没有未解决的违规项或待审查项
REVIEW REQUIRED	没有证据证实存在污染，但证据或可用性不完整
NOT CLEAN	至少一条特征、连接、转换、拆分或调优路径使用了禁止信息

不确定时不能判为 CLEAN。必须重新生成并重新评估固定矩阵； 评分后再删除可疑列，无法挽救先前的指标。

审计报告模板

Leakage audit
Sport / question / target / grain:
Decision time T and publication policy:
Data snapshot and feature count:
Validation and grouping rule:
Automated helper result / exit status:
Lineage and transform evidence reviewed:
Findings:
  1. [PASS | REVIEW | FAIL] item, evidence, affected scope
Contaminated fields/artifacts:
Required repairs and retests:
Remaining uncertainty:
Verdict: CLEAN | REVIEW REQUIRED | NOT CLEAN
Auditor / date:

完整性与资源路由

1. 宁可误判为待审查，也不要误判为干净；切勿根据指标推断数据干净。
2. 审计中的时间线排序必须与构建过程完全一致。
3. 不要通过删除不良测试时段或重新定义成功来修复泄漏。
4. NOT CLEAN 会阻止提出预测性主张，直到重建并重新测试。
5. 使用 references/audit_checklist.md 完成审计， 使用 references/leakage_patterns.md 查看分类，并 使用 references/case_studies.md 进行诊断。
6. 配合 feature-rules 进行修复，并配合 validation-design 设计折叠。