@feiyang666/dsh-usage-plugin 1.14.0 → 1.16.5

package/CHANGELOG.md

@@ -8,9 +8,65 @@
 
 ---
 
-## v1.14.0 (2026-08-27)
+## v1.16.5 (2026-08-29)
+
+### 新增 / New
+
+- **概览页 Hero 主指标卡**：顶部新增「本月已消耗」渐变大数字卡 + 当前计费时段徽章；设置月度预算后同卡显示预算使用进度条（≥80% 黄色提醒，≥100% 红色超支告警并显示超支金额）。
+- **核心指标卡片分层**：原 7 张等大统计卡改为「3 大主卡（总消耗 / 调用次数 / 缓存命中率）+ 4 小辅助卡（输入·未命中 / 输出 / 高峰消耗 / 空闲消耗）」，关键指标视觉权重突出。
+- **近 30 天消耗趋势图**（canvas 堆叠柱状）：概览页新增按日消耗趋势，高峰（橙）/ 空闲（蓝）堆叠着色，悬停显示当日高峰/空闲/总消耗与调用数。
+- **模型消耗占比环形图**：概览页新增各模型消耗占比环形图 + 图例（模型名 + 百分比）。
+- **会话消耗排行 Top 10**：概览页新增按会话（sessionId）聚合的消耗排行，显示调用次数与消耗、相对进度条，便于定位「最烧钱」的对话。
+- **缓存命中列表关键字搜索**：新增搜索框，按 模型 / 服务商 / 会话ID / 用途 实时过滤，与日期筛选叠加生效。
+- **月度预算设置与超支预警**（`lib/index.js` + `lib/client.js`）：价格表页新增「月度预算」区块（输入金额保存 / 清除），持久化到数据目录 `budget.json`；概览页 Hero 显示当月已用/预算进度。新增 `setBudget` API，`list` 附带 `budget` 字段（向后兼容）。
+- **说明信息收进可折叠抽屉**：原本首屏固定展示的「本地统计与官方后台的差异 / 高峰·空闲时段说明 / 计价说明」三段说明收进「▸ 帮助与说明」按钮（默认收起），有中断记录时按钮带数量角标；首屏直接展示数据。
+- **底部工具条重组**：导出 CSV / JSON / PNG / 打开目录 / 选择文件导入 / 帮助与说明 合并为一行，导出目标目录输入独立一行。
+
+### 修复 / Fixed
+
+- 概览页 Hero 高峰时段徽章颜色修正（高峰 = 橙色）。
+
+### 说明 / Notes
 
-> 📄 本版本英文发布说明（English release notes）：[RELEASE_NOTES.md](./RELEASE_NOTES.md)
+- 所有新 UI 文案均已补充英文词典（`__T_EN`），英文界面即时可用。
+- 未引入新 npm 依赖；现有测试 30/30 全部通过。
+
+---
+
+## v1.15.0 (2026-08-29)
+
+### 新增 / New
+
+- **用量日历新增日期范围筛选**（`lib/client.js` CalendarView）：日历视图此前只有月份导航、无法只看指定区间；现在顶部新增与概览一致的筛选栏（今天 / 近7天 / 近30天 / 全部 + 自定义起止日期）。筛选激活时：
+  - **每日消耗统计表跨月显示**范围内所有有记录的天（不再局限于当前月），标题显示所选范围；
+  - 顶部「本月调用 / 本月消耗」卡片自动切换为「范围内调用 / 范围内消耗」并按范围汇总（含高峰/空闲拆分）；
+  - 热力图仅对范围内日期着色，范围外显示为空（`—`）；
+  - 空态文案随范围显示「该范围内暂无记录。」；
+  - 预设按钮切换时自动清空自定义起止日期，避免残留范围误判。
+
+---
+
+## v1.14.1 (2026-08-29)
+
+### 修复 / Fixed
+
+- **中断调用兜底记录，使「调用次数」与 DeepSeek 官方后台对齐**（`lib/index.js`）：harness 在流被中断（aborted / error / timeout / 用户停止生成）时不会产出 `usage` chunk（usage 只在收到 `[DONE]` 哨兵后才由 adapter yield），导致这类调用此前完全不被插件记录——而官方后台仍会把该次请求计入「API 请求次数」并按实际 token 计费，于是插件统计的调用次数长期低于官方（如 8 月 27 日 985 vs 1033）。现在无 usage 但确为真实模型调用（通过 `isRealCall`，排除内部 `dsh2shell-*`/`fake`）的流，会在 `observe()` 的 `finally` 里补记一条 **0-token 的「中断调用」**（新增 `interrupted: true` 字段，`finishReason` 如实标记 `aborted`/`error`/`timeout`）。token 与费用均为 0，不会虚增消耗；调用次数与官方口径一致。
+- **面板透明展示中断调用**（`lib/client.js`）：
+  - 概览「调用次数」卡片新增 `· 中断 N（未计费）` 提示；
+  - 缓存命中列表与用量日历当日明细中，中断调用行在模型名旁显示红色「中断」徽标、结束原因红色标注、消耗列显示 `—`；
+  - PNG 导出报告同样在模型名旁标注「中断」、消耗列显示 `—`；
+  - 结束原因新增 `aborted → 已中断 / Interrupted`、`timeout → 超时 / Timeout` 映射（中英双语）。
+  - **用量面板顶部新增「本地统计与官方后台的差异」提示横幅**：说明本面板统计的是插件本地捕获的调用（官方价格 + 峰谷时段），与官方后台（platform.deepseek.com 用量页）相比金额可能更低——① 中断/出错/超时的调用官方仍按实际 token 计费而插件按 0 记录；② 账号下其他 API Key（其它应用/脚本）的调用不经过 DeepSeek Harness，官方包含而插件不包含；③ 精确对账可导出官方月度账单 CSV 对比。检测到中断调用时额外显示「当前记录中有 N 次中断调用（未计费）」红字提示。
+- **持久化与 API 透传 `interrupted`**（`lib/index.js`）：`normalizeRecord` / `projectRecord` 均保留该字段，重启恢复、`/usage/api` list 输出、JSON 导出一致。
+
+### 测试 / Tests
+
+- 新增 `test/interrupt.test.js`：验证中断兜底仅记录真实模型调用（DeepSeek 官方 / 第三方真实 provider），内部 `fake`/`dsh*` 占位调用永不兜底记录。
+- 全部 30/30 通过。
+
+---
+
+## v1.14.0 (2026-08-27)
 
 ### 新增 / New
 
@@ -277,6 +333,3 @@
 - CSV / JSON / PNG 长图导出（最新在前，最多 2000 条，超出提示），支持自定义导出目录（原生目录选择器）与「打开所在目录」。
 - JSON / CSV 导入合并，按时间去重。
 - Windows / macOS / Linux 跨平台路径与原生操作适配；启动诊断日志 `dsh-usage-boot.log`。
----
-
-📄 **英文发布说明入口（English release notes）**：[RELEASE_NOTES.md](./RELEASE_NOTES.md)

package/README.md

@@ -33,8 +33,10 @@ dsh-usage-plugin is a **usage & cost tracker** plugin in the DeepSeek Harness ec
 > Supports **Windows / macOS / Linux**: paths are handled per platform (`node:path`), and the folder picker / "reveal in file manager" use each OS's native mechanism (macOS: `osascript` / `open`; Linux: `zenity` / `xdg-open`). Balance query and export do not depend on Windows-only commands.
 
 - **Usage & Cost**: records each model call's token usage and cache hits (input miss / cache hit / cache write / output / reasoning / finish reason), and computes cost using DeepSeek's peak/valley or base pricing (peak hours on weekdays are automatically priced by Beijing time 09:00–12:00 and 14:00–18:00; since 2026-08-23 weekends are billed entirely at the off-peak rate). Model names come from the actual request parameters, so non-DeepSeek models are shown truthfully instead of "unknown model"; models without an official price are counted as 0. The overview shows a by-model table plus a by-API-provider × model drill-down (each provider grouped with every model's calls and peak/off-peak cost split) and a grand total row. The overview also supports **date filtering** (Today / Last 7 days / Last 30 days / All, plus a custom start–end range), so the aggregate stats can be scoped to any single day or date range.
-- **Usage Calendar**: a monthly daily-usage heatmap (colored by cost or call count), hover for details including the peak/off-peak cost split, click a day for its call list and peak/off-peak totals, plus a per-day statistics table with peak cost / off-peak cost / total columns and monthly rollups.
+- **Usage Calendar**: a monthly daily-usage heatmap (colored by cost or call count), hover for details including the peak/off-peak cost split, click a day for its call list and peak/off-peak totals, plus a per-day statistics table with peak cost / off-peak cost / total columns and rollups. Supports **date-range filtering** (Today / 7 days / 30 days / All plus custom start–end dates): when a range is active, the daily stats table shows every day in range across months, the top cards switch to "Calls in range / Cost in range" with range totals, and the heatmap only colors days inside the range.
 - **Cache Hit List**: newest-first, fully scrollable, with quick filters (Today / 7 days / 30 days / All) and custom date ranges; the summary line and footer total split peak vs off-peak consumption with a grand cost total. The list is paginated (100 rows per page), so it stays smooth even with large data volumes.
+- **Interrupted calls shown truthfully**: calls that were aborted / errored / timed out (e.g. manually stopped generation, stream interruption) are shown with a red **"Interrupted"** badge, the finish reason (Interrupted / Error / Timeout) and a `—` cost. The official console still counts these as API requests and bills their actual tokens, but the harness does not report their usage to the plugin — so the plugin records them at 0 tokens, keeping the **call count aligned with the official console** while costs are unaffected. The Overview's "Calls" card adds a `· interrupted N (not billed)` hint.
+- **Local stats vs official console**: a fixed notice banner at the top of the panel explains that this panel reflects calls captured locally by the plugin (official prices + peak/off-peak hours), and that the official console (platform.deepseek.com usage page) may show a higher amount because: ① interrupted/failed/timed-out calls are still billed by the console while the plugin records them as 0; ② calls from other API keys on your account (other apps/scripts) do not pass through DeepSeek Harness — the console includes them, the plugin does not; ③ for exact reconciliation, export the official monthly billing CSV and compare. When interrupted calls are detected, the banner also shows a red "Current records include N interrupted call(s) (not billed)" line.
 - **Price Table**: the official DeepSeek API price table (covering `deepseek-v4-flash` / `deepseek-v4-flash-vision-exp` / `deepseek-v4-pro`) — base and peak/valley unit prices shown side by side (peak vs off-peak), editable in-panel and persisted to `pricing.json`, with a reset-to-default option.
 - **Balance Query**: queries your DeepSeek account balance using the configured `DEEPSEEK_API_KEY`.
 - **Export**: CSV / JSON / **PNG long image** (newest-first, up to the latest 2000 records, warns if exceeded; the PNG report includes peak/off-peak cost columns), to any directory (native picker), auto-opens the folder after export.
@@ -309,6 +311,10 @@ pnpm dsh web
 - **[@mumuer1024](https://github.com/mumuer1024)**: reported and diagnosed the persistence-path drift across workspaces (history "disappearing" / counted as 0) and proposed storing data in a fixed, dedicated directory ([#4](https://github.com/feiyang-dev/dsh-usage-plugin/issues/4)).
 - **[@liu3734](https://github.com/liu3734)**: reported and diagnosed the Windows-only path handling / spawn issues on macOS (POSIX) and proposed the cross-platform fix ([#1](https://github.com/feiyang-dev/dsh-usage-plugin/issues/1)).
 
+## Changelog
+
+- [CHANGELOG.md](./CHANGELOG.md) — detailed notes for every release.
+
 ## License
 
 MIT © dsh-usage-plugin

package/README.zh.md

@@ -6,7 +6,6 @@
 
 [GitHub](https://github.com/feiyang-dev/dsh-usage-plugin) · [npm](https://www.npmjs.com/package/@feiyang666/dsh-usage-plugin) · MIT License
 
-> 📄 **本版本英文发布说明（What’s New in v1.14.0）**：[RELEASE_NOTES.md](./RELEASE_NOTES.md)
 
 **由开发者制作的 DeepSeek Harness 插件** —— 记录每一次模型调用的 token 用量与消耗，支持峰谷计费、余额查询、日历热力图与 CSV / JSON / PNG 导出。
 
@@ -35,8 +34,10 @@ dsh-usage-plugin 是 DeepSeek Harness 生态的**用量与消耗统计插件**
 > 支持 **Windows / macOS / Linux**：路径按当前平台处理（`node:path`），目录选择与「打开所在目录」均调用系统原生方式（macOS 用 `osascript` / `open`，Linux 用 `zenity` / `xdg-open`），余额查询与导出不依赖 Windows 专用命令。
 
 - **用量与消耗**：记录每次模型调用的 token 用量与缓存命中（输入·未命中 / 缓存命中 / 缓存写入 / 输出 / 推理 / 结束原因），按 DeepSeek 峰谷/基础价格计算消耗（工作日高峰时段按北京时间 9:00–12:00、14:00–18:00 计价；自 2026-08-23 起周末全天按空闲价计费）。模型名以请求参数为准如实显示（非 DeepSeek 模型不再显示为「未知模型」，无官方价格的模型消耗按 0 统计）。概览含「按模型」表与「按 API 服务商 × 模型」明细表（每个服务商一组，组内列出各模型的调用与高峰/空闲分列消耗），底部有总费用合计。概览还支持**日期筛选**（今天 / 近 7 天 / 近 30 天 / 全部，外加自定义起止区间），可将聚合统计限定到任意一天或日期范围。
-- **用量日历**：按月查看每日用量热力图（按消耗或调用数着色），悬停查看详情（含高峰 / 空闲消耗拆分）、点击某天查看当日调用明细与高峰/空闲消耗统计，附本月每日统计表（高峰消耗 / 空闲消耗 / 总消耗分列）与月度汇总。
+- **用量日历**：按月查看每日用量热力图（按消耗或调用数着色），悬停查看详情（含高峰 / 空闲消耗拆分）、点击某天查看当日调用明细与高峰/空闲消耗统计，附每日统计表（高峰消耗 / 空闲消耗 / 总消耗分列）与汇总。支持**日期范围筛选**（今天 / 近7天 / 近30天 / 全部 + 自定义起止日期）：筛选激活时每日统计表跨月显示范围内所有天、顶部卡片切换为「范围内调用 / 范围内消耗」并按范围汇总、热力图仅对范围内日期着色。
 - **缓存命中列表**：最新记录排在最前，支持 今天 / 近7天 / 近30天 / 全部 快捷筛选与自定义起止日期区间，汇总行与表尾合计区分高峰消耗 / 空闲消耗 / 总费用合计；列表分页渲染（每页 100 条），记录量大也不卡顿。
+- **中断调用如实呈现**：被中止 / 出错 / 超时（如手动停止生成、流中断）的调用在面板中标红显示「中断」徽标、结束原因（已中断 / 错误 / 超时）与消耗 `—`。这类调用官方后台仍会计入「API 请求次数」并按实际 token 计费，但 harness 不向插件上报 usage——插件按 0 token 记录它们，**调用次数与官方口径一致，消耗不受影响**；概览「调用次数」卡片会提示 `中断 N（未计费）`。
+- **本地统计 vs 官方后台的差异提示**：用量面板顶部固定显示说明横幅——本面板统计的是插件本地捕获的调用（官方价格 + 峰谷时段），与官方后台（platform.deepseek.com 用量页）相比金额可能更低：① 中断/出错/超时的调用官方仍按实际 token 计费而插件按 0 记录；② 账号下其他 API Key（其它应用/脚本）的调用不经过 DeepSeek Harness，官方包含而插件不包含；③ 精确对账可导出官方月度账单 CSV 对比。检测到中断调用时，横幅额外以红字显示「当前记录中有 N 次中断调用（未计费）」。
 - **价格表**：**DeepSeek 官方 API 价格表**（覆盖官方模型 `deepseek-v4-flash` / `deepseek-v4-flash-vision-exp` / `deepseek-v4-pro`），展示基础价与峰谷价（高峰/空闲）单价表，高峰价与空闲价分列展示，支持在面板内直接编辑价格并持久化（数据目录 `pricing.json`），也可一键恢复默认。
 - **剩余余额查询**：用当前配置的 `DEEPSEEK_API_KEY` 查询 DeepSeek 账户余额；并支持 **百炼 Token Plan 配额查询**（复用 `bl auth login --console` 的控制台 OAuth token，无需阿里云 AccessKey，展示本周配额已用百分比与重置时间）。
 - **导出**：CSV / JSON / **PNG 长图**（按最新在前展示，最多含最近 2000 条，超出会提示；PNG 报告含高峰 / 空闲消耗分列统计），可导出到任意目录（原生目录选择器），导出后自动打开所在目录。
@@ -311,6 +312,10 @@ pnpm dsh web
 - **[@mumuer1024](https://github.com/mumuer1024)**：报告并定位了持久化路径随会话工作区漂移导致历史数据"消失/统计为 0"的问题，提出把数据写到固定专用目录的方案（[#4](https://github.com/feiyang-dev/dsh-usage-plugin/issues/4)）。
 - **[@liu3734](https://github.com/liu3734)**：报告并定位 macOS（POSIX）下路径处理与 spawn 的 Windows 专用问题，提出跨平台修复方案（[#1](https://github.com/feiyang-dev/dsh-usage-plugin/issues/1)）。
 
+## 更新日志
+
+- [CHANGELOG.md](./CHANGELOG.md) —— 每次发布的详细更新内容。
+
 ## 许可
 
 MIT © dsh-usage-plugin