代码侦察员
MCP服务器为AI编码代理提供IDE级代码智能——符号导航， 语义搜索、持久内存——针对令牌效率进行了优化。
📖 **** --安装、代理集成、工具参考、检索堆栈设置和架构。
适用于Claude Code、GitHub Copilot、Cursor和任何支持MCP的代理。
它的作用
- 符号导航 —
symbols,references,symbol_at,call_graph,edit_code，由9种语言的LSP支持 - 语义搜索 --使用捆绑的ONNX嵌入模型（22MB，零设置）按概念查找代码，而不是grep
- 图书馆导航 --通过范围搜索、版本跟踪和自动发现来探索依赖源代码
- 多项目工作空间 --在中注册相关项目
workspace.toml用于跨项目导航，具有每个项目的内存和索引 - 代币效率 --默认情况下紧凑，按需提供详细信息，从不转储完整文件
为什么不直接读取文件呢？
| 无codescout | 有codescout |
|---|---|
| 代理读取完整文件以查找一个函数 | 按符号名称导航——零文件读取 |
grep 返回噪声（注释、字符串、文档） | references 返回确切的呼叫站点 |
| 上下文消耗导航开销 | 令牌设计高效——默认紧凑 |
| 会话之间的状态丢失 | 会话之间的持久内存 |
| 从不同的入口点重新读取相同的模块 | 一次构建符号索引，立即查询 |
快速开始
cargo build
./target/debug/codescout start --project /path/to/code在中添加codescout作为MCP服务器 ~/.claude/settings.json:
{
"mcpServers": {
"codescout": {
"command": "codescout",
"args": ["start", "--project", "."]
}
}
}然后在Claude Code中使用——它将通过codescout的工具路由所有文件/符号/搜索操作。
入职培训至关重要。 在开始新项目的工作之前，运行 onboarding() --它发现语言，读取关键项目文件，以及 生成特定于项目的系统提示和内存文件。没有它， 代理没有项目上下文，将在代码库中盲目导航。 请参阅 Claude代码集成指南 了解详情。提示： 安装 codescout配套插件 在每个会话中自动引导Claude使用codescout工具，包括子代理。
检索堆栈
codescout使用外部Docker Compose堆栈（Qdrant+llama服务器+TEI） 语义嵌入和混合检索。 需要 semantic_search.
两个配置文件： cpu （笔记本电脑/无GPU开发）和 gpu （单个CUDA卡）。
# 1. download the dense embedding model (~90MB, once)
mkdir -p ./models
curl -L -o ./models/CodeRankEmbed-Q4_K_M.gguf \
https://huggingface.co/brandtcormorant/CodeRankEmbed-Q4_K_M-GGUF/resolve/main/coderankembed-q4_k_m.gguf
# 2. start the stack — pick one profile
docker compose --profile cpu --env-file .env.cpu up -d # ~3GB RAM, no GPU
# OR
docker compose --profile gpu --env-file .env.gpu up -d # ~6GB RAM, 1.5GB VRAM
# 3. wait for sparse + rerank to warm up (~30-60s first run, downloads from HF)
docker compose ps
# 4. source env, build the per-project index
set -a; source .env.cpu; set +a # or .env.gpu
cargo run --release --bin sync_project -- . codescout| 服务 | 配置文件 | 图像 | 默认URL |
|---|---|---|---|
| qdrant | 两者都有 | qdrant/qdrant:v1.17.0 | http://127.0.0.1:6333（HTTP），：6334（gRPC） |
| 密集型（CodeRankEmbed-Q4） | cpu | ghcr.io/ggml-org/llama.cpp:server | http://127.0.0.1:48081 |
| 密集型（CodeRankEmbed-Q4） | gpu | ghcr.io/ggml-org/llama.cpp:server-cuda | http://127.0.0.1:48081 |
| 稀疏（Splade_PP_en_v1） | 两者都有 | ghcr.io/huggingface/text-embeddings-inference | http://127.0.0.1:48084 |
| 重新登录（bge重新登录库） | cpu | text-embeddings-inference:cpu-1.6 | http://127.0.0.1:48083 |
| 再存储（bge-ranker-v2-m3） | gpu | text-embeddings-inference:86-1.8 | http://127.0.0.1:48083 |
CodeRankEmbed是不对称的-- CODESCOUT_QUERY_PREFIX 在 .env.{cpu,gpu} 是必需的。 该堆栈的经验得分：传统自然基准上的30/60（见 docs/trackers/retrieval-benchmark.md).
索引速度
根据这个代码库（约18k块，密集嵌入器是唯一的 有意义的瓶颈；在同步过程中不使用稀疏/重排序）：
| 配置文件 | 单块p50 | 持续吞吐量 | 初始同步（~18k块） |
|---|---|---|---|
| cpu（llama服务器，4线程） | 600ms | 2.4块/秒 | 约125分钟 |
| gpu（骆驼服务器cuda，RTX A5000） | 7.6毫秒 | 117-132块/秒 | 约2.6分钟 |
~50倍的差距与典型的CPU相匹配↔量化137M嵌入器的GPU比率。 初始索引后的增量同步在两种配置文件上都很好——仅 更改的块重新嵌入。如果你在CPU上，你的项目比 大约2k个块，预计会让第一个同步保持运行。
停止堆栈：
docker compose --profile cpu down # or --profile gpu代理集成
| 代理 | 指南 |
|---|---|
| 克劳德代码 | docs/agents/claude-code.md |
| GitHub副本 | docs/agents/copilot.md |
| 光标 | docs/agents/cursor.md |
多代理基础架构
codescout的设计是基于对多智能体系统中复合误差的研究——研究和实证证据证实，生产管道中的故障率为41-87%。这一发现促使人们选择基于单会话技能的工作流，而不是代理编排链。 阅读分析→
科特林
codescout围绕Kotlin的现实构建了一流的Kotlin支持 项目启动成本高昂，JetBrains的kotlin lsp只允许一个lsp 每个工作区的进程。
- LSP多路复用器 --超然的
codescout mux进程共享一个
kotlin-lsp JVM跨所有codescout实例。无需配置。 冷启动（8-15秒JVM启动）发生一次；后续会话连接 立即。
- 并发实例安全 --每个实例都有一个隔离的系统路径
使用断路器防止IntelliJ平台锁争用 失败得很快，而不是超时。
- Gradle隔离 --每个实例
GRADLE_USER_HOME消除守护进程
锁定并行会话之间的争用。
| 度量 | 无多路复用 | 有多路复用 |
|---|---|---|
| kotlin lsp JVM每台机器 | 1个会话（每个约2GB） | 1个共享（总共约2GB） |
| 第二阶段冷启动 | 8-15s | ~0s（多路复用器已经预热） |
| 典型LSP响应 | 120s+超时 | 30-270ms |
工具（20）
Symbol navigation (5) · File operations (7) · Shell (1) · Semantic search (2) · Memory (1) · Library navigation (1) · Workflow & Config (3)
支持的语言：Rust、Python、Types/JavaScript、Go、Java、Kotlin、C/C++、C#、Ruby。
→ 工具参考
语义搜索和嵌入
codescout捆绑包 全迷你LM-L6-v2 （量化，22MB）作为其默认嵌入模型。 它通过ONNX本地运行-无需外部服务器，无需API密钥，无需GPU。首先 index(action: build)，模型下载一次到 ~/.cache/huggingface/hub/.
对于使用Ollama或GPU的用户，codescout还支持外部嵌入服务器 （Ollama、OpenAI、llama.cpp、vLLM、TEI）通过标准 /v1/embeddings API
实验性功能
新功能登陆 experiments 到达之前的分支 master. 它们可能会更改或删除，恕不另行通知，并且可能尚未包含在您安装的版本中。
→ 浏览实验功能
贡献
看 贡献.md 关于如何开始。欢迎来自Claude Code的PR！
特性
- 支持多项目工作区，支持每个项目的LSP、内存和语义索引
- 通过每个库嵌入数据库和版本过时提示进行库导航
- LSP空闲TTL——空闲语言服务器自动关闭（Kotlin:2小时，其他：30分钟），并在下次查询时透明地重新启动
- 具有语义回忆的会话间持久记忆
- 输出缓冲器(
@cmd_*,@file_*)用于令牌高效的大输出处理 - 渐进式披露——默认情况下紧凑，按需提供全部细节