在使用 DeepSeek Harness（DSH）进行智能体开发时，监控 Token 消耗与缓存效率是控制成本和优化性能的关键环节。手动解析 session.jsonl.zstd 文件以获取统计信息既耗时又容易出错。
下面介绍的 dsh-token-usage-xc 是一个由 xchannel1987 维护的插件，旨在提供实时、可视化的 Token 用量统计与趋势分析。它支持按模型分桶展示、缓存命中率计算，并提供持久化存储与 RPC 接口。
核心功能¶
实时用量统计¶
插件会在设置页新增「今日 Token 用量」分区，实时展示按模型分桶的详细数据，包括：
* 输入 Token（uncachedInput）
* 输出 Token（output）
* 缓存读 Token（cacheRead）
* 缓存写 Token（cacheWrite）
* 请求次数
缓存命中率分析¶
插件自动计算缓存命中率，公式为：
cacheRead / (uncachedInput + cacheRead) × 100%
这有助于评估缓存策略的有效性。
7 日趋势图表¶
提供堆叠柱状图展示最近 7 日的 Token 消耗趋势。支持日期切换以查看历史数据，以及按模型筛选查看特定模型的消耗情况。
会话顶栏徽标（可选）¶
在设置中启用「会话顶栏显示今日总 Token」后，会话页顶栏会显示今日总 Token 徽标。
* 点击徽标可快速查看明细。
* 支持 K/M/B 等简化显示，悬停查看精确值。
* 针对移动端（≤1023px）进行了排布优化，徽标位于倒数第二位，与后台任务图标互不遮挡。
数据持久化¶
数据按天落盘到本地文件，确保重启不丢失。
* 存储路径：~/.dsh/storages/dsh-token-usage-xc/<YYYY-MM-DD>.json
* 策略：启动时若早于插件加载会自动回填今日用量；旧数据会在 7 天后自动清理。
RPC 接口¶
插件提供 RPC 接口供其他插件调用，便于集成到更复杂的工作流中。
安装与启用¶
使用官方安装命令添加插件：
dsh plugin --profile web add dsh-token-usage-xc
安装完成后重启 DSH，即可在设置页看到新增的「今日 Token 用量」分区。
使用方法¶
-
查看今日用量
打开 DSH 设置，找到「今日 Token 用量」分区，查看按模型分桶的明细数据。 -
查看 7 日趋势
在用量面板点击「趋势」标签，查看堆叠柱状图，点击日期可查看详情，支持模型筛选。 -
启用顶栏徽标
在设置中打开「会话顶栏显示今日总 Token」，启用徽标。点击徽标可快速查看明细。
数据来源与统计口径¶
- 数据来源：监听
session/event事件的usage字段，按seq去重，确保每个 assistant/message 恰好一条。 - 总 Token 计算：
uncachedInput + cacheRead + cacheWrite + output。 - 归档规则：根据
event.time归档到YYYY-MM-DD。 - 兼容性：兼容 DSH 0.1.7-rc.1 或更高版本。
注意事项¶
- 插件仅计最终 usage，数据来源为 session/event 事件。
- 插件以当前 DSH 进程权限运行，安装前建议检查源码与许可证（MIT）。
总结¶
dsh-token-usage-xc 通过本地持久化和可视化图表，解决了 DSH 中 Token 统计的痛点。无论是日常成本监控，还是分析缓存优化效果，该插件都能提供结构化的数据支持。
