在数字时代，软件开发如同交响乐团的演出，每一行代码都是音符，相互依赖，共同奏响程序的乐章。然而，当需要对整个代码仓库进行大规模修改时，开发者常常陷入一场复杂而繁琐的「乐谱重写」。这正是《CodePlan: Repository-level Coding using LLMs and Planning》这篇论文试图解决的难题。CodePlan 是一个创新框架，结合了大型语言模型（LLMs）和智能规划算法，像一位经验丰富的指挥家，协调整个代码仓库的修改过程，确保每处改动都精准无误。本文将带你走进 CodePlan 的世界，探索它如何用人工智能的力量，重新定义软件工程的未来。
🧠 从单行代码到整个仓库：软件工程的「外循环」挑战
想象一下，你正在维护一个庞大的代码仓库，里面有成千上万行代码，分布在数百个文件中。突然，一个外部库的 API 升级了，所有调用这个库的地方都需要修改。你可能会先改一个函数，但这个改动却导致另一个文件的调用出错，引发连锁反应。这种「牵一发而动全身」的场景，在软件工程中被称为「仓库级编码任务」（repository-level coding tasks）。它包括包迁移、修复静态分析错误、添加类型注解等，涉及整个代码仓库的广泛修改。
传统工具如 GitHub Copilot 擅长处理「内循环」任务，比如补全一行代码或修改一个函数体。然而，仓库级任务的复杂性远超它们的应对能力。代码之间的依赖关系如同蜘蛛网，牵扯众多文件，而仓库的规模往往让直接输入到语言模型的提示（prompt）变得不切实际。CodePlan 的出现，正是为了应对这一挑战。它将仓库级编码任务转化为一个规划问题，通过多步骤的编辑链（chain of edits），让语言模型在全局依赖的指引下，逐步完成修改。
🎼 CodePlan 的核心：像指挥家一样协调代码修改
CodePlan 的设计灵感来源于自动化规划（automated planning），一种常用于机器人导航或定理证明的 AI 技术。它的核心思想是将复杂的任务分解为多个小步骤，每一步都明确目标和依赖关系。CodePlan 的工作流程可以比喻为一位指挥家在排练交响乐：先确定乐谱（任务指令），然后根据乐器的相互依赖（代码依赖），逐一调整每个声部的演奏（代码编辑），最终确保整首曲子和谐无瑕。
具体来说，CodePlan 的输入包括：
- 代码仓库：整个项目的源代码，包含所有文件和依赖关系。
- 种子编辑规格（Seed Specifications）：任务的起点，比如 API 变更的说明或初始代码修改。
- 正确性预言机（Oracle）：一个验证工具，比如 C# 的构建系统或 Python 的静态类型检查器 Pyright，用于判断修改后的仓库是否有效。
- 大型语言模型（LLM）：如 GPT-4，负责执行具体的代码编辑。
CodePlan 的输出是一个经过多步编辑的代码仓库，确保通过预言机的验证。它的核心算法包括三个关键组件：增量依赖分析（incremental dependency analysis）、变更影响分析（change may-impact analysis）和自适应规划（adaptive planning）。这些组件共同构成了 CodePlan 的「指挥棒」，引导语言模型完成复杂的修改任务。
🔍 增量依赖分析：绘制代码的「关系网」
要理解代码之间的依赖关系，CodePlan 首先需要一张「关系网」。这张网由依赖图（dependency graph）构成，节点是代码块（比如方法、类、字段声明），边则是它们之间的关系，例如调用（caller-callee）、继承（base-derived class）或字段使用（uses-used by）。图 4 在论文中展示了这种依赖图的结构，包含了多种关系，如图所示：
| 关系类型 | 描述 |
|---|---|
| ParentOf/ChildOf | 代码块与其语法上包含的块之间的关系 |
| Calls/CalledBy | 方法调用关系 |
| BaseClassOf/DerivedClassOf | 类继承关系 |
| Uses/UsedBy | 字段使用关系 |
依赖图的构建依赖于静态分析技术。对于 C#，CodePlan 使用 tree-sitter 库生成抽象语法树（AST），通过分析 AST 节点识别关系。对于 Python，它借助 Jedi 工具发现符号引用和声明。这种分析是增量的，每次代码修改后，只更新受影响的部分，类似于在交响乐中只调整某个声部的音调，而不必重新排练整首曲子。
例如，假设一个方法 func 的签名发生了变化，CodePlan 会通过依赖图找到所有调用 func 的地方，并标记它们为可能需要修改的代码块。这种增量分析确保了效率和准确性，避免了全量重新分析的开销。
⚡ 变更影响分析：捕捉代码修改的「涟漪效应」
代码修改就像往湖面扔一块石头，会引发一圈圈涟漪。CodePlan 的变更影响分析（change may-impact analysis）正是用来捕捉这些涟漪的工具。它通过分析代码变更的类型，判断哪些其他代码块可能受到影响。论文中的表 1 列出了各种变更类型及其影响范围，例如：
| 变更类型 | 影响范围 |
|---|---|
| 修改方法签名 | 所有调用该方法的代码块、继承相关的方法 |
| 修改类字段 | 使用该字段的语句、类的构造函数、子类/父类 |
| 添加新方法 | 调用该方法的代码块（如果覆盖了基类方法） |
以论文中的例子（图 3）为例，假设一个复杂数库的 API 发生了变化，从返回 tuple<float, float> 改为返回 Complex 对象。CodePlan 首先修改调用该 API 的方法 func，但这一改动改变了 func 的返回类型，进而影响了调用 func 的方法 process。变更影响分析通过依赖图识别出这种「涟漪效应」，并生成新的编辑任务，确保 process 也得到相应更新。
这种分析的独特之处在于，它不仅能捕捉显而易见的错误（如编译失败），还能发现微妙的行为变化。比如，修改一个方法的返回值从 True 到 False，可能不会引发编译错误，但会影响调用者的逻辑。CodePlan 的分析能够主动识别这些潜在问题，超越了传统构建工具的局限。
🛠 自适应规划：动态调整「乐谱」
CodePlan 的自适应规划算法是整个框架的「大脑」。它维护一个计划图（plan graph），记录所有需要执行的编辑任务。每个节点是一个编辑义务（edit obligation），包含代码块、编辑指令和状态（待处理或已完成）。边则表示编辑之间的因果关系，比如一个方法的修改导致另一个方法的更新。
自适应规划的过程可以分为五个步骤：
- 提取代码片段：从仓库中提取需要编辑的代码块，保留其所属类的结构信息，以提供足够的上下文。
- 收集上下文：包括空间上下文（spatial context，如相关的方法定义）和时间上下文（temporal context，如之前的编辑记录）。
- 构建提示：将代码片段、编辑指令和上下文组合成一个提示，交给语言模型处理。
- 合并代码：将语言模型生成的代码合并回仓库，并更新依赖图。
- 扩展计划：根据变更影响分析，识别新的编辑义务，动态扩展计划图。
这个过程是动态的，就像指挥家在演出中根据乐手的表现调整节奏。如果预言机发现错误（如编译失败），CodePlan 会将错误信息作为新的种子编辑，进入下一轮规划。这种自适应能力确保了 CodePlan 能够应对复杂的依赖关系和不可预测的语言模型输出。
📊 实验验证：CodePlan 的实战表现
为了验证 CodePlan 的效果，研究团队在多种代码仓库上进行了实验，涵盖了 C# 的包迁移任务和 Python 的时间编辑任务。实验数据集包括两个内部专有仓库（Int-1 和 Int-2）和四个公开 GitHub 仓库（Ext-1、T-1、T-2、T-3），规模从 4 个文件到 168 个文件不等。以下是数据集的统计信息（改编自论文表 2）：
| 仓库 | 任务类型 | 文件数 | 代码行数 | 修改文件数 | 种子编辑数 | 衍生编辑数 | 差异行数 |
|---|---|---|---|---|---|---|---|
| Int-1 | C# 迁移 | 91 | 8853 | 47 | 41 | 110 | 1744 |
| Int-2 | C# 迁移 | 168 | 16476 | 97 | 63 | 375 | 4902 |
| Ext-1 | C# 迁移 | 55 | 8868 | 21 | 42 | 16 | 1024 |
| T-1 | Python 时间编辑 | 21 | 3883 | 2 | 2 | 0 | 104 |
| T-2 | Python 时间编辑 | 137 | 20413 | 2 | 1 | 8 | 15 |
| T-3 | Python 时间编辑 | 4 | 1874 | 3 | 1 | 10 | 39 |
实验对比了 CodePlan 与两种基线方法：
- Build-Repair（C#）：基于构建系统错误逐一修复。
- Pyright-Repair（Python）：基于 Pyright 静态检查器修复错误。
结果显示，CodePlan 在 5/6 个仓库中通过了预言机验证（即构建无错误或类型检查通过），而基线方法在所有仓库中均未能通过。这种优越性归功于 CodePlan 的规划能力，它能主动识别和传播衍生编辑，而基线方法仅能被动响应显式错误。
例如，在 T-2 仓库中，种子编辑为一个方法添加了一个默认参数（图 6）。Pyright 没有报告错误，因为默认参数不会破坏类型安全。然而，开发者在真实场景中更新了调用点以显式传递参数。CodePlan 通过变更影响分析识别出这些调用点，成功完成了编辑，而 Pyright-Repair 完全忽略了这些潜在需求。
🌍 上下文的重要性：时间与空间的协奏曲
CodePlan 的成功离不开对时间上下文和空间上下文的充分利用。时间上下文记录了之前的编辑历史，帮助语言模型理解当前编辑的因果关系；空间上下文则提供了代码块之间的关系，比如调用链或类层次结构。论文通过消融实验（ablation study）验证了这些上下文的重要性。
在 Int-1 仓库的实验中，去除时间和空间上下文后，CodePlan 的表现显著下降（表 4）：
| 方法 | 匹配块 | 缺失块 | 多余块 | DiffBLEU | Levenshtein 距离 | 预言机结果 |
|---|---|---|---|---|---|---|
| CodePlan（带上下文） | 151 | 0 | 0 | 1.00 | 0 | 通过 |
| CodePlan（无上下文，迭代1） | 112 | 39 | 4 | 0.73 | 3674 | 未通过 |
| CodePlan（无上下文，迭代3） | 121 | 30 | 54 | 0.51 | 4524 | 未通过 |
没有时间上下文，语言模型无法理解编辑的因果关系，例如无法知道基类方法需要因派生类方法的变化而更新（图 8）。没有空间上下文，模型可能会误以为某些代码元素不存在，生成多余的代码块（图 10）。这些实验证明，上下文是 CodePlan 精准编辑的关键。
🚀 CodePlan 的独特优势：从微观到宏观的掌控
CodePlan 的成功不仅仅在于技术细节，更在于它对仓库级编码任务的整体掌控。以下是它的几个关键优势：
- 战略规划：CodePlan 像一位棋手，提前规划每一步棋，确保每处修改都服务于全局目标。相比之下，基线方法如同「头痛医头」，只关注局部错误。
- 增量分析：通过动态更新依赖图，CodePlan 保持了对代码关系的实时掌控，避免了传统静态分析的低效。
- 微妙行为变化的捕捉：CodePlan 能识别不引发编译错误但影响逻辑的修改，比如返回值变化，这让它在功能正确性上更胜一筹。
- 轻量级部署：相比需要复杂构建环境的基线方法，CodePlan 的静态分析轻量且易于集成，适合大规模项目。
- 因果关系的维护：CodePlan 能追踪变更的因果链，避免了基线方法中常见的「治标不治本」问题。
这些优势在 Ext-1 仓库的迁移任务中得到了充分体现（图 11）。CodePlan 成功将 Console.WriteLine 迁移到 ITestOutputHelper.WriteLine，不仅完成了直接替换，还通过变更影响分析更新了构造函数和调用链，保持了代码的完整性。
⚠ 局限性与未来：CodePlan 的下一乐章
尽管 CodePlan 表现卓越，但它仍有改进空间。首先，在动态类型语言（如无类型注解的 Python）中，依赖分析的准确性可能受限，因为动态依赖难以通过静态分析捕捉。其次，CodePlan 目前专注于代码文件的修改，而企业级软件系统往往包含配置文件、元数据等非代码 artifacts，未来的依赖图需要扩展到这些领域。
此外，CodePlan 依赖语言模型的输出质量。如果模型生成了错误的代码，可能会引发连锁错误，尽管多轮迭代能部分缓解这一问题。未来的研究可以探索更复杂的提示策略（如 few-shot 或链式推理），或引入专门的错误检测机制。
另一个潜在方向是处理动态依赖，如数据流依赖或多线程执行依赖。这些依赖需要更高级的分析技术，可能结合运行时信息或符号执行。CodePlan 的框架具有良好的扩展性，可以通过定制变更影响分析规则，适应更多任务场景。
🎉 结语：代码仓库的未来交响
CodePlan 就像一位数字时代的指挥家，将大型语言模型的生成能力与规划算法的逻辑严谨性相结合，为仓库级编码任务带来了一场革命。它不仅提高了开发者的生产力，还为软件工程的自动化开辟了新路径。从包迁移到时间编辑，CodePlan 展示了人工智能在复杂软件开发中的巨大潜力。
未来，随着对动态依赖、非代码 artifacts 和更智能提示策略的支持，CodePlan 有望成为软件开发的「全能指挥家」，协调从代码到配置的每一部分，奏响更宏伟的数字交响乐。对于开发者来说，这不仅意味着更高效的工作流程，更是对创造力的解放，让他们专注于设计乐章，而非修补音符。
参考文献
- Bairi, R. , Sonwane, A., Kanade, A., et al. (2023). CodePlan: Repository-level Coding using LLMs and Planning. ✅arXiv preprint arXiv:2309.12499.
- Agrawal, L. A., Kanade, A., Goyal, N., et al. (2023). Guiding Language Models of Code with Global Context using Monitors. ✅arXiv preprint arXiv:2306.10763.
- Ahmad, W. U., Chakraborty, S., Ray, B., & Chang, K.-W. (2021). Unified Pre-training for Program Understanding and Generation. ✅arXiv preprint arXiv:2103.06333.
- Gupta, P. , Khare, A., Bajpai, Y., et al. (2023). GrACE: Generation using Associated Code Edits. ✅arXiv preprint arXiv:2305.14129.
- Wei, J. , Durrett, G., & Dillig, I. (2023). Coeditor: Leveraging Contextual Changes for Multi-round Code Auto-editing. ✅arXiv preprint arXiv:2305.18584.