FEATURED / AI

给 AI Agent 一张代码地图

用对照实验说明代码知识图谱为什么能帮助 Agent 更快理解大型仓库。

2026-04-29 知识图谱 · 代码理解 · Agent

SOURCE / Cshiyuan/article / 成品/AI深度学习系列/25-给AI-Agent一张代码地图.md

为什么 AI Agent 需要知识图谱

把一个 500 行的业务文件丢给 Claude，让它做重构分析——识别坏味道、给出方案、评估风险。听起来挺合理的任务。

盯着它的 turn 消耗看，画风有点诡异：

阶段	Turn 消耗
读目标文件	1
追 import 依赖	3-5
读 RPC proto	2-3
读 checker/handler 抽象层	2-3
理解调用链上游	2-3

15 轮 turn 预算，全部花在”这段代码在哪、谁调用谁”上，没有余力做分析。这就像新员工入职第一天就被叫去做重构——80% 时间都在问”这段代码在哪里？谁在用它？”。

Agent 15 轮 turn 预算分配对比

问题定位错了。Agent 的瓶颈不是理解代码的能力，而是在有限 turn 内建立全局认知。这个观察并非个例——社区在 2025-2026 年已经达成共识，Agent 失败的根源是 context 管理，不是模型智能。

根本原因一：上下文窗口是漏斗，不是仓库

1M token 听起来很慷慨，但 Microsoft Research 2025 年的研究显示，LLM 的上下文利用率在 100K token 之后跌到约 60%——塞得越满，输出越糟。Chroma 的 “Context Rot” 研究覆盖 GPT-4.1、Claude 4、Gemini 2.5 共 18 个模型，结论一致：token 越多，质量越差，哪怕没到窗口上限。

Morph LLM 的实测更具体：Claude Code 跑一个 35 分钟的任务通常会累积 80K-150K token，就算用 1M 窗口的模型，50K 左右就开始出现 context rot。业界给”把整个 codebase 塞进 context”起了个名字叫 “dump everything” antipattern——按 $15/M token 计，一次全量查询 $15，精准检索 30K token 只要 $0.45，33 倍成本差。

一句话：把 1M token 当成冰箱往里塞菜，Agent 站在冰箱门口翻半天还找不着昨天的剩饭。

根本原因二：向量相似 ≠ 逻辑相连

纯 vector RAG 是当前主流 Agent 的默认检索方案，但它有一个永远过不去的坎：只能找”长得像”的，找不到”逻辑连着”的。

FalkorDB 基于 Diffbot KG-LM Benchmark 的对比给出了最狠的数据：

查询类型	Vector RAG	GraphRAG
“重置密码怎么办”（单跳）	94%	95%
“找出签约人也批准了相关附录的合同”（多跳）	34%	91%
“批准这笔预算的人的下属是谁”（关系链）	28%	89%
10 万+ 互联文档规模	40% 查询直接失败	全部可解

这正好对应代码 Agent 的痛点——“谁调用了调用 X 的函数？“、”这个数据结构有多少消费者？“这类多跳关系查询，Vector RAG 把相关的调用方和被调方分别搜出来，死活拼不到一起。

根本原因三：Agent 需要地图，不是回忆的碎片

Reddit r/ClaudeCode 热帖《Claude Code isn’t getting worse. Your codebase is just getting bigger》里，开发者吐槽：**”代码库从几千行涨到 1 万行以上，CC 没有 1M 上下文，也根本不会去读你所有文件，我试过了”**。

Arize AI 分析一年的生产 Agent 故障后得出一个让人哭笑不得的数据：某位开发者的 session 里 58% 被打上了 “BAD” 标签——Agent 声称任务完成，实际命令还在报错。Anthropic 官方博客《Effective context engineering for AI agents》直接承认：长时间任务里管理 context 是当前最核心的难题。

代码库里跑着的 Agent 不是在”回忆哪个文件见过”，它需要一张”从 A 函数怎么走到 B 服务”的路线图。没有图谱的 Agent 像背包客没带 GPS，每到一个路口都要重新 grep 一遍问路。

这就是代码知识图谱这个东西要解决的问题——预先把”谁调用谁、谁依赖谁、谁和谁相似”都算出来，Agent 拿到就能直接问答。

知识图谱有哪些：2026 年的三条主线

先画张大地图。知识图谱 + AI 这个交叉方向，2025-2026 年明显分化成三条并行主线，每条都有自己的明星项目。

1. GraphRAG（文档问答场景）

让 LLM 在大文档集合上做多跳推理。代表：Microsoft GraphRAG（旗舰，重型）、LightRAG（EMNLP 2025，轻量增量）、HippoRAG 2（ICML 2025，海马体启发的记忆化 RAG）。Neo4j 成了事实标准后端。

2. Agent Memory（长期记忆场景）

让 Agent 把对话、经历沉淀成可检索的图。代表：Zep 的 Graphiti（bi-temporal 时序图追踪事实有效期）、Cognee（Temporal Cognification）、Mem0g（跟 Amazon Neptune 集成）。hybrid（图 + 向量 + BM25）是默认配置。

3. 代码知识图谱（本文焦点）

把代码仓库变成图给 AI Agent 用。这块现在分成了四大流派：

流派	代表工具	核心原理
tree-sitter / AST 派	Aider RepoMap、Graphify、CodeGraphContext	静态解析抽取符号 + 调用关系，本地跑，省 token
纯 embedding 派	Cursor、Windsurf	代码分块 + 向量检索，通用但对结构盲
图数据库派	GitNexus、Greptile	AST → Neo4j/嵌入式图库，关系查询强
混合派	Sourcegraph Cody、Augment Code	embedding + 精确搜索 + 依赖分析，企业级

四派正在向混合收敛——纯 embedding 在大仓库会失灵，纯图在语义查询上弱，两边都在补对方的课。MCP（Model Context Protocol）成了图派工具的默认交付形态。

三条跨界共识

图谱不替代向量，是补位：arXiv 2502.11371 的系统评测下了定论——单跳查询 vector 稳赢，多跳 / 关系 / 跨文档场景 graph 领先，跑 Hybrid 才是正道
静态 KG 死，temporal / incremental 生：LightRAG、HippoRAG 2、Zep 全部支持增量更新和时序感知。世界知识会过期这件事，社区终于认了
学术背书明确：NeurIPS 2025 的 Code Graph Model (CGM) 把仓库代码图结构直接塞进 LLM attention，SWE-bench Lite 43% 解决率，开源模型第一；NAACL 2025 的 CODEXGRAPH 首次系统化”LLM + 代码图谱”范式

大背景讲完。下面拆两个具体项目——GitNexus 和 Graphify，分属”图数据库派”和”tree-sitter + 聚类派”，代码图谱这条线上两个思路完全相反的开源代表。

实际上的使用：两个代表性项目

GitNexus：浏览器内的图索引引擎

查看 GitNexus Web UI 示例

主打 “Zero-Server 代码智能引擎”——所有索引和可视化都在浏览器里跑，不依赖云端。技术栈大致三层：

Parser：AST 抽取代码结构，提取函数、类、调用关系等节点和边
存储：嵌入式图数据库（二进制格式），默认写到 ~/.gitnexus/ 目录
访问：只通过 MCP Server 对外暴露查询 API。Agent 调 gitnexus_search、gitnexus://repos 这类 MCP 工具拿结果

一句话：一切通过工具访问。你用它的 CLI 索引，结果锁在它的数据库里，Agent 必须经 MCP 中介查询。

Graphify：AST + 语义 + 社区聚类

查看 Graphify 项目

走的是完全另一条路——三阶段流水线：

1. AST 提取（确定性、零 token）

用 Tree-sitter 解析源码，支持 21 种语言。Tree-sitter 是增量式 parser 生成器，每种语言都有社区维护的 grammar。解析完映射节点和边：

函数定义 → Function 节点
类定义   → Class 节点
import   → Depends 边
函数调用 → Calls 边

纯规则驱动，不调 LLM——所以”零 token”。

2. LLM 语义抽取（可选）

AST 只看到结构，看不到意图。这一步让 LLM 读每个函数生成语义节点（”这函数做什么”、”属于哪个业务域”），和 AST 节点连起来，形成”代码 + 语义”的双层图。不需要的话可以跳过省钱。

3. Leiden 社区聚类

把密集连接的子图识别成”社区”——类似微信好友圈的概念。用的是 Leiden 算法，比老的 Louvain 算法更稳定。每个社区就是一个”微服务 / 领域模块 / 功能集群”，然后给每个社区自动生成一份 Wiki 文档描述核心节点和入口函数。

输出：graph.json（图结构）+ graph.html（交互可视化）+ wiki/*.md（社区文档）+ GRAPH_REPORT.md（核心节点 Top-N）。全是纯文本，放哪里都能读，任何 Agent 都能直接 Read。

最关键的机制差异在”聚类”这步：Graphify 把大图压缩成可消化的模块，Wiki 是 LLM-friendly 的自然语言摘要，Agent 进来不用自己漫游整张图，先读 Wiki 找对的社区，再查节点。这就是它宣传”71.5x token 压缩”的底层逻辑——读自然语言摘要比啃 JSON 边列表省得多。

经验反馈：我的 A/B/C 实验 + 社区一手反馈

原理讲得再好也要实测。我们做了一个对照实验，外加整理了社区几个月的真实反馈。

A/B/C 对照实验：有图谱到底值不值

从一个多服务项目里挑 5 个不同复杂度的 RPC 接口，给每组 Agent 统一的任务 prompt：

分析这个文件的实现，识别坏味道、给出重构方案、评估风险。输出结构化报告。

三组唯一差异：

A/B/C 三组对照实验设计

模型、prompt、目标文件完全一致。

效率对比

A/B 两组五次实验加总：

指标	A 组（有图谱）	B 组（无图谱）
总工具调用	128 次	152 次（多 19%）
总耗时	1,059 秒	2,043 秒（慢 93%）
Token 消耗	446K	458K

A 组的工具调用少一成，时间只花一半——不是磨洋工省下来的，是不用绕远路。

质量对比：B 组全军覆没

更离谱的是产出质量：

指标	A 组	B 组
结构化异味	31 条（编号列表）	0 条
结构化重构方案	25 个	0 个
产出完整报告	5/5	0/5

B 组 5 个 Agent 没有一个写出分析结论。Agent 还在”这个函数在哪定义”的迷魂阵里转圈，预算已经见底。

C 组：隔离变量

A/B 对照的结论看起来很清晰：”没图谱就不行”。但有个混淆变量——B 组同时缺图谱也缺 turn。B 组的 0 产出，到底是因为缺图谱，还是因为 turn 不够？

C 组就是来拆这个绑定的：没图谱，但解除 turn 限制。

结果有点意外：

指标	A 组	B 组	C 组
产出结构化报告	✅	❌	✅
Bug 命中率（共 4 个已知 Bug）	4/4	0/4	1/4

C 组确实产出了报告——说明 B 组的 0 产出主要是 turn 卡死的。但它的 Bug 命中率只有 1/4——只找到了当前文件里的那个 Bug。另外 3 个 Bug 分布在其他文件里，C 组根本没打开过那些文件。A 组借助图谱的跨服务边精准跳转，全中。

修正后的结论

无图谱 + 足够 turn 也能产出报告
图谱的真正价值 = 把分析范围从”单文件”扩展到”跨服务全局”
在有限 turn 内，图谱同时解决了”加速探索”和”扩大可见性”两个问题

工具驱动 vs 数据驱动

实验证明图谱值得用，回到 GitNexus vs Graphify 的选型。

工具驱动 vs 数据驱动的架构对比

全维度对比：

维度	GitNexus	Graphify
数据格式	嵌入式图数据库（二进制）	JSON + Markdown
存储位置	`~/.gitnexus/`（HOME 目录）	项目内任意目录
Agent 访问	启动 MCP Server	直接 Read 文件
团队共享	LFS + 软链接 + 启动脚本	git pull
索引方式	黑盒	AST（确定性、可审计）
失败模式	静默（MCP 断连无提示）	明确报错
LLM Token	未知	AST 提取零 token，文档生成可选 LLM

GitNexus 把知识锁在自己的工具里，Graphify 把知识变成可流通的数据。GitNexus 不是索引做得差，而是把自己变成了必经之路——给自己加了六道收费站，任何一站塞车整条路瘫痪。一旦 MCP 连接静默失败（这事还真遇到过），你连知道它死了都要过一会儿。

实测一次 Graphify 的构建成本：上千个 Go 文件的多服务项目，生成约 10 万节点、15 万边的图谱，耗时 3 分钟，LLM token 消耗为零（纯 AST）。图谱跟着代码一起进 git，谁 clone 下来都能直接用，零运维成本。

社区反馈：别只听官方宣传

Reddit、Hacker News、GitHub Issues、独立博主复盘几个月信息扒了一遍，真实反馈比宣传复杂得多。

三个最常见的正面评价：

token 账单立刻降一半：CodeGraphContext 实测 20x 压缩（~95%），code-review-graph 在 commit review 场景 6.8x（1928 vs 13205 tokens），独立博主实测”真实跨文件任务”能稳定省 40-55%
tree-sitter 增量更新爽：修改代码后图谱 <2s 重建，比纯 RAG 重嵌入快一个数量级
纯本地、零服务、企业合规友好：SQLite / 文件存储，不外泄代码

三个被反复吐槽的痛点：

超大仓库崩盘：HN 热评”Aider 小项目很香，>5k 文件就完全不可用”。monorepo、生成代码、vendored deps 会把图本身撑爆上下文，必须手写 .aiderignore / .cgcignore 才能用
动态语言 / DI / 反射失真：Python 鸭子类型下”函数签名等于没说”；Java Spring 依赖注入、反射、动态分发 AST 根本追不到，跨文件 CALLS 边大量缺失，反而误导 Agent
冷启动易错、无错误日志：安装失败、空图、静默断连是常态。GitNexus Issue #433 直接指出 7 个主流 Graph RAG 工具全部缺重试/超时/错误可见性——transient failures 默默破坏 Agent 行为

真实 trade-off：

单人 + 中小仓（1k-5k 文件）+ 静态语言（Go / TypeScript / Rust）：几乎稳赚
团队 monorepo / 动态语言 / 生成代码多：初始收益被索引噪声抵消，要花时间调优才能回本
单文件 bug fix 类任务：图的 metadata 可能比原文件还大，反向亏

code-review-graph 作者自己承认这点：**”单文件改动 + 小包场景下，图的收益 <1x，只有多文件跨改才回本”**。

Salvatore Sanfilippo 在 LLM 编程实践博客里直接唱反调：重要场景”provide extensive information… all the code base if possible”——暗示他不信任图压缩。Simon Willison 整个 2025 年几乎没推过任何 repomap 工具，态度冷淡。

一句话总结社区态度：把它当上下文优化工具能显著省钱，但别指望它”理解”你的代码——大仓库、动态语言、DI 场景下，知识图谱仍是脆弱的启发式，不是银弹。