Preface

In the DSH plugin ecosystem, search and scraping typically rely on specific backends. If only one backend is used, or a backend is bound to a single Key, upper-layer calls are directly affected when quota exhaustion, network jitter, or backend unavailability occurs.

dsh-search-failover is a DSH plugin maintained by Walvez, designed to take over ctx.web search and scraping at the provider level, pooling multiple search/scraping backends for scheduling.

What is it

dsh-search-failover is a native provider-level intelligent search/fetch pool for DeepSeek Harness (DSH).

It maintains the native web_search and web_fetch tool signatures, replacing the actual providers for search and scraping at the underlying layer. The plugin is licensed under MIT and requires:

Node.js >=22

Core Features

The capabilities verified below are introduced.

Provider-level Transparent Replacement

The plugin non-invasively takes over DSH’s ctx.web search + scraping, keeping the native tool signatures unchanged:

web_search
web_fetch

Dual Routing Strategies

The plugin provides two routing strategies:

  1. Priority Failover
    Tries backends in priority order; if the previous backend fails or is tripped, it proceeds to the next backend.

  2. Weighted Rotate
    Distributes search traffic to different backends based on weight.

Smart Quota Awareness and Circuit Breakers

Circuit breakers are used to handle quota exhaustion and transient errors:

Quota Exhaustion: Long cooldown 1h
Transient Errors: Short cooldown 60s
Cooldown Expiry: Half-open probe

AI Autonomous Source Switching Skill

The plugin provides the web_search_from skill. AI can autonomously select the following engines to re-search and compare:

exa
serper
tavily
jina
firecrawl

Web GUI Settings Panel

The plugin provides a modern card-style Web GUI settings panel, used for:

  • Filling / modifying API Keys
  • Switching strategies
  • Drag-and-drop sorting
  • Testing connectivity

Changes take effect in real-time upon saving; no process restart is required.

Single Engine Multi-Key Rotation

Multiple Keys can be filled for the same backend. When a Key’s quota is exhausted, it switches to the next Key.

Search Backend Support

Verified search backend support:

Exa
Serper
Tavily
Jina
SerpApi
Firecrawl
SearXNG
DuckDuckGo
Brave

Fetch Support

Verified fetch support:

Jina Reader
Exa Contents
Tavily Extract
Firecrawl Scrape

Local Key Storage

Keys are securely stored locally at:

~/.dsh/settings.yaml

The README explicitly states that no reporting occurs.

Installation and Enablement

Install the plugin first, modify the configuration, and finally start the DSH Web.

Install the Plugin

Execute in the DSH project or Web Profile directory:

dsh plugin --profile web add dsh-search-failover

Mount Declaration and Default Backend Configuration

Declare the mount and default backend configuration in cordis.patch.yml. The example below sets the strategy, maximum return count, timeout, backend list, and circuit breaker parameters:

- id: search-pool
  name: dsh-search-failover
  config:
    strategy: failover
    maxResults: 8
    timeoutMs: 15000
    backends:
      - id: exa
        kind: exa
        apiKeyEnv: EXA_API_KEY
        priority: 1
      - id: serper
        kind: serper
        apiKeyEnv: SERPER_API_KEY
        priority: 2
      - id: tavily
        kind: tavily
        apiKeyEnv: TAVILY_API_KEY
        priority: 3
      - id: jina
        kind: jina
        apiKeyEnv: JINA_API_KEY
        priority: 4
      - id: firecrawl
        kind: firecrawl
        apiKeyEnv: FIRECRAWL_API_KEY
        priority: 5
      - id: serpapi
        kind: serpapi
        apiKeyEnv: SERPAPI_API_KEY
        priority: 6
      - id: searxng
        kind: searxng
        baseURL: http://127.0.0.1:8080
        priority: 7
    circuit:
      threshold: 3
      burstWindowMs: 300000
      cooldownMs: 60000
      quotaCooldownMs: 3600000

Configuration Item Explanations:

strategy: failover / rotate
maxResults: Default maximum number of results returned
timeoutMs: Timeout for a single request
backends: List of backends
circuit: Circuit breaker parameters

Start DSH Web

Execute:

dsh web

Open the Web GUI. The default address is:

http://127.0.0.1:3080

Go to “Settings -> Search Pool” to manage all Keys directly in the interface.

Local Debugging

If local cloning and soft-link debugging are needed, clone the repository first and then mount the current directory:

git clone https://github.com/Walvez/dsh-search-failover.git
dsh plugin --profile web add link:$(pwd)/dsh-search-failover

Applicable Scenarios and Notes

Suitable for the following situations:

  • Need to configure multiple search backends simultaneously
  • Need to rotate multiple Keys for the same engine
  • Need to share a set of scheduling and circuit breaking for search and scraping
  • Need to explicitly select different search engines on the Agent side
  • Need to integrate self-hosted SearXNG

Notes:

  1. The plugin runs with the current dsh process permissions; check the source code and license before installing.
  2. Node.js requirements:
    >=22
  1. Some backends require API Keys; Tavily supports anonymous retrieval without a key; SearXNG is a self-hosted instance.
  2. Some backends only support search and not scraping, such as Serper and SerpApi.
  3. opencodex sidecar is optional and disabled by default; run opencodex locally on the machine if needed.
  4. The quota reference table in the verified materials is incomplete; this article does not elaborate on specific quotas.

Conclusion

Following the steps above, dsh-search-failover can organize DSH’s search and scraping into a provider-level pool: strategies are switchable, Keys are rotatable, backends are circuit-breakable, and the GUI allows direct maintenance.

GitHub:

https://github.com/Walvez/dsh-search-failover

Directory page: The verified materials did not provide a verifiable URL.