dsh-ds-balance 2.1.2 → 2.1.3

package/README.md

@@ -136,7 +136,8 @@ dsh plugin --profile web add "$PWD"
   但**手改配置文件写成的非法组合不会再报错** —— 宿主那一侧已经不再强制它，插件会在读到的那一刻把这一对**回落成默认值**并在日志里记一次。
 
 > **升级提示**：设置项存在插件那一行的配置里，键名跟着宿主升级变过一次，**旧值不会自动迁移** —— 升级后请照上表重填一次。
-- **刷新**：服务端刷新周期与界面轮询周期。
+- **刷新**：服务端刷新周期、界面轮询周期与手动刷新冷却。冷却从**刷完那一刻**起算，
+  浮层上的秒数就是真实剩余；后端说这次没触发，界面按它给的剩余时间收尾，不假装刷过。
 
 保存即生效，不必重启 DSH。
 
@@ -152,6 +153,14 @@ dsh plugin --profile web add "$PWD"
 密钥只经 DSH 的凭据通道解析，卡片里的 `API Key` 一栏默认继承官方模型页配好的那一份，且只读不可改。
 由启动环境（环境变量）提供时，字段只读，徽标写明来源。
 
+**换了 key 多久生效，跟着 DSH 的层走 —— 本插件不额外追：**
+
+- **启动环境（环境变量）给的 key：改了要重启 DSH。** 进程的环境在它启动那一刻就定死了，之后再改外面那个变量，跑着的插件看不到。
+- **在官方模型页 / 凭据库换的 key：不必重启**，最迟下一个服务端刷新周期生效（连续失败退避期间会更久）；想立刻看到就点浮层里的手动刷新（它带冷却）。
+- 生效之前，界面显示的还是**旧账本**的数字 —— 账本标识按 key 派生，新旧不会混，但内存里那份要等下一次抓取成功才被换掉。
+
+为什么这么定 → [关键决策](docs/ARCHITECTURE.md#关键决策)。
+
 ## 安全与边界
 
 - **API Key 永不返回界面**：配置接口只回一个固定长度的掩码串，连末几位也不给。

package/README_en.md

@@ -136,7 +136,7 @@ Open **Plugins → Installed** and step into the **DeepSeek Balance** (shown as
   but a hand-edited config file with an illegal pair **no longer errors** — the Host side stopped enforcing it, so the plugin **falls that pair back to its defaults** the moment it reads it, and logs one line.
 
 > **Upgrade note**: the settings live in this plugin's own entry config and the key it is filed under changed once; **old values are not migrated** — please fill the table above in once after upgrading.
-- **Refresh**: the server refresh interval and the UI poll interval.
+- **Refresh**: the server refresh interval, the UI poll interval and the manual refresh cooldown. The cooldown counts from **the moment the refresh finishes**, so the seconds shown in the popover are the real ones left; if the backend says the refresh did not fire, the UI takes its remaining time instead of pretending otherwise.
 
 Saving applies immediately; there is no need to restart DSH.
 
@@ -152,6 +152,14 @@ Saving applies immediately; there is no need to restart DSH.
 The key is resolved only through DSH's credential channel; the card's "API key" inherits the one already configured on the official model settings page.
 When it comes from the launch environment (an environment variable) the field is read-only and the badge says where it came from.
 
+**How long a key change takes to land follows DSH's own layers — this plugin deliberately adds nothing on top:**
+
+- **A key from the launch environment (an environment variable): restart DSH to change it.** A process's environment is fixed the moment it starts; a later change to that variable outside is invisible to the running plugin.
+- **A key changed on the official model settings page / in the credential store: no restart needed** — it lands by the next server refresh cycle at the latest (later while failure backoff is active); to see it at once, use the manual refresh in the popover (it is rate-limited).
+- Until then the UI still shows the **previous ledger**: the ledger identifier is derived from the key, so the two never mix, but the in-memory copy is only replaced once the next fetch succeeds.
+
+Why it is this way → [Key decisions](docs/ARCHITECTURE.md#关键决策).
+
 ## Security and boundaries
 
 - **The API key is never returned to the UI**: the config endpoint returns only a fixed-length mask, not even the last few characters.

package/lib/client.js

@@ -411,16 +411,7 @@ function SelectorControl(props) {
 }
 function ActionRow(props) {
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
-    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: fields_default.actions, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-      import_dsh_client_ui_primitives.Button,
-      {
-        type: "button",
-        variant: "outline",
-        disabled: props.disabled,
-        onClick: props.onClick,
-        children: props.label
-      }
-    ) }),
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: fields_default.actions, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_dsh_client_ui_primitives.Button, { type: "button", variant: "outline", disabled: props.disabled, onClick: props.onClick, children: props.label }) }),
     props.result === null ? null : (
       // 成功只是通报，用 polite 的 status；失败需要用户处理，按 06 §6.7 的「行内错误」用 alert。
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
@@ -1377,6 +1368,14 @@ function currentAgeMs(seenAt, seenAgeMs, now) {
   const base = Number.isFinite(seenAgeMs) ? Math.max(0, seenAgeMs) : 0;
   return Math.max(0, base + (now - seenAt));
 }
+var MS_PER_SECOND = 1e3;
+function cooldownUntilOf(now, configuredSeconds, rejectedRemainingMs) {
+  const span = rejectedRemainingMs === null ? Math.max(0, configuredSeconds) * MS_PER_SECOND : Math.max(0, rejectedRemainingMs);
+  return now + span;
+}
+function cooldownSecondsOf(until, now) {
+  return Math.max(0, Math.ceil((until - now) / MS_PER_SECOND));
+}
 
 // src/client/mock/scenarios.ts
 var T0 = 176e10;
@@ -1868,8 +1867,8 @@ var REFRESH_SIMULATION_MS = 600;
 var PANEL_GAP = 8;
 var PANEL_MARGIN = 12;
 var MEASURE_STYLE = { visibility: "hidden", left: 0, top: 0 };
-var MS_PER_SECOND = 1e3;
-var TICK_MS = MS_PER_SECOND;
+var MS_PER_SECOND2 = 1e3;
+var TICK_MS = MS_PER_SECOND2;
 function useConfigSlotState(probe) {
   const [state, setState] = (0, import_react5.useState)(() => probe.getSnapshot());
   (0, import_react5.useEffect)(() => {
@@ -1975,7 +1974,7 @@ function SidebarBalance({
       () => {
         void load();
       },
-      Math.max(5, config.clientPollSeconds) * MS_PER_SECOND
+      Math.max(5, config.clientPollSeconds) * MS_PER_SECOND2
     );
     return () => {
       cancelled = true;
@@ -2009,9 +2008,12 @@ function SidebarBalance({
     gap: PANEL_GAP,
     margin: PANEL_MARGIN
   });
-  (0, import_react5.useEffect)(() => {
+  (0, import_react5.useLayoutEffect)(() => {
     if (!open) return;
     setNow(Date.now());
+  }, [open]);
+  (0, import_react5.useEffect)(() => {
+    if (!open) return;
     const id = window.setInterval(() => {
       setNow(Date.now());
     }, TICK_MS);
@@ -2019,6 +2021,17 @@ function SidebarBalance({
       window.clearInterval(id);
     };
   }, [open]);
+  (0, import_react5.useEffect)(() => {
+    if (cooldownUntil === 0) return;
+    const remaining = cooldownUntil - Date.now();
+    if (remaining <= 0) return;
+    const id = window.setTimeout(() => {
+      setNow(Date.now());
+    }, remaining);
+    return () => {
+      window.clearTimeout(id);
+    };
+  }, [cooldownUntil]);
   (0, import_react5.useEffect)(() => {
     if (!open) return;
     const onKeyDown = (event) => {
@@ -2034,30 +2047,34 @@ function SidebarBalance({
     if (refreshing) return;
     if (Date.now() < cooldownUntil) return;
     setRefreshing(true);
-    const finish = () => {
+    const finish = (rejectedRemainingMs) => {
+      const at = Date.now();
       setRefreshing(false);
       setCooldownUntil(
-        Date.now() + Math.max(0, config.manualRefreshCooldownSeconds) * MS_PER_SECOND
+        cooldownUntilOf(at, config.manualRefreshCooldownSeconds, rejectedRemainingMs)
       );
+      setNow(at);
     };
     if (mock) {
       refreshTimer.current = window.setTimeout(() => {
         refreshTimer.current = void 0;
         markFresh();
-        finish();
+        finish(null);
       }, REFRESH_SIMULATION_MS);
       return;
     }
     void (async () => {
+      let rejectedRemainingMs = null;
       try {
-        await requestRefresh({ reason: "manual" });
+        const result = await requestRefresh({ reason: "manual" });
+        if (!result.triggered) rejectedRemainingMs = Math.max(0, result.cooldownMs);
         const next = await requestBalance({ currency: preference });
         loadedRef.current = true;
         acceptBalance(next);
       } catch (error) {
         if (!loadedRef.current) showUnreachable(error);
       } finally {
-        finish();
+        finish(rejectedRemainingMs);
       }
     })();
   }, [
@@ -2110,7 +2127,7 @@ function SidebarBalance({
   if (stateText !== null && stateText !== markerLabel) ariaParts.push(stateText);
   if (markerLabel !== null) ariaParts.push(markerLabel);
   const ariaLabel = ariaParts.join(" ");
-  const cooldownSeconds = Math.max(0, Math.ceil((cooldownUntil - now) / MS_PER_SECOND));
+  const cooldownSeconds = cooldownSecondsOf(cooldownUntil, now);
   const ageMs = currentAgeMs(view.seenAt, view.seenAgeMs, now);
   const ringTitle = !wide && stateText !== null ? `${t("sidebar.aria.ring")} ${stateText}` : void 0;
   const hoverLabel = shown === null ? stateText : formatMoney(shown.total, shown.currency);

package/lib/services/balance-service.d.ts

@@ -61,6 +61,8 @@ export declare class BalanceService {
     private error;
     private failures;
     private retryAfterMs;
+    /** 上一次真的触发过手动刷新的时刻；`null` 表示本进程还没有过。 */
+    private lastManualRefreshAt;
     private inflight;
     /** 落盘失败只报一次，避免每轮刷新都刷屏。 */
     private persistWarned;
@@ -90,6 +92,13 @@ export declare class BalanceService {
      * 手动刷新。
      *
      * 冷却中不触发；已有请求在飞时合并并回报 `joined`。
+     *
+     * **冷却的锚点是「上一次手动刷新」，不是「上一次抓取」**：调度与轮询也在抓，
+     * 拿 `snapshot.fetchedAt` 当锚点的话，一次自动刷新就会把用户刚按下的一下吞掉 ——
+     * 界面转了圈、倒计时也走了，上游却一次没打。
+     *
+     * 时刻取**决定触发那一刻**（不是抓完那一刻）：客户端从「拿到结果那一刻」起算，
+     * 两者相差一个往返 ⇒ 客户端更保守，按钮亮起时按下去一定真的会抓。
      */
     forceRefresh(reason: string): Promise<RefreshResult>;
     /** 快照是否还在 `serverRefreshSeconds` 窗口内。**只看时间，不看状态。** */

package/lib/services/balance-service.js

@@ -21,6 +21,8 @@ export class BalanceService {
     error = null;
     failures = 0;
     retryAfterMs = null;
+    /** 上一次真的触发过手动刷新的时刻；`null` 表示本进程还没有过。 */
+    lastManualRefreshAt = null;
     inflight = null;
     /** 落盘失败只报一次，避免每轮刷新都刷屏。 */
     persistWarned = false;
@@ -92,15 +94,28 @@ export class BalanceService {
      * 手动刷新。
      *
      * 冷却中不触发；已有请求在飞时合并并回报 `joined`。
+     *
+     * **冷却的锚点是「上一次手动刷新」，不是「上一次抓取」**：调度与轮询也在抓，
+     * 拿 `snapshot.fetchedAt` 当锚点的话，一次自动刷新就会把用户刚按下的一下吞掉 ——
+     * 界面转了圈、倒计时也走了，上游却一次没打。
+     *
+     * 时刻取**决定触发那一刻**（不是抓完那一刻）：客户端从「拿到结果那一刻」起算，
+     * 两者相差一个往返 ⇒ 客户端更保守，按钮亮起时按下去一定真的会抓。
      */
     async forceRefresh(reason) {
+        const now = this.options.clock.now();
         const cooldownMs = this.options.config.current().manualRefreshCooldownSeconds * 1000;
-        const since = this.options.clock.now() - (this.snapshot?.fetchedAt ?? 0);
-        if (this.state === 'ok' && since < cooldownMs) {
+        const last = this.lastManualRefreshAt;
+        if (last !== null && now - last < cooldownMs) {
+            const remaining = cooldownMs - (now - last);
             this.metrics.counter('force_rejected_total');
-            this.options.logger?.debug('ds-balance: manual refresh rejected by cooldown', { reason });
-            return { triggered: false, joined: false, cooldownMs: cooldownMs - since, state: this.state };
+            this.options.logger?.debug('ds-balance: manual refresh rejected by cooldown', {
+                reason,
+                cooldownMs: remaining,
+            });
+            return { triggered: false, joined: false, cooldownMs: remaining, state: this.state };
         }
+        this.lastManualRefreshAt = now;
         if (this.inflight !== null) {
             await this.inflight;
             return { triggered: true, joined: true, cooldownMs: 0, state: this.state };

package/lib/services/scheduler.d.ts

@@ -19,6 +19,13 @@ export declare const MAX_BACKOFF_MS = 300000;
 export declare const JITTER_RATIO = 0.2;
 /** 延迟下限，避免忙转。 */
 export declare const MIN_DELAY_MS = 1000;
+/**
+ * 健康态延迟给「这一轮抓取本身」留的余量。
+ *
+ * 延迟是从上一轮**抓完之后**起算的，而抓取要几百毫秒（本机实测到上游一个往返约 0.2 秒）。
+ * 延迟若正好等于缓存窗口，新快照就会晚于窗口过期落地，那个缝里又会出现一次轮询代打的抓取。
+ */
+export declare const SCHEDULE_GUARD_MS = 1000;
 /** 定时器抽象，测试可注入。 */
 export interface SchedulerTimers {
     set(callback: () => void, ms: number): unknown;
@@ -49,6 +56,22 @@ export interface SchedulerOptions {
  * @returns 取整后的毫秒数。
  */
 export declare function jitter(base: number, ratio: number, random: () => number): number;
+/**
+ * 健康态的单边抖动：落在 `[base * (1 - ratio), base - SCHEDULE_GUARD_MS]`。
+ *
+ * **为什么健康态不能用对称抖动**：缓存窗口就是 `serverRefreshSeconds`
+ * （见 `BalanceService.withinWindow`），对称抖动有一半轮次落在窗口**之后** ——
+ * 那段时间里界面一次普通轮询就会自己穿透上游抓一次，紧接着这一轮 tick 又抓一次。
+ * 本机 3608 个快照间隔里 158 对相隔不足 3 秒的连击，其中 117 对前面那格超过 60 秒（窗口已过），
+ * 就是这么来的。单边抖动把「tick 不越过窗口」变成结构保证。
+ *
+ * 退避与缺密钥重试仍走对称的 {@link jitter}：那些分支本来就在窗口外，没有这条不变量。
+ * @param base - 基准毫秒数。
+ * @param ratio - 抖动比例。
+ * @param random - 随机源，返回 `[0, 1)`。
+ * @returns 取整后的毫秒数。
+ */
+export declare function jitterWithin(base: number, ratio: number, random: () => number): number;
 /**
  * 算下一轮该等多久。
  *

package/lib/services/scheduler.js

@@ -19,6 +19,13 @@ export const JITTER_RATIO = 0.2;
 const MAX_BACKOFF_EXPONENT = 10;
 /** 延迟下限，避免忙转。 */
 export const MIN_DELAY_MS = 1000;
+/**
+ * 健康态延迟给「这一轮抓取本身」留的余量。
+ *
+ * 延迟是从上一轮**抓完之后**起算的，而抓取要几百毫秒（本机实测到上游一个往返约 0.2 秒）。
+ * 延迟若正好等于缓存窗口，新快照就会晚于窗口过期落地，那个缝里又会出现一次轮询代打的抓取。
+ */
+export const SCHEDULE_GUARD_MS = 1000;
 /** 把值夹到区间内。 */
 function clamp(value, min, max) {
     return Math.min(max, Math.max(min, value));
@@ -35,6 +42,26 @@ export function jitter(base, ratio, random) {
     const span = base * ratio * 2;
     return Math.floor(min + random() * span);
 }
+/**
+ * 健康态的单边抖动：落在 `[base * (1 - ratio), base - SCHEDULE_GUARD_MS]`。
+ *
+ * **为什么健康态不能用对称抖动**：缓存窗口就是 `serverRefreshSeconds`
+ * （见 `BalanceService.withinWindow`），对称抖动有一半轮次落在窗口**之后** ——
+ * 那段时间里界面一次普通轮询就会自己穿透上游抓一次，紧接着这一轮 tick 又抓一次。
+ * 本机 3608 个快照间隔里 158 对相隔不足 3 秒的连击，其中 117 对前面那格超过 60 秒（窗口已过），
+ * 就是这么来的。单边抖动把「tick 不越过窗口」变成结构保证。
+ *
+ * 退避与缺密钥重试仍走对称的 {@link jitter}：那些分支本来就在窗口外，没有这条不变量。
+ * @param base - 基准毫秒数。
+ * @param ratio - 抖动比例。
+ * @param random - 随机源，返回 `[0, 1)`。
+ * @returns 取整后的毫秒数。
+ */
+export function jitterWithin(base, ratio, random) {
+    const upper = Math.max(MIN_DELAY_MS, base - SCHEDULE_GUARD_MS);
+    const lower = Math.min(upper, Math.max(MIN_DELAY_MS, base * (1 - ratio)));
+    return Math.floor(lower + (upper - lower) * random());
+}
 /**
  * 算下一轮该等多久。
  *
@@ -55,7 +82,7 @@ export function nextDelayMs(status, options = {}) {
         const exponent = Math.min(Math.max(0, status.consecutiveFailures - 1), MAX_BACKOFF_EXPONENT);
         return jitter(Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** exponent), JITTER_RATIO, random);
     }
-    return jitter(Math.max(MIN_DELAY_MS, status.serverRefreshSeconds * 1000), JITTER_RATIO, random);
+    return jitterWithin(Math.max(MIN_DELAY_MS, status.serverRefreshSeconds * 1000), JITTER_RATIO, random);
 }
 /** 真正的默认定时器。 */
 const defaultTimers = {

package/lib/types/client/model.d.ts

@@ -103,3 +103,28 @@ export declare function ageBucket(ageMs: number): {
  * @returns 毫秒计的当前年龄；基准缺失时按 0 算。
  */
 export declare function currentAgeMs(seenAt: number, seenAgeMs: number, now: number): number;
+/**
+ * 一次手动刷新之后的冷却截止时刻。
+ *
+ * **基准是「拿到结果那一刻」**，不是点击那一刻：后端的手动冷却从它收到请求起算，
+ * 客户端晚一个往返才起算 ⇒ 客户端永远比后端保守，按钮亮起来时按下去一定真的会抓。
+ *
+ * 返回的是**精确时刻**；调用方必须把展示用的「现在」与它设成同一刻（见
+ * {@link cooldownSecondsOf}）。
+ * @param now - 拿到结果那一刻的本地时刻（毫秒）。
+ * @param configuredSeconds - 配置里的手动刷新冷却秒数。
+ * @param rejectedRemainingMs - 后端拒绝（`triggered: false`）时给出的剩余毫秒；`null` 表示这次真的触发了。
+ * @returns 冷却截止的本地时刻（毫秒）。
+ */
+export declare function cooldownUntilOf(now: number, configuredSeconds: number, rejectedRemainingMs: number | null): number;
+/**
+ * 冷却剩余秒数，向上取整。
+ *
+ * **`now` 必须与设定截止时刻时用的是同一刻**：截止是精确时刻，而界面里的「现在」是每秒
+ * 采样一次的状态；拿一个最多旧一秒的值去取整，5 秒的冷却会显示成 6 秒 ——
+ * 更糟的是按钮的禁用判据也是这个值，等于真的多禁一秒。
+ * @param until - 冷却截止的本地时刻（毫秒）；0 表示没有冷却。
+ * @param now - 当前本地时刻（毫秒）。
+ * @returns 剩余秒数；已过期或没有冷却时为 0。
+ */
+export declare function cooldownSecondsOf(until: number, now: number): number;

package/lib/version.d.ts

@@ -8,5 +8,5 @@
 /** 线上 schema 版本。响应里逐条回传，消费方据此判断兼容性。 */
 export declare const SCHEMA_VERSION = 1;
 /** 插件版本。与 `package.json` 的 `version` 一致（有测试兜底）。 */
-export declare const PLUGIN_VERSION = "2.1.2";
+export declare const PLUGIN_VERSION = "2.1.3";
 //# sourceMappingURL=version.d.ts.map

package/lib/version.js

@@ -8,5 +8,5 @@
 /** 线上 schema 版本。响应里逐条回传，消费方据此判断兼容性。 */
 export const SCHEMA_VERSION = 1;
 /** 插件版本。与 `package.json` 的 `version` 一致（有测试兜底）。 */
-export const PLUGIN_VERSION = '2.1.2';
+export const PLUGIN_VERSION = '2.1.3';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ds-balance",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "icon": "./icon.svg",
   "description": "DSH plugin: shows the DeepSeek account balance at the bottom of the sidebar, with a configuration card on the Plugins page.",
   "keywords": [