dsh-token-use 0.1.1 → 0.2.0

package/README.en.md

@@ -4,26 +4,44 @@
 
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
-A real-time token usage plugin for DeepSeek Harness: install it, then read your usage in **Settings → Token usage** (the plugin adds its own top-level Settings entry). The page refreshes every 5 seconds and stays quiet while the tab is hidden — no wasted polling.
+A real-time token usage and cost plugin for DeepSeek Harness: install it, then read your usage in **Settings → Token usage** (the plugin adds its own top-level Settings entry). The page refreshes every 5 seconds and stays quiet while the tab is hidden — no wasted polling.
 
 ## Features
 
-- **Totals card** — total (input + output + cache), input, output, cache read, cache write, reasoning, calls.
+- **Cost card** — spend estimated live from DeepSeek's published prices × the usage recorded here, with peak/off-peak rates. Every card (totals, trend, by model, by day, by project) carries an amount.
+- **Daily price book** — the official pricing page is fetched once a day at **12:00** and cached locally, so restarts keep it and an offline machine falls back to a built-in snapshot.
+- **Totals card** — estimated cost, total (input + output + cache), input, output, cache read, cache write, reasoning, calls.
+- **Per-model pricing** — cache-hit input, cache-miss input and output are priced separately per model; anything that is not a DeepSeek model (claude, gpt, …) is never counted and shows `—`.
 - **Range tabs** — by day / by month / all, with a date or month picker; defaults to by day = today.
 - **Model filter** — the dropdown beside the range tabs narrows every breakdown to one model (including that model's project and per-day rows); defaults to all models.
-- **Trend chart** — five series (total, input, output, cache read, calls) over the last 30 days, drawn with a tree-shaken ECharts bundle that ships inside the plugin (no CDN). The token series share the left axis, calls use the right one, and the axis tooltip shows every dimension for the hovered day. Rendering is imperative, so moving the mouse never re-renders React.
+- **Trend chart** — drawn with a tree-shaken ECharts bundle that ships inside the plugin (no CDN). Cache read / input / output stack into an **area composition** whose top edge is the total (with a total reference line), each day's amount is drawn as **cost bars** against a ¥ axis, and calls live in the tooltip. The card switches between **7 / 30 / 90 days (7 by default)**. A day without usage is a real zero (stacking needs it), and the tooltip still names it; tick labels keep one unit across an axis and monotone smoothing never overshoots. Rendering is imperative, so moving the mouse never re-renders React.
 - **Unit switch** — 亿 / 万 / 千 in Chinese, B / M / K in English; remembered per browser.
-- **Detail tables** — by model, by day and by project, each with a total column.
+- **Detail tables** — by model, by day and by project, each with an amount column (hover a row for its rates) and a total column.
+
+## The amounts are estimates
+
+The amount card (the last of the totals cards) carries an ⓘ icon — hover it for the full note:
+
+> Amounts are estimates: DeepSeek's published prices × the usage recorded here, priced with the peak/off-peak rate in effect at each call. Official price changes, cache accounting and reporting lag can make this differ from your actual bill — the official settlement prevails.
+
+How it is computed:
+
+- Priced fields: `inputTokens` (cache-miss input), `cacheReadTokens` (cache-hit input), `outputTokens` (includes reasoning); DeepSeek does not charge for cache writes.
+- Peak/off-peak: the pricing page publishes a peak window (currently 01:00–04:00 and 06:00–10:00 UTC on weekdays, with off-peak at half price). **Each record is priced with the rate in effect when it happened**, so a later price change never rewrites history.
+- DeepSeek models only: a model whose name does not contain `deepseek` (claude, gpt, minimax, …) contributes no amount, and neither does a DeepSeek name that matches no official price entry — both are listed in the ⓘ note.
+- **What it leaves out**: auxiliary calls such as web search and session-title generation are billed, but their tokens stay server-side where nothing local can read them. They are therefore counted by number and never guessed at, and the ⓘ note lists how many happened in the window — which makes this amount a **lower bound** on the bill. Checked against an official hourly export: every call we do count matches it token for token and tier for tier.
+- Currency defaults to CNY (the Chinese pricing page); set `currency: USD` to read the English one.
+
 
 ## Why it is worth installing
 
 You are burning tokens, but you cannot say where: which project costs the most, which model leans hardest on the cache, how much this week grew over last week.
 
-**dsh-token-use turns that into numbers you can read at a glance.** It folds every call as it happens, then lays totals, input, output, cache hits, reasoning and call counts out in the settings page, with filters by model, day, month or project and a smooth trend line that tells the story. Install it and you are done: nothing to configure, no session restart, and it never pops up while you are coding.
+**dsh-token-use turns that into numbers you can read at a glance.** It folds every call as it happens, then lays cost, totals, input, output, cache hits, reasoning and call counts out in the settings page, with filters by model, day, month or project and a smooth trend line that tells the story. Install it and you are done: nothing to configure, no session restart, and it never pops up while you are coding.
 
 The most expensive cost is the one you cannot see — make it visible.
 
-![Token usage panel: range and model filters, totals cards, the 30-day trend chart and the by-model table](assets/token-usage.jpg)
+![Token usage panel: range and model filters, the cost and totals cards, the 7/30/90-day trend chart (stacked composition + cost bars), and the by-model / by-day / by-project tables with amounts](assets/token-usage.jpg)
 
 ## Install
 
@@ -40,8 +58,9 @@ dsh plugin --profile web add /path/to/dsh-token-use
 
 ## Performance design
 
-- The host side **never polls, never writes to disk and sets no timers**: it folds usage in O(1) increments from the `session/event` bus (one dictionary addition per `assistant/message`).
+- The host side **never polls and sets no periodic timer** other than the daily price refresh: it folds usage in O(1) increments from the `session/event` bus (one dictionary addition and one multiplication per `assistant/message`).
 - History is rebuilt **once** at boot by streaming `$DSH_HOME/sessions/**/session.jsonl.zstd` (native zstd from `node:zlib`), yielding the event loop between files (`scheduler.yield()`) so session handling is never blocked. A per-session sequence watermark de-duplicates the rebuild against live events, whatever order they arrive in.
+- **Price refresh**: one HTTPS GET per day at 12:00 local time (15 s timeout, retried an hour later on failure), stored atomically in `$DSH_HOME/dsh-token-use/pricing.json` (up to 30 snapshots). A restart reads the cache synchronously and does not re-fetch; a failed fetch falls back to the built-in snapshot, so the panel always shows numbers.
 - One read-only JSON endpoint is exposed: `GET /dsh-token-use` (loopback only, in-memory snapshot, `no-store`).
 
 ```sh
@@ -54,6 +73,8 @@ curl 'http://127.0.0.1:3080/dsh-token-use?day=2026-09-10'
 curl 'http://127.0.0.1:3080/dsh-token-use?model=deepseek-v4-flash'
 ```
 
+Every bucket carries a `cost` (the estimate); `pricing` holds the current price book, when it was fetched and when it refreshes next; `modelPricing` maps each observed model to its rates or to the reason it carries no amount.
+
 ## Development
 
 ```sh
@@ -70,6 +91,8 @@ Published to npm as `dsh-token-use`; its `repository` field points back here, wh
 - `input` / `output` — input and output tokens as reported by the API.
 - `cacheRead` / `cacheWrite` — prompt cache read/write tokens (the API counts cache reads on the input side for billing).
 - `reasoning` — reasoning tokens.
+- `cost` — the estimate from those fields and the rates in effect; cache writes are not billed and reasoning is already inside output, so nothing is counted twice.
+- `auxiliary` — how many auxiliary calls in the window the amount leaves out (`search` web search, `title` session titles).
 - Model attribution — the model of the session's most recent `request/header`; small calls that carry no usage record (title generation, for example) are not counted.
 - Project attribution — the `cwd` in the session's creation header (live events read `session.header.cwd`, history reads the log header); subagent and forked sessions inherit their parent's project; usage that cannot be attributed yet is held and back-filled as soon as it resolves, only reaching `(no cwd)` after 30 seconds. |
 
@@ -80,11 +103,12 @@ These differences are already handled before anyone else installs the plugin:
 | Dimension | Notes |
 | --- | --- |
 | Runtime | Requires **dsh web ≥ 0.1.0-rc.6** (the settings sidebar `settings.section` slot). The host half uses Node built-ins only; zstd decoding uses `node:zlib` (built in from Node 22.15, and dsh itself requires ^22.19 \|\| >=24, so it is always present). |
-| Data directory | Resolved from `$DSH_HOME` (environment variable, defaulting to `~/.dsh`), matching dsh's own `dsh-home-paths` rules; a custom home works too. The plugin is **read-only** — it writes nothing. |
+| Settings rail glyph | The shell hardcodes the rail glyph per section id and falls back to the same settings gear for every unknown id (ours and the market plugin's alike) — a slot registration cannot name an icon. The plugin masks its own bar-chart glyph over that gear with a structure-only selector anchored on a marker class inside its own label: no dependency on the shell's hashed class names, and if a future shell changes the markup the selector stops matching and the gear simply stays (never two glyphs), with no functional impact. |
+| Data directory | Resolved from `$DSH_HOME` (environment variable, defaulting to `~/.dsh`), matching dsh's own `dsh-home-paths` rules; a custom home works too. Recorded usage is **read-only**; the only file written is the price cache `$DSH_HOME/dsh-token-use/pricing.json` (atomic replace), and `pricing.enabled: false` turns both the fetch and that write off. |
 | Session formats | Handles `session.jsonl[.zstd]` (multi-frame zstd with checksums), the versioned next generation `session.v<N>.jsonl[.zstd]` that dsh leaves alongside the old file after a migration, and plaintext `.jsonl`. A session is read from its **highest-version generation only**, so a migration never double counts; `.bak`, `.corrupt-*` and `session.lock` are skipped, and a single corrupt frame only raises `scan.skipped`. |
 | Directory layout | Follows the official JSONL persistence layout `sessions/<project dir>/<session dir>/`, reading every session independently. |
 | Accounting | Some providers (the pi-ai adapter, for instance) fold reasoning tokens into output, so a `reasoning` column of 0 is normal there; calls that record no `usage` (title generation, web search) are not counted; model attribution uses the session's most recent `request/header`. |
-| Network | The endpoint is **loopback-only** by default. On a LAN deployment (trustedHosts configured) set `allowRemote: true` in the profile patch; it still accepts same-origin requests only, and the client names the reason when it sees a 403. |
+| Network | The endpoint is **loopback-only** by default. On a LAN deployment (trustedHosts configured) set `allowRemote: true` in the profile patch; it still accepts same-origin requests only, and the client names the reason when it sees a 403. Outbound traffic has exactly one purpose: fetching the official pricing page from `api-docs.deepseek.com` once a day (repoint it with `pricing.url`, or turn it off with `pricing.enabled: false`). |
 | Performance | The history rebuild runs on a **worker thread**, so the host event loop is never blocked; events arriving meanwhile are buffered and replayed after the scan, with the session sequence watermark keeping the two folds distinct. Only event increments happen afterwards. |
 | Multiple instances | Every `$DSH_HOME` is counted separately; several profiles under one home share the `sessions` directory, so their usage is merged. |
 
@@ -97,6 +121,11 @@ These differences are already handled before anyone else installs the plugin:
     endpoint: /dsh-token-use
     scanAtBoot: true    # false counts only usage recorded after the plugin starts
     allowRemote: false  # set true for LAN (non-loopback) access; same-origin only
+    pricing:
+      enabled: true     # false turns the daily fetch off (built-in/existing snapshots only)
+      currency: CNY     # CNY (Chinese pricing page, 元) or USD (English page, $)
+      refreshHour: 12   # local hour of the daily fetch
+      # url: https://api-docs.deepseek.com/zh-cn/quick_start/pricing  # custom pricing page
 ```
 
 ## After installing

package/README.md

@@ -4,26 +4,44 @@
 
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
-DeepSeek Harness 实时 Token 用量插件：安装后在 **设置 → Token 用量** 查看用量（自带设置侧边栏一级入口），页面每 5 秒刷新（页面隐藏时暂停，零轮询浪费）。
+DeepSeek Harness 实时 Token 用量与消费金额插件：安装后在 **设置 → Token 用量** 查看用量（自带设置侧边栏一级入口），页面每 5 秒刷新（页面隐藏时暂停，零轮询浪费）。
 
 ## 功能
 
-- **总量卡片**：总计（输入+输出+缓存）、输入、输出、缓存读、缓存写、推理、调用次数。
+- **金额卡片**：按 DeepSeek 官方定价 × 本地用量实时估算消费金额（含高峰/空闲时段倍率），每张卡片（总量、趋势、按模型、按日期、按项目）都带金额字段。
+- **官方定价自动更新**：每天 **12:00** 抓取一次官方定价页并缓存到本地，重启不丢、断网可用内置快照兜底。
+- **总量卡片**：金额（估算）、总计（输入+输出+缓存）、输入、输出、缓存读、缓存写、推理、调用次数。
+- **按模型区分单价**：输入/输出/缓存命中分别按模型的官方单价计价；非 DeepSeek 模型（claude、gpt 等）一律不计金额，用 `—` 标出。
 - **范围筛选**：按天 / 按月 / 全部三个 tab，默认「按天=今天」；可选日期、月份。
 - **模型筛选**：时间筛选旁的下拉框按模型过滤（含该模型的项目/按天维度明细），默认全部模型。
-- **用量趋势折线图**：基于 ECharts（按需打包、随插件离线分发，不依赖 CDN）展示最近 30 天总计、输入、输出、缓存命中、调用次数五条折线；token 维度共用左轴，调用次数用右轴，悬停轴提示显示当日全部明细。图表用命令式渲染，鼠标移动不触发 React 重渲染。
+- **用量趋势图**：基于 ECharts（按需打包、随插件离线分发，不依赖 CDN）。缓存命中/输入/输出按**堆叠面积**画出构成，上沿即总计（另有一条总计参考线），每天金额用**金额柱**走右轴（¥），调用次数在悬停提示里。卡片右上角可切 **7 / 30 / 90 天（默认 7 天）**。无用量日为真实 0 值（堆叠才准），悬停会写明「当日无用量」；刻度单位整轴统一，单调平滑不过冲。图表用命令式渲染，鼠标移动不触发 React 重渲染。
 - **单位切换**：中文（亿 / 万 / 千）与英文（B / M / K）一键切换，记忆选择。
-- **明细表**：按模型、按日期、按项目三张表，含总计列。
+- **明细表**：按模型、按日期、按项目三张表，含金额列（悬停显示该模型单价）与总计列。
+
+## 金额是估算值
+
+金额卡片（总量卡片里的最后一个）右上角有个 ⓘ，鼠标移入即显示完整口径说明：
+
+> 金额为估算值：按 DeepSeek 官网定价 × 本地记录用量推算，并已按调用时刻区分高峰/空闲单价。受官方调价、缓存计费口径与统计延时影响，可能与实际账单有出入，请以官网结算金额为准。
+
+口径细节：
+
+- 计价字段：`inputTokens`（缓存未命中输入）、`cacheReadTokens`（缓存命中输入）、`outputTokens`（含推理）；缓存写官方不计费。
+- 高峰/空闲：官网每日公布高峰时段（当前为 UTC 工作日 01:00–04:00、06:00–10:00，空闲价格为高峰的一半），**每条记录按它发生时刻的单价计价**，之后调价不会改写历史。
+- 只统计 DeepSeek 模型：模型名里不含 `deepseek` 的（claude、gpt、minimax…）不计金额；名字模糊匹配不到官方定价的 DeepSeek 模型也不计，并在 ⓘ 说明里列出。
+- **少算的部分**：联网搜索、会话标题这类辅助调用**会产生账单，但 token 数只在服务端、本地取不到**，所以只计次数、不猜金额，ⓘ 说明里列出本期次数。因此这里的金额是**账单下限**，实际只会略高。用官方逐小时导出核对过：我们统计到的请求，token 数与高峰/空闲单价和官方逐行一致。
+- 币种默认人民币（取官网中文页），可在配置里切成 `USD`（取官网英文页）。
+
 
 ## 为什么值得装
 
 你在烧 token，但你说不清烧在哪：哪个项目最贵、哪个模型最吃缓存、这周比上周涨了多少。
 
-**dsh-token-use 把这些变成一眼看得懂的数字。** 它跟着每一次调用实时累加，把总量、输入、输出、缓存命中、推理和调用次数摊开在设置页里，按模型、按天、按月、按项目随手切换，趋势用一条平滑曲线讲清楚。装完即用：不用配置、不用重启会话、不会在你写代码的时候跳出来打扰你。
+**dsh-token-use 把这些变成一眼看得懂的数字。** 它跟着每一次调用实时累加，把消费金额、总量、输入、输出、缓存命中、推理和调用次数摊开在设置页里，按模型、按天、按月、按项目随手切换，趋势用一条平滑曲线讲清楚。装完即用：不用配置、不用重启会话、不会在你写代码的时候跳出来打扰你。
 
 看不见的成本最贵——把它变成看得见的。
 
-![Token 用量面板：范围与模型筛选、总量卡片、最近 30 天趋势图与按模型明细](assets/token-usage.jpg)
+![Token 用量面板：范围与模型筛选、金额与总量卡片、7/30/90 天可切的趋势图（堆叠构成 + 金额柱）、以及按模型/按日期/按项目三张带金额的明细表](assets/token-usage.jpg)
 
 ## 安装
 
@@ -40,8 +58,9 @@ dsh plugin --profile web add /解压路径/dsh-token-use
 
 ## 性能设计
 
-- 宿主侧 **不轮询、不写盘、不加定时器**：通过 `session/event` 事件总线做 O(1) 增量累加（每条 `assistant/message` 一次字典加法）。
+- 宿主侧 **不轮询、不写盘、不加定时器**（除了每天一次定价刷新）：通过 `session/event` 事件总线做 O(1) 增量累加（每条 `assistant/message` 一次字典加法 + 一次金额乘法）。
 - 启动时做 **一次性**历史重建：流式解压 `$DSH_HOME/sessions/**/session.jsonl.zstd`（`node:zlib` 原生 zstd），每读一个文件主动让出事件循环（`scheduler.yield()`），不阻塞会话处理；重建与实时事件用「会话 seq 水位」去重，任意先后顺序都不会重复计数。
+- **定价刷新**：每天 12:00 一次 HTTPS GET（15 秒超时，失败 1 小时后重试），结果写入 `$DSH_HOME/dsh-token-use/pricing.json`（原子替换，最多保留 30 份快照）；进程重启时同步读缓存，不重复联网；联网失败自动退回内置快照，面板照常显示。
 - 只暴露一个只读 JSON 接口 `GET /dsh-token-use`（仅回环可访问，内存快照，`no-store`）。
 
 ```sh
@@ -54,6 +73,8 @@ curl 'http://127.0.0.1:3080/dsh-token-use?day=2026-09-10'
 curl 'http://127.0.0.1:3080/dsh-token-use?model=deepseek-v4-flash'
 ```
 
+响应里每个桶都带 `cost`（估算金额），`pricing` 是当前价目表、抓取时间与下次刷新时间，`modelPricing` 是各模型匹配到的单价或未计价原因。
+
 ## 开发
 
 ```sh
@@ -70,6 +91,8 @@ pnpm run build        # 重新生成 client/client.js（= 精简 ECharts + clien
 - `input` / `output`：API 上报的输入/输出 tokens。
 - `cacheRead` / `cacheWrite`：提示词缓存读/写 tokens（API 计费口径中缓存读也计入输入侧）。
 - `reasoning`：推理 tokens。
+- `cost`：按上面的字段与当时单价算出的估算金额；缓存写不计费，推理已含在输出内，不重复计。
+- `auxiliary`：本期未计入金额的辅助调用次数（`search` 联网搜索、`title` 会话标题）。
 - 模型归属：该会话最近一次 `request/header` 的 model；标题生成等无 usage 记录的小调用不在统计内。
 - 项目归属：取会话创建头里的 `cwd`（实时事件读 `session.header.cwd`，历史扫描读日志头）；子会话/分叉会话继承父会话的项目；极少数暂时无法归属的调用先挂起，归属明确后自动回填，30 秒仍未明确才记入 `(no cwd)`。
 
@@ -80,11 +103,12 @@ pnpm run build        # 重新生成 client/client.js（= 精简 ECharts + clien
 | 维度 | 说明 |
 | --- | --- |
 | 运行环境 | 需要 **dsh web ≥ 0.1.0-rc.6**（设置侧边栏 `settings.section` 槽位）。宿主侧只用 Node 内置模块；zstd 解压依赖 `node:zlib`（Node ≥ 22.15 内置，dsh 自身要求 ^22.19 \|\| >=24，故必然满足）。 |
-| 数据目录 | 按 `$DSH_HOME`（环境变量，缺省 `~/.dsh`）解析，与 dsh 官方 `dsh-home-paths` 规则一致；自定义 home 同样有效。插件**只读**，不写任何文件。 |
+| 数据目录 | 按 `$DSH_HOME`（环境变量，缺省 `~/.dsh`）解析，与 dsh 官方 `dsh-home-paths` 规则一致；自定义 home 同样有效。历史用量**只读**；唯一写入的是定价缓存 `$DSH_HOME/dsh-token-use/pricing.json`（原子替换，可用 `pricing.enabled: false` 完全关闭联网与写盘）。 |
+| 设置导航图标 | 应用按 section id 硬编码导航图标，未知 id（含本插件与插件市场）都回退成同一个齿轮，槽位没有 icon 选项。插件用「结构选择器 + mask」把自己的柱状图图标画在齿轮位置：只依赖自身 `label` 里的标记类名，不依赖应用 CSS 模块的哈希类名；若应用改版导致结构变化，选择器失配即回退为默认齿轮（不会出现两个图标），功能不受影响。 |
 | 会话格式 | 同时支持 `session.jsonl[.zstd]`（多帧 zstd，含 checksum）、带版本号的新一代 `session.v<N>.jsonl[.zstd]`（dsh 迁移后会与旧文件并存），以及明文 `.jsonl`；同一会话**只读最高版本那一代**，不会重复计数；`.bak`/`.corrupt-*`/`session.lock` 自动跳过，个别损坏帧只计入 `scan.skipped`。 |
 | 目录布局 | 兼容官方 JSONL 持久层的 `sessions/<项目目录>/<会话目录>/` 结构；会话按项目目录、会话 ID 独立读取。 |
 | 统计口径 | 部分 provider（如 pi-ai 适配）会把推理 token 并入输出，此时「推理」列为 0 属正常；标题生成、联网搜索等不落 `usage` 的调用不计入；模型归属取该会话最近一次 `request/header`。 |
-| 网络访问 | 接口默认**仅回环**。局域网部署（配置了 trustedHosts）时在 profile patch 里开 `allowRemote: true`，且仍只接受同源请求；客户端遇到 403 会直接提示原因。 |
+| 网络访问 | 接口默认**仅回环**。局域网部署（配置了 trustedHosts）时在 profile patch 里开 `allowRemote: true`，且仍只接受同源请求；客户端遇到 403 会直接提示原因。出网只有一个用途：每天 12:00 抓一次 `api-docs.deepseek.com` 官方定价页（可用 `pricing.url` 换源、`pricing.enabled: false` 关闭）。 |
 | 性能 | 历史重建在 **Worker 线程**执行，不阻塞宿主事件循环；期间新事件先缓冲、扫描完成后回放，靠会话 seq 水位去重。之后只做事件增量。 |
 | 多实例 | 每个 `$DSH_HOME` 独立统计；同一 home 下的多个 profile 共享 `sessions` 目录，统计会合并显示。 |
 
@@ -97,6 +121,11 @@ pnpm run build        # 重新生成 client/client.js（= 精简 ECharts + clien
     endpoint: /dsh-token-use
     scanAtBoot: true    # false 则只统计插件启动之后的实时用量
     allowRemote: false  # 局域网（非回环）访问时设为 true，仅接受同源请求
+    pricing:
+      enabled: true     # false 则关闭每日定价抓取，只用内置/已有快照
+      currency: CNY     # CNY（官网中文页，元）或 USD（官网英文页，$）
+      refreshHour: 12   # 本地时间每天几点抓取
+      # url: https://api-docs.deepseek.com/zh-cn/quick_start/pricing  # 自定义定价页
 ```
 
 ## 安装后