dsh-plugin-usage

DeepSeek Harness 的 Token 用量统计插件（UI 参考 CC Switch 的「用量统计」功能）。

A token usage statistics plugin for DeepSeek Harness, inspired by CC Switch's usage stats.

GitHub: bennett-dsh/dsh-plugin-usage · npm: dsh-plugin-usage

• 按天 / 自定义时间范围查看 Token 用量
• 按模型筛选，查看调用次数、输入/输出 Token、缓存命中、费用
• 可配置的每百万 Token 价格表（内置 DeepSeek 常见模型默认价，未配置的模型标记为「未定价」）
• 深/浅色主题自适应（使用 DSH 主题变量），无第三方图表库（手写堆叠柱状图）

Features: daily / custom-range views · model filtering · call counts, in/out tokens, cache hits & cost · configurable per-million-token pricing (built-in defaults for common DeepSeek models; unpriced models are flagged) · dark/light theme via DSH tokens · zero chart dependencies (hand-written stacked bars).

功能特性 / Features

• 📊 用量总览 — 总 Token、输入/输出 Token、调用次数、成本汇总卡片
• 📅 时间范围 — 今日 / 近 7 天 / 近 30 天 / 自定义范围
• 🔍 模型筛选 — 多选模型，按模型查看明细与占比
• 📈 每日趋势 — 按天堆叠柱状图（输入=蓝、输出=绿），hover 查看明细
• 💰 定价配置 — 为模型设置每百万 Token 价格（输入 / 输出 / 缓存命中 / 缓存创建），保存后立即生效
• 🌗 主题自适应 — 跟随 DSH 深/浅色主题，无第三方图表库

效果图

安装与构建 / Install & Build

npm install        # 首次（devDependencies：typescript）
npm run build      # tsc 输出到 lib/，并生成 client 模块入口

通过官方命令安装（推荐）/ Install via the Official Command

插件已发布为 npm 包，使用 DSH 官方的插件管理命令安装：

dsh plugin --profile web add dsh-plugin-usage
dsh web            # 重启后生效

安装后 dsh 会检测到包的 dsh.bundle 声明，自动把 dsh-plugin-usage 加入 profile 的 dsh.profile.bundles 层栈，无需手动编辑任何配置文件。卸载 / 更新：

dsh plugin --profile web remove dsh-plugin-usage   # 卸载
dsh plugin --profile web update dsh-plugin-usage   # 更新

若 pnpm 因「发布时间过新」拒绝安装（minimumReleaseAge 校验），把 dsh-plugin-usage@<version> 加入 profile 的 pnpm-workspace.yaml 的 minimumReleaseAgeExclude 列表后重试（官方对新发布包同样采用此做法）。

从源码加载 / Load from Source

正式加载使用 patch 方式：把以下条目加入 ~/.dsh/profiles/web/cordis.patch.yml（或使用 --patch 参数），路径替换为你本地的仓库路径：

- insert:
  - id: usage-host
    name: '/path/to/dsh-plugin-usage/lib/host/index.js'
  - id: usage-client
    name: '/path/to/dsh-plugin-usage/lib/client/index.js'

然后启动：

dsh web --patch /path/to/dsh-plugin-usage/cordis.yml

开发期也可以在会话中通过动态插件（cordis_define）加载：Client UI 由 Host 的 usage/client-source RPC 从 src/client/index.js 实时读取并在浏览器中评估（UI 代码只有一份，改完刷新即生效）。

使用说明 / Usage

1. 打开设置（左下角）→ 左侧导航「用量统计」。
2. 顶部筛选：日期预设（今日 / 近 7 天 / 近 30 天 / 自定义）、模型多选。
3. 汇总卡：总 Token、输入 Token、输出 Token、调用次数、成本（未定价调用会在卡片下提示）。
4. 每日用量趋势：按天堆叠柱状图（输入=蓝、输出=绿），hover 查看明细。
5. 按模型明细表：请求数 / 输入 / 输出 / 总 Token / 成本 / 占比。
6. 「定价配置」区块：为模型设置每百万 Token 价格，保存后立即生效。

数据来源与口径 / Data Source

插件不自己记录原始日志，而是折叠 DSH 已持久化的会话日志：

• DSH 的 agent loop 会把每次模型调用的用量以 assistant/message 会话事件（携带 usage：输入/输出/缓存命中/缓存创建 Token 与 message.source.{provider,model}）写入会话日志（~/.dsh/sessions/）。
• 插件启动时回填（backfill）全部历史会话，之后每 2s 增量扫描活跃会话（内存），每 30s 增量扫描持久化会话（按 seq 水位）。
• 覆盖范围：所有 agent loop 调用（含子代理）。compaction / session-title 等辅助调用不写入会话日志，不在统计范围内。
• 去重：按会话内 (turn, step) 去重——同一 (turn, step) 的后续用量事件替换先前样本，而不是重复累计。
• 费用 = (输入×输入价 + 输出×输出价 + 缓存命中×缓存命中价 + 缓存创建×缓存创建价) / 1e6，价格表可改。
• 价格表持久化：官方 DSH settings 服务可用时，价格表经 usage.prices settings 命名空间持久化（重启后保留，并出现在官方 Plugins 配置页）；否则回退到进程内存（仅本次运行有效）。

动态插件形态下数据保存在进程内存中，重启后自动从会话日志重新回填，无需落盘文件。

源码结构 / Project Structure

src/
├── host/
│   ├── index.js         Host 入口：接线 fold / scan / query / settings / aggregate / rpc / client-source，驱动定时扫描
│   ├── settings.js      价格表 + 费用计算（内置 DeepSeek 常见模型默认价，可选 settings 命名空间持久化）
│   ├── state.js         运行时状态：records / watermarks / backfill / dedup / index
│   ├── aggregate.js     增量聚合索引：add / remove / recordsInRange，供查询高效取数
│   ├── fold.js          会话事件 → usage 记录（含会话内 (turn, step) 去重替换）
│   ├── scan.js          启动回填 + 活跃/持久化会话的增量扫描（每 tick / 每 30s，按 seq 水位）
│   ├── query.js         聚合与查询：按天/按模型汇总、未定价检测、heatmap
│   ├── rpc.js           RPC 注册：usage/query、usage/prices、usage/client-source（动态 harness 与静态 connection 桥）
│   ├── client-source.js 读取 src/client/index.js 实时提供给浏览器（动态插件形态）
│   └── time.js          时间分桶：day/hour/minute 粒度与 step 网格（纯函数）
├── client/index.js   Client half：设置页「用量统计」仪表盘（筛选/汇总卡/柱状图/模型表/定价配置），样式内联
└── client/styles.js  UI 样式源（构建脚本已合并进 index.js，可删除）
scripts/
└── build-client.js   构建时生成 lib/client/index.js 模块入口（同一份 UI 代码的正式加载形态）
cordis.patch.yml      bundle patch：`dsh plugin add` 安装后由 `dsh.bundle` 声明自动激活

开发与测试 / Development & Testing

npm install        # 首次安装依赖（devDependencies：typescript）
npm run build      # tsc 输出到 lib/，再由 scripts/build-client.js 生成 client 模块入口
npm test           # node --test tests/

src/host/ 下的宿主逻辑（fold / scan / query / aggregate / time / settings 等）均为可直接 import 的 ESM 模块，单元测试直接运行，无需启动 DSH harness。

说明 / Notes

• 插件名 usage；动态插件运行在会话级，卸载后统计重新回填即可恢复。
• 价格表持久化策略见「数据来源与口径」（官方 settings 可用时走 usage.prices 命名空间，否则进程内存回退）。

开源协议 / License

MIT