编码智能体执行框架Harness设计实证研究arXiv编号arXiv:2609.20804v1 [cs.AI]摘要编码智能体执行框架coding harness决定大模型如何把模型原生能力转化为长视界软件工程任务性能。现有工作大多将执行框架作为完整黑盒系统做评测各个独立组件的实际贡献缺少量化对比。本文搭建一套轻量化模块化编码智能体执行框架固定主执行循环只改变三大核心组件规划模块、动作空间、上下文管理策略。实验选用4个大模型在SWE‑Bench Verified、Terminal‑Bench 2.1两大基准上一共覆盖176组对照配置包含5套上下文管理策略、4种上下文窗口预算并对规划、动作空间开展定向消融。主要发现上下文管理的收益随上下文窗口预算收紧而显著提升核心价值是避免上下文溢出造成任务提前终止先做规则式内容省略、再调用大模型摘要T4分级策略在全部上下文管理策略中取得最优综合精度‑开销权衡给被省略内容增加可恢复召回机制模型极少调用该能力没有带来准确率提升规划模块对弱模型是精度增强脚手架对强模型主要起到降低开销的作用对最终成功率影响很小预定义工具集可以提升bash能力较弱模型的性能擅长bash的模型仅依靠bash接口即可有效工作并且显著降低开销在以命令行为主的任务上收益尤为明显。轨迹层面分析解释背后机制上下文管理主要延长执行轨迹长度但几乎不改变智能体行为模式规划模块改变轨迹终止时机动作空间改变代码编辑的操作粒度。本文结论可以指导面向模型能力、资源预算感知的执行框架设计同时提供一套模块化底座用于未来新组件的对比评测。关键词编码智能体执行框架Harness上下文管理规划动作空间SWE‑BenchTerminal‑Bench目录引言执行框架Harness整体设计2.1 规划模块2.2 动作空间2.3 上下文管理2.4 其余固定组件2.4.1 安全机制2.4.2 编辑后诊断2.4.3 卡死检测实验3.1 实验设置3.1.1 模型3.1.2 评测基准3.1.3 实现细节3.1.4 消融实验配置3.2 主要实验结果分析相关工作5.1 编码智能体5.2 编码智能体执行框架5.3 上下文管理结论参考文献附录A 执行框架全套提示词A.1 系统提示词A.2 规划模块提示词A.3 上下文管理提示词A.4 卡死检测提示词附录B 工具完整说明附录C 轨迹分析1 引言大语言模型已经可以自主处理真实软件工程任务解决GitHub Issue、完成端到端终端任务。这类能力依靠编码智能体执行框架coding harness这一层软件组件干预智能体的完整行为规划脚手架维护任务结构动作接口将模型意图转为可执行操作上下文管理策略在有限窗口约束下保留交互历史。固定模型仅修改执行框架就可以显著改变任务成功率。但目前绝大多数研究把整套执行框架作为完整系统做对比。不同框架之间性能差异无法区分收益来自规划逻辑、工具设计、上下文管理还是组件之间的交互效应。由此引出核心研究问题各个执行框架组件是普适有效还是效果依赖模型能力、任务类型、资源预算本文构建一套模块化编码执行框架固定主ReAct执行循环仅改变三大可消融组件规划模块、动作空间、上下文管理安全权限、编辑后诊断、卡死检测等其余组件全部保持不变作为统一底层执行基座。规划模块维护一份可在轨迹中持续更新的显式任务计划动作空间两种模式①预定义工具集②仅bash命令接口上下文管理设计5套策略T0‑T4T0无管理T1规则省略过期工具输出T2增加外部存储事件召回T3纯LLM摘要T4分级策略先规则省略再做摘要。实验选用Nemotron‑330B / 120B / 550B同家族不同规模模型外加Mistral‑Medium‑3.5‑128B跨家族模型评测基准SWE‑Bench Verified、Terminal‑Bench 2.1上下文窗口预算设置32k / 64k / 96k / 128k一共176组对照实验。除成功率、开销指标外开展细粒度轨迹分析观测各个干预如何改变任务推进、终止行为、上下文使用、工具调用模式。本文核心贡献搭建可消融模块化编码智能体执行框架将规划、动作空间、上下文管理解耦隔离各个组件的独立效应大规模实证176组配置揭示组件效果依赖上下文窗口预算、模型能力强弱、任务类型的条件性规律轨迹层面解释机制上下文管理延长轨迹、规划改变终止点、动作空间改变代码编辑粒度提供可复用底座与提示词脚本支撑未来编码智能体组件的受控评测。2 执行框架Harness整体设计整套框架遵循标准ReAct循环每一轮依次执行推理步骤 → 执行动作 → 获取观测。固定容器环境、安全沙箱、卡死检测、编辑诊断只对规划、动作空间、上下文管理做变量控制。2.1 规划模块开启规划模块系统提示定义协议第一轮要求模型输出初始任务规划模型可调用update_plan工具在轨迹过程中修改计划。计划内容注入每一轮模型输入不存入普通对话历史。关闭规划模块移除全部规划相关提示、注入逻辑、update_plan工具其余执行逻辑完全不变。本实验评估的是持久化规划脚手架组件的效果不是广义上模型内部思考规划能力。2.2 动作空间两套动作接口预定义工具集模式提供read_file、write_file、edit_file、list_files、glob_files、grep_text、web_fetch、bash每个工具带类型参数schema附带错误与副作用说明文件工具强制读‑写校验编辑之后自动触发诊断。仅bash模式移除全部预定义文件、检索、网页工具仅保留bash规划、上下文管理所必需的辅助工具update_plan、recall_event依然保留。该对比包含整套接口差异工具集合、指令、状态追踪、编辑校验不只是工具数量差异。工具只读主要参数说明文件IOread_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, pathglob模式匹配文件grep_text✅query, path, include正则搜索文件内容执行bash❌command, timeout_seconds, cwd执行shell命令网页web_fetch✅url, format获取网页文本/markdown规划辅助update_plan❌plan创建/更新任务计划上下文管理辅助recall_event✅id读取外部存储中历史事件原始内容T2/T42.3 上下文管理5套上下文管理策略T0无管理不做任何轮次间压缩一旦超过上下文窗口直接终止轨迹。T1Elision省略规则性省略过期的大体积工具返回观测保留指令与近期交互。T2Elision Recall在T1基础上增加外部存储与recall_event召回工具被省略内容可以恢复读取。T3Summarization摘要仅使用大模型摘要不做规则省略。T4分级策略ElisionRecallSummarization先执行规则省略软阈值B 1 B_1B1把大体积中间输出置换为占位符原始内容存入外部存储超过硬阈值B 2 B_2B2对最老的中间事件执行LLM摘要开头系统提示、最近若干轮交互保持原文不压缩。T4完整流程达到软阈值B 1 B_1B1大体积工具输出替换简短占位符原始内容off‑load到外部存储可通过recall_event(id)恢复上下文继续增长达到硬阈值B 2 B_2B2对最老的一批中间事件调用LLM做摘要系统前缀、最近N轮交互永远保持原文不压缩。2.4 其余固定组件2.4.1 安全机制容器沙箱执行所有工具调用权限隔离禁止高危系统操作所有实验复用同一套安全配置。2.4.2 编辑后诊断文件编辑完成自动运行基础检查语法校验、编译、单元测试调用输出诊断观测返回智能体。两套动作空间模式下诊断逻辑保持一致。2.4.3 卡死检测监控轨迹重复行为、循环调用工具、长时间没有实质进展触发卡死检测输出结构化提示给到模型到达最大轮次上限强制终止。3 实验3.1 实验设置3.1.1 模型Nemotron‑330B、120B、550B同家族能力梯度Mistral‑Medium‑3.5‑128B跨家族对照模型3.1.2 评测基准SWE‑Bench Verified仓库级GitHub Issue缺陷修复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 消融实验配置上下文管理消融4种窗口 × 5种策略在128k窗口、T4上下文策略基础上做规划开关消融、动作空间开关消融合计176组独立实验配置。3.2 主要实验结果上下文窗口越紧张上下文管理收益越高T0无管理策略在32k大量样本直接上下文溢出、任务提前失败随着窗口扩大128k不同上下文策略之间成功率差距大幅缩小。上下文管理的主要贡献是避免溢出导致提前终止让智能体可以走到代码修改与验证阶段。T4分级策略取得最优精度‑开销权衡T4先省略后摘要对比其他策略维持相当平均成功率同时压低峰值上下文减少摘要调用频次。T2增加的recall_event召回机制在实验中极少被模型调用对比纯T1省略策略没有带来准确率提升。规划模块的条件效应弱模型规划是精度脚手架维持轨迹存活足够久以尝试代码编辑提升成功率代价增加开销强模型规划主要用来消除冗余的编辑后验证步骤降低开销对成功率影响很小。动作空间条件效应bash能力弱的模型预定义工具集提升任务成功率bash能力强的模型仅bash模式可以一次完成多条操作交互轮次更少显著降低开销在终端类任务收益尤其突出。4 分析轨迹层面统计得到机制性解释上下文管理主要作用是延长可执行轨迹总长度几乎不改变智能体本身行为模式128k大窗口条件下不同上下文策略轨迹形态高度接近。规划模块对最弱模型延长轨迹存活时间保证能够执行编辑动作对强模型改变轨迹终止位置减少冗余的事后验证步骤缩短SWE‑Bench轨迹Terminal‑Bench的开销变化取决于轨迹长度分布重塑效果。动作空间bash‑only提升单次动作的代码编写体量减少交互轮次。失败阶段归因统计SWE‑Bench任务的失败分布行为编码统计Terminal‑Bench动作级编码统计召回事件实际调用频次极低。5 相关工作5.1 编码智能体SWE‑Agent、OpenHands等编码智能体系统结合规划、工具调用、上下文管理解决软件工程任务大多将整套Harness作为完整系统评估难以定位组件贡献。5.2 编码智能体执行框架现有框架实现各不相同工具定义、规划范式、上下文压缩策略差异巨大跨框架对比只能得到整体效果无法解耦单个组件的因果效应。本工作提供受控消融的模块化底座。5.3 上下文管理分为有损省略、摘要、无损外部存储召回两类有损压缩可能丢弃后续有用信息无损方案依赖模型主动调用召回接口。本文对比5套策略在编码长视界任务上的实际表现发现召回接口很少被模型实际使用。6 结论本文对编码智能体执行框架三大核心组件开展大规模消融实证。上下文管理收益高度依赖窗口预算窗口越小收益越大T4分级先规则省略后摘要综合最优可恢复召回机制极少被模型使用无精度增益。规划组件效果取决于模型能力弱模型用来提升成功率强模型主要用来降本。动作空间存在条件权衡弱模型受益预定义工具集强bash能力模型使用纯bash接口可以显著降低开销。轨迹分析揭示背后机制上下文管理延长轨迹规划改变终止时机动作空间改变操作粒度。本工作的模块化框架、全套提示脚本可以为未来编码智能体组件评测提供实验底座。未来方向研究更多组件错误恢复、多轮反思拓展更多模型家族、更多类型软件工程任务。7 参考文献完整参考文献参见原文网页https://arxiv.org/html/2609.20804v1附录A 执行框架全套提示词A.1 系统提示词预定义工具集 / bash‑only两套系统prompt完整文本定义工具调用格式、输出约束、沙箱行为。A.2 规划模块提示词开启规划模块的第一轮提醒promptupdate_plan工具描述规划内容注入输入的组装逻辑。A.3 上下文管理提示词T1‑T4策略对应的系统提示包含recall_event工具说明阈值参数说明。A.4 卡死检测提示词卡死检测判断prompt触发卡死之后给到模型的结构化反馈提示。附录B 工具完整说明全部工具的自然语言完整描述、参数约束、读写属性、副作用recall_event、update_plan辅助工具完整文档。附录C 轨迹分析标注方案SWE‑Bench失败阶段归因SWE‑Bench行为编码Terminal‑Bench动作级编码评判设置与人工校验SWE‑Bench轨迹实验结果失败阶段统计、行为画像Terminal‑Bench轨迹结果128k窗口下轨迹统计Recall‑Event实际调用频次统计Judge评判器完整提示词。
