前言¶

DeepSeek Harness (DSH) 的插件化架構允許開發者擴展其能力。對於需要聯網搜索和網頁抓取的 Agent，DSH 默認的 web-search-deepseek 可能無法滿足需求，或者開發者希望使用 Tavily 和 Firecrawl 等第三方服務。dsh-tavily-firecrawl 是一個插件，它將 DSH 的聯網能力替換爲 Tavily 搜索 與 Firecrawl 抓取 的組合，並支持多 API Key 輪詢。

前置條件¶

在安裝和使用此插件前，請確保環境滿足以下要求：

• DSH CLI：版本需 ≥ 0.1.0-rc.5。
• Node.js：版本需 ≥ 20。
• 包管理器：需要安裝 pnpm（dsh plugin 命令依賴）。
• DSH 版本：需要安裝了帶 web seam（ctx.web）的 DSH 版本（官方 dsh-base + dsh-web-app 組合均滿足）。

安裝¶

通過 CLI 直接安裝官方 bundle：

dsh plugin --profile web add dsh-tavily-firecrawl

也可以通過以下方式安裝：

• 鎖定 GitHub Tag：

    dsh plugin --profile web add github:skillre/dsh-tavily-firecrawl#v0.2.0

• 本地 tgz 包：

    npm pack
    dsh plugin --profile web add ./dsh-tavily-firecrawl-0.2.0.tgz

• 使用腳本（無需 pnpm / dsh CLI）：

    ./install.sh

安裝完成後，需要重啓 dsh 進程以加載插件配置。

核心功能¶

• 替換聯網能力：插件會自動禁用內置的 web-search-deepseek，註冊 Tavily 作爲 web_search 提供方，註冊 Firecrawl 作爲 web_fetch 提供方。
• 多 Key 輪詢：支持配置多個 API Key，插件會自動在可用 Key 之間輪流使用。當某個 Key 出現 401（失效）、429（限流）或 402/403/432/433（額度不足）等錯誤時，會自動切換到下一個 Key，確保單次請求不會因單一 Key 失效而失敗。
• 純 ESM 實現：純 JavaScript ESM 模塊，無需編譯，依賴通過 DSH 的 node_modules 解析，無需額外安裝。

配置與使用¶

安裝後，需要在環境變量或配置文件中提供 Tavily 和 Firecrawl 的憑證。

方式 A：環境變量

在 $DSH_HOME/.env 或啓動目錄的 .env 中添加：

TAVILY_API_KEY=tvly-xxxx
FIRECRAWL_API_KEY=fc-xxxx

方式 B：多 Key 輪詢（推薦）

如果註冊了多個免費版賬號，可以通過環境變量或配置文件列出 Key，插件會自動輪詢：

# 逗號、分號或空白分隔都支持
TAVILY_API_KEYS=tvly-aaaa,tvly-bbbb,tvly-cccc
FIRECRAWL_API_KEYS=fc-aaaa;fc-bbbb

方式 C：配置文件

在 cordis.patch.yml 中添加配置：

- insert:
    - id: web-tavily-firecrawl
      name: 'dsh-tavily-firecrawl'
      config:
        search:
          apiKeys: ['tvly-aaaa', 'tvly-bbbb']
        fetch:
          apiKeys: ['fc-aaaa', 'fc-bbbb']

注意：憑證在插件加載時讀取一次。修改 Key 或配置後必須重啓 dsh 進程才能生效。

多 Key 輪詢與失敗處理¶

插件對 Key 的狀態管理分爲“永久失效”和“暫時冷卻”兩類。

正常調用：多個併發請求會落在不同的 Key 上，輪流使用。

冷卻狀態：保存在內存中，重啓 dsh 進程後清空。

Key 讀取優先級：
1. 配置文件 apiKeys（數組）
2. 配置文件 apiKey（字符串）
3. 環境變量 *_API_KEYS
4. 環境變量 *_API_KEY

注意：所有 Key 都不可用時，會明確報出每個 Key 的狀態和預計恢復時間。

工具與預設¶

本插件只負責提供 web_search 和 web_fetch 的 Provider，工具的註冊由 Agent 預設的 tool-web.fetch 決定。

• DSH 版本 ≥ 0.1.5：自帶預設已開啓 fetch: true，安裝後直接可用。
• DSH 版本 ≈ 0.1.0-rc.5：自帶預設未開啓 fetch。需要手動啓用，或使用本插件附帶的 standard-web 預設：

    cp -R node_modules/dsh-tavily-firecrawl/presets/standard-web "$DSH_HOME/.agent-presets/"

驗證¶

安裝完成後，可以通過以下方式驗證：

1. 命令行驗證：直接讓 Agent 執行操作。
   • “搜一下 DeepSeek”
   • “抓取 https://example.com”
2. 本地測試（無需聯網）：

    node --test "test/**/*.test.mjs"

常見問題¶

• 搜索報 HTTP 432？ 該 Tavily 賬號超了套餐額度，消息裏會直接帶原文。建議增加 Key 輪詢或升級套餐。
• 搜索報 has no usable API key？ 所有 Key 都在冷卻中或已失效。消息會列出每個 Key 的狀態。重啓進程可清空內存冷卻狀態。
• 改完配置不生效？ 插件在啓動時加載配置，必須重啓 dsh 進程。
• web_fetch 工具不存在？ 檢查 Agent 預設中是否啓用了 fetch: true。

結尾¶

dsh-tavily-firecrawl 是一個輕量級的 DSH 插件，通過引入 Tavily 和 Firecrawl，解決了原生聯網能力的擴展與 Key 管理問題。其多 Key 輪詢機制能有效提升服務的可用性。

• GitHub 倉庫：https://github.com/skillre/dsh-tavily-firecrawl
• 插件目錄：https://www.skillhub.cn/plugins/skillre/dsh-tavily-firecrawl