DeepSeek Harness (DSH) 的开发者在使用 API 进行开发或调试时，需要实时掌握账户余额以及本机的 token 消耗情况。由于 DeepSeek 官方未公开详细的用量查询接口，手动统计本机会话日志不仅繁琐，还容易出错。下面介绍一款由社区维护的插件，通过命令行接口同时解决余额查询与用量汇总的问题。
插件简介¶
该插件名为 dsh-deepseek-usage，由开发者 kane-le 维护，遵循 MIT 许可证。它是一个 DSH 插件，旨在通过 /usage 命令提供账户余额的实时查询，并汇总本机 DSH 会话日志中的 token 用量。
核心功能¶
该插件主要包含以下能力：
- 实时查询官方账户余额：通过调用
GET https://api.deepseek.com/user/balance接口，获取账户可用状态、各币种总余额 / 充值余额 / 赠送余额。 - 汇总本机 DSH 会话日志：解析本机会话日志文件，统计输入 tokens、输出 tokens、缓存读取 tokens 和推理 tokens。
- 增量扫描：支持增量扫描会话日志，首次扫描后，后续查询仅读取新增内容，节省时间。
- 自动处理压缩日志：支持自动解析 zstd 压缩的日志文件（
session.jsonl.zstd），无需外部解压工具。
安装与启用¶
插件通过插件管理器安装。请确保已安装 DeepSeek Harness。
- 将插件源码下载到本地，例如保存为
/path/to/dsh-deepseek-usage。 - 在终端中执行以下命令添加插件：
dsh plugin --profile web add /path/to/dsh-deepseek-usage
- 安装完成后，重启
dsh web进程，插件会自动加入 profile 的 bundles。
典型用法¶
安装并重启后，可在 Web 界面或命令行中调用以下命令：
| 命令 | 说明 |
|---|---|
/usage |
查看完整报告：本机累计 token 用量 + 实时余额 |
/usage balance |
仅查询余额，不进行日志扫描 |
/usage rescan |
强制重新扫描全部会话日志后输出完整报告 |
示例输出：
DeepSeek API 用量与余额
================================
[用量] 本机累计（会话日志 + 实时跟踪）
输入 tokens: 196,267
输出 tokens: 107,874
缓存读取 tokens: 6,773,172
推理 tokens: 54,537
会话数: 9 | 最近活动: 2026-08-24 18:11:51 UTC
...
[余额] 实时查询
账户可用: 是
CNY 总余额 2.04 | 充值 2.04 | 赠送 0.00
技术细节¶
API Key 解析顺序¶
插件会按照以下顺序尝试获取 API Key：
- 官方 credentials 服务（Web 界面「设置 → 模型」写入的配置）。
- 环境变量
DEEPSEEK_API_KEY。 - 本地配置文件
$DSH_HOME/.credentials.yaml中的DEEPSEEK_API_KEY行。
接口与日志路径¶
- 接口地址：默认为
https://api.deepseek.com，可通过环境变量DEEPSEEK_BASE_URL覆盖。 - 日志路径：
$DSH_HOME/sessions/*/*/session.jsonl[.zstd]。 - 数据存储：用量账本保存在
$DSH_HOME/storages/deepseek-usage.json。
数据与幂等性¶
- 去重机制：用量数据按
会话:回合:步骤键进行去重合并。实时事件与日志回扫共用同一键空间，不会重复计数。 - 增量扫描：日志扫描基于文件大小和修改时间（mtime），首次全量扫描后，后续命令仅读取新增内容。
- 解码方式：日志文件为 zstd 多帧格式，插件使用
node:zlib进行解码，无需依赖外部工具。
适用场景与注意¶
- 适用对象：使用 DeepSeek Harness 进行开发或调试的用户，需要监控 API 消耗。
- 数据来源说明：用量数据完全来自本机会话日志。由于官方 API 未公开用量查询接口，该插件通过解析日志实现统计。
- 权限注意：插件以当前 dsh 进程权限运行，安装前请检查源码与许可证。
