把 Codex / Gemini 等额度显示在 Windows 任务栏上的小挂件。
纯标准库实现，不装任何第三方包。不依赖 TrafficMonitor，也不依赖任何第三方插件。
- 多个数据源竖排在一个挂件里，宽度只取最宽的一行，加源不横向拉长
- 颜色预警：剩余 >30% 绿 ／ >10% 黄 ／ ≤10% 红，离线灰
- 点一下立即重新查询（跳过缓存真正打上游），边框会闪一下做反馈
- 悬停显示明细：已用百分比、重置倒计时、周用量、上次查询时间
- 自动避让：会扫描任务栏上已有的挂件（TrafficMonitor 等），自动排到它们左边
- 系统图标优先：任务按钮区会随窗口变宽，塞不下时挂件自动降级成悬浮球，浮在任务栏上方
- 拖动可移动，松手靠近任务栏自动吸附；右键出菜单
- 开机自启、单实例保护、画布自愈、日志自动轮转
挂件本身不联网，中间有一个本地取数服务：
┌────────────────┐ HTTP ┌──────────────────┐ POST/GET ┌──────────────┐
│ 任务栏挂件 │ ────────▶ │ 本地取数服务 │ ─────────▶ │ 上游代理 │
│ codex_quota_bar │ 127.0.0.1│ quota_bridge.py │ │ (你的 API 代理) │
└────────────────┘ /all └──────────────────┘ └──────────────┘
只负责显示 解析 / 算剩余 / 倒计时 转发到 ChatGPT 等
为什么分两层： 上游返回的 body 有时是一段转义过的 JSON 字符串，
第三方 TrafficMonitor 插件的 JSONPath 没法穿透它，而且插件也不支持
100 - used_percent 这类运算。拆成两层后，挂件这一层保持零依赖，
换上游代理也不用改代码 —— 只改 config.json。
取数服务还做了三件事：按源分别缓存（默认 90 秒）、 按缓存时间戳扣减倒计时（倒计时走真实时间，不因刷新间隔而卡顿）、 强制刷新防抖（8 秒内重复强制只打一次上游，手抖点不烂）。
任务栏塞得下 -> 两行药丸，贴在托盘左侧
任务栏塞不下 -> 46px 悬浮球，浮在任务栏上方
判定依据是任务按钮区右沿到托盘左沿之间的实际空隙（taskbar_gap()）。
空格不够就自动降级，窗口开关导致空隙变化时会在两种形态之间自动切换，
任何时候都不会盖住系统的任务按钮或托盘图标。
- Windows 10 / 11
- Python 3.10 以上（用标准安装包即可，自带 tkinter）
- 一个（或多个）能访问 ChatGPT / Gemini 的上游代理
两种数据源类型：
kind: "codex" —— 走 Sub2API / CLIProxyAPI 这类转发接口：
{
"id": "codex",
"label": "Codex",
"kind": "codex",
"proxy": "http://你的代理:8317",
"management_key": "代理的管理密钥（X-Management-Key）",
"auth_index": "该代理里 Codex 账号的 auth_index"
}kind: "gptquota" —— 直连一个已经算好百分比的 /quota 接口：
{
"id": "gemini",
"label": "Gemini",
"kind": "gptquota",
"url": "http://你的代理:8318/quota",
"headers": { "Content-Type": "application/json" }
}后者期望返回
gemini/claude_gpt两个对象， 各含pct_remaining_5h、pct_remaining_week、reset_5h、reset_week。
怎么拿
auth_index： 用管理密钥调代理的GET /v0/management/auth-files，返回里type为codex的那条， 它的auth_index字段就是要填的值。
- 把整个文件夹复制到任意位置（建议
D:\Software\CodexQuotaBridge这类简单路径） - 把
config.example.json复制成config.json，填好上面那三项 - 双击
install.bat
install.bat 会自动探测常见的 Python 安装路径，先自检配置和连通性，
通过了才写入开机自启并启动；任何一步失败都会停下来告诉你原因。
| 键 | 默认值 | 说明 |
|---|---|---|
sources |
— | 数据源数组，必填。每项一个，顺序即显示顺序（从上到下） |
bridge_port |
28317 |
本地取数服务端口，被占用就改 |
refresh_seconds |
30 |
挂件刷新频率（秒） |
cache_seconds |
90 |
实际查询上游的间隔（秒），按源分别缓存 |
log_file |
quota_bridge.log |
日志文件名 |
refresh_seconds 和 cache_seconds 分开设，是为了让倒计时走得平滑
又不至于频繁打上游。
删掉某个源就是从数组里去掉那一项，重新跑 install.bat 即可。
| 操作 | 方式 |
|---|---|
| 立即重新查询 | 单击挂件（真打上游，不是拿缓存；边框会闪一下） |
| 看明细 | 鼠标悬停 |
| 移动位置 | 按住拖动，松手靠近任务栏会自动吸附 |
| 改刷新间隔 / 开机自启 / 退出 | 右键菜单 |
python codex_quota_bar.py --check 自检配置并试拉一次数据
python codex_quota_bar.py --install 写开机自启并启动
python codex_quota_bar.py --uninstall 取消自启并停止
python codex_quota_bar.py 直接启动（不加自启）双击 uninstall.bat。它会取消开机自启并停掉进程，文件保留。
想彻底删掉就直接删整个文件夹。
| 文件 | 作用 |
|---|---|
codex_quota_bar.py |
挂件本体，只负责显示，不联网 |
quota_bridge.py |
本地取数服务 |
config.example.json |
配置模板（复制成 config.json 使用） |
install.bat / uninstall.bat |
一键安装 / 卸载 |
quota_bridge.log |
取数服务日志，超过 256KB 自动轮转 |
widget.log |
挂件日志：异常、看门狗自愈记录 |
bar.pid / bridge.pid |
运行时 PID，供卸载脚本精确定位 |
任务栏上没有出现
先跑 python codex_quota_bar.py --check。取数正常但看不到挂件的话，
多半是有别的工具占了位置 —— 右键菜单选「重新贴回任务栏」。
通常等 15 秒会自己恢复：挂件内置了看门狗，每 15 秒检查一次画布，
发现画布空了（比如锁屏/休眠唤醒后 Tk 丢绘制）就自动重建，
并重新抢一次置顶。恢复过程会记到 widget.log：
[2026-10-15 08:15:37] [TEST] artificially blank the canvas, verify watchdog self-heal
[2026-10-15 08:15:47] 检测到画布为空，自动重建
挂件用
pythonw.exe运行，没有 stderr，所以异常全部落在widget.log。 挂件看起来空白但进程还在时，先看这个文件。
显示「-- 离线」
quota_bridge.log 里有具体错误。多数是上游代理不可达或密钥过期。
端口被占用
改 config.json 里的 bridge_port。
能不能同时看多个账号 / 多家服务
可以，sources 里加几项就行，竖着排显示。每个源有独立的缓存和独立的状态色。
同一个上游的多个 Codex 账号，就是加两条 kind: "codex"、不同的 auth_index。
挂件变成悬浮球了
任务按钮太宽，空隙塞不下两行药丸就会自动降级。把窗口收一收就会变回药丸， 或者直接在药丸模式下按住拖到喜欢的位置（手动拖过之后系统不再自动挪它）。
会不会和 TrafficMonitor 打架
不会。定位时会枚举任务栏的子窗口，找出第三方挂件（含 TrafficMonitor
挂在 Shell_TrayWnd 下的那个），把自己放到它们左边。
config.json 里的 management_key 是等价于账号密码的凭据。
- 它已经在
.gitignore里，不要手动git add -f - 不要把它提交到任何公开仓库
- 不要贴进 issue、日志截图、网盘公开链接
MIT