@dsh-external/dsh-omniroute-models
简体中文
OmniRoute model manager: a DSH host+client plugin that pulls every OmniRoute model and its
modalities, and lets you control which OmniRoute models DSH actually serves through a
searchable / filterable / multi-select settings page.
Pain point: OmniRoute (an OpenAI-compatible gateway) exposes a lot of models (1000+ on this machine).
DSH's built-in "Models" page has no search or filter, and its discovery contract does not return
modalities (DiscoveredModelView only has id/name/contextWindow/maxTokens). This plugin maps
OmniRoute /v1/models real input_modalities/context_length/max_output_tokens into
llm-pi-ai.providers.<route>.models; a single check applies immediately, no restart needed.
What it does
- Filter by vendor: the namespace prefix of a model id (the part before the first
/, e.g.
opencode-go/deepseek-… → opencode-go) is parsed out; the UI has a "Vendor" dropdown and a
vendor column to filter/view by vendor (opencode, oc, auto, github, no namespace…).
- Switch by route (DSH provider): auto-enumerates every configured route under
llm-pi-ai.providers (route, displayName, api, baseURL, model count, OpenAI-compatible or not);
the top "Route" dropdown switches which endpoint's models you manage.
- One click pulls the provider's
/v1/models (default http://localhost:20128/v1), giving each
model's input (text/image, derived from input_modalities/capabilities.vision),
contextWindow, maxTokens.
- Adds an "OmniRoute model manager" page to the DSH settings panel: search box + modality filter +
select-matching/clear-all + per-row checkbox.
- "Save selected" replaces
llm-pi-ai.providers.<route>.models in one go (DSH serves exactly the
checked ones), written through the official settings seam into settings.yaml and effective on the
next request; sibling fields like apiKeyEnv/api/baseURL are preserved.
- Enabled models are pre-checked, and on re-pull the stored value wins (it does not override
modalities/capacities you hand-edited in
settings.yaml).
- Modality keeps only
text/image (what DSH understands); video/audio etc. are clipped so the
plugin never writes modalities DSH cannot handle (and thus fails validation).
- Web search: wires DSH's built-in
web_search to one of two sources, selected in the Web search card — the OmniRoute aggregate search (POST /v1/search, Tavily/Brave/Exa/Serper/Ollama/…) or the DeepSeek official native search. When the OmniRoute source is disabled, or the source is set to DeepSeek official, web_search automatically falls back to DeepSeek's official search instead of failing. For the OmniRoute source, the key is optional (OmniRoute uses its own per-provider stored keys) but if your endpoint requires one it resolves in this order: literal searchApiKey → DSH credentials ref named by searchApiKeyEnv → process env (same pattern as the official dsh-web-search-deepseek).
API key requirement (model provider vs. search)
Every OmniRoute call now needs a valid key — since OmniRoute 3.8.50 even
GET /v1/models (the model catalog) rejects anonymous requests with 401
(REQUIRE_API_KEY does not change this).
- Pulling the catalog / saving the whitelist: the plugin resolves the route's
apiKeyEnv through the DSH credential store first (the exact seam llm-pi-ai
uses for chat), then the process env, then the ?apiKey= query parameter.
Store the OmniRoute gateway token once as a DSH credential (or set the env
var) and both the catalog and chat work.
- Actually chatting: DSH's
llm-pi-ai adapter (via @earendil-works/pi-ai)
requires a non-empty key and throws No API key for provider: <route>
otherwise. Fill the provider's API key field (a DSH credential ref) in the
"Models" settings. pi-ai also accepts a provider-level
headers.authorization, but that is the non-standard path, not recommended.
For the web search provider the key is genuinely optional (OmniRoute serves
POST /v1/search anonymously and uses its own stored upstream keys) — see the
Web search bullet above.
Internals
- Host (
src/index.ts): registers two same-origin JSON routes (ctx.webServer.register):
GET /omniroute-models/api/catalog?provider=<route> — enumerates the llm-pi-ai provider
directory (providers) → reads the route's current models → requests GET {baseURL}/models →
returns { configured, compatible, provider, displayName, api, baseURL, providers:[...], models:[{id,name,input,contextWindow,maxTokens,enabled}], enabledCount, totalCount }; returns compatible:false only when the route protocol cannot be listed through an OpenAI-shaped /v1/models; anthropic-messages/openai-responses are pulled just like openai-completions (the OmniRoute gateway's model catalog is protocol-agnostic and always OpenAI format).POST /omniroute-models/api/apply — { provider, models:[{id,name,input,contextWindow,maxTokens}] },
validated then written via ctx.settings.mutate('llm-pi-ai', [{op:'set', path:['providers',provider,'models'], value}], expectedRevision);
conflicts return SETTINGS_CONFLICT, schema rejection returns settings-rejected.- The component does not register/own the
llm-pi-ai namespace (that is the adapter
@deepseek-ai/dsh-llm-pi-ai's); it only reads/writes an existing namespace.
- Client (
src/client/index.tsx): subscribes the settings.section slot (id omniroute-models, order 15),
renders a React table; all data goes through same-origin fetch, no ctx.api/LLM remote.
- Web search provider (
src/index.ts): owns the omniroute-models settings namespace for search config and, when enabled, registers a ctx.web WebSearchProvider (id omniroute) so DSH's web_search uses OmniRoute; config/test routes GET|POST /omniroute-models/api/search-config and POST /omniroute-models/api/search-test. The section is registered via installSettingsSection (which waits for the settings service), so the plugin's activation order never races it; available() only requires enabled + an http(s) base URL, and the key is resolved lazily per request.
- Only chat-capable models are listed: the gateway
/v1/models can mix in /video/image-generation
entries; the host's filters by () so they are
never mis-listed/mis-saved as text chat models. OmniRoute ≥3.8.50 additionally lists its search
engines as pseudo models (, , …) with no ; those are
filtered by their vendor suffix.
i18n
- Uses DSH's official locale mechanism (
@deepseek-ai/dsh-client-locale), namespace omniroute-models.
- Dictionaries live in
src/client/locales.ts: zh is the key-set source of truth; en: Record<OmniKey,string>
is compile-checked complete.
- The client sets
inject = ['slots','locale']; apply calls ctx.effect(() => ctx.locale.register(NS, { zh, en })),
then ctx.locale.bind(NS) for t; the settings.section registers with inject: () => ({ t }) and
label: () => t('nav'); the section reads copy from props.t and refreshes when the language switches
(DSH settings → Language).
- Host message localization: the deterministic catalog/apply messages return a
code (e.g. catalog.notConfigured,
apply.duplicateId) plus params, keeping the Chinese message for curl/development; the client's hostMessage
only translates known code (host.* keys), so SETTINGS_CONFLICT/settings-rejected exception codes are not mis-translated.
- Add a third language: add the dictionary in
locales.ts, add it to dictionaries, and add the locale to the
registration loop in apply.
Build
# Dev prerequisites: install build tooling, then point @deepseek-ai runtime types at the DSH harness
pnpm install && pnpm link:dev
npm run build # host → lib/index.js
npm run build:client # client → lib/client.js
Install / inject
- In this environment (super-injector):
dev_inject_plugin /path/to/dsh-omniroute-models, host+client applied immediately.
- Production bundle (GitHub, pinned):
dsh plugin --profile web add github:publieople/dsh-omniroute-models#v0.2.5, then restart the target profile.
Usage
- Refresh the DSH page (runtime-injected client modules only bootstrap after a page reload).
- Open "Settings" → the "OmniRoute model manager" entry appears on the right.
- Search / filter by modality / check the models to use (vision models show a
text + image badge).
- Click "Save selected" → writes
llm-pi-ai.providers.omniroute.models in settings.yaml.
- Send a message with a just-checked model to verify (vision models can attach an image).
Verify
- host:
curl "http://127.0.0.1:3080/omniroute-models/api/catalog" should return the model list + modalities + enabled.
- write:
curl -X POST .../api/apply -d '{"provider":"omniroute","models":[{...}]}'.
- check
~/.dsh/settings.yaml's llm-pi-ai.providers.omniroute.models (with input/contextWindow/maxTokens, siblings preserved).
