智能路由 XHToken/dsh-intelligent-router

DSH 智能路由

为 DeepSeek Harness（DSH）提供智能 LLM 路由 —— 多模型路由策略、自动故障转移、缓存亲和保持、数据匿名化，以及可视化设置界面。

路由器把自己注册为 DSH 里的 auto 服务商。选 AUTO – Intelligent Router 作为模型，每个请求都会路由到你配置的路由组里最合适的成员 —— 规则、策略、故障转移、提示词缓存感知保持，全在底层自动完成。

架构

DSH 智能路由注册为 DeepSeek Harness 里的 auto 服务商，让每个请求依次经过可配置的路由组、策略、意图规则、缓存亲和保持和自动故障转移。

使用演示

下图展示 AUTO - Intelligent Router 在 DSH 里的真实对话流程：请求先分类，再匹配路由规则，最后由选中的服务商/模型成员处理。

路由细节

请求生命周期

设置与实时持久化

策略、路由组与保持

功能

路由

- 路由组 —— 组织成员（服务商 + 模型），在设置界面里统一管理
- 四种路由策略 —— order（优先级）· smart（按任务规模感知：本地还是云端）· rotate（轮询）· usage（最少使用优先）
- 规则引擎 — 支持 minTokens / hasImage / anyAgent / intent 条件；第一条命中的规则会把目标模型固定到候选链最前面
- 意图路由 — 用轻量分类模型（由你选择）给消息意图打标签；规则据此路由
- 粘性（缓存亲和） — off / turn / auto / session（默认 session）：只要服务商的提示词缓存还值得保留，就把上次成功的成员留在最前面，按 DSH 会话分别记录

可靠性

- 自动故障转移 — 错误分三级（TRANSIENT / PERMANENT / UNKNOWN），不误判：认证错误和校验错误绝不消耗重试；连接错误、限流错误和 5xx 错误则落到下一个候选
- 配额守卫 — 超出限额的成员直接跳过，不消耗重试

体验

- 设置界面（Magpie 风格，中/英）— 模型选择器由 DSH 已配置的模型填充，策略胶囊按钮、规则构建器、意图分类器选择、保存时校验，通过 DSH 设置服务实时持久化
- 可观测性 — 按组/按成员的指标、延迟跟踪、成本估算，以及 router/fallback 事件（宿主侧）

环境要求

- DeepSeek Harness >= 0.2.0-rc.2（在 compatibility.json 中声明）
- Node.js >= 18（DSH 运行时），开发需要 pnpm

安装

Via DSH (recommended)
dsh plugin --profile web add github:XHToken/dsh-intelligent-router

Or build from source
git clone https://github.com/XHToken/dsh-intelligent-router.git
cd dsh-intelligent-router
pnpm install && pnpm build
cp -r dist/* ~/.dsh/profiles/web/node_modules/dsh-llm-router/dist/
cp cordis.patch.yml compatibility.json ~/.dsh/profiles/web/node_modules/dsh-llm-router/

[!WARNING]
首次安装需要重启 DSH。 插件的加载器入口和客户端 bundle 会在服务器启动时编入启动图。
如果安装时 DSH 已在运行，它不会察觉新包——在你重启之前，设置界面（以及 auto 服务商）都会缺失。
停掉正在运行的 dsh web 进程再重新启动；只刷新浏览器不够。之后修改路由配置（在设置界面点保存）或重新构建插件 bundle，都会通过 HMR 实时生效——只有包级别的安装/卸载才需要重启。
等待 DSH 未来支持。

从配置档目录用本地二进制启动 DSH（cd ~/.dsh/profiles/web && ./node_modules/.bin/dsh web --port 3082）。用 npx 启动可能加载重复的模块树，导致设置写入失败。

快速开始

1. 启动 DSH，打开 设置 → 内置插件 → LLM Router
2. 点 + 添加模型，从 DSH 已配置的服务商中挑选成员
3. 选择策略（默认 order）；可选添加规则
4. 点 保存（通过 DSH 设置服务立即持久化）
5. 在聊天里选择 AUTO – Intelligent Router，搞定

要用指定分组，写 group/<groupId> 这种服务商形式。

配置参考

设置界面会把配置写进配置档的 cordis.patch.yml（id: llm-router）。最小示例：

- id: llm-router
name: 'dsh-llm-router'
config:
enabled: true
defaultGroup: 'default'
routeGroups:
- id: 'default'
name: 'Default'
strategy: 'order' # order | smart | rotate | usage
stays: 'session' # off | turn | auto | session
enabled: true
members:
- provider: 'ollama'
model: 'SparkLLM/Spark-X2.5-1.7B'
priority: 1
enabled: true
protocol: 'openai-responses'
- provider: 'qwen37plus'
model: 'qwen3.7-plus'
priority: 2
enabled: true
protocol: 'anthropic-messages'
- provider: 'deepseekv41flash'
model: 'deepseek-v4.1-flash'
priority: 3
enabled: true
protocol: 'openai-responses'
classifierModel: # used by intent rules
provider: 'ollama'
model: 'SparkLLM/Spark-X2.5-1.7B'
rules:
- minTokens: 10000
hasImage: true
intent: '复杂问题'
target: { provider: 'qwen37plus', model: 'qwen3.7-plus' }
- minTokens: 2000
intent: '复杂问题'
target: { provider: 'deepseekv41flash', model: 'deepseek-v4.1-flash' }
- intent: '简单问题'
target: { provider: 'ollama', model: 'SparkLLM/Spark-X2.5-1.7B' }
fallback:
enabled: true
maxRetries: 3 # total attempts per request
retryDelay: 1000
quotaTracking:
enabled: true

完整带注释的 schema 见 cordis.patch.yml.example。

文档

- 路由策略与规则引擎
- Magpie 集成设计
- 设置界面设计
- DeepSeek Harness 架构分析
- 用法示例：可复现的案例，附截图（agent-teams、coding、document pipeline、data anonymization、image redesign），由 dsh-router-examples 技能建立索引

开发

pnpm install
pnpm run build # tsup + ModuleLoader wrap
pnpm run typecheck # tsc --noEmit
pnpm run lint # eslint
pnpm test:run # vitest (194 tests)
pnpm run doctor # self-check a DSH installation (host version, plugin tree)

每次 push 都会跑质量流水线，之后 E2E 工作流 会把插件装进真实的 DSH 宿主（启动 → 重启 → 设置界面 bundle 契约 → doctor）。

路线图

- pace / weighted / intent 三种策略已在 schema 中声明，但尚未实现（会静默降级为 order）——要么实现，要么删掉
- 停留窗口（turn ≈ 2 分钟，auto ≈ 5 分钟）是写死的近似值——改为可配置
- 配额上限写死（每天 1M token、每天 1k 请求），且从不自动重置——接上 quotaTracking.limits
- 监控数据还没有 UI 通道（面板显示的是假数据）
- 中间件系统已实现，但没接进请求链路
- 删掉遗留的双重调用路径（route() 瀑布流 / llm-client.ts）

参与贡献

欢迎贡献——见 CONTRIBUTING.md。请先阅读行为准则。安全问题见 SECURITY.md。

参考资料

- magpie——本项目的设置 UI 与路由策略设计参考并借鉴了该项目。非常感谢作者。

许可证

基于 XHToken 社区许可证 授权。完整文本见 LICENSE。