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

package/README.md

@@ -61,6 +61,9 @@
 - 凭据默认继承官方模型页配好的那一份，不必重填；徽标只报「已配置密钥。/ 未配置密钥。」（官方卡片同款），
   只读时不给编辑，并说明原因。
 - 颜色只表达状态（正常 / 偏低 / 告急），与金额大小无关；读法与理由见「[圆环怎么读](#圆环怎么读)」。
+- 插件页里以**本地化名字**出现：中文界面是「DeepSeek 余额」，英文界面是「DeepSeek Balance」——
+  卡片与详情页的标题、那句话说明都跟随界面语言，图标就是左边栏那个环（橙色弧环，画的是「用了七成」那一档）；
+  详情页仍会把包名 `dsh-ds-balance` 单独写出来。
 
 ## 安装
 
@@ -106,25 +109,29 @@ dsh plugin --profile web add "$PWD"
 
 ## 版本兼容
 
-- 配置界面注册在宿主的 `plugins.bundle.config` 槽，**该槽由 DSH 0.1.6-alpha.2 引入**（下限的真源是 [package.json](package.json) 的 `engines.dsh`，现状现查 `node scripts/compat-swap.mjs check`）。
-- 更早的宿主上圆环与浮层照常工作，只是**插件页里不会出现配置区**（不报错）—— 这就是分水岭。插件不查宿主版本号，只探测这一格在不在：探测不到时**浮层里会多一行英文 `[WARN]`**，说明配置界面为什么不可用、该往哪儿升级。
+- 配置界面注册在宿主的 `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`。
-- 声明是**窄**的：下限是引入该槽的那一版，上限排掉下一个可能不兼容的大版本 —— 不是「以后都兼容」，也不把更早的版本算进来。可它罩不住新的预发布段，所以宿主推新的 alpha 之后仍可能过期；每周的 `declaration` 巡检专门盯这件事，红了怎么办见[兼容性](docs/PUBLISHING.md#兼容性)。
+- 声明是**窄**的：下限是我们实测过的那一版，用 `>=` 而**不设上限** —— 既不承诺「以后都兼容」，也不会因为宿主多推一个预发布段就失效。为什么这么定见[兼容性](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

@@ -61,6 +61,9 @@ The division of labour is fixed: **the ring answers "roughly how much is left",
 - 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
 
@@ -106,25 +109,29 @@ 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, which **arrives with DSH 0.1.6-alpha.2** (the floor's single source is `engines.dsh` in [package.json](package.json); check the current lines 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 (with no error) — that is the watershed. The plugin never reads a Host version: it probes whether that slot exists, and when it does not, **the popover carries one extra English `[WARN]` line** saying why the configuration page is unavailable and where to upgrade.
+- 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 that introduced the slot and the ceiling excludes the next possibly-incompatible version — not "everything in the future counts", and nothing earlier is claimed either. It still cannot cover a new prerelease segment, so a new Host alpha can outdate it; the weekly `declaration` patrol watches exactly that, and what to do when it goes red is in [Compatibility](docs/PUBLISHING.md#兼容性).
+- 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 with four groups **all collapsed by default** — expand them from their headers:
+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>