Code Graph Builder — 代码知识图谱引擎

1 / 14
←→ 导航 | Space 下一页
Project → Package → File
Function → CALLS → Function
Class → INHERITS → Class
Module → IMPORTS → Module
Interface → IMPLEMENTS
v0.3.1

# Code Graph
Builder

将任意代码库转化为结构化知识图谱， 让 AI 编程助手真正理解函数关系、调用链路与模块结构

🔷 知识图谱 🔍 语义搜索 🤖 MCP 协议 📖 Wiki 生成 ⚡ 11 种语言
— 背景问题

## AI 助手为什么
读不懂你的代码？

大型代码库中，单纯的文件读取无法还原函数调用链、类继承关系、跨模块依赖——这正是现有 AI 工具的盲区。

📂
上下文爆炸
直接贴代码文件，Token 超限，关键信息被截断丢失
🔗
关系缺失
AI 看不到函数间的调用链路、类的继承层次
🌐
跨文件盲区
跨模块调用、接口实现等关系无法被线性文本描述
🔄
重复索引
每次对话都需要重新提供上下文，没有持久化知识库
— 解决方案

## 构建代码的 知识大脑

一次构建，持久查询。静态分析 × 知识图谱 × 语义向量 × LLM

📁
源代码仓库
→
🌳
Tree-sitter AST
→
🕸️
知识图谱
→
📄
API 文档
→
🔍
语义向量
→
🤖
MCP / AI 助手
📊 结构化图数据库
Kùzu 嵌入式，无需 Docker，完整 Cypher 支持，零部署成本
🧠 Qwen3 语义嵌入
函数级向量索引，1536 维，余弦相似度检索
⚙️ 19 个 MCP 工具
Claude Code / Cursor 可直接调用，标准化工具集
— 核心架构

## 五层顺序 处理管道

基于 Tree-sitter AST，按顺序执行五个处理器，从项目结构到语义调用关系逐层构建

01
StructureProcessor — 项目结构识别
识别 Project → Package → Folder → File 的层次结构
CONTAINS_*
02
DefinitionProcessor — 定义提取
提取 Function、Class、Method、Interface、Enum，含签名、文档字符串、可见性
DEFINES
03
ImportProcessor — 导入关系解析
解析 import / include / use 语句，建立模块间依赖关系图
IMPORTS
04
CallProcessor — 调用点收集
识别所有函数调用位置，收集调用上下文和调用者信息
调用列表
05
CallResolver — 跨文件调用解析
将调用点与定义匹配，处理跨文件、链式、方法调用
CALLS
— 数据模型

## 知识图谱 Schema

节点类型 — 13 种
Project Package Folder File Module Function Method Class Interface Enum Type Union ModuleInterface
核心节点属性
qualified_name signature docstring return_type visibility parameters start_line end_line
关系类型 — 13 种
CONTAINS_PACKAGE CONTAINS_FOLDER CONTAINS_FILE DEFINES DEFINES_METHOD IMPORTS EXPORTS INHERITS IMPLEMENTS OVERRIDES CALLS DEPENDS_ON_EXTERNAL EXPORTS_MODULE
图数据库
⚡ Kùzu 嵌入式图数据库
无需 Docker · 完整 ACID 事务 · Cypher 查询 · Python 原生 API
— 多语言支持

## 支持 11 种 编程语言

基于 Tree-sitter 统一解析框架，添加新语言只需定义 LanguageSpec 和查询规则

Python
✓ 完全支持
JavaScript
✓ 完全支持
TypeScript
✓ 完全支持
C++
✓ 完全支持
Lua
✓ 完全支持
C
⚡ 开发中
Rust
⚡ 开发中
Go
⚡ 开发中
Java
⚡ 开发中
Scala
⚡ 开发中
C# / PHP
⚡ 开发中
+ 可扩展
定义 LanguageSpec
C/C++ 特殊支持
宏定义 · struct/union 成员 · 内存所有权推断 · header/impl 分离
Python 特殊支持
装饰器识别 · 类型注解提取 · 嵌套函数 · dataclass 支持
— 文档架构

## 三层 API 文档体系

专为向量检索优化，不同粒度满足不同查询场景

L1
索引层 — index.md
列出所有模块和类，用于导航和概览；快速定位目标模块
L2
模块层 — module_name.md
模块描述、公开 API 列表、调用关系总览；了解模块职责和对外接口
L3
函数层 — 向量化单元 ⭐ 核心
单函数详情：签名 · 调用树 · 调用者列表 · 参数内存方向 · 截断源码（2000字符）
📊 调用树可视化
每个函数附带完整调用树和被调用关系列表
🤖 LLM 生成描述
无文档字符串时，自动调用 LLM 生成语义描述
💾 源码内联
截断至 2000 字符的源代码直接嵌入文档单元
— 智能检索

## RAG 语义搜索 引擎

向量相似度 + 图遍历双重检索，精准定位相关代码上下文

检索流程
💬
用户查询
自然语言输入
🔍
语义向量搜索
Qwen3 · 1536 维 · Top-K 召回
🕸️
图遍历扩展
调用者 · 被调用者 · 相关节点
🤖
LLM 生成分析
OpenAI / DeepSeek / Moonshot
📄
Markdown 输出
结构化分析文档
向量化组件
Qwen3 Embedder
text-embedding-v4 · 1536 维 · DashScope API · 批量编码
向量存储
MemoryVectorStore（默认）· QdrantVectorStore（生产）
Cypher 生成
自然语言 → Cypher 查询，LLM 翻译，错误自动重试
— MCP 集成

## 19 个 MCP 工具

Claude Code、Cursor 等 AI 助手可直接通过 MCP 协议调用，零摩擦集成

📦 仓库管理（4 个）
initialize_repository — 完整四步流水线
get_repository_info — 图统计元数据
list_repositories — 工作区仓库列表
switch_repository — 切换活跃仓库
🔍 代码搜索（5 个）
find_api ⭐ — 语义搜索 + 文档附加
semantic_search — 向量相似度搜索
query_code_graph — 自然语言 → Cypher
get_code_snippet — 按限定名取源码
locate_function — Tree-sitter 精确定位
📖 API 文档（4 个）
list_api_docs — L1 / L2 文档索引
get_api_doc — L3 函数详情（含源码）
list_api_interfaces — 按模块列公开 API
generate_api_docs — 重新生成文档
🗺️ Wiki 与分析（6 个）
list_wiki_pages — Wiki 页面目录
get_wiki_page — 读取 Wiki 内容
generate_wiki — 重新生成 Wiki
rebuild_embeddings — 重建向量索引
build_graph — 重建知识图谱
prepare_guidance — 设计文档分析
— 持久化存储

## 工作空间 文件布局

每个仓库独立隔离存储，支持多仓库并存切换，一次构建永久可用

~/.code-graph-builder/ # CGB_WORKSPACE ├── active.txt # 当前活跃仓库 └── my_project_a1b2c3d4/ # hash(仓库路径) ├── meta.json # 元数据 ├── graph.db # Kùzu 图数据库 ├── vectors.pkl # 向量缓存 ├── api_docs/ │ ├── index.md │ └── module_*.md └── wiki/ ├── index.md └── pages/*.md
🔒 仓库隔离
每个仓库以路径 Hash 命名，互不干扰，switch_repository 一键切换
⚡ 增量更新
只需重新运行对应步骤（graph-build / embed-gen / wiki-gen）局部更新
🌐 环境变量配置
CGB_WORKSPACE 自定义路径 · LLM_API_KEY · DASHSCOPE_API_KEY
— 性能基准

## 性能指标 TinyCC · 1611 个函数

≥95%
调用识别率
≥90%
跨文件调用准确率
≤5%
最大误报率
处理耗时（1611 函数基准）
📊
图构建
~ 3 分钟
📄
API 文档生成
~ 3 分钟
🔍
向量化（API 调用）
~ 27 分钟
系统要求
⚡ 解析速度
目标 ≥ 1000 func/s · 最低 ≥ 500 func/s
💾 内存占用
目标 ≤ 2GB · 最大 ≤ 4GB
🗄️ DB 写入
目标 ≥ 500 nodes/s · 最低 ≥ 200 nodes/s
— LLM 集成

## 灵活的 LLM 提供商支持

自动按优先级检测环境变量，支持任意 OpenAI 兼容 API

优先级
配置方式
适用
#1
LLM_API_KEY / LLM_BASE_URL / LLM_MODEL
通用，最高优先
#2
OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL
OpenAI 兼容
#3
MOONSHOT_API_KEY / MOONSHOT_MODEL
Moonshot / Kimi
已验证 LLM
OpenAI GPT-4o DeepSeek Chat Moonshot Kimi-k2.5 任意 OAI 兼容
嵌入提供商
Qwen3 (DashScope) text-embedding-v4 DASHSCOPE_API_KEY
🛠️ 最新改进 — 安装向导支持多 Provider 选择
`/cgb-start` 向导现已支持交互式选择 LLM 和嵌入提供商，无需手动配置环境变量
— 快速上手

## 四步 快速开始

1
安装 Code Graph Builder
pip install "code-graph-builder[treesitter-full,semantic,rag]"
2
配置 MCP 服务器（Claude Code / Cursor）
cgb-mcp # 启动 MCP 服务器
3
运行交互式设置向导
/cgb-start # 在 Claude Code 中运行
4
初始化代码仓库（完整四步流水线）
/repo-init /path/to/your/project
🔍 代码搜索
`/code-search "函数功能描述"`
📋 查找 API
`/api-find "接口名称"`
📚 读取 Wiki
`/wiki-read 页面名称`
Code Graph Builder · v0.3.1

## 让 AI 真正
读懂你的代码

静态分析 × 知识图谱 × 语义向量 × LLM
构建永久可查询的代码知识库

11
支持语言
19
MCP 工具
3L
文档架构
≥95%
调用识别率
📦 pip install code-graph-builder 🚀 /cgb-start