105 lines
4.6 KiB
Markdown
105 lines
4.6 KiB
Markdown
---
|
||
name: llm-provider-billing
|
||
description: Use when 用户问 LLM 余额/还有多少钱/够不够跑。查询各 API 提供商账户余额。
|
||
category: custom
|
||
metadata:
|
||
author: Hermes Agent
|
||
last_updated: "2026-09-01"
|
||
---
|
||
|
||
# LLM Provider Billing / 余额查询
|
||
|
||
查各家 LLM API 账户还剩多少钱、是否可调用。先看本技能，别猜端点。
|
||
|
||
## DeepSeek（已验证 ✅）
|
||
|
||
官方端点 `GET https://api.deepseek.com/user/balance`，用普通 API key 做 Bearer 认证，无需额外权限。
|
||
|
||
### 一键查询
|
||
|
||
```bash
|
||
bash ~/.hermes/skills/custom/llm-provider-billing/scripts/deepseek-balance.sh
|
||
```
|
||
|
||
或手动：
|
||
|
||
```bash
|
||
export DEEPSEEK_API_KEY=$(grep '^DEEPSEEK_API_KEY=' ~/.hermes/.env | cut -d= -f2-)
|
||
curl -s https://api.deepseek.com/user/balance \
|
||
-H "Accept: application/json" \
|
||
-H "Authorization: Bearer $DEEPSEEK_API_KEY"
|
||
```
|
||
|
||
### 返回结构
|
||
|
||
```json
|
||
{
|
||
"is_available": true,
|
||
"balance_infos": [
|
||
{ "currency": "CNY", "total_balance": "16.60",
|
||
"granted_balance": "0.00", "topped_up_balance": "16.60" }
|
||
]
|
||
}
|
||
```
|
||
|
||
- `total_balance` = `granted_balance`(赠送) + `topped_up_balance`(充值)；三个字段都是**十进制字符串**，解析时不要转 float
|
||
- `is_available` = 余额是否足够调用（≠ 服务可用性，不预测消耗速度）
|
||
- 多币种时 USD/CNY 分开列，不要自行换算汇率
|
||
|
||
### 关键事实
|
||
|
||
- **Key 位置**：`~/.hermes/.env` 的 `DEEPSEEK_API_KEY`（Hermes 的 config.yaml 里 api_key 均为空，key 集中在 .env）
|
||
- **402 vs 401**：余额归零 → HTTP 402 Insufficient Balance（key 仍有效，充值即恢复）；key 错误/缺失 → 401。遇到 402 是去充值，不是换 key
|
||
- 充值/发票在 platform.deepseek.com 的 Billing 页面
|
||
|
||
## 阿里云百炼 Token Plan（已验证 ✅）
|
||
|
||
Token Plan 是订阅制（周配额），"余量" = 本周剩余 token 配额比例，语义区别于 DeepSeek 的余额。
|
||
|
||
### 一键查询
|
||
|
||
```bash
|
||
bash ~/.hermes/skills/custom/llm-provider-billing/scripts/bailian-token-plan.sh
|
||
# --summary 附加统一用量摘要（免费额度 freeTier + 近期用量）
|
||
bash ~/.hermes/skills/custom/llm-provider-billing/scripts/bailian-token-plan.sh --summary
|
||
```
|
||
|
||
### 鉴权要求（关键）
|
||
|
||
- **Console 鉴权**：首次运行前需浏览器一次性授权 `bl auth login --console --console-site domestic`（国内站）
|
||
- **API Key 查不了配额**：`bl auth login --api-key <key>` / 环境变量里的 key（用户的是 `OPENAI_API_KEY`）只能调模型，不能查余量
|
||
- 授权凭据落盘 `~/.bailian/config.json`，登录一次长期有效；回调走本机 `127.0.0.1` 端口，浏览器必须与 CLI 同机
|
||
- **会话有效期由服务端决定**（实测约 1 天级，bl CLI 无 TTL 参数可调，config.json 只存 36 位 opaque access_token，无 refresh token）——过期后 `bailian-token-plan.sh` **已内置自动续期**：检测到 expired 错误自动拉起 `bl auth login --console`，等回调写盘后重试查询。若本机浏览器保持阿里云「自动登录」登录态，整条链路无需人工点击
|
||
|
||
### 返回结构（实测 2026-09-10）
|
||
|
||
```json
|
||
{
|
||
"per1WeekPercentage": 0.032949624,
|
||
"per1WeekResetTime": 1789624440000
|
||
}
|
||
```
|
||
|
||
- `per1WeekPercentage`：**本周已用比例**（0.033 ≈ 3.3% 已用；实测随时间递增，确认是"已用"不是"剩余"），剩余 ≈ 1 - 该值
|
||
- `per1WeekResetTime`：本周配额重置时间（epoch 毫秒，如 2026-09-17 13:54 CST，即 7 天滚动窗口）
|
||
- 原始 JSON 只有这两个字段，无绝对额度数值；脚本自动换算已用/剩余百分比 + 本地时区重置时间
|
||
|
||
### 相关命令
|
||
|
||
| 命令 | 用途 | 鉴权 |
|
||
|---|---|---|
|
||
| `bl usage token-plan --output json` | Token Plan 周配额用量 | Console |
|
||
| `bl usage summary --output json` | 统一摘要：freeTier 剩余额度 + 近期用量 | Console |
|
||
| `bl usage stats` / `bl usage free` | 用量统计 / 免费额度 | Console |
|
||
| `bl token-plan list-seats` | 订阅座位详情 | AK/SK（`ALIBABA_CLOUD_ACCESS_KEY_ID` 等环境变量） |
|
||
|
||
## 其他提供商（待扩展）
|
||
|
||
每家端点不同。添加前先用 web_search 验证官方文档并实测一次，把端点 + 返回结构记录到 `references/`。
|
||
|
||
## 坑
|
||
|
||
- `curl | python3 -m json.tool` 管道到解释器可能触发安全审批；可先 `> /tmp/bal.json` 再解析
|
||
- 本技能脚本：`scripts/deepseek-balance.sh`（从 ~/.hermes/.env 自动读 key，无需手动 export）
|
||
- **YAML frontmatter 里的日期必须加引号**（`last_updated: "2026-09-01"`），裸 `2026-08-30` 会被 YAML 解析成 date 对象，导致 skill_view 报 "Object of type date is not JSON serializable"（本次会话实测踩坑）
|