科研代码不是结果文件夹，而是一条证据链

我以前也很容易被研究代码制造的错觉说服：图已经生成，指标已经写进 README，项目似乎就完成了。后来我越来越在意另一个问题：其他人能否从原始输入出发，沿着同一条路径得到足以支持相同结论的结果。

在审计 GitHub 仓库时，我检查了图像复原、微电网调度、EV 充电负荷、行程时间估计和信号周期估计等项目。部分研究仓库是私有的，因此本文只公开通用方法，不公开私有仓库名称、代码、数据或特定交付细节。公开样本使用 Single-lens 作为例子。

先区分四种“完成”

层级	实际含义
能运行	当前机器能执行主程序
能重复	原作者在同一条件下能再次得到结果
能复现	其他人使用提供的材料能得到相符结论
能复用	代码、数据与文档足以支持新实验

ACM Artifact Review and Badging 也把 artifact 的可用、功能性、可复用性与结果复现分开评价。一个 GitHub 链接只能证明“有材料”，不能自动证明结果可复现。

仓库审计中反复出现的五类研究

图像复原：指标之前先验证成像假设

我在 Single-lens 中实现了维纳滤波、分块 PSF、Lucy–Richardson、PSNR/SSIM、PSF 检查和性能比较。对我来说，最有价值的部分不是某个最高分，而是发现 PSF 有效尺度与图像尺寸存在明显不匹配，并尝试解释算法上限。

图像复原的证据链应该是：

PSF 来源与物理含义 → 输入预处理 → 算法参数 → 输出图像 → 指标 → 失败解释

如果 PSF 与目标图像不匹配，再复杂的算法也可能只是在优化错误模型。

微电网强化学习：合成数据不能伪装成现场数据

我在相关项目中实现了 DDQN、分阶段奖励、强约束动作空间和 Greedy 基线。其中一个仓库明确说明论文现场数据未公开，因此我使用正弦曲线与噪声生成仿真场景，并提醒绝对成本和回报会不同。

这句限制比“完整复现”更重要。合成数据可以验证算法行为，却不能直接支持对真实电网经济性的结论。

强化学习项目还必须报告训练/验证/测试场景划分、随机种子、回合数、约束违反率和多次运行波动。只展示最好一次训练曲线，会高估稳定性。

负荷预测：预测值进入调度后，误差会继续传播

EV 负荷项目把概率预测的 P50 接到后续微电网调度，并保留 P10/P90 作为不确定性范围。这个结构比单独报告 MAE 更接近真实决策链。

但一旦预测成为另一个模型的输入，就需要同时检查：

基础负荷与 EV 负荷是否被重复叠加。
训练与测试时间窗口是否泄漏未来信息。
调度结果对预测区间有多敏感。
使用真实值与预测值时，结论差异多大。

模型串联后，每个接口都是新的假设。

ETA：首先排除标签泄漏

行程时间估计项目包含路径编码、时间上下文、图结构、注意力偏置和多种损失。仓库特别强调，时间间隔先验来自训练集统计，而不是样本真实未来时间。

这说明研究仓库需要把“没有泄漏”写进设计证据，而不是只写在结论里。最有价值的诊断往往包括未见路段、未见 OD、时间分布漂移、长尾路径和简单历史均值 baseline。

如果复杂模型没有稳定超过朴素均值，应该先调查数据划分与任务定义，而不是继续堆层数。

信号周期估计：论文基线与工程改进必须分开

周期估计项目同时保留论文基线、论文对齐仿真和多参数共识改进。它没有把改进方案伪装成原论文，而是分别输出结果和比较报表。

复现研究中，“哪里与论文相同，哪里是自己的工程改进”必须能从入口、配置和结果目录中看出来。否则即使数字更好，也无法判断是复现成功还是任务已经改变。

一条合格证据链的七个环节

1. 数据来源

记录数据来自公开数据集、真实采集、论文附件还是合成生成。对于私有数据，至少说明字段、时间范围、脱敏和不可公开的原因。

2. 数据版本

文件名不等于版本。需要校验和、下载日期、生成脚本或不可变链接。空间数据与在线 API 尤其容易在未来发生变化。

3. 划分策略

随机划分、按时间划分、按主体划分会回答不同问题。时间序列随机打散可能把未来模式泄漏到训练集；同一路段或同一用户跨集合也可能造成隐性重叠。

4. 基线

至少包含一个简单、可解释、计算成本低的 baseline。均值、持久性、线性模型、Greedy 或传统滤波都可以。没有 baseline，复杂模型的指标没有参照物。

5. 配置与环境

依赖版本、硬件、随机种子、训练预算、停止条件和关键超参数必须进入文件，而不是只存在于命令历史。

6. 原始结果与制图

图表应该可以从原始结果重新生成。保存 CSV/JSON、训练历史和绘图脚本，比只提交 PNG 更接近可复现 artifact。

7. 结论边界

明确哪些结论只适用于当前数据、哪些经过消融支持、哪些仍是推测。结果不理想也应该保留，因为失败能暴露模型假设。

README 中最危险的词

“完整复现”“达到理论极限”“专业级”“显著提升”都不是不能用，但它们需要更强证据。

更稳妥的写法是：

“按论文描述实现主要算法路径，未公开数据部分使用合成场景替代。”
“在当前两组样本与参数下，方法 A 的 PSNR 高于基线 B。”
“结果接近本项目计算的上界；该上界依赖当前噪声与 PSF 假设。”
“尚未由独立环境复现。”

结论越具体，越容易被验证，也越有研究价值。

最小研究仓库模板

README：问题、范围、数据来源、运行顺序、限制
configs：所有实验配置
src：模型与数据逻辑
scripts：训练、评估、制图
tests：关键公式、数据约束、泄漏检查
artifacts/raw：原始指标与日志
artifacts/figures：由 raw 生成的图
environment：锁定依赖与硬件说明

NeurIPS 的 Paper Checklist 把可复现性、透明度、伦理和社会影响纳入提交检查。对个人研究仓库而言，不需要完整复制会议流程，但可以借用同一个原则：让每个主要结论都能追溯到数据、配置和输出。

科研代码的目标不是让目录看起来丰富，而是让怀疑者能够沿着证据链检查你。