论文精读：NL2Repo-Bench — 从自然语言到完整代码仓库，Coding Agent 的长程生成评测
精读字节跳动 Seed 联合南大、北大等提出的 NL2Repo-Bench：首个端到端仓库生成基准，给一份需求文档从零构建完整 Python 库。104 个任务、9 个领域、严格 pytest 验证。Claude 4.5 最高 40%，GPT-5 仅 22%，暴露了长程规划、架构设计和自主执行的巨大 gap。
论文：NL2Repo-Bench: Towards Long-Horizon Repository Generation Evaluation of Coding Agents 作者：ByteDance Seed、M-A-P、2077AI、南京大学、北京大学等 发布：2025-12（v1），2026-01（v2） 代码：GitHub
一句话总结
给 Agent 一份自然语言需求文档和一个空文件夹，要求从零构建完整的 Python 仓库并通过原始 pytest 测试。最强的 Claude 4.5 也只能通过 40% 的测试，GPT-5 仅 22%。
一、为什么需要这个基准
现有 Coding Agent 基准的能力评测谱系是这样的：
函数级 文件级 仓库级（修复） 仓库级（生成）
HumanEval/MBPP → CrossCodeEval → SWE-bench/Commit0 → NL2Repo-Bench
✅ 已饱和 ✅ 接近饱和 ⚠️ 进展中 ❌ 新前沿| 基准 | 输入 | 任务 | 输出 | 本质 |
|---|---|---|---|---|
| HumanEval | 函数签名 + docstring | 写一个函数 | 一段代码 | 补全 |
| SWE-bench | 代码仓库 + issue | 修一个 bug | 一个 patch | 修复 |
| PaperBench | 论文 PDF | 复现实验 | 代码+实验结果 | 复现 |
| NL2Repo-Bench | 仅自然语言文档 | 从零构建完整仓库 | 可安装的 Python 包 | 创建 |
SWE-bench 给了现成的代码仓库让你改，PaperBench 给了论文让你实现——但现实中很多开发工作是”从一份需求文档开始，写出完整的项目”。NL2Repo-Bench 填补的就是这个空白。
核心区别：其他基准都提供了某种形式的代码先验（已有仓库、函数签名、代码框架），NL2Repo-Bench 什么都不给——空文件夹 + 需求文档 = 你的全部起点。
二、任务定义
输入
一份标准化的自然语言规格文档（平均 ~18,800 tokens），包含四部分：
- 项目描述：整体功能和设计目标
- 支持信息：依赖关系、环境要求
- API 使用指南：外部接口的使用示例
- 实现节点：内部架构和模块划分的详细描述
输出
一个完全可安装的 Python 库——不是代码片段，不是 notebook，而是可以 pip install 的完整包。
评估
在隔离 Docker 容器中运行目标仓库的原始 pytest 测试套件。没有 LLM Judge，没有人工评分——测试过了就是过了，没过就是没过。
这使得 NL2Repo-Bench 的评估完全确定性，不存在评分偏差问题。
三、构建方法
3.1 仓库选取
从 GitHub 筛选 Python 开源仓库，准入门槛：
| 维度 | 标准 |
|---|---|
| 活跃度 | 近 3 年内有更新 |
| 权威性 | ≥10 GitHub Stars |
| 完整性 | 包含 pytest 测试套件，且源码能通过自测 |
| 规模 | 300–120,000 LOC |
| 代表性 | 覆盖 9 个领域 |
3.2 需求文档生成——逆向工程
这是构建方法中最巧妙的部分：
现有仓库代码
↓
AST 静态扫描（提取所有 API 签名：类、函数、参数）
↓
逐 API 生成详细描述
↓
组装为标准化需求文档
↓
人工专家 + AI 工具双重校验关键操作：
- AST 辅助注释：先用 AST 解析器扫描目标仓库提取全部 API，再逐一生成描述，确保文档覆盖所有公开接口
- 静态覆盖率验证：自动检查文档是否遗漏了 API
- 四阶段 QA：人工文档审核 → 静态工具检测 → 镜像环境验证 → 预实验验证（用 SOTA Agent 跑一遍排除环境歧义）
3.3 任务统计
| 维度 | 数据 |
|---|---|
| 总任务数 | 104 |
| 领域覆盖 | 9 类：Web 开发、测试、工具库、ML、数据处理、数据库交互、网络工具、批处理、系统工具 |
| 难度分布 | Easy（≤1,500 LOC）26 个 / Medium（1,500–4,000 LOC）46 个 / Hard（≥4,000 LOC）32 个 |
| 平均输入 | ~18,800 tokens |
| 平均输出 | 数千行代码，多文件结构 |
四、实验结果
4.1 主实验
在 OpenHands-CodeAct Agent 框架下评估（部分模型同时在 Cursor-CLI 和 Claude Code 下测试）：
| 模型 | 框架 | 总体通过率 | Pass@1 | Easy | Medium | Hard |
|---|---|---|---|---|---|---|
| Claude-Sonnet-4.5 | Claude Code | 40.2% | 3 | 51.8 | 44.5 | 25.1 |
| Claude-Sonnet-4.5 | OpenHands | 39.9% | 3 | 55.3 | 43.0 | 21.4 |
| Claude-Sonnet-4.5 | Cursor | 39.2% | 4 | 52.9 | 41.4 | 24.8 |
| Claude-Sonnet-4 | OpenHands | 37.0% | 5 | 53.1 | 41.3 | 16.1 |
| Gemini-3-pro | Cursor | 34.2% | 3 | 44.9 | 40.9 | 16.8 |
| DeepSeek-V3.2 | OpenHands | 27.6% | 1 | 43.1 | 29.1 | 12.9 |
| Kimi-K2 | OpenHands | 22.7% | 3 | 40.8 | 20.2 | 11.6 |
| GPT-5 | OpenHands | 21.7% | 1 | 38.4 | 20.7 | 9.6 |
| Qwen3-Instruct | OpenHands | 17.9% | 1 | 34.7 | 15.2 | 8.9 |
| GLM-4.6 | OpenHands | 17.5% | 2 | 34.4 | 15.5 | 6.5 |
| Qwen3-thinking | OpenHands | 13.8% | 1 | 25.0 | 11.3 | 6.5 |
几个关键数字：
- 最强的 Claude 4.5 也只有 40%，Hard 任务降到 25%
- Pass@1（完全通过所有测试）最多只有 5 个——104 个仓库里只有不到 5% 能完美复现
- Claude 在三个不同框架下表现几乎一致（~39-40%），说明瓶颈在模型本身而非框架
4.2 GPT-5 的”协作偏差”
GPT-5 的 21.7% 低于预期。分析发现原因不是能力不行，而是行为模式不对：
| 指标 | Claude 4.5 | GPT-5 |
|---|---|---|
| 平均交互轮数 | 180+ | 78.4 |
| 早退率 | 低 | 高 |
GPT-5 倾向于过早停止并等待用户输入——它更像是一个”协作编程助手”而非”自主开发者”。这暴露了一个有趣的 alignment 副作用：为了在人机协作场景中表现好而做的对齐训练，反而损害了完全自主执行的能力。
4.3 Thinking 模型的”过度自信”
Qwen3-thinking 表现最差（13.8%），原因出人意料：
| 指标 | Qwen3-thinking |
|---|---|
| 早退率 | 49.0% |
| 未完成率 | 46.2% |
将近一半的任务 Agent 自己觉得”做完了”就停了，但实际远未完成。分析认为是 thinking 机制导致了“幻觉验证”——模型在内部推理中误以为代码已经通过测试，但从未实际运行验证。
4.4 消融实验
轮次限制：性能随交互轮数增加而提升，但在约 200 轮后饱和。瓶颈不在步数，在语义理解和架构规划。
开卷考试（提供测试用例）：Claude 4.5 从 40.2% → 59.4%。即使告诉你”答案长什么样”，依然有 40% 做不到——说明核心困难不是”不知道要做什么”，而是”做不到”。
五、工具使用行为分析
论文对 Agent 的工具使用模式做了深入分析，这部分非常有洞察：
高性能 Agent 的行为模式
编辑代码 (str_replace_editor) → 运行测试 (execute_bash) → 分析结果 → 编辑修复 → 再测试
↑ ↓
└──────────── 测试驱动开发（TDD）循环 ────────────────────┘- 使用
task_tracker（规划工具）的频率与性能正相关（r=0.711） - 高性能模型表现出强烈的编辑-测试交替循环，类似人类的 TDD 模式
低性能 Agent 的行为模式
编辑 → 编辑 → 编辑 → 编辑 → ... → 终于想起来跑一下 → 全面崩溃- 连续多次编辑而不做中间测试，错误层层累积
- 缺乏系统性规划，大量轮次浪费在无意义的文件导航上
启示：未来 Coding Agent 的训练应该强化规划能力和 TDD 循环模式——不是写更多代码，而是更频繁地验证。
六、与其他基准的定位对比
| 维度 | SWE-bench | PaperBench | NL2Repo-Bench |
|---|---|---|---|
| 输入先验 | 完整代码仓库 + issue | 论文 PDF | 仅自然语言文档 |
| 任务类型 | 修 bug | 复现论文 | 从零构建 |
| 代码先验 | 有（现有仓库） | 无（但有论文指导） | 完全没有 |
| 评估方式 | 回归测试 | LLM Judge | 严格 pytest |
| 核心挑战 | 定位 + 局部修改 | 理解 + 全栈实现 | 架构设计 + 长程一致性 |
| SOTA | ~65%（Claude） | ~21%（Claude） | ~40%（Claude） |
NL2Repo-Bench 比 SWE-bench 难在没有代码先验——不是在别人的代码里改几行，而是从头写整个项目。比 PaperBench 简单在有清晰的需求文档——不需要从论文中提炼需求。
它占据了一个独特的生态位：给定明确需求、从零到一构建完整系统——这恰好是日常开发中最常见的场景之一。
七、局限与思考
论文自身的局限
- 仅限 Python：所有仓库都是 Python 项目。Java/Go/Rust 等语言的仓库生成可能面临不同挑战（强类型系统、编译等）
- 仓库规模受限：最大 120K LOC，而真实工业项目动辄百万行
- 需求文档质量过高：逆向工程生成的文档比真实需求文档完整得多——实际开发中的需求往往模糊、不完整、自相矛盾
- 单人场景：评测的是单 Agent 独立开发，不涉及多人协作
引发的更大问题
Coding Agent 的三个层次：
Level 1：写函数（HumanEval） → 已基本解决
Level 2：改代码（SWE-bench） → 快速进展中
Level 3：建项目（NL2Repo-Bench） → 刚刚开始
Level 4：维护演进（持续开发/重构） → 完全空白NL2Repo-Bench 打开了 Level 3 的大门。但真实开发中更难的是 Level 4——一个项目创建后需要持续维护、迭代需求、重构架构。这个方向目前没有任何基准。
从”写代码”到”做工程”的范式转变：
这篇论文最大的价值不是基准本身，而是它提出的思维转变——评测 Coding Agent 不应该只看”能不能写对一段代码”，而应该看”能不能做好一个项目”。后者涉及：
- 架构设计能力（不是给你设计好的，你自己想）
- 长程规划能力（不是一步到位，需要规划几十个文件的开发顺序）
- 自我验证能力（不是写完就完了，要自己测自己改）
- 一致性维护能力（文件 A 的修改要和文件 B 的接口对得上）
这些能力在 HumanEval 和 SWE-bench 中几乎完全不可见。
八、关键结论
- 仓库级生成是 Coding Agent 当前的真正前沿——函数级和修复级已经接近饱和，从零构建才是下一个能力瓶颈
- 40% 是当前天花板——即使是最强的 Claude 4.5 也只能通过 40% 的测试，Hard 任务降到 25%
- 规划能力比代码能力更重要——使用规划工具的频率与性能正相关（r=0.711），TDD 循环是高性能的关键行为模式
- Alignment 有副作用——GPT-5 的”协作偏差”说明针对人机协作的对齐训练可能损害自主执行能力
- Thinking 模型可能”过度自信”——内部推理导致幻觉验证，Qwen3-thinking 49% 的早退率是警示
- 上下文窗口是必要非充分条件——排名前列的模型都有超长上下文（≥1M），但 Kimi-K2（也有超长上下文）表现一般，说明基础推理能力同样关键
参考资料
- NL2Repo-Bench Team. NL2Repo-Bench: Towards Long-Horizon Repository Generation Evaluation of Coding Agents. arXiv:2512.12730, 2025.
- GitHub: multimodal-art-projection/NL2RepoBench.