dsh-web-search-ark

Readme

# dsh-web-search-ark

A web-search provider plugin for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness)
that routes the built-in `web_search` capability through **Volcengine Ark
(火山方舟)**. It is designed for deployments whose chat model runs on Ark and
that do not have a DeepSeek official-platform key.

> 中文使用指南见 [docs/使用指南.md](docs/使用指南.md)。

## Why

The official DeepSeek search provider speaks the Anthropic Messages API against
DeepSeek's own platform, so an Ark-only deployment fails with
`Authentication Fails ... key is invalid`. Ark exposes its 联网内容插件
(web search plugin) only through the **Responses API** with the native
`{"type": "web_search"}` tool. This plugin calls that endpoint and maps the
model's `url_citation` annotations to DSH search sources.

## What it does

- Registers a search provider under the id **`ark-official`**
  (`web.searchProvider: ark-official`, or `$DSH_WEB_SEARCH_PROVIDER=ark-official`).
- Calls `POST {baseURL}/responses` with the native `web_search` tool
  (`max_keyword` bounds how many keyword searches one round may run; Ark
  accepts 1–50).
- Normalizes the Responses body into DSH's search-result shape (answer text,
  deduplicated sources with title / publish time / site name), and throws a
  structured `WEB_PROVIDER_ERROR` when the model never triggered a search.
- Ships a settings card in **Settings → Plugins** (model, endpoint, max
  keywords, API key) with the same staged save / collapse behavior as the
  built-in cards.
- Records every request under the session event
  `web/ark-search-llm-request` (registered into the session vocabulary, so the
  fail-closed persistence reader still loads affected session logs).

## Requirements

| Item | Requirement |
|---|---|
| DSH | `0.1.2-rc.1` (verified for 1.1.0+), e.g. `npx @deepseek-ai/dsh@0.1.2-rc.1` (`0.1.1-rc.2` for 1.0.x) |
| Node / pnpm | `dsh plugin` is a pnpm forwarder — install pnpm (`npm i -g pnpm` or `corepack enable`) |
| Ark account | 联网内容插件 (web search plugin) enabled, with a usable API key |
| Network | Access to `ark.cn-beijing.volces.com` (or your own `ARK_SEARCH_BASE_URL`) |

## Install

```bash
# 1. Install DSH (pin the verified version)
npx @deepseek-ai/dsh@0.1.2-rc.1

# 2. Make sure pnpm is available
npm install -g pnpm        # or: corepack enable

# 3. Unpack the plugin and place it inside the DSH home (important!)
unzip dsh-web-search-ark-1.0.0.zip
mkdir -p ~/.dsh/profiles/web/packages
cp -R web-search-ark ~/.dsh/profiles/web/packages/

# 4. Register the plugin (writes package.json deps + dsh.profile.bundles)
dsh plugin --profile web add ~/.dsh/profiles/web/packages/web-search-ark

# 5. Append to ~/.dsh/profiles/web/cordis.patch.yml (merge into the array):
#    - id: web
#      config:
#        searchProvider: ark-official

# 6. Configure the Ark key (the same key as your chat model works):
#    A) Settings → Models page in the web UI, or
#    B) VOLCENGINE_API_KEY in ~/.dsh/.credentials.yaml, or
#    C) export VOLCENGINE_API_KEY in the launching environment

# 7. Start and verify
dsh web
```

> **Keep the plugin directory inside `~/.dsh`** (the official location is
> `~/.dsh/profiles/<profile>/packages/`). If it lives elsewhere, `dsh plugin
> add` fails with `Cannot find package '@deepseek-ai/schemastery'`, because
> Node resolves `@deepseek-ai/*` bridges from the plugin's real path upward to
> `~/.dsh/profiles/node_modules/`.

## Configuration

| Key | Default | Description |
|---|---|---|
| `apiKeyEnv` | `VOLCENGINE_API_KEY` | Credential reference: resolved from the credentials service, the launching environment, or a literal `apiKey` in this section |
| `baseURL` | `https://ark.cn-beijing.volces.com/api/v3` | Responses-API base; `/responses` is appended. Env override: `ARK_SEARCH_BASE_URL` |
| `model` | `deepseek-v4-flash-ga-260731` | Model id used for the search sub-task |
| `maxKeyword` | `5` | Max keyword searches per round (Ark allows 1–50) |

The bundle patch (`cordis.patch.yml`) presets `apiKeyEnv`, `model`, and
`maxKeyword`; a user patch only needs `web.searchProvider: ark-official`.
See `examples/example-cordis.patch.yml`.

## Cost

Ark's web search plugin bills **per actual search invocation**: one
`web_search` may fan out into up to `maxKeyword` keyword searches, each billed
separately. There is no cache; repeated calls cost again. Every request is
recorded under `web/ark-search-llm-request` for reconciliation in the Ark
console.

## Development

```bash
npm ci                      # installs the DSH dev dependencies for the tests
npm test                    # offline contract + client-card + session-load checks
SMOKE_LIVE=1 npm run test:live   # also perform one real Ark search (needs a key)
```

Environment variables for the test harness:

| Variable | Default | Purpose |
|---|---|---|
| `DSH_MODULES_ROOT` | auto (`./node_modules`, then `~/.dsh/profiles/node_modules`) | Where `@deepseek-ai/*` packages resolve from |
| `DSH_CREDENTIALS_FILE` | `~/.dsh/.credentials.yaml` | Credential file for live tests |
| `SMOKE_LIVE` | unset | Perform the live Ark search scenario |
| `ARK_SMOKE_API_KEY_ENV` | `VOLCENGINE_API_KEY` | Credential reference for the live call |
| `ARK_SMOKE_MODEL` | `deepseek-v4-flash-ga-260731` | Model for the live call |
| `ARK_SMOKE_MAX_KEYWORD` | `3` | `max_keyword` for the live call |
| `DSH_SESSIONS_ROOT` / `DSH_SESSION_ID` | — | Session-log A/B test; skipped when unset |

## Release

```bash
npm run release
```

Builds `release/dsh-web-search-ark-<version>.zip` (a `web-search-ark/` tree
ready for the install steps above) plus `release/SHA256SUMS.txt`. The script
self-verifies the zip by extracting it and comparing every entry before
declaring success; `release/` also keeps the unpacked tree, so
`cd release && shasum -a 256 -c SHA256SUMS.txt` verifies everything at once.
Pushing a `v*` tag triggers `.github/workflows/release.yml`, which runs the
tests and attaches the artifacts to the GitHub release.

## License

[MIT](LICENSE) © 2026 Oscar Fang