dsh-usage-state 0.4.4 → 0.4.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/CHANGELOG.md +99 -52
  2. package/README.en.md +62 -127
  3. package/README.md +59 -156
  4. package/docs/adapters.md +65 -77
  5. package/lib/client.js +209 -64
  6. package/lib/index.js +343 -179
  7. package/lib/typert.js +1 -0
  8. package/package.json +17 -8
package/CHANGELOG.md CHANGED
@@ -1,85 +1,132 @@
1
1
  # 更新日志（Changelog）
2
2
 
3
- 所有对外可见的变更按版本记录于此。每条决策"为什么改"的来龙去脉见 [`docs/design-changelog.md`](docs/design-changelog.md)（修订记录）；发布与验证的操作记录见 [`docs/release.md`](docs/release.md)。
3
+ 用户可见的变更按版本记录于此。设计取舍见 [设计修订](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)。
4
4
 
5
- 格式参照 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)；版本号遵循语义化版本。`0.3.0` 起发布 npm（此前仅 GitHub 安装）。
5
+ 格式参照 [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记录；历史比较引用说明见文末。
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
- ### 0.4.4（待发布）
9
+ ## [0.4.6] - 2026-10-14
10
10
 
11
- - **纯文档发布**：README 与实际行为对齐（SVG 进度环、输入框上方独立一行、版本清单补全），文档结构重组（架构 / 平台事实 / 发布 / 待办 / 设计修订各自成档）；`CHANGELOG.md` 自本版起随包发布。`lib/` 与 0.4.3 逐字节相同，无任何运行时变更。
11
+ ### Fixed
12
+
13
+ - Kimi Code provider（kimi-code/kimi-coding/kimi-for-coding）和api.kimi.com/api.kimi.ai自动选择Coding Plan用量，Moonshot保持API余额；显式模式选择优先。
14
+ - Kimi用量兼容官方客户端usages比例池（5h/7d/月总额度/编程月用量）及旧usage/limits计数；TIME_UNIT_MINUTE的300分钟归一为5h，新套餐无周额度时不虚构7d。
15
+ - Kimi Code完整API地址不再重复拼接coding路径；Moonshot与Kimi Code的provider凭据按模式筛选，HTTP200错误信封及非法读数不会覆盖成功值。
16
+
17
+ ### Validation
18
+
19
+ - 新增provider→凭据→请求→RPC回归、月额度状态行渲染及真实tarball的Kimi预构建运行冒烟，纳入现有CI/Release的Node24与Node20门禁。
20
+ - 使用既有KIMI_CODING_API_KEY对官方接口完成只读实测，成功读取5h/7d窗口；未将密钥或账户响应写入仓库。月额度形态依官方客户端固定源码和去身份fixture验证。
21
+
22
+ ## [0.4.5] - 2026-10-10
23
+
24
+ ### Fixed
25
+
26
+ - provider级凭据覆盖贯通读取、描述和保存；显式provider端点/ref优先于legacy source默认，固定端点不尝试镜像。
27
+ - Moonshot余额按官方人民币元解析；DeepSeek跳过非法金额，无有效读数时报parse并保留同身份旧成功值；响应体超时/中断归network。
28
+ - 宿主按有效目标签名、私有凭据摘要和generation隔离缓存/在途；拒绝配置切换、ABA、晚lookup和晚HTTP的旧结果，目标移除及stop不再触发后续查询。已解析密钥的原文回显在快照错误边界精确替换。
29
+ - legacy models仅通过normalize迁移，权威空provider目录停止轮询；普通getState只初始化缺失/变更身份，浏览器30s轮询不缩短5min宿主idle，间隔修改会重调timer。
30
+ - origin-only endpointHints传到设置页和状态行；默认provider按可见顺序排序；旧值tooltip含原因，RPC断线标年龄/陈旧。客户端配置身份失效后拒绝旧RPC，普通请求中的显式刷新排一次，已有force则共享。
31
+ - 配置写入false/rejection、凭据保存/清除失败与pending均有反馈；配置只读和凭据权限分开，未编辑输入框失焦不写回旧草稿。
32
+
33
+ ### Engineering
34
+
35
+ - 新增标准Ubuntu CI、Dependabot和默认verify的手动Release；action固定完整SHA，npm OIDC与GitHub附档分离权限，复用同一已验证tarball和checksum。
36
+ - 修复Release在job级env使用runner.temp导致整份工作流无法解析的问题，tarball路径改在runner步骤中设置；CI新增固定版本/checksum的actionlint检查表达式上下文。
37
+ - Dependabot保留React18与TypeScript JavaScript编译API兼容线，忽略这些依赖的自动major更新；纳入tsdown0.23.0、unrun0.3.1和Zod4.6.5。Zod测试验证固定v4依赖及真实codec行为，不再要求旧补丁号4.5.1。
38
+ - 新增metadata、已提交产物、实际tarball、稳定发布tag和预构建runtime门禁；必要产物缺失改为硬失败，不再skip。规范工具链固定Node24.21.0/npm11.19.1，锁文件根版本同步包版本。
39
+ - schemastery peer/dev下界更正为3.18.3（3.18.2缺少volatile能力），锁定解析版本3.18.4；没有扩大DSH发布线范围。
40
+ - 版本升至0.4.5，交付此前Unreleased整改；新增稳定版本tag自动派发可信main上的Release，手动触发仍默认verify。npm经OIDC发布同一已验证tarball，GitHub Release附相同字节与checksum。
41
+
42
+ ### Documentation
43
+
44
+ - 精简中英README，增加任务导航、领域术语、开发指南和用户排查；明确0.4.5包含整改，0.4.4及更早版本仍有旧版问题。
45
+ - 双语README增加CI/npm状态徽章，恢复修复版npm安装指引并记录0.4.5版本说明。
46
+ - 设计、架构、适配器、平台和发布文档同步本地实现及验证边界；A01–A17状态归入唯一Backlog，历史研究与修订1–24保留。
47
+ - 0.4.4发布日期和历史提交引用已校正；真实账户、视觉及实际凭据写入验证仍未新增。
48
+
49
+ ## [0.4.4] - 2026-10-06
50
+
51
+ - 更新README中的SVG进度环、输入框上方独立行和版本导航文案，拆分维护文档的职责。
52
+ - CHANGELOG自本版起随npm包发布；预构建lib与0.4.3相同，无预构建运行代码变更。
12
53
 
13
54
  ## [0.4.3] - 2026-10-05
14
55
 
15
- - **进度显示改为 SVG 圆环**：平台 `ContextMeter` 同款几何（14×14、r=5.5、2px 描边、12 点起弧），替代 `█`/`░` 文字条（其字形回落宽度不可控，见修订 21/23）。阈值变色经 `currentColor` 传导到环上；`display.progressBar` 配置键保留（关掉即隐藏环）。
16
- - **排版对齐平台统计行**：字号/行高照抄 `StatsPills` 的显式表达式（修订 22）。
17
- - **折行修复**：分隔符与它引导的段落同盒（`data-usage-part`），折行不再留下孤立的 `·`（修订 21）。
18
- - 数据模型：`StatusSegment.bar?: string` → `progress?: number`。
56
+ - **进度显示改为SVG圆环**：平台ContextMeter同款几何（14×14、r=5.5、2px描边、12点起弧），替代文字条（字形回落问题见修订21/23）。阈值变色经currentColor传导到环，沿用display.progressBar配置键。
57
+ - 字号/行高照抄平台统计行的显式表达式（修订22）。
58
+ - 分隔符与它引导的段落同盒，折行不再留下孤立的分隔符（修订21）。
59
+ - 显示模型从文字bar改为数值progress。
60
+
61
+ ## [0.4.2] - 2026-10-05
62
+
63
+ - 状态行迁到conversation.input.dock，位于输入框上方、与输入卡片同宽、order=200；保留原生统计行（修订20）。
64
+ - 此前GitHub开发阶段对共享dock的适配记录在修订19，最终随本版迁为上方独立行；不把该后续提交误列为npm0.4.1已发布内容。
19
65
 
20
- ## [0.4.2] — 2026-10-05
66
+ ## [0.4.1] - 2026-10-05
21
67
 
22
- - 状态行迁到 **`conversation.input.dock`**（输入框上方、与输入卡片同宽的独立一行，`order: 200`）。0.2 里 `conversation.composer.dock` 是与平台统计、上下文计量器共排的一排 pill，不存在"输入框之下"的整行位置（修订 20）。
68
+ - **修复0.4.0读数全缺**：客户端RPC贡献参数codec缺少0.2要求的create()，remote.usageState未挂载，界面误报Mode not supported（修订18）。0.4.0用户应升级至最新兼容版。
69
+ - 挂载失败记录console.error和store错误；catalog未到时显示读取中。
70
+ - 新增真实0.2 registry契约测试，源码与构建产物各一条。
23
71
 
24
- ## [0.4.1] — 2026-10-05
72
+ ## [0.4.0] - 2026-10-05
25
73
 
26
- - **修复 0.4.0 读数全缺**：客户端 RPC contribution 的参数 codec 缺少 0.2 要求的 `create()` 工厂，`remote.usageState` 从未挂载，界面误报 `Mode not supported`（修订 18）。**0.4.0 用户必须升级。**
27
- - 挂载失败不再被静默吞掉（`console.error` + 写入 store）；catalog 未到时显示"读取中"而不是"模式不支持"。
28
- - dock 布局适配：与平台 `.pill` 同构，不再挤压/裁切平台统计（修订 19）。
29
- - 新增**真实 0.2 registry 契约测试**（源码与构建产物各一条，修订 18）。
74
+ - 迁移到DSH0.2的Config/configForms/configEditor设置模型；旧settingsScope/settings.register已移除（修订17）。支持范围收紧为 `>=0.2.0-rc.2 <0.3.0-0`。
75
+ - 新增dsh-settings与schemastery peer声明，并在patch中提供config:{}。
76
+ - 本版仍有客户端RPC挂载缺陷，随后由0.4.1修复。
30
77
 
31
- ## [0.4.0] — 2026-10-05
78
+ ## [0.3.2] - 2026-09-30
32
79
 
33
- - **迁移到 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`。
34
- - `peerDependencies` 新增 `@deepseek-ai/dsh-settings`（让 0.1.x 宿主在**安装时**被运行时闸门拒绝，而不是装上后启动崩溃）与 `@deepseek-ai/schemastery`。
35
- - `cordis.patch.yml` 插入行补 `config: {}`，避免新装实例状态行沉默。
36
- - ⚠️ 本版有读数缺失缺陷（见 0.4.1）。
80
+ - 仅放宽engines.dsh，源码与产物未改（修订16）。
81
+ - 0.1线末版；声称的0.2兼容后来被真机推翻。DSH0.2不能使用本版，需最新兼容0.4系列。
37
82
 
38
- ## [0.3.2] — 2026-09-30
83
+ ## [0.3.1] - 2026-09-22
39
84
 
40
- - 仅放宽 `engines.dsh` 到 `>=0.1.5-rc.1 <0.3.0-0`；源码与产物零改动（修订 16）。
41
- - ⚠️ **0.1 线末版**。它声称的 0.2 兼容后来被真机推翻（0.2 删除了 `settingsScope`，装上会让 web 启动失败，修订 17）——0.2 宿主请装 `0.4.x`。
85
+ - 移除React runtime peer，浏览器React由平台模块表提供；React仍作开发依赖（修订15）。
42
86
 
43
- ## [0.3.1] — 2026-09-22
87
+ ## [0.3.0] - 2026-09-22
44
88
 
45
- - 移除 `peerDependencies.react`：浏览器半边的 React 由平台运行时注入，不走 node_modules，声明它只会产生 `missing peer` 警告（修订 15）。
89
+ - 移除回合行，账户当前读数只在输入区域显示（修订13）。
90
+ - 首次发布npm，去掉private并声明engines.dsh；进入dsh-market收录链路（修订14）。
46
91
 
47
- ## [0.3.0] — 2026-09-22
92
+ ## [0.2.3] - 2026-09-22
48
93
 
49
- - **移除回合行**：账户级读数不能诚实地描述单个回合，`conversation.chat.*` 上的展示整体否决（修订 13；可行性实验见修订 8）。
50
- - 去掉 `private`，**首次发布 npm** 并被 dsh-market 收录（分类 `usage`，修订 14）；`engines.dsh` 随包声明（市场徽标与兼容判定读它）。
94
+ - 设置页头部改两列网格，长provider名截断，不挤走控件（修订12）。
95
+ - README补充上游行为参考与致谢。
51
96
 
52
- ## [0.2.3] — 2026-09-22
97
+ ## [0.2.2] - 2026-09-21
53
98
 
54
- - 设置页卡头部改两列网格：provider 名过长时只截断灰色的 id（悬停看全文），`↑ ↓ 模式` 控件永不换行（修订 12）。
55
- - README 增补对上游 `dsh-cost-meter` 的溯源致谢。
99
+ - 三处健壮性修复，宿主不再轮询已删provider。
56
100
 
57
- ## [0.2.2] — 2026-09-21
101
+ ## [0.2.1] - 2026-09-21
58
102
 
59
- - 三处健壮性修复；不再轮询已删除的 provider。
103
+ - 修复已删provider仍留在设置页的幽灵行。
60
104
 
61
- ## [0.2.1] — 2026-09-21
105
+ ## [0.2.0] - 2026-09-21
62
106
 
63
- - 修复"幽灵 provider 行"（已删除的 provider 仍出现在设置页）。
107
+ - 新增OpenCode Zen Go来源，5h/7d/30d；同源模式合并路由（修订11）。
64
108
 
65
- ## [0.2.0] — 2026-09-21
109
+ ## 0.1.0 - 2026-09-21
66
110
 
67
- - 新增数据源 **OpenCode Zen Go**（5h / 7d / 30d；修订 11）。通往同一账户的两条 DSH 路由按 `source:mode` 去重，只发一次请求。
111
+ - 首版：四家适配器、宿主缓存/RPC、输入区域状态行、provider配置与中英UI。
112
+ - 首版完整发布提交尚未确认，不链接不存在的版本标签。
68
113
 
69
- ## [0.1.0] — 2026-09-21
114
+ ## 历史引用说明
70
115
 
71
- - 首版：数据源适配器框架 + DeepSeek / z.ai / Kimi / Sub2API 四家、composer 状态行（余额 / 5h·7d 已用百分比 + 倒计时 + 阈值变色）、设置页（provider 四态 + 排序 + 密钥写入）、凭据探测与直读兜底、Typert RPC 快照通道、中英双语、`node:test` 单测。
116
+ 0.4.5起建立版本tag/Release；更早发布没有保存这些引用。0.3.0至0.4.4的比较端点来自各npm版本的gitHead；0.2系列引用对应实现提交，不能替代当时没有保存的正式发布产物。早期日期沿用历史版本记录。今后版本应按发布流程建立稳定引用。
72
117
 
73
- [Unreleased]: https://github.com/takboo/dsh-usage-state/compare/0.4.3...HEAD
74
- [0.4.3]: https://github.com/takboo/dsh-usage-state/compare/0.4.2...0.4.3
75
- [0.4.2]: https://github.com/takboo/dsh-usage-state/compare/0.4.1...0.4.2
76
- [0.4.1]: https://github.com/takboo/dsh-usage-state/compare/0.4.0...0.4.1
77
- [0.4.0]: https://github.com/takboo/dsh-usage-state/compare/0.3.2...0.4.0
78
- [0.3.2]: https://github.com/takboo/dsh-usage-state/compare/0.3.1...0.3.2
79
- [0.3.1]: https://github.com/takboo/dsh-usage-state/compare/0.3.0...0.3.1
80
- [0.3.0]: https://github.com/takboo/dsh-usage-state/compare/0.2.3...0.3.0
81
- [0.2.3]: https://github.com/takboo/dsh-usage-state/compare/0.2.2...0.2.3
82
- [0.2.2]: https://github.com/takboo/dsh-usage-state/compare/0.2.1...0.2.2
83
- [0.2.1]: https://github.com/takboo/dsh-usage-state/compare/0.2.0...0.2.1
84
- [0.2.0]: https://github.com/takboo/dsh-usage-state/compare/0.1.0...0.2.0
85
- [0.1.0]: https://github.com/takboo/dsh-usage-state/releases/tag/0.1.0
118
+ [Unreleased]: https://github.com/takboo/dsh-usage-state/compare/v0.4.6...HEAD
119
+ [0.4.6]: https://github.com/takboo/dsh-usage-state/compare/v0.4.5...v0.4.6
120
+ [0.4.5]: https://github.com/takboo/dsh-usage-state/compare/3ad9a71e2f7e4b9a05c69bc529e396a364ae6aeb...v0.4.5
121
+ [0.4.4]: https://github.com/takboo/dsh-usage-state/compare/885541638ffa4da05b39bd1864085ba6d9acc288...3ad9a71e2f7e4b9a05c69bc529e396a364ae6aeb
122
+ [0.4.3]: https://github.com/takboo/dsh-usage-state/compare/0d2d4376d0db990fb36df5d6124e5b7894974d62...885541638ffa4da05b39bd1864085ba6d9acc288
123
+ [0.4.2]: https://github.com/takboo/dsh-usage-state/compare/e5ef97375d01faf9073ef5e4c7522f6ff59514f9...0d2d4376d0db990fb36df5d6124e5b7894974d62
124
+ [0.4.1]: https://github.com/takboo/dsh-usage-state/compare/d93e2c7cdbbba76346d753171b2a4c8408793fc2...e5ef97375d01faf9073ef5e4c7522f6ff59514f9
125
+ [0.4.0]: https://github.com/takboo/dsh-usage-state/compare/d9e08c8765ff89b9dc57b8ac56ee4c61412176d6...d93e2c7cdbbba76346d753171b2a4c8408793fc2
126
+ [0.3.2]: https://github.com/takboo/dsh-usage-state/compare/9f8b863339ebf552478e48c93cc80641f5e2ecb5...d9e08c8765ff89b9dc57b8ac56ee4c61412176d6
127
+ [0.3.1]: https://github.com/takboo/dsh-usage-state/compare/098a31c5b01c600a42ce5bc86d51627ec97b2b16...9f8b863339ebf552478e48c93cc80641f5e2ecb5
128
+ [0.3.0]: https://github.com/takboo/dsh-usage-state/compare/dd37b3d...098a31c5b01c600a42ce5bc86d51627ec97b2b16
129
+ [0.2.3]: https://github.com/takboo/dsh-usage-state/compare/7adb90e...dd37b3d
130
+ [0.2.2]: https://github.com/takboo/dsh-usage-state/compare/e4d40d7...7adb90e
131
+ [0.2.1]: https://github.com/takboo/dsh-usage-state/compare/c01a64f...e4d40d7
132
+ [0.2.0]: https://github.com/takboo/dsh-usage-state/commit/c01a64f
package/README.en.md CHANGED
@@ -1,179 +1,114 @@
1
1
  # dsh-usage-state
2
2
 
3
- 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.
3
+ [中文](README.md) | **English**
4
4
 
5
- > 中文说明见 [README.md](README.md)。
5
+ [![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)
6
6
 
7
- ```
8
- its own line above the composer input: z.ai / GLM · ◔ 5h 12% (4h0m) · ◔ 7d 59% (3d17h)
9
- DeepSeek · ¥58.13
10
- hover any segment: Source DeepSeek · Mode API balance · Granted 0 · Topped up 58.13
7
+ > **Release status:** Current version **0.4.6** adds automatic Kimi Code provider usage detection, regional endpoints, and current/legacy quota responses. See the [GitHub Release](https://github.com/takboo/dsh-usage-state/releases/tag/v0.4.6) for the tarball and checksum and the [Changelog](CHANGELOG.md#046---2026-10-14) for details.
8
+
9
+ 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.
10
+
11
+ ```text
12
+ z.ai / GLM · ◔ 5h 12% (4h0m) · ◔ 7d 59% (3d17h)
13
+ DeepSeek · ¥58.13
11
14
  ```
12
15
 
13
16
  ## Features
14
17
 
15
- - **Works with zero configuration**: the plugin figures out which data source and mode a provider needs, and reuses the API key DSH already has.
16
- - **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.
17
- - **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.
18
- - **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.
19
- - **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.
20
- - **Bilingual** (zh / en), following the DSH locale setting.
21
- - **Display only**: balances and quotas, nothing else — no cost accounting, pricing catalog, history or budgets.
18
+ - Recognized providers default to Auto and reuse existing DSH credentials. Configuration is per provider; the model list is informational.
19
+ - Balances, used percentages, reset countdowns and SVG rings, with configurable amber/red thresholds (80%/95% by default) and an option to hide rings.
20
+ - 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.
21
+ - Hover details include source, mode, reset time and balance components. The UI follows DSH's Chinese/English language setting.
22
+ - Current account readings only: no cost attribution, price catalog, budgets or historical bills.
22
23
 
23
24
  ## Install
24
25
 
25
- **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.
26
- **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)).
26
+ 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.
27
+
28
+ Install from npm:
27
29
 
28
30
  ```bash
29
- # 1) install (npm package)
30
31
  dsh plugin --profile web add dsh-usage-state
31
-
32
- # 2) restart DSH — the plugin's bundle patch is read at startup
33
-
34
- # 3) remove
35
- dsh plugin --profile web remove dsh-usage-state
32
+ # Restart DSH afterwards: the bundle patch is read at startup.
36
33
  ```
37
34
 
38
- Installing straight from GitHub works too (same content as the npm package):
35
+ You can also install from GitHub:
39
36
 
40
37
  ```bash
41
38
  dsh plugin --profile web add github:takboo/dsh-usage-state
42
39
  ```
43
40
 
44
- For development, a local path works too (host-side changes still need a DSH restart):
45
-
46
- ```bash
47
- dsh plugin --profile web add /path/to/dsh-usage-state
48
- ```
41
+ 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.
49
42
 
50
- 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.
43
+ 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.
51
44
 
52
- 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).
45
+ 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.
53
46
 
54
47
  ## Quick start
55
48
 
56
- 1. Open **Settings → Usage state**: one row per provider configured in DSH.
57
- 2. Leave it on **Auto** (it detects the data source and its primary mode), or pick `API` / `Coding Plan` / `Hidden`; use ↑↓ to reorder.
58
- 3. The reading appears on its own line above the composer input, as wide as the input card.
59
-
60
- 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).
61
-
62
- 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).
63
-
64
- ## Screenshots
65
-
66
- 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):
49
+ 1. Open **Settings → Usage state** to inspect providers, models and the detected source.
50
+ 2. Keep Auto for recognized providers, or choose a supported API, Coding Plan or Hidden option.
51
+ 3. Set your instance URL for a self-hosted Sub2API source. The current model's reading appears above the input.
52
+ 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.
67
53
 
68
- ![The reading on its own line above the composer](https://raw.githubusercontent.com/takboo/dsh-usage-state/main/assets/screenshots/status-line.webp)
54
+ 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.
69
55
 
70
- Settings: one row per provider; **Auto** detects the data source and its primary mode:
56
+ ## Sources
71
57
 
72
- ![Provider list in the settings page](https://raw.githubusercontent.com/takboo/dsh-usage-state/main/assets/screenshots/settings-providers.webp)
58
+ | Source | API reading | Coding-plan reading | Main credential |
59
+ |---|---|---|---|
60
+ | DeepSeek official | CNY/USD balance | — | DEEPSEEK_API_KEY |
61
+ | z.ai / Zhipu GLM | — | 5h / 7d used % | ZAI_API_KEY and related refs |
62
+ | Kimi / Moonshot | CNY balance | Kimi Code subscription windows | MOONSHOT_API_KEY / KIMI_CODING_API_KEY |
63
+ | OpenCode Zen Go | — | 5h / 7d / 30d used % | OPENCODE_GO_API_KEY / OPENCODE_API_KEY |
64
+ | Sub2API | Balance or key allowance | Depends on the instance, e.g. 5h / 1d / 7d / 30d | SUB2API_API_KEY and instance URL |
73
65
 
74
- Expanding **Advanced** lets you override the source and endpoint, name a credential, or paste a key (written to the DSH credential store):
66
+ Kimi Code routes `kimi-code`, `kimi-coding`, and `kimi-for-coding`, plus custom providers declaring `api.kimi.com` / `api.kimi.ai`, automatically read subscription usage. The plugin displays only returned windows: 5h, 7d, monthly total, and monthly code usage. Moonshot regional APIs retain CNY balance mode. Explicit settings take precedence.
75
67
 
76
- ![Advanced block](https://raw.githubusercontent.com/takboo/dsh-usage-state/main/assets/screenshots/settings-advanced.webp)
68
+ 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).
77
69
 
78
- ## Supported sources
70
+ ## Screenshots
79
71
 
80
- | Source | API mode | Coding-plan mode | Credential |
81
- |---|---|---|---|
82
- | DeepSeek official | balance (CNY / USD) | — (no coding plan) | `DEEPSEEK_API_KEY` |
83
- | z.ai / Zhipu GLM | — | 5h / 7d used % | `ZAI_API_KEY` and friends |
84
- | Kimi (China) | Moonshot pay-as-you-go balance | Kimi Code subscription windows | `MOONSHOT_API_KEY` / `KIMI_CODING_API_KEY` |
85
- | OpenCode Zen Go | — | 5h / 7d / 30d used % | `OPENCODE_GO_API_KEY` / `OPENCODE_API_KEY` |
86
- | Sub2API (self-hosted) | balance / key quota | 5h / 7d from `rate_limits[]` | `SUB2API_API_KEY` + instance URL |
72
+ OpenCode Zen Go's three windows on the independent line above the input:
87
73
 
88
- - **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.
89
- - **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%.
90
- - 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).
74
+ ![Account readings above the input](https://raw.githubusercontent.com/takboo/dsh-usage-state/main/assets/screenshots/status-line.webp)
91
75
 
92
- ## Display, refresh, credentials
76
+ Provider settings and advanced controls:
93
77
 
94
- - **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.
95
- - **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).
78
+ ![Provider settings](https://raw.githubusercontent.com/takboo/dsh-usage-state/main/assets/screenshots/settings-providers.webp)
96
79
 
97
- 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.
98
- - **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.
99
- - **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.
100
- - **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.
80
+ ![Advanced settings](https://raw.githubusercontent.com/takboo/dsh-usage-state/main/assets/screenshots/settings-advanced.webp)
101
81
 
102
- ## Compatibility
82
+ ## Refresh and credentials
103
83
 
104
- - **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`.
105
- - `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.
106
- - 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`.
107
- - 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).
108
- - 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).
109
- - 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`.**
110
- - 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.
111
- - 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.
112
- - Published to npm as [`dsh-usage-state`](https://www.npmjs.com/package/dsh-usage-state); GitHub installs work too.
84
+ 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.
113
85
 
114
- ## Limitations
86
+ 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.
115
87
 
116
- - **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.
117
- - **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.
118
- - **Clicking the line does not open settings** (the platform exposes no public "open settings panel" service); details are in the hover tooltip.
119
- - **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.
120
- - Full list: [`docs/backlog.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/backlog.md).
88
+ ## Known limitations
121
89
 
122
- ## Development
90
+ See the [Backlog (Chinese)](https://github.com/takboo/dsh-usage-state/blob/main/docs/backlog.md) for remediation status and verification scope.
123
91
 
124
- ```bash
125
- npm install # add --cache /tmp/npm-cache if ~/.npm is not writable
126
- npm test # node:test runs .ts / .tsx directly (needs Node >= 22.6)
127
- npm run typecheck # tsc --noEmit
128
- npm run build # tsdown → lib/ (host index.js + typert.js, browser client.js)
129
- npm run watch # rebuilds client.js only; client changes hot-reload, no page refresh
130
- ```
92
+ - **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).
93
+ - **Account scope:** one target is still selected per source and mode. Identity isolation does not add independent multi-account support.
94
+ - **Live verification:** Kimi Code monthly quotas, Sub2API accounts, high-threshold colors, real credential writes and nonzero OpenCode readings still lack live coverage. Local interaction tests do not replace that acceptance.
95
+ - **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.
131
96
 
132
- **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.
97
+ ## Development and docs
133
98
 
134
- ```bash
135
- npm run build # lib/ must exist
136
- scripts/dev-local.sh # creates/reuses the dev profile, prints the token URL
137
- # second terminal:
138
- npm run watch # rebuilds client.js on save
139
- ```
140
-
141
- 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.
142
-
143
- ⚠️ **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:
99
+ 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:
144
100
 
145
101
  ```bash
146
- npm pack --pack-destination /tmp --cache /tmp/npm-cache
147
- dsh plugin --profile web add /tmp/dsh-usage-state-<version>.tgz # file: install
148
- dsh plugin --profile web add "$PWD" # link: install, for hot reload
149
- dsh plugin --profile web add dsh-usage-state@<published> # back to the published build
102
+ npm ci
103
+ npm run typecheck
104
+ npm run build
105
+ npm test
150
106
  ```
151
107
 
152
- Bump the version and publish only after you have **seen** the change work.
153
-
154
- 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.
155
-
156
- ## Docs
157
-
158
- | Document | Contents |
159
- |---|---|
160
- | [CHANGELOG](CHANGELOG.md) | Changes per version |
161
- | [`docs/architecture.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/architecture.md) | Code map, decision → code → test → verification traceability (Chinese) |
162
- | [`docs/adapters.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/adapters.md) | Adding a data source: contract, workflow, pitfalls, troubleshooting (Chinese) |
163
- | [`docs/design-consensus.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/design-consensus.md) | The design as it currently stands (Chinese) |
164
- | [`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) |
165
- | [`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) |
166
- | [`docs/platform-notes.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/platform-notes.md) | Measured facts about DSH platform behaviour (Chinese) |
167
- | [`docs/backlog.md`](https://github.com/takboo/dsh-usage-state/blob/main/docs/backlog.md) | Backlog, candidate data sources, explicit non-goals (Chinese) |
168
- | [`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) |
169
-
170
- ## Acknowledgements
108
+ 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.
171
109
 
172
- - **[`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.
173
- 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.
174
- If the upstream author wants a clearer attribution or a different arrangement, open an issue and it will be fixed.
175
- - **[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).
110
+ ## Acknowledgements and license
176
111
 
177
- ## License
112
+ 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.
178
113
 
179
- [MIT](LICENSE)
114
+ [MIT](LICENSE). Report problems or attribution suggestions through [Issues](https://github.com/takboo/dsh-usage-state/issues).