@deepseek-ai/dsh-web-search-searxng

English | 中文

为 DeepSeek Harness 的 web 能力 seam（ctx.web）提供基于 SearXNG 的 WebSearchProvider。它调用 SearXNG 实例的 JSON API（/search?format=json），把聚合结果映射为 seam 标准化的 WebSearchResult。

这是一个实现包：它向 ctx.web 注册 provider，通过 ctx.credentials 或进程环境解析可选的 API key，在有发起方 Agent 时把辅助请求记录到会话中，且不注册任何面向模型的工具。它是一个函数/命名空间插件（inject: ['web']）。

为什么用 SearXNG

• 自托管、隐私：查询发往你自己的实例，不经过第三方搜索厂商。
• 每次搜索零模型成本：与需要发起完整模型调用的厂商搜索不同，一次搜索只是一个 HTTP GET——又便宜又快。
• 多引擎聚合：SearXNG 在一个端点后聚合 Bing、Brave、Baidu、Google、DuckDuckGo 等。
• 可移植：把 baseURL 指向任意 SearXNG——本地 Docker、局域网实例或公共实例均可。

依赖

• 一个 DSH 主机可达的 SearXNG 实例（默认 http://localhost:8080）。
• 挂载了 web seam 的 DeepSeek Harness profile（所有标准 profile 都自带）。

安装

一键安装（bundle）

本包声明了 dsh.bundle.patch（cordis.patch.yml），因此一条 dsh plugin add 即可同时完成"注册插件 + 切换 web seam"，无需手动编辑任何 YAML：

dsh plugin --profile web add /path/to/dsh-web-search-searxng

配置优先走环境变量——启动 dsh 前设置即可，完全不用改配置：

export SEARXNG_BASE_URL=http://localhost:8080   # 可选；默认 http://localhost:8080
export SEARXNG_MAX_RESULTS=10                    # 可选；默认 10
export SEARXNG_LANGUAGE=en                       # 可选；默认 'all'（不传该参数）

手动安装（本地开发）

# 1. 让包能从 profile 的 node_modules 解析
ln -sfn /path/to/dsh-web-search-searxng \
        "$DSH_HOME/profiles/node_modules/@deepseek-ai/dsh-web-search-searxng"

# 2. 在 cordis.patch.yml 中注册插件并切换搜索 provider（见下方配置）

- insert:
    - id: web-search-searxng
      name: '@deepseek-ai/dsh-web-search-searxng'
      config:
        baseURL: http://localhost:8080
        maxResults: 10

- id: web
  config:
    searchProvider: searxng-local

重启 DSH 进程（或 GUI）使 patch 生效。

web profile 默认禁用 HMR 重载；修改 cordis.patch.yml 后需要重启进程。

测试

node --test tests/provider.spec.js   # 17 个测试，零依赖（node:test）

配置

键	默认值	含义
baseURL	http://localhost:8080	SearXNG 基础地址；自动追加 /search。可从任意环境层的 $SEARXNG_BASE_URL 回退。无法解析时 provider 不可用。
maxResults	10	单次搜索返回来源数量上限（seam 也会强制执行自己的上限）。
language	all	搜索语言，作为 language=... 发送（如 en、zh-CN）。'all'（或未设置）时完全省略该参数。可从 $SEARXNG_LANGUAGE 回退。
apiKey	省略	字面量 SearXNG API key（当实例需要时）。优先用 apiKeyEnv，避免密钥进入配置文件；非空字面量优先。
apiKeyEnv	SEARXNG_API_KEY	每次搜索通过 ctx.credentials 解析的凭据引用，seam 缺失时从进程环境读取。本地无密钥实例缺省即可。

- id: web-search-searxng
  name: '@deepseek-ai/dsh-web-search-searxng'
  config:
    baseURL: http://localhost:8080
    maxResults: 10

以上条目是 web-search-searxng 设置区块的基础层：用户层对其覆盖会作用于下一次搜索，因为 provider 是每次调用时投影配置段，而不是在注册时快照。apiKey 带 role('secret')，不会出现在任何层的 describe() 响应中。

限流说明（Docker Desktop 下的本地 Docker）

当 SearXNG 跑在 Docker Desktop 里时，来自宿主机的请求到达容器时 REMOTE_ADDR 是 compose 网关 IP（如 172.18.0.1）而非 127.0.0.1。SearXNG 限流器会把它当作外部客户端，对 JSON API 返回 429（API_MAX = 4 次/小时）。本 provider 每次请求都发送 X-Forwarded-For: 127.0.0.1；配合 limiter.toml 中 trusted_proxies = ['127.0.0.0/8'] 以及回环段和 Docker 网段的 pass_ip 白名单，本地客户端可以完全绕过 JSON API 配额。

如果你的 SearXNG 是远程实例（局域网/云），请相应移除该头，或在服务端调整 trusted_proxies/pass_ip。

结果映射

SearXNG 返回的 provider 生成答案本 provider 不信任为 content，因此省略。sources[] 来自 results[]：url ← url、title ← title、snippet ← content、publishedAt ← publishedDate。按 URL 去重。

provider 失败表现为 WEB_PROVIDER_ERROR；调用方取消表现为 WEB_ABORTED。HTTP 重定向会被跟随（SearXNG 可能对 blob/重定向端点返回 307）。

请求日志

在发起方 Agent 下执行的搜索，会在派发前把仅日志用途的 web/searxng-search-request 会话事件写入会话，包含解析后的端点和查询（不含密钥）。Agent 之外的直接程序化调用没有发起会话可记录。

License

MIT