dsh-deepseek-quota
A DeepSeek Harness (DSH) web GUI plugin: shows your remaining DeepSeek API quota (balance) and today's consumption in a floating card pinned to the bottom-right corner of the page.
dsh-deepseek-quota 截图
中文文档在前，英文说明见下文。 / Chinese docs first, English below.
中文说明
一个给 DeepSeek Harness（DSH）网页界面用的插件：在页面右下角悬浮显示你的 DeepSeek API 额度（余额） 与 今日消费。
功能
- 右下角悬浮卡片（注册在框架级
shell.overlay 槽位，纯叠加、不遮挡应用）。
- 显示总余额、可用状态、当前对话费用、今日已消费、赠送余额与充值余额。
- 当前对话费用：宿主侧对每条
assistant/message 按官方价格表计价（含 2026-08-17 起峰谷定价；定价引擎移植自 dsh-web-billing，MIT），通过 GET /api/deepseek-session-cost?sessionId=<id> 返回当前会话累计费用——按持久化日志全量回放，包含安装前（重启前）的历史。把鼠标放到费用后面的圆圈叹号 ⓘ 上，会显示代入真实数值的计算公式（输入/缓存命中/输出 tokens × 单价 = 小计，单价为加权有效价 ¥/M）。
- 余额每 60 秒自动刷新、对话费用每 5 秒刷新，也可手动刷新。
- 峰谷时段提示：显示当前处于 DeepSeek 的高峰（工作日 09:00–12:00 / 14:00–18:00，北京时间）还是空闲时段（2026-08-17 起；周六、周日全天空闲），让你知道现在跑模型更贵还是更便宜；随余额每 60 秒刷新。
- 可折叠为小钱包图标：点卡头右下角的箭头即可把卡片收成右下角的一个小钱包图标（点击可展开）；折叠态下钱包图标会以颜色标识当前峰谷（高峰=红、空闲=绿、常规=灰）或错误状态，颜色随余额每 60 秒刷新。
- 自动跟随应用浅色/深色主题（使用
--dsw-* 设计变量）。
- 明确的错误状态：未配置 Key、网络失败、接口报错等。
- API Key 不出本机：浏览器只访问本地路由（由宿主侧注册）。
安装
需要 pnpm。
# 已安装 dsh CLI：
dsh plugin --profile web add dsh-deepseek-quota
# 未安装 dsh CLI（例如通过 npx 启动）：
npx @deepseek-ai/dsh plugin --profile web add dsh-deepseek-quota
该包声明了 dsh.bundle，dsh plugin 会自动把它加进 profile 的 bundle 层（无需手动改配置）。之后：
- 重启网页应用：
dsh web（若无 dsh CLI，用 npx @deepseek-ai/dsh web；bundle 层在启动时读取）。
- 打开 http://127.0.0.1:3080 并刷新页面。
- 右下角即出现额度卡片。
手动方式：把包放进 profile 的 node_modules，并在 ~/.dsh/profiles/web/cordis.patch.yml 中加一条：
- insert:
- id: deepseek-quota
name: dsh-deepseek-quota
配置
插件读取的正是 harness 自己在用的那个 Key：DEEPSEEK_API_KEY（通过凭证服务解析；在 设置 → 模型 页面填写，存于 ~/.dsh/.credentials.yaml，或在启动环境中导出）。
今日消费（今日已消费）
DeepSeek 官方 API 没有开放用量查询接口，所以插件按优先级使用两种来源：
-
官方数据（优先）——与平台控制台相同的可按日期筛选的数据。需要配置可选的平台会话令牌：
# 获取令牌：登录 https://platform.deepseek.com，打开 DevTools → Console，执行：
# JSON.parse(localStorage.getItem('userToken')).value
# 然后把值写入凭证（例如追加到 ~/.dsh/.credentials.yaml）：
# DEEPSEEK_PLATFORM_TOKEN: <令牌>
配置后，宿主侧调用 platform.deepseek.com/api/v0/usage/cost?month=&year= 并取"今天"那一行。卡片显示 今日已消费 ¥X.XX。
-
估算（兜底）——未配置令牌时，宿主侧按余额差值估算（max(0, 当天期初余额 − 当前余额)，状态存于 ~/.dsh/storages/deepseek-quota-day.json）。卡片显示 今日约消费 ≈¥X.XX，避免被误认为官方数字。
无需其它配置。
工作原理
| 部分 | 文件 | 作用 |
|---|
| 宿主侧 | lib/index.js | Cordis 插件（inject: credentials, webServer），注册 GET /api/deepseek-balance（余额+今日消费+当前峰谷计价时段）与 GET /api/deepseek-session-cost?sessionId=<id>（当前对话费用）；订阅 session/event 对每条 assistant/message 计价。 |
| 定价 | lib/pricing.js | DeepSeek 官方价格引擎（政策时间表 + 峰谷定价，周末全天低峰），移植自 dsh-web-billing（MIT）。 |
| 浏览器侧 | lib/client.js | dsh.client 网页包，把组件注册进 shell.overlay；余额每 60 秒轮询（含峰谷时段徽章）、当前会话费用每 5 秒轮询。 |
| 组合层 | cordis.patch.yml | dsh.bundle 补丁层，插入加载项。 |
开发
git clone <你的仓库>
cd dsh-deepseek-quota
# 修改 lib/index.js（宿主）/ lib/client.js（浏览器侧）
# 本地安装测试：
dsh plugin --profile web add . # 无 dsh CLI 时：npx @deepseek-ai/dsh plugin --profile web add .
修改 lib/client.js 后需重启 dsh web（无 dsh CLI 时用 npx @deepseek-ai/dsh web）以重新生成引导哈希（rev），再强制刷新页面。
协议
MIT
English
A plugin for the DeepSeek Harness (DSH) web GUI that shows your remaining DeepSeek API quota (balance) in a floating card pinned to the bottom-right corner of the page.
Features
- Bottom-right overlay card (registered into the frame-wide
shell.overlay slot — additive, never blocks the app).
- Shows total balance, availability, current conversation cost, today's consumption, and the granted / topped-up balance.
- Current conversation cost (
当前对话费用): the host prices every assistant/message with the official DeepSeek price table (incl. peak/off-peak since 2026-08-17; pricing engine ported from dsh-web-billing, MIT) and reports the current session's accumulated cost via GET /api/deepseek-session-cost?sessionId=<id> — the whole conversation is replayed from its persisted log, so the figure includes history from before the plugin was installed. Hover the circled ⓘ next to the value to see the live formula with real numbers (输入/缓存命中/输出 tokens × 单价 = 小计, with the effective blended ¥/M rate).
- Auto-refreshes every 60 s (balance) / 5 s (conversation cost), plus a manual refresh button.
- Peak/off-peak indicator (
峰谷时段提示): shows whether the current time falls in DeepSeek's peak (高峰), off-peak (空闲), or flat (常规) pricing window (weekdays 09:00–12:00 / 14:00–18:00 Beijing time since 2026-08-17; weekends are off-peak all day), so you can tell when a run will cost more or less. Refreshes with the balance (60 s).
- Collapsible to a small wallet icon: click the chevron in the card header to collapse the card into a small wallet icon at the bottom-right (click to expand); in the collapsed state the icon is tinted by the current peak/off-peak state (peak = red, off-peak = green, flat = gray) or the error state, refreshed with the balance (60 s).
- Follows the app's light/dark theme (
--dsw-* tokens).
- Explicit error states: missing API key, network failure, provider errors.
- The API key never leaves your machine — the browser only talks to local routes that the host half registers.
Install
Requires pnpm.
# With the dsh CLI installed:
dsh plugin --profile web add dsh-deepseek-quota
# Without the dsh CLI installed (e.g. running via npx):
npx @deepseek-ai/dsh plugin --profile web add dsh-deepseek-quota
The package declares dsh.bundle, so dsh plugin automatically adds it to the profile's bundle layers (no manual patch editing). Then:
- Restart the web app:
dsh web (or npx @deepseek-ai/dsh web without the CLI; bundle layers are read at boot).
- Open http://127.0.0.1:3080 and refresh the page.
- The balance card appears at the bottom-right.
Manual alternative: install the package into the profile's node_modules and add a loader entry to ~/.dsh/profiles/web/cordis.patch.yml:
- insert:
- id: deepseek-quota
name: dsh-deepseek-quota
Configuration
The plugin reads the same API key the harness already uses: DEEPSEEK_API_KEY, resolved through the credentials service (set it on the Settings → Models page; it is stored in ~/.dsh/.credentials.yaml, or export it in the launching environment).
Today's consumption (今日已消费)
The official DeepSeek API exposes no usage query endpoint, so the widget uses two sources, in order:
-
Official (preferred) — the same date-filterable data the platform console shows. Configure the optional platform session token:
# get the token: log in to https://platform.deepseek.com, open DevTools → Console, run:
# JSON.parse(localStorage.getItem('userToken')).value
# then store it as a credential (e.g. add to ~/.dsh/.credentials.yaml):
# DEEPSEEK_PLATFORM_TOKEN: <token>
With the token set, the host queries platform.deepseek.com/api/v0/usage/cost?month=&year= and picks today's row. The card shows 今日已消费 ¥X.XX.
-
Estimate (fallback) — without the token, the host meters the balance (max(0, day-opening balance − current)), persisted under ~/.dsh/storages/deepseek-quota-day.json. The card shows 今日约消费 ≈¥X.XX so it is never mistaken for an official figure. Note the official usage page can also be filtered to "today" — the platform token unlocks that same data.
No other configuration needed.
How it works
| Part | File | What it does |
|---|
| Host half | lib/index.js | Cordis plugin (inject: credentials, webServer) registering GET /api/deepseek-balance (balance + today's consumption + the current peak/off-peak pricing period) and GET /api/deepseek-session-cost?sessionId=<id> (current conversation cost); subscribes session/event to price every assistant/message. |
| Pricing | lib/pricing.js | Official DeepSeek price-table engine (policy timeline + peak/off-peak, weekends off-peak all day), ported from dsh-web-billing (MIT). |
| Browser half | lib/client.js | dsh.client web bundle registering the widget into shell.overlay; polls balance every 60 s (incl. the peak/off-peak badge) and the current session's cost every 5 s. |
| Composition | cordis.patch.yml | The dsh.bundle patch layer that inserts the loader entry. |
Development
git clone <your-fork>
cd dsh-deepseek-quota
# edit lib/index.js (host) / lib/client.js (browser half)
# install locally and test:
dsh plugin --profile web add . # without the CLI: npx @deepseek-ai/dsh plugin --profile web add .
After changing lib/client.js, restart dsh web (or npx @deepseek-ai/dsh web) so the boot-graph hash (rev) regenerates, then hard-refresh the page.
License
MIT
