# token-watch

**Repository Path**: nachao/token-watch

## Basic Information

- **Project Name**: token-watch
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-13
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Token Watch - 多平台API余额监控工具

一个轻量级的桌面监控工具，实时追踪多个AI服务平台的API使用配额和余额。

![Python](https://img.shields.io/badge/Python-3.7+-blue.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)
![Platform](https://img.shields.io/badge/Platform-Windows-lightgrey.svg)

## ✨ 特性

- 🎯 **多平台支持**：DeepSeek、小米、Kimi、Llama、智谱AI、火山引擎等主流AI服务平台
- 📊 **实时监控**：30秒自动刷新，实时显示API使用情况
- 📈 **可视化曲线**：历史数据曲线图，直观展示使用趋势
- ⚙️ **灵活配置**：支持自定义平台、刷新间隔、API密钥等
- 🔔 **系统托盘**：最小化到系统托盘，不占用任务栏空间
- 💾 **数据持久化**：自动保存历史数据，程序重启不丢失
- 🎨 **美观界面**：半透明悬浮窗口，支持拖拽和置顶

## 📸 界面预览

```
┌──────────────────┐
│ DeepSeek         │
│ $9.60      -1.25 │ ← 余额(左) 消耗(右)
│ ~~~~~╮           │ ← 历史曲线
│      ╰~~~~~      │
├──────────────────┤
│ Kimi             │
│ 91%      ⏳1:00  │ ← 已使用百分比(左) 倒计时(右)
│ ~~~~~╮           │ ← 已使用百分比曲线
│      ╰           │
├──────────────────┤
│ BigModel         │
│ 36%      ⏳2:30  │ ← 已使用(左) 倒计时(右)
│ ~~~~~╮           │ ← 使用率曲线
│      ╰~~~~~      │
└──────────────────┘
```

## 🚀 快速开始

### 环境要求

- Windows 10/11
- Python 3.7+
- 网络连接

### 数据迁移（升级用户）

如果你是从旧版本升级，程序启动时会自动迁移历史数据：

- `history.json` → `data/history_deepseek.json`
- `history_*.json` → `data/history_*.json`

迁移完成后，可以手动删除根目录下的旧历史文件。

### 安装步骤

1. **克隆仓库**
```bash
git clone https://gitee.com/nachao/token-watch.git
cd token-watch
```

2. **安装依赖**
```bash
pip install -r requirements.txt
```

3. **配置API密钥**

复制配置示例并编辑：
```bash
copy config\config.example.json config\config.json
```

然后编辑 `config/config.json`，填入你的API密钥：

```json
{
  "platforms": [
    {
      "name": "DeepSeek",
      "url": "https://api.deepseek.com/user/balance",
      "api_key": "your-api-key-here",
      "type": "deepseek",
      "enabled": true
    }
  ]
}
```

4. **启动程序**

**方法一：直接运行**
```bash
python watch.py
```

**方法二：使用启动脚本（推荐）**
```bash
# 双击 start.vbs 即可启动
# 或在命令行运行：
start.vbs
```

## ⚙️ 配置说明

### 支持的平台

| 平台 | 类型 | 配置说明 |
|------|------|----------|
| **DeepSeek** | `deepseek` | 需要api_key |
| **小米** | `xiaomi` | 需要cookie |
| **Kimi** | `kimi` | 需要kimi_token |
| **Llama** | `llama` | 需要API地址 |
| **智谱AI (BigModel)** | `bigmodel` | 需要jwt_token、organization、project |
| **火山引擎** | `volcengine` | 需要csrf_token、web_id、cookie |

### 配置示例

#### DeepSeek配置
```json
{
  "name": "DeepSeek",
  "url": "https://api.deepseek.com/user/balance",
  "api_key": "sk-xxxxxxxxxxxx",
  "type": "deepseek",
  "enabled": true
}
```

#### 小米配置
```json
{
  "name": "Xiaomi",
  "url": "https://platform.xiaomimimo.com/api/v1/tokenPlan/usage",
  "type": "xiaomi",
  "enabled": true,
  "cookie": "api-platform_serviceToken=\"your-token\"; userId=xxx"
}
```

**数据展示**：
- **左边**：总配额百分比 (如 72.0%)
- **右边**：已使用量 (如 144.0M)
- **曲线**：已使用量变化趋势

**Cookie 过期处理**：
当看板显示 "Cookie过期" 时，说明小米平台的认证 Cookie 已失效。请按以下步骤更新：

1. 打开浏览器访问：https://platform.xiaomimimo.com
2. 登录你的小米账号
3. 按 `F12` 打开开发者工具，切换到 `Console` 标签
4. 输入 `document.cookie` 并回车，复制整个 Cookie 字符串
5. 打开 `config/config.json`，找到 Xiaomi 配置的 `cookie` 字段
6. 将新的 Cookie 粘贴进去（保留引号）
7. 保存文件并重启程序

详细说明请参考：[docs/UPDATE_XIAOMI_COOKIE.md](docs/UPDATE_XIAOMI_COOKIE.md)

#### Kimi配置
```json
{
  "name": "Kimi",
  "url": "https://www.kimi.com/apiv2/kimi.gateway.billing.v1.BillingService/GetUsages",
  "type": "kimi",
  "enabled": true,
  "kimi_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..."
}
```

#### Llama配置
```json
{
  "name": "Llama",
  "url": "http://your-llama-server/metrics",
  "type": "llama",
  "enabled": true
}
```

#### 智谱AI (BigModel) 配置
```json
{
  "name": "BigModel",
  "url": "https://bigmodel.cn/api/monitor/usage/quota/limit",
  "type": "bigmodel",
  "enabled": true,
  "jwt_token": "eyJhbGciOiJIUzUxMiJ9...",
  "organization": "org-your-org-id",
  "project": "proj-your-project-id"
}
```

**数据展示**：
- **左边**：已使用配额百分比 (如 36%)
- **右边**：配额重置倒计时 (如 2:30，表示2小时30分钟后重置)
- **曲线**：使用率变化趋势

**获取智谱AI配置信息**：
1. 登录 [智谱AI开放平台](https://bigmodel.cn)
2. 打开浏览器开发者工具 (F12)
3. 访问 `https://bigmodel.cn/coding-plan/personal/usage`
4. 在 Network 标签中找到 `/api/monitor/usage/quota/limit` 请求
5. 复制以下信息：
   - `authorization` 请求头 → `jwt_token` (完整的JWT令牌)
   - `bigmodel-organization` 请求头 → `organization`
   - `bigmodel-project` 请求头 → `project`

#### 火山引擎 (Volcengine) 配置
```json
{
  "name": "Volcengine",
  "url": "https://console.volcengine.com/api/top/ark/cn-beijing/2024-01-01/GetCodingPlanUsage?",
  "type": "volcengine",
  "enabled": true,
  "csrf_token": "your-csrf-token-here",
  "web_id": "your-web-id-here",
  "cookie": "your-complete-cookie-here"
}
```

**数据展示**：
- **左边**：已使用配额百分比 (会话级别，如 7.45%)
- **右边**：配额重置倒计时 (如 5:30，表示5小时30分钟后重置)
- **曲线**：使用率变化趋势

**获取火山引擎配置信息**：
1. 登录 [火山引擎控制台](https://console.volcengine.com/ark)
2. 打开浏览器开发者工具 (F12)
3. 访问任意使用量统计页面
4. 在 Network 标签中找到 `GetCodingPlanUsage` 请求
5. 复制以下信息：
   - `x-csrf-token` 请求头 → `csrf_token`
   - `x-web-id` 请求头 → `web_id`
   - 完整的 `cookie` 请求头 → `cookie`

### 全局配置

```json
{
  "refresh_ms": 30000,      // 刷新间隔（毫秒）
  "max_points": 10000       // 历史数据最大保存点数
}
```

#### DPI 缩放支持（完全自适应）

程序会**自动检测系统的 DPI 缩放比例**，并智能调整字体大小和窗口尺寸：

| DPI 设置 | 检测到的缩放比例 | 自动字体大小 |
|---------|----------------|------------|
| 100% (96 DPI) | 1.0 | 6-7 号字体 |
| 125% (120 DPI) | 1.25 | 6-7 号字体 |
| 150% (144 DPI) | 1.5 | 7-8 号字体 |
| 175% (168 DPI) | 1.75 | 7-8 号字体 |
| 200% (192 DPI) | 2.0 | 8-9 号字体 |

**无需手动配置**，程序会根据你的系统设置自动选择最合适的字体大小。

如需手动覆盖自动设置（不推荐），可以添加：

```json
{
  "base_font_size": 7       // 强制使用指定字体大小（不会再乘以DPI缩放）
}
```

## 🎯 功能说明

### 界面操作

- **拖拽**：点击窗口任意位置拖拽
- **置顶**：右键托盘图标 → 置顶/取消置顶
- **退出**：右键托盘图标 → 退出

### 数据说明

| 平台 | 左边显示 | 右边显示 | 曲线展示 |
|------|----------|----------|----------|
| **DeepSeek** | 当前余额($) | 本次会话消耗 | 余额变化趋势 |
| **Xiaomi** | 总配额百分比 | 已使用量 | 已使用量变化 |
| **Kimi** | 已使用百分比 | 配额重置倒计时 | 已使用百分比变化 |
| **Llama** | 总Token数 | 生成速度(t/s) | 总Token数变化 |
| **智谱AI** | 已使用配额百分比 | 配额重置倒计时 | 使用率变化趋势 |
| **火山引擎** | 已使用配额百分比(月度) | 配额重置倒计时 | 使用率变化趋势 |

- **颜色**：
  - 🟢 绿色：平台已启用
  - 🔴 红色：平台已禁用

## 📁 项目结构

```
token-watch/
├── watch.py              # 主程序
├── requirements.txt      # 依赖包
├── start.vbs            # 启动脚本
├── README.md            # 项目说明
├── LICENSE              # 许可证
├── .gitignore           # Git忽略文件
├── config/              # 配置目录（自动创建）
│   ├── config.json      # 配置文件（需创建）
│   └── config.example.json  # 配置示例
├── data/                # 历史数据目录（自动创建）
│   └── history_*.json   # 各平台历史数据
└── logs/                # 日志目录（自动创建）
    └── watch_YYYY-MM-DD.log  # 按日期命名的日志文件
```

## 🔧 依赖项

```
pystray>=0.19.5
Pillow>=10.0.0
```

## 📝 日志和调试

程序运行日志保存在 `logs/` 目录中，按日期命名（如 `watch_2026-05-13.log`），包含：

- API请求状态
- 数据解析结果
- 错误和警告信息
- 数据迁移记录

查看当日日志：
```bash
type logs\watch_%date%.log
```

或直接打开 `logs/` 目录查看历史日志文件。

## 📊 数据管理

### 历史数据文件

所有平台的历史数据保存在 `data/` 目录：

```
data/
├── history_deepseek.json     # DeepSeek 余额历史
├── history_xiaomi.json       # 小米使用量历史
├── history_kimi.json         # Kimi 配额历史
├── history_llama.json        # Llama Token 历史
├── history_bigmodel.json     # 智谱AI 配额历史
└── history_volcengine.json   # 火山引擎配额历史
```

### 数据迁移

首次运行新版本时，程序会自动迁移旧数据：

- `history.json` → `data/history_deepseek.json`
- `history_*.json` → `data/history_*.json`

迁移成功后，控制台会显示迁移的文件数量。此时可以手动删除根目录下的旧历史文件。

## 🛡️ 安全提示

⚠️ **重要安全事项**：

1. **不要提交敏感信息**：`config/config.json` 包含API密钥，请勿提交到版本控制系统
2. **定期更新密钥**：建议定期更换API密钥
3. **权限控制**：确保配置文件只有你能够访问
4. **网络安全**：建议在可信网络环境下使用

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 贡献建议

- 🐛 Bug修复
- ✨ 新功能开发
- 📖 文档改进
- 🎨 UI/UX优化
- ⚡ 性能优化

## 📄 开源协议

本项目采用 [MIT License](LICENSE) 开源协议。

## 🙏 致谢

- [pystray](https://github.com/moses-palmer/pystray) - 系统托盘功能
- [Pillow](https://python-pillow.org/) - 图像处理
- 所有贡献者和使用者

## 📧 联系方式

- 问题反馈：[GitHub Issues](https://gitee.com/nachao/token-watch/issues)
- 功能建议：[GitHub Discussions](https://gitee.com/nachao/token-watch)

## 🗺️ 路线图

- [ ] 支持更多AI平台
- [ ] 添加使用量预警功能
- [ ] 支持自定义界面主题
- [ ] 添加数据导出功能
- [ ] 支持macOS和Linux平台

---

**注意**：本工具仅供学习和个人使用，请遵守相关平台的使用条款。

⭐ 如果这个项目对你有帮助，请给个 Star！