前言¶

DSH 的插件機制比較貼近「一切皆插件」：搜索提供方、抓取提供方可以掛到宿主接口上，而不是要求使用者重寫主流程。對於需要把 web_search 切到外部搜索引擎的場景，常見痛點是配置分散、參數不完整、連通性驗證不方便。

dsh-plugin-tavily 解決的就是這個問題：它爲 DeepSeek Harness 提供一個 Tavily-backed web search provider，把完整請求參數放進 WebUI 設置卡，並保留 yaml 配置優先的能力。下面介紹它的定位、安裝方式和典型用法。

這是什麼¶

dsh-plugin-tavily 是 1624318455 維護的 DSH web search provider 插件。它向 harness 的 ctx.web seam 註冊一個 tavily provider，使 web_search 請求可以通過 Tavily 回答。

插件同時提供 WebUI 設置卡，用於粘貼 API key、調整高級參數、測試連通性；也支持通過 cordis.patch.yml 固定配置。材料中 package.json 顯示版本爲 0.6.2。

核心功能¶

搜索提供方¶

• 向 ctx.web seam 註冊 tavily search provider。
• web_search 工具本身不變，只是回答它的後端變成 Tavily。
• WebUI 中可在 tavily 與 official DeepSeek provider 之間切換。
• 無 Tavily key 時以 keyless 模式運行，免費且有限速；有 key 時使用對應賬戶層。
• 配置優先級爲：cordis.patch.yml > WebUI > code defaults。
• WebUI 可編輯的 Tavily 參數包括：API key、API Base URL、maxResults、searchDepth、topic、includeAnswer、includeRawContent、timeout、days、chunksPerSource、timeRange、startDate/endDate、includeImages、includeDomains/excludeDomains、country。
• 提供參數預設：Deep research、Quick summary、Live news。
• 服務端連通性探測接口爲 POST /api/tavily-probe。
• 狀態接口爲 GET /api/tavily-status，用於顯示當前 key 與額度狀態。
• API 連接測試會給出分類錯誤：invalid key、insufficient credits、rate limited、service down、timeout、network。
• 設置卡提供 Usage & cost 面板，可顯示當前設置下單次搜索的 credit/token 估算，並通過 Tavily GET /usage 查看用量。

抓取提供方¶

• 提供基於 Tavily Extract 的 fetch provider：tavily-extract，用於從 URL 讀取頁面內容。
• 提供可選 Firecrawl fetch provider：firecrawl，默認憑證引用爲 FIRECRAWL_API_KEY。
• 如果沒有 Firecrawl key，抓取時報告 WEB_PROVIDER_CREDENTIAL_MISSING；未被選擇時保持未啓用。

穩定性與工程化選項¶

• 持久化結果緩存：cacheFile 默認關閉，best-effort，並帶 debounce；磁盤失敗不會導致搜索失敗。
• 429 場景下的重試：有界 backoff，並可選 TTL/LRU cache。
• TTL/LRU cache 默認跳過時效敏感搜索，例如新聞、金融或帶有時間窗口的請求。
• 可選 concise debug logging：不會記錄 API key 或原始響應體。
• 多 key 輪換與故障切換：apiKeyRefs 只保存引用，key 仍保存在 credentials store 或環境中；連續失敗 3 次後進入 60 秒冷卻。
• 引用格式：citeFormat: footnote 或默認 plain。
• 自動降級引擎：fallbackEngine: deepseek，僅在 service-side Tavily failures 時觸發，例如 timeout、network、5xx；key-level faults 如 429、401 不觸發該降級。
• key 解析順序：literal apiKey → credentials service（apiKeyEnv）→ process.env[apiKeyEnv]。

安裝與啓用¶

1、安裝插件¶

先安裝插件。官方安裝命令如下：

dsh plugin --profile web add "github:1624318455/dsh-plugin-tavily#main"

開發階段也可以從本地路徑安裝：

dsh plugin --profile web add "file:/absolute/path/to/dsh-plugin-tavily"

安裝後重啓 dsh。插件自帶的 cordis.patch.yml 會將 web.config.searchProvider 設爲 tavily，因此不需要再手動選擇搜索提供方。

2、填寫 Tavily API key¶

打開 WebUI：

設置 → 插件 → 網頁搜索

展開 Web search (Tavily) 設置卡，將 Tavily API key 粘貼到 API key 字段。沒有 key 時也可以使用 keyless 模式。

3、選擇搜索提供方¶

在設置卡中切換 Web search engine：

• tavily
• official DeepSeek

經過上面的步驟後，繼續使用 web_search 即可。工具接口不變，只有後端提供方發生變化。

4、手動覆蓋 yaml（可選）¶

如果你希望手動固定 provider，可以寫入 profile 配置：

# ~/.dsh/profiles/web/cordis.patch.yml
- id: web
  config:
    searchProvider: tavily

典型用法¶

啓用 Tavily Extract 抓取¶

如果還需要用 Tavily Extract 做頁面抓取，可以設置 fetch provider：

export DSH_WEB_FETCH_PROVIDER=tavily-extract

或者在 cordis.patch.yml 中寫：

- id: web
  config:
    searchProvider: tavily
    fetchProvider: tavily-extract

啓用 Firecrawl 抓取（可選）¶

如果需要改用 Firecrawl 抓取頁面，可以設置：

export DSH_WEB_FETCH_PROVIDER=firecrawl

或在同一行配置中寫：

- id: web
  config:
    searchProvider: tavily
    fetchProvider: firecrawl

使用 Firecrawl 需要自己的 key。材料給出的默認憑證引用是 FIRECRAWL_API_KEY。沒有 key 時，該 provider 在 fetch 時會報告 WEB_PROVIDER_CREDENTIAL_MISSING，其餘情況保持未啓用。

測試連接與查看狀態¶

設置卡中的連接測試會檢查當前輸入的 key 和 API Base URL，並給出分類錯誤說明。已存儲 key 不能由瀏覽器讀回；如果測試已經配置好的 key，需要重新輸入一次，且不會再次保存。

服務端接口：

POST /api/tavily-probe
GET /api/tavily-status

其中 GET /api/tavily-status 會讀取已存儲 key，並配合 Tavily GET /usage 顯示狀態。

適用場景與注意¶

適合以下場景：

• 希望 web_search 走 Tavily。
• 需要在 WebUI 中調整完整 Tavily 請求參數。
• 需要 yaml 配置優先，避免 UI 中舊值覆蓋開發者固定值。
• 需要頁面抓取，並可選用 tavily-extract 或 firecrawl。
• 需要連通性測試、用量查看、多 key 輪換、降級和調試日誌。

使用前建議注意：

• 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。材料中 package.json 列出了 LICENSE 文件，但未給出具體許可證類型。
• 已存儲 key 不能由瀏覽器讀回；測試已配置 key 時需要重新輸入一次。
• 持久化結果緩存默認關閉，且爲 best-effort。
• TTL/LRU cache 默認跳過時效敏感搜索，例如新聞、金融或帶時間窗口的請求。
• 自動降級只在 service-side 失敗時觸發，不會把 429、401 這類 key-level 故障當成服務宕機。
• Firecrawl 未配置 key 時保持未啓用，fetch 會報告 WEB_PROVIDER_CREDENTIAL_MISSING。
• DSH 插件目錄是獨立站點，不應理解成官方應用商店。

相關鏈接¶

• 目錄頁：https://www.skillhub.cn/plugins/1624318455/dsh-plugin-tavily
• GitHub：https://github.com/1624318455/dsh-plugin-tavily