前言¶

DeepSeek Harness（DSH）的 ctx.web 能力 seam 对接了一个 web_search 工具，模型通过该工具发起搜索请求。DSH 的官方 @deepseek-ai/dsh-web-search-deepseek 提供商使用 DeepSeek 内置的搜索接口，但在需要使用其他搜索引擎时，需要额外引入一个 provider。@xiaolizi0v0/dsh-web-search-serper 就是为了解决这个问题：它把 Serper 的 Google 搜索 API 注册到 ctx.web seam 下，并提供一个直接可用的 serper_search 工具。

插件定位¶

@xiaolizi0v0/dsh-web-search-serper 是一个 Cordis bundle，把 Serper 的搜索后端接入 Harness 的 ctx.web 能力 seam，遵循官方 provider 的接口形状。它只负责传输和结果映射，模型侧的 web_search schema 仍由 @deepseek-ai/dsh-tool-web 拥有，插件同时也注册了一个 serper_search 工具供直接调用。

核心功能¶

• 注册 provider：在 ctx.web seam 下注册 id 为 serper 的 provider。
• 接口形状：提供 name、inject、Config、apply，以及 id、available() 和 search(request, signal)。
• 请求与映射：向 https://google.serper.dev/search 发送 POST 请求，将 Serper 返回的 organic 映射为 seam 的 sources[]（link→url、title、snippet、date→publishedAt），并对结果按 URL 去重；将 answerBox.answer / answerBox.snippet 映射为可选的 provider content；拒绝重定向（redirect: "error"）。
• 配置项：web-search-serper 命名空间下的配置包括 apiKey（支持明文与凭据服务）、apiKeyEnv（默认 SERPER_API_KEY）、endpoint（默认 https://google.serper.dev/search，可通过环境变量 SERPER_SEARCH_ENDPOINT 回退）、gl/hl（默认 us/en）、num（默认 10，范围 1–100）、page（默认 1）、includeAnswerBox（默认 true，将 Serper 的 answer box 作为 provider answer）、tool（默认 true，注册 serper_search 工具）、toolMaxResults（默认 8，工具对结果数量的限制）、toolTimeoutMs（默认 30000，工具的 cooperative timeout budget）。
• 工具 serper_search：一个独立的工具，直接调用该插件的 provider 对象，无需在 seam 中配置 searchProvider。工具参数包括必填的 query，以及可选的 type（organic | news）、page（1–10）、maxResults、gl、hl，这些可选参数会回退到插件配置。工具对结果应用 toolMaxResults 限制，并报告 truncated；呈现使用 card: "web" / kind: "search" 视图，与官方 web 工具保持一致。
• 错误码：无凭据时为 WEB_PROVIDER_CREDENTIAL_MISSING（包括无 key 或 Serper 返回 401/403）；调用取消时为 WEB_ABORTED；传输/provider/unmappable body 时为 WEB_PROVIDER_ERROR（会指明 endpoint）。
• 安装：可通过 DSH 1024Store 或官方命令安装 npm 包 @xiaolizi0v0/dsh-web-search-serper，或作为本地 bundle 安装。

安装与启用¶

从 DSH 1024Store 目录（npm 包名 @xiaolizi0v0/dsh-web-search-serper）安装：

dsh1024 plugin --profile web add @xiaolizi0v0/dsh-web-search-serper
# 或官方命令
dsh plugin --profile web add @xiaolizi0v0/dsh-web-search-serper

也可作为本地 bundle 安装（需用 plugin_manager: action install_bundle, target <绝对路径>）。

安装后，在 profile patch 中添加以下配置以将 web_search 路由到 Serper provider：

- id: include:web
  config:
    searchProvider: serper

安装后需重启 profile（如果插件模块已加载，替换已安装包需要重新生成 JavaScript 模块），浏览器端只需重新渲染即可。

典型用法¶

在 profile patch 中配置 searchProvider: serper 后，模型通过 web_search 工具发起搜索，该工具会通过 seam 调用 Serper provider。例如，在 Chat 工具中直接提问，模型会调用 web_search，由 Serper provider 执行搜索并返回结构化结果。

直接调用 serper_search 工具（无需配置 searchProvider）：

{
  "query": "deepseek harness",
  "type": "news",
  "page": 2,
  "maxResults": 5
}

query 为必填字段，type 为 organic 或 news，page 为 1–10，maxResults、gl、hl 可选并回退到插件配置。工具会对结果应用 toolMaxResults 限制并报告 truncated，呈现为 card: "web" / kind: "search" 视图。

适用场景与注意¶

• 适合在需要使用 Google 搜索结果、或需要调用 Serper API 的场景下，作为 DSH ctx.web 的补充 provider。
• 插件以当前 DSH 进程的权限运行，安装前应检查源码与许可证。
• web_search 路径依赖 searchProvider 配置，需在 profile patch 中明确路由；serper_search 工具不依赖该配置，可直接使用。

结尾¶

@xiaolizi0v0/dsh-web-search-serper 把 Serper 的 Google 搜索能力接入 DSH 的 web 能力 seam，并提供一个可直接调用的 serper_search 工具，方便在 DSH 生态中集成第三方搜索引擎。插件目录页与源码仓库见下：
- DSH 插件目录页
- GitHub 仓库