103 lines
4.3 KiB
Markdown
103 lines
4.3 KiB
Markdown
---
|
||
tags: [skill-search, 语义搜索, 技能发现, feature-flag]
|
||
create time: 2026-06-09 22:30
|
||
---
|
||
|
||
# EXPERIMENTAL_SKILL_SEARCH — 技能语义搜索
|
||
|
||
## 概述
|
||
|
||
EXPERIMENTAL_SKILL_SEARCH 提供 DiscoverSkills 工具，根据当前任务语义搜索可用技能。目标是让模型在执行任务时自动发现和推荐相关的技能（包括本地和远程），无需用户手动查找。
|
||
|
||
> [!info]
|
||
> Feature Flag: `FEATURE_EXPERIMENTAL_SKILL_SEARCH=1`
|
||
> 实现状态：全部 Stub（8 个文件），布线完整
|
||
|
||
## 正文
|
||
|
||
### 实现架构
|
||
|
||
#### 模块状态
|
||
|
||
| 模块 | 文件 | 状态 | 说明 |
|
||
|------|------|------|------|
|
||
| DiscoverSkillsTool | `src/tools/DiscoverSkillsTool/prompt.ts` | **Stub** | 空工具名 |
|
||
| 预取 | `src/services/skillSearch/prefetch.ts` | **Stub** | 3 个函数全部空操作 |
|
||
| 远程加载 | `src/services/skillSearch/remoteSkillLoader.ts` | **Stub** | 返回空结果 |
|
||
| 远程状态 | `src/services/skillSearch/remoteSkillState.ts` | **Stub** | 返回 null/undefined |
|
||
| 信号 | `src/services/skillSearch/signals.ts` | **Stub** | `DiscoverySignal = any` |
|
||
| 遥测 | `src/services/skillSearch/telemetry.ts` | **Stub** | 空操作日志 |
|
||
| 本地搜索 | `src/services/skillSearch/localSearch.ts` | **Stub** | 空操作缓存 |
|
||
| 功能检查 | `src/services/skillSearch/featureCheck.ts` | **Stub** | `isSkillSearchEnabled => false` |
|
||
| SkillTool 集成 | `src/tools/SkillTool/SkillTool.ts` | **布线** | 动态加载所有远程技能模块 |
|
||
| 提示集成 | `src/constants/prompts.ts` | **布线** | DiscoverSkills schema 注入 |
|
||
|
||
#### 预期数据流
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["模型处理用户任务"] --> B{"DiscoverSkills 工具触发 需要实现"}
|
||
B --> C["本地搜索: 索引已安装技能元数据"]
|
||
C --> D["localSearch.ts -> 技能名称/描述/关键字匹配"]
|
||
B --> E["远程搜索: 查询技能市场/注册表"]
|
||
E --> F["remoteSkillLoader.ts -> fetch + 解析"]
|
||
D --> G["结果排序和过滤"]
|
||
F --> G
|
||
G --> H["返回推荐技能列表"]
|
||
H --> I["模型使用 SkillTool 调用推荐技能"]
|
||
```
|
||
|
||
#### 预取机制
|
||
|
||
`prefetch.ts` 预期在用户提交输入前分析消息内容，提前搜索相关技能：
|
||
|
||
- `startSkillDiscoveryPrefetch()` — 开始预取
|
||
- `collectSkillDiscoveryPrefetch()` — 收集预取结果
|
||
- `getTurnZeroSkillDiscovery()` — 获取 turn 0 的技能发现结果
|
||
|
||
### 需要补全的内容
|
||
|
||
| 优先级 | 模块 | 工作量 | 说明 |
|
||
|--------|------|--------|------|
|
||
| 1 | `DiscoverSkillsTool` | 大 | 语义搜索工具 schema + 执行 |
|
||
| 2 | `skillSearch/prefetch.ts` | 中 | 用户输入分析和预取逻辑 |
|
||
| 3 | `skillSearch/remoteSkillLoader.ts` | 大 | 远程市场/注册表获取 |
|
||
| 4 | `skillSearch/remoteSkillState.ts` | 小 | 已发现技能状态管理 |
|
||
| 5 | `skillSearch/localSearch.ts` | 中 | 本地索引构建/查询 |
|
||
| 6 | `skillSearch/featureCheck.ts` | 小 | GrowthBook/配置门控 |
|
||
| 7 | `skillSearch/signals.ts` | 小 | `DiscoverySignal` 类型定义 |
|
||
|
||
### 关键设计决策
|
||
|
||
1. **预取优化**：在用户提交前就开始搜索，减少首次响应延迟
|
||
2. **本地+远程双搜索**：本地索引快速匹配 + 远程市场深度搜索
|
||
3. **SkillTool 集成**：发现的技能通过 SkillTool 调用，不需要新的调用机制
|
||
4. **独立于 MCP_SKILLS**：MCP_SKILLS 从 MCP 服务器发现，EXPERIMENTAL_SKILL_SEARCH 从技能市场发现
|
||
|
||
### 使用方式
|
||
|
||
```bash
|
||
# 启用 feature（需要补全后才能真正使用）
|
||
FEATURE_EXPERIMENTAL_SKILL_SEARCH=1 bun run dev
|
||
```
|
||
|
||
### 文件索引
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `src/tools/DiscoverSkillsTool/prompt.ts` | 工具 schema（stub） |
|
||
| `src/services/skillSearch/prefetch.ts` | 预取逻辑（stub） |
|
||
| `src/services/skillSearch/remoteSkillLoader.ts` | 远程加载（stub） |
|
||
| `src/services/skillSearch/remoteSkillState.ts` | 远程状态（stub） |
|
||
| `src/services/skillSearch/signals.ts` | 信号类型（stub） |
|
||
| `src/services/skillSearch/telemetry.ts` | 遥测（stub） |
|
||
| `src/services/skillSearch/localSearch.ts` | 本地搜索（stub） |
|
||
| `src/services/skillSearch/featureCheck.ts` | 功能检查（stub） |
|
||
| `src/tools/SkillTool/SkillTool.ts` | SkillTool 集成点 |
|
||
| `src/constants/prompts.ts:95,335,778` | 提示增强 |
|
||
|
||
## 关联笔记
|
||
|
||
- [[claude-code-best/docs/features/mcp-skills]]
|
||
- [[claude-code-best/docs/features/extensibility/skills]]
|