dsh-keys-manager

DSH Keys Manager

English | 简体中文

A DeepSeek Harness plugin that turns one provider API key into a managed pool. It extends the Models page rather than replacing it: providers, models, and the model picker stay where they are; only the API-key source moves behind the manager.

What it does

Pool and routing

• Several keys per provider, each with an alias and a health state.
• One key pinned to a session, round-robin for new sessions; a failing request is retried on its key, then moved to another key.
• Exponential cooldown recovery, capped at seven days.

Accounts and sign-in

• Seven pi-ai OAuth providers can join the pool as an account instead of a pasted key.
• Two more sign in through the plugin's own bundled clients: Kilo and Z.AI Coding Plan.
• Seven companion transport routes for providers the vendored pi-ai cannot speak: Cursor, Devin, the two Google routes, Factory Droid, and the two GitLab Duo routes.

Interface

• A search-driven Keys Manager page on the plugin's own detail page.
• A "managed by Keys Manager" badge inside the existing Models provider cards.
• Extra built-in providers installed as ordinary llm-pi-ai routes — 35 of them, listed under Provider coverage.

Quick start

Install

In the Desktop or Web app, open Plugins → Add plugin, enter dsh-keys-manager, click Install, then Enable now. This installs the same published package as the CLI path, already carrying its built bundle.

dsh plugin --profile web add dsh-keys-manager

One install yields both bundles, dsh-keys-manager and llm-omp-transports; enable both — the manager owns credentials and routing, the transport the seven routes' wire protocols. Refresh the Web page afterwards for the browser half.

git clone https://github.com/btspoony/dsh-keys-manager
cd dsh-keys-manager
pnpm i
dsh plugin --profile web link .

Use it

Take over a provider and add keys

1. Search for a provider. Open Plugins → Keys Manager → View (Plugins → 密钥管理 → 查看 in the Chinese locale); the manager renders on the plugin's detail page. Existing DSH providers appear first; the plugin also ships the curated extra catalog described under Provider coverage.
2. Adopt a provider. For an existing provider the manager imports the currently resolved credential, writes a broker reference into the provider profile, and leaves the original key in the credential store so release can restore it.
3. Add more keys with an alias. Every key is stored in the Harness credential store under its own reference; the manager state document never contains a key literal.
4. Manage a key from the three-dot menu: rename, pause/resume, delete. A key row shows status, last use, and the recovery time while cooling.
5. Tune retry count (1–3), base cooldown, and recovery grace in the settings card.

Accounts and sign-in

Providers that ship a native OAuth sign-in offer two ways to join the pool: Add key stores a static API key, while Add account runs the provider's OAuth sign-in flow and stores the result as an account row in the same pool. Nine routes join as an account: seven through pi-ai's own flows, kilo and zai through the plugin's bundled clients (device code, pasted zcode:// redirect), which mint a static credential renewed only by Sign in again.

API keys form the selection ring — sticky sessions, round-robin, retry failover and cooldowns operate across the provider's keys — while one projected OAuth grant serves its provider, and an account row's counters reflect only that account's own successes and failures. Per-account ranking is future work. When the projected grant fails, the account cools down and the pool falls back to its keys, or stops serving on an OAuth-only route until a manual re-login.

muse-code needs no transport or account row of its own: the vendored pi-ai meta route (openai-responses on https://api.meta.ai/v1) serves it, the agreement check was static, and the first live call is a manual smoke check per Known limits.

Transport routes

Providers the vendored pi-ai cannot speak are served by the companion dsh-llm-omp-transports component:

• One grant per route, at llm-omp-transports/<route> — no key pool and no per-account rotation. Sign-in happens in the Transport accounts section of the Keys Manager page.
• Models are generated from the pinned @oh-my-pi/pi-catalog@18.12.3 table when the transport is built, and the clients are unofficial: read the transports package docs and its known limits before relying on them.

Selection and failure policy

Configuration & data

Manager metadata lives at:

$DSH_HOME/keys-manager/state.json

with owner-only permissions. It contains aliases, credential references, health counters, session bindings, and provider adoption facts. API key literals live only in the Harness credential store; an account row follows the same rule behind its grantRef, with only non-sensitive metadata (email, account id, expiry) in the state. The file is written atomically through a temporary file and a rename.

Each managed provider profile points its apiKeyEnv at a broker reference such as KEYSMGR_ZAI_CODING_CN_3FA2C1. The Host credential layer answers that reference per request with the session's selected key. The Models page sees the profile as configured; writing directly to the broker reference is refused with a pointer to the manager.

Provider coverage

Four groups, one pool:

• DSH built-in — routes from the shipped DSH pi-ai catalog. The set follows your installed DSH version, so the Models page is the authoritative list; four of them are outside single-key pooling (below).
• Plugin extra built-in — 35 routes this plugin adds as ordinary llm-pi-ai routes.
• OAuth accounts — 9 routes that join as an account instead of a pasted key: seven use pi-ai's own flows, kilo and zai are signed in by the plugin's bundled clients.
• Transport routes — 7 routes the vendored pi-ai cannot speak, served by dsh-llm-omp-transports.

Every other DSH catalog route exposes an API-key credential; a route you declare yourself in the profile (自定义 / Custom) is pooled like any built-in.

Documentation

Chinese: README.zh-CN.md · 开发 · 发布 · 已知限制.

License

Released under the MIT License.