@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.
