dsh-ds-balance 2.3.0 → 3.0.0

package/lib/http/routes.js

@@ -4,13 +4,13 @@
  * 三层职责分得很开：本文件只管**注册**，`handlers.ts` 管**怎么做**，
  * `wire.ts` 管**长什么样**。注册需要 `ctx`，所以只有本文件碰宿主。
  *
- * 契约要点（docs/backend-architecture.md §3.3 / §8.2）：
+ * 契约要点（docs/BACKEND-CONTRACTS.md §3.3 / §8.2）：
  * - `path` 写死精确值、不带尾随斜杠（实现是 Map 精确键匹配）；
  * - `requestBody` 必填；
  * - 物理载体**已先做完信任与浏览器鉴权**，handler 不必再判一次。
  * @module dsh-ds-balance/http/routes
  */
-import { handleBalance, handleConfigGet, handleConfigUpdate, handleHealthz, handleRefresh, handleTestConnection, } from './handlers.js';
+import { handleBalance, handleConfigGet, handleConfigUpdate, handleHealthz, handleRefresh, handleSources, handleTestConnection, } from './handlers.js';
 /**
  * `/api/v1/config` 的方法分发。
  *
@@ -35,6 +35,7 @@ export const HTTP_ROUTES = [
     { path: '/api/v1/balance', methods: ['GET'], handle: handleBalance },
     { path: '/api/v1/balance/refresh', methods: ['POST'], handle: handleRefresh },
     { path: '/api/v1/config', methods: ['GET', 'POST'], handle: handleConfigRoute },
+    { path: '/api/v1/sources', methods: ['GET'], handle: handleSources },
     { path: '/api/v1/test-connection', methods: ['POST'], handle: handleTestConnection },
     { path: '/api/v1/healthz', methods: ['GET'], handle: handleHealthz },
 ];

package/lib/http/wire.d.ts

@@ -1,7 +1,7 @@
 /**
  * 线上形状与序列化。
  *
- * 契约见 docs/backend-architecture.md §8：**金额一律八位小数字符串**，
+ * 契约见 docs/BACKEND-CONTRACTS.md §8：**金额一律八位小数字符串**，
  * `bigint` 最小单位只活在进程内。本模块是纯函数，不碰 `ctx`、不发请求。
  * @module dsh-ds-balance/http/wire
  */
@@ -43,12 +43,68 @@ export interface WireCredentialInfo {
     source: string | null;
     writable: boolean;
 }
+/**
+ * 一条取数途径的只读状态。
+ *
+ * **这是「连接」组唯一的事实出口**：界面不再自己拼四档判据，也不再跨端点拼两半。
+ * 判据住在后端（它本来就持有 `credentials` 与 `deepseekAccount`），客户端只渲染。
+ *
+ * `masked` 是**首尾片段掩码**（`sk-cf08d*****3b84`），与平台控制台
+ * `platform.deepseek.com/api_keys` 同形 —— **完整密钥永不跨这条线**，
+ * 后端解析出明文后立刻算掩码并丢掉明文。见 [AGENTS.md](AGENTS.md) 的红线。
+ */
+export interface WireKeySource {
+    /** 生效的凭据引用名。 */
+    ref: string;
+    /** 解析链此刻能不能拿到值（`credentials` 或环境变量任一有）。 */
+    configured: boolean;
+    /** 生效值的来源层：`file` / `env` / `project-env` / `user-env`；未知为 `null`。 */
+    source: string | null;
+    /** 首尾片段掩码；未配置或拿不到明文时是空串。 */
+    masked: string;
+    /** 账本标识前 8 位（`HMAC(salt, key)`）；未配置时是空串。 */
+    tag8: string;
+}
+/** 账号登录那条途径的只读状态。 */
+export interface WireAccountSource {
+    /** 宿主是否装了账号接缝。缺席时整条途径不存在，界面据此显示「不可用」而不是消失。 */
+    available: boolean;
+    /** 本地存着登录凭据（存储态，不代表服务端验过）。 */
+    signedIn: boolean;
+    /** 账号显示名；读不到时为 `null`。 */
+    name: string | null;
+    /** 头像 URL；没有头像时为 `null`。 */
+    avatarUrl: string | null;
+    /** 服务端已脱敏的联系方式；读不到时为 `null`。 */
+    contact: string | null;
+}
+/**
+ * `GET /api/v1/sources` 的响应体。
+ *
+ * `revision` 是**凭据世代**：凭据库变了、或账号登录态变了，它就 +1。
+ * 界面拿它当「有没有东西换了」的判据 —— 不必把密钥本身放进 React 的依赖串。
+ */
+export interface WireSourcesResponse {
+    requestId: string;
+    schemaVersion: number;
+    revision: number;
+    key: WireKeySource;
+    account: WireAccountSource;
+}
 /** `GET /api/v1/balance` 的响应体。 */
 export interface WireBalanceResponse {
     requestId: string;
     schemaVersion: number;
     /** 这一份数字是哪条取数路给的；界面据此在标题里标来源。 */
     source: BalanceSource;
+    /**
+     * **这条路上用的凭据是哪一份**：掩码 key（首尾片段、不可逆）或账号名。
+     *
+     * 它跟着数字一起走，而不是让界面另外读一次 `/api/v1/sources` —— 两个缓存各自刷新时
+     * 标签会先跳、数字还停在旧的，那就是**标错来源**。读不到时 `null`，
+     * 界面退回「（API Key）」那种路名标签。
+     */
+    sourceIdentity: string | null;
     /**
      * 处境：界面**唯一**的分支入口。
      *
@@ -86,8 +142,9 @@ export declare function toWireError(info: ErrorInfo): WireError;
  * - 没有快照时 `isAvailable` 记 `false`。
  * @param view - 服务层给出的视图。
  * @param accountTag8 - 当前账本标识前 8 位；没有快照时传空串。
+ * @param sourceIdentity - 这条路上那份凭据的身份（掩码 key / 账号名）；读不到传 null。
  * @param requestId - 本次请求的标识。
  * @returns 契约 §8.3 的响应体。
  */
-export declare function toWireBalanceView(view: BalanceView, accountTag8: string, requestId: string): WireBalanceResponse;
+export declare function toWireBalanceView(view: BalanceView, accountTag8: string, sourceIdentity: string | null, requestId: string): WireBalanceResponse;
 //# sourceMappingURL=wire.d.ts.map

package/lib/http/wire.js

@@ -1,7 +1,7 @@
 /**
  * 线上形状与序列化。
  *
- * 契约见 docs/backend-architecture.md §8：**金额一律八位小数字符串**，
+ * 契约见 docs/BACKEND-CONTRACTS.md §8：**金额一律八位小数字符串**，
  * `bigint` 最小单位只活在进程内。本模块是纯函数，不碰 `ctx`、不发请求。
  * @module dsh-ds-balance/http/wire
  */
@@ -33,10 +33,11 @@ function thresholdPair(pair) {
  * - 没有快照时 `isAvailable` 记 `false`。
  * @param view - 服务层给出的视图。
  * @param accountTag8 - 当前账本标识前 8 位；没有快照时传空串。
+ * @param sourceIdentity - 这条路上那份凭据的身份（掩码 key / 账号名）；读不到传 null。
  * @param requestId - 本次请求的标识。
  * @returns 契约 §8.3 的响应体。
  */
-export function toWireBalanceView(view, accountTag8, requestId) {
+export function toWireBalanceView(view, accountTag8, sourceIdentity, requestId) {
     const thresholds = {};
     for (const [currency, pair] of Object.entries(view.thresholds)) {
         thresholds[currency] = thresholdPair(pair);
@@ -45,6 +46,7 @@ export function toWireBalanceView(view, accountTag8, requestId) {
         requestId,
         schemaVersion: SCHEMA_VERSION,
         source: view.source,
+        sourceIdentity,
         situation: view.situation,
         state: view.state,
         stale: view.stale,

package/lib/index.d.ts

@@ -31,7 +31,7 @@ export declare const SALT_FILE_NAME = ".salt";
  *
  * 异步是因为盐要从磁盘读；读失败会降级，不阻断挂载。
  *
- * `refs` 是**引用面**不是值：schema 里 11 个字段全是 `.volatile()` 的，Loader 把
+ * `refs` 是**引用面**不是值：schema 里 9 个字段全是 `.volatile()` 的，Loader 把
  * 值提交进这些引用而不重挂本插件，所以 `apply` 只跑一次，读值一律走
  * `createConfigSource` 的现读路径。
  * @param ctx - 宿主上下文。

package/lib/index.js

@@ -22,6 +22,7 @@ import { BalanceService } from './services/balance-service.js';
 import { ConfigService } from './services/config-service.js';
 import { KeyResolver } from './services/key-resolver.js';
 import { Scheduler } from './services/scheduler.js';
+import { SourcesService } from './services/sources-service.js';
 import { createAccountSource } from './adapters/host-account.js';
 import { SourceLedger } from './services/balance-source.js';
 import { accountReader, keyReader } from './services/source-readers.js';
@@ -49,8 +50,11 @@ export const SALT_FILE_NAME = '.salt';
  * **阈值与展示币种不在里面**：它们不改变上游取数节奏，而 severity 是后端按缓存快照
  * 现算的。把它们也算进去，用户改一次阈值就会顺带打一次官方接口 ——
  * 界面只要重新读一次缓存就够了。
+ *
+ * **`apiKey` 已随字段一起删（3.0）**：它曾是「用户显式覆盖密钥」的逃生舱，
+ * 现在解析链只剩引用名与环境变量，所以改引用名才是需要重排的那件事。
  */
-const SCHEDULE_FIELDS = ['serverRefreshSeconds', 'baseUrl', 'apiKey', 'apiKeyRef'];
+const SCHEDULE_FIELDS = ['serverRefreshSeconds', 'apiKeyRef'];
 /** 系统时钟。 */
 const systemClock = {
     now: () => Date.now(),
@@ -268,7 +272,7 @@ function connectRoute(ctx) {
  *
  * 异步是因为盐要从磁盘读；读失败会降级，不阻断挂载。
  *
- * `refs` 是**引用面**不是值：schema 里 11 个字段全是 `.volatile()` 的，Loader 把
+ * `refs` 是**引用面**不是值：schema 里 9 个字段全是 `.volatile()` 的，Loader 把
  * 值提交进这些引用而不重挂本插件，所以 `apply` 只跑一次，读值一律走
  * `createConfigSource` 的现读路径。
  * @param ctx - 宿主上下文。
@@ -281,10 +285,7 @@ export async function apply(ctx, refs) {
     // 端口只建一次：KeyResolver 与 HTTP 端点读的是同一份「可不可写」的事实。
     const credentials = credentialsPort(ctx);
     const keys = new KeyResolver({
-        readConfig: () => {
-            const current = configService.current();
-            return { apiKey: current.apiKey, apiKeyRef: current.apiKeyRef };
-        },
+        readConfig: () => ({ apiKeyRef: configService.current().apiKeyRef }),
         credentials,
         logger,
     });
@@ -328,6 +329,14 @@ export async function apply(ctx, refs) {
         logger,
         metrics,
     });
+    // 两条取数途径的状态：界面「连接」组的唯一事实出口。
+    const sources = new SourcesService({
+        keys,
+        credentials,
+        account: () => account.current(),
+        salt,
+        logger,
+    });
     const scheduler = new Scheduler({ target: service, logger });
     /**
      * 可选服务到位时把来源判据重定一次。
@@ -346,9 +355,26 @@ export async function apply(ctx, refs) {
         // 所以改阈值、改展示币种都不会顺带打一次官方接口。
         const stopWatching = ctx.on('loader/volatile-update', (paths) => {
             if (paths.some((path) => path.length > 0 && SCHEDULE_FIELDS.some((field) => field === path[0]))) {
+                // 引用名改了 = 换了另一份凭据：两条途径的状态要重读，缓存也失效。
+                sources.invalidate();
                 scheduler.reset();
             }
         });
+        /**
+         * 凭据库变了就作废状态缓存。
+         *
+         * **这是对 [2026-09-30 那条决策](../../.agents/notes/2026-09-30-credential-change-refresh-boundary.md)
+         * 的有意反转**，理由写在新记录里：那一轮「不订阅」是因为订阅只买到「把等一个周期压到秒级」，
+         * 而现在界面要**展示**凭据状态 —— 不订阅的话，在官方模型页换了 key 之后，
+         * 卡片会一直显示旧的那把（同一个引用名，值换了），那是**说假话**，不是「慢一点」。
+         *
+         * 只作废缓存，不重排调度：取数节奏仍由 `SCHEDULE_FIELDS` 与轮询决定，
+         * 免得同一引用名重写成同一个值也白抓一次上游。
+         */
+        const stopCredentialWatch = ctx.on('credentials/reference-updated', (ref) => {
+            if (ref === sources.keyRef())
+                sources.invalidate();
+        });
         let stopped = false;
         // 先恢复落盘快照再起调度，否则首拉之前的窗口里界面会闪一次空态。
         void service.restore().then(() => {
@@ -358,6 +384,7 @@ export async function apply(ctx, refs) {
         return () => {
             stopped = true;
             stopWatching();
+            stopCredentialWatch();
             scheduler.stop();
             // 句柄由调用方关闭：facility 不绑消费方 fiber（契约 §10.0）。
             void store.close();
@@ -375,6 +402,8 @@ export async function apply(ctx, refs) {
                 logger,
                 metrics,
                 credentials,
+                sources,
+                account: () => account.current(),
             });
             return () => {
                 void disposeRoutes();

package/lib/ports/account.d.ts

@@ -6,6 +6,23 @@
  * @module dsh-ds-balance/ports/account
  */
 import type { AccountBalance } from '../domain/account.js';
+/**
+ * 账号的显示身份。
+ *
+ * **只有账号那条路有身份**：API Key 是一串没有身份的字符串，官方 `AccountProfile`
+ * 也只存在于账号侧。所以「连接」组的两行不是对称的 —— 账号那行有头像与名字，
+ * Key 那行只有引用名与掩码。
+ *
+ * `contact` 由**服务端脱敏**后给出（如 `138****5678`），本插件不再加工。
+ */
+export interface AccountIdentity {
+    /** 显示名；平台没给时为 `null`。 */
+    readonly name: string | null;
+    /** 头像 URL；没有头像时为 `null`。 */
+    readonly avatarUrl: string | null;
+    /** 已脱敏的联系方式；没有时为 `null`。 */
+    readonly contact: string | null;
+}
 /** 账号来源的只读面。没有写入口：余额只是读。 */
 export interface AccountSource {
     /** 本地存着登录凭据（宿主原文：存储态，不代表服务端验过）。 */
@@ -16,6 +33,14 @@ export interface AccountSource {
      * 拿不到时回 `null`（宿主本次进程还没读过 profile），调用方按「未知账号」处理。
      */
     accountId(): Promise<string | null>;
+    /**
+     * 读一次账号身份（名字 / 头像 / 脱敏联系方式）。
+     *
+     * **这是一次真上游请求**（宿主 `getProfile` 每次都打 Platform，只有上一次失败时才用
+     * 同一 grant 的缓存兜底），所以调用方必须缓存它，不许每次渲染都问。
+     * 未登录或资料读不到时回 `null`。
+     */
+    profile(): Promise<AccountIdentity | null>;
     /**
      * 读一次钱包。
      *

package/lib/ports/core-store.d.ts

@@ -1,5 +1,5 @@
 /**
- * 快照存储端口。实现走 dsh 官方存储接缝，见 docs/backend-architecture.md §10。
+ * 快照存储端口。实现走 dsh 官方存储接缝，见 docs/BACKEND-CONTRACTS.md §10。
  * @module dsh-ds-balance/ports/core-store
  */
 import type { BalanceSnapshot } from '../domain/balance.js';

package/lib/ports/core-store.js

@@ -1,5 +1,5 @@
 /**
- * 快照存储端口。实现走 dsh 官方存储接缝，见 docs/backend-architecture.md §10。
+ * 快照存储端口。实现走 dsh 官方存储接缝，见 docs/BACKEND-CONTRACTS.md §10。
  * @module dsh-ds-balance/ports/core-store
  */
 export {};

package/lib/services/key-resolver.d.ts

@@ -1,9 +1,14 @@
 /**
  * 密钥解析。
  *
- * 解析链（优先级从高到低）：配置 `apiKey` → `credentials.resolve(apiKeyRef)` →
+ * 解析链（优先级从高到低）：`credentials.resolve(apiKeyRef)` →
  * `process.env[apiKeyRef]` → 抛 {@link NoKeyError}。
  *
+ * **第一档「配置 `apiKey`」已删（3.0）**：它让手改 `settings.yaml` 的人可以静默压过
+ * 官方那份凭据，而界面读的 `credentials.describe()` 看不见它 —— 于是「凭据来源」展示
+ * 会说假话。删掉后这条链就是「跟随官方」的字面实现。见
+ * [决策记录](../../.agents/notes/2026-10-15-drop-apikey-field.md)。
+ *
  * **无 credentials seam 时不抛错**：吞掉后继续往下走，让 env 层有机会接手。
  * @module dsh-ds-balance/services/key-resolver
  */
@@ -11,7 +16,6 @@ import type { Credentials } from '../ports/credentials.js';
 import type { Logger } from '../ports/logger.js';
 /** 每次解析时现读的配置切片。 */
 export interface KeyResolverConfig {
-    apiKey: string;
     apiKeyRef: string;
 }
 /** 构造参数。 */
@@ -28,12 +32,38 @@ export interface KeyResolverOptions {
 }
 /** 契约要求的引用名形状。 */
 export declare const CREDENTIAL_REF_PATTERN: RegExp;
+/** 环境变量那一档在 `describe()` 口径下的来源名（官方也用 `env`）。 */
+export declare const ENV_SOURCE = "env";
+/** 解析结果：明文值，以及它**从哪一档来的**。 */
+export interface ResolvedKey {
+    /** 明文密钥。**调用方负责不把它写进日志或消息。** */
+    readonly value: string;
+    /** 来源层：凭据服务给的那个（`file` / `env` / …），或 `env`（我们自己的环境变量那一档）。 */
+    readonly source: string;
+}
 /** 解析当前可用的明文密钥。 */
 export declare class KeyResolver {
     private readonly options;
     constructor(options: KeyResolverOptions);
     /**
-     * 走完整条解析链。
+     * 现读生效的凭据引用名（已 trim）。
+     *
+     * 「连接」组的 Key 那行要显示它，所以读引用名也走这里 —— 免得展示路径另读一份配置。
+     * @returns 引用名；配置读不到时回空串。
+     */
+    describeRef(): string;
+    /**
+     * 走完整条解析链，并**一并回报值是从哪一档来的**。
+     *
+     * 为什么要回报来源：界面要展示「这把 key 是已保存的凭据还是环境变量」。
+     * 判据只能有一份 —— 就是这条链本身。让消费方自己再读一遍环境变量是**第二份判据**，
+     * 两者迟早会漂（本仓有一条注释说得很清楚：判据不许另抄一份）。
+     * @returns 明文值与来源层。
+     * @throws {NoKeyError} 整条链都没取到值。
+     */
+    resolveWithSource(): Promise<ResolvedKey>;
+    /**
+     * 走完整条解析链，只要值。
      * @returns 明文密钥。**调用方负责不把它写进日志或消息。**
      * @throws {NoKeyError} 整条链都没取到值。
      */

package/lib/services/key-resolver.js

@@ -1,15 +1,22 @@
 /**
  * 密钥解析。
  *
- * 解析链（优先级从高到低）：配置 `apiKey` → `credentials.resolve(apiKeyRef)` →
+ * 解析链（优先级从高到低）：`credentials.resolve(apiKeyRef)` →
  * `process.env[apiKeyRef]` → 抛 {@link NoKeyError}。
  *
+ * **第一档「配置 `apiKey`」已删（3.0）**：它让手改 `settings.yaml` 的人可以静默压过
+ * 官方那份凭据，而界面读的 `credentials.describe()` 看不见它 —— 于是「凭据来源」展示
+ * 会说假话。删掉后这条链就是「跟随官方」的字面实现。见
+ * [决策记录](../../.agents/notes/2026-10-15-drop-apikey-field.md)。
+ *
  * **无 credentials seam 时不抛错**：吞掉后继续往下走，让 env 层有机会接手。
  * @module dsh-ds-balance/services/key-resolver
  */
 import { NoKeyError, describeError } from '../domain/errors.js';
 /** 契约要求的引用名形状。 */
 export const CREDENTIAL_REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** 环境变量那一档在 `describe()` 口径下的来源名（官方也用 `env`）。 */
+export const ENV_SOURCE = 'env';
 /** 解析当前可用的明文密钥。 */
 export class KeyResolver {
     options;
@@ -17,18 +24,32 @@ export class KeyResolver {
         this.options = options;
     }
     /**
-     * 走完整条解析链。
-     * @returns 明文密钥。**调用方负责不把它写进日志或消息。**
+     * 现读生效的凭据引用名（已 trim）。
+     *
+     * 「连接」组的 Key 那行要显示它，所以读引用名也走这里 —— 免得展示路径另读一份配置。
+     * @returns 引用名；配置读不到时回空串。
+     */
+    describeRef() {
+        try {
+            return this.options.readConfig().apiKeyRef.trim();
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * 走完整条解析链，并**一并回报值是从哪一档来的**。
+     *
+     * 为什么要回报来源：界面要展示「这把 key 是已保存的凭据还是环境变量」。
+     * 判据只能有一份 —— 就是这条链本身。让消费方自己再读一遍环境变量是**第二份判据**，
+     * 两者迟早会漂（本仓有一条注释说得很清楚：判据不许另抄一份）。
+     * @returns 明文值与来源层。
      * @throws {NoKeyError} 整条链都没取到值。
      */
-    async resolve() {
-        const config = this.options.readConfig();
-        const override = config.apiKey.trim();
-        if (override !== '')
-            return override;
-        const ref = config.apiKeyRef.trim();
+    async resolveWithSource() {
+        const ref = this.describeRef();
         if (ref === '')
-            throw new NoKeyError('no API key: both apiKey and apiKeyRef are empty');
+            throw new NoKeyError('no API key: apiKeyRef is empty');
         const isValid = this.options.isValidRef ?? ((value) => CREDENTIAL_REF_PATTERN.test(value));
         if (!isValid(ref)) {
             throw new NoKeyError(`no API key: apiKeyRef ${JSON.stringify(ref)} is not a valid credential reference`);
@@ -38,7 +59,7 @@ export class KeyResolver {
                 const resolved = await this.options.credentials.resolve(ref);
                 const value = (resolved?.value ?? '').trim();
                 if (value !== '')
-                    return value;
+                    return { value, source: resolved.source ?? 'credentials' };
             }
             catch (error) {
                 // 没有 seam、引用名不存在、远程拒绝 —— 都只是「这一档没取到」，继续往下走。
@@ -51,8 +72,16 @@ export class KeyResolver {
         const env = this.options.env ?? process.env;
         const fromEnv = (env[ref] ?? '').trim();
         if (fromEnv !== '')
-            return fromEnv;
+            return { value: fromEnv, source: ENV_SOURCE };
         throw new NoKeyError(`no API key: ${ref} is not configured`);
     }
+    /**
+     * 走完整条解析链，只要值。
+     * @returns 明文密钥。**调用方负责不把它写进日志或消息。**
+     * @throws {NoKeyError} 整条链都没取到值。
+     */
+    async resolve() {
+        return (await this.resolveWithSource()).value;
+    }
 }
 //# sourceMappingURL=key-resolver.js.map

package/lib/services/source-readers.js

@@ -5,7 +5,7 @@
  * 三个方法都是**本地读**，只有 `read()` 会打上游。
  * @module dsh-ds-balance/services/source-readers
  */
-import { endpointOf } from '../config.js';
+import { ENDPOINT } from '../config.js';
 import { projectAccountBalance } from '../domain/account.js';
 import { NoKeyError } from '../domain/errors.js';
 import { computeAccountTag } from './account-tag.js';
@@ -28,9 +28,9 @@ export function keyReader(options) {
         },
         async read() {
             const apiKey = await keys.resolve();
-            const current = config.current();
             const raw = await client.fetchBalance({
-                baseUrl: endpointOf(current),
+                // 端点固定为官方根地址（3.0 起不再可配），见 config.ts 的 ENDPOINT。
+                baseUrl: ENDPOINT,
                 apiKey,
                 timeoutMs: config.timeoutMs(),
             });

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

@@ -19,6 +19,16 @@ import type { BalanceSource } from '../domain/balance.js';
 export declare const KEY_PROVIDER = "deepseek-official";
 /** 账号登录那条路的宿主 provider id。 */
 export declare const ACCOUNT_PROVIDER = "deepseek-account";
+/**
+ * 两条取数路的 id。
+ *
+ * 它们是**闭集的两个成员**（{@link BalanceSource}），所以给名字、不再到处写裸字面量：
+ * 「这条路的凭据是谁」那条判据（[sources-service.ts](sources-service.ts) 的 `identityOf`）
+ * 与回落顺序都要按名字比对，散着写迟早有一处漏改。
+ */
+export declare const HTTP_SOURCE: BalanceSource;
+/** @see HTTP_SOURCE */
+export declare const ACCOUNT_SOURCE: BalanceSource;
 /**
  * 路由都指不出该走哪条时的固定顺序：**排在前的先被选中**。
  *

package/lib/services/source-selector.js

@@ -18,12 +18,22 @@
 export const KEY_PROVIDER = 'deepseek-official';
 /** 账号登录那条路的宿主 provider id。 */
 export const ACCOUNT_PROVIDER = 'deepseek-account';
+/**
+ * 两条取数路的 id。
+ *
+ * 它们是**闭集的两个成员**（{@link BalanceSource}），所以给名字、不再到处写裸字面量：
+ * 「这条路的凭据是谁」那条判据（[sources-service.ts](sources-service.ts) 的 `identityOf`）
+ * 与回落顺序都要按名字比对，散着写迟早有一处漏改。
+ */
+export const HTTP_SOURCE = 'deepseek-http';
+/** @see HTTP_SOURCE */
+export const ACCOUNT_SOURCE = 'deepseek-account';
 /** 宿主 provider id → 本插件的取数来源。**认得的路只有这里列出的**。 */
 const ROUTED = {
     // 官方余额端点那条：凭据是 API Key（解析链见 KeyResolver）。
-    [KEY_PROVIDER]: 'deepseek-http',
+    [KEY_PROVIDER]: HTTP_SOURCE,
     // 宿主账号服务那条：凭据是账号登录态。
-    [ACCOUNT_PROVIDER]: 'deepseek-account',
+    [ACCOUNT_PROVIDER]: ACCOUNT_SOURCE,
 };
 /**
  * 路由都指不出该走哪条时的固定顺序：**排在前的先被选中**。
@@ -31,9 +41,9 @@ const ROUTED = {
  * Key 优先是刻意的：它让「今天能用的用户」数字一字不变 —— 账号那条路是补上断掉的那条，
  * 不是抢走已经在用的那条。
  */
-export const FALLBACK_ORDER = ['deepseek-http', 'deepseek-account'];
+export const FALLBACK_ORDER = [HTTP_SOURCE, ACCOUNT_SOURCE];
 /** 一条都不可用时回落到谁。挑 Key 那条，因为它的 `NO_KEY` 文案是既有用户认识的那句。 */
-export const DEFAULT_SOURCE = 'deepseek-http';
+export const DEFAULT_SOURCE = HTTP_SOURCE;
 /**
  * 把宿主 provider id 翻成我们认的来源。
  *