代码搜索
AI代理的多仓库语义代码搜索——一个具有向量+BM25混合检索、符号导航和跨仓库编排的Rust MCP服务器。完全本地,完全离线,没有GPU,没有Docker。
codesearch通过5个统一的MCP工具为AI代理(OpenCode、Claude Code、Cursor和任何MCP客户端)提供了深入的代码库理解。索引一次,同时在多个存储库中进行语义搜索。
为什么要进行代码搜索?
- 多回购服务模式:使用跨回购RRF排名在存储库组之间展开查询
- 混合检索:向量嵌入+BM25全文搜索与互序融合
- 符号导航:跳转到定义、查找用法、跟踪导入和依赖项——在同一个工具中
- AST感知分块:9种语言的树型解析——块与函数/类对齐,而不是任意的行范围
- 代币高效:默认情况下返回元数据;代理仅在需要时通过以下方式获取完整代码
get_chunk - 占地面积轻:磁盘上有数百MB,仅在CPU上运行,没有运行时模型下载(在企业代理后面工作)
- 单仓库零配置:
codesearch index && codesearch mcp--完成了
与此相比如何?
MCP代码搜索生态系统在2025年底/2026年初迅速发展,许多项目共享相同的基线堆栈(Rust+树保姆+BM25+嵌入+MCP)。codesearch的重点是:
| 重点领域 | 代码搜索 | 典型替代方案 |
|---|---|---|
| 存储库范围 | 多回购与交叉回购RRF服务 | 通常一次只有一个回购 |
| 占地面积 | ~数百MB,仅CPU,无Docker | GB规模,GPU,Docker或云 |
| 企业/离线 | 无运行时获取;静态二进制 | 经常在第一次运行时拉取模型 |
| 符号导航 | find (定义/用法/导入/依赖项)与语义搜索位于同一位置 |
通常是一个单独的代码图工具 |
| 每次通话的令牌成本 | compact=true 默认情况下;按需获取块 |
经常转储完整片段 |
同一利基市场中的其他项目可能会在调用图遍历、抛光的独立CLI或内存/知识图功能方面做得更深入。codesearch有意地缩小了范围——它选择了“轻量级、多仓库、MCP原生、完全离线”,并保持在那个通道上。
建筑```mermaid
graph TB
Agent[AI Agent / MCP Client] -->|MCP stdio or HTTP| Router{MCP Router}
Router --> Search[search tool]
Router --> Find[find tool]
Router --> Explore[explore tool]
Router --> GetChunk[get_chunk tool]
Router --> FindImpact[find_impact tool]
Router --> Status[status tool]
Search -->|mode=semantic| Semantic[Vector ANN + BM25 + RRF Fusion]
Search -->|mode=literal| Literal[Tantivy FTS / Regex]
Find -->|definition/usages| SymbolIndex[Symbol Index]
Find -->|imports/dependents| DepGraph[Dependency Graph]
Explore -->|outline| TreeSitter[Tree-sitter AST]
Explore -->|similar| Semantic
Semantic --> Arroy[arroy ANN vectors]
Semantic --> Tantivy[Tantivy BM25]
Arroy --> LMDB[(LMDB)]
Tantivy --> TantivyIdx[(Tantivy Index)]
GetChunk --> LMDB
FindImpact -->|C# symbols| CSharpHelper[scip-csharp helper]
CSharpHelper -->|SCIP index| ScipLMDB[(LMDB scip_symbols)]
subgraph "Serve Mode (multi-repo)"
ServeRouter[HTTP Router] -->|project/group routing| Repo1[Repo A]
ServeRouter --> Repo2[Repo B]
ServeRouter --> RepoN[Repo N]
end
Router -->|client mode| ServeRouter
## 快速开始
### 安装
从下载预构建的二进制文件 发布:
|平台|下载|
|----------|----------|
|Windows x86_64| `codesearch-windows-x86_64.zip` |
|Windows x86_64+C#| `codesearch-windows-x86_64-with-csharp.zip` |
|Linux x86_64| `codesearch-linux-x86_64.tar.gz` |
|Linux x86_64+C#| `codesearch-linux-x86_64-with-csharp.tar.gz` |
|macOS ARM64| `codesearch-macos-arm64.tar.gz` |
|macOS ARM64+C#| `codesearch-macos-arm64-with-csharp.tar.gz` |
或者从源代码构建:```bash
git clone https://github.com/flupkede/codesearch.git
cd codesearch
cargo build --release
为存储库建立索引```bash
Register and index the current repo (adds to ~/.codesearch/repos.json)
codesearch index add
Register and index a repo from outside the repo folder
codesearch index add /path/to/my-project
Incremental update (only changed files)
codesearch index /path/to/my-project
Full rebuild
codesearch index /path/to/my-project --force
Remove a repo
codesearch index rm /path/to/my-project
List registered repos
codesearch index list
`codesearch index add` 旨在从您要注册的仓库内部运行。
如果你从其他地方启动它,请明确传递repo路径。
首次索引需要2-5分钟。后续运行是递增的(10-30秒)。分支开关触发自动重新索引。
## MCP配置
codesearch通过MCP连接到AI代理。两种模式:
|模式|如何|最适合|
|------|-----|----------|
| **本地(stdio)** | `codesearch mcp` --单个仓库,自动索引+文件监视|在一个项目上工作|
| **服务(HTTP)** | `codesearch serve` --多仓库、TUI仪表板、懒惰FSW |多仓库、跨仓库搜索|
### 本地/单一代表
代理人产卵 `codesearch mcp` 作为一个子流程。它会自动检测最近的索引并启动文件监视器。
**OpenCode** — `~/.config/opencode/config.json`:```json
{
"mcp": {
"codesearch": {
"type": "local",
"command": ["codesearch", "mcp"],
"enabled": true
}
}
}
克劳德代码 — ~/.config/claude-code/config.json:```json
{
"mcpServers": {
"codesearch": {
"command": "codesearch",
"args": ["mcp"]
}
}
}
**克劳德桌面版** — `claude_desktop_config.json`:```json
{
"mcpServers": {
"codesearch": {
"command": "codesearch",
"args": ["mcp"]
}
}
}
服务/多重回购
先启动服务器,然后连接您的代理。服务器使用TUI仪表板、懒惰的文件系统监视器和空闲驱逐来管理所有注册的存储库。```bash
Start the server (default port 39725)
codesearch serve
**OpenCode** --通过HTTP连接:```json
{
"mcp": {
"codesearch": {
"type": "remote",
"url": "http://127.0.0.1:39725/mcp",
"enabled": true
}
}
}
克劳德代码/克劳德桌面 --通过强制服务连接 --mode client:```json
{
"mcpServers": {
"codesearch": {
"command": "codesearch",
"args": ["mcp", "--mode", "client"]
}
}
}
> **注:** 在多回购模式下,代理必须指定 `project` 或 `group` 在工具调用中。 `status` 总是在没有范围的情况下工作。 `get_chunk` 当chunk_id在存储库中唯一时自动路由;如果不明确,则返回候选者并要求 `project`.
## MCP工具参考
### `search` --代码搜索
参数 · 类型 · 说明
`query` · string · 自然语言、代码片段、正则表达式或精确术语
`mode` · `"semantic"` · `"literal"` · 搜索后端(默认:语义)
`filter_path` · string · 路径前缀过滤器(语义模式)
`file_glob` · string · 全局过滤器(文字模式),例如。 `"src/**/*.rs"`
`language` · string · 语言过滤器(文字模式)
`regex` · bool · 将查询视为正则表达式(文字模式)
`phrase` · bool · 精确短语匹配(文字模式)
`compact` · bool · 仅元数据,无代码(默认值:true)
`limit` · int · 最大结果(默认值:10个语义,20个文字)
`project` · string · 目标特定回购(多回购)
`group` · string · 跨回购组搜索(多回购)
**语义模式** 结合向量相似度(fastembed)+BM25词汇评分+精确标识符增强,与RRF融合。最适合概念查询和混合自然语言+符号搜索。
**文字模式** 使用Tantivy FTS。使用 `regex=true` 用于带标点符号的图案(`foo::bar`, `Vec`).使用 `phrase=true` 用于多词精确匹配。
### `find` --符号导航
参数 · 类型 · 说明
`symbol` · string · 符号名称或文件路径(用于导入)
`kind` · `"definition"` · `"usages"` · `"imports"` · `"dependents"` · 导航类型
`definition_kind` · string · 过滤器:函数、类、方法、结构、特性、枚举、接口
`project` / `group` · string · 多仓库路由
### `explore` --文件探索
参数 · 类型 · 说明
`target` · string · 文件路径(大纲)或chunk_id(类似)
`kind` · `"outline"` · `"similar"` · 勘探类型
`limit` · int · 类似模式的最大结果
`project` / `group` · string · 多仓库路由
**大纲** 返回文件中的所有顶级符号(种类、签名、行范围)。
**相似** 查找与给定chunk_id语义相关的块。
### `get_chunk` --读取代码
|参数|类型|说明|
|-----------|------|-------------|
| `chunk_id` |int |从搜索/探索结果中提取ID|
| `context_lines` |int |前后额外行数(0-20,默认值:0)|
| `project` |string |如果chunk_id存在于多个存储库中,则消除歧义|
在多仓库模式下:当chunk_id唯一时自动路由;当不明确时返回候选人列表。
### `find_impact` --符号参考影响
通过每种语言的语义分析,以文件/行精度查找所有调用点和对符号的引用。目前支持 **C** (通过捆绑 `scip-csharp` 助手)。
|参数|类型|说明|
|-----------|------|-------------|
| `symbol_name` |string |符号名称(例如。 `"FieldDefinition.Validate"`) |
| `file` |string |基于位置的查找的文件路径|
| `line` |int |基于位置的查找行号|
| `language` |string |语言提示(从文件扩展名自动检测)|
| `project` / `group` |string |多仓库路由|
返回引用列表 `file`, `start_line`, `end_line`,以及 `kind` (例如。 `"call"`, `"definition"`).暴露 `index_age_seconds` 因此,代理人可以推断出陈旧性。
> **注:** 需要 `-with-csharp` 发布变体或单独安装 `scip-csharp` 帮手。看 C#语义搜索.
### `status` --索引信息
参数 · 类型 · 说明
`kind` · `"index"` · `"projects"` · 查询什么
`project` / `group` · string · 多仓库路由
## 服务模式(多代表)
对于同时跨多个存储库工作:```bash
codesearch serve
这将启动一个后台HTTP服务器:
- TUI仪表板 (ratatui)显示仓库状态、CPU使用率、活动会话
- 懒惰的文件系统观察者 --在每个仓库的第一次查询时激活
- 闲置驱逐 (30分钟)--从内存中卸载未使用的存储库
- 会话跟踪 通过MCP保持活力
存储库注册
repo通过以下方式注册 codesearch index add:```bash
Register a repo (creates index + adds to ~/.codesearch/repos.json)
codesearch index add /path/to/my-project --alias my-project
Remove a repo
codesearch index rm /path/to/my-project
List registered repos
codesearch index list
服务阅读 `~/.codesearch/repos.json` 启动时,管理所有已注册的存储库。
### 群组
组允许您在相关存储库中搜索:```bash
codesearch groups add my-group repo1 repo2 repo3
codesearch groups list
然后在MCP工具中: group="my-group" 将查询扇出到组中的所有repo。
MCP连接模式
这 codesearch mcp 命令支持三种模式:
| 模式 | 行为 |
|---|---|
auto (默认) |
如果正在运行,则连接服务,否则连接本地stdio |
client |
始终连接到服务,如果不运行则失败 |
local |
始终使用本地数据库(经典的单仓库stdio) |
codesearch mcp --mode client # force serve connection
服务端点位于 /mcp (流式HTTP传输)。
CLI参考
命令 · 描述
codesearch index [PATH] · 为回购建立索引(增量; --force 全面重建)
codesearch search · CLI搜索(用于测试)
codesearch mcp · 启动MCP stdio服务器
codesearch serve · 使用TUI启动多仓库HTTP服务器
codesearch stats · 显示数据库统计信息
codesearch clear · 删除索引
codesearch doctor · 健康检查(型号、索引、配置)
codesearch setup · 下载嵌入模型
codesearch cache stats\ · clear · 管理嵌入缓存
codesearch groups list\ · add\ · remove · 管理存储库组
配置
环境变量
| 变量 | 描述 |
|---|---|
CODESEARCH_SERVE_PORT |
服务模式端口(默认值:39725) |
CODESEARCH_MCP_MODE |
MCP模式:自动、客户端、本地 |
CODESEARCH_REPOS_CONFIG |
repos.json的路径 |
CODESEARCH_REPO_IDLE_TIMEOUT_SECS |
空闲驱逐超时(默认值:1800) |
CODESEARCH_CACHE_MAX_MEMORY |
嵌入缓存MB(默认值:500) |
CODESEARCH_BATCH_SIZE |
嵌入批量大小 |
CODESEARCH_SCIP_CSHARP |
覆盖路径 scip-csharp 助手 |
RUST_LOG |
日志级别(例如。 codesearch=debug) |
.codesearchignore
放在repo根目录中。Gitignore语法。从索引中排除路径:```gitignore
Vendored code
vendor/
node_modules/
Generated files
.generated.cs
/migrations/*
### `repos.json`
位于 `~/.codesearch/repos.json`.由管理 `codesearch index add/rm`。包含回购别名→ 路径和组定义。看 服务模式.
## C#语义搜索
所有C#特定的设置、操作、安装和测试都存在于 README_CSharp.md.
如果你不使用C#repos,你可以完全跳过它。
## 支持的语言
树保姆AST感知组块:
|语言|扩展|
|----------|-----------|
|生锈| `.rs` |
python `.py` |
JavaScript · `.js`, `.jsx`
TypeScript · `.ts`, `.tsx`
C `.c`, `.h` |
C `.cpp`, `.hpp` |
C `.cs` |
去吧 · `.go`
Java `.java` |
所有其他文本文件都使用基于行的分块作为回退。
## 核心技术
|组件|技术|
|-----------|-----------|
|嵌入|fastembed+ONNX运行时(CPU)|
|矢量存储| arroy(近似最近邻)+LMDB|
|全文搜索| Tantivy(BM25,AND模式)|
|分块|树型AST解析|
|增量同步|SHA-256内容哈希|
|缓存| 3层:内存中(Moka)→ 永久磁盘→ 查询缓存|
|架构|通过版本化 `metadata.json` |
## 发展```bash
# Build
cargo build
# Run tests
cargo test
# Check + lint
cargo clippy --all-targets -- -D warnings
# Format
cargo fmt --all
许可证
阿帕奇-2.0
致谢
这个项目是 恶魔 通过 选项非常感谢你建立了如此坚实的基础。
内置: fastembed rs, 干河床, 突进, 树保姆, 骑, LMDB.
