Agent Usage 🚀

AI 编程助手（Google Antigravity agy 与 OpenAI codex）用量、额度（Quota）与速率限制（Rate Limit）自动获取与监控工具。

---

✨ 核心特性

• 🤖 全面支持主流 Agent：
  • Google Antigravity (agy)：自动读取凭据，直接获取 4 大核心额度窗口：
    1. Gemini (5-Hour)：内置 Gemini 模型 5 小时短周期额度
    2. Gemini (7-Day)：内置 Gemini 模型 7 天周额度
    3. Claude & GPT (5-Hour)：外部三方模型 5 小时短周期额度
    4. Claude & GPT (7-Day)：外部三方模型 7 天周额度
    • 同时自动识别接口新增的模型独立额度组（如 Gemini 4 Argon (7-Day)），作为附加窗口一并输出。 （支持 --show-models 查看细分模型清单）
  • OpenAI Codex (codex)：自动读取 ~/.codex/auth.json，获取 ChatGPT 订阅类型（Plus/Pro/Team）、5小时会话窗口用量、7天滚动周用量、重置倒计时、Credits 余额及状态。
• 🔑 无感自动凭据发现：
  • Windows 原生集成：自动读取 Windows 凭据管理器中的 gemini:antigravity。
  • Codex 原生集成：自动读取 ~/.codex/auth.json。
  • 完善的备选机制：支持环境变量（AGY_ACCESS_TOKEN, CODEX_ACCESS_TOKEN）与自定义凭证文件覆盖。
• 📊 高颜值终端 UI (rich)：
  • 自适应色块进度条（绿色安全 / 黄色预警 / 红色告警）。
  • 清晰展示各窗口剩余百分比、已用百分比、重置倒计时及本地转换时间。
• ⏱️ 实时监控模式 (--watch)：
  • 动态刷新用量，支持设定轮询间隔和阈值告警回调。
• 🌐 内置 REST API 服务 (--serve)：
  • 内置轻量 FastAPI 接口，方便外部看板或告警机器人对接。
• 💻 Python SDK 支持：
  • 提供标准的同步/异步 API、强类型 Pydantic 数据模型。

---

📦 安装

在项目目录下安装依赖或安装为命令行工具：

pip install -e .

---

⚡ 命令行 (CLI) 快速上手

1. 查看全部 Agent 用量（默认）

python -m agent_usage.cli
# 或安装后直接运行：
agent-usage

2. 仅查看 Google Antigravity (AGY) 用量

python -m agent_usage.cli --agy

3. 仅查看 OpenAI Codex 用量

python -m agent_usage.cli --codex

4. 输出 JSON 格式（用于脚本或自动化工作流）

python -m agent_usage.cli --json

5. 开启实时监控（Watch 模式）

# 每 30 秒自动刷新终端监控看板
python -m agent_usage.cli --watch --interval 30

6. 启动隐身安全 REST API 服务

# 首次生成私有密钥。服务端和客户端需配置相同的 AGENT_USAGE_SECRET。
$env:AGENT_USAGE_SECRET = python -c "import secrets; print(secrets.token_urlsafe(32))"

# 启动隐身 REST API 服务（默认端口: 8111，无默认密钥）
agent-usage --serve --port 8111

# 自定义端口启动
agent-usage --serve --port 8888

Note

🛡️ 极致隐身安全设计（Stealth Mode）：

1. 零信息泄露：直接浏览器或端口扫描访问 /、/docs、/redoc、/openapi.json 等路径直接返回空白 404，不暴露任何服务名称、版本或路由线索。
2. 公私钥签名防重放认证：必须通过基于主密钥派生的 Ed25519 非对称签名（附带防重放时间戳）或 API Token 鉴权才能访问 /api/... 接口，否则一律返回 404 伪装。
3. 端到端报文加密：支持请求 X-Encrypt-Response: true，服务端使用 AES-256-GCM 对返回的用量 JSON 进行全报文加密传输。

7. 客户端远程查询（自动完成公私钥签名与解密）

# 查询远程服务器用量（自动使用密钥签名鉴权与报文解密）
agent-usage --remote http://127.0.0.1:8111

---

🪟 Windows 系统服务（开机自启）

项目内置了完整的 PowerShell 自动化运维脚本，可一键将 Agent Usage 隐身 REST API 注册为 Windows 系统服务并设置开机自启。

脚本清单

脚本文件	权限要求	说明
install-service.ps1	管理员（自动提权）	安装 Windows 系统服务、配置开机自启、初始化日志轮转并立即启动
start-service.ps1	管理员（自动提权）	启动 Windows 系统服务
stop-service.ps1	管理员（自动提权）	优雅停止 Windows 系统服务
restart-service.ps1	管理员（自动提权）	刷新凭证快照并重启系统服务
status-service.ps1	普通用户/管理员	查询服务状态、PID、内存、端口监听与最近日志
uninstall-service.ps1	管理员（自动提权）	停止并彻底注销卸载系统服务
manage-service.ps1	交互式控制台	提供可视化的数字菜单控制台，方便日常运维管理

常用操作示例

# 1. 配置 AGENT_USAGE_SECRET 后安装并开机自启（默认端口 8111）
.\install-service.ps1

# 2. 自定义端口安装
.\install-service.ps1 -Port 8888

# 3. 查看运行状态与最新日志
.\status-service.ps1

# 4. 重启服务
.\restart-service.ps1

# 5. 停止服务
.\stop-service.ps1

# 6. 交互式菜单控制台
.\manage-service.ps1

---

🐍 Python SDK 使用示例

1. 同步获取用量

from agent_usage import UsageManager

manager = UsageManager()

# 获取全部用量报告
report = manager.get_all_usage_sync()

# 读取 Codex 状态
if report.codex and report.codex.success:
    print(f"Codex 邮箱: {report.codex.email}, 订阅: {report.codex.plan_type}")
    if report.codex.primary_window:
        print(f"5小时窗口剩余: {report.codex.primary_window.remaining_percent}%")
        print(f"重置倒计时: {report.codex.primary_window.reset_after_human}")

# 读取 Antigravity 状态
if report.agy and report.agy.success:
    print(f"AGY 邮箱: {report.agy.user_email}, 计划: {report.agy.tier_name}")
    for model in report.agy.key_models:
        print(f"- {model.display_name}: 剩余 {model.remaining_percent}% (重置时间: {model.reset_time_local})")

2. 异步并发获取

import asyncio
from agent_usage import UsageManager

async def main():
    manager = UsageManager()
    report = await manager.get_all_usage_async()
    print("获取时间:", report.timestamp)
    print(report.model_dump_json(indent=2))

asyncio.run(main())

3. 持续监控与告警回调 (UsageWatcher)

from agent_usage.watcher import UsageWatcher

def on_alert(agent_name, message, level):
    print(f"[{level}] {agent_name}: {message}")

watcher = UsageWatcher(
    interval_seconds=60,
    alert_threshold_percent=15.0,  # 剩余额度低于 15% 时触发告警
    on_alert=on_alert,
)

watcher.run_sync()

---

🔐 凭证配置说明

1. Google Antigravity (agy)：

   • 只要在本地使用过 agy 登录，凭证即保存在 Windows 凭据管理器的 gemini:antigravity 中，程序会自动提取。
   • 自定义配置（可选）：可设置环境变量 AGY_ACCESS_TOKEN 或 GEMINI_ACCESS_TOKEN。
   • 自动刷新过期 Token 需配置对应的 AGY_CLIENT_ID 和 AGY_CLIENT_SECRET；项目不内置 OAuth 客户端凭据。未配置时仍可使用有效的访问 Token。
   • 程序会自动探测本机 agy --version 并上报真实的客户端标识，以获取最新的 Gemini / Gemini 4 Argon 额度分组；如自动探测失败，可手动设置 AGY_USER_AGENT 覆盖。

2. OpenAI Codex (codex)：

   • 只要运行过 codex login，凭据将保存在 ~/.codex/auth.json 中，程序会自动解析。
   • 自定义配置（可选）：可设置环境变量 CODEX_ACCESS_TOKEN 及 CODEX_ACCOUNT_ID。

3. 远程服务鉴权：设置 AGENT_USAGE_SECRET，或显式传入 --secret / SDK 的 secret 参数。没有默认密钥，空密钥无法通过鉴权。凭证文件、环境变量文件、日志和压测结果均不应提交到仓库。

---

🧪 运行测试

pytest -v

本地部署模型测速

默认测试 http://127.0.0.1:8000/v1，自动读取 /models 的第一个模型。需要鉴权时，通过环境变量 LOCAL_MODEL_API_KEY 或 --api-key 提供密钥：

python benchmark_local_model.py

常用参数：

# 增加任务数和最大输出长度
python benchmark_local_model.py --tasks 10 --max-tokens 256

# 同时进行 12 个任务；默认会分别测试 12 个非流式和 12 个流式请求
python benchmark_local_model.py --tasks 12 --concurrency 12

# 只测试 12 个同时进行的非流式请求
python benchmark_local_model.py --tasks 12 --concurrency 12 --no-stream

# 使用环境变量保存 key
$env:LOCAL_MODEL_API_KEY = "your-key"
python benchmark_local_model.py

# 输出 JSON
python benchmark_local_model.py --json > benchmark.json