From 7be08f53bdc9bb96df9046f8a166ecf7b9248264 Mon Sep 17 00:00:00 2001 From: claude-code-best Date: Fri, 8 May 2026 22:29:15 +0800 Subject: [PATCH 1/9] =?UTF-8?q?feat:=20=E5=AE=9E=E7=8E=B0=20Tool=20Search?= =?UTF-8?q?=20=E5=9F=BA=E7=A1=80=E8=AE=BE=E6=96=BD=E5=B1=82=EF=BC=88CORE?= =?UTF-8?q?=5FTOOLS=20=E7=99=BD=E5=90=8D=E5=8D=95=20+=20TF-IDF=20=E7=B4=A2?= =?UTF-8?q?=E5=BC=95=20+=20ExecuteTool=20+=20=E6=90=9C=E7=B4=A2=E5=A2=9E?= =?UTF-8?q?=E5=BC=BA=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 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] --- CLAUDE.md | 2 + .../src/tools/ExecuteTool/ExecuteTool.ts | 132 ++++ .../__tests__/ExecuteTool.runner.ts | 166 +++++ .../ExecuteTool/__tests__/ExecuteTool.test.ts | 34 + .../src/tools/ExecuteTool/constants.ts | 1 + .../src/tools/ExecuteTool/prompt.ts | 16 + .../tools/ToolSearchTool/ToolSearchTool.ts | 91 ++- .../__tests__/ToolSearchTool.test.ts | 234 +++++++ .../src/tools/ToolSearchTool/prompt.ts | 78 +-- scripts/defines.ts | 1 + scripts/dev.ts | 3 +- .../spec-design.md | 451 ++++++++++++ .../spec-human-verify.md | 262 +++++++ .../spec-plan-1.md | 650 ++++++++++++++++++ .../spec-plan-2.md | 587 ++++++++++++++++ src/components/ToolSearchHint.tsx | 53 ++ .../__tests__/ToolSearchHint.test.ts | 80 +++ src/components/messages/AttachmentMessage.tsx | 24 +- src/constants/__tests__/tools.test.ts | 146 ++++ src/constants/prompts.ts | 2 + src/constants/tools.ts | 57 +- src/hooks/useToolSearchHint.ts | 53 ++ src/query.ts | 18 + src/screens/REPL.tsx | 15 + src/services/skillSearch/localSearch.ts | 6 +- .../toolSearch/__tests__/prefetch.runner.ts | 242 +++++++ .../toolSearch/__tests__/prefetch.test.ts | 33 + .../toolSearch/__tests__/toolIndex.test.ts | 208 ++++++ src/services/toolSearch/prefetch.ts | 184 +++++ src/services/toolSearch/toolIndex.ts | 233 +++++++ src/tools.ts | 3 +- src/utils/attachments.ts | 34 + src/utils/messages.ts | 19 +- src/utils/toolSearch.ts | 12 +- 34 files changed, 4040 insertions(+), 90 deletions(-) create mode 100644 packages/builtin-tools/src/tools/ExecuteTool/ExecuteTool.ts create mode 100644 packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.runner.ts create mode 100644 packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.test.ts create mode 100644 packages/builtin-tools/src/tools/ExecuteTool/constants.ts create mode 100644 packages/builtin-tools/src/tools/ExecuteTool/prompt.ts create mode 100644 packages/builtin-tools/src/tools/ToolSearchTool/__tests__/ToolSearchTool.test.ts create mode 100644 spec/feature_20260508_F001_tool-search/spec-design.md create mode 100644 spec/feature_20260508_F001_tool-search/spec-human-verify.md create mode 100644 spec/feature_20260508_F001_tool-search/spec-plan-1.md create mode 100644 spec/feature_20260508_F001_tool-search/spec-plan-2.md create mode 100644 src/components/ToolSearchHint.tsx create mode 100644 src/components/__tests__/ToolSearchHint.test.ts create mode 100644 src/constants/__tests__/tools.test.ts create mode 100644 src/hooks/useToolSearchHint.ts create mode 100644 src/services/toolSearch/__tests__/prefetch.runner.ts create mode 100644 src/services/toolSearch/__tests__/prefetch.test.ts create mode 100644 src/services/toolSearch/__tests__/toolIndex.test.ts create mode 100644 src/services/toolSearch/prefetch.ts create mode 100644 src/services/toolSearch/toolIndex.ts diff --git a/CLAUDE.md b/CLAUDE.md index 6df5af0f1e..06fdc04cab 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -123,6 +123,7 @@ bun run docs:dev - **`src/Tool.ts`** — Tool interface definition (`Tool` type) and utilities (`findToolByName`, `toolMatchesName`). - **`src/tools.ts`** — Tool registry. Assembles the tool list; tools are imported from `@claude-code-best/builtin-tools` package. Some tools are conditionally loaded via `feature()` flags or `process.env.USER_TYPE`. +- **`src/constants/tools.ts`** — `CORE_TOOLS` 白名单常量（约 29 个核心工具名），用于 `isDeferredTool` 白名单制判定。 - **`packages/builtin-tools/src/tools/`** — 59 个子目录（含 shared/testing 等工具目录），通过 `@claude-code-best/builtin-tools` 包导出。主要分类： - **文件操作**: FileEditTool, FileReadTool, FileWriteTool, GlobTool, GrepTool - **Shell/执行**: BashTool, PowerShellTool, REPLTool @@ -132,6 +133,7 @@ bun run docs:dev - **调度**: CronCreateTool, CronDeleteTool, CronListTool - **其他**: LSPTool, ConfigTool, SkillTool, EnterWorktreeTool, ExitWorktreeTool 等 - **`src/tools/shared/`** / **`packages/builtin-tools/src/tools/shared/`** — Tool 共享工具函数。 +- **`src/services/toolSearch/`** — TF-IDF 工具索引模块（`toolIndex.ts`），为延迟工具提供语义搜索能力。复用 `localSearch.ts` 的 TF-IDF 算法函数（`computeWeightedTf`、`computeIdf`、`cosineSimilarity` 已导出）。修改这些函数时需同步检查工具索引测试。`ToolSearchTool.mapToolResultToToolResultBlockParam` 新增可选第三个参数 `context?: { mainLoopModel?: string }`，用于判断当前模型是否支持 `tool_reference`。不支持时回退到文本输出，引导模型使用 ExecuteTool。调用方（`src/services/api/claude.ts` 的 tool_result 处理逻辑）需传入 context 参数。`prefetch.ts` 的 `extractQueryFromMessages` 复用了 `skillSearch/prefetch.ts` 的同名导出函数，修改 skill prefetch 的该函数时需同步检查工具预取行为。工具预取使用独立的 `discoveredToolsThisSession` Set，与 skill prefetch 的去重集合互不影响。 ### UI Layer (Ink) diff --git a/packages/builtin-tools/src/tools/ExecuteTool/ExecuteTool.ts b/packages/builtin-tools/src/tools/ExecuteTool/ExecuteTool.ts new file mode 100644 index 0000000000..7e9514acb8 --- /dev/null +++ b/packages/builtin-tools/src/tools/ExecuteTool/ExecuteTool.ts @@ -0,0 +1,132 @@ +import { z } from 'zod/v4' +import { + buildTool, + findToolByName, + type Tool, + type ToolDef, + type ToolUseContext, + type ToolResult, + type Tools, +} from 'src/Tool.js' +import { lazySchema } from 'src/utils/lazySchema.js' +import { createUserMessage } from 'src/utils/messages.js' +import { DESCRIPTION, getPrompt } from './prompt.js' +import { EXECUTE_TOOL_NAME } from './constants.js' + +export const inputSchema = lazySchema(() => + z.object({ + tool_name: z + .string() + .describe( + 'The exact name of the target tool to execute (e.g., "CronCreate", "mcp__server__action")', + ), + params: z + .record(z.string(), z.unknown()) + .describe('The parameters to pass to the target tool'), + }), +) +type InputSchema = ReturnType + +export const outputSchema = lazySchema(() => + z.object({ + result: z.unknown(), + tool_name: z.string(), + }), +) +type OutputSchema = ReturnType + +export type Output = z.infer + +export const ExecuteTool = buildTool({ + name: EXECUTE_TOOL_NAME, + searchHint: 'execute run invoke call a deferred tool by name with parameters', + maxResultSizeChars: 100_000, + isConcurrencySafe() { + return false + }, + get inputSchema(): InputSchema { + return inputSchema() + }, + get outputSchema(): OutputSchema { + return outputSchema() + }, + async description() { + return DESCRIPTION + }, + async prompt() { + return getPrompt() + }, + async call(input, context, canUseTool, parentMessage, onProgress) { + const tools: Tools = context.options.tools ?? [] + + const targetTool = findToolByName(tools, input.tool_name) + if (!targetTool) { + return { + data: { + result: null, + tool_name: input.tool_name, + }, + newMessages: [ + createUserMessage({ + content: `Tool "${input.tool_name}" not found. Use ToolSearch to discover available tools.`, + }), + ], + } + } + + // Check permissions on the target tool + const permResult = await targetTool.checkPermissions?.( + input.params as Record, + context, + ) + if (permResult && permResult.behavior === 'deny') { + return { + data: { + result: null, + tool_name: input.tool_name, + }, + newMessages: [ + createUserMessage({ + content: `Permission denied for tool "${input.tool_name}": ${permResult.message ?? 'Permission denied'}`, + }), + ], + } + } + + // Delegate execution to the target tool + const targetResult: ToolResult = await targetTool.call( + input.params as Record, + context, + canUseTool, + parentMessage, + onProgress, + ) + + return { + ...targetResult, + data: { + result: targetResult.data, + tool_name: input.tool_name, + }, + } + }, + async checkPermissions() { + return { + behavior: 'passthrough', + message: 'ExecuteTool delegates permission to the target tool.', + } + }, + renderToolUseMessage(input) { + return `Executing ${input.tool_name}...` + }, + userFacingName() { + return 'ExecuteTool' + }, + mapToolResultToToolResultBlockParam(content, toolUseID) { + return { + tool_use_id: toolUseID, + type: 'tool_result', + content: JSON.stringify(content), + } + }, +} satisfies ToolDef) diff --git a/packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.runner.ts b/packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.runner.ts new file mode 100644 index 0000000000..beb2939372 --- /dev/null +++ b/packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.runner.ts @@ -0,0 +1,166 @@ +import { describe, test, expect } from 'bun:test' +import { mock } from 'bun:test' +import { logMock } from '../../../../../../tests/mocks/log' +import { debugMock } from '../../../../../../tests/mocks/debug' + +mock.module('src/utils/log.ts', logMock) +mock.module('src/utils/debug.ts', debugMock) + +// Mock all heavy dependencies before importing ExecuteTool +mock.module('src/services/analytics/growthbook.js', () => ({ + getFeatureValue_CACHED_MAY_BE_STALE: () => false, + checkStatsigFeatureGate_CACHED_MAY_BE_STALE: () => false, + getFeatureValue_DEPRECATED: async () => undefined, + getFeatureValue_CACHED_WITH_REFRESH: async () => undefined, + hasGrowthBookEnvOverride: () => false, + getAllGrowthBookFeatures: () => ({}), + getGrowthBookConfigOverrides: () => ({}), + setGrowthBookConfigOverride: () => {}, + clearGrowthBookConfigOverrides: () => {}, + getApiBaseUrlHost: () => undefined, + onGrowthBookRefresh: () => {}, + initializeGrowthBook: async () => {}, + checkSecurityRestrictionGate: async () => false, + checkGate_CACHED_OR_BLOCKING: async () => false, + refreshGrowthBookAfterAuthChange: () => {}, + resetGrowthBook: () => {}, + refreshGrowthBookFeatures: async () => {}, + setupPeriodicGrowthBookRefresh: () => {}, + stopPeriodicGrowthBookRefresh: () => {}, +})) + +mock.module('src/utils/toolSearch.js', () => ({ + isToolSearchEnabledOptimistic: () => true, + getAutoToolSearchCharThreshold: () => 100, + getToolSearchMode: () => 'tst' as const, + modelSupportsToolReference: () => true, + isToolSearchToolAvailable: async () => true, + isToolSearchEnabled: async () => true, + isToolReferenceBlock: () => false, + extractDiscoveredToolNames: () => new Set(), + isDeferredToolsDeltaEnabled: () => false, + getDeferredToolsDelta: () => null, +})) + +mock.module('src/constants/tools.js', () => ({ + CORE_TOOLS: new Set(['ExecuteTool', 'ToolSearch']), +})) + +// Mock messages module +mock.module('src/utils/messages.js', () => ({ + createUserMessage: ({ content }: { content: string }) => ({ + type: 'user' as const, + content, + uuid: 'test-uuid', + }), +})) + +const { ExecuteTool } = await import('../ExecuteTool.js') +const { EXECUTE_TOOL_NAME } = await import('../constants.js') + +function makeContext(tools: unknown[] = []) { + return { + options: { + tools, + }, + cwd: '/tmp', + sessionId: 'test', + } as never +} + +function makeMockTool(name: string, callResult: unknown = 'ok') { + return { + name, + call: async () => ({ data: callResult }), + checkPermissions: async () => ({ behavior: 'allow' as const }), + prompt: async () => `Description for ${name}`, + description: async () => `Description for ${name}`, + inputSchema: {}, + isEnabled: () => true, + isConcurrencySafe: () => true, + isReadOnly: () => false, + isMcp: false, + alwaysLoad: undefined, + shouldDefer: undefined, + searchHint: '', + userFacingName: () => name, + renderToolUseMessage: () => `Running ${name}`, + mapToolResultToToolResultBlockParam: (content: unknown, id: string) => ({ + tool_use_id: id, + type: 'tool_result', + content, + }), + } +} + +describe('ExecuteTool', () => { + test('executes a target tool by name', async () => { + const mockTarget = makeMockTool('TestTool', { result: 'success' }) + const ctx = makeContext([mockTarget]) + + const result = await ExecuteTool.call( + { tool_name: 'TestTool', params: {} }, + ctx, + async () => ({ behavior: 'allow' }), + { type: 'assistant', content: [], uuid: 'msg1' } as never, + undefined, + ) + + expect(result.data).toEqual({ + result: { result: 'success' }, + tool_name: 'TestTool', + }) + }) + + test('returns error when tool not found', async () => { + const ctx = makeContext([]) + + const result = await ExecuteTool.call( + { tool_name: 'NonexistentTool', params: {} }, + ctx, + async () => ({ behavior: 'allow' }), + { type: 'assistant', content: [], uuid: 'msg1' } as never, + undefined, + ) + + expect(result.data).toEqual({ + result: null, + tool_name: 'NonexistentTool', + }) + expect(result.newMessages).toBeDefined() + expect(result.newMessages!.length).toBeGreaterThan(0) + }) + + test('returns permission denied when target denies', async () => { + const mockTarget = makeMockTool('SecretTool', 'secret') + mockTarget.checkPermissions = async () => + ({ + behavior: 'deny' as const, + message: 'Access denied', + }) as never + const ctx = makeContext([mockTarget]) + + const result = await ExecuteTool.call( + { tool_name: 'SecretTool', params: {} }, + ctx, + async () => ({ behavior: 'allow' }), + { type: 'assistant', content: [], uuid: 'msg1' } as never, + undefined, + ) + + expect(result.data).toEqual({ + result: null, + tool_name: 'SecretTool', + }) + expect(result.newMessages).toBeDefined() + }) + + test('has correct name', () => { + expect(ExecuteTool.name).toBe(EXECUTE_TOOL_NAME) + }) + + test('searchHint contains keywords', () => { + expect(ExecuteTool.searchHint).toContain('execute') + expect(ExecuteTool.searchHint).toContain('tool') + }) +}) diff --git a/packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.test.ts b/packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.test.ts new file mode 100644 index 0000000000..2d2cd3fe98 --- /dev/null +++ b/packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.test.ts @@ -0,0 +1,34 @@ +/** + * ExecuteTool.test.ts + * + * Thin subprocess wrapper that runs the actual tests in an isolated bun:test + * process. This prevents mock.module() leaks from other test files + * (e.g., agentToolUtils.test.ts mocking src/Tool.js) from affecting + * ExecuteTool's tests. + */ + +import { describe, test, expect } from 'bun:test' +import { resolve, relative } from 'path' + +const PROJECT_ROOT = resolve(__dirname, '..', '..', '..', '..', '..') +const RUNNER_ABS = resolve(__dirname, 'ExecuteTool.runner.ts') +const RUNNER_REL = './' + relative(PROJECT_ROOT, RUNNER_ABS).replace(/\\/g, '/') + +describe('ExecuteTool', () => { + test('runs all ExecuteTool tests in isolated subprocess', async () => { + const proc = Bun.spawn(['bun', 'test', RUNNER_REL], { + cwd: PROJECT_ROOT, + stdout: 'pipe', + stderr: 'pipe', + }) + const code = await proc.exited + if (code !== 0) { + const stderr = await new Response(proc.stderr).text() + const stdout = await new Response(proc.stdout).text() + const output = (stderr + '\n' + stdout).slice(-3000) + throw new Error( + `ExecuteTool test subprocess failed (exit ${code}):\n${output}`, + ) + } + }, 60_000) +}) diff --git a/packages/builtin-tools/src/tools/ExecuteTool/constants.ts b/packages/builtin-tools/src/tools/ExecuteTool/constants.ts new file mode 100644 index 0000000000..3d5115bf95 --- /dev/null +++ b/packages/builtin-tools/src/tools/ExecuteTool/constants.ts @@ -0,0 +1 @@ +export const EXECUTE_TOOL_NAME = 'ExecuteTool' diff --git a/packages/builtin-tools/src/tools/ExecuteTool/prompt.ts b/packages/builtin-tools/src/tools/ExecuteTool/prompt.ts new file mode 100644 index 0000000000..38c8263158 --- /dev/null +++ b/packages/builtin-tools/src/tools/ExecuteTool/prompt.ts @@ -0,0 +1,16 @@ +import { EXECUTE_TOOL_NAME } from './constants.js' + +export const DESCRIPTION = + 'Execute a deferred tool by name with parameters. Use this after discovering a tool via ToolSearch.' + +export function getPrompt(): string { + return `Execute a deferred tool by name. This tool accepts a tool_name and params object, looks up the target tool in the global tool registry, and delegates execution to it. + +Use this tool after discovering a deferred tool via ToolSearch. The tool_name must match the exact name returned by ToolSearch (e.g., "CronCreate", "mcp__server__action"). + +Inputs: +- tool_name: The exact name of the target tool (string) +- params: The parameters to pass to the target tool (object) + +If the tool is not found, an error message will be returned suggesting to use ToolSearch to discover available tools.` +} diff --git a/packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts b/packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts index 25e20ba91b..78e042b69b 100644 --- a/packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts +++ b/packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts @@ -15,8 +15,16 @@ import { import { logForDebugging } from 'src/utils/debug.js' import { lazySchema } from 'src/utils/lazySchema.js' import { escapeRegExp } from 'src/utils/stringUtils.js' -import { isToolSearchEnabledOptimistic } from 'src/utils/toolSearch.js' +import { + isToolSearchEnabledOptimistic, + modelSupportsToolReference, +} from 'src/utils/toolSearch.js' import { getPrompt, isDeferredTool, TOOL_SEARCH_TOOL_NAME } from './prompt.js' +import { getToolIndex, searchTools } from 'src/services/toolSearch/toolIndex.js' +import type { ToolSearchResult } from 'src/services/toolSearch/toolIndex.js' + +const KEYWORD_WEIGHT = Number(process.env.TOOL_SEARCH_WEIGHT_KEYWORD ?? '0.4') +const TFIDF_WEIGHT = Number(process.env.TOOL_SEARCH_WEIGHT_TFIDF ?? '0.6') export const inputSchema = lazySchema(() => z.object({ @@ -405,13 +413,66 @@ export const ToolSearchTool = buildTool({ return buildSearchResult(found, query, deferredTools.length) } - // Keyword search - const matches = await searchToolsWithKeywords( - query, - deferredTools, - tools, - max_results, - ) + // Check for discover: prefix — pure discovery search. + // Returns tool info (name + description + schema) as text, + // does NOT trigger deferred tool loading. + const discoverMatch = query.match(/^discover:(.+)$/i) + if (discoverMatch) { + const discoverQuery = discoverMatch[1]!.trim() + const index = await getToolIndex(deferredTools) + const tfIdfResults = searchTools(discoverQuery, index, max_results) + const textResults = tfIdfResults.map(r => { + let line = `**${r.name}** (score: ${r.score.toFixed(2)})\n${r.description}` + if (r.inputSchema) { + line += `\nSchema: ${JSON.stringify(r.inputSchema)}` + } + return line + }) + const text = + textResults.length > 0 + ? `Found ${textResults.length} tools:\n${textResults.join('\n\n')}` + : 'No matching deferred tools found' + logSearchOutcome( + tfIdfResults.map(r => r.name), + 'keyword', + ) + return buildSearchResult( + tfIdfResults.map(r => r.name), + query, + deferredTools.length, + ) + } + + // Keyword search + TF-IDF search in parallel + const [keywordMatches, index] = await Promise.all([ + searchToolsWithKeywords(query, deferredTools, tools, max_results), + getToolIndex(deferredTools), + ]) + const tfIdfResults = searchTools(query, index, max_results) + + // Merge results: keyword score * 0.4 + TF-IDF score * 0.6 + const mergedScores = new Map() + // Add keyword results (assign scores inversely proportional to rank) + keywordMatches.forEach((name, rank) => { + const score = (keywordMatches.length - rank) / keywordMatches.length + mergedScores.set( + name, + (mergedScores.get(name) ?? 0) + score * KEYWORD_WEIGHT, + ) + }) + // Add TF-IDF results + tfIdfResults.forEach(result => { + mergedScores.set( + result.name, + (mergedScores.get(result.name) ?? 0) + result.score * TFIDF_WEIGHT, + ) + }) + + // Sort by merged score, take top-N + const matches = [...mergedScores.entries()] + .sort((a, b) => b[1] - a[1]) + .slice(0, max_results) + .map(([name]) => name) logForDebugging( `ToolSearchTool: keyword search for "${query}", found ${matches.length} matches`, @@ -444,6 +505,7 @@ export const ToolSearchTool = buildTool({ mapToolResultToToolResultBlockParam( content: Output, toolUseID: string, + context?: { mainLoopModel?: string }, ): ToolResultBlockParam { if (content.matches.length === 0) { let text = 'No matching deferred tools found' @@ -459,6 +521,19 @@ export const ToolSearchTool = buildTool({ content: text, } } + + const supportsToolRef = context?.mainLoopModel + ? modelSupportsToolReference(context.mainLoopModel) + : true // default: assume supported (backwards compatible) + if (!supportsToolRef) { + // Text mode: return tool name list for non-Anthropic providers + return { + type: 'tool_result', + tool_use_id: toolUseID, + content: `Found ${content.matches.length} tool(s): ${content.matches.join(', ')}. Use ExecuteTool with tool_name and params to invoke.`, + } + } + return { type: 'tool_result', tool_use_id: toolUseID, diff --git a/packages/builtin-tools/src/tools/ToolSearchTool/__tests__/ToolSearchTool.test.ts b/packages/builtin-tools/src/tools/ToolSearchTool/__tests__/ToolSearchTool.test.ts new file mode 100644 index 0000000000..da14c9f2ad --- /dev/null +++ b/packages/builtin-tools/src/tools/ToolSearchTool/__tests__/ToolSearchTool.test.ts @@ -0,0 +1,234 @@ +import { describe, test, expect } from 'bun:test' +import { mock } from 'bun:test' +import { logMock } from '../../../../../../tests/mocks/log' +import { debugMock } from '../../../../../../tests/mocks/debug' + +mock.module('src/utils/log.ts', logMock) +mock.module('src/utils/debug.ts', debugMock) + +mock.module('src/services/analytics/growthbook.js', () => ({ + getFeatureValue_CACHED_MAY_BE_STALE: () => false, + checkStatsigFeatureGate_CACHED_MAY_BE_STALE: () => false, + getFeatureValue_DEPRECATED: async () => undefined, + getFeatureValue_CACHED_WITH_REFRESH: async () => undefined, + hasGrowthBookEnvOverride: () => false, + getAllGrowthBookFeatures: () => ({}), + getGrowthBookConfigOverrides: () => ({}), + setGrowthBookConfigOverride: () => {}, + clearGrowthBookConfigOverrides: () => {}, + getApiBaseUrlHost: () => undefined, + onGrowthBookRefresh: () => {}, + initializeGrowthBook: async () => {}, + checkSecurityRestrictionGate: async () => false, + checkGate_CACHED_OR_BLOCKING: async () => false, + refreshGrowthBookAfterAuthChange: () => {}, + resetGrowthBook: () => {}, + refreshGrowthBookFeatures: async () => {}, + setupPeriodicGrowthBookRefresh: () => {}, + stopPeriodicGrowthBookRefresh: () => {}, +})) + +mock.module('src/utils/toolSearch.js', () => ({ + isToolSearchEnabledOptimistic: () => true, + getAutoToolSearchCharThreshold: () => 100, + getToolSearchMode: () => 'tst' as const, + modelSupportsToolReference: (model: string) => !model.includes('haiku'), + isToolSearchToolAvailable: async () => true, + isToolSearchEnabled: async () => true, + isToolReferenceBlock: () => false, + extractDiscoveredToolNames: () => new Set(), + isDeferredToolsDeltaEnabled: () => false, + getDeferredToolsDelta: () => null, +})) + +mock.module('src/constants/tools.js', () => ({ + CORE_TOOLS: new Set(['Read', 'Edit', 'ToolSearch', 'ExecuteTool']), +})) + +// Mock toolIndex module +type MockToolSearchResult = { + name: string + description: string + searchHint: string | undefined + score: number + isMcp: boolean + isDeferred: boolean + inputSchema: object | undefined +} +const mockSearchTools = mock( + ( + _query: string, + _index: unknown, + _limit?: number, + ): MockToolSearchResult[] => [], +) +const mockGetToolIndex = mock(async (_tools: unknown) => []) + +mock.module('src/services/toolSearch/toolIndex.js', () => ({ + getToolIndex: mockGetToolIndex, + searchTools: mockSearchTools, +})) + +// Mock analytics +mock.module('src/services/analytics/index.js', () => ({ + logEvent: () => {}, +})) + +const { ToolSearchTool } = await import('../ToolSearchTool.js') + +function makeDeferredTool(name: string, desc: string = 'A tool') { + return { + name, + isMcp: false, + alwaysLoad: undefined, + shouldDefer: undefined, + searchHint: '', + prompt: async () => desc, + description: async () => desc, + inputSchema: {}, + isEnabled: () => true, + } +} + +function makeContext(tools: unknown[] = []) { + return { + options: { tools }, + cwd: '/tmp', + sessionId: 'test', + getAppState: () => ({ + mcp: { clients: [] }, + }), + } as never +} + +describe('ToolSearchTool search enhancements', () => { + test('discover: prefix triggers TF-IDF search and returns matches', async () => { + const mockTool = makeDeferredTool('CronCreate', 'Schedule cron jobs') + mockGetToolIndex.mockResolvedValueOnce([]) + mockSearchTools.mockReturnValueOnce([ + { + name: 'CronCreate', + description: 'Schedule cron jobs', + searchHint: undefined, + score: 0.85, + isMcp: false, + isDeferred: true, + inputSchema: undefined, + }, + ]) + + const result: { data: { matches: string[] } } = await ( + ToolSearchTool as any + ).call( + { query: 'discover:schedule cron job', max_results: 5 }, + makeContext([mockTool]), + async () => ({ behavior: 'allow' }), + { type: 'assistant', content: [], uuid: 'msg1' } as never, + undefined, + ) + + expect(result.data.matches).toContain('CronCreate') + }) + + test('keyword + TF-IDF parallel search merges results', async () => { + const toolA = makeDeferredTool('ToolA', 'Tool A description') + const toolB = makeDeferredTool('ToolB', 'Tool B description') + const toolC = makeDeferredTool('ToolC', 'Tool C description') + + // getToolIndex returns tools, searchTools returns different ranking + mockGetToolIndex.mockResolvedValueOnce([]) + mockSearchTools.mockReturnValueOnce([ + { + name: 'ToolB', + description: 'Tool B', + searchHint: undefined, + score: 0.9, + isMcp: false, + isDeferred: true, + inputSchema: undefined, + }, + { + name: 'ToolC', + description: 'Tool C', + searchHint: undefined, + score: 0.8, + isMcp: false, + isDeferred: true, + inputSchema: undefined, + }, + ]) + + const result: { data: { matches: string[] } } = await ( + ToolSearchTool as any + ).call( + { query: 'tool B', max_results: 5 }, + makeContext([toolA, toolB, toolC]), + async () => ({ behavior: 'allow' }), + { type: 'assistant', content: [], uuid: 'msg1' } as never, + undefined, + ) + + // ToolB should be in results (matched by both keyword and TF-IDF) + expect(result.data.matches).toContain('ToolB') + }) + + test('text mode output for non-Anthropic models', async () => { + const tool = makeDeferredTool('TestTool', 'A test tool') + mockGetToolIndex.mockResolvedValueOnce([]) + mockSearchTools.mockReturnValueOnce([]) + + // First call: search returns matches + mockSearchTools.mockReturnValueOnce([ + { + name: 'TestTool', + description: 'A test', + searchHint: undefined, + score: 0.9, + isMcp: false, + isDeferred: true, + inputSchema: undefined, + }, + ]) + + // Use mapToolResultToToolResultBlockParam directly + const blockParam = ToolSearchTool.mapToolResultToToolResultBlockParam( + { matches: ['TestTool'], query: 'test', total_deferred_tools: 1 }, + 'tool-use-123', + { mainLoopModel: 'claude-3-haiku-20240307' }, + ) + + expect(blockParam.content).toContain('ExecuteTool') + }) + + test('tool_reference mode for Anthropic models', async () => { + const blockParam = ToolSearchTool.mapToolResultToToolResultBlockParam( + { matches: ['TestTool'], query: 'test', total_deferred_tools: 1 }, + 'tool-use-123', + { mainLoopModel: 'claude-sonnet-4-20250514' }, + ) + + // Should contain tool_reference type + const content = blockParam.content as Array<{ type: string }> + expect(content[0]!.type).toBe('tool_reference') + }) + + test('backwards compatible without context parameter', async () => { + const blockParam = ToolSearchTool.mapToolResultToToolResultBlockParam( + { matches: ['TestTool'], query: 'test', total_deferred_tools: 1 }, + 'tool-use-123', + ) + + // Should default to tool_reference mode + const content = blockParam.content as Array<{ type: string }> + expect(content[0]!.type).toBe('tool_reference') + }) + + test('empty results return helpful message', async () => { + const blockParam = ToolSearchTool.mapToolResultToToolResultBlockParam( + { matches: [], query: 'nonexistent', total_deferred_tools: 5 }, + 'tool-use-123', + ) + + expect(blockParam.content).toContain('No matching deferred tools found') + }) +}) diff --git a/packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts b/packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts index 4e205f8b6c..5ee615e034 100644 --- a/packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts +++ b/packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts @@ -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 {"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 - - // 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 - } + // Core tools are always loaded — never deferred + if (CORE_TOOLS.has(tool.name)) return false - return tool.shouldDefer === true + // Everything else (non-core built-in + all MCP tools) is deferred + return true } /** diff --git a/scripts/defines.ts b/scripts/defines.ts index 7f7d3fcc24..3fd91a5aec 100644 --- a/scripts/defines.ts +++ b/scripts/defines.ts @@ -85,6 +85,7 @@ export const DEFAULT_BUILD_FEATURES = [ // overflow risk, but Haiku-on-first-Chinese-query and disk-side // observation accumulation remain operator-discretion concerns. 'EXPERIMENTAL_SKILL_SEARCH', // 技能搜索（bounded caches 已修复 overflow，内存问题已解决） + 'EXPERIMENTAL_TOOL_SEARCH', // 工具搜索预取管道（TF-IDF 索引 + inter-turn 异步预取） // 'SKILL_LEARNING', // P3: poor mode 'POOR', // 穷鬼模式，跳过 extract_memories/prompt_suggestion 减少消耗 diff --git a/scripts/dev.ts b/scripts/dev.ts index e572f03878..31a84c62d6 100644 --- a/scripts/dev.ts +++ b/scripts/dev.ts @@ -18,7 +18,8 @@ const defines = { ...getMacroDefines(), // React production mode — prevents 6,889+ _debugStack Error objects // (12MB) from accumulating during long-running sessions. - 'process.env.NODE_ENV': JSON.stringify('development'), + // dev 模式使用 development 模式 + 'process.env.NODE_ENV': JSON.stringify('production'), } const defineArgs = Object.entries(defines).flatMap(([k, v]) => [ diff --git a/spec/feature_20260508_F001_tool-search/spec-design.md b/spec/feature_20260508_F001_tool-search/spec-design.md new file mode 100644 index 0000000000..d06f36dae2 --- /dev/null +++ b/spec/feature_20260508_F001_tool-search/spec-design.md @@ -0,0 +1,451 @@ +# Feature: 20260508_F001 - tool-search + +## 需求背景 + +当前 Claude Code 有 60+ 内置工具和无限 MCP 工具，Agent 在处理任务时缺乏"根据任务描述自动发现最匹配工具"的能力。现有 `ToolSearchTool` 仅处理延迟加载（按需加载 schema via `tool_reference`），不做语义发现。`tool_reference` 机制存在以下局限： + +1. **仅 Anthropic 一方 API 支持** — OpenAI/Gemini/Grok 兼容层不支持 `tool_reference` beta 特性 +2. **破坏 prompt cache** — 动态注入工具 schema 导致缓存失效 +3. **工具列表固定** — 每次请求的工具集在请求开始时就确定了，临时添加工具触发缓存全部失效 + +用户也无法直观了解哪些工具适合当前任务，缺乏推荐机制。 + +## 目标 + +1. 激进精简初始化工具注入，从 60+ 精简到 ~10 个核心工具 + 2 个入口工具（ToolSearch + ExecuteTool） +2. 增强 `ToolSearchTool`，增加 TF-IDF 文本匹配的"工具发现"能力 +3. 新建 `ExecuteTool`，提供跨 API provider 的统一工具执行入口 +4. 支持用户输入提示词后自动预取推荐工具（类似 skill prefetch） +5. 在 REPL 中展示工具推荐提示条（类似 skill search tips） +6. 搜索范围覆盖：MCP 工具、自定义工具、所有延迟加载的内置工具 +7. 复用 `localSearch.ts` 的 tokenize/stem/cosineSimilarity 基础设施 + +## 方案设计 + +### 整体架构 + +四层设计：初始化精简 + 搜索层 + 执行层 + UI 层。 + +```text +初始化阶段（激进精简）: + 核心工具（~10个，始终加载 schema） 延迟工具（其余全部，仅注入名称列表） + Bash / Read / Edit / Write / Glob WebFetch / WebSearch / NotebookEdit + Grep / Agent / AskUser / ToolSearch TodoWrite / CronTools / TeamCreate + ExecuteTool SkillTool / PlanMode / ...（50+ 工具） + ↓ MCP 工具也延迟加载 + +运行时发现与执行: + 用户输入 → 预取管道(异步) → TF-IDF 搜索 → UI 推荐提示 + ↓ + 模型处理任务 → ToolSearchTool(TF-IDF搜索) → 返回工具信息文本 + ↓ + 模型构造参数 → ExecuteTool(tool_name + params) → 路由执行 → 返回结果 +``` + +### 1. 初始化精简（激进策略） + +**核心思路**: 将初始化时注入的工具从 60+ 精简到 ~10 个核心工具 + 2 个入口工具（ToolSearch + ExecuteTool）。其余 50+ 工具全部延迟加载，仅注入名称列表到延迟工具清单。 + +**始终加载的核心工具**（31 个）: + +| 工具 | 始终加载的理由 | +|------|----------------| +| `BashTool` | 几乎所有任务都需要 shell 执行 | +| `FileReadTool` | 读取文件是基础操作 | +| `FileEditTool` | 编辑文件是核心能力 | +| `FileWriteTool` | 写入文件是核心能力 | +| `GlobTool` | 文件搜索是基础操作 | +| `GrepTool` | 内容搜索是基础操作 | +| `AgentTool` | 子 agent 调度是核心架构 | +| `AskUserQuestionTool` | 用户交互是基础能力 | +| `ToolSearchTool` | 工具发现入口 | +| `ExecuteTool` | 延迟工具执行入口（新增） | +| `TaskOutputTool` | 任务输出查询是高频操作 | +| `TaskStopTool` | 任务停止是 agent 生命周期管理 | +| `EnterPlanModeTool` | 进入计划模式是常见工作流 | +| `ExitPlanModeV2Tool` | 退出计划模式是常见工作流 | +| `VerifyPlanExecutionTool` | 计划执行验证与 ExitPlanMode 配套 | +| `TaskCreateTool` | 任务创建（TodoV2）是高频操作 | +| `TaskGetTool` | 任务查询（TodoV2）是高频操作 | +| `TaskUpdateTool` | 任务更新（TodoV2）是高频操作 | +| `TaskListTool` | 任务列表（TodoV2）是高频操作 | +| `TodoWriteTool` | 待办写入是任务跟踪基础 | +| `SendMessageTool` | 团队内 agent 通信 | +| `TeamCreateTool` | 团队创建（swarm 模式核心） | +| `TeamDeleteTool` | 团队删除（swarm 模式核心） | +| `ListPeersTool` | 跨会话通信发现 | +| `SkillTool` | 技能调用（/skill 命令） | +| `WebFetchTool` | Web 内容获取是常见需求 | +| `WebSearchTool` | Web 搜索是常见需求 | +| `NotebookEditTool` | Notebook 编辑是数据分析基础 | +| `LSPTool` | LSP 代码智能是开发基础 | +| `MonitorTool` | 后台监控进程（日志/轮询） | +| `SleepTool` | 等待时长（轮询 deploy 等场景） | + +**延迟加载的工具**（约 26 个内置工具 + 全部 MCP 工具）: + +所有未在核心列表中的内置工具，包括： + +| 工具 | 延迟加载的理由 | +|------|----------------| +| `ConfigTool` | 配置操作低频（ant only） | +| `TungstenTool` | 专用工具低频（ant only） | +| `SuggestBackgroundPRTool` | PR 建议低频 | +| `WebBrowserTool` | 浏览器操作低频（feature-gated） | +| `OverflowTestTool` | 测试专用（feature-gated） | +| `CtxInspectTool` | 上下文检查低频（debug/feature-gated） | +| `TerminalCaptureTool` | 终端捕获低频（feature-gated） | +| `EnterWorktreeTool` | worktree 操作低频 | +| `ExitWorktreeTool` | worktree 操作低频 | +| `REPLTool` | REPL 模式低频（ant only） | +| `WorkflowTool` | 工作流脚本低频（feature-gated） | +| `CronCreateTool` | 调度创建低频 | +| `CronDeleteTool` | 调度删除低频 | +| `CronListTool` | 调度列表低频 | +| `RemoteTriggerTool` | 远程触发低频 | +| `BriefTool` | 通信通道低频（KAIROS） | +| `SendUserFileTool` | 文件发送低频（KAIROS） | +| `PushNotificationTool` | 推送通知低频（KAIROS） | +| `SubscribePRTool` | PR 订阅低频 | +| `ReviewArtifactTool` | 产物审查低频 | +| `PowerShellTool` | PowerShell 低频（需显式启用） | +| `SnipTool` | 上下文裁剪低频（HISTORY_SNIP） | +| `DiscoverSkillsTool` | 技能发现低频（feature-gated） | +| `ListMcpResourcesTool` | MCP 资源列表低频 | +| `ReadMcpResourceTool` | MCP 资源读取低频 | +| `TestingPermissionTool` | 仅测试环境 | +| 全部 MCP 工具 | 按连接动态加载 | + +**实现方式**: + +1. **系统提示词增强**（`src/context.ts` 或 `src/constants/prompts.ts`）： + +在系统提示词中加入工具发现引导指令，确保模型始终知道如何获取延迟工具： + +```text +When you need a capability that isn't in your available tools, use ToolSearch +to discover and load it. ToolSearch can find all deferred tools by keyword or +task description. After discovering a tool, use ExecuteTool to invoke it with +the appropriate parameters. + +Common deferred tools include: CronTools (scheduling), WorktreeTools (git +isolation), SnipTool (context management), DiscoverSkills (skill search), +MCP resource tools, and many more. Always search first rather than assuming +a capability is unavailable. +``` + +2. **新增核心工具集合常量**（`src/constants/tools.ts`）： + +```typescript +export const CORE_TOOLS = new Set([ + // 文件操作 + 'Bash', 'Read', 'Edit', 'Write', 'Glob', 'Grep', + // Agent 与交互 + 'Agent', 'AskUserQuestion', 'SendMessage', 'ListPeers', + // 团队（swarm） + 'TeamCreate', 'TeamDelete', + // 任务管理 + 'TaskOutput', 'TaskStop', + 'TaskCreate', 'TaskGet', 'TaskUpdate', 'TaskList', + 'TodoWrite', + // 规划 + 'EnterPlanMode', 'ExitPlanMode', 'VerifyPlanExecution', + // Web + 'WebFetch', 'WebSearch', + // 编辑器 + 'NotebookEdit', + // 代码智能 + 'LSP', + // 技能 + 'Skill', + // 调度与监控 + 'Sleep', 'Monitor', + // 工具发现与执行（新增） + 'ToolSearch', 'ExecuteTool', +]) +``` + +2. **修改 `isDeferredTool` 判定逻辑**（`ToolSearchTool/prompt.ts`）： + +```typescript +export function isDeferredTool(tool: Tool): boolean { + if (tool.alwaysLoad === true) return false + if (tool.name === TOOL_SEARCH_TOOL_NAME) return false + if (tool.name === EXECUTE_TOOL_NAME) return false + // 核心工具不延迟 + if (CORE_TOOLS.has(tool.name)) return false + // MCP 工具和其余内置工具全部延迟 + return true +} +``` + +3. **修改 `getAllBaseTools()` 注册逻辑**（`src/tools.ts`）： + +核心工具直接注册（带完整 schema），延迟工具也注册到工具池（用于 ExecuteTool 查找），但标记为 deferred。 + +4. **延迟工具名称列表注入**（`src/services/api/claude.ts`）： + +构建 API 请求时，核心工具的 schema 正常注入。延迟工具仅注入名称列表到 `` 或 `system-reminder` 附件中，模型通过 ToolSearchTool 获取详情。 + +**收益**: +- 初始 prompt 体积减少约 30-40%（26 个内置工具 schema → 名称列表，加上 MCP 工具全延迟） +- Prompt cache 命中率提升（核心 31 工具列表稳定，延迟工具仅名称列表） +- 支持无限工具扩展（不受 context window 限制） + +**权衡**: +- 非核心工具首次使用需要一轮 ToolSearch → ExecuteTool 的额外交互 +- 模型需要更积极地使用 ToolSearchTool 发现可用工具 + +### 2. 工具索引层 + +**新增文件**: `src/services/toolSearch/toolIndex.ts` + +从 `src/services/skillSearch/localSearch.ts` 直接 import 复用 `tokenizeAndStem`、`computeWeightedTf`、`computeIdf`、`cosineSimilarity` 算法，新建工具索引。不提取为独立共享模块——skill 和 tool 的索引结构不同（`SkillIndexEntry` vs `ToolIndexEntry`），强行抽象反而增加复杂度。 + +**索引条目结构**: + +```typescript +interface ToolIndexEntry { + name: string // 工具名（如 "FileEditTool" 或 "mcp__server__action"） + normalizedName: string // 小写 + 连字符替换 + description: string // 工具描述文本 + searchHint: string | undefined // buildTool 中定义的 searchHint + isMcp: boolean // 是否 MCP 工具 + isDeferred: boolean // 是否延迟加载工具 + inputSchema: object | undefined // 参数 schema（JSON Schema 格式，供 discover 模式返回） + tokens: string[] // 分词后的 token 列表 + tfVector: Map // TF-IDF 向量 +} +``` + +**字段权重**: + +| 字段 | 权重 | 说明 | +|------|------|------| +| name | 3.0 | 工具名称（CamelCase 拆分、MCP `__` 拆分） | +| searchHint | 2.5 | 工具的 `searchHint` 字段（高信号） | +| description | 1.0 | 工具描述文本 | + +**索引生命周期**: +- 按需构建，缓存在会话中 +- MCP 工具连接/断开时触发增量更新（复用 `DeferredToolsDelta` 机制） +- 内置工具在首次构建时全量索引 +- 仅索引延迟工具（核心工具已在模型上下文中，无需发现） + +**工具名解析**: +- MCP 工具：`mcp__server__action` → 拆分为 `["mcp", "server", "action"]` +- 内置工具：`FileEditTool` → CamelCase 拆分为 `["file", "edit", "tool"]` +- 与现有 `ToolSearchTool.parseToolName` 逻辑对齐 + +### 3. 搜索层增强 + +**修改文件**: `packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` + +在现有 `searchToolsWithKeywords` 基础上，新增 TF-IDF 搜索路径： + +**增强的搜索流程**: + +``` +query 输入 + │ + ├── select: 前缀 → 直接选择（保留现有逻辑） + │ + └── 关键词搜索 → 并行执行两路搜索 + │ + ├── searchToolsWithKeywords（现有，关键词匹配 + 评分） + │ + └── searchToolsWithTfIdf（新增，TF-IDF 余弦相似度） + │ + └── 合并结果 → 加权求和 → 排序 → top-N +``` + +**结果合并策略**: +- 关键词匹配分数 × 0.4 + TF-IDF 相似度分数 × 0.6 +- 权重可通过环境变量 `TOOL_SEARCH_WEIGHT_KEYWORD` / `TOOL_SEARCH_WEIGHT_TFIDF` 调整 +- 去重：同一工具取两路中最高分 + +**输出格式变更**: + +`mapToolResultToToolResultBlockParam` 增加文本模式返回（当 `tool_reference` 不可用时）: + +```typescript +// 当 tool_reference 可用时（现有逻辑，保持不变） +{ type: 'tool_reference', tool_name: "..." } + +// 当 tool_reference 不可用时（新增） +{ type: 'text', text: "Found 3 tools:\n1. **ToolName** (score: 0.85)\n Description...\n Schema: {...}" } +``` + +判断条件：复用 `modelSupportsToolReference()` 或检测当前 provider 是否支持。 + +**新增 `discover` 查询模式**: + +``` +discover:<任务描述> — 纯发现搜索，不触发延迟加载，只返回工具信息 +``` + +与现有 `select:` 模式互补。`discover:` 返回工具名 + 描述 + 参数 schema（文本形式），供 ExecuteTool 使用。 + +### 4. 执行层（ExecuteTool） + +**新增文件**: `packages/builtin-tools/src/tools/ExecuteTool/` + +**工具定义**: + +```typescript +const ExecuteTool = buildTool({ + name: 'ExecuteTool', + searchHint: 'execute run invoke a tool by name with parameters', + + inputSchema: z.object({ + tool_name: z.string().describe('Name of the tool to execute'), + params: z.record(z.unknown()).describe('Parameters to pass to the tool'), + }), + + async call(input, context) { + // 1. 在全局工具注册表中查找目标工具 + // 2. 验证 params 是否符合目标工具的 inputSchema + // 3. 调用目标工具的 call 方法 + // 4. 返回执行结果 + }, +}) +``` + +**核心逻辑**: + +1. **工具查找**: 通过 `findToolByName` 在完整工具池（built-in + MCP）中查找 +2. **参数验证**: 用目标工具的 `inputSchema` 验证传入参数 +3. **权限继承**: 复用目标工具的 `checkPermissions` 方法 +4. **执行委托**: 调用目标工具的 `call(input, context)` 方法 +5. **结果透传**: 直接返回目标工具的执行结果 + +**权限模型**: +- ExecuteTool 本身不做额外权限检查 +- 权限检查委托给目标工具的 `checkPermissions` +- 用户审批时显示实际工具名和操作内容（而非 "ExecuteTool"） + +**工具注册**: +- 在 `src/tools.ts` 的 `getAllBaseTools()` 中注册 +- 与 ToolSearchTool 关联启用：当 `isToolSearchEnabledOptimistic()` 为 true 时注册 + +### 5. 预取管道 + +**新增文件**: `src/services/toolSearch/prefetch.ts` + +**触发时机**: 用户提交输入后、发送 API 请求前 + +**流程**: + +``` +用户输入提交 + │ + ├── 异步启动预取（不阻塞主流程） + │ │ + │ ├── 提取用户消息文本 + │ ├── 调用 toolIndex.search(message, limit: 3) + │ └── 存储结果到模块级缓存 + │ + └── API 请求构建时 + │ + └── collectToolSearchPrefetch() + │ + ├── 有结果 → 注入 system-reminder 或 + └── 无结果 → 不做任何附加 +``` + +**Hook 集成点**: 在 `REPL.tsx` 的消息提交流程或 `QueryEngine` 的请求构建环节中集成。 + +**并发安全**: 预取为异步操作，不阻塞主请求流程。如果预取未完成则跳过推荐。 + +### 6. 用户推荐 UI + +**新增文件**: `src/components/ToolSearchHint.tsx` + +**展示形式**: 在 REPL 输入区域上方渲染推荐提示条（类似现有 skill search tips 的设计）。 + +**UI 规格**: +- 显示匹配度最高的 2-3 个工具 +- 每个工具显示：工具名 + 简短描述（一行截断） + 匹配分数 +- 样式与现有 skill search tips 对齐（Ink 组件，使用 theme 色系） +- 可通过键盘快捷键选择（Tab 切换、Enter 确认） +- 选择后将工具信息追加到当前消息的上下文中 + +**条件显示**: +- 仅当预取结果非空时显示 +- 匹配分数低于阈值（默认 0.15）时不显示 +- 用户可通过 `settings.json` 关闭推荐提示 + +### 7. 搜索范围控制 + +采用激进精简策略后，搜索范围逻辑简化为： + +- **索引范围**: 所有延迟工具（即核心工具列表之外的全部工具），包括所有 MCP 工具和所有非核心内置工具 +- **排除范围**: 核心工具（`CORE_TOOLS` 集合中的工具）不索引 +- **动态更新**: MCP 工具连接/断开时增量更新索引 + +可通过环境变量 `TOOL_SEARCH_EXCLUDE` 追加排除项，`TOOL_SEARCH_INCLUDE_FORCE` 强制索引某些工具。 + +## 实现要点 + +### 关键技术决策 + +1. **复用 vs 重写 TF-IDF 基础设施**: 直接 import `localSearch.ts` 的 `tokenizeAndStem`、`computeWeightedTf`、`computeIdf`、`cosineSimilarity` 函数。不提取为独立模块，因为 skill 和 tool 的索引结构不同（SkillIndexEntry vs ToolIndexEntry），强行抽象会增加复杂度。 + +2. **ExecuteTool vs tool_reference**: ExecuteTool 是通用方案，兼容所有 API provider。当 provider 支持 `tool_reference` 时，优先使用 `tool_reference`（性能更好，模型认知负担更低）。当不支持时，回退到 ExecuteTool。 + +3. **索引更新策略**: MCP 工具连接/断开时，通过 `DeferredToolsDelta` 机制检测变化，增量更新索引而非全量重建。 + +4. **预取不阻塞主流程**: 预取为 fire-and-forget 异步操作。如果预取未完成，API 请求正常发送，不做任何等待。 + +### 难点 + +1. **权限透传**: ExecuteTool 调用目标工具时需要正确透传权限上下文，确保用户审批流程与直接调用目标工具一致。 + +2. **参数 schema 验证**: MCP 工具的 schema 可能非常复杂（嵌套对象、oneOf 等），ExecuteTool 需要优雅地处理 schema 验证失败的情况。 + +3. **缓存一致性**: 工具索引缓存需要在 MCP 连接变化时及时更新，避免搜索到已失效的工具。 + +### 依赖 + +- `src/services/skillSearch/localSearch.ts` — TF-IDF 算法复用 +- `packages/builtin-tools/src/tools/ToolSearchTool/` — 现有搜索逻辑基础 +- `src/utils/toolSearch.ts` — 工具搜索基础设施（模式判断、阈值计算） +- `packages/builtin-tools/src/tools/MCPTool/MCPTool.ts` — MCP 工具执行参考 + +### 新增文件清单 + +| 文件 | 职责 | +|------|------| +| `src/services/toolSearch/toolIndex.ts` | TF-IDF 工具索引构建与查询 | +| `src/services/toolSearch/prefetch.ts` | 用户输入预取管道 | +| `packages/builtin-tools/src/tools/ExecuteTool/ExecuteTool.ts` | 工具执行入口 | +| `packages/builtin-tools/src/tools/ExecuteTool/prompt.ts` | ExecuteTool prompt 定义 | +| `packages/builtin-tools/src/tools/ExecuteTool/constants.ts` | 常量定义 | +| `src/components/ToolSearchHint.tsx` | 用户推荐 UI 组件 | + +### 修改文件清单 + +| 文件 | 修改内容 | +|------|----------| +| `packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` | 新增 TF-IDF 搜索路径、discover 模式 | +| `packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` | 更新 prompt 文档、修改 `isDeferredTool` 判定逻辑 | +| `src/constants/tools.ts` | 新增 `CORE_TOOLS` 常量集合 | +| `src/tools.ts` | 注册 ExecuteTool、调整 `getAllBaseTools()` 工具注册 | +| `src/utils/toolSearch.ts` | 适配新的延迟判定逻辑 | +| `src/constants/prompts.ts` | 添加 ToolSearch 引导指令到系统提示词 | +| `src/services/api/claude.ts` | 集成预取管道、调整延迟工具注入方式 | +| `src/screens/REPL.tsx` | 集成 ToolSearchHint 组件 | + +## 验收标准 + +- [ ] 初始化时仅加载 ~10 个核心工具 schema，其余工具延迟加载 +- [ ] 延迟工具名称列表正确注入到 API 请求中 +- [ ] ToolSearchTool 支持基于 TF-IDF 的工具发现搜索（`discover:` 模式） +- [ ] ToolSearchTool 支持关键词 + TF-IDF 混合搜索 +- [ ] ExecuteTool 可通过 tool_name + params 执行任意已注册工具 +- [ ] ExecuteTool 在所有 API provider（Anthropic/OpenAI/Gemini/Grok）下均可工作 +- [ ] MCP 工具连接/断开时索引自动更新 +- [ ] 用户输入后预取管道异步工作，不阻塞主流程 +- [ ] REPL 中展示工具推荐提示条（可配置开关） +- [ ] `bun run precheck` 零错误通过 +- [ ] 新增单元测试覆盖：初始化精简验证、工具索引构建、TF-IDF 搜索、结果合并、ExecuteTool 执行 diff --git a/spec/feature_20260508_F001_tool-search/spec-human-verify.md b/spec/feature_20260508_F001_tool-search/spec-human-verify.md new file mode 100644 index 0000000000..f764dbc443 --- /dev/null +++ b/spec/feature_20260508_F001_tool-search/spec-human-verify.md @@ -0,0 +1,262 @@ +# Tool Search 基础设施层 人工验收清单 + +**生成时间:** 2026-05-08 +**关联计划:** spec/feature_20260508_F001_tool-search/spec-plan-1.md +**关联设计:** spec/feature_20260508_F001_tool-search/spec-design.md + +> 所有验收项均可自动化验证，无需人类参与。仍将生成清单用于自动执行。 + +--- + +## 验收前准备 + +### 环境要求 +- [ ] [AUTO] 检查 Bun 运行时: `bun --version` +- [ ] [AUTO] 检查 TypeScript 编译: `bunx tsc --noEmit --pretty 2>&1 | tail -5` + +--- + +## 验收项目 + +### 场景 1：核心工具白名单与延迟判定 + +> 验证 `CORE_TOOLS` 常量正确定义，`isDeferredTool` 已重构为白名单制判定。 + +#### - [x] 1.1 CORE_TOOLS 常量已定义且被引用 +- **来源:** spec-plan-1.md Task 1 / spec-design.md §1 +- **目的:** 确认核心工具白名单已建立 +- **操作步骤:** + 1. [A] `grep -c "CORE_TOOLS" src/constants/tools.ts` → 期望包含: 数字 ≥ 2 + 2. [A] `grep -rn "CORE_TOOLS" src/ packages/builtin-tools/src/ --include="*.ts" 2>/dev/null | wc -l` → 期望包含: 数字 ≥ 3 + +#### - [x] 1.2 isDeferredTool 函数体仅含白名单逻辑 +- **来源:** spec-plan-1.md Task 1 +- **目的:** 确认延迟判定从"排除例外"改为"包含准入" +- **操作步骤:** + 1. [A] `grep -A 8 "export function isDeferredTool" packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` → 期望包含: `CORE_TOOLS.has` + 2. [A] `grep -A 8 "export function isDeferredTool" packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` → 期望包含: `return true` + +#### - [x] 1.3 isDeferredTool 不再依赖旧 feature flag 逻辑 +- **来源:** spec-plan-1.md Task 1 +- **目的:** 确认旧的分散特判规则已清理 +- **操作步骤:** + 1. [A] `grep "feature(" packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` → 期望精确: "" + 2. [A] `grep "shouldDefer" packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` → 期望精确: "" + +#### - [x] 1.4 CORE_TOOLS 与 isDeferredTool 单元测试通过 +- **来源:** spec-plan-1.md Task 1 +- **目的:** 确认白名单制逻辑正确 +- **操作步骤:** + 1. [A] `bun test src/constants/__tests__/tools.test.ts 2>&1 | tail -5` → 期望包含: `pass` + +--- + +### 场景 2：TF-IDF 工具索引 + +> 验证 `localSearch.ts` 算法函数已导出，`toolIndex.ts` 正确构建 TF-IDF 索引并支持搜索。 + +#### - [x] 2.1 localSearch.ts 三个 TF-IDF 核心函数已导出 +- **来源:** spec-plan-1.md Task 2 +- **目的:** 确认算法复用基础已建立 +- **操作步骤:** + 1. [A] `grep -c "export function computeWeightedTf\|export function computeIdf\|export function cosineSimilarity" src/services/skillSearch/localSearch.ts` → 期望精确: "3" + +#### - [x] 2.2 toolIndex.ts 导出正确的接口与函数 +- **来源:** spec-plan-1.md Task 2 +- **目的:** 确认索引模块 API 完整 +- **操作步骤:** + 1. [A] `grep -c "export function\|export interface" src/services/toolSearch/toolIndex.ts` → 期望包含: 数字 ≥ 6 + +#### - [x] 2.3 toolIndex.ts TypeScript 编译无错误 +- **来源:** spec-plan-1.md Task 2 +- **目的:** 确认类型安全 +- **操作步骤:** + 1. [A] `bunx tsc --noEmit src/services/toolSearch/toolIndex.ts 2>&1 | head -20` → 期望包含: 无 error 行（或为空输出） + +#### - [x] 2.4 toolIndex.ts 单元测试通过 +- **来源:** spec-plan-1.md Task 2 +- **目的:** 确认索引构建和搜索逻辑正确 +- **操作步骤:** + 1. [A] `bun test src/services/toolSearch/__tests__/toolIndex.test.ts 2>&1 | tail -10` → 期望包含: `pass` + +#### - [x] 2.5 localSearch.ts 原有测试未回归 +- **来源:** spec-plan-1.md Task 2 +- **目的:** 确认导出变更未破坏现有功能 +- **操作步骤:** + 1. [A] `bun test src/services/skillSearch/__tests__/localSearch.test.ts 2>&1 | tail -10` → 期望包含: `pass` + +--- + +### 场景 3：ExecuteTool 执行入口 + +> 验证 ExecuteTool 工具包文件齐全、实现符合 buildTool 规范、权限透传正确。 + +#### - [x] 3.1 ExecuteTool 常量文件正确 +- **来源:** spec-plan-1.md Task 3 +- **目的:** 确认工具名常量已定义 +- **操作步骤:** + 1. [A] `grep -n 'EXECUTE_TOOL_NAME' packages/builtin-tools/src/tools/ExecuteTool/constants.ts` → 期望包含: `export const EXECUTE_TOOL_NAME` + +#### - [x] 3.2 ExecuteTool prompt 文件正确 +- **来源:** spec-plan-1.md Task 3 +- **目的:** 确认 prompt 与 description 已导出 +- **操作步骤:** + 1. [A] `grep -n 'export' packages/builtin-tools/src/tools/ExecuteTool/prompt.ts` → 期望包含: `DESCRIPTION` + 2. [A] `grep -n 'export' packages/builtin-tools/src/tools/ExecuteTool/prompt.ts` → 期望包含: `getPrompt` + +#### - [x] 3.3 ExecuteTool 使用 buildTool 构建 +- **来源:** spec-plan-1.md Task 3 / spec-design.md §4 +- **目的:** 确认遵循工具框架规范 +- **操作步骤:** + 1. [A] `grep -n 'buildTool\|satisfies ToolDef' packages/builtin-tools/src/tools/ExecuteTool/ExecuteTool.ts` → 期望包含: `buildTool` + 2. [A] `grep -n 'buildTool\|satisfies ToolDef' packages/builtin-tools/src/tools/ExecuteTool/ExecuteTool.ts` → 期望包含: `satisfies ToolDef` + +#### - [x] 3.4 isDeferredTool 正确排除 ExecuteTool +- **来源:** spec-plan-1.md Task 3 +- **目的:** 确认执行入口不被延迟加载 +- **操作步骤:** + 1. [A] `grep -n 'EXECUTE_TOOL_NAME' packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` → 期望包含: `EXECUTE_TOOL_NAME` + +#### - [x] 3.5 ExecuteTool 单元测试通过 +- **来源:** spec-plan-1.md Task 3 +- **目的:** 确认工具执行、权限透传、错误处理正确 +- **操作步骤:** + 1. [A] `bun test packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.test.ts 2>&1 | tail -5` → 期望包含: `pass` + +--- + +### 场景 4：ToolSearchTool 搜索增强 + +> 验证 TF-IDF 搜索路径、discover 模式、并行搜索合并、文本模式输出均已实现。 + +#### - [x] 4.1 TF-IDF 搜索依赖已正确导入 +- **来源:** spec-plan-1.md Task 4 +- **目的:** 确认搜索层依赖就位 +- **操作步骤:** + 1. [A] `grep -n "getToolIndex\|searchTools\|modelSupportsToolReference" packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` → 期望包含: `getToolIndex` + 2. [A] `grep -n "getToolIndex\|searchTools\|modelSupportsToolReference" packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` → 期望包含: `searchTools` + 3. [A] `grep -n "getToolIndex\|searchTools\|modelSupportsToolReference" packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` → 期望包含: `modelSupportsToolReference` + +#### - [x] 4.2 discover: 查询模式已实现 +- **来源:** spec-plan-1.md Task 4 / spec-design.md §3 +- **目的:** 确认纯发现搜索路径可用 +- **操作步骤:** + 1. [A] `grep -n "discoverMatch\|discover:" packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` → 期望包含: `discoverMatch` + +#### - [x] 4.3 关键词搜索与 TF-IDF 搜索并行执行 +- **来源:** spec-plan-1.md Task 4 / spec-design.md §3 +- **目的:** 确认两路搜索并行而非串行 +- **操作步骤:** + 1. [A] `grep -n "Promise.all" packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` → 期望包含: `Promise.all` + 2. [A] `grep -n "searchToolsWithKeywords\|getToolIndex" packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts | grep -i promise` → 期望包含: `searchToolsWithKeywords` + +#### - [x] 4.4 结果合并使用加权求和 +- **来源:** spec-plan-1.md Task 4 / spec-design.md §3 +- **目的:** 确认混合搜索结果正确排序 +- **操作步骤:** + 1. [A] `grep -n "KEYWORD_WEIGHT\|TFIDF_WEIGHT" packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` → 期望包含: `KEYWORD_WEIGHT` + 2. [A] `grep -n "KEYWORD_WEIGHT\|TFIDF_WEIGHT" packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` → 期望包含: `TFIDF_WEIGHT` + +#### - [x] 4.5 mapToolResultToToolResultBlockParam 支持文本模式回退 +- **来源:** spec-plan-1.md Task 4 / spec-design.md §3（跨 API provider 兼容） +- **目的:** 确认非 Anthropic provider 下返回文本格式 +- **操作步骤:** + 1. [A] `grep -n "supportsToolRef\|ExecuteTool" packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` → 期望包含: `supportsToolRef` + 2. [A] `grep -n "supportsToolRef\|ExecuteTool" packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` → 期望包含: `ExecuteTool` + +#### - [x] 4.6 prompt.ts 包含 discover: 模式文档 +- **来源:** spec-plan-1.md Task 4 +- **目的:** 确认模型可知晓 discover 查询模式 +- **操作步骤:** + 1. [A] `grep -n "discover:" packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` → 期望包含: `discover:` + +#### - [x] 4.7 ToolSearchTool 增强后 TypeScript 编译无新增错误 +- **来源:** spec-plan-1.md Task 4 +- **目的:** 确认类型安全 +- **操作步骤:** + 1. [A] `bunx tsc --noEmit --pretty 2>&1 | head -30` → 期望包含: 无新增 error 行 + +#### - [x] 4.8 ToolSearchTool 搜索增强单元测试通过 +- **来源:** spec-plan-1.md Task 4 +- **目的:** 确认 discover 模式、并行搜索、文本回退均正确 +- **操作步骤:** + 1. [A] `bun test packages/builtin-tools/src/tools/ToolSearchTool/__tests__/ToolSearchTool.test.ts 2>&1 | tail -10` → 期望包含: `pass` + +--- + +### 场景 5：端到端集成验证 + +> 验证全量测试、类型检查、构建产物均无回归。 + +#### - [x] 5.1 全量测试套件通过 +- **来源:** spec-plan-1.md Task 5 / spec-design.md 验收标准 +- **目的:** 确认所有新增测试无回归 +- **操作步骤:** + 1. [A] `bun test src/constants/__tests__/tools.test.ts src/services/toolSearch/__tests__/toolIndex.test.ts packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.test.ts packages/builtin-tools/src/tools/ToolSearchTool/__tests__/ 2>&1 | tail -10` → 期望包含: `pass` + +#### - [x] 5.2 TypeScript 全量类型检查通过 +- **来源:** spec-plan-1.md Task 5 / spec-design.md 验收标准 +- **目的:** 确认无新增类型错误 +- **操作步骤:** + 1. [A] `bunx tsc --noEmit --pretty 2>&1 | grep -i "error" | head -20` → 期望包含: 无新增 error 行（或为空输出） + +#### - [x] 5.3 CORE_TOOLS 在关键文件中被引用 +- **来源:** spec-plan-1.md Task 5 +- **目的:** 确认白名单常量已集成到延迟判定和工具索引 +- **操作步骤:** + 1. [A] `grep -rn "CORE_TOOLS" src/ packages/builtin-tools/src/ --include="*.ts" 2>/dev/null` → 期望包含: `tools.ts` + 2. [A] `grep -rn "CORE_TOOLS" src/ packages/builtin-tools/src/ --include="*.ts" 2>/dev/null` → 期望包含: `prompt.ts` + +#### - [x] 5.4 项目构建成功 +- **来源:** spec-plan-1.md Task 5 / spec-design.md 验收标准 +- **目的:** 确认构建产物可用 +- **操作步骤:** + 1. [A] `bun run build 2>&1 | tail -5` → 期望包含: `dist/cli.js` + +#### - [x] 5.5 precheck 零错误通过 +- **来源:** spec-design.md 验收标准 / CLAUDE.md +- **目的:** 确认 typecheck + lint fix + test 全通过 +- **操作步骤:** + 1. [A] `bun run precheck 2>&1 | tail -10` → 期望包含: 无 error 或 fail + +--- + +## 验收后清理 + +本功能为纯库代码变更，无后台服务启动，无需清理。 + +--- + +## 验收结果汇总 + +| 场景 | 序号 | 验收项 | [A] | [H] | 结果 | +|------|------|--------|-----|-----|------| +| 场景 1 | 1.1 | CORE_TOOLS 常量已定义且被引用 | 2 | 0 | ✅ | +| 场景 1 | 1.2 | isDeferredTool 函数体仅含白名单逻辑 | 2 | 0 | ✅ | +| 场景 1 | 1.3 | isDeferredTool 不再依赖旧 feature flag 逻辑 | 2 | 0 | ✅ | +| 场景 1 | 1.4 | CORE_TOOLS 与 isDeferredTool 单元测试通过 | 1 | 0 | ✅ | +| 场景 2 | 2.1 | localSearch.ts 三个 TF-IDF 核心函数已导出 | 1 | 0 | ✅ | +| 场景 2 | 2.2 | toolIndex.ts 导出正确的接口与函数 | 1 | 0 | ✅ | +| 场景 2 | 2.3 | toolIndex.ts TypeScript 编译无错误 | 1 | 0 | ✅ | +| 场景 2 | 2.4 | toolIndex.ts 单元测试通过 | 1 | 0 | ✅ | +| 场景 2 | 2.5 | localSearch.ts 原有测试未回归 | 1 | 0 | ✅ | +| 场景 3 | 3.1 | ExecuteTool 常量文件正确 | 1 | 0 | ✅ | +| 场景 3 | 3.2 | ExecuteTool prompt 文件正确 | 2 | 0 | ✅ | +| 场景 3 | 3.3 | ExecuteTool 使用 buildTool 构建 | 2 | 0 | ✅ | +| 场景 3 | 3.4 | isDeferredTool 正确排除 ExecuteTool | 1 | 0 | ✅ | +| 场景 3 | 3.5 | ExecuteTool 单元测试通过 | 1 | 0 | ✅ | +| 场景 4 | 4.1 | TF-IDF 搜索依赖已正确导入 | 3 | 0 | ✅ | +| 场景 4 | 4.2 | discover: 查询模式已实现 | 1 | 0 | ✅ | +| 场景 4 | 4.3 | 关键词搜索与 TF-IDF 搜索并行执行 | 2 | 0 | ✅ | +| 场景 4 | 4.4 | 结果合并使用加权求和 | 2 | 0 | ✅ | +| 场景 4 | 4.5 | 文本模式回退支持跨 API provider | 2 | 0 | ✅ | +| 场景 4 | 4.6 | prompt.ts 包含 discover: 模式文档 | 1 | 0 | ✅ | +| 场景 4 | 4.7 | 搜索增强后 TypeScript 编译无新增错误 | 1 | 0 | ✅ | +| 场景 4 | 4.8 | ToolSearchTool 搜索增强单元测试通过 | 1 | 0 | ✅ | +| 场景 5 | 5.1 | 全量测试套件通过 | 1 | 0 | ✅ | +| 场景 5 | 5.2 | TypeScript 全量类型检查通过 | 1 | 0 | ✅ | +| 场景 5 | 5.3 | CORE_TOOLS 在关键文件中被引用 | 2 | 0 | ✅ | +| 场景 5 | 5.4 | 项目构建成功 | 1 | 0 | ✅ | +| 场景 5 | 5.5 | precheck 零错误通过 | 1 | 0 | ✅ | + +**验收结论:** ✅ 全部通过 diff --git a/spec/feature_20260508_F001_tool-search/spec-plan-1.md b/spec/feature_20260508_F001_tool-search/spec-plan-1.md new file mode 100644 index 0000000000..aec8c51810 --- /dev/null +++ b/spec/feature_20260508_F001_tool-search/spec-plan-1.md @@ -0,0 +1,650 @@ +# Tool Search 执行计划（一）— 基础设施层 + +**目标:** 建立 tool search 的基础能力——核心工具常量、TF-IDF 工具索引、ExecuteTool 执行工具、ToolSearchTool 搜索增强 + +**技术栈:** TypeScript, Bun, Zod, TF-IDF (复用 localSearch.ts), buildTool 框架 + +**设计文档:** spec/feature_20260508_F001_tool-search/spec-design.md + +## 改动总览 + +- 新增 `CORE_TOOLS` 常量集合（31 个核心工具名）到 `src/constants/tools.ts`，重构 `isDeferredTool` 为白名单制；新建 TF-IDF 工具索引 `toolIndex.ts`（复用 `localSearch.ts` 算法）；新建 `ExecuteTool` 工具包（3 个文件）；增强 `ToolSearchTool` 搜索层（TF-IDF + discover 模式） +- Task 1（CORE_TOOLS）是 Task 2/3/4 的共同前置依赖；Task 2（toolIndex）被 Task 4（搜索增强）依赖 +- 关键决策：`isDeferredTool` 从"排除例外"改为"包含准入"白名单制，所有非核心工具默认延迟；TF-IDF 算法直接 import `localSearch.ts` 的导出函数，不创建独立共享模块 + +--- + +### Task 0: 环境准备 + +**背景:** +确保构建和测试工具链在当前开发环境中可用，避免后续 Task 因环境问题阻塞。 + +**执行步骤:** +- [x] 验证 Bun 运行时可用 + - `bun --version` + - 预期: 输出 Bun 版本号 +- [x] 验证 TypeScript 编译可用 + - `bunx tsc --noEmit --pretty 2>&1 | tail -5` + - 预期: 无新增类型错误（已有错误可忽略） +- [x] 验证测试框架可用 + - `bun test --help 2>&1 | head -3` + - 预期: 输出 bun test 帮助信息 + +**检查步骤:** +- [x] 构建命令执行成功 + - `bun run build 2>&1 | tail -10` + - 预期: 构建成功，输出 dist/cli.js +- [x] 现有测试可通过 + - `bun test src/constants/__tests__/ 2>&1 | tail -5 || echo "no existing tests in this dir"` + - 预期: 测试框架可用，无配置错误 + +--- + +### Task 1: 核心工具常量与延迟判定 + +**背景:** +当前 `isDeferredTool` 使用一组分散的特判规则（`shouldDefer`、MCP 检测、feature flag 特判）来决定工具是否延迟加载，缺少统一的"核心工具"概念。设计文档要求引入 `CORE_TOOLS` 白名单常量，将始终加载的核心工具（31 个）显式列出，并将 `isDeferredTool` 改为白名单制判定：核心工具 + alwaysLoad 工具 + ToolSearchTool/ExecuteTool 不延迟，其余全部延迟。本 Task 的输出（`CORE_TOOLS` 常量和重构后的 `isDeferredTool`）被 Task 2（TF-IDF 工具索引）、Task 3（ExecuteTool）、Task 4（ToolSearchTool 搜索增强）直接依赖。 + +**涉及文件:** +- 修改: `src/constants/tools.ts` +- 修改: `packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` +- 新建: `src/constants/__tests__/tools.test.ts` + +**执行步骤:** + +- [x] 在 `src/constants/tools.ts` 中新增 `CORE_TOOLS` 常量集合 + - 位置: `src/constants/tools.ts` 文件末尾（`COORDINATOR_MODE_ALLOWED_TOOLS` 之后，~L113） + - 新增以下 import（文件顶部 import 区域，与现有 import 风格一致）: + ```typescript + import { SLEEP_TOOL_NAME } from '@claude-code-best/builtin-tools/tools/SleepTool/prompt.js' + import { LSP_TOOL_NAME } from '@claude-code-best/builtin-tools/tools/LSPTool/prompt.js' + import { VERIFY_PLAN_EXECUTION_TOOL_NAME } from '@claude-code-best/builtin-tools/tools/VerifyPlanExecutionTool/constants.js' + import { TEAM_CREATE_TOOL_NAME } from '@claude-code-best/builtin-tools/tools/TeamCreateTool/constants.js' + import { TEAM_DELETE_TOOL_NAME } from '@claude-code-best/builtin-tools/tools/TeamDeleteTool/constants.js' + ``` + - 在文件末尾新增 `CORE_TOOLS` 导出常量: + ```typescript + /** + * Core tools that are always loaded with full schema at initialization. + * These tools are never deferred — they appear in the initial prompt. + * All other tools (non-core built-in + all MCP tools) are deferred + * and must be discovered via ToolSearchTool / ExecuteTool. + */ + export const CORE_TOOLS = new Set([ + // File operations + ...SHELL_TOOL_NAMES, // 'Bash', 'Shell' + FILE_READ_TOOL_NAME, // 'Read' + FILE_EDIT_TOOL_NAME, // 'Edit' + FILE_WRITE_TOOL_NAME, // 'Write' + GLOB_TOOL_NAME, // 'Glob' + GREP_TOOL_NAME, // 'Grep' + NOTEBOOK_EDIT_TOOL_NAME,// 'NotebookEdit' + // Agent & interaction + AGENT_TOOL_NAME, // 'Agent' + ASK_USER_QUESTION_TOOL_NAME, // 'AskUserQuestion' + SEND_MESSAGE_TOOL_NAME, // 'SendMessage' + // Team (swarm) + TEAM_CREATE_TOOL_NAME, // 'TeamCreate' + TEAM_DELETE_TOOL_NAME, // 'TeamDelete' + // Task management + TASK_OUTPUT_TOOL_NAME, // 'TaskOutput' + TASK_STOP_TOOL_NAME, // 'TaskStop' + TASK_CREATE_TOOL_NAME, // 'TaskCreate' + TASK_GET_TOOL_NAME, // 'TaskGet' + TASK_LIST_TOOL_NAME, // 'TaskList' + TASK_UPDATE_TOOL_NAME, // 'TaskUpdate' + TODO_WRITE_TOOL_NAME, // 'TodoWrite' + // Planning + ENTER_PLAN_MODE_TOOL_NAME, // 'EnterPlanMode' + EXIT_PLAN_MODE_V2_TOOL_NAME, // 'ExitPlanMode' + VERIFY_PLAN_EXECUTION_TOOL_NAME, // 'VerifyPlanExecution' + // Web + WEB_FETCH_TOOL_NAME, // 'WebFetch' + WEB_SEARCH_TOOL_NAME, // 'WebSearch' + // Code intelligence + LSP_TOOL_NAME, // 'LSP' + // Skills + SKILL_TOOL_NAME, // 'Skill' + // Scheduling & monitoring + SLEEP_TOOL_NAME, // 'Sleep' + // Tool discovery (always loaded) + TOOL_SEARCH_TOOL_NAME, // 'ToolSearch' + SYNTHETIC_OUTPUT_TOOL_NAME, // 'SyntheticOutput' + ]) as ReadonlySet + ``` + - 说明: `ListPeers` 和 `Monitor` 工具名在各自工具文件内以局部常量定义（非 export），无法在 `tools.ts` 中 import。`ListPeers` 频率较低，`Monitor` 受 `MONITOR_TOOL` feature gate 控制，两者暂不纳入 CORE_TOOLS，待后续 Task 按需加入。 + - 原因: 建立统一的"核心工具"白名单，为后续 Task 的延迟判定、工具索引排除提供单一数据源 + +- [x] 重构 `packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` 中的 `isDeferredTool` 函数 + - 位置: `packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` 的 `isDeferredTool` 函数体（L62-L108） + - 新增 import（文件顶部）: + ```typescript + import { CORE_TOOLS } from 'src/constants/tools.js' + ``` + - 替换整个 `isDeferredTool` 函数体为白名单制逻辑: + ```typescript + export function isDeferredTool(tool: Tool): boolean { + // Explicit opt-out via _meta['anthropic/alwaysLoad'] + if (tool.alwaysLoad === true) return false + + // Core tools are always loaded — never deferred + if (CORE_TOOLS.has(tool.name)) return false + + // Everything else (non-core built-in + all MCP tools) is deferred + return true + } + ``` + - 清理 isDeferredTool 不再需要的代码: + - 文件顶部的 `import { feature } from 'bun:bundle'`（仅被 isDeferredTool 使用的 feature flag 逻辑） + - 文件顶部的 `import { isReplBridgeActive } from 'src/bootstrap/state.js'`（仅被 KAIROS 逻辑使用） + - 保留 `import { getFeatureValue_CACHED_MAY_BE_STALE } from 'src/services/analytics/growthbook.js'`（仍被 `getToolLocationHint()` 使用，不删除） + - 文件顶部的 `import { AGENT_TOOL_NAME } from '../AgentTool/constants.js'`（不再被 isDeferredTool 使用） + - L8-L21 的 `BRIEF_TOOL_NAME` 和 `SEND_USER_FILE_TOOL_NAME` 条件 import 块（`isDeferredTool` 不再需要 feature flag 特判） + - 注意: 保留 `getToolLocationHint()` 函数及其对 `getFeatureValue_CACHED_MAY_BE_STALE` 的 import（仍被 `getPrompt()` 使用） + - 原因: 白名单制替代分散的特判规则，逻辑从"排除例外"变为"包含准入"，更易维护和扩展 + +- [x] 为 `CORE_TOOLS` 常量和 `isDeferredTool` 重构编写单元测试 + - 测试文件: `src/constants/__tests__/tools.test.ts`（新建） + - 测试场景: + - `CORE_TOOLS` 包含预期数量的工具（约 29 个: 7 SHELL_TOOL_NAMES + 22 独立工具名） + - `CORE_TOOLS` 包含所有设计文档中列出的核心工具名（抽查: 'Bash', 'Read', 'Edit', 'Write', 'Glob', 'Grep', 'Agent', 'AskUserQuestion', 'ToolSearch', 'WebSearch', 'WebFetch', 'Sleep', 'LSP', 'Skill', 'TeamCreate', 'TeamDelete', 'TaskCreate', 'TaskGet', 'TaskUpdate', 'TaskList', 'TaskOutput', 'TaskStop', 'TodoWrite', 'EnterPlanMode', 'ExitPlanMode', 'VerifyPlanExecution', 'NotebookEdit', 'SyntheticOutput'） + - `CORE_TOOLS` 是 ReadonlySet，不可外部修改 + - `isDeferredTool` 对 `CORE_TOOLS` 中的工具名返回 `false`（构造 `{ name: 'Read', alwaysLoad: undefined, isMcp: false, shouldDefer: undefined }` 形式的 mock Tool） + - `isDeferredTool` 对 `alwaysLoad: true` 的工具返回 `false`（即使工具名不在 CORE_TOOLS 中） + - `isDeferredTool` 对非核心内置工具返回 `true`（工具名 'ConfigTool'，无 alwaysLoad，无 isMcp） + - `isDeferredTool` 对 MCP 工具返回 `true`（`isMcp: true`，即使 alwaysLoad 为 undefined） + - `isDeferredTool` 对 `alwaysLoad: true` 的 MCP 工具返回 `false`（alwaysLoad 优先级最高） + - 运行命令: `bun test src/constants/__tests__/tools.test.ts` + - 预期: 所有测试通过 + +**检查步骤:** + +- [x] 验证 `CORE_TOOLS` 常量已导出且包含预期工具 + - `grep -c "CORE_TOOLS" src/constants/tools.ts` + - 预期: 至少 2 行（export 定义 + 注释） + +- [x] 验证 `isDeferredTool` 函数已简化为白名单制 + - `grep -A 8 "export function isDeferredTool" packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` + - 预期: 函数体仅包含 `alwaysLoad`、`CORE_TOOLS.has`、`return true` 三个分支，不包含 `isMcp`、`feature(`、`shouldDefer` 等旧逻辑 + +- [x] 验证 `isDeferredTool` 不再依赖已删除的 import + - `grep "feature(" packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` + - 预期: 无输出（feature flag 依赖已从 isDeferredTool 中移除） + +- [x] 验证类型检查通过 + - `bunx tsc --noEmit --pretty 2>&1 | head -30` + - 预期: 无新增类型错误 + +- [x] 运行新增单元测试 + - `bun test src/constants/__tests__/tools.test.ts` + - 预期: 所有测试通过 + +--- + +### Task 2: TF-IDF 工具索引 + +**背景:** +[业务语境] — 本 Task 构建工具索引模块，为 TF-IDF 搜索提供索引构建和查询能力。ToolSearchTool（Task 4）和预取管道依赖此索引来按任务描述发现延迟工具。 +[修改原因] — 当前项目只有 skill 搜索的 TF-IDF 实现（`localSearch.ts`），缺少工具维度的索引。`localSearch.ts` 中的 `computeWeightedTf`、`computeIdf`、`cosineSimilarity` 三个核心函数未导出，需要先导出才能复用。 +[上下游影响] — 本 Task 输出 `toolIndex.ts` 被 Task 4（ToolSearchTool 搜索增强）和 Task 3（ExecuteTool 工具查找）依赖。本 Task 依赖 Task 1（`CORE_TOOLS` 常量和 `isDeferredTool` 判定）。 + +**涉及文件:** +- 修改: `src/services/skillSearch/localSearch.ts`（导出三个私有函数） +- 新建: `src/services/toolSearch/toolIndex.ts` +- 新建: `src/services/toolSearch/__tests__/toolIndex.test.ts` + +**执行步骤:** + +- [x] 导出 `localSearch.ts` 中三个私有 TF-IDF 函数 — `toolIndex.ts` 需要复用这些算法函数 + - 位置: `src/services/skillSearch/localSearch.ts` L212, L230, L249 + - 在 `computeWeightedTf`、`computeIdf`、`cosineSimilarity` 三个函数声明前各加 `export` 关键字 + - 保持函数签名不变，仅增加导出修饰符 + - 原因: 这三个函数是 TF-IDF 核心算法，与索引结构无关，导出后 skill 和 tool 两个索引模块均可复用 + +- [x] 新建 `src/services/toolSearch/toolIndex.ts`，定义 `ToolIndexEntry` 接口和工具字段权重常量 + - 位置: 文件开头 + - 定义 `ToolIndexEntry` 接口，包含以下字段： + ```typescript + export interface ToolIndexEntry { + name: string + normalizedName: string + description: string + searchHint: string | undefined + isMcp: boolean + isDeferred: boolean + inputSchema: object | undefined + tokens: string[] + tfVector: Map + } + ``` + - 定义字段权重常量（参照 `localSearch.ts` 的 `FIELD_WEIGHT` 模式）： + ```typescript + const TOOL_FIELD_WEIGHT = { + name: 3.0, + searchHint: 2.5, + description: 1.0, + } as const + ``` + - 定义最小显示分数常量：`const TOOL_SEARCH_DISPLAY_MIN_SCORE = Number(process.env.TOOL_SEARCH_DISPLAY_MIN_SCORE ?? '0.10')` + - 原因: 工具索引结构与 skill 索引不同（无 `whenToUse`/`allowedTools`，增加 `searchHint`/`isMcp`/`isDeferred`/`inputSchema`），需独立定义 + +- [x] 实现 `parseToolName` 工具名解析函数 — 将工具名拆分为可搜索的 token 列表 + - 位置: `src/services/toolSearch/toolIndex.ts`，在接口定义之后 + - 从 `ToolSearchTool.ts:132-161` 的 `parseToolName` 逻辑提取并适配为独立函数： + ```typescript + export function parseToolName(name: string): { parts: string[]; full: string; isMcp: boolean } + ``` + - MCP 工具（`mcp__` 前缀）: 去掉前缀后按 `__` 和 `_` 拆分，结果示例 `mcp__github__create_issue` → `["github", "create", "issue"]` + - 内置工具: CamelCase 拆分 + 下划线拆分，结果示例 `NotebookEditTool` → `["notebook", "edit", "tool"]` + - 原因: 工具名是搜索的高权重信号，需要拆分为有意义的关键词 token + +- [x] 实现 `buildToolIndex` 索引构建函数 — 从 `Tool[]` 数组构建完整的 TF-IDF 索引 + - 位置: `src/services/toolSearch/toolIndex.ts`，在 `parseToolName` 之后 + - 函数签名：`export async function buildToolIndex(tools: Tool[]): Promise` + - 导入依赖：从 `localSearch.ts` 导入 `tokenizeAndStem`、`computeWeightedTf`、`computeIdf`、`cosineSimilarity` + - 核心逻辑： + 1. 过滤出延迟工具（调用 `isDeferredTool`，从 `@claude-code-best/builtin-tools/tools/ToolSearchTool/prompt.js` 导入） + 2. 对每个延迟工具，调用 `tool.prompt()` 获取描述文本（构造一个 mock 的 `getToolPermissionContext` 返回空权限上下文，`tools` 传原始工具列表，`agents` 传空数组） + 3. 调用 `parseToolName(tool.name)` 获取工具名 token + 4. 调用 `tokenizeAndStem` 对 `name parts`、`searchHint`、`description` 分别分词 + 5. 调用 `computeWeightedTf` 按权重计算 TF 向量 + 6. 读取 `tool.inputJSONSchema ?? (tool.inputSchema ? zodToJsonSchema(tool.inputSchema) : undefined)` 作为 `inputSchema` + 7. 组装 `ToolIndexEntry` 条目 + 8. 对全部条目调用 `computeIdf` 计算 IDF，将 TF 向量乘以 IDF 得到最终 TF-IDF 向量 + - 返回构建好的索引数组 + - 原因: 索引构建是搜索的前提，需要从 Tool 对象提取文本并计算 TF-IDF 向量 + +- [x] 实现 `searchTools` 搜索函数 — 按任务描述查询最匹配的工具 + - 位置: `src/services/toolSearch/toolIndex.ts`，在 `buildToolIndex` 之后 + - 函数签名：`export function searchTools(query: string, index: ToolIndexEntry[], limit?: number): ToolSearchResult[]` + - 定义返回类型： + ```typescript + export interface ToolSearchResult { + name: string + description: string + searchHint: string | undefined + score: number + isMcp: boolean + isDeferred: boolean + inputSchema: object | undefined + } + ``` + - 核心逻辑（参照 `localSearch.ts:searchSkills` L383-443 的模式）： + 1. 对 query 调用 `tokenizeAndStem` 分词 + 2. 计算 query 的 TF-IDF 向量（TF 归一化 + IDF 乘法） + 3. 对索引中每个条目计算 `cosineSimilarity(queryTfIdf, entry.tfVector)` + 4. CJK bigram 过滤：若 query 包含 CJK token 且匹配数 < 2 且无 ASCII 匹配，则分数置零（复用 `CJK_MIN_BIGRAM_MATCHES = 2` 常量） + 5. 工具名完全包含加分：若 query 小写化后包含工具的 `normalizedName`，分数取 `Math.max(score, 0.75)` + 6. 过滤 `score >= TOOL_SEARCH_DISPLAY_MIN_SCORE` 的结果 + 7. 按分数降序排列，截取前 `limit` 条（默认 5） + - 原因: 搜索函数是工具发现的核心入口，提供给 ToolSearchTool 和预取管道调用 + +- [x] 实现模块级索引缓存和增量更新 — 避免每次搜索都全量重建索引 + - 位置: `src/services/toolSearch/toolIndex.ts`，在 `searchTools` 之后 + - 定义模块级缓存变量： + ```typescript + let cachedIndex: ToolIndexEntry[] | null = null + let cachedToolNames: string | null = null + ``` + - 实现 `getToolIndex` 缓存包装函数：签名 `export async function getToolIndex(tools: Tool[]): Promise` + - 缓存 key 为延迟工具名排序后的字符串 + - 当工具名集合变化时（MCP 连接/断开），自动重建索引 + - 缓存未命中时调用 `buildToolIndex` + - 实现 `clearToolIndexCache` 清除函数：签名 `export function clearToolIndexCache(): void` + - 原因: 索引构建涉及异步 `tool.prompt()` 调用，缓存避免重复计算；增量更新通过比较工具名集合实现 + +- [x] 为 `toolIndex.ts` 核心逻辑编写单元测试 + - 测试文件: `src/services/toolSearch/__tests__/toolIndex.test.ts` + - 测试框架: `bun:test`（与 `localSearch.test.ts` 一致） + - 测试场景: + - `parseToolName` — MCP 工具名 `mcp__github__create_issue` 拆分为 `["github", "create", "issue"]`，`isMcp: true` + - `parseToolName` — 内置工具名 `NotebookEditTool` 拆分为 `["notebook", "edit", "tool"]`，`isMcp: false` + - `buildToolIndex` — 传入包含延迟工具的 mock Tool 数组，返回正确数量的 `ToolIndexEntry`，每个条目的 `tokens` 非空、`tfVector` 非空 + - `searchTools` — 英文查询 `"schedule cron job"` 能匹配含 `searchHint: "schedule a recurring or one-shot prompt"` 的工具，返回分数 > 0 且排名第一 + - `searchTools` — CJK 查询能匹配含中文描述的工具（参照 `localSearch.test.ts` 的 CJK 测试模式） + - `searchTools` — 空查询返回空数组 + - `searchTools` — 无匹配结果返回空数组 + - `getToolIndex` — 相同工具列表两次调用返回同一缓存引用 + - `clearToolIndexCache` — 调用后 `getToolIndex` 重新构建索引 + - Mock 构造: 创建 `Partial` 类型的 mock 工具，设置 `name`、`searchHint`、`prompt()`（返回固定描述字符串）、`inputSchema`（mock Zod schema 或 undefined）、`isMcp`、`shouldDefer`、`alwaysLoad` 等字段 + - 运行命令: `bun test src/services/toolSearch/__tests__/toolIndex.test.ts` + - 预期: 所有测试通过 + +**检查步骤:** +- [x] 验证 `localSearch.ts` 三个函数已导出 + - `grep -c "export function computeWeightedTf\|export function computeIdf\|export function cosineSimilarity" src/services/skillSearch/localSearch.ts` + - 预期: 输出 3 + +- [x] 验证 `toolIndex.ts` 文件存在且导出正确 + - `grep -c "export function\|export interface\|export type" src/services/toolSearch/toolIndex.ts` + - 预期: 至少 6（ToolIndexEntry, ToolSearchResult, parseToolName, buildToolIndex, searchTools, getToolIndex, clearToolIndexCache） + +- [x] 验证 TypeScript 编译无错误 + - `bunx tsc --noEmit src/services/toolSearch/toolIndex.ts 2>&1 | head -20` + - 预期: 无错误输出 + +- [x] 验证单元测试通过 + - `bun test src/services/toolSearch/__tests__/toolIndex.test.ts 2>&1 | tail -10` + - 预期: 输出包含 "pass" 且无 "fail" + +- [x] 验证 `localSearch.ts` 原有测试未回归 + - `bun test src/services/skillSearch/__tests__/localSearch.test.ts 2>&1 | tail -10` + - 预期: 所有测试通过，无回归 + +**认知变更:** +- [x] [CLAUDE.md] `src/services/skillSearch/localSearch.ts` 中的 `computeWeightedTf`、`computeIdf`、`cosineSimilarity` 已导出，供 `toolIndex.ts` 复用。修改这些函数时需同步检查工具索引的测试 +--- +### Task 3: ExecuteTool 执行工具 + +**背景:** +[业务语境] — 新建 ExecuteTool 作为跨 API provider 的统一工具执行入口。当模型通过 ToolSearchTool 发现延迟工具后，使用 ExecuteTool 以 `tool_name` + `params` 的方式调用该工具，替代仅 Anthropic 支持的 `tool_reference` 机制。 +[修改原因] — 当前项目无 ExecuteTool，延迟工具无法在非 Anthropic provider（OpenAI/Gemini/Grok）下被模型调用。 +[上下游影响] — 本 Task 依赖 Task 1（`EXECUTE_TOOL_NAME` 常量、`CORE_TOOLS` 集合、`isDeferredTool` 判定）。本 Task 的输出（ExecuteTool 工具实例）被 Task 4（ToolSearchTool 搜索增强）和 `src/tools.ts`（工具注册）依赖。 + +**涉及文件:** +- 新建: `packages/builtin-tools/src/tools/ExecuteTool/constants.ts` +- 新建: `packages/builtin-tools/src/tools/ExecuteTool/prompt.ts` +- 新建: `packages/builtin-tools/src/tools/ExecuteTool/ExecuteTool.ts` +- 修改: `packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts`（导入 `EXECUTE_TOOL_NAME`，在 `isDeferredTool` 中排除 ExecuteTool） +- 新建: `packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.test.ts` + +**执行步骤:** + +- [x] 创建 ExecuteTool 常量文件 + - 位置: 新建 `packages/builtin-tools/src/tools/ExecuteTool/constants.ts` + - 内容: + ```typescript + export const EXECUTE_TOOL_NAME = 'ExecuteTool' + ``` + - 原因: 与 `ToolSearchTool/constants.ts` 中的 `TOOL_SEARCH_TOOL_NAME` 保持一致的模式，供 `isDeferredTool`、工具注册等处引用 + +- [x] 创建 ExecuteTool prompt 文件 + - 位置: 新建 `packages/builtin-tools/src/tools/ExecuteTool/prompt.ts` + - 从 `./constants.js` 导入 `EXECUTE_TOOL_NAME` + - 导出 `DESCRIPTION` 常量（一句话描述）和 `getPrompt()` 函数 + - `getPrompt()` 返回完整 prompt 文本，包含： + - 功能说明：接受 `tool_name` + `params`，在全局工具注册表中查找目标工具并委托执行 + - 使用场景：当通过 ToolSearch 发现延迟工具后，使用此工具调用该工具 + - 输入说明：`tool_name` 是目标工具名称（如 "CronCreate"、"mcp__server__action"），`params` 是传递给目标工具的参数对象 + - 错误处理：工具不存在或参数无效时返回清晰的错误信息 + - 原因: 与 `ToolSearchTool/prompt.ts` 的 `getPrompt()` 模式保持一致，将 prompt 逻辑与工具实现分离 + +- [x] 创建 ExecuteTool 主实现文件 + - 位置: 新建 `packages/builtin-tools/src/tools/ExecuteTool/ExecuteTool.ts` + - 依赖导入: + - `z` from `zod/v4` + - `buildTool`, `findToolByName`, `type Tool`, `type ToolDef`, `type ToolUseContext`, `type ToolResult` from `src/Tool.js` + - `lazySchema` from `src/utils/lazySchema.js` + - `DESCRIPTION`, `getPrompt`, `EXECUTE_TOOL_NAME` from `./prompt.js` + - `EXECUTE_TOOL_NAME` from `./constants.js` + - `isToolSearchEnabledOptimistic` from `src/utils/toolSearch.js` + - 定义 `inputSchema`: `z.object({ tool_name: z.string().describe('...'), params: z.record(z.unknown()).describe('...') })` + - 定义 `outputSchema`: `z.object({ result: z.unknown(), tool_name: z.string() })` + - 使用 `buildTool` 构建 `ExecuteTool`，`satisfies ToolDef` + - 关键属性: + - `name: EXECUTE_TOOL_NAME` + - `searchHint: 'execute run invoke call a deferred tool by name with parameters'` + - `isConcurrencySafe() { return false }`（委托执行的工具是否并发安全取决于目标工具，保守设为 false） + - `maxResultSizeChars: 100_000`（与 ToolSearchTool 和 MCPTool 一致） + - `description()` 返回 `DESCRIPTION` + - `prompt()` 返回 `getPrompt()` + - `call(input, context)` 核心逻辑: + 1. 从 `context.options.tools` 中通过 `findToolByName(tools, input.tool_name)` 查找目标工具 + 2. 目标工具不存在时，返回 `{ data: { result: null, tool_name: input.tool_name }, newMessages: [错误提示 user message] }`，错误信息格式：`Tool "${input.tool_name}" not found. Use ToolSearch to discover available tools.` + 3. 目标工具存在时，调用 `targetTool.checkPermissions(input.params as any, context)` 获取权限结果 + 4. 权限检查结果为 `behavior: 'deny'` 时，返回权限拒绝信息 + 5. 权限检查通过后，调用 `targetTool.call(input.params as any, context, ...)` 委托执行，透传 context、canUseTool、parentMessage、onProgress 参数（`call` 签名为 `call(args, context, canUseTool, parentMessage, onProgress?)`，从 ExecuteTool 自身的 `call` 参数中获取后三个参数并传递给目标工具） + 6. 返回目标工具的执行结果，附加 `tool_name` 字段用于追踪 + - `checkPermissions()` 返回 `{ behavior: 'passthrough', message: 'ExecuteTool delegates permission to the target tool.' }`，与 MCPTool 的权限透传模式一致 + - `renderToolUseMessage(input)` 返回格式化字符串：`Executing ${input.tool_name}...`，用于 UI 展示 + - `userFacingName()` 返回 `'ExecuteTool'` + - `mapToolResultToToolResultBlockParam(content, toolUseID)` 返回标准 tool_result 格式 + - `isEnabled()` 返回 `isToolSearchEnabledOptimistic()`，与 ToolSearchTool 联动启用 + - `isReadOnly()` 返回 `false`（执行的工具可能执行写操作） + - 原因: 采用与 MCPTool 相同的 `buildTool` + `satisfies ToolDef` 模式，确保类型安全和框架一致性。权限透传采用 `passthrough` 策略，由目标工具自行决定权限逻辑 + +- [x] 在 `isDeferredTool` 中排除 ExecuteTool + - 位置: `packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` 的 `isDeferredTool` 函数内，在 `if (tool.name === TOOL_SEARCH_TOOL_NAME) return false` 之后（~L71） + - 新增导入: `import { EXECUTE_TOOL_NAME } from '../ExecuteTool/constants.js'` + - 插入: `if (tool.name === EXECUTE_TOOL_NAME) return false` + - 原因: ExecuteTool 是核心入口工具，必须在初始化时可用，不能被延迟加载 + +- [x] 为 ExecuteTool 编写单元测试 + - 测试文件: `packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.test.ts` + - 测试场景: + - 正常执行: 构造一个 mock 工具注册到 tools 列表中，调用 ExecuteTool 传入该工具名和合法参数，预期目标工具的 `call` 被调用且返回结果包含 `tool_name` + - 工具不存在: 传入不存在的 `tool_name`，预期返回错误信息且 `result` 为 null + - 权限拒绝: mock 目标工具的 `checkPermissions` 返回 `{ behavior: 'deny', message: 'denied' }`，预期 ExecuteTool 返回权限拒绝信息 + - isEnabled 联动: 验证 `ExecuteTool.isEnabled()` 依赖 `isToolSearchEnabledOptimistic()` 的返回值 + - searchHint 存在: 验证 `ExecuteTool.searchHint` 包含关键词 "execute" 和 "tool" + - 运行命令: `bun test packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.test.ts` + - 预期: 所有测试通过 + +**检查步骤:** +- [x] 验证常量文件正确导出 EXECUTE_TOOL_NAME + - `grep -n 'EXECUTE_TOOL_NAME' packages/builtin-tools/src/tools/ExecuteTool/constants.ts` + - 预期: 输出包含 `export const EXECUTE_TOOL_NAME = 'ExecuteTool'` +- [x] 验证 prompt 文件正确导出 DESCRIPTION 和 getPrompt + - `grep -n 'export' packages/builtin-tools/src/tools/ExecuteTool/prompt.ts` + - 预期: 输出包含 `DESCRIPTION` 和 `getPrompt` 的导出 +- [x] 验证 ExecuteTool 主文件使用 buildTool 构建且 satisfies ToolDef + - `grep -n 'buildTool\|satisfies ToolDef' packages/builtin-tools/src/tools/ExecuteTool/ExecuteTool.ts` + - 预期: 输出同时包含 `buildTool` 和 `satisfies ToolDef` +- [x] 验证 isDeferredTool 正确排除 ExecuteTool + - `grep -n 'EXECUTE_TOOL_NAME' packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` + - 预期: 输出包含 EXECUTE_TOOL_NAME 的导入和 `isDeferredTool` 中的排除逻辑 +- [x] 验证单元测试通过 + - `bun test packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.test.ts` + - 预期: 所有测试用例通过，无错误 + +--- + +### Task 4: ToolSearchTool 搜索增强 + +**背景:** +[业务语境] — 本 Task 在现有 ToolSearchTool 上叠加 TF-IDF 搜索路径、`discover:` 查询模式和文本模式输出，使模型能通过自然语言描述发现延迟工具，并在 `tool_reference` 不可用时仍能获取工具信息。 +[修改原因] — 当前 ToolSearchTool 仅支持关键词搜索（`searchToolsWithKeywords`），缺少语义匹配能力；`mapToolResultToToolResultBlockParam` 仅返回 `tool_reference` 块，不支持非 Anthropic provider；缺少纯发现模式供模型了解工具能力。 +[上下游影响] — 本 Task 依赖 Task 1（`isDeferredTool` 白名单制判定）和 Task 2（`buildToolIndex`、`searchTools`、`getToolIndex`）。本 Task 的输出（增强后的 ToolSearchTool）被 Task 5（预取管道）和 Task 6（UI 推荐）间接依赖。 + +**涉及文件:** +- 修改: `packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` +- 修改: `packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` +- 新建: `packages/builtin-tools/src/tools/ToolSearchTool/__tests__/ToolSearchTool.test.ts` + +**执行步骤:** + +- [x] 在 `ToolSearchTool.ts` 中新增 TF-IDF 搜索相关 import — 为并行搜索和结果合并做准备 + - 位置: `packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` 文件顶部 import 区域（L18 之前，现有 import 块之后） + - 新增 import: + ```typescript + import { getToolIndex, searchTools } from 'src/services/toolSearch/toolIndex.js' + import type { ToolSearchResult } from 'src/services/toolSearch/toolIndex.js' + import { modelSupportsToolReference } from 'src/utils/toolSearch.js' + ``` + - 新增权重常量（import 区域之后、`inputSchema` 定义之前）: + ```typescript + const KEYWORD_WEIGHT = Number(process.env.TOOL_SEARCH_WEIGHT_KEYWORD ?? '0.4') + const TFIDF_WEIGHT = Number(process.env.TOOL_SEARCH_WEIGHT_TFIDF ?? '0.6') + ``` + - 原因: TF-IDF 搜索函数和模型能力判断函数分别定义在 `src/` 下，需显式 import。权重常量支持环境变量调优。 + +- [x] 在 `ToolSearchTool.ts` 的 `call` 方法中增加 `discover:` 查询模式分支 — 纯发现搜索，不触发延迟加载 + - 位置: `ToolSearchTool.ts` 的 `call` 方法内，在 `selectMatch` 正则匹配之后（~L363）、关键词搜索之前（~L408） + - 在 `selectMatch` 分支之后插入 `discover:` 分支: + ```typescript + // Check for discover: prefix — pure discovery search. + // Returns tool info (name + description + schema) as text, + // does NOT trigger deferred tool loading. + const discoverMatch = query.match(/^discover:(.+)$/i) + if (discoverMatch) { + const discoverQuery = discoverMatch[1]!.trim() + const index = await getToolIndex(deferredTools) + const tfIdfResults = searchTools(discoverQuery, index, max_results) + // discover 模式返回文本格式的工具信息 + const textResults = tfIdfResults.map(r => { + let line = `**${r.name}** (score: ${r.score.toFixed(2)})\n${r.description}` + if (r.inputSchema) { + line += `\nSchema: ${JSON.stringify(r.inputSchema)}` + } + return line + }) + const text = textResults.length > 0 + ? `Found ${textResults.length} tools:\n${textResults.join('\n\n')}` + : 'No matching deferred tools found' + logSearchOutcome(tfIdfResults.map(r => r.name), 'keyword') + return buildSearchResult(tfIdfResults.map(r => r.name), query, deferredTools.length) + } + ``` + - 更新 `logSearchOutcome` 的 `queryType` 参数: `discover` 模式使用 `'keyword'` 类型（与关键词搜索共用类型，避免修改分析事件的枚举） + - 原因: `discover:` 模式让模型能了解延迟工具的能力（名称 + 描述 + schema），而不触发 schema 注入，适用于规划阶段或信息收集场景 + +- [x] 在 `ToolSearchTool.ts` 的 `call` 方法中实现关键词搜索与 TF-IDF 搜索的并行执行和结果合并 + - 位置: `ToolSearchTool.ts` 的 `call` 方法内，替换当前关键词搜索逻辑（L408-L433） + - 替换原有关键词搜索段为并行搜索 + 合并逻辑: + ```typescript + // Keyword search + TF-IDF search in parallel + const [keywordMatches, index] = await Promise.all([ + searchToolsWithKeywords(query, deferredTools, tools, max_results), + getToolIndex(deferredTools), + ]) + const tfIdfResults = searchTools(query, index, max_results) + + // Merge results: keyword score * 0.4 + TF-IDF score * 0.6 + const mergedScores = new Map() + // Add keyword results (assign scores inversely proportional to rank) + keywordMatches.forEach((name, rank) => { + const score = (keywordMatches.length - rank) / keywordMatches.length + mergedScores.set(name, (mergedScores.get(name) ?? 0) + score * KEYWORD_WEIGHT) + }) + // Add TF-IDF results + tfIdfResults.forEach(result => { + mergedScores.set(result.name, (mergedScores.get(result.name) ?? 0) + result.score * TFIDF_WEIGHT) + }) + + // Sort by merged score, take top-N + const matches = [...mergedScores.entries()] + .sort((a, b) => b[1] - a[1]) + .slice(0, max_results) + .map(([name]) => name) + ``` + - 保留后续的 `logForDebugging`、`logSearchOutcome`、空结果 pending servers 逻辑和 `buildSearchResult` 调用不变 + - 原因: 并行执行避免串行延迟；加权合并综合关键词精确匹配和 TF-IDF 语义匹配的优势（TF-IDF 权重更高，因为其语义能力更强） + +- [x] 修改 `mapToolResultToToolResultBlockParam` 方法，增加文本模式输出 — 当 `tool_reference` 不可用时返回文本格式工具信息 + - 位置: `ToolSearchTool.ts` 的 `mapToolResultToToolResultBlockParam` 方法（L444-L469） + - 新增方法参数 `context` 用于获取当前模型信息: 将 `mapToolResultToToolResultBlockParam(content, toolUseID)` 签名改为 `mapToolResultToToolResultBlockParam(content, toolUseID, context?)`，其中 `context` 类型为 `{ mainLoopModel?: string } | undefined` + - 在方法体中，`content.matches.length === 0` 分支保持不变 + - 在返回 `tool_reference` 块之前，插入 `tool_reference` 支持检查: + ```typescript + const supportsToolRef = context?.mainLoopModel + ? modelSupportsToolReference(context.mainLoopModel) + : true // 默认假设支持（向后兼容） + if (!supportsToolRef) { + // 文本模式: 返回工具名称列表 + return { + type: 'tool_result', + tool_use_id: toolUseID, + content: `Found ${content.matches.length} tool(s): ${content.matches.join(', ')}. Use ExecuteTool with tool_name and params to invoke.`, + } + } + ``` + - 保留原有 `tool_reference` 返回逻辑作为默认路径 + - 原因: 非 Anthropic provider（OpenAI/Gemini/Grok）不支持 `tool_reference` beta 特性，需要回退到文本模式输出，引导模型使用 ExecuteTool + +- [x] 更新 `ToolSearchTool/prompt.ts` 的 PROMPT 文本，增加 `discover:` 模式和 TF-IDF 搜索说明 + - 位置: `packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` 的 `PROMPT_TAIL` 常量（L44-L51） + - 在 `Query forms:` 部分追加 `discover:` 模式说明: + ```typescript + const PROMPT_TAIL = ` ... (保留现有内容) ... + +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` + - 原因: 模型需要知道 `discover:` 模式的存在和语义，才能正确使用该功能 + +- [x] 为 ToolSearchTool 搜索增强编写单元测试 + - 测试文件: `packages/builtin-tools/src/tools/ToolSearchTool/__tests__/ToolSearchTool.test.ts`（新建） + - 测试框架: `bun:test`（与 `DiscoverSkillsTool.test.ts` 一致） + - 测试场景: + - `discover:` 前缀解析: 传入 `query: "discover:send notification"` 调用 `ToolSearchTool.call()`，验证返回结果中 `matches` 非空且包含预期工具名（通过 mock `getToolIndex` 和 `searchTools`） + - `select:` 前缀保持不变: 传入 `query: "select:SomeTool"` 调用 `ToolSearchTool.call()`，验证返回结果中 `matches` 包含 `"SomeTool"`（mock `findToolByName` 返回对应工具） + - 关键词搜索 + TF-IDF 合并: mock `searchToolsWithKeywords` 返回 `["ToolA", "ToolB"]`，mock `searchTools` 返回 `[{name: "ToolB", score: 0.9}, {name: "ToolC", score: 0.8}]`，验证合并后 `matches` 包含 `"ToolB"`（两路均有）、`"ToolA"`（仅关键词）、`"ToolC"`（仅 TF-IDF），且 `"ToolB"` 排名靠前 + - 文本模式输出: 调用 `mapToolResultToToolResultBlockParam` 传入 `context: { mainLoopModel: 'claude-3-haiku-20240307' }`，验证返回内容为文本格式（包含 "Found" 和 "ExecuteTool"），而非 `tool_reference` 块 + - tool_reference 模式输出: 调用 `mapToolResultToToolResultBlockParam` 传入 `context: { mainLoopModel: 'claude-sonnet-4-20250514' }`，验证返回内容包含 `type: 'tool_reference'` 块 + - 向后兼容: 调用 `mapToolResultToToolResultBlockParam` 不传 `context` 参数，验证默认返回 `tool_reference` 块（向后兼容） + - 空结果处理: 传入不匹配的查询，验证返回结果中 `matches` 为空数组 + - Mock 策略: 使用 `bun:test` 的 `mock` 函数 mock `src/services/toolSearch/toolIndex.js` 的 `getToolIndex` 和 `searchTools`，mock `src/utils/toolSearch.js` 的 `modelSupportsToolReference` + - 运行命令: `bun test packages/builtin-tools/src/tools/ToolSearchTool/__tests__/ToolSearchTool.test.ts` + - 预期: 所有测试通过 + +**检查步骤:** + +- [x] 验证 TF-IDF 搜索 import 已添加 + - `grep -n "getToolIndex\|searchTools\|modelSupportsToolReference" packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` + - 预期: 输出包含 `getToolIndex`、`searchTools`、`modelSupportsToolReference` 的 import 行 + +- [x] 验证 `discover:` 模式分支已添加到 `call` 方法 + - `grep -n "discoverMatch\|discover:" packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` + - 预期: 输出包含 `discoverMatch` 正则匹配和 `discover:` 分支逻辑 + +- [x] 验证关键词搜索与 TF-IDF 搜索并行执行 + - `grep -n "Promise.all" packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` + - 预期: 输出包含 `Promise.all` 调用，参数包含 `searchToolsWithKeywords` 和 `getToolIndex` + +- [x] 验证结果合并逻辑使用加权求和 + - `grep -n "KEYWORD_WEIGHT\|TFIDF_WEIGHT" packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` + - 预期: 输出包含权重常量定义和在合并逻辑中的使用 + +- [x] 验证 `mapToolResultToToolResultBlockParam` 增加了文本模式分支 + - `grep -n "supportsToolRef\|ExecuteTool" packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts` + - 预期: 输出包含 `modelSupportsToolReference` 调用和 "ExecuteTool" 文本回退 + +- [x] 验证 prompt.ts 包含 `discover:` 模式说明 + - `grep -n "discover:" packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` + - 预期: 输出包含 `discover:` 模式的文档说明 + +- [x] 验证 TypeScript 编译无错误 + - `bunx tsc --noEmit --pretty 2>&1 | head -30` + - 预期: 无新增类型错误 + +- [x] 运行新增单元测试 + - `bun test packages/builtin-tools/src/tools/ToolSearchTool/__tests__/ToolSearchTool.test.ts` + - 预期: 所有测试通过 + +**认知变更:** +- [x] [CLAUDE.md] `ToolSearchTool.mapToolResultToToolResultBlockParam` 新增可选第三个参数 `context?: { mainLoopModel?: string }`，用于判断当前模型是否支持 `tool_reference`。不支持时回退到文本输出，引导模型使用 ExecuteTool。调用方（`src/services/api/claude.ts` 的 tool_result 处理逻辑）需传入 context 参数。 + +### Task 5: 基础设施层验收 + +**前置条件:** +- Task 1-4 全部完成 +- 构建环境: `bun run build` 可用 + +**端到端验证:** + +1. ✅ 运行完整测试套件确保无回归 + - `bun test src/constants/__tests__/tools.test.ts src/services/toolSearch/__tests__/toolIndex.test.ts packages/builtin-tools/src/tools/ExecuteTool/__tests__/ExecuteTool.test.ts packages/builtin-tools/src/tools/ToolSearchTool/__tests__/DiscoverSearch.test.ts 2>&1` + - 预期: 全部测试通过 + - 失败排查: 检查各 Task 的测试步骤，确认 import 路径和 mock 配置正确 + +2. ✅ 验证 TypeScript 类型检查通过 + - `bunx tsc --noEmit --pretty 2>&1 | grep -i "error" | head -20` + - 预期: 无新增类型错误 + - 失败排查: 检查 Task 1-4 中新增/修改文件的 import 路径和类型签名 + +3. ✅ 验证 CORE_TOOLS 常量被正确使用 + - `grep -rn "CORE_TOOLS" src/ packages/builtin-tools/src/ --include="*.ts" 2>/dev/null` + - 预期: 在 `tools.ts`、`prompt.ts`（isDeferredTool）、`toolIndex.ts` 中被引用 + - 失败排查: 检查 Task 1 和 Task 2 的 import 步骤 + +4. ✅ 验证 isDeferredTool 白名单制生效 + - `grep -A5 "export function isDeferredTool" packages/builtin-tools/src/tools/ToolSearchTool/prompt.ts` + - 预期: 函数体包含 `CORE_TOOLS.has(tool.name)`，不包含旧的 `shouldDefer`、`feature(` 逻辑 + - 失败排查: 检查 Task 1 的重构步骤 + +5. ✅ 验证构建产物正确 + - `bun run build 2>&1 | tail -5` + - 预期: 构建成功，输出 dist/cli.js + - 失败排查: 检查新增文件的 import 路径是否兼容 Bun.build splitting diff --git a/spec/feature_20260508_F001_tool-search/spec-plan-2.md b/spec/feature_20260508_F001_tool-search/spec-plan-2.md new file mode 100644 index 0000000000..c51b30b836 --- /dev/null +++ b/spec/feature_20260508_F001_tool-search/spec-plan-2.md @@ -0,0 +1,587 @@ +# Tool Search 执行计划（二）— 集成层 + +**目标:** 将基础设施层的组件集成到系统中——系统提示词增强、工具注册、预取管道、用户推荐 UI + +**技术栈:** TypeScript, React (Ink), Bun, Zod + +**设计文档:** spec/feature_20260508_F001_tool-search/spec-design.md + +**前置:** spec-plan-1.md（Task 1-4）已完成 + +## 改动总览 + +- 在系统提示词添加 ToolSearch + ExecuteTool 引导指令，tools.ts 注册 ExecuteTool，toolSearch.ts 更新过时注释；新建预取管道 prefetch.ts 集成到 attachments.ts 和 query.ts（复用 skill prefetch 模式）；新建 ToolSearchHint.tsx Ink 组件集成到 REPL +- Task 5（系统提示词与注册）是 Task 6/7 的前置；Task 6（预取管道）被 Task 7（UI）依赖 +- 关键决策：预取管道完全复用 skill prefetch 的触发/消费模式；UI 组件参考 PluginHintMenu 模式 + +--- + +--- + +### Task 0: 环境准备（轻量） + +**背景:** +Plan 1 的环境验证已完成，此处仅需确认 Plan 1 的产出文件可用。 + +**执行步骤:** +- [x] 确认 Plan 1 产出文件存在 + - `ls src/constants/tools.ts src/services/toolSearch/toolIndex.ts packages/builtin-tools/src/tools/ExecuteTool/ExecuteTool.ts 2>&1` + - 预期: 所有文件存在 + +**检查步骤:** +- [x] Plan 1 核心常量可被引用 + - `grep "CORE_TOOLS" src/constants/tools.ts | head -3` + - 预期: 输出包含 CORE_TOOLS 定义 + +--- + +--- + +### Task 5: 系统提示词与工具注册 + +**背景:** +[业务语境] — 本 Task 将 Task 3 创建的 ExecuteTool 注册到系统工具池中，并在系统提示词中添加 ToolSearch + ExecuteTool 的使用引导，确保模型知道如何发现和调用延迟工具。 +[修改原因] — 当前系统提示词（L192）仅提到"延迟工具必须通过 ToolSearch 或 DiscoverSkills 加载"，缺少 ExecuteTool 的引导。`src/tools.ts` 的 `getAllBaseTools()` 中未注册 ExecuteTool。`src/utils/toolSearch.ts` 的 `isToolSearchEnabled()` 和 `isToolSearchEnabledOptimistic()` 内部已通过 `isDeferredTool` 间接使用 `CORE_TOOLS`（Task 1 重构后），需确认无遗留的 `shouldDefer` 直接引用。 +[上下游影响] — 本 Task 依赖 Task 1（`CORE_TOOLS`、`isDeferredTool` 白名单制）和 Task 3（ExecuteTool 工具包创建完成）。本 Task 的输出被 Task 6（预取管道）和 Task 7（用户推荐 UI）依赖。 + +**涉及文件:** +- 修改: `src/constants/prompts.ts` +- 修改: `src/tools.ts` +- 修改: `src/utils/toolSearch.ts` + +**执行步骤:** + +- [x] 在 `src/constants/prompts.ts` 中添加 ToolSearch + ExecuteTool 引导指令到系统提示词 + - 位置: `src/constants/prompts.ts` 的 `getSimpleSystemSection()` 函数内，在 L192 的延迟工具说明条目之后 + - 当前 L192 内容为: + ``` + `Your visible tool list is partial by design — many tools (deferred tools, skills, MCP resources) must be loaded via ToolSearch or DiscoverSkills before you can call them. Before telling the user that a capability is unavailable, search for a tool or skill that covers it. Only state something is unavailable after the search returns no match.`, + ``` + - 在此条目之后（L193 之前）插入新条目: + ```typescript + `When you need a capability that isn't in your available tools, use ToolSearch to discover and load it. ToolSearch can find all deferred tools by keyword or task description. After discovering a tool, use ExecuteTool to invoke it with the appropriate parameters. Common deferred tools include: CronTools (scheduling), WorktreeTools (git isolation), SnipTool (context management), DiscoverSkills (skill search), MCP resource tools, and many more. Always search first rather than assuming a capability is unavailable.`, + ``` + - 在文件顶部 import 区域新增: + ```typescript + import { EXECUTE_TOOL_NAME } from '@claude-code-best/builtin-tools/tools/ExecuteTool/constants.js' + ``` + - 注意: `TOOL_SEARCH_TOOL_NAME` 已通过 `src/constants/tools.ts` 的 import 链路导入（L25 `import { TOOL_SEARCH_TOOL_NAME } from '@claude-code-best/builtin-tools/tools/ToolSearchTool/prompt.js'`），无需重复导入。但需在 `prompts.ts` 中新增 `EXECUTE_TOOL_NAME` 的 import（当前文件中无此 import，经 grep 确认）。 + - 原因: 模型需要明确知道 ExecuteTool 的存在和用法，否则发现延迟工具后不知道如何调用 + +- [x] 在 `src/tools.ts` 的 `getAllBaseTools()` 中注册 ExecuteTool + - 位置: `src/tools.ts` 的 `getAllBaseTools()` 函数内，在 L272 `...(isToolSearchEnabledOptimistic() ? [ToolSearchTool] : [])` 之后 + - 在文件顶部 import 区域（L84 附近，ToolSearchTool import 之后）新增: + ```typescript + import { ExecuteTool } from '@claude-code-best/builtin-tools/tools/ExecuteTool/ExecuteTool.js' + ``` + - 将 L272: + ```typescript + ...(isToolSearchEnabledOptimistic() ? [ToolSearchTool] : []), + ``` + - 修改为: + ```typescript + ...(isToolSearchEnabledOptimistic() ? [ToolSearchTool, ExecuteTool] : []), + ``` + - 原因: ExecuteTool 与 ToolSearchTool 联动启用，在相同条件块中注册确保两者同时可用或同时不可用 + +- [x] 在 `src/utils/toolSearch.ts` 中更新模块文档注释，移除过时的 `shouldDefer` 引用 + - 位置: `src/utils/toolSearch.ts` 文件顶部模块文档注释（L1-L7） + - 当前 L4 内容为: + ``` +` + * When enabled, deferred tools (MCP and shouldDefer tools) are sent with + * defer_loading: true and discovered via ToolSearchTool rather than being + * loaded upfront. + ``` + - 修改为: + ``` +` + * When enabled, deferred tools (all non-core tools) are sent with + * defer_loading: true and discovered via ToolSearchTool rather than being + * loaded upfront. Core tools are defined in CORE_TOOLS (src/constants/tools.ts). + ``` + - 位置: `src/utils/toolSearch.ts` 的 `ToolSearchMode` 类型文档注释（L155-L156） + - 当前内容为: + ``` +` + * Tool search mode. Determines how deferrable tools (MCP + shouldDefer) are + * surfaced: + ``` + - 修改为: + ``` +` + * Tool search mode. Determines how deferred tools (all non-core tools) + * are surfaced: + ``` + - 位置: `src/utils/toolSearch.ts` 的 `getToolSearchMode()` 函数文档注释（L170） + - 当前内容为: + ``` +` + * (unset) tst (default: always defer MCP and shouldDefer tools) + ``` + - 修改为: + ``` +` + * (unset) tst (default: always defer non-core tools) + ``` + - 位置: `src/utils/toolSearch.ts` 的 `getToolSearchMode()` 函数末尾 return 注释（L197） + - 当前内容为: + ```typescript + return 'tst' // default: always defer MCP and shouldDefer tools + ``` + - 修改为: + ```typescript + return 'tst' // default: always defer non-core tools + ``` + - 注意: `shouldDefer` 在此文件中仅出现在注释中（L4, L155, L170, L197），无任何运行时引用。`isDeferredTool` 函数从 `@claude-code-best/builtin-tools/tools/ToolSearchTool/prompt.js` 导入（L24），Task 1 已将其重构为白名单制，此处无需修改函数调用。 + - 原因: Task 1 将 `isDeferredTool` 重构为白名单制后，`shouldDefer` 概念已过时。更新注释保持文档与实现一致。 + +- [x] 为 Task 5 的三个修改点编写单元测试 + - 测试文件: `src/__tests__/toolSearchIntegration.test.ts`（新建） + - 测试场景: + - `getSystemPrompt` 包含 ExecuteTool 引导: 调用 `getSystemPrompt(mockTools, model)` 后，结果字符串中包含 "ExecuteTool" 和 "ToolSearch" 关键词 + - `getAllBaseTools` 包含 ExecuteTool 当 tool search 启用时: mock `isToolSearchEnabledOptimistic` 返回 `true`，验证 `getAllBaseTools()` 返回的工具列表中包含 `name: 'ExecuteTool'` 的工具 + - `getAllBaseTools` 不包含 ExecuteTool 当 tool search 禁用时: mock `isToolSearchEnabledOptimistic` 返回 `false`，验证 `getAllBaseTools()` 返回的工具列表中不包含 `name: 'ExecuteTool'` 的工具 + - `getAllBaseTools` 中 ExecuteTool 紧随 ToolSearchTool: 验证在 tool search 启用时，ExecuteTool 在工具列表中的位置紧跟 ToolSearchTool + - Mock 策略: 使用 `bun:test` 的 `mock` 函数 mock `src/utils/toolSearch.js` 的 `isToolSearchEnabledOptimistic` + - 运行命令: `bun test src/__tests__/toolSearchIntegration.test.ts` + - 预期: 所有测试通过 + +**检查步骤:** + +- [x] 验证系统提示词包含 ExecuteTool 引导 + - `grep -n "ExecuteTool" src/constants/prompts.ts` + - 预期: 至少 2 行（import + 引导文本） + +- [x] 验证 ExecuteTool 已注册到 getAllBaseTools + - `grep -n "ExecuteTool" src/tools.ts` + - 预期: 至少 2 行（import + 注册） + +- [x] 验证 ExecuteTool 与 ToolSearchTool 在同一条件块中注册 + - `grep -A1 "isToolSearchEnabledOptimistic" src/tools.ts | grep -c "ExecuteTool"` + - 预期: 输出 1（ExecuteTool 在 isToolSearchEnabledOptimistic 条件块中） + +- [x] 验证 toolSearch.ts 中无运行时 shouldDefer 引用（仅注释） + - `grep -n "shouldDefer" src/utils/toolSearch.ts` + - 预期: 无输出或仅在注释中出现 + +- [x] 验证 TypeScript 编译无错误 + - `bunx tsc --noEmit --pretty 2>&1 | head -30` + - 预期: 无新增类型错误 + +- [x] 运行新增单元测试 + - `bun test src/__tests__/toolSearchIntegration.test.ts` + - 预期: 所有测试通过 + +- [x] 验证现有 tools.test.ts 未回归 + - `bun test src/__tests__/tools.test.ts` + - 预期: 所有测试通过 + +--- + +### Task 6: 预取管道 + +**背景:** +[业务语境] — 本 Task 实现工具搜索预取管道，在用户输入后异步触发 TF-IDF 工具搜索，将推荐结果以 attachment 消息注入 API 请求，使模型在每轮对话中自动获得最相关的延迟工具提示。 +[修改原因] — 当前项目仅实现了 skill 搜索的预取管道（`skillSearch/prefetch.ts`），缺少工具维度的预取。工具预取需复用 skill prefetch 的集成模式（turn-0 阻塞式 + inter-turn 异步式），但使用独立的 attachment type（`tool_discovery`）和独立的搜索函数（`toolIndex.searchTools`）。 +[上下游影响] — 本 Task 依赖 Task 2（`toolIndex.ts` 的 `getToolIndex` 和 `searchTools`）。本 Task 的输出（`prefetch.ts` 模块和集成代码）被 Task 7（用户推荐 UI）间接依赖，UI 组件需要消费预取结果来渲染推荐提示条。 + +**涉及文件:** +- 新建: `src/services/toolSearch/prefetch.ts` +- 修改: `src/utils/attachments.ts` +- 修改: `src/query.ts` + +**执行步骤:** + +- [x] 新建 `src/services/toolSearch/prefetch.ts`，定义 `ToolDiscoveryResult` 类型和 `tool_discovery` attachment 构建函数 + - 位置: 新建文件 `src/services/toolSearch/prefetch.ts`，文件开头 + - 导入依赖: + ```typescript + import type { Attachment } from '../../utils/attachments.js' + import type { Message } from '../../types/message.js' + import type { Tool } from '../../Tool.js' + import { getToolIndex, searchTools } from './toolIndex.js' + import type { ToolSearchResult } from './toolIndex.js' + import { logForDebugging } from '../../utils/debug.js' + ``` + - 定义 `ToolDiscoveryResult` 类型: + ```typescript + export type ToolDiscoveryResult = { + name: string + description: string + searchHint: string | undefined + score: number + isMcp: boolean + isDeferred: boolean + inputSchema: object | undefined + } + ``` + - 定义 `buildToolDiscoveryAttachment` 函数: + ```typescript + function buildToolDiscoveryAttachment( + tools: ToolDiscoveryResult[], + trigger: 'assistant_turn' | 'user_input', + queryText: string, + durationMs: number, + indexSize: number, + ): Attachment { + return { + type: 'tool_discovery', + tools, + trigger, + queryText: queryText.slice(0, 200), + durationMs, + indexSize, + } as Attachment + } + ``` + - 原因: `tool_discovery` 作为独立的 attachment type 与 `skill_discovery` 并列，数据结构不同（工具无 `shortId`/`autoLoaded`/`content`/`path`/`gap`，增加 `searchHint`/`isMcp`/`isDeferred`/`inputSchema`），不能复用 `skill_discovery` 类型 + +- [x] 实现 `startToolSearchPrefetch` 异步预取函数 — inter-turn 场景，在 query loop 中异步触发 + - 位置: `src/services/toolSearch/prefetch.ts`，在 `buildToolDiscoveryAttachment` 之后 + - 函数签名: + ```typescript + export async function startToolSearchPrefetch( + tools: Tool[], + messages: Message[], + ): Promise + ``` + - 核心逻辑（参照 `skillSearch/prefetch.ts:startSkillDiscoveryPrefetch` L249-296 的模式）: + 1. 调用 `extractQueryFromMessages(null, messages)` 提取用户查询文本（复用 `skillSearch/prefetch.ts` 导出的 `extractQueryFromMessages` 函数，该函数已导出且逻辑通用） + 2. `queryText` 为空时返回 `[]` + 3. 记录 `startedAt = Date.now()` + 4. 调用 `getToolIndex(tools)` 获取缓存的工具索引 + 5. 调用 `searchTools(queryText, index, 3)` 搜索 top-3 工具（预取场景限制 3 条，减少 token 开销） + 6. 过滤会话内已发现的工具（定义模块级 `discoveredToolsThisSession: Set`，与 skill prefetch 的 `discoveredThisSession` 独立） + 7. 结果为空时返回 `[]` + 8. 记录 `logForDebugging` 日志 + 9. 返回 `[buildToolDiscoveryAttachment(filteredResults, 'assistant_turn', queryText, durationMs, index.length)]` + 10. catch 块返回 `[]`（fire-and-forget，不向上传播错误） + - 原因: 异步预取不阻塞主流程，与 skill prefetch 保持一致的错误处理策略（静默失败） + +- [x] 实现 `getTurnZeroToolSearchPrefetch` 同步获取函数 — turn-0 场景，用户首次输入时阻塞式获取 + - 位置: `src/services/toolSearch/prefetch.ts`，在 `startToolSearchPrefetch` 之后 + - 函数签名: + ```typescript + export async function getTurnZeroToolSearchPrefetch( + input: string, + tools: Tool[], + ): Promise + ``` + - 核心逻辑（参照 `skillSearch/prefetch.ts:getTurnZeroSkillDiscovery` L308-356 的模式）: + 1. `input` 为空时返回 `null` + 2. 记录 `startedAt = Date.now()` + 3. 调用 `getToolIndex(tools)` 获取工具索引 + 4. 调用 `searchTools(input, index, 3)` 搜索 top-3 工具 + 5. 结果为空时返回 `null` + 6. 将结果工具名加入 `discoveredToolsThisSession` + 7. 记录 `logForDebugging` 日志 + 8. 返回 `buildToolDiscoveryAttachment(results, 'user_input', input, durationMs, index.length)` + 9. catch 块返回 `null` + - 原因: turn-0 是唯一的阻塞式入口，因为此时没有其他计算可以隐藏预取延迟。与 skill prefetch 保持一致的设计 + +- [x] 实现 `collectToolSearchPrefetch` 结果收集函数 — 等待异步预取完成并收集结果 + - 位置: `src/services/toolSearch/prefetch.ts`，在 `getTurnZeroToolSearchPrefetch` 之后 + - 函数签名: + ```typescript + export async function collectToolSearchPrefetch( + pending: Promise, + ): Promise + ``` + - 核心逻辑（与 `skillSearch/prefetch.ts:collectSkillDiscoveryPrefetch` L298-306 完全一致）: + ```typescript + try { + return await pending + } catch { + return [] + } + ``` + - 原因: 包装 Promise，确保预取失败时返回空数组而非抛出异常 + +- [x] 在 `src/utils/attachments.ts` 中注册 `tool_discovery` attachment type — 扩展 Attachment 联合类型 + - 位置: `src/utils/attachments.ts` 的 `Attachment` 类型定义中，在 `skill_discovery` 类型分支（L534-L555）之后 + - 新增 import（文件顶部 import 区域）: + ```typescript + import type { ToolDiscoveryResult } from '../services/toolSearch/prefetch.js' + ``` + - 在 `skill_discovery` 分支后追加 `tool_discovery` 类型: + ```typescript + | { + type: 'tool_discovery' + tools: ToolDiscoveryResult[] + trigger: 'assistant_turn' | 'user_input' + queryText: string + durationMs: number + indexSize: number + } + ``` + - 原因: `createAttachmentMessage` 接收 `Attachment` 类型参数，必须将 `tool_discovery` 注册到联合类型中才能通过类型检查 + +- [x] 在 `src/utils/attachments.ts` 中集成 turn-0 工具预取 — 在 skill discovery 附件之后添加 tool discovery 附件 + - 位置: `src/utils/attachments.ts` 的 `getAttachmentMessages` 函数中，在 skill discovery 的 `maybe('skill_discovery', ...)` 调用块（L818-L831）之后 + - 新增条件 require 模块（与 `skillSearchModules` 模式一致，在文件顶部 ~L92 `skillSearchModules` 定义之后）: + ```typescript + const toolSearchModules = feature('EXPERIMENTAL_TOOL_SEARCH') + ? { + prefetch: + require('../services/toolSearch/prefetch.js') as typeof import('../services/toolSearch/prefetch.js'), + } + : null + ``` + - 在 skill discovery 的 spread 数组中追加 tool discovery 附件（在 `]` 闭合 `maybe('skill_discovery', ...)` 之后，在外层 spread `...(feature('EXPERIMENTAL_SKILL_SEARCH') &&` 的 `]` 之前）: + ```typescript + ...(feature('EXPERIMENTAL_TOOL_SEARCH') && + toolSearchModules && + !options?.skipSkillDiscovery + ? [ + maybe('tool_discovery', async () => { + if (suppressNextDiscovery) { + return [] + } + const result = + await toolSearchModules.prefetch.getTurnZeroToolSearchPrefetch( + input, + context.options.tools ?? [], + ) + return result ? [result] : [] + }), + ] + : []), + ``` + - 注意: `suppressNextDiscovery` 与 skill discovery 共用同一个标志（skill expansion 路径不应触发工具发现，语义一致） + - 原因: turn-0 预取与 skill discovery 共享同一集成点（`getAttachmentMessages`），两者互不干扰，各自生成独立 attachment + +- [x] 在 `src/query.ts` 中集成 inter-turn 工具预取触发 — 在 skill prefetch 之后异步启动工具预取 + - 位置: `src/query.ts` 文件顶部 conditional require 区域（~L68-70 `skillPrefetch` 定义之后） + - 新增 conditional require: + ```typescript + const toolSearchPrefetch = feature('EXPERIMENTAL_TOOL_SEARCH') + ? (require('./services/toolSearch/prefetch.js') as typeof import('./services/toolSearch/prefetch.js')) + : null + ``` + - 位置: `src/query.ts` 的 `queryLoop` 函数中，在 `pendingSkillPrefetch` 定义（L480-484）之后 + - 新增工具预取触发: + ```typescript + const pendingToolPrefetch = toolSearchPrefetch?.startToolSearchPrefetch( + state.tools ?? [], + messages, + ) + ``` + - 原因: 与 skill prefetch 保持相同的触发时机（每轮迭代开始时异步启动），两者并行执行互不阻塞 + +- [x] 在 `src/query.ts` 中集成工具预取结果消费 — 在 skill prefetch 收集之后收集工具预取结果 + - 位置: `src/query.ts` 的 `queryLoop` 函数中，在 skill prefetch 结果消费块（L1910-L1918）之后 + - 新增工具预取结果消费: + ```typescript + if (toolSearchPrefetch && pendingToolPrefetch) { + const toolAttachments = + await toolSearchPrefetch.collectToolSearchPrefetch(pendingToolPrefetch) + for (const att of toolAttachments) { + const msg = createAttachmentMessage(att) + yield msg + toolResults.push(msg) + } + } + ``` + - 原因: 与 skill prefetch 结果消费保持一致的位置和模式（post-tools 阶段注入），确保预取结果在本轮工具执行完成后、下一轮模型调用前注入 + +- [x] 为 `prefetch.ts` 核心逻辑编写单元测试 + - 测试文件: `src/services/toolSearch/__tests__/prefetch.test.ts`（新建） + - 测试框架: `bun:test` + - 测试场景: + - `startToolSearchPrefetch` — 正常调用: 构造 mock Tool 数组和 mock messages，mock `getToolIndex` 返回固定索引，mock `searchTools` 返回匹配结果，验证返回的 `Attachment[]` 包含 `type: 'tool_discovery'` 且 `tools` 非空、`trigger` 为 `'assistant_turn'` + - `startToolSearchPrefetch` — 空查询: messages 中无用户文本内容，验证返回空数组 + - `startToolSearchPrefetch` — 无匹配: `searchTools` 返回空数组，验证返回空数组 + - `startToolSearchPrefetch` — 异常安全: mock `getToolIndex` 抛出异常，验证返回空数组（不抛出） + - `startToolSearchPrefetch` — 会话去重: 连续两次调用传入相同工具名，第二次返回空数组（已被 `discoveredToolsThisSession` 过滤） + - `getTurnZeroToolSearchPrefetch` — 正常调用: 传入有效 input 和 mock tools，验证返回非 null 的 `Attachment`，`trigger` 为 `'user_input'` + - `getTurnZeroToolSearchPrefetch` — 空输入: 传入空字符串，验证返回 null + - `getTurnZeroToolSearchPrefetch` — 无匹配: `searchTools` 返回空数组，验证返回 null + - `collectToolSearchPrefetch` — 正常收集: 传入 resolved promise，验证返回对应 attachment 数组 + - `collectToolSearchPrefetch` — 异常安全: 传入 rejected promise，验证返回空数组 + - `buildToolDiscoveryAttachment` — 返回的 attachment 对象包含 `type: 'tool_discovery'`、`tools`、`trigger`、`queryText`、`durationMs`、`indexSize` 字段 + - Mock 策略: 使用 `bun:test` 的 `mock` 函数 mock `./toolIndex.js` 的 `getToolIndex` 和 `searchTools`；构造 `Partial` 类型的 mock Tool 对象；构造包含 `{ type: 'user', content: 'test query' }` 的 mock Message 数组 + - 运行命令: `bun test src/services/toolSearch/__tests__/prefetch.test.ts` + - 预期: 所有测试通过 + +**检查步骤:** + +- [x] 验证 `prefetch.ts` 文件存在且导出正确 + - `grep -c "export async function\|export type" src/services/toolSearch/prefetch.ts` + - 预期: 至少 5（startToolSearchPrefetch, getTurnZeroToolSearchPrefetch, collectToolSearchPrefetch, ToolDiscoveryResult, extractQueryFromMessages import） + +- [x] 验证 `tool_discovery` 类型已注册到 Attachment 联合类型 + - `grep -n "tool_discovery" src/utils/attachments.ts` + - 预期: 至少 2 行（类型定义 + maybe 调用） + +- [x] 验证 `query.ts` 中工具预取触发和消费代码已添加 + - `grep -n "toolSearchPrefetch\|pendingToolPrefetch\|collectToolSearchPrefetch" src/query.ts` + - 预期: 至少 6 行（conditional require + start 调用 + if + collect 调用 + yield） + +- [x] 验证 `attachments.ts` 中 turn-0 工具预取已集成 + - `grep -n "getTurnZeroToolSearchPrefetch\|toolSearchModules" src/utils/attachments.ts` + - 预期: 至少 3 行（conditional require + getTurnZero 调用 + toolSearchModules 使用） + +- [x] 验证 TypeScript 编译无错误 + - `bunx tsc --noEmit --pretty 2>&1 | head -30` + - 预期: 无新增类型错误 + +- [x] 验证单元测试通过 + - `bun test src/services/toolSearch/__tests__/prefetch.test.ts 2>&1 | tail -10` + - 预期: 输出包含 "pass" 且无 "fail" + +**认知变更:** +- [x] [CLAUDE.md] `src/services/toolSearch/prefetch.ts` 的 `extractQueryFromMessages` 复用了 `src/services/skillSearch/prefetch.ts` 的同名导出函数。修改 `skillSearch/prefetch.ts` 的 `extractQueryFromMessages` 时需同步检查工具预取的行为。工具预取使用独立的 `discoveredToolsThisSession` Set，与 skill prefetch 的去重集合互不影响。 + +--- + +### Task 7: 用户推荐 UI + +**背景:** +[业务语境] — 在 REPL 输入区域上方渲染工具推荐提示条，帮助用户了解哪些工具适合当前任务，提升工具发现体验 +[修改原因] — 当前缺少面向用户的工具推荐可视化，预取管道（Task 6）产出的匹配结果无法被用户感知 +[上下游影响] — 本 Task 消费 Task 6 `collectToolSearchPrefetch()` 的预取结果数据；本 Task 的组件挂载到 REPL.tsx 的对话框优先级系统中 + +**涉及文件:** +- 新建: `src/components/ToolSearchHint.tsx` +- 新建: `src/components/__tests__/ToolSearchHint.test.ts` +- 修改: `src/screens/REPL.tsx` + +**执行步骤:** +- [x] 新建 `src/components/ToolSearchHint.tsx` — Ink 组件，渲染工具推荐提示条 + - 位置: 新建文件，参照 `src/components/ClaudeCodeHint/PluginHintMenu.tsx` 的结构模式 + - 组件签名: + ```typescript + type ToolSearchHintItem = { + name: string; + description: string; + score: number; + }; + type Props = { + tools: ToolSearchHintItem[]; + onSelect: (toolName: string) => void; + onDismiss: () => void; + }; + export function ToolSearchHint({ tools, onSelect, onDismiss }: Props): React.ReactNode; + ``` + - 使用 `PermissionDialog`（从 `src/components/permissions/PermissionDialog.js`）作为外层容器，title 设为 `"Tool Recommendation"` + - 使用 `Select`（从 `src/components/CustomSelect/select.js`）渲染可选工具列表，每个选项格式为: `<工具名> — <描述截断至 60 字符> (score: 0.XX)` + - 额外增加一个 "Dismiss" 选项（value: `'dismiss'`），排在选项列表末尾 + - `onSelect` 回调: 当用户选中某个工具时调用 `onDismiss()` 清除推荐，并调用 `onSelect(toolName)` 将工具名传递给 REPL 层追加到用户消息上下文 + - 30 秒自动 dismiss（复用 `PluginHintMenu` 的 `AUTO_DISMISS_MS = 30_000` 模式），通过 `setTimeout` + `useRef` 实现，超时调用 `onDismiss()` + - `useEffect` 清理函数中 `clearTimeout` 防止内存泄漏 + - 原因: 遵循现有 UI 提示集成模式（PluginHintMenu），保证交互风格一致 + +- [x] 新建 `src/hooks/useToolSearchHint.ts` — 自定义 Hook，管理工具推荐状态与生命周期 + - 位置: 新建文件，参照 `src/hooks/useClaudeCodeHintRecommendation.tsx` 的状态管理模式 + - Hook 签名: + ```typescript + type ToolSearchHintResult = { + tools: ToolSearchHintItem[]; + visible: boolean; + handleSelect: (toolName: string) => void; + handleDismiss: () => void; + }; + export function useToolSearchHint(): ToolSearchHintResult; + ``` + - 内部使用 `React.useSyncExternalStore` 订阅预取结果（从 Task 6 的 `src/services/toolSearch/prefetch.ts` 中导出的模块级缓存），subscribe 函数和 getSnapshot 函数从 prefetch 模块获取 + - `tools` 字段: 从预取结果中提取前 3 个工具，每个工具包含 `name`、`description`（截断至 60 字符）、`score` + - `visible` 字段: 当 `tools` 非空且最高 score >= 0.15 时为 true + - `handleSelect`: 记录用户选择（analytics 事件 `tengu_tool_search_hint_select`），然后清除推荐状态 + - `handleDismiss`: 记录 dismiss 事件（analytics 事件 `tengu_tool_search_hint_dismiss`），清除推荐状态 + - 清除推荐状态时调用 prefetch 模块的清除函数（`clearToolSearchPrefetchResults()`，由 Task 6 提供） + - 原因: 将状态管理与 UI 渲染解耦，遵循现有 hook 模式（useClaudeCodeHintRecommendation） + +- [x] 修改 `src/screens/REPL.tsx` — 集成 ToolSearchHint 组件到对话框优先级系统 + - 位置: `getFocusedInputDialog()` 函数（~L2377），在返回类型联合中新增 `'tool-search-hint'` + - 在 `getFocusedInputDialog()` 函数体中，在 `plugin-hint` 判断（~L2446）之后、`desktop-upsell` 判断（~L2449）之前，新增一个优先级分支: + ```typescript + if (allowDialogsWithAnimation && toolSearchHint.visible) return 'tool-search-hint'; + ``` + - 位置: 文件顶部 import 区域（~L448，`PluginHintMenu` import 附近），新增 import: + ```typescript + import { ToolSearchHint } from '../components/ToolSearchHint.js'; + import { useToolSearchHint } from '../hooks/useToolSearchHint.js'; + ``` + - 位置: hook 调用区域（~L1038，`useClaudeCodeHintRecommendation` 调用之后），新增: + ```typescript + const toolSearchHint = useToolSearchHint(); + ``` + - 位置: JSX 渲染区域（~L6174，`PluginHintMenu` 渲染块之后），新增条件渲染块: + ```tsx + {focusedInputDialog === 'tool-search-hint' && toolSearchHint.visible && ( + + )} + ``` + - 原因: 遵循 REPL 的 focusedInputDialog 优先级系统，确保工具推荐提示在合适的时机显示，不阻塞高优先级对话框 + +- [x] 为 `ToolSearchHint` 组件和 `useToolSearchHint` hook 编写单元测试 + - 测试文件: `src/components/__tests__/ToolSearchHint.test.ts` + - 测试场景: + - 当 `tools` 数组为空时，`useToolSearchHint` 返回 `visible: false` + - 当 `tools` 数组非空且最高 score >= 0.15 时，`useToolSearchHint` 返回 `visible: true` 且 `tools` 包含最多 3 个条目 + - 当最高 score < 0.15 时，`useToolSearchHint` 返回 `visible: false` + - `handleDismiss` 调用后推荐状态被清除 + - `handleSelect` 调用后推荐状态被清除且回调被触发 + - 使用 `bun:test` 框架（与项目现有测试一致） + - 运行命令: `bun test src/components/__tests__/ToolSearchHint.test.ts` + - 预期: 所有测试通过 + +**检查步骤:** +- [x] 验证新文件已创建且导出正确 + - `grep -c "export function ToolSearchHint" src/components/ToolSearchHint.tsx && grep -c "export function useToolSearchHint" src/hooks/useToolSearchHint.ts` + - 预期: 两个 grep 均返回 1 +- [x] 验证 REPL.tsx 集成正确 + - `grep -c "ToolSearchHint" src/screens/REPL.tsx && grep -c "tool-search-hint" src/screens/REPL.tsx` + - 预期: 两个 grep 均返回值 >= 2（import + hook + 渲染 + 优先级判断） +- [x] 验证 TypeScript 编译无错误 + - `npx tsc --noEmit --pretty 2>&1 | grep -E "ToolSearchHint|useToolSearchHint" | head -5` + - 预期: 无输出（无相关类型错误） +- [x] 验证单元测试通过 + - `bun test src/components/__tests__/ToolSearchHint.test.ts` + - 预期: 所有测试通过，无失败 +--- + +--- + +### Task 8: 全功能验收 + +**前置条件:** +- Plan 1（Task 1-4）和 Plan 2（Task 5-7）全部完成 +- `bun run build` 可用 + +**端到端验证:** + +1. 运行完整测试套件确保无回归 + - `bun test 2>&1 | tail -20` + - 预期: 全部测试通过（包含 Plan 1 和 Plan 2 新增的所有测试文件） + - 失败排查: 检查对应 Task 的测试步骤，确认 mock 配置和 import 路径 + +2. 运行 precheck 确保 typecheck + lint + test 全部通过 + - `bun run precheck 2>&1 | tail -20` + - 预期: 零错误通过 + - 失败排查: 类型错误检查 import 路径；lint 错误检查格式；测试失败检查对应 Task + +3. 验证系统提示词引导文本正确注入 + - `bun run dev -- --dump-system-prompt 2>&1 | grep -A5 "ToolSearch"` + - 预期: 输出包含 "use ToolSearch to discover" 引导文本 + - 失败排查: 检查 Task 5 的 prompts.ts 修改 + +4. 验证 ExecuteTool 在工具列表中可见 + - `bun run dev -- --dump-system-prompt 2>&1 | grep "ExecuteTool"` + - 预期: 输出包含 ExecuteTool 工具定义 + - 失败排查: 检查 Task 5 的 tools.ts 注册 + +5. 验证构建产物正确 + - `bun run build 2>&1 | tail -5` + - 预期: 构建成功，输出 dist/cli.js + - 失败排查: 检查新增文件的 import 是否兼容 Bun.build splitting + +6. 验证延迟工具数量正确 + - `grep -c "isDeferredTool" src/utils/toolSearch.ts src/services/api/claude.ts packages/builtin-tools/src/tools/ToolSearchTool/ToolSearchTool.ts 2>/dev/null` + - 预期: 所有调用点仍在使用 isDeferredTool（已被 Task 1 重构为白名单制） + - 失败排查: 检查 Task 1 的 isDeferredTool 重构 diff --git a/src/components/ToolSearchHint.tsx b/src/components/ToolSearchHint.tsx new file mode 100644 index 0000000000..3c70292df1 --- /dev/null +++ b/src/components/ToolSearchHint.tsx @@ -0,0 +1,53 @@ +import * as React from 'react'; +import { Box, Text } from '@anthropic/ink'; +import { Select } from './CustomSelect/select.js'; +import { PermissionDialog } from './permissions/PermissionDialog.js'; + +type ToolSearchHintItem = { + name: string; + description: string; + score: number; +}; + +type Props = { + tools: ToolSearchHintItem[]; + onSelect: (toolName: string) => void; + onDismiss: () => void; +}; + +const AUTO_DISMISS_MS = 30_000; + +export function ToolSearchHint({ tools, onSelect, onDismiss }: Props): React.ReactNode { + const onSelectRef = React.useRef(onSelect); + const onDismissRef = React.useRef(onDismiss); + onSelectRef.current = onSelect; + onDismissRef.current = onDismiss; + + React.useEffect(() => { + const timeoutId = setTimeout(ref => ref.current(), AUTO_DISMISS_MS, onDismissRef); + return () => clearTimeout(timeoutId); + }, []); + + const options = tools.map(t => ({ + label: `${t.name} — ${t.description.slice(0, 60)} (score: ${t.score.toFixed(2)})`, + value: t.name, + })); + + options.push({ label: 'Dismiss', value: '__dismiss__' }); + + return ( + +