dsh-usage-indicator

Readme

# dsh-usage-indicator

[![CI](https://github.com/TiferKing/dsh-usage-indicator/actions/workflows/ci.yml/badge.svg)](https://github.com/TiferKing/dsh-usage-indicator/actions/workflows/ci.yml)

![Screenshot1](docs/screenshots/Screenshot1.png)

DSH（DeepSeek Harness）Web 侧边栏插件：实时显示**上下文余量**、**账户余额**和**预计下次上下文压缩轮次**。数据本地闭环，API Key 不离开本机。

## 功能

- 上下文占用 / 模型窗口进度条，接近压缩阈值变黄、达到变红
- 账户余额进度条，低于警示线整条变红
- 「N 轮后压缩」EMA 估算，数据不足显示"评估中"
- Web 设置面板可调整满条额度与警示线，热生效
- 侧边栏收起时为紧凑圆环 + 余额状态点

## 安装

前置：已安装 DSH 与 pnpm（缺 pnpm 先执行 `npm install -g pnpm`）。

**方式一：Release 包（推荐）**

```powershell
dsh plugin --profile web add C:\path\to\dsh-usage-indicator-<version>.tgz
```

**方式二：源码安装（clone 即用，内置 lib/ 无需构建）**

```powershell
git clone https://github.com/TiferKing/dsh-usage-indicator.git
dsh plugin --profile web add .\dsh-usage-indicator
```

安装后重启 `dsh web` 生效；更新用新包再执行一次 `add`；卸载：`dsh plugin --profile web remove dsh-usage-indicator`。

## 使用与配置

默认读取环境变量 `DEEPSEEK_API_KEY` 查余额，侧边栏顶部实时显示卡片；收起侧边栏自动切换为圆环视图。Web 设置面板「API 用量指示」可修改满条额度与警示线，写入 `settings.yaml` 热生效。

| 字段 | 默认值 | 说明 |
|---|---|---|
| `apiKeyEnv` | `DEEPSEEK_API_KEY` | 余额接口的凭证引用 |
| `baseURL` | `$DEEPSEEK_BASE_URL` → `https://api.deepseek.com` | 余额接口基址（自定义网关时配置） |
| `refreshIntervalMs` | `60000` | host 轮询周期（毫秒），下限 30 秒 |
| `thresholdRatio` | `0.8` | 上下文压缩阈值，**需与 `dsh-compaction-basic` 保持一致** |
| `fullBalance` | `100` | 资金条满条金额 |
| `warnBalance` | `20` | 余额低于该值时资金条变红 |

## 开发

```powershell
npm install
npm run build      # 产出 lib/index.js + lib/client.js
npm run typecheck  # 类型检查
npm test           # 运行测试（需 Node ≥ 22.18）
```

结构：`src/index.ts`（host：轮询 + `/api/usage-indicator` 路由）、`src/client.tsx`（侧边栏卡片与设置页）、`src/balance.ts`（余额解析）、`test/`。欢迎提交 Issue 与 PR。

## License

[MIT](LICENSE)