dsh-web-search

Out-of-tree multi-engine web search for DeepSeek Harness. The installable bundle registers one dsh-web-search provider that can use Tavily, Brave Search, or a private SearXNG instance.

Prerequisites

• The dsh CLI and a Web profile.
• For a source checkout: Node.js ^22.19 or >=24, pnpm, and a sibling ../deepseek-harness checkout. Client typecheck and tsdown extend that tree; published installs use the prebuilt package and do not need it.
• A Tavily or Brave API key for that engine, or a private SearXNG instance you operate or trust.

Install

Add the published bundle to a profile. That is the only package dsh plugin add needs; @anht3889/dsh-web-search-service is a nested dependency of the bundle, not a second plugin.

dsh plugin --profile web add @anht3889/dsh-web-search-bundle

From a local source checkout, build and add the workspace path instead of the npm name:

pnpm install && pnpm run build
dsh plugin --profile web add ./packages/bundle

Restart the Web profile after either install:

dsh --profile web

Open Settings → 网络搜索 (Web search in the English locale), select an engine, enter its required key or URL, and save. Engine changes apply to the next search without another restart.

Engines

The initial engine is unselected, so the pinned provider is unavailable until an engine is configured. SearXNG has no public default: use a private instance you operate or trust, and enable JSON responses in its settings. Searches request format=json; a 403 response usually means the instance does not allow format: json.

Configuration and secrets

Secret resolution uses the first non-empty value from the mounted ctx.credentials service, the private fallback file, then the process environment. Settings writes keys through ctx.credentials when it is mounted; otherwise it writes the fallback file. The HTTP API and Settings status expose only whether each key is configured, never its value.

If no Host webserver is mounted, the provider still supports headless searches, but the Settings UI and management HTTP routes are unavailable. Configure the same catalog and secret locations before starting that composition.

Runtime behavior

The bundle pins web.searchProvider to dsh-web-search. DeepSeek's deepseek-official provider remains installed but is unused while that pin is active; an unavailable wrapper does not silently fall back to it.

Management service

The manager publishes ctx.webSearchManager, whose Service Definition is @anht3889/dsh-web-search-service. The service exposes the live catalog, value-free secret state, write operations, provider availability, and change notifications without requiring a web server. Hosts without a loopback HTTP API use this service to manage the same runtime directly.

Installing the bundle pulls in the seam package as an npm dependency. TypeScript hosts that want the WebSearchManagement types can depend on @anht3889/dsh-web-search-service directly; profile users never add it with dsh plugin add. Each running profile caches its catalog in memory; a catalog written by another already-running profile becomes visible only after restart.

The Host management API serves:

• GET and PUT /web-search/config
• GET and PUT /web-search/secrets

Secret writes are write-only; omitted or empty values leave existing keys unchanged.

Restore DeepSeek search

Put this exact layer in the Web profile patch at $DSH_HOME/profiles/web/cordis.patch.yml:

- id: web
  config:
    searchProvider: deepseek-official

Restart the Web profile. A patch row replaces the complete web config, so add any other required web config keys to the same mapping.

Troubleshooting

• WEB_PROVIDER_CONFIGURED_UNAVAILABLE: Select an engine. For SearXNG, also provide a valid absolute private-instance URL. There is no automatic DeepSeek fallback.
• Missing Tavily or Brave key: Set the matching key in Settings, ctx.credentials, the fallback secrets file, or the process environment. The provider can appear available before key resolution, but the search call fails with WEB_PROVIDER_ERROR when the key is absent.
• SearXNG HTTP 403: Enable JSON output (format: json) in the instance settings and confirm you are using your private instance.
• Corrupt config.json: Host startup fails if $DSH_HOME/web-search/config.json exists but is not valid JSON or fails catalog validation (unknown keys, invalid engine, or SearXNG selected without an absolute URL). Delete the file to restore the empty catalog, or fix the JSON. Do not put secrets in this file.

Package-specific exports are listed in packages/bundle/README.md.