Introduction¶

The plugin-based architecture of DeepSeek Harness (DSH) allows developers to extend its capabilities. For Agents that require web search and web scraping, DSH’s default web-search-deepseek may not be sufficient, or developers may want to use third-party services such as Tavily and Firecrawl. dsh-tavily-firecrawl is a plugin that replaces DSH’s web connectivity with a combination of Tavily search and Firecrawl scraping, and supports multiple API key rotation.

Prerequisites¶

Before installing and using this plugin, ensure your environment meets the following requirements:

• DSH CLI: version ≥ 0.1.0-rc.5.
• Node.js: version ≥ 20.
• Package manager: pnpm must be installed (required by the dsh plugin command).
• DSH version: a DSH version with web seam (ctx.web) must be installed (the official dsh-base + dsh-web-app combination satisfies this requirement).

Installation¶

Install the official bundle directly via the CLI:

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

It can also be installed in the following ways:

• Pinned GitHub tag:

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

• Local tgz package:

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

• Use the script (no pnpm / dsh CLI required):

    ./install.sh

After installation, restart the dsh process to load the plugin configuration.

Core features¶

• Replaces the web capability: The plugin automatically disables the built-in web-search-deepseek, registers Tavily as the web_search provider, and registers Firecrawl as the web_fetch provider.
• Multiple key rotation: Supports configuring multiple API keys. The plugin automatically rotates among available keys. If a key encounters errors such as 401 (invalid), 429 (rate limited), or 402/403/432/433 (insufficient quota), it automatically switches to the next key, ensuring that a single request does not fail because one key is invalid.
• Pure ESM implementation: A pure JavaScript ESM module. No compilation is required. Dependencies are resolved through DSH’s node_modules, so no additional installation is needed.

Configuration and usage¶

After installation, provide Tavily and Firecrawl credentials through environment variables or a configuration file.

Option A: Environment variables

Add the following to $DSH_HOME/.env or the .env file in the startup directory:

TAVILY_API_KEY=tvly-xxxx
FIRECRAWL_API_KEY=fc-xxxx

Option B: Multiple key rotation (recommended)

If you registered multiple free-tier accounts, you can list the keys in environment variables or a configuration file. The plugin will rotate among them automatically:

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

Option C: Configuration file

Add the configuration to 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']

Note: Credentials are read once when the plugin is loaded. After modifying keys or configuration, you must restart the dsh process for changes to take effect.

Multiple key rotation and failure handling¶

The plugin classifies key state management into two categories: “permanent invalidation” and “temporary cooldown”.

Normal calls: Multiple concurrent requests are distributed across different keys and used in rotation.

Cooldown state: Stored in memory and cleared after restarting the dsh process.

Key resolution priority:
1. apiKeys in the configuration file (array)
2. apiKey in the configuration file (string)
3. *_API_KEYS environment variable
4. *_API_KEY environment variable

Note: When all keys are unavailable, the error explicitly reports the status of each key and the estimated recovery time.

Tools and presets¶

This plugin only provides providers for web_search and web_fetch. Tool registration is determined by the Agent preset’s tool-web.fetch.

• DSH version ≥ 0.1.5: The built-in preset already has fetch: true enabled, so it is ready to use after installation.
• DSH version ≈ 0.1.0-rc.5: The built-in preset does not enable fetch. You need to enable it manually or use the standard-web preset included with this plugin:

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

Verification¶

After installation, you can verify it in the following ways:

1. Command-line verification: Ask the Agent to perform operations directly.
   • “Search DeepSeek”
   • “Fetch https://example.com”
2. Local tests (no network required):

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

FAQ¶

• What if search reports HTTP 432? The Tavily account has exceeded its plan quota; the message includes the original error text. Consider adding key rotation or upgrading the plan.
• What if search reports has no usable API key? All keys are in cooldown or invalid. The message lists the status of each key. Restarting the process clears the in-memory cooldown state.
• What if configuration changes do not take effect? The plugin loads its configuration at startup; you must restart the dsh process.
• What if the web_fetch tool is missing? Check whether fetch: true is enabled in the Agent preset.

Conclusion¶

dsh-tavily-firecrawl is a lightweight DSH plugin. By introducing Tavily and Firecrawl, it addresses extensibility and key management issues for the native web capability. Its multiple key rotation mechanism can effectively improve service availability.

• GitHub repository: https://github.com/skillre/dsh-tavily-firecrawl
• Plugin directory: https://www.skillhub.cn/plugins/skillre/dsh-tavily-firecrawl