deepseek-harness/packages/web/web-search-searxng/README.zh.md

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

[English](README.md) | 中文

由 [SearXNG](https://docs.searxng.org) 支持的 `WebSearchProvider`，用于 harness [web 能力 seam](../web/README.md)（`ctx.web`）。它调用 SearXNG 实例的 JSON API（`GET /search?format=json`），把扁平 `results[]` 映射为 seam 规范化的 `WebSearchResult`。此提供方面向自托管或私有 SearXNG：不存在统一的公共实例，因此 `baseURL` 没有默认值，提供方刻意不携带 API 密钥或 `Authorization` 头。

这是一个**实现**包：它向 `ctx.web` 注册提供方，不拥有 `ctx.web` 键，也不注册面向模型的工具（后者属于 `@deepseek-ai/dsh-tool-web`）。与 `@deepseek-ai/dsh-llm-deepseek` 一样，它是函数／命名空间插件（`inject: ['web']`），负责注册后端，而非默认导出服务。

## 配置

| 配置键 | 默认值 | 含义 |
|---|---|---|
| `baseURL` | （无） | SearXNG 实例基址；追加 `/search`。为空或无法解析时提供方不可用。 |
| `language` | `auto` | SearXNG `language` 请求值；`auto` 让实例按用户偏好决定。 |
| `timeRange` | （未设置） | SearXNG `time_range` 时效过滤器：`day`、`week`、`month` 或 `year`。省略时不发送过滤器。 |

```yaml
- id: web-search-searxng
  name: '@deepseek-ai/dsh-web-search-searxng'
  config:
    baseURL: https://searx.example
```

上面的条目是 `web-search-searxng` Settings 分节的基础层：覆盖在它之上的用户层（`settings.yaml` 分节或会话内设置的编辑）会作用于**下一次**搜索，因为提供方按调用投影分节，而非在注册时捕获。因此 seam 的提供方选择在实例或过滤器变化时不会闪烁。不含 `baseURL` 的分节仍能通过 schema，但提供方保持不可用——不会猜测任何端点。

```yaml
# $DSH_HOME/settings.yaml
web-search-searxng:
  baseURL: https://searx.example
  language: auto
  timeRange: day
```

SearXNG 不提供按请求控制结果数量的方式——页面大小属于实例配置——因此没有 `numResults` 选项；seam 会在结果返回时强制执行 `maxResults`。

## 映射

SearXNG 返回扁平 `results[]`，不返回生成答案，因此省略 `content`。每项结果映射为 `WebSearchSource`：`url` ← `url`、`title` ← `title`、`snippet` ← `content`、`publishedAt` ← `publishedDate`。与 Exa 提供方不同，此提供方**不会**丢弃无 snippet 的结果：URL 与标题仍然有用，因此保留每项结果。提供方失败（HTTP 错误、网络失败、响应体无法解析或结构不符）以 `WebError` `WEB_PROVIDER_ERROR` 呈现；中止请求以 `WEB_ABORTED` 呈现。HTTP 重定向会在访问 `Location` 指向的目标之前被拒绝，并以 `WEB_PROVIDER_ERROR` 呈现。请求不携带 `Authorization` 头，因此不会有凭据泄露给重定向目标。

## 模型体验

通过 [`dsh-tool-web`](../tool-web/README.md) 间接影响；该工具保留此提供方经 `maxResults` 限制的 URL、标题、snippet 与发布日期，或将确切的错误消息 `SearXNG search aborted`、`SearXNG search request failed: <error>` 和 `SearXNG returned an unprocessable response body: <error>` 置于消费方的错误包装层内；生成答案与提供方私有字段不进入上下文。

#### KV Cache 影响

不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。

## 已知限制与暂缓事项

- **请求端不限制结果数量**：SearXNG 页面大小属于实例配置，因此提供方不发送数量，由 seam 在返回时截断；只抓取单页（通常约 20 条结果）。
- **不呈现聚合答案或 infobox 内容**：SearXNG 的 `answers` 与 `infoboxes` 不映射进 `content`。不信任任何生成答案。
- **按错误形状分类中止**：只有 `DOMException` 且名为 `AbortError` 时才映射为 `WEB_ABORTED`；携带自定义原因的中止（例如 `dsh-timeout` 的 `TimeoutReason`）会呈现为 `WEB_PROVIDER_ERROR`。