dsh-usage-overview 0.0.0-stage → 1.1.0
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/LICENSE +21 -0
- package/README.en.md +176 -0
- package/README.md +153 -2
- package/cordis.patch.yml +3 -0
- package/lib/client.js +2185 -0
- package/lib/index.js +178 -0
- package/lib/log-fold.js +196 -0
- package/lib/protocol.js +104 -0
- package/lib/usage.js +425 -0
- package/package.json +44 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 callanjones
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
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
|
+
|  |  |
|
|
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,3 +1,154 @@
|
|
|
1
|
-
#
|
|
1
|
+
# DSH 用量总览
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[English](README.en.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
|
+
|  |  |
|
|
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
|
+
接口只读,不写入任何 Harness 状态。
|
|
104
|
+
|
|
105
|
+
| 路由 | 用途 |
|
|
106
|
+
|---|---|
|
|
107
|
+
| `GET /plugins/dsh-usage-overview/stats?range=7d\|30d\|90d\|all` | 聚合后的看板数据 |
|
|
108
|
+
|
|
109
|
+
来自本机回环地址的请求会被接受;经过 DSH 会话认证的远程请求同样会被接受,因此
|
|
110
|
+
手机通过远程隧道访问时无需把接口暴露给匿名调用者。
|
|
111
|
+
|
|
112
|
+
浏览器端由 DSH 客户端模块系统提供,并在页面的 boot graph 中声明。
|
|
113
|
+
|
|
114
|
+
## 开发
|
|
115
|
+
|
|
116
|
+
构建和检查脚本不依赖打包器,直接用 Node.js 运行。
|
|
117
|
+
|
|
118
|
+
```sh
|
|
119
|
+
node scripts/build.mjs
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
该命令把 Host 端的 `lib/*.js` 从 `src/` 复制过去,并把浏览器端打包成
|
|
123
|
+
`lib/client.js`(DSH 的模块加载格式)。
|
|
124
|
+
|
|
125
|
+
### 检查
|
|
126
|
+
|
|
127
|
+
| 命令 | 作用 |
|
|
128
|
+
|---|---|
|
|
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
|
+
## 许可证
|
|
153
|
+
|
|
154
|
+
MIT
|
package/cordis.patch.yml
ADDED