花五篇量出了边界，现在需要一张更大的地图
如果你从第 03 篇一路读到这里，那我们一起送走了一个缠了整整五篇的幽灵------Q8。
回顾一下这场漫长的追捕。Q8 是 process payment and create Stripe charge，它的 ground truth 里有个 calculate_order_total（计算订单总价），我们用尽了文本检索的所有招式去抓它：向量基线抓不到，三种 chunking 抓不到，把 called_by 编进 embedding 只推到相似度 0.51 还是抓不到，最后连业界公认的"终极武器"BM25 + 向量混合检索都翻了车------不仅没修好 Q8，还把总分从 0.958 拖到了 0.931。
五篇的结论，最后收束成一句话：
calculate_order_total和"Stripe 支付"的关联，纯粹是结构性 的。它藏在调用图的一条边上（被process_checkout调用），不写在任何函数的文本里。因此任何纯文本方案------向量、BM25、混合------都物理上够不着它。
这句话，是我们花五篇实验换来的、有数字支撑的硬结论。它值钱，但它也只是一块拼图。
因为在追 Q8 的过程中，我们其实顺手量出了三条检索路线各自的势力范围：向量擅长什么、够不着什么；图擅长什么、代价是什么；还有一类查询------"名为 validate_jwt_token 的函数在哪"------根本用不着语义，精确匹配一秒就返回。 这三块势力范围拼在一起，才是代码库检索的完整版图。
所以这一篇，我们换个高度。前五篇是拿着放大镜量单个检索算法的召回率，这一篇要退到卫星视角，画一张系统架构图：向量、图、符号这三路信号，到底该怎么组织成一个真正能用的生产系统。
先给你打个预防针，读之前记在心里：这篇里凡是带具体 Recall 数字的，都是前五篇已经跑实验验证过的结论；凡是讲"该怎么设计系统"的部分，都是从这些结论推导出来的工程设计建议，还没有在完整生产系统上端到端验证过。 我会在关键处反复标注，别把设计建议当成实验结论。
先把三路信号的势力范围划清楚
在动手设计之前，先把前五篇量出来的三块势力范围摆到台面上。这是整篇架构设计的地基，地基里的每一块砖都带着实验编号。
第一路：向量检索------语义相似查询的主场。
这是第 03 篇建立、后续四篇反复验证的基线：AST 函数级分割 + 原始代码 embedding，Recall@5 = 0.958，是所有文本方案里最强的向量基线（已实验验证）。它擅长处理"用自然语言描述功能、去找实现"这类查询------你说"找加密并安全存储密码的函数"，它能命中 hash_password，哪怕你一个字都没提到函数名。
它的边界也被量得很清楚：语义鸿沟填不平（第 06、07 篇）。calculate_order_total 和"Stripe 支付"在真实世界就是两回事，任何 embedding 技巧都拉不近它俩。
第二路：图检索------结构关系查询的主场。
第 05 篇证明了调用图携带的结构信息是向量够不着的正交真相 （已实验验证）：Q8 靠 process_checkout → calculate_order_total 这条调用边被两跳捞回。但第 05 篇也量出了它的代价------朴素 BFS 2 跳扩展会撑爆候选集，把 Q1 原本命中的 verify_password 挤出 top-5，一进一退总分归零。
结论很微妙：方向对，方法糙。 图信号值钱，但"检索后拿它做无脑 BFS 扩展"是错误用法。这个教训直接决定了后面架构里图检索的地位。
第三路：符号检索------精确匹配查询的主场。
这一路前五篇没专门做实验，但它的价值不言自明，也不需要实验证明：当你的查询本身就是一个精确的符号------"名为 validate_jwt_token 的函数定义在哪"、"哪些文件 import 了 redis.Redis"------你要的不是"语义相近"，而是"字面精确命中"。这时候向量是杀鸡用牛刀，还容易被语义近似带偏；一个 grep 或一张函数名→文件→行号的符号表，10 毫秒内精确返回。
把三块势力范围并排放，能看到一个漂亮的事实------它们几乎不重叠：
arduino
查询类型 最擅长的路 举例
──────────────────────────── ─────────── ─────────────────────────
自然语言描述功能，找实现 向量 "找验证 JWT 令牌的函数"
精确符号名 / import 符号 "validate_jwt_token 在哪"
结构关系 / 调用链 图 "谁调用了 createPayment"
──────────────────────────── ─────────── ─────────────────────────第 01 篇建立的"四个知识层次"框架，正好和这个版图对应：语法层（AST/符号）、语义层（向量）、架构层（图），再加上意图层（Git 历史）。生产系统的第一原则，就是承认这四层信号各自独立、缺一不可------不存在一个能通吃四层的"最好的检索方法"。
架构原则一：多路召回，各司其职
第一个原则，也是最反直觉的一个：别再找"那个最好的检索方法"了。
前五篇我们干的就是这件事------不停地问"向量行不行？BM25 行不行？Hybrid 行不行？"，每一次都在赌某一路能通吃所有查询。结果五连败，最后被逼着承认：Q8 这类结构查询，文本路线物理上够不着。
换个思路：不是找一个全能选手，而是让每一路只干它最擅长的活。 向量管语义、图管结构、符号管精确------三路并行召回，各自覆盖自己的势力范围。
用一个类比：这就像医院的分诊台。你不会指望一个全科医生把心脏搭桥、拔牙、验血全包了。你先分诊，骨折的送骨科，牙疼的送牙科，验血的送化验室。每个科室在自己的领域是专家，跨出领域就是外行。 检索也一样------用向量去做精确符号匹配，就像让牙医给你做心脏搭桥，理论上他也认识心脏，但你真的不想让他动手。
这个原则直接来自前五篇的教训：我们已经用五篇的失败，证明了"逼一路信号去干它不擅长的活"的下场。向量被逼着去够 Q8 的结构关系，够了五篇没够着。既然如此，就让图去干这活，让向量回到它的语义主场。
标注： "多路召回"这个架构方向，是从第 05/07 篇的实验结论直接推导出来的设计原则。三路各自的势力范围有实验支撑（向量 0.958、图修好 Q8、符号无需实验），但"三路组合成完整系统后的整体 Recall"还没有端到端实验数据------这是设计建议，不是实验结论。
架构原则二：查询路由，按意图激活对应的路
有了三路召回，马上冒出一个问题：一个查询进来，激活哪几路？
如果不管三七二十一，每次都把三路全跑一遍再融合，不仅慢，还会互相污染------第 07 篇已经血淋淋地演示过了：向量在 Q7 上满分，BM25 却因为"execute"这个高频通用词过度匹配拖到 0.67，RRF 一融合，把好的那路也拉下水了。盲目融合，是让擅长的路被不擅长的路拖累。
所以需要一个查询路由（Query Router）：先判断这个查询是什么类型，再决定激活哪几路。
arduino
查询 "validate_jwt_token 函数在哪里" → 符号路（精确匹配）
查询 "验证 JWT 令牌的函数" → 向量路（语义相似）
查询 "createPayment 调用了哪些函数" → 图路（结构关系）
查询 "支付流程完整链路" → 图路 + 向量路（混合）实现上不必上来就动用 LLM。绝大多数查询意图，靠几条规则就能识别：
- 查询里出现精确的标识符（
snake_case/camelCase的函数名、import的模块名）→ 优先符号路。 - 出现"谁调用了""依赖了什么""调用链""完整流程"这类结构关键词 → 激活图路。
- 剩下的自然语言描述 → 走向量路。
- 复合查询（既有结构意图又有语义描述）→ 多路联合。
规则识别不了的边缘情况，再用一个小模型辅助分类兜底------但这不是必需品，规则能覆盖绝大多数场景。
标注（重要）： 这里的"查询路由"是伪代码级别的设计概念，不是已经实验验证的结果。上面那张"查询 → 路"的映射表是我根据三路势力范围手工设计的路由规则，它符合前五篇的实验直觉，但"路由准确率有多高、误路由的代价多大"这些问题，本系列还没做过实验。请当成设计建议来读。
架构原则三：图检索是一等公民，不是后处理补丁
这是整篇架构里最重要的一个转变，也是对第 05 篇失败的直接修正。
回想第 05 篇为什么翻车：它的流程是先向量检索取 top-3 种子，再从种子出发做 BFS 图扩展 。图遍历是跟在向量后面的一道后处理。这个顺序错了------它把图当成了向量的补丁，导致图扩展进来的"结构相关但查询无关"的函数污染了向量的排序，把 Q1 做砸了。
正确的做法是把图检索升格为和向量并列的一等召回路：
- 图索引和向量索引并行建立，两者都是独立的一等召回入口，谁也不依赖谁。
- 向量路取自己的 top-k；图路独立执行 ------从查询里识别出提到的函数名/模块名，直接走图遍历（沿
CALLS/CALLED_BY边），返回结构上相关的函数。 - 两路结果最后融合 。注意这里的融合不是第 07 篇那种不分场景的 RRF，而是按查询类型加权合并：结构查询里图路权重高，语义查询里向量路权重高。
一张图说清这个转变：
markdown
❌ 第 05 篇（图是后处理补丁）
Query → Vector top-k → BFS 扩展 → 重排
↑ 图在这里，跟在向量后面，污染排序
✅ 生产架构（图是并列的一等公民）
Query ─┬─→ Vector 路 ─┐
└─→ Graph 路 ─┴─→ 按查询类型加权融合 → 结果
两路并行，各自独立召回为什么这么改能解决第 05 篇的问题？因为第 05 篇的病根是"图扩展撑大了向量的候选集，稀释了向量排序"。当图路变成独立的一路、有自己的召回逻辑和触发条件（第 07 篇结尾建议过：只对高置信函数触发、只走 1 跳、按业务规则过滤邻居），它就不会再无差别地往向量的候选池里塞噪声。图路捞回 Q8 的 calculate_order_total，向量路守住 Q1 的 verify_password，两条路各管各的，井水不犯河水。
标注： "图作为一等公民、按查询类型加权融合"是从第 05/07 篇失败中推导出的设计修正方向。第 05 篇"图后处理会污染排序"是已实验验证的失败 ；但"并行一等公民 + 加权融合就能同时守住 Q1 和 Q8"是设计推论，尚未在本系列实验中验证。方向有实验支撑，具体的融合权重和触发条件需要后续实战篇去调。
架构原则四：增量更新，不全量重建
前三个原则解决"怎么查"，第四个原则解决一个更要命的工程现实：代码每天都在变。
前五篇的实验都是在一个静态的 28 函数小数据集上跑的。但真实项目不是标本------每天几十上百个 commit，函数被增删改、签名变化、调用关系重连。如果索引策略是"每次都全量重建"，那对一个几十万行的代码库，光建一次向量索引就要跑几十分钟，图和符号表也得跟着全部重算。开发者改一行代码等十分钟索引，这系统没人会用。
所以第四个原则是：Git diff 驱动的增量更新，绝不全量重建。
具体三条：
1. Git diff 驱动。 一个 commit 进来，先算出它到底改了哪些文件、哪些函数，只重新索引这些变更点。没动的函数，它的 embedding、图节点、符号表项一个字节都不用重算。
2. 变更传播。 这一条容易被忽略，但很关键。函数改动不是孤立的------如果 create_payment_intent 的签名变了，那所有调用它的函数，它们的调用图边也得跟着更新。所以增量更新不只是"重算改动的函数"，还要沿调用图把变更传播到受影响的邻居。这恰恰是前面把图当一等公民的又一个好处：图结构本身就是变更传播的路径。
3. 版本快照。 支持按 commit hash 查询历史版本------这就接上了第 01 篇的第四层"意图层"。"这个函数三个月前长什么样""这行代码是哪个 commit、为解决什么问题引入的"，这类查询要的不是当前代码，而是代码的演化历史，答案藏在 Git 里。
sql
Code Change (git commit)
│
┌─────▼──────┐
│ Git Diff │ ← 只找出变更文件 / 函数
└─────┬──────┘
│
┌─────▼──────┐
│ AST Parser │ ← 只重新解析变更文件
└──┬──────┬──┘
│ │
┌───▼──┐ ┌─▼──────┐
│Embed │ │ Graph │ ← 两路并行增量更新
│Update│ │ Update │ Graph 还负责把变更
└──────┘ └────────┘ 沿调用边传播给邻居标注： 增量更新是纯设计建议，本系列前五篇全部在静态数据集上实验，没有跑过任何增量更新的实验。但这个方向没什么争议------它是任何生产级索引系统的标配，也是第 01 篇就点明的"动态性是最大挑战"的直接回应。
完整系统架构图
把四个原则拼起来，就是一张完整的系统架构。分两个视角看：查询时 发生什么，索引时发生什么。
查询流程（在线，用户发起查询时）：
objectivec
Query
│
┌──────▼──────┐
│ Query Router│ ← 识别查询意图（规则为主）
└──┬───┬───┬──┘
│ │ │
┌───────▼┐ ┌▼──────┐ ┌▼────────┐
│ Vector │ │ Graph │ │ Symbol │
│ Index │ │ Index │ │ Index │
│(AST + │ │(CALLS/│ │(grep / │
│embedding│ │CALLED_│ │AST 符号 │
│) │ │BY) │ │表) │
└───┬────┘ └──┬────┘ └────┬────┘
│ │ │
┌───▼─────────▼───────────▼────┐
│ Result Merger │
│ （按查询类型加权合并，去重） │
└──────────────┬────────────────┘
│
Top-k Results三路索引并行召回（由 Router 决定激活哪几路），最后 Result Merger 按查询类型加权合并、去重，产出最终结果。注意 Merger 不是无脑 RRF------它知道这是个结构查询还是语义查询，据此调整各路权重。这正是第 07 篇教给我们的：融合必须分场景，否则擅长的路会被不擅长的路拖垮。
索引流程（离线，Git hook 触发）：
就是上一节那张 Git diff 驱动的增量更新图。三路索引在 commit 时并行增量更新，图索引额外负责变更传播。
两张图合起来，就是这套架构的全貌：查询时三路并行召回按意图加权融合，索引时 Git diff 驱动三路并行增量更新。 每一处设计，都能在前五篇里找到对应的实验教训。
各层索引的实现复杂度对比
设计归设计，落地时你得知道每一路的工程成本。下面这张表，把三路（外加意图层）的构建成本、更新成本、查询延迟、适用场景摊开对比。
| 索引类型 | 构建成本 | 更新成本 | 查询延迟 | 适用查询 |
|---|---|---|---|---|
| 符号索引（grep / AST 符号表） | 低（秒级） | 极低（增量） | < 10ms | 精确符号查询 |
| 向量索引（AST + embedding） | 中（分钟级） | 中（仅变更函数） | ~100ms | 语义查询 |
| 调用图索引（AST 解析） | 低（秒级） | 低（仅变更文件） | < 50ms | 结构关系查询 |
| Git 历史索引 | 高（首次全量） | 低（增量 commit） | 变化 | 意图 / 历史查询 |
几个值得留意的点：
- 符号索引是性价比之王。 秒级构建、10 毫秒查询，成本几乎可以忽略，却能干净利落地覆盖一整类精确查询。任何系统都应该第一个上它。
- 向量索引是最贵的一路。 embedding 要跑模型，构建按分钟计，查询延迟也最高（~100ms）。这也是为什么增量更新对它最关键------你绝不想每次 commit 都重跑全量 embedding。
- 调用图索引出乎意料地便宜。 它就是 AST 解析加一张边表，秒级就能建好，查询也快。第 05 篇早就证明了它的价值，而它的成本低到没有任何理由不上。图检索被冷落，从来不是因为它贵，而是因为大家没想清楚怎么用它（第 05 篇的教训）。
- Git 历史索引首次最贵。 全量扫一遍 commit 历史不便宜，但之后每个新 commit 都是增量，边际成本很低。
标注： 表里的成本和延迟是量级估算（秒级/分钟级/毫秒级），来自前五篇 demo 的实际运行体感和常规工程经验，不是在生产规模代码库上的精确基准测试。用它来判断相对优先级（先上便宜的符号和图，再上贵的向量），别拿它当 SLA。
实现路径：从小到大，分三阶段落地
架构画得再漂亮，一口气全上也会噎死。正确的姿势是分阶段落地，每个阶段都能独立交付价值，跑通了再进下一阶段。
Phase 1：向量 + 符号（最小可用系统）
先上最便宜、最没争议的两路：
- 符号索引：ripgrep + 一张 AST 符号表（函数名 → 文件 → 行号的字典）。秒级构建，覆盖所有精确查询。
- 向量索引：AST 函数级分割 + 原始代码 embedding。这是第 03 篇验证过的最强向量基线（Recall@5 = 0.958，已实验验证），直接照搬。
- 查询路由：先用最简单的规则------查询里有精确标识符走符号，否则走向量。
这一阶段就能覆盖"精确符号查询"和"语义描述查询"两大类，是一个立刻能用的最小系统。别小看它------绝大多数日常代码检索都落在这两类里。
Phase 2：加入调用图（补上结构查询）
Phase 1 跑顺了，再补第三路：
- 调用图索引：AST 解析建
CALLS/CALLED_BY边表。成本低（秒级），价值高（第 05 篇验证能修 Q8）。 - 图路作为独立的一等召回路接入------从查询识别函数名，独立走图遍历，绝不做第 05 篇那种"跟在向量后面 BFS"的后处理。
- 升级查询路由：识别"谁调用了""调用链"这类结构关键词，激活图路。
- 升级 Result Merger：从"单路直出"改成"按查询类型加权融合"。
这一阶段补上了 Q8 那类结构查询------也就是文本路线物理上够不着的那块版图。
Phase 3：加入 Git 历史 + 增量更新（生产化）
前两阶段是"能查得准"，这一阶段是"能扛得住生产"：
- Git 历史索引：接上第 01 篇的意图层，支持"这行代码为什么这么写""三个月前的版本"这类查询。
- 增量更新：把三路索引的构建全部改造成 Git diff 驱动。这是从"demo"到"生产"的关键一跃------没有增量更新，前面的架构在真实项目上跑不起来。
- 变更传播：函数签名变了，沿调用图更新受影响邻居的边。
分阶段的意义在于：每一阶段都是一个能独立上线、独立创造价值的完整系统。 Phase 1 就能解决大部分检索需求；Phase 2 补上结构盲区；Phase 3 让它能在真实项目的日常演化中活下去。你不必等三阶段全做完才交付------恰恰相反，你应该在 Phase 1 上线后收集真实查询，用它们来指导 Phase 2、3 的优先级。
工具选型建议
最后落到具体的螺丝钉。这部分是工程惯例的选型建议，不涉及实验结论。
向量存储： pgvector（PostgreSQL 插件）或 Qdrant。选它们的关键理由是支持元数据过滤------你能在向量检索时附加"只在 payment 模块""只在这几个文件里"这类过滤条件，这对代码检索极其有用（很多查询天然带模块范围）。
图存储：不需要 Neo4j。 这一点要特别强调，因为一说"知识图谱"很多人条件反射就要上图数据库。本系列所有 demo 的调用图，都是一个 Python dict（{函数名: [被调用的函数]}）存在内存里、序列化到文件，完全够用（第 05 篇已验证）。大型项目如果内存扛不住，用 NetworkX 或干脆拿 SQLite 存一张边表，也远比 Neo4j 轻。代码调用图的规模，撑不起一个专用图数据库的运维成本。
符号索引： ripgrep（15.1.0 版本支持 PCRE2 + JIT，够快）负责全文精确匹配，再加一张 AST 解析出来的符号表（函数名 → 文件 → 行号）负责定义级查询。两者配合覆盖所有精确符号需求。
增量更新触发： Git pre-push hook，或者 CI/CD pipeline 里加一个索引更新步骤。前者本地即时更新，后者集中式、适合团队共享索引。
查询路由实现： 规则为主（关键词识别 + 标识符模式匹配），LLM 辅助为辅（且非必需）。别一上来就上 LLM 分类------规则能覆盖绝大多数，还快、还免费、还可解释。
一个现成的落地案例：codebase-memory-mcp
讲了这么多设计，你可能想问：这套架构有没有已经跑起来的东西？有。
第 02 篇介绍过的 codebase-memory-mcp 这个 MCP Server，对照本篇的架构设计，它基本就是一个完整的落地案例：
- 它已经实现了向量检索 + 调用图 + 符号索引三路召回------正是本篇原则一的多路召回。
- 通过 MCP 协议直接暴露给 Claude Code 使用------你在 Claude Code 里可以直接调它的
search_graph（符号/语义搜索）、trace_path（调用链追踪）、query_graph（图查询）等工具。 - 它把三路信号组织成一个统一的知识图谱接口，正是本篇"三路组合成一个系统"的思路。
换句话说，本篇画的架构图不是纸上谈兵------它有一个已经能用、已经接进 Claude Code 工作流的实现。下一篇实战篇，我们就会拿 codebase-memory-mcp 在一个真实项目上做端到端演示，看这套多路召回的架构在真实代码库里到底表现如何------那时候，前五篇积累的所有实验直觉，终于要在真实项目上接受检验了。
总结
- 五篇实验量出了三路信号的势力范围，它们几乎不重叠。 向量管语义相似查询（0.958，已验证），图管结构关系查询（修好 Q8，已验证），符号管精确匹配查询（无需实验）。第一原则就是承认没有通吃四层的"最好方法"。
- 原则一：多路召回，各司其职。 别再找全能选手，让每一路只干它最擅长的活------这是从五篇"逼一路信号通吃"连续失败中推导出的设计方向。
- 原则二：查询路由，按意图激活对应的路。 精确标识符走符号、结构关键词走图、自然语言走向量，规则为主 LLM 为辅。（伪代码级设计概念，未实验验证。）
- 原则三：图检索是一等公民，不是后处理补丁。 直接修正第 05 篇的失败------图和向量并行独立召回、按查询类型加权融合，而不是让图跟在向量后面做 BFS 污染排序。（方向有实验支撑，融合细节待实战验证。）
- 原则四：Git diff 驱动增量更新，绝不全量重建。 只重算变更函数、沿调用图传播变更、支持 commit 版本快照接入意图层。（纯设计建议，回应第 01 篇"动态性是最大挑战"。）
- 分三阶段落地，每阶段独立交付价值。 Phase 1 向量+符号（最小可用）→ Phase 2 加调用图（补结构盲区）→ Phase 3 加 Git 历史+增量更新（生产化）。
- 工具选型： pgvector/Qdrant 存向量（要元数据过滤），图不用 Neo4j（Python dict / SQLite 边表足矣），ripgrep + AST 符号表做精确匹配，Git hook 或 CI 触发增量更新。
codebase-memory-mcp是这套架构的现成落地案例，已实现三路召回并接入 Claude Code。下一篇用它做真实项目的端到端实战演示。
从第 03 篇的一个向量基线，到这一篇的三路召回架构，我们完成了从"检索算法"到"系统架构"的视角跃迁。Q8 的故事教会我们的那句话，正是这套架构的地基：
有些关联天生不在文本里------所以我们需要的从来不是更聪明的一路，而是各司其职的多路。
参考资料
- 本系列 codebase-memory-mcp 工具介绍：见本系列第 02 篇
- 四个知识层次框架：见本系列第 01 篇
- 图检索双刃剑实验：见本系列第 05 篇
- 文本路线边界实验：见本系列第 07 篇
欢迎访问 PrimeSkills ------ 一个精心策划的 AI Agent 与技能市场，所有内容均经过真实企业级工作流验证。没有噱头，只有真正有效的东西。
更多实用知识和有趣产品，欢迎访问我的个人主页