Clipping 微信公众号

别再用 RAG 思路做 AI Coding 知识库:上一代知识系统,正在拖慢下一代 Code Agent

by Dolphin7 原文 ↗
Created: 2026-07-06

公众号名称:dolphin07

作者名称:Dolphin7

发布时间:2026-07-06 19:45

如果 Cursor、Claude Code、Codex 这类 Code Agent 想理解你的项目,它们第一反应真的是去查 RAG(Retrieval-Augmented Generation,检索增强生成)吗?

很多团队的默认答案是:当然。

把 README、接口文档、设计方案、事故复盘、历史需求切片,做 embedding,放进向量库;用户提问时检索 TopK,把结果拼进 prompt,再让大模型回答。看起来,一个“能理解项目的智能编程助手”就搭起来了。

但这套系统真正擅长的,是回答问题,不是修改系统。

RAG 没错。错的是把 RAG 当成 Code Agent 知识系统的中心。

当你让 Agent “加一个退款接口”时,你不是要它解释退款流程,而是要它在现有订单、支付、库存、权限、消息、数据库、测试体系里完成一次正确变更。它最后交付的不是一段答案,而是一个 patch;它要证明的不是“说得对”,而是“改得对”。

这里有一个被低估的分界:

RAG 面向问题,Code Agent 面向任务。

RAG 找相关资料,Code Agent 需要组装可行动上下文。

RAG 是给模型补资料,不是给 Agent 建现场。

继续用“给人查资料”的方式喂一个“要执行任务的 Agent”,本质上是在把工程现场降维成文档问答。

这会带来一个很具体的后果:知识库越做越全,Agent 改代码却仍然不稳。

这件事要分四层看:

  1. 1. RAG 到底经历了怎样的技术演进,每一步解决了什么问题;
  2. 2. 为什么演进到 Agentic Retrieval,仍然不能自然覆盖 Code Agent 场景;
  3. 3. Agentic Search 的本质是什么,它和 RAG、Agentic Retrieval 的边界在哪里;
  4. 4. 面向 Code Agent 的知识系统,为什么应该从“文档检索”升级为“任务上下文系统”。

一、RAG 解决的是“回答有依据”

RAG 不是简单的“向量库 + TopK”。工程实现上,它通常分成两段:离线索引把资料变成可检索资产,在线问答把用户问题转成检索、排序、上下文拼装和回答生成。

RAG 最初要解决的是一个朴素但关键的问题:模型参数里的知识有限、会过期、不可直接更新;企业真实知识在外部系统里,需要在回答时被检索进来。

经典 RAG 把预训练模型的参数记忆和外部非参数记忆结合起来。模型不再只依赖自己“记住了什么”,还可以从外部知识索引里取回资料,再基于资料生成回答。它非常适合知识密集型问答:你问“报销流程是什么”,系统找到流程文档;你问“订单接口有哪些字段”,系统找到接口说明;你问“某次事故为什么发生”,系统找到复盘材料。

这条路线优化的核心是 answer grounding:让回答更准确、更有依据、更少幻觉。

但 RAG 并没有停留在“向量库 + TopK”。过去几年,它一直在演进。

阶段典型做法主要解决的问题仍然留下的边界
Naive RAGchunk + embedding + vector top-k让模型看到外部资料query 稍偏就召回差,chunk 容易切断语义
Advanced RAGquery rewrite、hybrid search、metadata filter、rerank、context compression提升召回率、排序质量和上下文利用率仍主要是在回答前选择资料
Graph RAG实体抽取、关系聚合、社区摘要、多跳查询处理跨文档关系和复杂实体关联图谱关系不等于代码执行影响面
Modular RAGrouter、多索引、多检索器、fusion、可插拔 pipeline支持异构知识源和复杂检索链路模块再多,核心仍是检索管线
Agentic Retrievalquery planning、多轮检索、retriever as tool、source reference、activity log让 Agent 规划检索、拆分问题、多源查资料主要还是为回答或 grounding 生产资料

这张表要表达的不是“RAG 过时了”。

恰恰相反,RAG 一直在变强。Naive RAG 解决“能不能看到外部资料”,Advanced RAG 解决“能不能找得更准”,Graph RAG 解决“能不能理解关系”,Modular RAG 解决“能不能接入多源数据”,Agentic Retrieval 解决“能不能让 Agent 规划检索”。

但这条演进线一直围绕一个中心目标:让模型获得更好的 grounding data,然后生成更可信的回答。

RAG 的演进,本质上是在强化“回答前的资料供给”;Code Agent 的难点,却发生在“行动中的证据调度”。

而 Code Agent 的目标不是回答正确。它要在一个真实工程系统里行动,并用测试、编译、CI、review 来证明行动正确。

这一步,就已经越过了传统 RAG 的中心边界。


二、为什么“上一代知识系统”会拖慢 Code Agent

“上一代知识系统正在拖慢下一代 Code Agent”,不是因为 RAG 落后,而是因为系统目标错了。

拖慢 Agent 的不是 RAG 本身,而是把所有工程事实都当成文档来处理的系统假设。

一旦这个假设错了,后面的技术投入会越做越偏:索引越多,噪声越多;文档越全,误导越隐蔽;召回越高,Agent 越可能自信地改错。

拆开看,至少有四种拖慢机制。

拖慢机制RAG 思路里的默认做法Code Agent 真正需要的能力
上下文选择过早在回答前用 query 决定 TopK在任务推进中动态决定下一步要查什么
知识形态被压平把代码、schema、测试、文档都当文本片段按 symbol、call graph、API、DB、test 等结构化方式组织
反馈信号断开检索结果进入 prompt 后,链路基本结束测试失败、编译错误、CI trace 要回流到搜索和上下文构建
指标目标错位优化 recall@k、faithfulness、answer correctness优化入口定位、约束覆盖、测试通过、review 返工率

第一,RAG 容易过早决定上下文。

在问答系统里,先检索再回答是合理的。用户问“退款流程是什么”,系统找到退款文档,然后生成答案。但在代码任务里,很多关键线索不是一开始就知道的。Agent 读到一个函数,才知道要追哪个调用方;跑出一个测试失败,才知道真正约束藏在哪个边界 case;打开 schema,才发现文档里的字段早就废弃。

如果一开始就用 query 做 TopK,等于在 Agent 还没理解任务现场之前,就替它决定了现场是什么。上下文选早了,后面的推理再聪明,也是在错误现场里推理。

第二,RAG 容易把知识形态压平。

代码不是普通文档。代码有 symbol、类型、调用关系、数据流、控制流、运行副作用、测试约束和部署路径。数据库 schema 不是“关于数据库的文本”,它是系统状态的硬约束;OpenAPI 不是“接口说明文档”,它是调用契约;测试不是“知识材料”,它是可执行的行为边界。

把这些都塞进向量库,本质上是在用一种工具处理所有知识形态。这不是统一知识,而是抹平约束。

第三,RAG 容易断开反馈。

问答系统的反馈主要来自回答质量:是否准确、是否有引用、是否忠实于材料。Code Agent 的反馈来自工程系统:编译是否通过,测试是否失败,schema 是否允许,调用链是否受影响,review 是否指出兼容问题。

如果测试失败不能触发下一轮搜索,如果 CI trace 不能进入上下文构建,如果 review 反馈不能沉淀为任务约束,那么这个系统就只是“回答时查资料”,还不是“执行时找证据”。

第四,RAG 容易让指标错位。

一个 RAG 系统可以有很高的召回率,却仍然帮不上代码修改;它可以找到很多相关文档,却漏掉真正的调用方;它可以回答得很完整,却让 Agent 改错入口。

Code Agent 知识系统的第一指标不是“资料像不像”,而是“改动能不能成立”。

这就是上一代知识系统拖慢下一代 Agent 的方式:它不是让模型变笨,而是让团队围绕错误目标优化。


三、用一个退款任务看清楚:相关文档不等于可执行上下文

假设你让 Agent 做一个看似普通的任务:

给订单系统增加退款能力。

作为问答问题,RAG 可以直接发挥作用:召回退款流程文档、订单系统 README、支付接口说明、历史需求文档,然后总结出一段完整回答。

但如果这是一个真实代码任务,Agent 需要走的路径完全不同。

它首先要找到入口:退款能力应该加在哪里?是 order controller,还是 payment service,还是已有 after-sale 模块?如果系统里已经有取消订单、逆向交易、补偿库存、支付回滚这些实现,它们可能比任何设计文档都更有参考价值。

然后它要理解数据状态:订单表里是否已有 refund_status?状态是否允许从 paid 转到 refunding?有没有唯一索引保证幂等?有没有历史 migration 导致字段语义和文档不一致?

接着它要理解服务关系:退款会影响支付服务、库存服务、积分服务、消息服务吗?这些调用是同步还是异步?失败后如何补偿?消息重试会不会导致重复退款?

它还要理解接口契约:退款 API 的 request、response、错误码、权限、幂等 key、审计字段,哪些是强约束?哪些只是文档建议?

最后它要找到验证路径:哪些单测覆盖状态流转?哪些集成测试覆盖支付回滚?有没有历史 bug 用例?CI 失败时应该继续追哪条路径?

把这些信息拆开看,会发现真正支撑代码修改的上下文并不主要来自文档。

Agent 需要知道什么更可靠的信息来源主要知识形态
退款入口在哪里route / controller / service / symbol index代码结构
已有类似逻辑怎么写semantic code search / reference search代码模式
谁会被影响call graph / dependency graph工程关系
API 契约是什么OpenAPI / gRPC / GraphQL metadata结构化契约
数据状态如何约束DB schema / enum / migration / constraint数据约束
是否要求幂等unique key / retry logic / incident history运行约束
为什么当初这么设计ADR / design doc / PR discussion文档和历史
怎么证明改对了test map / CI trace / similar tests验证证据

这里最容易被低估的一点是:你当然可以把整个代码库和文档都 embedding,但那只是把系统空间压扁成文本空间。

RAG 能找到“语义相似的片段”,但 Code Agent 更需要知道“这个片段在系统里处于什么位置,它依赖谁,它影响谁,它是否仍然可信”。

分界就在这里:相关性和可行动性,不是一回事。

RAG 的核心排序标准通常是 relevance:哪些内容和 query 更相似。Code Agent 需要的却是 actionability:哪些上下文足以支撑下一步正确行动。

相关,不等于可用;相似,不等于可改。

一个旧设计文档可能和任务高度相关,但已经过期;一个数据库唯一索引可能在文本上和用户需求不相似,却决定实现必须幂等;一个失败测试不是“知识文档”,却可能是下一轮搜索最重要的线索;一段 commit message 不适合回答用户问题,却可能解释为什么某个看起来多余的兼容分支不能删除。

所以 Code Agent 的上下文至少要满足四个维度:

维度含义代码任务里的例子
Relevance与当前任务相关refund 文档、退款代码、支付接口
Freshness反映当前系统事实当前 schema、当前 API、当前测试
Actionability能指导下一步行动入口函数、调用方、错误码、约束
Verifiability能被验证单测、集成测试、CI trace、review checklist

只有 relevance,是不够的。

更危险的是,相关但不可行动的上下文会让 Agent 更自信。它可能基于旧文档改代码,基于局部片段推断全局行为,基于相似 chunk 忽略真实约束。

这就是为什么很多 AI Coding 知识库在问答阶段看起来不错,一进入自动修改、自动修 bug、自动重构,就开始不稳定。

问题不在于 RAG 完全没用,而在于你把 RAG 放在了系统中心。

RAG 应该负责文档和非结构化知识;Code Agent 的核心系统,应该负责把文档、代码、接口、数据库、调用关系、历史和测试组合成一个可行动上下文。


四、Agentic Search:不是更聪明的检索,而是任务控制流

讲到这里,必须区分三个概念:RAG、Agentic Retrieval、Agentic Search。

它们经常被混在一起,但在 Code Agent 场景里,混在一起会直接影响架构判断。

维度RAGAgentic RetrievalAgentic Search
触发点回答前回答前或回答过程中任务执行过程中
输入querycomplex query / chat history / subqueriestask state
工具retriever / rerankerretriever as tool / knowledge source routersearch、read、schema、git、test、CI、compiler
控制权pipeline 决定检索流程Agent 或 LLM 规划检索Agent 根据执行反馈决定下一步
反馈answer qualitygrounding quality / source referencetest failure、compile error、CI trace、review signal
输出answer contextgrounded evidencenext-action context

Agentic Retrieval 主要解决“如何让 Agent 更聪明地检索资料”。

例如 Microsoft Azure AI Search 的 agentic retrieval,会让系统进行 query planning,把复杂问题拆成多个 subquery,并行执行 keyword、vector 或 hybrid search,再做 semantic reranking,最后合并结果,同时保留 source reference 和 activity log。LangGraph 的 agentic RAG 也体现了类似思路:retriever 不再只是固定 pipeline 的一个步骤,而是 Agent 可以决定是否调用的 tool。

这比传统 RAG 前进了一大步。但 Code Agent 还要再往前。

Agentic Search 不是让检索更聪明,而是让搜索进入 Agent 的执行控制流。

Retrieval 的关键词是“取回资料”,Search 的关键词是“寻找证据”。前者服务回答,后者服务行动。

它不只是问“要检索哪些资料”,而是持续回答:

  1. 1. 当前任务推进到哪一步了?
  2. 2. 现在缺少哪类证据?
  3. 3. 应该查代码、schema、测试、Git,还是文档?
  4. 4. 新发现是否推翻了上一轮假设?
  5. 5. 验证失败后,下一轮搜索应该从哪里开始?

在退款任务里,它可能是这样的:

这条路径不是一次 TopK 能解决的。它要求搜索成为 Agent 行动的一部分。

这也是为什么“Agentic Search”比“Agentic Retrieval”更适合描述 Code Agent 场景。Retrieval 强调把资料取回来,Search 强调在环境中寻找证据、更新状态、决定行动。前者仍然像知识系统,后者更像任务系统。


五、任务上下文系统:Code Agent 需要的是四层责任,而不是一个向量库

RAG 不够,Agentic Search 也不是全部。真正落地时,还需要一个系统级承载。

不必发明新名词。更准确的说法是:Code Agent 需要一个面向任务的上下文系统。

它的责任边界很清楚:

在 Agent 执行任务前和执行过程中,从代码、文档、API、数据库、图谱、Git、测试等系统里选择证据,并把证据组织成可行动、可验证、可迭代的任务上下文。

它的输入不是“用户问题”,而是“工程任务”。

它的输出不是“回答”,而是“任务上下文包”。

最小架构可以这样理解:

这套系统有四层责任。

责任层输入输出典型失败模式
规划器 Planner任务、仓库状态、当前进度证据计划查错源、查太多、漏掉关键约束
工具层 Tools证据计划原始证据只拿文档、漏 schema/test/call graph
组装器 Builder原始证据、上下文预算任务上下文包把噪声塞进 prompt,或丢掉关键事实
验证器 Verifierpatch、测试、CI/review 反馈通过/失败、新线索失败不能回流搜索,Agent 原地重试

第一层是 Planner。

它判断当前任务需要哪些上下文。修 bug、新增接口、重构、补测试、依赖升级,需要的上下文完全不同。Planner 的价值是避免把所有资料都当上下文,也避免让模型在噪声里猜。

第二层是 Tools。

它们从不同系统里拿证据。文档用 RAG,代码用 symbol index、AST、LSP、semantic code search,调用关系用 call graph,API 用 OpenAPI / gRPC metadata,数据库用 schema metadata / migration history,历史原因用 commit / PR / issue search,验证路径用 test map / CI trace。

第三层是 Builder。

它把多源证据组织成 Agent 能行动的上下文,而不是简单堆 chunk。它要标明哪些事实必须进入 prompt,哪些只是导航线索,哪些可能过期,哪些和当前代码冲突,哪些需要继续验证,哪些应该转成测试 checklist。

第四层是 Verifier。

Code Agent 的上下文不能停在“看起来合理”。它必须被测试、CI、静态检查、review 反馈验证。验证失败不是结束,而是下一轮搜索的入口。

一个真正有用的任务上下文包,应该直接告诉 Agent:从哪里改、受什么约束、怎么验证。

任务上下文包:新增退款能力

目标:
  - 新增退款能力
  - 不破坏支付、库存、消息重试

修改入口:
  - order.controller.createRefund()
  - payment.service.rollback()

当前事实:
  - orders.refund_status 已存在
  - refund_request 有幂等唯一键
  - 老订单可能没有 refund_status

相关实现:
  - cancel order flow
  - reverse payment flow
  - inventory compensation handler

接口契约:
  - POST /refund
  - PaymentRollbackRequest
  - RefundErrorCode

关键风险:
  - 重试导致重复退款
  - 库存补偿消息乱序
  - 老订单兼容

验证路径:
  - 正常退款
  - 重复请求
  - 支付失败
  - 库存补偿重试
  - 老订单兼容

待确认:
  - refund_status 是回填,还是首次退款时懒初始化?

到这里,任务上下文系统已经不抽象。

它不是“再做一个知识库”,而是把分散在工程系统里的事实组织成 Agent 可以行动的现场。


六、长上下文不是解法:容量变大,不代表选择正确

这里还需要补一个常见误区:既然模型上下文窗口越来越大,为什么不把整个 repo、所有文档、所有历史都塞进去?

这解决的是容量问题,不是上下文工程问题。

长上下文解决“装得下”,不解决“选得对”。

长上下文能让模型“装下更多”,但不能自动解决四件事:

问题为什么长上下文解决不了
选择哪些事实对当前任务真正重要,仍然需要判断
顺序哪些信息应该先进入注意力中心,仍然需要组织
可信度文档是否过期、代码是否最新、历史是否仍适用,仍然需要标注
验证上下文是否足以支撑 patch,仍然要靠测试和工程反馈

更大的上下文窗口,甚至可能让问题更隐蔽。

当你塞进去的材料更多,Agent 看起来更“懂项目”,但它也更容易被噪声污染,更难区分旧文档和当前代码,更难判断哪条信息应该支配实现决策。

对 Code Agent 来说,真正稀缺的不是 token 容量,而是高信号证据。

所以任务上下文系统的目标,不是把更多东西塞给模型,而是在每一步找到最少但足够的工程证据。

上下文不是越多越好,而是越能支撑下一步行动越好。

这也是 Context Engineering 在 Agent 时代变得重要的原因:提示词只是入口,真正决定 Agent 行为的是每一轮推理时进入上下文的状态、工具结果、历史记录、约束和验证反馈。


七、企业落地:不要先选向量库,先选一个可验证任务

很多团队一上来就问工具:

  • • 向量库选 FAISS、Pinecone、Qdrant、Milvus,还是 pgvector?
  • • RAG 框架用 LangChain 还是 LlamaIndex?
  • • 搜索用 Elastic 还是 OpenSearch?
  • • 图数据库要不要上 Neo4j?
  • • 要不要做 MCP?

这些都是二阶问题,不该排第一。

更重要的问题是:

这个任务需要哪种上下文?

因为不同知识形态,需要不同索引方式。

知识形态典型内容更合理的技术
文档层README、ADR、技术方案、事故复盘Docs RAG + hybrid search + rerank
符号层function、class、interface、definition、referenceSymbol Index / LSP / AST
调用层caller、callee、dependency、service relationCall Graph / Dependency Graph
接口层OpenAPI、gRPC、GraphQL、error codeAPI Metadata
数据层table、column、index、constraint、migrationDB Schema Metadata
历史层commit、PR、issue、incidentGit / PR / Issue Search
验证层unit test、integration test、CI traceTest Map / Verification Trace

RAG 适合自然语言文档。

代码结构需要代码索引。

调用影响需要图。

接口和数据库需要 schema。

历史原因需要 Git。

验证路径需要测试系统。

如果把所有东西都塞进向量库,本质上是在用一种工具处理所有知识形态。这不是先进,而是把系统结构压平了。

真正的建设路径应该从一个真实任务倒推。

比如第一版只选一个目标:

让 Agent 修改一个真实接口,并通过测试。

那么 MVP 可能只需要:

  1. 1. 能找到相关 route、controller、service、function;
  2. 2. 能找到同 repo 的相似实现;
  3. 3. 能检索 README、ADR、设计文档;
  4. 4. 能读取 OpenAPI / gRPC 定义;
  5. 5. 能读取表结构、字段、索引、关键状态;
  6. 6. 能找到主要调用方和依赖服务;
  7. 7. 能定位并运行相关测试;
  8. 8. 能把测试失败回流成下一轮搜索线索。

这一版跑通后,再补更完整的 code graph、更好的 rerank、更强的 freshness、更细的 eval、更系统的 trace。

不要一开始就建设“公司级研发知识中台”。

先让 Agent 在一个真实 repo、一个真实任务上,少读错文件,少漏约束,更快通过测试。

先让一个真实任务跑通,再谈平台化;先让一次改动变准,再谈知识中台。


八、真正的评估指标:不是召回率,而是改动质量

如果按 RAG 项目评估,指标通常围绕检索和回答:

  • • recall@k;
  • • MRR;
  • • answer correctness;
  • • faithfulness;
  • • 引用是否正确。

这些指标仍然有用,但不足以评估 Code Agent。

Code Agent 的知识系统应该看另一组指标:

指标说明
入口定位时间Agent 是否更快找到正确文件、函数、接口
约束覆盖率是否覆盖 schema、API、调用方、权限、幂等、测试
无关阅读量是否减少无关文件和噪声上下文
过期引用率是否减少对旧文档、旧实现、旧约束的依赖
调用方漏检率是否减少影响面遗漏
测试定位时间是否更快找到应该运行和补充的测试
一次通过率patch 是否更高概率通过定向测试
返工率review 后是否更少因为上下文缺失返工
失败恢复能力测试失败后是否能搜索新证据并修正

**指标一变,系统形态就变了。**这不是普通的 RAG 系统,而是 AI Coding 平台的一层基础设施:RAG 解决模型如何看到资料,Agentic Retrieval 解决 Agent 如何规划检索资料,Agentic Search 解决 Agent 如何在任务中持续寻找证据,Context Engineering 解决哪些证据应该在什么时候进入上下文,而任务上下文系统负责把这些能力组织成一个可执行、可验证、可演进的工作环境。

这条关系可以压成一句话:

这不是概念升级游戏,而是系统责任的变化:以前知识系统服务阅读,现在知识系统服务行动;以前资料相关就有价值,现在上下文必须支持任务推进;以前人是最终判断者,现在 Agent 会直接执行。

当执行权交给 Agent,知识系统就不能只证明“我找到了资料”,而要证明“我支撑了一次正确行动”。


结尾:别用上一代知识系统解决下一代 Code Agent 问题

所以,“别再用 RAG 思路做 AI Code Agent”,不是说 RAG 没用。RAG 仍然有位置,它是文档通道,是任务上下文系统中处理 README、ADR、设计文档、事故复盘、规范说明的重要能力。

但 Code Agent 还需要代码索引、调用图、API schema、数据库 schema、Git history、测试映射、上下文规划、证据组装和验证反馈。只做 RAG,得到的是一个更会查资料的系统;要做 Code Agent,需要的是一个能组织工程现场的系统。

最后用三句话收束:

RAG 面向问题,Agent 面向任务。

RAG 检索文档,Code Agent 组装上下文。

Code Agent 的知识系统,本质上不是向量数据库,而是一个可组合、可验证、可行动的任务上下文系统。

未来 AI Coding 知识库的竞争,不会停留在谁有更大的向量库,而会转向谁能把工程事实组织成可执行上下文。真正值钱的不是“知识接入”,而是“上下文调度”。

如果还在用“切 chunk + embedding”的方式构建 Code Agent 知识库,问题可能不在模型能力,而在用上一代知识系统解决下一代 Code Agent 问题。

这篇先把第一层问题讲清楚:别把 Code Agent 的知识系统做成文档问答系统。

后面几篇会继续拆更具体的坑:

  1. 1. Agent 会自己搜索以后,为什么更容易被旧文档带偏?
    讲知识污染:旧 Wiki、半成品需求、事故复盘、Memory,哪些能进上下文,哪些必须降权。
  2. 2. 知识库越全越费 Token:Repo Map、Symbol Index、Code Graph 怎么救场?
    讲上下文预算:Repo Map 找方向,Symbol Index 找位置,Code Graph 找关系,最后只把证据放进执行上下文。
  3. 3. Token 降下来了,知识却没人敢信:Context Engineering 的治理难题。
    讲可信度:过期、漂移、冲突、责任人、CI / Review / Eval 如何把知识持续校准。
  4. 4. 自建 AI Coding 知识库:技术栈到底怎么选,怎么落地?
    讲落地路径:FTS、Vector、Tree-sitter、LSP、SCIP、Repo Map、Code Graph、Context Engine 怎么选,90 天内怎么证明有价值。

内容效果不满意?点此反馈

输入关键词开始搜索