dsh-usage-state 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# 更新日志（Changelog）
+
+所有对外可见的变更按版本记录于此。每条决策"为什么改"的来龙去脉见 [`docs/design-changelog.md`](docs/design-changelog.md)（修订记录）；发布与验证的操作记录见 [`docs/release.md`](docs/release.md)。
+
+格式参照 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)；版本号遵循语义化版本。`0.3.0` 起发布 npm（此前仅 GitHub 安装）。
+
+## [Unreleased]
+
+### 0.4.4（待发布）
+
+- **纯文档发布**：README 与实际行为对齐（SVG 进度环、输入框上方独立一行、版本清单补全），文档结构重组（架构 / 平台事实 / 发布 / 待办 / 设计修订各自成档）；`CHANGELOG.md` 自本版起随包发布。`lib/` 与 0.4.3 逐字节相同，无任何运行时变更。
+
+## [0.4.3] - 2026-10-05
+
+- **进度显示改为 SVG 圆环**：平台 `ContextMeter` 同款几何（14×14、r=5.5、2px 描边、12 点起弧），替代 `█`/`░` 文字条（其字形回落宽度不可控，见修订 21/23）。阈值变色经 `currentColor` 传导到环上；`display.progressBar` 配置键保留（关掉即隐藏环）。
+- **排版对齐平台统计行**：字号/行高照抄 `StatsPills` 的显式表达式（修订 22）。
+- **折行修复**：分隔符与它引导的段落同盒（`data-usage-part`），折行不再留下孤立的 `·`（修订 21）。
+- 数据模型：`StatusSegment.bar?: string` → `progress?: number`。
+
+## [0.4.2] — 2026-10-05
+
+- 状态行迁到 **`conversation.input.dock`**（输入框上方、与输入卡片同宽的独立一行，`order: 200`）。0.2 里 `conversation.composer.dock` 是与平台统计、上下文计量器共排的一排 pill，不存在"输入框之下"的整行位置（修订 20）。
+
+## [0.4.1] — 2026-10-05
+
+- **修复 0.4.0 读数全缺**：客户端 RPC contribution 的参数 codec 缺少 0.2 要求的 `create()` 工厂，`remote.usageState` 从未挂载，界面误报 `Mode not supported`（修订 18）。**0.4.0 用户必须升级。**
+- 挂载失败不再被静默吞掉（`console.error` + 写入 store）；catalog 未到时显示"读取中"而不是"模式不支持"。
+- dock 布局适配：与平台 `.pill` 同构，不再挤压/裁切平台统计（修订 19）。
+- 新增**真实 0.2 registry 契约测试**（源码与构建产物各一条，修订 18）。
+
+## [0.4.0] — 2026-10-05
+
+- **迁移到 DSH 0.2 原生设置模型**：宿主 `Config = z.any().volatile()` + `configForms` + `configEditor`；0.2 删除了 `settingsScope` / `settings.register`，两套 API 无重叠（修订 17）。`engines.dsh` 收紧为 `>=0.2.0-rc.2 <0.3.0-0`；0.1 线用户请停在 `0.3.2`。
+- `peerDependencies` 新增 `@deepseek-ai/dsh-settings`（让 0.1.x 宿主在**安装时**被运行时闸门拒绝，而不是装上后启动崩溃）与 `@deepseek-ai/schemastery`。
+- `cordis.patch.yml` 插入行补 `config: {}`，避免新装实例状态行沉默。
+- ⚠️ 本版有读数缺失缺陷（见 0.4.1）。
+
+## [0.3.2] — 2026-09-30
+
+- 仅放宽 `engines.dsh` 到 `>=0.1.5-rc.1 <0.3.0-0`；源码与产物零改动（修订 16）。
+- ⚠️ **0.1 线末版**。它声称的 0.2 兼容后来被真机推翻（0.2 删除了 `settingsScope`，装上会让 web 启动失败，修订 17）——0.2 宿主请装 `0.4.x`。
+
+## [0.3.1] — 2026-09-22
+
+- 移除 `peerDependencies.react`：浏览器半边的 React 由平台运行时注入，不走 node_modules，声明它只会产生 `missing peer` 警告（修订 15）。
+
+## [0.3.0] — 2026-09-22
+
+- **移除回合行**：账户级读数不能诚实地描述单个回合，`conversation.chat.*` 上的展示整体否决（修订 13；可行性实验见修订 8）。
+- 去掉 `private`，**首次发布 npm** 并被 dsh-market 收录（分类 `usage`，修订 14）；`engines.dsh` 随包声明（市场徽标与兼容判定读它）。
+
+## [0.2.3] — 2026-09-22
+
+- 设置页卡头部改两列网格：provider 名过长时只截断灰色的 id（悬停看全文），`↑ ↓ 模式` 控件永不换行（修订 12）。
+- README 增补对上游 `dsh-cost-meter` 的溯源致谢。
+
+## [0.2.2] — 2026-09-21
+
+- 三处健壮性修复；不再轮询已删除的 provider。
+
+## [0.2.1] — 2026-09-21
+
+- 修复"幽灵 provider 行"（已删除的 provider 仍出现在设置页）。
+
+## [0.2.0] — 2026-09-21
+
+- 新增数据源 **OpenCode Zen Go**（5h / 7d / 30d；修订 11）。通往同一账户的两条 DSH 路由按 `source:mode` 去重，只发一次请求。
+
+## [0.1.0] — 2026-09-21
+
+- 首版：数据源适配器框架 + DeepSeek / z.ai / Kimi / Sub2API 四家、composer 状态行（余额 / 5h·7d 已用百分比 + 倒计时 + 阈值变色）、设置页（provider 四态 + 排序 + 密钥写入）、凭据探测与直读兜底、Typert RPC 快照通道、中英双语、`node:test` 单测。
+
+[Unreleased]: https://github.com/takboo/dsh-usage-state/compare/0.4.3...HEAD
+[0.4.3]: https://github.com/takboo/dsh-usage-state/compare/0.4.2...0.4.3
+[0.4.2]: https://github.com/takboo/dsh-usage-state/compare/0.4.1...0.4.2
+[0.4.1]: https://github.com/takboo/dsh-usage-state/compare/0.4.0...0.4.1
+[0.4.0]: https://github.com/takboo/dsh-usage-state/compare/0.3.2...0.4.0
+[0.3.2]: https://github.com/takboo/dsh-usage-state/compare/0.3.1...0.3.2
+[0.3.1]: https://github.com/takboo/dsh-usage-state/compare/0.3.0...0.3.1
+[0.3.0]: https://github.com/takboo/dsh-usage-state/compare/0.2.3...0.3.0
+[0.2.3]: https://github.com/takboo/dsh-usage-state/compare/0.2.2...0.2.3
+[0.2.2]: https://github.com/takboo/dsh-usage-state/compare/0.2.1...0.2.2
+[0.2.1]: https://github.com/takboo/dsh-usage-state/compare/0.2.0...0.2.1
+[0.2.0]: https://github.com/takboo/dsh-usage-state/compare/0.1.0...0.2.0
+[0.1.0]: https://github.com/takboo/dsh-usage-state/releases/tag/0.1.0

package/README.en.md

@@ -5,7 +5,7 @@ See your **account balance** or **coding-plan quota** at a glance in [DSH (DeepS
 > 中文说明见 [README.md](README.md)。
 
 ```
-its own line above the composer input:   z.ai / GLM · 5h 12% (4h0m) ▓▓▓░░░░░ · 7d 59% (3d17h) ▓▓▓▓▓░░░
+its own line above the composer input:   z.ai / GLM · ◔ 5h 12% (4h0m) · ◔ 7d 59% (3d17h)
                              DeepSeek · ¥58.13
 hover any segment:           Source DeepSeek · Mode API balance · Granted 0 · Topped up 58.13
 ```
@@ -23,7 +23,7 @@ hover any segment:           Source DeepSeek · Mode API balance · Granted 0 ·
 ## Install
 
 **Requirements**: DSH `0.2.0-rc.2` or a later 0.2 release, Node ≥ 20, installed into the `web` profile. The package **ships the prebuilt `lib/`**, so installation has no build step.
-**On the 0.1 line install `0.3.2` instead**: DSH 0.2 replaced the whole settings API (`settingsScope` / `settings.register` → `configForms` / the plugin's own `Config`), and the two share no surface, so `0.4.0` and up support the 0.2 line only (see revision 17 of [`docs/design-consensus.md`](docs/design-consensus.md)).
+**On the 0.1 line install `0.3.2` instead**: DSH 0.2 replaced the whole settings API (`settingsScope` / `settings.register` → `configForms` / the plugin's own `Config`), and the two share no surface, so `0.4.0` and up support the 0.2 line only (see revision 17 of [`docs/design-changelog.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/design-changelog.md)).
 
 ```bash
 # 1) install (npm package)
@@ -49,7 +49,7 @@ dsh plugin --profile web add /path/to/dsh-usage-state
 
 It is also listed in [dsh-market](https://github.com/dsh-market/dsh-market): search for `usage state` (or `takboo`) and install it in one click — the plugin is on the [awesome-dsh-plugin](https://awesome-dsh-plugin.com) curated list under Usage & Billing.
 
-Nothing showing up after installing? See the troubleshooting table at the end of [`docs/adapters.md`](docs/adapters.md).
+Nothing showing up after installing? See the troubleshooting table at the end of [`docs/adapters.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/adapters.md).
 
 ## Quick start
 
@@ -87,12 +87,14 @@ Expanding **Advanced** lets you override the source and endpoint, name a credent
 
 - **z.ai is regional**: a coding-plan key only works on its own region (`open.bigmodel.cn` for China, `api.z.ai` globally). China is the default; the other host is tried as a mirror, and you can pin an endpoint in the settings.
 - **OpenCode Zen Go** reads `rolling` / `weekly` / `monthly` from `opencode.ai/zen/go/v1/usage`. Both DSH routes into the same account (built-in `opencode-go` and the custom `opencode-go-deepseek`) produce one reading and one request. A missing subscription or a rejected key is reported as an auth failure, never as 0%.
-- Other vendors (Claude Pro/Max, MiniMax, OpenRouter, Codex, Antigravity, Volcengine Ark, …) are not implemented, but the adapter contract and a candidate list are ready: see [`docs/adapters.md`](docs/adapters.md).
+- Other vendors (Claude Pro/Max, MiniMax, OpenRouter, Codex, Antigravity, Volcengine Ark, …) are not implemented, but the adapter contract and a candidate list are ready: see [`docs/adapters.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/adapters.md).
 
 ## Display, refresh, credentials
 
-- **Placement**: directly below the composer's stats row, aligned with the native row's geometry. The line is always visible — it never depends on hover or a click.
-- **Elements**: provider label · balance + currency · each window (5h / 7d / 30d) used % · reset countdown · mini progress ring · threshold colours (defaults: amber ≥80%, red ≥95%).
+- **Placement**: its own full-width line **above** the composer input, as wide as the input card (the `conversation.input.dock` slot on DSH 0.2). The line is always visible — it never depends on hover or a click — and wraps between segments on narrow windows instead of clipping.
+- **Elements**: provider label · balance + currency · each window (5h / 7d / 30d): an SVG progress ring + used % + reset countdown · threshold colours (defaults: amber ≥80%, red ≥95%, configurable; the colour applies to the whole segment and carries into the ring).
+
+The ring copies the geometry of the platform's own context meter (a 14×14 circle whose arc starts at twelve o'clock), replacing the earlier `█`/`░` text bar — a vector shape has no glyph metrics, so it cannot be inflated by font fallback; it can be turned off in the settings.
 - **Semantics**: percentages are always *used*; balances only appear in API mode, and coding-plan mode shows the windows the source actually has (5h / 7d for z.ai and Sub2API, plus 30d for OpenCode Zen Go); a stale reading shows its age instead of hiding.
 - **Refresh**: 2s after a turn ends, plus a 5-minute idle fallback; at most one real request per source per 60s, in-flight calls are shared, failures are not throttled.
 - **Credentials**: override → the provider's declared `apiKeyEnv` → the source's built-in ref → DSH credential store. Keys are written to `~/.dsh/.credentials.yaml`; **this plugin never stores a plaintext key** and the browser never receives a key value.
@@ -101,18 +103,21 @@ Expanding **Advanced** lets you override the source and endpoint, name a credent
 
 - **0.2 line only**: `engines.dsh` = `>=0.2.0-rc.2 <0.3.0-0` (this is what dsh-market's badge and install gate read). On an earlier host, install `0.3.2`.
 - `peerDependencies` carry `@deepseek-ai/dsh-settings` (`^0.2.0-rc.2`) and `@deepseek-ai/schemastery` (`^3.18.2`). The first one is deliberate: the runtime install gate only reads `@deepseek-ai/dsh*` peers, so declaring it makes a 0.1.x host **refuse the install** instead of accepting it and then failing to boot. Both are platform-provided; pnpm may print a `missing peer` warning for them, which is expected.
+- Version `0.4.4`: docs-only release — the README matches actual behaviour and `CHANGELOG.md` ships with the package; `lib/` is byte-identical to `0.4.3`.
+- Version `0.4.3`: progress becomes the **platform-style SVG ring** (replacing the `█`/`░` text bar, with threshold colours carried onto the ring), typography copied from the platform stats row, and wraps no longer leave an orphaned `·` (revisions 21–23).
 - Version `0.4.2` moves the status line to `conversation.input.dock`, giving it **its own line above the composer input** — DSH 0.2 turned the old below-the-input position into a shared row of pills next to the platform's stats and context meter (revisions 19/20).
 - Version `0.4.1` fixes `0.4.0`'s missing readings: the browser half's RPC contribution lacked the `create()` factory 0.2 requires, so `remote.usageState` never mounted — the UI showed **no readings at all** and mislabelled the cause as `Mode not supported`. The same release stops swallowing a rejected mount, says "reading" while the catalog is absent, and adds **real 0.2 registry contract tests** (revision 18). **Use `0.4.1`, not `0.4.0`.**
-- Version `0.4.0` migrates to the 0.2 settings model (`Config` + `configForms`, with cross-entry config read through `configEditor`). Verification and results: [`docs/implementation.md`](docs/implementation.md) §10; rationale: [`docs/design-consensus.md`](docs/design-consensus.md) revision 17.
+- Version `0.4.0` migrates to the 0.2 settings model (`Config` + `configForms`, with cross-entry config read through `configEditor`). Changes: [CHANGELOG](CHANGELOG.md); verification: [`docs/release.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/release.md); rationale: [`docs/design-changelog.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/design-changelog.md) revision 17.
 - Version `0.3.2` (last of the 0.1 line) only widened `engines.dsh`; **its claimed 0.2 compatibility was wrong** — on `0.2.0-rc.2` it fails the entire web boot because `settingsScope` does not exist there.
 - Published to npm as [`dsh-usage-state`](https://www.npmjs.com/package/dsh-usage-state); GitHub installs work too.
 
 ## Limitations
 
 - **Kimi and Sub2API are not verified against live accounts yet** (no credentials on the author's machine); their `/v1/usage` style endpoints are undocumented and parsed defensively.
+- **The threshold colours (amber/red) have no real-machine sample yet**: implemented and pinned by tests, but live readings have stayed below the thresholds; set the amber threshold to 10 temporarily to see them.
 - **Clicking the line does not open settings** (the platform exposes no public "open settings panel" service); details are in the hover tooltip.
 - **Current reading only**: the line reports the account's latest value. The plugin keeps no per-turn and no per-time history, so scrolling back through old turns shows no "balance at that moment". Account history, if ever added, would be keyed by time rather than by turn — a separate decision.
-- Full list: [`docs/implementation.md`](docs/implementation.md) §6.
+- Full list: [`docs/backlog.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/backlog.md).
 
 ## Development
 
@@ -152,15 +157,20 @@ Host-side changes need a DSH restart; client-side changes do not. The `lib/` out
 
 | Document | Contents |
 |---|---|
-| [`docs/implementation.md`](docs/implementation.md) | Implementation and verification overview: code map, decision → code → test → verification traceability, open items |
-| [`docs/adapters.md`](docs/adapters.md) | Adding a data source: contract, workflow, pitfalls, candidate vendors, troubleshooting |
-| [`docs/design-consensus.md`](docs/design-consensus.md) | Design consensus and its revision log (Chinese) |
-| [`docs/research/README.md`](docs/research/README.md) | Read-only research index (vendor APIs, the replaced plugin, DSH RPC contract) |
+| [CHANGELOG](CHANGELOG.md) | Changes per version |
+| [`docs/architecture.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/architecture.md) | Code map, decision → code → test → verification traceability (Chinese) |
+| [`docs/adapters.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/adapters.md) | Adding a data source: contract, workflow, pitfalls, troubleshooting (Chinese) |
+| [`docs/design-consensus.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/design-consensus.md) | The design as it currently stands (Chinese) |
+| [`docs/design-changelog.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/design-changelog.md) | Design revision log: every decision change with its reasoning (Chinese) |
+| [`docs/release.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/release.md) | Release process, end-to-end verification, acceptance checklist, market listing (Chinese) |
+| [`docs/platform-notes.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/platform-notes.md) | Measured facts about DSH platform behaviour (Chinese) |
+| [`docs/backlog.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/backlog.md) | Backlog, candidate data sources, explicit non-goals (Chinese) |
+| [`docs/research/README.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/research/README.md) | Read-only research index (vendor APIs, the replaced plugin, DSH RPC contract) |
 
 ## Acknowledgements
 
 - **[`dsh-cost-meter`](https://github.com/Han-1413141/dsh-cost-meter)** by Han-1413141 (MIT): this plugin is a **simplified replacement** for it. It keeps the "show me my balance / coding-plan quota" need and drops everything else — cost accounting, pricing catalog, history, budgets, peak/off-peak alerts.
-  The data-source endpoints, the meaning of the response fields and several compatibility pitfalls (OpenCode Zen Go needs a browser UA, z.ai reports auth failure as HTTP 200 + `{success:false}`, the legacy `coding_plan/usage` fallback, sub2api's `rate_limits[]` shape, …) come from a **read-only analysis** of `dsh-cost-meter@1.7.28`, recorded in [`docs/research/dsh-cost-meter-analysis.md`](docs/research/dsh-cost-meter-analysis.md). The implementation here is independently written TypeScript rather than copied source, but those behaviours are upstream's work and credit belongs there.
+  The data-source endpoints, the meaning of the response fields and several compatibility pitfalls (OpenCode Zen Go needs a browser UA, z.ai reports auth failure as HTTP 200 + `{success:false}`, the legacy `coding_plan/usage` fallback, sub2api's `rate_limits[]` shape, …) come from a **read-only analysis** of `dsh-cost-meter@1.7.28`, recorded in [`docs/research/dsh-cost-meter-analysis.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/research/dsh-cost-meter-analysis.md). The implementation here is independently written TypeScript rather than copied source, but those behaviours are upstream's work and credit belongs there.
   If the upstream author wants a clearer attribution or a different arrangement, open an issue and it will be fixed.
 - **[DSH (DeepSeek Harness)](https://github.com/deepseek-ai)**: the host platform. The plugin relies on its settings namespace, credential store, Typert RPC, slot system and UI primitives (`@deepseek-ai/dsh-client-ui-primitives` and friends).
 

package/README.md

@@ -4,10 +4,10 @@
 
 在 [DSH（DeepSeek Harness）](https://github.com/deepseek-ai) 里一眼看到你的**账户余额**或**套餐额度**——就在输入框上方、与输入卡片同宽的一行（原生统计行与其弹窗原样保留、不做替换）。
 
-> A minimal DSH plugin that shows your account **balance** (API mode) or **coding-plan quota** (5h / 7d / 30d) for the model you are using, right under the composer.
+> A minimal DSH plugin that shows your account **balance** (API mode) or **coding-plan quota** (5h / 7d / 30d) for the model you are using, on its own line right above the composer input.
 
 ```
-输入框上方独立一行：      z.ai / GLM · 5h 12% (4h0m) ▓▓▓░░░░░ · 7d 59% (3d17h) ▓▓▓▓▓░░░
+输入框上方独立一行：      z.ai / GLM · ◔ 5h 12% (4h0m) · ◔ 7d 59% (3d17h)
                         DeepSeek · ¥58.13
 悬停任意一段：          Source DeepSeek · Mode API balance · Granted 0 · Topped up 58.13
 ```
@@ -25,7 +25,7 @@
 ## 安装
 
 **前置条件**：DSH `0.2.0-rc.2` 或更新的 0.2 线、Node ≥ 20，装进 `web` profile。包内**自带预构建的 `lib/`**，安装时没有构建步骤。
-**用 0.1 线请装 `0.3.2`**：DSH 0.2 换掉了整套设置 API（`settingsScope` / `settings.register` → `configForms` / 插件自带 `Config`），两套 API 没有重叠，所以 `0.4.0` 起只支持 0.2 线（原因见 [`docs/design-consensus.md`](docs/design-consensus.md) 修订 17）。
+**用 0.1 线请装 `0.3.2`**：DSH 0.2 换掉了整套设置 API（`settingsScope` / `settings.register` → `configForms` / 插件自带 `Config`），两套 API 没有重叠，所以 `0.4.0` 起只支持 0.2 线（原因见 [`docs/design-changelog.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/design-changelog.md) 修订 17）。
 
 ```bash
 # 1) 安装（npm 包）
@@ -51,7 +51,7 @@ dsh plugin --profile web add /path/to/dsh-usage-state
 
 也可以在 [dsh-market](https://github.com/dsh-market/dsh-market) 里搜索 `usage state`（或 `takboo`）一键安装——本插件已收录在精选列表 [awesome-dsh-plugin](https://awesome-dsh-plugin.com) 的「用量与计费」分类。
 
-装好后界面没有出现？见 [`docs/adapters.md`](docs/adapters.md) 末尾的排查表。
+装好后界面没有出现？见 [`docs/adapters.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/adapters.md) 末尾的排查表。
 
 ## 快速开始
 
@@ -89,13 +89,15 @@ dsh plugin --profile web add /path/to/dsh-usage-state
 
 - **z.ai 分区域**：coding plan 的 key 只在自己区域的站点有效（国内 `open.bigmodel.cn` / 国际 `api.z.ai`）。默认国内站，失败时自动镜像重试；也可在设置里钉死端点。
 - **OpenCode Zen Go**：读 `opencode.ai/zen/go/v1/usage` 的 `rolling` / `weekly` / `monthly`；通往同一账户的两条 DSH 路由（内置 `opencode-go` 与自定义 `opencode-go-deepseek`）只产生一个读数、只发一次请求。无订阅或密钥无效时报鉴权失败，而非 0%。
-- **其他厂商**（Claude Pro/Max、MiniMax、OpenRouter、Codex、Antigravity、Volcengine Ark…）未实现，但适配器契约与候选清单已备好，见 [`docs/adapters.md`](docs/adapters.md)。
+- **其他厂商**（Claude Pro/Max、MiniMax、OpenRouter、Codex、Antigravity、Volcengine Ark…）未实现，但适配器契约与候选清单已备好，见 [`docs/adapters.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/adapters.md)。
 
 ## 显示与交互
 
-**位置**：输入框统计行的正下方（与原生统计行的几何对齐，跟随 DSH 的会话内容宽度）。读数**始终可见**，不依赖悬停，也不需要点击。
+**位置**：输入框**上方**、与输入卡片同宽的独立一行（DSH 0.2 的 `conversation.input.dock` 槽位）。读数**始终可见**，不依赖悬停，也不需要点击；窗口过窄时在段与段之间折行，不会裁切。
 
-**元素**：供应商标签 · 余额金额 + 币种 · 各窗口（5h / 7d / 30d）已用百分比 · 重置倒计时 · 迷你进度环 · 阈值变色（默认 ≥80% 黄、≥95% 红，可在设置里改）。
+**元素**：供应商标签 · 余额金额 + 币种 · 各窗口（5h / 7d / 30d）：SVG 进度环 + 已用百分比 + 重置倒计时 · 阈值变色（默认 ≥80% 琥珀、≥95% 红，可在设置里改；颜色作用于整段并传导到圆环）。
+
+进度环取平台上下文计量器（`ContextMeter`）同款几何（14×14 圆环、弧从 12 点开始），替代早期的 `█`/`░` 文字条——矢量没有字形度量，不会因字体回落而撑爆排版；设置里可整体关闭。
 
 **口径**：百分比一律是**已用**（与 z.ai / Claude 官方一致）；API 模式显示余额，Coding Plan 模式显示该数据源实际提供的窗口（z.ai 与 Sub2API 是 5h / 7d，OpenCode Zen Go 多一个 30d）。
 
@@ -125,18 +127,21 @@ dsh plugin --profile web add /path/to/dsh-usage-state
 
 - **只支持 DSH 0.2 线**：`engines.dsh` = `>=0.2.0-rc.2 <0.3.0-0`（市场读它做徽标与"可安装"判定）。0.2 之前的宿主请装 `0.3.2`。
 - `peerDependencies` 里有 `@deepseek-ai/dsh-settings`（`^0.2.0-rc.2`）与 `@deepseek-ai/schemastery`（`^3.18.2`）：前者是**故意的**——平台的运行时安装闸门只读 `@deepseek-ai/dsh*` 的 peer，声明它可以让 0.1.x 宿主在**安装时**就拒绝，而不是装上之后把启动搞崩；两者都由平台提供，pnpm 可能为此打一行 `missing peer` 警告，属预期。
+- 版本 `0.4.4`：纯文档发布——README 与实际行为对齐、`CHANGELOG.md` 随包发布；`lib/` 与 `0.4.3` 逐字节相同。
+- 版本 `0.4.3`：进度显示改为**平台同款 SVG 圆环**（替代 `█`/`░` 文字条，阈值变色经颜色传导到环上）、排版照抄平台统计行字号、折行不再留下孤立的 `·`（修订 21–23）。
 - 版本 `0.4.2`：状态行迁到 `conversation.input.dock`，成为**输入框上方的独立一行**（0.1 时代它在输入框之下，而 0.2 把那个位置改成了与平台统计、上下文计量器共排的一排 pill——见修订 19/20）。
 - 版本 `0.4.1`：修 `0.4.0` 的读数缺失——客户端 RPC contribution 的参数 codec 少了 0.2 要求的 `create()`，`remote.usageState` 因此从未挂载，界面表现为**没有任何读数**并误报 `Mode not supported`。同一轮还让挂载失败不再被静默吞掉、catalog 未到时改说「读取中」，并把**真实 0.2 registry 契约测试**写进单测（修订 18）。**请用 `0.4.1`，不要用 `0.4.0`。**
-- 版本 `0.4.0`：迁到 0.2 原生设置模型（`Config` + `configForms`，宿主侧 `configEditor` 读跨条目配置）。验证方式与结论见 [`docs/implementation.md`](docs/implementation.md) §10、决策见 [`docs/design-consensus.md`](docs/design-consensus.md) 修订 17。
+- 版本 `0.4.0`：迁到 0.2 原生设置模型（`Config` + `configForms`，宿主侧 `configEditor` 读跨条目配置）。变更明细见 [CHANGELOG](CHANGELOG.md)，验证方式与结论见 [`docs/release.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/release.md)、决策见 [`docs/design-changelog.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/design-changelog.md) 修订 17。
 - 版本 `0.3.2`（0.1 线末版）：仅放宽 `engines.dsh`；**它声称的 0.2 兼容是错的**（0.3.2 在 0.2.0-rc.2 上会因 `settingsScope` 不存在而让整个 web 启动失败）。
 - 同名发布在 npm（[`dsh-usage-state`](https://www.npmjs.com/package/dsh-usage-state)），也可从 GitHub 直接安装。
 
 ## 已知限制
 
 - **Kimi、Sub2API 未经真机验证**（本机无凭据），代码与单测已就绪；Sub2API 的 `/v1/usage` 属未文档化接口，已按易错接口做容错。
+- **阈值变色（琥珀/红）尚无真机视觉样本**：代码已实现且被单测钉住，但真机读数长期低于阈值；把设置里黄色阈值临时改成 10 即可确认。
 - **点击状态行不会打开设置**（客户端没有公开的"打开设置面板"服务）；细节通过悬浮提示呈现。
 - **只在输入框上方展示，不覆盖历史**：状态行给出的是账户**当前**读数；插件不按回合、也不按时间保存历史读数，因此翻看旧回合时看不到"当时的余额"。若将来要做，会是以时间轴（而不是回合）为口径的单独决定。
-- 完整清单见 [`docs/implementation.md`](docs/implementation.md) §6。
+- 完整清单见 [`docs/backlog.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/backlog.md)。
 
 ## 开发
 
@@ -184,15 +189,20 @@ tests/           与 src 对应；tests/build 校验的是产物本身
 
 | 文档 | 内容 |
 |---|---|
-| [`docs/implementation.md`](docs/implementation.md) | 实现与验证总览：代码地图、决策→实现→测试→验证追溯、未验证清单、平台注意事项 |
-| [`docs/adapters.md`](docs/adapters.md) | 添加数据源：契约、四步流程、约定与坑、候选厂商、排查表 |
-| [`docs/design-consensus.md`](docs/design-consensus.md) | 设计共识与修订记录（每条决策的来龙去脉） |
-| [`docs/research/README.md`](docs/research/README.md) | 只读侦察报告索引（各厂商接口、被替代插件剖析、DSH RPC 契约） |
+| [CHANGELOG](CHANGELOG.md) | 按版本的变更记录 |
+| [`docs/architecture.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/architecture.md) | 代码地图、决策→实现→测试→验证追溯 |
+| [`docs/adapters.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/adapters.md) | 添加数据源：契约、四步流程、约定与坑、排查表 |
+| [`docs/design-consensus.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/design-consensus.md) | 当前有效的设计共识 |
+| [`docs/design-changelog.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/design-changelog.md) | 设计修订记录（每条决策变更的来龙去脉） |
+| [`docs/release.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/release.md) | 发布流程、端到端验证、人工验收清单、市场收录 |
+| [`docs/platform-notes.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/platform-notes.md) | DSH 平台行为的实测事实 |
+| [`docs/backlog.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/backlog.md) | 待办、候选数据源、明确不做的否决护栏 |
+| [`docs/research/README.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/research/README.md) | 只读侦察报告索引（各厂商接口、被替代插件剖析、DSH RPC 契约） |
 
 ## 致谢与参考
 
 - **[`dsh-cost-meter`](https://github.com/Han-1413141/dsh-cost-meter)**（作者 Han-1413141，MIT 许可）：本插件是它的**简化替代品**——只保留「看余额 / 看 Coding Plan 额度」这个展示需求，砍掉计费、价格目录、历史账单、预算与峰谷提醒等全部逻辑（见上面的「只做显示」）。
-  数据源端点、响应字段语义与若干兼容陷阱（OpenCode Zen Go 必须带浏览器 UA、z.ai 用 HTTP 200 + `{success:false}` 表达鉴权失败、旧 `coding_plan/usage` 兜底路径、sub2api 的 `rate_limits[]` 形态等）来自对 `dsh-cost-meter@1.7.28` 的**只读分析**，记录见 [`docs/research/dsh-cost-meter-analysis.md`](docs/research/dsh-cost-meter-analysis.md)。本仓库的实现是独立编写的 TypeScript，不是对其源码的照搬；但那些行为语义确实源自上述分析，应归功于上游。
+  数据源端点、响应字段语义与若干兼容陷阱（OpenCode Zen Go 必须带浏览器 UA、z.ai 用 HTTP 200 + `{success:false}` 表达鉴权失败、旧 `coding_plan/usage` 兜底路径、sub2api 的 `rate_limits[]` 形态等）来自对 `dsh-cost-meter@1.7.28` 的**只读分析**，记录见 [`docs/research/dsh-cost-meter-analysis.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/research/dsh-cost-meter-analysis.md)。本仓库的实现是独立编写的 TypeScript，不是对其源码的照搬；但那些行为语义确实源自上述分析，应归功于上游。
   若上游作者认为某处需要更明确的署名或授权，请提 issue，我会立刻调整。
 - **[DSH（DeepSeek Harness）](https://github.com/deepseek-ai)**：宿主平台。插件使用它的设置命名空间、凭据库、Typert RPC、插槽系统与 UI 原语（`@deepseek-ai/dsh-client-ui-primitives` 等）。
 

package/docs/adapters.md

@@ -68,25 +68,9 @@ export interface UsageSource {
 | OpenCode Zen Go | Coding Plan | `GET https://opencode.ai/zen/go/v1/usage` | **必须带浏览器 UA**（否则 Cloudflare error 1010 → 403，实测）。根对象是 `usage.{rolling,weekly,monthly}`（文档写作 `data.usage`，两种都接受），字段 `percent` 已是 0..100 已用百分比（用 `clampPercent`，**不要**用 `normalizePercent`，否则 `1` 会变成 100%），`resetsAt` 是 ISO 串。窗口名 `rolling/weekly/monthly` → 规范键 `5h/7d/30d`。401/403 = 无订阅或密钥无效（**不是** 0%）。`resolveProvider` 会把 provider 声明的 `baseURL` 归一成 origin、`normalizeBaseUrl` 会剥掉尾部 `/vN`，所以请求前还要再剥掉 `/zen/go` 尾段，否则出现 `/zen/go/zen/go/v1/usage` |
 | Sub2API（自建） | API + Coding Plan | `GET {base}/v1/usage` | 未文档化的内部接口，字段曾出现前后端漂移；所有字段可选、未知结构降级。一个接口覆盖两种模式：`quota.remaining` 或钱包 `balance` 视为 USD 余额，`rate_limits[]` 的 `window` 直接是 `5h`/`1d`/`7d`（美元计价，百分比自算 `used/limit`）。`requiresBaseUrl: true` |
 
-## 候选数据源（未实现）
+## 候选数据源
 
-以下接口已侦察确认存在（详见 `docs/research/provider-balance-quota-apis.md`），但都**不适合 v1 的凭据模型**（本插件只支持环境变量风格字符串密钥，经 DSH 凭据库存取）：
-
-| 厂商 | 端点 | 为什么还没做 |
-|---|---|---|
-| Anthropic Claude Pro/Max | `GET https://api.anthropic.com/api/oauth/usage` | 必须 OAuth 访问令牌（`user:profile`），普通 API key 无法调用；需要新增 OAuth 凭据的存取通道。返回 `five_hour` / `seven_day` 的 `utilization` + `resets_at`，是最标准的 5h/7d 形态 |
-| Codex / ChatGPT 订阅 | `GET https://chatgpt.com/backend-api/wham/usage` | 需要 ChatGPT OAuth；`rate_limit.primary_window`（18000s）与 `secondary_window`（604800s） |
-| MiniMax Token Plan | `GET https://www.minimaxi.com/v1/token_plan/remains` | 纯 API key，**可以**按本模板实现：`current_interval_remaining_percent` / `current_weekly_remaining_percent`（注意是"剩余"，要反转） |
-| Kimi Code 国际版 | `GET https://api.kimi.com/coding/v1/usages` | 与已实现的国内版同端点，无需新增 |
-| OpenRouter | `GET {base}/api/v1/credits`、`/api/v1/key` | 余额接口按官方 OpenAPI 需要 management key；`/key` 的 `limit_remaining/limit` 可换算已用 %，但无 5h/7d 概念 |
-| SiliconFlow | `GET https://api.siliconflow.cn/v1/user/info` | 纯 CNY 余额，可照模板实现 |
-| CommandCode | `GET https://api.commandcode.ai/alpha/billing/credits` | 返回 `windowLimits.{fiveHour,weekly}.{used,cap,resetAt}`，形态与我们的窗口模型几乎一致 |
-| Volcengine Ark Coding Plan | `open.volcengineapi.com` 控制面 | 需要 AK/SK HMAC 签名，凭据形态超出 v1 |
-| Gemini Code Assist / Antigravity | 私有端点 / 本地语言服务 | OAuth 或本地进程通信，且 Google 已关闭个人版 CLI OAuth |
-
-> OpenCode Zen 已实现（见上表），不再是候选；它只差一个 `user-agent` 就能直连，不需要 OAuth。
-
-**优先级建议**：MiniMax → CommandCode → SiliconFlow（都是纯 API key、返回结构简单），再考虑为 Anthropic / Codex 增加 OAuth 凭据通道。
+以下接口已侦察确认存在但**尚未实现**——候选清单、各家的"为什么还没做"与优先级建议统一维护在 [`backlog.md`](backlog.md) §3，此处不重复。新增适配器前先读它，再回到上面的「加一个适配器的步骤」。
 
 ## 排查
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-usage-state",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "type": "module",
   "description": "DSH plugin: show account balance (API mode) or coding-plan quota (5h/7d/30d) for the model in use",
   "license": "MIT",
@@ -74,6 +74,7 @@
     "README.md",
     "README.en.md",
     "LICENSE",
+    "CHANGELOG.md",
     "docs/adapters.md"
   ],
   "keywords": [