dsh-ds-balance 2.0.0-alpha.0 → 2.0.0-alpha.2

package/README.md

@@ -39,28 +39,31 @@
 
 | 界面 | 一句话 | 你会用它来 |
 |---|---|---|
-| 侧栏圆环 | 常驻左边栏底部的状态环 + 名称，**环里填了多少 = 余额离该币种预警线还有多远** | 扫一眼就知道还剩多少、离预警线多远 |
-| 余额浮层 | 点条目展开：总额、赠送 / 充值拆分、数据新鲜度、手动刷新（带冷却） | 核对具体数字，以及数据是几分钟前的 |
-| 设置卡片 | 连接 / 展示 / 阈值 / 刷新四组，默认四组全展开，各自可折叠 | 换端点、换币种、调预警线、调节奏 |
+| 侧栏圆环 | 常驻左边栏底部的状态环 + 名称，**展开态悬浮条目就报出余额金额**，**环里填了多少 = 余额离该币种预警线还有多远** | 扫一眼就知道还剩多少、离预警线多远 |
+| 余额浮层 | 点条目展开：总额、赠送 / 充值拆分、数据新鲜度、手动刷新（带冷却）；**右上角图标一键跳到插件页** | 核对具体数字，以及数据是几分钟前的 |
+| 设置卡片 | 连接 / 展示 / 阈值 / 刷新四组，**默认四组全收起**，点组头逐组展开 | 换端点、换币种、调预警线、调节奏 |
 
 三种界面的分工是死的：**圆环回答「大概还剩多少」，浮层回答「具体是多少」，卡片回答「怎么算」。**
 
 <p align="center">
   <img src="assets/settings-card.png" alt="插件页里的「DeepSeek 余额」卡片" width="360">
   <br>
-  <em>卡片就是这四组：默认全展开，各自可折叠；组里有填错的项时那一组会自己展开。</em>
+  <em>卡片就是这四组：默认四组全收起，点组头逐组展开；组里有填错的项时那一组会自己展开。</em>
 </p>
 
 ## 能力
 
 - 左边栏底部常驻一个状态环加名称，点开看明细；收起与展开是同一个环，位置不变。
 - 余额按设定的周期自动刷新，界面读的是缓存 —— 开着界面不会反复去打上游接口。
-- 浮层给出总额、赠送 / 充值拆分、数据是多久之前的，以及一个带冷却的手动刷新。
-- 多币种：显示哪个币种由账户决定；设置里选的币种账户里没有时，浮层会说明并给一键改用。
-- 设置卡片分四组、默认全展开、各自可折叠；组里有填错的项时，那一组会自己展开。
+- 浮层给出总额、赠送 / 充值拆分、数据是多久之前的，以及一个带冷却的手动刷新；标题那行「鲸鱼图标 + DeepSeek 余额」本身是外链，点开是新标签页里的[官网用量页](https://platform.deepseek.com/usage)。
+- 多币种：显示哪个币种由账户决定；设置里选的币种账户里没有时，浮层会说明并给「改用实际币种」——**点它直接写进设置**，设置页那一格跟着变；宿主不可写时按钮置灰。
+- 设置卡片分四组、**默认全收起**、点组头展开；组里有填错的项时，那一组会自己展开。
 - 凭据默认继承官方模型页配好的那一份，不必重填；徽标只报「已配置密钥。/ 未配置密钥。」（官方卡片同款），
   只读时不给编辑，并说明原因。
 - 颜色只表达状态（正常 / 偏低 / 告急），与金额大小无关；读法与理由见「[圆环怎么读](#圆环怎么读)」。
+- 插件页里以**本地化名字**出现：中文界面是「DeepSeek 余额」，英文界面是「DeepSeek Balance」——
+  卡片与详情页的标题、那句话说明都跟随界面语言，图标就是左边栏那个环（橙色弧环，画的是「用了七成」那一档）；
+  详情页仍会把包名 `dsh-ds-balance` 单独写出来。
 
 ## 安装
 
@@ -75,7 +78,7 @@
 npm install -g @deepseek-ai/dsh@alpha     # 本插件承诺支持的线
 ```
 
-兼容性不是推断出来的：每周由 [compat.yml](.github/workflows/compat.yml) 在 `alpha` 与 `next` 两条线上换包实跑一遍现有测试。当前结论与红了怎么办见 [兼容性](docs/PUBLISHING.md#兼容性)。配置界面注册在宿主的 `plugins.bundle.config` 槽，**该槽由 DSH 0.1.6 引入**（下限的真源是 [package.json](package.json) 的 `engines.dsh`，现查 `node scripts/compat-swap.mjs check`）：更早的宿主上圆环与浮层照常工作，但**插件页里不会出现配置区**（静默，不报错）—— 这就是分水岭。
+兼容性不是推断出来的：每周由 [compat.yml](.github/workflows/compat.yml) 在 `alpha` 与 `next` 两条线上换包实跑一遍现有测试，另有一步单独判声明面罩不罩得住；红了会开或更新一条固定标题的跟踪 issue。当前结论与红了怎么办见 [兼容性](docs/PUBLISHING.md#兼容性)，宿主版本的分水岭见[版本兼容](#版本兼容)。
 
 ### 从 npm 安装
 
@@ -104,20 +107,31 @@ dsh plugin --profile web add "$PWD"
 
 仓库带有 GitHub topic [`dsh-plugin`](https://github.com/topics/dsh-plugin)，插件市场据此自动发现插件。
 
+## 版本兼容
+
+- 配置界面注册在宿主的 `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#兼容性)。
+
 ## 配置
 
-打开侧边栏 **插件（Plugins）** →「已安装（Installed）」组，点进 **dsh-ds-balance** 的详情页；配置表单直接铺在那一页上，四组默认全展开、各自可折叠：
+打开侧边栏 **插件（Plugins）** →「已安装（Installed）」组 → 点进 **DeepSeek 余额**（英文界面下是 **DeepSeek Balance**）的详情页 —— **配置区就在描述下面，直接可改**（那一行上没有第二个 Configure 步骤）；四组**默认全收起**，点组头逐组展开：
 
 <p align="center">
   <img src="assets/settings-cards-position.png" alt="Plugins 页列表里「DeepSeek 余额」的位置" width="480">
   <br>
-  <em>Plugins 页列表里的位置：<code>dsh-ds-balance</code> 与其他已安装插件并排；点进它的详情页才是上面那张配置表单。</em>
+  <em>Plugins 页列表里的位置：「DeepSeek 余额」与其他已安装插件并排；点它的插件名进详情页，上面那张配置表单就在描述下面。</em>
 </p>
 
 - **连接**：API 地址与凭据，两项都默认留空 —— 地址留空即用 DeepSeek 官方端点，凭据继承官方模型页那一份、只读不可改；
   二级「自定义设置」里只放凭据引用名。
 - **展示**：金额用哪种币种，或让它自动跟随账户。
 - **阈值**：每个币种两档提醒线（预警 / 告急）。同一币种内**告急必须严格低于预警**，相等也会被拒绝。
+  `POST /api/v1/config` 也按这条判，违反回 `422`；
+  但**手改配置文件写成的非法组合不会再报错** —— 宿主那一侧已经不再强制它，插件会在读到的那一刻把这一对**回落成默认值**并在日志里记一次。
+
+> **升级提示**：设置项存在插件那一行的配置里，键名跟着宿主升级变过一次，**旧值不会自动迁移** —— 升级后请照上表重填一次。
 - **刷新**：服务端刷新周期与界面轮询周期。
 
 保存即生效，不必重启 DSH。

package/README_en.md

@@ -39,28 +39,31 @@ The balance needs somewhere to live that does not take up room. A permanent stat
 
 | Surface | One line | Use it for |
 |---|---|---|
-| Sidebar ring | A status ring plus label at the bottom of the sidebar; **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) | Checking the exact figures, and how many minutes old they are |
-| Settings card | Connection / Display / Thresholds / Refresh, all expanded by default, each collapsible | Changing the endpoint, the currency, the warning lines, the cadence |
+| 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 jumps straight to the Plugins page** | 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".**
 
 <p align="center">
   <img src="assets/settings-card_en.png" alt="The DeepSeek balance card on the Plugins page" width="360">
   <br>
-  <em>The card is those four groups: all expanded by default, each collapsible; a group holding a bad value opens itself.</em>
+  <em>The card is those four groups: all collapsed by default, expanded one header at a time; a group holding a bad value opens itself.</em>
 </p>
 
 ## Capabilities
 
 - A permanent status ring plus label at the bottom of the sidebar; click it for the breakdown. The collapsed and expanded states share the same ring, in the same place.
 - The balance refreshes on its own schedule and the UI reads a cache — leaving the interface open does not hammer the upstream.
-- The popover shows the total, the granted / topped-up split, how old the data is, and a manual refresh with a cooldown.
-- Multiple currencies: the account decides which currency is shown; when the one chosen in settings is absent, the popover explains and offers a one-click switch.
-- The settings card has four groups, all expanded by default and each collapsible; a group holding a bad value opens itself.
+- The popover shows the total, the granted / topped-up split, how old the data is, and a manual refresh with a cooldown; its title line (whale icon + "DeepSeek balance") is itself a link that opens the [official usage page](https://platform.deepseek.com/usage) in a new tab.
+- Multiple currencies: the account decides which currency is shown; when the one chosen in settings is absent, the popover explains and offers "switch to the shown currency" — **that writes straight into settings**, and the settings field follows; the button is disabled when the Host is not writable.
+- The settings card has four groups, **all collapsed by default**, expanded one header at a time; a group holding a bad value opens itself.
 - The credential is inherited from the official model settings by default, so there is nothing to re-enter; where it comes from is on a badge
   (a key is configured / no key is configured, exactly the official card's wording), and a read-only field explains itself instead of offering an edit.
 - Colour carries state only (normal / low / critical), never an amount; see "[Reading the ring](#reading-the-ring)".
+- It appears on the Plugins page under a **localized name**: "DeepSeek Balance" in English, "DeepSeek 余额" in Chinese —
+  the card and the details page follow the interface language, and the icon is the same ring as the sidebar one
+  (an orange arc reading "seven tenths used"); the details page still spells out the package name `dsh-ds-balance`.
 
 ## Installation
 
@@ -75,7 +78,7 @@ Install the host by **naming the version line explicitly**: the `latest` tag of
 npm install -g @deepseek-ai/dsh@alpha     # the line this plugin promises to support
 ```
 
-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. The current verdict, and what to do when it goes red, are in [Compatibility](docs/PUBLISHING.md#兼容性). The configuration UI registers into the Host's `plugins.bundle.config` slot, which **arrives with DSH 0.1.6** (the floor's single source is `engines.dsh` in [package.json](package.json); check it live with `node scripts/compat-swap.mjs check`): on an earlier Host the ring and the popover keep working, but the configuration area never appears on the Plugins page (silently, with no error) — that is the watershed.
+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).
 
 ### From npm
 
@@ -104,20 +107,31 @@ Same as the npm route: it takes effect after a restart.
 
 The repository carries the GitHub topic [`dsh-plugin`](https://github.com/topics/dsh-plugin), which is how the plugin marketplace discovers plugins.
 
+## 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#兼容性).
+
 ## Configuration
 
-Open **Plugins → Installed** and step into the **dsh-ds-balance** details page. The form runs straight down that page, four groups all expanded by default and each collapsible:
+Open **Plugins → Installed** and step into the **DeepSeek Balance** (shown as **DeepSeek 余额** in Chinese) details page — **the configuration sits right below the description, ready to edit** (there is no second Configure step on that row). Four groups are **all collapsed by default** — expand them from their headers:
 
 <p align="center">
   <img src="assets/settings-cards-position_en.png" alt="Where the DeepSeek balance entry sits in the Plugins list" width="480">
   <br>
-  <em>Where it sits: the Plugins page's list view, with <code>dsh-ds-balance</code> alongside the other installed plugins; the details page behind it carries the form shown above.</em>
+  <em>Where it sits: the Plugins page's list view, with "DeepSeek Balance" alongside the other installed plugins; open its details page and the form shown above sits right below the description.</em>
 </p>
 
 - **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.
+
+> **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 and the UI poll interval.
 
 Saving applies immediately; there is no need to restart DSH.

package/icon.svg

@@ -0,0 +1,36 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <!--
+    dsh-ds-balance 的插件页图标：就是左边栏那个状态环（轨道 + 七成弧），等比放大。
+
+    几何照 src/client/sidebar/PercentRing.tsx（viewBox 16 / 笔画 1 / 半径 6.5 / 中心 8），
+    整组用 translate(18 18) scale(9/7) translate(-8 -8) 搬进 36 格：
+    墨迹外径 14 放大成 18，外接框 9–27，四周各留 9（官方配方 8–9）。
+    弧长 70%，dasharray 与组件在 ratio=0.7 时算出来的逐字相同；线帽照环用圆头。
+
+    两处颜色都只能写死（宿主按图片渲染，currentColor 与主题变量都不起作用）：
+
+    弧 #F59E0B：宿主那条 warn 档语义色（amber-500）的值，亮暗两块表逐字相同，
+    也就是环在 warning 档画出来的颜色。
+
+    轨道 #7F8287 + 45%：环的轨道用的是「跟随主题的半透明色」（亮 12% 黑 / 暗 16% 白），
+    静态资源烘不了主题，所以取中性的 neutral-500（亮暗同值）加四成半不透明度 ——
+    它落在白底上约等于亮档轨道的观感、落在深色底上约等于暗档的观感，两种主题都看得见，
+    又明显比弧轻。
+
+    注意：XML 注释里不许出现连续两个连字符，所以这里不写那几条 token 的原名 ——
+    第一版就是这么坏掉的（浏览器当图片解析失败，插件页静默回落成默认图形）。
+  -->
+  <g transform="translate(18 18) scale(1.2857142857142858) translate(-8 -8)">
+    <circle cx="8" cy="8" r="6.5" stroke="#7F8287" stroke-opacity="0.45" stroke-width="1" />
+    <circle
+      cx="8"
+      cy="8"
+      r="6.5"
+      stroke="#F59E0B"
+      stroke-width="1"
+      stroke-linecap="round"
+      stroke-dasharray="28.588 40.841"
+      transform="rotate(-90 8 8)"
+    />
+  </g>
+</svg>