dsh-ds-balance 2.1.3 → 2.2.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 安装
 
@@ -113,10 +141,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 +167,9 @@ dsh plugin --profile web add "$PWD"
 - **连接**：API 地址与凭据，两项都默认留空 —— 地址留空即用 DeepSeek 官方端点，凭据继承官方模型页那一份、只读不可改；
   二级「自定义设置」里只放凭据引用名。
 - **展示**：金额用哪种币种，或让它自动跟随账户。
-- **阈值**：每个币种两档提醒线（预警 / 告急）。同一币种内**告急必须严格低于预警**，相等也会被拒绝。
-  `POST /api/v1/config` 也按这条判，违反回 `422`；
-  但**手改配置文件写成的非法组合不会再报错** —— 宿主那一侧已经不再强制它，插件会在读到的那一刻把这一对**回落成默认值**并在日志里记一次。
+- **阈值**：每个币种两档提醒线（预警 / 告急）。同一币种内**告急必须严格低于预警**，相等也会被拒绝
+  （保存时就会拦下来）；但**手改配置文件写成的非法组合不会再报错** ——
+  插件读到的那一刻会把这一对**回落成默认值**并在日志里记一次。
 
 > **升级提示**：设置项存在插件那一行的配置里，键名跟着宿主升级变过一次，**旧值不会自动迁移** —— 升级后请照上表重填一次。
 - **刷新**：服务端刷新周期、界面轮询周期与手动刷新冷却。冷却从**刷完那一刻**起算，
@@ -145,7 +181,9 @@ dsh plugin --profile web add "$PWD"
 
 - 环里填多少 = 当前余额占该币种**预警线**的比例，100% 封顶；告急线不参与画环 —— 它已经决定了颜色。
 - 颜色只表达状态，与金额大小无关：正常、偏低、告急各一色；账户读不到时另画一个带叉号的环。
-- 没配阈值的币种退回按状态定性：正常与不可用画满环，偏低 3/4，告急 1/4，未知空环。
+- 没配阈值的币种退回按状态定性：**正常画满环，偏低 3/4，告急 1/4**。
+  （只有**有余额可看**的那一族画弧 —— 上面三档，加上「数据已过期」时的那份旧数字；
+  账户读不到、账户停用、没接入、账户没钱这些**都不画弧**，环靠颜色与中心记号说话。）
 - 为什么颜色不由金额算、阈值为什么只当刻度 → [数据流](docs/ARCHITECTURE.md#数据流)。
 
 ### 凭据
@@ -153,6 +191,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 +215,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
 
@@ -113,10 +143,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 +172,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 +184,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 +194,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 +218,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, 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;
 }
 /**
  * 域声明。

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

@@ -25,7 +25,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']),
 });
 /**
  * 域声明。

package/lib/adapters/host-account.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 宿主账号服务 → {@link AccountSource}。
+ *
+ * 这是**可选**接缝：`apply` 里由 `ctx.inject(['deepseekAccount'], …)` 把门，服务缺席时整个对象
+ * 不存在，插件退回只看 API Key。
+ *
+ * 服务面用**鸭子类型**收窄而不是 import 宿主类型：`ctx.deepseekAccount` 的类型来自
+ * `@deepseek-ai/dsh-deepseek-account`，而运行时提供方是 `-account-platform` —— 引类型要多挂一个包，
+ * 而这里只用到三个方法。运行期关系由 `ctx.inject` 表达，声明面由 `peerDependencies` 表达。
+ * @module dsh-ds-balance/adapters/host-account
+ */
+import type { AccountWallet } from '../domain/account.js';
+import type { AccountSource } from '../ports/account.js';
+import type { Logger } from '../ports/logger.js';
+/** 宿主单次余额查询的结果形状（对齐 `AccountDetails['balance']`）。 */
+export type HostAccountBalance = {
+    readonly status: 'ready';
+    readonly value: readonly AccountWallet[];
+    readonly bonusWallets: readonly AccountWallet[];
+} | {
+    readonly status: 'failed';
+};
+/** 宿主为这次调用要的客户端标识（对齐 `AccountClientMetadata`）。 */
+export interface HostAccountClient {
+    readonly version: string;
+    readonly locale: string;
+    readonly timezoneOffsetSeconds: number;
+}
+/**
+ * 宿主账号服务的最小面。
+ *
+ * 三个方法的语义逐字对齐宿主 `DeepSeekAccount` 的公开面；`null` 一律表示**此刻没有可用账号**
+ * （未登录，或凭据在查询途中被换掉），不是「余额为零」。
+ */
+export interface HostAccountFace {
+    getState(): Promise<{
+        readonly status?: string;
+    } | undefined>;
+    getBalance(client: HostAccountClient): Promise<HostAccountBalance | null>;
+    getPlatformSession(): Promise<{
+        readonly userId?: string | null;
+    } | null>;
+}
+/** 构造参数。 */
+export interface HostAccountOptions {
+    service: HostAccountFace;
+    /** 上报给 Platform 的客户端版本；用插件版本，与响应里回传的那个同源。 */
+    version: string;
+    /** 上报给 Platform 的语言；只选服务端文案，界面文案由本插件自己的词典给。 */
+    locale?: string;
+    /** 上报给 Platform 的时区偏移（秒，东为正）。 */
+    timezoneOffsetSeconds?: () => number;
+    logger?: Logger | undefined;
+}
+/**
+ * 把宿主账号服务收窄成 {@link AccountSource}。
+ *
+ * `readBalance` 的三种结果各有去处，**不合并**：
+ * - `null` → 回 `null`，上层回落另一条取数路；
+ * - `failed` → 抛 `UpstreamError`，**不回落**（回落只会把真因换成更难懂的 `NO_KEY`）；
+ * - `ready` → 原样交出去。
+ * @param options - 宿主服务与客户端标识。
+ * @returns 端口实现。
+ */
+export declare function createAccountSource(options: HostAccountOptions): AccountSource;
+//# sourceMappingURL=host-account.d.ts.map

package/lib/adapters/host-account.js

@@ -0,0 +1,68 @@
+/**
+ * 宿主账号服务 → {@link AccountSource}。
+ *
+ * 这是**可选**接缝：`apply` 里由 `ctx.inject(['deepseekAccount'], …)` 把门，服务缺席时整个对象
+ * 不存在，插件退回只看 API Key。
+ *
+ * 服务面用**鸭子类型**收窄而不是 import 宿主类型：`ctx.deepseekAccount` 的类型来自
+ * `@deepseek-ai/dsh-deepseek-account`，而运行时提供方是 `-account-platform` —— 引类型要多挂一个包，
+ * 而这里只用到三个方法。运行期关系由 `ctx.inject` 表达，声明面由 `peerDependencies` 表达。
+ * @module dsh-ds-balance/adapters/host-account
+ */
+import { UpstreamError, describeError } from '../domain/errors.js';
+/**
+ * 把宿主账号服务收窄成 {@link AccountSource}。
+ *
+ * `readBalance` 的三种结果各有去处，**不合并**：
+ * - `null` → 回 `null`，上层回落另一条取数路；
+ * - `failed` → 抛 `UpstreamError`，**不回落**（回落只会把真因换成更难懂的 `NO_KEY`）；
+ * - `ready` → 原样交出去。
+ * @param options - 宿主服务与客户端标识。
+ * @returns 端口实现。
+ */
+export function createAccountSource(options) {
+    const { service } = options;
+    const client = () => ({
+        version: options.version,
+        locale: options.locale ?? 'zh-CN',
+        timezoneOffsetSeconds: options.timezoneOffsetSeconds?.() ?? 0,
+    });
+    return {
+        async signedIn() {
+            try {
+                const state = await service.getState();
+                return state?.status === 'credential-stored';
+            }
+            catch (error) {
+                options.logger?.debug('ds-balance: account state unreadable', {
+                    error: describeError(error),
+                });
+                return false;
+            }
+        },
+        async accountId() {
+            try {
+                const session = await service.getPlatformSession();
+                const id = session?.userId;
+                return typeof id === 'string' && id !== '' ? id : null;
+            }
+            catch (error) {
+                options.logger?.debug('ds-balance: account identity unreadable', {
+                    error: describeError(error),
+                });
+                return null;
+            }
+        },
+        async readBalance() {
+            const result = await service.getBalance(client());
+            if (result === null)
+                return null;
+            if (result.status === 'failed') {
+                // 502 只是给分类用的：账号服务的查询失败属于上游不可用，不是「没有额度」。
+                throw new UpstreamError(502, 'account balance query failed');
+            }
+            return { wallets: result.value, bonusWallets: result.bonusWallets };
+        },
+    };
+}
+//# sourceMappingURL=host-account.js.map