RAG 与代码库感知

RAG 与代码库感知

本节摘要:AI 的上下文窗口再大,也装不下你整个项目。当你问「帮我修改用户登录逻辑」时,AI 怎么知道登录代码在哪个文件、用了什么工具函数、有哪些调用方?答案是 RAG(检索增强生成):把你的代码切成小块、转成向量、建立索引,提问时通过语义检索找到最相关的代码片段,拼装进上下文。本节用直觉而非公式,讲清代码 RAG 的完整流程和 Cursor 中 @codebase 的底层机制。

一、为什么需要代码库感知

一个中等规模项目有 500+ 文件、5万+ 行代码。AI 的上下文窗口(即使 200K token)也装不下全部。

没有 RAG 时:你得手动告诉 AI「登录逻辑在 src/auth/login.ts,它调用了 src/utils/jwt.ts 的 verifyToken,还有 src/models/user.ts 的 findByEmail」。每次都要当「人肉索引」。

有 RAG 时:你说「帮我修改登录逻辑」,AI 自动搜索到相关文件,理解上下文后再回答。

二、代码 RAG 的完整流程

逐步解释:

索引阶段(项目打开时自动执行)

1. 分块:把每个代码文件切成小块(通常按函数/类/模块边界,每块 200~500 行)
2. 向量嵌入:用嵌入模型(如 text-embedding-3-small)把每块代码转成一个高维向量(如 1536 维的数字数组)
3. 存入索引:向量和对应的代码内容、文件路径一起存入本地索引

检索阶段(你提问时执行)

4. Query 向量化:把你的问题也转成向量
5. 语义检索:在索引中找到与问题向量「最相似」的 Top-K 个代码块(余弦相似度)
6. 上下文拼装:把检索到的代码块 + 你的问题 + .cursorrules 规范拼装成完整 prompt
7. LLM 生成:模型基于拼装后的上下文生成回答

关键概念:「语义相似」不等于「关键词匹配」。你问「怎么处理用户鉴权」,RAG 能找到名为 verifyToken 的函数——即使代码里没有「鉴权」这两个字。这就是向量检索比全文搜索强大的地方。

三、Cursor 中的 @codebase

Cursor 的 @codebase 就是代码 RAG 的用户界面:

• 你在 Chat 中写 @codebase 登录逻辑是怎么实现的?
• Cursor 把你的问题向量化 → 在项目索引中检索 → 找到最相关的代码块 → 拼装上下文 → 送给模型

@codebase vs @file:

• @codebase:AI 自己搜索,适合「不确定代码在哪」时
• @file:你手动指定,适合「明确知道要看哪个文件」时

💡 技巧:@codebase 的检索质量取决于索引质量。如果项目中有大量生成代码(node_modules、dist、.next),会干扰检索。用 .cursorignore 排除它们。

四、索引策略与性能

什么该索引

• 源代码文件(.ts / .py / .go / .java 等)
• 配置文件(package.json / tsconfig.json)
• 文档(README / docs/)

什么不该索引

• 依赖目录:node_modules / venv / vendor
• 构建产物:dist / build / .next
• 版本控制:.git
• 大型数据文件:*.csv / *.sql dump

.cursorignore

类似 .gitignore 的语法,告诉 Cursor 哪些文件不要索引:

node_modules/
dist/
.next/
*.min.js
*.lock
​

性能考量

• 首次打开大项目,索引可能需要 1~5 分钟(CPU 会飙高)
• 索引完成后,后续检索是毫秒级
• 项目文件变化时,索引增量更新(只重新处理变化的文件)
• 超大项目(10万行+)可能需要更多内存

五、RAG 的局限性

诚实说,RAG 不是万能的:

• 检索不准:如果问题太模糊(「帮我优化代码」),检索到的可能不相关
• 上下文窗口限制:即使检索到了 10 个相关代码块,加上问题本身,可能接近窗口上限
• 跨文件关系:RAG 能找到单个相关函数,但「A 调用 B,B 调用 C」的链式关系需要多次检索
• 新文件延迟:刚创建的文件可能还没被索引(通常几秒到几十秒延迟)

应对策略:

• 问题尽量具体(「src/auth/ 下的登录验证逻辑」优于「登录逻辑」)
• 对于复杂跨文件任务,手动 @file 指定关键文件 + @codebase 补充
• 给索引几秒钟追上你的编辑速度

本节要点回顾

1. 核心问题:项目太大装不进上下文窗口,需要「按需检索」
2. RAG 流程:代码分块 → 向量嵌入 → 建索引 → 提问时语义检索 → 拼装上下文
3. 语义检索:向量相似度匹配,能找到「意思相关但用词不同」的代码
4. @codebase:Cursor 中 RAG 的用户界面;不确定代码在哪时用它
5. 索引优化:用 .cursorignore 排除无关文件,提高检索精度
6. 局限:检索可能不准、跨文件关系需要多次检索、新文件有延迟

RAG 让 AI「看到材料」,.cursorrules 让 AI「知道规矩」。两者结合,就是下一节的实战:为一个真实项目构建专属的 AI 编程助手。