Zero 架构 · 第四课

护栏:循环对模型的「不信任」

第一课的循环有个 maxTurns = 12 的天花板 —— 那是最后的硬止损。但一个只靠天花板 兜底的 agent 会很糟:模型可能连着 12 回合空转、或对同一个坏调用反复撞墙、或一直只调工具 从不产出结论。护栏(guardState)就是循环用来提前识别这些失控 模式的一组有界计数器。

对齐 mission:一个真实的 coding agent,一半复杂度不在「让它能干活」,而在「让它别乱干」。 这一课解释 Zero 怎么把「模型可能不听话」这个前提,编码成具体的停止与提醒规则。

核心洞察:循环假设模型会犯错

护栏状态挂在每次运行开头(newGuardState),在第一课循环的两个点被喂数据: 每个回合后 observeTurn、每个工具结果后 observeToolResult。 guardrails.go:353 它把失控分成两类处理:

• 硬停(halt): 情况无法靠继续解决 —— 直接结束这次运行。
• 软推(nudge): 情况也许能自我纠正 —— 注入一次性提醒消息,不停止。

硬停:两道熔断

① 连续空回合 → 停

一个回合既无可见文本、又无工具调用就是「空回合」。连续 maxEmptyTurns = 3 次就停止运行,以免在撞到 maxTurns 之前白烧回合。 任何一次有产出的回合都会把计数器清零。 guardrails.go:19、 guardrails.go:414

② 同一错误重复失败 → 先提示,再停

这是最精妙的一道。observeToolResult 按工具名 + 错误签名记录 连续失败次数(errorSignature 把错误输出归一成一个签名, guardrails.go:252)。它是一个升级阶梯: guardrails.go:381

• 失败到第 2 次(toolFailureHintAt):注入一次性纠正提示 —— 把该工具的 schema + 精确错误喂回去,让模型自己改。
• 失败到第 4 次(toolFailureStopAt):halt。任何模型(弱或强)都不该 在一个坏调用上循环。
• 一次成功就清空该工具的失败连击。

软推:四类一次性提醒(不停止)

关键:每条提醒都是一次性的(...ReminderSent 标志),或每个区间 一次(计划更新会开启新的 stale 区间并重置标志)。这避免了「每回合都唠叨同一句」的噪音。 guardrails.go:475、 guardrails.go:486

三个反复出现的设计手法

• 进展即重置。 好回合清零 emptyTurns;工具成功清空失败连击;计划更新 开启新区间。计数器度量的是「连续的坏」,不是「累计的坏」。
• 先提示,后熔断。 重复失败在第 2 次给药方、第 4 次才停 —— 给模型自愈的机会, 但机会有限。
• 一次性,不唠叨。 每个提醒带 sent 标志。护栏要像安静的护栏,不是碎嘴的副驾。

动手回忆

接下来该读的一手源码

less +14  ../zero/internal/agent/guardrails.go   # 所有阈值常量一目了然
less +381 ../zero/internal/agent/guardrails.go   # observeToolResult 升级阶梯
less +414 ../zero/internal/agent/guardrails.go   # observeTurn 空回合/tool-only 计数

读的时候先只看顶部那组 const(:14)—— 每个数字就是一条策略。然后看两个 observe* 方法怎么在「进展时清零、连续坏时累加」。护栏的全部智慧就在这两件事里。