这项由上海交通大学彭维涵、石雨灵、王宇航、张欣云、沈备军和顾晓东（通讯作者）团队完成的开创性研究发表于2025年9月，论文编号为arXiv:2509.14635v1。有兴趣深入了解的读者可以通过该编号查询完整论文。

代码就像是程序员写的"小说"，每个函数和类就是其中的章节。传统的AI系统在理解代码时，就像只能读懂单独的段落，却无法理解整本小说的情节发展。上海交通大学的研究团队意识到了这个问题的严重性。当程序员在实际工作中遇到问题时，他们需要在成千上万行代码中找到相关信息，理解不同文件之间的关系，掌握整个软件架构。这就好比要理解一座复杂的城市，你不能只看单个建筑，而要了解街道如何连接、交通如何流动、各个区域如何协作。

现有的代码问答系统就像只能看懂单个房间的室内设计师，却无法理解整栋楼的建筑风格。这些系统在处理诸如CoSQA和CodeQA等基准测试时表现不错，但这些测试都聚焦于小的代码片段，完全忽略了真实软件开发中的复杂性。程序员实际工作时需要跨越多个文件进行推理，理解软件架构，在长距离的代码依赖关系中找到答案。

研究团队构建了一个名为SWE-QA的全新基准测试，包含576个高质量的问答对，涵盖了意图理解、跨文件推理和多跳依赖分析等多个维度。这就像是为AI系统设计了一套"城市规划师"的考试，不再只是考察能否看懂单个建筑图纸，而是要求它们理解整个城市的运作机制。

为了构建这个基准测试，研究团队首先从11个热门代码仓库中爬取了77100个GitHub问题。他们发现，开发者在实际工作中提出的问题具有明显的分类特征，于是构建了一个两层分类体系。第一层按照问题的主要类型分为"什么"（事实询问）、"为什么"（因果解释）、"在哪里"（位置识别）和"如何"（程序解释）四大类。第二层则进一步细化为12个具体的用户意图类别，比如依赖追踪、设计理念阐述、算法分析等。

这种分类体系的建立过程就像是图书馆管理员整理书籍。研究团队首先随机选取1000个问题进行人工分析，通过反复的开放编码过程识别出重复出现的模式和开发者意图。然后使用强大的语言模型GPT-5对剩余的126415个问题进行分类。结果显示，"如何"类问题占比最高，达到35.2%，主要关注实现细节；"在哪里"类问题紧随其后，占28.4%，表明开发者经常需要定位功能、数据流或特定标识符；"为什么"类问题占23.1%，探究设计理念和目的；"什么"类问题占剩余的13.3%，寻求定义或架构总结。

基于这个分类体系，研究团队为每个用户意图类别创建了抽象的种子模板。这些模板就像是问题生成的"配方"，比如"从<类>类继承的子类有哪些？"和"<模块>在<条件>情况下如何实现<功能>？"这些模板捕捉了重复出现问题的本质，为生成多样化、针对特定仓库的问题实例提供了蓝图。

问题实例化的过程就像是根据菜谱制作不同口味的菜肴。研究团队使用tree-sitter这个语言无关的解析工具来解析每个代码仓库的结构，生成一个类型化的核心元素及其关系图。这个图包括仓库、文件、代码片段、类、方法、属性、函数、参数和变量等节点，边则表示包含关系。每个函数还跟踪它调用的函数和调用它的函数，每个文件记录其导入内容，揭示文件间的依赖关系。

通过选择一个焦点元素周围的紧凑子图，并将其与第一阶段的种子模板结合，研究团队能够生成针对特定上下文的问题。子图提供了签名、定义、类成员关系、文件路径、导入和传入传出调用等信息，确保提供充足的上下文而不会让提示过于复杂。

答案收集阶段采用了检索增强生成的流程。研究团队首先为每个问题建立目标仓库代码元素的综合索引，包括函数、类及其相互依赖关系。使用这个索引，他们通过语义相似性匹配和结构依赖分析的组合来检索相关的代码片段、文档和架构元数据，确保为答案生成提供丰富相关的上下文。

在获得检索到的上下文后，研究团队利用强大的语言模型，在人类专家使用Cursor等工具的协助下，生成初步答案。这个过程由强调事实准确性、完整性和严格遵循提供上下文的提示指导。提示明确指示模型引用代码位置，避免引入检索材料中不存在的信息，从而最大限度地减少幻觉现象。

数据验证过程就像是出版社的编辑审核流程。所有初步的问答对都要经过严格的数据验证过程，由熟悉目标仓库的经验丰富的开发者进行。在LLM驱动工具如Cursor的协助下，审查员仔细验证每个声明的事实准确性，评估解释的完整性，并完善语言的清晰度和精确性。这种人在回路的方法允许进行细致的修正，确保每个答案不仅正确而且易于理解。

经过修订后，问答对还要经过最终的过滤步骤。如果问答对未能达到质量标准就会被丢弃，过滤标准包括但不限于模糊或表述不当的问题、修订后仍然事实错误或不完整的答案，或者无法充分基于仓库代码和文档的答案。研究团队还强制执行跨仓库的Level-1类别平衡，每个仓库产生正好48个最终配对。

最终的SWE-QA基准测试包含了来自12个多样化Python仓库的576个问题，这些仓库总共包含11335个文件、19544个类、128835个函数和超过300万行代码。为确保问题类型的平衡表示，研究团队选择了相等数量的"什么"、"为什么"、"在哪里"和"如何"问题，每个仓库贡献48个样本。

与现有的代码问答基准测试相比，SWE-QA具有根本性的突破。传统基准测试如CoSQA、CodeQA和CS1QA专门关注孤立的代码片段或教育环境，根本无法解决真正的仓库级代码模块理解问题。即使是支持多跳推理的CodeQueries，也只在孤立的Python函数内操作，没有跨文件依赖关系。最近的大规模努力如ProCQA和InfiBench从StackOverflow收集数据，但仍然局限于一般编程任务，没有针对仓库结构。

虽然CoReQA通过从GitHub问题和评论收集数据在仓库级别操作，但它强调问题解决而不是代码模块理解。关键是，这些现有基准测试都不要求模型将代码模块理解为仓库内相互连接的架构组件。SWE-QA填补了这个根本空白，专门针对真正的代码模块理解，要求模型理解模块如何相互作用和依赖、模块在更广泛代码库中的架构角色，以及模块之间的语义契约。

一、智能代理的诞生：让AI像程序员一样思考

为了验证这个基准测试的有效性，研究团队开发了一个名为SWE-QA-Agent的智能代理系统。这个代理就像是一个会编程的侦探，能够在复杂的代码仓库中进行系统性的搜索和推理。

传统的问答系统就像是只能查字典的学生，只能根据给定的信息片段回答问题。而SWE-QA-Agent更像是一个经验丰富的程序员，会主动地在代码库中寻找线索，分析不同文件之间的关系，逐步构建对整个系统的理解。

这个代理系统基于ReAct框架构建，将推理、行动和观察整合到一个迭代循环中。代理的认知过程由四个基本行动驱动。ReadFile行动让代理能够检查仓库内特定文件的内容，这是进行底层代码理解的主要机制，代理可以执行cat和grep等标准命令行工具，实现精确的内容检索和模式匹配。GetRepoStructure行动通过检索仓库文件和目录结构的层次表示来促进高层结构理解，通过执行tree命令为代理提供可在整个推理过程中参考的全局上下文地图。SearchContent行动利用检索增强生成流程，使用商业级代码嵌入模型voyage-code-3，将代理的搜索能力提升到超越简单关键词匹配的抽象概念层面。Finish行动标志着答案任务的完成，表明代理已经从收集的信息中综合出最终答案或达到预定义的最大迭代次数。

代理的工作流程就像是一个熟练的侦探破案过程。首先进行广泛的SearchContent行动来检索最相关的代码片段，建立初始上下文。然后代理进入探索和精化的循环，在每一步中分析当前上下文以形成思考，然后战略性地选择行动来获得高层结构概览或检查具体实现细节。每个行动的输出作为观察，逐步丰富代理的理解。这个迭代循环持续进行，直到代理确定已收集足够证据来构建综合答案，此时它调用Finish行动来综合并返回最终回应。

工作流程的关键原则是保持目标导向，缓解上下文过载并防止无目的探索以确保效率。代理被配置为每个问题最多进行5次推理-行动迭代，所有语言模型解码温度设置为0以避免随机性的影响。

二、六大模型同台竞技：谁能真正理解代码

研究团队选择了六个广泛认可的大型语言模型进行评估，包括Devstral-Small-1.1、Qwen2.5-Coder-32B-Instruct、Qwen2.5-72B-Instruct、DeepSeek-V3、GPT-4o和Claude 3.7 Sonnet。这些模型涵盖了专有模型和开源模型，包括通用目的和代码专门变体。此外，还包括两个商业编程工具Tongyi Lingma和Cursor作为系统级基准。

每个模型在四种不同设置下进行评估。Direct设置中，模型仅接收任务指令，没有从仓库检索的任何详细上下文，这个基准旨在评估模型关于目标仓库的内部知识。Function Chunking RAG方法基于语义边界对代码进行分区，将仓库解析为函数级块，避免将函数拆分为单元。Sliding Window RAG方法采用滑动窗口通过将长文件分割为重叠段来提取代码片段，这种策略有效捕获本地和跨文件上下文。SWE-QA-Agent是研究团队提出的基于ReAct范式的自主代理框架，执行迭代推理来检索相关代码和文档，生成上下文感知的回应同时保留中间推理轨迹。

评估采用了基于LLM的评价方法，使用GPT-5作为评判模型，从五个维度对答案质量进行评分：正确性衡量答案是否事实准确，完整性衡量答案是否完全解决问题，相关性衡量答案是否与问题相关，清晰度衡量答案是否结构良好且易于理解，推理质量衡量答案是否呈现连贯的推理过程。每个维度在预定义的5分量表上评分，为提高可靠性，LLM对每个实例的每个维度评估五次，通过多数投票确定最终的维度级分数，然后聚合为总体实例分数。

实验结果显示了明显的性能差异。直接查询语言模型而不提供仓库上下文的基准方法在所有模型上都产生最低分数，强调了基于上下文的必要性。滑动窗口RAG和函数分块RAG都通过提供相关代码片段大幅改善性能。基于代理的方法SWE-QA-Agent通过将检索与迭代推理相结合，在有能力的基础模型上提供最强的提升。对于较轻量级的模型，性能通常与标准RAG相当，反映出代理规划和工具使用引入的开销在基础模型能够可靠遵循计划时最有回报。

在所有模型中，Claude 3.7 Sonnet表现最佳，与SWE-QA-Agent结合时达到47.82的最高总分。这紧随商业工具Cursor的45.55分。有趣的是，尽管GPT-4o声誉良好，但与代理结合时得分39.54，不仅落后于Claude，还落后于DeepSeek V3的42.70分。这表明不同模型在软件工程任务上具有不同的能力水平，较新的模型如Claude 3.7 Sonnet可能为代码相关推理进行了更好的优化。

开源模型虽然总体上没有超越顶级专有模型，但显示出巨大潜力。DeepSeek V3与代理结合时看到第二大绝对改进（+8.32），其42.70的最终得分具有很强的竞争力。这强调了代理框架带来的重要价值，因为它可以大幅提升基础模型的能力。

商业编程工具表现出强劲性能。Cursor达到45.55的总分，成为评估中的第二佳表现者，仅略低于基于代理方法与Claude 3.7 Sonnet的47.82分。Tongyi Lingma也得到44.80的高分。这些工具是高度集成的系统，可能采用高级专有语言模型和复杂的上下文检索机制。它们令人印象深刻的结果作为基准，验证了为复杂仓库级问答构建集成工具增强系统的有效性。

三、人类专家的验证：真正的考官登场

虽然基于LLM的评价方法提供了可扩展的评估方法，但容易受到固有偏见的影响。为了补充自动化指标并获得对答案质量更可靠的评估，研究团队进行了人类评估。他们招募了三名专业软件工程师，每人都有四年以上的开发经验，且不是该论文的共同作者。研究团队随机选择了144个问题进行这项研究，从12个仓库的每个分类法类别中各抽取一个问题，构成基准测试的四分之一。

对于每个问题，参与者都会收到参考答案以及基于Claude 3.7 Sonnet模型的四种方法生成的答案：没有上下文的基础模型、函数分块RAG、滑动窗口RAG和提出的SWE-QA-Agent。为确保公平性，答案以随机顺序呈现，参与者不知道哪种方法生成了哪个答案。每位参与者被要求在与自动评估中使用的相同五个维度上，以10分制为144个答案评分。

人类评估的结果与基于LLM的评价结果高度一致。提出的基于代理的方法SWE-QA-Agent显著优于所有其他方法，达到45.51的最高总分。这证实了人类专家也发现代理生成的答案质量更优。研究团队观察到，与基础模型相比，SWE-QA-Agent在完整性（从4.82到8.85）和推理（从5.35到8.74）维度上有最大幅度的改进。这表明代理的迭代检索和推理过程在产生全面且逻辑合理的答案方面特别有效。虽然两种RAG方法都显示出比基准的显著改进，但仍然不及代理的性能，强调了简单检索对复杂仓库级问题的局限性。

四、问题类型大揭秘：AI的强项与弱点

为了理解性能如何在不同类型的仓库级问题上变化，研究团队使用最佳执行方法SWE-QA-Agent进行了分类法感知分析。结果显示高层概念性问题和底层实现导向查询之间存在差异。

模型在"为什么"问题上始终达到最高分数（平均43.10），特别是"设计理念"（44.40），在与"概念/定义"相关的"什么"问题上表现良好（44.22）。这表明当所需信息在自然语言中明确表达时模型表现出色，比如文档字符串、注释或架构说明。

需要深度程序性或位置性理解的问题性能较低。"在哪里"问题产生最低平均分数（37.55），其中"数据/控制流"为36.88分。要求实现解释的"如何"问题（38.15）也仍然具有挑战性。这些类别通常需要重建分散的逻辑，跨文件和超越内联文档的隐式控制路径，强调多跳代码追踪和依赖推理。

这种性能差异就像是让AI参加不同科目的考试。在"文科"类的问题上，AI可以很好地理解和总结已有的文档和注释，就像一个善于阅读理解的学生。但在"理科"类的问题上，需要进行复杂的逻辑推理和多步骤分析时，AI就显得力不从心了，就像需要解复杂数学题时一样困难。

五、代码仓库大比拼：哪些项目最难搞定

为了评估模型的泛化能力，研究团队分析了它们在SWE-QA中12个不同仓库上的性能，再次使用SWE-QA-Agent方法。结果表明，虽然性能总体一致，但可能受到每个仓库具体特征的显著影响。

平均而言，大多数仓库呈现类似的难度水平，得分聚集在40分左右。例如，django（41.90）、matplotlib（41.08）和sphinx（40.68）显示可比较的结果。然而，研究团队观察到明显的异常值。requests仓库平均看起来更容易（43.72）。相反，pytest（36.76）和sqlfluff（36.72）更具挑战性。这种差异与代码库大小、架构复杂性、插件或钩子系统、API表面清晰度和增加推理深度的非常规模式等因素一致。

某些模型对仓库特定功能比其他模型更敏感。例如，Qwen2.5-Coder-32B模型在特定仓库上显示出明显的敏感性（pytest上12.78分，sqlfluff上17.06分），而在其他仓库如requests（41.30）上表现出色，表明在特定风格下的脆弱性。相比之下，顶级执行模型如Claude 3.7 Sonnet在所有仓库上保持高分（46.32-49.16），展示出对不同代码库风格和复杂性的更强稳健性。

这种差异就像是让同一个翻译在处理不同语言时的表现。有些翻译可能精通浪漫语言系列，但在处理亚洲语言时就会遇到困难。同样，某些AI模型可能在处理传统架构的代码时表现良好，但遇到使用插件系统或复杂钩子机制的项目时就会力不从心。

六、真实案例分析：看AI如何破解复杂问题

为了展示答案质量的实际差异，研究团队研究了一个来自sqlfluff的复杂问题："SQLFluff如何实现其用于自定义规则的插件系统？"

基准滑动窗口RAG仅检索到关于get_rules()的片段，产生一个错过核心机制的通用答案。该方法只能获得关于get_rules()函数的有限信息，导致答案缺乏关键细节，无法解释插件系统的真实架构。

相比之下，SWE-QA-Agent代理发现了pluggy库的使用，并检索了更深层的上下文，包括PluginSpec和注册流程，使模型能够解释实际的架构。代理通过假设驱动的多步搜索完成这一点。从get_rules()开始，它推断出一个hookspec接口并找到带有抽象方法的PluginSpec。然后它定位插件管理器初始化和hookspec注册，最后验证第三方规则的分发入口点发现。这些相互印证的片段共同支撑最终答案，涵盖规范/钩子、加载/协调和外部注册，产生简洁的机制级解释，更加完整、精确和可验证。

这个案例就像是两个侦探在调查同一个案件。普通的RAG方法就像是只在案发现场找到一个线索就匆忙下结论的新手侦探，而SWE-QA-Agent则像是经验丰富的老侦探，会系统地收集多方面的证据，分析它们之间的关联，最终得出完整准确的结论。

七、实验设计的周密考虑：确保结果可信

研究团队在实验设计上投入了大量心思，确保结果的可信度。他们意识到数据污染是一个主要威胁，即语言模型可能在预训练期间遇到过基准测试数据，这可能夸大性能指标并影响公平评估。为了解决这个问题，他们采用了系统验证方法，比较模型在直接回答（不检索）和基于RAG方法之间的性能。

分析显示这些方法之间存在实质性的性能差距，基于RAG的方法始终优于直接回答基准。这个显著差距表明数据污染的影响最小，因为被污染的样本在两种条件下都会表现出类似的性能。

研究团队还考虑到外部有效性的威胁。评估基于来自12个热门Python仓库的问题，虽然覆盖了各种类型和意图，但可能无法完全代表不同领域和复杂性级别的真实用户查询的多样性。为了缓解这种威胁，他们仔细选择跨越不同领域的仓库，并确保问题分类法覆盖多样的查询类型和复杂性级别。

基准测试专门关注Python仓库，这可能限制发现对其他编程语言的一般化程度。然而，提出的方法是语言无关的，不依赖Python特定功能，建议对其他编程语言具有强烈的可转移性。核心检索和推理机制应该在不同编程范式中保持有效。

人类评估虽然由三名经验丰富的软件工程师进行，但可能在质量评估中引入主观偏见。为了最小化这种威胁，研究团队提供了详细的评估指南，进行了注释者间一致性分析，并使用多数投票进行最终判断。

八、相关研究的深度对比：站在巨人的肩膀上

代码问答领域已经看到了显著的进步，专门方法利用语言模型和预训练技术来处理源代码查询。CodeMaster采用基于预训练的方法，通过任务适应自动回答代码问题，使用语法和语义分析将代码注释转换为问答对。CIQA引入了一个编码启发的问答模型，学习表示和利用来自GitHub等代码仓库的外部API，为编程任务引入了QA文本到代码算法。

其他方法包括将自然语言查询与代码片段匹配的基于检索的方法，以及针对特定领域问答的微调变压器。然而，这些方法主要关注片段级理解，缺乏处理复杂仓库范围推理的能力。与这些在孤立代码元素上操作的方法相比，当前工作通过引入仓库级上下文感知和多跳推理能力来解决现有代码问答系统的根本局限性。

现有的代码问答基准测试根本无法解决真正的仓库级代码模块理解。大多数现有工作在更有限的范围内操作，片段级基准测试如CodeQueries和CodeQA专门关注孤立的代码片段或单个方法。CodeQA故意采用完整的Python函数作为答案来确保功能独立性，而CoSQA针对函数级代码搜索，其中每个查询映射到单个Python函数，明确避免跨文件依赖。CS1QA关注入门编程教育和基于课程的示例，而不是生产软件架构。

最近的仓库级基准测试从GitHub问题讨论收集数据，而不是直接建模代码模块关系。CodeRepoQA关注预测问题中的回应，但不评估对实际代码模块、文件结构或模块间依赖的理解。CoReQA从176个仓库的GitHub问题和评论中收集问答对，强调问题解决而不是代码理解。Spyder-CodeQA仅从单个IDE仓库提供325个问答对，而InfiBench和ProCQA关注一般编程任务或基于StackOverflow的代码搜索，而不针对仓库结构。

关键是，这些基准测试都不要求模型将代码模块理解为仓库内相互连接的架构组件。关于模块接口、跨模块数据流、架构模式或不同代码模块之间语义关系的问题仍然未得到解决。为了解决这个根本差距，研究团队提出了SWE-QA，这是一个仓库级代码问答基准测试，专门针对真正的代码模块理解。

仓库级代码理解已经成为现代软件工程工具的关键能力，现有方法主要关注代码生成、翻译和问题解决。传统方法使用检索增强方法从仓库收集相关代码上下文，而更复杂的系统如RepoUnderstander引导代理进行系统导航和分析以实现综合仓库理解。RepoFusion通过训练代码模型来整合仓库上下文以增强单行完成和仓库特定理解来推进这种范式。基于图的方法表示代码结构来捕获跨文件关系，而基于代理的系统利用工具使用和导航来利用仓库感知编码协助的LLM推理能力。

然而，现有的仓库理解方法主要针对代码生成和完成任务，对综合问答能力的关注有限。虽然这些方法在上下文检索和代码合成方面表现出熟练程度，但它们缺乏评估多跳推理、架构理解和跨文件依赖分析的系统评估框架，这些特征是复杂仓库级问题的特征。相比之下，当前的SWE-QA-Agent采用专门为仓库级问答设计的基于ReAct的代理框架，利用迭代推理、检索和结构化导航的工具，实现跨代码库的精确多跳推理。

说到底，这项研究就像是为AI系统设计了一套全新的"驾照考试"。以前的考试只要求AI能够识别单个交通标志，而现在的考试要求它们能够在复杂的城市道路网络中规划路线，理解交通流量，掌握整个交通系统的运作规律。SWE-QA基准测试和SWE-QA-Agent代理系统的组合，为评估和提升AI系统在真实软件开发环境中的能力提供了全新的工具。

这项研究的意义远不止于学术层面。随着软件系统变得越来越复杂，开发者需要更智能的工具来帮助他们理解和维护代码。SWE-QA-Agent这样的系统有望成为程序员的得力助手，能够快速回答关于复杂代码库的问题，帮助新开发者更快地熟悉项目，协助经验丰富的程序员解决棘手的技术问题。

虽然目前的结果显示了巨大的进步，但也揭示了仍存在的挑战。AI系统在处理需要深度推理和多步骤分析的问题时还有很大改进空间，特别是在定位功能和追踪复杂依赖关系方面。未来的研究方向包括扩展到更多编程语言、整合动态仓库更新，以及进一步提升多跳推理能力。

研究团队承诺将继续改进和扩展这个基准测试，定期添加新的仓库以防止数据污染，并探索更多创新的代理设计。他们的工作为整个AI和软件工程社区提供了宝贵的资源，推动了这个重要研究方向的发展。有兴趣的研究者和开发者可以通过GitHub仓库获取完整的代码和数据，为这个开放的研究生态系统做出贡献。

Q&A

Q1：SWE-QA基准测试是什么？它有什么特殊之处？

A：SWE-QA是上海交通大学团队开发的仓库级代码问答基准测试，包含576个高质量问答对，涵盖12个Python项目。与传统只能处理代码片段的测试不同，它要求AI理解整个代码库的架构、跨文件依赖和复杂的代码关系，就像要求AI从理解单个房间升级到理解整栋建筑的设计理念。

Q2：SWE-QA-Agent代理系统是如何工作的？

A：SWE-QA-Agent就像一个会编程的智能侦探，它有四种基本技能：读取文件内容、获取仓库结构、搜索相关内容和完成任务。它会像经验丰富的程序员一样，在代码库中主动寻找线索，分析不同文件间的关系，通过多轮推理逐步构建对整个系统的理解，而不是简单地查找现成答案。

Q3：哪些AI模型在SWE-QA测试中表现最好？

A：Claude 3.7 Sonnet结合SWE-QA-Agent表现最佳，得分47.82分，显示出在复杂代码推理方面的优势。商业工具Cursor紧随其后得分45.55分。有趣的是，开源模型DeepSeek V3表现也很出色，得分42.70分，显示出开源模型的巨大潜力。研究发现AI在回答概念性问题时表现更好，但在需要深度推理的定位和实现问题上仍有困难。