opencode-usage-watchdog

一个盯着 OpenCode Go / Zen API 额度的静默看门狗。平时一句话不说， 只有真正需要注意的时候才开口。单文件、只用 Python 标准库。

它是干什么的

• 定时查询官方额度接口 GET https://opencode.ai/zen/go/v1/usage（Bearer 认证）
• 静默契约：没有输出 = 一切正常（空 stdout）。只有这些情况才打印报告：
  • 任一窗口的用量变化 ≥ 2 个百分点 → 🔄 变化报告
  • 任一窗口 ≥ 85%，或配额状态不是 ok → ⚠️ 告警
  • 任一窗口落在 70%–84% → ⚡ 预警
  • 每个 UTC 日的第一次检查 → 📊 日报
  • 有史以来第一次运行 → 📡 首报（顺便证明链路是通的）
• 把百分比换算成美元（Go 套餐上限：5 小时滚动 $12 / 每周 $30 / 每月 $60）
• 每次成功检查往历史文件追加一行 JSON，方便以后看趋势
• 拉取失败限速报告：一小时最多一条，不刷屏
• 使用浏览器 User-Agent：该接口在 Cloudflare 后面，非浏览器 UA 会被 403

镜子 vs 闹钟

	界面类工具（镜子）	本脚本（闹钟）
工作方式	把额度数字显示在仪表盘 / 状态栏 / 侧边栏	后台定时检查
谁找谁	你要自己打开界面去看	有事它主动找你
阈值提醒	一般没有	85% 告警 / 70% 预警 / 2pp 变化

镜子要靠自己去看，闹钟到点会叫你。

也说实话：界面类工具有好看的 UI；本脚本没有界面，只输出纯文本， 适合配合定时任务把输出推到聊天工具里。

要求

• Python 3（只用标准库，不需要 pip install 任何东西；已在 Python 3.11 上测试）
• 一个 OpenCode Go / Zen 的 API key
• 可选：Hermes Agent（用它的 cron 把报告投递到聊天工具；脚本本身完全独立）

安装

mkdir -p ~/.hermes/scripts
cp opencode_usage_monitor.py ~/.hermes/scripts/

配置 API key

按优先级从高到低，找到第一个就停：

1. 环境变量 OPENCODE_GO_API_KEY 或 OPENCODE_ZEN_API_KEY
2. $HERMES_HOME/.env
3. ~/.hermes/.env

.env 文件写法（export 前缀和引号都认）：

OPENCODE_GO_API_KEY=你的key

文件路径

• 状态文件：~/.hermes/opencode-usage-state.json
• 历史文件：~/.hermes/opencode-usage-history.jsonl
• 设置了 HERMES_HOME 时，默认路径跟着它走
• 两个路径都可以用环境变量覆盖（测试、多实例必备）：
  • OPENCODE_WATCHDOG_STATE
  • OPENCODE_WATCHDOG_HISTORY

用法

# 正常巡检（静默优先）
python3 ~/.hermes/scripts/opencode_usage_monitor.py

# 强制打印当前报告（调试用；不读写 state/history，无视状态）
python3 ~/.hermes/scripts/opencode_usage_monitor.py --once

# 离线自检：内置 fixture 跑遍所有报告分支，全部通过才退出码 0
python3 ~/.hermes/scripts/opencode_usage_monitor.py --selftest

第一次运行一定会打印首报；紧接着再跑一次没有任何输出—— 别怀疑，这正是静默契约在正常工作。

定时任务

普通 crontab，每小时一次：

0 * * * * $HOME/.hermes/scripts/opencode_usage_monitor.py

Hermes Agent（脚本即任务，stdout 原文投递；空输出 = 静默，不打扰）：

hermes cron create "every 1h" --name "opencode-go usage watchdog" \
  --script opencode_usage_monitor.py --no-agent

输出示例

首报：

📡 opencode-go usage — first report
  rolling    9%   $1.08/12    ~3h10m
  weekly     3%   $0.90/30    ~2d13h
  monthly    1%   $0.60/60    ~30d18h
  channel: go

变化报告（带标题头和 pp 标记）：

🔄 opencode-go usage change
  rolling   14%   $1.68/12    ~3h10m  (+5pp)
  weekly     3%   $0.90/30    ~2d13h
  monthly    1%   $0.60/60    ~30d18h
  channel: go

告警：

⚠️ OPENCODE-GO USAGE ALERT
  (>= 85% or quota error: rolling)
  rolling   90%  $10.80/12    ~3h10m  (+76pp)
  weekly     3%   $0.90/30    ~2d13h
  monthly    1%   $0.60/60    ~30d18h
  channel: go

读法：rolling 9% $1.08/12 ~3h10m = 5 小时滚动窗口用了 9%（约 1.08 美元， 上限 12 美元），大约 3 小时 10 分钟后重置。

调节参数

常量都在脚本最上面，直接改：

常量	默认	含义
ALERT_PCT	85	严重告警阈值（百分比）
WARN_PCT	70	预警阈值（百分比）
DELTA_PP	2	变化多少个百分点就报告
DOLLAR_LIMITS	12 / 30 / 60	三个窗口的美元上限（滚动 / 周 / 月）
FAIL_COOLDOWN_SEC	3600	拉取失败报告的间隔下限

退出码

退出码	含义
0	正常（包括静默和已报告）
1	找不到 API key
2	--once 拉取失败
非 0	--selftest 有检查项失败

自检证据

验收矩阵逐条的真实命令与真实输出见 SELFTEST-EVIDENCE.md。

文件

• opencode_usage_monitor.py — 看门狗本体（单文件，只用标准库）
• README.md — 本文（中文，默认）
• README.en.md — English version
• SELFTEST-EVIDENCE.md — 验收证据