架构定位

生产工程

用评测、可观测性、部署与证据证明系统在真实约束下可靠。

如何证明系统可靠，并完成部署、作品集和面试表达？

受这些层约束

概念校准

验证与评测

它是什么: 用测试、Schema、引用、状态和验收规则检查单次结果，并用数据集衡量系统表现。
它不是什么: 不等于让模型对自己的输出再给一次意见；验证必须落到外部可检查证据。

可观测性

它是什么: 通过结构化日志、Trace、指标和版本信息解释系统在一次运行中发生了什么。
它不是什么: 不只是保存终端输出；没有关联 ID、状态转换和敏感信息边界的日志难以诊断。

贯穿式作品集交付

集成三个场景，补齐发布包、演示、架构文档和证据索引。

本章只做一件事发布 HeatStack Forge 1.0 和三套可复现案例。

开始前，Forge 已经具备已完成 Module 16 的“评测、可观测性、部署与可靠性”，其通过验收的 solution 是本章起点。

完成后，Forge 将能够发布 HeatStack Forge 1.0 和三套可复现案例。

卡住时的最小恢复点先交付软件场景最小发布包，再逐条合并迁移场景。

下载本章实验仓库Python 3.12 · pytest · Pydantic · SQLite · deterministic Mock

阶段能力链

01为软件、办公研究和音乐场景定义可比较的输入、输出与验收合同02把每次场景运行的输出、测试和追踪绑定为一个可验证结果03对发布文件排序并计算内容哈希，使相同输入产生相同清单摘要04用可检查的演示步骤连接用户问题、系统动作和证据文件05记录上下文、选择、备选与后果，拒绝只有结论没有取舍依据的架构说明06按场景、能力和证据类型建立索引，并防止同一路径被不同哈希覆盖07只有三场景、架构说明、演示脚本和证据索引齐全时发布 Forge 1

每一步只增加一种可验证能力；后一步建立在前一步已经通过的代码和测试上。

概念校准\n\n在开始操作代码前，先把本章涉及的概念放回正确的工程边界。\n\n
\n\n### 验证与评测 evaluation\n\n- 它是什么: Verification 用测试、Schema、引用、状态或验收规则检查一次结果；Evaluation 用数据集和指标衡量多次运行表现。\n- 它不是什么: 它不是让模型对自己的回答再给一次意见；通过与否必须落到外部可检查证据。\n- 与相邻概念的关系: Agent Loop 依赖 Verification 决定停止，RAG 需要分层评测，Planning 需要节点验收，Observability 提供运行记录。\n- 在 HeatStack Forge 中的位置: Forge 为单次运行保存合同测试与 evidence，再用固定场景集比较质量、延迟、成本、权限和恢复能力。\n- 典型误用与修正: 误用是把一个综合分数当成全部结论。修正方法是定义分层指标、失败样本和版本基线，并结合产品风险评审。\n\n### 可观测性 observability\n\n- 它是什么: 通过结构化日志、Trace、指标、状态转换和版本信息解释一次运行发生了什么，并支持定位失败与比较版本。\n- 它不是什么: 它不只是终端输出，也不是无限记录所有输入；缺少关联 ID、状态转换或敏感信息边界的日志既难排查又可能泄露数据。\n- 与相邻概念的关系: Harness 产生运行事件，Agent Loop 与工具调用形成 Trace，Evaluation 聚合指标，Memory 与恢复依赖版本记录。\n- 在 HeatStack Forge 中的位置: Forge 为每次任务生成 operation_id，记录阶段、工具、耗时、成本、错误类别、状态变化和证据路径，同时过滤敏感信息。\n- 典型误用与修正: 误用是等失败后再临时加日志。修正方法是在合同设计时定义事件与关联字段，并用故障注入确认能重建时间线。\n\n

STAGE 01

为软件、办公研究和音乐场景定义可比较的输入、输出与验收合同

先看一个具体问题

为什么非空检查挡不住路径逃逸？

在 forge/portfolio/scenarios.py 中，ScenarioContract 目前只检查场景名称是否允许以及输入、输出、验收元组是否非空。

当输入路径为 ../private.csv 时，validate() 不会报错，因为该路径非空且场景 office 合法。

这意味着合同可以引用包外文件，破坏交付包的封闭性，并可能泄露工作区中的敏感数据。

本阶段需要补全路径限制逻辑，使任何绝对路径或包含 .. 的路径都被拒绝。

先做判断

在补全路径检查之前，请预测：如果只检查输入路径非空，ScenarioContract("office", ("../private.csv",), ("brief.md",), ("citations present",)).validate() 会发生什么？

抛出 ValueError，因为路径包含 ..
正常返回，因为路径非空且场景合法
抛出 ValueError，因为场景 office 不允许
抛出 TypeError，因为路径不是字符串

判断依据: 当前代码只检查非空，没有检查路径内容，所以 ../private.csv 会被接受，validate() 正常返回。这正是测试 test_scenario_path_escape_is_rejected 失败的原因。

它是什么

合同验证是完整性与路径限制的组合

ScenarioContract.validate() 必须同时检查三件事：场景名称在允许集合中、所有元组非空、输入路径不逃逸包目录。

路径限制通过拒绝绝对路径（以 / 开头）和包含 .. 的路径来实现，确保输入只能来自包内。

它不是什么

合同验证不是只检查非空

仅检查非空无法阻止 ../private.csv 这样的路径，因为该路径非空且场景合法。

合同验证也不是对文件内容或输出正确性的检查，它只负责合同本身的完整性和路径安全。

它与相邻概念的关系

路径检查与场景、完整性的关系

场景检查确保合同属于已知场景，完整性检查确保必要字段存在，路径检查确保输入来源受控。

三者缺一不可：如果省略路径检查，合同可能引用包外文件；如果省略完整性检查，合同可能缺少必要字段。

本阶段的边界决定: 路径检查必须同时拒绝绝对路径和包含 .. 的路径，因为绝对路径直接指向文件系统任意位置，而 .. 可以跳出当前目录。只拒绝其中一种仍可能被绕过。

实验 ID: portfolio-delivery-01-three-scenario-contracts
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/portfolio-delivery/01-three-scenario-contracts/
验收: 待验收

教师示范

目标: 演示如何创建 ScenarioContract 并调用 validate()，展示完整合同通过和路径逃逸被拒绝。

首先，我们创建一个合法的软件场景合同，输入路径为 frontend-app/spec.md，输出为 patch.diff，验收标准为 tests pass。

调用 validate() 后，该合同通过，因为场景合法、所有元组非空、输入路径不逃逸。

然后，我们创建一个办公场景合同，输入路径为 ../private.csv，调用 validate() 会抛出包含 escapes 的 ValueError。

实施步骤

在 Python 环境中导入 ScenarioContract。
创建合法合同：ScenarioContract("software", ("frontend-app/spec.md",), ("patch.diff",), ("tests pass",))。
调用 validate()，观察无异常。
创建逃逸合同：ScenarioContract("office", ("../private.csv",), ("brief.md",), ("citations present",))。
调用 validate()，观察抛出 ValueError 且消息包含 escapes。

真实 solution 代码: forge/portfolio/__init__.py

"""Portfolio delivery artifacts."""

真实 solution 代码: forge/portfolio/scenarios.py

from dataclasses import dataclass

ALLOWED_SCENARIOS = frozenset({"software", "office", "music"})

@dataclass(frozen=True)
class ScenarioContract:
    scenario: str
    input_paths: tuple[str, ...]
    expected_outputs: tuple[str, ...]
    acceptance: tuple[str, ...]

    def validate(self) -> None:
        if self.scenario not in ALLOWED_SCENARIOS:
            raise ValueError("unknown scenario")
        if not self.input_paths or not self.expected_outputs or not self.acceptance:
            raise ValueError("scenario contract is incomplete")
        if any(path.startswith("/") or ".." in path.split("/") for path in self.input_paths):
            raise ValueError("scenario input escapes its pack")

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

合法合同通过是因为所有检查都满足：场景 software 在允许集合中，输入、输出、验收元组非空，输入路径 frontend-app/spec.md 不包含 .. 且不是绝对路径。

逃逸合同被拒绝是因为输入路径 ../private.csv 包含 ..，触发路径检查，抛出 ValueError。

带提示练习

补全 validate() 中缺失的路径逃逸检查，使测试 test_scenario_path_escape_is_rejected 通过。

打开 forge/portfolio/scenarios.py。
在 validate() 方法中，在完整性检查之后添加路径检查逻辑。
使用 any() 和生成器表达式检查 self.input_paths 中的每个路径。
条件为：路径以 / 开头，或者路径按 / 分割后包含 ..。
如果条件为真，抛出 ValueError("scenario input escapes its pack")。
运行测试验证。

逐级提示

提示1：使用 path.startswith("/") 检查绝对路径。
提示2：使用 ".." in path.split("/") 检查父目录遍历。
提示3：将两个条件用 or 组合，并放在 any() 中。

完成标准

test_scenario_path_escape_is_rejected 通过。
test_complete_scenario_contract_passes 仍然通过。

故障注入与排查

故障夹具 fixtures/failure.json 描述了一个场景合同读取包外输入的问题。当前 forge/portfolio/scenarios.py 中的 validate() 只检查完整性和场景名称，没有检查输入路径是否逃逸。运行测试 test_scenario_path_escape_is_rejected 时，合同 ScenarioContract("office", ("../private.csv",), ("brief.md",), ("citations present",)) 被接受，测试抛出 AssertionError。

本阶段已经学习了合同验证的完整性和路径限制。故障夹具中的缺陷正是缺少路径限制，学习者可以通过补全路径检查来修复。测试 test_scenario_path_escape_is_rejected 明确要求拒绝包含 .. 的路径，因此本阶段的知识足以定位并修复问题。

已验证的故障合同

目标测试: test_scenario_path_escape_is_rejected
故障文件: forge/portfolio/scenarios.py

诊断顺序

运行 python -m pytest -q ../tests/test_stage.py::test_scenario_path_escape_is_rejected，观察测试失败。
查看测试代码，发现它创建了输入路径为 ../private.csv 的合同，并期望 validate() 抛出包含 escapes 的 ValueError。
检查 forge/portfolio/scenarios.py 中的 validate() 方法，发现只有场景检查和完整性检查，没有路径检查。
确认缺陷：缺少对绝对路径和包含 .. 的路径的拒绝逻辑。

修复原则: 在 validate() 方法中添加路径检查：if any(path.startswith("/") or ".." in path.split("/") for path in self.input_paths): raise ValueError("scenario input escapes its pack")。这样，任何绝对路径或包含 .. 的路径都会触发 ValueError，测试通过。

python -m pytest -q ../tests/test_stage.py::test_scenario_path_escape_is_rejected

迁移挑战

使用 ScenarioContract 为办公场景创建合同，输入路径为 ../private.csv，验证其抛出包含 escapes 的 ValueError。

改变的条件: 将输入路径从合法路径改为包含 .. 的逃逸路径，同时保持场景为 office。

编写一个 Python 脚本或交互式命令，创建 ScenarioContract("office", ("../private.csv",), ("brief.md",), ("citations present",))，调用 validate()，并捕获 ValueError，检查错误消息是否包含 escapes。

完成标准

合同创建成功，场景为 office，输入路径为 ../private.csv。
调用 validate() 抛出 ValueError，且错误消息包含 escapes。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么路径逃逸检查必须同时拒绝绝对路径和包含 .. 的路径？如果只拒绝其中一种，会有什么风险？

一个有力回答应包含

绝对路径直接指向文件系统任意位置，不受包目录限制，可能读取任意文件。
包含 .. 的路径可以跳出当前目录，例如 ../private.csv 会访问上级目录的文件。
只拒绝绝对路径，攻击者可以使用相对路径 ../ 逃逸；只拒绝 ..，攻击者可以使用绝对路径。
两者结合才能确保输入路径始终位于包内。

掌握证据

通过测试 test_complete_scenario_contract_passes，证明合法合同能够通过验证。
通过测试 test_scenario_path_escape_is_rejected，证明路径逃逸被正确拒绝。
在 forge/portfolio/scenarios.py 中实现了路径检查逻辑，确保合同验证的完整性。

STAGE 02

把每次场景运行的输出、测试和追踪绑定为一个可验证结果

先看一个具体问题

交付结果缺少必需输出却被接受

在 Stage 01 中，我们定义了 ScenarioContract，它规定了每个场景必须交付哪些输出文件和通过哪些验收检查。现在需要实现 verify_delivery 函数，确保交付结果完整满足合同要求。

当前起始代码中 forge/portfolio/integration.py 文件尚未创建，因此测试在导入时就会失败。学习者需要创建该文件并实现 DeliveryResult 数据类和 verify_delivery 函数。

一个常见的错误是只检查结果中是否有任意输出，而忽略了合同要求的完整输出集合。例如，软件场景合同要求输出 patch.diff 和 test.txt，但结果只包含 patch.diff，如果只检查非空就会错误地接受这个不完整的交付。

本阶段的目标是让学习者理解验证必须基于合同要求进行集合减法，而不是仅检查非空。通过实现正确的验证逻辑，确保所有必需输出和验收检查都存在，并且 trace_id 非空。

先做判断

如果 verify_delivery 只检查 result.outputs 是否非空，会发生什么？

它会正确拒绝缺少 test.txt 的交付结果。
它会错误地接受缺少 test.txt 的交付结果。
它会因为类型错误而崩溃。
它会忽略验收检查。

判断依据: 正确答案是第二个选项。只检查非空无法发现缺失的必需输出，因为结果中至少有一个输出文件就会通过检查。正确的做法是从合同要求的输出集合中减去实际输出集合，如果差集非空则说明有缺失。

它是什么

合同覆盖验证

合同覆盖验证是一种基于集合运算的验证方法：将合同要求的输出集合和验收检查集合分别与实际结果中的输出集合和通过检查集合进行差集运算。

如果差集为空，说明所有要求都已满足；如果差集非空，则说明存在缺失项，交付不完整。

这种验证方式明确、可检查，不依赖于主观判断，能够精确指出缺失的具体项目。

它不是什么

不是非空检查

非空检查只验证结果中是否有任意输出，无法保证所有必需输出都存在。

它不能发现缺失的特定文件或检查，因此会错误地接受不完整的交付。

合同覆盖验证要求对每个必需项进行逐一核对，而不是笼统地判断是否存在输出。

它与相邻概念的关系

与 ScenarioContract 的关系

ScenarioContract 定义了场景的 expected_outputs 和 acceptance 集合，verify_delivery 使用这些集合作为验证的基准。

DeliveryResult 保存实际交付的输出和通过的检查，verify_delivery 将两者进行对比。

验证通过的条件是：场景名称匹配、所有 expected_outputs 都在 result.outputs 中、所有 acceptance 都在 result.passed_checks 中，并且 trace_id 非空。

本阶段的边界决定: 验证必须基于合同要求进行集合减法，而不是仅检查非空。如果只检查非空，就会漏掉缺失的必需输出或验收检查，导致不完整的交付被错误接受。

实验 ID: portfolio-delivery-02-end-to-end-evidence
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/portfolio-delivery/02-end-to-end-evidence/
验收: 待验收

教师示范

目标: 演示 verify_delivery 如何检查合同要求的所有输出和验收检查，展示完整结果通过和缺失输出被拒绝。

假设我们有一个软件场景合同，要求输出 patch.diff 和 test.txt，并通过检查 ‘tests pass’。

首先，我们创建一个完整的 DeliveryResult，包含所有必需输出和通过检查，然后调用 verify_delivery，应该不会抛出异常。

接着，我们创建一个缺少 test.txt 的 DeliveryResult，调用 verify_delivery 应该抛出包含 ‘incomplete’ 的 ValueError。

实施步骤

定义合同：ScenarioContract(‘software’, (‘spec.md’,), (‘patch.diff’,‘test.txt’), (‘tests pass’,))。
创建完整结果：DeliveryResult(‘software’, frozenset({‘patch.diff’,‘test.txt’}), frozenset({‘tests pass’}), ‘trace-1’)。
调用 verify_delivery(contract, result)，验证通过，无异常。
创建缺失结果：DeliveryResult(‘software’, frozenset({‘patch.diff’}), frozenset({‘tests pass’}), ‘trace-1’)。
调用 verify_delivery(contract, result)，抛出 ValueError，消息包含 ‘incomplete’。

真实 solution 代码: forge/portfolio/integration.py

from dataclasses import dataclass
from forge.portfolio.scenarios import ScenarioContract

@dataclass(frozen=True)
class DeliveryResult:
    scenario: str
    outputs: frozenset[str]
    passed_checks: frozenset[str]
    trace_id: str

def verify_delivery(contract: ScenarioContract, result: DeliveryResult) -> None:
    contract.validate()
    if result.scenario != contract.scenario:
        raise ValueError("scenario result mismatch")
    missing_outputs = set(contract.expected_outputs) - result.outputs
    missing_checks = set(contract.acceptance) - result.passed_checks
    if missing_outputs or missing_checks or not result.trace_id:
        raise ValueError("delivery evidence is incomplete")

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

verify_delivery 首先调用 contract.validate() 确保合同自身有效，然后检查场景名称是否匹配。

接着计算 missing_outputs = set(contract.expected_outputs) - result.outputs，如果差集非空则说明有缺失输出。

同样计算 missing_checks = set(contract.acceptance) - result.passed_checks，检查缺失的验收检查。

最后检查 trace_id 是否非空，任何一项不满足都会抛出 ValueError(‘delivery evidence is incomplete’)。

带提示练习

让学习者补全 verify_delivery 中缺失的集合减法逻辑，使测试通过。

创建 forge/portfolio/integration.py 文件。
定义 DeliveryResult 数据类，包含 scenario、outputs、passed_checks、trace_id 字段。
实现 verify_delivery 函数，首先调用 contract.validate() 并检查场景名称匹配。
计算 missing_outputs 和 missing_checks，如果任一非空或 trace_id 为空，则抛出 ValueError(‘delivery evidence is incomplete’)。
运行测试 python -m pytest -q tests/test_stage.py，确保两个测试都通过。

逐级提示

使用集合差集运算：set(contract.expected_outputs) - result.outputs。
不要忘记检查 trace_id 是否非空。
错误消息必须包含 ‘incomplete’，否则测试会失败。

完成标准

test_complete_delivery_passes 通过
test_missing_expected_output_is_rejected 通过

故障注入与排查

当前 faulty 版本的 forge/portfolio/integration.py 中，verify_delivery 只检查了 result.outputs 是否非空，而没有检查是否包含所有合同要求的输出。因此，当测试 test_missing_expected_output_is_rejected 传入只包含 patch.diff 的结果时，verify_delivery 不会抛出异常，导致测试失败。

本阶段学习的集合减法验证方法正是修复这个缺陷的关键。通过计算 missing_outputs 和 missing_checks，可以精确识别缺失的必需输出和验收检查，从而拒绝不完整的交付。

已验证的故障合同

目标测试: test_missing_expected_output_is_rejected
故障文件: forge/portfolio/integration.py

诊断顺序

运行测试 python -m pytest -q ../tests/test_stage.py::test_missing_expected_output_is_rejected，观察失败信息。
检查 forge/portfolio/integration.py 中的 verify_delivery 函数，发现只有 if not result.outputs: raise ValueError(‘outputs required’)。
这个检查只验证了 outputs 非空，没有验证是否包含所有合同要求的输出。
因此，当结果只包含 patch.diff 而缺少 test.txt 时，函数不会抛出异常，测试中的 else 分支触发 AssertionError。

修复原则: 修改 verify_delivery 函数，添加集合减法逻辑：missing_outputs = set(contract.expected_outputs) - result.outputs；missing_checks = set(contract.acceptance) - result.passed_checks；如果 missing_outputs 或 missing_checks 非空，或者 trace_id 为空，则抛出 ValueError(‘delivery evidence is incomplete’)。

python -m pytest -q ../tests/test_stage.py::test_missing_expected_output_is_rejected

迁移挑战

现在有一个办公场景的交付结果需要验证。合同要求输出 (‘brief.md’, ‘citations.txt’)，但结果只包含 ‘brief.md’。请使用 verify_delivery 验证这个结果，并确认它抛出包含 ‘incomplete’ 的 ValueError。

改变的条件: 场景从软件交付变为办公研究，合同要求的输出集合不同，且结果缺少一个必需输出。

编写一个测试或直接调用 verify_delivery，传入办公场景合同和只包含 ‘brief.md’ 的 DeliveryResult，断言抛出 ValueError 且消息包含 ‘incomplete’。

完成标准

验证调用 verify_delivery 时抛出 ValueError。
错误消息中包含 ‘incomplete’。
合同要求的输出集合为 (‘brief.md’, ‘citations.txt’)，结果只包含 ‘brief.md’，因此缺失 ‘citations.txt’。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么必须同时检查缺失的输出和缺失的验收检查？如果只检查输出非空，会漏掉什么情况？

一个有力回答应包含

只检查输出非空无法发现缺失的特定输出文件，例如缺少 test.txt 时仍可能通过。
验收检查同样重要，如果结果声称通过但实际缺少某个检查，交付也是不完整的。
同时检查两者才能确保交付结果完全满足合同要求，避免不完整的交付被接受。

掌握证据

通过测试 test_complete_delivery_passes，证明完整交付结果能够通过验证。
通过测试 test_missing_expected_output_is_rejected，证明缺失输出时验证会抛出包含 ‘incomplete’ 的 ValueError。
实现 verify_delivery 函数，使用集合减法检查缺失的输出和验收检查，并检查 trace_id 非空。

STAGE 03

对发布文件排序并计算内容哈希，使相同输入产生相同清单摘要

先看一个具体问题

为什么相同输入却得到不同清单？

你刚完成 Stage 02 的交付验证，现在需要把发布文件打包成清单。

测试 test_same_inputs_produce_same_manifest 要求两次调用 build_manifest("1.0", {"a.txt": b"a"}) 返回完全相同的字典。

但当前 forge/portfolio/packaging.py 文件尚未创建，测试收集阶段直接报错 ModuleNotFoundError。

你需要实现一个函数，让相同输入产生相同输出，这是可复现发布的基础。

先做判断

在实现 build_manifest 时，以下哪个做法最可能破坏可复现性？

对文件路径排序后再生成清单
在清单中加入当前时间戳
使用 SHA-256 计算文件内容哈希
用 JSON 序列化时固定键顺序

判断依据: 加入时间戳会让每次构建的清单不同，即使输入文件完全相同，因此无法通过 test_same_inputs_produce_same_manifest。排序和固定序列化顺序是保证确定性的关键。

它是什么

可复现清单是什么

可复现清单是一个确定性函数：给定相同的版本号和文件内容，总是生成完全相同的清单字典。

它只依赖版本号和排序后的文件条目，不包含任何随时间变化的元数据。

清单摘要 manifestSha256 是对规范化 JSON 字符串的哈希，因此相同输入必然得到相同摘要。

它不是什么

可复现清单不是什么

它不是包含构建时间、构建序号或随机数的日志，那些非确定性信息会让相同输入产生不同摘要。

它也不是简单地把文件字典原样输出，因为字典顺序可能不稳定，必须显式排序。

它不负责验证文件内容是否正确，只负责记录文件路径、哈希和大小。

它与相邻概念的关系

与其他概念的关系

可复现清单是 Stage 02 交付验证的延伸：验证通过后，用清单固化发布内容。

它依赖哈希函数（SHA-256）来唯一标识文件内容，任何内容变化都会改变哈希。

排序是保证确定性的关键，因为 JSON 序列化时键顺序可能影响最终字符串。

本阶段的边界决定: 如果清单中包含时间戳，相同输入会产生不同摘要，因此必须排除所有非确定性元数据，只保留版本和排序后的文件条目。

实验 ID: portfolio-delivery-03-reproducible-release-package
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/portfolio-delivery/03-reproducible-release-package/
验收: 待验收

教师示范

目标: 演示 build_manifest 如何对文件排序并计算确定性摘要，展示相同输入产生相同清单。

假设我们调用 build_manifest("1.0", {"z.txt": b"z", "a.txt": b"a"})。

函数首先对文件名排序，得到 ["a.txt", "z.txt"]。

然后为每个文件计算 SHA-256 哈希和字节数，生成条目列表。

最后将版本和条目列表序列化为规范化 JSON，并计算其 SHA-256 作为 manifestSha256。

实施步骤

对文件名字典的键进行排序。
遍历排序后的文件名，为每个文件创建条目字典，包含 path、sha256 和 bytes。
构造包含 version 和 files 的字典，用 json.dumps 以固定键顺序和紧凑分隔符序列化。
计算序列化字符串的 SHA-256 哈希，作为 manifestSha256。
返回包含 version、files 和 manifestSha256 的字典。

真实 solution 代码: forge/portfolio/packaging.py

import hashlib
import json

def build_manifest(version: str, files: dict[str, bytes]) -> dict[str, object]:
    if not version or not files:
        raise ValueError("version and files are required")
    entries=[]
    for name in sorted(files):
        if name.startswith("/") or ".." in name.split("/"):
            raise ValueError("release path escapes root")
        entries.append({"path":name,"sha256":hashlib.sha256(files[name]).hexdigest(),"bytes":len(files[name])})
    canonical=json.dumps({"version":version,"files":entries},sort_keys=True,separators=(",",":")).encode()
    return {"version":version,"files":entries,"manifestSha256":hashlib.sha256(canonical).hexdigest()}

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

排序确保无论输入字典顺序如何，文件条目顺序一致。

规范化 JSON 序列化使用 sort_keys=True 和固定分隔符，避免默认空格或键顺序导致字符串不同。

最终哈希只取决于版本和文件内容，因此相同输入必然得到相同摘要。

带提示练习

移除 build_manifest 中的非确定性元数据（如 buildSerial），使测试通过。

创建 forge/portfolio/packaging.py 文件。
实现 build_manifest 函数，先检查 version 和 files 非空，否则抛出 ValueError。
对文件名排序，并为每个文件计算 SHA-256 哈希和字节数。
构造规范化 JSON 字符串，只包含 version 和 files，使用 sort_keys=True 和紧凑分隔符。
计算该字符串的 SHA-256 哈希作为 manifestSha256，返回完整字典。

逐级提示

不要包含任何全局计数器或时间戳。
使用 sorted(files) 获取排序后的文件名列表。
json.dumps 时设置 sort_keys=True, separators=(',', ':') 确保输出稳定。

完成标准

test_manifest_lists_sorted_files 通过，文件顺序为 ['a.txt', 'z.txt']。
test_same_inputs_produce_same_manifest 通过，两次调用返回相同字典。

故障注入与排查

你实现了 build_manifest，但测试 test_same_inputs_produce_same_manifest 仍然失败。运行 python -m pytest -q ../tests/test_stage.py::test_same_inputs_produce_same_manifest 显示两次调用返回的字典不同，差异在于 buildSerial 和 manifestSha256。可执行故障夹具修改 forge/portfolio/packaging.py，并由 test_same_inputs_produce_same_manifest 稳定复现。

本阶段的核心是可复现性，你已经知道清单摘要必须只依赖版本和排序后的文件内容。当前故障正是由于在哈希中混入了非确定性元数据 buildSerial，导致相同输入产生不同摘要。通过移除该字段并重新计算哈希，可以修复此问题。

已验证的故障合同

目标测试: test_same_inputs_produce_same_manifest
故障文件: forge/portfolio/packaging.py

诊断顺序

运行故障测试，观察断言失败信息。
注意到两次调用返回的字典中 buildSerial 不同，导致 manifestSha256 不同。
检查 build_manifest 源码，发现它使用了全局变量 _build_serial 并在每次调用时递增。
确认该字段被包含在用于计算哈希的 payload 中，因此哈希随调用次数变化。

修复原则: 移除 buildSerial 字段和全局计数器，只使用 version 和排序后的 files 条目构造规范化 JSON，然后计算哈希。这样相同输入必然产生相同摘要。

python -m pytest -q ../tests/test_stage.py::test_same_inputs_produce_same_manifest

迁移挑战

音乐场景需要发布清单，文件为 {'track.mp3': b'music', 'cover.jpg': b'image'}。

改变的条件: 将文件集合从文本文件改为音乐场景的音频和图片文件，但保持函数接口不变。

使用 build_manifest 为音乐场景构建清单，验证两次调用返回相同的 manifestSha256。

完成标准

两次调用 build_manifest('1.0', {'track.mp3': b'music', 'cover.jpg': b'image'}) 返回的字典完全相等。
清单中文件顺序为 ['cover.jpg', 'track.mp3']，且每个文件条目的 sha256 和 bytes 正确。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么文件顺序会影响清单摘要？如果两个文件内容相同但顺序不同，清单摘要会改变吗？请解释排序在可复现性中的作用。

一个有力回答应包含

文件顺序影响序列化后的 JSON 字符串，因为 files 列表的顺序不同会导致字符串不同。
即使文件内容相同，顺序不同也会改变哈希，因此必须排序以保证确定性。
排序确保无论输入字典顺序如何，输出清单的文件列表顺序一致，从而保证相同输入产生相同摘要。

掌握证据

通过测试 test_manifest_lists_sorted_files，验证文件按路径排序。
通过测试 test_same_inputs_produce_same_manifest，验证相同输入产生相同清单。
在故障实验室中成功移除 buildSerial，修复非确定性元数据问题。

STAGE 04

用可检查的演示步骤连接用户问题、系统动作和证据文件

先看一个具体问题

演示脚本缺少证据路径导致不可验证

你正在为 HeatStack Forge 准备一个演示脚本，脚本包含三个步骤：展示请求、执行命令、展示测试结果。

当前代码中 validate_demo 只检查了叙述字段，没有检查命令和证据路径，导致一个缺少证据路径的步骤也能通过验证。

测试 test_demo_without_evidence_path_is_rejected 期望当证据路径为空时抛出包含 ‘incomplete’ 的 ValueError，但当前代码会接受这个不完整的步骤。

你需要修改 forge/portfolio/demo.py 中的 validate_demo 函数，确保每个步骤的叙述、命令和证据路径都非空。

先做判断

如果 validate_demo 只检查叙述字段，会发生什么？

缺少证据路径的步骤会被接受，演示无法验证
缺少命令的步骤会被拒绝，但缺少证据路径的步骤会被接受
所有步骤都会被拒绝，因为叙述字段可能为空
演示脚本无法运行，因为缺少必要的字段

判断依据: 正确答案是第一个选项。只检查叙述字段会导致缺少证据路径的步骤被接受，因为验证逻辑没有覆盖命令和证据路径。

它是什么

演示验证是完整性检查

演示验证通过检查每个步骤的叙述、命令和证据路径是否非空，确保演示脚本的每个步骤都有可验证的证据。

它使用 all() 函数同时检查三个字段，任何一个为空都会抛出 ValueError。

它不是什么

演示验证不是内容质量评估

演示验证不检查叙述是否优美、命令是否最优或证据文件是否真实存在，它只检查字段是否非空。

它也不检查步骤之间的逻辑顺序或步骤 ID 是否唯一，这些是其他验证逻辑的职责。

它与相邻概念的关系

演示验证与测试的关系

测试 test_complete_demo_passes 验证完整演示通过，而 test_demo_without_evidence_path_is_rejected 验证缺失证据路径被拒绝。

validate_demo 函数是这两个测试的核心，它必须同时满足通过和拒绝的条件。

本阶段的边界决定: 演示验证必须要求每个步骤都有叙述、命令和证据路径，缺少任何一项都不可验证。

实验 ID: portfolio-delivery-04-verifiable-demo-script
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/portfolio-delivery/04-verifiable-demo-script/
验收: 待验收

教师示范

目标: 演示 validate_demo 如何检查每个步骤的叙述、命令和证据路径，展示完整演示通过和缺失证据被拒绝。

我们首先定义一个 DemoStep 数据类，包含 step_id、narration、command 和 evidence_path 四个字段。

然后实现 validate_demo 函数，它接收一个 DemoStep 元组，检查步骤数量至少为 3，并且每个步骤的叙述、命令和证据路径都非空。

最后运行测试，验证完整演示通过，缺失证据路径的演示被拒绝。

实施步骤

定义 DemoStep 数据类，包含 step_id、narration、command 和 evidence_path 字段。
实现 validate_demo 函数，检查步骤数量至少为 3。
在循环中检查每个步骤的叙述、命令和证据路径是否非空，使用 all() 函数。
如果任何字段为空，抛出包含 ‘incomplete’ 的 ValueError。

真实 solution 代码: forge/portfolio/demo.py

from dataclasses import dataclass

@dataclass(frozen=True)
class DemoStep:
    step_id: str
    narration: str
    command: str
    evidence_path: str

def validate_demo(steps: tuple[DemoStep, ...]) -> None:
    if len(steps) < 3:
        raise ValueError("demo needs setup, action, and proof")
    ids=[step.step_id for step in steps]
    if len(ids)!=len(set(ids)):
        raise ValueError("demo step IDs must be unique")
    for step in steps:
        if not all((step.narration.strip(),step.command.strip(),step.evidence_path.strip())):
            raise ValueError("demo step is incomplete")

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

validate_demo 首先检查步骤数量，确保演示包含至少三个步骤。

然后对每个步骤使用 all() 检查叙述、命令和证据路径是否非空，任何一个为空都会抛出 ValueError。

测试 test_complete_demo_passes 使用完整步骤，因此通过；测试 test_demo_without_evidence_path_is_rejected 将第三个步骤的证据路径设为空字符串，因此抛出 ValueError。

带提示练习

补全 validate_demo 中缺失的证据路径检查，使测试通过。

打开 forge/portfolio/demo.py 文件。
在 validate_demo 函数的循环中，添加对 step.command 和 step.evidence_path 的非空检查。
使用 all() 函数同时检查三个字段，如果任何一个为空，抛出包含 ‘incomplete’ 的 ValueError。
运行测试 python -m pytest -q tests/test_stage.py，确保两个测试都通过。

逐级提示

提示：all() 函数可以同时检查多个条件，例如 all((step.narration.strip(), step.command.strip(), step.evidence_path.strip()))。
提示：确保错误消息包含 ‘incomplete’，因为测试断言了这一点。

完成标准

validate_demo 函数检查每个步骤的叙述、命令和证据路径。
测试 test_complete_demo_passes 和 test_demo_without_evidence_path_is_rejected 都通过。

故障注入与排查

你正在运行故障夹具 fixtures/failure.json，其中 test_demo_without_evidence_path_is_rejected 测试失败。故障代码只检查叙述字段，导致缺少证据路径的步骤被接受。你需要诊断并修复这个问题。

本阶段已经学习了演示验证的完整性检查，知道必须同时检查叙述、命令和证据路径。故障代码缺少对命令和证据路径的检查，因此可以通过添加这些检查来修复。

已验证的故障合同

目标测试: test_demo_without_evidence_path_is_rejected
故障文件: forge/portfolio/demo.py

诊断顺序

运行故障测试命令 python -m pytest -q ../tests/test_stage.py::test_demo_without_evidence_path_is_rejected，观察测试失败。
查看 forge/portfolio/demo.py 中的 validate_demo 函数，发现它只检查了 step.narration，没有检查 step.command 和 step.evidence_path。
修改 validate_demo 函数，使用 all() 同时检查三个字段，并在任何字段为空时抛出包含 ‘incomplete’ 的 ValueError。
重新运行测试，确认测试通过。

修复原则: 在 validate_demo 函数的循环中，将 if not step.narration.strip(): 替换为 if not all((step.narration.strip(), step.command.strip(), step.evidence_path.strip())):，并确保错误消息包含 ‘incomplete’。

python -m pytest -q ../tests/test_stage.py::test_demo_without_evidence_path_is_rejected

迁移挑战

你有一个办公场景的演示脚本，包含三个步骤。第三个步骤的证据路径为空字符串。使用 DemoStep 数据类创建这三个步骤，并用 validate_demo 验证这个演示，确认它抛出包含 ‘incomplete’ 的 ValueError。

改变的条件: 将第三个步骤的证据路径从有效路径改为空字符串，模拟缺失证据的情况。

使用 DemoStep 数据类创建三个步骤，其中第三个步骤的 evidence_path 为空字符串。调用 validate_demo 并捕获 ValueError，断言错误消息包含 ‘incomplete’。

完成标准

演示元组包含三个 DemoStep 实例，第三个步骤的 evidence_path 为空字符串。
调用 validate_demo 抛出 ValueError，且错误消息包含 ‘incomplete’。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么证据路径对于演示的可验证性至关重要？如果只检查叙述，演示脚本会有什么问题？

一个有力回答应包含

证据路径指向实际生成的证据文件，是验证演示步骤是否真实执行的关键。
只检查叙述会导致缺少证据的步骤被接受，演示无法复现，失去可信度。

掌握证据

通过测试 test_complete_demo_passes，证明完整演示可以通过验证。
通过测试 test_demo_without_evidence_path_is_rejected，证明缺失证据路径的演示会被拒绝。
成功修复故障夹具中的缺陷，使 test_demo_without_evidence_path_is_rejected 测试通过。

STAGE 05

记录上下文、选择、备选与后果，拒绝只有结论没有取舍依据的架构说明

先看一个具体问题

为什么只有决策 ID 和选择的记录无法通过验证？

在上一阶段，我们通过 DemoStep 和 validate_demo 验证了演示脚本的步骤完整性，但架构决策记录（ADR）还没有被纳入验证范围。

当前测试 test_decision_without_alternatives_is_rejected 期望：当 alternatives 为空元组时，DecisionRecord.validate() 必须抛出包含 'tradeoff' 的 ValueError。

然而，如果 validate() 只检查 decision_id 和 choice 是否非空，那么一个没有备选方案、后果和证据的记录也会被接受，导致测试失败。

你需要实现 DecisionRecord.validate()，确保它拒绝缺少取舍依据的架构决策记录。

先做判断

在实现 DecisionRecord.validate() 之前，请预测：如果只检查 decision_id 和 choice 非空，会发生什么？

所有测试都会通过，因为决策 ID 和选择已经足够。
test_decision_without_alternatives_is_rejected 会失败，因为空 alternatives 不会被拒绝。
test_complete_decision_record_passes 会失败，因为完整记录也会被拒绝。
两个测试都会失败，因为 validate() 没有实现。

判断依据: 正确答案是第二个选项。只检查 decision_id 和 choice 会让空 alternatives 的记录通过验证，从而触发测试中的 AssertionError。

它是什么

架构决策记录（ADR）的验证是什么？

ADR 验证是一种外部可检查的规则，确保每个决策记录不仅包含决策 ID 和选择，还包含上下文、备选方案、后果和证据。

DecisionRecord.validate() 通过检查这些字段是否非空，以及选择是否不在备选方案中，来保证记录包含足够的取舍依据。

它不是什么

ADR 验证不是什么？

它不是让模型对自己的决策再给一次意见，也不是仅仅检查决策 ID 是否存在。

它不关心决策内容是否正确，只关心记录是否完整地呈现了决策的上下文、备选方案、后果和证据。

它与相邻概念的关系

ADR 验证与其他概念的关系

ADR 验证是 Verification 概念的具体应用：通过测试和规则检查一次结果，而不是通过数据集衡量多次运行表现。

它与 Observability 相关，因为完整的 ADR 提供了决策的上下文和证据，有助于解释系统为什么这样设计。

它与 Agent Loop 的停止条件相关：如果决策记录不完整，验证失败，循环应该继续补充信息。

本阶段的边界决定: 边界决策：验证必须基于外部可检查的证据（字段非空、选择不在备选方案中），而不是模型的主观判断。

实验 ID: portfolio-delivery-05-architecture-decision-records
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/portfolio-delivery/05-architecture-decision-records/
验收: 待验收

教师示范

目标: 演示 DecisionRecord.validate() 如何检查备选方案、后果和证据，展示完整记录通过和缺失备选被拒绝。

假设我们有一个完整的决策记录：DecisionRecord("adr-1", "Need recovery", "SQLite", ("Redis",), ("single-node",), ("recovery-test.txt",))。

调用 validate() 时，它会检查所有字段非空，并且 choice 不在 alternatives 中，因此不会抛出异常。

如果我们创建一个缺少备选方案的记录：DecisionRecord("adr-1", "Need recovery", "SQLite", (), ("single-node",), ("test.txt",))，validate() 应该抛出 ValueError，因为 alternatives 为空。

实施步骤

定义 DecisionRecord 数据类，包含 decision_id、context、choice、alternatives、consequences、evidence 字段。
实现 validate() 方法，首先检查 decision_id、context、choice 是否非空。
然后检查 alternatives、consequences、evidence 是否非空。
最后检查 choice 是否不在 alternatives 中。

真实 solution 代码: forge/portfolio/architecture.py

from dataclasses import dataclass

@dataclass(frozen=True)
class DecisionRecord:
    decision_id: str
    context: str
    choice: str
    alternatives: tuple[str, ...]
    consequences: tuple[str, ...]
    evidence: tuple[str, ...]

    def validate(self) -> None:
        if not all((self.decision_id.strip(),self.context.strip(),self.choice.strip())):
            raise ValueError("decision identity and context are required")
        if not self.alternatives or not self.consequences or not self.evidence:
            raise ValueError("decision tradeoff evidence is incomplete")
        if self.choice in self.alternatives:
            raise ValueError("chosen option cannot be listed as rejected alternative")

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

完整记录通过验证，因为所有字段都非空，且 choice 不在 alternatives 中。

缺失备选方案的记录被拒绝，因为 alternatives 为空，触发了 ValueError。

带提示练习

补全 DecisionRecord.validate() 中缺失的备选方案检查，使测试通过。

打开 forge/portfolio/architecture.py 文件。
在 validate() 方法中，添加检查 alternatives、consequences、evidence 是否非空的代码。
添加检查 choice 是否不在 alternatives 中的代码。
运行测试命令验证。

逐级提示

使用 if not self.alternatives or not self.consequences or not self.evidence: 来检查空元组。
使用 if self.choice in self.alternatives: 来检查选择是否在备选方案中。
确保错误消息包含 'tradeoff' 字符串，以满足测试断言。

完成标准

test_complete_decision_record_passes 通过。
test_decision_without_alternatives_is_rejected 通过。

故障注入与排查

故障夹具 fixtures/failure.json 中定义了一个缺陷：DecisionRecord.validate() 只检查决策 ID 和选择，导致没有备选方案的记录也能通过验证。测试 test_decision_without_alternatives_is_rejected 因此失败，因为空 alternatives 没有被拒绝。

本阶段已经学习了如何实现完整的 validate() 方法，包括检查备选方案、后果和证据。因此，学习者能够识别出缺陷在于缺少这些检查，并修复它。

已验证的故障合同

目标测试: test_decision_without_alternatives_is_rejected
故障文件: forge/portfolio/architecture.py

诊断顺序

运行故障命令 python -m pytest -q ../tests/test_stage.py::test_decision_without_alternatives_is_rejected，观察测试失败。
查看测试代码，发现它创建了一个 alternatives 为空元组的 DecisionRecord，并期望 validate() 抛出 ValueError。
检查 forge/portfolio/architecture.py 中的 validate() 实现，发现它只检查了 decision_id 和 choice，没有检查 alternatives、consequences、evidence。
因此，空 alternatives 没有被拒绝，测试抛出 AssertionError。

修复原则: 在 validate() 方法中添加对 alternatives、consequences、evidence 的非空检查，并确保错误消息包含 'tradeoff'。同时添加检查 choice 不在 alternatives 中。

python -m pytest -q ../tests/test_stage.py::test_decision_without_alternatives_is_rejected

迁移挑战

在办公研究场景中，你需要为一个决策简报记录架构决策。使用 DecisionRecord 创建一个记录，其中 alternatives 为空元组，验证其抛出包含 'tradeoff' 的 ValueError。

改变的条件: 将场景从软件交付改为办公研究，并改变决策内容，但保持 alternatives 为空元组以触发验证失败。

编写一个 Python 脚本，导入 DecisionRecord，创建一个 alternatives 为空元组的记录，并调用 validate()，捕获并打印异常消息。

完成标准

脚本成功创建 DecisionRecord 实例，其中 alternatives 为空元组。
调用 validate() 时抛出 ValueError，且异常消息包含 'tradeoff'。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么备选方案对于架构决策记录是必需的？如果只记录决策 ID 和选择，会丢失什么信息？

一个有力回答应包含

备选方案展示了决策时的其他可能选择，体现了权衡过程。
没有备选方案，就无法判断当前选择是否经过充分比较，决策可能缺乏依据。
只记录决策 ID 和选择会丢失上下文、后果和证据，导致无法评估决策的合理性。

掌握证据

通过测试 test_complete_decision_record_passes，证明完整的决策记录能够通过验证。
通过测试 test_decision_without_alternatives_is_rejected，证明缺少备选方案的记录会被拒绝。
在故障实验室中成功修复 validate() 方法，使故障测试通过。

STAGE 06

按场景、能力和证据类型建立索引，并防止同一路径被不同哈希覆盖

先看一个具体问题

证据索引必须防止同一路径出现冲突哈希

在作品集交付中，我们需要把不同场景产生的证据（如文件、报告、测试结果）组织成可搜索的索引，以便后续按能力或场景快速查找。

当前 forge/portfolio/evidence_index.py 文件尚未创建，测试 test_evidence_is_grouped_by_capability 和 test_conflicting_hash_for_same_path_is_rejected 会因导入错误而失败。

如果只是简单地把每个证据条目追加到列表里，而不检查同一路径是否已经记录了不同的内容哈希，索引就会变得自相矛盾：同一个文件路径对应两个不同的内容指纹，下游消费者无法判断哪个是真实的。

因此，本阶段的核心决策是：在构建索引时维护一个路径到哈希的映射，一旦发现同一路径出现不同哈希，立即抛出包含 conflicting 的 ValueError，而不是静默覆盖或并存。

先做判断

在 build_index 中，如果同一个 path 先后出现两个不同的 sha256，以下哪种处理方式最符合证据索引的不可变身份要求？

直接追加第二个条目，让列表包含两个哈希，由使用者自行判断。
用后出现的哈希覆盖先前的哈希，保持路径唯一。
检测到冲突时抛出 ValueError，并让错误信息包含 conflicting。
忽略第二个条目，只保留第一个哈希。

判断依据: 证据索引必须保证路径与内容哈希的一一对应，否则同一路径指向两个不同内容会让下游无法确定真实证据。因此，检测到冲突时应当拒绝并抛出异常，而不是覆盖或并存。

它是什么

证据索引是路径到哈希的不可变映射

证据索引把每个证据条目按能力（capability）分组，并在组内记录路径、场景、类型和内容哈希。

它同时维护一个全局的路径到哈希映射，用于在插入新条目时检查该路径是否已经出现过且哈希一致。

如果同一路径的哈希一致，可以安全地重复引用；如果哈希不同，说明内容已经改变或存在冲突，必须拒绝。

它不是什么

证据索引不是简单的追加列表

它不能允许同一路径携带多个不同的哈希，因为那样会让索引失去可信度。

它也不是一个自动去重或覆盖的存储结构；冲突必须显式抛出异常，让调用方决定如何处理。

它不负责验证哈希本身的正确性，只负责维护路径与哈希之间的一致性约束。

它与相邻概念的关系

索引与证据项、能力分组的关系

EvidenceItem 是不可变数据类，包含 path、sha256、scenario、capability 和 kind 五个字段。

build_index 接收一个 EvidenceItem 元组，返回一个字典：键是能力名称，值是该能力下的证据条目列表。

在构建过程中，seen 字典记录每个路径首次出现的哈希，后续条目如果路径相同但哈希不同，就会触发冲突异常。

本阶段的边界决定: 当且仅当同一路径已经存在且哈希不同时，必须抛出包含 conflicting 的 ValueError；如果哈希相同，则允许重复引用。

实验 ID: portfolio-delivery-06-searchable-evidence-index
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/portfolio-delivery/06-searchable-evidence-index/
验收: 待验收

教师示范

目标: 演示 build_index 如何按能力分组，并在检测到路径哈希冲突时抛出异常。

假设我们有两个证据项：一个来自软件场景的恢复能力，路径为 a.txt，哈希为 64 个 a；另一个来自同一场景和能力，路径也是 a.txt，但哈希为 64 个 b。

调用 build_index 处理这两个条目时，第一个条目正常加入 recovery 组，并记录 seen['a.txt'] = 'a'*64。

处理第二个条目时，发现 a.txt 已经在 seen 中，且哈希不同，于是抛出 ValueError("evidence path has conflicting hashes")。

实施步骤

创建 EvidenceItem 元组，包含两个路径相同但哈希不同的条目。
调用 build_index，观察它抛出 ValueError。
检查异常消息中包含 conflicting，确认冲突被正确识别。

真实 solution 代码: forge/portfolio/evidence_index.py

from dataclasses import dataclass

@dataclass(frozen=True)
class EvidenceItem:
    path: str
    sha256: str
    scenario: str
    capability: str
    kind: str

def build_index(items: tuple[EvidenceItem, ...]) -> dict[str, list[dict[str,str]]]:
    seen: dict[str,str]={}
    index: dict[str,list[dict[str,str]]]={}
    for item in items:
        if item.path in seen and seen[item.path] != item.sha256:
            raise ValueError("evidence path has conflicting hashes")
        seen[item.path]=item.sha256
        index.setdefault(item.capability,[]).append({"path":item.path,"scenario":item.scenario,"kind":item.kind,"sha256":item.sha256})
    for entries in index.values(): entries.sort(key=lambda value:value["path"])
    return index

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

这个测试故意传入两个路径相同但哈希不同的证据项，期望 build_index 抛出包含 conflicting 的 ValueError。

当前实现只是简单追加，没有检查冲突，所以测试失败并抛出 AssertionError。

修复方法是在循环中维护 seen 字典，当发现路径已存在且哈希不同时，抛出 ValueError。

带提示练习

补全 build_index 中缺失的路径哈希冲突检查，使两个测试都通过。

在 forge/portfolio/evidence_index.py 中定义 EvidenceItem 数据类和 build_index 函数。
在 build_index 内部初始化 seen 字典和 index 字典。
遍历每个 EvidenceItem，检查 item.path 是否已在 seen 中且哈希不同，若是则抛出 ValueError。
将当前条目的路径和哈希记录到 seen，并按能力分组追加到 index。
最后对每个能力下的条目按路径排序，返回索引。

逐级提示

使用 if item.path in seen and seen[item.path] != item.sha256: 来检测冲突。
异常消息必须包含 conflicting，例如 raise ValueError("evidence path has conflicting hashes")。
排序可以使用 entries.sort(key=lambda value: value["path"])。

完成标准

test_evidence_is_grouped_by_capability 通过，索引按能力正确分组。
test_conflicting_hash_for_same_path_is_rejected 通过，冲突时抛出包含 conflicting 的 ValueError。

故障注入与排查

故障夹具 fixtures/failure.json 描述了一个证据路径冲突场景：同一个路径 a.txt 被两个不同的内容哈希索引。运行测试 test_conflicting_hash_for_same_path_is_rejected 会失败，因为当前 build_index 实现只是追加条目而没有检查路径身份。

本阶段已经建立了路径到哈希映射的思维模型，并知道必须在冲突时拒绝。学习者可以定位到 forge/portfolio/evidence_index.py 中的 build_index 函数，发现缺少 seen 字典和冲突检查，从而修复缺陷。

已验证的故障合同

目标测试: test_conflicting_hash_for_same_path_is_rejected
故障文件: forge/portfolio/evidence_index.py

诊断顺序

运行故障命令 python -m pytest -q ../tests/test_stage.py::test_conflicting_hash_for_same_path_is_rejected，观察测试失败并抛出 AssertionError: ambiguous evidence path was indexed。
检查 forge/portfolio/evidence_index.py 中的 build_index 函数，发现它只是用 setdefault 追加条目，没有维护路径到哈希的映射。
确认缺陷：当两个 EvidenceItem 具有相同路径但不同哈希时，索引会同时包含两个条目，导致路径身份冲突。

修复原则: 在 build_index 中增加 seen 字典，遍历时检查路径是否已存在且哈希不同，若是则抛出 ValueError("evidence path has conflicting hashes")；否则记录路径和哈希，并继续追加条目。最后对每个能力下的条目按路径排序。

python -m pytest -q ../tests/test_stage.py::test_conflicting_hash_for_same_path_is_rejected

迁移挑战

音乐创作场景中，两个证据项都指向同一个音频文件 track.mp3，但内容哈希不同。你需要使用 EvidenceItem 和 build_index 构建索引，并验证系统会拒绝这种冲突。

改变的条件: 将场景从软件交付改为音乐创作，并改变证据路径为 track.mp3，同时保持两个条目的哈希不同。

编写一个测试或脚本，创建两个 EvidenceItem，路径均为 track.mp3，场景为 music，能力为 release，类型为 audio，但哈希分别为 64 个 c 和 64 个 d。调用 build_index，断言它抛出 ValueError 且消息包含 conflicting。

完成标准

断言 build_index 对这两个条目抛出 ValueError。
断言异常消息中包含 conflicting，证明冲突被正确识别。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么证据索引必须在同一路径出现不同哈希时拒绝，而不是静默覆盖或并存？请从下游消费者和证据可信度的角度解释。

一个有力回答应包含

同一路径对应不同哈希意味着内容已经改变或存在冲突，如果并存，下游无法确定哪个是真实证据。
静默覆盖会丢失历史信息，且可能掩盖错误；拒绝并抛出异常迫使调用方显式处理冲突，保证索引的不可变身份。

掌握证据

通过测试 test_evidence_is_grouped_by_capability，证明索引能按能力正确分组。
通过测试 test_conflicting_hash_for_same_path_is_rejected，证明冲突检测机制有效。
在故障实验室中成功修复 build_index，使故障测试从失败转为通过。

STAGE 07

只有三场景、架构说明、演示脚本和证据索引齐全时发布 Forge 1

先看一个具体问题

发布门禁必须检查所有必需场景和部分

当前 forge/portfolio/release.py 文件尚未创建，测试 test_complete_portfolio_publishes 和 test_missing_music_scenario_blocks_release 在导入模块时就会失败。

你需要实现 PortfolioRelease 数据类和 publish 函数，使完整作品集能够发布，而缺少音乐场景的作品集被阻止并抛出包含 ‘music’ 的 ValueError。

发布门禁不能只检查场景集合非空，必须对照必需的场景集合和部分集合进行验证。

先做判断

如果 publish 函数只检查 release.scenarios 是否非空，当传入只包含 software 和 office 两个场景的作品集时，会发生什么？

发布成功，因为场景集合非空
抛出 ValueError，因为缺少 music 场景
返回空字符串
抛出 TypeError

判断依据: 正确答案是“发布成功，因为场景集合非空”。只检查非空无法发现缺失的必需场景，这正是故障夹具中注入的缺陷。

它是什么

发布门禁是对照必需集合的完整性检查

发布门禁将作品集中包含的场景集合与 REQUIRED_SCENARIOS 常量定义的必需场景集合进行比较，任何缺失的场景都会导致发布失败。

同样，它也会检查必需的部分集合 REQUIRED_SECTIONS，确保架构说明、演示脚本和证据索引等关键部分都存在。

只有当两个集合都没有缺失时，publish 才会返回发布标识符。

它不是什么

发布门禁不是简单的非空检查

发布门禁不会因为场景集合中至少有一个元素就认为作品集完整，它必须包含所有三个场景：software、office 和 music。

它也不是对作品集质量的评分，而是对发布契约的硬性验证，任何缺失都会阻止发布。

发布门禁不负责生成缺失的内容，它只负责检测并报告缺失项。

它与相邻概念的关系

发布门禁与作品集组件的关系

PortfolioRelease 数据类封装了版本号、场景集合、部分集合和工件哈希，publish 函数使用这些字段进行验证。

REQUIRED_SCENARIOS 和 REQUIRED_SECTIONS 常量定义了发布契约，测试用例根据这些契约构造输入并断言行为。

故障夹具中的缺陷是只检查场景非空，导致缺少 music 场景的作品集被错误发布。

本阶段的边界决定: 发布门禁必须对照必需集合检查场景和部分，任何缺失都会阻止发布；不能只检查非空或存在任意场景。

实验 ID: portfolio-delivery-07-portfolio-release-gate
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/portfolio-delivery/07-portfolio-release-gate/
验收: 待验收

教师示范

目标: 演示 publish 如何检查必需场景和部分，展示完整作品集发布成功和缺失音乐场景被阻止。

我们首先定义 REQUIRED_SCENARIOS 和 REQUIRED_SECTIONS 常量，然后创建 PortfolioRelease 数据类。

在 publish 函数中，我们计算缺失的场景和部分，如果任一集合非空则抛出 ValueError，否则返回发布标识符。

通过运行测试，我们看到完整作品集发布成功，而缺少 music 场景的作品集抛出包含 ‘music’ 的错误。

实施步骤

创建 forge/portfolio/release.py 文件。
定义 REQUIRED_SCENARIOS 和 REQUIRED_SECTIONS 常量。
定义 PortfolioRelease 数据类，包含 version、scenarios、sections 和 artifact_sha256 字段。
实现 publish 函数，计算缺失集合并抛出异常或返回标识符。
运行测试验证行为。

真实 solution 代码: forge/portfolio/release.py

from dataclasses import dataclass

REQUIRED_SCENARIOS=frozenset({"software","office","music"})
REQUIRED_SECTIONS=frozenset({"overview","architecture","evaluation","failures","demo","evidence"})

@dataclass(frozen=True)
class PortfolioRelease:
    version:str
    scenarios:frozenset[str]
    sections:frozenset[str]
    artifact_sha256:str

def publish(release: PortfolioRelease)->str:
    missing_scenarios=REQUIRED_SCENARIOS-release.scenarios
    missing_sections=REQUIRED_SECTIONS-release.sections
    if missing_scenarios or missing_sections:
        raise ValueError(f"portfolio incomplete scenarios={sorted(missing_scenarios)} sections={sorted(missing_sections)}")
    if len(release.artifact_sha256)!=64:
        raise ValueError("artifact hash is invalid")
    return f"forge-{release.version}-{release.artifact_sha256[:12]}"

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

为什么这样实现

missing_scenarios = REQUIRED_SCENARIOS - release.scenarios 计算缺失的场景集合，如果非空则说明作品集不完整。

missing_sections = REQUIRED_SECTIONS - release.sections 同样检查必需的部分。

当缺少 music 场景时，missing_scenarios 包含 ‘music’，因此抛出 ValueError，错误消息中包含 ‘music’。

带提示练习

补全 publish 中缺失的必需场景检查，使测试通过。

打开 forge/portfolio/release.py 文件。
定义 REQUIRED_SCENARIOS 常量，包含 ‘software’、‘office’ 和 ‘music’。
定义 REQUIRED_SECTIONS 常量，包含 ‘overview’、‘architecture’、‘evaluation’、‘failures’、‘demo’ 和 ‘evidence’。
在 publish 函数中，计算 missing_scenarios 和 missing_sections。
如果任一缺失集合非空，抛出 ValueError，错误消息中包含缺失项。
运行测试 python -m pytest -q tests/test_stage.py 验证通过。

逐级提示

使用集合差集操作 REQUIRED_SCENARIOS - release.scenarios 来找出缺失的场景。
错误消息中应包含缺失的场景名称，例如 ‘music’。
不要忘记检查 artifact_sha256 的长度是否为 64。

完成标准

test_complete_portfolio_publishes 测试通过。
test_missing_music_scenario_blocks_release 测试通过，且错误消息包含 ‘music’。

故障注入与排查

故障夹具 fixtures/failure.json 中，forge/portfolio/release.py 的 publish 函数只检查 release.scenarios 是否非空，而没有对照必需的场景集合。当运行测试 test_missing_music_scenario_blocks_release 时，传入只包含 software 和 office 两个场景的作品集，publish 函数错误地返回了发布标识符，导致测试失败并抛出 AssertionError: two-scenario portfolio was published as complete。

本阶段已经学习了发布门禁必须对照必需集合检查场景和部分，因此能够识别出只检查非空是错误的。通过实现缺失集合的计算和异常抛出，可以修复这个缺陷，使测试通过。

已验证的故障合同

目标测试: test_missing_music_scenario_blocks_release
故障文件: forge/portfolio/release.py

诊断顺序

运行测试 python -m pytest -q ../tests/test_stage.py::test_missing_music_scenario_blocks_release，观察到测试失败并抛出 AssertionError。
检查 forge/portfolio/release.py 中的 publish 函数，发现它只检查 if not release.scenarios，而没有检查是否包含所有必需场景。
对比测试期望：缺少 music 场景时应该抛出 ValueError 且错误消息包含 ‘music’。
修复方法：定义 REQUIRED_SCENARIOS 常量，计算缺失场景，如果缺失则抛出 ValueError。

修复原则: 在 forge/portfolio/release.py 中定义 REQUIRED_SCENARIOS 和 REQUIRED_SECTIONS 常量，并在 publish 函数中计算缺失集合，如果任一缺失则抛出包含缺失项名称的 ValueError。同时检查 artifact_sha256 的长度是否为 64。

python -m pytest -q ../tests/test_stage.py::test_missing_music_scenario_blocks_release

迁移挑战

使用 PortfolioRelease 和发布函数尝试发布一个缺少 music 场景的作品集，验证其抛出包含 ‘music’ 的 ValueError。

改变的条件: 将作品集的场景集合从完整的三个场景改为只包含 software 和 office 两个场景，以触发发布门禁的缺失检查。

编写一个测试或脚本，构造一个 PortfolioRelease 实例，其 scenarios 字段为 frozenset({'software', 'office'})，sections 字段为完整的必需部分集合，artifact_sha256 为 64 个字符的字符串。调用发布函数，断言它抛出 ValueError 且错误消息中包含 ‘music’。

完成标准

调用发布函数时抛出 ValueError 异常。
异常消息中包含字符串 ‘music’。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

..                                                                       [100%]
2 passed in <duration>s

设计解释题: 为什么发布门禁必须检查所有三个场景，而不是只检查场景集合非空？请解释只检查非空会导致什么后果，以及如何通过集合差集来确保完整性。

一个有力回答应包含

只检查非空无法发现缺失的必需场景，例如缺少 music 场景的作品集会被错误发布。
使用集合差集 REQUIRED_SCENARIOS - release.scenarios 可以精确找出缺失的场景，从而阻止不完整的发布。
发布门禁的目的是确保作品集包含所有必需的场景和部分，以满足发布契约。

掌握证据

通过测试 test_complete_portfolio_publishes，证明完整作品集能够成功发布。
通过测试 test_missing_music_scenario_blocks_release，证明缺少 music 场景的作品集被阻止并抛出包含 ‘music’ 的 ValueError。
成功实现 forge/portfolio/release.py 中的 PortfolioRelease 数据类和 publish 函数，包含必需集合检查和工件哈希长度验证。

完成本章

发布 HeatStack Forge 1.0 和三套可复现案例。

FORGE / LOCAL CHECK

本地实验自检

未开始
2阅读中
3实验已下载
4测试结果已读取
5本地自检通过

verification.json 只在当前浏览器中解析，不会上传。这里验证的是实验合同，不是服务器认证或第三方背书。

选择 verification.json

主要层

依赖能力

为后续提供

受这些层约束

概念校准

验证与评测

可观测性

贯穿式作品集交付

先看一个具体问题

为什么非空检查挡不住路径逃逸？

先做判断

它是什么

合同验证是完整性与路径限制的组合

它不是什么

合同验证不是只检查非空

它与相邻概念的关系

路径检查与场景、完整性的关系

先看一个具体问题

交付结果缺少必需输出却被接受

先做判断

它是什么

合同覆盖验证

它不是什么

不是非空检查

它与相邻概念的关系

与 ScenarioContract 的关系

先看一个具体问题

为什么相同输入却得到不同清单？

先做判断

它是什么

可复现清单是什么

它不是什么

可复现清单不是什么

它与相邻概念的关系

与其他概念的关系

先看一个具体问题

演示脚本缺少证据路径导致不可验证

先做判断

它是什么

演示验证是完整性检查

它不是什么

演示验证不是内容质量评估

它与相邻概念的关系

演示验证与测试的关系

先看一个具体问题

为什么只有决策 ID 和选择的记录无法通过验证？

先做判断

它是什么

架构决策记录（ADR）的验证是什么？

它不是什么

ADR 验证不是什么？

它与相邻概念的关系

ADR 验证与其他概念的关系

先看一个具体问题

证据索引必须防止同一路径出现冲突哈希

先做判断

它是什么

证据索引是路径到哈希的不可变映射

它不是什么

证据索引不是简单的追加列表

它与相邻概念的关系

索引与证据项、能力分组的关系

先看一个具体问题

发布门禁必须检查所有必需场景和部分

先做判断

它是什么

发布门禁是对照必需集合的完整性检查

它不是什么

发布门禁不是简单的非空检查

它与相邻概念的关系

发布门禁与作品集组件的关系