README.md 生成中智能体复杂度的幻象：单智能体与多智能体 RAG 系统的评估

📊 论文图表(共 5 张)

展开查看 5 张图

‹ ›

TL;DR

这篇论文针对 GitHub 仓库 README 生成任务，系统对比了单智能体流水线、专用多智能体系统以及引入开发者引导规划（DevPlan）的混合架构三种方案。研究发现单智能体在词法质量上与多智能体相当，但 token 消耗降低 86%、运行速度提升一倍；多智能体则在结构一致性上表现优异（98%）；而轻量级的开发者引导规划被证明是超越所有配置的关键——它能产生最高质量的整体文档，同时保持较低的资源开销。

研究背景与动机

大型语言模型正在深刻改变软件工程的自动化工作流，从代码补全到文档生成无所不包。在仓库级文档生成这一具体场景中，如何让模型准确理解代码库的结构和语义，并生成清晰、完整的 README 文件，一直是困扰研究者和工程师的难题。

为了解决这一问题，当前主流方案往往依赖[[多智能体系统]]——让多个智能体分别负责代码理解、信息检索、内容生成等不同子任务，通过协作完成任务。这种设计的直觉在于：复杂任务可以被分解为更简单的子任务，每个子任务由专门优化的智能体处理，最终结果应该优于单一智能体独立完成整个流程。

然而，这种直觉假设并未得到充分的实证检验。多智能体架构固然强大，但它引入的额外复杂性——更多的模型调用、更长的执行链路、更复杂的状态管理——在实际部署中会产生显著的资源开销。如果一个系统需要消耗两倍以上的 token 才能换来微乎其微的质量提升，那这种复杂性在生产环境中往往是不划算的。

本文的切入点正是这一被忽视的效率维度。作者认为，架构复杂性的增加是否真的带来了相应的性能提升，这是一个需要系统性评估的问题。他们选择 GitHub README 生成作为评估场景，这是软件工程中一个具有实际价值的任务，也是检验[[RAG]]架构设计合理性的理想试验场。

方法

研究团队设计了三套并行的评估体系，每套体系代表了一种不同的架构理念。

第一套是单智能体流水线。这个设计追求的是极简主义：单个智能体负责从代码库中检索相关信息，理解其结构和功能，然后直接生成 README 文档。没有任何任务分解，没有子智能体协作，一切都在一个统一的流程中完成。这种设计的优势在于执行链路短、调用次数少，但风险在于单一智能体需要同时承担信息理解、结构规划和内容生成等多重职责，一旦某个环节出错就可能影响整体质量。

第二套是专用多智能体系统。与单智能体不同，这套系统将生成流程拆分为多个专门的处理单元。代码分析智能体负责理解代码结构，信息检索智能体负责从代码库中提取相关内容，规划智能体负责组织文档的整体框架，最终的生成智能体负责输出最终文本。每个智能体各司其职，通过消息传递协调工作。这种设计符合「让专业的人做专业的事」的软件工程原则，但代价是更长的执行链路和更高的 token 消耗。

第三套是开发者引导规划（DevPlan）变体。这是论文提出的核心创新点。研究者发现，无论单智能体还是多智能体系统，都面临一个共同的瓶颈：自主规划能力有限——智能体在规划文档结构时往往缺乏对代码库整体架构的把握，容易出现遗漏或结构混乱。

DevPlan 的解决方案是引入一个轻量级的开发者引导层。具体做法是，在实际生成之前，先利用代码库的元信息（如目录结构、模块划分、关键文件位置等）生成一个粗粒度的文档大纲。这个大纲作为先验知识注入到后续的生成流程中，指导单智能体或多智能体的具体工作。这样一来，规划职责被部分转移给了系统化的代码分析，而智能体则专注于执行细节，从而缓解了自主规划不准确的问题。

实验与结果

实验设置以 LARCH——一个当前最先进的 README 生成基线系统——以及原始人工撰写的 README 作为参照基准。评估维度覆盖词法质量（词汇丰富度、准确性）、结构一致性（章节组织、格式规范）和整体文档质量三个层面。

关键数据揭示了一个重要的权衡关系。单智能体流水线在词法质量上与多智能体系统几乎持平，这意味着当评估重点落在遣词造句的准确性时，单智能体并没有明显的劣势。然而，两者在 token 消耗上的差距是惊人的：单智能体方案的 token 消耗仅为多智能体的 14%，节省了 86% 的资源。与此同时，单智能体的运行速度是多智能体的两倍，这对于需要快速响应的开发场景具有实际意义。

但多智能体系统并非一无是处。手工分类分析显示，多智能体在结构一致性上达到了 98% 的惊人水平，几乎完美地遵循了标准 README 的格式规范。相比之下，单智能体流水线在结构层面存在明显缺陷，格式混乱和章节缺失的情况时有发生。这说明任务分解虽然增加了资源开销，但它确实有效地解决了单智能体在结构规划上的短板。

最值得关注的是 DevPlan 的表现。引入轻量级开发者引导规划后，整体文档质量超越了所有被评估的配置方案。这表明，将领域知识以结构化大纲的形式注入生成流程，是一个高效且实用的策略。DevPlan 不需要引入完整的多智能体协作机制，只需要在生成前添加一个基于代码分析的规划步骤，就能在保持较低资源消耗的同时，显著提升输出质量。

讨论与可借鉴点

这项研究的价值在于揭示了[[智能体架构]]设计中一个常见的误区：复杂性并不总是等同于优越性。在追求更强大系统的过程中，研究者有时会忽视一个基本事实——每一个额外的组件都意味着额外的开销，只有当这种开销被证明能换来实质性提升时才是合理的。

本文的局限同样值得注意。首先，README 生成是一个相对受限的任务，其结论未必能直接推广到其他软件工程场景。其次，评估指标虽然涵盖了词法和结构两个维度，但对于文档的实用性、可读性等更主观的质量维度涉及有限。未来的工作可以探索 DevPlan 在其他文档类型（如 API 文档、技术博客）中的应用，以及如何自动化生成更高质量的开发者引导规划。

对于从业者而言，这项研究提供了一个清晰的设计原则：不要为了复杂而复杂。在考虑引入多智能体架构之前，不妨先评估单智能体方案能否满足需求，以及引入的任务分解是否真的解决了实际痛点。对于那些确实需要结构化输出的场景，轻量级的规划引导可能是一个性价比更高的选择——它不需要推翻现有的系统架构，只需要在关键节点注入领域知识，就能带来可观的收益。

摘要

大型语言模型（LLMs）正越来越多地被用于自动化多种软件工程任务，包括代码补全、代码摘要、测试以及仓库级文档的生成。尽管多智能体系统（MAS）常被用于支持此类任务，其前提假设是任务分解能够提升性能，但架构复杂度对实际效率的影响仍未得到充分考察。本研究对用于生成 GitHub 仓库 README 文件的、依赖检索增强生成（RAG）的架构进行了实证评估。在本工作中，我们系统性地比较了单智能体流水线、专用多智能体系统以及一种开发者引导规划（DevPlan）变体，并以当前最先进的基线 LARCH 以及原始的真实文档作为基准进行评测。结果表明存在一个关键的架构权衡：单智能体流水线在词法质量上与多智能体系统相当，同时将 token 消耗降低了 86%，且运行速度提升一倍。相比之下，手工分类分析显示多智能体系统实现了较高的结构一致性（98%），解决了在单智能体方法中观察到的格式问题。自主规划被识别为流水线的主要瓶颈；引入轻量级的开发者引导规划能够产生最高的整体文档质量，超越了所有被分析的方案。

Abstract

Large Language Models (LLMs) are increasingly utilized to automate several software engineering tasks, including code completion, code summarization, testing, and the generation of repository-level documentation. While Multi-Agent Systems (MAS) are often adopted to support such tasks under the premise that task decomposition improves performance, the impact of architectural complexity on practical efficiency remains under-examined. This study empirically evaluates Retrieval-Augmented Generation (RAG) dependent architectures for the generation of README files for GitHub repositories. In this work, we conducted a systematic comparison between a Single-Agent pipeline, a specialized MAS, and a developer-guided planning (DevPlan) variant, benchmarked against LARCH -- a state-of-the-art baseline -- and the original ground truth. Results indicate a critical architectural trade-off: the Single-Agent pipeline achieves lexical quality comparable to MAS while reducing token consumption by 86% and operating at twice the speed. In contrast, manual taxonomy analysis demonstrates that MAS achieves high structural consistency (98%), resolving formatting issues observed in single-agent approaches. Autonomous planning is identified as the primary pipeline bottleneck; incorporating lightweight developer-guided plans produces the highest overall documentation quality, surpassing all the analyzed configurations.