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

Install

# 1. Install DSH (pin the verified version)
npx @deepseek-ai/dsh@0.1.1-rc.2

# 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

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:

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