xchannel1987/dsh-token-usage-xc

中文 | English

DSH Token 用量统计插件 —— 实时追踪今日与最近 7 日 Token 消耗，按模型分桶展示，提供缓存命中率分析和趋势图表。

DSH 0.1.7 兼容（>=0.1.7-rc.1）：设置命名空间已按 0.1.7 机制适配（宿主导出 Config

• volatile 字段），设置入口位于「设置」页的对应分区。

✨ 核心特性

📊 今日 Token 用量

在设置页新增「今日 Token 用量」分区，实时展示：

• 按模型统计：输入/输出/缓存读/缓存写 Token 数
• 缓存命中率：cacheRead / (uncachedInput + cacheRead) × 100%
• 请求次数：每个模型的 API 调用次数
• 当日总计：所有模型的汇总数据

📈 7 日趋势图

• 堆叠柱状图：按模型分色的 7 日用量趋势
• 日期切换：查看任意历史日期数据
• 模型筛选：可选择显示特定模型

🔔 顶栏徽标（可选）

• 实时显示：会话顶栏显示今日总 Token
• 点击展开：点击徽标查看明细
• 紧凑格式：K/M/B 简化显示，悬停查看精确值
• 移动端排布（≤1023px）：顶栏一行依次为 汉堡 │ PTC 模式 │ 剩余表计 │ 用量徽标 │ 后台任务，徽标位于倒数第二、jobs 最右，与抽屉图标同一水平互不遮挡；≤380px 自动换行并保持视觉顺序
• 移动端紧凑：隐藏「tok」后缀并收紧内边距，保证 390px 宽度下一行完整显示

💾 数据持久化

• 按天落盘：~/.dsh/storages/dsh-token-usage-xc/<YYYY-MM-DD>.json
• 重启不丢：重启后数据自动恢复
• 自动清理：7 天自动清理旧数据
• 启动回填：回填今天早于插件加载的用量

🔧 数据来源

来源	说明
session/event	监听 assistant/message 事件的 usage 字段
模型归属	直接读取事件的 message.source.model
会话水位	按 seq 去重，避免重复计数

为什么不自己解析 session.jsonl.zstd？
该文件是多 zstd 帧拼接，需要像持久化后端那样扫描帧边界逐帧解码。插件统一走 sessionQuery，避免重复实现这套复杂逻辑。

📦 安装

# 使用 DSH CLI
dsh plugin --profile web add dsh-token-usage-xc

# 或使用 npm
npm install dsh-token-usage-xc

安装后重启 DSH，在设置页可看到新增的「今日 Token 用量」分区。

⚙️ 配置

选项	默认值	说明
enabled	true	启用统计
refreshIntervalSec	60	前端刷新间隔（10-3600秒）
backfill	true	启动时回填今日用量
headerBadge	false	会话顶栏显示总 Token 徽标

🎮 使用

查看今日用量

1. 打开 DSH 设置
2. 找到「今日 Token 用量」分区
3. 查看按模型分桶的明细数据

查看 7 日趋势

1. 在用量面板点击「趋势」标签
2. 查看堆叠柱状图
3. 点击日期查看详情

启用顶栏徽标

1. 在设置中打开「会话顶栏显示今日总 Token」
2. 会话页顶栏将显示今日总量
3. 点击徽标可快速查看明细

🔌 数据接口

提供 RPC 接口供其他插件调用：

// rpc.call("/api", "dsh-token-usage-xc/today", {})  → 物理路由 POST /api/dsh-token-usage-xc/today
// （0.2.24 起首选；dsh <0.1.5 或宿主带 profile 补丁时旧通道 rpc.call("/dsh-token-usage-xc","today") 亦在）
{
  available: boolean;
  date: string;           // 'YYYY-MM-DD'
  totalTokens: number;
  requests: number;
  models: {
    model: string;
    modelName: string | null;
    provider: string;
    uncachedInputTokens: number;
    outputTokens: number;
    cacheReadTokens: number;
    cacheWriteTokens: number;
    totalTokens: number;
    requests: number;
  }[];
}

// rpc.call("/api", "dsh-token-usage-xc/last7days", {})
// 返回最近 7 日的汇总数据

📐 统计口径

• 总 Token = uncachedInput + cacheRead + cacheWrite + output
• 缓存命中率 = cacheRead / (uncachedInput + cacheRead) × 100%
• 仅计最终 usage：每个 assistant/message 恰好一条，天然无重复
• 按事件时间归档：根据 event.time 归到 YYYY-MM-DD

📄 许可证

MIT

🔗 链接

• GitHub
• npm
• 问题反馈