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

Readme

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

English | [中文](README.zh.md)

A [Bocha Web Search](https://open.bocha.cn/)-backed `WebSearchProvider` and installable Profile bundle for [DeepSeek Harness](https://github.com/deepseek-ai/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](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/web/web).

## Install

Install the bundle into a Profile:

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

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

```sh
dsh --profile web --dump-config
```

Start the Web app with:

```sh
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`):

```yaml
BOCHA_API_KEY: your-api-key
```

On POSIX, the file must be owner-only:

```sh
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:

```sh
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:

```sh
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:

```yaml
- 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:

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

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

```sh
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.