@kenz1117/dsh-ui-usage-billing 0.9.1 → 0.9.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +187 -0
- package/README.md +52 -143
- package/lib/client.js +838 -413
- package/lib/index.js +293 -32
- package/lib/types/aggregate.d.ts +19 -4
- package/lib/types/client/PeakAlertBanner.d.ts +18 -0
- package/lib/types/client/UsageBilling.d.ts +4 -4
- package/lib/types/client/completion-notify.d.ts +28 -0
- package/lib/types/client/locales.d.ts +1 -1
- package/lib/types/client/peak-alert.d.ts +49 -0
- package/lib/types/client/pricing.d.ts +34 -4
- package/lib/types/client/provider-display.d.ts +21 -0
- package/lib/types/subscriptions.d.ts +20 -1
- package/package.json +1 -1
package/README.en.md
ADDED
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# dsh-ui-usage-billing
|
|
4
|
+
|
|
5
|
+
<p align="center">A billing dashboard plugin for DeepSeek Harness — aggregates model usage in real time from persisted session logs and estimates cost against current multi-provider prices, shown in a one-click dashboard from the sidebar.</p>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<a href="https://github.com/kenz1117/dsh-ui-usage-billing/blob/main/LICENSE"><img alt="GitHub license" src="https://img.shields.io/github/license/kenz1117/dsh-ui-usage-billing"></a>
|
|
9
|
+
<a href="https://github.com/kenz1117/dsh-ui-usage-billing"><img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/kenz1117/dsh-ui-usage-billing"></a>
|
|
10
|
+
<a href="https://www.npmjs.com/package/@kenz1117/dsh-ui-usage-billing"><img alt="npm version" src="https://img.shields.io/npm/v/@kenz1117/dsh-ui-usage-billing"></a>
|
|
11
|
+
<a href="https://www.npmjs.com/package/@kenz1117/dsh-ui-usage-billing"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@kenz1117/dsh-ui-usage-billing"></a>
|
|
12
|
+
<a href="https://github.com/kenz1117/dsh-ui-usage-billing/issues"><img alt="GitHub issues" src="https://img.shields.io/github/issues/kenz1117/dsh-ui-usage-billing"></a>
|
|
13
|
+
<a href="https://github.com/kenz1117/dsh-ui-usage-billing/graphs/contributors"><img alt="GitHub contributors" src="https://img.shields.io/github/contributors/kenz1117/dsh-ui-usage-billing"></a>
|
|
14
|
+
<a href="https://awesome-dsh-plugin.com"><img alt="Awesome DSH Plugin" src="https://awesome-dsh-plugin.com/badge.svg"></a>
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
[English](README.en.md) · [中文](README.md)
|
|
18
|
+
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
> **Peak/off-peak pricing update (from 2026-08-23 (Sun) 00:00 Beijing)**: DeepSeek models follow the new official rule — **weekdays (Mon–Fri)** keep the original peak/off-peak split (peak 09:00–12:00 / 14:00–18:00, ×2); **weekends (Sat/Sun)** are no longer split and are billed at the **off-peak price** all day. The plugin's billing engine, rate table and per-turn peak/off-peak bands all reflect this.
|
|
24
|
+
|
|
25
|
+
### Demo GIF
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
## Features
|
|
30
|
+
|
|
31
|
+
- **Sidebar entry**: a dashboard-style trigger card above the Settings button — month cost as the headline number (monospace) with a 7-day sparkline mini-trend, second line "Today / This week"; collapses to an icon button; hover reveals a quick-look card.
|
|
32
|
+
- **Billing dashboard (tabbed)**: Overview / Trends / Providers / Stats / Rates / Settings — hero figures + YoY/DoD + month projection + KPI×4 + heatmap; 7/30-day trend; provider billing & subscriptions; export / cost breakdown / workspaces / session detail; model rate table; budget & peak alerts. Restrained tones, `--dsw-*` tokens, dark/light adaptive.
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
- **Live cost bar**: below the composer, persistent "This turn ¥x · Session ¥y" plus the peak/off-peak tier & switch countdown and subscription low-quota chips (≤20% appear, ≤10% red).
|
|
36
|
+
- **Peak/off-peak switch alert**: a popover before a tier switch plus an optional system notification (lead time / position / mode / preview configurable), distinguishing "About to enter peak ×2 — can wait" / "About to enter off-peak, price halves".
|
|
37
|
+
- **Live-priced rate table**: models.dev fetched pricing + live-model alignment — the models actually configured are all included; peak/off-peak split (weekdays 9-12 / 14-18 peak ×2, weekends off-peak all day) plus a live USD→CNY rate, refreshed every 6 hours.
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
- **Official vs third-party buckets**: the detail cost column is split by official DeepSeek direct / third-party relay ("official x / third y" when mixed); the Stats tab has an official/third-party summary card.
|
|
41
|
+
- **Monthly budget + tier alerts**: a budget bar (on/off / amount / progress, ≥80% amber, over red pulse); notifies once per tier crossing 50/80/100%; a balance below the threshold (in CNY) alerts once a day.
|
|
42
|
+
- **Subscription quota**: detects subscription providers in `llm-pi-ai` (Kimi / Z.ai / OpenCode Go / MiniMax / OpenRouter / Xiaomi / Volcano…); those with a quota API show remaining % and reset time live, exhausted in red, no API shown as "not wired"; subscription-channel model cost is 0.
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
- **Custom provider balance**: configure any HTTP endpoint for balance (`extract` supports constant / dot-path / add-subtract / divide, header `{{ENV}}` via the credentials seam); DeepSeek / Kimi / StepFun / SiliconFlow have built-in official balances, and the balance column estimates "≈N days" from the 7-day daily burn.
|
|
46
|
+
- **Real usage aggregation**: the server aggregates from session logs on demand (incremental cache recomputes only written sessions), with per-session corruption tolerance and snapshot fallback; the `usage_stats` tool lets the model query today / month spend.
|
|
47
|
+
- **Multi-language + dual currency**: the ¥/$ switch is bilingual (USD→English, CNY→Chinese, this plugin only); the rate table converts to the selected currency.
|
|
48
|
+
- **Model health + uncatalogued annotation**: provider connection dots (green / red / grey); a model id not in the catalog is marked "uncatalogued" priced at the fallback, with provider inferred (e.g. `mi-mimo-2.5` → Xiaomi); estimated-price models are marked "estimated".
|
|
49
|
+
- **Session detail + cost spikes + heatmap**: sessions sorted by cost (title / project / calls / cost / last active); per-turn cost bars (last 40 turns, amount at bar top, peak/off-peak background bands, >2× spike flagged with attribution); a monthly calendar heatmap (5-color scale, hover detail).
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
- **Export + offline self-contained**: the Stats tab exports daily / per-session CSV and full JSON; no chart library, no external CDN, pure design tokens.
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
## Quick start
|
|
58
|
+
|
|
59
|
+
Add to the host `cordis.patch.yml`:
|
|
60
|
+
|
|
61
|
+
```yaml
|
|
62
|
+
- insert:
|
|
63
|
+
- id: ui-usage-billing
|
|
64
|
+
name: '@kenz1117/dsh-ui-usage-billing'
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Or install via a package manager:
|
|
68
|
+
|
|
69
|
+
```sh
|
|
70
|
+
npm install @kenz1117/dsh-ui-usage-billing
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
After the host starts, the billing entry appears above the sidebar Settings. No extra configuration is needed; when `sessionPersistence` is available it aggregates real usage automatically.
|
|
74
|
+
|
|
75
|
+
## How it works
|
|
76
|
+
|
|
77
|
+
The plugin has a server side and a browser side:
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
Browser Server (Node)
|
|
81
|
+
│ │
|
|
82
|
+
├─ GET /api/billing/usage-stats ────────▶ ├─ sessionPersistence walks persisted session logs
|
|
83
|
+
│ ├─ attributes a call to its preceding request/header model
|
|
84
|
+
│ ├─ buckets tokens by cache hit / miss
|
|
85
|
+
│ └─ estimates cost (CNY) from the live rate table
|
|
86
|
+
├─ GET /api/billing/pricing ────────────▶ ├─ live USD→CNY rate and model prices
|
|
87
|
+
├─ GET /api/billing/balance ────────────▶ ├─ DeepSeek official balance API (credentials seam)
|
|
88
|
+
├─ llm.models health probe ─────────────▶ └─ returns aggregated stats JSON
|
|
89
|
+
└─ renders the dashboard
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
- **Server** (`src/index.ts`): injects `webServer`, `sessionPersistence` and `credentials`, and registers `GET /api/billing/usage-stats`, `/api/billing/pricing`, `/api/billing/balance`. The aggregator caches folded results per session: each LLM call is attributed to the model of its preceding `request/header`, tokens split into cache-hit / cache-miss buckets, dates bucketed by the local timezone; a log file with unchanged mtime+size reuses its cached fold, only written sessions are re-folded, and the whole document has a 5s TTL to coalesce heavy polling. Aggregation logic lives in `src/aggregate.ts`.
|
|
93
|
+
- **Browser** (`src/client/`): requests the endpoints above to render the dashboard and probes each provider connection via `llm.models`. Until real data arrives it shows an all-zero empty snapshot, never fabricated samples.
|
|
94
|
+
|
|
95
|
+
## Theme collaboration
|
|
96
|
+
|
|
97
|
+
This plugin **depends on no theme package** and runs standalone. The dashboard modal declares a `billing.dashboard.decor` decoration slot (head / hero / trend / models / footer anchors) and registers a real-time cost summary as the `ctx.billingMetrics` service: theme plugins (e.g. acid-zine) inject their own decoration visuals (MacDots, tape, torn notes…) and subscription-cost data into their sticker layer. Plugin and theme load/unload independently — with no theme the default visuals apply; without billing the theme still runs.
|
|
98
|
+
|
|
99
|
+
## Billing engine
|
|
100
|
+
|
|
101
|
+
The rate table (`src/client/pricing.ts`) stores each model in its **native currency**: domestic providers enter CNY directly, overseas providers enter USD. Cost is computed and displayed in CNY uniformly — USD models convert via the **live rate**, domestic models never pass through a rate. At startup the server fetches the live rate and model prices (`src/pricing-fetch.ts`): USD→CNY prefers the Tencent Finance quote (keyless, reachable in China), falling back to open.er-api then the built-in default; it then refreshes every 6 hours, and the rate-table modal shows a "today's rate" marker plus live / built-in badge. The **display currency follows the user**: switching ¥ / $ converts each per-1M-token unit price via `convertUnitPrice` at the live rate (falling back to the native currency when the rate is unavailable).
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
cost (CNY) = (missInput × p_input + cacheHit × p_cacheHit + output × p_output) / 10⁶
|
|
105
|
+
—— prices in native currency; USD models convert at the live USD → CNY rate
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`input` in the stats is total input (cacheHit + cacheMiss); estimation splits it into hit / miss to avoid double counting. Models with two-band billing are mixed by `DEFAULT_PEAK_SHARE` (default 0.5); weekends (Beijing Sat/Sun) are charged at the off-peak rate all day.
|
|
109
|
+
|
|
110
|
+
### Supported models (2026-08-21 lineup, OpenAI-compatible)
|
|
111
|
+
|
|
112
|
+
| Provider | Models |
|
|
113
|
+
| -------- | ------------------------------------------------------------------------------------------- |
|
|
114
|
+
| DeepSeek | V4 Flash, V4 Flash Vision (Exp), V4 Pro (peak/off-peak billing: weekdays peak 09:00-12:00 / 14:00-18:00 Beijing = 2× off-peak; weekends off-peak all day) |
|
|
115
|
+
| Zhipu AI | GLM-5.3, GLM-5.2, GLM-4.6 |
|
|
116
|
+
| Aliyun | Qwen3.8 Max, Qwen3.7-Max, Qwen3.5-Plus, Qwen3.5-Flash |
|
|
117
|
+
| Doubao | Seed-2.0 Pro, Seed-2.0 Mini, Seed-1.6 |
|
|
118
|
+
| Moonshot | Kimi K3, K2.7 Code, K2.7 Code HighSpeed, K2.6 |
|
|
119
|
+
| Xiaomi | MiMo V2.5 (exempt when billed via a token-plan subscription channel)¹ |
|
|
120
|
+
| MiniMax | MiniMax-M3 |
|
|
121
|
+
| Baidu | ERNIE-5.1 |
|
|
122
|
+
| Tencent | Hunyuan T1, Hunyuan Hy3 |
|
|
123
|
+
| 01.AI | Yi-Lightning |
|
|
124
|
+
| StepFun | Step 3.7 Flash |
|
|
125
|
+
| iFlytek | Spark 4.0 Ultra (plan-based)¹ |
|
|
126
|
+
| SenseTime | SenseNova 6.5 (beta)¹ |
|
|
127
|
+
| Baichuan | Baichuan M3-Plus |
|
|
128
|
+
| OpenAI | GPT-5.6 Sol / Terra / Luna |
|
|
129
|
+
| Google | Gemini 3.1 Pro, 3.6 Flash (Standard / Flex two-band, Flex = −50%) |
|
|
130
|
+
| xAI | Grok 4.6, Grok 4.3 |
|
|
131
|
+
| Meta | Llama 4 Maverick, Scout |
|
|
132
|
+
| Other | Unified fallback pricing for uncatalogued models |
|
|
133
|
+
|
|
134
|
+
> ¹ iFlytek, SenseTime and Xiaomi have not published per-token prices — the table shows estimates; cost is 0 when these models go through a subscription channel (coding / token plan / opencode), and recalibrates automatically when official pricing is published. Subscription channels align with pi-ai built-in providers (kimi-coding, zai-coding-cn, opencode, opencode-go, qwen/xiaomi token-plan regional variants), overridable via `subscriptionProviders`.
|
|
135
|
+
|
|
136
|
+
To add a model: append an entry to `MODEL_CATALOG` and map its real id in `MODEL_KEY_ALIASES` in `src/client/pricing.ts` (shared by the aggregation layer and the client renderer).
|
|
137
|
+
|
|
138
|
+
## HTTP API
|
|
139
|
+
|
|
140
|
+
The public HTTP endpoints and field definitions are documented in source: `GET /api/billing/pricing`, `/api/billing/balance`, `/api/billing/usage-stats` (see `src/index.ts`, `src/aggregate.ts`).
|
|
141
|
+
|
|
142
|
+
## Configuration
|
|
143
|
+
|
|
144
|
+
| Field | Default | Description |
|
|
145
|
+
| ----------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
146
|
+
| `statsPath` | unset | Absolute path to a fallback `.dsh-usage-stats.json` (used when `sessionPersistence` is unavailable) |
|
|
147
|
+
| `balanceApiKeyEnv` | `DEEPSEEK_API_KEY` | Credential ref for the DeepSeek balance query; only used as a fallback when llm-pi-ai has no `apiKeyEnv` for deepseek |
|
|
148
|
+
| `subscriptionProviders` | `kimi-coding`, `xiaomi-token-plan-cn` | Subscription (coding / token plan) provider id list — tokens counted, cost 0 |
|
|
149
|
+
| `monthlyBudget` | unset | Default monthly budget (CNY); sent with usage-stats as the budget bar's initial amount (user UI settings take precedence and persist locally) |
|
|
150
|
+
| `lowBalanceThreshold` | `50` | Low-balance alert threshold (CNY); sent with usage-stats, alerts once a day when any provider's CNY balance is below it |
|
|
151
|
+
| `subscriptionPlans` | auto-detect | Subscription quota adapter whitelist (`{ provider, baseUrl?, region? }`); when unset, auto-detects all subscription providers from `llm-pi-ai` (queries those with a quota API, marks the rest) |
|
|
152
|
+
|
|
153
|
+
## Development
|
|
154
|
+
|
|
155
|
+
Requirements: Node.js ^22.19 || >=24, pnpm.
|
|
156
|
+
|
|
157
|
+
```sh
|
|
158
|
+
pnpm install
|
|
159
|
+
pnpm --filter @kenz1117/dsh-ui-usage-billing bundle # builds lib/index.js and lib/client.js
|
|
160
|
+
npx vitest run packages/client/ui-usage-billing/tests # unit tests
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## Release
|
|
164
|
+
|
|
165
|
+
This package is a standalone npm package that other DeepSeek Harness hosts can install once published.
|
|
166
|
+
|
|
167
|
+
```sh
|
|
168
|
+
npm publish --access public
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
The host discovers the browser side automatically via the `dsh.client` declaration (`platform: web`) and the `exports["./client"]` bundle in `package.json` — no registry registration needed.
|
|
172
|
+
|
|
173
|
+
## Model Experience
|
|
174
|
+
|
|
175
|
+
None. This plugin is a pure UI surface: it registers no tools, injects no system prompt, writes no model-visible events to the session log, and touches no session KV cache; usage statistics are aggregated by the server from existing session logs, whose content is owned by other packages.
|
|
176
|
+
|
|
177
|
+
## Known Limitations and Deferred Work
|
|
178
|
+
|
|
179
|
+
- **Balance queries cover DeepSeek / Moonshot (Kimi) / StepFun**: these three use a standard Bearer API key. Other providers expose no public balance API or need non-Bearer auth (Xiaomi MiMo via console Cookie, SenseTime via AccessKey signing, MiniMax/Doubao via quota or AK/SK), so they currently show "not configured"; the extension point is `src/balance.ts` (add a querier per provider balance API).
|
|
180
|
+
- **Overspend notifications rely on the browser Notification API**: when permission is denied or the platform lacks support, only the in-UI red-pulse fallback remains — no host-level notification channel; notifications are capped at once per day.
|
|
181
|
+
- **Session rows are not navigable**: clicking a session row does not open that session (cross-plugin navigation needs a host session-selection channel); sessions are capped at 100 rows and the panel shows the top 20.
|
|
182
|
+
- **Cost is a catalog estimate**: models without published per-token pricing (iFlytek, SenseTime, Xiaomi) use estimates (feature-list footnote ¹); official billing is authoritative.
|
|
183
|
+
- **The 30-day trend is bounded by log retention**: dates outside the persisted log retention window are shown as zeros in the window, not backfilled.
|
|
184
|
+
|
|
185
|
+
## License
|
|
186
|
+
|
|
187
|
+
[MIT](LICENSE) © 2026 KenZ (kenz1117)
|
package/README.md
CHANGED
|
@@ -1,65 +1,58 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
1
3
|
# dsh-ui-usage-billing
|
|
2
4
|
|
|
3
|
-
DeepSeek Harness
|
|
5
|
+
<p align="center">DeepSeek Harness 计费仪表盘插件 — 从持久化会话日志实时聚合模型用量，按多厂商最新官方价格估算费用，侧边栏一键查看完整仪表盘。</p>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<a href="https://github.com/kenz1117/dsh-ui-usage-billing/blob/main/LICENSE"><img alt="GitHub license" src="https://img.shields.io/github/license/kenz1117/dsh-ui-usage-billing"></a>
|
|
9
|
+
<a href="https://github.com/kenz1117/dsh-ui-usage-billing"><img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/kenz1117/dsh-ui-usage-billing"></a>
|
|
10
|
+
<a href="https://www.npmjs.com/package/@kenz1117/dsh-ui-usage-billing"><img alt="npm version" src="https://img.shields.io/npm/v/@kenz1117/dsh-ui-usage-billing"></a>
|
|
11
|
+
<a href="https://www.npmjs.com/package/@kenz1117/dsh-ui-usage-billing"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@kenz1117/dsh-ui-usage-billing"></a>
|
|
12
|
+
<a href="https://github.com/kenz1117/dsh-ui-usage-billing/issues"><img alt="GitHub issues" src="https://img.shields.io/github/issues/kenz1117/dsh-ui-usage-billing"></a>
|
|
13
|
+
<a href="https://github.com/kenz1117/dsh-ui-usage-billing/graphs/contributors"><img alt="GitHub contributors" src="https://img.shields.io/github/contributors/kenz1117/dsh-ui-usage-billing"></a>
|
|
14
|
+
<a href="https://awesome-dsh-plugin.com"><img alt="Awesome DSH Plugin" src="https://awesome-dsh-plugin.com/badge.svg"></a>
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
[中文](README.md) · [English](README.en.md)
|
|
18
|
+
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
> **峰谷计费规则更新（自 2026-08-23（周日）00:00 起）**：DeepSeek 模型按官方新规计费——**工作日（周一至周五）** 继续执行原峰谷分段计费（高峰 09:00–12:00 / 14:00–18:00，×2）；**周末（周六、周日）** 全天不再区分峰谷时段，统一按**低谷价**计费。插件计费引擎、费率表与每轮费用峰谷分带均已同步生效。
|
|
4
24
|
|
|
25
|
+
### 演示动图
|
|
5
26
|
|
|
6
|
-
|
|
7
|
-
[](https://github.com/kenz1117/dsh-ui-usage-billing)
|
|
8
|
-
[](https://www.npmjs.com/package/@kenz1117/dsh-ui-usage-billing)
|
|
9
|
-
[](https://awesome-dsh-plugin.com)
|
|
27
|
+
|
|
10
28
|
|
|
11
29
|
## 特性
|
|
12
30
|
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
-
|
|
28
|
-
-
|
|
29
|
-
-
|
|
30
|
-
-
|
|
31
|
-
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
- **厂商计费与订阅（按厂商聚合）**：模型计费明细与订阅套餐合并为**单一容器**，按厂商作为一级分组——同厂商的非订阅按量模型（显示实际费用）与订阅套餐（显示额度卡片）落在同一组，避免散乱；余额与健康圆点只在厂商组头部显示一次（**余额是厂商的余额**，不再随每行重复）。订阅 provider 通过内置别名归并到对应模型厂商（如 `kimi-coding` → 月之暗面），无模型厂商的跨厂商通道（如 opencode）按自身名独立成组。
|
|
39
|
-
- **模型可用数按模型统计**：侧边栏入口右上角「N 模型可用」按**模型数量**统计（各厂商成功接入的模型之和），而非厂商数量，口径与文案一致。
|
|
40
|
-
- **用量热力图**：当月日历热力图（本月 1 号到今天每天一格，周日开头 7 列），按日费用分 5 档色阶，悬停显示日期与金额。概览 Tab 常驻。
|
|
41
|
-
- **每轮费用与成本突增**：按会话轮次折叠的每轮费用图（最近 40 轮），位于趋势 Tab；每根柱子顶部标注该轮费用数字，相对近 6 轮成本超 2 倍的轮次红色标注并归因（输出增长 / 上下文膨胀 / 缓存命中率下降）。
|
|
42
|
-
- **工作区统计**：按会话工作目录（cwd 末级）归并的花费 / 调用 / Token 汇总表。
|
|
43
|
-
- **双币种显示 & 多语种联动**：仪表盘右上角 ¥ / $ 切换——美元金额按当前汇率换算显示；面板文案同时随币种切换（USD → 英文、CNY → 中文，仅本插件生效，不影响宿主全局语言）。费率表的单价也按所选币种换算（切 USD 时人民币计价模型换算为 $，不再固定显示 ¥）。
|
|
44
|
-
- **触发卡 hover 速览**：悬停侧边栏触发卡即浮现速览卡（今日 / 本周 / 当月 + 近 7 天迷你柱），无需点开仪表盘。
|
|
45
|
-
- **峰谷时段占比**：趋势 Tab 内按每轮起始时刻（北京时间高峰 9-12 / 14-18）精确分摊高峰 / 空闲费用，堆叠条 + 金额百分比图例。
|
|
46
|
-
- **费用构成（估算）**：统计 Tab 内按角色归因的三段堆叠条（用户输入 / 助手输出 / 工具结果）——输出成本实测计价，输入成本按消息文本长度占比摊分（日志无角色级实测 token，标注估算口径）。
|
|
47
|
-
- **数据导出**：统计 Tab 顶部一键导出按日 CSV、按会话 CSV 与全量 JSON（文件名带日期范围），便于对账。
|
|
48
|
-
- **模型自查用量（`usage_stats` 动态工具）**：模型可在对话中直接查询用量费用（`today` / `month` / `session` / `all` 四档），例如"今天花了多少钱"；tools 服务缺席时自动跳过注册。
|
|
49
|
-
- **统计快照落盘**：聚合结果原子写（temp+rename，权限 600）到 `~/.dsh/.dsh-usage-stats.json`，重启首屏与聚合异常都有最近数据可看；启动时检测到另一实例的新鲜快照会告警（双实例会导致提醒重复）。
|
|
50
|
-
- **离线自包含**：无图表库、无外部 CDN，全部使用设计令牌，适配深色/浅色主题。
|
|
51
|
-
|
|
52
|
-
## 截图
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
31
|
+
- **侧边栏入口**：设置按钮上方的仪表盘式触发卡——本月费用主数字（等宽字体）+ 近 7 天 sparkline 迷你趋势，副行「今日 / 本周」；折叠栏自动切为图标钮；悬停浮现速览卡。
|
|
32
|
+
- **计费仪表盘（分区 Tab）**：概览 / 趋势 / 明细 / 统计 / 费率 / 设置 六区——Hero 大数字 + 本年/今日环比 + 本月预计 + KPI×4 + 热力图；趋势图 7/30 天；厂商计费与订阅；导出 / 费用构成 / 工作区 / 会话明细；模型单价表；预算与峰谷提醒。克制冷调、`--dsw-*` 令牌、深浅主题自适应。
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
- **即时代费用条**：输入框下方常驻「本轮 ¥x · 会话 ¥y」+ 峰谷档位与切换倒计时 + 订阅额度预警 chips（≤20% 浮现、≤10% 红）。
|
|
36
|
+
- **峰/谷切换提醒**：切档前弹窗 + 可选系统通知（提前量 / 位置 / 模式 / 预览可配），区分「即将进峰时 ×2 可稍等」/「即将进平价 价格减半」。
|
|
37
|
+
- **实时定价费率表**：models.dev 抓价 + 探活模型对标——系统实际配置模型全纳入；峰谷分时（工作日 9-12 / 14-18 高峰 ×2，周末全天低谷）+ 实时汇率（USD→CNY），每 6 小时刷新。
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
- **官方 vs 三方分桶**：明细费用列按官方 DeepSeek 直连 / 第三方中转分解（混合时「官 x / 三 y」），统计 Tab 有「官方/三方」汇总卡。
|
|
41
|
+
- **月度预算 + 分档提醒**：预算条（开关 / 金额 / 进度，≥80% 琥珀、超支红脉）；跨 50 / 80 / 100% 各提醒一次；余额折算 CNY 低于阈值每天提醒一次。
|
|
42
|
+
- **订阅套餐额度**：识别 `llm-pi-ai` 里的订阅类 provider（Kimi / Z.ai / OpenCode Go / MiniMax / OpenRouter / 小米 / 火山…），有额度 API 的实时显示剩余%与重置时间、用尽标红，无 API 标「未接入」；订阅通道模型费用记 0。
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
- **自定义 Provider 余额**：配置任意 HTTP 端点查余额（`extract` 支持常量 / 点路径 / add-subtract / divide，请求头 `{{ENV}}` 经凭据 seam）；DeepSeek / Kimi / 阶跃星辰 / 硅基流动内置官方余额，余额列按近 7 天日均折算「约可撑 N 天」。
|
|
46
|
+
- **真实用量聚合**：服务端从会话日志实时聚合（增量缓存只重算写过的会话），单会话损坏容错、快照落盘回退；`usage_stats` 工具让模型自查今天 / 本月花费。
|
|
47
|
+
- **多语种 + 双币种**：¥ / $ 切换随币种双语（USD→英文、CNY→中文，仅本插件生效）；费率表按所选币种换算。
|
|
48
|
+
- **模型健康 + 未收录标注**：厂商接入状态圆点（绿 / 红 / 灰）；模型 id 不在目录时标「未收录」按兜底价估算、厂商自动推断（如 `mi-mimo-2.5` → 小米）；估算价模型标注「估算价」。
|
|
49
|
+
- **会话明细 + 成本突增 + 热力图**：按会话费用倒序（标题 / 项目 / 调用 / 费用 / 最后活跃）；每轮费用柱状图（最近 40 轮、金额贴柱顶、峰谷背景分带、超 2 倍红标归因）；当月日历热力图（5 档色阶、悬停明细）。
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
- **数据导出 + 离线自包含**：统计 Tab 导出按日 / 按会话 CSV 与全量 JSON；无图表库、无外部 CDN、纯设计令牌。
|
|
54
|
+
|
|
55
|
+
|
|
63
56
|
|
|
64
57
|
## 快速开始
|
|
65
58
|
|
|
@@ -112,13 +105,13 @@ cost（CNY）= (missInput × p_input + cacheHit × p_cacheHit + output × p_outp
|
|
|
112
105
|
—— 价格为原生币种；美元模型按实时 USD → CNY 汇率折算
|
|
113
106
|
```
|
|
114
107
|
|
|
115
|
-
统计中的 `input` 为总输入（cacheHit + cacheMiss），估算按命中 / 未命中分拆计价，避免重复计费。支持双档计费的模型按 `DEFAULT_PEAK_SHARE`（默认 0.5
|
|
108
|
+
统计中的 `input` 为总输入（cacheHit + cacheMiss），估算按命中 / 未命中分拆计价，避免重复计费。支持双档计费的模型按 `DEFAULT_PEAK_SHARE`（默认 0.5）混合高峰与低谷档；周末（北京时间周六 / 周日）全天按低谷价计费。
|
|
116
109
|
|
|
117
110
|
### 支持模型（2026-08-21 主流阵容，OpenAI 兼容系列）
|
|
118
111
|
|
|
119
112
|
| 厂商 | 模型 |
|
|
120
113
|
| -------- | --------------------------------------------------------------------------------------- |
|
|
121
|
-
| DeepSeek | V4 Flash、V4 Flash Vision (Exp)、V4 Pro
|
|
114
|
+
| DeepSeek | V4 Flash、V4 Flash Vision (Exp)、V4 Pro（按时段峰谷计费：工作日高峰 09:00-12:00 / 14:00-18:00 北京 = 低谷 2 倍；周末全天低谷） |
|
|
122
115
|
| 智谱 AI | GLM-5.3、GLM-5.2、GLM-4.6 |
|
|
123
116
|
| 阿里通义 | Qwen3.8 Max、Qwen3.7-Max、Qwen3.5-Plus、Qwen3.5-Flash |
|
|
124
117
|
| 字节豆包 | Doubao Seed-2.0 Pro、Seed-2.0 Mini、Seed-1.6 |
|
|
@@ -144,87 +137,7 @@ cost（CNY）= (missInput × p_input + cacheHit × p_cacheHit + output × p_outp
|
|
|
144
137
|
|
|
145
138
|
## HTTP API
|
|
146
139
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
实时定价文档（汇率 + 模型价，6 小时后台刷新），浏览器端单价表数据源：
|
|
150
|
-
|
|
151
|
-
```json
|
|
152
|
-
{
|
|
153
|
-
"source": "live",
|
|
154
|
-
"rate": 7.11,
|
|
155
|
-
"rateTime": "2026-08-16T12:00:00+08:00",
|
|
156
|
-
"models": {
|
|
157
|
-
"flash": { "input": 3, "output": 9, "cacheHit": 0.1 }
|
|
158
|
-
}
|
|
159
|
-
}
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
`source` 为 `live`（腾讯财经 / OpenRouter 拉到）或 `builtin`（全部降级内置默认值）；`rate` 为 USD→CNY 实时汇率。
|
|
163
|
-
|
|
164
|
-
### `GET /api/billing/balance`
|
|
165
|
-
|
|
166
|
-
各接入厂商账户余额。API Key 复用 `llm-pi-ai` 设置的 `providers.<id>.apiKeyEnv`（DeepSeek 未在 llm-pi-ai 配置时回退到 `balanceApiKeyEnv`）：
|
|
167
|
-
|
|
168
|
-
```json
|
|
169
|
-
{
|
|
170
|
-
"balances": [
|
|
171
|
-
{
|
|
172
|
-
"provider": "deepseek",
|
|
173
|
-
"displayName": "DeepSeek",
|
|
174
|
-
"currency": "CNY",
|
|
175
|
-
"totalBalance": 12.34
|
|
176
|
-
},
|
|
177
|
-
{
|
|
178
|
-
"provider": "月之暗面",
|
|
179
|
-
"displayName": "月之暗面",
|
|
180
|
-
"currency": "CNY",
|
|
181
|
-
"totalBalance": 49.59,
|
|
182
|
-
"grantedBalance": 46.59,
|
|
183
|
-
"toppedUpBalance": 3.0
|
|
184
|
-
},
|
|
185
|
-
{
|
|
186
|
-
"provider": "阶跃星辰",
|
|
187
|
-
"displayName": "阶跃星辰",
|
|
188
|
-
"currency": "CNY",
|
|
189
|
-
"totalBalance": 150.0,
|
|
190
|
-
"toppedUpBalance": 200.0,
|
|
191
|
-
"grantedBalance": 50.0
|
|
192
|
-
}
|
|
193
|
-
]
|
|
194
|
-
}
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
查询失败时对应条目带 `error`（`unconfigured` / `unauthorized` / `unreachable`），表格按此渲染状态提示。
|
|
198
|
-
|
|
199
|
-
### `GET /api/billing/usage-stats`
|
|
200
|
-
|
|
201
|
-
聚合统计文档，浏览器端数据源：
|
|
202
|
-
|
|
203
|
-
```json
|
|
204
|
-
{
|
|
205
|
-
"total": {
|
|
206
|
-
"calls": 733,
|
|
207
|
-
"input": 255931033,
|
|
208
|
-
"output": 414286,
|
|
209
|
-
"cacheHit": 255525760,
|
|
210
|
-
"cacheMiss": 405273,
|
|
211
|
-
"cost": 22.87
|
|
212
|
-
},
|
|
213
|
-
"byModel": {
|
|
214
|
-
"flash": { "calls": 733, "input": 255931033, "output": 414286, "cacheHit": 255525760, "cacheMiss": 405273, "cost": 22.87 }
|
|
215
|
-
},
|
|
216
|
-
"byDay": {
|
|
217
|
-
"2026-08-15": { "calls": 74, "input": 32593373, "output": 35375, "cacheHit": 32558208, "cacheMiss": 35165, "cost": 0.52 }
|
|
218
|
-
},
|
|
219
|
-
"byDayModels": {
|
|
220
|
-
"2026-08-15": {
|
|
221
|
-
"flash": { "calls": 74, "input": 32593373, "output": 35375, "cacheHit": 32558208, "cacheMiss": 35165, "cost": 0.52 }
|
|
222
|
-
}
|
|
223
|
-
}
|
|
224
|
-
}
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
字段含义：`input` 为总输入 token；`cacheHit` / `cacheMiss` 为缓存命中 / 未命中分桶；`cost` 为人民币估算费用。`byDayModels` 是 **模型 × 日期** 二维统计（`[date][modelKey]`），趋势图按模型堆叠的输入；当年 / 当月 / 当日三维费用由浏览器端按 `byDay` 日期前缀归并。`bySession` 为会话明细（按费用倒序，封顶 100 行）：`title` 取自日志中最新的 `session/title` 事件，`cwd` 为会话创建时的工作目录。配置 `monthlyBudget` 时响应额外携带 `budget` 字段（两条服务路径一致注入）。`sessionPersistence` 不可用时回退到配置文件（见下）。
|
|
140
|
+
对外 HTTP 接口与字段定义详见源码：`GET /api/billing/pricing`、`/api/billing/balance`、`/api/billing/usage-stats`（见 `src/index.ts`、`src/aggregate.ts`）。
|
|
228
141
|
|
|
229
142
|
## 配置
|
|
230
143
|
|
|
@@ -259,11 +172,7 @@ npm publish --access public
|
|
|
259
172
|
|
|
260
173
|
## Model Experience
|
|
261
174
|
|
|
262
|
-
无。本插件是纯 UI surface
|
|
263
|
-
|
|
264
|
-
#### KV Cache effect
|
|
265
|
-
|
|
266
|
-
无直接影响。插件不改变任何会话的提示前缀或历史，不触及 KV 缓存。
|
|
175
|
+
无。本插件是纯 UI surface：不注册工具、不注入系统提示、不向会话日志写入模型可见事件，也不触及会话 KV 缓存；用量统计由服务端从既有会话日志聚合，日志内容由其他包各自负责。
|
|
267
176
|
|
|
268
177
|
## Known Limitations and Deferred Work
|
|
269
178
|
|