From ed5340d7e081ce7c8b321a409e5b51d506d97944 Mon Sep 17 00:00:00 2001
From: weishen <ishenwei@gmail.com>
Date: Tue, 1 Sep 2026 18:23:59 +0800
Subject: [PATCH] Add llm-provider-billing skill: DeepSeek balance query

---
 llm-provider-billing/SKILL.md                 | 63 +++++++++++++++++++
 .../scripts/deepseek-balance.sh               | 18 ++++++
 2 files changed, 81 insertions(+)
 create mode 100644 llm-provider-billing/SKILL.md
 create mode 100644 llm-provider-billing/scripts/deepseek-balance.sh

diff --git a/llm-provider-billing/SKILL.md b/llm-provider-billing/SKILL.md
new file mode 100644
index 0000000..20a61f9
--- /dev/null
+++ b/llm-provider-billing/SKILL.md
@@ -0,0 +1,63 @@
+---
+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 页面
+
+## 其他提供商（待扩展）
+
+每家端点不同。添加前先用 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"（本次会话实测踩坑）
diff --git a/llm-provider-billing/scripts/deepseek-balance.sh b/llm-provider-billing/scripts/deepseek-balance.sh
new file mode 100644
index 0000000..707010d
--- /dev/null
+++ b/llm-provider-billing/scripts/deepseek-balance.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# DeepSeek 余额实时查询 — 自动从 ~/.hermes/.env 读 key，无需手动 export
+# 用法: bash deepseek-balance.sh  (或 chmod +x 后直接执行)
+set -euo pipefail
+
+ENV_FILE="$HOME/.hermes/.env"
+KEY=$(grep '^DEEPSEEK_API_KEY=' "$ENV_FILE" 2>/dev/null | cut -d= -f2- | tr -d '"' | tr -d "'")
+
+if [ -z "$KEY" ]; then
+  echo "❌ 未在 $ENV_FILE 找到 DEEPSEEK_API_KEY" >&2
+  exit 1
+fi
+
+echo "🔍 查询 DeepSeek 余额 ..." >&2
+curl -s --max-time 20 https://api.deepseek.com/user/balance \
+  -H "Accept: application/json" \
+  -H "Authorization: Bearer $KEY"
+echo