技能路由 lau4tin1/dsh-skill-router

欢迎使用 DSH-SKILL-ROUTER！

dafeiyu

给 DeepSeek Harness 用的技能路由

RAG 风格的技能路由插件，用于 DeepSeek Harness：把技能（技能的 name + description + whenToUse 路由面）向量化，把每个用户任务也向量化，用基于间隔的筛选规则只留下明显相关的技能，再把它们的完整内容自动注入提示词——加载技能不需要模型往返一次。

- 设计：见 DESIGN.md。
- 状态：V1 已完成并跑通——能对着真实的 DSH 0.1.5-rc.2 类型通过类型检查，能构建，能挂载进运行中的 DSH 配置档（已在 web 和无头配置档中验证），并在真实技能上通过 20/24 条中英双语路由提示词（node demo/e2e.ts）。兼容 DSH 0.1.5-rc.2 到 0.2.0-rc.2（peer 范围 >=0.1.5-rc.2 <0.3.0-0）；它用到的所有路由 API——ctx.skills.snapshot/get、skills/change、renderSkillContent、createUserMessage，以及 agent/pre-step 中间件——在 0.2.0-rc.2 中都没有变化。

安装

dsh plugin --profile web add dsh-skill-router

装进 web 配置档；把 web 换成别的配置档名就能装到对应配置档。需要 dsh，并且 PATH 里有 pnpm。

pnpm 12 构建审批 —— 首次安装会拉取原生依赖（onnxruntime-node、sharp、protobufjs），它们的构建脚本默认被 pnpm 拦截。如果 dsh plugin 停在 ERR_PNPM_IGNORED_BUILDS，打开 $DSH_HOME/profiles/<name>/pnpm-workspace.yaml，把 pnpm 写进去的 allowBuilds 各项改成 true，再重新执行同一条 dsh plugin ... add 命令。

第一次跑真实任务时会下载一次嵌入模型（约 543MB，q8）到 $DSH_HOME/skill-router/models，之后完全离线运行。

目录结构

- src/index.ts —— Cordis 插件入口（name / inject / Config / apply）。
- src/selection.ts —— 筛选规则（最大间隔 / 与最大值之比，弱下限）。
- src/similarity.ts —— 余弦相似度 + 向量辅助函数（纯函数）。
- src/embedding.ts —— 通过 transformers.js（ONNX）接入的真实嵌入模型。
- src/skillIndex.ts —— 索引：构建、向量化、变更时按摘要差异同步。
- src/config.ts —— schemastery 配置 schema + 映射器。
- src/render.ts —— 渲染注入的 <system-reminder> 块（复用 DSH 的 renderSkillContent）。
- demo/e2e.ts —— 对下载下来的技能做端到端路由测试。

构建

npm install # toolchain (typescript, esbuild); DSH types come from a local checkout symlink
npm run typecheck # tsc --noEmit against the real DSH types
npm run build # esbuild -> lib/index.js (@deepseek-ai/* kept external)

演示

技能放在 .agents/skills/ —— 这是真实 DSH 会扫描的根目录（rank 200，见 DESIGN.md §14）。演示解析它们的方式和注册表暴露它们的方式一致：

node demo/e2e.ts # plugin defaults
node demo/e2e.ts 0.2 # experiment with the minScore floor

配置（默认值）

enabled: true
embedding:
model: Xenova/bge-m3 # optional; any HF ONNX embedding model
dtype: q8 # or fp32
cacheDir: ~/.dsh/skill-router # optional; models + index live here
rule: largest-gap # or ratio-to-max
minScore: 0.2 # confidence floor (precision > recall)
ratioThreshold: 0.75
maxSkills: 4

上面是插件的默认配置，也就是经典的 gap/ratio 模式。随包提供的 cordis.patch.yml 改用尺度无关的覆盖配置：minScore: 0.05 和 zThreshold: 2.5。

语言

中文和英文开箱即用——默认模型是多语言的，中文提示词能按语义匹配英文技能描述（反过来也一样），跨语言没问题。有一条 DSH 注册表规则要遵守：技能名称必须保持 kebab-case ASCII（pdf-tools），但 description、whenToUse 和正文可以用中文。注入的指令块是中英双语的（中文/English）。

嵌入模型

只有一个引擎：通过 transformers.js（ONNX）跑真正的本地模型——稠密语义向量；同义词和改写都能匹配，不要求字面重合。默认 Xenova/bge-m3（q8，约 543MB 下载，1024 维，[CLS] pooling）——中英双语旗舰级质量。想换别的，改 embedding.model：multilingual-e5-small（快，需要 query/passage 前缀——已自动处理）、bge-large-en-v1.5、bge-large-zh-v1.5。

打分时会对向量做去偏，减去语料均值（「中心化」），去掉那个共享方向——否则不相关的文本也会拿到约 0.8 分。推理固定单线程，保证结果确定。

所有重数据都放在工作目录之外：模型从 huggingface.co 一次性下载到 <cacheDir>/models，技能嵌入索引持久化在 <cacheDir>/skill-index.json（原子写入，带模型 id 标记），所以重启后没变过的技能不会重新嵌入。

开发说明

node_modules/@deepseek-ai 和 node_modules/js-yaml 是指向 DSH 检出目录的本地符号链接，用于类型检查和演示；全新安装后要重新创建。运行时由真实的 DSH 配置档提供 @deepseek-ai/* 包（它们声明为 peerDependencies，构建时保持外部依赖）。