# SkillRouter 调研报告

**版本**: v1.0  
**作者**: 庞统（副军师）🐦  
**日期**: 2026-05-16  
**源码位置**: `/Volumes/stock/knowledge_base/SkillRouter/`  
**论文**: arXiv:2603.22455 (2026)  

---

## 1. SkillRouter 是什么

SkillRouter 是一个**两阶段检索+重排序**系统，解决"给一个用户任务，从几万个 Skill 中找到最相关的那一个"的问题。

**规模**：在 ~80K 开源 Skill 池上评估，74.0% Top-1 准确率。模型仅 0.6B 参数，可跑在消费级硬件上。

## 2. 核心发现

### 2.1 Skill Body 是决定性信号

**论文最核心的发现**：只看 Skill 的 name + description（元数据）远远不够。

| 对比 | 准确率下降 |
|------|-----------|
| 隐藏 Skill body（只留 name+desc） | **31-44 百分点下降** |
| Cross-encoder 注意力分析 | **91.7% 的注意力集中在 body 字段** |

**结论**：Skill 的实现文本（body）是路由的决定性信号，不是元数据。

### 2.2 两阶段管线架构

```
用户任务描述
     ↓
[Stage 1: Embedding Retrieval]
  0.6B encoder → 离线预嵌入所有 Skill → cosine similarity → Top-50 候选
     ↓
[Stage 2: Reranker]
  0.6B cross-encoder → 对 Top-50 候选逐个打分 → Top-1 最终结果
     ↓
最相关的 Skill
```

**Stage 1（检索）**：
- 模型：SkillRouter-Embedding-0.6B
- Skill 离线预嵌入，存向量
- 运行时只需编码 query（一次 forward pass）+ 近邻搜索
- 输出 Top-50 候选

**Stage 2（重排序）**：
- 模型：SkillRouter-Reranker-0.6B
- 对 Top-50 候选用 cross-encoder 精排
- 输入：query + skill_full_text（name + desc + body）
- 输出：yes/no 相关性判断

### 2.3 技术细节

| 方面 | 实现 |
|------|------|
| **Skill 格式化** | `"{name} \| {desc} \| {body}"` — body 最多 8000 字符 |
| **Query 格式化** | `"Instruct: Given a coding task... Query: {task}"` |
| **编码方式** | last_token_pool + L2 normalize → cosine similarity |
| **Rerank prompt** | flat-full: `"<Instruct>: ... <Query>: ... <Document>: {name} \| {desc} \| {body}"` |
| **Rerank 判断** | Qwen2.5 风格 chat template → 输出 yes/no |
| **硬件** | 单 GPU，消费级即可 |
| **依赖** | PyTorch + Transformers，无外部基础设施 |

## 3. 和 moziplus 的对接分析

### 3.1 我们的规模

| 维度 | SkillRouter 评估 | moziplus 实际 |
|------|-----------------|-------------|
| Skill 池大小 | ~80K | ~30-50 个 |
| 评估准确率 | 74.0% Top-1 | — |
| 硬件要求 | 单 GPU | Mac mini (M系列) |

**关键洞察**：SkillRouter 是为 ~80K Skill 池设计的。我们只有 30-50 个 Skill。在这个规模下：
- Stage 1（向量检索）可能杀鸡用牛刀——30 个 Skill 的相似度计算用 SQLite FTS5 或简单关键词匹配就够了
- Stage 2（重排序）的核心发现（body 是关键信号）对我们有价值——说明 Skill description 四要素（课题4 D4-8）确实重要

### 3.2 三层组合方案

用户提出的组合：**SkillRouter + OpenClaw 动态关键词 + L2 注入兜底**

```
┌─────────────────────────────────────────────────────────────┐
│ Layer 1: SkillRouter 检索（精准匹配）                        │
│   输入: 任务描述（来自黑板 task description）                  │
│   过程: 任务描述 → SkillRouter → Top-3 相关 Skill            │
│   输出: 精准匹配的 Skill 列表                                │
│   适用: Skill 数量 > 50 时启动，< 50 时用关键词匹配即可       │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: OpenClaw 动态关键词（触发加载）                      │
│   机制: Skill description 四要素（When to use + triggers）    │
│   过程: Agent 读到匹配的关键词 → 主动 read SKILL.md          │
│   适用: 当前已优化（课题4 D4-8）                              │
├─────────────────────────────────────────────────────────────┤
│ Layer 3: L2 引擎注入（兜底保障）                              │
│   机制: prompt_templates/ 中写死关键操作步骤                  │
│   保证: 核心操作不依赖任何触发机制                             │
│   适用: 已设计（课题4 D4-6/D4-7）                             │
└─────────────────────────────────────────────────────────────┘
```

### 3.3 对接方案

**阶段判断**：

| Skill 数量 | 推荐方案 | 理由 |
|-----------|---------|------|
| < 50 | 关键词匹配（当前）+ L2 注入兜底 | 30 个 Skill 全量列表注入 system prompt 也才 ~1000 token |
| 50-200 | FTS5 全文检索 | SQLite 原生支持，不需要 ML 模型 |
| 200+ | SkillRouter | 这个规模下 SkillRouter 的优势才体现 |

**当前决策**：不部署 SkillRouter，继续用关键词匹配 + L2 注入。原因：
1. 当前 Skill 数量 < 50，全量注入 system prompt 即可
2. SkillRouter 需要 GPU 推理（0.6B 模型），Mac mini CPU 跑起来延迟较高
3. 核心 Skill 的操作规范已经在 L2 prompt_templates 中写死，不依赖被动触发

**未来触发条件**（何时引入 SkillRouter）：
- Skill 数量超过 100 个
- 或者引入社区 Skill 生态（如 clawhub / awesome-llm-skills）
- 届时 SkillRouter 的 0.6B 模型可以在 NAS Docker（有 GPU 的 Windows Node）上跑

### 3.4 SkillRouter 的经验对我们的价值

即使不部署，SkillRouter 的核心发现指导我们写好 Skill：

| SkillRouter 发现 | 我们的行动 |
|-----------------|----------|
| **Skill body 是关键信号**（91.7% 注意力） | Skill description 要写具体（不只是标题），四要素中 "When to use" 和示例对话是 body 级别的信息 |
| **元数据不够**（name+desc 下降 31-44pp） | 不能只写简短 description，要写完整的触发场景和操作步骤 |
| **cross-encoder 比向量检索更准** | 关键词精确匹配（OpenClaw 已有）比语义搜索更可靠——在小规模下 |

## 4. 结论

1. **SkillRouter 源码已下载**：`/Volumes/stock/knowledge_base/SkillRouter/`
2. **SkillRouter 的经验指导 Skill 写法**：body 内容是关键，description 要具体
3. **三层组合方案**：
   - L3 关键词触发（当前，已优化）
   - L2 引擎注入（课题4）→ 核心兜底
   - SkillRouter（未来）→ 规模化时引入

> **⏳ 待进一步探讨**：用户要求继续探讨 SkillRouter 的应用可能性（轻量化方案），不关闭此选项。