前言¶
在 DeepSeek Harness（DSH）里跑智能体，模型调用会分散在多个会话、多个 provider 路由上。若只靠各家控制台或账单页，很难和「本机实际发生了多少次调用、各模型各用了多少 token」对齐；本地也没有统一视图把用量、预估费用和账户余额放在同一处。
下面介绍社区插件 token-usage-statistic（维护者 zhiwuli0228）。它作为 客户端 类 DSH 插件，从 DSH 会话事件采样 token，写入可重放账本，并在 DSH Desktop 与 DSH Web 的侧边栏面板展示用量、账户与导出。Desktop 与 Web 共用同一份 Web 客户端包和同一套 Host 逻辑，只有一份实现。
插件目录页：skillhub.cn/plugins/zhiwuli0228/token-usage-statistic。源码与完整说明见 GitHub 仓库（当前 npm 包版本 1.0.2，MIT 许可证）。社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系；该插件尚未收录官方插件库，在 Discover / 市场搜不到时按包名安装即可。
这是什么¶
token-usage-statistic 是 DeepSeek Harness 插件：统计本机所有模型调用的 token 用量与按事件时间估算的费用，支持历史回填、账户余额/订阅额度、日/月预算与无凭据导出，并在侧边栏面板中呈现。
Host 侧监听 assistant/message、assistant/chunk、compaction/summary 等会话事件；Client 侧通过 sidebar.panellist 与 main (key=token-usage) 注入「模型用量统计」面板。账本默认落在 %DSH_HOME%\token-usage-statistic\usage.jsonl，费用不落盘，重放时按价格规则重算。
核心功能¶
用量采样与历史回填¶
- 三源采样：
assistant/message、assistant/chunk、compaction/summary；同一turn:step的后续样本会替换先前样本。 - 启动后增量扫描
sessionPersistence；账本中每个会话的最高 seq 作为游标，fork 从inheritedEventCount起读。
费用估算¶
每个样本按自己的事件时间匹配历史价格规则（DeepSeek 峰谷时段、上海时区）；未定价时 fail-closed。内置 DeepSeek 官方 USD 价（每 1M tokens），覆盖 deepseek-v4-flash / deepseek-v4-pro 的历史分段；只有 pricing.providers 内的路由会被计价，第三方网关默认未定价。
账户与预算¶
自动发现三类来源：DSH Desktop 账户（deepseekAccount）、官方 DeepSeek API Key（llm-deepseek）、以及 llm-pi-ai provider 的公开余额接口。accounts.monitors 可配置私有监控端点。凭据仅在 Host 内通过 ctx.credentials 解析，不落盘到导出内容。
日/月预算通过 budgets.daily / budgets.monthly 与 budgets.currency 配置；达到 80% 为预警，100% 为超限；费用不完整时不拿部分和比较。
面板与导出¶
侧栏三个标签：用量 / 账户 / 导出。时间范围支持今天 / 7 天 / 30 天 / 全部；图表指标可在 Tokens、调用次数、预估费用之间切换（1.0.2 起切换控件在图表标题旁，并显示「当前指标 · 合计」摘要）。
只读 HTTP API 仅接受回环 GET/HEAD，例如：
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /token-usage-statistic/api/summary |
用量、费用、预算、回填状态 |
| GET | /token-usage-statistic/api/export/daily.csv |
按日 provider/model CSV |
| GET | /token-usage-statistic/api/export.json |
版本化 JSON，无凭据 |
CSV 导出带 UTF-8 BOM 与公式注入防护，不含提示词、回复或密钥。
安装与启用¶
Desktop 与 Web 使用不同 profile（desktop / web），两端都要用时各执行一次。Desktop 安装前先完全退出 App（含托盘图标）。本地安装脚本需要 Node.js ≥ 20；只走图形界面安装则不需要。
DSH Desktop（不需要 PATH 上有 dsh）：
npm run plugin:install -- desktop # 链接当前仓库
npm run plugin:install -- desktop --npm # 安装 npm 上已发布的包
DSH Web：
dsh plugin --profile web add token-usage-statistic
dsh web
Web 走 npm 安装的 dsh，需要 PATH 上有 pnpm；Desktop 自带的 dsh 已内置 pnpm。
图形界面（Desktop）：插件 / Plugins → 输入 token-usage-statistic → 安装 → 重启 Desktop。
装完后侧栏应出现「模型用量统计」。若入口未出现，可查看 %DSH_HOME%\token-usage-statistic\activation.json 中的路由注册结果。
兼容性概览：
| 运行环境 | 支持 | 面板 |
|---|---|---|
| DSH Desktop | ✅ | 侧边栏「模型用量统计」 |
DSH Web (dsh web) |
✅ | 同一侧边栏面板 |
| DSH CLI / headless | ⚠️ 仅采集 | 无侧边栏；账本仍写入 |
典型用法¶
- 打开侧栏 →「模型用量统计」。
- 在 用量 页选择时间范围与图表指标；点击每日柱子可查看当天会话、模型与工作区名称。
- 在 账户 页查看余额或订阅额度，必要时点「刷新账户」立即触发 Host 刷新。
- 在 导出 页或通过回环 API 拉取 CSV/JSON，用于离线分析或备份（仍不含凭据）。
最小配置示例（刷新间隔与日/月预算）：
- override:
- id: token-usage-statistic
config:
refreshMs: 15000
budgets:
currency: USD
daily: 5
monthly: 50
完整字段（dataFile、sessionLimit、backfill、modelAliases、pricing、accounts.monitors 等）见仓库 README 中的配置参考。
适用场景与注意¶
适合谁：长期在 DSH Desktop 或 Web 上开发、调试智能体，需要本机维度的 token 汇总、DeepSeek 相关路由的预估费用，以及把用量与账户/预算放在同一侧边栏的开发者。
运行权限：插件以当前 DSH 进程权限运行，会读取会话持久化、写入 %DSH_HOME% 下账本与账户快照，并在 Host 内解析凭据以查询余额。安装前应自行审阅 源码 与 MIT 许可证，确认符合你的安全与合规要求。
局限：CLI / headless 场景仅采集、无面板；第三方网关默认未纳入内置计价；账户查询有 HTTPS、超时与响应大小边界，无公开接口的 provider 不会猜测性请求。
结尾¶
token-usage-statistic 把 DSH 会话事件变成可重放的用量账本，并在 Desktop / Web 侧边栏统一展示 token、预估费用、账户与导出——适合需要「本机真相来源」而非只看云端账单的使用方式。
- 目录页：https://www.skillhub.cn/plugins/zhiwuli0228/token-usage-statistic
- GitHub：https://github.com/zhiwuli0228/token-usage-statistic
