内容
# 技能路由器
适用于 **Claude 代码** 和 **Claude 桌面版** 的静默、最小上下文 **技能路由器**。
每个提示都被拦截，**技能路由器** 确定所需的 **技能** —— 请求所需的最低技能集 —— 除非你询问 *"如何确定技能？"*，否则该技能集对模型不可见。
> **技能路由器所需的技能**。技能路由器是**唯一**决定请求需要哪些技能的组件。下游的所有组件（钩子注入、MCP 工具、模型）都使用路由器的 **所需技能** —— 没有重新选择或重新排序技能的独立操作。这样可以在保持正确性的同时，将上下文保持最小（1-3 个技能，仅名称）。
跨平台（macOS · Windows · Linux）。一个运行时依赖项（`@modelcontextprotocol/sdk`）；路由核心没有任何依赖项。
- **它如何决定 / 内部机制：** [`ARCHITECTURE.md`](./ARCHITECTURE.md)
- **为什么使用钩子和 MCP（而不仅仅使用 MCP）：** 纯 MCP 服务器无法拦截提示 —— 只有 `UserPromptSubmit` 钩子在每个提示时运行。因此，我们同时提供了这两个功能。
---
## 一键安装
**npx（所有平台 - 推荐）：**
```bash
npx @akbuilds/skillfish-router install
```
就这样 —— 无需克隆，无需全局安装。你也可以全局安装：
```bash
npm install -g @akbuilds/skillfish-router && skillfish-router install
```
或者，从下载的版本中：双击 **`install.command`**（macOS）或 **`install.bat`**（Windows）；在 Linux 上运行 **`bash installers/install.sh`**。
`install` 命令：
1. 检测 Claude 代码和 Claude 桌面版。
2. **备份** 您的 Claude 配置（原子写入；失败时回滚）。
3. 将无依赖项的钩子/守护进程运行时复制到稳定的 `~/.skillfish/runtime` 并安装指向该位置的 `UserPromptSubmit` 钩子（因此它在 npx 缓存清除和升级后仍然存在）。
4. 将 MCP 服务器注册为 `npx -y @akbuilds/skillfish-router@<ver> mcp`，适用于 Claude 代码和（如果存在）Claude 桌面版 —— 现代 MCP 约定。
5. 索引已安装的 Skillfish 技能。
6. 运行最终的健康检查（`doctor`）。
幂等 —— 随时重新运行；它会收敛到恰好一个钩子和一个 MCP 条目。使用以下命令验证：
```bash
npx @akbuilds/skillfish-router doctor
```
---
## 命令行界面
使用 `npx @akbuilds/skillfish-router <command>`（或全局安装后直接使用 `skillfish-router <command>`）运行任何命令：
```
install 安装钩子 + 注册 MCP 服务器
uninstall 删除所有添加的内容，恢复以前的配置
update 升级软件包，然后重新应用配置
doctor 诊断运行时、构建、实时服务器和线路
status 当前安装的简洁快照
rebuild-index 强制重建能力索引
mcp 通过 stdio 运行 MCP 服务器（Claude 通过 npx 启动）
version 打印版本号
全局： --dry-run --json --yes/-y --help/-h --version/-V
install: --no-hook --no-mcp --no-desktop --code-only --desktop-only --force-desktop
uninstall:--restore-backup --purge
update: --local
```
`--dry-run` 打印每个更改而无需写入任何字节 —— 安全地尝试。`mcp` 由 Claude 调用，而不是您。
---
## 卸载
```bash
npx @akbuilds/skillfish-router uninstall # 精确：仅删除添加的内容
npx @akbuilds/skillfish-router uninstall --restore-backup # 字节到字节恢复备份
npx @akbuilds/skillfish-router uninstall --purge # 还要删除 ~/.skillfish（运行时 + 备份）
```
默认的精确卸载保留您可能拥有的任何其他钩子或 MCP 服务器。备份存储在 `~/.skillfish/backups/`（或 `%USERPROFILE%\.skillfish\backups\`）。
---
## 对您的配置的影响
| 目标 | 文件 | 更改 |
| --- | --- | --- |
| Claude 代码（钩子） | `~/.claude/settings.json` | 一个 `UserPromptSubmit` 钩子 → `node "~/.skillfish/runtime/…/user-prompt-submit.js"` |
| Claude 代码（MCP） | `~/.claude.json` | `mcpServers["skillfish-router"]` = `npx -y @akbuilds/skillfish-router@<ver> mcp` |
| Claude 桌面版（MCP） | 平台配置¹ | `mcpServers["skillfish-router"]` = `npx -y @akbuilds/skillfish-router@<ver> mcp` |
¹ macOS `~/Library/Application Support/Claude/claude_desktop_config.json` ·
Windows `%APPDATA%\Claude\claude_desktop_config.json` ·
Linux `~/.config/Claude/claude_desktop_config.json`.
所有写入都是原子的（临时 + 重命名），并在之前进行完整的备份。没有任何内容是硬编码的；每个路径都源自 `os.homedir()` 和平台约定，并且所有路径都可以通过环境变量覆盖（CI 使用它来隔离整个流程）。
---
## 故障排除
**安装后出现 `skillfish-router: command not found`。**
npm 全局二进制目录不在您的 PATH 中。使用 `npm bin -g`（或 `npm prefix -g`）找到它并将其添加到 PATH。在 Windows 上，请打开新的终端以刷新 PATH。
**`doctor` 显示“PATH 上的 node”为警告。**
Claude 通过 `node` 启动钩子/MCP。如果您的 shell 无法非交互式地找到 `node`，请全局安装 Node 或确保您的 shell 配置文件导出它。路由器在从具有 `node` 的 shell 启动时仍然有效。
**`doctor` 显示“MCP 服务器启动：探测失败”。**
缺少或损坏的构建。请重新运行 `npx @akbuilds/skillfish-router install`（或 `… update`），然后再次运行 `… doctor`。
**Claude 代码似乎没有路由。**
钩子在会话启动时加载 —— 在安装后完全重启 Claude 代码。使用 `skillfish-router status`（hook=yes, mcp=yes）确认线路。
**Claude 桌面版未显示服务器。**
重启 Claude 桌面版后安装 —— 它在启动时读取其配置。
**“Claude 桌面版未检测到 - 跳过。”**
其应用数据文件夹尚不存在。请安装/启动 Claude 桌面版一次，然后重新运行 `skillfish-router install`，或使用 `--force-desktop` 强制执行。
**配置文件解析失败。**
安装程序拒绝覆盖无法解析的配置（以避免数据丢失）。修复报告的文件中的 JSON 语法，然后重新运行。
**完全撤销所有更改。**
`skillfish-router uninstall --restore-backup` 从安装时的备份恢复每个 touched 文件（或删除安装程序创建的文件）。
**PowerShell 阻止脚本。**
使用提供的 `install.bat`，或运行 `powershell -ExecutionPolicy Bypass -File installers\install.ps1`。
**企业 / 非标准配置位置。**
设置 `CLAUDE_CONFIG_DIR`, `SKILLFISH_CODE_SETTINGS`, `SKILLFISH_CODE_MCP_CONFIG`, `SKILLFISH_DESKTOP_CONFIG`, 或 `SKILLFISH_HOME` 以指向自定义路径。
---
## 开发
```bash
git clone … && cd skillfish-router
npm install
npm run build # 生成 dist/
npm test # 单元测试
npm run smoke # 跨平台安装/卸载烟雾测试
npm run audit # F1–F4 回归 + 并发/生命周期（16 个场景）
npm run e2e # tarball → MCP → 守护进程 → 所需技能 → 恢复（13 步）
npm run route -- --explain "制作 30 秒的解说视频" # 尝试路由器
```
CI（`[.github/workflows/ci.yml](./.github/workflows/ci.yml)`）运行类型检查、测试、烟雾测试、审计和端到端测试，涵盖 macOS/Windows/Linux × Node 18/20/22，在每个操作系统上执行真正的安装程序脚本，并验证发布的 tarball 可以安装和运行于干净的环境中。
## 发布
软件包是一个 **公共作用域** 软件包（`@akbuilds/skillfish-router`, `publishConfig.access = "public"`）。`prepack`/`prepublishOnly` 重建 `dist/`，并且 `files` 只会发送 `dist/ bin/ installers/` + 文档（不包括 `src/`、测试或开发依赖项）。
**手动发布：**
```bash
npm login # 一次，作为 akcodes9 npm 账户
npm publish --dry-run # 检查 tarball（名称、文件、“公共访问”）
npm publish --access public # 或 --provenance 来自 CI（见下文）
```
然后任何人都可以安装 `npx @akbuilds/skillfish-router install`.
**自动（推荐）- 标记驱动的语义版本控制：**
```bash
npm version patch # 升级 package.json + 提交 + 标签 vX.Y.Z
git push --follow-tags
```
[`.github/workflows/release.yml](./.github/workflows/release.yml)` 然后保护标签与 `package.json` 匹配，运行完整的 3-OS × Node-18/20/22 矩阵（包括 e2e），**发布到 npm 具有出处** (`npm publish --provenance --access public`)，并用每个平台的工件和 `SHA256SUMS.txt` 清单切割 GitHub 版本。需要一个 `NPM_TOKEN` 仓库秘密；出处使用工作流的 OIDC 身份。
## 许可证
MIT - 请参阅 [`LICENSE`](./LICENSE)。
