dsh-ds-balance 2.3.1 → 3.0.0

package/lib/config.d.ts

@@ -1,8 +1,22 @@
 /**
  * 插件配置：schemastery schema、常量与派生值。
  *
- * 字段名与 [UI 侧契约与移交](../docs/UI-HANDOFF.md) 第六节逐字一致，共 **11** 个。
+ * 字段名与 [UI 侧契约与移交](../docs/UI-HANDOFF.md) 第六节逐字一致，共 **9** 个。
  * `timeoutMs` **不在 schema 里**：它是常量加环境变量覆盖，UI 不暴露。
+ *
+ * **本轮删掉两个字段（2.x → 3.0），理由都是「跟随官方」**：
+ * - `apiKey`：它让手改 `settings.yaml` 的人可以静默压过官方那份凭据，而界面读的
+ *   `credentials.describe()` **看不见**它 —— 于是「凭据来源」展示会说假话。
+ * - `baseUrl`：本插件的职责就是**绑定官方**，端点没有第二个合法取值。
+ *   **不能**跟着官方的 `DEEPSEEK_BASE_URL` 走：那个变量是 **Messages 根地址**
+ *   （`https://api.deepseek.com/anthropic`），而余额端点在根域下
+ *   （`GET {root}/user/balance`）—— 照抄会拼出 `.../anthropic/user/balance`，错。
+ *   代价是走内网镜像/自建代理的部署失去了唯一变通办法（契约 §3.2「端点独立」的由来）。
+ *
+ * `apiKeyRef` **保留但不上界面**：它是「读凭据存储里的哪一条」这个输入，
+ * 默认值就是官方那一个（`DEEPSEEK_API_KEY`），而状态展示是**跟着它读**的
+ * （不像 `apiKey` 那样绕开 `describe()`），所以留着一个不可见的逃生舱不构成假话。
+ * 见 [决策记录](../.agents/notes/2026-10-15-drop-apikey-field.md)。
  * @module dsh-ds-balance/config
  */
 import z from '@deepseek-ai/schemastery';
@@ -37,14 +51,17 @@ export declare const CURRENCY_AUTO = "auto";
 /** 官方凭据的默认引用名。与 `llm-deepseek` 的默认逐字相同。 */
 export declare const DEFAULT_API_KEY_REF = "DEEPSEEK_API_KEY";
 /**
- * 生效的端点基址。
+ * 生效的端点基址。**是一个常量，不再是配置项**（3.0 起删掉了 `baseUrl`）。
+ *
+ * 真源是 [ports/deepseek-client.ts](ports/deepseek-client.ts) 的 `DEFAULT_BASE_URL`；
+ * 这里转出去，是为了让「抓取」与「测连接」两条路都从一个名字取地址，
+ * 不必各自 import 端口层。
  *
- * **空串翻译成官方默认地址的唯一一处**：界面默认留空（官方「网页搜索」卡片同款），
- * 用户填了就用填的。抓取与测连接都必须走这里，不许各自判空。
- * @param config - 至少含 `baseUrl` 的配置。
- * @returns 可以直接拼路径的基址。
+ * **端点独立于对话适配器**（契约 §3.2）：本插件打的是官方余额端点
+ * `GET {root}/user/balance`，而官方的 `DEEPSEEK_BASE_URL` 指的是 **Messages 根地址**
+ * （`https://api.deepseek.com/anthropic`）—— 两者拼法不同，所以**不读那个变量**。
  */
-export declare function endpointOf(config: Pick<Config, 'baseUrl'>): string;
+export declare const ENDPOINT = "https://api.deepseek.com";
 /** 超时常量。UI 不暴露，改环境变量即可。 */
 export declare const DEFAULT_TIMEOUT_MS = 8000;
 /** 覆盖超时的环境变量名。 */
@@ -56,12 +73,8 @@ export declare const TIMEOUT_RANGE: {
 };
 /** 插件配置。 */
 export interface Config {
-    /** DeepSeek API Key。**用户显式覆盖**用；留空则走引用名解析。 */
-    apiKey: string;
-    /** 凭据引用名。必须匹配 `^[A-Za-z_][A-Za-z0-9_]*$`。 */
+    /** 凭据引用名。必须匹配 `^[A-Za-z_][A-Za-z0-9_]*$`。**不上界面**：默认即官方那一个。 */
     apiKeyRef: string;
-    /** 端点基址。**端点独立**，不继承对话适配器；**留空表示用官方默认地址**。 */
-    baseUrl: string;
     /** 服务端刷新频率（秒）。 */
     serverRefreshSeconds: number;
     /** 客户端轮询频率（秒）。 */
@@ -107,11 +120,11 @@ export declare function readConfig(refs: ConfigRefs): Config;
  * 悄悄写进用户层。**顺序与数量由 `test/config-fields.test.ts` 对着 schema 兜底**，
  * 不靠人记。
  */
-export declare const CONFIG_FIELDS: readonly ["apiKey", "apiKeyRef", "baseUrl", "serverRefreshSeconds", "clientPollSeconds", "manualRefreshCooldownSeconds", "displayCurrency", "cnyWarn", "cnyCritical", "usdWarn", "usdCritical"];
+export declare const CONFIG_FIELDS: readonly ["apiKeyRef", "serverRefreshSeconds", "clientPollSeconds", "manualRefreshCooldownSeconds", "displayCurrency", "cnyWarn", "cnyCritical", "usdWarn", "usdCritical"];
 /**
  * 配置 schema。加载期校验，非法配置 fail loud。
  *
- * **11 个字段全部 `.volatile()`**，两条独立理由，缺一不可：
+ * **10 个字段全部 `.volatile()`**，两条独立理由，缺一不可：
  * 1. 只有 volatile 字段进得了表单 —— 宿主的 `volatileForm()` 在没有 volatile
  *    字段时返回 `undefined`，该行整条退出 `describe()`，于是
  *    `ctx.configForms.get(ENTRY_ID)` 拿到的快照永远不是 `ready`，
@@ -119,7 +132,7 @@ export declare const CONFIG_FIELDS: readonly ["apiKey", "apiKeyRef", "baseUrl",
  *    漏加一个字段不会报错，只会让那一个字段在表单里消失。
  * 2. 写入路径按 volatile 逐路径放行：非 volatile 路径直接抛
  *    `Config field "..." is not volatile`（宿主 `settings/src/index.ts` 的
- *    `write()`）。`apiKey` 不给它加，`POST /api/v1/config` 就会被宿主拒掉。
+ *    `write()`）。所以每一个要能改的字段都得加。
  *
  * 副作用是好的：全字段 volatile ⇒ Loader 永远判「只有 volatile 变了」⇒
  * 改配置**永不重挂**，`apply` 只跑一次。
@@ -127,9 +140,7 @@ export declare const CONFIG_FIELDS: readonly ["apiKey", "apiKeyRef", "baseUrl",
  * 阈值只在这里存储，前端不做金额比较：颜色由后端的 `severity` 决定。
  */
 export declare const Config: z<Schemastery.ObjectS<NoInfer<{
-    apiKey: z<string, string, "volatile-defined">;
     apiKeyRef: z<string, string, "volatile-defined">;
-    baseUrl: z<string, string, "volatile-defined">;
     serverRefreshSeconds: z<number, number, "volatile-defined">;
     clientPollSeconds: z<number, number, "volatile-defined">;
     manualRefreshCooldownSeconds: z<number, number, "volatile-defined">;
@@ -139,9 +150,7 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     usdWarn: z<number, number, "volatile-defined">;
     usdCritical: z<number, number, "volatile-defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
-    apiKey: z<string, string, "volatile-defined">;
     apiKeyRef: z<string, string, "volatile-defined">;
-    baseUrl: z<string, string, "volatile-defined">;
     serverRefreshSeconds: z<number, number, "volatile-defined">;
     clientPollSeconds: z<number, number, "volatile-defined">;
     manualRefreshCooldownSeconds: z<number, number, "volatile-defined">;

package/lib/config.js

@@ -1,8 +1,22 @@
 /**
  * 插件配置：schemastery schema、常量与派生值。
  *
- * 字段名与 [UI 侧契约与移交](../docs/UI-HANDOFF.md) 第六节逐字一致，共 **11** 个。
+ * 字段名与 [UI 侧契约与移交](../docs/UI-HANDOFF.md) 第六节逐字一致，共 **9** 个。
  * `timeoutMs` **不在 schema 里**：它是常量加环境变量覆盖，UI 不暴露。
+ *
+ * **本轮删掉两个字段（2.x → 3.0），理由都是「跟随官方」**：
+ * - `apiKey`：它让手改 `settings.yaml` 的人可以静默压过官方那份凭据，而界面读的
+ *   `credentials.describe()` **看不见**它 —— 于是「凭据来源」展示会说假话。
+ * - `baseUrl`：本插件的职责就是**绑定官方**，端点没有第二个合法取值。
+ *   **不能**跟着官方的 `DEEPSEEK_BASE_URL` 走：那个变量是 **Messages 根地址**
+ *   （`https://api.deepseek.com/anthropic`），而余额端点在根域下
+ *   （`GET {root}/user/balance`）—— 照抄会拼出 `.../anthropic/user/balance`，错。
+ *   代价是走内网镜像/自建代理的部署失去了唯一变通办法（契约 §3.2「端点独立」的由来）。
+ *
+ * `apiKeyRef` **保留但不上界面**：它是「读凭据存储里的哪一条」这个输入，
+ * 默认值就是官方那一个（`DEEPSEEK_API_KEY`），而状态展示是**跟着它读**的
+ * （不像 `apiKey` 那样绕开 `describe()`），所以留着一个不可见的逃生舱不构成假话。
+ * 见 [决策记录](../.agents/notes/2026-10-15-drop-apikey-field.md)。
  * @module dsh-ds-balance/config
  */
 import z from '@deepseek-ai/schemastery';
@@ -37,17 +51,17 @@ export const CURRENCY_AUTO = 'auto';
 /** 官方凭据的默认引用名。与 `llm-deepseek` 的默认逐字相同。 */
 export const DEFAULT_API_KEY_REF = 'DEEPSEEK_API_KEY';
 /**
- * 生效的端点基址。
+ * 生效的端点基址。**是一个常量，不再是配置项**（3.0 起删掉了 `baseUrl`）。
+ *
+ * 真源是 [ports/deepseek-client.ts](ports/deepseek-client.ts) 的 `DEFAULT_BASE_URL`；
+ * 这里转出去，是为了让「抓取」与「测连接」两条路都从一个名字取地址，
+ * 不必各自 import 端口层。
  *
- * **空串翻译成官方默认地址的唯一一处**：界面默认留空（官方「网页搜索」卡片同款），
- * 用户填了就用填的。抓取与测连接都必须走这里，不许各自判空。
- * @param config - 至少含 `baseUrl` 的配置。
- * @returns 可以直接拼路径的基址。
+ * **端点独立于对话适配器**（契约 §3.2）：本插件打的是官方余额端点
+ * `GET {root}/user/balance`，而官方的 `DEEPSEEK_BASE_URL` 指的是 **Messages 根地址**
+ * （`https://api.deepseek.com/anthropic`）—— 两者拼法不同，所以**不读那个变量**。
  */
-export function endpointOf(config) {
-    const url = config.baseUrl.trim();
-    return url === '' ? DEFAULT_BASE_URL : url;
-}
+export const ENDPOINT = DEFAULT_BASE_URL;
 /** 超时常量。UI 不暴露，改环境变量即可。 */
 export const DEFAULT_TIMEOUT_MS = 8000;
 /** 覆盖超时的环境变量名。 */
@@ -63,9 +77,7 @@ export const TIMEOUT_RANGE = { min: 1000, max: 60_000 };
  */
 export function readConfig(refs) {
     return {
-        apiKey: refs.apiKey.get(),
         apiKeyRef: refs.apiKeyRef.get(),
-        baseUrl: refs.baseUrl.get(),
         serverRefreshSeconds: refs.serverRefreshSeconds.get(),
         clientPollSeconds: refs.clientPollSeconds.get(),
         manualRefreshCooldownSeconds: refs.manualRefreshCooldownSeconds.get(),
@@ -84,9 +96,7 @@ export function readConfig(refs) {
  * 不靠人记。
  */
 export const CONFIG_FIELDS = [
-    'apiKey',
     'apiKeyRef',
-    'baseUrl',
     'serverRefreshSeconds',
     'clientPollSeconds',
     'manualRefreshCooldownSeconds',
@@ -99,7 +109,7 @@ export const CONFIG_FIELDS = [
 /**
  * 配置 schema。加载期校验，非法配置 fail loud。
  *
- * **11 个字段全部 `.volatile()`**，两条独立理由，缺一不可：
+ * **10 个字段全部 `.volatile()`**，两条独立理由，缺一不可：
  * 1. 只有 volatile 字段进得了表单 —— 宿主的 `volatileForm()` 在没有 volatile
  *    字段时返回 `undefined`，该行整条退出 `describe()`，于是
  *    `ctx.configForms.get(ENTRY_ID)` 拿到的快照永远不是 `ready`，
@@ -107,7 +117,7 @@ export const CONFIG_FIELDS = [
  *    漏加一个字段不会报错，只会让那一个字段在表单里消失。
  * 2. 写入路径按 volatile 逐路径放行：非 volatile 路径直接抛
  *    `Config field "..." is not volatile`（宿主 `settings/src/index.ts` 的
- *    `write()`）。`apiKey` 不给它加，`POST /api/v1/config` 就会被宿主拒掉。
+ *    `write()`）。所以每一个要能改的字段都得加。
  *
  * 副作用是好的：全字段 volatile ⇒ Loader 永远判「只有 volatile 变了」⇒
  * 改配置**永不重挂**，`apply` 只跑一次。
@@ -115,9 +125,7 @@ export const CONFIG_FIELDS = [
  * 阈值只在这里存储，前端不做金额比较：颜色由后端的 `severity` 决定。
  */
 export const Config = z.object({
-    apiKey: z.string().role('secret').default('').volatile(),
     apiKeyRef: z.string().role('credential-ref').default(DEFAULT_API_KEY_REF).volatile(),
-    baseUrl: z.string().default('').volatile(),
     serverRefreshSeconds: z.natural().min(10).max(3600).default(60).volatile(),
     clientPollSeconds: z.natural().min(5).max(600).default(30).volatile(),
     manualRefreshCooldownSeconds: z.natural().min(0).max(600).default(30).volatile(),
@@ -198,7 +206,7 @@ export function resolveThresholdPairs(value) {
         violations.push(pair.currency);
         if (config === value)
             config = { ...value };
-        // 字段名是 `keyof Config`（值类型是 11 个字段的并集），逐键赋值 TS 推不出来，
+        // 字段名是 `keyof Config`（值类型是 9 个字段的并集），逐键赋值 TS 推不出来，
         // 所以走一次数值视图 —— 这对字段在 schema 里本来就是数字。
         const numeric = config;
         numeric[pair.warn] = pair.defaultWarn;

package/lib/domain/credential.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 凭据的**展示形态**：把明文密钥折成首尾片段掩码。
+ *
+ * **完整密钥永不跨这条线**：调用方解析出明文、当场折成掩码、立刻丢掉明文。
+ * 这是 [http/AGENTS.md](../http/AGENTS.md) 那条红线的落点 —— 放宽到「只回首尾掩码」，
+ * 而不是「回固定长度的星号」。
+ *
+ * 形态与 DeepSeek 平台控制台 `platform.deepseek.com/api_keys` 一致：
+ * `sk-cf08d*****3b84`。选它的理由是**辨识度**：用户要能一眼看出「我现在用的是哪一把
+ * key」——固定长度的 `********` 回答不了这个问题，而「换 key 之后余额不对」正是这个
+ * 插件最容易遇到的困惑。
+ *
+ * **星号个数是固定的 5 个**：真实长度不进掩码，否则等于把密钥长度也送出去。
+ * @module dsh-ds-balance/domain/credential
+ */
+/** 掩码里保留的头部长字符数。`sk-cf08d` 正好是 8 个字符，与平台控制台同形。 */
+export declare const MASK_HEAD = 8;
+/** 掩码里保留的尾部字符数。 */
+export declare const MASK_TAIL = 4;
+/** 中间固定的星号个数。**不随密钥长度变化** —— 长度本身也是信息。 */
+export declare const MASK_STARS = "*****";
+/**
+ * 把明文密钥折成首尾片段掩码。
+ *
+ * 长度不足以同时露首尾时**整串打码**：`sk-abc` 这种短值露 8 个头就等于露了全串。
+ * 空值回空串 —— 调用方据此显示「未配置」而不是显示一串星号。
+ * @param value - 明文密钥；调用方负责在此之后不再使用它。
+ * @returns `sk-cf08d*****3b84` 形态的掩码，或空串。
+ */
+export declare function maskKey(value: string): string;
+/**
+ * 生效值的来源层是否算「已保存的凭据」。
+ *
+ * 判据只有一处（这里），界面与后端都用它 —— 来源层的取值来自官方
+ * `credentialProvider.describe()` 的 `source`，本仓见
+ * [ports/credentials.ts](../ports/credentials.ts)。
+ * @param source - `describe()` 给的来源层；未知或读不到时传 `null`。
+ * @returns 是否来自凭据存储（`.credentials.yaml`）。
+ */
+export declare function isSavedSource(source: string | null): boolean;
+//# sourceMappingURL=credential.d.ts.map

package/lib/domain/credential.js

@@ -0,0 +1,52 @@
+/**
+ * 凭据的**展示形态**：把明文密钥折成首尾片段掩码。
+ *
+ * **完整密钥永不跨这条线**：调用方解析出明文、当场折成掩码、立刻丢掉明文。
+ * 这是 [http/AGENTS.md](../http/AGENTS.md) 那条红线的落点 —— 放宽到「只回首尾掩码」，
+ * 而不是「回固定长度的星号」。
+ *
+ * 形态与 DeepSeek 平台控制台 `platform.deepseek.com/api_keys` 一致：
+ * `sk-cf08d*****3b84`。选它的理由是**辨识度**：用户要能一眼看出「我现在用的是哪一把
+ * key」——固定长度的 `********` 回答不了这个问题，而「换 key 之后余额不对」正是这个
+ * 插件最容易遇到的困惑。
+ *
+ * **星号个数是固定的 5 个**：真实长度不进掩码，否则等于把密钥长度也送出去。
+ * @module dsh-ds-balance/domain/credential
+ */
+/** 掩码里保留的头部长字符数。`sk-cf08d` 正好是 8 个字符，与平台控制台同形。 */
+export const MASK_HEAD = 8;
+/** 掩码里保留的尾部字符数。 */
+export const MASK_TAIL = 4;
+/** 中间固定的星号个数。**不随密钥长度变化** —— 长度本身也是信息。 */
+export const MASK_STARS = '*****';
+/** 能安全露首尾的最短长度：头 + 尾。再短就只能整串打码。 */
+const MASK_MIN_LENGTH = MASK_HEAD + MASK_TAIL;
+/**
+ * 把明文密钥折成首尾片段掩码。
+ *
+ * 长度不足以同时露首尾时**整串打码**：`sk-abc` 这种短值露 8 个头就等于露了全串。
+ * 空值回空串 —— 调用方据此显示「未配置」而不是显示一串星号。
+ * @param value - 明文密钥；调用方负责在此之后不再使用它。
+ * @returns `sk-cf08d*****3b84` 形态的掩码，或空串。
+ */
+export function maskKey(value) {
+    const text = value.trim();
+    if (text === '')
+        return '';
+    if (text.length < MASK_MIN_LENGTH)
+        return MASK_STARS;
+    return text.slice(0, MASK_HEAD) + MASK_STARS + text.slice(-MASK_TAIL);
+}
+/**
+ * 生效值的来源层是否算「已保存的凭据」。
+ *
+ * 判据只有一处（这里），界面与后端都用它 —— 来源层的取值来自官方
+ * `credentialProvider.describe()` 的 `source`，本仓见
+ * [ports/credentials.ts](../ports/credentials.ts)。
+ * @param source - `describe()` 给的来源层；未知或读不到时传 `null`。
+ * @returns 是否来自凭据存储（`.credentials.yaml`）。
+ */
+export function isSavedSource(source) {
+    return source === 'file';
+}
+//# sourceMappingURL=credential.js.map

package/lib/http/handlers.d.ts

@@ -18,6 +18,8 @@ import type { BalanceService } from '../services/balance-service.js';
 import type { ConfigService } from '../services/config-service.js';
 import type { KeyResolver } from '../services/key-resolver.js';
 import type { Scheduler } from '../services/scheduler.js';
+import type { SourcesService } from '../services/sources-service.js';
+import type { AccountSource } from '../ports/account.js';
 /** 一套 handler 需要的全部依赖。 */
 export interface HttpDeps {
     service: BalanceService;
@@ -31,16 +33,45 @@ export interface HttpDeps {
     metrics?: ReadableMetrics | undefined;
     /** 凭据端口。只用来读「配没配 / 可不可写」，**永远不读值**。 */
     credentials?: Credentials | undefined;
+    /** 两条取数途径的状态。`GET /api/v1/sources` 的唯一来源。 */
+    sources: SourcesService;
+    /**
+     * 取当前账号端口实现；服务可能晚到，所以是函数而不是实例。
+     * `POST /api/v1/test-connection` 的 `source: 'deepseek-account'` 那条路用它。
+     */
+    account: () => AccountSource | undefined;
 }
 /** `GET /api/v1/balance`。**状态码始终 200**，业务错误走 `state` + `error`。 */
 export declare function handleBalance(request: Request, deps: HttpDeps): Promise<Response>;
 /** `POST /api/v1/balance/refresh`。请求体 `{ reason, provider }`，都可省略。 */
 export declare function handleRefresh(request: Request, deps: HttpDeps): Promise<Response>;
-/** `GET /api/v1/config`。**掩码是手动的** —— 本响应自己构造，不走 settings 读取。 */
+/** `GET /api/v1/config`。 */
 export declare function handleConfigGet(_request: Request, deps: HttpDeps): Promise<Response>;
+/**
+ * `GET /api/v1/sources`。
+ *
+ * 「连接」组的唯一事实出口：两条途径的状态一次给全。`?refresh=1` 强制重读
+ * （卡片打开 / 窗口重新获得焦点 / 点测试按钮时用），否则走缓存。
+ *
+ * **失败也回 200 + 一份保守快照**：界面读不到状态时该显示「未确认」，
+ * 而不是让整张卡片消失（与 `credential` 段同一策略）。
+ */
+export declare function handleSources(request: Request, deps: HttpDeps): Promise<Response>;
 /** `POST /api/v1/config`。请求是任意字段子集；形状不合法或校验失败一律 `422`。 */
 export declare function handleConfigUpdate(request: Request, deps: HttpDeps): Promise<Response>;
-/** `POST /api/v1/test-connection`。**不动活动缓存。** */
+/**
+ * `POST /api/v1/test-connection`。**不动活动缓存。**
+ *
+ * 请求体 `{ source?, apiKey?, timeoutMs? }`。
+ * - `source` 省略或 `deepseek-http`（默认）：走官方余额端点，行为与从前逐字相同；
+ * - `source: 'deepseek-account'`：走账号那条路真读一次钱包。
+ *
+ * **真连一次上游**，回真实的 `latencyMs`。这正是它存在的意义 ——
+ * 界面上的 **Test** 按钮读的就是这里，而不是本地字符串检查。
+ *
+ * **余额预览不在这里**：卡片按 [settings/AGENTS.md](../client/settings/AGENTS.md)
+ * 不许出现任何额度信息，所以账号那条只回成败与延迟，不回钱包内容。
+ */
 export declare function handleTestConnection(request: Request, deps: HttpDeps): Promise<Response>;
 /** `GET /api/v1/healthz`。 */
 export declare function handleHealthz(_request: Request, deps: HttpDeps): Promise<Response>;

package/lib/http/handlers.js

@@ -11,7 +11,7 @@
  */
 import { classify, describeError } from '../domain/errors.js';
 import { situationOf } from '../domain/situation.js';
-import { CONFIG_FIELDS, endpointOf, validateThresholds } from '../config.js';
+import { CONFIG_FIELDS, ENDPOINT, validateThresholds } from '../config.js';
 import { PLUGIN_VERSION, SCHEMA_VERSION } from '../version.js';
 import { newRequestId, toWireBalanceView, toWireError, } from './wire.js';
 /** `testConnection` 超时的可接受区间；越界一律回落默认值。 */
@@ -63,6 +63,9 @@ function failureView(requestId, error, state = 'error', source = 'deepseek-http'
         requestId,
         schemaVersion: SCHEMA_VERSION,
         source,
+        // 进程级失败时**不声称知道凭据身份**：那份身份是异步读的，而这里必须同步返回。
+        // 界面据此退回路名标签，而路名仍然为真。
+        sourceIdentity: null,
         situation: 'internal-error',
         state,
         stale: false,
@@ -78,22 +81,6 @@ function failureView(requestId, error, state = 'error', source = 'deepseek-http'
         error: toWireError(classify(error)),
     };
 }
-/** 从配置里挑出 `GET /api/v1/config` 要回传的字段。**`apiKey` 永不出现在这里。** */
-function publicConfig(config) {
-    const { apiKey: _secret, ...rest } = config;
-    return rest;
-}
-/**
- * `apiKey` 的掩码。
- *
- * **不回传密钥的任何片段**：只回答「配没配」。回一个固定长度的星号串是为了让
- * 字段名 `apiKeyMasked` 名副其实，同时不给任何爆破线索。
- * @param value - 当前生效的 `apiKey`。
- * @returns 已配置时是固定长度的掩码串，未配置时是空串。
- */
-function maskApiKey(value) {
-    return value.trim() === '' ? '' : '********';
-}
 /** `GET /api/v1/balance`。**状态码始终 200**，业务错误走 `state` + `error`。 */
 export async function handleBalance(request, deps) {
     const requestId = newRequestId();
@@ -104,7 +91,9 @@ export async function handleBalance(request, deps) {
             ...(currency === null || currency === '' ? {} : { currency }),
             providerHint,
         });
-        return json(toWireBalanceView(view, deps.service.accountTag8() ?? '', requestId));
+        // 凭据身份跟着这份数字一起回去：界面拿它当标题里的来源标签（「是哪一把」而不是「哪条路」）。
+        const sourceIdentity = await deps.sources.identityOf(view.source);
+        return json(toWireBalanceView(view, deps.service.accountTag8() ?? '', sourceIdentity, requestId));
     }
     catch (error) {
         deps.logger?.error('ds-balance: balance handler failed', {
@@ -171,20 +160,24 @@ async function credentialInfo(deps, ref) {
         return null;
     }
 }
-/** 组装配置响应体。**`apiKey` 永不出现；掩码是手动的。** */
+/**
+ * 组装配置响应体。
+ *
+ * **配置整份回传**：9 个字段里没有一个是秘密（密钥在 3.0 随 `apiKey` 字段一起删了），
+ * 所以不再需要从前那个「挑字段 + 手动掩码」的包装。掩码现在归 `GET /api/v1/sources`。
+ */
 async function configBody(requestId, deps) {
     const config = deps.config.current();
     return {
         requestId,
         schemaVersion: SCHEMA_VERSION,
-        config: publicConfig(config),
-        apiKeyMasked: maskApiKey(config.apiKey),
+        config,
         credential: await credentialInfo(deps, config.apiKeyRef),
         timeoutMs: deps.config.timeoutMs(),
         error: null,
     };
 }
-/** `GET /api/v1/config`。**掩码是手动的** —— 本响应自己构造，不走 settings 读取。 */
+/** `GET /api/v1/config`。 */
 export async function handleConfigGet(_request, deps) {
     const requestId = newRequestId();
     try {
@@ -198,6 +191,44 @@ export async function handleConfigGet(_request, deps) {
         return json({ requestId, schemaVersion: SCHEMA_VERSION, error: toWireError(classify(error)) });
     }
 }
+/**
+ * `GET /api/v1/sources`。
+ *
+ * 「连接」组的唯一事实出口：两条途径的状态一次给全。`?refresh=1` 强制重读
+ * （卡片打开 / 窗口重新获得焦点 / 点测试按钮时用），否则走缓存。
+ *
+ * **失败也回 200 + 一份保守快照**：界面读不到状态时该显示「未确认」，
+ * 而不是让整张卡片消失（与 `credential` 段同一策略）。
+ */
+export async function handleSources(request, deps) {
+    const requestId = newRequestId();
+    const force = queryParam(request, 'refresh') === '1';
+    try {
+        const snapshot = force ? await deps.sources.refresh() : await deps.sources.snapshot();
+        return json({
+            requestId,
+            schemaVersion: SCHEMA_VERSION,
+            revision: snapshot.revision,
+            key: snapshot.key,
+            account: snapshot.account,
+        });
+    }
+    catch (error) {
+        deps.logger?.error('ds-balance: sources handler failed', {
+            requestId,
+            error: describeError(error),
+        });
+        // 保守快照：两条途径都说「读不到」。`revision: -1` 是一个界面认得出「这份不可信」的值。
+        return json({
+            requestId,
+            schemaVersion: SCHEMA_VERSION,
+            revision: -1,
+            key: { ref: '', configured: false, source: null, masked: '', tag8: '' },
+            account: { available: false, signedIn: false, name: null, avatarUrl: null, contact: null },
+            error: toWireError(classify(error)),
+        });
+    }
+}
 /** `POST /api/v1/config`。请求是任意字段子集；形状不合法或校验失败一律 `422`。 */
 export async function handleConfigUpdate(request, deps) {
     const requestId = newRequestId();
@@ -250,16 +281,69 @@ export async function handleConfigUpdate(request, deps) {
         return json({ requestId, schemaVersion: SCHEMA_VERSION, error: toWireError(classify(error)) });
     }
 }
-/** `POST /api/v1/test-connection`。**不动活动缓存。** */
+/**
+ * `POST /api/v1/test-connection`。**不动活动缓存。**
+ *
+ * 请求体 `{ source?, apiKey?, timeoutMs? }`。
+ * - `source` 省略或 `deepseek-http`（默认）：走官方余额端点，行为与从前逐字相同；
+ * - `source: 'deepseek-account'`：走账号那条路真读一次钱包。
+ *
+ * **真连一次上游**，回真实的 `latencyMs`。这正是它存在的意义 ——
+ * 界面上的 **Test** 按钮读的就是这里，而不是本地字符串检查。
+ *
+ * **余额预览不在这里**：卡片按 [settings/AGENTS.md](../client/settings/AGENTS.md)
+ * 不许出现任何额度信息，所以账号那条只回成败与延迟，不回钱包内容。
+ */
 export async function handleTestConnection(request, deps) {
     const requestId = newRequestId();
     try {
         const body = await readJsonObject(request);
-        const config = deps.config.current();
-        const rawBaseUrl = body?.baseUrl;
-        const baseUrl = typeof rawBaseUrl === 'string' && rawBaseUrl.trim() !== ''
-            ? rawBaseUrl.trim()
-            : endpointOf(config);
+        const rawSource = body?.source;
+        const source = rawSource === 'deepseek-account' ? 'deepseek-account' : 'deepseek-http';
+        if (source === 'deepseek-account') {
+            const account = deps.account();
+            if (account === undefined) {
+                return json({
+                    requestId,
+                    schemaVersion: SCHEMA_VERSION,
+                    source,
+                    ok: false,
+                    latencyMs: 0,
+                    code: 'NO_KEY',
+                    message: 'account service is not available',
+                });
+            }
+            const startedAt = Date.now();
+            try {
+                const balance = await account.readBalance();
+                const latencyMs = Date.now() - startedAt;
+                if (balance === null) {
+                    return json({
+                        requestId,
+                        schemaVersion: SCHEMA_VERSION,
+                        source,
+                        ok: false,
+                        latencyMs,
+                        code: 'NO_KEY',
+                        message: 'account is not signed in',
+                    });
+                }
+                return json({ requestId, schemaVersion: SCHEMA_VERSION, source, ok: true, latencyMs });
+            }
+            catch (error) {
+                const latencyMs = Date.now() - startedAt;
+                const info = classify(error);
+                return json({
+                    requestId,
+                    schemaVersion: SCHEMA_VERSION,
+                    source,
+                    ok: false,
+                    latencyMs,
+                    code: info.code,
+                    message: info.message,
+                });
+            }
+        }
         const rawTimeout = Number(body?.timeoutMs);
         const timeoutMs = Number.isFinite(rawTimeout) &&
             rawTimeout >= TEST_TIMEOUT_RANGE.min &&
@@ -271,9 +355,17 @@ export async function handleTestConnection(request, deps) {
             ? rawApiKey.trim()
             : await deps.keys.resolve().catch(() => null);
         if (apiKey === null)
-            return json({ requestId, ok: false, latencyMs: 0, code: 'NO_KEY', message: NO_KEY_MESSAGE });
-        const result = await deps.client.testConnection({ baseUrl, apiKey, timeoutMs });
-        return json({ requestId, schemaVersion: SCHEMA_VERSION, ...result });
+            return json({
+                requestId,
+                schemaVersion: SCHEMA_VERSION,
+                source,
+                ok: false,
+                latencyMs: 0,
+                code: 'NO_KEY',
+                message: NO_KEY_MESSAGE,
+            });
+        const result = await deps.client.testConnection({ baseUrl: ENDPOINT, apiKey, timeoutMs });
+        return json({ requestId, schemaVersion: SCHEMA_VERSION, source, ...result });
     }
     catch (error) {
         deps.logger?.warn('ds-balance: test-connection handler failed', {
@@ -284,6 +376,7 @@ export async function handleTestConnection(request, deps) {
         return json({
             requestId,
             schemaVersion: SCHEMA_VERSION,
+            source: 'deepseek-http',
             ok: false,
             latencyMs: 0,
             code: info.code,

package/lib/http/routes.d.ts

@@ -11,7 +11,7 @@
  * @module dsh-ds-balance/http/routes
  */
 import type { Context } from '@deepseek-ai/cordis';
-import { handleBalance, handleHealthz, handleRefresh, handleTestConnection, type HttpDeps } from './handlers.js';
+import { handleBalance, handleHealthz, handleRefresh, handleSources, handleTestConnection, type HttpDeps } from './handlers.js';
 /**
  * `/api/v1/config` 的方法分发。
  *
@@ -40,6 +40,10 @@ export declare const HTTP_ROUTES: readonly [{
     readonly path: "/api/v1/config";
     readonly methods: readonly ["GET", "POST"];
     readonly handle: typeof handleConfigRoute;
+}, {
+    readonly path: "/api/v1/sources";
+    readonly methods: readonly ["GET"];
+    readonly handle: typeof handleSources;
 }, {
     readonly path: "/api/v1/test-connection";
     readonly methods: readonly ["POST"];

package/lib/http/routes.js

@@ -10,7 +10,7 @@
  * - 物理载体**已先做完信任与浏览器鉴权**，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 },
 ];