> For the complete documentation index, see [llms.txt](https://code-visualization.shawnxie.top/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://code-visualization.shawnxie.top/di-wu-pian-ai-shi-dai-de-xin-ying-yong/code-graph-for-ai-agent.md).

# 代码图谱如何服务 AI Agent

代码图谱既可以给人看，也可以给 Agent 查。对 AI 来说，图谱最大的价值不是“画图”，而是把大仓库压缩成可查询、可解释、可审计的结构化上下文。

一个真实仓库中，文件数量、依赖关系、测试路径和历史变更都可能非常复杂。Agent 如果只靠读取文件和文本搜索，容易遗漏结构关系。代码图谱提供了另一种方式：让 Agent 通过工具查询软件事实。

## 图谱作为上下文压缩层

代码库包含大量信息，但一次任务通常只需要其中一小部分。图谱可以根据关系筛选上下文。

例如，给定一个目标方法，图谱可以返回：

* 方法定义位置。
* 上游调用方。
* 下游依赖。
* 所属模块。
* 相关测试。
* 最近变更。
* 运行时路径。
* Owner 和架构规则。

这些信息比把整个目录塞给 Agent 更有效，因为它们围绕任务组织，并且保留关系。

## 结构化查询优于盲目读文件

Agent 当然可以读文件，但读文件之前应该知道为什么读。图谱查询可以帮助 Agent 做阅读计划。

例如：

```
find_symbol("OrderService.cancel")
find_callers("OrderService.cancel")
find_callees("OrderService.cancel")
related_tests("OrderService.cancel")
impact_analysis(diff)
architecture_rules("order")
```

这些查询让 Agent 的工作过程更像有经验的工程师：先定位符号，再看调用关系，再找测试，再评估影响面。

## RAG 与代码图谱的互补关系

向量检索适合回答“哪些文本和这个问题语义相关”。它能发现命名不同但含义接近的文档、注释和代码。

代码图谱适合回答“这些实体之间是什么关系”。它能稳定表达调用、依赖、引用、覆盖、变更和 owner。

二者互补：

* 向量检索找到候选上下文。
* 图谱查询验证结构关系。
* 静态分析提供符号和调用。
* 运行时数据提供真实路径。
* 变更历史提供演进背景。

只用向量检索，容易缺少结构约束；只用图谱，可能漏掉自然语言需求和文档语义。两者结合更适合仓库级任务。

## MCP 风格工具接口

面向 Agent 的图谱能力应该通过工具接口暴露，而不是只做前端页面。

常见工具可以包括：

* `find_symbol`：查找符号定义。
* `find_references`：查找引用位置。
* `find_callers`：查找调用方。
* `find_callees`：查找被调用方。
* `impact_analysis`：分析变更影响。
* `related_tests`：推荐相关测试。
* `architecture_rules`：查询架构约束。
* `runtime_paths`：查询运行时 Trace 路径。

工具返回应尽量结构化，包含证据来源和置信度。Agent 可以据此继续阅读文件或执行修改。

## 约束修改范围

图谱不仅提供上下文，还可以约束 AI 行为。

例如：

* 只允许修改影响面内文件。
* 跨模块修改必须解释原因。
* 修改公共接口必须列出所有实现和调用方。
* 修改核心路径必须补充测试。
* 违反架构规则时阻断提交。

这些约束可以在 Agent 修改前作为提示，也可以在修改后作为检查。它们把代码图谱从“知识库”升级为“治理工具”。

## 查询轨迹审计

Agent 的查询过程应该可记录：

* 它查询了哪些符号。
* 它查看了哪些调用方。
* 它是否查了相关测试。
* 它是否读取了架构规则。
* 它是否忽略了高风险路径。

查询轨迹可以进入 Review 报告。Reviewer 不仅看最终 Diff，也可以看 Agent 是否进行了必要的上下文检查。

## 图谱结果的表达

Agent 不一定需要图形界面。它更适合消费结构化结果：

```json
{
  "symbol": "OrderService.cancel",
  "callers": ["OrderController.cancel", "OrderJob.retryCancel"],
  "related_tests": ["OrderServiceTest.cancel_shouldReleaseStock"],
  "risks": ["核心订单路径", "库存回滚依赖"],
  "evidence": ["static_call_graph", "coverage_report"]
}
```

人类可以看图，Agent 可以查 JSON，CI 可以消费报告。三者应该共享同一套图谱事实。

## 图谱维护成本

代码图谱不是一次性生成就结束。它需要随代码变化更新：

* 提交后更新源码结构。
* 测试后更新覆盖关系。
* 运行后更新 Trace 和性能属性。
* PR 合并后更新变更历史。
* 架构规则变化后重新检查违规依赖。

如果图谱过时，Agent 会基于错误事实做决定。因此，图谱的更新时间和数据来源必须可见。

## 小结

代码图谱服务 AI Agent 的核心方式，是提供结构化上下文、可查询关系、修改约束和审计证据。它让 Agent 不再只是读取文本，而是能够围绕任务查询软件事实。

下一章会讨论当 Agent 生成代码之后，如何把这些事实转化为 Review 证据层。