# dsh-balance-pie

> [English](./README.md) · [中文](./README.zh-CN.md)

**DSH 插件 · 余额监控 / 真实消耗统计 / 历史热力图**

[![DSH](https://img.shields.io/badge/DSH-Plugin-566efe)](#)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](#-许可证)

[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）插件：在 DSH 网页界面右下角显示一个可拖动的悬浮饼图，实时展示**今日初始余额、各项目真实消耗、剩余余额**；最小化后停靠在侧边栏，并内置**按月历史热力图**与**按天消耗表格**。

## ✨ 特性

- 🥧 可拖拽悬浮饼图：今日初始 / 真实消耗 / 剩余余额，一目了然
- 📊 真实消耗口径：按余额实际下跌统计，充值退款自动正确，重启不重置
- 💰 充值自动识别 + 一键充值按钮（直达官方充值页）
- 📅 历史回顾：GitHub 风格按月热力图（无记录日为白色）+ 按天表格（日期 / 消耗 / 剩余）
- 🗂 本地持久化：当日状态 + 按天日志（节流写入，保留 90 天）
- 📐 侧边栏自适应：展开横向条 / 收起竖向条 + 余额
- ⚙️ 设置中心「余额」：参数与历史两个子页，全部即时生效
- 🌐 中英文切换（默认跟随 DSH 语言），金额可换算显示币种

## 🚀 快速开始

前置：DSH 已配置 DeepSeek API key。

本仓库**内置预构建产物**（`lib/`）并声明了 `dsh.bundle` manifest——可直接**从 GitHub 一行安装**：

```sh
dsh plugin --profile web add github:f1yan9/dsh-balance-pie
```

重启 dsh web，打开网页界面即可看到右下角悬浮饼图。

卸载：

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

> **手动安装**：克隆仓库（或将插件目录放入 `$DSH_HOME/profiles/node_modules/dsh-balance-pie/`），并在 profile 的 `cordis.patch.yml` 追加 `insert` 块；重启 dsh web。重新构建：`node build.mjs`（esbuild 自动探测）。

## 📖 使用

- **悬浮饼图**：拖动调整位置；悬停扇区查看明细；点 **—** 最小化、**⚙** 打开设置、**↻** 刷新、**充值图标** 去充值。
- **侧边栏**：最小化后变为条形图（展开态横向、收起窄轨竖向 + 余额），点击展开回饼图。
- **设置（「余额」分区）**：参数设置子页包含全部选项（轮询、币种、单价、历史、语言等）；历史子页展示热力图与表格。

## ⚙️ 配置

在设置抽屉「余额」分区编辑，或写入 DSH profile 的 `cordis.patch.yml`。常用项：

| 配置 | 说明 | 默认 |
|---|---|---|
| `pollIntervalMs` | 余额轮询间隔 | 10000ms |
| `pricesJson` | 模型谷段单价（每百万 token） | 已预置 deepseek-v4-flash |
| `peakMultiplier` | 高峰单价倍率 | 2 |
| `language` | 界面语言（auto 跟随 DSH） | auto |
| `displayCurrency` | 显示币种（可换算） | auto（账户币种） |
| `topUpUrl` | 充值页地址 | 官方充值页 |

## 🛠 开发

```sh
node build.mjs        # 重新构建 lib/（esbuild 自动探测：HARNESS_ROOT → 本地 pnpm store → npm i -D esbuild）
node test/run.mjs     # typecheck → build → smoke → unit
```

## 📁 数据存储

插件数据保存在 `$DSH_HOME/dsh-balance-pie/`：

- `daily-state.json` — 当日状态（锚点、真实消耗、充值基线）
- `history/YYYY-MM-DD.jsonl` — 按天历史日志（保留 90 天）

## ❓ 常见问题

- **消耗与账单对不上？** 消耗为真实口径（余额下跌）；多项目场景下项目金额按用量估算分摊，可在设置校准单价。
- **重启后今日初始重置？** 不会——锚点与消耗持久化在本地，同日重启自动恢复。
- **充值后没变化？** 充值在下次轮询（默认 10s）检测；已花掉的历史充值无法追溯修正。
- **历史数据在哪？** `$DSH_HOME/dsh-balance-pie/history/`——删除该目录即清空历史。

## 📄 许可证

MIT