---
name: loop-engineering
description: 构建或修复 Agent 迭代循环时使用——解决 Agent 过早宣称完成、活干到一半就停、假成功、循环停不下来等问题，设计验证器与终止条件，实现提议者-审核者（Proposer-Reviewer）双 Agent 循环。覆盖过早终止三种形态、验证器是循环瓶颈的原则、LoopX 持久控制面、LongHorizon-Harness 的 MEA 循环、提议者-审核者最小不变量（审核者读独立证据、退回给可定位修复条件）。
---

# Loop 工程与提议者-审核者

## 何时使用
- Agent 干到一半就停：写完代码不跑测试就报"完成"、用户交代两件事只办一件就汇报"都办好了"
- 需要判断 Agent 说的"已完成"是否可信，要设计验证器与终止条件
- Agent 遇到一次失败就宣布整件事办不成（过早放弃），或误以为办成了实则闭环没走完（假成功）
- 实现提议者-审核者循环（PPT/网页生成、代码生成、视频剪辑、安全与内容审查）
- 需要跨上下文刷新、跨 GUI/CLI 的长程任务连续性管理
- 循环停不下来、token 失控，需要预算与轮数上限

## 核心原则
- **在验证之前，"完成"只是模型的一句宣称，不是证明。** 把宣称变成证明，正是 Loop 工程的课题：设计一个让 Agent 持续运转的循环——发现下一件该做的事、执行、验证、记录进度。人的角色从"给 Agent 写提示词的操作者"变成"设计循环的工程师"。
- **循环的瓶颈在验证器，而不在模型。** 验证不可靠，循环转得再快，也只是把劣质产出更快地标记为完成。
- **模型可以提出"完成"，但不能批准自己的"完成"。** 这是 Loop 工程最核心的可检查不变量：只有通过独立验证的结果才能写入持久进度并消耗配额。
- **审查必须引入新信息。** 让同一个 Agent 生成后再自己审查，等于"让模型再想一遍"——ICLR 2024 的研究表明无外部反馈时 GPT-4 自我纠错反而把更多正确答案改错。有效的审查读的是执行反馈（测试通过/失败）、视觉反馈（渲染截图）、工具反馈（外部验证输出）。
- **审核者必须读独立证据。** 不是复述提议者的解释，而是看渲染结果、执行结果、外部事实。
- **退回必须可定位。** 审核意见要能指向具体修复条件（哪一页、什么 issue_type、什么严重度、怎么改），而非"看起来不太好"。
- **人的门禁在执行前拦截。** 人工门禁、等待状态和预算上限应在循环继续之前就阻止它，而不是事后补救。

## 实践模式

### 1. 先识别：你的失败属于哪一种过早终止
| 形态 | 表现 | 根因 |
|---|---|---|
| 偷懒式假完成 | 只做一部分就宣称全部做完：代码写完测试没跑、部署没试就报"任务完成"；交代两件事只办一件就汇报"都办好了" | 缺少覆盖全部验收项的验证清单 |
| 过早放弃 | 一条路走不通就宣布整件事办不成：打了一个电话被拒就告诉用户"办不了"，其实还有表单、邮件等渠道 | 未枚举替代路径，无重规划机制 |
| 假成功 | 以为办成了，实际闭环没走完：对方口头同意退款，但用户还需在 App 确认一步，Agent 却报"已办妥" | 把中间确认当最终状态，缺端到端闭环校验 |

三种形态指向同一根源：完成的标准由模型自述，而非由验证器判定。

### 2. 最小循环骨架（提议者-审核者）
```python
candidate = proposer(task, constraints)
evidence = execute_or_render(candidate)       # tests, state, screenshot, facts
review = independent_reviewer(candidate, evidence)

while review.veto and budget_remaining:
    candidate = proposer.repair(candidate, review.findings)
    evidence = execute_or_render(candidate)
    review = independent_reviewer(candidate, evidence)

if review.pass:
    publish(candidate, evidence, review)      # 连证据一起发布
else:
    escalate_or_reject(review)                # 预算耗尽则升级，不放水
```
三条最小不变量：
1. 审核者读取**独立证据**（执行结果、渲染截图、外部事实），而不是只复述提议者的解释；
2. 退回时给出**可定位的修复条件**（位置、问题类型、严重度、建议）；
3. 审核者**不能修改测试、证据采集器或发布门槛**——否则"独立验证"退化成自我批准。

### 3. 证据采集：为新信息设计通道
- **代码**：跑测试与编译，把通过/失败与错误信息作为反馈。
- **前端 / PPT / 幻灯片**：真渲染成 PNG 再交给 Vision 模型审查——截图承载着提议者写代码时完全无法获得的布局信息（溢出、拥挤、图片尺寸）。
- **视频**：截取关键帧采样审查。
- **事实性内容**：用外部工具（搜索、解释器、数据源）验证。
- 反面对照：只保留模型自我评估而移除工具验证，大部分提升随之消失。

### 4. LoopX：把循环从聊天历史抽到持久控制面
```text
LoopX 决策 → Agent 执行 → 独立验证器证明 → LoopX 提交
```
- 目标与边界说明"为什么做"；门禁和待办决定"现在能做什么"；证据与配额决定"是否继续"；移交让下一轮或另一个 Agent 接着工作。
- LoopX 不替代 Agent 运行时，而是管理跨轮次的连续性。
- 验证失败进入修复或重规划；只有通过独立验证的结果才写入持久进度并消耗配额。

### 5. LongHorizon-Harness：MEA 循环处理长程任务
把长程执行重新表述为**任务状态管理**，循环实现为 Manage–Execute–Audit：
- **Manager**：根据原始目标、已核实进展、失败证据和剩余工作，生成下一项**有界**子任务；
- **Executor**：在全新上下文中通过 GUI 或 CLI 改变环境；
- **Auditor**：以只读方式检查真实结果，只有审计通过的内容才进入下一轮任务状态；失败被保留为恢复和重规划的依据。

价值在于把任务连续性从不断增长的执行历史中分离出来：上下文可以刷新、界面操作可能失败，下一轮仍从最近一次**已核实**的状态继续。论文在模型与执行后端相同、只改外层 loop 的对照中，WeaveBench PassRate 从 51.8% 提升到 80.7%，OSWorld 2.0 二元完成率从 2.8% 到 8.3%，Terminal-Bench 2.1 从 69.7% 到 77.2%；代价不固定——前两个基准分别多耗 2.3 倍总 token 与 3.6 倍输出 token，第三个反而少 24%。部署时还需处理旧状态失效，并用轮数、时间、费用预算防止恢复循环无限运行。

### 6. 预算、终止与防失控
- 每轮设轮数/token/时间上限，耗尽即升级或拒绝，不放水通过。
- 终止条件由验证器判定，不由模型自述。
- 并行 worker 场景：结算点定义为"第一个**已验证**成功"，用幂等的锁认领胜者后广播取消其余 worker。
- 自主性强的 Agent 用独立 API key，防止子 Agent 爆炸式增长导致 token 开销失控。

### 7. 扩展到更多审查场景
同一范式适用于：安全审查（提议者生成操作方案，审核者查合规与风险）、内容审核（起草回复，审核者查业务规则与用语规范）、代码审核（写代码，审核者查安全与最佳实践）。变体还包括规划者–生成者–评估者三 Agent：先约定每轮完成标准，评估者操作真实应用并提交缺陷报告。

## 常见陷阱
- **自我批准**：让生成者同时定义验收标准、执行验证并判定通过——独立验证退化成形式。
- **无新信息的审查**：同一模型重读自己的输出，准确率反而下降；等同计算量下多 Agent 辩论与单 Agent 持平。
- **模糊退回**："看起来不太好"式的意见无法定位修复，循环空转。
- **证据与候选不同步**：审核者看的是上一轮证据或提议者的自述，而非当前候选的真实执行结果。
- **循环转不动与停不下来是两个极端**：前者是验证缺失导致假完成，后者是缺少预算与轮数上限；两者都要靠显式的终止条件和配额解决。
- **理解债**：循环交付越快，人对系统实际实现的理解落后越远。可以外包思考，不能外包理解——审查者与门禁的存在正是为了让人始终能理解并指导系统。

## 配套代码
- `chapter5/paper-to-ppt/` — Proposer 写 Slidev 代码，Reviewer 逐页真渲染 PNG 并用 Vision LLM 给结构化意见（`page`/`issue_type`/`severity`/`suggestion` + 总分与 pass），双 Agent 峰值上下文 24,186 vs 单 Agent 自审 92,601 token
- `chapter5/video-edit/` — 两步 Vision 定位（10s 粗扫 → 1s 精扫）封装为子 Agent，Proposer 生成 Blender bpy / ffmpeg 剪辑脚本，Reviewer 采样关键帧复审迭代

## 深度阅读
- `book/chapter10.md`「对等协作模式」→「Loop 工程」
- `book/chapter10.md`「对等协作模式」→「提议者-审核者范式」