Agent Booster

此仓库已归档。 Agent Booster 现位于 sseshachala/conductai → tools/booster。请从 PyPI 安装（pip install agent-booster）；在 conductai 上提交问题和 PR。

Agent Booster

通过只路由相关代码，将 AI 编码 Agent 的令牌成本降低 5–15 倍。

Agent Booster 不会在每次读取时都将完整源文件发送给模型，而是为代码库建立符号索引，只返回与当前任务相关的函数和类。

---

工作原理

Without Booster                    With Booster
─────────────────                  ────────────────────────────
Read executor.py                   smart_read executor.py + task
→ 1,881 lines (~6k tokens)         → 3 matching functions (~200 tokens)

五个层协同工作：

层	功能
符号索引	tree-sitter 解析每个 .py、.ts、.tsx、.js、.jsx 文件，并将函数和类提取到 SQLite
向量嵌入	sentence-transformers 为每个符号生成编码，以进行语义搜索
智能读取	给定文件和任务后，执行逐文件向量搜索，并仅返回匹配符号的行范围
MCP 服务	通过 stdio 暴露四个工具，任何兼容 MCP 的 Agent 都可以调用
平台初始化	一条命令即可为 Claude Code、Cursor、Windsurf 或 Codex 写入正确的配置

---

安装

需要 Python 3.10+。

pip install agent-booster          # symbol index + MCP tools
pip install agent-booster[embed]   # + semantic vector search (recommended)

---

快速开始

第 1 步 — 配置 AI 工具

booster init claude     # Claude Code
booster init cursor     # Cursor
booster init windsurf   # Windsurf
booster init codex      # OpenAI Codex CLI
booster init all        # all four

每条命令都会准确显示将要更改的文件，征求确认后再写入。可完全撤销：

booster remove claude   # or cursor, windsurf, codex, all

示例 — 配置 OpenAI Codex（booster init codex → booster start → booster gain）：

每个项目只需运行一次，而非每个会话运行一次。 Hook 位于项目根目录的 .claude/settings.json 和 .mcp.json 中。 在此目录中打开的每个 Claude Code 会话——无论在哪个终端窗口，只要在同一台机器上——都会自动加载这些配置。 无需为每个会话单独设置。

第 2 步 — 为代码库建立索引

在项目根目录运行一次。进行大规模重构后重新运行。

booster index && booster embed
# Indexed 260 files, 1800 symbols.
# Built embeddings for 1800 symbols.

索引存储在 .booster/ 中（已加入 gitignore）。所有会话共享同一索引。

第 3 步 — 重启 AI 工具

现在，每个会话都可以使用 agent-booster MCP 服务。Claude Code（及其他工具）会自动对已建立索引的文件使用 smart_read 和 search_context。

第 4 步 — 跟踪节省情况

booster gain

---

CLI 参考

booster init <platform>

为目标平台写入 MCP 服务配置和规则文件。进行任何更改前都会征求确认。

booster init claude     # .mcp.json + CLAUDE.md + .claude/settings.json hook
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        # all four

booster init claude --yes   # skip confirmation (CI/scripts)

booster remove <platform>

彻底撤销 init 写入的所有内容，不留残余。

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。

booster index
# Indexed 260 files, 1800 symbols.

booster embed

为所有已索引的符号构建 sentence-transformer 向量嵌入。语义 search_context 调用需要此步骤。使用 all-MiniLM-L6-v2（在本地运行，不会有数据离开你的机器）。

booster embed
# Built embeddings for 1800 symbols.

booster search "<query>"

在所有已索引的符号中进行关键词搜索。返回文件路径、行号、类型、名称和签名。

booster search "guard install"
# apps/web/src/app/settings/modules/page.tsx:99  function handleInstall  function handleInstall() {

booster route "<task>"

根据任务复杂度推荐 haiku、sonnet 或 opus，评估依据包括关键词信号、文件数量和符号数量。

booster route "fix the guard SSE role check"
# haiku  (narrow task — 0 symbol(s) in 1 file)

booster route "refactor the entire runtime compiler and DSL layer"
# opus  (matches complexity keywords)

booster serve

通过 stdio 启动 MCP 服务。通过 booster init 完成配置后，Claude Code、Cursor、Windsurf 和 Codex 会自动调用此命令。通常无需直接运行。

booster gain

显示过去调用 smart_read 的令牌节省情况，包括读取总数、已提供与已节省的令牌数、节省率，以及节省最多的文件。

Agent Booster — Token Savings Report
─────────────────────────────────────
Active days:        3
Total reads:        47
Tokens served:      12,400
Tokens saved:       89,200
Savings rate:       88%

Top files by savings:
  executor.py              18,400 tokens saved  (12 reads)
  guard.py                 14,200 tokens saved  (8 reads)

---

MCP 工具

booster serve 运行后，Agent 即可使用以下四个工具：

get_symbols(file)

返回文件中所有已索引的符号，包括名称、类型、行范围和签名。无需读取文件。

Input:  { "file": "apps/api/app/runtime/executor.py" }
Output: function run_workflow (lines 42-89): def run_workflow(...)
        class WorkflowState (lines 91-140): class WorkflowState:

search_context(task)

在整个索引中进行语义向量搜索。按余弦相似度返回排名前 10 的匹配结果。如果尚未构建嵌入，则回退到关键词搜索。

Input:  { "task": "guard install uninstall" }
Output: apps/web/src/app/settings/modules/page.tsx:99 function handleInstall — function handleInstall() {
        apps/web/src/components/guard/GuardNav.tsx:13 function GuardNav — function GuardNav() {
        ...

smart_read(file, task)

在单个文件中运行向量搜索，仅返回匹配符号的源代码行，并在标题中显示名称和行范围。如果没有匹配的符号，则会返回明确提示，让模型知道应回退到完整的 Read，而不是悄无声息地接收整个文件。

Input:  { "file": "apps/api/app/runtime/executor.py", "task": "execute output block" }
Output: # function _execute_output (lines 1165-1210)
        def _execute_output(block, state, credentials, ...):
            ...

route_model(task, files?)

根据任务复杂度信号，推荐使用 haiku、sonnet 或 opus。如果省略 files，则会通过 search_context 自动检测。

Input:  { "task": "fix the login redirect bug" }
Output: { "model": "haiku", "reason": "narrow task — 1 symbol in 1 file" }

---

booster init claude 会写入哪些内容

文件	更改
.mcp.json	将 agent-booster 添加到 mcpServers
CLAUDE.md	追加 Booster 使用规则块（哨兵标记）
.claude/settings.json	配置 PreToolUse（Read + Grep）和 UserPromptSubmit 钩子
.claude/hooks/booster-gate.py	阻止对已索引文件执行 Read — 强制使用 smart_read
.claude/hooks/booster-grep-nudge.py	提示将语义 Grep 模式改用 search_context
.claude/hooks/booster-route.py	自动调用 route_model — 在每次用户轮次中推荐使用 haiku/sonnet/opus

booster remove claude 会彻底移除这六个文件，不留任何残余。

---

适用场景

Agent Booster 是三层 Token 缩减方案中的第三层：

Layer 3 — Agent Booster     AST+semantic routing, smart file reads
Layer 2 — RTK               Token compression on CLI/git/build output
Layer 1 — Prompt caching    Stable context reuse (native to 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，因为符号索引已加入 Git 忽略规则。

可以彻底撤销吗？ 可以。booster remove claude 会移除全部六个文件并清理设置条目，不留任何残余。

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "agent-booster": {
      "command": "booster",
      "args": ["serve"]
    }
  }
}

启动 Claude Desktop 前，先在项目根目录中运行一次 booster index && booster embed。无需设置环境变量。

---

项目布局

tools/booster/
├── README.md
├── pyproject.toml
└── booster/
    ├── cli.py          # click commands: index, embed, search, serve, init, remove, route, gain
    ├── indexer.py      # tree-sitter parser + SQLite symbol store + vector search
    ├── retriever.py    # smart_read: per-file vector search → relevant line slice
    ├── mcp_server.py   # MCP server: get_symbols, search_context, smart_read, route_model
    └── stats.py        # token savings tracking (booster gain)