dsh-ds-balance 2.1.3 → 2.2.0

package/lib/services/balance-source.js

@@ -0,0 +1,294 @@
+/**
+ * 一个取数来源的账本：快照、状态机、抓取与落盘。
+ *
+ * 职责：把「读一次 → 归一化 → 落快照」包成一次可合并的请求，并维护这一条路自己的缓存状态。
+ * **对外永不抛错**：一切失败都变成 `view.state` 与 `view.error`。
+ *
+ * 两条路（API Key / 账号登录）各持一份账本，互不影响 —— 谁的失败都不该拖累另一条。
+ * @module dsh-ds-balance/services/balance-source
+ */
+import { classify, describeError, parseRetryAfter, } from '../domain/errors.js';
+import { normalize } from '../domain/normalize.js';
+import { pickBalance } from '../domain/select.js';
+import { severityOf, thresholdsFor } from '../domain/severity.js';
+import { situationOf } from '../domain/situation.js';
+import { noopMetrics } from '../ports/metrics.js';
+import { accountTag8 } from './account-tag.js';
+/** 一条路的账本。 */
+export class SourceLedger {
+    options;
+    metrics;
+    snapshot = null;
+    state = 'empty';
+    error = null;
+    failures = 0;
+    retryAfterMs = null;
+    /** 上一次真的触发过手动刷新的时刻；`null` 表示本账本还没有过。 */
+    lastManualRefreshAt = null;
+    inflight = null;
+    /** 落盘失败只报一次，避免每轮刷新都刷屏。 */
+    persistWarned = false;
+    constructor(options) {
+        this.options = options;
+        this.metrics = options.metrics ?? noopMetrics;
+    }
+    /** 这条路的 id。 */
+    source() {
+        return this.options.source;
+    }
+    /** 这条路的凭据此刻可用吗。 */
+    available() {
+        return this.options.reader.available();
+    }
+    /** 当前状态切片，供调度与健康检查使用。 */
+    status() {
+        // 处境判定的四个事实与 `toView` 同源：这里也现算一次挑币种，不走第二套规则。
+        const preference = this.options.config.current().displayCurrency;
+        const selected = this.snapshot === null ? null : pickBalance(this.snapshot.balances, preference);
+        return {
+            source: this.options.source,
+            state: this.state,
+            errorCode: this.error?.code ?? null,
+            consecutiveFailures: this.failures,
+            hasSnapshot: this.snapshot !== null,
+            serverRefreshSeconds: this.options.config.current().serverRefreshSeconds,
+            retryAfterMs: this.retryAfterMs,
+            lastSuccessAt: this.snapshot?.fetchedAt ?? null,
+            isAvailable: this.snapshot?.isAvailable ?? false,
+            hasSelected: selected !== null,
+            severity: this.severityOf(selected),
+        };
+    }
+    /**
+     * 当前账本标识的前 8 位；还没有快照时是 `null`。
+     *
+     * **只回前 8 位**：完整 tag 是账本作用域标识，没有对外的理由。
+     */
+    accountTag8() {
+        const tag = this.snapshot?.accountTag;
+        return tag === undefined ? null : accountTag8(tag);
+    }
+    /**
+     * 从存储恢复最近快照（这条账本第一次被用到时调一次）。
+     *
+     * **按 `accountTag` 过滤**：凭据轮换后 tag 变了，旧快照视为不存在，不混用。
+     * 没有凭据可算 tag 时静默跳过。
+     */
+    async restore() {
+        try {
+            const accountTag = await this.options.reader.tag();
+            const stored = await this.options.store.loadLatestSnapshot(accountTag);
+            if (stored === null)
+                return;
+            this.snapshot = stored;
+            this.state = this.withinWindow() ? 'ok' : 'stale';
+            this.publishGauge();
+        }
+        catch (error) {
+            this.options.logger?.debug('ds-balance: no snapshot restored', {
+                source: this.options.source,
+                error: describeError(error),
+            });
+        }
+    }
+    /**
+     * 取当前视图。
+     *
+     * 有在飞的请求就合并；不 force 且未过期就返回缓存；否则拉一次。
+     */
+    async getView(options = {}) {
+        if (this.inflight !== null)
+            return this.inflight;
+        if (options.force !== true && this.canServeCache())
+            return this.toView(options.currency);
+        const run = this.fetchOnce(options.currency).finally(() => {
+            this.inflight = null;
+        });
+        this.inflight = run;
+        return run;
+    }
+    /**
+     * 手动刷新。
+     *
+     * 冷却中不触发；已有请求在飞时合并并回报 `joined`。
+     *
+     * **冷却的锚点是「上一次手动刷新」，不是「上一次抓取」**：调度与轮询也在抓，
+     * 拿 `snapshot.fetchedAt` 当锚点的话，一次自动刷新就会把用户刚按下的一下吞掉 ——
+     * 界面转了圈、倒计时也走了，上游却一次没打。
+     *
+     * 时刻取**决定触发那一刻**（不是抓完那一刻）：客户端从「拿到结果那一刻」起算，
+     * 两者相差一个往返 ⇒ 客户端更保守，按钮亮起时按下去一定真的会抓。
+     */
+    async forceRefresh(reason) {
+        const now = this.options.clock.now();
+        const cooldownMs = this.options.config.current().manualRefreshCooldownSeconds * 1000;
+        const last = this.lastManualRefreshAt;
+        if (last !== null && now - last < cooldownMs) {
+            const remaining = cooldownMs - (now - last);
+            this.metrics.counter('force_rejected_total', { source: this.options.source });
+            this.options.logger?.debug('ds-balance: manual refresh rejected by cooldown', {
+                source: this.options.source,
+                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 };
+        }
+        await this.getView({ force: true });
+        return { triggered: true, joined: false, cooldownMs: 0, state: this.state };
+    }
+    /** 快照是否还在 `serverRefreshSeconds` 窗口内。**只看时间，不看状态。** */
+    withinWindow() {
+        if (this.snapshot === null)
+            return false;
+        const window = this.options.config.current().serverRefreshSeconds * 1000;
+        return this.options.clock.now() - this.snapshot.fetchedAt < window;
+    }
+    /**
+     * 能否直接拿缓存顶上。
+     *
+     * 与 {@link withinWindow} 分开：`restore` 要在状态还是 `empty` 时用纯时间判据，
+     * 而这里必须要求 `ok` —— 否则一次失败之后，窗口内的旧快照会让 `getView`
+     * 永远不再重试。
+     */
+    canServeCache() {
+        return this.state === 'ok' && this.withinWindow();
+    }
+    /** 跑一次真实抓取。**所有异常都在这里被吸收。** */
+    async fetchOnce(currency) {
+        const startedAt = this.options.clock.now();
+        try {
+            const { raw, accountTag } = await this.options.reader.read();
+            const snapshot = normalize(raw, accountTag, this.options.clock.now(), this.options.source);
+            // 落盘失败不算这次抓取失败：快照留在内存里，界面照常显示，
+            // 代价只是重启后不恢复。存储是可降级的一层。
+            await this.persist(snapshot);
+            this.snapshot = snapshot;
+            this.state = 'ok';
+            this.error = null;
+            this.failures = 0;
+            this.retryAfterMs = null;
+            this.count('ok');
+            this.observe(this.options.clock.now() - startedAt);
+            this.publishGauge();
+            return this.toView(currency);
+        }
+        catch (error) {
+            this.applyFailure(error, startedAt);
+            return this.toView(currency);
+        }
+    }
+    /**
+     * 把快照落盘。
+     *
+     * **失败只记一次 warn，不往上抛**：存储层降级不该让整个余额功能不可用。
+     * @param snapshot - 刚归一化出来的快照。
+     */
+    async persist(snapshot) {
+        try {
+            await this.options.store.saveSnapshot(snapshot);
+        }
+        catch (error) {
+            if (this.persistWarned)
+                return;
+            this.persistWarned = true;
+            this.options.logger?.warn('ds-balance: snapshot not persisted, continuing in memory', {
+                source: this.options.source,
+                error: describeError(error),
+            });
+        }
+    }
+    /** 记录一次失败，并把状态推到 `stale` 或 `error`。 */
+    applyFailure(error, startedAt) {
+        const info = classify(error);
+        this.failures += 1;
+        this.error = info;
+        this.state = this.snapshot === null ? 'error' : 'stale';
+        this.retryAfterMs = retryAfterOf(error, this.options.clock.now());
+        // 只在首次失败打 warn，避免日志刷屏。
+        if (this.failures === 1) {
+            this.options.logger?.warn('ds-balance: balance fetch failed', {
+                source: this.options.source,
+                code: info.code,
+            });
+        }
+        this.count('error');
+        this.observe(this.options.clock.now() - startedAt);
+        this.publishGauge();
+    }
+    /** 记一次抓取耗时（带上来源标签，两条路各自可看）。 */
+    observe(durationMs) {
+        this.metrics.histogram('balance_fetch_duration_ms', { source: this.options.source }, durationMs);
+    }
+    /** 记一次抓取结果。 */
+    count(result) {
+        this.metrics.counter('balance_fetch_total', { result, source: this.options.source });
+    }
+    /** 把缓存状态推成指标。 */
+    publishGauge() {
+        this.metrics.gauge('cache_state', { state: this.state, source: this.options.source }, 1);
+    }
+    /** 把缓存折成对外视图。 */
+    toView(currency) {
+        const config = this.options.config.current();
+        const thresholds = this.options.config.thresholds();
+        const preference = currency ?? config.displayCurrency;
+        const selected = this.snapshot === null ? null : pickBalance(this.snapshot.balances, preference);
+        const severity = this.severityOf(selected);
+        return {
+            source: this.options.source,
+            // 处境由事实一次判出；界面拿它当唯一分支入口。
+            situation: situationOf({
+                hasSnapshot: this.snapshot !== null,
+                stale: this.state === 'stale',
+                isAvailable: this.snapshot?.isAvailable ?? false,
+                hasSelected: selected !== null,
+                severity,
+                errorCode: this.error?.code ?? null,
+            }),
+            state: this.state,
+            stale: this.state === 'stale',
+            fetchedAt: this.snapshot?.fetchedAt ?? null,
+            ageMs: this.snapshot === null
+                ? null
+                : Math.max(0, this.options.clock.now() - this.snapshot.fetchedAt),
+            isAvailable: this.snapshot?.isAvailable ?? null,
+            balances: this.snapshot?.balances ?? [],
+            selected: selected === null ? null : { currency: selected.currency, total: selected.total },
+            severity,
+            thresholds,
+            error: this.state === 'ok' ? null : this.error,
+        };
+    }
+    /**
+     * 这一份视图的严重度。
+     *
+     * **只服务环的颜色与弧长**；「处境」是另一个维度，由 {@link situationOf} 判，
+     * 两者不再各自决定界面形态（历史上它们是两条互相打架的链）。
+     * @param selected - 选中币种的那条余额；没快照时是 `null`。
+     * @returns 严重度。
+     */
+    severityOf(selected) {
+        if (this.snapshot === null) {
+            // 没有快照时只有两种事实：没接入（空环）与读不到（叉）。
+            // 具体是哪一种由处境层判，这里给的 severity 只保证颜色不撒谎。
+            return this.error?.code === 'NO_KEY' ? 'unknown' : 'unavailable';
+        }
+        const thresholds = this.options.config.thresholds();
+        return severityOf(selected, this.snapshot?.isAvailable ?? false, thresholdsFor(selected?.currency ?? '', thresholds));
+    }
+}
+/** 从上游错误里抽 `Retry-After`；抽不到返回 `null`。 */
+function retryAfterOf(error, now) {
+    if (typeof error !== 'object' || error === null || !('headers' in error))
+        return null;
+    const headers = error.headers;
+    if (!(headers instanceof Headers))
+        return null;
+    return parseRetryAfter(headers, now) ?? null;
+}
+//# sourceMappingURL=balance-source.js.map

package/lib/services/scheduler.d.ts

@@ -7,7 +7,7 @@
  */
 import type { BalanceView } from '../domain/balance.js';
 import type { Logger } from '../ports/logger.js';
-import type { BalanceStatus, GetViewOptions } from './balance-service.js';
+import type { BalanceStatus } from './balance-service.js';
 /** 首拉延迟。 */
 export declare const INITIAL_DELAY_MS = 1000;
 /** 缺密钥时的快速重试间隔。 */
@@ -33,7 +33,13 @@ export interface SchedulerTimers {
 }
 /** 调度器需要的最小服务面。 */
 export interface SchedulerTarget {
-    getView(options?: GetViewOptions): Promise<BalanceView>;
+    /**
+     * 抓一轮**当前活跃来源**。
+     *
+     * 调度**不重新解析来源**：节拍属于「这份数据」，不属于某一次请求 —— 每轮都按全局默认重算的话，
+     * 会话级的来源会被无声地顶掉。
+     */
+    refreshActive(): Promise<BalanceView>;
     status(): BalanceStatus;
 }
 /** 构造参数。 */

package/lib/services/scheduler.js

@@ -158,7 +158,7 @@ export class Scheduler {
         if (!this.running)
             return;
         try {
-            await this.options.target.getView({ force: true });
+            await this.options.target.refreshActive();
         }
         catch (error) {
             // 服务承诺永不抛错；这里是防御，不让调度链断掉。

package/lib/services/source-readers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 两条取数路的读取策略。
+ *
+ * 账本（{@link SourceLedger}）只认这个接口，不认凭据、不认 HTTP —— 换来源就是换一个 reader。
+ * 三个方法都是**本地读**，只有 `read()` 会打上游。
+ * @module dsh-ds-balance/services/source-readers
+ */
+import type { AccountSource } from '../ports/account.js';
+import type { DeepSeekClient } from '../ports/deepseek-client.js';
+import type { SourceReader } from './balance-source.js';
+import type { ConfigService } from './config-service.js';
+import type { KeyResolver } from './key-resolver.js';
+/** Key 那条路：解析链拿明文密钥 → 官方余额端点。 */
+export declare function keyReader(options: {
+    keys: KeyResolver;
+    client: DeepSeekClient;
+    config: ConfigService;
+    salt: string;
+}): SourceReader;
+/** 账号那条路：登录态 → 钱包查询 → 投影成官方余额端点同一个形状。 */
+export declare function accountReader(options: {
+    /** 取当前端口实现；服务可能晚到，所以这里必须是函数而不是实例。 */
+    account: () => AccountSource | undefined;
+    salt: string;
+}): SourceReader;
+//# sourceMappingURL=source-readers.d.ts.map

package/lib/services/source-readers.js

@@ -0,0 +1,73 @@
+/**
+ * 两条取数路的读取策略。
+ *
+ * 账本（{@link SourceLedger}）只认这个接口，不认凭据、不认 HTTP —— 换来源就是换一个 reader。
+ * 三个方法都是**本地读**，只有 `read()` 会打上游。
+ * @module dsh-ds-balance/services/source-readers
+ */
+import { endpointOf } from '../config.js';
+import { projectAccountBalance } from '../domain/account.js';
+import { NoKeyError } from '../domain/errors.js';
+import { computeAccountTag } from './account-tag.js';
+/** Key 那条路：解析链拿明文密钥 → 官方余额端点。 */
+export function keyReader(options) {
+    const { keys, client, config, salt } = options;
+    return {
+        async available() {
+            try {
+                await keys.resolve();
+                return true;
+            }
+            catch {
+                // 解析链没取到值就是「这条路此刻不可用」，不是错误：上层据此回落另一条。
+                return false;
+            }
+        },
+        async tag() {
+            return computeAccountTag(salt, await keys.resolve());
+        },
+        async read() {
+            const apiKey = await keys.resolve();
+            const current = config.current();
+            const raw = await client.fetchBalance({
+                baseUrl: endpointOf(current),
+                apiKey,
+                timeoutMs: config.timeoutMs(),
+            });
+            return { raw, accountTag: computeAccountTag(salt, apiKey) };
+        },
+    };
+}
+/** 账号那条路：登录态 → 钱包查询 → 投影成官方余额端点同一个形状。 */
+export function accountReader(options) {
+    const { account, salt } = options;
+    const require = () => {
+        const current = account();
+        if (current === undefined)
+            throw new NoKeyError('no credential: account service is unavailable');
+        return current;
+    };
+    /**
+     * 账号账本的派生输入。
+     *
+     * 用 `account:` 前缀把两个键空间分开：账号 id 与明文密钥因此不可能撞到同一个账本。
+     * 宿主本进程还没读过 profile 时 id 拿不到，退回 `unknown` —— 代价是那种情况下换账号不换账本，
+     * 由下一轮抓取修正（见决策记录的「已知代价」）。
+     */
+    const tagOf = async () => computeAccountTag(salt, `account:${(await require().accountId()) ?? 'unknown'}`);
+    return {
+        async available() {
+            const current = account();
+            return current !== undefined && (await current.signedIn());
+        },
+        tag: tagOf,
+        async read() {
+            const balance = await require().readBalance();
+            // `null` = 查询途中凭据被换掉/登出：此刻这条路的凭据没了，与「没有密钥」同一类事实。
+            if (balance === null)
+                throw new NoKeyError('no credential: account is not signed in');
+            return { raw: projectAccountBalance(balance), accountTag: await tagOf() };
+        },
+    };
+}
+//# sourceMappingURL=source-readers.js.map

package/lib/services/source-selector.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 取数来源选择。纯函数，没有 `ctx`、没有 I/O。
+ *
+ * **本文件是「新增一个来源」要动的唯一一处逻辑**：加一行 `ROUTED`、把新来源排进
+ * `FALLBACK_ORDER`，再在装配处多建一份账本（reader + ledger）。账本状态机、调度、HTTP、
+ * 界面都不认识具体来源 —— 它们只认 {@link BalanceSource} 这个闭集与「哪条此刻活跃」。
+ *
+ * 规则是**四层回落**：
+ * 1. 当前会话的路由（客户端把会话级选择当提示带上来的）；
+ * 2. 全局默认路由（提示缺席时宿主自己读）；
+ * 3. 固定顺序（`FALLBACK_ORDER`）；
+ * 4. 一条都不可用：回 {@link DEFAULT_SOURCE}，让它自然报 `NO_KEY`（与只有一条路时逐字相同）。
+ *
+ * 完整判据见 [决策记录](../../.agents/notes/2026-09-30-account-balance-source.md)。
+ * @module dsh-ds-balance/services/source-selector
+ */
+import type { BalanceSource } from '../domain/balance.js';
+/** API Key 那条路的宿主 provider id。 */
+export declare const KEY_PROVIDER = "deepseek-official";
+/** 账号登录那条路的宿主 provider id。 */
+export declare const ACCOUNT_PROVIDER = "deepseek-account";
+/**
+ * 路由都指不出该走哪条时的固定顺序：**排在前的先被选中**。
+ *
+ * Key 优先是刻意的：它让「今天能用的用户」数字一字不变 —— 账号那条路是补上断掉的那条，
+ * 不是抢走已经在用的那条。
+ */
+export declare const FALLBACK_ORDER: readonly BalanceSource[];
+/** 一条都不可用时回落到谁。挑 Key 那条，因为它的 `NO_KEY` 文案是既有用户认识的那句。 */
+export declare const DEFAULT_SOURCE: BalanceSource;
+/** 路由判出来的来源；`'other'` 表示当前跑在别家供应商上（两条官方路都没在用）。 */
+export type RoutedSource = BalanceSource | 'other' | null;
+/**
+ * 把宿主 provider id 翻成我们认的来源。
+ *
+ * **只认 {@link ROUTED} 里列出的两条**：别家的余额插件够不着，也不该去猜。
+ * @param provider - 宿主给的路由 id；读不到时传 `null`。
+ * @returns 认得的来源，或 `'other'` / `null`。
+ */
+export declare function routeOf(provider: string | null | undefined): RoutedSource;
+/**
+ * 选这一轮走哪条路。
+ * @param input - 路由判据，以及逐来源的可用性（由门面从各账本问出来）。
+ * @returns 要用的来源。
+ */
+export declare function pickSource(input: {
+    routed: RoutedSource;
+    available: (source: BalanceSource) => boolean;
+}): BalanceSource;
+//# sourceMappingURL=source-selector.d.ts.map

package/lib/services/source-selector.js

@@ -0,0 +1,64 @@
+/**
+ * 取数来源选择。纯函数，没有 `ctx`、没有 I/O。
+ *
+ * **本文件是「新增一个来源」要动的唯一一处逻辑**：加一行 `ROUTED`、把新来源排进
+ * `FALLBACK_ORDER`，再在装配处多建一份账本（reader + ledger）。账本状态机、调度、HTTP、
+ * 界面都不认识具体来源 —— 它们只认 {@link BalanceSource} 这个闭集与「哪条此刻活跃」。
+ *
+ * 规则是**四层回落**：
+ * 1. 当前会话的路由（客户端把会话级选择当提示带上来的）；
+ * 2. 全局默认路由（提示缺席时宿主自己读）；
+ * 3. 固定顺序（`FALLBACK_ORDER`）；
+ * 4. 一条都不可用：回 {@link DEFAULT_SOURCE}，让它自然报 `NO_KEY`（与只有一条路时逐字相同）。
+ *
+ * 完整判据见 [决策记录](../../.agents/notes/2026-09-30-account-balance-source.md)。
+ * @module dsh-ds-balance/services/source-selector
+ */
+/** API Key 那条路的宿主 provider id。 */
+export const KEY_PROVIDER = 'deepseek-official';
+/** 账号登录那条路的宿主 provider id。 */
+export const ACCOUNT_PROVIDER = 'deepseek-account';
+/** 宿主 provider id → 本插件的取数来源。**认得的路只有这里列出的**。 */
+const ROUTED = {
+    // 官方余额端点那条：凭据是 API Key（解析链见 KeyResolver）。
+    [KEY_PROVIDER]: 'deepseek-http',
+    // 宿主账号服务那条：凭据是账号登录态。
+    [ACCOUNT_PROVIDER]: 'deepseek-account',
+};
+/**
+ * 路由都指不出该走哪条时的固定顺序：**排在前的先被选中**。
+ *
+ * Key 优先是刻意的：它让「今天能用的用户」数字一字不变 —— 账号那条路是补上断掉的那条，
+ * 不是抢走已经在用的那条。
+ */
+export const FALLBACK_ORDER = ['deepseek-http', 'deepseek-account'];
+/** 一条都不可用时回落到谁。挑 Key 那条，因为它的 `NO_KEY` 文案是既有用户认识的那句。 */
+export const DEFAULT_SOURCE = 'deepseek-http';
+/**
+ * 把宿主 provider id 翻成我们认的来源。
+ *
+ * **只认 {@link ROUTED} 里列出的两条**：别家的余额插件够不着，也不该去猜。
+ * @param provider - 宿主给的路由 id；读不到时传 `null`。
+ * @returns 认得的来源，或 `'other'` / `null`。
+ */
+export function routeOf(provider) {
+    if (provider === null || provider === undefined || provider === '')
+        return null;
+    return ROUTED[provider] ?? 'other';
+}
+/**
+ * 选这一轮走哪条路。
+ * @param input - 路由判据，以及逐来源的可用性（由门面从各账本问出来）。
+ * @returns 要用的来源。
+ */
+export function pickSource(input) {
+    const { routed, available } = input;
+    if (routed !== null && routed !== 'other' && available(routed))
+        return routed;
+    for (const source of FALLBACK_ORDER) {
+        if (available(source))
+            return source;
+    }
+    return DEFAULT_SOURCE;
+}
+//# sourceMappingURL=source-selector.js.map

package/lib/types/client/api-types.d.ts

@@ -6,6 +6,13 @@ import type { ErrorCode } from '../domain/errors.ts';
 import type { UNREACHABLE_CODE } from './data.ts';
 /** 余额数据的状态维度。 */
 export type BalanceState = 'empty' | 'ok' | 'stale' | 'error';
+/**
+ * 余额来源。
+ *
+ * 与宿主 `domain/balance.ts` 的 `BalanceSource` **逐字同形**：两个半体不共享值，
+ * 所以这里是自己抄的一份字面量，由 `test/client-data.test.ts` 对账。
+ */
+export type BalanceSource = 'deepseek-http' | 'deepseek-account';
 /** 颜色严重度维度。前端只做机械映射，不比较金额。 */
 export type Severity = 'ok' | 'warn' | 'critical' | 'unavailable' | 'unknown';
 /** 估算来源。第一版 UI 不消费。 */
@@ -42,6 +49,15 @@ export interface BalanceError {
 export interface BalanceResponse {
     requestId: string;
     schemaVersion: number;
+    /** 这一份数字是哪条取数路给的。标题里的来源标签读它。 */
+    source: BalanceSource;
+    /**
+     * 处境：界面唯一的分支入口。
+     *
+     * **旧宿主没有这个字段**（客户端 HMR 换新、宿主重启才换），所以类型上可选，
+     * 读它必须过形状守卫 —— 见 [situation.ts](situation.ts) 的 `situationOfResponse`。
+     */
+    situation?: string;
     state: BalanceState;
     stale: boolean;
     fetchedAt: number;

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

@@ -50,13 +50,16 @@ export declare const UNREACHABLE_CODE = "PLUGIN_UNREACHABLE";
 /**
  * 「还没拿到数据」的占位视图。
  *
- * 空态而不是错误态：首拉还没回来时不该先闪一下「读取失败」。
+ * 处境是 `checking`：首帧**不该**先闪一下「尚未配置」—— 那是「没接入」的说法，
+ * 而我们此刻只是还没问到。
  * @returns 契约形状的响应。
  */
 export declare function pendingView(): BalanceResponse;
 /**
  * 「拿不到数据」的视图。
  *
+ * 处境是 `offline` —— **插件自己的端点不可达**，这与「接入了但上游读不到」
+ * （`fetch-failed`）是两件不同的事：后者我们至少知道自己问了谁。
  * 只在**一次都没成功过**的时候用；已经有数据时宁可继续显示旧值 ——
  * 后端自己的 `state: stale` 才是「数据过期」的权威表达。
  * @param message - 面向用户的一句话。
@@ -68,12 +71,16 @@ export declare function unreachableView(message: string): BalanceResponse;
  *
  * `displayCurrency` **总是**作为查询参数传出去，包括 `auto` —— 后端的挑选规则
  * 把 `auto` 当作「不指定」，所以传它不等于替后端做决定。
- * @param options - 显示币种、可注入的 fetch 与取消信号。
+ *
+ * `provider` 是**当前会话在用的路由**这条提示：后端据此选数据来源。读不到会话时
+ * 干脆不传，后端回落到全局默认路由 —— 提示缺席不该让界面失去来源。
+ * @param options - 显示币种、会话路由提示、可注入的 fetch 与取消信号。
  * @returns 后端响应。
  * @throws 端点不可达、非 2xx 或响应不是 JSON。
  */
 export declare function requestBalance(options: {
     currency: string;
+    provider?: string | undefined;
     fetchImpl?: FetchLike;
     signal?: AbortSignal;
 }): Promise<BalanceResponse>;
@@ -93,11 +100,13 @@ export declare function requestConfig(options?: {
  * 触发一次手动刷新。
  *
  * 后端的冷却还没过时它回 `triggered: false`，那是正常结果而不是错误。
- * @param options - 刷新原因与可注入的 fetch。
+ * `provider` 与读取余额时给的是同一条提示：刷新要刷**你正在看的那个来源**。
+ * @param options - 刷新原因、会话路由提示与可注入的 fetch。
  * @returns 后端的刷新结果。
  * @throws 端点不可达、非 2xx 或响应不是 JSON。
  */
 export declare function requestRefresh(options?: {
     reason?: string;
+    provider?: string | undefined;
     fetchImpl?: FetchLike;
 }): Promise<RefreshResult>;

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

@@ -16,6 +16,12 @@
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
 import './sidebar/footer-stack.module.css';
+import { type LocaleKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        'ds-balance': LocaleKey;
+    }
+}
 /**
  * 本插件那一行的 Loader 条目 id —— **逐字抄自宿主半边的 `src/config.ts`**。
  *