Code-Graph-RAG：用知识图谱重构代码 RAG
理解一个陌生的大型代码库是开发者的日常痛点——接手几万行的项目，光搞清"这个函数被谁调用""数据怎么流转"就要花几天。传统代码 RAG 把代码当文本切片 + 向量检索，在跨文件的"调用关系""数据流"问题上力不从心，因为它不懂代码结构。Code-Graph-RAG（命令 cgr）换了个思路：用 Tree-sitter 把代码解析成 AST，把函数/类/方法及其调用、引用、数据流关系建成知识图谱存入图数据库 Memgraph，再用 AI 把自然语言翻译成 Cypher 图查询。这样"谁调用了 login()""有没有死代码""用户输入怎么流到数据库"这类结构化问题就能精准回答，还能驱动 AI 做外科手术式的代码编辑。参考 GitHub 仓库。
1、概述：Code-Graph-RAG 是什么
Code-Graph-RAG 是一个开源（MIT）的多语言代码库理解与编辑工具。指向一个仓库后，它读取每个源文件，抽取函数、类、方法、模块及它们之间的关系，存储为一张互联互通的图。图建好后，你可以：用自然语言问代码相关问题、按名字或意图检索源码、用 AST 补丁精准编辑、按规范优化代码、检测死代码、做结构化搜索替换。
能力 说明
------------------------------------------------------------------------
多语言解析 Tree-sitter 解析 13+ 种语言，统一图 schema
知识图谱 函数/类/方法 + 调用/引用/数据流关系，存入 Memgraph
自然语言问答 AI 把问题翻译成 Cypher 图查询，答案基于真实结构
AST 编辑 外科手术式补丁 + diff 预览，AI 驱动改代码
死代码检测 从入口反向遍历调用边，找出无人调用的函数
MCP 集成 作为 MCP Server，让 Claude Code 直接查改代码库核心实现（定位）：
1. 它是"代码库理解 + AI 编辑"工具，不是单纯的代码搜索
2. 核心创新是用知识图谱承载代码结构，而非传统文本切片
3. 支持单仓库多语言混合，统一 schema 覆盖 Python/TS/Go/Rust/Java/C#/C++ 等 13+ 种
4. 既能交互式 CLI 查询，也能作为 MCP Server 集成进 AI 编程助手
2、核心思路：为什么用知识图谱
这是理解 Code-Graph-RAG 的关键。传统代码 RAG 把代码按 token 切片、向量化、语义检索——适合"找实现某功能的代码段"，但面对结构化问题就抓瞎：
问题类型 传统向量 RAG 知识图谱 RAG
------------------------------------------------------------------
"找登录相关代码" ✓ 语义相似即可 ✓
"谁调用了 login()" ✗ 不懂调用关系 ✓ 遍历 CALLS 边
"login 的完整调用链" ✗ 跨文件拓扑缺失 ✓ 沿调用边递归
"有没有死代码" ✗ 需要入度分析 ✓ 反向遍历找无入边节点
"用户输入怎么到 DB" ✗ 需要数据流 ✓ 沿 FLOWS_TO 追踪核心实现（图 vs 向量的本质区别）：
1. 向量 RAG 把代码当"文本"，丢失了符号间的拓扑关系
2. 知识图谱把代码当"图"：节点是函数/类/方法，边是 CALLS/REFERENCES/FLOWS_TO
3. "调用关系/死代码/数据流"本质是图问题，用 Cypher 一步到位，向量做不到
4. Code-Graph-RAG 实际是图 + 向量混合：结构化问题走图，语义相似度走 Qdrant 向量
3、工作原理与架构
系统分两大组件：多语言解析器（建图）+ RAG 系统（查图）。解析器用 Tree-sitter 把代码读成 AST，抽取符号与关系入 Memgraph；RAG 系统把自然语言转成 Cypher，查图拿结果再交给 AI 组织回答。
// 建图阶段（一次性）
Source Code -> Tree-sitter Parser -> AST Analysis -> Memgraph Knowledge Graph
|
// 查询阶段（每次提问） |
User Query -> AI Model (Cypher Gen) -> Cypher Query -> Graph Results -> Response
// 关键设计：
// - Tree-sitter：业界标准的增量解析库，一套方案支持 13+ 种语言
// - 统一 schema：不同语言的函数/类/方法映射到同一套图节点与边类型
// - Cypher 生成：AI 不直接猜答案，而是先生成图查询，答案来自真实结构核心实现：
1. Tree-sitter 解析：跨语言统一抽象，函数/类/方法/模块都进同一套节点类型
2. AST 分析抽边：调用、引用、导入、包含、数据流等关系都变成图的边
3. Memgraph 存储：图数据库承载拓扑结构，支持 Cypher 高效遍历
4. AI 生成 Cypher：自然语言先翻译成图查询，结果再交给模型组织答案——答案有据可依
4、安装与环境
命令行工具 cgr 发布在 PyPI。用 uv 或 pipx 安装，带上 treesitter-full（全语言解析）和 semantic（向量搜索）两个 extra。还需 Docker（跑 Memgraph）、cmake、ripgrep。
# 前置：Docker（用于 Memgraph）、cmake、ripgrep
# 方式一：uv（官方推荐）
uv tool install "code-graph-rag[treesitter-full,semantic]"
# 方式二：pipx
pipx install "code-graph-rag[treesitter-full,semantic]"
# extras 说明：
# treesitter-full 安装所有语言的 Tree-sitter 解析器
# semantic 启用向量语义检索（配合 Qdrant）核心实现：
1. 推荐用 uv tool install，隔离环境、避免污染系统 Python
2. treesitter-full 装全语言解析器；只分析少数语言可不带此 extra 减体积
3. semantic 启用向量检索（Qdrant），是"图 + 向量混合"里的向量那半
4. Docker 用来跑 Memgraph 图数据库；cmake/ripgrep 是解析与搜索的底层依赖
5、快速上手
三步走：起服务 → 解析入库 → 交互查询。cgr 自带"Memgraph + Qdrant"栈，无需手写 docker-compose。
# 1. 启动打包好的 Memgraph + Qdrant 服务栈（无需 compose 文件）
cgr daemon up
# 2. 把仓库解析进图（--update-graph 触发解析，--clean 清空旧图重新建）
cgr start --repo-path /path/to/repo --update-graph --clean
# 3. 进入交互式查询（自然语言提问）
cgr start --repo-path /path/to/repo
# 示例问题：
# "谁调用了 handleLogin 方法？"
# "这个项目里有没有死代码？"
# "用户输入的 password 字段最终流到了哪些函数？"核心实现：
1. cgr daemon up 一键起 Memgraph + Qdrant，无需自己写 compose
2. --update-graph 触发 Tree-sitter 解析并把符号与关系写入图
3. --clean 清空旧图，适合首次入库或大改动后重建
4. 再次 cgr start（不带 update）即进入交互查询，支持自然语言
6、核心能力一览
图谱建好后，Code-Graph-RAG 能做的不止是问答，而是一整套"代码理解 + 编辑"能力：
- 自然语言问答：答案基于真实代码结构，而非模型猜测，减少幻觉
- 源码检索：按名字或意图取回任意函数/类/方法的真实源码
- AST 外科手术式编辑：AI 生成 AST 补丁改代码，改前先 diff 预览
- 代码优化：按语言最佳实践或自定义编码规范优化
- 死代码检测：从入口点遍历调用/引用边，找出无人引用的函数
- 数据流追踪：沿 FLOWS_TO 污点边追踪值如何流经赋值/调用/IO（C#/Java/C/Go）
- 结构化搜索替换：用 ast-grep 按 AST 模式跨库查找与改写，比正则可靠
核心实现（亮点）：
1. FLOWS_TO 数据流边是安全审计利器：追踪用户输入到 IO sink 的路径
2. 死代码检测天然适合图：反向遍历找无入边节点，向量 RAG 做不到
3. AST 补丁编辑比"全文重写"更安全，diff 预览可人工确认
4. ast-grep 结构化搜索超越正则：按语法结构匹配，不怕格式差异
7、MCP 集成：让 Claude Code 直接查改代码
Code-Graph-RAG 可作为 MCP（Model Context Protocol）Server 运行。这意味着 Claude Code 等 MCP 客户端能直接查询和编辑你的代码库——AI 助手不再"盲读文件"，而是先通过图谱理解结构再动手，准确率显著提升。
// 作为 MCP Server 运行后，MCP 客户端（如 Claude Code）可获得的能力：
// - 查询代码结构与关系（调用、引用、数据流）
// - 按意图检索源码
// - 触发 AST 编辑与结构化搜索替换
//
// 集成价值：
// 传统 AI 编程助手靠"读文件全文"理解代码，跨文件关系全靠猜；
// 接入图谱后，助手能先"查图"理解拓扑，再精准定位修改点，
// 尤其在大型代码库里大幅降低幻觉与误改。核心实现：
1. 遵循 MCP 标准，任何 MCP 客户端（Claude Code 等）都能接入
2. AI 助手从"读文件猜结构"升级为"查图谱知结构"
3. 大型代码库里，这种"先理解再动手"显著降低误改风险
4. 具体配置见仓库 docs/guide/mcp-server.md
8、总结
Code-Graph-RAG 的核心洞察是：代码的本质是图，不是文本。把函数/类/调用/数据流建成知识图谱，结构化问题就能用图查询精准作答，这是传统向量 RAG 在关系类问题上永远追不上的。
关键要点：
- 本质：Tree-sitter 解析 + Memgraph 图谱 + AI 生成 Cypher 的混合 RAG
- 优势：调用关系/死代码/数据流等结构化问题，图查询完胜向量切片
- 安装：uv tool install "code-graph-rag[treesitter-full,semantic]"，需 Docker/cmake/ripgrep
- 使用：cgr daemon up 起服务 → cgr start --update-graph 建图 → 交互查询
- 能力：问答/检索/AST 编辑/死代码/数据流追踪/结构化搜索替换
- 集成：MCP Server 模式让 Claude Code 先查图、再改码，降低大型库误改
对于维护大型遗留系统、做代码审计、或想让 AI 编程助手真正"看懂"整个仓库的开发者而言，"把代码变成知识图谱"这条路线值得重点关注——它补上了传统 RAG 在"代码结构理解"上的短板，让"谁调用了谁""数据怎么流""哪些是死代码"这类工程核心问题有了确定性的答案。配合 MCP 接入 AI 助手，更让"AI 真正理解大型代码库"从愿景走向现实。理解了"代码即图"这个底层思路，也就抓住了下一代代码智能工具的设计方向。
