一句话总结

微软亚洲研究院、加州大学圣地亚哥分校与清华大学的研究人员提出了 RPG-Encoder，这是一种统一框架，将仓库规划图（RPG）转化为双向、高保真表示，弥合代码理解与生成之间的鸿沟——在 SWE-bench 上实现 93.7% 的 Acc@5，在 RepoCraft 上实现 98.5% 的重建覆盖率，同时通过融合语义意图与依赖拓扑结构，将维护成本降低 95.7%。

主要贡献

• 我们将仓库推理重新定义为理解与生成之间的双向循环，引入 RPG 作为统一表示，融合语义意图与结构依赖，以弥合现有碎片化方法中的推理差距。
• RPG-Encoder 实现语义提升，将代码编码为 RPG 节点与边，并使用基于增量差异的更新机制，将维护开销降低 95.7%，支持可扩展、无漂移的演化，与代码变更保持同步。
• 在 SWE-bench Verified（93.7% Acc@5）和 RepoCraft（98.5% 重建覆盖率）上评估，RPG-Encoder 在理解方面优于基线方法超过 10%，在重建方面优于 24.3%，证明其高保真、结构感知的实用性适用于复杂代码库。

引言

作者利用最初为代码生成设计的仓库规划图（RPG），构建了 RPG-Encoder——一种统一表示，将仓库理解与生成作为互逆的双向过程连接起来。先前的方法存在表示碎片化的问题：API 文档缺乏结构上下文，而依赖图缺失语义意图，迫使代理手动推断连接或理由——两者均因漂移或静态更新而产生高维护成本。RPG-Encoder 通过将代码编码为语义丰富、拓扑感知的 RPG 来解决此问题；通过提交差异进行增量演化，将维护开销降低 95.7%；并作为结构感知导航的统一接口。它在 SWE-bench 任务上取得最先进的结果，在 RepoCraft 上实现 98.5% 的重建覆盖率，证明 RPG 的保真度，并闭合意图与实现之间的闭环。

数据集

• 作者选用六个真实世界的 Python 仓库，基于其流行度与结构复杂性，构建 RepoCraft 基准，用于评估自动化仓库重建。
• 他们通过使用 Sphinx 编译每个仓库的 docs/ 目录中的源文件，将 reStructuredText 或 Markdown 转换为统一文本格式，捕获类、函数与模块定义，构建文档数据集。
• 编译后的文档作为基线代理的真值规范，模拟人类开发者查阅的参考材料。
• 在六个仓库中，文档涵盖 7,320 个文件和超过 250 万 token，为测试长上下文理解提供了充分的上下文。
• 未描述训练划分、混合比例或裁剪策略；数据集直接用于评估，元数据直接从编译后的文档节点（包括函数签名和参数描述）中提取。

方法

作者利用 RPG-Encoder 将原始代码库转换为结构化、语义锚定的仓库规划图（RPG），作为代理式代码理解的统一推理基底。架构分为三个核心阶段：编码、演化与操作，每个阶段解决代码库表示生命周期的不同阶段。

如下图所示，RPG-Encoder 通过合成融合语义层级与执行依赖的双视图图，弥合冗长、实现密集的代码与高层功能意图之间的差距。这使代理不仅将仓库视为文件集合，而是视为一个连贯、可导航的系统。

编码阶段始于语义提升，系统解析整个代码库，提取每个函数与类的原子语义特征。这些特征以简洁、与实现无关的动宾短语表达（如“存储基础认证凭据”、“发送 GET 请求”），捕捉行为意图而非内部逻辑。此步骤在仓库全局执行，确保粒度一致，避免局部偏差。提取的特征随后聚合为文件级摘要，建立连接文件与其组成函数的功能边。

接下来，功能抽象将这些低级特征重组为层级结构，通过识别潜在功能中心点（如“数据处理”、“模型训练”）作为高层节点。这通过 LLM 指导的聚类实现：模型分析所有文件级节点的语义特征以诱导抽象类别，然后递归地将每个节点分配给最语义兼容的父节点。为确保结构稳定性，当直接父子关系缺乏足够粒度时，插入中间节点。

工件锚定将此抽象层级与物理代码工件绑定。对于每个高层节点，系统通过聚合所有后代叶节点的路径并应用基于 Trie 的分支分析，提取有意义、非冗余的目录最近公共祖先（LCA），计算其最小目录范围。这确保抽象功能概念（如“数据预处理”）与具体路径（如“sklearn/preprocessing”）绑定。最后，通过 AST 分析注入依赖边，映射导入、调用与继承关系，完成 RPG。

演化阶段根据代码库变更增量维护 RPG。对于每次提交，系统解析差异以识别受影响实体，并应用三种原子操作之一：删除、修改或添加。删除触发空父节点的递归剪枝，以保持结构整洁。修改评估语义漂移；如果功能意图超出阈值，节点通过删除和重新插入重路由至新领域。添加通过自上而下的语义路由插入，LLM 根据特征对齐选择最合适的父节点，确保层级保持语义连贯。

操作阶段通过三个核心工具将 RPG 作为统一推理基底暴露。SearchNode 通过匹配行为短语与语义特征或执行基于关键词的代码片段搜索，支持意图驱动的发现。FetchNode 为已验证实体检索精确的源上下文与元数据，确保代理基于真值代码推理。ExploreRPG 支持沿依赖或功能边的拓扑遍历，允许代理发现调用链、上游依赖或语义相关模块。这些工具共同实现多维导航，整合功能意图与物理实现。

RPG 的双视图结构——按功能与依赖边划分但共享统一节点集——允许检索期间无缝切换上下文。此设计通过作为知识源（存储语义特征与元数据）和过程编码器（通过边诱导拓扑顺序），减少信息过载，暴露架构理解所必需的因果关系与层级。

实验

• RPG 通过增强文件与函数定位显著提升仓库理解能力，通过结合语义与拓扑引导超越基线，过滤噪声同时确保全面覆盖。
• RPG 作为仓库重建的完整表示基底，实现近乎无损的结构与功能恢复，代码量与模块化与人工编写的项目高度匹配。
• 语义特征与拓扑依赖相互强化：移除任一均导致性能下降，确认两者对精确定位与结构保真度均至关重要。
• RPG 通过减少冗余探索并集中推理于相关代码，实现高效、低成本导航，在单位成本下获得比基线更高的准确率。
• 增量 RPG 更新以最小计算开销保持高保真度，使长期仓库演化可持续而不牺牲性能。
• RPG 诱导结构化代理行为，促进“先搜索后聚焦”模式，利用拓扑获取全局上下文后再深入实现细节，减少搜索与范围相关失败。
• 消融实验确认层级约束至关重要：移除文件或函数元数据导致结构崩溃，合并模块或失去粒度，凸显 RPG 在保留架构意图中的作用。

作者使用 RPG 增强仓库理解与重建，在多个基准和模型中展示定位精度与结构保真度的一致提升。结果表明，整合语义特征与拓扑约束使代理能够精确将高层意图映射到实现单元，同时减少冗余探索。消融研究确认语义锚定与结构连通性相互强化，其结合使用优于基于文本或部分图的基线。

RPG-Encoder 在仓库理解任务中显著提升成本效率，在 GPT-4.1 和 GPT-5 上均以每美元更高的准确率超越所有基线。它在保持卓越性能的同时减少推理步骤数量与货币成本，证明结构化导航实现更聚焦、更经济的代码库探索。

作者使用消融实验隔离层级结构对仓库重建的影响，表明移除文件或函数元数据导致代码组织显著变化。无文件级边界时，模型将特征合并为更少、更密集的文件；无函数元数据时，它们生成更多类与函数以补偿失去的过程引导。这些发现确认显式拓扑信号在重建过程中保留模块性与结构保真度至关重要。

作者使用 RPG 通过整合语义与拓扑信号增强仓库理解，提升多个模型在文件级与函数级的定位精度。结果表明，RPG 引导的代理在精度与召回率上持续优于基线，尤其在函数级，结构约束有助于将高层意图映射到特定代码单元。消融研究确认语义特征与依赖图均至关重要，移除任一均导致性能下降与推理成本增加。

RPG-Encoder 在多个 LLM 上持续实现更高成本效益，通过减少每任务的推理步骤数与货币成本，证明结构化导航比基线方法更高效。尽管某些基线（如 LocAgent）在较弱模型上成本较低，RPG-Encoder 在更强模型（如 GPT-4.1 和 GPT-5）上保持卓越效率，平衡精度与最小资源消耗。这种效率源于 RPG 能够早期引导代理定位相关代码区域，最小化冗余工具调用与上下文消耗。