Introduction

The plugin mechanism of DSH closely follows the principle of “everything is a plugin”: search providers and fetch providers can be attached to host interfaces without requiring users to rewrite the main workflow. In scenarios where web_search needs to be switched to an external search engine, common pain points include scattered configurations, incomplete parameters, and inconvenient connectivity verification.

dsh-plugin-tavily solves this problem by providing a Tavily-backed web search provider for DeepSeek Harness. It places complete request parameters in the WebUI settings card while retaining the capability to prioritize YAML configurations. Below, we introduce its positioning, installation methods, and typical usage.

What is This

dsh-plugin-tavily is a DSH web search provider plugin maintained by 1624318455. It registers a tavily provider on the harness’s ctx.web seam, enabling web_search requests to be answered through Tavily.

The plugin also provides a WebUI settings card for pasting API keys, adjusting advanced parameters, and testing connectivity. It also supports fixed configurations via cordis.patch.yml. The package.json in the materials indicates the version is 0.6.2.

Core Features

Search Provider

  • Registers a tavily search provider on the ctx.web seam.
  • The web_search tool itself remains unchanged; only its backend is now Tavily.
  • Switchable between tavily and the official DeepSeek provider in the WebUI.
  • Operates in keyless mode without a Tavily key (free with rate limits); uses the corresponding account tier with a key.
  • Configuration priority: cordis.patch.yml > WebUI > code defaults.
  • Editable Tavily parameters in the WebUI include: API key, API Base URL, maxResults, searchDepth, topic, includeAnswer, includeRawContent, timeout, days, chunksPerSource, timeRange, startDate/endDate, includeImages, includeDomains/excludeDomains, country.
  • Provides parameter presets: Deep research, Quick summary, Live news.
  • Server-side connectivity probe endpoint: POST /api/tavily-probe.
  • Status endpoint: GET /api/tavily-status, used to display current key and quota status.
  • API connection tests provide categorized errors: invalid key, insufficient credits, rate limited, service down, timeout, network.
  • The settings card includes a Usage & cost panel, showing credit/token estimates for a single search under current settings and displaying usage via Tavily’s GET /usage.

Fetch Provider

  • Provides a fetch provider based on Tavily Extract: tavily-extract, used to read page content from URLs.
  • Provides an optional Firecrawl fetch provider: firecrawl, with default credential reference FIRECRAWL_API_KEY.
  • If no Firecrawl key is configured, fetching reports WEB_PROVIDER_CREDENTIAL_MISSING; remains disabled when not selected.

Stability and Engineering Options

  • Persistent result caching: cacheFile defaults to off, best-effort, with debounce; disk failures do not cause search failures.
  • Retries on 429 errors: bounded backoff, with optional TTL/LRU cache.
  • TTL/LRU cache defaults to skipping time-sensitive searches, such as news, finance, or requests with time windows.
  • Optional concise debug logging: does not log API keys or raw response bodies.
  • Multi-key rotation and failover: apiKeyRefs stores only references; keys remain in the credentials store or environment; enters a 60-second cooldown after 3 consecutive failures.
  • Citation formats: citeFormat: footnote or default plain.
  • Automatic fallback engine: fallbackEngine: deepseek, triggered only on service-side Tavily failures (e.g., timeout, network, 5xx); key-level faults like 429 or 401 do not trigger this fallback.
  • Key resolution order: literal apiKey → credentials service (apiKeyEnv) → process.env[apiKeyEnv].

Installation and Enabling

1. Install the Plugin

First, install the plugin. The official installation command is:

dsh plugin --profile web add "github:1624318455/dsh-plugin-tavily#main"

During development, you can also install from a local path:

dsh plugin --profile web add "file:/absolute/path/to/dsh-plugin-tavily"

After installation, restart dsh. The plugin’s included cordis.patch.yml will set web.config.searchProvider to tavily, so no manual selection of the search provider is needed.

2. Fill in the Tavily API Key

Open the WebUI:

Settings → Plugins → Web Search

Expand the Web search (Tavily) settings card and paste the Tavily API key into the API key field. You can also use keyless mode without a key.

3. Select the Search Provider

Switch the Web search engine in the settings card:

  • tavily
  • official DeepSeek

After completing the steps above, continue using web_search as usual. The tool interface remains unchanged; only the backend provider has changed.

4. Manually Override YAML (Optional)

If you want to manually fix the provider, you can write the profile configuration:

# ~/.dsh/profiles/web/cordis.patch.yml
- id: web
  config:
    searchProvider: tavily

Typical Usage

Enable Tavily Extract for Fetching

If you also need to use Tavily Extract for page fetching, set the fetch provider:

export DSH_WEB_FETCH_PROVIDER=tavily-extract

Or write in cordis.patch.yml:

- id: web
  config:
    searchProvider: tavily
    fetchProvider: tavily-extract

Enable Firecrawl Fetching (Optional)

If you need to switch to Firecrawl for fetching pages, set:

export DSH_WEB_FETCH_PROVIDER=firecrawl

Or write in the same configuration:

- id: web
  config:
    searchProvider: tavily
    fetchProvider: firecrawl

Using Firecrawl requires your own key. The default credential reference given in the materials is FIRECRAWL_API_KEY. Without a key, this provider reports WEB_PROVIDER_CREDENTIAL_MISSING during fetching; otherwise, it remains disabled.

Test Connection and View Status

The connection test in the settings card checks the currently entered key and API Base URL, providing categorized error descriptions. Stored keys cannot be read back by the browser; if testing an already configured key, you need to re-enter it once, and it will not be saved again.

Server endpoints:

POST /api/tavily-probe
GET /api/tavily-status

Where GET /api/tavily-status reads the stored key and displays status in conjunction with Tavily’s GET /usage.

Applicable Scenarios and Notes

Suitable for the following scenarios:

  • Wanting web_search to use Tavily.
  • Needing to adjust complete Tavily request parameters in the WebUI.
  • Requiring YAML configuration priority to prevent old UI values from overriding developer-fixed values.
  • Needing page fetching with the option to use tavily-extract or firecrawl.
  • Requiring connectivity testing, usage viewing, multi-key rotation, fallback, and debug logging.

Before use, please note:

  • The plugin runs with the permissions of the current dsh process. Check the source code and license before installation. The package.json in the materials lists a LICENSE file but does not specify the license type.
  • Stored keys cannot be read back by the browser; testing an already configured key requires re-entering it once.
  • Persistent result caching defaults to off and is best-effort.
  • TTL/LRU cache defaults to skipping time-sensitive searches, such as news, finance, or requests with time windows.
  • Automatic fallback only triggers on service-side failures; it does not treat key-level faults like 429 or 401 as service outages.
  • Firecrawl remains disabled when not configured with a key; fetching reports WEB_PROVIDER_CREDENTIAL_MISSING.
  • The DSH plugin directory is an independent site and should not be interpreted as an official app store.

Related Links

  • Directory page: https://www.skillhub.cn/plugins/1624318455/dsh-plugin-tavily
  • GitHub: https://github.com/1624318455/dsh-plugin-tavily