rogerdigital/dsh-searxng

dsh-searxng

dsh-vet

一个 DeepSeek Harness（dsh）插件，它将一个由
SearXNG 支持的搜索提供程序注册到 Web 能力接缝
（ctx.web）中，通过一个免费、自托管、无需密钥的元搜索
实例为你的 agent 提供 web_search——而不是付费的 Exa/Perplexity API。

快速开始

要求：Node.js 20 或更高版本、dsh、Docker Engine 或 Docker Desktop，以及 Docker Compose v2。

setup 命令会安装 dsh-searxng 并将其附加到所选 profile，因此无需单独的
插件安装步骤。

npx dsh-searxng setup
dsh --profile web

setup 会创建一个仅限回环、版本固定的 SearXNG Docker 部署，等待 JSON API 就绪，通过 SearXNG
和最终的 DSH 提供程序配置运行一次真实搜索，只有在此之后才会激活
该 profile。重复执行该命令会复用同一个自有的容器、端口、配置和
密钥。

需要时可使用其他 DSH profile 或端口：

npx dsh-searxng setup --profile research --port 9080
dsh --profile research

包安装和 DSH 插件激活绝不会启动 Docker。只有显式的 dsh-searxng setup 或
dsh-searxng remove --service 命令才会更改 Docker。

现有 SearXNG

现有的本地、远程、带身份验证或独立管理的 SearXNG 实例是一条
一等路径：

npx dsh-searxng setup --profile web --url https://search.example.com

该端点必须是 HTTP(S)，不得包含凭据、查询或片段，并且必须启用 JSON 搜索。
DSH profile 中现有的提供程序选项（如 authHeader、language、engines 和 categories）
会被保留并在验证中使用。外部模式绝不会调用 Docker。

手动安装插件

如果你自行管理 DSH profile 补丁，并且不希望 setup 命令附加它，
可以只安装插件包：

dsh plugin add dsh-searxng

使用具名 profile 时，请使用 dsh plugin --profile  add dsh-searxng。

运维

快速健康检查结果；在第一个失败处停止。
npx dsh-searxng status --profile web

有序的环境、Docker、所有权、HTTP、JSON、搜索、profile 和提供程序检查，
外加本地隐私态势及其明确的超出范围限制。
npx dsh-searxng doctor --profile web

只读的引擎健康探测组合：每个引擎报告的失败及原因、
结果贡献和证据限制。不写入任何内容。
npx dsh-searxng tune --profile web

为受管部署规划并执行所有权安全的修复。
npx dsh-searxng repair --profile web

将受管部署迁移到打包版本，并带有经验证的回滚。
npx dsh-searxng update --profile web
从该配置文件中分离配置并移除插件包。
npx dsh-searxng remove --profile web

同时停止并移除所拥有的服务；保留其数据和本地状态。
npx dsh-searxng remove --profile web --service

永久删除确切拥有的数据卷和受管目录。
npx dsh-searxng remove --profile web --service --purge-data

永久删除会在交互式终端上提示确认。自动化必须添加 --yes。--json 在 setup、status、doctor、repair、update 和 remove 上可用。破坏性 Docker 操作仅在容器、网络和卷标签与此 DSH home 匹配后运行；同名的外部资源会被拒绝。

恢复语义

repair 和 update 会在第一次变更与验证完成之间，将其进度记录到
$DSH_HOME/dsh-searxng/journal.json；setup
和 remove 会读取该日志，以在中断期间拒绝运行或在中断后进行清理。

- 当记录到中断的操作时，setup 会拒绝运行，并指向 repair。
- 当存在日志时，repair 会接管：它在执行任何普通修复之前，从磁盘重新计算恢复决策（清除
日志、验证目标或恢复回滚），并且还会移除死进程留下的隔离陈旧锁。doctor 会报告中断
操作的 id、kind、phase 和 age。
- update 是事务性的：当前部署保持权威，直到目标通过
就绪、真实搜索和提供程序验证。第一次 Docker 变更之后的任何失败都会
回滚到先前的镜像和配置，并重新验证它们；相同版本的更新
会以 E_DEPLOYMENT_UNSUPPORTED 被拒绝。
- 一旦部署消失，remove --service 会清除日志，因此后续的 setup 不会
被拒绝。

提供程序配置

setup 命令管理
$DSH_HOME/profiles//cordis.patch.yml 中的 web-search-searxng 行。可以将以下可选值添加到该行：

| 键 | 默认值 | 含义 |
|---|---|---|
| baseURL | 受管或 --url 端点 | SearXNG 基础 URL。 |
| language | 无 | SearXNG 语言，例如 zh-CN 或 en-US。 |
| engines | 无 | 逗号分隔的引擎允许列表。 |
| categories | 无 | 逗号分隔的类别过滤器。 |
| authHeader | 无 | 用于受保护外部实例的 Authorization 头。 |
| cacheTtlMs | 600000 | 缓存查询结果的生存时间（毫秒）；0 禁用缓存。 |
| minIntervalMs | 1500 | 网络请求之间的最小间隔；0 禁用节流。 |
| queueCapacity | 8 | 在提供程序以背压拒绝之前，可以等待节流槽位的请求数。 |
| totalBudgetMs | 15000 | 一次搜索调用的挂钟时间预算，涵盖节流等待、退避和网络尝试。 |

重复查询由作用域限定于提供程序实例的进程内缓存提供服务
（不会写入磁盘）；缓存命中不会执行网络请求。
并发搜索会经过一个令牌桶（突发为 2，之后每 minIntervalMs 允许一个请求），而队列已满时会立即以可重试错误拒绝，而不是阻塞调用方。失败的响应和空结果页永远不会被缓存——缓存的空页面会在整个 TTL 内掩盖上游恢复——并且空结果页会按原样返回：engines/categories 允许列表绝不会为了追逐结果而被静默放宽。当实例返回 HTTP 429 时，提供方会遵循 Retry-After，并在剩余预算内最多重试一次。

每查询控制

SearXNG 支持在查询字符串本身中进行每查询路由；提供方会原样传递查询语法：

- :zh-CN / :en — 为此查询选择结果语言（: 前缀）。
- !bing / !news — 为此查询选择一个引擎或类别（! 前缀）。
- site:example.com — 将结果限制到一个域名（支持情况取决于引擎）。

例如，查询 :zh-CN 大模型 排行榜 会以中文搜索，而不受配置文件的 language 影响；!github compose network mapping 只使用 GitHub 引擎。请根据你的实例的引擎列表核实引擎名称。

如果有多个 DSH 搜索提供方可用，请使用 DSH_WEB_SEARCH_PROVIDER=searxng 或相应的 searchProvider DSH Web 配置来选择此提供方。

故障排除

- E_DOCKER_MISSING / E_DOCKER_OFFLINE：安装或启动 Docker。
- E_COMPOSE_UNSUPPORTED：启用 Docker Compose v2。
- E_JSON_DISABLED：将 json 添加到 SearXNG 的 search.formats。
- E_AUTH_FAILED：检查外部实例的 authHeader 配置。
- E_TLS_FAILED：端点的 TLS 证书验证失败；检查证书链并重试。
- E_RATE_LIMITED：调整实例限流器或上游引擎选择。
- E_RESOURCE_FOREIGN：同名 Docker 资源不带有此安装的所有权标签；它绝不会被自动修改。
- E_BUNDLE_DAMAGED：生成的配置包不完整或不匹配；repair 会从打包的资产重建它，同时保留现有密钥。
- E_DEPLOYMENT_UNSUPPORTED：打包的部署目录无法满足请求（请求了未知版本或相同版本，或某个条目与当前状态不兼容）；请升级 dsh-searxng 或选择一个可用版本。
- E_PROFILE_CONCURRENT_MODIFICATION：DSH 配置文件在操作期间发生了更改；请检查并重试。

doctor --json 返回完整的已脱敏检查列表和可操作的错误代码。

运行时支持

- Node.js：20 及更新版本。
- CLI、测试、构建和打包产物：已在 CI 中的 Linux、macOS 和 Windows 上验证。
- 托管 Docker 流程（包括修复和更新回滚）以及 Docker 适配器集成：已在选择启用的 Linux CI 中通过 Docker Engine 和 Compose v2 验证。发布认证运行器也在那里执行；CI 不提供 Docker Desktop，并使用一个桩 dsh，因此它不是正式认证。
- 已认证的按版本 Docker 环境：仅限那些在 docs/release-certification.md 中拥有来自发布 tarball 的完整通过报告的环境——分别来自 macOS + Docker Desktop、Windows + Docker Desktop + WSL2，以及 Linux + Docker Engine + Compose v2 各一个。
- macOS 上的 Docker Desktop 已针对 0.4.0 认证
（docs/certification/v0.4.0-darwin-arm64.json）；Windows 上的 Docker Desktop 兼容（相同的
引擎、相同的 Compose v2 插件）但未认证，直到其报告针对给定版本存在为止。
- 外部 SearXNG 模式不需要 Docker，可在任何装有 Node.js 20+ 的平台上运行。
- 托管路径不支持 Podman 和 Podman Compose。

setup 从打包的部署目录中选择要安装的部署
（与当前状态 schema 兼容的最新条目），并复用目录中仍然列出的
健康现有部署；使用 update 在部署版本之间切换。

dsh 处于开发者预览阶段，预计会有破坏性变更。版本 0.4.0 支持
@deepseek-ai/dsh-web >=0.1.0-rc.6 =0.0.1-rc.3 .tgz

许可证

MIT