dsh-token-stats - 本地 Token 统计与成本分析插件

前言¶

DeepSeek Harness（DSH）采用插件化架构。开发者在调试或长期使用过程中，常需要追踪跨会话的 Token 消耗情况与费用成本。本插件在 DSH 的设置页新增「Token 统计」分区，并提供常驻悬浮小窗。它不依赖外部服务，完全通过读取本地会话日志聚合数据，实现零模型消耗的用量监控。

核心功能¶

常驻悬浮小窗¶

界面右下角默认停靠一个悬浮小窗，用于随时查看今日用量。

1. 四种形态

   • 吸附态：贴边细条，仅显示运行状态点与竖排今日数字。
   • 折叠态：小横条，显示名称、齿轮、状态点与今日数字。
   • 悬浮态：完整卡片，包含折叠态内容、热力图与图例。
   • 完整历史面板：独立浮层，展示全年热力图与汇总指标。

2. 交互方式

   • 悬停：吸附态下悬停可预览，折叠/悬浮态下悬停方块可查看当日输入/输出/缓存明细。
   • 双击：吸附态展开为悬浮态；悬浮态双击退回折叠态。
   • 拖动与缩放：拖动卡片任意位置可移动，拖右下角把手可调整大小。
   • 全年历史：鼠标停在标题栏约 160ms 可展开完整历史面板。
   • 点击方块：选中日期后，主数字切换为当日值，标签更新，并出现「回今天」按钮。

3. 运行状态

   • 有会话运行时，卡片外框呈现蓝色呼吸效果；系统开启「减少动态效果」时降级为常亮蓝框。
   • 小窗会自动停靠逻辑：窗口未最大化时自动最小化为吸附态，最大化时恢复为完整卡片。

设置页分区¶

设置页中的「Token 统计」分区提供完整的用量分析。

1. 顶部指标卡

   • 连续天数：当前连续使用天数 / 最长连续天数。
   • 累计 Token：随页签周期取值（每日/每周/每月/累计）。
   • 峰值 Token、最长单轮耗时：随页签和区块联动。

2. Token 活动热力图

   • 支持每日/每周/每月/累计四个时间页签。
   • 未用时段显示空心方块，有用量时段按实际用量四分位自适应填色。
   • 悬停方块可查看该时段明细气泡。

3. 模型用量分布

   • 展示模型行与环形饼图。
   • 显示缓存命中率（口径与 OpenAI 一致）。
   • 悬停模型行可查看输入/输出/缓存明细。

4. 性能时序

   • 展示用时、工具调用次数与耗时、首字时间（TTFT）、输出速度。

费用估算¶

点击「费用单价配置」可设置模型单价。

1. 基本单价

   • 每个模型可配置输入、输出、缓存读、缓存写四项单价（单位：货币/每百万 token）。
   • 支持指定币种，各币种分别合计。

2. 时段单价（峰谷价）

   • 可添加多个价格档，每个档包含四项单价与绑定的时间段。
   • 支持跨零点时间段（如 22:00～06:00）。
   • 支持按星期指定生效范围。

3. 历史价

   • 记录历代价格，按生效起始日计算某日费用。

4. 共享定价

   • 同一定价条目可套用多个模型 key。

套餐配额与预算告警¶

1. 套餐配额

   • 支持设置适用范围（全部模型/Provider前缀/指定模型）与计量单位（调用次数/Token量/费用）。
   • 按模型细分额度，汇总行显示总使用率。

2. 预算告警

   • 支持设置日预算（费用或 Token 双口径）。
   • 超标当天热力图方块带红圈，顶部显示告警条。

会话下钻¶

点击热力图方块后，展示该时间区块消耗最高的会话（Top 10）。

1. 主 / 子代理视图
   • 综合：只列主会话，子代理折叠。
   • 全部：主/子平铺混合。
   • 主对话：仅列主会话。
   • 子对话：仅列子代理会话。
2. 会话明细
   • 显示会话名（工作区/UUID 或标题）。
   • 悬停显示完整目录名与输入/输出/缓存明细。
   • 提供一键复制会话名称与 ID 按钮。

导出¶

1. 导出 CSV：日序列逐日一行，带 UTF-8 BOM。
2. 导出 JSON：包含 totals, days, models，支持双币种费用。

安装与前置条件¶

1. 环境要求

   • DSH 版本需 >=0.1.7-alpha.1
   • Node.js 版本需 >=22.15

2. 数据依赖

   • 插件依赖本地会话日志：$DSH_HOME/sessions/**/session.l.zstd（旧格式）与 session.v3.jsonl.zstd（新格式）。
   • 配置文件位于：$DSH_HOME/token-stats.cfg.json。

3. 安装方式

   • 将插件代码放置到 DSH 的插件目录中（具体路径取决于 DSH 的配置，通常为 ~/.dsh/plugins/ 或类似结构）。

典型用法¶

1. 查看今日用量：鼠标悬停在右下角的悬浮小窗上，查看今日数字。
2. 切换日期：双击悬浮小窗展开，点击热力图中的方块查看特定日期的用量。
3. 配置单价：点击悬浮小窗标题栏的齿轮图标，或进入设置页的「Token 统计」分区，配置模型的输入、输出及缓存单价。
4. 查看模型分布：在设置页查看各模型的用量占比及缓存命中率。
5. 导出数据：在设置页点击「导出 CSV」或「导出 JSON」按钮，保存统计数据。

注意事项¶

1. 零模型消耗：插件在运行时不会注册任何工具或发起 LLM 调用，所有数据均为读取本地日志。
2. 实时性：数据更新为秒级准实时，受日志落盘延迟影响，有数秒延迟。
3. 首次解析：首次安装或无缓存时打开分区，需全量解析历史日志，耗时约半分钟。
4. 配置文件：费用配置（定价、套餐、颜色）最终写入 $DSH_HOME/token-stats.cfg.json，直接编辑该文件并刷新页面即可生效。