Code-Graph-RAG：用知识图谱理解代码库

Fen9Pi2026/8/12大约 11 分钟

前言：代码理解的下一维度

2026-08-12 15:14 GMT+8

理解代码库的方式在进化：

第一代：grep + 文本搜索

找到包含某个关键词的文件
不理解结构，不理解关系

第二代：LSP + 语言服务器

理解单个文件的语法
不理解跨文件关系

第三代：RAG + 向量检索

基于语义相似度检索
不理解精确的结构关系

第四代：知识图谱 + 图遍历

解析代码库，构建知识图谱，用自然语言查询、编辑、优化代码

今天介绍 Code-Graph-RAG：

Parse code with Tree-sitter, build knowledge graph in Memgraph, query in plain English

一、项目概览

Code-Graph-RAG 是一个多语言代码库分析工具，用知识图谱理解和操作代码。

一句话说清楚：

解析多语言代码库，在 Memgraph 中构建结构知识图谱，用自然语言查询、编辑、优化代码

项目地址：https://github.com/vitali87/code-graph-rag 官网：https://code-graph-rag.com 开源协议：MIT Python：支持 PyPI 安装

核心特性

多语言解析：

13+ 语言支持（Python, TypeScript, TSX, JavaScript, Rust, Go, Java, C, C++, C#, PHP, Lua, Dart）
基于 Tree-sitter 解析
单一统一图模式

知识图谱：

Memgraph 存储
函数、类、方法、模块及其关系
跨文件、跨语言结构理解

自然语言查询：

将自然语言转换为 Cypher 查询
基于真实结构的答案
按名称或意图检索源代码

代码编辑：

基于 AST 的外科手术式补丁
Diff 预览
AI 驱动的编辑和优化

高级功能：

死代码检测
结构化搜索和替换（ast-grep）
数据流跟踪（FLOWS_TO 边）

二、最新特性

1. Ruby 支持

通过 pluggable ast-grep tier：

单个 YAML 模式文件添加语言
无需手写解析器
发出 Module、Function、Class 节点 + import 边

2. 结构化搜索和替换

ast-grep 集成：

用 AST 模式查找和重写代码
作为 agent 工具暴露
匹配和转换整个代码库的结构
不依赖文本或正则表达式

3. 数据流跟踪

FLOWS_TO 边：

跟踪值通过赋值、函数调用和 I/O sinks 的流动
支持 10 种语言：
- Python, JavaScript, TypeScript/TSX
- Go, Java, Rust
- C++, C, C#
污点分析、安全审计

三、工作原理

两个组件

1. 多语言解析器

基于 Tree-sitter
读取代码库
提取函数、类、方法、模块及其关系
存入 Memgraph（单一语言无关模式）

2. RAG 系统（codebase_rag/）

交互式 CLI
将自然语言转换为 Cypher 查询
检索匹配的代码
驱动 AI 编辑和优化

数据流

源代码 → Tree-sitter 解析器 → AST 分析 → Memgraph 知识图谱
                                                       |
用户查询 → AI 模型（Cypher 生成）→ Cypher 查询 → 图结果 → 响应

技术栈

解析：

Tree-sitter（多语言解析）
ast-grep（AST 模式匹配）

存储：

Memgraph（图数据库）
Qdrant（向量搜索）

查询：

Cypher（图查询语言）
AI 模型（自然语言到 Cypher）

四、支持的语言

完全支持

13+ 语言：

Python, TypeScript, TSX, JavaScript
Rust, Go, Java
C, C++, C#
PHP, Lua, Dart

开发中

Scala

结构支持

Ruby（通过 ast-grep）：

模块、函数、类
Import 关系

语言能力矩阵

每种语言的具体能力见 Language Support

五、核心能力

1. 自然语言查询

功能：

用自然语言问问题
得到基于真实结构的答案
不依赖模糊的语义相似度

示例："

"这个代码库中有哪些类？"
"找到所有调用了 authenticate 的函数"
"这个项目中如何处理错误？"
"找到所有未使用的导入"

工作流程：

用户输入自然语言
AI 模型生成 Cypher 查询
Memgraph 执行查询
返回匹配的代码片段

2. 源代码检索

功能：

按名称检索函数、类、方法
按意图检索（语义搜索）
返回实际源代码

示例：

# 按名称检索
cgr query "find the User class"

# 按意图检索
cgr query "find authentication functions"

3. 代码编辑

功能：

基于 AST 的外科手术式补丁
Diff 预览
AI 驱动的编辑
修改前确认

工作流程：

用户请求编辑
AI 生成补丁
AST 应用补丁
显示 diff
用户确认后写入文件

4. 代码优化

功能：

针对语言最佳实践优化
针对自定义编码标准优化
自动重构建议

示例：

cgr optimize --against best-practices
cgr optimize --against my-standards.json

5. 死代码检测

功能：

通过调用和引用边遍历
从入口点开始
找到未被调用的代码

价值：

清理未使用的代码
减少维护负担
提高代码质量

6. 结构化搜索和替换

功能：

用 AST 模式查找代码
用 AST 模式重写代码
作为 agent 工具暴露

优势：

不依赖文本匹配
不依赖正则表达式
精确的结构匹配

示例：

# 查找所有使用特定模式的函数
cgr ast-grep "function_call(name: 'console.log', ...)"

# 重命名函数
cgr ast-grep-replace "oldFunction(...)" "newFunction($1)"

7. 数据流跟踪

功能：

FLOWS_TO 边跟踪值流动
跟踪赋值、函数调用、I/O sinks
支持 10 种语言

应用：

污点分析
安全审计
数据流追踪

六、快速开始

安装

前置要求：

Python 3.8+
Docker（用于 Memgraph）
cmake
ripgrep

推荐安装（uv）：

uv tool install "code-graph-rag[treesitter-full,semantic]"

或用 pipx：

pipx install "code-graph-rag[treesitter-full,semantic]"

启动服务

# 启动 Memgraph + Qdrant 栈
cgr daemon up

解析代码库

# 解析仓库到图谱
cgr start --repo-path /path/to/repo --update-graph

# 查询图谱
cgr start --repo-path /path/to/repo

注意：

图是共享的
同步一个项目不影响其他项目
--clean 会删除所有项目（会先确认）

七、MCP 服务器

集成 Claude Code

Code-Graph-RAG 作为 MCP 服务器运行：

Claude Code 可以直接查询和编辑代码库
无需离开编辑器
实时代码理解

设置：见 MCP Server 指南。

八、架构设计

图模式

统一语言无关模式：

函数（Function）
类（Class）
方法（Method）
模块（Module）
关系边（IMPORTS, CALLS, REFERENCES, ...）

关系边类型：

IMPORTS：模块导入
CALLS：函数调用
REFERENCES：变量引用
FLOWS_TO：数据流
DEFINES：定义
INHERITS：继承

解析流程

1. Tree-sitter 解析：

读取源代码文件
生成 AST
提取节点

2. AST 分析：

识别函数、类、方法
提取关系
构建图节点和边

3. 图存储：

存入 Memgraph
建立索引
优化查询

4. 向量化（可选）：

生成向量嵌入
存入 Qdrant
支持语义搜索

查询流程

1. 自然语言输入：

用户输入查询
AI 模型处理

2. Cypher 生成：

AI 模型生成 Cypher 查询
基于图模式
基于用户意图

3. 图查询：

Memgraph 执行 Cypher
返回匹配节点
返回相关代码

4. 响应生成：

格式化结果
返回源代码
提供上下文

流程图1

九、实际应用

场景 1：代码导航

场景：新成员加入团队，需要快速理解代码库

使用 Code-Graph-RAG：

# 查询入口点
cgr query "what are the main entry points in this codebase?"

# 查询核心模块
cgr query "what modules handle authentication?"

# 查询调用链
cgr query "show me the call chain from request handler to database"

价值：

✅ 快速理解代码结构
✅ 不需要阅读所有文件
✅ 基于真实关系，不是猜测

场景 2：重构

场景：需要重命名一个函数，确保所有调用都更新

使用 Code-Graph-RAG：

# 查找所有调用
cgr query "find all functions that call 'processPayment'"

# 结构化替换
cgr ast-grep-replace "processPayment(...)" "handlePayment($1)"

# 验证更改
cgr query "show me all calls to 'handlePayment'"

价值：

✅ 精确找到所有调用
✅ 不会遗漏
✅ 可以验证更改

场景 3：死代码检测

场景：清理未使用的代码

使用 Code-Graph-RAG：

# 查找未使用的函数
cgr dead-code --type function

# 查找未使用的类
cgr dead-code --type class

# 查找未使用的导入
cgr dead-code --type import

价值：

✅ 自动化检测
✅ 精确识别
✅ 减少维护负担

场景 4：安全审计

场景：查找所有可能的安全问题

使用 Code-Graph-RAG：

# 数据流跟踪
cgr dataflow --source "user_input" --sink "sql_execute"

# 查找潜在的 SQL 注入
cgr query "find all database queries that use user input"

价值：

✅ 精确跟踪数据流
✅ 识别安全风险
✅ 不依赖人工审查

场景 5：代码优化

场景：根据最佳实践优化代码

使用 Code-Graph-RAG：

# 针对最佳实践优化
cgr optimize --against best-practices

# 针对自定义标准优化
cgr optimize --against my-standards.json

价值：

✅ 自动化优化建议
✅ 基于实际代码结构
✅ 可以自定义标准

十、与传统工具的对比

vs grep

维度	grep	Code-Graph-RAG
理解	文本匹配	结构理解
跨文件	不支持	支持
关系	不理解	理解调用、引用、继承
精确度	误报多	精确匹配
查询	正则表达式	自然语言 + Cypher

vs LSP

维度	LSP	Code-Graph-RAG
范围	单文件	整个代码库
跨文件	有限	完整支持
查询	定义、引用	自然语言查询
编辑	单文件重构	跨代码库重构
优化	无	自动化优化建议

vs 传统 RAG

维度	传统 RAG	Code-Graph-RAG
理解	向量相似度	图结构遍历
精确度	模糊匹配	精确结构匹配
关系	不理解	理解所有关系
查询	语义搜索	自然语言 + 图查询
编辑	不支持	基于 AST 编辑

十一、企业服务

开源基础

Code-Graph-RAG 是开源的：

MIT 许可证
免费使用
完整功能

企业服务

对于需要更多功能的组织：

1. 云托管部署：

托管云基础设施
图数据库和 AI agent 连接
零基础设施开销
处理扩展、更新、可用性

2. 本地和隔离网络部署：

在自己的环境中完全部署
包括隔离网络
受监管行业的完整数据主权
安全敏感组织

其他服务：

定制开发
集成咨询
技术支持合同
团队培训

View plans & pricing at code-graph-rag.com

十二、核心价值

1. 理解代码结构

不仅是找到代码：

理解代码之间的关系
理解调用链
理解依赖关系

基于真实结构：

不是猜测
不是模糊匹配
是精确的图遍历

2. 自然语言交互

不需要学习查询语言：

用自然语言提问
AI 生成 Cypher 查询
返回精确结果

降低门槛：

不需要了解图数据库
不需要了解 Cypher
不需要了解代码库细节

3. 跨语言支持

单一统一模式：

多语言代码库
统一图模式
跨语言理解

Monorepo 支持：

混合语言项目
统一视图
跨语言查询

4. 精确编辑

基于 AST 的编辑：

不是文本替换
是结构化编辑
理解代码语法

Diff 预览：

修改前预览
确认后应用
安全可靠

5. 高级分析

死代码检测：

精确识别
自动化检测
清理建议

数据流跟踪：

跟踪值流动
安全审计
污点分析

结构化搜索：

AST 模式匹配
精确查找
批量替换

十三、适用场景

代码理解

新成员加入：

快速理解代码库
学习架构
理解关系

代码审查：

理解变更影响
检查调用链
验证关系

重构

重命名：

找到所有调用
批量更新
验证更改

提取：

提取公共代码
理解依赖
安全重构

维护

死代码检测：

清理未使用代码
减少维护负担
提高质量

优化：

针对最佳实践
针对自定义标准
自动化建议

安全

数据流跟踪：

跟踪敏感数据
查找安全风险
审计合规

十四、总结

核心问题

传统代码理解的局限：

❌ grep 只能文本匹配，不理解结构
❌ LSP 只能单文件，不理解跨文件关系
❌ RAG 只能向量相似度，不理解精确结构

Code-Graph-RAG 的解决方案

知识图谱 + 图遍历：

✅ 解析代码库，构建知识图谱
✅ 用自然语言查询、编辑、优化
✅ 精确的结构关系理解
✅ 跨语言、跨文件支持

为什么选择 Code-Graph-RAG？

1. 精确理解

不是模糊匹配
是精确结构理解
基于真实代码关系

2. 自然语言交互

不需要学习查询语言
用自然语言提问
AI 生成查询

3. 跨语言支持

13+ 语言
单一统一模式
Monorepo 支持

4. 精确编辑

基于 AST 的编辑
Diff 预览
安全可靠

5. 高级分析

死代码检测
数据流跟踪
结构化搜索

记住

Code-Graph-RAG 是代码理解的下一维度。
从 grep 的文本匹配，到 LSP 的单文件理解，到 RAG 的语义搜索，到 Code-Graph-RAG 的知识图谱。
用知识图谱理解代码结构，用自然语言查询、编辑、优化代码。

附：资源链接

项目资源：

GitHub：https://github.com/vitali87/code-graph-rag
官网：https://code-graph-rag.com
文档：https://github.com/vitali87/code-graph-rag/tree/main/docs
PyPI：https://pypi.org/project/code-graph-rag/

文档资源：

安装指南：Installation
快速开始：Quick Start
架构概览：Architecture Overview
图模式：Graph Schema
MCP 服务器：MCP Server

安装速查：

# 安装（推荐 uv）
uv tool install "code-graph-rag[treesitter-full,semantic]"

# 或用 pipx
pipx install "code-graph-rag[treesitter-full,semantic]"

# 启动服务
cgr daemon up

# 解析代码库
cgr start --repo-path /path/to/repo --update-graph

# 查询代码库
cgr start --repo-path /path/to/repo