前言¶
在 DeepSeek Harness（DSH）裏做帶聯網能力的智能體時，ctx.web 的搜索能力通常只綁定一個 search provider id。環境變量 $DSH_WEB_SEARCH_PROVIDER 也只是覆蓋同一字段，源碼註釋寫明 “NOT a hidden priority chain”——宿主本身沒有「先 A 後 B 再 C」的優先級鏈。若本地 Tavily 代理沒起、第三方配額用盡、或某一後端超時，單源配置要麼直接失敗，要麼只能手工改配置換源。
下面介紹的 dsh-cascade-search（維護者 Ryker0716）把三級網頁搜索後端收進單個 provider，按順序自動降級，並附帶圖形化設置頁與 cordis.patch.yml bundle patch。插件歸類爲聯網工具，當前 GitHub 星標爲 0；npm 包版本 1.2.1，許可證 MIT，要求 Node.js >= 22。
這是什麼¶
dsh-cascade-search 是面向 DSH 的插件：爲 Harness 的 web_search 實現三級降級鏈，默認順序爲：
tavily-proxy → querit → deepseek-search-api
本地免費 第三方配額 官方計費 5元/1000次
前一級不可用（未配置、憑據讀取失敗、報錯、超時、或返回 0 條且沒有摘要）時自動嘗試下一級，並寫一條不含密鑰的 warn 日誌。官方 DeepSeek 搜索 API 作爲最後一道防線；每級超時是單次請求的總等待上限（含響應正文），用戶主動取消搜索會立即停止，不會繼續調用後面的後端。
核心功能¶
降級邏輯¶
降級判斷落在插件內部的 lib/cascade.js 引擎中，而非 DSH 宿主。Harness 的 WebRuntime.search() 只解析一個 configuredId；因此「鏈式回退」只能由單個 provider（本插件註冊的 cascade-search）實現。
憑據與配置¶
密鑰經 credentialRef 從 Harness credentials 服務（$DSH_HOME/.credentials.yaml）現取，不緩存；新增密鑰無需重啓。
| 後端 | 默認 ref |
|---|---|
| tavily-proxy | TAVILY_PROXY_AUTH_KEY（代理管理 authKey，不是 tvly-* 池 Key） |
| querit | QUERIT_API_KEY |
| deepseek | DEEPSEEK_API_KEY |
config 中沒有 apiKey 字面量字段，避免密鑰寫入配置文件。
圖形化設置（client 半側）¶
安裝後路徑：插件 → 已安裝插件 → dsh-cascade-search。面板可配置：
- 降級順序（逗號分隔，可重排）
- 接管網頁搜索開關（
adopt） - 每一級的啓用、接口地址、密鑰名稱、密鑰、超時
保存後立刻生效，無需重啓。設置頁由 lib/client.js 註冊到 plugins.bundle.config slot。
adopt：接管默認搜索源¶
dsh.bundle.patch 先於用戶 profile 應用；若 profile 或 GUI 把 web.config.searchProvider 釘成別的 id，會靜默覆蓋插件。插件在 apply() 時通過 volatile 配置引用把自己設爲選中 provider（cascade-search）。同一會話內 GUI 再改搜索源不會覆蓋該選擇；要換策略應改本插件的 order。若希望 GUI 接管，將 adopt 設爲 false，並自行保證 web.config.searchProvider 指向 cascade-search。
設計要點（節選）¶
available()恆返回true，避免 seam 拋出WEB_PROVIDER_CONFIGURED_UNAVAILABLE吞掉各級失敗原因。- 空結果且無摘要才降級；有摘要但暫無來源時保留摘要。
- 取消時不降級，拋出宿主約定的
WEB_ABORTED。 maxResults按後端鉗制：tavily 上限 20，querit/deepseek 上限 50。
安裝與啓用¶
npm 安裝（推薦）¶
在 CLI 管理的 web profile 中執行：
dsh plugin --profile web add dsh-cascade-search
該命令從 npm 下載插件、加入 profile 依賴並自動登記 bundle；不需要事先全局 npm install -g 或改 npm 鏡像。安裝後重啓 DSH，再在插件詳情頁配置憑據與鏈。
備選：從 GitHub 安裝最新源碼：
dsh plugin --profile web add github:Ryker0716/dsh-cascade-search
需要固定版本時優先使用 npm 包 1.2.1。
桌面 profile¶
桌面 profile 不能通過 CLI 改依賴。需編輯 ~/.dsh/profiles/desktop/package.json，在 dependencies 中追加 dsh-cascade-search（可用 link: 指向解壓目錄），在 dsh.profile.bundles 中追加 "dsh-cascade-search"，然後：
cd ~/.dsh/profiles/desktop
CI=true pnpm install --no-frozen-lockfile
只追加本插件，不要覆蓋整個 package.json。
典型配置¶
等價於設置頁的 cordis.patch.yml 片段示例（手改時注意：config 是整體替換，非深合併，改部分字段需寫全整個 config 或使用 GUI）：
- id: cascade-search
name: dsh-cascade-search
config:
order: [tavily, querit, deepseek]
adopt: true
tavilyEnabled: true
tavilyUrl: http://localhost:9100
tavilyCredentialRef: TAVILY_PROXY_AUTH_KEY
tavilyTimeoutMs: 10000
tavilyDepth: basic
queritEnabled: true
queritUrl: https://api.querit.ai/v1/search
queritCredentialRef: QUERIT_API_KEY
queritTimeoutMs: 25000
deepseekEnabled: true
deepseekUrl: https://api.deepseek.com/v1/tools/search
deepseekCredentialRef: DEEPSEEK_API_KEY
deepseekTimeoutMs: 60000
不想用官方 API 兜底時，將 deepseekEnabled 設爲 false，或從 .credentials.yaml 刪除 DEEPSEEK_API_KEY。
適用場景與注意¶
適合誰： 希望在 DSH 智能體或 CLI web profile 中穩定使用網頁搜索、又不想在單一後端故障時手工換源的用戶；已有或可部署本地 tavily-proxy、並願意按需配置 Querit 或 DeepSeek 官方搜索 API 的場景。
運行權限： 插件以當前 DSH 進程權限運行，會發起對外 HTTP 請求並讀取本地憑據庫。安裝前應在 GitHub 倉庫 查看源碼與 MIT 許可證，確認符合你的安全與合規要求。
排障提示： 三級全失敗時錯誤信息會彙總各級原因。例如 tavily-proxy: not configured 多爲缺 TAVILY_PROXY_AUTH_KEY 或代理未監聽 9100；deepseek-search-api: HTTP 404 常因 endpoint 應爲 https://api.deepseek.com/v1/tools/search。
生態說明： DSH 奉行「一切皆插件」；SkillHub 目錄頁 爲社區站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
經過上面的步驟，你會得到一個自帶 GUI、可通過 npm 或 GitHub 安裝的搜索 provider：本地優先、第三方次之、官方 API 兜底，且失敗路徑可觀測。進一步瞭解與提 issue 請訪問：
