The Devil Is in the Interface: Evaluating How Tool Architecture Shapes Coding Agent Behavior 精读

• 论文链接：The Devil Is in the Interface: Evaluating How Tool Architecture Shapes Coding Agent Behavior（COLM 2026）
• 代码仓库：https://github.com/XZ-X/tool-arch-study.git
• 发表时间：2026年8月（arXiv:2608.11386v1，2026-08-11提交）
• 机构：普渡大学 + 微软研究院 + 芝加哥大学（企业界与高校合作；一作 Xiangzhe Xu 在微软研究院实习期间完成主要工作）
• 领域标签：编码智能体、工具设计、Harness 工程、Agent 评测

一、论文背景

先从最基础的概念说起。编码智能体是一类以 LLM 为大脑、以软件仓库为工作环境的智能系统：给它一个 issue 描述和一个代码仓库快照，它要自己找到相关文件、理解代码、做出修改、跑测试，最终产出一个能通过隐藏测试用例的补丁。现在大家熟悉的 Claude Code、OpenHands、SWE-Agent 都属于这一类。

智能体要完成这些动作，离不开工具。工具决定了智能体如何访问信息（怎么搜代码、怎么看文件）以及如何在环境中采取行动（怎么改文件、怎么执行命令）。可以说，工具是智能体与外部世界之间的"桥梁"。

论文把工具设计拆成两个问题：

• 第一个问题：给智能体什么能力？ 即智能体能获取哪些信息、能执行哪些动作。比如给它一个语义检索引擎（基于嵌入向量搜代码），它就多了一种"原本没有"的能力。
• 第二个问题：这些能力以什么方式呈现给模型？ 同样是"搜索代码"这个能力，可以用自由的 bash 命令表达，可以用封装好的原子工具表达，可以用自然语言查询表达，甚至可以用写一段可执行代码来表达。能力相同，呈现方式（接口）不同。

前者是主流研究方向——程序分析模块、语义索引、多方案对比机制，都在"加能力"。而后者，论文称之为工具架构，即"能力如何组织和暴露给模型"，长期以来缺乏系统性的实证研究。

为什么第二个问题被忽视了？ 论文给出了一个很实际的观察：在真实系统中，能力和架构往往是纠缠在一起的。一个语义检索工具既引入了嵌入检索的新能力，又同时把 grep 式底层交互换成了自然语言接口——两件事一起变了。如果它提升了性能，你根本说不清增益来自新能力还是新接口。归因困难，导致"接口本身的效应"成了被忽略的盲区。

这篇论文的核心贡献，就是用一个精心设计的受控实验把这两个变量拆开，单独度量工具架构的影响。

二、论文定位和关联工作

论文借用了软件工程领域的经典类比（Parnas 1972 等工作）：软件架构与"功能"是互补的——功能描述系统"做什么"，架构描述系统"如何组织"，而架构深刻影响鲁棒性、可维护性等非功能属性。同理，工具能力对应功能，工具架构对应软件架构，架构影响的是智能体的一致性（重复运行是否稳定）、探索（搜索上下文是否充分）和效率（步数与 token 消耗）这些"非功能属性"。

在工具学习的大谱系里，已有工作可以粗分为三类，本文与它们都不同：

一句话定位：本文是第一个把"工具架构"本身当作实验变量、在能力近似等价条件下做系统受控研究的工作，连接了工具学习研究与智能体可靠性研究两条线。

三、问题定义

论文要回答的研究问题可以抽象为：在底层信息与动作能力保持等价的前提下，接口的结构本身会如何改变智能体的行为？

这个问题的形式化实验设计是：

• 自变量：6 种工具架构（BashOnly / Atomic / NLSearch / Python / HypoTrack / Scratchpad）。
• 控制变量：所有架构都刻意实现成与 BashOnly 能力等价——不引入新信息、新动作。
• 因变量：四个维度的行为指标——任务解决率、一致性（pass^k）、探索多样性（Jaccard / CodeBLEU）、效率（输入/输出 token、步数）。
• 实验规模：3 个 actor 模型（Qwen3Coder-30B、Kimi K2.5、Claude Sonnet 4.5）× 6 种架构 × 65 个任务实例 × 每实例 10 次独立 rollout，共 11,700 条轨迹。

“能力等价"为什么是整个实验设计的关键？ 这是论文方法论上最讲究的地方：

1. Atomic 不扩展 bash 能力，只是把常用 shell 动作（grep、sed、heredoc 写文件等）重新封装成简单工具，附录 Table 3 给出了原子工具与 bash 命令的逐条映射（search ↔ grep/find/rg、str_replace ↔ sed -i、create ↔ heredoc 等）。
2. NLSearch 不用嵌入索引，而是一个与主模型相同的子智能体，接收自然语言查询后内部仍用 grep 之类的 bash 命令迭代搜索。所以它改变的是"查询的表达接口”，不是检索能力。
3. Python 不引入新动作——有 bash 的智能体本来就能写 Python 脚本再执行。作者人工检查了 100 个采样的 Python 动作，97 个都对应 BashOnly 中已有的操作（附录 B.5）。
4. 认知脚手架工具只接受文本——记录的内容本来也能写在推理文本里，不增加检索、记忆管理或新信息。

在这样的控制下，如果不同架构的行为指标出现系统差异，归因就清晰了：只能来自接口本身。

任务基准用的是 SWE-bench Live（一个污染受控的仓库级修 bug 基准），从中随机抽 25 个仓库、每仓库最多 5 个 issue，共 65 题。此外还用 SWE-bench Verified（修 bug）、SWE-bench Pro（功能实现）和一个带完整堆栈的调试子集做泛化验证。

四、问题解法

论文的"解法"就是六种架构的精心设计，每种都代表真实编码智能体中的主流设计选择（论文 Table 1 给出了对应关系）：

两个维度的设计意图值得展开：

• Atomic——受限的结构化接口。它不是"功能更多"，恰恰是"自由更少"：字符串替换工具只做针对性替换，文件查看工具只读有界区域。设计假设是：自由 shell 下模型要现场拼 sed/awk/heredoc，容易拼错；受限接口把这些错误模式直接堵死。
• NLSearch——自然语言中介。模型不再想"用什么正则去 grep"，而是直接问"哪里抛出了 CalledProcessError"。底层执行相同，但表达成本和表达习惯变了。
• Python——复合表达。一步可以同时遍历目录、检查多个文件、批量替换、写回——这些在 bash 架构下需要多轮工具调用。
• HypoTrack/Scratchpad——认知脚手架。意图是改变模型的"思考组织方式"：前者鼓励多假设分支管理，后者给推理草稿一个落脚点。

评测指标上最关键的设计是 pass^k。传统 pass@k 回答的是"k 次尝试里至少一次成功吗"——这对"多采样挑最好"的场景合适；但 pass^k 回答的是"k 次重复尝试全部成功吗"，即 C(c,k)/C(n,k)，它衡量重复运行的稳定性：只有每次都成功才等于 1，出现任何失败都拉低分数。论文取 k∈{5,7,9}。这个选择直指智能体落地最痛的点——用户要的是"能复现的成功"，不是"偶尔的灵光"。

五、评估指标与实验证据

5.1 总体解决率：架构间大体相近

这是论文有意为之的结果：能力被控制等价后，总体解决率在各架构间差别不大（附录 Figure 5）。这个"没有差异"的结果本身是实验有效性的证据——说明控制成功了，架构改变的不是"能不能做"而是"怎么做"。

5.2 一致性：Atomic 是唯一全面提升的架构

核心数据（相对同模型 BashOnly 的变化）：

三个规律：Atomic 是唯一在全部三个模型上 pass^k 都提升的架构；增益幅度与模型强弱负相关——最弱的 Qwen3Coder-30B 提升最大（pass^5 从 0.046 到 0.106，约 2.3 倍；按 pass^5/pass^9 相对倍数最高达 4.7 倍），强模型 Kimi/Sonnet 提升 0.0130.031；其余架构无跨模型规律，Scratchpad 和 Python 偏中性或负面。附录 B.2 把 BashOnly vs Atomic 扩到每实例 30 次重复，增益依然稳定（Qwen +0.060+0.067），排除了小样本波动。

5.3 探索：NLSearch 唯一持续拓宽阅读面

读多样性（跨次 rollout 读文件集合的 Jaccard 距离，相对 BashOnly 变化）：NLSearch 在三个模型上分别 +18.6%（Q3C）、+21.3%（Kimi）、+13.4%（Sonnet），是唯一全面提升的架构；其他架构变化小或有正有负。但解的多样性变化都很小——即便读的文件不同，最终补丁仍趋同。架构对"仓库遍历"的影响远大于对"最终方案"的影响。

附加分析（附录 B.4）：NLSearch 的探索是"有意义的广"——高相关文件召回率在三模型上全部提升（Q3C +0.046、Kimi +0.053、Sonnet +0.064），但精确率下降（如 Sonnet -0.104），即多读也带来噪声。

5.4 效率：Python 全面胜出

相对 BashOnly，Python 接口以相近任务表现实现步数 -41.6%、token 消耗 -56.3%（摘要数据）。分模型看（附录 Table 8）：Qwen 步数 77→46、Kimi 65→47、Sonnet 80→55；Qwen 与 Kimi 的输出/观测 token 总量大致持平，但每步吞吐更大（如 Qwen 每步输出 197→315 token）——说明每步干的活更多，而步数更少。对 Sonnet 还有一个额外发现：bash 下常见"连续整文件重写却得不到执行反馈"的投机式修订，Python 下编辑与执行天然耦合、反馈更快，高浪费尾部显著减少。而 Atomic 的效率与模型相关：对 Qwen 省成本（输入 token 980K→662K，-32%），对 Kimi/Sonnet 反而增 20%（附录 Table 10）。

5.5 错误类型分析：Atomic 的机制证据

附录 B.3 把环境交互错误分三类：misaligned-param（工具用到错误目标）、mis-edit（改出语法/缩进错误）、wrong-syntax（命令本身拼错）。BashOnly 下 Qwen 每轨迹平均 3.11 个交互错误（Kimi 0.35、Sonnet 0.54）——错误率排序与 pass^k 排序完全镜像。换 Atomic 后 Qwen 降到 1.17，其中 mis-edit 1.64→0.19、wrong-syntax 0.96→0.01，恰好是受限接口直接堵死的两类错误。misaligned-param 反而升（0.52→0.97），合理解释是原子工具参数校验更严，把过去会静默失败/部分生效的错误显式暴露出来。

5.6 泛化验证与认知脚手架失效

在 SWE-bench Verified、SWE-bench Pro、调试任务上（两开源模型、每实例 5 次），三条主结论方向一致：Atomic 使 pass^5 总体 +9.5pp（Qwen）/+2.5pp（Kimi）；NLSearch 读多样性总体 +13.0%/+9.4%；Python 输入 token 与步数总体下降。

认知脚手架为何无效（附录 C）：Scratchpad 内容与 BashOnly 已有推理高度重合（BLEU 打分多数高于 0.6，即"抄自己"）；HypoTrack 真正记录多个竞争假设的分支行为极少，多数轨迹要么不用、只记一条假设。

六、效果优势的根源解释

把证据串成因果链，就能解释每个架构为什么有效或无效。

Atomic 的因果链：受限接口 → 低级错误骤减 → 重跑稳定 → pass^k 跳升。 自由 shell 要求模型现场生成 sed/awk/heredoc 这类语法精确度极高的文本，弱模型的执行级失误会不断累积；原子工具把这些操作变成参数受校验的结构化调用后，mis-edit 和 wrong-syntax 几乎归零（1.64→0.19、0.96→0.01），每次 rollout 更不容易中途翻车，于是"k 次全成功"的概率大幅上升。这也解释了为何弱模型受益最大：强模型本来就不犯这些错（BashOnly 下 Kimi 每轨迹仅 0.35 个错误），改进空间小。

Python 的因果链：单步复合操作 → 步数骤减 → 累积输入 token 下降。 关键在 token 的记账方式：每次 API 调用都要重发完整历史，输入 token 随步数累积放大。Python 让模型把遍历、检查、替换、写回打包进一个代码块，单步输出更多（197→315 token/步）但步数从 77 降到 46，总账算下来输入成本大降。对 Sonnet 还有第二条链：编辑-执行耦合 → 反馈更及时 → 减少盲目整文件重写。

NLSearch 的因果链：降低查询的表达与切换成本 → 早期查询更多样 → 探索更广。 直接证据是早期搜索动作多样性（附录 Table 5）：前 20 步搜索查询的 Jaccard 距离，NLSearch 下 Qwen 为 0.850 vs BashOnly 0.692（Kimi 0.873 vs 0.634、Sonnet 0.862 vs 0.681）。bash 下模型跨 rollout 反复用相似的 grep/find 模式；自然语言接口让每次提问更不同，读到的文件集合更分散，召回更多相关文件——但代价是精确率下降，多读的上下文需要模型自己过滤。

Scratchpad/HypoTrack 无效的根源：接口没有改变信息获取方式，只改变了记录方式。 论文的核心洞察是——这两个工具提供的通道，模型"本来就有"（推理文本里能写同样的内容），所以模型只是把已有思路投射进去（BLEU 高重合），而不是产生新思路。HypoTrack 想诱导多假设分支，但主流模型在长任务里倾向单线程推进，工具没有提供强制分叉的理由。有效的接口改变的是信息如何流入模型（搜索方式、操作粒度、反馈时机），无效的接口只是给既有行为多开了个记录窗口。

七、必要知识反推

想真正吃透这篇论文，以下三层知识是必要的：

领域层

• 编码智能体的工作循环：读 issue → 定位文件 → 理解代码 → 修改 → 跑测试 → 提交补丁；SWE-bench 家族（Live/Verified/Pro）的评测协议——隐藏测试用例判定补丁是否真正解决问题。
• 主流工具栈现状：SWE-Agent 的 ACI（agent-computer interface）、OpenHands 与 Claude Code 的原子工具集、Smolagents 的 CodeAct 范式、Augment 的语义检索引擎——论文六架构正源于这些真实设计。
• Harness 工程的兴起：Anthropic/OpenAI 2026 年密集讨论"围绕模型的工程系统"设计，本文是其工具维度的科学化。

方法论层

• 受控变量实验设计：这是全文的方法论灵魂。刻意让 NLSearch 内部用 grep、让 Python 动作 97% 可在 bash 中完成、让人工验证高相关文件代理标签（94.4% 精确率）——每一步都在堵"能力不等价"的漏洞。这种"为归因清晰而牺牲性能上限"的设计思路值得所有实证研究者学习。
• pass^k 指标族：C(c,k)/C(n,k) 的无偏估计，理解它与 pass@k 的本质差异（全成功概率 vs 至少一次成功概率），以及为何 k 越大对偶发失败越敏感。
• 软件可靠性理论：fault–error–failure 链（Avizienis 2004），论文用它建立"交互错误是重复运行不可靠的解释透镜"。

工程层

• token 成本的累积记账：输入 token = Σ 各步完整历史长度，步数是成本的一阶决定因素。
• Jaccard 距离/CodeBLEU 距离衡量行为多样性的做法。
• 错误分类法：misaligned-param / mis-edit / wrong-syntax 三分法可直接复用于自家智能体的失败分析。

融合节点：这篇论文最大的思想嫁接，是把 HCI（人机交互）领域"界面塑造行为“的经典命题引入智能体工具设计——同一个系统、同一批功能，界面不同，用户（这里是模型）的行为统计特征就不同。软件工程里"架构决定非功能属性"的旧智慧，在 LLM 智能体身上重新成立。

八、通用性灵感

以下几条启发都不限于编码智能体。

灵感一：接口即行为塑造器。 核心思想：在能力等价前提下，接口的组织与暴露方式本身就是一等设计变量，系统性改变使用者的稳定性、探索广度与效率。论文证据：六架构能力等价，pass^k、读多样性、步数/token 却出现系统性差异。推广场景：任何 LLM 智能体的工具层设计（客服智能体的工单接口、数据分析智能体的查询接口）、MCP 工具服务器设计、甚至提示词中"指令的组织方式”——都应把"接口形态"当独立实验变量来 A/B 测试，而不是与能力捆绑上线。

灵感二：受限接口提升弱模型的稳定性。 核心思想：能力较弱的模型在自由接口下容易被低级执行错误拖垮；收窄自由度（参数受校验的结构化原语）能堵死高频错误模式，收益与模型弱点成正比。论文证据：Qwen 错误数 3.11→1.17、mis-edit 1.64→0.19、pass^5 提升 4.7 倍量级，而强模型增益小。推广场景：为中小模型设计智能体时优先用结构化工具而非裸 shell；GUI 自动化、运维变更等高危操作场景，受限接口等于安全护栏；反过来，强模型配受限接口可能适得其反（Atomic 让 Kimi/Sonnet 输入 token +20%）——接口粒度要匹配模型的自然交互风格。

灵感三：复合表达优于原子调用（步数视角）。 核心思想：LLM 智能体的累积成本随交互步数放大（每步重发全部历史），支持单步复合表达的接口（写代码）比逐个工具调用更省。论文证据：Python 步数 -41.6%、输入 token -56.3%，且每步吞吐更高（Qwen 197→315 token/步）。推广场景：智能体成本优化的第一杠杆不是"每步说短点"而是"步数减半"；工具设计应允许批量参数、脚本化组合；评测智能体时"步数"应与准确率并列为核心指标。

灵感四：降低表达成本能拓宽探索。 核心思想：把"怎么搜"的技术细节（正则、命令）换成"搜什么"的自然表达，能诱导更多样的早期查询、更广的上下文覆盖——即便底层检索能力完全没变。论文证据：NLSearch 早期查询 Jaccard 0.85 vs 0.69，读多样性 +13.4%~27.9%，相关文件召回三模型全升。推广场景：RAG 系统的查询接口设计（自然语言提问 vs 关键词检索）；推荐/检索系统的探索-利用权衡；任何希望"用户多尝试不同角度"的 AI 产品功能，先审视表达成本。

灵感五：不改变信息获取方式的认知脚手架是空转的。 核心思想：只提供"记录想法"的通道而不改变信息流入方式或强制不同推理策略，模型只会把已有思路投射进去，行为不会变。论文证据：Scratchpad 内容与原推理 BLEU 高重合、HypoTrack 分支行为罕见，两者各指标基本无效。推广场景：警惕各种"思考工具"“计划工具"的疗效幻觉——评估它们要看行为分布是否真的改变（如查询多样性、路径分支率），而不是看模型是否在用；要让脚手架有效，必须绑上信息增益（检索）、强制策略（如 MCTS）或真实的外部状态。

一个综合提醒：论文同时展示了"没有免费午餐”——Atomic 提稳定性但可能增成本，NLSearch 增探索但降精确率，Python 省成本但对弱模型 pass^k 略降。接口设计本质是按模型能力与部署目标（稳？广？省？）做的多目标权衡，没有普适最优解。

九、结语

这篇论文用 11,700 条轨迹的受控实验证明了一个朴素而深刻的结论：魔鬼藏在接口里。给智能体同样的能力，只是换一种呈现方式，重复稳定性可以差 4.7 倍，探索广度可以差两成，成本可以差一半。对工具/harness 设计者来说，它把"接口形态"从工程直觉提升为可度量的设计变量；对研究者来说，它示范了如何在纠缠的系统中做干净的归因实验。下次你纠结"要不要给智能体加个新工具"时，先问一句：我是在加能力，还是在改接口？两者的价值机制完全不同。

本文基于论文全文逐页阅读撰写。