zcode-usage-stats 0.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.md +176 -0
- package/cordis.patch.yml +4 -0
- package/lib/client.js +1124 -0
- package/lib/index.mjs +416 -0
- package/package.json +53 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 qianxiao1213
|
|
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.md
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
<p align="center"><img src="https://capsule-render.vercel.app/api?type=waving&color=0:1D5FD0,100:0E7C86&height=170§ion=header&text=zcode-usage-stats&fontSize=56&fontColor=ffffff&animation=fadeIn" width="100%"></p>
|
|
2
|
+
|
|
3
|
+
<div align="center">
|
|
4
|
+
|
|
5
|
+
#### DeepSeek Harness（DSH）插件：ZCode 风格的 Token 用量统计面板
|
|
6
|
+
|
|
7
|
+
**覆盖：全历史会话扫描 × 用量趋势 × 模型仪表盘 × 活跃热力图 × 深浅双主题**
|
|
8
|
+
|
|
9
|
+
[](https://git.io/typing-svg)
|
|
10
|
+
|
|
11
|
+
[](#-版本历史)
|
|
12
|
+
[](#-安装)
|
|
13
|
+
[](#-设计与实现)
|
|
14
|
+
[](#-许可与致谢)
|
|
15
|
+
|
|
16
|
+
</div>
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
一个装进 DSH 设置页的「Token 记账本」。扫描 `~/.dsh` 下的全历史会话，把每一枚 token 按天、按小时、按模型算清楚：今天写了多少、哪个模型最费、哪天是巅峰。**纯本地扫描、本地聚合、本地渲染**——数据不出本机。
|
|
21
|
+
|
|
22
|
+
> ⚠️ 非官方社区插件，与 DeepSeek / ZCode 无关联。"zcode" 仅为致敬对象与包名沿用。
|
|
23
|
+
|
|
24
|
+
## 📸 界面预览
|
|
25
|
+
|
|
26
|
+
| ☀️ 浅色主题 | 🌙 深色主题 |
|
|
27
|
+
|:---:|:---:|
|
|
28
|
+
| <img src="assets/usage-stats.png" width="400" alt="浅色主题"> | <img src="assets/usage-stats2.png" width="400" alt="深色主题"> |
|
|
29
|
+
|
|
30
|
+
## ✨ 功能特性
|
|
31
|
+
|
|
32
|
+
| 模块 | 说明 |
|
|
33
|
+
|------|------|
|
|
34
|
+
| 📅 **时间范围** | 今天 / 昨天 / 近 7 天 / 近 30 天 / 本月 / 上月 / 全部 / 自定义区间（起止自动校验防倒序） |
|
|
35
|
+
| 🔥 **活跃分布** | 日历点阵热力图：一格一天，点面积 = 当日 Token（sqrt 换算）；每日 / 每周 / 累计三档分桶；峰值日虚线圈标注 |
|
|
36
|
+
| 📈 **用量趋势** | 一条线一个模型，圆点 = 当期用量，峰值直接标数；悬停看各模型分项，图例可点击显隐 |
|
|
37
|
+
| 🍩 **模型用量** | 刻度环仪表盘：100 刻 = 100%，每 10 刻一枚锚点；扇形命中区悬停查看模型明细；模型超过 6 个自动并「其他」防撞色 |
|
|
38
|
+
| 🧮 **顶部指标** | 累计 Token / 单日峰值 / 最长会话时长 / 当前连续天数 / 最长连续天数 |
|
|
39
|
+
| ♿ **无障碍与体验** | WCAG AA 对比度（明暗双主题逐项核算）、`prefers-reduced-motion` 降级、透明命中层让小点也轻松悬停、深浅主题跟随 DSH |
|
|
40
|
+
|
|
41
|
+
## 📦 安装
|
|
42
|
+
|
|
43
|
+
前置：已安装 `@deepseek-ai/dsh`（及 DSH 插件命令依赖的 `pnpm`）。
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
dsh plugin --profile web add github:Amer-CN/zcode-usage-stats
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
> 包发布到 npm 后，可改用 `dsh plugin --profile web add zcode-usage-stats`。
|
|
50
|
+
|
|
51
|
+
安装后重启 DSH 进程，打开 **设置 → 使用统计** 即可看到统计页面。
|
|
52
|
+
|
|
53
|
+
## 🚀 使用
|
|
54
|
+
|
|
55
|
+
- 顶部切换时间范围；**「全部」**显示自使用以来的所有数据。
|
|
56
|
+
- 趋势图悬停查看各模型分项，点击图例显隐对应模型。
|
|
57
|
+
- **「刷新」**强制重新扫描全部会话。
|
|
58
|
+
|
|
59
|
+
## ⚙️ 工作原理
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
~/.dsh 会话文件
|
|
63
|
+
│
|
|
64
|
+
▼ sessionPersistence 全量枚举 + 回放事件
|
|
65
|
+
按天 / 按小时 / 按模型聚合 ──► 内存 + 磁盘双层缓存（SWR）
|
|
66
|
+
│
|
|
67
|
+
▼
|
|
68
|
+
GET /api/usage-stats（过宿主信任栅栏：Host/Origin + cookie）
|
|
69
|
+
│
|
|
70
|
+
▼
|
|
71
|
+
设置页前端：手写 SVG 按实测容器宽度 1:1 出图
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## 🎨 设计与实现
|
|
75
|
+
|
|
76
|
+
| 设计点 | 说明 |
|
|
77
|
+
|--------|------|
|
|
78
|
+
| **图表** | 手写 SVG（日历点阵 / 发丝折线 / 刻度环），零运行时图表库依赖 |
|
|
79
|
+
| **配色** | 自研双轨色板：类目色 6 个跨色相承载模型身份，序数色单色相明度阶承载用量大小；两套主题均满足 WCAG AA，类目色两两色距核算保证一眼可分 |
|
|
80
|
+
| **排版** | 固定 px 字阶 + 4 的倍数间距阶梯；图表按 ResizeObserver 实测容器宽度 1:1 出图，不做等比缩放，字号真实可读 |
|
|
81
|
+
| **命中区** | 视觉元素不绑事件：热力图逐格透明矩形、刻度环整圈扇形 path，悬停不闪烁 |
|
|
82
|
+
| **服务端** | 复用宿主 `sessionPersistence` 聚合；内存 + 磁盘双层缓存，SWR 过期后台刷新，首屏不因全量扫描卡顿 |
|
|
83
|
+
| **安全** | `/api/usage-stats` 自行通过宿主 `connection.requestRejection` 信任栅栏鉴权 |
|
|
84
|
+
|
|
85
|
+
## 🔢 数据口径
|
|
86
|
+
|
|
87
|
+
| 指标 | 口径 |
|
|
88
|
+
|------|------|
|
|
89
|
+
| Token 用量 | 以 `assistant/message` 事件携带的全量 `usage` 为准（input + output + cacheRead + cacheWrite），按 `turn:step` 去重防重复计数 |
|
|
90
|
+
| Turns | 以 `step/end` 事件按新 turn 计数（覆盖 completed / failed / cancelled） |
|
|
91
|
+
| 模型归属 | 优先取消息自身 `model`，回退 `request/context` 当前模型，再回退归并为 `other` |
|
|
92
|
+
| 活跃日 | 当天有 ≥1 条 usage 事件；连续天数按活跃日相邻日推算 |
|
|
93
|
+
|
|
94
|
+
## 🤝 兼容性
|
|
95
|
+
|
|
96
|
+
- 针对 DSH 开发者预览版开发，锁定 `@deepseek-ai/dsh >= 0.1.0-rc.5`。
|
|
97
|
+
- 依赖 DSH 宿主提供的 `sessionPersistence`、`webServer`、`connection` 服务，以及客户端运行时 `@deepseek-ai/dsh-client-runtime`、`@deepseek-ai/dsh-client-ui-slots`。
|
|
98
|
+
|
|
99
|
+
## 🗂️ 仓库结构
|
|
100
|
+
|
|
101
|
+
<details>
|
|
102
|
+
<summary><b>目录树</b>（点击展开）</summary>
|
|
103
|
+
|
|
104
|
+
```
|
|
105
|
+
zcode-usage-stats/
|
|
106
|
+
├── package.json # 插件清单（dsh 客户端注入声明）
|
|
107
|
+
├── cordis.patch.yml # DSH 补丁声明
|
|
108
|
+
├── LICENSE # MIT
|
|
109
|
+
├── README.md # 本文件
|
|
110
|
+
├── assets/
|
|
111
|
+
│ ├── usage-stats.png # 浅色主题截图
|
|
112
|
+
│ └── usage-stats2.png # 深色主题截图
|
|
113
|
+
├── build/
|
|
114
|
+
│ ├── body.js # 前端真源：界面 + 手写 SVG 图表
|
|
115
|
+
│ ├── panel.css # 前端真源：样式与配色变量
|
|
116
|
+
│ └── assemble.cjs # 合成脚本：body.js + panel.css → client.new.js
|
|
117
|
+
├── tests/
|
|
118
|
+
│ ├── acceptance.sh # 验收门禁：15 项检查（一条命令跑完）
|
|
119
|
+
│ ├── harness.cjs # 渲染挂具：模拟容器宽度渲染出预览 HTML
|
|
120
|
+
│ ├── assert.cjs # 几何断言：三张图的尺寸/可读性
|
|
121
|
+
│ ├── contrast.cjs # WCAG 对比度核算（明暗两套）
|
|
122
|
+
│ ├── preset-conformance.cjs # custom 色板合规校验
|
|
123
|
+
│ └── preview-*.html # 渲染产物（gitignore）
|
|
124
|
+
└── lib/
|
|
125
|
+
├── index.mjs # 宿主侧：扫描全历史会话 + 聚合 + 双层缓存 + API
|
|
126
|
+
└── client.js # 前端合成产物（勿直接编辑，见「从源码构建」）
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
</details>
|
|
130
|
+
|
|
131
|
+
## 🛠️ 从源码构建
|
|
132
|
+
|
|
133
|
+
`lib/client.js` 是合成产物，**请勿直接编辑**。前端真源在 `build/`：
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
# 1. 编辑 build/body.js（界面 + 图表）与 build/panel.css（样式 + 配色变量）
|
|
137
|
+
# 2. 合成
|
|
138
|
+
node build/assemble.cjs
|
|
139
|
+
|
|
140
|
+
# 3. 用合成结果覆盖部署文件
|
|
141
|
+
cp build/client.new.js lib/client.js
|
|
142
|
+
|
|
143
|
+
# 4. 验收（15 项必须全过）
|
|
144
|
+
bash tests/acceptance.sh
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
验收脚本会按真实面板宽度渲染出预览 HTML（`tests/preview-*.html`）并跑几何断言、WCAG 对比度与色板合规检查。默认读取本机 `~/.dsh` 下的用量缓存；可用 `USAGE_CACHE=/path/to/cache.json bash tests/acceptance.sh` 指定其它缓存，缓存不可用时自动改用内置合成数据。
|
|
148
|
+
|
|
149
|
+
> 提 PR 请改 `build/` 下的源文件，并在描述里附上 `bash tests/acceptance.sh` 的输出。
|
|
150
|
+
|
|
151
|
+
## 📜 版本历史
|
|
152
|
+
|
|
153
|
+
<details>
|
|
154
|
+
<summary><b>当前 v0.1.0</b>（2026-09-13）· 初始开源版本</summary>
|
|
155
|
+
|
|
156
|
+
| 版本 | 内容 |
|
|
157
|
+
|------|------|
|
|
158
|
+
| v0.1.0 | 初始开源版本：以 [qianxiao1213/zcode-usage-stats](https://github.com/qianxiao1213/zcode-usage-stats) 原版为基线，重写全部图表界面与配色（活跃分布 / 用量趋势 / 模型用量三图 + 自研双轨色板），补齐双主题截图与文档 |
|
|
159
|
+
|
|
160
|
+
</details>
|
|
161
|
+
|
|
162
|
+
## 🙏 许可与致谢
|
|
163
|
+
|
|
164
|
+
- 代码以 **MIT License** 发布，见 [LICENSE](LICENSE)。
|
|
165
|
+
- 上游致谢：基于 [qianxiao1213/zcode-usage-stats](https://github.com/qianxiao1213/zcode-usage-stats) 重构——图表界面与配色全部重写，数据聚合层在其基线上演进。
|
|
166
|
+
- 本插件为非官方社区项目，与 DeepSeek / ZCode 无关联。
|
|
167
|
+
|
|
168
|
+
<div align="center">
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
Made by [@Amer-CN](https://github.com/Amer-CN)
|
|
173
|
+
|
|
174
|
+
*数据只在本机算，哪也不去。*
|
|
175
|
+
|
|
176
|
+
</div>
|
package/cordis.patch.yml
ADDED