第八篇讨论了一个问题：

Agent 进入复杂项目时，为什么需要一张地图？

项目地图解决的是：

项目在哪里。

它帮助 Agent 理解：

• 项目结构；
• 模块边界；
• 当前任务位置。

但地图只能告诉 Agent “在哪里”，不能告诉它“如何连接”。

真实项目中的代码还存在：

• 调用关系；
• 数据流；
• 组件依赖。

如果 Agent 只能搜索文件，它知道某个函数在哪里，却不知道：

• 谁调用它；
• 修改会影响什么；
• 哪些模块依赖它。

这就是代码知识图谱要解决的问题：

从项目认知，进一步走向代码关系理解。

---

一、从文件搜索到关系理解

传统方式中，Agent 通常通过：

搜索关键词
    ↓
读取文件
    ↓
推断关系

理解项目。

小项目没有问题。

但项目变大以后，大量 token 会消耗在：

• 寻找代码位置；
• 重建调用关系；
• 理解模块结构。

更合理的方式，是提前建立代码关系：

代码
 ↓
结构分析
 ↓
关系图谱
 ↓
Agent 上下文
 ↓
修改决策

Agent 不再从零探索项目，而是在已有地图上行动。

---

二、代码地图不是文档，而是关系模型

传统文档告诉人：

项目是什么。

代码地图告诉 Agent：

代码之间如何连接。

它帮助 Agent 理解：

• 一个函数在哪里被调用；
• 一个接口影响哪些模块；
• 一个组件依赖哪些资源；
• 一次修改可能影响哪些路径。

因此，代码地图不是 README 的替代品。

它是 Agent 理解项目结构的基础。

---

三、从关键词修改到影响分析

没有代码地图时：

Agent 看到：

修改登录模块。

它可能直接修改相关文件。

但真实关系可能是：

login
 ↓
authentication service
 ↓
user model
 ↓
permission system

修改一个节点，可能影响整个链路。

有了关系地图，Agent 可以提前分析：

• 修改范围；
• 影响路径；
• 潜在风险。

这让 Agent 从：

根据关键词修改

变成：

根据关系修改。

---

四、代码知识图谱不仅用于修改，也用于清理

代码关系理解不仅帮助 Agent 修改代码，也帮助 Agent 判断哪些代码已经失去价值。

传统项目中，删除旧代码很困难。

因为人不知道：

• 这段代码是否还有调用者；
• 这个接口是否仍然被使用；
• 这个测试是否覆盖当前逻辑。

因此，很多项目选择保留旧代码。

但随着 AI 编程普及，残留代码会产生新的问题：

Agent 会把这些历史内容当作当前上下文的一部分。

旧代码、旧测试和过期注释，可能继续影响 Agent 的判断。

代码知识图谱提供了一种关系视角。

它可以帮助发现：

• 没有调用关系的函数；
• 没有引用的组件；
• 已废弃的接口；
• 不再匹配当前结构的测试。

因此，代码图谱不仅帮助 Agent 找到应该修改什么，也帮助 Agent 判断应该删除什么。

---

五、代码地图为什么能减少 token？

LLM 的上下文有限。

传统方式中，Agent 需要通过：

• 搜索文件；
• 阅读代码；
• 分析调用关系；
• 推断依赖路径；

逐渐建立项目认知。

大量 token 消耗在“理解项目”上，而不是解决问题。

这和普通 RAG 有所不同。

普通 RAG 主要解决的是：

从大量资料中找到相关文本。

例如，任务涉及登录逻辑时，RAG 可能检索到：

• login.py
• auth.py
• user_service.py

这些文件看起来相关，但它们之间是什么关系，仍然需要 Agent 自己判断。

在 Agent 工程中，RAG 和 Skill 解决的是两个不同问题：

RAG：
从哪里获得知识

Skill：
怎样完成任务

RAG 负责提供相关资料。

Skill 负责任务流程、工具调用和验收标准。

但无论是 RAG 还是 Skill，都依赖准确的项目上下文。

如果 Agent 只拿到相似文本，却不知道代码之间的关系，它仍然可能改错位置，或者忽略隐藏影响。

代码知识图谱关注的不是相似文本，而是代码关系。

它提前提取：

• 函数关系；
• 调用路径；
• 模块依赖；
• 数据流向。

把隐藏在代码中的关系，转换成结构化上下文。

因此，它给 Agent 的不是更多文本，而是更高密度的项目关系。

普通 RAG：
找到相关内容

代码知识图谱：
找到相关关系

这就是它能够减少 token 的原因。

Agent 不必每次重新阅读大量文件，再从文本中推断关系，而是可以直接围绕相关路径展开分析。

同时，代码知识图谱也能帮助 Agent 识别项目中的历史残留：

• 哪些代码仍然有效；
• 哪些代码已经脱离当前系统；
• 哪些测试已经失去意义。

因此，代码知识图谱不仅提高修改准确性，也帮助项目持续清理和演化。

---

六、从项目地图到 Agent 地图

项目地图解决：

项目是什么。

代码知识图谱解决：

项目如何连接。

未来 Agent 工作流可能是：

项目认知
 ↓
代码关系
 ↓
任务状态
 ↓
执行修改
 ↓
验证反馈
 ↓
经验沉淀

Agent 不再只是读取文件，而是在持续更新的项目模型中工作。

---

本章小结

复杂项目中，Agent 最大的问题不是不会写代码。

而是不知道代码之间的关系。

项目地图告诉 Agent：

项目在哪里。

代码知识图谱告诉 Agent：

项目如何连接。

只有从文件理解走向关系理解，Agent 才能真正参与大型项目。

---

延伸阅读

代码知识图谱正在成为 Agent 理解大型项目的一种方式。

例如：

CodeGraph

该项目通过构建本地代码知识图谱，为 Agent 提供符号关系、调用路径和影响范围分析，使 Agent 从逐文件搜索转向基于关系理解项目。

它体现了一个趋势：

Agent 的能力提升，不只是来自更大的模型，也来自更准确、更低成本的上下文。