diff --git a/docs/research/v2.6-research-06-skillrouter.md b/docs/research/v2.6-research-06-skillrouter.md new file mode 100644 index 0000000..31ef052 --- /dev/null +++ b/docs/research/v2.6-research-06-skillrouter.md @@ -0,0 +1,145 @@ +# 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: `": ... : ... : {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. **当前不部署**:Skill 数量 < 50,关键词匹配 + L2 注入兜底足够 +3. **SkillRouter 的经验指导 Skill 写法**:body 内容是关键,description 要具体 +4. **预留接口**:当 Skill 数量超过 100 时,引入 SkillRouter 的两阶段管线 +5. **三层组合最终方案**: + - L3 关键词触发(当前,已优化)→ 够用 + - L2 引擎注入(课题4)→ 核心兜底 + - SkillRouter(未来)→ 规模化时引入