dsh-web-search-order：DSH 搜索提供方有序降級方案

前言¶

DSH 的 web_search 工具依賴外部搜索提供方（如 exa、deepseek-official）。這些提供方可能因網絡波動、API 限流、憑據錯誤或超時而失敗。DSH 的 seam 沒有提供方級別的超時控制，也沒有內置的自動切換機制。本插件爲 ctx.web 已註冊的提供方增加了一層有序降級邏輯：它不實現搜索後端，也不處理憑據，而是將提供方串成一條鏈。當提供方不可用、報錯、超時或返回空結果時，它會自動切換到下一個提供方，直到找到可用結果或全部失敗。

核心功能¶

實現網絡搜索提供方的有序降級：按配置順序依次嘗試多個搜索提供方。
在已註冊提供方之上工作：讀取並處理 ctx.web 中已註冊的提供方（如 exa、deepseek-official）。
支持配置項：通過 order（優先級）、exclude（排除列表）、timeoutSeconds（超時預算）、fallbackOnEmpty（空結果處理）進行控制。
自動切換機制：當提供方不可用、超時或返回空結果時自動換下一個。
錯誤處理：處理 WEB_PROVIDER_ERROR 和 WEB_PROVIDER_UNAVAILABLE 等錯誤。

安裝與啓用¶

使用官方命令安裝插件。包內自帶 cordis.patch.yml，dsh plugin 會把它追加進該 profile 的 dsh.profile.bundles，啓動時把 web.searchProvider 指到本插件。

安裝命令：

dsh plugin --profile web add github:killcerr/dsh-web-search-order

本地開發：
如果需要修改源碼，使用路徑安裝。修改後重啓 DSH 即可，無需重裝：

dsh plugin --profile web add C:\path\to\dsh-web-search-order

配置與行爲¶

插件支持以下配置項：

order: 提供方 ID 列表，越靠前優先級越高。未點名的提供方按註冊順序接在後面。沒裝（認不出）的 ID 會被忽略，只提示一次。
exclude: 永不嘗試的提供方 ID 列表，優先級高於 order。
timeoutSeconds: 單次嘗試的超時預算（秒）。本插件自行實現此超時，DSH seam 沒有提供方級別的超時。
fallbackOnEmpty: 當既沒有 sources 也沒有回答文本時，是否當作未命中並換下一個。設爲 false 則原樣返回空結果。

版本差異：
* 0.1.5 線：支持在 ~/.dsh/settings.yaml 的 web-search-order 小節配置，熱生效。
* 0.1.6+ 線：在插件行的 config 中配置，設置頁編輯會寫回 profile patch。

兼容性與環境¶

Node.js 版本：需要 Node.js >= 22.19.0。
DSH 版本：聲明兼容性爲 >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0。
- 注意：0.1.7 線使用 config 行配置，不再支持 settings.yaml。
0.2.0+：不再聲明兼容性。

生態背景¶

DSH 理念是「一切皆插件」。本插件屬於社區目錄中的聯網工具類別，由 killcerr 維護，遵循 MIT 許可證。