核心概念
Provider
Provider 是额度来源类型，例如 CLIProxyAPI、火山引擎和千问。不同 Provider 的认证方式、接口结构和额度窗口都不一样，TokenBall 会在后端统一标准化。
实例
实例是某个 Provider 的具体连接配置。例如：
- 本机 CLIProxyAPI
- 远程 CLIProxyAPI
- 火山引擎主账号
- 千问 Token Plan 个人账号
一个 Provider 可以配置多个实例。
账号
账号是实例下具体产生额度的对象。CLIProxyAPI 下通常是多个 Codex 账号；火山引擎下可能是 Coding Plan 或 Agent Plan；千问下是个人版 Token Plan。
额度窗口
额度窗口表示一段统计周期，例如 5 小时、每周、每月或上游返回的自定义窗口。每个窗口可以包含：
- 总量
- 已用量
- 剩余量
- 剩余百分比
- 重置时间
- 单位，例如 percent、token、request、credit、afp
当前关键窗口
当前关键窗口是当下最限制继续使用服务的额度窗口。TokenBall 会优先选择上游明确标记的限制窗口；如果没有标记，则选择剩余百分比最低的窗口。
示例：
| 窗口 | 剩余 |
|---|---|
| 5 小时 | 18% |
| 每周 | 63% |
| 每月 | 81% |
此时 TokenBall 会把 5 小时 作为关键窗口，因为它最先限制继续使用。
总剩余额度
总剩余额度用于悬浮球主显示，它基于启用账号的关键窗口计算。它不是简单代表某个平台官方总额度，而是一个用于快速判断当前可用性的桌面摘要。
缓存数据
当网络、认证或上游接口异常时，TokenBall 会保留上次成功同步的数据，并在界面上标记缓存或降级状态，避免把未知状态误显示为 0%。