dsh-tavily

English | 简体中文

Tavily web search for DeepSeek Harness (DSH) — multiple API keys, rotation and failover, a live usage gauge, the direct extract / map / crawl tools, and a key-management card on the Plugins page.

The built-in web_search tool is never replaced: Tavily is an addition to the native search, not a swap-in for it. This plugin registers no web-search provider and never rewrites web.searchProvider.

Highlights

• 🔑 Multiple Tavily API keys — manage a flat key list from the DSH UI.
• 🔁 Key rotation & failover — round-robin across keys; automatically retries on HTTP 401/429/432/433, and a load-balance mode caps in-flight requests per Tavily account.
• 📊 Live usage gauge — per-key Tavily usage and totals, fetched server-side without exposing keys.
• ⚡ Direct Tavily tools — tavily_extract reads a known URL's content, tavily_map discovers a site's links, and tavily_crawl pulls an entire site, all under the same key rotation.

Install

From the Plugins page

1. Open Plugins in the DSH sidebar and choose Add plugin.
2. Enter the npm package name @moguiyu/dsh-tavily, or the GitHub address https://github.com/moguiyu/dsh-tavily for the source. The field also takes a tarball or an absolute local path.
3. Press Install, then Enable now. A freshly installed bundle stays switched off until you enable it.

The card then renders on the dsh-tavily bundle's own page — between its description and its rows.

From the CLI

The dialog accepts exactly what dsh plugin add accepts, so either route works:

# from the npm release — the stable, marketplace-counted version
dsh plugin --profile web add @moguiyu/dsh-tavily

# from the repository — always the latest source
dsh plugin --profile web add github:moguiyu/dsh-tavily

--profile <name> picks the profile to install into; both forms resolve to the same plugin.

Requirements — DSH is a development preview (0.1.x-rc/alpha, 0.2.x-rc). The tools and the key/usage routes work on every supported line, 0.1.0-rc.7 onward. Both the card and the Plugins-page install route need 0.1.6-alpha.2 or newer, the release that added the Plugins page and moved plugin configuration there; on older lines the plugin is fully functional and installs from the CLI, it simply has no card. The npm name is the scoped @moguiyu/dsh-tavily, not the similarly-named community dsh-tavily provider-swap plugin.

Compatibility — 0.3.x is a single self-contained package: the tools, the routes and the card all live in @moguiyu/dsh-tavily, which uses only the long-stable ctx.tools / ctx.webServer / ctx.credentials / ctx.systemPrompt seams. There is no version-specific code path left to feature-detect. Peer ranges list one comparator per host tuple (^0.1.0-rc.7, ^0.1.1-rc.1, ^0.1.2-alpha.2, ^0.1.3-alpha.1, ^0.1.5-0, ^0.1.6-0, ^0.1.7-0, ^0.2.0-0), because prerelease comparators never cascade — a new host line means a new comparator, not a widened old one.

Packages

One package. Earlier releases also shipped @moguiyu/dsh-tavily-backend and @moguiyu/dsh-tool-tavily-search. From 0.3.0 both are folded into @moguiyu/dsh-tavily, which is now self-contained; the two old packages are deprecated and no longer updated.

Credentials

• TAVILY_API_KEYS — comma-separated key list; the tools rotate through it, retrying on HTTP 401/429.
• TAVILY_API_KEY — primary key auto-synced to the first key.

Both are managed automatically by the card. Keys never leave the server unmasked, and no state file holds key material.

Key usage strategy

• Rotate each key — round-robin; on HTTP 401/429/432/433 the next key is tried.
• Lowest usage first / Highest usage first — re-order keys by live Tavily usage on save.
• Load balance — keep at most N requests in flight per Tavily account (1 by default) and spread concurrent calls across accounts, so one free account is never hit in parallel. Tavily's 100 requests/minute applies per account, and several keys can share one account; the grouping is inferred from each key's account block on /usage, and any key can be pinned or split off by hand in the card's Account column.

Keys that cannot serve a request are skipped rather than failing the call: 401, 429, 432 (plan limit) and 433 (pay-as-you-go limit) all fail over to the next key, and every key is tried at most once per call.

Tavily tools

tavily_search plus the direct tools, all independent of web_search:

• tavily_search — full search surface (search_depth, topic, days, domain filters, include_answer, include_raw_content);
• tavily_extract — pull the complete content of known HTTP(S) URLs;
• tavily_map — discover a site's links without fetching page content;
• tavily_crawl — crawl a site and return the extracted content of its pages.

Composing the plugin registers them; there is no separate tool-level switch. To turn them off, disable the plugin with the toggle on its Plugins page — the built-in web_search keeps its native provider either way, and its schema is never touched.

State files

• ~/.dsh/tavily-manager.json — saved key dates, strategy, per-account concurrency cap, and the inferred/pinned account grouping (masked names only)

Mode 600, no secrets stored.

Development

pnpm install
pnpm test
pnpm build

License

MIT