deepseek-web-retrieval 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project are documented here.
 
+## 0.4.0
+
+- Ground the search defaults in surveyed industry factory defaults
+  ([research](docs/research/search-api-defaults.md)): every surveyed AI-native search API
+  returns ten results by default and none filters results client-side by score or
+  authority, so `maxResults` moves 5 → 10 (matching the API `count` default) and the
+  `minRerank`/`minAuthority` thresholds move to 0 with `allowUnknownAuthority` flipping
+  to `true` — the pass-through default returns what DeepSeek ranked, and the thresholds
+  remain available as opt-ins. `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` becomes a
+  false-only switch (`false`/`0`/`no`/`off` disables) since the default is now on.
+  Unchanged and now evidence-backed: `maxRetries=0` (search-API SDK cohort: tavily-python
+  and Linkup ship no retries; the 2-retry defaults belong to chat-completion SDKs), the
+  30 s timeout, and the 1,200/16,000-character truncations
+- Drop the "Token- and cost-efficient" bullet from the README's Features section —
+  the default parameters are no longer endorsed as a selling point, and their behavior
+  is stated neutrally in General behavior
+
 ## 0.3.0
 
 - Close the lifecycle gaps in the keyless e2e coverage with a `reinit` scenario: tier

package/README.md

@@ -9,6 +9,24 @@ coding agents are in progress.
 
 This is an unofficial community project. It is not affiliated with OpenCode or DeepSeek.
 
+## Features
+
+- **One core, every host** — a native OpenCode v2 plugin plus a stdio MCP
+  server for everything else; identical retrieval behavior on each
+- **Tiered routing** — optional, preferred, forced, or off, per capability;
+  forced refuses when exclusivity is impossible
+- **Plan-then-apply installer** — every write previewed as old → new before
+  touching disk; arrays merge instead of replacing; uninstall reverses
+  exactly what was applied
+- **Trap-aware detection** — catches what the agents' own docs don't warn
+  about: Codex's silent `[tools] web_search` no-op, Pi's codemode hiding MCP
+  tools; conflicting rules and web-capable servers surface in the plan
+- **Git-safe installs** — the key never enters config files
+  (`${DEEPSEEK_API_KEY}` indirection or `env_vars`), so a project-scope
+  install commits clean
+- **Fails loudly, never falls back** — no silent provider switches;
+  localhost and private URLs blocked before they leave the machine
+
 ## Usage
 
 Shipped adapters:
@@ -31,28 +49,34 @@ For shared search, fetch, retry, and privacy behavior, see below.
 
 ## General behavior
 
+What this adapter layer adds on top of the
+[DeepSeek Search and Fetch APIs](https://api-docs.deepseek.com/guides/search) — the APIs'
+own capabilities (Markdown-only output, no JavaScript rendering, no private networks or
+binary files, per-request billing) are documented there.
+
 ### Search
 
-- Sends `need_content: false` and returns DeepSeek's `summary`, falling back to `snippet`.
-- Filters by `rerank_score` and `authority`, deduplicates URLs, and returns at most five
-  results by default.
-- The final query, including `blockedDomains`, `includeDomains`, and `language` operators,
-  must be 128 characters or fewer. Longer queries are rejected locally.
+- Requests summaries only (`need_content: false`, `summary` falling back to `snippet`);
+  full page content never enters the results.
+- Returns at most ten results by default (matching the API's `count` default and the
+  industry norm for AI-native search APIs), deduplicating URLs. Optional
+  `rerank_score` and `authority` thresholds are off by default; when enabled they
+  drop results below the configured score or tier.
+- Builds `blockedDomains`, `includeDomains`, and `language` into query operators and
+  rejects the final query locally when it exceeds the API's 128-character limit.
 - An empty result set is normal and is not an error.
 
 ### Fetch
 
-- DeepSeek Fetch returns Markdown only. `format: "text"` and `format: "html"` are rejected.
-- Output is capped at 16,000 characters by default, including the title. A
+- Output is capped at 16,000 characters by default, including the title; a
   `[content truncated]` marker is added when the limit leaves room for it.
-- If the page already starts with the same title as a top-level heading, no duplicate title
-  is added.
-- Responses larger than 5 MiB are rejected before parsing.
-- URLs must be absolute `http://` or `https://` URLs with a host, no embedded credentials,
-  and at most 8,192 characters.
-- The core supports allowed/blocked domain lists and private-host blocking. DeepSeek does
-  not render JavaScript and cannot reach private networks; PDFs, images, and other binary
-  files are unsupported.
+- A page that already opens with its title as a top-level heading does not get a
+  duplicate title.
+- Responses larger than 5 MiB are rejected before parsing; URLs must be absolute
+  `http://` or `https://`, credential-free, and at most 8,192 characters.
+- `format: "text"` and `format: "html"` are rejected rather than misrepresented.
+- Allowed/blocked domain lists and private-host blocking are enforced on the client,
+  before a request leaves the machine.
 
 ### Timeouts and retries
 
@@ -68,10 +92,9 @@ provider or fetch implementation.
 
 ### Privacy and cost
 
-Queries and URLs are sent to `https://api.deepseek.com`. The API key is sent only as a
-Bearer token to DeepSeek. Search and Fetch are billed per successful request; check current
-DeepSeek pricing and rate limits before enabling a team deployment. A 429 means you should
-wait, reduce concurrency, or increase retries.
+Queries and URLs are sent to `https://api.deepseek.com`; the API key is sent only as a
+Bearer token to DeepSeek and to nothing else. Retrieval is billed per successful request —
+see the official docs for pricing and rate limits before enabling a team deployment.
 
 ## Development
 

package/dist/cli.js

@@ -16,7 +16,7 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
 // src/core/constants.ts
-var SEARCH_ENDPOINT = "https://api.deepseek.com/v1/tools/search", FETCH_ENDPOINT = "https://api.deepseek.com/v1/tools/fetch", DEFAULT_SEARCH_COUNT = 10, DEFAULT_MAX_RESULTS = 5, DEFAULT_MIN_RERANK = 1.5, DEFAULT_MIN_AUTHORITY = 2, DEFAULT_MAX_SUMMARY_CHARS = 1200, DEFAULT_FETCH_MAX_CHARS = 16000, DEFAULT_TIMEOUT_MS = 30000, MIN_TIMEOUT_MS = 1000, MAX_TIMEOUT_MS = 120000, MAX_QUERY_CHARS = 128, MAX_URL_CHARS = 8192, MAX_ERROR_BODY_CHARS = 2000, MAX_RESPONSE_BYTES, FETCH_TRUNCATION_MARKER = `
+var SEARCH_ENDPOINT = "https://api.deepseek.com/v1/tools/search", FETCH_ENDPOINT = "https://api.deepseek.com/v1/tools/fetch", DEFAULT_SEARCH_COUNT = 10, DEFAULT_MAX_RESULTS = 10, DEFAULT_MIN_RERANK = 0, DEFAULT_MIN_AUTHORITY = 0, DEFAULT_MAX_SUMMARY_CHARS = 1200, DEFAULT_FETCH_MAX_CHARS = 16000, DEFAULT_TIMEOUT_MS = 30000, MIN_TIMEOUT_MS = 1000, MAX_TIMEOUT_MS = 120000, MAX_QUERY_CHARS = 128, MAX_URL_CHARS = 8192, MAX_ERROR_BODY_CHARS = 2000, MAX_RESPONSE_BYTES, FETCH_TRUNCATION_MARKER = `
 
 [content truncated]`, DEFAULT_API_KEY_SOURCE = "auto", DEFAULT_MAX_RETRIES = 0, MAX_RETRIES = 5, DEFAULT_RETRY_BASE_DELAY_MS = 250, MAX_RETRY_DELAY_MS = 1e4, API_KEY_ENV = "DEEPSEEK_API_KEY", ENABLE_SEARCH_ENV = "DEEPSEEK_ENABLE_SEARCH", ENABLE_FETCH_ENV = "DEEPSEEK_ENABLE_FETCH";
 var init_constants = __esm(() => {
@@ -4128,7 +4128,7 @@ function resolveSearchOptions(input) {
     maxResults: clampInt(input?.maxResults, DEFAULT_MAX_RESULTS, 0, 50),
     minRerank: finiteNumber(input?.minRerank, DEFAULT_MIN_RERANK),
     minAuthority: finiteNumber(input?.minAuthority, DEFAULT_MIN_AUTHORITY),
-    allowUnknownAuthority: input?.allowUnknownAuthority === true,
+    allowUnknownAuthority: input?.allowUnknownAuthority !== false,
     blockedDomains: normalizeDomains(input?.blockedDomains),
     includeDomains: normalizeDomains(input?.includeDomains),
     language: optionalText(input?.language),
@@ -4195,10 +4195,8 @@ var DOMAINS_ENV = {
   fetchAllowedDomains: "DEEPSEEK_FETCH_ALLOWED_DOMAINS",
   fetchBlockedDomains: "DEEPSEEK_FETCH_BLOCKED_DOMAINS"
 };
-var FLAG_ENV = {
-  allowUnknownAuthority: "DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY"
-};
 var FALSE_ONLY_ENV = {
+  allowUnknownAuthority: "DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY",
   fetchBlockPrivateHosts: "DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS",
   searchEnabled: ENABLE_SEARCH_ENV,
   fetchEnabled: ENABLE_FETCH_ENV
@@ -4212,7 +4210,7 @@ function pluginOptionsFromEnv(env) {
   putNumber(options, "maxResults", env);
   putNumber(options, "minRerank", env);
   putNumber(options, "minAuthority", env);
-  putBoolean(options, "allowUnknownAuthority", env);
+  putFalseOnly(options, "allowUnknownAuthority", env);
   putDomains(options, "blockedDomains", env);
   putDomains(options, "includeDomains", env);
   putText(options, "language", env);
@@ -4248,10 +4246,6 @@ function putText(target, key, env) {
   if (trimmed)
     target[key] = trimmed;
 }
-function putBoolean(target, key, env) {
-  if (isTrueValue(env[FLAG_ENV[key]]))
-    target[key] = true;
-}
 function putFalseOnly(target, key, env) {
   if (isFalseValue(env[FALSE_ONLY_ENV[key]]))
     target[key] = false;
@@ -4264,10 +4258,6 @@ function putDomains(target, key, env) {
   if (domains.length > 0)
     target[key] = domains;
 }
-function isTrueValue(value) {
-  const trimmed = value?.trim().toLowerCase();
-  return trimmed === "true" || trimmed === "1" || trimmed === "yes" || trimmed === "on";
-}
 function isFalseValue(value) {
   const trimmed = value?.trim().toLowerCase();
   return trimmed === "false" || trimmed === "0" || trimmed === "no" || trimmed === "off";
@@ -4725,7 +4715,7 @@ var SEARCH_QUERY_OPERATORS = "Use site:/-site: operators in the query to include
 var package_default = {
   $schema: "https://json.schemastore.org/package.json",
   name: "deepseek-web-retrieval",
-  version: "0.3.0",
+  version: "0.4.0",
   description: "Token-efficient DeepSeek Search and Fetch for coding agents, starting with OpenCode v2.",
   type: "module",
   license: "MIT",

package/docs/agents/codex.md

@@ -127,10 +127,10 @@ defaults and clamping match the other adapters. `DEEPSEEK_API_KEY` goes in `env_
 | --- | --- | --- |
 | `DEEPSEEK_ENABLE_SEARCH` | `true` | Register the search tool. Only an explicit `false`/`0`/`no`/`off` disables it; at least one tool must stay enabled. |
 | `DEEPSEEK_SEARCH_COUNT` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
-| `DEEPSEEK_SEARCH_MAX_RESULTS` | `5` | Results returned to the model after filtering, 0–50. `0` returns no results. |
-| `DEEPSEEK_SEARCH_MIN_RERANK` | `1.5` | Drop results below this relevance score. DeepSeek scores are 0–3. |
-| `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `2` | Drop known authorities below this tier. Authority is 0–4. |
-| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `false` | Keep results whose authority is missing or unknown. |
+| `DEEPSEEK_SEARCH_MAX_RESULTS` | `10` | Results returned to the model after filtering, 0–50. `0` returns no results. |
+| `DEEPSEEK_SEARCH_MIN_RERANK` | `0` | Drop results below this relevance score. DeepSeek scores are 0–3. |
+| `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `0` | Drop known authorities below this tier. Authority is 0–4. |
+| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `true` | Keep results whose authority is missing or unknown. Set `false`/`0` to drop them. |
 | `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` | unset | Comma-separated; adds `-site:` operators to the query. |
 | `DEEPSEEK_SEARCH_INCLUDE_DOMAINS` | unset | Comma-separated; restricts results with `site:` operators. |
 | `DEEPSEEK_SEARCH_LANGUAGE` | unset | Adds a `lang:` operator, for example `zh,en`. |

package/docs/agents/opencode-v2.md

@@ -100,7 +100,7 @@ A complete global config:
 Use the bare package name (optionally pinned) as the `package` value:
 
 ```jsonc
-"plugins": [{ "package": "deepseek-web-retrieval@0.3.0" }]
+"plugins": [{ "package": "deepseek-web-retrieval@0.4.0" }]
 ```
 
 **Global checkout**
@@ -173,10 +173,10 @@ Set these in the plugin's `options` object.
 | --- | --- | --- |
 | `searchEnabled` | `true` | Register the DeepSeek search provider at all. Only an explicit `false` disables it. |
 | `count` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
-| `maxResults` | `5` | Results returned to the model after filtering, 0–50. `0` returns no results. |
-| `minRerank` | `1.5` | Drop results below this relevance score. DeepSeek scores are 0–3. |
-| `minAuthority` | `2` | Drop known authorities below this tier. Authority is 0–4. |
-| `allowUnknownAuthority` | `false` | Keep results whose authority is missing or unknown. |
+| `maxResults` | `10` | Results returned to the model after filtering, 0–50. `0` returns no results. |
+| `minRerank` | `0` | Drop results below this relevance score. DeepSeek scores are 0–3. |
+| `minAuthority` | `0` | Drop known authorities below this tier. Authority is 0–4. |
+| `allowUnknownAuthority` | `true` | Keep results whose authority is missing or unknown. Only an explicit `false` disables it. |
 | `blockedDomains` | `[]` | Add `-site:` operators to the search query. |
 | `includeDomains` | `[]` | Restrict results with `site:` operators. |
 | `language` | unset | Add a `lang:` operator, for example `zh,en`. |

package/docs/agents/pi.md

@@ -132,10 +132,10 @@ defaults and clamping match the OpenCode adapter.
 | --- | --- | --- |
 | `DEEPSEEK_ENABLE_SEARCH` | `true` | Register the search tool. Only an explicit `false`/`0`/`no`/`off` disables it; at least one tool must stay enabled. |
 | `DEEPSEEK_SEARCH_COUNT` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
-| `DEEPSEEK_SEARCH_MAX_RESULTS` | `5` | Results returned to the model after filtering, 0–50. `0` returns no results. |
-| `DEEPSEEK_SEARCH_MIN_RERANK` | `1.5` | Drop results below this relevance score. DeepSeek scores are 0–3. |
-| `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `2` | Drop known authorities below this tier. Authority is 0–4. |
-| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `false` | Keep results whose authority is missing or unknown. Set `true`/`1`. |
+| `DEEPSEEK_SEARCH_MAX_RESULTS` | `10` | Results returned to the model after filtering, 0–50. `0` returns no results. |
+| `DEEPSEEK_SEARCH_MIN_RERANK` | `0` | Drop results below this relevance score. DeepSeek scores are 0–3. |
+| `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `0` | Drop known authorities below this tier. Authority is 0–4. |
+| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `true` | Keep results whose authority is missing or unknown. Set `false`/`0` to drop them. |
 | `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` | unset | Comma-separated; adds `-site:` operators to the query. |
 | `DEEPSEEK_SEARCH_INCLUDE_DOMAINS` | unset | Comma-separated; restricts results with `site:` operators. |
 | `DEEPSEEK_SEARCH_LANGUAGE` | unset | Adds a `lang:` operator, for example `zh,en`. |

package/docs/research/search-api-defaults.md

@@ -0,0 +1,309 @@
+# Search and fetch API defaults across vendors
+
+This note answers one question: what are the **factory defaults** — the values applied when a
+caller passes nothing — of the mature AI-native web-search and web-fetch APIs? It exists
+because this repo layers its own client-side defaults on top of the DeepSeek Search/Fetch API,
+and the original values (`maxResults=5` on an API `count` of 10, `minRerank=1.5`,
+`minAuthority=2`, `allowUnknownAuthority=false`, `maxRetries=0`, `timeout=30s`, fetch
+truncation at 16,000 characters, summary truncation at 1,200, response-body cap 5 MiB) were
+challenged as arbitrary. The pages below are the benchmark against which the repo's defaults
+are grounded; based on this survey the search-side defaults were changed on 2026-10-21 to
+`maxResults=10`, `minRerank=0`, `minAuthority=0`, `allowUnknownAuthority=true` (filters stay
+available as opt-ins). It records facts only; the closing section lines the repo's values up
+against them without recommending changes.
+
+**Research baseline:** 2026-10-21. Claims are cited to primary sources only: official vendor
+documentation and official SDK source (GitHub repos and published npm/PyPI packages). Secondhand
+blogs and tutorials are excluded. "Default" means the value in force when the parameter is
+omitted — not the allowed range, and not an example value. Where no default is published, that
+is stated as such rather than guessed.
+
+The five questions asked of every product:
+
+1. Search-result count default (the analogue of this repo's `maxResults`/API `count`).
+2. Any **client-side relevance/authority filtering** default (the analogue of
+   `minRerank`/`minAuthority`/`allowUnknownAuthority`) — in particular, does anyone drop
+   results by authority in the client?
+3. HTTP retry default at the SDK layer.
+4. Request timeout default (SDK and API layer).
+5. Fetched-content truncation default (character limits, byte caps).
+
+## Tavily
+
+API defaults from the official OpenAPI reference for `POST /search`
+([docs](https://docs.tavily.com/documentation/api-reference/endpoint/search)):
+
+| Parameter | Default when omitted | Source |
+| --- | --- | --- |
+| `max_results` | **10** (min 0, max 20) | [API reference](https://docs.tavily.com/documentation/api-reference/endpoint/search) |
+| `search_depth` | **`basic`** (vs `advanced`/`fast`/`ultra-fast`) | same |
+| `chunks_per_source` | **3** (chunks of ~500 chars `basic`/`fast`, ~800 `advanced`) | same |
+| `topic` | **`general`** | same |
+| `include_answer` / `include_raw_content` / `include_images` | **false** | same |
+| `auto_parameters` | **false** | same |
+| `include_domains` / `exclude_domains` | **empty** | same |
+| `include_domains_mode` | **`restrict`** ("`include_domains` acts as a hard filter unless set to `prefer`") | same |
+
+No relevance score, authority tier, or any other per-result quality signal is returned or
+filterable in the client — ranking is server-side and opaque.
+
+SDK layer ([tavily-python, master](https://github.com/tavily-ai/tavily-python/blob/master/tavily/tavily.py)):
+`max_results` and `search_depth` default to `None` (so the API defaults above apply); `search`
+has `timeout: float = 60` clamped to `min(timeout, 120)` seconds; `extract` defaults to 30 s and
+`crawl` to 150 s. The client posts through a plain `requests.Session` with no retry adapter —
+the only retry-related code parses a `retry_after_seconds` field out of error payloads.
+
+## Exa
+
+API defaults from the official OpenAPI spec
+([reference](https://exa.ai/docs/reference/search)):
+
+| Parameter | Default when omitted | Source |
+| --- | --- | --- |
+| `numResults` | **10** (max 100) | [reference](https://exa.ai/docs/reference/search); the [search quickstart](https://exa.ai/docs/search/quickstart) states it in prose: "Search returns up to 10 results by default" |
+| `type` | **`auto`** | [reference](https://exa.ai/docs/reference/search) |
+| `contents.text` (boolean form) | **false** — "If true, returns full page text with default settings. If false, disables text return." | same |
+| `contents.text.verbosity` | **`compact`** | same |
+| `contents.highlights` (boolean form) | **false** | same |
+| `moderation` | **false** | same |
+| `contents.livecrawlTimeout` | **10000 ms** | same |
+| `contents.text.maxCharacters` | **no published default** (max 1,000,000); the [contents quickstart](https://exa.ai/docs/contents/quickstart) frames it as opt-in: "Full pages can be large, so use `maxCharacters` when you need a limit" | both |
+
+Like Tavily, Exa exposes no per-result authority/score field and no client filter for one;
+`moderation` (off by default) is content-moderation, not authority.
+
+## Perplexity
+
+The Sonar chat-completions API was retired on 2026-09-27; the live products are the Search API
+and the Agent API ([migration guide](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar/overview)).
+
+Search API (`POST /search`,
+[reference](https://docs.perplexity.ai/api-reference/search-post); the
+[quickstart](https://docs.perplexity.ai/docs/search/quickstart) restates it):
+
+| Parameter | Default when omitted | Source |
+| --- | --- | --- |
+| `max_results` | **10** (1–20) | [quickstart](https://docs.perplexity.ai/docs/search/quickstart): "`max_results` accepts values from 1 to 20 and defaults to 10" |
+| `search_type` | **`web`** | [reference](https://docs.perplexity.ai/api-reference/search-post) |
+
+Agent API `web_search` tool ([tool guide](https://docs.perplexity.ai/docs/agent-api/tools/web-search),
+[schema](https://docs.perplexity.ai/api-reference/agent-post)): `max_results` accepts 1–50 and
+`max_tokens`/`max_tokens_per_page` cap search context, but none of the three publishes a numeric
+default — "When omitted, the default budget applies" is all the docs say. The one published
+tool-count default in the same schema is `image_search.max_results`: **5** (1–30)
+([reference](https://docs.perplexity.ai/api-reference/agent-post)). The retired Sonar
+`web_search_options.search_context_size` has no named-size successor; the
+[migration table](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar/how-to) maps it
+to the token budgets above, and the current docs no longer state its old default. No
+authority/score filtering exists on any of these surfaces.
+
+## Firecrawl
+
+API defaults from the official OpenAPI references
+([search](https://docs.firecrawl.dev/api-reference/endpoint/search),
+[scrape](https://docs.firecrawl.dev/api-reference/endpoint/scrape)):
+
+| Parameter | Default when omitted | Source |
+| --- | --- | --- |
+| search `limit` | **10** (1–100; per source type when multiple `sources`) | [search reference](https://docs.firecrawl.dev/api-reference/endpoint/search) |
+| search `sources` | **`["web"]`** | same |
+| search `timeout` | **60000 ms** | same |
+| search `highlights` | **true** | same |
+| scrape `timeout` | **60000 ms** (min 1 s, max 300 s) | [scrape reference](https://docs.firecrawl.dev/api-reference/endpoint/scrape) |
+| scrape `onlyMainContent` | **true** | same |
+| scrape `maxAge` (cache freshness window) | **172800000 ms (2 days)** | same |
+
+No character or byte truncation default is published for scraped content. No authority/score
+filter exists.
+
+SDK layer (`@mendable/firecrawl-js` 4.50.0, npm tarball with registry provenance;
+[source](https://www.npmjs.com/package/@mendable/firecrawl-js)): `maxRetries` defaults to
+**3** (`options.maxRetries ?? 3`), retrying **only HTTP 502** with exponential backoff
+(`backoffFactor` 0.5 s × 2^attempt); `timeoutMs` defaults to **300000 ms (5 min)**.
+
+## Jina Reader (r.jina.ai / s.jina.ai)
+
+Official product page ([jina.ai/reader](https://jina.ai/reader/)) and official repo
+([jina-ai/reader](https://github.com/jina-ai/reader)):
+
+| Behavior | Default | Source |
+| --- | --- | --- |
+| Search-mode result count (`s.jina.ai`) | **fixed 5** — "Reader searches the web, fetches the top 5 results, visits each URL, and applies `r.jina.ai` to it"; no count parameter is exposed | [repo README](https://github.com/jina-ai/reader/blob/main/README.md); the [product page](https://jina.ai/reader/) likewise: "it returns a list of five entries" |
+| `x-timeout` | **no default set** — optional header, integer seconds, max 180; when absent the option stays `null` (no client-side deadline) | [README](https://github.com/jina-ai/reader/blob/main/README.md) and [`crawler-options.ts`](https://github.com/jina-ai/reader/blob/main/src/dto/crawler-options.ts) (`instance.timeout ??= null`) |
+| `x-token-budget` | **no default** (parsed only when sent) | [`crawler-options.ts`](https://github.com/jina-ai/reader/blob/main/src/dto/crawler-options.ts) |
+| Content truncation | none published | — |
+
+No relevance/authority filter; no retry logic documented.
+
+## Anthropic web_search / web_fetch server tools
+
+Current docs live at
+[web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool),
+[web fetch tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool),
+and the [server tools guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools).
+
+| Parameter | Default when omitted | Source |
+| --- | --- | --- |
+| `web_search.max_uses` | optional; no numeric default published ("limits the number of searches performed"; guidance: "Simple factual queries typically use 1–3 searches") | [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) |
+| `web_fetch.max_uses` | optional; **"There is currently no default limit."** | [web fetch tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool) |
+| `web_fetch.max_content_tokens` | optional token cap; **no default value published** (doc example: 100000) — "If the fetched content exceeds this limit, the tool truncates it … applies to text content, not to binary content such as PDFs" | [web fetch tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool) |
+| `web_fetch` URL length | hard max **250 characters** | same (error `url_too_long`) |
+| `web_fetch` content types | text, HTML, PDF only; `robots.txt` and private addresses respected server-side | same |
+| `web_fetch.use_cache` | **true** | same |
+| `web_fetch.citations` | **disabled by default** | same |
+| `response_inclusion` (both tools) | **`"full"`** | both |
+| Result count / authority filter | **neither exists** — the model decides how many searches to run; no score or authority field is returned | both |
+
+A widely repeated pair of numbers — "truncate to 20,000 characters" and "5 MiB" — is **not in
+the current official docs** (checked 2026-10-21), nor in the November 2025 snapshot of the same
+page on the Internet Archive; the published truncation mechanism is the token-based
+`max_content_tokens` parameter above, with no published default.
+
+SDK layer (official repos, default branch):
+
+| SDK | Default timeout | Default max retries | Source |
+| --- | --- | --- | --- |
+| anthropic-sdk-typescript | **10 minutes** (`options.timeout ?? BaseAnthropic.DEFAULT_TIMEOUT`) | **2** (`options.maxRetries ?? 2`) | [`client.ts`](https://github.com/anthropics/anthropic-sdk-typescript/blob/main/src/client.ts) |
+| anthropic-sdk-python | **600 s total, 5 s connect** (`httpx.Timeout(timeout=10 * 60, connect=5.0)`) | **2** (`DEFAULT_MAX_RETRIES = 2`) | [`_constants.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_constants.py) |
+
+## OpenAI Responses web_search
+
+From the official guide
+([Web search tool](https://platform.openai.com/docs/guides/tools-web-search)):
+
+| Parameter | Default when omitted | Source |
+| --- | --- | --- |
+| Result count | **not exposed** — no count parameter; the docs note the size setting "does not set an exact token count or guarantee a specific number of sources or citations" | [guide](https://platform.openai.com/docs/guides/tools-web-search) |
+| `search_context_size` | **`medium`** — "Use `low` for simple lookups, `medium` for a balanced default, and `high` …" | [guide](https://platform.openai.com/docs/guides/tools-web-search) |
+| `external_web_access` | **true** (live access) | [guide](https://platform.openai.com/docs/guides/tools-web-search) |
+| `return_token_budget` | **`default`** — "Uses the standard returned-token budget … the same behavior as omitting `return_token_budget`" (numeric value unpublished) | [guide](https://platform.openai.com/docs/guides/tools-web-search) |
+
+No relevance/authority score or filter is exposed on any web-search surface.
+
+SDK layer (official repos, default branch):
+
+| SDK | Default timeout | Default max retries | Source |
+| --- | --- | --- | --- |
+| openai-node | **600000 ms (10 min)** (`OpenAI.DEFAULT_TIMEOUT = 600000`) | **2** (`@param {number} [opts.maxRetries=2]`) | [`client.ts`](https://github.com/openai/openai-node/blob/master/src/client.ts) |
+| openai-python | **600 s total, 5 s connect** (`httpx.Timeout(timeout=600, connect=5.0)`) | **2** (`DEFAULT_MAX_RETRIES = 2`); initial retry delay 0.5 s, max 8 s | [`_constants.py`](https://github.com/openai/openai-python/blob/main/src/openai/_constants.py) |
+
+## Brave Search API
+
+From the official Web Search API query documentation
+([docs](https://api-dashboard.search.brave.com/app/documentation/web-search/query)):
+
+| Parameter | Default when omitted | Source |
+| --- | --- | --- |
+| `count` | **20** — "Maximum number of results per page (max 20, default 20). The actual number of results returned may be less than count." | [docs](https://api-dashboard.search.brave.com/app/documentation/web-search/query) |
+| `offset` | 0 (0-based, max 9) | same |
+
+No relevance/authority filter beyond `safesearch`-style content controls; ranking is
+server-side.
+
+## Linkup
+
+From the official OpenAPI reference
+([search reference](https://docs.linkup.so/pages/documentation/endpoints/search/reference))
+and the official Python SDK source
+([linkup-python-sdk](https://github.com/LinkupPlatform/linkup-python-sdk/blob/main/src/linkup/_client.py)):
+
+| Parameter | Default when omitted | Source |
+| --- | --- | --- |
+| `depth` | **no published default** — enum `flash`/`fast`/`standard`/`deep`; the spec's prose calls `fast` "the recommended default for most agentic applications" without declaring an omission default. The SDK makes `depth` a required argument | [reference](https://docs.linkup.so/pages/documentation/endpoints/search/reference), [`_client.py`](https://github.com/LinkupPlatform/linkup-python-sdk/blob/main/src/linkup/_client.py) |
+| `maxResults` | **no published default** (min 1; schema example: 5) | [reference](https://docs.linkup.so/pages/documentation/endpoints/search/reference) |
+| `includeImages` / `includeInlineCitations` / `includeSources` | **false** | same |
+| SDK `timeout` | **None — "the request will have no timeout"** | [`_client.py`](https://github.com/LinkupPlatform/linkup-python-sdk/blob/main/src/linkup/_client.py) |
+
+The SDK has no retry loop for transient failures (its one retry path is the x402 payment
+handshake). No relevance/authority filter exists.
+
+## You.com
+
+The API documentation is still public at
+[you.com/docs](https://you.com/docs/api-reference/search/v1-search). Defaults for
+`POST /v1/search` ([reference](https://you.com/docs/api-reference/search/v1-search)):
+
+| Parameter | Default when omitted | Source |
+| --- | --- | --- |
+| `count` | **10** — per section (`web` and `news`) | [reference](https://you.com/docs/api-reference/search/v1-search) |
+| `safesearch` | **`moderate`** | same |
+| `crawl_timeout` | **10 s** (1–60) | same |
+| `livecrawl_formats` (deprecated) | **`["html"]`** | same |
+| `extraction.highlights.total_max_tokens` | **8192 tokens** (range 1024–8192; "Omit it to get the default budget of 8192") | same |
+| `extraction.full_page.extraction_formats` | **`["markdown"]`** | same |
+| Result content | **snippets by default**; highlights/full-page are opt-in via `extraction` | same |
+
+`moderate` safesearch is a content-moderation filter, not an authority filter; no
+relevance/authority score is exposed.
+
+## What DeepSeek itself claims
+
+The challenge quote attributed to the DeepSeek docs — an "AI 原生的通用搜索引擎" that
+"通过严格的识别机制进行过滤，确保向用户与 LLM 呈现权威可信的信息" — is **not present** on
+<https://api-docs.deepseek.com/guides/search> (checked 2026-10-21, English and 中文 pages).
+The closest positioning sentences actually on the page:
+
+- EN: "It is powered by DeepSeek's in-house search engine."
+  ([guide](https://api-docs.deepseek.com/guides/search))
+- ZH: "该接口由 DeepSeek 自研搜索引擎提供支持。"
+  ([指南](https://api-docs.deepseek.com/zh-cn/guides/search))
+
+So the official docs claim an in-house engine but make **no published claim of server-side
+quality filtering**. What they do publish, verbatim
+([指南](https://api-docs.deepseek.com/zh-cn/guides/search)):
+
+- `rerank_score`: "排序分数，0～3 分，综合考虑相关性、权威性、时效性等维度，**大于等于 1.5 分为优质结果**。"
+- `authority`: "网页权威性，0～4（**-1 表示未知**），**大于等于 3 为极权威结果**。"
+- Request defaults: `count` "否 / 默认值 10 / 返回条数，1～50"; `need_content` "否 / false";
+  `localization` "否 / 空"; `ori_question` optional.
+- Response sizing: `snippet` "短摘要 … 通常为 100～200 字符"; `summary` "长摘要 … 通常为 600～800 字符".
+
+## What this means for this repo's defaults
+
+Fact-by-fact alignment of the repo's client-side defaults
+(`src/core/constants.ts`) against the surveyed factory defaults. No recommendation is made
+here; the table only lines up what the industry ships.
+
+| Repo default | Industry factory defaults observed above |
+| --- | --- |
+| API `count=10`, client `maxResults=10` (post-dedup cap; `5` before 2026-10-21) | API-level count defaults: Tavily 10, Exa 10, Perplexity Search API 10, Firecrawl 10, You.com 10 (per section), Brave 20. Post-filter caps are uncommon; a fixed 5 exists at Jina (`s.jina.ai` top 5, not configurable) and Perplexity's `image_search` tool (default 5). Linkup's schema example is 5 but no default is published. OpenAI and Anthropic expose no count at all |
+| `minRerank=0`, `minAuthority=0`, `allowUnknownAuthority=true` — no client-side filtering (previously `1.5`/`2`/`false`) | **No surveyed product filters search results client-side by relevance score or authority.** The only published thresholds for DeepSeek's own fields are the docs' quality labels (≥1.5 "优质", ≥3 "极权威") — labels, not filters. The closest shipped analogues are domain allow/block lists (Tavily, Exa, Perplexity, You.com, Anthropic, Brave) and You.com's `safesearch: moderate` default, which is content moderation, not authority |
+| `maxRetries=0` | Official model-API SDKs: OpenAI 2, Anthropic 2 (both languages). Search-API SDKs: firecrawl-js 3 (502 only), tavily-python 0, Linkup SDK 0 |
+| `timeout=30s` (search and fetch, 1–120 s range, covers body read) | Search/scrape API timeouts: Firecrawl 60 s (scrape max 300 s), Tavily SDK search 60 s (cap 120 s) / extract 30 s, You.com `crawl_timeout` 10 s, Linkup SDK no timeout, Jina `x-timeout` unset by default (max 180 s). Model-API SDKs: OpenAI and Anthropic 10 minutes |
+| Fetch truncation 16,000 chars | Exa: page text **off** by default (`contents.text: false`), opt-in `maxCharacters` with no published default; DeepSeek itself: `need_content: false` by default; Anthropic `web_fetch`: token-based `max_content_tokens`, no published default (example 100000), no char/MiB figure in current docs; You.com highlights budget 8192 tokens; Firecrawl and Jina publish no truncation default |
+| Summary truncation 1,200 chars | DeepSeek's own field doc says `summary` is "通常为 600～800 字符"; no surveyed vendor ships a client-side summary cap (they return snippets/highlights sized server-side: Exa verbosity `compact`, You.com highlights budget) |
+| Response body cap 5 MiB | No surveyed product publishes a response-body byte cap; the only published byte-adjacent limits are Anthropic's URL length (250 chars) and content-type whitelist, and Exa's `maxCharacters` ceiling of 1,000,000 characters |
+| Filter markers (`minRerank`/`minAuthority` matching) | Nothing to compare: no surveyed vendor returns a per-result authority tier at all — DeepSeek's `rerank_score`/`authority` response fields are the outlier, which is what makes client-side thresholds possible here and nowhere else in this survey |
+
+## Sources
+
+- DeepSeek: [Search & Fetch guide (EN)](https://api-docs.deepseek.com/guides/search) ·
+  [网页搜索与抓取 (ZH)](https://api-docs.deepseek.com/zh-cn/guides/search)
+- Tavily: [search API reference](https://docs.tavily.com/documentation/api-reference/endpoint/search) ·
+  [tavily-python source](https://github.com/tavily-ai/tavily-python/blob/master/tavily/tavily.py)
+- Exa: [search reference (OpenAPI)](https://exa.ai/docs/reference/search) ·
+  [search quickstart](https://exa.ai/docs/search/quickstart) ·
+  [contents quickstart](https://exa.ai/docs/contents/quickstart)
+- Perplexity: [Search API quickstart](https://docs.perplexity.ai/docs/search/quickstart) ·
+  [Search API reference](https://docs.perplexity.ai/api-reference/search-post) ·
+  [Agent API web_search tool](https://docs.perplexity.ai/docs/agent-api/tools/web-search) ·
+  [Agent API schema](https://docs.perplexity.ai/api-reference/agent-post) ·
+  [Sonar migration guide](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar/how-to)
+- Firecrawl: [search reference](https://docs.firecrawl.dev/api-reference/endpoint/search) ·
+  [scrape reference](https://docs.firecrawl.dev/api-reference/endpoint/scrape) ·
+  [npm @mendable/firecrawl-js](https://www.npmjs.com/package/@mendable/firecrawl-js)
+- Jina: [reader product page](https://jina.ai/reader/) ·
+  [jina-ai/reader README](https://github.com/jina-ai/reader/blob/main/README.md) ·
+  [crawler-options.ts](https://github.com/jina-ai/reader/blob/main/src/dto/crawler-options.ts)
+- Anthropic: [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) ·
+  [web fetch tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool) ·
+  [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools) ·
+  [anthropic-sdk-typescript client.ts](https://github.com/anthropics/anthropic-sdk-typescript/blob/main/src/client.ts) ·
+  [anthropic-sdk-python _constants.py](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_constants.py)
+- OpenAI: [web search tool guide](https://platform.openai.com/docs/guides/tools-web-search) ·
+  [openai-node client.ts](https://github.com/openai/openai-node/blob/master/src/client.ts) ·
+  [openai-python _constants.py](https://github.com/openai/openai-python/blob/main/src/openai/_constants.py)
+- Brave: [Web Search API query docs](https://api-dashboard.search.brave.com/app/documentation/web-search/query)
+- Linkup: [search reference (OpenAPI)](https://docs.linkup.so/pages/documentation/endpoints/search/reference) ·
+  [linkup-python-sdk _client.py](https://github.com/LinkupPlatform/linkup-python-sdk/blob/main/src/linkup/_client.py)
+- You.com: [POST /v1/search reference](https://you.com/docs/api-reference/search/v1-search)

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "deepseek-web-retrieval",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Token-efficient DeepSeek Search and Fetch for coding agents, starting with OpenCode v2.",
   "type": "module",
   "license": "MIT",

package/src/core/constants.ts

@@ -1,10 +1,16 @@
 export const SEARCH_ENDPOINT = "https://api.deepseek.com/v1/tools/search"
 export const FETCH_ENDPOINT = "https://api.deepseek.com/v1/tools/fetch"
 
+/**
+ * Search defaults are benchmarked against surveyed AI-native search APIs and
+ * DeepSeek's own factory defaults; see docs/research/search-api-defaults.md.
+ * Result caps cluster at 10 across vendors, and no surveyed vendor filters
+ * results client-side by score or authority — thresholds stay opt-in.
+ */
 export const DEFAULT_SEARCH_COUNT = 10
-export const DEFAULT_MAX_RESULTS = 5
-export const DEFAULT_MIN_RERANK = 1.5
-export const DEFAULT_MIN_AUTHORITY = 2
+export const DEFAULT_MAX_RESULTS = 10
+export const DEFAULT_MIN_RERANK = 0
+export const DEFAULT_MIN_AUTHORITY = 0
 export const DEFAULT_MAX_SUMMARY_CHARS = 1200
 
 export const DEFAULT_FETCH_MAX_CHARS = 16000

package/src/core/options.ts

@@ -40,7 +40,7 @@ export function resolveSearchOptions(input?: PluginOptions): SearchOptions {
     maxResults: clampInt(input?.maxResults, DEFAULT_MAX_RESULTS, 0, 50),
     minRerank: finiteNumber(input?.minRerank, DEFAULT_MIN_RERANK),
     minAuthority: finiteNumber(input?.minAuthority, DEFAULT_MIN_AUTHORITY),
-    allowUnknownAuthority: input?.allowUnknownAuthority === true,
+    allowUnknownAuthority: input?.allowUnknownAuthority !== false,
     blockedDomains: normalizeDomains(input?.blockedDomains),
     includeDomains: normalizeDomains(input?.includeDomains),
     language: optionalText(input?.language),

package/src/mcp/config.ts

@@ -30,12 +30,9 @@ const DOMAINS_ENV = {
   fetchBlockedDomains: "DEEPSEEK_FETCH_BLOCKED_DOMAINS",
 } as const
 
-const FLAG_ENV = {
-  allowUnknownAuthority: "DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY",
-} as const
-
 /** Shared defaults are true; only an explicit false value disables them. */
 const FALSE_ONLY_ENV = {
+  allowUnknownAuthority: "DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY",
   fetchBlockPrivateHosts: "DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS",
   searchEnabled: ENABLE_SEARCH_ENV,
   fetchEnabled: ENABLE_FETCH_ENV,
@@ -58,7 +55,7 @@ export function pluginOptionsFromEnv(env: Env): PluginOptions {
   putNumber(options, "maxResults", env)
   putNumber(options, "minRerank", env)
   putNumber(options, "minAuthority", env)
-  putBoolean(options, "allowUnknownAuthority", env)
+  putFalseOnly(options, "allowUnknownAuthority", env)
   putDomains(options, "blockedDomains", env)
   putDomains(options, "includeDomains", env)
   putText(options, "language", env)
@@ -95,10 +92,6 @@ function putText(target: Record<string, unknown>, key: keyof typeof TEXT_ENV, en
   if (trimmed) target[key] = trimmed
 }
 
-function putBoolean(target: Record<string, unknown>, key: keyof typeof FLAG_ENV, env: Env): void {
-  if (isTrueValue(env[FLAG_ENV[key]])) target[key] = true
-}
-
 function putFalseOnly(target: Record<string, unknown>, key: keyof typeof FALSE_ONLY_ENV, env: Env): void {
   if (isFalseValue(env[FALSE_ONLY_ENV[key]])) target[key] = false
 }
@@ -113,11 +106,6 @@ function putDomains(target: Record<string, unknown>, key: keyof typeof DOMAINS_E
   if (domains.length > 0) target[key] = domains
 }
 
-function isTrueValue(value: string | undefined): boolean {
-  const trimmed = value?.trim().toLowerCase()
-  return trimmed === "true" || trimmed === "1" || trimmed === "yes" || trimmed === "on"
-}
-
 function isFalseValue(value: string | undefined): boolean {
   const trimmed = value?.trim().toLowerCase()
   return trimmed === "false" || trimmed === "0" || trimmed === "no" || trimmed === "off"