图 Schema：节点与关系类型

CGB 支持三种图后端：Kuzu（推荐，嵌入式）、Memgraph（生产级）、Memory（单测用）。三者共享同一套图 Schema，通过抽象接口 GraphBackend 隔离。

🔴

Function / Method

主键 qualified_name，持有签名、参数列表、可见性、docstring、起止行号

🟣

Class / Interface / Enum

持有继承链、实现接口列表；Interface 区别于 Class，Enum 区别于 Type

🔵

Module / Package

模块对应单个源文件，Package 对应目录；通过 CONTAINS_MODULE / CONTAINS_PACKAGE 关联

🟡

File / Folder / Project

文件系统层，Project 是根节点，通过 CONTAINS_FILE / CONTAINS_FOLDER 形成树形结构

三 Pass 构建策略

图构建被拆成三个顺序执行的 Pass，原因很简单：调用解析（Pass 2）依赖 所有文件的函数定义都已写入图（Pass 1 完成），否则跨文件调用永远找不到目标节点。

1

Pass 1 — 定义提取（definition_processor）

扫描所有文件，写入 Project / Package / Folder / File / Module / Class / Function / Method 节点，及 CONTAINS_* / DEFINES / DEFINES_METHOD 边。同时把所有 FQN 注册进 FunctionRegistryTrie。此 Pass 完成后图中有完整的"结构骨架"。

2

Pass 2 — 调用与导入解析（call_processor / call_resolver / type_inference）

再次扫描所有文件，用 call_query 和 import_query 提取调用和导入，结合 Trie 消歧后写入 CALLS / IMPORTS / DEPENDS_ON_EXTERNAL 边。type_inference 负责为动态语言推断方法调用的接收者类型。

3

Pass 3 — Embedding 向量化（可选）

为每个函数节点生成 embedding 向量并存入向量索引（Chroma / Qdrant）。向量由函数签名 + docstring + 调用上下文拼接后送入 embedding 模型。此 Pass 可独立运行（cgb rebuild-embeddings）。

增量更新：基于 git diff 的智能重建

每次 cgb index 时，CGB 比较当前 HEAD commit hash 与上次索引时记录的 hash。如果相同则跳过；不同则通过 git diff --name-only 获取改动文件列表，仅重建这些文件。超过50个改动文件时触发全量重建。

📄

meta.json

→

🔀

git HEAD

→

📑

diff 列表

→

⚡

增量重建

→

🔄

全量重建

→

💾

更新 hash

点击"下一步"开始 Step 0 / 6

Kuzu 锁竞争与并发写入处理

Kuzu 是嵌入式数据库，同一时刻只允许一个进程持有写锁。当 MCP 服务器正在读图、同时用户触发 cgb index 写图时，就会发生锁竞争。CGB 的处理策略是指数退避重试。

💡 关键洞察

图 Schema 中"14种节点 + 11种关系"的设计颗粒度，直接决定了查询能力的上限。颗粒度不够（如把 Function 和 Method 合并）会丢失"方法归属哪个类"的信息；颗粒度过细（如区分 AsyncFunction 和 Function）则会让 Cypher 查询复杂度爆炸。CGB 的当前 Schema 是在可查询性和写入复杂度之间权衡的结果。

Pass 2 内部协作：call_processor 与 type_inference

对于动态语言（Python/JavaScript），方法调用 obj.parse() 需要先推断 obj 的类型才能确定调用目标。type_inference 模块承担这个职责，与 call_resolver 协作完成消歧。

方法调用消歧 — 内部协作

0 / 4 messages