@dsh-external/dsh-plugin-tavily

🖥️ GUI usage (recommended for most users)

Open 设置 → 插件 → 网页搜索 and expand the Web search (Tavily) card.

• Basic area (always visible):
  • Status indicator — a live badge (✅ normal / ⚠️ credits low / ✗ API error / no key) checked by the host with the stored key (GET /api/tavily-status, which reads Tavily GET /usage and costs no search credits); the Refresh button forces a re-check (auto-checks are throttled to once a minute).
  • Web search engine — Tavily (default; keyless if no key) or official DeepSeek. This is the real provider switch; the plugin is already elected as the provider.
  • API key — paste your Tavily key. It is stored through the credentials service, never in a settings file.
  • API Base URL — leave blank for https://api.tavily.com, or set a proxy/endpoint base.
  • Parameter preset — apply Deep research, Quick summary, or Live news in one click: several advanced fields are staged at once (yaml-pinned fields are skipped); press Save to apply.
  • Test API connection — verifies the key/base URL you just entered; failures are classified (invalid key / insufficient credits / rate limited / service down / timeout / network) with a targeted explanation. Testing consumes one Tavily search credit. If a key is already configured but you have not typed one, the card tells you to re-enter it once; the browser intentionally cannot read stored secrets back.
  • Estimated cost — a live line shows the estimated credits and rough token count for the current depth/result/chunk settings.
  • Check usage — reads Tavily GET /usage with the currently entered key and shows the remaining credits, search usage, and plan. Stored keys must be re-entered once, like the connectivity test.
• Advanced area (🔧 Advanced Tavily request parameters):
  • Max results — how many web results per search (1–20, default 5).
  • Search depth — basic (balanced), advanced (2 credits, deep), fast, or ultra-fast (1 credit, lowest latency).
  • Topic — general, news, or finance.
  • Generated answer — true/basic (quick) or advanced (detailed).
  • Raw page content — false, markdown, or text; enabling greatly increases context token usage.
  • Chunks per source — snippet chunks per source (1–3).
  • Time range — recency preset (day/week/month/year/d/w/m/y).
  • Start date / End date — precise YYYY-MM-DD publish windows.
  • Include images / Image descriptions / Include favicon — request richer result metadata.
  • Include domains / Exclude domains — site allow/deny lists.
  • Country boost — bias toward one country (general topic).
  • Rate-limit retries — extra attempts (0–5) after a 429; waits honor retry-after with a bounded backoff.
  • Cache TTL (seconds) — cache identical searches to save credits; 0 disables (0–3600).
  • Cache max entries — LRU cap on cached searches (1–10000, default 200); the oldest entry evicts past it.
  • Skip cache for fresh queries — when on (default), news/finance searches and searches with a time window bypass the cache entirely.
  • Debug logging — one concise line per search/extract (query excerpt, credits, cache state, duration, errors); never the key or raw bodies.
  • Citation format — plain (answer only, default) or footnote (appends [1] title — url… numbered sources the model can cite).
  • Fallback engine — none (default) or DeepSeek (automatic): on a Tavily-side failure (timeout/network/5xx) the search is answered by the official DeepSeek provider.
  • Request timeout (ms) — default 30000.
  • Recency window (days) — optional recency filter for news/finance topics.

Every control has a short hint and a placeholder showing the default. Values are saved with the card's Save button and apply live; no service restart is needed.

If a field shows "Covered by config file; edit the yaml to change", it is pinned by cordis.patch.yml — the WebUI deliberately does not allow overriding it.

⚙️ Config-file usage (developer/pro users)

Configuration lives in your profile's cordis.patch.yml (~/.dsh/profiles/web/cordis.patch.yml). Add a web-search-tavily row with a config block:

- id: web-search-tavily
  name: '@dsh-external/dsh-plugin-tavily'
  config:
    searchDepth: advanced
    topic: news
    maxResults: 8
    includeRawContent: false
    timeout: 20000
    engine: tavily
    citeFormat: footnote          # numbered [1] title — url citations in the answer
    fallbackEngine: deepseek      # answer via DeepSeek on a Tavily-side outage
    apiKeyRefs:                   # multi-key rotation ring (credential refs only)
      - TAVILY_API_KEY_1
      - TAVILY_API_KEY_2

Priority

cordis.patch.yml config  >  WebUI card values  >  code defaults

• If a key is present in the yaml config block, the card disables that field and shows the configuration-covered badge.
• If the yaml does not set a field, the WebUI value (if any) is used.
• If neither sets it, the code default applies.

Settings table

Key	Default	Meaning	GUI editable
apiKey	unset	literal Tavily API key; prefer the credentials store instead	key field (via credentials)
apiKeyEnv	TAVILY_API_KEY	credential reference / environment key the provider resolves per search	config only
apiKeyRefs	[]	extra credential references for the multi-key rotation ring (refs only; keys stay in the credentials store/env)	config only
baseURL	https://api.tavily.com	endpoint base, /search appended	✓
maxResults	5	default number of web results per search (1–20)	✓
searchDepth	basic	basic/advanced/fast/ultra-fast	✓
topic	general	general, news, or finance	✓
includeAnswer	true	generated answer: true/basic (quick) or advanced (detailed)	✓
includeRawContent	false	raw page content: false, markdown, or text (context-heavy)	✓
chunksPerSource	3	snippet chunks per source (1–3)	✓
timeRange	unset	recency preset: day/week/month/year/d/w/m/y	✓
timeout	30000	request timeout in milliseconds	✓
engine	tavily	engine answering web_search: tavily (keyless if no key) or deepseek	✓
citeFormat	plain	answer/source layout: plain or footnote (numbered citations)	✓
fallbackEngine	none	on a Tavily-side failure (timeout/network/5xx), answer via deepseek	✓
days	unset	recency window in days (news/finance topics)	✓
retryMaxAttempts	2	extra attempts after a 429 (0–5)	✓
cacheTtlSeconds	0	query-cache TTL in seconds (0 disables)	✓
cacheMaxEntries	200	LRU cap on cached searches (1–10000)	✓
cacheBypassFresh	true	skip the cache for news/finance or time-windowed searches	✓
cacheFile	unset	JSON file the result cache persists to (survives restarts); unset/empty disables	config only
debug	false	concise per-search debug logging (never the key/raw bodies)	✓
firecrawlBaseURL	https://api.firecrawl.dev/v1	Firecrawl fetch provider endpoint base (/scrape appended)	config only
firecrawlApiKey	unset	literal Firecrawl API key; prefer the credential reference	config only
firecrawlApiKeyEnv	FIRECRAWL_API_KEY	Firecrawl credential reference resolved per fetch	config only
startDate	unset	include results after this YYYY-MM-DD	✓
endDate	unset	include results before this YYYY-MM-DD	✓
includeImages	false	collect query-related and per-source images	✓
includeImageDescriptions	false	add a description per image	✓
includeFavicon	false	include the favicon URL per result	✓
includeDomains	[]	only include these domains (allow list)	✓
excludeDomains	[]	exclude these domains (deny list)	✓
country	unset	boost results from one country (general topic)	✓
numResults	5	deprecated alias for maxResults	no (use maxResults)

apiKeyEnv stays config-only deliberately: it is an advanced wiring detail. Values saved from the GUI land in ~/.dsh/settings.yaml's web-search-tavily section. Settings edits apply live — the provider re-reads the section for every operation, so no restart or re-registration is needed after changing a value from the card or the file.