dsh-keys-manager

Usage

Open Plugins → Keys Manager → View (rendered as Plugins → 密钥管理 → 查看 in the Chinese locale). The manager renders on the plugin's detail page, between its description and its included rows, matching the shipped plugin configuration cards.

1. Search for a provider. Existing DSH providers appear first; the plugin also ships the curated extra catalog described above.
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.

Selection and failure policy

• Sticky session: the first request of a session selects a key and binds it for that session/provider pair. Later requests reuse it.
• Round robin: a new session advances the provider cursor and takes the next healthy key.
• Retry: a failing request is retried on the same key retryCount times.
• Switch: after the retry budget is spent, the failing key is marked cooling, and the session is rebound to another healthy key.
• Cooldown: the first failure cools a key for baseCooldownMs. A failure while cooling, or within recoveryGraceMs after recovery, doubles the next cooldown. A long healthy gap resets the escalation. The hard cap is seven days.
• Recovery: the key is automatically selectable again when its cooldown expires; no manual reset is required.
• Delegation: request-shaped failures such as CONTEXT_WINDOW_EXCEEDED and cancellation never cool a key. When no alternate key exists, the manager delegates to the composition's normal retry/fallback 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. 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.

OAuth2 extension point

The state shape already distinguishes kind: "api-key" from kind: "oauth" and keeps a nullable oauth object beside the credential reference. A future account flow can add records under keys-manager/ / without rewriting existing rows. Providers whose only authentication is OAuth are reported as unsupported in this version rather than being treated as API-key providers.