内容
 
 
 
# 代码库代理-MCP
代码库代理-MCP是一个MCP服务器，它使用轻量级RAG流水线将代码库分析委托给专用的OpenAI兼容LLM。 与其强制要求主要编码助手反复扫描大型代码库，不如让它单独执行这项工作，并仅返回当前任务所需的信息。
它可以与本地模型（如Gemma或Qwen）以及价格低廉的OpenAI兼容云提供商一起运行，从而在保持主要助手专注于推理和代码生成的同时，减少延迟和令牌消耗。
可选的Qdrant集成可以缓存以前的检索结果，目前正在计划演进为连接代码库的语义检索代码实体（文件、类和函数）。
## 为什么
现代编码代理经常花费数千（有时数百万）个令牌重新阅读代码库、依赖项源和文档，然后才能开始解决实际任务。
当以下情况时，这变得更加昂贵：
- 项目正在积极演进；
- 文档不完整或过时；
- 必须直接检查源代码；
- 每个新代理会话都从空上下文开始。
代码库代理-MCP将此探索委托给专用分析模型。 主要编码助手仅接收相关发现，而无需重复处理整个代码库。
## 工作原理
1. 将您的本地或低成本云LLM连接到代码库代理-MCP。
2. 将代码库代理-MCP作为MCP服务器连接到您的执行器（ClaudeCode、Codex、OpenCode等）。
3. 以短语“使用技能`libraries-analysis-skill`”开始您的开发提示，以降低成本。
## 基准测试
### 任务
[task.md](example/prompts/cengal_based_system_of_apps/task.md) - 编写两个小型应用程序，合计约200行代码，使用[Cengal](https://github.com/FI-Mihej/Cengal)库（进程间通信、异步多进程应用程序，带有TUI、异步wxPython GUI）。
在现实世界的开发中，输出令牌的数量相对于每次会话必须重新读取的项目数据量也相对较小，而这些数据量会消耗输入令牌。 工作和相关成本的规模要大得多。
### 测量
（禁用代码库代理-MCP中的VectorDB缓存，以在最坏的情况下评估性能。）
搜索和Cengal代码库分析阶段消耗的令牌：
| 方法 | 所有输入令牌 | 输入令牌 | 缓存输入令牌 | 输出令牌 |
| --- | --- | --- | --- | --- |
| 无 | 791930 | 684087 | 107843 | 5361 |
| 使用代码库代理-MCP | 416160 | 229003 | 187157 | 13755 |
根据各种模型的当前令牌定价估算的成本：
| 方法 | Claude Haiku 4.5 | Claude Sonnet 5（2026年9月1日） | Claude Opus 4.8 | Claude Fable 5 | GPT-5.5 | GPT-5.5-Pro * |
| --- | --- | --- | --- | --- | --- | --- |
| 无 | 0.89美元 | 2.68美元 | 4.46美元 | 8.93美元 | 3.64美元 | 24.72美元 |
| 使用代码库代理-MCP | 0.37美元 | 1.12美元 | 1.87美元 | 3.74美元 | 1.65美元 | 14.96美元 |
| 成本降低（倍） | 2.4 | 2.39 | 2.39 | 2.39 | 2.2 * | 1.65 |
* GPT Pro模型不支持缓存令牌。
* 我使用保守（最小）的估计值来计算缓存令牌。 OpenAI动态计算GPT模型的缓存令牌（GPT Pro除外），这意味着实际记费的缓存令牌数量远高于我的计算结果。 因此，使用代码库代理-MCP的实际优势大于“2.2倍”，因为使用代码库代理-MCP时缓存令牌的比例高于不使用它时的比例。
启用代码库代理-MCP中的VectorDB缓存（`qdrant_*`插件）后，节省效果会更加明显。
### 执行器
基准测试使用OpenCode执行器，因为它提供了主代理会话和所有子代理会话的详细统计信息。
### LLM
在OpenCode执行器端和代码库代理-MCP端均使用`google/gemma-4-12b-qat`模型。
### 提示
* [with__codebase_agent__agents.md](examples/prompts/cengal_based_system_of_apps/opencode/with__codebase_agent__agents.md)
* 代码库代理-MCP的MCP服务器是唯一连接到OpenCode的服务器，代理和技能安装在项目目录中。
* [without__codebase_agent__subagents.md](examples/prompts/cengal_based_system_of_apps/general/without__codebase_agent__subagents.md)
* 随后，所有MCP服务器都从OpenCode断开连接（禁用），不再安装代理或技能。
* 短语“Spawn subagents.”对于普通的OpenCode具有显著优势。 我出于必要使用了它，因为如果不使用它，干净的OpenCode会一致地陷入无限循环：“进行研究->编写一两个文件，直到上下文窗口已满->删除部分对话历史记录，而不是总结它->重新开始”。 同时，连接到OpenCode的代码库代理-MCP服务器即使在没有安装技能或代理的情况下也能成功完成任务，尽管效率略低。
### 缓存输入
每个提供商都以不同的方式实现缓存，有些则根本不支持缓存。 我选择了一种保守的记账方法，可以产生最小的可能缓存令牌数量，以避免高估结果。 特别是，OpenAI的实际缓存令牌数量大约是我的计算结果的1.2-1.5倍，因为OpenAI的动态缓存算法。 因此，使用GPT-5.5的优势可能与使用Anthropic模型的节省效果相当，甚至超过后者。
## 架构
```text
ClaudeCode + Opus -> 代码库代理-MCP -> OpenAI兼容LLM（本地或云）
|
+-> 配置的本地代码库
+-> 内置工具和插件
+-> 可选的Qdrant缓存
+-> 外部MCP插件（任意MCP服务器）
```
## 功能
- 代码和依赖项分析，适用于文件大于连接模型上下文窗口的代码库。
- 自动对话历史记录压缩。
- 通过`qdrant_*`内置插件可选的RAG缓存。
- 沙盒文件系统访问，限定在配置的库根目录内。
- 可插拔的外部stdio MCP工具。
- 与本地OpenAI兼容服务器（如LM Studio、llama.cpp服务器、vLLM兼容端点或兼容托管API）配合使用。
- 与云OpenAI兼容服务器配合使用。
- 异步后台作业，带有SQLite结果持久性。
## 如何开始
1. 安装
2. 配置
3. 连接到您的编码代理
4. 使用代码库代理-MCP
## 安装
1. 安装`uv`：
https://docs.astral.sh/uv/getting-started/installation/
2. 通过`uvx`初始化并创建代码库代理-MCP配置：
```bash
uvx --from codebase-agent-mcp cb-agent-init
```
它将返回您的`codebase_agent.config.json`配置文件路径。
随时可以使用`uvx --from codebase-agent-mcp cb-agent-init`查找配置文件的位置。
### 更新到最新版本
```bash
uvx --from codebase-agent-mcp@latest cb-agent-init
```
这不会影响您的配置。
## 配置
本地LLM的技术细节和配置建议：[docs](docs/main.md)
在启动服务器之前，请编辑`codebase_agent.config.json`。
### 最小配置
定义OpenAI兼容LLM（本地或云）
| 字段 | 用途 |
| --- | --- |
| `base_url` | OpenAI兼容端点。 如果省略，则自动追加`/v1`。 |
| `api_key` | 发送到端点的API密钥。 对于不需要密钥的本地服务器，请使用类似`[EMPTY]`的占位符。 |
| `model` | OpenAI兼容服务器公开的模型名称。 |
| `reasoning_allowed` | 当`false`时，客户端向提供商发送额外提示，在支持的情况下禁用思考/推理。 |
| `reasoning_effort` | 发送请求的推理努力值。 对于支持的模型/端点，请使用`none`。 |
| `max_tokens` | 模型上下文窗口限制（令牌）。 |
本地代码库、依赖项源或文档树，执行器可以分析。
| 字段 | 用途 |
| --- | --- |
| `name` | 作为MCP工具调用中的`library_name`使用的公开名称。 名称必须唯一。 |
| `allowed` | 启用或禁用库。 禁用的库不会被列出或分析。 |
| `path` | 本地目录的绝对路径。 路径必须存在且启用。 |
| `instructions` | 此代码库的额外指导，例如首选API、文档文件夹或项目约定。 |
### Qdrant（可选）
代码库代理-MCP作为[Qdrant](https://github.com/qdrant/qdrant)的客户端：本地或云。
`qdrant_fastembed`和`qdrant_cloud`启用RAG缓存。 默认情况下安装`qdrant_fastembed`客户端。 它们的`configuration`可以包含：
| 字段 | 用途 |
| --- | --- |
| `model_name` | 嵌入模型名称。 如果省略，则默认为`sentence-transformers/all-MiniLM-L6-v2`。 |
| `init` | 传递给`qdrant_client.QdrantClient`的关键字参数，例如`url`、`api_key`或`cloud_inference`。 |
> 在首次使用之前，并在每次更改`qdrant_*`插件配置中的`"configuration"."model_name"`字段后，必须初始化（下载）模型，然后再使用MCP服务器。 过程在下面的“用法”->“Qdrant（可选）”部分中描述。
## 连接到ClaudeCode/Codex等
### 注册为MCP服务器
2. 配置您的MCP客户端（ClaudeCode/Codex/OpenCode/Hermes/PiAgent等）通过`uvx`运行代码库代理-MCP：
```json
{
"mcpServers": {
"codebase-agent-mcp": {
"command": "uvx",
"args": [
"codebase-agent-mcp"
]
}
}
}
```
### 在您的执行器（ClaudeCode/Codex等）中安装子代理和技能
* ClaudeCode：复制`./integration_to/claude/.claude`到项目根目录。
* Codex：复制`./integration_to/codex/.agents`、`./integration_to/codex/.codex`和`./integration_to/codex/.codex/config.toml`到项目根目录。
* OpenCode：复制`./integration_to/opencode/.opencode`到项目根目录。
* Cursor：复制`./integration_to/cursor/.cursor`到项目根目录。
* Antigravity：复制`./integration_to/antigravity/.agents`到项目根目录。 Antigravity缺乏代理概念，这意味着工作将比使用其他执行器效率低。 确保启用隐式缓存以实现显著节省。
* Hermes Agent：复制`./integration_to/hermes/skills`到项目根目录。
* Pi Coding Agent：1. 安装`https://github.com/nicobailon/pi-subagents`或类似解决方案；2. 复制`./integration_to/pi_agent/.pi`到项目根目录。
## 用法
以短语“使用技能`libraries-analysis-skill`”开始您的开发提示。
示例提示：[with__codebase_agent__skills.md](examples/prompts/cengal_based_system_of_apps/general/with__codebase_agent__skills.md)
### Qdrant（可选）
#### 准备模型
在启用`qdrant_*`插件运行代码库代理-MCP之前，并在更改`qdrant_*`插件配置中的`"configuration"."model_name"`字段后，请始终运行：
```bash
uvx --from codebase-agent-mcp cb-agent-ensure-qdrant-models
```
#### 索引依赖库（待完成）
对依赖库代码库进行索引，以将单个实体的关键功能（文件、类、函数）添加到RAG存储中。
```bash
uvx --from codebase-agent-mcp cb-agent-index-dependency-libraries
```
### 保护依赖库代码免受提示注入
将提示注入嵌入到存储库代码中变得越来越普遍。 从Meta维护的存储库（`github.com/facebook/*`）开始，它们主要干扰编码代理，但无害，然后是真正危险的情况，可能导致凭证泄露、社会保障号暴露、经济损失和其他安全事件。
一些简单的例子：
* [他们正在毒害代理！（作者：The PrimeTime）](https://www.youtube.com/watch?v=bh6S4N8TnYQ)
* 提示注入：[github.com/facebook/docusaurus](https://github.com/facebook/docusaurus/blob/main/AGENTS.md)
* 对Claude Code的结果：[PR #12105](https://github.com/facebook/docusaurus/pull/12105)
* [Meta核心开发人员在X上的帖子](https://x.com/mitchellh/status/2067970516951150721)，作者庆祝他们在`AGENTS.md`、代码注释和存储库中其他位置嵌入的提示注入的有效性。
* 提示注入：[github.com/ghostty-org/ghostty](https://github.com/ghostty-org/ghostty/blob/main/AGENTS.md)
* 同样的方法，取得了类似的效果。
现实世界的提示注入使用数百万种有效的措辞变体，并且不断创建新的变体。
* 使用正则表达式或其他原始技术来防御它们是无效的。
* 守卫模型。 即使最好的守卫模型也只能达到约85%的鲁棒性。 这意味着大约六分之一的攻击成功。 对于生产系统来说，这是可以接受的保护级别吗？ 见：[Evaluating the Robustness of Large Language Model Safety Guardrails Against Adversarial Attacks](https://arxiv.org/abs/2511.22047v1)，[Bag of Tricks for Subverting Reasoning-based Safety Guardrails](https://arxiv.org/abs/2510.11570)等。
* 天真的LLM-based检测。 现在有大量研究认为，使用LLM通过提示相同的（或类似的）LLM来检测提示注入从根本上来说是不可靠的，因为检测器本身存在漏洞以及不可接受的高误报和/或误负率，用于生产。 见：[How Not to Detect Prompt Injections with an LLM (2025)](https://arxiv.org/abs/2507.05630)，[WAInjectBench: Benchmarking Prompt Injection Detections for Web Agents](https://arxiv.org/abs/2510.01354)，[Formalizing and Benchmarking Prompt Injection Attacks and Defenses](https://arxiv.org/abs/2310.12815)，[Optimization-based Prompt Injection Attack to LLM-as-a-Judge](https://arxiv.org/abs/2403.17710)等。
#### 解决方案和工具（待完成）
添加新依赖库后（即在配置文件中的`libraries`字段添加新条目），建议对依赖库代码库进行净化，去除其中的提示注入。
该目的的专用工具将很快发布。 请继续关注更新。
它将类似以下方式启动：
```bash
uvx --from codebase-agent-mcp cb-agent-sanitize-library-codebases
```
# Github 仓库
Github仓库是该项目的精选公开镜像。 积极的开发（包括实验代码和私人研究笔记）在私有仓库中进行；定期在此发布选定的快照。
## 路线图
* 支持`qdrant_fastembed_gpu`插件。
* 内部优化和扩展的工具集。
* 集成内容净化系统以保护免受提示注入。
* 为LLM提供关于如何使用连接的MCP服务器的指令的配置字段。
* 用于更快LLM操作的内部子代理层次结构。
# Cengal
基于[Cengal](https://github.com/FI-Mihej/Cengal)
## 使用Cengal的项目
* [text_file_read_and_refactor_mcp](https://github.com/FI-Mihej/text_file_read_and_refactor_mcp) - 高效的Python stdio MCP服务器，公开安全的文本文件搜索、读取和重构工具。 工具自动解析文件BOM和代码页。
* [InterProcessPyObjects](https://github.com/FI-Mihej/InterProcessPyObjects) - 高性能包提供闪电般快速的进程间通信，通过共享内存，使Python对象可以在进程间以异常高效的方式共享。
* [cengal_app_dir_path_finder](https://github.com/FI-Mihej/cengal_app_dir_path_finder) - Python模块提供统一的API，用于轻松检索OS特定的应用程序目录，增强跨Windows、Linux和macOS的数据管理。
* [cengal_cpu_info](https://github.com/FI-Mihej/cengal_cpu_info) - 扩展的缓存CPU信息，具有一致的输出格式。
* [cengal_memory_barriers](https://github.com/FI-Mihej/cengal_memory_barriers) - 快速跨平台Python内存屏障。
* [Bensbach](https://github.com/FI-Mihej/cengal_memory_barriers) - 快速跨平台内存屏障。
* [Bensbach](https://github.com/FI-Mihej/Bensbach) - 从Unreal Engine 3字节码到类似Lisp的脚本和编译回Unreal Engine 3字节码的反编译器。为游戏模制作。
* [Realistic-Damage-Model-mod-for-Long-War](https://github.com/FI-Mihej/Realistic-Damage-Model-mod-for-Long-War) - 适用于原版XCOM:EW和Long War模的模。为Bensbach制作，Bensbach由Cengal制作
# 许可
Copyright © 2026 ButenkoMS. All rights reserved.
Licensed under the Apache License, Version 2.0.
