@bocha-ai/dsh-web-search-bocha

English | 中文

A Bocha Web Search-backed WebSearchProvider and installable Profile bundle for DeepSeek Harness. The package registers provider id bocha, calls Bocha's POST /v1/web-search endpoint, and carries a dsh.bundle patch that selects the provider after installation.

The package supplies search only. DeepSeek Harness continues to own the model-facing web_search tool, result limits, citations, provider selection, and error presentation through its web capability.

Install

Install the bundle into a Profile:

dsh plugin --profile web add @bocha-ai/dsh-web-search-bocha

Optionally inspect the composed configuration; this prints it and exits:

dsh --profile web --dump-config

Start the Web app with:

dsh --profile web

Configure the API key with either option below. You do not need both.

Option 1: DSH credentials document

Store the key in $DSH_HOME/.credentials.yaml (normally ~/.dsh/.credentials.yaml):

BOCHA_API_KEY: your-api-key

On POSIX, the file must be owner-only:

chmod 600 ~/.dsh/.credentials.yaml

The plugin resolves this reference through the Harness credentials service for every search, so a stored key rotation applies to the next request without a restart.

Option 2: Environment variable

For CI, containers, or a per-run override, export the key before starting Harness:

export BOCHA_API_KEY='your-api-key'

If both options configure BOCHA_API_KEY, the inherited environment variable takes precedence over the managed credentials document.

Removing the package removes its provider row and bundle layer:

dsh plugin --profile web remove @bocha-ai/dsh-web-search-bocha

Bundle behavior

cordis.patch.yml replaces the base web row's complete config with searchProvider: bocha and inserts a web-search-bocha row that loads this package. Existing providers remain mounted, but ctx.web routes search to bocha. Profile, Harness-home, and command-line patch layers applied later can replace either row.

Config

Key	Default	Meaning
apiKey	—	Optional literal Bocha API key. It is redacted from settings descriptions, but the credentials service is preferred so no plaintext key enters a Profile patch.
apiKeyEnv	BOCHA_API_KEY	Credential reference resolved through the Harness credentials service for every search.
baseURL	https://api.bocha.cn	API base; /v1/web-search is appended.
freshness	noLimit	Time filter sent on every search: noLimit, oneDay, oneWeek, oneMonth, oneYear, one date such as 2025-04-06, or a range such as 2025-01-01..2025-04-06.
summary	true	Requests Bocha's longer per-page summary.
count	10	Default count when the Harness request has no maxResults; integer from 1 through 50.

A later Profile patch can configure the inserted row without changing the package:

- id: web-search-bocha
  config:
    freshness: 2025-01-01..2025-04-06
    summary: true
    count: 10

Mapping and failures

The provider reads data.webPages.value[]. It maps url to WebSearchSource.url, name to title, summary to snippet with snippet as the fallback, and datePublished to publishedAt; an entry without a non-blank URL is dropped. Bocha does not return one generated answer for this endpoint, so WebSearchResult.content is omitted.

The request's maxResults overrides count and is capped at Bocha's maximum of 50 before the request is sent. The Harness web capability still enforces its own final source bound.

HTTP errors, provider-declared non-200 codes, network failures, and unprocessable response bodies surface as WebError WEB_PROVIDER_ERROR. Error messages retain Bocha's log_id when present. Abort-shaped failures surface as WEB_ABORTED, and redirects are rejected before their target is contacted.

The provider resolves the referenced credential at each search entry, so a key stored or rotated through the UI takes effect on the next request without restarting or re-registering the provider. A missing referenced credential surfaces as WEB_PROVIDER_CREDENTIAL_MISSING.

Development

Install development dependencies, run the keyless tests, build, and inspect the npm payload:

npm install
npm test
npm run build
npm pack --dry-run

Run the live smoke only when a Bocha key is available:

BOCHA_API_KEY='your-api-key' npm run test:e2e

Model Experience

Indirectly, through DeepSeek Harness dsh-tool-web, which renders this provider's bounded URLs, titles, summaries or snippets, and publication dates under the stable web_search tool contract.

KV Cache effect

No direct invalidation; the Harness tool consumer owns any request-prefix changes.

Known Limitations and Deferred Work

• Current upstream DSH does not expose third-party search settings in its built-in Plugins UI — that card and the Host settings allowlist are internal to DSH. Configure this package through its Profile row and store BOCHA_API_KEY in the credentials document or launch environment; publishing this npm package does not require a patched DSH checkout.
• Freshness is deployment configuration rather than a model-facing argument — every request from one mounted provider uses the same freshness value because the provider-neutral Harness request currently carries only query and maxResults.
• Bocha-specific siteName and other media fields are omitted — the portable Harness source type has no site-name, image, or video fields.
• One API call returns at most 50 sources — a larger Harness maxResults request is capped at Bocha's documented maximum before transport.