dsh-ds-balance 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zlZayn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# ds-balance
+
+[English](README_en.md)
+
+[![ci](https://github.com/zlZayn/dsh-ds-balance/actions/workflows/ci.yml/badge.svg?branch=main)](.github/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FzlZayn%2Fdsh-ds-balance%2Fmain%2Fpackage.json&query=%24.engines.node&label=node&color=brightgreen)](package.json)
+[![dsh](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FzlZayn%2Fdsh-ds-balance%2Fmain%2Fpackage.json&query=%24.engines.dsh&label=dsh&color=blueviolet)](package.json)
+
+> **NOTE**
+> 本包尚未发布到 npm，现在只能从源码安装。发布流程与版本号判定链见
+> [docs/PUBLISHING.md](docs/PUBLISHING.md)。
+
+在 DSH 的左边栏底部显示 DeepSeek 账户余额，并在设置里提供一张配置卡片。
+余额真实读自官方 `GET /user/balance`；颜色只由后端返回的 `severity` 决定。
+
+![设置卡片](assets/settings-card.png)
+
+## 能力
+
+- 侧栏底部常驻一个状态圆环加名称，点击展开浮层看余额明细；弧长是「余额占 warn 阈值」的比例，折叠与展开共用同一个圆环。
+- 真实读取 DeepSeek 官方余额（`GET /user/balance`），按 `serverRefreshSeconds` 在服务端刷新，
+  浏览器按 `clientPollSeconds` 取缓存，不穿透到上游。
+- 浮层：余额、赠送 / 充值拆分、数据新鲜度与手动刷新（带冷却）。
+- 多币种：由**后端**选定展示币种；设置里选的币种不在账户里时，浮层说明并给出一键改用。
+- 设置卡片分四组、各自可折叠：连接 / 展示 / 阈值 / 刷新，默认四组全收起；组内有非法草稿时该组强制展开。
+- 凭据字段带「已由启动环境提供 / 已配置 / 未配置 / 已覆盖」徽标；只读时框内留空，由徽标与说明行交代原因。凭据默认继承官方模型页配好的那一份，不必重填。
+- 只按后端给的 `severity` 上色；阈值只用来定圆环弧长，不参与配色。
+
+## 安装
+
+前置：DSH `^0.1.6-alpha.1`，Node `>=20`。
+
+从 npm 安装尚未开放（包未发布）。从源码安装：
+
+```bash
+git clone https://github.com/zlZayn/dsh-ds-balance.git
+cd dsh-ds-balance
+npm install
+npm run build
+dsh plugin --profile <profile> add .
+```
+
+装完还要把插件行写进该 profile 的 `cordis.patch.yml`；完整步骤与回滚方式见
+[AGENTS.md](AGENTS.md) 的「常用命令」。
+
+**宿主半边改了代码必须重启 DSH**；浏览器半边由客户端热更换入。
+
+装好之后它在两处出现：设置 → 插件 → 插件配置里的配置卡片，以及左边栏底部的状态圆环。
+
+## 配置
+
+卡片分四组，默认全收起：
+
+- 连接：只读的凭据状态、可编辑的 API 地址，以及收在二级「自定义设置」里的 apiKey 与 apiKeyRef。
+- 展示：金额用哪种币种，或让它自动跟随账户。
+- 阈值：几档提醒线。**由后端判定** —— 前端只拿 `warn` 当圆环弧长的刻度，不据此上色。同一币种的告急必须低于预警，否则保存按钮是灰的。
+- 刷新：服务端刷新周期与浏览器轮询周期。
+
+## 数据从哪来、到哪去
+
+- 端点由宿主半边通过 `ctx.connection.fetch` 注册在 `/api/v1/*` 下，物理载体已做完信任与浏览器鉴权。
+- **API Key 永不返回前端**：配置接口只回一个固定长度的掩码串，连末几位也不给。
+- 密钥只经 DSH 的凭据通道解析，不落日志、不落本插件的文件。
+- 余额快照落在 DSH 自己的存储目录（`ctx.storageDomain`），按凭据派生出的账本标识分组；
+  换 key 自动开新账本，旧快照不会被混用。
+- 一个非记录型文件 `.salt` 落在 `$DSH_HOME` 下，用来派生账本标识；**它丢了旧快照会读不回来**。
+
+## 界面与后端的边界
+
+- 颜色只由后端 `severity` 决定。前端只在圆环弧长里读 `warn` 阈值当刻度，不用它配色。
+- 金额一律是八位小数的字符串，前端按字符串裁两位显示，不经过浮点数。
+- 完整响应形状与配置契约 → [docs/ui-handoff.md](docs/ui-handoff.md)。
+
+## 贡献
+
+报 bug、提功能与提 PR 的前置条件见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## License
+
+MIT，见 [LICENSE](LICENSE)。

package/README_en.md

@@ -0,0 +1,81 @@
+# ds-balance
+
+[中文](README.md)
+
+[![ci](https://github.com/zlZayn/dsh-ds-balance/actions/workflows/ci.yml/badge.svg?branch=main)](.github/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FzlZayn%2Fdsh-ds-balance%2Fmain%2Fpackage.json&query=%24.engines.node&label=node&color=brightgreen)](package.json)
+[![dsh](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FzlZayn%2Fdsh-ds-balance%2Fmain%2Fpackage.json&query=%24.engines.dsh&label=dsh&color=blueviolet)](package.json)
+
+> **NOTE**
+> This package is not on npm yet; it installs from source only.
+> The release flow and the version-bump decision chain are in
+> [docs/PUBLISHING.md](docs/PUBLISHING.md).
+
+Shows the DeepSeek account balance at the bottom of the DSH sidebar, with a configuration card in settings.
+The balance is read from the real `GET /user/balance`; colour comes only from the `severity` the server returns.
+
+![settings card](assets/settings-card_en.png)
+
+## Capabilities
+
+- A permanent status ring plus label at the bottom of the sidebar; click it to open a popover with the balance breakdown. Its arc is the balance as a fraction of the `warn` threshold, and the collapsed and expanded states share the same ring.
+- Reads the real DeepSeek balance (`GET /user/balance`); the server refreshes on `serverRefreshSeconds` and the browser reads the cache on `clientPollSeconds` without hitting the upstream.
+- Popover: total balance, granted / topped-up split, data freshness, and a manual refresh with cooldown.
+- Multiple currencies: the **server** picks which currency to show; when the currency chosen in settings is absent from the account, the popover says so and offers a one-click switch.
+- The settings card has four collapsible groups — Connection / Display / Thresholds / Refresh — all collapsed by default; a group with an invalid draft is forced open.
+- Credential fields carry a "provided by launch environment / configured / not configured / overridden" badge; a read-only field stays empty and lets the badge and the line under it explain why. The credential is inherited from the official model settings by default, so there is nothing to re-enter.
+- Colour comes only from the `severity` the server returns; thresholds only scale the ring arc and never affect colour.
+
+## Installation
+
+Prerequisites: DSH `^0.1.6-alpha.1`, Node `>=20`.
+
+Installing from npm is not open yet (the package is unpublished). From source:
+
+```bash
+git clone https://github.com/zlZayn/dsh-ds-balance.git
+cd dsh-ds-balance
+npm install
+npm run build
+dsh plugin --profile <profile> add .
+```
+
+After installing, add the plugin row to that profile's `cordis.patch.yml`; the full steps and rollback are in
+[AGENTS.md](AGENTS.md), section "常用命令".
+
+**Changing the host half requires restarting DSH**; the browser half is hot-swapped by the client.
+
+Once installed it shows up in two places: a configuration card under Settings → Plugins → Plugin configuration,
+and a status ring at the bottom of the sidebar.
+
+## Configuration
+
+The card has four groups, all collapsed by default:
+
+- Connection: the read-only credential state, an editable API base URL, and the apiKey / apiKeyRef kept inside the nested "Customised settings".
+- Display: which currency to use for amounts, or let it follow the account.
+- Thresholds: the alert lines. They are **evaluated on the server** — the frontend only scales the ring arc by `warn`, and never colours anything from them. Within one currency the critical line must be lower than the warning, or Save stays disabled.
+- Refresh: the server refresh interval and the browser poll interval.
+
+## Where the data comes from and goes
+
+- Endpoints are registered by the host half under `/api/v1/*` via `ctx.connection.fetch`; the physical carrier already applies trust and browser authentication.
+- **The API key is never returned to the frontend**: the config endpoint returns only a fixed-length mask, not even the last few characters.
+- The key is resolved only through the DSH credential channel; it is never logged and never written to a file owned by this plugin.
+- Balance snapshots land in DSH's own storage (`ctx.storageDomain`), grouped by a ledger identifier derived from the credential. Changing the key opens a new ledger; old snapshots are never mixed in.
+- One non-record file, `.salt`, lives under `$DSH_HOME` and derives the ledger identifier. **Losing it makes old snapshots unreadable.**
+
+## Boundary between UI and backend
+
+- Colour is decided only by the server's `severity`. The frontend reads the `warn` threshold only to scale the ring arc, never to colour anything.
+- Amounts are always eight-decimal strings; the frontend trims them to two characters-wise and never goes through floating point.
+- Full response shape and configuration contract → [docs/ui-handoff.md](docs/ui-handoff.md).
+
+## Contributing
+
+Prerequisites for bug reports, feature proposals, and pull requests are in [CONTRIBUTING_en.md](CONTRIBUTING_en.md).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-ds-balance bundle patch —— 把本插件作为一行插入 dsh profile。
+#
+# 格式对齐 DSH 官方 bundle patch：顶层是 loader patch 条目数组；
+# `insert` 在 profile 根上追加插件行。
+#
+# name 必须是 loader 能从 profile 的 node_modules 解析到的模块 id，即本包自身的包名。
+- insert:
+    - id: dsh-ds-balance
+      name: dsh-ds-balance

package/lib/adapters/console-logger.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 控制台日志。
+ *
+ * 宿主半边**没有统一的 logger 服务**，所以直接落 `console`。
+ * 字段对象原样序列化，因此**调用方不许把凭据传进来** ——
+ * 这是 `services/` 与 `adapters/` 共同的规则。
+ * @module dsh-ds-balance/adapters/console-logger
+ */
+import type { Logger } from '../ports/logger.js';
+/** 每条日志的前缀，便于在宿主输出里筛。 */
+export declare const LOG_PREFIX = "[ds-balance]";
+/** 日志落点。测试注入替身，生产用全局 `console`。 */
+export interface ConsoleLike {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/**
+ * 造一个落 `console` 的日志器。
+ * @param sink - 落点；默认全局 `console`。
+ * @returns 端口实现。
+ */
+export declare function createConsoleLogger(sink?: ConsoleLike): Logger;
+//# sourceMappingURL=console-logger.d.ts.map

package/lib/adapters/console-logger.js

@@ -0,0 +1,35 @@
+/**
+ * 控制台日志。
+ *
+ * 宿主半边**没有统一的 logger 服务**，所以直接落 `console`。
+ * 字段对象原样序列化，因此**调用方不许把凭据传进来** ——
+ * 这是 `services/` 与 `adapters/` 共同的规则。
+ * @module dsh-ds-balance/adapters/console-logger
+ */
+/** 每条日志的前缀，便于在宿主输出里筛。 */
+export const LOG_PREFIX = '[ds-balance]';
+/** 把字段对象序列化；序列化不了就退回占位串，绝不因为日志把流程打断。 */
+function render(fields) {
+    if (fields === undefined)
+        return '';
+    try {
+        return ' ' + JSON.stringify(fields);
+    }
+    catch {
+        return ' [unserializable fields]';
+    }
+}
+/**
+ * 造一个落 `console` 的日志器。
+ * @param sink - 落点；默认全局 `console`。
+ * @returns 端口实现。
+ */
+export function createConsoleLogger(sink = console) {
+    return {
+        debug: (message, fields) => { sink.debug(`${LOG_PREFIX} ${message}${render(fields)}`); },
+        info: (message, fields) => { sink.info(`${LOG_PREFIX} ${message}${render(fields)}`); },
+        warn: (message, fields) => { sink.warn(`${LOG_PREFIX} ${message}${render(fields)}`); },
+        error: (message, fields) => { sink.error(`${LOG_PREFIX} ${message}${render(fields)}`); },
+    };
+}
+//# sourceMappingURL=console-logger.js.map

package/lib/adapters/domain-core-store.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 用 dsh 官方存储接缝实现 {@link CoreStore}。
+ *
+ * 关键约束（见 docs/backend-architecture.md §10）：
+ * - `open` 每进程只能一次，重名抛 `already-open`；
+ * - **`close()` 必须由调用方在 `ctx.effect` 的 disposer 里调用**，否则热重挂会锁死；
+ * - 打开失败要**降级**而不是抛出去 —— 未观察的 rejection 曾把宿主整个拖下水。
+ * @module dsh-ds-balance/adapters/domain-core-store
+ */
+import type { BalanceSnapshot } from '../domain/balance.js';
+import type { CoreStore, StoreHealth } from '../ports/core-store.js';
+import type { Logger } from '../ports/logger.js';
+/** 域里的表名。 */
+export declare const SNAPSHOT_TABLE = "snapshots";
+/** 域记录：JSON 安全形状，金额存字符串最小单位。 */
+export interface StoredSnapshot {
+    snapshotId: string;
+    accountTag: string;
+    fetchedAt: number;
+    isAvailable: boolean;
+    balances: Array<{
+        currency: string;
+        total: string;
+        granted: string;
+        toppedUp: string;
+    }>;
+    source: 'deepseek-http';
+}
+/**
+ * 域声明。
+ *
+ * `backend` **不写**：路由归部署方（默认组合只有 json 后端），插件无权指定。
+ */
+export declare const DS_BALANCE_DOMAIN: {
+    name: string;
+    version: number;
+    tables: {
+        snapshots: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, StoredSnapshot>;
+    };
+};
+/** 表句柄的最小结构化面；测试用替身实现它。 */
+export interface KvTableLike {
+    get(key: string): StoredSnapshot | undefined;
+    keys(): IterableIterator<string>;
+    put(key: string, value: StoredSnapshot): Promise<void>;
+}
+/** 域句柄的最小结构化面。 */
+export interface DomainLike {
+    table(name: string): KvTableLike;
+    close(): Promise<void>;
+}
+/** 打开域的函数；生产里传 `(spec) => ctx.storageDomain.open(spec)`。 */
+export type DomainOpener = (spec: typeof DS_BALANCE_DOMAIN) => Promise<DomainLike>;
+/** 构造参数。 */
+export interface DomainCoreStoreOptions {
+    open: DomainOpener;
+    logger?: Logger;
+}
+/** 把领域快照转成可 JSON 化的记录。 */
+export declare function toStored(snapshot: BalanceSnapshot): StoredSnapshot;
+/** 把记录还原成领域快照。金额坏掉时抛 `ParseError`，绝不静默归零。 */
+export declare function fromStored(record: StoredSnapshot): BalanceSnapshot;
+/**
+ * 官方存储接缝上的快照存储。
+ *
+ * 构造期**永不抛错**，而且**打开是懒的、失败可重试**：
+ *
+ * - **懒打开**：`storageDomain` 可能在插件装载之后才就绪；构造期就打开会把一次
+ *   过早的失败永久钉死。第一次用到时才开。
+ * - **失败可重试**：一轮打开失败只记一次 error，之后每次操作重新试一次；
+ *   服务后到了就自动接上，不必重挂插件。
+ * - **永不产生未观察的 rejection**：`ensureOpen` 返回的 promise 永远 resolve，
+ *   错误记在 `openError` 上，由调用方按需翻成 {@link StorageError}。
+ *   已装插件的注释说，逃出去的 rejection 曾经能把整个宿主拖下水。
+ */
+export declare class DomainCoreStore implements CoreStore {
+    private readonly options;
+    /** 正在进行的这一轮打开；成功后常驻，失败后置回 `null` 以便重试。 */
+    private ready;
+    private handle;
+    private table;
+    private openError;
+    /** 打开失败只记一次日志，免得每次操作都刷屏。 */
+    private openFailureLogged;
+    private closed;
+    constructor(options: DomainCoreStoreOptions);
+    /** 确保域已打开。**永不 reject。** */
+    private ensureOpen;
+    private initialize;
+    /** 拿到可用表，或在降级状态下抛出可读错误。 */
+    private requireTable;
+    saveSnapshot(snapshot: BalanceSnapshot): Promise<void>;
+    /**
+     * 读该账本最近一条快照。
+     *
+     * **按 `accountTag` 过滤**：凭据轮换后 tag 会变，旧快照不得混用。
+     * 用 `snapshotId`（单调可排序）决定新旧，不依赖 `fetchedAt`。
+     */
+    loadLatestSnapshot(accountTag: string): Promise<BalanceSnapshot | null>;
+    health(): Promise<StoreHealth>;
+    /** 幂等关闭。**必须挂在 `ctx.effect` 的 disposer 上。** */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=domain-core-store.d.ts.map

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

@@ -0,0 +1,184 @@
+/**
+ * 用 dsh 官方存储接缝实现 {@link CoreStore}。
+ *
+ * 关键约束（见 docs/backend-architecture.md §10）：
+ * - `open` 每进程只能一次，重名抛 `already-open`；
+ * - **`close()` 必须由调用方在 `ctx.effect` 的 disposer 里调用**，否则热重挂会锁死；
+ * - 打开失败要**降级**而不是抛出去 —— 未观察的 rejection 曾把宿主整个拖下水。
+ * @module dsh-ds-balance/adapters/domain-core-store
+ */
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
+import { z } from 'zod';
+import { StorageError } from '../domain/errors.js';
+import { formatMoney, parseMoney } from '../domain/money.js';
+/** 域里的表名。 */
+export const SNAPSHOT_TABLE = 'snapshots';
+const storedBalanceSchema = z.object({
+    currency: z.string(),
+    total: z.string(),
+    granted: z.string(),
+    toppedUp: z.string(),
+});
+const storedSnapshotSchema = z.object({
+    snapshotId: z.string(),
+    accountTag: z.string(),
+    fetchedAt: z.number(),
+    isAvailable: z.boolean(),
+    balances: z.array(storedBalanceSchema),
+    source: z.literal('deepseek-http'),
+});
+/**
+ * 域声明。
+ *
+ * `backend` **不写**：路由归部署方（默认组合只有 json 后端），插件无权指定。
+ */
+export const DS_BALANCE_DOMAIN = defineDomain({
+    name: 'ds_balance',
+    version: 1,
+    tables: {
+        [SNAPSHOT_TABLE]: domainTable(storedSnapshotSchema),
+    },
+});
+/** 把领域快照转成可 JSON 化的记录。 */
+export function toStored(snapshot) {
+    return {
+        snapshotId: snapshot.snapshotId,
+        accountTag: snapshot.accountTag,
+        fetchedAt: snapshot.fetchedAt,
+        isAvailable: snapshot.isAvailable,
+        balances: snapshot.balances.map((item) => ({
+            currency: item.currency,
+            total: formatMoney(item.total),
+            granted: formatMoney(item.granted),
+            toppedUp: formatMoney(item.toppedUp),
+        })),
+        source: snapshot.source,
+    };
+}
+/** 把记录还原成领域快照。金额坏掉时抛 `ParseError`，绝不静默归零。 */
+export function fromStored(record) {
+    const balances = record.balances.map((item) => ({
+        currency: item.currency,
+        total: parseMoney(item.total),
+        granted: parseMoney(item.granted),
+        toppedUp: parseMoney(item.toppedUp),
+    }));
+    return {
+        snapshotId: record.snapshotId,
+        accountTag: record.accountTag,
+        fetchedAt: record.fetchedAt,
+        isAvailable: record.isAvailable,
+        balances,
+        source: record.source,
+        raw: undefined,
+    };
+}
+/** 把未知异常压成一行可读文本。 */
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * 官方存储接缝上的快照存储。
+ *
+ * 构造期**永不抛错**，而且**打开是懒的、失败可重试**：
+ *
+ * - **懒打开**：`storageDomain` 可能在插件装载之后才就绪；构造期就打开会把一次
+ *   过早的失败永久钉死。第一次用到时才开。
+ * - **失败可重试**：一轮打开失败只记一次 error，之后每次操作重新试一次；
+ *   服务后到了就自动接上，不必重挂插件。
+ * - **永不产生未观察的 rejection**：`ensureOpen` 返回的 promise 永远 resolve，
+ *   错误记在 `openError` 上，由调用方按需翻成 {@link StorageError}。
+ *   已装插件的注释说，逃出去的 rejection 曾经能把整个宿主拖下水。
+ */
+export class DomainCoreStore {
+    options;
+    /** 正在进行的这一轮打开；成功后常驻，失败后置回 `null` 以便重试。 */
+    ready = null;
+    handle = null;
+    table = null;
+    openError;
+    /** 打开失败只记一次日志，免得每次操作都刷屏。 */
+    openFailureLogged = false;
+    closed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    /** 确保域已打开。**永不 reject。** */
+    ensureOpen() {
+        if (this.closed)
+            return Promise.resolve();
+        if (this.ready === null) {
+            const attempt = this.initialize().catch((error) => {
+                this.openError = error;
+                this.handle = null;
+                this.table = null;
+                this.ready = null;
+                if (!this.openFailureLogged) {
+                    this.openFailureLogged = true;
+                    this.options.logger?.error('ds-balance: storage domain unavailable, running degraded', { error: describe(error) });
+                }
+            });
+            this.ready = attempt;
+        }
+        return this.ready;
+    }
+    async initialize() {
+        const handle = await this.options.open(DS_BALANCE_DOMAIN);
+        this.handle = handle;
+        this.table = handle.table(SNAPSHOT_TABLE);
+        this.openError = undefined;
+    }
+    /** 拿到可用表，或在降级状态下抛出可读错误。 */
+    async requireTable() {
+        await this.ensureOpen();
+        if (this.openError !== undefined) {
+            throw new StorageError(`storage domain unavailable: ${describe(this.openError)}`, { cause: this.openError });
+        }
+        if (this.table === null)
+            throw new StorageError('storage domain is not open');
+        return this.table;
+    }
+    async saveSnapshot(snapshot) {
+        const table = await this.requireTable();
+        await table.put(snapshot.snapshotId, toStored(snapshot));
+    }
+    /**
+     * 读该账本最近一条快照。
+     *
+     * **按 `accountTag` 过滤**：凭据轮换后 tag 会变，旧快照不得混用。
+     * 用 `snapshotId`（单调可排序）决定新旧，不依赖 `fetchedAt`。
+     */
+    async loadLatestSnapshot(accountTag) {
+        const table = await this.requireTable();
+        let newest = null;
+        for (const key of table.keys()) {
+            const record = table.get(key);
+            if (record === undefined || record.accountTag !== accountTag)
+                continue;
+            if (newest === null || record.snapshotId > newest.snapshotId)
+                newest = record;
+        }
+        return newest === null ? null : fromStored(newest);
+    }
+    async health() {
+        if (this.closed)
+            return { ok: false, detail: 'closed' };
+        await this.ensureOpen();
+        return this.openError === undefined ? { ok: true } : { ok: false, detail: describe(this.openError) };
+    }
+    /** 幂等关闭。**必须挂在 `ctx.effect` 的 disposer 上。** */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const pending = this.ready;
+        if (pending !== null)
+            await pending;
+        const handle = this.handle;
+        this.handle = null;
+        this.table = null;
+        if (handle !== null)
+            await handle.close();
+    }
+}
+//# sourceMappingURL=domain-core-store.js.map

package/lib/adapters/http-deepseek-client.d.ts

@@ -0,0 +1,36 @@
+/**
+ * DeepSeek 上游的 HTTP 实现。
+ * @module dsh-ds-balance/adapters/http-deepseek-client
+ */
+import type { RawBalanceResponse } from '../domain/balance.js';
+import type { DeepSeekCallOptions, DeepSeekClient, TestConnectionResult } from '../ports/deepseek-client.js';
+/** 可替换的 fetch，便于测试注入。 */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** 构造参数。 */
+export interface HttpDeepSeekClientOptions {
+    /** 注入 fetch；默认用全局 `fetch`。 */
+    fetchImpl?: FetchLike;
+    /** 注入时刻函数，测延迟用。 */
+    now?: () => number;
+}
+/**
+ * 用 WHATWG fetch 调 DeepSeek 的 `GET /user/balance`。
+ *
+ * 超时用自建的 `AbortController + setTimeout`（而不是 `AbortSignal.timeout`），
+ * 这样测试可以在不睡真实时间的前提下驱动超时分支。
+ */
+export declare class HttpDeepSeekClient implements DeepSeekClient {
+    private readonly fetchImpl;
+    private readonly now;
+    constructor(options?: HttpDeepSeekClientOptions);
+    fetchBalance(options: DeepSeekCallOptions): Promise<RawBalanceResponse>;
+    testConnection(options: DeepSeekCallOptions): Promise<TestConnectionResult>;
+    /**
+     * 发一次请求并处理状态码。
+     * @throws {UpstreamError} 非 2xx。
+     * @throws {TimeoutError} 超时。
+     * @throws {NetworkError} 连不上。
+     */
+    private request;
+}
+//# sourceMappingURL=http-deepseek-client.d.ts.map