README
dsh-search-failover
DeepSeek Harness (DSH) 原生 provider 级智能搜索 / 抓取池
直连检索端点,模型 Token = 0 · 多源容灾 · 加权轮询 · 额度感知熔断 · AI 自主换源 · 现代卡片流 Web GUI
为什么不用官方默认搜索?
DSH 默认通道 deepseek-official 不是专用搜索 API:每次 web_search 都会发起一轮完整 Messages 模型调用,由 DeepSeek 在服务端执行搜索。这意味着:
官方 deepseek-official |
本插件 search-pool |
|
|---|---|---|
| 检索方式 | 一整轮 LLM 调用 + 服务端 web_search 工具 |
直连 Exa / Tavily / Jina / Firecrawl 等检索端点 |
| 模型 token | 每次搜索都烧(input + output),结果还会回灌上下文 | 0(纯检索,不碰任何 LLM) |
| 计费来源 | DEEPSEEK_API_KEY 余额 |
各引擎自己的免费额度 |
抓取 web_fetch |
同样走官方通道 | 同步接管:Jina Reader / Exa Contents / Tavily Extract / Firecrawl Scrape |
| 宕机 / 额度耗尽 | 整条链路挂掉 | 熔断冷却 + 自动下探下一个引擎 / 下一个 Key |
装上即把 searchProvider 与 fetchProvider 都指到 search-pool。卸载后自动回落到官方通道。
✨ 核心特性
- 🛡️ Provider 级透明替换:无侵入接管 DSH
ctx.web的 搜索 + 抓取,保持原生web_search/web_fetch工具签名不变。 - 🔄 双重路由策略:
- 优先顺序 (Failover):按优先级从高到低依次尝试,前一个后端失败或熔断自动下探下一个。
- 加权轮询 (Weighted Rotate):按 1~10 权重将搜索流量平摊到所有健康引擎,最大化榨干各大搜索源的免费额度。
- ⚡ 智能额度感知与熔断器 (Circuit Breaker):
- 遇到额度耗尽(HTTP 402/429/Quota Exceeded)→ 长冷却 (1h),避免无效请求;
- 遇到临时网络抖动(Transient Error)→ 5 分钟内连续 3 次失败触发 短冷却 (60s);
- 冷却到期自动半开探活,成功立即恢复。
- 🤖 AI 自主换源技能 (
web_search_from):- 为 Agent 注入专属换源工具。当 AI 认为默认结果不够理想、信息过时或源单一时,可自主选择
exa/serper/tavily/jina/firecrawl等引擎重新搜索并对比。
- 为 Agent 注入专属换源工具。当 AI 认为默认结果不够理想、信息过时或源单一时,可自主选择
- 🎛️ 现代卡片流 Web GUI 设置面板:
- 在 DSH 设置页一键填写/修改 API Key、切换策略、拖拽排序、测试连通性,保存即实时生效,无需重启进程。
- 密钥安全保存在本地
~/.dsh/settings.yaml,绝不上报。
- 🔑 单引擎多 Key 轮换:同一后端可换行或逗号填多个 Key;Key A 额度耗尽先切 Key B,全部挂了才熔断下探下一个引擎。
- 🔌 全生态适配:
- 搜索:Exa, Serper, Tavily (keyless 匿名档), Jina, SerpApi, Firecrawl, SearXNG (自托管), DuckDuckGo, Brave
- 抓取:Jina Reader (
r.jina.ai) · Exa Contents · Tavily Extract · Firecrawl Scrape
🏗️ 架构概览
┌──────────────────────────────────────────────────────────────┐
│ AI Agent / User Chat │
└──────────────┬────────────────────────────────┬──────────────┘
│ (默认搜索 / 抓取) │ (显式换源)
▼ ▼
┌──────────────────────────────┐ ┌─────────────────────────────┐
│ 原生 web_search / web_fetch │ │ web_search_from (增强工具) │
└──────────────┬───────────────┘ └──────────────┬──────────────┘
│ │
▼ ▼
┌──────────────────────────────────────────────────────────────┐
│ SearchPoolProvider (search-pool) │
│ │
│ [调度决策] │
│ ├── 指定源 (source): 直连指定引擎, 不走池 │
│ ├── Failover: 按 priority 升序依次尝试 │
│ └── Rotate: 按 weight 展开加权轮转 │
│ │
│ [熔断与健康守护] │
│ ├── CircuitBreaker 监控各后端健康度 │
│ └── 额度耗尽(1h 冷却) / 瞬时错误(60s 冷却) / 探活恢复 │
└──────────────────────────────┬───────────────────────────────┘
│
┌──────────┬──────────┬─────┴────┬──────────┬──────────┬──────────┐
▼ ▼ ▼ ▼ ▼ ▼ ▼
┌─────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌─────────┐┌─────┐ ┌─────────┐
│ Exa │ │Serper│ │Tavily│ │ Jina │ │Firecrawl││Serp-│ │ SearXNG │
│ │ │ .dev │ │(Anon)│ │ AI │ │ .dev ││ Api │ │ (Local) │
└─────┘ └──────┘ └──────┘ └──────┘ └─────────┘└─────┘ └─────────┘
🎛️ 设置面板实机预览
- 实时密钥填写:随时填写或更新各引擎 API Key(支持多行多 Key),点击保存立即热生效。行内「↗」直达各引擎申请页。
- 网页抓取接管:
web_fetch同步走搜索池(Jina Reader / Exa / Tavily / Firecrawl),享受同一套熔断与多 Key。 - 一键测试连接 (▶ 测试):对指定后端发起 1 条测试搜索,毫秒级反馈连通状态与响应耗时。
- 动态优先级调整 (↑ / ↓):通过按钮调整引擎在 Failover 链中的优先级。
- 轮询权重调节:在轮询分摊模式下,为不同引擎设置 1~10 权重值。
- 添加自定义后端:无需改写代码或配置文件,直接在界面添加 SearXNG 实例或新后端。
- 额度余量透视:行内直接显示支持额度查询的后端(如 SerpApi)的套餐类型、剩余次数及重置日期。
🚀 快速开始
1. 安装插件
在你的 DSH 项目或 Web Profile 下安装:
# 方式 A: 从 npm 安装 (推荐)
dsh plugin --profile web add dsh-search-failover
# 方式 B: 本地克隆软链调试 (开发者)
git clone https://github.com/Walvez/dsh-search-failover.git
dsh plugin --profile web add link:$(pwd)/dsh-search-failover
2. 启用配置
在 cordis.patch.yml 中声明挂载与默认后端配置:
更多「網頁與瀏覽器」外掛
anysearch-dsh
作者 anysearch-team
為 DeepSeek Harness 提供的 AnySearch 網頁搜尋提供方與高階搜尋工具。
dsh-find-plugin
作者 awesome-dsh-plugin
Find DSH plugins inside the agent — live GitHub dsh-plugin topic search, star-ranked / 會話內搜尋發現 DSH 外掛
fnos-dsh
作者 fnosp
DeepSeek Harness應用與harness外掛 monorepo
modsearch
作者 liustack
🥇 The strongest free web search plugin for DeepSeek Harness, and the search bridge for every model without native web access. Free, no signup, no API key. Ask the web or X, get structured JSON evidence. | 🥇 全網最強的 DeepSeek Harness 免費聯網搜尋外掛,免費免註冊免 API key。為不能聯網的模型補上搜索,問網頁或 X,拿回結構化 JSON 證據(搜尋、抓取、引用)。
