代码图谱如何服务 AI Agent
代码图谱既可以给人看，也可以给 Agent 查。对 AI 来说，图谱最大的价值不是“画图”，而是把大仓库压缩成可查询、可解释、可审计的结构化上下文。
一个真实仓库中，文件数量、依赖关系、测试路径和历史变更都可能非常复杂。Agent 如果只靠读取文件和文本搜索，容易遗漏结构关系。代码图谱提供了另一种方式：让 Agent 通过工具查询软件事实。
图谱作为上下文压缩层
代码库包含大量信息，但一次任务通常只需要其中一小部分。图谱可以根据关系筛选上下文。
例如，给定一个目标方法，图谱可以返回：
方法定义位置。
上游调用方。
下游依赖。
所属模块。
相关测试。
最近变更。
运行时路径。
Owner 和架构规则。
这些信息比把整个目录塞给 Agent 更有效，因为它们围绕任务组织，并且保留关系。
结构化查询优于盲目读文件
Agent 当然可以读文件，但读文件之前应该知道为什么读。图谱查询可以帮助 Agent 做阅读计划。
例如：
这些查询让 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 不一定需要图形界面。它更适合消费结构化结果：
人类可以看图，Agent 可以查 JSON，CI 可以消费报告。三者应该共享同一套图谱事实。
图谱维护成本
代码图谱不是一次性生成就结束。它需要随代码变化更新：
提交后更新源码结构。
测试后更新覆盖关系。
运行后更新 Trace 和性能属性。
PR 合并后更新变更历史。
架构规则变化后重新检查违规依赖。
如果图谱过时，Agent 会基于错误事实做决定。因此，图谱的更新时间和数据来源必须可见。
小结
代码图谱服务 AI Agent 的核心方式，是提供结构化上下文、可查询关系、修改约束和审计证据。它让 Agent 不再只是读取文本，而是能够围绕任务查询软件事实。
下一章会讨论当 Agent 生成代码之后，如何把这些事实转化为 Review 证据层。
Last updated