编码智能体执行框架（Harness）设计实证研究

编码智能体执行框架（Harness）设计实证研究

arXiv编号：arXiv:2609.20804v1 [cs.AI]

摘要
编码智能体执行框架（coding harness）决定大模型如何把模型原生能力转化为长视界软件工程任务性能。现有工作大多将执行框架作为完整黑盒系统做评测，各个独立组件的实际贡献缺少量化对比。本文搭建一套轻量化模块化编码智能体执行框架，固定主执行循环，只改变三大核心组件：规划模块、动作空间、上下文管理策略。
实验选用4个大模型，在SWE‑Bench Verified、Terminal‑Bench 2.1两大基准上，一共覆盖176组对照配置，包含5套上下文管理策略、4种上下文窗口预算，并对规划、动作空间开展定向消融。主要发现：

1. 上下文管理的收益随上下文窗口预算收紧而显著提升，核心价值是避免上下文溢出造成任务提前终止；
2. 先做规则式内容省略、再调用大模型摘要（T4分级策略），在全部上下文管理策略中取得最优综合精度‑开销权衡；给被省略内容增加可恢复召回机制，模型极少调用该能力，没有带来准确率提升；
3. 规划模块对弱模型是精度增强脚手架，对强模型主要起到降低开销的作用，对最终成功率影响很小；
4. 预定义工具集可以提升bash能力较弱模型的性能；擅长bash的模型仅依靠bash接口即可有效工作，并且显著降低开销，在以命令行为主的任务上收益尤为明显。

轨迹层面分析解释背后机制：上下文管理主要延长执行轨迹长度，但几乎不改变智能体行为模式；规划模块改变轨迹终止时机；动作空间改变代码编辑的操作粒度。本文结论可以指导面向模型能力、资源预算感知的执行框架设计，同时提供一套模块化底座，用于未来新组件的对比评测。

关键词
编码智能体；执行框架Harness；上下文管理；规划；动作空间；SWE‑Bench；Terminal‑Bench

目录

1. 引言
2. 执行框架Harness整体设计
   • 2.1 规划模块
   • 2.2 动作空间
   • 2.3 上下文管理
   • 2.4 其余固定组件
     • 2.4.1 安全机制
     • 2.4.2 编辑后诊断
     • 2.4.3 卡死检测
3. 实验
   • 3.1 实验设置
     • 3.1.1 模型
     • 3.1.2 评测基准
     • 3.1.3 实现细节
     • 3.1.4 消融实验配置
   • 3.2 主要实验结果
4. 分析
5. 相关工作
   • 5.1 编码智能体
   • 5.2 编码智能体执行框架
   • 5.3 上下文管理
6. 结论
7. 参考文献
8. 附录A 执行框架全套提示词
   • A.1 系统提示词
   • A.2 规划模块提示词
   • A.3 上下文管理提示词
   • A.4 卡死检测提示词
9. 附录B 工具完整说明
10. 附录C 轨迹分析

1 引言

大语言模型已经可以自主处理真实软件工程任务：解决GitHub Issue、完成端到端终端任务。这类能力依靠编码智能体执行框架（coding harness），这一层软件组件干预智能体的完整行为：规划脚手架维护任务结构；动作接口将模型意图转为可执行操作；上下文管理策略在有限窗口约束下保留交互历史。固定模型，仅修改执行框架，就可以显著改变任务成功率。

但目前绝大多数研究把整套执行框架作为完整系统做对比。不同框架之间性能差异，无法区分收益来自规划逻辑、工具设计、上下文管理，还是组件之间的交互效应。由此引出核心研究问题：各个执行框架组件是普适有效，还是效果依赖模型能力、任务类型、资源预算？

本文构建一套模块化编码执行框架，固定主ReAct执行循环，仅改变三大可消融组件：规划模块、动作空间、上下文管理；安全权限、编辑后诊断、卡死检测等其余组件全部保持不变，作为统一底层执行基座。

• 规划模块：维护一份可在轨迹中持续更新的显式任务计划；
• 动作空间：两种模式：①预定义工具集；②仅bash命令接口；
• 上下文管理：设计5套策略T0‑T4；T0无管理；T1规则省略过期工具输出；T2增加外部存储+事件召回；T3纯LLM摘要；T4分级策略：先规则省略，再做摘要。

实验选用Nemotron‑3（30B / 120B / 550B）同家族不同规模模型，外加Mistral‑Medium‑3.5‑128B跨家族模型；评测基准SWE‑Bench Verified、Terminal‑Bench 2.1；上下文窗口预算设置32k / 64k / 96k / 128k；一共176组对照实验。除成功率、开销指标外，开展细粒度轨迹分析，观测各个干预如何改变任务推进、终止行为、上下文使用、工具调用模式。

本文核心贡献

1. 搭建可消融模块化编码智能体执行框架，将规划、动作空间、上下文管理解耦，隔离各个组件的独立效应；
2. 大规模实证176组配置，揭示组件效果依赖上下文窗口预算、模型能力强弱、任务类型的条件性规律；
3. 轨迹层面解释机制：上下文管理延长轨迹、规划改变终止点、动作空间改变代码编辑粒度；
4. 提供可复用底座与提示词脚本，支撑未来编码智能体组件的受控评测。

2 执行框架Harness整体设计

整套框架遵循标准ReAct循环：每一轮依次执行推理步骤 → 执行动作 → 获取观测。固定容器环境、安全沙箱、卡死检测、编辑诊断；只对规划、动作空间、上下文管理做变量控制。

2.1 规划模块

开启规划模块：系统提示定义协议；第一轮要求模型输出初始任务规划；模型可调用update_plan工具在轨迹过程中修改计划。计划内容注入每一轮模型输入，不存入普通对话历史。
关闭规划模块：移除全部规划相关提示、注入逻辑、update_plan工具；其余执行逻辑完全不变。

本实验评估的是持久化规划脚手架组件的效果，不是广义上模型内部思考规划能力。

2.2 动作空间

两套动作接口：

1. 预定义工具集模式：提供read_file、write_file、edit_file、list_files、glob_files、grep_text、web_fetch、bash；每个工具带类型参数schema，附带错误与副作用说明；文件工具强制读‑写校验，编辑之后自动触发诊断。
2. 仅bash模式：移除全部预定义文件、检索、网页工具；仅保留bash；规划、上下文管理所必需的辅助工具（update_plan、recall_event）依然保留。

该对比包含整套接口差异：工具集合、指令、状态追踪、编辑校验，不只是工具数量差异。

工具	只读	主要参数	说明
文件IO
read_file	✅	path, offset, limit	读取文件，返回带行号内容
write_file	❌	path, content, overwrite	新建/覆盖文件
edit_file	❌	path, old_text, new_text, replace_all	文件内精确字符串替换
检索
list_files	✅	path, recursive	列出目录
glob_files	✅	pattern, path	glob模式匹配文件
grep_text	✅	query, path, include	正则搜索文件内容
执行
bash	❌	command, timeout_seconds, cwd	执行shell命令
网页
web_fetch	✅	url, format	获取网页文本/markdown
规划辅助
update_plan	❌	plan	创建/更新任务计划
上下文管理辅助
recall_event	✅	id	读取外部存储中历史事件原始内容（T2/T4）

2.3 上下文管理

5套上下文管理策略：

• T0：无管理，不做任何轮次间压缩；一旦超过上下文窗口直接终止轨迹。
• T1：Elision省略：规则性省略过期的大体积工具返回观测，保留指令与近期交互。
• T2：Elision + Recall：在T1基础上增加外部存储与recall_event召回工具；被省略内容可以恢复读取。
• T3：Summarization摘要：仅使用大模型摘要，不做规则省略。
• T4：分级策略（Elision+Recall+Summarization）：先执行规则省略（软阈值B 1 B_1B1​），把大体积中间输出置换为占位符，原始内容存入外部存储；超过硬阈值B 2 B_2B2​，对最老的中间事件执行LLM摘要；开头系统提示、最近若干轮交互保持原文不压缩。

T4完整流程：

1. 达到软阈值B 1 B_1B1​：大体积工具输出替换简短占位符，原始内容off‑load到外部存储，可通过recall_event(id)恢复；
2. 上下文继续增长达到硬阈值B 2 B_2B2​：对最老的一批中间事件调用LLM做摘要；
3. 系统前缀、最近N轮交互永远保持原文，不压缩。

2.4 其余固定组件

2.4.1 安全机制

容器沙箱执行所有工具调用；权限隔离；禁止高危系统操作；所有实验复用同一套安全配置。

2.4.2 编辑后诊断

文件编辑完成自动运行基础检查：语法校验、编译、单元测试调用；输出诊断观测返回智能体。两套动作空间模式下诊断逻辑保持一致。

2.4.3 卡死检测

监控轨迹重复行为、循环调用工具、长时间没有实质进展；触发卡死检测输出结构化提示给到模型；到达最大轮次上限强制终止。

3 实验

3.1 实验设置

3.1.1 模型

• Nemotron‑3：30B、120B、550B（同家族，能力梯度）
• Mistral‑Medium‑3.5‑128B：跨家族对照模型

3.1.2 评测基准

1. SWE‑Bench Verified：仓库级GitHub Issue缺陷修复；
2. Terminal‑Bench 2.1：端到端Linux终端任务。

3.1.3 实现细节

• 运行环境：Docker容器沙箱；
• 上下文窗口预算：32k / 64k / 96k / 128k；
• 全部5套上下文策略T0‑T4；
• 最大交互轮次上限统一；
• 评估指标：任务成功率、token开销；轨迹统计：工具调用、终止原因、编辑行为；
• 判定：SWE‑Bench使用官方diff校验；Terminal‑Bench使用基准自带评测器。

3.1.4 消融实验配置

1. 上下文管理消融：4种窗口 × 5种策略；
2. 在128k窗口、T4上下文策略基础上，做规划开关消融、动作空间开关消融；
   合计176组独立实验配置。

3.2 主要实验结果

1. 上下文窗口越紧张，上下文管理收益越高
   T0无管理策略在32k大量样本直接上下文溢出、任务提前失败；随着窗口扩大（128k），不同上下文策略之间成功率差距大幅缩小。上下文管理的主要贡献是避免溢出导致提前终止，让智能体可以走到代码修改与验证阶段。

2. T4分级策略取得最优精度‑开销权衡
   T4（先省略后摘要）对比其他策略，维持相当平均成功率，同时压低峰值上下文，减少摘要调用频次。

T2增加的recall_event召回机制在实验中极少被模型调用，对比纯T1省略策略，没有带来准确率提升。

3. 规划模块的条件效应

• 弱模型：规划是精度脚手架，维持轨迹存活足够久以尝试代码编辑，提升成功率，代价增加开销；
• 强模型：规划主要用来消除冗余的编辑后验证步骤，降低开销，对成功率影响很小。

4. 动作空间条件效应

• bash能力弱的模型：预定义工具集提升任务成功率；
• bash能力强的模型：仅bash模式可以一次完成多条操作，交互轮次更少，显著降低开销；在终端类任务收益尤其突出。

4 分析

轨迹层面统计得到机制性解释：

1. 上下文管理：主要作用是延长可执行轨迹总长度，几乎不改变智能体本身行为模式；128k大窗口条件下，不同上下文策略轨迹形态高度接近。
2. 规划模块：对最弱模型，延长轨迹存活时间，保证能够执行编辑动作；对强模型，改变轨迹终止位置，减少冗余的事后验证步骤，缩短SWE‑Bench轨迹；Terminal‑Bench的开销变化取决于轨迹长度分布重塑效果。
3. 动作空间（bash‑only）：提升单次动作的代码编写体量，减少交互轮次。

失败阶段归因统计：SWE‑Bench任务的失败分布；行为编码统计；Terminal‑Bench动作级编码统计；召回事件实际调用频次极低。

5 相关工作

5.1 编码智能体

SWE‑Agent、OpenHands等编码智能体系统，结合规划、工具调用、上下文管理解决软件工程任务；大多将整套Harness作为完整系统评估，难以定位组件贡献。

5.2 编码智能体执行框架

现有框架实现各不相同：工具定义、规划范式、上下文压缩策略差异巨大；跨框架对比只能得到整体效果，无法解耦单个组件的因果效应。本工作提供受控消融的模块化底座。

5.3 上下文管理

分为有损（省略、摘要）、无损（外部存储召回）两类；有损压缩可能丢弃后续有用信息；无损方案依赖模型主动调用召回接口。本文对比5套策略在编码长视界任务上的实际表现，发现召回接口很少被模型实际使用。

6 结论

本文对编码智能体执行框架三大核心组件开展大规模消融实证。

1. 上下文管理收益高度依赖窗口预算：窗口越小收益越大；T4分级（先规则省略，后摘要）综合最优；可恢复召回机制极少被模型使用，无精度增益。
2. 规划组件效果取决于模型能力：弱模型用来提升成功率；强模型主要用来降本。
3. 动作空间存在条件权衡：弱模型受益预定义工具集；强bash能力模型使用纯bash接口可以显著降低开销。

轨迹分析揭示背后机制：上下文管理延长轨迹；规划改变终止时机；动作空间改变操作粒度。本工作的模块化框架、全套提示脚本可以为未来编码智能体组件评测提供实验底座。

未来方向：研究更多组件（错误恢复、多轮反思）；拓展更多模型家族、更多类型软件工程任务。

7 参考文献

完整参考文献参见原文网页：https://arxiv.org/html/2609.20804v1

附录A 执行框架全套提示词

A.1 系统提示词

预定义工具集 / bash‑only两套系统prompt完整文本，定义工具调用格式、输出约束、沙箱行为。

A.2 规划模块提示词

开启规划模块的第一轮提醒prompt；update_plan工具描述；规划内容注入输入的组装逻辑。

A.3 上下文管理提示词

T1‑T4策略对应的系统提示，包含recall_event工具说明，阈值参数说明。

A.4 卡死检测提示词

卡死检测判断prompt；触发卡死之后给到模型的结构化反馈提示。

附录B 工具完整说明

全部工具的自然语言完整描述、参数约束、读写属性、副作用；recall_event、update_plan辅助工具完整文档。

附录C 轨迹分析

1. 标注方案
   • SWE‑Bench失败阶段归因；
   • SWE‑Bench行为编码；
   • Terminal‑Bench动作级编码；
2. 评判设置与人工校验；
3. SWE‑Bench轨迹实验结果：失败阶段统计、行为画像；
4. Terminal‑Bench轨迹结果；
5. 128k窗口下轨迹统计；
6. Recall‑Event实际调用频次统计；
7. Judge评判器完整提示词。

---