dsh-usage-state 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -1,85 +1,118 @@
 # 更新日志（Changelog）
 
-所有对外可见的变更按版本记录于此。每条决策"为什么改"的来龙去脉见 [`docs/design-changelog.md`](docs/design-changelog.md)（修订记录）；发布与验证的操作记录见 [`docs/release.md`](docs/release.md)。
+用户可见的变更按版本记录于此。设计取舍见 [设计修订](https://github.com/takboo/dsh-usage-state/blob/main/docs/design-changelog.md)，发布验证流程见 [发布与验收](https://github.com/takboo/dsh-usage-state/blob/main/docs/release.md)。
 
-格式参照 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)；版本号遵循语义化版本。`0.3.0` 起发布 npm（此前仅 GitHub 安装）。
+格式参照 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循语义化版本。0.3.0起发布npm，之前仅GitHub分发。已发布日期按 [npm registry](https://registry.npmjs.org/dsh-usage-state) 的UTC记录；历史比较引用说明见文末。
 
 ## [Unreleased]
 
-### 0.4.4（待发布）
+## [0.4.5] - 2026-10-10
 
-- **纯文档发布**：README 与实际行为对齐（SVG 进度环、输入框上方独立一行、版本清单补全），文档结构重组（架构 / 平台事实 / 发布 / 待办 / 设计修订各自成档）；`CHANGELOG.md` 自本版起随包发布。`lib/` 与 0.4.3 逐字节相同，无任何运行时变更。
+### Fixed
+
+- provider级凭据覆盖贯通读取、描述和保存；显式provider端点/ref优先于legacy source默认，固定端点不尝试镜像。
+- Moonshot余额按官方人民币元解析；DeepSeek跳过非法金额，无有效读数时报parse并保留同身份旧成功值；响应体超时/中断归network。
+- 宿主按有效目标签名、私有凭据摘要和generation隔离缓存/在途；拒绝配置切换、ABA、晚lookup和晚HTTP的旧结果，目标移除及stop不再触发后续查询。已解析密钥的原文回显在快照错误边界精确替换。
+- legacy models仅通过normalize迁移，权威空provider目录停止轮询；普通getState只初始化缺失/变更身份，浏览器30s轮询不缩短5min宿主idle，间隔修改会重调timer。
+- origin-only endpointHints传到设置页和状态行；默认provider按可见顺序排序；旧值tooltip含原因，RPC断线标年龄/陈旧。客户端配置身份失效后拒绝旧RPC，普通请求中的显式刷新排一次，已有force则共享。
+- 配置写入false/rejection、凭据保存/清除失败与pending均有反馈；配置只读和凭据权限分开，未编辑输入框失焦不写回旧草稿。
+
+### Engineering
+
+- 新增标准Ubuntu CI、Dependabot和默认verify的手动Release；action固定完整SHA，npm OIDC与GitHub附档分离权限，复用同一已验证tarball和checksum。
+- 修复Release在job级env使用runner.temp导致整份工作流无法解析的问题，tarball路径改在runner步骤中设置；CI新增固定版本/checksum的actionlint检查表达式上下文。
+- Dependabot保留React18与TypeScript JavaScript编译API兼容线，忽略这些依赖的自动major更新；纳入tsdown0.23.0、unrun0.3.1和Zod4.6.5。Zod测试验证固定v4依赖及真实codec行为，不再要求旧补丁号4.5.1。
+- 新增metadata、已提交产物、实际tarball、稳定发布tag和预构建runtime门禁；必要产物缺失改为硬失败，不再skip。规范工具链固定Node24.21.0/npm11.19.1，锁文件根版本同步包版本。
+- schemastery peer/dev下界更正为3.18.3（3.18.2缺少volatile能力），锁定解析版本3.18.4；没有扩大DSH发布线范围。
+- 版本升至0.4.5，交付此前Unreleased整改；新增稳定版本tag自动派发可信main上的Release，手动触发仍默认verify。npm经OIDC发布同一已验证tarball，GitHub Release附相同字节与checksum。
+
+### Documentation
+
+- 精简中英README，增加任务导航、领域术语、开发指南和用户排查；明确0.4.5包含整改，0.4.4及更早版本仍有旧版问题。
+- 双语README增加CI/npm状态徽章，恢复修复版npm安装指引并记录0.4.5版本说明。
+- 设计、架构、适配器、平台和发布文档同步本地实现及验证边界；A01–A17状态归入唯一Backlog，历史研究与修订1–24保留。
+- 0.4.4发布日期和历史提交引用已校正；真实账户、视觉及实际凭据写入验证仍未新增。
+
+## [0.4.4] - 2026-10-06
+
+- 更新README中的SVG进度环、输入框上方独立行和版本导航文案，拆分维护文档的职责。
+- CHANGELOG自本版起随npm包发布；预构建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`。
+- **进度显示改为SVG圆环**：平台ContextMeter同款几何（14×14、r=5.5、2px描边、12点起弧），替代文字条（字形回落问题见修订21/23）。阈值变色经currentColor传导到环，沿用display.progressBar配置键。
+- 字号/行高照抄平台统计行的显式表达式（修订22）。
+- 分隔符与它引导的段落同盒，折行不再留下孤立的分隔符（修订21）。
+- 显示模型从文字bar改为数值progress。
+
+## [0.4.2] - 2026-10-05
+
+- 状态行迁到conversation.input.dock，位于输入框上方、与输入卡片同宽、order=200；保留原生统计行（修订20）。
+- 此前GitHub开发阶段对共享dock的适配记录在修订19，最终随本版迁为上方独立行；不把该后续提交误列为npm0.4.1已发布内容。
 
-## [0.4.2] — 2026-10-05
+## [0.4.1] - 2026-10-05
 
-- 状态行迁到 **`conversation.input.dock`**（输入框上方、与输入卡片同宽的独立一行，`order: 200`）。0.2 里 `conversation.composer.dock` 是与平台统计、上下文计量器共排的一排 pill，不存在"输入框之下"的整行位置（修订 20）。
+- **修复0.4.0读数全缺**：客户端RPC贡献参数codec缺少0.2要求的create()，remote.usageState未挂载，界面误报Mode not supported（修订18）。0.4.0用户应升级至最新兼容版。
+- 挂载失败记录console.error和store错误；catalog未到时显示读取中。
+- 新增真实0.2 registry契约测试，源码与构建产物各一条。
 
-## [0.4.1] — 2026-10-05
+## [0.4.0] - 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）。
+- 迁移到DSH0.2的Config/configForms/configEditor设置模型；旧settingsScope/settings.register已移除（修订17）。支持范围收紧为 `>=0.2.0-rc.2 <0.3.0-0`。
+- 新增dsh-settings与schemastery peer声明，并在patch中提供config:{}。
+- 本版仍有客户端RPC挂载缺陷，随后由0.4.1修复。
 
-## [0.4.0] — 2026-10-05
+## [0.3.2] - 2026-09-30
 
-- **迁移到 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）。
+- 仅放宽engines.dsh，源码与产物未改（修订16）。
+- 0.1线末版；声称的0.2兼容后来被真机推翻。DSH0.2不能使用本版，需最新兼容0.4系列。
 
-## [0.3.2] — 2026-09-30
+## [0.3.1] - 2026-09-22
 
-- 仅放宽 `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`。
+- 移除React runtime peer，浏览器React由平台模块表提供；React仍作开发依赖（修订15）。
 
-## [0.3.1] — 2026-09-22
+## [0.3.0] - 2026-09-22
 
-- 移除 `peerDependencies.react`：浏览器半边的 React 由平台运行时注入，不走 node_modules，声明它只会产生 `missing peer` 警告（修订 15）。
+- 移除回合行，账户当前读数只在输入区域显示（修订13）。
+- 首次发布npm，去掉private并声明engines.dsh；进入dsh-market收录链路（修订14）。
 
-## [0.3.0] — 2026-09-22
+## [0.2.3] - 2026-09-22
 
-- **移除回合行**：账户级读数不能诚实地描述单个回合，`conversation.chat.*` 上的展示整体否决（修订 13；可行性实验见修订 8）。
-- 去掉 `private`，**首次发布 npm** 并被 dsh-market 收录（分类 `usage`，修订 14）；`engines.dsh` 随包声明（市场徽标与兼容判定读它）。
+- 设置页头部改两列网格，长provider名截断，不挤走控件（修订12）。
+- README补充上游行为参考与致谢。
 
-## [0.2.3] — 2026-09-22
+## [0.2.2] - 2026-09-21
 
-- 设置页卡头部改两列网格：provider 名过长时只截断灰色的 id（悬停看全文），`↑ ↓ 模式` 控件永不换行（修订 12）。
-- README 增补对上游 `dsh-cost-meter` 的溯源致谢。
+- 三处健壮性修复，宿主不再轮询已删provider。
 
-## [0.2.2] — 2026-09-21
+## [0.2.1] - 2026-09-21
 
-- 三处健壮性修复；不再轮询已删除的 provider。
+- 修复已删provider仍留在设置页的幽灵行。
 
-## [0.2.1] — 2026-09-21
+## [0.2.0] - 2026-09-21
 
-- 修复"幽灵 provider 行"（已删除的 provider 仍出现在设置页）。
+- 新增OpenCode Zen Go来源，5h/7d/30d；同源模式合并路由（修订11）。
 
-## [0.2.0] — 2026-09-21
+## 0.1.0 - 2026-09-21
 
-- 新增数据源 **OpenCode Zen Go**（5h / 7d / 30d；修订 11）。通往同一账户的两条 DSH 路由按 `source:mode` 去重，只发一次请求。
+- 首版：四家适配器、宿主缓存/RPC、输入区域状态行、provider配置与中英UI。
+- 首版完整发布提交尚未确认，不链接不存在的版本标签。
 
-## [0.1.0] — 2026-09-21
+## 历史引用说明
 
-- 首版：数据源适配器框架 + DeepSeek / z.ai / Kimi / Sub2API 四家、composer 状态行（余额 / 5h·7d 已用百分比 + 倒计时 + 阈值变色）、设置页（provider 四态 + 排序 + 密钥写入）、凭据探测与直读兜底、Typert RPC 快照通道、中英双语、`node:test` 单测。
+0.4.5起建立版本tag/Release；更早发布没有保存这些引用。0.3.0至0.4.4的比较端点来自各npm版本的gitHead；0.2系列引用对应实现提交，不能替代当时没有保存的正式发布产物。早期日期沿用历史版本记录。今后版本应按发布流程建立稳定引用。
 
-[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
+[Unreleased]: https://github.com/takboo/dsh-usage-state/compare/v0.4.5...HEAD
+[0.4.5]: https://github.com/takboo/dsh-usage-state/compare/3ad9a71e2f7e4b9a05c69bc529e396a364ae6aeb...v0.4.5
+[0.4.4]: https://github.com/takboo/dsh-usage-state/compare/885541638ffa4da05b39bd1864085ba6d9acc288...3ad9a71e2f7e4b9a05c69bc529e396a364ae6aeb
+[0.4.3]: https://github.com/takboo/dsh-usage-state/compare/0d2d4376d0db990fb36df5d6124e5b7894974d62...885541638ffa4da05b39bd1864085ba6d9acc288
+[0.4.2]: https://github.com/takboo/dsh-usage-state/compare/e5ef97375d01faf9073ef5e4c7522f6ff59514f9...0d2d4376d0db990fb36df5d6124e5b7894974d62
+[0.4.1]: https://github.com/takboo/dsh-usage-state/compare/d93e2c7cdbbba76346d753171b2a4c8408793fc2...e5ef97375d01faf9073ef5e4c7522f6ff59514f9
+[0.4.0]: https://github.com/takboo/dsh-usage-state/compare/d9e08c8765ff89b9dc57b8ac56ee4c61412176d6...d93e2c7cdbbba76346d753171b2a4c8408793fc2
+[0.3.2]: https://github.com/takboo/dsh-usage-state/compare/9f8b863339ebf552478e48c93cc80641f5e2ecb5...d9e08c8765ff89b9dc57b8ac56ee4c61412176d6
+[0.3.1]: https://github.com/takboo/dsh-usage-state/compare/098a31c5b01c600a42ce5bc86d51627ec97b2b16...9f8b863339ebf552478e48c93cc80641f5e2ecb5
+[0.3.0]: https://github.com/takboo/dsh-usage-state/compare/dd37b3d...098a31c5b01c600a42ce5bc86d51627ec97b2b16
+[0.2.3]: https://github.com/takboo/dsh-usage-state/compare/7adb90e...dd37b3d
+[0.2.2]: https://github.com/takboo/dsh-usage-state/compare/e4d40d7...7adb90e
+[0.2.1]: https://github.com/takboo/dsh-usage-state/compare/c01a64f...e4d40d7
+[0.2.0]: https://github.com/takboo/dsh-usage-state/commit/c01a64f

package/README.en.md

@@ -1,179 +1,112 @@
 # dsh-usage-state
 
-See your **account balance** or **coding-plan quota** at a glance in [DSH (DeepSeek Harness)](https://github.com/deepseek-ai) — on its own line above the composer input, as wide as the input card.
+[中文](README.md) | **English**
 
-> 中文说明见 [README.md](README.md)。
+[![CI](https://github.com/takboo/dsh-usage-state/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/takboo/dsh-usage-state/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/dsh-usage-state)](https://www.npmjs.com/package/dsh-usage-state)
 
-```
-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
+> **Version note:** **0.4.5** includes the balance parsing, credential override, cache isolation and failure-display fixes previously recorded as Unreleased. See the [Changelog](CHANGELOG.md#045---2026-10-10). Users of 0.4.4 or earlier should upgrade to 0.4.5 or a newer compatible version.
+
+Show the current model provider's **account balance** or **coding-plan quota** above the composer input in [DSH (DeepSeek Harness)](https://github.com/deepseek-ai/deepseek-harness). The line matches the input card's width and preserves the native statistics and context meter.
+
+```text
+z.ai / GLM · ◔ 5h 12% (4h0m) · ◔ 7d 59% (3d17h)
+DeepSeek · ¥58.13
 ```
 
 ## Features
 
-- **Works with zero configuration**: the plugin figures out which data source and mode a provider needs, and reuses the API key DSH already has.
-- **Configured per provider, not per model** — readings are account-level, so each provider gets one setting: `Auto` / `API` / `Coding Plan` / `Hidden`. The model list is informational.
-- **One line, always visible**: its own line above the composer input (DSH 0.2 mounts it at `conversation.input.dock`, width-matched to the input card; the native stats row and context meter are left untouched, not replaced) — no hover, no click.
-- **Never invents data**: a failed refresh keeps the last good value and marks it stale (`12m ago ⚠`); rejected keys, endpoint errors and network problems each get a readable reason.
-- **Hover details**: source and mode, the window's absolute reset time, the granted/topped-up split of a balance, the failure reason with the provider's own message.
-- **Bilingual** (zh / en), following the DSH locale setting.
-- **Display only**: balances and quotas, nothing else — no cost accounting, pricing catalog, history or budgets.
+- Recognized providers default to Auto and reuse existing DSH credentials. Configuration is per provider; the model list is informational.
+- Balances, used percentages, reset countdowns and SVG rings, with configurable amber/red thresholds (80%/95% by default) and an option to hide rings.
+- A failed source request keeps the last successful reading for the same effective account identity, with its age and reason. An RPC failure also marks retained values as stale.
+- Hover details include source, mode, reset time and balance components. The UI follows DSH's Chinese/English language setting.
+- Current account readings only: no cost attribution, price catalog, budgets or historical bills.
 
 ## 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-changelog.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/design-changelog.md)).
+Requires DSH matching `>=0.2.0-rc.2 <0.3.0-0`. The prebuilt plugin declares Node ≥20. Install into the `web` profile you actually use.
+
+Install from npm:
 
 ```bash
-# 1) install (npm package)
 dsh plugin --profile web add dsh-usage-state
-
-# 2) restart DSH — the plugin's bundle patch is read at startup
-
-# 3) remove
-dsh plugin --profile web remove dsh-usage-state
+# Restart DSH afterwards: the bundle patch is read at startup.
 ```
 
-Installing straight from GitHub works too (same content as the npm package):
+You can also install from GitHub:
 
 ```bash
 dsh plugin --profile web add github:takboo/dsh-usage-state
 ```
 
-For development, a local path works too (host-side changes still need a DSH restart):
-
-```bash
-dsh plugin --profile web add /path/to/dsh-usage-state
-```
+This repository commits prebuilt artifacts for DSH's GitHub installation path. A floating Git branch may be ahead of npm; record the source and version/commit when reproducing an issue. This does not describe every npm Git installation's lifecycle.
 
-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.
+You can also search for `usage state` or `takboo` in [dsh-market](https://github.com/dsh-market/dsh-market); check the actual installation source and version afterwards. The plugin is on the [curated list](https://awesome-dsh-plugin.com); catalog visibility depends on the selected region and a successful catalog build.
 
-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).
+Use historical version 0.3.2 on DSH 0.1; it does not work on 0.2. Version 0.4.0 has a broken RPC mount, so upgrade to the **latest compatible release**. See the [Changelog](CHANGELOG.md) for version history.
 
 ## Quick start
 
-1. Open **Settings → Usage state**: one row per provider configured in DSH.
-2. Leave it on **Auto** (it detects the data source and its primary mode), or pick `API` / `Coding Plan` / `Hidden`; use ↑↓ to reorder.
-3. The reading appears on its own line above the composer input, as wide as the input card.
-
-If a source needs an endpoint or a key (a self-hosted Sub2API, or a provider without a credential yet), expand that row's **Advanced** block to override the source, set the endpoint, name the credential, or paste a key (written to the DSH credential store).
-
-A very long provider name never pushes the controls around: the card header stays on one line and only the grey provider id is truncated (hover it for the full text).
-
-## Screenshots
-
-The reading on its own line above the composer (shown here with OpenCode Zen Go's three windows; the row under the card is DSH's own statistics, untouched by this plugin — hover any segment for source, mode and the absolute reset time):
+1. Open **Settings → Usage state** to inspect providers, models and the detected source.
+2. Keep Auto for recognized providers, or choose a supported API, Coding Plan or Hidden option.
+3. Set your instance URL for a self-hosted Sub2API source. The current model's reading appears above the input.
+4. Use Refresh now for an explicit query. Check the settings error and the [troubleshooting guide (Chinese)](https://github.com/takboo/dsh-usage-state/blob/main/docs/troubleshooting.md) if it fails.
 
-![The reading on its own line above the composer](https://raw.githubusercontent.com/takboo/dsh-usage-state/main/assets/screenshots/status-line.webp)
+Advanced controls offer source, endpoint, credential name and key writes. Explicit provider overrides take precedence over legacy source defaults. Descriptions and requests share the candidate order; saves prioritize the explicit ref. Pinned endpoints do not try mirrors, and account configuration/key changes discard previous-identity readings. Configuration and credential write permissions are separate; saves/clears report failure and prevent repeated in-flight operations.
 
-Settings: one row per provider; **Auto** detects the data source and its primary mode:
+## Sources
 
-![Provider list in the settings page](https://raw.githubusercontent.com/takboo/dsh-usage-state/main/assets/screenshots/settings-providers.webp)
-
-Expanding **Advanced** lets you override the source and endpoint, name a credential, or paste a key (written to the DSH credential store):
-
-![Advanced block](https://raw.githubusercontent.com/takboo/dsh-usage-state/main/assets/screenshots/settings-advanced.webp)
-
-## Supported sources
-
-| Source | API mode | Coding-plan mode | Credential |
+| Source | API reading | Coding-plan reading | Main credential |
 |---|---|---|---|
-| DeepSeek official | balance (CNY / USD) | — (no coding plan) | `DEEPSEEK_API_KEY` |
-| z.ai / Zhipu GLM | — | 5h / 7d used % | `ZAI_API_KEY` and friends |
-| Kimi (China) | Moonshot pay-as-you-go balance | Kimi Code subscription windows | `MOONSHOT_API_KEY` / `KIMI_CODING_API_KEY` |
-| OpenCode Zen Go | — | 5h / 7d / 30d used % | `OPENCODE_GO_API_KEY` / `OPENCODE_API_KEY` |
-| Sub2API (self-hosted) | balance / key quota | 5h / 7d from `rate_limits[]` | `SUB2API_API_KEY` + instance URL |
+| DeepSeek official | CNY/USD balance | — | DEEPSEEK_API_KEY |
+| z.ai / Zhipu GLM | — | 5h / 7d used % | ZAI_API_KEY and related refs |
+| Kimi / Moonshot | CNY balance | Kimi Code subscription windows | MOONSHOT_API_KEY / KIMI_CODING_API_KEY |
+| OpenCode Zen Go | — | 5h / 7d / 30d used % | OPENCODE_GO_API_KEY / OPENCODE_API_KEY |
+| Sub2API | Balance or key allowance | Depends on the instance, e.g. 5h / 1d / 7d / 30d | SUB2API_API_KEY and instance URL |
 
-- **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`](https://github.com/takboo/dsh-usage-state/blob/main/docs/adapters.md).
+Percentages mean **used**. z.ai keys belong to their China/global region; China is the default endpoint and failures may try the mirror. The current cache merges by source and mode, so separate keys/instances must not be treated as supported independent accounts. Endpoints, field semantics and extension steps are in the [adapter guide (Chinese)](https://github.com/takboo/dsh-usage-state/blob/main/docs/adapters.md).
 
-## Display, refresh, credentials
+## Screenshots
 
-- **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).
+OpenCode Zen Go's three windows on the independent line above the input:
 
-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.
+![Account readings above the input](https://raw.githubusercontent.com/takboo/dsh-usage-state/main/assets/screenshots/status-line.webp)
 
-## Compatibility
+Provider settings and advanced controls:
 
-- **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`). 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.
+![Provider settings](https://raw.githubusercontent.com/takboo/dsh-usage-state/main/assets/screenshots/settings-providers.webp)
 
-## Limitations
+![Advanced settings](https://raw.githubusercontent.com/takboo/dsh-usage-state/main/assets/screenshots/settings-advanced.webp)
 
-- **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/backlog.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/backlog.md).
+## Refresh and credentials
 
-## Development
+The host schedules refreshes 2 seconds after a turn ends and has a 5-minute fallback timer. The browser reads the RPC mirror every 30 seconds. Ordinary polling initializes a missing or changed account identity, otherwise it does not shorten idle queries to once a minute. Successful requests have a default 60-second minimum; explicit refresh can bypass it, and active retries after failure are not throttled by that successful-request interval. Editing the idle interval reschedules the timer.
 
-```bash
-npm install          # add --cache /tmp/npm-cache if ~/.npm is not writable
-npm test             # node:test runs .ts / .tsx directly (needs Node >= 22.6)
-npm run typecheck    # tsc --noEmit
-npm run build        # tsdown → lib/ (host index.js + typert.js, browser client.js)
-npm run watch        # rebuilds client.js only; client changes hot-reload, no page refresh
-```
+The plugin queries balances/quotas and reads the selected model and provider catalog. It writes no session logs and reports no readings to third parties. The host does not return stored key values to the browser; a key the user actively pastes is sent through DSH's credential service to the credential file in the selected home. Environment values take precedence and usually cannot be edited in settings.
 
-**Local loop (no release needed)**: `scripts/dev-local.sh` creates a throwaway profile under `/tmp/dsh-dev` (override with `DSH_HOME`), installs this repository into it as a `link:` and boots a host on its own port with the Desktop app's bundled CLI. Your real profiles are never touched.
+## Known limitations
 
-```bash
-npm run build                 # lib/ must exist
-scripts/dev-local.sh          # creates/reuses the dev profile, prints the token URL
-# second terminal:
-npm run watch                 # rebuilds client.js on save
-```
+See the [Backlog (Chinese)](https://github.com/takboo/dsh-usage-state/blob/main/docs/backlog.md) for remediation status and verification scope.
 
-Because the profile links this working tree, a rebuild is picked up by the running host: client changes are hot-swapped by `dsh-client-hmr` (the host stat-polls every bundle at 500ms and tells the browser to reload the module over `/plugins/events`) — no restart, no release. Host-side changes (`src/host/**`, `src/index.ts`, `cordis.patch.yml`) need this script restarted.
+- **Older npm 0.4.4 and earlier:** still has credential override, pin/cache identity, legacy hiding, default ordering and failure-display defects. It still divides Moonshot balances ≥100 yuan by 100 and may turn invalid DeepSeek amounts into zero. These are fixed in 0.4.5; upgrade if you use an older version. Cross-check old-version amounts against the [official API](https://platform.kimi.com/docs/api/balance.md).
+- **Account scope:** one target is still selected per source and mode. Identity isolation does not add independent multi-account support.
+- **Live verification:** Kimi Code/Sub2API accounts, high-threshold colors, real credential writes and nonzero OpenCode readings still lack live coverage. Local interaction tests do not replace that acceptance.
+- **Scope:** the line can be absent without a selected model or when hidden; clicking it does not open settings; readings are not saved as history.
 
-⚠️ **This profile has no credentials**: `$DSH_HOME/.credentials.yaml` is home-level, and a fresh home starts without keys and without your other plugins (a font plugin changes the very glyph metrics a layout depends on). It is for **structural / host-side** checks only. To judge how something *looks*, install the same build into a profile that already has your keys and plugins — still without publishing:
+## Development and docs
+
+Development supports Node 22.18+ on the 22 line or Node 24.11+. Canonical builds pin **Node 24.21.0** ([.node-version](https://github.com/takboo/dsh-usage-state/blob/main/.node-version)) and **npm 11.19.1** (packageManager), above the runtime floor. Basic checks:
 
 ```bash
-npm pack --pack-destination /tmp --cache /tmp/npm-cache
-dsh plugin --profile web add /tmp/dsh-usage-state-<version>.tgz   # file: install
-dsh plugin --profile web add "$PWD"                               # link: install, for hot reload
-dsh plugin --profile web add dsh-usage-state@<published>          # back to the published build
+npm ci
+npm run typecheck
+npm run build
+npm test
 ```
 
-Bump the version and publish only after you have **seen** the change work.
-
-Host-side changes need a DSH restart; client-side changes do not. The `lib/` output is **committed on purpose**: `dsh plugin add github:...` installs straight from the repository with no build step, and `npm test` guards the bundle envelope, the require allow-list and the `exports` targets.
-
-## Docs
-
-| Document | Contents |
-|---|---|
-| [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
+See the [development guide (Chinese)](https://github.com/takboo/dsh-usage-state/blob/main/docs/development.md) for local profiles, watch and HMR requirements. The [documentation index (Chinese)](https://github.com/takboo/dsh-usage-state/blob/main/docs/index.md) links architecture, design, release, audit and research material by task.
 
-- **[`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`](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).
+## Acknowledgements and license
 
-## License
+Thanks to [dsh-cost-meter](https://github.com/Han-1413141/dsh-cost-meter) by Han-1413141 (MIT) for data-source behavior references. This TypeScript implementation was written independently; endpoint, field and compatibility provenance is recorded in the [upstream analysis](https://github.com/takboo/dsh-usage-state/blob/main/docs/research/dsh-cost-meter-analysis.md). DSH provides the settings, credentials, RPC, slots and UI primitives.
 
-[MIT](LICENSE)
+[MIT](LICENSE). Report problems or attribution suggestions through [Issues](https://github.com/takboo/dsh-usage-state/issues).