Preface

When building agent toolchains in DeepSeek Harness (DSH), there are times when you need to add Tavily search capabilities without replacing the built-in web_search. moguiyu/dsh-tavily is designed for this scenario: it integrates Tavily into DSH as a set of optional enhancement tools while preserving DSH’s original search path.

What This Is

moguiyu/dsh-tavily is a DSH plugin maintained by moguiyu, licensed under MIT. It primarily provides:

  • Multiple Tavily API key management
  • Key rotation and failover
  • Usage viewing
  • Direct Tavily tools such as tavily_search, tavily_extract, tavily_map, and tavily_crawl

The key boundary here is: it does not replace the built-in web_search, does not register a web-search provider, and does not override web.searchProvider.

Core Features

  • Multi-Key List: Maintain a flat list of Tavily API keys from the DSH settings interface.
  • Rotation and Failover: Supports round-robin; automatically retries on HTTP 401/429.
  • Usage Viewing: Displays Tavily usage and limits for each key, fetched server-side, with keys never exposed in an unredacted state.
  • Direct Tavily Tools: Provides tavily_search, tavily_extract, tavily_map, and tavily_crawl.
  • Settings Card: After refreshing the browser, the Tavily Search card appears under Settings → Plugins → plugin configuration.
  • Advanced Tools Disabled by Default: Advanced Tavily tools are opt-in; enabling them does not alter the default web_search.

Installation and Enablement

First, check the version requirements:

DSH: 0.1.0-rc.x
keyed plugin-config card: 0.1.0-rc.7 or later

Install from the GitHub repository:

dsh plugin --profile web add github:moguiyu/dsh-tavily

Install from the npm distribution package:

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

The npm package name is the scoped @moguiyu/dsh-tavily, not the same-named community dsh-tavily provider-swap plugin.

After installation, refresh the browser, and the Tavily Search card will appear under Settings → Plugins → plugin configuration.

Typical Usage

  1. Configure the key list:
TAVILY_API_KEYS=<key1>,<key2>,<key3>

TAVILY_API_KEY is automatically synced to the first key.

  1. Select the key usage strategy:
Rotate each key
Lowest usage first
Highest usage first
  1. To use direct Tavily tools, enable them in the tavily-search settings namespace. Once enabled, tavily_search, tavily_extract, tavily_map, and tavily_crawl are provided; these tools do not change the default web_search.

Local State and Secret Handling

State files include:

~/.dsh/tavily-manager.json
~/.dsh/tavily-tool.json
~/.dsh/tavily-toggle.json

Among these, ~/.dsh/tavily-toggle.json is a legacy state file. File permissions are set to mode 600, and no secret material is stored. Keys are never sent off the server in an unredacted state.

Applicable Scenarios and Notes

This plugin is suitable for developers who want to use Tavily within DSH while keeping the built-in web_search. If your primary needs are multi-key rotation, failover, and usage viewing, start by configuring TAVILY_API_KEYS; if you also need direct Tavily tools, enable them in the tavily-search settings namespace.

The plugin runs with the current dsh process’s permissions. Before installation, review the source code, license, and any third-party search services it will call. The plugin is licensed under MIT.

Access and Links

GitHub:

https://github.com/moguiyu/dsh-tavily

The catalog page can be found in the standalone plugin directory under either moguiyu/dsh-tavily or @moguiyu/dsh-tavily; the community directory is a separate site with no official affiliation to DeepSeek / 幻方 and should not be considered an official app store.