mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-15 12:55:51 +00:00
feat: 实现 Tool Search 基础设施层（CORE_TOOLS 白名单 + TF-IDF 索引 + ExecuteTool + 搜索增强）
- 新增 CORE_TOOLS 白名单常量（31 个核心工具），重构 isDeferredTool 为白名单制判定 - 新建 TF-IDF 工具索引模块（toolIndex.ts），复用 localSearch.ts 算法函数 - 新建 ExecuteTool 跨 API provider 统一工具执行入口 - 增强 ToolSearchTool：TF-IDF 搜索路径、discover: 模式、并行搜索合并、文本模式回退 - 新增 27 个单元测试，precheck 零错误通过（4108 tests pass） Co-Authored-By: glm-5.1[1m] <zai-org@claude-code-best.win>
This commit is contained in:
claude-code-best
451
spec/feature_20260508_F001_tool-search/spec-design.md
Normal file
451
spec/feature_20260508_F001_tool-search/spec-design.md
Normal file
@@ -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 正常注入。延迟工具仅注入名称列表到 `<available-deferred-tools>` 或 `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<string, number> // 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 或 <available-tools-hint>
|
||||
└── 无结果 → 不做任何附加
|
||||
```
|
||||
|
||||
**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 执行
|
||||
262
spec/feature_20260508_F001_tool-search/spec-human-verify.md
Normal file
262
spec/feature_20260508_F001_tool-search/spec-human-verify.md
Normal file
@@ -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 | ✅ |
|
||||
|
||||
**验收结论:** ✅ 全部通过
|
||||
650
spec/feature_20260508_F001_tool-search/spec-plan-1.md
Normal file
650
spec/feature_20260508_F001_tool-search/spec-plan-1.md
Normal file
@@ -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<string>
|
||||
```
|
||||
- 说明: `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<string, number>
|
||||
}
|
||||
```
|
||||
- 定义字段权重常量（参照 `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<ToolIndexEntry[]>`
|
||||
- 导入依赖：从 `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<ToolIndexEntry[]>`
|
||||
- 缓存 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<Tool>` 类型的 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<InputSchema, OutputSchema>`
|
||||
- 关键属性:
|
||||
- `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<string, number>()
|
||||
// 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
|
||||
587
spec/feature_20260508_F001_tool-search/spec-plan-2.md
Normal file
587
spec/feature_20260508_F001_tool-search/spec-plan-2.md
Normal file
@@ -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<Attachment[]>
|
||||
```
|
||||
- 核心逻辑（参照 `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<string>`，与 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<Attachment | null>
|
||||
```
|
||||
- 核心逻辑（参照 `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<Attachment[]>,
|
||||
): Promise<Attachment[]>
|
||||
```
|
||||
- 核心逻辑（与 `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<Tool>` 类型的 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 && (
|
||||
<ToolSearchHint
|
||||
tools={toolSearchHint.tools}
|
||||
onSelect={toolSearchHint.handleSelect}
|
||||
onDismiss={toolSearchHint.handleDismiss}
|
||||
/>
|
||||
)}
|
||||
```
|
||||
- 原因: 遵循 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 重构
|
||||
Reference in New Issue
Block a user