内容
# 代理增强器
通过仅路由重要的代码，将 AI 编码代理令牌成本降低 5-15 倍。
与其在每次读取时将完整源文件发送到模型，不如使用代理增强器构建代码库的符号索引，并仅返回与当前任务相关的函数和类。
## 工作原理
```
无增强器 使用增强器
───────────────── ────────────────────────────
读取 executor.py 智能读取 executor.py + 任务
→ 1,881 行（约 6k 令牌） → 3 个匹配函数（约 200 令牌）
```
五层技术共同工作：
| 层 | 功能 |
|---|---|
| **符号索引** | tree-sitter 解析每个 `.py`、`.ts`、`.tsx`、`.js`、`.jsx` 文件，将函数/类提取到 SQLite |
| **向量嵌入** | sentence-transformers 对每个符号进行编码，以便语义搜索 |
| **智能读取** | 给定文件 + 任务，运行每个文件的向量搜索，仅返回匹配的符号行范围 |
| **MCP 服务器** | 通过 stdio 公开四种工具 — 任何兼容 MCP 的代理都可以调用它们 |
| **平台初始化** | 一条命令为 Claude Code、Cursor、Windsurf 或 Codex 编写正确的配置 |
## 安装
需要 Python 3.10+。
```bash
pip install agent-booster # 符号索引 + MCP 工具
pip install agent-booster[embed] # + 语义向量搜索（推荐）
```
## 快速入门
**步骤 1 — 连接您的 AI 工具**
```bash
booster init claude # Claude Code
booster init cursor # Cursor
booster init windsurf # Windsurf
booster init codex # OpenAI Codex CLI
booster init all # 所有四个
```
每个命令都会显示将更改哪些文件，询问确认，然后写入文件。完全可逆：
```bash
booster remove claude # 或 cursor、windsurf、codex、all
```
示例 — 连接 OpenAI Codex (`booster init codex` → `booster start` → `booster gain`):
> **每个项目运行一次，而不是每个会话。**
> 钩子位于 `.claude/settings.json` 和 `.mcp.json` 在项目根目录。
> 在此目录中打开的任何 Claude Code 会话 — 任何终端窗口，同一台机器 — 都可以自动拾取它们。
> 不需要每个会话设置。
**步骤 2 — 索引您的代码库**
从项目根目录运行一次。在大型重构后重新运行。
```bash
booster index && booster embed
# 索引 260 个文件，1800 个符号。
# 为 1800 个符号构建嵌入。
```
索引存储在 `.booster/`（gitignored）。索引在所有会话中共享。
**步骤 3 — 重新启动您的 AI 工具**
`agent-booster` MCP 服务器现在可在每个会话中使用。Claude Code（和其他工具）将自动在索引文件上使用 `smart_read` 和 `search_context`。
**步骤 4 — 跟踪节省**
```bash
booster gain
```
## CLI 参考
### `booster init <平台>`
为目标平台编写 MCP 服务器配置和规则文件。在进行任何更改之前询问确认。
```bash
booster init claude # .mcp.json + CLAUDE.md + .claude/settings.json 钩子
booster init cursor # .cursor/mcp.json + .cursorrules
booster init windsurf # ~/.windsurf/mcp.json + .windsurfrules
booster init codex # ~/.codex/config.json + AGENTS.md
booster init all # 所有四个
booster init claude --yes # 跳过确认（CI/脚本）
```
### `booster remove <平台>`
干净地撤销 `init` 编写的全部内容。无残留。
```bash
booster remove claude
booster remove cursor
booster remove windsurf
booster remove codex
booster remove all
```
### `booster index`
扫描当前目录下的所有 `.py`、`.ts`、`.tsx`、`.js`、`.jsx` 文件。将函数、类、方法和接口提取到 `.booster/symbols.db`。跳过 `node_modules`、`.venv`、`__pycache__`、`.git`、`.booster`、`.next`、`dist`、`build`。
```bash
booster index
# 索引 260 个文件，1800 个符号。
```
### `booster embed`
为所有索引符号构建句子转换器向量嵌入。语义 `search_context` 调用所需。在本地使用，不会离开您的机器。
```bash
booster embed
# 为 1800 个符号构建嵌入。
```
### `booster search "<查询>"`
跨所有索引符号的关键字搜索。返回文件路径、行号、种类、名称和签名。
```bash
booster search "guard install"
# apps/web/src/app/settings/modules/page.tsx:99 函数 handleInstall 函数 handleInstall() {
```
### `booster route "<任务>"`
根据任务复杂性 — 关键字信号、文件数量和符号数量 — 推荐 `haiku`、`sonnet` 或 `opus`。
```bash
booster route "fix the guard SSE role check"
# haiku （狭窄任务 — 0 符号在 1 个文件中）
booster route "refactor the entire runtime compiler and DSL layer"
# opus （匹配复杂性关键字）
```
### `booster serve`
通过 stdio 启动 MCP 服务器。通过 `booster init` 配置后，Claude Code、Cursor、Windsurf 和 Codex 会自动调用。你很少需要直接运行此命令。
### `booster gain`
显示过去 `smart_read` 调用的令牌节省 — 总读取量、提供令牌与节省令牌、节省率和按节省量排名的前几个文件。
```
代理增强器 — 令牌节省报告
─────────────────────────────────────
活动天数： 3
总读取量： 47
提供令牌： 12,400
节省令牌： 89,200
节省率： 88%
按节省量排名的前几个文件：
executor.py 18,400 令牌已节省 (12 次读取)
guard.py 14,200 令牌已节省 (8 次读取)
```
## MCP 工具
`booster serve` 运行后，以下四种工具可供代理使用：
### `get_symbols(文件)`
返回文件的索引符号 — 名称、种类、行范围和签名。不需要读取文件。
```
输入： { "file": "apps/api/app/runtime/executor.py" }
输出： function run_workflow (lines 42-89): def run_workflow(...)
class WorkflowState (lines 91-140): class WorkflowState:
```
### `search_context(任务)`
跨索引中的所有符号进行语义向量搜索。返回按余弦相似度排名的前 10 个匹配结果。如果嵌入未构建，则回退到关键字搜索。
```
输入： { "task": "guard install uninstall" }
输出： apps/web/src/app/settings/modules/page.tsx:99 函数 handleInstall — 函数 handleInstall() {
apps/web/src/components/guard/GuardNav.tsx:13 函数 GuardNav — 函数 GuardNav() {
...
```
### `smart_read(文件, 任务)`
运行每个文件的向量搜索，仅返回匹配符号的源代码行，并附有显示名称和行范围的标题。如果没有符号匹配，则返回明确的消息，以便模型知道回退到完整读取，而不是默默地接收整个文件。
```
输入： { "file": "apps/api/app/runtime/executor.py", "task": "execute output block" }
输出： # 函数 _execute_output (lines 1165-1210)
def _execute_output(block, state, credentials, ...):
...
```
### `route_model(任务, 文件?)`
根据任务复杂性信号推荐 `haiku`、`sonnet` 或 `opus`。如果省略 `files`，则通过 `search_context` 自动检测。
```
输入： { "task": "fix the login redirect bug" }
输出： { "model": "haiku", "reason": "狭窄任务 — 1 个符号在 1 个文件中" }
```
## `booster init claude` 编写的内容
| 文件 | 更改 |
|---|---|
| `.mcp.json` | 将 `agent-booster` 添加到 `mcpServers` |
| `CLAUDE.md` | 追加增强器用法规则块（哨兵标记） |
| `.claude/settings.json` | 连接 `PreToolUse` （读取 + Grep）和 `UserPromptSubmit` 钩子 |
| `.claude/hooks/booster-gate.py` | **阻止** 索引文件上的 `Read` — 强制 `smart_read` |
| `.claude/hooks/booster-grep-nudge.py` | **提示** 语义 `Grep` 模式朝向 `search_context` |
| `.claude/hooks/booster-route.py` | **自动路由模型** — 在每个用户回合上推荐 haiku/sonnet/opus |
`booster remove claude` 删除所有六个文件并清理设置条目。无残留。
## 适用场景
代理增强器是三层令牌减少堆栈中的第三层：
```
第 3 层 — 代理增强器 AST+语义路由，智能文件读取
第 2 层 — RTK CLI/git/构建输出的令牌压缩
第 1 层 — 提示缓存 稳定上下文重用（原生于 Claude Code + API）
```
每层都是独立且可单独添加的。
## 常见问题
**如果我打开第二个终端，它是否有效？**
是的。钩子被连接到 `.claude/settings.json` 和 `.mcp.json` 在您的项目根目录中 — 而不是在特定的终端会话中。在此项目中打开的任何新的 Claude Code 窗口都可以自动拾取它们。
**我需要在重启机器后再次运行 `booster init` 吗？**
不需要。`booster init` 将文件写入磁盘一次。它们在重启和会话之间持续存在。您只需要在删除这些文件或切换到新项目时重新运行它。
**我的队友是否也需要运行 `booster init`？**
是的 — 每个开发人员，每个项目一次。如果您将 `.mcp.json` 和 `.claude/settings.json` 提交到存储库，队友在克隆时可以获得钩子。他们仍然需要本地运行 `pip install agent-booster[embed]` 和 `booster index && booster embed`，因为符号索引是 gitignored 的。
**我可以完全撤销它吗？**
是的。`booster remove claude` 删除所有六个文件并清理设置条目。无残留。
## 项目布局
```
tools/booster/
├── README.md
├── pyproject.toml
└── booster/
├── cli.py # click 命令：index、embed、search、serve、init、remove、route、gain
├── indexer.py # tree-sitter 解析器 + SQLite 符号存储 + 向量搜索
├── retriever.py # smart_read：每个文件的向量搜索 → 相关行切片
├── mcp_server.py # MCP 服务器：get_symbols、search_context、smart_read、route_model
└── stats.py # 令牌节省跟踪（booster gain）
```
