← Agents From First Principles

规划与执行

把打算做的多步工作表示为可检视的计划,在任何东西执行之前校验其结构与语义,并让观察而非习惯来决定剩余路线何时必须改变。

批评循环一次只处理一件事。它假设任务已经作为一个我们可以持有、检视和改进的候选存在。

有些任务没有可持有的草稿。

检查一个项目,复现失败的测试,找出原因,打补丁,重跑相关测试,并报告改变了什么。

没有哪个狭窄动作能负责任地完成那个目标,而且这些动作互相约束。在诊断之前打补丁是穿着工作外衣的猜测,而在观察到一个通过的测试之前报告成功是一个关于世界的断言,而运行中没有任何东西支持它。更糟的是,如果执行揭示某个假设错了,剩余的路线也可能一起错。一个独立选择每个动作的运行时可以对新观察作出反应,但没有对预期路线的显式表示,它就没有具体的东西可以把改变后的世界与之比较。

所以我们需要在执行打算做的工作之前表示它。那个表示就是一个计划。

这个词带有包袱,所以值得精确一点。一份流畅的步骤列表在任何有用的意义上都不是计划:模型可以产出读起来有序的东西,同时遗漏一个依赖、假设一个不存在的资源,或把一个不可逆动作放在本该证明它的证据之前。

听起来像计划的文字不给运行时任何可检查的东西。

所以这里的定义更强:

计划是一个关于当前状态如何到达目标的、可被否证的假设。

可被否证是承重的词。计划通过暴露足够结构让运行时能在执行前拒绝它,并通过声明足够证据让后续观察能告诉我们它何时不再是真的,来收回自己的成本。

    flowchart TD
    G["目标 + 已知事实"] --> P["规划器"]
    P --> PL["被提议的计划"]
    PL --> V{"结构与<br/>语义有效?"}
    V -->|no| R["拒绝,或<br/>拒绝该任务"]
    V -->|yes| S["选择一个就绪的步骤"]
    S --> E["执行器"]
    E --> O["观察"]
    O --> C{"剩余步骤是否<br/>依赖已被撤回的事实?"}
    C -->|no| S
    C -->|yes| P

    classDef model fill:#fbe3cd,stroke:#b8712c,color:#000
    classDef runtime fill:#d8e6f4,stroke:#2b6cb0,color:#000
    classDef execution fill:#eef2f7,stroke:#6b7280,color:#000
    class P model
    class V,S,C,R runtime
    class E execution
  

颜色分离的是责任,而不是假装每个组件都是模型调用。规划器是概率性提案组件。蓝色方框是对显式数据的运行时决策。执行器是执行组件:它可以调用确定性工具、模型辅助的能力,或某种混合,但它不拥有路线。有三条约束重要。规划器在规划时不产生副作用,执行器从不重写路线,且运行时从不因为一个模型产出了计划就把它当作权威。

最后这条正是动作边界对一个被提议的动作所持的立场,现在应用到被提议的一串动作上。


1. 何时值得构建一个计划

对于一个动作就能完成的任务,规划增加延迟、token,以及第二件可能出错的东西:

action = decide(state)
observation = execute(action)

当成功取决于动作之间的关系而不仅仅是数量时,规划才划算。六个独立动作可能只需要普通的编排。三个动作中第二个消费第一个产出的证据,就需要把那个依赖写在运行时能读到的地方。问题不是存在多少步骤,而是正确性是否依赖于它们之间运行时必须保持的关系。

这个区分很容易丢失,因为模型能把一个目标分解成看起来像规划的散文:

  1. 检查项目
  2. 修复问题
  3. 测试它
  4. 报告成功

确实获得了某些东西:工作被命名了。但每一个决定路线是否可执行的问题仍然悬而未决。第二步开始前必须知道什么?第一步应该产出什么证据?什么让第三步是就绪的而非仅仅是下一个?哪个观察会告诉我们路线已经死了?

比较说同一件事的两种方式。用散文:

在诊断之前复现 bug

用数据:

diagnose.depends_on = ("reproduce",)

第一个是对读者的建议。第二个是运行时可以强制的约束,而两者之间的差距就是本书的绝大部分。

如果正确性依赖于某种关系,就表示那个关系。


2. 计划步骤是一个可能错的断言

一个只携带指令的步骤只是带额外语法的句子。要可检查,它必须声明它等待什么、需要什么、以及留下什么:

from dataclasses import dataclass

@dataclass(frozen=True)
class PlanStep:
    id: str
    action: str
    depends_on: tuple[str, ...] = ()
    requires: tuple[str, ...] = ()
    produces: tuple[str, ...] = ()
    expected_evidence: str = ""

@dataclass(frozen=True)
class Plan:
    steps: tuple[PlanStep, ...]

requires 和 produces 命名事实而不是描述它们,而正是那个选择使本章其余部分成为可能。写成 "the failure has been reproduced" 的前置条件是散文:运行时可以存储和展示它,但无法可靠地把它与执行状态匹配。写成事实名 failure_reproduced,由更早的步骤产出、由这一步消费,它就成为校验器可以在执行前检查、观察之后可以确立或撤回的东西。

已声明事实与已观察事实之间的区分重要。produces=("failure_reproduced",) 是关于成功执行应该确立什么的机器可检查断言。expected_evidence 是那份确立在轨迹中应该是什么样子的、人类可读的解释;它本身不把任何东西提升进状态。运行时不能仅仅因为步骤返回 ok=True 就添加 failure_reproduced。本章后面我们要求观察本身携带实际被确立的事实。

reproduce = PlanStep(
    id="reproduce",
    action="Run the focused failing test and capture its output.",
    requires=("repository_available",),
    produces=("failure_reproduced", "error_trace"),
    expected_evidence="a reproducible failure with a concrete error trace",
)

diagnose = PlanStep(
    id="diagnose",
    action="Identify the smallest code path that explains the failure.",
    depends_on=("reproduce",),
    requires=("failure_reproduced", "error_trace"),
    produces=("root_cause",),
    expected_evidence="a root-cause hypothesis tied to observed code and failure output",
)

列表把一个全序强加到往往没有全序的工作上。检查日志和运行失败的测试都需要仓库,彼此都不需要,而两者都必须在诊断开始前完成。作为列表,一次检查会任意地被挡在另一次之后,且没有任何东西区分哪些顺序是必需的、哪些是偶然的。

    flowchart LR
    T["测试<br/>→ failure_reproduced"]
    L["日志<br/>→ log_evidence"]
    D["诊断<br/>→ root_cause"]
    P["打补丁<br/>→ patch_applied"]
    V["验证<br/>→ tests_pass"]

    T --> D
    L --> D
    D --> P
    P --> V
  

依赖把计划变成一个小有向无环图。不需要图库来收集收益:一个 depends_on 元组和一次拓扑遍历就够了,而保持它这么小意味着整个结构在一行日志里仍然可读。


3. 计划与执行状态是不同的对象

计划说我们打算做什么。执行状态说发生了什么。把它们折叠成一个可变对象诱人且昂贵。

from dataclasses import dataclass, field

@dataclass
class ExecutionState:
    completed: set[str] = field(default_factory=set)
    observations: dict[str, Observation] = field(default_factory=dict)
    facts: set[str] = field(default_factory=set)
    outcome: str | None = None

facts 是运行时对"已经确立了什么"的小型工作模型。每个步骤的 requires 字段都对照它被检查。它以环境或任务契约提供的事实开始,且只从有观察支持的事实增长。计划可以预测一个步骤会产生什么;执行状态记录这次运行实际挣到了什么。

随着执行推进而改变计划,那么一次失败的运行就无法被诊断,因为记录我们意图的产物已经被我们做的事覆盖了。然后三种相当不同的失败留下相同的轨迹:路线错了;路线对了但某个步骤执行糟糕;路线对了但运行时在运行中静默改变了它。

计划 = 预期路线。执行状态 = 那条路线的观察历史。

运行时状态一章让这个状态持久化并给它进度与停止规则。这里我们只需要足够多来检查前置条件并记录每个步骤留下了什么。


4. 结构校验:运行时能证明什么

动作边界确立了模型输出是一个提案而非指令。一个生成的计划同样是提案,而且是一个大得多的,所以同一道闸门属于它前面。

有些缺陷无需知道任何关于领域的东西就可判定:重复的 id、依赖一个不存在的步骤、一个步骤依赖自身、一个环、一个留空的必需字段。这些就是动作边界所称的 schema 失败,即无论含义如何对象都是畸形的,所以我们复用那个异常而不是为计划发明一套平行词汇。

def _topological_order(plan: Plan) -> list[PlanStep]:
    by_id = {step.id: step for step in plan.steps}
    order: list[PlanStep] = []
    visiting: set[str] = set()
    visited: set[str] = set()

    def visit(node: str) -> None:
        if node in visiting:
            raise SchemaError(f"dependency cycle reached at {node!r}")
        if node in visited:
            return

        visiting.add(node)
        for dependency in by_id[node].depends_on:
            visit(dependency)
        visiting.discard(node)
        visited.add(node)
        order.append(by_id[node])

    for step_id in by_id:
        visit(step_id)

    return order

def validate_plan_structure(plan: Plan) -> None:
    ids = [step.id for step in plan.steps]
    duplicates = {i for i in ids if ids.count(i) > 1}

    if duplicates:
        raise SchemaError(f"duplicate step ids: {sorted(duplicates)}")

    known = set(ids)

    for step in plan.steps:
        if step.id in step.depends_on:
            raise SchemaError(f"{step.id}: depends on itself")

        unknown = set(step.depends_on) - known
        if unknown:
            raise SchemaError(f"{step.id}: unknown dependencies {sorted(unknown)}")

        if not step.action.strip():
            raise SchemaError(f"{step.id}: empty action")

        if not step.expected_evidence.strip():
            raise SchemaError(f"{step.id}: no expected evidence declared")

    _topological_order(plan)

这无法显示一个计划会工作。它显示某一类计划不可能工作,这比乍听更有价值:生成的依赖图中的环是常见失败,而且是完全静默的。没有这个检查的运行时通过到达一个没有任何步骤就绪的位置来发现它,而那恰恰也是成功完成的样子。

这个检查把一次以歧义结束的运行变成在第一次工具调用之前抛出的错误。


5. 语义校验:结构抓不到的东西

考虑一个复现故障、删除失败的测试、并报告测试现在通过了的计划。上一节的每项检查都通过:id 唯一、依赖真实、无环、每个字段都被填充。它也是一个旨在击败目标而非达成目标的计划,而再多的结构检查也不会这么说,因为缺陷存在于步骤的含义中。

语义检查需要一份关于目标实际要求什么的陈述。运行时无法从目标字符串推断它,而要求规划器检查自己的计划把同一个分布放在测试的两侧。所以要求被单独声明,作为任务而非路线的属性:

@dataclass(frozen=True)
class GoalContract:
    required: frozenset[str] = frozenset()
    forbidden: frozenset[str] = frozenset()
    must_precede: frozenset[tuple[str, str]] = frozenset()
    given_facts: frozenset[str] = frozenset()
    obtainable_facts: frozenset[str] = frozenset()

然后用契约检查一个计划就是四个问题,而第四个正是 requires/produces 设计存在的理由:

def _ancestors(plan: Plan) -> dict[str, set[str]]:
    closure: dict[str, set[str]] = {}

    for step in _topological_order(plan):
        ancestors = set(step.depends_on)

        for dependency in step.depends_on:
            ancestors |= closure[dependency]

        closure[step.id] = ancestors

    return closure


def validate_plan_semantics(plan: Plan, contract: GoalContract) -> None:
    ids = {step.id for step in plan.steps}
    by_id = {step.id: step for step in plan.steps}

    missing = contract.required - ids
    if missing:
        raise SemanticError(f"required steps absent: {sorted(missing)}")

    banned = contract.forbidden & ids
    if banned:
        raise SemanticError(f"forbidden steps present: {sorted(banned)}")

    ancestors = _ancestors(plan)

    out_of_order = sorted(
        (before, after)
        for before, after in contract.must_precede
        if before in ids
        and after in ids
        and before not in ancestors[after]
    )
    if out_of_order:
        raise SemanticError(f"ordering violations: {out_of_order}")

    for step in plan.steps:
        available = set(contract.given_facts)

        for ancestor_id in ancestors[step.id]:
            available |= set(by_id[ancestor_id].produces)

        unmet = set(step.requires) - available
        if unmet:
            raise SemanticError(
                f"{step.id}: requires facts not supplied by its dependency "
                f"ancestors or initial state: {sorted(unmet)}"
            )

最后那个检查问每个必需事实是存在于初始状态中,还是由消费它的步骤的某个依赖祖先声明。仅在某个有效拓扑序中把一个无关的产出者放得更早,绝不能满足一个计划从未表示的依赖。

因此一个修补它从未定位到的代码的计划,在任何工具运行之前就失败,并指出缺失的关系,而非依赖彼此独立步骤的偶然顺序。

一份契约不必完整才有用。四个必需的规划里程碑和一个禁止的里程碑已经能抓住"删除测试"那个计划。在这个小型实现中那些里程碑使用规范步骤 id,例如 reproduce、diagnose、patch 和 verify;生产系统可以把它们表示为类型化的步骤种类而非依赖任意的模型生成名称。

契约也不是用户目标的最终验证器。它描述规划义务:必须出现的工作、必须不出现的工作、顺序约束,以及路线可以依赖的事实。后续验证仍必须决定结果环境状态是否真的满足目标。


6. 不可行是一个结果,不是一次失败

一个没有部署凭据却被要求发布版本的规划器有三个选择。它可以发明步骤直到输出看起来像工作。它可以产出一个欢快运行直到最后一步失败的计划。或者它可以报告从这里不存在路线。

只有第三个诚实,也只有第三个可行动。

@dataclass(frozen=True)
class PlanningFailure:
    reason: str
    unsatisfiable: tuple[str, ...]

PlanResult = Plan | PlanningFailure

那个类型是拒绝变得可表示的地方。规划流水线应当被允许返回一条可接受的路线,或一份"当前没有可用路线"的结构化陈述。在这个实现中运行时可以从任务的事实与能力契约推导那个拒绝,而非信任规划器宣布自己无法继续。

因此 PlanResult 属于规划边界,即使面向模型的 propose() 函数仍然发出一个候选 Plan。调用方必须处理两种结果:一条可以尝试的路线,和一个当前不可行的任务。

检测复用事实词汇,问一个与语义检查不同的问题:

def refuse_if_impossible(
    plan: Plan,
    contract: GoalContract,
) -> PlanningFailure | None:
    reachable = contract.given_facts | contract.obtainable_facts
    needed = {fact for step in plan.steps for fact in step.requires}
    impossible = tuple(sorted(needed - reachable))

    if not impossible:
        return None

    return PlanningFailure(
        reason="required facts cannot be produced by any available capability",
        unsatisfiable=impossible,
    )

语义检查问这个计划是否连贯地安排了它的前置条件。可行性针对被声明的能力模型问一个更宽的问题:这条路线所需的事实是已经给出,还是能通过运行时已知的能力获得?一条路线可以结构干净,而在那个模型下仍不可行,因为它最终依赖某个没有已声明能力能确立的事实。

那个区分改变了我们报告的失败。如果 deployment_credentials 既未给出也未声明为可获得,那么在当前能力模型下要求规划器给出一条措辞不同的部署路线是白费功夫。规划子系统应当显式返回缺失的前置条件,而非假装另一次采样创造了运行时并不拥有的能力。

    flowchart LR
    PP["被提议的计划"] --> S{"结构"}
    S -->|SchemaError| SR["畸形:<br/>环、未知 id、<br/>空字段"]
    S -->|ok| F{"可行性"}
    F -->|PlanningFailure| FR["当前能力下<br/>无可接受路线:<br/>必需事实无法获得"]
    F -->|ok| M{"语义"}
    M -->|SemanticError| MR["格式良好但错误:<br/>禁止步骤、缺失<br/>验证、未满足的顺序"]
    M -->|ok| X["执行"]
  

识别不可行是一种能力而非缺失的能力,并作为能力被度量:Agent Planning Benchmark 在长程规划与损坏工具之外测试不可解任务和有校准的拒绝,把它评估的模型中拒绝校准作为系统性弱点报告。[5]

一个无法表示拒绝的运行时无法展示它,无论模型本会说什么。


7. 规划器提案,执行器执行

规划器的输出是数据,不是动作。执行器的输入是一个被批准的步骤,不是目标。两半都是约束,且各自买到一个诊断。

让规划器在规划时产生副作用,那么规划质量就不再可与执行质量分离,因为我们将要评分的那个计划不再作为一个对象存在:它已经溶进轨迹里。给执行器不受约束的权威去追求整个目标,那么它可能引入不出现在任何被批准路线中、也不被任何显式规划记录所证成的动作。

一个狭窄的执行契约守住了这条线:

Execute only the step you were given.

Return:
- what was attempted
- what was observed
- whether the expected evidence was produced
- any fact a remaining step depends on that no longer holds

假设被批准的步骤是运行那个聚焦的失败测试,而执行器发现夹具损坏了。先重写夹具很可能是对的。静默地做才是问题,因为运行时仍在据以校验的那个计划不再描述正在发生的事,而本该证明一条新路线的那个发现被埋在工具日志里。

修复不是禁止那个发现,那会让执行器故意变蠢。它是把发现路由到执行已经拥有的观察通道:

Observation(
    ok=False,
    kind="precondition_withdrawn",
    data={"step": "reproduce", "fact": "fixture_valid"},
)

def withdrawn_facts(observation: Observation) -> set[str]:
    if observation.kind != "precondition_withdrawn":
        return set()
    return {observation.data["fact"]}

复用动作边界的 Observation 类型使这几乎免费。执行已经有一条通道用来报告改变运行时对当前状态可以相信什么的信��。一个被撤回的前置条件恰恰就是:一个计划所依赖、而新观察不再支持的事实。


8. 让使路线失效的证据触发重新规划

规划是针对规划器运行时已知的事实进行的。执行产生新事实,也可以使路线所依赖的事实失效。每次观察后都重新规划会把普通执行变成对计划的重复重采样,所以这里的触发器刻意更窄:

这次观察是否使剩余路线所需的某个事实失效了?

新事实可以让额外的计划工作就绪,而不需要新计划。重新规划保留给更强的情况:被声明的路线从运行时现在拥有的状态出发已无法到达。

def ready_steps(plan: Plan, state: ExecutionState) -> list[PlanStep]:
    return [
        step
        for step in _topological_order(plan)
        if step.id not in state.completed
        and set(step.depends_on) <= state.completed
        and set(step.requires) <= state.facts
    ]

def reachable_route(
    plan: Plan,
    state: ExecutionState,
) -> tuple[set[str], set[str]]:
    """Facts and steps the remaining route could reach if future steps succeed."""
    facts = set(state.facts)
    hypothetically_completed = set(state.completed)
    remaining = [
        step for step in _topological_order(plan)
        if step.id not in state.completed
    ]

    changed = True
    while changed:
        changed = False
        for step in remaining:
            if step.id in hypothetically_completed:
                continue
            if not set(step.depends_on) <= hypothetically_completed:
                continue
            if not set(step.requires) <= facts:
                continue

            hypothetically_completed.add(step.id)
            facts |= set(step.produces)
            changed = True

    return facts, hypothetically_completed

def invalidated_steps(plan: Plan, state: ExecutionState) -> tuple[PlanStep, ...]:
    _, reachable_steps = reachable_route(plan, state)
    return tuple(
        step
        for step in plan.steps
        if step.id not in state.completed
        and step.id not in reachable_steps
    )

第二个比看起来更微妙,搞错它代价高昂。一个事实尚未出现在 state.facts 中的步骤通常没有坏:它可能在等待更早的某个剩余步骤确立它们。但简单地把每个未来的 produces 集合做并集太乐观,因为两个被阻塞的步骤可以表面上互相满足。

因此 reachable_route() 计算一个小不动点。它从已经确立的事实和已完成步骤出发,然后反复标记一个剩余步骤为假设可达,仅当它的被声明依赖与必需事实都可能得到满足。该步骤被声明的产出随后被加入下一轮的假设事实集合。只有当这个闭包无法再到达某个剩余步骤时,该步骤才被判定失效。

那些假设产出都不进入 ExecutionState。它们只存在于可达性计算内部;运行时事实仍然需要实际观察。

那个计算仍然在被声明的计划事实上推理,而非预测工具是否会成功。这是有意的。它问的是路线从当前状态出发是否在结构上仍然可能,而非未来执行是否被保证。

重新规划昂贵且有方差。一个每次观察后都重新规划的系统,会把预算中更多部分花在修改意图而非执行意图上,而每个新计划都是从一个已经产出一条它愿意放弃的路线的分布中来的另一次采样。ReWOO 从另一个方向得出了相关结论,把计划提前构建,以阻止推理在每次工具调用上被重复。[2] 本章保留了那个设计放弃的一点东西:观察仍然能否证剩余路线。

当检查触发时,应该把运行而不是目标交给规划器。只拿到原始目标的重新规划器会产出与原计划接近的东西,因为那是它第一次拥有的输入。它需要已完成的步骤及其产生的事实、失败的那一步、被撤回的事实,以及仍然适用的约束。

从当前观察到的状态构建一条路线,保留仍然有效的已完成工作。

保留需要一个身份规则。ExecutionState.completed 记录步骤 id,所以一个修订后的计划不能把某个已完成步骤的 id 复用于不同工作。如果 diagnose 已经完成,重新规划器不能把 diagnose 重新定义为检查另一个子系统并指望调度器注意到;调度器会正确地把那个 id 当作已完成。因此已完成的 id 属于已完成的工作。实质不同的工作需要新 id,而保留的已完成步骤必须保持其含义。

那使重新规划质量可度量而非凭印象:

def redundant_remaining_work(
    state: ExecutionState,
    revised: Plan,
) -> tuple[str, ...]:
    return tuple(sorted(
        step.id
        for step in revised.steps
        if step.id not in state.completed
        and step.produces
        and set(step.produces) <= state.facts
    ))

把一个已完成步骤保留在修订计划中本身不是重复工作:ready_steps() 会跳过已在 state.completed 中的 id。更有用的信号是一个剩余步骤,其被声明的产出已被确立。在这个事实模型下,那是新路线看起来准备执行、尽管其结果已经持有的工作。

因此 redundant_remaining_work() 是一个诊断而非证明。一个步骤可能有不以其事实表示的副作用。但一个反复调度许多产出已被确立的剩余步骤的重新规划器,很可能是在重新生成路线而非只修补改变的部分。


9. 把失败归因到规划器或执行器

这是整项分离所启用的诊断,也是接受额外活动部件的理由。

一个 patch → report success 的计划即使执行完美无缺,也可能是规划失败,尽管执行器得分完美。一个 reproduce → diagnose → patch → verify 的计划通过规划契约,然后在应用补丁时死掉,首先指向执行而非规划。

限定词重要,因为规划得分总是相对于评分所用的契约。一个弱契约可以批准一条仍然无法达成用户实际目标的路线。

端到端成功把两者折叠成一个数字,而优化那个数字的团队无法分辨该改变哪个组件。这正是 Agent Planning Benchmark 所围绕构建的问题:只报告端到端成功的评估使得难以确定失败源自规划还是执行。[5]

层 它度量什么 这里的失败看起来像
规划器 必需步骤召回、禁止步骤规避、顺序正确性、拒绝校准 路线遗漏验证,或依赖某个没有能力能产生的事实
执行器 给定有效步骤的完成情况、产出证据、计划外动作率 路线没问题而补丁编译不过
系统 目标成功、模型调用、工具调用、重新规划、重复工作、延迟 上面两者之一,这就是为什么只看系统数字诊断不出任何东西

表格没抓到的第四种失败,是最常被误诊为模型问题的那种:

    flowchart TD
    F["运行失败"] --> A{"计划通过<br/>契约了吗?"}
    A -->|no| PLAN["规划器缺陷:<br/>离线评分计划"]
    A -->|yes| B{"步骤产出了<br/>它们声明的证据吗?"}
    B -->|no| EXEC["执行器缺陷:<br/>对着冻结的计划重跑"]
    B -->|yes| C{"运行中有<br/>事实被撤回吗?"}
    C -->|yes| ENV["环境已变动:<br/>度量重新规划质量"]
    C -->|no| CON["契约太弱:<br/>目标需要一条<br/>没人写下来的约束"]
  

一个被声明的计划被正确执行、所有被声明的证据都出现了,而用户目标仍失败的运行,是规划契约或后续验证规格遗漏了重要东西的强证据。那应该在责怪规划器或执行器之前被调查,因为更强的提示词无法恢复一个运行时从未表示的要求。


10. 不执行就为计划评分

要弄清规划器是否改进了,把执行冻结在实验之外。构建正确约束已知的任务,索取一个计划,并给这个计划打分。

为校验而写的 GoalContract 已经是答案钥匙:

CASES = {
    "parser-fix": GoalContract(
        required=frozenset({"reproduce", "diagnose", "patch", "verify"}),
        forbidden=frozenset({"delete_test", "skip_test"}),
        must_precede=frozenset({
            ("reproduce", "diagnose"),
            ("diagnose", "patch"),
            ("patch", "verify"),
        }),
        given_facts=frozenset({"repository_available"}),
        obtainable_facts=frozenset({
            "failure_reproduced", "error_trace",
            "root_cause", "patch_applied", "tests_pass",
        }),
    ),
}

@dataclass(frozen=True)
class PlanGrade:
    admissible: bool
    required_recall: float
    forbidden_present: tuple[str, ...]
    order_violations: tuple[tuple[str, str], ...]

def grade_plan(plan: Plan, contract: GoalContract) -> PlanGrade:
    ids = {step.id for step in plan.steps}
    required_recall = (
        len(contract.required & ids) / len(contract.required)
        if contract.required
        else 1.0
    )

    ancestors: dict[str, set[str]] = {}
    structurally_valid = False

    try:
        validate_plan_structure(plan)
        structurally_valid = True
        ancestors = _ancestors(plan)

        refusal = refuse_if_impossible(plan, contract)
        if refusal is not None:
            admissible = False
        else:
            validate_plan_semantics(plan, contract)
            admissible = True
    except (SchemaError, SemanticError):
        admissible = False

    order_violations: tuple[tuple[str, str], ...] = ()
    if structurally_valid:
        order_violations = tuple(sorted(
            (before, after)
            for before, after in contract.must_precede
            if after in ids
            and (before not in ids or before not in ancestors[after])
        ))

    return PlanGrade(
        admissible=admissible,
        required_recall=required_recall,
        forbidden_present=tuple(sorted(contract.forbidden & ids)),
        order_violations=order_violations,
    )

只写一次契约买到运行期间的校验器和评估期间的评分器,这比两者单独任一个都更值钱。离线得分与运行时真正检查的属性对齐——必需里程碑、禁止工作、顺序和可接受性——所以改进可以用部署的控制逻辑来解释。它们本身不是更高端到端任务成功的证明。

得分还有一个单一分数所没有的形状。一个召回 1.0 而有三处顺序违规的规划器,与一个 0.5 且没有违规的规划器面临不同问题:前者知道工作是什么而不知道它如何拼合,后者是在丢步骤。形式规划基准发现流畅输出与可执行输出之间的差距是持久的,[3] 这正是直接给结构评分而非从下游成功推断它的理由。


11. 对着冻结的计划测试执行器

现在反转实验。给执行器一个已知可接受的计划,并完全移除它选择路线的全部能力。然后只度量它是否执行了被给的步骤、产出了该步骤声明的证据、保持在范围内,以及它多频繁地在计划之外行动。

如果系统在这些条件下仍然失败,规划器的工作不会修好它。

那读起来显而易见且被常规违反。大量提示词工程投入到更好的分解上,而那些系统的实际失败是执行器无法可靠地运行命令并读其输出。冻结的计划是规划版的植入缺陷测试,与批评与修订章中对批评者所用的相同:保持一个已知良好的组件,让另一个无处躲藏。


12. 消融测试规划是否值得

把一个规划智能体与一个完全不同的技术栈比较什么也回答不了,因为一次动了太多东西。在相同任务集上一次加一个机制。

系统 显式计划 依赖 结构检查 语义检查 证据触发的重新规划
直接智能体 – – – – –
散文分解 yes 隐式 – – –
结构化计划 yes yes – – –
校验过的计划 yes yes yes yes –
自适应计划 yes yes yes yes yes

为每一行报告计划得分、执行器错误率、目标成功、不必要动作、模型调用和延迟。有信息量的比较在相邻行之间,因为每一对隔离一个机制。

如果结构化计划胜过散文分解但校验在其之上没带来任何东西,那么规划器本来就在产出格式良好的图,那些闸门是保险而非改进。如果校验带来大量收益,那么规划器在生成跑不通的计划,下一个该买的是更丰富的契约而非更强的模型。

两种结果都给出比只有聚合成功有用得多的、关于工程努力该花在哪里的信号。

显式规划是否把计算改进了足够程度,以证明那个额外规划步骤的正当性?


13. 组装运行时

以上一切组合成一个循环。这里只出现顶层函数;类型和校验器与上面定义的完全一致,而配套仓库带着它的测试承载可运行版本。

from typing import Callable

def prepare_plan(plan: Plan, contract: GoalContract) -> PlanResult:
    validate_plan_structure(plan)

    refusal = refuse_if_impossible(plan, contract)
    if refusal is not None:
        return refusal

    validate_plan_semantics(plan, contract)
    return plan

def observed_facts(observation: Observation) -> set[str]:
    if not observation.ok or not isinstance(observation.data, dict):
        return set()

    return set(observation.data.get("facts", ()))


def completed_step_changes(
    old: Plan,
    new: Plan,
    completed: set[str],
) -> tuple[str, ...]:
    old_by_id = {step.id: step for step in old.steps}
    new_by_id = {step.id: step for step in new.steps}

    return tuple(sorted(
        step_id
        for step_id in completed
        if step_id in old_by_id
        and (
            step_id not in new_by_id
            or new_by_id[step_id] != old_by_id[step_id]
        )
    ))

def run_plan(
    goal: str,
    contract: GoalContract,
    propose: Callable[[str, GoalContract, ExecutionState, Plan | None], Plan],
    execute_step: Callable[[PlanStep, ExecutionState], Observation],
) -> ExecutionState:
    state = ExecutionState(facts=set(contract.given_facts))
    plan = prepare_plan(propose(goal, contract, state, None), contract)

    if isinstance(plan, PlanningFailure):
        state.outcome = f"refused: {plan.reason}"
        return state

    while ready := ready_steps(plan, state):
        step = ready[0]
        observation = execute_step(step, state)
        state.observations[step.id] = observation

        # Observations may invalidate assumptions whether or not the attempted
        # action otherwise returned success.
        state.facts -= withdrawn_facts(observation)

        if observation.ok:
            established = observed_facts(observation)
            missing = set(step.produces) - established

            if missing:
                state.outcome = (
                    f"expected_evidence_missing: {step.id}: {sorted(missing)}"
                )
                return state

            state.completed.add(step.id)
            # The environment may establish more than the plan predicted.
            # Preserve those observed facts; intention does not cap reality.
            state.facts |= established

            if not invalidated_steps(plan, state):
                continue

        elif not invalidated_steps(plan, state):
            state.outcome = f"step_failed: {step.id}"
            return state

        revised = prepare_plan(
            propose(goal, contract, state, plan),
            contract,
        )

        if isinstance(revised, PlanningFailure):
            state.outcome = f"replanning_refused: {revised.reason}"
            return state

        if revised == plan:
            state.outcome = "replanning_produced_no_new_route"
            return state

        changed_completed = completed_step_changes(
            plan,
            revised,
            state.completed,
        )
        if changed_completed:
            state.outcome = (
                "replanning_changed_completed_work: "
                f"{list(changed_completed)}"
            )
            return state

        plan = revised

    # This is completion of the declared planning milestones, not verified
    # success of the user's goal. Final goal verification belongs elsewhere.
    state.outcome = (
        "plan_complete"
        if contract.required <= state.completed
        else "blocked"
    )
    return state

读这个循环看它从不做什么。它不在调度器内部发明下一条路线;它从依赖和已确立事实计算下一步被允许跑什么。规划器只在必须提出或修补一条路线时被调用。execute_step 自身可以使用确定性工具或模型辅助能力,但它收到一个被批准的步骤而非对计划的权威。

另一个重要改变很容易被忽略:成功的返回码不会自动把 step.produces 中列出的每个事实提升进执行状态。观察必须显式确立那些预期事实。如果必需证据缺失,步骤就��完成。如果一个观察确立了计划未预测的额外事实,运行时保留它们而非丢弃。规划器的预测约束期望;它们不覆盖执行实际报告的东西。

最后一行刻意命名为 plan_complete,而非 success。就绪步骤耗尽在"用尽被声明的路线"和"变得阻塞"之间是有歧义的,所以规划契约区分了那些情况。用户目标是否真的达成,仍属于本书后面构建的外部验证机制。

这个循环缺少的是一个不是"没有任何东西就绪"的停止理由。它没有预算、没有进度概念,也没有对一个步骤失败、触发一次措辞上不同的重新规划、然后在少一次模型调用的情况下回到基本相同位置的那种情况的防御。revised == plan 这个守卫只捕捉完全相同的替换计划。

那些不是规划问题,在这里加上它们会把终止逻辑埋进那个职责是路由的组件。


14. 这个表示买到了什么

这里没有什么让模型更擅长规划。规划器与否则会逐个决定动作的那个模型是同一个。改变的是它的输出不再是控制流而成为一个对象。

一旦预期工作成为一个对象,四件之前不显式的事情变得可能。它可以在工具执行或副作用之前被拒绝,因为一个环或一个缺失的必需里程碑在数据中可见。它可以不被执行就被评分,把路线是否合理与工具是否工作分开。它可以与实际发生的事情比较,因为意图在运行后幸存而非被它覆盖。而规划边界可以显式表示拒绝,而非强迫每个请求变成一个动作形状的答案。

代价不小:又一次模型调用、另一份延迟预算、又一个可能出错的产物,以及一份必须有人编写并保持最新的契约。形式规划研究表明流畅的模型输出仍可能通不过可执行性检查,[3] 而 LLM-Modulo 工作主张把生成的提案与外部的基于模型的验证结合。[4] 本章从第一性原理到达同一个工程形状:生成提案;运行时检查;执行产出证据。

规划器提出一条路线。运行时决定那条路线是否可接受。环境决定它是否幸存。


研究渊源

本章是工程重建而非综述,参考是有选择的:每一个被引用都是因为它解决了设计必须回答的一个具体问题。

  1. Wang et al. — Plan-and-Solve Prompting: Improving Zero-Shot Chain-of-Thought Reasoning by Large Language Models (ACL 2023). 把多步推理分为制定计划然后执行子任务,在其被评估的推理任务上提供证据表明显式分解相对 Zero-shot-CoT 可以减少遗漏步骤的错误。https://arxiv.org/abs/2305.04091

  2. Xu et al. — ReWOO: Decoupling Reasoning from Observations for Efficient Augmented Language Models (2023). 在工具观察之前构建计划以阻止推理在每次调用上被重复,此处引用是因为它证明了规划与执行可以是独立模块而非一条交错的轨迹。https://arxiv.org/abs/2305.18323

  3. Valmeekam et al. — On the Planning Abilities of Large Language Models: A Critical Investigation (NeurIPS 2023). 在形式规划域上测试 LLM 并把看似合理的输出与可执行的有效计划分开,这是校验一个生成的计划而非信任它的经验基础。https://arxiv.org/abs/2305.15771

  4. Kambhampati et al. — LLMs Can’t Plan, But Can Help Planning in LLM-Modulo Frameworks (ICML 2024). 主张复合系统,其中生成的候选计划遇上外部的基于模型的批评者或验证器;这里构建的结构与语义闸门是那种安排的一个小实例。https://arxiv.org/abs/2402.01817

  5. Sun et al. — Agent Planning Benchmark: A Diagnostic Framework for Planning Capabilities in LLM Agents (2026). 在 22 个领域的 4,209 个多模态案例中把规划作为上游能力与执行分开诊断,包括损坏工具和不可解任务的设置,并报告长程规划与有校准的拒绝作为系统性弱点。https://arxiv.org/abs/2606.04874


下一章:运行时状态、进度与终止

运行时现在记录了足够的执行状态来路由工作:已完成的步骤、观察和已确立的事实。它尚未表示的是它自己在这场计算中的进度。

它无法说十个动作是否花在了本应一个动作完成的事情上、最后三个是否产出了任何真正新的东西、它是否正带着不同措辞回到同一状态,或者剩余预算是否值得再试一次。上面的循环可以让一个步骤失败、重新规划,并在少一次模型调用的情况下回到基本相同的位置;那个相等性检查只捕捉完全相同的替换计划。

那些不再是规划问题。它们是关于进度、预算、重复和终止的问题。