dsh-usage-overview 1.0.0 → 1.1.1

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 ADDED
@@ -0,0 +1,176 @@
1
+ # DSH Usage Overview
2
+
3
+ [简体中文](README.md)
4
+
5
+ A usage overview plugin for DeepSeek Harness. It reads the harness's own session
6
+ records and presents token totals, an annual activity heatmap, daily token and
7
+ cache-hit-rate trends, and a per-model breakdown with a stacked day/week chart.
8
+
9
+ [GitHub](https://github.com/w-callan-w/dsh-usage-overview) · [Gitee](https://gitee.com/callanjones/deep-seek-harness-usage-plugin) · [npm](https://www.npmjs.com/package/dsh-usage-overview)
10
+
11
+ ## Features
12
+
13
+ - **Headline metrics** — total tokens, peak day, longest chat, current and
14
+ longest streaks, and prompt-cache hit rate.
15
+ - **Token activity** — a year of daily usage as a Sunday-aligned heatmap with
16
+ five intensity levels.
17
+ - **Daily token trend** — one smoothed line per provider route, with a shared
18
+ crosshair and per-route legend totals.
19
+ - **Daily cache hit rate** — input-token weighted cache hit rate per day, with
20
+ gaps for days that had no input tokens.
21
+ - **Model usage** — a donut chart, an attributed model list (provider source,
22
+ sessions, turns, tokens, share), and a stacked daily/weekly usage chart.
23
+ - **Range selector** — 7, 30, 90 days, or all time.
24
+ - **Fluid layout** — sized against the panel, not the window; the card strip,
25
+ model panel, range control, and charts adapt continuously to the available
26
+ width.
27
+ - **Light and dark themes** — colours come from DSH theme tokens, including the
28
+ tooltip's own dark-surface label token.
29
+
30
+ | Desktop | Phone (390px) |
31
+ |---|---|
32
+ | ![Desktop](docs/dashboard.png) | ![Phone](docs/dashboard-mobile.png) |
33
+
34
+ ## Install
35
+
36
+ The plugin is a DSH bundle. It needs a harness build that provides the
37
+ `webServer` service.
38
+
39
+ ### From npm
40
+
41
+ The package is published as `dsh-usage-overview`. Add it to the active profile:
42
+
43
+ ```sh
44
+ cd "$DSH_HOME/profiles/desktop"
45
+ pnpm add dsh-usage-overview
46
+ ```
47
+
48
+ Then add `"dsh-usage-overview"` to `dsh.profile.bundles` in that profile's
49
+ `package.json` and restart DeepSeek Harness.
50
+
51
+ ### From a local copy
52
+
53
+ 1. Copy the package into the target profile:
54
+
55
+ ```sh
56
+ cp -r dsh-usage-overview "$DSH_HOME/profiles/desktop/node_modules/"
57
+ ```
58
+
59
+ 2. Add it to the profile's bundle list in
60
+ `$DSH_HOME/profiles/desktop/package.json`:
61
+
62
+ ```json
63
+ {
64
+ "dsh": {
65
+ "profile": {
66
+ "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-usage-overview"]
67
+ }
68
+ }
69
+ }
70
+ ```
71
+
72
+ 3. Restart DeepSeek Harness. The sidebar entry **用量统计** / **Usage** appears
73
+ after the profile is composed.
74
+
75
+ The Desktop shell composes its profile once at launch. Editing files while it is
76
+ running does not mount a new bundle; quit and relaunch. A CLI-launched profile
77
+ with DSH's HMR bundle can reload on a manifest change.
78
+
79
+ ## Usage
80
+
81
+ Open **用量统计** in the sidebar.
82
+
83
+ - The range selector controls the headline metrics, the daily token trend, the
84
+ cache-rate chart, and the model usage trend.
85
+ - The activity heatmap always draws a year grid; the range selector does not
86
+ change its window.
87
+ - Hovering a chart raises exact figures for the hovered day or week.
88
+ - The model usage chart has a **每日 / 每周** switch. Weeks start on Monday; a
89
+ partial week at either end of the range remains visible.
90
+ - On narrow panels the heatmap scrolls horizontally and opens at the most recent
91
+ weeks.
92
+
93
+ ## Data
94
+
95
+ The plugin reads durable harness data only. It writes no harness state, calls no
96
+ model, and registers no model-facing tool.
97
+
98
+ 1. **Session logs** — `$DSH_HOME/sessions/<workspace>/<session>/session.v4.jsonl.zstd`.
99
+ Each log is a sequence of independently compressed zstd frames; every frame is
100
+ decoded separately. Assistant messages carry their own timestamp, provider
101
+ usage, provider, and model, which yields the real daily and per-route series.
102
+ 2. **Session index** — directory names provide session identity, creation time,
103
+ and log paths.
104
+ 3. **Projection cache** — `$DSH_HOME/storages/session_projcache/sessions/*.json`
105
+ is a fallback for unreadable logs and supplies session titles.
106
+ 4. **Live session services** — `ctx.sessions.list()` and
107
+ `ctx.sessionProjections.snapshot(session)` make an active session's running
108
+ totals count immediately.
109
+
110
+ Cache reads are counted as billed tokens. The cache hit rate is:
111
+
112
+ ```text
113
+ cacheRead / (cacheRead + cacheWrite + uncachedInput)
114
+ ```
115
+
116
+ Output tokens are excluded because they are not cacheable.
117
+
118
+ ## HTTP surface
119
+
120
+ The route is read-only.
121
+
122
+ | Route | Purpose |
123
+ |---|---|
124
+ | `GET /plugins/dsh-usage-overview/stats?range=7d\|30d\|90d\|all` | Aggregate dashboard document |
125
+
126
+ A request is accepted when it comes from loopback, or when DSH's session
127
+ authentication vouches for it. The second path lets a phone reach the panel
128
+ through the remote tunnel without opening the route to anonymous callers.
129
+
130
+ The browser half is provided by DSH's client module system and advertised in the
131
+ page's boot graph.
132
+
133
+ ## Development
134
+
135
+ No bundler or runtime dependency is required. Node.js runs the build and check
136
+ scripts directly.
137
+
138
+ ```sh
139
+ node scripts/build.mjs
140
+ ```
141
+
142
+ This copies the Host half (`lib/*.js`) from `src/` and bundles the browser half
143
+ into `lib/client.js` using DSH's module-loading format.
144
+
145
+ ### Checks
146
+
147
+ | Command | Purpose |
148
+ |---|---|
149
+ | `node scripts/check-sources.mjs` | Client source syntax and stylesheet template |
150
+ | `node scripts/lint-bundle.mjs` | Built browser bundle parses |
151
+ | `node scripts/check-build-fresh.mjs` | Committed `lib/` matches a fresh build |
152
+ | `node scripts/test-aggregation.mjs` | Aggregation, attribution, cache-rate, and edge cases |
153
+ | `node scripts/render-check.mjs` | Bundle materializes and renders in a React stub |
154
+ | `node scripts/preview.mjs` | Static dashboard preview |
155
+ | `node scripts/responsive-check.mjs [origin]` | Seven widths, live resize, light/dark contrast, screenshots |
156
+ | `node scripts/verify-install.mjs` | Installed profile package, exports, routes, trust guard |
157
+ | `node scripts/verify-live.mjs [origin]` | Running host serves the routes and bundle |
158
+
159
+ `responsive-check.mjs` and `verify-live.mjs` need a running host; pass its origin
160
+ when it is not the default `http://127.0.0.1:50494`.
161
+
162
+ ## Layout and theming
163
+
164
+ The dashboard measures the panel, not the viewport. The card strip flows on a
165
+ 150px basis, the model panel and range control wrap by content width, and each
166
+ chart redraws at its measured pixel width. Type, spacing, and padding scale with
167
+ container query units, so there are no hard layout breakpoints.
168
+
169
+ Colours use DSH `--dsw-*` tokens for both themes. The tooltip is a dark surface in
170
+ both light and dark mode and therefore uses `--dsw-alias-tooltip-label`; small
171
+ labels and chart axes use the higher-contrast secondary label token. The
172
+ `responsive-check.mjs` theme pass enforces a minimum contrast ratio of 4.5:1.
173
+
174
+ ## License
175
+
176
+ MIT
package/README.md CHANGED
@@ -1,63 +1,55 @@
1
- # DSH Usage Overview
1
+ # DSH 用量总览
2
2
 
3
- [简体中文](README.zh-CN.md)
3
+ [English](README.en.md)
4
4
 
5
- A usage overview plugin for DeepSeek Harness. It reads the harness's own session
6
- records and presents token totals, an annual activity heatmap, daily token and
7
- cache-hit-rate trends, and a per-model breakdown with a stacked day/week chart.
5
+ 一款 DeepSeek Harness 的用量总览面板插件。插件直接读取 Harness 自身的会话记录,
6
+ 展示 Token 总量、全年活跃热力图、每日 Token 与缓存命中率趋势,以及按模型拆分的
7
+ 用量构成和按日/按周堆叠图。
8
8
 
9
9
  [GitHub](https://github.com/w-callan-w/dsh-usage-overview) · [Gitee](https://gitee.com/callanjones/deep-seek-harness-usage-plugin) · [npm](https://www.npmjs.com/package/dsh-usage-overview)
10
10
 
11
- ## Features
12
-
13
- - **Headline metrics** — total tokens, peak day, longest chat, current and
14
- longest streaks, and prompt-cache hit rate.
15
- - **Token activity** — a year of daily usage as a Sunday-aligned heatmap with
16
- five intensity levels.
17
- - **Daily token trend** — one smoothed line per provider route, with a shared
18
- crosshair and per-route legend totals.
19
- - **Daily cache hit rate** — input-token weighted cache hit rate per day, with
20
- gaps for days that had no input tokens.
21
- - **Model usage** — a donut chart, an attributed model list (provider source,
22
- sessions, turns, tokens, share), and a stacked daily/weekly usage chart.
23
- - **Range selector** — 7, 30, 90 days, or all time.
24
- - **Fluid layout** — sized against the panel, not the window; the card strip,
25
- model panel, range control, and charts adapt continuously to the available
26
- width.
27
- - **Light and dark themes** — colours come from DSH theme tokens, including the
28
- tooltip's own dark-surface label token.
29
-
30
- | Desktop | Phone (390px) |
11
+ ## 功能
12
+
13
+ - **头部指标**:累计 Token、单日峰值、最长聊天时长、当前/最长连续天数、缓存命中率。
14
+ - **Token 活动**:最近一年的每日用量热力图,周日对齐,五级强度。
15
+ - **每日 Token 趋势**:每个 Provider 路由一条平滑曲线,共享十字准线,图例显示各自合计。
16
+ - **每日缓存命中率**:按输入 Token 加权的每日命中率;当天没有输入 Token 时留空,不画成 0%。
17
+ - **模型用量**:圆环图、带来源的模型列表(Provider、会话数、轮数、Token、占比),
18
+ 以及按日/按周切换的堆叠柱状图。
19
+ - **时间范围**:近 7 日、近 30 日、近 90 日、全部。
20
+ - **无级自适应布局**:按面板宽度而不是窗口宽度布局;统计卡、模型区、时间范围控件
21
+ 和图表都会随可用空间连续调整。
22
+ - **浅色/深色主题**:颜色来自 DSH 主题 Token;提示气泡使用自身深色表面的专用前景色。
23
+
24
+ | 桌面 | 手机(390px) |
31
25
  |---|---|
32
- | ![Desktop](docs/dashboard.png) | ![Phone](docs/dashboard-mobile.png) |
26
+ | ![桌面](docs/dashboard.png) | ![手机](docs/dashboard-mobile.png) |
33
27
 
34
- ## Install
28
+ ## 安装
35
29
 
36
- The plugin is a DSH bundle. It needs a harness build that provides the
37
- `webServer` service.
30
+ 本插件是一个 DSH Bundle,需要宿主提供 `webServer` 服务。
38
31
 
39
- ### From npm
32
+ ### 从 npm 安装
40
33
 
41
- The package is published as `dsh-usage-overview`. Add it to the active profile:
34
+ 包名为 `dsh-usage-overview`。把它加入当前 Profile:
42
35
 
43
36
  ```sh
44
37
  cd "$DSH_HOME/profiles/desktop"
45
38
  pnpm add dsh-usage-overview
46
39
  ```
47
40
 
48
- Then add `"dsh-usage-overview"` to `dsh.profile.bundles` in that profile's
49
- `package.json` and restart DeepSeek Harness.
41
+ 然后在 Profile 的 `package.json` 中把 `"dsh-usage-overview"` 加入
42
+ `dsh.profile.bundles`,重启 DeepSeek Harness。
50
43
 
51
- ### From a local copy
44
+ ### 从本地目录安装
52
45
 
53
- 1. Copy the package into the target profile:
46
+ 1. 将包复制到目标 Profile:
54
47
 
55
48
  ```sh
56
49
  cp -r dsh-usage-overview "$DSH_HOME/profiles/desktop/node_modules/"
57
50
  ```
58
51
 
59
- 2. Add it to the profile's bundle list in
60
- `$DSH_HOME/profiles/desktop/package.json`:
52
+ 2. 在 `$DSH_HOME/profiles/desktop/package.json` 的 Bundle 列表中注册:
61
53
 
62
54
  ```json
63
55
  {
@@ -69,109 +61,94 @@ Then add `"dsh-usage-overview"` to `dsh.profile.bundles` in that profile's
69
61
  }
70
62
  ```
71
63
 
72
- 3. Restart DeepSeek Harness. The sidebar entry **用量统计** / **Usage** appears
73
- after the profile is composed.
64
+ 3. 重启 DeepSeek Harness。侧边栏出现 **用量统计** 入口。
74
65
 
75
- The Desktop shell composes its profile once at launch. Editing files while it is
76
- running does not mount a new bundle; quit and relaunch. A CLI-launched profile
77
- with DSH's HMR bundle can reload on a manifest change.
66
+ Desktop 版本只在启动时组装一次 Profile,运行中修改文件不会挂载新 Bundle,需要退出并
67
+ 重新启动。使用 DSH HMR Bundle 的 CLI Profile 可以在清单变化时自动重载。
78
68
 
79
- ## Usage
69
+ ## 使用
80
70
 
81
- Open **用量统计** in the sidebar.
71
+ 在侧边栏打开 **用量统计**。
82
72
 
83
- - The range selector controls the headline metrics, the daily token trend, the
84
- cache-rate chart, and the model usage trend.
85
- - The activity heatmap always draws a year grid; the range selector does not
86
- change its window.
87
- - Hovering a chart raises exact figures for the hovered day or week.
88
- - The model usage chart has a **每日 / 每周** switch. Weeks start on Monday; a
89
- partial week at either end of the range remains visible.
90
- - On narrow panels the heatmap scrolls horizontally and opens at the most recent
91
- weeks.
73
+ - 时间范围控制头部指标、每日 Token 趋势、缓存命中率图以及模型用量趋势。
74
+ - Token 活动始终绘制全年网格,时间范围不会改变它的窗口。
75
+ - 悬停图表可查看对应日期/周的精确数据。
76
+ - 模型用量图支持 **每日 / 每周** 切换;周以周一为起点,首尾不完整的周仍会显示。
77
+ - 面板较窄时,热力图可横向滚动,并默认定位到最新几周。
92
78
 
93
- ## Data
79
+ ## 数据来源
94
80
 
95
- The plugin reads durable harness data only. It writes no harness state, calls no
96
- model, and registers no model-facing tool.
81
+ 插件只读取 Harness 的持久化数据,不写入任何 Harness 状态,不调用模型,也不注册
82
+ 面向模型的工具。
97
83
 
98
- 1. **Session logs** — `$DSH_HOME/sessions/<workspace>/<session>/session.v4.jsonl.zstd`.
99
- Each log is a sequence of independently compressed zstd frames; every frame is
100
- decoded separately. Assistant messages carry their own timestamp, provider
101
- usage, provider, and model, which yields the real daily and per-route series.
102
- 2. **Session index** — directory names provide session identity, creation time,
103
- and log paths.
104
- 3. **Projection cache** — `$DSH_HOME/storages/session_projcache/sessions/*.json`
105
- is a fallback for unreadable logs and supplies session titles.
106
- 4. **Live session services** — `ctx.sessions.list()` and
107
- `ctx.sessionProjections.snapshot(session)` make an active session's running
108
- totals count immediately.
84
+ 1. **会话日志**:`$DSH_HOME/sessions/<workspace>/<session>/session.v4.jsonl.zstd`。
85
+ 每个日志由多个独立压缩的 zstd frame 组成,需要逐帧解码。assistant 消息自带时间、
86
+ Provider 用量、Provider 和模型信息,可还原真实的每日与分路由数据。
87
+ 2. **会话索引**:目录信息提供会话 ID、创建时间和日志路径。
88
+ 3. **投影缓存**:`$DSH_HOME/storages/session_projcache/sessions/*.json` 在日志不可读时
89
+ 作为兜底,并提供会话标题。
90
+ 4. **实时会话服务**:`ctx.sessions.list()` 与
91
+ `ctx.sessionProjections.snapshot(session)` 让正在运行的会话立即计入统计。
109
92
 
110
- Cache reads are counted as billed tokens. The cache hit rate is:
93
+ 缓存读取按计费 Token 计入。缓存命中率公式:
111
94
 
112
95
  ```text
113
96
  cacheRead / (cacheRead + cacheWrite + uncachedInput)
114
97
  ```
115
98
 
116
- Output tokens are excluded because they are not cacheable.
99
+ 输出 Token 不参与计算,因为输出无法命中缓存。
117
100
 
118
- ## HTTP surface
101
+ ## HTTP 接口
119
102
 
120
- Both routes are read-only.
103
+ 接口只读,不写入任何 Harness 状态。
121
104
 
122
- | Route | Purpose |
105
+ | 路由 | 用途 |
123
106
  |---|---|
124
- | `GET /plugins/dsh-usage-overview/stats?range=7d\|30d\|90d\|all` | Aggregate dashboard document |
125
- | `GET /plugins/dsh-usage-overview/session?id=<session-id>` | One durable session record |
107
+ | `GET /plugins/dsh-usage-overview/stats?range=7d\|30d\|90d\|all` | 聚合后的看板数据 |
126
108
 
127
- A request is accepted when it comes from loopback, or when DSH's session
128
- authentication vouches for it. The second path lets a phone reach the panel
129
- through the remote tunnel without opening the route to anonymous callers.
109
+ 来自本机回环地址的请求会被接受;经过 DSH 会话认证的远程请求同样会被接受,因此
110
+ 手机通过远程隧道访问时无需把接口暴露给匿名调用者。
130
111
 
131
- The browser half is provided by DSH's client module system and advertised in the
132
- page's boot graph.
112
+ 浏览器端由 DSH 客户端模块系统提供,并在页面的 boot graph 中声明。
133
113
 
134
- ## Development
114
+ ## 开发
135
115
 
136
- No bundler or runtime dependency is required. Node.js runs the build and check
137
- scripts directly.
116
+ 构建和检查脚本不依赖打包器,直接用 Node.js 运行。
138
117
 
139
118
  ```sh
140
119
  node scripts/build.mjs
141
120
  ```
142
121
 
143
- This copies the Host half (`lib/*.js`) from `src/` and bundles the browser half
144
- into `lib/client.js` using DSH's module-loading format.
122
+ 该命令把 Host 端的 `lib/*.js` 从 `src/` 复制过去,并把浏览器端打包成
123
+ `lib/client.js`(DSH 的模块加载格式)。
145
124
 
146
- ### Checks
125
+ ### 检查
147
126
 
148
- | Command | Purpose |
127
+ | 命令 | 作用 |
149
128
  |---|---|
150
- | `node scripts/check-sources.mjs` | Client source syntax and stylesheet template |
151
- | `node scripts/lint-bundle.mjs` | Built browser bundle parses |
152
- | `node scripts/check-build-fresh.mjs` | Committed `lib/` matches a fresh build |
153
- | `node scripts/test-aggregation.mjs` | Aggregation, attribution, cache-rate, and edge cases |
154
- | `node scripts/render-check.mjs` | Bundle materializes and renders in a React stub |
155
- | `node scripts/preview.mjs` | Static dashboard preview |
156
- | `node scripts/responsive-check.mjs [origin]` | Seven widths, live resize, light/dark contrast, screenshots |
157
- | `node scripts/verify-install.mjs` | Installed profile package, exports, routes, trust guard |
158
- | `node scripts/verify-live.mjs [origin]` | Running host serves the routes and bundle |
159
-
160
- `responsive-check.mjs` and `verify-live.mjs` need a running host; pass its origin
161
- when it is not the default `http://127.0.0.1:50494`.
162
-
163
- ## Layout and theming
164
-
165
- The dashboard measures the panel, not the viewport. The card strip flows on a
166
- 150px basis, the model panel and range control wrap by content width, and each
167
- chart redraws at its measured pixel width. Type, spacing, and padding scale with
168
- container query units, so there are no hard layout breakpoints.
169
-
170
- Colours use DSH `--dsw-*` tokens for both themes. The tooltip is a dark surface in
171
- both light and dark mode and therefore uses `--dsw-alias-tooltip-label`; small
172
- labels and chart axes use the higher-contrast secondary label token. The
173
- `responsive-check.mjs` theme pass enforces a minimum contrast ratio of 4.5:1.
174
-
175
- ## License
129
+ | `node scripts/check-sources.mjs` | 客户端源码语法与样式模板 |
130
+ | `node scripts/lint-bundle.mjs` | 构建后的浏览器 Bundle 可解析 |
131
+ | `node scripts/check-build-fresh.mjs` | `lib/` 与最新构建一致 |
132
+ | `node scripts/test-aggregation.mjs` | 聚合、归属、缓存命中率与边界条件 |
133
+ | `node scripts/render-check.mjs` | Bundle 可物化并在 React Stub 中渲染 |
134
+ | `node scripts/preview.mjs` | 生成静态预览 |
135
+ | `node scripts/responsive-check.mjs [origin]` | 七种宽度、实时缩放、浅色/深色对比度、截图 |
136
+ | `node scripts/verify-install.mjs` | 已安装 Profile 的清单、导出、路由与信任校验 |
137
+ | `node scripts/verify-live.mjs [origin]` | 运行中的宿主确实提供路由和 Bundle |
138
+
139
+ `responsive-check.mjs` 与 `verify-live.mjs` 需要宿主正在运行;如果端口不是默认的
140
+ `http://127.0.0.1:50494`,请把实际地址作为参数传入。
141
+
142
+ ## 布局与主题
143
+
144
+ 看板测量的是面板宽度,不是窗口宽度。统计卡以 150px 为基准自动换行,模型区和时间
145
+ 范围控件按内容宽度决定并排或换行,每个图表按测量到的像素宽度重绘;字号、间距和
146
+ 内边距使用容器查询单位连续缩放,不依赖固定布局断点。
147
+
148
+ 颜色使用 DSH 的 `--dsw-*` 主题 Token。提示气泡在浅色和深色主题下都是深色表面,
149
+ 因此使用 `--dsw-alias-tooltip-label`;小号标签和图表坐标轴使用对比度更高的
150
+ Secondary 文本 Token。`responsive-check.mjs` 的主题检查会强制最低对比度不低于 4.5:1。
151
+
152
+ ## 许可证
176
153
 
177
154
  MIT
package/icon.svg ADDED
@@ -0,0 +1,11 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36" fill="none">
2
+ <defs>
3
+ <linearGradient id="dshUsageOverviewDial" x1="7" y1="27" x2="29" y2="9" gradientUnits="userSpaceOnUse">
4
+ <stop offset="0" stop-color="#39c07a"/>
5
+ <stop offset="1" stop-color="#4f8ef7"/>
6
+ </linearGradient>
7
+ </defs>
8
+ <path d="M8.09 25.41A12.2 12.2 0 1 1 27.91 25.41" stroke="url(#dshUsageOverviewDial)" stroke-width="4.2" stroke-linecap="round"/>
9
+ <path d="M18 18.5 23.3 11.72" stroke="#e8892b" stroke-width="3.4" stroke-linecap="round"/>
10
+ <circle cx="18" cy="18.5" r="2.7" fill="#e8892b"/>
11
+ </svg>
package/lib/client.js CHANGED
@@ -15,7 +15,6 @@ window.__ModuleLoader__.load({
15
15
 
16
16
  const USAGE_STATS_PATH = '/plugins/dsh-usage-overview/stats';
17
17
 
18
- const USAGE_SESSION_PATH = '/plugins/dsh-usage-overview/session';
19
18
 
20
19
  const RANGE_PRESETS = Object.freeze([
21
20
  { id: '7d', days: 7 },
@@ -112,7 +111,7 @@ window.__ModuleLoader__.load({
112
111
  const day = String(date.getDate()).padStart(2, '0');
113
112
  return `${String(date.getFullYear())}-${month}-${day}`;
114
113
  }
115
- return { USAGE_SCHEMA_VERSION, PANEL_ID, NS, USAGE_STATS_PATH, USAGE_SESSION_PATH, RANGE_PRESETS, PROVIDER_SOURCE_LABELS, SERIES_COLORS, TOKEN_BUCKETS, cacheHitRate, isUsageDocument, formatTokens, formatTokensZh, formatDuration, formatPercent, dayKeyOf };
114
+ return { USAGE_SCHEMA_VERSION, PANEL_ID, NS, USAGE_STATS_PATH, RANGE_PRESETS, PROVIDER_SOURCE_LABELS, SERIES_COLORS, TOKEN_BUCKETS, cacheHitRate, isUsageDocument, formatTokens, formatTokensZh, formatDuration, formatPercent, dayKeyOf };
116
115
  })();
117
116
 
118
117
  // ---- src/client/charts.js ----
@@ -312,7 +311,7 @@ window.__ModuleLoader__.load({
312
311
  const scrollState = useRef({ overflowing: false, atRight: true });
313
312
 
314
313
  const grid = useMemo(() => buildHeatGrid(days, HEATMAP_DAYS, now), [days, now]);
315
- const peak = useMemo(() => days.reduce((max, day) => Math.max(max, day.total), 0), [days]);
314
+ const peak = useMemo(() => days.reduce((max, day) => Math.max(max, day.total ?? 0), 0), [days]);
316
315
 
317
316
  useEffect(() => {
318
317
  const node = host.current;
@@ -502,7 +501,7 @@ window.__ModuleLoader__.load({
502
501
  return { count, labels, lines, gridLines, ticks, xOf, peak };
503
502
  }, [days, series, rangeDays, width, height, padTop, padRight, padBottom, padLeft]);
504
503
 
505
- const hover = hoverIndex === null ? null : plot.labels[hoverIndex];
504
+ const hover = hoverIndex === null ? null : (plot.labels[hoverIndex] ?? null);
506
505
 
507
506
  return h(
508
507
  'div',
@@ -693,8 +692,8 @@ window.__ModuleLoader__.load({
693
692
 
694
693
  const empty = plot.values.length === 0;
695
694
 
696
- const hover = hoverIndex === null ? null : plot.labels[hoverIndex];
697
- const hoverRate = hoverIndex === null ? null : plot.rates[hoverIndex];
695
+ const hover = hoverIndex === null ? null : (plot.labels[hoverIndex] ?? null);
696
+ const hoverRate = hoverIndex === null ? null : (plot.rates[hoverIndex] ?? null);
698
697
  const hoverTotals = hover?.entry?.totals;
699
698
  const hoverRead = hoverTotals?.cacheReadTokens ?? 0;
700
699
  const hoverInput =
@@ -1156,7 +1155,7 @@ window.__ModuleLoader__.load({
1156
1155
  }, [days, models, rangeDays, granularity, width, height, padTop, padRight, padBottom, padLeft]);
1157
1156
 
1158
1157
  const empty = models.length === 0 || plot.values.every((value) => value <= 0);
1159
- const hover = hoverIndex === null ? null : plot.bars[hoverIndex];
1158
+ const hover = hoverIndex === null ? null : (plot.bars[hoverIndex] ?? null);
1160
1159
  const hoverRows = [];
1161
1160
  if (hover !== null) {
1162
1161
  hoverRows.push(`总计 ${formatTokensZh(hover.total)} tokens`);
package/lib/index.js CHANGED
@@ -4,12 +4,11 @@ import { join } from 'node:path';
4
4
  import {
5
5
  PANEL_ID,
6
6
  PROVIDER_SOURCE_LABELS,
7
- USAGE_SESSION_PATH,
8
7
  USAGE_STATS_PATH,
9
8
  } from './protocol.js';
10
9
  import { buildUsageDocument, collectSessions, mergeLive } from './usage.js';
11
10
 
12
- export { PANEL_ID, NS, USAGE_STATS_PATH, USAGE_SESSION_PATH } from './protocol.js';
11
+ export { PANEL_ID, NS, USAGE_STATS_PATH } from './protocol.js';
13
12
 
14
13
  export const inject = ['webServer'];
15
14
 
@@ -176,40 +175,4 @@ export function apply(ctx) {
176
175
  },
177
176
  'stats route',
178
177
  );
179
-
180
- mount(
181
- USAGE_SESSION_PATH,
182
- (req, res) => {
183
- void (async () => {
184
- if (req.method !== 'GET' && req.method !== 'HEAD') {
185
- json(res, 405, { error: 'method-not-allowed' });
186
- return;
187
- }
188
- if (!trustedRequest(ctx, req)) {
189
- json(res, 403, { error: 'request-not-trusted' });
190
- return;
191
- }
192
- try {
193
- const url = new URL(req.url ?? '/', 'http://127.0.0.1');
194
- const id = url.searchParams.get('id');
195
- if (id === null || id.length === 0) {
196
- json(res, 400, { error: 'missing-session-id' });
197
- return;
198
- }
199
- const home = resolveHome();
200
- const sessions = await collectSessions(home);
201
- const found = sessions.find((session) => session.id === id);
202
- if (found === undefined) {
203
- json(res, 404, { error: 'session-not-found' });
204
- return;
205
- }
206
- json(res, 200, { schemaVersion: 1, session: found });
207
- } catch (error) {
208
- ctx.logger?.warn?.(`dsh-usage-overview: session read failed: ${String(error)}`);
209
- json(res, 500, { error: 'usage-unavailable' });
210
- }
211
- })();
212
- },
213
- 'session route',
214
- );
215
178
  }
package/lib/protocol.js CHANGED
@@ -6,7 +6,6 @@ export const NS = 'usage-overview';
6
6
 
7
7
  export const USAGE_STATS_PATH = '/plugins/dsh-usage-overview/stats';
8
8
 
9
- export const USAGE_SESSION_PATH = '/plugins/dsh-usage-overview/session';
10
9
 
11
10
  export const RANGE_PRESETS = Object.freeze([
12
11
  { id: '7d', days: 7 },
package/package.json CHANGED
@@ -2,7 +2,8 @@
2
2
  "name": "dsh-usage-overview",
3
3
  "displayName": "DSH Usage Overview",
4
4
  "description": "A usage overview for DeepSeek Harness: token totals, activity heatmap, daily token and cache trends, and per-model attribution.",
5
- "version": "1.0.0",
5
+ "version": "1.1.1",
6
+ "icon": "icon.svg",
6
7
  "author": "w-callan-w",
7
8
  "repository": {
8
9
  "type": "git",
@@ -29,8 +30,9 @@
29
30
  "files": [
30
31
  "lib",
31
32
  "cordis.patch.yml",
33
+ "icon.svg",
32
34
  "README.md",
33
- "README.zh-CN.md"
35
+ "README.en.md"
34
36
  ],
35
37
  "license": "MIT",
36
38
  "dsh": {
package/README.zh-CN.md DELETED
@@ -1,155 +0,0 @@
1
- # DSH 用量总览
2
-
3
- [English](README.md)
4
-
5
- 一款 DeepSeek Harness 的用量总览面板插件。插件直接读取 Harness 自身的会话记录,
6
- 展示 Token 总量、全年活跃热力图、每日 Token 与缓存命中率趋势,以及按模型拆分的
7
- 用量构成和按日/按周堆叠图。
8
-
9
- [GitHub](https://github.com/w-callan-w/dsh-usage-overview) · [Gitee](https://gitee.com/callanjones/deep-seek-harness-usage-plugin) · [npm](https://www.npmjs.com/package/dsh-usage-overview)
10
-
11
- ## 功能
12
-
13
- - **头部指标**:累计 Token、单日峰值、最长聊天时长、当前/最长连续天数、缓存命中率。
14
- - **Token 活动**:最近一年的每日用量热力图,周日对齐,五级强度。
15
- - **每日 Token 趋势**:每个 Provider 路由一条平滑曲线,共享十字准线,图例显示各自合计。
16
- - **每日缓存命中率**:按输入 Token 加权的每日命中率;当天没有输入 Token 时留空,不画成 0%。
17
- - **模型用量**:圆环图、带来源的模型列表(Provider、会话数、轮数、Token、占比),
18
- 以及按日/按周切换的堆叠柱状图。
19
- - **时间范围**:近 7 日、近 30 日、近 90 日、全部。
20
- - **无级自适应布局**:按面板宽度而不是窗口宽度布局;统计卡、模型区、时间范围控件
21
- 和图表都会随可用空间连续调整。
22
- - **浅色/深色主题**:颜色来自 DSH 主题 Token;提示气泡使用自身深色表面的专用前景色。
23
-
24
- | 桌面 | 手机(390px) |
25
- |---|---|
26
- | ![桌面](docs/dashboard.png) | ![手机](docs/dashboard-mobile.png) |
27
-
28
- ## 安装
29
-
30
- 本插件是一个 DSH Bundle,需要宿主提供 `webServer` 服务。
31
-
32
- ### 从 npm 安装
33
-
34
- 包名为 `dsh-usage-overview`。把它加入当前 Profile:
35
-
36
- ```sh
37
- cd "$DSH_HOME/profiles/desktop"
38
- pnpm add dsh-usage-overview
39
- ```
40
-
41
- 然后在 Profile 的 `package.json` 中把 `"dsh-usage-overview"` 加入
42
- `dsh.profile.bundles`,重启 DeepSeek Harness。
43
-
44
- ### 从本地目录安装
45
-
46
- 1. 将包复制到目标 Profile:
47
-
48
- ```sh
49
- cp -r dsh-usage-overview "$DSH_HOME/profiles/desktop/node_modules/"
50
- ```
51
-
52
- 2. 在 `$DSH_HOME/profiles/desktop/package.json` 的 Bundle 列表中注册:
53
-
54
- ```json
55
- {
56
- "dsh": {
57
- "profile": {
58
- "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-usage-overview"]
59
- }
60
- }
61
- }
62
- ```
63
-
64
- 3. 重启 DeepSeek Harness。侧边栏出现 **用量统计** 入口。
65
-
66
- Desktop 版本只在启动时组装一次 Profile,运行中修改文件不会挂载新 Bundle,需要退出并
67
- 重新启动。使用 DSH HMR Bundle 的 CLI Profile 可以在清单变化时自动重载。
68
-
69
- ## 使用
70
-
71
- 在侧边栏打开 **用量统计**。
72
-
73
- - 时间范围控制头部指标、每日 Token 趋势、缓存命中率图以及模型用量趋势。
74
- - Token 活动始终绘制全年网格,时间范围不会改变它的窗口。
75
- - 悬停图表可查看对应日期/周的精确数据。
76
- - 模型用量图支持 **每日 / 每周** 切换;周以周一为起点,首尾不完整的周仍会显示。
77
- - 面板较窄时,热力图可横向滚动,并默认定位到最新几周。
78
-
79
- ## 数据来源
80
-
81
- 插件只读取 Harness 的持久化数据,不写入任何 Harness 状态,不调用模型,也不注册
82
- 面向模型的工具。
83
-
84
- 1. **会话日志**:`$DSH_HOME/sessions/<workspace>/<session>/session.v4.jsonl.zstd`。
85
- 每个日志由多个独立压缩的 zstd frame 组成,需要逐帧解码。assistant 消息自带时间、
86
- Provider 用量、Provider 和模型信息,可还原真实的每日与分路由数据。
87
- 2. **会话索引**:目录信息提供会话 ID、创建时间和日志路径。
88
- 3. **投影缓存**:`$DSH_HOME/storages/session_projcache/sessions/*.json` 在日志不可读时
89
- 作为兜底,并提供会话标题。
90
- 4. **实时会话服务**:`ctx.sessions.list()` 与
91
- `ctx.sessionProjections.snapshot(session)` 让正在运行的会话立即计入统计。
92
-
93
- 缓存读取按计费 Token 计入。缓存命中率公式:
94
-
95
- ```text
96
- cacheRead / (cacheRead + cacheWrite + uncachedInput)
97
- ```
98
-
99
- 输出 Token 不参与计算,因为输出无法命中缓存。
100
-
101
- ## HTTP 接口
102
-
103
- 两个接口都是只读的。
104
-
105
- | 路由 | 用途 |
106
- |---|---|
107
- | `GET /plugins/dsh-usage-overview/stats?range=7d\|30d\|90d\|all` | 聚合后的看板数据 |
108
- | `GET /plugins/dsh-usage-overview/session?id=<session-id>` | 单个会话的持久化记录 |
109
-
110
- 来自本机回环地址的请求会被接受;经过 DSH 会话认证的远程请求同样会被接受,因此
111
- 手机通过远程隧道访问时无需把接口暴露给匿名调用者。
112
-
113
- 浏览器端由 DSH 客户端模块系统提供,并在页面的 boot graph 中声明。
114
-
115
- ## 开发
116
-
117
- 构建和检查脚本不依赖打包器,直接用 Node.js 运行。
118
-
119
- ```sh
120
- node scripts/build.mjs
121
- ```
122
-
123
- 该命令把 Host 端的 `lib/*.js` 从 `src/` 复制过去,并把浏览器端打包成
124
- `lib/client.js`(DSH 的模块加载格式)。
125
-
126
- ### 检查
127
-
128
- | 命令 | 作用 |
129
- |---|---|
130
- | `node scripts/check-sources.mjs` | 客户端源码语法与样式模板 |
131
- | `node scripts/lint-bundle.mjs` | 构建后的浏览器 Bundle 可解析 |
132
- | `node scripts/check-build-fresh.mjs` | `lib/` 与最新构建一致 |
133
- | `node scripts/test-aggregation.mjs` | 聚合、归属、缓存命中率与边界条件 |
134
- | `node scripts/render-check.mjs` | Bundle 可物化并在 React Stub 中渲染 |
135
- | `node scripts/preview.mjs` | 生成静态预览 |
136
- | `node scripts/responsive-check.mjs [origin]` | 七种宽度、实时缩放、浅色/深色对比度、截图 |
137
- | `node scripts/verify-install.mjs` | 已安装 Profile 的清单、导出、路由与信任校验 |
138
- | `node scripts/verify-live.mjs [origin]` | 运行中的宿主确实提供路由和 Bundle |
139
-
140
- `responsive-check.mjs` 与 `verify-live.mjs` 需要宿主正在运行;如果端口不是默认的
141
- `http://127.0.0.1:50494`,请把实际地址作为参数传入。
142
-
143
- ## 布局与主题
144
-
145
- 看板测量的是面板宽度,不是窗口宽度。统计卡以 150px 为基准自动换行,模型区和时间
146
- 范围控件按内容宽度决定并排或换行,每个图表按测量到的像素宽度重绘;字号、间距和
147
- 内边距使用容器查询单位连续缩放,不依赖固定布局断点。
148
-
149
- 颜色使用 DSH 的 `--dsw-*` 主题 Token。提示气泡在浅色和深色主题下都是深色表面,
150
- 因此使用 `--dsw-alias-tooltip-label`;小号标签和图表坐标轴使用对比度更高的
151
- Secondary 文本 Token。`responsive-check.mjs` 的主题检查会强制最低对比度不低于 4.5:1。
152
-
153
- ## 许可证
154
-
155
- MIT