ProgramBench 是一个开源的AI 评估框架，用来回答一个问题：大语言模型能否从零重建一个完整的程序？在 ProgramBench 中，AI Agent 只能拿到一个编译好的二进制文件和文档，必须自己架构并实现一个能复现原程序行为的完整代码库。本文带你用5 分钟完成 ProgramBench 安装、镜像自动拉取，并运行你的第一次 AI 评估，文末附常用参数清单。

🧭 什么是 ProgramBench？

ProgramBench 的评估流程可以概括为四步：

1. 选取一个开源 CLI 工具（以 Rust / Go / C 项目为主）；
2. 把它编译进一个移除源码的 Docker 镜像（cleanroom 环境）；
3. 让 LM Agent 只能通过"与二进制交互"的方式逆向出完整实现；
4. 用 AI 生成的行为测试（behavioral tests）给重建出来的实现打分。

仓库内置了上百个真实任务的评估数据，每个任务目录都包含task.yaml（仓库、commit、语言、难度等元信息）和tests.json（测试分支与忽略项清单），例如：

• 任务定义示例：task.yaml
• 测试清单示例：tests.json

完整任务库位于 src/programbench/data/tasks/ 目录，另有内置的 correct / incorrect 对照运行结果可参考 src/programbench/data/test_runs/。

✅ 开始前的环境准备

💡 提示：programbench eval会自动拉取所需 Docker 镜像，无需手动 pull。

🚀 5 分钟安装 ProgramBench

官方推荐用 Python 包管理器uv，一行命令即可完成安装：

# 免安装直接运行 uvx programbench --help # 或安装到当前项目 uv pip install programbench # 或传统 pip 方式 pip install programbench

如果想在源码中调试或贡献，也可以克隆仓库（https://gitcode.com/gh_mirrors/pr/ProgramBench ）后执行uv sync。安装完成后 CLI 入口即programbench命令：命令定义在 cli/main.py，评估核心逻辑在 eval/eval.py。

📦 理解镜像拉取机制

评估镜像统一来自 Docker Hub 的programbench组织，使用task_cleanroom_v6标签。镜像名规则很简单：任务 ID 中的__替换为_1776_。例如任务ffmpeg__ffmpeg.360a402对应的镜像是：

programbench/ffmpeg_1776_ffmpeg.360a402:task_cleanroom_v6

镜像命名函数可参考 constants.py。

除了镜像，每个任务的测试包（test blobs）会在评估时按需从 HuggingFace 下载。如果想提前预热缓存，可以执行：

uv run programbench blob sync # 全量预下载 uv run programbench blob sync <instance_id> # 只下载单个任务

▶️ 运行你的首次 AI 评估

第 1 步：准备 run 目录

把 Agent 产出的完整代码库打包为submission.tar.gz，并按"任务 ID 一个子目录"的结构组织：

my-first-run ├── testorg__calculator.abc1234 │ └── submission.tar.gz ├── abishekvashok__cmatrix.5c082c6 │ └── submission.tar.gz └── ...

第 2 步：一条命令启动评估

uv run programbench eval /path/to/my-first-run

它会自动完成：拉取镜像 → 编译 submission → 在独立容器内执行行为测试 → 在每个任务目录写出<instance_id>.eval.json结果文件，并在结束时打印整体摘要。

第 3 步：常用参数速查

参数完整定义见 cli/main.py。

📊 查看评分：programbench info

评估完成后，任何时候都可以重新打开汇总视图：

uv run programbench info /path/to/my-first-run

它会读取每个实例的tests.json，剔除被标记为不可靠（ignored）的测试分支，再按统一口径计算最终得分——官方强烈建议以programbench info的口径为准。单个eval.json的字段含义（test_results、log、executable_hash等）说明详见 docs/README.md。

🏁 进阶：提交到排行榜

评估通过后，还可以把 run 目录打包为正式提交（生成submission.yaml与_stats/score.json），校验一致性，再走 PR 注册到 leaderboard：

uv run programbench submit package /path/to/my-first-run # 打包为提交 uv run programbench submit verify ./submission-dir # 一致性校验 uv run programbench submit register ./submission-dir # 注册提交

提交生命周期源码见 cli/submit.py，提交模板位于 data/templates/。

❓ 常见问题 FAQ

Q1：macOS / Windows 上能跑吗？不能原生运行。官方镜像仅构建linux/amd64，请使用 Linux x86_64 机器。

Q2：评估时一直卡在下载怎么办？镜像与测试 blob 都是按需拉取的，先用programbench blob sync预热，并确认机器能正常访问 Docker Hub 与 HuggingFace。

Q3：只想试跑一个任务？组合过滤参数即可：programbench eval <run_dir> --filter 'testorg__calculator.*' --slice 0:1。

Q4：Agent 推理阶段需要联网吗？不需要，且必须断网——这是 ProgramBench 保证"从零重建"公平的规则之一。

📚 延伸阅读

• 完整使用指南：docs/README.md
• 项目说明：README.md
• 评估核心代码：src/programbench/eval/
• 工具函数（镜像控制、数据加载等）：src/programbench/utils/

按以上步骤，你已经在 5 分钟内完成了 ProgramBench 的安装、镜像自动拉取和首次 AI 评估。接下来可以逐步调大--workers并行度，跑满整个任务库，测出你的 Agent 在"从二进制到源码"这一硬指标上的真实水平。