前言¶
DSH 的插件体系允许扩展 harness 的模型选择、设置卡片和请求路由能力。dsh-model-router 是一个社区插件，用于解决一个具体场景：用户已经配置了多个提供商和多个模型，希望在模型选择器中统一看到全部模型，并在每次 LLM 请求发出时，把请求发到该模型当前激活的提供商。
它不在会话中保存真实提供商，而是让会话始终使用虚拟提供商 model-router，请求发出时再解析当前激活提供商并委派给原有 adapter 管线。下面介绍它的能力、安装方式和配置项。
这是什么¶
dsh-model-router 由 fonlan 维护，许可证为 MIT。
它向 DSH harness 注册一个虚拟模型提供商：
model-router
该提供商会汇聚用户已添加的所有提供商及其模型，并按 model id 严格归并。每次 LLM 请求发出时，插件会把请求路由到该模型当前激活的提供商。
设置入口位于：
设置 → 插件 → 插件配置 → 模型路由
核心能力¶
虚拟 model-router 提供商¶
安装后，model-router 会出现在输入框下方的模型选择器中，也会出现在默认模型设置等模型选择入口中。
它列出全部已配置提供商的所有模型。模型条目会标注当前激活提供商，例如：
via OpenCode Go
这意味着用户看到的不是分散在各个提供商下的模型，而是一个统一的模型入口。
模型选择菜单中的提供商切换¶
当当前会话选择的是 model-router 模型时，点击输入栏的模型选择器，可以看到「模型 / 提供商 / 推理等级」三栏菜单。
其中「提供商」一栏会列出该模型当前激活的提供商，支持直接切换。切换后，该模型后续请求会使用新的激活提供商。
该入口显示由 showQuickSwitch 控制。当 router 全局只有一个提供商，或当前模型仅由一个提供商服务时，提供商栏会自动隐藏。
严格按 model id 归并¶
同一个模型如果出现在多个提供商中，会被归并为一条模型条目。
模型展示名、上下文窗口、推理档位等参数会跟随当前激活的提供商。请求时，插件会按该提供商的原始模型 ID 发给真实提供商。
匹配时忽略模型 ID 前缀¶
插件支持匹配时忽略模型 ID 前缀，默认开启，可通过设置关闭。
例如配置示例中：
deepseek/deepseek-v4-flash
和：
deepseek-v4-flash
可以视为同一模型，统一显示不带前缀的模型 ID。请求时传入带前缀的 ID 也能命中同一路由。
这里只是配置示例，不表示这些模型一定可用。
请求时实时路由¶
会话中始终保存：
provider=model-router
每次 LLM 请求发出时，插件在进程内解析当前激活提供商，并委派给真实 adapter 管线处理。
这种方式对主 agent、子代理、工具 LLM 调用使用同一路由逻辑。
设置卡片¶
设置卡片位于：
设置 → 插件 → 插件配置 → 模型路由
在设置卡片中，每个模型下列出其全部提供商，并支持以下操作：
- 点击提供商，切换当前实际使用的提供商。
- 拖拽提供商，调整优先级顺序。
- 未配置 API 密钥的提供商不可选，并会被标灰。
order 和 active 分开维护：
- 点击切换只改
active。 - 拖拽排序只改
order。
order 用于维护优先级顺序，为后续自动切换策略预留；当前版本在请求失败时直接返回错误，不做自动切换。
模型显示顺序¶
模型选择列表中的 model-router 分组支持三种显示顺序：
custom | name | recent
含义如下：
custom：自定义顺序，可手动拖拽模型顺序。name：按名称排序。recent：最近使用排序，最近请求过的模型排最前，未用过的排最后。
切换显示顺序和拖拽模型顺序后，全局即时生效。
自动同步配置¶
新增或删除提供商、模型后，插件会自动同步配置：
- 消失的提供商从排序中清理。
- 激活提供商失效时，自动回落到剩余第一位。
- 新提供商追加到排序末尾。
- 消失的模型从自定义顺序中清理。
- 新模型追加到自定义顺序末尾。
- 未配置过的模型自动选择排序第一位。
modelOrder 和 recentlyUsed 由插件自动维护，无需手写。
CLI 和 headless profile¶
插件不仅用于 web profile。CLI / headless profile 安装后，同样会按照配置进行路由。
这类场景下，可以直接手改 settings.yaml 中的 model-router 段。
安装与启用¶
从 npm 包安装¶
使用官方安装命令：
dsh plugin --profile web add @fonlan/dsh-model-router
本地源码安装¶
也可以从仓库本地构建后安装。在仓库目录下构建出 lib/ 产物后，以本地目录方式添加：
pnpm build
dsh plugin --profile web add .
挂载与生效¶
安装后，插件通过 cordis.patch.yml 自动挂载到目标 profile：
- 服务端注册
model-router提供商与路由配置。 - web 端注册
settings.plugin.item设置卡片。 - 重启 profile 后生效。
web profile 重启后，输入框下方的模型选择器中会出现 Model Router 分组。
注意：插件以当前 DSH 进程权限运行。安装前应检查源码和许可证。该插件许可证为 MIT。
配置示例¶
路由配置持久化在 settings 文档的 model-router 命名空间中。下面给出一个配置示例；其中的模型 ID 仅作为示例，不表示模型可用性。
model-router:
showQuickSwitch: true
ignoreModelIdPrefix: true
modelSort: custom
modelOrder:
- deepseek-v4-flash
- qwen3.7-max
recentlyUsed:
deepseek-v4-flash: 1787036509332
models:
deepseek-v4-flash:
order:
- opencode-go
- deepseek-official
active: opencode-go
各配置项含义如下：
showQuickSwitch
控制在模型选择菜单中是否显示提供商切换入口，默认开启。
ignoreModelIdPrefix
控制匹配时是否忽略模型 ID 前缀，默认开启。
modelSort
控制模型显示顺序，可选：
custom | name | recent
默认值为：
custom
modelOrder
用于 custom 模式下的模型显示顺序，由插件自动维护。
recentlyUsed
用于 recent 模式，记录模型 ID 与最后使用时间戳，由插件自动维护。
models.<model>.active
当前实际使用的提供商。
models.<model>.order
提供商优先级顺序，用于后续自动切换策略。
典型用法¶
Web profile¶
1、安装插件并重启 profile。
dsh plugin --profile web add @fonlan/dsh-model-router
2、打开：
设置 → 插件 → 插件配置 → 模型路由
3、在某个模型下点击提供商，切换当前实际使用的提供商。
4、如需调整优先级，可以拖拽提供商顺序。
5、回到输入框下方的模型选择器，选择 model-router 中的模型。发起请求时，会路由到当前激活提供商。
CLI / headless profile¶
1、安装插件到目标 profile。
2、重启 profile。
3、修改 settings.yaml 中的 model-router 段，例如调整：
models.<model>.active
models.<model>.order
modelSort
showQuickSwitch
ignoreModelIdPrefix
4、重启后按配置路由。
适用场景与注意¶
适合以下 DSH 用户：
- 已经配置多个提供商。
- 同一个模型可能来自多个提供商。
- 希望在一个模型选择器中统一查看模型。
- 希望手动切换某个模型当前使用的提供商。
- 希望手动维护提供商优先级顺序。
- 需要在 web、CLI 或 headless profile 中使用同一套路由配置。
需要注意以下几点：
- 当前提供商请求失败时，插件直接返回错误；自动切换是后续规划功能。
order和active分开维护，点击切换不会改变拖拽出来的优先级顺序。- 未配置 API 密钥的提供商在设置卡片中不可选。
- 配置示例中的模型 ID 只是示例，不表示这些模型可用。
- 插件以当前 DSH 进程权限运行，安装前应检查源码和许可证。
- DSH 社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系，不应视为官方应用商店。
结尾¶
dsh-model-router 的价值，是把多个提供商的模型入口收敛到 model-router 这一个虚拟提供商下，并在每次请求发出时解析当前激活提供商。它适合需要统一管理多提供商模型入口、手动切换当前提供商并维护优先级的 DSH 用户。
目录页：未提供已核实 URL。
GitHub：
https://github.com/fonlan/dsh-model-router
