Web Search (Z.ai) for DeepSeek Harness

September 5, 2026 · View on GitHub

Search the web from DeepSeek Harness using Z.ai or Zhipu, with a native settings card in English and Chinese. Choose Coding Plan MCP quota or REST API balance, and reuse your existing ZAI_API_KEY when it is eligible for the selected service.

English | 中文 · Listed in Awesome DSH Plugins

New in 0.2.0: Coding Plan MCP search, a native English/Chinese settings card, and explicit Z.ai / Zhipu endpoints. REST API mode remains available.

Existing users: the default changes from REST to Coding Plan. To keep your current API billing, explicitly save API — API balance before your first search after upgrading. See Upgrading from 0.1.0.

What changes in 0.2

Two billing modes. Coding Plan is the default. API mode retains the existing REST transport and its engine/recency options. There is no automatic fallback to paid API.
Native settings. Set the mode, manage your key, and choose the Z.ai or Zhipu MCP endpoint in Settings → Web Search (Z.ai). Changes apply to the next search.
Same DSH integration. Provider ID zai, the web-search-zai settings namespace, and the model-facing web-search tools stay the same.
Keys stay in credentials. Blank input preserves the shared key. Reset clears only search-setting overrides; it keeps the key.

Mode	Uses	Choose it when
Coding Plan (`coding-plan`, default)	Subscription MCP quota	Your key has an eligible Coding Plan subscription
API (`api`)	Separately billed API balance	You want REST search or are keeping your 0.1.0 setup

A search can consume quota even without a chat inference request. In our Zhipu test (September 2026), each search consumed one point from the Coding Plan's rolling 5-hour pool (2,000 points per window). In REST API mode, a single search was billed at ¥0.05 RMB. A point is not a model token, and these observations are not guaranteed rates or allowances — check the current Z.ai search documentation, Z.ai usage policy, and Zhipu search documentation for your account. This is a community plugin; listing in a community catalog does not imply official DSH or Z.ai endorsement.

Install and configure

Requirements: DeepSeek Harness with the dsh CLI and its web settings services, plus Node.js 22.19+ within Node 22, or 24+. Use a native key for the service you select; third-party chat gateway keys are not supported.

Install the npm package into the web profile:

dsh plugin --profile web add dsh-web-search-zai@latest
dsh web

Prebuilt JavaScript is included. The package manager installs runtime dependencies; you do not need to allow a plugin build script. If you run DSH from its source repository, use pnpm dsh in place of dsh from that repository.

Alternatively, install the latest GitHub build:

dsh plugin --profile web add github:kenny2077/dsh-web-search-zai

In Settings → Web Search (Z.ai):

Choose Coding Plan — subscription MCP quota or API — API balance.
Leave the masked key input blank if DSH already has the right ZAI_API_KEY. Otherwise enter the key. Replacing the shared key also affects chat using that credential.
For a Zhipu / China Coding Plan key, open Advanced settings, click Use Zhipu (China), and save. Z.ai international is the default. Key format and UI language do not select the endpoint automatically.
Save, then ask DSH to search the web. The card shows the saved mode, which can differ from an unsaved selection.

Installing a local checkout

Local-path installs link to your checkout. Install its dependencies before registering it, and repeat pnpm install --frozen-lockfile after pulling an upgrade:

git clone https://github.com/kenny2077/dsh-web-search-zai.git
cd dsh-web-search-zai
pnpm install --frozen-lockfile
dsh plugin --profile web add .
dsh web

With a source checkout of DSH, run pnpm dsh plugin --profile web add <absolute-plugin-path> from the DSH repository after installing the plugin's dependencies.

Upgrading from 0.1.0

Your key, credential reference, REST endpoint, engine, and recency settings keep their meaning. An omitted billingMode now selects Coding Plan, including configurations created by 0.1.0. No automatic migration guesses your subscription or changes your billing choice.

Keep REST API billing

After upgrading, choose API — API balance in the card and Save before searching. For a file-based setup, stop DSH and add this field to the existing namespace in $DSH_HOME/settings.yaml:

web-search-zai:
  billingMode: api
  # Keep your existing apiKeyEnv, baseURL, searchEngine, and searchRecency here.

Merge this field into your existing settings; do not replace the whole file. A previously configured REST baseURL or ZAI_SEARCH_BASE_URL does not select API mode by itself.

Choose Coding Plan

Save Coding Plan and an endpoint matching the service that issued your key:

Service	`mcpURL`
Z.ai international (default)	`https://api.z.ai/api/mcp/web_search_prime/mcp`
Zhipu / China	`https://open.bigmodel.cn/api/mcp/web_search_prime/mcp`

For Zhipu:

web-search-zai:
  billingMode: coding-plan
  mcpURL: https://open.bigmodel.cn/api/mcp/web_search_prime/mcp
  apiKeyEnv: ZAI_API_KEY

An exhausted or ineligible Coding Plan returns an error. Switching to API billing is always an explicit choice.

Update the installation

Stop DSH, use the command for your installation, then restart DSH and reload its browser page:

Installed from	Update
npm	`dsh plugin --profile web update dsh-web-search-zai --latest`
GitHub	`dsh plugin --profile web update dsh-web-search-zai --latest`
Local checkout	Run `git pull --ff-only`, then `pnpm install --frozen-lockfile` in the plugin checkout

To try the GitHub build from an npm installation, run the GitHub install command above. To return to the previous release, use dsh plugin --profile web add dsh-web-search-zai@0.1.0 and restart; that release always uses REST. Your shared credential remains in DSH.

Settings reference

Field	Default	Purpose
`billingMode`	`coding-plan`	`coding-plan` or `api`
`mcpURL`	Z.ai international URL above	Full MCP endpoint; Coding Plan only
`apiKeyEnv`	`ZAI_API_KEY`	DSH credential reference, resolved for each search
`apiKey`	Unset	Optional literal key; overrides the managed credential
`baseURL`	`https://api.z.ai/api/paas/v4`	REST only; `/web_search` is appended
`searchEngine`	`search-prime`	REST only; Zhipu uses `search_pro`
`searchRecency`	Unset	REST only; `day`, `week`, `month`, or `year`

For Zhipu REST, set baseURL to https://open.bigmodel.cn/api/paas/v4 and searchEngine to search_pro. MCP uses its own full URL, not the chat endpoint or REST base URL.

The card saves non-secret fields through DSH settings and writes keys only through DSH credentials. It never reads a stored key into the browser. A literal apiKey overrides the managed key; the card identifies that override and disables key editing until the literal is removed. Without DSH credentials, the provider resolves the configured reference from the launch environment.

Save writes edited fields with revision checks. If settings change while you are editing, discard the stale edits and retry. A failed key write after a successful settings save is reported separately; re-enter the key to retry. Save a changed credential reference before entering its key.

Reset search settings removes only the card's non-secret user overrides and restores inherited values, including the default Coding Plan mode when no composition override exists. It preserves the shared key. Controls are disabled when the host settings or credential service is unavailable or read-only.

Troubleshooting

Symptom	Check
`Cannot find package '@modelcontextprotocol/sdk'`	For a local link, run `pnpm install --frozen-lockfile` in the plugin checkout, then restart DSH. `git pull` alone does not install new dependencies.
Search fails after upgrading	Check the saved billing mode. Existing REST users must explicitly select `api`.
Authentication or quota error	Match the key to its Z.ai/Zhipu endpoint and check the subscription or API balance for the selected mode. A configured badge reports key presence, not successful authentication.
New card is missing	Confirm the plugin is installed in the `web` profile, restart DSH, and reload the browser. The old 0.1.0 release has no card; update to 0.2.0 or later.
Settings are read-only	Use a supported DSH host connection with writable settings and credentials; file-based configuration remains available.
Fewer results than requested	The provider drops entries without a URL or nonblank snippet. The DSH web service caps the final result count.

How it fits into DSH

DSH model → web_search tool → ctx.web → zai provider
                                        ├─ coding-plan → MCP search → plan quota
                                        └─ api → REST /web_search → API balance
                                                      ↓
                                      source URLs, titles, and snippets

The plugin registers into the existing ctx.web service. It returns sources; the chat model decides how to use them in its answer. No publication dates or generated answers are invented. It does not enable a model provider's separate chat-side web_search option.

MCP connections are created per search and closed afterward. Each Coding Plan operation has a 60-second deadline, supports caller cancellation, and is cancelled on plugin unload. HTTP redirects are rejected; searches are not automatically retried. Errors preserve DSH codes: WEB_PROVIDER_ERROR, WEB_PROVIDER_CREDENTIAL_MISSING, and WEB_ABORTED.

Verification and development

Automated coverage includes REST regression tests, local MCP JSON/SSE servers, authentication headers, tool discovery, quota errors, malformed/double-encoded responses, cancellation, timeouts, settings conflicts, partial saves, and the browser bundle. CI runs on Windows and Ubuntu with Node 22 and 24.

Live checks are separate: Zhipu Coding Plan returned real results both directly and through DSH's registered ctx.web service. The maintainer also verified the plugin in DSH on Windows, and previously tested REST mode. These checks do not promise quota availability for another account or endpoint.

pnpm install --frozen-lockfile
pnpm typecheck
pnpm build
pnpm test

Routine tests use local servers and consume no search quota. Opt-in live tests require ZAI_API_KEY and an explicit ZAI_LIVE_BILLING_MODE (coding-plan or api). Set ZAI_SEARCH_MCP_URL for Zhipu. Each pnpm test:live invocation performs one search. See CONTRIBUTING.md for commands and release checks, and CHANGELOG.md for changes.

License

MIT