dsh-ds-balance 2.3.1 → 3.0.0

package/lib/services/sources-service.js

@@ -0,0 +1,209 @@
+/**
+ * 取数途径的状态服务。
+ *
+ * **这是「连接」组唯一的事实出口**：两条途径（API Key / 账号登录）的只读状态都从这里出去，
+ * 界面不再自己拼判据、也不再跨端点拼两半。
+ *
+ * 为什么值得单独一层：
+ * - 判据本来散在三处（客户端的 `use-credential-state`、卡片的徽章映射、`data.ts` 的形状守卫），
+ *   每处都能各自漂；收敛到这里之后只剩一进一出。
+ * - 只有后端同时持有 `credentials` 与 `deepseekAccount` 两个接缝，所以只有它能一次答完。
+ * - `revision` 是**凭据世代**：凭据库变了或账号登录态变了就 +1。界面拿它当「有没有东西换了」
+ *   的判据 —— 这样密钥本身永远不必进 React 的依赖串（那是既有决策，
+ *   见 [边界记录](../../.agents/notes/2026-10-01-boundaries-left-as-is.md) 第 3 条）。
+ *
+ * **明文密钥只在本文件的生命周期内出现一次**：解析 → 折成掩码与账本标识 → 丢掉。
+ * 掩码之外的任何形态都不出这个函数，见 [domain/credential.ts](../domain/credential.ts)。
+ *
+ * **判据只有一份**：值、来源层、配没配，全部由解析链（[key-resolver.ts](key-resolver.ts)）
+ * 与官方 `describe()` 回答。本文件不自己再读一遍环境变量或配置。
+ * @module dsh-ds-balance/services/sources-service
+ */
+import { maskKey } from '../domain/credential.js';
+import { ACCOUNT_SOURCE, HTTP_SOURCE } from './source-selector.js';
+import { computeAccountTag } from './account-tag.js';
+/**
+ * 两条途径的状态。
+ *
+ * 缓存策略是「按需重建」而不是定时刷新：`snapshot()` 在没有缓存时读一次，
+ * `refresh()` 强制重读。**账号身份是一次真上游请求**（宿主 `getProfile` 每次打 Platform），
+ * 所以它必须被缓存 —— 渲染一次问一次是不行的。
+ */
+export class SourcesService {
+    options;
+    /** 当前缓存；`undefined` 表示还没读过。 */
+    cache;
+    /** 凭据世代。凭据或登录态一变就 +1，界面据此知道「有东西换了」。 */
+    generation = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * 当前快照；没有缓存时先读一次。
+     *
+     * 读失败**不抛**：界面读不到状态时应当显示「未确认」而不是整张卡片消失。
+     * 所以失败会退化成一份保守快照（两条途径都「读不到」），并记一笔 debug。
+     * @returns 快照。
+     */
+    async snapshot() {
+        if (this.cache !== undefined)
+            return this.cache;
+        return await this.refresh();
+    }
+    /**
+     * 强制重读一次并换掉缓存。
+     *
+     * 调用时机：卡片打开、窗口重新获得焦点、点 **Test**、以及凭据变更事件之后。
+     * @returns 新快照。
+     */
+    async refresh() {
+        const key = await this.readKey();
+        const account = await this.readAccount();
+        const snapshot = { revision: this.generation, key, account };
+        this.cache = snapshot;
+        return snapshot;
+    }
+    /**
+     * 现读生效的凭据引用名。
+     *
+     * 订阅方拿它判「这条事件是不是与我有关」：事件只给引用名，不给值。
+     * @returns 引用名；读不到时回空串。
+     */
+    keyRef() {
+        return this.currentRef();
+    }
+    /**
+     * **这条取数路用的是哪一份凭据** —— 给余额响应标注来路的那个事实。
+     *
+     * 它跟数字一起走（`GET /api/v1/balance` 的 `sourceIdentity`），而不是让界面另外去读一次
+     * `/api/v1/sources`：两个缓存各自刷新时，**标签会先跳、数字还停在旧的**，
+     * 那就是在标错来源 —— 比不标更糟。
+     *
+     * 回的是**不可逆的掩码**（首尾片段）或账号名，不是密钥本身。
+     * 认不出这条路、或这条路没有身份时回 `null`（界面据此退回「（API Key）」那种路名标签）。
+     * @param source - 这一份数字来自哪条路。
+     * @returns 掩码 key / 账号名；没有则 null。
+     */
+    async identityOf(source) {
+        try {
+            const snapshot = await this.snapshot();
+            if (source === HTTP_SOURCE)
+                return snapshot.key.masked === '' ? null : snapshot.key.masked;
+            if (source === ACCOUNT_SOURCE)
+                return snapshot.account.name;
+            return null;
+        }
+        catch {
+            // 读不到身份只是少一个标签，绝不能连累余额响应本身。
+            return null;
+        }
+    }
+    /**
+     * 作废缓存并把世代 +1。
+     *
+     * 宿主侧订阅到凭据变更（或账号登出）时调它。**下一次读取会拿到新世代**，
+     * 所以界面靠「世代变了」就能知道该重读，不必把密钥放进依赖串。
+     * @returns 新的世代号。
+     */
+    invalidate() {
+        this.generation += 1;
+        this.cache = undefined;
+        return this.generation;
+    }
+    /**
+     * 读 Key 那条途径。
+     *
+     * **判据只有一份：解析链自己**（`resolveWithSource()` 一并回报值与来源层）。
+     * 这里不自己再读一遍环境变量 —— 那是第二份判据，两者迟早会漂。
+     *
+     * 掩码与账本标识取自链拿到的明文；解析失败只表示「这条路此刻没凭据」，不是错误。
+     * @returns 状态。
+     */
+    async readKey() {
+        const ref = this.currentRef();
+        let plain = '';
+        let source = null;
+        try {
+            const resolved = await this.options.keys.resolveWithSource();
+            plain = resolved.value;
+            source = resolved.source;
+        }
+        catch {
+            // 解析链没取到值就是「这条路没凭据」；来源层留 null（界面显示「状态未确认」）。
+        }
+        // 链给不出值时，仍问一次 describe 判「配没配」：凭据存储里可能有值，
+        // 只是解析链因为别的原因没走到（例如引用名形状被判非法）。
+        const described = plain === '' ? await this.describe(ref) : null;
+        return {
+            ref,
+            configured: plain !== '' || described?.configured === true,
+            source: source ?? described?.source ?? null,
+            masked: maskKey(plain),
+            tag8: plain === '' ? '' : computeAccountTag(this.options.salt, plain).slice(0, 8),
+        };
+    }
+    /** 现读生效的引用名；配置读不到时回落 schema 默认值。 */
+    currentRef() {
+        try {
+            const ref = this.options.keys.describeRef();
+            return ref === '' ? '' : ref;
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * 问官方凭据服务要来源层。
+     *
+     * 失败一律回 `null`（端口缺席、引用名非法、远程拒绝）：界面据此退化成
+     * 「未确认」，而不是把整张卡片打挂。
+     * @param ref - 生效的引用名。
+     * @returns 来源层与可写性，或 `null`。
+     */
+    async describe(ref) {
+        const credentials = this.options.credentials;
+        if (credentials === undefined || ref === '')
+            return null;
+        try {
+            const described = await credentials.describe(ref);
+            return { configured: described.configured === true, source: described.source ?? null };
+        }
+        catch (error) {
+            this.options.logger?.debug('ds-balance: credential describe failed', {
+                ref,
+                error: String(error),
+            });
+            return null;
+        }
+    }
+    /**
+     * 读账号那条途径。
+     *
+     * `signedIn()` 是**本地读**（宿主只读一次存储记录，不打网络）；`profile()` 才是上游请求。
+     * 所以未登录时**不问身份** —— 省掉一次注定失败的 Platform 调用。
+     * @returns 状态。
+     */
+    async readAccount() {
+        const account = this.options.account();
+        if (account === undefined) {
+            // 宿主没装账号接缝：整条途径不存在。界面据此显示「不可用」而不是让它消失 ——
+            // 消失会让人以为是 bug。
+            return { available: false, signedIn: false, name: null, avatarUrl: null, contact: null };
+        }
+        // `signedIn()` 抛错时当未登录：这条路读不到就是「此刻用不上」，
+        // 不是「整个端点坏掉」—— 端点还得把 Key 那条途径报出去。
+        const signedIn = await account.signedIn().catch(() => false);
+        if (!signedIn) {
+            return { available: true, signedIn: false, name: null, avatarUrl: null, contact: null };
+        }
+        const identity = await account.profile().catch(() => null);
+        return {
+            available: true,
+            signedIn: true,
+            name: identity?.name ?? null,
+            avatarUrl: identity?.avatarUrl ?? null,
+            contact: identity?.contact ?? null,
+        };
+    }
+}
+//# sourceMappingURL=sources-service.js.map

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

@@ -51,6 +51,14 @@ export interface BalanceResponse {
     schemaVersion: number;
     /** 这一份数字是哪条取数路给的。标题里的来源标签读它。 */
     source: BalanceSource;
+    /**
+     * **这条路上用的凭据是哪一份**：掩码 key（首尾片段、不可逆）或账号名。
+     *
+     * **旧宿主没有这个字段**（客户端 HMR 换新、宿主重启才换），所以类型上可选，
+     * 读它必须过形状守卫 —— 见 [model.ts](model.ts) 的 `sourceIdentityOf`。
+     * 没有它时界面退回 `source` 那个路名标签（「（API Key）」），那句话仍然为真。
+     */
+    sourceIdentity?: string | null;
     /**
      * 处境：界面唯一的分支入口。
      *

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

@@ -16,6 +16,10 @@ export declare const BALANCE_PATH = "/api/v1/balance";
 export declare const REFRESH_PATH = "/api/v1/balance/refresh";
 /** 配置读端点。界面只从这里取「凭据可不可写」这一件事。 */
 export declare const CONFIG_PATH = "/api/v1/config";
+/** 两条取数途径的状态端点。「连接」组的唯一事实出口。 */
+export declare const SOURCES_PATH = "/api/v1/sources";
+/** 测连接端点。**真打上游**，不是本地模拟。 */
+export declare const TEST_PATH = "/api/v1/test-connection";
 /** 可替换的 fetch，便于测试注入。 */
 export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 /**
@@ -45,6 +49,48 @@ export interface RefreshResult {
     cooldownMs: number;
     state: BalanceState;
 }
+/** 一条取数途径的只读状态。与后端 `WireKeySource` 同形。 */
+export interface KeySourceInfo {
+    ref: string;
+    configured: boolean;
+    source: string | null;
+    /** 首尾片段掩码，如 `sk-cf08d*****3b84`；未配置时是空串。 */
+    masked: string;
+    /** 账本标识前 8 位；未配置时是空串。 */
+    tag8: string;
+}
+/** 账号那条途径的只读状态。与后端 `WireAccountSource` 同形。 */
+export interface AccountSourceInfo {
+    available: boolean;
+    signedIn: boolean;
+    name: string | null;
+    avatarUrl: string | null;
+    contact: string | null;
+}
+/** `GET /api/v1/sources` 的响应里本插件消费的那部分。 */
+export interface SourcesResponse {
+    /** 凭据世代；变了就说明有东西换了。`-1` 表示这份快照不可信。 */
+    revision: number;
+    key: KeySourceInfo;
+    account: AccountSourceInfo;
+}
+/** 一次测连接的结果。 */
+export interface TestResult {
+    source: 'deepseek-http' | 'deepseek-account';
+    ok: boolean;
+    latencyMs: number;
+    code?: string;
+    message?: string;
+}
+/**
+ * 「读不到状态」时的保守快照。
+ *
+ * 两条途径都说「读不到」，世代 `-1` 让界面认得出这份不可信。
+ * **不抛错、不返回 null**：卡片读不到状态时该显示「未确认」，
+ * 而不是让整张卡片消失（与 `credential` 段同一策略）。
+ * @returns 保守快照。
+ */
+export declare function unknownSources(): SourcesResponse;
 /** 端点拿不到、或回的不是 JSON 时用的错误码。 */
 export declare const UNREACHABLE_CODE = "PLUGIN_UNREACHABLE";
 /**
@@ -110,3 +156,29 @@ export declare function requestRefresh(options?: {
     provider?: string | undefined;
     fetchImpl?: FetchLike;
 }): Promise<RefreshResult>;
+/**
+ * 读一次两条途径的状态。
+ *
+ * `refresh` 为真时让后端强制重读（绕过它的缓存）—— 卡片打开、窗口重新获得焦点、
+ * 点 **Test** 时都用它。这正是修掉「在官方页换了 key，这里还显示旧的那把」的那一环。
+ * @param options - 是否强制重读，以及可注入的 fetch。
+ * @returns 两条途径的状态；形状不对时退化成保守快照。
+ * @throws 端点不可达、非 2xx 或响应不是 JSON。
+ */
+export declare function requestSources(options?: {
+    refresh?: boolean;
+    fetchImpl?: FetchLike;
+}): Promise<SourcesResponse>;
+/**
+ * 测一条途径的连接。**真打上游。**
+ *
+ * 这是对从前那个「本地字符串检查 + 800ms 假延迟」的替换：界面上那个按钮
+ * 现在读的是后端已经写好、也已经测过的真端点。
+ * @param source - 测哪条途径。
+ * @param options - 可注入的 fetch。
+ * @returns 结果；失败也是一份合法结果（`ok: false` + `code`）。
+ * @throws 端点不可达、非 2xx 或响应不是 JSON。
+ */
+export declare function requestTest(source: 'deepseek-http' | 'deepseek-account', options?: {
+    fetchImpl?: FetchLike;
+}): Promise<TestResult>;

package/lib/types/client/icons/currency.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 自绘的货币图标（「展示」组用）。
+ *
+ * **为什么自绘**：官方图标集里没有任何货币语义的字形 —— 逐个核对过
+ * `@deepseek-ai/dsh-client-ui-primitives` 的全部图标导出，无 Coin / Money / Currency /
+ * Wallet / Yuan / Dollar。而「展示」这一组讲的正是**显示币种**，
+ * 用 `IconDataOutlineRegular`（数据）或 `IconGaugeOutlineRegular`（量程）都是在将就。
+ *
+ * **规格逐条照官方** `ui-primitives/src/icons/index.tsx` 的写法（红线会逐值比对）：
+ * - `viewBox="0 0 16 16"`（官方统一网格）
+ * - `size` 默认 **14**（官方 `Icon*Artwork` 的默认值）
+ * - `strokeWidth` 走 {@link ICON_REGULAR_STROKE}（= 1）
+ * - `stroke="currentColor"` + `fill="none"`（颜色随上下文）
+ * - `aria-hidden="true"`（装饰性字形，语义由所在行的标题承担）
+ *
+ * 字形取**双横杠的 ¥**：它在中日英三种语境下都是「货币」的第一读法，
+ * 比 `$` 更少歧义（`$` 还会被读成 shell 变量或正则锚点）。
+ * @module dsh-ds-balance/client/icons/currency
+ */
+import type { IconProps } from '@deepseek-ai/dsh-client-ui-primitives';
+/**
+ * 渲染货币图标。
+ * @param props - 尺寸与额外类名；颜色随 `currentColor`。
+ * @returns 货币字形。
+ */
+export declare function CurrencyOutlineIcon({ size, className }: IconProps): import("react").JSX.Element;

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

@@ -0,0 +1,92 @@
+/**
+ * 本插件用到的**全部图标，一处定义**。
+ *
+ * 为什么要有一张表：图标从前散在四处（卡片 JSX、`fields.tsx` 的 `icon={null}`、
+ * 选择器的 chevron、浮层的两个按钮），同一个概念在不同文件里各写一份，
+ * 改一处必漏一处 —— 而且「哪个组用哪个图标」这件事本身没有地方可查。
+ *
+ * 取值规则（本仓规则层定的）：
+ * 1. **官方图标集里有语义对得上的就用官方的**（`@deepseek-ai/dsh-client-ui-primitives`
+ *    的 `Icon*OutlineRegular`）—— 本文件只做「选哪个」，不重新画；
+ * 2. 官方没有对应语义时**自绘**，且规格逐条照官方
+ *    （`viewBox="0 0 16 16"`、`strokeWidth={1}`、`stroke="currentColor"`、
+ *    `aria-hidden="true"`、`size` 默认 14），见 [./icons/CURRENCY_ARTWORK]。
+ * 3. 笔画粗细一律用 `Regular`（1px），与配置页其余图标同档；`Medium` 是给大字号场景的。
+ *
+ * **尺寸**：`DisclosureRow` 的 `.leading svg` 会用自己的 CSS 覆盖 svg 的 width/height
+ * （见官方 `DisclosureRow.module.css`），所以传不传 `size` 都不影响分组头；
+ * 传它是为了浮层这类直接渲染的地方。
+ * @module dsh-ds-balance/client/icons
+ */
+import type { ComponentType } from 'react';
+import type { IconProps } from '@deepseek-ai/dsh-client-ui-primitives';
+import { CurrencyOutlineIcon } from './icons/currency.tsx';
+/** 本插件用到的图标组件形状。 */
+export type AppIcon = ComponentType<IconProps>;
+/**
+ * 四个配置分组的图标。
+ *
+ * **连接用链条**（`IconLinkOutlineRegular`）：这一组讲的是「接通官方」，
+ * 而它从前用的是 `IconApiOutlineRegular`（`</>`）—— 那个字形讲的是「写代码」，
+ * 语义对不上。
+ *
+ * **展示用自绘货币图标**：官方图标集里**没有**货币语义的字形
+ * （逐个核对过 `ui-primitives/src/icons/index.tsx` 的全部导出：无 Coin / Money /
+ * Currency / Wallet / Yuan / Dollar），而这一组讲的正是「显示币种」。
+ * 仪表盘（`IconGaugeOutlineRegular`）语义偏「量程」，不选。
+ */
+export declare const GROUP_ICONS: {
+    readonly connection: (props: IconProps) => import("react").JSX.Element;
+    readonly display: typeof CurrencyOutlineIcon;
+    readonly thresholds: (props: IconProps) => import("react").JSX.Element;
+    readonly refresh: (props: IconProps) => import("react").JSX.Element;
+};
+/** 分组键，与 `BalanceSettingsCard` 的分组顺序一致。 */
+export type GroupIconKey = keyof typeof GROUP_ICONS;
+/**
+ * 测试结果的成败图标。
+ *
+ * **用图形而不是 `✓` / `✗` 字符**：字符的基线、字重、间距都跟着字体走，
+ * 与旁边那行等宽掩码并排时会歪，粗细也完全不受我们控制。
+ * 用官方那一对**同族的纯字形**（对勾 / 叉）：形状本身就说清了成与败，
+ * 所以不需要颜色去补（测试结果**不上色**）。取 `Regular` 档，与配置页其余图标同档。
+ *
+ * **这一对的选择被「声明下限」约束过**：更顺眼的 `IconCloseCircleOutlineRegular`
+ * （带圆圈的叉）在宿主更新的一档里才有，**本仓声明的那一档没有**
+ * （那一档只有 `IconCloseCircleFillRegular`，与对勾的 outline 不是一个画风）。
+ * 引官方符号前先在声明下限那一档确认它存在 —— 这条规则就是这么生效的。
+ */
+export declare const RESULT_ICONS: {
+    readonly ok: (props: IconProps) => import("react").JSX.Element;
+    readonly fail: (props: IconProps) => import("react").JSX.Element;
+};
+/**
+ * 分组折叠头的两个箭头。
+ *
+ * **两个都常驻 DOM**，靠 CSS 的透明度互换（收起显下箭头、展开显上箭头）。
+ * 不按 `open` 条件渲染：那样悬浮换箭头时元素会被替换，过渡会闪一下、还会让
+ * `overflow: hidden` 那一行抖动。
+ *
+ * 为什么这一对要放在表里而不是写在 `fields.tsx` 里：本文件是「哪个图标用在哪儿」
+ * 的唯一出处，`fields.tsx` 只该消费它。
+ */
+export declare const HEADER_CHEVRONS: {
+    readonly closed: (props: IconProps) => import("react").JSX.Element;
+    readonly open: (props: IconProps) => import("react").JSX.Element;
+};
+/**
+ * 选择器 pill 右端的 chevron。
+ *
+ * 与 `Menu` 原语配套：pill 是自绘的，所以箭头也得自己放。
+ */
+export declare const SELECTOR_ICON: AppIcon;
+/**
+ * 浮层里的图标。
+ *
+ * `plugins` 与宿主侧栏 Plugins 条目同字形（跨插件只走服务，但图标是平台模块，
+ * 可以照引）；`refresh` 与分组头的刷新同源。
+ */
+export declare const POPOVER_ICONS: {
+    readonly plugins: (props: IconProps) => import("react").JSX.Element;
+    readonly refresh: (props: IconProps) => import("react").JSX.Element;
+};

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

@@ -13,6 +13,7 @@ export declare const zh: {
     readonly 'popover.title': "账户余额";
     readonly 'popover.source.key': "（API Key）";
     readonly 'popover.source.account': "（账号登录）";
+    readonly 'popover.source.identity': "（{identity}）";
     readonly 'popover.total': "余额";
     readonly 'popover.granted': "赠送";
     readonly 'popover.toppedUp': "充值";
@@ -35,9 +36,6 @@ export declare const zh: {
     readonly 'settings.group.refresh': "刷新";
     readonly 'settings.group.display': "展示";
     readonly 'settings.group.thresholds': "阈值";
-    readonly 'settings.field.apiKey': "API Key";
-    readonly 'settings.field.apiKeyRef': "API 密钥引用名";
-    readonly 'settings.field.baseUrl': "接口地址";
     readonly 'settings.field.serverRefreshSeconds': "服务端刷新频率（秒）";
     readonly 'settings.field.clientPollSeconds': "客户端轮询频率（秒）";
     readonly 'settings.field.manualRefreshCooldownSeconds': "手动刷新冷却（秒）";
@@ -46,8 +44,20 @@ export declare const zh: {
     readonly 'settings.field.cnyCritical': "CNY 告急";
     readonly 'settings.field.usdWarn': "USD 预警";
     readonly 'settings.field.usdCritical': "USD 告急";
-    readonly 'settings.hint.apiKeyRef': "凭据存储里的条目名；非空时优先于 API Key。";
-    readonly 'settings.hint.baseUrl': "留空则使用提供方默认地址。";
+    readonly 'settings.sources.title': "取数途径";
+    readonly 'settings.sources.key': "API Key";
+    readonly 'settings.sources.account': "账号登录";
+    readonly 'settings.sources.groupNote': "两条途径都跟随官方：密钥用官方模型页配好的那一份，账号用宿主已登录的那个。本插件不自己保存凭据。";
+    readonly 'settings.sources.sourceSaved': "取自官方模型页保存的凭据";
+    readonly 'settings.sources.sourceEnv': "取自启动环境变量 {name}";
+    readonly 'settings.sources.sourceUnknown': "来源未确认";
+    readonly 'settings.sources.accountNoService': "本部署没有账号服务，这条途径不可用。";
+    readonly 'settings.test': "测试";
+    readonly 'settings.testing': "正在测试…";
+    readonly 'settings.test.ok': "{ms}ms";
+    readonly 'settings.test.noKey': "没有可用凭据";
+    readonly 'settings.test.notSignedIn': "尚未登录";
+    readonly 'settings.test.fail': "连接失败：{message}";
     readonly 'settings.hint.displayCurrency': "所选币种不存在时，回落到账户实际持有的币种。";
     readonly 'settings.hint.threshold': "后端判定；界面颜色跟随返回的严重度。";
     readonly 'settings.hint.thresholdPair': "告急值必须低于预警值";
@@ -55,14 +65,6 @@ export declare const zh: {
     readonly 'settings.hint.clientPollSeconds': "刷新显示的间隔；正常时只读缓存，读不到时才访问上游。";
     readonly 'settings.hint.manualRefreshCooldownSeconds': "两次手动刷新之间的最短间隔。";
     readonly 'settings.currency.auto': "自动（跟随账户）";
-    readonly 'settings.credential.configured': "已配置密钥。";
-    readonly 'settings.credential.notConfigured': "未配置密钥。";
-    readonly 'settings.hint.credential': "不写入设置文件。留空表示保持当前密钥。";
-    readonly 'settings.group.customized': "自定义设置";
-    readonly 'settings.test': "测试连接";
-    readonly 'settings.testing': "测试中…";
-    readonly 'settings.test.ok': "连接正常。";
-    readonly 'settings.test.fail': "连接失败：{message}";
     readonly 'settings.save': "保存";
     readonly 'settings.saving': "保存中…";
     readonly 'settings.failed': "保存失败，请重试。";

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

@@ -102,6 +102,16 @@ export type SourceLabelKey = 'popover.source.key' | 'popover.source.account';
  * @returns 词典键，或 `null` 表示不标。
  */
 export declare function sourceLabelKeyOf(source: string | undefined | null): SourceLabelKey | null;
+/**
+ * 读响应里那条「这份数字用的是哪一份凭据」（掩码 key / 账号名）。
+ *
+ * **形状守卫**：这个字段是后加的，而客户端半边由 HMR 立刻换新、宿主半边要重启才换 ——
+ * 于是「新客户端 + 旧宿主」是合法中间态，旧宿主根本不回这个字段。
+ * 不是非空字符串就当没有（界面退回路名标签），绝不把 `undefined` 漏进渲染。
+ * @param response - 余额响应。
+ * @returns 身份；没有或形状不对时 `null`。
+ */
+export declare function sourceIdentityOf(response: BalanceResponse): string | null;
 /**
  * 一次手动刷新之后的冷却截止时刻。
  *

package/lib/types/client/settings/AccountAvatar.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 账号头像。
+ *
+ * 规格逐值照官方 `ui-settings-account/AccountAvatar.module.css` 与
+ * `AccountSection.module.css` 的 `.avatar`：32×32、`border-radius: 50%`、
+ * `corner-shape: round`（**必须是真的圆**，不能继承宿主的 superellipse）、
+ * `object-fit: cover`、底色 `--dsw-alias-bg-skeleton`。
+ *
+ * `referrerPolicy="no-referrer"` 与官方一致：头像 URL 由 Platform 给出，
+ * 请求它时不该把本页地址带出去。
+ *
+ * **加载失败回落成空圆底**，不显示碎图 —— 头像缺失是常态（平台可以没配），
+ * 而一个破图图标比一个安静的圆底难看得多。失败后**不再重试**（同一个 URL 重试也是失败）。
+ * @module dsh-ds-balance/client/settings/AccountAvatar
+ */
+import type { ReactNode } from 'react';
+/** 属性。 */
+export interface AccountAvatarProps {
+    /** 头像 URL；`null` 表示平台没给头像。 */
+    url: string | null;
+}
+/**
+ * 渲染账号头像。
+ * @param props - 头像 URL。
+ * @returns 头像元素；没有 URL 或加载失败时是一个空圆底。
+ */
+export declare function AccountAvatar({ url }: AccountAvatarProps): ReactNode;

package/lib/types/client/settings/BalanceSettingsCard.d.ts

@@ -1,7 +1,14 @@
 /**
  * 「DeepSeek 余额」在 bundle 详情页里的配置卡片：标题与描述由页面画，卡内只有控件与保存。
- * 只做配置：连接、展示、阈值、刷新四组；不展示任何额度信息，也不按阈值给任何东西上色。
+ * 只做配置与**来源状态**：不展示任何额度信息，也不按阈值给任何东西上色。
  * 分组按使用频率排序：刷新三项有合理默认值，放最后。
+ *
+ * **「连接」组在 3.0 重做成只读状态展示**：从前它是一列输入框（一个继承官方的只读
+ * 凭据框 + 可编辑的接口地址 + 二级「自定义设置」里的引用名），但那些输入要么是假的
+ * （接口地址只服务官方、密钥框根本不能填），要么没有使用场景。现在它只回答一件事：
+ * **两条取数途径各自通不通**，以及一个真打上游的测试按钮。
+ *
+ * 判据住在后端（`GET /api/v1/sources`），本文件只渲染 —— 见 [use-sources.ts](use-sources.ts)。
  * @module dsh-ds-balance/client/settings/BalanceSettingsCard
  */
 import type { LocaleKey } from '../locales.ts';