Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

构建代码图谱

源码采集得到的是一批节点和边，但还不算完整的代码图谱。代码图谱需要稳定的数据模型、查询能力、更新策略和证据来源。

本章把采集结果组织成可查询模型，为后续影响面分析、可视化界面和 Agent 查询接口打基础。

图谱范围

最小图谱先覆盖以下实体：

  • repository

  • file

  • class

  • interface

  • method

  • test

最小关系先覆盖：

  • contains

  • extends

  • implements

  • calls

  • references

  • covers

  • changes

后续可以再扩展服务、接口、数据库表、消息 topic、owner、Trace 和 PR 等节点。

节点表设计

节点表可以设计为：

properties 可以存放复杂度、注解、参数、返回值、测试类型、owner 等扩展信息。初期不必拆得太细，先保证查询可用。

边表设计

边表可以设计为：

其中：

  • confidence 表示置信度。

  • source_kind 表示边的来源，例如 AST、type_resolver、coverage、git、manual。

  • properties 保存行号、调用表达式、观察次数、更新时间等。

边的来源非常重要。静态解析出来的调用边、运行时 Trace 确认的调用边、命名约定推断的测试边，证据强度不同。

关系方向

关系方向要保持一致。例如：

  • file contains class

  • class contains method

  • method calls method

  • class implements interface

  • test covers method

  • commit changes method

方向一致后，查询会简单很多。查调用方就是反向查 calls，查被调用方就是正向查 calls。

图谱查询能力

最小系统应该提供以下查询：

  • 根据名称查找节点。

  • 查询某个方法的调用方。

  • 查询某个方法的被调用方。

  • 查询某个类的实现或父类。

  • 查询某个文件包含的类和方法。

  • 查询从某个方法到入口的路径。

  • 查询某个方法相关测试。

如果用 SQLite，可以通过边表做递归查询；如果用内存图，可以构建正向和反向邻接表；如果用图数据库，可以用图查询语言表达多跳路径。

版本和增量更新

第一版可以全量重建图谱。每次扫描仓库后，删除旧图谱并重新生成。

当项目变大后，需要增量更新：

  • 根据 Git Diff 找到变更文件。

  • 重新解析变更文件。

  • 删除这些文件相关旧节点和旧边。

  • 写入新节点和新边。

  • 更新受影响的跨文件调用关系。

增量更新比全量更新复杂，但对大仓库很重要。

处理不确定关系

代码图谱中会有不确定关系。例如调用目标无法唯一解析、测试关联来自命名约定、运行时 Trace 受采样影响。

不要删除不确定关系，也不要把它们当成确定事实。更好的做法是保留关系，并标注：

  • 来源。

  • 置信度。

  • 推断规则。

  • 是否被运行时证据确认。

这样，后续报告可以说“该影响路径来自静态候选调用，未被运行时证据确认”，而不是给出过度确定的结论。

图谱数据校验

构建图谱后，需要做基础校验：

  • 节点 ID 是否唯一。

  • 边的 source 和 target 是否存在。

  • 关系类型是否在允许列表中。

  • 源码位置是否有效。

  • 是否存在明显重复边。

  • 是否存在解析失败文件。

这些校验能避免后续分析建立在坏数据上。

输出格式

图谱可以同时输出两种格式：

  • 机器可读 JSON：供查询接口和 Agent 使用。

  • 人类可读报告：展示统计信息和采集质量。

报告可以包含：

  • 文件数。

  • 类和方法数量。

  • 调用边数量。

  • 解析失败文件。

  • 外部依赖数量。

  • 候选边和确定边比例。

小结

代码图谱是实践项目的核心数据层。它把采集到的源码结构组织成可查询事实，并保留来源、置信度和源码位置。

下一章会使用这张图谱构建变更影响分析。

Previous采集源码结构Next构建变更影响分析

Last updated