[Feature]: 暴露 quota / usage API 给第三方, 支持 real-time 拉取 (替代 T+1 延迟)

Comienza rastreando el comando mmx quota existente y su endpoint interno de quota; después, revisa cómo mmx auth login proporciona las credenciales. Define la respuesta pública de uso, el comportamiento de actualización, la autenticación, la documentación y el alcance del SDK; el trabajo estará terminado cuando los clientes de terceros puedan recuperar datos precisos de quota y uso casi en tiempo real a través de una interfaz documentada.

Feature Request: 暴露 quota / usage API 给第三方，real-time 替代 T+1 延迟

反馈时间：2026-06-08
反馈人：Plus 订阅用户 + CodexBar 第三方工具使用者

---

一、用户场景

我同时是 MiniMax Plus 订阅用户，也是 macOS 菜单栏用量监控工具 CodexBar（@steipete/CodexBar）的用户。

CodexBar 已经在监控 OpenAI Codex / Claude / Cursor / Gemini / MiniMax 等多家 provider，核心体验是：

• 实时显示会话 5h 滚动窗口剩余百分比 + 重置倒计时
• 实时显示每周配额剩余百分比
• 实时显示今日 token 用量 + 近 30 天费用
• 当用量接近耗尽时给出"≈ 30% 耗尽风险"等预警

这套体验依赖一个前提：上游服务方（OpenAI、Anthropic 等）提供官方、real-time、可被第三方调用的 usage / quota API。

---

二、现状（MiniMax 这边缺什么）

1. 没有公开的 usage / quota API
   • mmx-cli 内部有 mmx quota 命令，说明后端 API 是有的，但没文档化 / 没开放给第三方
   • CodexBar 的 MiniMax provider 只能 hack（本地 log 估算）— 数据不准确 + 延迟严重
2. 数据延迟一天（T+1）
   • 平台 dashboard 上 "今日 token 用量" 要到第二天才更新
   • 用户完全无法在消耗异常的当天自助定位
3. quota 数据存在已知 bug（不阻塞 feature request，但希望一起修）
   • #173: mmx quota show video 显示 100% 剩但实际 0/0
   • #48: Token Plan Plus 配置返 0
   • #47: cache 折扣不透明
   • #92: mmx quota show 与 Token Plan dashboard 数据不一致

---

三、建议方案

3.1 短期（先解决 "T+1 延迟"）

把现有内部 quota 端点的刷新频率从 T+1 改成 T+0 / near-real-time（流式或 ≤ 5 分钟延迟）。

3.2 中期（暴露给第三方）

参考 OpenAI 给 Codex 提供的使用量 API 体验：

• 公开 GET /v1/coding_plan/usage 或类似端点
• 至少返回以下字段（按 CodexBar 类工具够用为标准）：
  • current_window_remaining_percent（5h 滚动窗口）
  • current_window_resets_at（ISO 8601 timestamp）
  • weekly_remaining_percent
  • weekly_resets_at
  • today_token_used / today_cost_usd
  • month_token_used / month_cost_usd
  • last_refresh_at
• 走标准 Bearer token 鉴权（用户用 mmx auth login 拿到的 API key 即可调）
• 文档化 + 加 SDK（Node.js / Python / Swift 至少一门）

3.3 长期

• 在 mmx-cli 加 mmx quota serve 启动本地 proxy，让没装 SDK 的工具也能通过本地 socket 拉
• 把 mmx quota 的实现细节（参考 #92）也修一下，跟 dashboard 对齐

---

四、对 MiniMax 团队的价值

• 生态：第三方工具（CodexBar、Hammerspoon 脚本、Slack bot、Prometheus exporter）能自然接入，形成 MiniMax 用量可视化生态
• 降低客服压力：现在 T+1 + 没 API，用户消耗异常时无法自助定位，只能靠工单。开放 API 后这类 issue 大量减少
• 对标 OpenAI：OpenAI 的 usage API 已经是 de facto 行业标准，MiniMax 在做 "Codex 那种 agent CLI" 配套的可视化工具时也应该同步跟上

---

五、参考链接

• OpenAI Usage API: https://platform.openai.com/usage
• CodexBar: https://github.com/steipete/CodexBar
• 相关 issue（MiniMax 侧已知 quota 数据问题）：
  • #173 — video quota 数据不准确
  • #48 — Token Plan Plus 配置返 0
  • #47 — cache 折扣不透明
  • #92 — mmx quota show 与 dashboard 不一致

---

谢谢！