LemCAE/dsh-balance

English | 中文

deepseek-harness（dsh）的组合插件（Host + Web Client 双半）： 查询 DeepSeek 开放平台账户余额，并估算当前会话的消耗金额。通过 dsh plugin add 安装。

功能

• 余额查询：调用官方 GET https://api.deepseek.com/user/balance，复用 harness 自身的 DEEPSEEK_API_KEY 凭据（与 Models 页同一把）。密钥只经有界 node 子进程的 stdin 传递， 不进入命令行、日志或任何输出。
• 当前会话消耗估算：从会话日志折叠 provider 上报的 token 用量（未命中输入 / 缓存命中 / 输出）， 按官方价目表逐步骤计价（按北京时间峰谷价，高峰 9-12 / 14-18，其余为「空闲」）。 仅为估算，以官方账单为准。
• 顶栏徽章（会话头部）：余额 ¥x | 会话 ≈¥y，点击刷新；悬停 500ms 显示明细气泡 （按钮正下方、水平居中、视口边缘自动夹紧）。
• 设置页（设置 → DeepSeek 余额）：余额明细、自动刷新开关、自动刷新间隔下拉 （15 秒 … 5 分钟或自定义）、界面语言下拉（跟随主界面 / 中文 / English）、可编辑价目表 （空闲 / 高峰 × 模型）。改动持久化于设置文档，重启不丢。
• 模型工具：deepseek_balance——余额 + 调用方会话的预估消耗。
• 暂停自动查询：连续 2 个刷新周期无新对话（user/assistant 消息）后暂停自动查询 （转为 5 分钟低频探测）；出现新对话后自动恢复活跃刷新。自动刷新也可手动开关 （设置页开关或 /dsh-balance auto-refresh <on|off>），关闭后不再发起查询。
• 完全自包含：部署无需修改宿主仓库任何代码（通信走内置 commands Remote 命名空间）。

安装

标准方式（bundle 安装，推荐）：

dsh plugin --profile web add @lemcae/dsh-balance

安装器把包加入 web profile 的依赖与 bundle 列表；重启 dsh web 后，loader 自动应用包内 cordis.patch.yml 完成插件挂载。验证：

• 打开任意会话 → 顶栏出现 余额 ¥x | 会话 ≈¥y 徽章，悬停显示明细；
• 设置 → DeepSeek 余额 → 完整卡片（余额、间隔、界面语言、价目表）；
• 让模型调用 deepseek_balance 工具。

手动安装（同一机制，不经过插件安装器）：编辑 $DSH_HOME/profiles/web/package.json， 在 dependencies 加 "@lemcae/dsh-balance": "<最新版本>"（以 npm 为准），在 dsh.profile.bundles 数组加 "@lemcae/dsh-balance"，然后在该目录执行 pnpm install 并重启。

Peer 依赖为官方 @deepseek-ai/* 包（^0.1.0-rc.5 线，兼容 rc.5 与 rc.6；@deepseek-ai/cordis ^4.0.1） 与 react，由宿主提供。

使用

• 徽章：显示 余额 ¥x | 会话 ≈¥y；点击刷新；悬停查看明细（构成、模型、更新于、刷新节奏/空闲提示）。
• 设置页：余额行、「自动刷新开关」、「自动刷新间隔」（15 秒 … 5 分钟或自定义）、「界面语言」（跟随主界面 / 中文 / English）、价目表编辑（「保存」持久化）、切换时刻提示。
• 命令（命令面板也可用）：/dsh-balance [refresh | interval <毫秒> | prices <JSON> | language <auto|zh-CN|en> | auto-refresh <on|off>]。
• 工具：deepseek_balance（无参数）。

配置

settings 命名空间 dsh-balance：

字段	默认	含义
autoRefresh	true	是否启用自动刷新（/dsh-balance auto-refresh on|off）
refreshIntervalMs	30000	活跃时自动刷新间隔（5000–600000 毫秒）
language	auto	插件界面语言：auto（跟随主界面）、zh-CN 或 en
prices	见源码	{ models: { deepseek-v4-flash, deepseek-v4-pro, default } }，每模型 { offPeak, peak }，单位：元 / 百万 tokens

计价按北京时间峰谷价：高峰 9-12、14-18 用 peak，其余用 offPeak。

已知限制和延后工作

• 估算与账单的差异：消耗基于本机会话日志计算，可能与官方账单不一致（平台侧缓存策略、 未记录请求、模型改名、价格变动等）。可在设置页更新价目表。
• 未知模型按 default（v4-flash）计价。
• 子代理（subagent）有独立 sessionId，不纳入本会话估算。
• 压缩（compaction）：会话压缩会重写事件 seq，增量折叠可能停留在压缩前的合计（估算场景可接受）。
• 日志噪声：每次自动刷新都会执行一次斜杠命令，向会话日志追加 command/run 与 command/done 两条事件；暂停自动查询可大幅减少。
• 暂停恢复延迟：暂停期间客户端每 PAUSED_REFRESH_MS（5 分钟）探测一次；新对话出现后 会在下一次探测时恢复活跃刷新，恢复最长延迟该间隔。
• 余额缓存 10 秒；同一周期内工具与界面共享一次 API 调用。

模型体验

请求上下文与条件

模型读取

工具 deepseek_balance 的 schema（零参数）与描述：声明使用 harness 凭据查询官方余额端点， 并返回当前会话的消耗估算。

Token 开销

无固定 token 开销；结果为数据相关载荷（余额、消耗、价目表、空闲状态）。

KV 缓存影响

前缀稳定：工具名、描述与 schema 恒定，结果随调用变化，不影响前缀复用。