Garmin AI 用量表盘 — 项目交接

在 Garmin Forerunner 955 手表上一屏显示 Claude Code 和 Codex(GPT) 的 5 小时 / 7 天剩余额度和重置时间，同时显示时间、心率、电量。 VPS 定时在 tmux 里启动两个 CLI、抓取 /usage、/status 的屏幕输出，解析后写成 JSON；手表通过手机上的 Garmin Connect 拉这份 JSON。 本页可以独立读懂，不依赖任何历史会话。

目录

1. 先判断是哪一边的问题：手表屏幕上是右上角小红 !（网络请求失败）还是整屏 IQ! 大图标（程序崩溃）？处理路径完全不同，见 ⑧。
2. 在 VPS 上看数据：curl https://www.edmundhuang.xyz/void/api/v2/garmin/usage，看是不是 200、updated_at 新不新、字段格式有没有变化；再 tail -4 logs/garmin-usage.log 看 cron 有没有按时写。
3. 改 VPS 端（解析、格式、频率）：直接在 VPS 上改 workspace/garmin-watchface/vps/parse_usage.py 或 crontab，立即生效，手表不用动。
4. 改手表端（布局、逻辑）：只能在 Mac 上编译（VPS 没有 SDK），流程见 ⑨。改完先在模拟器验证，再侧载到真机。
5. 能在 VPS 端解决的，优先在 VPS 端解决：手表重新侧载要连 Mac、走 MTP，成本高。

┌─ VPS（日本东京，系统时区 Asia/Tokyo）────────────────────────────┐
│ cron → vps/parse_usage.py                                           │
│   ├─ tmux 里跑 `claude` → 发 /usage  → capture-pane → 正则解析      │
│   ├─ tmux 里跑 `codex`  → 发 /status → capture-pane → 正则解析      │
│   ├─ 时区换算 Asia/Tokyo → Asia/Bangkok，7D 重置时间转成星期        │
│   └─ 写 vps/usage.json（某字段解析失败 → 沿用上一轮旧值）           │
│ void-webui（FastAPI）GET /void/api/v2/garmin/usage → 原样返回该文件 │
│ nginx https://www.edmundhuang.xyz 反代                              │
└─────────────────────────────────────────────────────────────────────┘
                 ▲ HTTPS（UA: ConnectMobile，机主手机是 iPhone）
┌─ 手机 Garmin Connect ──┐   手表本身不能上网，全靠手机中转；
└────────────▲───────────┘   App 在后台被杀或蓝牙断了，请求就失败
             │ 蓝牙
┌─ fr955 手表 AIUsage widget ─────────────────────────────────────────┐
│ 打开时拉一次（按 UP/DOWN/SELECT 手动刷新）→ DataModel 缓存         │
│ UsageView 每秒重绘（时钟、心率、电量都在手表本地读）               │
└─────────────────────────────────────────────────────────────────────┘

要点：手表拿到的永远是 VPS 上的缓存，不是实时值，最坏会滞后一个 cron 间隔。接口不加鉴权，因为 widget 发不了 Authorization 头；数据只有用量百分比，不敏感。

{
  "claude": { "5h_pct": 97, "7d_pct": 91, "reset_5h": "21:59", "reset_7d": "TUE 11:00" },
  "gpt":    { "5h_pct": 100, "7d_pct": 99, "reset_5h": "21:55", "reset_7d": "MON 08:27" },
  "updated_at": "2026-09-30 19:28"
}

⚠️ 任何字段类型或格式的改动都可能让已经装在表上的旧 widget 崩溃（Monkey C 没有异常兜底，一出错就是 IQ!）。改格式前先读 UsageView.mc 里对应字段的处理代码。

SDKBIN="$HOME/Library/Application Support/Garmin/ConnectIQ/Sdks/connectiq-sdk-mac-9.1.0-2026-03-09-6a872a80b/bin"
WIDGET="$HOME/works/the-void/workspace/garmin-watchface/garmin-widget"

# 编译（fr955）
"$SDKBIN/monkeyc" -f "$WIDGET/monkey.jungle" -o "$WIDGET/AIUsage.prg" -d fr955 -y "$HOME/garmin-keys/developer_key.der"

# 模拟器：先开模拟器，窗口出来后再推送（模拟器走 Mac 网络，能拉到 VPS 真实数据）
open "$SDKBIN/ConnectIQ.app"
"$SDKBIN/monkeydo" "$WIDGET/AIUsage.prg" fr955

# 真机：手表 USB 连 Mac（MTP）→ 用 OpenMTP 把 AIUsage.prg 拷进 GARMIN/APPS/ → 断开