terminal-bench：可自动执行与判分 100+ 真实任务的 LLM 代理终端评测基准
【免费下载链接】terminal-bench-1A benchmark for LLMs on complicated tasks in the terminal项目地址: https://gitcode.com/GitHub_Trending/tb/terminal-bench-1
terminal-bench 是面向 LLM 代理的终端任务评测框架。它将 100 多个真实终端任务整理成版本化数据集，在隔离容器中自动执行任务并跑测试判分，省去为每次模型评测手工搭环境、写用例的重复工作。
问题场景：手工测终端能力为什么不可靠
评估一个代理的终端能力时，手工测试有三个坑：用例随手写、环境各机器不同、结果不可复现。同一个模型可能这次完成任务、下次失败，你分不清是模型问题还是环境问题。terminal-bench 的任务集针对的就是这件事：每个任务都有明确描述、测试脚本和参考方案，执行全部发生在 Docker 沙箱里，同一条命令任何时候跑都可比。
🚀 如何运行第一次 terminal-bench 评测
前提条件：宿装有 Docker，并配置好对应模型的 API key。安装用uv tool install terminal-bench（也提供 pip 包，按常规方式安装即可），装好后会得到一个tb命令。随后即可发起第一次评测：
tb run --agent terminus --model anthropic/claude-3-7-latest
terminus 代理负责把模型接到终端上，默认使用仓库内置任务目录。耗时取决于任务数量与并发，结束后控制台输出汇总表，细节写入输出目录。
🔄 terminal-bench 评测流程内部如何运作
数据流分三个阶段：任务下发 → 代理执行 → 测试验证。
任务下发：执行引擎 terminal_bench/harness/harness.py 读取任务目录里 task.yaml 的英文描述，按任务的 Dockerfile 与 docker-compose.yaml 为每个任务拉起独立容器，并应用任务声明的代理超时与测试超时。
代理执行：代理拿到任务描述后循环做"观察终端输出、决定下一条命令、写入容器"。内置代理实现集中在 terminal_bench/agents/，其中包括直接执行参考方案 solution.sh 的 OracleAgent，常用于先验证整条流水线是否跑得通。
测试验证：代理停止或超时后，框架在容器内执行 run-tests.sh，用任务声明的解析器（如 pytest）解析测试输出，把每条用例的通过情况写入 results.json。
📊 terminal-bench 结果日志怎么看
结果默认写入 runs/ 目录（可用 --output-path 改）。每个任务一个子目录，内容分五类：results.json 记录各用例通过与总体判定；commands.txt 是代理发出的完整命令历史；panes/ 下是代理执行前、执行后、测试后的三张终端画面快照，用来判断"卡在哪一步"；sessions/ 是 asciinema 录像，可逐帧回放；agent-logs/ 是代理自身日志。
运行结束时控制台输出汇总表：Resolved Trials（解决数）、Unresolved Trials、Accuracy 与 Pass@k。想要可视化，项目自带一个 Streamlit 仪表盘（dashboard/ 目录），可按运行回放过程并查看各任务得分。
tb run 常用参数表
| 参数 | 作用 |
|---|---|
| --task-id | 指定任务 ID 或 glob 模式，可重复传入 |
| --n-tasks | 只运行前 N 个任务 |
| --exclude-task-id | 排除指定任务 |
| --n-concurrent | 并发试次数，默认 4 |
| --n-attempts | 每个任务尝试次数，配合计算 pass@k |
| --dataset | 数据集名与版本，如 terminal-bench-core==0.1.1（对应官方榜单题集） |
| --agent-kwarg | 以 key=value 形式给代理传额外参数 |
| --global-timeout-multiplier | 全局超时倍数，默认 1.0 |
| --no-rebuild | 跳过重建容器镜像 |
如何自定义任务：最小三件套
新增任务只需三个文件：task.yaml（英文指令与超时等运行参数）、run-tests.sh 加 tests/（测试验证脚本）、solution.sh（参考方案）。把它们和 Dockerfile 一起放进以任务命名的目录，harness 即可识别。仓库在 terminal_bench/cli/template-task/ 提供了模板可直接照抄。任务也不限于纯 shell 操作，例如 original-tasks/ 下的 interactive-maze-game 要求代理在 9x9 迷宫里找出路：
🛠 常见问题排查：4 条 Q&A
Q：评测中途报错或卡住，怎么定位？ 先看 run.log 与该任务输出目录；镜像构建失败、内存不足通常体现在构建阶段。可临时把并发降到 1 再复现，排除资源争抢。
Q：代理超时了，但任务显然做得到？ task.yaml 里的 max_agent_timeout_sec 控制代理时限，可用 --global-timeout-multiplier 放大，或用 --global-agent-timeout-sec 全局覆盖。
Q：结果和榜单对不上？ 确认 --dataset 传的版本与榜单一致（terminal-bench-core==0.1.1）。不指定版本时默认取 head，终端会有提示，且未必对应榜单口径。
Q：想复盘代理到底做了什么？ 看该任务输出目录的 commands.txt 与 panes/ 快照即可；sessions/ 里的录像支持完整回放。
对正在做代理开发、模型选型评测，或需要可复现终端任务分数的团队，terminal-bench 提供的是一套现成的"任务集 + 沙箱 + 判分"基础设施。
【免费下载链接】terminal-bench-1A benchmark for LLMs on complicated tasks in the terminal项目地址: https://gitcode.com/GitHub_Trending/tb/terminal-bench-1
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
