dsh-ds-balance 2.1.3 → 2.3.0

package/README.md

@@ -29,7 +29,7 @@
 ---
 
 > [!NOTE]
-> **余额读自 DeepSeek 官方 `GET /user/balance`**，不是估算。凭据只经 DSH 的凭据通道解析：API Key 不会出现在设置文件里，也不会返回给界面。
+> **余额读自 DeepSeek 官方接口**，不是估算。凭据只经 DSH 的凭据通道解析：API Key 不会出现在设置文件里，也不会返回给界面。
 
 余额要有地方看，但不该占地方。左边栏底部一个常驻的状态环，点开是三段金额与数据新鲜度；要改配置，进侧边栏**插件（Plugins）**页里本插件的详情页。
 
@@ -39,12 +39,40 @@
   <em>常驻<strong>左边栏底部</strong>，与「使用统计」「设置」并排；点开是余额、赠送 / 充值拆分与数据新鲜度。</em>
 </p>
 
+## 一眼看懂那个环
+
+那个环是「现在是什么情况」，一眼能分出五种，各自对应你该做的事：
+
+| 你看到 | 意思 | 你该做什么 |
+|---|---|---|
+| 彩环 + 一段弧 | 有余额，颜色就是多还是少 | **看数字** |
+| 灰环 + 一段缺口在转 | 正在取，还没结果 | **等** |
+| 灰环 + 中间一个 **＋** | 没接入官方 | **去配置**（填 API Key 或登录账号） |
+| 灰色空环 | 连上了，账户就是没余额 | **不用管** |
+| 红环 + 中间一个 **叉** | 这里没有可用的数字 | **等、检查，或去查账户** |
+
+**鼠标停上去，它会告诉你这一格现在什么意思**（收起态那 56px 轨道、展开态带名字的条目，
+停上去显示的是同一句话）：
+
+- **数字可信时**（正常 / 偏低 / 告急）—— 直接显示**金额**；
+- **其余情况** —— 显示这个处境自己的话：「正在获取」「读不到余额」「服务异常」
+  「尚未配置凭据」「账户不可用」「数据已过期」「暂无余额」。
+
+**账户停用**与**数据过期**虽然手里有数字，也**不**显示那个数字：
+停用的账户、过期的快照，报出来的数只会误导（「我有 ¥0」/「我有 ¥110」）。
+环已经把问题画出来了（红叉 / 旧色），悬停该做的是解释问题。
+
+两种「看不到」分得开：**没接入**提示你去配凭据；**接入了但读不到**说「读不到余额」
+（不写「暂时」—— 有些原因等一下就好，有些得你去改凭据，说「暂时」会把人劝去干等）。
+那个**叉**既表示「读不到」，也表示「读到了但这个账户不能用」——
+两者都是「这里没有可用的数字」，都要你去查。
+
 ## 界面一览
 
 | 界面 | 一句话 | 你会用它来 |
 |---|---|---|
-| 侧栏圆环 | 常驻左边栏底部的状态环 + 名称，**展开态悬浮条目就报出余额金额**，**环里填了多少 = 余额离该币种预警线还有多远** | 扫一眼就知道还剩多少、离预警线多远 |
-| 余额浮层 | 点条目展开：总额、赠送 / 充值拆分、数据新鲜度、手动刷新（带冷却）；**右上角图标跳到本插件的配置格**（宿主没有那条跨插件深链服务时退回 Plugins 列表，悬浮文字同步改口径） | 核对具体数字，以及数据是几分钟前的 |
+| 侧栏圆环 | 常驻左边栏底部的状态环 + 名称；**悬停（收起态与展开态一样）显示同一句话**：数字可信时显金额，否则显状态文案；**环里填了多少 = 余额离该币种预警线还有多远** | 扫一眼就知道还剩多少、离预警线多远 |
+| 余额浮层 | 点条目展开：总额、赠送 / 充值拆分、数据新鲜度、手动刷新（带冷却）；**右上角图标直达本插件的配置**（宿主版本不支持时退回 Plugins 列表，悬浮文字同步改口径） | 核对具体数字，以及数据是几分钟前的 |
 | 设置卡片 | 连接 / 展示 / 阈值 / 刷新四组，**默认四组全收起**，点组头逐组展开 | 换端点、换币种、调预警线、调节奏 |
 
 三种界面的分工是死的：**圆环回答「大概还剩多少」，浮层回答「具体是多少」，卡片回答「怎么算」。**
@@ -73,16 +101,16 @@
 
 ### 前置
 
-- **DSH**：版本范围以 [package.json](package.json) 的 `engines.dsh` 与 `peerDependencies` 为准，本插件跟的是宿主当前那条 alpha 线。
-- Node `>= 20`（同上，真源是 `engines.node`）。
+- **DSH**：版本范围以 [package.json](package.json) 的声明为准，本插件跟的是宿主当前那条 **RC 线**（dist-tag 是 `next`）。
+- **Node**：`>= 20`（同一处声明）。
 
-装宿主时**要显式点名版本线**：`@deepseek-ai/dsh` 的 `latest` 标签比本插件要求的那条线还旧 —— 按默认方式装会落在声明范围之外。
+装宿主时**要显式点名版本线**：`@deepseek-ai/dsh` 的 `alpha` 与 `latest` 都**不是**我们声明的那条线 —— 按默认方式装会落在声明范围之外。
 
 ```bash
-npm install -g @deepseek-ai/dsh@alpha     # 本插件承诺支持的线
+npm install -g @deepseek-ai/dsh@next      # 本插件承诺支持的线（RC 线；npm 上没有 rc 这个 tag）
 ```
 
-兼容性不是推断出来的：每周由 [compat.yml](.github/workflows/compat.yml) 在 `alpha` 与 `next` 两条线上换包实跑一遍现有测试，另有一步单独判声明面罩不罩得住；红了会开或更新一条固定标题的跟踪 issue。当前结论与红了怎么办见 [兼容性](docs/PUBLISHING.md#兼容性)，宿主版本的分水岭见[版本兼容](#版本兼容)。
+兼容性怎么保证、哪条线该跟，见[版本兼容](#版本兼容)。
 
 ### 从 npm 安装
 
@@ -104,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)
@@ -113,10 +144,18 @@ dsh plugin --profile web add "$PWD"
 
 ## 版本兼容
 
-- 配置界面注册在宿主的 `plugins.bundle.config` 槽，**key 逐字就是包名**：一个 bundle 一份配置，渲染在它自己的详情页里。**这个落点往返过一次**（bundle 槽 → 行槽 → bundle 槽），两次都不是版本问题，是 UX 选择：行槽要多点一次 Configure，而 bundle 槽的座位 props **永远不带 `form`** —— 表单由卡片自己向 `ctx.configForms.get(<本插件那一行的 Loader 条目 id>)` 取。下限的真源是 [package.json](package.json) 的 `engines.dsh`，现状现查 `node scripts/compat-swap.mjs check`。
-- 下限抬上去的原因**是设置接缝换了，不是槽**：客户端侧的作用域服务被删、宿主侧 `settings.register` 被删，两半改用新的 `configForms` 与 volatile 配置引用 —— **没有那两样东西，浏览器半边整个不渲染**（圆环与浮层也一起消失）。插件不查宿主版本号：它盯的是 `ctx.inject(['configForms'])` 在窗口内有没有回调（**不盯槽名** —— 两个候选槽在更早的宿主上也在座，槽在不在推不出拿不拿得到表单）；拿不到时**浮层里会多一行英文 `[WARN]`**，说明配置界面为什么不可用、该往哪儿升级。
-- 需要配置界面，就把宿主升到 `engines.dsh` 声明的那一版或更高：`npm install -g @deepseek-ai/dsh@alpha`。
-- 声明是**窄**的：下限是我们实测过的那一版，用 `>=` 而**不设上限** —— 既不承诺「以后都兼容」，也不会因为宿主多推一个预发布段就失效。为什么这么定见[兼容性](docs/PUBLISHING.md#兼容性)。
+- **需要哪一版宿主**：以 [package.json](package.json) 的声明为准，本插件跟的是宿主当前那条 **RC 线**。
+  需要配置界面，就把宿主升到那一版或更高：`npm install -g @deepseek-ai/dsh@next`。
+- **声明是「窄」的**：下限是我们实测过的那一版，用 `>=` 而**不设上限** —— 不承诺「以后都兼容」。
+  （它罩得住**同一 `major.minor.patch` 内**后续的预发布版本；宿主换一个补丁位再推预发布，
+  这条下限就罩不住了，届时要再抬一次。为什么见[兼容性](docs/PUBLISHING.md#兼容性)。）
+- **下限为什么抬上去**：不是换了界面位置，而是**设置接缝换过**（旧宿主上没有本插件依赖的那两样东西，
+  浏览器半边会整个不渲染 —— 圆环与浮层也一起消失）。插件不查宿主版本号，而是**当场探测那个能力**；
+  拿不到时浮层里会多一行英文提示，说明配置界面为什么不可用、该往哪儿升级。
+  技术细节见 [配置表单的能力探测](docs/ARCHITECTURE.md)。
+- **兼容性不是推断出来的**：每周由 [compat.yml](.github/workflows/compat.yml) 在 `next`（RC 线）上
+  换包实跑一遍现有测试，另有一步单独判声明面罩不罩得住；红了会开或更新一条固定标题的跟踪 issue。
+  当前结论与红了怎么办见 [兼容性](docs/PUBLISHING.md#兼容性)。
 
 ## 配置
 
@@ -131,9 +170,9 @@ dsh plugin --profile web add "$PWD"
 - **连接**：API 地址与凭据，两项都默认留空 —— 地址留空即用 DeepSeek 官方端点，凭据继承官方模型页那一份、只读不可改；
   二级「自定义设置」里只放凭据引用名。
 - **展示**：金额用哪种币种，或让它自动跟随账户。
-- **阈值**：每个币种两档提醒线（预警 / 告急）。同一币种内**告急必须严格低于预警**，相等也会被拒绝。
-  `POST /api/v1/config` 也按这条判，违反回 `422`；
-  但**手改配置文件写成的非法组合不会再报错** —— 宿主那一侧已经不再强制它，插件会在读到的那一刻把这一对**回落成默认值**并在日志里记一次。
+- **阈值**：每个币种两档提醒线（预警 / 告急）。同一币种内**告急必须严格低于预警**，相等也会被拒绝
+  （保存时就会拦下来）；但**手改配置文件写成的非法组合不会再报错** ——
+  插件读到的那一刻会把这一对**回落成默认值**并在日志里记一次。
 
 > **升级提示**：设置项存在插件那一行的配置里，键名跟着宿主升级变过一次，**旧值不会自动迁移** —— 升级后请照上表重填一次。
 - **刷新**：服务端刷新周期、界面轮询周期与手动刷新冷却。冷却从**刷完那一刻**起算，
@@ -145,7 +184,9 @@ dsh plugin --profile web add "$PWD"
 
 - 环里填多少 = 当前余额占该币种**预警线**的比例，100% 封顶；告急线不参与画环 —— 它已经决定了颜色。
 - 颜色只表达状态，与金额大小无关：正常、偏低、告急各一色；账户读不到时另画一个带叉号的环。
-- 没配阈值的币种退回按状态定性：正常与不可用画满环，偏低 3/4，告急 1/4，未知空环。
+- 没配阈值的币种退回按状态定性：**正常画满环，偏低 3/4，告急 1/4**。
+  （只有**有余额可看**的那一族画弧 —— 上面三档，加上「数据已过期」时的那份旧数字；
+  账户读不到、账户停用、没接入、账户没钱这些**都不画弧**，环靠颜色与中心记号说话。）
 - 为什么颜色不由金额算、阈值为什么只当刻度 → [数据流](docs/ARCHITECTURE.md#数据流)。
 
 ### 凭据
@@ -153,6 +194,18 @@ dsh plugin --profile web add "$PWD"
 密钥只经 DSH 的凭据通道解析，卡片里的 `API Key` 一栏默认继承官方模型页配好的那一份，且只读不可改。
 由启动环境（环境变量）提供时，字段只读，徽标写明来源。
 
+**余额有两条官方取数路，插件自己选**：模型页 / 环境变量配的 API Key 一条，**DSH 账号登录**一条
+（只登录、没配 Key 也能看到余额）。选择顺序是：
+
+- **当前会话在用的那条** —— 切会话、换模型都跟着换；
+- 读不到会话就按全局默认模型的路由；
+- 都判不出来时 **Key 优先、账号兜底**；
+- 两条都没有，才是「尚未配置凭据」。
+
+浮层标题右边那个括号就是这份数字的来源：`（API Key）` / `（账号登录）`。**显示哪个、刷新就刷哪个、标签也写哪个** —— 三者始终同一条。
+
+**这个插件只记官方的那一个数字**，所以首选那条读不到时会自动退到另一条官方路：只要账号或 API Key 有一个能用，就照常显示（哪怕是一份稍旧的快照）。**两条路都拿不到数字，才会提示** —— 那才是真的没接入官方。左栏那个环这时长什么样，见[一眼看懂那个环](#一眼看懂那个环)。
+
 **换了 key 多久生效，跟着 DSH 的层走 —— 本插件不额外追：**
 
 - **启动环境（环境变量）给的 key：改了要重启 DSH。** 进程的环境在它启动那一刻就定死了，之后再改外面那个变量，跑着的插件看不到。
@@ -165,8 +218,8 @@ dsh plugin --profile web add "$PWD"
 
 - **API Key 永不返回界面**：配置接口只回一个固定长度的掩码串，连末几位也不给。
 - 密钥不落日志、不落本插件的文件；设置文件里只有引用名，卡片可以安全截图或分享。
-- 余额快照存在 DSH 自己的数据目录里，按凭据派生出的账本标识分组 —— 换 key 自动开新账本，旧快照不会被混用。
-- 账本标识还要一个 `.salt` 文件（在 DSH 的 home 目录下）参与派生；**它丢了，旧快照就读不回来**。
+- 余额快照存在 DSH 自己的数据目录里，按凭据派生出的标识分组 —— **换 key 自动开新账本**，旧快照不会被混用。
+- 那份标识还要 DSH home 目录下一个随机盐文件参与派生；**它丢了，旧快照就读不回来**（不会串到别人账上）。
 - 只访问 `api.deepseek.com`，不代理、不转发其他流量。
 
 ## 许可

package/README_en.md

@@ -29,7 +29,7 @@
 ---
 
 > [!NOTE]
-> **The balance is read from the official `GET /user/balance`** — not estimated. The credential is resolved only through DSH's credential channel: the API key never lands in a settings file and is never returned to the UI.
+> **The balance is read from the official DeepSeek API** — not estimated. The credential is resolved only through DSH's credential channel: the API key never lands in a settings file and is never returned to the UI.
 
 The balance needs somewhere to live that does not take up room. A permanent status ring at the bottom of the sidebar; click it for the three amounts and the freshness of the data. Anything you want to configure lives on the plugin's details page under **Plugins → Installed**.
 
@@ -39,12 +39,42 @@ The balance needs somewhere to live that does not take up room. A permanent stat
   <em>A permanent fixture at the <strong>bottom of the sidebar</strong>, alongside Usage statistics and Settings; click it for the balance, the granted / topped-up split, and how fresh the data is.</em>
 </p>
 
+## The ring at a glance
+
+That ring is "what is going on right now" — five shapes, each with a different thing for you to do:
+
+| What you see | Meaning | What you do |
+|---|---|---|
+| Coloured ring + an arc | There is a balance; the colour is how much | **Read the number** |
+| Grey ring + a gap rotating | Fetching; no answer yet | **Wait** |
+| Grey ring + a **+** in the middle | Nothing connected | **Configure** (an API key, or sign in) |
+| Grey, empty ring | Connected, the account simply has no balance | **Nothing** |
+| Red ring + a **×** in the middle | No usable number here | **Wait, investigate, or check the account** |
+
+**Hover it and it tells you what this spot means right now** (the same sentence whether you hover the
+56px rail ring or the expanded entry with its label):
+
+- **When the number is trustworthy** (normal / low / critical) — it shows the **amount**;
+- **otherwise** — it shows that situation's own line: "Loading", "Balance unavailable",
+  "Service error", "No credential configured", "Account unavailable", "Data is stale", "No balance".
+
+**A suspended account and stale data hold a number too, and still do not show it**:
+a suspended account or an expired snapshot reporting a figure only misleads ("I have ¥0" /
+"I have ¥110"). The ring already draws the problem (red cross / old colour); hovering explains it.
+
+The two kinds of "nothing to show" are told apart as well: **not connected** asks you to configure
+a credential; **connected but unreadable** says "Balance unavailable".
+It deliberately does **not** say "temporarily" — some causes clear up on their own, others need you
+to fix a credential, and "temporarily" would send the second group away to wait for nothing.
+The **×** covers both "could not read it" and "read it, but this account cannot be used" —
+both mean "no usable number here", and both send you to investigate.
+
 ## Surface at a glance
 
 | Surface | One line | Use it for |
 |---|---|---|
-| Sidebar ring | A status ring plus label at the bottom of the sidebar; **in the expanded state, hovering the entry reports the balance amount**, and **how full it is = how far the balance is from that currency's warning line** | Seeing at a glance how much is left and how close it is to the warning line |
-| Balance popover | Click the entry: total, granted / topped-up split, data freshness, manual refresh (with cooldown); **an icon at its top right opens this plugin's configuration page** (on a host without that cross-plugin deep link it falls back to the Plugins list, and its tooltip says so) | Checking the exact figures, and how many minutes old they are |
+| Sidebar ring | A status ring plus label at the bottom of the sidebar; **hovering it (in either state) says what this spot means** — the amount when the number is trustworthy, otherwise the situation's own line; and **how full it is = how far the balance is from that currency's warning line** | Seeing at a glance how much is left and how close it is to the warning line |
+| Balance popover | Click the entry: total, granted / topped-up split, data freshness, manual refresh (with cooldown); **an icon at its top right opens this plugin's configuration page** (on a host that does not support it, it falls back to the Plugins list and its tooltip says so) | Checking the exact figures, and how many minutes old they are |
 | Settings card | Connection / Display / Thresholds / Refresh, **all collapsed by default**, expand a group from its header | Changing the endpoint, the currency, the warning lines, the cadence |
 
 The division of labour is fixed: **the ring answers "roughly how much is left", the popover answers "exactly how much", and the card answers "how is that computed".**
@@ -73,16 +103,16 @@ 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 under `engines.dsh` and `peerDependencies`; this plugin follows the alpha line the host is on.
-- Node `>= 20` (same source of truth: `engines.node`).
+- **DSH**: the range is whatever [package.json](package.json) declares; this plugin follows the host's current **RC line** (the dist-tag is `next`).
+- **Node**: `>= 20` (declared in the same place).
 
-Install the host by **naming the version line explicitly**: the `latest` tag of `@deepseek-ai/dsh` is older than the line this plugin requires — a default install lands outside the declared range.
+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.
 
 ```bash
-npm install -g @deepseek-ai/dsh@alpha     # the line this plugin promises to support
+npm install -g @deepseek-ai/dsh@next      # the line this plugin promises to support (the RC line; there is no `rc` tag on npm)
 ```
 
-Compatibility is measured, not inferred: every week [compat.yml](.github/workflows/compat.yml) swaps packages onto the `alpha` and `next` lines and reruns the existing tests, and one separate job judges whether the declared ranges still cover the line; a red patrol opens or updates a tracking issue with a fixed title. The current verdict, and what to do when it goes red, are in [Compatibility](docs/PUBLISHING.md#兼容性); the Host-version watershed is in [Version compatibility](#version-compatibility).
+Compatibility is measured, not inferred: every week [compat.yml](.github/workflows/compat.yml) swaps packages onto the `next` (RC) line and reruns the existing tests, and one separate job judges whether the declared ranges still cover the line; a red patrol opens or updates a tracking issue with a fixed title. The current verdict, and what to do when it goes red, are in [Compatibility](docs/PUBLISHING.md#兼容性); the Host-version watershed is in [Version compatibility](#version-compatibility).
 
 ### From npm
 
@@ -104,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)
@@ -113,10 +147,21 @@ The repository carries the GitHub topic [`dsh-plugin`](https://github.com/topics
 
 ## Version compatibility
 
-- The configuration UI registers into the Host's `plugins.bundle.config` slot, **keyed literally by the package name**: one bundle, one configuration, rendered on that bundle's own details page. **That landing spot travelled once** (bundle slot → row slot → bundle slot) and neither move was about Host versions — it is a UX choice: the row slot costs one extra Configure click, while the bundle slot's owner props **never carry a `form`** — the card fetches it itself through `ctx.configForms.get(<the Loader entry id of this plugin's row>)`. The floor's single source is `engines.dsh` in [package.json](package.json); check the current lines with `node scripts/compat-swap.mjs check`.
-- The floor moved **because the settings seam changed, not because of the slot**: the client-side scope service was removed, the Host-side `settings.register` was removed, and both halves moved to the new `configForms` service and volatile config references — **without those two the whole client half never renders** (the ring and the popover go with it). The plugin never reads a Host version: it watches whether `ctx.inject(['configForms'])` calls back within its window (**never the slot name** — both candidate slots are present on earlier Hosts too, and a slot being there says nothing about getting a form). When it never does, **the popover carries one extra English `[WARN]` line** saying why the configuration page is unavailable and where to upgrade.
-- To get the configuration page, upgrade the Host to the version `engines.dsh` declares or higher: `npm install -g @deepseek-ai/dsh@alpha`.
-- The declaration is **narrow**: the floor is the version we actually tested, written as `>=` with **no ceiling** — it claims neither "everything in the future counts" nor anything earlier. Why it is written that way is in [Compatibility](docs/PUBLISHING.md#兼容性).
+- **Which Host version is required**: whatever [package.json](package.json) declares; this plugin follows the host's current **RC line**.
+  To get the configuration page, upgrade the Host to that version or higher: `npm install -g @deepseek-ai/dsh@next`.
+- **The declaration is narrow**: the floor is the version we actually tested, written as `>=` with **no ceiling** —
+  it claims no "everything in the future counts".
+  (It does cover later prereleases **within the same `major.minor.patch`**; once the host moves a patch position and
+  ships another prerelease, this floor no longer covers it and has to be raised again. Why: [Compatibility](docs/PUBLISHING.md#兼容性).)
+- **Why the floor moved**: not a change of where the UI lives, but a change of the **settings seam**
+  (without the two things this plugin relies on, the whole client half never renders — the ring and the popover go with it).
+  The plugin never reads a Host version; it **probes that capability live**, and when it is absent the popover carries
+  one extra English line saying why the configuration page is unavailable and where to upgrade.
+  Technical detail: see [Architecture](docs/ARCHITECTURE.md).
+- **Compatibility is not inferred**: a weekly [compat.yml](.github/workflows/compat.yml) run swaps packages on both the
+  `alpha` and `next` lines and re-runs the existing tests, plus a separate check that the declared range still covers the
+  tracked line; a failure opens or updates a tracking issue with a fixed title. Current conclusions and what to do when
+  it goes red: see [Compatibility](docs/PUBLISHING.md#兼容性).
 
 ## Configuration
 
@@ -131,9 +176,8 @@ Open **Plugins → Installed** and step into the **DeepSeek Balance** (shown as
 - **Connection**: the API base URL and the credential, both blank by default — a blank URL means the official DeepSeek endpoint, and the credential is inherited from the official model page and is read-only.
   The nested "Customised settings" holds only the credential reference name.
 - **Display**: which currency to use for amounts, or let it follow the account.
-- **Thresholds**: two alert lines per currency (warning / critical). **Within one currency the critical line must be strictly lower than the warning line** — equality is rejected too.
-  `POST /api/v1/config` enforces the same rule and answers `422` otherwise;
-  but a hand-edited config file with an illegal pair **no longer errors** — the Host side stopped enforcing it, so the plugin **falls that pair back to its defaults** the moment it reads it, and logs one line.
+- **Thresholds**: two alert lines per currency (warning / critical). **Within one currency the critical line must be strictly lower than the warning line** — equality is rejected too, and saving is blocked while it is.
+  But a hand-edited config file with an illegal pair **no longer errors** — the plugin **falls that pair back to its defaults** the moment it reads it, and logs one line.
 
 > **Upgrade note**: the settings live in this plugin's own entry config and the key it is filed under changed once; **old values are not migrated** — please fill the table above in once after upgrading.
 - **Refresh**: the server refresh interval, the UI poll interval and the manual refresh cooldown. The cooldown counts from **the moment the refresh finishes**, so the seconds shown in the popover are the real ones left; if the backend says the refresh did not fire, the UI takes its remaining time instead of pretending otherwise.
@@ -144,7 +188,9 @@ Saving applies immediately; there is no need to restart DSH.
 
 - How full the ring is = the current balance as a fraction of that currency's **warning line**, capped at 100%; the critical line takes no part in drawing it — it already decided the colour.
 - Colour carries state only, never an amount: normal, low and critical each get one hue; an account that cannot be read gets a ring with a cross instead.
-- A currency with no threshold configured falls back to state: full ring for normal and unavailable, 3/4 for low, 1/4 for critical, empty for unknown.
+- A currency with no threshold configured falls back to state: **a full ring for normal, 3/4 for low, 1/4 for critical**.
+  (Only the family with a balance to look at draws an arc — those three, plus the old number while data is stale;
+  an unreadable account, a suspended account, nothing connected, an account with no balance: none of those draw an arc.)
 - Why colour is never computed from an amount, and why thresholds are only a scale → [Data flow](docs/ARCHITECTURE.md#数据流).
 
 ### Credentials
@@ -152,6 +198,18 @@ Saving applies immediately; there is no need to restart DSH.
 The key is resolved only through DSH's credential channel; the card's "API key" inherits the one already configured on the official model settings page.
 When it comes from the launch environment (an environment variable) the field is read-only and the badge says where it came from.
 
+**The balance has two official routes and the plugin picks one itself**: the API key from the model settings page or the launch environment, and the **DSH account sign-in** (signed in without a key is enough). The order is:
+
+- **the route the current session is on** — switching sessions *or the model in this session* re-reads it at once;
+- with no session readable, the globally selected model's route;
+- with neither decidable, **key first, account as the fallback**;
+- only when both are missing does it read "no credential configured".
+
+The parenthesised label to the right of the popover title is where that number came from: `(API key)` / `(account sign-in)`.
+**Whichever is shown is also the one that gets refreshed and named** — display, refresh and label never disagree.
+
+**This plugin only tracks the official number**, so if the preferred route has nothing to show it falls back to the other official one: as long as either the account or an API key works, you still see a balance (even a slightly older snapshot). **You are only told about it when neither route can produce a number** — that is what "not connected to official" means. What the ring looks like at that moment: see [the ring at a glance](#the-ring-at-a-glance).
+
 **How long a key change takes to land follows DSH's own layers — this plugin deliberately adds nothing on top:**
 
 - **A key from the launch environment (an environment variable): restart DSH to change it.** A process's environment is fixed the moment it starts; a later change to that variable outside is invisible to the running plugin.
@@ -164,8 +222,8 @@ Why it is this way → [Key decisions](docs/ARCHITECTURE.md#关键决策).
 
 - **The API key is never returned to the UI**: the config endpoint returns only a fixed-length mask, not even the last few characters.
 - The key is never logged and never written to a file owned by this plugin; the settings file holds only a reference name, so the card is safe to screenshot or share.
-- Balance snapshots live in DSH's own data directory, grouped by a ledger identifier derived from the credential — changing the key opens a new ledger and old snapshots are never mixed in.
-- That identifier also involves a `.salt` file in DSH's home directory; **lose it and old snapshots become unreadable**.
+- Balance snapshots live in DSH's own data directory, grouped by an identifier derived from the credential — **changing the key opens a new ledger** and old snapshots are never mixed in.
+- That identifier also involves a random salt file in DSH's home directory; **lose it and old snapshots become unreadable** (they can never resolve to someone else's).
 - Only `api.deepseek.com` is contacted; nothing is proxied or forwarded.
 
 ## License

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

@@ -7,7 +7,7 @@
  * - 打开失败要**降级**而不是抛出去 —— 未观察的 rejection 曾把宿主整个拖下水。
  * @module dsh-ds-balance/adapters/domain-core-store
  */
-import type { BalanceSnapshot } 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';
 /** 域里的表名。 */
@@ -24,7 +24,7 @@ export interface StoredSnapshot {
         granted: string;
         toppedUp: string;
     }>;
-    source: 'deepseek-http';
+    source: BalanceSource;
 }
 /**
  * 域声明。
@@ -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(),
@@ -25,7 +50,9 @@ const storedSnapshotSchema = z.object({
     fetchedAt: z.number(),
     isAvailable: z.boolean(),
     balances: z.array(storedBalanceSchema),
-    source: z.literal('deepseek-http'),
+    // **取值只增不改**：域版本一动，已落盘的账本会在 open 时直接 `version-mismatch` 拒开。
+    // 旧记录里只有 `deepseek-http`，它必须一直是合法值。
+    source: z.enum(['deepseek-http', 'deepseek-account']),
 });
 /**
  * 域声明。
@@ -125,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() {
@@ -147,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' };