dsh-balance-meter

一句话定位

在 DSH Web 界面的输入框旁边显示 DeepSeek 账户余额和当前会话估算花费，按你实际调用的模型（flash/pro）自动按官方单价计价，并支持官方 API、中转接口、本地记账三种余额来源。

核心能力

• 在输入框下方的状态条显示余额 + 本场会话花费 chip，点击展开按币种、按 token 分桶的明细
• 调用 DeepSeek 官方的 "获取用户余额" 接口读取真实账户余额（赠送 + 充值）
• 自动从每个会话的请求头识别本次对话用的是 flash 还是 pro 模型，按对应官方单价核算花费
• 每 6 小时自动抓取一次官方价格页，价格调整和 2026-08-17 的峰谷定价上线都无需更新插件
• 支持三种余额来源：DeepSeek 官方 API、第三方中转兼容端点（API Key 留在本地仅作 Bearer 凭据）、本地手工记账（适用于无余额接口的场景）
• 在插件设置面板可切换来源、调整余额查询间隔、修改本地余额基线

技术实现

• 语言: TypeScript（含 React 18 + TSX 客户端）
• 关键依赖: @deepseek-ai/cordis（DSH 的插件运行时/DI 容器）、@deepseek-ai/dsh-credentials（凭据通道）、@deepseek-ai/dsh-settings（设置面板 schema）、@deepseek-ai/schemastery（配置 schema）
• 架构模式: 双端插件——主机侧把 BalanceService 注册成 cordis 服务并挂载 /api/balance 等 HTTP 路由；浏览器侧把一个 React 组件注册到 DSH 的 conversation.composer.dock 槽位里，每 30 秒轮询主机接口
• 入口文件: 主机侧 src/index.ts，浏览器侧 src/client/index.ts

适用场景

经常用 DSH 跑 DeepSeek 对话、希望随时知道"还剩多少钱、本场花多少"的用户；用第三方中转 API 但还想看到账户余额（plugin 会按你指定的中转路径解析数字余额并明确标注为"中转"）；以及没有余额接口、只能自己在设置面板里维护当前余额基线的场景。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:Ghost011118/dsh-balance-meter

安装后重启 dsh web 并刷新浏览器页面。

配置项

插件默认零配置即可工作。如下设置可在 DSH 设置面板中调整，也可以在 cordis.patch.yml 的组合配置里覆盖：

常见问题

Q: 安装后在哪里看到余额 chip？

A: 重启 dsh web 并刷新页面后，输入框下方的状态条会出现一个 "余额 CNY x.xx · 本场 CNY y.yy" 的按钮。点击展开可以看按币种（赠送 + 充值）和按 token 分桶（输入 / 缓存读 / 输出）的明细。

Q: 显示 "no API key for provider route deepseek-official" 怎么办？

A: 宿主从 DSH 凭据存储（~/.dsh/.credentials.yaml）读取 DeepSeek API Key——也就是 Web 上 Models 页面写入的那个 Key。在凭据文件里加上 DEEPSEEK_API_KEY: sk-... 即可，DSH 运行中编辑也能热重载；plugin 的余额查询与 LLM 路由都走同一套凭据通道。

Q: 余额卡在 "不可用"，必须点击才能刷新吗？

A: 不需要。该问题在新版本中已修复：错误视图不会被当作新鲜缓存复用，每次 30 秒轮询都会重新查询 provider，所以只要底层条件恢复（余额可达、网络恢复、Key 已写入），chip 会自己恢复正常显示。

Q: 我用第三方中转 API，怎么显示余额？

A: 在插件设置里把"余额来源"切换为"中转"。DeepSeek 兼容格式的中转可直接返回 balance_infos；其他格式需要填写"中转余额字段路径"（如 data.balance）。plugin 会明确把中转来源标为"中转"，绝不会伪装成官方余额。API Key 始终留在 DSH 主机，只作为 Bearer 凭据发往中转端点。

Q: manual 模式的数据存在哪里？安全吗？

A: 账本存在 DSH settings 命名空间下的 balance.manualLedger 字段里，标记为隐藏的密钥字段——不另建明文文件，也不会随普通余额响应发给浏览器。账本记录基线、剩余余额、本地累计扣费、以及每个会话的累计 token 检查点。

Q: 重启 DSH 或者插件会重复扣费吗？

A: 不会。manual 模式只扣除"上次成功持久化的 token 检查点"之后的正向 token 增量——轮询和重启都不会对同一份累计会话消耗重复扣费。

Q: 缓存写入（cache write）token 会扣费吗？

A: 不会。DeepSeek 不对缓存写入单独计费，plugin 默认按 0 元/百万 tokens 计算。

Q: 2026-08-17 的峰谷定价会自动切换吗？

A: 会。plugin 每 6 小时抓取一次官方价格页，解析当前单价和峰/闲两套单价；2026-08-17 之后按当前北京时间（09:00-12:00、14:00-18:00 高峰，其余闲时）自动按对应单价核算。该日期之前即使页面已列出峰谷表，也仍按当前单一价格计价。

上手难度

入门 — 零配置即可用，余额来源、API Key、刷新间隔都能在 Web 设置面板里点选；唯一需要前置准备的是在 Web 的 Models 页面写入 DeepSeek API Key。

已知问题与限制

• API Key 解析按"凭据通道 → 启动环境变量 → process.env"的顺序回退。当凭据 seam 已挂载时，仅 export DEEPSEEK_API_KEY 不会生效（seam 优先级更高）
• 中转模式必须显式配置"中转余额字段路径"才能识别数字余额；中转响应若不包含 DeepSeek 兼容的 balance_infos，未配置字段路径时会显示"中转余额错误"
• manual 模式要求部署有可写的 DSH settings provider，否则无法持久化本地账本
• 计价模式设为 auto 时，如果某会话还没有产生过任何请求头，plugin 会回退到 flash 单价
• cacheWriteTokens 默认按 0 计费，不支持单独开启（DeepSeek 官方不单独对缓存写入计费）

English | 中文

DeepSeek account balance and session-cost readout for the DeepSeek Harness (DSH) Web GUI.

• Explicit balance sources: official API, proxy-compatible endpoint, or a manual balance accounted and persisted locally
• Current session estimated spend (token usage x official pricing)
• Per-model pricing: reads the model actually driving each session from its request header (flash vs pro), so the cost tracks the model you used instead of a fixed default
• Auto-fetches the official pricing page every 6h, so price changes and the 2026-08-17 peak/off-peak pricing rollout never require a plugin update
• Peak-hour band (Beijing 09:00-12:00 / 14:00-18:00) applied automatically once the peak pricing goes live

Features

The composer dock shows a chip with the account total balance and the current session's estimated cost:

Balance CNY 4.16 · This session CNY 2.57

Clicking the chip reveals the per-currency balance breakdown (granted + top-up) and the per-bucket cost breakdown (input / cache read / output). Clicking while an error is shown forces an immediate refresh.

Requirements

• DeepSeek Harness 0.1.0-rc.6 or newer (web profile)
• A DeepSeek API key stored through the DSH credentials seam (DEEPSEEK_API_KEY — the web Models page writes it)

Installation

From a git URL (no npm account needed):

dsh plugin --profile web add https://github.com/Ghost011118/dsh-balance-meter

Or from a local checkout:

git clone https://github.com/Ghost011118/dsh-balance-meter.git
dsh plugin --profile web add link:$(pwd)/dsh-balance-meter

Restart dsh web, then refresh the page. The balance chip appears in the composer dock next to the conversation stats line.

Configuration

The plugin is zero-config by default (uses DEEPSEEK_API_KEY and the official pricing page). Optional composition settings:

- insert:
    - id: balance
      name: 'dsh-balance-meter'
      config:
        source: official    # official (default) | proxy | manual
        model: auto         # 'auto' (default) | 'flash' | 'pro'
        pricingRefreshHours: 6

Proxy and manual modes

proxy mode keeps the API key on the DSH host and sends it only as a Bearer credential to the configured endpoint. A DeepSeek-compatible relay may return balance_infos directly. Other relays must configure proxyBalancePath; a missing or non-numeric value is reported as a proxy error and is never labelled as an official balance.

manual mode requires a writable DSH settings provider. The hidden ledger is stored inside the existing balance settings namespace, not in a separate plaintext file and never in the browser response. It records a baseline, remaining amount, locally charged spend, and per-session cumulative-token checkpoints. Only positive token deltas after the last persisted checkpoint are charged, so polling or restarting DSH cannot deduct the same cumulative session usage twice. Changing manualBalance or manualCurrency intentionally creates a new baseline and checkpoints all currently live sessions.

How the cost is estimated

The plugin reads DSH's durable tokenUsage projection (the same accounting the built-in stats line uses) and converts the four buckets — uncached input, cache read, cache write, output — to money using prices parsed from the official pricing page. Cache-write tokens are not billed separately by DeepSeek and default to 0.

For the price set, in auto mode (the default) it uses the model actually driving the session: each session's request header records the provider/model of the most recent request, and the plugin maps that id (deepseek-v4-flash → flash, deepseek-v4-pro → pro) to the matching per-million prices. A session is therefore priced at whatever model produced its usage, not a hard-coded flash. When no header exists yet or the model id is unrecognized, auto falls back to flash. Setting model: flash or model: pro explicitly forces that preset and ignores auto-detection, so you can pin the estimate to one model when you want to.

Before the 2026-08-17 peak-pricing rollout the current single prices stay authoritative; after it, the peak/off-peak band for the current Beijing hour is applied. If the pricing page cannot be fetched, built-in presets (flash: 0.02 / 1 / 2 CNY per 1M) are used. Explicit cost.* overrides in the composition config take precedence over any preset. The cost JSON also reports pricingKey and model so the chip can show which model was priced.

Troubleshooting

"no API key for provider route `deepseek-official`"

The host reads your key from the DSH credentials store — the file <harness home>/.credentials.yaml (default ~/.dsh/.credentials.yaml), the same store the web Models page writes. This plugin's balance query and the LLM route resolve through that same seam.

• If this error appears, make sure the document contains DEEPSEEK_API_KEY: sk-... (a strict mapping of reference to non-empty string). Editing it while DSH runs is fine — the provider hot-reloads and re-reads the file.
• When a credentials seam is mounted, both the LLM route and this plugin read the key only from the credential store; a plain export DEEPSEEK_API_KEY is ignored in that case. Exporting still helps for the plugin's own fallback when no seam is present.
• Prefer running dsh web through a single supervised instance (e.g. dsh-autostart) instead of launching several ad-hoc npx dsh web processes that can race on the same port and settle different credential snapshots. If you encounter this right after killing a manual instance, confirm the other (still-supervised) instance read the key — the balance chip recovering to a live total means the key resolved.
• The error is transient-friendly: the balance chip auto-recovers, because an error state is never cached as fresh — the next poll re-queries the provider.

Balance stuck on "unavailable" and only updates on click

An error/unavailable snapshot used to be served from the cache until it aged out, so a transient failure could hold the chip on "unavailable" until you clicked to force a refresh. Now an erroneous view is never reused as a fresh cache: every poll re-queries the provider, so the chip recovers on its own as soon as the underlying condition clears (balance reachable, network back, key stored).

License

BSD-3-Clause. Copyright (c) 2026, Ghost011118.