dsh-ds-balance

[!NOTE] 余额读自 DeepSeek 官方接口，不是估算。凭据只经 DSH 的凭据通道解析：API Key 不会出现在设置文件里，也不会返回给界面。

余额要有地方看，但不该占地方。左边栏底部一个常驻的状态环，点开是三段金额与数据新鲜度；要改配置，进侧边栏插件（Plugins）页里本插件的详情页。

常驻左边栏底部，与「使用统计」「设置」并排；点开是余额、赠送 / 充值拆分与数据新鲜度。

一眼看懂那个环

那个环是「现在是什么情况」，一眼能分出五种，各自对应你该做的事：

鼠标停上去，它会告诉你这一格现在什么意思（收起态那 56px 轨道、展开态带名字的条目， 停上去显示的是同一句话）：

• 数字可信时（正常 / 偏低 / 告急）—— 直接显示金额；
• 其余情况 —— 显示这个处境自己的话：「正在获取」「读不到余额」「服务异常」 「尚未配置凭据」「账户不可用」「数据已过期」「暂无余额」。

账户停用与数据过期虽然手里有数字，也不显示那个数字： 停用的账户、过期的快照，报出来的数只会误导（「我有 ¥0」/「我有 ¥110」）。 环已经把问题画出来了（红叉 / 旧色），悬停该做的是解释问题。

两种「看不到」分得开：没接入提示你去配凭据；接入了但读不到说「读不到余额」 （不写「暂时」—— 有些原因等一下就好，有些得你去改凭据，说「暂时」会把人劝去干等）。 那个叉既表示「读不到」，也表示「读到了但这个账户不能用」—— 两者都是「这里没有可用的数字」，都要你去查。

界面一览

三种界面的分工是死的：圆环回答「大概还剩多少」，浮层回答「具体是多少」，卡片回答「怎么算」。

卡片就是这四组：默认四组全收起，点组头逐组展开；组里有填错的项时那一组会自己展开。

能力

• 左边栏底部常驻一个状态环加名称，点开看明细；收起与展开是同一个环，位置不变。
• 余额按设定的周期自动刷新，界面读的是缓存 —— 开着界面不会反复去打上游接口。
• 浮层给出总额、赠送 / 充值拆分、数据是多久之前的，以及一个带冷却的手动刷新；标题那行「鲸鱼图标 + DeepSeek 余额」本身是外链，点开是新标签页里的官网用量页。
• 多币种：显示哪个币种由账户决定；设置里选的币种账户里没有时，浮层会说明并给「改用实际币种」——点它直接写进设置，设置页那一格跟着变；宿主不可写时按钮置灰。
• 设置卡片分四组、默认全收起、点组头展开；组里有填错的项时，那一组会自己展开。
• 凭据默认继承官方模型页配好的那一份，不必重填；徽标只报「已配置密钥。/ 未配置密钥。」（官方卡片同款）， 只读时不给编辑，并说明原因。
• 颜色只表达状态（正常 / 偏低 / 告急），与金额大小无关；读法与理由见「圆环怎么读」。
• 插件页里以本地化名字出现：中文界面是「DeepSeek 余额」，英文界面是「DeepSeek Balance」—— 卡片与详情页的标题、那句话说明都跟随界面语言，图标就是左边栏那个环（橙色弧环，画的是「用了七成」那一档）； 详情页仍会把包名 dsh-ds-balance 单独写出来。

安装

前置

• DSH：版本范围以 package.json 的声明为准，本插件跟的是宿主当前那条 RC 线（dist-tag 是 next）。
• Node：>= 20（同一处声明）。

装宿主时要显式点名版本线：@deepseek-ai/dsh 的 alpha 与 latest 都不是我们声明的那条线 —— 按默认方式装会落在声明范围之外。

npm install -g @deepseek-ai/dsh@next      # 本插件承诺支持的线（RC 线；npm 上没有 rc 这个 tag）

兼容性怎么保证、哪条线该跟，见版本兼容。

从 npm 安装

dsh plugin --profile web add dsh-ds-balance

装完重启 dsh --profile web 生效。

从源码安装

git clone https://github.com/zlZayn/dsh-ds-balance.git
cd dsh-ds-balance
npm install && npm run build

dsh plugin --profile web add "$PWD"

与 npm 那条路一样，重启后生效。

发现与安装

• npm：dsh-ds-balance
• GitHub：zlZayn/dsh-ds-balance

仓库带有 GitHub topic dsh-plugin，插件市场据此自动发现插件。

版本兼容

• 需要哪一版宿主：以 package.json 的声明为准，本插件跟的是宿主当前那条 RC 线。 需要配置界面，就把宿主升到那一版或更高：npm install -g @deepseek-ai/dsh@next。
• 声明是「窄」的：下限是我们实测过的那一版，用 >= 而不设上限 —— 不承诺「以后都兼容」。 （它罩得住同一 major.minor.patch 内后续的预发布版本；宿主换一个补丁位再推预发布， 这条下限就罩不住了，届时要再抬一次。为什么见兼容性。）
• 下限为什么抬上去：不是换了界面位置，而是设置接缝换过（旧宿主上没有本插件依赖的那两样东西， 浏览器半边会整个不渲染 —— 圆环与浮层也一起消失）。插件不查宿主版本号，而是当场探测那个能力； 拿不到时浮层里会多一行英文提示，说明配置界面为什么不可用、该往哪儿升级。 技术细节见 配置表单的能力探测。
• 兼容性不是推断出来的：每周由 compat.yml 在 next（RC 线）上 换包实跑一遍现有测试，另有一步单独判声明面罩不罩得住；红了会开或更新一条固定标题的跟踪 issue。 当前结论与红了怎么办见 兼容性。

配置

打开侧边栏 插件（Plugins） →「已安装（Installed）」组 → 点进 DeepSeek 余额（英文界面下是 DeepSeek Balance）的详情页 —— 配置区就在描述下面，直接可改（那一行上没有第二个 Configure 步骤）；四组默认全收起，点组头逐组展开：

Plugins 页列表里的位置：「DeepSeek 余额」与其他已安装插件并排；点它的插件名进详情页，上面那张配置表单就在描述下面。

• 连接：API 地址与凭据，两项都默认留空 —— 地址留空即用 DeepSeek 官方端点，凭据继承官方模型页那一份、只读不可改； 二级「自定义设置」里只放凭据引用名。
• 展示：金额用哪种币种，或让它自动跟随账户。
• 阈值：每个币种两档提醒线（预警 / 告急）。同一币种内告急必须严格低于预警，相等也会被拒绝 （保存时就会拦下来）；但手改配置文件写成的非法组合不会再报错 —— 插件读到的那一刻会把这一对回落成默认值并在日志里记一次。

升级提示：设置项存在插件那一行的配置里，键名跟着宿主升级变过一次，旧值不会自动迁移 —— 升级后请照上表重填一次。

• 刷新：服务端刷新周期、界面轮询周期与手动刷新冷却。冷却从刷完那一刻起算， 浮层上的秒数就是真实剩余；后端说这次没触发，界面按它给的剩余时间收尾，不假装刷过。

保存即生效，不必重启 DSH。

圆环怎么读

• 环里填多少 = 当前余额占该币种预警线的比例，100% 封顶；告急线不参与画环 —— 它已经决定了颜色。
• 颜色只表达状态，与金额大小无关：正常、偏低、告急各一色；账户读不到时另画一个带叉号的环。
• 没配阈值的币种退回按状态定性：正常画满环，偏低 3/4，告急 1/4。 （只有有余额可看的那一族画弧 —— 上面三档，加上「数据已过期」时的那份旧数字； 账户读不到、账户停用、没接入、账户没钱这些都不画弧，环靠颜色与中心记号说话。）
• 为什么颜色不由金额算、阈值为什么只当刻度 → 数据流。

凭据

密钥只经 DSH 的凭据通道解析，卡片里的 API Key 一栏默认继承官方模型页配好的那一份，且只读不可改。 由启动环境（环境变量）提供时，字段只读，徽标写明来源。

余额有两条官方取数路，插件自己选：模型页 / 环境变量配的 API Key 一条，DSH 账号登录一条 （只登录、没配 Key 也能看到余额）。选择顺序是：

• 当前会话在用的那条 —— 切会话、换模型都跟着换；
• 读不到会话就按全局默认模型的路由；
• 都判不出来时 Key 优先、账号兜底；
• 两条都没有，才是「尚未配置凭据」。

浮层标题右边那个括号就是这份数字的来源：（API Key） / （账号登录）。显示哪个、刷新就刷哪个、标签也写哪个 —— 三者始终同一条。

这个插件只记官方的那一个数字，所以首选那条读不到时会自动退到另一条官方路：只要账号或 API Key 有一个能用，就照常显示（哪怕是一份稍旧的快照）。两条路都拿不到数字，才会提示 —— 那才是真的没接入官方。左栏那个环这时长什么样，见一眼看懂那个环。

换了 key 多久生效，跟着 DSH 的层走 —— 本插件不额外追：

• 启动环境（环境变量）给的 key：改了要重启 DSH。 进程的环境在它启动那一刻就定死了，之后再改外面那个变量，跑着的插件看不到。
• 在官方模型页 / 凭据库换的 key：不必重启，最迟下一个服务端刷新周期生效（连续失败退避期间会更久）；想立刻看到就点浮层里的手动刷新（它带冷却）。
• 生效之前，界面显示的还是旧账本的数字 —— 账本标识按 key 派生，新旧不会混，但内存里那份要等下一次抓取成功才被换掉。

为什么这么定 → 关键决策。

安全与边界

• API Key 永不返回界面：配置接口只回一个固定长度的掩码串，连末几位也不给。
• 密钥不落日志、不落本插件的文件；设置文件里只有引用名，卡片可以安全截图或分享。
• 余额快照存在 DSH 自己的数据目录里，按凭据派生出的标识分组 —— 换 key 自动开新账本，旧快照不会被混用。
• 那份标识还要 DSH home 目录下一个随机盐文件参与派生；它丢了，旧快照就读不回来（不会串到别人账上）。
• 只访问 api.deepseek.com，不代理、不转发其他流量。

许可

MIT。

贡献

外部贡献入口（报 bug 带什么、提功能前先翻什么、提 PR 前做什么）→ CONTRIBUTING.md。

设计取向与实现约束 → docs/ARCHITECTURE.md；发布流程与版本号判定 → docs/PUBLISHING.md；维护者文档地图 → AGENTS.md。