feat(probe): zero-cost wham usage probe with /responses fallback

ChatGPT exposes GET /backend-api/wham/usage which returns structured JSON
(plan_type, 5h/7d window used_percent + reset_at, credits, spend_control)
without consuming any tokens. Previously ProbeUsageSnapshot sent a minimal
/responses request that did cost ~13 input + 5 output tokens per probe.

Changes:
- New proxy/usage_wham.go: QueryWhamUsage() + ApplyWhamUsage() that map
  the structured response onto existing Account/Store helpers
  (SetUsageSnapshot5h, PersistUsageSnapshot, MarkPremium5hRateLimited,
  UpdateAccountPlanType). Reuses newCodexStandardTransport so per-account
  proxies still work.
- admin/usage_probe.go: ProbeUsageSnapshot tries wham first; falls back
  to the original /responses probe on any failure so we never regress
  if /wham/usage changes.
- Unit tests cover header construction, JSON parsing, plan_type sync
  to DB, 5h/7d snapshot persistence, and premium 5h rate-limit
  detection at 100%.

Author: james-6-23

admin/usage_probe.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"log"
 	"net/http"
 	"time"
 
@@ -12,7 +13,11 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
-// ProbeUsageSnapshot 主动发送最小探针请求刷新账号用量
+// ProbeUsageSnapshot 主动刷新账号用量。
+//
+// 优先尝试 /backend-api/wham/usage（零额度成本的结构化端点）；
+// 失败时（4xx/5xx/网络）回退到给 /backend-api/codex/responses 发一个最小请求
+// （会真实计入用量但保证向下兼容）。
 func (h *Handler) ProbeUsageSnapshot(ctx context.Context, account *auth.Account) error {
 	if account == nil {
 		return nil
@@ -25,6 +30,52 @@ func (h *Handler) ProbeUsageSnapshot(ctx context.Context, account *auth.Account)
 		return nil
 	}
 
+	// 1) 优先用 wham（零成本）
+	if err := h.probeUsageViaWham(ctx, account); err == nil {
+		return nil
+	} else {
+		log.Printf("[账号 %d] wham 用量探测失败，回退到 /responses 探针: %v", account.DBID, err)
+	}
+
+	// 2) Fallback: 原有的 /responses 最小探针
+	return h.probeUsageViaResponses(ctx, account)
+}
+
+// probeUsageViaWham 通过 /backend-api/wham/usage 拉取用量，
+// 不消耗任何 token 额度。
+func (h *Handler) probeUsageViaWham(ctx context.Context, account *auth.Account) error {
+	usage, resp, err := proxy.QueryWhamUsage(ctx, account, h.store.ResolveProxyForAccount(account))
+	if resp != nil {
+		// QueryWhamUsage 在非 200 时不会读 body；这里关闭，并按状态码做冷却
+		_, _ = io.Copy(io.Discard, resp.Body)
+		_ = resp.Body.Close()
+		switch resp.StatusCode {
+		case http.StatusUnauthorized:
+			h.store.ReportRequestFailure(account, "client", 0)
+			h.store.MarkCooldown(account, 24*time.Hour, "unauthorized")
+		case http.StatusTooManyRequests:
+			h.store.ReportRequestFailure(account, "client", 0)
+		}
+	}
+	if err != nil {
+		return err
+	}
+	if usage == nil {
+		return fmt.Errorf("wham returned empty body")
+	}
+
+	state := proxy.ApplyWhamUsage(h.store, account, usage)
+	h.store.ReportRequestSuccess(account, 0)
+	// 用量未耗尽时重置冷却
+	if !state.Premium5hRateLimited && (!state.HasUsage7d || state.UsagePct7d < 100) {
+		h.store.ClearCooldown(account)
+	}
+	return nil
+}
+
+// probeUsageViaResponses 原有探针：发送最小 /responses 请求，
+// 通过响应头同步 Codex 用量状态。会真实消耗少量 token。
+func (h *Handler) probeUsageViaResponses(ctx context.Context, account *auth.Account) error {
 	payload := buildTestPayload(h.store.GetTestModel())
 	resp, err := proxy.ExecuteRequest(ctx, account, payload, "", h.store.ResolveProxyForAccount(account), "", nil, nil)
 	if err != nil {

proxy/usage_wham.go

@@ -0,0 +1,180 @@
+package proxy
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/codex2api/auth"
+)
+
+// WhamUsageURL 是 ChatGPT 后端用量查询端点。
+// 该端点返回结构化 JSON（不消耗任何额度），可用于零成本获取账号 5h/7d 用量。
+const WhamUsageURL = "https://chatgpt.com/backend-api/wham/usage"
+
+// whamURLForTest 允许测试替换默认 URL。生产代码不要赋值。
+var whamURLForTest = ""
+
+// WhamUsage 是 /backend-api/wham/usage 的响应结构。
+type WhamUsage struct {
+	UserID    string `json:"user_id"`
+	AccountID string `json:"account_id"`
+	Email     string `json:"email"`
+	PlanType  string `json:"plan_type"`
+
+	RateLimit struct {
+		Allowed         bool             `json:"allowed"`
+		LimitReached    bool             `json:"limit_reached"`
+		PrimaryWindow   *WhamUsageWindow `json:"primary_window"`
+		SecondaryWindow *WhamUsageWindow `json:"secondary_window"`
+	} `json:"rate_limit"`
+
+	Credits *struct {
+		HasCredits           bool   `json:"has_credits"`
+		Unlimited            bool   `json:"unlimited"`
+		OverageLimitReached  bool   `json:"overage_limit_reached"`
+		Balance              string `json:"balance"`
+		ApproxLocalMessages  []int  `json:"approx_local_messages"`
+		ApproxCloudMessages  []int  `json:"approx_cloud_messages"`
+	} `json:"credits,omitempty"`
+
+	SpendControl *struct {
+		Reached         bool        `json:"reached"`
+		IndividualLimit interface{} `json:"individual_limit"`
+	} `json:"spend_control,omitempty"`
+}
+
+// WhamUsageWindow 是单个限流窗口（primary=5h，secondary=7d）。
+type WhamUsageWindow struct {
+	UsedPercent         float64 `json:"used_percent"`
+	LimitWindowSeconds  int64   `json:"limit_window_seconds"`
+	ResetAfterSeconds   int64   `json:"reset_after_seconds"`
+	ResetAt             int64   `json:"reset_at"`
+}
+
+// QueryWhamUsage 调用 /backend-api/wham/usage 获取账号当前用量。
+// 该调用不消耗任何 token 额度——比发送最小 /responses 请求更便宜。
+func QueryWhamUsage(ctx context.Context, account *auth.Account, proxyURL string) (*WhamUsage, *http.Response, error) {
+	url := WhamUsageURL
+	if whamURLForTest != "" {
+		url = whamURLForTest
+	}
+	return queryWhamUsageWithURL(ctx, account, proxyURL, url)
+}
+
+func queryWhamUsageWithURL(ctx context.Context, account *auth.Account, proxyURL, url string) (*WhamUsage, *http.Response, error) {
+	if account == nil {
+		return nil, nil, fmt.Errorf("account is nil")
+	}
+	accessToken := account.GetAccessToken()
+	if accessToken == "" {
+		return nil, nil, fmt.Errorf("account has no access token")
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return nil, nil, fmt.Errorf("build wham request: %w", err)
+	}
+	req.Header.Set("Authorization", "Bearer "+accessToken)
+	req.Header.Set("Accept", "application/json")
+	req.Header.Set("User-Agent", latestCodexCLIUserAgentPrefix)
+	req.Header.Set("Originator", Originator)
+	if accountID := strings.TrimSpace(account.AccountID); accountID != "" {
+		req.Header.Set("chatgpt-account-id", accountID)
+	}
+
+	client := &http.Client{Transport: newCodexStandardTransport(proxyURL)}
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, nil, fmt.Errorf("wham request: %w", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		// 调用方需要根据状态码触发刷新 / 冷却；返回 resp 让上层处理 body。
+		return nil, resp, fmt.Errorf("wham returned status %d", resp.StatusCode)
+	}
+
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 64<<10))
+	_ = resp.Body.Close()
+	if err != nil {
+		return nil, resp, fmt.Errorf("read wham response: %w", err)
+	}
+
+	var usage WhamUsage
+	if err := json.Unmarshal(body, &usage); err != nil {
+		return nil, resp, fmt.Errorf("parse wham response: %w", err)
+	}
+	return &usage, resp, nil
+}
+
+// ApplyWhamUsage 将 /wham/usage 返回的数据写入账号 state + 持久化。
+// 行为与 SyncCodexUsageState（处理 /responses 响应头时）保持一致：
+//   - plan_type 同步到内存 + DB
+//   - 5h 窗口写入 SetUsageSnapshot5h
+//   - 7d 窗口走 PersistUsageSnapshot
+//   - premium 5h 用尽时走 MarkPremium5hRateLimited
+func ApplyWhamUsage(store *auth.Store, account *auth.Account, usage *WhamUsage) CodexUsageSyncResult {
+	result := CodexUsageSyncResult{}
+	if account == nil || usage == nil {
+		return result
+	}
+
+	if store != nil && usage.PlanType != "" {
+		store.UpdateAccountPlanType(account, usage.PlanType)
+	}
+
+	now := time.Now()
+
+	// 5h 主窗口
+	if w := usage.RateLimit.PrimaryWindow; w != nil && w.LimitWindowSeconds > 0 {
+		resetAt := whamWindowResetAt(w, now)
+		account.SetUsageSnapshot5h(w.UsedPercent, resetAt)
+		result.UsagePct5h = w.UsedPercent
+		result.Reset5hAt = resetAt
+		result.HasUsage5h = true
+		result.Used5hHeaders = true
+	}
+
+	// 7d 次窗口
+	if w := usage.RateLimit.SecondaryWindow; w != nil && w.LimitWindowSeconds > 0 {
+		resetAt := whamWindowResetAt(w, now)
+		account.SetReset7dAt(resetAt)
+		result.UsagePct7d = w.UsedPercent
+		result.HasUsage7d = true
+		if store != nil {
+			store.PersistUsageSnapshot(account, w.UsedPercent)
+		}
+	} else if result.Used5hHeaders && store != nil {
+		// 只有 5h 数据时，单独持久化 5h 快照
+		store.PersistUsageSnapshot5hOnly(account)
+		result.Persisted5hOnly = true
+	}
+
+	// premium 5h 限流标记
+	if result.Used5hHeaders && account.IsPremium5hPlan() && result.HasUsage5h && result.UsagePct5h >= 100 {
+		if store != nil {
+			store.MarkPremium5hRateLimited(account, result.Reset5hAt)
+		}
+		result.Premium5hRateLimited = true
+	}
+
+	return result
+}
+
+func whamWindowResetAt(w *WhamUsageWindow, now time.Time) time.Time {
+	if w == nil {
+		return time.Time{}
+	}
+	// reset_at 是 unix 时间戳（秒），优先使用；缺失时 fallback 到 reset_after_seconds
+	if w.ResetAt > 0 {
+		return time.Unix(w.ResetAt, 0)
+	}
+	if w.ResetAfterSeconds > 0 {
+		return now.Add(time.Duration(w.ResetAfterSeconds) * time.Second)
+	}
+	return time.Time{}
+}