> For the complete documentation index, see [llms.txt](https://code-visualization.shawnxie.top/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://code-visualization.shawnxie.top/di-liu-pian-shi-jian-xiang-mu/build-code-graph.md).

# 构建代码图谱

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

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

## 图谱范围

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

* repository
* file
* class
* interface
* method
* test

最小关系先覆盖：

* contains
* extends
* implements
* calls
* references
* covers
* changes

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

## 节点表设计

节点表可以设计为：

```
id                稳定 ID
type              节点类型
name              简短名称
qualified_name    全限定名称
file_path         源码路径
start_line        起始行
end_line          结束行
properties        JSON 属性
```

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

## 边表设计

边表可以设计为：

```
id
source
target
type
confidence
source_kind
properties
```

其中：

* `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 使用。
* 人类可读报告：展示统计信息和采集质量。

报告可以包含：

* 文件数。
* 类和方法数量。
* 调用边数量。
* 解析失败文件。
* 外部依赖数量。
* 候选边和确定边比例。

## 小结

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

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