主题
Claude Code 本地代码索引方向调研
本调研聚焦 Claude Code（含 Codex / Cursor / Windsurf 等 AI CLI/IDE）"读不懂大代码库" 这一核心痛点，系统梳理 5 个具有代表性的开源代码索引项目，从背景、原理、用法到选型给出完整说明。
1. 调研背景
当下主流的 AI 编码助手（Claude Code、Codex、Cursor、Windsurf、Kiro 等）在中小项目上表现尚可，但一旦面对真实的中大型仓库（>1k 文件、Monorepo、跨语言、超大 C++/Chromium 级），就会暴露同一个核心问题：
AI 不"理解"代码库结构，每次任务都靠 grep + read 反复重读，token 消耗与延迟双双爆炸。
具体表现为：
| 痛点 | 典型现象 |
|---|---|
| 盲读 | AI 反复 Glob + Grep + Read 同一批文件，单轮对话烧掉 10 万+ token |
| 猜结构 | 没有调用图，AI 只能从 README.md 或目录名猜架构，理解错调用链 |
| 遗漏依赖 | 改一个函数，不知道下游谁调用，回归缺测试覆盖 |
| 慢 | Chromium 级仓库 Grep 单次扫描就要 137 秒，工具调用排队 |
| 重复劳动 | 每次新对话从零开始，没有"项目记忆" |
业界给出的解决思路高度一致： 为 AI Agent 在本地建一份"持久化代码索引"，按需精准喂给模型，而不是让模型自己每次去找。
但实现路线分成了几大流派：
本地代码索引
│
┌──────────┬───────────┬───┴────────┬─────────────┬───────────┐
▼ ▼ ▼ ▼ ▼ ▼
LSP 派 知识图谱派 向量 RAG 派 混合检索派 AST 结构派 Grep 加速派
│ │ │ │ │ │
Serena code-review- Claude Semble ast-grep BitFun
(24K⭐) graph Context code-graph- MCP (flashgrep)
GitNexus (Zilliz 9K) rag-mcp Probe Probe
(兼通用搜索)本调研主线对应整理了你提供的 5 个项目（02–06），覆盖图谱派、混合检索派、Grep 加速派的代表实现。
补遗章节（08）补全了业内另外 10+ 个主流方案，特别是 Serena（24K stars，LSP 派王者） 和 Claude Context（Zilliz，9K stars，向量 RAG 派代表）。
2. 五大项目速览
| 项目 | 流派 | 核心定位 | 技术栈 | 索引产物 | 集成方式 |
|---|---|---|---|---|---|
| code-review-graph | 知识图谱 | 为代码评审/日常编码生成 AST 图，按"爆炸半径"喂上下文 | Python + Tree-sitter + SQLite | .code-review-graph/*.sqlite | MCP (28 工具) + CLI + Hooks |
| GitNexus | 知识图谱 | 在浏览器/本地把 codebase 变成可查询的图谱 + 7 个 Skills | Node.js + Tree-sitter + KuzuDB + transformers.js | .gitnexus/ (KuzuDB) | MCP (7 工具) + Hooks + Skills + Web UI |
| code-graph-rag-mcp | 图谱 + RAG | 给 Codex/Claude Code 加"代码语义索引"，11 种语言 | Node.js + Tree-sitter + sqlite-vec + 多嵌入提供方 | ./.code-graph-rag/vectors.db | MCP (26 方法) |
| Semble | 语义+词法混合 | 为 AI Agent 打造极速代码搜索引擎（98% token 节省） | Python + Model2Vec + BM25 + RRF | 内存/单文件索引 | MCP + CLI + Python API |
| BitFun (flashgrep) | Grep 替代 | 用 trigram 倒排索引把 grep 提速 36.1 倍 | Rust + TypeScript | mmap trigram 索引 | 内置于 BitFun IDE / 命令行 |
详细对比矩阵请见 07-comparison-and-selection.md。
3. 五大项目核心指标对比
3.1 性能与 Token 效率
| 项目 | 索引速度 | 查询延迟 | Token 节省 | 实测基准 |
|---|---|---|---|---|
| code-review-graph | 500 文件 ~10s；2,900 文件增量 <2s | 0.4–1.5ms | 8.2× 平均（评审任务 6.8×，日常编码 49×） | 6 个真实开源仓库 |
| GitNexus | 中等仓库分钟级 | ~ms（KuzuDB 原生） | 未公开统一指标，按 cluster 命中给出最小集 | 多个真实项目案例 |
| code-graph-rag-mcp | 100+ 文件/秒（Tree-sitter） | <100ms | — | 5.5× faster than Native Claude tools（55.84s → <10s） |
| Semble | ~250ms / 仓库 | ~1.5ms | ~98% 减少 token（45,692 → 566） | NDCG@10 = 0.854 |
| BitFun (flashgrep) | Chromium 79s 全量索引 | 子秒级 | — | 36.1× faster than Claude Code Grep（137.2s → 7.82s） |
3.2 语言支持
| 项目 | 语言数 | 备注 |
|---|---|---|
| code-review-graph | 23+ | 含 Jupyter (.ipynb)、Databricks notebook、Zig、PowerShell、Julia、Svelte、Perl XS |
| GitNexus | 11 | TS/JS/Python/Java/C/C++/C#/Go/Rust/PHP/Swift |
| code-graph-rag-mcp | 11 | 含 Python/TS/JS/C/C++/C#/Rust/Go/Java/Kotlin/VBA |
| Semble | 通用 | 基于 Tree-sitter 通用代码 chunk |
| BitFun | 全语言（按字节） | trigram 与语言无关，按字节流索引 |
3.3 集成与生态
| 项目 | MCP 支持 | Claude Code | Codex | Cursor | 其他 |
|---|---|---|---|---|---|
| code-review-graph | ✅ 28 工具 + 5 prompt 模板 | ✅ | ✅ | ✅ | Windsurf / Zed / Continue / OpenCode / Antigravity / Qwen / Qoder / Kiro |
| GitNexus | ✅ 7 工具 + Resources | ✅（+ 7 Skills + hooks） | ✅ | ✅ | Windsurf / OpenCode |
| code-graph-rag-mcp | ✅ 26 方法 | ✅ | ✅ | ✅ | Gemini CLI / Claude Desktop |
| Semble | ✅ | ✅（claude mcp add semble） | ✅ | ✅ | OpenCode、Python/CLI 直接使用 |
| BitFun | ✅（BitFun 内置） | 间接（命令行 flashgrep 可被任意 AI 调用） | ✅（同上） | ✅ | 自家 ADE/IDE |
4. 三大技术流派归纳
4.1 知识图谱派（Graph-first）
代表：code-review-graph、GitNexus
核心思想：
- Tree-sitter 解析所有源码 → 抽取节点（函数/类/导入）和边（调用/继承/测试）
- 落到本地图数据库（SQLite / KuzuDB）
- 通过 MCP 暴露查询接口：邻居、爆炸半径、社区、关键路径
- AI 每次只读"图上找到的最小集"，而不是整个文件
优势：
- 结构精准，能回答"谁调用 X？"、"改 X 会影响哪些测试？"
- 适合代码评审、影响分析、安全重构
- Token 效率最高（理论上只读真正相关的几十行）
劣势：
- 仅靠图无法做"按语义找"（如"加密用户密码的地方"）
- 跨文件动态调用、反射、DSL 难以建图
- 小变更（单文件）反而比直接读源更贵（结构元数据开销）
4.2 语义/词法混合检索派（Hybrid Retrieval）
代表：Semble、code-graph-rag-mcp、Claude Context (Zilliz)
核心思想：
- 用 AST 感知方式把代码切成 chunk（函数/类粒度）
- 双路检索：
- 语义 = 静态/轻量嵌入（Model2Vec / sentence-transformers / OpenAI 兼容端点）
- 词法 = BM25 / 倒排索引
- RRF（Reciprocal Rank Fusion）融合得分
- 代码感知重排：定义优先、文件聚合、噪声惩罚
优势：
- 既能找名字，又能按意图找
- Semble 这种"静态 Model2Vec"路线 CPU 上极快（250ms 建库，1.5ms 查询）
- 不依赖外部 GPU / API Key
劣势：
- 没有调用关系图，"改这个谁受影响"需另查
- 嵌入质量决定上限，纯静态嵌入对长上下文略弱
4.3 索引加速派（Grep-replacement）
代表：BitFun 的 flashgrep
核心思想：
- 把每个文件切成所有重叠的 3-byte trigram
- 建立 trigram → 文件列表（posting list）的倒排索引
- 查询时用模式中的 trigram 取交集 → 缩小到候选文件 → 精确匹配
- mmap 磁盘格式 + 并行搜索
优势：
- 完全语言无关，对二进制/超大仓库也能用
- 与 grep 行为兼容，调用方式不变，AI 不用重新学
- 在 Chromium 这种 6000 万行级仓库上实现"亚秒级搜索"
劣势：
- 只是"更快的 grep"，不解决"AI 不懂结构"的核心问题
- 索引占用磁盘较大（约源码体积 58%）
5. 阅读建议
按需选择章节：
- 零基础小白 / 概念不熟 → 先看 09 基础概念扫盲
- 想快速选型 → 直接看 07-comparison-and-selection.md
- 想理解技术原理 → 按 02 → 03 → 04 → 05 → 06 顺序阅读
- 想了解业内全貌 → 加读 08-other-solutions.md（含 Serena、Claude Context 等 10+ 项目）
- Claude Code 用户首选 → 02 code-review-graph 或 03 GitNexus
- Codex 用户首选 → 04 code-graph-rag-mcp 或 05 Semble
- 超大仓库（Monorepo/C++/Chromium） → 06 BitFun flashgrep
6. 文档目录
| # | 文档 | 内容 |
|---|---|---|
| 00 | README.md | 本文，调研总览 |
| 01 | 01-background-and-overview.md | 背景与三大技术流派详解 |
| 02 | 02-code-review-graph.md | code-review-graph 完整指南 |
| 03 | 03-gitnexus.md | GitNexus 完整指南 |
| 04 | 04-code-graph-rag-mcp.md | 给 Codex 加代码语义索引 |
| 05 | 05-semble.md | Semble 极速代码搜索引擎 |
| 06 | 06-bitfun-flashgrep.md | BitFun flashgrep 加速实战 |
| 07 | 07-comparison-and-selection.md | 5 项目对比矩阵 + 选型建议 |
| 08 | 08-other-solutions.md | 业内其他主流方案补遗（Serena / Claude Context / Probe / ast-grep / Cody 等 10+ 项目） |
| 09 | 09-concepts-for-beginners.md | 基础概念扫盲：从 0 到 1 看懂 MCP / AST / LSP / 向量嵌入 / RAG / Trigram 等 23 个核心概念，每个配生活化类比 |
7. 参考资料
- code-review-graph (GitHub)
- GitNexus (GitHub)
- code-graph-rag-mcp (GitHub)
- Semble (GitHub)
- BitFun (GitHub)
- 知乎《开源 Claude Code 本地代码知识图谱：code-review-graph 完整上手攻略》
- 知乎《GitNexus 保姆级教程：将代码库索引为知识图谱》
- 知乎《我给 Codex 加了一个代码语义索引》
- 知乎《Semble：专为 AI Agent 打造的极速代码搜索引擎》
- 知乎《超大仓库检索速度超越 Claude Code 36.1 倍：开源项目 BitFun 做对了什么》