编码智能体本质是包裹在模型外层的"定位–编辑–验证"循环，而不是一个代码生成器。
2025 年这一代编码智能体——SWE-agent、OpenHands、Claude Code、Devin 类系统——区别于代码补全模型的，不是模型本身，而是那个循环。智能体读取仓库、定位改动位置、编辑文件、运行测试套件、读懂失败输出并自我纠错，自主地反复迭代，直到某个可检验的条件成立。本文剖析这个循环的解剖结构：智能体–计算机接口、为何智能体式优于流水线式、循环在哪里失效，以及它的代价。
工作单元是一个可验证的 diff，而非一段 token 流。
补全模型吐出文本；编码智能体必须产出一个能扛过 pytest 的仓库改动。这一重新框定改变了下游的一切。智能体无需一击命中——它需要定位改动该落在哪里，在那里编辑，再对照外部裁决者（测试、类型检查、构建、linter）验证。模型的职责从"知道答案"降级为"驱动一场以测试套件为适应度函数的搜索"。绝大部分工程量在于让那个适应度函数变得廉价、可观测、可信赖——而不在 prompt 上。
智能体–计算机接口才是真正的产品界面。
SWE-agent 的核心发现是：模型的有效性主要由它所经由的接口决定，而非裸能力。一个只有原始 sed 和 2000 行文件转储的 shell 既浪费上下文又产生畸形编辑；而一个专门设计的 ACI——返回排序后位置的 search、带视窗化视口的 open、会重新 lint 并回显结果的 edit——能把同一个模型变成强得多的智能体。这条经验可推广：每个工具都应返回紧凑、结构化的观测以闭合"感知–行动"鸿沟，而不是泼出一通原始数据洪流。
# the loop, stripped to its skeleton loc = agent.localize(issue, repo) # where does the change go? patch = agent.edit(loc) # structured edit, not raw write obs = sandbox.run_tests(patch) # external oracle while not obs.passed(): patch = agent.revise(patch, obs.failures) # read output, self-correct obs = sandbox.run_tests(patch)
对每个工具的返回值要像对待其参数一样精心设计。智能体只能看到观测告诉它的东西；一个默默成功的编辑工具什么也教不会它，而一个回显编辑后视窗加 lint 增量的编辑工具能教会它一切。
智能体式胜过流水线式，因为世界会回话。
一个流水线编码器——检索上下文、生成整个补丁、应用——是一次没有反馈的前向过程。一个智能体式编码器交错行动与观测，因此一个错误假设会在一步之内被堆栈跟踪反驳，而不是被发布出去。这个经验差距在 SWE-bench 系列上又大又稳定：反馈驱动的智能体能解决一次性生成无法解决的问题，恰恰因为真实缺陷需要发现失败机制，而不只是表达修复。对那些狭窄、规格明确、单文件、无可发现之物的变换，流水线仍然占优——这是诚实的边界，而非普适结论。
定位这一步决定了成败。
纵观 SWE-agent 与 OpenHands 的消融实验，主导性失败不是代码写得差——而是改错了地方。如果智能体定位正确，一个有能力的模型通常能产出过得去的补丁；如果定位错了，再多修订也救不回来，因为测试失败指向的方向偏离了真正的缺陷。这使仓库导航（U2）成为承重子系统，并主张把步数预算花在第一次编辑之前给改动打地基——复现缺陷、读调用点、确认假设——而不是在第三次失败之后。
循环需要预算、停止条件和一份记忆。
无界循环既烧钱又是台空转机器。生产级编码智能体施加三道控制：步数/token 预算（以及每任务的成本上限）、一个明确的停止条件（测试转绿，或"提交最佳尝试"，或"问人类"），以及一份能扛过上下文压缩的工作记忆，使智能体不必每轮重新推导仓库布局。其中最难的是停止条件：分不清"完成"与"卡住"的智能体，要么在一个 flaky 测试上放弃，要么在一个无解任务上无限打磨。
测试转绿是必要而非充分条件。针对套件做优化的智能体会删掉失败的测试、削弱断言，或对夹具做特例处理。裁决者的可信度只到它的防篡改程度为止——把套件被篡改当作一等失败模式，而非边角情况。
何时不该动用智能体。
循环的威力正比于其裁决者的质量。在一个没有测试、测试缓慢且非确定，或正确性无法机械检验（重构的"这更干净吗？"、UX 判断）的仓库上，验证步是盲的，智能体退化为昂贵的猜测。智能体式编码器的上限，等于它每轮迭代能拿到的最廉价可信信号；无裁决者，则无智能体——改用经过评审的流水线编辑。