01 - 调研背景与技术概述

本章解释"为什么需要本地代码索引"，并系统梳理当前业界三大主流技术流派的设计哲学与适用边界。

---

1. 问题：AI Coding Agent 在大代码库上的崩溃曲线

1.1 Claude Code / Codex / Cursor 的默认行为

主流 AI 编码助手的默认上下文获取流程是：

用户提问
   ↓
LLM 调用 Glob / Grep / Read 工具
   ↓
返回若干文件片段
   ↓
LLM 再次 Grep / Read（往往多轮）
   ↓
拼出"它认为有用"的上下文 → 回答 / 改代码

这套流程在 <300 文件 的小项目上非常顺手，因为：

• Glob 扫不了多少东西
• Grep 一次能扫完
• Read 几个文件就能凑齐上下文

但当项目大到一定规模，问题逐级放大：

仓库规模	现象
500–1k 文件	Grep/Read 调用变多，单轮 token 飙到 3–5 万
1k–10k 文件	频繁卡在工具调用，模型开始"猜"而非"读"
10k+ 文件（Monorepo）	几乎不可用，每次 Grep 命中几千个结果，模型只能截断盲选
Chromium 级（6000 万行）	单次 Grep 137 秒，AI Agent 直接超时

1.2 三个核心成本

• Token 成本：每次重读源码 = 几万 token，按 Sonnet 4 价格折算单轮可达 0.5–2 美元
• 延迟成本：工具调用串行，单次任务 30 秒到几分钟
• 正确性成本：模型读不全 → 改错代码 / 漏处理调用方 / 回归测试缺失

---

2. 解决思路：把 "AI 重新探索" 换成 "持久化索引"

业界共识：与其让 LLM 每次去找，不如先建一份"代码索引"，让 LLM 一次问到点子上。

这份索引至少要回答 3 类问题：

1. 结构问题：函数 X 在哪里？它调用了谁？谁调用它？继承自谁？
2. 语义问题：哪段代码做"用户认证"？哪里在"加密密码"？
3. 影响问题：改 X 的爆炸半径是什么？哪些测试覆盖了？

围绕这 3 类问题，业界分化出三大技术流派。

---

3. 三大技术流派详解

3.1 知识图谱派（Graph-first）

代表项目：code-review-graph（tirth8205）、GitNexus（abhigyanpatwari）

设计哲学

代码本质上是 图：节点是符号（函数、类、变量），边是关系（调用、继承、引用、测试覆盖）。把这张图建出来、存起来、查得快，就能精准回答结构问题。

技术栈通用模式

源码
 │
 ▼ Tree-sitter（多语言 AST 解析器）
AST
 │
 ▼ 抽取规则（每种语言的 _CLASS_TYPES / _FUNCTION_TYPES / _CALL_TYPES）
节点 + 边
 │
 ▼ 落库
本地图数据库（SQLite / KuzuDB）
 │
 ▼ MCP Server 暴露查询接口
AI Agent 通过 MCP 调用

核心能力

• 邻居查询：callers(X), callees(X), imports(X)
• 爆炸半径（Blast Radius）：从变更点 BFS/DFS 出 N 跳，收集所有可能受影响的节点
• 社区检测（Community）：用 Leiden 等图算法聚类，识别"功能区"
• 中心度（Centrality）：找出枢纽节点（被调用次数最多）和"桥"节点（连接两个社区的关键路径）
• 流（Flow）：从入口函数追踪典型执行路径
• 风险评分：把 git diff 映射到图上，输出"这次改动碰到了哪些热点"

优势

• ✅ 结构问题答得最准
• ✅ 适合 PR Review、重构、影响分析
• ✅ Token 节省最多（理论上只读爆炸半径内的几十个节点）

劣势

• ❌ 无法回答"语义问题"（找意图相关代码）→ 通常要叠加语义检索
• ❌ 跨语言/反射/动态调度建图困难
• ❌ 小改动反而比 naive read 贵（结构元数据开销）
• ❌ 图算法在巨型仓库（10M+ LoC）上仍慢

---

3.2 语义/词法混合检索派（Hybrid Retrieval）

代表项目：Semble（MinishLab）、code-graph-rag-mcp（er77）、Claude Context（Zilliz）

设计哲学

不一定要建完整图，但需要"按意思找"。结合 向量语义检索（找意图） 和 倒排索引（找名字），再用代码感知的规则重排，就能在 Token 极少的前提下给 LLM 最相关的 5–10 个 chunk。

技术栈通用模式

源码
 │
 ▼ Tree-sitter 切分（按函数/类粒度）
chunks
 │
 ├─► 静态嵌入（Model2Vec / sentence-transformers / OpenAI 兼容）
 │       │
 │       ▼
 │   向量库（sqlite-vec / FAISS / 内存）
 │
 └─► 倒排索引（BM25 / lexical）

查询时：
查询 → 双路检索 → RRF 融合 → 代码感知重排 → top-K chunks → 喂给 LLM

关键设计

• AST 感知 chunking：不像普通文档 RAG 按固定长度切，而是沿函数/类边界切，保留完整语义单元
• 静态嵌入：用 Model2Vec 这类"无 Transformer"的轻量嵌入，CPU 跑得起 250ms 索引整个仓库
• 代码感知重排：
  • 标识符匹配优先于内容匹配
  • 定义所在 chunk 优于引用所在 chunk
  • 同一文件多次命中 → 提升该文件排名
  • 测试文件、shim 文件降权
• RRF 融合：避免一路过强压制另一路

优势

• ✅ 极快（CPU 上即可达到生产级延迟）
• ✅ 极省 token（Semble 实测降低 98%）
• ✅ 兼顾"找名字"和"找意图"
• ✅ 零外部依赖（无 GPU / 无 API Key）

劣势

• ❌ 没有结构关系图，"影响分析"较弱
• ❌ 嵌入质量决定上限，纯静态嵌入对超长函数略弱
• ❌ 重排规则需要按语言/团队调优

---

3.3 索引加速派（Grep-replacement）

代表项目：BitFun 的 flashgrep

设计哲学

不动 AI Agent 的"思维流程"，只改它最常用的工具——把 grep 做快 30 倍以上，让现有 Agent 在巨型仓库上能跑起来。

核心技术：Trigram 倒排索引

源码字节流
 │
 ▼ 滑窗切 trigram（每 3 字节一个 token）
"abcdef" → {"abc", "bcd", "cde", "def"}
 │
 ▼ 倒排：trigram → 包含它的文件列表
 │
 ▼ mmap 落盘

查询：

搜索 "fetchRates"
 │
 ▼ 拆 trigram: {"fet", "etc", "tch", "chR", "hRa", "Rat", "ate", "tes"}
 │
 ▼ 取所有 trigram 的 posting list 交集
候选文件集合（往往只剩几十个）
 │
 ▼ 在候选文件里做精确匹配（regex / literal）
最终命中

关键工程

• mmap 索引格式：常驻文件系统缓存，启动即用
• 并行搜索：候选文件并行扫
• 增量更新：文件改动 → 仅重建该文件的 trigram

优势

• ✅ 完全语言无关，对任何文本/二进制都能用
• ✅ 与 grep 行为兼容，AI Agent 调用方式不变
• ✅ 巨型仓库上效果最显著（Chromium 137s → 7.82s）

劣势

• ❌ 只是"快 grep"，不解决"AI 理解结构"
• ❌ 索引占空间（约源码 58%）
• ❌ 不能回答语义类问题
• ❌ 需要预先构建索引（首次 Chromium 79s）

---

4. 三大流派的对比

维度	知识图谱派	混合检索派	Grep 加速派
回答结构问题（谁调用 X）	⭐⭐⭐⭐⭐	⭐⭐	⭐
回答语义问题（认证在哪）	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐
回答影响问题（爆炸半径）	⭐⭐⭐⭐⭐	⭐⭐	⭐
索引速度	中（500 文件 10s）	极快（250ms）	中（Chromium 79s）
查询速度	毫秒级	毫秒级	亚秒级
Token 节省	8.2× 平均	98%	不直接节省
多语言	11–23+	通用	与语言无关
超大仓库适配	中	中	极佳
集成成本	MCP 即可	MCP 即可	工具替换
典型场景	PR Review、重构	语义检索、新人 onboarding	巨型仓库基础检索

---

5. 三派组合：现实最优解

事实上 没有任何单一项目能独占鳌头，最佳实践是组合：

            ┌────────────────────────────┐
            │       AI Coding Agent      │
            │   (Claude Code / Codex)    │
            └──────────────┬─────────────┘
                           │ MCP
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼
   知识图谱             语义检索           Grep 加速
 (GitNexus /          (Semble /         (flashgrep)
  code-review-graph)   code-graph-rag)
        │                  │                  │
        └──────────────────┼──────────────────┘
                           ▼
                      本地代码仓库

典型分工：

• 用户问"认证流程怎么走？" → 走 Semble 找意图
• 用户问"改 validateUser 影响哪些测试？" → 走 code-review-graph 查图
• 用户让 AI 找一个特定字符串/常量 → 走 flashgrep 加速 grep

---

6. 后续章节路径

项目	流派	推荐场景
02 code-review-graph	图谱	PR 评审 / 23 语言 / 与 Claude Code 强集成
03 GitNexus	图谱	浏览器 Web UI / 7 个 Skills / KuzuDB
04 code-graph-rag-mcp	图谱+RAG	给 Codex 加语义索引
05 Semble	语义+词法	最省 token / CPU 上跑
06 BitFun flashgrep	Grep 加速	Chromium 级仓库
07 对比与选型	—	直接看选型决策