RepoLens

# RepoLens AI 智能体本地代码库索引工具。 RepoLens 扫描代码库，建立紧凑的本地索引，并通过 CLI、MCP stdio 服务器和 localhost HTTP API/UI 提供代码导航工具。从一开始，它就被设计为跨平台的：Windows、Linux、macOS 和类 Unix 环境。 ## 链接 - 🚀 [最新版本](https://github.com/dandyArise/RepoLens/releases/latest) - 📦 [v0.1.11 版本二进制文件](https://github.com/dandyArise/RepoLens/releases/tag/v0.1.11) - ⚙️ [GitHub Actions 构建](https://github.com/dandyArise/RepoLens/actions) - 🧩 [Windows 安装程序](https://github.com/dandyArise/RepoLens/blob/main/install/install.ps1) - 🧩 [Linux/macOS 安装程序](https://github.com/dandyArise/RepoLens/blob/main/install/install.sh) - 🗺️ [路线图](ROADMAP.md) ## 亮点 - ⚡ 快速的 Rust CLI，支持并行索引。 - 🧠 为 AI 智能体提供的 MCP stdio 服务器。 - 🖥️ 本地 HTTP API 和可选 UI。 - 🧭 符号、搜索、大纲、依赖、反向依赖和受保护的读取。 - ✍️ 具有哈希保护、原子写入和立即重新索引的安全编辑工具。 - 👀 监视模式，支持增量更新和变更跟踪。 - 🧰 Codex、Claude Desktop 和 Cursor 的自动配置。 - 🔐 默认阻止敏感文件。 - 🌍 支持 Windows、Linux 和 macOS 的发布二进制文件。 ## AI 智能体可以与 RepoLens 合作 🤖 RepoLens 为 AI 智能体提供项目快速地图，以便在开始编辑前。 没有 RepoLens，智能体通常需要打开许多文件，运行广泛的搜索，并花费上下文在可能不相关的代码上。有了 RepoLens，智能体可以首先提出有针对性的问题： - 在哪里定义了此函数、类、路由或配置键？ - 哪些文件提到了这个词或标识符？ - 这个文件中的重要符号是什么？ - 这个文件导入了什么？ - 哪些文件依赖于此文件？ - 自从索引建立以来发生了什么变化？ - 我可以只读取我需要的确切行吗？ 这有助于智能体使用更少的令牌，避免嘈杂的文件读取，并进行更安全的编辑。RepoLens 不会取代智能体。它为智能体提供更好的本地导航工具，以便更快地理解代码库。 典型的智能体工作流程： ```text search -> inspect symbols -> read focused lines -> check dependencies -> edit with hash guard ``` ## 状态 已实现： - 跨平台 Rust CLI。 - `rg` 类似扫描器默认值：git 忽略、隐藏文件、常见构建文件夹、大小上限和敏感路径。 - 敏感文件的默认安全设置。 - `.repolens/index.json` 处的 JSON 快照。 - `.repolens/index.bin` 处的二进制快照，支持 mmap 加载以实现更快的重新加载。 - 快照元数据命令/工具。 - 用于搜索的单词和三元组索引。 - 并行文件索引。 - Rust、TypeScript、JavaScript、TSX/JSX、Python、Go、PHP、Java、C#、C/C++、Ruby、JSON、YAML 和 TOML 的符号提取。 - Rust、TS/JS、Python、Go、PHP、Java、C#、C/C++ 和 Ruby 的导入/依赖提取。 - 相对 TS/JS 依赖解析。 - 已解析导入的前向和反向依赖图。 - 带有紧凑工具的 MCP stdio 服务器。 - 本地 HTTP API。 - localhost UI（可选）。 - 监视模式，支持变更序列跟踪和增量文件更新。 - 基本基准命令，可选 `rg` 比较。 - 框架、夹具、模拟和断言的通用测试感知报告。 - Windows、Linux 和 macOS 的发布构建。 - 支持 Rust 缓存的 CI。 尚未实现： - 大型代码库的性能报告。 ## 全局安装 📦 安装 RepoLens 一次，然后仅在您要使用的项目中启用它。 Windows PowerShell： ```powershell iwr https://raw.githubusercontent.com/dandyArise/RepoLens/main/install/install.ps1 -UseBasicParsing | iex ``` 更新后： ```powershell iwr https://raw.githubusercontent.com/dandyArise/RepoLens/main/install/install.ps1 -UseBasicParsing | iex ``` Linux/macOS： ```sh curl -fsSL https://raw.githubusercontent.com/dandyArise/RepoLens/main/install/install.sh | sh ``` 更新后： ```sh curl -fsSL https://raw.githubusercontent.com/dandyArise/RepoLens/main/install/install.sh | env REPOLENS_ACTION=update sh ``` 默认值： - Windows 安装到 `%USERPROFILE%\bin` - Windows 将 `%USERPROFILE%\bin` 添加到用户 `PATH` - Linux/macOS 安装到 `$HOME/.local/bin` - 在复制二进制文件之前验证校验和 - 支持的资产：Windows x86_64、Linux x86_64/arm64、macOS x86_64/arm64 然后打开一个项目文件夹，并为您的 AI 客户端激活 RepoLens： ```powershell repolens init . --target codex ``` 这里的 `.` 表示当前项目文件夹。您可以在任何其他代码库中运行相同的命令，以便在那里使用 RepoLens。Codex 注册是特定于项目的：每个代码库都获得一个稳定的 `repolens_<project>_<hash>` MCP 服务器条目，注册另一个代码库不会替换前一个条目。 使用所有支持的客户端： ```powershell repolens init . --target all ``` 检查或禁用稍后： ```powershell repolens mcp-status --target all repolens disable --target codex ``` 对于 Codex，`mcp-status` 报告已注册的 RepoLens 项目数量。`disable --target codex` 删除所有 RepoLens 项目条目，同时保留无关的 MCP 服务器。 ## 故障排除 🧯 ### Windows 上无法识别 `repolens` 关闭并重新打开 PowerShell，然后运行： ```powershell repolens --help ``` 如果仍然失败，请使用完整路径运行： ```powershell & "$env:USERPROFILE\bin\repolens.exe" --help ``` ### 我已安装，但 AI 客户端无法看到 RepoLens 从项目文件夹运行 `init`，然后重启 AI 客户端： ```powershell cd <your-project-folder> repolens init . --target codex repolens mcp-status --target codex ``` 对于所有支持的客户端： ```powershell repolens init . --target all repolens mcp-status --target all ``` ### 我在错误的文件夹中运行了 `init` 每个 Codex 项目都独立注册。禁用所有 RepoLens Codex 条目，然后仅初始化您要保留的项目： ```powershell repolens disable --target codex cd <correct-project-folder> repolens init . --target codex ``` ### 在不卸载的情况下禁用 RepoLens ```powershell repolens disable --target codex ``` ### 卸载 RepoLens ```powershell iwr https://raw.githubusercontent.com/dandyArise/RepoLens/main/install/install.ps1 -OutFile "$env:TEMP\install-repolens.ps1" & "$env:TEMP\install-repolens.ps1" -Action uninstall ``` ## 安装程序选项 ```powershell .\install\install.ps1 -Version v0.1.11 .\install\install.ps1 -Action update .\install\install.ps1 -Action status -InitTarget all .\install\install.ps1 -Action disable -InitTarget codex .\install\install.ps1 -Action uninstall ``` ```sh REPOLENS_VERSION=v0.1.11 sh install/install.sh REPOLENS_ACTION=update sh install/install.sh REPOLENS_ACTION=status REPOLENS_INIT_TARGET=all sh install/install.sh REPOLENS_ACTION=disable REPOLENS_INIT_TARGET=codex sh install/install.sh REPOLENS_ACTION=uninstall sh install/install.sh ``` ## 与 AI 智能体一起使用 🤖 RepoLens 可以为 Codex、Claude Desktop 和 Cursor 注册自己作为 MCP 服务器。 从您要索引的代码库： ```powershell repolens init . --target all ``` 配置一个客户端： ```powershell repolens init . --target codex repolens init . --target claude repolens init . --target cursor ``` 检查或删除 MCP 注册而不卸载二进制文件： ```powershell repolens mcp-status --target all repolens disable --target codex repolens disable --target all ``` `disable` 仅从客户端 MCP 配置中删除 RepoLens。它保留配置文件中的其他部分，并在写入 `.bak` 备份之前。 然后重启您的 AI 客户端。客户端将接收一个运行 `repolens mcp <repo-root>` 的 `repolens` MCP 服务器。 为了在智能体工作流中获得最佳结果，请在项目指令中添加 RepoLens优先的指令： ```md # RepoLens 在 `repolens_*` 工具可用时，在基于 shell 的代码库探索之前使用 RepoLens 工具。 首先调用 `repolens_status` 并确认 `root` 是当前代码库。 如果根目录错误或过时，请不要依赖 RepoLens 结果来完成任务。 从正确的项目根目录运行 `repolens init . --target codex` 并重启 Codex 以使 MCP 服务器重新加载。 优先： - `repolens_status` 验证附加的代码库根目录。 - `repolens_search` 用于文本/代码搜索。 - `repolens_word` 用于标识符查找。 - `repolens_symbol` 用于符号查找。 - `repolens_outline` 用于文件/模块结构。 - `repolens_deps` 用于文件依赖项。 - `repolens_rdeps` 用于更改共享代码前的反向依赖项。 - `repolens_read` 用于聚焦的文件读取和行范围。 - `repolens_bundle` 当多个小型 RepoLens 调用提供更好的上下文时。 - `repolens_changes` 检查观察者跟踪的更改。 - `repolens_snapshot` 当索引元数据有用时。 使用正常的 shell/项目命令进行构建、 lint、测试、git、运行时日志、 生成输出和最近编辑后的确切实时文件系统状态。 对于新项目： 1. 运行 `repolens index .` 以建立本地索引。 2. 运行 `repolens init . --target codex` 以将项目注册到 Codex。 3. 在期望出现 `repolens_*` MCP 工具之前重启 Codex。 ``` `index` 和 `init` 执行不同的作业：`repolens index .` 构建或刷新 本地 `.repolens` 索引，而 `repolens init . --target codex` 编写 当前项目根目录的 MCP 注册。 ## 从源代码安装 🛠️ 要求： - Rust 稳定版。 - `rg` 可选，仅用于比较的基准测试。 ```powershell git clone https://github.com/dandyArise/RepoLens.git cd RepoLens cargo build --release ``` 二进制文件： ```powershell .\target\release\repolens.exe --help ``` ## 发布构建 🚀 发布工作流目标： - `repolens-windows-x86_64.zip` - `repolens-linux-x86_64.tar.gz` - `repolens-linux-arm64.tar.gz` - `repolens-darwin-x86_64.tar.gz` - `repolens-darwin-arm64.tar.gz` 每个存档都附带一个 `.sha256` 文件。标记的发布版本会发布一个组合的 `checksums.sha256`。 已发布的资产可在 [最新发布页面](https://github.com/dandyArise/RepoLens/releases/latest) 上找到。 要创建发布版本： ```powershell git tag v0.1.11 git push origin v0.1.11 ``` 在开发过程中： ```powershell cargo run -- --help ``` ## 快速入门 ⚡ ```powershell cargo run -- index . cargo run -- status . cargo run -- search "ProjectIndex" . cargo run -- read src/main.rs . --lines 1-40 cargo run -- read src/main.rs . --level aggressive cargo run -- smart src/main.rs . cargo run -- tests-aware . cargo run -- gain . --format json cargo run -- self-update --version latest cargo run -- outline src/main.rs . cargo run -- symbol ProjectIndex . cargo run -- deps src/main.rs . cargo run -- bench . --query ProjectIndex --symbol ProjectIndex ``` ## CLI 命令 🧰 ### `index` 构建 `.repolens/index.json`。 ```powershell repolens index . ``` ### `status` 打印索引计数。 ```powershell repolens status . ``` 示例： ```text root: C:\path\to\project files: 20 words: 1153 trigrams: 8889 symbols: 136 symbol names: 120 deps files: 14 ``` ### `tree` 列出索引文件，包含行数和字节数。 ```powershell repolens tree . ``` ### `search` 搜索索引内容。 ```powershell repolens search "handleAuth" . repolens search "ProjectIndex" . --limit 10 ``` ### `word` 查找包含标识符的文件。 ```powershell repolens word UserService . ``` ### `read` 读取文件，支持行范围、字节上限和哈希保护。 ```powershell repolens read src/main.rs . --lines 1-80 repolens read src/main.rs . --max-bytes 4000 repolens read src/main.rs . --hash <blake3_hash> repolens read src/main.rs . --level compact repolens read src/main.rs . --level aggressive ``` 读取级别： - `normal`：当前行为，支持行范围的完整文本。 - `compact`：保留结构和短主体，省略长函数主体。 - `aggressive`：保留导入和可能的签名，以便快速代码定位。 `read` 在可以写入时记录 `.repolens/usage.jsonl` 中的本地使用估计值。日志记录不会阻塞 `read` 命令。 ### `smart` 为一个文件打印紧凑的 JSON 摘要，使用索引符号和导入。 ```powershell repolens smart src/main.rs . ``` v1 摘要是机械的，不是 AI 生成的。它基于符号名称、导入、语言和文件大小。 ### `tests-aware` 打印关于测试文件、框架、夹具、模拟、断言和重要行的通用 JSON 报告。 ```powershell repolens tests-aware . ``` 报告是代码库通用的。它使用路径和内容启发式方法，适用于常见的生态系统，而不是假设一个堆栈。 ### `outline` 列出一个文件中的符号。 ```powershell repolens outline src/main.rs . repolens outline src/lib.ts . repolens outline app.py . ``` 支持的符号语言： - Rust - TypeScript - JavaScript - TSX/JSX - Python - Go - PHP - Java - C# - C/C++ - Ruby - JSON/TOML/YAML 键 ### `symbol` 按名称查找符号。支持精确归一化查找；保留子字符串回退。 ```powershell repolens symbol ProjectIndex . repolens symbol make_user . --limit 5 ``` ### `deps` 列出一个文件中找到的导入/依赖项。 ```powershell repolens deps src/main.rs . repolens deps src/app.ts . repolens deps main.py . repolens rdeps src/utils.ts . ``` 当前提取： - Rust：`use`、`mod` - TS/JS：`import`、`require`，支持 `./` 和 `../` 的相对路径解析 - Python：`import`、`from ... import` - Go：`import` - PHP：`use`、`require`、`include` - Java：`import` - C#：`using` - C/C++：`#include` - Ruby：`require`、`require_relative` ### `bench` 测量索引/搜索/符号的计时，并可选地将搜索与 `rg` 进行比较。 ```powershell repolens bench . --query ProjectIndex --symbol ProjectIndex --limit 20 repolens bench . --query ProjectIndex --symbol ProjectIndex --json ``` 报告包括构建/保存/加载计时和 JSON/二进制快照大小。 ### `gain` 总结本地 `read` 和 `smart` 使用日志的估计上下文节省。 ```powershell repolens gain . repolens gain . --format json ``` 令牌计数基于本地字节数。`gain` 将节省来源分开，例如行范围、字节上限、紧凑读取、激进读取和智能摘要。如果不存在使用日志，RepoLens 会打印一条简短消息并成功退出。 ### `self-update` 通过官方安装程序更新已安装的 `repolens` 二进制文件。 ```powershell repolens self-update repolens self-update --version latest ``` 当前进程退出后，替换程序在后台启动，因此运行的二进制文件不会就地覆盖。 ### `edit` 应用受保护的行编辑并立即重建 `.repolens/index.json`。 需要当前文件哈希。 从 `tree`、`.repolens/index.json` 或 MCP `repolens_tree` 获取。 ```powershell repolens edit src/main.rs . --op replace --start 10 --end 12 --content "new text`n" --hash <current_hash> repolens edit src/main.rs . --op insert --start 20 --content "inserted line`n" --hash <current_hash> repolens edit src/main.rs . --op delete --start 30 --end 35 --hash <current_hash> ``` 安全规则： - 拒绝丢失或过时的哈希； - 拒绝路径遍历； - 拒绝敏感路径，除非 `allow_sensitive = true`； - 拒绝非 UTF-8 文件； - 通过临时文件和原子重命名写入； - 写入后立即重新索引。 ### `mcp` 启动 MCP stdio 服务器。 ```powershell repolens mcp . ``` ### `serve` 启动本地 HTTP API。拒绝非回环主机。 ```powershell repolens serve . repolens serve . --host 127.0.0.1 --port 4177 ``` 路由： - `GET /` - `GET /status` - `GET /snapshot` - `GET /tree?limit=200` - `GET /search?q=ProjectIndex&limit=20` - `GET /word?q=ProjectIndex&limit=20` - `GET /read?path=src/main.rs&lines=1-40` - `GET /outline?path=src/main.rs` - `GET /symbol?q=ProjectIndex&limit=20` - `GET /deps?path=src/main.rs` - `GET /rdeps?path=src/main.rs` - `GET /changes` - `POST /edit` ### `snapshot` 打印 `.repolens/index.json` 元数据。 ```powershell repolens snapshot . ``` ### `watch`、`changes`、`hot` `watch` 保持 `.repolens/index.json` 更新并写入 `.repolens/changes.json`。修改、创建和删除的文件在可能的情况下进行增量应用。 ```powershell repolens watch . repolens watch . --poll --interval-ms 1000 repolens changes . repolens hot . --limit 10 ``` `changes` 返回最新的观察者序列和更改路径。`hot` 仅打印最近更改的路径。 ### `init` 为支持的客户端写入 MCP 配置。`enable` 是相同操作的显式别名。 ```powershell repolens init . --target all repolens init . --target codex repolens init . --target claude repolens init . --target cursor repolens enable . --target codex ``` 当前目标： - Codex：`~/.codex/config.toml` - Claude Desktop： - Windows： `%APPDATA%\Claude\claude_desktop_config.json` - macOS/Linux 默认：`~/Library/Application Support/Claude/claude_desktop_config.json` - Cursor：`~/.cursor/mcp.json` `init` 将当前 `repolens` 可执行文件注册为： ```text repolens mcp <repo-root> ``` Codex 为每个代码库使用一个稳定的 MCP 条目。遗留 `[mcp_servers.repolens]` 条目在下一次运行 `init --target codex` 时自动迁移到特定于项目的命名方案。现有的项目注册、非相关的 MCP 服务器、注释和 `config.toml` 中的格式都会被保留。 示例，包含两个代码库： ```toml [mcp_servers.repolens_github_project_a_718d9cf2] command = "C:\\Users\\me\\bin\\repolens.exe" args = ["mcp", "D:\\Github\\project-a"] [mcp_servers.repolens_github_project_b_f4a29a11] command = "C:\\Users\\me\\bin\\repolens.exe" args = ["mcp", "D:\\Github\\project-b"] ``` ### `enable`, `disable`, `mcp-status` 在不安装或卸载二进制文件的情况下，管理 RepoLens MCP 注册。 ```powershell repolens enable . --target all repolens mcp-status --target all repolens disable --target all ``` `disable` 仅删除 RepoLens： - Codex：删除 RepoLens MCP 项目条目，包括遗留的 `[mcp_servers.repolens]` - Claude Desktop/Cursor：删除 `mcpServers.repolens` 现有的无关 MCP 服务器将被保留。 ## MCP 工具 已实现的工具： - `repolens_status` - `repolens_switch_workspace` - `repolens_snapshot` - `repolens_tree` - `repolens_search` - `repolens_word` - `repolens_read` - `repolens_outline` - `repolens_symbol` - `repolens_deps` - `repolens_rdeps` - `repolens_edit` - `repolens_changes` - `repolens_bundle` 所有 MCP 工具都接受一个可选的 `workspaceRoot` 参数（或 `root` 别名）。当提供时，RepoLens 按需加载该存储库索引，在运行的 MCP 进程中缓存它，并使其成为后续调用的活动根。这允许长期运行的代理会话在不重启 AI 客户端的情况下在存储库之间热切换。 为了安全，热切换根目录必须显式允许。RepoLens 允许初始 MCP 根目录，通过 `repolens init . --target codex` 在 Codex 配置中注册的 RepoLens 根目录，以及 `REPOLENS_MCP_ROOTS` 中以分号分隔的额外根目录。 示例 JSON-RPC 调用： ```json {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"repolens_status","arguments":{}}} ``` 切换到另一个工作区： ```json {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"repolens_switch_workspace","arguments":{"workspaceRoot":"D:\\Github\\DataBloom"}}} ``` 针对特定工作区调用一个工具： ```json {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"repolens_search","arguments":{"workspaceRoot":"D:\\Github\\DataBloom","query":"askLmStudioAssistant","limit":5}}} ``` 捆绑示例： ```json {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"repolens_bundle","arguments":{"ops":[{"tool":"repolens_status","arguments":{}},{"tool":"repolens_search","arguments":{"query":"ProjectIndex","limit":3}}]}}} ``` 如果 `workspaceRoot` 传递给 `repolens_bundle`，则嵌套操作继承它，除非操作提供自己的 `workspaceRoot`。 ## 配置 RepoLens 读取存储库根目录下的 `.repolensrc.toml` 文件（如果存在）。 示例： ```toml max_file_size = "1mb" allow_sensitive = false include_hidden = false ``` 默认值： - `max_file_size = "1mb"` - `allow_sensitive = false` - `include_hidden = false` 默认情况下，RepoLens 遵循类似 `rg` 的存储库过滤：`.gitignore`、git 排除、全局 gitignore 和隐藏文件都被尊重。只有当必须索引隐藏的项目文件（如 `.github` 或 `.vscode`）时，才设置 `include_hidden = true`。 可以复制一个示例文件： ```powershell copy .repolensrc.example.toml .repolensrc.toml ``` ## 安全默认值 RepoLens 跳过重量级或生成的目录： - `.git` - `.repolens` - `node_modules` - `target` - `dist` - `build` - `.next` - `.cache` - `.venv` - `__pycache__` RepoLens 默认阻止敏感名称： - `.env` - `.env.*` - `*.pem` - `*.key` - `id_rsa` - `id_ed25519` - `credentials*` - `secrets*` 仅在受控的本地测试中设置 `allow_sensitive = true`。 ## 开发 ```powershell cargo fmt --check cargo test cargo clippy --all-targets -- -D warnings ``` 当前测试覆盖率包括： - 路径安全 - 扫描器和 `.gitignore` - 二进制检测 - 配置解析 - 单词/三元组提取 - 符号提取 - 依赖提取 - TS/JS 相对依赖解析 - 前向/反向依赖图 - 监视器状态跟踪 - HTTP 回环保护 - 快照保存/加载 - 二进制快照保存/加载 - MCP 请求处理 ## 路线图 下一个计划工作： - 大型存储库的性能报告。 长期目标： - 更强大的 MCP 自动配置变体。