# tokenorb

**Repository Path**: adv30/tokenorb

## Basic Information

- **Project Name**: tokenorb
- **Description**: Windows 桌面悬浮球：实时监测 DeepSeek / GLM / 火山方舟 / MiniMax / Kimi 等 9 家 LLM 余额与套餐额度 + 本机 CPU/内存，墨仓水位可视化、越线变色提醒。原生 GDI+ 渲染 + WebView2 面板，零弹窗、单实例、静默常驻。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# token 余额悬浮球（TokenOrb）

[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

Windows 桌面悬浮球，实时展示 DeepSeek / 智谱 GLM / 火山方舟 / MiniMax / 小米 MiMo / Kimi /
硅基流动 / 腾讯混元 / 阿里百炼 等多家 LLM 账户余额与套餐额度、本机 CPU/内存占用；余额异常时
球体变色提醒。原生 GDI+ 悬浮球 + WebView2 设置面板，零弹窗、单实例、静默常驻。

## 截图

| 玩具态 | 细读态 | 磁吸条 |
|:---:|:---:|:---:|
| ![玩具态](screenshots/toy.png) | ![细读态](screenshots/detail.png) | ![磁吸条](screenshots/bar.png) |

墨仓式水位阵列 + 底部文字轮播；悬停展开细读态行卡（余额/额度/到期 + CPU/内存）；贴左右缘自动收窄为磁吸条（鼠标移入还原）。

## 功能一览

- **悬浮球（玩具态）**：墨仓式余额水位阵列 + 底部文字轮播；悬停展开细读态行卡全景
- **细读态**：各厂商余额条 / 额度窗口 / 到期时间，本机 CPU·内存实时占用
- **显示模式**：轮播 / 固定厂商 / 固定单个 Key，墨仓焦点高亮联动
- **阈值告警**：余额/额度水位越线 → 黄/红分级，球描边与状态点变色
- **多账户支持**：单账户墨仓 + 逐 Key 帧、按账号独立刷新频率（全局默认 + 每 Key 覆盖）
- **设置面板**：Key 管理（增删改、掩码显示）、刷新频率、主题、仓可见性、贴边吸附、
  配置导入导出（Web 版格式兼容）
- **零打扰**：无弹窗（球上自灭横幅），单实例静默退出，二次启动唤醒原实例
- **安装包**：Inno Setup 一键安装，按用户免管理员，卸载保留配置

## 支持的厂商

| 厂商 | 类型 | 鉴权方式 | 字段 |
|------|------|----------|------|
| DeepSeek | 余额 | Bearer Token | `api_key` |
| 智谱 GLM | 额度 | Bearer Token | `api_key` |
| 火山方舟 | 额度 | AK/SK 签名 | `api_key` |
| MiniMax | 额度 | Bearer Token | `api_key` |
| 小米 MiMo | 额度 | 浏览器 Cookie | `api_key` |
| Kimi（Moonshot） | 余额 | Bearer Token | `api_key` |
| 硅基流动 | 余额 | Bearer Token | `api_key` |
| 腾讯混元 | 余额 | 腾讯云 SecretId/SecretKey | `access_key_id` + `secret_access_key` |
| 阿里百炼 | 余额 | RAM AccessKey（ACS3 签名） | `access_key_id` + `secret_access_key` |

> 说明：额度型厂商展示套餐剩余百分比与重置时间；余额型展示账户余额（CNY）。
> 未启用的厂商不会出现在菜单中。腾讯混元 / 阿里百炼需在云控制台开通对应账单权限
> （`bssapi:QueryAccountBalance` / 账户余额查询）。

## 快速开始

### 使用（最终用户）

直接运行安装包，或双击可执行文件（无需安装 Python）：

- 下载最新版：到仓库 **发行版（Releases）** 页面获取安装包
  `tokenorb-setup-<ver>.exe`（Gitee：<https://gitee.com/adv30/tokenorb/releases>），
  双击安装（无需 Python，按用户安装免管理员，卸载保留配置）
- 首次使用：挂件显示「点此添加 Key」→ 单击挂件打开面板 → 添加 API Key
- 单击挂件：展开 / 收起面板；悬停：细读态；右键：显示模式 / 立即刷新 / 设置 / 退出

### 从源码开发

#### 环境要求

- **Windows 10/11（x64）**——项目重度依赖 Win32 API（PDH 计数、GDI+、单实例 mutex），
  仅支持 Windows。
- **Python 3.11**（3.10+ 大概率可用，未作正式支持声明）。
- **依赖**：`pip install -r requirements.txt`（pywebview / pythonnet / psutil）。
- **Node.js**（可选，仅 `selftest.py::test_panel_js` 做面板 JS 语法回归用）。
- **WebView2 运行时**：Windows 11 一般自带；Windows 10 缺失时面板不可用但球仍可用。

#### 安装与运行

```powershell
cd desktop
python -m pip install -r ../requirements.txt   # 或 cd .. && pip install -r requirements.txt
python -X utf8 app.py          # 开发运行（悬浮球 + 面板）
```

#### 测试

```powershell
python -X utf8 selftest.py     # 纯逻辑单测（498 例，必须 0 失败）
python -X utf8 smoke.py        # 端到端冒烟（源码起 app.py + 独立 APPDATA；跑前先杀净残留实例）
```

> **注意**：smoke 用 `sys.executable -X utf8 app.py` 起源码实例，但单实例 mutex 是进程级
> 命名对象——本机若有正在运行的 `tokenorb` 实例（含旧版 exe），会撞掉 smoke 起的所有
> 测试实例（静默退出→假失败）。跑 smoke 前先杀净：`taskkill /f /im tokenorb.exe` 或
> `Get-Process tokenorb | Stop-Process`。

## 目录结构

```
desktop/                       桌面版（Python 3 + pywebview + GDI+）
  app.py                       入口（T-main = webview 泵，WinForms 球 + WebView2 面板）
  bridge.py                    js_api 桥（面板 <-> 核心）
  core/                        纯逻辑层：config / scheduler / aggregate / sysmon /
                               providers / theme / webview_patch / debuglog /
                               singleinstance / appmeta
  ui/                          渲染层：ball_window（原生 GDI+ 悬浮球）/ panel_html /
                               geom / theme / windows
  tools/                       构建工具：make_installer / patch_version / verify_providers
  docs/                        需求（REQUIREMENTS）+ 架构设计（DESIGN）+ 迭代分析与设计
  selftest.py                  纯逻辑单测（含面板 JS 语法回归）
  smoke.py                     端到端冒烟
balance_panel.py               Web 版面板（独立运行，端口 8787，桌面版不读写其配置）
CHANGELOG.md                   版本变更记录
LICENSE                        MIT 协议
```

## 打包交付

```powershell
cd desktop
# 1. PyInstaller 打包（onedir，--clean 干净重建）
python -m PyInstaller --clean --noconfirm --onedir --windowed --name tokenorb --paths .. `
  --distpath dist --workpath build --specpath build `
  --hidden-import webview.platforms.edgechromium --hidden-import webview.platforms.winforms app.py
# 2. exe 版本资源补丁（勿用 --version-file，嵌入损坏；make_installer 已内置防呆）
python -X utf8 tools/patch_version.py
# 3. 安装包（内置前置跑 patch_version）
python -X utf8 tools/make_installer.py
```

产物：`desktop/dist/tokenorb-setup-<ver>.exe`（按用户安装，无需管理员）。

完整交付流程（含打包后试跑、清理、提交红线）见 `AGENTS.md` §8。

## 配置与隐私

- 配置存于 `%APPDATA%\tokenorb\config.json`，**含明文 API Key**，不入库、不外发；
  导出文件同样含明文，需自行保管。
- 运行日志：`%APPDATA%\tokenorb\debug.log`（64KB 自截断，不含 Key）。
- 纯本机运行，不监听任何网络端口；exe 内不内嵌任何 Key 或个人配置。

## 文档

- 需求与验收标准：`desktop/docs/REQUIREMENTS.md`
- 架构设计总纲：`desktop/docs/DESIGN.md`
- 各功能迭代分析/设计：`desktop/docs/ANALYSIS-*.md`、`desktop/docs/DESIGN-*.md`
- 开发纪律与高频问题（含红线）：`AGENTS.md`

## 常见问题

**双击没反应 / 球看不见？**
- 多为后台残留实例占锁：`tasklist | findstr tokenorb` 查进程，结束旧实例后再启动；
  或看 `%APPDATA%\tokenorb\debug.log` 的 `singleinstance:` / `surface` 行。

**面板恒「加载中」？**
- 看 debug.log：球侧日志正常但无 `js:` 前缀 = 面板脚本未执行；跑 `desktop/selftest.py`
  可自动定位（node --check）。

## License

[MIT](LICENSE)