@wannanbigpig/dsh-usage-stats 0.1.0 → 0.1.2

package/README.md

@@ -17,13 +17,23 @@ DeepSeek official balance, token usage, a contribution heatmap, and per-hour sta
 | ⏱️ | 按小时统计 | 选中日期的 24 小时输入/输出柱状图；悬停显示 Token、费用和模型明细，高峰时段自动标注 |
 | 💰 | 消费金额 | 估算消费（CNY，可配置模型单价）；费用按**请求完成时间（usage 上报时间）**归属小时与峰谷，与 DeepSeek 官方账单口径一致 |
 | ⚠️ | 用量提醒与限额 | 每日消费限额 + 最低余额保障 + 预警百分比，**按 API Key 独立配置** |
-| 🛑 | 超限停止调用 | 默认仅提醒；显式开启 `stopOnExceed` 后，今日消费达到限额的严重预警比例（默认 90%，设置页可调）即在 `agent/request` / `llm/stream` 拦截模型调用 |
+| 🛑 | 超限停止调用 | 默认仅提醒；显式开启 `stopOnExceed` 后，今日消费**达到每日限额（100%）**或余额跌破保障线时，在 `agent/request` / `llm/stream` 拦截模型调用；临界预警比例只触发红色警告，不拦截 |
 | 🔑 | 按 API Key 统计 | `keyProviders` 把 provider 路由映射到具体 Key，今日消费按 Key 归集、限额按 Key 判定 |
 | 🔄 | 后台监测 | 服务端启动即刷新，之后每 5 分钟更新余额与本地 Token 聚合 |
 | 🔒 | 本机安全边界 | 端点仅接受回环请求（GET / limits 支持 POST）；API Key 只在服务端解析，绝不进入浏览器或日志 |
 
 界面支持中文和英文。Token 数据来自会话事件中的 provider-reported `usage`（`assistant/chunk` 或 `assistant/message`），不是本地估算；「消费金额」是根据模型单价 × Token 数计算的**估算值**，请以 DeepSeek 官方账单为准。统计、限额判定与「今日」口径均按**北京时间**（服务端下发 `today` 字段，客户端优先使用），机器或浏览器时区不是 UTC+8 也保持一致。
 
+## 界面预览 / Screenshots
+
+「用量/余额」查询中心（概览标签）：DeepSeek 官方余额卡、用量预警、Token 汇总、年度贡献热图与按小时统计。
+
+![用量/余额查询中心（概览）](assets/screenshots/usage-panel.png)
+
+「设置 → 用量与计费」：按 API Key（或全局）配置每日消费限额、余额提醒线与预警比例，硬停止默认关闭。
+
+![设置 → 用量与计费（限额配置）](assets/screenshots/limits-settings.png)
+
 ## 快速安装 / Quick start
 
 需要 DeepSeek Harness `web` profile（`@deepseek-ai/dsh >= 0.1.0-rc.7`，`dsh plugin` 子命令自该版本引入）与 [pnpm](https://pnpm.io/installation)（`dsh plugin` 会把参数转发给 profile 目录里的 pnpm，因此所有 pnpm 子命令都可用）。
@@ -126,10 +136,10 @@ DEEPSEEK_API_KEY: sk-your-key-here
 「设置 → 用量与计费」页面承载限额配置（已从查询弹窗迁出，弹窗保持只读）。可**按 Key（或全局）**配置：
 
 - **启用限额**：开关。
-- **每日消费限额**（CNY）：今日估算消费达到限额 × `alertPercent`（默认 80%）→ 黄色预警；达到限额 × `criticalPercent`（默认 90%）→ 红色已超限，即硬停止的触发点（并非等到 100% 限额）；两个比例都可在设置页调整。
+- **每日消费限额**（CNY）：今日估算消费达到限额 × `alertPercent`（默认 80%）→ 黄色预警；达到限额 × `criticalPercent`（默认 90%）→ 红色已超限（仅提醒与告警，不拦截）；两个比例都可在设置页调整。
 - **余额提醒线**：新鲜余额低于该值 → 预警；余额过期或查询失败时显示灰色状态且 fail-open。
 - **预警百分比**：50% / 70% / 80% / 90% / 95%。
-- **超限停止调用**：默认关闭，仅提醒；用户显式开启后，今日消费达到限额 × `criticalPercent`（默认 90%，设置页可调）即视为已超限，在 `agent/request` 与 `llm/stream` 拦截新的模型调用（抛出 `UsageLimitExceededError`，消息会提示去调整限额）。余额查询失败或快照过期时，最低余额规则 fail-open，不会阻断调用。
+- **超限停止调用**：默认关闭，仅提醒；用户显式开启后，今日消费**达到每日限额（100%）**或余额跌破最低余额保障线时，在 `agent/request` 与 `llm/stream` 拦截新的模型调用（抛出 `UsageLimitExceededError`，消息会提示去调整限额）；临界预警（默认 90%）只显示红色已超限并触发告警，不拦截。余额查询失败或快照过期时，最低余额规则 fail-open，不会阻断调用。
 
 限额保存在 `~/.dsh/storages/usage-limits.json`，当前 schema 为 v2。旧 v1 文件会安全迁移：保留提醒规则，但不会自动继承旧 `stopOnExceed` / `minBalance` 为硬停止；用户需在设置页重新确认开启。v2 会拒绝未知配置字段。**规则解析采用全局兜底**：某个 Key 未设置数值（或仅有空壳规则）时，沿用全局限额；Key 设置了数值则覆盖全局、未设置的字段继续继承全局，因此全局限额始终是底线，不会被空壳 Key 规则静默绕过。拦截采用 **fail-open** 策略：限额检查本身出错时放行调用，绝不因插件故障阻塞模型。
 

package/lib/index.js

@@ -1049,7 +1049,8 @@ function evaluateKeyQuota({ keyRef, limits, todayCost = 0, balance = null, balan
 	const spendStatus = rule.dailyCostLimit !== null && rule.dailyCostLimit > 0
 		? (exceeded ? "exceeded" : (warning ? "warning" : "normal"))
 		: "muted";
-	const status = exceeded && rule.stopOnExceed
+	const hardLimitReached = balanceExceeded || (rule.dailyCostLimit !== null && rule.dailyCostLimit > 0 && numericCost >= rule.dailyCostLimit);
+	const status = exceeded && rule.stopOnExceed && hardLimitReached
 		? "blocked"
 		: exceeded ? "exceeded"
 			: warning ? "warning"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wannanbigpig/dsh-usage-stats",
   "description": "DeepSeek 官方余额、Token 用量、月历热图与离线 tokenizer，内置在 Harness 侧栏",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/wannanbigpig/dsh-usage-stats.git"
@@ -17,6 +17,7 @@
   ],
   "files": [
     "lib/",
+    "assets/",
     "cordis.patch.yml",
     "README.md",
     "LICENSE"