DSH, as a Headless tool, needs to handle scenarios such as request header filtering and multi-key polling when calling certain models. Older plugin versions replace the official adapter, causing features such as streaming and tool calls to fail. This plugin uses the standard installation method, retains the official llm-pi-ai adapter, and only injects request headers and polling keys. DSH’s design philosophy is “everything is a plugin”; community-maintained plugins have no official affiliation with DeepSeek.

Core Features

This plugin mainly solves the following problems:

  1. Configure request headers by provider: Supports editing request headers in the “Model Extensions” section of the settings sidebar.
  2. Key polling: Configure multiple API keys for the same provider; the plugin automatically polls and injects them in Round-Robin order.
  3. Configure retry policies by provider: Supports adjusting retry mode, retry count, retryable error codes, and backoff parameters.
  4. Automatic User-Agent restoration: The official adapter filters user-agent; this plugin restores it in the underlying layer to the final request.
  5. Preserve official adapter capabilities: Core features such as reasoning feedback, SSE parsing, and tool calls remain completely consistent with the state before the plugin is installed.

Installation and Enablement

The standard installation method is recommended; manual modification of official code is not required, and reinstallation is not required when upgrading dsh.

Install using npm:

dsh plugin --profile web add dsh-llm-pi-ai-headers

Or install from GitHub:

dsh plugin --profile web add "git+https://github.com/xsluck/dsh-llm-pi-ai-headers.git"

After installation, restart the dsh web process and hard refresh the browser (Ctrl+F5). The configuration entry will then appear.

Usage

  1. Go to Settings → Model Extensions.
  2. Select a provider and add custom headers in the “Request Headers” area.
    • For example, add the following for the OpenCode Zen free tier: Key User-Agent, Value opencode/1.18.18, to avoid 403 errors.
  3. Configure key polling:
    • The primary key saved for the provider on the “Models” page automatically becomes position 1 in the polling pool.
    • Keys added on the extensions page are appended after the primary key.
    • The plugin injects keys into the Authorization request header by default.
  4. Adjust retry policy (optional):
    • Change the mode (limited count / unlimited retries) and maximum retry count in the “Retry Policy” area.
    • Select retryable error codes via Chinese labels or add custom codes.
  5. Save the configuration.

Key Polling Mechanism

After enabling the plugin, key polling takes effect automatically. The request order is: the 1st request uses the primary key, the 2nd request uses the first added key, and so on.

Configuration example (equivalent to UI editing):

llm-pi-ai:
  providers:
    my-provider:
      apiKeyEnv: MY_PROVIDER_API_KEY   # 主 Key，来自凭据库
      keyPool:
        headerName: Authorization      # 注入的请求头名
        keys:                          # 追加的备用 Key
          - "sk-key-bbb-second"
          - "sk-key-ccc-third"

Notes:
* The primary key is not written to disk and remains in the credential store; the plugin only reads it during polling.
* Additional keys are stored in plaintext in ~/.dsh/settings.yaml. Ensure that access permissions to the file are controlled.

Quota Exhaustion and Automatic Pool Recovery

When the server returns a quota exhaustion error (such as 429, with messages containing keywords like “usage limit”, “quota”, or “balance”):

  1. The plugin classifies that key as a QUOTA error, rather than a temporary rate limit.
  2. The key is immediately removed from the polling pool.
  3. The plugin attempts to parse the reset time from the message. After the time arrives, the key automatically returns to the pool without a restart.
  4. If no reset time is present in the message, it defaults to a 1-hour cooldown.
  5. If all keys are in cooldown, the plugin still attempts to send the key that will be unfrozen earliest.

Notes

  • Old version vs. new version: The old installation script disables and replaces the official adapter, which poses risks of parameter truncation and contract issues. New users should prioritize the standard installation method described above. Retaining the old installation is only recommended for existing users.
  • Compatibility: After installation, the official llm-pi-ai adapter is never modified; after uninstallation, the system returns to its original official state.