DeepSeek Harness 搜索故障轉移插件

DeepSeek Harness 插件 DeepSeek DSH dsh-web-search-failover 聯網工具 故障轉移 2026-10-23

前言

DeepSeek Harness（DSH）在 ctx.web seam 上每次只解析一個 search provider，provider 也只有一個 model 字段，沒有失敗重試鏈。一旦上游出錯（HTTP 錯誤、沒有 web_search_tool_result 結果塊或返回空結果），整次搜索就失敗。new-api 的自動換渠道只在“同一個模型名有多個渠道”時生效，要麼在網關造別名，要麼在 harness 側做故障轉移。本插件選後者：保持網關上的官方模型名，通過順序嘗試多個後端，在任一後端失敗時自動切換到下一個，直到所有後端都失敗才報錯。

這是什麼

dsh-web-search-failover 是 DeepSeek Harness 的聯網工具類插件，由維護者 xingzoudefengye 提供。它註冊了一個 deepseek-failover provider，按順序嘗試一組搜索後端。當主後端失敗或返回空結果時，插件會自動切換到下一個後端，直到所有後端都嘗試完。插件通過 patch 自身禁用默認的 web-search-deepsearch 行，無需手動編輯 profile。插件本身純 JS、無構建步驟，依賴 DSH ≥ 0.2.1 與 Node ≥ 22。

核心功能

  • 註冊 deepseek-failover provider，替換默認搜索 provider。
  • 支持有序後端列表，第 0 個優先，後續爲備胎。
  • 失敗判定：拋錯、成功但沒有 sources，但不處理 WEB_ABORTED（用戶取消）。
  • 通過 backends 配置項逐個構造 provider，每項獨立指定 model、baseURL 和 apiKeyEnv。
  • 通過 cordis.patch.yml patch 自身，禁用默認 web-search-deepseek 行。
  • 插件無構建步驟，純 JS，不會觸發 pnpm 的 allowBuilds 攔截。

安裝與啓用

前置條件：

  • DSH ≥ 0.2.1
  • Node ≥ 22，且 pnpm 在 PATH 上
  • 能訪問 https://codeload.github.com
  • 一個 OpenAI/Anthropic 兼容的搜索網關及其 API key

在 web profile 下安裝：

dsh plugin --profile web add github:xingzoudefengye/dsh-web-search-failover

Windows 上完全一樣：

dsh plugin --profile web add github:xingzoudefengye/dsh-web-search-failover

安裝後必須重啓 DSH（關掉 dsh web 的終端再重新起）。插件在 host 啓動時 import，不重啓不會生效。

Desktop 版 profile 名是 desktop，需要先完全退出應用再加：

dsh plugin --profile desktop add github:xingzoudefengye/dsh-web-search-failover

憑據配置

插件的 apiKeyEnv 指向一個憑據引用名，不是明文。把網關令牌寫入 harness 的憑據文件：

  • macOS / Linux：~/.dsh/.credentials.yaml
  • Windows：%USERPROFILE%\.dsh\.credentials.yaml

示例：

refs:
  NEWAPI_API_KEY: sk-...

該文件由 harness 的 credentials 插件注入，不需要寫系統環境變量。如果更習慣環境變量，可以把 apiKeyEnv 改成對應的變量名。

配置示例

在 profile 的 cordis.patch.yml 裏覆蓋 id: web-search-failover 的 config。插件默認順序爲 deepseek-v4-flash → claude-haiku-5-5，不覆蓋則按此走：

- id: web-search-failover
  config:
    providerId: deepseek-failover   # ctx.web 選中的 provider 名，一般不用改
    backends:
      - { model: deepseek-v4-flash,  baseURL: https://your-gateway/v1, apiKeyEnv: NEWAPI_API_KEY }
      - { model: claude-haiku-5-5,   baseURL: https://your-gateway/v1, apiKeyEnv: NEWAPI_API_KEY }

配置項說明：

鍵 默認 作用
providerId deepseek-failover 註冊給 ctx.web 的 provider 名；bundle patch 裏 web.searchProvider 必須與它一致
backends — 有序列表，第 0 個優先，其後都是備胎；每項 model / baseURL / apiKeyEnv 各自獨立
apiKeyEnv / baseURL / apiKey / apiVersion / maxTokens / maxUses 見 lib/index.js 的 Config 舊式單後端字段；用 backends 時不需要，插件按 backend 逐個構造 provider

失敗判定：拋錯、或成功但沒有 sources。WEB_ABORTED（用戶取消）直接向上拋，不換後端。全部失敗才返回最後一個錯誤；如果所有後端都成功但確實沒結果，返回那個空結果。

驗證安裝

執行以下命令，應看到 searchProvider: deepseek-failover：

dsh --profile web --dump-config | grep -A3 "searchProvider"

PowerShell：

dsh --profile web --dump-config | Select-String -Pattern "searchProvider" -Context 0,3

再做一次真實搜索，網關日誌裏會出現主後端的模型名；只有主後端失敗時纔會多一條備用後端。

注意：插件自帶的 cordis.patch.yml 裏 baseURL 寫的是示例網關（http://43.133.21.227:3000/v1），請改成你自己的網關地址。

適用場景與注意

  • 適合需要多個搜索後端、希望自動切換的場景，如主後端不穩定或需要混合使用不同模型進行搜索。
  • 插件以當前 dsh 進程的權限運行，安裝前建議檢查源碼與許可證。
  • 插件不處理 WEB_ABORTED，用戶取消不會觸發備用後端。
  • 舊式單後端字段（apiKeyEnv、baseURL 等）在配置 backends 時不需要。

卸載

dsh plugin --profile web remove dsh-web-search-failover

然後重啓 DSH。bundle 的 patch 隨之失效，harness 原有的 web-search-deepsearch 行會恢復；如果你之前手工在 profile patch 裏刪過它，需要自己加回來。

同步到另一臺機器

邏輯全在插件裏，換機器不需要搬配置，但要滿足四件事：

  1. 裝插件：運行 dsh plugin add github:xingzoudefengye/dsh-web-search-failover。版本自動跟 master 最新提交，兩臺機器不必同 commit，但 harness 版本要一致（都 ≥ 0.2.1）。
  2. 憑據：.credentials.yaml 的 refs: 裏要有 NEWAPI_API_KEY。
  3. 清掉舊的 provider 行：profile patch 裏若還有 - id: web-search-deepsearch，刪掉。
  4. 網關可達：baseURL 換成本機可訪問的地址。

排錯

現象 原因 處理
dsh plugin add 成功，但搜索行爲沒變 插件在 host 進程啓動時 import，進程裏的模塊不會熱替換 重啓 DSH（關掉 dsh web 再起）
改了插件源碼（哪怕是 lib/index.js）也不生效 Node 的 ESM 緩存：已 import 的模塊不會重新執行 同上，重啓 host；GitHub 安裝還需先 dsh plugin add 重裝以拉新代碼
dsh plugin add 卡住或報網絡錯誤 拉的是 codeload.github.com 的 tarball，公司網絡/代理常攔 走代理，或把倉庫整目錄拷過去，依賴改成 file: 路徑後 pnpm install（插件無外部 npm 依賴，離線可裝）
報 WEB_PROVIDER_UNAVAILABLE 所有 backends 都 available() === false，通常是 apiKeyEnv 指向的引用沒有值 檢查 .credentials.yaml 的 refs: 裏有該鍵，且鍵名與 apiKeyEnv 完全一致
搜索一直是備用後端的模型 主後端失敗但未報錯（返回空結果也會觸發回落） 看網關日誌確認主後端返回碼；密鑰額度、模型名拼寫是最常見原因
配置樹裏出現同一個 row id 衝突（web-search-deepsearch 被兩處同時聲明） profile patch 裏手工加過 id: web-search-deepsearch 的行，與 bundle patch 打架 刪掉 profile 裏那一行，插件自帶的 patch 已負責禁用它

開發

本倉庫是純 JS、無構建步驟。倉庫裏沒有 node_modules，直接 npm test 會因爲找不到 @deepseek-ai/* 的 peer 依賴而失敗 —— 先把本機已安裝的 harness 包鏈進來：

node scripts/dev-link.mjs            # 探測 dsh 的安裝位置，鏈入 schemastery / dsh-web / dsh-web-search-deepseek 等
npm test                             # node --test

dev-link 依次探測：dsh 可執行文件所在的 npm 目錄、$DSH_HOME/profiles/<profile>、$DSH_HOME/profiles、$DSH_HOME，也可以用第一個參數或 DSH_PACKAGE_DIR 直接指定 @deepseek-ai/dsh-* 所在目錄。Windows 上用 junction，不需要管理員權限。

改完代碼在本地驗證，再裝到 profile：dsh plugin --profile web add <本倉庫絕對路徑> 走 link: 依賴，配合 dev-link 即可改完重啓 host 就看到效果。

生態背景

DeepSeek Harness 的理念是「一切皆插件」，社區目錄 SkillHub 與 DeepSeek / 幻方無官方從屬關係，僅作爲插件索引與展示。本插件遵循 MIT 許可證，由維護者 xingzoudefengye 維護。

相關插件

同作者、同一套安裝方式（dsh plugin add github:xingzoudefengye/<repo>）：

結語

本插件通過有序後端列表與自動切換機制，解決了 DeepSeek Harness 單一搜索 provider 失敗導致整次搜索失敗的問題，適合需要高可用搜索能力的場景。更多細節與源碼請參考：GitHub | SkillHub 目錄頁

相關文章

快速從零部署一個DeepSeek-R1服務 2025-04-05 使用 dsh-anchored-standard 爲 DeepSeek Harness 配置兩階段 Agent 預設 2026-08-17 用 dsh-web-ui 把 DeepSeek Harness 網頁界面補成工作臺 2026-08-17 用 modlens 給 DeepSeek Harness 的純文本模型補上視覺 2026-08-17 用 dsh-TUI 給 DeepSeek Harness 補上全屏終端界面 2026-08-17
羽毛球分组比赛记分
小程序二维码

欢迎使用《羽毛球分组比赛记分》微信小程序

小夜