前言¶
在 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。
