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
| Provider | Credential | Endpoint |
|---|
| Exa | EXA_API_KEY | https://api.exa.ai |
| Tavily | TAVILY_API_KEY | https://api.tavily.com |
| Brave | BRAVE_SEARCH_API_KEY | https://api.search.brave.com |
| Perplexity | PPLX_API_KEY | https://api.perplexity.ai |
| DeepSeek | DEEPSEEK_API_KEY | https://api.deepseek.com/anthropic/v1 |
| SearXNG | none (self-hosted) | SEARXNG_BASE_URL |
| DuckDuckGo | none | — |
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.
