终端智能体（Terminal Agent）是近几年“大模型 + 工程实践”结合最紧密的方向之一。它让大模型不再停留在对话窗口里，而是直接接管 Shell，通过执行命令、观察输出、修正步骤来完成实际软件任务。也正是因为它接入的是真实系统，不同项目之间的对比才会出现许多看起来互相矛盾的结果：同一个智能体在一个评测集上接近 SOTA，在另一个评测集上却排在中游；同一套工具在一次演示中能完成多文件重构，在另一台机器上却连依赖都没装好。这个现象并不是评测方故意制造差异，而是终端智能体的工作方式、评测基准的设计目标、使用场景的约束条件三者在互相影响。
需要先澄清一个概念：这里讨论的“终端智能体”，指运行在命令行终端里的 AI 代理程序，研究对象是如何让大模型自动执行 Shell 命令并完成任务，而不是指手机、电脑等终端设备上的端侧模型。理解这一点后，再看综述材料里的“矛盾”会清晰很多。接下来文章会先拆解终端智能体的执行回路，再盘点主流项目与评测基准，最后给出可执行的自建评测方法和生产落地建议。
1. 先拆清楚终端智能体的执行回路，才能理解对比为什么失真
很多综述把终端智能体当作一个整体来比较，但实际使用时，它是一条由“任务理解、命令执行、输出观察、状态更新、结果判断”组成的回路。两个项目表面上都能执行命令，内部回路的设计却可能完全不同，对比结果自然不统一。
1.1 终端智能体的最小工作单元
终端智能体的输入是一个自然语言任务描述，输出是若干命令、文件修改和最终总结。和聊天机器人相比，它最大的特点是输出会落在真实文件系统、进程和网络环境中，因此每一步都要对现实结果负责。
一个标准的执行循环可以拆成四个阶段。
第一，任务解析与规划。智能体拿到任务后，需要把目标拆成可执行步骤。比如“修复项目中的依赖冲突”，需要先分析 package.json、锁定文件、npm 版本，再决定是升级依赖还是调整版本范围。
第二，命令生成与执行。智能体基于当前状态生成一条或多条 Shell 命令，并送到终端执行。这一步看起来简单，实际难点在于命令的上下文依赖：可能需要先读取目录结构，再决定执行哪个脚本。
第三，输出观察与状态更新。命令执行后，标准输出、标准错误、退出码都需要被采集并回传给模型。很多失败就发生在这一层：模型没有看到完整报错，只观察到截断后的末尾，于是做出了错误判断。
第四，结果判断与循环控制。智能体判断任务是否完成，如果未完成，则基于新的状态继续生成命令。为了防止死循环，必须设置最大步数或超时时间。
这个回路决定了终端智能体的能力边界：它既受底层模型推理能力影响，也受命令执行环境和状态采集方式影响。综述对比如果只比较“谁能完成任务”，不比较回路里的这些细节，结果就会失真。
1.2 终端智能体与聊天机器人和 IDE 插件的关键差异
要理解终端智能体的定位，可以用三类工具做对比。
| 对比维度 | 聊天机器人 | IDE 插件 | 终端智能体 |
|---|---|---|---|
| 输入 | 用户文本 | 代码上下文 + 用户操作 | 任务文本 + 环境状态 |
| 输出 | 对话文本 | 补丁、建议、补全 | 命令、文件修改、执行结果 |
| 状态管理 | 会话上下文 | 编辑器缓冲区 | 文件系统、进程、环境变量 |
| 反馈来源 | 用户继续提问 | IDE 报错和代码分析 | 命令退出码、stdout、stderr |
| 权限边界 | 无真实系统操作 | 限制在编辑器内 | 可读写文件、安装依赖、运行服务 |
| 失败成本 | 低，重问一次即可 | 中，补丁可能不合法 | 高，可能污染环境或破坏代码 |
IDE 插件的控制范围通常限制在编辑器和项目解析结果中，终端智能体的控制范围则扩展到整个 Shell。它既能执行npm install，也能运行测试、修改配置、提交 Git 记录。权限越大，能力越强，但可复现性和安全性就越差。这也是不同项目在“哪个更好用”上结论分歧非常大的原因之一。
1.3 用最小代码结构模拟一个终端智能体循环
为了把执行回路讲清楚，这里用一段说明性 Python 代码模拟一个终端智能体的最小骨架。这个示例只用于理解流程，不构成生产实现。
import subprocess MAX_STEPS = 30 class TerminalAgent: def __init__(self, model): self.model = model self.history = [] def run(self, task: str) -> str: plan = self.model.plan(task) for step in range(MAX_STEPS): command = self.model.decide(plan, self.history) if command is None: break proc = subprocess.run( command, shell=True, capture_output=True, text=True ) self.history.append({ "command": command, "stdout": proc.stdout[-2000:], "stderr": proc.stderr[-2000:], "code": proc.returncode, }) if self.model.is_done(plan, self.history): return self.model.summarize(plan, self.history) raise RuntimeError("max_steps_exceeded")这段代码里有几个设计点需要重点理解。
第一是proc.stdout[-2000:]。真实终端输出可能非常长，模型上下文有限，必须截断或者做摘要。截断长度会影响模型对失败原因的判断，如果真正报错发生在输出尾部之外，模型就会丢失关键信息。
第二是记录returncode。退出码是判断命令是否成功的最硬指标，比解析输出文本更可靠。但退出码为 0 也不代表任务正确完成，比如一个测试脚本没有真正运行测试就正常退出，这种情况需要结合 stdout 内容判断。
第三是MAX_STEPS。没有它，一个执行失败的智能体会无限尝试，既浪费 token，也可能不断修改文件造成不可控结果。生产系统中通常还应该有总时长限制和操作审计。
2. 主流终端智能体盘点和“看似同代、其实不同”的设计取向
当前终端智能体项目数量增长很快，类型也很多样。综述对比矛盾的一个重要原因，是作者把“都是终端里的智能体”当作同一种东西，却没有深究每个项目在权限模型、执行方式、模型依赖上的差异。
2.1 当前常见的终端智能体项目
以下表格用于帮助理解设计差异，不构成排名，也不代表任何真实评测结果。这些项目迭代速度很快，能力边界也在不断变化。
| 项目 | 常见定位 | 执行环境 | 模型依赖 | 开源情况 |
|---|---|---|---|---|
| Codex CLI | OpenAI 推出的命令行编程智能体 | 本地终端 | OpenAI 系列模型 | 客户端开源 |
| Claude Code | Anthropic 推出的终端编码智能体 | 本地或远程终端 | Claude 系列模型 | 商业产品 |
| Gemini CLI | Google 推出的终端智能体 | 本地终端 | Gemini 系列模型 | 开源 |
| OpenHands | 开源通用软件工程智能体 | 容器沙箱为主 | 可插拔模型 | 开源 |
| SWE-agent | 学术场景下的 Agent 框架 | 评测沙箱 | 可插拔模型 | 开源 |
| Goose | Block 开源的终端智能体 | 本地终端 | 可插拔模型 | 开源 |
| Qwen Code | 阿里 Qwen 生态的编码智能体 | 本地终端 | Qwen 系列模型 | 开源 |
从表格能看出，不同项目至少存在四类差异：执行环境是本地还是容器沙箱、模型是绑定还是可插拔、产品形态是开源框架还是商业 CLI、是否默认鼓励自主执行。这些差异会直接改变使用体验和评测结果。
2.2 最容易让对比失真的一批配置项
即使使用同一个项目，只要配置不同，任务表现就可能完全不同。综述如果不记录这些配置，排名就失去了参考价值。
| 配置项 | 常见取值 | 对结果的影响 |
|---|---|---|
| 执行模式 | dry-run、confirm、auto、audit | 确认步骤越多，速度越慢，但误操作越少 |
| 文件系统权限 | 允许写整个目录、只允许写工作区 | 权限过窄会失败，过宽会破坏环境 |
| 网络访问 | 允许安装依赖、禁止外网 | 无法安装依赖的任务直接失败 |
| 上下文上限 | 8k、32k、128k、200k | 截断后模型可能丢失关键报错 |
| 模型版本 | GPT-4o、Claude 3.5、Gemini 2.5 等 | 不同模型对同一条命令链的推理差异明显 |
| 温度与随机参数 | 0、0.2、0.7 | 高随机性会导致多次运行结果不稳定 |
| 工作目录 | 项目根目录、系统任意目录 | 路径感知错误会引发整条命令链偏离 |
最容易踩的坑是把“同一个 Agent 的默认配置”误当成“该 Agent 的唯一能力”。一个配置为confirm模式的工具，和一个配置为auto模式的工具，在自主性指标上会有巨大差异，但这种差异并不代表底层模型能力不同。
2.3 开源与商业产品的可观测性差异
开源终端智能体通常能输出完整执行日志，方便二次分析和定制，但日志字段、格式、采集方式需要自己维护。商业产品往往自带可观测面板，但日志字段不一定完整开放，对比时需要统一数据口径。
这导致一个现实问题：综述中的性能数据可能来自不同来源。有的数据是作者自己跑出来的，有的引用厂商文档，有的来自开源仓库的 README。这些数据的环境、模型、配置不同，直接放在一张表里对比，就会产生“矛盾”。后续章节会专门说明如何规避这个问题。
3. 评测基准差异是综述对比矛盾的第一个放大器
评测基准是用户观察终端智能体能力的窗口，但每个基准的设计目标不同，考察的能力维度也不同。把不同基准的结果放在一起比较，就像把数学竞赛和编程比赛的成绩直接相加，结论必然失真。
3.1 常见评测基准和它们真正想考察的东西
| 评测基准 | 主要面向 | 典型任务 | 结果判定方式 |
|---|---|---|---|
| SWE-bench | 软件工程问题修复 | 根据 GitHub Issue 生成代码补丁 | 运行隐藏测试集 |
| Terminal-Bench | 终端智能体能力 | 操作终端完成命令、调试、版本管理 | 检查命令结果和输出 |
| LiveCodeBench | 代码生成与推理 | 在线算法题 | 执行测试用例 |
| AgentBench | 多环境智能体 | 操作系统、数据库、网页等 | 执行结果结合规则 |
SWE-bench 关注的是模型能否理解一个真实 Issue 并生成可通过测试的补丁。Terminal-Bench 更关注智能体能否在终端环境里逐步操作，比如创建文件、运行脚本、读取日志、修正参数。LiveCodeBench 本质上更接近代码生成评测，它不要求智能体操作终端，只要求生成正确代码。
这些基准的差异意味着：一个智能体在 Terminal-Bench 上表现很好，并不代表它能在 SWE-bench 上拿高分。反之亦然。
3.2 同一个智能体为什么在不同评测集上名次不同
造成名次漂移的原因可以分成四类。
第一，技能维度不同。SWE-bench 需要长上下文理解和精准生成 diff；Terminal-Bench 需要多轮命令交互和错误恢复能力。一个模型可能长上下文能力强但命令纠错能力弱。
第二，任务粒度不同。SWE-bench 的每个任务可能需要阅读多个文件、理解项目结构、修改代码；Terminal-Bench 的某些任务可能只是执行一条命令并检查输出。智能体在复杂任务上的策略和在简单任务上的策略完全不同。
第三，成功标准不同。有的基准要求“最终状态正确”，有的要求“生成补丁能通过隐藏测试”，还有的要求“交互过程中不能有高成本操作”。对同一个任务，用不同标准判断会得到完全不同的结论。
第四，尝试次数策略不同。有的评测允许智能体反复尝试直到超时，有的只统计第一次成功。多轮尝试会显著提高成功率，但也让结果更难以解释。
3.3 评测污染、版本漂移和口径不一致
“为什么报告中的结果互相矛盾”还有一个重要来源：评测集可能进入了模型的训练语料，或者模型版本已经更新。
公开评测集一旦被广泛传播，新训练的模型就有可能见过题目。此时评测成绩反映的更像“记忆能力”而不是“泛化能力”。这是很多综述不愿意面对但必须承认的问题。
版本漂移也很常见。同一个终端智能体，底层模型从旧版本升级到新版本后，命令生成质量可能显著变化。如果两份报告分别引用升级前后的结果，又没有标注版本，单看数字就会觉得矛盾。
口径不一致指成功判据、超时时间、是否人工辅助等细节不同。同样是“80% 成功率”，一个来自单轮自动执行，一个来自多轮人工辅助执行，两者完全不可比。写综述时，这些信息每一项都必须记录。
4. 使用场景不同会让同一个智能体得到两种相反评价
“这个智能体到底好不好用”在很大程度上取决于你在什么环境里使用它。本地开发和云端沙箱对智能体的要求截然不同，一个在实验室里好用的 Agent，到了生产环境可能因为权限和审计限制而表现平平。
4.1 本地开发、云端沙箱和 CI 流水线对智能体的要求
| 场景 | 网络权限 | 数据安全 | 可重复性 | 主要限制 |
|---|---|---|---|---|
| 本地开发 | 通常有外网 | 代码在本地 | 中，依赖本地环境 | 环境差异化大，操作可能影响开发机 |
| 云端沙箱 | 可控 | 数据隔离好 | 高，可构建一致镜像 | 资源受限，网络策略复杂 |
| CI 流水线 | 通常受限 | 有代码和密钥 | 高，任务幂等 | 权限管理严格，失败成本高 |
在本地开发场景，智能体可以直接修改文件、安装依赖、运行测试，体验接近“一个人坐在终端前工作”。在云端沙箱场景，智能体通常运行在隔离容器里，可以放心让它自主执行高风险操作。在 CI 流水线场景，智能体可能只负责生成命令或补丁，真正执行由流水线完成，因为涉及代码仓库权限和部署密钥。
这些场景对“成功”的定义也不同。本地任务可能以“开发体验顺畅、没破坏环境”为成功，CI 任务可能以“补丁不引入新错误”为成功，云端任务可能以“有限时间内完成全部步骤”为成功。
4.2 自主程度与人工确认会改变任务结果
如果两个评测分别使用不同执行模式，结果几乎无法直接对比。常见执行模式包括以下四种。
- dry-run 模式：只打印命令，不真实执行。用于模型行为检查和成本预估。
- confirm 模式：每执行一条高风险命令前都询问用户。安全但慢，人工成本高。
- auto 模式：智能体自主执行全部命令，只在任务结束时汇报。效率高但风险大。
- audit 模式：全自主执行，但把每一步操作写入审计日志，事后可追溯。适合与权限回收配合。
举一个常见例子：在 confirm 模式下，智能体想执行npm install，需要等用户确认；用户如果不理解，可能会拒绝，导致任务失败。在 auto 模式下，同样任务会自动执行并成功。如果把两个模式的结果放进同一种成功率统计里，得出的结论就没有意义。
4.3 安全策略和权限模型影响成功率之外的所有指标
终端智能体的权限模型不只是安全话题，也直接决定可用性。用一个简化的 YAML 示例说明最小权限原则在终端智能体上的落地。
permissions: allow: - "pwd" - "ls" - "git status" - "git diff" - "npm ci" - "npm test" deny: - "rm -rf /" - "curl * | bash" - "sudo *" require_confirm: - "git push" - "rm -rf dist" - "npm publish"这个配置的含义是：只允许查看目录、Git 状态、安装依赖和运行测试；禁止危险命令；对推送仓库、删除构建目录、发布 npm 包这类高风险操作要求人工确认。
权限模型一旦变化，成功率、耗时、token 消耗都会变化。在一个允许全权限的环境里，智能体可以自由尝试；在最小权限环境里，很多任务根本执行不了。综述如果不说明权限配置，读者看到“这个 Agent 比那个 Agent 差”，就会产生错误归因。
5. 不被综述带偏：自己搭一套可复现的终端智能体评测
选择终端智能体的正确方式不是比较论文摘要，而是建立自己的评测任务集，在固定条件下验证。这里的核心原则是：任务要贴近实际，环境要可复现，判定要客观。
5.1 先定义任务集，而不是先比较总分
一份好的任务集应该覆盖四类任务：命令操作、代码修改、环境配置、排错恢复。每个任务都应有明确的输入、准备步骤、成功判据和超时时间。
下面是一个任务描述示例，使用 YAML 记录，便于脚本化执行。
task: id: t001 name: fix-dependency-conflict description: 修复项目中的依赖冲突，使 npm test 通过 setup: - git clone https://example.com/repo.git - cd repo && git checkout v1.0.0 success_criteria: - npm ci 执行成功 - npm test 全部通过 timeout_seconds: 900 execution_mode: confirm model: claude-3-5-sonnet任务集的规模不需要很大。对于内部选型，20 到 50 个任务已经能暴露稳定差异。关键是要覆盖自己实际工作的典型场景，而不是从公开评测集里随便抽几条。
5.2 固定环境、模型和执行模式的评测步骤
为了让多次评测可以复现，需要把环境固定下来。推荐用容器镜像来保证每次运行的文件系统、工具版本一致。
docker build -t terminal-agent-eval:${COMMIT_ID} . agent eval --config eval.yaml --suite ./suites --output ./results固定内容包括：
- 容器镜像的提交哈希
- 底层模型的名称和版本
- API 端点和超时参数
- 执行模式（auto、confirm、audit）
- 上下文长度上限
- 最大步数和总时长
- 评测任务集版本
每次运行后，日志必须保留原始命令、输出、退出码和最终判定结果。没有这些信息，任何“成功”或“失败”都无从复核。
5.3 分析结果时重点关注哪些指标和日志
只看最终成功率是最容易犯的错误。至少应该同时记录以下指标。
| 指标 | 含义 | 为什么重要 |
|---|---|---|
| 一次通过率 | 未经过修正就成功完成 | 反映模型对任务的理解质量 |
| 最终成功率 | 经过多轮尝试后成功 | 反映智能体的容错和恢复能力 |
| 平均命令数 | 完成任务用了多少条命令 | 衡量执行效率和规划能力 |
| 平均 token 消耗 | 单任务消耗多少上下文 | 直接关系到成本 |
| 平均耗时 | 从任务开始到结束的时间 | 影响生产环境可用性 |
| 失败原因分布 | 环境、理解、权限、命令错误的比例 | 帮助定位瓶颈 |
失败原因分类可以按下面几种统计：环境准备失败、任务理解偏差、命令语法错误、依赖安装失败、权限不足、超时、模型生成不稳定。如果一份评测里失败原因以“权限不足”为主，说明问题不在智能体能力，而在环境配置。
6. 常见误区、排查路径与生产落地清单
综述对比中的“矛盾”，大多数可以通过检查实验条件来消除。这一部分归纳常见误导方式，并给出生产落地时需要遵守的工程底线。
6.1 综述里最容易误导人的六种对比方式
| 误区 | 为什么错 | 正确做法 |
|---|---|---|
| 用不同时间点的结果对比 | 模型和工具版本都会变化 | 同时段重新验证 |
| 忽略底层模型版本 | 同 Agent 换模型后表现差异大 | 明确记录模型版本 |
| 拿 confirm 模式比 auto 模式的自主性 | 执行模式不同，不可比 | 统一执行模式 |
| 只对比成功率 | 忽略成本和安全性 | 同时看耗时、token 和失败原因 |
| 忽略环境差异 | 容器与本地环境差异巨大 | 统一镜像和目录结构 |
| 被演示视频误导 | 演示通常挑选成功案例 | 用任务集重复运行并统计方差 |
6.2 当两份报告出现矛盾时，按这条链路排查
面对两个互相矛盾的对比结论，不要马上判断谁对谁错。按以下顺序检查。
- 确认两份报告的时间段是否重叠，模型和 Agent 版本是否一致。
- 确认执行模式是否相同，是否一个用 confirm、一个用 auto。
- 确认评测任务集是否一致，成功判据是否相同。
- 确认运行环境是否一致，本地、容器、CI 的网络和权限差异是否被处理。
- 确认统计口径，成功率是最终成功率还是一次通过率。
- 查看原始日志和失败任务分布，判断差异由少数异常任务造成，还是整体水平差异。
- 用相同配置在同一任务集上重复运行至少三轮，观察方差。
6.3 学习环境、测试环境和生产环境的实施差异
学习环境的目标是快速体验，可以直接运行官方 demo，使用默认配置，把项目放在临时目录里，不要连接真实生产仓库。
测试环境的目标是评估真实能力，应该建立固定任务集、固定容器镜像、固定模型版本，并保留全部运行日志。
生产环境的目标是受控落地，终端智能体不能直接获得生产服务器的高权限。推荐的最低要求如下。
- 使用最小权限账户，只授权任务所需的目录和命令。
- 高风险操作必须有人工确认，或者接入审批流程。
- 所有执行记录写入审计日志，包含时间、命令、退出码和执行者。
- 设置资源限制，包括最大步数、最大 token 数、最大运行时长。
- 对文件系统做快照或版本控制，方便回滚。
- 配置异常通知，智能体连续失败时及时告警。
7. 综述写作与选型：把结论建立在可复现的事实上
无论你是要写一篇终端智能体综述，还是要为公司做技术选型，最底层的方法论是一致的：减少不确定信息，保留可复现信息。
7.1 写综述或选型报告时应该保留哪些信息
一份合格的对比报告，至少应该包含以下元数据。
- 智能体名称和版本
- 底层模型名称和版本
- 评测时间
- 执行模式
- 权限配置
- 容器镜像或系统环境
- 评测任务集名称和版本
- 成功判据
- 单任务最大步数、超时时间
- 运行轮次和结果方差
没有这些信息，任何对比结论都只能用于初步参考，不能用于正式选型。
7.2 终端智能体落地时的工程底线
终端智能体不是更大的代码生成模型，它是一套可以修改真实环境的自动化系统。落地时应该像对待发布系统一样对待它，而不是像对待聊天机器人一样。
安全边界要前置设计：在接入终端智能体之前，先明确它能访问哪些目录、能执行哪些命令、能连接哪些网络。日志要默认全量记录，而不是失败时才记录。权限控制要支持按任务粒度动态收缩，不能一个授权贯穿所有任务。遇到系统被误操作或命令链条失控时，要能利用快照快速回滚。
7.3 后续值得关注的扩展方向
终端智能体的发展还处在早期，以下几个方向值得持续关注。
评测标准化：终端智能体的评测会逐渐从“看论文数字”转向“看可复现基准”，更多团队会建立内部任务集，把评测纳入 CI 流程。
多智能体协作：一个智能体负责理解任务，另一个负责代码修改，第三个负责测试验证，每个角色都能在更窄的权限范围内运行，有助于控制风险。
可观测性增强：执行轨迹、命令副作用、上下文窗口利用率都会成为调试和选型的标准指标。
安全沙箱成熟化：更细粒度的系统调用过滤、文件系统虚拟化和网络代理，会让终端智能体在生产环境中获得更大的操作空间，同时不突破审计边界。
对比终端智能体时，最需要保留的判断是：没有脱离环境和配置的绝对能力排名。一份可靠的综述，真正有价值的不是“谁第一谁第二”，而是那些可以被复现的运行条件、失败原因统计和生产风险提示。下次再看到两个结论完全相反的终端智能体报告，优先去对比它们的评测时间、模型版本、执行模式和环境配置，而不是急着相信某一个结论。你能找到的“矛盾”，往往就是评测信息不完整留下的缺口，也是你自己搭建评测任务集时最该补上的位置。
