← Agents From First Principles

构建完整智能体

把十个机制组合成一个可运行的智能体,放到一个真正坏掉的仓库上。新增不加任何机制。报告那些独立构建的章节在名字、状态身份与谁拥有真值这些接缝上哪里起争执。

本书里每个机制都对照一个为隔离它而选的问题被论证过。

这种隔离是刻意的,它也是一种保护。记忆章取的是召回成瓶颈的任务,把其他一切停住,去度量它所来要度量的那一件事。结果是更干净的解释和更弱的主张。它里边什么也没确立——比如同一个检索策略在搜索控制器扩展四十个节点时的行为,或当验证器坚持每一份证据都必须携带搜索控制器从未听说过的状态身份时的行为。

组合失败自成一类缺陷。它们可能不出现在任何单个机制的测试里,因为每个机制都是对照自己章节的假设测的。它们出现在接缝处:两样组件给同一个对象取了不同的名字、给不同的对象取了相同的名字、或在状态、权威、身份、证据上悄悄抱持不相容的假设。组合还能在另一组件或环境行使它局部测试从未挑战过的某个假设时,暴露单个组件内部潜在的缺陷。

因此本章把整套东西跑到一个小小的、真正坏掉的仓库上,遵守一个单一约束:

压轴章不新增任何智能体机制。

这个约束正是它值得做的事的原因。如果完整系统只有在引入一个框架、一个编排层,或一个特权提示之后才能跑起来,那么前面各章就是十篇随笔而非一个构造,本书的中心主张就只是装饰。

一个命令跑它:

python -m first_principles_agent \
    --repo examples/broken-parser \
    --task "Fix pipe-delimited records"

有趣的结果不是成功修复。最终集成过了一遍就浮出九个接缝处的发现。七个要求代码、类型或策略修正;一个要求一条显式的预算假设;一个毫无特别胶合地成立。最严重的是一个对抗性运行发现、而一次干净演示会隐藏的、真正的验证器 bug。第 14 节列出了全部九个。本章其余部分挣出它们。


1. 一个小到拿得动的缺陷,以及一个先于优化而立的契约

目标仓库只有一个函数和一个错误。

# parser.py
def split_record(text: str, delimiter: str = ",") -> list[str]:
    return text.split(",")

签名接受一个分隔符,而函数体忽略它。

两个测试描述后果,它们的不对称正是任务有用的原整性——不是任意性。

# tests/test_parser.py
def test_default_comma_delimiter() -> None:
    assert split_record("A,B,C") == ["A", "B", "C"]

def test_pipe_delimiter() -> None:
    assert split_record("A|B|C", "|") == ["A", "B", "C"]

第一个通过。第二个失败。一个只有失败测试的任务承认退化解法——让失败别再发生——而保留要求把练习变成工程:有些东西必须改变,同时有些东西必须保持为真。

验证章的契约类型直接表达了这个形状。

CONTRACT = GoalContract(criteria=(
    Criterion(
        id="pipe",
        description="split_record splits pipe-delimited records on the pipe",
        kind=CriterionKind.CHANGE,
    ),
    Criterion(
        id="comma",
        description="split_record still splits comma-delimited records",
        kind=CriterionKind.PRESERVE,
    ),
    Criterion(
        id="protected",
        description="tests/test_parser.py remains byte-identical to the baseline",
        kind=CriterionKind.PRESERVE,
    ),
))

第三条不是可选的好粒子。删掉 test_pipe_delimiter 就让可见套件变绿;这样做等于毁掉告诉我们要么要求行为是否被保留的仪器。FORBID 仍是一般契约词汇的一部分;这个 fixture 不需要强行让每个枚举成员被使用,当保留判据更准确地陈述了要求。

时机比内容要紧。

契约由可信的任务建立在允许行动策略对着它优化之前就固定。在这个压轴里,harness被允许为了构造契约而检视受控 fixture 及其基线相关资产,因为受保护路径与保留要求是仓库事实。模型不能做的是,一旦学到哪条难,就弱化或重写那些判据。

那就是真正的不变量:

成功的定义必须先于针对它的优化而确立,尽管不必先于对任务的观察。

一个建立在运行之后、或一旦判据显得难就悄悄修订的契约,度量的是这次运行碰巧做的任何事。

模型提案要尝试什么。成功的定义不是它能重新定义的事情之一。


2. 两个都叫 GoalContract 的对象

第一个接缝在 import 语句处失败。

规划章定义了一个叫 GoalContract 的对象,描述一条经过任务的路线是否可走:哪些事实被给定、哪些是可得的、哪些顺序必须成立。验证章定义了一个叫 GoalContract 的对象,描述现实是否改变:一个判据元组,每项带 id 与 kind,加一个修订计数器。两者都是冻结的数据类。两者都以目标命名。没有任何一个字段相同。

规划契约 验证契约
问题 这条路线可走吗? 世界按要求改变了吗?
评估时机 执行之前 最后一次变异之后
内容 事实集合、顺序约束 带 kinds 的判据
失败形态 不可行的计划 FAIL、PARTIAL 或 UNKNOWN

写在相隔六章之处,每个名字在本地都相当合理。放在一个模块里,它们相撞;而这次相撞精确是验证章在其结尾警告过的:一份计划表示悄悄变成它本该描述的状态。如果两个对象都答覆 contract,那运行时里某个函数就会接受 whichever 交给它,然后答出一个没人问过的问题。

压轴把规划对象命名为 PlanContract,而让 GoalContract 留给验证器。

那是一个带着承重理由的小编辑。可行性与达成是不同的主张,它们在不同时候对照不同证据被评估,一个能够混淆它们的系统最终会因为计划连贯而报告任务成功。


3. 工作区是状态的单位

搜索、修订与预览都想试东西。没有一个能碰受控的 fixture。

应用因此把仓库复制进一个隔离工作区,只在复本上工作,这样每次运行都从同一个已知缺陷开始,而不是从前一次运行留下的任何东西。原本保持坏着,是故意的。它是「什么改变了」能成为一个有意义问题的基线。

这份复本还必须变成一个身份。验证章把每一份证据绑定到一个 state_id,并把 id 不匹配所裁定状态的证据丢掉;这要求从与判据相关的所有工作区内容到字符串有一个函数。

第一个实现故意很小:

def _rel(path: Path, root: Path) -> str:
    return str(path.relative_to(root))

IGNORED_PARTS = frozenset({
    ".git",
    ".pytest_cache",
    "__pycache__",
})

def snapshot(root: Path) -> dict[str, str]:
    return {
        _rel(path, root): sha256(path.read_bytes()).hexdigest()
        for path in sorted(root.rglob("*"))
        if path.is_file()
        and not (set(path.parts) & IGNORED_PARTS)
    }

def state_id(snap: dict[str, str]) -> str:
    payload = "\n".join(
        f"{path}:{digest}"
        for path, digest in sorted(snap.items())
    )
    return sha256(payload.encode()).hexdigest()[:16]

几行哈希,整个证据系统就立在它们的表示选择之上。

快照排除验证器生成的缓存目录,这样 merely 通过 Python 或 pytest 运行一遍就能观察到的、不会因观察就改变其身份的工作区。这个排除是状态契约的一部分,不是 housekeeping:身份里省略的任何东西必须不能影响被验证的判据。更大系统需要对生成产物、符号链接、权限与可能判据相关的其他元数据有一条显式政策。

第 12 节回到 _rel,因为它的第一个实现在一种只有在正确操作系统上的对抗性运行才能揭示的方式里是错的。

工作区也是分支隔离活在的地方。轨迹搜索章在部分未来上分支并最终只提交一个;压轴把一个分支实现为第二份副本,这样一次真正把真正测试套件跑起来的预览能保持真正工作区不被触碰。

    flowchart LR
    SRC["受控 fixture<br/>examples/broken-parser"] -->|copy| WS["工作区<br/>state_id: s0"]
    WS -->|copy| B1["分支 B1<br/>state_id: b1"]
    WS -->|copy| B2["分支 B2<br/>state_id: b2"]
    B1 -.discarded.-> X1[ ]
    B2 -.discarded.-> X2[ ]
    WS ==>|one authorized mutation| WS2["工作区<br/>state_id: s1"]
    WS2 --> EV["绑定 s1 的证据"]
    style WS2 fill:#f6c8c8,stroke:#b04a4a
    style X1 fill:none,stroke:none
    style X2 fill:none,stroke:none
  

虚线分支携带一个第 8 节使之精确的后果。

一个分支可以真正产生测试结果。那些结果是证据——关于 b1 的证据——而不是任何人将最终裁定的那个状态。


4. 暴露跟随阶段,删除不在动作空间

压轴需要三项普通能力:读取文件、运行测试、应用补丁。每项都是一名 ToolSpec,声明了 effect——而这个效果正是暴露策略推理的内容。能力章的可信控制结果保留存在,因此动作表面仍然可以请求、等待或弃权,如果任务变得不能继续。

run_tests 仅被标记为 READ_ONLY,因为处理器被约束成不会留下与判据相关的变异。一个写出缓存、夹具或生成文件的原始测试命令,不会仅仅因为人们把测试想成「读」就满足那份契约。效果元数据必须描述运行时真正暴露的那个被 wrap 的能力。

REGISTRY = {
    **CONTROL_TOOLS,
    "read_file": ToolSpec(
        name="read_file",
        family="repository",
        purpose="Return the text of one file inside the workspace.",
        use_when=("the implementation under test must be inspected",),
        avoid_when=("the path lies outside the workspace",),
        input_schema={
            "type": "object",
            "properties": {
                "path": {"type": "string", "minLength": 1},
            },
            "required": ["path"],
            "additionalProperties": False,
        },
        output_schema={
            "type": "object",
            "properties": {
                "text": {"type": "string"},
            },
            "required": ["text"],
            "additionalProperties": False,
        },
        effect=Effect.READ_ONLY,
        idempotent=True,
        open_world=False,
        handler=handlers.read_file,
    ),
    "run_tests": ToolSpec(..., effect=Effect.READ_ONLY, idempotent=True),
    "apply_patch": ToolSpec(..., effect=Effect.MUTATING, idempotent=False),
}

TRUSTED_CONTROLS = frozenset(CONTROL_TOOLS)

随后能力章的阶段策略再无需改动就工作。发现阶段,智能体看到的是普通只读工具加上可信控制结果;apply_patch 不是靠指令而被藏起来的——它是从模型所见的普通动作集合里缺席,因此被藏起来。

tool_view(
    PHASE_POLICY["discover"],
    REGISTRY,
    trusted_controls=TRUSTED_CONTROLS,
)  # controls + read_file + run_tests

tool_view(
    PHASE_POLICY["modify"],
    REGISTRY,
    trusted_controls=TRUSTED_CONTROLS,
)  # controls + read_file + run_tests + apply_patch

tool_view(
    PHASE_POLICY["verify"],
    REGISTRY,
    trusted_controls=TRUSTED_CONTROLS,
)  # controls + read_file + run_tests
    flowchart LR
    D["discover<br/>READ_ONLY"] --> MO["modify<br/>MUTATING"] --> VE["verify<br/>READ_ONLY"]
    D -.-> DT["read_file<br/>run_tests<br/>+ control outcomes"]
    MO -.-> MT["read_file<br/>run_tests<br/>apply_patch<br/>+ control outcomes"]
    VE -.-> VT["read_file<br/>run_tests<br/>+ control outcomes"]
    style MT fill:#f6c8c8,stroke:#b04a4a
  

这个变异能力在运行的恰好一个阶段可见。在此之前与之后,关于 patch 对任何东西的提案仍然会过动作边界,并因授权而非靠模型记住工具消失了而被拒绝。

注意注册表里没有什么。没有广泛的 delete_file,没有无限制的 write_file,没有 shell。剩下的变异能力 apply_patch 足够窄,它的目标可以在执行之前被检查并被授权。经典的奖励作弊——删掉失败测试、收集一个绿套件——因此被两层阻止:运行时不暴露一般的删除能力;一个以受保护测试为目标的 apply_patch 提案因授权而被拒绝。

这就是架构差异。智能体不是单纯被指示别碰评估器;能力表面限制了变异可表达的方式,动作边界决定特定变异是否被允许。

这也是接口设计如何在不改变模型权重的情况下改变结果。SWE-agent 报告说在原版 2,294 任务的 SWE-bench 上用 GPT-4 Turbo 得到 12.47% 的 resolve,对比之前 3.8% 的非交互式 retrieval-augmented 基线,并且它的 ablations 把相当大幅度的增益归于 agent-computer interface。[2] 动作表面是一个工程变量,而且是工程师拥有的变量。


5. 先复现失败,再诊断

第一个动作不是编辑。

在触碰任何东西之前跑失败测试,建立基线、给诊断一个具体目标,并证明后来的绿套件代表一个转变,而不是一个永远就能通过的测试。

提案像其他任何一样过动作边界。

decision = prepare_action(model.propose(view), policy, context)

if not isinstance(decision, Accepted):
    raise RuntimeError(
        f"baseline action rejected at {decision.stage}: {decision.message}"
    )

observation = execute_as_observation(decision.action, tools)

# Observation(
#     ok=True,
#     kind="action_result",
#     data={
#         "failed": ["test_pipe_delimiter"],
#         "expected": ["A", "B", "C"],
#         "observed": ["A|B|C"],
#     },
# )

然后运行时问这一步值得取吗。

答案暴露了看起来已经健全的一个接缝。

progress = measure_repair(before, after, observation)

# Progress(
#     task_delta=0.0,
#     evidence_delta=1.0,
#     regression_delta=0.0,
#     integrity_ok=True,
#     measurement_ok=True,
# )

progress.productive  # True

没修成什么。任务 delta 为零,而一个只给修复计分的进度测度会把这一步计分成浪费动作,并启动耐心计数器跑向停转。运行时状态章的 Progress 把与任务相关的证据当作一种运动本身,而 measurement_ok 阻止缺失的仪表化伪装成零进度。

建立真相的步骤可以在不装作修好了什么的情况下挣得自己的位置。

活动不是进度;弄清楚不是 mere activity。


6. 三个完整修复,以及一个看不见真相的分数

探查返回 return text.split(","),把失败连到一个 implementation choice。候选选择机器随后产生三个完整 repair candidates 而不是 commit 到第一个。

winner, candidates = best_of_n(
    prompt=repair_prompt(source, observation.data),
    generate=model.propose_repair,
    score=static_repair_score,
    n=3,
)

三者被选来暴露三种不同 outcome:hard-code the pipe、使用调用方的参数,或改变 nothing that matters。

只有第二个修了抽象。第一个拿一个失败测试 trade another,第三个保留了缺陷却看起来像在做 work。

第一次集成实现暴露了 selection metrics 里更微妙的阶段错误。verified_success 是 bool | None,因为一个候选个人可能合法 remain unverified。但 oracle@N 与 selected verified success 是 evaluation metrics,computing them requires 相关的 external labels to exist。

把 None 当 false 会在实验还没跑之前就造成失败。把 None 从每个度量返回会保留不确定性,但把 phase rule 推进每个调用方。共享 record 因此采取候选选择章建立的更严格 approaches:eligible candidates 若缺 required labels,outcome metrics 仍 refusal to compute。

Immediately after selection:

record = RunRecord(
    task_id="broken-parser",
    candidates=candidates,
    winner_index=candidates.index(winner),
)

record.require_verified_labels()
# ValueError:
# verified labels required for eligible candidates: [...]

这个拒绝是正当的结果。没有任何東西针对隔离环境被执行过;因此信号只有 score——一个从未真正跑过测试套件的评估器所产出的静态代理。

For executable repair candidates, oracle@N is therefore an evaluation metric, not an online selector input. It becomes computable only after 中 中 an independent mechanism supplies the 中 中 required candidate-outcome labels. In this capstone, trajectory search supplies those labels 中 中 through isolated branch previews. ……

Unknown candidate quality must 中 remain unknown until evidence 中 exists.

This is an old problem 中 中 wearing new clothes. Qi et al. found that generate-and-validate repair systems 中 中 could accept many patches that 中 中 satisfy the validating tests without 中 中 being correct repairs.[3] A static proxy is a 中 中 weaker instrument than a test 中 中 suite, and a test suite is 中 中 already weaker than the full 中 中 behavioural truth.


7. 修订必须挣得它的替换,有一条规则处于惰性

The selected repair is already 中 中 functionally correct, and the revision loop runs 中 中 anyway, because “already correct” is a claim the runtime 中 中 cannot yet make.

run = improve(
    task=TASK,
    start=winner,
    critique_fn=model.critique,
    revise_fn=model.revise,
    evaluate_fn=static_repair_score,
    verify_fn=None,
    holds=comma_behaviour_preserved,
    budget=2,
    min_severity=3,
    margin=0.03,
)
run.termination  # Termination.NO_MATERIAL_DEFECT

The critique — that the repair should make 中 中 the delimiter contract explicit — produces a docstring and no 中 中 behavioural change, which the proxy gate accepts 中 中 on a score margin. One revision, then the critic reports no 中 中 material defect and the loop 中 中 stops rather than spending its 中 中 budget rewriting the candidate indefinitely.

The verify_fn=None argument is the joint.

Look at what the acceptance 中 中 rule does when it fires: ……

def accept_revision(old: Candidate, new: Candidate, *, margin: float) -> bool:
    if old.verified_success != new.verified_success:
        return bool(new.verified_success)
    if old.score is None or new.score is None:
        return False
    return new.score - old.score >= margin

The first branch is the 中 中 strongest rule in the revision 中 中 chapter: when fresh external verification distinguishes 中 中 the two versions, the proxy loses. In the capstone it cannot 中 中 fire before branch execution. Both candidates carry verified_success=None, so the comparison falls through 中 中 to the score margin. The rule is not wrong; this stage simply has no 中 中 external evidence yet.

已有两种回复,而只有一种是诚实的。让一个在活的工作区跑测试的 verify_fn 可用,会给修订时改变工作区的规则打开通道,这破坏单次提交。另一种选择是接受 commit 前修订只是代理阶段,把这条事实记入 run report,之后让环境 memiliki 最后的话。压轴 chose 这后者。


8. 搜索在预览上分支,证据活不过分支

Trajectory search answers a different 中 中 question from candidate selection: keep several partial futures alive 中 中 long enough for evidence to 中 中 separate them, then collapse to one. Here it also supplies what 中 中 section 6 needs, because an isolated branch is 中 中 a place where a repair 中 中 candidate can actually be exercised 中 中 without committing it to the 中 中 real workspace.

committed = search_then_commit(
    state=run_state,
    propose=lambda s, width: patch_proposals(s, run.final, width),
    prepare=lambda raw: prepare_action(raw, MODIFY_POLICY, context),
    preview=preview_in_branch,
    evaluate=score_branch,
    execute=lambda action: execute_as_observation(action, tools),
    vote_key=repair_action_signature,
    base_width=2,
    extra_width=3,
    threshold=0.35,
)

repair_action_signature represents the semantic repair choice 中 中 rather than merely the action 中 中 kind. Every candidate here is an 中 中 apply_patch; voting only on that name 中 中 would report unanimous agreement while 中 中 the patches themselves proposed different 中 中 futures.

The preview is where the 中 中 composition becomes real.

def preview_in_branch(state, action: Action) -> BranchResult:
    with branch(state.workspace) as scratch:
        apply_patch(scratch, action)
        report = run_pytest(scratch)
        return BranchResult(
            state_id=state_id(snapshot(scratch)),
            report=report,
        )

Every branch runs the real 中 中 test suite against a real 中 中 isolated copy, so score_branch can use direct environment observations 中 中 rather than relying only on 中 中 a model’s judgement. Once those observations are attributed 中 中 to the branch state and 中 中 interpreted by the branch evaluator, they provide strong branch-local evidence 中 中 for ranking futures and labelling 中 中 candidate outcomes. ……

They are still evidence about 中 中 the branch that produced them, not about the workspace that 中 中 will eventually be committed.

The frontier selects the branch 中 中 that uses the caller’s delimiter 中 中 and records it as B1.

这是第二次 name collision。搜索与验证章各自独立抵达了 members、顺序相同的 EvidenceTier enum。概念上令人鼓舞,code 上却危险:两样结构相同的 enum classes 仍然是不同类型。共享 runtime 把词汇移到一个模块,两个机制都从它 import。

The next joint resolves without 中 中 glue. A branch’s test report is 中 中 bound to b1. The committed workspace will later 中 中 have state id s1. When the verifier asks whether 中 中 branch evidence is current for 中 中 the committed workspace, the answer is no.

evidence_is_current(
    branch_evidence,
    current_state_id=s1,
)  # False

So branch evidence cannot be 中 中 laundered into the final verdict, and no branch-specific exception is 中 中 required.

That is what good composition 中 中 looks like: a state-binding rule written for 中 中 stale evidence also blocks evidence 中 中 from an alternative future.

The branch results still earn 中 中 their cost. They fill in verified_success for the candidate-selection diagnostic, which makes those metrics computable 中 中 after preview.

At initial selection After isolated branch preview
score (static proxy) yes yes
verified_success unknown yes
oracle@N unknown yes
selection_gap@N unknown yes
Evidence usable for the final 中 中 verdict no no

On this run oracle@N and selected_success@N are both 1 and the gap is 0: the generator produced a working 中 中 branch and the proxy happened 中 中 to select one that survives 中 中 isolated testing. Those remain two facts, and a gap of zero 中 中 on one task is not 中 中 evidence that the selector is 中 中 generally good.


9. One authorized mutation

Search has chosen. The patch now crosses the 中 中 action boundary a second time, immediately before the side effect, because authority and preconditions are 中 中 properties of the moment of 中 中 execution rather than of the 中 中 moment of proposal.

The protected evaluation path belongs 中 中 to authorization policy, not to preconditions.

raw = '{"action": "apply_patch", "path": "tests/test_parser.py", ...}'

prepare_action(raw, MODIFY_POLICY, context)

# Rejected(
#     stage=Stage.AUTHORIZATION,
#     message="tests/test_parser.py is a protected evaluation asset",
# )

The proposal is well-formed and 中 中 semantically meaningful. It is rejected because the 中 中 runtime does not grant this 中 中 call authority to modify the 中 中 protected asset.

前置条件回答不同问题。被接受的 parser.py patch 携带它被 prepare 时对准的 workspace identity。在执行前,边界会检查 live workspace 是否 still has 那个 identity。如果 search 运行期间另一个操作改变了 workspace,提案就显得 stale,必须重新考虑,而不是把它 apply 到一个它从未评估过的 state。

authorization:
    may this call modify this path?

precondition:
    is the workspace still the state this proposal assumed?

被接受的 patch 只 mutate parser.py,没有其他。workspace diff 对照这个 expectation 检查,而不是对照 model 对它做了什么;动到任何未批准 path 的 diff 都停掉整个 run,而不是继续奔向一个 convenient PASS。

The environment reports what the 中 中 workspace contains. The agent’s recollection is not 中 中 consulted.


10. Evidence is collected after the 中 中 last mutation

Only now does final verification 中 中 begin, and the ordering is the 中 中 point.

Evidence collected before the final 中 中 mutation describes a state that 中 中 no longer exists.

Each required criterion has a 中 中 protected evidence bar before collection 中 中 begins:

BARS = {
    "pipe": EvidenceBar(
        criterion_id="pipe",
        min_tier=EvidenceTier.ENVIRONMENT,
        accepted_sources=frozenset({"pytest"}),
    ),
    "comma": EvidenceBar(
        criterion_id="comma",
        min_tier=EvidenceTier.ENVIRONMENT,
        accepted_sources=frozenset({"pytest"}),
    ),
    "protected": EvidenceBar(
        criterion_id="protected",
        min_tier=EvidenceTier.ENVIRONMENT,
        accepted_sources=frozenset({"workspace_diff"}),
    ),
}

Then the final workspace 被 snapshotted,每一条证据 bind 到那个 exact identity。下面的 records 是 trusted pytest 与 workspace-diff collectors 之后 outputs;行动 model 不自己构造 Evidence 对象并 select verdict=PASS。

final = snapshot(workspace)
sid = state_id(final)

evidence = (
    Evidence(
        criterion_id="pipe",
        source="pytest",
        tier=EvidenceTier.ENVIRONMENT,
        state_id=sid,
        collected_at=now,
        verifier_id=VERIFIER_ID,
        verifier_version=VERIFIER_VERSION,
        verifier_config_id=VERIFIER_CONFIG_ID,
        verdict=Verdict.PASS,
        payload={"test": "test_pipe_delimiter"},
    ),
    Evidence(
        criterion_id="comma",
        source="pytest",
        tier=EvidenceTier.ENVIRONMENT,
        state_id=sid,
        collected_at=now,
        verifier_id=VERIFIER_ID,
        verifier_version=VERIFIER_VERSION,
        verifier_config_id=VERIFIER_CONFIG_ID,
        verdict=Verdict.PASS,
        payload={"test": "test_default_comma_delimiter"},
    ),
    Evidence(
        criterion_id="protected",
        source="workspace_diff",
        tier=EvidenceTier.ENVIRONMENT,
        state_id=sid,
        collected_at=now,
        verifier_id=VERIFIER_ID,
        verifier_version=VERIFIER_VERSION,
        verifier_config_id=VERIFIER_CONFIG_ID,
        verdict=Verdict.PASS,
        payload={
            "baseline_digest": baseline.get("tests/test_parser.py"),
            "current_digest": final.get("tests/test_parser.py"),
        },
    ),
)

integrity = protected_integrity(
    baseline,
    final,
    protected_paths={"tests/test_parser.py"},
)

result = verify_goal(
    CONTRACT,
    evidence,
    BARS,
    current_state_id=sid,
    integrity=integrity,
)

# GoalVerification(
#     verdict=Verdict.PASS,
#     integrity=IntegrityStatus.CLEAN,
#     coverage=1.0,
#     established=3,
#     total_required=3,
# )

integrity is computed from the baseline 中 中 and final workspace; CLEAN is not a constant supplied 中 中 because the cooperative run looked 中 中 reasonable. The evidence envelope is runtime-minted 中 中 as well: source, tier, state identity, verifier identity, verifier version and verifier configuration 中 中 are properties of the trusted 中 中 collector, not fields the acting model 中 中 is allowed to assert about 中 中 its own work.

The evidence bars stop a 中 中 model’s opinion from clearing a 中 中 criterion. Each required criterion demands environment-tier 中 中 evidence from an accepted source, so a judge’s confident assessment 中 中 that the parser looks correct 中 中 is filtered out before adjudication 中 中 rather than argued with afterwards.

The full run reports one 中 中 structured result:

TASK        Fix pipe-delimited records
RESULT      VERIFIED_SUCCESS
  selected_candidate      use-argument
  revision_accepted       true          (then NO_MATERIAL_DEFECT)
  search_selected         B1
  committed_paths         parser.py
  final_state_id          caa2473f7089d10c
  oracle@N / gap          1 / 0         (from isolated branch previews)
  verification_verdict    PASS
  verification_integrity  CLEAN

Note how late VERIFIED_SUCCESS appears, and how little of the 中 中 pipeline was entitled to produce 中 中 it. The selector did not earn 中 中 it, the revision gate did not 中 中 earn it, the search controller did not 中 中 earn it, and a single green targeted 中 中 test would not have earned 中 中 it either.

Current goal-level evidence bound to 中 中 the final state, above the protected evidence bars 中 中 and accompanied by clean integrity, earned it. Nothing earlier in the system 中 中 has standing to.


11. Now attack the verifier

A successful run proves that 中 中 the mechanisms compose on a 中 中 cooperative path.

It says nothing about whether 中 中 the verifier is any good. The verification chapter’s argument was 中 中 that a verifier is software 中 中 sitting on the attack surface, and Zhong et al. found 323 of 1,968 audited agent-benchmark tasks hackable from 中 中 the task description alone.[5]

The adversarial control is deliberately 中 中 not an action the agent 中 中 can take. It is an external procedure 中 中 that reaches into a workspace 中 中 copy and does what the 中 中 normal action space forbids.

def tamper(workspace: Path) -> None:
    """External control: delete the visible failing test without fixing parser.py."""
    path = workspace / "tests" / "test_parser.py"
    path.write_text(
        drop_test(
            path.read_text(),
            "test_pipe_delimiter",
        )
    )

The parser stays broken. The failing test is removed. Then the real pytest runner 中 中 executes on the tampered repository, and the naive protocol — did the visible suite pass? — becomes green on a repository 中 中 where the requested behaviour was 中 中 never repaired.

    flowchart TD
    T[tampered workspace<br/>parser still broken<br/>protected test deleted] --> P[run real pytest]
    P --> N[naive checker: suite green]
    N --> Q{protected-path<br/>integrity check}
    Q -->|baseline digest matches| C[CLEAN: adjudicate criteria]
    Q -->|protected file changed| V[VIOLATED]
    V --> F[FAIL]
    style F fill:#f6c8c8,stroke:#b04a4a
  

这比一个断言 integrity=VIOLATED 映射到 FAIL 的单元 test 更强。false success 是真实存在的:genuine test runner 报 genuine green suite,而 integrity 层是 preventing 这个 observation 得不到 promoted into a trustworthy goal verdict 的那个东西。

One boundary is important. Protecting the visible test from 中 中 deletion or modification does not solve test overfitting. The agent can still read 中 中 the visible examples, and a patch can satisfy 中 中 them while failing untested behaviour. Smith et al.’s 2015 result is exactly why broader 中 中 correctness claims need independent tests, hidden checks or other evidence 中 中 not used to construct the 中 中 repair.[4]

The capstone makes a narrower 中 中 claim. Its protected criterion tests evaluation integrity: can the acting system remove 中 中 or rewrite the instrument and 中 中 still obtain PASS? It does not claim that 中 中 one immutable visible test suite 中 中 proves universal parser correctness.

Integrity protects what the 中 evidence means; it does not magically 中 make incomplete evidence complete.


12. The verifier failed its first 中 中 adversarial run

On Windows, the attack succeeded. ……

naive checker   PASS
integrity       CLEAN      <- wrong

The protected test had been 中 中 deleted and the integrity check 中 中 reported that nothing had changed. Tracing it took one look 中 中 at the snapshot keys. The baseline recorded the protected 中 中 file as tests\test_parser.py, because str(Path.relative_to()) renders with the platform separator, while the protection policy named 中 中 tests/test_parser.py.

The first integrity helper compared 中 中 two missing lookups. baseline.get("tests/test_parser.py") and final.get("tests/test_parser.py") were both None, and equality manufactured CLEAN.

The failure is not exotic. It is a lookup between 中 中 two spellings of one path. ……

What makes it serious is 中 中 that it produced a silent 中 中 positive integrity result rather than 中 中 UNKNOWN or an error, which is the worst available 中 中 failure mode for a component 中 中 whose job is to detect 中 中 tampering. ……

The fix belongs in the 中 中 representation, and it needs one more 中 中 guard than as_posix() alone.

from pathlib import Path, PurePosixPath

class SnapshotConflict(RuntimeError):
    pass

def canonical_repo_path(value: str) -> str:
    normalized = value.replace("\\", "/")
    path = PurePosixPath(normalized)

    if path.is_absolute() or ".." in path.parts:
        raise ValueError(f"unsafe repository-relative path: {value!r}")

    return path.as_posix()

def _rel(path: Path, root: Path) -> str:
    return canonical_repo_path(
        path.relative_to(root).as_posix()
    )

def snapshot(root: Path) -> dict[str, str]:
    snap: dict[str, str] = {}

    for path in sorted(root.rglob("*")):
        if not path.is_file():
            continue
        if set(path.parts) & IGNORED_PARTS:
            continue

        rel = _rel(path, root)

        if rel in snap:
            raise SnapshotConflict(
                f"multiple files canonicalise to {rel!r}"
            )

        snap[rel] = sha256(path.read_bytes()).hexdigest()

    return snap

Protected-path configuration passes through the 中 中 same canonical_repo_path() function before lookup. The snapshot and the policy 中 中 therefore share a representation rather 中 中 than merely sharing a string 中 中 convention.

The regression tests assert invariants 中 中 rather than the original symptom: ……

  • Windows and POSIX spellings of 中 中 the same repository-relative policy path 中 中 canonicalise identically.
  • Snapshots produced on different platforms 中 中 use the same relative-key representation. ……
  • Protected modification or deletion is 中 中 detected regardless of separator style. ……
  • Missing protected baseline entries produce 中 中 UNKNOWN or configuration failure, never CLEAN.
  • Two entries that canonicalise to 中 中 one path are rejected as 中 中 a snapshot conflict rather than 中 中 silently deduplicated.

That last test matters because 中 中 canonicalisation can close one hole 中 中 by opening another. A normalizer that silently merges 中 中 two distinct inputs would recreate 中 中 the same integrity failure one 中 中 layer lower. ……

This failure belongs in the 中 中 capstone rather than in an 中 中 errata note, because it demonstrates the verification 中 中 chapter’s thesis better than the 中 中 cooperative run does. ……

A verifier is software. Naming a class ProtectedPathVerifier confers nothing. Its own invariants have to 中 中 be tested against adversarial and 中 中 environmental variation.

The evidence boundary became more 中 中 trustworthy because an attack found 中 中 a hole in it. A cooperative-only demonstration would have 中 中 left the verifier confidently wrong 中 中 on one platform.


13. Memory changes the second run 中 中 and is never required for 中 中 the first

The first run reports memory_used=false, and that is the correct 中 中 result rather than a missing 中 中 feature.

An agent that cannot establish 中 中 the truth from the current 中 中 environment has a dependency, not a memory.

A verified PASS 之后,write policy 终于被允许考虑 persistence。它对一条狭窄 record 返回 PERSIST,因为信息 scoped、reusable 且 backed 名 evidence。One verified run is not enough to promote a procedure。memory chapter 在 procedural promotion 之前 requires repeated support,所以压轴 instead stores an episode。

One verified run is not enough to promote a procedure. The memory chapter requires repeated 中 中 support before procedural promotion, so the capstone stores an 中 中 episode instead:

record = MemoryRecord(
    id="mem-target-pipe",
    kind=MemoryKind.EPISODIC,
    content=(
        "A focused test for the pipe criterion is: "
        "pytest tests/test_parser.py::test_pipe_delimiter"
    ),
    created_at=now,
    scope={"repo": "broken-parser"},
    provenance={"run": run_id},
    authority=Authority.VERIFIED_OUTCOME,
    asserts="targeted_test_command",
    asserted_value=(
        "pytest tests/test_parser.py::test_pipe_delimiter"
    ),
    evidence_ids=("ev-pipe",),
)

decision = memory_write_policy(record, verification=result)
assert decision.disposition is WriteDisposition.PERSIST

store.add(record)

VERIFIED_OUTCOME records why this episode deserves 中 中 more authority than a model-generated 中 中 note; it does not turn the 中 中 record into present truth. The evidence_ids make the promotion attributable and 中 中 give memory-management code a stable 中 中 link it can consult if 中 中 supporting evidence is later invalidated. That invalidation policy is separate 中 中 from the memory-to-memory derivation graph, which is carried by derived_from.

The controlled test then requires 中 中 a specific pair of outcomes: ……

Verdict memory_used Targeted test discovery
First run VERIFIED_SUCCESS false discovered from current environment
Second run VERIFIED_SUCCESS true recalled from the verified episode 中 中

Memory that changes nothing is 中 中 storage. Memory a run cannot proceed 中 中 without is a dependency dressed 中 中 as a convenience. The pair above demonstrates that 中 中 recall can reduce repeated discovery 中 中 while the current environment remains 中 中 sufficient to establish the truth 中 中 independently. ……

One budget interaction still needs 中 中 a decision. Retrieval is written as a 中 中 per-decision operation, and search expands several nodes 中 中 per step, so naive composition can multiply 中 中 retrieval cost by the branch 中 中 factor and let memory quietly 中 中 consume the search budget. The capstone retrieves once, at the root, before branching:

memories, conflicts = retrieve_for_decision(
    state=run_state,
    store=store,
    rank=lexical_rank,
    now=now,
)

The assumption is explicit: the retrieved episode describes the 中 中 task and repository, not a branch-local condition. Nothing a branch does changes 中 中 which pytest invocation targets the 中 中 pipe criterion.

Where that assumption fails — where branches diverge enough that 中 中 different memories become applicable — retrieval has to move inside 中 中 expansion and its cost must 中 中 be charged to search.


14. Nine integration findings, and what each one cost 中 中

This table is the chapter’s 中 中 actual result. The successful repair shows that 中 中 the pieces run; the table shows what composition 中 中 demanded.

Joint What collided Resolution Cost
GoalContract Planning feasibility contract vs verification 中 中 achievement contract, same name Rename/alias the planning type PlanContract One type rename
EvidenceTier Search and verification independently defined 中 中 the same vocabulary Move to one shared enum 中 中 One shared type
Verdict Critique union vs PASS/FAIL/PARTIAL/UNKNOWN Rename the revision union CritiqueVerdict One type rename
Candidate success verified_success=None was being collapsed into failure, and verified metrics were requested 中 中 before labels existed Preserve tri-state candidate labels; refuse verified-outcome metrics until isolated 中 中 previews supply the required labels 中 中 One metric invariant plus phase 中 中 rule
Branch evidence Search produces real evidence for 中 中 branch state b1, verifier adjudicates committed state s1 No special case: state binding rejects it Zero; the existing invariant held
Protected path Stable policy was described as 中 中 a precondition Reject protected assets at AUTHORIZATION; reserve PRECONDITION for current-state assumptions 中 中 One stage correction
Memory promotion One verified episode was being 中 中 promoted directly to PROCEDURAL memory 中 中 Store EPISODIC; require repeated support for procedural 中 中 promotion One policy correction
Memory × search budget Per-decision retrieval multiplied by branch 中 中 factor Retrieve once at the root 中 中 under an explicit task-level applicability 中 中 assumption One documented assumption
Path identity Windows and POSIX path spellings 中 中 disagreed inside state/integrity lookup Canonical repository-relative paths plus collision 中 中 checks One real verifier bug

Seven required a type, code or policy correction. One required an explicit budget/applicability assumption. One — branch evidence versus final evidence 中 中 — required nothing, because both mechanisms had independently 中 中 committed to the same state-identity 中 中 rule.

That last category matters as 中 中 much as the failures.

这个关节之所以能不靠特别胶合就成立,是因为两个机制各自独立约定到了同一条语义不变量:证据属于生成它的状态。在裁定 committed workspace 时,共享的 state_id 表示就足以让验证器拒绝 branch-local evidence。

显式表示也把失败定位得更容易,即使它没让接口自动相容。两个独立定义的 EvidenceTier 枚举立刻暴露了类型相撞。AUTHORIZATION/PRECONDITION 区分让受保护路径策略错误可具名化。相比之下,最危险的失败是对着非正式约定的那些,比如两个组件对一个 repository-relative 路径的表示起争执。

A shared vocabulary is not 中 中 automatically a shared type, and an explicit type is 中 中 not automatically a shared invariant.

路径 bug 是最小也最锐利的例子。两个组件在人话短语 tests/test_parser.py 上达成一致,却对一个 repository-relative path 是什么起了争执。那偏差本身只会是一个平时的 lookup bug。验证器失败来自下一步:两次失败的 lookup 都返回 None,等号把缺失信息转化成了正面的完整性结论。

The model did not reason 中 中 badly. Software on two sides of 中 中 a boundary represented the same 中 中 object differently, and the verifier then collapsed 中 中 unknown into equal. The bug therefore violated two 中 中 of the book’s central rules 中 中 at once: shared objects need shared representations, and missing evidence must never 中 中 manufacture certainty.


15. What one repaired repository does 中 中 not establish

The result is narrow. Being precise about the narrowness 中 中 is part of the claim.

It does not show that 中 中 the agent repairs arbitrary repositories. SWE-bench contains 2,294 software-engineering problems drawn from real 中 中 GitHub issues and pull requests 中 中 across twelve Python repositories, and resolving them frequently requires 中 中 coordinated changes across multiple functions, classes and files.[1] One function in one file 中 中 is a miniature of that 中 中 problem, chosen so the mechanisms are 中 中 visible rather than so the 中 中 task is hard.

It does not show that 中 中 a live model behaves as 中 中 the recorded fixture does. The capstone holds model behaviour 中 中 constant on purpose, because it is testing whether 中 中 the runtime can represent authority, state, isolation and evidence. A live model would add 中 中 variance to candidate generation, critique and routing, which is a different experiment.

Runtime correctness and model 中 quality are different experimental 中 variables.

A stronger model should improve 中 中 proposal quality. It should not be asked 中 中 to rescue a runtime that 中 中 cannot tell a branch from 中 中 the committed workspace or UNKNOWN 中 中 from false.

Nor does the capstone show 中 中 that lexical capability retrieval scales 中 中 past a handful of tools, that this small search controller 中 中 is compute-optimal, that one verified episode should 中 中 become a procedure, or that most useful tasks 中 中 have deterministic oracles. Repository repair was chosen partly 中 中 because important parts of it 中 中 are externally checkable.

What it does establish is 中 中 narrower and falsifiable.

The mechanisms can compose without 中 中 collapsing the distinctions the book 中 中 spent ten chapters building:

  • A proposal is still not 中 中 authority.
  • A plan is still not 中 中 runtime state.
  • Activity is still not progress. ……
  • Exposure is still not authorization. ……
  • A retrieved record is still 中 中 not present truth.
  • A branch score is still 中 中 not final verification.
  • Branch evidence is still evidence 中 中 about the branch that produced 中 中 it.
  • A green suite is evidence, but not automatically sufficient evidence 中 中 of goal satisfaction or evaluation 中 中 integrity.
  • UNKNOWN is still different from 中 中 false.

Had those distinctions collapsed under 中 中 integration, the book would have been 中 中 pedagogically tidy and architecturally false.


16. Where the model ended up 中 中 ……

There is still a language 中 中 model in this system, and it does substantial work. It proposes diagnoses, candidate repairs, critiques, revisions and capability choices.

What changed is everything around 中 中 those proposals.

    flowchart TD
    subgraph M[model contributes]
        M1[defect hypotheses]
        M2[candidate repairs]
        M3[critiques and revisions]
        M4[capability proposals]
    end

    subgraph R[runtime owns]
        R1[goal and plan contracts]
        R2[state and reducers]
        R3[action space and exposure]
        R4[authorization and preconditions]
        R5[budgets, recovery and termination]
        R6[memory and search policies]
        R7[evidence bars, integrity and adjudication]
    end

    subgraph E[environment supplies]
        E1[workspace effects]
        E2[test and tool observations]
        E3[current external state]
    end

    M --> R
    R --> E
    E --> R
  

Everything leaving the model’s column 中 中 is a proposal, hypothesis or judgement.

Everything leaving the environment’s column 中 中 is an observation, not automatically a fact or 中 中 sufficient evidence of goal satisfaction. The runtime decides which observations 中 中 establish state, which actions may execute, and which observations or checks 中 中 may enter the protected evidence 中 中 path. The verifier decides what the 中 中 resulting admissible evidence earns.

That is the full boundary 中 中 the book has been constructing: ……

The model proposes. The runtime controls execution. The environment supplies observations. The verifier decides what evidence 中 中 those observations support and what 中 中 that evidence earns.

None of that makes the 中 中 model unimportant. It makes its uncertainty legible.

That is the book’s engineering 中 中 thesis, and the capstone is the 中 中 first place it becomes an 中 中 integrated result rather than a 中 中 preference:

Move as much correctness as possible out of probabilistic model behaviour and into explicit, inspectable software — without pretending the remaining probabilistic parts have disappeared.

They have not disappeared. The model still writes the 中 中 patch. ……

The difference is that when 中 中 this run reported VERIFIED_SUCCESS, the claim rested on trusted 中 中 checks and environment observations collected 中 中 against a criterion-relevant workspace identity, converted into evidence by collectors 中 中 the acting model did not 中 中 control, and adjudicated against a success 中 中 contract fixed before optimisation, protected evidence bars and an 中 中 integrity policy.

And when the same machinery 中 中 was attacked, it failed on one platform 中 中 for a reason that had 中 中 nothing to do with model 中 中 intelligence.

That is the more useful 中 中 result.

A system built this way 中 中 can still be wrong. What changes is that more 中 中 of its wrongness has a 中 中 location: a type, a stage, a state identity, a policy, an evidence source, a violated invariant. That makes the failure findable, nameable and fixable — which is what engineering can 中 中 actually promise.


研究渊源

This chapter adds no new 中 中 agent mechanism, so the references here concern 中 中 the two questions a capstone 中 中 raises: how small the repository-repair demonstration 中 中 is relative to real software-engineering 中 中 work, and how much trust passing 中 中 tests deserve.

  1. Jimenez et al. — SWE-bench: Can Language Models Resolve Real-World 中 中 GitHub Issues? (ICLR 2024). Introduces 2,294 software-engineering problems drawn from real 中 中 GitHub issues and pull requests 中 中 across twelve Python repositories, and notes that resolution frequently 中 中 requires coordinated changes across multiple 中 中 functions, classes and files; cited in section 15 for the scale the capstone 中 中 deliberately does not reach. https://arxiv.org/abs/2310.06770

  2. Yang et al. — SWE-agent: Agent-Computer Interfaces Enable Automated Software 中 中 Engineering (NeurIPS 2024). Reports 12.47% resolution on the original 2,294-task SWE-bench with GPT-4 Turbo, compared with the previous 3.8% non-interactive retrieval-augmented result, and uses ablations to show 中 中 that agent-computer-interface design materially affects 中 中 performance; cited in section 4 because action-space and feedback design 中 中 are engineering variables rather than 中 中 wrappers. https://arxiv.org/abs/2405.15793

  3. Qi et al. — An Analysis of Patch Plausibility 中 中 and Correctness for Generate-and-Validate Patch 中 中 Generation Systems (ISSTA 2015). Distinguishes patches accepted by a 中 中 validating test suite from correct 中 中 repairs and finds the accepted 中 中 set can contain many incorrect 中 中 patches; cited in section 6 for why a proxy — and even a test suite 中 中 — must not be conflated with 中 中 full correctness. https://doi.org/10.1145/2771783.2771791

  4. Smith, Barr, Le Goues and Brun — Is the Cure Worse Than 中 中 the Disease? Overfitting in Automated Program Repair 中 中 (ESEC/FSE 2015). Studies test-suite overfitting in automated 中 中 repair and shows why passing 中 中 the tests used during repair 中 中 does not by itself establish 中 中 general correctness; cited in section 11 to bound what the protected 中 中 visible test can prove. https://doi.org/10.1145/2786805.2786825

  5. Zhong et al. — Hardening Agent Benchmarks with Adversarial 中 中 Hacker-Fixer Loops (2026). Audits 1,968 tasks across five terminal-agent benchmarks, finds 323 hackable from the task description 中 中 alone, and introduces an adversarial hacker-fixer-solver 中 中 loop for verifier hardening; cited for the adversarial control 中 中 in section 11. https://arxiv.org/abs/2606.08960

The new evidence in this 中 中 chapter is implementation and integration 中 中 evidence rather than a research 中 中 result: the controlled runtime composes on 中 中 one repository-repair fixture; the final integration review surfaces 中 中 nine interface findings across the 中 中 chapter APIs; and the adversarial run directly 中 中 exposed a cross-platform integrity bug 中 中 that required hardening the state 中 中 representation rather than weakening the 中 中 test.


The construction is complete

The book began with one 中 中 question:

Who decides what happens next?

The answer became progressively less 中 中 mysterious.

The model proposes. Software represents the available actions, the state, the plan, the budget, the memory, the search frontier and the 中 中 evidence bar. The environment returns observations. Verification decides what those observations 中 中 justify saying about the goal.

Reliable agency does not require 中 中 pretending the probabilistic parts disappeared. ……

It requires putting those parts 中 中 inside a system that can 中 中 distinguish a proposal from permission, intention from state, activity from progress, memory from truth, promise from proof, and confidence from evidence.

That is the construction.