編碼智能體 harness 設計實證：規劃、工具與上下文管理各有何用

论文研究什么

编码智能体不只是一个语言模型。模型运行在一层“harness”（外壳）之中：这是一层软件，包含控制循环、工具接口，以及决定模型保留哪些交互历史的规则。论文《An Empirical Study of Harness Design for Coding Agents》（arXiv 2609.20804，2026 年 9 月 17 日提交）要问的是：这一层里，到底哪些部分真正起作用。作者共九人，来自 UMass Amherst、Emory University 和 UNC Charlotte。论文注明，部分工作是在 Zoom Video Communications 实习期间完成的。

作者指出，此前的研究多把完整的 harness 当作整体来比较。他们引用了一项跨 harness 评测：Claude-Opus-4.5 在 OpenHands 上表现最好，而 Claude-Sonnet-4.5 在 SWE-Agent 上表现最好。这类结果说不清，收益究竟来自规划、工具设计、上下文管理，还是它们与模型的相互作用。因此作者从零搭建了一个轻量 harness。它的 ReAct 循环固定不变，只改变三个组件：规划（planning）、动作空间（action space）和上下文管理（context management）。权限处理、编辑后诊断和卡死检测在所有实验中保持不变。

实验设置

harness 基于 LangGraph 构建，基准测试通过 Harbor 运行。每个任务最多 300 步。论文测试四个模型：Nemotron-3 的三种规模（30B、120B、550B）以及 Mistral-Medium-3.5-128B。基准有两个：SWE-Bench Verified 含 500 个经人工验证的 GitHub issue，Terminal-Bench 2.1 含 89 个命令行任务。论文报告成功率和每任务平均成本，成本按 OpenRouter 价格计算。

上下文管理分五档。T0 不做任何处理，窗口溢出就报错终止。T1 把过期的工具输出换成简短占位符（elision，省略）。T2 在此基础上加入外部存储和 recall_event 工具，让被省略的内容可以读回。T3 只用 LLM 摘要。T4 分阶段组合三者：先省略，历史仍然太长时才做摘要。软、硬阈值分别是可用窗口的 0.6 和 0.85。五档策略分别在 32k、64k、96k、128k token 的窗口下运行。规划和动作空间（预定义工具对比仅用 bash）只在 T4、128k 窗口下做消融。合计 176 个匹配设置。作者用双侧精确 McNemar 检验比较成功率，并把错误发现率控制在 0.05。

四项发现与论文给出的数字

1. 窗口越紧，上下文管理越有价值。 对四个模型取平均，随着窗口从 32k 增至 128k，受管理档位（T1 至 T4）与 T0 的差距在 SWE-Bench 上从 35.7 降到 15.9、5.5、2.7 个百分点；在 Terminal-Bench 上从 9.5 降到 7.5、4.8、2.8。T0 的溢出失败率在 SWE-Bench 上从 78.7% 降到 8.7%，在 Terminal-Bench 上从 61.0% 降到 12.1%。所有受管理档位在每个预算下的溢出失败都是零。表 3 中的一个例子：32k 下，Nemotron-3 550B 在 SWE-Bench 上用 T0 得 6.40%，用 T4 得 55.60%。论文的结论是，多数收益来自避免过早截断。

2. 分阶段的“先省略、后摘要”（T4）效率最高，召回几乎没有增益。 T4 的成功率与 T1 至 T3 相近。它在八个“模型加基准”面板中有七个成本最低，并且在每个窗口预算下平均每任务成本都最低，四个预算下的峰值上下文占比也都最低。在 32k 下，T1 和 T2 的上下文仍会逼近整个窗口。召回机制则是另一回事。在 32 组匹配比较中，T2 胜 T1 共 15 次，败 14 次，平 3 次，平均差为负 0.36 个百分点。在 64 个设置中有 36 个（56.3%）模型从未调用 recall_event。每任务平均召回次数从 32k 下的 0.540 降到 128k 下的 0.007。 3. 规划从“准确率脚手架”变成“成本节省器”。 对 Nemotron-3 30B，规划使 SWE-Bench 成功率提高 11.6 个百分点，Terminal-Bench 提高 4.5 个百分点，但成本更高。对 120B 模型，没有一致的增益。对 Nemotron-3 550B 和 Mistral-Medium-3.5-128B，规划把 SWE-Bench 成本分别降低约 30% 和 32%，成功率分别下降 2.0 和 0.4 个百分点。 4. 最佳动作空间取决于模型。 对 Nemotron-3 30B，预定义工具集使成功率在 SWE-Bench 上提高 15.0 个百分点，在 Terminal-Bench 上提高 10.1 个百分点。对 Nemotron-3 550B，仅用 bash 使成功率分别提高 3.6 和 5.6 个百分点，成本分别降低 53% 和 30%。Mistral 则喜忧参半：完整工具集在 SWE-Bench 上更好（高 23.2 个百分点），但仅用 bash 在 Terminal-Bench 上多得 6.7 个百分点。

轨迹分析说明了什么

作者还用 LLM 评判器给每个回合标注了工作流阶段。这些标注解释了上面四项发现。 上下文管理主要让运行变长。在 32k 且无管理时，SWE-Bench 的中位轨迹只有 20 至 30 回合，多数运行停在定位问题的阶段。有管理时，中位长度升到约 50 至 180 回合，运行能走到验证阶段。 规划对弱模型和强模型作用不同。对 Nemotron-3 30B，在 SWE-Bench 上关掉规划，中位轨迹从 40 回合降到 5 回合。没有规划时，68.6% 的运行没有做任何编辑，有规划时是 27.8%。对两个最强的模型，规划把中位轨迹从 108 缩短到 74 回合（550B），从 68 缩短到 53 回合（Mistral）。作者把其中大部分归因于编辑后验证的减少。

动作空间改变了代码的写法。对 Nemotron-3 30B 在 Terminal-Bench 上，66% 的仅 bash 运行在模型发出仅 bash 注册表中并不存在的工具调用后终止，平均轨迹从 71 回合缩到 15 回合。对 550B 模型在 Terminal-Bench 上，仅用 bash 使中位轨迹从 47 步缩到 31 步，写代码动作的占比从 16% 升到 27%。对已编辑文件的重复补丁在四个模型上都减少了，例如 30B 从 3.3 降到 0.4。

我们的分析

我们的理解是，这篇论文的主旨在于“条件”，而不在于“赢家”。每一项发现都带着一个“如果”：如果窗口很紧，如果模型较弱，如果模型精通 bash。单一的默认 harness 无法同时适配这些情形。凡是报告“harness A 优于 harness B”的人，也应当写明模型、预算和任务类型。

第二个主题是，额外的机制并不免费。召回工具增加了机制，模型却很少使用。预定义工具帮助了弱模型，对强模型却似乎带来了额外负担，用作者的话说是“动作选择和交互开销”。同时，结果并没有说“越简单越好”。仅用 bash 使 550B 模型的成本近乎减半，却严重伤害了 30B 模型，也伤害了 Mistral 在 SWE-Bench 上的表现。

第三点关于成本。美元数字取决于 2026 年 8 月的 OpenRouter 价格和这几个具体模型。规划后回合数减少这样的方向性结论，比美元数值更容易迁移。

局限与未解问题

作者自己列出了几项局限。结论只针对他们实现的具体组件，并非普适最优的 harness。规划和动作空间只在 T4、128k 窗口下做了消融，要检验其他组合需要完整的因子实验。每个设置对每个任务只运行一次。Terminal-Bench 只有 89 个任务，因此那里许多对比在 McNemar 检验下不显著，作者依靠跨模型、跨预算的一致方向来下结论。SWE-Bench Verified 只含 Python。模型规模只是能力的不完美代理，作者说这些交叉点应当先验证，再用于其他模型家族、harness 或任务。他们还指出，动作空间的改动打包了多个因素：工具可用性、提示词、文件状态跟踪和自动诊断。

只读论文文本，我们再补两点。我们没有运行代码，也没有复核表格。此外，研究使用的是一个开放权重家族加另一个模型，对许多商业编码工具所用的闭源前沿模型没有任何说明。

给读者的实用建议

对构建编码智能体的团队，这篇论文提示几个习惯。在添加复杂的记忆功能之前，先测量长任务多久触及一次上下文上限，因为论文发现多数收益来自避免溢出。在为 LLM 摘要付费之前，先试试便宜的基于规则的省略。

不要假定召回工具会被使用，要查看调用日志。对每个模型单独测试规划，因为它可能让弱模型成本上升，让强模型成本下降。对强模型试试仅用 bash 的接口，但对 shell 能力弱的模型保留结构化工具。最后，更换模型或上下文预算时，重新做这些检查。