dsh-balance-monitor

English | 中文

A DeepSeek Harness plugin that monitors your DeepSeek API account balance: official /user/balance snapshots, in-session queries, Beijing-time peak/off-peak pricing status, and a native-style sidebar badge.

English

Features

Installation

# Option 1: install from npm (recommended)
# Web profile
dsh plugin --profile web add @rainronin/dsh-balance-monitor
# DSH Desktop profile (or run inside Desktop's own terminal without --profile)
dsh plugin --profile desktop add @rainronin/dsh-balance-monitor

# Option 2: install straight from GitHub
dsh plugin --profile web add github:Rainronin/dsh-balance-monitor
dsh plugin --profile desktop add github:Rainronin/dsh-balance-monitor

# Option 3: clone and link-install locally (instant reload while developing)
git clone https://github.com/Rainronin/dsh-balance-monitor.git
cd dsh-balance-monitor
dsh plugin --profile web add .
dsh plugin --profile desktop add .

# host-side changes require a restart
dsh web

> If pnpm blocks the prepare build script of a git-hosted plugin, add the
> printed key to allowBuilds in $DSH_HOME/profiles//pnpm-workspace.yaml
> and re-run.

The plugin joins dsh.profile.bundles automatically. Inspect the composed tree:

dsh --profile web --dump-config
dsh --profile desktop --dump-config

Usage

In-session query — just ask the agent:

查一下 DeepSeek 余额 / check my DeepSeek balance

Sidebar badge — at the sidebar footer next to Settings: 刷新 force-refreshes
past the cache; polling follows the host-configured interval (30s by default);
the collapsed (rail) state shows a single status lamp (green = 连接正常,
amber = degraded). The badge follows the dsh native theme. When a conversation is
selected, the badge also shows 本会话 ¥xx.xx — the estimated cumulative cost of
that conversation, calculated from official DeepSeek V4 peak/off-peak pricing;
switching conversations switches the cost automatically.

Configuration

Override in the profile's cordis.patch.yml:

- id: balance-monitor
config:
cacheTtlMs: 10000
pollIntervalMs: 10000

Error semantics

Peak/off-peak pricing status

The official pricing page defines peak hours as Beijing time 09:00-12:00 and
14:00-18:00; all other hours are off-peak. The new pricing takes effect at
2026-08-17 00:00 Beijing time. The host computes the current phase and the
badge shows:

Architecture

host half (Node)
BalanceRemoteService (service key `balance`; loader mounts the default-exported class)
├─ credential lookup → GET https://api.deepseek.com/user/balance → 30s TTL cache + serialization
├─ ds_balance tool + optional agent/pre-step injection + configurable polling
├─ peak/off-peak pricing state computed on Beijing time (09:00-12:00, 14:00-18:00 peak)
├─ balance/sessionCost: scans the selected session's event log and estimates cumulative
│   cost using official DeepSeek V4 peak/off-peak prices
└─ typert/typert-host.js: hand-written TYPERT strict manifest (exported as ./typert,
registered by typert-loader; api-gateway claims /api/balance/* via the strict definition)

browser half (client.tsx → lib/client.js, wrapped in the official __ModuleLoader__ shell)
├─ sidebar.footer.action slot: native-style badge (wide/rail states)
└─ data channel: direct calls over the official RPC protocol (POST /api/balance/,
client-request envelope), host-configured polling + `刷新` force refresh + phase-transition refresh

The third-party Typert Remote client path ($mount contribution → namespace
service) failed silently in practice, so the badge talks the official RPC wire
protocol directly (dsh-host-apiproxy fetch-carrier envelope), while the host
side keeps the official TYPERT strict registration.

Development

npm install            # toolchain (typescript/pnpm + type deps)
npm run build          # clean + tsc (host ESM/client CJS) + wrap-client + RPC/typert self-checks
node scripts/diagnose.mjs # local cordis integration diagnosis (mock services)
dsh plugin --profile web add .   # link install

Build notes: npm run build cleans lib/ first, compiles the host half as ESM
and the browser half as CommonJS, wraps the client with scripts/wrap-client.mjs into
the official window.__ModuleLoader__.load shell (same shape as official
dsh-client-ui-* artifacts, served by dsh-client-modules as
/plugins//client.js), then runs scripts/verify-client.mjs (bundle registration,
slot mounting, RPC envelope and rpcId echo) and scripts/verify-typert.mjs (strict
codec positive/negative cases).

中文

DeepSeek Harness 插件：DeepSeek API 账户余额监测——官方 /user/balance 接口快照 + 会话内查询 + 北京时间峰谷计价状态 + dsh 原生风格侧边栏徽章。

功能

安装

# 方式一：npm 直装（推荐）
# Web profile
dsh plugin --profile web add @rainronin/dsh-balance-monitor
# DSH Desktop profile（或在 Desktop 专用终端里直接 dsh plugin add，无需 --profile）
dsh plugin --profile desktop add @rainronin/dsh-balance-monitor

# 方式二：GitHub 直装
dsh plugin --profile web add github:Rainronin/dsh-balance-monitor
dsh plugin --profile desktop add github:Rainronin/dsh-balance-monitor

# 方式三：本地 clone 后 link 安装（改代码即时生效，适合二次开发）
git clone https://github.com/Rainronin/dsh-balance-monitor.git
cd dsh-balance-monitor
dsh plugin --profile web add .
dsh plugin --profile desktop add .

# host 半改动后重启生效
dsh web

> git 托管插件若被 pnpm 拦截 prepare 构建脚本，按提示把键加进
> $DSH_HOME/profiles//pnpm-workspace.yaml 的 allowBuilds 再重跑。

安装后插件自动进入 dsh.profile.bundles 层列表；检查配置树：

dsh --profile web --dump-config
dsh --profile desktop --dump-config

使用

会话内查询——直接让 agent 查：

帮我查一下 DeepSeek 余额

侧边栏徽章——侧边栏底部（Settings 旁）：刷新 按钮穿透缓存立即刷新；
轮询间隔跟随 host 配置（默认 30s）；折叠态（rail）显示单色状态灯（绿 = 连接正常，
琥珀 = 异常）。徽章跟随 dsh 原生主题。选中某个会话时，徽章还会显示 本会话 ¥xx.xx——
按 DeepSeek 官方 V4 峰谷价格估算的当前会话累计费用；切换会话时会自动跟随当前会话。

配置

覆盖示例（profile 的 cordis.patch.yml）：

- id: balance-monitor
config:
cacheTtlMs: 10000
pollIntervalMs: 10000

错误语义

峰谷计价状态

官方价格页定义高峰时段为北京时间 09:00-12:00、14:00-18:00，其余为空闲；
新计价于 2026-08-17 00:00 北京时间生效。host 计算当前阶段，徽章显示：

架构

host 半（Node）
BalanceRemoteService（服务键 balance，loader 行直接挂载 default 导出类）
├─ 凭证解析 → GET https://api.deepseek.com/user/balance → 30s TTL 缓存 + 串行化
├─ ds_balance 工具 + 可配置轮询（每轮注入为可选项，默认关闭）
├─ 峰谷计价状态：按北京时间 09:00-12:00、14:00-18:00 计算高峰
├─ balance/sessionCost：扫描所选会话事件日志，按官方 DeepSeek V4 峰谷价格估算累计费用
└─ typert/typert-host.js：手写 TYPERT strict 元数据（./typert 导出，typert-loader 注册，
api-gateway 按 strict 定义认领 /api/balance/* 端点）

browser 半（client.tsx → lib/client.js，__ModuleLoader__ 注册壳）
├─ sidebar.footer.action slot：dsh 原生风格徽章（wide/rail 双态）
└─ 数据通道：官方 RPC 公开协议直调（POST /api/balance/，
client-request 信封），host 配置轮询 + `刷新` 穿透刷新 + 阶段切换即时刷新

第三方 Typert Remote 客户端链路（$mount 贡献 → 命名空间服务）在本机环境实测
静默失效，故徽章改用官方 RPC 公开协议直调（dsh-host-apiproxy fetch carrier 信封），
host 端严格保留官方 TYPERT strict 注册路径。

开发

npm install            # 装工具链（typescript/pnpm，含类型依赖）
npm run build          # clean + tsc（host ESM/client CJS）+ wrap-client 包壳 + RPC/typert 自检
node scripts/diagnose.mjs # 本地 cordis 集成诊断（mock 服务验证工具注册与服务可见性）
dsh plugin --profile web add .   # link 安装

构建说明：npm run build 先清空 lib/，host 半编译为 ESM、browser 半编译为
CommonJS，再经 scripts/wrap-client.mjs 包进官方 window.__ModuleLoader__.load 注册壳
（与官方 dsh-client-ui-* 产物同构，由 dsh-client-modules 服务为
/plugins//client.js）；随后 scripts/verify-client.mjs 验证 bundle 注册、slot
挂载、RPC 信封与 rpcId 回显，scripts/verify-typert.mjs 验证 strict codec 正反例。