dsh-ds-balance 2.1.2 → 2.2.0

package/lib/index.js

@@ -22,6 +22,10 @@ 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 { createAccountSource } from './adapters/host-account.js';
+import { SourceLedger } from './services/balance-source.js';
+import { accountReader, keyReader } from './services/source-readers.js';
+import { PLUGIN_VERSION } from './version.js';
 export { Config, ENTRY_ID } from './config.js';
 export { CURRENCY_AUTO } from './config.js';
 /** 插件名，loader 诊断用。 */
@@ -184,6 +188,81 @@ function connectStorage(ctx) {
         return (await facility.open(spec));
     };
 }
+/**
+ * 接上账号登录态这条可选接缝。
+ *
+ * 与 `connectStorage` 同一套把门方式：`deepseekAccount` 可能在插件装载之后才就绪，
+ * 所以句柄是可变的、缺席时读回 `undefined`（账号那条账本据此判「这条路此刻不可用」）。
+ *
+ * 服务面按鸭子类型收窄（见 [host-account.ts](adapters/host-account.ts) 的说明）。
+ * @param ctx - 宿主上下文。
+ * @param logger - 日志端口。
+ * @returns 取当前端口实现的函数。
+ */
+function connectAccount(ctx, logger) {
+    const handle = {};
+    const handlers = new Set();
+    ctx.inject(['deepseekAccount'], (accountCtx) => {
+        accountCtx.effect(() => {
+            const service = accountCtx
+                .deepseekAccount;
+            handle.source = createAccountSource({
+                service,
+                version: PLUGIN_VERSION,
+                // 只选 Platform 那边的服务端文案；界面文案由本插件自己的词典给。
+                locale: 'zh-CN',
+                timezoneOffsetSeconds: () => -new Date().getTimezoneOffset() * 60,
+                logger,
+            });
+            for (const handler of [...handlers])
+                handler();
+            return () => {
+                handle.source = undefined;
+            };
+        }, 'ds-balance: account source');
+    });
+    return {
+        current: () => handle.source,
+        onReady: (handler) => {
+            handlers.add(handler);
+            // 服务可能早就到位（inject 回调同步跑过），那就当场通知一次。
+            if (handle.source !== undefined)
+                handler();
+        },
+    };
+}
+/**
+ * 接上「当前默认模型走哪条路由」这条可选接缝。
+ *
+ * 只用来定**全局默认来源**；会话级的来源由客户端当提示带上来（见 `GetViewOptions.providerHint`）。
+ * 服务缺席时读回 `null`，选源就只按「Key 优先，账号兜底」走。
+ * @param ctx - 宿主上下文。
+ * @returns 读当前 provider id 的函数。
+ */
+function connectRoute(ctx) {
+    const handle = {};
+    const handlers = new Set();
+    ctx.inject(['agentDefaultModel'], (routeCtx) => {
+        routeCtx.effect(() => {
+            const model = routeCtx.agentDefaultModel;
+            // 现读：宿主的这个服务每次都从它自己的配置引用里取，不做缓存。
+            handle.read = () => model.currentSelection().provider ?? null;
+            for (const handler of [...handlers])
+                handler();
+            return () => {
+                handle.read = undefined;
+            };
+        }, 'ds-balance: model route');
+    });
+    return {
+        current: () => handle.read?.() ?? null,
+        onReady: (handler) => {
+            handlers.add(handler);
+            if (handle.read !== undefined)
+                handler();
+        },
+    };
+}
 /**
  * 组装并交出生命周期。
  *
@@ -214,17 +293,54 @@ export async function apply(ctx, refs) {
     // 默认组合没有指标 sink，所以用内存登记表把聚合值留下来，
     // 由 healthz 的 metrics 段暴露（见 .agents/notes 的决策）。
     const metrics = new MemoryMetrics();
+    // 两条取数路各持一份账本；选源由门面按四层回落决定。
+    const account = connectAccount(ctx, logger);
+    const route = connectRoute(ctx);
+    const ledgers = new Map([
+        [
+            'deepseek-http',
+            new SourceLedger({
+                source: 'deepseek-http',
+                reader: keyReader({ keys, client, config: configService, salt }),
+                store,
+                config: configService,
+                clock: systemClock,
+                logger,
+                metrics,
+            }),
+        ],
+        [
+            'deepseek-account',
+            new SourceLedger({
+                source: 'deepseek-account',
+                reader: accountReader({ account: () => account.current(), salt }),
+                store,
+                config: configService,
+                clock: systemClock,
+                logger,
+                metrics,
+            }),
+        ],
+    ]);
     const service = new BalanceService({
-        client,
-        store,
-        keys,
-        config: configService,
-        clock: systemClock,
-        salt,
+        ledgers,
+        routeProvider: () => route.current(),
         logger,
         metrics,
     });
     const scheduler = new Scheduler({ target: service, logger });
+    /**
+     * 可选服务到位时把来源判据重定一次。
+     *
+     * 宿主刚起来时账号与默认模型可能都还没就绪，那一次解析只能按兜底走；服务到齐后
+     * 作废「已定」并立刻重排一轮，免得首屏那一分钟一直在刷错的那条账本。
+     */
+    const reselectSource = () => {
+        service.invalidateSource();
+        scheduler.reset();
+    };
+    account.onReady(reselectSource);
+    route.onReady(reselectSource);
     ctx.effect(() => {
         // 排程只看这几项。事件给的是「真的变了的路径」，比原来的全量 diff 更准，
         // 所以改阈值、改展示币种都不会顺带打一次官方接口。

package/lib/ports/account.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 账号登录态端口。
+ *
+ * 宿主提供这条接缝（`ctx.deepseekAccount`）时才装配；**缺席时账号那条取数路整条不存在**，
+ * 插件退回只看 API Key —— 与没有这条接缝之前逐字相同。
+ * @module dsh-ds-balance/ports/account
+ */
+import type { AccountBalance } from '../domain/account.js';
+/** 账号来源的只读面。没有写入口：余额只是读。 */
+export interface AccountSource {
+    /** 本地存着登录凭据（宿主原文：存储态，不代表服务端验过）。 */
+    signedIn(): Promise<boolean>;
+    /**
+     * 稳定账号 id：作为账号账本的派生输入。
+     *
+     * 拿不到时回 `null`（宿主本次进程还没读过 profile），调用方按「未知账号」处理。
+     */
+    accountId(): Promise<string | null>;
+    /**
+     * 读一次钱包。
+     *
+     * `null` 表示**此刻没有可用账号**（未登录，或凭据在查询途中被换掉）——
+     * 调用方据此回落另一条路，而不是把它当成零余额。
+     */
+    readBalance(): Promise<AccountBalance | null>;
+}
+//# sourceMappingURL=account.d.ts.map

package/lib/ports/account.js

@@ -0,0 +1,9 @@
+/**
+ * 账号登录态端口。
+ *
+ * 宿主提供这条接缝（`ctx.deepseekAccount`）时才装配；**缺席时账号那条取数路整条不存在**，
+ * 插件退回只看 API Key —— 与没有这条接缝之前逐字相同。
+ * @module dsh-ds-balance/ports/account
+ */
+export {};
+//# sourceMappingURL=account.js.map

package/lib/services/balance-service.d.ts

@@ -1,71 +1,56 @@
 /**
- * 余额缓存与状态机。
+ * 余额服务门面：**决定这一轮走哪条取数路**，然后把活交给那条路的账本。
  *
- * 职责：把「拿密钥 → 调上游 → 归一化 → 落快照」包成一次可合并的请求，并维护缓存状态。
- * **对外永不抛错**：一切失败都变成 `view.state` 与 `view.error`。
+ * 门面自己不持状态、不抓数据 —— 两份状态在 {@link SourceLedger} 里，一个来源一份。
+ * 选源规则是四层回落（会话路由 → 全局默认路由 → Key 优先 → 都没有），判据是纯函数
+ * [source-selector.ts](source-selector.ts)；两条路的读取策略在
+ * [source-readers.ts](source-readers.ts)。
  * @module dsh-ds-balance/services/balance-service
  */
-import type { BalanceView, CacheState } from '../domain/balance.js';
-import { type ErrorCode } from '../domain/errors.js';
-import type { Clock } from '../ports/clock.js';
-import type { CoreStore } from '../ports/core-store.js';
-import type { DeepSeekClient } from '../ports/deepseek-client.js';
+import type { BalanceSource, BalanceView } from '../domain/balance.js';
 import type { Logger } from '../ports/logger.js';
-import { type Metrics } from '../ports/metrics.js';
-import type { ConfigService } from './config-service.js';
-import type { KeyResolver } from './key-resolver.js';
-/** `forceRefresh` 的返回值，形状对齐契约 §8.4。 */
-export interface RefreshResult {
-    triggered: boolean;
-    joined: boolean;
-    cooldownMs: number;
-    state: CacheState;
-}
-/** 调度器需要的状态切片。 */
-export interface BalanceStatus {
-    state: CacheState;
-    errorCode: ErrorCode | null;
-    consecutiveFailures: number;
-    hasSnapshot: boolean;
-    serverRefreshSeconds: number;
-    /** 上游给的 `Retry-After`，优先于自算退避。 */
-    retryAfterMs: number | null;
-    /** 最近一次成功抓取的时刻；从未成功过是 `null`。健康检查要用。 */
-    lastSuccessAt: number | null;
-}
+import type { Metrics } from '../ports/metrics.js';
+import type { BalanceStatus, LedgerViewOptions, RefreshResult, SourceLedger } from './balance-source.js';
+export type { BalanceStatus, RefreshResult, SourceReader } from './balance-source.js';
 /** `getView` 的可选参数。 */
-export interface GetViewOptions {
-    /** 跳过新鲜度判据强制拉一次。 */
-    force?: boolean;
-    /** 覆盖展示币种偏好；缺省读配置。 */
-    currency?: string;
+export interface GetViewOptions extends LedgerViewOptions {
+    /**
+     * 客户端给的**当前会话路由 id**（宿主 provider 名）。
+     *
+     * 只当提示用：认不出来或没给，就回落到全局默认路由 —— 客户端读不到会话时，
+     * 界面不该因此失去来源。
+     */
+    providerHint?: string | null;
 }
 /** 构造参数。 */
 export interface BalanceServiceOptions {
-    client: DeepSeekClient;
-    store: CoreStore;
-    keys: KeyResolver;
-    config: ConfigService;
-    clock: Clock;
-    /** 服务端盐，用来算 `accountTag`。 */
-    salt: string;
+    /** 两条账本；两个 id 都要在。 */
+    ledgers: ReadonlyMap<BalanceSource, SourceLedger>;
+    /** 全局默认路由 id（宿主 `agentDefaultModel.currentSelection().provider`）；读不到回 `null`。 */
+    routeProvider: () => string | null;
     logger?: Logger | undefined;
+    /** 指标；来源切换计数用它（界面刻意不给提示，这是唯一观测出口）。 */
     metrics?: Metrics | undefined;
 }
-/** 余额缓存与状态机。 */
+/** 余额服务门面。 */
 export declare class BalanceService {
     private readonly options;
-    private readonly metrics;
-    private snapshot;
-    private state;
-    private error;
-    private failures;
-    private retryAfterMs;
-    private inflight;
-    /** 落盘失败只报一次，避免每轮刷新都刷屏。 */
-    private persistWarned;
+    /** 当前活跃来源；由最近一次解析决定，调度与健康检查读它。 */
+    private active;
+    /**
+     * 来源判据是否已经定下来过。
+     *
+     * 宿主刚起来时两个可选服务（账号、默认模型）可能还没到，那一次解析只能按兜底走；
+     * 服务到齐后由装配处调 {@link invalidateSource} + `scheduler.reset()` 重新定一次。
+     * 一旦有请求解析过就以请求为准 —— 调度不拿全局默认去顶会话级的来源。
+     */
+    private resolved;
+    /** 每条路只恢复一次（存储扫描不便宜，来回切来源不该重复扫）。 */
+    private readonly restores;
     constructor(options: BalanceServiceOptions);
-    /** 当前状态切片，供调度与健康检查使用。 */
+    /** 当前活跃来源。诊断与测试用。 */
+    activeSource(): BalanceSource;
+    /** 当前活跃账本的状态切片，供调度与健康检查使用。 */
     status(): BalanceStatus;
     /**
      * 当前账本标识的前 8 位；还没有快照时是 `null`。
@@ -73,49 +58,45 @@ export declare class BalanceService {
      * **只回前 8 位**：完整 tag 是账本作用域标识，没有对外的理由。
      */
     accountTag8(): string | null;
-    /**
-     * 从存储恢复最近快照（挂载时调一次）。
-     *
-     * **按 `accountTag` 过滤**：凭据轮换后 tag 变了，旧快照视为不存在，不混用。
-     * 没有密钥可算 tag 时静默跳过。
-     */
+    /** 从存储恢复最近快照（挂载时调一次，恢复的是**当前活跃来源**那条账本）。 */
     restore(): Promise<void>;
     /**
      * 取当前视图。
      *
-     * 有在飞的请求就合并；不 force 且未过期就返回缓存；否则拉一次。
-     */
-    getView(options?: GetViewOptions): Promise<BalanceView>;
-    /**
-     * 手动刷新。
+     * `providerHint` 一变（用户切了会话、切了模型）就重新解析来源 —— 这是「跟着会话走」的入口。
      *
-     * 冷却中不触发；已有请求在飞时合并并回报 `joined`。
+     * **本插件只记官方的那一个数字**，所以首选那条路拿不出数字时**退到另一条官方路**：
+     * 叉（空态 / 失败态）只在「官方两条路都拿不到数据」时才出现 —— 那才是「没接入官方」。
      */
-    forceRefresh(reason: string): Promise<RefreshResult>;
-    /** 快照是否还在 `serverRefreshSeconds` 窗口内。**只看时间，不看状态。** */
-    private withinWindow;
+    getView(options?: GetViewOptions): Promise<BalanceView>;
+    /** 取一条路的视图（先确保它恢复过）。 */
+    private viewOf;
     /**
-     * 能否直接拿缓存顶上。
+     * 定时刷新：刷**用户实际看到的那条**。
      *
-     * 与 {@link withinWindow} 分开：`restore` 要在状态还是 `empty` 时用纯时间判据，
-     * 而这里必须要求 `ok` —— 否则一次失败之后，窗口内的旧快照会让 `getView`
-     * 永远不再重试。
+     * 来源还没定过（宿主刚起来、可选服务未到齐）时先解析一次；定过之后就认 `active` ——
+     * 而 `active` 是**上一次真正把数字交出去的那条**（`getView` 兜底出去的也算），
+     * 所以兜底展示的账号数字才会被继续刷新，不会永远停在一张旧快照上。
      */
-    private canServeCache;
-    /** 跑一次真实抓取。**所有异常都在这里被吸收。** */
-    private fetchOnce;
+    refreshActive(): Promise<BalanceView>;
+    /** 作废「来源已定」这件事，让下一次调度重新解析。 */
+    invalidateSource(): void;
     /**
-     * 把快照落盘。
+     * 手动刷新：**用户看哪条就刷哪条**（与 {@link getView} 同一条判定）。
      *
-     * **失败只记一次 warn，不往上抛**：存储层降级不该让整个余额功能不可用。
-     * @param snapshot - 刚归一化出来的快照。
+     * 首选那条一条数字都没有时，界面上实际是兜底那条在撑着 —— 那就刷兜底那条，
+     * 否则用户点了刷新、数字却永远不动。冷却仍由那条自己的账本管。
      */
-    private persist;
-    /** 记录一次失败，并把状态推到 `stale` 或 `error`。 */
-    private applyFailure;
-    /** 把缓存状态推成指标。 */
-    private publishGauge;
-    /** 把缓存折成对外视图。 */
-    private toView;
+    forceRefresh(reason: string, providerHint?: string | null): Promise<RefreshResult>;
+    /** 找一条**有快照**的官方路；都没有就退回默认那条（那时才画叉）。 */
+    private firstWithSnapshot;
+    /** 记下「这条刚刚把数字交出去了」：展示、刷新、标签从此都认它。 */
+    private mark;
+    /** 解析这一轮**首选**哪条路。 */
+    private resolve;
+    /** 取账本；缺一条属于装配错误，直接抛（静默降级会让界面永远停在空态）。 */
+    private ledger;
+    /** 首次用到某条路时才恢复它的快照；并发调用合并成一次。 */
+    private restoreLedger;
 }
 //# sourceMappingURL=balance-service.d.ts.map