wonder/cs-note

Fork 0

Files

T

wonder e92c0327d9 vault backup: 2026-06-09 23:15:17

2026-06-09 23:15:17 +08:00

15 KiB

Raw Permalink Blame History

tags, create time

ToolSearch 设计指南

概述

基于 feature/tool_search 分支的 4 次 commit 迭代，系统性地记录 ToolSearch 的架构、核心机制、演进历史和维护指南。ToolSearch 采用延迟加载模式，将 60+ 工具分为 Core Tools（始终加载）和 Deferred Tools（按需发现），通过 TF-IDF + 关键词混合搜索解决 token 爆炸、prompt cache 失效和模型注意力稀释三大问题。

正文

1. 问题背景

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

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

2. 解决方案概览

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

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

3. 核心架构

3.1 工具分类体系

flowchart LR
    subgraph ALL["All Tools (60+ built-in + MCP)"]
        direction TB
        CORE["Core Tools (29 个)\n始终加载，直接调用\nCORE_TOOLS 白名单定义"]
        DEFER["Deferred Tools (其余全部)\n不加载 schema，按需发现\nisDeferredTool() 判定"]
    end

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 三层组件架构

flowchart TB
    subgraph API["API Layer (src/services/api/claude.ts)"]
        A1["判定是否启用 ToolSearch"]
        A2["过滤 deferred tools 不进入 API tools 数组"]
        A3["注入 available-deferred-tools 或 delta 附件"]
        A4["处理 tool_reference/text 格式的消息归一化"]
    end
    subgraph QUERY["Query Loop (src/query.ts)"]
        Q1["Turn-zero 预取：用户输入时触发"]
        Q2["Inter-turn 预取：assistant turn 后异步触发"]
    end
    subgraph SEARCH["Search Engine"]
        S1["SearchExtraToolsTool — 搜索入口（4 种查询模式）"]
        S2["TF-IDF Index (toolIndex.ts) — 语义搜索"]
        S3["Keyword Search — 精确匹配"]
        S4["ExecuteExtraTool — 代理执行"]
    end
    API --> QUERY --> SEARCH

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 执行管道

flowchart TD
    A["模型调用 ExecuteExtraTool"] --> B["在全局工具注册表中查找目标工具"]
    B --> C{"检查 isEnabled()"}
    C -->|不可用| ERR["返回错误"]
    C -->|可用| D["委托目标工具的 checkPermissions()"]
    D --> E["调用目标工具的 call()"]
    E --> F["返回结果（包装为 ExecuteExtraTool 的 output schema）"]

    style A fill:#eef,stroke:#66c
    style F fill:#efe,stroke:#6a6

关键设计：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 代理调用

[!info] prompt cache 是 Claude Code 性能优化的关键。每次 tools JSON 变化都会导致缓存失效，代价远大于通过 ExecuteExtraTool 代理调用 deferred tools 的额外 token。

4. 预取机制（Prefetch）

4.1 两个触发时机

Turn-zero（getTurnZeroSearchExtraToolsPrefetch）— 用户输入第一轮时，基于输入文本搜索相关 deferred tools，以 attachment 形式注入
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 组件

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 行

Tip

v2 的核心洞察：依赖 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 时返回明确拒绝

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

7 个文件，+36/-18 行

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

Tip

不是所有用户都需要团队功能。将其延迟化后，大部分用户可以节省约 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 修改注意事项

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

9.3 性能优化配置

# 环境变量调优
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 — 从对话历史中提取搜索查询文本

关联笔记

feature-flags - 构建时 Feature Flags（含工具搜索相关 flags）
growthbook-ab-testing - GrowthBook A/B 测试（tengu_glacier_2xr 控制搜索行为）
hidden-features - 未公开功能深度解析

15 KiB Raw Permalink Blame History Unescape Escape