用代码知识图谱减少智能体反复搜索

AI 在仓库里回答「谁调用了这个函数」，经常要反复 grep、打开文件，再把一堆搜索结果塞进上下文。ParkEase 的作者发现，真正费劲的问题往往是调用关系和模块依赖，于是用 Graphify 给代码建了一张关系图。

结论很实用：先查图，可以减少为了找关系而加载的上下文。但图只能提供代码证据，不能替团队判断规则；解析遗漏和查询歧义，也需要单独处理。

代码关系图为什么能省掉反复搜索

grep 擅长找字符串，却不能直接回答「哪些命令开启了数据库事务」「谁往 outbox 写数据」「哪个 API 目录依赖哪个领域模块」。这些问题需要把散落在文件里的关系拼起来。

Graphify 用 tree-sitter 解析代码的语法树，再把符号及其关系组织成知识图谱（knowledge graph）。可以把它理解成一张可查询的代码地图：节点是代码中的对象，边描述对象之间的联系。

在 ParkEase 中，它覆盖了 643 个代码文件及 SQL migrations，生成 4,011 个节点和 10,775 条边。

作者看重两个特点。首先，它不用 embeddings，也不用向量数据库；边来自解析或后续分析，并标记为直接发现或推断。因此，答案出错时，可以追查具体是哪条关系出了问题。其次，构建过程在本机执行，相同代码生成相同的图。

不过，确定性只能保证结果可重复，不能保证解析完整或推断正确。

查事务调用链，为什么还要读规则

作者用下面三个命令查询符号关系、两个对象之间的路径，以及自然语言描述的业务链路：

graphify explain "withTransaction()"   # 一个符号及所有指向它的边
graphify path "CreateBookingCommand" "OutboxService"
graphify query "how does booking reach the ledger?"

这里最值得看的是第一行：它把事务辅助函数的调用关系集中列出来，为检查事务使用情况提供入口。

ParkEase 有两条事务规则：每次写入使用一个事务，事务内部不能调用外部服务。作者认为，列出领域层中使用事务辅助函数的命令，可以把原本需要十五次 grep 的检查集中到一次查询中。

但不要把「找到调用者」当成「已经证明合规」。外部服务是否在事务回调中执行，仍可能需要继续检查路径和源码。原文没有展示完整的检查过程。

图告诉你代码做了什么，规则告诉你代码应该怎么做。

因此，作者每次仍直接读取决策记录和规则文档。如果让现有代码反过来定义「什么被允许」，待检查的实现就成了自己的裁判。

本地免费，也有需要补上的边界

作者关闭了 Graphify 对文档执行 AI 分析的步骤，没有为它设置 API keys，只构建 code-only 图。这条路径由本地语法解析完成，不产生模型 API 费用；文档 AI 分析则会计费。

这里的「零成本」有明确范围。原文没有给出构建耗时、维护投入或实际节省的 token 数，不能据此推导整个工作流没有成本。

数据方面，图是磁盘上数 MB 的明文。作者通过忽略文件排除环境文件、密钥和 keystores，也不把生成的图提交到仓库。本地运行并不自动解决敏感信息问题。

安装也踩过坑：首次装进共享 Python 用户包目录后，依赖遮蔽破坏了三个无关工具，后来改用独立虚拟环境。

另外，两类误报会影响使用：

• tree-sitter 无法解析一种合法的 TypeScript 写法，即带泛型参数的 tagged template，导致两个测试文件报告「语法错误、没有符号」。源码本身没有问题。
• 自由文本查询通过子串选择起始节点，查询 connect 会混入无关的 .connect()。需要精确结果时，作者建议直接指定符号名。

我的判断

我认可把关系查询前置。对调用链、跨目录依赖这类问题，结构化结果更贴近问题本身，能减少 AI 从搜索输出里重新拼关系的工作。

但原文提供的是作者在 ParkEase 上的经验，没有与 grep、IDE 的引用查找或语言服务给出对照数据，也没有证明准确率、延迟和费用分别改善多少。单个函数查引用，现有 IDE 可能已经够用；跨模块路径查询，才更能体现这张图的价值。

还要留意覆盖率。两个文件解析失败，不影响其他文件的图，却会让「全仓没有其他调用者」这样的结论失去充分依据。原文也没说清代码变更后如何更新图。用于审查前，既要确认图足够新，也要确认目标文件确实进入了图。

能拿来做什么

• 给 AI 安排调用链调查时，可以先让它查询明确的符号和路径，再打开相关源码核验，减少无目标的反复搜索。
• 检查 Node 服务的事务边界时，可以从事务辅助函数的调用者列表入手，并单独读取团队规则，核对事务内是否发生外部调用。
• 在 TypeScript 仓库试用前，先检查解析失败的文件；遇到缺失符号时，用源码和 IDE 引用查找补证。
• 安装时使用独立 Python 虚拟环境，并为生成图设置敏感文件排除规则，避免提交图文件。