# fastroute

本地 MCP 插件：agent 接到新任务时，从本地已安装的全部 skill（用户级/插件级/项目级）中检索 Top-N 推荐。只推荐不执行。

索引方法来自 SkillRouter（arXiv 2603.22455）：all-field 分段多向量（name+description 一个向量 + 正文 ~800 字符切块各一个向量），查询对每块算余弦、skill 得分取 max-pool。

## 工具

| 工具 | 用途 |
|---|---|
| `recommend_skills` | 任务开始前检索最相关 skill；返回 score、tier（auto/prompt/skip，参考值）、调用名与路径 |
| `reindex_skills` | 安装/删除 skill 后增量重建索引（mtime diff），无需重启会话 |

## 安装（Claude Code）

```bash
claude mcp add fastroute -- node /absolute/path/to/fastroute/dist/index.js
```

## 数据与模型

- 数据目录 `~/.fastroute`（`FASTROUTE_DATA_DIR` 覆盖）：`fastroute.db`、`config.json`、`models/`
- embedding 模型：`Xenova/paraphrase-multilingual-MiniLM-L12-v2`（q8，约 135MB），首次调用工具时联网下载，默认 ModelScope 镜像（`FASTROUTE_EMBEDDING_HOST` 可指回 `https://huggingface.co`）；已有 `~/.knowyoubetter/models` 缓存时直接复用
- **模型是硬依赖**：离线且无缓存时工具返回错误与下载指引，无词法降级
- config.json 可覆盖：`chunkSize`(800)、`autoThreshold`(0.9)、`promptThreshold`(0.6)、`topK`(5)、`userSkillsDir`、`pluginCacheDir`、`projectSkillsEnabled`
- 修改 `chunkSize` 后已有索引不会自动重切：需删除 `~/.fastroute/fastroute.db` 再调用 `reindex_skills`

## 开发

```bash
npm install
npm test            # 单测 + 集成（fake embedder，不联网）
npm run test:real   # 真实 embedding 冒烟（首次下载模型）
npm run eval        # distractor 评测：Hit@1/Hit@5/MRR
npm run build
npx @modelcontextprotocol/inspector node dist/index.js
```