claude-code/docs/design/tool-search-design-guide.md

# ToolSearch 设计指南

> 基于 feature/tool_search 分支的 4 次 commit 迭代，系统性地记录 ToolSearch 的架构、核心机制、演进历史和维护指南。

## 1. 问题背景

Claude Code 内置了 60+ 工具，加上用户连接的 MCP 服务器可能引入数十甚至上百个额外工具。将所有工具的完整 schema 一次性发送给模型，会产生几个严重问题：

1. **Token 爆炸** — 每个工具定义（name + description + inputSchema）平均消耗数百 token，60 个工具就是数万 token 的常量开销。
2. **Prompt Cache 失效** — 工具列表作为 prompt 的一部分参与缓存计算。任何工具的增减（如 MCP 服务器连接/断开）都会导致整段缓存失效。
3. **模型注意力稀释** — 过多的工具定义干扰模型对核心工具的选择准确性。

## 2. 解决方案概览

ToolSearch 采用 **延迟加载（Deferred Loading）** 模式：

- 将工具分为 **Core Tools**（始终加载）和 **Deferred Tools**（按需发现）
- 模型通过 `SearchExtraTools` 工具搜索并发现 deferred tools
- 通过 `ExecuteExtraTool` 工具代理执行发现的 deferred tools
- **工具数组在会话中保持稳定**，不再动态注入已发现的 deferred tools（v3 修复的关键决策）

## 3. 核心架构

### 3.1 工具分类体系

```
┌─────────────────────────────────────────────────────────────┐
│                     All Tools (60+ built-in + MCP)          │
├───────────────────────────┬─────────────────────────────────┤
│    Core Tools (29 个)     │     Deferred Tools (其余全部)    │
│    始终加载，直接调用      │     不加载 schema，按需发现      │
│    CORE_TOOLS 白名单定义   │     isDeferredTool() 判定       │
└───────────────────────────┴─────────────────────────────────┘
```

**Core Tools**（`src/constants/tools.ts` 中的 `CORE_TOOLS` Set）：

| 类别 | 工具 |
|------|------|
| 文件操作 | Bash/Shell, Read, Edit, Write, Glob, Grep, NotebookEdit |
| Agent 交互 | Agent, AskUserQuestion |
| 任务管理 | TaskOutput, TaskStop, TaskCreate, TaskGet, TaskList, TaskUpdate, TodoWrite |
| 规划 | EnterPlanMode, ExitPlanMode, VerifyPlanExecution |
| Web | WebFetch, WebSearch |
| 代码智能 | LSP |
| 技能 | Skill |
| 调度/监控 | Sleep |
| 工具发现 | SearchExtraTools, ExecuteExtraTool, SyntheticOutput |

**isDeferredTool 判定逻辑**（`packages/builtin-tools/src/tools/SearchExtraToolsTool/prompt.ts`）：

```
isDeferredTool(tool) =
  tool.alwaysLoad === true?  → false（显式跳过延迟）
  CORE_TOOLS.has(tool.name)? → false（核心工具不延迟）
  otherwise                  → true（其余全部延迟）
```

### 3.2 三层组件架构

```
┌──────────────────────────────────────────────────────┐
│  API Layer (src/services/api/claude.ts)              │
│  ├─ 判定是否启用 ToolSearch                          │
│  ├─ 过滤 deferred tools 不进入 API tools 数组         │
│  ├─ 注入 <available-deferred-tools> 或 delta 附件    │
│  └─ 处理 tool_reference/text 格式的消息归一化         │
├──────────────────────────────────────────────────────┤
│  Query Loop (src/query.ts)                           │
│  ├─ Turn-zero 预取：用户输入时触发                    │
│  └─ Inter-turn 预取：assistant turn 后异步触发        │
├──────────────────────────────────────────────────────┤
│  Search Engine                                       │
│  ├─ SearchExtraToolsTool — 搜索入口（4 种查询模式）  │
│  ├─ TF-IDF Index (toolIndex.ts) — 语义搜索          │
│  ├─ Keyword Search — 精确匹配                       │
│  └─ ExecuteExtraTool — 代理执行                      │
└──────────────────────────────────────────────────────┘
```

### 3.3 搜索引擎设计

SearchExtraToolsTool 支持四种查询模式：

| 模式 | 语法 | 行为 | 返回 |
|------|------|------|------|
| **Select** | `select:CronCreate,Snip` | 按名称直接获取，逗号分隔多选 | 精确匹配列表 |
| **Discover** | `discover:schedule cron job` | 纯发现模式，返回描述+schema | 工具信息文本 |
| **Keyword** | `notebook jupyter` | 关键词搜索 | 按相关性排序 |
| **Required** | `+slack send` | `+` 前缀强制包含 | 包含必选词的结果 |

**混合搜索算法**：

```
最终分数 = 关键词分数 × 0.4 + TF-IDF 分数 × 0.6
```

- **Keyword Search**：基于工具名解析（CamelCase 分词、MCP 前缀拆解）、searchHint 匹配、描述文本匹配，加权计分
- **TF-IDF Search**：复用 `skillSearch/localSearch.ts` 的算法，对 name (3.0)、searchHint (2.5)、description (1.0) 三个字段加权计算 TF-IDF 向量

**MCP 工具名解析**：

```
mcp__slack__send_message → parts: ["slack", "send", "message"]
CamelCase → parts: ["cron", "create"]
```

### 3.4 执行管道

```
模型调用 ExecuteExtraTool({tool_name: "CronCreate", params: {...}})
  ↓
ExecuteTool.call() 在全局工具注册表中查找 CronCreate
  ↓
检查目标工具 isEnabled() — 桥接/条件工具可能不可用
  ↓
委托目标工具的 checkPermissions() — 权限传递给实际工具
  ↓
调用目标工具的 call() — 与直接调用完全等价
  ↓
返回结果（包装为 ExecuteExtraTool 的 output schema）
```

关键设计：ExecuteExtraTool 的 `checkPermissions()` 返回 `passthrough`，将权限决策完全委托给目标工具。它本身不引入额外的权限层。

### 3.5 Prompt Cache 稳定性策略（v3 关键修复）

**问题**：早期版本在发现 deferred tool 后会将其注入 API tools 数组，导致每次发现新工具时 tools JSON 变化，prompt cache 全面失效。

**修复**（commit `c14b7ead`）：deferred tools **始终不进入 API tools 数组**。tools 数组在整个会话中只包含 core tools + SearchExtraTools + ExecuteExtraTool，保持稳定。

```
API Tools 数组（会话期间不变）:
  [Core Tools (29)] + [SearchExtraTools, ExecuteExtraTool, SyntheticOutput]
  
  不包含: 任何 deferred tool（即使已被发现）
  执行方式: 通过 ExecuteExtraTool 代理调用
```

## 4. 预取机制（Prefetch）

### 4.1 两个触发时机

1. **Turn-zero**（`getTurnZeroSearchExtraToolsPrefetch`）— 用户输入第一轮时，基于输入文本搜索相关 deferred tools，以 attachment 形式注入
2. **Inter-turn**（`startSearchExtraToolsPrefetch`）— assistant turn 结束后，基于对话上下文异步搜索

### 4.2 Attachment 管道

```
prefetch → Attachment(type: 'tool_discovery')
  → messages.ts 转换为 system-reminder
  → "The following tools were discovered... Use ExecuteExtraTool to invoke..."
```

### 4.3 会话去重

`discoveredToolsThisSession` Set 跟踪已发现的工具，避免重复推荐。该 Set 独立于 skill prefetch 的去重集合，互不影响。使用 `addBoundedSessionEntry()` 保持上限 500 条，超出时裁剪到 400 条。

## 5. 模式切换系统

通过环境变量 `ENABLE_SEARCH_EXTRA_TOOLS` 控制：

| 环境变量值 | 模式 | 行为 |
|-----------|------|------|
| 未设置 | `tst` | 默认启用，始终延迟非核心工具 |
| `true` | `tst` | 强制启用 |
| `false` | `standard` | 完全禁用，所有工具内联加载 |
| `auto` | `tst-auto` | 仅当 deferred tools 超过上下文窗口 10% 时启用 |
| `auto:N` | `tst-auto` | 自定义阈值百分比（N=0 启用，N=100 禁用） |
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` | `standard` | 全局 kill switch |

`isSearchExtraToolsEnabledOptimistic()` — 快速判断（不检查阈值），用于工具注册
`isSearchExtraToolsEnabled()` — 完整判断（含阈值检查），用于 API 调用

## 6. Deferred Tools Delta 机制

对于 Anthropic 内部用户（`USER_TYPE=ant`）或启用了 `tengu_glacier_2xr` feature flag 的用户，使用 **delta attachment** 替代 `<available-deferred-tools>` 头部注入：

- 首次：注入完整的 deferred tools 列表
- 后续：只注入增量变化（新增/移除）
- 优势：不会因为工具池变化导致整个头部缓存失效

Delta attachment 扫描历史消息中的 `deferred_tools_delta` 类型 attachment，重建已宣告集合，然后差分计算当前 deferred pool 的变化。

## 7. 演进历史

### v1: 基础设施层（`7be08f53`）

**34 个文件，+4040/-90 行**

- 定义 `CORE_TOOLS` 白名单（31 个核心工具）
- 实现 TF-IDF 工具索引模块 `toolIndex.ts`
- 创建 `ExecuteTool` 作为统一执行入口
- 增强 ToolSearchTool：TF-IDF 搜索路径、discover 模式、并行搜索合并
- 新增 27 个单元测试
- 实现预取管道和 UI 组件

**关键文件**：
- `src/services/toolSearch/toolIndex.ts` → 后续重命名为 `searchExtraTools/toolIndex.ts`
- `packages/builtin-tools/src/tools/ExecuteTool/` — 执行入口
- `src/constants/tools.ts` — CORE_TOOLS 定义

### v2: 统一自建搜索（`8c157f07`）

**17 个文件，+274/-395 行**（净减少 121 行）

- **移除 `tool_reference` blocks** — 不再依赖 Anthropic API 的 `tool_reference` 功能
- **移除 `defer_loading` 字段** — 不再发送 API 级别的工具延迟加载标记
- **移除 `modelSupportsToolReference()`** — 不再区分模型是否支持 tool_reference
- **重命名 ExecuteTool → ExecuteExtraTool** — 更清晰地表达其作为代理执行器的角色
- **输出改为纯文本** — 所有 provider 通用，无需特殊 API 功能支持
- **简化 system prompt** — 工具使用指南从 ~120 行压缩到 ~10 行

**设计决策**：这次重构的核心洞察是 — 依赖 Anthropic 私有 API 特性（tool_reference、defer_loading、beta header）使得系统只能用于 first-party provider。自建 TF-IDF + keyword 搜索完全能满足需求，且对所有 provider（OpenAI、Gemini、Grok）通用。

### v3: Cache 稳定性修复（`c14b7ead`）

**7 个文件，+46/-31 行**

- **移除 "discover then include" 逻辑** — 发现的 deferred tools 不再注入 tools 数组
- **tools 数组保持稳定** — 只有 core tools + SearchExtraTools + ExecuteExtraTool
- **强化优先级引导** — core tools 直接调用，ToolSearch 仅作为发现 deferred tools 的手段
- **已加载工具拒绝提示** — 搜索 core tool 时返回明确拒绝

**设计决策**：prompt cache 是 Claude Code 性能优化的关键。每次 tools JSON 变化都会导致缓存失效，代价远大于通过 ExecuteExtraTool 代理调用 deferred tools 的额外 token。因此选择牺牲一点直接调用的便利性，换取 cache 稳定性。

### v4: Agents/Teams 延迟化（`af0d7dc8`）

**7 个文件，+36/-18 行**

- 将 `TeamCreate`、`TeamDelete`、`SendMessage` 从 CORE_TOOLS 移除
- 这些工具仅在 swarm 模式下常用，平时占用 context token
- swarm 模式下 SendMessage 保持 always loaded
- TeamCreate/TeamDelete 在 swarm 未启用时返回启用提示

**设计决策**：不是所有用户都需要团队功能。将其延迟化后，大部分用户可以节省约 3 个工具定义的 token 开销。

## 8. 文件索引

### 核心文件

| 文件 | 职责 |
|------|------|
| `src/constants/tools.ts` | CORE_TOOLS 白名单、工具权限集合 |
| `src/utils/searchExtraTools.ts` | 模式判定、阈值计算、delta 差分、discovered tools 提取 |
| `src/services/searchExtraTools/toolIndex.ts` | TF-IDF 索引构建和搜索 |
| `src/services/searchExtraTools/prefetch.ts` | 预取管道（turn-zero + inter-turn） |
| `packages/builtin-tools/src/tools/SearchExtraToolsTool/` | 搜索工具实现（4 种查询模式） |
| `packages/builtin-tools/src/tools/ExecuteTool/` | 代理执行器实现 |
| `src/services/api/claude.ts` | API 层集成（工具过滤、消息归一化） |
| `src/query.ts` | 查询循环集成（预取触发点） |
| `src/utils/messages.ts` | Attachment → system-reminder 转换 |

### 共享基础设施

| 文件 | 被复用的导出 |
|------|-------------|
| `src/services/skillSearch/localSearch.ts` | `tokenizeAndStem`, `computeWeightedTf`, `computeIdf`, `cosineSimilarity` |
| `src/services/skillSearch/prefetch.ts` | `extractQueryFromMessages` |

### 测试文件

| 文件 | 覆盖范围 |
|------|---------|
| `src/services/searchExtraTools/__tests__/toolIndex.test.ts` | 索引构建、TF-IDF 搜索、CJK 处理 |
| `src/services/searchExtraTools/__tests__/prefetch.test.ts` | 预取管道、去重、attachment 生成 |
| `packages/builtin-tools/src/tools/SearchExtraToolsTool/__tests__/` | 搜索工具 4 种模式 |
| `packages/builtin-tools/src/tools/ExecuteTool/__tests__/` | 代理执行 |

## 9. 维护指南

### 9.1 新增工具的延迟化决策

将新工具加入 deferred 状态的标准：
- 工具仅在特定场景使用（如 swarm 模式、特定 MCP 集成）
- 工具的 schema 较大（占用较多 context token）
- 工具不是模型默认会尝试的核心操作

将已延迟的工具提升为 core tool：
- 在 `src/constants/tools.ts` 的 `CORE_TOOLS` Set 中添加工具名常量
- 确保导入对应的 `*_TOOL_NAME` 常量

### 9.2 修改注意事项

1. **修改 `localSearch.ts` 的 TF-IDF 函数**：需同步检查 `toolIndex.test.ts` 和 `localSearch.test.ts`
2. **修改 `skillSearch/prefetch.ts` 的 `extractQueryFromMessages`**：需同步检查工具预取行为（`searchExtraTools/prefetch.ts` 调用同一函数）
3. **修改 CORE_TOOLS**：需更新 `src/constants/__tests__/tools.test.ts` 测试
4. **修改 `isDeferredTool`**：需更新 `src/constants/__tests__/tools.test.ts` 和 `SearchExtraToolsTool.test.ts`

### 9.3 性能优化配置

```bash
# 环境变量调优
ENABLE_SEARCH_EXTRA_TOOLS=auto:15    # 当 deferred tools 超过上下文 15% 时启用
SEARCH_EXTRA_TOOLS_WEIGHT_KEYWORD=0.5  # 关键词搜索权重
SEARCH_EXTRA_TOOLS_WEIGHT_TFIDF=0.5    # TF-IDF 搜索权重
SEARCH_EXTRA_TOOLS_DISPLAY_MIN_SCORE=0.10  # 最低显示分数阈值
```

### 9.4 搜索质量调优

- `TOOL_FIELD_WEIGHT`（`toolIndex.ts`）：控制 name/searchHint/description 对 TF-IDF 分数的贡献权重
- `KEYWORD_WEIGHT` / `TFIDF_WEIGHT`（`SearchExtraToolsTool.ts`）：控制混合搜索中两种算法的最终权重比例
- `searchHint` 属性：为工具添加精心编写的搜索提示，提高关键词匹配质量

## 10. 与 Skill Search 的关系

ToolSearch 和 SkillSearch 是平行的搜索系统，共享底层算法但服务于不同领域：

| 维度 | ToolSearch | SkillSearch |
|------|-----------|-------------|
| 搜索对象 | Deferred 工具（内置 + MCP） | 用户技能（skill） |
| 执行方式 | `ExecuteExtraTool` 代理调用 | 直接注入 attachment 内容 |
| 字段权重 | name:3.0, searchHint:2.5, desc:1.0 | name:3.0, whenToUse:2.0, desc:1.0 |
| 缓存策略 | 按工具名列表缓存 | 按 cwd 缓存 |
| 去重集合 | `discoveredToolsThisSession` | 独立的 Set |

共享的底层函数：
- `tokenizeAndStem` — 统一的 CJK/ASCII 分词和词干提取
- `computeWeightedTf` — 加权词频计算
- `computeIdf` — 逆文档频率计算
- `cosineSimilarity` — 向量余弦相似度
- `extractQueryFromMessages` — 从对话历史中提取搜索查询文本