Neo4j 推出的 Relate 让编码智能体能够查询代码仓库历史记录

关键要点

  • Neo4j 的 Relate 嵌入式图数据库使编程代理能够查询代码库的提交历史,识别仅靠源代码分析无法发现的隐藏文件依赖关系和共同变更模式。
  • 在 FastAPI 基准测试中,基于图谱的代理正确识别出三个同级安全模块,它们分别与 api_key.py 共同变更了 18 次、17 次和 16 次,而所有仅依赖代码的代理都未能找到它们。
  • Relate 在 4.6 秒内将 FastAPI 的 8,102 次提交导入一个 30 MB 的 .rl 文件中,并发现该包中有 126 对文件曾至少共同变更五次,其中 42 对没有代码引用。

Neo4j 的 Relate 是一款面向 AI Agent 的嵌入式图数据库,可帮助编码 Agent 访问代码仓库的提交历史,识别仅靠源代码无法揭示的隐藏文件依赖关系和共同变更模式。在一项比较三个 Agent——Codex、OpenCode 和 Pi——的基准测试中,这些 Agent 均运行于 gpt-6.1-sol;配备 Relate 的 git-to-graph 扩展后,它们正确识别出会一同变更的同级文件,而仅依赖代码的 Agent 未能找到这些文件。

Relate 面向 Agent 的原生架构

Relate 是一款开源图数据库,专为 AI Agent 直接查询而构建。它以嵌入式系统运行——只需一个二进制文件,无需部署服务器,整个数据库存储为单个 .rl 文件,Agent 可使用 Cypher 查询。其“面向 Agent 的原生”设计包含多项功能,例如 relate skill install 可为编码 Agent 安装一项技能,其中包含文档化的 CLI 命令和预构建查询目录;relate serve --mcp 则可将数据库作为模型上下文协议(MCP)工具公开,并提供 --read-only 标志以拒绝所有写入操作。Relate 扩展支持将外部数据加载到图中;本文展示了两个扩展:用于仓库提交历史的 git-to-graph,以及用于工作树的 fs-to-graph。

从 FastAPI 仓库构建图

使用 FastAPI 仓库(从 2018 年 12 月到 2026 年 11 月共有 8,102 次提交),git-to-graph 扩展导入了 8,102 次提交、914 位贡献者和 5,733 个文件,创建了 34,551 条 TOUCHED 边和 48,322 条 CO_CHANGED 边。fs-to-graph 扩展导入了 429 个文件夹和 3,229 个文件,创建了 3,657 条 CONTAINS 边。历史记录导入耗时 4.6 秒,文件导入耗时 14 秒,最终存储为一个 30 MB 的文件。两个命令都写入同一个 Relate 存储,因此一个图就能同时表示当前代码结构和历史变更模式。创建的图模式显示了人员如何编写提交、提交涉及哪些文件、文件如何共同变更及其边的计数,以及文件夹如何包含文件或嵌套文件夹。

通过共同变更分析发现隐藏文件依赖关系

在 FastAPI 安全模块中,文件 security/api_key.py 出现在 28 次提交中。其中有 18 次提交也变更了 oauth2.py;17 次变更了 http.py;16 次变更了 open_id_connect_url.py。这四个模块彼此之间没有直接导入关系,因此仅凭源代码无法看出它们之间的关系。通过查询 CO_CHANGED 关系——该关系将同一提交中出现的文件关联起来,并统计出现次数——Agent 可以发现,每当添加一种安全方案(例如在提交 #134, description in #1757 中添加 auto_error,或在 #13786, and WebSocket support in #10147 中添加 401 状态码),这四个模块都会一起变更。当被问及在为 APIKeyHeader 添加构造函数参数之前还需要变更哪些文件时,没有任何仅依赖代码的 Agent 提到这三个同级模块,而三个 Agent 都借助图访问权限识别出了它们。

查询历史先例

该图支持 Agent 查找进行过类似变更的早期提交。针对 security/api_key.py 文件,查询主题行中包含“security”的提交,找到了四次都触及相同三个源文件(open_id_connect_url.py、oauth2.py、http.py)的提交。这些提交包括:2019-04-03 的提交 fad3a9e1,为安全工具添加 auto_error(#134),包含 10 项测试;2021-07-29 的提交 3b2e8919,为所有安全方案类添加 description 参数,包含 11 项测试;2025-11-24 的提交 51ad909f,在安全类中使用 401 状态码,包含 23 项测试;以及 2026-10-18 的提交 1884325c,为安全依赖项添加 WebSocket 支持(#10147),包含 3 项测试。这种模式提供了一个范例,展示了哪些文件必须变更,以及需要进行多大范围的测试。

根据提交历史识别合适的审阅者

查询图中编写过涉及 routing.py 和 applications.py 的提交的人员,并排除机器人账户后,可按提交次数和最近活跃时间对审阅者进行排序。Sebastián Ramírez 以 135 次提交位居首位,最近一次触及相关文件的时间为 2026-10-22;其次是 David Montague(8 次提交,最近一次触及时间为 2019-11-27)、Marcelo Trylesinski(7 次提交,最近一次触及时间为 2025-10-11)、Mohammed(7 次提交,最近一次触及时间为 2019-03-23)、Yurii Motov(5 次提交,最近一次触及时间为 2026-07-28)和 Yurii Karabas(3 次提交,最近一次触及时间为 2023-01-07)。last_touch 列十分重要,因为仅按提交次数排序可能会让过时的贡献者排在前面,而近期活动则表明其仍在积极参与。

没有代码引用却存在耦合的文件

由于 fs-to-graph 会在与提交历史相同的节点上存储文件文本,因此只需一次查询,就能找出 fastapi/ 包中共同变更至少五次的 126 对文件。在这 126 对文件中,有 42 对(三分之一)不存在任何方向上的引用——任何一个文件的文本都没有提到另一个文件的名称。这种关系模式无法仅通过导入图或文本搜索发现,揭示了源代码分析中不可见的隐藏架构耦合。

Agent 基准测试结果

三个编码 Agent(Codex 0.167.1、OpenCode 2.2.7 和 Pi 1.5.2)均运行于 gpt-6.1-sol,推理强度设为 medium,并接受了两项任务:为 APIKeyHeader 添加一个可选构造函数参数,以及为 APIRouter.add_api_route 添加一个关键字参数。两种情况下,Agent 都被要求不要编辑任何内容,而是提供一份简报,列出还需变更哪些文件、应运行哪些测试,以及应由谁审阅。

在仅依赖代码的条件下,Agent 可以访问不含 .git 目录的 FastAPI 工作副本,以及标准的搜索和读取工具。在图支持条件下,Agent 拥有相同的工作副本,并可通过 MCP 以只读模式访问 Relate。

结果显示,仅依赖代码的 Agent 和图支持的 Agent 都找到了相同的核心测试和可见依赖项(例如导入 routing 的 applications.py)。然而,只有图支持的 Agent 识别出了三个同级安全模块。OpenCode 报告称,这三个模块分别与 api_key.py 共同变更了 17、18 和 16 次,应检查它们以确保 API 一致性,而不是自动编辑。Codex 补充道:“此前两次添加 description 和 auto_error 的变更都涉及全部四个模块。”仅依赖代码的 Agent 无法识别活跃审阅者,而是从 docs/en/docs/management.md 中找到了项目维护者。Codex 表示:“仅凭这个工作副本,我无法确定这些方法的路由专家或近期贡献者。”Pi 写道:“没有历史记录或明确的组件所有权信息,我无法确定这部分代码的近期维护者。”有了图访问权限后,三个 Agent 都根据相关文件的提交历史给出了具体人员名单。

为 Agent 配置图访问权限

Relate 可以通过 MCP 提供只读存储。发送 MATCH (n:Person) DETACH DELETE n 这样的写入查询会返回错误:“只读查询仅允许 MATCH 查询。”对于 Codex,可在 ~/.codex/config.toml 中使用 relate 命令及其参数注册服务器。对于 OpenCode,可在 ~/.config/opencode/opencode.json 的 mcp.servers 部分进行配置。Pi 则通过带有 --read-only 标志的 relate 命令行访问同一个存储。对于这三个 Agent,relate skill install --agent 都可以添加一个包含预置历史查询目录的技能,让 Agent 不必从空白页面开始。

在一次处理安全任务的 Codex 会话中,Agent 调用了 read_cypher,但没有提供任何查询,执行引擎在 0.3 毫秒内作出了响应。该查询查找与 fastapi/fastapi/security/api_key.py 共同变更的文件,并按频率返回耦合文件及其变更次数。

实现与扩展系统

git-to-graph 会对整个提交历史调用一次 git log,在内存中构建执行计划,并通过六个批量 MERGE 阶段写入数据:人员、提交、文件,然后是三种关系类型(AUTHORED、TOUCHED 和 CO_CHANGED)。该扩展会在写入前创建范围索引,并在写入后为提交主题创建全文索引。由于扩展不拥有数据库,因此它会作为子进程运行,通过 MCP 与 Relate 主机通信;主机负责管理存储、事务批处理和各项限制。

两个标志用于控制导入时间范围:--since 会读取指定日期之后的所有内容,--until 则设定范围结束时间,因此可以一致地导入不同历史时期的数据。例如,relate run git-to-graph fastapi --since 2024-01-01 --until 2025-01-01 -d fastapi-2024.rl 只会导入 2024 年的数据。

有两项配置细节对准确分析很重要。第一,图中的路径包含导入时所在的目录,因此当导入器从父目录运行时,包中的文件会显示为 fastapi/fastapi/routing.py。第二,fs-to-graph 扩展默认最多存储 64 KB 的文件文本;对于 FastAPI,routing.py(260 KB)和 applications.py(185 KB)等大文件需要使用 --max-content-bytes 400000 标志,才能纳入完整内容。

用户代码仓库快速上手

要在任何代码库中使用 Relate,只需四个步骤:安装二进制文件和扩展,从父目录运行导入器,安装 Agent 技能,以及将存储注册为只读 MCP 服务器。

安装命令会使用 curl 下载并安装 Relate,然后安装两个必需的扩展。导入命令从代码仓库的上一级目录运行,因此图中的路径会以仓库名称开头。安装技能并启动 MCP 服务器后,Agent 就能访问历史查询和只读图。

完成设置后,Agent 可以针对任何文件回答三个核心问题:这个文件变更时,还有哪些文件会变更?以前有人做过类似的变更吗?谁参与过相关工作?

关键事实

  • Relate 是一款面向 AI Agent 设计的开源嵌入式图数据库,整个数据库以单个 .rl 文件的形式存储,可通过 Cypher 查询,无需部署服务器。
  • FastAPI 基准测试导入了 8,102 次提交、914 位贡献者和 5,733 个文件,创建了 34,551 条 TOUCHED 边和 48,322 条 CO_CHANGED 边;历史记录导入耗时 4.6 秒,文件导入耗时 14 秒。
  • 该基准测试比较了三个编码 Agent(Codex 0.167.1、OpenCode 2.2.7 和 Pi 1.5.2),它们均运行于 gpt-6.1-sol,推理强度为 medium,并完成两项任务:为 APIKeyHeader 添加构造函数参数,以及为 APIRouter.add_api_route 添加关键字参数。
  • 仅依赖代码的 Agent 未能识别与 api_key.py 分别共同变更了 18、17 和 16 次的三个同级安全模块(oauth2.py、http.py、open_id_connect_url.py);三个图支持的 Agent 都识别出了这些模块。
  • 共同变更分析发现,FastAPI 包中有 126 对文件共同变更至少五次,其中 42 对(三分之一)彼此之间没有代码引用。
  • fs-to-graph 扩展默认最多存储 64 KB 的文件文本;FastAPI 导入时使用 --max-content-bytes 400000,以纳入 routing.py(260 KB)和 applications.py(185 KB)等大文件。
  • git-to-graph 支持通过 --since 和 --until 标志进行指定时间范围的导入;重复运行导入可合并结果而不会产生重复数据。
  • Relate 提供的只读 MCP 工具会拒绝写入操作;Agent 可通过标准输入/输出上的 MCP,或通过带有 --read-only 标志的 relate CLI 访问存储。
  • relate skill install --agent 命令会添加一个预构建历史查询目录,让 Agent 无需手动提示,就能查找共同变更的文件、先例提交和活跃审阅者。

常见问题

使用 Relate 时,Agent 可以检索哪些关于文件变更和历史的信息?

Agent 可以查询 CO_CHANGED 关系,查看哪些文件出现在同一提交中以及它们共同出现的次数,从而发现隐藏依赖关系。它们可以按关键词搜索提交主题,查找进行过类似变更的早期提交,了解哪些文件共同变更以及涉及多少项测试。它们还可以查询编写过触及指定文件的提交的人员,并根据提交次数和最近一次触及时间识别活跃审阅者。查询可在毫秒内返回;Codex 在安全任务中的 read_cypher 调用耗时 0.3 毫秒。

仅依赖代码的 Agent 与图支持的 Agent 在识别代码依赖关系方面有何不同?

仅依赖代码的 Agent 能够识别一个文件导入另一个文件这类可见依赖关系(例如 applications.py 导入 routing.py),也能直接读取测试文件来找到核心测试。不过,对于共同变更却没有代码引用的文件,仅依赖代码的 Agent 无法识别;没有任何仅依赖代码的简报提到这三个同级安全模块(oauth2.py、http.py、open_id_connect_url.py),尽管它们与 api_key.py 分别共同变更了 18、17 和 16 次。图支持的 Agent 识别出了这些模块,并说明了判断依据;OpenCode 指出了共同变更次数,并建议检查 API 一致性,而 Codex 则引用了显示这一模式的先前提交。仅依赖代码的 Agent 也无法识别活跃审阅者;Codex 和 Pi 表示,没有历史记录就无法确定路由专家或近期维护者,而图支持的 Agent 则根据提交活动和最近活跃时间对审阅者进行了排序。

为编码 Agent 配置 Relate 需要哪些技术步骤?

安装需要三个步骤:通过 curl 脚本下载 Relate 二进制文件,安装 git-to-graph 和 fs-to-graph 扩展,然后从代码仓库的上一级目录运行导入命令。git-to-graph 命令会将提交历史导入 .rl 文件,fs-to-graph 则会将工作树添加到同一文件中。对于大文件,可使用 --max-content-bytes 标志(FastAPI 使用了 400000 字节,以纳入 260 KB 和 185 KB 的文件)。如需让 Agent 访问,可运行 relate skill install --agent 来添加预置查询,然后运行 relate serve --mcp stdio --database /path/to/repo.rl --read-only,通过 MCP 提供存储。针对特定 Agent 的配置(Codex、OpenCode、Cursor、Claude Code)需要在 ~/.codex/config.toml 或 ~/.config/opencode/opencode.json 等配置文件中注册 relate 命令。

免责声明:本页面信息可能来自第三方,仅供参考,不代表 Gate 的观点或意见,亦不构成任何财务、投资或法律建议。数字资产交易风险较高,请勿仅依赖本页面信息作出决策。具体内容详见声明。
评论
0/400
暂无评论