chinng-inta/dsh-web-search-searxng

dsh-web-search-searxng

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

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

这是一个实现包：它向 ctx.web 注册一个 provider，而不
注册面向模型的工具。@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 秒，而使用 registry 约 2 秒）。除非你在跟踪未发布的更改，否则优先使用 npm。

两种方式都一样

该包声明了 dsh.bundle，因此一条命令即可激活它：bundle 补丁
会插入 provider 行，并在 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 结果页作答，而此 provider 会失败并给出指明修复方法的
消息，而不是解析错误。

公共实例是糟糕的后端：大多数会拒绝程序化访问（来自机器人过滤器的 HTTP 403）
或进行严格的速率限制。请运行你自己的实例。

配置

该插件拥有 web-search-searxng 设置命名空间，因此其配置节会在 harness 自身的
分层中解析：

schema 默认值  →  插件行的 config（组合基础）  →  设置文档中的用户层

当没有任何层设置 baseURL 时，它还会回退到 $SEARXNG_URL。开始使用无需其他配置：导出该变量，provider 即已配置完成。
该部分按每次搜索进行投影，因此对设置文档的编辑无需重启即可影响下一次搜索——并且清除 baseURL 会回退到环境变量，而不是让提供程序困在一个它再也看不到的值上。注册本身从不移动，因此当配置变化时，提供程序选择不会闪烁。

未挂载设置提供程序的部署仍可正常工作：源会回退到组合条目，与组合时完全一致。

所有键都是可选的。

| 键 | 默认值 | 含义 |
|---|---|---|
| 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 | 无 | 额外的请求头，例如用于位于认证代理之后的实例。 |

作为插件行的组合基础：

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

…或作为 harness 设置文档中的用户层（默认位于 $DSH_HOME/settings.yaml），它优先于上面的行，并且是配置界面所写入的内容：

web-search-searxng:
language: ja
maxSnippetChars: 300

每个塑造搜索行为的旋钮都是部署设置，而不是模型参数。该接缝的 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 以及任何 --patch 覆盖层之前应用，因此你始终可以覆盖该选择。但请注意，patch 会替换目标行的整个 config：如果你为了其他目的自行 patch web 行，也要在那里重新声明 searchProvider: searxng。

映射

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

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

truncated 从此 provider 始终为 false：maxResults 的强制执行由 seam 负责，报告我们自己的截断会错误归因于是谁的边界截断了列表。

错误

失败是 WebError，工具层会将其转换为可读的工具结果。

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

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

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

已知限制

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

兼容性

| 本包 | DeepSeek Harness |
|---|---|
| 0.4.0+ | 0.1.2-rc.1 |
| 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.3.0 发布设置卡片时没有附带其样式表——它能工作，但会以浏览器默认样式渲染。请使用 0.3.1 或更高版本。

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

许可证

MIT