dsh-token-stats: DeepSeek Harness Token 用量统计插件

前言¶

DeepSeek Harness（DSH）采用插件化架构，旨在为智能体开发提供灵活的运行环境。在开发或调试过程中，精确统计 Token 消耗、监控缓存命中情况以及分析不同时间段的调用趋势是必要的。虽然 DSH 提供了基础的计量能力，但在需要聚合历史数据、查看多维度折线图或关注缓存效率时，往往缺乏现成的可视化方案。

dsh-token-stats 插件旨在解决这一问题。它通过读取 DSH 的 Session 日志，聚合全部会话的 Token 使用情况，并在本地生成可视化的统计报表。

插件信息¶

名称：dsh-token-stats
维护者：IZRINO
类别：联网工具
许可证：MIT

核心功能¶

全会话统计：统计全部会话的 Token 消耗与调用次数，不按 workspace 过滤。
多维聚合：支持按小时、天、周、月四种粒度聚合数据。
可视化图表：生成 SVG 折线图，同时展示输入、缓存读、缓存写、输出和总 Token。
缓存分析：支持缓存命中率计算。
本地化：所有数据存储在本地，不涉及云端传输。
历史回溯：支持对历史会话进行自动回填。

安装与启用¶

需要安装一个可用的 dsh web profile，并使用 dsh plugin 命令。

将插件代码拉取到本地目录，或使用 Git 地址。
执行安装命令：

dsh plugin --profile web add /home/izrino/code/dsh-token-stats

重启 dsh web，打开设置面板，找到「Token 统计」页面。

配置¶

在 DSH 的 profile 配置文件 cordis.patch.yml 中，找到 token-stats 插件行，添加或修改 config 字段。注意不要重复添加插件行。

- insert:
    - id: token-stats
      name: dsh-token-stats
      config:
        timezone: Asia/Shanghai
        weekStart: monday
        retainDays: 365
        dataDir: ''
      inject:
        - webServer
        - sessions
        - sessionPersistence

配置项	默认值	说明
`dataDir`	`''`	缓存目录。空值使用 `$DSH_HOME/storages/dsh-token-stats`；支持绝对路径或相对路径。
`timezone`	`system`	天/周/月统计的时区。`system` 为宿主机时区，也可指定 IANA 名称（如 `UTC`）。
`weekStart`	`monday`	周统计的起始日。
`retainDays`	`365`	小时桶数据保留的天数，范围 7-3650。

配置错误会导致插件加载失败。

架构与指标¶

插件不监听实时流，而是直接读取持久化的 Session 日志作为真源。对于流式输出中的 Usage chunk，插件会将其与最终 assistant/message 的 Usage 进行替换，确保数据口径与官方 dsh-token-meter 一致。

指标定义¶

inputTokens：未缓存的输入 Token。
outputTokens：模型输出 Token。
cacheReadTokens / cacheWriteTokens：缓存读 / 写 Token。
totalTokens：上述四项之和，不包含 reasoning Token。
calls：最终采用的 Usage 样本数。
cacheHitRate：缓存命中率。计算公式为 cacheReadTokens / (inputTokens + cacheReadTokens + cacheWriteTokens)。无 prompt token 时返回 null。

Host API¶

插件提供了一组 HTTP 接口用于查询数据。所有接口仅接受来自 127.0.0.1 的 GET 请求。

接口列表¶

/api/token-stats/series：获取折线图数据。
/api/token-stats/summary：获取范围汇总数据。
/api/token-stats/breakdown：按模型或供应商分组统计。
/api/token-stats/health：查询插件健康状态。

API 参数与示例¶

以 series 接口为例：

curl 'http://127.0.0.1:3080/api/token-stats/series?granularity=day&metric=totalTokens'

参数说明：
* granularity：hour | day | week | month。
* metric：统计指标。
* fromMs / toMs：时间范围（毫秒）。
* timezone：可选时区。

注意事项¶

数据落盘时机：缓存数据仅在 API 请求、实时事件防抖以及 session/flush 操作时写入磁盘，非实时刷新。
DSH 版本状态：DSH 目前处于 pre-release 阶段，插件契约随版本变化，本插件基于 0.1.0-rc.x 实现。
显示限制：设置页仅展示汇总数据，不保存原始调用明细。
时区处理：天/周/月统计按配置时区归桶。DST 地区的小时桶可能跨越两个本地日期，按 UTC 小时的本地起始归属。
安全性：API 仅允许 Loopback 访问。

结语¶

dsh-token-stats 提供了一套轻量级、本地化的 Token 统计方案，适合需要深入分析调用成本和缓存效率的开发者。通过 SVG 图表和聚合 API，可以快速定位异常调用或优化缓存策略。

GitHub：https://github.com/IZRINO/dsh-token-stats
目录页：https://www.skillhub.cn/plugins/IZRINO/dsh-token-stats