Code-Graph-RAG

Code-Graph-RAG

Code-Graph-RAG 使用 Tree-sitter 解析多语言代码库，并在可用时借助编译器级前端和运行时跟踪增强解析效果；它在无需服务器的嵌入式图数据库中构建代码结构的知识图谱，让你能够用通俗英语查询、编辑和优化代码。它可在一个统一的图架构下处理包含多种语言的单体仓库。

1. 索引： cgr start --update-graph 解析仓库并构建知识图谱（速度更快）

2. 提问： cgr start 基于该图谱回答问题并编辑代码

最新动态 🔥

• 安静模式增强：CLI 的 --quiet 标志现在会隐藏死代码和重复项的扫描提示，使输出更加简洁。
• 上下文预算修复：系统现在能够正确处理目标内容超出已分配预算的情况，避免出现意外行为。
• 代码质量：现已报告会影响方法调用的装饰器和修饰符变更，并确保正确加载子模块语法。
• CGR 清理功能：新增 cgr prune 功能，可移除根目录已不存在的项目。

完整历史记录请参阅 NEWS.md。

功能介绍

将 Code-Graph-RAG 指向一个代码仓库，它会读取每个源文件，提取函数、类、方法、模块及它们之间的关系，并将结果存储为相互关联的图。图构建完成后，你可以：

• 用自然语言询问有关代码库的问题，并获得基于实际结构的答案。
• 按名称或意图检索任何函数、类或方法的实际源代码。
• 通过 Agent 编辑代码，使用基于 AST 的精准补丁，并在任何更改生效前预览差异。
• 根据语言最佳实践或你自己的编码规范优化代码。
• 从入口点沿调用和引用边遍历，查找死代码。
• 使用 ast-grep 按 AST 模式进行结构化搜索和重写。
• 叠加运行时行为：使用 cgr trace 跟踪测试运行（或提取生产环境的 eBPF 配置文件），并将实际发生的调用合并到图中，从而揭示静态分析无法看到的分派。

工作原理

系统由两个组件组成：

1. 多语言解析器。 基于 Tree-sitter 的解析器会读取代码库，并按照统一的语言无关架构，将函数、类、方法、模块及其关系载入图中。在有可用工具链的情况下，编译器级前端会叠加精确事实（C/C++ 使用 libclang，Go 使用 go/types，C#、Java 和 Python 则可选择使用 Roslyn、javac 和 Jedi）；动态跟踪会合并运行时观察到的调用。Tree-sitter 仍是核心：跟踪只能看到实际运行的代码，而编译器前端只能覆盖其工具链能够构建的部分。
2. RAG 系统（codebase_rag/）。交互式 CLI，可将自然语言转换为 Cypher 查询、检索匹配的代码，并驱动 AI 驱动的编辑和优化。

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

默认情况下，图存储在嵌入式 SQLite 文件中。Memgraph 和 Neo4j 是可选后端，运行相同的 Cypher；图后端对它们进行了比较。

如需了解完整概况，请参阅架构概览和图架构。

支持的语言

全面支持 Python、TypeScript、TSX、JavaScript、Rust、Go、Java、C、C++、C#、PHP、Lua、Dart 和 Julia。Scala 正在开发中；Ruby、Kotlin、Swift、Elixir、Haskell、Solidity、Bash 和 Nix 则通过可插拔的 ast-grep 层提供结构化支持（包括模块、函数、类——仅限语言本身支持这些结构的情况）和导入。有关各语言的具体能力，请参阅语言支持矩阵。

安装

cgr 已发布到 PyPI。使用 treesitter-full（tree-sitter 语法）、ast-grep（Ruby、Kotlin、Swift、Elixir、Haskell、Solidity、Bash、Nix）和 semantic（向量搜索）附加项进行系统级安装：

# with uv (recommended)
uv tool install "code-graph-rag[treesitter-full,ast-grep,semantic]"

# or with pipx
pipx install "code-graph-rag[treesitter-full,ast-grep,semantic]"

我会获得哪个版本？

有三个版本序列，它们有意采用不同的发布节奏：

位置	跟踪内容
git 标签	每个版本，每次合并对应一个
GitHub Releases（二进制文件、签名）	每第 50 个版本，以及任何安全修复、破坏性变更或标记为 release now 的合并
PyPI	每第 50 个版本，以及任何安全修复、破坏性变更或标记为 release now 的合并

因此，main 上最新的标签通常会领先于最新的发行版，往往相差数十个补丁版本；只有在刚发布之后，两者才会一致。这不是卡住了，只是发布节奏有意不同。安全修复、破坏性变更或维护者标记为 release now 的合并都不会等待发布节奏：每次都会立即发布一个发行版并上传到 PyPI。

uv tool install 和 pipx install 会安装最新的 PyPI 版本，也就是最新的发行版，而不是最新的标签。中间标签的作用是让每次合并都可追溯；二进制文件和 PyPI 上传则遵循上述发布节奏。

如需运行比最新发行版更新的代码，请从 git 安装：

uv tool install "code-graph-rag[treesitter-full,ast-grep,semantic] @ git+https://github.com/vitali87/code-graph-rag@main"

如需升级现有安装，请运行 uv tool upgrade code-graph-rag（使用 pipx 时运行 pipx upgrade code-graph-rag；如果是从 git 安装，则运行 pipx reinstall code-graph-rag）。升级介绍了其他安装方式。

你还需要 Python 3.12+ 和 ripgrep。默认情况下，图存储在嵌入式 SQLite 文件中，因此无需运行数据库服务：不需要 Docker，也不需要 cmake。Memgraph 和 Neo4j 仍可作为可选后端使用（图后端）。完整的先决条件、源码安装和环境配置请参阅安装指南。

说明

wheel 是纯 Python（py3-none-any），因此可安装在任何配备 Python 3.12 或更高版本的平台上。较旧的系统解释器（Debian Bookworm 附带 3.11）需要显式指定解释器；相关命令请参阅安装。

快速开始

# Parse a repository into the graph, then query it
cgr start --repo-path /path/to/repo --update-graph
cgr start --repo-path /path/to/repo

图会写入 ~/.cgr/graph.sqlite（设置 SQLITE_GRAPH_PATH 可更改路径）。 如需改用 Memgraph，请通过 memgraph extra 安装驱动，设置 GRAPH_BACKEND=memgraph，然后运行 cgr daemon up 启动打包好的 Memgraph + Qdrant 堆栈。

对每个要建立索引的仓库重复运行第一条命令；图是共享的，同步一个项目不会影响其他项目。如需从空图开始，请添加 --clean——它会删除共享图中的所有项目，而不只是当前项目；如果会删除其他项目，它会先要求确认。

默认索引不会包含可选的捕获组；添加 --capture 或设置 CGR_CAPTURE 即可包含它们。

快速开始指南会带你在五分钟内完成解析、查询和导出。

MCP 服务

Code-Graph-RAG 以 MCP 服务的形式运行，因此 Claude Code 和其他 MCP 客户端可以直接查询和编辑你的代码库。设置方法请参阅 MCP 服务指南。

文档

入门

• 安装
• 快速入门
• 配置

用户指南

• CLI 参考
• 交互式查询
• 代码优化
• 死代码检测
• 动态调用追踪
• 图导出
• 实时更新
• C/C++ 语义模式
• MCP 服务
• 跨语言移植

架构

• 概览
• 图模式
• 图后端
• 语言支持
• 数据流边

Python SDK

• 概览
• 图加载器
• Cypher 生成器
• 语义搜索

进阶

• 添加语言
• 忽略模式
• 构建二进制文件
• 故障排除

企业服务

Code-Graph-RAG 是开源且免费使用的。对于有更多需求的组织，我们提供全托管云解决方案和本地部署：

• 云托管部署：为图数据库和 AI Agent 连接提供托管云基础设施。无需承担基础设施管理工作，我们负责扩缩容、更新和可用性，让您的团队专注于构建。
• 本地部署与隔离网络部署：在您自己的环境中完整部署 Code-Graph-RAG，包括隔离网络。为受监管行业和安全敏感型组织提供完全的数据自主权。

我们还提供定制开发、集成咨询、技术支持合同和团队培训。

在 code-graph-rag.com 查看方案与定价

参与贡献

贡献指南请参阅 CONTRIBUTING.md。适合初次提交 PR 的工作可以从 TODO 问题中寻找。

支持

遇到问题或有疑问时，请先查看故障排除指南，然后再提交问题。

如果 cgr 对您有帮助，请考虑通过 GitHub Sponsors 认捐支持。cgr 会在 cgr --version 页面以及大多数命令在终端中执行完毕后显示该页面链接；设置 CGR_SPONSOR_PLEDGE=false 可隐藏这行内容。

无障碍访问

ACCESSIBILITY.md 介绍了 cgr 及其文档对使用辅助技术或替代设置人士的支持情况、已知限制及其解决方法，以及如何报告访问障碍。

许可证

MIT。请参阅 LICENSE。

第三方组件及其许可证信息已在致谢页面列出。