在上一篇文章《AI 友好架构：平台工程赋能 AI 自动编程》，我们提及了 DevOps 平台应该大量的预先生成项目、模板、上下文等信息。在这一篇文章中， 我们将详细展开其中的一个核心实践：预生成上下文。
最近的几个月里，预先生成上下文在 AI 编码领域成为了一个热门话题，或者说技术趋势。开发人员受益于这些 AI 生成的 Wiki，用于 快速理解开源项目的用途、技术架构。尽管，从理解深度来说，现在的基于 RAG、文档检索的方式还有待提升，还需要加入基于 AST 的上下文分析，来 提升准确度和覆盖度。但是从效率上来说，预生成上下文的方式已经成为了一个趋势。
因此，我们开始为 AutoDev 开发一个新功能 Context Worker，旨在通过预生成上下文来提升 RAG 的效果。如果你对这个功能感兴趣，欢迎加入我们的 GitHub：https://github.com/unit-mesh/autodev-work
引子：谁都会，但谁都做不好的 RAG
2023 年，LangChain 框架的出现从某种意义上简化（也从某种意义上复杂化）了 AI 应用的开发，RAG （Retrieval Augmented Generation） 也成为了一个热门的应用开发领域概念。RAG 的核心思想是将检索和生成结合起来，通过检索相关信息来增强生成模型的能力。
技术因素：不确定的 RAG，随机的模型生成
RAG 流程中的每一个环节都可能引入变数，这些变数累积起来，形成了影响最终效果的“不确定性链条”。
通常，主流的 RAG 实现包含两个主要阶段：
索引阶段。将非结构化、结构化的数据（个人无法理解）以某种拆分方式拆分，进行向量化（可选），存储到数据库中。
检索阶段。对用户的输入进行转换，进行向量化（可选），在数据库中进行检索，返回相关的上下文信息，再经过一定的处理（可选），传递给生成模型进行生成。
这个过程中存在大量的不确定性因素，导致了 RAG 的效果往往不如预期。
索引阶段：知识库构建的质量直接决定了后续检索的上限。其核心难点包括：如何合理分块以保留语义完整性（尤其是代码边界）、 选择合适的嵌入模型进行向量化、以及针对多源数据进行有效预处理，避免“垃圾进、垃圾出”。
检索阶段的挑战：即使用户查询意图明确，从索引中高效准确地找到相关信息也非易事。精准检索需解决查询歧义、提升搜索能力（如混合搜索、HyDE）、 进行结果重排序(Re-ranking)，并控制上下文长度以防信息丢失或干扰生成。
最后，由于 LLM 本身在生成回复时也会引入随机性。模型对查询意图的理解以及对检索到的上下文信息的解读都可能存在偏差，这导致即使输入完全相同， 输出结果也可能不一致或不准确。RAG 系统非常依赖外部数据的质量和相关性；如果检索过程出现偏差，生成阶段的质量必然会受到影响。
业务因素：大量的垃圾知识在影响到 RAG 的效果
去年，我们在与大量企业交流时发现：企业中海量的文档和代码（“文档太多”）带来了重大挑战。代码的版本化和文档的版本化方式是不一致的。通常来说，你 在流水线上通过的代码就是可以 work 的，但是你很难从 04-03.docx 和 修订版 12.docx 中判断出哪个是最新的版本。即使你能判断出哪个是最新的版本，你也很难判断出这个版本是否是正确的版本。
因此，质量参差不齐（“质量不齐”）进一步使问题复杂化，因为模型在即时处理时可能会从次优或错误的示例中学习或检索信息（用户查询）。如果引导不当，生成式 AI 可能会产生有害的、虚假的或剽窃的内容，当输入数据庞大且未经整理（即未经过预处理和筛选）时，这些风险会放大。
在这种文档数据背景下，即使拥有最优秀的文本分块、向量嵌入和检索算法，它们也只能在充满噪声、过时或错误的数据之上运行。其结果是，RAG 系统非但不能解决企业原有的信息混乱问题，反而可能延续甚至放大这些问题。
代码检索：从结构化检索到 DeepWiki
生成式 AI 能很好解决创建新项目的问题，但是对于理解和修改存量的代码，依然会有大量的挑战。在软件工程师和 AI 研究员各自有各自不同的思考， 工程师讲究的是经典的工程化思维，AI 更多的是大力飞砖的新一代方式，两种思维方式在过去的几年里不断的交融。
当前主流的 AI 编程工具在代码检索方面采用了多样化的策略，它们通常结合了传统的基于关键字和结构的方法与新兴的 AI 技术，以期在速度、准确性和上下文理解之间取得平衡。
关键信息检索：工程思维与结构化索引
当你的检索需要在客户端运行的时候，你需要考虑到性能和效率的问题。你需要考虑到如何在本地的机器上进行高效的检索，而不是依赖于云端的计算能力。
而代码本身是结构化的，但是并不意味着主流的代码检索方式是结构化的。我们在之前的文章中提到过，主流的代码检索方式有两种：
基于关键信息的检索：如 Cline、Copilot、Cursor 等
基于代码和文本的检索：如 Bloop、SourceGraph Cody 等
而从现有的方式来看，主流的是基于关键信息的检索方式。诸如于：
Cline：AST（抽象语法树） + 正则检索
Copilot（2024）：生成关键词 + TreeSitter AST（抽象语法树）中的关键信息（类、方法名等）搜索
Cursor：Ripgrep 文本搜索 + 云端的向量化
Continue：基于 SQLite 的文本搜索 + LanceDB 本地向量化
……
简单来说，它们都是基于关键信息来进行检索的，只需要对代码的类名、方法名、变量名等进行检索即可。所以，用户的输入是一个关键词，或者是一句话，再交由 模型来转换成查询条件，最后交给模型总结即可。
不过，关键词检索速度快，但其对用户意图的理解有限，容易产生不相关的结果。而基于抽象语法树的检索虽然能理解代码结构，但在处理语义相似性方面存在不足。
关键文档生成：预生成代码库文档
当你的检索可以在云端运行的时候，又需要考虑到性能和效率的问题，预先生成文档就变成一个非常好的方案：它可以解决存量大量文档的老旧问题，并且可以 提升非常高效的检索效率。
如下是我们结合 DeepResearch 调研的：代码文档工具中预生成策略对比分析
如我们开头所说，尽管从理解深度来说，现在的基于 RAG、文档检索的方式还有待提升，但是一旦成为技术趋势，那么就会有大量的工具和平台开始支持这个趋势。
而这些工具在面对复杂或包含隐式逻辑的代码时，由于缺少准确的代码关联关系，对于缺少文档或者大型项目来说，就变得非常有限。
与之相似的，在模型能力进一步加强之后，AI 友好的文档也是一个非常重要的话题。文档中的代码准确性就变得更加重要，错误的文档和知识，刚会 让你的 AI 助手变得难以信任。
预生成上下文
预生成上下文是指在用户发起查询或生成请求之前，系统针对特定代码仓库、文档或 SDK，离线构建一组结构化的上下文数据。这些上下文经过理解、 加工与组织，使其在运行时能够被快速检索和引用，从而提升代码智能体在生成、解释或检索代码时的准确性、相关性和响应速度。
其核心要素包含：
文档与代码的抽取与解析：包括 API 文档、源码注释、示例代码、变更日志等；
语义理解与摘要生成：提取关键能力、用途、限制等元信息；
向量化与索引构建：为快速语义检索构建 embedding 索引；
版本绑定与内容更新策略：确保上下文始终与特定版本保持一致；
AutoDev 探索：AutoDev Context Worker
基于上述的想法和研究，我们开始构建 AutoDev Context Worker。结合我们的 AutoDev IDE 插件的能力，以下是我们的基本思路：
深度项目解析与 AST 构建结构化，Context Worker 对整个项目（或指定的模块范围）进行深度解析。这包括构建完整的 AST，识别所有的函数、类、接口及其签名、注释（docstrings）。同时，分析项目依赖（内部模块间和外部库依赖），构建初步的依赖图。
自动化代码摘要与“意图”标注：对于缺乏良好注释的代码块（函数、复杂逻辑段），尝试使用 LLM 预先生成简洁的摘要或“意图描述”。对于一些关键的架构组件或核心算法，可以预先打上特定的标签或元数据。
构建项目级知识图谱：将解析出的代码实体（类、函数、变量等）及其关系（调用、继承、实现、引用等），并围绕领域模型构建知识图谱， 标注实体的语义和上下文信息。
……
通过这些预计算和预组织工作，Context Worker 旨在为 AI 辅助研发功能（如代码生成、缺陷修复、代码重构、需求理解等）提供高质量、即时可用、 深度结构化的上下文。解决了传统 RAG 在处理复杂代码时可能出现的上下文不完整、不准确、检索效率低等问题，从而更好地实现 “AI 友好架构”的理念， 赋能更高级别的 AI 自动编程能力。
总结
本文探讨了预生成上下文作为增强 AI 编程能力的关键机制。传统 RAG 方法面临的不确定性和知识质量问题，使得预生成上下文成为一种更可靠的替代方案。通过对比分析了当前代码检索方法的局限性，我们看到基于关键信息检索虽快速但理解有限，而 DeepWiki 等预生成文档工具虽有进步但在处理复杂代码逻辑时仍有不足。
预生成上下文代表了 AI 友好架构的重要实践，它将传统软件工程的结构化思维与AI大模型的生成能力相结合，为下一代智能编程工具铺平了道路。通过主动构建而非被动检索代码上下文，我们能够更好地赋能AI理解和修改现有代码库，使开发者能够更专注于创造性工作，而非重复性任务。
