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

package/README.md

@@ -1,81 +1,153 @@
-# ds-balance
+<p align="center">
+  <h1 align="center">dsh-ds-balance</h1>
+</p>
 
-[English](README_en.md)
+<div align="center">
+  <p><strong>把 DeepSeek 账户余额放进 DSH 的左边栏</strong></p>
+  <p><em>DeepSeek account balance in the DSH sidebar</em></p>
 
-[![ci](https://github.com/zlZayn/dsh-ds-balance/actions/workflows/ci.yml/badge.svg?branch=main)](.github/workflows/ci.yml)
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![node](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FzlZayn%2Fdsh-ds-balance%2Fmain%2Fpackage.json&query=%24.engines.node&label=node&color=brightgreen)](package.json)
-[![dsh](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FzlZayn%2Fdsh-ds-balance%2Fmain%2Fpackage.json&query=%24.engines.dsh&label=dsh&color=blueviolet)](package.json)
+  <p>
+    <a href="https://api-docs.deepseek.com/"><img src="https://img.shields.io/badge/DeepSeek%20API-Official-4D6BFE?style=flat" alt="DeepSeek 官方接口"></a>
+    <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/DeepSeek%20Harness-Plugin-4176E6?style=flat" alt="DeepSeek Harness Plugin"></a>
+  </p>
 
-> **NOTE**
-> 本包尚未发布到 npm，现在只能从源码安装。发布流程与版本号判定链见
-> [docs/PUBLISHING.md](docs/PUBLISHING.md)。
+  <p>
+    <a href="https://github.com/zlZayn/dsh-ds-balance/actions/workflows/ci.yml"><img src="https://github.com/zlZayn/dsh-ds-balance/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+    <a href="https://www.npmjs.com/package/dsh-ds-balance"><img src="https://img.shields.io/npm/v/dsh-ds-balance.svg" alt="npm"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT 许可证"></a>
+  </p>
 
-在 DSH 的左边栏底部显示 DeepSeek 账户余额，并在设置里提供一张配置卡片。
-余额真实读自官方 `GET /user/balance`；颜色只由后端返回的 `severity` 决定。
+  <p>
+    <strong><a href="README.md">简体中文</a></strong> · <a href="README_en.md">English</a>
+  </p>
+</div>
 
-![设置卡片](assets/settings-card.png)
+---
+
+> [!NOTE]
+> **余额读自 DeepSeek 官方 `GET /user/balance`**，不是估算。凭据只经 DSH 的凭据通道解析：API Key 不会出现在设置文件里，也不会返回给界面。
+
+余额要有地方看，但不该占地方。左边栏底部一个常驻的状态环，点开是三段金额与数据新鲜度；要改配置，进侧边栏**插件（Plugins）**页里本插件的详情页。
+
+<p align="center">
+  <img src="assets/sidebar-popover.png" alt="左边栏底部的「DeepSeek 余额」条目与展开的余额浮层" width="360">
+  <br>
+  <em>常驻<strong>左边栏底部</strong>，与「使用统计」「设置」并排；点开是余额、赠送 / 充值拆分与数据新鲜度。</em>
+</p>
+
+## 界面一览
+
+| 界面 | 一句话 | 你会用它来 |
+|---|---|---|
+| 侧栏圆环 | 常驻左边栏底部的状态环 + 名称，**环里填了多少 = 余额离该币种预警线还有多远** | 扫一眼就知道还剩多少、离预警线多远 |
+| 余额浮层 | 点条目展开：总额、赠送 / 充值拆分、数据新鲜度、手动刷新（带冷却） | 核对具体数字，以及数据是几分钟前的 |
+| 设置卡片 | 连接 / 展示 / 阈值 / 刷新四组，默认四组全展开，各自可折叠 | 换端点、换币种、调预警线、调节奏 |
+
+三种界面的分工是死的：**圆环回答「大概还剩多少」，浮层回答「具体是多少」，卡片回答「怎么算」。**
+
+<p align="center">
+  <img src="assets/settings-card.png" alt="插件页里的「DeepSeek 余额」卡片" width="360">
+  <br>
+  <em>卡片就是这四组：默认全展开，各自可折叠；组里有填错的项时那一组会自己展开。</em>
+</p>
 
 ## 能力
 
-- 侧栏底部常驻一个状态圆环加名称，点击展开浮层看余额明细；弧长是「余额占 warn 阈值」的比例，折叠与展开共用同一个圆环。
-- 真实读取 DeepSeek 官方余额（`GET /user/balance`），按 `serverRefreshSeconds` 在服务端刷新，
-  浏览器按 `clientPollSeconds` 取缓存，不穿透到上游。
-- 浮层：余额、赠送 / 充值拆分、数据新鲜度与手动刷新（带冷却）。
-- 多币种：由**后端**选定展示币种；设置里选的币种不在账户里时，浮层说明并给出一键改用。
-- 设置卡片分四组、各自可折叠：连接 / 展示 / 阈值 / 刷新，默认四组全收起；组内有非法草稿时该组强制展开。
-- 凭据字段带「已由启动环境提供 / 已配置 / 未配置 / 已覆盖」徽标；只读时框内留空，由徽标与说明行交代原因。凭据默认继承官方模型页配好的那一份，不必重填。
-- 只按后端给的 `severity` 上色；阈值只用来定圆环弧长，不参与配色。
+- 左边栏底部常驻一个状态环加名称，点开看明细；收起与展开是同一个环，位置不变。
+- 余额按设定的周期自动刷新，界面读的是缓存 —— 开着界面不会反复去打上游接口。
+- 浮层给出总额、赠送 / 充值拆分、数据是多久之前的，以及一个带冷却的手动刷新。
+- 多币种：显示哪个币种由账户决定；设置里选的币种账户里没有时，浮层会说明并给一键改用。
+- 设置卡片分四组、默认全展开、各自可折叠；组里有填错的项时，那一组会自己展开。
+- 凭据默认继承官方模型页配好的那一份，不必重填；徽标只报「已配置密钥。/ 未配置密钥。」（官方卡片同款），
+  只读时不给编辑，并说明原因。
+- 颜色只表达状态（正常 / 偏低 / 告急），与金额大小无关；读法与理由见「[圆环怎么读](#圆环怎么读)」。
 
 ## 安装
 
-前置：DSH `^0.1.6-alpha.1`，Node `>=20`。
+### 前置
 
-从 npm 安装尚未开放（包未发布）。从源码安装：
+- **DSH**：版本范围以 [package.json](package.json) 的 `engines.dsh` 与 `peerDependencies` 为准，本插件跟的是宿主当前那条 alpha 线。
+- Node `>= 20`（同上，真源是 `engines.node`）。
+
+装宿主时**要显式点名版本线**：`@deepseek-ai/dsh` 的 `latest` 标签比本插件要求的那条线还旧 —— 按默认方式装会落在声明范围之外。
+
+```bash
+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`）：更早的宿主上圆环与浮层照常工作，但**插件页里不会出现配置区**（静默，不报错）—— 这就是分水岭。
+
+### 从 npm 安装
+
+```bash
+dsh plugin --profile web add dsh-ds-balance
+```
+
+装完**重启 `dsh --profile web`** 生效。
+
+### 从源码安装
 
 ```bash
 git clone https://github.com/zlZayn/dsh-ds-balance.git
 cd dsh-ds-balance
-npm install
-npm run build
-dsh plugin --profile <profile> add .
+npm install && npm run build
+
+dsh plugin --profile web add "$PWD"
 ```
 
-装完还要把插件行写进该 profile 的 `cordis.patch.yml`；完整步骤与回滚方式见
-[AGENTS.md](AGENTS.md) 的「常用命令」。
+与 npm 那条路一样，重启后生效。
+
+### 发现与安装
 
-**宿主半边改了代码必须重启 DSH**；浏览器半边由客户端热更换入。
+- **npm**：[`dsh-ds-balance`](https://www.npmjs.com/package/dsh-ds-balance)
+- **GitHub**：[`zlZayn/dsh-ds-balance`](https://github.com/zlZayn/dsh-ds-balance)
 
-装好之后它在两处出现：设置 → 插件 → 插件配置里的配置卡片，以及左边栏底部的状态圆环。
+仓库带有 GitHub topic [`dsh-plugin`](https://github.com/topics/dsh-plugin)，插件市场据此自动发现插件。
 
 ## 配置
 
-卡片分四组，默认全收起：
+打开侧边栏 **插件（Plugins）** →「已安装（Installed）」组，点进 **dsh-ds-balance** 的详情页；配置表单直接铺在那一页上，四组默认全展开、各自可折叠：
 
-- 连接：只读的凭据状态、可编辑的 API 地址，以及收在二级「自定义设置」里的 apiKey 与 apiKeyRef。
-- 展示：金额用哪种币种，或让它自动跟随账户。
-- 阈值：几档提醒线。**由后端判定** —— 前端只拿 `warn` 当圆环弧长的刻度，不据此上色。同一币种的告急必须低于预警，否则保存按钮是灰的。
-- 刷新：服务端刷新周期与浏览器轮询周期。
+<p align="center">
+  <img src="assets/settings-cards-position.png" alt="Plugins 页列表里「DeepSeek 余额」的位置" width="480">
+  <br>
+  <em>Plugins 页列表里的位置：<code>dsh-ds-balance</code> 与其他已安装插件并排；点进它的详情页才是上面那张配置表单。</em>
+</p>
 
-## 数据从哪来、到哪去
+- **连接**：API 地址与凭据，两项都默认留空 —— 地址留空即用 DeepSeek 官方端点，凭据继承官方模型页那一份、只读不可改；
+  二级「自定义设置」里只放凭据引用名。
+- **展示**：金额用哪种币种，或让它自动跟随账户。
+- **阈值**：每个币种两档提醒线（预警 / 告急）。同一币种内**告急必须严格低于预警**，相等也会被拒绝。
+- **刷新**：服务端刷新周期与界面轮询周期。
 
-- 端点由宿主半边通过 `ctx.connection.fetch` 注册在 `/api/v1/*` 下，物理载体已做完信任与浏览器鉴权。
-- **API Key 永不返回前端**：配置接口只回一个固定长度的掩码串，连末几位也不给。
-- 密钥只经 DSH 的凭据通道解析，不落日志、不落本插件的文件。
-- 余额快照落在 DSH 自己的存储目录（`ctx.storageDomain`），按凭据派生出的账本标识分组；
-  换 key 自动开新账本，旧快照不会被混用。
-- 一个非记录型文件 `.salt` 落在 `$DSH_HOME` 下，用来派生账本标识；**它丢了旧快照会读不回来**。
+保存即生效，不必重启 DSH。
 
-## 界面与后端的边界
+### 圆环怎么读
 
-- 颜色只由后端 `severity` 决定。前端只在圆环弧长里读 `warn` 阈值当刻度，不用它配色。
-- 金额一律是八位小数的字符串，前端按字符串裁两位显示，不经过浮点数。
-- 完整响应形状与配置契约 → [docs/ui-handoff.md](docs/ui-handoff.md)。
+- 环里填多少 = 当前余额占该币种**预警线**的比例，100% 封顶；告急线不参与画环 —— 它已经决定了颜色。
+- 颜色只表达状态，与金额大小无关：正常、偏低、告急各一色；账户读不到时另画一个带叉号的环。
+- 没配阈值的币种退回按状态定性：正常与不可用画满环，偏低 3/4，告急 1/4，未知空环。
+- 为什么颜色不由金额算、阈值为什么只当刻度 → [数据流](docs/ARCHITECTURE.md#数据流)。
 
-## 贡献
+### 凭据
 
-报 bug、提功能与提 PR 的前置条件见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+密钥只经 DSH 的凭据通道解析，卡片里的 `API Key` 一栏默认继承官方模型页配好的那一份，且只读不可改。
+由启动环境（环境变量）提供时，字段只读，徽标写明来源。
+
+## 安全与边界
+
+- **API Key 永不返回界面**：配置接口只回一个固定长度的掩码串，连末几位也不给。
+- 密钥不落日志、不落本插件的文件；设置文件里只有引用名，卡片可以安全截图或分享。
+- 余额快照存在 DSH 自己的数据目录里，按凭据派生出的账本标识分组 —— 换 key 自动开新账本，旧快照不会被混用。
+- 账本标识还要一个 `.salt` 文件（在 DSH 的 home 目录下）参与派生；**它丢了，旧快照就读不回来**。
+- 只访问 `api.deepseek.com`，不代理、不转发其他流量。
+
+## 许可
+
+[MIT](LICENSE)。
+
+## 贡献
 
-## License
+外部贡献入口（报 bug 带什么、提功能前先翻什么、提 PR 前做什么）→ [CONTRIBUTING.md](CONTRIBUTING.md)。
 
-MIT，见 [LICENSE](LICENSE)。
+设计取向与实现约束 → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)；发布流程与版本号判定 → [docs/PUBLISHING.md](docs/PUBLISHING.md)；维护者文档地图 → [AGENTS.md](AGENTS.md)。

package/README_en.md

@@ -1,81 +1,153 @@
-# ds-balance
+<p align="center">
+  <h1 align="center">dsh-ds-balance</h1>
+</p>
 
-[中文](README.md)
+<div align="center">
+  <p><strong>DeepSeek account balance in the DSH sidebar</strong></p>
+  <p><em>把 DeepSeek 账户余额放进 DSH 的左边栏</em></p>
 
-[![ci](https://github.com/zlZayn/dsh-ds-balance/actions/workflows/ci.yml/badge.svg?branch=main)](.github/workflows/ci.yml)
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![node](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FzlZayn%2Fdsh-ds-balance%2Fmain%2Fpackage.json&query=%24.engines.node&label=node&color=brightgreen)](package.json)
-[![dsh](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FzlZayn%2Fdsh-ds-balance%2Fmain%2Fpackage.json&query=%24.engines.dsh&label=dsh&color=blueviolet)](package.json)
+  <p>
+    <a href="https://api-docs.deepseek.com/"><img src="https://img.shields.io/badge/DeepSeek%20API-Official-4D6BFE?style=flat" alt="DeepSeek official API"></a>
+    <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/DeepSeek%20Harness-Plugin-4176E6?style=flat" alt="DeepSeek Harness Plugin"></a>
+  </p>
 
-> **NOTE**
-> This package is not on npm yet; it installs from source only.
-> The release flow and the version-bump decision chain are in
-> [docs/PUBLISHING.md](docs/PUBLISHING.md).
+  <p>
+    <a href="https://github.com/zlZayn/dsh-ds-balance/actions/workflows/ci.yml"><img src="https://github.com/zlZayn/dsh-ds-balance/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+    <a href="https://www.npmjs.com/package/dsh-ds-balance"><img src="https://img.shields.io/npm/v/dsh-ds-balance.svg" alt="npm"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
+  </p>
 
-Shows the DeepSeek account balance at the bottom of the DSH sidebar, with a configuration card in settings.
-The balance is read from the real `GET /user/balance`; colour comes only from the `severity` the server returns.
+  <p>
+    <a href="README.md">简体中文</a> · <strong><a href="README_en.md">English</a></strong>
+  </p>
+</div>
 
-![settings card](assets/settings-card_en.png)
+---
+
+> [!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 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**.
+
+<p align="center">
+  <img src="assets/sidebar-popover_en.png" alt="The DeepSeek balance entry at the bottom of the sidebar, with its popover open" width="360">
+  <br>
+  <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>
+
+## Surface at a glance
+
+| 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 |
+
+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>
+</p>
 
 ## Capabilities
 
-- A permanent status ring plus label at the bottom of the sidebar; click it to open a popover with the balance breakdown. Its arc is the balance as a fraction of the `warn` threshold, and the collapsed and expanded states share the same ring.
-- Reads the real DeepSeek balance (`GET /user/balance`); the server refreshes on `serverRefreshSeconds` and the browser reads the cache on `clientPollSeconds` without hitting the upstream.
-- Popover: total balance, granted / topped-up split, data freshness, and a manual refresh with cooldown.
-- Multiple currencies: the **server** picks which currency to show; when the currency chosen in settings is absent from the account, the popover says so and offers a one-click switch.
-- The settings card has four collapsible groups — Connection / Display / Thresholds / Refresh — all collapsed by default; a group with an invalid draft is forced open.
-- Credential fields carry a "provided by launch environment / configured / not configured / overridden" badge; a read-only field stays empty and lets the badge and the line under it explain why. The credential is inherited from the official model settings by default, so there is nothing to re-enter.
-- Colour comes only from the `severity` the server returns; thresholds only scale the ring arc and never affect colour.
+- 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 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)".
 
 ## Installation
 
-Prerequisites: DSH `^0.1.6-alpha.1`, Node `>=20`.
+### Requirements
 
-Installing from npm is not open yet (the package is unpublished). From source:
+- **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`).
+
+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.
+
+```bash
+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.
+
+### From npm
+
+```bash
+dsh plugin --profile web add dsh-ds-balance
+```
+
+**Restarting `dsh --profile web`** is what makes it take effect.
+
+### From source
 
 ```bash
 git clone https://github.com/zlZayn/dsh-ds-balance.git
 cd dsh-ds-balance
-npm install
-npm run build
-dsh plugin --profile <profile> add .
+npm install && npm run build
+
+dsh plugin --profile web add "$PWD"
 ```
 
-After installing, add the plugin row to that profile's `cordis.patch.yml`; the full steps and rollback are in
-[AGENTS.md](AGENTS.md), section "常用命令".
+Same as the npm route: it takes effect after a restart.
+
+### Discovery
 
-**Changing the host half requires restarting DSH**; the browser half is hot-swapped by the client.
+- **npm**: [`dsh-ds-balance`](https://www.npmjs.com/package/dsh-ds-balance)
+- **GitHub**: [`zlZayn/dsh-ds-balance`](https://github.com/zlZayn/dsh-ds-balance)
 
-Once installed it shows up in two places: a configuration card under Settings → Plugins → Plugin configuration,
-and a status ring at the bottom of the sidebar.
+The repository carries the GitHub topic [`dsh-plugin`](https://github.com/topics/dsh-plugin), which is how the plugin marketplace discovers plugins.
 
 ## Configuration
 
-The card has four groups, all collapsed by default:
+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:
 
-- Connection: the read-only credential state, an editable API base URL, and the apiKey / apiKeyRef kept inside the nested "Customised settings".
-- Display: which currency to use for amounts, or let it follow the account.
-- Thresholds: the alert lines. They are **evaluated on the server** — the frontend only scales the ring arc by `warn`, and never colours anything from them. Within one currency the critical line must be lower than the warning, or Save stays disabled.
-- Refresh: the server refresh interval and the browser poll interval.
+<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>
+</p>
 
-## Where the data comes from and goes
+- **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.
+- **Refresh**: the server refresh interval and the UI poll interval.
 
-- Endpoints are registered by the host half under `/api/v1/*` via `ctx.connection.fetch`; the physical carrier already applies trust and browser authentication.
-- **The API key is never returned to the frontend**: the config endpoint returns only a fixed-length mask, not even the last few characters.
-- The key is resolved only through the DSH credential channel; it is never logged and never written to a file owned by this plugin.
-- Balance snapshots land in DSH's own storage (`ctx.storageDomain`), grouped by a ledger identifier derived from the credential. Changing the key opens a new ledger; old snapshots are never mixed in.
-- One non-record file, `.salt`, lives under `$DSH_HOME` and derives the ledger identifier. **Losing it makes old snapshots unreadable.**
+Saving applies immediately; there is no need to restart DSH.
 
-## Boundary between UI and backend
+### Reading the ring
 
-- Colour is decided only by the server's `severity`. The frontend reads the `warn` threshold only to scale the ring arc, never to colour anything.
-- Amounts are always eight-decimal strings; the frontend trims them to two characters-wise and never goes through floating point.
-- Full response shape and configuration contract → [docs/ui-handoff.md](docs/ui-handoff.md).
+- 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.
+- Why colour is never computed from an amount, and why thresholds are only a scale → [Data flow](docs/ARCHITECTURE.md#数据流).
 
-## Contributing
+### Credentials
 
-Prerequisites for bug reports, feature proposals, and pull requests are in [CONTRIBUTING_en.md](CONTRIBUTING_en.md).
+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.
+
+## Security and boundaries
+
+- **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**.
+- Only `api.deepseek.com` is contacted; nothing is proxied or forwarded.
 
 ## License
 
-MIT, see [LICENSE](LICENSE).
+[MIT](LICENSE).
+
+## Contributing
+
+Where to report bugs, what to check before proposing a feature, and what to do before sending a PR → [CONTRIBUTING_en.md](CONTRIBUTING_en.md).
+
+Design stance and implementation constraints → [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md); the release flow and the version-bump decision chain → [docs/PUBLISHING.md](docs/PUBLISHING.md); the maintainer's document map → [AGENTS.md](AGENTS.md).