llm-provider-billing: 新增百炼 Token Plan 余量查询（bailian-token-plan.sh + SKILL.md 文档）

llm-provider-billing/SKILL.md

@@ -52,6 +52,46 @@ curl -s https://api.deepseek.com/user/balance \
 - **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 同机
+
+### 返回结构（实测 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/`。

llm-provider-billing/scripts/bailian-token-plan.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# 阿里云百炼 Token Plan 余量/配额查询 — 依赖 bl CLI 的控制台登录（一次性授权）
+# 用法: bash bailian-token-plan.sh [--summary]
+#   --summary  额外输出统一用量摘要（免费额度 + 近期用量）
+set -euo pipefail
+
+if ! command -v bl >/dev/null 2>&1; then
+  echo "❌ 未找到 bl CLI，请先: npm install -g bailian-cli" >&2
+  exit 1
+fi
+
+AUTH=$(bl auth status --output json 2>/dev/null || true)
+if ! echo "$AUTH" | grep -q '"authenticated": *true'; then
+  echo "❌ 百炼控制台未登录（API Key 只能调模型，查不了配额）。请先执行一次性授权:" >&2
+  echo "   bl auth login --console --console-site domestic" >&2
+  exit 1
+fi
+
+echo "🔍 查询百炼 Token Plan 配额 ..." >&2
+if ! bl usage token-plan --output json > /tmp/bailian-token-plan.json 2>/tmp/bailian-token-plan.err; then
+  echo "❌ bl usage token-plan 失败:" >&2
+  cat /tmp/bailian-token-plan.err >&2
+  exit 1
+fi
+cat /tmp/bailian-token-plan.json
+echo
+
+# 友好摘要：周配额已用/剩余比例 + 重置时间（本地时区）
+if command -v python3 >/dev/null 2>&1; then
+  python3 - <<'PY'
+import json, sys, datetime, time
+try:
+    d = json.load(open('/tmp/bailian-token-plan.json'))
+except Exception as e:
+    print(f"⚠️ 无法解析 JSON: {e}", file=sys.stderr)
+    sys.exit(0)
+used = d.get('per1WeekPercentage')
+reset = d.get('per1WeekResetTime')
+if used is not None:
+    used_pct = used * 100
+    print(f"📊 本周 Token Plan 已用: {used_pct:.2f}%  |  剩余约为: {100 - used_pct:.2f}%")
+else:
+    print("⚠️ 响应中没有 per1WeekPercentage 字段（结构可能已变化），请参考上方原始 JSON")
+if reset:
+    dt = datetime.datetime.fromtimestamp(reset / 1000)
+    tzname = time.strftime('%Z')
+    print(f"🔄 本周配额重置时间: {dt.strftime('%Y-%m-%d %H:%M:%S')}（本地时区 {tzname or 'local'}）")
+PY
+fi
+
+if [ "${1:-}" = "--summary" ]; then
+  echo "=== 统一用量摘要（免费额度等） ===" >&2
+  bl usage summary --output json
+fi