AI 一次能改整个代码库:聊聊全仓库级编辑背后的检索与定位

真正让全仓库级编辑成为可能的，通常不是把几百万行代码一次性塞进上下文，也不是模型突然拥有了某种全知视角。它背后更接近一个循环工作的工程系统：先找到可能相关的区域，再把自然语言需求定位到具体符号和调用关系上，只读取当前步骤需要的代码，完成一小批修改，然后用编译、测试和新的搜索结果继续纠偏。

所谓“一次改完整个代码库”，本质上不是一次生成，而是许多轮检索、定位、编辑和验证被封装成了一次任务。

一、代码库不是一篇很长的文章

如果把仓库理解成一份超长文本，最直接的办法似乎是：把所有文件拼起来交给模型，让它从头读到尾。

这条路很快就会遇到三个问题。

第一是容量。一个中型项目就可能有几十万到几百万行代码，再加上依赖、生成文件、构建产物和历史配置，远远超过一次有效推理所需要的工作集。

第二是信噪比。修改订单状态机时，仓库里的图片、锁文件、其他业务模块和构建缓存不仅没有帮助，还会稀释真正关键的信息。

第三是结构。代码的意义并不只由相邻文字决定。一个函数真正影响谁，取决于导入、调用、继承、类型、路由、配置、数据库结构和运行时约定。两个相距很远的文件，可能在同一条调用链上；两个名字相似的函数，可能完全无关。

所以，面向代码库的 AI 首先要解决的不是“如何读完”，而是两个更实际的问题：

1. 这次任务究竟需要读哪些部分？
2. 用户说的概念，在代码中具体对应哪些文件、符号和关系？

前者是检索，后者是定位。

二、第一层检索：从仓库里缩小候选范围

当用户说“把所有旧鉴权迁移掉”，系统手里只有一段自然语言。仓库里却未必存在“旧鉴权”这四个字。它可能表现为 legacyAuth、一个旧的中间件、某个请求头、一组权限装饰器，或者散落在多个服务里的重复逻辑。

因此，成熟的编码 Agent 往往会组合几种检索方式，而不是押注一种搜索。

1. 文件与目录结构检索

仓库结构是成本最低、信息密度很高的一层索引。

src/auth、middleware、routes、tests、migrations 这些目录名，本身就在表达系统边界。package.json、pyproject.toml、go.mod、Cargo.toml、构建配置和 README，则能告诉 Agent 语言、框架、入口和验证命令。

所以 Agent 接手仓库后的第一步，通常不是立刻改代码，而是建立一张粗糙的地图：

仓库规则 → 技术栈与命令 → 主要目录 → 入口文件 → 目标模块

这张地图不需要覆盖每个文件。它的作用，是先排除大部分明显无关的区域。

2. 关键词与正则检索

精确文本搜索仍然是代码检索里最可靠的工具之一。

接口名、类名、环境变量、错误码、路由路径和配置键，都适合用关键词搜索。它速度快、结果可解释，而且不会因为语义模型的相似度判断而悄悄漏掉精确引用。

但关键词检索依赖“你已经知道该搜什么”。用户使用业务语言，代码使用技术语言；旧接口可能被包装、别名导入，甚至通过字符串和配置间接引用。只搜一个名字，通常只能找到第一圈线索。

因此，Agent 会从首轮结果里继续提取新关键词：导入来源、函数名、类型名、调用参数、错误信息，再进行下一轮搜索。检索词不是一次想出来的，而是在调查中逐渐长出来的。

3. 语义检索

向量检索擅长解决“意思相关，但字面不同”的问题。

例如，用户说“失败后自动重试”，代码里可能没有 retry，却有“重新入队”“指数退避”或“恢复未完成任务”等实现。把代码块、函数或文件摘要转成向量后，系统可以从语义上寻找候选区域。

不过，语义相似不等于真实依赖。一个仓库里可能有五套“重试”逻辑，检索出来都很像，真正需要修改的只有其中一套。向量检索更适合扩大候选集，不能单独承担最终定位。

4. 符号与依赖检索

代码天然是一张图。

定义与引用、导入与导出、接口与实现、调用方与被调用方、路由与处理器、模型与数据库表，都可以构成边。语言服务器、AST 索引、编译器数据库和代码图谱，能够回答纯文本搜索很难稳定回答的问题：

• 这个方法在哪里定义？
• 哪些调用真正指向这个符号？
• 一个接口有哪些实现类？
• 改动这个类型会影响哪些下游模块？
• 同名函数中，当前调用绑定的是哪一个？

文本搜索寻找“长得像的地方”，符号检索寻找“在程序结构上有关的地方”。全仓库修改要做稳，二者缺一不可。

三、定位比检索更难：找到文件不等于找到改动点

假设检索已经找到 20 个可能相关的文件，下一步并不是把它们全部交给模型重写。

Agent 还要判断：哪些是定义，哪些是调用方；哪些是真正运行的代码，哪些是测试夹具；哪些只是同名；哪些属于兼容层；哪些由代码生成器产生，不应该直接编辑。

这就是定位阶段。

定位通常需要建立三种上下文。

局部上下文：这个符号周围发生了什么

模型需要看到目标函数、相邻类型、导入和必要的辅助逻辑，而不是只看命中的一行。上下文过窄，容易错过默认值、异常处理和隐含约束；上下文过宽，又会引入无关内容。

因此，工具常以函数、类、代码块或固定行数为单位读取，并在发现新线索时继续展开。

关系上下文：它和仓库其他位置怎样连接

仅理解函数内部还不够。一次接口迁移至少要知道：谁调用它、返回值流向哪里、类型在哪里声明、测试如何构造输入、配置从哪里注入。

这也是为什么优秀的 Agent 会反复执行“找定义—找引用—读调用方—再找新引用”，而不是只围绕第一次命中的文件工作。

约束上下文：哪些东西不能被改变

代码库里最重要的信息，有时不在代码本身。

仓库说明文件、lint 规则、测试约定、API 文档、数据库迁移规则和团队指令，决定了一次修改的边界。一个实现从局部看完全正确，却可能违反公开接口兼容性、目录规范或部署环境限制。

全仓库编辑的质量，很大程度上取决于 Agent 能否在开始时发现这些约束，并在每轮编辑中持续保留它们。

四、Agent 如何从一句需求生成一组跨文件修改

以“把旧鉴权接口迁移到新接口”为例，一个较完整的执行过程大致如下：

理解任务  ↓读取仓库规则与项目结构  ↓搜索旧接口、封装层、配置和测试  ↓确认定义、引用与关键调用链  ↓列出修改计划和潜在影响面  ↓分批编辑实现、调用方、类型与测试  ↓运行类型检查、测试和构建  ↓根据错误重新检索并补漏  ↓审查最终 diff，再次验证

这里最关键的不是第一次修改有多准，而是系统有没有反馈闭环。

比如，模型修改了鉴权函数的返回类型，类型检查会暴露遗漏的调用方；测试失败会揭示某个兼容分支仍依赖旧行为；构建错误会指向未更新的导出；最终搜索则可以检查旧接口名是否还有残留。

编译器、测试和静态分析在这个过程中相当于第二套定位系统。它们把“可能哪里有问题”变成具体文件、行号和错误信息，再交给 Agent 继续处理。

因此，Agent 的能力并不只是生成代码。它还要会利用确定性工具产生的新证据，更新自己对仓库的理解。

五、为什么长上下文仍然重要，但不是全部答案

如果检索和定位已经这么关键，长上下文还有什么价值？

价值很大。

更长的上下文允许模型同时保留更多调用方、类型定义、测试、仓库约束和前几轮工具结果，减少信息在轮次之间丢失。对跨模块重构而言，能够同时对照旧实现、新接口和几个典型调用方，明显好过每次只看一个文件。

但长上下文解决的是“当前工作台能摆下多少材料”，不是“怎样从仓库里选对材料”。

一个百万 Token 的窗口，如果被锁文件、生成代码、重复日志和无关模块占满，效果可能还不如经过检索后得到的 30K 高相关上下文。随着任务推进，旧计划、过期错误和已经修改的代码片段还可能继续留在上下文里，造成版本混淆。

所以真正有效的架构通常是：

用检索控制进入上下文的内容，用结构化状态保留任务进度，用长上下文承载当前阶段的工作集，用工具验证对仓库真实状态的判断。

这四件事互相补位，而不是谁取代谁。

六、全仓库编辑最常见的五类失败

能力看起来很强，不代表它已经稳定。跨文件任务中的错误，往往不是语法写错，而是“少改了一处”或“多改了一处”。

1. 召回不全

Agent 找到了大多数直接引用，却漏掉动态导入、字符串配置、脚本、文档示例或另一种语言里的调用。最终代码局部正确，仓库整体仍处于新旧混用状态。

2. 同名误伤

仅凭文本或语义相似度，修改了名称相同但语义无关的模块。大型单体仓库、多语言仓库和复制代码较多的项目尤其容易出现这种问题。

3. 只改定义，没有追到消费端

函数签名改完了，直接调用方也更新了，但返回值经过两层封装后仍被按旧语义使用。符号引用能找到结构关系，却不一定自动理解业务语义的传播。

4. 上下文中的代码已经过期

Agent 先读文件 A，随后修改了它，几轮之后又根据早先读到的版本继续推理。如果工具没有重新读取当前内容，就可能生成冲突补丁或恢复旧逻辑。

5. 验证覆盖不足

测试通过，只能说明被执行的那些检查没有发现问题。测试缺失、条件编译、平台差异、外部服务和运行时配置，都可能让错误逃出闭环。

这些失败说明，全仓库编辑最难的指标不是“写对率”，而是改动覆盖率与影响面判断：该改的是否找全，不该改的是否避开，改完以后是否有足够证据证明系统仍然成立。

七、怎样让 AI 更稳地修改你的代码库

如果希望 Agent 在真实项目中可靠工作，仓库本身也要提供可检索、可定位、可验证的环境。

1. 给任务一个清晰边界

“优化鉴权代码”太模糊；“将 legacyAuth 的三个调用入口迁移到 verifySession，保持公开 API 和错误码不变”更容易形成完整候选集，也更容易判断任务何时完成。

2. 保持模块边界和命名可读

对人难以导航的仓库，对 Agent 同样难。稳定的目录结构、明确的入口、一致的命名和较少的隐式副作用，会直接提升检索质量。

3. 把项目命令和约束写进仓库

告诉 Agent 如何安装、测试、构建，哪些目录不能直接修改，哪些接口必须兼容，能减少它通过猜测建立错误工作模型。

4. 为关键路径提供机器可执行的反馈

类型检查、单元测试、集成测试、lint、API 契约测试和数据库校验，都是修改后的定位器。没有这些反馈，Agent 只能用“代码看起来合理”代替验证。

5. 要求先调查，再分批修改

让 Agent 在编辑前列出目标符号、调用方、风险和验证方式，可以尽早发现它的仓库地图是否错误。修改时保持批次足够小，则能让每次失败更容易归因。

6. 最后检查残留与 diff

完成迁移后重新搜索旧符号、旧配置和旧错误信息；同时审查完整 diff，排除无关格式化、意外删除和超出范围的修改。前者检查“是否漏改”，后者检查“是否多改”。

八、真正的突破，是 AI 学会了在代码库中行动

从代码补全到全仓库编辑，变化不只是上下文从几千 Token 增长到了几十万 Token。

更重要的变化是，模型外面多了一套可以行动的系统：它能浏览目录、搜索文本、查询符号、读取局部代码、应用补丁、运行命令，再把新的结果带回下一轮推理。

于是，代码库不再是一份必须一次读完的静态文本，而变成了一个可以持续查询、逐步理解、反复验证的环境。

这也解释了为什么今天的 Agent 可以修改远大于自身上下文窗口的仓库。它不需要永远记住每一行代码，只需要在当前步骤找到正确的工作集，并保留足以完成任务的关系和约束。

所谓“AI 一次能改整个代码库”，真正发生的是：

检索让它知道去哪里看，定位让它知道应该改什么，代码工具让它能够执行，验证闭环让它发现自己还漏了什么。

模型当然仍然重要，但仓库级能力从来不是模型参数单独创造的。它来自模型、搜索、代码索引、编辑器、编译器、测试系统和任务编排共同组成的一条链。

下一阶段的竞争，也不会只是谁能吞下更长的上下文，而是谁能更准确地建立代码地图、更完整地追踪影响面，并用更低的成本证明一次跨仓库修改真的完成了。