repo2graph

向代码库提问，即可获取能够回答问题的源代码。每个代码块都以 [cite: path:start-end] 标注，且整个回复都在工具强制执行的令牌数上限内。 一次 tree-sitter 扫描会记录谁调用谁、谁导入了什么，以及 git 中哪些文件经常一起变更。 检索从 BM25 匹配开始，并沿着这些关联继续查找。

它不需要模型、API 密钥、语言服务器或数据库。构建、查询和 MCP 服务都不会发起网络调用；例外情况只有 rag --answer（选择启用后会将内容包发送给大模型）、repo2graph github 和使用 GitHub 规范作为目标的 rag/query（两者都会克隆仓库），以及 --vectors/embed（首次使用时会下载嵌入模型）。解析器也是这一承诺的一部分： tree-sitter-language-pack 固定在 1.0 以下，因此每种语法都会编译进已安装的 wheel，而不是在首次解析时才下载 — 详见 SECURITY.md。你可以通过 CLI 使用它，将其作为 Claude Code 或 Cursor 中的 MCP 服务，或将其用作 GitHub Action。

试用

uvx repo2graph demo                                   # bundled example repo, five questions answered
uvx repo2graph build . -o .r2g                        # index your own code
uvx repo2graph rag "how does routing work" -o .r2g    # a cited, budget-bounded context pack

通过 MCP 为 Agent 提供同样的功能：

claude mcp add repo2graph -- uvx --from "repo2graph[mcp]" repo2graph-mcp .

Cursor、Claude Desktop 和其他客户端：docs/mcp.md。包含预期输出的分步指南：demo in docs/cli.md。它在十三个知名仓库上生成的内容 — Django、FastAPI、React、Kubernetes、Linux 等，每个仓库都固定在指定的提交版本，并附有可复现结果的命令：examples/。

在 VS Code 中，扩展 editors/vscode/（预览版，由源代码构建）通过同一个 MCP 服务，显示光标所在符号的调用方、被调用方、基类和共同变更文件。

它比 grep 更好吗？

对于跨文件的结构性问题，是的。对于单文件的词法查询，不是 — grep 是更好的工具。 两方面的评估均基于针对 Flask、 requests、FastAPI 和 Hono 的 40 个词法问题与 40 个结构性问题；repo2graph 并未针对这些问题进行调优。评分依据是能够回答问题的定义，并且每种检索器都使用相同的令牌预算 （方法、完整表格和分析；原始数据见 results_holdout_final.json）。

repo2graph 的优势：跨文件结构性问题

grep 在结构上无法遍历依赖边、计算反向调用闭包或追踪跨模块委托。对于证据可证实地跨越跨文件图边的问题：

预算	repo2graph	仅词法搜索	grep，然后阅读匹配项附近的内容
2,000 个令牌	29%	24%	14%
4,000 个令牌	60%	48%	21%
8,000 个令牌	79%	55%	38%

发挥作用的是图结构，这才是重要的对比：与关闭扩展功能时使用同一检索器的结果相比，扩展分别提升了 +5/+12/+24 个百分点。与 grep 相比，优势为 +15/+39/+41 个百分点 — 随着预算增加，优势不减反增，因为无论给 grep 多大空间，它都没有可追踪的边。它在每种预算下所用的令牌数也少于 grep，平均分别少 7、7 和 398 个令牌，因为返回带引用的定义比返回每个文本匹配项周围的上下文范围更精简。

grep 的优势：单文件词法问题

预算	repo2graph	grep，然后阅读命中内容的上下文
2,000 个 token	17%	28%
4,000 个 token	29%	48%
8,000 个 token	45%	59%

对于证据位于单个文件中的纯词法问题，文本搜索正是 grep 的最佳场景，而且差距确实存在：−11/−19/−14 个百分点。我们还没有弥合这一差距。剩下的原因似乎是词汇不匹配，而非排序问题——问题中写的是“datetime”，代码中写的却是“timestamp”——这也是为什么 稠密向量路径能在 8,000 个 token 时将差距缩小到 −2 个百分点，而进一步调整 BM25 并没有效果。这条路径需要下载模型，因此是可选的 （pip install "repo2graph[rag]"），零依赖的默认配置仍然是默认选项。 这个额外依赖会引入 PyTorch，而在 Linux 上会带来 NVIDIA CUDA wheel（数 GB）；首次使用时会从 Hugging Face 获取模型。在采用模型之前，请自行审查其许可证和训练数据。 缓存模型后，设置 HF_HUB_OFFLINE=1，即可让后续运行不再发起请求。

如果不想承担这么多开销——例如在 CI 运行器上——可以运行 pip install "repo2graph[rag-static]"，并使用 --embed-backend static，无需 torch 即可进行稠密检索：model2vec 是一个 token→向量表，并进行均值池化，因此推理只需 numpy；它占用约 60 MB 的依赖包空间和约 31 MB 的模型空间。 它是另一种模型（256 维，而非 384 维），并非运行同一模型的廉价方式，因此检索结果会有所不同——上面的数据对应的是 rag 后端。在查询端传入与 embed 时相同的 --embed-backend：记录的模型 ID 会按后端添加前缀，因此如果不匹配，系统会拒绝操作，而不是静默融合。

repo2graph 在 Agent 场景中的优势：更少轮次

在模拟的 Agent 工作流中（通过 scripts/agent_eval.py 执行 search → read → answer）。没有模型参与其中——“Agent”是基于真实 ripgrep 和真实索引的确定性策略：

任务集	方法	成功率	平均轮次	平均 token 数	每次读取的精确率
结构类（40）	repo2graph	40%	1.9	2,590	12.0%
结构类（40）	ripgrep	10%	2.5	586	29.0%
词法类（40）	repo2graph	20%	1.4	2,070	21.7%
词法类（40）	ripgrep	18%	3.0	740	89.1%

结构类任务的成功率是 ripgrep 的 4 倍，而且它一两轮就能得出答案，而 grep 需要三轮。轮次是变化最大的一项——结构类任务从 3.1 降至 1.9——因为更精准的种子排序让答案更常出现在第一组结果中，而对 Agent 来说，节省一轮比节省一个 token 更有价值。它并不省资源：结构类任务的 token 数是 grep 的 4.4 倍，词法类任务则是 2.8 倍，并且两类任务中 grep 的每次读取精确率都更高。repo2graph 通过上下文换取召回率和更少轮次；预算相同的对比见上方的单次查询表格。

完整起见，本页此前报告的 35+10 题集合——自这些表格的第一个版本起就已公开，因此它是回归测试集，而非证据——现在的结果为：词法类任务中 repo2graph 为 44/63/80%，grep 为 35/61/72%；结构类任务中 repo2graph 为 60/80/100%，grep 为 20/20/70%。这些数字看起来更好，这正是上方引用留出集结果的原因。

它能做到而 grep 做不到的事：

• 一步查找关系。 repo_neighbours 会返回某个符号的调用方、被调用方、基类和定义文件，每项都带有行号。每条边都有一个 confidence：如果某个名称可能对应多个定义，就会标记为 ambiguous，并按 1/n 计算权重，而非猜测。
• 严格的上限。 返回前会对结果包进行测量、截断并再次测量（通过 MCP 最多 12k 个 token），因此 Agent 无法通过此工具让自己的上下文溢出。
• 通过图查找反向闭包。 repo_blast_radius 会遍历依赖某个符号的内容，并受跳数和访问上限约束，每条边都附有引用。

它与 Serena、Aider 的 repo map、CodeGraphContext、code-graph-rag、Sourcegraph、Cursor 的索引和 Claude Code 自带的搜索功能，以及依赖图工具 Madge、dependency-cruiser 和 CodeSee 的比较（包括何时应改用这些工具）： docs/comparison.md。想找 Sourcetrail 的替代品？它并非可直接替换的产品——没有交互式桌面界面——比较文档说明了它采用的替代方案。

五个入门问题

向你的代码仓库提问	图能补充的信息
Where is authentication enforced?	守卫本身，以及调用它的路由（--framework-edges 会列出每个端点）
What calls <function>?	指向该函数的 CALLS 边，每条边都带有置信度分数
What tests cover <module>?	从测试模块指向被测代码的 IMPORTS 边
What would be affected by changing <api>?	定义本身，以及通过指向它的 CALLS 边找到的直接调用方（说明节点）
Trace <a request> from route to persistence.	处理程序及其被调用方，逐跳展示，每个代码块都标明文件和行号

GitHub Action

- uses: actions/checkout@v4
  with: { fetch-depth: 0 }   # full history, so CO_CHANGE edges are meaningful

- uses: Srinivasan-78/repo2graph@v4
  with:
    git-history: "500"
    commit-branch: graph     # optional: publish graph.html to a browsable branch

@v4 会跟随每个 4.x 版本发布；若要手动升级，请固定到精确标签（@v4.1.0）。此 Action 从不调用大模型。输入和输出见：docs/cli.md。

命令

命令	说明
repo2graph build <path> -o .r2g	将代码库解析为图和分块（--incremental、--git-history N、--framework-edges）
repo2graph query "<q>" -o .r2g	BM25 搜索加一次图跳转
repo2graph rag "<q>" -o .r2g	有预算限制且带引用的上下文包（--answer 会将其发送给大模型：需主动启用，这是唯一会将代码发送到任何地方的路径）
repo2graph explain <edge|node|retrieval>	说明边为何存在，或某个代码块为何被检索到
repo2graph github <owner/repo> -o <dir>	无需本地克隆即可获取、构建并清理
repo2graph demo	为捆绑的示例建立索引，并回答上面的五个问题
repo2graph map、repo2graph stats、repo2graph index-status、repo2graph embed	重新生成 graph.html，报告数量和新鲜度，并添加可选的稠密向量
repo2graph diff	比较两次构建之间的结构变化：新增、删除和重命名的符号、边，以及调用者发生变化的对象
repo2graph doctor、repo2graph bug-report、repo2graph explain-path、repo2graph completion	诊断设置、生成保护隐私的错误报告包、说明某条路径为何（未）建立索引、提供 Shell 补全
repo2graph-mcp <path>	stdio MCP 服务：repo_map、repo_search、repo_neighbours、repo_blast_radius 以及另外五个工具

完整标志：docs/cli.md。Python API：docs/python-api.md。 最多 50,000 个文件的构建成本：benchmarks/perf/README.md。

它无法做到什么

• 按类型解析调用。 调用按名称匹配，并根据类、文件、导入和目录进行范围限定。对于类型未知的接收者，x.get() 会被记录为低置信度推测，而非事实。若要获取精确引用，请使用语言服务器工具，或将 SCIP 索引（由 scip-python、scip-typescript 等工具生成）交给 build --scip index.scip，以精确解析该索引涵盖的调用和基类；请参阅docs/architecture.md。
• 识别动态分派、反射或计算所得的导入。 缺少一条边并不能证明不存在调用。
• 跨越语言边界（例如 Python 通过绑定调用 C++）。
• 识别通过调用注册的路由。 build --framework-edges 会将由装饰器声明的路由关联到其处理程序（FastAPI、Flask、Starlette、Sanic、NestJS），并为每个端点添加一个节点，因此 GET /users/{id} 是可以查询的对象。Express、Hono 和 Django 的 urlpatterns 则通过调用来注册，例如 app.get("/x", handler)；其中处理程序是一个参数，通常是内联函数，因此不会生成边。

Python、JS、TS、TSX、Go、Rust、Java、Ruby、C、C++、C#、PHP、Kotlin、Swift、Scala、Bash、Lua、Objective-C 和 HCL（Terraform）均会提取符号、调用和类，此外还包括 Vue 和 Svelte 组件的 <script> 代码块以及 Jupyter 笔记本的代码单元。其他所有文件仍会作为文本建立索引。那些会导致解析失败的特定情况——反射分派、字符串键控注册表、barrel 重新导出——都作为已知失败案例固定在合成回归测试套件中；各语言的覆盖率评分则参差不齐，详见docs/architecture.md §4。

这十九种语言中，只有两种在真实代码库上进行了基准测试：Python（Flask、requests、FastAPI）和 TypeScript（Hono）。其余语言均应视为已解析但未经测量。这绝非形式问题——检索基准测试在查看唯一的 TypeScript 代码库时，立即发现了两个解析缺口，其中一个掩盖了 Hono 的整个公共 API；如果没有真实代码库可供提问，这两个问题都不会显现。

状态

3.x CLI、MCP 工具和输出架构遵循语义化版本规范。默认路径在本地运行，不发送遥测数据，并始终确保密钥不会出现在 Agent 回复中 （哪些内容绝不会离开你的设备、 如何排除凭据文件、 报告漏洞）。项目提供了用于构建只读、非 root 本地镜像的 Dockerfile（.github/SECURITY.md）。

平台与环境要求

环境	状态	详情
Python	3.10 – 3.14	已在 CI 中针对 Linux、macOS 和 Windows 进行了测试（15 种组合）。尚未测试 Python 3.15+。请注意，3.10 将于 2026 年 10 月结束生命周期；它仍是受支持的最低版本，但建议升级。
Linux (glibc)	支持（glibc ≥ 2.34）	预编译的 tree-sitter-language-pack 语法轮子要求 glibc ≥ 2.34（Ubuntu 22.04+、Debian 12+、RHEL 9+、Amazon Linux 2023+）。
旧版 Linux	不支持轮子	RHEL 8、CentOS 8、Amazon Linux 2、Debian 11 和 Ubuntu 20.04 搭载的 glibc < 2.34。轮子无法加载；请使用 glibc 2.34+ 容器，或从源代码编译语法。
Alpine / musl	不支持轮子	不提供适用于 musl libc 的预编译语法轮子。请使用 glibc 容器，或使用 C 工具链构建。
macOS / Windows	完全支持	已在 macOS 12+（Apple Silicon 和 Intel）以及 Windows 10/11（UTF-8 和 CP1252 代码页）上测试。

运行 repo2graph doctor 诊断环境和平台支持情况。

安全与维护方针

• 单一维护者： repo2graph 由一位作者（@Srinivasan-78）开发和维护。
• 自动化门禁： 拉取请求必须通过自动化 CI 检查（ruff、mypy、多操作系统测试矩阵、合成回归基准测试）。
• 审查政策： 拉取请求合并到 main 无需第三方审查批准。
• 提交签名： 目前未强制要求对 main 上的提交进行签名。
• 完整性： 发布到 PyPI 的版本附带来源证明。CI 和贡献者使用的 uv.lock 会通过哈希固定每个依赖项（uv sync --frozen）；普通的 pip install repo2graph 会在 pyproject.toml 中指定的版本范围内自行解析版本，且不会读取该文件。

贡献

git clone https://github.com/Srinivasan-78/repo2graph && cd repo2graph
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
make lint format-check typecheck test

请从 develop 分支创建分支。请先阅读 .github/CONTRIBUTING.md 和 docs/architecture.md。目前最有帮助的贡献是为检索基准测试新增 问题，尤其是针对你熟悉的代码库。所有文档：架构、CLI、 MCP、Python API、对比。

采用 MIT 许可证。