前言¶
DeepSeek Harness (DSH) 的 web_search 工具默認使用官方提供的搜索能力。在實際使用中，單一路由或單一提供方在額度管理、容錯和靈活性上往往不夠。dsh-tavily 插件通過 Tavily Search API 替換了 DSH 官方的網頁搜索，提供多 API Key 管理、餘額輪詢和自動故障切換的能力。
這是什麼¶
dsh-tavily 是一個用於 DeepSeek Harness 的持久化插件，由 Yuuz12 維護。它屬於「聯網工具」類別，遵循 MIT 許可證。
該插件旨在解決 DSH 官方網頁搜索的單一性限制，允許用戶在 DSH 界面中管理多個 Tavily Key，並根據餘額或自定義順序進行調用，同時具備本地用量統計和失敗重試機制。
核心功能¶
- 替換官方網頁搜索：在設置中切換後，模型調用
web_search工具時會走 Tavily API，關閉後自動回落到官方搜索。 - 多 API Key 池管理：支持添加任意數量的 Tavily API Key。
- 智能調度策略：
- 餘額優先輪流：默認策略，按剩餘額度排序，額度高的優先；額度並列的輪流使用。
- 手動順序：支持自定義 Key 的使用順序。
- 失敗自動切換：當某把 Key 出現鑑權失敗、額度用盡或限流（429）時，自動切換至下一把 Key。429 限流有 30 秒冷卻，其他錯誤有 5 分鐘冷卻。
- 本地用量統計與刷新：本地記錄調用次數、成功/失敗及積分消耗，支持一鍵從 Tavily 官方接口刷新余額。
- 設置集成：配置項直接集成在 DSH 的「插件配置」界面卡片中。
- 安全集成：支持與
dsh-webui-auth集成，通過會話校驗保護 API 端點。 - 零依賴：純 JavaScript 實現，無構建步驟。
安裝與啓用¶
安裝前請確保 DeepSeek Harness 版本不低於 0.1.2-alpha.2（DSH Desktop 2.0.4）。
使用官方推薦的 npm 安裝命令：
npx @deepseek-ai/dsh plugin --profile web add @yuuz12/dsh-tavily
安裝完成後必須重啓 DSH 才能生效。如果已安裝舊版本，建議先卸載再安裝：
npx @deepseek-ai/dsh plugin --profile web remove @yuuz12/dsh-tavily
使用方法¶
- 打開 設置 → 插件 → 插件配置。
- 在卡片列表中找到「Tavily 網頁搜索」並展開。
- 在密鑰區域粘貼 Tavily API Key（可在 app.tavily.com 免費註冊獲取，每月 1000 積分），點擊添加密鑰。
- 點擊密鑰區右上角的刷新全部用量按鈕，拉取每個 Key 的官方餘額數據。
- 打開頂部的替換官方網頁搜索開關。
- 調整多密鑰策略（餘額優先 / 手動順序）、搜索深度、單次結果上限等參數。
多密鑰調度規則¶
插件提供兩種調度模式，具體行爲如下：
| 策略 | 行爲描述 |
|---|---|
| 餘額優先（默認） | 剩餘積分多的 Key 優先；無限額度的計劃最優先；從未刷新過用量的 Key 排在已知餘額之後作兜底；頭部並列的密鑰按請求次數輪流使用。 |
| 手動順序 | 嚴格按列表自上而下使用，不做輪轉。 |
| 失敗切換 | 任一密鑰出錯時自動嘗試下一把；全部失敗才向模型報錯。 |
| 冷卻機制 | 401/403（鑑權失敗）、432/433（超額）導致 5 分鐘冷卻；429（限流）導致 30 秒冷卻。冷卻中的密鑰會沉底但繼續參與 Failover。 |
數據與安全¶
- 存儲位置：密鑰與統計數據存儲在本地。使用 npm 安裝時，數據文件位於
<profile>/dsh-tavily.json。 - 隱私保護：密鑰僅存儲在本地，不會隨 HTTP 響應返回完整內容。界面顯示時已脫敏（如
tvly-…xxxx）。 - 數據安全：升級或重裝插件不會丟失密鑰與統計；插件卸載不會自動刪除該文件。
- dsh-webui-auth 集成：插件會探測
sessions.jsonl文件以啓用會話校驗。若找到，所有/dsh-tavily/*端點將要求有效的dsh_wua_sessionCookie；未找到則保持開放。
結尾¶
dsh-tavily 通過引入多 Key 池和智能調度，爲 DSH 用戶提供了更可控的網頁搜索能力。它不依賴外部構建工具，且所有敏感數據均本地化處理，適合需要精細管理搜索配額的場景。
