dsh-balance-mini

Readme

# dsh-balance-mini

DeepSeek Harness（dsh web）的极简余额监视器：左下角一枚常驻余额徽章，点击展开详情面板。零配置、零依赖，只为"随时看一眼余额"而生。

> 作者：**DaYanQAQ** · License: MIT

## 功能

- 💰 **常驻余额徽章**：左下角实时显示「余额：￥xx.xx · 更新于 HH:MM」，不占界面空间；随侧边栏宽度自适应（拖动侧边栏时平滑跟随）
- 🚦 **红绿灯圆灯**：收起侧边栏时，徽章收缩为红/黄/绿小圆灯——低于 10 元红色、10~20 元黄色、20 元以上绿色；金额文字颜色同规则
- 🔄 **每分钟自动刷新**：每 60 秒自动查询一次余额，面板右上角可手动刷新
- 🏷️ **多供应商**：支持 DeepSeek（深度求索）、Kimi（月之暗面）、OpenRouter。**在 Harness 的「设置-模型」里配置了哪家的 API Key，哪家就自动可用**；未配置的供应商选择后显示提示，余额显示为 ￥0.00
- ⏰ **高峰/空闲时段提示**：按 DeepSeek 官方定价显示当前时段——高峰 = 北京时间周一至周五 9:00–12:00、14:00–18:00；其余时间（晚间、凌晨、午休、周末全天）为空闲时段，空闲价格为高峰的一半。并倒计时距下一时段切换的时间
- 📖 **首次使用说明**：第一次打开面板时弹出使用说明（颜色含义、红绿灯、刷新频率），点「知道了」后不再出现
- 🌐 **中英文自动切换**：跟随浏览器语言
- 🔒 **本机安全边界**：接口仅接受回环地址（127.0.0.1）访问；API Key 只在本机进程内读取，仅发往对应供应商官方接口，不落盘、不转发任何第三方

## 安装

需要 DeepSeek Harness（`@deepseek-ai/dsh >= 0.1.0-rc.6`）。

**方式一（推荐，命令行安装）**：

1. 在命令行执行：

   ```sh
   dsh plugin --profile web add dsh-balance-mini
   ```

2. 重启 `dsh web`，并在浏览器里硬刷新页面（Ctrl+Shift+R）
3. 左下角出现余额徽章即安装成功 ✅

**方式二（本地开发，链接本项目文件夹，改动即时生效）**：

```sh
dsh plugin --profile web add file:/path/to/dsh-balance-mini
```

卸载：

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

## 配置

**零配置开箱即用。** 插件读取 DSH 凭据文件（`~/.dsh/.credentials.yaml`）中的各供应商 API Key，配置了哪家就用哪家：

```yaml
refs:
  DEEPSEEK_API_KEY: sk-xxxxxxxx      # DeepSeek：platform.deepseek.com
  MOONSHOT_API_KEY: sk-xxxxxxxx      # Kimi：platform.moonshot.cn
  OPENROUTER_API_KEY: sk-or-xxxx     # OpenRouter：openrouter.ai
```

添加或删除某家的 Key 后，重新打开余额面板即生效（无需重启）。

## 项目结构

```
├── cordis.patch.yml   # bundle 补丁层（挂载插件行）
├── lib/
│   ├── server.js      # 服务端：回环路由 + 多供应商余额拉取与缓存（55 秒 TTL）
│   └── client.js      # 客户端：手写模块束，无构建步骤
├── package.json
├── LICENSE
└── README.md
```

## 供应商接入说明

- **已接入**：DeepSeek（`GET /user/balance`）、Kimi（`GET /v1/users/me/balance`，与 DeepSeek 同构）、OpenRouter（`GET /api/v1/credits`，美元额度）
- **未接入**：Z.ai（智谱）无公开余额查询 API；通义千问/豆包需走阿里云/火山引擎 OpenAPI（AccessKey 签名，且查询的是云账户整体余额，与模型额度语义不符），均暂不接入

## 相关项目

- [dsh-shortcut](https://github.com/DaYanQAQ/DSH-Shortcut)：Windows 桌面快捷方式工具——双击智能启动/唤起、浏览器打开前终端自动最小化，崩溃一键重装救援（不删用户数据）

## 致谢

本项目基于 [Ychris12138/dsh-usage-stats](https://github.com/Ychris12138/dsh-usage-stats)（MIT License）改造而来，感谢原作者。

## License

[MIT](LICENSE) © 2026 DaYanQAQ · 包含 dsh-usage-stats contributors 的版权声明