3 步跑通 terminal-bench：AI 终端评测的完整实战指南

3 步跑通 terminal-bench：AI 终端评测的完整实战指南

【免费下载链接】terminal-bench-1A benchmark for LLMs on complicated tasks in the terminal项目地址: https://gitcode.com/GitHub_Trending/tb/terminal-bench-1

terminal-bench 是一个面向 AI 终端评测的基准框架：它把语言模型接入一个隔离的 Docker 终端环境，让 AI 代理自主完成写代码、修环境、起服务这类真实任务，再用测试脚本自动判定结果。本文从安装到第一次跑通评测，再到内部数据流、并发调优与自定义任务开发，把一条完整的评测链路讲清楚。

先看一个真实的评测场景

以最基础的任务hello-world为例，代理在容器里只拿到一句英文指令：创建一个/app/hello.txt，内容写入Hello, world!。代理自行决定执行什么命令；任务结束后，评测器在容器内运行tests/test_outputs.py，用 pytest 断言文件存在且内容精确匹配。通过即记一次成功。

这就是整个基准的判定逻辑：指令、测试脚本、参考解三件套齐全，结果不靠人眼看日志。仓库目前在 original-tasks/ 目录下内置了 200 多个原始任务，覆盖文件操作、Git 修复、编译 C/Rust 程序、训练模型、搭建 Web 服务等场景，每个任务一个独立目录，任务注册表 负责版本化管理。

terminal-bench 是什么，解决谁的问题

一句话定位：terminal-bench 是给构建 LLM 代理、评测框架或系统级推理能力的团队提供的可复现 AI 终端评测工具——任务数据集 + 执行 harness 两部分组成，通过tbCLI 驱动。

• 任务数据集：每个任务 = 英文指令（task.yaml）+ Docker 环境 + 测试脚本（run-tests.sh）+ 参考解（solution.sh或solution.yaml）。
• 执行 harness：位于 terminal_bench/harness/，负责把模型连到沙箱终端、并发调度、记录与判定。
• 代理层：terminal_bench/agents/ 内置 terminus、oracle 等实现，也支持 OpenHands、ClaudeCode、Aider、Goose 等安装型代理和 MCP 代理。

安装并跑通第一次评测

环境要求：Python 3.12+、Docker（沙箱必须）、uv包管理器。

1. 安装 CLI：uv tool install terminal-bench（也可以pip install terminal-bench），装完用tb --version验证。
2. 用 oracle 代理验证管线：tb run --agent oracle --task-id hello-world。oracle 不接模型，直接执行任务的参考解并跑测试。这一步能确认你的 Docker 环境和测试链路没问题，是排查配置问题的最快方式。
3. 接入真实模型：tb run --agent terminus --model anthropic/claude-3-7-latest，代理会在容器内自主执行任务，结果写入输出目录。

运行结束后，默认输出落在runs/目录下，按run_id（默认时间戳YYYY-MM-DD__HH-MM-SS）组织：每个任务一个 trial 目录，包含run.log运行日志和 asciinema 录制的完整终端录像。用tb tasks list可以浏览当前数据集里所有可用任务。

一次评测的完整数据流

顺着一次tb run的执行过程看，系统内部是这样运转的：

1. 解析数据集：harness 读取 registry.json，确定任务集合（本地original-tasks/或指定版本的terminal-bench-core数据集），应用--task-id、--n-tasks、--exclude-task-id做筛选。
2. 构建沙箱：按任务的Dockerfile基于基础镜像构建容器（--no-rebuild可跳过）。
3. 代理接管终端：通过 tmux 会话把指令注入容器终端，代理（如 terminus）循环执行「读输出 → 调 LLM → 发命令」；AsciinemaHandler 同步录制全过程。
4. 超时与判定：任务到达max_agent_timeout_sec或代理主动结束，harness 在容器内执行run-tests.sh，由 pytest 产出结构化结果。
5. 汇总产出：每个 trial 生成TrialResults（含成功与否、失败模式），整轮汇总为BenchmarkResults写入输出目录；加--upload-results可上传到远端。

并发在这一层生效：--n-concurrent（默认 4）控制同时运行的容器数，--n-attempts控制每任务重复次数。

熟练之后：调并发、筛任务、写新任务

常用参数速查

写一个自定义任务：新建目录放入四样东西——task.yaml（指令、parser_name、超时配置）、Dockerfile（环境）、run-tests.sh+tests/test_outputs.py（判定）、solution.sh（参考解）。写好先用tb run --agent oracle --task-id 你的任务名验证参考解能通过测试，再换真实模型评测。任务可以引用数据文件甚至图片，比如 code-from-image 任务 直接给模型一张代码截图，要求它复现程序：

对接其他基准：adapters/ 目录提供了 SWE-bench、MLE-bench、AppWorld 等外部基准的适配层，可以把它们的任务转成 terminal-bench 格式统一评测。

排错与常见问题

• 评测结果异常：先看runs/<run_id>/下的run.log，再回放 asciinema 录像定位代理卡在哪一步；日志级别用--log-level调高可看到更多细节。
• 镜像构建慢：调试阶段加--no-rebuild复用已有镜像；跑完用默认的--cleanup行为清理 Docker 镜像，避免磁盘占满。
• 机器资源不够：把--n-concurrent降到 1~2，同时控制--n-attempts，先小规模验证再全量跑。

小结与下一步

terminal-bench 的价值在于把「AI 代理能不能在终端干活」变成可复现、可对比、可自动判定的指标。建议的行动路径：先tb run --agent oracle --task-id hello-world打通管线，再用--n-tasks 5跑一个小样本对比两个模型，最后用--dataset-name terminal-bench-core --dataset-version 0.1.1对齐排行榜口径做正式评测。

【免费下载链接】terminal-bench-1A benchmark for LLMs on complicated tasks in the terminal项目地址: https://gitcode.com/GitHub_Trending/tb/terminal-bench-1