技术摘要：Code-QA-Bench

问题陈述

当前针对 AI 编程代理的基准测试（如 HumanEval、MBPP 和 SWE-Bench）主要侧重于代码生成或问题修复。虽然它们在衡量补丁生成方面行之有效，但未能充分评估代码理解能力——即理解现有代码库、追踪控制流、定位功能以及解释行为的能力。在区分真正的代码推理与文档回忆或预训练记忆方面存在关键缺口。现有的仓库级问答基准测试通常在文档完整的仓库上评估代理，这使得难以判断代理是在阅读代码，还是仅仅从训练数据或提供的文档中回忆信息。

方法论

Code-QA-Bench 引入了一个全自动框架，旨在合成仓库级问答基准测试，将代码理解与文档和记忆隔离开来。该框架基于四个核心原则运行：

1. 三条件实验设计

为了量化代码访问、文档和记忆的具体贡献，每个任务均在三种不同条件下进行评估：

• 闭卷（Closed-book）： 代理仅接收问题，无法访问仓库。这衡量先验知识和记忆能力。
• 仅代码（Code-only）： 代理可访问仓库，但所有自然语言内容（文档字符串、注释、README 和文档文件）均被移除。这衡量纯粹的代码结构推理能力。
• 有文档（Documented）： 代理可访问包含所有文档的完整仓库。这衡量由文档增强的代码推理能力。

关键指标源自这些条件之间的差异：

• 仅代码 - 闭卷：超越记忆之外的代码阅读带来的真实贡献。
• 有文档 - 仅代码：文档对代码理解的效用。

2. 文档移除（环境级控制）

为了强制进行代码结构推理，该框架通过编程方式剥离每个仓库的“仅代码”版本，移除内容包括：

• 文档字符串： 通过抽象语法树（AST）识别并移除（插入 pass 以保持语法正确）。
• 注释： 移除或截断整行注释和内联注释。
• 文档文件： 删除 docs/、doc/ 等目录，以及 README*、*.md 和 *.rst 等文件。
  关键在于保留可执行代码、导入语句、类型注解和字符串字面量，确保来自标识符的语义信号得以保留。

3. 答案优先的任务生成

与以往先生成问题的方法不同，Code-QA-Bench 采用答案优先流程：

1. 块选择： 提取文档块，并根据内容质量、代码引用和结构信号进行评分。
2. 黄金答案生成： 配备工具的代理探索源代码（使用 read_file、list_directory、search_code），生成经过验证的“黄金答案”。代理被要求至少追溯比文档更深一层，并包含文本中不存在的事实。
3. 验证： 进行“仅代码审计”，确保黄金答案不包含任何只能从文档中恢复的断言。如果某项断言依赖于文档，则将其移除或重写。
4. 问题推导： 从经过验证的黄金答案中推导出自然语言问题，确保任务基于真实的代码结构。

4. 双重任务集

该基准测试生成两个不同的任务集：

• 代码可推导任务（528 个任务）： 黄金答案被验证为仅从代码结构中即可恢复。这些任务验证了设计（预期 仅代码 ≈ 有文档）。
• 文档依赖任务（100 个任务）： 黄金答案仅从文档生成，故意要求文档才能完整回答。这些任务量化了文档的效用（预期 有文档 > 仅代码）。

5. 评估

任务由 LLM 评判器（GPT-5.4）在 0–5 分制下，沿三个维度进行评分：

• 准确性： 事实断言的正确性。
• 完整性： 对评分标准中关键点的覆盖范围。
• 具体性： 对特定文件、函数或代码模式的引用。
  最终得分为这三个维度的归一化平均值。

关键结果

实验在四个前沿模型（Claude Opus 4.6、DeepSeek-V4-Pro、Kimi-K2.6、Gemini-3.1-Pro）上进行，涉及来自 SWE-Bench 的 10 个 Python 仓库。

1. 代码访问是主导因素

访问代码库相比记忆带来了显著的性能提升。仅代码 相对于 闭卷 的平均增益为 +0.23，是文档所提供增益的三倍。这证实了阅读代码对理解的贡献远大于单纯的先验知识。

2. 文档提供适度且可衡量的效用

对于文档依赖任务，访问文档带来了一致且具有统计显著性的改进（有文档 - 仅代码 = +0.071，p < 0.003）。这表明虽然代码结构允许代理推断大部分答案，但文档提供了关键细节（设计原理、边缘情况），从而提高了完整性和准确性。

3. 实验设计的验证

在代码可推导任务上，仅代码 和 有文档 条件之间的性能差距微乎其微（∆ ≈ +0.007），且对大多数模型而言统计上不显著。这验证了该方法论：该框架成功隔离了文档不必要的任务，证明了在文档依赖任务上观察到的收益是真实的效用，而非评估设置的人为产物。

4. 模型特定洞察

• 记忆： 模型在闭卷条件下的得分为 0.56–0.68，表明对知名库存在显著的预训练记忆。
• 推理与回忆： DeepSeek-V4-Pro 在仅代码和闭卷之间显示出最大差距（+0.450），表明其严重依赖主动代码探索而非参数化回忆。
• 类别分析： 与“为什么”类问题会显示出最大文档差距的假设相反，“在哪里”类问题（功能定位）在代码可推导任务上显示出最显著的差异，表明文档起到了导航索引的作用。

意义与主张

本文主张 Code-QA-Bench 通过以下方式推动了评估 AI 编程代理的方法论转变：

1. 分离理解与记忆： 它提供了一种量化方法，衡量代理在多大程度上依赖阅读代码，而非回忆训练数据或文档。
2. 环境级控制： 通过在仓库级别移除文档而非过滤问题，它迫使代理与代码结构互动，解决了现有基准测试中的“污染”问题。
3. 自动化与可复现： 该流程完全自动化、与仓库无关，且适用于任何文档完善的 Python 仓库，允许随着模型改进而持续更新基准测试。
4. 诊断价值： 三条件设计提供了生成型基准测试所缺失的诊断信号（例如具体性饱和、记忆水平），从而更细致地展现代理的能力。

作者得出结论，虽然前沿模型是强大的代码结构阅读者，但文档带来的适度但一致的收益突显了为 AI 代理提供文档完善的代码库的持续重要性。该框架是开源的，既可作为评估工具，也可作为经过验证的训练数据来源。