dsh-web-search-ark
A web-search provider plugin for DeepSeek Harness (DSH)
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。
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
# 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
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
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 © 2026 Oscar Fang
