S09：Artifact Hash 与最小 Bundle Manifest

内容类型：预习教材（不代表已完成）
日期：2026-12-01
阶段：P2 · AI Systems Engineering 90
总路线：Day 099 / 360
周次 / 节奏：W2 · 周二最小实现
状态：教材已备；学习未完成
主题：content address、hash、manifest、integrity

一句话定义

Artifact hash 为具体字节内容提供稳定指纹，bundle manifest 则用显式字段把多个产物及其关系组成一个可校验、可追踪的系统候选版本。

学习目标

1. 能为三个小文件计算 SHA-256，并说明 hash 能证明和不能证明什么。
2. 能设计包含逻辑名、版本、URI/路径、digest、类型与依赖的最小 manifest。
3. 能验证文件缺失、内容改变和 manifest 引用不一致。
4. 能理解 canonicalization、目录 artifact 和大文件分块带来的边界，而不扩大实现。

核心知识

文件名和修改时间不是可靠身份；内容 digest 能在字节变化时产生不同指纹。SHA-256 可用于完整性校验和内容寻址，但 hash 本身不证明来源可信、安全无漏洞或许可合法。若攻击者能同时替换文件和 manifest，单独比较 digest 也无法发现，因此还需要可信签名、访问控制或透明日志；这些留待后续供应链主题。

Manifest 是机器可读的“组合说明书”。最小字段可包括 bundle_id、created_at、artifacts[]、每项的 name/type/version/path/digest/size、依赖关系与 schema version。不要把 secret、绝对个人路径或敏感正文写入 manifest。模型、prompt、index、tool schema 和 policy 可以用统一引用结构，但它们的兼容检查不同。

Hash 的对象必须明确定义。文本换行、JSON 字段顺序、压缩方式都会改变字节。可以选择对原始字节 hash，最简单也最诚实；若要对语义规范化内容 hash，就必须版本化 canonicalization 规则。目录可用排序后的文件 digest 构造 Merkle-like 根，但本日只需三个文件。

机制与推导

对文件字节 b，digest 为 d = SHA256(b)。一个 bundle identity 可由规范化 manifest（不含可变时间等字段）计算：

[ bundle_digest=SHA256(canonical(artifact_1...artifact_n,relations)) ]

校验算法按 manifest 逐项读取文件、重算 digest 并比较，返回 ok / missing / mismatch。状态不应只用布尔值，否则无法区分缺失与篡改。原子性也是边界：manifest 写完而某个文件尚未落盘会形成暂时不完整 bundle，真实系统常用临时位置、提交标记或事务式发布处理。

最小练习或观察步骤

1. 准备三个无敏感内容的小文件，例如 prompt、tool schema 和 policy JSON。
2. 用 Node 标准库逐文件读取并计算 SHA-256，不引入新平台。
3. 用 JSON 写 manifest，包含 schema version、artifact type、relative path、digest 和 size。
4. 写一个验证函数，分别输出 ok、missing、digest mismatch。
5. 修改 prompt 一个字符后重验，真实记录变化；不要预写“验证成功”。
6. 恢复或另存新版本，说明旧 manifest 为何仍应保留。

常见误区与边界

• 认为 hash 能证明作者身份、无恶意内容或监管合规。
• 把可变 URL 当唯一引用，没有保存 digest。
• manifest 中记录本机绝对路径，导致迁移困难或泄露用户名。
• 规范化 JSON 却未版本化规则，使不同实现算出不同 identity。
• 文件改变后直接更新旧 digest，掩盖一次真实版本变化。

系统场景连接

银行内部 AI 助手可能由模型 API 配置、系统提示词、工具契约与数据访问策略组成。Bundle manifest 能让一次调查知道当时使用哪个组合，但它不代替权限审查。智能合约分析工具也可锁定链数据快照、规则和模型配置，避免“同名报告”实际来自不同输入。

自检问题

1. SHA-256 digest 可以支持哪些主张，不能支持哪些主张？
2. 为什么相对路径加 digest 比单独绝对路径更适合 manifest？
3. 文件缺失与 hash mismatch 为什么要分开报告？
4. 哪些字段不应参与 bundle digest，为什么？

专业课程对齐

• 阅读 MLflow 官方文档 中 artifacts 与 model packaging 内容，观察平台如何保存产物路径和元数据，再与本日手写 manifest 的最小字段对照。
• 阅读 OpenLineage 官方文档 的 dataset facets 与 run event 概念，理解 hash/版本怎样作为 lineage 元数据，而不是替代 job/run 关系。
• 阅读 Full Stack Deep Learning 2022 的 experiment management 与 deployment 讲次，关注一个可发布产物为何需要配置和依赖上下文。

深入学习提示

把 hash 看成“对哪一串字节作出的声明”。先亲手制造换行或字段顺序变化，再讨论 canonicalization 是否值得。阅读平台文档时不要照搬庞大 metadata schema，只问本地 manifest 是否能回答：具体内容是什么、依赖谁、是否缺失、能否保留旧组合。最后列出 provenance 与 integrity 的区别，为 W9 供应链学习留钩子。

学后填写区

• 实际选择的三个 artifact：
• manifest 字段：
• 修改后观察到的 digest 变化：
• 校验器能识别的状态：
• hash 仍无法证明的事项：