SearXNG 搜索源 chinng-inta/dsh-web-search-searxng

dsh-web-search-searxng

一个由 SearXNG 支持的 WebSearchProvider，用于 DeepSeek Harness 的 Web 能力接缝（ctx.web）。

SearXNG 是一个自托管的元搜索引擎。这里的一次搜索就是对该实例的 /search?format=json 端点发起的一次普通检索调用，因此与随附的 DeepSeek 提供程序不同，它不需要 API 密钥，也不消耗模型轮次——随附的提供程序会使用原生的 web_search 服务器工具发起一次完整的 Messages 请求，每次搜索都要付出延迟和生成 token 的代价。

这是一个实现包：它向 ctx.web 注册一个提供程序，而不会注册面向模型的工具。@deepseek-ai/dsh-tool-web 拥有 web_search、其 schema、其提示词指引以及结果卡片。安装此包即可让该现有工具针对你自己的实例工作。

安装

从 npm 安装

dsh plugin --profile web add dsh-web-search-searxng

从本仓库安装

dsh plugin --profile web add github:chinng-inta/dsh-web-search-searxng

git 依赖不会附带 lib/，因此该包会通过其 prepare 脚本自行构建——而
pnpm 会阻止安装脚本，直到你允许它们。因此首次运行会失败，并打印出需要允许的确切
键。将其添加到你的 profile 的 pnpm-workspace.yaml 中并重新运行：

allowBuilds:
"dsh-web-search-searxng@https://codeload.github.com/chinng-inta/dsh-web-search-searxng/tar.gz/": true

该键固定了一个提交，因此每当你安装更新的修订版本时它都会变化。从源码构建还需要获取开发工具链（约 20 秒，而从注册表安装约 2 秒）。除非你在跟踪未发布的更改，否则优先使用 npm。

两种方式皆可

该包声明了 dsh.bundle，因此一条命令也能激活它：bundle 补丁插入提供程序行，并在 web 行上选择它。将其指向你的实例并重启：

export SEARXNG_URL=http://searxng.internal:8888

在启动前验证组合：

dsh --profile web --dump-config | grep -A3 'id: web'

你的实例必须提供 JSON

SearXNG 默认不启用 JSON API。在实例的 settings.yml 中：

search:
formats:
- html
- json

没有它，端点会以 HTML 结果页面作答，而此提供程序会失败并给出指明修复方法的消息，而不是解析错误。

公共实例是不佳的后端：大多数拒绝程序化访问（来自机器人过滤器的 HTTP 403）或激进地限流。请运行你自己的实例。

配置

配置就是此插件行的 config。当该行未设置 baseURL 时，它还会回退到 $SEARXNG_URL，因此开始使用无需其他任何东西：导出该变量，提供程序即已配置。

每个键都声明为 volatile，自 dsh 0.1.7-rc.2 起这意味着两件事：harness 设置服务可以编辑它，而编辑会就地更新正在运行的插件（无需重启）。提供程序每次搜索时读取该行，因此编辑会影响到下一次搜索，而清除 baseURL 会回退到环境变量，而不是让提供程序滞留在它再也看不到的值上。注册本身从不移动，因此当配置变化时，提供程序选择不会闪烁。

有两种设置方式：

- Plugins 页面。 打开此包，然后在其 web-search-searxng 行上打开配置控件。该页面编辑实例 URL 和搜索语言，并保存到活动配置文件的补丁（$DSH_HOME/profiles//cordis.patch.yml）中。
- 一个补丁行，在你的配置文件补丁或 --patch 覆盖层中：

- id: web-search-searxng
config:
baseURL: http://searxng.internal:8888
language: ja
categories:
- general
- news

补丁行会替换目标行的整个 config，因此请重新声明你想要的每一个键。而你在 --patch 覆盖层中设置的行位于 Plugins 页面写入的配置文件补丁之上：在那里保存仍会更改运行中的值，但它不会被持久化，并且覆盖层会在下次启动时再次胜出。

所有键都是可选的。

| 键 | 默认值 | 含义 |
| baseURL | $SEARXNG_URL | 实例根地址；会追加 /search。缺失或非 http(s) 会使提供程序报告为不可用，而不是让每次搜索都失败。 |
| categories | 实例默认值 | categories= 过滤器，例如 ['news']。 |
| engines | 实例默认值 | engines= 过滤器，例如 ['duckduckgo', 'brave']。 |
| language | 实例默认值 | language= 过滤器，例如 ja、en-US。 |
| timeRange | 未设置 | time_range= 过滤器：day / week / month / year。 |
| safesearch | 实例默认值 | safesearch=：0 关闭，1 适中，2 严格。 |
| timeoutMs | 10000 | 单次搜索的资源兜底限制。 |
| maxSnippetChars | 500 | 每个来源的摘要字符数上限。 |
| headers | 无 | 额外的请求头，例如用于位于需要认证的代理后面的实例。 |

从 0.4.x 升级：$DSH_HOME/settings.yaml 的 web-search-searxng: 部分不再被读取——dsh 0.1.7 移除了该文档。dsh 会在第一个启动的配置文件中将它一次性导入到该配置文件的补丁中（并将文件重命名为 settings.yaml.imported）；请检查结果是否落到了你预期的位置。

每一个塑造搜索的旋钮都是部署设置，而不是模型参数。该接缝的 WebSearchRequest 有意只包含 query + maxResults；提供程序中立的控制项（时效性、域过滤器、搜索深度）在上游被列为延迟工作。将它们保留在配置中，正是使此提供程序可替代内置提供程序的原因。

timeoutMs 是资源兜底限制，而不是面向模型的工具调用预算—— @deepseek-ai/dsh-tool-call-timeout-policy 通过 tool-web 的 searchTimeoutMs 拥有该预算。请将此值保持在工具预算之下，这样慢实例会表现为提供程序失败，而不是工具超时。
提供程序选择

该 bundle 补丁设置了 web.searchProvider: searxng。这是必需的，而非个人偏好。

仅当恰好有一个已注册的提供程序可用时，该接缝才会自动选择，而 @deepseek-ai/dsh-web-search-deepseek 只要存在凭据解析器就会报告为可用——它自己的 apply() 总是会提供该解析器——因此即使在未配置密钥的默认组合上，它也会回答 available() === true。如果注册第二个提供程序而不指定使用哪一个，就会导致每次搜索都失败并报 WEB_PROVIDER_AMBIGUOUS。

Bundle 层会在你的 profile 的 cordis.patch.yml、home 补丁以及任何 --patch 覆盖层之前应用，因此你始终可以覆盖该选择。但请注意，补丁会替换目标行的整个 config：如果你自己为了其他目的修补了 web 行，也要在那里重新声明 searchProvider: searxng。

映射

| SearXNG | 接缝 |
| results[].url | sources[].url（必需；没有该字段的结果会被丢弃） |
| results[].title | sources[].title |
| results[].content | sources[].snippet，上限为 maxSnippetChars |
| results[].publishedDate | sources[].publishedAt |
| answers[] | content，以换行符连接；为空时省略 |

来源会按 URL 去重，因为元搜索引擎会合并那些经常返回同一页面的引擎。空字符串会被视为缺失，而不是作为空字段输出——接缝的可选字段存在，是为了让适配器永远不必凭空捏造它们。

来自此提供程序的 truncated 始终为 false：接缝负责 maxResults 的强制执行，而报告我们自己的截断会错误地将列表被截断归因于错误的边界。

错误

失败会表现为 WebError，由工具层转换为可读的工具结果。

| 情况 | 代码 |
| 调用方取消 | WEB_ABORTED |
| timeoutMs 已耗尽 | WEB_PROVIDER_ERROR |
| 实例返回非 2xx（403 会带有机器人过滤提示） | WEB_PROVIDER_ERROR |
| 响应不是 JSON（通常是 formats 配置错误） | WEB_PROVIDER_ERROR |
| 响应体无法解析 | WEB_PROVIDER_ERROR |

available() 是一个低开销的同步检查——一个可解析的 http(s) 基础 URL——正如接缝所要求的那样；它从不访问网络。

重定向会被拒绝（redirect: 'error'）。自托管实例没有理由重定向搜索，而跟随重定向会将查询发送到部署从未配置过的主机。

已知限制

- maxResults 不会被下推。 SearXNG 不提供结果数量参数，因此实例会返回其完整的第一页，再由接缝进行截断。这限制的是 token，而不是实例的工作量。
- publishedDate 通常缺失。 通用 Web 引擎很少为结果标注日期；新闻引擎通常会。如果你需要日期，请使用 categories: ['news'] 进行过滤。
- 信息框不会被呈现。 它们是结构化的实体卡片，而不是对查询的回答，因此将它们扁平化为 content 会把它们呈现为回答。
- 没有按引擎的失败报告。 SearXNG 在部分失败时会报告 unresponsive_engines[]；而接缝的结果结构无处安放它，因此一次降级的搜索看起来就像一次结果稀少的搜索。

兼容性

| 本包 | DeepSeek Harness |
| 0.5.0+ | 0.1.7-rc.2 |
| 0.4.0 | 0.1.2-rc.1 – 0.1.5-rc.3 |
| 0.3.3 – 0.3.x | 0.1.0-rc.8 – 0.1.1-rc.2 |
| 0.1.x – 0.3.2 | 0.1.0-rc.6 |

每一行都互斥：此处没有任何内容向后兼容，也没有任何更旧的版本向前兼容。安装错误的组合不仅仅会丢失这张卡片——它会让整个 Web UI 的插件加载失败，因为这些破坏会表现为无法解析的客户端 require 或无效的插槽注册（#1）：

- rc.8 从加载器的种子表中移除了 @deepseek-ai/dsh-client-web-react。直到 0.3.2，本包都从它导入 bindSnapshotSelector。0.3.3 改为通过插槽注入面的 hooks 隔间将其 store 交给渲染器，而 rc.8 正是在那里合成选择器钩子的。
- rc.8 将 settings.plugin.item 从 list 插槽（id + order）变成了 keyed 插槽（key = 卡片所编辑的设置命名空间）。0.3.3 以 keyed 方式注册，而 rc.6 会拒绝这种方式。
- 0.1.2-alpha.1 彻底删除了 @deepseek-ai/dsh-client-runtime。直到 0.3.x，本包都从它获取 createSnapshotStore 并在 dsh.client.inject 中声明它；0.4.0 从 @deepseek-ai/dsh-client-store（前端现在交给加载器的一个种子）获取同一个函数，并从 inject 中移除这个幻影项，否则该行会永远处于待处理状态。
- 0.1.2-alpha.2 从 @deepseek-ai/dsh-settings 中删除了 settingsNamespace() 和
installSettingsSection() 辅助函数。0.4.0 使用裸命名空间字面量，并在
ctx.inject(['settings'], …) 内调用 settings.installSection，这现在是挂载/卸载
生命周期。
- 0.1.7-rc.2 移除了共享的 settings.yaml 以及 settings.installSection：设置变成了每个插件行自己的 config，可在 schema 将字段标记为 volatile 的地方编辑，并作为实时引用传递给 apply。0.5.0 将每个键都标记为 volatile 并在每次搜索时读取它们； 0.4.0 的宿主端调用了已移除的方法，因此其设置永远不会挂载。同一版本还删除了设置页面的 settings.plugin.item 插槽；0.5.0 改为在插件页面的 plugins.row.config 上注册（键为 dsh-web-search-searxng#web-search-searxng）。

0.3.0 发布了设置卡片却没有附带其样式表——它能工作，但会以浏览器默认样式渲染。请使用 0.3.1 或更高版本。

该 harness 是一个开发者预览版，各发布候选版本之间存在破坏性变更，其包在 next dist-tag 下发布当前活跃线（latest 仍指向较旧的 0.0.1-rc.1）。请固定你的 harness 版本。

许可证

MIT