code-graph-rag

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

当代码库变成一座迷宫

想象一下：你接手一个 50 万行的遗留 monorepo，里面混杂着 Python、TypeScript、Rust、Go 四种语言。没有任何文档，函数调用链绕了三层，类继承关系像一团乱麻。你要怎么快速找到"哪个模块在处理用户认证"？

传统做法是 grep + 人工追踪 —— 费时、容易漏、还容易晕。Code-Graph-RAG 正是为解决这个问题而生：它用知识图谱代替文本搜索，让 AI 成为你理解代码的导航仪。

核心技术：Tree-sitter 解析 + Memgraph 图数据库

Code-Graph-RAG 的核心架构分为两层：

第一层：多语言解析引擎。 项目基于 Tree-sitter 构建了一套解析系统。Tree-sitter 是一种增量式语法解析器，可以生成代码的抽象语法树（AST），准确识别函数、类、方法、模块以及它们之间的调用关系。Code-Graph-RAG fork 了多个 tree-sitter 语法包，修复了上游已知 bug，确保解析准确性。

第二层：Memgraph 知识图谱。 解析结果被存储进 Memgraph 图数据库中，采用统一的语言无关图谱 Schema。这意味着 Python 中的 class 和 TypeScript 中的 interface 会被映射到同一个抽象概念 Node 上，跨语言调用关系用 Edge 表示。整个 monorepo 最终变成了一张可查询的图。

Source Code → Tree-sitter Parser → AST Analysis → Memgraph Knowledge Graph
                                                      ↓
User Query → AI Model (Cypher Gen) → Cypher Query → Graph Results → Response

支持语言：几乎覆盖主流

项目支持的编程语言包括：Python、TypeScript、TSX、JavaScript、Rust、Go、Java、C、C++、C#、PHP、Lua、Dart（全支持），以及 Ruby、Kotlin、Swift、Elixir、Haskell、Solidity、Bash、Nix（结构支持）。对于 C/C++，还提供语义模式（semantic mode）用于精确的类型推断。

核心能力一览

Code-Graph-RAG 提供了丰富的命令行交互能力：

• 自然语言查询：用大白话问代码库，AI 生成 Cypher 图查询语句，返回有据可查的答案。
• 精准代码检索：按名称或语义意图查找具体函数、类或方法，直接定位源码。
• AI 辅助编辑：内置 AST 级别的精准补丁系统 —— 修改代码前先展示 diff 预览，确认后才执行，避免误改。
• 代码优化建议：基于语言最佳实践或自定义标准，对代码进行优化分析。
• 死代码检测：从入口点出发，沿调用边和引用边遍历，找出从未被调用的代码。
• AST 模式搜索：使用 ast-grep 进行结构化的代码模式搜索和批量重写。
• 动态调用追踪：通过 cgr trace 追踪测试运行或生产环境的 eBPF 数据，将运行时行为叠加到静态知识图上，揭示静态分析无法看到的动态分派。
• 实时增量更新：realtime_updater 监控文件系统变化，自动同步代码变更到图谱。
• MCP Server：作为 Model Context Protocol 服务器运行，Claude Code 等 MCP 客户端可以直接在 IDE 中查询和编辑代码库。

上手体验：门槛不低，但文档扎实

安装方式非常现代化。项目发布到 PyPI，推荐用 uv tool install 安装：

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

除了 Python 包本身，还需要 Docker（运行 Memgraph）、cmake、ripgrep 等依赖。Python 版本要求 3.12 以上。对于有经验的全栈开发者来说，这个安装过程不算复杂；但对于只想快速试试的 AI 爱好者，确实比开箱即用的 Web 应用多了几个步骤。

项目的文档质量令人印象深刻 —— 架构文档、SDK 文档、部署指南、故障排查手册一应俱全，MkDocs 构建，结构清晰。CI/CD 完善：GitHub Actions + Codecov + SonarCloud + OpenSSF Best Practices，质量门禁严格。

架构亮点

项目的 Python SDK 设计值得关注：

• Graph Loader：将代码解析结果加载到 Memgraph 的核心模块。
• Cypher Generator：将自然语言查询转换为 Cypher 图查询语言的 AI 生成器，基于 pydantic-ai 实现。
• Semantic Search：向量语义搜索能力，通过 huggingface-hub 接入 embedding 模型。

商业化探索

有趣的是，这个完全开源（MIT 许可）的项目同时在探索商业化路径 —— 提供云托管版本和本地/气隙网络部署方案，面向需要合规和托管服务的企业客户。这在开源 AI 工具中越来越常见，但也让一些社区用户保持观望态度。

总结

Code-Graph-RAG 是一个工程质量很高的开源项目，将 RAG（检索增强生成）范式从文档领域迁移到了代码理解领域。Tree-sitter + Memgraph 的组合解决了多语言 monorepo 的结构化理解问题，而 AI 辅助编辑和死代码检测等功能对大型代码库的维护者有直接价值。适合有技术背景的用户、AI/ML 开发者以及需要深度理解遗留代码库的团队。如果你的团队管理着一个复杂的多语言代码库，Code-Graph-RAG 值得加入工具箱。