前言¶
DeepSeek Harness (DSH) 是一个基于插件化的智能体开发框架。在开发与调试过程中，开发者需要了解当前会话对模型 API 的调用频次与 Token 消耗情况。官方 Web 界面目前未提供直接的用量统计视图，手动查看日志较为繁琐。
dsh-usage-info 插件填补了这一空白，它不依赖外部服务，直接在本地基于 DSH 的会话日志生成统计报表。
功能定位¶
这是一个本地化的用量统计插件，由 shenzhantu 维护。它为 DSH Web 界面在“设置 -> 插件”下方新增了一个“用量信息”导航项，用于展示今日及本月的 API 调用情况。
核心价值在于回答两个问题：
1. 今天 / 这个月一共调用了多少次模型 API？
2. 每个模型（厂商/模型）各请求了多少次、用了多少 Tokens？
核心功能¶
- 本地统计与快照：纯本地 JSON 持久化，无数据库依赖。页面接口直接返回内存快照，打开速度快，无需等待历史扫描。
- 自动重建与增量同步：服务端启动后自动从本机会话日志全量重建历史统计，之后仅进行增量同步，重启不丢失数据。
- 分组与排序：按厂商/模型分组统计请求次数与 Tokens。同一厂商的模型排在一起，厂商内部模型按 A-Z 排序。
- 详细数据维度：支持今日/本月时间视图切换。包含 Tokens 输入（区分缓存命中/未命中）及 Tokens 输出统计。
- 隐私安全：原始数据只读取 DSH 本机会话日志，不修改、不上传任何会话内容。页面接口仅接受 GET，并校验请求来自本机回环地址。
安装与启用¶
安装前请确保已安装 DSH 的 web profile（版本 @deepseek-ai/dsh >= 0.1.0-rc.6）。
使用官方安装命令添加插件：
dsh plugin --profile web add "github:<你的GitHub用户名>/dsh-usage-info"
添加后重启 dsh web，刷新浏览器即可生效。
使用方法¶
- 重启
dsh web。 - 打开 Web 界面，进入 设置。
- 点击左侧导航中 插件 下方的 用量信息。
- 在页面顶部切换 本月 或 今日 视图。
统计口径¶
插件通过解析 DSH 会话事件进行统计：
- 请求次数：
assistant/message：计 1 次compaction/summary：计 1 次session/title-llm-request：计 1 次（该事件 DSH 不持久化 usage，故 Tokens 为 0）
- Tokens 计算：
- Tokens 输入（缓存命中）：来自
cacheReadTokens - Tokens 输入（缓存未命中）：
inputTokens + cacheWriteTokens - Tokens 输出：
outputTokens
- Tokens 输入（缓存命中）：来自
数据与隐私¶
- 存储位置：统计结果缓存于
~/.dsh/storages/dsh-usage-info.json。删除该文件后，下次启动会自动重建。 - 数据来源：全部来自 DSH 本机会话日志。
- 网络请求：不计算价格、不查询官方余额/账单、不发起任何上游网络请求。
适用场景¶
适合需要在本地监控模型调用成本、验证 API 调用逻辑以及查看缓存命中率的开发者。
结语¶
dsh-usage-info 提供了一种轻量级、隐私友好的方式来追踪 DSH 的使用情况。所有计算均在本地完成，不涉及敏感数据上传。
