前言¶

在 DeepSeek Harness（DSH）里跑 Composer 或智能体时，token 统计只能反映本机消耗，平台控制台里的余额往往滞后数分钟，干活时数字几乎不动。充值、成块结算还会让「照抄读数」和真实花费对不上。若你希望在 Composer 输入框下方直接看到「还能用多久」，就需要把平台读数当作周期锚点，再用本机 token 消耗实时递减——这正是社区插件 dsh-balance（npm 包名 @zzxxxxxx/dsh-balance）要做的事。下文介绍其定位、能力、安装方式与配置要点；事实均来自 GitHub 仓库 README 与 package 元数据。

这是什么¶

dsh-balance 由维护者 zzzxxxxxxxxxx 发布，在 SkillHub 目录中归类为联网工具。它在带 Web 界面的 DSH profile 里，于输入框下方提供读数 pill，显示预估余额与估算可用时长（ETA）；host 半定期轮询 DeepSeek 余额端点，浏览器半只读快照，API Key 不经浏览器出网。

插件当前版本 0.1.0，许可证 MIT，依赖 DeepSeek Harness ≥ 0.2.0-rc.1。

核心功能¶

锚点读数，而非滞后抄表¶

平台结算通常滞后约 1～5 分钟。插件每次从平台取得的读数只作周期锚点，界面显示的是「锚点 − k × 本机已消耗」，数字随本机 token 实时递减。在时刻 T 取得的读数反映的是 T − settlementLagMs 之前的用量，本地累计从该截止时刻起算，避免最后几分钟被重复扣除。

分档计价与校正系数 k¶

按官方高峰价分档（缓存命中 / 未命中 / 输出），默认价目表覆盖 deepseek-flash、deepseek-v4-pro；空闲时段相对高峰按 offPeakFactor（默认 0.5）计价。高峰定义为北京时间周一至周五 09:00–12:00、14:00–18:00（不含法定节假日，其余半价）。再用近期余额下降的中位数学习标量 k，吸收过期价目表、未收录模型与统一折扣。价目表准确时 k 应在 1.0 附近，可作为自检。

充值与异常下降¶

只累加余额下降；充值抬高钱包但不进入消耗统计，不污染 k。没有本地用量解释的大额下降记为「非用量调整」。ETA 在启用 etaIntegratesSchedule 时会跨峰谷时段积分，避免临近 18:00 仍按高峰价估算而偏小。

界面与接口¶

• pill：示例形态为 ¥36.35 · 2 天 4 小时；状态点平时为绿，低于 etaWarnMs 转橙，低于 etaCriticalMs 或余额耗尽转红，未标定或连不上时为灰。
• 面板：点开 pill 可查看平台读数、本机推算已消耗、当前预估余额、时段与切换、消耗速率、校正系数等；右下角可请求 host 立即刷新。
• 无斜杠命令、无设置页；host 提供 GET /dsh-balance/state 与 POST /dsh-balance/refresh。

出网目标仅余额端点；可选第二个目标是显式启用时的节假日远程源（默认关闭）。凭据引用与内置 deepseek-official provider 相同，为 DEEPSEEK_API_KEY。

安装与启用¶

环境要求：DeepSeek Harness ≥ 0.2.0-rc.1，Node ^22.19.0 || >=24.0.0。

推荐从 npm 安装（注意 scope，勿与无 scope 的同名包 dsh-balance 混淆）：

dsh plugin --profile <profile> add @zzxxxxxx/dsh-balance

安装完成后重启 dsh（profile 在启动时组合）。

API Key 取自凭据引用 DEEPSEEK_API_KEY，可在设置 → 模型、$DSH_HOME/.credentials.yaml 或环境变量中配置；模型能正常调用即表示已就绪。

卸载：

dsh plugin --profile <p> remove @zzxxxxxx/dsh-balance

卸载后同样需要重启。无 Web 界面的 profile 下 host 仍会轮询，但不显示 pill。

典型用法¶

1. 在目标 profile 执行上述 add 命令并重启 DSH。
2. 打开带 Composer Web 界面的会话，确认输入框下方出现 pill。
3. 需要明细或手动对齐平台读数时，点击 pill 打开面板，必要时使用「立即刷新」。
4. 需调整轮询周期、结算滞后、价目表、峰谷窗口或 ETA 阈值时，在 profile 插件行的 config: 中修改字段（见下节），改完重启。

本插件不提供独立设置页；全部行为由 cordis.patch.yml 插入项中的 config 驱动。

配置要点¶

配置写在插件 insert 的 config: 下，改完需重启。常用字段示例（完整默认值见仓库 README）：

- insert:
    - id: dsh-balance
      name: '@zzxxxxxx/dsh-balance'
      config:
        apiKeyEnv: DEEPSEEK_API_KEY
        apiOrigin: https://api.deepseek.com
        balancePath: /user/balance
        refreshIntervalMs: 60000
        settlementLagMs: 300000
        priceTable:
          deepseek-flash: { input: 1, cacheRead: 0.02, output: 4 }
          deepseek-v4-pro: { input: 4.5, cacheRead: 0.15, output: 13.5 }
        offPeakFactor: 0.5
        peakWindows: ['09:00-12:00', '14:00-18:00']
        priceTimeZone: Asia/Shanghai
        etaWarnMs: 86400000
        etaCriticalMs: 14400000
        holidaySourceEnabled: false
        persist: true

几条语义 worth knowing：

• settlementLagMs 默认 300000（5 分钟），ETA 分子来自锚点，会略偏小该上界，但不会随滞后漂移。
• 校正系数需若干笔下降才稳定；此前状态为灰、「未标定」，速率退化为按余额差估算。
• 价目表币种 priceCurrency 须与钱包一致（默认 CNY），否则退化为 weights 相对权重计价。
• 法定节假日可写 holidays / makeupWorkdays，或开启 holidaySourceEnabled 拉远程源；未发布年份不会当作「无节假日」。

适用场景与注意¶

适合：长期在 DSH Composer 上开发、希望在本机界面实时感知 DeepSeek API 余额与大致可用时长、并愿意接受「估算而非账单级精确」的开发者。

注意：

• 插件以当前 dsh 进程权限运行，会访问 API Key 与余额端点；安装前请查阅 源码 与 MIT 许可证，自行评估信任边界。
• README 标明插件仍处早期，可能存在问题，可到 Issues 反馈。
• SkillHub 等为社区目录，与 DeepSeek / 幻方无官方从属关系；星标与传播数据以各站点当时展示为准（仓库线索为 0 star）。

结尾¶

经过上面的步骤，你可以在 Composer dock 旁获得「锚点 + 本机 token + 峰谷价」驱动的余额与 ETA，减少反复打开控制台对表的次数。目录页：SkillHub — dsh-balance；源码与完整配置说明：GitHub — zzzxxxxxxxxxx/dsh-balance。