一文搞懂大仓库 AI 助手的仓库级上下文索引

问题背景：为什么 AI 助手在大仓库里容易“失忆”

在小型示例项目中，AI 编码助手往往表现得非常聪明：它能一次读懂几个文件，准确补全函数，甚至完成小型重构。但进入几十万行、多模块、多语言的大型仓库后，问题会迅速暴露：它只看到当前文件，却不知道某个类型在其他包中的引用；它修改了函数签名，却遗漏调用方；它根据相似命名猜测框架约定，最终生成看似合理、实际无法编译的代码。

根因并不只是模型能力不足，而是**上下文管理（context-management）**失败。模型不会天然知道整个代码库，IDE 注入的打开文件、光标附近代码和少量检索片段，很难覆盖跨文件修改所需的调用链、类型定义、配置注册点和测试约束。尤其在 monorepo 中，一个公共接口可能跨越多个服务、SDK、示例和测试目录。

因此，面向大仓库适配，不能只依赖“把更多文件塞进 Prompt”。更可靠的方法是建立仓库级上下文索引（repo-index），在开发者提出任务时，通过检索增强找到真正相关的代码、符号和依赖关系，再把证据压缩成模型可使用的上下文。

方案对比：全量塞入、纯向量检索与仓库级索引

常见方案可以分为三类。

第一类是全量上下文方案，即将整个仓库或大量文件直接提供给长上下文模型。它实现简单，但成本高、噪声大。模型在长上下文中仍可能忽略中间内容，而且 CI、构建产物、锁文件和生成代码会稀释关键信息。

第二类是纯向量 RAG，把代码切块后生成 embedding，再按语义相似度召回。它适合自然语言文档和“找相似实现”，但对精确符号、调用关系和配置键不够稳定。例如查询 UserService.create 时，向量检索可能召回大量包含 create 的 CRUD 片段，却漏掉间接调用方。

第三类是仓库级上下文索引，将代码切块、符号表、导入导出关系、文件路径、文档和 Git 历史组合成混合索引。查询时先做实体识别和调用链扩展，再结合 BM25、向量检索与图关系重排，最后生成结构化上下文。它的工程复杂度更高，但更适合跨文件重构和大仓库适配。

实操步骤：构建一个轻量级 repo-index

下面示例用 Python 演示核心链路：遍历仓库、跳过无关文件、抽取符号关键词、建立倒排索引，并根据任务查询召回相关文件。生产环境可以把 BM25 替换为 OpenSearch，把向量接入 embedding 服务，把符号关系替换为 tree-sitter、LSP 或 SCIP/LSIF 数据。

# pip install rank-bm25
# python repo_index.py /path/to/repo "把 UserService.create 改成批量创建"
import os
import re
import json
import math
from rank_bm25 import BM25Okapi

SKIP_DIRS = {".git", "node_modules", "dist", "build", ".next", "coverage", "vendor"}
INCLUDE_EXT = {".py", ".ts", ".tsx", ".js", ".go", ".java", ".md", ".yaml", ".yml"}

def iter_files(root: str):
    """遍历仓库，跳过依赖目录、构建产物和超大文件。"""
    for base, dirs, files in os.walk(root):
        dirs[:] = [d for d in dirs if d not in SKIP_DIRS and not d.startswith(".")]
        for name in files:
            path = os.path.join(base, name)
            ext = os.path.splitext(name)[1]
            if ext not in INCLUDE_EXT:
                continue
            if os.path.getsize(path) > 300_000:
                continue
            yield path

def tokenize(code: str):
    """同时保留英文词、驼峰词和蛇形词，提升符号检索召回。"""
    tokens = re.findall(r"[A-Za-z_][A-Za-z0-9_]+", code.lower())
    expanded = []
    for token in tokens:
        expanded.append(token)
        expanded.extend(re.findall(r"[a-z]+|[0-9]+", token))
    return [t for t in expanded if len(t) > 1]

def extract_symbols(code: str, path: str):
    """轻量抽取函数、类、接口和导出符号；生产中建议改用 LSP。"""
    patterns = [
        r"\bclass\s+([A-Za-z_][A-Za-z0-9_]*)",
        r"\b(?:def|func|function)\s+([A-Za-z_][A-Za-z0-9_]*)",
        r"\bexport\s+(?:async\s+)?(?:function|const|class)\s+([A-Za-z_][A-Za-z0-9_]*)",
        r"\binterface\s+([A-Za-z_][A-Za-z0-9_]*)",
    ]
    symbols = []
    for pattern in patterns:
        symbols.extend(re.findall(pattern, code))
    # 路径也是强信号，例如 services/user_service.py
    symbols.extend(re.split(r"[/_.\\-]", path))
    return [s.lower() for s in symbols if len(s) > 1]

def build_index(root: str):
    docs, metas = [], []
    for path in iter_files(root):
        try:
            code = open(path, "r", encoding="utf-8", errors="ignore").read()
        except OSError:
            continue
        tokens = tokenize(code) + extract_symbols(code, path)
        docs.append(tokens)
        metas.append({"path": path, "size": len(code)})
    return BM25Okapi(docs), metas

def retrieve(query: str, bm25: BM25Okapi, metas: list[dict], top_k: int = 8):
    scores = bm25.get_scores(tokenize(query))
    ranked = sorted(enumerate(scores), key=lambda x: x[1], reverse=True)[:top_k]
    return [{"path": metas[i]["path"], "score": round(float(score), 3)} for i, score in ranked]

if __name__ == "__main__":
    import sys
    root, query = sys.argv[1], sys.argv[2]
    bm25, metas = build_index(root)
    print(json.dumps(retrieve(query, bm25, metas), ensure_ascii=False, indent=2))

仅有词法召回还不够。跨文件任务应在 BM25 结果上做三类扩展：一是沿 import/export 找到定义文件；二是沿调用关系找到使用方；三是加入同模块测试和迁移文档。可以给不同证据设置权重：定义文件权重最高，直接调用方次之，测试用于约束行为，示例和文档只作为补充。

上下文组装：让模型知道“为什么看这些文件”

检索结果不能简单拼接。建议把上下文分为任务、证据、约束和输出要求四段。每个代码片段都要带路径、符号名和入选原因，否则模型无法判断文件职责，也难以在补丁中保持 import 路径正确。

你正在大型仓库中执行跨文件修改。

任务：{user_task}

已检索证据：
1. 文件：{path}
   角色：{definition | caller | test | config | doc}
   相关符号：{symbol}
   入选原因：{reason}
   代码摘要：{snippet}

修改约束：
- 保持公共 API 向后兼容；如不兼容，必须列出所有调用方和迁移方案。
- 不要修改生成代码、锁文件和无关格式化内容。
- 优先复用现有错误码、日志字段和测试工具。
- 输出补丁前，先列出受影响文件、风险点和验证命令。

输出格式：
1. 影响面分析
2. 逐文件修改计划
3. 可应用的 unified diff
4. 回归测试与回滚方案

上下文预算也要显式管理。假设模型可用 128k token，不代表应全部塞满。较稳妥的比例是系统指令和任务占 10%，检索证据占 45%，当前修改内容占 30%，预留 15% 给推理和输出。对于超长文件，应按符号截取，而不是整文件截断；否则文件尾部的导出函数或测试断言很容易丢失。

检索质量优化：从“相似”走向“可执行影响面”

大仓库适配的关键指标不是召回了多少代码，而是模型能否完成可验证修改。建议在 RAG 侧记录四个信号：查询中的实体是否解析到唯一定义；Top-K 中是否包含直接调用方；受影响测试是否进入上下文；生成补丁能否通过类型检查和目标测试。

重排时可以使用简单但有效的规则：精确符号匹配加分，路径与任务模块一致加分，测试文件与被测文件同路径加分，近期频繁变更且与任务相关的文件少量加分；生成文件、快照文件和第三方依赖默认降权。对于多义词，例如 Client、Manager、Handler，必须结合 import 来源消歧，不能只按名称匹配。

如果仓库已有编译数据库或语言服务，优先使用 LSP 获取“查找引用”“跳转定义”“重命名”等能力。AI 助手可以先调用这些确定性工具，再让 LLM 负责计划和代码生成。确定性工具负责不错漏，大模型负责理解意图，这种分工比纯语义猜测稳定得多。

避坑总结：大仓库上下文检索的高频问题

第一，把构建产物和依赖目录索引进来，导致补丁改到生成代码。 常见现象是模型修改了 dist/index.js、*.pb.go 或 lockfile，下一次构建又覆盖变更。修正方法是在索引阶段默认排除 node_modules、dist、build、生成目录和第三方依赖，并在 Prompt 中明确禁止修改生成文件；确需改生成规则时，只检索生成器模板和 schema。

第二，只按自然语言相似度召回，漏掉精确调用方。 例如任务说“调整用户创建接口的限流逻辑”，向量结果召回登录、注册、管理员创建等相似代码，却没有找到真正引用 UserService.create 的中间件。修正方法是先做符号识别，再用 BM25、正则或 LSP 查定义和引用，把向量检索作为补充，而不是唯一入口。

第三，代码切块过小，丢失类结构和 import 信息。 模型看到一个方法片段，却不知道类继承自哪里、异常类型来自哪个包，于是生成错误 import 或重复定义。修正方法是按 AST 符号切块，保留文件头部 import、类声明、函数签名和必要类型；片段大小可按 token 预算动态调整，但边界必须由语法结构决定。

第四，上下文只给源码不给测试，模型无法判断行为契约。 典型结果是函数签名改对了，却破坏旧调用方依赖的默认值、异常码或分页字段。修正方法是把同模块单元测试、集成测试和契约测试作为高优先级约束注入，并要求模型先说明哪些测试应新增或调整，再输出补丁。

第五，索引长期不更新，检索结果与当前分支漂移。 开发者切换分支后，索引仍指向已删除文件，模型会引用过期符号。修正方法是把索引与 Git 提交、文件 mtime 或语言服务变更挂钩，在分支切换和文件保存后增量更新；无法保证新鲜度时，应在上下文中标注索引时间，并对补丁执行实时类型检查。

结语

大型仓库中的 AI 编码助手，本质上是一个“检索、理解、修改、验证”闭环系统。repo-index 不是简单的向量库，而是代码符号、文件关系、测试约束和任务意图的上下文管理层。只有让正确的定义、调用方和验证证据在正确时间进入 Prompt，AI 才能从局部补全工具升级为可承担跨文件修改的工程伙伴。

免责声明

本工具与文章内容仅用于学习测试场景，优化建议仅供参考，请勿直接用于生产环境，由此产生的风险自行承担。