dsh-ds-balance 2.1.1 → 2.1.3

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="icon.svg" alt="dsh-ds-balance" width="80" height="80">
+</p>
+
 <p align="center">
   <h1 align="center">dsh-ds-balance</h1>
 </p>
@@ -132,7 +136,8 @@ dsh plugin --profile web add "$PWD"
   但**手改配置文件写成的非法组合不会再报错** —— 宿主那一侧已经不再强制它，插件会在读到的那一刻把这一对**回落成默认值**并在日志里记一次。
 
 > **升级提示**：设置项存在插件那一行的配置里，键名跟着宿主升级变过一次，**旧值不会自动迁移** —— 升级后请照上表重填一次。
-- **刷新**：服务端刷新周期与界面轮询周期。
+- **刷新**：服务端刷新周期、界面轮询周期与手动刷新冷却。冷却从**刷完那一刻**起算，
+  浮层上的秒数就是真实剩余；后端说这次没触发，界面按它给的剩余时间收尾，不假装刷过。
 
 保存即生效，不必重启 DSH。
 
@@ -148,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

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="icon.svg" alt="dsh-ds-balance" width="80" height="80">
+</p>
+
 <p align="center">
   <h1 align="center">dsh-ds-balance</h1>
 </p>
@@ -132,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.
 
@@ -148,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/adapters/console-logger.js

@@ -26,10 +26,18 @@ function render(fields) {
  */
 export function createConsoleLogger(sink = console) {
     return {
-        debug: (message, fields) => { sink.debug(`${LOG_PREFIX} ${message}${render(fields)}`); },
-        info: (message, fields) => { sink.info(`${LOG_PREFIX} ${message}${render(fields)}`); },
-        warn: (message, fields) => { sink.warn(`${LOG_PREFIX} ${message}${render(fields)}`); },
-        error: (message, fields) => { sink.error(`${LOG_PREFIX} ${message}${render(fields)}`); },
+        debug: (message, fields) => {
+            sink.debug(`${LOG_PREFIX} ${message}${render(fields)}`);
+        },
+        info: (message, fields) => {
+            sink.info(`${LOG_PREFIX} ${message}${render(fields)}`);
+        },
+        warn: (message, fields) => {
+            sink.warn(`${LOG_PREFIX} ${message}${render(fields)}`);
+        },
+        error: (message, fields) => {
+            sink.error(`${LOG_PREFIX} ${message}${render(fields)}`);
+        },
     };
 }
 //# sourceMappingURL=console-logger.js.map

package/lib/adapters/domain-core-store.js

@@ -111,7 +111,9 @@ export class DomainCoreStore {
                 this.ready = null;
                 if (!this.openFailureLogged) {
                     this.openFailureLogged = true;
-                    this.options.logger?.error('ds-balance: storage domain unavailable, running degraded', { error: describeError(error) });
+                    this.options.logger?.error('ds-balance: storage domain unavailable, running degraded', {
+                        error: describeError(error),
+                    });
                 }
             });
             this.ready = attempt;
@@ -128,7 +130,9 @@ export class DomainCoreStore {
     async requireTable() {
         await this.ensureOpen();
         if (this.openError !== undefined) {
-            throw new StorageError(`storage domain unavailable: ${describeError(this.openError)}`, { cause: this.openError });
+            throw new StorageError(`storage domain unavailable: ${describeError(this.openError)}`, {
+                cause: this.openError,
+            });
         }
         if (this.table === null)
             throw new StorageError('storage domain is not open');
@@ -160,7 +164,9 @@ export class DomainCoreStore {
         if (this.closed)
             return { ok: false, detail: 'closed' };
         await this.ensureOpen();
-        return this.openError === undefined ? { ok: true } : { ok: false, detail: describeError(this.openError) };
+        return this.openError === undefined
+            ? { ok: true }
+            : { ok: false, detail: describeError(this.openError) };
     }
     /** 幂等关闭。**必须挂在 `ctx.effect` 的 disposer 上。** */
     async close() {

package/lib/adapters/http-deepseek-client.js

@@ -2,7 +2,7 @@
  * DeepSeek 上游的 HTTP 实现。
  * @module dsh-ds-balance/adapters/http-deepseek-client
  */
-import { NetworkError, ParseError, TimeoutError, UpstreamError, classify, describeError } from '../domain/errors.js';
+import { NetworkError, ParseError, TimeoutError, UpstreamError, classify, describeError, } from '../domain/errors.js';
 import { parseErrorBody } from '../domain/normalize.js';
 /** 去掉尾部斜杠，避免拼出双斜杠路径。 */
 function joinUrl(baseUrl, path) {
@@ -39,13 +39,21 @@ export class HttpDeepSeekClient {
             const raw = await this.fetchBalance(options);
             const latencyMs = this.now() - startedAt;
             const balances = Array.isArray(raw?.balance_infos)
-                ? raw.balance_infos.map((item) => ({ currency: String(item.currency), total: String(item.total_balance) }))
+                ? raw.balance_infos.map((item) => ({
+                    currency: String(item.currency),
+                    total: String(item.total_balance),
+                }))
                 : [];
             return { ok: true, latencyMs, isAvailable: raw?.is_available === true, balances };
         }
         catch (error) {
             const info = classify(error);
-            return { ok: false, latencyMs: this.now() - startedAt, code: info.code, message: info.message };
+            return {
+                ok: false,
+                latencyMs: this.now() - startedAt,
+                code: info.code,
+                message: info.message,
+            };
         }
     }
     /**
@@ -61,7 +69,9 @@ export class HttpDeepSeekClient {
             timedOut = true;
             controller.abort();
         }, options.timeoutMs);
-        const forwardAbort = () => { controller.abort(); };
+        const forwardAbort = () => {
+            controller.abort();
+        };
         options.signal?.addEventListener('abort', forwardAbort, { once: true });
         let response;
         try {

package/lib/adapters/salt-file.js

@@ -20,8 +20,12 @@ export const SALT_ENCODING = 'hex';
  */
 export async function loadOrCreateSalt(options) {
     const read = options.read ?? (async (path) => readFile(path, 'utf8'));
-    const write = options.write ?? (async (path, data, mode) => writeFile(path, data, { mode }));
-    const makeDir = options.makeDir ?? (async (path) => { await mkdir(path, { recursive: true }); });
+    const write = options.write ??
+        (async (path, data, mode) => writeFile(path, data, { mode }));
+    const makeDir = options.makeDir ??
+        (async (path) => {
+            await mkdir(path, { recursive: true });
+        });
     const random = options.random ?? ((bytes) => randomBytes(bytes).toString(SALT_ENCODING));
     try {
         const existing = (await read(options.path)).trim();