repograph

RepoGraph

在 2 秒内将任意代码库转化为交互式架构图。无需服务器，充分保护隐私，专为 Claude 和 Claude Code 打造。

👉 试用交互式在线演示（zustand 的架构图，由一条命令生成）

在修改代码前，先找出关键文件。RepoGraph 会扫描本地导入关系，按目录和可能的架构层对源文件分组，并生成交互式 HTML 图。目录聚类和工具文件折叠功能可避免共享辅助文件让视图变成一团乱麻。三个 MCP 工具可让 Claude 检查架构，并追踪拟议变更的影响。

“2 秒”描述的是快速上手体验，并非经测量的性能保证。扫描耗时和 HTML 大小取决于代码库；较小的图可能约为 40 KB。无需账户、服务器或配置文件。交互式地图打开时会从公共 CDN 下载固定版本的 Cytoscape 和布局脚本；RepoGraph 不会发送源代码或图数据。首次打开时必须能够访问 CDN 脚本。导出 SVG、JSON 和 Mermaid 格式无需浏览器 CDN 脚本。

快速开始

npx repograph-cli .

打开打印出的 file:///.../repograph.html 链接。单击文件可查看以青色标出的传入调用方，以及以红色标出的传出依赖。双击目录框可将其折叠或展开。按 f 可让图适应视口大小。搜索会在完整文件路径中匹配子序列；小地图可帮助你在大型图中跳转。

需要 Node.js 18 或更高版本。扫描过程始终在你的设备上进行。HTML 中包含文件路径和图数据，因此分享时应将其视为代码库信息。首次打开交互式地图时，需要能够访问 CDN 脚本。RepoGraph 不会发送源代码或图数据。导出 SVG、JSON 和 Mermaid 格式无需浏览器 CDN 脚本。

CLI 参考

repograph [path] [options]
repograph mcp

Options:
  -o, --output <file>       Write to a file
  --theme <theme>           dark | light | matrix (default: dark)
  --max-depth <n>           Maximum directory nesting (default: 6)
  --no-collapse-utils      Show utility candidates immediately
  --format <format>        html | json | mermaid | svg (default: html)
  -V, --version            Show version
  -h, --help               Show help

路径默认为 .。HTML 默认输出到当前工作目录下的 ./repograph.html，写入后会打印其绝对文件 URL。除非指定 --output，否则其他格式会输出到 stdout。输出目录会自动创建。--max-depth 0 只扫描根目录中的文件。

npx repograph-cli ./my-app --output ./architecture.html --theme matrix
npx repograph-cli . --format json > graph.json
npx repograph-cli . --format mermaid --output architecture.mmd
npx repograph-cli . --format svg --output architecture.svg
npx repograph-cli . --max-depth 10 --no-collapse-utils

静态 SVG 会将文件按 entry → business → unknown → data → util 列排列。Mermaid 导出会保留嵌套的目录子图。两种格式都包含工具候选项；HTML 默认隐藏已折叠的工具文件及其边。

与 Claude 搭配使用

从 MCP Registry 安装

RepoGraph 已作为 io.github.Karry1123/repograph 列入官方 MCP Registry。支持 Registry 的客户端可通过该名称安装；也可使用下方的 Claude 手动配置方式。

Claude Desktop

将以下条目添加到 claude_desktop_config.json，并与现有服务合并：

{
  "mcpServers": {
    "repograph": {
      "command": "npx",
      "args": ["-y", "repograph-cli", "mcp"]
    }
  }
}

重启 Claude Desktop，然后提问：“扫描 /absolute/path/to/project 中的代码库，并显示修改 src/core/graph.ts 的影响。”请使用绝对代码库路径；MCP 服务启动时的工作目录可能不同。Windows 路径同样适用，例如 JSON 中的 F:\\RepoGraph。

Claude Code

claude mcp add repograph -- npx -y repograph-cli mcp

让 Claude 在重构前生成架构图，或在编辑模块前找出它的所有传递调用方。MCP 模式使用 stdio 传输协议，且仅将错误写入 stderr。

工具

工具	参数	结果
scan_repository_graph	path（仓库根目录的绝对路径）、maxDepth（整数，默认值为 6）、collapseUtils（布尔值，默认值为 true）	完整的 ArchitectureGraph JSON：节点、边、嵌套集群和指标。用于查看结构和枢纽文件。
generate_architecture_html	path、outputPath（默认值为 ./repograph.html，相对于 path）、theme（dark / light / matrix）	写入独立的交互式地图；返回 { success, filePath, nodeCount }。适用于需要可视化的场景。
query_impact_path	path、changedFile（相对于仓库的路径，例如 src/core/graph.ts）	返回直接和传递调用方及其 BFS 深度、受影响集群和影响范围。编辑或删除文件前使用。

每个工具都会在每次调用时对 path 执行全新的静态扫描，因此无需预先扫描。除 generate_architecture_html（会写入一个文件）外，所有工具均标注为 readOnlyHint: true。

生成 HTML 时，相对 outputPath 会以仓库路径为基准解析。绝对输出路径则直接使用。工具使用的实用工具扇入阈值为 15。找不到变更文件时会返回错误，并附上最接近的匹配 ID。transitiveDependents 包含深度为 1 的直接调用方；blastRadius 统计受影响文件的唯一数量，不包括变更文件本身。

地图的工作原理

导入会转换为边

每个源文件都会成为一个节点，其 ID 为使用正斜杠的相对路径。本地导入会转换为从导入方指向依赖项的有向边。JavaScript 和 TypeScript 使用 Babel 解析；对于不支持的语法，则使用正则表达式回退方案。同类型的重复引用会合并，并记录为边权重。外部包会被排除。通过导入的绑定实现的类继承会生成 inheritance 边；import() 会生成 dynamic 边。

RepoGraph 会尝试查找源文件扩展名、目录索引文件、NodeNext .js → .ts 对应文件，以及基于启发式规则将 @/ 映射到 src/ 的别名。它不会执行代码，也不会加载项目专属的编译器插件。计算得出的导入路径和自定义别名可能无法识别。

分层赋予图表含义

层	文件或目录线索	颜色
入口	controller、route、router、handler、api、endpoint、cli、app、server、main；根目录 index	青色
业务	service、usecase、core、domain、logic、manager	洋红色
数据	repo、repository、model、schema、entity、store、db、dao、migration	琥珀色
实用工具	util、utils、helpers、common、shared、lib、constants、types、config；高扇入	石板灰
未知	其他所有内容	靛蓝色

分类时会依次检查入口、业务、数据和实用工具线索。这是一种可解释的文件名启发式规则，并非对设计的语义判断。集群根据前两级目录生成，并保留嵌套的父级目录。

折叠实用工具以减少干扰

传入调用方超过 12 个且传出依赖不超过两个的文件，或名称类似实用工具的文件，都会被视为折叠候选项。CLI/API 的默认阈值为 12；MCP 的默认值为 15。折叠的节点及其边仍保留在图数据和影响分析中，但不会显示在 HTML 初始视图中。选择“显示实用工具”即可查看这些内容。度数按唯一相邻文件计数，而非重复导入次数。

影响范围沿调用者传播

影响分析会沿反向边执行广度优先搜索。它可以处理循环，每个文件只访问一次，并记录最短调用深度。检查器会列出直接调用者和依赖项；高亮会追踪完整的传递链。如果某个循环同时属于两条链，则优先显示依赖项高亮。

死代码警告会统计没有入站本地边、且看起来不像入口点的文件。请将这些警告视为审查提示：框架、反射、外部使用者和动态加载都可能导致某些有效文件没有静态调用者。耦合因子是唯一出度的平均值；密度是边数除以 n * (n - 1)（文件少于两个时为零）。LOC 统计非空源代码行，包括注释。

支持的语言和扫描规则

语言	解析规则
JavaScript / TypeScript	ESM 导入/重新导出、require()、动态导入、导入的超类绑定；JS/JSX/MJS/CJS/TS/TSX/MTS/CTS
Python	import a.b、绝对和相对 from 导入、.py 模块和 __init__.py 包
Go	单条导入和导入块；根目录 go.mod 模块路径会解析到目标目录中扫描到的每个 .go 文件
Rust	mod x; 会解析到 x.rs 或 x/mod.rs；use crate::... 会解析 src/ 下的模块

根目录和嵌套的 .gitignore 规则均会遵循。RepoGraph 会跳过依赖项、构建、缓存和编辑器目录，包括 node_modules、.git、dist、build、out、coverage、__pycache__、.venv、venv、.next、.nuxt、target、vendor、.idea、.vscode 和 .cache。为避免循环，会跳过符号链接。超过 1.5 MB 的文件和 *.min.js 文件不会纳入扫描。测试/规格文件会从主图中排除，但其数量会保留在 metrics.excludedTestFiles 中。

Python、Go 和 Rust 的解析有意采用静态启发式方法：不会评估工作区清单、构建标签、Python 导入钩子、Rust 宏和非根目录 Go 模块。只有纳入扫描的文件才能成为节点或目标。

适用场景

此表描述的是各工具的侧重点，而非功能完整性或性能基准。请查看每个项目的当前文档，了解其完整功能。

	RepoGraph	Madge	CodeSee	Gitingest
主要输出	本地交互式 HTML 架构图	模块依赖图	代码探索与映射平台	仓库文本上下文
工作流	CLI + 三个 MCP 工具	依赖分析 CLI/API	平台工作流	提取代码以提供大模型上下文
主要侧重点	分层、工具模块折叠、调用者影响	模块关系和循环	协作式代码理解	可分享的代码上下文
RepoGraph 的方式	无服务端；嵌入式图快照	互补的依赖分析工具	不同的平台模式	互补的文本优先工具

编程方式使用

import { analyzeRepository } from 'repograph-cli/dist/src/api.js';
import { impactPath } from 'repograph-cli/dist/src/core/graph.js';
import { renderToHtml } from 'repograph-cli/dist/src/renderer/htmlTemplate.js';

const graph = await analyzeRepository('.', {
  maxDepth: 6,
  collapseUtils: true,
  utilThreshold: 12,
});
const impact = impactPath(graph, 'src/api.ts');
const html = renderToHtml(graph, { theme: 'dark' });

createServer() 和 startMcpServer() 从 dist/src/index.js 导出；导入该模块不会启动传输层。图数据模型位于 src/types.ts，并随附生成的 TypeScript 声明。

参与贡献

npm install
npm run build
node dist/bin/cli.js . --output demo/self.html
node dist/bin/cli.js . --format json
node dist/bin/cli.js . --format mermaid

开发期间，请使用 npm run dev -- .。在会阻止运行 npm.ps1 的 Windows PowerShell 环境中，请使用 npm.cmd。确保路径 ID 可移植，避免执行扫描到的代码，并针对包含相关导入的小型仓库测试解析规则变更。提交错误报告或贡献时，请附上复现步骤和预期的边。

许可证

MIT © 2026 Karry。请参阅 LICENSE。

路线图 · 点星投票

• TypeScript/JavaScript
• Python
• Go
• Rust
• Java/Kotlin（达到 200 ⭐ 后解锁）
• C#（300 ⭐）
• PHP/Ruby（500 ⭐）
• Monorepo 工作区 + tsconfig 路径别名解析（200 ⭐）
• VS Code 扩展（1000 ⭐）

点星投票，提交一个语言支持请求议题，并分享你需要支持的导入和项目布局。这些门槛用于指导优先级，并不代表承诺交付日期。