dsh-commandcode-quota 0.2.2 → 0.3.0

package/README.md

@@ -6,7 +6,12 @@ The plugin renders a compact status row directly underneath the DSH composer:
 
 - **5-hour, weekly and monthly usage windows** as live percentages
 - **Available balance**
-- Click the row to expand the full breakdown: used / limit / remaining / reset time, total spend, tokens, success rate, subscription and account information
+- Click the row to expand the full breakdown: used / limit / remaining / reset time, total spend, tokens, daily spend, subscription and account information
+- **Three status lights** — normal / low balance / exhausted. The current one lights up and the others dim, driven by the official `belowThreshold` and `exceeded` fields; hover any light for an explanation
+- **The bar color follows usage**: cool while usage is low, warming up past 55%, red near the limit, with an internal gradient
+- **Six bar palettes** to choose from in the gear settings; the choice is remembered
+- **Overrun warning**: based on this period's daily average, the monthly card adds a line like “~N days until empty” when the remaining credit will not last until reset
+- A skeleton screen shows on first load so the layout does not jump when data arrives
 
 It is **single-account by design**. There is no account switcher, and your API key never reaches the browser.
 
@@ -76,12 +81,14 @@ The package has two halves:
 - **Host half** (`src/index.js`) resolves the key through the DSH credentials service and registers a read-only HTTP endpoint that fans out to the Command Code API, then aggregates the responses into a single payload. The key is read on every request and never serialized to the client.
 - **Client half** (`src/client.js`) registers a status row into the composer dock slot, polls the host endpoint, and renders it with DSH theme tokens so light and dark themes both work.
 
+Polling is tiered: balance every 3 minutes (cheap), usage and subscriptions every 30 minutes (expensive). Polling pauses while the page is hidden and refreshes fully when it comes back.
+
 Data comes from four Command Code endpoints, each called with `Authorization: Bearer <key>`:
 
 | Endpoint | Used for |
 |---|---|
 | `GET /alpha/billing/credits` | Balance and the 5-hour / weekly limits |
-| `GET /alpha/usage/summary` | Spend, tokens and success rate |
+| `GET /alpha/usage/summary` | Spend, tokens and the period start (for daily spend) |
 | `GET /alpha/billing/subscriptions` | Subscription status and period boundaries |
 | `GET /alpha/whoami` | Account information |
 
@@ -91,8 +98,11 @@ The monthly window is composed from the usage total plus the remaining credits,
 
 - The four requests run in parallel, so total latency is the slowest one rather than the sum.
 - A connection-level failure is retried once; a deliberate timeout is not retried.
-- On failure the panel falls back to the last successful value (kept in-process for 6 hours) and reports it as stale.
+- On failure the panel falls back to the last successful value (kept for 6 hours) and reports it as stale.
+- That snapshot is also written to `$DSH_HOME/dsh-commandcode-quota-cache.json`, so it **survives a restart**. It holds quota fields only — no account details, and never the key itself.
+- The snapshot is keyed by a fingerprint of the API key, so switching keys never reuses another account's data.
 - An HTTP 401 is never masked by cached data, because it means the credential itself is wrong.
+- When **all four** endpoints fail, the response carries a readable reason and the panel shows an error rather than a blank box.
 
 ## Development
 

package/README.zh.md

@@ -6,7 +6,12 @@
 
 - **5 小时、每周、每月**三个额度窗口的实时百分比
 - **可用余额**
-- 点击状态栏展开完整明细：已用 / 上限 / 剩余 / 重置时间、总消耗、Tokens、成功率，以及订阅和账户信息
+- 点击状态栏展开完整明细：已用 / 上限 / 剩余 / 重置时间、总消耗、Tokens、日均消耗，以及订阅和账户信息
+- **三档状态灯**：正常 / 余额低 / 已用尽，当前档亮起、其余压暗（依据官方 `belowThreshold` 与 `exceeded` 字段），悬停每个灯有解释
+- **进度条颜色随用量变化**：低用量保持所选冷色，55% 之后逐渐转暖，接近上限转红；条形内部也带一段渐变
+- **六种进度配色可选**：在齿轮设置里切换，选择会记住
+- **超额预警**：按本周期日均推算，如果会在重置前用光，月窗口会多一行「按当前日均，约 N 天后用完」
+- 首次加载显示骨架屏，数据回来时版面不会跳一下
 
 **刻意做成单账号**：没有账号切换，API key 也不会进入浏览器。
 
@@ -76,12 +81,14 @@ New-Item -ItemType Junction `
 - **宿主端**（`src/index.js`）通过 DSH 凭据服务解析 key，注册一个只读 HTTP 端点，并发请求 Command Code API 后聚合成一个响应。key 每次请求现读，绝不序列化给客户端。
 - **客户端**（`src/client.js`）往输入框的 dock 槽位注册状态栏，轮询宿主端点，并全部使用 DSH 主题 token 渲染，自动适配深色/浅色主题。
 
+轮询是分层的：余额 3 分钟一次（轻量），用量与订阅 30 分钟一次（重查询）；页面不可见时暂停，切回前台立即补一次完整查询。
+
 数据来自四个 Command Code 接口，均带 `Authorization: Bearer <key>`：
 
 | 接口 | 用途 |
 |---|---|
 | `GET /alpha/billing/credits` | 余额，以及 5 小时 / 每周限额 |
-| `GET /alpha/usage/summary` | 消耗、Tokens、成功率 |
+| `GET /alpha/usage/summary` | 消耗、Tokens、周期起始时间（用于日均消耗） |
 | `GET /alpha/billing/subscriptions` | 订阅状态与周期起止 |
 | `GET /alpha/whoami` | 账户信息 |
 
@@ -91,8 +98,11 @@ New-Item -ItemType Junction `
 
 - 四个请求并发发出，总耗时等于最慢的一个，而不是四者之和。
 - 连接级失败重试一次；主动超时不重试。
-- 请求失败时回退到上次成功的值（进程内保留 6 小时），并标记为陈旧数据。
+- 请求失败时回退到上次成功的值（保留 6 小时），并标记为陈旧数据。
+- 这份快照同时落盘到 `$DSH_HOME/dsh-commandcode-quota-cache.json`，**重启后依然可用**；只保存额度相关字段，不含账户信息，也不含 key 本身。
+- 快照按 API key 的指纹隔离：换 key 之后不会把上一个账号的数据当成兜底值。
 - HTTP 401 不会被缓存掩盖——它意味着凭据本身有问题，必须让用户看到。
+- 四个接口**全部**失败时，响应会带出可读的失败原因，面板显示错误而不是一块空白。
 
 ## 开发
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-commandcode-quota",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Command Code balance and quota panel for DeepSeek Harness: a status row under the composer showing balance and the 5-hour, weekly and monthly windows.",
   "type": "module",
   "license": "MIT",