dsh-plugin-duwg

Readme

# dsh-plugin-duwg

每日用量统计插件 for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)。

在输入框下方显示**当天 Token 用量**（万/亿简化显示，悬停看精确值）与**缓存命中率**，含余额血条和预计消耗。

Daily token usage & cache-hit stats for DeepSeek Harness. Shows today's token usage (simplified to 万/亿 with exact values on hover), cache hit rate, account balance bar, and estimated cost right below the composer.

---

## 功能 Features

- **今日总消耗**：当天所有会话的 input / output / cache-read / cache-write Token 汇总（Host 端聚合，按天持久化）
- **会话日志校准**：启动时扫描 `$DSH_HOME/sessions` 下的 `.jsonl.zstd` 会话日志（zstd 帧自动识别），校准当天用量，进程重启/崩溃后数据也不丢
- **万/亿 简化**：大数字自动转为 `1.23万` / `4.56亿`，悬停显示精确值
- **缓存命中率**：缓存读取占总量的比例，绿色数字实时显示
- **余额血条**：显示 DeepSeek 账户余额与当天最高余额（充值自动抬高上限），低余额变红
- **预计消耗**：网关透传的费用字段累计（`usage.cost`）
- **持久化**：数据写入 `$DSH_HOME/storages/duwg/usage.json`，跨进程保留、跨天自动重置

## 安装 Install

```bash
# 从源码安装（推荐先审查）
dsh plugin --profile web add <本仓库路径或 git URL>

# 或从 npm（发布后）
dsh plugin --profile web add dsh-plugin-duwg
```

安装后重启 `dsh web`，小部件会出现在输入框下方。

## 数据位置 Data

```
$DSH_HOME/storages/duwg/usage.json
```

（`$DSH_HOME` 默认 `~/.dsh`）

## 工作原理 How it works

- **Host 半**（`lib/index.js`）：拦截 `llm/stream` 瀑布流聚合 usage 块（同一流只计一次）；提供 `GET /duwg/usage-stats` HTTP 路由；余额走官方 `api.deepseek.com/user/balance`（60s 缓存，仅 host 端持有 API key）；启动时扫描会话日志校准
- **Client 半**（`lib/client.js`）：DOM 挂载的小部件，2s 轮询刷新，数字原地更新不重建 DOM

## 安全 Security

- API key 只存在于 host 端，通过官方 `ctx.credentials` 解析，绝不进入浏览器
- 余额查询仅调用 DeepSeek 官方接口，60s 缓存降低调用频率
- 会话日志扫描仅读取本地 `$DSH_HOME/sessions` 下的 `.jsonl.zstd` 文件，用于校准用量，不对外发送
- 无任何第三方网络请求、无遥测

## License

MIT