**English** | [中文](./README.md)

# dsh-hydrasearch

Two free, barely-rate-limited web search backends for DeepSeek Harness.

Once installed, the built-in `web_search` / `web_fetch` gain a safety net: TinyFish and AnySearch stand by in order, and one takes over automatically when the other fails.

> **Version 0.4.0, and DSH 0.2.0-rc.2 is supported.** Verified on a local 0.2.0-rc.2 desktop build: the plugin loads, and both `web_search` and `web_fetch` return through the TinyFish / AnySearch chain. The older generations (0.1.x-rc.6, 0.1.6-alpha.2, 0.1.7-alpha.1, 0.1.7-rc.1) are no longer supported — see "Supported DSH versions".

## Why use it

- **Both are free, with very high rate limits.** TinyFish and AnySearch both offer free usage that everyday searching and fetching will not exhaust. AnySearch does not even require a key up front — anonymous access works, at a lower quota.
- **Automatic failover between two backends.** If one times out, gets rate-limited, or errors out, the next one takes over, so a search never fails as a whole because of a single backend.

## Free quota and rate limits

| Backend | Cost | Rate limit |
| --- | --- | --- |
| TinyFish Search | Free, never draws from your balance | 30 requests/min · 500 requests/hour |
| TinyFish Fetch | Free, never draws from your balance | 150 URLs/min · 1,000 URLs/day |
| AnySearch (with key) | Free tier: 1,000 requests/day | 20 QPS |
| AnySearch (anonymous) | Shares the daily free quota | Rate-limited per client IP, lower than the above |

TinyFish Search and Fetch are free at any account balance and keep working at $0. AnySearch works without a key too, and a key raises it to the free tier. Figures come from the vendors' sites and may change; the official pages are authoritative.

## What it does

- **Search**: web search with language, region, date range, site allow/deny lists, and vertical-domain filters, plus control over how many pages each search may fetch.
- **Fetch**: turn a given URL into Markdown, HTML, or JSON, optionally returning the page's links and image links too.

## Installation

Add this repository with one command, then restart DSH: `dsh plugin --profile web add github:dgagf111/dsh-hydrasearch`

After the restart, open **Plugins page → Installed → `dsh-hydrasearch` → the row's configure entry**. On first use, enter a TinyFish key in the card; AnySearch can be left without one.

> To check it works, just use DSH's `web_search` / `web_fetch`: both should return normally, which means the request really went through the TinyFish / AnySearch chain rather than the built-in official search.

## Supported DSH versions

| DSH version | Status |
| --- | --- |
| **0.2.0-rc.2** | ✅ **Supported** — peerDependencies are `^0.2.0-rc.2`, `manifestVersion` is 1, `dsh.engines.dsh` is `>=0.2.0-rc.2`; verified on a local desktop build |
| 0.1.6-alpha.2 / 0.1.7-alpha.1 / 0.1.7-rc.1 / 0.1.x-rc.6 | ❌ No longer supported (dropped deliberately, not by omission) |

Why the older generations were dropped: DSH runs a compatibility gate over a plugin's `@deepseek-ai/dsh-*` peer ranges, and if any range is unsatisfied the **entire bundle is skipped** — it does not appear in the Installed list at all (not even as a greyed-out row) and the UI says nothing; the one trace is a stderr line at startup, `skipping profile bundle "dsh-hydrasearch": ... is incompatible with dsh 0.2.0-rc.2`. The old peers were `^0.1.0-rc.6`, which `0.2.0-rc.2` does not satisfy, so the whole package vanished; raising the peers to `^0.2.0-rc.2` in 0.4.0 is the fix.

### Upgrading from an older release

1. Update DSH to 0.2.0-rc.2.
2. Re-run the install command so the profile picks up 0.4.0: `dsh plugin --profile web add github:dgagf111/dsh-hydrasearch` (`dsh plugin` forwards its arguments to pnpm inside the profile and then re-reconciles the bundle list, so running it again is safe).
3. Restart DSH.

**Re-enter your API key once.** Since 0.3.0 the credential references are plugin-owned (`HYDRASEARCH_TINYFISH_API_KEY` / `HYDRASEARCH_ANYSEARCH_API_KEY`) — the old names collided with conventional environment variables, which made a stored key impossible to replace or clear. A key stored under the old reference is not read any more; enter it again in the card.

See [CHANGELOG.md](./CHANGELOG.md) for the full list of changes in this release, and [docs/](./docs/) for the mechanism-level notes.

## Configuration

Everything happens in the `dsh-hydrasearch` card on the Plugins page:

- **Backend order**: drag to reorder; the topmost backend is tried first.
- **Failover**: on by default; turn it off and only the first available backend is used, whose failure is final.
- **Backend parameters**: search endpoint, language, region, date range, site filters, page count, fetch format, timeout, cache policy and more — fill in what you need, leave the rest blank to omit them.

## API keys and privacy

- **The key lives only in the credential center on your own machine** (DSH's local credentials file). It is never uploaded, never synced, and never written to logs.
- The plugin places the key in the request header sent to **the search service you are calling**, and to nothing else. There is no other recipient, and the plugin itself contains no telemetry or usage reporting.
- Read, write, and clear all target that same store.

## License

MIT