Route OpenRouter requests through a configured provider list and quantization cap, injected as provider.only/order with allow_fallbacks, plus provider.quantizations.
Install
# from npm (prebuilt)
dsh plugin --profile web add dsh-openrouter-providers
# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)
dsh plugin --profile web add github:MoRanYue/dsh-openrouter-providers
Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).
README
中文 | English
A DeepSeek Harness plugin: pick the providers OpenRouter requests may use from the official directory, or scope that per model rule, and set a quantization cap and a service tier (service_tier); the plugin injects them as provider.only / provider.order / provider.quantizations routing parameters (plus a top-level service_tier) into every OpenRouter model request (multimodal requests carrying images pass through). It can optionally route those requests through the billion-context compression proxy. The plugin owns its configuration and writes it to $DSH_HOME/openrouter-providers.json (~/.dsh/openrouter-providers.json when DSH_HOME is unset); it is restored after a restart.
Compatible DSH versions: 0.1.5-rc.1 through 0.2.2-rc.1 (engines.dsh: >=0.1.5-rc.1 <0.3.0). This plugin imports no @deepseek-ai/dsh-* package at all — its only peer is @deepseek-ai/cordis — so neither the 0.1.7 nor the 0.2.x breaking changes reach it; the 0.2 major-version crossing was re-verified item by item on a real 0.2.0-rc.2, 0.2.1-alpha.1, 0.2.1-alpha.2, 0.2.1-alpha.4, 0.2.1-rc.2, 0.2.1-rc.3 and 0.2.2-rc.1 (config round-trip, llm/stream reroute, real OpenRouter routing, billion-context proxy routing, Plugins-page title and icon, settings-page form rendering, adapter contract, service-tier injection). The 0.2.2-rc.1 row was a contract review plus a live load: the host half activates normally (state endpoint and catalog fetch both work), and the eight LlmAdapter members, the llm/stream event signature, the client bundle protocol and the plugins.bundle.config slot contract are unchanged (that release's badge, llm/models-updated, purpose generics and content.ts tool-projection refactor are all additive); the reroute path (provider restriction, proxy) has not yet issued a real request on that version. Note: since 0.2.1-alpha.3 DSH treats engines.dsh as a real gate (taking precedence over peerDependencies, refusing to load on a mismatch), so raising the upper bound is a prerequisite for any 0.3.x upgrade.
Why the settings service is no longer used: DSH
0.1.7removed settings namespace registration (settings.register/SettingsScope/watch) and now enumerates only.volatile()fields on profile entry Configs. A plugin built on the old API fails silently on 0.1.7:applyreturns early, so neither the HTTP route nor thellm/streamreroute is registered, the settings page reports "Cannot read the current state (Host half unavailable)", and request injection never takes effect. This plugin owns its configuration document instead and treats the old namespace as an optional, capability-detected enhancement (below), so behavior is identical on old and new hosts.
Configuration entry points (dual-stack): DSH 0.1.6-alpha.2 moved plugin configuration out of Settings onto the new sidebar Plugins page and retired settings.plugin.item. This plugin registers both slots and lets the host's declarations decide which one applies (the undeclared one simply never fires — no error either way):
| Host | Slot | Where |
|---|---|---|
DSH ≥ 0.1.6-alpha.2 |
plugins.bundle.config (keyed by package name) |
Sidebar Plugins → this bundle's page → configuration form |
DSH < 0.1.6-alpha.2 |
settings.plugin.item |
Settings → Plugins → Plugin configuration → collapsible card |
On old hosts that card is dispatched per settings namespace the Host serves, so the plugin probes for settings.register and registers an empty pass-through namespace only when it exists — purely so the card can be dispatched; it carries no values. From 0.1.7 on, that API is gone, the namespace is skipped, and nothing else is affected.
Features
- Checkbox provider picker: the Host half fetches the official OpenRouter directory (
https://openrouter.ai/api/v1/providers, cached for 24 hours) and the form renders a searchable checkbox list, while keeping a field for hand-typed custom slugs. Selected entries stay visible even when they are absent from the directory, so an incomplete offline snapshot never drops an existing selection. If the directory cannot be fetched the form falls back to the built-in snapshot, labels it clearly as "offline or not refreshed", and retries after 60 seconds rather than waiting out the full day. - Configuration form: pick the routing mode and the quantization cap:
- Only these providers → the request body carries
provider: { only: [...], allow_fallbacks: false } - Try in order → injects
provider: { order: [...], allow_fallbacks: true } - Quantization cap → injects
provider: { quantizations: ['int4' | 'int8' | ...] }(optional, unrestricted by default; valid values in OpenRouter Quantization) - The whole feature has a master switch; saving writes the plugin-owned configuration file (
$DSH_HOME/openrouter-providers.json). On the new Plugins page only a save writes and leaving the page drops staged edits; the legacy card additionally offers a Discard button and an unsaved badge.
- Only these providers → the request body carries
- Per-model rules (optional): a
modelRulesarray in the configuration file lets different models use different provider restrictions — pinmakora/xiaomiforxiaomi/mimo*while leaving every other model unrestricted, for example. Rules are evaluated top-down and the first match wins; unmatched models keep the global configuration.patternis a case-insensitive glob (a*makes it a wildcard), and without a*it matches a namespace prefix (xiaomialready coversxiaomi/mimo-v2.6-flash).modeisinherit(follow the global mode) /only/order/off(skip injection for that model). An empty ruleprovidersinherits the global list. Resolution happens in bothbuildBody()and thellm/streamreroute gate, each against the request's own model, so a model that resolves to no restriction is never forced through the plugin's adapter. - Localized UI: copy comes from the plugin's
openrouter-providerslocale namespace (zh/en); switching the language re-renders the UI live with no page reload. On hosts without the locale service it falls back to Chinese copy. - Display name and icon on the Plugins page:
meta.title/meta.descriptionin the packagedlocale/zh.jsonandlocale/en.jsonprovide the localized display name (OpenRouter Providersin English, 「OpenRouter 提供商列表」in Chinese), so the plugin list shows a readable name instead of the bare package namedsh-openrouter-providers;icon: "./icon.svg"inpackage.jsonsupplies the card and row artwork (three fading rounded bars, suggesting a provider list narrowing step by step). Both follow the DSH interface language. Note thatexportsmust include"./locale/*.json": "./locale/*.json", otherwise Node's exports resolution throwsERR_PACKAGE_PATH_NOT_EXPORTEDand the display name silently falls back to the package name;iconmust be a relative path with a.svg/.png/.jpg/.jpeg/.webpextension, inside the manifest directory and at most 256 KiB — a violation is reported rather than ignored, but only the icon is lost and the name still applies. - Route detection does not look at the name: a provider in the profile can be renamed freely (to
aaaa, say) and still counts as an OpenRouter route as long as itsbaseURLhost isopenrouter.ai(subdomains included) or itsapiKeyEnvisOPENROUTER_API_KEY— the result is cached for 30 seconds, so a rename needs no restart. The built-inopenrouteralways counts, and extra route names can be listed in the configuration file'sroutesarray. The test deliberately anchors on the URL's host rather than a substring match:/openrouter\.ai/also matches a path fragment on an unrelated domain. - Image input: images in a multimodal request are converted to OpenRouter
image_urlparts (adata:URL) instead of being rejected outright. Bytes come from the host path theattachmentsservice hands out; an image already moved out of context (offloaded) degrades to a text placeholder rather than re-sending bytes that are no longer part of the history. The per-request image budget honours the host'sIMAGE_OFFLOAD_REQUIREDcontract — when exceeded,compaction-image-offloadmoves the oldest images out of context and retries, so the user never sees a failure — and it is enforced against the provider's actualmaxRequestImageBytesrather than a hardcoded 20 MiB. - Service tier (optional): injects the top-level
service_tier, one ofdefault/flex/priority/ultrafast(OpenRouter Service Tiers). Two things are easy to conflate: "not injected" is not the same asdefault— omitting the field defers to the workspace default and still lets the:nitro/:floorvariants admit tier endpoints, whereas sendingdefaultpins the standard tier and closes that door.ultrafastneeds an adequatemax_tokens, otherwise it degrades topriority.fastis not offered — it is a synonym forpriority. The form also reports which tier and provider served the last request (theservice_tierfrom the response), because OpenRouter falls back silently when a tier cannot be met; without that feedback you cannot tell whether the setting did anything. - Request injection: the plugin listens on the
llm/streamwaterfall — when the requested provider route is recognised as OpenRouter (enabled, with a non-empty list, or a quantization cap, or a service tier, or the proxy on), the request is rerouted to the plugin's own chat-completions adapter, which builds the request body and injects theproviderfield;reasoning.effort(off/low/medium/high/max, all valid OpenRouter values) passes through unchanged. The session log and UI still show the original route name. - billion-context compression proxy (optional): with the proxy switch set to Auto, the plugin detects a running local billion-context proxy and, when found, sends requests through its
/bili/entry point (<origin>/bili/https://openrouter.ai/api/v1/chat/completions) to gain its context compression; when no proxy is detected it goes direct, so installing this plugin can never break generation. The proxy switch and the provider-restriction master switch are independent: to get compression alone, turn the provider restriction off and enable the proxy by itself. - Credentials: reuses the existing
OPENROUTER_API_KEY— resolved through thecredentialsservice first (matchingllm-pi-ai'sapiKeyEnv), falling back to the same-named environment variable of the shell that launcheddsh web, so there is no need to enter it again in the UI. - App attribution: requests carry
HTTP-Referer: https://github.com/deepseek-ai/deepseek-harness,X-OpenRouter-Title: DeepSeek Harness OpenRouter, andX-OpenRouter-Categories: cli-agent, so OpenRouter's UI and leaderboards showDeepSeek Harness OpenRouterinstead of Unknown (OpenRouter App Attribution).
Installation (bundle mount)
The plugin mounts as a bundle package, like other plugins (dshmarket, dsh-recall-plugin, …): its cordis.patch.yml insert row is merged into the profile composition automatically.
Option A: install from npm (recommended)
In the profile directory (for example ~/.dsh/profiles/web/):
pnpm add dsh-openrouter-providers@latest
Then add the package to the profile package.json's dsh.profile.bundles list:
"dsh": { "profile": { "bundles": [ ..., "dsh-openrouter-providers" ] } }
Restart dsh web. The bundle coordinator merges the package's cordis.patch.yml (insert row: id: openrouter-providers) on its own.
Option B: install from GitHub
pnpm add dsh-openrouter-providers@github:MoRanYue/dsh-openrouter-providers
The remaining steps are the same as Option A (add to dsh.profile.bundles and restart).
Option C: local path
pnpm add dsh-openrouter-providers@file:D:\\path\\to\\dsh-openrouter-providers
# then add the package name to dsh.profile.bundles and restart
Manual mount (without the bundle)
Append to ~/.dsh/profiles/web/cordis.patch.yml:
- insert:
- id: openrouter-providers
name: 'dsh-openrouter-providers'
Then add the package to the profile package.json's dependencies and dsh.profile.bundles, run pnpm install, and restart.
Usage
- Make sure the model's provider route is OpenRouter — the built-in
openrouterroute, or any provider in the profile whosebaseURLhost isopenrouter.aior whoseapiKeyEnvisOPENROUTER_API_KEY(see "Route detection does not look at the name" above). - Open the configuration entry for your host (see the table above: sidebar Plugins → this bundle's page on DSH ≥
0.1.6-alpha.2, or Settings → Plugins → Plugin configuration on older hosts), check providers in the directory (or type a slug the directory does not list), choose the routing mode, quantization cap and service tier, and save. To scope by model, add rules under Per-model rules. - Every later OpenRouter request carries the injected provider routing parameters.
- For context compression: start the billion-context proxy (
bili) first, then set this plugin's Proxy field to Auto and save. The line under the field reports whether it is connected (Proxy in use: http://127.0.0.1:18790) or not detected; once detected it takes effect immediately, with no DSH restart.
Per-model rules look like this in the configuration file (the form edits the same thing):
{
"enabled": true,
"mode": "only",
"providers": ["deepinfra", "novita"],
"quantization": "off",
"serviceTier": "off",
"proxy": "auto",
"modelRules": [
{ "pattern": "xiaomi/mimo*", "mode": "only", "providers": ["makora", "xiaomi"] },
{ "pattern": "anthropic/*", "mode": "off", "providers": [] }
]
}
Provider slug format: see the OpenRouter Provider Routing docs (
order/onlyfields).
How it works (brief)
- Transport: the dynamic plugin environment has no built-in
fetch, so the adapter spawns anode -echild process through thesubprocessservice to perform HTTP + SSE streaming parsing (text/reasoning/tool-call deltas, usage,[DONE], error classification such as AUTH/RATE_LIMIT/INVALID_REQUEST/SERVER). - Image assembly and budgets:
serializeMessages()turns image blocks intodata:URLs and measures them the way DSH itself does — the base64 length isceil(bytes/3)*4, excluding thedata:prefix (counting the prefix would trip the budget about 22 bytes per image early, effectively moving one more image out of context than the host would). The three budgets have different origins:maxRequestImageBytes(the per-request hard ceiling) comes from that provider's configuration and is genuinely enforced;requestImageMaxBytes(single-image raw bytes) andrequestImagePixelBudget(single-image pixels) are only re-encoding targets in the host — pi-ai satisfies them by downscaling through a quality ladder — and since this plugin carries no image codec they are not enforced at their defaults (doing so would degrade most screenshots to placeholders for no benefit); they are enforced only when the user explicitly configures them, and an over-budget image degrades to a text placeholder with the reason. Image bytes are read withnode:fsstraight from attachment storage: that is DSH-owned data living outside any workspace, and the path comes from the trustedattachmentsservice rather than from user or model input, so the workspace sandbox policy does not apply to it (the same path the plugin already uses to read and write its own configuration file). - Locating a provider's image budget: the adapter only ever sees
PLUGIN_ROUTE, while the budget hangs off the provider the user configured. The reroute records the real route in aWeakMapkeyed by the request'sAbortSignal, andstream()reads it back — the signal is the only object that survives every layer's option spread with its identity intact, so no non-standard field has to be threaded through the option bag. - State persistence: the plugin owns its configuration and writes
$DSH_HOME/openrouter-providers.json(~/.dsh/…whenDSH_HOMEis unset), independent of the settings service. On first start, while the file still holds shipped defaults, the plugin tries each legacy location once, in order:<workspaceRoot>/.dsh-plugins/openrouter-providers.json(v1.0.4 and earlier), then$DSH_HOME/settings.yaml.imported(the renamed settings document 0.1.7 left behind, whose section for this plugin could not be imported because it declares no Config). The first source that holds values wins, and an existing configuration is never overwritten afterwards. - Client communication: the configuration card reads and writes state over the HTTP API
GET/POST /api/openrouter-providers/state(registered on the Host half throughwebServer). The client now shows the status code and response excerpt for a non-2xx response instead of reporting every failure as "Host half unavailable". - Provider directory: the same state route also returns
catalog([{slug, name}]) andcatalogSource(live/builtin). The directory is fetched withnode:httpsdirectly — for the same reason as the proxy probe, it must not go throughglobalThis.fetch, or a host with billion-context mounted would rewrite the fetch into a proxied request. It is cached for 24 hours; a failed refresh keeps the last successful list withcatalogSourcestilllive(stale but genuinely official), and only a fetch that has never succeeded falls back to the built-in snapshot withbuiltin, which the UI labels as "offline or not refreshed". The settings page waits at most 1.5 seconds for a refresh, so an offline host never blocks the form. - Adapter contract: the plugin registers a plain object adapter (not an
LlmAdaptersubclass), so it has no base-class defaults to fall back on and must implement every member the host calls. Besidesstream,LlmRuntimecallsproviderInfo/providerRetryPolicy/imageRequestPricing/imageRequestTarget/listModels/resolveModel/prepareCall— omit any one and that call site throwsTypeError: adapter.<name> is not a function. This plugin'slistModels()returns an empty array, so the synthetic route never appears in the model catalog (it is reachable only internally, fromllm/stream);imageRequestPricing()returnsundefined, leaving the token meter and spill policy on their own neutral estimates;imageRequestTarget()echoes the normalized width, height and byte ceiling, matching the base-class default (that member arrived in DSH0.2.1-alpha.3and is currently called only by the CUA screenshot path). - Service tier:
service_tieris a top-level field, not something insideprovider. It has three states rather than two: "not injected" (off),default, andflex/priority/ultrafast.defaultlooks like "nothing chosen" but is an active pin to the standard tier — omitting the field leaves the:nitro/:floorvariants free to admit tier endpoints, while sendingdefaultcloses that door. OpenRouter does not validate this field: probing showed every string (evenbogus) answers 200 and is silently ignored, so the legal set is enforced by a whitelist in the plugin and an out-of-range value is dropped when the configuration is written. Theservice_tierin the response is the only signal that a tier actually applied (nullmeans a non-tier endpoint served the request); the child process surfaces it alongsideprovideras aservedevent, the Host remembers the most recent one and returns it on the state route, and the form renders "which tier served the last request" from it. - billion-context proxy integration: the proxy address is never a hardcoded port; it is resolved in billion-context's own discovery order: the
BILI_MCP_PROXYenvironment variable →$XDG_STATE_HOME/billion-context/proxy-origin(both a bare URL and the instance JSON are supported) →lanes.dshinport-zone.jsonbeside it → thehttp://127.0.0.1:8787fallback. Every candidate is confirmed by requesting/__bili/healthand requiringok: true. The probe deliberately usesnode:http/node:httpsrather thanglobalThis.fetch: once billion-context is mounted it patches the hostfetchto rewrite every URL to<origin>/bili/<original>, so afetch-based probe would have its own request rewritten into a request the proxy makes to itself — and would then "succeed" forever. The result is cached for 30 seconds and refreshed in the background; the request path only reads that cache, so it never blocks generation on a socket. The settings page re-probes on every load and shows whether the proxy is actually in use. Requests carry anx-acp-session: <sessionId>header so the proxy buckets its compression state per conversation and the compression actually accumulates (the value comes from the session identity the host stamps onGenerateOptions.sessionIdfor exactly this kind of transport metadata).
Limitations
- Images are not re-encoded: this plugin carries no image codec, so the attachment's original bytes go out as a
data:URL. The host'srequestImageMaxBytes/requestImagePixelBudgetdefaults are only re-encoding targets (pi-ai meets them by downscaling through a quality ladder), so they are not enforced by default; the user has to configure them explicitly, and over-budget images then degrade to text placeholders. The trade-off is that a very large original is sent as-is and may hit the provider's own per-image limit. - Image bytes are read with
node:fsstraight from attachment storage, bypassing the workspace sandbox (see "How it works"). - With the global "enable provider restriction" switch off, all per-model rules are inactive too (the form greys out the rules section), because that switch is the master gate.
- In
onlymodeallow_fallbacks=false: the request fails when none of the listed providers is available (OpenRouter behavior). - Proxy routing is decided per request: if the proxy stops, requests fall back to a direct connection within 30 seconds (the probe cache TTL); if it starts, they pick it up within the same window, or immediately on opening the settings page once.
- The service tier is best effort: OpenRouter does not error when it cannot satisfy a tier, it just falls back, so setting
flexand seeing "no tier endpoint matched" is a normal outcome rather than a plugin failure.ultrafastadditionally needs an adequatemax_tokens, otherwise it degrades topriority. - The proxy and the provider restriction share one transport (this plugin's adapter), so with the proxy on, requests bypass the host's native
openrouterroute. If another plugin (such as billion-context's dsh-native) relies on intercepting the hostglobalThis.fetch, those interceptors do not apply to this plugin's traffic — an inherent consequence of owning the transport.
License
MIT
Links
More in this category
Ebony-Vinyl/dsh-our-free-model★ 82220
Adds free model lanes to DeepSeek Harness — DeepSeek V4.1 Flash, Kimi K3 and others — with no login, sign-up or API key, plus a local OpenAI-compatible gateway, fallback routing and a usage dashboard.
dingminhua/dsh-connect-workbuddy★ 1862
Connects locally signed-in WorkBuddy models, CN and international alike, to DSH, reading each model's credit multiplier from the upstream catalog on every refresh, with per-model image input toggles, account switching backed by an auto-failing-over pool, manual daily check-in, and read-only credit overviews shown as compact pills on the card and in the composer.
Alice-Marx/dsh-model-router★ 1005
Routes DeepSeek Harness work across configured model APIs and supported vendor CLIs with dependency-aware packages and cost previews.
V1ki/dsh-plugin-subscriptions★ 629
Use ChatGPT (Codex), Claude, and Grok subscriptions as DeepSeek Harness LLM providers, with Settings login, model catalogs, usage, plus image_generate, video_generate, and x_search tools.
XDTrees/dsh-workbuddy-xdpool★ 580
Merge every locally signed-in WorkBuddy account into DeepSeek Harness as one auto-failing-over model pool (multi-account rotation, live credits, and a model catalog showing per-model credit multipliers and free/night-discount tags).
XDTrees/dsh-xdpool★ 580
Merge every locally signed-in WorkBuddy account into DeepSeek Harness as one auto-failing-over model pool: multi-account rotation, 429 cooldowns, live credits, a model catalog with per-model credit multipliers and free/night-discount tags, QR-code login for 13 vendors, and aggregate free-tier channels. Accounts persist across restarts.
Community comments
Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.