Introduction

DeepSeek Harness (DSH) adopts a modular design, and plugins are the primary way to extend its functionality. In agent development, model routing, failover, and multi-model management are common requirements. The dsh-cpa plugin is designed to address these requirements. It integrates CLI Proxy API (CPA) into the DSH ecosystem by registering a cpa provider, enabling DSH to directly consume CPA’s model capabilities, context windows, authenticated account data, and model lists.

Plugin Overview

dsh-cpa is a dsh bundle plugin for CLI Proxy API (CPA).

  • Positioning: Registers a cpa provider. Requests go to CPA’s /v1/chat/completions, and the model list from /v1/models is synchronized.
  • Maintainer: Moraxyc
  • License: MIT

Installation and Enablement

Before installation, ensure DSH is installed and the version is 0.2.0-rc.2 or higher.

Quick installation (Web service):

npx @deepseek-ai/dsh plugin --profile web add dsh-cpa

Installation from source:

npx @deepseek-ai/dsh plugin --profile web add .

Headless Profile installation:

npx @deepseek-ai/dsh plugin --profile headless add dsh-cpa

After installation, once the Web service is restarted, management routes remain available.

Core Features

The plugin provides the following core capabilities:

  1. Provider Registration and Routing: Registers a cpa provider. Agent requests are automatically routed to CPA’s /v1/chat/completions endpoint.
  2. Model Synchronization: Automatically synchronizes the model list from /v1/models, refreshing it every 5 minutes.
  3. Dual-Mode Support: Supports external CPA (connecting to an existing service) and internal CPA (started automatically by the plugin).
  4. Intelligent Routing and Failover:
    • User-specified models are always the first candidate.
    • Retries follow candidate order only if the request has not yet produced streamed content and CPA returns quota exhaustion, rate limiting, server errors, transport errors, or empty responses.
    • Once streaming has started, requests are not replayed.
  5. Management Panel: Provides a settings panel supporting configuration of external CPA URL, API Key, Management Key, or internal CPA path.
  6. Usage Status Monitoring: Parses x-cpa-trace-id, records execution traces, and provides usage status and summaries.
  7. Account Management Isolation: Account credentials and switching are managed by CPA. The plugin only consumes masked account/quota data.

Typical Usage

Using an Existing CPA

If you already have a running CPA service, you can switch to “external CPA” mode in DSH’s settings panel. After filling in the CPA URL, API key, and management key, click “Apply”.

Automatically Starting an Internal CPA

By default, the plugin generates $DSH_HOME/cpa/config.yaml and automatically starts the cli-proxy-api process. Before starting, it resolves the executable in PATH; if the binary is not in PATH, enter the absolute path in “Internal CPA Path” on the CPA settings page.

Intelligent Failover

When using the cpa provider in Agent configuration, the system generates a candidate order based on synchronized model capabilities, context windows, account health, and quota snapshots. If CPA returns insufficient quota or service abnormalities, the plugin attempts to switch to the next candidate model (unless streaming has already started).

Notes

  1. Version Requirement: DSH must be installed with version 0.2.0-rc.2 or higher.
  2. Data Security: The plugin only consumes CPA’s masked account and quota data and does not copy CPA’s account management capabilities. CPA’s management API does not expose token summaries.
  3. Replay Mechanism: Once the streaming response begins, requests are not replayed, avoiding the Agent receiving duplicate content or side effects.
  4. Settings Persistence: Settings are saved to the dsh-cpa configuration of the current active profile.
  5. Permissions: The plugin runs with the permissions of the current DSH process. Please ensure you review the source code and license before installation.

Summary

dsh-cpa seamlessly integrates CPA’s capabilities into DSH’s agent routing system. By automatically synchronizing model lists, providing intelligent failover, and offering unified usage status monitoring, it simplifies multi-model management and proxy development workflows. Through the settings panel, users can flexibly configure internal or external CPA services.