给编码代理装上“监工”：可靠循环工程实践

编码代理很能干，但需要“监工”

Claude Code、Codex 这类工具自带一条执行循环：能看文件、调工具、改代码、根据中间结果调整行为。单次任务跑得很好。但放到真实项目里，一次任务可能持续几小时，涉及几十次迭代，还要应对测试失败、接口变动、上下文丢失。这时候，光靠自带循环不够。

你需要一个外层监督者，像团队里的技术负责人：

• 决定什么时候开始下一轮工作
• 限制代理能做什么
• 隔离每次改动，防止搞乱主仓库
• 要求提供证据，证明改动有效
• 判断失败是重试还是重新规划
• 该停的时候坚决停

核心思路：外面再套一层控制环

这篇文章讲怎么搭这层控制环。它包含十几个关键组件，下面逐个说。

1. 类型化任务契约：给代理“写合同”

所谓契约，就是任务的输入、输出、允许的动作、成功标准。相当于后端接口的 Schema。代理只能在约定范围内行动，不能自由发挥。

比如一个任务契约可能是这样的：

• 目标：修复解析器崩溃
• 输入：出错日志、复现脚本
• 允许动作：修改 parse.py、test_parser.py，运行 pytest
• 禁止动作：改动依赖文件、格式化全局代码
• 成功标准：pytest 全部通过，且复现脚本不再崩溃

有了契约，代理的行为就可预期，出了问题也容易追责。

2. 持久计划账本：每一步都要留痕

代理的计划不能只存在模型上下文里，进程一崩就全丢。要写进文件或数据库，形成“计划账本”。每次执行了什么、为什么这样做、结果如何，都追加记录。

这就像程序员写工作日志，但比日志更严格。账本让监督者能随时知道“现在到哪一步了”，还能在失败后恢复现场。

3. 有界 worker 切换：防止代理“跑偏”

代理一旦开始改代码，有时会顺手改很多东西。必须给每次切换设边界，比如最多改3个文件，最多执行10条命令。用完额度就强制交回控制权。

这个“有界”很重要。就像你请外包团队修BUG，不能给他们整个仓库权限，只给一个隔离工位，改完交付。

4. 提供商适配器：统一不同代理的接口

Claude Code、Codex、DeepSeek 等工具接口各不相同。适配器把它们包装成统一的标准接口，上层监督逻辑就不用关心具体是哪个模型。

以后再换更强的模型，只要适配器不变，控制环照常工作。

5. 标准化事件流：让外部系统“看懂”代理

代理执行过程中会产生各种信息。不同工具输出格式不一样，有的写日志，有的打屏，有的返回 JSON。需要一个标准化事件流，把所有关键动作转成统一事件，比如“读取文件”“修改文件”“运行测试”“收到错误”。

这样，外部监控、告警、可视化都能接入。相当于给代理装上统一的“仪表盘”。

6. 独立 Git diff 采集：不信任代理的自述

代理说“我改了3个文件”，你不能完全信。要独立地去 Git 仓库里采集实际 diff，判断它到底动了什么。采集过程必须独立于代理，甚至独立于执行环境。

为什么要独立？因为代理可能出错，也可能“嘴硬”。只有 diff 是客观事实。

7. 验证与完成门：没有证据就不算完

代理说“任务完成”没用，必须通过验证门。典型验证包括：

• 单元测试、集成测试通过
• lint 检查通过
• 类型检查通过
• 性能指标没退化
• 复现脚本不再失败

验证门通过，任务才算真正完成。这一条不可妥协。

8. 失败分类：决定重试还是重新规划

代理任务不会总成功。失败时，先分类：

• 临时性失败：比如网络超时、测试环境启动慢，可以重试
• 确定性失败：同样的输入总是同样的报错，重试没用，需要调整方案
• 方向性失败：代理理解错了需求，需要重新规划任务

分类机制用规则加模型判断。比如连续两次同样失败，就标记为确定性失败，不再重试。

9. 无进展检测：别让代理“空转”

有时候代理不会报错，但一直不产生有效改动。比如反复读文件，就是不改代码。需要检测“无进展状态”：连续 N 次迭代没有新 diff、测试结果没变化，就触发暂停。

这就像进展汇报里的“阻塞项”，没有进展就必须升级给人类。

10. 跨运行预算：控制总成本

单次重试有次数限制，但还要有更大的预算。比如整个修复过程最多运行20次代理，总 token 花费不超过 X，总耗时不超过 Y。预算用尽就停止，并保留现场。

预算控制是生产环境的基本要求。AI 编码代理一旦跑飞，成本和风险都很高。

11. Git worktree 隔离：互不干扰

用 Git worktree 给每次任务开独立工作目录。这样并行跑多个任务也不会互相污染。主仓库保持干净，每个任务的结果相当于一个分支，验证通过后再合并。

这比传统分支更彻底，因为 worktree 是文件系统级别的隔离。

12. 触发准入：不要随便启动代理

外部系统（比如 CI、Issue tracker）会频繁触发任务。但不是所有触发都要执行。需要一个准入机制，根据请求合法性、资源可用性、是否有重复任务来决定是否接受。

就像服务端的熔断和限流，避免被无效请求打爆。

13. 取消处理：能叫停，也能清理

有时候人判断任务方向错了，需要中途取消。取消不是直接杀进程，而是优雅地停止：通知代理、保留现场、清理临时资源，并记录取消原因。

这样才能保证下一次可以从容地重新规划。

14. 终端工件保留：留证、可审计

任务结束，不管成功还是失败，所有产物都要留存：代理输入、输出、diff、测试日志、验证结果、运行时间、token 消耗。这些工件既是审计依据，也是数据资产，将来复盘还是训练更好的代理都需要。

一个贯穿的例子：解析器崩溃修复

用前面说的架构，看一个完整场景。

你的项目里有个解析器，最近在线上频繁崩溃，日志报空指针。传统流程是派人查，但你想试试编码代理。监督者决定启动一个修复任务。

• 首先，控制器复现崩溃。用最小化脚本触发空指针，确认错误存在，并保存现场。
• 然后，定义任务契约：目标是修复崩溃，允许修改 parse.py 和对应测试，禁止其他改动，成功标准是 pytest 通过且复现脚本退出码为 0。
• 接着，在独立 worktree 里启动代理调用。代理尝试修改代码，生成补丁。
• 控制器独立采集 diff，确认改动范围没超出契约。
• 然后跑验证门。如果测试失败，失败分类器判断：是临时失败还是确定性失败？比如发现是测试用例本身有并发问题，就重试一次。但如果代理改了依赖版本导致更多失败，就判定为方向性失败，重新规划任务。
• 与此同时，无进展检测发现代理连续5次迭代没产生 diff，直接暂停。
• 整个过程中，预算系统记录 token 消耗。超过设定值，强制停止。
• 最后，成功时把补丁合并到主分支；失败时保留所有工件，交给人分析。

这个例子用到了上面全部机制。核心思想是：不把编码代理当“自动程序员”，而是当“可控制的实习生”。你做监督，它做执行，每一步都有证据、有边界、有停止条件。

这背后是工程思维，不是魔法

很多团队用 AI 编码代理，总觉得“扔给它一个 issue，它自己就能搞定”。结果经常跑出各种幺蛾子。原因不是模型不够强，而是缺少监督机制。

可靠的关键，是把软件开发中已有的工程实践（任务拆解、代码审查、测试验证、过程留痕）迁移到 AI 执行者身上。模型负责“手艺”，系统负责“管理”。

总结

本文提出的外部控制环，包含 14 个关键组件：任务契约、计划账本、有界切换、适配器、事件流、独立 diff、验证门、失败分类、无进展检测、预算、worktree 隔离、准入、取消、工件保留。

它们不需要一次性全部实现。可以从最小闭环开始：任务契约 + 验证门 + 重试限制。跑顺了，再加预算、隔离、事件流。重要的是，把“监督”当成系统设计的一部分，而不是事后补救。