dsh-ds-balance 2.2.0 → 2.3.1

package/README.md

@@ -101,7 +101,7 @@
 
 ### 前置
 
-- **DSH**：版本范围以 [package.json](package.json) 的声明为准，本插件跟的是宿主当前那条 **RC 线**（dist-tag 是 `next`）。
+- **DSH**：版本范围以 [package.json](package.json) 的 `engines.dsh` 为唯一真源（与全部 `@deepseek-ai/dsh-*` 声明逐字相同），本插件跟的是宿主当前那条 **RC 线**（dist-tag 是 `next`）。声明面同时承诺**两族**（RC 族与仍可用的旧 RC 族，用 `||` 显式枚举 —— npm 只在同一 `major.minor.patch` 的预发布之间匹配，单区间罩不住两族），具体值一律现查，本文件不抄那个会漂的值。
 - **Node**：`>= 20`（同一处声明）。
 
 装宿主时**要显式点名版本线**：`@deepseek-ai/dsh` 的 `alpha` 与 `latest` 都**不是**我们声明的那条线 —— 按默认方式装会落在声明范围之外。
@@ -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)
@@ -150,8 +153,9 @@ dsh plugin --profile web add "$PWD"
   浏览器半边会整个不渲染 —— 圆环与浮层也一起消失）。插件不查宿主版本号，而是**当场探测那个能力**；
   拿不到时浮层里会多一行英文提示，说明配置界面为什么不可用、该往哪儿升级。
   技术细节见 [配置表单的能力探测](docs/ARCHITECTURE.md)。
-- **兼容性不是推断出来的**：每周由 [compat.yml](.github/workflows/compat.yml) 在 `next`（RC 线）上
-  换包实跑一遍现有测试，另有一步单独判声明面罩不罩得住；红了会开或更新一条固定标题的跟踪 issue。
+- **兼容性不是推断出来的**：每周由 [compat.yml](.github/workflows/compat.yml) 在 `next`（RC 线，承诺线）与
+  声明面里的**第二族**（旧 RC 族，记录线）上换包实跑一遍现有测试，另有一步单独判声明面罩不罩得住；
+  承诺线红了会开或更新一条固定标题的跟踪 issue。
   当前结论与红了怎么办见 [兼容性](docs/PUBLISHING.md#兼容性)。
 
 ## 配置

package/README_en.md

@@ -103,7 +103,7 @@ The division of labour is fixed: **the ring answers "roughly how much is left",
 
 ### Requirements
 
-- **DSH**: the range is whatever [package.json](package.json) declares; this plugin follows the host's current **RC line** (the dist-tag is `next`).
+- **DSH**: the range lives in `engines.dsh` in [package.json](package.json) — the single source of truth, character-for-character identical to every `@deepseek-ai/dsh-*` entry. This plugin follows the host's current **RC line** (the dist-tag is `next`). The declared surface commits to **two** prerelease families (the RC family and the still-usable older one, enumerated with `||` — npm only matches prereleases within the same `major.minor.patch`, so a single range cannot cover two families); the exact value drifts, so look it up rather than trusting this file.
 - **Node**: `>= 20` (declared in the same place).
 
 Install the host by **naming the version line explicitly**: neither `alpha` nor `latest` of `@deepseek-ai/dsh` is the line we declare — a default install lands outside the declared range.
@@ -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

@@ -1,13 +1,13 @@
 /**
  * 用 dsh 官方存储接缝实现 {@link CoreStore}。
  *
- * 关键约束（见 docs/backend-architecture.md §10）：
+ * 关键约束（见 docs/BACKEND-CONTRACTS.md §10）：
  * - `open` 每进程只能一次，重名抛 `already-open`；
  * - **`close()` 必须由调用方在 `ctx.effect` 的 disposer 里调用**，否则热重挂会锁死；
  * - 打开失败要**降级**而不是抛出去 —— 未观察的 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

@@ -1,7 +1,7 @@
 /**
  * 用 dsh 官方存储接缝实现 {@link CoreStore}。
  *
- * 关键约束（见 docs/backend-architecture.md §10）：
+ * 关键约束（见 docs/BACKEND-CONTRACTS.md §10）：
  * - `open` 每进程只能一次，重名抛 `already-open`；
  * - **`close()` 必须由调用方在 `ctx.effect` 的 disposer 里调用**，否则热重挂会锁死；
  * - 打开失败要**降级**而不是抛出去 —— 未观察的 rejection 曾把宿主整个拖下水。
@@ -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/adapters/salt-file.d.ts

@@ -1,7 +1,7 @@
 /**
  * 服务端盐的读写。
  *
- * `accountTag` 由它派生，所以**它丢了账本就会孤立**：见 docs/backend-architecture.md §19 第 5 条。
+ * `accountTag` 由它派生，所以**它丢了账本就会孤立**：见 docs/BACKEND-CONTRACTS.md §19 第 5 条。
  * 文件权限 0600；路径由组装点用 `@deepseek-ai/dsh-home-paths` 的 `dshHomePath()` 拼出来。
  * @module dsh-ds-balance/adapters/salt-file
  */

package/lib/adapters/salt-file.js

@@ -1,7 +1,7 @@
 /**
  * 服务端盐的读写。
  *
- * `accountTag` 由它派生，所以**它丢了账本就会孤立**：见 docs/backend-architecture.md §19 第 5 条。
+ * `accountTag` 由它派生，所以**它丢了账本就会孤立**：见 docs/BACKEND-CONTRACTS.md §19 第 5 条。
  * 文件权限 0600；路径由组装点用 `@deepseek-ai/dsh-home-paths` 的 `dshHomePath()` 拼出来。
  * @module dsh-ds-balance/adapters/salt-file
  */

package/lib/config.d.ts

@@ -1,7 +1,7 @@
 /**
  * 插件配置：schemastery schema、常量与派生值。
  *
- * 字段名与 [UI 侧契约与移交](../docs/ui-handoff.md) 第六节逐字一致，共 **11** 个。
+ * 字段名与 [UI 侧契约与移交](../docs/UI-HANDOFF.md) 第六节逐字一致，共 **11** 个。
  * `timeoutMs` **不在 schema 里**：它是常量加环境变量覆盖，UI 不暴露。
  * @module dsh-ds-balance/config
  */

package/lib/config.js

@@ -1,7 +1,7 @@
 /**
  * 插件配置：schemastery schema、常量与派生值。
  *
- * 字段名与 [UI 侧契约与移交](../docs/ui-handoff.md) 第六节逐字一致，共 **11** 个。
+ * 字段名与 [UI 侧契约与移交](../docs/UI-HANDOFF.md) 第六节逐字一致，共 **11** 个。
  * `timeoutMs` **不在 schema 里**：它是常量加环境变量覆盖，UI 不暴露。
  * @module dsh-ds-balance/config
  */

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/http/handlers.d.ts

@@ -3,7 +3,7 @@
  *
  * 依赖全部构造注入、**不碰 `ctx`** —— 因此它能脱离宿主直接测。
  *
- * 铁律（见 docs/backend-architecture.md §19 第 3、4 条）：
+ * 铁律（见 docs/BACKEND-CONTRACTS.md §19 第 3、4 条）：
  * - **任何 handler 都不许把异常抛出去**。抛出去会被宿主包成 500，前端就拿不到
  *   `error` 结构了。余额端点的业务错误一律走 `200 + state: error`。
  * - **每次请求现读配置**，不许在闭包里捕获旧值。

package/lib/http/handlers.js

@@ -3,7 +3,7 @@
  *
  * 依赖全部构造注入、**不碰 `ctx`** —— 因此它能脱离宿主直接测。
  *
- * 铁律（见 docs/backend-architecture.md §19 第 3、4 条）：
+ * 铁律（见 docs/BACKEND-CONTRACTS.md §19 第 3、4 条）：
  * - **任何 handler 都不许把异常抛出去**。抛出去会被宿主包成 500，前端就拿不到
  *   `error` 结构了。余额端点的业务错误一律走 `200 + state: error`。
  * - **每次请求现读配置**，不许在闭包里捕获旧值。

package/lib/http/routes.d.ts

@@ -4,7 +4,7 @@
  * 三层职责分得很开：本文件只管**注册**，`handlers.ts` 管**怎么做**，
  * `wire.ts` 管**长什么样**。注册需要 `ctx`，所以只有本文件碰宿主。
  *
- * 契约要点（docs/backend-architecture.md §3.3 / §8.2）：
+ * 契约要点（docs/BACKEND-CONTRACTS.md §3.3 / §8.2）：
  * - `path` 写死精确值、不带尾随斜杠（实现是 Map 精确键匹配）；
  * - `requestBody` 必填；
  * - 物理载体**已先做完信任与浏览器鉴权**，handler 不必再判一次。

package/lib/http/routes.js

@@ -4,7 +4,7 @@
  * 三层职责分得很开：本文件只管**注册**，`handlers.ts` 管**怎么做**，
  * `wire.ts` 管**长什么样**。注册需要 `ctx`，所以只有本文件碰宿主。
  *
- * 契约要点（docs/backend-architecture.md §3.3 / §8.2）：
+ * 契约要点（docs/BACKEND-CONTRACTS.md §3.3 / §8.2）：
  * - `path` 写死精确值、不带尾随斜杠（实现是 Map 精确键匹配）；
  * - `requestBody` 必填；
  * - 物理载体**已先做完信任与浏览器鉴权**，handler 不必再判一次。

package/lib/http/wire.d.ts

@@ -1,7 +1,7 @@
 /**
  * 线上形状与序列化。
  *
- * 契约见 docs/backend-architecture.md §8：**金额一律八位小数字符串**，
+ * 契约见 docs/BACKEND-CONTRACTS.md §8：**金额一律八位小数字符串**，
  * `bigint` 最小单位只活在进程内。本模块是纯函数，不碰 `ctx`、不发请求。
  * @module dsh-ds-balance/http/wire
  */

package/lib/http/wire.js

@@ -1,7 +1,7 @@
 /**
  * 线上形状与序列化。
  *
- * 契约见 docs/backend-architecture.md §8：**金额一律八位小数字符串**，
+ * 契约见 docs/BACKEND-CONTRACTS.md §8：**金额一律八位小数字符串**，
  * `bigint` 最小单位只活在进程内。本模块是纯函数，不碰 `ctx`、不发请求。
  * @module dsh-ds-balance/http/wire
  */

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

@@ -1,5 +1,5 @@
 /**
- * 快照存储端口。实现走 dsh 官方存储接缝，见 docs/backend-architecture.md §10。
+ * 快照存储端口。实现走 dsh 官方存储接缝，见 docs/BACKEND-CONTRACTS.md §10。
  * @module dsh-ds-balance/ports/core-store
  */
 import type { BalanceSnapshot } from '../domain/balance.js';
@@ -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/ports/core-store.js

@@ -1,5 +1,5 @@
 /**
- * 快照存储端口。实现走 dsh 官方存储接缝，见 docs/backend-architecture.md §10。
+ * 快照存储端口。实现走 dsh 官方存储接缝，见 docs/BACKEND-CONTRACTS.md §10。
  * @module dsh-ds-balance/ports/core-store
  */
 export {};

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.1";
 //# 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.1';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ds-balance",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "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": [
@@ -47,7 +47,7 @@
     "LICENSE"
   ],
   "engines": {
-    "dsh": ">=0.2.0-rc.1",
+    "dsh": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
     "node": ">=20"
   },
   "dsh": {
@@ -75,16 +75,16 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.3",
-    "@deepseek-ai/dsh-client-connection": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-locale": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-primitives": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-credentials": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-deepseek-account-platform": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-home-paths": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-settings": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-storage-domain": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-connection": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-client-ui-primitives": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-credentials": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-deepseek-account-platform": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-home-paths": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-settings": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-storage-domain": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
     "@deepseek-ai/schemastery": "^3.18.3",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
@@ -92,19 +92,19 @@
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.3",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.4",
-    "@deepseek-ai/dsh-client-connection": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-locale": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-plugin-manager": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-primitives": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-renderer": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-sidebar": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-slots": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-credentials": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-deepseek-account-platform": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-home-paths": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-settings": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-storage-domain": ">=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-connection": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-client-ui-primitives": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-client-ui-renderer": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-client-ui-settings": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-client-ui-sidebar": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-credentials": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-deepseek-account-platform": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-home-paths": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-settings": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
+    "@deepseek-ai/dsh-storage-domain": ">=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0",
     "@deepseek-ai/schemastery": "^3.18.3",
     "@eslint/js": "^10.0.1",
     "@types/node": "^20.0.0",