AI 原生开放教材

外观

AI 工程从零到一（中文）源码研读·中文原文 ↗原件 ↓仓库 ↗

Agent Harness Loop 契约 ​

harness 才是 agent。模型只是协处理器。这节课把 loop 契约钉死，好让你把任何模型接进去。

类型： Build 语言： Python 前置要求： 第 13 阶段第 01-07 课、第 14 阶段第 01 课 预计时间： ~90 分钟

学习目标 ​

  • 把 agent harness loop 指定成一个带显式转移的确定性状态机。
  • 实现 10 个生命周期 hook topic，供运维把策略、遥测和护栏接进去。
  • 定义 2 个 pull point，让 loop 把控制权还给调用方，并在收到新输入后恢复。
  • 对每个 session 强制执行预算限制（turn、tool call、wall-clock），且超限时不泄漏半截状态。
  • 发出一条带类型的 11 种事件流，让下游 UI 和 tracer 不用直接窥探 loop 就能订阅。
figure
cf-loop-contract

框架 ​

一个能无人值守跑 40 个 turn 的 coding agent，不是聊天循环。它是一个状态机：运维可以拦它的节点，可以审它的边。一旦你把契约写清楚，换模型、换工具、换策略都不再是重构，而是一次注册调用。

这节课就做这件事。我们把 6 个状态、10 个 hook topic、2 个 pull point、11 种事件类型和一层预算外壳都定下来。harness 里的其他东西（tool registry、JSON-RPC transport、dispatcher、planner）都往这个形状里插。

状态 ​

loop 有 6 个状态。5 个是活动态，1 个是终止态。

mermaid
stateDiagram-v2
    [*] --> IDLE
    IDLE --> PLANNING: run(goal)
    PLANNING --> EXECUTING: plan 已提交
    EXECUTING --> AWAITING_TOOL: 需要 tool_call
    AWAITING_TOOL --> REFLECTING: 收到结果
    EXECUTING --> REFLECTING: 无工具步骤完成
    REFLECTING --> EXECUTING: 下一步
    REFLECTING --> PLANNING: 重新规划
    REFLECTING --> DONE: 目标达成
    PLANNING --> DONE: 无 plan
    DONE --> [*]

IDLE 是唯一合法入口。DONE 是唯一合法出口。AWAITING_TOOL 是唯一会让出 pull point 的状态，其他转移全是内部行为。

这个状态机必须是确定性的。给定同一份事件日志，harness 必须重回同一个状态。正是这个性质，才让你能在调试时 replay session，而不用重新调用模型。

Hook Topic ​

hook 是运维插进 loop 的接缝。harness 会触发 10 个 topic。每个 topic 都能挂任意多个 subscriber。subscriber 按注册顺序触发；它可以改 payload、抛错中止本轮，也可以返回一个 sentinel 跳过下一步。

text
before_plan         after_plan
before_tool_call    after_tool_call
before_step         after_step
on_error
on_pause
on_budget_exceeded
on_complete

这个形状，基本就是 Claude Code、Cursor、OpenCode 到 2025 年中收敛出来的公共套路。名字是功能性的，不是品牌性的。拦 rm -rf 的 hook 放在 before_tool_call。发 OpenTelemetry span 的 hook 放在 after_step。处理暂停恢复的 hook 放在 on_pause。

Pull Point ​

loop 会让出控制权两次。第一次是在 AWAITING_TOOL，因为没有工具结果它没法继续。第二次是在 on_pause，因为预算耗尽，或者某个 hook 明确要求人工 review。

pull point 不是异常，而是 return。调用方检查 harness 状态，取回 harness 要的东西，然后调用 resume(payload)。harness 从停下来的地方继续。这和 Python generator 是同一种形状。pull point 之上的 transport 由你选：TUI 里是按键；MCP 里是 tools/call；队列里是 job poll。

事件流 ​

loop 会在契约里的特定位置把事件追加到一条带类型的流里。流是 append-only，subscriber 可以从任意 offset replay。实现的 11 种事件如下：

  • session.start：调用 run(goal) 时发一次
  • plan.draft：planner 返回草案时发
  • plan.commit：草案被提交成当前 plan 后发
  • step.start：每个执行 step 开始时发
  • step.end：每个执行 step 结束时发
  • tool.call：需要工具的 step 把控制权让回调用方时发
  • tool.result：带着 tool result 恢复时发
  • tool.error：带着错误恢复，或 hook 中止调用时发
  • budget.warn：打到预算上限时发
  • session.pause：loop 因预算或 hook 暂停时发
  • session.complete：loop 进入 DONE 时发一次

事件不复制 hook payload。hook 是命令式的，负责改、拦、跳过；事件是观察式的，负责记录和外发。两者别混。

预算外壳 ​

一个 session 带 3 个限制：turn 数、tool call 数、wall-clock 秒数。每个 turn 把 turn 计数加一，每次 tool call 把 tool call 计数加一，wall-clock 在每次状态转移时检查。任何一个限制被打满时，loop 会先触发 on_budget_exceeded，再发 budget.warn，然后在下一个 pull point 上带着预算超限原因转回 IDLE。

预算不是 kill switch，而是 yield。到底是扩预算后恢复，还是直接结束 session，由调用方决定。

这节课不做什么 ​

它不调用模型，不注册真实工具，也不实现 transport。那是后面 4 节课的事。这节课先把契约钉死，好让后面 4 节可以接进来而不用重写。

main.py 里的 deterministic planner 只是占位符。它会返回一个硬编码的 3 步 plan，其中两步需要 tool result。重点是 loop，不是 plan。

怎么读代码 ​

HarnessLoop 是主类，负责持有状态、触发 hook、发事件。Budget 跟踪预算。Event 是事件流里的类型化信封。HookRegistry 是分发表。_transition 是唯一能改状态的函数，所以状态机约束全收口在这一处。

先把 main.py 从头到尾读一遍，再读 code/tests/test_loop.py。测试把每条状态转移和每种 hook 触发顺序都钉住了。

往前走 ​

生产里最难的不是写状态机，而是让契约真的可执行。它得扛住 planner 热重载，扛住工具返回坏 JSON，也得扛住一个 hook 在 40 turn session 跑到三分之二时于 before_tool_call 抛错。这节课的测试就在打这些故障模式。跑它们，拆它们，再补 case。

下一课加 tool registry。再下一课加 JSON-RPC transport。再下一课加 dispatcher。到第 24 课，这个文件里的 loop 就会带着真实 plan、真实工具和真实预算跑起来。