dsh-search-router

English · 中文

A tiny DeepSeek Harness (DSH)
plugin: one native WebSearchProvider registered into ctx.web, forwarding
every web_search call to a search backend you choose — with sequential
fallback when one fails. The model keeps seeing the same web_search tool; no
new tools, no MCP, no reranking, no caching.

DSH Agent → web_search → ctx.web → dsh-search-router → Exa / Tavily / Brave / SearXNG

Supported providers

SearXNG keeps the router fully self-hostable — no commercial API needed. The
instance must enable the json output format (search.formats in its
settings.yml). DuckDuckGo is keyless, so a zero-configuration deployment
still serves web searches out of the box. Provider endpoints (and the
Perplexity/DeepSeek model) can be overridden per provider (see the full
schema below).

Install

dsh plugin --profile web add github:XGrin/dsh-search-router
dsh web

Or clone and link locally (for development):

git clone https://github.com/XGrin/dsh-search-router.git
dsh plugin --profile web add link:/path/to/dsh-search-router

The composition patch points the web seam at the router, disables the built-in
DeepSeek search provider, and re-enables the web_search tool in the web
profile. Uninstall (dsh plugin --profile web remove dsh-search-router)
restores the original composition.

Configure

Two ways, targeting the same knobs — the GUI wins per field, and a GUI reset
re-inherits the composition value. With zero configuration the router
auto-detects every provider whose key or endpoint is ambient, in canonical
order: exa → tavily → brave → perplexity → deepseek → searxng → duckduckgo.

In the app

Settings → Plugins → Plugin configuration shows a "Search router" card:
one row per active provider, numbered by fallback priority and draggable to
reorder (also keyboard-reorderable), an inline editor per provider, an
add-provider flow, and an Advanced fold (timeout, empty-results policy). Every
change applies live — no restart.

API keys entered here persist in the settings document as secrets and
override the environment variables; clearing a stored key falls back to
EXA_API_KEY / TAVILY_API_KEY / BRAVE_SEARCH_API_KEY.

In the composition

The profile's own patch layer — $DSH_HOME/profiles/web/cordis.patch.yml
(create it if absent). A patch replaces the row's whole config, so state the
complete block. Two examples:

# Tavily, falling back to a self-hosted SearXNG
- id: search-router
  config:
    order: [tavily, searxng]
    providers:
      tavily: { apiKeyEnv: TAVILY_API_KEY }
      searxng: { baseUrl: https://search.example.com }

# SearXNG only — no commercial keys anywhere
- id: search-router
  config:
    provider: searxng
    providers:
      searxng: { baseUrl: http://127.0.0.1:8888 }

Full schema:

- id: search-router
  config:
    provider: exa                  # single-provider mode (XOR with order)
    order: [exa, tavily, searxng]  # fallback-chain mode
    timeoutMs: 10000               # per-provider timeout (default 10000)
    emptyResultsFallback: true     # 0-result success counts as failure (default true)
    providers:
      exa:        { apiKey: …, apiKeyEnv: EXA_API_KEY, baseURL: … }
      tavily:     { apiKey: …, apiKeyEnv: TAVILY_API_KEY, baseURL: … }
      brave:      { apiKey: …, apiKeyEnv: BRAVE_SEARCH_API_KEY, baseURL: … }
      perplexity: { apiKey: …, apiKeyEnv: PPLX_API_KEY, baseURL: …, model: sonar }
      deepseek:   { apiKey: …, apiKeyEnv: DEEPSEEK_API_KEY, baseURL: …, model: deepseek-v4-flash }
      searxng:    { baseUrl: …, baseUrlEnv: SEARXNG_BASE_URL }
      duckduckgo: { baseURL: … }

Prefer apiKeyEnv over a literal apiKey in files you might commit.

Fallback

A provider counts as failed on network errors, timeouts, any non-2xx status,
unparseable responses — and by default on empty results
(emptyResultsFallback: false to change). The router walks the chain in order
and returns the first success; the model never sees the earlier failures. If
every provider fails, web_search throws one aggregated, key-free error:

search-router: all configured search providers failed:
- exa: HTTP 429
- tavily: timeout after 10000ms
- searxng: HTTP 503

Development

node test/integration.mjs /path/to/a/dsh/installation/node_modules   # router vs. the real seam, mocked providers
node test/client-smoke.mjs                                          # browser bundle, the way the shell loads it

MIT.