前言¶
用 DeepSeek Harness（DSH）跑 web profile 时，账户余额和官方文档里的峰谷计价规则往往不在同一屏里；会话多了之后，也很难从界面直接看出「这一 workspace 大概花了多少」。社区插件 dsh-balance（维护者 zz0-0）把余额查询、当前计价窗口和按会话/工作区的费用估算接到 DSH 页面上，数据走本地 DSH 服务，API Key 不注入浏览器。
这是什么¶
dsh-balance 是面向 DeepSeek Harness web profile 的联网类插件：在窗口右下角展示实时账户余额与当前高峰/谷价窗口，并从 session 日志汇总每条对话、每个 workspace 的费用估算。插件通过 GitHub 仓库 zz0-0/dsh-balance 分发；社区目录页见 skillhub.cn/plugins/zz0-0/dsh-balance（独立站点，与 DeepSeek / 幻方无官方从属关系）。当前 package 版本为 0.1.0，许可证 MIT。
核心功能¶
余额卡片与详情面板¶
卡片固定在窗口右下角，与 composer 独立：显示总余额、当前窗口（谷价 / 高峰）、距下次切换的剩余时间，以及本地时区的切换时刻。在无对话的 hero 屏也会留在窗口底部；当 composer 或单会话状态行占到底角时，卡片会上移，避免挡住其他信息。
点击卡片打开菜单式详情面板，内容包括：账户余额 / 充值 / 赠送额度、本地与北京时间的下次切换、当前本地/北京时间、高峰时段说明、价目表来源与更新时间、账本路径、刷新按钮。赠送额度行始终显示（无赠送时为 0）；若仍有赠送余额，该行链到 DeepSeek Billing 查看过期信息。面板支持点击外部或 Esc 关闭。
侧边栏费用估算¶
侧边栏在每条对话行显示 ≈¥…（或 USD 账户下的 $）估算，workspace 行显示其下对话合计。悬停 badge 可看 token 与已记录估算。composer 状态行刻意不再放置费用标签，避免与对话行重复挤占空间。
动态价目与峰谷规则¶
价目与高峰窗口不是写死在插件里：启动时以及缓存超过六小时时，会从官方文档页拉取 CNY / USD 价表并解析模型列、缓存命中/未命中/输出单价，以及中文页脚注中的高峰时段。解析失败时保留旧缓存，详情里标记为 缓存/默认。
高峰默认为北京工作日 09:00–12:00、14:00–18:00；周末恒为谷价（自 2026-08-23 起文档所述规则）。工作日若为中国法定节假日则按谷价；调休形成的「周末」仍按周末处理。节假日数据来自 https://api.apihubs.cn/holiday/get?year=YYYY&size=500（当年与次年），缓存 30 天。
账本与计价原则¶
本地账本路径为 ~/.dsh/.dsh-balance-costs.json（或 $DSH_HOME 下同名文件）。每条 session 记录 costs.CNY / costs.USD、tokens、lastSeq、当时使用的 pricingVersions 与 calendarVersions。再次扫描 session 时，只对 seq > lastSeq 的事件计价；已入账事件不会因调价或重启而重算，新价只影响新事件。
余额 API 可能返回多币种 balance_infos；展示以非零余额最大的币种为主（CNY 并列时优先 CNY）。双币种均有正余额时卡片可叠显两种余额，估算仍以较大余额对应币种为准。
主题、语言与可选通知¶
UI 使用 DSH menu-surface 设计 token（明暗、圆角、字号），跟随 DSH 界面语言（zh-* / English）。若用户此前已对 DSH 站点授予浏览器通知权限，峰谷窗口切换时可在标签页打开状态下推送通知；浏览器完全关闭则无法收到。
环境与依赖¶
安装前请确认：
- DSH 0.2.1.x 且启用 web profile；README 在
0.2.1-rc.3上测试，package.json声明engines.dsh = ">=0.2.1-0 <0.2.2-0"，其他 DSH 线版本不会挂载该插件。 - Node.js
^22.19.0 || >=24.0.0（与 DSH 要求一致）。 - 在 DSH credentials 中配置
DEEPSEEK_API_KEY。
安装与启用¶
从 GitHub 安装（勿与 npm 上无关的 dsh-balance 包混淆）：
dsh plugin --profile web add github:zz0-0/dsh-balance
systemctl --user restart dsh-web
或使用显式 git URL：
dsh plugin --profile web add git+https://github.com/zz0-0/dsh-balance.git
systemctl --user restart dsh-web
首次安装后请对 DSH 页面硬刷新（Ctrl/Cmd + Shift + R），以便注入浏览器脚本。systemctl 行假设 Linux 用户级 dsh-web 服务；若手动运行 dsh web，需自行重启该进程。
更新与卸载：
# 更新
dsh plugin --profile web add github:zz0-0/dsh-balance
systemctl --user restart dsh-web
# 移除
dsh plugin --profile web remove dsh-balance
systemctl --user restart dsh-web
典型用法¶
- 打开 DSH web 界面，看右下角卡片上的总余额、当前
谷价/高峰与下次切换倒计时。 - 点击卡片打开详情，核对价表来源时间、账本路径，必要时点刷新。
- 在侧边栏浏览各对话与 workspace 的
≈费用 badge；需要明细时悬停查看 token 与记录值。
若卡片显示 余额? / Balance?，多为 DEEPSEEK_API_KEY 缺失或无效，需在 DSH credentials 中检查。
架构与隐私（简要）¶
插件为 DSH bundle：cordis.patch.yml 把条目写入 web profile。Host（lib/index.js）解析 API Key、请求 api.deepseek.com/user/balance、读 session、维护账本、拉取价目/节假日，并提供 GET /dsh-balance/data 与 GET /dsh-balance/client.js。Browser（client.js）只访问本地 DSH 服务，绘制卡片、面板与侧边栏 badge。
出站请求限于：余额 API、两个官方 pricing 文档页、api.apihubs.cn 节假日接口；无额外遥测。价目与节假日缓存位于 ~/.dsh/（如 .dsh-balance-pricing.json、.dsh-balance-holidays.json 等）。
适用场景与注意¶
适合长期在 DSH web 上开发智能体、需要对照官方峰谷规则控成本、并希望按对话/workspace 复盘 API 消耗的开发者。
插件以当前运行 DSH 的进程权限执行 host 逻辑并持有对 credentials 的访问；安装前请自行审阅 仓库源码 与 MIT 许可证，确认可接受其网络与本地文件行为。
结尾¶
dsh-balance 把 DeepSeek 账户余额、峰谷窗口与会话级费用估算收进 DSH 同一界面，价目跟随官方文档更新，账本只增不重算历史。目录与文档：
