@arcaneorion/dsh-tavily-web：DeepSeek Harness Tavily 檢索與網頁抓取能力層

前言¶

DeepSeek Harness (DSH) 採用插件化架構。在構建需要聯網能力的智能體或應用時，對接 Tavily API 進行檢索以及獲取網頁正文是常見需求。本插件旨在爲 DSH 提供一個能力層，通過註冊兩個模型可見的工具，解決單賬號額度耗盡導致工具失效的問題，並提供基於 shell seam 的網頁抓取能力。

核心能力¶

插件註冊了兩個模型可見的工具，並將自身掛載爲宿主 web 註冊表的唯一 fetch provider。

tavily_search：基於 Tavily API 的檢索工具。返回包含來源列表（URL、標題、摘要、發佈時間）的 JSON 數據。插件實現了多 API Key 輪詢池，單賬號額度耗盡時自動切換下一把 Key，不會導致整個工具失效。
web_fetch：基於 shell seam 調用 curl 抓取單頁的工具。不依賴 Tavily API，無需 Key。返回 HTTP 狀態碼及去標籤後的正文內容。

爲了與出廠的 DeepSeek provider 區分，檢索功能不註冊爲 web.search() provider，而是作爲模型可見工具存在，避免選擇歧義。

安裝與啓用¶

該插件爲 profile bundle，安裝一次後，該 profile 下的所有會話均可使用上述工具。

dsh plugin --profile web add @arcaneorion/dsh-tavily-web

安裝完成後，需要重啓 DSH（dsh --profile web），因爲 host 插件不支持熱重載。啓動日誌中應出現類似 (key pool: N ref(s), cooldown 900s) 的信息以確認加載成功。

配置說明¶

插件默認配置了一個包含 8 個 key 引用名的輪詢池（TAVILY_API_KEY 至 TAVILY_API_KEY_8）。未配置的引用名會被自動跳過，零成本運行。

要覆蓋默認配置，需修改用戶層 ~/.dsh/profiles/<profile>/cordis.patch.yml，而不是修改包自帶的 patch：

- id: tavily-web
  config:
    keyRefs: [TAVILY_API_KEY, TAVILY_WORK_KEY]   # 替換默認家族
    apiKeys: []                                  # 字面量 key，排在 keyRefs 之後；密鑰更該放 seam
    cooldownSeconds: 900                         # 403/429/432 後的退避秒數

技術細節與注意事項¶

兼容性¶

當前插件適配 DSH 0.2.0-rc.1（peer 聲明爲 0.2.0）。在升級 DSH 版本前，建議先驗證 peer 依賴版本，因爲 web 註冊表與 shell seam 的契約在不同版本間可能發生變化。

發佈形態限制¶

npm tarball 僅包含 src/、cordis.patch.yml、README.md，不包含 tests/ 目錄。要運行測試，需使用倉庫副本。

入口文件類型¶

package.json 的 main 字段必須指向普通 .js 文件（src/tavily-web.js），不能指向 .ts 文件。這是因爲 ESM 在 node_modules 中不支持 stripping types，直接加載 .ts 會導致靜默失敗（loader 無法初始化）。

Curl 調用陷阱¶

Tavily API 的報錯體（如 432 錯誤）是合法的 JSON，但 curl 遇到 HTTP 錯誤時退出碼仍爲 0。如果代碼僅解析 JSON 而不檢查 HTTP 狀態碼，會將 API 錯誤誤判爲“搜索結果爲空”。本插件在 web_fetch 中強制要求檢查狀態碼。

短結尾¶

該插件爲 DSH 提供了穩定的多 Key Tavily 檢索和網頁抓取能力，適合需要高可用性聯網功能的場景。更多源碼、測試用例及目錄信息，可參考其 GitHub 倉庫。