如何设计可控的agent-loops

目录

• 为什么要谈循环
• 循环的基本结构
• 四种常见循环
• 什么时候不要使用循环
• 质量控制：把检查放进循环里
• 成本控制：不要让自动化变成失控的轮询
• 落地步骤
• 设计检查表

为什么要谈循环

很多团队在引入代码智能体时，第一反应是继续优化提示词：把背景写得更完整，把要求写得更细，把“请认真检查”写得更坚定。这样做对简单任务有用，但一旦任务变长，问题就会转移。

真正困难的地方通常不是模型不知道怎么写代码，而是它不知道该工作到什么时候、该用什么方式证明自己做对了、失败几次之后应该停下来、什么时候应该把问题交还给人。

这就是循环设计要解决的问题。

循环不是让智能体无限运行。循环是把一项工作拆成可以重复执行的单元，并为每一轮定义清楚：

• 由什么触发。
• 本轮允许读取和修改什么。
• 用什么标准验证结果。
• 未通过时是否继续。
• 达到什么条件必须停止。

一旦这些边界被明确，智能体就不只是一个响应提示词的工具，而可以成为一个受控的执行单元。

循环的基本结构

一个可控循环通常包含四个环节：触发、执行、验证、停止。

触发决定循环什么时候开始。它可以来自人的一次请求，也可以来自定时任务、外部事件、队列消息、监控告警或代码仓库里的状态变化。

执行决定智能体在一轮里做什么。它可能读取代码、查文档、调用 API、修改文件、运行脚本，也可能把任务拆给多个子任务处理。

验证决定本轮结果是否可信。验证可以是单元测试、端到端测试、lint、类型检查、截图对比、性能指标、日志检查、人工审查，或者另一个独立智能体的 review。

停止决定循环何时结束。常见停止条件包括任务完成、达到最大轮次、预算耗尽、连续失败、出现高风险修改、需要额外权限或需要业务判断。

一个常见错误是只设计执行，不设计验证和停止。这样得到的不是循环，而是一段难以控制的自动化过程。

四种常见循环

1. 按轮次推进

这是最基础的模式。人发起一次请求，智能体完成一轮工作，然后把结果交回。下一轮是否继续，由人决定。

它适合探索性任务、短任务和判断标准还不清楚的任务。例如初步理解一个模块、尝试修一个小 bug、整理一段代码的改造思路，或者让智能体先给出几个备选方案。

这种模式的优势是风险低。人始终掌握方向，每轮都可以纠偏。缺点是人的参与密度高，智能体无法长时间独立推进。

要让这种模式更可靠，重点不是让提示词越来越长，而是把常用检查动作固定下来。例如前端改动必须打开页面、操作控件、检查控制台、保存截图；后端改动必须跑相关测试、检查日志、确认错误处理路径。这些检查动作应该成为固定流程，而不是每次靠人临时提醒。

2. 按目标停止

当任务需要多轮尝试，并且完成标准可以写清楚时，可以使用目标型循环。

这类循环的关键是把“做得更好一点”改成可验证目标。例如：

• 修复这个测试文件里的所有失败用例，最多尝试 5 轮。
• 把某个页面的性能分数提升到 90 以上，不能删除现有功能。
• 完成一组接口迁移，所有调用方测试通过后停止。
• 处理这批类型错误，但不修改公开 API。

目标型循环适合有明确验收标准的工程任务。它把一部分停止判断交给系统，但仍然需要边界：最多尝试几轮、哪些文件不能改、失败时如何回退、什么情况必须请求人工判断。

如果目标本身含糊，循环会变得低效。比如“优化一下代码质量”不是好目标，因为它没有可执行的停止条件。“移除这个模块中的重复分支，并保证现有测试全部通过”才是更适合循环执行的目标。

3. 按时间触发

有些工作不是一次性的，而是会周期性出现。比如每天汇总问题、每隔一段时间检查未处理 PR、定时扫描失败任务、同步外部系统状态、查看某个队列是否积压。

这类任务适合时间触发循环。

时间触发的好处是稳定，坏处是很容易过度运行。很多系统的状态并不会高频变化，但循环却被设置成几分钟跑一次，最后消耗集中在大量没有变化的检查上。

设计时间触发循环时，应该先回答三个问题：

• 被观察对象多久变化一次。
• 变化出现后，最晚多久处理仍然可以接受。
• 如果连续多次没有变化，是否应该降低频率或暂停。

如果可以使用事件触发，就不要依赖高频轮询。定时循环适合“状态变化不方便直接订阅”的场景，而不是所有自动化任务的默认选项。

4. 主动循环

主动循环是更完整的自动化 routine。它可以由事件或计划触发，在没有人实时参与的情况下完成一组边界清晰的工作。

典型场景包括 issue 分流、依赖升级、低风险代码迁移、失败任务重试、反馈渠道中的 bug 报告处理、重复性文档维护等。

主动循环的设计要求最高，因为它交出去的不只是某一轮执行，而是触发、执行、验证和反馈的整条链路。它至少需要：

• 明确的任务入口。
• 清晰的权限范围。
• 可执行的验收标准。
• 独立审查或抽样审查。
• 失败告警。
• 可回滚策略。
• 用量上限。

如果缺少这些约束，主动循环会把小问题放大。它可能反复修改同一类代码、提交不必要的变更、在错误方向上迭代多轮，或者把本该由人判断的问题包装成自动化结果。

什么时候不要使用循环

循环有成本，也会引入新的故障模式。以下情况通常不适合一上来就设计循环：

• 任务目标还没有被人理解清楚。
• 验收标准无法写成检查项。
• 修改影响范围很大，但缺少测试和回滚手段。
• 需要业务、法律、安全或产品判断。
• 一次脚本就能稳定完成。
• 错误结果的代价明显高于人工处理成本。

一个实用原则是：先把人工流程跑顺，再把其中稳定、重复、可验证的部分交给循环。

不要把循环当成弥补流程混乱的工具。流程本身不清楚时，自动化只会更快地产生不清楚的结果。

质量控制：把检查放进循环里

循环输出的质量，主要取决于它周围的工程系统，而不只是模型本身。

保持代码库一致

智能体会模仿已有模式。代码库里如果存在多套风格、重复抽象、过时接口和不稳定测试，智能体很可能继续沿用这些问题。反过来，如果项目结构清楚、命名一致、测试可靠，它就更容易生成符合预期的修改。

因此，循环设计不是孤立的提示词工程。它依赖代码库本身的可读性和可维护性。

把“好”的定义写成检查

“写得干净一点”“注意边界情况”“不要破坏现有功能”都太抽象。更好的做法是把这些要求变成可执行检查：

• 哪些测试必须通过。
• 哪些页面必须能打开。
• 哪些日志不能出现新错误。
• 哪些指标不能下降。
• 哪些公共接口不能改变。
• 哪些文件或目录不能修改。

检查越具体，循环越容易稳定。

使用独立审查

执行任务的智能体对自己的方案天然有路径依赖。它已经围绕某个解释展开了上下文，容易忽略替代方案和反例。

对有风险的改动，可以引入独立审查：让另一个评审者只看 diff、测试结果和目标，不继承前一个执行者的推理过程。这样更容易发现过度修改、遗漏边界、测试覆盖不足和不必要的复杂度。

把单次失败沉淀成系统改进

如果循环某次产出了不合格结果，只修当前问题是不够的。应该追问：为什么验证没有拦住它？

可能的改进包括新增测试、补充文档、更新检查清单、收紧权限范围、增加人工确认点，或者把某类任务从主动循环降级为人工触发。

质量控制的目标不是让每次都不出错，而是让每次错误都能减少下一次同类错误的概率。

成本控制：不要让自动化变成失控的轮询

循环会放大收益，也会放大成本。成本不仅是 token 或接口费用，还包括代码审查成本、错误回滚成本、上下文维护成本和团队对自动化结果的信任成本。

能用脚本解决的，不要交给推理

格式转换、批量重命名、固定模板生成、数据清洗、简单迁移，这些任务通常更适合脚本。智能体可以生成脚本、运行脚本、解释结果，但不应该每次都重新推理固定步骤。

给每个循环设置预算

预算不只是金额。它可以包括最大轮次、最大运行时间、最大文件改动数、最大并发数、最大上下文大小、最大失败次数。

没有预算的循环很难排查。即使它最终成功，也可能用远高于必要的成本完成。

先小规模试点

任何会批量修改代码、批量处理 issue 或批量调用工具的循环，都应该先在小范围运行。观察它的成功率、误判类型、平均成本和人工介入点，再决定是否扩大。

不要一开始就把整个仓库、整个队列或所有项目交给循环处理。

选择合适的模型和工具

不是每一步都需要最强模型。分类、去重、格式检查、简单摘要可以用更低成本的模型或确定性脚本；架构判断、安全边界、复杂修复再交给更强模型。

合适的组合通常比单一大模型从头跑到尾更稳定，也更便宜。

落地步骤

第一步：找一个真实瓶颈

不要先设计平台，先找一个你已经反复遇到的问题。比如 PR 评论处理慢、测试失败定位慢、依赖升级没人做、bug 报告分流占用时间、文档和代码不同步。

这个任务最好有两个特征：重复出现，并且验收标准能写出来。

第二步：画出人工流程

把人现在怎么做写下来：从哪里发现任务，读哪些信息，做哪些判断，运行哪些检查，什么时候认为完成，什么时候升级给别人。

这一步经常会暴露真实问题：很多所谓“可以自动化”的任务，其实连人工流程都没有稳定标准。

第三步：只交出去一个环节

第一次不要做端到端主动循环。可以先让智能体负责一轮执行，或者只负责生成候选方案，或者只负责运行检查和整理失败原因。

小范围交付更容易观察质量，也更容易建立团队信任。

第四步：补齐验证器

如果没有验证器，循环只能靠自信。把测试、脚本、截图、日志、指标、审查清单补上，让循环有东西可以依据。

验证器越可靠，循环越可以自动化。

第五步：加入停止条件和人工升级

停止条件应该提前写清楚。常见规则包括：

• 连续失败 3 次后停止。
• 超过预算后停止。
• 修改敏感目录前请求确认。
• 测试无法运行时停止。
• 发现需求冲突时停止。
• 影响公共接口时转人工审查。

循环不是越自主越好。能识别自己该停下来，是可靠系统的一部分。

第六步：记录运行结果

每次循环都应该留下可审计记录：输入是什么，做了哪些动作，改了哪些文件，验证结果如何，成本是多少，是否触发人工介入。

这些记录不是为了形式，而是为了后续判断它是否值得继续扩大范围。

设计检查表

在把一个任务交给智能体循环之前，可以先过一遍这张表。

智能体循环的价值，不在于让系统看起来更自动，而在于把重复劳动中的判断、验证和边界变得更清楚。只要这些东西没有被写清楚，循环越长，风险越高。反过来，一旦触发、验证、停止和成本边界足够明确，循环就会成为一种稳定的工程执行方式，而不是一次性提示词的延长版。