Code-Graph-RAG：把整个 monorepo 变成知识图谱，再用自然语言查它

Code-Graph-RAG：把整个 monorepo 变成知识图谱，再用自然语言查它

问它"谁调用了 UserService.create_user"，它跑一条 Cypher 查询。

对代码库做 RAG 的常规做法是：切 chunk、算 embedding、相似度检索。这个方案回答不了结构问题--"哪些函数调用了 X"、"这个值从哪来流到哪"、"哪些代码是死代码"。embedding 知道哪两段代码相似，不知道谁调用谁。

Code-Graph-RAG（4,776 星，MIT，Python）换了一条路：用 Tree-sitter 把多语言代码库解析成真正的结构图--函数、类、调用边、继承边、数据流边--存进 Memgraph 图数据库，然后让 LLM 把自然语言翻译成 Cypher 图查询。它的自我定位是"The ultimate RAG for your monorepo"。

项目 2025 年 6 月创建，一年多攒到 4.8k 星。有个背景信息让我意外：funding.json 显示这个项目零外部融资，2025 年收入 $0，本质上是一个人（vitali87，4,271 个 commit）做到今天的规模。独立的工程质量做到这个程度，值得认真看。

本文提纲

  1. 管线：从源码到 Cypher 查询
  2. 一张图，14 种语言，统一 schema
  3. 运行时调用追踪：静态+动态融合的王牌
  4. 数据流与污点追踪：FLOWS_TO 边
  5. 不只读，还能改：外科手术式补丁
  6. MCP 接入 Claude Code：19 个工具
  7. 该知道的坑：诚实声明与安全公告
  8. 上手

管线：从源码到 Cypher 查询

README 里的管线一句话讲完：

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

画成图：

MERMAID_BLOCK_0

关键区别在检索方式：chunk-RAG 是"embedding 相似度"，这里是"图遍历"。"什么函数调用了 UserService.create_user"在向量库里没有答案（调用关系不是文本相似性），在图里是一条一跳的 MATCH 查询。LLM 在这个架构里的角色被刻意收窄：只做自然语言到 Cypher 的翻译，结构判断交给图引擎，答案基于真实的图结构而非模型回忆。

一张图，14 种语言，统一 schema

对 monorepo 来说，比"多语言解析"更重要的是统一 schema：Python 的函数和 TypeScript 的函数在图里是同一种节点，跨语言的调用关系是同一种边。混栈仓库（比如 Python 后端 + TS 前端 + Go 工具）可以在一张图里统一查询。

schema 本身（来自 docs/architecture/graph-schema.md）约 21 种节点类型、23 种关系类型。核心的关系类型一眼能看懂设计意图：

  • 结构：DEFINES、IMPORTS、INHERITS、IMPLEMENTS、OVERRIDES
  • 行为：CALLS、REFERENCES、INSTANTIATES
  • 数据：FLOWS_TO（污点传播）、READS_FROM / WRITES_TO（ENV、STDOUT、FILE、NETWORK 等 I/O 资源）
  • 质量：HAS_VULNERABILITY、CodeSmell、SecurityIssue 节点

语言支持分两档：14 种完全支持（Python、TypeScript、TSX、JavaScript、Rust、Go、Java、C、C++、C#、PHP、Lua、Dart，Scala 开发中），8 种基础支持走可插拔的 ast-grep 层（Ruby、Kotlin、Swift、Elixir、Haskell、Solidity、Bash、Nix）--加一门"基础"语言只需要写一个 YAML 模式文件，不用写解析器。C/C++ 和 C# 还有混合前端：tree-sitter 打底，libclang / Roslyn 补语义事实（精确的重载解析、宏处理、LINQ 查询语法）。

运行时调用追踪：静态+动态融合的王牌

这是整个项目最独特的能力，值得单独讲。

静态分析有天然盲区：接口分发、虚方法、函数指针、反射、框架路由--这些调用静态分析看不见。Code-Graph-RAG 的解法是 cgr trace：动态追踪器跑你的代码（通常是测试套件），把实际发生的调用合并回图里，标记成 CALLS 边，静态分析漏掉的打上 static_missed: true 标记。

静态图告诉你"代码看起来怎么连接"，运行时图告诉你"代码实际怎么连接"，两张图叠在一起，盲区显形。追踪器覆盖 Python、JVM、Node.js、.NET、PHP、Lua、Dart、Go、Rust、C/C++。

更进一步，它还能吃生产环境的 eBPF 持续剖析 profile（Parca、Pyroscope、OpenTelemetry 格式）：cgr trace convert --format ebpf。生产环境的真实调用路径直接进图。JS/TS 的追踪器会用 source map 把转译后的帧映射回 TS 源码。

据我了解，把静态调用图和动态 trace 在同一个知识图谱里融合的开源项目，这是第一个。

数据流与污点追踪：FLOWS_TO 边

FLOWS_TO 边沿赋值、函数参数、返回值、I/O sink 追踪值的流动，把溯源问题变成图的可达性问题：

"这个用户输入最终会不会流进这条 SQL 拼接？"--从 input 节点走到 sink 节点，存在路径就是有风险。安全审计里最耗人力的部分，变成了一次图遍历。

覆盖 10 种语言。文档里特别注明它是"intentionally conservative"（刻意保守）：过程内追踪，参数传递只跟一层。宁可漏报不误报，这个取向对安全工具是正确的。

不只读，还能改：外科手术式补丁

Code-Graph-RAG 不只是问答工具，还能驱动修改：

  • AI 代码编辑：基于 AST 的外科手术式补丁（surgical patching，用 diff-match-patch），改之前先给 diff 预览
  • 结构化搜索替换：用 ast-grep 的 AST 模式而不是文本正则做搜索替换--重构同一表达式在不同格式下的写法，AST 模式能全部命中
  • 代码优化：按语言最佳实践或你自己的编码规范建议优化
  • 死代码检测：从入口点沿调用/引用边走，走不到的就是死代码--这是图结构的直接应用

交互入口是 CLI（cgr 命令），也可以走 MCP。示例查询长这样：

> Index this repository
> What functions call UserService.create_user?
> Update the login function to add rate limiting

底层技术栈：pydantic-ai（agent 框架）、typer（CLI）、rich、UniXcoder embedding（配 Qdrant 做语义搜索，补图查询的语义维度）、watchdog（文件系统监听实时更新图）。支持多仓库共享一张图，同步一个仓库不影响其他的。

MCP 接入 Claude Code：19 个工具

对 Claude Code 用户，直接把 Code-Graph-RAG 挂成 MCP server：

claude mcp add --transport stdio code-graph-rag \
  --env TARGET_REPO_PATH=/absolute/path/to/your/project \
  --env CYPHER_PROVIDER=openai \
  --env CYPHER_MODEL=gpt-5.6-luna \
  --env CYPHER_API_KEY=your-api-key \
  -- code-graph-rag mcp-server

暴露 19 个工具，包括 query_code_graph、semantic_search、structural_search、surgical_replace_code、explain_traceback、rank_root_causes、flow_verdict。rank_root_causes 对 traceback 做根因排序，flow_verdict 回答数据流判定--而且它的返回值有三种：FOUND / NO_FLOW / UNKNOWN。覆盖不全时明确说 UNKNOWN，不假装没有流。这种工程诚实度我喜欢。

该知道的坑：诚实声明与安全公告

文档里的局限声明（这些直接影响你能不能用）：

  • ast-grep 层是"基础"档：只有扁平名称（无命名空间限定）、没有调用图解析--死代码检测会跳过这些语言的文件
  • FLOWS_TO 保守追踪：过程内、参数只跟一层
  • 依赖 Docker（Memgraph）和 cmake，不是零依赖 pip install
  • --clean 会明确警告：删的是共享图里的所有项目，不是一个

更需要重视的是安全面。过去两周连发三个安全公告，都和"对不可信仓库跑 cgr"相关：

  • v0.0.670（8 月 18 日）：修复两个链式 EXECUTE_SHELL 审批绕过 RCE（git core.sshCommand 后门路径、find -exec 绕过路径），官方原话"强烈建议所有对不可信仓库运行 cgr 的用户升级"
  • v0.0.639（8 月 14 日）：运行时调用追踪扩展到 Go/JVM/Node.js/.NET/PHP/Lua/Dart
  • v0.0.589（8 月 10 日）：修复 structural_search/structural_replace 里跟随符号链接的任意文件读写（CVSS 7.1）

两周三个 RCE 级公告，说明两件事：agent 的 shell 工具面确实是攻击面（这个教训对所有 agent 工具通用）；维护者响应很快，修得也快。如果你用它跑陌生代码，务必升到最新版。

上手

前置：Python 3.12+、Docker、cmake、ripgrep，加一个 API key（OpenAI/Gemini，或 Ollama 跑本地模型免费）：

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

# 起内置的 Memgraph + Qdrant 栈，不需要 compose 文件
cgr daemon up

# 解析仓库进图，然后查询
cgr start --repo-path /path/to/repo --update-graph
cgr start --repo-path /path/to/repo

四条命令从安装到能查。发布节奏非常快（版本号到 v0.0.670，几天一版），仓库质量信号齐全：OpenSSF Scorecard、SonarCloud、Codecov，还有个 claude-code-review.yml CI 工作流--Claude 在 CI 里审 PR。企业版提供托管云和本地 air-gapped 部署。

参考文档与链接

你的 monorepo 多少种语言？查调用关系现在用什么办法？评论区聊聊。觉得静态+动态融合这思路对的，点个赞。

作者: itech001
来源: 公众号：AI人工智能时代(the-ai-era)
网站: https://www.theaiera.top/
关注每日最新AI新闻和技术博客，主页有更多的文章的AI 技术参考：https://www.theaiera.top

本文首发于 AI人工智能时代，转载请注明出处。

posted @ 2026-08-22 22:50  iTech  阅读(9)  评论(0)    收藏  举报