一份为 AI 小白准备的全面指南，助你理解、上手并评估 AI 代码助手的能力。

1 SWE-bench 是什么？

SWE-bench（Software Engineering Benchmark）是一个专门为评测大型语言模型（LLM）解决真实世界软件工程问题而设计的基准测试集[runloop.ai]。简单来说，它就像是为 AI 代码助手准备的一场 “高考”，检验它们是否具备初级软件工程师的核心技能。

它评测的能力并非简单的代码生成，而是一个完整的 “问题解决” 流程，包括：

• 理解问题： 阅读并理解来自真实 GitHub 项目的问题描述（Issue）。
• 定位代码： 在庞大而复杂的代码库中，找到需要修改的相关文件和函数。
• 编写补丁： 编写代码补丁（Patch）来修复 Bug 或实现功能。
• 通过测试： 确保生成的补丁能够通过所有相关的单元测试，并且没有引入新的问题。

2 为什么 SWE-bench 很重要？

在 SWE-bench 出现之前，很多 AI 编码能力的评测（如 HumanEval）都类似于 LeetCode 刷题，模型只需在孤立环境中编写一个函数。但这与真实开发工作相去甚远。SWE-bench 的重要性在于其 “真实性” 和 “综合性”：
贴近真实开发场景。它模拟了开发者处理 GitHub Issue 的日常工作：面对一个不完美的需求描述，在一个庞大的既有代码库中进行多文件、跨目录的修改[epoch.ai]。这比编写孤立的算法更能反映 AI 在实际协作中的应用潜力。

客观度量 “自主修复” 能力。通过自动化测试验证，SWE-bench 提供了一个客观的标尺，用于衡量一个 AI 代理（Agent）是否真的能 “独立” 解决中小型软件问题。这对于评估和比较不同 AI 模型或工具的实用价值至关重要。

3 SWE-bench 的数据与任务构成

SWE-bench 的任务来自于真实的开源项目。最初版本的 SWE-bench 包含了从 12 个流行的 Python 开源项目（如 Django, scikit-learn, matplotlib 等）中收集的2,294 个真实问题实例。

每个评测任务（也称 “样本”）都包含以下几个关键部分[epoch.ai]：

• 修复前的代码库（Repository Snapshot）： 包含 Bug 的项目代码的特定版本。
• 问题描述（Issue）： 从 GitHub 抓取的真实用户提交的 Issue，包括标题和详细描述。
• 黄金补丁（Gold Patch）： 人类开发者为解决此问题提交并被合并的最终代码修改。
• 测试补丁（Test Patch）： 人类开发者为验证修复而添加或修改的测试代码。

评测的核心是两组自动化测试：

• Fail-to-Pass（失败到通过）： 这些测试在修复前是失败的，因为它们专门用于复现这个 Bug。一个正确的修复必须让这些测试通过。
• Pass-to-Pass（通过到通过）： 这些是项目中原有的、与此 Bug 无直接关系的其他测试。正确的修复必须保证这些测试继续通过，即没有引入 “回归性” 问题（Regression）。

4 评测流程揭秘

SWE-bench 的评测流程就像一个自动化的 “黑盒测试”，它模拟了 AI 代理从接到任务到提交代码的全过程：

1. 输入： AI 代理接收到两样东西：修复前的代码库快照和问题描述文本。它不知道 “正确答案”（黄金补丁）是什么。
2. 执行： AI 代理在一个受控的、隔离的计算环境（通常是 Docker 容器）中开始工作。它可以像人类开发者一样，使用工具（如文件查看、代码编辑、全局搜索等）来阅读、分析和修改代码。
3. 输出： 代理完成修改后，生成一个标准的 diff 格式的代码补丁（Patch）。
4. 验证： 系统会自动将这个补丁应用到代码库中，然后运行前面提到的 Fail-to-Pass 和 Pass-to-Pass 测试。只有当所有相关测试都通过时，才算作一次成功的解决。
5. 计分： 最后，根据成功解决的问题数量，计算出最终得分。

5 示例：SWE-bench 的一个 Test Instance（以 SymPy 为例）

下面用一个真实来源的简化示例，帮你直观理解 SWE-bench 的 “测试实例” 由哪些部分构成，以及 AI 代理如何被评测和判定成功。

1. 仓库与快照： 评测开始于一个特定的代码库（如 sympy）在修复问题前的版本快照。整个环境（包括依赖）被打包在一个可复现的容器中，确保测试的一致性。
2. Issue 摘要： AI 代理收到的核心输入是真实的 GitHub Issue 文本，通常包含用户的问题描述、一个用于复现 bug 的最小代码片段（MRE），以及期望的正确行为描述。
3. 测试补丁与用例： 评测系统使用两组测试来验证修复的有效性：
   1. Fail-to-Pass: 专门为复现该 Bug 而编写的新测试。修复前它必然失败，一个正确的修复必须使其转为通过。
   2. Pass-to-Pass: 仓库中已有的相关测试。正确的修复必须保证这些测试继续通过，以证明没有引入新的问题（回归）。
4. 代理/模型流程： AI 代理在容器化环境中读取 Issue 与仓库代码，分析并定位问题相关的模块与函数，然后生成一个标准 diff 格式的代码补丁（patch）提交给评测器。

下面是一个 “示意性” 的补丁片段（非原始修复，仅用于说明格式与修改类型）：

成功判定与计分清单

输入： 仓库快照 + GitHub Issue 文本

环境： 隔离的 Docker 容器
输出： 标准的代码补丁（patch diff）

验证： 应用补丁后，Fail-to-Pass 测试由失败转为通过，且 Pass-to-Pass 测试保持通过。

计分： 若验证成功，该实例记为 “Resolved”，计入最终的 % Resolved 指标。

此类 “简单但真实” 的 Bugfix 任务在 SWE-bench Verified 中占多数，其中 Django 和 SymPy 等热门仓库的样例较多。 对于更困难、更接近真实世界复杂度的场景，可以参考 SWE-Bench Pro 与 SWE-bench-Live 的设计。

6 自动化测试框架/套件 (Harness)

如果你将 SWE-bench 视为一场考试，那么自动化测试套件（Harness）就是那个一丝不苟的 “监考和阅卷系统”。它是一套用于在可复现环境中，驱动评测、应用模型生成的补丁、运行测试并记录结果的自动化执行框架。

Harness 在 SWE-bench 中的核心职责

Harness 负责整个评测流程的自动化、标准化和可信度，其具体职责包括：

• 环境准备：为每个测试实例启动一个干净、隔离的容器化环境（如 Docker），确保外部干扰最小化。
• 数据装载：将特定版本的代码库快照、问题描述（Issue）和测试用例加载到环境中。
• 补丁应用：接收由 AI 代理（Scaffold）生成的代码补丁，并将其应用到代码库上。
• 测试执行：严格执行 Fail-to-Pass 和 Pass-to-Pass 两组测试。
• 结果采集与计分：根据测试结果，判定任务是否 “Resolved”，并计算 % Resolved、pass@1 等核心指标。
• 日志与工件持久化：记录完整的执行日志（Trajectory）、命令历史、最终生成的代码补丁以及测试报告，用于后续分析和错误归因。

Harness vs. 脚手架 (Scaffold)：分工与协作

新手常常混淆 Harness 和 Scaffold，但它们角色不同，协同工作：

脚手架 (Scaffold)

角色：AI 代理的大脑和双手。它更偏向于 “模型驱动策略”，负责指导大模型如何思考和行动。它为模型提供一套工具（如文件查看器、编辑器、代码搜索）和策略（如重试、自我修正、多方案生成），最终目标是产出一个高质量的代码补丁 。

测试套件 (Harness)

角色：评测流程的规则和裁判。它更偏向于 “评测执行与验证基础设施”，不关心模型如何得出答案，只负责提供一个标准化的 “考场”，并用统一的规则来 “阅卷” 和 “计分”。

两者的协作关系是：Scaffold 产出代码补丁 (Patch)，Harness 负责验证这个补丁是否正确并给出分数。

典型实现与生态

SWE-bench 生态中有多种成熟的 Harness 和 Scaffold 实现：

• SWE-bench CLI / 官方 Docker 流程：官方提供的基础 Harness，通过命令行和 Docker 镜像实现了标准化的评测流程，是所有评测的基础。
• SWE-agent & mini-SWE-agent：不仅是流行的开源代理（Scaffold），也捆绑了完整的评测 Harness。特别是 mini-SWE-agent，以其极简设计成为 “Bash Only” 榜单的基准，用于更公平地比较模型本身的能力。
• Inspect Framework：一个在学术界评测中常用的执行框架（Harness），提供了灵活的配置和扩展性。
• RepoLaunch Agent：SWE-bench-Live 背后的强大 Harness，特别增强了对多语言（Go, JS/TS, Java 等）仓库的构建和日志解析能力，代表了更前沿的评测基础设施。

Harness 的关键能力与最佳实践

关键能力要点

• 可复现性：通过容器镜像、固定依赖版本和随机种子，保证每次评测结果的一致性。
• 可靠测试：严格执行双重校验，防止错误或不完整的修复蒙混过关。
• 资源与成本控制：支持设置超时、重试次数、内存/CPU 限额，以管理评测成本。
• 可观测性：提供详细日志、命令轨迹和失败原因标注，便于分析模型行为。
• 结果规范化：输出统一格式的产物（日志、补丁、报告），便于横向对比和提交榜单。

最佳实践与常见误区

• 先跑基线：先用 Bash Only 模式跑一个基准分，以区分模型和脚手架各自的贡献。
• 固定环境：对比不同模型时，务必使用完全相同的 Harness 和版本，避免 “环境误差”。
• 归因分析：对失败案例进行分类（定位失败、编辑错误、测试覆盖不足等），深入理解模型短板。
• 误区：仅看总分，忽视 pass@1 和执行日志。过度重试可能刷高分数，但掩盖了模型 “一次做对” 的真实能力，并极大增加成本。

Harness 评测清单

一个标准的 Harness 评测流程可以简化为以下五步：

1. 环境 (Environment)：加载正确的 Docker 镜像，创建隔离容器。
2. 数据 (Data)：装载代码库快照、Issue 描述和测试补丁。
3. 执行 (Execution)：接收并应用 AI 代理生成的代码补丁（Patch）。
4. 验证 (Validation)：运行 Fail-to-Pass 和 Pass-to-Pass 两组测试。
5. 报告 (Reporting)：输出 % Resolved、pass@1、成本和详细日志。

7 核心指标与榜单解读

% Resolved（解决率）：

这是 SWE-bench 最核心的指标，代表模型成功解决的问题占总问题数的百分比。例如，在包含 500 个问题的 SWE-bench Verified 数据集上，如果一个模型解决了 70 个，其解决率就是 14%。

Pass@1（单次尝试通过率）：

这个指标强调的是模型在 “第一次尝试” 中就成功解决问题的能力，这更贴近用户的实际体验。有些评测方法或 “脚手架”（Scaffold）可能会让模型进行多次尝试、自我修正或生成多个候选方案，这会增加成本和时间，但 Pass@1 专注于最直接、最高效的解决方案。

成本与尝试次数：

榜单上通常会标注解决每个问题所需的平均成本（例如 API 调用费用）。不同的 “脚手架”（即驱动模型执行任务的策略和工具集）会产生不同的成本。一个复杂的脚手架可能会进行大量搜索、代码分析和多次尝试，从而提高解决率，但成本也更高。

8 SWE-bench 家族：不同版本的区别

随着时间推移，SWE-bench 已经发展成一个包含多个变体的 “家族”，以应对不同的评测需求和原始版本的局限性。

版本	特点	适用场景
SWE-bench Verified	由 OpenAI 合作推出，从原版中人工筛选出 500 个高质量、描述清晰的 Python 问题 [epoch.ai]。这是目前最流行和最常被引用的版本。	社区公认的 “标准考试”，用于对比主流模型。
SWE-bench Lite	一个更小的子集（300 个问题），旨在降低评测成本和时间[swebench.com]。	快速迭代、学术研究或资源有限时的初步评测。
SWE-bench Pro	由 Scale AI 推出，难度更高，旨在解决原版的数据污染和难度问题。它包含来自 41 个仓库的 1865 个任务，并特意选用 GPL 协议或私有商业代码库以防模型 “背题”[Scale AI]。	对模型 “泛化能力” 和解决未知问题能力的压力测试。
SWE-bench-Live	由微软维护，是一个 “活” 的基准测试，每月都会增加新的问题实例，以确保评测的时效性和防止数据污染 [swe-bench-live.github.io]。	持续追踪最新模型的真实能力，进行最前沿的研究
其他变体	Multimodal: 问题描述中包含图片。Multilingual: 包含多种编程语言的问题[multi-swe-bench]。Bash Only: 使用统一的、最小化的代理来评测所有模型，以更公平地比较模型本身的能力。	针对特定能力（如多模态理解、多语言支持）的专项评测。

9 深入分析：局限性与演进

SWE-bench Verified 的特点与局限

虽然 Verified 版本是标准，但它也有明显的局限性，理解这些局限性有助于我们客观看待榜单分数[epoch.ai]：

• 任务偏向简单 Bug 修复：约 90% 的任务是经验丰富的工程师能在 1 小时内解决的小问题，其中近 40% 是 15 分钟内的 “微不足道” 的修改。它主要衡量 “修复小 Bug” 的能力，而非 “开发新功能” 或 “重构” 等更复杂的任务。
• 热门仓库集中度高：Django 一个项目就占了近一半的问题，前五大仓库占比超过 80%。这意味着模型可能在训练中已经 “见过” 这些代码库，存在 “背题” 风险（数据污染），导致分数虚高。
• “脚手架” 影响巨大： 评测成绩不仅取决于模型本身，更严重依赖于驱动模型的 “脚手架”（Scaffold）。一个好的脚手架（包含优化的工具、提示策略、多轮尝试机制）可以将模型的解决率提升 高达 20%。因此，榜单上的分数是 “模型 + 脚手架” 的综合表现。

SWE-Bench Pro 的提升

Scale AI 推出的 SWE-Bench Pro 针对 Verified 的痛点做了显著增强[Scale AI]：

• 增强防污染： 选用受 GPL 等 “病毒式” 许可证保护或完全私有的商业代码库，这些代码极不可能出现在模型的训练数据中。
• 提升任务难度和多样性： 包含更多样化、更复杂的仓库，平均代码修改量（107 行）远高于 Verified，更接近真实开发复杂度。
• 人类增补需求： 保留了原始 Issue 的模糊性，但由人类专家提炼出清晰的需求列表，既保留了挑战，又确保了可评估性。
• 可复现环境与双重校验： 每个任务都在独立的容器化环境中执行，并严格执行 fail-to-pass 和 pass-to-pass 双重校验。

Pro 版本还区分了 “公开榜” 和 “商业榜”，后者更能衡量模型在完全陌生的商业代码上的泛化能力。

SWE-bench-Live 的定位

SWE-bench-Live 则走了另一条路：保持更新[swe-bench-live.github.io]。它通过自动化流程每月从 GitHub 获取最新的、高质量的问题实例。其 Lite 和 Verified 子集保持 “冻结” 不变，以提供一个稳定的基线用于公平对比，而 “full” 全量数据集则不断更新，为前沿研究提供了一个不受污染的 “活” 靶场。

10 新手上手指南

对于想要亲手尝试 SWE-bench 的 AI 小白，这里有一份简化的上手路径和建议：
上手建议

• 从 Lite 或 Verified 开始： 这两个版本评测成本较低，文档和社区支持也最完善，适合初学者入门。
• 使用官方工具： 强烈建议使用官方提供的 Docker 环境和命令行工具（CLI），这能帮你省去大量环境配置的麻烦 [runloop.ai]。
• 准备好硬件资源： 运行 SWE-bench 对硬件有一定要求，建议准备一台拥有至少 120GB 磁盘空间、16GB+ 内存 和多核 CPU 的机器。
• 先跑通基线： 可以先尝试运行 “Bash Only” 模式，它使用最简单的代理，能让你快理解整个评测流程并得到一个基础分数。
• 再尝试流行脚手架： 熟悉流程后，可以尝试集成社区流行的脚手架，如官方的 SWE-agent 或更轻量的 mini-SWE-agent，来驱动 GPT-4、Claude 等模型，观察分数变化。

实操步骤（简版清单）

• 环境准备： 安装并配置好 Docker、Python 和 Git。
• 拉取数据与镜像： 根据官方文档，克隆 SWE-bench 仓库，并下载所需的数据集文件和 Docker 镜像。
• 选择模型与脚手架： 配置你要评测的 LLM 的 API Key，并选择一个代理（脚手架）来执行任务。
• 运行评测命令： 使用官方提供的 run.py 脚本，传入模型、数据集、脚手架等参数来启动评测。
• 分析结果： 评测结束后，系统会生成报告，显示最终的 % Resolved 分数。同时会为每个任务保留详细的日志（trajectory）。
• 错误归因： 对于失败的案例，通过分析日志来判断失败原因，例如是定位问题失败、工具调用出错，还是生成的修复方案本身逻辑错误等。

11 典型应用场景

• 评估和选型： 企业或开发者可以利用 SWE-bench 来横向比较市面上不同代码代理（如 Devin, Code-GPT 等）或底层模型（GPT-5 vs Claude 4）的真实编程能力。
• 研究和优化： AI 研究者通过分析模型在 SWE-bench 上的失败案例，可以发现当前 AI 在代码理解、规划、调试等方面的短板，从而进行针对性优化。
• 内部验证前的基准： 在将 AI 代码助手引入公司内部的私有代码库之前，先在 SWE-bench 这样的公开基准上进行测试，可以快速筛选掉表现不佳的方案，节约内部验证成本。

重要提示： 公开基准测试的分数不完全等同于在你的私人代码库上的表现。由于代码风格、复杂度、业务逻辑的差异，一个在 SWE-bench 上表现优异的代理，仍需要在你的真实环境中进行二次验证[Scale AI]。

12 常见问题（FAQ）

问：SWE-bench 是不是只测 Python？

答：原版和 Verified 版本以 Python 为主。但 SWE-bench-Live、Multi-SWE-bench 和 SWE-Bench Pro 已经扩展到了包括 Go、JavaScript/TypeScript、Java 在内的多种语言[Scale AI][swe-bench-live.github.io]。

问：模型会不会直接 “抄答案”？

答：存在这种风险，即 “数据污染”。由于 SWE-bench Verified 的问题大部分来自 2023 年之前，很可能已被模型当做训练数据学习过[epoch.ai]。SWE-Bench Pro 和 SWE-bench-Live 正是为了缓解此问题而设计的，它们采用更新、更冷门或私有的代码库。

问：为什么同一个模型在不同榜单上分数不同？

答：主要原因是 “脚手架”（Scaffold）不同。不同的团队会为同一个模型（如 GPT-4）设计不同的执行策略和工具集，这会导致性能差异巨大。此外，评测时允许的尝试次数和成本上限也不同。

问：如何理解模型在 Verified 上 70%，在 Pro 上只有 23%？

答：这恰恰说明了不同基准的难度差异。例如，Claude 4.5 Sonnet 在 Verified (Bash Only) 上能达到 70.6% 的高分，但在更难、更防污染的 SWE-Bench Pro 上，即便是最强的 GPT-5 和 Claude Opus 4.1，得分也只有 23% 左右。这表明，AI 解决简单、熟悉的 Bug 的能力已相当不错，但在面对真正陌生的、复杂的任务时，仍有很长的路要走。