第 17 章：让源码、实验包和电子书保持同一事实

发布是可追溯的数据链

一本工程书同时包含解释、可执行代码和运行证据。如果 EPUB 来自本地重建、在线页来自另一提交、实验 ZIP 又遗漏配置，读者很难判断哪个结果可信。发布设计应从同一份源码构建所有产物，并把精确提交和流水线记录连接起来。

本项目 Markdown 按编号排序，构建程序生成分章网页、完整下载稿和 EPUB。教学代码从实际 lab 与 cmd 目录读取，生成代码附录并进入实验 ZIP。这样修复一次代码后，不必手工复制到三种文档形式，也能通过哈希与全文比对发现内容偏离。

生成附录不能替代正文。正文负责解释为什么按这个顺序操作、哪里存在竞态，以及实验没有证明什么；代码附录让离线读者查完整实现。仅把仓库代码塞进 EPUB，无法形成一条可理解的工程学习路径。

构建门槛各自证明什么

真实 kind 套件证明固定环境下命名场景执行成功。发布校验比较原稿、网页和 EPUB 的章节全文与元数据，并检查归档文件。EPUBCheck 验证出版格式规范。浏览器检查字号、目录、搜索、主题、移动宽度和无 JavaScript 阅读。这些门槛互补，任何一项都不能替代事实审稿。

例如 EPUBCheck 不会发现 observedGeneration 解释错误，绿色单元测试也不会发现封面作者写错。作者身份、权利说明、官方来源和实验边界需要独立阅读核对。发布说明应写出每类证据的范围，而不是用“全部验证通过”隐藏不同验证的对象。

本项目作者为 Aias00，个人版权保留。技术背景不构成任何组织的著作署名或授权。第三方官方文档只保存链接、取得时间、哈希与原创摘要，全文缓存被忽略，不把第三方网页整份打包分发。

从同一次 CI 取发布资产

Pages 与 Release 的 EPUB 必须来自同一次成功流水线的 book-downloads artifact。先让真实实验、格式和浏览器门槛通过，再部署 Pages，再以该 artifact 创建版本发布。不能为了补一个 Release 下载链接而在本地重新构建，看起来相同的文件也可能包含不同元数据或代码。

发布后实际下载 Pages 和 Release 文件，与 CI artifact 比较字节和 SHA256。只检查 URL 存在或 HTTP 状态为二百，无法发现缓存仍在提供旧版本。内容一致性需要检查文件本身，格式验证则应该对最终下载到的 EPUB 再执行一次。

已发布资产不应被静默覆盖。修正文稿或实验后，应形成新的源码提交和补丁版本，保留旧版本供读者对照。运行证据、源提交和资产哈希组成版本身份，三者变化都应有可查记录。

文档更新不必重建书籍

交付记录加入公开验证链接，通常不改变书稿与代码。工作流通过路径过滤避免文档提交重新触发昂贵 kind 实验和重建；必要的证据回填使用明确的跳过标记。这样可以记录最终发布现场，而不制造一套与已发布资产不同的新构建。

但路径过滤也需要评审。若构建会读取 README，却把 README 排除触发路径，就可能造成产物漂移。本项目实验包不依赖仓库首页说明，而包含自身 lab/README，构建输入与触发路径保持对应。

在线阅读也是交付的一部分

阅读器默认浅色纸张，允许切换低饱和深色，并与其他书共享主题存储键。所有文章正文由静态 HTML 提供，JavaScript 只增强搜索、字号和交互。移动端检查覆盖每章与无脚本路径，避免只有首页好看而代码附录横向撑破页面。

练习是从一台没有仓库的机器下载 ZIP 和 EPUB，分别运行实验入口与离线阅读。只有读者实际得到的产物可用，源码目录中的成功才完成了最后一段交付。

版本说明回答三个问题

读者应能找到这份EPUB来自哪个提交、实验在哪次运行执行、公开文件是否与验证文件一致。交付记录把这三个答案直接连接起来，避免让使用者根据日期和文件名猜测。

如果只有运行号而没有原始测试流，后续无法重新判断验证范围；如果只有哈希而没有源码身份，文件虽然可校验却难以维护。证据链的价值来自各环节能互相核对。