为开源项目建立可复现的构建差异“变更收据”

1 · 创新命题

中 面向发布桌面工具和教育软件的小型开源维护者，做一个构建收据生成器：两台隔离环境从同一 源码构建，若哈希不同，就把时间戳、路径、依赖下载与压缩顺序造成的差异定位成可读证据；相对只显示 “二进制不同”的 CI 失败，把走向可复现构建的排错时间量化压缩。 EN A build-receipt generator for small open-source teams that explains why two isolated builds of the same source differ—timestamps, paths, fetched dependencies or archive ordering—turning a hash mismatch from a dead end into an auditable repair list.

2 · 背景与空白

Reproducible Builds 项目长期维护方法与测试，Debian 有 reprotest，diffoscope 可深入比较产物； SLSA、in-toto 与 Sigstore 关注来源、证明和签名，但“有 provenance”不自动意味着可复现。现有工具 强大却输出繁复，小维护者难以从差异树定位第一处可行动原因。空白在：不是另造 diffoscope， 而是将双构建、差异归因、修复建议和前后证据压成一张发布收据，并验证它是否真的减少排错时间。

3 · 可检验假设

H1 对注入 6 类非确定性缺陷的公开项目，收据在前 3 条建议中命中真实根因的比例 ≥ 85%，修复后 至少 70% 项目达到逐字节一致构建。 H2（采纳）≥ 8 名维护者使用收据定位首个根因的中位时间，比直接阅读 diffoscope 原始输出缩短 ≥ 30%，且不会降低正确率。

4 · 量化验收标准

1. 【方法学校验 · 硬门槛】 用自建编排复现 Reproducible Builds 官方至少 10 个公开 非确定性算例，二进制相同/不同结论与 reprotest 一致率 100%，根因类别一致率 ≥ 90%。 此条不过，后续全部结论无效。
2. ≥ 20 个固定提交项目，覆盖至少 2 种构建生态；每项目在两台干净容器各构建 ≥ 3 次。
3. 统计口径按项目划分，不把同项目缺陷变体跨训练/测试；根因排序报 MRR、top-3 召回与精确率， 不用文件级 accuracy。
4. 基线含 diffoscope 原始输出、reprotest、人工 checklist；修复后必须第三次独立构建验证。
5. 构建时间为重尾分布，报中位数与 IQR；网络失败与缺失依赖单列，不伪装成不可复现。
6. 每个自动建议由两名团队成员在不知道注入类型时独立判定；分歧保留并报告一致性，避免把作者自己的 解释直接当成客观真值。

5 · 数据与工具

用途	来源 / 工具
构建校验	Reproducible Builds test cases、Debian reprotest —— 仅用于校验与对比，不计入数据贡献
差异分析	diffoscope；能展开多种格式，但根因解释层需自己实现
隔离环境	Podman/Docker、Nix 或 Guix；选择一种主路径，跨平台能力 需核实
证明对照	SLSA provenance、in-toto、Sigstore Rekor；用于边界讨论，不把签名等同复现
硬件	普通笔记本或学校服务器；构建缓存关闭以避免污染

能力边界：两个一致的恶意构建仍可能一致。致命错误是把“可复现”写成“代码安全”；本项目只 证明给定源码与环境能产出相同字节，不审计源码善恶。

收据不能只给一个红叉：它要指出第一处分歧位于编译器、归档器还是打包元数据，并附可重跑命令、环境 摘要和修复后哈希。为防工具自己制造可复现假象，第二构建不得复用第一构建的工作目录、下载缓存或 未声明环境变量；依赖若从网络消失，应分类为“来源不可重建”而非“二进制不一致”。 此外必须冻结源码提交、依赖锁文件和工具链镜像摘要；三者任一变化都应开启新实验，而不能算同一次 复现。修复建议若要求修改上游源码，要区分通用补丁和仅适用于当前包的临时规避。

6 · 赛季执行路径

1. 第 1–2 周：跑官方算例，完成方法学校验。
2. 第 3 周：冻结 6 类缺陷与收据字段；搭双容器构建。
3. 第 4–6 周：20 项目三次构建，记录失败而不筛掉难例。
4. 第 7 周：根因排序与修复建议；第 8 周第三构建验证。
5. 第 9 周：基线与消融；第 10 周维护者盲测。
6. 第 11–12 周：安全边界、单位经济、简述与演示。

7 · 新颖性边界

不声称：不发明 reproducible builds；不替代代码审计、签名或 SLSA；不保证所有生态可复现。 已有工作：Reproducible Builds、reprotest、diffoscope 解决构建与差异；SLSA、in-toto、Sigstore 提供供应链证明。本项目贡献是面向小维护者的根因排序与前后“变更收据”，并用时间和正确率验证 工作流价值。护城河类型：工作流替换（D）+ 累积数据（E）；非确定性根因—修复对照库是资产。

8 · go/no-go

第 2 周末：10 个算例根因一致率 < 70%，具名降级为 双构建可复现性审计报告器，不自动归因， 仍保留“是否一致 + 差异证据”的主框架。 第 6 周末：成功完成构建的项目 < 12 个，收窄到 Python wheel 或 Debian package 单生态； 第 10 周若排错时间未缩短 ≥ 10%，降级为 CI 归档插件，不声称改善效率。