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, research for synthesized reports, 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.
• 📝 Research reports — tavily_research runs Tavily's Research endpoint (mini/pro/auto), waits for the task and returns a synthesized, cited report; tavily_get_research collects one that was still running. Research costs far more credits than search (mini 4–110, pro 15–250), so it stays opt-in per call.

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/alpha). The tools and the key/usage routes are verified on 0.1.6-alpha.2, 0.1.7-rc.2, 0.2.0-rc.2 and the 0.2.1-alpha line, and are expected to work on every declared line back to 0.1.0-rc.7 — the peer range is deliberately wider than the verified store matrix. 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, ^0.2.1-0), because prerelease comparators never cascade — a new host line means a new comparator, not a widened old one. dsh.compatibility.dshReleases is the narrower, actually-verified store matrix: a rolling window over the last few host lines, not a historical ledger. Both are generated from one file, compatibility.json, so they cannot drift apart.

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 and the research pair, 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;
• tavily_research — queue Tavily's Research endpoint and wait for a synthesized, cited report (model: mini / pro / auto, plus citation_format, output_length, domain filters and an optional output_schema);
• tavily_get_research — collect a research task by request_id when it outlived the first call.

tavily_research polls the task and returns the report when it finishes; timeout_seconds: 0 queues it and returns the id immediately. mini suits narrow questions (observed live: ~11 s, 9 credits) and pro broad ones (minutes). Because research is billed dynamically and far above search — mini 4–110 credits, pro 15–250 — it is a per-call choice, not a default.

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