代码知识图谱的工作原理

「代码知识图谱」这个词听起来很抽象。实际上它解决的是一个非常具体的问题：当你问 AI「改了这个函数会影响哪里」时，它怎么给出准确答案？

答案不能靠猜，只能靠索引。

图谱里存什么

Manon 的知识图谱索引代码库中每一个可命名的实体及其关系：

• 实体：函数、类、方法、模块、变量、路由、接口
• 关系：调用（CALLS）、被调用（CALLED_BY）、导入（IMPORTS）、继承（INHERITS）、处理（HANDLES）、定义在（DEFINED_IN）

这个图谱是有向的——你可以沿着调用边从任意节点向上（找调用者）或向下（找被调用者）遍历，可配置深度。

以一个实际例子说明：假设你要修改 process_payment() 函数。图谱可以立刻告诉你：这个函数被 checkout_flow()、subscription_renew()、admin_refund() 三个地方调用，而 checkout_flow() 本身又被 12 个路由处理器调用。你在改一个函数，实际上影响的是整个支付链路。

架构：本地解析 + 云端图谱

出于数据安全考虑，代码本身不离开本地：

1. 本地 AST 解析：tree-sitter 在本地解析源文件，提取符号和关系，生成结构化的 AST 数据
2. 增量上传：只上传 AST 元数据（不是源代码），文件哈希检测变更，只同步差异部分
3. 云端构建图谱：MatrixoneGraph 将 AST 数据构建成 NetworkX 有向图 + 向量索引
4. 混合查询：图遍历（结构精确）+ 向量搜索（语义模糊）组合返回结果

为什么需要向量 + 图的混合检索

纯图遍历的问题：你必须知道节点名称才能找到它。如果你在找「处理用户认证的逻辑」但不知道函数叫什么，图遍历无从下手。

纯向量搜索的问题：语义相似不等于结构相关。「处理支付」和「处理退款」语义接近，但在调用图里可能完全分离。向量搜索会返回语义相关的结果，但可能漏掉结构上关键的调用者。

混合检索：自然语言查询 → 向量搜索找到语义最近的节点 → 沿图谱边展开结构关联 → 返回精确的上下文。

四个查询工具

工具	适合场景	解决什么问题
manon_search	探索性搜索、不知道关键词	「找一下处理用户权限的代码」
manon_graph	改代码前影响评估	「改这个函数会影响哪里」
manon_deep_query	跨模块架构理解	「这个项目的认证流程是怎么设计的」
manon_impact	commit 后风险评估	「这次提交的改动风险有多高」

代码健康度：8 个维度

知识图谱另一个重要用途是计算代码健康度评分（0-100）。8 个维度从不同角度衡量代码库的结构质量：

维度	衡量内容	为什么重要
MC 模块耦合度	跨模块依赖比例	耦合越高，改一处动全身
CD 循环依赖	循环依赖数量	循环依赖是架构腐化的典型信号
FI 扇入集中度	高扇入实体比例	过度集中的调用点是单点故障
DC 死代码	零调用者实体比例	死代码增加认知负担，掩盖真实依赖
FS 函数复杂度	超大函数比例	大函数难测试、难复用、难理解
TD 技术债务	TODO/FIXME 密度	显式债务标记的密度
MF 模块碎片化	微型模块 + 深路径比例	过度碎片化的模块增加导航成本
RE 间接层密度	桶式重导出比例	过多间接层使依赖追踪困难

实际效果：基准测试数据

我们在 OpenClaw 项目（2,100 个文件）上做了对比测试，用知识图谱查询 vs. 原生工具（Grep/Glob/Read）：

维度	Manon 图谱	原生工具	差异
完成同等任务耗时	~30 分钟	~8-12 小时	快 16-24 倍
准确率	95%+	60-70%	+30%
每任务工具调用次数	1 次	13.7 次	减少 91%
总 Token 消耗	~19.5K	~350K	节省 94%
质量评分（5 分制）	4.3	3.2	+34%

16-24 倍这个数字来自真实工作场景：理解一个陌生模块的所有调用关系，用 Grep 需要反复搜索、交叉验证，容易漏；用 manon_graph 一次调用返回完整的上下游关系图。

语言支持

专用解析器（深度提取符号、调用、导入、继承、路由）：Python、TypeScript、JavaScript、Java、PHP。

通用解析器（符号 + 导入，tree-sitter 自动下载）：Go、Rust、C/C++、C#、Ruby、Swift、Kotlin、Scala、Lua、R、Elixir、Dart、Haskell、OCaml、Bash、Zig 共 17 种。