dsh-token-stats

DeepSeek Harness Token 用量统计插件

_中文

为 DeepSeek Harness（DSH） Web UI 打造的 Token 消耗统计插件：在设置面板里一目了然每个模型每天、每个统计区间的 token 用量。

功能

套餐余额功能参考自 dsh-musage（MIT），API Key 直接复用 DSH 模型设置里已配置的凭据（credentials 服务），无需重复配置。

安装

标准安装（推荐）

本插件是标准 DSH bundle：package.json 声明 dsh.bundle.patch，包内自带 cordis.patch.yml，用官方 dsh plugin 命令安装：

# 本地开发：pnpm 软链到本仓库，改代码即生效（无需重新复制）
dsh plugin --profile web add /path/to/dsh-token-stats

# 正式发布：从 GitHub Release tarball 安装
dsh plugin --profile web add https://github.com/MoonlitDropOfBlood/dsh-token-stats/releases/download/v1.4.0/duke-dsh-plugins-dsh-token-stats-1.4.0.tgz

重启 DSH 后，打开 DSH Web UI 的设置（侧栏底部），左侧导航会出现 Token 统计 页。

dsh plugin add 把插件装成 profile 的 npm 依赖并追加到 dsh.profile.bundles，启动时 DSH 自动应用包内的 cordis.patch.yml 挂载插件。卸载：dsh plugin --profile web remove dsh-token-stats。

使用

1. 打开 设置 → Token 统计。
2. 在 近 7 天 / 近 30 天 两个 Tab 间切换：
   • 柱状图展示区间内每天、每个模型的消耗（堆叠）。
   • 饼图展示区间内每个模型的总消耗占比。
   • 顶部卡片给出区间总 Tokens / 输入 / 输出。
3. 下方 每日活跃 热力图展示更长时间范围：格子越多 = 容器越宽，最多覆盖近一年。
4. 会话输入框工具行（model 选择器左侧）内联显示当前 provider 的套餐余额：
   • DeepSeek / OpenRouter 显示余额（如 ¥43.97 / $12.50）；
   • MiniMax / Kimi / 智谱 显示 5h X% | 7d Y%（5 小时 / 7 天窗口已用百分比，悬停查看重置时间）；
   • 切换模型时自动切换 provider；每 60s 自动刷新，点击读数立即强制刷新；
   • 未配置对应 API Key 或拉取失败时显示 ⚠（悬停查看原因）；当前 provider 不在支持列表时不占位。

工作原理

DSH 会话日志（唯一权威数据源）
  ├─ LIVE   : session/event  → assistant/message(usage)   [插件启动后实时累计]
  ├─ HISTORY: sessionQuery.readSession() → 回填历史        [仅扫描从未回填过的会话]
  ├─ DEDUP  : 按 session+seq 水位线去重，绝不重复计数
  └─ PERSIST: 聚合 + 水位线落盘 stats.json（防抖写盘 + 停止时 flush）
        │
        ▼
TokenStatsService.getStats()   ← ctx.remote.tokenStats.getStats()（Client 调用）
TokenStatsService.getQuota()   ← ctx.remote.tokenStats.getQuota(provider, force)
        │
        ├─ getStats → 设置面板「Token 统计」页（柱状图 / 饼图 / 热力图）
        └─ getQuota → composer 工具行内联读数（conversation.input.right，
                      紧贴 model select 左侧；跟随当前会话模型自动切 provider）

• 数据按本地日历天 × 模型（provider::model）聚合；total = input + output + cacheRead + cacheWrite。
• 历史回填只统计插件启动前发生的调用，实时监听只统计启动后的，两者通过每个会话的事件序号水位线合并，不会重复。
• 模型/模型来自 assistant/message 的 message.source（kind = 'model'），无需自行解析请求头。
• 套餐余额：Host 半经 credentials 服务解析用户在模型设置里已配置的 API Key（引用命名遵循 <ROUTE>_API_KEY 约定），GET provider 官方端点（宿主全局 fetch 优先，无 fetch 时回退 subprocess curl）；30s 缓存 + 失败指数退避（5s→30min），不落盘。

目录结构

dsh-token-stats/
├── index.js            # Host 半：TokenStatsService（Remote 服务，采集 + 回填）
├── client.js           # Client 半：设置页「Token 统计」UI bundle
├── typert.host.js      # Typert Host manifest（tokenStats/getStats 描述）
├── cordis.patch.yml    # dsh bundle patch（挂载行）
├── .github/workflows/  # GitHub Actions 发布
├── AGENTS.md           # 面向 AI agent 的开发指南（含踩坑）
└── LICENSE             # MIT

开发

npm run check           # node --check index.js client.js typert.host.js
dsh plugin --profile web add /path/to/dsh-token-stats   # 安装/重装到本机 DSH profile

详见 AGENTS.md——记录了 DSH 正式插件（Host/Client/Typert 三件套）的完整机制和踩坑。

License

本项目遵循 MIT License。

本项目是基于 DeepSeek Harness 构建的社区插件，并非 DeepSeek 官方产品。