openrouter-usage

该 Skill 是专为 OpenRouter AI API 平台设计的用量与成本监控解决方案，旨在为开发者和团队提供透明、实时的支出可视化能力。

核心用法：通过调用 OpenRouter 官方 /auth/key 端点获取实时消费总额（今日/本周/本月）及账户余额，同时支持通过 /activity 端点（需 Management Key）拉取近 7 天各 AI 模型的详细支出 breakdown。用户可通过配置 OPENROUTER_API_KEY 环境变量或创建本地 credentials.env 文件完成身份验证，执行 python3 scripts/stats.py 即可生成带 emoji 的格式化报告。系统提供 Python 和 curl 双路径方案，适配不同运行环境。

显著优点：安全性与轻量化是其核心优势。实现上仅依赖 Python 标准库（urllib、json、os 等），零第三方包引入，彻底杜绝供应链攻击风险。代码规范严谨，无 eval、exec、system 等危险函数，所有网络请求均指向 OpenRouter 官方 HTTPS 端点，且仅执行只读查询。功能设计考虑周全，输出格式直观清晰（💰 金额统计 + 模型分布列表），并对 API 错误（401/403/429）及网络异常具备完善的 try-except 错误处理机制。

潜在缺点：作为 T3 来源的个人社区项目（Arkology Studio），其长期维护稳定性、代码审查深度不及企业级项目。功能上存在数据延迟限制：/activity 端点仅返回已完成 UTC 日的历史数据，导致今日消费可能显示在总额中，但无法立即在模型级 breakdown 中查看，需等待次日 UTC 零点。此外，获取完整功能（模型级分析）需提供可选的 Management Key，增加了凭据管理的复杂度。

适合人群：主要面向使用 OpenRouter 作为 AI API 聚合平台的开发者、技术团队、财务管理人员，以及需要定期监控多模型 AI 支出、分析不同模型成本效益、进行预算控制和成本优化的场景。

使用风险：常规风险包括网络依赖性（需稳定互联网连接）、API 速率限制（429）可能导致的数据获取延迟，以及凭据泄露风险。用户需妥善保管 OPENROUTER_API_KEY 和可选的 OPENROUTER_MGMT_KEY，强烈建议使用环境变量而非明文配置文件存储敏感信息。由于代码仅进行只读 API 查询，无数据修改、系统配置变更或破坏性操作，整体风险可控。

核心功能

OpenRouter Usage Monitor 是一款专注于 LLM 调用成本追踪的轻量级工具，通过与 OpenRouter 官方 API 对接，提供双维度的用量统计：

1. 实时总览（/auth/key 端点）：返回今日、本周、本月的累计花费及账户余额，数据准实时更新
2. 历史模型明细（/activity 端点）：展示过去 7 天内各模型的具体调用成本与请求次数，便于识别高消耗模型

显著优点

• 零依赖设计：仅使用 Python 标准库（urllib/json/os/datetime），彻底规避供应链攻击风险
• 安全传输：强制 HTTPS (TLS 1.2+) 通信，Bearer Token 认证符合 OAuth2 标准
• 灵活凭证管理：支持环境变量（推荐）与本地文件双模式，适应不同部署场景
• 多语言支持：提供 Python 主脚本 + curl 回退方案，兼容受限环境

局限性与注意事项

• 数据延迟：/activity 仅返回已完成 UTC 日的数据，今日花费可能暂时缺失于模型明细
• 权限分层：模型级细账需要额外的 OPENROUTER_MGMT_KEY，普通 API Key 无法获取
• T3 来源：由个人开发者维护（Arkology Studio），虽通过安全审计但长期维护稳定性需观察
• 只读限制：纯查询功能，不支持预算告警或自动限额设置

适合人群

• 使用 OpenRouter 聚合多家 LLM 的开发者/团队
• 需要按项目/模型拆分成本进行内部结算的场景
• 对第三方依赖极度敏感、偏好标准库解决方案的安全意识用户

常规风险

• API Key 泄露风险：若误将 credentials.env 提交至代码仓库
• 误操作风险：混淆 OPENROUTER_API_KEY（查询）与 OPENROUTER_MGMT_KEY（管理）的权限边界
• 网络故障：官方 API 偶发 429 限流或超时，需做好重试逻辑

使用建议

首次配置后建议先用 curl 测试连通性，确认 200 OK 后再集成至自动化脚本。对于多团队协作，推荐将凭证注入 CI/CD 环境变量而非文件存储。