前言¶

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 倉庫