Codex Usage Widget / Codex 用量桌面小组件

一个用于 Windows 桌面右下角悬浮显示 的 Codex 用量小组件。
A lightweight Windows desktop floating widget for monitoring Codex usage.

本次更新 / What's New

• 更清晰的日间/夜间界面：根据背景亮度自动切换文字、状态和圆环底轨颜色，浅色背景也能读清楚。
  Better day/night readability with adaptive text and ring colors.
• 后台刷新：网络请求放到后台 Job，不会因为接口慢或网络波动卡住悬浮窗。
  Background refresh keeps the widget responsive.
• 更安全的认证写回：access token 过期时刷新 token，并在写认证文件前备份、加锁、原子写入。
  Safer auth refresh with backup, file lock, and atomic writes.
• 配置/缓存迁移到 AppData：运行时文件保存到 %LOCALAPPDATA%\CodexUsageWidget，项目目录保持干净。
  Runtime config/cache now live under AppData.
• 更好的发布体验：新增便携 zip 构建脚本，可选择把抓取脚本打包成 tools\codex_usage_fetch.exe。
  Release packaging now supports a portable zip with an optional bundled exe.
• 工程化补齐：新增测试、检查脚本、版本文件、Changelog、License、GitHub Actions CI 和自动 release workflow。
  Added tests, checks, metadata, changelog, license, CI, and release workflow.

---

界面预览 / Preview

日间模式 / Day mode	夜间模式 / Night mode

截图为示例数据，仅用于展示界面效果。
The previews use sample data and are for UI demonstration only.

---

功能特点 / Features

• 显示 5 小时窗口与 7 天窗口的用量百分比（已用/剩余）
  Shows usage for both 5-hour and 7-day windows (used/remaining).
• 每 60 秒自动刷新
  Auto-refreshes every 60 seconds.
• 后台刷新，不因网络请求卡住悬浮窗
  Refreshes in the background so the widget UI stays responsive.
• 支持透明度调节（20%~100%）
  Adjustable opacity (20%~100%).
• 支持图层切换（始终置顶 / 普通层级）
  Layer mode switch (always-on-top / normal).
• 自动跟随系统明暗主题颜色
  Adapts to system light/dark theme.
• 游戏模式（自动检测全屏 + 手动强制显示/隐藏，手动优先）
  Game mode (auto full-screen detection + manual force show/hide, manual override has priority).
• 网络异常时使用本地缓存数据显示
  Falls back to cached data when network requests fail.
• 配置与缓存保存到用户 AppData，不污染项目目录
  Stores generated config/cache under the user's AppData folder.
• token 刷新写回前会备份并原子写入认证文件
  Backs up and atomically writes auth files when refreshing tokens.

---

项目结构 / Project Structure

• codex_usage_widget.ps1：桌面悬浮窗主程序
  Main PowerShell widget UI.
• codex_usage_fetch.py：请求 Codex usage 接口并返回 JSON
  Fetches Codex usage data and returns JSON.
• 启动Codex用量桌显.bat：一键启动入口（Windows）
  One-click launcher on Windows.
• widget_config.json：界面配置（自动生成）
  UI config file (auto-generated, stored in %LOCALAPPDATA%\CodexUsageWidget).
• last_usage.json：最近一次成功数据缓存（自动生成）
  Last successful usage cache (auto-generated, stored in %LOCALAPPDATA%\CodexUsageWidget).
• tests/：核心 Python 逻辑的轻量测试
  Lightweight tests for the Python usage parser/cache behavior.

---

使用方法 / How to Use

中文

1. 从 Releases 下载 CodexUsageWidget-*.zip 并解压。
2. 确保你已在本机完成 Codex CLI / Codex 桌面相关环境登录，并生成 ~/.codex/auth.json 或 ~/.hermes/auth.json。仅网页版 ChatGPT 登录通常无法使用，因为本工具读取的是本地认证文件，不读取浏览器 cookie。
3. 双击 启动Codex用量桌显.bat。
4. 右下角出现悬浮窗后，可右键调整透明度与图层。
5. 双击悬浮窗可关闭。

English

1. Download CodexUsageWidget-*.zip from Releases and unzip it.
2. Make sure Codex CLI or a Codex desktop-related environment has authenticated on this machine and created ~/.codex/auth.json or ~/.hermes/auth.json. Logging in only through the ChatGPT website usually is not enough because this widget reads local auth files, not browser cookies.
3. Double-click 启动Codex用量桌显.bat.
4. Right-click the widget to change opacity and layer mode.
5. Double-click the widget to close it.

---

依赖 / Requirements

• Windows 10/11
• PowerShell 5+
• Python 3.x

---

开发与验证 / Development

运行完整检查：

.\scripts\check.ps1

构建便携 zip 包：

.\scripts\build_release.ps1

如果想把 Python 抓取脚本打成单文件 exe，一起放入 release 包：

.\scripts\build_release.ps1 -InstallPyInstaller

生成的 zip 位于 dist\CodexUsageWidget-<version>.zip。如果包内存在 tools\codex_usage_fetch.exe，小组件会优先使用它；否则会回退到本机 Python。

CI 会在 GitHub Actions 上运行 scripts/check.ps1。推送 v* tag 时会自动构建 zip 并发布到 GitHub Releases。

---

说明 / Notes

• 本项目依赖 ChatGPT/Codex 的本地认证文件与非公开 usage 接口；这些结构可能随官方客户端更新而变化。
  This project depends on local ChatGPT/Codex auth files and non-public usage endpoints, so it may need updates when the official client changes.
• 本项目读取本机已有认证文件，不需要在代码里硬编码 token。
  This project uses local existing auth files and does not require hardcoding tokens in code.
• 仅网页版 ChatGPT 登录不会自动生成本项目需要的本地认证文件。
  A browser-only ChatGPT login does not automatically create the local auth files required by this widget.
• 建议不要提交个人认证文件到仓库。
  Do not commit personal auth credentials to the repository.
• 如果 access token 过期，脚本会使用 refresh token 刷新，并在写回认证文件前创建 .bak 备份。
  When the access token expires, the script refreshes it and creates a .bak backup before writing the auth file.

---

License

MIT（可按需改成你自己的许可证）
MIT (you can change this to your preferred license).