Spine

repomap

为 AI Agent 绘制代码库地图：代码图谱、搜索、调用路径和变更影响分析。无需 API 密钥。

代码图谱 · 混合搜索 · 调用路径 · 变更影响分析 · 交互式图谱界面。
一个 Rust 二进制文件。本地运行。无需 API 密钥。MIT。

npx -y @sylphx/repomap setup

在线演示 · 文档 · 快速入门 · 工具 · 图谱界面 · 基准测试 · 对比

_{在 excalidraw 上运行的真实界面（687 个文件，不到半秒完成索引）：搜索符号、查看其代码和调用方，然后查看变更的影响范围。在浏览器中试用，无需安装。}

查看实际效果

在任意代码库上运行。这是 repomap 自身源码的真实输出（v1.5.0，已精简）：询问更改 pagerank 会导致什么问题。

$ npx -y @sylphx/repomap impact pagerank

# Impact (MEDIUM risk)
Changing: function pagerank (crates/repomap-core/src/graph.rs:639)
2 direct callers, 4 symbols affected in total across 6 files and 3 modules; 5 files importing the changed files; 1 test file to run.

## Direct callers (will break if the contract changes)
- method DbSchema.graph_json — crates/repomap-core/src/db.rs:1981
- function link — crates/repomap-core/src/graph.rs:122

## Indirect (depth 2)
- function assemble — crates/repomap-core/src/index.rs:700

一次本地调用，无需 API 密钥，并能给出可供 Agent 引用的 file:line 答案。

快速入门

npx -y @sylphx/repomap setup     # add repomap to Claude Code, Codex, Cursor, VS Code, Claude Desktop, Windsurf, Gemini CLI
npx -y @sylphx/repomap serve     # open the graph UI for the current repo

想手动配置一个客户端？Claude Code 可运行 claude mcp add repomap -- npx -y @sylphx/repomap mcp；Cursor、VS Code、Codex 和 Docker 的代码片段见下文。

就这么简单。添加 --claude-hooks，还可以增强 Claude Code 的 Grep 和 Glob。setup 会检测你使用的客户端，写入其 MCP 配置，并列出所做的每项更改。再次运行时不会有任何变化。然后询问你的 Agent：“使用 repomap 为这个代码库绘制地图。”

· 在 VS Code 中安装

需要 Node 18+。在编辑器中确认安装，打开项目并启用服务。两个链接都会在本地运行 npx -y @sylphx/repomap mcp；无需 API 密钥。

从终端为 VS Code 安装：

code --add-mcp '{"name":"repomap","command":"npx","args":["-y","@sylphx/repomap","mcp"]}'

或将服务添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "repomap": {
      "command": "npx",
      "args": [
        "-y",
        "@sylphx/repomap",
        "mcp"
      ]
    }
  }
}

对于 .vscode/mcp.json，请使用 VS Code 的 servers 格式：

{
  "servers": {
    "repomap": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@sylphx/repomap",
        "mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "repomap": { "command": "npx", "args": ["-y", "@sylphx/repomap", "mcp"] }
  }
}

[mcp_servers.repomap]
command = "npx"
args = ["-y", "@sylphx/repomap", "mcp"]

{ "mcpServers": { "repomap": { "command": "docker", "args": ["run", "-i", "--rm", "-v", "/path/to/repo:/workspace:ro", "ghcr.io/sylphxai/repomap"] } } }

实测：SWE-bench Verified 上的文件定位

仅通过一次问题文本搜索，即可在 83.0% 的 SWE-bench Verified 问题中将所有修复文件找入前 10 名（semble：71.0%）。这是文件检索，不是问题解决。

权衡：在 semble 公开的代码搜索数据集上，NDCG@10 为 0.845，而 semble 为 0.851；在该数据集上 semble 表现更好。这并不意味着它在所有任务上的搜索都更优。实测搜索质量和局限性。

Agent 会把大部分上下文耗在 grep、ls 和读取整个文件上，只为弄清楚内容在哪里。repomap 会预先提供地图：

• 它在哪里？ 混合搜索可匹配符号名称、函数内的词语以及代码含义，并显示匹配行。可以询问“失败请求在哪里重试”，也可以搜索 parseConfig。
• 这是什么？ 一次调用即可返回符号代码、带调用位置行号的调用方、被调用方、子类型，以及能够到达该符号的测试。
• 如何从 A 到达 B？ 最短调用路径，每一跳都标注 file:line。
• 如果我修改它，会有什么影响？ 直接和间接调用方、导入该文件的文件、受影响的模块、要运行的测试，以及风险等级。提交前，可以将你的 git diff 传给它。
• 这个代码库是什么样的？ 根据实际依赖关系（而非仅根据文件夹）发现的模块、最核心的文件、最常用的符号，以及入口点。

所有信息都来自本地索引：tree-sitter 解析、已解析的导入和调用图、PageRank、Louvain 社区检测、对 AST 代码块的 BM25 搜索，以及一个轻量级静态代码嵌入模型（33 MB，从 Hugging Face 下载一次，之后可离线使用）。所有数据都留在你的计算机上，也不会调用任何 API；唯一的网络请求是下载模型（设置 REPOMAP_EMBED=0 可跳过）。

Agent 能获得什么

六种工具，各有明确用途：

答案是精简文本，并标注 file:line，因此只消耗少量令牌。传入 format: "json" 可获取结构化输出。

> impact target=decode

# Impact (LOW risk)
Changing: function decode (src/auth/token.ts:14)
1 direct caller, 3 symbols affected in total across 3 files and 2 modules; 1 file importing the changed files; no tests reach this.

## Direct callers (will break if the contract changes)
- function verifyToken — src/auth/token.ts:8

## Indirect (depth 2)
- method SessionStore.refresh — src/auth/session.ts:5

## Indirect (depth 3)
- function handleRefresh — src/api/router.ts:6

## Importing files
- src/auth/session.ts

终端中也可以使用相同命令：repomap map、repomap search "…"、repomap context X、repomap trace A B、repomap impact --changed、repomap db。

图形界面

npx -y @sylphx/repomap serve            # live, with code preview
npx -y @sylphx/repomap export           # repomap.html: one self-contained file you can publish

影响。 选择一个文件并按 i：所有依赖它的项目都会按深度高亮显示，并提供可点击浏览的列表。	代码。 点击一个符号即可查看其源码、调用方和被调用方。打开 ↗ 会跳转到你的编辑器或 GitHub。

• 使用 WebGL 渲染（Sigma.js），即使有数万个文件和边，也能保持流畅
• 模块按实际依赖关系着色和聚类，文件大小按 PageRank 显示；测试、示例和文档以弱化样式显示，且可一键查看
• / 搜索文件、符号和代码；d 显示依赖关系；f 调整视图以适应屏幕
• 点击模块将其设为焦点，按住 Shift 并点击可将其隐藏；可切换测试、边和标签
• export 会生成一个带深层链接（#path/to/file）的 HTML 文件，并固定指向你提交版本的 GitHub 链接。很适合用于 README、Wiki 或设计评审。

数据库映射

npx -y @sylphx/repomap db                              # from migrations / Prisma / Drizzle / SQLAlchemy / Diesel / Django
npx -y @sylphx/repomap db --url-env DATABASE_URL       # live Postgres, MySQL or SQLite, read-only
npx -y @sylphx/repomap db users                        # one table: columns, indexes, who references it, where it is queried
npx -y @sylphx/repomap db --serve                      # the same graph UI, for tables and foreign keys

repomap 从代码仓库读取架构：SQL 迁移（按顺序应用，跳过 down 迁移）、schema.prisma、Drizzle pgTable/mysqlTable/sqliteTable、SQLAlchemy 和 Flask-SQLAlchemy 模型、Diesel table!，以及 Django models.py（字段、ForeignKey/ManyToManyField、Meta、隐式联结表）。它也可以检查实时数据库。每张表都会关联到查询它的代码：原始 SQL（FROM users）、Prisma（prisma.user.findMany）、Diesel（users::table）、Django（Post.objects…），以及导入这些模型的文件所使用的 ORM 模型或表。

实时连接严格为只读：

• Postgres 在 READ ONLY 事务中运行，且必须由服务端确认。
• MySQL 在 START TRANSACTION READ ONLY 事务中运行。
• SQLite 以只读方式打开，并启用 query_only。

只读取目录元数据，绝不读取表中的行。连接字符串来自参数或环境变量，绝不会被存储或打印。Agent 通过 db MCP 工具获取相同数据；请传入 url_env，而不是 URL 本身。

Agent 就绪度评分

npx -y @sylphx/repomap score

该评分从 0 到 100，评估 AI Agent 在代码仓库中工作的难易程度。它涵盖八项检查：

• Agent 指令（AGENTS.md / CLAUDE.md 及其有效性）
• 易于发现的构建和测试命令
• 测试覆盖率
• CI
• 模块边界
• 文件大小
• 文档
• 类型

每项未达标的检查都会附带具体的修复方法，评分最后还会生成一行徽章，供你添加到 README 中。对于 CI，请使用 --min 70；--update-readme README.md 会刷新徽章。

使用 GitHub Action 保持徽章为最新：

# .github/workflows/agent-ready.yml
on: { push: { branches: [main] } }
permissions: { contents: write, pull-requests: write }
jobs:
  score:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: SylphxAI/repomap@v1
        with:
          update-readme: true   # opens or updates one PR with the fresh badge
          min-score: 0          # set e.g. 70 to fail below a bar

Claude Code 钩子

npx -y @sylphx/repomap setup --claude-hooks

此功能需选择启用，且可以安全地重复运行；setup --remove 可将其移除。它会安装一个 PreToolUse 钩子：每当 Claude Code 运行 Grep 或 Glob 时，repomap 就会补充符号的定义位置、调用者以及所属模块。它能在几十毫秒内作出响应，且绝不会阻止搜索。

repomap (code map) for this search:
- function `compose` defined at src/compose.ts:15 (module router); 3 callers: Hono.route (src/hono-base.ts:228), Hono.#dispatch (src/hono-base.ts:452), every (src/middleware/combine/index.ts:102)

语言

使用 tree-sitter 解析符号、调用、导入和继承：TypeScript、TSX、JavaScript、Python、Go、Rust、Java、Kotlin、Swift、C、C++、C#、Ruby、PHP。 搜索也涵盖 Markdown、YAML、TOML、JSON、SQL、shell、Protobuf、GraphQL、HTML/CSS、Vue、Svelte、Scala 等。

模块只从核心代码中识别。测试、示例、文档和基准测试会单独归类，因此绝不会被识别为模块或与模块混淆。

导入解析支持相对路径、@/ 别名、npm 工作区包、Python 包和相对导入、Go 模块、Rust mod/use/工作区 crate、Java/PHP 命名空间、C/C++ include 和 Ruby require。会遵循 .gitignore 和 .repomapignore。

理解问题的搜索

在 semble 的公开代码搜索基准上（63 个代码仓库、19 种语言、1,251 个问题），repomap 的 search 得分为 NDCG@10 0.845，semble 在相同运行环境下为 0.851。此前 repomap 的得分为 0.851：更强的问题定位能力在这里约牺牲了 0.006 分。在我们针对 60 个大型代码仓库问题的测试中，repomap 得分为 0.846，semble 为 0.799，但在 VS Code 上仍是 semble 更胜一筹。参数量为 137M 的 CodeRankEmbed 模型公布的得分为 0.839，纯 BM25 得分为 0.673（此处引用数据，未重新运行测试）。

在文件定位测试中（500 个 SWE-bench Verified 问题，每个问题只调用一次 search 并传入问题文本），repomap 在 83.0% 的问题中能在前 10 个结果里找到所有修复文件（Acc@10；前 5 个结果为 74.8%，前 1 个为 48.8%），semble 则分别为 71.0% / 61.6% / 34.0%。此次改动前，repomap 的得分为 62.2% / 51.8% / 23.6%。纯 BM25 的前 10 个结果得分为 55.8%，关闭嵌入功能的 repomap 得分为 77.6%。在同一运行环境下，索引/查询中位耗时为 1.682 s / 54.4 ms，旧版二进制为 1.686 s / 59.8 ms，semble 为 12.813 s / 354.4 ms。默认参数仅在一个不重叠的 300 个实例调优数据集上选定，随后冻结，再进行一次 Verified 测试。LocAgent 等 Agent 系统在不同子集上报告了更高的数字，并在流程中使用了语言模型；这些数据仅供引用，未重新运行测试。

无需 GPU、向量数据库或 API 密钥。一个 33 MB 的静态代码模型在 CPU 上运行，与 BM25 和符号名称配合使用。

快

索引会并行构建，并按文件缓存，因此首次运行后只需重新解析有变更的文件。MCP 服务会将图保存在内存中，并在文件变更时刷新。

在 4 vCPU 的 GitHub 托管运行器上测得（方法和完整表格）：

对比

如果你需要精确到 LSP 级别的重构编辑，请选择 Serena。repomap 旨在帮助你轻松理解和浏览代码库，无需设置；它还支持语义搜索，无需向量数据库或 API 密钥，并采用可在工作中使用的许可证。搜索质量通过 基准测试中的公开基准衡量。

免费

repomap 的所有功能均以 MIT 许可证免费提供，包括多代码仓库工作区（--workspace）以及在你自己的 CI 中使用 impact。无需许可证密钥，也没有付费层级。

CLI

repomap setup [--client cursor,codex] [--claude-hooks] [--dry-run] [--remove]
repomap serve [dir] [--port 7878] [--no-open]
repomap export [dir] [--out repomap.html] [--json]
repomap map [dir-to-focus] [-C root] [--tokens 1000] [--json]
repomap search <query> [--path src/] [--kind function] [--limit 10]
repomap context <target> [--code-lines 60]
repomap trace <from> [to] [--callers] [--depth 3]
repomap impact [targets…] [--changed] [--base main]
repomap db [table] [--url-env VAR | --url URL] [--serve | --out db.html] [--json]
repomap score [dir] [--json] [--min N] [--update-readme README.md [--insert]]
repomap index [dir] [--no-cache] [--json]
repomap mcp [--root dir]

macOS（arm64、x64）、Linux glibc（x64、arm64）和 Windows x64 的二进制文件以 npm 可选依赖的形式发布。它们也附在每个 GitHub release 中。从源代码安装：cargo install --git https://github.com/SylphxAI/repomap sylphx-repomap。

从 Spine、Locus 或 CodeRAG 迁移

@sylphx/spine、@sylphx/locus 和 @sylphx/coderag 是 @sylphx/repomap 的轻量别名，旧工具名称仍可使用。请参阅迁移指南，了解名称映射以及如何切换。

贡献

cargo test --workspace          # engine + CLI tests
bun install && bun run build:ui # rebuild the UI bundle (ui/ -> crates/repomap/assets/)
cargo run -p sylphx-repomap -- serve .

欢迎提交问题和 PR，尤其欢迎添加对新语言的支持：在 crates/repomap-core/src/lang.rs 中添加语法和查询。

Sylphx 的其他项目

• anymd：将任意文件（PDF、Word、PowerPoint、Excel、EPUB、HTML、图像）转换为适用于 AI Agent 的简洁 Markdown。
• lockdocs：根据 lockfile 提供精确版本的库文档。本地运行、离线可用、没有速率限制。
• skills：经过实战检验的 Claude Code 和 Codex Agent 技能，一条命令即可安装。
• readme-mark：通过一个 URL 生成精美的 README 图像：横幅、徽章、图标和统计卡片。

了解更多 Sylphx 项目：https://sylphx.com/open-source

Star 历史

隐私

repomap 在你的计算机上运行。索引、搜索和每次查询都会在本地读取你的代码，不会将任何内容发送到其他地方。repomap 唯一会发起的网络请求，是你首次搜索时从 Hugging Face 下载嵌入模型；不会发送任何代码。设置 REPOMAP_EMBED=0 可跳过此步骤，仅使用关键词搜索。repomap export 文件包含路径、符号名称和行号，不包含源代码。有关完整边界，请参阅 SECURITY.md。

支持

有疑问、发现错误，或计划在团队中部署？请发送邮件至 [email protected]，或提交问题。

MIT 许可证。© Sylphx Limited，注册于英格兰和威尔士，公司编号 16438428。注册办公地址：128 City Road, London EC1V 2NX, United Kingdom。邮箱：[email protected]。隐私 · 条款 · sylphx.com