dsh-ds-balance 2.0.0-alpha.2 → 2.0.0

package/lib/adapters/domain-core-store.js

@@ -9,7 +9,7 @@
  */
 import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
 import { z } from 'zod';
-import { StorageError } from '../domain/errors.js';
+import { StorageError, describeError } from '../domain/errors.js';
 import { formatMoney, parseMoney } from '../domain/money.js';
 /** 域里的表名。 */
 export const SNAPSHOT_TABLE = 'snapshots';
@@ -73,10 +73,6 @@ export function fromStored(record) {
         raw: undefined,
     };
 }
-/** 把未知异常压成一行可读文本。 */
-function describe(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 /**
  * 官方存储接缝上的快照存储。
  *
@@ -115,7 +111,7 @@ export class DomainCoreStore {
                 this.ready = null;
                 if (!this.openFailureLogged) {
                     this.openFailureLogged = true;
-                    this.options.logger?.error('ds-balance: storage domain unavailable, running degraded', { error: describe(error) });
+                    this.options.logger?.error('ds-balance: storage domain unavailable, running degraded', { error: describeError(error) });
                 }
             });
             this.ready = attempt;
@@ -132,7 +128,7 @@ export class DomainCoreStore {
     async requireTable() {
         await this.ensureOpen();
         if (this.openError !== undefined) {
-            throw new StorageError(`storage domain unavailable: ${describe(this.openError)}`, { cause: this.openError });
+            throw new StorageError(`storage domain unavailable: ${describeError(this.openError)}`, { cause: this.openError });
         }
         if (this.table === null)
             throw new StorageError('storage domain is not open');
@@ -164,7 +160,7 @@ export class DomainCoreStore {
         if (this.closed)
             return { ok: false, detail: 'closed' };
         await this.ensureOpen();
-        return this.openError === undefined ? { ok: true } : { ok: false, detail: describe(this.openError) };
+        return this.openError === undefined ? { ok: true } : { ok: false, detail: describeError(this.openError) };
     }
     /** 幂等关闭。**必须挂在 `ctx.effect` 的 disposer 上。** */
     async close() {

package/lib/adapters/http-deepseek-client.js

@@ -2,7 +2,7 @@
  * DeepSeek 上游的 HTTP 实现。
  * @module dsh-ds-balance/adapters/http-deepseek-client
  */
-import { NetworkError, ParseError, TimeoutError, UpstreamError, classify } from '../domain/errors.js';
+import { NetworkError, ParseError, TimeoutError, UpstreamError, classify, describeError } from '../domain/errors.js';
 import { parseErrorBody } from '../domain/normalize.js';
 /** 去掉尾部斜杠，避免拼出双斜杠路径。 */
 function joinUrl(baseUrl, path) {
@@ -82,7 +82,7 @@ export class HttpDeepSeekClient {
             if (error instanceof Error && error.name === 'AbortError') {
                 throw new TimeoutError(`upstream aborted after ${options.timeoutMs}ms`, { cause: error });
             }
-            throw new NetworkError(error instanceof Error ? error.message : String(error), { cause: error });
+            throw new NetworkError(describeError(error), { cause: error });
         }
         finally {
             clearTimeout(timer);

package/lib/client.js

@@ -512,8 +512,11 @@ function probeFailure(baseUrl, apiKey, apiKeyRef) {
   if (apiKey.trim() === "" && apiKeyRef.trim() === "") return "no API key or credential reference configured";
   return null;
 }
+function isRecord(input) {
+  return typeof input === "object" && input !== null && !Array.isArray(input);
+}
 function asRecord(input) {
-  return typeof input === "object" && input !== null && !Array.isArray(input) ? input : {};
+  return isRecord(input) ? input : {};
 }
 function shallowEqual(a, b) {
   const keys = Object.keys(a);
@@ -1319,7 +1322,7 @@ var scenarios = {
     selected: { currency: "CNY", total: "0.00000000" }
   }),
   /** 有旧值但本次刷新失败。 */
-  stale: make({ state: "stale", stale: true, severity: "unknown", ageMs: 36e5, fetchedAt: T0 - 36e5, error: { code: "NETWORK", message: "fetch failed" } }),
+  stale: make({ state: "stale", stale: true, severity: "unknown", ageMs: 36e5, fetchedAt: T0 - 36e5, error: { code: "NO_NETWORK", message: "fetch failed" } }),
   /** 无值失败。 */
   error: make({
     state: "error",
@@ -1329,7 +1332,7 @@ var scenarios = {
     balances: [],
     selected: null,
     ageMs: 0,
-    error: { code: "HTTP_500", message: "upstream returned 500" }
+    error: { code: "UPSTREAM_5XX", message: "upstream returned 500" }
   }),
   /** 未配置。 */
   empty: make({ state: "empty", severity: "unknown", isAvailable: false, balances: [], selected: null, ageMs: 0 }),
@@ -1984,8 +1987,17 @@ var DEFAULT_CONFIG = {
   clientPollSeconds: 30
 };
 var inject = ["slots", "locale"];
+function isTranslate(value) {
+  return typeof value === "function";
+}
+function translateOf(value) {
+  return isTranslate(value) ? value : (key) => key;
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function asRecord2(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+  return isRecord2(value) ? value : {};
 }
 function useFormSnapshot(form) {
   const subscribe = (0, import_react6.useCallback)((listener) => form.subscribe(listener), [form]);
@@ -2030,7 +2042,7 @@ function SidebarSeatComponent(props) {
     SidebarBalance,
     {
       wide: props.seat.wide,
-      t: props.seat.t,
+      t: translateOf(props.seat.t),
       configSlotProbe: props.configSlotProbe,
       pluginsNavigation: props.pluginsNavigation,
       onSelectCurrency: selectCurrency,
@@ -2046,7 +2058,7 @@ function SidebarSeatComponent(props) {
   );
 }
 function SettingsSeatComponent(props) {
-  const t = props.seat.t;
+  const t = translateOf(props.seat.t);
   return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(BalanceSettingsCard, { t, form: props.form });
 }
 var PLUGINS_PANEL_ID = "plugins";
@@ -2080,8 +2092,10 @@ function apply(ctx) {
   ctx.effect(() => () => configSlotProbe.dispose(), "ds-balance: config slot probe");
   const pluginsNavigation = createPluginsNavigation();
   ctx.inject(["layout"], (layoutCtx) => {
+    if (!("layout" in layoutCtx)) return;
     const face = layoutCtx.layout;
-    if (face === void 0 || typeof face.selectPanel !== "function") return;
+    if (typeof face !== "object" || face === null) return;
+    if (!("selectPanel" in face) || typeof face.selectPanel !== "function") return;
     const selectPanel = face.selectPanel.bind(face);
     layoutCtx.effect(() => pluginsNavigation.attach(() => {
       try {

package/lib/config.d.ts

@@ -173,7 +173,19 @@ export interface ThresholdPair {
  * 归成一对来判（[use-config-form.ts](client/settings/use-config-form.ts) 的 `THRESHOLD_PAIRS`）。
  * 两边各存一份是因为**宿主与浏览器两个半体不许值导入**；约定本身由测试对着本表兜底。
  */
-export declare const THRESHOLD_PAIRS: readonly ThresholdPair[];
+export declare const THRESHOLD_PAIRS: readonly [{
+    readonly currency: "CNY";
+    readonly warn: "cnyWarn";
+    readonly critical: "cnyCritical";
+    readonly defaultWarn: 10;
+    readonly defaultCritical: 5;
+}, {
+    readonly currency: "USD";
+    readonly warn: "usdWarn";
+    readonly critical: "usdCritical";
+    readonly defaultWarn: 2;
+    readonly defaultCritical: 1;
+}];
 /**
  * 跨字段校验：每个币种内 `critical` 必须**严格低于** `warn`。
  *

package/lib/domain/errors.d.ts

@@ -81,4 +81,13 @@ export declare function parseRetryAfter(headers: Headers | undefined, now?: numb
  * @returns 契约里的错误形状。
  */
 export declare function classify(error: unknown): ErrorInfo;
+/**
+ * 把任意异常压成一行文本，供日志与错误消息使用。
+ *
+ * **绝不带凭据**：上游约定异常文本里不含密钥，所以它可以安全写进日志。
+ * 只取 `Error.message`；非 `Error` 的抛出值退回 `String()`。
+ * @param error - 任意抛出的值。
+ * @returns 单行错误文本。
+ */
+export declare function describeError(error: unknown): string;
 //# sourceMappingURL=errors.d.ts.map

package/lib/domain/errors.js

@@ -125,7 +125,7 @@ export function classify(error) {
         if (error.name === 'AbortError' || error.name === 'TimeoutError') {
             return { code: 'UPSTREAM_TIMEOUT', message: error.message, retryable: true };
         }
-        const code = error.code;
+        const code = 'code' in error ? error.code : undefined;
         if (typeof code === 'string' && /^(ECONN|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|UND_ERR)/.test(code)) {
             return { code: 'NO_NETWORK', message: error.message, retryable: true };
         }
@@ -133,4 +133,15 @@ export function classify(error) {
     }
     return { code: 'STORAGE_ERROR', message: String(error), retryable: true };
 }
+/**
+ * 把任意异常压成一行文本，供日志与错误消息使用。
+ *
+ * **绝不带凭据**：上游约定异常文本里不含密钥，所以它可以安全写进日志。
+ * 只取 `Error.message`；非 `Error` 的抛出值退回 `String()`。
+ * @param error - 任意抛出的值。
+ * @returns 单行错误文本。
+ */
+export function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 //# sourceMappingURL=errors.js.map

package/lib/http/handlers.js

@@ -9,7 +9,7 @@
  * - **每次请求现读配置**，不许在闭包里捕获旧值。
  * @module dsh-ds-balance/http/handlers
  */
-import { classify } from '../domain/errors.js';
+import { classify, describeError } from '../domain/errors.js';
 import { CONFIG_FIELDS, endpointOf, validateThresholds } from '../config.js';
 import { PLUGIN_VERSION, SCHEMA_VERSION } from '../version.js';
 import { newRequestId, toWireBalanceView, toWireError, } from './wire.js';
@@ -27,10 +27,6 @@ function json(body, status = 200) {
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/** 把未知异常压成一行。**绝不带凭据** —— 异常里不含密钥是上游的约定。 */
-function describe(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 /** 读一个查询参数；URL 坏掉时返回 `null`。 */
 function queryParam(request, name) {
     try {
@@ -100,7 +96,7 @@ export async function handleBalance(request, deps) {
         return json(toWireBalanceView(view, deps.service.accountTag8() ?? '', requestId));
     }
     catch (error) {
-        deps.logger?.error('ds-balance: balance handler failed', { requestId, error: describe(error) });
+        deps.logger?.error('ds-balance: balance handler failed', { requestId, error: describeError(error) });
         return json(failureView(requestId, error));
     }
 }
@@ -115,7 +111,7 @@ export async function handleRefresh(request, deps) {
         return json({ requestId, schemaVersion: SCHEMA_VERSION, ...result, error: null });
     }
     catch (error) {
-        deps.logger?.error('ds-balance: refresh handler failed', { requestId, error: describe(error) });
+        deps.logger?.error('ds-balance: refresh handler failed', { requestId, error: describeError(error) });
         return json({
             requestId,
             schemaVersion: SCHEMA_VERSION,
@@ -149,7 +145,7 @@ async function credentialInfo(deps, ref) {
         };
     }
     catch (error) {
-        deps.logger?.debug('ds-balance: credential describe failed', { ref, error: describe(error) });
+        deps.logger?.debug('ds-balance: credential describe failed', { ref, error: describeError(error) });
         return null;
     }
 }
@@ -173,7 +169,7 @@ export async function handleConfigGet(_request, deps) {
         return json(await configBody(requestId, deps));
     }
     catch (error) {
-        deps.logger?.error('ds-balance: config read handler failed', { requestId, error: describe(error) });
+        deps.logger?.error('ds-balance: config read handler failed', { requestId, error: describeError(error) });
         return json({ requestId, schemaVersion: SCHEMA_VERSION, error: toWireError(classify(error)) });
     }
 }
@@ -185,7 +181,7 @@ export async function handleConfigUpdate(request, deps) {
         const body = await readJsonObject(request);
         if (body === null)
             return json({ requestId, error: { code: 'VALIDATION', message: 'body must be a JSON object', retryable: false } }, 422);
-        const unknown = Object.keys(body).filter((key) => !CONFIG_FIELDS.includes(key));
+        const unknown = Object.keys(body).filter((key) => !CONFIG_FIELDS.some((field) => field === key));
         if (unknown.length > 0) {
             return json({ requestId, error: { code: 'VALIDATION', message: `unknown config field: ${unknown.join(', ')}`, retryable: false } }, 422);
         }
@@ -201,7 +197,7 @@ export async function handleConfigUpdate(request, deps) {
         }
     }
     catch (error) {
-        deps.logger?.warn('ds-balance: config write rejected', { requestId, error: describe(error) });
+        deps.logger?.warn('ds-balance: config write rejected', { requestId, error: describeError(error) });
         return json({ requestId, error: toWireError(classify(error)) }, 422);
     }
     // 写完立刻回读，让调用方看到落盘后的真实值（掩码同上）。
@@ -209,7 +205,7 @@ export async function handleConfigUpdate(request, deps) {
         return json(await configBody(requestId, deps));
     }
     catch (error) {
-        deps.logger?.error('ds-balance: config readback failed', { requestId, error: describe(error) });
+        deps.logger?.error('ds-balance: config readback failed', { requestId, error: describeError(error) });
         return json({ requestId, schemaVersion: SCHEMA_VERSION, error: toWireError(classify(error)) });
     }
 }
@@ -235,7 +231,7 @@ export async function handleTestConnection(request, deps) {
         return json({ requestId, schemaVersion: SCHEMA_VERSION, ...result });
     }
     catch (error) {
-        deps.logger?.warn('ds-balance: test-connection handler failed', { requestId, error: describe(error) });
+        deps.logger?.warn('ds-balance: test-connection handler failed', { requestId, error: describeError(error) });
         const info = classify(error);
         return json({ requestId, schemaVersion: SCHEMA_VERSION, ok: false, latencyMs: 0, code: info.code, message: info.message });
     }
@@ -250,7 +246,7 @@ export async function handleHealthz(_request, deps) {
         store = { ok: health.ok, detail: health.detail ?? null };
     }
     catch (error) {
-        store = { ok: false, detail: describe(error) };
+        store = { ok: false, detail: describeError(error) };
     }
     return json({
         requestId,

package/lib/http/wire.d.ts

@@ -6,7 +6,7 @@
  * @module dsh-ds-balance/http/wire
  */
 import type { BalanceView, CacheState, Currency, Severity } from '../domain/balance.js';
-import type { ErrorInfo } from '../domain/errors.js';
+import type { ErrorCode, ErrorInfo } from '../domain/errors.js';
 /** 一个币种的余额，金额是八位小数字符串。 */
 export interface WireBalance {
     currency: Currency;
@@ -23,9 +23,10 @@ export interface WireThresholdPair {
  * 线上的错误结构。
  *
  * `details` **不出去**：它可能带上游原文，属于内部诊断面。
+ * `code` 取宿主闭集 {@link ErrorCode} —— 线上只出现这几种码。
  */
 export interface WireError {
-    code: string;
+    code: ErrorCode;
     message: string;
     retryable: boolean;
 }

package/lib/index.js

@@ -16,6 +16,7 @@ import { HttpDeepSeekClient } from './adapters/http-deepseek-client.js';
 import { SALT_BYTES, SALT_ENCODING, loadOrCreateSalt } from './adapters/salt-file.js';
 import { createConsoleLogger } from './adapters/console-logger.js';
 import { MemoryMetrics } from './adapters/memory-metrics.js';
+import { describeError } from './domain/errors.js';
 import { registerHttpRoutes } from './http/routes.js';
 import { BalanceService } from './services/balance-service.js';
 import { ConfigService } from './services/config-service.js';
@@ -51,10 +52,6 @@ const systemClock = {
     now: () => Date.now(),
     timezone: () => 'Asia/Shanghai',
 };
-/** 把未知异常压成一行。 */
-function describe(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 /**
  * 读服务端盐；读不出来就退回一份进程内临时盐。
  *
@@ -68,7 +65,7 @@ async function resolveSalt(logger) {
         return await loadOrCreateSalt({ path: dshHomePath(SALT_FILE_NAME) });
     }
     catch (error) {
-        logger.error('ds-balance: salt file unavailable, using an ephemeral salt', { error: describe(error) });
+        logger.error('ds-balance: salt file unavailable, using an ephemeral salt', { error: describeError(error) });
         return randomBytes(SALT_BYTES).toString(SALT_ENCODING);
     }
 }
@@ -217,7 +214,7 @@ export async function apply(ctx, refs) {
         // 排程只看这几项。事件给的是「真的变了的路径」，比原来的全量 diff 更准，
         // 所以改阈值、改展示币种都不会顺带打一次官方接口。
         const stopWatching = ctx.on('loader/volatile-update', (paths) => {
-            if (paths.some((path) => path.length > 0 && SCHEDULE_FIELDS.includes(path[0]))) {
+            if (paths.some((path) => path.length > 0 && SCHEDULE_FIELDS.some((field) => field === path[0]))) {
                 scheduler.reset();
             }
         });

package/lib/services/balance-service.js

@@ -5,7 +5,7 @@
  * **对外永不抛错**：一切失败都变成 `view.state` 与 `view.error`。
  * @module dsh-ds-balance/services/balance-service
  */
-import { classify, parseRetryAfter } from '../domain/errors.js';
+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';
@@ -67,7 +67,7 @@ export class BalanceService {
             this.publishGauge();
         }
         catch (error) {
-            this.options.logger?.debug('ds-balance: no snapshot restored', { error: describe(error) });
+            this.options.logger?.debug('ds-balance: no snapshot restored', { error: describeError(error) });
         }
     }
     /**
@@ -165,7 +165,7 @@ export class BalanceService {
             if (this.persistWarned)
                 return;
             this.persistWarned = true;
-            this.options.logger?.warn('ds-balance: snapshot not persisted, continuing in memory', { error: describe(error) });
+            this.options.logger?.warn('ds-balance: snapshot not persisted, continuing in memory', { error: describeError(error) });
         }
     }
     /** 记录一次失败，并把状态推到 `stale` 或 `error`。 */
@@ -209,13 +209,11 @@ export class BalanceService {
 }
 /** 从上游错误里抽 `Retry-After`；抽不到返回 `null`。 */
 function retryAfterOf(error, now) {
+    if (typeof error !== 'object' || error === null || !('headers' in error))
+        return null;
     const headers = error.headers;
-    if (headers === undefined)
+    if (!(headers instanceof Headers))
         return null;
     return parseRetryAfter(headers, now) ?? null;
 }
-/** 把未知异常压成一行。 */
-function describe(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 //# sourceMappingURL=balance-service.js.map

package/lib/services/key-resolver.js

@@ -7,13 +7,9 @@
  * **无 credentials seam 时不抛错**：吞掉后继续往下走，让 env 层有机会接手。
  * @module dsh-ds-balance/services/key-resolver
  */
-import { NoKeyError } from '../domain/errors.js';
+import { NoKeyError, describeError } from '../domain/errors.js';
 /** 契约要求的引用名形状。 */
 export const CREDENTIAL_REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
-/** 把未知异常压成一行。 */
-function describe(error) {
-    return error instanceof Error ? error.message : String(error);
-}
 /** 解析当前可用的明文密钥。 */
 export class KeyResolver {
     options;
@@ -48,7 +44,7 @@ export class KeyResolver {
                 // 没有 seam、引用名不存在、远程拒绝 —— 都只是「这一档没取到」，继续往下走。
                 this.options.logger?.debug('ds-balance: credentials.resolve did not yield a key, falling back to env', {
                     ref,
-                    error: describe(error),
+                    error: describeError(error),
                 });
             }
         }

package/lib/services/scheduler.js

@@ -5,6 +5,7 @@
  * `Retry-After` 都能生效，也不会堆积重叠的请求。
  * @module dsh-ds-balance/services/scheduler
  */
+import { describeError } from '../domain/errors.js';
 /** 首拉延迟。 */
 export const INITIAL_DELAY_MS = 1000;
 /** 缺密钥时的快速重试间隔。 */
@@ -131,7 +132,7 @@ export class Scheduler {
         catch (error) {
             // 服务承诺永不抛错；这里是防御，不让调度链断掉。
             this.options.logger?.error('ds-balance: scheduler tick threw', {
-                error: error instanceof Error ? error.message : String(error),
+                error: describeError(error),
             });
         }
         if (!this.running)

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

@@ -2,6 +2,8 @@
  * 后端契约类型。本阶段不实现后端，这些形状只用来约束 mock 数据。
  * @module dsh-ds-balance/client/api-types
  */
+import type { ErrorCode } from '../domain/errors.ts';
+import type { UNREACHABLE_CODE } from './data.ts';
 /** 余额数据的状态维度。 */
 export type BalanceState = 'empty' | 'ok' | 'stale' | 'error';
 /** 颜色严重度维度。前端只做机械映射，不比较金额。 */
@@ -24,9 +26,16 @@ export interface TodayUsage {
     needsReview: boolean;
     range: [string, string] | null;
 }
+/**
+ * 客户端可见的错误码：宿主闭集 ∪ 客户端本地合成的「端点不可达」。
+ *
+ * `UNREACHABLE_CODE` 只在客户端产生（端点拿不到、或回的不是 JSON），宿主侧不认识它，
+ * 所以是**显式扩展**而不是往宿主闭集里塞。
+ */
+export type BalanceErrorCode = ErrorCode | typeof UNREACHABLE_CODE;
 /** 后端错误。 */
 export interface BalanceError {
-    code: string;
+    code: BalanceErrorCode;
     message: string;
 }
 /** `GET /api/v1/balance` 的响应。 */

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

@@ -9,7 +9,7 @@
  * 传过去、把失败翻成可展示的错误态。
  * @module dsh-ds-balance/client/data
  */
-import type { BalanceResponse } from './api-types.ts';
+import type { BalanceResponse, BalanceState } from './api-types.ts';
 /** 余额端点。路径与宿主半边逐字一致，不带尾随斜杠。 */
 export declare const BALANCE_PATH = "/api/v1/balance";
 /** 手动刷新端点。 */
@@ -43,7 +43,7 @@ export interface RefreshResult {
     triggered: boolean;
     joined: boolean;
     cooldownMs: number;
-    state: string;
+    state: BalanceState;
 }
 /** 端点拿不到、或回的不是 JSON 时用的错误码。 */
 export declare const UNREACHABLE_CODE = "PLUGIN_UNREACHABLE";

package/lib/types/client/settings/use-config-form.d.ts

@@ -55,7 +55,7 @@ export declare function selectField(field: string): ValueFieldSpec;
 /** 自动币种取值。 */
 export declare const AUTO_CURRENCY = "auto";
 /** 已知币种。阈值分组就是按这两个币种定义的，故它们是币种列表的最小闭集。 */
-export declare const KNOWN_CURRENCIES: readonly string[];
+export declare const KNOWN_CURRENCIES: readonly ["CNY", "USD"];
 /** 一对阈值：同一币种内的预警与告急。 */
 export interface ThresholdPair {
     readonly currency: string;
@@ -72,7 +72,19 @@ export interface ThresholdPair {
     readonly defaultCritical: number;
 }
 /** 阈值成对的清单；字段名沿用宿主 schema 的「币种代码小写 + Warn / Critical」。 */
-export declare const THRESHOLD_PAIRS: readonly ThresholdPair[];
+export declare const THRESHOLD_PAIRS: readonly [{
+    readonly currency: "CNY";
+    readonly warn: "cnyWarn";
+    readonly critical: "cnyCritical";
+    readonly defaultWarn: 10;
+    readonly defaultCritical: 5;
+}, {
+    readonly currency: "USD";
+    readonly warn: "usdWarn";
+    readonly critical: "usdCritical";
+    readonly defaultWarn: 2;
+    readonly defaultCritical: 1;
+}];
 /**
  * 一对阈值是否满足「告急 **严格低于** 预警」。
  *

package/lib/types/domain/errors.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 领域错误与错误分类。
+ *
+ * 宿主半边的对外错误一律映射成 {@link ErrorInfo}：合约规定余额错误走
+ * `200 + state: error`，HTTP 层不得把异常抛出去让宿主包成 500。
+ * @module dsh-ds-balance/domain/errors
+ */
+/** 对外可见的错误码闭集。 */
+export type ErrorCode = 'NO_KEY' | 'NO_NETWORK' | 'UPSTREAM_TIMEOUT' | 'UPSTREAM_401' | 'UPSTREAM_402' | 'UPSTREAM_422' | 'UPSTREAM_429' | 'UPSTREAM_4XX' | 'UPSTREAM_5XX' | 'UPSTREAM_503' | 'PARSE_ERROR' | 'SHAPE_ERROR' | 'COOLDOWN' | 'CONFLICT' | 'VALIDATION' | 'UNAUTHORIZED' | 'NOT_FOUND' | 'STORAGE_ERROR';
+/** 跨线传给前端的错误形状。 */
+export interface ErrorInfo {
+    code: ErrorCode;
+    message: string;
+    retryable: boolean;
+    details?: Record<string, unknown>;
+}
+/** 构造 {@link AppError} 的可选参数。 */
+export interface AppErrorOptions {
+    retryable?: boolean;
+    details?: Record<string, unknown>;
+    cause?: unknown;
+}
+/** 所有本插件错误的基类：带错误码与可重试标记。 */
+export declare class AppError extends Error {
+    readonly code: ErrorCode;
+    readonly retryable: boolean;
+    readonly details: Record<string, unknown> | undefined;
+    constructor(code: ErrorCode, message: string, options?: AppErrorOptions);
+}
+/** 没有可用的 API Key。解析链全空时抛这个。 */
+export declare class NoKeyError extends AppError {
+    constructor(message?: string);
+}
+/** 请求超时。 */
+export declare class TimeoutError extends AppError {
+    constructor(message?: string, options?: AppErrorOptions);
+}
+/** 网络不可达（DNS / 连接失败）。 */
+export declare class NetworkError extends AppError {
+    constructor(message?: string, options?: AppErrorOptions);
+}
+/** 把 HTTP 状态码映射到错误码。 */
+export declare function upstreamCodeOf(status: number): ErrorCode;
+/** 上游返回了非 2xx。 */
+export declare class UpstreamError extends AppError {
+    readonly status: number;
+    readonly headers: Headers | undefined;
+    constructor(status: number, message: string, options?: {
+        headers?: Headers;
+        cause?: unknown;
+    });
+}
+/** 金额或响应体解析失败。绝不静默归 0。 */
+export declare class ParseError extends AppError {
+    constructor(message: string, options?: AppErrorOptions);
+}
+/** 响应结构与契约不符。 */
+export declare class ShapeError extends AppError {
+    constructor(message?: string, options?: AppErrorOptions);
+}
+/** 入参或配置没通过校验。**不可重试** —— 同一份输入重放还是失败。 */
+export declare class ValidationError extends AppError {
+    constructor(message?: string, options?: AppErrorOptions);
+}
+/** 存储层失败。可重试。 */
+export declare class StorageError extends AppError {
+    constructor(message: string, options?: AppErrorOptions);
+}
+/**
+ * 解析 `Retry-After`。支持秒数与 HTTP-date 两种写法。
+ * @param headers - 上游响应头；缺失时返回 `undefined`。
+ * @param now - 当前时刻，HTTP-date 用它算差值；便于测试注入。
+ * @returns 毫秒数，或 `undefined` 表示没给出可用的提示。
+ */
+export declare function parseRetryAfter(headers: Headers | undefined, now?: number): number | undefined;
+/**
+ * 把任意异常映射成对外错误。
+ *
+ * 顺序重要：先认自己的类型，再认带 `status` 的外部错误，最后兜底。
+ * @param error - 任意抛出的值。
+ * @returns 契约里的错误形状。
+ */
+export declare function classify(error: unknown): ErrorInfo;
+/**
+ * 把任意异常压成一行文本，供日志与错误消息使用。
+ *
+ * **绝不带凭据**：上游约定异常文本里不含密钥，所以它可以安全写进日志。
+ * 只取 `Error.message`；非 `Error` 的抛出值退回 `String()`。
+ * @param error - 任意抛出的值。
+ * @returns 单行错误文本。
+ */
+export declare function describeError(error: unknown): string;

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.0.0-alpha.2";
+export declare const PLUGIN_VERSION = "2.0.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.0.0-alpha.2';
+export const PLUGIN_VERSION = '2.0.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ds-balance",
-  "version": "2.0.0-alpha.2",
+  "version": "2.0.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": [