vitali87/code-graph-rag · 上手攻略

  • 仓库：vitali87/code-graph-rag
  • 链接：https://github.com/vitali87/code-graph-rag
  • 分类：AI · 代码智能 · RAG · 知识图谱
  • 作者：Tom
  • 更新：2026-08-15

它是什么

Code-Graph-RAG 是一个面向多语言代码库的 AI 问答与编辑系统。它用 Tree-sitter 解析源码，构建代码结构知识图谱存入 Memgraph，再用自然语言驱动 Cypher 查询，实现代码问答、编辑和优化。整个流程对用户屏蔽了图数据库细节——只需一条 CLI 命令，就能把一个陌生仓库变成可对话的智能体。

核心思路：把代码当知识图谱来索引，而不是当纯文本 chunk 来检索。

解决什么问题

  • 接手遗留代码时，无法快速理解模块关系和调用链
  • 传统基于 embedding 的代码检索对结构关系（继承、调用、引用）建模不足
  • 跨语言 monorepo（如 React+Node+Java）缺少统一的代码理解工具
  • 找死代码、分析代码质量需要写复杂正则或手动梳理
  • 纯静态分析无法处理动态分发（反射、函数指针、框架路由）

快速安装

前置依赖

依赖 说明
Python 3.12+ 运行时
Docker Memgraph 图数据库
cmake 编译 pymgclient
ripgrep (rg) 文本搜索
uv（推荐）或 pip 包管理器

系统依赖安装（macOS）：

brew install cmake ripgrep

Ubuntu/Debian：

sudo apt-get update && sudo apt-get install cmake ripgrep

安装 code-graph-rag

推荐用 uv 安装（含所有语言支持 + 语义搜索）：

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

或用 pipx：

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

从源码安装（需要 Git）：

git clone https://github.com/vitali87/code-graph-rag.git
cd code-graph-rag
uv sync --extra treesitter-full   # 多语言支持
make dev                          # 含测试和 pre-commit

启动 Memgraph

cgr daemon up

这会自动启动容器化的 Memgraph（无需手动写 docker-compose）。

⚠️ 注意：cgr daemon up 需要 Docker 运行状态。第一次启动会拉取 Memgraph 镜像。

核心用法

1. 将代码库解析入图

# 首次解析（清空旧图后重建）
cgr start --repo-path /path/to/repo --clean

# 增量更新（保留其他仓库的图数据）
cgr start --repo-path /path/to/repo --update-graph

解析完成后，代码的函数、类、方法、模块及其关系会以节点和边的形式存入 Memgraph。

2. 自然语言问答

cgr ask "Which function handles user authentication in this repo?"

背后流程：自然语言 → AI 生成 Cypher 查询 → 图数据库执行 → 返回答案 + 源码引用。

3. 运行时调用追踪（补充静态分析）

对于反射、接口分发、函数指针等静态分析盲区，用 cgr trace 运行测试套件，将实际发生的调用合并进图：

cgr trace --run "pytest tests/"

支持的运行时：Python、JVM（Java/Scala）、Node.js、.NET、PHP、Lua、Dart、Go。

4. AST 模式搜索与替换

用 ast-grep 做结构化搜索，作为 Agent 工具暴露：

# 搜索符合 AST 模式的代码
cgr search --pattern "foo($A$, $B$)"

# 替换（diff 预览后再确认）
cgr replace --pattern "old_pattern" --replacement "new_pattern"

5. 代码优化建议

cgr optimize --func "my_function"

基于语言最佳实践或自定义规则，对指定函数提出优化建议。

6. 死代码检测

cgr find-dead-code --entry "src/main.py"

从入口点出发，沿 CALLS 和 REFERENCE 边遍历，找出从未被调用的代码。

支持的语言

语言 状态 说明
Python / TypeScript / TSX / JavaScript ✅ 完全支持 Tree-sitter 解析
Rust / Go / Java / C / C++ / C# ✅ 完全支持 Tree-sitter 解析
PHP / Lua / Dart ✅ 完全支持 Tree-sitter 解析
Ruby ✅ 结构级支持 ast-grep YAML 模式，模块/函数/类/导入
Scala 🔨 开发中 —

详情见 Language Support。

典型适用场景

  1. 接手陌生大型代码库：快速建立全局视图，找到核心模块和调用链
  2. 代码审查辅助：自动识别某次改动的影响范围（沿调用边反向遍历）
  3. 跨语言 monorepo 分析：一次解析 Typescript + Go + Python 混写项目
  4. 死代码清理：大型历史项目清理无引用代码
  5. AI 结对的代码编辑：自然语言驱动定点修改，不依赖纯文本相似度
  6. 运行时路径分析：补充接口分发、反射等静态盲区的实际调用数据

坑与注意

  1. Memgraph 依赖：必须跑 Docker。没有 Docker 只能看 README，没法实际使用。
  2. Python 3.12 以下可能不兼容：cgr CLI 依赖较新的 Python，建议 3.12+。
  3. 首次解析耗时：大型仓库（>10k 文件）Tree-sitter 解析 + 入图可能需要数分钟，请耐心等待。
  4. Ruby 支持有限：Ruby 只支持结构级（模块/函数/类/导入），不支持方法内 AST 精细操作。
  5. 云端模型需要 API Key：使用 Gemini 或 OpenAI 做自然语言→Cypher 转换需要对应 Key；可选本地 Ollama 替代。
  6. 增删代码后需手动 --update-graph：图不会自动同步代码变动，遗漏会导致查询结果过期。
  7. .md 文件中的代码示例未经验证：文档中部分命令示例截断，建议以 cgr --help 输出为准。

与同类对比

工具 索引方式 多语言 运行时追踪 自然语言编辑
Code-Graph-RAG Tree-sitter + Memgraph 图 ✅ 12+ 语言 ✅ cgr trace ✅ Agent 驱动
GitHub Copilot 闭源 embedding 有限 ❌ 辅助补全，非独立工具
Sourcegraph 代码索引 + embedding ✅ ❌ 搜索为主
cursor-symbol 符号索引 有限 ❌ 辅助编辑
semgrep 规则/AST ✅ ❌ 仅分析，不编辑

核心差异：Code-Graph-RAG 用图数据库建模代码关系，天然适合"找出所有调用某函数的地方"这类结构化查询，而非纯文本相似度匹配。

一句话推荐

如果你需要在大型多语言代码库上做结构化分析和 AI 驱动编辑，Code-Graph-RAG 是目前开源方案中多语言支持最广、图谱建模最完整的工具；唯一的门槛是需要跑 Docker 和接受首次建图的几分钟等待。

来源

  • GitHub README（https://github.com/vitali87/code-graph-rag）
  • Installation 文档（https://github.com/vitali87/code-graph-rag/blob/main/docs/getting-started/installation.md）
  • Architecture Overview 文档（https://github.com/vitali87/code-graph-rag/blob/main/docs/architecture/overview.md）
  • Language Support 文档（https://github.com/vitali87/code-graph-rag/blob/main/docs/architecture/language-support.md）