前言¶
DeepSeek Harness（DSH）是一个插件化的智能体开发框架。在日常使用中，监控官方 API 余额和 Token 消耗量是刚需。现有的方案往往需要额外的后台进程或跨域调用，不够轻量。这个插件通过原生侧边栏集成，直接读取 DSH 的会话日志来聚合 Token 使用数据，并实时查询官方余额。
这是什么¶
这是一个轻量级的 DSH 侧边栏插件，由 lurejewel 维护，采用 MIT 许可证。它不依赖独立的守护进程或数据库，完全利用 DSH 现有的安装环境和凭证服务。主要功能是展示官方 DeepSeek 余额以及基于本地会话日志的 Token 使用历史。
核心功能¶
该插件包含以下核心能力：
- 官方余额查询：利用 DSH 已有的
DEEPSEEK_API_KEY直接向api.deepseek.com/user/balance发起请求。API 密钥永远不会存储在浏览器中，所有调用均在服务器端完成。 - Token 使用历史：扫描
$DSH_HOME/sessions目录下的日志文件，按天聚合输入、输出和缓存 Token 数据，支持展示今日总量、每日平均值和缓存命中率。 - 侧边栏集成：在左侧边栏底部注册触发器。展开时显示标签，收起时显示图标。点击后通过模态框展示数据。
- 一键充值：在刷新按钮旁提供“充值/Top up”按钮，点击后直接打开官方计费页面。
- 零 footprint：无守护进程，无额外配置，无数据库。所有数据均来源于当前的 DSH 安装。
安装与启用¶
在安装前，请确保环境满足以下版本要求：
| 组件 | 最低版本 |
|---|---|
| DeepSeek Harness | >= 0.1.0-rc.7 (实测 0.1.5-rc.2) |
| Node.js | >= 20 |
| pnpm | >= 10 |
执行以下命令安装插件：
dsh plugin --profile web add dsh-usage-plugin
安装后需要重启 dsh web 进程才能生效，随后在浏览器中硬刷新（Cmd/Ctrl + Shift + R）即可在左侧边栏底部看到使用量图标。
典型用法¶
插件通过侧边栏面板与后端 API 交互。
侧边栏操作¶
- 刷新：点击图标或刷新按钮获取最新数据。使用
fresh=1参数可绕过短时的结果缓存。 - 充值：点击充值按钮跳转至官方充值页面。
API 接口¶
插件暴露了两个 HTTP 接口，与 DSH 的其他 /api 接口共享进程级 Token 鉴权：
- 查询余额：
GET /api/dsh-usage/balance
- 查询统计：
GET /api/dsh-usage/stats?days=N
其中 `N` 为查询天数，默认 7，范围限制在 1 到 90 之间。
适用场景与注意¶
该插件适合需要在开发或使用过程中频繁查看余额和 Token 消耗量的 DSH 用户。
注意事项：
1. 数据源安全：余额查询发生在服务器端，密钥不会暴露给前端；Token 历史仅读取本地日志，不涉及第三方网络调用。
2. 性能优化：会话日志扫描在 Worker 线程中运行，不会阻塞 DSH Web 服务器的主事件循环，防止健康检查误判服务宕机。
3. 版本兼容：需要 DeepSeek Harness 版本 >= 0.1.0-rc.7。
结尾¶
该插件通过原生侧边栏的形式，解决了余额查询和历史 Token 统计的痛点，且保持了零配置的轻量化特性。相关源码与安装详情可访问插件仓库。
