Codex Remaining Credit Monitoring Tool

一个面向 Windows 10/11 的轻量桌面组件：仅在 Codex 桌面窗口处于前台时显示剩余额度，切换到其他应用后立即隐藏。

v0.1.0 功能

• 通过本机 Codex App Server 读取主要与次要额度窗口、剩余百分比和重置时间。
• Codex 前台时显示，离开 Codex 后隐藏；隐藏期间停止主动读取。
• 220 × 82 的紧凑悬浮窗，正常状态鼠标穿透，不阻断 Codex 点击。
• 优先停靠在 Codex 窗口外侧；屏幕空间不足时贴边显示。
• 支持多显示器、负坐标显示器和 Per-Monitor V2 DPI 缩放。
• 托盘支持立即刷新、移动/重置位置、UI Automation 降级、开机启动和退出。
• 主数据源失败时可选用 UI Automation 降级；只接受严格匹配的额度文本。
• 不读取、复制、记录或提交 Codex Token、浏览器 Cookie 和登录凭据。

运行前提

1. Windows 10/11 x64。

2. 已安装并登录 Codex 桌面应用。

3. 安装官方独立 Codex CLI，用于启动本地 App Server：

   npm install --global @openai/codex@latest
   codex --version

Windows Store 版 Codex 内置的 codex.exe 受包权限保护，普通桌面程序不能直接执行。因此本工具会优先发现官方 npm CLI，并主动排除受保护的 WindowsApps 路径。

安装与使用

1. 将发布压缩包解压到稳定目录，建议：

   C:\Users\Starry\Apps\CodexQuotaMonitor
   

2. 运行 CodexQuotaMonitor.exe。发布版本首次运行后默认注册当前路径为用户级开机启动项；Debug 构建不会注册。

3. 打开或切回 Codex。组件会自动显示并读取额度；切换到其他应用后自动隐藏。

4. 若要移动，右键托盘图标，选择“移动组件位置”，拖动组件并松开。正常模式随后自动恢复鼠标穿透。

5. 右键托盘图标选择“重置组件位置”，可恢复自动停靠。

请先把程序放到最终目录再首次运行，否则开机启动项会指向临时解压路径。

隐私边界

• 组件只启动官方 codex app-server 子进程，通过标准输入/输出发送协议请求。
• Codex CLI 自行使用现有登录状态；组件不打开或解析 auth.json、浏览器数据或系统凭据。
• App Server 标准错误输出被直接丢弃，不写日志。
• UI Automation 只保留严格匹配后的数字结果，不记录未匹配的界面文字。
• 本地缓存、构建产物、日志探针、work/ 与 outputs/ 均被 Git 忽略。

开发验证

dotnet restore CodexQuotaMonitor.sln --configfile NuGet.Config
dotnet test tests\CodexQuotaMonitor.Core.Tests\CodexQuotaMonitor.Core.Tests.csproj
dotnet build CodexQuotaMonitor.sln --no-restore

本机 App Server 集成测试不会输出额度值，仅验证发现、握手和解析是否成功：

$env:RUN_CODEX_INTEGRATION_TESTS = '1'
dotnet test tests\CodexQuotaMonitor.App.Tests\CodexQuotaMonitor.App.Tests.csproj --no-restore

架构和协议边界见 docs/ARCHITECTURE.md。

版本与回滚

可运行版本使用语义化 Git 标签，例如 v0.1.0。发布历史不会强制改写；需要回滚时，可从对应标签重新下载或构建。