dsh-web-search-custom
English | 简体中文
Point the DeepSeek Harness (dsh)
web profile at any JSON search API — give it a URL and (optionally) an API
key, and it replaces the built-in DeepSeek search. It ships pointed at the
AnySearch unified search API, and
the keyless path needs no account at all:
POST https://api.anysearch.com/v1/search # apiKey empty -> anonymous tier, no Authorization header
POST https://api.anysearch.com/v1/search # apiKey set -> Authorization: Bearer <key>, that key's quota
[!IMPORTANT]
Design intent. The plugin is a thin adapter, nothing more: it owns one
search provider behind the ctx.web capability seam and one settings card.
It ships no search engine, no index and no cache; the only credential it ever
sends is the one you type into the card (or export as an environment variable),
and an empty key means no auth header at all. Uninstall it and the stock
provider is back with zero residue.
Table of Contents
Why
dsh's web profile resolves search through the ctx.web seam. Out of the box
that seam is served by a hosted search backend, which is the wrong trade for
anyone who runs their own search stack (SearXNG, an internal search gateway, a
vendor API), wants queries to stay inside their own network, or wants to bring
their own search key.
This plugin registers one additional provider into that seam and lets you select
it. Everything else — the web_search tool, result capping, cancellation, error
propagation — keeps working unchanged, because it is the same seam the stock
provider uses.
Features
- Standard dsh bundle plugin. Zero intrusion: no dsh source is modified;
removing the plugin restores the stock search provider.
- Zero runtime dependencies. Only dsh-shipped packages are used
(
@deepseek-ai/dsh-settings, @deepseek-ai/schemastery, plus React on the
browser side). Nothing is vendored or bundled.
- AnySearch by default, keyless out of the box.
api: auto detects the
AnySearch host and speaks its native POST envelope. Leave apiKey empty and the
request carries no Authorization header (anonymous, per-IP rate-limited
free tier); set a key and it is sent as Authorization: Bearer <key> against
that key's quota. An invalid key becomes a clear error instead of a silent
fallback to anonymous.
- SearXNG and friends still work. Switch
api to generic for templated
GET/POST endpoints; the shipped mapping matches SearXNG's results[] / url /
title / content / publishedDate shape.
- In-settings configuration card (Settings → Plugins): profile, URL, API key,
result cap, timeout and the whole field mapping are editable in the page, with
the same overridden/reset affordances as first-party plugin cards.
How it works
web_search tool
│
▼
ctx.web (capability seam) ──selection──▶ provider id "custom"
│ │
│ ▼
│ fetch(your endpoint) ──▶ your JSON API
│ │
└◀──── WebSearchResult { sources[], truncated } ◀──┘
The host side registers the namespace web-search-custom (so the settings page
can render a card for it) and registers a search provider with the stable id
custom. The provider's search(query, signal) reads the live settings value on
every call, picks a profile, performs the HTTP request with the caller's
cancellation signal plus its own timeout, and maps the JSON payload into
sources[] (deduplicated by URL, non-http(s) entries dropped, HTML stripped,
entities decoded).
api | Request | Response mapping | Fields that apply |
|---|
anysearch (auto-detected) | POST {"query","max_results"}; Authorization: Bearer only when a key is set | data.results[].{title,url,snippet}, falling back to content | url, apiKey, headers, timeoutMs, maxResults |
generic | templated GET/POST ({query} URL-encoded, {queryRaw} verbatim, {apiKey}) | resultsPath + urlField / titleField / snippetField / publishedField | all of the above plus method, body, authHeader, authScheme, resultsPath, the four field names |
Both a non-2xx status and a non-zero business code fail the search. The vendor's
message and request_id are preserved in the error text; credentials that the
API returns inside a 402 body are redacted before the message can reach a log or
the model.
Provider selection follows the seam's own rules, resolved at call time:
a configured id wins; with no id configured, exactly one usable provider is
required. The plugin's own cordis.patch.yml therefore also sets
web.searchProvider: custom so the choice is explicit rather than accidental.
Requirements
| Item | Value |
|---|
| DeepSeek Harness | `>=0.1.2-alpha.3 <0.1.8 |
| Node.js | `^22.19.0 |
| Runtime dependencies | none — the peers come from the dsh host install |
| Network | outbound access from the dsh host to the endpoint you configure (AnySearch resolves to its mainland-China gateway) |
| AnySearch API key | optional — the anonymous tier works without one |
The dsh range is declared under dsh.engines.dsh (and mirrored in
peerDependencies for the dsh packages the plugin relies on). The disjunction is
load-bearing rather than cosmetic: npm semver only satisfies a prerelease from a
range group that itself contains a prerelease with the same
[major, minor, patch] tuple, so a plain <0.2.0 group does not cover
0.1.5-rc.1 or 0.1.7-rc.1. DSH itself checks the same peers at install and
startup preflight with includePrerelease: true; that gate is more permissive,
which is precisely why the pnpm-strict side needs its own counter-proof.
tests/entry.test.mjs pins this with a decision table, a counter-proof against
the old single range, and tests/host-integration.test.mjs runs the host's real
evaluatePluginCompatibility and real semver against it.
[!IMPORTANT]
dsh 0.1.7 moved the settings model. The plugin was adapted for
0.1.7-rc.1: settings.installSection() is gone (an exported Config schema
is the namespace now, and its fields must be .volatile() to be editable
live), the browser-side settingsScope service was replaced by
configForms, and the card moved from the removed settings.plugin.item slot
to plugins.item on the Plugins page. The card renders through the shared
official form primitives, so it looks and behaves like the built-in provider
cards. Details: docs/DSH-0.1.7-ADAPTATION.md.
Install
dsh plugin --profile web add dsh-web-search-custom
Restart the dsh web instance afterwards. From a local checkout, pass the
directory path instead of the package name.
Configure in the settings page
Open Settings → Plugins in the web UI and click into the
"Custom search (web-search-custom)" row — its page shows the form:
- the API profile (
auto / anysearch / generic),
- the search URL (AnySearch by default),
- the API key — leave it empty for the keyless tier,
- the result cap (
maxResults, 1–10 on AnySearch),
- request method, POST body template, extra headers (JSON), timeout,
- the result field mapping (
resultsPath / urlField / titleField /
snippetField / publishedField; generic profile only).
Saving writes the web-search-custom: entry of your profile patch document
($DSH_HOME/profiles/web/cordis.patch.yml) and takes effect immediately — the
next search uses the new value, no restart. The form, its overridden/reset badges
and its read-only notice are the same shared components the first-party provider
cards use.
If an older release pinned a different URL there, clear that field (Reset → Save)
so the shipped AnySearch default applies again.
Configuration reference
| Field | Default | Description |
|---|
api | auto | Profile: auto (decided by the URL host), anysearch (AnySearch POST API), generic (any templated JSON endpoint) |
url | https://api.anysearch.com/v1/search | Search endpoint. The AnySearch profile POSTs here; the generic profile supports {query} (URL-encoded), {queryRaw} (verbatim) and {apiKey} placeholders and appends q= for GET without a {query} |
apiKey | empty | Optional. Empty in the AnySearch profile sends no Authorization header (anonymous free tier); set it to send Authorization: Bearer <key>. In the generic profile the header name/scheme fields apply, and a {apiKey} in the URL or body suppresses the extra header |
maxResults | 10 | AnySearch profile only: sent as max_results, computed as min(this, caller limit) and clamped to 1–10 |
method | GET | Generic profile only: GET or POST; anything else degrades to GET |
body | {"query":"{query}"} | Generic profile only: POST body template, supports {query} / {queryRaw} / {apiKey} |
headers | {} | Extra request headers as a JSON string |
authHeader | Authorization | Generic profile only: header name used for the API key |
authScheme | Bearer | Generic profile only: auth scheme; leave empty to send the bare key |
timeoutMs | 30000 | Per-request timeout |
resultsPath | results | Generic profile only: dotted path to the result array, e.g. data.results |
In the generic profile each field also falls back to a wider list of common
aliases at mapping time (for example a missing titleField value still tries
title then name). The AnySearch profile always reads
data.results[].title / .url / .snippet and falls back to .content.
Vertical and parameterized queries
The AnySearch profile sends a plain general-web query. For vertical search
(tag / params / zone / language — see the
API docs) switch to the
generic profile and write the body yourself; the response envelope stays the same,
so only the field mapping changes:
- id: web-search-custom
config:
api: generic
url: 'https://api.anysearch.com/v1/search'
method: POST
body: '{"query":"{queryRaw}","tag":"code.doc","params":{"library":"golang"},"max_results":5}'
resultsPath: data.results
urlField: url
titleField: title
snippetField: snippet
publishedField: ''
Other configuration channels
Profile patch layer (settings document alternative)
- id: web-search-custom
config:
api: auto
url: 'https://api.anysearch.com/v1/search'
apiKey: ''
maxResults: 10
method: GET
body: '{"query":"{query}"}'
headers: '{}'
authHeader: Authorization
authScheme: Bearer
timeoutMs: 30000
resultsPath: results
urlField: url
titleField: title
snippetField: content
publishedField: publishedDate
Note: a patch replaces the whole config block — write every key when overriding.
Environment variables
Environment overrides win over the settings page and require no file edit:
| Variable | Description |
|---|
WEB_SEARCH_CUSTOM_API | Override the profile (auto / anysearch / generic) |
WEB_SEARCH_CUSTOM_URL | Override the search URL |
WEB_SEARCH_CUSTOM_API_KEY | Override the API key (recommended for secrets); empty keeps the keyless tier |
WEB_SEARCH_CUSTOM_MAX_RESULTS | Override the AnySearch result cap |
WEB_SEARCH_CUSTOM_HEADERS | Extra headers, JSON string |
WEB_SEARCH_CUSTOM_TIMEOUT_MS | Timeout in milliseconds |
Uninstall
dsh plugin --profile web remove dsh-web-search-custom
Restart dsh and the stock search provider takes over again.
Limits
- The API key is stored as an ordinary settings field, not in a credential
store. For sensitive deployments prefer
WEB_SEARCH_CUSTOM_API_KEY.
- AnySearch caps a single request at 10 results (
max_results 1–10); the tool
layer truncates further to the caller's maxResults.
- AnySearch's anonymous tier is rate-limited per client IP and metered against a
daily free quota. When it runs out the API answers 402 and may return
auto-generated credentials; the plugin surfaces that as an error and redacts
those credentials instead of storing them. Add a key to keep searching.
- Result mapping is field-based, not query-language aware: the generic profile
needs the field mapping (and, if necessary,
resultsPath) adjusted for exotic
payload shapes.
Development
pnpm install # dev dependencies (@deepseek-ai/dsh + dsh-settings 0.1.7-rc.1,
# schemastery 3.18.4 — the host-contract test loads the real packages)
pnpm test # node --test tests/*.test.mjs && node tests/client-smoke.mjs
pnpm run test:host # host-contract subset, on its own
pnpm is required for the dev install: the dsh devDependency pulls native
subprocess helpers whose build scripts must be explicitly declined (see
allowBuilds in pnpm-workspace.yaml) — nothing here needs a native build.
| Test | What it proves |
|---|
tests/entry.test.mjs | Real entry load (import('../src/index.js')), manifest declarations, the 0.1.7 settings-namespace source (Config exported, every field .volatile(), {get()} live references, configure({ auto: false })), the engines decision table (hand-rolled comparator + counter-proof + cross-check against the host's real semver.satisfies), four-way key parity (host schema ↔ client fields ↔ client views ↔ patch config), locale key parity, static guards against the removed client APIs, dependency hygiene |
tests/anysearch.test.mjs | AnySearch profile: auto-detection, keyless vs Bearer headers, max_results arithmetic, vendor envelope mapping, the error envelope (message + request_id + 402 credential redaction), and generic-profile non-regression |
tests/host-integration.test.mjs | Driven by the real host packages: real Cordis + WebRuntime + the real @deepseek-ai/cosmokit volatile protocol (a _commitVolatile-style update is visible to the next search), the real dsh-settings schema helpers (volatileForm / isVolatilePath / projectForm / plainConfig), real source-level assertions on the client bundles this card depends on, and the host's real evaluatePluginCompatibility + semver against the declared ranges |
tests/client-smoke.mjs | Browser half: bundle id, short service names, locale parity, configForms.whileServed gating, the plugins.item registration contract (id/order/label thunk), both views (summary one-liner vs page form), save/reset write path, invalid-input blocking, read-only disabling and the read-only write refusal |
tests/live-search.mjs | Opt-in live check against a real endpoint: DSH_WSC_LIVE_URL='https://api.anysearch.com/v1/search' node tests/live-search.mjs (add DSH_WSC_LIVE_BAD_KEY=1 to also assert the invalid-key error path) |
Live checks (opt-in, they hit the network)
# end-to-end through the real seam against a live endpoint
DSH_WSC_LIVE_URL='https://api.anysearch.com/v1/search' node tests/live-search.mjs 'your query'
# the same, plus the invalid-key error path
DSH_WSC_LIVE_URL='https://api.anysearch.com/v1/search' DSH_WSC_LIVE_BAD_KEY=1 node tests/live-search.mjs 'your query'
# two-arm control: prove the user-layer url is what decides, and that the new default returns results
DSH_WSC_LIVE_PARITY=1 node tests/live-settings-parity.mjs
The default pnpm test suite stays offline-runnable; these scripts print SKIP unless the
environment variable above is set.
src/index.js host half — settings namespace, profile dispatch, result mapping
lib/client.js browser half — settings card (hand-written bundle, no build step;
renders through the shared official form primitives)
cordis.patch.yml bundle patch: select provider "custom" and mount the plugin
tests/ entry + anysearch + host-contract + client-smoke + opt-in live check
License
MIT
