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.1-rc.2 (verified), e.g. npx @deepseek-ai/dsh@0.1.1-rc.2
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.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

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