OpenRouter 路由 WuSiYu/dsh-openrouter-routing

dsh-openrouter-routing

让 dsh 走 OpenRouter 时，可以按模型指定上游供应商（provider）和量化精度（precision/quantization）。可以在 Web 插件界面里设置，也可以写 cordis.patch.yml——两者改的是同一份配置。

安装

在 dsh 的 Plugins（插件）页 → Add plugin 里任选一种：

| 方式 | 填什么 |
| npm | dsh-openrouter-routing（或 dsh-openrouter-routing@1.2.3） |
| GitHub | https://github.com/WuSiYu/dsh-openrouter-routing |
| 本地目录 | 本仓库的绝对路径（开发用，改完重装即生效） |

装完重启一次 dsh 并刷新页面，配置页才会出现（客户端模块的包元数据在进程内缓存到重启为止，见下文）。要求 dsh >=0.2.1-rc.3；不满足时安装会被拒绝（incompatible-version），可用版本豁免放行。

为什么需要插件、它是怎么做到的，见下文为什么需要插件与工作方式与边界。

在插件界面里设置

Plugins（插件）页 → 本插件卡片 → 行 openrouter-routing → Configure（配置），页面里可以：

- 开关整组规则；
- 每条规则填：模型 ID 或通配（deepseek/deepseek-v4.1-flash、deepseek/、）、供应商（逗号分隔 → only）、量化精度（逗号分隔 → quantizations）；
- 勾选「只用这些供应商」→ 写 allow_fallbacks: false；
- 添加/删除规则，保存后下一次请求立即生效（走标准设置通道写回 profile 补丁层，不需要重启）。

页面不编辑 order、sort、max_price、require_parameters 等偏好；这些仍写在 cordis.patch.yml 里，保存时会被原样保留。

首次启用需要重启一次 dsh：客户端模块的包元数据（dsh.client 声明）在进程内按包名缓存到重启为止，插件安装时它还没有这一半。重启后刷新页面即可看到配置入口；之后改 client.js 只需刷新页面，改 index.js / schema.js 才需要再次重启。

用 YAML 设置（等价方式）

~/.dsh/profiles/<profile>/cordis.patch.yml
- id: openrouter-routing
name: 'dsh-openrouter-routing'
config:
models:
"deepseek/deepseek-v4.1-flash" # 建议写别名对应的实底 id，通配也行 provider: DeepInfra # 或 ["DeepInfra", "Fireworks"] require_parameters: true # 只选真的支持 reasoning/tools 的供应商 "deepseek/":
order: ["DeepInfra", "Fireworks", "Together"]
sort: throughput

precision（量化精度）默认不要写，原因见下面的精度说明。

cordis.patch.yml 由 HMR 监视，保存后立即重载；而 bundle 自带的补丁文件不在监视范围内。

装好之后，也可以用模型工具 openrouter_routing 查看当前规则、配置页是否可用、以及最近改写过的请求（含 HTTP 状态）。

配置字段

| 字段 | 默认 | 说明 |
| enabled | true | false 时所有规则失效，请求原样发出 |
| hosts | ["openrouter.ai"] | 需要改写的域名，子域名自动包含；填自建网关域名也能生效 |
| models | {} | 键是模型 ID 或通配模式（ 任意字符，? 单个字符），值是一条规则 |
| default | 无 | 没有任何 models 键匹配时使用的规则 |

规则里可以写：

| 键 | 类型 | 作用 |
| provider | 字符串、字符串数组或对象 | 字符串/数组 = 只允许这些供应商（= only）；对象 = 直接写 OpenRouter 的偏好字段 |
| precision | 字符串或字符串数组 | 量化精度（= quantizations）。不建议使用，见精度说明 |
| only / order / ignore | 字符串或数组 | 白名单 / 优先顺序 / 黑名单 |
| quantizations | 字符串或数组 | 精度白名单，常见值 fp4 fp8 bf16 fp16 mxfp4 unknown。同上，不建议使用 |
| allow_fallbacks | 布尔 | 白名单都不可用时是否允许回退，默认由 OpenRouter 决定（允许） |
| require_parameters | 布尔 | 只选支持请求里全部参数的供应商 |
| data_collection | allow / deny | 是否允许供应商记录数据 |
| sort | 字符串或对象 | price / throughput / latency，或 { by, partition } |
| max_price | 对象 | 价格上限，如 { prompt: 0.2, completion: 1 } |
| preferred_min_throughput / preferred_max_latency | 数字或对象 | 吞吐/延迟偏好，如 { p90: 50 } |
未识别的键不会被拒绝，而是原样放进 provider 一并发出（这样 OpenRouter 将来新增字段不用等插件更新），并会在 openrouter_routing 的规则列表里标注为 passed through。已知键写错类型（例如 allow_fallbacks: "no"）会在插件激活时报错，行会显示为 failed，不会静默失效。

关于 precision / quantizations 的可靠性

精度由 provider 自行、可选上报，不一定有实际意义，也不一定能反映质量差异。 很多大厂——包括模型厂商自己的官方端点——均未上报精度，值为 unknown。

quantizations 是字面过滤：一旦写了 fp8，所有 unknown 的端点会被整体排除，很可能正好把官方那家排掉。以 deepseek/deepseek-v4.1-flash-1017 为例，34 个端点里 14 个是 unknown（含官方 DeepSeek 端点），fp8 15 个、fp4 4 个、mxfp4 只有 1 个。

更根本的原因是：这类模型本身是混合精度权重（V4.1-Flash 是 FP4 路由专家 + FP8 其余），单一标签描述不了它；unknown 往往只是「不方便标」，不等于「质量未知」。

所以：

- 想保质量 → require_parameters: true + 自己实测，而不是按精度筛；
- 想控成本 → sort: price / max_price，价格是可查的真实指标；
- 实测出某家不行 → ignore: ["那家"] 精确排除。

另外，某些模型（尤其 ~vendor/model-latest 这类别名）在 OpenRouter 上没有 endpoints 元数据，根本查不到分家精度；这种情况下写精度过滤等于盲筛，还可能因为筛空 + allow_fallbacks: false 直接让请求失败。

匹配顺序

1. 模型 ID 完全相等的那条规则优先；
2. 否则按 models 里的书写顺序，取第一条匹配的通配规则；
3. 都不匹配时用 default。

更多例子

固定供应商、禁止回退（供应商挂了就直接报错，不会偷偷换一家）：

models:
"deepseek/deepseek-v4.1-flash":
provider: DeepInfra
allow_fallbacks: false

只要便宜的、延迟可接受的：

models:
"deepseek/":
sort: "price"
preferred_max_latency: { p90: 30 }
max_price: { prompt: 0.3, completion: 1.2 }

状态查询

插件注册了一个只读工具 openrouter_routing（无参数），返回配置页可用性、当前规则和最近 20 次改写记录：

OpenRouter provider routing: active.
Rewritten hosts: openrouter.ai
Configuration page: available on this row in the Web Plugins page.
Rules (an exact model id wins over every pattern; otherwise the first matching pattern wins):
- model "deepseek/deepseek-v4.1-flash-1017" -> {"only":["DeepInfra"],"require_parameters":true}
Rewritten requests, newest first (last 20 kept):
- 2026-10-23T09:12:44.031Z model=deepseek/deepseek-v4.1-flash-1017 rule="deepseek/deepseek-v4.1-flash-1017" -> HTTP 200
provider={"only":["DeepInfra"],"require_parameters":true}

直接问 dsh「现在 OpenRouter 用的是什么供应商 / 精度」即可。插件同时用 logger.debug 记录每次改写（openrouter-routing: <model> via "<rule>" -> HTTP <status>）。

为什么需要插件

dsh 的 pi-ai 适配器（@deepseek-ai/dsh-llm-pi-ai）在配置里故意不开放 pi-ai 的 openRouterRouting 字段——COMPLETIONS_COMPAT_GATE 把它标成 withhold。而请求体里的 provider 对象正是 pi-ai 从这个字段生成的（dist/api/openai-completions.js: params.provider = model.compat.openRouterRouting），所以只靠 providers.openrouter.models[].compat 无法设置供应商或精度，写进去会被直接拒绝。本插件补上这个缺口。

工作方式与边界

- 拦截点：globalThis.fetch。pi-ai 的 OpenAI 兼容实现用 openai SDK（v7）发请求，SDK 在构造 client 时取 globalThis.fetch，而 client 是每次请求现建的，所以装插件后立即生效。
- 只碰该碰的：仅 POST + 配置的域名 + 请求体是 JSON 且带 model 字段 + 命中规则时才改写；其他请求（GET、别的域名、非 JSON body、流式 body）一律原样调用上一个 fetch。
- 合并而非覆盖：请求体里已有的 provider 字段会保留，配置里的键覆盖同名键。pi-ai 默认会带一个空 provider: {}，正好被合并。
- 不改响应：只返回上游 Response 本身（额外记一个状态码），SSE 流式响应不受影响。
- 可卸载 / 即时生效：只有 globalThis.fetch 还是自己那层时，disposer 才恢复；配置变化（界面保存或 cordis.patch.yml 热重载）通过 loader/volatile-update 就地重建规则，无需重启。新配置如果非法，会保留上一份并记一条 warn，不会让请求失败。
- 配置页：schema.js 会加载本安装自带的 @deepseek-ai/schemastery（按 process.resourcesPath 等路径探测，asar 内也能加载），并为该行声明 Config；client.js 通过 ctx.configForms + plugins.row.config 插槽把页面注册到 Plugins 页。找不到 schemastery 时插件照常工作（openrouter_routing 会说明配置页不可用），只是没有界面。
- 已知边界：流式（ReadableStream）body 无法检查，会透传；同一个进程里所有 session 共用这套规则（规则按模型 ID 匹配，不区分 session）；模型 ID 必须是 OpenRouter 上的原始 ID（例如 deepseek/deepseek-v4.1-flash），不支持 :nitro 这类 slug 变体——变体请用偏好字段表达。

目录

| 文件 | 作用 |
| index.js | Host 插件：装 fetch 拦截器、注册 openrouter_routing 工具、跟随 volatile 配置更新 |
| routing.js | 纯逻辑：配置校验、模式匹配、请求体改写 |
| schema.js | 加载本安装的 schemastery 并声明可编辑的 Config（配置页的前提） |
| client.js | 浏览器半：Plugins 页里的配置表单（自绘控件 + 主题 token） |
| cordis.patch.yml | bundle 补丁，插入 openrouter-routing 这一行（默认 models: {}，即不生效） |
| test/routing.test.mjs | Host 侧用例：规则引擎、拦截器、volatile 更新 |
| test/client.test.mjs | 客户端用例：行映射、插槽注册、保存路径 |
| locale/.json | 插件管理页显示的名称与说明 |
| icon.svg | 插件图标（自绘） |

开发

npm test # 22 个用例，无需安装依赖（schemastery 缺失时自动跳过配置页）
npm pack --dry-run # 看实际会发布的文件

发布：改 package.json 的 version → 打 tag（git tag v1.0.1 && git push --tags），
.github/workflows/publish.yml 会校验 tag 与版本一致、跑测试、带 provenance 发布到 npm。
首次使用前在仓库 Secrets 里加 NPM_TOKEN（npm automation token）。

许可

MIT