dsh-balance-tasks：DeepSeek Harness 余额与任务数估算插件

前言¶

DeepSeek Harness（DSH）采用插件化架构，扩展功能依赖社区贡献。在开发或使用 DSH 过程中，直接查看总余额无法判断剩余任务数。Bil812 提供的 dsh-balance-tasks 插件解决了这一问题，它在右下角展示实时余额、峰谷档位以及基于历史消耗估算的剩余任务数。

核心功能¶

该插件提供以下核心能力：

悬浮卡显示：在界面右下角悬浮卡片，实时显示账户总余额、当前峰谷档位及切换倒计时。
任务数估算：基于历史平均消耗（包含上下文增量、输出 Token、缓存命中情况），估算当前余额还能跑多少个任务。
峰谷计价：支持峰谷时段计价（UTC 峰时段 01:00–04:00、06:00–10:00，谷时价格 = 峰时价格 / 2）。
数据持久化：账本数据持久化存储，支持重启后自动恢复。
接口访问：提供 RESTful API，允许外部程序查询余额和任务数。

安装与启用¶

安装前，请确保已在 设置 → 模型 中配置了 DEEPSEEK_API_KEY。插件会复用该 Key，不会出本机。

执行以下命令安装插件：

dsh plugin --profile web add github:Bil812/dsh-balance-tasks

安装完成后，重启 dsh web 即可生效。

配置模型价格¶

插件需要配置模型价格才能正确计算。在 设置 → 插件 → balance-tasks（或直接编辑 $DSH_HOME/settings.yaml）中配置 balance-tasks.models 列表。

配置项包含模型 ID、是否显示以及峰谷价格。内置默认模型为 deepseek-v4-flash、deepseek-v4-pro 和 deepseek-v4-flash-vision-exp。

示例配置如下：

balance-tasks:
  models:
    - { model: deepseek-v4-flash, show: true }
    - { model: deepseek-v4-pro, show: true }
    - { model: deepseek-v4-flash-vision-exp, show: true }
    # 自定义模型配置
    - model: deepseek-v5-xxx
      show: true
      peak: { miss: 4.0, hit: 0.15, out: 12.0 }
      offpeak: { miss: 2.0, hit: 0.08, out: 6.0 }

数据口径与逻辑¶

插件通过复用 llm/stream 的 usage 数据，与官方账单口径保持一致。计费价格与 dsh-conversation-cost 一致，包含输入 miss、缓存 hit 和输出 out 三种计费方式。

剩余任务数计算：
采用“统一口径”计算。从当前上下文 ctx 开始，累加估算下一任务的价格，直到余额耗尽。公式如下：
下一任务价格 = 平均新增上下文(delta)×miss + 当前上下文(ctx)×hit + 平均输出(outAvg)×out

峰谷判定：按调用发生时刻判定，2026-08-17 00:00 北京时间起生效。
存储位置：聚合账本存储在 $DSH_HOME/storages/balance-tasks.json。数据每 10 秒节流并仅在变动时原子写入，每次启动自动全量读取恢复。
适用范围：估算仅对 CNY 余额生效；无历史用量时显示“暂无用量记录”。

API 接口¶

插件提供 RESTful API 用于查询余额和任务数。

获取余额数据：

GET /api/balance-tasks

强制刷新余额：

GET /api/balance-tasks?refresh=1

返回的 JSON 包含 balance（余额）、tier（档位）、stats（总统计）以及 perModel（各模型详情，含 remainingTasks、avgTokensPerTask、nextTaskCost 等）。

卸载¶

如需卸载，执行以下命令：

dsh plugin --profile web remove dsh-balance-tasks