dsh-multi-model-router

dsh-multi-model-router

简体中文 | English

多模型路由 DeepSeek Harness 插件：场景感知的模型 + 提供商选择， 费用优先 / 速率优先自动路由，跨提供商故障转移，两级套餐·档位菜单。

A DeepSeek Harness plugin for scene-aware multi-model routing with cost-first / speed-first auto-routing, cross-provider failover, and a two-level package·tier selection menu.

纯 META-适配器：注册 mmr 路由，暴露虚拟模型（mmr/coding、mmr/cost:gpt-4o、mmr/speed:deepseek-chat）， 其 stream() 解析虚拟模型为真实提供商 + 模型后委托 ctx.llm.stream() 派发。 不持有 API 密钥、不发出任何出站 HTTP 请求。

---

亮点

• 场景路由 — 定义命名场景（编程 / 翻译 / 搜索 …），每个场景有主模型 + 有序候选链（跨提供商）。 选择场景的虚拟模型（mmr/<场景>）即委托给最佳可用候选，在首个正文增量前故障转移。
• 费用优先 — mmr/cost:<基础模型> 按费用从低到高自动路由。内置 30+ 热门模型价格表； 未知模型按最贵处理（排在最后，绝不归零）。纯本地，无出站 HTTP。
• 速率优先 — mmr/speed:<基础模型> 按速度从快到慢自动路由。内置最小速度探针 （TTFT + tok/s，防假：排除未流出的推理 token）。TTL 缓存 5 分钟。
• 两级菜单 — 第一级选模型（套餐），第二级选提供商（档位）。对话内快捷选择按钮 + 完整设置页。
• 模型收藏 ★ — 收藏常用模型置顶到一级菜单。设置页可拖拽排序。
• 可靠性层 — 分级冷却（限流=短、服务器=中、鉴权=长，指数退避上限 30 分钟）、 健康感知排序（滑动窗口、时间衰减 + 错误码加权）、每步最大切换数约束。
• 跨提供商故障转移 — 正文前失败丢弃缓冲并前进到下一候选；正文后失败以部分输出结束。 兼容 dsh-our-free-model 路由。
• 工具配对修复 — 被中断的工具调用在委托前获得合成响应，防止 400 错误。
• 信任围栏 — 优先使用 connection.admit（与 /api 同级），缺失时回退到回环 + 同源检查。
• 零出站 HTTP、零 API 密钥 — 纯委托层，安全边界不受影响。

架构

┌─────────────────────────────────────────────────┐
│  index.js (Host 入口)                           │
│  apply(ctx, config) → registerAdapter(['mmr'])   │
│  + webServer /api/mmr/* + emitTopology          │
├─────────────────────────────────────────────────┤
│  src/adapter.js   — META-适配器 (鸭子类型)      │
│  src/router.js    — resolveVirtualModel +       │
│                     orderCandidates + enumerate │
│  src/scenes.js    — 场景/虚拟模型定义           │
│  src/failover.js  — 链路遍历 + 缓冲+前进       │
│  src/health.js    — 分级冷却 + 健康排序        │
│  src/pricing.js   — 价格表 + sortByCost         │
│  src/speed.js     — 探针 + tok/s + sortBySpeed  │
│  src/repair.js    — 工具配对修复               │
│  src/trust.js     — 信任围栏 (admit/loopback)  │
│  src/chunk.js     — StreamChunk 谓词           │
│  src/store.js     — 原子 JSON 存储 (0600)      │
│  src/api.js       — CRUD HTTP 接口             │
├─────────────────────────────────────────────────┤
│  client.js (Web 半身)                           │
│  settings.section → "模型路由" 设置页          │
│  conversation.input.right → 快捷选择按钮       │
└─────────────────────────────────────────────────┘

路由器是 META-适配器：它注册在 mmr 路由下，暴露虚拟模型 （mmr/coding、mmr/cost:gpt-4o、mmr/speed:deepseek-chat）。 其 stream() 将虚拟模型解析为真实提供商 + 模型，通过 ctx.llm.stream({provider, model, ...}) 委托派发。 递归安全：解析出的提供商始终是真实路由（deepseek、our-free-model …），绝不是 mmr。

安装

从插件市场

在 DSH 设置 → 插件市场中搜索 dsh-multi-model-router，或粘贴 GitHub 地址安装：

https://github.com/LiyinAlpaca/dsh-multi-model-router

从 GitHub（命令行）

dsh plugin --profile <profile> add github:LiyinAlpaca/dsh-multi-model-router

安装后重启 DSH 一次。--profile 填实际使用的 profile 名称。

⚠️ 不要在 profile 目录运行 npm install。 DSH profile 是 pnpm-only 环境， npm install 会无视 nodeLinker: hoisted 布局并自动安装 peerDependencies， 导致核心运行时包重复注册、对话不可用。请只通过插件市场或 dsh plugin 命令安装。

从本地目录

1. 克隆本仓库到本地。
2. 确保 @deepseek-ai/cordis、@deepseek-ai/dsh-llm、@deepseek-ai/schemastery 可用。
3. 重启 DSH。

配置

打开 设置 → 模型路由：

• 场景标签 — 添加 / 编辑 / 删除场景。每个场景有主模型 + 有序候选链 + 策略（fallback / round-robin）。
• 收藏标签 ★ — 切换收藏 + 拖拽排序。收藏的模型置顶到一级菜单。
• 健康标签 — 查看每个候选的健康分、连续失败数和冷却状态。
• 价格标签 — 查看价格表（每百万 token 美元）。
• 速度标签 — 查看速度探针结果（tok/s、TTFT、采样数）。
• 候选标签 — 查看所有已注册提供商的真实模型。
• 设置标签 — maxSwitchesPerStep、healthRanking 开关、customPricing 覆盖。

默认场景

兼容性

• DSH 0.1.5+ / 0.1.7+ / 0.2.0+ — 鸭子类型适配器（无 instanceof）、扁平重试策略、结构性兼容。
• dsh-our-free-model — 兼容。路由器的 enumerateReal() 包含除 mmr 外的所有提供商， 因此 our-free-model 路由是可选候选。无冲突（不同提供商路由）。
• Node 22.19+ / 24+

测试

node test/failover.test.mjs   # 45 tests — 链路遍历、缓冲+前进、失败分类
node test/health.test.mjs     # 23 tests — 分级冷却、健康分、排序
node test/pricing.test.mjs    # 25 tests — 价格表、token 估算、sortByCost
node test/speed.test.mjs      # 26 tests — 探针、tok/s、decodeWindow、sortBySpeed
node test/repair.test.mjs     # 13 tests — 工具配对修复
node test/api.test.mjs        # 26 tests — CRUD、信任围栏、404
node test/smoke.test.mjs      # 21 tests — apply() + 适配器契约 + 委托
# Total: 179 tests, 0 failures

全部离线执行，不出网、不消耗任何模型额度。

安全与隐私

• 所有状态写入 DSH_HOME/multi-model-router/settings.json（权限 0600），不上传至任何位置。
• 路由器不持有 API 密钥、不发出任何出站 HTTP 请求。每次调用都委托给其他已注册适配器的 ctx.llm.stream。
• 插件 HTTP 路由（/api/mmr/*）带信任围栏：优先使用 composition 的 connection.admit（与内核 /api 同级）， 缺失时回退到结构化围栏（回环 Host + 同源 Origin 检查）。
• 请求体上限 1 MB（413 拒绝）。

许可证

MIT，见 LICENSE。

本项目为独立插件，与任何模型提供方无隶属、认可或赞助关系。

致谢

• dsh-our-free-model — 降级链 + 故障转移引擎（MIT）， 本路由器的链路遍历和"缓冲到首答"模式基于其实现。
• dsh-model-router — 分级冷却 + 健康感知排序 + maxSwitchesPerStep 可靠性层。
• dsh-model-router (Alice-Marx) — 费用效用公式（costUtility = 1/(1+C/C_ref)）。
• dshelm — 策略解析 + 证据评分概念。