@omdp/dsh-key-fallback 3.0.0 → 3.1.0

package/README.md

@@ -1,48 +1,75 @@
 # @omdp/dsh-key-fallback
 
 Multi-key API key pool with automatic rotation for DeepSeek Harness. Sits between the LLM adapter and the credential store:
-the plugin picks a key from the per-provider pool and writes it into the provider's credential reference before each request;
-on a retryable error (`AUTH` / `QUOTA_EXCEEDED` / `RATE_LIMIT` by default), it advances to the next key in the chain and returns `{ kind: 'retry' }` so the agent loop retries with the rotated key.
+the plugin picks a key from the per-provider pool and pre-writes it into the provider's credential reference before each request;
+on a configured trigger error it marks the failed key (cooldown) and advances to the next key in the chain, then lets DSH's own
+`dsh-llm-retry` decide whether/when to retry (the plugin never re-sends on its own).
 
-This is **v3** (work in progress; not yet feature-frozen). v3 supersedes v1 (which stored keys in plaintext under `~/.dsh/settings.yaml#keyFallback.providers`);
-v1 still ships in this profile (it registers the `key-fallback` settings namespace), so v3 deliberately uses a different namespace (`key-fallback-pools`) to avoid the registration conflict.
+Current version is **v6** (`3.1.0`).
 
-## What's in v3
+## What v6 offers
 
-- **Independent settings page**: **Settings → API Key 回退** — a top-level section, not a card under plugin config.
-- **Provider dropdown** (the chooser merges `ctx.llm.listProviders()` and `ctx.llm.listConfigurableProviders()`).
-- **Add / remove keys via the UI** (write-only; the value is never read back into the page).
-- **Per-provider enabled switch** (disable = the pool is bypassed entirely).
-- **Environment key in the pool**: the runtime composes `effectiveKeys = [envKey, ...userKeys]`. The env key is the first entry, marked `[环境来源]` in the UI, and cannot be edited or deleted; the environment remains the source of truth for it.
-- **Manual key selector** (pool-level dropdown "当前使用") — pick any key (including the env one) to lock the pool to that key. Failures do **not** auto-rotate while a key is locked; select "自动轮换" to return to cursor-based rotation.
-- **Rotation on retryable errors** (`agent/request-error` waterfall) with cooldown tracking per key.
-- **Pre-write on every request** (`agent/request` waterfall) so the LLM adapter always reads the pool key, not the original env value.
-- **v1 → v3 one-shot migration** on first launch: reads `~/.dsh/settings.yaml#keyFallback.providers`, writes the plaintext keys into the credential store, copies the pool metadata into the new namespace, and marks `keyFallbackMigratedToV3: true` to prevent re-running. The v1 plaintext block is **left in place** (deleting it would touch a file DSH is actively using; verify the v3 UI looks right, then delete manually).
+**Settings → API Key 回退** — a top-level settings page with a redesigned UI:
 
-## What's still in flight / not done
+- **Pool cards** with status dots, badges, enable switch, per-pool cooldown display and a "重置冷却" reset button.
+- **轮转触发码 (rotation triggers) are now configurable and actually enforced**: click chips to select which error codes
+  cause rotation (`QUOTA` / `AUTH` / `RATE_LIMIT` / `TIMEOUT` / `TRANSPORT` / `SERVER`), or add a custom code. The default set is a
+  superset of the old hard-coded behavior, so existing pools behave identically unless you change it.
+- **真正当前使用的 key 显示**: the page shows which key is actually being used right now (derived from the last value written to the
+  provider's env), instead of a truncated hash.
+- **短 ref 命名**: new keys are named `key_fallback_<provider>_key1`, `key_fallback_<provider>_key2`, … so the UI shows clean short
+  names (`key1`, `key2`…) instead of long ref strings. Existing long refs are migrated once, automatically and idempotently.
+- **明文揭示**: every key row has an eye toggle (`👁` / `🙈`) that fetches and shows the real value via `GET /keys/plain` (only for
+  keys owned by that pool, or the pool's env key).
+- **环境密钥可编辑**: the pool's env key (`AGNES_API_KEY` etc.) can be updated right in the page when it's backed by the writable
+  credential file. If it is supplied by the launching environment (read-only), the UI says so and refuses to edit.
+- **Per-key controls**: rename/update value, set the "失败后→" next key (nextRef), lock the pool to a specific key ("设为当前"),
+  delete a key (the env key is not deletable).
+- **Pool-level "锁定"**: lock the pool to a specific key or return to 自动轮换 (cursor-based).
 
-- **Cooldown / failure status rendering in the UI**: host returns `failCount / cooldownUntil / cooldownRemainingMs / lastErrorAt / lastErrorMsg / status: 'cooling' | 'healthy'` per key and a pool-level `cursor`; the client currently shows the basic list and the env-key badge but does not yet render the cooldown progress bars. Pending — I stopped here for a stable checkpoint after you said "收尾" (wrap up).
-- **v1 and v3 running side by side**: v1's host still loads alongside v3 and both touch the same `~/.dsh/.credentials.yaml`. This is the root cause of the credential-file lock contention you hit while editing model config. To eliminate it: uninstall v1 (remove the dep from `~/.dsh/profiles/web/package.json` and delete `node_modules/@omdp/dsh-key-fallback` so only v3 remains). **Until you do, behavior is undefined under concurrent writes.**
-- **DSH-side bundle caching**: the browser keeps old client bundles by `rev=` hash. The settings-page fix you saw (label-as-function contract) only lands after a DSH restart that re-hashes the plugin. Use Ctrl+Shift+R if a page shows stale UI.
+## Rotation semantics
+
+- **pick**: respects `useKeyRef` lock first (but a cooling locked key is skipped so the pool never deadlocks on a bad key), otherwise
+  cursor round-robin over live keys.
+- **fail** (`agent/request-error`, registered `prepend` so it runs before `dsh-llm-retry`): only when the error matches the pool's
+  `rotateOn` (code / status mapping / message keyword). Marks the failed key with a fixed `cooldownMs` (no exponential backoff), then
+  switches to `nextRef` if configured, else the next live key.
+- **re-send** is left entirely to DSH's `dsh-llm-retry` with the user's own retry policy; this plugin only switches the key and writes
+  config/env. `ABORTED` (user cancel) never triggers rotation.
+
+## Diagnostics
+
+- The client POSTs runtime exceptions to `POST /dsh-key-fallback/diag`.
+- `GET /dsh-key-fallback/diag` returns the in-memory buffer (last 200 entries) as JSON.
 
 ## Install
 
 ```sh
-# 1) from a local checkout (no publish required)
+# from a local checkout (no publish required)
 dsh plugin --profile web add link:D:/WorkSpace/omdp/dsh-key-fallback
 # or from npm
 dsh plugin --profile web add @omdp/dsh-key-fallback
 
-# 2) restart DSH
-
-# 3) open Settings → API Key 回退
+# restart DSH, then open Settings → API Key 回退
 ```
 
-## Diagnostics (built in for v3, not for v1)
+> Note: this profile currently installs the package from npm (`^3.x`) into
+> `~/.dsh/profiles/web/node_modules/@omdp/dsh-key-fallback`; copying updated `lib/index.js` + `lib/client.js` there and restarting DSH
+> picks up v6.
+
+## HTTP API (host)
 
-- The client wires `window.addEventListener('error' / 'unhandledrejection')` to POST every runtime exception to `POST /dsh-key-fallback/diag`.
-- The host keeps the last 50 reports in memory.
-- `GET /dsh-key-fallback/diag` returns the buffer as JSON. Use this to see what's actually breaking in the browser (instead of reading minified DSH bundles).
+| Method | Path | Purpose |
+| --- | --- | --- |
+| GET | `/dsh-key-fallback/pools` | list pools with live status, activeRef, env writability, per-key status |
+| POST | `/dsh-key-fallback/pools` | create/update pool (enabled, cooldownMs, rotateOn, useKeyRef, …) |
+| DELETE | `/dsh-key-fallback/pools?provider=` | delete pool + all its keys |
+| POST | `/dsh-key-fallback/keys` | add key (auto short ref `key_fallback_<p>_keyN`) |
+| PATCH | `/dsh-key-fallback/keys` | update value / label / nextRef / useKeyRef (env key value = edit env) |
+| DELETE | `/dsh-key-fallback/keys?provider=&ref=` | delete key (env key refused) |
+| GET | `/dsh-key-fallback/keys/plain?provider=&ref=` | reveal real value (pool-owned keys / env key only) |
+| POST | `/dsh-key-fallback/reset` | reset cooldown state for a pool |
+| GET/POST | `/dsh-key-fallback/diag` | diagnostics buffer |
 
 ## License
 

package/lib/client.js

@@ -1,14 +1,13 @@
-// @omdp/dsh-key-fallback — Client half (v3)
+// @omdp/dsh-key-fallback — Client half (v6)
 //
 // 独立设置页「设置 → API Key 回退」：
 //  1) provider 下拉（来自 /providers：live + dormant）→ 「启用」创建池
-//  2) 每个池一张卡片：enabled 开关 / env / cooldownMs / rotateOn chips /
-//     key 链（只写输入，保存后不回读，只显示 [hidden] 占位 + 删除）
-//  3) 顶部刷新按钮 + 冷却重置
+//  2) 每个池一张卡片：enabled 开关 / env / cooldownMs / rotateOn 可点选 chips /
+//     key 链（只写输入 + 眼睛看明文 + 环境密钥可编辑）
+//  3) 顶部刷新 + 冷却重置
 //
 // 走 fetch 跟 host 通信（/dsh-key-fallback/*），视觉用 --dsw-alias-* 变量。
-//
-// ── 诊断：把渲染/运行时错误上报到 host 的 /dsh-key-fallback/diag ──
+
 function __kfReportDiag(kind, message, stack) {
   try {
     fetch('/dsh-key-fallback/diag', {
@@ -34,60 +33,80 @@ window.__ModuleLoader__.load({
     var React = require('react')
     var ce = React.createElement
 
+    // ── 常用代码 / 名称 ──
+    var ROTATE_CODES = ['QUOTA', 'AUTH', 'RATE_LIMIT', 'TIMEOUT', 'TRANSPORT', 'SERVER']
+    function codeLabel(c) {
+      return { QUOTA: '配额用尽', AUTH: '认证失败', RATE_LIMIT: '限流', TIMEOUT: '超时', TRANSPORT: '传输错误', SERVER: '服务端' }[c] || c
+    }
+
     // ── CSS（一次注入）──
     var CSS = [
-      '.kf_root{display:flex;flex-direction:column;gap:16px;padding:0 24px 28px}',
-      '.kf_head{display:flex;align-items:flex-end;justify-content:space-between;gap:12px;flex-wrap:wrap;border-bottom:1px solid var(--dsw-alias-border-l1,rgba(128,128,128,.22));padding-bottom:12px}',
-      '.kf_title{font-size:17px;font-weight:600;color:var(--dsw-alias-label-primary,#eee);margin:0}',
-      '.kf_sub{font-size:12.5px;color:var(--dsw-alias-label-secondary,#9aa);margin:4px 0 0;line-height:1.55}',
-      '.kf_card{background:var(--dsw-alias-bg-layer-1,rgba(255,255,255,.035));border:1px solid var(--dsw-alias-border-l1,rgba(128,128,128,.22));border-radius:12px;padding:14px 16px;display:flex;flex-direction:column;gap:12px}',
-      '.kf_cardHead{display:flex;align-items:center;gap:10px;flex-wrap:wrap}',
-      '.kf_name{font-weight:600;font-size:14.5px;color:var(--dsw-alias-label-primary,#eee);display:flex;align-items:center;gap:8px;flex-wrap:wrap}',
-      '.kf_badge{display:inline-flex;align-items:center;gap:4px;font-size:11px;padding:2px 9px;border-radius:999px;border:1px solid currentColor;line-height:1.6;white-space:nowrap}',
+      '.kf_root{display:flex;flex-direction:column;gap:18px;padding:0 24px 30px;max-width:980px;margin:0 auto}',
+      '.kf_head{display:flex;align-items:flex-start;justify-content:space-between;gap:14px;flex-wrap:wrap;padding-bottom:14px;border-bottom:1px solid var(--dsw-alias-border-l1,rgba(128,128,128,.2))}',
+      '.kf_title{font-size:19px;font-weight:700;color:var(--dsw-alias-label-primary,#f1f1f1);margin:0;display:flex;align-items:center;gap:10px;letter-spacing:.2px}',
+      '.kf_title .kf_dot{width:10px;height:10px;border-radius:50%;background:linear-gradient(135deg,#4ade80,#22d3ee);box-shadow:0 0 10px rgba(74,222,128,.6)}',
+      '.kf_sub{font-size:12.5px;color:var(--dsw-alias-label-secondary,#9aa);margin:6px 0 0;line-height:1.65}',
+      '.kf_headRight{display:flex;align-items:center;gap:8px;flex-wrap:wrap}',
+      '.kf_badge{display:inline-flex;align-items:center;gap:5px;font-size:11.5px;padding:3px 10px;border-radius:999px;border:1px solid currentColor;line-height:1.55;white-space:nowrap;font-weight:500}',
       '.kf_badge.muted{color:var(--dsw-alias-label-secondary,#9aa)}',
       '.kf_badge.ok{color:var(--dsw-alias-state-success-primary,#4ade80)}',
       '.kf_badge.warn{color:var(--dsw-alias-state-warn-primary,#fbbf24)}',
       '.kf_badge.brand{color:var(--dsw-alias-brand-primary,#7aa2ff);border-color:var(--dsw-alias-brand-primary,#7aa2ff)}',
       '.kf_badge.err{color:var(--dsw-alias-state-error-primary,#f87171)}',
-      '.kf_switch{position:relative;width:34px;height:20px;border-radius:999px;background:var(--dsw-alias-bg-base,rgba(0,0,0,.3));border:1px solid var(--dsw-alias-border-l2,rgba(128,128,128,.4));cursor:pointer;transition:background .15s;flex:none}',
-      '.kf_switch::after{content:"";position:absolute;top:1px;left:1px;width:16px;height:16px;border-radius:50%;background:var(--dsw-alias-label-secondary,#9aa);transition:transform .15s,background .15s}',
-      '.kf_switch.on{background:color-mix(in srgb,var(--dsw-alias-brand-primary,#5b8cff) 50%,transparent);border-color:var(--dsw-alias-brand-primary,#5b8cff)}',
-      '.kf_switch.on::after{transform:translateX(14px);background:var(--dsw-alias-brand-primary,#7aa2ff)}',
-      '.kf_btn{cursor:pointer;font:inherit;font-size:12px;padding:5px 12px;border-radius:8px;border:1px solid var(--dsw-alias-border-l2,rgba(128,128,128,.4));background:transparent;color:inherit;transition:background .12s;flex:none}',
+      '.kf_btn{cursor:pointer;font:inherit;font-size:12px;padding:6px 13px;border-radius:9px;border:1px solid var(--dsw-alias-border-l2,rgba(128,128,128,.4));background:transparent;color:inherit;transition:background .12s,border-color .12s,transform .05s;flex:none;line-height:1.5}',
       '.kf_btn:hover:not(:disabled){background:var(--dsw-alias-bg-layer-2,rgba(128,128,128,.14))}',
+      '.kf_btn:active:not(:disabled){transform:scale(.97)}',
       '.kf_btn:disabled{opacity:.45;cursor:default}',
-      '.kf_btn.primary{border:1px solid color-mix(in srgb,var(--dsw-alias-brand-primary,#5b8cff) 55%,transparent);background:color-mix(in srgb,var(--dsw-alias-brand-primary,#5b8cff) 15%,transparent);color:var(--dsw-alias-brand-primary,#7aa2ff)}',
+      '.kf_btn.primary{border:1px solid color-mix(in srgb,var(--dsw-alias-brand-primary,#5b8cff) 55%,transparent);background:color-mix(in srgb,var(--dsw-alias-brand-primary,#5b8cff) 14%,transparent);color:var(--dsw-alias-brand-primary,#7aa2ff)}',
       '.kf_btn.primary:hover:not(:disabled){background:color-mix(in srgb,var(--dsw-alias-brand-primary,#5b8cff) 26%,transparent)}',
-      '.kf_btn.danger{color:var(--dsw-alias-state-error-primary,#f87171);border-color:currentColor}',
+      '.kf_btn.danger{color:var(--dsw-alias-state-error-primary,#f87171);border-color:color-mix(in srgb,var(--dsw-alias-state-error-primary,#f87171) 55%,transparent)}',
       '.kf_btn.ghost{border-style:dashed}',
-      '.kf_form{display:grid;grid-template-columns:repeat(auto-fit,minmax(170px,1fr));gap:10px}',
-      '.kf_form label{display:flex;flex-direction:column;gap:4px;font-size:12px;color:var(--dsw-alias-label-secondary,#9aa)}',
-      '.kf_form input,.kf_form select,.kf_chips select{font:inherit;font-size:13px;padding:6px 9px;border-radius:8px;border:1px solid var(--dsw-alias-border-l2,rgba(128,128,128,.35));background:var(--dsw-alias-bg-base,rgba(0,0,0,.18));color:inherit}',
-      '.kf_form input:focus,.kf_form select:focus{outline:2px solid var(--dsw-alias-brand-primary,rgba(91,140,255,.5));outline-offset:0;border-color:transparent}',
-      '.kf_keys{display:flex;flex-direction:column;gap:6px}',
-      '.kf_keyRow{display:flex;align-items:center;gap:10px;padding:8px 10px;border:1px solid var(--dsw-alias-border-l1,rgba(128,128,128,.18));border-radius:8px;background:var(--dsw-alias-bg-base,rgba(0,0,0,.16));flex-wrap:wrap}',
-      '.kf_keyLabel{font-weight:500;font-size:12.5px;color:var(--dsw-alias-label-primary,#eee);min-width:120px;flex:0 0 auto;display:flex;gap:8px;align-items:center}',
-      '.kf_keyRef{font-size:11px;color:var(--dsw-alias-label-secondary,#9aa);font-family:ui-monospace,Menlo,Consolas,monospace;opacity:.7}',
-      '.kf_inputSecret{flex:1;min-width:200px;font:inherit;font-family:ui-monospace,Menlo,Consolas,monospace;font-size:12.5px;padding:7px 10px;border-radius:8px;border:1px solid var(--dsw-alias-border-l2,rgba(128,128,128,.35));background:var(--dsw-alias-bg-base,rgba(0,0,0,.25));color:inherit}',
-      '.kf_inputSecret:focus{outline:2px solid var(--dsw-alias-brand-primary,rgba(91,140,255,.5));border-color:transparent}',
-      '.kf_hiddenBadge{font-size:11.5px;color:var(--dsw-alias-label-secondary,#9aa);font-family:ui-monospace,Menlo,Consolas,monospace;padding:7px 10px;border:1px dashed var(--dsw-alias-border-l2,rgba(128,128,128,.3));border-radius:8px;flex:1;min-width:200px;text-align:center}',
-      '.kf_chips{display:flex;gap:6px;flex-wrap:wrap}',
-      '.kf_chip{cursor:pointer;font:inherit;font-size:11.5px;padding:3px 11px;border-radius:999px;border:1px solid var(--dsw-alias-border-l2,rgba(128,128,128,.35));background:transparent;color:var(--dsw-alias-label-secondary,#9aa);transition:all .12s}',
+      '.kf_card{background:linear-gradient(180deg,var(--dsw-alias-bg-layer-1,rgba(255,255,255,.045)),rgba(255,255,255,.015));border:1px solid var(--dsw-alias-border-l1,rgba(128,128,128,.2));border-radius:14px;padding:16px 18px;display:flex;flex-direction:column;gap:14px;box-shadow:0 1px 0 rgba(255,255,255,.03) inset}',
+      '.kf_cardHead{display:flex;align-items:center;gap:10px;flex-wrap:wrap}',
+      '.kf_avatar{width:32px;height:32px;border-radius:9px;display:flex;align-items:center;justify-content:center;font-size:14px;font-weight:700;color:#0b1220;background:linear-gradient(135deg,#7aa2ff,#22d3ee);flex:none;text-transform:uppercase}',
+      '.kf_name{font-weight:700;font-size:14.5px;color:var(--dsw-alias-label-primary,#f1f1f1);display:flex;align-items:center;gap:8px;flex-wrap:wrap}',
+      '.kf_switch{position:relative;width:36px;height:21px;border-radius:999px;background:var(--dsw-alias-bg-base,rgba(0,0,0,.3));border:1px solid var(--dsw-alias-border-l2,rgba(128,128,128,.4));cursor:pointer;transition:background .15s;flex:none}',
+      '.kf_switch::after{content:"";position:absolute;top:1px;left:1px;width:17px;height:17px;border-radius:50%;background:var(--dsw-alias-label-secondary,#9aa);transition:transform .15s,background .15s}',
+      '.kf_switch.on{background:color-mix(in srgb,var(--dsw-alias-state-success-primary,#4ade80) 45%,transparent);border-color:var(--dsw-alias-state-success-primary,#4ade80)}',
+      '.kf_switch.on::after{transform:translateX(15px);background:#4ade80}',
+      '.kf_meta{display:flex;gap:18px;flex-wrap:wrap;align-items:center;font-size:12.5px;color:var(--dsw-alias-label-secondary,#9aa);background:var(--dsw-alias-bg-base,rgba(0,0,0,.14));border:1px solid var(--dsw-alias-border-l1,rgba(128,128,128,.14));border-radius:10px;padding:9px 12px}',
+      '.kf_meta b{color:var(--dsw-alias-label-primary,#e8e8e8);font-weight:600}',
+      '.kf_activePill{display:inline-flex;align-items:center;gap:6px;font-weight:600;color:var(--dsw-alias-state-success-primary,#4ade80)}',
+      '.kf_activePill::before{content:"";width:8px;height:8px;border-radius:50%;background:#4ade80;box-shadow:0 0 8px rgba(74,222,128,.8);animation:kf_pulse 1.8s ease-in-out infinite}',
+      '@keyframes kf_pulse{0%,100%{opacity:1}50%{opacity:.35}}',
+      '.kf_sel{font:inherit;font-size:12px;background:var(--dsw-alias-bg-base,rgba(0,0,0,.18));color:inherit;border:1px solid var(--dsw-alias-border-l2,rgba(128,128,128,.35));border-radius:8px;padding:4px 8px}',
+      '.kf_section{font-size:11px;font-weight:700;letter-spacing:.6px;text-transform:uppercase;color:var(--dsw-alias-label-tertiary,#778);display:flex;align-items:center;gap:8px}',
+      '.kf_section::after{content:"";flex:1;height:1px;background:var(--dsw-alias-border-l1,rgba(128,128,128,.15))}',
+      '.kf_chips{display:flex;gap:7px;flex-wrap:wrap;align-items:center}',
+      '.kf_chip{cursor:pointer;font:inherit;font-size:11.5px;padding:4px 12px;border-radius:999px;border:1px solid var(--dsw-alias-border-l2,rgba(128,128,128,.35));background:transparent;color:var(--dsw-alias-label-secondary,#9aa);transition:all .12s;display:inline-flex;align-items:center;gap:5px}',
       '.kf_chip:hover{color:var(--dsw-alias-label-primary,#ddd);border-color:var(--dsw-alias-brand-primary,#5b8cff)}',
-      '.kf_chip.active{background:color-mix(in srgb,var(--dsw-alias-brand-primary,#5b8cff) 26%,transparent);color:var(--dsw-alias-brand-primary,#7aa2ff);border-color:color-mix(in srgb,var(--dsw-alias-brand-primary,#5b8cff) 60%,transparent)}',
-      '.kf_err{color:var(--dsw-alias-state-error-primary,#f87171);font-size:12.5px;line-height:1.5}',
-      '.kf_status{font-size:11px;padding:1px 8px;border-radius:999px;line-height:1.7;white-space:nowrap;flex:none}',
-      '.kf_status.live{color:var(--dsw-alias-state-success-primary,#4ade80)}',
-      '.kf_status.cooling{color:var(--dsw-alias-state-warn-primary,#fbbf24)}',
-      '.kf_status.cooldown{color:var(--dsw-alias-state-error-primary,#f87171)}',
-      '.kf_nextRow{display:flex;align-items:center;gap:6px;font-size:12px;color:var(--dsw-alias-label-secondary,#9aa)}',
-      '.kf_nextSel{font:inherit;font-size:12px;background:transparent;color:inherit;border:1px solid var(--dsw-alias-border-l2,rgba(128,128,128,.4));border-radius:6px;padding:2px 6px}',
-      '.kf_ok{color:var(--dsw-alias-state-success-primary,#4ade80);font-size:12.5px;line-height:1.5}',
-      '.kf_empty{font-size:13px;color:var(--dsw-alias-label-secondary,#888);padding:16px 4px;text-align:center}',
-      '.kf_addrow{display:flex;gap:10px;align-items:flex-end;flex-wrap:wrap;background:var(--dsw-alias-bg-layer-1,rgba(255,255,255,.035));border:1px dashed var(--dsw-alias-border-l2,rgba(128,128,128,.4));border-radius:12px;padding:12px 14px}',
+      '.kf_chip.on{background:color-mix(in srgb,var(--dsw-alias-state-success-primary,#4ade80) 18%,transparent);color:var(--dsw-alias-state-success-primary,#4ade80);border-color:color-mix(in srgb,var(--dsw-alias-state-success-primary,#4ade80) 55%,transparent)}',
+      '.kf_chip.on::before{content:"✓";font-size:10px}',
+      '.kf_customRow{display:flex;gap:8px;align-items:center;flex-wrap:wrap}',
+      '.kf_input{font:inherit;font-size:12.5px;padding:6px 10px;border-radius:8px;border:1px solid var(--dsw-alias-border-l2,rgba(128,128,128,.35));background:var(--dsw-alias-bg-base,rgba(0,0,0,.2));color:inherit;outline:none}',
+      '.kf_input:focus{border-color:var(--dsw-alias-brand-primary,#5b8cff);box-shadow:0 0 0 2px color-mix(in srgb,var(--dsw-alias-brand-primary,#5b8cff) 25%,transparent)}',
+      '.kf_keys{display:flex;flex-direction:column;gap:7px}',
+      '.kf_keyRow{display:flex;align-items:center;gap:10px;padding:9px 12px;border:1px solid var(--dsw-alias-border-l1,rgba(128,128,128,.16));border-radius:10px;background:var(--dsw-alias-bg-base,rgba(0,0,0,.14));flex-wrap:wrap;transition:border-color .12s}',
+      '.kf_keyRow.active{border-color:color-mix(in srgb,var(--dsw-alias-state-success-primary,#4ade80) 55%,transparent)}',
+      '.kf_statusDot{width:8px;height:8px;border-radius:50%;flex:none}',
+      '.kf_statusDot.live{background:#4ade80}',
+      '.kf_statusDot.cooling{background:#fbbf24;box-shadow:0 0 6px rgba(251,191,36,.6)}',
+      '.kf_statusDot.recovered{background:#38bdf8}',
+      '.kf_keyName{font-weight:600;font-size:12.5px;color:var(--dsw-alias-label-primary,#e8e8e8);min-width:56px;display:flex;align-items:center;gap:6px}',
+      '.kf_keyRef{font-size:10.5px;color:var(--dsw-alias-label-secondary,#9aa);font-family:ui-monospace,Menlo,Consolas,monospace;opacity:.75;max-width:180px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}',
+      '.kf_keyVal{flex:1;min-width:170px;font-family:ui-monospace,Menlo,Consolas,monospace;font-size:12px;padding:6px 10px;border-radius:8px;border:1px dashed var(--dsw-alias-border-l2,rgba(128,128,128,.3));background:var(--dsw-alias-bg-base,rgba(0,0,0,.22));color:inherit}',
+      '.kf_keyActions{display:flex;gap:6px;align-items:center;flex-wrap:wrap}',
+      '.kf_err{color:var(--dsw-alias-state-error-primary,#f87171);font-size:12px;line-height:1.5}',
+      '.kf_ok{color:var(--dsw-alias-state-success-primary,#4ade80);font-size:12px;line-height:1.5}',
+      '.kf_empty{font-size:13px;color:var(--dsw-alias-label-secondary,#888);padding:18px 4px;text-align:center}',
+      '.kf_addrow{display:flex;gap:10px;align-items:flex-end;flex-wrap:wrap;background:var(--dsw-alias-bg-layer-1,rgba(255,255,255,.035));border:1px dashed var(--dsw-alias-border-l2,rgba(128,128,128,.4));border-radius:12px;padding:13px 15px}',
       '.kf_addrow label{display:flex;flex-direction:column;gap:5px;font-size:12px;color:var(--dsw-alias-label-secondary,#9aa);min-width:240px;flex:1}',
       '.kf_spinner{display:inline-block;width:12px;height:12px;border:2px solid var(--dsw-alias-border-l2,rgba(128,128,128,.4));border-top-color:var(--dsw-alias-brand-primary,#5b8cff);border-radius:50%;animation:kf_spin .7s linear infinite;vertical-align:-2px;margin-right:6px}',
       '@keyframes kf_spin{to{transform:rotate(360deg)}}',
+      '.kf_iconBtn{cursor:pointer;font:inherit;font-size:12px;width:28px;height:28px;border-radius:8px;border:1px solid var(--dsw-alias-border-l2,rgba(128,128,128,.3));background:transparent;color:var(--dsw-alias-label-secondary,#9aa);display:inline-flex;align-items:center;justify-content:center;transition:all .12s;flex:none;line-height:1}',
+      '.kf_iconBtn:hover:not(:disabled){color:var(--dsw-alias-label-primary,#eee);border-color:var(--dsw-alias-brand-primary,#5b8cff);background:var(--dsw-alias-bg-layer-2,rgba(128,128,128,.12))}',
+      '.kf_iconBtn:disabled{opacity:.4;cursor:default}',
+      '.kf_envNote{font-size:11.5px;color:var(--dsw-alias-label-secondary,#9aa);border:1px dashed var(--dsw-alias-border-l2,rgba(128,128,128,.28));border-radius:8px;padding:6px 10px;flex:1;min-width:150px}',
     ].join('')
     if (typeof document !== 'undefined' && !document.querySelector('style[data-plugin-css="@omdp/dsh-key-fallback"]')) {
       var tag = document.createElement('style')
@@ -97,8 +116,6 @@ window.__ModuleLoader__.load({
     }
 
     function api(path, options) {
-      // 先进入 Promise 微任务：JSON.stringify、AbortController、fetch 的同步异常
-      // 也必须落到统一错误结果，不能让按钮卡在"保存中"。
       return Promise.resolve().then(function () {
         var url = '/dsh-key-fallback' + path
         var opts = Object.assign({ method: 'GET' }, options || {})
@@ -106,15 +123,12 @@ window.__ModuleLoader__.load({
           opts.body = JSON.stringify(opts.body)
           opts.headers = Object.assign({ 'Content-Type': 'application/json' }, opts.headers || {})
         }
-        // 8s 超时：避免请求挂起导致 UI 一直"保存中"
         var ctrl = (typeof AbortController === 'function') ? new AbortController() : null
         var timer = null
         if (ctrl) {
           opts.signal = ctrl.signal
           timer = setTimeout(function () { ctrl.abort() }, 8000)
         }
-        // Promise.race：即使宿主 fetch 忽略 AbortSignal，也保证 8s 内 settle，
-        // 避免保存/删除永久卡在“保存中”。
         var timeoutP = new Promise(function (_, reject) {
           var t = setTimeout(function () { reject(new Error('请求超时')) }, 8000)
           if (typeof t === 'object' && t && typeof t.unref === 'function') t.unref()
@@ -127,28 +141,34 @@ window.__ModuleLoader__.load({
       })
     }
 
-    // ── 单个 key 行：编辑态显示 password input，未编辑显示 [hidden] 占位 ──
+    // ── 单个 key 行：状态点 / 短名 / ref / 明文揭示 / 更新 / 删除 ──
     function KeyRow(props) {
       var k = props.entry
+      var isEnv = props.source === 'env'
       var editing = React.useState(false)
       var isEditing = editing[0]
       var setEditing = editing[1]
       var val = React.useState('')
       var value = val[0]
       var setValue = val[1]
+      var reveal = React.useState(false)
+      var isRevealed = reveal[0]
+      var setRevealed = reveal[1]
+      var plain = React.useState('')
+      var plainText = plain[0]
+      var setPlain = plain[1]
       var busy = React.useState(false)
       var isBusy = busy[0]
       var setBusy = busy[1]
       var err = React.useState('')
       var setErr = err[1]
+      var revealing = React.useState(false)
+      var isRevealing = revealing[0]
+      var setRevealing = revealing[1]
+
       function save() {
         if (!value) { setErr('请输入 key'); return }
         setBusy(true); setErr('')
-        try {
-          __kfReportDiag('save', 'PATCH start provider=' + props.provider + ' ref=')
-        } catch (e) {}
-        // 额外包一层 Promise：即使 api 被宿主替换或请求构造同步抛错，
-        // 也一定会进入 catch，按钮不会永久停在"保存中"。
         Promise.resolve().then(function () {
           return api('/keys', { method: 'PATCH', body: { provider: props.provider, ref: k.ref, value: value, label: k.label || '' } })
         })
@@ -156,55 +176,77 @@ window.__ModuleLoader__.load({
             if (!r.ok) { setErr((r.body && r.body.error) || ('HTTP ' + r.status)); return }
             setValue(''); setEditing(false); props.onChanged()
           })
-          .catch(function (e) {
-            setErr((e && e.message) || String(e))
-          })
-          .then(function () {
-            // 成功、HTTP 错误、请求异常全部收口 busy 状态。
-            setBusy(false)
+          .catch(function (e) { setErr((e && e.message) || String(e)) })
+          .then(function () { setBusy(false) })
+      }
+      function toggleReveal() {
+        if (isRevealed) { setRevealed(false); setPlain(''); return }
+        setRevealing(true); setErr('')
+        api('/keys/plain?provider=' + encodeURIComponent(props.provider) + '&ref=' + encodeURIComponent(k.ref))
+          .then(function (r) {
+            setRevealing(false)
+            if (!r.ok) { setErr((r.body && r.body.error) || ('HTTP ' + r.status)); return }
+            setPlain(r.body.value || ''); setRevealed(true)
           })
+          .catch(function (e) { setRevealing(false); setErr(String(e && e.message || e)) })
       }
-      var isEnv = props.source === 'env'
       var st = k.status || (isEnv ? 'live' : '')
-      var nowMs = Date.now()
       var cooling = k.cooldownRemainingMs > 0
-      var stLabel = isEnv ? '' : (st === 'cooling' || cooling) ? ('冷却中 ' + Math.ceil((k.cooldownRemainingMs || 0) / 1000) + 's') : (st === 'recovered' ? '已恢复' : (st === 'cooldown' ? '冷却' : '正常'))
-      return ce('div', { className: 'kf_keyRow' },
-        ce('div', { className: 'kf_keyLabel' },
-          k.label ? k.label : (k.ref || '').slice(-8),
-          isEnv ? ce('span', { className: 'kf_badge brand' }, '[环境来源]') : null,
-          isEnv || !stLabel ? null : ce('span', { className: 'kf_status ' + ((st === 'cooling' || cooling) ? 'cooling' : 'live') }, stLabel),
-          ce('span', { className: 'kf_keyRef' }, k.ref)
+      var dotCls = isEnv ? 'live' : (cooling || st === 'cooling') ? 'cooling' : (st === 'recovered' ? 'recovered' : 'live')
+      var stLabel = isEnv ? '环境' : (cooling ? '冷却 ' + Math.ceil((k.cooldownRemainingMs || 0) / 1000) + 's' : (st === 'recovered' ? '已恢复' : '正常'))
+      return ce('div', { className: 'kf_keyRow' + (k.active ? ' active' : '') },
+        ce('span', { className: 'kf_statusDot ' + dotCls, title: stLabel }),
+        ce('span', { className: 'kf_keyName' },
+          k.name || (k.ref || '').slice(-8),
+          k.active ? ce('span', { className: 'kf_badge ok', style: { padding: '1px 7px', fontSize: 10.5 } }, '当前') : null,
         ),
+        ce('span', { className: 'kf_keyRef', title: k.ref }, k.ref),
         isEnv
-          ? ce('span', { className: 'kf_hiddenBadge', style: { flex: 1 } }, '来自环境配置（不可编辑/删除；可设为当前、参与轮换）')
+          ? ce('span', { className: 'kf_envNote' },
+              props.pool.envSource === 'env' && props.pool.envWritable === false
+                ? '由启动环境提供（只读）'
+                : '环境来源 · 可编辑/参与轮换',
+            )
           : isEditing
-            ? ce('div', null,
-                ce('input', { className: 'kf_inputSecret', type: 'text', autoComplete: 'off', spellCheck: false, placeholder: '粘贴新 key（只写，不回读）', value: value, onChange: function (e) { setValue(e.target.value) } }),
+            ? ce('input', { className: 'kf_input kf_keyVal', type: 'text', autoComplete: 'off', spellCheck: false, placeholder: '粘贴新 key（只写，不回读）', value: value, onChange: function (e) { setValue(e.target.value) } })
+            : ce('span', { className: 'kf_keyVal' },
+                isRevealed ? plainText || '(空)' : '[hidden] 已保存',
+              ),
+        ce('div', { className: 'kf_keyActions' },
+          isEnv || !stLabel ? null : ce('span', { className: 'kf_badge ' + ((cooling || st === 'cooling') ? 'warn' : (st === 'recovered' ? 'brand' : 'ok')), style: { padding: '1px 8px', fontSize: 10.5 } }, stLabel),
+          ce('button', { className: 'kf_iconBtn', title: isRevealed ? '隐藏明文' : '显示明文', disabled: isRevealing, onClick: toggleReveal }, isRevealing ? '…' : (isRevealed ? '🙈' : '👁')),
+          isEnv ? null : (isEditing
+            ? ce('span', null,
                 ce('button', { className: 'kf_btn primary', disabled: isBusy, onClick: save }, isBusy ? '保存…' : '保存'),
                 ce('button', { className: 'kf_btn', onClick: function () { setEditing(false); setValue(''); setErr('') } }, '取消'),
               )
-            : ce('div', null,
-                ce('span', { className: 'kf_hiddenBadge' }, '[hidden] 已保存（点击「更新」可改）'),
-                ce('button', { className: 'kf_btn', onClick: function () { setEditing(true) } }, '更新'),
-              ),
-        ce('label', { className: 'kf_nextRow' },
-            '失败后切换到',
-            ce('select', { className: 'kf_nextSel', value: k.nextRef || '', onChange: function (e) { api('/keys', { method: 'PATCH', body: { provider: props.provider, ref: k.ref, nextRef: e.target.value } }).then(function () { props.onChanged() }).catch(function () {}) } },
-              ce('option', { value: '' }, '自动（顺序循环）'),
-              (props.allRefs || []).filter(function (r) { return r !== k.ref }).map(function (r) { return ce('option', { key: r, value: r }, r.slice(-12)) }),
+            : ce('button', { className: 'kf_btn', onClick: function () { setEditing(true) } }, '更新')),
+          ce('label', { className: 'kf_meta', style: { padding: '2px 8px', gap: 5, fontSize: 11.5, background: 'transparent', border: 'none' } },
+            '失败后→',
+            ce('select', { className: 'kf_sel', value: k.nextRef || '', onChange: function (e) { api('/keys', { method: 'PATCH', body: { provider: props.provider, ref: k.ref, nextRef: e.target.value } }).then(function () { props.onChanged() }).catch(function () {}) } },
+              ce('option', { value: '' }, '自动'),
+              (props.allRefs || []).filter(function (r) { return r !== k.ref }).map(function (r) { return ce('option', { key: r, value: r }, displayShort(r, props.allNames)) }),
             ),
           ),
-                props.currentRef === k.ref ? null : ce('button', { className: 'kf_btn primary', onClick: function () {
-                  api('/keys', { method: 'PATCH', body: { provider: props.provider, ref: k.ref, useKeyRef: k.ref } })
-                    .then(function () { props.onChanged() }).catch(function (e) { setErr((e && e.message) || String(e)) })
-                } }, '设为当前'),
-                isEnv ? null : ce('button', { className: 'kf_btn danger', onClick: function () { props.onDelete() } }, '删除'),
-        isEnv || !k.lastErrorMsg ? null : ce('span', { className: 'kf_err', title: k.lastErrorMsg }, '上次错误: ' + k.lastErrorMsg.slice(0, 60)),
+          props.currentRef === k.ref ? null : ce('button', { className: 'kf_btn primary', onClick: function () {
+            api('/pools', { method: 'POST', body: { provider: props.provider, enabled: props.pool.enabled, env: props.pool.env, cooldownMs: props.pool.cooldownMs, rotateOn: props.pool.rotateOn, useKeyRef: k.ref } })
+              .then(function (r) { if (!r.ok) { setErr((r.body && r.body.error) || ('HTTP ' + r.status)); return } props.onChanged() })
+              .catch(function (e) { setErr(String(e && e.message || e)) })
+          } }, '设为当前'),
+          isEnv ? null : ce('button', { className: 'kf_btn danger', onClick: function () { props.onDelete() } }, '删除'),
+        ),
+        !k.lastErrorMsg ? null : ce('span', { className: 'kf_err', title: k.lastErrorMsg }, '上次错误: ' + k.lastErrorMsg.slice(0, 50)),
         err ? ce('span', { className: 'kf_err' }, err) : null,
       )
     }
 
+    function displayShort(ref, names) {
+      if (names && names[ref]) return names[ref]
+      var m = /_key(\d+)$/.exec(ref || '')
+      if (m) return 'key' + m[1]
+      return (ref || '').slice(-8)
+    }
+
     // ── 单个 provider 池卡片 ──
     function PoolCard(props) {
       var pool = props.pool
@@ -214,16 +256,31 @@ window.__ModuleLoader__.load({
       var errSet = React.useState('')
       var err = errSet[0]
       var setErr = errSet[1]
-      var okSet = React.useState('')
-      var ok = okSet[0]
-      var setOk = okSet[1]
       var newKey = React.useState('')
       var newKeyVal = newKey[0]
       var setNewKey = newKey[1]
       var addBusy = React.useState(false)
       var isAddBusy = addBusy[0]
       var setAddBusy = addBusy[1]
+      var envEdit = React.useState('')
+      var envEditVal = envEdit[0]
+      var setEnvEdit = envEdit[1]
+      var envBusy = React.useState(false)
+      var isEnvBusy = envBusy[0]
+      var setEnvBusy = envBusy[1]
+      var customCode = React.useState('')
+      var customCodeVal = customCode[0]
+      var setCustomCode = customCode[1]
 
+      function savePool(patch) {
+        var body = Object.assign({ provider: pool.provider, enabled: pool.enabled, env: pool.env, cooldownMs: pool.cooldownMs, rotateOn: pool.rotateOn }, patch || {})
+        api('/pools', { method: 'POST', body: body })
+          .then(function (r) {
+            if (!r.ok) { setErr((r.body && r.body.error) || ('HTTP ' + r.status)); return }
+            props.onChanged()
+          })
+          .catch(function (e) { setErr(String(e && e.message || e)) })
+      }
       function toggle() {
         if (busy) return
         setBusy(true); setErr('')
@@ -248,60 +305,116 @@ window.__ModuleLoader__.load({
           .then(function (r) { if (r.ok) props.onChanged(); else setErr((r.body && r.body.error) || ('HTTP ' + r.status)) })
           .catch(function (e) { setErr(String(e && e.message || e)) })
       }
-      function setUseKey(ref) {
-        api('/pools', { method: 'POST', body: { provider: pool.provider, enabled: pool.enabled, env: pool.env, cooldownMs: pool.cooldownMs, rotateOn: pool.rotateOn, useKeyRef: ref } })
-          .then(function (r) { if (!r.ok) { setErr((r.body && r.body.error) || ('HTTP ' + r.status)); return } props.onChanged() })
-          .catch(function (e) { setErr(String(e && e.message || e)) })
-      }
       function deletePool() {
         if (!confirm('确认删除「' + pool.provider + '」池（会清掉所有 key）？')) return
         api('/pools?provider=' + encodeURIComponent(pool.provider), { method: 'DELETE' })
           .then(function (r) { if (r.ok) props.onChanged(); else setErr((r.body && r.body.error) || ('HTTP ' + r.status)) })
           .catch(function (e) { setErr(String(e && e.message || e)) })
       }
+      function resetCooldown() {
+        api('/reset', { method: 'POST', body: { provider: pool.provider } })
+          .then(function (r) { if (r.ok) props.onChanged(); else setErr((r.body && r.body.error) || ('HTTP ' + r.status)) })
+          .catch(function (e) { setErr(String(e && e.message || e)) })
+      }
+      function toggleCode(code) {
+        var next = (pool.rotateOn || []).slice()
+        var i = next.indexOf(code)
+        if (i >= 0) next.splice(i, 1)
+        else next.push(code)
+        if (next.length === 0) next = ROTATE_CODES.slice()
+        savePool({ rotateOn: next })
+      }
+      function addCustomCode() {
+        var c = String(customCodeVal || '').trim().toUpperCase().replace(/\s+/g, '_')
+        if (!c) return
+        var next = (pool.rotateOn || []).slice()
+        if (next.indexOf(c) < 0) next.push(c)
+        setCustomCode('')
+        savePool({ rotateOn: next })
+      }
+      function saveEnvKey() {
+        if (!envEditVal) { setErr('请输入环境密钥'); return }
+        setEnvBusy(true); setErr('')
+        api('/keys', { method: 'PATCH', body: { provider: pool.provider, ref: pool.env, value: envEditVal } })
+          .then(function (r) {
+            setEnvBusy(false)
+            if (!r.ok) { setErr((r.body && r.body.error) || ('HTTP ' + r.status)); return }
+            setEnvEdit(''); props.onChanged()
+          })
+          .catch(function (e) { setEnvBusy(false); setErr(String(e && e.message || e)) })
+      }
+      var keys = Array.isArray(pool.keys) ? pool.keys : []
+      var userKeys = keys.filter(function (k) { return k.ref !== pool.env })
+      var allRefs = keys.map(function (x) { return x.ref })
+      var allNames = {}
+      keys.forEach(function (k) { allNames[k.ref] = k.name })
+
       return ce('div', { className: 'kf_card' },
         ce('div', { className: 'kf_cardHead' },
+          ce('span', { className: 'kf_avatar' }, (pool.displayName || pool.provider || '?').slice(0, 1)),
           ce('div', { className: 'kf_name' },
             pool.displayName || pool.provider,
             ce('span', { className: 'kf_badge ' + (pool.enabled ? 'ok' : 'muted') }, pool.enabled ? '启用' : '停用'),
             ce('span', { className: 'kf_badge muted' }, 'env: ' + pool.env),
           ),
           ce('div', { style: { flex: 1 } }),
+          ce('button', { className: 'kf_btn', title: '重置冷却', onClick: resetCooldown }, '↺ 重置冷却'),
           ce('div', { className: 'kf_switch' + (pool.enabled ? ' on' : ''), onClick: toggle, title: pool.enabled ? '停用' : '启用' }),
           ce('button', { className: 'kf_btn danger', disabled: busy, onClick: deletePool }, '删除池'),
         ),
-        ce('div', { style: { fontSize: 12, color: 'var(--dsw-alias-label-secondary,#9aa)', display: 'flex', gap: 14, flexWrap: 'wrap', alignItems: 'center' } },
-          ce('span', null, 'key 数: ' + (Array.isArray(pool.keys) ? pool.keys.length : 0)),
-          pool.currentRef ? ce('span', { style: { color: 'var(--dsw-alias-brand-primary,#7aa2ff)' } }, '当前用: ' + pool.currentRef.slice(-12)) : null,
-          ce('span', null, 'cooldown: ' + (pool.cooldownMs || 0) + ' ms'),
+        ce('div', { className: 'kf_meta' },
+          ce('span', null, 'key 数: ', ce('b', null, keys.length)),
+          ce('span', null, 'cooldown: ', ce('b', null, pool.cooldownMs + ' ms')),
+          ce('span', null, '当前使用: ', pool.activeRef && pool.activeName
+            ? ce('span', { className: 'kf_activePill' }, pool.activeName)
+            : ce('span', { className: 'kf_badge muted', style: { padding: '1px 8px', fontSize: 10.5 } }, '尚未使用')),
           ce('label', { style: { display: 'flex', alignItems: 'center', gap: 6 } },
-            ce('span', null, '当前使用:'),
-            ce('select', { value: pool.useKeyRef || '_auto', onChange: function (e) { var v = e.target.value; if (v === '_auto') setUseKey(''); else setUseKey(v) } },
+            ce('span', null, '锁定:'),
+            ce('select', { className: 'kf_sel', value: pool.useKeyRef || '_auto', onChange: function (e) { var v = e.target.value; savePool({ useKeyRef: (v === '_auto' ? '' : v) }) } },
               ce('option', { value: '_auto' }, '自动轮换'),
-              (Array.isArray(pool.keys) ? pool.keys : []).map(function (k) {
-                return ce('option', { value: k.ref, key: k.ref }, (k.ref === pool.env ? '[环境] ' : '') + (k.label || k.ref.slice(-8)))
-              }),
+              (keys).map(function (k) { return ce('option', { value: k.ref, key: k.ref }, (k.ref === pool.env ? '[环境] ' : '') + (k.name || k.ref.slice(-8))) }),
             ),
           ),
         ),
+        ce('div', { className: 'kf_section' }, '轮换触发码'),
         ce('div', { className: 'kf_chips' },
-          ce('span', { style: { fontSize: 11.5, color: 'var(--dsw-alias-label-secondary,#9aa)', alignSelf: 'center' } }, '轮换触发码:'),
-          ['QUOTA_EXCEEDED', 'AUTH', 'RATE_LIMIT'].map(function (code) {
-            return ce('span', { key: code, className: 'kf_chip' + ((pool.rotateOn || []).includes(code) ? ' active' : '') }, code)
+          ROTATE_CODES.map(function (code) {
+            var on = (pool.rotateOn || []).indexOf(code) >= 0
+            return ce('button', { key: code, className: 'kf_chip' + (on ? ' on' : ''), title: codeLabel(code), onClick: function () { toggleCode(code) } }, codeLabel(code))
+          }),
+        ),
+        ce('div', { className: 'kf_customRow' },
+          ce('input', { className: 'kf_input', style: { width: 130 }, placeholder: '自定义错误码', value: customCodeVal, onChange: function (e) { setCustomCode(e.target.value) }, onKeyDown: function (e) { if (e.key === 'Enter') addCustomCode() } }),
+          ce('button', { className: 'kf_btn ghost', onClick: addCustomCode }, '+ 添加'),
+          (pool.rotateOn || []).filter(function (c) { return ROTATE_CODES.indexOf(c) < 0 }).map(function (c) {
+            return ce('span', { key: c, className: 'kf_chip on' }, c)
           }),
+          ce('span', { style: { fontSize: 11, color: 'var(--dsw-alias-label-secondary,#9aa)' } }, '勾选=失败后轮换；取消=不轮换'),
         ),
-        ((Array.isArray(pool.keys) ? pool.keys : [])).length === 0
+        ce('div', { className: 'kf_section' }, '密钥链'),
+        keys.length === 0
           ? ce('div', { className: 'kf_empty' }, '还没有 key。在下方粘贴第一个。')
-          : ce('div', { className: 'kf_keys' }, (Array.isArray(pool.keys) ? pool.keys : []).map(function (k) {
-                return ce(KeyRow, { key: k.ref, entry: k, provider: pool.provider, allRefs: (Array.isArray(pool.keys) ? pool.keys : []).map(function (x) { return x.ref }), onDelete: (k.ref === pool.env) ? null : function () { deleteKey(k.ref) }, onChanged: props.onChanged, source: (k.ref === pool.env) ? 'env' : 'user', currentRef: pool.currentRef || '' })
+          : ce('div', { className: 'kf_keys' },
+              keys.map(function (k) {
+                return ce(KeyRow, { key: k.ref, entry: k, provider: pool.provider, pool: pool, allRefs: allRefs, allNames: allNames, onDelete: (k.ref === pool.env) ? null : function () { deleteKey(k.ref) }, onChanged: props.onChanged, source: (k.ref === pool.env) ? 'env' : 'user', currentRef: pool.activeRef || '' })
               }),
             ),
-        ce('div', { style: { display: 'flex', gap: 10, alignItems: 'center', flexWrap: 'wrap' } },
-          ce('input', { className: 'kf_inputSecret', style: { flex: 1, minWidth: 220 }, type: 'text', autoComplete: 'off', spellCheck: false, placeholder: '粘贴新 API key 后点添加（只写，保存后不回读）', value: newKeyVal, onChange: function (e) { setNewKey(e.target.value) } }),
-          ce('button', { className: 'kf_btn primary', disabled: isAddBusy, onClick: addKey }, isAddBusy ? '添加中…' : '添加 key'),
+        true
+          ? ce('div', { className: 'kf_customRow', style: { background: 'var(--dsw-alias-bg-base,rgba(0,0,0,.1))', padding: '8px 10px', borderRadius: 10 } },
+              ce('span', { style: { fontSize: 11.5, color: 'var(--dsw-alias-label-secondary,#9aa)', flex: '0 0 auto' } }, '更新环境密钥 (' + pool.env + '):'),
+              pool.envWritable === false
+                ? ce('span', { className: 'kf_envNote', style: { border: 'none', padding: 0 } }, '由启动环境提供，只读（请在启动 DSH 的终端里修改）')
+                : ce('span', { style: { display: 'flex', flex: 1, gap: 8, flexWrap: 'wrap', minWidth: 220 } },
+                    ce('input', { className: 'kf_input kf_keyVal', type: 'text', autoComplete: 'off', spellCheck: false, placeholder: '粘贴新环境密钥（只写，不回读）', value: envEditVal, onChange: function (e) { setEnvEdit(e.target.value) }, onKeyDown: function (e) { if (e.key === 'Enter') saveEnvKey() } }),
+                    ce('button', { className: 'kf_btn primary', disabled: isEnvBusy, onClick: saveEnvKey }, isEnvBusy ? '保存…' : '保存'),
+                  ),
+            )
+          : null,
+        ce('div', { className: 'kf_customRow' },
+          ce('input', { className: 'kf_input kf_keyVal', type: 'text', autoComplete: 'off', spellCheck: false, placeholder: '粘贴新 API key 后点添加（只写，保存后不回读）', value: newKeyVal, onChange: function (e) { setNewKey(e.target.value) }, onKeyDown: function (e) { if (e.key === 'Enter') addKey() } }),
+          ce('button', { className: 'kf_btn primary', disabled: isAddBusy, onClick: addKey }, isAddBusy ? '添加中…' : '+ 添加 key'),
         ),
         err ? ce('div', { className: 'kf_err' }, err) : null,
-        ok ? ce('div', { className: 'kf_ok' }, ok) : null,
       )
     }
 
@@ -322,16 +435,21 @@ window.__ModuleLoader__.load({
       var addingSet = React.useState(false)
       var adding = addingSet[0]
       var setAdding = addingSet[1]
+      var refreshing = React.useState(false)
+      var isRefreshing = refreshing[0]
+      var setRefreshing = refreshing[1]
 
       function refresh() {
+        setRefreshing(true)
         Promise.all([api('/pools'), api('/providers')])
           .then(function (rs) {
+            setRefreshing(false)
             if (!rs[0].ok) { setErr((rs[0].body && rs[0].body.error) || ('HTTP ' + rs[0].status)); return }
             setPools(rs[0].body.pools || [])
             var d = rs[1] && rs[1].body || {}; setDir((d && typeof d === 'object') ? d : {})
             setErr('')
           })
-          .catch(function (e) { setErr(String(e && e.message || e)) })
+          .catch(function (e) { setRefreshing(false); setErr(String(e && e.message || e)) })
       }
       React.useEffect(function () { refresh() }, [])
 
@@ -357,17 +475,20 @@ window.__ModuleLoader__.load({
       return ce('div', { className: 'kf_root' },
         ce('div', { className: 'kf_head' },
           ce('div', null,
-            ce('h2', { className: 'kf_title' }, 'API Key 回退'),
+            ce('h2', { className: 'kf_title' }, ce('span', { className: 'kf_dot' }), 'API Key 回退'),
             ce('p', { className: 'kf_sub' }, '为 LLM provider 维护多个 API key，请求失败时自动换下一个 key 重试。key 只写入本机 .credentials.yaml，不进设置文件。'),
           ),
-          (pools || []).length === 0 ? ce('span', { className: 'kf_badge warn' }, '尚未启用') : ce('span', { className: 'kf_badge ok' }, (pools || []).length + ' 个池'),
+          ce('div', { className: 'kf_headRight' },
+            (pools || []).length === 0 ? ce('span', { className: 'kf_badge warn' }, '尚未启用') : ce('span', { className: 'kf_badge ok' }, (pools || []).length + ' 个池'),
+            ce('button', { className: 'kf_btn', disabled: isRefreshing, onClick: refresh }, isRefreshing ? '刷新…' : '↻ 刷新'),
+          ),
         ),
         ce('div', { className: 'kf_addrow' },
           adding
-            ? ce('div', null,
+            ? ce('div', { style: { display: 'flex', gap: 10, alignItems: 'flex-end', flexWrap: 'wrap', width: '100%' } },
                 ce('label', null,
                   ce('span', null, '选择 LLM provider'),
-                  ce('select', { value: pick, onChange: function (e) { setPick(e.target.value) } },
+                  ce('select', { className: 'kf_sel', style: { fontSize: 13, padding: '7px 10px' }, value: pick, onChange: function (e) { setPick(e.target.value) } },
                     ce('option', { value: '' }, '— 选择 —'),
                     all.map(function (p) { return ce('option', { value: p.id, key: p.id }, p.name + '（' + p.id + ' · ' + p.hint + '）') }),
                   ),
@@ -402,4 +523,4 @@ window.__ModuleLoader__.load({
     exports.inject = ['slots']
     return module.exports
   },
-})
+})

package/lib/index.js

@@ -1,12 +1,18 @@
-// @omdp/dsh-key-fallback — Host half (ESM, v5)
+// @omdp/dsh-key-fallback — Host half (ESM, v6)
 //
-// v5 = v1 核心功能全量恢复（预写 + 失败标记 + 顺序配置）+ v4 的 CRUD 与极简配置：
-//   - 配置来源 = ~/.dsh/settings.yaml 的 key-fallback.providers[*]
-//   - agent/request 预写：每次请求把池当前 key 写入 env + credentials（v1 行为）
-//   - agent/request-error：标记失败的 key（failCount/cooldown/status/lastError）并按 nextRef 顺序切下一个
-//   - 每个 key 可配置 nextRef（失败后跳转到指定 key），UI 可直接配置轮换顺序
-//   - GET /pools 返回每个 key 的实时状态（status/failCount/cooldownRemaining/lastError），UI 展示
-import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+// v6 = v5 全量功能 + 用户要求的修复与增强：
+//   - 轮转触发码真正生效：agent/request-error 按池的 rotateOn 判断（可配置、chips 可点选），
+//     数字 status 与消息关键字按所选触发码映射；默认集=旧行为超集（无回归）。
+//   - 「当前使用」显示修复：GET /pools 返回 activeRef（= 最近一次预写进 process.env 的 key），
+//     POST/PATCH 改 useKeyRef 后同步刷新内存池 + env，UI 立刻显示真正在用的 key。
+//   - key 短命名：新增 key 自动命名为 key_fallback_<provider>_key<N>；
+//     旧的长 ref 在首次加载时一次性迁移（refsCompacted 标记，幂等，先 set 新 ref 再 unset 旧 ref）。
+//   - 明文揭示：GET /keys/plain?provider=&ref= 返回真实值（走 rawResolve，绕过池 wrap）。
+//   - 环境密钥可编辑：PATCH /keys 的 ref 等于池 env 时改写 .credentials.yaml（describe 可写才允许）。
+//   - 隐藏 bug 修复：PATCH /keys 解构 useKeyRef（此前「设为当前」静默失效）；
+//     warmPools 不再二次调用 pickKey；GET /pools 返回真实 label；POST /diag 接受；
+//     resolve wrap 尊重 pool.enabled。
+import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { load as loadYaml, dump as dumpYaml } from 'js-yaml'
@@ -43,7 +49,7 @@ const profileSchema = z.object({
   env: z.string().pattern(/^[A-Za-z_][A-Za-z0-9_]*$/).default('NINEROUTER_API_KEY'),
   cooldownMs: z.number().min(0).default(30000),
   enabled: z.boolean().default(true),
-  rotateOn: z.array(z.string()).default(['QUOTA_EXCEEDED', 'AUTH', 'RATE_LIMIT']),
+  rotateOn: z.array(z.string()).default(['QUOTA', 'AUTH', 'RATE_LIMIT', 'TIMEOUT', 'TRANSPORT', 'SERVER']),
   keyRefs: z.array(z.object({
     ref: z.string().pattern(/^[A-Za-z_][A-Za-z0-9_]*$/),
     label: z.string().default(''),
@@ -52,6 +58,7 @@ const profileSchema = z.object({
   })).default([]),
   displayName: z.string().default(''),
   useKeyRef: z.string().default(''),
+  refsCompacted: z.boolean().default(false),
 })
 
 function readSettings() {
@@ -87,10 +94,74 @@ function sendJson(res, code, data) {
   } catch (e) { try { res.end() } catch {} }
 }
 
-const RETRYABLE_CODES = ['RATE_LIMIT', 'AUTH', 'QUOTA_EXCEEDED', 'TIMEOUT', 'TRANSPORT']
+// ── 轮转触发语义（v6：rotateOn 真正生效）──
+// 默认集 = 旧 RETRYABLE_CODES 行为超集（QUOTA_EXCEEDED 规范化成规范码 QUOTA）；
+// 用户保存什么就严格按什么判断——不做「等于旧三元组就提升成超集」的魔法，
+// 否则用户精确配置的三个码保存后刷新会变回六个，配置不生效。
+const DEFAULT_ROTATE_ON = ['QUOTA', 'AUTH', 'RATE_LIMIT', 'TIMEOUT', 'TRANSPORT', 'SERVER']
+function canonicalCode(c) {
+  const s = String(c || '').toUpperCase()
+  if (s === 'QUOTA_EXCEEDED' || s === 'QUOTA') return 'QUOTA'
+  return s
+}
+// 读取池配置时规范化 rotateOn；空数组/未配置 → 返回默认超集。
+function effectiveRotateOn(stored) {
+  const norm = (Array.isArray(stored) ? stored : []).map(canonicalCode).filter(Boolean)
+  if (norm.length === 0) return [...DEFAULT_ROTATE_ON]
+  return norm
+}
+const CODE_KEYWORDS = {
+  QUOTA: /quota|insufficient|balance|credit|budget|exhaust|billing|limit exceeded/i,
+  AUTH: /401|403|auth|credential|denied|forbidden|invalid key|api key|unauthor|token/i,
+  RATE_LIMIT: /429|rate|limit|throttl|too many|try again later|concurr|busy/i,
+  TIMEOUT: /timeout|timed ?out|deadline|gateway timeout/i,
+  TRANSPORT: /transport|network|econn|socket|eai|dns|fetch failed|connection|closed|reset|unreachable/i,
+  SERVER: /5\d\d|server error|internal|unavailable|502|503|504|bad gateway|overload/i,
+  EMPTY_RESPONSE: /empty response|no content|empty reply/i,
+}
+function shouldRotate(pool, code, rawMsg, status) {
+  const triggers = effectiveRotateOn(pool.cfg.rotateOn)
+  if (triggers.includes(code)) return true
+  const s = Number(status)
+  if (Number.isFinite(s) && s >= 400 && s <= 599) {
+    const mapped = s === 429 ? 'RATE_LIMIT' : (s === 401 || s === 403 ? 'AUTH' : (s === 402 ? 'QUOTA' : (s >= 500 ? 'SERVER' : 'AUTH')))
+    if (triggers.includes(mapped)) return true
+  }
+  for (const t of triggers) {
+    const rx = CODE_KEYWORDS[t]
+    if (rx && rx.test(rawMsg)) return true
+  }
+  return false
+}
+
+// ── key 短命名 ──
+function safeProvider(provider) {
+  return String(provider || '').replace(/[^A-Za-z0-9_]/g, '_')
+}
+function isShortRef(ref) {
+  return /^key_fallback_[A-Za-z0-9_]+_key\d+$/.test(ref)
+}
+function shortRefOf(provider, n) {
+  return 'key_fallback_' + safeProvider(provider) + '_key' + n
+}
+// 为新增 key 分配下一个空闲短 ref（key1、key2…）
+function nextKeyRef(provider, keyRefs) {
+  const used = new Set((Array.isArray(keyRefs) ? keyRefs : []).map((e) => e && e.ref).filter(Boolean))
+  let n = 1
+  while (used.has(shortRefOf(provider, n))) n++
+  return shortRefOf(provider, n)
+}
+// 从 ref 派生显示名（label 优先，否则 key_fallback_x_keyN → keyN）
+function displayNameOf(entry) {
+  if (entry && entry.label) return entry.label
+  const ref = (entry && entry.ref) || ''
+  const m = /_key(\d+)$/.exec(ref)
+  if (m) return 'key' + m[1]
+  return ref
+}
 
 export function apply(ctx) {
-  try { ctx.logger.info('key-fallback: v5 host apply() starting (config = settings.yaml)') } catch (e) {}
+  try { ctx.logger.info('key-fallback: v6 host apply() starting (config = settings.yaml)') } catch (e) {}
   const diagLog = []
   const diag = (kind, msg) => { try { diagLog.push({ kind, msg: String(msg).slice(0, 300), at: Date.now() }); if (diagLog.length > 200) diagLog.splice(0, diagLog.length - 200) } catch (e) {} }
   diag('apply', 'host loaded')
@@ -105,9 +176,9 @@ export function apply(ctx) {
       try { result = await rawResolve(ref) } catch (e) { result = undefined }
       const refName = String(ref || '')
       const pool = poolsByEnv.get(refName)
-      if (pool && pool.currentRef) {
+      if (pool && pool.cfg && pool.cfg.enabled !== false && pool.currentRef) {
         const cur = pool.keyValues.find((k) => k.ref === pool.currentRef)
-        if (cur) { diag('resolve', 'pool-hit ' + refName + ' -> ' + cur.ref.slice(-12)); return { value: cur.value, source: 'pool' } }
+        if (cur) { diag('resolve', 'pool-hit ' + refName + ' -> ' + cur.ref); return { value: cur.value, source: 'pool' } }
       }
       return result
     }
@@ -120,6 +191,8 @@ export function apply(ctx) {
   function readPools() {
     const cfg = readSettings()
     const providers = (cfg && cfg.providers) || {}
+    // 每次全量重建 env 索引：删除池/改 env 后不得残留旧映射（否则 wrap 会命中已删池）
+    poolsByEnv.clear()
     for (const name in providers) {
       if (!pools.has(name)) pools.set(name, { cfg: providers[name], keyValues: [], cursor: 0, currentRef: '' })
       else pools.get(name).cfg = providers[name]
@@ -129,11 +202,59 @@ export function apply(ctx) {
     for (const name of [...pools.keys()]) if (!providers[name]) pools.delete(name)
   }
 
-  async function resolvePoolKeys(pool) {
+  // 一次性迁移旧长 ref → 短 ref（key_fallback_x_keyN）。幂等：迁移后长 ref 不存在即自然短路。
+  // 顺序：先 set 新 ref（从旧 ref 读值）→ 改 settings → 再 unset 旧 ref；任一步失败即中止，保留旧状态可重试。
+  // 注意：不依赖 refsCompacted 短路——空池创建会先置标记，若之后外部导入旧格式长 ref 仍必须迁移。
+  async function compactRefs(provider, prof) {
+    const entries = (prof.keyRefs || []).map((e) => {
+      if (typeof e === 'string') return { ref: e, label: '', createdAt: 0, nextRef: '' }
+      return { ref: e.ref || '', label: e.label || '', createdAt: e.createdAt || 0, nextRef: e.nextRef || '' }
+    })
+    const longOnes = entries.filter((e) => e.ref && e.ref.startsWith('key_fallback_') && !isShortRef(e.ref))
+    if (longOnes.length === 0) return false
+    const oldToNew = new Map()
+    const used = new Set(entries.map((e) => e.ref).filter(isShortRef))
+    let n = 1
+    for (const e of longOnes) {
+      while (used.has(shortRefOf(provider, n))) n++
+      oldToNew.set(e.ref, shortRefOf(provider, n))
+      used.add(shortRefOf(provider, n))
+      n++
+    }
+    // 1) 写新 ref（读旧值）
+    for (const [oldRef, newRef] of oldToNew) {
+      let hit
+      try { hit = rawResolve ? await rawResolve(credentialRef(oldRef)) : await ctx.credentials.resolve(credentialRef(oldRef)) } catch (e) { hit = undefined }
+      if (!hit || !hit.value) return false
+      try { backupFile(CRED_FILE, 'credentials'); await ctx.credentials.set(credentialRef(newRef), hit.value) } catch (e) { return false }
+    }
+    // 2) 更新 settings 引用
+    for (const e of entries) {
+      if (e.ref && oldToNew.has(e.ref)) e.ref = oldToNew.get(e.ref)
+      if (e.nextRef && oldToNew.has(e.nextRef)) e.nextRef = oldToNew.get(e.nextRef)
+    }
+    if (prof.useKeyRef && oldToNew.has(prof.useKeyRef)) prof.useKeyRef = oldToNew.get(prof.useKeyRef)
+    prof.keyRefs = entries
+    prof.refsCompacted = true
+    // 3) unset 旧 ref（best-effort）
+    for (const oldRef of oldToNew.keys()) { try { await ctx.credentials.unset(credentialRef(oldRef)) } catch (e) {} }
+    return true
+  }
+
+  async function resolvePoolKeys(pool, providerName) {
+    // 迁移旧 ref（一次），成功后持久化 settings —— 用与 pool.cfg 同一对象的 settings 块
+    const cfg = readSettings()
+    const providers = cfg.providers || {}
+    // 让 pool.cfg 指向本次解析的树（之前 readPools 解析的是旧树，改它无法写回）
+    if (providers[providerName]) pool.cfg = providers[providerName]
+    let compacted = false
+    if (pool.cfg) { try { compacted = await compactRefs(providerName, pool.cfg) } catch (e) { compacted = false } }
+    if (compacted) writeSettings(cfg)
     // 保留已有状态（failCount/cooldown/lastError），避免重建时丢状态
     const prev = new Map(pool.keyValues.map((k) => [k.ref, k]))
     pool.keyValues = []
-    for (const entry of (pool.cfg.keyRefs || [])) {
+    const entries = (pool.cfg.keyRefs || []).map((e) => typeof e === 'string' ? { ref: e, label: '', createdAt: 0, nextRef: '' } : e)
+    for (const entry of entries) {
       const ref = (entry && typeof entry === 'object') ? entry.ref : entry
       const nextRef = (entry && typeof entry === 'object' && entry.nextRef) ? entry.nextRef : ''
       if (!ref) continue
@@ -142,7 +263,7 @@ export function apply(ctx) {
         if (hit && hit.value) {
           const old = prev.get(ref) || {}
           pool.keyValues.push({
-            ref, value: hit.value, source: 'user',
+            ref, value: hit.value, source: 'user', label: (entry && entry.label) || '',
             nextRef,
             failCount: old.failCount || 0,
             cooldownUntil: old.cooldownUntil || 0,
@@ -164,7 +285,7 @@ export function apply(ctx) {
           const found = pool.keyValues.find((k) => k.ref === envRef)
           if (!found) {
             pool.keyValues.push({
-              ref: envRef, value: hit.value, source: 'env',
+              ref: envRef, value: hit.value, source: 'env', label: '',
               nextRef: '',
               failCount: old.failCount || 0,
               cooldownUntil: old.cooldownUntil || 0,
@@ -182,7 +303,7 @@ export function apply(ctx) {
     readPools()
     const pool = pools.get(provider)
     if (!pool) return undefined
-    await resolvePoolKeys(pool)
+    await resolvePoolKeys(pool, provider)
     return pool
   }
 
@@ -235,6 +356,15 @@ export function apply(ctx) {
     return undefined
   }
 
+  // 把 useKeyRef 选择立即落到内存池 + process.env，让「当前使用」立刻真实
+  function applySelection(pool, ref) {
+    if (!pool || !ref) return
+    const kv = pool.keyValues.find((k) => k.ref === ref)
+    if (!kv) return
+    pool.currentRef = ref
+    try { process.env[pool.cfg.env] = kv.value } catch (e) {}
+  }
+
   // ── 预写：v1 同款 —— 全局 agent/request（DSH 全局收得到这个 waterfall），
   //    每次请求同步 buildPools() 重读 settings，选 key，同步写 process.env，
   //    credentials.set fire-and-forget（不 await 阻塞 waterfall）。
@@ -243,11 +373,13 @@ export function apply(ctx) {
     for (const name of pools.keys()) {
       const pool = pools.get(name)
       if (pool) {
-        try { await resolvePoolKeys(pool) } catch (e) {}
-        // 预热时确定初始 currentRef：useKeyRef 锁定优先，否则 pickKey
+        try { await resolvePoolKeys(pool, name) } catch (e) {}
+        // 预热时确定初始 currentRef：useKeyRef 锁定优先，否则 pickKey（只调一次）
         if (pool.keyValues.length > 0 && !pool.currentRef) {
           const locked = pool.cfg.useKeyRef && pool.keyValues.find((k) => k.ref === pool.cfg.useKeyRef)
-          pool.currentRef = (locked && locked.ref) || (pickKey(pool) && pickKey(pool).ref) || pool.keyValues[0].ref
+          let picked = null
+          if (!(locked && locked.ref)) picked = pickKey(pool)
+          pool.currentRef = (locked && locked.ref) || (picked && picked.ref) || pool.keyValues[0].ref
         }
       }
     }
@@ -255,7 +387,6 @@ export function apply(ctx) {
 
   // 启动时预热 pools（resolve keyValues，供同步预写 pickKey 用）
   try { warmPools().catch(() => {}) } catch (e) {}
-  // 每次 settings 变化也刷新 —— webServer 路由里已有调用，这里兜底周期不设
 
   ctx.on('agent/request', (payload, next) => {
     // next() 是 async，但我们要同步写 env —— 用 then 链，立即返回 p 不阻塞 waterfall
@@ -275,7 +406,7 @@ export function apply(ctx) {
         pool.currentRef = key.ref
         diag('agent/request', 'PICK ' + key.ref + ' env=' + pool.cfg.env)
         try { process.env[pool.cfg.env] = key.value } catch (e) {}
-        try { backupFile(CRED_FILE, 'credentials'); ctx.credentials.set(credentialRef(pool.cfg.env), key.value).catch(() => {}) } catch (e) {}
+        try { backupFile(CRED_FILE, 'credentials') } catch (e) {}
       } catch (e) {}
       return config
     }).catch((e) => {})
@@ -286,12 +417,13 @@ export function apply(ctx) {
   ctx.on('agent/request-error', async (payload, next) => {
     const code = String((payload && payload.failure && payload.failure.code) || (payload && payload.code) || '')
     const rawMsg = String((payload && payload.failure && payload.failure.message) || (payload && payload.message) || '')
+    const status = (payload && payload.failure && payload.failure.status) || (payload && payload.status)
     const provider = (payload && payload.provider) || ''
-    const isRetryable = RETRYABLE_CODES.includes(code) || /^[45]\d\d$/.test(code) || /rate|limit|quota|exhaust|throttl|429|timeout|timed?out|auth|credential|denied|forbidden|unavailable|busy|key/i.test(rawMsg)
-    if (!provider || !isRetryable) return next()
-    diag('request-error', 'provider=' + provider + ' code=' + code)
+    if (!provider) return next()
+    diag('request-error', 'provider=' + provider + ' code=' + code + ' status=' + status)
     const pool = await getPool(provider)
-    if (!pool || pool.keyValues.length === 0) return next()
+    if (!pool || pool.keyValues.length === 0 || pool.cfg.enabled === false) return next()
+    if (!shouldRotate(pool, canonicalCode(code), rawMsg, status)) return next()
     let curRef = pool.currentRef
     if (!curRef) {
       const envCur = process.env[pool.cfg.env]
@@ -302,7 +434,7 @@ export function apply(ctx) {
     // 失败后优先按 nextRef 轮换（用户配置的顺序）；useKeyRef 只决定初始选择
     const nextKey = nextKeyFor(pool, curRef)
     if (nextKey) {
-      try { await backupFile(CRED_FILE, 'credentials'); ctx.credentials.set(credentialRef(pool.cfg.env), nextKey.value); process.env[pool.cfg.env] = nextKey.value } catch (e) {}
+      try { await backupFile(CRED_FILE, 'credentials'); process.env[pool.cfg.env] = nextKey.value } catch (e) {}
       pool.currentRef = nextKey.ref
     } else {
       // 无 nextRef 可选时：若 useKeyRef 锁定 key 仍 live 则退回它，否则放弃
@@ -329,7 +461,11 @@ export function apply(ctx) {
           req.on('error', reject)
         })
 
-        if (path === 'diag' && req.method === 'GET') {
+        if (path === 'diag' && (req.method === 'GET' || req.method === 'POST')) {
+          if (req.method === 'POST') {
+            try { const b = await readBody(); diag(b.kind || 'client', b.message || b.msg || '') } catch (e) {}
+            return sendJson(res, 200, { ok: true })
+          }
           return sendJson(res, 200, { diag: diagLog })
         }
 
@@ -355,13 +491,32 @@ export function apply(ctx) {
             const out = []
             readPools()
             for (const [name, pool] of pools) {
-              await resolvePoolKeys(pool)
+              await resolvePoolKeys(pool, name)
               const now = Date.now()
+              // 真正当前使用的 key：最近一次预写进 process.env 的值
+              let activeRef = ''
+              if (pool.cfg.enabled !== false) {
+                const envCur = process.env[pool.cfg.env]
+                if (envCur) { const m = pool.keyValues.find((k) => k.value === envCur); if (m) activeRef = m.ref }
+                if (!activeRef && pool.currentRef) activeRef = pool.currentRef
+              }
+              // 环境密钥可写性（描述：文件=可写，启动环境=只读）
+              let envWritable = null
+              let envSource = ''
+              try {
+                if (ctx.credentials.describe) {
+                  const d = await ctx.credentials.describe(credentialRef(pool.cfg.env))
+                  envWritable = d ? d.writable !== false : null
+                  envSource = d ? (d.source || '') : ''
+                }
+              } catch (e) {}
               const keys = pool.keyValues.map((k) => {
                 const cooling = (k.cooldownUntil || 0) > now
+                const entry = (pool.cfg.keyRefs || []).find((x) => (x && x.ref) === k.ref) || {}
                 return {
                   ref: k.ref,
-                  label: '',
+                  name: displayNameOf({ label: k.label || entry.label, ref: k.ref }),
+                  label: k.label || entry.label || '',
                   source: k.source,
                   nextRef: k.nextRef || '',
                   status: cooling ? 'cooling' : (k.failCount ? 'recovered' : 'live'),
@@ -370,6 +525,7 @@ export function apply(ctx) {
                   cooldownRemainingMs: cooling ? (k.cooldownUntil - now) : 0,
                   lastErrorAt: k.lastErrorAt || 0,
                   lastErrorMsg: k.lastErrorMsg || '',
+                  active: k.ref === activeRef,
                 }
               })
               out.push({
@@ -378,10 +534,14 @@ export function apply(ctx) {
                 env: pool.cfg.env,
                 cooldownMs: pool.cfg.cooldownMs,
                 enabled: pool.cfg.enabled,
-                rotateOn: pool.cfg.rotateOn || [],
+                rotateOn: effectiveRotateOn(pool.cfg.rotateOn),
                 useKeyRef: pool.cfg.useKeyRef || '',
                 currentRef: pool.currentRef || '',
+                activeRef: activeRef,
+                activeName: activeRef ? (keys.find((k) => k.ref === activeRef) || {}).name || activeRef : '',
                 envKeyValue: pool.envKeyValue ? mask(pool.envKeyValue) : '',
+                envWritable: envWritable,
+                envSource: envSource,
                 keys: keys,
               })
             }
@@ -400,18 +560,29 @@ export function apply(ctx) {
               env: envName,
               enabled: enabled !== false,
               cooldownMs: Number.isFinite(cooldownMs) && cooldownMs >= 0 ? cooldownMs : (cur.cooldownMs ?? 30000),
-              rotateOn: Array.isArray(rotateOn) && rotateOn.length > 0 ? rotateOn : (cur.rotateOn || ['QUOTA_EXCEEDED', 'AUTH', 'RATE_LIMIT']),
+              rotateOn: Array.isArray(rotateOn) && rotateOn.length > 0 ? rotateOn.map(canonicalCode).filter(Boolean) : effectiveRotateOn(cur.rotateOn),
               keyRefs: (cur.keyRefs || []).map((x) => {
                 if (typeof x === 'string') return { ref: x, label: '', createdAt: 0, nextRef: '' }
                 return { ref: x.ref, label: x.label || '', createdAt: x.createdAt || 0, nextRef: x.nextRef || '' }
               }),
               displayName: (typeof displayName === 'string' && displayName) ? displayName : (cur.displayName || provider),
               useKeyRef: (typeof useKeyRef === 'string') ? useKeyRef : (cur.useKeyRef || ''),
+              refsCompacted: cur.refsCompacted === true,
             }
             let validated
             try { validated = profileSchema(upd) } catch (e) { return sendJson(res, 400, { error: 'invalid profile: ' + (e && e.message || e) }) }
             cfg.providers[provider] = validated
             writeSettings(cfg)
+            // 同步内存池 + env，让「当前使用」立刻真实
+            try {
+              const pool = await getPool(provider)
+              if (pool) {
+                if (validated.useKeyRef) applySelection(pool, validated.useKeyRef)
+                else if (pool.currentRef && !pool.keyValues.find((k) => k.ref === pool.currentRef && isLive(k))) {
+                  const pk = pickKey(pool); if (pk) { pool.currentRef = pk.ref; try { process.env[pool.cfg.env] = pk.value } catch (e) {} }
+                }
+              }
+            } catch (e) {}
             return sendJson(res, 200, { ok: true, pool: validated })
           }
           if (req.method === 'DELETE') {
@@ -423,6 +594,7 @@ export function apply(ctx) {
             for (const k of (prof.keyRefs || [])) { try { backupFile(CRED_FILE, 'credentials'); await ctx.credentials.unset(credentialRef(k.ref || k)) } catch (e) {} }
             delete cfg.providers[provider]
             writeSettings(cfg)
+            pools.delete(provider)
             return sendJson(res, 200, { ok: true })
           }
           return sendJson(res, 405, { error: 'method not allowed' })
@@ -437,28 +609,49 @@ export function apply(ctx) {
             const cfg = readSettings()
             if (!cfg.providers || !cfg.providers[provider]) return sendJson(res, 404, { error: 'pool not found' })
             const prof = cfg.providers[provider]
-            const newRef = 'key_fallback_' + provider + '_' + Date.now().toString(36) + '_' + Math.floor(Math.random() * 0xffffffff).toString(36)
+            const newRef = nextKeyRef(provider, prof.keyRefs || [])
             try { backupFile(CRED_FILE, 'credentials'); await ctx.credentials.set(credentialRef(newRef), value) } catch (e) { return sendJson(res, 500, { error: 'credentials write failed' }) }
             const newEntry = { ref: newRef, label: (typeof label === 'string' && label) ? label : '', createdAt: Date.now(), nextRef: '' }
             prof.keyRefs = [...(prof.keyRefs || []), newEntry]
             writeSettings(cfg)
+            // 刷新内存池，让新 key 立即可参与轮换（幂等；已 compacted 则快速返回）
+            try { await getPool(provider) } catch (e) {}
             return sendJson(res, 200, { ok: true, key: newEntry, valueMask: mask(value) })
           }
           if (req.method === 'PATCH') {
             const body = await readBody()
-            const { provider, ref, value, label, nextRef } = body || {}
+            const { provider, ref, value, label, nextRef, useKeyRef } = body || {}
             if (typeof provider !== 'string' || !provider || typeof ref !== 'string' || !ref) return sendJson(res, 400, { error: 'provider & ref required' })
             const cfg = readSettings()
             const prof = cfg.providers && cfg.providers[provider]
             if (!prof) return sendJson(res, 404, { error: 'pool not found' })
             const entry = (prof.keyRefs || []).find((k) => k.ref === ref)
-            if (!entry) return sendJson(res, 404, { error: 'key not found' })
+            const isEnvKey = ref === prof.env
+            if (!entry && !isEnvKey) return sendJson(res, 404, { error: 'key not found' })
             if (typeof value === 'string' && value) {
-              try { backupFile(CRED_FILE, 'credentials'); await ctx.credentials.set(credentialRef(ref), value) } catch (e) { return sendJson(res, 500, { error: 'credentials write failed' }) }
+              // 环境密钥：允许改写 .credentials.yaml（describe 可写才允许；启动环境提供=只读）
+              if (isEnvKey) {
+                let writable = null
+                try { if (ctx.credentials.describe) { const d = await ctx.credentials.describe(credentialRef(ref)); writable = d ? d.writable !== false : null } } catch (e) {}
+                if (writable === false) return sendJson(res, 400, { error: '该环境密钥由启动环境提供（只读）；请改启动 DSH 的终端环境变量' })
+              }
+              try { backupFile(CRED_FILE, 'credentials'); await ctx.credentials.set(credentialRef(ref), value) } catch (e) { return sendJson(res, 500, { error: 'credentials write failed: ' + ((e && e.message) || e) }) }
+              // 同步内存池 + env
+              try {
+                const pool = pools.get(provider)
+                if (pool) {
+                  const kv = pool.keyValues.find((k) => k.ref === ref)
+                  if (kv) kv.value = value
+                  if (isEnvKey) pool.envKeyValue = value
+                }
+              } catch (e) {}
+            }
+            if (typeof label === 'string') { if (entry) entry.label = label }
+            if (typeof nextRef === 'string') { if (entry) entry.nextRef = nextRef }
+            if (typeof useKeyRef === 'string') {
+              prof.useKeyRef = useKeyRef
+              try { const pool = await getPool(provider); if (pool) applySelection(pool, useKeyRef) } catch (e) {}
             }
-            if (typeof label === 'string') entry.label = label
-            if (typeof nextRef === 'string') entry.nextRef = nextRef
-            if (typeof useKeyRef === 'string') prof.useKeyRef = useKeyRef
             writeSettings(cfg)
             return sendJson(res, 200, { ok: true })
           }
@@ -469,6 +662,7 @@ export function apply(ctx) {
             const cfg = readSettings()
             const prof = cfg.providers && cfg.providers[provider]
             if (!prof) return sendJson(res, 404, { error: 'pool not found' })
+            if (ref === prof.env) return sendJson(res, 400, { error: '环境密钥不可删除' })
             const idx = (prof.keyRefs || []).findIndex((k) => k.ref === ref)
             if (idx < 0) return sendJson(res, 404, { error: 'key not found' })
             try { backupFile(CRED_FILE, 'credentials'); await ctx.credentials.unset(credentialRef(ref)) } catch (e) {}
@@ -477,11 +671,35 @@ export function apply(ctx) {
             // 清理指向已删 key 的 nextRef
             for (const k of (prof.keyRefs || [])) if (k.nextRef === ref) k.nextRef = ''
             writeSettings(cfg)
+            // 同步内存池
+            try {
+              const pool = pools.get(provider)
+              if (pool) {
+                pool.keyValues = pool.keyValues.filter((k) => k.ref !== ref)
+                if (pool.currentRef === ref) { pool.currentRef = ''; try { const pk = pickKey(pool); if (pk) { pool.currentRef = pk.ref; try { process.env[pool.cfg.env] = pk.value } catch (e) {} } } catch (e) {} }
+              }
+            } catch (e) {}
             return sendJson(res, 200, { ok: true })
           }
           return sendJson(res, 405, { error: 'method not allowed' })
         }
 
+        // 明文揭示：仅限本池拥有的 user key 或环境密钥
+        if (path === 'keys/plain' && req.method === 'GET') {
+          const provider = url.searchParams.get('provider')
+          const ref = url.searchParams.get('ref')
+          if (!provider || !ref) return sendJson(res, 400, { error: 'provider & ref required' })
+          const pool = await getPool(provider)
+          if (!pool) return sendJson(res, 404, { error: 'pool not found' })
+          const isUserKey = (pool.cfg.keyRefs || []).some((k) => k.ref === ref)
+          const isEnvKey = ref === pool.cfg.env
+          if (!isUserKey && !isEnvKey) return sendJson(res, 404, { error: 'key not found' })
+          let hit
+          try { hit = rawResolve ? await rawResolve(credentialRef(ref)) : await ctx.credentials.resolve(credentialRef(ref)) } catch (e) { hit = undefined }
+          if (!hit || !hit.value) return sendJson(res, 404, { error: 'no value' })
+          return sendJson(res, 200, { ok: true, ref: ref, value: hit.value })
+        }
+
         if (path === 'reset') {
           if (req.method === 'POST') {
             const body = await readBody()

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@omdp/dsh-key-fallback",
-  "description": "Elliptic key pool with automatic rotation for DeepSeek Harness LLM providers. Settings → API Key 回退 UI: pick provider, add multiple keys (write-only). v3.",
-  "version": "3.0.0",
+  "description": "API Key 回退轮换插件：多 key 池 + 自动轮换（触发码可配置）+ 环境密钥编辑 + 明文揭示 + 短 ref 迁移。Settings → API Key 回退 UI. v6.",
+  "version": "3.1.0",
   "type": "module",
   "main": "lib/index.js",
   "exports": {