AI 代码库索引策略：让 Agent 找到真正相关的文件

一次真实的翻车

上个月我在一个 Monorepo 里让 Coding Agent 改一个支付回调的处理逻辑。它很快就「改完了」——问题是我后来发现，它改了 apps/server 里的 handler，却漏掉了 packages/shared/src/payment-types.ts 里的类型定义，还完全没碰 apps/worker 里异步重试的那段代码。

原因不复杂：Agent 拿到的上下文里没有那些文件。它用关键词搜了「payment callback」，命中了 server 目录下的几个文件，就直接开干了。调用链上游的类型、下游的异步消费者，全部消失在检索盲区里。

这不是 Agent 变笨了，是索引没喂对。

代码索引为什么比文本索引难

普通文档检索面对的是平面文本——分词、向量化、排序，完事。代码不一样，它至少有四层结构：

1. 词法层：变量名、函数名、import 路径——关键词搜索能覆盖这一层
2. 语法层：AST 里的函数定义、类继承、接口实现——需要 parser 才能拿到
3. 语义层：这个函数「做什么业务」、这个模块「承担什么职责」——需要 embedding 或 LLM 理解
4. 拓扑层：调用链、数据流、部署依赖——需要图结构来表达

只靠任何一层都不够。关键词搜索会漏掉改了名但没改功能的引用；纯语义检索可能把「相似但无关」的文件拉进来；AST 能告诉你谁调用了谁，但不知道业务含义；图结构 powerful 但构建成本高。

2026 年的共识是混合索引——把多层信号组合起来，让 Agent 在检索时能同时利用结构精确性和语义模糊匹配。Ry Walker 在 2026 年 6 月的code intelligence tools 对比研究中把当前工具分成四个层次：知识图谱引擎、符号+语义搜索、上下文打包、商业平台。这个分类基本覆盖了市面上所有方案的索引策略光谱。

三层索引架构：从文本到图谱

我把自己实践和调研过的索引策略整理成三层，从简单到复杂：

第一层：文本分块 + 向量检索

这是最基础的 RAG 方案。把代码文件按固定行数或函数边界切成 chunk，用 embedding 模型转成向量，存进向量数据库，查询时做余弦相似度匹配。

# 最简单的代码索引：按行切分 + embedding
def chunk_by_lines(file_path: str, chunk_size: int = 50) -> list[str]:
    """按固定行数切分文件——最粗暴但也最快的方式"""
    with open(file_path) as f:
        lines = f.readlines()
    return [
        "".join(lines[i:i + chunk_size])
        for i in range(0, len(lines), chunk_size)
    ]
 
# 问题：一个函数可能被切成两半，语义断裂

这种做法的问题很明显：一个 80 行的函数可能被切成两个 chunk，语义断裂；两个功能完全不同但命名相似的函数会被错误召回。Cursor 早期的 @codebase 功能就用了这个方案，它在官方博客中提到，代码分块会「按函数、类和逻辑块智能切分」，而不是简单按行数——这已经是在弥补纯文本分块的缺陷了。

第二层：AST 感知分块 + 符号索引

用 Tree-sitter 之类的 parser 把源码解析成 AST，按函数、类、方法等语法单元切分。每个 chunk 天然是一个完整的语义单位。同时提取符号表——谁定义了什么、谁 import 了谁。

# AST 感知分块：用 Tree-sitter 按函数边界切分
import tree_sitter_python as tspython
from tree_sitter import Language, Parser
 
PY_LANGUAGE = Language(tspython.language())
 
def chunk_by_function(file_path: str) -> list[dict]:
    """按函数定义切分，每个 chunk 是一个完整的函数"""
    parser = Parser(PY_LANGUAGE)
    with open(file_path, "rb") as f:
        tree = parser.parse(f.read())
 
    chunks = []
    for node in tree.root_node.children:
        if node.type == "function_definition":
            chunks.append({
                "name": node.children[1].text.decode(),  # 函数名
                "code": node.text.decode(),
                "start_line": node.start_point[0],
                "end_line": node.end_point[0],
            })
    return chunks
 
# 每个 chunk 语义完整，不会把一个函数切成两半

arXiv 上的 Codebase-Memory 论文（Vogel et al., 2026）把这个思路推到了极致：用 Tree-sitter 解析 66 种语言的 AST，提取函数、类、接口、枚举等节点，再解析 CALLS、IMPORTS、INHERITS、IMPLEMENTS 等关系边，最终构建出一个属性图（property graph），存在单个 SQLite 文件里。整个系统零外部依赖，查询延迟低于 1 毫秒。

第三层：知识图谱 + 调用链追踪

在符号索引之上，把调用关系、数据流、git 共变关系、测试覆盖关系全部建成图。Agent 检索时不再只是找「相似的文件」，而是能沿着图做「影响分析」——改了这个函数，哪些调用方会受影响，哪些测试需要重跑。

// 知识图谱查询：追踪一个函数的所有调用方
interface CallGraphNode {
  file: string
  symbol: string
  line: number
  callers: CallGraphNode[]  // 谁调用了这个函数
  callees: CallGraphNode[]  // 这个函数调用了谁
}
 
// Agent 改一个函数前，先查图
async function getImpactSet(fn: string): Promise<CallGraphNode[]> {
  const graph = await loadCallGraph()
  const node = graph.findNode(fn)
  // BFS 向上遍历，找到所有间接受影响的调用方
  return bfsUpstream(graph, node, maxDepth = 5)
}
 
// 结果：Agent 知道改完这个函数，还要检查 3 个调用方和 2 个测试文件

Codebase-Memory 的评测数据显示，这种图方法在 31 种语言的对比中，token 消耗只有传统 explorer agent 的十分之一，工具调用次数减少 2.1 倍，质量分数 83% vs 92%——在函数式语言（Haskell、OCaml、Elixir）上差距缩小到约 1%。

索引流水线长什么样

把上面的思路串起来，一个完整的代码索引流水线大概是这样：

几个关键设计决策值得展开说：

增量检测——不能每次全量重建。Codebase-Memory 用 XXH3 哈希做文件级变更检测，Cursor 用 Merkle tree 做增量同步（大约每 5 分钟跑一次）。我的经验是，对于一个 5 万行的项目，全量索引要 2-3 分钟，增量检测能把变更文件的处理压缩到秒级。

调用图解析是最难的一环。Codebase-Memory 用了「6 策略级联」：从 import map 精确匹配（置信度 0.95）一路降到模糊字符串匹配（0.30-0.40）。对于 Go、C、C++ 这类有指针、模板的语言，还需要 LSP 风格的混合类型解析来处理 method receiver 和指针间接调用。

本地 vs 云端是个绕不开的问题。Cursor 的方案需要把代码加密上传到云端生成 embedding，它的博客明确说「源码不以明文存储」，向量库「只存向量，不存源码」，文件名和路径也做了混淆。但代码终究离开了本地。grepai 走了另一条路——100% 本地运行，用 Ollama 做 embedding，完全不出网。对于安全敏感的项目，这个区别很关键。

三个工具的真实表现

Cursor：产品级索引的标杆

Cursor 的 @codebase 功能是大多数开发者第一次接触「代码库索引」的入口。它的索引流程是：扫描文件 → 按函数/类/逻辑块智能切分 → 加密上传生成 embedding → 存入远程向量库 → 查询时 1-3 秒返回结果。

优势在于开箱即用、增量同步、团队共享索引（Secure Codebase Indexing）。缺点也很明显：超过 10 万行的大项目可能丢边缘代码；依赖云端，有数据合规顾虑；纯向量检索对结构关系不敏感。

CodeGraph：本地知识图谱的爆发

CodeGraph 在 2026 年 1 月上线，5 个月内拿到 47.4k GitHub stars。它的核心是用 Tree-sitter 解析 21 种语言的 AST，在本地 SQLite 里构建完整的依赖图、调用链和执行流。通过 MCP 协议暴露给 Agent，支持「影响半径分析」——改一个函数，立刻知道哪些文件会被波及。

独立评测显示 CodeGraph 能减少 58%-70% 的工具调用次数。但 Ry Walker 的研究也指出，这个项目 91% 的 commit 来自一个人，存在集中风险。

Codebase-Memory：学术级的严谨

这个 arXiv 论文项目把索引做到了极致严谨：66 种语言支持、6 策略调用解析、Louvain 社区检测、14 种 MCP 结构化查询。Linux 内核（2800 万行、75000 个文件）能在 3 分钟内完成索引，生成 210 万个节点和 490 万条边。BFS 调用路径追踪在深度 5 时只需要 0.3 毫秒。

论文的核心结论是：最优方案是混合策略——「图检索用于结构查询，文件探索用于源码级任务」。这和我自己的实践观察一致。

索引策略对比

检索结果要可解释

Agent 不能只是个黑盒——它得能说清楚「为什么读了这些文件」。我在实践中会要求 Agent 在动手之前先输出一段上下文说明：

我选择了以下文件作为上下文：
1. apps/server/handlers/payment.ts — 支付回调入口，匹配「payment callback」
2. packages/shared/src/payment-types.ts — PaymentCallback 类型定义，被 #1 import
3. apps/worker/payment-retry.ts — 异步重试逻辑，调用链下游
4. docs/payment-flow.md — 项目文档中的支付流程说明

未选择 apps/billing/invoice.ts 的原因：虽然包含 payment 关键词，
但属于账单模块，与回调处理无直接调用关系。

这种可解释性让人类审查者能快速判断 Agent 是否遗漏了关键模块。如果上下文选错了，后续实现再快也是白搭——你在一个错误的基础上盖楼，越高效越危险。

我见过最糟糕的情况是一次数据库迁移重构。Agent 只看到了 migration 文件本身，没有读取 db/seed.ts 里的测试数据构造逻辑，也没有看 scripts/backfill.ts 里的历史数据处理脚本。结果是迁移本身写对了，但测试数据和新逻辑不匹配，历史数据也没被正确转换。如果 Agent 在动手前输出了上下文选择说明，人类审查者一眼就能看出缺了这两个文件。

另一个值得注意的点是上下文预算控制。大模型的上下文窗口是有限的，你不能把所有相关文件都塞进去。我的做法是按任务类型分配预算：

• 修改单个函数：只加载直接调用链（上游调用方 + 下游被调用方），预算控制在 4000 token 以内
• 跨模块重构：加载模块边界、接口定义和测试文件，预算 8000-12000 token
• 新功能开发：加载相关 feature 目录、类型定义、项目规范文档，预算 12000-16000 token

超出预算时，优先保留调用链上的文件和类型定义，砍掉纯语义相似但无结构关联的文件。

索引不是万能药：与验证闭环结合

Indexed agent 在 ForgeCode 的对比测试中确实表现更好——平均快 22%，API 调用少 35%。但这个测试也暴露了一个有趣的问题：在最后的编码任务（Land the Lunar Module）中，indexed agent 反而表现更差——211 秒 vs 157 秒，25 次 API 调用 vs 18 次。原因是「同步漂移」：它用了过时的 embedding，引用了不存在的函数。

这说明索引有两个固有局限：

1. 时效性——索引总是滞后的。分支切换、PR 合并、本地未提交的修改，都可能让索引和实际代码不一致。
2. 精度边界——embedding 是近似匹配，不是精确查询。它会召回「看起来相关」的文件，但不保证逻辑相关。

所以索引永远不能替代验证。Agent 找到相关文件、完成修改之后，仍然要跑 typecheck、测试、build，最好还有浏览器验收或 E2E。这些验证步骤是最后一道防线，确保改动真的正确，而不是「看起来正确」。

从架构层面看，索引和验证构成了一个闭环：索引负责缩小搜索空间，让 Agent 能快速定位到相关文件；验证负责确认改动的正确性，捕获索引无法覆盖的逻辑错误。两者缺一不可。只有索引没有验证，你会得到「高效但可能错误」的输出；只有验证没有索引，你会得到「正确但低效」的输出——Agent 在大量无关文件里大海捞针，浪费时间和 token。

实践中我还发现一个有趣的现象：当索引质量好时，Agent 的验证通过率也更高。这不是巧合——好的索引让 Agent 看到了完整的上下文，它做出的决策更准确，自然更容易通过验证。反过来说，如果验证反复失败，很可能是索引出了问题——Agent 漏掉了关键文件，或者拉进了太多无关文件导致注意力分散。

不同规模项目的选型建议

不是所有项目都需要知识图谱。根据项目规模选择合适的索引策略，能避免过度投入：

小型项目（< 1 万行代码）：直接用 Repomix 之类的上下文打包工具就够了。把整个仓库压成一个 XML 文件，一次性塞进 Agent 的上下文窗口。零配置，零维护，适合周末项目和原型验证。

中型项目（1-10 万行代码）：用 AST 感知分块 + 向量检索。Cursor 的 @codebase 或者开源的 claude-context 都能胜任。关键是按函数边界切分，保留符号表信息。这个阶段的痛点通常是跨文件引用追踪——谁 import 了谁、改了类型定义要去哪些文件改——需要符号索引来补位。

大型项目（> 10 万行代码）：必须上知识图谱。CodeGraph 或 Codebase-Memory 这类工具能提供完整的调用链追踪和影响分析。增量索引和图一致性是这个阶段的核心挑战——项目每天都在变，索引必须跟上节奏，否则就会出现前面说的「同步漂移」问题。

Monorepo：这是最复杂的场景。多个应用共享包，边界模糊，依赖关系错综复杂。除了知识图谱，还需要额外的目录边界标注——哪些目录是 server 端、哪些是 client 端、哪些是共享包、哪些是测试工具。Agent 在不了解这些边界的情况下，很容易在 server 代码里引用 client 专属的依赖，或者反过来。

落地检查清单

如果你要为自己的项目搭建代码索引，这是我总结的检查清单：

基础层

• 确认项目语言是否在 Tree-sitter 支持列表中（目前覆盖 66 种语言）
• 配置忽略规则：node_modules、dist、.next、coverage、lock 文件不进索引
• 选择分块策略：优先按函数/类边界切分，避免按固定行数硬切
• 为每个 chunk 保留文件路径和行号元数据，方便 Agent 回溯定位

结构层

• 构建符号表：提取所有函数、类、接口、枚举的定义位置
• 解析 import/export 关系：跨文件引用必须进入索引
• 构建调用图：至少覆盖项目内部函数调用关系
• 标注测试文件与源码的映射关系——Agent 改完代码要知道跑哪些测试

语义层

• 选择 embedding 方案：安全敏感项目用本地 Ollama，其他场景可用云端 API
• 考虑混合检索：BM25 关键词 + 稠密向量，互补精确匹配和语义模糊匹配
• 为 chunk 附加上下文标签：模块名、业务域、最近 git 修改时间

工程层

• 实现增量索引：用文件哈希检测变更，只重建受影响的 chunk
• 索引大小监控：定期检查索引覆盖率和过期比例
• 设置上下文预算：按任务类型限制注入 Agent 的 token 数量，避免上下文爆炸
• 可解释性：要求 Agent 在操作前说明选择了哪些文件、为什么选择

验证层

• 索引不能替代 typecheck——每次改动后必须跑类型检查
• 索引不能替代测试——相关测试用例必须通过
• 索引不能替代构建——确保 build 成功
• 定期对比索引结果和人工判断，校准检索质量

写在最后

代码索引这件事，本质上是在回答一个问题：Agent 应该看到什么？

看得太少，它会漏掉关键的调用链和项目约束，改出「局部正确、全局翻车」的代码。看得太多，上下文窗口被无关文件塞满，注意力分散，反而找不到重点。

2026 年的工具生态已经给出了方向：本地优先的知识图谱 + AST 感知分块 + 混合检索，是目前兼顾精度、性能和隐私的最优组合。但没有任何一种索引方案能一劳永逸——你需要持续校准、监控、验证，让索引质量和项目演化保持同步。

Agent 的输出质量，上限取决于它读到的上下文。索引就是这个上限的守门人。

参考资料

1. Walker, R. (2026). Code Intelligence Tools for AI Agents Compared. Ry Walker Research.
2. Vogel, M., Meyer-Eschenbach, F., Kohler, S., Grünewald, E., & Balzer, F. (2026). Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP. arXiv:2603.27277v1.
3. Cursor. (2026). Securely Indexing Large Codebases. Cursor Blog.
4. Easton, D. (2026). Complete Guide to Cursor Codebase Indexing.
5. ForgeCode. (2025). AI Code Agents: Indexed vs. Non-Indexed Performance.
6. Kilo.ai. (2026). AI Coding Assistants for Large Codebases: Architecture, Evaluation.
7. BuildMVPFast. (2026). Repository Intelligence in AI Coding Tools (2026).
8. MindStudio. (2026). Coding Agents Skipped RAG — RAG Still Wins on Large Docs.