前言¶
DeepSeek Harness（DSH）通過 ctx.web 暴露統一的網頁能力，web_search 是其中常用的一環。若你只想用自建或本地 SearXNG 聚合多引擎、且不想爲搜索單獨申請 API Key，又希望 SearXNG 宕機、超時或 5xx 時對話裏的搜索不要直接斷掉，就需要在公開 seam 上掛一個 provider，而不是改 DSH 源碼。
下面介紹社區插件 @clinkai/dsh-web-search-searxng（倉庫 w384/clinkai-dsh-web-search-searxng）。它把 SearXNG 接到 DSH 的 web_search，並可選地在失敗時回退到內置 DeepSeek 搜索。插件由維護者 w384 發佈，當前 package 版本爲 0.2.0，許可證 MIT。DSH 社區插件目錄見 SkillHub 條目；目錄站與 DeepSeek / 幻方無官方從屬關係，安裝前仍建議自行閱讀源碼與許可證。
這是什麼¶
一句話：面向 DSH web profile 的 SearXNG 搜索 provider 包，通過 dsh.bundle.patch 掛載到 Cordis 層，不 patch DSH 源碼、也不依賴 DSH 內部 export，因此 DSH 升級不會覆蓋你的插件層。
一個包在公開 seam 上註冊兩個 provider id，用 web.searchProvider 選用哪一個：
| provider id | 行爲 |
|---|---|
searxng |
純 SearXNG：GET {baseUrl}/search?q=<query>&format=json |
search-fallback |
先走 SearXNG；後端不可用、掛起、5xx，或（可選）空結果時，按 fallbackProvider 重試 |
README 說明：無需 API Key、無計費（SearXNG 側聚合多引擎）；search-fallback 在 Docker/SearXNG 不可達時可透明使用內置 DeepSeek 搜索。回退路徑要求 searxng 與 deepseek-official 等對應 provider 在 seam 註冊表中均已註冊（通常由各自插件提供）。
核心功能¶
兩個 provider 的分工¶
searxng：所有請求只打你配置的 SearXNGbaseUrl，適合已穩定運維實例、且接受 SearXNG 失敗時直接報錯的情況。search-fallback：在連接失敗、超時、HTTP 5xx，以及配置fallbackOnEmpty: true時的空結果場景下，由調度器走fallbackProvider（默認deepseek-official）。調用方取消、4xx 等會原樣透傳，不會誤觸發回退。
配置項（插件實例 web-search-searxng）¶
| key | 默認值 | 含義 |
|---|---|---|
baseUrl |
http://127.0.0.1:8080 |
SearXNG 地址 |
timeoutMs |
15000 |
單次 SearXNG 請求超時 |
fallbackEnabled |
true |
是否註冊 search-fallback provider |
fallbackProvider |
deepseek-official |
回退時使用的 provider id |
fallbackOnEmpty |
false |
是否把 SearXNG 空結果視爲失敗並回退 |
運行環境¶
package.json 要求 Node >=18.17，DSH >=0.1.5-rc.2 <1.0.0；peer 含 @deepseek-ai/dsh-web（可選）等。插件以當前 DSH 進程權限運行，SearXNG 若只監聽本機，需與 DSH 同機或網絡可達。
先跑 SearXNG（Docker）¶
SearXNG 無原生 Windows 支持，README 建議用 Docker Compose。DSH Web GUI 默認佔用 127.0.0.1:8080，因此示例把容器映射到主機 18081，避免端口衝突導致「容器在跑但連不上」。
services:
searxng:
image: searxng/searxng:latest
container_name: searxng
ports:
- "127.0.0.1:18081:8080"
volumes:
- ./config:/etc/searxng:rw
restart: unless-stopped
在 config/settings.yml 中啓用 JSON 格式，否則插件請求的 format=json 無法工作：
search:
formats:
- html
- json
README 中關於引擎的實測說明（非猜測）：國內引擎如 sogou、360search 默認 disabled，不顯式開啓時可能出現「能連上 SearXNG 但默認搜索無結果」；google 在隧道或代理可用時可工作；brave、duckduckgo、quark 等易被 bot 攔截，代理未必能解決。DNS/隧道未就緒時失敗的引擎會被 SearXNG 標記 Suspended 一段時間，下結論前可先重啓容器。可按引擎單獨配代理，例如只對 google 走 host.docker.internal:12000，國內引擎保持直連。
安裝與啓用¶
包內自帶 dsh.bundle.patch，安裝後由 DSH 以 bundle 層掛載 provider，無需手改源碼。
# from npm (once published)
dsh plugin --profile web add @clinkai/dsh-web-search-searxng
# straight from GitHub — no registry needed, the built entry is committed
dsh plugin --profile web add github:w384/clinkai-dsh-web-search-searxng
# from a local checkout, or from a packed tarball
dsh plugin --profile web add link:/path/to/clinkai-dsh-web-search-searxng
dsh plugin --profile web add ./clinkai-dsh-web-search-searxng-0.2.0.tgz
在 $DSH_HOME/profiles/<profile>/cordis.patch.yml 中覆蓋本實例的 SearXNG 地址，並指定 seam 使用的 provider：
- id: web-search-searxng
config:
baseUrl: http://127.0.0.1:18081
fallbackOnEmpty: true
- id: web
config:
searchProvider: search-fallback # or: searxng
經過上面的步驟，啓用 web profile 並重啓或 reload 後，依賴 ctx.web 的 web_search 會走你選的 provider。
典型用法與排錯¶
- 只想自建搜索、可接受 SearXNG 失敗時不回退：
searchProvider: searxng，並保證baseUrl與 Docker 映射一致。 - 本地 SearXNG 爲主、官方搜索兜底：
searchProvider: search-fallback，保留默認fallbackProvider: deepseek-official，並確保官方 web 搜索 provider 插件已安裝。 - SearXNG 常返回空列表：將
fallbackOnEmpty設爲true（上例已示），空結果會觸發回退。
排錯要點來自 README：
- 8080 衝突：主機 8080 已被 DSH Web GUI 佔用時，勿把 SearXNG 映射到 8080；改用
18081並同步baseUrl。 - Windows 保留端口：Hyper-V/WSL NAT 可能佔用端口段，綁定失敗時可執行
netsh interface ipv4 show excludedportrange protocol=tcp排查。
適用場景與注意¶
適合已在 DSH web profile 下開發智能體、希望搜索走本地 SearXNG、又不想維護多套搜索調用邏輯的開發者。search-fallback 適合本機 Docker 偶發停服或引擎不穩定、但仍需對話內搜索可用的場景。
注意：插件不替代你對 SearXNG 引擎列表、代理與合規使用的判斷；SearXNG 與 DSH 均在本機或你控制的網絡內運行，權限等同於運行 DSH 的用戶。社區目錄與 GitHub 星標（截至資料抓取時倉庫爲 1 star）僅作發現入口，不代表官方背書。
結尾¶
@clinkai/dsh-web-search-searxng 在 DSH 公開 web seam 上提供 searxng 與 search-fallback 兩種搜索 provider，配置 baseUrl 與 searchProvider 即可切換；失敗時可按文檔回退到 deepseek-official。詳情與 issue 見 GitHub 倉庫，目錄頁見 SkillHub。
