dsh-balance-tasks

Readme

# dsh-balance-tasks

DeepSeek Harness 插件：**余额与任务数换算显示**。

右下角悬浮卡实时显示：

- **余额**（官方 `/user/balance`，总余额/赠送/充值）
- **还能跑多少个任务**（估算：1 任务 ≈ 1 会话；**统一口径**：每个任务价格 = 平均单次任务消耗的 Tokens（新增上下文 delta + 输出 outAvg，历史平均）× 当前档单价 + 当前已有的上下文 Tokens（按缓存命中价重读），从当前上下文起逐任务计价直到余额耗尽）
- **当前峰谷档位 + 距切换倒计时**（UTC 峰时段 01:00–04:00、06:00–10:00，即北京时间 9–12、14–18）

点击卡片可立即刷新余额。

<img width="422" height="201" alt="image" src="https://github.com/user-attachments/assets/9d6baf9f-0273-479e-bc7c-2cb70821edf8" />

## 安装

```sh
dsh plugin --profile web add <本目录>
```

或直接从 GitHub 安装：

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

重启 `dsh web` 后生效。要求已在 **设置 → 模型** 配置 `DEEPSEEK_API_KEY`（插件复用同一把 Key，通过凭据服务解析，不出本机）。

## 数据口径

- usage 折叠自 `llm/stream` 的 usage 块（含子代理、压缩、标题等辅助调用），与官方账单口径一致；
- 计费价格与 `dsh-conversation-cost` 一致：未命中输入按 miss 价、缓存命中按 hit 价、输出（含 reasoning）按 out 价；
- 峰谷按调用发生时刻判定，2026-08-17 00:00 北京时间起生效，谷时 = 峰时半价；
- 聚合账本持久化在 `$DSH_HOME/storages/balance-tasks.json`（10 秒节流 + 退出落盘，均**原子写**且**仅在账本有改动时写**，避免空账本覆盖历史）；**每次启动自动全量读取恢复**，重启后估算保留；
- **判断口径（统一）**：`剩余任务数` = 从当前上下文 `ctx` 起逐任务累加——每个任务价格 = `平均新增上下文(delta)×miss + 当时上下文(ctx)×hit + 平均输出(outAvg)×out`，`ctx` 每次 `+delta`，直到余额耗尽；即把「历史平均单任务消耗」与「当前已有上下文」统一进同一个计价公式，不再输出两套互不相同的数字；
- **当前时段口径**：单价统一取**当前峰谷档位**（峰时按峰价、谷时按谷价，峰价 = 谷价 ×2），模拟期内不轮换——剩余任务数即「以当前峰谷状态继续跑」的估计；
- 估算仅对 **CNY 余额** 生效；无历史用量时显示「暂无用量记录」。

## 模型显示配置

在 **设置 → 插件 → balance-tasks**（或直接编辑 `$DSH_HOME/settings.yaml` 的 `balance-tasks` 段）配置：

- **`models`**：模型列表，每项含 `model`（模型 id）、`show`（卡片是否显示）、可选 `peak`/`offpeak`（每项 `{ miss, hit, out }`，元/M tokens）。
- 内置默认：`deepseek-v4-flash`（Flash）、`deepseek-v4-pro`（Pro）、`deepseek-v4-flash-vision-exp`（官方 EXP，与 Flash 同价但**单列统计**）。
- **隐藏模型**：把对应项的 `show` 设为 `false`。
- **新增自定义模型**：加一项 `model` + `peak`/`offpeak` 价格，无需改插件代码即会被计价并显示；未配价格的自定义模型不显示（除非已有用量）。
- 卡片只显示开启的模型，行序按内置顺序在前，其余按配置/用量次序。

示例：

```yaml
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 }
```

## 接口

`GET /api/balance-tasks`（`?refresh=1` 强制重查余额）返回 `{ balance, tier, tierSecondsLeft, stats: { totalSessions, totalCost, overallAvgCostPerTask, overallAvgTokensPerTask, overallRemainingTasks }, perModel: [...] }`；`perModel[].remainingTasks` 为统一口径剩余任务数，`perModel[].avgTokensPerTask`（历史平均 tok/个）、`avgOutputPerTask`（平均输出 tok/个）、`contextTokens`（当前上下文）、`growthPerTask`（平均新增 tok/任务）、`nextTaskCost`（下一任务价格 = delta×miss + ctx×hit + outAvg×out）。

## 卸载

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

MIT License