dsh-ds-balance 2.2.0 → 2.3.0

package/README.md

@@ -132,6 +132,9 @@ dsh plugin --profile web add "$PWD"
 
 与 npm 那条路一样，重启后生效。
 
+⚠️ 上面那步 `npm install` 不能省：`link:` 装法下依赖由仓库自己提供（见 [AGENTS.md](AGENTS.md)），
+漏装则插件显示「未运行」（`ERR_MODULE_NOT_FOUND`）。
+
 ### 发现与安装
 
 - **npm**：[`dsh-ds-balance`](https://www.npmjs.com/package/dsh-ds-balance)

package/README_en.md

@@ -134,6 +134,10 @@ dsh plugin --profile web add "$PWD"
 
 Same as the npm route: it takes effect after a restart.
 
+⚠️ The `npm install` above is not optional: under the `link:` form the repository supplies its
+own dependencies (see [AGENTS.md](AGENTS.md)) — skip it and the plugin shows as "not running"
+(`ERR_MODULE_NOT_FOUND`).
+
 ### Discovery
 
 - **npm**: [`dsh-ds-balance`](https://www.npmjs.com/package/dsh-ds-balance)

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

@@ -7,7 +7,7 @@
  * - 打开失败要**降级**而不是抛出去 —— 未观察的 rejection 曾把宿主整个拖下水。
  * @module dsh-ds-balance/adapters/domain-core-store
  */
-import type { BalanceSnapshot, BalanceSource } from '../domain/balance.js';
+import { type BalanceSnapshot, type BalanceSource } from '../domain/balance.js';
 import type { CoreStore, StoreHealth } from '../ports/core-store.js';
 import type { Logger } from '../ports/logger.js';
 /** 域里的表名。 */
@@ -41,8 +41,11 @@ export declare const DS_BALANCE_DOMAIN: {
 /** 表句柄的最小结构化面；测试用替身实现它。 */
 export interface KvTableLike {
     get(key: string): StoredSnapshot | undefined;
+    /** 一次迭代同时拿到 `[key, record]`；比 `keys()` +逐键 `get()` 少一轮查找。 */
+    entries(): IterableIterator<[string, StoredSnapshot]>;
     keys(): IterableIterator<string>;
     put(key: string, value: StoredSnapshot): Promise<void>;
+    delete(key: string): Promise<boolean>;
 }
 /** 域句柄的最小结构化面。 */
 export interface DomainLike {
@@ -95,8 +98,49 @@ export declare class DomainCoreStore implements CoreStore {
      *
      * **按 `accountTag` 过滤**：凭据轮换后 tag 会变，旧快照不得混用。
      * 用 `snapshotId`（单调可排序）决定新旧，不依赖 `fetchedAt`。
+     *
+     * **走 `entries()` 而不是 `keys()` + 逐键 `get()`**：后者是每条记录两次查找，
+     * 记录数涨上去（保留策略落地前实测过千条）时白费一大半；`entries()` 一次迭代给全。
      */
     loadLatestSnapshot(accountTag: string): Promise<BalanceSnapshot | null>;
+    /**
+     * 只保留该账本最近 `keepN` 条，删掉更旧的（跨账本不动）。
+     *
+     * **批间让出事件循环的理由是摊平写放大，不是防限流**：宿主 json 后端默认 `single`
+     * 布局，每次 `delete` 都要原子重写整份单元文件。删几十条若挤在同一个 tick 上，
+     * 会连带把同一进程里的取数与轮询一起拖住。所以内部**分批 + 每批之后让出一次** ——
+     * 批次大小与间隔属于实现细节，不上端口（领域层只调一次，不需要知道分了几批）。
+     *
+     * **单次最多删 {@link PRUNE_MAX_PER_CALL} 条**：超出部分留给后续启动或写入路径，
+     * 保证任何一次调用的耗时都有确定上界（理由见那个常量）。
+     *
+     * **零写入的幂等**：没超期时一条都不删、返回 0（超期判定先做完再动手）。
+     *
+     * @param accountTag - 要修剪的账本。
+     * @param keepN - 保留条数（新到旧）。
+     * @returns 本次**实际**删掉的条数（可能小于超期总数，因为有单次上限）。
+     */
+    pruneByTag(accountTag: string, keepN: number): Promise<number>;
+    /**
+     * 修剪一个账本的内部实现（不重复 `requireTable` 的开表开销）。
+     */
+    private pruneOwned;
+    /**
+     * 启动时的一次性清理：把**所有**账本桶各修剪一次。
+     *
+     * 为什么扫全表而不是只清「当前那个账本」：启动这一刻还不知道会用哪个 `accountTag`
+     * （要等 reader 给），而首次升级的迁移诉求是「把所有攒下来的桶都收一遍」——
+     * 只清一个桶的话，凭据轮换出来的旧桶永远清不掉，文件就一直大。
+     *
+     * **失败绝不影响 open**：清理抛错只记一条 warn。这里抛出去会让
+     * `ensureOpen` 判成打开失败，整个存储被打成降级 —— 那比慢更糟。
+     * 删到一半也是安全的：清理幂等，下次启动继续。
+     */
+    private pruneAllLedgersOnOpen;
+    /** 取出属于该账本的全部记录。 */
+    private collectOwned;
+    /** 分批删除，每批之后让出一次事件循环。 */
+    private deleteInBatches;
     health(): Promise<StoreHealth>;
     /** 幂等关闭。**必须挂在 `ctx.effect` 的 disposer 上。** */
     close(): Promise<void>;

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

@@ -9,10 +9,35 @@
  */
 import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
 import { z } from 'zod';
+import { SNAPSHOT_KEEP_N, } from '../domain/balance.js';
 import { StorageError, describeError } from '../domain/errors.js';
 import { formatMoney, parseMoney } from '../domain/money.js';
 /** 域里的表名。 */
 export const SNAPSHOT_TABLE = 'snapshots';
+/**
+ * 修剪时每批删多少条，之后让出一次事件循环。
+ *
+ * **实现细节，不上端口**：领域层只调一次 `pruneByTag`，不需要知道分了几批。
+ * 取值只是「别让一批太大」的粗界，真实瓶颈是单布局下的整份重写次数，
+ * 所以调大调小不影响正确性，只影响同进程别的活被挤住多久。
+ */
+const PRUNE_BATCH_SIZE = 40;
+/**
+ * 单次修剪最多删多少条，**之后剩下的交给后续启动或写入路径**。
+ *
+ * **为什么需要上界**：`single` 布局下每次 `delete` 都要原子重写整份单元文件，
+ * 而「删掉一批」的开销随文件体积线性涨。首次升级时存量可能很大（本机实测 9000 条 /
+ * 3.8 MB），若一次性清空就是数千次整份重写，**会把宿主连同 Agent 一起卡死**
+ * —— 实测现象是侧栏无限转圈、Agent 停止响应，清空数据后立刻恢复。
+ *
+ * 这个数是**实现约束**不是领域策略：领域层只说「留几条」，「一次最多删多少」
+ * 属于「别把自己卡死」的工程判断，所以不上端口（与批次大小同理）。
+ *
+ * 取 500 的依据：配合 {@link PRUNE_BATCH_SIZE} 是 12.5 批，批次边界清晰；
+ * 收敛靠**多次启动叠加**而不是一次删完 —— 清到 20 条这个终态是幂等的，
+ * 每次启动删一批，未删完的下次继续。
+ */
+const PRUNE_MAX_PER_CALL = 500;
 const storedBalanceSchema = z.object({
     currency: z.string(),
     total: z.string(),
@@ -127,6 +152,10 @@ export class DomainCoreStore {
         this.handle = handle;
         this.table = handle.table(SNAPSHOT_TABLE);
         this.openError = undefined;
+        // 首次升级的一次性清理：必须在**任何读取之前**做，否则首次
+        // loadLatestSnapshot 仍要面对存量的大文件。等下一次抓取再清太晚 ——
+        // 那正是「保留策略只在稳态有效、首次升级要等两小时」那个盲区。
+        await this.pruneAllLedgersOnOpen(SNAPSHOT_KEEP_N);
     }
     /** 拿到可用表，或在降级状态下抛出可读错误。 */
     async requireTable() {
@@ -149,19 +178,128 @@ export class DomainCoreStore {
      *
      * **按 `accountTag` 过滤**：凭据轮换后 tag 会变，旧快照不得混用。
      * 用 `snapshotId`（单调可排序）决定新旧，不依赖 `fetchedAt`。
+     *
+     * **走 `entries()` 而不是 `keys()` + 逐键 `get()`**：后者是每条记录两次查找，
+     * 记录数涨上去（保留策略落地前实测过千条）时白费一大半；`entries()` 一次迭代给全。
      */
     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)
+        for (const [, record] of table.entries()) {
+            if (record.accountTag !== accountTag)
                 continue;
             if (newest === null || record.snapshotId > newest.snapshotId)
                 newest = record;
         }
         return newest === null ? null : fromStored(newest);
     }
+    /**
+     * 只保留该账本最近 `keepN` 条，删掉更旧的（跨账本不动）。
+     *
+     * **批间让出事件循环的理由是摊平写放大，不是防限流**：宿主 json 后端默认 `single`
+     * 布局，每次 `delete` 都要原子重写整份单元文件。删几十条若挤在同一个 tick 上，
+     * 会连带把同一进程里的取数与轮询一起拖住。所以内部**分批 + 每批之后让出一次** ——
+     * 批次大小与间隔属于实现细节，不上端口（领域层只调一次，不需要知道分了几批）。
+     *
+     * **单次最多删 {@link PRUNE_MAX_PER_CALL} 条**：超出部分留给后续启动或写入路径，
+     * 保证任何一次调用的耗时都有确定上界（理由见那个常量）。
+     *
+     * **零写入的幂等**：没超期时一条都不删、返回 0（超期判定先做完再动手）。
+     *
+     * @param accountTag - 要修剪的账本。
+     * @param keepN - 保留条数（新到旧）。
+     * @returns 本次**实际**删掉的条数（可能小于超期总数，因为有单次上限）。
+     */
+    async pruneByTag(accountTag, keepN) {
+        const table = await this.requireTable();
+        return this.pruneOwned(table, accountTag, keepN);
+    }
+    /**
+     * 修剪一个账本的内部实现（不重复 `requireTable` 的开表开销）。
+     */
+    async pruneOwned(table, accountTag, keepN) {
+        if (keepN < 0)
+            return 0;
+        const owned = this.collectOwned(table, accountTag);
+        if (owned.length <= keepN)
+            return 0;
+        // 先按 snapshotId 排好序再决定删哪些：留下的必然是「最新的 keepN 条」，
+        // 而刚写入的那条 id 单调最大，所以永远在保留集里。
+        const ordered = owned
+            .slice()
+            .sort((a, b) => (a.snapshotId < b.snapshotId ? -1 : a.snapshotId > b.snapshotId ? 1 : 0));
+        const doomed = ordered.slice(0, ordered.length - keepN).slice(0, PRUNE_MAX_PER_CALL);
+        await this.deleteInBatches(table, doomed);
+        return doomed.length;
+    }
+    /**
+     * 启动时的一次性清理：把**所有**账本桶各修剪一次。
+     *
+     * 为什么扫全表而不是只清「当前那个账本」：启动这一刻还不知道会用哪个 `accountTag`
+     * （要等 reader 给），而首次升级的迁移诉求是「把所有攒下来的桶都收一遍」——
+     * 只清一个桶的话，凭据轮换出来的旧桶永远清不掉，文件就一直大。
+     *
+     * **失败绝不影响 open**：清理抛错只记一条 warn。这里抛出去会让
+     * `ensureOpen` 判成打开失败，整个存储被打成降级 —— 那比慢更糟。
+     * 删到一半也是安全的：清理幂等，下次启动继续。
+     */
+    async pruneAllLedgersOnOpen(keepN) {
+        const table = this.table;
+        if (table === null)
+            return;
+        try {
+            const buckets = new Map();
+            for (const [, record] of table.entries()) {
+                const bucket = buckets.get(record.accountTag);
+                if (bucket === undefined)
+                    buckets.set(record.accountTag, [record]);
+                else
+                    bucket.push(record);
+            }
+            let removed = 0;
+            let remaining = 0;
+            for (const accountTag of buckets.keys()) {
+                removed += await this.pruneOwned(table, accountTag, keepN);
+            }
+            for (const bucket of buckets.values())
+                remaining += Math.min(bucket.length, keepN);
+            if (removed > 0) {
+                // 进度日志：删了多少、之后大约还剩多少（每次启动还会再删一批，直到收敛）。
+                // 没有它，使用者只会看到「数据怎么还在变多」，无从判断清理是否在推进。
+                this.options.logger?.debug('ds-balance: pruned stored snapshots on open', {
+                    removed,
+                    remainingApprox: remaining,
+                    buckets: buckets.size,
+                    keepN,
+                });
+            }
+        }
+        catch (error) {
+            // 刻意只记一条 warn：清理是尽力而为，不该把存储打成降级。
+            this.options.logger?.warn('ds-balance: startup snapshot prune failed, continuing', {
+                error: describeError(error),
+            });
+        }
+    }
+    /** 取出属于该账本的全部记录。 */
+    collectOwned(table, accountTag) {
+        const owned = [];
+        for (const [, record] of table.entries()) {
+            if (record.accountTag === accountTag)
+                owned.push(record);
+        }
+        return owned;
+    }
+    /** 分批删除，每批之后让出一次事件循环。 */
+    async deleteInBatches(table, doomed) {
+        for (let offset = 0; offset < doomed.length; offset += PRUNE_BATCH_SIZE) {
+            const batch = doomed.slice(offset, offset + PRUNE_BATCH_SIZE);
+            for (const record of batch)
+                await table.delete(record.snapshotId);
+            // 让出一次事件循环：把同 tick 的连续原子重写摊开，别挤住同进程的别的活。
+            await new Promise((resolve) => setImmediate(resolve));
+        }
+    }
     async health() {
         if (this.closed)
             return { ok: false, detail: 'closed' };

package/lib/domain/balance.d.ts

@@ -46,6 +46,26 @@ export interface BalanceSnapshot {
     /** 原始响应，审计用。 */
     raw: unknown;
 }
+/**
+ * 每个账本保留多少条快照。**历史保留深度，不是功能开关。**
+ *
+ * **为什么住在 domain**：写入路径（`SourceLedger.persist`）与启动清理
+ * （`DomainCoreStore.initialize`）都要读它，而 adapters 与 services 互相不能依赖 ——
+ * `domain/` 是两层共同的下游，是唯一能放这个常量的地方。
+ * （最初它住在 `balance-source.ts` 顶部，理由是「紧挨唯一调用点」；启动清理加入后
+ * 调用点变成两个，那条理由就不再成立。）
+ *
+ * - 当前**没有任何功能读第二条以后的记录**：唯一读点是 `loadLatestSnapshot` 取最新一条，
+ *   仓内没有 `listSnapshots`，也没有历史端点（`docs/ARCHITECTURE.md` 的阶段边界
+ *   明写不做图表）。所以这个数**不是**为功能服务的，不要因为「用不到」就调到 1。
+ * - 它真正的作用是**故障回退余量**：最新那条写失败、写坏、或落盘途中崩了时还能退到上一条，
+ *   覆盖连续两次失败就要 ≥ 3。
+ * - **刻意不进配置面**：配置字段用户看得见、改得动，而这个数没有用户可感知的语义 ——
+ *   改小它用户看不出界面变化，只会在某天丢快照时才后悔。给一个看不出区别的旋钮比不给更糟。
+ *
+ * 量级：一条快照约 0.9 KB，20 条约 18 KB —— 余量与存储成本之间没有取舍压力。
+ */
+export declare const SNAPSHOT_KEEP_N = 20;
 /** 一个币种的预警 / 告急阈值。 */
 export interface ThresholdPair {
     warn: Units;

package/lib/domain/balance.js

@@ -4,5 +4,24 @@
  * 这里定义的是**契约形状**：金额一律 `bigint` 最小单位，序列化时才变字符串。
  * @module dsh-ds-balance/domain/balance
  */
-export {};
+/**
+ * 每个账本保留多少条快照。**历史保留深度，不是功能开关。**
+ *
+ * **为什么住在 domain**：写入路径（`SourceLedger.persist`）与启动清理
+ * （`DomainCoreStore.initialize`）都要读它，而 adapters 与 services 互相不能依赖 ——
+ * `domain/` 是两层共同的下游，是唯一能放这个常量的地方。
+ * （最初它住在 `balance-source.ts` 顶部，理由是「紧挨唯一调用点」；启动清理加入后
+ * 调用点变成两个，那条理由就不再成立。）
+ *
+ * - 当前**没有任何功能读第二条以后的记录**：唯一读点是 `loadLatestSnapshot` 取最新一条，
+ *   仓内没有 `listSnapshots`，也没有历史端点（`docs/ARCHITECTURE.md` 的阶段边界
+ *   明写不做图表）。所以这个数**不是**为功能服务的，不要因为「用不到」就调到 1。
+ * - 它真正的作用是**故障回退余量**：最新那条写失败、写坏、或落盘途中崩了时还能退到上一条，
+ *   覆盖连续两次失败就要 ≥ 3。
+ * - **刻意不进配置面**：配置字段用户看得见、改得动，而这个数没有用户可感知的语义 ——
+ *   改小它用户看不出界面变化，只会在某天丢快照时才后悔。给一个看不出区别的旋钮比不给更糟。
+ *
+ * 量级：一条快照约 0.9 KB，20 条约 18 KB —— 余量与存储成本之间没有取舍压力。
+ */
+export const SNAPSHOT_KEEP_N = 20;
 //# sourceMappingURL=balance.js.map

package/lib/index.js

@@ -313,7 +313,7 @@ export async function apply(ctx, refs) {
             'deepseek-account',
             new SourceLedger({
                 source: 'deepseek-account',
-                reader: accountReader({ account: () => account.current(), salt }),
+                reader: accountReader({ account: () => account.current(), salt, logger }),
                 store,
                 config: configService,
                 clock: systemClock,

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

@@ -20,6 +20,21 @@ export interface CoreStore {
      * @returns 最近一条快照，或 `null` 表示该账本还没有记录。
      */
     loadLatestSnapshot(accountTag: string): Promise<BalanceSnapshot | null>;
+    /**
+     * 只保留该账本最近 `keepN` 条快照，删掉更旧的。
+     *
+     * 与 {@link loadLatestSnapshot} 同构：两个都是 **tag 作用域**的操作 ——
+     * 「按账本分桶、只动自己那个桶」这条语义由本端口统一承担，调用方不必知道记录怎么组织。
+     *
+     * **`keepN` 由调用方（领域层）传入**：端口只执行「留几条」，不决定该留几条 ——
+     * 那是领域层的策略。端口也不暴露实现步骤（分几批删、批间隔多久、怎么排序）。
+     *
+     * **只动 `accountTag` 这一个桶**：别的账本一条都不许碰。
+     * @param accountTag - 要修剪的账本。
+     * @param keepN - 该账本要保留的条数（新到旧）。
+     * @returns 实际删掉的条数；`0` 表示本来就没超期（**必须是零写入的幂等操作**）。
+     */
+    pruneByTag(accountTag: string, keepN: number): Promise<number>;
     /** 端口自检。 */
     health(): Promise<StoreHealth>;
     /** 释放存储句柄。**必须由调用方在 `ctx.effect` 的 disposer 里调用。** */

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

@@ -23,7 +23,13 @@ import type { ConfigService } from './config-service.js';
 export interface SourceReader {
     /** 这条路的凭据此刻可用吗。 */
     available(): Promise<boolean>;
-    /** 这次快照的账本标识；凭据拿不到时抛错（由调用方吸收）。 */
+    /**
+     * 这次快照的账本标识。
+     *
+     * **凭据 / 身份拿不到时抛错，由调用方吸收** —— 不能退化成某个占位标识：
+     * 账本键一旦落成别的值，那条快照就再也读不回来（`restore()` 会静默跳过，
+     * 下一轮拿到真标识后自愈）。
+     */
     tag(): Promise<string>;
     /** 抓一次余额，连账本标识一起给。 */
     read(): Promise<{
@@ -93,6 +99,8 @@ export declare class SourceLedger {
     private inflight;
     /** 落盘失败只报一次，避免每轮刷新都刷屏。 */
     private persistWarned;
+    /** 修剪失败只报一次：与落盘分开记，两者是不同的降级事实。 */
+    private retentionWarned;
     constructor(options: SourceLedgerOptions);
     /** 这条路的 id。 */
     source(): BalanceSource;
@@ -145,9 +153,14 @@ export declare class SourceLedger {
     /** 跑一次真实抓取。**所有异常都在这里被吸收。** */
     private fetchOnce;
     /**
-     * 把快照落盘。
+     * 把快照落盘，并按账本执行保留策略。
+     *
+     * **两件事分别记账**：落盘失败与修剪失败**不能并进同一个 catch** ——
+     * 写已经成功时若把它报成「snapshot not persisted」，日志就在说谎，
+     * 而排查存储问题的人正是按这条日志判断写没写成功的。
      *
-     * **失败只记一次 warn，不往上抛**：存储层降级不该让整个余额功能不可用。
+     * 落盘失败只记一次 warn（每轮刷新都会重来，不限流就刷屏）；
+     * 修剪失败同样只记一次 —— 它让文件继续变大，是需要被看见的降级，但不该淹没主流程。
      * @param snapshot - 刚归一化出来的快照。
      */
     private persist;

package/lib/services/balance-source.js

@@ -8,6 +8,7 @@
  * @module dsh-ds-balance/services/balance-source
  */
 import { classify, describeError, parseRetryAfter, } from '../domain/errors.js';
+import { SNAPSHOT_KEEP_N } from '../domain/balance.js';
 import { normalize } from '../domain/normalize.js';
 import { pickBalance } from '../domain/select.js';
 import { severityOf, thresholdsFor } from '../domain/severity.js';
@@ -28,6 +29,8 @@ export class SourceLedger {
     inflight = null;
     /** 落盘失败只报一次，避免每轮刷新都刷屏。 */
     persistWarned = false;
+    /** 修剪失败只报一次：与落盘分开记，两者是不同的降级事实。 */
+    retentionWarned = false;
     constructor(options) {
         this.options = options;
         this.metrics = options.metrics ?? noopMetrics;
@@ -85,7 +88,11 @@ export class SourceLedger {
             this.publishGauge();
         }
         catch (error) {
-            this.options.logger?.debug('ds-balance: no snapshot restored', {
+            // **warn 而非 debug**：这条账本没能从存储恢复，是一条降级事实 ——
+            // 记在 debug 级别等于藏起来，使用者只会看到界面空着而无从判断原因。
+            // 仍**不设 state / errorCode**：恢复失败后前端自己会 getView() 走正常抓取，
+            // 在这里塞错误态会让「本来就没有快照」与「存储坏了」混成同一个处境。
+            this.options.logger?.warn('ds-balance: could not restore snapshot for this ledger', {
                 source: this.options.source,
                 error: describeError(error),
             });
@@ -183,9 +190,14 @@ export class SourceLedger {
         }
     }
     /**
-     * 把快照落盘。
+     * 把快照落盘，并按账本执行保留策略。
      *
-     * **失败只记一次 warn，不往上抛**：存储层降级不该让整个余额功能不可用。
+     * **两件事分别记账**：落盘失败与修剪失败**不能并进同一个 catch** ——
+     * 写已经成功时若把它报成「snapshot not persisted」，日志就在说谎，
+     * 而排查存储问题的人正是按这条日志判断写没写成功的。
+     *
+     * 落盘失败只记一次 warn（每轮刷新都会重来，不限流就刷屏）；
+     * 修剪失败同样只记一次 —— 它让文件继续变大，是需要被看见的降级，但不该淹没主流程。
      * @param snapshot - 刚归一化出来的快照。
      */
     async persist(snapshot) {
@@ -193,10 +205,24 @@ export class SourceLedger {
             await this.options.store.saveSnapshot(snapshot);
         }
         catch (error) {
-            if (this.persistWarned)
+            if (!this.persistWarned) {
+                this.persistWarned = true;
+                this.options.logger?.warn('ds-balance: snapshot not persisted, continuing in memory', {
+                    source: this.options.source,
+                    error: describeError(error),
+                });
+            }
+            // 落盘都没成功，谈不上修剪：这一轮不删任何东西。
+            return;
+        }
+        try {
+            await this.options.store.pruneByTag(snapshot.accountTag, SNAPSHOT_KEEP_N);
+        }
+        catch (error) {
+            if (this.retentionWarned)
                 return;
-            this.persistWarned = true;
-            this.options.logger?.warn('ds-balance: snapshot not persisted, continuing in memory', {
+            this.retentionWarned = true;
+            this.options.logger?.warn('ds-balance: snapshot retention failed, ledger will keep growing', {
                 source: this.options.source,
                 error: describeError(error),
             });

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

@@ -7,6 +7,7 @@
  */
 import type { AccountSource } from '../ports/account.js';
 import type { DeepSeekClient } from '../ports/deepseek-client.js';
+import type { Logger } from '../ports/logger.js';
 import type { SourceReader } from './balance-source.js';
 import type { ConfigService } from './config-service.js';
 import type { KeyResolver } from './key-resolver.js';
@@ -22,5 +23,6 @@ export declare function accountReader(options: {
     /** 取当前端口实现；服务可能晚到，所以这里必须是函数而不是实例。 */
     account: () => AccountSource | undefined;
     salt: string;
+    logger?: Logger;
 }): SourceReader;
 //# sourceMappingURL=source-readers.d.ts.map

package/lib/services/source-readers.js

@@ -40,7 +40,7 @@ export function keyReader(options) {
 }
 /** 账号那条路：登录态 → 钱包查询 → 投影成官方余额端点同一个形状。 */
 export function accountReader(options) {
-    const { account, salt } = options;
+    const { account, salt, logger } = options;
     const require = () => {
         const current = account();
         if (current === undefined)
@@ -51,10 +51,20 @@ export function accountReader(options) {
      * 账号账本的派生输入。
      *
      * 用 `account:` 前缀把两个键空间分开：账号 id 与明文密钥因此不可能撞到同一个账本。
-     * 宿主本进程还没读过 profile 时 id 拿不到，退回 `unknown` —— 代价是那种情况下换账号不换账本，
-     * 由下一轮抓取修正（见决策记录的「已知代价」）。
+     *
+     * **拿不到账号 id 就抛错，不落盘**（兑现 `SourceReader.tag` 的契约）：
+     * 宿主本进程还没读过 profile 时 id 会给不出值，而账本键一旦落成别的值，
+     * 那条快照就再也读不回来 —— 「重启后按同一个键读回自己那份快照」这条承诺会在那一刻落空。
+     * 抛错比换一个占位键诚实：`restore()` 会静默跳过，下一轮拿到真 id 后自然自愈。
      */
-    const tagOf = async () => computeAccountTag(salt, `account:${(await require().accountId()) ?? 'unknown'}`);
+    const tagOf = async () => {
+        const id = await require().accountId();
+        if (id === null) {
+            logger?.debug('ds-balance: account identity unavailable, skipping this snapshot');
+            throw new NoKeyError('no credential: account identity is unavailable');
+        }
+        return computeAccountTag(salt, `account:${id}`);
+    };
     return {
         async available() {
             const current = account();

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ds-balance",
-  "version": "2.2.0",
+  "version": "2.3.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": [