dsh-plugin-token-heatmap 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 +95 -0
- package/cordis.patch.yml +4 -0
- package/lib/client.js +900 -0
- package/lib/index.js +335 -0
- package/package.json +85 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 P-CAmilE
|
|
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,95 @@
|
|
|
1
|
+
# dsh-plugin-token-heatmap
|
|
2
|
+
|
|
3
|
+
该插件为每日 Token 用量热力图插件，面向 DeepSeek Harness Web GUI（dsh web profile）。
|
|
4
|
+
|
|
5
|
+
以 53 周 × 7 天的网格展示每日 token 消耗，右下角常驻一个按当日消耗着色的方形图标，点击展开可拖动的悬浮窗。数据权威在宿主端：安装后自动回填历史会话日志，之后实时累计。
|
|
6
|
+
|
|
7
|
+
## 功能
|
|
8
|
+
|
|
9
|
+
- **双数据视图**：「全局」（所有会话合计）与「当前会话」，悬浮窗内切换
|
|
10
|
+
- **历史回填**：首次安装自动扫描全部会话日志，把过去的 token 消耗计入热力图
|
|
11
|
+
- **实时更新**：窗口可见时每 3 秒轮询，数据带版本号，仅变化时更新
|
|
12
|
+
- **5 级蓝色色阶**：12 个月窗口内非零天数按四分位分档，最深色 `#396BE2`
|
|
13
|
+
- **竖向网格**：最新一周在顶部，向下滚动回看 12 个月，带「回到最新」浮层
|
|
14
|
+
- **悬浮窗交互**：头部拖动、位置 clamp 在视口内、显隐/位置/视图记忆于 localStorage
|
|
15
|
+
- **汇总统计**：今日 / 本周 / 本月 / 12 个月合计，tooltip 展示输入 / 输出 / 缓存读写分项
|
|
16
|
+
- **主题适配**：深浅主题均正常显示（DSH 主题 token）
|
|
17
|
+
|
|
18
|
+
## 环境要求
|
|
19
|
+
|
|
20
|
+
- Node.js ≥ 20，pnpm
|
|
21
|
+
- DeepSeek Harness web profile（宿主需提供 `@deepseek-ai/*` 运行时，见 `peerDependencies`）
|
|
22
|
+
- 依赖 `@deepseek-ai/*` 为内部私有包，仅能在 DSH 环境内安装
|
|
23
|
+
|
|
24
|
+
## 构建
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pnpm install
|
|
28
|
+
pnpm build # 产出 lib/index.js（宿主）+ lib/client.js（客户端 bundle）
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## 验证
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
pnpm typecheck # tsc --noEmit
|
|
35
|
+
pnpm test # node --test，宿主端单元测试
|
|
36
|
+
pnpm test:ui # vitest，客户端组件测试
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## 安装
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
dsh plugin --profile web add dsh-plugin-token-heatmap
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
重启dsh web，右下角出现方形图标即安装成功。首次启动后台执行回填，期间界面可用。
|
|
46
|
+
|
|
47
|
+
## 数据存储
|
|
48
|
+
|
|
49
|
+
宿主端持久化在 `$DSH_HOME/token-heatmap/`（即 `~/.dsh/token-heatmap/`）：
|
|
50
|
+
|
|
51
|
+
| 文件 | 内容 |
|
|
52
|
+
|---|---|
|
|
53
|
+
| `global.json` | 全局每日用量（近 13 个月） |
|
|
54
|
+
| `sessions.json` | 按会话每日用量 |
|
|
55
|
+
| `meta.json` | 回填状态（done / scanned / skipped） |
|
|
56
|
+
|
|
57
|
+
写入策略：内存合并 → 5 秒节流 → 原子写（临时文件 + rename）。文件损坏时从空状态启动并告警，不阻断插件。
|
|
58
|
+
|
|
59
|
+
## localStorage 键（客户端）
|
|
60
|
+
|
|
61
|
+
| 键 | 说明 |
|
|
62
|
+
|---|---|
|
|
63
|
+
| `dsh.tokenHeatmap.visible` | 悬浮窗显隐 |
|
|
64
|
+
| `dsh.tokenHeatmap.position` | 悬浮窗位置 |
|
|
65
|
+
| `dsh.tokenHeatmap.iconPosition` | 图标位置 |
|
|
66
|
+
| `dsh.tokenHeatmap.view` | 视图（global / session） |
|
|
67
|
+
|
|
68
|
+
## 架构
|
|
69
|
+
|
|
70
|
+
一个 npm 包、双半区（宿主 + 客户端）：
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
src/
|
|
74
|
+
├── index.ts # 宿主端入口：实时累计 + 一次性回填
|
|
75
|
+
├── usage-store.ts # 每日聚合存储（节流原子写、13 个月裁剪）
|
|
76
|
+
├── backfill.ts # 会话日志扫描回填
|
|
77
|
+
├── service.ts # TypertRemoteService：tokenHeatmap Remote 服务
|
|
78
|
+
├── day.ts # 本地时区自然日工具
|
|
79
|
+
├── usage.ts # 聚合/合并/裁剪纯函数
|
|
80
|
+
└── client/
|
|
81
|
+
├── index.tsx # 客户端入口：挂载 Remote + shell.overlay
|
|
82
|
+
├── remote.ts # 手工 Typert Remote 描述符 + strict 校验器
|
|
83
|
+
├── TokenHeatmapOverlay.tsx # 悬浮窗 + 右下角图标
|
|
84
|
+
├── HeatmapGrid.tsx # 周×天网格（竖向滚动）
|
|
85
|
+
├── ToggleIcon.tsx # 右下角方形图标
|
|
86
|
+
└── palette.ts # 5 级色阶与四分位映射
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
- **数据通道**：客户端 ↔ 宿主走 Typert Remote 机制（`@Remote` 方法暴露为 `<namespace>/<method>` 端点）；方法有 `getGlobalUsage` / `getSessionUsage` / `getBackfillStatus`
|
|
90
|
+
- **UI 注册**：`ctx.slots.inject('shell.overlay', ...)` 挂到根级浮动层
|
|
91
|
+
- **用量口径**：input + output + cacheRead + cacheWrite 合并为每日 total 用于着色
|
|
92
|
+
|
|
93
|
+
## License
|
|
94
|
+
|
|
95
|
+
[MIT](LICENSE)
|
package/cordis.patch.yml
ADDED