dsh-token-monitor

<p align="center">

<strong>简体中文</strong> | <a href="README.en.md">English</a>

</p>

> 🤖 AI 生成声明：本项目由 AI 辅助生成，仅供学习与技术交流使用，不构成任何形式的商业保证或支持承诺。

一个 DeepSeek Harness 插件：在侧边栏底部（设置图标旁）放一张 「今日用量」卡片，实时显示今日 token 总量（形如"今日用量：8888万"）；点击卡片即弹出完整统计窗口——今日 / 近 7 天 / 近 30 天总量、近 30 天按模型的堆叠用量图、按模型的使用排行（固定 30 天窗口）、以及会话数统计。不再占用设置页面，一键直达。


功能特性

• 🚀 一键直达 — 侧边栏「今日用量」卡片实时显示今日 token 总量（单行"今日用量：8888万"，每 30 秒自刷新，折叠成窄栏时只显示数值）；点击弹出统计窗口（支持 Esc / ✕ / 点遮罩关闭，背景滚动锁定）。
• 📊 近 30 天模型使用情况 — 30 天堆叠柱状图：每根柱子按模型分色堆叠（当天用量最高的模型在柱底，颜色按 30 天排名固定）；图表区域铺满灰色点阵网格背景（每一天恰好两列点、垂直每 13px 一行，参考 temp/model-usage.png），有调用的柱子叠在点阵之上；横轴只显示每周一的基准日期；悬浮/点击某天弹出明细卡片（日期 / 总计 / 各模型色块行，样式参考 temp/tooltip.png），无任何高亮/变灰/柱上标签效果。
• 🏆 模型使用排行 — 固定 30 天窗口：前 4 名 2×2 卡片（序号一行 / 模型名 + token 总数 / 提供商 + 占比右对齐，无增长与单位标签），悬停轻微放大。
• 💬 会话统计 — 今日 / 近 7 天 / 近 30 天开启的顶层对话数（不含子代理内部会话），副文字显示对应时段的模型请求次数。
• 🔄 自动刷新 — 页面每 30 秒轮询（带幂等重扫，数字自动修正），另有手动「刷新」与「回填历史」按钮。
• 💾 持久化 — 数据写入 $DSH_HOME/plugins/token-monitor/data.json，重启不丢（按天桶保留 181 天；每个桶内按模型细分）。
• 🕘 历史回填 — 会话日志是唯一数据源：启动 / 点击「回填历史」/ 30 秒轮询都会把窗口内全部会话用量幂等重扫进新桶（原子替换），把插件安装之前的用量也统计进来；重复运行不会重复计数，旧桶脏数据自动自愈，30 天堆叠图与模型排行立即可用。
• 🎨 DSH 原生风格 — 亮色主题、1px 细边框卡片、8–10px 圆角、无阴影；颜色走 --dsw-alias-* 主题变量，跟随 DSH 深色主题。

安装

从本仓库安装：

dsh plugin --profile web add github:zhangzheng25/dsh-token-monitor

或从本地目录安装：

dsh plugin --profile web add E:\path\to\dsh-token-monitor

dsh plugin 会在 profile 目录中转发给 pnpm 安装，并自动调和 dsh.profile.bundles；包内 dsh.bundle.patch（cordis.patch.yml）把插件行插入宿主组合，dsh.client.platform: "web" 让 web 外壳加载 client/bundle.js。

安装后重启 DSH，侧边栏底部（设置图标旁）会出现「今日用量」卡片，点击即弹出统计窗口。

架构

┌────────────────────────── Host（Node.js）──────────────────────────┐
│ src/index.js                                                       │
│  • backfill()               ← 会话日志为唯一数据源（幂等全量重建：   │
│      sessionQuery 为 live-preferred，内存活跃会话 + 落盘日志都算，   │
│      每次把窗口内全部 assistant/message 的 usage 折叠进新桶并原子    │
│      替换，重复运行不重复计数；启动 / 点「回填历史」/ 30 秒轮询都跑） │
│      （输入 / 输出 / 缓存命中 / 缓存未命中 / 推理，按天按模型分桶，   │
│       模型归属取 message.source，覆盖 181 天窗口）                   │
│  • buildSessionStats()      ← 顶层对话统计（delegationDepth === 0）│
│      （20 秒缓存）                                                 │
│  • persist()                ← 防抖写入（schema v3：按天按模型分桶， │
│      保留 181 天）                                                │
│      $DSH_HOME/plugins/token-monitor/data.json                      │
│  • webServer.register('/token-monitor/today') ← 轻量今日读数（不触发│
│      重建，供侧边栏卡片轮询）                                        │
│  • webServer.register('/token-monitor/snapshot') ← 供 Client 读取   │
│      （静态 bundle 模式，含 modelRank 三档聚合 + modelDaily30）       │
└─────────────────────────────────────────────────────────────────────┘
                          │ fetch('/token-monitor/snapshot')
                          ▼
┌────────────────────────── Client（浏览器）─────────────────────────┐
│ client/bundle.js — 手工构建的 web bundle，符合 client-modules 协议  │
│  （window.__ModuleLoader__.load）                                  │
│  • slots.inject('sidebar.footer.action') → 侧边栏「今日用量」卡片     │
│      （点击弹出 fixed 模态，内容 = 完整统计面板；无 settings.section）│
│  • 指标卡 + 会话卡 + 30 天模型堆叠图 + 模型使用排行                  │
│  • 卡片每 30 秒轮询 /token-monitor/today；弹窗打开时拉取快照并       │
│    每 30 秒刷新，另有刷新 / 回填历史按钮                            │
└─────────────────────────────────────────────────────────────────────┘

数据来源

• 唯一数据源 = 会话日志：会话日志中 assistant/message 事件的 usage 字段（模型归属取自同事件 message.source 的 provider / model），经 ctx.sessionQuery 读取。sessionQuery 是 live-preferred 的——内存中的活跃会话和落盘日志都能读到，因此进行中的调用也会被统计，无需 llm/stream 实时钩子（旧版本同时用瀑布流实时捕获 + 日志回填，两者重叠导致同一调用被重复计数、数字虚高，v3 已移除实时路径并改为幂等全量重建）。
• 会话数：sessionQuery.listSessions() 的会话头部（cwd / createdAt / delegationDepth）；只有顶层会话（delegationDepth === 0）计入对话。

开发

node --check src/index.js      # Host 语法检查
node --check client/bundle.js  # Client bundle 语法检查

Client bundle 为手工编写以匹配 client-modules bundle 协议，无需构建步骤。

许可

[MIT](./LICENSE)