代码不是文档
文档知识库的检索逻辑：把文档切成 chunk，向量化，问题来了找相似 chunk，生成答案。
代码库可以用同样的方法，但会漏掉大量信息。"找到所有调用 parseInput() 的地方"这个问题，向量检索给不了可靠答案：相似度搜索找不到调用关系，只能找到语义相近的代码片段。"修改 parseInput() 会影响哪些测试"需要完整的调用图，向量检索根本无法回答。
代码库与文档库的三个本质区别：
1. 结构性更强
文档：段落之间的关系是顺序和引用
代码：函数调用函数，类继承类，模块导入模块
这些关系不在文本里，在运行时语义里
2. 语义层次复杂
同一个业务概念分散在：
- 接口定义（interface/abstract class）
- 具体实现（implementation）
- 单元测试（test_xxx.py）
- 内联注释（# 解释为什么）
- 函数签名（参数名传达意图）
向量检索会把这五个层次的碎片混在一起返回
3. 动态性高
文档更新频率：每月/每季
代码更新频率：每天多次
知识库需要增量更新，不能靠全量重建
四个理解层次
代码库的知识有四个层次，每个层次对应不同的查询能力要求：
层次 1：语法层（Syntactic）
代码作为文本的表面结构——变量名、函数签名、类定义、导入语句。
# 语法层可以回答的问题：
"找到所有名字里包含 'Parser' 的类"
"这个文件定义了哪些函数"
"哪些文件导入了 utils 模块"
工具： 正则表达式、符号索引（LSP/ctags）、AST 解析。
层次 2：语义层（Semantic）
函数的意图——它做什么，为什么存在，和其他函数有什么关系。
# 语义层可以回答的问题：
"找到处理用户认证的代码"
"哪个函数负责解析 JSON 配置文件"
"和数据库连接管理相关的所有类"
工具： 代码向量化（CodeBERT/语义 Embedding）+ 注释联合索引。语义层是向量检索的主战场。
层次 3：架构层（Architectural）
模块之间的依赖关系、调用链路、系统边界。
# 架构层可以回答的问题：
"修改 parseInput() 会影响哪些下游调用方"
"这个功能的完整调用链路是什么"
"模块 A 和模块 B 之间有哪些依赖"
工具： 调用图（Call Graph）、依赖图（Dependency Graph）、代码知识图谱。
层次 4：业务意图层（Intent）
代码为什么这样设计——历史决策、权衡取舍、业务背景。
# 意图层可以回答的问题：
"这个奇怪的边界处理是为什么加的"
"为什么选择了这个算法而不是更简单的方案"
"这段代码是为了解决什么 Bug 才加进来的"
工具： Git 历史（commit message + diff）+ Jira/GitHub Issue 关联。
现有技术方案的能力矩阵
方案 语法层 语义层 架构层 意图层
──────────────────────────────────────────────────────
grep / ripgrep ✓ ✗ ✗ ✗
向量化检索（通用） △ ✓ ✗ △
向量化检索（代码专用） △ ✓✓ ✗ △
AST 符号索引 ✓✓ △ △ ✗
调用图 / 依赖图 △ △ ✓✓ ✗
代码知识图谱 ✓✓ ✓ ✓✓ △
Git 历史索引 ✗ △ ✗ ✓✓
混合方案 ✓✓ ✓✓ ✓✓ ✓
✓✓ 擅长 ✓ 能做 △ 有限 ✗ 不支持
没有任何单一方案能覆盖全部四个层次。真正可用的代码库知识库需要混合方案：向量检索处理语义层，图结构处理架构层，Git 历史处理意图层。
四类典型场景
场景 1：Bug 定位
用户问题： "这个 NullPointerException 在 config.parse() 里，相关代码在哪？"
需要： 语义层（找到 config.parse 的实现）+ 架构层（找到调用链，定位 null 来自哪一步）
单纯向量检索的问题： 能找到 config.parse 的实现，但无法自动追溯 null 值的来源调用链。
场景 2：影响分析
用户问题： "我要修改 UserService.getById() 的返回类型，会影响哪些地方？"
需要： 架构层（完整的调用图）
工具要求： 必须有 Call Graph，向量检索完全无法回答这个问题。
场景 3：新人理解模块
用户问题： "认证模块的整体设计是什么，主要有哪些类和它们的职责？"
需要： 语义层（类的意图）+ 架构层（类之间的关系）+ 意图层（为什么这样设计）
理想答案包含： 类列表 + 各类职责 + 关键设计决策（最好能引用 commit 记录）
场景 4：代码审查辅助
用户问题： "这个 PR 修改了 parseInput()，它的测试覆盖是否完整？"
需要： 架构层（TESTS 边：哪些测试覆盖了这个函数）+ 语法层（找到所有测试函数）
代码库知识库的技术谱系
代码库知识体系
│
├── 传统代码搜索
│ ├── grep / ripgrep 精确字符串，最快
│ ├── sourcegraph / zoekt 正则 + 符号索引，企业级
│ └── LSP（语言服务器） 符号定位、跳转定义
│
├── 语义向量检索
│ ├── 通用 Embedding 把代码当文本（有损失）
│ ├── CodeBERT / UniXcoder 代码专用预训练模型
│ └── 代码 + 注释联合索引 混合语义
│
├── 结构化代码理解
│ ├── AST 解析（Tree-sitter） 语法结构提取
│ ├── 调用图（Call Graph） 函数调用关系
│ ├── 依赖图（Import Graph） 模块依赖关系
│ └── 代码知识图谱 统一的图表示
│
├── 历史知识
│ ├── Git Blame 每行代码的修改历史
│ ├── Git Commit 索引 变更意图和原因
│ └── Issue 关联 Bug/需求与代码的映射
│
└── 工具层（暴露给 Agent）
├── MCP Server 标准协议，任意 Host 可用
├── LSP 客户端 IDE 集成
└── 自定义 API 业务系统集成
为什么 codebase-memory-mcp 是本系列的核心参考
codebase-memory-mcp（docs/learn-agent/KB/08_KB/codebase-memory-mcp）是一个专门为代码库知识化设计的 MCP Server，它同时支持：
- 符号检索：基于 AST 的精确符号定位
- 语义检索：向量化语义搜索
- 图查询：调用关系和依赖关系查询
- MCP 协议：标准化暴露，Claude Code 直接可用
这个项目是"混合方案"的一个完整实现，后续系列的工具实测（Article 02）和企业落地（Article 09）都会基于它展开。
总结
- 代码库有四个知识层次：语法层（AST）→ 语义层（向量）→ 架构层（图）→ 意图层（Git 历史）；每层需要不同的工具支撑
- 没有单一最优方案：向量检索处理语义，调用图处理架构，Git 历史处理意图——完整的代码库知识库必须是混合方案
- 代码库的关键挑战是动态性：代码每天都在变，索引策略必须支持增量更新，不能依赖全量重建
欢迎访问 PrimeSkills —— 一个精心策划的 AI Agent 与技能市场，所有内容均经过真实企业级工作流验证。没有噱头，只有真正有效的东西。
更多实用知识和有趣产品，欢迎访问我的个人主页
