dsh-usage-stats：DSH 侧边栏 Token 用量统计与额度监控

前言¶

在 DeepSeek Harness (DSH) 的插件生态中，开发者往往需要实时追踪 Token 的消耗情况，并查看各类服务的余额额度。dsh-usage-stats 插件将用量统计与额度监控挂载于 Web 侧边栏底部，点击即可打开详情面板，按模型、会话、日期三个维度展示数据。

插件介绍¶

这是一个 DSH Web 插件，用于统计 Token 使用量并展示余额。它挂载于侧边栏底部展示今日用量，点击后打开详情面板进行多维度的数据查看。

核心功能¶

侧边栏今日统计
在侧边栏底部展示今日统计，支持宽列与 56px rail 自适应展示。
详情面板
面板按概览、日期、会话、模型、设置五个标签页组织信息。
模型统计重定向
在设置页配置规则，将某个供应商的某个模型的用量算到另一个供应商的某个模型名下，模型页按规则归并展示，账本原始数据保持不变。
额度监控
- OpenCode Go：展示滚动 5 小时、本周、本月三档剩余额度。
- DeepSeek：展示多币种余额。
- Z.ai：展示滚动 5 小时与本周百分比，以及每月 Web 搜索次数。
会话 ID 徽标
在会话标题旁显示 session-id 徽标，悬停可复制。默认开启，可在设置页关闭。

安装与启用¶

使用官方命令安装插件：

dsh plugin --profile web add @xfqz86/dsh-usage-stats

卸载命令：

dsh plugin --profile web remove @xfqz86/dsh-usage-stats

配置与使用¶

设置位置¶

设置位于详情面板的“设置”标签页，配置保存在 DSH 该 profile 的配置文件 ~/.dsh/profiles/<profile>/cordis.patch.yml 中。换浏览器或换设备登录同一台 DSH 时，偏好设置保持一致。

基础配置¶

启用额度监控（如 DeepSeek 余额、OpenCode Go 额度、Z.ai 额度）与侧边栏展示。额度抓取间隔默认为 5 分钟，下限为 3 分钟。

在配置文件中只修改需要调整的字段，例如将 Go 额度抓取间隔改为 10 分钟：

- id: usage-stats
  name: '@xfqz86/dsh-usage-stats'
  config:
    goFetchMinutes: 10

凭据配置¶

需在 DSH 凭据中心配置对应 Key：
* OpenCode Go：OPENCODE_GO_API_KEY
* DeepSeek：DEEPSEEK_API_KEY（兼容 DEEPSEEK_APIKEY、DEEPSEEK_API_TOKEN、DEEPSEEK_TOKEN）
* Z.ai：ZAI_CODING_CN_API_KEY 或 ZAI_API_KEY（前者优先）

会话 ID 徽标¶

默认在会话标题旁显示会话 ID 徽标。若需关闭，可在详情面板的“设置”标签页中关闭。

数据存储与统计口径¶

数据存储¶

数据存储为 SQLite，位于 $DSH_HOME/storages/dsh-usage-stats/ledger.sqlite。首次启动会自动扫描历史会话并导入，后续随事件实时增量更新，重启后可从账本恢复。

统计口径¶

数据源：携带 data.usage 的记录，包括对话调用 assistant/message 和压缩上下文的调用 compaction/summary。
计算方式：
- total = input + output + cacheRead + cacheWrite
- reasoning 单列
维度划分：
- 按模型维度取 provider 与 model（对话调用取 message.source，压缩调用取事件顶层）。
- 按会话维度记录标题、工作目录、创建与最近活跃时间。
- 按本地自然日划分日期。
不含内容：不含会话标题自动生成等辅助调用的用量（仅记录请求，不记录返回的用量）。

生态与链接¶

GitHub 仓库：https://github.com/xfqz86/dsh-usage-stats
社区目录：https://www.skillhub.cn/plugins/xfqz86/dsh-usage-stats
许可证：MIT

注意：该插件以当前 DSH 进程的权限运行，安装前请检查源码与许可证。