dsh-plugin-web-search-tavily

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

# dsh-plugin-web-search-tavily

English | [中文](README.zh.md)

A community [Tavily](https://tavily.com) search provider for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`). It registers a `WebSearchProvider` into the `ctx.web` capability seam, so the shipped `web_search` tool can be served by Tavily without touching any model-facing schema.

Ships as a **dsh bundle**: installing it into a profile inserts its plugin row automatically.

## Install

```sh
dsh plugin --profile web add dsh-plugin-web-search-tavily
```

Provide the API key through the environment (`TAVILY_API_KEY`, e.g. in `$DSH_HOME/.env`) or through plugin config. When more than one search provider is usable in your composition, pin the selection with `$DSH_WEB_SEARCH_PROVIDER=tavily` or by patching the `web` row's `searchProvider` in your profile's `cordis.patch.yml`; with Tavily as the only usable provider, selection is automatic.

Verify without booting, then boot:

```sh
dsh --profile web --dump-config   # shows a "# == dsh-plugin-web-search-tavily" layer
dsh --profile web
```

## Config

Override any field by patching the `web-search-tavily` row in your profile's `cordis.patch.yml` (a patch replaces the whole `config` value — restate the fields you keep):

| Key | Default | Meaning |
|---|---|---|
| `apiKey` | `$TAVILY_API_KEY` | Tavily API key. Empty makes the provider registered-but-unavailable. |
| `baseURL` | `https://api.tavily.com` | Endpoint base; `/search` is appended. |
| `searchDepth` | `basic` | Tavily `search_depth`. `advanced` returns richer snippets at extra credit cost. |
| `topic` | `general` | Tavily `topic` vertical (`general` or `news`; `news` populates `publishedAt`). |
| `includeAnswer` | `true` | Request Tavily's generated answer; it surfaces as the search result's `content`. |
| `numResults` | *(omitted)* | Default result count when a request carries no `maxResults`. The seam still enforces the tool-layer bound either way. |

```yaml
- id: web-search-tavily
  config:
    searchDepth: advanced
    includeAnswer: false
```

## Behavior

- `POST {baseURL}/search` with `Authorization: Bearer `, honoring the request `AbortSignal`; redirects are refused.
- `results[].content` maps to `snippet`, `published_date` to `publishedAt`; entries without a non-blank snippet are dropped rather than padded with invented text.
- A non-blank `answer` maps to the result's `content`; nothing is fabricated when Tavily returns none.
- Cancellation surfaces as `WebError` code `WEB_ABORTED`; every other failure (transport, non-2xx, unprocessable body) is `WEB_PROVIDER_ERROR` with the richest provider detail available and a preserved `cause` chain. A non-2xx JSON error body's `detail.error` / `detail` / `error` / `message` fields are tried in that order.
- `available()` is a cheap local check (key present, base URL parseable, bounds valid) and never touches the network.

## Model Experience

### What the model sees

Nothing from this package directly. The model-facing `web_search` schema and rendering belong to `@deepseek-ai/dsh-tool-web`; this provider only changes which backend serves the call. Result `content` (Tavily's generated answer, when enabled) and per-source `title`/`snippet`/`publishedAt` flow through the tool's ordinary rendering.

### Token effect

`includeAnswer: true` adds one provider-generated answer paragraph to each search result the model reads. `searchDepth: advanced` tends to return longer snippets. Both are provider-output effects; the tool-layer `maxResults` bound is enforced by the seam regardless of provider.

### KV Cache effect

None. Search results enter the conversation as ordinary tool results; this package contributes no prompt sections and changes no request prefix.

## Development

```sh
npm install
npm run build
npm test                      # keyless: loopback double asserts wire shape and error taxonomy
TAVILY_API_KEY=tvly-... npm test   # adds the live smoke (self-skips without the key)
```

Keyless tests drive the real provider against a loopback HTTP double and assert the exact request shape (method, path, bearer header, user-agent, body fields), response mapping, the error taxonomy, and cancellation. The live smoke verifies the wire contract against the real API and self-skips without a key; it last passed against the live Tavily API at v0.1.1 (2026-08).

## Known Limitations and Deferred Work

- **The Tavily wire contract is pinned to its 2026-08 public documentation.** Field names (`search_depth`, `include_answer`, `max_results`) are this package's responsibility to track; the live smoke is the drift detector, last green against the live API at v0.1.1.
- **`include_domains` / `exclude_domains` / `days` are not exposed.** The seam's request carries only `query` and `maxResults` today; domain filtering would be provider config rather than a per-call control, and no consumer has asked for it yet.
- **No retry policy.** A transient Tavily failure surfaces as one `WEB_PROVIDER_ERROR`; retrying is left to the caller or a future seam-level policy, matching the in-tree providers.
- **dsh is in developer preview.** This package pins `@deepseek-ai/dsh-web` to the currently published pre-release; expect lockstep bumps while upstream iterates.

## License

MIT