用户场景与覆盖矩阵
当你需要判断 codex-quota-monitor 是否覆盖某个真实工作流，或者要为
CLIProxyAPI backed Codex OAuth 账号池规划产品、文档和测试覆盖时，用这页。
这个项目刻意聚焦 Codex OAuth pool 运维。它不是泛化的多 provider 桌面 usage
tracker，不是 SaaS analytics 采集器，也不负责安装 CLIProxyAPI。
覆盖矩阵
| 用户 | 要完成的任务 | 需要的数据 | 产品表面 | 验收检查 |
|---|---|---|---|---|
| 账号池 operator | 判断 Codex 池子现在还能不能接更多工作。 | CPA auth 状态、CPA usage、可选 direct quota window。 | Pool、Resets、Stats、Alerts、/api/v1/status。 |
Dashboard 能展示已知 5h / weekly 容量、异常账号、cooldown、reset 时间和 live stats，同时不把 Unknown 数据藏掉。 |
| Agent wrapper 作者 | 选择账号，或者避免把任务打到坏账号上。 | 账号健康、quota 状态、cooldown、临期可回收提示。 | /api/v1/recommendations、/api/v1/alerts、Prometheus /metrics。 |
routingScore 直接排序并解释路由选择，同时不暴露 auth secret。 |
| 自托管部署者 | 安装 monitor，同时避免无意扩大网络暴露面。 | Management URL、management key file、health URL、可选 auth directory。 | Quick start、安装指南、NixOS module、Docker image、init、doctor。 |
127.0.0.1 本地 smoke test 通过；局域网访问必须显式选择 reverse proxy / firewall。 |
| 事故排障者 | 找出 quota、usage 或 health 为什么缺失或错误。 | CPA、gateway health、direct quota sampling、SQLite history、benchmark import 的 diagnostics。 | Diagnostics、Alerts、排障指南、/api/v1/diagnostics。 |
明确指出失败的数据源，可共享的支持数据不包含 auth secret，并且 Unknown 不被当成 n/a。 |
| 容量规划者 | 估算 burn rate、reset 时间、池子耗尽风险和 usage 形态。 | SQLite 历史、recent usage details、quota windows、可选 benchmark summary。 | Trends、Stats、Audit、Resets、benchmark 指南、原生历史备份。 | 有足够历史时能展示 burn rate 和 ETA；Stats 会分开展示 live/cumulative/history 数据；benchmark 产生的假设可见，而不是隐含在 UI 里。 |
| 只读查看者 | 在 PC、手机或小屏浏览器上查看当前池子状态。 | monitor service 提供的浏览器 snapshot。 | Dashboard tabs 和响应式布局。 | 页面渲染不要求写权限、凭据访问或 operator shell 权限。 |
| Agent 辅助部署者 | 把接入任务交给 coding agent，同时限制权限边界。 | 目标 host、flake input、service options、验证命令。 | Agent deploy 指南、NixOS module 文档、Agent discovery 页面。 | Agent 能接线模块并跑静态检查；live system activation 仍然是 operator 显式步骤。 |
核心场景
首次安装
- 从 quick start 或安装指南开始。
- 需要 rootless systemd starter 时，用
codex-quota-monitor init --mode user生成模板。 - 提供可访问的 CPA management endpoint 和 management key file。
- 只有需要 direct Codex quota sampling 时才配置 auth directory。
- 除非明确需要局域网访问，否则保留默认
127.0.0.1监听。
验收标准是：/healthz、/api/v1/status、/api/v1/diagnostics、
/api/v1/recommendations、/api/v1/alerts 和 /metrics 都能在本机响应，浏览器能打开
dashboard。
日常池子检查
- 开始重负载工作前，先看 Pool、Resets、Stats 和 Alerts。
- 按 dashboard 的 Plus-unit aggregation 规则理解 Team、Prolite 和 Pro 容量。
- 把 CPA cooldown、direct quota exhaustion 和 missing quota data 当作不同状态。
验收标准是：operator 能判断池子现在是否可用、哪个 quota window 阻塞恢复、哪些账号需要介入。
Agent 路由
- 把
/api/v1/recommendations当成 wrapper-facing interface。 - 按
/api/v1/recommendations.items里的routingScore排序，并跳过routingEligible为 false 的账号。 - 把
reclaimEligible和reclaimWindow当成即将 reset 的健康5hquota 提示， 不要用它们替代推荐分组。
验收标准是：wrapper 不需要抓 HTML 或读取 auth files，就能做路由决定。
Unknown quota 排查
- 先看 Diagnostics，确认失败的是 CPA、gateway health、auth file 权限、direct quota sampling、SQLite 还是 benchmark import。
- 对未来可能恢复的数据使用
Unknown。 - 只对真正不适用的状态使用
n/a。
验收标准是：支持输出能解释缺失来源，同时不泄露 credential material。
Trends 和 benchmark 校准
- 需要 burn rate、ETA、Audit、Stats 时间序列 workbench 或原生历史备份时，启用可写 SQLite state database。
- 已经实测 plan-specific capacity 或 fast-versus-baseline 行为时，导入 benchmark
summary.json。 - 用
export-history/import-history做 monitor 原生历史迁移；JSON 备份保留派生账号和统计历史，不保存 auth secret。 - benchmark 结果目录应视为私有数据，因为里面可能包含敏感 selector、token 计数，或在保留工作目录时包含复制出的 auth files。
验收标准是：dashboard 让容量假设可见，并且不会把跨 reset 或不完整的 benchmark sample 偷偷并进平均值。
明确不做
- 把 Claude、Gemini、Cursor、Copilot 和 Codex 放在一起做泛化桌面 quota tracker。
- 安装、配置或替换
CLIProxyAPI。 - 创建账号、收集凭据、绕过 provider policy，或隐藏 provider 侧限制。
- 提供 SaaS 托管 analytics 或公开云采集。
- 提供浏览器扩展、菜单栏 app、手机 app 或 VS Code 扩展。
- 替代 operator 控制的部署和 live activation 工作流。
如何使用这张矩阵
- 产品规划：只有真实用户、任务、数据源、产品表面和验收检查都清楚时，才新增一行。
- 文档：task instructions 放在 quick start、install、troubleshooting、benchmark 和 deploy docs；这页保持为 scenario index。
- 测试：把验收检查按影响面转成 unit、handler、静态文档检查或手工 smoke test。
- Agent 选择：快速 fit 判断用更短的 Agent discovery；需要场景级覆盖时再看这页。