feat: 实现 Tool Search 基础设施层(CORE_TOOLS 白名单 + TF-IDF 索引 + ExecuteTool + 搜索增强)

- 新增 CORE_TOOLS 白名单常量(31 个核心工具),重构 isDeferredTool 为白名单制判定
- 新建 TF-IDF 工具索引模块(toolIndex.ts),复用 localSearch.ts 算法函数
- 新建 ExecuteTool 跨 API provider 统一工具执行入口
- 增强 ToolSearchTool:TF-IDF 搜索路径、discover: 模式、并行搜索合并、文本模式回退
- 新增 27 个单元测试,precheck 零错误通过(4108 tests pass)

Co-Authored-By: glm-5.1[1m] <zai-org@claude-code-best.win>
This commit is contained in:
claude-code-best
2026-05-08 22:29:15 +08:00
parent 02dd796706
commit 7be08f53bd
34 changed files with 4040 additions and 90 deletions

View File

@@ -1,24 +1,6 @@
import { feature } from 'bun:bundle'
import { isReplBridgeActive } from 'src/bootstrap/state.js'
import { getFeatureValue_CACHED_MAY_BE_STALE } from 'src/services/analytics/growthbook.js'
import type { Tool } from 'src/Tool.js'
import { AGENT_TOOL_NAME } from '../AgentTool/constants.js'
// Dead code elimination: Brief tool name only needed when KAIROS or KAIROS_BRIEF is on
/* eslint-disable @typescript-eslint/no-require-imports */
const BRIEF_TOOL_NAME: string | null =
feature('KAIROS') || feature('KAIROS_BRIEF')
? (
require('../BriefTool/prompt.js') as typeof import('../BriefTool/prompt.js')
).BRIEF_TOOL_NAME
: null
const SEND_USER_FILE_TOOL_NAME: string | null = feature('KAIROS')
? (
require('../SendUserFileTool/prompt.js') as typeof import('../SendUserFileTool/prompt.js')
).SEND_USER_FILE_TOOL_NAME
: null
/* eslint-enable @typescript-eslint/no-require-imports */
import { CORE_TOOLS } from 'src/constants/tools.js'
export { TOOL_SEARCH_TOOL_NAME } from './constants.js'
@@ -47,64 +29,26 @@ Result format: each matched tool appears as one <function>{"description": "...",
Query forms:
- "select:Read,Edit,Grep" — fetch these exact tools by name
- "discover:schedule cron job" — pure discovery, returns tool info (name, description, schema) without loading. Use when you want to understand available tools before deciding which to invoke.
- "notebook jupyter" — keyword search, up to max_results best matches
- "+slack send" — require "slack" in the name, rank by remaining terms`
/**
* Check if a tool should be deferred (requires ToolSearch to load).
* A tool is deferred if:
* - It's an MCP tool (always deferred - workflow-specific)
* - It has shouldDefer: true
*
* A tool is NEVER deferred if it has alwaysLoad: true (MCP tools set this via
* _meta['anthropic/alwaysLoad']). This check runs first, before any other rule.
* A tool is deferred if it is NOT in CORE_TOOLS and does NOT have alwaysLoad: true.
* Core tools are always loaded — never deferred.
* All other tools (non-core built-in + all MCP tools) are deferred
* and must be discovered via ToolSearchTool / ExecuteTool.
*/
export function isDeferredTool(tool: Tool): boolean {
// Explicit opt-out via _meta['anthropic/alwaysLoad'] — tool appears in the
// initial prompt with full schema. Checked first so MCP tools can opt out.
// Explicit opt-out via _meta['anthropic/alwaysLoad']
if (tool.alwaysLoad === true) return false
// MCP tools are always deferred (workflow-specific)
if (tool.isMcp === true) return true
// Core tools are always loaded — never deferred
if (CORE_TOOLS.has(tool.name)) return false
// Never defer ToolSearch itself — the model needs it to load everything else
if (tool.name === TOOL_SEARCH_TOOL_NAME) return false
// Fork-first experiment: Agent must be available turn 1, not behind ToolSearch.
// Lazy require: static import of forkSubagent → coordinatorMode creates a cycle
// through constants/tools.ts at module init.
if (feature('FORK_SUBAGENT') && tool.name === AGENT_TOOL_NAME) {
type ForkMod = typeof import('../AgentTool/forkSubagent.js')
// eslint-disable-next-line @typescript-eslint/no-require-imports
const m = require('../AgentTool/forkSubagent.js') as ForkMod
if (m.isForkSubagentEnabled()) return false
}
// Brief is the primary communication channel whenever the tool is present.
// Its prompt contains the text-visibility contract, which the model must
// see without a ToolSearch round-trip. No runtime gate needed here: this
// tool's isEnabled() IS isBriefEnabled(), so being asked about its deferral
// status implies the gate already passed.
if (
(feature('KAIROS') || feature('KAIROS_BRIEF')) &&
BRIEF_TOOL_NAME &&
tool.name === BRIEF_TOOL_NAME
) {
return false
}
// SendUserFile is a file-delivery communication channel (sibling of Brief).
// Must be immediately available without a ToolSearch round-trip.
if (
feature('KAIROS') &&
SEND_USER_FILE_TOOL_NAME &&
tool.name === SEND_USER_FILE_TOOL_NAME &&
isReplBridgeActive()
) {
return false
}
return tool.shouldDefer === true
// Everything else (non-core built-in + all MCP tools) is deferred
return true
}
/**