SearXNG 联网搜索 svoemesto/dsh-web-search-searxng

dsh-web-search-searxng

这是 DeepSeek Harness 的插件包，让智能体用上可用的 web_search，而且不需要厂商密钥。它把基于 SearXNG 的搜索服务商接到 harness 的 Web 访问接缝（ctx.web）上，默认还会拉起自己的 SearXNG 容器——也就是说，装好插件包，配置就全做完了。

工作原理，以及与「裸」SearXNG 的区别

「裸」的做法就是一个三十行的适配器：拼出 {base}/search?format=json，返回 results[]。它默认你已经把 SearXNG 跑起来了、JSON 已开启、端口空闲、镜像是最新的、容器还活着。而且它分不清「什么都没搜到」和「内部引擎挂了」：两种情况都返回 HTTP 200 加一个空列表。

我们的插件把实例本身和可靠性一起打进包里：

1. 安装即得到可用实例。 插件拉取 searxng/searxng，取第一个空闲端口，生成 settings.yml（开启 JSON、关闭限流器、密钥只生成一次），等 /healthz 就绪，卸载时停掉容器。没有「先自己起一个 SearXNG」这一步；如果你已经有实例，填一个 baseURL 参数就行，不会创建容器。
2. 引擎失败算错误，不算空结果。 SearXNG 会返回 unresponsive_engines；插件再跑一遍（按 fallbackEngines，或者去掉收窄的过滤条件），之后才告诉你哪些引擎失败了。
3. 临时故障能扛过去。 网络错误、单次尝试超时、429/5xx 都会重试；调用方主动取消则绝不重试；最坏延迟是 (retries + 1) × timeoutMs。
4. 重复查询不花代价。 60 秒 TTL 缓存：智能体经常重复同一个搜索，第二次直接从内存返回。
5. 结果适合引用。 只保留 http(s)，摘要不超过 800 字符，带 publishedAt，引擎给出的回答（answers）作为 content——不编造任何文字。

引擎是 SearXNG 并行查询的来源。生成的配置里写了 use_default_settings: true，所以启用的是当前版本的默认集合：general 分类下是 brave、duckduckgo、google cse、wikipedia 和 wikidata（外加 currency、dictzone、lingva 这类辅助引擎）；google、bing、qwant、yandex 在配置里存在但被关闭——它们要么需要密钥，要么不稳定，需要在 settings.yml 里手动开启。查看自己实例启用了哪些引擎：

curl -s http://127.0.0.1:8888/config | jq -r '.engines[] | select(.enabled) | .name'

我们不做的事：不调外部 API，不要密钥，不为搜索付费，也不编造摘要——content 来自引擎。服务商注册为 searxng，web_search 工具保持原样；包是普通 ESM，无依赖，无需构建。

要求

| 要求 | 用途 |
| Docker 守护进程，运行 dsh 的用户可访问（docker version） | 插件自己启动和停止容器 |
| 首次启动约 400 MB 磁盘空间和网络 | 一次性拉取镜像 |
| Node 22+（harness 本来就要求） | fetch、AbortSignal.timeout |
| 带 ctx.web 接缝的 DSH（当前 0.2.x） | 服务商注册到这个接缝；旧版本上该行只是等待服务，什么都不做 |
| dsh 命令可用的 pnpm 和 git | dsh plugin 通过 pnpm 安装包，github: 规格需要 git |

没有 Docker？把 baseURL 指向已有的 SearXNG 实例——这样什么都不启动（见使用已有实例）。

安装

包声明了 dsh.bundle，所以安装的同时也就激活了它：

从 GitHub（支持的方式）
dsh plugin --profile web add github:svoemesto/dsh-web-search-searxng

从本地副本（用于开发）
dsh plugin --profile web add /path/to/dsh-web-search-searxng

在已运行的 harness 内部，plugin_manager → install_bundle 做同样的事，把包目录作为 target。之后问智能体一些时效性强的问题：web_search 会通过你的实例回答。

首次启动很慢——只有一次。 插件拉取镜像、创建容器，然后等待 /healthz（最长 startupTimeoutMs，默认 90 秒）。实例没准备好之前，搜索会以错误「SearXNG instance is not ready: …」结束；拉取在后台继续，下一次搜索就能通过。

创建了什么

| 什么 | 哪里 |
| 容器 | dsh-searxng（名称可配置），--restart unless-stopped，只发布到 127.0.0.1:<空闲端口>:8080 |
| 设置 | $DSH_HOME/searxng/settings.yml（默认 ~/.dsh/searxng/），只写一次，永不覆盖 |
| 密钥 | 生成到这些设置里；重启和更新后保留 |
| 端口 | 从 port（8888）开始的第一个空闲端口，最多扫描 50 个端口——SearXNG 已被占用的机器也能继续工作 |

容器在插件激活时启动，在插件卸载时停止（harness 退出、HMR 重载、删除插件）。容器本身保留，所以下次启动只需几秒；数据和密钥留在 $DSH_HOME/searxng。

你的配置档里改了什么

两行补丁，都能在 dsh --profile <名称> --dump-config 里看到：

- 行 web-search-searxng——服务商本身（默认 port: 8888）；
- 行 web 的覆盖：searchProvider: searxng 和 fetchProvider: http。补丁整体替换 config，所以 fetchProvider 显式写出——否则安装后 web_fetch 就没有服务商了。如果配置档里已经保存了来自 Settings → Plugins → Web search 的覆盖，它比补丁更强：搜索仍由 DeepSeek 负责，尽管插件已安装。

名为 dsh-searxng、由非本插件创建的容器，不复用，不会停止：插件会检查标签 dsh.plugin=dsh-web-search-searxng，遇到别人的容器就拒绝工作，并给出明确提示（请换一个 containerName）。

配置

所有字段都可选，都有可用的默认值。

| 字段 | 默认值 | 含义 |
| baseURL | （未设置） | 使用这个已有实例，不启动任何东西。未设置 → 用自己的容器。 |
| port | 8888 | 容器的第一个候选端口；被占用的会跳过。 |
| image | searxng/searxng:latest | 任何兼容的 SearXNG 镜像（镜像站、固定标签）。 |
| containerName | dsh-searxng | 插件拥有的容器。 |
| dataDir | $DSH_HOME/searxng | 宿主机上存放 settings.yml 的目录。 |
| instanceName | DSH web search | 实例自己界面里的名称。 |
| startupTimeoutMs | 90000 | 等待就绪的时间预算（1000–600000）。 |
| timeoutMs | 20000 | 单次搜索的时间预算。 |
| language | （未设置） | 作为 language 传入；未设置 = 用实例的值。 |
| categories | （未设置） | general、news、…… |
| safesearch | （未设置） | 0、1、2。 |
| timeRange | （未设置） | day、week、month、year。 |
| numResults | （未设置） | 只在调用方没传 maxResults 时截断；真正的上限由接缝控制。 |
| apiKey | （未设置） | 作为 preference[api_key] 传给需要密钥的实例。 |
| retries | 1 | 错误可重试时，首次之后的额外尝试次数（0–5）。 |
| retryDelayMs | 300 | 两次尝试之间的间隔。 |
| fallbackEngines | [] | 重试时收窄到的引擎，例如 ["brave", "duckduckgo", "google cse"]；留空则重试时不带 language、categories、time_range。 |
| cacheTtlMs | 60000 | 缓存结果的存活时间；0 关闭缓存。 |
| cacheMaxEntries | 200 | 缓存里保留多少次搜索，超出后淘汰最旧的。 |

值不合法会中止激活，并指出是哪个字段——拼写错误绝不会变成悄悄失效的搜索。

配置行示例（写在 bundle 或配置档的补丁里）：

- insert:
- id: web-search-searxng
name: dsh-web-search-searxng
config:
port: 8888
language: ru

使用已有实例

config:
baseURL: http://127.0.0.1:8888

这样不会创建容器，也不需要 Docker。机器上已经有 SearXNG 在跑别的任务，或者实例在另一台主机上时，这很有用。

结果如何呈现

- results[] → {url, title?, snippet?, publishedAt?}；没有绝对 http(s) URL 的条目会被丢弃，空摘要会被略过（不会编造），摘要限制在 800 字符；
- 引擎的第一个非空回答（answers[]）会成为 content——这是引擎的真实输出，不是在这里编出来的文字；
- 没有结果 且 unresponsive_engines 列表非空 → WEB_PROVIDER_ERROR 带上引擎名称，让「半坏」的实例能被看见，而不是看起来像一次诚实的空结果。

错误会带上接缝处的错误码：WEB_PROVIDER_ERROR（HTTP 错误、无法解析的响应体、超时、网络问题、未就绪）和 WEB_ABORTED（调用方取消）。

重试与缓存

失败是暂时性的时候才重试：网络错误、单次尝试超时、HTTP 429/5xx，或者——卡拉 OK 文本搜索教会我们的那种情况——HTTP 200，但结果为零，且 unresponsive_engines 列表非空。重试不是原样再发一次同样的请求：

- 如果设置了 fallbackEngines，搜索就收窄到这些引擎（engines=bing,brave,…），过滤条件保留；
- 否则重试时去掉 language、categories、time_range——正是这些收窄条件可能把一个本来能正常返回的请求清零。

最坏延迟是 (retries + 1) × timeoutMs；用默认值算是 40 秒，落在工具 60 秒的预算之内。调用方取消不重试。

相同的搜索会缓存在进程内存里：键包含查询、结果条数上限、language、categories、safesearch、timeRange、备用引擎列表和实例地址。条目存活 cacheTtlMs（默认 60 秒），缓存最多保留 cacheMaxEntries 次搜索。缓存只在进程内——不落文件，不同 Harness 主机之间也不共享状态——而且只存成功结果，所以一次失败不会挡住之后成功的搜索。

诊断

| 症状 | 原因与处理 |
| docker is not available on this machine | 启动 Docker，或设置 baseURL。 |
| SearXNG instance is not ready: … did not become healthy | 查看 docker logs dsh-searxng；可能镜像还在首次下载。 |
| no free port in 8888..8937 | 调小 port 或释放端口；每个容器占一个。 |
| 搜索结果奇怪或很少 | SearXNG 聚合的是第三方引擎；docker logs 会显示哪些引擎失败了（unresponsive_engines）。 |
| 同一台机器上跑两个 harness | 它们共用容器名和端口；第二个会复用已启动的那个。要隔离就设置不同的 containerName + port。 |
| container "dsh-searxng" exists but was not created by this plugin | 机器上已有同名容器，但没有我们的标记。在配置里换一个 containerName，或删掉那个容器。 |
| 卸载 | 移除 bundle 会停掉容器；要回收磁盘，执行 docker rm -f dsh-searxng 并删除 $DSH_HOME/searxng。 |

安全

- 容器只发布到 127.0.0.1；局域网内访问不到。
- JSON 输出开着，限流关着——这只因为绑定在 loopback 上才安全。如果要把实例暴露到外网，请在 settings.yml 里开启限流，并把它放到代理后面。
- 密钥在本地生成，只存在 settings.yml 里。

开发

没有依赖，也没有构建步骤：源码就是产物。

index.js точка входа плагина (apply, жизненный цикл, выбор режима)
src/config.js 校验与默认值 src/container.js Docker 生命周期：inspect / start / pull+create / health / stop src/settings.js 生成 settings.yml（含一次性密钥） src/provider.js SearXNG 的 JSON-API 客户端与结果映射 test/unit.test.mjs 单元测试集（模拟 Docker，不联网） test/docker.smoke.mjs 真实容器：ensure → search → stop → rm

DSH 里插件卡片的文案用俄语：harness 只提供 zh/en 两种语言包，所以俄语文案放在 locale/en.json（以及 locale/ru.json）里，才能在界面上显示；英文文档在 README.en.md。

node --test test/unit.test.mjs # 配置、设置、容器生命周期、映射、错误
node test/docker.smoke.mjs # 真实容器；需要 Docker 和网络，会启动 dsh-searxng-smoke

CI 在每次 push 时用 Node 22 和 24 跑单元测试集（.github/workflows/ci.yml）；容器检查是手动的（.github/workflows/docker-smoke.yml）。

发布

仓库本身就是分发渠道：没有「发布到注册表」这一步。

1. 提升 package.json 里的 version，并在 CHANGELOG.md 里加一条记录。
2. 提交，打上 v<version> 标签，推送标签。
3. 基于该标签创建 GitHub 发布（gh release create v<version> 或用网页界面）。

安装和锁定版本都直接从 GitHub 来：

dsh plugin --profile web add github:svoemesto/dsh-web-search-searxng
dsh plugin --profile web add github:svoemesto/dsh-web-search-searxng#v2.0.1

想让插件出现在社区列表里，就在 GitHub 上给仓库打 dsh-plugin 主题标签。

许可证

MIT —— 见 LICENSE。