终端智能体评测最近特别热但很多人在对比模型时忽略了一个问题真正让分数忽上忽下的往往不是模型本身而是脚手架。终端智能体不是聊天机器人它要在命令行环境里完成执行命令、读取输出、修改文件、判断下一步操作这一整套闭环。我连续跑了几组对比后得到一个很直接的感受换模型可能只带来几个百分点的波动换一套脚手架分数可能直接换档。这篇文章想把这层关系拆清楚。先讲终端智能体评测里的“分数”是从哪里来的再讲为什么脚手架比模型更影响分数最后给出一套可以复现的评测思路、观察指标和排查路径。如果你正在做 Agent 评测或者准备跑类似 SWE-bench 的终端任务这篇内容可以帮你省掉很多无谓的调参时间。1. 你要测的是“终端智能体”不是“会聊天的模型”1.1 终端智能体的核心闭环命令、回显、判断、下一步先明确一个概念终端智能体通常指运行在 CLI 环境里的 AI Agent它能接收一个自然语言任务然后在终端中执行命令、读取输出、修改文件、安装依赖、运行测试最后把结果返回给用户。这比普通聊天问答复杂在一个位置模型必须对真实环境产生动作并且根据动作结果调整后续动作。也就是说任务不是“生成一段文字”而是“在有限步数内把一个真实任务做完”。我一般会把终端智能体的工作闭环拆成四个阶段任务解析把用户请求变成可执行的计划。命令生成把计划变成具体命令比如cd、ls、grep、python、pip install。结果读取拿到命令回显、退出码、stderr、stdout。自我修正根据结果决定继续执行、换方案还是终止任务。这四个阶段任何一个环节出问题最终任务都可能失败。而它们并不都由模型决定。1.2 模型负责意图脚手架负责可执行性很多人把终端智能体简单理解成“很会写命令的模型”。真实跑过就会发现模型只是其中一个组件。模型负责的是“理解意图”和“生成合理动作”。例如当用户说“帮我把这个目录下所有超过 100MB 的文件列出来”模型需要知道用find或du这类命令去处理还要知道如何过滤结果。这确实是模型的功劳。但从模型生成一条命令到最终任务完成中间还有一大堆工程环节命令怎么传给终端是用 shell 直接执行还是走伪终端返回的 stdout/stderr 怎么截断、怎么合并、怎么回传超时了怎么办命令执行失败要不要重试上一条命令没有结束下一条命令能不能继续长日志怎么处理是全部塞进上下文还是先压缩环境隔离怎么做多个并发任务会不会互相污染。这些环节统称为“脚手架”。它们不是模型能力的一部分却在评测里直接影响分数。你可以想象成模型是大脑脚手架是四肢、神经和裁判体系。大脑足够聪明但如果手脚动作变形或者裁判看错动作分数照样低。2. 评测分数为什么会被脚手架“带偏”2.1 同一模型不同脚手架容易出现明显分数差我在实际对比中最常看到的现象是有人换了模型分数没怎么涨于是怀疑模型不行。但把同一个模型放到另一套 Agent 框架里分数立刻变高了。这说明模型没有被公平暴露在评测任务里。举个常见的例子。任务要求修改项目里的一个配置文件然后运行测试确认测试通过。模型可能已经生成了正确的sed命令但脚手架把sed命令的换行符处理错了导致命令语法错误。如果脚手架没有“解析 stderr 并让模型看到失败原因”模型就会在错误的空转里反复调用同一个命令直到步数耗尽。最后评测判定失败分数很低。这不是模型不会写sed而是脚手架没有把执行结果可靠地回传给模型。所以评测终端智能体本质上是在评测“模型 脚手架 评测逻辑”这一整套系统。2.2 评测集本身也在放大脚手架差异不同评测集的侧重点不一样。有的评测集偏重多文件代码修改有的偏重命令行工具调用有的偏重“从零开始部署一个服务”。同一个模型在不同数据集上分数排名可能完全不同。原因是评测任务对脚手架的要求不同纯命令执行类任务主要考验命令生成和输出解析。文件修改类任务主要考验diff判定和补丁应用。日志排查类任务主要考验长上下文处理和关键信息提取。端到端部署类任务主要考验超时控制、依赖安装和错误恢复。如果评测集把大量任务设计成“需要多步修改文件”那么脚手架的补丁生成能力就比模型本身更重要。如果评测集主要是“问一句、答一句”的命令问答那么模型参数的影响才会更明显。所以看评测分数时第一件事不是比较模型强弱而是看评测任务主要由哪些环节构成。2.3 判定逻辑输出解析比模型输出更直接决定得分还有一个容易被忽略的环节评测系统如何判定“成功”。很多 Agent 评测不是看最终回答文本而是看执行结果。常见判定方式有三种检查文件系统要求的文件是否被创建、修改内容是否匹配检查命令输出进程退出码是否为 0测试是否通过检查最终回复用字符串匹配或语义相似度判断答案是否正确。三种方式对脚手架的敏感度完全不同。文件系统检查要求脚手架能准确定位工作目录不能把文件写错位置命令输出检查要求终端交互稳定超时和重试机制合理最终回复检查要求模型能把中间过程归纳成结论。我见过很多“看起来成功但被判失败”的案例。比如模型明明把文件改对了但脚手架把工作目录从/project切到了/tmp导致文件写到了错误位置又比如测试命令确实输出了ALL TESTS PASSED但评测脚本只匹配输出里的最后一行而最后一行是空行于是判定失败。这些都不是模型能力问题但分数都记在模型头上。3. 搭建一个能复现的终端智能体评测环境3.1 最小评测环境清单在跑任何 Agent 评测之前先把环境固定下来。我建议的最小环境包含这些一个干净的 Linux 容器或虚拟机避免宿主机环境干扰固定版本的 Python、Node、Java 等运行时一个可复现的依赖锁定文件而不是每次现场安装评测脚本本身和被测 Agent 分离不能互相依赖日志输出目录和结果输出目录分开网络按需开启尽量不让 Agent 依赖外网下载。为什么要强调干净环境因为终端智能体可能执行rm、cp、sed、pip install这类命令。一旦环境被污染后面的任务会被前面的失败影响。评测结果不稳定很多问题不是模型不稳而是环境没隔离干净。我用容器跑评测时通常会为每个任务创建独立快照。任务结束后销毁容器重新拉一个新的。这样能省掉大量排查环境脏乱的时间。3.2 任务类型选择单命令、多步骤、调试类、文件修改类评测终端智能体不要只选一种任务。至少覆盖四类任务类型典型场景主要考验单命令执行查文件、查进程、查端口命令生成、退出码读取多步骤操作下载安装依赖并运行服务计划分解、状态记忆文件修改类改配置、改代码、生成补丁文件操作、diff 判定调试排错类服务启动失败找原因日志理解、错误恢复每类任务准备 5 到 20 条即可。先小批量跑通流程再扩大规模。如果你一开始就上几百条任务一旦系统性问题出现很难定位是模型问题还是脚手架问题。3.3 结果判定标准评测任务要事先定义清楚什么算“通过”。我建议每条任务至少写三个信息输入任务描述前置条件文件位置、端口、环境变量通过条件文件内容、退出码、输出关键词、测试结果。不要只写“让 Agent 完成这个任务”。没有明确的通过条件评测分数就失去意义。特别是人工复看结果时如果没有统一标准很容易出现“这个案例看起来完成了但测试没跑过”的争议。3.4 先跑样例任务再上批量我的习惯是先把评测环境搭好跑 3 到 5 条单任务人工检查每一步输出。确认命令能执行、输出能回传、结果能判定再开批量。不要一上来就开最大并发。终端智能体评测的并发和普通接口压测不一样。每条任务都会创建新的终端会话可能还会安装依赖、修改文件资源占用比单纯问答要高得多。小批量跑通之后观察 CPU、内存、磁盘和日志目录再逐步增加并发。4. 影响分数的脚手架模块逐个拆解4.1 Agent 循环错误发生后是重试还是换路径Agent 循环是整个脚手架最核心的部分。它决定了模型在一次动作之后是能看到反馈、重新规划还是只能机械地重发命令。一个相对稳定的 Agent 循环至少包含模型生成动作脚手架执行动作脚手架捕获结果将结果回传给模型模型基于结果生成下一步。这个循环看起来很基础但工程实现上有区别。比如模型生成了一条命令命令执行失败退出码非 0。脚手架应该把失败原因整理成简洁信息给模型而不是只把原始 stderr 丢回去也不是直接掐断任务。如果错误信息太乱模型可能无法定位问题。如果错误信息被截断得太狠模型可能看不到关键报错。这里的截断策略、格式化方式都会影响模型能不能在下一步做出正确判断。我遇到很多模型“表现不佳”的评测结果其实都是错误回传格式太差导致的。4.2 终端交互层伪终端、退出码、超时和回显终端智能体不是简单调用subprocess.run()就完事。真实终端任务里命令可能是交互式的比如启动服务器后会一直保持运行或者需要阅读y/N确认。这时候就需要伪终端PTY模拟交互。但伪终端也会带来问题。如果回显没有处理好模型看到的内容可能包含重复的命令输入干扰判断如果超时控制不合理启动一个常驻进程会一直占用任务导致评测卡死。我建议在终端交互层明确记录这几个字段命令内容退出码stdout 摘要stderr 摘要执行耗时是否因超时强制结束是否为伪终端是否有交互写入。这些字段是排查问题的重要依据。很多评测结果“分数低但不知道低在哪”就是因为日志里没有记录退出码和超时状态。4.3 上下文管理长输出截断与关键信息保留终端任务的输出经常非常长。一次grep可能返回几千行一次pytest可能打印几万字符。如果脚手架把所有输出都塞进模型上下文不仅浪费 token还可能让模型忽略关键信息。常见的处理方式有按行数截断取前 N 行和后 N 行按关键字提取比如只看error、failed、traceback附近内容对重复内容去重对超大文件用tail、head或grep二次筛选。但截断策略要谨慎。截断太狠模型看不到完整报错截断太浅上下文容易超长。实际评测中我一般会先记录完整输出到日志文件再给模型回传摘要。这样既保证模型有足够信息也方便事后复现问题。4.4 工具定义与参数校验很多终端智能体并不是只靠模型直接写 shell 命令而是给模型暴露了一组工具比如run_command、read_file、write_file、search_file、run_tests。这些工具的参数定义和校验逻辑属于脚手架的一部分。工具定义会影响模型的选择。如果工具数量太多、参数复杂模型可能选错工具。如果工具数量太少模型又只能用一条长命令硬拼。在实际评测中我建议先固定一套工具集不要频繁调整。工具名称、参数顺序、返回结构的一致性往往比某一个工具内部实现更影响分数。模型很容易在“不知道有哪些工具”的情况下乱猜这是脚手架的问题不是模型能力问题。4.5 失败重试与任务队列评测任务不会总是一次成功。终端命令可能因为网络抖动、服务未启动、权限问题失败。这时候脚手架的失败重试策略非常重要。常见错误做法是任务失败了就原样重发一遍连续重试三次然后放弃。更好的做法是让模型看到失败原因允许它调整命令或步骤比如先检查文件是否存在再决定是否安装依赖。批量评测时还要考虑任务队列。任务之间有先后关系吗失败任务会跳过还是继续阻塞输出文件会覆盖吗这些听起来不像“模型能力”但会直接影响最终分数和评测效率。我建议在跑批量前先设计好任务命名规则和日志落盘规则避免不同任务之间互相覆盖。5. 模型在什么时候才真正决定上限5.1 指令遵循能力决定任务解析准确度虽然脚手架影响很大但模型并不是不重要。任务一开始的“任务解析”环节模型能力就非常关键。如果模型不能准确理解“先修改配置文件再运行测试”这类指令后续动作可能从一开始就偏了。这里考验的是模型对中文或英文指令的遵循能力以及对任务隐含背景的理解能力。我在评测中看到很多失败发生在“模型根本没有按照任务的约束条件执行”。比如任务要求“不要修改测试文件”模型为了快速通过测试私自改掉了测试用例。这种情况下脚手架完全没问题问题出在模型的指令遵循能力。5.2 长上下文和工具调用能力在复杂任务中显形简单命令任务里模型差异可能被脚手架掩盖。但复杂任务比如多文件重构、跨目录定位问题、从错误日志反推修复方案模型的长上下文能力和工具调用能力就会变成真正的瓶颈。具体表现为模型能否记住前面改过哪些文件能否从大量日志中找出真正的错误行能否合理调用多个工具而不是只用一个命令硬碰硬能否在尝试失败后换一种更稳妥的方案。这些能力在评测集里占比越大模型差异越明显。所以做模型对比时最好把任务按复杂度分层。如果全部都是简单命令你看到的分数差异很可能不是模型能力差异而是脚手架差异。5.3 什么时候优先换模型什么时候先修脚手架这里给一个我自己的判断方法如果任务失败在“模型一开始就误解任务”优先考虑换模型或优化提示词如果任务失败在执行阶段比如命令生成了但运行报错先检查脚手架的错误回传和重试逻辑如果任务失败在结果判定比如文件改对了但被判定错误先检查评测逻辑如果多任务之间互相污染优先检查环境隔离。换句话说不要看到分数低就下结论说模型不行。先把失败任务按阶段归类确定失败到底发生在解析、执行、反馈还是判定环节。6. 一组可复用的对比思路和观察指标6.1 单变量对比模型不变只改脚手架要验证“脚手架比模型更影响分数”最直接的方法是单变量对比。固定同一个模型分别跑两套脚手架记录分数差异。这里的对比要注意几点模型温度尽量设为 0 或比较低的固定值减少随机性评测任务完全一致每个配置跑至少两遍确认结果是否稳定记录每轮失败的具体原因而不只记录整体分数。如果两套脚手架分数差异超过 5 个百分点同时同一脚手架下相同模型两次跑分差距不大就可以确认脚手架对分数的影响不小。6.2 记录分数之外的指标耗时、成本、失败类型、重试次数只看分数会丢失很多信息。我建议每次评测都记录以下指标指标说明为什么重要通过率通过任务数 / 总任务数最终分数平均耗时每条任务从开始到结束的时间反映效率平均步数模型执行动作的次数反映脚手架是否高效平均重试次数命令失败后的重试次数反映错误恢复能力失败类型分布超时、命令错误、判定失败、环境问题定位问题阶段Token 消耗输入输出总 token反映成本并发稳定性并发任务是否互相影响反映生产可用性这些指标能帮你判断“分数高到底是真能力强还是任务简单碰巧通过了”。如果一条任务通过了但花了 30 步、重试了 20 次那这个分数在真实生产里没有太大参考价值。6.3 用表格做横向对比如果你要写评测报告建议按脚手架维度做一张横向对比表。示例脚手架配置模型通过率平均耗时平均重试次数主要失败点A 框架模型 X62%3.2 分钟4.1长日志截断导致漏掉关键错误B 框架模型 X74%2.8 分钟2.5文件修改后未刷新上下文A 框架模型 Y65%3.0 分钟3.8任务解析偏差B 框架模型 Y78%2.5 分钟2.1无明显集中问题这里的数据只是示例真实数据需要自己跑。但格式可以参考。通过这种方式能直观看出脚手架配置变化和模型变化各自带来的影响。7. 常见问题与排查顺序7.1 同一份代码分数不稳定先查环境隔离如果你连续跑两次得到的结果差异很大优先检查环境隔离是否到位。常见问题包括前一个任务创建的临时文件没有被清理前一个任务的进程还在后台运行网络缓存、依赖包目录互相复用评测脚本把多个任务输出写到同一个文件。解决办法是每个任务使用独立工作目录任务结束后杀掉残留进程必要时重建容器或虚拟机。7.2 任务卡住或超时先看伪终端和命令返回任务卡住很少是模型“发呆”多半是命令本身没有结束。比如pip install长时间无响应或者启动了开发服务器后一直不退出。这时先排查终端交互层命令是否通过伪终端执行是否设置了合理的命令超时是否在命令超时后给模型返回了“强制终止”的信息模型是否知道进程已经被杀掉可以进行下一步。如果模型始终不知道命令被强制终止它会一直重复等待表现为“任务卡死但模型没有报错”。7.3 输出看起来正确但判定失败先查评测解析这也是高频问题。模型在日志里明显已经完成了任务但最终分数显示失败。第一步看评测脚本的判定逻辑。具体检查判定依据是文件内容还是输出关键词是否区分了 stdout 和 stderr是否区分大小写是否只匹配最后一行是否因为命令输出包含大量字符导致匹配失败是否因为编码问题中文或特殊字符解析错误。这些环节都很容易导致误判。我通常会在评测脚本里把判定过程中的中间变量打印出来比如“提取到的字符串是什么”“预期字符串是什么”“匹配结果如何”。这样能快速定位是否误判。7.4 推荐排查顺序表遇到评测结果不符合预期我一般按下面顺序排查顺序检查项怎么查1日志查看 Agent 执行日志确认每一步动作2输出回传确认 stderr/stdout 是否被截断或丢失3退出码确认命令是否真的成功4工作目录确认文件是否写到了预期位置5判定逻辑检查评测脚本匹配规则6环境差异对比两次运行的环境变量和依赖版本7模型输入检查模型实际收到的上下文是否完整这个顺序能覆盖大部分问题。不要一开始就怀疑模型先把最执行链条上的工程问题清干净。7.5 最后几点经验终端智能体评测本质上是在评测一整套“能做事”的系统而不是单个模型文件。只看最终分数很难知道瓶颈在哪里。我建议把评测变成“可持续复现”的工程流程固定环境、记录日志、分类失败、逐步对比。如果你的目标是验证模型能力就更要控制脚手架变量。每次只改一个因素不要同时换模型又换框架。如果你发现模型分数一直上不去先别急着换更大的模型先看失败任务集中在哪里。很多情况下把脚手架的错误回传、上下文截断和结果判定修好分数提升比换模型更稳定。真正落地评测时最该盯住的不是“最高分能到多少”而是这个分数能不能稳定复现、失败原因是否清楚、换环境后是否还能跑通。这些问题理顺了模型和脚手架各自的价值才会在分数里真正显露出来。