liuxianjin/ai-usage-widget：AI 使用量统计

English | 中文

一个 Windows 10/11 桌面悬浮小组件：实时显示 Codex、GLM（智谱）、Kimi、MiniMax 四家 AI 编程工具的官方订阅额度进度和本机 token 用量统计，常驻置顶，帮你一眼看到额度消耗，避免写代码写到一半撞限。

如果你同时订阅了多家 AI 编程套餐（5 小时窗口 + 每周窗口），一定会遇到这些问题：不知道当前窗口还剩多少额度、不知道什么时候重置、切换工具时不知道该省着用哪个。这个小组件把四家的额度聚合到一块置顶悬浮窗里，按官方数据实时显示。

功能特性

官方额度优先：直接查询各家官方接口，显示实际窗口（5 小时 / 每周）、剩余百分比和重置倒计时；支持多额度桶。
本机 token 统计：扫描各工具本地会话日志，按源统计最近 5 小时和最近 7 天的 token 消耗，与官方额度相互独立、互为印证。
估算进度：在「设置」中为某源手填 token 上限后，本机统计可显示估算进度条（明确标注「估算」，与官方额度区分）。
诚实的状态标注：查询失败时显示本地日志中的历史快照并注明「账户未核验」；超过 180 秒未更新标为「已过期」；到达重置点后等待服务端数据，不自行归零；缺失数据显示「未知」，不推定为 0%。
悬浮窗交互：无边框、置顶、标题栏拖动、透明度 20%～100% 可调、刷新间隔 30/60/120/300 秒可选。
贴边收拢：标题栏图钉弹起后，窗口贴屏幕右缘自动隐藏（仅留 2px 边缘），鼠标移到右缘滑出，移开约 0.8 秒后收回。
常驻系统托盘：不占任务栏；托盘右键提供显示/隐藏、立即刷新、设置与退出，单击切换显隐。
窗口内滚动：高度不超过任务栏，内容超出时鼠标滚轮上下滚动（无滚动条）。

支持的数据源

数据源	官方额度	本机 token 统计	前置条件
Codex（OpenAI）	✅ 通过本机 Codex CLI 的官方 App Server 查询	✅	安装并登录 Codex CLI
GLM（智谱 Coding Plan）	✅ 自动发现或手动粘贴 Coding Plan token	✅	智谱 Coding Plan 订阅
Kimi	✅ 复用本机 kimi CLI 登录凭据	✅	安装并登录 kimi CLI
MiniMax	✅ 复用本机 mcode 登录凭据	✅	安装并登录 mcode

各源的官方额度查询相互独立：某一家未登录或查询失败，只影响该源（显示原因或回退本机统计），不影响其他源。

快速开始

方式一：直接运行预构建 exe（推荐）

到 Releases 下载 AIUsageWidget.exe（单文件，约 45 MB）。
双击运行。首次运行 Windows SmartScreen 可能提示「已保护你的电脑」，点「更多信息」→「仍要运行」即可（exe 未做代码签名，属正常提示）。
确认对应 CLI 已登录（见上表前置条件），小组件会自动发现并显示官方进度。

配置保存在 %LOCALAPPDATA%/AIUsageWidget/；卸载删掉 exe 和该目录即可。

方式二：从源码运行

需要 Windows 10/11、Python 3.11+。在项目根目录的 PowerShell 中执行：

python -m venv .venv
.venv/Scripts/python.exe -m pip install -r requirements.txt
.venv/Scripts/python.exe app.py

安装完成后可双击 run.bat，不打开控制台窗口。关闭后会保存窗口位置、透明度和刷新间隔。

各数据源配置说明

Codex：全自动。从 PATH 和标准 npm 安装位置寻找原生 Codex CLI；未找到时可用环境变量指定：
```
$env:AI_USAGE_CODEX_EXE = 'C:/absolute/path/to/codex.exe'
```
AI_USAGE_CODEX_EXE 只接受原生 exe 的绝对路径，不接受 .cmd 或 .ps1。日志路径遵循已有 CODEX_HOME，默认 %USERPROFILE%/.codex/sessions/。
GLM（智谱 Coding Plan）：自动发现在环境变量或 Claude Code 配置中、且 base URL 指向智谱官方域名（open.bigmodel.cn / api.z.ai）的 Coding Plan token（即「用智谱套餐跑 Claude Code」的配置）；没有发现的，在小组件「设置」里粘贴一次订阅 token（智谱订阅配置里的 ANTHROPIC_AUTH_TOKEN）。第三方中转站的 token 不会被使用。手动粘贴优先，token 仅保存在本机设置文件，只用于额度查询、不写日志。
Kimi / MiniMax：全自动。直接使用本机 kimi / mcode 的登录凭据查询官方额度；token 过期时按官方流程自动续期并把轮换结果原子写回凭据文件（与对应 CLI 行为一致），全程不复制凭据。未登录时显示原因并回退本机统计。

数据含义和边界

显示	含义
官方额度	服务端最近一次返回的额度百分比，按实际额度桶和窗口展示
日志快照，账户未核验	查询失败后的历史参考值，可能来自此前登录的账户
已过期	额度超过 180 秒未更新，不能作为当前剩余额度判断
待刷新	旧窗口已到重置时间，等待新数据
暂无额度数据／未知	登录方式不支持、字段缺失或当前读取失败，不代表 0%
估算 x%	本机 token 除以您在设置中填写的上限得到的估算值，不是官方额度
Codex 本机 token	扫描最近 7 天修改的本地 rollout 文件，累计增量去重后的统计
GLM、MiniMax 本机 token	逐请求 input+output+缓存读写合计，缓存读写按真实处理量计入
Kimi 本机 token	上下文快照累计，近似输入消耗、不含输出（Kimi 日志未提供逐轮增量）
无本地数据	对应工具的数据目录不存在或最近无使用

80% 起用黄色，95% 起用红色。未知、过期和等待重置的窗口不显示有效进度条。5 分钟刷新间隔可能在下一次查询前显示过期，这是正常的保守提示。

本机统计不包含其他设备、未落盘请求及已删除日志；日志损坏、首次累计基线无法恢复时会注明不完整。复制的相同用量事件按时间和累计字段指纹去重；修改或删除历史日志会改变统计结果。官方查询超时为 12 秒。

隐私与安全

只读本机：四个工具的数据目录分别为 Codex %USERPROFILE%/.codex/sessions/、GLM %USERPROFILE%/.zcode/cli/rollout/、Kimi %USERPROFILE%/.kimi-code/sessions/、MiniMax %USERPROFILE%/.minimax/v2/sessions/，均只读取用量与额度字段，不读取会话正文和凭据。
不复制凭据：对 kimi / mcode 的凭据文件只在续期时按官方流程原子写回轮换结果，行为与对应 CLI 一致；不把凭据写到日志或其他位置。
不上传、不外发：所有查询只发往各家的官方额度接口，不发起模型请求，没有遥测和统计上报。
配置最小化：%LOCALAPPDATA%/AIUsageWidget/settings.json 仅保存界面设置（位置、透明度、间隔、手动填写的上限和 GLM token）。损坏配置回退默认值。

开发

.venv/Scripts/python.exe -m pip install -r requirements-dev.txt
.venv/Scripts/python.exe -m unittest discover -s tests -v    # 84 个单元测试，全部合成数据
.venv/Scripts/python.exe tests/smoke_widget.py               # 原生窗口冒烟 + 实时截图
.venv/Scripts/python.exe -m PyInstaller --noconfirm ai_usage.spec

单元测试不需要任何账户；smoke_widget.py 会短时打开原生窗口、只读查询真实额度并截图。构建产物为 dist/AIUsageWidget.exe，不内嵌 CLI、认证信息或会话日志。

项目结构：

app.py              # 入口：悬浮窗、托盘、后台刷新、右键菜单
presentation.py     # 显示与文案格式化
providers/          # 各数据源：base.py 数据契约；codex/glm/kimi/minimax
aggregator.py       # 本机 token 窗口聚合与去重
config.py           # 设置校验与原子持久化
tests/              # 标准库 unittest，合成数据
docs/superpowers/   # 设计文档（specs）与实施验证记录（plans）

设计文档入口：docs/superpowers/specs/；Codex 官方协议参考：App Server 文档。