dsh-llm-usage-stats

DeepSeek Harness（DSH）大模型用量统计插件：自动记录每个大模型的 token 消耗与缓存命中率，在设置面板的「模型用量」页面用图表查看，数据按天持久化为 JSON 文件，可随时清空。

本项目按 DSH web plugin 规范发布（dsh.client 机制），安装方式与 dsh-better-sidebar 等社区插件一致。

✨ 功能特性

• 汇总卡片：总输入（未缓存）/ 缓存读取 / 缓存写入 / 总输出 / 缓存命中率 / 请求次数
• 图表：Token 消耗趋势柱状图（输入构成堆叠 + 输出）、缓存命中率折线图 —— 手写 SVG，零外部依赖
• 时间范围：天 / 周 / 月 / 自定义起止日期（超过 90 天自动按月聚合）
• 模型筛选：下拉自动列出当前已配置的模型（默认模型带「默认」标记），兼容历史上出现过的模型
• 模型明细：响应式卡片布局，任意窗口宽度无横向溢出
• 性能友好：监听 llm/stream 只做纯内存聚合（流完全透传、每次调用零 I/O），定时落盘默认 300 秒（页面可调 30 秒–24 小时），不影响 Harness 运行效率
• 容错：某指标取不到（如 DeepSeek 不报告缓存写入）显示 —，不报错、不中断
• 附带网页版仪表盘：浏览器访问 http://127.0.0.1:3080/llm-usage-stats/

📦 安装

前置条件：~/.dsh/profiles/web/ 是 pnpm 项目（DSH 默认结构，未改动的机器直接可用）。

方式一：从 GitHub 安装（推荐）

cd ~/.dsh/profiles/web
pnpm add github:lightli369/dsh-llm-usage-stats

然后编辑 package.json，在 dsh.profile.bundles 数组里加一项：

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-llm-usage-stats"
      ]
    }
  }
}

pnpm install

重启 dsh，打开 设置 → 模型用量。

方式二：本地源码安装（二次开发）

git clone https://github.com/lightli369/dsh-llm-usage-stats.git ~/dsh-llm-usage-stats
cd ~/.dsh/profiles/web
pnpm add file:~/dsh-llm-usage-stats
# 同样在 dsh.profile.bundles 里加 "dsh-llm-usage-stats"，然后 pnpm install，重启

🗂 数据说明

• 目录：~/.dsh/llm-usage-stats/，按天一个文件：usage-YYYY-MM-DD.json
• 格式：

{
  "models": {
    "deepseek-modlens/deepseek-v4-pro": {
      "input": 41905,
      "output": 18443,
      "cacheRead": 10245888,
      "cacheWrite": null,
      "reasoning": 9988,
      "requests": 63
    }
  }
}

• 统计语义：input 为未缓存输入；计费输入 = input + cacheRead + cacheWrite；缓存命中率 = cacheRead ÷ 计费输入
• 清空：页面底部「清空所有记录」，或直接删除目录下所有 usage-*.json 文件
• 重启安全：内存增量按周期落盘，重启最多丢失一个落盘周期（默认 5 分钟）的数据

🔌 HTTP API

供二次开发同源调用（返回 JSON）：

方法	路径	说明
GET	/llm-usage-stats/api/query?from=YYYY-MM-DD&to=YYYY-MM-DD&model=all	按天 × 模型的聚合数据
GET	/llm-usage-stats/api/status	数据目录、落盘间隔、上次落盘时间
GET	/llm-usage-stats/api/models	已配置模型列表 + 默认模型
POST	/llm-usage-stats/api/flush	立即落盘
POST	/llm-usage-stats/api/clear	清空全部记录
POST	/llm-usage-stats/api/set-interval?n=300	修改落盘间隔（30–86400 秒）

🗂 项目结构

├── lib
│   ├── index.js     # Host 插件：数据采集、定时落盘、HTTP API
│   └── client.js    # Client bundle：设置面板「模型用量」页面
├── package.json     # dsh.client 声明（platform: web）
├── LICENSE
└── README.md

📄 License

MIT