dsh-ds-balance 2.1.3 → 2.2.0

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

@@ -7,11 +7,12 @@ export declare const NS = "ds-balance";
 /** 中文词典（键集真源）。 */
 export declare const zh: {
     readonly 'sidebar.label': "DeepSeek 余额";
-    readonly 'sidebar.aria.balance': "DeepSeek 余额";
     readonly 'sidebar.aria.ring': "DeepSeek 余额状态";
     readonly 'sidebar.aria.refresh': "刷新余额";
     readonly 'sidebar.aria.mismatch': "显示的币种与你选择的不一致";
     readonly 'popover.title': "账户余额";
+    readonly 'popover.source.key': "（API Key）";
+    readonly 'popover.source.account': "（账号登录）";
     readonly 'popover.total': "余额";
     readonly 'popover.granted': "赠送";
     readonly 'popover.toppedUp': "充值";
@@ -23,12 +24,13 @@ export declare const zh: {
     readonly 'popover.action.useShown': "改用 {shown}";
     readonly 'popover.action.openPlugins': "打开插件页";
     readonly 'popover.action.openPluginConfig': "打开插件配置页";
-    readonly 'state.unavailable': "账户不可用";
-    readonly 'state.stale': "数据已过期";
-    readonly 'state.error': "读取失败";
-    readonly 'state.empty': "尚未配置";
-    readonly 'state.noKey': "尚未填写 API Key";
-    readonly 'state.noBalance': "暂无余额";
+    readonly 'situation.checking': "正在获取";
+    readonly 'situation.unavailable': "读不到余额";
+    readonly 'situation.internalError': "服务异常";
+    readonly 'situation.noCredential': "尚未配置凭据";
+    readonly 'situation.accountUnavailable': "账户不可用";
+    readonly 'situation.stale': "数据已过期";
+    readonly 'situation.emptyWallet': "暂无余额";
     readonly 'settings.group.connection': "连接";
     readonly 'settings.group.refresh': "刷新";
     readonly 'settings.group.display': "展示";
@@ -44,15 +46,13 @@ export declare const zh: {
     readonly 'settings.field.cnyCritical': "CNY 告急";
     readonly 'settings.field.usdWarn': "USD 预警";
     readonly 'settings.field.usdCritical': "USD 告急";
-    readonly 'settings.hint.apiKey': "留空则改用引用名从凭据存储读取。";
     readonly 'settings.hint.apiKeyRef': "凭据存储里的条目名；非空时优先于 API Key。";
     readonly 'settings.hint.baseUrl': "留空则使用提供方默认地址。";
     readonly 'settings.hint.displayCurrency': "所选币种不存在时，回落到账户实际持有的币种。";
-    readonly 'settings.hint.number': "请填数字；留空表示使用默认值。";
     readonly 'settings.hint.threshold': "后端判定；界面颜色跟随返回的严重度。";
     readonly 'settings.hint.thresholdPair': "告急值必须低于预警值";
     readonly 'settings.hint.serverRefreshSeconds': "访问官方接口的间隔。";
-    readonly 'settings.hint.clientPollSeconds': "刷新显示的间隔；只读本地缓存，不访问上游。";
+    readonly 'settings.hint.clientPollSeconds': "刷新显示的间隔；正常时只读缓存，读不到时才访问上游。";
     readonly 'settings.hint.manualRefreshCooldownSeconds': "两次手动刷新之间的最短间隔。";
     readonly 'settings.currency.auto': "自动（跟随账户）";
     readonly 'settings.credential.configured': "已配置密钥。";
@@ -75,17 +75,9 @@ export declare const zh: {
     readonly 'settings.reset': "重置";
     readonly 'settings.invalidNumber': "请填数字；留空表示使用默认值。";
     readonly 'settings.hint.refreshAdvanced': "不常改：默认值适用于大多数情况。";
-    readonly 'settings.currencyMismatch': "当前账户无 {wanted} 余额，实际显示 {shown}";
-    readonly 'dev.title': "开发场景";
-    readonly 'dev.hint': "仅用于 UI 开发；不影响真实配置。";
 };
 /** 词典键。 */
 export type LocaleKey = keyof typeof zh;
-declare module '@deepseek-ai/dsh-client-ui-slots' {
-    interface LocaleNamespaceMap {
-        'ds-balance': LocaleKey;
-    }
-}
 /** 英文词典。缺键会在编译期报错。 */
 export declare const en: Record<LocaleKey, string>;
 /** 取词典。未知语言回落英文。 */

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

@@ -11,8 +11,6 @@ import type { BalanceResponse } from '../api-types.ts';
 import { type ScenarioKey } from './scenarios.ts';
 /** URL 查询参数名。 */
 export declare const SCENARIO_PARAM = "dsb";
-/** 开发模式参数名：出现即显示场景切换器。 */
-export declare const DEV_PARAM = "dsb-dev";
 /** `?dsb=` 的这个取值表示「回到真实端点」，并顺手清掉已存的场景。 */
 export declare const LIVE_PARAM_VALUE = "live";
 /**
@@ -22,15 +20,18 @@ export declare const LIVE_PARAM_VALUE = "live";
  * @returns 场景键，或 `null` 表示用真实端点。
  */
 export declare function resolveScenario(): ScenarioKey | null;
-/** 当前生效的场景键；走真实端点时回落到默认场景，供切换器显示。 */
-export declare function currentScenario(): ScenarioKey;
-/** 切换场景并持久化；刷新页面后仍生效。 */
-export declare function setScenario(key: ScenarioKey): void;
-/** 是否处于开发模式（显示场景切换器）。 */
-export declare function isDevMode(): boolean;
-/** 订阅场景变化。回调立即收到一次当前值，返回退订函数。 */
+/**
+ * 订阅场景变化。回调**立即收到一次当前值**，返回退订函数。
+ *
+ * 现有调用方（`SidebarBalance`）只用它那一次立即回调来对账「现在走不走 mock」——
+ * 因为**场景在运行期不会变**：唯一的入口是 URL 参数（刷新页面才重新解析）。
+ *
+ * **想加回场景切换器**（曾经的 `?dsb-dev` + `setScenario()` + `notifyScenario()` 三件套，
+ * 见 [README.md](README.md)）时：把那两个函数加回来、在这里调 `notifyScenario(key)` 即可 ——
+ * 注册表与订阅语义都还在下面。本轮把它们删掉是因为它们**全仓零引用**
+ * （`isDevMode` / `DEV_PARAM` / `setScenario` / `notifyScenario`），
+ * 而配套的两条词典键也是孤儿键。
+ */
 export declare function subscribeScenario(listener: (key: ScenarioKey) => void): () => void;
-/** 通知所有订阅者场景已变。 */
-export declare function notifyScenario(key: ScenarioKey): void;
 /** 取当前场景的数据快照。 */
 export declare function currentBalance(): BalanceResponse;

package/lib/types/client/mock/scenarios.d.ts

@@ -11,20 +11,28 @@ import type { BalanceResponse } from '../api-types.ts';
 export declare const scenarios: {
     /** 正常。 */
     ok: BalanceResponse;
+    /** 正常，但数字来自账号登录那条路（用来眼看「来源标签」）。 */
+    account: BalanceResponse;
     /** 余额偏低但可用。 */
     warn: BalanceResponse;
     /** 余额告急。 */
     critical: BalanceResponse;
-    /** 账户不可用（余额耗尽 / 欠费）。 */
+    /** 账户不可用（余额耗尽 / 欠费）。读到了，但上游说这个账户停用。 */
     unavailable: BalanceResponse;
-    /** 有旧值但本次刷新失败。 */
+    /** 有旧值但本次刷新失败：数字照常显示，文案说它旧。 */
     stale: BalanceResponse;
-    /** 无值失败。 */
+    /** 无值失败：接入了却读不到（没有旧快照）。环是叉。 */
     error: BalanceResponse;
-    /** 未配置。 */
+    /** 插件自己的端点不可达（旧契约里没有这个信号，靠客户端本地合成）。 */
+    offline: BalanceResponse;
+    /** 插件自己出错了（装配错误之类）：与「上游坏了」分开说。 */
+    internalError: BalanceResponse;
+    /** 未配置：尚无任何解释。 */
     empty: BalanceResponse;
-    /** 未配置且带 NO_KEY 错误。 */
+    /** 未配置且带 NO_KEY 错误 —— 需要用户去配置的那一族。 */
     noKey: BalanceResponse;
+    /** 首帧：还没问到后端。 */
+    checking: BalanceResponse;
     /** 多币种。`selected` 显式写出，不靠 `make()` 的默认值兜。 */
     multiCurrency: BalanceResponse;
     /**

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

@@ -4,34 +4,17 @@
  * @module dsh-ds-balance/client/model
  */
 import type { BalanceInfo, BalanceResponse, Severity } from './api-types.ts';
-/** StateDot 的五个状态（原生原语取值）。 */
-export type DotState = 'done' | 'warning' | 'ongoing' | 'error' | 'idle';
-/** severity → StateDot 状态。见 .agents/notes 的映射决策。 */
-export declare function dotStateOf(severity: Severity): DotState;
-/** 圆环中心可以画的符号。目前只有「账户不可用」用得到。 */
-export type RingMarker = 'cross';
-/** 一个 severity 对应的环形态。 */
-export interface RingSpec {
-    /** 弧的状态；决定弧色。 */
-    state: DotState;
-    /** 中心符号；`null` 表示不画。 */
-    marker: RingMarker | null;
-}
 /**
- * severity → 环形态。
+ * StateDot 的五个状态（原生原语取值）。
  *
- * **颜色只有四个色相可用**：官方 token 里 `error-primary` 与 `error-secondary`
- * 在深色主题下同值，没有第五种颜色。所以两档「红」靠**形状**区分：
- *
- * - 颜色编码「数值严重度」：绿 → 琥珀 → 红。
- * - 形状编码「账户可用性」：`unavailable` 是账户维度的事实，与余额高低无关，
- *   它拿红弧再加一个中心叉号。色盲与低分辨率下依然能分开。
- *
- * `critical` 与 `unavailable` 都是红弧，这是有意的：**别再往回改成从红系里挑两个**。
- * @param severity - 后端给的严重度。
- * @returns 弧状态与中心符号。
+ * **这是圆环状态的真源**：`PercentRing` 的 `RingState` 就是它（类型别名，不是另抄一份）——
+ * 抄一份的代价是两处各自增删取值都能编译通过，而 CSS 的 `data-state` 规则只认其中一个。
  */
-export declare function ringSpecOf(severity: Severity): RingSpec;
+export type DotState = 'done' | 'warning' | 'ongoing' | 'error' | 'idle';
+/** severity → StateDot 状态。见 .agents/notes 的映射决策。 */
+export declare function dotStateOf(severity: Severity): DotState;
+/** 圆环中心可以画的符号。两者几何同源（同一个 `MARK_ARM`），只差朝向。 */
+export type RingMarker = 'cross' | 'plus';
 /**
  * 圆环的弧长比例：选中币种的余额占它 warn 阈值的几分之几，封顶 1。
  *
@@ -103,6 +86,22 @@ export declare function ageBucket(ageMs: number): {
  * @returns 毫秒计的当前年龄；基准缺失时按 0 算。
  */
 export declare function currentAgeMs(seenAt: number, seenAgeMs: number, now: number): number;
+/**
+ * 来源标签的词典键。
+ *
+ * 只认两条官方取数路：认不出来就回 `null`，界面不标 —— 标错来源比不标更糟。
+ * 括号与词本身都在词典里（中文全角、英文半角带空格），这里只回键。
+ *
+ * 键的形状写在这里而不是从词典模块取 `LocaleKey`：视图模型不该依赖词典模块，
+ * 而这两个键是它自己要产出的东西（词典侧由 `Record<LocaleKey, string>` 兜完整性）。
+ */
+export type SourceLabelKey = 'popover.source.key' | 'popover.source.account';
+/**
+ * 把来源折成标签键。
+ * @param source - 响应里的来源；老宿主或占位视图可能没有。
+ * @returns 词典键，或 `null` 表示不标。
+ */
+export declare function sourceLabelKeyOf(source: string | undefined | null): SourceLabelKey | null;
 /**
  * 一次手动刷新之后的冷却截止时刻。
  *

package/lib/types/client/route-hint.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 「当前会话在用哪条路由」这条提示。
+ *
+ * 侧栏是**壳层**的座位，不在会话作用域里，所以它拿不到会话级模型选择 —— 这里自己去宿主
+ * 的客户端服务上读一次。
+ *
+ * 三条更新路径，缺一不可：
+ * 1. **切会话**：订阅 `uiSession` 的主绑定；
+ * 2. **同一会话内换模型**：订阅那个会话的 `modelSelection` 投影（换会话时重绑）；
+ * 3. 读不到就什么都不说 —— 后端回落到全局默认路由，界面照常，只是少了「跟着会话走」。
+ *
+ * **服务由调用方经 `ctx.inject` 递进来**（构造参数是一个 getter），本模块绝不碰 `ctx`：
+ * cordis 不许读没 `inject` 过的服务，直接访问会抛 —— 而这个读发生在**渲染期**，
+ * 抛出去等于整条左下角条目被停用（真机踩过：条目注册了、但 `active: false`）。
+ *
+ * 形状**全部鸭子类型**：`uiSession` 与 `sessions` 是宿主自己的客户端服务，跨版本会动，
+ * 而本仓不为它们新增依赖（见 [AGENTS.md](AGENTS.md) 的跨插件服务约定）。读不出来只降级，不抛错。
+ * @module dsh-ds-balance/client/route-hint
+ */
+/** 宿主 `HostObservable` 的最小面。 */
+interface Observable {
+    getSnapshot?: () => unknown;
+    subscribe?: (listener: () => void) => () => void;
+}
+/** 会话绑定里我们要走到的那条链。 */
+interface SessionBindingLike {
+    session?: {
+        projections?: {
+            faceOf?: (key: string) => Observable | undefined;
+        };
+    };
+}
+/**
+ * 这条提示要读的宿主面。
+ *
+ * 两个字段都可缺席：宿主没装相应插件、或服务还没到位时，整条提示退化成 `undefined`。
+ */
+export interface RouteHintContext {
+    uiSession?: {
+        adapter?: {
+            current?: Observable;
+        };
+    };
+    sessions?: {
+        binding?: (id: unknown) => SessionBindingLike | undefined;
+    };
+}
+/** 可订阅的路由提示。 */
+export interface RouteHint {
+    /** 当前会话在用的 provider id；读不到回 `undefined`。 */
+    getSnapshot(): string | undefined;
+    /** 订阅会话切换与模型切换；返回退订函数。 */
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * 造一个路由提示。
+ * @param services - 取当前宿主服务面的函数（由 `ctx.inject` 填的那个可变句柄）。
+ * @returns 提示对象；宿主没有这些服务时永远回 `undefined`。
+ */
+export declare function createRouteHint(services: () => RouteHintContext): RouteHint;
+export {};

package/lib/types/client/sidebar/BalancePopover.d.ts

@@ -21,6 +21,13 @@ export interface BalancePopoverProps {
     displayCurrency: string;
     /** 数据现在的年龄（毫秒）= 收到那份响应时后端报的年龄 + 此后流逝的时间。 */
     ageMs: number;
+    /**
+     * 标题里的来源标签（含括号，来自词典）；`null` 表示不标。
+     *
+     * 由父组件算好再传进来：本组件不做来源判断，也不拼括号 —— 中英文的括号不同形，
+     * 拼在代码里必然出错。
+     */
+    sourceLabel: string | null;
     /** 是否正在刷新。 */
     refreshing: boolean;
     /** 冷却剩余秒数；0 表示可以刷新。 */

package/lib/types/client/sidebar/PercentRing.d.ts

@@ -13,13 +13,21 @@
  * - **弧长**表达比例：余额占该币种 warn 阈值的几分之几，由 `model.ts` 的 `ringRatioOf` 算好传进来。
  *   阈值是用户自己设的刻度，所以不必再定义「满」是多少；本组件不做任何金额判断。
  * - **颜色**按 state 机械映射，取值与原生 StateDot 的 data-state 一一对应，来源只有 `severity`。
- * 账户不可用（unavailable）在这条弧上再加一个中心叉号：颜色只有四个色相可用，
- * 形状负责把「账户维度不可用」与「余额维度告急」分开。
+ * 中心记号用**形状**补颜色表达不了的那两件事，两者几何同源、只差朝向：
+ * - `cross`（斜交 45°）：账号维度读不到 —— 否定；
+ * - `plus`（正交 0°/90°）：没有接入凭据，需要用户去配置 —— 肯定／添加。
+ * 颜色只有四个色相可用，形状负责把「读不到」「待配置」「余额告急」三者分开。
  * @module dsh-ds-balance/client/sidebar/PercentRing
  */
-import type { RingMarker } from '../model.ts';
-/** 圆环能表达的状态；取值域与原生 StateDot 对齐，本插件用不到 ongoing。 */
-export type RingState = 'done' | 'warning' | 'error' | 'idle';
+import type { DotState, RingMarker } from '../model.ts';
+/**
+ * 圆环能表达的状态。
+ *
+ * **是 `DotState` 的别名，不是另抄一份**：抄一份的代价是两处各自增删取值都能编译通过，
+ * 而 CSS 的 `data-state` 规则只认其中一个 —— 那时会出现「组件传了一个没有对应规则的值」，
+ * 颜色静默回落到基色。取值域与原生 StateDot 的 `data-state` 逐值对齐（含 `ongoing`）。
+ */
+export type RingState = DotState;
 /** 圆环属性。 */
 export interface PercentRingProps {
     /** 状态，决定环的颜色；语义与原生 StateDot 的同一套枚举一致。 */

package/lib/types/client/sidebar/SidebarBalance.d.ts

@@ -13,6 +13,7 @@
  */
 import { type LocaleKey } from '../locales.ts';
 import { type ConfigSlotProbe } from '../config-slot.ts';
+import type { RouteHint } from '../route-hint.ts';
 import { type PluginsAction } from './BalancePopover.tsx';
 /**
  * 「打开本插件配置」这个**可选**入口。宿主没提供 layout 服务时整条链不存在，
@@ -47,6 +48,13 @@ export interface SidebarBalanceProps {
      * 宿主缺 layout 服务时整条链不存在，图标就不出现。
      */
     pluginsNavigation?: PluginsNavigation;
+    /**
+     * 「当前会话在用哪条路由」这条提示；宿主没有相应客户端服务时给 `undefined`。
+     *
+     * 它只影响**取哪条数据来源**（后端据此选 Key 那条还是账号那条），不影响别的行为；
+     * 缺席时后端回落到全局默认路由，界面照常。
+     */
+    routeHint?: RouteHint;
     /**
      * 「改用 X」：把后端实际给的那个币种写进本插件那一行的设置命名空间（`displayCurrency`）。
      *
@@ -85,4 +93,4 @@ export interface SidebarBalanceProps {
  * @param props - 展开态、词典与配置切片。
  * @returns 条目元素。
  */
-export declare function SidebarBalance({ wide, t, config, configSlotProbe, onSelectCurrency, pluginsNavigation, }: SidebarBalanceProps): JSX.Element | null;
+export declare function SidebarBalance({ wide, t, config, configSlotProbe, onSelectCurrency, pluginsNavigation, routeHint, }: SidebarBalanceProps): JSX.Element | null;

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

@@ -0,0 +1,164 @@
+/**
+ * 处境 → 界面形态的唯一映射表。
+ *
+ * **为什么要有它**：环、文案、来源标签以前**各拼各的** —— 环只吃 `severity`，文案吃
+ * `state + error.code + isAvailable + selection`，标签吃 `state + source`。三套输入集不同、
+ * 优先级也不同，于是必然出现「环说 A、文案说 B」与「一个空环代表三种处境」。
+ * 现在三者都从同一个处境派生，组件里不再有第二个分支入口。
+ *
+ * **分层是刻意的**（细节见 [docs/ARCHITECTURE.md](../../../docs/ARCHITECTURE.md)）：
+ * - **处境**（内部，11 个取值）：诊断要细，日志与指标都用它；
+ * - **视觉族**（收起态，5 个）：视觉要粗 —— 收起态只有一个圆环，塞不下 11 种区别；
+ * - **通道值**（色 / 弧 / 符号）：组件只认这一层。
+ *
+ * **每一处合并都是有意的**（见 `SHAPES` 的注释），不是默认掉进去的。
+ * 反向也成立：**每一处拆分都是为了消掉一次同形** —— 同形的两组在屏幕上没法区分，
+ * 而它们要用户做的事往往不同。这条不变量由 `test/render-matrix.test.ts` 按
+ * **真组件的渲染结果**钉住（不是读这张表）。
+ * @module dsh-ds-balance/client/situation
+ */
+import type { BalanceInfo, BalanceResponse, Severity } from './api-types.ts';
+import type { LocaleKey } from './locales.ts';
+import { type DotState, type RingMarker } from './model.ts';
+/**
+ * 处境闭集 —— 与宿主 `domain/situation.ts` **逐字同形**。
+ *
+ * 两个半体不共享值，所以这里是自己抄的一份字面量，由 `test/situation.test.ts` 对账。
+ */
+export type Situation = 'checking' | 'offline' | 'internal-error' | 'no-credential' | 'fetch-failed' | 'account-unavailable' | 'stale' | 'empty-wallet' | 'ok' | 'low' | 'critical';
+/** 全部处境；测试用它断言形态表完备。 */
+export declare const SITUATIONS: readonly ["checking", "offline", "internal-error", "no-credential", "fetch-failed", "account-unavailable", "stale", "empty-wallet", "ok", "low", "critical"];
+/**
+ * 收起态的视觉族 = **圆环能表达的几种形态**。
+ *
+ * 五族与「屏幕上看得见的东西」一一对应，**没有两族同形**（`test/render-matrix.test.ts`
+ * 按真组件的渲染结果钉住这条）：
+ * - `gauge`：有数字，颜色是余额高低的编码 —— 看数字（ok / low / critical / stale）；
+ * - `unreadable`：读不到，或读到了但用不了 —— 红环 + 叉。等 / 检查 / 去查账户
+ *   （端点不通 / 抓取失败 / 我们坏了 / 账户停用）；
+ * - `needs-credential`：没接入，需要**用户去配置** —— 灰环 + ＋（唯一需要动手的一族）；
+ * - `pending`：正在取，还没有答案 —— 灰环 + 一条不完整的转弧（首帧）；
+ * - `empty`：连上了、账户可用，就是没有余额 —— 灰空环，无需动作。
+ *
+ * **为什么 `checking` 与 `empty-wallet` 拆成两族**：两者都是灰环，曾经同族 ——
+ * 于是「加载中」与「账户没钱」在屏幕上**逐像素相同**，而用户要做的事完全不同
+ * （等 vs 什么都不用做）。转弧把「还在动」画出来，两者才分得开。
+ *
+ * **为什么 `account-unavailable` 归 `unreadable`**：它和另外三个一样，都是
+ * 「这个数字现在拿不到 / 不可信」，用户要做的也是去查（账户 / 网络 / 我们）。
+ * 它曾经挂在 `gauge` 的红端，靠「红环无叉」与「余额告急」区分 —— 但那区分**不成立**：
+ * 余额恰好为 0 的 `critical` 同样是红环、无叉、无弧，两者逐像素相同。
+ * 加叉之后与 `critical` 分开了；叉的语义扩成「读不到**或用不了**」，同属
+ * 「否定：这里没有可用的数字」。
+ *
+ * **`unreadable` 与 `pending` 不合并**：合并只能二选一 ——
+ * 全红会让每次加载都闪一下叉（冤枉），全灰会让真失败看起来像「没事」。
+ * 两者的颜色差就是「试过且失败」与「还没有答案」的分界，值得留。
+ */
+export type SituationFamily = 'gauge' | 'unreadable' | 'needs-credential' | 'pending' | 'empty';
+/** 弧长来源：按余额比例画，还是不画。 */
+export type ArcSource = 'gauge' | 'none';
+/** 一个处境对应的界面形态。 */
+export interface Presentation {
+    /** 视觉族（收起态的粒度）。 */
+    family: SituationFamily;
+    /** 环的颜色状态。 */
+    ring: DotState;
+    /** 环的中心符号；`null` 表示不画。 */
+    marker: RingMarker | null;
+    /** 弧长从哪来。 */
+    arc: ArcSource;
+    /** 浮层 / 悬停的状态文案键；`null` 表示「一切正常，不必说」。 */
+    textKey: LocaleKey | null;
+}
+/**
+ * 取一个处境的形态。
+ *
+ * `gauge` 族的环色**必须**由 `severity` 定（绿 / 琥珀 / 红就是余额高低的编码），
+ * 所以这一族的颜色在这里现算 —— 这是全仓**唯一**读 `severity` 配色的地方。
+ * @param situation - 处境。
+ * @param severity - 后端给的严重度；只对 `gauge` 族有意义。
+ * @returns 完整形态。
+ */
+export declare function presentationOf(situation: Situation, severity: Severity): Presentation;
+/**
+ * 一个处境的视觉族。
+ *
+ * **它没有生产消费方**（`grep family src/` 只剩声明与这里）—— 这是有意的，不是遗漏：
+ * 组件只需要 `ring` / `marker` / `arc` 那三个通道值，多知道一层「族」就是多耦合一层。
+ *
+ * **但它不是死代码**，和退役的 `ringSpecOf` 有本质区别（那条教训见
+ * [test/model.test.ts](../../../test/model.test.ts) 的「形态不变量」）：
+ * - `ringSpecOf` 是个**映射函数**，输出没有任何消费方，测试断言的又是它自己的映射 ——
+ *   那些断言**自我满足**，守着一个再也画不到屏幕上的东西；
+ * - `family` 是一条**独立的声明**：「我宣称这些处境在屏幕上应当同形」。它被
+ *   [test/render-matrix.test.ts](../../../test/render-matrix.test.ts) 当作**假设**，
+ *   拿去和**真组件的渲染结果**（另一份独立观测）对账 —— 假设与证据来自两处，
+ *   对不上才红。删掉它，那条不变量就失去「应该」这一侧，只剩「实际」。
+ *
+ * 数学上也确实推不出来：`(ring, marker, arc)` 这组通道值**定不了族** ——
+ * `error|cross|none` 收了 unreadable 四个，而 gauge 四个处境分散在三种通道值上
+ * （颜色与弧长本身就是它们的读数）。所以族是一层额外的、必须显式声明的信息。
+ * @param situation - 处境。
+ * @returns 视觉族。
+ */
+export declare function familyOf(situation: Situation): SituationFamily;
+/**
+ * 悬停文案 —— **收起态与展开态共用这一条**。
+ *
+ * 规则：**数字可信才显数字；这个处境有话说时，先说话**。
+ *
+ * 判据写成 `stateText ?? 金额`，而不是「有 `shown` 就显金额」，因为这两件事
+ * **不是一回事**：
+ * - `account-unavailable`（账户停用）上游**可能给余额行**（mock 的 `unavailable`
+ *   场景就带着一条 ¥0），`stale` 更是必然带着一份旧数字。它们都有 `shown`，
+ *   但那份数字**不可信或不可用** —— 显它反而误导（「我有 ¥0」/「我有 ¥110」）。
+ * - 环已经把问题画出来了（红叉 / 旧色），悬停该做的是**解释问题**，不是再报一个数字。
+ *
+ * 而「有没有文案」正好就是「数字可不可信」：`textKey` 只在 `ok` / `low` / `critical`
+ * 三个处境上是 `null` —— 那三个才是「没什么要说的，看数字就行」。
+ * 这不是巧合：文案表与形态表是同一份声明（见 `SHAPES`）。
+ *
+ * **为什么必须是同一个函数**：两态此前各算各的 —— 收起态用 `ringTitle`
+ * （只在有状态文案时才设），展开态用 `hoverLabel`（有数字就给数字）。于是有三种不一致：
+ * 1. 收起态**有数字时什么都不显示**：`ok` / `low` / `critical` 的 `stateText` 是 `null`，
+ *    于是 `ringTitle` 是 `undefined`，那个 `<svg>` 里连 `<title>` 都没有；
+ * 2. 收起态遇到 `stale`（有数字也有文案）显的是「数据已过期」，展开态却显旧金额 ——
+ *    两态**各说各的**；
+ * 3. 收起态还多一个「DeepSeek 余额状态 」前缀，同一个处境两态文字不同。
+ *
+ * 收敛到一个返回值之后，两态**不可能**再分叉 —— 这是结构保证，不是靠两处对齐。
+ * 交付通道仍分两条（收起态走 SVG 原生 `<title>`、展开态走官方 `Tooltip` 原语），
+ * 但那是「怎么显示」的差别，与「说什么」无关。
+ * @param shown - 实际展示的那条余额；`null` 表示没有数字。
+ * @param stateText - 处境的文案；`null` 表示这个处境没什么要说的（数字可信）。
+ * @returns 悬停要显示的那一句；`null` 表示两态都不挂悬停。
+ */
+export declare function hoverTextOf(shown: BalanceInfo | null, stateText: string | null): string | null;
+/** 是不是处境闭集里的取值。 */
+export declare function isSituation(value: unknown): value is Situation;
+/**
+ * 从**旧宿主**的响应推导处境。
+ *
+ * 客户端半边由 HMR 立刻换新，宿主半边要重启才换（见
+ * [事故复盘](../../../docs/postmortem/2026-09-17-client-host-version-skew.md)）——
+ * 所以「新客户端 + 旧宿主」是**合法的中间态**，那时响应里没有 `situation`，
+ * 只能照旧字段推。这条路径是**兼容层**，新宿主上了就走不到。
+ *
+ * **优先级必须与宿主 `situationOf` 逐条对齐**，包括那三条修正。这里曾经漏搬了第三条：
+ * `state === 'stale'` 判在 `selected === null` **之前**，于是「快照在、里面没有可展示币种、
+ * 这轮又没读到」会被推成 `stale` —— 用户手里一个数字都没有，界面上却说「数据已过期」。
+ * 兼容层走的是同一条渲染路径，所以那边的缺陷在这边同样成立，修一条不算修完。
+ *
+ * 推不出来的边角（`internal-error` 与 `account-unavailable` 在旧契约里没有各自的信号）
+ * 退到最接近的那个处境。
+ * @param response - 后端响应。
+ * @returns 处境。
+ */
+export declare function legacySituationOf(response: BalanceResponse): Situation;
+/**
+ * 取一份响应的处境：新宿主给什么用什么，旧宿主现推。
+ * @param response - 后端响应。
+ * @returns 处境。
+ */
+export declare function situationOfResponse(response: BalanceResponse): Situation;

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.3";
+export declare const PLUGIN_VERSION = "2.2.0";
 //# 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.3';
+export const PLUGIN_VERSION = '2.2.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ds-balance",
-  "version": "2.1.3",
+  "version": "2.2.0",
   "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": [
@@ -47,7 +47,7 @@
     "LICENSE"
   ],
   "engines": {
-    "dsh": ">=0.1.7-alpha.1",
+    "dsh": ">=0.2.0-rc.1",
     "node": ">=20"
   },
   "dsh": {
@@ -75,15 +75,16 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.3",
-    "@deepseek-ai/dsh-client-connection": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-client-locale": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-client-ui-primitives": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-credentials": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-home-paths": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-settings": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-storage-domain": ">=0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-connection": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-locale": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-credentials": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-deepseek-account-platform": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-home-paths": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-settings": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-storage-domain": ">=0.2.0-rc.1",
     "@deepseek-ai/schemastery": "^3.18.3",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
@@ -91,18 +92,19 @@
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.3",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.4",
-    "@deepseek-ai/dsh-client-connection": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-client-locale": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-client-ui-plugin-manager": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-client-ui-primitives": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-client-ui-renderer": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-client-ui-sidebar": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-credentials": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-home-paths": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-settings": ">=0.1.7-alpha.1",
-    "@deepseek-ai/dsh-storage-domain": ">=0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-connection": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-locale": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-sidebar": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-credentials": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-deepseek-account-platform": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-home-paths": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-settings": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-storage-domain": ">=0.2.0-rc.1",
     "@deepseek-ai/schemastery": "^3.18.3",
     "@eslint/js": "^10.0.1",
     "@types/node": "^20.0.0",