dsh-usage-stats

一句话定位

为 DeepSeek Harness 增加一个"用量统计"设置页：用 GitHub 风格的 53 周热力图回顾每天的会话回合，并配以 Token 消耗、缓存命中率、DeepSeek 账户余额和工作区别名管理。面向想看清自己每周/每月到底"烧"了多少 Token 的普通用户。

核心能力

• 渲染 53 周 × 7 天 GitHub 风格热力图，按回合数分四档绿色浓度，悬停查看当日各工作区回合与 Token 明细
• 展示总回合数、总会话数、输入/输出/缓存读取/缓存写入/推理 Token 分项卡片与缓存命中率
• 调 DeepSeek /user/balance 接口查询账户余额（CNY / USD 等多币种），5 分钟内复用缓存
• 在头部维护工作区别名表，保存到本地 KV 存储并跨重启保留
• 提供 30 天 / 90 天 / 全部三档时间范围切换，所有卡片与进度条随之重算

技术实现

• 语言: JavaScript（ESM，无构建步骤）
• 关键依赖: 无第三方运行时依赖（package.json 不声明 dependencies）；host 半只用 Cordis 框架自带的服务（sessionQuery、workspaceRegistry、subprocess、credentials、settings、storage、webServer、timer），client 半通过运行时注入的 react 渲染
• 架构模式: 双半插件（host 半 + web client 半）。host 半在启动时跑一次历史会话扫描回填 + 订阅 session/event 实时折叠 turn/end 与 assistant/message.usage；通过 webServer.register 暴露三个 HTTP 路由给前端；client 半以 window.__ModuleLoader__.load 工厂格式提供 React 组件，并 slots.inject('settings.section', ...) 把"用量统计"页注册进设置面板
• 入口文件: lib/index.js（host）、lib/client.js（client bundle）、cordis.patch.yml（注入清单）

适用场景

经常用 DeepSeek Harness 跑长会话、想知道自己一周到底消耗了多少 Token、哪些工作区最"费钱"的用户；或者同时维护多个 DSH 项目目录、想给每个项目目录起个易记别名的用户。安装后能在设置面板直观看到活动节奏、Token 分布和官方账户余额，方便判断要不要调整模型档位或续费。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:Make0209/dsh-usage-stats

配置项

本插件无需额外配置。安装即用，无需写环境变量或修改 cordis.patch.yml。

如需账户余额卡片显示数字，需确保宿主中 llm-deepseek 的 API Key 环境变量（默认 DEEPSEEK_API_KEY）已正确配置；插件不会自行写入该配置。

常见问题

Q: 安装后需要重启 DSH 才能看到用量统计页吗？

A: 不需要。host 半启动时立刻跑历史回填，client 半随 web 页面加载，刷新浏览器即可在设置面板的"用量统计"标签页看到内容。

Q: 余额卡片显示「未配置」该怎么办？

A: 插件读取的是 llm-deepseek 配置中的 API Key 环境变量（默认 DEEPSEEK_API_KEY），先把 DeepSeek 开放平台的 Key 配到该环境变量或 settings 配置里，再点余额卡片旁的刷新即可。

Q: 卸载插件后历史用量数据会丢失吗？

A: 不会。Token 与回合数全部来自 DSH 持久化的会话日志，会话日志不归本插件所有；插件删除后再次安装会重新回填全部历史。仅工作区别名属于插件自身存储。

Q: 能否只统计某一个项目工作区的用量？

A: 可以切换顶部「30 天 / 90 天 / 全部」时间范围查看总量，热力图本身是按天聚合；按工作区分项的 Token 用量与进度条在工作区栏会自动列出，但只能汇总，无法排除某个工作区。

Q: 账户余额走哪个接口，数据多久刷新一次？

A: 走 DeepSeek 官方 https://api.deepseek.com/user/balance 接口。插件内有 5 分钟缓存，需要强制刷新可访问 /api/usage-stats/balance?force=1。

Q: macOS / Linux 上能看到账户余额吗？

A: 余额查询依赖 curl.exe 或 powershell.exe 进程，在 macOS / Linux 上通常取不到余额；但用量热力图、Token 看板、缓存命中率、工作区别名均跨平台可用。

Q: 工作区别名保存在哪里，删除后能找回吗？

A: 保存在 DSH 的 $DSH_HOME/storages 下一个名为 usage-stats-aliases 的 KV 单元里（global 段）。插件卸载时只会关闭连接，不会主动清理；删除插件并清空 storages 后无法恢复。

Q: 热力图为什么只有最近 53 周？

A: 源码里写死只统计 53 周（约一年）内的日期，超出范围的当天格子不会渲染，统计卡片"全部时间"范围也只对 53 周内的事件重新聚合。

上手难度

入门 — 安装一条命令即可，零配置；安装后设置面板即出现"用量统计"标签页，所有交互都是鼠标点击。

已知问题与限制

• 账户余额仅在能成功 spawn curl.exe 或 powershell.exe 的环境（即 Windows 或带 PowerShell 的环境）下生效，macOS / Linux 用户看到的余额卡片会处于"查询失败"状态（lib/index.js:438-441）
• 热力图与"全部时间"统计均只覆盖最近 53 周，更早的会话日志会被聚合丢弃；热力图本身不回溯（lib/index.js:50-58）
• 仅有「能归属到已注册工作区」的会话（通过会话 cwd 匹配工作区路径）会被统计；未注册工作区或 cwd 为空的会话不出现在任何卡片与热力图中（lib/index.js:226-233）
• 余额查询结果会缓存 5 分钟；余额数字变动需要主动调用 ?force=1 或等缓存过期才会刷新（lib/index.js:410）

DeepSeek Harness 插件：GitHub 风格用量热力图 + Token / 缓存命中 / 账户余额看板 + 工作区别名管理。

• 热力图：53 周 GitHub 绿，每完成一个回合点亮；悬停按工作区显示次数明细与当日 Token
• 统计卡片：总花费 Token（分项）、缓存命中率、账户余额（DeepSeek 官方接口）、总使用次数、连续使用、各工作区 Token 进度条
• 工作区别名：头部「✎ 工作区别名」管理，持久化保存（$DSH_HOME/storages 的 KV 单元 usage-stats-aliases）
• 时间范围切换（近 30 天 / 近 90 天 / 全部）、动画、亮暗主题自适应

效果截图

安装

本插件是标准的 DSH 社区插件包（声明 dsh.bundle manifest + web client 半），数据全部来自持久化会话日志，安装后自动回填历史。

方式一：官方插件命令（推荐）

dsh plugin --profile web add dsh-usage-stats

安装后刷新页面即可，无需手动改配置、无需重启。

方式二：手动注册（本地包）

1. 把本目录放入任意位置，并在 $DSH_HOME/profiles/node_modules/ 下创建指向本目录的符号链接（Windows 用 junction）：

   New-Item -ItemType Junction -Path "$env:DSH_HOME\profiles\node_modules\dsh-usage-stats" -Target "<本目录绝对路径>"
   

2. 在 $DSH_HOME/profiles/web/cordis.patch.yml 添加一行：

   - insert:
       - id: usage-stats
         name: dsh-usage-stats
   

   用户 patch 层会被热重载：保存后刷新页面即可。

架构

• Host 半（lib/index.js）：扫描持久化会话日志聚合用量（turn/end + assistant/message.usage），监听 session/event 实时折叠；通过 webServer 服务注册数据路由：
  • GET /api/usage-stats — 统计快照
  • GET /api/usage-stats/balance?force=1 — 账户余额（复用 llm-deepseek 的 API Key 配置）
  • POST /api/usage-stats/alias — 设置工作区别名
• Client 半（lib/client.js）：window.__ModuleLoader__ 工厂格式的浏览器 bundle，注册设置面板「用量统计」页（settings.section 槽位）。

数据说明

• 使用次数与 Token 全部来自 DSH 持久化会话日志，插件激活时会自动回填全部历史，插件卸载/重启后数据不丢
• 余额查询走 DeepSeek 官方 /user/balance 接口；未配置 API Key 时卡片显示引导文案
• 仅统计能归属到已注册工作区（按会话 cwd 匹配）的会话

开发

• 修改 lib/index.js / lib/client.js 后刷新页面即生效（client bundle 随页面加载）；host 半改动通过重启 DSH 生效
• 插件包无第三方依赖：host 半只使用 Cordis 服务，client 半只使用 react（模块表提供）

License

MIT