repo-graph

为 AI 编程助手提供的结构化图谱记忆。 映射你的代码库。按结构导航。只读重要的内容。

repo-graph 为 LLM 提供了一份代码库地图——包括实体、关系和流程——这样它们就可以直接导航到正确的文件，而无需先阅读所有内容。

repo-graph 不会用整个代码库淹没 LLM 的上下文窗口（或者寄希望于它猜对），而是构建了一个轻量级的图谱，展示了代码库中存在什么、事物如何连接以及入口点在哪里。LLM 查询该图谱，找到它所需的最少文件集，并仅读取这些文件。

演示

https://github.com/user-attachments/assets/a1e4171b-b225-40d4-9210-39453e14b76a

https://github.com/user-attachments/assets/fc3191e5-fc35-4bd7-8372-72af55995883

同样的 Bug，同样的模型，同样的提示词——唯一的区别是是否安装了 repo-graph。

任务： 修复一个 Go + Angular 单体仓库（566 个节点，620 条边）中反向的比较运算符。

Token 消耗减少 2.5 倍。速度提升约 9 倍。同样的正确修复。

测试是如何进行的

两次运行均使用相同的条件以确保比较公平：

• 相同模型：Claude Opus，100%（无 Haiku 路由）

• 相同提示词：“最近创建的群组显示为已关闭，而旧群组显示为已开启。这是反向的——新群组应该对成员开放以加入。找到并修复这个 Bug。”

• 全新上下文：每次运行都从 /clear 开始，没有之前的对话

• 无其他工具：两次运行都移除了 CLAUDE.md、插件、钩子和所有其他 MCP 服务器——唯一的变量是是否安装了 repo-graph

• 无提示：提示词描述的是症状，而不是位置——Claude 必须自己找到 group_controller.go:57

如果没有 repo-graph，Claude 会 grep 关键字、读取文件、再次 grep、读取更多文件，最终缩小到 Bug 所在位置。使用 repo-graph，Claude 调用 flow("groups")，直接获取准确的处理函数和文件，读取它并修复它。

浏览 预生成的示例，包括 FastAPI、Gin、Hono 和 NestJS —— 无需安装即可查看真实的图谱输出。

问题所在

处理代码的 LLM 将大部分上下文浪费在定位上：

• 阅读最终发现无关的文件

• 遗漏不同语言组件之间的连接

• 不知道功能从哪里开始或它涉及什么

• 在只需要 5 个文件时加载了 50 个文件

这既昂贵又缓慢，并且随着代码库的增长情况会变得更糟。

repo-graph 如何解决它

repo-graph 会扫描你的代码库一次，并构建一个包含以下内容的图谱：

• 实体：模块、包、类、函数、路由、服务、组件

• 关系：导入、调用、处理、定义、包含

• 流程：从入口点到数据层的端到端路径

然后它公开了 12 个 MCP 工具，让 LLM 可以：

1. 定位 — “这个仓库里有哪些语言？主要功能是什么？”

2. 导航 — “追踪从路由到数据库的登录流程” / “UserService 和支付 API 之间的最短路径是什么？”

3. 范围界定 — “我需要阅读多少行代码才能理解这个功能？” / “给我修复这个 Bug 所需的文件”

4. 评估 — “更改此函数的影响范围有多大？” / “哪些文件是最大的维护风险？”

LLM 只需几百个 Token 即可获得结构化上下文，而无需阅读数千行代码。

支持的语言

多个分析器可以匹配同一个仓库（例如：Go 后端 + Angular 前端 + SCSS）。每个分析器将其节点和边贡献到一个统一的图谱中。

安装

pip install mcp-repo-graph

需要 Python 3.11+。唯一的运行时依赖是 mcp[cli]。

快速开始

1. 生成图谱

repo-graph-generate --repo /path/to/your/project

这将扫描代码库并将图谱数据写入目标仓库内的 .ai/repo-graph/。

2. 连接到你的 AI 助手

添加到你的 MCP 配置中：

Claude Code (~/.claude/claude_code_config.json 或项目 .mcp.json)：

{
  "mcpServers": {
    "repo-graph": {
      "command": "repo-graph",
      "args": ["--repo", "/path/to/your/project"]
    }
  }
}

使用环境变量：

{
  "mcpServers": {
    "repo-graph": {
      "command": "repo-graph",
      "env": { "REPO_GRAPH_REPO": "/path/to/your/project" }
    }
  }
}

3. 使用它

AI 助手现在可以访问所有 12 个工具。它可以回答的查询示例：

• “这个代码库是做什么的？” -> status 工具

• “追踪结账流程” -> flow 工具

• “如果我更改 UserService，什么会坏掉？” -> impact 工具

• “修复这个 Bug 我需要哪些文件？” -> minimal_read 工具

• “这个文件太大了，我该如何拆分它？” -> split_plan 工具

• “可视化展示认证流程” -> graph_view 工具

4. 使用 git 钩子保持更新（推荐）

将 repo-graph-generate 添加到 pre-commit 钩子中，以便图谱自动保持最新——无需在重新生成上消耗 LLM 上下文：

# .git/hooks/pre-commit (or add to your existing hook)
#!/bin/sh
repo-graph-generate --repo .
git add .ai/repo-graph/

chmod +x .git/hooks/pre-commit

每次提交都会保持图谱为最新状态。LLM 始终拥有最新的地图，而不会在 generate 上浪费任何 Token。

提示： 如果你不希望图谱数据进入版本控制，请将 .ai/repo-graph/ 添加到 .gitignore 并跳过 git add 行——图谱将仅在本地存在。

MCP 工具参考

生成

导航

上下文预算

健康分析

工作原理

1. 检测 — scan_project_dirs() 查找项目根目录（包括单体仓库布局，如 packages/*, apps/*, services/*, src/*）。每个分析器都会检查其标记文件。

2. 扫描 — 匹配的分析器使用正则表达式启发式方法提取实体和关系。无需 AST 解析，无需外部工具链，无需构建步骤。

3. 合并 — 所有分析器结果合并为一个图谱。节点按 ID 去重，边按 (from, to, type) 去重。

4. 服务 — MCP 服务器将图谱加载到内存中，并公开基于 BFS 的遍历工具。

图谱数据格式

生成的文件位于目标仓库内的 .ai/repo-graph/：

• nodes.json — [{id, type, name, file_path}, ...]

• edges.json — [{from, to, type}, ...]

• flows/*.yaml — 带有有序步骤序列的命名功能流程

• state.md — 用于快速定位的人类可读快照

边类型：imports, defines, contains, uses, calls, handles, handled_by, exports, includes。

添加新的分析器

创建 repo_graph/analyzers/<language>.py：

from .base import AnalysisResult, Edge, LanguageAnalyzer, Node, scan_project_dirs, rel_path, read_safe

class MyLangAnalyzer(LanguageAnalyzer):

    @staticmethod
    def detect(repo_root):
        # Check for language marker files
        return any(
            (d / "my-marker").exists()
            for d in scan_project_dirs(repo_root)
        )

    def scan(self):
        nodes, edges = [], []
        # ... scan files, extract entities, build relationships ...
        return AnalysisResult(
            nodes=nodes,
            edges=edges,
            state_sections={"MyLang": f"{len(nodes)} entities\n"},
        )

    # Optional: file-level analysis for bloat_report / split_plan
    def supported_extensions(self):
        return {".mylang"}

    def analyze_file(self, file_path):
        # Return dict with function/method sizes, class counts, etc.
        pass

    def format_bloat_report(self, analysis):
        # Format the analysis dict into a human-readable string
        pass

通过将其添加到 _analyzer_classes() 中，在 analyzers/__init__.py 中注册它。

许可证

MIT

支持

如果 repo-graph 为你节省了时间，请考虑请我喝杯咖啡。