前言¶

用 DeepSeek API 做开发时，有三个问题经常需要停下来确认：账户还剩多少钱、现在是不是半价时段、刚才那次调用扣了多少。余额要靠接口单独查询，峰谷计价又让成本随时段浮动，纯靠切换页面和心算并不现实。

DSH 的 Web 界面右下角有鲸鱼挂件可以看余额（数据与官方接口同源），但如果你希望在写代码的同时，把双币种余额、峰谷状态和每次扣款都放在视线里，deepseek-balance-banner 把这些做成了页面顶部的一条横幅。下面介绍它的功能、安装和日常使用。

这是什么¶

deepseek-balance-banner 是 DeepSeek Harness（DSH）Web 界面的一个社区插件，作者是 iskshadow195563，采用 MIT 许可证。它是一个标准的 DSH bundle 包，安装后在页面顶部右侧、主题切换（白昼/夜间）按钮的左侧，同时显示 USD 与 CNY 两个余额胶囊，负值高亮，每 60 秒自动刷新。

插件由社区独立开发，与 DeepSeek 官方无隶属关系。

核心功能¶

双币种余额与负值高亮¶

插件调用官方 GET /user/balance，解析返回的全部 balance_infos，USD 与 CNY 各渲染一个胶囊。任一币种余额小于 0 时以警告色高亮，欠费一眼可见。

扣款与充值动画¶

检测到扣款时，从余额胶囊旁弹出红色游戏化扣血飘字（如 -¥0.03），上浮、放大、渐隐；充值或入账时弹出绿色正向飘字（如 +¥0.05）。悬停横幅可以查看本次页面会话的扣款总额与充值总额。

峰谷时段识别¶

徽章实时显示当前处于高峰（标准价）还是低谷（半价），并附当前北京时间；周六、周日全天自动显示为低谷价。时段规则依据 DeepSeek 官方 2026-08-23 生效的计价规则。

刷新机制¶

每 60 秒自动刷新；点击任意胶囊可以立即手动刷新。宿主侧另有 25 秒 TTL 缓存，避免请求过于频繁地打到官方接口。

演示模式与主题适配¶

样式使用 DSH 主题变量（--dsw-*），深色、浅色皮肤均协调。页面 URL 加 ?dsb-demo=1 会循环播放扣血/充值动画，用于开发或预览。

安装与启用¶

前置条件¶

1、dsh >= 0.1.0-rc.6，推荐 0.1.1-rc.2+；
2、已在 DSH 凭据中配置 DEEPSEEK_API_KEY（用于请求 GET https://api.deepseek.com/user/balance）；
3、存在 Web Profile 目录 $DSH_HOME/profiles/web/（Windows 默认 %USERPROFILE%\.dsh\profiles\web\）。

一条命令安装¶

# 从 npm 安装
dsh plugin --profile web add deepseek-balance-banner

# 或从 GitHub 直装（不需要 npm 账号）
dsh plugin --profile web add github:iskshadow195563/DeepSeek_Harness_Balance_Banner#v1.0.0

--profile 为必填参数，web 是默认的 Web 界面 profile，如果使用其他 profile 名请替换。安装完成后插件加入该 Profile 的 bundle 层，重启 dsh web 并 F5 刷新页面即可生效。

手动安装¶

不想走包管理时，可以把 deepseek-balance-banner.mjs 放进 Web profile 目录：

# macOS / Linux
cp deepseek-balance-banner.mjs "${DSH_HOME:-$HOME/.dsh}/profiles/web/"

# Windows PowerShell
Copy-Item deepseek-balance-banner.mjs "$env:USERPROFILE\.dsh\profiles\web\"

再编辑同目录的 cordis.patch.yml，追加 insert 条目：

- insert:
    - id: deepseek-balance-banner
      name: ./deepseek-balance-banner.mjs?v=1

?v=1 用于破浏览器 ESM 缓存，插件升级时把数字加一。保存后通常热生效，若 5 秒内没反应，重启 dsh web 并 F5 刷新页面。

注意：同一插件不要以包形态和文件形态重复安装。卸载包形态使用：

dsh plugin --profile web remove deepseek-balance-banner

文件形态安装则删除 .mjs 文件，并移除 cordis.patch.yml 中对应的 insert 两行，刷新页面。

日常使用与排查¶

• 查看余额：顶部右侧胶囊同时显示 ¥ 人民币与 $ USD，负值以警告色高亮；
• 手动刷新：点击任意胶囊，或等 60 秒自动刷新；
• 数据来源：官方 GET /user/balance，与 DSH 右下角鲸鱼挂件同源；
• 演示模式：页面 URL 加 ?dsb-demo=1。

两种常见情况：胶囊一直显示 — 或加载中，先检查 DEEPSEEK_API_KEY 是否已在 DSH 凭据中配置；只显示一个币种，通常是你的账号只返回了一种币种。

工作原理与安全设计¶

数据链路如下：

浏览器页面 ──(同源 fetch)──> 本机 dsh web(/dsb-balance.json)
                                    │ ctx.credentials 解析 DEEPSEEK_API_KEY(不落页面)
                                    ▼
                     https://api.deepseek.com/user/balance  (balance_infos: USD + CNY)

宿主插件把余额端点挂在本机 dsh web 上，页面脚本以 60 秒轮询访问，宿主侧用 25 秒 TTL 缓存合并请求。整个流程是只读的，没有任何写操作；插件本身不包含密钥，DEEPSEEK_API_KEY 由 DSH 凭据服务在宿主进程内解析，页面只与本机 dsh web 同源通信，不跨域、不落 Key。

适用场景与注意事项¶

插件适合长期开着 DSH Web 界面、希望随时掌握余额、峰谷价和单次扣款的使用者。安装前有几点建议：

1、插件以当前 dsh 进程的权限运行，安装前先阅读源码仓库，确认代码行为符合预期；
2、确认许可证（本项目为 MIT）与你的使用方式一致；
3、如果你自行维护插件版本，每次发布记得把安装补丁里的 ?v= 数字加一，避免浏览器缓存旧脚本。

小结¶

deepseek-balance-banner 把余额查询、峰谷计价提示和扣款反馈压缩成页面顶部的一条横幅，是 DSH「一切皆插件」思路下一个典型的小而完整的能力补充。项目主页与社区目录如下：

• GitHub：https://github.com/iskshadow195563/DeepSeek_Harness_Balance_Banner
• 社区插件目录：https://www.skillhub.cn/plugins/iskshadow195563/DeepSeek_Harness_Balance_Banner （社区独立站点，与 DeepSeek / 幻方无官方从属关系）