dsh-web-search-tokenrhythm

Readme

# dsh-web-search-tokenrhythm

[![npm version](https://img.shields.io/npm/v/dsh-web-search-tokenrhythm)](https://www.npmjs.com/package/dsh-web-search-tokenrhythm)
[![license](https://img.shields.io/npm/l/dsh-web-search-tokenrhythm)](https://www.npmjs.com/package/dsh-web-search-tokenrhythm)

A web-search provider for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) that turns the built-in `web_search` tool into real searches through the **Token Rhythm (基元律动)** gateway's OpenAI **Responses API** (`web_search` tool). No extra account, no new API key — it reuses the key you already store for chat.

## Quick start (3 steps)

Run these inside your dsh profile directory (e.g. `%USERPROFILE%\.dsh\profiles\web`):

```sh
# 1. Install the package
pnpm add dsh-web-search-tokenrhythm
```

```jsonc
// 2. Register the bundle in profiles/web/package.json
"dsh": {
  "profile": {
    "bundles": [
      "@deepseek-ai/dsh-base",
      "@deepseek-ai/dsh-web-app",
      "dsh-web-search-tokenrhythm"   // ← add this line
    ]
  }
}
```

```sh
# 3. Restart dsh web
```

That's it. The bundle mounts the provider and switches `web_search` to it automatically — no `cordis.patch.yml` editing required.

## Prerequisites

- Your gateway must support the OpenAI **Responses API** with the native **`web_search`** tool. Token Rhythm does (`deepseek-v4-flash-0731`, which declares `webSearch: true`). Other gateways: check their model metadata before switching.
- Store an API key so the provider can authenticate. The default credential reference is **`DEEPSEEK_API_KEY`** — save it through the web UI (**Settings → Models**) or your credentials file. Point the provider at another reference with `apiKeyEnv` if you prefer.

## Verify it works

In any chat, ask: **“帮我搜一下 XXX”** or “search the web for XXX”. The response will include real source links.

## Configuration

| Key | Default | Meaning |
|---|---|---|
| `apiKeyEnv` | `DEEPSEEK_API_KEY` | Credential reference resolved for each search. |
| `baseURL` | `https://tokenrhythm.studio/v1` | OpenAI-compatible endpoint base; `/responses` is appended. |
| `model` | `deepseek-v4-flash-0731` | Search model; must declare `webSearch: true` on your gateway. |
| `maxTokens` | `2048` | Upper bound on generated answer tokens. |
| `maxRetries` | `2` | Retries for transient gateway `503` responses. |

### Switching to another gateway

Override the row from your **own** profile `cordis.patch.yml` (later layers win):

```yaml
- id: web-search-tokenrhythm
  name: dsh-web-search-tokenrhythm
  config:
    apiKeyEnv: MY_GATEWAY_API_KEY
    baseURL: https://my-gateway.example/v1
    model: my-web-search-model
```

Or edit the `web-search-tokenrhythm` section in the GUI Settings page — it takes effect on the next search without a restart.

### Not using a gateway with `web_search`?

This provider cannot help. Install a different search backend instead (e.g. `@deepseek-ai/dsh-web-search-exa` or `@deepseek-ai/dsh-web-search-perplexity`) and set `searchProvider` to its id.

## Troubleshooting

| Symptom | Cause / Fix |
|---|---|
| `WEB_PROVIDER_CREDENTIAL_MISSING` | No key for `apiKeyEnv`. Save it in **Settings → Models** or set `apiKeyEnv` to a reference you have. |
| `tools.0.input_schema 类型错误` / invalid tool type | The gateway does **not** support the `web_search` tool. Switch gateway or provider. |
| `SERVICE_BUSY` (HTTP 503) | Gateway overloaded; retried automatically up to `maxRetries`. Retry the search later if it still fails. |
| Search works but sources have no titles | Expected: this gateway returns opened-page URLs plus a generated answer; no structured title/snippet. |

## How it works

One search issues a **full Responses model call** with `tools: [{ type: 'web_search' }]`. The gateway runs server-side retrieval; the model may open several pages (`web_search_call` items). The provider:

- collects opened-page URLs as citeable `sources[]` (deduplicated, `#ws_call_id=` tracking fragments stripped);
- takes the model's `final_answer` text as `content`;
- retries transient `503` responses.

Failures surface as `WEB_PROVIDER_ERROR`; caller cancellation as `WEB_ABORTED`. MIT licensed.

## Development

```sh
# Build (TypeScript → lib/)
pnpm exec tsc -b .

# Test (Vitest, 16 cases)
pnpm exec vitest run tests/provider.spec.ts

# Package
npm pack
```

The package follows the DeepSeek Harness plugin conventions: a Cordis plugin exporting `name` / `inject` / `apply` / `Config`, plus a bundle patch (`cordis.patch.yml`) that mounts itself when the package is listed in a profile's `dsh.profile.bundles`.

## License

[MIT](LICENSE)