前言¶
DeepSeek Harness（DSH）在 web profile 里提供 web_search 工具，默认走 DeepSeek API 侧的搜索能力：每次查询会计费，且与 API Key 绑定。若你已有或可部署 SearXNG 元搜索引擎，更希望 Agent 的联网检索走自己掌控的基础设施、且不依赖第三方搜索 API 账号，就需要在 ctx.web 这条 seam 上注册另一套 WebSearchProvider。
下面介绍社区插件 dsh-web-searxng-search（维护者 kkgace，分类：联网工具）。它在 Harness 里挂接自托管 SearXNG 实例，无需 API Key 与厂商账号；内置 web_search 的调用方式不变，由配置切换实际后端。
这是什么¶
dsh-web-searxng-search 是 DSH 的 Cordis 插件：实现 WebSearchProvider 契约，通过 ctx.web.registerSearchProvider 注册搜索提供者，并由 bundle 自带的 cordis.patch.yml 将 web.searchProvider 指向 searxng。搜索请求发往你在 baseURL 中配置的 SearXNG 根地址，读取其 Search API 的 JSON 结果。
- 仓库：kkgace/dsh-web-searxng-search
- 社区目录：SkillHub 插件页
- 许可证：MIT（README 与 package.json 一致）
- 当前 package 版本：0.1.0
插件本身无额外运行时依赖；@deepseek-ai/* 由宿主作为 peer 提供。要求 Node.js >= 22.19，DeepSeek Harness 侧需 @deepseek-ai/dsh-web 0.1.x。
核心功能¶
README 中列出的能力如下，均围绕「替换 provider、不改工具面」：
- 即插即用：在
ctx.webseam 上注册 provider，内置web_search继续可用。 - 可配置检索行为：超时、语言、安全搜索级别、SearXNG categories 与 engines 白名单。
- 结果按 URL 去重：元搜索常返回重复条目。
- 配置错误可区分：实例返回 HTML（未开 JSON）与「无结果」会给出不同提示。
- 生命周期：注册包在
ctx.effect中，卸载与 HMR 可干净回滚。 - 离线测试：仓库含 14 个不依赖网络的单元测试（
npm test）。
失败以 WebError 抛出，宿主处理；不会静默回退到其他 provider。
前置条件：SearXNG 开启 JSON¶
SearXNG 默认不输出 JSON；未启用时实例仍可能返回 200 与 HTML 页面，插件会报配置类错误而非「无结果」。在实例的 settings.yml 中启用 JSON：
# settings.yml
search:
formats:
- html
- json
安装插件前，用 curl 验证端点（将地址换成你的实例）：
curl -fsS 'http://localhost:8888/search?q=test&format=json' | head -c 120
安装与启用¶
在 web profile 下添加插件（命令来自官方 README）：
# from npm
dsh plugin --profile web add dsh-web-searxng-search
# from GitHub
dsh plugin --profile web add github:kkgace/dsh-web-searxng-search
# from a local checkout
dsh plugin --profile web add /path/to/dsh-web-searxng-search
然后重启 web 应用：
dsh web
插件上架后，也可在 Settings → Plugin Market 中安装。
注意：仅安装插件不够。bundle 会通过 patch 将 web.searchProvider 设为 searxng；若 profile 未生效或仍指向内置 provider，web_search 会继续走原后端。修改配置后需重启 dsh web。
配置¶
默认 baseURL 为 http://localhost:8888。指向自有实例时，在 profile overlay 里补丁已有条目，不要 insert 新行（否则会与 bundle 重复 id，启动报 duplicate loader entry id: web-search-searxng）：
# ~/.dsh/profiles/web/cordis.patch.yml
- id: web-search-searxng
config:
baseURL: 'https://searxng.example.com'
也可在运行 dsh 的环境中设置 SEARXNG_BASE_URL。
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
baseURL |
string |
http://localhost:8888 |
实例根 URL，不要带末尾 /search |
timeoutMs |
number |
15000 |
单次请求超时，1000–120000 ms |
language |
string |
— | 传给实例的 UI 语言，如 en-US |
safeSearch |
0 \| 1 \| 2 |
0 |
关闭 · 适中 · 严格 |
categories |
string |
— | 逗号分隔类别，如 general,it |
engines |
string |
— | 逗号分隔引擎名，缩小检索范围 |
apiKey |
string |
— | 仅当实例需要 Bearer 时填写 |
典型用法与排查¶
仍走其他 provider：检查 web.searchProvider 是否为 searxng，并确认已执行 dsh web 重启。
有数据却显示无结果：多为实例未开 JSON format，见上文 settings.yml。
WEB_PROVIDER_CONFIGURED_UNAVAILABLE：available() 为 false，通常 baseURL 不是合法的 http(s) 绝对 URL。
WEB_PROVIDER_TIMEOUT：在 timeoutMs 内实例未响应，可调大超时或检查网络与实例负载。
Agent 侧无需改工具名：配置正确后，对话里照常触发 web_search，请求由插件转发到 SearXNG。
适用场景与注意¶
适合：已部署或计划部署 SearXNG、希望 DSH Agent 联网检索自控、避免 DeepSeek 搜索 API 计费与 Key 归因的团队或个人。
不适合：没有可维护的 SearXNG 实例，或不愿在元搜索层做引擎与合规配置的场景。
DSH 生态强调「一切皆插件」；SkillHub 等社区目录独立于 DeepSeek / 幻方，并非官方应用商店。插件以当前 dsh 进程权限运行，安装前建议阅读仓库源码与 MIT 许可证，确认 baseURL 与可选 apiKey 符合你的安全策略。
结尾¶
dsh-web-searxng-search 在 ctx.web 上把 web_search 接到自托管 SearXNG，保留工具接口、换掉计费与厂商账号依赖；前提是实例开启 JSON API，并通过 patch 正确选中 searxng provider。
- 目录页：https://www.skillhub.cn/plugins/kkgace/dsh-web-searxng-search
- GitHub：https://github.com/kkgace/dsh-web-searxng-search
