@junjiangao/dsh-web-search-tavily
基于 Tavily 的搜索提供商，用于 DeepSeek Harness 的 Web 能力接口（ctx.web）：无密钥模式、完整的官方搜索参数、设置部分和凭据支持
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:junjiangao/dsh-web-search-tavily#6e0caf8699db1b1211ab762373dc628d8797dcd9Web Search Tavily 以 @junjiangao/dsh-web-search-tavily 发布，当前版本为 0.2.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 中文
A Tavily-backed WebSearchProvider for the DeepSeek Harness web capability seam (ctx.web), modeled on the packages/web/web-search-* family. It registers a provider into ctx.web — it does not own ctx.web and does not register a model-facing tool (that is @deepseek-ai/dsh-tool-web).
Highlights:
Authorization, x-tavily-access-mode: keyless, and the dsh-web-search-tavily-keyless client source.dsh-settings section (editable from the web settings page) plus dsh-credentials resolution; the key can also come from a literal apiKey or the environment.dsh.bundle, installable with dsh plugin add.This package is distributed as a GitHub repository (not published to npm). Install it into a profile with dsh plugin, which forwards to pnpm:
# GitHub spec — main branch
dsh plugin --profile <name> add github:junjiangao/dsh-web-search-tavily
# pin a commit when you need reproducibility (a later push cannot change it)
# dsh plugin --profile <name> add github:junjiangao/dsh-web-search-tavily#<sha>
# or a local checkout
dsh plugin --profile <name> add /path/to/dsh-web-search-tavily
# or a packed tarball (no build permission needed)
pnpm pack
dsh plugin --profile <name> add ./dsh-web-search-tavily-0.1.0.tgz
Built lib/ artifacts are committed to the repository, and the package declares no lifecycle scripts, so a git install needs no build permission — pnpm never asks for an allowBuilds entry. When you develop the plugin, rebuild with pnpm build and commit the updated lib/ together with the source change. (A source-only revision without lib/ would need the pnpm allowBuilds step; prefer the main-branch flow above.)
Registering the provider is not the same as selecting it. The web seam picks a provider by id:
searchProvider on the web plugin row, orDSH_WEB_SEARCH_PROVIDER (only read when the web row carries no searchProvider — dsh-base currently sets searchProvider: deepseek-official, so the environment variable alone has no effect).With several search providers installed, pin tavily in the profile's cordis.patch.yml (a later layer than every bundle):
- id: web
config:
searchProvider: tavily # restate every other key the web row carries
This bundle deliberately only inserts its own plugin row and never overrides the web row: a patch row replaces the whole row config instead of deep-merging, and multiple provider bundles must not fight over it.
All fields optional except where the schema default is noted. The same schema powers the settings section.
| Key | Default | Meaning |
|---|---|---|
apiKey | (none) | Literal Tavily API key. Prefer apiKeyEnv/credentials so no secret enters configuration files; a stored literal is redacted from settings descriptions. |
apiKeyEnv | TAVILY_API_KEY | Credential reference / environment variable carrying the key. |
baseURL | https://api.tavily.com | Endpoint base; /search is appended. TAVILY_BASE_URL environment fallback. |
searchDepth | basic | ultra-fast |
topic | (none) | general |
timeRange | (none) | day |
startDate / endDate | (none) | Absolute dates (YYYY-MM-DD) sent as start_date / end_date. |
days | (none) | Day window sent as days. Positive integer. |
maxResults | (none) | Default result count when a request carries no maxResults; clamped to Tavily's 20. |
includeDomains / excludeDomains | [] | Domain lists sent as include_domains / exclude_domains; empty lists are omitted. |
includeAnswer | false | true |
includeRawContent | false | true |
includeImages | false | Sent as include_images; image results are not surfaced by the seam (deferred). |
includeImageDescriptions | false | Sent as include_image_descriptions. |
includeFavicon |
Key resolution order: literal apiKey → dsh-credentials (apiKeyEnv ref) → environment (apiKeyEnv, default TAVILY_API_KEY) → keyless.
# With key (env)
- id: web-search-tavily
name: '@junjiangao/dsh-web-search-tavily'
config:
apiKeyEnv: TAVILY_API_KEY
# With key (literal — prefer credentials/env)
- id: web-search-tavily
name: '@junjiangao/dsh-web-search-tavily'
config:
apiKey: !!js process.env.TAVILY_API_KEY
# Keyless — no key anywhere, the provider falls back to keyless mode
- id: web-search-tavily
name: '@junjiangao/dsh-web-search-tavily'
When every key source is empty, requests carry no Authorization, send x-tavily-access-mode: keyless, and use the dsh-web-search-tavily-keyless client source — the same convention as the official Tavily SDK. Keyless mode is a legitimate provider state, not a configuration error. Tavily's server rate-limits keyless use and may ignore or downgrade some parameters (result count, depth, answer). Only search (and extract) exist in keyless mode; this provider only ever calls /search.
WEB_SEARCH_TAVILY_SETTINGS_NAMESPACE = 'web-search-tavily' (a plain namespace constant) installs the configuration as a settings section through the dsh 0.1.2 settings service (settings.installSection, gated by ctx.inject(['settings'], ...)), so the web settings page can edit every field above and changes apply to the next search without re-registration. The recommended key path is the credentials service (written from the web Models/settings page) under the apiKeyEnv reference. A literal apiKey stored in settings is supported but persists in the settings document — prefer credentials or the environment.
The package also ships a client face (dsh.client declaration + exports["./client"], built as lib/client.js): it registers a web-search-tavily card into the settings page's "Plugins → Plugin configuration" tab covering the common fields (API key, key env var, endpoint, result count, search depth, topic, and the answer/images/raw content/favicon/usage toggles). The card binds the same settings namespace; other fields save straight into the settings document, while the API key goes through the credentials domain and never lands in the settings file. The wire face is probed per call to match the deployment line: dsh 0.1.1-rc.x serves connection.api.credentials (object arguments, { result: { ok, value | error } } envelope — the same face the official cards of that line call), while dsh 0.1.2+ mounts remote.credentials (positional arguments, RemoteResult envelope); failed reads retry with backoff until the face answers. @deepseek-ai/dsh-client-ui-primitives is declared as a bundle external for the native chevron. Restart the web service after install so the client-modules graph picks the package up (it scans loader entries at startup).
Card features:
PluginCard 1:1 — the native 14px primitives chevron, official spacing/typography/colors under a tavily- scoped stylesheet, the read-only notice when the document is not writable, and auto-collapse once the Host confirms a save. Closed by default; the whole header row (title + description + chevron) toggles it, with an unsaved badge while drafts exist.apiKeyEnv: TAVILY_API_KEY, searchDepth: basic, maxResults: 5, includeAnswer/includeImages/includeRawContent/includeFavicon/includeUsage: false) — deliberately not aggressive values, because keyless mode (no key) rate-limits and may ignore or downgrade result count, depth, and answer parameters; official defaults behave identically with and without a key. Staged only; review then save.web-search-deepseek card, the card asks the credentials domain via credentials.describe — an exported TAVILY_API_KEY, a credential-store record, or a stored literal all report as "configured" with no manual setup. Only when every source is empty does the keyless notice appear (rate limiting and parameter downgrade). A key supplied by the launch environment is read-only here: the key input disables (the official card gates on the same writable answer), and a genuinely refused write surfaces the host's own refusal message verbatim instead of a generic save-failure line.includeRawContent significantly raises tokens/cost, includeAnswer adds output tokens, maxResults scales with count, searchDepth: advanced is slower and costlier).answer (when includeAnswer is enabled) → content.WebSearchSource: url, title, publishedAt ← published_date, and snippet preferring content with raw_content as fallback. Blank fields are omitted; URL-less results are dropped.max_results is clamped to 20 (Tavily's documented bound); the seam still enforces the final maxResults truncation (truncated).Indirectly, through dsh-tool-web: the model sees the maxResults-bounded URLs, titles, snippets, and publication dates, plus the generated answer when includeAnswer is enabled. Provider failures surface as WebError WEB_PROVIDER_ERROR (message from the Tavily error body, including the keyless-limit envelope); cancellation surfaces as WEB_ABORTED. Credential-bearing requests reject redirects before the Location target is contacted.
No direct invalidation; the named consumer owns any request-prefix changes.
pnpm install
pnpm build # tsc → lib/; commit lib/ together with source changes
pnpm test # vitest unit suite
pnpm test:coverage # per-file 100% gate on src/
pnpm test:e2e # real-API smoke; self-skips without $TAVILY_API_KEY
Unlike harness in-repo packages (which extend tsconfig.base.json and build lib/types + bundled lib/index.js), this standalone package builds with a single tsc pass into lib/. The published API is unchanged. To vendor it into deepseek-harness/packages/web/web-search-tavily, switch the peer/dev dependencies to workspace:^ and adjust the tsconfig to the harness layout.
search is implemented — no Tavily extract/crawl/map/research; keyless mode only permits search/extract anyway.includeImages / includeImageDescriptions / includeFavicon / includeUsage pass through to the API but the seam has no surface for images/usage/favicons yet.searchProvider: tavily is a profile-layer decision (see above).WEB_ABORTED.MIT
false |
Sent as include_favicon; not surfaced (deferred). |
includeUsage | false | Sent as include_usage; not surfaced (deferred). |
autoParameters | false | Sent as auto_parameters. |
exactMatch | false | Sent as exact_match. |
language | (none) | Sent as language. |
filterByLanguage | false | Sent as filter_by_language. |
country | (none) | Sent as country. |
chunksPerSource | (none) | Sent as chunks_per_source. Positive integer. |