Skip to main content
Glama
Dynamic Skill Router MCP Server

Dynamic Skill Router MCP Server

README.md
# Dynamic Skill Router

面向 AI 编程工具的本地技能与能力路由器。面对一个任务,它先区分当前请求、未来想法和明确限制,再把相关 Skill、插件或 MCP 工具整理成咨询卡,供宿主决定是否查阅或采用。

它提供 CLI 与 stdio MCP 两个入口,也支持在同一 `routeId` 下继续按阶段检索。路由结果不会自行操作外部工具或扩大用户授权。

![源码架构示意](docs/architecture.svg)

> 图按本项目实际模块生成,是架构示意,不是运行界面截图。

## 安装到自己的 Codex

将[这段简短安装提示词](docs/install-prompt.md)交给你电脑上的 Codex,即可让它按照[完整安装与验收指南](docs/codex-install.md)处理代码、依赖、MCP、Skill 和全局工作规则。路由服务统一叫 `dynamic_skill_router`,使用与你安装版本相同的完整路由核心;Skill、MCP、插件来自你自己的电脑。安装不继承作者账号、工具库或私有历史,也不需要路由器专用 API Key。

指南附有[本机来源配置](examples/skill-sources.codex.json)与[通用全局规则模板](examples/codex-global-rules.md),包含“深入而不是更大”和按证据改进原则。以新会话的实际 MCP 调用和本机能力发现验收;下方“快速上手”是隔离演示,不能代替完整安装。

## 功能

- 发现配置来源中的 Skill,记录来源、重复项、失效链接、版本哈希及覆盖情况。
- V4 咨询卡区分 `skip / consult / adapt / execute`;支持显式技能名称、阶段查询和同一任务复用。
- 联合处理宿主提供的 `runtimeTools`、插件元数据和只读配置清单;配置存在不等于当前可调用。
- 简单任务可走原生快速路径;遇阻时生成可核验的恢复与资料查询建议。
- MCP 接口提供发现、读取、路由、阶段查询、协作规划及反馈记录;不执行被推荐的业务工具。

## 4.3.21 技能管理任务匹配 — 2026-11-02

改进对明确要求升级技能目录或路由器的任务匹配,并针对解释、否定及引用场景增加回归检查。候选仍是供宿主判断的建议,复杂表达的准确性不能保证。

## 4.3.20 任务产物与技能咨询 — 2026-11-02

结合当前任务的动作、产物及技能摘要中明确列出的触发短语,改善部分前端、文档、简历、视频转写与资料阅读任务的咨询;匹配到具体用途时可在相关阶段继续咨询,并优先覆盖多种任务需要。

候选仅供宿主根据完整请求、技能范围和实际权限决定;对不同阶段、条件句、产品与局部功能的限制仍可能理解有误。已知部分包含其他任务对象的技能管理升级请求可能漏选相关技能。复杂自然语言禁网仍须宿主核对并重传真实限制,路由器不是权限隔离机制。

## 4.3.19 精确工具的搜索与打开动作 — 2026-11-02

当宿主对指定工具显式禁止搜索、用户同时明确要求该工具打开给定链接时,路由器可分别建议核对其打开动作,并保留搜索禁令。工具建议不构成授权,是否联网仍由宿主按原文和当前阶段判断。

自然语言的网络限制仍可能被误判:只禁止搜索的请求可能被当作全面禁网;禁止搜索和访问任何网络、同时允许打开网址的复合请求也可能漏掉全面禁网。宿主须核对完整原文,在支持的入口传递并在阶段检索和恢复时重传真实限制;路由器不是网络隔离机制。

## 4.3.18 任务匹配与阶段搜索限制 — 2026-11-02

改进部分中文技能匹配,区分目录交付与参考资料只读。宿主可按当前阶段显式传入搜索禁令;结构化限制须重传,无法替代原文理解和实际授权检查。

## 4.3.17 任务对象与来源范围 — 2026-11-02

改进部分网页 Canvas、JSON Canvas、视频转写和资料研究的技能咨询。隐含资料研究的网页搜索推荐尚未修复。宿主可用 `invocationContext.sourceScopes` 传入多项已确认来源限制;它们只能收紧,宿主仍须判断完整原文并在各阶段重传。

## 4.3.16 全局限制识别 — 2026-11-02

补充部分明确的全任务离线和仅用给定资料说法;引用证据范围不自动等于禁止查阅背景。原文分别限定给定资料和指定网站时,宿主须核对并补传未识别的一侧,确认两个限制都得到保留。不同分部的限制仍应由宿主核对完整原文。

## 4.3.15 LaTeX 工具用途 — 2026-11-02

改进可见 LaTeX 工具的用途识别,区分编译现有文档与新建项目;仍须核对实际项目、文件、工具效果与授权。编译诊断工具不一定导出 PDF,推荐不代表已调用或成功。

## 4.3.12 离线边界 — 2026-11-02

改进部分明确离线与外网禁令的识别。MCP 的 `openWorldHint: false` 不代表工具一定离线:固定远程服务也可能只访问封闭范围。禁网时,网络效果未知的工具需由宿主核实;路由咨询并非网络隔离机制。分部分任务的不同限制仍须按原文判断。

## 4.3.11 请求边界与宿主约束 — 2026-11-02

对请求生成示例、给定资料、来源范围和保护原始输入的部分表述作更细致的区分。创建独立输出不自动意味着可以覆盖输入;多段请求中不同来源的限制,以及覆盖与追加的区别仍须宿主核对原文。

`invocationContext` 支持 `sourceScope` 和 `preserveInputs`。宿主字段只收紧用户已有的限制;同时存在给定资料和指定站点限制时,`sourceScopes` 表示两者均须满足。显式的 `allowedActions` 不包含 `network` 时,该次调用不得联网;未提供列表时不由缺省推断禁网。详见 [V4 契约](skill/dynamic-skill-router/references/router-contract-v4.md)。

补充已有提醒管理和指定论文正文段落的工具用途判断,并区分禁止分享文档和编辑文档。建议依然需要核对对象、输入、工具实际效果及授权,不代表调用或访问已经成功。

工具输入证据中增加对部分本地文件名与网站域名的区分;同一后缀也可能对应真实网站,宿主仍需核对上下文。

## 4.3.10 请求边界与能力用途

对指定来源、离线、本地输出与输入保护的部分表述作更细致的区分;对象级禁止不自动扩大为所有写入均被禁止。

对有明确动作和对象的提醒、资料检索及部分专项工具用途补充匹配,并减少少数通用字段词导致的无关建议。结果仍是有限的启发式咨询,由宿主核对输入、适用范围及授权,不自动执行工具。

## 4.3.9 任务对象与运行时身份

普通词汇可辅助检索,但不应仅凭多个泛化词重合就建议不相关的专业技能。此版本增加部分任务对象、编程语言和应用框架的匹配检查,并保留显式点名与禁止规则。

按宿主提供的运行时技能名称可解析到对应实体;同名冲突仍需明确区分,禁用或不兼容身份不会因其他来源自动变为可用。这些规则是有限的启发式判断,路由建议仍由宿主核对。

## 4.3.8 工具类别与图片编辑边界

区分搜索工具类别限制和完整禁网,并改进图片编辑、编辑必要性询问和工具用途否定的部分识别。混合工具是否适用仍需宿主依据当前任务、工具说明和授权核对;建议不会自动调用工具。

## 4.3.7 请求边界与可选反馈

改进部分精确工具禁用、离线来源限制和图片中物体移除意图的判断。建议仍由宿主核对,不自动执行工具。

显式使用 `node src/cli.mjs report-outcome --input-json` 从标准输入提交 V4 JSON,可把有证据的反馈记入本地日志;加 `--dry-run` 只校验不写入。`modelId` 仅在宿主明确提供真实值时填写;未知时记录只供审计。记录会附加当前路由器版本,只填写必要依据,不自动收录完整请求。反馈不是模型训练。

## 4.3.6 能力意图修正

对明确查询当前股票价格的请求,可提示宿主核实可用的在线来源;尊重禁网及仅用给定资料的限制。更准确地区分照片背景虚化的编辑请求与对现有效果的查看。建议不代表工具已调用、服务已认证或价格可靠。

## 4.3.5 摘要与任务相关性

对特定格式的自动生成登记摘要,优先采用手册中有效的描述;没有可用描述时标记占位,提醒宿主核对完整手册。人工整理的摘要保留。该识别针对明确格式,并非能识别所有空泛摘要。

技能相关性评估更谨慎地区分不适用场景、当前任务对象和明确禁止;继续保留独立目标与显式点名。某些包含“示例”字样的当前文件请求仍可能被截断,宿主应核对完整原文。建议不扩大授权,不能保证所有领域排序都正确。

## 4.3.4 请求理解与来源选择

4.3.4 区分文件时间等元数据的读取与修改、单独输出与保护输入,并改进具名来源、多个来源及独立任务的能力建议。CLI 在提供真实模型标识时可使用符合验证条件的反馈,`--no-feedback` 可关闭;来源和反馈均是咨询信息,不改变授权。

简单算术可使用快速路径。相关性筛选更关注任务对象及明确的 AI 指令需求;具体改进和限制须以合成测试与真实任务证据分别判断。

## 4.3.3 请求边界与候选证据

4.3.3 对中文候选增加保守的词边界证据检查,减少通用词和跨词片段单独支撑不相关建议;显式点名和已有触发规则继续保留。具体行为依赖运行环境的分词能力,仍需结合原请求判断。

本版还细化否定修改动作与独立输出的区别,并区分实际图标素材与仅需图标组件代码。工具建议仍不是实际调用或授权。

4.3.2 与 4.3.3 的公开回归中,一个自定义 Word Skill 因身份名称和分数阈值只得到 `skip`;该合成案例在 4.3.4 中恢复为正式回归。另一类 AI 工作说明改写的合成变体仍可能漏荐,详见验证记录。

## 4.3.2 请求边界修复

4.3.2 改进指定本地输入的来源范围、否定技能要求,以及当前产物与未来待做任务的区分。当时的技能评分与排序沿用4.3.1。

## 4.3.1 来源范围与恢复建议

4.3.1 改善禁网、限定来源、只读建议与额外文件输出的区分,并约束来源受限时的恢复查询;具体判断仍由宿主结合原始请求和授权完成。

## 4.3.0 请求证据与能力建议

本版为引文、代码块和附件上下文提供来源片段信息,辅助区分用户正在下达的指令与引用内容。来源边界不确定时应回看原文;这些规则不是完整语言理解,也不能代替授权判断。

约束分别描述只读、禁网、资料来源范围和保护输入;能力候选可说明匹配的任务意图和已有输入。用户提供的链接不因“仅用所给资料”而自动被禁止访问,保护输入也不自动禁止创建用户要求的独立输出。

工具候选仍是咨询结果,不代表工具已调用、已认证或业务结果可用。完整字段与限制见 [V4 契约](skill/dynamic-skill-router/references/router-contract-v4.md);跨领域质量和成本收益未在本次公开副本中作全面验证。

## 技术栈

Node.js **22+**、ES modules;锁定依赖 `@modelcontextprotocol/server`、`smol-toml`、`zod`。MCP 集成测试使用 `@modelcontextprotocol/client`。本仓库不需要云端 API Key。

## 快速上手

```powershell
git clone https://github.com/yangwei251003/dynamic-skill-router.git
cd dynamic-skill-router
npm ci --ignore-scripts
npm run health
npm run list
npm run demo
```

三个演示命令会先验证临时 HOME 隔离,再启动子进程。默认仅扫描仓库自带的两个原创示例 Skill 和路由器自身 Skill;不连接第三方服务,不读取你的个人技能库、账号配置或历史记录。输出中的本地路径属于你自己的克隆目录。

演示和测试包装器会忽略调用者已有的 `SKILL_ROUTER_DATA_ROOT`,固定读取本仓库的 `examples/data`;直接运行 `node src/cli.mjs ...` 不经过该包装器,仍可用这一环境变量指定自己的数据根。

`npm run demo` 应返回 `ok: true`,并选出 `example-code-review`。`examples/runtime-tools.json` 是合成元数据,仅展示数据格式,不是真实会话工具清单,也不代表示例工具可被执行。

### 安装 Skill

将本仓库的 `skill/dynamic-skill-router/` 目录复制到所用宿主支持的 Skill 目录,再按宿主方式刷新或启动新会话。当前 Codex 官方用户目录约定为 `.agents/skills/dynamic-skill-router/`;旧环境的 `.codex/skills` 以目标宿主真实发现结果为准。先检查目标是否已有同名内容;完整配置和验收见 [Codex 安装指南](docs/codex-install.md),本仓库不自动覆盖用户配置或已有 Skill。

Skill 入口提供路由使用规则,实际 CLI/MCP 服务仍从本仓库运行,保留克隆目录与已安装依赖;按下面的说明配置 MCP。不同宿主的 Skill 路径和重载方式以该宿主文档为准。

### 直接使用 CLI

```powershell
node src/cli.mjs route '使用 example-code-review 审查代码' --host generic --contract-version 4 --dry-run --context
node src/cli.mjs health --host generic --contract-version 4
```

省略 `--contract-version 4` 会保留原 V3 兼容行为。若要传入完整 JSON,可以通过标准输入使用 `--input-json`,不要把私人信息拼接进 shell 命令。

### MCP 接入

需要支持 stdio MCP 的 AI 工具。命令为 `node`,参数为你本机克隆目录中 `src/mcp-server.mjs` 的**绝对路径**。Codex 的安全示例见 [mcp-config.toml](examples/mcp-config.toml);替换 `CORE_PATH` 后,手工合并该段到自己的有效配置,保留其他设置。

启动脚本只提供本地 MCP 服务,不自带网络部署或宿主账户。使用 `host: generic` 时默认读取仓库示例来源;选择 `host: codex` 或显式指定配置来源,可能只读检查对应机器的配置与插件登记。真实宿主应提供本次会话的 `runtimeSkills` 和 `runtimeTools`;复制示例元数据不能证明工具在线。

## 配置自己的技能来源

1. 先阅读 [配置说明](docs/configuration.md)。
2. 将自己有权使用的 Skill 目录加入 `config/skill-sources.json`,或通过代码 API 的 `sources` 参数显式传入。
3. 用 `health/list/coverage` 检查覆盖情况,再进行路由。
4. 不把自己的技能注册表、配置、反馈、日志或技能正文提交到此公共仓库。

## 目录结构

```text
src/                  CLI、MCP、发现、路由、恢复与维护源码
skill/                路由器本身的Skill入口与契约
config/               通用示例来源与未知状态宿主模板
examples/             原创示例Skill、示例注册表和合成工具元数据
scripts/              隔离运行和无外部动作的演示
tests/                可移植的既有回归与MCP测试
docs/                 结构示意、配置和验证范围
```

原机器的能力仪表板、第三方 Skill 全文、个人注册表、真实账号配置、运行日志、反馈和历史请求回放未收录。排除范围见 [PROVENANCE.md](PROVENANCE.md)。

## 验证

```powershell
npm test
npm run test:v421
npm run test:v43
npm run test:v439
npm run test:v4310
npm run test:v4311
```

也可用 `npm run test:all` 依次运行上述检查。这些命令通过隔离运行器使用临时 HOME。各版本的实际测试结果、未验证范围和限制见 [验证记录](docs/validation.md);既有结果不能代替对所有宿主、领域或成本收益的验证。已有桌面会话可能仍保留旧连接。

## 维护边界

`src/` 保留旧版同步、宿主规则安装与恢复源码,供维护者按需使用。这些维护入口可能写文件;演示和 `npm test` 不会把它们应用到真实用户目录。公开的宿主模板默认 `syncManaged/catalogManaged=false`、模型与能力未知。不要未经核实就把旧机的能力状态复制到新机器。

公开仓库不包含个人仪表板生成器;旧同步流程在文件缺失时跳过该步骤,已提供生成器的安装仍按原方式调用。同步可能修改其数据根目录,运行前先确认目标。

## 更新与许可

见 [CHANGELOG.md](CHANGELOG.md)。自有代码与文档采用 [MIT](LICENSE);依赖许可与来源见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 和 [PROVENANCE.md](PROVENANCE.md)。