
Graphtia 构建本地代码图,帮助理解复杂软件系统
来源标题:Building a Local Code Graph to Understand Complex Software Systems
Graphtia 推出 Graphtia Explorer,在本地维护代码库的语义图,让用户或 AI 代理可持续追踪代码关系而无需重复重建。它支持符号解析、跨语言边界、API 和已声明数据库,并对代理查询设限。团队还介绍了相关测量结果和失败实验,这些将影响后续改进。
以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。
在陌生的代码仓库里找到一个函数通常不难,难的是理解它为什么存在。我需要找到它的调用方,搞清楚它的依赖从哪来,再追踪一处改动的影响,一路走进还没读过的文件。这大部分工作都是我在搜索 results 和源码之间来回切换时在脑子里完成的。
当 coding agent 参与调查时,这件事就更难了。一个答案听起来可能很合理,却漏掉了一条会改变结论的关系。我想要一种方法,能把这些说法追溯回代码,看看究竟确认了什么。
这个需求促使我构建了 Graphtia Explorer。它为本地代码库维护一张语义图,让人或 agent 能继续调查,而不必每次都重新构建同样的连接。真正有用的部分,是在一个 symbol、它的关系以及背后的源码之间来回移动。Graphtia 自己存储代码里的一个小例子可以让这一点更具体。
在 crates/atlasgraph-storage/src/lib.rs 中,ReverseBlock 是一个私有的 Rust 类型,用于入边查找。它的声明很短: Copy struct ReverseBlock { storage_class: StorageClass, schema_version: String, partition_id: u32, block_id: u64, by_target: BTreeMap<String, Vec<ReverseEdgeReference>>, 其中有意思的字段是 by_target。它按 target 对反向边引用分组;每个引用持有一个 edge ID 和一个 source URI。读这个声明就引出了我的第一个问题:谁读取这些 block,这个读取者又如何融入一次查询?
为写这篇文章,我们对着已索引的仓库和原始源码核对了这条路径。第一次 neighborhood 请求撞上了时间预算。我们没有把部分视图当作完整答案,而是转向该类型的引用。这个聚焦的结果返回了六条已确认的静态 TYPE_USES 关系。
其中一条指向 AtlasStorage::load_reverse_block_with_peak。在第 3884 行,该类型是 block decoder 的泛型参数。选中这个方法,下一个问题就有了精确目标。一次一跳的 callers 查询返回了来自 load_admitted_reverse_block 的一条已确认调用,该调用的源码位于第 3873 行。
现在调查已经从类型声明推进到了一条具体的读取路径。我可以检查 decoder,看看外层方法如何校验这个 block。如果我需要的是构造那一侧,已索引的 writer 对 ReverseBlock 另有一条 INSTANTIATES 关系。类型使用、构造和调用是不同的事实,所以图把它们保持为不同的关系。
这里的限制也很有用。从 prepare_reverse_block 到 load_admitted_reverse_block 的进一步连接仍处于 UNRESOLVED 状态。表达式在源码中可见,但这次 Rust 分析没有提升它的 receiver target。打开代码可以让我们检查这个缺口,而不改变图的证据标签。
可视化工作流遵循同样的节奏:选一个小的东西,查看它周围的关系,再检查让其中某条关系变得有意思的源码。下一步有用的操作可能是某个入向使用,也可能是某个出向依赖。这取决于问题是什么。
Explorer 把图和源码视图放在一起,这样移动到相邻实体时不必重新开始调查。我可以顺着一条关系进入代码,用在那里读到的内容选择下一个实体,然后朝任一方向继续。
一张包含数千个节点的图会让这件事更难。可视化器使用固定 revision 的有界投影,并在 worker 中执行布局。编辑器仍然是我编写和运行代码的地方;这个视图帮我决定接下来需要理解系统的哪一部分。
示例与方法:本节附带的真实分屏图像展示的是一个单独的 TypeScript 示例。它说明的是界面,而不是上面的 ReverseBlock 查询。那次调查使用的是聚焦的 MCP 查询和源码检查,不是运行时 trace,也不是原生 UI 点击的录制。reference 和 caller 查询在请求的已索引范围内完成了。第一次 neighborhood 仍然是部分结果。
要让这种导航可靠,图需要保留的不只是名字。声明和引用必须有能经受后续存储和查询的身份标识。它们的源码位置必须仍能解释一条 edge 为什么存在。
引擎发现符合条件的输入,然后向相应的 producer 索取事实。它解析这些事实所支持的关系,并发布一个持久的图 revision。桌面端和 MCP 客户端都调查那个 revision。构建索引不需要 AI 模型。
不同的输入需要不同的处理。一个声明出来的 SQL 表不是已部署的数据库。一份项目文档不应抬高代码 LOC 计数。保持这些语料分离,也是下面测量要区分物理输入文件和分析条目的原因。
文档有明确的边界:准入限制为 256 KiB,而搜索覆盖元数据和一个 4 KiB 的文本前缀。读取选中的文档是单独的操作。一次搜索未命中不能排除后面段落中的某个短语。
ReverseBlock 这个例子还暴露了一个贯穿整个系统的区别:识别一个名字,比解析一次使用意味着什么要容易。
Graphtia 建立在成熟的语言技术之上。JavaScript 和 TypeScript 使用 Oxc 进行解析和语义作用域处理,并配合模块解析。Rust 使用 syn。另外六个语法前端使用 Tree-sitter;语言矩阵列出了它们各自的覆盖范围。C# 路径使用单独的 Roslyn 分析器,而 C/C++ 和准备好的 Arduino 分析使用隔离的 libclang 包。
(原文较长,此处译出前 6000 字,完整内容请点「打开原文」。)
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。