切换深色模式
编程 Agent 的 Harness：观察、行动与反馈
对应 CS224V · 2026-11-11 · Coding Agents。日期为校方课表日期，可能调整。核对官方课表。
资料状态
核对日期：2026-09-19。对应课程尚未开课；本文是基于公开课纲与文中原始资料的原创预习技术解读，不是课堂实录、讲义翻译或官方作业答案。本文于 2026-09-20 深度修订。示例为原创教学设计；离线实验与真实模型实验的边界分别说明，不以推演冒充模型实测。
课程助手的版本过滤需要修复。CS329Z 从“怎样证明修复成立”讨论这个任务，本篇则固定模型，考察周围的运行环境：模型看见什么、能做什么、动作结果如何反馈。相同模型放入不同 Harness，可能表现出完全不同的定位和修复能力。
把一次编程操作拆成三个契约
观察契约规定返回文件内容、行号、版本和截断状态；动作契约规定允许怎样编辑、运行和回滚；反馈契约规定成功、失败与未知怎样表达。
SWE-agent 研究强调 Agent 与计算机交互接口的重要性。本文不复刻论文工具，而以版本过滤缺陷推导自己的协议。
例如读取文件应返回内容版本或哈希。随后编辑携带预期旧版本，执行器发现文件已被其他操作修改时拒绝应用。这比盲目按旧行号替换更能防止覆盖新改动。
text
read(file) → content、revision=7
edit(file, expected_revision=7, patch)
若当前 revision=8 → stale_revision，要求重新读取返回多少信息会改变下一步选择
测试失败日志可能有几万行。全部返回会耗费上下文，只给一句“失败”又无法定位。可返回退出码、失败测试名、关键断言、截断标记和完整日志引用。
摘要必须保持事实，不把“测试没有运行”改成“测试失败”。若摘要不足，模型可以按引用回读。这样的渐进读取将上下文预算用于当前需要的信息，同时保留排障能力。
日志引用需要绑定本次命令，不能指向不断被覆盖的 latest.log，否则下一轮可能读到另一次执行的结果。
编辑工具的安全性与效率有取舍
整文件覆盖接口简单，但容易丢掉未读取的修改；逐行操作精确，却可能需要很多轮，并受行号漂移影响。带预期上下文的补丁可以在效率与冲突检测之间取得平衡。
对于大文件，可以先搜索符号再读取局部区域。工具返回需要区分真实文件行号与显示片段编号，否则模型可能把第 5 个显示行当成文件第 5 行。
工具设计应围绕常见任务，而不是把终端所有能力直接交给模型。执行命令的目录、超时、输出大小和权限都属于协议。
将运行状态与模型会话分开
模型一轮结束不等于命令结束。异步测试应返回执行 ID，后续轮询拿到状态。命令仍运行时启动第二次同类测试，可能争用端口或修改同一测试数据。
进程重启后也要知道哪些命令已完成、哪些结果未知。状态记录保存命令 ID、环境与退出结果；对可能有副作用的命令不能仅靠“没有日志”判断没执行。
长任务 Harness 资料可补充跨执行阶段的连续性设计。这里仍需结合本仓库的具体工具语义验证。
拒绝旧补丁之后，恢复过程也要有契约
遇到 stale_revision 后，不应自动去掉版本检查再次执行。正确恢复是读取新内容，判断他人修改是否影响原补丁，再生成新的差异。否则所谓乐观并发控制只是在第一次尝试时检查，最终仍会覆盖其他人的工作。
补丁自身也可能包含多个修改点。如果前两个成功、第三个失败，执行器必须明确是全部回滚还是部分应用，并返回当前版本。模型若以为完全失败再次提交，会重复修改已经成功的部分。更容易推理的默认是先校验全部上下文，再原子应用单文件补丁；多文件事务则需额外设计，不能从单文件保证推导出来。
测试结果还要绑定被测内容。第 8 版通过测试后又发生第 9 版编辑，不能继续拿第 8 版的绿色结果为当前交付背书。保存被测提交、文件摘要或工作区快照标识，才能建立“这个结果验证了哪些改动”的关系。
这些接口增加了一些元数据，却减少了模型需要猜测的隐含状态。Harness 的效率应按完成正确修复的总代价评估，而不是只比较一次工具调用的响应长度。
优化 Harness 时固定哪些变量
建立三种观察方式：完整日志、纯摘要、摘要加回读引用。保持模型、任务、初始仓库和总预算一致，比较定位步骤、正确修复、误编辑、成本与耗时。
若纯摘要更快但经常遗漏真正异常，说明节省上下文牺牲了必要信息。若完整日志造成更多无关修改，可能需要过滤和分层读取。结果应按任务类型拆分，而不是只报告一个平均分。
修改工具协议后，还要更新校验与错误反馈，不能只改提示词期待模型适应未说明的语义。
避免针对固定测试环境过拟合
Agent 可能学会固定文件位置或测试名，而不是一般修复策略。用路径变化、等价错误和不同日志长度测试其适应性。还应防止它直接修改测试结果或绕过验收入口。
自动搜索 Harness 配置时，同样需要开发与独立测试任务。把最容易让当前基准通过的工具设计成生产默认值，可能在真实仓库中隐藏重要输出。
本讲的结论不是“越丰富的工具越好”，而是每个接口都应提供足够且可核实的信息，使合法动作和恢复路径清楚。下一讲将观察对象从代码文本换成文档图像，进一步讨论信息在感知阶段怎样丢失。继续阅读文档转录。