dsh-cost-meter 1.7.36 → 1.7.38

package/README.md

@@ -6,11 +6,11 @@
 
 **Session cost tracking plugin for the DeepSeek Harness web GUI (bilingual UI)**
 
-Per-conversation cost · daily totals · OpenCode Go subscription quota display · budget with usage percentage · official account balance · custom provider balance · balance progress bar · history · peak/off-peak pricing hours display (peak hours UTC 01:00–04:00, 06:00–10:00; from Aug 23, 2026 weekends are billed at off-peak prices all day, shown as “Weekend — all off-peak”) · pre-switch popup & system-notification alerts for peak/off-peak changes (position / lead time / alert type configurable) · one-click price sync from the official docs · Codex-style token usage heat grid · multi-vendor model pricing (built-in 90+ model price catalog with auto-matching) · mainstream Coding Plan quota queries & display (Anthropic / Z.ai / MiniMax / Kimi / OpenRouter / SiliconFlow / CommandCode / SCNet / Volcano Ark / Qwen / Xiaomi MiMo) plan/API dual-track billing (subscription quota vs pay-as-you-go money separated, per-1% & full-window token/equivalent-cost estimates with daily/weekly/monthly curves) · · quota strip above the input box (budget / Go / coding-plan usage in one row, toggleable)
+Per-conversation cost · daily totals · OpenCode Go subscription quota display · budget with usage percentage · official account balance · custom provider balance · balance progress bar · history · peak/off-peak pricing hours display (peak hours UTC 01:00–04:00, 06:00–10:00; weekends and Chinese public holidays are off-peak all day, with separate labels) · pre-switch popup & system-notification alerts for peak/off-peak changes (position / lead time / alert type configurable) · one-click price sync from the official docs · Codex-style token usage heat grid · multi-vendor model pricing (built-in 90+ model price catalog with auto-matching) · mainstream Coding Plan quota queries & display (Anthropic / Z.ai / MiniMax / Kimi / OpenRouter / SiliconFlow / CommandCode / SCNet / Volcano Ark / Qwen / Xiaomi MiMo) plan/API dual-track billing (subscription quota vs pay-as-you-go money separated, per-1% & full-window token/equivalent-cost estimates with daily/weekly/monthly curves) · · quota strip above the input box (budget / Go / coding-plan usage in one row, toggleable)
 
-[![version](https://img.shields.io/badge/version-1.7.36-4176E6)](https://github.com/Han-1413141/dsh-cost-meter)
+[![version](https://img.shields.io/badge/version-1.7.38-4176E6)](https://github.com/Han-1413141/dsh-cost-meter)
 
-**v1.7.36** prevents CommandCode quota failures caused by CDN responses that contain compressed bytes without a `Content-Encoding` header. Requests use `Accept-Encoding: identity` by default while retaining explicit overrides. See the [release notes](docs/release-notes/v1.7.36.md).
+**v1.7.38** adds [external usage snapshots](docs/external-usage.md#english): DSH and other processes sharing an account appear separately and in combined daily/monthly totals. See the [release notes](docs/release-notes/v1.7.38.md).
 
 [![npm](https://img.shields.io/npm/v/dsh-cost-meter?label=npm)](https://www.npmjs.com/package/dsh-cost-meter)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
@@ -40,6 +40,7 @@ Per-conversation cost · daily totals · OpenCode Go subscription quota display
 | Today's cost | Sidebar bottom (above the settings button) | “Today ¥x”, hover for call count and token details |
 | Budget box | Sidebar bottom (between the balance row and the settings button) | Rounded-square frame: budget, used %, progress bar, today's cost & share of budget, used/limit; ≥80% warning, ≥100% over-budget |
 | Summary cards | Settings page | Today / this month / cumulative cost and call counts |
+| External usage | Settings → Cost | [Read-only snapshots](docs/external-usage.md#english) from other processes on the same account; per-source tokens/calls/cost and recent days, plus DSH + external daily/monthly/all-time totals. Official balance reconciliation stays DSH-only. |
 | Token usage stats | Settings page (Cost section) | All-time token totals (input/cache/output/calls) + a Codex-style 26-week daily usage heat grid that fills the settings width; hover a cell for that day's detail |
 | Token Plan usage stats | Settings page (Usage) | Per enabled coding plan (incl. Go): per-1% quota and full-window token / equivalent-cost estimates for the current windows (sample delta / live ratio), plus daily/weekly/monthly usage curves; plan-channel amounts are equivalent-only and never touch real money (issue #64) |
 | Today's sessions | Settings page | Per-session call count, input/cache/output tokens and cost |
@@ -47,7 +48,7 @@ Per-conversation cost · daily totals · OpenCode Go subscription quota display
 | Pre-install history import | Automatic on first launch | After install/upgrade, the first launch automatically replays all host session logs to import conversations from before the plugin was installed (missing dates are rebuilt whole; existing dates only gain previously unknown sessions; idempotent and never double-counts live metering; costs priced at per-event historical rates); a manual re-run entry remains in Settings |
 | Budget settings | Settings page, top | Limit, period (today / month / cumulative / custom date range), used % |
 | Price table | Settings page | Per-model off-peak / peak prices (input/output shorthand supported; cache prices derived automatically); fully editable |
-| Peak/off-peak hours display | Settings / budget / today | Shows UTC peak hours 01:00–04:00 and 06:00–10:00 with the current tier; from Aug 23, 2026 weekends (Sat & Sun, Beijing time) are billed at off-peak prices all day and shown as “Weekend — all off-peak”; expanded view shows a peak/off-peak period strip (current period + countdown), collapsed (rail) view shows a vertical peak/off-peak progress bar; independently toggleable |
+| Peak/off-peak hours display | Settings / budget / today | Shows UTC peak hours 01:00–04:00 and 06:00–10:00 with the current tier; weekends and configured Chinese public holidays (Beijing dates) are off-peak all day, with separate labels; expanded view shows a period strip and countdown, collapsed view shows a vertical bar; independently toggleable |
 | Peak/off-peak switch popup alert | Global overlay | A full-width bracketed popup appears when the next tier switch is within the configured lead time (default 2 minutes, 1–30), with an alert-colored badge distinguishing entering peak vs off-peak; position selectable (**bottom-right / screen center**), alert type selectable (entering peak / entering off-peak / both), one alert per switch point; optionally **sends a browser (system) notification** (so you still get alerted when the page is backgrounded; requires granting notification permission); configured in the peak pricing panel in Settings, with a **one-click popup preview** (rendered by the real component — copy, position and notifications exactly as they will fire) |
 | Official price sync | Settings page | Fetches and parses the official pricing page, applies with one click; the **official price currency** is selectable (USD · English page / CNY · Chinese page) — CNY prices are booked at the display exchange rate and match the official CNY bill when displayed in CNY |
 | UI language | Settings → Display settings | Simplified Chinese / English / Follow browser (auto); switches instantly and auto-saves |
@@ -316,22 +317,22 @@ On Node.js 20, use `npm install -g pnpm@10` instead. See [pnpm installation and
 dsh plugin --profile web add dsh-cost-meter
 ```
 
-**PowerShell one-click script** (copy the whole line, paste, press Enter; pnpm is provisioned automatically, git is auto-detected — no clone needed; the install chain is **pinned to the release tag `v1.7.36`** — review the script before running):
+**PowerShell one-click script** (copy the whole line, paste, press Enter; pnpm is provisioned automatically, git is auto-detected — no clone needed; the install chain is **pinned to the release tag `v1.7.38`** — review the script before running):
 
 ```powershell
-irm https://raw.githubusercontent.com/Han-1413141/dsh-cost-meter/v1.7.36/install.ps1 | iex
+irm https://raw.githubusercontent.com/Han-1413141/dsh-cost-meter/v1.7.38/install.ps1 | iex
 ```
 
 **Or a plain command line** (the machine must already have pnpm and git; also pinned to the tag):
 
 ```sh
-dsh plugin --profile web add github:Han-1413141/dsh-cost-meter#v1.7.36
+dsh plugin --profile web add github:Han-1413141/dsh-cost-meter#v1.7.38
 ```
 
 Without git, use the GitHub tag archive:
 
 ```sh
-dsh plugin --profile web add https://github.com/Han-1413141/dsh-cost-meter/archive/refs/tags/v1.7.36.tar.gz
+dsh plugin --profile web add https://github.com/Han-1413141/dsh-cost-meter/archive/refs/tags/v1.7.38.tar.gz
 ```
 
 After installing, **restart** `dsh web` (plugin rows, the Typert manifest and the client bundle are all scanned at startup):
@@ -403,7 +404,7 @@ dsh plugin --profile web add link:./dsh-cost-meter  # symlink; edit lib/client.j
 - Price units match the official docs: **USD / 1M tokens**;
 - cost = cache-missed input × cache-miss + output × output + (cache read + cache write) × cache-hit (cache writes follow the legacy official rule and are billed at the hit price);
 - **Pure two-tier peak/off-peak pricing** (the official scheme since 2026-08): peak hours (01:00–04:00, 06:00–10:00 UTC) bill at the peak price and all other hours at the off-peak price (off-peak = half of peak). The base tier equals the off-peak tier, and billing falls back to off-peak when peak/off-peak is disabled; the Settings page shows the live tier (peak / off-peak); the budget/today's cost area shows a peak/off-peak period strip (current/next period with countdown), and the collapsed rail shows a vertical peak/off-peak progress bar;
-- **Weekend all-off-peak rule** (official notice, effective 2026-08-23 00:00 Beijing time): weekends (Saturday & Sunday by the Beijing calendar) no longer differentiate peak/off-peak and are billed entirely at off-peak prices; the period strip shows “Weekend — all off-peak” with the countdown pointing to Monday's first peak window. Charges before that moment still follow the previous rules (the first affected weekend covers Sunday only);
+- **Weekends and Chinese public holidays**: weekends are off-peak all day from 2026-08-23 00:00 Beijing time, including work-shift weekends. Chinese public holidays are also off-peak all day. `peakHolidays` contains Beijing dates in `YYYY-MM-DD` format and defaults to the published 2026 Mid-Autumn and National Day dates after the peak-pricing change; edit the list in Settings → Cost → Peak pricing for future holidays. The period strip labels holidays separately and counts down to the next actual price change. Historical DeepSeek costs are recalculated once from complete session logs; rows without complete logs keep their recorded amounts;
 - **Historical billing correctness**: calls before 2026-08-16 16:00 UTC (the peak-era boundary) are billed at the base prices of that time, and later calls at the two-tier scheme;
 - The ledger always stores amounts in **USD**; currency and FX rate only affect display (default 1 USD = 7.2 CNY, configurable);
 - The session badge is **billed exactly** at the moment each call is made (host-exported per-call cost), just like daily/monthly/cumulative totals and the budget;

package/README.zh-CN.md

@@ -6,11 +6,11 @@
 
 **DeepSeek Harness 会话费用统计插件(界面中英双语)**
 
-本会话费用 · 当日费用 · OpenCode Go 订阅额度显示 · 预算与已用百分比 · 官方账户余额 · 自定义 Provider 余额查询(可配任意 HTTP 端点) · 余额三段进度条 · 历史记录 · 峰谷计价时段显示(UTC 01:00–04:00、06:00–10:00 为峰时段;2026-08-23 起周末全天按谷价,显示「周末时段——全谷价」) · 峰/谷切换前弹窗与系统通知提醒(位置/提前量/提醒类型可配) · 官方价格一键同步 · 类 Codex Token 用量热图 · 多厂商多模型价格计费(内置 90+ 模型价格目录与自动匹配) · 主流 Coding Plan 额度查询与显示(Anthropic / Z.ai / MiniMax / Kimi / OpenRouter / SiliconFlow / CommandCode / SCNet / 火山方舟 / 千问 / 小米 MiMo 十一家,含 Volcano Ark AK/SK 签名与 MiMo 控制台 Cookie 查询) · Plan/API 双轨计费(订阅额度与按量金额分离统计,每 1% 额度与满窗的 token/等值金额估算及日/周/月曲线) · 输入框上方额度横条(预算/Go/Coding Plan 用量一条横排显示,可开关)
+本会话费用 · 当日费用 · OpenCode Go 订阅额度显示 · 预算与已用百分比 · 官方账户余额 · 自定义 Provider 余额查询(可配任意 HTTP 端点) · 余额三段进度条 · 历史记录 · 峰谷计价时段显示(UTC 01:00–04:00、06:00–10:00 为峰时段;周末与中国法定假日全天按谷价,分别标注) · 峰/谷切换前弹窗与系统通知提醒(位置/提前量/提醒类型可配) · 官方价格一键同步 · 类 Codex Token 用量热图 · 多厂商多模型价格计费(内置 90+ 模型价格目录与自动匹配) · 主流 Coding Plan 额度查询与显示(Anthropic / Z.ai / MiniMax / Kimi / OpenRouter / SiliconFlow / CommandCode / SCNet / 火山方舟 / 千问 / 小米 MiMo 十一家,含 Volcano Ark AK/SK 签名与 MiMo 控制台 Cookie 查询) · Plan/API 双轨计费(订阅额度与按量金额分离统计,每 1% 额度与满窗的 token/等值金额估算及日/周/月曲线) · 输入框上方额度横条(预算/Go/Coding Plan 用量一条横排显示,可开关)
 
-[![version](https://img.shields.io/badge/version-1.7.36-4176E6)](https://github.com/Han-1413141/dsh-cost-meter)
+[![version](https://img.shields.io/badge/version-1.7.38-4176E6)](https://github.com/Han-1413141/dsh-cost-meter)
 
-**v1.7.36**：修复 CDN 返回压缩数据却缺失 `Content-Encoding` 时 CommandCode 额度解析失败；请求默认协商明文响应，保留调用方显式指定的编码。详见[更新说明](docs/release-notes/v1.7.36.md)。
+**v1.7.38**：新增[外部用量快照](docs/external-usage.md#中文)，按来源区分 DSH 与同账户其他进程的消耗，并显示日/月合计。详见[更新说明](docs/release-notes/v1.7.38.md)。
 
 [![npm](https://img.shields.io/npm/v/dsh-cost-meter?label=npm)](https://www.npmjs.com/package/dsh-cost-meter)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
@@ -40,6 +40,7 @@
 | 当日费用 | 侧边栏底部(设置按钮上方) | 「今日 ¥x」,悬停见调用次数与 token 明细 |
 | 预算图框 | 侧边栏底部(余额行与设置按钮之间) | 圆角方形图框:预算、已用%、进度条、今日费用与占预算%、已用/额度,≥80% 预警、≥100% 超支 |
 | 汇总卡片 | 设置页 | 今日 / 本月 / 累计费用与调用次数 |
+| 外部用量 | 设置 → 费用 | 同账户其他进程通过[只读快照](docs/external-usage.md#中文)提供用量；按来源查看 token、调用、费用和近期每日记录，并显示 DSH + 外部的日/月/累计合计。官方余额对账仍只用 DSH 账本。 |
 | Token 用量统计 | 设置页(费用设置) | 历史累计 token 总量(输入/缓存/输出/调用)+ 类 Codex 的 26 周每日用量方格热图,横向铺满设置页宽度,悬停见当日明细 |
 | Token Plan 用量统计 | 设置页(用量) | 各已启用 Coding Plan(含 Go)当前窗口的「每 1% 额度」与「满窗 100%」对应的 token 数与等值金额估算(采样差分/当前用量折算),附每日/每周/每月用量曲线;Plan 类调用金额只记等值,不动真金白银(issue #64) |
 | 今日会话明细 | 设置页 | 每个会话的调用次数、输入/缓存/输出 token 与费用 |
@@ -48,7 +49,7 @@
 | 导入安装前历史 | 首次启动自动 | 安装/升级后首次启动自动回放宿主全部会话日志,把未装插件时期的对话导入账本(缺失日期整日重建,已有日期只补未知会话,幂等不与实时计费重复;金额按事件时刻历史价回推);设置页保留手动重跑入口 |
 | 预算设置 | 设置页顶部 | 额度、周期(今日/本月/累计/自定义日期区间)、已用% |
 | 价格表 | 设置页 | 每模型 谷时/峰时 两档价格(支持 input/output 简写,缓存价自动补齐),增删改自由 |
-| 峰谷计价时段显示 | 设置页 / 预算 / 今日费用 | 显示 UTC 峰时段 01:00–04:00、06:00–10:00 与当前档位;2026-08-23 起周末(周六及周日,北京时间)全天按谷价计费并显示「周末时段——全谷价」;展开态显示峰时/平价时段条(当前时段 + 倒计时),收起(rail)态显示竖向峰谷进度条,可单独开关 |
+| 峰谷计价时段显示 | 设置页 / 预算 / 今日费用 | 显示 UTC 峰时段 01:00–04:00、06:00–10:00 与当前档位；周末和已配置的中国法定假日（北京日期）全天按谷价计费并分别标注；展开态显示时段条与倒计时，收起态显示竖向条，可单独开关 |
 | 峰/谷切换弹窗提醒 | 全局浮层 | 距进入峰/谷时段不足设定提前量(默认 2 分钟,1-30 可配)时全屏色条徽标弹窗(提醒色区分进入峰/谷);弹窗位置可选**右下角 / 屏幕中心**,提醒类型可选(进入峰 / 进入谷 / 峰和谷),同一切换点只提醒一次;可选**同步发送浏览器(系统)通知**(页面最小化也能收到,需授权通知权限);设置页峰谷计价面板内配置,并可**一键预览弹窗效果**(真实组件渲染,文案/位置/通知与实际触发完全一致) |
 | 官方价格同步 | 设置页 | 抓取解析官方定价页,一键应用;可选**官方价格币种**(美元·英文官方页 / 人民币·中文官方页),人民币价按展示汇率折算入账、展示人民币时与官方账单一致 |
 | 界面语言 | 设置页 → 显示设置 | 简体中文 / English / 跟随浏览器(自动);切换即时生效并自动保存 |
@@ -316,22 +317,22 @@ Node.js 20 请改用 `npm install -g pnpm@10`。版本要求见 [pnpm 官方安
 dsh plugin --profile web add dsh-cost-meter
 ```
 
-**PowerShell 一键脚本**(复制整行粘贴回车;自动补齐 pnpm、自动探测 git,无需克隆仓库;安装链**固定到发布 tag `v1.7.36`**,建议先下载审阅再运行):
+**PowerShell 一键脚本**(复制整行粘贴回车;自动补齐 pnpm、自动探测 git,无需克隆仓库;安装链**固定到发布 tag `v1.7.38`**,建议先下载审阅再运行):
 
 ```powershell
-irm https://raw.githubusercontent.com/Han-1413141/dsh-cost-meter/v1.7.36/install.ps1 | iex
+irm https://raw.githubusercontent.com/Han-1413141/dsh-cost-meter/v1.7.38/install.ps1 | iex
 ```
 
 **或直接命令行**(机器上需已有 pnpm 与 git;同样固定到 tag):
 
 ```sh
-dsh plugin --profile web add github:Han-1413141/dsh-cost-meter#v1.7.36
+dsh plugin --profile web add github:Han-1413141/dsh-cost-meter#v1.7.38
 ```
 
 没有 git 时可用 GitHub tag 打包直链:
 
 ```sh
-dsh plugin --profile web add https://github.com/Han-1413141/dsh-cost-meter/archive/refs/tags/v1.7.36.tar.gz
+dsh plugin --profile web add https://github.com/Han-1413141/dsh-cost-meter/archive/refs/tags/v1.7.38.tar.gz
 ```
 
 安装后**重启** `dsh web`(插件行、Typert 清单与客户端 bundle 均在启动时扫描):
@@ -403,7 +404,7 @@ dsh plugin --profile web add link:./dsh-cost-meter  # 符号链接,改 lib/clien
 - 价格单位与官方文档一致:**美元 / 1M tokens**;
 - 成本 = 未命中输入 × cache-miss + 输出 × output + (缓存读 + 缓存写) × cache-hit(缓存写沿用官方历史规则按命中价计费);
 - **纯峰谷两档计价**(2026-08 起官方方案):峰时段(01:00–04:00、06:00–10:00 UTC)按峰时价,其余按谷时价(谷时价 = 峰时价的一半);基础档与谷时档同价,未启用峰谷时按谷时价计;设置页实时显示当前档位(峰时段/谷时段);预算与今日费用区域显示峰时/平价时段条(当前/下一时段与倒计时),收起态显示竖向峰谷进度条;
-- **周末全谷价新规**(官方通知,2026-08-23 00:00 北京时间起):周末(周六及周日,按北京日历)全天不再区分峰谷,统一按谷价计费;时段条显示「周末时段——全谷价」并倒计时至下周一首个峰时段;该时刻之前的费用仍按原峰谷规则结算(首个受覆盖的周末仅周日全天);
+- **周末与法定假日全天谷价**：自 2026-08-23 北京时间 00:00 起，周六、周日全天谷价，调休上班的周末也不例外。中国法定假日同样全天谷价。`peakHolidays` 为 `YYYY-MM-DD` 北京日期数组，默认预置 2026 年峰谷规则生效后的中秋和国庆日期；以后可在 设置 → 费用 → 峰谷计价 中修改。时段条单独标注假日并倒计时至下一次实际价格变化。历史 DeepSeek 金额升级时从完整会话日志一次性重算；日志不完整的记录保留原金额;
 - **历史计费正确性**:2026-08-16 16:00 UTC(峰谷时代分界)之前的调用按当时的基础价计费,之后的调用按峰谷两档;
 - 账本金额恒以**美元**存储,币种/汇率仅影响显示(默认 1 USD = 7.2 CNY,可改);
 - 会话徽章与当日/月度/累计、预算一样,按每次调用的**实际时刻精确计费**(宿主导出的逐次成本);

package/docs/external-usage.md

@@ -0,0 +1,61 @@
+# External usage snapshots / 外部用量快照
+
+## English
+
+Another local process can write `$DSH_HOME/storages/cost-meter/external_usage.json` to add usage from the **same account** that bypasses DSH. The plugin reads the file on each state refresh. It never calls Hindsight or any other external service. Settings → Cost shows DSH and external usage separately, plus combined today/month/all-time totals. Expand a source to see its token buckets, calls, costs and up to 90 recent daily rows. DSH session totals and official balance reconciliation remain DSH-only.
+
+Write the entire snapshot to a temporary file in the same directory, then atomically rename it to `external_usage.json`. Replace the file on every refresh; **do not append deltas**. The same snapshot can be read repeatedly without double-counting. Use ISO 8601 timestamps with `Z` or an explicit offset. `source` is a stable name (1–64 characters), not a model name. Up to eight sources are accepted. The file is capped at 512 KiB; each source can supply up to 3,660 daily summaries, or the whole file can supply up to 5,000 individual records. Snapshots older than 24 hours are marked stale; those older than 30 days, malformed, oversized, or unreadable are ignored. The producer should refresh regularly and keep historical days in each replacement snapshot. All-time totals cover only the days supplied by the producer.
+
+**Daily summary mode**: `input` means uncached input, `cached` means cache-read input, and `cacheWrite` is a separate optional bucket. All buckets are mutually exclusive. `costUsd` is the exact USD cost calculated by the producer; it is required because daily totals cannot reconstruct peak/off-peak or long-context prices for individual calls. `calls` is the number of calls. Optional `reasoning` is reported separately. Amounts are converted to the selected display currency by the plugin.
+
+```json
+{
+  "fetchedAt": "2026-09-26T09:00:00Z",
+  "sources": [
+    {
+      "source": "Hindsight",
+      "days": {
+        "2026-09-25": {
+          "input": 4888706,
+          "output": 592536,
+          "cached": 1082880,
+          "calls": 363,
+          "costUsd": 1.2345
+        }
+      }
+    }
+  ]
+}
+```
+
+**Call record mode**: send one record per completed call with a stable unique `id` within that source. The plugin calculates USD cost using its configured provider/model prices and each call's timestamp, including the configured DeepSeek peak/off-peak rules. Current price settings are reapplied when the snapshot is read, so use daily `costUsd` summaries if historical costs must remain fixed. An unpriced provider/model invalidates the snapshot instead of silently recording zero cost. `input`, `output`, `cached`, optional `cacheWrite` and `reasoning` have the same meanings as in summary mode. Each record represents one call.
+
+```json
+{
+  "fetchedAt": "2026-09-26T09:00:00Z",
+  "source": "Hindsight",
+  "records": [
+    {
+      "id": "request-abc123",
+      "at": "2026-09-25T08:40:00Z",
+      "provider": "deepseek",
+      "model": "deepseek-chat",
+      "input": 1200,
+      "output": 250,
+      "cached": 100
+    }
+  ]
+}
+```
+
+A snapshot can contain a single top-level source as above, or a `sources` array. Each source uses either `days` or `records`, never both. Do not include calls already reported to DSH; source separation prevents same-name model collisions but cannot detect duplicate calls across systems. The file must contain no API keys or other credentials. The budget widget continues to use DSH's own ledger; combined totals appear in the external usage section.
+
+## 中文
+
+其他本地进程可将同一账户、但绕过 DSH 的用量写入 `$DSH_HOME/storages/cost-meter/external_usage.json`。插件每次刷新状态时读取，不直接请求 Hindsight 等服务。设置 → 费用按来源显示外部用量、DSH 与外部合计，以及近 90 天的逐日数据；DSH 会话金额和官方余额对账仍只使用 DSH 账本。
+
+采集器先在同目录写完整临时文件，再原子重命名为 `external_usage.json`。每次刷新替换整份快照，**不要追加增量**；重复读取不会重复计费。时间使用带 `Z` 或时区偏移的 ISO 8601。`source` 是稳定的来源名称，不是模型名。最多 8 个来源；文件上限 512 KiB；每来源最多 3660 条日汇总，或整份快照最多 5000 条调用记录。超过 24 小时未更新会标为过期；超过 30 天、损坏、过大或不可读的快照会被忽略。刷新时应保留所需的历史日期；累计费用只覆盖采集器提供的日期。
+
+上方第一例为**每日汇总**：`input` 是非缓存输入，`cached` 是缓存读取，可选 `cacheWrite` 是独立缓存写入；各桶互不重叠。`costUsd` 是采集器计算的准确美元费用，必须提供，因为日合计不能还原每次调用的峰谷或长上下文价格。`calls` 是调用次数，`reasoning` 可单独提供。插件按当前显示汇率展示费用。
+
+第二例为**逐次记录**：每次完成的调用提供来源内唯一且稳定的 `id`。插件按 `at`、provider/model 及现有价表计算美元费用，包括 DeepSeek 峰谷规则。快照每次读取会应用当前价格设置；若历史费用必须固定，请使用含 `costUsd` 的日汇总。未知价格的模型会使整份快照失效，避免误记零费用。每个来源只能在 `days` 和 `records` 中选一种。不要包含已由 DSH 记录的调用；来源分栏能区分同名模型，但无法自动识别跨系统重复调用。文件中不要存放密钥。预算图框仍按 DSH 账本计算；合计显示在外部用量区。

package/lib/backfill.js

@@ -485,6 +485,7 @@ export function replaySessionRecords(records, config, wantDates = null) {
       enabled: resolved.billingMode === 'deepseek-peak' && config?.peakEnabled === true,
       effectiveAtMs: Date.parse(config?.peakEffectiveAt ?? ''),
       windows: config?.peakWindows,
+      holidays: config?.peakHolidays,
     }
     // 官方价格币种为人民币(issue #47)时,DeepSeek 主表计出的成本为人民币,
     // 按展示汇率折算为美元入账——与 store.account() 完全同口径。
@@ -898,10 +899,10 @@ export async function importLegacyHistory(ledger, sessionsRoot) {
  * @param includeBucket - 可选的 (providerModelKey, date) 过滤器，仅修复目标价格路径。
  * @returns {{ scanned, recostedSessions, skippedSessions, recostedDays }}。
  */
-export async function recomputeLedgerPricingBasis(ledger, sessionsRoot, includeBucket) {
+export async function recomputeLedgerPricingBasis(ledger, sessionsRoot, includeBucket, onlySessionIds = null) {
   const result = { scanned: 0, recostedSessions: 0, skippedSessions: 0, recostedDays: 0 }
   const bySession = new Map()
-  for await (const records of sessionBillingRecords(ledger, sessionsRoot)) {
+  for await (const records of sessionBillingRecords(ledger, sessionsRoot, onlySessionIds)) {
     if ((result.scanned += 1) % 8 === 0) await new Promise(resolve => setImmediate(resolve))
     let replayed
     try {