dsh-usage-dashboard
English | 中文
DeepSeek 平台用量仪表盘插件:在 DeepSeek Harness Web UI 右下角挂一枚余额角标,点开展示真实扣费数据(与 platform.deepseek.com/usage 同源),不必再切回开发平台查看花费。
**适用范围:**本插件仅查询 DeepSeek 官方 API 与 DeepSeek Platform 的账户余额、用量和扣费数据。即使 Harness 配置了其他模型供应商,本插件也不会读取相应供应商的账单;此时面板可能继续显示 DeepSeek 数据、显示不可用或报错,均不代表当前模型供应商的真实余额或花费。
当前稳定版本为 1.1.1,完整的小版本变更见 CHANGELOG.md。
效果预览
安装并配置后,右下角余额角标可展开为完整的 DeepSeek 用量仪表盘(峰谷横幅、今日/本月指标、用量热力图与模型分布环形图):
DeepSeek Harness 用量仪表盘(深色主题 · 峰时 · 中文)
界面截图
面板 —— 深色 / 浅色 × 中文 / English:
余额角标 —— 峰时琥珀色呼吸光 / 谷时绿色静光:
功能
- 余额角标:右下角一枚胶囊实时显示账户余额;当前为峰时/谷时时,边框呈现琥珀呼吸光 / 绿色静光;点击展开面板,点击面板外任意处或角标即可关闭(打开/关闭均带 160ms 淡入淡出)
- 账户余额:官方
/user/balance(API Key)+ 平台 get_user_summary(登录态),充值/赠送拆分;金额币种跟随账户(¥/$/€),只换符号、不做汇率换算
- 指标卡(3×2 网格):今日金额 · 今日Token · 请求数(日)/ 本月金额 · 本月Token · 缓存命中率(月);今日两张卡各带"今日占本月"进度条,粒度一目了然
- 用量热力图(GitHub 风格,默认收起):点击「用量热力图」标题行展开;近
historyMonths 个月(默认 6)的每日金额/Token,颜色越深用量越高;悬停单格即时浮卡显示当日金额、Token、请求数与命中率,无用量日提示"该日无用量"。展开状态记在浏览器本地
- 模型分布环形图:支持 日 / 周 / 月 三种周期并可 ‹ › 左右翻看、按金额/按 Token 两个排序维度;图例同时显示两个维度(主值跟随排序维度,另一维度以同排小字常显);中心显示周期总量;小额模型自动合并为灰色"其他"(份额 ≥1.5% 且前 8 名单独显示)
- 峰谷时段横幅:面板顶部统一风格横幅(峰橙红 / 谷绿,右侧紧凑倒计时),提示当前计费时段与建议(默认峰时
09:00–12:00、14:00–18:00 北京时间,其余谷时约 5 折;窗口用 peakWindows 配置)
- 面板内升级提示:检测到 npm 上有新版本时,页脚版本号变成可点击徽标(显示
当前版本 → 可用版本),一键复制升级命令(命令由 updateCommand 配置);不自动安装,升级后需重启 dsh web
- 中英双语 + 面板语言开关:设置里可选「跟随界面 / 中文 / English」,默认跟随 Harness 界面语言;显式选择只影响本面板并记在浏览器本地(非中英语言按 fallback 链回退英文)
- userToken 管理面板:一次性粘贴平台登录态,保存在宿主端
$DSH_HOME/storages/dsh-usage-dashboard.secret(0600 权限),浏览器只会拿到脱敏值;支持验证、清除、环境变量 DEEPSEEK_PLATFORM_TOKEN 兜底
刷新机制
| 触发方式 | 说明 |
|---|
| 固定轮询 | 宿主端每 refreshIntervalMs(默认 10 分钟)向 DeepSeek 拉取一次;浏览器端每 clientPollIntervalMs(默认 30 秒)读一次本地缓存;页面隐藏时暂停,回到前台立即补拉 |
| 任务完成即时刷新 | 监听会话 turn/end 事件,每轮任务结束后立即向 DeepSeek 拉取一次,最小冷却 taskRefreshCooldownMs(默认 60 秒),高频任务自动合并防连击 |
| 手动 | 面板 ↻ 按钮穿透缓存强制刷新;打开面板、切换图表维度、保存配置时也会立即刷新 |
DeepSeek 账单本身有分钟级结算延迟,任务刚结束立刻拉到的数字可能尚未完全入账,下一个轮询周期会自动补齐。
DeepSeek 数据来源
| 数据 | 接口 | 凭据 |
|---|
| 官方余额 | GET {apiBaseUrl}/user/balance | API Key(默认 DEEPSEEK_API_KEY,经 ctx.credentials 解析) |
| 平台余额 | GET {platformBaseUrl}/api/v0/users/get_user_summary | 平台 userToken |
| 每日用量 | GET {platformBaseUrl}/api/v0/usage/by_api_key/amount?start=&end=&tz= | 平台 userToken |
| 每日花费 | GET {platformBaseUrl}/api/v0/usage/by_api_key/cost?start=&end=&tz= | 平台 userToken |
| 每日用量(兜底) | GET {platformBaseUrl}/api/v0/usage/amount?month=&year= | 平台 userToken |
| 每日花费(兜底) | GET {platformBaseUrl}/api/v0/usage/cost?month=&year= | 平台 userToken |
start/end 为 epoch 秒,tz 为时区偏移秒(timezoneOffsetSec,默认 28800 = GMT+8)。该接口与官网用量页同源:
按 GMT+8 切天且当天实时更新(旧接口按 UTC 切天,当天的桶恒为 0,因此仅作兜底)。
平台用量接口为未公开接口(usage 页面同源,社区应用已在使用的稳定调用方式),官方改版可能导致失效;
插件对响应做防御式解析,失效时保留上次成功数据并显示错误,不影响 Harness 本身。
⚠️ 安全与隐私(使用前必读)
- userToken 是账户级凭证。真实扣费数据来自 platform.deepseek.com 的登录态接口,需要你的
userToken(相当于平台账户的访问凭证),请像保管密码一样对待它,不要把它粘贴进公开渠道、聊天记录或任何 git 仓库。
- 网络只流向 DeepSeek 官方:token 仅用于向
platform.deepseek.com 的三个未公开用量接口发起只读查询,以及官方 api.deepseek.com/user/balance。插件不含任何遥测、统计上报或第三方转发。
- 本地存储:token 保存在
$DSH_HOME/storages/dsh-usage-dashboard.secret(0600 权限,仅宿主进程可读);浏览器页面只能拿到脱敏值(abcd****wxyz),明文 token 不会下发到浏览器。也可以用环境变量 DEEPSEEK_PLATFORM_TOKEN 代替。
- 仓库与代码不含任何密钥;插件代码不会打印、记录或上传 token。
- 分享安装记录前必须脱敏:不要运行或分享会完整打印
.credentials.yaml、环境变量或 token 的命令。发送日志/会话压缩包前,请搜索并移除 sk-、userToken、DEEPSEEK_API_KEY、DEEPSEEK_PLATFORM_TOKEN 等内容;不再需要的调试快照(例如 $DSH_HOME/logs/dsh-web-env-snapshot.json)应及时删除。
- 未公开接口风险:
/api/v0/usage/* 是平台内部接口,无 SLA,官方改版可能导致数据失效(不影响 Harness 本体,失败时保留上次成功数据)。
- 清除方法:面板 ⚙️ 设置 →「清除已保存的 token」,或直接删除
~/.dsh/storages/dsh-usage-dashboard.secret。
- 使用本插件即表示你已了解上述风险并自行承担。详见 SECURITY.md。
安装
准备工作
- Node.js
18 或更高版本
- 已能正常启动 DeepSeek Harness
pnpm 可用(插件安装器会调用它)
先检查:
node --version
pnpm --version
如果第二条命令提示未找到,安装固定版本:
npm install --global pnpm@10.15.0
方式一:npm 发布包(推荐)
无需克隆仓库,直接安装发布包。安装时记不记“版本范围”决定以后升级是否省心,两种都支持,按需二选一:
方式一 A:跟随更新(默认推荐,升级最方便)
dsh plugin --profile web add deepseek-harness-usage-dashboard
不写死版本号时,pnpm 会按 ^1.1.1 这类范围记录。以后要升级,一条命令即可跟随到最新 1.x:
dsh plugin --profile web update deepseek-harness-usage-dashboard
方式一 B:固定版本(可复现)
dsh plugin --profile web add deepseek-harness-usage-dashboard@1.1.1
这里特意固定为 1.1.1,避免未来发布新版本后安装结果发生变化;升级时需要把版本号换成新版本,重新执行上面的命令。
方式二:GitHub Release .tgz(npm 不可用或受 pnpm 完整性策略限制时)
请先从 v1.1.1 Release 下载 .tgz,再用本地 file: 路径安装。这样 pnpm 可以把 tarball 固定写入 Profile 锁文件:
dsh plugin --profile web add "file:C:/Users/你的用户名/Downloads/deepseek-harness-usage-dashboard-1.1.1.tgz"
Get-FileHash "C:/Users/你的用户名/Downloads/deepseek-harness-usage-dashboard-1.1.1.tgz" -Algorithm SHA256
SHA-256 应与 Release 页面公布的值一致。远程 URL 也可直接尝试:
dsh plugin --profile web add https://github.com/nzz0991999-ai/dsh-usage-dashboard/releases/download/v1.1.1/deepseek-harness-usage-dashboard-1.1.1.tgz
配置 DeepSeek Platform userToken
DEEPSEEK_API_KEY 与 userToken 不是同一个凭据:API Key 用于官方余额接口;平台登录态 userToken 用于今日/月度用量和实际扣费。platform.deepseek.com 与 api.deepseek.com 是 DeepSeek 官方统一域名,不是本插件自建的中转地址。
- 用 Chrome 或 Edge 登录 https://platform.deepseek.com,并保持该页面处于登录状态。
- 按
F12 打开 DevTools → Application(应用) → Local Storage(本地存储) → https://platform.deepseek.com。
- 搜索
userToken,只复制其 Value(值),不要复制字段名、引号或前后空格。如果找不到,刷新平台页面或重新登录后再检查。
- 回到 Harness,打开右下角仪表盘 → ⚙️ 设置 → 粘贴 → 「验证并保存」。保存成功后只会显示脱敏值。
请勿把 userToken 粘贴到终端、聊天、Issue、截图或安装日志中。高级用户也可在启动 Harness 前设置 DEEPSEEK_PLATFORM_TOKEN,但命令行历史可能保存明文,因此面板粘贴方式更安全。
升级
插件发布新版本后,按你的安装方式执行对应命令,然后回到原工作目录重启 dsh web 并强制刷新页面:
| 安装方式 | 升级到最新 |
|---|
| npm 跟随更新(方式一 A) | dsh plugin --profile web update deepseek-harness-usage-dashboard |
| npm 固定版本(方式一 B) | dsh plugin --profile web add deepseek-harness-usage-dashboard@<新版本号> |
GitHub Release .tgz(方式二) | 从 Release 重新下载新的 .tgz,再执行 dsh plugin --profile web add "file:…" 重装 |
先查看是否有新版本:
dsh plugin --profile web outdated
采用「方式一 A(跟随更新)」时,update 会自动升到最新 1.x;采用「方式一 B(固定版本)」时,update 不会越级,需把版本号显式换成新版本——这是可复现性的取舍。
面板内的一键升级提示
检测到 npm 上有更新版本时,面板右下角的版本号会变成可点击的琥珀色徽标(显示 当前版本 → 可用版本):
点完徽标之后做什么——四步,其中第 3 步不能省:
- 点击徽标:升级命令写入剪贴板,徽标变绿显示「✓ 已复制升级命令」(约 2.5 秒后恢复);悬停可预览将要复制的命令。徽标只复制文本,不执行任何命令、也不改动本机文件。
- 粘贴到终端执行:命令取自配置项
updateCommand,默认是 dsh plugin --profile web update deepseek-harness-usage-dashboard。
- 重启
dsh web:宿主的插件代码在启动时加载,只替换磁盘上的文件不会生效。
- 强制刷新页面(Cmd/Ctrl+Shift+R):客户端 bundle 同样是启动时提供;重启后徽标自动消失(本机已是最新)。
提示只在打开面板时出现,不会主动弹窗打扰;检查频率由 updateCheckIntervalMs 控制(默认 6 小时),checkUpdate: false 可完全关闭。
常见安装问题
EADDRINUSE: address already in use 127.0.0.1:3080
这通常表示已有一个 dsh web 正在运行,不是插件、API Key 或 userToken 出错。如果原来的页面能打开,直接使用并刷新,不要再次启动。
Windows PowerShell 可先确认监听进程:
$dshPid = Get-NetTCPConnection -LocalPort 3080 -State Listen |
Select-Object -First 1 -ExpandProperty OwningProcess
Get-CimInstance Win32_Process -Filter "ProcessId=$dshPid" |
Select-Object ProcessId, CommandLine
确认它确实是旧的 dsh web 后,再结束并从正确工作目录重启:
taskkill /PID $dshPid /T /F
Set-Location "F:/path/to/your/harness-workspace"
dsh web
macOS/Linux 可用 lsof -nP -iTCP:3080 -sTCP:LISTEN 查看进程,确认后执行 kill <PID>,再从原工作目录启动。
ERR_MODULE_NOT_FOUND: @deepseek-ai/schemastery
这是本地目录被作为 link: 安装时可能出现的依赖缺失。移除旧插件后,改用上面的 npm 包或 Release .tgz 重新安装:
dsh plugin --profile web remove dsh-usage-dashboard
dsh plugin --profile web add deepseek-harness-usage-dashboard@1.1.1
安装后没有角标
确认安装和重启都使用 web profile,并从原 Harness 工作目录启动;然后对浏览器页面执行一次强制刷新。若当前已有一个旧的 dsh web 进程,先按上面的端口占用步骤确认并重启该进程。
覆盖配置
写进 $DSH_HOME/profiles/web/cordis.patch.yml:
- id: dsh-usage-dashboard
config:
refreshIntervalMs: 300000 # 服务器向 DeepSeek 拉取用量的频率(ms)
clientPollIntervalMs: 15000 # 浏览器读取缓存的频率(ms)
timeoutMs: 8000 # 单次请求超时(ms)
historyMonths: 6 # 面板可回看的月数
apiKeyRef: DEEPSEEK_API_KEY # 官方余额用的凭据引用名
timezoneOffsetSec: 28800 # 用量/花费的时区偏移(秒), 默认 GMT+8; 决定"今天"和按天分桶, 不看浏览器时区
taskRefreshCooldownMs: 60000 # 任务完成后即时刷新的最小冷却(ms)
peakWindows: [09:00-12:00, 14:00-18:00] # 峰时窗口(HH:MM-HH:MM, 北京时间)
checkUpdate: true # 是否检查 npm 新版本(仅提示, 不自动安装)
updateCheckIntervalMs: 21600000 # 检查新版本的频率(ms), 默认 6 小时
updateCommand: dsh plugin --profile web update deepseek-harness-usage-dashboard # 页脚徽标一键复制的升级命令
发布流程(维护者)
发版前先把两份 CHANGELOG 里对应版本的小节写好并提交(中文 CHANGELOG.md + 英文 CHANGELOG_EN.md),
它是 GitHub Release 正文的唯一来源;然后一条命令完成剩下的全部动作:
npm run release -- 1.3.0 "简短摘要"
scripts/release.sh 会依次:
- 前提校验:在
main、与 origin/main 同步、工作区干净、gh 已登录、版本号递增、tag 未被占用、两份 CHANGELOG 都有该版本小节
- 本地校验:
npm test + node --check client/client.js + verify:package
- 提交:
package.json 改版本 → release: vX.Y.Z <摘要> → 推送
- 打标:注解 tag
vX.Y.Z → 推送
- 发 Release:用 CHANGELOG 小节合成正文(中文 + 折叠的英文 + compare 链接)→
gh release create --verify-tag
- 提示发布 npm:加
--publish 则继续执行 npm publish --access public(账号要求 2FA 时需在交互式终端输入 OTP)
| 参数 | 作用 |
|---|
--dry-run | 只做校验并预览将要执行的动作与 Release 正文,不改动任何东西 |
--yes | 跳过确认提示(脚本化/CI 调用) |
--skip-checks | 跳过第 2 步的本地校验 |
--publish | 第 6 步真的执行 npm publish |
--branch <name> | 指定发布分支(默认 main) |
脚本不会做危险操作:不改写历史、不 --force、不自动提交 CHANGELOG;版本号未递增、tag 已存在、工作区不干净等情况一律直接终止。
卸载
dsh plugin --profile web remove deepseek-harness-usage-dashboard
如果你卸载的是使用旧包名安装的 1.0.0 或更早版本,请改用 dsh plugin --profile web remove dsh-usage-dashboard。如不再使用,可同时删除 $DSH_HOME/storages/dsh-usage-dashboard.secret。
