dsh-billing-balance

English · 中文

DeepSeek Harness (DSH) dynamic Cordis plugin that shows your DeepSeek official API account balance and Volcengine Ark Coding Plan / Agent Plan quota (used percentages for the 5-hour/session, weekly and monthly windows, plus a countdown to the next quota reset) in the Web GUI.

DeepSeek Harness（DSH）动态 Cordis 插件：在 Web GUI 中显示 DeepSeek 官方 API 账户余额与火山方舟 Coding Plan / Agent Plan 套餐额度（5小时/会话、每周、每月窗口的已用百分比与距下次额度重置的倒计时）。

English

中文 · ← Back to DeepSeekHarnessPlugins

Features

• DeepSeek balance: total / top-up / gift balance and account availability (GET https://api.deepseek.com/user/balance).
• Volcengine Ark Coding Plan: used percentage, progress bar and countdown to reset (ticking every second) for the session (5-hour) / weekly / monthly windows; if you also subscribe to Agent Plan (5h/week/month windows), it is shown as well (Agent Plan also exposes a daily window).
• Three display spots + linkage:
  1. Settings → "Model Balance" page: full panel + manual refresh button + Volcengine AK/SK configuration area;
  2. Readout line below the conversation input box: a persistent one-line summary, auto-refreshing every 30 seconds;
  3. Floating round button ↻ at the bottom right: click to refresh (… → ✓), drag to reposition, hover to show the current DeepSeek balance.
• AK/SK configured in Settings: paste the Volcengine access keys directly on the settings page; they are written to ~/.dsh/.credentials.yaml through DSH's official credentials service, never echoed back in the page, and quota is fetched immediately after saving.

UI Sketch

Settings → Model Balance
┌──────────────────────────────────────┐
│ Model Balance                 [Refresh]│
│ ┌ DeepSeek Official API ────────────┐  │
│ │ Total (CNY)              ¥ 26.91  │  │
│ │ Top-up                   ¥ 26.91  │  │
│ │ Gift                      ¥ 0.00  │  │
│ │ ✓ Account available               │  │
│ └───────────────────────────────────┘  │
│ ┌ Volcengine Ark Coding Plan ────────┐  │
│ │ Coding Plan quota (session/week/month)│
│ │ 5h/session   12.3% used  ▓▓░░░░    │  │
│ │ Reset countdown        4h 21m      │  │
│ │ Weekly       45.0% used  ▓▓▓▓▓░░   │  │
│ │ Monthly       3.0% used  ▓░░░░░░   │  │
│ │ ── Access key config ───────────── │  │
│ │ [AK input] [SK input]              │  │
│ │ [Save & refresh] [Clear]           │  │
│ └────────────────────────────────────┘  │
└──────────────────────────────────────┘

Installation (dsh.bundle)

This repo is also an installable dsh plugin package (package.json declares dsh.bundle + dsh.client):

dsh plugin --profile web add github:YZz-S/dsh-billing-balance

After installation, the three spots — "Settings → Model Balance", the readout below the input box and the floating refresh button — take effect automatically. The dynamic usage (cordis_define loading host.js / client.js) is kept; pick either one.

Quick Start

Prerequisites: a running DeepSeek Harness (dynamic Cordis plugins supported; this plugin was developed and verified on DSH + Node.js v22 + Windows).

1. Run cordis_define in a DSH session:
   • code.host: the content of host.js in this directory (the leading comment may be removed);
   • code.client: the content of client.js.
2. Activate with cordis_run; the first activation includes Client code and needs approval in the page.
3. Open Settings → Model Balance and confirm the DeepSeek balance displays correctly.
4. (Optional) Paste the Volcengine AK/SK in "Access key config" → Save & refresh to view plan quota.

A dynamic plugin disappears when the DSH process ends; for a permanent install, integrate both halves as persistent plugin rows in the DSH composition (host composition + dsh.client web artifact).

Directory Structure

Both usage modes share the same functionality: the installable bundle (index.js + lib/client.js + cordis.patch.yml) and the dynamic cordis_define (host.js / client.js) are mutually exclusive — either one gives the same effect.

Credential Configuration

The plugin reads the following keys from the DSH credentials service (~/.dsh/.credentials.yaml):

Why must the quota API use AK/SK? The Volcengine plan quota API (OpenAPI /open/GetCodingPlanUsage) only accepts control-plane V4 signatures (AK/SK or SSO); a data-plane ARK API key (ark-…) cannot call it — that is Volcengine's official capability boundary (see the implementation notes of ark-cli and cc-switch).

Getting AK/SK: Volcengine console → account avatar (top right) → API access keys (region cn-beijing; the account needs Ark usage-query permission).

Technical Implementation

• Host half (DSH Node process):
  • Credential reading: settings.prepareDocument() locates settings.yaml; .credentials.yaml is read from the same directory; AK/SK writes go through the credentials service;
  • HTTP: the dynamic plugin sandbox provides no fetch, so a node -e inline script is run through the subprocess service (Node ≥ 18 has built-in fetch; the child has its own AbortController timeout); the script is hard-coded, parameters come only from local credentials;
  • DeepSeek: GET /user/balance with Authorization: Bearer;
  • Volcengine: OpenAPI V4 signing (HMAC-SHA256, credential scope {date}/{region}/ark/request, fixed SignedHeaders order host;x-date;x-content-sha256;content-type, empty body, canonical query sorted by key) requests https://open.volcengineapi.com/?Action=…&Region=…&Version=2024-01-01; parses Result.QuotaUsage[] (Level/Percent/ResetTime, second-level timestamps) and tolerates field aliases like Usages/Details and UsedPercent/ResetTimestamp;
  • RPC: get-status (read cache), refresh (force re-pull), set-volc-keys (write/clear AK/SK then re-pull); background refresh every 60 seconds with inFlight dedup.
• Client half (browser): registers three Slots — settings.section (settings page), conversation.composer.dock (readout line), shell.overlay (draggable floating button); a shared in-package state store keeps every view in sync immediately when any entry refreshes; the countdown ticks locally every second.
• Data flow: Client ⇄ Host only via the Package private JSON RPC; return values are all plain data (no live service objects).

Known Limitations

• The dynamic plugin is process-level: after a DSH restart you must define + run it again.
• The Volcengine Coding Plan backend only returns each window's Percent (no absolute used/total); ResetTime may be absent when no window is active (shown as "—").
• The session window is labeled "5h/session" per community implementation convention; Agent Plan's 5h window maps to 5 hours likewise.
• The Volcengine gateway has no official field-by-field documentation; parsing is based on testing and public implementations (see References & Credits). If Volcengine changes the response structure, parsing may return empty — the panel then shows the raw API error.
• Balance data is indicative only and is not a billing basis.

References & Credits

• DeepSeek API Docs — Get User Balance
• volcengine/ark-cli (usage plan semantics: session/weekly/monthly windows, GetCodingPlanUsage call surface)
• farion1231/cc-switch (Volcengine OpenAPI V4 signing details and measured QuotaUsage fields; this plugin is an independent JS reimplementation)
• steipete/CodexBar (inspiration for the Doubao/DeepSeek balance display)

License

MIT

中文

English · ← 返回 DeepSeekHarnessPlugins

DeepSeek Harness（DSH）动态 Cordis 插件：在 Web GUI 中显示 DeepSeek 官方 API 账户余额 与 火山方舟 Coding Plan / Agent Plan 套餐额度（5小时/会话、每周、每月窗口的已用百分比与距下次额度重置的倒计时）。

功能特性

• DeepSeek 余额：总余额 / 充值余额 / 赠送余额、账户可用状态（GET https://api.deepseek.com/user/balance）。
• 火山方舟 Coding Plan：session（5小时）/ weekly / monthly 三个窗口的已用百分比、进度条、距重置倒计时（秒级跳动）；若同时订阅 Agent Plan（5h/周/月窗口），一并显示（Agent Plan 另含每日窗口）。
• 三处展示 + 联动：
  1. 设置 → 「模型余额」页面：完整面板 + 手动刷新按钮 + 火山 AK/SK 配置区；
  2. 对话输入框下方读数条：常驻一行摘要，自动每 30 秒刷新；
  3. 右下角悬浮圆钮 ↻：点击即刷新（…→✓），按住可拖动到任意位置，悬停显示当前 DeepSeek 余额。
• AK/SK 设置内配置：在设置页直接粘贴火山访问密钥，经 DSH 官方 credentials 服务写入 ~/.dsh/.credentials.yaml，页面不回显密钥，保存后立即拉取额度。

界面示意

设置 → 模型余额
┌──────────────────────────────────────┐
│ 模型余额                      [刷新]  │
│ ┌ DeepSeek 官方 API ──────────────┐  │
│ │ 总余额 (CNY)            ¥ 26.91 │  │
│ │ 充值余额                ¥ 26.91 │  │
│ │ 赠送余额                ¥ 0.00  │  │
│ │ ✓ 账户可用                      │  │
│ └──────────────────────────────────┘  │
│ ┌ 火山方舟 Coding Plan ────────────┐  │
│ │ Coding Plan 额度（session/周/月） │  │
│ │ 5小时/会话  12.3% 已用  ▓▓░░░░   │  │
│ │ 额度重置倒计时        4 小时 21 分│  │
│ │ 每周        45.0% 已用  ▓▓▓▓▓░░  │  │
│ │ 每月         3.0% 已用  ▓░░░░░░  │  │
│ │ ── 访问密钥配置 ──────────────── │  │
│ │ [AK 输入框] [SK 输入框]          │  │
│ │ [保存并刷新] [清除]              │  │
│ └──────────────────────────────────┘  │
└──────────────────────────────────────┘

安装（dsh.bundle）

本仓库同时是可安装的 dsh 插件包（package.json 声明 dsh.bundle + dsh.client）：

dsh plugin --profile web add github:YZz-S/dsh-billing-balance

安装后「设置 → 模型余额」「输入框下方读数条」「右下角悬浮刷新按钮」三处自动生效。 动态用法（cordis_define 加载 host.js / client.js）仍保留，两种方式二选一。

快速开始

前置条件：运行中的 DeepSeek Harness（支持动态 Cordis 插件；本插件在 DSH + Node.js v22 + Windows 上开发验证）。

1. 在 DSH 会话中执行 cordis_define：
   • code.host 填入本目录 host.js 的内容（去掉顶部注释亦可）；
   • code.client 填入 client.js 的内容。
2. cordis_run 激活；首次激活包含 Client 代码，需要在页面上批准。
3. 打开 设置 → 模型余额，确认 DeepSeek 余额显示正常。
4. （可选）在「访问密钥配置」粘贴火山 AK/SK → 保存并刷新，查看套餐额度。

动态插件随 DSH 进程结束而消失；如需永久内置，请将两个半边集成为 DSH 组合（host composition + dsh.client Web 产物）中的常驻插件行。

目录结构

两种用法共用同一套功能：可安装 bundle（index.js + lib/client.js + cordis.patch.yml）与动态 cordis_define（host.js / client.js）二选一，效果一致。

凭据配置

插件从 DSH 凭据服务读取以下键（~/.dsh/.credentials.yaml）：

为什么额度接口必须用 AK/SK？ 火山套餐额度接口（OpenAPI /open/GetCodingPlanUsage）只接受控制面 V4 签名（AK/SK 或 SSO），数据面 ARK API Key（ark-…）无法调用——这是火山官方的能力边界（参考 ark-cli 与 cc-switch 的实现说明）。

AK/SK 获取：火山引擎控制台 → 右上角账号头像 → API 访问密钥（区域 cn-beijing，账号需具备 Ark 用量查询权限）。

技术实现

• Host 半边（DSH Node 进程）：
  • 凭据读取：settings.prepareDocument() 定位 settings.yaml，同目录读取 .credentials.yaml；AK/SK 写入走 credentials 服务；
  • HTTP：动态插件沙箱不提供 fetch，因此通过 subprocess 服务执行 node -e 内嵌脚本（Node ≥18 自带 fetch，child 内置 AbortController 超时）；脚本固定内置，参数仅来自本地凭据；
  • DeepSeek：GET /user/balance，Authorization: Bearer；
  • 火山：OpenAPI V4 签名（HMAC-SHA256，credential scope {date}/{region}/ark/request，固定顺序 SignedHeaders host;x-date;x-content-sha256;content-type，空 body，canonical query 按 key 排序）请求 https://open.volcengineapi.com/?Action=…&Region=…&Version=2024-01-01；解析 Result.QuotaUsage[]（Level/Percent/ResetTime，秒级时间戳），兼容 Usages/Details 与 UsedPercent/ResetTimestamp 等字段别名；
  • RPC：get-status（读缓存）、refresh（强制重拉）、set-volc-keys（写/清 AK/SK 后重拉）；每 60 秒后台刷新，inFlight 去重。
• Client 半边（浏览器）：settings.section（设置页）、conversation.composer.dock（读数条）、shell.overlay（可拖动悬浮按钮）三个 Slot 注册；包内共享状态 store，任一入口刷新全部视图立即同步；倒计时每秒本地 tick。
• 数据流：Client ⇄ Host 仅通过 Package 私有 JSON RPC，返回值全部为自有纯数据（无活体服务对象）。

更新记录

• v0.2.1（2025）：修复「保存/刷新后偶发显示 500」——
  • 插件显式声明 inject 依赖（credentials / settings / fs），消除激活顺序竞态——之前未声明依赖时，插件可能在 credentials 服务就绪前被激活，保存火山密钥会间歇性报「credentials 服务不可用」；
  • 写火山 AK/SK 到凭据文件增加有限重试（只重试快速失败，如 Windows 下文件占用/杀软导致的 EPERM/EBUSY）；
  • 刷新失败时保留上次成功抓取的余额/额度并标记 stale，页面不再被上游偶发 500 清空，卡片会显示「⚠ 刷新失败：…（显示上次数据）」；
  • 前端解析错误响应体，显示真实原因（如「保存失败: …」），不再退化成裸 500；
  • 三个 UI 入口的刷新在客户端合并为一次。

已知限制

• 动态插件为进程级：DSH 重启后需重新 define + run。
• 火山 Coding Plan 后端只返回各窗口 Percent（不含绝对已用/总额）；无活跃窗口时可能缺 ResetTime（显示「—」）。
• session 窗口按社区实现惯例标注为「5小时/会话」；Agent Plan 的 5h 窗口同样映射为 5小时。
• 火山网关无官方公开的逐字段文档，字段解析基于实测与公共实现（见「参考与致谢」），火山若调整返回结构可能导致解析为空——此时面板会原样显示接口错误。
• 余额数据仅供提示，不构成计费依据。

参考与致谢

• DeepSeek API 文档 — 查询余额
• volcengine/ark-cli（usage plan 语义：session/weekly/monthly 窗口、GetCodingPlanUsage 调用面）
• farion1231/cc-switch（火山 OpenAPI V4 签名细节与 QuotaUsage 实测字段；本插件为独立 JS 重实现）
• steipete/CodexBar（Doubao/DeepSeek 余额展示思路）

许可

MIT

English · 中文