可复现工程与自动验证¶
“在我的电脑上能运行”不是可复现。可复现工程要求从明确输入、环境和命令得到带验收条件的输出，并能解释允许差异。对硬件项目，它还要区分可在软件重放的部分与必须在指定设备上测量的部分。
目的与学习成果¶
- 定义原始输入、权威参数、生成物和不可重建制品；
- 锁定依赖并记录实际运行环境；
- 用单一任务入口构建、测试、分析和文档；
- 设计确定性检查与有容差的数值检查；
- 生成机器可读证据清单和失败诊断。
最小环境¶
- 版本控制、命令行和一个小型 EE 项目；
- 文本环境/依赖清单；
- 可脚本化构建与测试工具；
- 校验和工具；
- 可选的持续集成，核心练习可完全本地完成。
容器是可选手段，不是自动答案。仍需记录基础镜像、目标架构、外部模型、硬件和无法封装的许可证要求。
学习顺序¶
- 资产分类：标记源、原始数据、配置、生成物和外部制品。
- 单一入口：为安装检查、测试、生成图和构建文档提供稳定命令。
- 环境锁定：记录工具与依赖版本、平台和获取来源。
- 确定性：固定随机种子、排序、区域设置和时间处理。
- 验收：文本用精确比较，浮点/测量用有物理依据的容差。
- 干净重建：在临时目录或隔离环境从头运行，并保存清单。
验证任务：重建一个完整微项目¶
选择一个包含计算、数据和报告的安全项目：
- 写资产清单，说明每项是否可重建、受何许可证约束；
- 创建统一验证入口，依次检查环境、测试、数据模式、图和文档；
- 固定种子并显式设置单位、时区与排序；
- 为关键数值设置有理由的容差，为文件记录校验和；
- 在干净目录运行两次，比较证据清单；
- 故意修改一个输入，确认依赖结果更新且验证能指出变化。
验收要求从源码到报告的一条命令成功，且失败时能定位到阶段而非只返回模糊错误。
常见失败与排查¶
- 漏装隐式依赖：从干净环境开始并记录系统级工具。
- 绝对路径泄漏：使用项目相对路径和可配置数据根。
- 每次校验和不同：排除时间戳元数据，固定排序、种子和生成器设置。
- 浮点结果跨平台微差：使用科学合理的容差，比较关键量而非整文件字节。
- 缓存掩盖缺失步骤：清空构建目录并验证缓存关闭路径。
- 硬件结果无法完全重放：保存固件、配置、原始数据、校准和允许统计范围。
可复现证据¶
- 源码提交与带说明里程碑；
- 环境、依赖、系统工具和许可证清单；
- 原始输入与不可重建制品的校验和；
- 单一构建/验证命令及阶段日志；
- 测试、模式、链接和文档检查摘要；
- 数值容差、种子和允许平台差异；
- 硬件修订、固件、校准与测量运行 ID。
成本、许可与无障碍¶
本地脚本和自由工具可完成核心流程。云端 CI 有额度、保留和隐私成本；先保证本地等价入口。商业工具应记录许可证前置条件，并为无法访问者提供标准导出或替代验证。
日志使用纯文本并给出明确阶段和错误。自动化结果不能只显示红绿颜色；同时输出状态词和诊断链接。低带宽用户可下载带校验和的源快照和小型证据包。
安全边界¶
- 自动化脚本按代码审阅，不在不可信贡献上使用密钥或连接硬件；
- CI 密钥最小权限、短寿命并避免写入日志；
- 自动硬件测试必须有限流、超时、急停和独立保护；
- 不把受限模型、个人数据或厂商机密上传公共制品；
- 可复现不等于安全或正确，仍需独立模型和风险审查。
完成清单¶
- 源、输入、配置、生成物和外部制品已分类。
- 一条稳定命令完成构建与全部检查。
- 环境、依赖、平台和许可证已记录。
- 随机性、排序、单位和时间处理明确。
- 确定性与容差检查均有理由。
- 项目在干净目录连续重建两次。
- 证据清单可追踪到源码、数据和硬件。
- 自动化密钥与硬件风险边界经过审查。