dsh-tavily-resilient-search：DSH 的彈性 Tavily 網絡搜索插件

前言¶

在 DeepSeek Harness (DSH) 的生態中，聯網能力通常通過插件實現。當使用 Tavily API 時，開發者常面臨密鑰限流（429）、配額耗盡（432/433）或密鑰被吊銷（401）的問題。如果處理不當，這些錯誤會直接中斷 Agent 循環，導致任務失敗。dsh-tavily-resilient-search 旨在解決這一痛點，通過原子級密鑰輪換和 Keyless 降級模式，保證 Agent 循環的連續性。

這是什麼¶

dsh-tavily-resilient-search 是一個獨立的 Cordis 插件，由用戶 frederico-kluser 維護。它通過 Tavily API 提供實時網絡搜索，核心能力包括：

原子級密鑰輪換：當一組密鑰中某個遇到限流或錯誤時，自動切換到下一個可用密鑰，而不中斷 Agent 循環。
Keyless 降級：當所有密鑰失效或未配置時，自動切換到 Keyless 模式（限制更嚴），並給出明確提示。
密鑰管理面板：提供 Web 界面進行密鑰的增刪改查及測試。
安全審計：記錄關鍵操作和拒絕的請求。

該插件遵循 MIT 許可證。

安裝與啓用¶

安裝該插件需要 Node.js 環境版本大於等於 24。安裝過程通過 DSH 的包管理器完成，插件聲明瞭 dsh.bundle.patch，因此安裝後會自動激活。

dsh plugin --profile web add dsh-tavily-resilient-search

安裝後，相關配置會自動注入到 DSH 的 Bundle 層。

配置與密鑰管理¶

環境變量配置¶

密鑰必須通過環境變量設置，絕不能以明文形式硬編碼在配置文件中。插件會按順序讀取環境變量。

export TAVILY_API_KEY_A="tvly-..."
export TAVILY_API_KEY_B="tvly-..."
export TAVILY_API_KEY_C="tvly-..."

Web 界面管理¶

插件提供了一個管理面板用於維護密鑰池。

訪問面板：在 DSH 界面的“Settings”中，只有當沒有有效密鑰時纔會顯示“Tavily Keys”入口。
CRUD 操作：支持添加、列出、編輯、刪除和測試密鑰。編輯和刪除操作需要二次確認（nonce）。
管理員令牌：首次啓動時，系統會生成一個 CSPRNG 令牌，保存在 ~/.dsh/dsh-tavily-resilient-search/admin-token.txt（權限 0600）。
- 如果忘記令牌，可通過環境變量 DSH_TAVILY_ADMIN_RESET=1 重置。
- 也可以直接設置 DSH_TAVILY_ADMIN_TOKEN。
安全策略：默認僅允許 Loopback 訪問。如果需要綁定公網地址（0.0.0.0），必須在配置中顯式開啓 admin.allowPublicBind: true，否則面板拒絕啓動。

配置參數¶

配置通過 Profile、Home 或 CLI 覆蓋層進行，注意插件採用整條目替換策略，而非深度合併。

字段	類型	默認值	說明
`apiKeys`	`string[]`	`[]`	密鑰數組，按順序輪詢。空數組表示 Keyless 模式。
`searchDepth`	`ultra-fast\\|fast\\|basic\\|advanced`	`basic`	搜索深度。
`maxResults`	`1..100`	`5`	最大結果數，會自動鉗制在 10 以內。
`includeAnswer`	`boolean`	`true`	是否包含 Tavily 的摘要答案。
`timeoutMs`	`number`	`15000`	單次 HTTP 請求超時時間。
`callTimeoutMs`	`number`	`120000`	整個調用（包括輪換）的總超時時間。
`projectId`	`string`	—	用於項目隔離的 ID。
`admin.enabled`	`boolean`	`true`	是否啓用管理面板。
`admin.trustedRemotes`	`string[]`	`loopback`	信任的遠程源。
`admin.allowedHosts`	`string[]`	`127.0.0.1`, `localhost`, `::1`	允許的 Host 名。
`securityProfile`	`{sandbox, approval}`	必填	安全策略，通常爲 `sandbox: 'workspace-write', approval: 'ask'`。

工具用法¶

安裝並激活後，插件會暴露 web_search 工具。

調用方式：

web_search(query, search_depth, max_results, topic)

參數：

query (string, 必填)：搜索詞，推薦小於 1500 字符，硬限制 4000 字符。
search_depth (enum, 可選)：ultra-fast、fast、basic、advanced。
max_results (integer, 可選)：1 到 10。
topic (enum, 可選)：general 或 news。

返回值：

返回包含 ok、query、answer、sources、responseTime、keylessFallbackUsed、error、detail、suggestion 的結構化數據。即使出錯，也會返回結構化信息，而非拋出異常中斷進程。

錯誤處理機制¶

插件針對不同的 HTTP 狀態碼有明確的處理邏輯：

429 (限流) / 432 (配額) / 433 (配額)：標記當前密鑰爲不可用，立即重試下一個密鑰，保持 payload 不變。
401 (未授權/吊銷)：密鑰失效，從池中移除並重試。
400 (參數錯誤)：不輪換密鑰，直接返回錯誤並附帶修正建議。
超時或網絡錯誤：嘗試輪換密鑰；若所有密鑰均失敗，則觸發 Keyless 模式或返回錯誤。

注意事項¶

Node 版本：必須使用 Node.js 24 或更高版本。
權限：插件以當前 DSH 進程的權限運行，需確保環境變量已正確設置。
源碼審查：雖然許可證爲 MIT，但在生產環境使用前，建議審查源碼以確保符合安全規範。
配置方式：配置時直接覆蓋配置項，注意不要試圖深度合併覆蓋 apiKeys 等數組字段。

總結¶

dsh-tavily-resilient-search 是一個爲追求高可用性而設計的 DSH 插件。它通過自動化的密鑰管理和容錯機制，解決了 Tavily API 在實際使用中常見的限流和配額問題，確保 Agent 在聯網任務中不會因 API 錯誤而意外終止。