编码代理为何表现不佳？问题可能出在外部框架

编码代理的困境：Lynch的质疑与团队实践

知名开发者Lynch最近提出一个尖锐的问题：为什么编码代理（coding agents）这么笨？ 这个问题在开发者社区引发了广泛讨论。一个团队在运行了多个从工单到Pull Request（ticket-to-PR）的代理后，得出了一个值得深思的结论——问题主要不在模型本身，而在于我们为代理构建的外部框架（harness）。

这个观点挑战了主流叙事。当编码代理表现不佳时，人们习惯归咎于底层大语言模型的能力不足。但实际部署经验表明，即使是强大的模型，在真实开发工作流中也常常表现得差强人意。这暗示着，模型与开发环境之间的“粘合层”可能存在系统性缺陷。

什么是编码代理的“Harness”？

Harness，即围绕AI模型构建的整套支撑系统，包括提示词模板、工具调用接口、上下文管理、错误恢复机制以及反馈循环。它决定了模型如何感知任务、执行操作并从结果中学习。

一个设计糟糕的harness会让最聪明的模型显得愚蠢。例如，如果代理无法获取完整的代码库上下文，或者工具调用频繁失败却缺乏重试策略，那么无论模型多强大，最终产出都会大打折扣。这正是Lynch所质疑的现象背后的技术根源。

上下文窗口（Context Window） 是大语言模型单次推理能处理的 token 总量上限，涵盖输入提示词与已生成内容。在编码代理场景中，它直接决定了代理能“看到”多少代码、工单描述、测试输出和历史操作记录。窗口过小会遗漏关键依赖，导致修改破坏其他模块；窗口过大则引入大量无关文件，稀释注意力并推高成本与延迟。因此，harness 的核心任务之一就是做上下文预算分配：判断哪些信息必须常驻、哪些可按需检索、哪些应被压缩成摘要或符号化索引。常见的工程手段包括基于嵌入的语义检索、AST 级代码切片、依赖图裁剪以及滚动摘要。理解上下文窗口的硬约束，才能明白为什么“把整个仓库塞给模型”既不可行也不经济。

从工单到PR：实践中暴露的框架缺陷

该团队在真实项目中运行ticket-to-PR代理，这类代理需要理解工单描述、定位相关代码、编写修改并提交PR。过程中暴露出几个典型的harness问题：

• 上下文窗口管理粗放：代理往往被塞入过多无关文件，导致关键信息被淹没；或者上下文过短，遗漏必要依赖。
• 工具调用缺乏鲁棒性：文件读写、命令执行等基础操作失败后，代理缺乏有效的恢复路径，容易陷入死循环。
• 反馈信号稀疏：代理难以从测试失败或编译错误中提取可操作的修正信息，导致重复犯错。

这些问题并非模型能力缺陷，而是框架设计未能为模型提供足够友好的工作环境。

幂等性（Idempotency） 指同一操作执行一次与执行多次产生相同结果。对编码代理而言，文件写入、补丁应用、分支创建、PR 提交等动作如果缺乏幂等保证，重试就会导致重复插入、冲突覆盖或冗余提交。实践中代理常因网络抖动或工具超时进入“重试—半成功—再重试”的混乱状态，最终产出脏补丁。健壮的 harness 会把每个工具调用设计成可安全重放的原子操作，或引入显式状态检查点与事务回滚：执行前记录基线快照，失败后比对差异再决定回退或继续。幂等工具原语配合状态检查点，是让代理在不确定环境中保持可恢复性的工程基础。

为什么我们总爱责怪模型？

将问题归因于模型是一种认知捷径。模型能力容易量化，而harness的质量难以度量，因此容易被忽视。此外，模型厂商的宣传也倾向于强调模型本身的突破，弱化了配套框架的重要性。

这种归因偏差导致团队在优化代理时，频繁更换模型却收效甚微。真正需要投入精力的是harness的工程化：如何设计更精准的上下文检索、更健壮的工具抽象、更密集的学习信号。

构建更好Harness的方向

基于该团队的实践经验，改进harness可以从几个层面入手。上下文管理上，采用动态检索而非全量注入，让代理按需获取代码片段。工具层需要提供幂等、可重试的操作原语，并内置状态检查点。反馈机制方面，将测试输出、lint结果结构化后回传给模型，使其能进行针对性修正。

这些改进并不需要更强大的模型，而是需要更细致的工程设计。当harness足够成熟时，中等能力的模型也能在编码任务上表现优异。

结构化反馈（Structured Feedback） 指把测试、编译、lint、类型检查等工具的输出从自由文本转换为机器可解析的信号，例如带文件位置、行号、错误码、严重级别的 JSON 记录。原始日志往往冗长且噪声大，模型难以从中定位可操作的修正点。结构化后，harness 可以只回传与当前修改相关的诊断项，按严重程度排序，并附带修复建议，形成高密度的学习信号。更进一步，可将反馈与具体 diff 关联，让模型明确“哪一行改动导致了哪个失败”，从而进行针对性修正而非盲目重写。这一层设计直接决定了代理能否从错误中快速收敛。

对AI编程工具开发的启示

Lynch的质疑和该团队的实践共同指向一个结论：编码代理的效能是模型与harness的乘积。忽视harness而单纯追求模型升级，如同给赛车换上更强引擎却忽略了变速箱和轮胎。

对于正在构建AI编程工具的开发者而言，这意味着需要将更多资源投入到代理框架的打磨上。工具调用协议、上下文压缩策略、错误恢复逻辑，这些看似枯燥的工程细节，才是决定编码代理能否真正落地的关键。

未来，随着模型能力逐渐趋同，harness的质量将成为区分优秀与平庸编码代理的核心竞争力。那些率先解决框架问题的团队，将更早迎来真正可用的自动化编程助手。