架构定位

Harness 与治理

用运行环境控制工具、权限、副作用、预算、人工确认、恢复和平台差异。

谁控制权限、运行环境、副作用、平台适配和恢复？

受这些层约束

概念校准

工具

它是什么: Agent 可通过明确参数、权限和结果合同调用的受约束能力。
它不是什么: 工具不等于 MCP；本地函数、命令或 HTTP 客户端也可以是工具。

Harness

它是什么: 承载模型、工具、状态、权限、日志、预算、人工确认和恢复的运行控制环境。
它不是什么: 它能限制风险并保留证据，但不能直接阻止模型产生幻觉。

验证与评测

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

工具系统、沙箱与副作用控制

建立工具注册、Dry-run、变更计划、确认、回滚和审计日志。

本章只做一件事所有写入先生成差异计划，确认后原子执行并可恢复。

开始前，Forge 已经具备已完成 Module 07 的“单 Agent 与工具调用循环”，其通过验收的 solution 是本章起点。

完成后，Forge 将能够修改文件前生成计划、等待确认并保留恢复记录。

卡住时的最小恢复点关闭写工具，只验证计划文件和路径边界。

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

阶段能力链

01为工具声明读取、写入和网络能力，并按最小能力集合查找工具02把工具路径限制在工作区内，并拒绝绝对路径、穿越和符号链接逃逸03在写入前生成不可变变更计划，明确目标、摘要和预期内容哈希04根据副作用风险和批准绑定信息决定是否允许执行05通过同目录临时文件和原子替换避免部分写入06在变更前捕获文件存在性与原内容，并按逆序完整回滚07把路径校验、计划审批、原子写入、回滚和审计组合为安全变更事务

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

概念校准\n\n在开始操作代码前，先把本章涉及的概念放回正确的工程边界。\n\n
\n\n### 工具 tool\n\n- 它是什么: Agent 可通过明确参数、权限、执行边界和结果合同调用的受约束能力，例如函数、命令、数据库查询或 HTTP 客户端。\n- 它不是什么: 工具不等于 MCP，也不等于任意脚本。协议可以暴露能力，但 Harness 仍决定是否允许调用及如何处理副作用。\n- 与相邻概念的关系: Agent Loop 选择工具，Schema 约束参数，Harness 执行权限检查和隔离，Verification 检查结果是否推进目标。\n- 在 HeatStack Forge 中的位置: Forge 的 tool registry 保存合同与风险等级；执行前生成变更计划，高风险写操作等待确认，执行后记录结果与恢复信息。\n- 典型误用与修正: 误用是让模型根据工具名称自由拼参数。修正方法是严格 Schema、确定性校验、超时、幂等键和拒绝分支测试。\n\n### Harness harness\n\n- 它是什么: 承载模型、工具、状态、权限、日志、预算、人工确认、隔离和恢复的运行控制环境。\n- 它不是什么: 它可以缩小风险、拒绝动作并保留证据，但不能保证模型输出永远正确，也不能代替领域验收。\n- 与相邻概念的关系: Agent Loop 在 Harness 中运行；Tool、Memory 和 MCP 连接受其策略约束；Observability 记录过程，Evaluation 判断行为。\n- 在 HeatStack Forge 中的位置: Forge Harness 管理工作目录、工具、确认队列、预算、Checkpoint、审计日志和回滚，把模型建议与真实副作用分开。\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

STAGE 01

为工具声明读取、写入和网络能力，并按最小能力集合查找工具

先看一个具体问题

Harness 在工具调用前如何知道工具可能产生哪些副作用

在 Module 07 的单 Agent 循环中，工具调用是直接执行的，Harness 无法在调用前判断某个工具是否会写入文件或发起网络请求，这导致任何工具都可能产生未受控的副作用。

本阶段需要创建 forge/tools/registry.py，引入 ToolDescriptor 和 ToolRegistry 两个符号，让每个工具在注册时声明自己的能力集合，Harness 据此在调用前进行权限判断。

当前测试文件 tests/test_stage.py 尝试从 forge.tools.registry 导入 ToolDescriptor 和 ToolRegistry，但由于 forge/tools 包尚不存在，收集阶段直接抛出 ModuleNotFoundError: No module named 'forge.tools'，退出码为 2。

先做判断

当 ToolDescriptor("shell", frozenset({"root"})) 被构造时，__post_init__ 中的 unknown = set(self.capabilities) - set(ALLOWED_CAPABILITIES) 计算结果是什么，接下来会发生什么？

unknown 为空集合，构造成功
unknown 为 {‘root’}，抛出 ValueError
unknown 为 {‘read’, ‘write’}，抛出 ValueError
unknown 为 {‘root’}，构造成功

判断依据: ALLOWED_CAPABILITIES 包含 read、write、network、process 四个成员，不包含 root，因此差集结果为 {‘root’}，非空集合触发 ValueError。选择第二项。

它是什么

工具能力声明是 Harness 权限决策的依据

ToolDescriptor 是一个冻结数据类，包含 name 和 capabilities 两个字段，capabilities 是 frozenset[str] 类型，表示该工具可能产生的副作用类别。

ALLOWED_CAPABILITIES 是一个模块级 frozenset，包含 read、write、network、process 四个成员，构成 Harness 的策略词汇表，所有工具声明的能力必须是其子集。

ToolRegistry 维护一个 dict[str, ToolDescriptor]，提供 register 方法注册工具并在重名时抛出 ValueError，提供 supporting 方法按所需能力集合筛选工具。

它不是什么

工具能力声明不等于任意脚本或 MCP 协议

工具不是任意脚本，它必须通过 ToolDescriptor 显式声明能力，未在 ALLOWED_CAPABILITIES 中的能力会在构造阶段被拒绝，而不是等到运行时才发现。

工具也不等于 MCP，协议可以暴露能力，但 Harness 仍依据 ToolDescriptor.capabilities 决定是否允许调用，协议本身不构成权限依据。

能力声明不代替领域验收，它只告诉 Harness 某个工具可能产生哪类副作用，具体调用结果是否正确仍需 Verification 检查。

它与相邻概念的关系

能力词汇表、描述符与注册表的因果链

ALLOWED_CAPABILITIES 约束 ToolDescriptor 的合法能力集合，ToolDescriptor.__post_init__ 在构造时计算 set(self.capabilities) - set(ALLOWED_CAPABILITIES)，若结果非空则抛出 ValueError，这确保注册到 ToolRegistry 中的工具不会携带未声明的能力。

ToolRegistry.supporting 接收一个 required 集合，通过 required <= set(tool.capabilities) 判断已注册工具的能力是否为所需集合的超集，仅返回满足全部能力要求的工具。

Agent Loop 选择工具时，先向 ToolRegistry 查询 supporting(required)，Harness 再根据返回的描述符执行权限检查和隔离，Observability 记录整个过程。

本阶段的边界决定: 能力声明在构造阶段强制校验，注册阶段强制去重，查询阶段按子集关系筛选；Harness 不会执行任何携带未声明能力的工具，也不会在运行时动态扩展 ALLOWED_CAPABILITIES。

实验 ID: tools-sandbox-side-effects-01-capability-registry
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/tools-sandbox-side-effects/01-capability-registry/
验收: 待验收

教师示范

目标: 在软件场景中注册 reader 和 editor 两个工具，调用 registry.supporting({“read”, “write”}) 验证仅返回 editor。

首先创建 forge/tools/__init__.py，从 .registry 模块导入 ToolDescriptor 和 ToolRegistry，使 from forge.tools.registry import ToolDescriptor, ToolRegistry 能够被测试文件正确导入。

然后创建 forge/tools/registry.py，定义 ALLOWED_CAPABILITIES、ToolDescriptor 和 ToolRegistry，其中 ToolDescriptor.__post_init__ 负责校验能力合法性，ToolRegistry.supporting 负责按子集关系筛选工具。

在软件场景中，reader 声明 frozenset({"read"})，editor 声明 frozenset({"read", "write"})，当查询 supporting({"read", "write"}) 时，只有 editor 的能力集是 {"read", "write"} 的超集，因此仅返回 editor。

实施步骤

创建 forge/tools/__init__.py，内容为 from .registry import ToolDescriptor, ToolRegistry 和 __all__ = ["ToolDescriptor", "ToolRegistry"]
创建 forge/tools/registry.py，定义 ALLOWED_CAPABILITIES = frozenset({"read", "write", "network", "process"})
定义 @dataclass(frozen=True) class ToolDescriptor，包含 name: str 和 capabilities: frozenset[str]，在 __post_init__ 中计算 unknown = set(self.capabilities) - set(ALLOWED_CAPABILITIES)，当 not self.name.strip() or unknown 时抛出 ValueError("invalid tool descriptor")
定义 @dataclass class ToolRegistry，包含 _tools: dict[str, ToolDescriptor]，register 方法在重名时抛出 ValueError("tool already registered")，supporting 方法返回 sorted((tool for tool in self._tools.values() if required <= set(tool.capabilities)), key=lambda tool: tool.name)

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

from .registry import ToolDescriptor, ToolRegistry

__all__ = ["ToolDescriptor", "ToolRegistry"]

真实 solution 代码: forge/tools/registry.py

from __future__ import annotations

from dataclasses import dataclass, field

ALLOWED_CAPABILITIES = frozenset({"read", "write", "network", "process"})

@dataclass(frozen=True)
class ToolDescriptor:
    name: str
    capabilities: frozenset[str]

    def __post_init__(self) -> None:
        unknown = set(self.capabilities) - set(ALLOWED_CAPABILITIES)
        if not self.name.strip() or unknown:
            raise ValueError("invalid tool descriptor")

@dataclass
class ToolRegistry:
    _tools: dict[str, ToolDescriptor] = field(default_factory=dict)

    def register(self, descriptor: ToolDescriptor) -> None:
        if descriptor.name in self._tools:
            raise ValueError("tool already registered")
        self._tools[descriptor.name] = descriptor

    def supporting(self, required: set[str]) -> list[ToolDescriptor]:
        return sorted((tool for tool in self._tools.values() if required <= set(tool.capabilities)), key=lambda tool: tool.name)

python -m pytest -q tests/test_stage.py

运行真实测试

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

为什么这样实现

supporting 方法中的 required <= set(tool.capabilities) 使用集合的子集关系运算符 <=，判断 required 中的每个能力是否都存在于 tool 的能力集中，只有全部满足时才返回该工具。

reader 的能力集是 {"read"}，不包含 write，因此 {"read", "write"} <= {"read"} 为 False，被过滤掉；editor 的能力集是 {"read", "write"}，{"read", "write"} <= {"read", "write"} 为 True，被返回。

带提示练习

解释 ToolDescriptor("shell", frozenset({"root"})) 构造时 __post_init__ 中 unknown 集合的计算过程，并理解为何触发 ValueError。

查看 ALLOWED_CAPABILITIES 的定义，确认其成员为 read、write、network、process，不包含 root
在 __post_init__ 中，unknown = set(self.capabilities) - set(ALLOWED_CAPABILITIES) 将 {"root"} 减去 {"read", "write", "network", "process"}，结果为 {'root'}
条件 not self.name.strip() or unknown 中，unknown 为 {'root'} 是非空集合，在布尔上下文中为 True，因此抛出 ValueError("invalid tool descriptor")
确认测试 test_unknown_capability_is_rejected 使用 pytest.raises(ValueError, match="invalid") 捕获该异常并匹配错误消息

逐级提示

set(self.capabilities) 将 frozenset 转为普通 set，- 运算符计算差集，即 self.capabilities 中存在但 ALLOWED_CAPABILITIES 中不存在的元素
Python 中非空集合在布尔上下文中为 True，空集合为 False，or 运算符在左侧为 False 时会评估右侧
pytest.raises(ValueError, match="invalid") 中的 match 参数使用 re.search 在异常消息中搜索子串 invalid，因此错误消息必须包含该子串

完成标准

ToolDescriptor("shell", frozenset({"root"})) 必须抛出 ValueError，且消息包含 invalid
ToolDescriptor("reader", frozenset({"read"})) 必须构造成功，不抛出异常

故障注入与排查

故障实验室提供的 faulty/ 树中，forge/tools/registry.py 的 ToolDescriptor.__post_init__ 方法里 unknown 被赋值为 set() 而非 set(self.capabilities) - set(ALLOWED_CAPABILITIES)，导致能力校验逻辑被丢弃。运行 python -m pytest -q ../tests/test_stage.py::test_unknown_capability_is_rejected 时，测试期望构造 ToolDescriptor("shell", frozenset({"root"})) 抛出 ValueError，但实际未抛出，测试失败并报告 DID NOT RAISE ValueError。

本阶段引入的 ALLOWED_CAPABILITIES 词汇表和 ToolDescriptor.__post_init__ 校验逻辑正是解决此缺陷的机制。修复方法是将 unknown 的赋值从 set() 改为 set(self.capabilities) - set(ALLOWED_CAPABILITIES)，这样当 capabilities 包含 root 时，差集结果为 {'root'}，非空集合触发 ValueError，测试通过。

已验证的故障合同

目标测试: test_unknown_capability_is_rejected
故障文件: forge/tools/registry.py

诊断顺序

打开 forge/tools/registry.py，定位到 ToolDescriptor.__post_init__ 方法，查看 unknown 变量的赋值表达式
发现 unknown = set() 是一个空集合字面量，没有引用 self.capabilities 或 ALLOWED_CAPABILITIES，因此差集计算被完全跳过
追踪条件判断 if not self.name.strip() or unknown:，由于 unknown 恒为空集合，布尔值为 False，只有 name 为空时才会抛出异常
构造 ToolDescriptor("shell", frozenset({"root"})) 时，name 为 "shell" 非空，unknown 为空集合，条件为 False，不抛出异常，与测试期望矛盾

修复原则: 将 forge/tools/registry.py 中 ToolDescriptor.__post_init__ 的 unknown = set() 修改为 unknown = set(self.capabilities) - set(ALLOWED_CAPABILITIES)，使差集计算实际比较工具声明的能力与策略词汇表，当存在未声明能力时 unknown 非空，触发 ValueError("invalid tool descriptor")。

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

迁移挑战

在办公研究场景中，需要一个从网络获取文档并读取内容的工具，其能力集为 frozenset({"network", "read"})。

改变的条件: 将场景从软件交付切换到办公研究，注册一个能力集为 network 和 read 的 web_fetcher 工具，而非 read 和 write 的 editor 工具。

使用 ToolDescriptor 构造一个名为 web_fetcher 的工具描述符，能力集为 frozenset({"network", "read"})，将其注册到 ToolRegistry 中，然后调用 registry.supporting({"network"}) 验证 web_fetcher 被返回。不修改 ALLOWED_CAPABILITIES 的成员。

完成标准

构造 ToolDescriptor("web_fetcher", frozenset({"network", "read"})) 不抛出异常，因为 network 和 read 均在 ALLOWED_CAPABILITIES 中
调用 registry.supporting({"network"}) 返回的列表中包含 web_fetcher，因为 {"network"} <= {"network", "read"} 为 True

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

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

设计解释题: 为什么 ALLOWED_CAPABILITIES 使用 frozenset 而不是 list？如果改用 list，__post_init__ 中的差集运算和 supporting 中的子集判断会产生什么语义差异或性能影响？

一个有力回答应包含

frozenset 是不可变的，保证模块加载后能力词汇表不会被运行时修改，避免工具动态注入未声明能力
frozenset 的成员查找和差集运算是基于哈希表的 O(1) 和 O(n) 操作，而 list 的 in 运算是 O(n)，在能力数量较大时性能更差
set(self.capabilities) - set(ALLOWED_CAPABILITIES) 依赖集合差集语义，若 ALLOWED_CAPABILITIES 是 list 需要先转为 set，否则 - 运算符对 list 无效
required <= set(tool.capabilities) 使用集合子集关系，frozenset 和 set 都支持 <= 运算符，list 不支持

掌握证据

test_registry_returns_only_tools_with_all_required_capabilities 通过，验证 supporting({"read", "write"}) 仅返回 editor 而非 reader
test_unknown_capability_is_rejected 通过，验证 ToolDescriptor("shell", frozenset({"root"})) 抛出 ValueError 且消息包含 invalid
test_duplicate_registration_is_rejected 通过，验证重复注册同名工具时抛出 ValueError 且消息包含 already
python -m pytest -q tests/test_stage.py 退出码为 0，三个测试全部通过

STAGE 02

把工具路径限制在工作区内，并拒绝绝对路径、穿越和符号链接逃逸

先看一个具体问题

字符串拼接无法阻止路径穿越

在软件交付场景中，Agent 需要修改前端仓库内的文件，工具系统接收一个相对路径并将其拼接到工作区根目录上。如果仅做词法拼接而不进行规范化解析，攻击者可以传入 ../secret.txt 这样的路径，使最终路径指向工作区之外的文件。

当前测试套件在 tests/test_stage.py 中定义了三个测试：test_relative_path_resolves_inside_workspace、test_parent_traversal_is_rejected 和 test_symlink_escape_is_rejected。由于 forge/tools/paths.py 尚不存在，测试在收集阶段就因 ModuleNotFoundError 而中断，退出码为 2。

学习者需要创建 forge/tools/paths.py 文件，实现 resolve_workspace_path 函数，使其在路径合法时返回工作区内已规范化的绝对路径，在路径穿越或符号链接逃逸时抛出包含 escapes 的 ValueError。

先做判断

当 workspace 为 /tmp/repo 且 requested 为 ../secret.txt 时，执行 resolved = workspace / Path(requested) 后再调用 resolved.relative_to(workspace) 会发生什么？

抛出 ValueError，因为 ../secret.txt 不以 workspace 为前缀
不抛出异常，因为词法拼接后的路径字符串仍以 workspace 开头
抛出 FileNotFoundError，因为文件不存在
返回 /tmp/secret.txt 且不报错

判断依据: 词法拼接 workspace / Path(“../secret.txt”) 得到的是 /tmp/repo/../secret.txt，这个字符串仍然以 /tmp/repo 开头，所以 relative_to(workspace) 不会抛异常。只有先调用 .resolve() 将 .. 消解为规范路径后，路径才会变成 /tmp/secret.txt，此时 relative_to 才能检测到逃逸。

它是什么

路径规范化解析的含义

路径规范化解析是指通过 pathlib.Path.resolve() 方法将路径中的 . 和 .. 段消解为真实的绝对路径，同时解析沿途的符号链接指向。只有经过 resolve 后的路径才代表文件系统上的真实位置，才能可靠地判断它是否落在工作区范围内。

resolve_workspace_path 函数的核心策略是：先拒绝绝对路径输入，再将工作区根目录与候选路径拼接，然后对拼接结果调用 resolve(strict=False) 得到规范路径，最后用 relative_to 检查规范路径是否仍在工作区内。

它不是什么

词法前缀匹配不是安全检查

仅检查路径字符串是否以工作区前缀开头不是有效的安全措施，因为 ../secret.txt 拼接后仍以工作区前缀开头但实际指向外部文件。词法匹配无法理解 .. 的语义，也无法发现符号链接指向工作区之外的目标。

resolve(strict=True) 在此场景中也不合适，因为目标文件可能尚未创建，strict=True 会在文件不存在时抛出 FileNotFoundError，而路径安全检查的目的是在文件访问之前就拒绝非法路径。

它与相邻概念的关系

resolve 与 relative_to 的协作关系

resolve 将路径转换为规范形式，消除 .. 和符号链接的歧义；relative_to 则在规范路径上做严格的包含关系判断。两者必须配合使用：先 resolve 再 relative_to，顺序不能颠倒也不能省略 resolve。

workspace 根目录本身也需要先调用 resolve() 进行规范化，否则当 workspace 包含符号链接时，即使候选路径合法，relative_to 也可能因前缀不匹配而误判。

本阶段的边界决定: 路径安全检查的边界在于：resolve(strict=False) 负责消解路径语义但不要求文件存在，relative_to 负责在规范路径上做包含判断，两者缺一不可；绝对路径在进入拼接之前就应被拒绝。

实验 ID: tools-sandbox-side-effects-02-workspace-path-policy
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/tools-sandbox-side-effects/02-workspace-path-policy/
验收: 待验收

教师示范

目标: 在软件场景中验证 resolve_workspace_path(tmp_path, “src/app.py”) 返回 tmp_path / “src” / “app.py”，并验证 resolve_workspace_path(tmp_path, “../secret.txt”) 抛出包含 escapes 的 ValueError。

首先创建 forge/tools/paths.py 文件，定义 resolve_workspace_path 函数。函数开头检查 requested 是否为空字符串，若为空则抛出 ValueError(“path is required”)。

接着将 requested 转为 Path 对象，调用 is_absolute() 检查是否为绝对路径，若是则抛出 ValueError(“absolute paths are forbidden”)。这一步在 resolve 之前执行，防止攻击者用绝对路径绕过工作区限制。

然后将 workspace.resolve() 作为根目录 root，将 root / candidate 拼接后调用 .resolve(strict=False) 得到规范路径 resolved。最后用 resolved.relative_to(root) 检查包含关系，若不包含则抛出 ValueError(“path escapes workspace”)。

实施步骤

创建 forge/tools/paths.py 文件并导入 from pathlib import Path
实现空路径检查和绝对路径拒绝逻辑
实现 root / candidate 拼接后调用 resolve(strict=False) 的规范化逻辑
用 relative_to(root) 做包含检查，失败时抛出包含 escapes 的 ValueError

真实 solution 代码: forge/tools/paths.py

from __future__ import annotations

from pathlib import Path

def resolve_workspace_path(workspace: Path, requested: str) -> Path:
    if not requested.strip():
        raise ValueError("path is required")
    candidate = Path(requested)
    if candidate.is_absolute():
        raise ValueError("absolute paths are forbidden")
    root = workspace.resolve()
    resolved = (root / candidate).resolve(strict=False)
    try:
        resolved.relative_to(root)
    except ValueError as error:
        raise ValueError("path escapes workspace") from error
    return resolved

python -m pytest -q tests/test_stage.py

运行真实测试

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

为什么这样实现

resolve(strict=False) 将 /tmp/repo/../secret.txt 消解为 /tmp/secret.txt，此时 relative_to(/tmp/repo) 因为 /tmp/secret.txt 不在 /tmp/repo 之下而抛出 ValueError，被捕获后重新抛出为 path escapes workspace。

对于合法路径 src/app.py，resolve(strict=False) 得到 /tmp/repo/src/app.py，relative_to(/tmp/repo) 返回 src/app.py 不抛异常，函数正常返回规范路径。

带提示练习

解释 faultySource 中 resolved = root / candidate 为何未触发 ValueError，并补全缺失的 .resolve(strict=False) 调用使 relative_to 检查生效。

阅读 faultySource 代码，注意 resolved = root / candidate 这一行缺少 resolve 调用
分析当 candidate 为 ../secret.txt 时，root / candidate 的词法结果仍以 root 开头，relative_to 不会抛异常
将 resolved = root / candidate 改为 resolved = (root / candidate).resolve(strict=False)
运行测试验证 test_parent_traversal_is_rejected 和 test_symlink_escape_is_rejected 均通过

逐级提示

root / Path(“../secret.txt”) 的字符串表示是 root/../secret.txt，它仍然以 root 开头
relative_to 做的是精确的路径段比较，不会自动消解 .. 段
只有 resolve() 才能把 .. 消解为真实的父目录路径
符号链接也需要 resolve 来解析其指向的真实目标目录

完成标准

resolved 变量的赋值包含 .resolve(strict=False) 调用
test_parent_traversal_is_rejected 测试通过，即 ../secret.txt 被正确拒绝
test_symlink_escape_is_rejected 测试通过，即符号链接逃逸被正确拒绝

故障注入与排查

faultySource 中的 resolve_workspace_path 函数在 forge/tools/paths.py 中定义，但 resolved = root / candidate 缺少 .resolve(strict=False) 调用。运行 test_parent_traversal_is_rejected 测试时，传入 ../secret.txt 的路径没有被拒绝，测试期望 ValueError 但实际未抛出，测试失败并报告 DID NOT RAISE ValueError。

本阶段教授的路径规范化机制正是修复此缺陷的关键：在 relative_to 检查之前调用 resolve(strict=False) 可以将 ../secret.txt 消解为工作区外的真实路径，从而使 relative_to 正确检测到逃逸。test_symlink_escape_is_rejected 也依赖同一机制来解析符号链接指向的真实目标。

已验证的故障合同

目标测试: test_parent_traversal_is_rejected
故障文件: forge/tools/paths.py

诊断顺序

运行 python -m pytest -q ../tests/test_stage.py::test_parent_traversal_is_rejected，观察输出为 FAILED 且消息为 DID NOT RAISE ValueError
检查 forge/tools/paths.py 中 resolved 的赋值行，确认缺少 .resolve(strict=False) 调用
在 Python 交互环境中执行 Path(‘/tmp/repo/../secret.txt’).relative_to(Path(‘/tmp/repo’)) 确认它不抛异常，而 Path(‘/tmp/repo/../secret.txt’).resolve().relative_to(Path(‘/tmp/repo’)) 才会抛 ValueError

修复原则: 将 forge/tools/paths.py 中的 resolved = root / candidate 修改为 resolved = (root / candidate).resolve(strict=False)。这样 ../secret.txt 会被消解为工作区外的路径，relative_to(root) 随即抛出 ValueError，被捕获后重新抛出为 path escapes workspace。符号链接也会被 resolve 解析到真实目标目录，同样触发逃逸检测。

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

迁移挑战

在音乐创作场景中，Agent 需要整理曲目元数据文件，工具系统接收路径 tracks/metadata.json 并将其限制在工作区内。

改变的条件: 将路径数据从软件场景的 src/app.py 改为音乐场景的 tracks/metadata.json

调用 resolve_workspace_path(tmp_path, “tracks/metadata.json”)，验证返回值等于 tmp_path / “tracks” / “metadata.json”。使用同一个 resolve_workspace_path 函数，仅将路径参数从 src/app.py 替换为 tracks/metadata.json，不修改函数实现或测试结构。

完成标准

resolve_workspace_path(tmp_path, “tracks/metadata.json”) 的返回值等于 tmp_path / “tracks” / “metadata.json”，确认合法相对路径仍被正确接受
resolve_workspace_path(tmp_path, “../tracks/metadata.json”) 仍抛出包含 escapes 的 ValueError，确认穿越路径在更换场景数据后仍被拒绝

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

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

设计解释题: 为什么在 resolve_workspace_path 中使用 resolve(strict=False) 而不是 strict=True？如果改用 strict=True 会对哪些合法但文件尚未创建的路径产生什么影响？

一个有力回答应包含

strict=False 允许路径指向尚不存在的文件，因为路径安全检查的目的是在文件访问前拒绝非法路径，而非验证文件是否存在
strict=True 在文件不存在时会抛出 FileNotFoundError，这会使原本合法的新文件创建请求被误判为路径错误
resolve(strict=False) 仍然会消解 .. 和符号链接，因此安全检查不受影响，只是不要求路径指向的文件已存在

掌握证据

test_relative_path_resolves_inside_workspace 通过，确认 resolve_workspace_path(tmp_path, "src/app.py") 返回 tmp_path / "src" / "app.py"
test_parent_traversal_is_rejected 通过，确认 ../secret.txt 被正确拒绝并抛出包含 escapes 的 ValueError
test_symlink_escape_is_rejected 通过，确认符号链接逃逸被 resolve(strict=False) 解析后正确拒绝
python -m pytest -q tests/test_stage.py 退出码为 0，三个测试全部通过

STAGE 03

在写入前生成不可变变更计划，明确目标、摘要和预期内容哈希

先看一个具体问题

写入前必须生成绑定字节内容的变更计划

当前代码库中不存在 forge/tools/plans.py 文件，因此测试在收集阶段抛出 ModuleNotFoundError，无法导入 build_change_plan 符号。学习者需要从零创建该文件，定义 PlannedWrite 与 ChangePlan 两个不可变数据类，并实现 build_change_plan 函数。

该函数的核心职责是在任何文件写入操作发生之前，将人类可读的摘要与待写入的字节内容分离，并对字节内容计算 SHA-256 哈希。如果错误地对摘要字符串计算哈希，审批环节将绑定到人类可读的描述文本而非实际写入的字节，从而导致内容替换攻击成为可能。

先做判断

在 faultySource 中，build_change_plan 使用 sha256(summary.encode(“utf8”)).hexdigest() 计算哈希。当测试断言 plan.writes[0].content_sha256 == sha256(b“A”).hexdigest() 时，结果会怎样？

断言失败，因为对摘要字符串 ‘write a’ 计算哈希的结果不等于对字节 b“A” 计算哈希的结果
断言通过，因为摘要和内容在概念上可以互换
抛出 TypeError，因为 summary 是字符串而 content 是 bytes
断言失败，因为排序导致路径顺序错误

判断依据: 正确答案是第一个。SHA-256 对不同输入产生不同输出，对字符串 ‘write a’ 编码后的哈希值必然不等于对单字节 b’A’ 计算的哈希值。这揭示了将人类可读元数据误认为副作用载荷的根本错误。

它是什么

变更计划是不可变的内容绑定契约

ChangePlan 是一个 frozen dataclass，它在写入操作执行之前捕获操作标识符和所有待写入文件的路径、摘要及内容哈希。一旦构造完成，其字段不可修改，这保证了审批阶段看到的计划与执行阶段使用的计划是同一份不可变记录。

content_sha256 字段必须由待写入的 bytes 直接计算得出，而非由 summary 字符串编码后计算。这意味着审批者通过验证哈希就能确认将要写入磁盘的确切字节内容，从而在审批与执行之间建立起密码学绑定。

它不是什么

摘要文本不能替代字节内容作为审批依据

summary 字段是人类可读的描述，例如 ‘write a’ 或 ‘write b’，它的作用是帮助操作者理解写入意图，但它的编码结果与实际文件字节毫无关联。两个完全不同的文件内容可以共享相同的摘要文本，因此对摘要计算哈希无法唯一标识写入载荷。

ChangePlan 也不是一个通用的键值存储或配置文件。它专门服务于副作用控制流程，其 writes 字段是一个有序的 PlannedWrite 元组，排序依据是 relative_path，这确保了同一组写入无论字典插入顺序如何，生成的计划始终一致。

它与相邻概念的关系

计划与 Harness 审批及验证的因果链

Harness 在执行文件写入前要求生成 ChangePlan，审批环节绑定到 plan 中的 content_sha256，执行环节再次计算实际写入字节的哈希并与计划中的哈希比对。如果两者不匹配，Harness 可以拒绝执行，从而防止审批后内容被替换。

Verification 依赖 ChangePlan 的不可变性来检查结果是否推进目标。测试 test_plan_hash_changes_when_content_changes 验证了当 content 从 b“A” 变为 b“B” 时，content_sha256 必须不同，这确保了哈希对内容变化的敏感性。

本阶段的边界决定: content_sha256 必须由待写入的 bytes 计算得出，绝不能由 summary 字符串编码计算；计划构造后不可变，writes 按 relative_path 排序以保证稳定性。

实验 ID: tools-sandbox-side-effects-03-dry-run-change-plan
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/tools-sandbox-side-effects/03-dry-run-change-plan/
验收: 待验收

教师示范

目标: 在软件场景中调用 build_change_plan(“op-1”, {“b.txt”: (“write b”, b“B”), “a.txt”: (“write a”, b“A”)})，验证 writes 按 relative_path 排序且 content_sha256 绑定字节内容。

测试 test_plan_is_stable_and_contains_content_hashes 传入一个无序字典，其中 b.txt 在 a.txt 之前插入。build_change_plan 必须使用 sorted(writes.items()) 对键进行排序，使输出的 writes 元组顺序为 [“a.txt”, “b.txt”]，这保证了同一组写入无论字典构造顺序如何都生成相同的计划。

排序后，函数对每个条目构造 PlannedWrite，其中 content_sha256 通过 sha256(content).hexdigest() 计算。对于 a.txt，content 是 b“A”，因此 content_sha256 等于 sha256(b“A”).hexdigest()，即 559aead08264d5795d3909718cdd05abd49572e84fe55590eef31a88a08fdffd。测试断言此值精确匹配。

实施步骤

定义 frozen dataclass PlannedWrite，包含 relative_path: str、summary: str、content_sha256: str 三个字段
定义 frozen dataclass ChangePlan，包含 operation_id: str 和 writes: tuple[PlannedWrite, …]
实现 build_change_plan，先校验 operation_id 和 writes 非空，再对 writes.items() 排序，最后用 sha256(content).hexdigest() 构造每个 PlannedWrite

真实 solution 代码: forge/tools/plans.py

from __future__ import annotations

from dataclasses import dataclass
from hashlib import sha256

@dataclass(frozen=True)
class PlannedWrite:
    relative_path: str
    summary: str
    content_sha256: str

@dataclass(frozen=True)
class ChangePlan:
    operation_id: str
    writes: tuple[PlannedWrite, ...]

def build_change_plan(operation_id: str, writes: dict[str, tuple[str, bytes]]) -> ChangePlan:
    if not operation_id.strip() or not writes:
        raise ValueError("operation id and writes are required")
    planned = tuple(PlannedWrite(path, summary, sha256(content).hexdigest()) for path, (summary, content) in sorted(writes.items()))
    if len({item.relative_path for item in planned}) != len(planned):
        raise ValueError("duplicate target path")
    return ChangePlan(operation_id, planned)

python -m pytest -q tests/test_stage.py

运行真实测试

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

为什么这样实现

排序步骤确保了计划的稳定性：无论调用者以何种顺序构造 writes 字典，sorted(writes.items()) 都按 relative_path 的字典序输出，因此 plan.writes 的路径列表始终为 [“a.txt”, “b.txt”]。

哈希步骤确保了内容绑定：sha256(content).hexdigest() 直接作用于待写入的 bytes 对象，而非 summary 字符串。这意味着如果有人在审批后偷偷将 content 从 b“A” 替换为 b“B”，执行时的哈希验证将立即失败。

带提示练习

解释 faultySource 中 sha256(summary.encode(“utf8”)) 为何产生错误哈希，并补全正确的 sha256(content).hexdigest() 调用，同时实现空写入拒绝逻辑。

阅读 faultySource 中 build_change_plan 的 PlannedWrite 构造表达式，定位 sha256 的输入参数
将 sha256(summary.encode(“utf8”)).hexdigest() 修改为 sha256(content).hexdigest()，使哈希绑定到待写入的字节内容
确认 if not operation_id.strip() or not writes: raise ValueError(…) 分支存在，使空字典输入抛出 ValueError

逐级提示

summary 是字符串 ‘write a’，content 是 bytes b’A’，对两者分别计算 SHA-256 会得到完全不同的结果
查看测试 test_empty_plan_is_rejected，它期望传入空字典 {} 时抛出 ValueError，因此需要检查 writes 的真值
sorted(writes.items()) 返回的是按路径排序后的列表，每个元素是 (path, (summary, content)) 元组

完成标准

build_change_plan 中 content_sha256 由 sha256(content).hexdigest() 计算而非 sha256(summary.encode(“utf8”)).hexdigest()
传入空字典 {} 时抛出 ValueError 异常
writes 元组按 relative_path 字典序排列

故障注入与排查

faultySource 中的 forge/tools/plans.py 文件已存在且包含完整的 PlannedWrite、ChangePlan 和 build_change_plan 定义，但 build_change_plan 在构造 PlannedWrite 时使用 sha256(summary.encode(“utf8”)).hexdigest() 而非 sha256(content).hexdigest()。运行 test_plan_is_stable_and_contains_content_hashes 时，断言 plan.writes[0].content_sha256 == sha256(b“A”).hexdigest() 失败，因为实际计算的是 sha256(b“write a”).hexdigest()。

本阶段教授的内容哈希绑定机制直接针对此缺陷：学习者通过 workedExample 理解了 content_sha256 必须由 bytes 计算，通过 guidedPractice 识别了 summary 与 content 的区别。修复方法是将 faultySource 中的 sha256(summary.encode(“utf8”)).hexdigest() 替换为 sha256(content).hexdigest()，使 test_plan_is_stable_and_contains_content_hashes 断言通过。

已验证的故障合同

目标测试: test_plan_is_stable_and_contains_content_hashes
故障文件: forge/tools/plans.py

诊断顺序

运行 python -m pytest -q ../tests/test_stage.py::test_plan_is_stable_and_contains_content_hashes，观察 AssertionError 显示期望值 559aead… 与实际值 71a93b9… 不匹配
在 forge/tools/plans.py 中定位 build_change_plan 函数的 PlannedWrite 构造表达式，检查 sha256 的输入参数
确认 sha256(summary.encode(“utf8”)).hexdigest() 对字符串 ‘write a’ 计算哈希，而测试期望的是对 bytes b’A’ 计算哈希

修复原则: 将 forge/tools/plans.py 中 build_change_plan 函数内的 sha256(summary.encode(“utf8”)).hexdigest() 替换为 sha256(content).hexdigest()。此修改使 content_sha256 直接绑定到待写入的字节内容，test_plan_is_stable_and_contains_content_hashes 断言 plan.writes[0].content_sha256 == sha256(b“A”).hexdigest() 将通过。

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

迁移挑战

办公研究场景：需要生成一份 Q3 决策简报的变更计划，目标文件为 report/draft.md，内容为 b“# Q3 Brief“。

改变的条件: 将写入目标从软件场景的 a.txt/b.txt 替换为办公场景的 report/draft.md，同时替换待写入的字节内容为 b“# Q3 Brief“

调用 build_change_plan(“brief-op”, {“report/draft.md”: (“write draft”, b“# Q3 Brief“)})，验证 plan.writes[0].content_sha256 == sha256(b“# Q3 Brief“).hexdigest()。使用与软件场景相同的 build_change_plan 公共 API，仅将字典键从 a.txt/b.txt 替换为 report/draft.md，将字节内容从 b“A”/b“B” 替换为 b“# Q3 Brief“。

完成标准

plan.writes[0].relative_path == “report/draft.md” 且 plan.writes 仅包含一个条目，验证办公场景中写入目标已从软件场景的 a.txt/b.txt 替换为 report/draft.md。
plan.writes[0].content_sha256 == sha256(b“# Q3 Brief“).hexdigest()，验证哈希值由待写入的字节内容 b“# Q3 Brief“ 直接计算得出，而非由摘要字符串计算。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

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

设计解释题: 为什么 writes 字典在排序后才生成 planned 元组，而不是直接按字典插入顺序构造？这与计划的不可变性和审批一致性有什么因果关系？

一个有力回答应包含

字典在 Python 3.7+ 中保持插入顺序，但调用者可能以任意顺序构造字典，排序确保同一组写入始终生成相同的 ChangePlan
如果按插入顺序构造，两次调用传入相同内容但顺序不同的字典会生成不同的计划，破坏审批一致性
排序发生在构造 PlannedWrite 之前，因此 content_sha256 绑定的是排序后确定路径对应的字节内容，审批者看到的计划顺序与执行顺序一致

掌握证据

test_plan_is_stable_and_contains_content_hashes 通过，验证 plan.writes 按 relative_path 排序为 ["a.txt", "b.txt"] 且 content_sha256 等于 sha256(b"A").hexdigest()
test_empty_plan_is_rejected 通过，验证传入空字典 {} 时 build_change_plan 抛出 ValueError
test_plan_hash_changes_when_content_changes 通过，验证 content 从 b"A" 变为 b"B" 时 content_sha256 不同
python -m pytest -q tests/test_stage.py 退出码为 0，三个测试全部通过

STAGE 04

根据副作用风险和批准绑定信息决定是否允许执行

先看一个具体问题

旧审批通过新计划：缺少 plan_digest 绑定的副作用风险

在软件交付场景中，Agent 在修改前端仓库前需要生成 ChangePlan 并等待人工审批。当前 forge/tools/approval.py 文件不存在，测试在导入 Approval 与 ApprovalGate 时直接抛出 ModuleNotFoundError，导致 tests/test_stage.py 全部收集失败。

即使后续创建了文件，如果 authorize 方法仅检查 approval.operation_id == operation_id，那么针对旧计划摘要 old 的审批仍能授权新计划摘要 new 的写入操作。这意味着攻击者或过时流程可以在计划内容已被替换后，复用同一操作标识的审批令牌执行未经验证的新写入。

本阶段要求你创建 forge/tools/approval.py，定义 Approval 数据类与 ApprovalGate 类，使 authorize 方法根据风险等级、操作标识和计划摘要三者共同决定是否允许执行，从而堵住旧审批授权新内容的漏洞。

先做判断

当 risk="reversible_write" 且 approval=Approval("op", "old")，而当前 plan_digest="new" 时，仅检查 operation_id 的 authorize 方法会返回什么？

返回 False，因为 plan_digest 不匹配
返回 True，因为 operation_id 匹配而 plan_digest 被忽略
抛出 ValueError，因为风险等级未知
返回 None，因为 approval 不完整

判断依据: 正确答案是返回 True。因为 faultySource 中的 return approval.operation_id == operation_id 只比较操作标识，完全忽略了 plan_digest 字段，所以旧审批会错误地授权新计划。这正说明必须同时校验 approval.plan_digest == plan_digest。

它是什么

ApprovalGate 的审批绑定模型

ApprovalGate.authorize 是一个纯决策函数，接收风险等级 risk、操作标识 operation_id、当前计划摘要 plan_digest 以及可选的 Approval 对象，返回布尔值或抛出异常。它不执行任何写入，只判断当前调用是否被允许进入执行阶段。

Approval 是一个冻结数据类，包含 operation_id 和 plan_digest 两个字段，代表人工审批时绑定的操作与计划内容快照。审批对象一旦创建就不可变，确保审批令牌不会被篡改以匹配不同的计划。

风险等级分为三类：read 无副作用无需审批；reversible_write 和 irreversible 有副作用，必须提供 Approval 且其 operation_id 与 plan_digest 同时匹配当前调用参数；未知风险等级直接抛出 ValueError。

它不是什么

ApprovalGate 不是执行器也不是权限缓存

ApprovalGate 不负责执行写入操作或修改文件系统状态，它只做授权判断。实际执行由 Harness 中的其他组件完成，ApprovalGate 的返回值仅作为执行前的门控信号。

它不是对模型输出的二次意见验证，也不是通用的权限缓存系统。审批对象的生命周期由调用方管理，ApprovalGate 不存储历史审批记录，也不在多次调用间累积状态。

它不替代领域验收测试。即使 authorize 返回 True，执行结果仍需通过 Verification 检查是否真正推进目标，审批门控只是副作用控制链中的一个环节。

它与相邻概念的关系

ApprovalGate 与 ChangePlan、Harness 的因果链

ApprovalGate 依赖 Stage 03 中已通过的 forge/tools/plans.py 的 ChangePlan 产生的 plan_digest。计划摘要是计划内容的密码学指纹，当计划内容变化时摘要必然变化，因此将审批绑定到摘要可以防止内容被替换后旧审批仍然有效。

Harness 在 Agent Loop 中调用 authorize，如果返回 False 则拒绝执行并保留日志证据，如果返回 True 才将操作传递给隔离执行环境。这种设计使审批决策与执行隔离分离，降低单点失误的风险。

Approval 的 operation_id 绑定确保审批针对特定操作而非通用令牌，plan_digest 绑定确保审批针对特定内容版本。两者缺一不可：只有 operation_id 匹配时，攻击者可以更换计划内容复用审批；只有 plan_digest 匹配时，审批可能被挪用到其他操作。

本阶段的边界决定: read 风险直接返回 True 不检查 approval；reversible_write 和 irreversible 风险要求 Approval 的 operation_id 和 plan_digest 同时匹配当前调用参数；未知风险抛出 ValueError，绝不默认放行。

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

教师示范

目标: 在软件场景中构造 ApprovalGate，验证 read 风险无需审批返回 True，然后验证 reversible_write 风险在 plan_digest 不匹配时返回 False、匹配时返回 True。

首先创建 forge/tools/approval.py 文件，定义冻结数据类 Approval，包含 operation_id: str 和 plan_digest: str 两个字段。然后定义 ApprovalGate 类，其 authorize 方法首先校验风险等级是否在已知集合中，未知则抛出 ValueError。

对于 read 风险，方法直接返回 True，因为读操作无副作用。对于 reversible_write 和 irreversible 风险，方法检查 approval 是否为 None，是则返回 False，否则比较 approval.operation_id == operation_id and approval.plan_digest == plan_digest。

这个示例展示了审批绑定的核心逻辑：操作标识确保审批针对正确的操作类型，计划摘要确保审批针对正确的内容版本。两者同时匹配才允许执行。

实施步骤

创建 forge/tools/approval.py，导入 dataclasses.dataclass 和 __future__.annotations。
定义 @dataclass(frozen=True) class Approval，包含 operation_id: str 和 plan_digest: str。
定义 class ApprovalGate，实现 authorize 方法：先校验 risk，read 返回 True，approval 为 None 返回 False，最后返回 approval.operation_id == operation_id and approval.plan_digest == plan_digest。

真实 solution 代码: forge/tools/approval.py

from __future__ import annotations

from dataclasses import dataclass

@dataclass(frozen=True)
class Approval:
    operation_id: str
    plan_digest: str

class ApprovalGate:
    def authorize(self, *, risk: str, operation_id: str, plan_digest: str, approval: Approval | None) -> bool:
        if risk not in {"read", "reversible_write", "irreversible"}:
            raise ValueError("unknown risk")
        if risk == "read":
            return True
        if approval is None:
            return False
        return approval.operation_id == operation_id and approval.plan_digest == plan_digest

python -m pytest -q tests/test_stage.py

运行真实测试

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

为什么这样实现

test_read_only_operation_needs_no_approval 验证 authorize(risk="read", operation_id="op", plan_digest="x", approval=None) 返回 True。这体现了读操作无副作用的边界决策：不需要审批对象，直接放行。

test_write_requires_approval_bound_to_the_exact_plan 验证当 plan_digest 为 new 而审批对象的 plan_digest 为 old 时返回 False，当两者都为 new 时返回 True。这证明了 and approval.plan_digest == plan_digest 条件的必要性。

test_unknown_risk_is_rejected 验证 risk="root" 时抛出 ValueError。这确保了未知风险等级不会默认放行，而是显式失败，防止新风险类型被意外允许。

带提示练习

解释 faultySource 中 return approval.operation_id == operation_id 为何允许旧 plan_digest 通过，并补全 and approval.plan_digest == plan_digest 条件使测试通过。

阅读 faultySource 中 ApprovalGate.authorize 的返回语句，确认它仅比较 operation_id 而忽略了 plan_digest 参数。
追踪 test_write_requires_approval_bound_to_the_exact_plan 的第一次断言：plan_digest="new" 但 Approval("op", "old") 的摘要为 old，当前代码因 operation_id 匹配而错误返回 True。
修改返回语句为 return approval.operation_id == operation_id and approval.plan_digest == plan_digest，使两个条件同时满足才返回 True。

逐级提示

注意 authorize 方法的参数列表中有 plan_digest: str，但 faultySource 的返回语句完全没有使用它。
思考：如果攻击者拿到了针对 old 计划的审批令牌，但当前计划已更新为 new，仅校验 operation_id 能否阻止攻击者执行新计划？
将 approval.operation_id == operation_id 与 approval.plan_digest == plan_digest 用 and 连接，确保两个条件同时为 True 才返回 True。

完成标准

test_write_requires_approval_bound_to_the_exact_plan 中 plan_digest 不匹配时 authorize 返回 False。
test_write_requires_approval_bound_to_the_exact_plan 中 plan_digest 匹配时 authorize 返回 True。
test_unknown_risk_is_rejected 仍然抛出 ValueError，未被修改影响。

故障注入与排查

在 fixtures/failure.json 定义的 stale-approval 故障中，forge/tools/approval.py 的 authorize 方法仅比较 approval.operation_id == operation_id，完全忽略 plan_digest 参数。当 test_write_requires_approval_bound_to_the_exact_plan 传入 plan_digest="new" 和 Approval("op", "old") 时，方法因 operation_id 匹配而错误返回 True，导致断言 assert ... is False 失败。

本阶段要求你理解审批必须同时绑定 operation_id 和 plan_digest。通过分析 faultySource 的返回语句，你可以定位到缺少 and approval.plan_digest == plan_digest 这一条件。补全该条件后，旧摘要 old 与当前摘要 new 不匹配，方法正确返回 False，测试通过。

已验证的故障合同

目标测试: test_write_requires_approval_bound_to_the_exact_plan
故障文件: forge/tools/approval.py

诊断顺序

运行 python -m pytest -q ../tests/test_stage.py::test_write_requires_approval_bound_to_the_exact_plan，观察 AssertionError: assert True is False，说明方法在应返回 False 时返回了 True。
检查 forge/tools/approval.py 中 authorize 的返回语句 return approval.operation_id == operation_id，确认它没有引用 plan_digest 参数。
对比测试中 plan_digest="new" 与 Approval("op", "old") 的 plan_digest="old"，确认两者不匹配但方法仍返回 True，根因是缺少摘要校验。

修复原则: 将 forge/tools/approval.py 中 authorize 方法的返回语句从 return approval.operation_id == operation_id 修改为 return approval.operation_id == operation_id and approval.plan_digest == plan_digest。这样当审批对象的 plan_digest 与当前调用的 plan_digest 不一致时，方法返回 False，阻止旧审批授权新计划内容。

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

迁移挑战

在音乐创作场景中，Agent 需要修改发行计划中的曲目元数据，这属于 reversible_write 风险，需要审批门控。

改变的条件: 将 operation_id 从 op 改为 release-op，plan_digest 从 new/old 改为 v2/v1，场景从软件交付切换到音乐发行。

构造 ApprovalGate，调用 authorize(risk="reversible_write", operation_id="release-op", plan_digest="v2", approval=Approval("release-op", "v1"))，验证返回 False。然后调用 authorize(risk="reversible_write", operation_id="release-op", plan_digest="v2", approval=Approval("release-op", "v2"))，验证返回 True。

完成标准

当 plan_digest 为 v2 而 Approval 的 plan_digest 为 v1 时，authorize 返回 False，阻止旧版本审批授权新版本发行计划。
当 operation_id 和 plan_digest 均匹配时，authorize 返回 True，允许对发行计划执行可逆写入。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

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

设计解释题: 为什么 read 风险直接返回 True 而不检查 approval？如果 plan_digest 不匹配但 operation_id 匹配，攻击者能做什么？请从副作用控制和审批绑定的因果角度解释这一设计权衡。

一个有力回答应包含

read 操作无副作用，不改变系统状态，因此无需审批门控，直接返回 True 可以减少不必要的审批摩擦。
如果 plan_digest 不匹配但 operation_id 匹配，攻击者可以替换计划内容后复用旧审批令牌执行未经验证的新写入，破坏审批与内容的一致性绑定。
将审批同时绑定到 operation_id 和 plan_digest 确保审批针对特定操作的特定内容版本，两者缺一都会打开重放或内容替换的攻击面。

掌握证据

test_read_only_operation_needs_no_approval 通过，验证 ApprovalGate().authorize(risk="read", ...) 返回 True。
test_write_requires_approval_bound_to_the_exact_plan 通过，验证 plan_digest 不匹配时返回 False、匹配时返回 True。
test_unknown_risk_is_rejected 通过，验证未知 risk 抛出 ValueError。
python -m pytest -q tests/test_stage.py 退出码为 0，三个测试全部通过。

STAGE 05

通过同目录临时文件和原子替换避免部分写入

先看一个具体问题

直接写入目标文件在崩溃时留下部分写入

在软件交付场景中，Agent 需要修改 config.txt 的内容。如果直接调用 target.write_bytes(content) 写入目标文件，当进程在写入过程中因崩溃或异常中断时，目标文件会残留部分字节，导致后续读取到截断的数据。

本阶段的起点是 forge/tools/approval.py 已通过验收，但 forge/tools/atomic.py 尚不存在，测试文件 tests/test_stage.py 在导入 forge.tools.atomic 时会抛出 ModuleNotFoundError。

学习者需要创建 forge/tools/atomic.py 并实现 atomic_write 函数，通过同目录临时文件和 os.replace 原子替换来保证目标文件要么完整更新，要么保持原样。

先做判断

当进程在 target.write_bytes(b"new-content") 执行到一半时崩溃，目标文件 config.txt 的内容会变成什么？

完整的新内容 b"new-content"
原始内容 b"old"
截断的部分内容，例如 b"new-c"
文件为空

判断依据: 直接写入目标文件不是原子操作，操作系统按字节逐步写入，崩溃时目标文件会保留已写入的部分字节，导致内容被截断而非完整或原始。

它是什么

原子写入的机制

原子写入要求所有字节先持久化到与目标文件位于同一目录的临时文件中，调用 handle.flush() 将 Python 缓冲区刷入操作系统，再调用 os.fsync(handle.fileno()) 强制将操作系统页缓存写入磁盘。

在临时文件完整持久化后，通过 os.replace(temporary_name, target) 将临时文件原子替换为目标文件。os.replace 在 POSIX 和 Windows 上都是原子操作，替换期间目标文件始终可访问且内容完整。

它不是什么

原子写入的边界

原子写入不是先写临时文件再直接写目标文件。如果先写临时文件再调用 target.write_bytes(content)，目标文件仍然面临部分写入的风险，临时文件的存在并不能保护直接写入的目标。

原子写入也不等于仅仅调用 flush()。flush() 只将 Python 内部缓冲区传递给操作系统，但数据可能仍停留在操作系统页缓存中，断电时会丢失，必须配合 os.fsync() 才能保证持久化。

它与相邻概念的关系

临时文件、替换与清理的协作

临时文件必须与目标在同一目录，因为 os.replace 的原子性仅在同一个文件系统内有效。跨文件系统替换会退化为先复制后删除的非原子操作。

finally 块中的 temporary_name 变量充当清理状态的标志。当 os.replace 成功后将其设为 None，表示临时文件已被替换、无需清理；若替换前发生异常，temporary_name 仍指向临时文件路径，finally 块负责将其删除以避免残留。

本阶段的边界决定: 原子写入的边界是：所有字节必须先通过同目录临时文件和 os.fsync 持久化，然后通过 os.replace 原子替换目标；失败时 finally 块必须清理残留的临时文件。

实验 ID: tools-sandbox-side-effects-05-atomic-write
输入: 软件交付：为前端仓库增加功能、修改代码并补测试。
证据目录: evidence/tools-sandbox-side-effects/05-atomic-write/
验收: 待验收

教师示范

目标: 在软件场景中对已有 b"old" 的 config.txt 调用 atomic_write(target, b"new-content")，验证目标内容完整更新且无 .tmp 残留。

首先创建 forge/tools/atomic.py 文件，定义 atomic_write 函数接收 target: Path 和 content: bytes 参数。函数体先调用 target.parent.mkdir(parents=True, exist_ok=True) 确保父目录存在。

然后使用 NamedTemporaryFile(dir=target.parent, prefix=target.name + ".", suffix=".tmp", delete=False) 在同目录创建临时文件，写入完整内容后调用 flush() 和 os.fsync() 持久化。

最后调用 os.replace(temporary_name, target) 完成原子替换，并将 temporary_name 设为 None 以跳过 finally 块的清理。

实施步骤

创建 forge/tools/atomic.py，导入 os、Path 和 NamedTemporaryFile
定义 atomic_write(target, content) 函数，先调用 target.parent.mkdir(parents=True, exist_ok=True)
在 try 块中用 NamedTemporaryFile 创建同目录临时文件，写入 content 后调用 handle.flush() 和 os.fsync(handle.fileno())
在 with 块退出后调用 os.replace(temporary_name, target) 并将 temporary_name 设为 None
在 finally 块中检查 temporary_name is not None 时调用 Path(temporary_name).unlink(missing_ok=True)

真实 solution 代码: forge/tools/atomic.py

from __future__ import annotations

import os
from pathlib import Path
from tempfile import NamedTemporaryFile

def atomic_write(target: Path, content: bytes) -> None:
    target.parent.mkdir(parents=True, exist_ok=True)
    temporary_name: str | None = None
    try:
        with NamedTemporaryFile(dir=target.parent, prefix=target.name + ".", suffix=".tmp", delete=False) as handle:
            temporary_name = handle.name
            handle.write(content)
            handle.flush()
            os.fsync(handle.fileno())
        os.replace(temporary_name, target)
        temporary_name = None
    finally:
        if temporary_name is not None:
            Path(temporary_name).unlink(missing_ok=True)

python -m pytest -q tests/test_stage.py

运行真实测试

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

为什么这样实现

NamedTemporaryFile 的 delete=False 参数确保在 with 块退出后临时文件不会被自动删除，因为我们需要在 with 块外部用 os.replace 移动它。

os.replace 在同一文件系统内是原子操作，目标文件要么完整指向新内容，要么保持原始内容，不会出现中间状态。

带提示练习

解释 faultySource 中 target.write_bytes(content[:1]) 为何只写入一个字节，并补全 os.replace(temporary_name, target) 调用使替换原子化。

阅读 faultySource 中的 target.write_bytes(content[:1]) 行，理解 content[:1] 只取第一个字节直接写入目标文件
理解这行代码绕过了临时文件，直接修改目标文件，导致目标文件被截断为单字节
将 target.write_bytes(content[:1]) 替换为 os.replace(temporary_name, target)，用原子替换代替直接写入
确认替换后 temporary_name = None 仍然存在，使 finally 块跳过清理

逐级提示

content[:1] 是 Python 切片语法，返回 content 的第一个字节，例如 b"new-content"[:1] 结果为 b"n"
os.replace(source, destination) 将 source 路径的文件原子移动到 destination 路径，覆盖已有文件
临时文件在 with 块退出后已关闭但未删除，temporary_name 保存了它的路径，os.replace 可以引用它

完成标准

target.write_bytes(content[:1]) 被替换为 os.replace(temporary_name, target)
运行 python -m pytest -q tests/test_stage.py::test_atomic_write_replaces_the_complete_file 通过

故障注入与排查

在 fixtures/failure.json 定义的 partial-write 故障中，forge/tools/atomic.py 的 atomic_write 函数已经正确创建了同目录临时文件并调用了 os.fsync 持久化，但在替换阶段没有调用 os.replace，而是直接执行 target.write_bytes(content[:1]) 将内容的第一个字节写入目标文件。这导致 test_atomic_write_replaces_the_complete_file 断言失败，因为目标文件内容为 b"n" 而非预期的 b"new-content"，同时临时文件被遗弃在同目录中。

本阶段已经建立了临时文件创建、fsync 持久化和 finally 清理的完整心智模型，学习者只需识别出 target.write_bytes(content[:1]) 绕过了原子替换这一关键缺陷，将其改为 os.replace(temporary_name, target) 即可修复。os.replace 保证目标文件要么完整替换为已持久化的临时文件内容，要么保持原样，不会出现部分写入。

已验证的故障合同

目标测试: test_atomic_write_replaces_the_complete_file
故障文件: forge/tools/atomic.py

诊断顺序

运行 python -m pytest -q ../tests/test_stage.py::test_atomic_write_replaces_the_complete_file，观察断言错误 assert b'n' == b'new-content'
打开 forge/tools/atomic.py，定位到 target.write_bytes(content[:1]) 行，分析 content[:1] 只取第一个字节 b"n"
对比已持久化的临时文件和直接写入目标文件的两条路径，确认缺少 os.replace(temporary_name, target) 调用

修复原则: 将 forge/tools/atomic.py 中的 target.write_bytes(content[:1]) 替换为 os.replace(temporary_name, target)。os.replace 将已通过 fsync 持久化的同目录临时文件原子移动到目标路径，覆盖原有内容。替换成功后 temporary_name 被设为 None，finally 块不会重复删除已不存在的临时文件。

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

迁移挑战

办公研究场景中，需要将季度决策简报写入嵌套路径 tmp_path / "reports" / "summary.txt"。

改变的条件: 将目标路径从 config.txt 改为嵌套路径 reports/summary.txt，内容从 b"new-content" 改为 b"Q3 summary"

使用已验证的 atomic_write 函数，对 tmp_path / "reports" / "summary.txt" 调用 atomic_write(target, b"Q3 summary")，验证目标文件内容为 b"Q3 summary"。仅修改目标路径和内容参数，不改变函数签名或内部实现。

完成标准

目标路径 tmp_path / "reports" / "summary.txt 的 read_bytes() 返回 b"Q3 summary"
tmp_path / "reports" 目录下无 .tmp 残留文件，且 atomic_write 自动创建了嵌套父目录

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

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

设计解释题: 为什么临时文件必须与目标文件在同一目录？如果临时文件位于跨文件系统的 /tmp 目录，os.replace 的行为会发生什么变化？

一个有力回答应包含

os.replace 的原子性仅在同一文件系统内保证，同目录确保临时文件和目标文件属于同一挂载点
跨文件系统时 os.replace 会退化为先复制后删除的非原子操作，复制过程中崩溃会导致目标文件部分写入
同目录还保证了替换操作是文件系统级的重命名，不涉及数据拷贝，性能更高且不会占用额外磁盘空间

掌握证据

test_atomic_write_replaces_the_complete_file 通过，验证 atomic_write 用 os.replace 原子替换目标文件且无 .tmp 残留
test_failed_replace_preserves_original_and_removes_temp 通过，验证 os.replace 失败时目标保持 b"old" 且 finally 块清理临时文件
test_parent_directory_is_created 通过，验证 atomic_write 通过 mkdir(parents=True, exist_ok=True) 自动创建嵌套父目录
python -m pytest -q tests/test_stage.py 退出码为 0，三个测试全部通过

STAGE 06

在变更前捕获文件存在性与原内容，并按逆序完整回滚

先看一个具体问题

文件修改后如何可靠地回到修改前的状态？

在软件交付场景中，你正在为一个前端仓库添加功能，需要修改现有文件并创建新文件。如果修改过程中出现错误，你必须能够将文件系统恢复到修改前的状态，否则后续步骤会基于错误的内容继续执行。

你手头已有 forge/tools/atomic.py 提供的 atomic_write 函数，它保证单次写入的原子性，但它不记录修改前的状态。你需要一个新的机制，在修改前捕获文件的存在性和原始字节，以便在需要时回滚。

本阶段的核心挑战是：当同一个文件被多次修改时，回滚日志必须保留第一次捕获的快照，而不是用后续修改后的内容覆盖它。如果覆盖了，回滚就会恢复到中间状态，而不是事务开始前的状态。

先做判断

在 RollbackJournal.capture 方法中，如果对同一个路径调用两次 capture，你认为第二次调用应该如何处理？

用当前内容覆盖第一次的快照，因为最新状态更准确。
忽略第二次调用，保留第一次捕获的快照。
追加一个新的快照，回滚时按逆序恢复所有快照。
抛出异常，因为重复捕获是编程错误。

判断依据: 正确答案是忽略第二次调用。回滚日志的目的是记录事务开始时的状态，而不是每次修改后的状态。如果覆盖了第一次快照，回滚就会恢复到中间状态，而不是原始状态。

它是什么

回滚日志是什么

回滚日志是一个记录文件系统变更前状态的列表，每个条目包含路径、该路径在捕获时是否存在以及原始字节内容。

capture 方法在修改文件之前调用，它记录当前状态；rollback 方法按逆序恢复这些状态，从而撤销所有变更。

它不是什么

回滚日志不是什么

回滚日志不是每次修改的完整历史记录，它只关心事务开始时的状态，因此不需要记录中间版本。

它也不是备份系统，它不保存修改后的内容，只保存修改前的状态，用于撤销操作。

它与相邻概念的关系

与原子写入的关系

atomic_write 保证单个文件写入的原子性，而回滚日志管理多个文件的整体恢复，两者互补。

回滚日志在恢复时调用 atomic_write 来写回原始内容，确保恢复过程本身也是原子的。

本阶段的边界决定: 回滚日志只处理文件系统状态，不涉及内存中的对象或数据库事务；它假设所有变更都通过文件系统操作完成，并且 capture 必须在修改前调用。

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

教师示范

目标: 在软件场景中，对已有 b"original" 的 file.txt 调用 journal.capture(target)，修改为 b"changed" 后再次 journal.capture(target)，然后 journal.rollback()，验证 target.read_bytes() == b"original"。

首先，你需要创建 forge/tools/rollback.py 文件，定义 Snapshot 和 RollbackJournal 两个类。Snapshot 是一个冻结的数据类，保存路径、存在性和内容。

RollbackJournal 维护一个快照列表，capture 方法在添加新快照前检查是否已有相同路径的快照，如果有则直接返回，确保保留首次快照。

rollback 方法遍历快照列表的逆序，对于存在的文件用 atomic_write 写回原始内容，对于不存在的文件则删除它。

实施步骤

创建 forge/tools/rollback.py，导入 dataclass、field、Path 和 atomic_write。
定义 Snapshot 数据类，包含 path、existed 和 content 字段。
定义 RollbackJournal 类，初始化 snapshots 列表。
实现 capture 方法：如果 snapshots 中已有相同路径，则直接返回；否则添加新快照。
实现 rollback 方法：逆序遍历快照，根据 existed 字段决定写回或删除。

真实 solution 代码: forge/tools/rollback.py

from __future__ import annotations

from dataclasses import dataclass, field
from pathlib import Path

from .atomic import atomic_write

@dataclass(frozen=True)
class Snapshot:
    path: Path
    existed: bool
    content: bytes

@dataclass
class RollbackJournal:
    snapshots: list[Snapshot] = field(default_factory=list)

    def capture(self, path: Path) -> None:
        if any(item.path == path for item in self.snapshots):
            return
        self.snapshots.append(Snapshot(path, path.exists(), path.read_bytes() if path.exists() else b""))

    def rollback(self) -> None:
        for snapshot in reversed(self.snapshots):
            if snapshot.existed:
                atomic_write(snapshot.path, snapshot.content)
            else:
                snapshot.path.unlink(missing_ok=True)

python -m pytest -q tests/test_stage.py

运行真实测试

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

为什么这样实现

在 capture 中，if any(item.path == path for item in self.snapshots): return 确保第二次调用不会覆盖第一次的快照，这是幂等性的关键。

rollback 使用 reversed(self.snapshots) 逆序恢复，因为后修改的文件应该先恢复，避免依赖关系问题。

带提示练习

解释 faultySource 中 self.snapshots = [item for item in self.snapshots if item.path != path] 为何丢弃首次快照，并补全 if any(item.path == path for item in self.snapshots): return 守卫使 capture 幂等。

阅读 forge/tools/rollback.py 的 faultySource，注意 capture 方法中的列表推导式。
分析该推导式的作用：它移除所有与当前路径相同的旧快照，然后追加新快照，这导致首次快照被覆盖。
修改 capture 方法，在追加前检查是否已有相同路径，如果有则直接返回。
运行测试 test_capture_keeps_the_first_prechange_snapshot 验证修改。

逐级提示

使用 any() 函数检查 self.snapshots 中是否存在相同路径的条目。
如果存在，直接 return，不要执行后续的追加操作。

完成标准

capture 方法对已记录路径是幂等的，不会覆盖首次快照。
test_capture_keeps_the_first_prechange_snapshot 测试通过。

故障注入与排查

在故障实验室中，你面对的是 fixtures/failure.json 描述的缺陷：当同一个路径被多次捕获时，回滚日志错误地覆盖了首次快照。具体表现为 test_capture_keeps_the_first_prechange_snapshot 失败，因为回滚后文件内容变成了中间修改后的 b"changed" 而不是原始 b"original"。

本阶段的核心概念就是保留首次快照，因此你可以直接应用 capture 的幂等性修复。通过检查 self.snapshots 中是否已有相同路径，你可以阻止覆盖行为，这正是故障的根因。

已验证的故障合同

目标测试: test_capture_keeps_the_first_prechange_snapshot
故障文件: forge/tools/rollback.py

诊断顺序

运行 python -m pytest -q ../tests/test_stage.py::test_capture_keeps_the_first_prechange_snapshot，观察失败输出。
检查 forge/tools/rollback.py 中的 capture 方法，发现它使用列表推导式移除了旧快照。
理解该推导式导致首次快照被丢弃，第二次捕获时记录了修改后的内容。
修复方法：在追加前检查是否已有相同路径，如果有则直接返回。

修复原则: 在 capture 方法开头添加 if any(item.path == path for item in self.snapshots): return，这样第二次捕获时不会覆盖首次快照。然后运行测试确认通过。

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

迁移挑战

在音乐创作场景中，你正在整理曲目信息，需要修改 tracks/lyrics.txt 的内容。你使用 RollbackJournal 记录修改前的状态，修改后回滚，确保内容恢复。

改变的条件: 将文件路径从 file.txt 改为 tracks/lyrics.txt，内容从 b"original" 和 b"changed" 改为 b"track-v1" 和 b"track-v2"，其余逻辑不变。

使用 RollbackJournal 构造日志，对 tracks/lyrics.txt 调用 capture，修改为 b"track-v2"，然后调用 rollback，验证内容恢复为 b"track-v1"。

完成标准

tracks/lyrics.txt 在回滚后内容等于 b"track-v1"。
RollbackJournal 的 rollback 方法恢复文件内容为 b"track-v1"。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

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

设计解释题: 为什么 rollback 方法必须使用 reversed(self.snapshots) 而不是正序遍历？请解释逆序恢复的必要性，并说明如果正序恢复可能产生什么后果。

一个有力回答应包含

逆序恢复确保后修改的文件先恢复，避免依赖关系问题，例如文件A被修改后，文件B基于A的新内容创建，正序恢复会先恢复A，导致B的恢复失败。
逆序恢复符合事务回滚的语义，即撤销操作按相反顺序执行，确保系统回到事务开始时的状态。

掌握证据

test_rollback_restores_modified_and_deleted_files 通过，验证了修改和删除文件的恢复。
test_capture_keeps_the_first_prechange_snapshot 通过，验证了首次快照的保留。
test_empty_journal_is_safe 通过，验证了空日志的回滚不产生错误。
python -m pytest -q tests/test_stage.py 退出码为 0，所有测试通过。

STAGE 07

把路径校验、计划审批、原子写入、回滚和审计组合为安全变更事务

先看一个具体问题

控制器如何确保只有经过审批的字节被写入，且路径逃逸时能回滚？

你已经在前面阶段分别实现了路径解析、计划构建、审批门、原子写入和回滚日志，但还没有一个统一的入口来串联这些能力。现在需要创建 forge/tools/controller.py，提供 SideEffectController 类，其 apply 方法在一次调用中完成：构建计划、计算摘要、通过审批门校验、逐个原子写入，并在任何异常时回滚已写入的文件。

当前测试文件 tests/test_stage.py 导入 from forge.tools.controller import SideEffectController, plan_digest，但该模块不存在，因此运行 python -m pytest -q tests/test_stage.py 会报 ModuleNotFoundError: No module named 'forge.tools.controller'，收集阶段直接失败。你的任务是创建这个模块，并让三个测试全部通过。

三个测试分别验证：正常审批后写入指定字节且审计状态为 committed；旧审批（摘要不匹配）被拒绝且不产生任何写入，审计状态为 denied；路径逃逸（如 ../escape.txt）触发回滚，已写入的安全文件被恢复，审计状态为 rolled_back。

先做判断

在实现 SideEffectController.apply 时，你认为审批校验的关键点是什么？

只要 approval 参数不是 None 就允许写入
必须用当前计划计算的摘要与 approval 中的摘要比对，通过 ApprovalGate 校验
只需要检查 approval.operation_id 是否匹配
不需要校验，直接写入即可

判断依据: 正确答案是第二个选项。测试 test_stale_approval_is_denied_without_writes 专门验证旧审批（摘要不匹配）必须被拒绝，因此仅检查 approval 非 None 是不够的，必须调用 ApprovalGate().authorize 并传入当前计划计算的摘要。

它是什么

安全变更事务的组成

SideEffectController.apply 是一个编排函数，它把五个独立能力按固定顺序串联：先用 build_change_plan 生成计划，再用 plan_digest 计算摘要，然后通过 ApprovalGate.authorize 校验审批，接着用 resolve_workspace_path 解析每个目标路径，最后用 atomic_write 写入并用 RollbackJournal 记录以便回滚。

摘要的计算方式是：对计划中每个写入项的 content_sha256 按顺序拼接成字符串，再对整个字符串做 SHA-256 哈希。这样任何字节变化都会导致摘要变化，从而让旧审批失效。

它不是什么

它不是简单的存在性检查

apply 不是只要 approval 对象存在就放行，而是必须验证审批的摘要与当前计划完全一致。如果只检查 approval is None，那么一个针对旧计划的审批也能通过，这正是故障夹具中注入的缺陷。

它也不是把写入和回滚分开处理，而是用 try/except 包裹整个写入循环，任何异常（包括路径逃逸）都会触发回滚，确保不会留下部分写入的状态。

它与相邻概念的关系

各组件如何协作

build_change_plan 生成计划，plan_digest 从计划中提取摘要，ApprovalGate.authorize 用摘要和 operation_id 校验审批，resolve_workspace_path 确保路径在 workspace 内，atomic_write 执行写入，RollbackJournal 记录已写入文件以便回滚。

审计列表 audit 记录每次操作的结果状态，测试通过检查 controller.audit[-1]["status"] 来验证行为是否符合预期。

本阶段的边界决定: 当审批摘要与当前计划摘要不一致时，必须拒绝写入并记录 denied，而不是尝试部分写入或忽略差异；当路径逃逸时，必须回滚所有已写入的文件并记录 rolled_back，而不是只跳过逃逸路径。

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

教师示范

目标: 在软件场景中，构造 SideEffectController(tmp_path)，调用 controller.apply("op-7", {"src/a.txt": b"A", "src/b.txt": b"B"}, Approval("op-7", plan_digest({"src/a.txt": b"A", "src/b.txt": b"B"})))，验证文件已写入且 controller.audit[-1]["status"] == "committed"。

首先，你需要创建 forge/tools/controller.py 文件，并导入所需的依赖：Approval, ApprovalGate, atomic_write, resolve_workspace_path, build_change_plan, RollbackJournal。

然后，实现 SideEffectController 类，其 apply 方法接受操作 ID、写入字典和审批对象。在方法内部，先构建计划并计算摘要，然后调用 ApprovalGate().authorize 进行校验，只有通过后才进入写入循环。

写入循环中，对每个相对路径，先调用 resolve_workspace_path 得到绝对路径，再用 journal.capture(target) 记录，最后用 atomic_write 写入。如果任何一步抛出异常，就调用 journal.rollback() 并记录 rolled_back。

实施步骤

创建 forge/tools/controller.py，导入所需模块。
定义 SideEffectController 数据类，包含 workspace 和 audit 字段。
实现 apply 方法：构建计划、计算摘要、调用 ApprovalGate().authorize，通过后执行写入循环。
实现 plan_digest 函数，用于计算写入字典的摘要。
运行测试命令，确认三个测试全部通过。

真实 solution 代码: forge/tools/controller.py

from __future__ import annotations

from dataclasses import dataclass, field
from hashlib import sha256
from pathlib import Path

from .approval import Approval, ApprovalGate
from .atomic import atomic_write
from .paths import resolve_workspace_path
from .plans import build_change_plan
from .rollback import RollbackJournal

@dataclass
class SideEffectController:
    workspace: Path
    audit: list[dict[str, str]] = field(default_factory=list)

    def apply(self, operation_id: str, writes: dict[str, bytes], approval: Approval | None) -> None:
        plan = build_change_plan(operation_id, {path: ("write file", content) for path, content in writes.items()})
        digest = sha256("".join(item.content_sha256 for item in plan.writes).encode("ascii")).hexdigest()
        if not ApprovalGate().authorize(risk="reversible_write", operation_id=operation_id, plan_digest=digest, approval=approval):
            self.audit.append({"operation_id": operation_id, "status": "denied"})
            raise PermissionError("write approval required")
        journal = RollbackJournal()
        try:
            for relative, content in writes.items():
                target = resolve_workspace_path(self.workspace, relative)
                journal.capture(target)
                atomic_write(target, content)
        except Exception:
            journal.rollback()
            self.audit.append({"operation_id": operation_id, "status": "rolled_back"})
            raise
        self.audit.append({"operation_id": operation_id, "status": "committed"})

def plan_digest(writes: dict[str, bytes]) -> str:
    plan = build_change_plan("preview", {path: ("write file", content) for path, content in writes.items()})
    return sha256("".join(item.content_sha256 for item in plan.writes).encode("ascii")).hexdigest()

python -m pytest -q tests/test_stage.py

运行真实测试

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

为什么这样实现

在 apply 中，ApprovalGate().authorize 会检查审批的摘要是否与当前计划摘要一致，如果不一致则返回 False，从而拒绝写入并记录 denied。

写入循环中的 journal.capture(target) 在写入前记录原文件状态，这样如果后续写入失败或路径逃逸，journal.rollback() 能恢复所有已写入的文件。

带提示练习

解释 faultySource 中 if approval is None 为何允许旧 plan_digest 通过审批，并补全 ApprovalGate().authorize(risk="reversible_write", operation_id=operation_id, plan_digest=digest, approval=approval) 调用使控制器校验 digest。

阅读 forge/tools/controller.py 的 faultySource，找到 if approval is None 这一行。
分析为什么这个检查只验证了审批对象存在，而没有验证审批的摘要与当前计划摘要一致。
将 if approval is None 替换为 if not ApprovalGate().authorize(risk="reversible_write", operation_id=operation_id, plan_digest=digest, approval=approval):。
运行 python -m pytest -q tests/test_stage.py::test_stale_approval_is_denied_without_writes 确认测试通过。

逐级提示

ApprovalGate.authorize 的签名是什么？它需要哪些参数？
摘要 digest 已经在代码中计算好了，你只需要把它传给 authorize。
注意 authorize 返回布尔值，如果为 False 应该拒绝写入并记录 denied。

完成标准

test_stale_approval_is_denied_without_writes 通过，且 controller.audit[-1]["status"] == "denied"。
test_controller_applies_only_the_approved_bytes 和 test_workspace_escape_is_rolled_back 仍然通过。

故障注入与排查

在故障夹具 fixtures/failure.json 中，目标测试是 test_stale_approval_is_denied_without_writes，目标文件是 forge/tools/controller.py。注入的缺陷是只检查审批对象是否存在，而没有验证审批的摘要是否与当前计划一致。因此，当你用一个针对旧计划（内容为 b"old"）的审批去申请写入新内容（b"new"）时，控制器错误地允许了写入，导致测试期望抛出 PermissionError 却没有抛出，测试失败。

本阶段的核心就是学习如何组合审批校验和写入逻辑，而故障夹具正是针对这一组合的缺陷。通过修复 apply 方法中的审批校验，你可以理解为什么必须用当前计划计算的摘要来验证审批，而不是仅仅检查审批对象是否存在。

已验证的故障合同

目标测试: test_stale_approval_is_denied_without_writes
故障文件: forge/tools/controller.py

诊断顺序

运行 python -m pytest -q ../tests/test_stage.py::test_stale_approval_is_denied_without_writes，观察失败信息：DID NOT RAISE PermissionError。
检查 forge/tools/controller.py 中的 apply 方法，发现 if approval is None 只检查了审批对象是否存在。
对比测试代码，测试传入的审批摘要与当前计划摘要不一致，但控制器没有调用 ApprovalGate().authorize 来校验，因此错误地允许了写入。
修复方法：将 if approval is None 替换为 if not ApprovalGate().authorize(risk="reversible_write", operation_id=operation_id, plan_digest=digest, approval=approval):。

修复原则: 在 apply 方法中，用 ApprovalGate().authorize 替换简单的存在性检查，传入 risk="reversible_write"、operation_id、当前计划计算的 digest 和 approval。这样，当审批摘要与当前计划不一致时，authorize 返回 False，控制器会记录 denied 并抛出 PermissionError，从而阻止写入。

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

迁移挑战

在办公场景中，你需要为一份季度简报生成草稿文件。使用 SideEffectController 和 plan_digest，将数据从 src/a.txt 和 b"A" 改为 report/draft.md 和 b"# Q3 Brief"。构造控制器并调用 apply，验证文件写入且审计状态为 committed。

改变的条件: 操作 ID 从 ‘op-7’ 变为 ‘brief-op’，写入文件数从两个变为一个，要求学习者针对新的操作 ID 和单文件写入重新计算摘要并构造审批。

编写一个测试或脚本，使用 SideEffectController(tmp_path) 和 plan_digest，调用 controller.apply("brief-op", {"report/draft.md": b"# Q3 Brief"}, Approval("brief-op", plan_digest({"report/draft.md": b"# Q3 Brief"})))，然后断言 (tmp_path / "report/draft.md").read_bytes() == b"# Q3 Brief" 且 controller.audit[-1]["status"] == "committed"。

完成标准

验证 (tmp_path / "report/draft.md").read_bytes() 等于 b"# Q3 Brief"，确保新路径和内容被正确写入。
验证 controller.audit[-1]["status"] 等于 "committed"，确保审批通过且操作成功记录。
验证 controller.audit[-1]["operation_id"] 等于 "brief-op"，确保操作 ID 正确传递。

运行真实测试

python -m pytest -q tests/test_stage.py

运行真实测试

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

设计解释题: 为什么摘要必须由所有计划写入项的 content_sha256 拼接后再哈希，而不是直接对每个文件内容单独哈希？请解释这种设计如何防止部分内容被替换而摘要不变。

一个有力回答应包含

拼接所有 content_sha256 再哈希，可以确保任何一项内容变化都会导致最终摘要变化，因为哈希对输入的任何位变化都敏感。
如果单独哈希每个文件，攻击者可能通过交换文件顺序或替换部分内容而不改变整体摘要，但拼接顺序固定，且每个 content_sha256 已经绑定到具体内容，因此无法绕过。

掌握证据

test_controller_applies_only_the_approved_bytes 通过，验证了正常审批后写入指定字节且审计状态为 committed。
test_stale_approval_is_denied_without_writes 通过，验证了旧审批被拒绝且不产生写入，审计状态为 denied。
test_workspace_escape_is_rolled_back 通过，验证了路径逃逸时回滚已写入文件，审计状态为 rolled_back。
运行 python -m pytest -q tests/test_stage.py 退出码为 0，所有测试通过。

完成本章

修改文件前生成计划、等待确认并保留恢复记录。

FORGE / LOCAL CHECK

本地实验自检

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

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

选择 verification.json

主要层

依赖能力

为后续提供

受这些层约束

概念校准

工具

Harness

验证与评测

工具系统、沙箱与副作用控制

先看一个具体问题

Harness 在工具调用前如何知道工具可能产生哪些副作用

先做判断

它是什么

工具能力声明是 Harness 权限决策的依据

它不是什么

工具能力声明不等于任意脚本或 MCP 协议

它与相邻概念的关系

能力词汇表、描述符与注册表的因果链

先看一个具体问题

字符串拼接无法阻止路径穿越

先做判断

它是什么

路径规范化解析的含义

它不是什么

词法前缀匹配不是安全检查

它与相邻概念的关系

resolve 与 relative_to 的协作关系

先看一个具体问题

写入前必须生成绑定字节内容的变更计划

先做判断

它是什么

变更计划是不可变的内容绑定契约

它不是什么

摘要文本不能替代字节内容作为审批依据

它与相邻概念的关系

计划与 Harness 审批及验证的因果链

先看一个具体问题

旧审批通过新计划：缺少 plan_digest 绑定的副作用风险

先做判断

它是什么

ApprovalGate 的审批绑定模型

它不是什么

ApprovalGate 不是执行器也不是权限缓存

它与相邻概念的关系

ApprovalGate 与 ChangePlan、Harness 的因果链

先看一个具体问题

直接写入目标文件在崩溃时留下部分写入

先做判断

它是什么

原子写入的机制

它不是什么

原子写入的边界

它与相邻概念的关系

临时文件、替换与清理的协作

先看一个具体问题

文件修改后如何可靠地回到修改前的状态？

先做判断

它是什么

回滚日志是什么

它不是什么

回滚日志不是什么

它与相邻概念的关系

与原子写入的关系

先看一个具体问题

控制器如何确保只有经过审批的字节被写入，且路径逃逸时能回滚？

先做判断

它是什么

安全变更事务的组成

它不是什么

它不是简单的存在性检查

它与相邻概念的关系

各组件如何协作