仓库映射器

Name: 仓库映射器
Author: pdavis68

作者：pdavis6863 星标更新：2025-09-19

安装使用来源：spider==github.com

项目介绍

RepoMap - 命令行工具和MCP服务器

RepoMap 是一个强大的工具，旨在帮助主要的大型语言模型理解并导航复杂的代码库。它既可以用作按需分析的命令行应用程序，也可以作为MCP（模型上下文协议）服务器，为其他应用程序提供持续的仓库映射能力。通过生成软件仓库的“地图”，RepoMap 高亮显示重要的文件、代码定义及其关系。它利用Tree-sitter进行准确的代码解析，并使用PageRank算法对代码元素的重要性进行排序，确保始终优先考虑最相关的信息。

辅助程序

RepoMap 完全基于Aider的仓库映射功能，但我认为它并没有与之共享任何代码。让我解释一下。

我最初的尝试是从Aider中提取RepoMap类，移除所有特定于Aider的依赖项，然后将其变成一个命令行工具。Python并不是我的母语，我确实很难让它正常工作。

所以几个小时前，我有了一个不同的想法。我从Aider中提取了RepoMap及其相关的部分代码，并将其输入到一个LLM（可能是Claude或Gemini 2.5 Pro，记不清了），让它根据Aider的实现创建规范。因此，它生成了一个非常详细的此应用程序的规范（不包括MCP的部分），然后我将其输入到Aider中，使用Claude 3.7构建了命令行版本。

然后，我结合使用了Aider与Claude 3.7、Cline与Gemini 2.5 Pro预览版及Gemini 2.5 Flash预览版，以及Phind.com、Gemini.com、Claude.com和ChatGPT.com，在几个小时后，终于解决了MCP服务器的问题。再次提醒，Python并不是我的母语。

示例输出

> python repomap.py . --chat-files repomap_class.py
聊天文件：['/mnt/programming/RepoMapper/repomap_class.py']
repomap_class.py:
(排名值：10.8111)

  36: CACHE_VERSION = 1
  39: TAGS_CACHE_DIR = os.path.join(os.getcwd(), f".repomap.tags.cache.v{CACHE_VERSION}")
  40: SQLITE_ERRORS = (sqlite3.OperationalError, sqlite3.DatabaseError)
  43: Tag = namedtuple("Tag", "rel_fname fname line name kind".split())
  46: class RepoMap:
  49:     def __init__(
  93:     def load_tags_cache(self):
 102:     def save_tags_cache(self):
 459:     def get_ranked_tags_map_uncached(
 483:         def try_tags(num_tags: int) -> Tuple[Optional[str], int]:
 512:     def get_repo_map(

utils.py:
(排名值：0.2297)

  18: Tag = namedtuple("Tag", "rel_fname fname line name kind".split())
  21: def count_tokens(text: str, model_name: str = "gpt-4") -> int:
  35: def read_text(filename: str, encoding: str = "utf-8", silent: bool = False) -> Optional[str]:

importance.py:
(排名值：0.1149)

   8: IMPORTANT_FILENAMES = {
  27: IMPORTANT_DIR_PATTERNS = {
  34: def is_important(rel_file_path: str) -> bool:
  56: def filter_important_files(file_paths: List[str]) -> List[str]:

    ...
    ...
    ...

特性

智能代码分析：使用Tree-sitter解析源代码并提取函数/类定义
相关性排名：采用PageRank算法对代码元素的重要性进行排名
令牌感知：尊重令牌限制以适应LLM上下文窗口
缓存：持久缓存以加快后续运行速度
多语言支持：支持Python、JavaScript、TypeScript、Java、C/C++、Go、Rust等多种语言
重要文件检测：自动识别并优先处理重要文件（如README、requirements.txt等）

安装

pip install -r requirements.txt

使用方法

基本用法

# 映射当前目录
python repomap.py .

# 映射特定目录并自定义令牌限制
python repomap.py src/ --map-tokens 2048

# 映射特定文件
python repomap.py file1.py file2.py

# 指定聊天文件（更高优先级）与其他文件
python repomap.py --chat-files main.py --other-files src/

# 指定提及的文件和标识符
python repomap.py --mentioned-files config.py --mentioned-idents "main_function"

# 启用详细输出
python repomap.py . --verbose

# 强制刷新缓存
python repomap.py . --force-refresh

# 指定用于令牌计数的模型
python repomap.py . --model gpt-3.5-turbo

# 设置最大上下文窗口
python repomap.py . --max-context-window 8192

# 排除PageRank为0的文件
python repomap.py . --exclude-unranked

该工具按照以下顺序优先处理文件：

--chat-files：这些文件具有最高优先级，因为它们被认为是您当前正在工作的文件。
--mentioned-files：这些文件具有较高优先级，因为它们在当前上下文中被明确提及。
--other-files：这些文件具有最低优先级，用于提供额外的上下文。

高级选项

# 启用详细输出
python repomap.py . --verbose

# 强制刷新缓存
python repomap.py . --force-refresh

# 指定用于令牌计数的模型
python repomap.py . --model gpt-3.5-turbo

# 设置最大上下文窗口
python repomap.py . --max-context-window 8192

# 排除PageRank为0的文件
python repomap.py . --exclude-unranked

# 提及特定文件或标识符以提高优先级
python repomap.py . --mentioned-files config.py --mentioned-idents "main_function"

工作原理

文件发现：扫描仓库中的源文件
代码解析：使用Tree-sitter解析代码并提取定义/引用
图构建：创建一个图，其中文件是节点，符号引用是边
排名：应用PageRank算法对文件和符号的重要性进行排名
令牌优化：使用二分查找将最重要的内容适配到令牌限制内
输出生成：格式化结果为可读的代码地图

输出格式

该工具生成一个结构化的视图，展示您的代码库：

文件路径和重要代码段
函数和类定义
代码元素之间的关键关系
根据实际使用和引用进行优先排序

依赖项

tiktoken：各种LLM模型的令牌计数
networkx：图算法（PageRank）
diskcache：持久缓存
grep-ast：Tree-sitter集成用于代码解析
tree-sitter：代码解析框架
pygments：语法高亮和词法分析

缓存

该工具使用持久缓存来加速后续运行：

缓存目录：.repomap.tags.cache.v1/
当文件更改时自动失效
可以通过--force-refresh清除

支持的语言

目前支持具有Tree-sitter语法的语言：

arduino
chatito
commonlisp
cpp
csharp
c
dart
d
elisp
elixir
elm
gleam
go
javascript
java
lua
ocaml_interface
ocaml
pony
properties
python
racket
r
ruby
rust
solidity
swift
udev
c_sharp
hcl
kotlin
php
ql
scala

许可证

此实现基于Aider项目中的RepoMap设计。

作为MCP服务器运行

RepoMap 还可以作为MCP（模型上下文协议）服务器运行，允许其他应用程序访问其仓库映射能力。

设置

RepoMap MCP服务器使用STDIO（标准输入/输出）进行通信。传输层不需要额外配置。
要将RepoMap设置为MCP服务器并与Cline（或其他类似工具如Roo）一起使用，请在您的Cline设置文件（例如cline_mcp_settings.json）中添加以下配置：

{
  "mcpServers": {
    "RepoMapper": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "/usr/bin/python3",
      "args": [
        "/absolute/path/to/repomap_server.py"
      ]
    }
  }
}

将"/absolute/path/to/repomap_server.py"替换为您实际的repomap_server.py文件路径。

使用方法

运行repomap_server.py脚本：

python repomap_server.py

服务器启动并通过STDIO监听请求。
其他应用程序可以使用服务器提供的repo_map工具生成仓库地图。它们必须指定project_root参数为要映射项目的绝对路径。

变更日志

2025年7月13日 - 移除了project.json依赖项。修复了MCP服务器，使其更容易让LLM处理文件名。