dsh-commandcode-quota 0.2.3 → 0.3.0

package/README.md

@@ -6,7 +6,12 @@ The plugin renders a compact status row directly underneath the DSH composer:
 
 - **5-hour, weekly and monthly usage windows** as live percentages
 - **Available balance**
-- Click the row to expand the full breakdown: used / limit / remaining / reset time, total spend, tokens, success rate, subscription and account information
+- Click the row to expand the full breakdown: used / limit / remaining / reset time, total spend, tokens, daily spend, subscription and account information
+- **Three status lights** — normal / low balance / exhausted. The current one lights up and the others dim, driven by the official `belowThreshold` and `exceeded` fields; hover any light for an explanation
+- **The bar color follows usage**: cool while usage is low, warming up past 55%, red near the limit, with an internal gradient
+- **Six bar palettes** to choose from in the gear settings; the choice is remembered
+- **Overrun warning**: based on this period's daily average, the monthly card adds a line like “~N days until empty” when the remaining credit will not last until reset
+- A skeleton screen shows on first load so the layout does not jump when data arrives
 
 It is **single-account by design**. There is no account switcher, and your API key never reaches the browser.
 
@@ -76,12 +81,14 @@ The package has two halves:
 - **Host half** (`src/index.js`) resolves the key through the DSH credentials service and registers a read-only HTTP endpoint that fans out to the Command Code API, then aggregates the responses into a single payload. The key is read on every request and never serialized to the client.
 - **Client half** (`src/client.js`) registers a status row into the composer dock slot, polls the host endpoint, and renders it with DSH theme tokens so light and dark themes both work.
 
+Polling is tiered: balance every 3 minutes (cheap), usage and subscriptions every 30 minutes (expensive). Polling pauses while the page is hidden and refreshes fully when it comes back.
+
 Data comes from four Command Code endpoints, each called with `Authorization: Bearer <key>`:
 
 | Endpoint | Used for |
 |---|---|
 | `GET /alpha/billing/credits` | Balance and the 5-hour / weekly limits |
-| `GET /alpha/usage/summary` | Spend, tokens and success rate |
+| `GET /alpha/usage/summary` | Spend, tokens and the period start (for daily spend) |
 | `GET /alpha/billing/subscriptions` | Subscription status and period boundaries |
 | `GET /alpha/whoami` | Account information |
 
@@ -91,8 +98,11 @@ The monthly window is composed from the usage total plus the remaining credits,
 
 - The four requests run in parallel, so total latency is the slowest one rather than the sum.
 - A connection-level failure is retried once; a deliberate timeout is not retried.
-- On failure the panel falls back to the last successful value (kept in-process for 6 hours) and reports it as stale.
+- On failure the panel falls back to the last successful value (kept for 6 hours) and reports it as stale.
+- That snapshot is also written to `$DSH_HOME/dsh-commandcode-quota-cache.json`, so it **survives a restart**. It holds quota fields only — no account details, and never the key itself.
+- The snapshot is keyed by a fingerprint of the API key, so switching keys never reuses another account's data.
 - An HTTP 401 is never masked by cached data, because it means the credential itself is wrong.
+- When **all four** endpoints fail, the response carries a readable reason and the panel shows an error rather than a blank box.
 
 ## Development
 

package/README.zh.md

@@ -6,7 +6,12 @@
 
 - **5 小时、每周、每月**三个额度窗口的实时百分比
 - **可用余额**
-- 点击状态栏展开完整明细：已用 / 上限 / 剩余 / 重置时间、总消耗、Tokens、成功率，以及订阅和账户信息
+- 点击状态栏展开完整明细：已用 / 上限 / 剩余 / 重置时间、总消耗、Tokens、日均消耗，以及订阅和账户信息
+- **三档状态灯**：正常 / 余额低 / 已用尽，当前档亮起、其余压暗（依据官方 `belowThreshold` 与 `exceeded` 字段），悬停每个灯有解释
+- **进度条颜色随用量变化**：低用量保持所选冷色，55% 之后逐渐转暖，接近上限转红；条形内部也带一段渐变
+- **六种进度配色可选**：在齿轮设置里切换，选择会记住
+- **超额预警**：按本周期日均推算，如果会在重置前用光，月窗口会多一行「按当前日均，约 N 天后用完」
+- 首次加载显示骨架屏，数据回来时版面不会跳一下
 
 **刻意做成单账号**：没有账号切换，API key 也不会进入浏览器。
 
@@ -76,12 +81,14 @@ New-Item -ItemType Junction `
 - **宿主端**（`src/index.js`）通过 DSH 凭据服务解析 key，注册一个只读 HTTP 端点，并发请求 Command Code API 后聚合成一个响应。key 每次请求现读，绝不序列化给客户端。
 - **客户端**（`src/client.js`）往输入框的 dock 槽位注册状态栏，轮询宿主端点，并全部使用 DSH 主题 token 渲染，自动适配深色/浅色主题。
 
+轮询是分层的：余额 3 分钟一次（轻量），用量与订阅 30 分钟一次（重查询）；页面不可见时暂停，切回前台立即补一次完整查询。
+
 数据来自四个 Command Code 接口，均带 `Authorization: Bearer <key>`：
 
 | 接口 | 用途 |
 |---|---|
 | `GET /alpha/billing/credits` | 余额，以及 5 小时 / 每周限额 |
-| `GET /alpha/usage/summary` | 消耗、Tokens、成功率 |
+| `GET /alpha/usage/summary` | 消耗、Tokens、周期起始时间（用于日均消耗） |
 | `GET /alpha/billing/subscriptions` | 订阅状态与周期起止 |
 | `GET /alpha/whoami` | 账户信息 |
 
@@ -91,8 +98,11 @@ New-Item -ItemType Junction `
 
 - 四个请求并发发出，总耗时等于最慢的一个，而不是四者之和。
 - 连接级失败重试一次；主动超时不重试。
-- 请求失败时回退到上次成功的值（进程内保留 6 小时），并标记为陈旧数据。
+- 请求失败时回退到上次成功的值（保留 6 小时），并标记为陈旧数据。
+- 这份快照同时落盘到 `$DSH_HOME/dsh-commandcode-quota-cache.json`，**重启后依然可用**；只保存额度相关字段，不含账户信息，也不含 key 本身。
+- 快照按 API key 的指纹隔离：换 key 之后不会把上一个账号的数据当成兜底值。
 - HTTP 401 不会被缓存掩盖——它意味着凭据本身有问题，必须让用户看到。
+- 四个接口**全部**失败时，响应会带出可读的失败原因，面板显示错误而不是一块空白。
 
 ## 开发
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-commandcode-quota",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Command Code balance and quota panel for DeepSeek Harness: a status row under the composer showing balance and the 5-hour, weekly and monthly windows.",
   "type": "module",
   "license": "MIT",

package/src/client.js

@@ -18,8 +18,13 @@ window.__ModuleLoader__.load({
 
     const FETCH_URL = "/__dsh-commandcode-quota/dashboard";
     const CREDENTIALS_URL = "/__dsh-commandcode-quota/credentials";
-    // 每 3 分钟后台自动刷新一次余额(面板开/关都刷新, 打开时看到的就是最新数据)
-    const REFRESH_MS = 3 * 60 * 1000;
+    // 分层轮询: credits(余额)轻量, 3 分钟一次; usage/subscriptions 是重查询, 30 分钟一次。
+    // 页面不可见时整轮跳过, 切回前台立即补一次 —— 免得后台白打上游接口。
+    const QUICK_REFRESH_MS = 3 * 60 * 1000;
+    const FULL_REFRESH_MS = 30 * 60 * 1000;
+
+    // 接口名 → 中文, 用于把宿主端返回的 errors 展示成人能读懂的话
+    const ENDPOINT_NAMES = { credits: "余额", usage: "用量", subscriptions: "订阅", whoami: "账户" };
 
     // ---- 格式化 --------------------------------------------------------------
 
@@ -28,6 +33,7 @@ window.__ModuleLoader__.load({
       return "$" + value.toFixed(digits);
     }
 
+    // 不设 G 档: token 计量惯例是 K/M, 2.56e9 应显示为 2560.5M 而不是 2.56G。
     function fmtNumber(value) {
       if (typeof value !== "number" || !Number.isFinite(value)) return "—";
       if (value >= 1e6) return (value / 1e6).toFixed(1) + "M";
@@ -86,7 +92,8 @@ window.__ModuleLoader__.load({
       const m = Math.floor((diff % 3600000) / 60000);
       if (days > 0) return `${days}天${h}小时`;
       if (h > 0) return `${h}小时${m}分`;
-      return `${m}分${Math.floor((diff % 60000) / 1000)}秒`;
+      // 不足 1 小时时精确到秒没有意义, 让人读到"47 分钟"就够了
+      return `${Math.max(1, m)} 分钟`;
     }
 
     // 到期日与今天不同时补上日期, 同时回答"还有多久"和"哪天到期"
@@ -106,23 +113,33 @@ window.__ModuleLoader__.load({
 
     const T = {
       bg: "var(--dsw-alias-bg-layer-1, #232324)",
-      bg2: "var(--dsw-alias-bg-layer-2, #2c2c2e)",
-      bg3: "var(--dsw-alias-bg-layer-3, #353636)",
+      // 不要用 --dsw-alias-brand-primary: 它只是个 neutral 色阶别名,
+      // 卡片底色: 从 layer-1 只混 6% 主文字色 —— 混多了是一块突兀的亮灰,
+      // 照搬 layer-2 又可能换肤后和 layer-1 同色糊成一片。6% + 1px 边框刚好。
+      bg2: "color-mix(in srgb, var(--dsw-alias-bg-layer-1, #232324) 96%, var(--dsw-alias-label-primary, #f9fafb) 4%)",
       border: "var(--dsw-alias-border-l2, rgba(255,255,255,.14))",
       borderL: "var(--dsw-alias-border-l1, rgba(255,255,255,.08))",
+      // 卡片描边自己派生: 浅色主题下主题的 border-l1 偏重(实测 #c4c5c6),
+      // 1px 就能把面板描得发脏; 10% 主文字色在两种主题下都刚好是一条淡线。
+      hairline: "color-mix(in srgb, var(--dsw-alias-label-primary, #f9fafb) 10%, transparent)",
       label: "var(--dsw-alias-label-primary, #f9fafb)",
       label2: "var(--dsw-alias-label-secondary, #d3d5d9)",
       label3: "var(--dsw-alias-label-tertiary, #adb2b8)",
-      // 进度条轨道在 深色主题下直接用近黑半透明 (Bar 里用 TRACK_STYLE 常量)
-      track: "var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.2))",
       success: "var(--dsw-alias-state-success-primary, #22c55e)",
       warn: "var(--dsw-alias-state-warn-primary, #f59e0b)",
       error: "var(--dsw-alias-state-error-primary, #f25a5a)",
-      brand: "var(--dsw-alias-brand-primary, #679efe)",
+      // 进度色用 Anthropic 官方柔和蓝 #6A9BCC: 低饱和, 深色底上不刺眼,
+      // 又天然和告警的琥珀 / 红分开。不能用 --dsw-alias-brand-primary
+      // (它只是中性色阶别名, 换肤后会整条变黑)。
+      brand: "#6A9BCC",
     };
 
-    // 深色主题下进度条轨道: 近黑半透明, 与填充色形成强对比
-    const TRACK_STYLE = "rgba(0, 0, 0, 0.35)";
+    // 进度条轨道: 从主文字色派生 10% 透明度 —— 深色主题得浅色轨道, 浅色主题得深色轨道,
+    // 不依赖 interactive-bg-hover(换肤后可能和背景同色, 轨道直接消失)。
+    const TRACK_STYLE = "color-mix(in srgb, var(--dsw-alias-label-primary, #f9fafb) 10%, transparent)";
+
+    // 原生 select 的下拉箭头替身(SVG data URI), 盖掉浏览器默认控件外观
+    const SELECT_CHEVRON = "url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='10' height='6' viewBox='0 0 10 6'%3E%3Cpath d='M1 1l4 4 4-4' fill='none' stroke='%23adb2b8' stroke-width='1.4' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E\")";
 
     // ---- 样式常量 -------------------------------------------------------------
 
@@ -131,16 +148,16 @@ window.__ModuleLoader__.load({
       width: 352,
       maxWidth: "calc(100vw - 40px)",
       maxHeight: "calc(100vh - 120px)",
-      overflowY: "auto",
       pointerEvents: "auto",
       zIndex: 9999,
       fontFamily: "inherit",
       color: T.label,
-      borderRadius: 16,
+      borderRadius: 14,
       background: T.bg,
       border: `1px solid ${T.border}`,
-      boxShadow: "0 16px 56px rgba(0,0,0,.55), 0 2px 10px rgba(0,0,0,.35)",
-      overflow: "hidden",
+      boxShadow: "0 18px 48px rgba(0,0,0,.5), 0 0 0 1px rgba(0,0,0,.25)",
+      overflowY: "auto",
+      overflowX: "hidden",
       animation: "ccUsagePop .22s cubic-bezier(.2,.9,.3,1.2)",
     };
 
@@ -214,6 +231,11 @@ window.__ModuleLoader__.load({
       React.createElement("line", { x1: "18", y1: "6", x2: "6", y2: "18" }),
       React.createElement("line", { x1: "6", y1: "6", x2: "18", y2: "18" }));
 
+    // 齿轮: 凭据设置入口(默认收起, 不占主面板)
+    const IconGear = () => React.createElement("svg", { width: 14, height: 14, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 1.8, strokeLinecap: "round", strokeLinejoin: "round" },
+      React.createElement("circle", { cx: 12, cy: 12, r: 3 }),
+      React.createElement("path", { d: "M19.4 15a1.7 1.7 0 0 0 .34 1.87l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06A1.7 1.7 0 0 0 15 19.4a1.7 1.7 0 0 0-1 1.55V21a2 2 0 1 1-4 0v-.09A1.7 1.7 0 0 0 9 19.4a1.7 1.7 0 0 0-1.87.34l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06A1.7 1.7 0 0 0 4.6 15a1.7 1.7 0 0 0-1.55-1H3a2 2 0 1 1 0-4h.09A1.7 1.7 0 0 0 4.6 9a1.7 1.7 0 0 0-.34-1.87l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06A1.7 1.7 0 0 0 9 4.6a1.7 1.7 0 0 0 1-1.55V3a2 2 0 1 1 4 0v.09a1.7 1.7 0 0 0 1 1.55 1.7 1.7 0 0 0 1.87-.34l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06A1.7 1.7 0 0 0 19.4 9c.12.38.4.7.78.86H21a2 2 0 1 1 0 4h-.09a1.7 1.7 0 0 0-1.55 1z" }));
+
     const IconClock = ({ color }) => React.createElement("svg", { width: 13, height: 13, viewBox: "0 0 24 24", fill: "none", stroke: color, strokeWidth: 2, strokeLinecap: "round" },
       React.createElement("circle", { cx: "12", cy: "12", r: "9" }),
       React.createElement("polyline", { points: "12 7 12 12 15 14" }));
@@ -253,58 +275,159 @@ window.__ModuleLoader__.load({
         sub ? React.createElement("div", { style: { fontSize: 11, color: T.label3, marginTop: 2, whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" } }, sub) : null);
     }
 
-    // 进度条: 轨道用深色 (与卡片背景强对比), 填充用 color-mix 渐变色
-    function Bar({ pct, color }) {
+    // 三档状态灯: 当前档亮起, 其余压暗。
+    // 数据来自官方字段 credits.belowThreshold / usage.windowLimits.*.exceeded;
+    // 这三个人话名字是给那两条数据起的, 不是官方术语 —— 悬停每个灯都有解释。
+    const STATUS_LEVELS = [
+      { key: "ok", label: "正常", hint: "余额充足，三个额度窗口都没用满", color: T.success },
+      { key: "low", label: "余额低", hint: "余额已低于你设定的告警阈值（threshold）", color: T.warn },
+      { key: "out", label: "已用尽", hint: "有额度窗口已经用满，等它按 5 小时 / 每周 / 每月重置", color: T.error },
+    ];
+
+    // 可选配色: 只改"低用量起点色"; 用量一高, 仍然统一走向暖色和红。
+    const PALETTES = [
+      { key: "mist", label: "雾蓝", hex: "#6A9BCC" },
+      { key: "indigo", label: "靛蓝", hex: "#5E6AD2" },
+      { key: "steel", label: "灰蓝", hex: "#7C9CBF" },
+      { key: "teal", label: "青绿", hex: "#2E9E8A" },
+      { key: "lilac", label: "丁香", hex: "#8B7BB8" },
+      { key: "clay", label: "陶土", hex: "#D97757" },
+    ];
+    const PALETTE_STORAGE_KEY = "dsh-commandcode-quota:palette";
+
+    function hexToRgb(hex) {
+      const m = /^#?([0-9a-f]{6})$/i.exec(String(hex));
+      if (!m) return [106, 155, 204];
+      const n = parseInt(m[1], 16);
+      return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+    }
+
+    /** 用量 → 颜色。起点由所选配色决定; 55% 之前保持冷静, 之后升温, 100% 收在红。 */
+    function usageColor(pct, brandHex) {
+      const base = hexToRgb(brandHex);
+      const stops = [
+        [0, base],
+        [55, base],
+        [70, [217, 164, 65]],
+        [85, [217, 119, 87]],
+        [100, [201, 79, 79]],
+      ];
+      const p = Math.max(0, Math.min(100, pct));
+      for (let i = 1; i < stops.length; i++) {
+        const [p1, c1] = stops[i];
+        if (p <= p1) {
+          const [p0, c0] = stops[i - 1];
+          const t = p1 === p0 ? 0 : (p - p0) / (p1 - p0);
+          const rgb = c0.map((v, k) => Math.round(v + (c1[k] - v) * t));
+          return `rgb(${rgb[0]}, ${rgb[1]}, ${rgb[2]})`;
+        }
+      }
+      return "rgb(201, 79, 79)";
+    }
+
+    // 进度条: 颜色随用量走, 条形内部还有一段 40 个百分点的渐变 —
+    // 高用量时能直接看出"冷 → 暖"的推进。消耗 > 0 时至少露出 3px。
+    function Bar({ pct, height = 8, forceColor, brand }) {
       const clamped = Math.max(0, Math.min(100, pct || 0));
-      const fillColor = color || T.success;
+      const end = forceColor || usageColor(clamped, brand);
+      const start = forceColor || usageColor(Math.max(0, clamped - 40), brand);
       return React.createElement("div", {
         style: {
-          height: 10,
+          height,
           borderRadius: 99,
           background: TRACK_STYLE,
-          border: "1px solid rgba(255,255,255,.06)",
           overflow: "hidden",
-          padding: 1,
+          boxShadow: "inset 0 1px 2px rgba(0,0,0,.12)",
         },
       },
         React.createElement("div", {
           style: {
-            width: clamped + "%",
+            width: clamped > 0 ? `max(${clamped}%, 3px)` : "0%",
             height: "100%",
             borderRadius: 99,
-            background: `linear-gradient(90deg, ${fillColor}, color-mix(in srgb, ${fillColor} 78%, #ffffff 22%))`,
-            boxShadow: `0 0 10px color-mix(in srgb, ${fillColor} 45%, transparent)`,
-            transition: "width .5s cubic-bezier(.3,.8,.3,1)",
+            background: `linear-gradient(90deg, ${start}, ${end})`,
+            transition: "width .45s cubic-bezier(.3,.8,.3,1)",
           },
         }));
     }
 
-    // 限额卡片: 标题 + 百分比 + 进度条 + 已用/上限/剩余 + 重置时间
-    function LimitCard({ title, used, cap, resetAt }) {
+    // 状态徽章: 颜色由服务端告警位决定, 不再永远绿色 active。
+    const BADGE_TONES = { success: T.success, warn: T.warn, error: T.error };
+    function StatusBadge({ tone, label }) {
+      const color = BADGE_TONES[tone] ?? T.success;
+      return React.createElement("div", {
+        style: {
+          display: "flex",
+          alignItems: "center",
+          gap: 6,
+          background: `color-mix(in srgb, ${color} 15%, transparent)`,
+          border: `1px solid color-mix(in srgb, ${color} 40%, transparent)`,
+          color,
+          borderRadius: 99,
+          padding: "4px 11px",
+          fontSize: 11.5,
+          fontWeight: 600,
+          whiteSpace: "nowrap",
+        },
+      },
+        React.createElement("span", { style: { width: 6, height: 6, borderRadius: "50%", background: color, display: "inline-block" } }),
+        label);
+    }
+
+    // 统一错误卡片: 顶部错误态与「余额字段缺失」态共用,
+    // 后者以前直接 return null, 于是查询失败被渲染成一块空白面板。
+    function ErrorBox({ text }) {
+      return React.createElement("div", {
+        style: {
+          margin: "16px",
+          padding: "12px 14px",
+          whiteSpace: "pre-line",
+          background: "color-mix(in srgb, var(--dsw-alias-state-error-primary, #f25a5a) 14%, transparent)",
+          border: "1px solid color-mix(in srgb, var(--dsw-alias-state-error-primary, #f25a5a) 38%, transparent)",
+          borderRadius: 12,
+          fontSize: 12.5,
+          color: T.error,
+          lineHeight: 1.6,
+        },
+      }, String(text));
+    }
+
+    // 一个额度窗口 = 一张卡: 名称 + 百分比 / 进度条 / 一行明细。
+    // 明细压成一行(已用/上限 · 剩余 · 重置), 信息不丢但高度减半。
+    function QuotaRow({ title, used, cap, resetAt, exceeded, brand, note }) {
       const capSafe = cap > 0 ? cap : (used > 0 ? used : 1);
       const pct = capSafe > 0 ? Math.min(100, (used / capSafe) * 100) : 0;
-      const color = pct >= 90 ? T.error : pct >= 70 ? T.warn : T.success;
+      const exhausted = exceeded === true;
+      // 颜色交给进度条表达(随用量连续变化), 数字保持主文字色, 只在用尽时转红 ——
+      // 浅色主题下黄/橙数字对比度不够, 读起来会糊。
+      const pctColor = exhausted ? T.error : T.label;
       const remaining = Math.max(0, capSafe - used);
       return React.createElement("div", {
         style: {
           background: T.bg2,
-          border: `1px solid ${T.borderL}`,
           borderRadius: 12,
-          padding: "12px 14px",
+          padding: "10px 13px 11px",
+          // 几乎同色的底 + 一条极细边框: 靠线和间距分组, 而不是靠一块亮灰
+          border: `1px solid ${T.hairline}`,
         },
       },
-        React.createElement("div", { style: { display: "flex", justifyContent: "space-between", alignItems: "center", marginBottom: 9 } },
-          React.createElement("div", { style: { display: "flex", alignItems: "center", gap: 7, fontSize: 12.5, fontWeight: 600, color: T.label } },
-            React.createElement(IconClock, { color }),
-            title),
-          React.createElement("span", { style: { fontSize: 16, fontWeight: 800, fontVariantNumeric: "tabular-nums", color } },
+        React.createElement("div", { style: { display: "flex", alignItems: "baseline", justifyContent: "space-between", gap: 8, fontSize: 12, color: T.label2 } },
+          React.createElement("span", { style: { fontWeight: 600 } },
+            title,
+            exhausted ? React.createElement("span", { style: { marginLeft: 6, fontSize: 10.5, fontWeight: 700, color: T.error } }, "已用尽") : null),
+          React.createElement("span", { style: { fontSize: 15, fontWeight: 700, fontVariantNumeric: "tabular-nums", color: pctColor, letterSpacing: "-.3px" } },
             (Math.round(pct * 10) / 10) + "%")),
-        React.createElement(Bar, { pct, color }),
-        React.createElement("div", { style: { display: "flex", justifyContent: "space-between", marginTop: 9, fontSize: 11.5, color: T.label2, fontVariantNumeric: "tabular-nums" } },
-          React.createElement("span", null, `已用 ${fmtCurrency(used)}`),
-          React.createElement("span", null, `上限 ${fmtCurrency(capSafe)}`)),
-        React.createElement("div", { style: { marginTop: 3, fontSize: 11, color: T.label3 } },
-          `剩余 ${fmtCurrency(remaining)} · 重置 ${fmtDuration(resetAt)}${fmtResetDay(resetAt)}`));
+        React.createElement("div", { style: { margin: "8px 0 7px" } },
+          React.createElement(Bar, { pct, brand, forceColor: exhausted ? T.error : null })),
+        // 固定两行: 一行放"已用/上限", 一行放"剩余/重置"。
+        // 挤成一行时日期会被断到下一行, 比多一行更难看。
+        React.createElement("div", { style: { fontSize: 11, color: T.label3, lineHeight: 1.55, fontVariantNumeric: "tabular-nums" } },
+          `已用 ${fmtCurrency(used)} / 上限 ${fmtCurrency(capSafe)}`),
+        React.createElement("div", { style: { fontSize: 11, color: T.label3, lineHeight: 1.55, fontVariantNumeric: "tabular-nums" } },
+          `剩余 ${fmtCurrency(remaining)} · `
+            + (exhausted ? `${fmtDuration(resetAt)}后重置` : `重置 ${fmtDuration(resetAt)}${fmtResetDay(resetAt)}`)),
+        // 超额预警: 只有"按当前日均撑不到重置"时才多出这一行
+        note ? React.createElement("div", { style: { marginTop: 4, fontSize: 11, color: T.warn, lineHeight: 1.5 } }, `⚠ ${note}`) : null);
     }
 
     // ---- 凭据条目选择 ------------------------------------------------------------
@@ -333,7 +456,7 @@ window.__ModuleLoader__.load({
           display: "flex",
           alignItems: "center",
           gap: 8,
-          padding: "9px 16px",
+          padding: "8px 16px 9px",
           borderBottom: `1px solid ${T.borderL}`,
           fontSize: 11.5,
           color: T.label3,
@@ -348,13 +471,18 @@ window.__ModuleLoader__.load({
           style: {
             flex: 1,
             minWidth: 0,
-            padding: "4px 6px",
+            padding: "4px 24px 4px 8px",
             fontSize: 11.5,
             fontFamily: "inherit",
             color: T.label2,
             background: T.bg2,
-            border: `1px solid ${T.border}`,
-            borderRadius: 8,
+            backgroundImage: SELECT_CHEVRON,
+            backgroundRepeat: "no-repeat",
+            backgroundPosition: "right 7px center",
+            appearance: "none",
+            WebkitAppearance: "none",
+            border: `1px solid ${T.borderL}`,
+            borderRadius: 7,
             cursor: safe.saving ? "default" : "pointer",
           },
         },
@@ -366,33 +494,70 @@ window.__ModuleLoader__.load({
 
     // ---- 面板内容 ----------------------------------------------------------------
 
-    function DashboardBody({ data, loading, error }) {
-      if (error) {
-        return React.createElement("div", { style: { padding: "16px 16px 20px" } },
-          React.createElement("div", {
+    function DashboardBody({ data, loading, error, palette }) {
+      if (error) return React.createElement(ErrorBox, { text: error });
+      if (loading && !data) {
+        // 骨架屏: 按真实布局占位(余额块 + 三张卡), 数据回来时不会整块"跳一下"
+        const bone = (key, w, h, mb) => React.createElement("div", {
+          key,
+          // 占位条要比卡片底色更实一点, 否则和卡片同色会"消失"
+          style: { width: w, height: h, borderRadius: 6, background: T.hairline, marginBottom: mb },
+        });
+        return React.createElement("div", {
+          key: "skeleton",
+          style: { padding: "14px 16px 12px" },
+          "aria-busy": true,
+          "aria-label": "正在获取额度",
+        },
+          bone("b1", "34%", 9, 10),
+          bone("b2", "48%", 26, 12),
+          bone("b3", "72%", 9, 6),
+          bone("b4", "58%", 9, 6),
+          bone("b5", "64%", 9, 14),
+          [0, 1, 2].map((i) => React.createElement("div", {
+            key: "sk" + i,
             style: {
-              background: "color-mix(in srgb, var(--dsw-alias-state-error-primary, #f25a5a) 14%, transparent)",
-              border: "1px solid color-mix(in srgb, var(--dsw-alias-state-error-primary, #f25a5a) 38%, transparent)",
+              background: T.bg2,
               borderRadius: 12,
-              padding: "12px 14px",
-              fontSize: 12.5,
-              color: T.error,
-              lineHeight: 1.5,
+              border: `1px solid ${T.hairline}`,
+              padding: "12px 13px",
+              marginBottom: i === 2 ? 0 : 9,
             },
-          }, String(error)));
+          },
+            bone("s" + i + "a", "40%", 9, 10),
+            bone("s" + i + "b", "100%", 8, 9),
+            bone("s" + i + "c", "76%", 9, 5),
+            bone("s" + i + "d", "52%", 9, 0))),
+          React.createElement("div", { style: { marginTop: 12, textAlign: "center", fontSize: 11, color: T.label3 } }, "正在获取额度…"));
       }
-      if (loading && !data) {
-        return React.createElement("div", { style: { padding: "24px 16px", textAlign: "center", fontSize: 12.5, color: T.label3 } },
-          React.createElement("div", { style: { width: 22, height: 22, margin: "0 auto 10px", border: "2px solid rgba(255,255,255,.18)", borderTopColor: T.brand, borderRadius: "50%", animation: "ccUsageSpin .8s linear infinite" } }),
-          "正在获取余额…（Command Code 接口较慢，约需 10~20 秒）");
+      if (!data) return null;
+      // 余额字段缺失(最常见的是 credits 单接口 401/500)时必须说清原因,
+      // 不能再 return null —— 那会把「查询失败」伪装成一块空白面板。
+      if (!data.balance) {
+        const failed = Array.isArray(data.errors) ? data.errors : [];
+        const detail = failed.length > 0
+          ? failed.map((e) => `${ENDPOINT_NAMES[e.endpoint] ?? e.endpoint}: ${e.message}`).join("\n")
+          : "服务端没有返回余额数据（点右上角 ⟳ 重试）";
+        return React.createElement(ErrorBox, { text: `额度查询失败\n${detail}` });
       }
-      if (!data || !data.balance) return null;
 
       const { balance, windowLimits, usage, subscription, user } = data;
 
       // 订阅开通时间: 优先 createdAt, 回退到当前周期开始
       const subSince = subscription && (subscription.createdAt || subscription.currentPeriodStart) || null;
 
+      // ---- 服务端告警位 --------------------------------------------------------
+      // API 已经把「余额低于阈值 / 窗口已用尽 / 订阅已取消续费」判好了, 之前一个都没用,
+      // 于是额度真的用尽时面板还是那个绿色 active 徽章 —— 在最该报警的时刻显得一切正常。
+      const belowThreshold = balance.belowThreshold === true;
+      const exhaustedNames = [];
+      if (windowLimits && windowLimits.fiveHour && windowLimits.fiveHour.exceeded === true) exhaustedNames.push("5 小时");
+      if (windowLimits && windowLimits.weekly && windowLimits.weekly.exceeded === true) exhaustedNames.push("每周");
+      if (windowLimits && windowLimits.exceeded === true && exhaustedNames.length === 0) exhaustedNames.push("额度");
+      // 状态档位: 任一窗口用尽 > 余额低于阈值 > 正常
+      const statusLevel = exhaustedNames.length > 0 ? "out" : belowThreshold ? "low" : "ok";
+      const brandHex = (palette && palette.hex) || PALETTES[0].hex;
+
       // 本次请求里订阅接口是否失败(接口本身慢/超时) —— 用于区分"没这条数据"和"没取到"
       const subFailed = Array.isArray(data.errors)
         && data.errors.some((e) => e && e.endpoint === "subscriptions");
@@ -406,31 +571,28 @@ window.__ModuleLoader__.load({
         : null;
       const monthReset = subscription && subscription.currentPeriodEnd ? subscription.currentPeriodEnd : null;
 
-      const rows = [];
+      // 日均消耗: 本周期已用 ÷ 本周期已过天数(periodStart 由 usage 接口给出)。
+      // 取代原来的「成功率」格子 —— 那是整期累计的运维指标, 对「今天还该不该放开用」没有决策价值。
+      const periodStart = usage && usage.periodStart ? toMs(usage.periodStart) : null;
+      const periodDays = periodStart !== null ? Math.max(0, (Date.now() - periodStart) / 86400000) : null;
+      const dailyAvg = monthUsed !== null && periodDays !== null && periodDays > 0 ? monthUsed / periodDays : null;
 
-      // 数据一致性告警 (典型: 两个账号解析到同一个 API key, 余额自然相同)
-      const warnings = Array.isArray(data.warnings) ? data.warnings : [];
-      if (warnings.length > 0) {
-        rows.push(React.createElement("div", {
-          key: "warnings",
-          style: {
-            margin: "12px 16px 0",
-            padding: "10px 12px",
-            borderRadius: 10,
-            background: "color-mix(in srgb, var(--dsw-alias-state-warn-primary, #f59e0b) 15%, transparent)",
-            border: "1px solid color-mix(in srgb, var(--dsw-alias-state-warn-primary, #f59e0b) 45%, transparent)",
-            color: T.warn,
-            fontSize: 11.5,
-            lineHeight: 1.55,
-          },
-        },
-          React.createElement("div", { style: { fontWeight: 700, marginBottom: 4 } }, "⚠ 凭据告警"),
-          warnings.map((w, i) => React.createElement("div", { key: i, style: { marginTop: i > 0 ? 4 : 0 } }, w))));
+      // 超额预警: 用本周期日均推算"剩余额度够不够撑到重置"。
+      // 进度条只说现在用了多少; 这条只在"按这个速度会在重置前用光"时出现。
+      let etaNote = null;
+      if (monthCap !== null && monthUsed !== null && dailyAvg !== null && dailyAvg > 0 && monthReset) {
+        const resetMs = toMs(monthReset);
+        const daysLeft = resetMs === null ? null : (resetMs - Date.now()) / 86400000;
+        const daysToEmpty = (monthCap - monthUsed) / dailyAvg;
+        if (daysLeft !== null && daysLeft > 0.5 && daysToEmpty > 0 && daysToEmpty < daysLeft) {
+          etaNote = `按当前日均，约 ${Math.max(1, Math.round(daysToEmpty))} 天后用完`;
+        }
       }
 
+      const rows = [];
+
       // 缓存兜底提示: 接口超时, 当前显示的是上次成功获取的数据
       if (staleList.length > 0) {
-        const FIELD_NAMES = { credits: "余额", usage: "用量", subscriptions: "订阅", whoami: "账户" };
         rows.push(React.createElement("div", {
           key: "stale",
           style: {
@@ -439,91 +601,115 @@ window.__ModuleLoader__.load({
             color: T.label3,
             lineHeight: 1.55,
           },
-        }, `⏱ ${staleList.map((s) => FIELD_NAMES[s.endpoint] || s.endpoint).join("、")} 本次请求超时，显示的是上次成功获取的数据（点右上角 ⟳ 重试）`));
+        }, `⏱ ${staleList.map((s) => ENDPOINT_NAMES[s.endpoint] || s.endpoint).join("、")} 本次请求超时，显示的是上次成功获取的数据（点右上角 ⟳ 重试）`));
       }
 
-      // Hero: 余额大数字
+      // 余额 + 账户信息: 状态灯与「本月剩余」同排, 其余信息独占整行 ——
+      // 灯放右边单独占一行会把"订阅开通"挤到换行。
       rows.push(React.createElement("div", {
-        key: "hero",
-        style: {
-          padding: "18px 16px 16px",
-          background: `linear-gradient(150deg, ${T.bg3}, ${T.bg2})`,
-          borderBottom: `1px solid ${T.borderL}`,
-        },
+        key: "balance",
+        style: { padding: "14px 16px 13px" },
       },
-        React.createElement("div", { style: { display: "flex", justifyContent: "space-between", alignItems: "flex-start" } },
-          React.createElement("div", null,
-            React.createElement("div", { style: { fontSize: 11, fontWeight: 600, color: T.label3, letterSpacing: ".7px", textTransform: "uppercase", marginBottom: 4 } }, "可用余额 Balance"),
-            React.createElement("div", {
-              style: {
-                fontSize: 34,
-                fontWeight: 800,
-                lineHeight: 1.05,
-                fontVariantNumeric: "tabular-nums",
-                letterSpacing: "-1px",
-                color: T.label,
-              },
-            }, fmtCurrency(balance.monthlyCredits))),
-          React.createElement("div", {
-            style: {
-              display: "flex",
-              alignItems: "center",
-              gap: 6,
-              background: "color-mix(in srgb, var(--dsw-alias-state-success-primary, #22c55e) 15%, transparent)",
-              border: "1px solid color-mix(in srgb, var(--dsw-alias-state-success-primary, #22c55e) 40%, transparent)",
-              color: T.success,
-              borderRadius: 99,
-              padding: "4px 11px",
-              fontSize: 11.5,
-              fontWeight: 600,
-            },
+        React.createElement("div", { style: { display: "flex", alignItems: "center", justifyContent: "space-between", gap: 8, marginBottom: 3 } },
+          React.createElement("span", { style: { fontSize: 11, color: T.label3 } }, "本月剩余"),
+          // 三档状态灯: 当前档亮起, 其余压暗 —— 比单独一个 "active" 更能说明处在哪一档。
+          React.createElement("div", { style: { display: "flex", alignItems: "center", gap: 4 } },
+            STATUS_LEVELS.map((level) => {
+              const active = level.key === statusLevel;
+              return React.createElement("span", {
+                key: level.key,
+                title: level.hint,
+                style: {
+                  display: "inline-flex",
+                  alignItems: "center",
+                  gap: 4,
+                  fontSize: 10.5,
+                  fontWeight: active ? 700 : 500,
+                  color: active ? level.color : T.label3,
+                  background: active ? `color-mix(in srgb, ${level.color} 14%, transparent)` : "transparent",
+                  border: `1px solid ${active ? `color-mix(in srgb, ${level.color} 38%, transparent)` : "transparent"}`,
+                  borderRadius: 99,
+                  padding: "2px 6px",
+                  opacity: active ? 1 : 0.5,
+                  whiteSpace: "nowrap",
+                },
+              }, React.createElement("span", {
+                style: {
+                  width: 5,
+                  height: 5,
+                  borderRadius: "50%",
+                  background: active ? level.color : T.label3,
+                  display: "inline-block",
+                },
+              }), level.label);
+            }))),
+        React.createElement("div", {
+          style: {
+            fontSize: 28,
+            fontWeight: 700,
+            lineHeight: 1.1,
+            letterSpacing: "-.8px",
+            fontVariantNumeric: "tabular-nums",
+            color: T.label,
           },
-            React.createElement("span", { style: { width: 6, height: 6, borderRadius: "50%", background: T.success, display: "inline-block" } }),
-            (subscription && subscription.status) ? subscription.status : "active")),
-        React.createElement("div", { style: { display: "flex", alignItems: "center", gap: 6, marginTop: 10, fontSize: 11.5, color: T.label2 } },
-            React.createElement(IconCalendar, { color: T.brand }),
-            React.createElement("span", null, subSince
-              ? `开通于 ${fmtDay(subSince)} · 已使用 ${fmtElapsed(subSince)}`
-              : (subFailed ? "订阅接口本次未响应（点右上角 ⟳ 重试）" : "订阅信息暂不可用"))),
-        React.createElement("div", { style: { display: "flex", gap: 8, marginTop: 12 } },
-          React.createElement(StatCard, { label: "总消耗", value: fmtCurrency(usage && usage.totalCost) }),
-          React.createElement(StatCard, { label: "Tokens", value: fmtNumber(usage && usage.totalTokens) }),
-          React.createElement(StatCard, { label: "成功率", value: usage ? usage.successRate + "%" : "—" }))));
-
-      // 限额卡片: 5小时 / 每周 / 每月
-      const limitCards = [];
+        }, fmtCurrency(balance.monthlyCredits)),
+        React.createElement("div", { style: { marginTop: 6, fontSize: 11, color: T.label3, lineHeight: 1.6, fontVariantNumeric: "tabular-nums" } },
+          `总消耗 ${fmtCurrency(usage && usage.totalCost)}　Tokens ${fmtNumber(usage && usage.totalTokens)}`),
+        React.createElement("div", { style: { fontSize: 11, color: T.label3, lineHeight: 1.6, fontVariantNumeric: "tabular-nums" } },
+          `日均 ${fmtCurrency(dailyAvg)}` + (periodDays !== null && periodDays >= 1 ? `　本周期 ${Math.floor(periodDays)} 天` : "")),
+        React.createElement("div", { style: { marginTop: 4, fontSize: 11, color: T.label3, lineHeight: 1.6 } },
+          subSince
+            ? `订阅开通 ${fmtDay(subSince)}，已 ${fmtElapsed(subSince)}`
+            : (subFailed ? "订阅接口本次未响应（点右上角 ⟳ 重试）" : "订阅信息暂不可用"))));
+
+      // 订阅取消续费提示
+      if (subscription && subscription.cancelAtPeriodEnd === true) {
+        rows.push(React.createElement("div", {
+          key: "cancel",
+          style: { padding: "0 16px 10px", fontSize: 11, color: T.warn, lineHeight: 1.55 },
+        }, `⚠ 订阅将于 ${fmtDay(subscription.currentPeriodEnd)} 到期，不再续费`));
+      }
+
+      // 三个窗口: 三张卡, 统一放在一个网格容器里
+      const windowCards = [];
       if (windowLimits && windowLimits.fiveHour) {
-        limitCards.push(React.createElement(LimitCard, {
+        windowCards.push(React.createElement(QuotaRow, {
           key: "5h",
           title: "5 小时窗口",
           used: windowLimits.fiveHour.used,
           cap: windowLimits.fiveHour.cap,
           resetAt: windowLimits.fiveHour.resetAt,
+          exceeded: windowLimits.fiveHour.exceeded,
+          brand: brandHex,
         }));
       }
       if (windowLimits && windowLimits.weekly) {
-        limitCards.push(React.createElement(LimitCard, {
+        windowCards.push(React.createElement(QuotaRow, {
           key: "week",
           title: "每周窗口",
           used: windowLimits.weekly.used,
           cap: windowLimits.weekly.cap,
           resetAt: windowLimits.weekly.resetAt,
+          exceeded: windowLimits.weekly.exceeded,
+          brand: brandHex,
         }));
       }
       if (monthCap !== null) {
-        limitCards.push(React.createElement(LimitCard, {
+        windowCards.push(React.createElement(QuotaRow, {
           key: "month",
           title: "每月窗口",
           used: monthUsed,
           cap: monthCap,
           resetAt: monthReset,
+          brand: brandHex,
+          note: etaNote,
         }));
       }
-      if (limitCards.length > 0) {
-        rows.push(React.createElement("div", { key: "limits", style: { padding: "14px 16px 4px" } },
-          React.createElement("div", { style: { fontSize: 11, fontWeight: 700, color: T.label3, letterSpacing: ".7px", textTransform: "uppercase", marginBottom: 10 } },
-            "窗口限额 Usage Limits"),
-          React.createElement("div", { style: { display: "grid", gap: 10 } }, limitCards)));
+      if (windowCards.length > 0) {
+        rows.push(React.createElement("div", {
+          key: "windows",
+          style: { padding: "0 12px 12px", display: "grid", gap: 9 },
+        }, windowCards));
       }
 
       // 底部: 账户 + 更新时间
@@ -546,6 +732,51 @@ window.__ModuleLoader__.load({
       return React.createElement("div", null, rows);
     }
 
+    // 配色选择: 六个颜色分两行排列, 只影响低用量起点色, 高用量仍统一走向暖色。
+    function PalettePicker({ value, onChange }) {
+      return React.createElement("div", {
+        style: {
+          display: "flex",
+          alignItems: "center",
+          gap: 8,
+          padding: "8px 16px 9px",
+          borderBottom: `1px solid ${T.borderL}`,
+          fontSize: 11.5,
+          color: T.label3,
+        },
+      },
+        React.createElement("span", { style: { whiteSpace: "nowrap" } }, "进度色"),
+        React.createElement("div", { style: { display: "grid", gridTemplateColumns: "repeat(3, 1fr)", gap: 6, flex: 1 } },
+          PALETTES.map((p) => {
+            const on = Boolean(value) && value.key === p.key;
+            return React.createElement("button", {
+              key: p.key,
+              type: "button",
+              title: p.label,
+              "aria-pressed": on,
+              onClick: () => onChange(p),
+              style: {
+                display: "inline-flex",
+                alignItems: "center",
+                justifyContent: "center",
+                gap: 5,
+                padding: "3px 6px",
+                borderRadius: 8,
+                cursor: "pointer",
+                fontSize: 11,
+                fontFamily: "inherit",
+                color: on ? T.label : T.label3,
+                background: on ? T.bg2 : "transparent",
+                border: `1px solid ${on ? T.hairline : "transparent"}`,
+              },
+            },
+              React.createElement("span", {
+                style: { width: 8, height: 8, borderRadius: "50%", background: p.hex, display: "inline-block", flexShrink: 0 },
+              }),
+              p.label);
+          })));
+    }
+
     // ---- 主组件 -------------------------------------------------------------------
 
     function UsageBadge() {
@@ -556,33 +787,53 @@ window.__ModuleLoader__.load({
       const timerRef = useRef(null);
       // 凭据条目：与 data / error 完全解耦 —— 这样面板报「没配 key」时依然能切换
       const [creds, setCreds] = useState({ entries: [], apiKeyEnv: null, saving: false, error: null });
+      // 凭据设置默认收起(见头部齿轮按钮)
+      const [gearOpen, setGearOpen] = useState(false);
+      // 进度色: 默认 Claude 蓝, 记住上次选择
+      const [palette, setPalette] = useState(() => {
+        try {
+          if (typeof localStorage === "undefined") return PALETTES[0];
+          const saved = localStorage.getItem(PALETTE_STORAGE_KEY);
+          return PALETTES.find((p) => p.key === saved) || PALETTES[0];
+        } catch {
+          return PALETTES[0];
+        }
+      });
+      // 外层容器引用：用来判断点击是否落在「状态栏 + 面板」之外
+      const rootRef = useRef(null);
 
-      const refresh = useCallback(async () => {
-        const fullUrl = FETCH_URL;
-        // Command Code 的用量/订阅接口要 10~25 秒, 余额接口 1~5 秒。
-        // 先只取余额(带上次缓存的用量/订阅)让面板立刻出内容, 再拉完整数据覆盖。
-        const quickUrl = fullUrl + "?scope=quick";
+      // options.full=false → 只刷余额(轻量); options.silent=true → 后台轮询, 不动 loading 态
+      const refresh = useCallback(async (options = {}) => {
+        const wantFull = options.full !== false;
+        const silent = options.silent === true;
+        // Command Code 的用量/订阅接口比余额接口慢得多, 所以两段式:
+        // 先只取余额让面板立刻出内容, 再拉完整数据覆盖。
+        const quickUrl = FETCH_URL + "?scope=quick";
 
         const pull = (url) => fetch(url, { cache: "no-store" }).then((res) => {
           if (!res.ok) throw new Error(`HTTP ${res.status}`);
           return res.json();
         });
 
-        setLoading(true);
+        if (!silent) setLoading(true);
         try {
           const quick = await pull(quickUrl);
           if (quick) {
             setData(quick);
+            // 余额拿到了就清掉上次的陈旧错误; 拿不到则让面板显示具体失败原因
+            if (quick.balance) setError(null);
           }
-          const full = await pull(fullUrl);
-          if (full) {
-            setData(full);
-            setError(full.ok === false && full.error ? full.error : null);
+          if (wantFull) {
+            const full = await pull(FETCH_URL);
+            if (full) {
+              setData(full);
+              setError(full.ok === false && full.error ? full.error : null);
+            }
           }
         } catch (reason) {
           setError(String(reason));
         } finally {
-          setLoading(false);
+          if (!silent) setLoading(false);
         }
       }, []);
 
@@ -602,6 +853,15 @@ window.__ModuleLoader__.load({
         }
       }, []);
 
+      const choosePalette = useCallback((next) => {
+        setPalette(next);
+        try {
+          if (typeof localStorage !== "undefined") localStorage.setItem(PALETTE_STORAGE_KEY, next.key);
+        } catch {
+          /* 隐私模式 / 存储不可用, 忽略 */
+        }
+      }, []);
+
       const pickCredential = useCallback(async (name) => {
         setCreds((prev) => ({ ...prev, saving: true, error: null }));
         try {
@@ -622,11 +882,47 @@ window.__ModuleLoader__.load({
       useEffect(() => {
         loadCredentials();
         refresh();
-        // 每 3 分钟自动查询一次余额(面板打开时也刷新)
-        timerRef.current = setInterval(() => refresh(), REFRESH_MS);
-        return () => { if (timerRef.current) clearInterval(timerRef.current); };
+        // 分层轮询: 余额 3 分钟 / 用量+订阅 30 分钟。页面不可见时整轮跳过,
+        // 切回前台立刻补一次完整查询 —— 后台不白打上游接口。
+        const doc = typeof document !== "undefined" ? document : null;
+        const visible = () => !doc || doc.hidden !== true;
+        const quickTimer = setInterval(() => { if (visible()) refresh({ full: false, silent: true }); }, QUICK_REFRESH_MS);
+        const fullTimer = setInterval(() => { if (visible()) refresh({ silent: true }); }, FULL_REFRESH_MS);
+        const onVisibility = () => { if (visible()) refresh({ silent: true }); };
+        if (doc && typeof doc.addEventListener === "function") doc.addEventListener("visibilitychange", onVisibility);
+        timerRef.current = { quickTimer, fullTimer };
+        return () => {
+          clearInterval(quickTimer);
+          clearInterval(fullTimer);
+          if (doc && typeof doc.removeEventListener === "function") doc.removeEventListener("visibilitychange", onVisibility);
+        };
       }, [loadCredentials, refresh]);
 
+      // 点击面板外部或按 Esc 关闭 —— 与 DSH 其它浮层的交互保持一致。
+      // 之前只有再点一次徽章才关得掉, 点别处没反应。
+      useEffect(() => {
+        if (!readoutOpen) return undefined;
+        const doc = typeof document !== "undefined" ? document : null;
+        if (!doc) return undefined;
+        const onPointerDown = (event) => {
+          const root = rootRef.current;
+          if (!root) return;
+          const target = event.target;
+          const inside = typeof Node !== "undefined" && target instanceof Node && root.contains(target);
+          if (!inside) setReadoutOpen(false);
+        };
+        const onKeyDown = (event) => {
+          if (event.key === "Escape") setReadoutOpen(false);
+        };
+        // capture 阶段监听: 面板内元素即使 stopPropagation 也能正确判定
+        doc.addEventListener("pointerdown", onPointerDown, true);
+        doc.addEventListener("keydown", onKeyDown);
+        return () => {
+          doc.removeEventListener("pointerdown", onPointerDown, true);
+          doc.removeEventListener("keydown", onKeyDown);
+        };
+      }, [readoutOpen]);
+
       function pctOf(win) {
         if (!win || typeof win.used !== "number" || typeof win.cap !== "number" || win.cap <= 0) return null;
         return Math.round((win.used / win.cap) * 100);
@@ -654,9 +950,14 @@ window.__ModuleLoader__.load({
       if (monthTotal !== null && monthTotal > 0 && monthUsed !== null) {
         parts.push({ key: "mo", label: "月 " + Math.round((monthUsed / monthTotal) * 100) + "%" });
       }
-      const readout = data
-        ? (parts.length > 0 ? parts : [{ key: "wait", label: "额度查询中…" }])
-        : [{ key: "idle", label: "Command Code" }];
+      // 状态栏也要能说人话: 查询失败时别再挂着「额度查询中…」骗人。
+      const readout = !data
+        ? [{ key: "idle", label: "Command Code" }]
+        : parts.length > 0
+          ? parts
+          : (Array.isArray(data.errors) && data.errors.length > 0)
+            ? [{ key: "err", label: "额度查询失败" }]
+            : [{ key: "wait", label: "额度查询中…" }];
 
       // 状态栏本体: 空心图标 + 三个占比读数。不加粗, 颜色沿用官方三级文字色。
       const badgeButton = React.createElement("button", {
@@ -699,7 +1000,7 @@ window.__ModuleLoader__.load({
         color: T.label,
       };
 
-      return React.createElement("div", { style: statusBarStyle },
+      return React.createElement("div", { style: statusBarStyle, ref: rootRef },
         badgeButton,
         readoutOpen ? React.createElement("div", { style: { ...shellStyle, ...panelPosStyle } },
           React.createElement("style", null, [
@@ -711,22 +1012,33 @@ window.__ModuleLoader__.load({
               display: "flex",
               justifyContent: "space-between",
               alignItems: "center",
-              padding: "10px 10px 10px 16px",
+              padding: "9px 10px 9px 16px",
               borderBottom: `1px solid ${T.borderL}`,
             },
           },
             React.createElement("span", { style: { fontSize: 13, fontWeight: 700, display: "flex", alignItems: "center", gap: 8 } },
-              React.createElement("span", { style: { width: 8, height: 8, borderRadius: "50%", background: T.brand, boxShadow: `0 0 8px ${T.brand}` } }),
+              // 品牌点: 去掉发光效果(原来像"正在录音"), 改成 6px 方块
+              React.createElement("span", { style: { width: 6, height: 6, borderRadius: 2, background: T.brand, display: "inline-block" } }),
               "Command Code"),
-            React.createElement("div", { style: { display: "flex", gap: 2 } },
+            React.createElement("div", { style: { display: "flex", gap: 1 } },
               React.createElement("button", {
-                style: iconBtn,
-                title: "刷新",
+                style: gearOpen ? { ...iconBtn, ...iconBtnHover } : iconBtn,
+                title: gearOpen ? "收起凭据设置" : "凭据设置",
+                "aria-label": "凭据设置",
+                "aria-expanded": gearOpen,
+                onClick: () => setGearOpen(!gearOpen),
+                onMouseEnter: (e) => { if (!gearOpen) Object.assign(e.currentTarget.style, iconBtnHover); },
+                onMouseLeave: (e) => { if (!gearOpen) { e.currentTarget.style.background = "transparent"; e.currentTarget.style.color = T.label3; } },
+              }, React.createElement(IconGear)),
+              React.createElement("button", {
+                style: loading ? { ...iconBtn, opacity: 0.45, cursor: "default" } : iconBtn,
+                title: loading ? "刷新中…" : "刷新",
                 "aria-label": "刷新",
+                "aria-busy": loading,
                 disabled: loading,
-                onClick: refresh,
-                onMouseEnter: (e) => Object.assign(e.currentTarget.style, iconBtnHover),
-                onMouseLeave: (e) => { e.currentTarget.style.background = "transparent"; e.currentTarget.style.color = T.label3; },
+                onClick: () => refresh(),
+                onMouseEnter: (e) => { if (!loading) Object.assign(e.currentTarget.style, iconBtnHover); },
+                onMouseLeave: (e) => { if (!loading) { e.currentTarget.style.background = "transparent"; e.currentTarget.style.color = T.label3; } },
               }, React.createElement(IconRefresh)),
               React.createElement("button", {
                 style: iconBtn,
@@ -736,8 +1048,10 @@ window.__ModuleLoader__.load({
                 onMouseEnter: (e) => Object.assign(e.currentTarget.style, iconBtnHover),
                 onMouseLeave: (e) => { e.currentTarget.style.background = "transparent"; e.currentTarget.style.color = T.label3; },
               }, React.createElement(IconClose)))),
-          React.createElement(CredentialPicker, { state: creds, onPick: pickCredential }),
-          React.createElement(DashboardBody, { data, loading, error })) : null);
+          // 凭据选择默认收起: 它是配置项, 不该常驻在数据面板的主视觉里
+          gearOpen ? React.createElement(CredentialPicker, { state: creds, onPick: pickCredential }) : null,
+          gearOpen ? React.createElement(PalettePicker, { value: palette, onChange: choosePalette }) : null,
+          React.createElement(DashboardBody, { data, loading, error, palette })) : null);
     }
 
     // ---- apply -----------------------------------------------------------------------

package/src/index.js

@@ -25,6 +25,7 @@
  * ESM module format (cordis bundle rule): named exports apply/inject/name.
  */
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
@@ -36,6 +37,14 @@ const DEFAULT_API_KEY_ENV = "COMMANDCODE_API_KEY";
 // Command Code 的 usage / subscriptions / whoami 实测要 8~20s, 8s 超时必然误杀。
 const DEFAULT_TIMEOUT_MS = 30000;
 
+// 落盘缓存文件名(与凭据选择文件同目录)。只存额度相关字段:
+// whoami 带邮箱等个人信息, 没有落盘价值, 不写进去。
+const CACHE_FILE_NAME = "dsh-commandcode-quota-cache.json";
+const PERSISTED_ENDPOINTS = ["credits", "usage", "subscriptions"];
+
+// 接口名 → 中文, 用于把失败原因写成一句人能看懂的话。
+const ENDPOINT_LABELS = { credits: "余额", usage: "用量", subscriptions: "订阅", whoami: "账户" };
+
 // --- HTTP helpers ------------------------------------------------------------
 
 function sendJson(res, status, obj) {
@@ -71,7 +80,7 @@ async function ccFetch(baseURL, path, apiKey, timeoutMs) {
       headers: {
         authorization: `Bearer ${apiKey}`,
         accept: "application/json",
-        "user-agent": "dsh-commandcode-quota/0.2.3"
+        "user-agent": "dsh-commandcode-quota/0.3.0"
       },
       signal: controller.signal
     });
@@ -142,17 +151,77 @@ const HANDLERS = {
  */
 const CACHE_TTL_MS = 6 * 60 * 60 * 1000;
 const lastGood = new Map();
+// 已从磁盘灌入过缓存的 key 指纹, 避免每次请求都读盘
+let hydratedFor = null;
+
+/** 缓存键带上 key 指纹: 换 key 后不会把上一个账号的数据当成兜底值。 */
+function cacheKey(fingerprint, endpoint) {
+  return `${fingerprint}|${endpoint}`;
+}
 
-function cacheGet(key) {
-  const hit = lastGood.get(key);
+function cacheGet(fingerprint, endpoint) {
+  const hit = lastGood.get(cacheKey(fingerprint, endpoint));
   if (!hit) return null;
   if (Date.now() - hit.at > CACHE_TTL_MS) return null;
   return hit;
 }
 
-function cacheSet(key, value) {
+function cacheSet(fingerprint, endpoint, value) {
   if (value === undefined || value === null) return;
-  lastGood.set(key, { value, at: Date.now() });
+  lastGood.set(cacheKey(fingerprint, endpoint), { value, at: Date.now() });
+}
+
+/** key 的短指纹: 落盘只存指纹, 绝不写原始 key。 */
+function keyFingerprint(apiKey) {
+  return createHash("sha256").update(String(apiKey)).digest("hex").slice(0, 16);
+}
+
+function cacheFile() {
+  return join(dshHome(), CACHE_FILE_NAME);
+}
+
+/**
+ * 冷启动兜底: 把上次进程落盘的额度数据读回内存缓存。
+ *
+ * 没有这一步时, DSH 一重启内存缓存就空 —— 此时 credits 单接口失败就没有旧值可退,
+ * 面板会整块空白。只认同一把 key(指纹相同), 过期的条目直接丢弃。
+ */
+function hydrateCache(fingerprint) {
+  if (!fingerprint || hydratedFor === fingerprint) return;
+  hydratedFor = fingerprint;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(cacheFile(), "utf8"));
+  } catch {
+    return;
+  }
+  if (!parsed || parsed.fingerprint !== fingerprint) return;
+  const entries = parsed.entries;
+  if (!entries || typeof entries !== "object") return;
+  for (const endpoint of PERSISTED_ENDPOINTS) {
+    const hit = entries[endpoint];
+    if (!hit || typeof hit.at !== "number") continue;
+    if (Date.now() - hit.at > CACHE_TTL_MS) continue;
+    if (lastGood.has(cacheKey(fingerprint, endpoint))) continue;
+    lastGood.set(cacheKey(fingerprint, endpoint), { value: hit.value, at: hit.at });
+  }
+}
+
+/** 把当前指纹下仍然新鲜的额度快照落盘; 失败静默, 不能影响查询本身。 */
+function persistCache(fingerprint) {
+  const entries = {};
+  for (const endpoint of PERSISTED_ENDPOINTS) {
+    const hit = cacheGet(fingerprint, endpoint);
+    if (hit) entries[endpoint] = hit;
+  }
+  if (Object.keys(entries).length === 0) return;
+  try {
+    const file = cacheFile();
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ fingerprint, entries }, null, 2) + "\n", "utf8");
+  } catch {
+    /* 落盘失败不影响查询 */
+  }
 }
 
 /**
@@ -166,6 +235,8 @@ async function fetchDashboard(cfg, timeoutMs, onlyKeys) {
   const errors = [];
   const stale = [];
   const out = { ok: true, fetchedAt: Date.now(), errors, stale };
+  const fingerprint = keyFingerprint(cfg.apiKey);
+  hydrateCache(fingerprint);
 
   const list = Array.isArray(onlyKeys) && onlyKeys.length > 0
     ? ENDPOINTS.filter(([key]) => onlyKeys.includes(key))
@@ -184,14 +255,14 @@ async function fetchDashboard(cfg, timeoutMs, onlyKeys) {
     const handler = HANDLERS[r.key];
     if (!r.error && r.status === 200 && r.json) {
       handler.apply(r.json, out);
-      cacheSet(r.key, handler.snapshot(out));
+      cacheSet(fingerprint, r.key, handler.snapshot(out));
       continue;
     }
     const message = r.error
       ? `请求失败: ${r.error}`
       : (r.status === 401 ? "API key 无效或无权限 (HTTP 401)" : `HTTP ${r.status}`);
     // 401 是凭据问题, 不能拿旧数据掩盖; 其余失败回退上次成功值。
-    const hit = r.status === 401 ? null : cacheGet(r.key);
+    const hit = r.status === 401 ? null : cacheGet(fingerprint, r.key);
     if (hit) {
       handler.restore(hit.value, out);
       stale.push({ endpoint: r.key, message, at: hit.at });
@@ -205,14 +276,24 @@ async function fetchDashboard(cfg, timeoutMs, onlyKeys) {
   if (skipped.length > 0) {
     out.cached = [];
     for (const [key] of skipped) {
-      const hit = cacheGet(key);
+      const hit = cacheGet(fingerprint, key);
       if (!hit) continue;
       HANDLERS[key].restore(hit.value, out);
       out.cached.push(key);
     }
   }
 
-  if (errors.length >= list.length) out.ok = false;
+  // 落盘: 下次进程启动时 hydrateCache 能把这份快照读回来
+  persistCache(fingerprint);
+
+  if (errors.length >= list.length) {
+    out.ok = false;
+    // 全部失败时必须把具体原因带出去。否则客户端只收到 ok:false、拿不到任何文案,
+    // 面板会被渲染成一块空白(2026-10-29 key 失效时就这么空了一整片)。
+    out.error = `查询失败: ${errors
+      .map((e) => `${ENDPOINT_LABELS[e.endpoint] ?? e.endpoint} ${e.message}`)
+      .join("；")}`;
+  }
   return out;
 }
 

package/test/client.test.cjs

@@ -13,9 +13,9 @@ const fixture = {
   // 月度窗口的重置时间取自订阅周期末，是 ISO 字符串而非毫秒数
   subscription: { status: "active", currentPeriodEnd: new Date(Date.now() + 20 * 86400000).toISOString() },
 };
-function mount({ open = true, data = fixture, failed = false, creds = null } = {}) {
+function mount({ open = true, data = fixture, failed = false, creds = null, gearOpen = false } = {}) {
   let registration, component, slot, stateIndex = 0;
-  const values = [open, data, false, null, creds || { entries: [], apiKeyEnv: null, saving: false, error: null }];
+  const values = [open, data, false, null, creds || { entries: [], apiKeyEnv: null, saving: false, error: null }, gearOpen, null];
   const updates = [], callbacks = [], effects = [], requests = [], timers = [];
   const React = {
     Fragment: "fragment",
@@ -61,8 +61,8 @@ function mount({ open = true, data = fixture, failed = false, creds = null } = {
 async function main() {
   const view = mount();
   const buttons = view.nodes.filter(node => node.type === "button");
-  assert.equal(buttons.length, 3, "只保留状态栏、刷新和关闭按钮，不应存在账号切换按钮");
-  assert.equal(view.stateIndex, 5, "状态：面板开合 / 数据 / 加载 / 错误 / 凭据条目");
+  assert.equal(buttons.length, 4, "状态栏 + 齿轮 + 刷新 + 关闭，不应存在账号切换按钮");
+  assert.equal(view.stateIndex, 7, "状态：面板开合 / 数据 / 加载 / 错误 / 凭据条目 / 凭据设置 / 配色");
   assert.equal(view.callbacks[0].deps.length, 0);
   for (const label of ["5h 10%", "周 20%", "月 30%", "$70.00", "5 小时窗口", "每周窗口", "每月窗口"]) {
     assert.ok(view.texts.includes(label), `保留额度展示：${label}`);
@@ -107,7 +107,7 @@ async function main() {
     ["报错态", { failed: true }],
     ["无数据态", { data: null }],
   ]) {
-    const view2 = mount({ ...options, creds: pickerState });
+    const view2 = mount({ ...options, creds: pickerState, gearOpen: true });
     const selects = view2.nodes.filter((n) => n.type === "select");
     assert.equal(selects.length, 1, `${label}下应能看到凭据条目下拉`);
     const opts = view2.nodes.filter((n) => n.type === "option");
@@ -126,13 +126,13 @@ async function main() {
     assert.equal(selects[0].props.value, "COMMANDCODE2_API_KEY", `${label}下应选中当前条目`);
   }
   // 宿主端读不到供应商时会退化成纯字符串数组，也必须照常工作
-  const plain = mount({ creds: { entries: ["BAILIAN_API_KEY"], apiKeyEnv: null, saving: false, error: null } });
+  const plain = mount({ creds: { entries: ["BAILIAN_API_KEY"], apiKeyEnv: null, saving: false, error: null }, gearOpen: true });
   assert.deepEqual(
     plain.nodes.filter((n) => n.type === "option").map((o) => o.children[0]),
     ["（未设置）", "BAILIAN_API_KEY"],
   );
   // 配置指向一个尚未添加的条目时也要出现在候选里，否则下拉会显示成空白
-  const orphan = mount({ creds: { entries: [{ ref: "OTHER_KEY", provider: null }], apiKeyEnv: "MISSING_KEY", saving: false, error: null } });
+  const orphan = mount({ creds: { entries: [{ ref: "OTHER_KEY", provider: null }], apiKeyEnv: "MISSING_KEY", saving: false, error: null }, gearOpen: true });
   assert.deepEqual(
     orphan.nodes.filter((n) => n.type === "option").map((o) => o.props.value),
     ["", "MISSING_KEY", "OTHER_KEY"],
@@ -140,9 +140,12 @@ async function main() {
   const timerView = mount({ open: false, data: null });
   assert.equal(timerView.nodes.filter(node => node.type === "button").length, 1);
   const cleanup = timerView.effects[0]();
+  // 分层轮询: 余额 3 分钟一次, 用量/订阅 30 分钟一次(重查询不该跟余额同频)
   assert.equal(timerView.timers[0].ms, 3 * 60 * 1000);
+  assert.equal(timerView.timers[1].ms, 30 * 60 * 1000);
   cleanup();
-  assert.equal(timerView.timers[1].cleared, 1);
+  assert.equal(timerView.timers[2].cleared, 1);
+  assert.equal(timerView.timers[3].cleared, 1);
   const failure = mount({ failed: true });
   await failure.callbacks[0].fn();
   assert.ok(failure.updates.some(update => update.index === 3 && update.value.includes("HTTP 503")));

package/test/host.test.cjs

@@ -138,11 +138,22 @@ async function main() {
   const stale = await app.request();
   assert.equal(stale.body.balance.monthlyCredits, 70);
   assert.equal(stale.body.stale.length, 4);
+  // 落盘缓存: 模拟 DSH 重启(新 context, 内存缓存为空)后 credits 失败,
+  // 应该能从磁盘快照回退余额, 而不是让面板空白。
+  const restarted = load();
+  restarted.respond(async () => ({ status: 503, json: async () => ({}) }));
+  const restored = await mount(restarted, config, { PRIMARY_TEST_KEY: "fixture-primary" })
+    .request(DASHBOARD + "?scope=quick");
+  assert.equal(restored.body.balance.monthlyCredits, 70, "重启后应能从落盘缓存回退余额");
+  assert.equal(restored.body.stale.length, 1);
   runtime.respond(async () => ({ status: 401, json: async () => ({}) }));
   const unauthorized = await app.request();
   assert.equal(unauthorized.body.ok, false);
   assert.equal(unauthorized.body.balance, undefined);
   assert.equal(unauthorized.body.errors.length, 4);
+  // 全失败必须带出可读原因, 否则客户端只拿到 ok:false, 面板会渲染成空白
+  assert.ok(unauthorized.body.error.includes("查询失败"), "全失败时应带出可读原因");
+  assert.ok(unauthorized.body.error.includes("余额"), "失败原因应标明是哪个接口");
   runtime.requests.length = 0;
   assert.equal((await app.request(undefined, "POST")).status, 405);
   assert.equal(runtime.requests.length, 0);
@@ -172,6 +183,9 @@ async function main() {
   });
   assert.equal((await mount(retryRuntime, config, { PRIMARY_TEST_KEY: "fixture-primary" }).request(DASHBOARD + "?scope=quick")).body.ok, true);
   assert.equal(attempts, 2);
+  // 超时用例要求「冷启动且无任何可用缓存」: 先清掉落盘快照,
+  // 否则 hydrateCache 会让 credits 兜底成功, 就测不到 ok:false 了。
+  fs.rmSync(join(fakeHome, "dsh-commandcode-quota-cache.json"), { force: true });
   const timeoutRuntime = load();
   timeoutRuntime.respond((url, options) => new Promise((resolve, reject) => {
     options.signal.addEventListener("abort", () => reject(new Error("模拟超时")), { once: true });