deepseek-web-retrieval 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
-All notable changes to this project are documented here, with one sentence per item.
+All notable changes to this project are documented here, one sentence per item.
+
+## 0.7.0
+
+- Layer a shared config file (`$XDG_CONFIG_HOME/deepseek-web-retrieval/config.json`, camelCase keys) under the environment on every host, with the precedence `built-in defaults < shared file < DEEPSEEK_* environment < host-native config`; unknown and host-integration keys are warned about and ignored, and the API key stays out of the file.
+- Add a `config` command that prints every knob with its effective value and source (default, file, or environment — a count-derived `maxResults` is labeled `count`), replays shared-file problems, and verifies the key, config, and network end to end with `config --search "<query>"`.
+- Forward every `DEEPSEEK_*` option variable — not just the API key — in the Codex installer's `env_vars` entry, so shell-set knobs reach the stdio server without hand-editing `config.toml`.
+- Surface DeepSeek's `rerank_score`, `authority`, and `site_name` on search results in both text and structured output, accept an optional `original_question` on the MCP and Pi search tools (sent as `ori_question`), and add the `searchLocalization` deployment knob.
+- Couple `maxResults` to `count` when left unset — configuring only `count` was a silent no-op — and retry transient failures (408/425/429/5xx) twice by default instead of failing the billed call on the first attempt.
+- Resolve the shared config directory the Windows way on win32 (`%APPDATA%`, with an explicitly set `XDG_CONFIG_HOME` still winning), for the shared config file and the installer's global records alike.
+- Add `init --pin` to register the exact running CLI version (`deepseek-web-retrieval@<version>`) instead of the unpinned name, with package-identity comparisons that still match a pinned ref to its lineage.
+- `config` now warns and exits 1 when a `DEEPSEEK_*` variable is set but unusable (unknown name, non-numeric value, no-op switch value) instead of silently showing the default.
 
 ## 0.6.0
 

package/README.md

@@ -75,12 +75,12 @@ Tiers: search=preferred, fetch=preferred
 
 Files:
   ~/.codex/config.toml
-    set mcp_servers.deepseek = {"command":"npx","args":["-y","deepseek-web-retrieval"],"env_vars":["DEEPSEEK_API_KEY"]} (was (absent))
+    set mcp_servers.deepseek = {"command":"npx","args":["-y","deepseek-web-retrieval"],"env_vars":["DEEPSEEK_API_KEY","DEEPSEEK_... (was (absent))
   ~/.codex/AGENTS.md
     upsert marked rules block
 
 Notes:
-  - Codex stdio children do not inherit the parent environment, so the entry forwards DEEPSEEK_API_KEY explicitly via env_vars; the key must be set in the shell that launches Codex.
+  - Codex stdio children do not inherit the parent environment, so the entry forwards DEEPSEEK_API_KEY and every DEEPSEEK_* option variable explicitly via env_vars; shell-set knobs reach the server without hand-editing config.toml (the shared config file works without any forwarding).
   - Rules block upserted in ~/.codex/AGENTS.md; Codex reads ~/.codex/AGENTS.md plus every AGENTS.md from the project root to the cwd.
   - Shared config ownership is recorded in ~/.codex/.config.toml.deepseek-web-retrieval.codex.owner.json; uninstall releases it. Keep this local metadata with the config.
 
@@ -89,7 +89,10 @@ Plan only — re-run with --apply to write these changes.
 
 Repeat your chosen command with `--apply` to write the plan. The host guides explain
 activation steps and per-host tier limits. Pi defaults to the extension path; add
-`--path mcp` to use its MCP fallback.
+`--path mcp` to use its MCP fallback. Add `--pin` to register the exact version of the
+CLI you are running (`deepseek-web-retrieval@<version>`) instead of the unpinned name,
+so hosts keep resolving that release rather than every latest publish — reproducible
+setups trade away auto-updates; re-run `init --pin` from a newer CLI to move the pin.
 
 Other stdio MCP hosts may use the server, but the supported setup guides and installer
 currently cover the three hosts above. See the [integration model](docs/integration.md)
@@ -113,11 +116,17 @@ binary files, per-request billing) are documented there.
 - 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 — the default
-  returns exactly what DeepSeek ranked, including results without a score;
-  when a positive threshold is set, results below it (or without a score to
-  compare) are dropped.
+  returns exactly what DeepSeek ranked, including results without a score. A positive
+  `rerank_score` threshold drops results below it and results without a score; a positive
+  `authority` threshold drops known authorities below it, while results with an unknown
+  authority stay unless `allowUnknownAuthority` is set to false.
 - Builds `blockedDomains`, `includeDomains`, and `language` into query operators and
   rejects the final query locally when it exceeds the API's 128-character limit.
+- On the paths where this package defines the search tool's inputs (the MCP server and
+  the Pi extension), the tool accepts an optional `original_question` — the user's
+  question in their own words — forwarded as DeepSeek's `ori_question`, trimmed and
+  truncated to the API's 128 characters; a blank input on the Pi extension falls back
+  to the most recent user message in the session.
 - An empty result set is normal and is not an error.
 
 ### Fetch
@@ -134,10 +143,10 @@ binary files, per-request billing) are documented there.
 
 ### Timeouts and retries
 
-Request timeouts include reading the response body. Retries are disabled by default;
-when enabled, retryable responses are 408, 425, 429, and 5xx, and `Retry-After` is honored
-up to 10 seconds. Other failures, including 401, timeouts, and network errors, fail
-without retrying.
+Request timeouts include reading the response body. Transient failures are retried twice
+by default (0–5, `maxRetries`); retryable responses are 408, 425, 429, and 5xx, and
+`Retry-After` is honored up to 10 seconds. Other failures, including 401, timeouts, and
+network errors, fail without retrying.
 
 ### No automatic fallback
 
@@ -151,6 +160,66 @@ Queries and URLs are sent to `https://api.deepseek.com`; the API key is sent onl
 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.
 
+## Configuration
+
+Every knob resolves through one chain, low → high, identically on every host:
+`built-in defaults < shared config file < DEEPSEEK_* environment < host-native config`
+— a higher layer always wins, so nothing already configured loses effect.
+
+The shared file — `$XDG_CONFIG_HOME/deepseek-web-retrieval/config.json`, default
+`~/.config/deepseek-web-retrieval/config.json` on Linux and macOS and
+`%APPDATA%\deepseek-web-retrieval\config.json` on Windows (an explicitly set
+`XDG_CONFIG_HOME` still wins there) — works on every host and uses the
+camelCase option keys:
+
+```json
+{
+  "count": 20,
+  "blockedDomains": ["pinterest.com"],
+  "language": "zh",
+  "searchLocalization": "203.0.113.7"
+}
+```
+
+Unknown keys and host-integration keys are warned about on stderr and ignored. The
+API key does not go in the file — it keeps its existing channels (`DEEPSEEK_API_KEY`
+in the environment, or OpenCode's stored credential).
+
+Knobs fall into three classes; the shared file carries the first two:
+
+| Knob class | Shared file | Examples |
+| --- | --- | --- |
+| API behavior — the user↔DeepSeek relationship | yes — that is the point of the file | `count`, `blockedDomains`, `language`, `maxRetries` |
+| Host-sensitive — interacts with host output caps and deadlines | carries the safe defaults; a host layer is the recommended override point | `searchTimeoutMs`, `fetchTimeoutMs`, `fetchMaxChars`, `maxSummaryChars` |
+| Host integration — the host's tool landscape | rejected — warned about and ignored | `searchEnabled`, `setDefaultWebsearch`, `apiKeySource` |
+
+The same knob has two names — the camelCase key for the shared file and OpenCode's
+options, the `DEEPSEEK_*` variable for the environment:
+
+| Shared file / OpenCode options | Environment |
+| --- | --- |
+| `count` | `DEEPSEEK_SEARCH_COUNT` |
+| `blockedDomains` | `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` |
+| `language` | `DEEPSEEK_SEARCH_LANGUAGE` |
+| `searchLocalization` | `DEEPSEEK_SEARCH_LOCALIZATION` |
+| `fetchMaxChars` | `DEEPSEEK_FETCH_MAX_CHARS` |
+| `maxRetries` | `DEEPSEEK_MAX_RETRIES` |
+
+The full per-knob mapping is documented side by side in each guide's option table;
+per-host mechanics — how the environment reaches a stdio server, each host's output
+caps and deadlines — live there too: [Codex](docs/agents/codex.md),
+[Pi](docs/agents/pi.md), [OpenCode](docs/agents/opencode-v2.md). Keep
+host-independent intent in the shared file; prefer a host layer when a
+host-sensitive knob would cross its host's cap or deadline.
+
+To see what actually resolves, run `npx deepseek-web-retrieval config`: every knob
+printed with its value and its source (`default`, `file`, or `env`), plus any problems
+in the file or in `DEEPSEEK_*` variables (unknown names, unusable values) replayed as
+visible warnings — it exits 1 when there are problems, so it doubles as a dotfile CI
+check. `npx deepseek-web-retrieval config --search "<query>"`
+runs one billed search through the effective configuration to verify the key, config,
+and network end to end.
+
 ## Development
 
 ```bash