@junjiangao/dsh-web-search-tavily

前言¶

DeepSeek Harness (DSH) 採用插件化架構，ctx.web 是接入 Web 搜索能力的關鍵 seam。在使用第三方搜索服務（如 Tavily）時，開發者通常需要處理 API 密鑰配置、參數映射以及複雜的調參流程。@junjiangao/dsh-web-search-tavily 是一個基於 Tavily 的 WebSearchProvider，它解決了密鑰管理繁瑣的問題，並提供了一個僅包含能提升檢索質量參數的原生配置表單。

插件介紹¶

這是一個爲 DSH 的 ctx.web 能力提供支持的 Tavily 搜索提供者。它不擁有 ctx.web，也不註冊面向模型的工具（即不註冊 dsh-tool-web）。

該插件的核心價值在於：
* Keyless 模式：無需在任何位置（配置文件、設置頁面、憑證系統、環境變量）提供 API 密鑰，請求直接運行在 Tavily 的 keyless 模式下。
* 原生配置表單：在 DSH 的 Plugins 頁面註冊配置卡片，僅渲染對檢索質量有影響的參數。
* 安全配置：表單分組設計，且具備依賴驅動的控制邏輯，防止配置導致 Tavily 返回 400 錯誤。

安裝與啓用¶

該插件以標準 bundle 的形式分發，需通過 dsh plugin 命令安裝。

1. 安裝插件¶

在目標 profile 下執行：

dsh plugin --profile <name> add github:junjiangao/dsh-web-search-tavily

2. 啓用 Tavily 提供者¶

註冊提供者與選擇提供者是兩回事。web seam 通過 searchProvider 字段決定使用哪個提供者。請確保在 profile 的 cordis.patch.yml 中指定：

- id: web
  config:
    searchProvider: tavily   # 必須顯式指定，以覆蓋默認的 deepseek-official

注意：環境變量 DSH_WEB_SEARCH_PROVIDER 僅在 web 行未配置 searchProvider 時生效。

核心功能¶

Keyless 模式¶

插件運行時不會發送 Authorization 頭，也不會設置 x-tavily-access-mode: keyless。它利用 dsh-web-search-tavily-keyless 客戶端源進行請求。

參數精簡與分組¶

表單分爲三個部分：憑證 / 檢索 / 高級。
* 憑證：包含 apiKey（密鑰）和 apiKeyEnv（環境變量引用）。
* 檢索：包含 searchDepth、includeDomains、excludeDomains、language、filterByLanguage。
* 高級：包含 includeDomainsMode 和 includePublishedDate，該部分默認摺疊。

所有其他 Tavily 參數（如 topic、timeRange、maxResults、autoParameters 等）保持 Tavily 的默認值，不顯示在表單中，但可通過 profile patch 覆蓋。

防止錯誤配置¶

表單實現了依賴控制。例如，當未設置 language 時，filterByLanguage 會被鎖定並顯示說明（因爲 Tavily 會返回 400 錯誤）。當未設置 includeDomains 時，includeDomainsMode 同樣會被鎖定。

配置說明¶

表單渲染字段¶

區段	字段	說明
憑證	`apiKey`	直接填寫的密鑰（不推薦，配置文件會脫敏）
憑證	`apiKeyEnv`	環境變量引用，如 `TAVILY_API_KEY`
檢索	`searchDepth`	精度/延遲/成本切換：basic, fast, advanced, ultra-fast
檢索	`includeDomains`	僅搜索指定域名列表
檢索	`excludeDomains`	排除指定域名列表
檢索	`language`	結果語言過濾
檢索	`filterByLanguage`	嚴格語言過濾，需配合 `language` 使用
高級	`includeDomainsMode`	`restrict`（僅限域名）或 `prefer`（加權域名）
高級	`includePublishedDate`	包含發佈日期（默認 true，幫助模型判斷時效性）

基礎設施參數¶

以下參數不顯示在表單中，因爲它們屬於基礎設施或默認行爲：
* baseURL：默認爲 https://api.tavily.com，可通過環境變量或 patch 覆蓋。
* topic、timeRange、maxResults、includeAnswer、includeRawContent、autoParameters、exactMatch、country 等。

注意事項¶

依賴環境：
- 需要安裝 DSH 版本 0.2.x（0.2.0-rc.1 或更高）。
- 需要運行 Node.js ^22.19.0 || >=24.0.0。
運行權限：插件以當前 DSH 進程的權限運行，請確保安裝前檢查源碼與許可證（MIT）。
數據源：該插件僅註冊提供者，不註冊工具。實際的數據獲取由 ctx.web 和底層的 dsh-tool-web 處理。

結語¶

該插件通過 Keyless 模式和精簡的配置表單，降低了接入 Tavily 搜索的門檻，並保證了檢索配置的健壯性。如需查看目錄或源碼，請訪問 SkillHub 或 GitHub。