前言¶
在 DSH 插件體系裏，搜索和抓取通常會依賴具體後端。如果只使用一個後端，或者一個後端只綁定一個 Key，遇到額度耗盡、網絡抖動、後端不可用時，上層調用會直接受影響。
dsh-search-failover 是 Walvez 維護的 DSH 插件，用於在 provider 級接管 ctx.web 的搜索與抓取，把多個搜索 / 抓取後端放進同一個池裏調度。
這是什麼¶
dsh-search-failover 是 DeepSeek Harness（DSH）原生 provider 級智能搜索 / 抓取池。
它保持原生 web_search 與 web_fetch 工具簽名不變，在底層替換搜索與抓取的實際 provider。插件使用 MIT 許可證，要求：
Node.js >=22
核心功能¶
下面介紹已覈實的能力。
Provider 級透明替換¶
插件無侵入接管 DSH ctx.web 的搜索 + 抓取，保持原生工具簽名不變：
web_search
web_fetch
雙重路由策略¶
插件提供兩種路由策略：
-
優先順序 Failover
按優先級順序嘗試後端，前一個後端失敗或熔斷後，下探下一個後端。 -
加權輪詢 Weighted Rotate
按權重將搜索流量分配給不同後端。
智能額度感知與熔斷器¶
熔斷器用於處理額度耗盡和瞬時錯誤：
額度耗盡：長冷卻 1h
瞬時錯誤：短冷卻 60s
冷卻到期：半開探活
AI 自主換源技能¶
插件提供 web_search_from 技能。AI 可自主選擇以下引擎重新搜索並對比：
exa
serper
tavily
jina
firecrawl
Web GUI 設置面板¶
插件提供現代卡片流 Web GUI 設置面板，可用於：
- 填寫 / 修改 API Key
- 切換策略
- 拖拽排序
- 測試連通性
保存即即時生效，無需重啓進程。
單引擎多 Key 輪換¶
同一後端可填寫多個 Key。某個 Key 額度耗盡時，先切下一個 Key。
搜索後端支持¶
已覈實的搜索後端支持：
Exa
Serper
Tavily
Jina
SerpApi
Firecrawl
SearXNG
DuckDuckGo
Brave
抓取支持¶
已覈實的抓取支持：
Jina Reader
Exa Contents
Tavily Extract
Firecrawl Scrape
密鑰本地保存¶
密鑰安全保存在本地路徑：
~/.dsh/settings.yaml
README 標註絕不上報。
安裝與啓用¶
先安裝插件，再修改配置，最後啓動 DSH Web。
安裝插件¶
在 DSH 項目或 Web Profile 下執行：
dsh plugin --profile web add dsh-search-failover
聲明掛載與默認後端配置¶
在 cordis.patch.yml 中聲明掛載與默認後端配置。下面示例設置策略、返回條數上限、超時、後端列表和熔斷參數：
- 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
配置項說明：
strategy: failover / rotate
maxResults: 默認返回條數上限
timeoutMs: 單個請求超時時間
backends: 後端列表
circuit: 熔斷參數
啓動 DSH Web¶
執行：
dsh web
打開 Web GUI，默認地址：
http://127.0.0.1:3080
進入「設置 → 搜索池」，即可在界面直接管理所有 Key。
本地調試¶
如果需要本地克隆軟鏈調試，先克隆倉庫，再掛載當前目錄：
git clone https://github.com/Walvez/dsh-search-failover.git
dsh plugin --profile web add link:$(pwd)/dsh-search-failover
適用場景與注意¶
適合以下情況：
- 需要同時配置多個搜索後端
- 需要同一引擎多 Key 輪換
- 需要搜索和抓取共用一套調度與熔斷
- 需要在 Agent 側顯式選擇不同搜索引擎
- 需要接入自託管 SearXNG
注意：
- 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。
- Node.js 要求：
>=22
- 部分後端需要 API Key；Tavily 支持無 key 匿名檔；SearXNG 爲自託管實例。
- 部分後端僅支持搜索，不支持抓取，如 Serper 與 SerpApi。
- opencodex sidecar 可選且默認不啓用，需要時本機運行 opencodex。
- 已覈實資料中的額度參考表不完整，本文不展開具體額度。
結尾¶
經過上面的步驟，dsh-search-failover 可以把 DSH 的搜索與抓取整理成 provider 級池：策略可切換、Key 可輪換、後端可熔斷，GUI 可直接維護。
GitHub：
https://github.com/Walvez/dsh-search-failover
目錄頁：已覈實資料未提供可驗證 URL。
