dsh-zhipu-toolkit

dsh-zhipu-toolkit

English | 简体中文

A DeepSeek Harness plugin that registers the Zhipu BigModel GLM family as a model-provider route — covering both BigModel endpoints with one served at a time: the Coding Plan endpoint (zai) or the ordinary OpenAPI endpoint (zhipu), with live model discovery, a locally-holdable API key, and a Web settings card.

Features

• Endpoint choice (one of two billing channels) — serve the Coding Plan endpoint or the ordinary API endpoint; both expose the same models and the same request semantics, so the choice is purely which billing channel your account uses.
• Self-maintained GLM catalog — the full GLM chat family (GLM-4.5 → GLM-5.3-Flash) with verified context windows and output caps, overlaid on pi-ai's builtin catalog.
• glm-5.3-flash native multimodality (image input enabled) — the official docs list GLM-5.3-Flash input as video, image, text, and file (multiple image_url parts in messages[].content[], URL or Base64); pi-ai's Model["input"] type only knows text/image today, so image input ships first and video/file input stays pending until the type grows those modes, while every other maintained model remains text-only.
• Local usage & quota statistics — the card aggregates this machine's session logs (multi-frame zstd) into per-model GLM usage: requests, tokens (cache counted), and credits converted at the official BigModel factors, with a recent-5h window, incremental caching (warm rescans are instant), a host background pre-scan, and official console deep links; the aggregate is computed and shown locally, nothing ever leaves the machine.
• Verified GLM-5.3 thinking semantics — GLM-5.3-series models always think; the plugin maps picker tiers onto the wire values the API accepts (low/medium/high → high, xhigh/max → max) and never wires thinking: disabled (the API refuses it with error 1210).
• Live model discovery — /models is polled at startup and after every settings/credential change; models the endpoint stopped serving drop out, while directly-verified models survive endpoint lag.
• Local API key on the settings card — optionally hold the key right on the card (stored in the dsh credentials store as ZHIPU_TOOLKIT_API_KEY, never in settings.yaml); a saved key shows as a masked summary (last characters only) with icon actions to edit-in-place or clear, and the env-reference path stays as fallback.
• Settings card (Web GUI) — the card lives in the official Settings → Plugins configuration tab (a settings.plugin.item slot keyed by the settings namespace, alongside the other configurable plugins) and edits the endpoint, credential refs, display name, default reasoning tier, and the local API key over a whitelisted RPC bridge; configuration is hot-reloadable (no restart).
• Bilingual UI — the card follows the host locale service (zh-CN / en) with a browser-language fallback.

Install

dsh plugin --profile web add dsh-zhipu-toolkit

Or install from a packed tarball during development:

npm pack
dsh plugin --profile web add ./dsh-zhipu-toolkit-<version>.tgz

Restart dsh web after installing (client bundles and the host plugin tree are assembled at startup).

Configuration

The plugin owns the zhipu-toolkit settings namespace. Layered like every DSH settings namespace: the composition entry (below) is the base layer, and user edits — from the Web settings card or ~/.dsh/settings.yaml — override it. Committed writes re-resolve the routes without a restart.

# ~/.dsh/settings.yaml
zhipu-toolkit:
  endpoints: coding         # coding | paas (one billing channel at a time)
  codingApiKeyEnv: BIGMODEL_API_KEY
  paasApiKeyEnv: ZHIPU_API_KEY
  displayName: BigModel
  defaultReasoningTier: low # low | medium | high | xhigh | max
  useLocalApiKey: false     # true = hold the key on the settings card

Field	Default	Notes
endpoints	coding	Which billing channel to serve (see Endpoints below).
codingApiKeyEnv	BIGMODEL_API_KEY	Credential reference for the Coding Plan route.
paasApiKeyEnv	ZHIPU_API_KEY	Credential reference for the ordinary route.
displayName	BigModel	Provider label shown in model selectors.
defaultReasoningTier	low	Tier wired for requests that name no effort.
useLocalApiKey	false	Hold the API key locally (credentials store) instead of an env ref.
codingBaseURL	https://open.bigmodel.cn/api/coding/paas/v4	Override for proxies/gateways.
paasBaseURL	https://open.bigmodel.cn/api/paas/v4	Override for proxies/gateways.
streamIdleTimeoutMs	300000	Max provider idle time per stream read.
maxRequestImageBytes	20971520	Base64 image payload bound per request.
requestImagePixelBudget	4194304	Total-pixel budget per inline image version.
requestImageMaxBytes	1048576	Encoded-byte cap per inline image version.

Two ways to provide the API key:

• Env reference (default) — store the key under the env-var-like reference (BIGMODEL_API_KEY / ZHIPU_API_KEY, or whichever you configured) through the credentials service: dsh credentials set BIGMODEL_API_KEY.
• Local key (card) — switch useLocalApiKey on and paste the key into the card's password field. It is stored in the dsh credentials store as ZHIPU_TOOLKIT_API_KEY (never in settings.yaml), takes effect immediately, and falls back to the env reference if unset. A saved key displays as a masked summary (e.g. ••••••••abcd); the edit icon re-opens the input so a new value overwrites the saved one on blur/Enter (an empty edit leaves it untouched), and the clear icon removes it.

Endpoints

The two endpoints expose identical model lists and parameter behavior (verified live 2026-09-06: both /models return the same 10 chat models; thinking/reasoning_effort: max behave identically). The difference is billing:

Route id	Endpoint	Billing
zai	https://open.bigmodel.cn/api/coding/paas/v4	Coding Plan: subscription quota (Lite/Pro/Max), 5-hour + weekly dual limits that reset with the window and never touch the balance; 50% discount off-peak; scoped to official coding tools.
zhipu	https://open.bigmodel.cn/api/paas/v4	Ordinary API: per-token billing (resource packs / balance), no scene restriction.

A deployment picks the one its account is billed on; the plugin serves that single route.

Reasoning tiers

GLM-5.3-series models cannot turn thinking off — the API rejects thinking: disabled with error 1210. The plugin therefore:

• removes off (and minimal) from the picker for GLM-5.3 / GLM-5.3-Flash;
• maps low/medium/high onto the high wire tier and xhigh/max onto max;
• defaults the profile to the configured tier (lowest offered, low) so effort-undefined requests stay valid.

All other maintained models keep pi-ai's builtin tier maps. The full offered picker set is low | medium | high | xhigh | max.

Troubleshooting

• no API key for provider route ... — no key is stored on any path. Store the env reference (dsh credentials set <ENV>), or switch useLocalApiKey on and paste the key on the card.
• Models missing from the picker — live discovery filters against what the endpoint's /models reports. Directly-verified models (glm-5.3, glm-5.3-flash) survive endpoint lag; everything else must be reported by the endpoint. Check the plugin logs for live refresh failed; keeping the maintained catalog.
• Error 1210 (请使用 low、high 或 max) — a request tried to disable thinking on a GLM-5.3-series model. Keep the default reasoning tier at low or above; do not select off.
• Settings card shows "read-only" — the deployment's settings document is read-only (e.g. a managed profile); edit the composition entry instead.
• Card never appears — confirm dsh web was restarted after install, and that the plugin loaded (dsh plugin list).

Credits

• The catalog design, the GLM-5.3 thinking-level mapping, the compat flags, and the append-override merge semantics are derived from dsh-bigmodel-catalog (commit d8189e3), verified live against both BigModel endpoints on 2026-09-06 — including reasoning_effort: max and max_tokens: 131072 round-trips with SSE reasoning_content.
• Message conversion and provider plumbing ride on pi-ai.

License

MIT