前言¶
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。
