Codex Token 日报桌面组件

一个只使用 Python 标准库的 macOS 悬浮小窗。它只读扫描本机 Codex 会话日志，按北京时间汇总每日 token，并根据本地价格配置估算 USD 金额。当前 pricing.json 使用 OpenAI 官方 API 标准档价格（来源和抓取日期已写入配置）；如果经代理转发，实际账单可能与公开标准价不同。窗口采用中性炭灰和冰蓝配色，摘要、估算金额与模型明细分层展示；macOS 系统自带 Python 3.9 的 Tk 8.5 无法正常绘制内容时，启动脚本会自动切换到本机已有的 Tk 9 运行时。

界面的 token 数量使用中文单位：满一亿显示“亿”（最多三位小数），满一万显示“万”（最多两位小数），不足一万显示整数。例如 346,200,000 显示为“3.462 亿”。

启动

已在本机创建的 Token 日报.app 快捷方式可以双击启动，组件已运行时会尝试唤起现有窗口。该快捷方式和 launch_widget.applescript 绑定本机路径，仅保留在本机，不纳入 Git 仓库；克隆仓库后请按下面的源码命令启动。

在项目目录执行：

python3 run_widget.py

如果系统 python3 是 macOS 自带的 Tk 8.5，窗口入口会自动切换到本机已有的 Tk 9；--once 控制台模式不会打开窗口，也不会切换解释器。

窗口宽 400px，默认高度 493px，提示信息和展开明细会增加高度。标题栏可以拖动，左侧两个灰色按钮分别关闭和最小化，第三个灰点仅为装饰。窗口默认置顶，可通过“窗口”菜单或右键菜单取消置顶；最小化后可在“窗口 → 显示窗口”恢复。

启动时加载今天的数据；顶部“今天 / 昨天”切换统计日期，“按模型明细”展开模型卡片，“刷新”立即重新扫描，默认每 15 分钟自动更新。列表超过可用屏幕高度时滚动显示，底部收起和刷新按钮保持可达。

使用 Tab 在日期、明细、刷新和模型列表之间移动焦点，空格激活按钮；模型列表聚焦后支持方向键、Page Up / Page Down、Home / End，也可使用鼠标滚轮。Command-M 最小化，Command-W 或 Command-Q 退出组件。

控制台检查

不打开窗口时执行：

python3 run_widget.py --once

价格配置

编辑 pricing.json，键名使用日志中的模型名，单位是 USD / 1M tokens：

{
  "gpt-example": {
    "input_per_million": 2.0,
    "cached_input_per_million": 0.2,
    "output_per_million": 10.0,
    "source": "官方价格页（填写日期）"
  }
}

cached_input_tokens 是 input_tokens 的子集；金额计算为：

(input_tokens - cached_input_tokens) * input_price
+ cached_input_tokens * cached_input_price
+ output_tokens * output_price

全部模型缺少完整公开单价时显示“无法估算”；部分缺价时显示“已知模型小计”并提示“部分模型无公开单价”，未知模型的金额为“—”。无记录时总量为 0、金额为“—”。未知金额不会假设为 0，日志异常与缺价提示可以同时显示。

Codex 在上下文重载或设置变更时可能写入一条总 token 有值、但输入/缓存/输出/推理分项全为 0 的元数据记录；组件会忽略这类记录，避免总量与分项不一致。

也可以用环境变量覆盖默认配置：CODEX_WIDGET_TZ（默认 Asia/Shanghai）、 CODEX_WIDGET_PRICING（价格 JSON 路径）和 CODEX_WIDGET_REFRESH_SECONDS（默认 900 秒，最小 60 秒）。

测试

PYTHONPYCACHEPREFIX=/tmp/codex-token-widget-pycache python3 -m compileall -q src run_widget.py
python3 -m unittest discover -s tests -v

图形状态回归测试默认跳过。在有桌面会话且 Python 使用 Tk 8.6 或更新版本的环境中可显式运行：

CODEX_WIDGET_GUI_TESTS=1 python3 -m unittest discover -s tests -v

这些测试使用合成报告，不读取个人会话日志。

可选：登录后自动启动

如果希望登录 macOS 后自动打开窗口，可以手动创建 ~/Library/LaunchAgents/com.codex.token-widget.plist，将下面的路径替换为本项目的绝对路径：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.codex.token-widget</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/bin/python3</string>
    <string>/绝对路径/codex-token-widget/run_widget.py</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><false/>
</dict>
</plist>

加载或移除 LaunchAgent 属于系统级操作，组件不会自动执行。需要启用时可手动运行：

launchctl load ~/Library/LaunchAgents/com.codex.token-widget.plist

数据与隐私

组件只读 ~/.codex/sessions 和 ~/.codex/archived_sessions，不上传、不修改或删除日志。组件不发送飞书消息；飞书日报自动化是独立流程。

当前实现是桌面悬浮小窗，不是 WidgetKit 系统小组件。桌面启动器调用本项目源码与本机 Python，尚非独立安装包。