前言¶
DeepSeek Harness（DSH）的会话日志记录了每一次调用，但原始日志只提供原始数据。开发者在调试、成本核算和用量分析时，需要把分散在多个会话中的 token 消耗、调用次数和费用聚合起来，按项目、provider 和模型拆分。手算或脚本统计容易遗漏，且无法实时更新。
插件定位¶
dsh-usage-dashboard 是一个运行在 DSH 客户端的用量与成本仪表板插件。它从本地会话日志中提取 token 和调用信息，按项目和 provider 分解，结合本地价格配置估算费用，并显示 DeepSeek 账户余额。所有计算都在本地完成，不向远程上传任何对话内容。
插件由维护者 Zhangw1998 维护，归类为客户端插件。
核心功能¶
1. KPI 与时间范围¶
在 Settings → Usage & Cost 页面，顶部展示三个主要指标和一个组成条：估算成本、总 token、输入/输出/缓存读的分布。时间范围支持今天、滚动 24 小时、7 天、30 天、90 天、全部时间，以及自定义范围。其中 24 小时是滚动窗口，与“今天”不同。
2. 过滤与钻取¶
通过三个可组合过滤器查看：项目、provider、模型。点击 provider 行或项目行可以钻取，查看该 provider 或项目下的详细分解。
3. 趋势图¶
趋势图可切换显示 token 或成本，并支持开关缓存读。缓存读通常占所有 token 的 95% 以上，关闭它才能看清输入/输出的形状。
4. Provider 分解¶
按 provider 展示输入/输出/缓存/调用次数，并用组成条分段显示。每行的数据与 KPI 和趋势图使用相同的过滤器，确保汇总与明细一致。
5. 项目表¶
展开项目行可查看该项目使用了哪些 provider，以及每个 provider 的 token 和费用。
6. 余额显示¶
DeepSeek 余额分为 API-key 钱包和登录账户钱包，分别显示充值额和赠送额。余额数据不用于推断累计花费。
7. 悬浮卡片与刷新策略¶
在聊天页面右下角有一个悬浮卡片，默认折叠为“Today ¥3.42 · 1.2M”的胶囊，展开可查看今日分解和余额。卡片可拖动，位置会被记住。刷新策略是：只在打开设置页、展开卡片或手动点击刷新时刷新，不使用后台轮询。由于完整扫描需要约 12 秒，闲置页面不会持续消耗 CPU。数据超过 10 分钟会变暗，提示数据已过期。
安装与启用¶
插件要求 DSH 构建版本包含 dsh plugin 子命令（已测试 0.2.1-rc.2）。
安装命令：
# replace "desktop" with your profile name (desktop / web)
dsh plugin --profile desktop add github:Zhangw1998/dsh-usage-dashboard
安装后重新加载 DSH，打开 Settings → Usage & Cost 即可看到仪表板。
卸载命令：
dsh plugin --profile desktop remove dsh-usage-dashboard
价格配置¶
默认价格规则在 pricing.js 中。如需覆盖，编辑：
~/.dsh/storages/usage-dashboard-pricing.json
该文件可配置每个 provider 的峰/谷时段费率、货币和计费模式（token / plan / subscription / unknown）。编辑前会进行校验，无效配置会被拒绝。
数据来源与隐私¶
插件在本地完成所有处理：
-
读取本地会话日志：扫描
~/.dsh/sessions/**/session.v4.jsonl.zstd（或$DSH_HOME/sessions）提取每次调用的 token 使用情况。对话内容不会被上传或复制到插件输出中。 -
余额请求：仅在配置了
DEEPSEEK_API_KEY时，向https://api.deepseek.com/user/balance发送一次请求。这是插件唯一访问的外部主机，且拒绝重定向。 -
写入文件：在
~/.dsh/storages/下写入扫描缓存和价格配置。不写入会话数据。
插件不包含遥测或第三方上报。
典型用法¶
打开 Settings → Usage & Cost，默认显示最近 7 天的用量。点击 provider 或项目行，查看细分数据。在趋势图中关闭缓存读，观察输入/输出比例。在价格配置中调整峰谷费率，刷新后重新计算估算成本。
适用场景与注意¶
适合需要按项目和 provider 统计 token 消耗、估算成本并查看 DeepSeek 余额的用户。插件以当前 DSH 进程的权限运行，安装前应检查源码与许可证。
结尾¶
该插件将分散的会话日志聚合为结构化用量面板，帮助开发者更好地掌控成本与使用情况。更多细节见：
- 插件目录页：https://www.skillhub.cn/plugins/Zhangw1998/dsh-usage-dashboard
- GitHub 仓库：https://github.com/Zhangw1998/dsh-usage-dashboard
