Agent4cs：面向大型层次化代码库的代码摘要多智能体系统

# Agent4cs：针对大型层次化代码库的多智能体代码摘要系统
来源：https://arxiv.org/html/2607.01425
###### 摘要

理解大型、复杂的代码库，尤其是那些结构混乱、文档不全的代码库，仍然是一项重大挑战。现有的代码摘要解决方案通常依赖单一语言模型或编码助手（如Claude Code），并将源代码视为纯文本，未能充分利用代码仓库中丰富的相互依赖关系和层次化信息。为解决这些不足，我们提出了Agent4cs —— 一个多智能体框架，以自底向上的方式总结大型代码库：摘要智能体专注于生成稳健的摘要；关键词提取智能体主动从子文件夹中提取关键信息；质量保证智能体迭代优化输出结果，提升可读性、连贯性和完整性。在7个前沿模型上进行评估，Agent4cs 相比两个结合代码片段的结构化提示基线，在所有文件夹层级上语义一致性平均提升8%。此外，在真实世界数据集上的广泛评估表明，相比相同基线，归一化关键词覆盖率最高提升38%。

多智能体系统，大型语言模型，智能体，代码摘要，软件工程，代码库

††版权：无††ccs：计算方法 多智能体系统††ccs：计算方法 协作与协调††ccs：计算方法 自然语言处理††ccs：软件及其工程 软件开发技术††ccs：软件及其工程 自动编程††ccs：软件及其工程 通用编程语言

## 1. 引言

随着软件项目的快速演进，文档往往变得不完整、过时或不一致。这种摩擦延缓了新手入职，增加了维护复杂性，并增加了缺陷和架构漂移的风险。为解决这些问题，大量研究工作致力于自动化代码摘要，例如识别类特征和提取功能关键词（Zhu and Pan,2019 (https://arxiv.org/html/2607.01425#bib.bib2)）。最近，深度学习方法通过利用神经模型学习代码结构与自然语言描述之间的复杂映射，进一步推动了该领域的发展（Zhang et al.,2022 (https://arxiv.org/html/2607.01425#bib.bib1); Shi et al.,2022 (https://arxiv.org/html/2607.01425#bib.bib18)）。大型语言模型（LLM）（Sun et al.,2025 (https://arxiv.org/html/2607.01425#bib.bib3); Zhang et al.,2024 (https://arxiv.org/html/2607.01425#bib.bib4)）的出现进一步缩小了代码与自然语言之间的语义鸿沟，为稳健的代码摘要提供了新途径。

尽管代码感知语言模型的进步显著提升了函数级摘要的效果（Sun et al.,2025 (https://arxiv.org/html/2607.01425#bib.bib3)），但实现全面的仓库级摘要仍然具有挑战性——跨文件依赖和层次化信息往往分散在多个目录中，因此未能充分利用。先前的努力表明，仅通过提示LLM不足以捕获仓库中所有子模块（Dhulshette et al.,2025 (https://arxiv.org/html/2607.01425#bib.bib33); Makharev and Ivanov,2025 (https://arxiv.org/html/2607.01425#bib.bib34); Elhashemy et al.,2025 (https://arxiv.org/html/2607.01425#bib.bib6)），而像Claude Code这样的交互式智能体是为按需查询式代码探索而设计的，并非以系统化方式生成持久文档（Tang and Runkler,2026 (https://arxiv.org/html/2607.01425#bib.bib5)）。对于通常远超30万token的工业级代码库，这一问题更加突出。因此，需要一种更结构化的解决方案。

参见图1。图1：Agent4cs 执行层次化仓库摘要的两个阶段：函数级摘要和层次化文件夹级摘要。

为弥补这一差距，我们提出了Agent4cs —— 一个智能体框架，其特点在于一个关键词提取智能体用于捕获子文件夹中的隐含信息，以及一个质量保证智能体提供迭代反馈以优化摘要，如图1所示。结合自底向上的层次化代码摘要方法，该框架加强了仓库内的跨文件夹连接，同时确保摘要质量和可读性，成为现有编码智能体的理想补充工具。本工作的主要贡献可概括如下：

- (i) 我们提出Agent4cs —— 一个轻量级的智能体框架，用于仓库级代码摘要。据我们所知，这是第一个针对层次化代码库摘要的多智能体方法。
- (ii) 通过遵循自底向上的摘要策略，我们有效利用了仓库内的层次化信息来增强跨文件夹连接，与两个包含片段级代码上下文的结构化提示基线相比，文件夹与子文件夹摘要之间的语义相似度平均提升8%。
- (iii) 我们通过集成跨越不同性能层级的七个前沿LLM，分析了Agent4cs的性能，研究了其在多样模型能力和计算预算下的有效性和鲁棒性。
- (iv) 我们在三个真实世界数据集及其混淆版本上验证了该方法，在某些LLM下，归一化关键词覆盖率相比代码片段增强基线提升约38%，同时保持了摘要长度。同时，在大多数评估的LLM上，我们提升了生成摘要的可读性。

## 2. 问题陈述

图2展示了一个大型Python仓库的代表性子集，展示了其多文件夹架构和底层源代码文件。为清晰起见，我们将代码摘要分为两个任务：针对单个代码文件的函数级摘要和针对仓库范围理解的层次化摘要（Zhang et al.,2022 (https://arxiv.org/html/2607.01425#bib.bib1); Zhu and Pan,2019 (https://arxiv.org/html/2607.01425#bib.bib2)）。

参见图2。图2：仓库概览：层次化文件夹结构（蓝色）与函数级代码文件（黄色）。仓库概览：层次化文件夹结构（蓝色）与函数级代码文件（黄色）。

### 2.1. 函数级代码摘要

图2中的代码文件（黄色）包含代码片段和函数。大多数已有数据集中的真实数据适用于这个问题范畴，提供了人工编写的函数-摘要对作为评估基准。然而，这种设置局限于局部代码解释。对于仓库级理解，这种面向函数的基准远远不够。

在我们的实验中，我们扩展了标准的整洁代码数据集，并包含了混淆代码以增加难度并模拟真实世界场景。代码混淆（Sebastian et al.,2016 (https://arxiv.org/html/2607.01425#bib.bib7); Viticchié et al.,2016 (https://arxiv.org/html/2607.01425#bib.bib8)）是一种有意为之的转换策略，它在保留源代码功能的同时隐藏其逻辑和结构，广泛应用于工业界以保护知识产权和防止恶意代码分析。常见的混淆技术包括结构修改、标识符重命名、结构修改以及控制流改变，所有这些都旨在使代码难以理解和分析。图3展示了一个混淆代码的示例，其中原始标识符（calculate_area, radius, pi, area）被替换为任意、无描述性的名称（a, b, c, d, e），这降低了语义清晰度并使代码更难以解释。

参见图3。图3：通过标识符重命名进行代码混淆的示例。通过标识符重命名进行代码混淆的示例。

在LLM出现之前，传统的摘要方法往往难以处理混淆代码，因为语义含义隐藏在层层语法转换之下。在混淆代码上评估LLM，可以深入了解模型的鲁棒性及其在混淆情况下提取底层功能的能力，这对于真实世界的代码理解场景具有重要价值。

### 2.2. 层次化代码摘要

大多数现有研究忽略了更高级别文件夹和子文件夹的摘要，因为从开源仓库收集的现有数据集在这一层级缺乏真实标注。然而，随着现代软件项目在复杂性和规模上不断增长，在文件夹和仓库级别理解代码对于有效的长期维护变得日益关键。因此，我们将层次化代码摘要视为更广泛代码摘要领域中的一个独特问题，并在本工作中提出新颖的解决方案和评估指标来应对这一挑战。

## 3. 相关工作

### 3.1. 用于代码摘要的神经模型

受神经机器翻译在自然语言处理中成功的启发（Bahdanau et al.,2015 (https://arxiv.org/html/2607.01425#bib.bib9); Cho et al.,2014 (https://arxiv.org/html/2607.01425#bib.bib10)），编码器-解码器架构很快被应用于代码摘要。早期的如CODE-NN训练了一个端到端的LSTM来为C#和SQL查询生成摘要（Iyer et al.,2016 (https://arxiv.org/html/2607.01425#bib.bib13)）。在这些序列神经模型的基础上，后续研究通过额外将抽象语法树（AST）与代码片段一起纳入深度强化学习框架，利用了结构化的代码信息（Wan et al.,2018 (https://arxiv.org/html/2607.01425#bib.bib16)）。这种结构感知能力随着基于图的神经架构而进一步发展，这种架构超越了扁平的AST表示，保留了AST树的层次性质（LeClaire et al.,2020 (https://arxiv.org/html/2607.01425#bib.bib15)）。一些后续研究将神经模型与检索技术相结合（Liu et al.,2021 (https://arxiv.org/html/2607.01425#bib.bib17); Zhang et al.,2020 (https://arxiv.org/html/2607.01425#bib.bib14)），通过利用训练语料中句法和语义相似的代码样本来增强编码器-解码器架构。

### 3.2. 用于代码摘要的语言模型

基于Transformer的语言模型的出现（Vaswani et al.,2017 (https://arxiv.org/html/2607.01425#bib.bib19)）标志着代码摘要的范式转变，从特定任务的神经架构转向在代码相关任务上微调预训练模型。这些基于注意力的模型在捕获长距离依赖关系方面表现出卓越性能，并在源代码摘要方面显著优于神经方法（Ahmad et al.,2020 (https://arxiv.org/html/2607.01425#bib.bib20)）。为探究这些模型是否真正理解代码语义或仅仅依赖表面层级的文本线索，研究人员修改了函数和变量名，发现这种变化对模型性能影响甚微（Mondal et al., 2023 (https://arxiv.org/html/2607.01425#bib.bib22)）。与此同时，对资源消耗的担忧推动了更紧凑替代方案的发展，例如将GPT-3.5的代码专业知识提炼到一个3.5亿参数的模型中（Su and McMillan,2024 (https://arxiv.org/html/2607.01425#bib.bib21)）。在这些基础之上，出现了几种创新方法。受遗传算法启发，EACS框架通过选择、交叉和变异操作改进候选摘要，持续提高了大型软件项目中代码文档的质量（Sun et al.,2024 (https://arxiv.org/html/2607.01425#bib.bib32)）。此外，ESALE将神经架构与Transformer相结合，采用两阶段方法——通过多任务学习预训练共享编码器，然后使用解码器进行特定任务的代码摘要微调（Fang et al.,2024 (https://arxiv.org/html/2607.01425#bib.bib23)）。

与语言建模的发展相一致，代码摘要的解决方案很快从微调演变为利用LLM进行高效的基于提示的推理。尽管早期对ChatGPT在代码摘要中的研究观察到其性能低于微调的语言模型（Sun et al.,2023b (https://arxiv.org/html/2607.01425#bib.bib24)），但近期采用更先进SOTA模型的研究表明，使用提示策略的LLM在大多数代码摘要和翻译基准上可以超越微调模型（Shin et al.,2025 (https://arxiv.org/html/2607.01425#bib.bib26); Sun et al.,2025 (https://arxiv.org/html/2607.01425#bib.bib3)）。为了理解当前LLM在代码摘要中有效性的驱动因素，研究人员还考察了代码与相应自然语言参考之间token重叠的影响，揭示LLM往往更依赖这些共享token，而非底层代码结构（Haldar and Hockenmaier,2024 (https://arxiv.org/html/2607.01425#bib.bib25)）。为增强LLM在代码理解及其他领域特定任务中的能力，带有演示示例的少样本提示被广泛使用（Gao et al.,2024 (https://arxiv.org/html/2607.01425#bib.bib28); Ahmed and Devanbu,2023 (https://arxiv.org/html/2607.01425#bib.bib27); Ahmed et al.,2024 (https://arxiv.org/html/2607.01425#bib.bib31); Tang et al.,2024 (https://arxiv.org/html/2607.01425#bib.bib30)），在仅使用几个演示示例的情况下，其性能可以超越用数千样本训练的微调模型。后续研究通过将数百个语义选择的少样本示例纳入软件工程领域，探索了该技术的上限（Tang et al.,2025 (https://arxiv.org/html/2607.01425#bib.bib29)）。

### 3.3. 层次化代码摘要

尽管基于LLM的技术已证明其在单个代码片段上的高效性，但总结具有复杂相互依赖关系的大型代码库的挑战促使研究人员开发能够捕获多层代码结构的方法。一种用于层次化仓库级代码摘要（HR-CS）的语法驱动方法（Dhulshette et al.,2025 (https://arxiv.org/html/2607.01425#bib.bib33)）采用本地LLM聚合代码片段级信息（如函数名、变量、输入和输出），然后生成全面的包级摘要，以提高相关性和覆盖率。另一项工作通过纳入类和仓库域上下文及少样本示例，将代码摘要扩展到函数之外（CS-BF）（Makharev and Ivanov,2025 (https://arxiv.org/html/2607.01425#bib.bib34)）。虽然这种仓库级摘要显示出前景，但它计算量大，且忽略了仓库内的中间文件夹层。相比之下，其他研究将摘要用作下游任务的中间步骤。例如，HCGS生成代码元素及其关系的摘要，以实现上下文感知的代码检索（Sounthiraraj et al.,2025 (https://arxiv.org/html/2607.01425#bib.bib35)），而另一种方法则利用LLM构建层次化项目摘要用于缺陷定位，通过自上而下的推理克服域不匹配和上下文限制（Oskooei et al.,2025 (https://arxiv.org/html/2607.01425#bib.bib36)）。