Upload 86 files

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+app/template/favicon.png filter=lfs diff=lfs merge=lfs -text

app/__init__.py

@@ -0,0 +1 @@
+"""App Package"""

app/api/v1/admin.py

@@ -0,0 +1,1299 @@
+from fastapi import APIRouter, Depends, HTTPException, Request, Query, Body, WebSocket
+from fastapi.responses import HTMLResponse, RedirectResponse
+from pydantic import BaseModel
+from typing import Any, Optional
+
+from app.core.auth import verify_api_key
+from app.core.config import config, get_config
+from app.core.storage import get_storage, LocalStorage, RedisStorage, SQLStorage
+import os
+from pathlib import Path
+import aiofiles
+import asyncio
+import json
+import time
+import uuid
+import orjson
+from starlette.websockets import WebSocketDisconnect, WebSocketState
+from app.core.logger import logger
+from app.services.register import get_auto_register_manager
+from app.services.register.account_settings_refresh import (
+    refresh_account_settings_for_tokens,
+    normalize_sso_token as normalize_refresh_token,
+)
+from app.services.api_keys import api_key_manager
+from app.services.grok.model import ModelService
+from app.services.grok.imagine_generation import (
+    collect_experimental_generation_images,
+    is_valid_image_value as is_valid_imagine_image_value,
+    resolve_aspect_ratio as resolve_imagine_aspect_ratio,
+)
+from app.services.token import get_token_manager
+from app.core.auth import _load_legacy_api_keys
+
+
+router = APIRouter()
+
+TEMPLATE_DIR = Path(__file__).parent.parent.parent / "static"
+
+
+class AdminLoginBody(BaseModel):
+    username: str | None = None
+    password: str | None = None
+
+async def render_template(filename: str):
+    """渲染指定模板"""
+    template_path = TEMPLATE_DIR / filename
+    if not template_path.exists():
+        return HTMLResponse(f"Template {filename} not found.", status_code=404)
+    
+    async with aiofiles.open(template_path, "r", encoding="utf-8") as f:
+        content = await f.read()
+    return HTMLResponse(content)
+
+@router.get("/", include_in_schema=False)
+async def root_redirect():
+    """Default entry -> /login (consistent with Workers/Pages)."""
+    return RedirectResponse(url="/login", status_code=302)
+
+
+@router.get("/login", response_class=HTMLResponse, include_in_schema=False)
+async def login_page():
+    """Login page (default)."""
+    return await render_template("login/login.html")
+
+
+@router.get("/admin", response_class=HTMLResponse, include_in_schema=False)
+async def admin_login_page():
+    """Legacy login entry (redirect to /login)."""
+    return RedirectResponse(url="/login", status_code=302)
+
+@router.get("/admin/config", response_class=HTMLResponse, include_in_schema=False)
+async def admin_config_page():
+    """配置管理页"""
+    return await render_template("config/config.html")
+
+@router.get("/admin/token", response_class=HTMLResponse, include_in_schema=False)
+async def admin_token_page():
+    """Token 管理页"""
+    return await render_template("token/token.html")
+
+@router.get("/admin/datacenter", response_class=HTMLResponse, include_in_schema=False)
+async def admin_datacenter_page():
+    """数据中心页"""
+    return await render_template("datacenter/datacenter.html")
+
+@router.get("/admin/keys", response_class=HTMLResponse, include_in_schema=False)
+async def admin_keys_page():
+    """API Key 管理页"""
+    return await render_template("keys/keys.html")
+
+@router.get("/chat", response_class=HTMLResponse, include_in_schema=False)
+async def chat_page():
+    """在线聊天页（公开入口）"""
+    return await render_template("chat/chat.html")
+
+@router.get("/admin/chat", response_class=HTMLResponse, include_in_schema=False)
+async def admin_chat_page():
+    """在线聊天页（后台入口）"""
+    return await render_template("chat/chat_admin.html")
+
+
+async def _verify_ws_api_key(websocket: WebSocket) -> bool:
+    api_key = str(get_config("app.api_key", "") or "").strip()
+    legacy_keys = await _load_legacy_api_keys()
+    if not api_key and not legacy_keys:
+        return True
+    token = str(websocket.query_params.get("api_key") or "").strip()
+    if not token:
+        return False
+    if (api_key and token == api_key) or token in legacy_keys:
+        return True
+    try:
+        await api_key_manager.init()
+        if api_key_manager.validate_key(token):
+            return True
+    except Exception as e:
+        logger.warning(f"Imagine ws api_key validation fallback failed: {e}")
+    return False
+
+
+async def _collect_imagine_batch(token: str, prompt: str, aspect_ratio: str) -> list[str]:
+    return await collect_experimental_generation_images(
+        token=token,
+        prompt=prompt,
+        n=6,
+        response_format="b64_json",
+        aspect_ratio=aspect_ratio,
+        concurrency=1,
+    )
+
+
+@router.websocket("/api/v1/admin/imagine/ws")
+async def admin_imagine_ws(websocket: WebSocket):
+    if not await _verify_ws_api_key(websocket):
+        await websocket.close(code=1008)
+        return
+
+    await websocket.accept()
+    stop_event = asyncio.Event()
+    run_task: Optional[asyncio.Task] = None
+
+    async def _send(payload: dict) -> bool:
+        try:
+            await websocket.send_text(orjson.dumps(payload).decode())
+            return True
+        except Exception:
+            return False
+
+    async def _stop_run():
+        nonlocal run_task
+        stop_event.set()
+        if run_task and not run_task.done():
+            run_task.cancel()
+            try:
+                await run_task
+            except asyncio.CancelledError:
+                pass
+            except Exception:
+                pass
+        run_task = None
+        stop_event.clear()
+
+    async def _run(prompt: str, aspect_ratio: str):
+        model_id = "grok-imagine-1.0"
+        model_info = ModelService.get(model_id)
+        if not model_info or not model_info.is_image:
+            await _send(
+                {
+                    "type": "error",
+                    "message": "Image model is not available.",
+                    "code": "model_not_supported",
+                }
+            )
+            return
+
+        token_mgr = await get_token_manager()
+        sequence = 0
+        run_id = uuid.uuid4().hex
+        await _send(
+            {
+                "type": "status",
+                "status": "running",
+                "prompt": prompt,
+                "aspect_ratio": aspect_ratio,
+                "run_id": run_id,
+            }
+        )
+
+        while not stop_event.is_set():
+            try:
+                await token_mgr.reload_if_stale()
+                token = token_mgr.get_token_for_model(model_info.model_id)
+                if not token:
+                    await _send(
+                        {
+                            "type": "error",
+                            "message": "No available tokens. Please try again later.",
+                            "code": "rate_limit_exceeded",
+                        }
+                    )
+                    await asyncio.sleep(2)
+                    continue
+
+                start_at = time.time()
+                images = await _collect_imagine_batch(token, prompt, aspect_ratio)
+                elapsed_ms = int((time.time() - start_at) * 1000)
+
+                sent_any = False
+                for image_b64 in images:
+                    if not is_valid_imagine_image_value(image_b64):
+                        continue
+                    sent_any = True
+                    sequence += 1
+                    ok = await _send(
+                        {
+                            "type": "image",
+                            "b64_json": image_b64,
+                            "sequence": sequence,
+                            "created_at": int(time.time() * 1000),
+                            "elapsed_ms": elapsed_ms,
+                            "aspect_ratio": aspect_ratio,
+                            "run_id": run_id,
+                        }
+                    )
+                    if not ok:
+                        stop_event.set()
+                        break
+
+                if sent_any:
+                    try:
+                        await token_mgr.sync_usage(
+                            token,
+                            model_info.model_id,
+                            consume_on_fail=True,
+                            is_usage=True,
+                        )
+                    except Exception as e:
+                        logger.warning(f"Imagine ws token sync failed: {e}")
+                else:
+                    await _send(
+                        {
+                            "type": "error",
+                            "message": "Image generation returned empty data.",
+                            "code": "empty_image",
+                        }
+                    )
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.warning(f"Imagine stream error: {e}")
+                await _send(
+                    {
+                        "type": "error",
+                        "message": str(e),
+                        "code": "internal_error",
+                    }
+                )
+                await asyncio.sleep(1.5)
+
+        await _send({"type": "status", "status": "stopped", "run_id": run_id})
+
+    try:
+        while True:
+            try:
+                raw = await websocket.receive_text()
+            except (RuntimeError, WebSocketDisconnect):
+                break
+
+            try:
+                payload = orjson.loads(raw)
+            except Exception:
+                await _send(
+                    {
+                        "type": "error",
+                        "message": "Invalid message format.",
+                        "code": "invalid_payload",
+                    }
+                )
+                continue
+
+            msg_type = payload.get("type")
+            if msg_type == "start":
+                prompt = str(payload.get("prompt") or "").strip()
+                if not prompt:
+                    await _send(
+                        {
+                            "type": "error",
+                            "message": "Prompt cannot be empty.",
+                            "code": "empty_prompt",
+                        }
+                    )
+                    continue
+                ratio = resolve_imagine_aspect_ratio(str(payload.get("aspect_ratio") or "2:3").strip())
+                await _stop_run()
+                run_task = asyncio.create_task(_run(prompt, ratio))
+            elif msg_type == "stop":
+                await _stop_run()
+            elif msg_type == "ping":
+                await _send({"type": "pong"})
+            else:
+                await _send(
+                    {
+                        "type": "error",
+                        "message": "Unknown command.",
+                        "code": "unknown_command",
+                    }
+                )
+    except WebSocketDisconnect:
+        logger.debug("WebSocket disconnected by client")
+    except asyncio.CancelledError:
+        logger.debug("WebSocket handler cancelled")
+    except Exception as e:
+        logger.warning(f"WebSocket error: {e}")
+    finally:
+        await _stop_run()
+        try:
+            if websocket.client_state == WebSocketState.CONNECTED:
+                await websocket.close(code=1000, reason="Server closing connection")
+        except Exception as e:
+            logger.debug(f"WebSocket close ignored: {e}")
+
+
+@router.post("/api/v1/admin/login")
+async def admin_login_api(request: Request, body: AdminLoginBody | None = Body(default=None)):
+    """管理后台登录验证（用户名+密码）
+
+    - 默认账号/密码：admin/admin（可在配置管理的「应用设置」里修改）
+    - 兼容旧版本：允许 Authorization: Bearer <password> 仅密码登录（用户名默认为 admin）
+    """
+
+    admin_username = str(get_config("app.admin_username", "admin") or "admin").strip() or "admin"
+    admin_password = str(get_config("app.app_key", "admin") or "admin").strip()
+
+    username = (body.username.strip() if body and isinstance(body.username, str) else "").strip()
+    password = (body.password.strip() if body and isinstance(body.password, str) else "").strip()
+
+    # Legacy: password-only via Bearer token.
+    if not password:
+        auth = request.headers.get("Authorization") or ""
+        if auth.lower().startswith("bearer "):
+            password = auth[7:].strip()
+            if not username:
+                username = "admin"
+
+    if not username or not password:
+        raise HTTPException(status_code=400, detail="Missing username or password")
+
+    if username != admin_username or password != admin_password:
+        raise HTTPException(status_code=401, detail="Invalid username or password")
+
+    return {"status": "success", "api_key": get_config("app.api_key", "")}
+
+@router.get("/api/v1/admin/config", dependencies=[Depends(verify_api_key)])
+async def get_config_api():
+    """获取当前配置"""
+    # 暴露原始配置字典
+    return config._config
+
+@router.post("/api/v1/admin/config", dependencies=[Depends(verify_api_key)])
+async def update_config_api(data: dict):
+    """更新配置"""
+    try:
+        await config.update(data)
+        return {"status": "success", "message": "配置已更新"}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+def _display_key(key: str) -> str:
+    k = str(key or "")
+    if len(k) <= 12:
+        return k
+    return f"{k[:6]}...{k[-4:]}"
+
+
+def _normalize_limit(v: Any) -> int:
+    if v is None or v == "":
+        return -1
+    try:
+        return max(-1, int(v))
+    except Exception:
+        return -1
+
+
+def _pool_to_token_type(pool_name: str) -> str:
+    return "ssoSuper" if str(pool_name or "").strip() == "ssoSuper" else "sso"
+
+
+def _parse_quota_value(v: Any) -> tuple[int, bool]:
+    if v is None or v == "":
+        return -1, False
+    try:
+        n = int(v)
+    except Exception:
+        return -1, False
+    if n < 0:
+        return -1, False
+    return n, True
+
+
+def _safe_int(v: Any, default: int = 0) -> int:
+    try:
+        return int(v)
+    except Exception:
+        return default
+
+
+def _normalize_token_status(raw_status: Any) -> str:
+    s = str(raw_status or "active").strip().lower()
+    if s == "expired":
+        return "invalid"
+    if s in ("active", "cooling", "invalid", "disabled"):
+        return s
+    return "active"
+
+
+def _normalize_admin_token_item(pool_name: str, item: Any) -> dict | None:
+    token_type = _pool_to_token_type(pool_name)
+
+    if isinstance(item, str):
+        token = item.strip()
+        if not token:
+            return None
+        if token.startswith("sso="):
+            token = token[4:]
+        return {
+            "token": token,
+            "status": "active",
+            "quota": 0,
+            "quota_known": False,
+            "heavy_quota": -1,
+            "heavy_quota_known": False,
+            "token_type": token_type,
+            "note": "",
+            "fail_count": 0,
+            "use_count": 0,
+        }
+
+    if not isinstance(item, dict):
+        return None
+
+    token = str(item.get("token") or "").strip()
+    if not token:
+        return None
+    if token.startswith("sso="):
+        token = token[4:]
+
+    quota, quota_known = _parse_quota_value(item.get("quota"))
+    heavy_quota, heavy_quota_known = _parse_quota_value(item.get("heavy_quota"))
+
+    return {
+        "token": token,
+        "status": _normalize_token_status(item.get("status")),
+        "quota": quota if quota_known else 0,
+        "quota_known": quota_known,
+        "heavy_quota": heavy_quota,
+        "heavy_quota_known": heavy_quota_known,
+        "token_type": token_type,
+        "note": str(item.get("note") or ""),
+        "fail_count": _safe_int(item.get("fail_count") or 0, 0),
+        "use_count": _safe_int(item.get("use_count") or 0, 0),
+    }
+
+
+def _collect_tokens_from_pool_payload(payload: Any) -> list[str]:
+    if not isinstance(payload, dict):
+        return []
+
+    collected: list[str] = []
+    seen: set[str] = set()
+    for raw_items in payload.values():
+        if not isinstance(raw_items, list):
+            continue
+        for item in raw_items:
+            token_raw = item if isinstance(item, str) else (item.get("token") if isinstance(item, dict) else "")
+            token = normalize_refresh_token(str(token_raw or "").strip())
+            if not token or token in seen:
+                continue
+            seen.add(token)
+            collected.append(token)
+    return collected
+
+
+def _resolve_nsfw_refresh_concurrency(override: Any = None) -> int:
+    source = override if override is not None else get_config("token.nsfw_refresh_concurrency", 10)
+    try:
+        value = int(source)
+    except Exception:
+        value = 10
+    return max(1, value)
+
+
+def _resolve_nsfw_refresh_retries(override: Any = None) -> int:
+    source = override if override is not None else get_config("token.nsfw_refresh_retries", 3)
+    try:
+        value = int(source)
+    except Exception:
+        value = 3
+    return max(0, value)
+
+
+def _trigger_account_settings_refresh_background(
+    tokens: list[str],
+    concurrency: int,
+    retries: int,
+) -> None:
+    if not tokens:
+        return
+
+    async def _run() -> None:
+        try:
+            result = await refresh_account_settings_for_tokens(
+                tokens=tokens,
+                concurrency=concurrency,
+                retries=retries,
+            )
+            summary = result.get("summary") or {}
+            logger.info(
+                "Background account-settings refresh finished: total={} success={} failed={} invalidated={}",
+                summary.get("total", 0),
+                summary.get("success", 0),
+                summary.get("failed", 0),
+                summary.get("invalidated", 0),
+            )
+        except Exception as exc:
+            logger.warning("Background account-settings refresh failed: {}", exc)
+
+    asyncio.create_task(_run())
+
+
+@router.get("/api/v1/admin/keys", dependencies=[Depends(verify_api_key)])
+async def list_api_keys():
+    """List API keys + daily usage/remaining (for admin UI)."""
+    await api_key_manager.init()
+    day, usage_map = await api_key_manager.usage_today()
+
+    out = []
+    for row in api_key_manager.get_all_keys():
+        key = str(row.get("key") or "")
+        used = usage_map.get(key) or {}
+        chat_used = int(used.get("chat_used", 0) or 0)
+        heavy_used = int(used.get("heavy_used", 0) or 0)
+        image_used = int(used.get("image_used", 0) or 0)
+        video_used = int(used.get("video_used", 0) or 0)
+
+        chat_limit = _normalize_limit(row.get("chat_limit", -1))
+        heavy_limit = _normalize_limit(row.get("heavy_limit", -1))
+        image_limit = _normalize_limit(row.get("image_limit", -1))
+        video_limit = _normalize_limit(row.get("video_limit", -1))
+
+        remaining = {
+            "chat": None if chat_limit < 0 else max(0, chat_limit - chat_used),
+            "heavy": None if heavy_limit < 0 else max(0, heavy_limit - heavy_used),
+            "image": None if image_limit < 0 else max(0, image_limit - image_used),
+            "video": None if video_limit < 0 else max(0, video_limit - video_used),
+        }
+
+        out.append({
+            **row,
+            "is_active": bool(row.get("is_active", True)),
+            "display_key": _display_key(key),
+            "usage_today": {
+                "chat_used": chat_used,
+                "heavy_used": heavy_used,
+                "image_used": image_used,
+                "video_used": video_used,
+            },
+            "remaining_today": remaining,
+            "day": day,
+        })
+
+    # New UI expects { success: true, data: [...] }
+    return {"success": True, "data": out}
+
+
+@router.post("/api/v1/admin/keys", dependencies=[Depends(verify_api_key)])
+async def create_api_key(data: dict):
+    """Create a new API key (optional name/key/limits)."""
+    await api_key_manager.init()
+    data = data or {}
+
+    name = str(data.get("name") or "").strip() or api_key_manager.generate_name()
+    key_val = str(data.get("key") or "").strip() or None
+    is_active = bool(data.get("is_active", True))
+
+    limits = data.get("limits") if isinstance(data.get("limits"), dict) else {}
+    try:
+        row = await api_key_manager.add_key(
+            name=name,
+            key=key_val,
+            is_active=is_active,
+            limits={
+                "chat_per_day": limits.get("chat_per_day"),
+                "heavy_per_day": limits.get("heavy_per_day"),
+                "image_per_day": limits.get("image_per_day"),
+                "video_per_day": limits.get("video_per_day"),
+            },
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    return {"success": True, "data": {**row, "display_key": _display_key(row.get("key", ""))}}
+
+
+@router.post("/api/v1/admin/keys/update", dependencies=[Depends(verify_api_key)])
+async def update_api_key(data: dict):
+    """Update name/status/limits for an API key."""
+    await api_key_manager.init()
+    data = data or {}
+    key = str(data.get("key") or "").strip()
+    if not key:
+        raise HTTPException(status_code=400, detail="Missing key")
+
+    existing = api_key_manager.get_key_row(key)
+    if not existing:
+        raise HTTPException(status_code=404, detail="Key not found")
+
+    if "name" in data and data.get("name") is not None:
+        name = str(data.get("name") or "").strip()
+        if name:
+            await api_key_manager.update_key_name(key, name)
+
+    if "is_active" in data:
+        await api_key_manager.update_key_status(key, bool(data.get("is_active")))
+
+    limits = data.get("limits") if isinstance(data.get("limits"), dict) else None
+    if limits is not None:
+        await api_key_manager.update_key_limits(
+            key,
+            {
+                "chat_per_day": limits.get("chat_per_day"),
+                "heavy_per_day": limits.get("heavy_per_day"),
+                "image_per_day": limits.get("image_per_day"),
+                "video_per_day": limits.get("video_per_day"),
+            },
+        )
+
+    return {"success": True}
+
+
+@router.post("/api/v1/admin/keys/delete", dependencies=[Depends(verify_api_key)])
+async def delete_api_key(data: dict):
+    """Delete an API key."""
+    await api_key_manager.init()
+    data = data or {}
+    key = str(data.get("key") or "").strip()
+    if not key:
+        raise HTTPException(status_code=400, detail="Missing key")
+
+    ok = await api_key_manager.delete_key(key)
+    if not ok:
+        raise HTTPException(status_code=404, detail="Key not found")
+    return {"success": True}
+
+@router.get("/api/v1/admin/storage", dependencies=[Depends(verify_api_key)])
+async def get_storage_info():
+    """获取当前存储模式"""
+    storage_type = os.getenv("SERVER_STORAGE_TYPE", "local").lower()
+    logger.info(f"Storage type: {storage_type}")
+    if not storage_type:
+        storage_type = str(get_config("storage.type", "")).lower()
+    if not storage_type:
+        storage = get_storage()
+        if isinstance(storage, LocalStorage):
+            storage_type = "local"
+        elif isinstance(storage, RedisStorage):
+            storage_type = "redis"
+        elif isinstance(storage, SQLStorage):
+            if storage.dialect in ("mysql", "mariadb"):
+                storage_type = "mysql"
+            elif storage.dialect in ("postgres", "postgresql", "pgsql"):
+                storage_type = "pgsql"
+            else:
+                storage_type = storage.dialect
+    return {"type": storage_type or "local"}
+
+@router.get("/api/v1/admin/tokens", dependencies=[Depends(verify_api_key)])
+async def get_tokens_api():
+    """获取所有 Token"""
+    storage = get_storage()
+    tokens = await storage.load_tokens()
+    data = tokens if isinstance(tokens, dict) else {}
+    out: dict[str, list[dict]] = {}
+    for pool_name, raw_items in data.items():
+        arr = raw_items if isinstance(raw_items, list) else []
+        normalized: list[dict] = []
+        for item in arr:
+            obj = _normalize_admin_token_item(pool_name, item)
+            if obj:
+                normalized.append(obj)
+        out[str(pool_name)] = normalized
+    return out
+
+@router.post("/api/v1/admin/tokens", dependencies=[Depends(verify_api_key)])
+async def update_tokens_api(data: dict):
+    """Update token payload and trigger background account-settings refresh for new tokens."""
+    storage = get_storage()
+    try:
+        from app.services.token.manager import get_token_manager
+
+        posted_data = data if isinstance(data, dict) else {}
+        existing_tokens: list[str] = []
+        added_tokens: list[str] = []
+
+        async with storage.acquire_lock("tokens_save", timeout=10):
+            old_data = await storage.load_tokens()
+            existing_tokens = _collect_tokens_from_pool_payload(
+                old_data if isinstance(old_data, dict) else {}
+            )
+
+            await storage.save_tokens(posted_data)
+            mgr = await get_token_manager()
+            await mgr.reload()
+
+            new_tokens = _collect_tokens_from_pool_payload(posted_data)
+            existing_set = set(existing_tokens)
+            added_tokens = [token for token in new_tokens if token not in existing_set]
+
+        concurrency = _resolve_nsfw_refresh_concurrency()
+        retries = _resolve_nsfw_refresh_retries()
+        _trigger_account_settings_refresh_background(
+            tokens=added_tokens,
+            concurrency=concurrency,
+            retries=retries,
+        )
+
+        return {
+            "status": "success",
+            "message": "Token updated",
+            "nsfw_refresh": {
+                "mode": "background",
+                "triggered": len(added_tokens),
+                "concurrency": concurrency,
+                "retries": retries,
+            },
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.post("/api/v1/admin/tokens/refresh", dependencies=[Depends(verify_api_key)])
+async def refresh_tokens_api(data: dict):
+    """刷新 Token 状态"""
+    from app.services.token.manager import get_token_manager
+    
+    try:
+        mgr = await get_token_manager()
+        tokens = []
+        if "token" in data:
+            tokens.append(data["token"])
+        if "tokens" in data and isinstance(data["tokens"], list):
+            tokens.extend(data["tokens"])
+            
+        if not tokens:
+             raise HTTPException(status_code=400, detail="No tokens provided")
+             
+        unique_tokens = list(set(tokens))
+        
+        sem = asyncio.Semaphore(10)
+        
+        async def _refresh_one(t):
+            async with sem:
+                return t, await mgr.sync_usage(t, "grok-3", consume_on_fail=False, is_usage=False)
+        
+        results_list = await asyncio.gather(*[_refresh_one(t) for t in unique_tokens])
+        results = dict(results_list)
+            
+        return {"status": "success", "results": results}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/api/v1/admin/tokens/nsfw/refresh", dependencies=[Depends(verify_api_key)])
+async def refresh_tokens_nsfw_api(data: dict):
+    """Refresh account settings (TOS + birth date + NSFW) for selected/all tokens."""
+    payload = data if isinstance(data, dict) else {}
+    mgr = await get_token_manager()
+
+    tokens: list[str] = []
+    seen: set[str] = set()
+
+    if bool(payload.get("all")):
+        for pool in mgr.pools.values():
+            for info in pool.list():
+                token = normalize_refresh_token(str(info.token or "").strip())
+                if not token or token in seen:
+                    continue
+                seen.add(token)
+                tokens.append(token)
+    else:
+        candidates: list[str] = []
+        single = payload.get("token")
+        if isinstance(single, str):
+            candidates.append(single)
+        batch = payload.get("tokens")
+        if isinstance(batch, list):
+            candidates.extend([item for item in batch if isinstance(item, str)])
+
+        for raw in candidates:
+            token = normalize_refresh_token(str(raw or "").strip())
+            if not token or token in seen:
+                continue
+            seen.add(token)
+            tokens.append(token)
+
+    if not tokens:
+        raise HTTPException(status_code=400, detail="No tokens provided")
+
+    concurrency = _resolve_nsfw_refresh_concurrency(payload.get("concurrency"))
+    retries = _resolve_nsfw_refresh_retries(payload.get("retries"))
+    result = await refresh_account_settings_for_tokens(
+        tokens=tokens,
+        concurrency=concurrency,
+        retries=retries,
+    )
+    return {
+        "status": "success",
+        "summary": result.get("summary") or {},
+        "failed": result.get("failed") or [],
+    }
+
+
+@router.post("/api/v1/admin/tokens/auto-register", dependencies=[Depends(verify_api_key)])
+async def auto_register_tokens_api(data: dict):
+    """Start auto registration."""
+    try:
+        data = data or {}
+        count = data.get("count")
+        concurrency = data.get("concurrency")
+        pool = (data.get("pool") or "ssoBasic").strip() or "ssoBasic"
+
+        try:
+            count_val = int(count)
+        except Exception:
+            count_val = int(get_config("register.default_count", 100) or 100)
+
+        if count_val <= 0:
+            count_val = int(get_config("register.default_count", 100) or 100)
+
+        try:
+            concurrency_val = int(concurrency)
+        except Exception:
+            concurrency_val = None
+        if concurrency_val is not None and concurrency_val <= 0:
+            concurrency_val = None
+
+        manager = get_auto_register_manager()
+        job = await manager.start_job(count=count_val, pool=pool, concurrency=concurrency_val)
+        return {"status": "started", "job": job.to_dict()}
+    except RuntimeError as e:
+        raise HTTPException(status_code=409, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/api/v1/admin/tokens/auto-register/status", dependencies=[Depends(verify_api_key)])
+async def auto_register_status_api(job_id: str | None = None):
+    """Get auto registration status."""
+    manager = get_auto_register_manager()
+    status = manager.get_status(job_id)
+    if status.get("status") == "not_found":
+        raise HTTPException(status_code=404, detail="Job not found")
+    return status
+
+
+@router.post("/api/v1/admin/tokens/auto-register/stop", dependencies=[Depends(verify_api_key)])
+async def auto_register_stop_api(job_id: str | None = None):
+    """Stop auto registration (best-effort)."""
+    manager = get_auto_register_manager()
+    status = manager.get_status(job_id)
+    if status.get("status") == "not_found":
+        raise HTTPException(status_code=404, detail="Job not found")
+    await manager.stop_job()
+    return {"status": "stopping"}
+
+@router.get("/admin/cache", response_class=HTMLResponse, include_in_schema=False)
+async def admin_cache_page():
+    """缓存管理页"""
+    return await render_template("cache/cache.html")
+
+@router.get("/api/v1/admin/cache", dependencies=[Depends(verify_api_key)])
+async def get_cache_stats_api(request: Request):
+    """获取缓存统计"""
+    from app.services.grok.assets import DownloadService, ListService
+    from app.services.token.manager import get_token_manager
+    
+    try:
+        dl_service = DownloadService()
+        image_stats = dl_service.get_stats("image")
+        video_stats = dl_service.get_stats("video")
+        
+        mgr = await get_token_manager()
+        pools = mgr.pools
+        accounts = []
+        for pool_name, pool in pools.items():
+            for info in pool.list():
+                raw_token = info.token[4:] if info.token.startswith("sso=") else info.token
+                masked = f"{raw_token[:8]}...{raw_token[-16:]}" if len(raw_token) > 24 else raw_token
+                accounts.append({
+                    "token": raw_token,
+                    "token_masked": masked,
+                    "pool": pool_name,
+                    "status": info.status,
+                    "last_asset_clear_at": info.last_asset_clear_at
+                })
+
+        scope = request.query_params.get("scope")
+        selected_token = request.query_params.get("token")
+        tokens_param = request.query_params.get("tokens")
+        selected_tokens = []
+        if tokens_param:
+            selected_tokens = [t.strip() for t in tokens_param.split(",") if t.strip()]
+
+        online_stats = {"count": 0, "status": "unknown", "token": None, "last_asset_clear_at": None}
+        online_details = []
+        account_map = {a["token"]: a for a in accounts}
+        batch_size = get_config("performance.admin_assets_batch_size", 10)
+        try:
+            batch_size = int(batch_size)
+        except Exception:
+            batch_size = 10
+        batch_size = max(1, batch_size)
+
+        async def _fetch_assets(token: str):
+            list_service = ListService()
+            try:
+                return await list_service.count(token)
+            finally:
+                await list_service.close()
+
+        async def _fetch_detail(token: str):
+            account = account_map.get(token)
+            try:
+                count = await _fetch_assets(token)
+                return ({
+                    "token": token,
+                    "token_masked": account["token_masked"] if account else token,
+                    "count": count,
+                    "status": "ok",
+                    "last_asset_clear_at": account["last_asset_clear_at"] if account else None
+                }, count)
+            except Exception as e:
+                return ({
+                    "token": token,
+                    "token_masked": account["token_masked"] if account else token,
+                    "count": 0,
+                    "status": f"error: {str(e)}",
+                    "last_asset_clear_at": account["last_asset_clear_at"] if account else None
+                }, 0)
+
+        if selected_tokens:
+            total = 0
+            for i in range(0, len(selected_tokens), batch_size):
+                chunk = selected_tokens[i:i + batch_size]
+                results = await asyncio.gather(*[_fetch_detail(token) for token in chunk])
+                for detail, count in results:
+                    online_details.append(detail)
+                    total += count
+            online_stats = {"count": total, "status": "ok" if selected_tokens else "no_token", "token": None, "last_asset_clear_at": None}
+            scope = "selected"
+        elif scope == "all":
+            total = 0
+            tokens = [account["token"] for account in accounts]
+            for i in range(0, len(tokens), batch_size):
+                chunk = tokens[i:i + batch_size]
+                results = await asyncio.gather(*[_fetch_detail(token) for token in chunk])
+                for detail, count in results:
+                    online_details.append(detail)
+                    total += count
+            online_stats = {"count": total, "status": "ok" if accounts else "no_token", "token": None, "last_asset_clear_at": None}
+        else:
+            token = selected_token
+            if token:
+                try:
+                    count = await _fetch_assets(token)
+                    match = next((a for a in accounts if a["token"] == token), None)
+                    online_stats = {
+                        "count": count,
+                        "status": "ok",
+                        "token": token,
+                        "token_masked": match["token_masked"] if match else token,
+                        "last_asset_clear_at": match["last_asset_clear_at"] if match else None
+                    }
+                except Exception as e:
+                    match = next((a for a in accounts if a["token"] == token), None)
+                    online_stats = {
+                        "count": 0,
+                        "status": f"error: {str(e)}",
+                        "token": token,
+                        "token_masked": match["token_masked"] if match else token,
+                        "last_asset_clear_at": match["last_asset_clear_at"] if match else None
+                    }
+            else:
+                online_stats = {"count": 0, "status": "not_loaded", "token": None, "last_asset_clear_at": None}
+            
+        return {
+            "local_image": image_stats,
+            "local_video": video_stats,
+            "online": online_stats,
+            "online_accounts": accounts,
+            "online_scope": scope or "none",
+            "online_details": online_details
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.post("/api/v1/admin/cache/clear", dependencies=[Depends(verify_api_key)])
+async def clear_local_cache_api(data: dict):
+    """清理本地缓存"""
+    from app.services.grok.assets import DownloadService
+    cache_type = data.get("type", "image")
+    
+    try:
+        dl_service = DownloadService()
+        result = dl_service.clear(cache_type)
+        return {"status": "success", "result": result}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.get("/api/v1/admin/cache/list", dependencies=[Depends(verify_api_key)])
+async def list_local_cache_api(
+    cache_type: str = "image",
+    type_: str = Query(default=None, alias="type"),
+    page: int = 1,
+    page_size: int = 1000
+):
+    """列出本地缓存文件"""
+    from app.services.grok.assets import DownloadService
+    try:
+        if type_:
+            cache_type = type_
+        dl_service = DownloadService()
+        result = dl_service.list_files(cache_type, page, page_size)
+        return {"status": "success", **result}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.post("/api/v1/admin/cache/item/delete", dependencies=[Depends(verify_api_key)])
+async def delete_local_cache_item_api(data: dict):
+    """删除单个本地缓存文件"""
+    from app.services.grok.assets import DownloadService
+    cache_type = data.get("type", "image")
+    name = data.get("name")
+    if not name:
+        raise HTTPException(status_code=400, detail="Missing file name")
+    try:
+        dl_service = DownloadService()
+        result = dl_service.delete_file(cache_type, name)
+        return {"status": "success", "result": result}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.post("/api/v1/admin/cache/online/clear", dependencies=[Depends(verify_api_key)])
+async def clear_online_cache_api(data: dict):
+    """清理在线缓存"""
+    from app.services.grok.assets import DeleteService
+    from app.services.token.manager import get_token_manager
+    
+    delete_service = None
+    try:
+        mgr = await get_token_manager()
+        tokens = data.get("tokens")
+        delete_service = DeleteService()
+
+        if isinstance(tokens, list):
+            token_list = [t.strip() for t in tokens if isinstance(t, str) and t.strip()]
+            if not token_list:
+                raise HTTPException(status_code=400, detail="No tokens provided")
+
+            results = {}
+            batch_size = get_config("performance.admin_assets_batch_size", 10)
+            try:
+                batch_size = int(batch_size)
+            except Exception:
+                batch_size = 10
+            batch_size = max(1, batch_size)
+
+            async def _clear_one(t: str):
+                try:
+                    result = await delete_service.delete_all(t)
+                    await mgr.mark_asset_clear(t)
+                    return t, {"status": "success", "result": result}
+                except Exception as e:
+                    return t, {"status": "error", "error": str(e)}
+
+            for i in range(0, len(token_list), batch_size):
+                chunk = token_list[i:i + batch_size]
+                res_list = await asyncio.gather(*[_clear_one(t) for t in chunk])
+                for t, res in res_list:
+                    results[t] = res
+
+            return {"status": "success", "results": results}
+
+        token = data.get("token") or mgr.get_token()
+        if not token:
+            raise HTTPException(status_code=400, detail="No available token to perform cleanup")
+
+        result = await delete_service.delete_all(token)
+        await mgr.mark_asset_clear(token)
+        return {"status": "success", "result": result}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+    finally:
+        if delete_service:
+            await delete_service.close()
+
+
+@router.get("/api/v1/admin/metrics", dependencies=[Depends(verify_api_key)])
+async def get_metrics_api():
+    """数据中心：聚合常用指标（token/cache/request_stats）。"""
+    try:
+        from app.services.request_stats import request_stats
+        from app.services.token.manager import get_token_manager
+        from app.services.token.models import TokenStatus
+        from app.services.grok.assets import DownloadService
+
+        mgr = await get_token_manager()
+        await mgr.reload_if_stale()
+
+        total = 0
+        active = 0
+        cooling = 0
+        expired = 0
+        disabled = 0
+        chat_quota = 0
+        total_calls = 0
+
+        for pool in mgr.pools.values():
+            for info in pool.list():
+                total += 1
+                total_calls += int(getattr(info, "use_count", 0) or 0)
+                if info.status == TokenStatus.ACTIVE:
+                    active += 1
+                    chat_quota += int(getattr(info, "quota", 0) or 0)
+                elif info.status == TokenStatus.COOLING:
+                    cooling += 1
+                elif info.status == TokenStatus.EXPIRED:
+                    expired += 1
+                elif info.status == TokenStatus.DISABLED:
+                    disabled += 1
+
+        dl = DownloadService()
+        local_image = dl.get_stats("image")
+        local_video = dl.get_stats("video")
+
+        await request_stats.init()
+        stats = request_stats.get_stats(hours=24, days=7)
+
+        return {
+            "tokens": {
+                "total": total,
+                "active": active,
+                "cooling": cooling,
+                "expired": expired,
+                "disabled": disabled,
+                "chat_quota": chat_quota,
+                "image_quota": int(chat_quota // 2),
+                "total_calls": total_calls,
+            },
+            "cache": {
+                "local_image": local_image,
+                "local_video": local_video,
+            },
+            "request_stats": stats,
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/api/v1/admin/cache/local", dependencies=[Depends(verify_api_key)])
+async def get_cache_local_stats_api():
+    """仅获取本地缓存统计（用于前端实时刷新）。"""
+    from app.services.grok.assets import DownloadService
+
+    try:
+        dl_service = DownloadService()
+        image_stats = dl_service.get_stats("image")
+        video_stats = dl_service.get_stats("video")
+        return {"local_image": image_stats, "local_video": video_stats}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+def _safe_log_file_path(name: str) -> Path:
+    """Resolve a log file name under ./logs safely."""
+    from app.core.logger import LOG_DIR
+
+    name = (name or "").strip()
+    if not name:
+        raise ValueError("Missing log file")
+    # Disallow path traversal.
+    if "/" in name or "\\" in name or ".." in name:
+        raise ValueError("Invalid log file name")
+
+    p = (LOG_DIR / name).resolve()
+    if LOG_DIR.resolve() not in p.parents:
+        raise ValueError("Invalid log file path")
+    if not p.exists() or not p.is_file():
+        raise FileNotFoundError(name)
+    return p
+
+
+def _format_log_line(raw: str) -> str:
+    raw = (raw or "").rstrip("\r\n")
+    if not raw:
+        return ""
+
+    # Try JSON log line (our file sink uses json lines).
+    try:
+        obj = json.loads(raw)
+        if not isinstance(obj, dict):
+            return raw
+        ts = str(obj.get("time", "") or "")
+        ts = ts.replace("T", " ")
+        if len(ts) >= 19:
+            ts = ts[:19]
+        level = str(obj.get("level", "") or "").upper()
+        caller = str(obj.get("caller", "") or "")
+        msg = str(obj.get("msg", "") or "")
+        if not (ts and level and msg):
+            return raw
+        return f"{ts} | {level:<8} | {caller} - {msg}".rstrip()
+    except Exception:
+        return raw
+
+
+def _tail_lines(path: Path, max_lines: int = 2000, max_bytes: int = 1024 * 1024) -> list[str]:
+    """Best-effort tail for a text file."""
+    try:
+        max_lines = int(max_lines)
+    except Exception:
+        max_lines = 2000
+    max_lines = max(1, min(5000, max_lines))
+    max_bytes = max(16 * 1024, min(5 * 1024 * 1024, int(max_bytes)))
+
+    with open(path, "rb") as f:
+        f.seek(0, os.SEEK_END)
+        end = f.tell()
+        start = max(0, end - max_bytes)
+        f.seek(start, os.SEEK_SET)
+        data = f.read()
+
+    text = data.decode("utf-8", errors="replace")
+    lines = text.splitlines()
+    # If we read from the middle of a line, drop the first partial line.
+    if start > 0 and lines:
+        lines = lines[1:]
+    lines = lines[-max_lines:]
+    return [_format_log_line(ln) for ln in lines if ln is not None]
+
+
+@router.get("/api/v1/admin/logs/files", dependencies=[Depends(verify_api_key)])
+async def list_log_files_api():
+    """列出可查看的日志文件（logs/*.log）。"""
+    from app.core.logger import LOG_DIR
+
+    try:
+        items = []
+        for p in LOG_DIR.glob("*.log"):
+            try:
+                stat = p.stat()
+                items.append(
+                    {
+                        "name": p.name,
+                        "size_bytes": stat.st_size,
+                        "mtime_ms": int(stat.st_mtime * 1000),
+                    }
+                )
+            except Exception:
+                continue
+        items.sort(key=lambda x: x["mtime_ms"], reverse=True)
+        return {"files": items}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/api/v1/admin/logs/tail", dependencies=[Depends(verify_api_key)])
+async def tail_log_api(file: str | None = None, lines: int = 500):
+    """读取后台日志（尾部）。"""
+    from app.core.logger import LOG_DIR
+
+    try:
+        # Default to latest log.
+        if not file:
+            candidates = sorted(LOG_DIR.glob("*.log"), key=lambda p: p.stat().st_mtime if p.exists() else 0, reverse=True)
+            if not candidates:
+                return {"file": None, "lines": []}
+            path = candidates[0]
+            file = path.name
+        else:
+            path = _safe_log_file_path(file)
+
+        data = await asyncio.to_thread(_tail_lines, path, lines)
+        return {"file": str(file), "lines": data}
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail="Log file not found")
+    except ValueError as ve:
+        raise HTTPException(status_code=400, detail=str(ve))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

app/api/v1/chat.py

@@ -0,0 +1,251 @@
+"""
+Chat Completions API 路由
+"""
+
+from typing import Any, Dict, List, Optional, Union
+
+from fastapi import APIRouter, Depends
+from fastapi.responses import StreamingResponse, JSONResponse
+from pydantic import BaseModel, Field, field_validator
+
+from app.core.auth import verify_api_key
+from app.services.grok.chat import ChatService
+from app.services.grok.model import ModelService
+from app.core.exceptions import ValidationException
+from app.services.quota import enforce_daily_quota
+
+
+router = APIRouter(tags=["Chat"])
+
+
+VALID_ROLES = ["developer", "system", "user", "assistant"]
+USER_CONTENT_TYPES = ["text", "image_url", "input_audio", "file"]
+
+
+class MessageItem(BaseModel):
+    """消息项"""
+    role: str
+    content: Union[str, List[Dict[str, Any]]]
+    
+    @field_validator("role")
+    @classmethod
+    def validate_role(cls, v):
+        if v not in VALID_ROLES:
+            raise ValueError(f"role must be one of {VALID_ROLES}")
+        return v
+
+
+class VideoConfig(BaseModel):
+    """视频生成配置"""
+    aspect_ratio: Optional[str] = Field("3:2", description="视频比例: 3:2, 16:9, 1:1 等")
+    video_length: Optional[int] = Field(6, description="视频时长(秒): 5-15")
+    resolution: Optional[str] = Field("SD", description="视频分辨率: SD, HD")
+    preset: Optional[str] = Field("custom", description="风格预设: fun, normal, spicy")
+    
+    @field_validator("aspect_ratio")
+    @classmethod
+    def validate_aspect_ratio(cls, v):
+        allowed = ["2:3", "3:2", "1:1", "9:16", "16:9"]
+        if v and v not in allowed:
+            raise ValidationException(
+                message=f"aspect_ratio must be one of {allowed}",
+                param="video_config.aspect_ratio",
+                code="invalid_aspect_ratio"
+            )
+        return v
+    
+    @field_validator("video_length")
+    @classmethod
+    def validate_video_length(cls, v):
+        if v is not None:
+            if v < 5 or v > 15:
+                raise ValidationException(
+                    message="video_length must be between 5 and 15 seconds",
+                    param="video_config.video_length",
+                    code="invalid_video_length"
+                )
+        return v
+
+    @field_validator("resolution")
+    @classmethod
+    def validate_resolution(cls, v):
+        allowed = ["SD", "HD"]
+        if v and v not in allowed:
+            raise ValidationException(
+                message=f"resolution must be one of {allowed}",
+                param="video_config.resolution",
+                code="invalid_resolution"
+            )
+        return v
+    
+    @field_validator("preset")
+    @classmethod
+    def validate_preset(cls, v):
+        # 允许为空，默认 custom
+        if not v:
+            return "custom"
+        allowed = ["fun", "normal", "spicy", "custom"]
+        if v not in allowed:
+             raise ValidationException(
+                message=f"preset must be one of {allowed}",
+                param="video_config.preset",
+                code="invalid_preset"
+             )
+        return v
+
+
+class ChatCompletionRequest(BaseModel):
+    """Chat Completions 请求"""
+    model: str = Field(..., description="模型名称")
+    messages: List[MessageItem] = Field(..., description="消息数组")
+    stream: Optional[bool] = Field(None, description="是否流式输出")
+    thinking: Optional[str] = Field(None, description="思考模式: enabled/disabled/None")
+    
+    # 视频生成配置
+    video_config: Optional[VideoConfig] = Field(None, description="视频生成参数")
+    
+    model_config = {
+        "extra": "ignore"
+    }
+
+
+def validate_request(request: ChatCompletionRequest):
+    """验证请求参数"""
+    # 验证模型
+    if not ModelService.valid(request.model):
+        raise ValidationException(
+            message=f"The model `{request.model}` does not exist or you do not have access to it.",
+            param="model",
+            code="model_not_found"
+        )
+    
+    # 验证消息
+    for idx, msg in enumerate(request.messages):
+        content = msg.content
+        
+        # 字符串内容
+        if isinstance(content, str):
+            if not content.strip():
+                raise ValidationException(
+                    message="Message content cannot be empty",
+                    param=f"messages.{idx}.content",
+                    code="empty_content"
+                )
+        
+        # 列表内容
+        elif isinstance(content, list):
+            if not content:
+                raise ValidationException(
+                    message="Message content cannot be an empty array",
+                    param=f"messages.{idx}.content",
+                    code="empty_content"
+                )
+            
+            for block_idx, block in enumerate(content):
+                # 检查空对象
+                if not block:
+                    raise ValidationException(
+                        message="Content block cannot be empty",
+                        param=f"messages.{idx}.content.{block_idx}",
+                        code="empty_block"
+                    )
+                
+                # 检查 type 字段
+                if "type" not in block:
+                    raise ValidationException(
+                        message="Content block must have a 'type' field",
+                        param=f"messages.{idx}.content.{block_idx}",
+                        code="missing_type"
+                    )
+                
+                block_type = block.get("type")
+                
+                # 检查 type 空值
+                if not block_type or not isinstance(block_type, str) or not block_type.strip():
+                    raise ValidationException(
+                        message="Content block 'type' cannot be empty",
+                        param=f"messages.{idx}.content.{block_idx}.type",
+                        code="empty_type"
+                    )
+                
+                # 验证 type 有效性
+                if msg.role == "user":
+                    if block_type not in USER_CONTENT_TYPES:
+                        raise ValidationException(
+                            message=f"Invalid content block type: '{block_type}'",
+                            param=f"messages.{idx}.content.{block_idx}.type",
+                            code="invalid_type"
+                        )
+                elif block_type != "text":
+                    raise ValidationException(
+                        message=f"The `{msg.role}` role only supports 'text' type, got '{block_type}'",
+                        param=f"messages.{idx}.content.{block_idx}.type",
+                        code="invalid_type"
+                    )
+                
+                # 验证字段是否存在 & 非空
+                if block_type == "text":
+                    text = block.get("text", "")
+                    if not isinstance(text, str) or not text.strip():
+                        raise ValidationException(
+                            message="Text content cannot be empty",
+                            param=f"messages.{idx}.content.{block_idx}.text",
+                            code="empty_text"
+                        )
+                elif block_type == "image_url":
+                    image_url = block.get("image_url")
+                    if not image_url or not (isinstance(image_url, dict) and image_url.get("url")):
+                        raise ValidationException(
+                            message="image_url must have a 'url' field",
+                            param=f"messages.{idx}.content.{block_idx}.image_url",
+                            code="missing_url"
+                        )
+
+
+@router.post("/chat/completions")
+async def chat_completions(request: ChatCompletionRequest, api_key: Optional[str] = Depends(verify_api_key)):
+    """Chat Completions API - 兼容 OpenAI"""
+    
+    # 参数验证
+    validate_request(request)
+
+    # Daily quota (best-effort)
+    await enforce_daily_quota(api_key, request.model)
+    
+    # 检测视频模型
+    model_info = ModelService.get(request.model)
+    if model_info and model_info.is_video:
+        from app.services.grok.media import VideoService
+        
+        # 提取视频配置 (默认值在 Pydantic 模型中处理)
+        v_conf = request.video_config or VideoConfig()
+        
+        result = await VideoService.completions(
+            model=request.model,
+            messages=[msg.model_dump() for msg in request.messages],
+            stream=request.stream,
+            thinking=request.thinking,
+            aspect_ratio=v_conf.aspect_ratio,
+            video_length=v_conf.video_length,
+            resolution=v_conf.resolution,
+            preset=v_conf.preset
+        )
+    else:
+        result = await ChatService.completions(
+            model=request.model,
+            messages=[msg.model_dump() for msg in request.messages],
+            stream=request.stream,
+            thinking=request.thinking
+        )
+    
+    if isinstance(result, dict):
+        return JSONResponse(content=result)
+    else:
+        return StreamingResponse(
+            result,
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"}
+        )
+
+
+__all__ = ["router"]

app/api/v1/files.py

@@ -0,0 +1,72 @@
+"""
+文件服务 API 路由
+"""
+
+import aiofiles.os
+from pathlib import Path
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import FileResponse
+
+from app.core.logger import logger
+
+router = APIRouter(tags=["Files"])
+
+# 缓存根目录
+BASE_DIR = Path(__file__).parent.parent.parent.parent / "data" / "tmp"
+IMAGE_DIR = BASE_DIR / "image"
+VIDEO_DIR = BASE_DIR / "video"
+
+
+@router.get("/image/{filename:path}")
+async def get_image(filename: str):
+    """
+    获取图片文件
+    """
+    if "/" in filename:
+        filename = filename.replace("/", "-")
+        
+    file_path = IMAGE_DIR / filename
+    
+    if await aiofiles.os.path.exists(file_path):
+        if await aiofiles.os.path.isfile(file_path):
+            content_type = "image/jpeg"
+            if file_path.suffix.lower() == ".png":
+                content_type = "image/png"
+            elif file_path.suffix.lower() == ".webp":
+                content_type = "image/webp"
+            
+            # 增加缓存头，支持高并发场景下的浏览器/CDN缓存
+            return FileResponse(
+                file_path, 
+                media_type=content_type,
+                headers={
+                    "Cache-Control": "public, max-age=31536000, immutable"
+                }
+            )
+
+    logger.warning(f"Image not found: {filename}")
+    raise HTTPException(status_code=404, detail="Image not found")
+
+
+@router.get("/video/{filename:path}")
+async def get_video(filename: str):
+    """
+    获取视频文件
+    """
+    if "/" in filename:
+        filename = filename.replace("/", "-")
+        
+    file_path = VIDEO_DIR / filename
+    
+    if await aiofiles.os.path.exists(file_path):
+        if await aiofiles.os.path.isfile(file_path):
+            return FileResponse(
+                file_path, 
+                media_type="video/mp4",
+                headers={
+                    "Cache-Control": "public, max-age=31536000, immutable"
+                }
+            )
+
+    logger.warning(f"Video not found: {filename}")
+    raise HTTPException(status_code=404, detail="Video not found")

app/api/v1/image.py

@@ -0,0 +1,1065 @@
+"""
+Image Generation API 路由
+"""
+
+import asyncio
+import base64
+import random
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Union
+
+import orjson
+from fastapi import APIRouter, Depends, File, Form, UploadFile
+from fastapi.responses import JSONResponse, StreamingResponse
+from pydantic import BaseModel, Field, ValidationError
+
+from app.core.auth import verify_api_key
+from app.core.config import get_config
+from app.core.exceptions import AppException, ErrorType, UpstreamException, ValidationException
+from app.core.logger import logger
+from app.services.grok.assets import UploadService
+from app.services.grok.chat import GrokChatService
+from app.services.grok.imagine_experimental import (
+    IMAGE_METHOD_IMAGINE_WS_EXPERIMENTAL,
+    IMAGE_METHOD_LEGACY,
+    ImagineExperimentalService,
+    resolve_image_generation_method,
+)
+from app.services.grok.imagine_generation import (
+    call_experimental_generation_once,
+    collect_experimental_generation_images,
+    dedupe_images as dedupe_imagine_images,
+    is_valid_image_value as is_valid_imagine_image_value,
+    resolve_aspect_ratio as resolve_imagine_aspect_ratio,
+)
+from app.services.grok.model import ModelService
+from app.services.grok.processor import ImageCollectProcessor, ImageStreamProcessor
+from app.services.quota import enforce_daily_quota
+from app.services.request_stats import request_stats
+from app.services.token import get_token_manager
+
+
+router = APIRouter(tags=["Images"])
+ALLOWED_RESPONSE_FORMATS = {"b64_json", "base64", "url"}
+
+
+class ImageGenerationRequest(BaseModel):
+    """Image generation request - OpenAI compatible."""
+
+    prompt: str = Field(..., description="Image prompt")
+    model: Optional[str] = Field("grok-imagine-1.0", description="Model name")
+    n: Optional[int] = Field(1, ge=1, le=10, description="Image count (1-10)")
+    size: Optional[str] = Field("1024x1024", description="Image size / ratio")
+    quality: Optional[str] = Field("standard", description="Reserved")
+    response_format: Optional[str] = Field(None, description="Response format")
+    style: Optional[str] = Field(None, description="Reserved")
+    stream: Optional[bool] = Field(False, description="Enable streaming")
+    concurrency: Optional[int] = Field(1, ge=1, le=3, description="Experimental concurrency")
+
+
+class ImageEditRequest(BaseModel):
+    """Image edit request - OpenAI compatible."""
+
+    prompt: str = Field(..., description="Edit prompt")
+    model: Optional[str] = Field("grok-imagine-1.0-edit", description="Model name")
+    image: Optional[Union[str, List[str]]] = Field(None, description="Input image(s)")
+    n: Optional[int] = Field(1, ge=1, le=10, description="Image count (1-10)")
+    size: Optional[str] = Field("1024x1024", description="Reserved")
+    quality: Optional[str] = Field("standard", description="Reserved")
+    response_format: Optional[str] = Field(None, description="Response format")
+    style: Optional[str] = Field(None, description="Reserved")
+    stream: Optional[bool] = Field(False, description="Enable streaming")
+
+
+def validate_generation_request(request: ImageGenerationRequest):
+    """Validate image generation request parameters."""
+    model_id = request.model or "grok-imagine-1.0"
+    if model_id != "grok-imagine-1.0":
+        raise ValidationException(
+            message="The model `grok-imagine-1.0` is required for image generation.",
+            param="model",
+            code="model_not_supported",
+        )
+
+    model_info = ModelService.get(model_id)
+    if not model_info or not model_info.is_image:
+        raise ValidationException(
+            message=f"The model `{model_id}` is not supported for image generation.",
+            param="model",
+            code="model_not_supported",
+        )
+
+    if not request.prompt or not request.prompt.strip():
+        raise ValidationException(
+            message="Prompt cannot be empty",
+            param="prompt",
+            code="empty_prompt",
+        )
+
+    if request.n is None:
+        request.n = 1
+    if request.n < 1 or request.n > 10:
+        raise ValidationException(
+            message="n must be between 1 and 10",
+            param="n",
+            code="invalid_n",
+        )
+
+    if request.stream and request.n not in [1, 2]:
+        raise ValidationException(
+            message="Streaming is only supported when n=1 or n=2",
+            param="stream",
+            code="invalid_stream_n",
+        )
+
+    if request.concurrency is None:
+        request.concurrency = 1
+    if request.concurrency < 1 or request.concurrency > 3:
+        raise ValidationException(
+            message="concurrency must be between 1 and 3",
+            param="concurrency",
+            code="invalid_concurrency",
+        )
+
+    if request.response_format:
+        candidate = request.response_format.lower()
+        if candidate not in ALLOWED_RESPONSE_FORMATS:
+            raise ValidationException(
+                message=f"response_format must be one of {sorted(ALLOWED_RESPONSE_FORMATS)}",
+                param="response_format",
+                code="invalid_response_format",
+            )
+
+
+def validate_edit_request(request: ImageEditRequest, images: List[UploadFile]):
+    """Validate image edit request parameters."""
+    model_id = request.model or "grok-imagine-1.0-edit"
+    if model_id != "grok-imagine-1.0-edit":
+        raise ValidationException(
+            message="The model `grok-imagine-1.0-edit` is required for image edits.",
+            param="model",
+            code="model_not_supported",
+        )
+
+    model_info = ModelService.get(model_id)
+    if not model_info or not model_info.is_image:
+        raise ValidationException(
+            message=f"The model `{model_id}` is not supported for image edits.",
+            param="model",
+            code="model_not_supported",
+        )
+
+    if not request.prompt or not request.prompt.strip():
+        raise ValidationException(
+            message="Prompt cannot be empty",
+            param="prompt",
+            code="empty_prompt",
+        )
+
+    if request.n is None:
+        request.n = 1
+    if request.n < 1 or request.n > 10:
+        raise ValidationException(
+            message="n must be between 1 and 10",
+            param="n",
+            code="invalid_n",
+        )
+
+    if request.stream and request.n not in [1, 2]:
+        raise ValidationException(
+            message="Streaming is only supported when n=1 or n=2",
+            param="stream",
+            code="invalid_stream_n",
+        )
+
+    if request.response_format:
+        candidate = request.response_format.lower()
+        if candidate not in ALLOWED_RESPONSE_FORMATS:
+            raise ValidationException(
+                message=f"response_format must be one of {sorted(ALLOWED_RESPONSE_FORMATS)}",
+                param="response_format",
+                code="invalid_response_format",
+            )
+
+    if not images:
+        raise ValidationException(
+            message="Image is required",
+            param="image",
+            code="missing_image",
+        )
+    if len(images) > 16:
+        raise ValidationException(
+            message="Too many images. Maximum is 16.",
+            param="image",
+            code="invalid_image_count",
+        )
+
+
+def resolve_response_format(response_format: Optional[str]) -> str:
+    candidate = response_format
+    if not candidate:
+        candidate = get_config("app.image_format", "url")
+    if isinstance(candidate, str):
+        candidate = candidate.lower()
+    if candidate in ALLOWED_RESPONSE_FORMATS:
+        return candidate
+    raise ValidationException(
+        message=f"response_format must be one of {sorted(ALLOWED_RESPONSE_FORMATS)}",
+        param="response_format",
+        code="invalid_response_format",
+    )
+
+
+def resolve_image_response_format(
+    response_format: Optional[str],
+    image_method: str,
+) -> str:
+    """
+    Keep legacy behavior, but for experimental imagine path:
+    if caller does not explicitly provide response_format and global default is `url`,
+    prefer `b64_json` to avoid loopback URL rendering issues in local deployments.
+    """
+    raw = response_format if not isinstance(response_format, str) else response_format.strip()
+    if not raw and image_method == IMAGE_METHOD_IMAGINE_WS_EXPERIMENTAL:
+        default_format = str(get_config("app.image_format", "url") or "url").strip().lower()
+        if default_format == "url":
+            return "b64_json"
+    return resolve_response_format(response_format)
+
+
+def response_field_name(response_format: str) -> str:
+    if response_format == "url":
+        return "url"
+    if response_format == "base64":
+        return "base64"
+    return "b64_json"
+
+
+def _image_generation_method() -> str:
+    return resolve_image_generation_method(
+        get_config("grok.image_generation_method", IMAGE_METHOD_LEGACY)
+    )
+
+
+def resolve_aspect_ratio(size: Optional[str]) -> str:
+    return resolve_imagine_aspect_ratio(size)
+
+
+def _is_valid_image_value(value: Any) -> bool:
+    return is_valid_imagine_image_value(value)
+
+
+def _dedupe_images(images: List[str]) -> List[str]:
+    return dedupe_imagine_images(images)
+
+
+async def _gather_limited(
+    task_factories: List[Callable[[], Awaitable[List[str]]]],
+    max_concurrency: int,
+) -> List[Any]:
+    sem = asyncio.Semaphore(max(1, int(max_concurrency or 1)))
+
+    async def _run(factory: Callable[[], Awaitable[List[str]]]) -> Any:
+        async with sem:
+            return await factory()
+
+    return await asyncio.gather(*[_run(factory) for factory in task_factories], return_exceptions=True)
+
+
+async def call_grok_legacy(
+    token: str,
+    prompt: str,
+    model_info,
+    file_attachments: Optional[List[str]] = None,
+    response_format: str = "b64_json",
+) -> List[str]:
+    """
+    调用 Grok 获取图片，返回图片列表
+    """
+    chat_service = GrokChatService()
+
+    try:
+        response = await chat_service.chat(
+            token=token,
+            message=prompt,
+            model=model_info.grok_model,
+            mode=model_info.model_mode,
+            think=False,
+            stream=True,
+            file_attachments=file_attachments,
+        )
+
+        processor = ImageCollectProcessor(
+            model_info.model_id,
+            token,
+            response_format=response_format,
+        )
+        return await processor.process(response)
+    except Exception as e:
+        logger.error(f"Grok image call failed: {e}")
+        return []
+
+
+async def call_grok_experimental_ws(
+    token: str,
+    prompt: str,
+    response_format: str = "b64_json",
+    n: int = 4,
+    aspect_ratio: str = "2:3",
+) -> List[str]:
+    return await call_experimental_generation_once(
+        token=token,
+        prompt=prompt,
+        response_format=response_format,
+        n=n,
+        aspect_ratio=aspect_ratio,
+    )
+
+
+async def call_grok_experimental_edit(
+    token: str,
+    prompt: str,
+    model_id: str,
+    file_uris: List[str],
+    response_format: str = "b64_json",
+) -> List[str]:
+    service = ImagineExperimentalService()
+    response = await service.chat_edit(token=token, prompt=prompt, file_uris=file_uris)
+    processor = ImageCollectProcessor(
+        model_id,
+        token,
+        response_format=response_format,
+    )
+    return await processor.process(response)
+
+
+async def _collect_experimental_generation_images(
+    token: str,
+    prompt: str,
+    n: int,
+    response_format: str,
+    aspect_ratio: str,
+    concurrency: int,
+) -> List[str]:
+    return await collect_experimental_generation_images(
+        token=token,
+        prompt=prompt,
+        n=n,
+        response_format=response_format,
+        aspect_ratio=aspect_ratio,
+        concurrency=concurrency,
+    )
+
+
+async def _experimental_stream_generation(
+    token: str,
+    prompt: str,
+    n: int,
+    response_format: str,
+    response_field: str,
+    aspect_ratio: str,
+    state: dict[str, Any],
+):
+    service = ImagineExperimentalService()
+    queue: asyncio.Queue[Optional[str]] = asyncio.Queue()
+    index_map: Dict[int, int] = {}
+    map_lock = asyncio.Lock()
+    next_output_index = 0
+
+    async def _resolve_output_index(raw_index: int) -> int:
+        nonlocal next_output_index
+        async with map_lock:
+            if raw_index not in index_map:
+                index_map[raw_index] = min(next_output_index, max(0, n - 1))
+                next_output_index += 1
+            return index_map[raw_index]
+
+    async def _progress_cb(raw_index: int, progress: float):
+        idx = await _resolve_output_index(raw_index)
+        await queue.put(
+            _sse_event(
+                "image_generation.partial_image",
+                {
+                    "type": "image_generation.partial_image",
+                    response_field: "",
+                    "index": idx,
+                    "progress": max(0, min(100, int(progress))),
+                },
+            )
+        )
+
+    async def _completed_cb(raw_index: int, raw_url: str):
+        idx = await _resolve_output_index(raw_index)
+        converted = await service.convert_url(
+            token=token,
+            url=raw_url,
+            response_format=response_format,
+        )
+        if not _is_valid_image_value(converted):
+            return
+
+        state["success"] = True
+        await queue.put(
+            _sse_event(
+                "image_generation.completed",
+                {
+                    "type": "image_generation.completed",
+                    response_field: converted,
+                    "index": idx,
+                    "usage": {
+                        "total_tokens": 50,
+                        "input_tokens": 25,
+                        "output_tokens": 25,
+                        "input_tokens_details": {"text_tokens": 5, "image_tokens": 20},
+                    },
+                },
+            )
+        )
+
+    producer_error: Optional[Exception] = None
+
+    async def _producer():
+        nonlocal producer_error
+        try:
+            await service.generate_ws(
+                token=token,
+                prompt=prompt,
+                n=n,
+                aspect_ratio=aspect_ratio,
+                progress_cb=_progress_cb,
+                completed_cb=_completed_cb,
+            )
+        except Exception as exc:
+            producer_error = exc
+        finally:
+            await queue.put(None)
+
+    producer_task = asyncio.create_task(_producer())
+    try:
+        while True:
+            chunk = await queue.get()
+            if chunk is None:
+                break
+            yield chunk
+    finally:
+        await producer_task
+
+    if not state.get("success", False):
+        if isinstance(producer_error, Exception):
+            raise producer_error
+        raise UpstreamException("Experimental imagine websocket returned no images")
+
+
+def _sse_event(event: str, data: dict) -> str:
+    return f"event: {event}\ndata: {orjson.dumps(data).decode()}\n\n"
+
+
+async def _synthetic_image_stream(
+    selected_images: List[str],
+    response_field: str,
+):
+    emitted = False
+    for idx, image in enumerate(selected_images):
+        if not isinstance(image, str) or not image or image == "error":
+            continue
+        emitted = True
+        yield _sse_event(
+            "image_generation.partial_image",
+            {
+                "type": "image_generation.partial_image",
+                response_field: "",
+                "index": idx,
+                "progress": 100,
+            },
+        )
+        yield _sse_event(
+            "image_generation.completed",
+            {
+                "type": "image_generation.completed",
+                response_field: image,
+                "index": idx,
+                "usage": {
+                    "total_tokens": 50,
+                    "input_tokens": 25,
+                    "output_tokens": 25,
+                    "input_tokens_details": {"text_tokens": 5, "image_tokens": 20},
+                },
+            },
+        )
+    if not emitted:
+        yield _sse_event(
+            "image_generation.completed",
+            {
+                "type": "image_generation.completed",
+                response_field: "error",
+                "index": 0,
+                "usage": {
+                    "total_tokens": 0,
+                    "input_tokens": 0,
+                    "output_tokens": 0,
+                    "input_tokens_details": {"text_tokens": 0, "image_tokens": 0},
+                },
+            },
+        )
+
+
+async def _record_request(model_id: str, success: bool):
+    try:
+        await request_stats.record_request(model_id, success=success)
+    except Exception:
+        pass
+
+
+async def _get_token_for_model(model_id: str):
+    """获取指定模型可用 token，失败时抛出统一异常"""
+    try:
+        token_mgr = await get_token_manager()
+        await token_mgr.reload_if_stale()
+        token = token_mgr.get_token_for_model(model_id)
+    except Exception as e:
+        logger.error(f"Failed to get token: {e}")
+        await _record_request(model_id or "image", False)
+        raise AppException(
+            message="Internal service error obtaining token",
+            error_type=ErrorType.SERVER.value,
+            code="internal_error",
+        )
+
+    if not token:
+        await _record_request(model_id or "image", False)
+        raise AppException(
+            message="No available tokens. Please try again later.",
+            error_type=ErrorType.RATE_LIMIT.value,
+            code="rate_limit_exceeded",
+            status_code=429,
+        )
+    return token_mgr, token
+
+
+def _pick_images(all_images: List[str], n: int) -> List[str]:
+    if len(all_images) >= n:
+        return random.sample(all_images, n)
+    selected = all_images.copy()
+    while len(selected) < n:
+        selected.append("error")
+    return selected
+
+
+def _build_image_response(selected_images: List[str], response_field: str) -> JSONResponse:
+    import time
+
+    return JSONResponse(
+        content={
+            "created": int(time.time()),
+            "data": [{response_field: img} for img in selected_images],
+            "usage": {
+                "total_tokens": 0 * len([img for img in selected_images if img != "error"]),
+                "input_tokens": 0,
+                "output_tokens": 0 * len([img for img in selected_images if img != "error"]),
+                "input_tokens_details": {"text_tokens": 0, "image_tokens": 0},
+            },
+        }
+    )
+
+
+@router.get("/images/method")
+async def get_image_generation_method():
+    return {"image_generation_method": _image_generation_method()}
+
+
+@router.post("/images/generations")
+async def create_image(
+    request: ImageGenerationRequest,
+    api_key: Optional[str] = Depends(verify_api_key),
+):
+    """Image Generation API."""
+    if request.stream is None:
+        request.stream = False
+
+    validate_generation_request(request)
+    model_id = request.model or "grok-imagine-1.0"
+    n = int(request.n or 1)
+    concurrency = max(1, min(3, int(request.concurrency or 1)))
+    image_method = _image_generation_method()
+    response_format = resolve_image_response_format(request.response_format, image_method)
+    request.response_format = response_format
+    response_field = response_field_name(response_format)
+    aspect_ratio = resolve_aspect_ratio(request.size)
+
+    await enforce_daily_quota(api_key, model_id, image_count=n)
+    token_mgr, token = await _get_token_for_model(model_id)
+    model_info = ModelService.get(model_id)
+
+    if request.stream:
+        if image_method == IMAGE_METHOD_IMAGINE_WS_EXPERIMENTAL:
+            stream_state: Dict[str, Any] = {"success": False}
+
+            async def _wrapped_experimental_stream():
+                try:
+                    try:
+                        async for chunk in _experimental_stream_generation(
+                            token=token,
+                            prompt=request.prompt,
+                            n=n,
+                            response_format=response_format,
+                            response_field=response_field,
+                            aspect_ratio=aspect_ratio,
+                            state=stream_state,
+                        ):
+                            yield chunk
+                    except Exception as stream_err:
+                        logger.warning(
+                            f"Experimental image generation realtime stream failed: {stream_err}. "
+                            "Fallback to synthetic stream."
+                        )
+                        try:
+                            all_images = await _collect_experimental_generation_images(
+                                token=token,
+                                prompt=request.prompt,
+                                n=n,
+                                response_format=response_format,
+                                aspect_ratio=aspect_ratio,
+                                concurrency=concurrency,
+                            )
+                            selected_images = _pick_images(_dedupe_images(all_images), n)
+                            stream_state["success"] = any(
+                                _is_valid_image_value(item) for item in selected_images
+                            )
+                            async for chunk in _synthetic_image_stream(selected_images, response_field):
+                                yield chunk
+                        except Exception as synthetic_err:
+                            logger.warning(
+                                f"Experimental synthetic stream failed: {synthetic_err}. "
+                                "Fallback to legacy stream."
+                            )
+                            chat_service = GrokChatService()
+                            response = await chat_service.chat(
+                                token=token,
+                                message=f"Image Generation: {request.prompt}",
+                                model=model_info.grok_model,
+                                mode=model_info.model_mode,
+                                think=False,
+                                stream=True,
+                            )
+                            processor = ImageStreamProcessor(
+                                model_info.model_id,
+                                token,
+                                n=n,
+                                response_format=response_format,
+                            )
+                            async for chunk in processor.process(response):
+                                yield chunk
+                            stream_state["success"] = True
+                finally:
+                    try:
+                        if stream_state.get("success"):
+                            await token_mgr.sync_usage(
+                                token,
+                                model_info.model_id,
+                                consume_on_fail=True,
+                                is_usage=True,
+                            )
+                            await _record_request(model_info.model_id, True)
+                        else:
+                            await _record_request(model_info.model_id, False)
+                    except Exception:
+                        pass
+
+            return StreamingResponse(
+                _wrapped_experimental_stream(),
+                media_type="text/event-stream",
+                headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
+            )
+
+        chat_service = GrokChatService()
+        try:
+            response = await chat_service.chat(
+                token=token,
+                message=f"Image Generation: {request.prompt}",
+                model=model_info.grok_model,
+                mode=model_info.model_mode,
+                think=False,
+                stream=True,
+            )
+        except Exception:
+            await _record_request(model_info.model_id, False)
+            raise
+
+        processor = ImageStreamProcessor(
+            model_info.model_id,
+            token,
+            n=n,
+            response_format=response_format,
+        )
+
+        async def _wrapped_stream():
+            completed = False
+            try:
+                async for chunk in processor.process(response):
+                    yield chunk
+                completed = True
+            finally:
+                try:
+                    if completed:
+                        await token_mgr.sync_usage(
+                            token,
+                            model_info.model_id,
+                            consume_on_fail=True,
+                            is_usage=True,
+                        )
+                        await _record_request(model_info.model_id, True)
+                    else:
+                        await _record_request(model_info.model_id, False)
+                except Exception:
+                    pass
+
+        return StreamingResponse(
+            _wrapped_stream(),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
+        )
+
+    all_images: List[str] = []
+    if image_method == IMAGE_METHOD_IMAGINE_WS_EXPERIMENTAL:
+        try:
+            all_images = await _collect_experimental_generation_images(
+                token=token,
+                prompt=request.prompt,
+                n=n,
+                response_format=response_format,
+                aspect_ratio=aspect_ratio,
+                concurrency=concurrency,
+            )
+        except Exception as e:
+            logger.warning(f"Experimental image generation failed, fallback to legacy: {e}")
+
+    if not all_images:
+        calls_needed = (n + 1) // 2
+        task_factories: List[Callable[[], Awaitable[List[str]]]] = [
+            lambda: call_grok_legacy(
+                token,
+                f"Image Generation: {request.prompt}",
+                model_info,
+                response_format=response_format,
+            )
+            for _ in range(calls_needed)
+        ]
+        results = await _gather_limited(
+            task_factories,
+            max_concurrency=min(calls_needed, concurrency),
+        )
+
+        all_images = []
+        for result in results:
+            if isinstance(result, Exception):
+                logger.error(f"Concurrent call failed: {result}")
+            elif isinstance(result, list):
+                all_images.extend(result)
+
+    selected_images = _pick_images(_dedupe_images(all_images), n)
+    success = any(_is_valid_image_value(img) for img in selected_images)
+    try:
+        if success:
+            await token_mgr.sync_usage(
+                token,
+                model_info.model_id,
+                consume_on_fail=True,
+                is_usage=True,
+            )
+        await _record_request(model_info.model_id, bool(success))
+    except Exception:
+        pass
+
+    return _build_image_response(selected_images, response_field)
+
+
+@router.post("/images/edits")
+async def edit_image(
+    prompt: str = Form(...),
+    image: Optional[List[UploadFile]] = File(None),
+    image_alias: Optional[List[UploadFile]] = File(None, alias="image[]"),
+    model: Optional[str] = Form("grok-imagine-1.0-edit"),
+    n: int = Form(1),
+    size: str = Form("1024x1024"),
+    quality: str = Form("standard"),
+    response_format: Optional[str] = Form(None),
+    style: Optional[str] = Form(None),
+    stream: Optional[bool] = Form(False),
+    api_key: Optional[str] = Depends(verify_api_key),
+):
+    """
+    Image Edits API
+
+    同官方 API 格式，仅支持 multipart/form-data 文件上传
+    """
+    try:
+        edit_request = ImageEditRequest(
+            prompt=prompt,
+            model=model,
+            n=n,
+            size=size,
+            quality=quality,
+            response_format=response_format,
+            style=style,
+            stream=stream,
+        )
+    except ValidationError as exc:
+        errors = exc.errors()
+        if errors:
+            first = errors[0]
+            loc = first.get("loc", [])
+            msg = first.get("msg", "Invalid request")
+            code = first.get("type", "invalid_value")
+            param_parts = [str(x) for x in loc if not (isinstance(x, int) or str(x).isdigit())]
+            param = ".".join(param_parts) if param_parts else None
+            raise ValidationException(message=msg, param=param, code=code)
+        raise ValidationException(message="Invalid request", code="invalid_value")
+
+    if edit_request.stream is None:
+        edit_request.stream = False
+    if edit_request.n is None:
+        edit_request.n = 1
+
+    image_method = _image_generation_method()
+    response_format = resolve_image_response_format(edit_request.response_format, image_method)
+    edit_request.response_format = response_format
+    response_field = response_field_name(response_format)
+    images = (image or []) + (image_alias or [])
+    validate_edit_request(edit_request, images)
+
+    model_id = edit_request.model or "grok-imagine-1.0-edit"
+    n = int(edit_request.n or 1)
+
+    await enforce_daily_quota(api_key, model_id, image_count=n)
+
+    max_image_bytes = 50 * 1024 * 1024
+    allowed_types = {"image/png", "image/jpeg", "image/webp", "image/jpg"}
+    image_payloads: List[str] = []
+
+    for item in images:
+        content = await item.read()
+        await item.close()
+        if not content:
+            raise ValidationException(
+                message="File content is empty",
+                param="image",
+                code="empty_file",
+            )
+        if len(content) > max_image_bytes:
+            raise ValidationException(
+                message="Image file too large. Maximum is 50MB.",
+                param="image",
+                code="file_too_large",
+            )
+
+        mime = (item.content_type or "").lower()
+        if mime == "image/jpg":
+            mime = "image/jpeg"
+        ext = Path(item.filename or "").suffix.lower()
+        if mime not in allowed_types:
+            if ext in (".jpg", ".jpeg"):
+                mime = "image/jpeg"
+            elif ext == ".png":
+                mime = "image/png"
+            elif ext == ".webp":
+                mime = "image/webp"
+            else:
+                raise ValidationException(
+                    message="Unsupported image type. Supported: png, jpg, webp.",
+                    param="image",
+                    code="invalid_image_type",
+                )
+
+        image_payloads.append(f"data:{mime};base64,{base64.b64encode(content).decode()}")
+
+    token_mgr, token = await _get_token_for_model(model_id)
+    model_info = ModelService.get(model_id)
+
+    file_ids: List[str] = []
+    file_uris: List[str] = []
+    upload_service = UploadService()
+    try:
+        for payload in image_payloads:
+            file_id, file_uri = await upload_service.upload(payload, token)
+            if file_id:
+                file_ids.append(file_id)
+            if file_uri:
+                file_uris.append(file_uri)
+    finally:
+        await upload_service.close()
+
+    if edit_request.stream:
+        if image_method == IMAGE_METHOD_IMAGINE_WS_EXPERIMENTAL:
+            try:
+                service = ImagineExperimentalService()
+                response = await service.chat_edit(
+                    token=token,
+                    prompt=edit_request.prompt,
+                    file_uris=file_uris,
+                )
+                processor = ImageStreamProcessor(
+                    model_info.model_id,
+                    token,
+                    n=n,
+                    response_format=response_format,
+                )
+
+                async def _wrapped_experimental_stream():
+                    completed = False
+                    try:
+                        async for chunk in processor.process(response):
+                            yield chunk
+                        completed = True
+                    finally:
+                        try:
+                            if completed:
+                                await token_mgr.sync_usage(
+                                    token,
+                                    model_info.model_id,
+                                    consume_on_fail=True,
+                                    is_usage=True,
+                                )
+                                await _record_request(model_info.model_id, True)
+                            else:
+                                await _record_request(model_info.model_id, False)
+                        except Exception:
+                            pass
+
+                return StreamingResponse(
+                    _wrapped_experimental_stream(),
+                    media_type="text/event-stream",
+                    headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
+                )
+            except Exception as e:
+                logger.warning(f"Experimental image edit stream failed, fallback to legacy: {e}")
+
+        chat_service = GrokChatService()
+        try:
+            response = await chat_service.chat(
+                token=token,
+                message=f"Image Edit: {edit_request.prompt}",
+                model=model_info.grok_model,
+                mode=model_info.model_mode,
+                think=False,
+                stream=True,
+                file_attachments=file_ids,
+            )
+        except Exception:
+            await _record_request(model_info.model_id, False)
+            raise
+
+        processor = ImageStreamProcessor(
+            model_info.model_id,
+            token,
+            n=n,
+            response_format=response_format,
+        )
+
+        async def _wrapped_stream():
+            completed = False
+            try:
+                async for chunk in processor.process(response):
+                    yield chunk
+                completed = True
+            finally:
+                try:
+                    if completed:
+                        await token_mgr.sync_usage(
+                            token,
+                            model_info.model_id,
+                            consume_on_fail=True,
+                            is_usage=True,
+                        )
+                        await _record_request(model_info.model_id, True)
+                    else:
+                        await _record_request(model_info.model_id, False)
+                except Exception:
+                    pass
+
+        return StreamingResponse(
+            _wrapped_stream(),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
+        )
+
+    all_images: List[str] = []
+    if image_method == IMAGE_METHOD_IMAGINE_WS_EXPERIMENTAL:
+        try:
+            calls_needed = (n + 1) // 2
+            if calls_needed == 1:
+                all_images = await call_grok_experimental_edit(
+                    token=token,
+                    prompt=edit_request.prompt,
+                    model_id=model_info.model_id,
+                    file_uris=file_uris,
+                    response_format=response_format,
+                )
+            else:
+                tasks = [
+                    call_grok_experimental_edit(
+                        token=token,
+                        prompt=edit_request.prompt,
+                        model_id=model_info.model_id,
+                        file_uris=file_uris,
+                        response_format=response_format,
+                    )
+                    for _ in range(calls_needed)
+                ]
+                results = await asyncio.gather(*tasks, return_exceptions=True)
+                for result in results:
+                    if isinstance(result, Exception):
+                        logger.warning(f"Experimental image edit call failed: {result}")
+                    elif isinstance(result, list):
+                        all_images.extend(result)
+            if not all_images:
+                raise UpstreamException("Experimental image edit returned no images")
+        except Exception as e:
+            logger.warning(f"Experimental image edit failed, fallback to legacy: {e}")
+
+    if not all_images:
+        calls_needed = (n + 1) // 2
+        if calls_needed == 1:
+            all_images = await call_grok_legacy(
+                token,
+                f"Image Edit: {edit_request.prompt}",
+                model_info,
+                file_attachments=file_ids,
+                response_format=response_format,
+            )
+        else:
+            tasks = [
+                call_grok_legacy(
+                    token,
+                    f"Image Edit: {edit_request.prompt}",
+                    model_info,
+                    file_attachments=file_ids,
+                    response_format=response_format,
+                )
+                for _ in range(calls_needed)
+            ]
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+            all_images = []
+            for result in results:
+                if isinstance(result, Exception):
+                    logger.error(f"Concurrent call failed: {result}")
+                elif isinstance(result, list):
+                    all_images.extend(result)
+
+    selected_images = _pick_images(all_images, n)
+    success = any(isinstance(img, str) and img and img != "error" for img in selected_images)
+    try:
+        if success:
+            await token_mgr.sync_usage(
+                token,
+                model_info.model_id,
+                consume_on_fail=True,
+                is_usage=True,
+            )
+        await _record_request(model_info.model_id, bool(success))
+    except Exception:
+        pass
+
+    return _build_image_response(selected_images, response_field)
+
+
+__all__ = ["router"]

app/api/v1/models.py

@@ -0,0 +1,51 @@
+"""
+Models API 路由
+"""
+
+import time
+
+from fastapi import APIRouter, HTTPException
+
+from app.services.grok.model import ModelService
+
+
+router = APIRouter(tags=["Models"])
+
+
+@router.get("/models")
+async def list_models():
+    """OpenAI 兼容 models 列表接口"""
+    ts = int(time.time())
+    data = [
+        {
+            "id": m.model_id,
+            "object": "model",
+            "created": ts,
+            "owned_by": "grok2api",
+            "display_name": m.display_name,
+            "description": m.description,
+        }
+        for m in ModelService.list()
+    ]
+    return {"object": "list", "data": data}
+
+
+@router.get("/models/{model_id}")
+async def get_model(model_id: str):
+    """OpenAI compatible: single model detail."""
+    m = ModelService.get(model_id)
+    if not m:
+        raise HTTPException(status_code=404, detail=f"Model '{model_id}' not found")
+
+    ts = int(time.time())
+    return {
+        "id": m.model_id,
+        "object": "model",
+        "created": ts,
+        "owned_by": "grok2api",
+        "display_name": m.display_name,
+        "description": m.description,
+    }
+
+
+__all__ = ["router"]

app/api/v1/uploads.py

@@ -0,0 +1,64 @@
+"""
+Uploads API (used by the web chat UI)
+"""
+
+import uuid
+from pathlib import Path
+
+import aiofiles
+from fastapi import APIRouter, UploadFile, File, HTTPException
+
+from app.services.grok.assets import DownloadService
+
+
+router = APIRouter(tags=["Uploads"])
+
+BASE_DIR = Path(__file__).parent.parent.parent.parent / "data" / "tmp"
+IMAGE_DIR = BASE_DIR / "image"
+
+
+def _ext_from_mime(mime: str) -> str:
+    m = (mime or "").lower()
+    if m == "image/png":
+        return "png"
+    if m == "image/webp":
+        return "webp"
+    if m == "image/gif":
+        return "gif"
+    if m in ("image/jpeg", "image/jpg"):
+        return "jpg"
+    return "jpg"
+
+
+@router.post("/uploads/image")
+async def upload_image(file: UploadFile = File(...)):
+    content_type = (file.content_type or "").lower()
+    if not content_type.startswith("image/"):
+        raise HTTPException(status_code=400, detail=f"Unsupported file type: {file.content_type}")
+
+    IMAGE_DIR.mkdir(parents=True, exist_ok=True)
+    name = f"upload-{uuid.uuid4().hex}.{_ext_from_mime(content_type)}"
+    path = IMAGE_DIR / name
+
+    size = 0
+    async with aiofiles.open(path, "wb") as f:
+        while True:
+            chunk = await file.read(1024 * 1024)
+            if not chunk:
+                break
+            size += len(chunk)
+            await f.write(chunk)
+
+    # Best-effort: reuse existing cache cleanup policy (size-based).
+    try:
+        dl = DownloadService()
+        await dl.check_limit()
+        await dl.close()
+    except Exception:
+        pass
+
+    return {"url": f"/v1/files/image/{name}", "name": name, "size_bytes": size}
+
+
+__all__ = ["router"]
+

app/api/v1/video.py

@@ -0,0 +1,3 @@
+"""
+TODO：Video Generation API 路由
+"""

app/core/auth.py

@@ -0,0 +1,159 @@
+"""
+API 认证模块
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Optional, Set
+
+from fastapi import HTTPException, Security, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from app.core.config import get_config
+
+# 定义 Bearer Scheme
+security = HTTPBearer(
+    auto_error=False,
+    scheme_name="API Key",
+    description="Enter your API Key in the format: Bearer <key>",
+)
+
+LEGACY_API_KEYS_FILE = Path(__file__).parent.parent.parent / "data" / "api_keys.json"
+_legacy_api_keys_cache: Set[str] | None = None
+_legacy_api_keys_mtime: float | None = None
+_legacy_api_keys_lock = asyncio.Lock()
+
+
+async def _load_legacy_api_keys() -> Set[str]:
+    """
+    Backward-compatible API keys loader.
+
+    Older versions stored multiple API keys in `data/api_keys.json` with a shape like:
+    [{"key": "...", "is_active": true, ...}, ...]
+    """
+    global _legacy_api_keys_cache, _legacy_api_keys_mtime
+
+    if not LEGACY_API_KEYS_FILE.exists():
+        _legacy_api_keys_cache = set()
+        _legacy_api_keys_mtime = None
+        return set()
+
+    try:
+        stat = LEGACY_API_KEYS_FILE.stat()
+        mtime = stat.st_mtime
+    except Exception:
+        mtime = None
+
+    if _legacy_api_keys_cache is not None and mtime is not None and _legacy_api_keys_mtime == mtime:
+        return _legacy_api_keys_cache
+
+    async with _legacy_api_keys_lock:
+        # Re-check in lock
+        if not LEGACY_API_KEYS_FILE.exists():
+            _legacy_api_keys_cache = set()
+            _legacy_api_keys_mtime = None
+            return set()
+
+        try:
+            stat = LEGACY_API_KEYS_FILE.stat()
+            mtime = stat.st_mtime
+        except Exception:
+            mtime = None
+
+        if _legacy_api_keys_cache is not None and mtime is not None and _legacy_api_keys_mtime == mtime:
+            return _legacy_api_keys_cache
+
+        try:
+            raw = await asyncio.to_thread(LEGACY_API_KEYS_FILE.read_text, "utf-8")
+            data = json.loads(raw) if raw.strip() else []
+        except Exception:
+            data = []
+
+        keys: Set[str] = set()
+        if isinstance(data, list):
+            for item in data:
+                if not isinstance(item, dict):
+                    continue
+                key = item.get("key")
+                is_active = item.get("is_active", True)
+                if isinstance(key, str) and key.strip() and is_active is not False:
+                    keys.add(key.strip())
+
+        _legacy_api_keys_cache = keys
+        _legacy_api_keys_mtime = mtime
+        return keys
+
+
+async def verify_api_key(
+    auth: Optional[HTTPAuthorizationCredentials] = Security(security),
+) -> Optional[str]:
+    """
+    验证 Bearer Token
+
+    - 若 `app.api_key` 未配置且不存在 legacy keys，则跳过验证。
+    - 若配置了 `app.api_key` 或存在 legacy keys，则必须提供 Authorization: Bearer <key>。
+    """
+    api_key = str(get_config("app.api_key", "") or "").strip()
+    legacy_keys = await _load_legacy_api_keys()
+
+    # 如果未配置 API Key 且没有 legacy keys，直接放行
+    if not api_key and not legacy_keys:
+        return None
+
+    if not auth:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing authentication token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    token = auth.credentials
+    if (api_key and token == api_key) or token in legacy_keys:
+        return token
+
+    raise HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Invalid authentication token",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+
+
+async def verify_app_key(
+    auth: Optional[HTTPAuthorizationCredentials] = Security(security),
+) -> Optional[str]:
+    """
+    验证后台登录密钥（app_key）。
+
+    如果未配置 app_key，则跳过验证。
+    """
+    app_key = str(get_config("app.app_key", "") or "").strip()
+
+    if not app_key:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="App key is not configured",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    if not auth:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing authentication token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    if auth.credentials != app_key:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid authentication token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    return auth.credentials
+
+
+__all__ = ["verify_api_key", "verify_app_key"]
+

app/core/config.py

@@ -0,0 +1,329 @@
+"""
+配置管理
+
+- config.toml: 运行时配置
+- config.defaults.toml: 默认配置基线
+"""
+
+from copy import deepcopy
+from pathlib import Path
+from typing import Any, Dict
+import tomllib
+
+from app.core.logger import logger
+
+DEFAULT_CONFIG_FILE = Path(__file__).parent.parent.parent / "config.defaults.toml"
+LEGACY_CONFIG_FILE = Path(__file__).parent.parent.parent / "data" / "setting.toml"
+
+
+def _as_str(v: Any) -> str:
+    if isinstance(v, str):
+        return v
+    return ""
+
+
+def _as_int(v: Any) -> int | None:
+    try:
+        if v is None:
+            return None
+        return int(v)
+    except Exception:
+        return None
+
+
+def _as_bool(v: Any) -> bool | None:
+    if isinstance(v, bool):
+        return v
+    return None
+
+
+def _split_csv_tags(v: Any) -> list[str] | None:
+    if not isinstance(v, str):
+        return None
+    parts = [x.strip() for x in v.split(",")]
+    tags = [x for x in parts if x]
+    return tags or None
+
+
+def _legacy_setting_to_config(legacy: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Migrate legacy `data/setting.toml` format (grok/global) to the new config schema.
+
+    Best-effort mapping only for stable fields. It does not delete or rename the legacy file.
+    """
+
+    grok = legacy.get("grok") if isinstance(legacy.get("grok"), dict) else {}
+    global_ = legacy.get("global") if isinstance(legacy.get("global"), dict) else {}
+
+    out: Dict[str, Any] = {}
+
+    # === app ===
+    app_url = _as_str(global_.get("base_url")).strip()
+    admin_username = _as_str(global_.get("admin_username")).strip()
+    app_key = _as_str(global_.get("admin_password")).strip()
+    api_key = _as_str(grok.get("api_key")).strip()
+    image_format = _as_str(global_.get("image_mode")).strip()
+
+    if app_url or admin_username or app_key or api_key or image_format:
+        out["app"] = {}
+        if app_url:
+            out["app"]["app_url"] = app_url
+        if admin_username:
+            out["app"]["admin_username"] = admin_username
+        if app_key:
+            out["app"]["app_key"] = app_key
+        if api_key:
+            out["app"]["api_key"] = api_key
+        if image_format:
+            out["app"]["image_format"] = image_format
+
+    # === grok ===
+    base_proxy_url = _as_str(grok.get("proxy_url")).strip()
+    asset_proxy_url = _as_str(grok.get("cache_proxy_url")).strip()
+    cf_clearance = _as_str(grok.get("cf_clearance")).strip()
+
+    temporary = _as_bool(grok.get("temporary"))
+    thinking = _as_bool(grok.get("show_thinking"))
+    dynamic_statsig = _as_bool(grok.get("dynamic_statsig"))
+    filter_tags = _split_csv_tags(grok.get("filtered_tags"))
+
+    retry_status_codes = grok.get("retry_status_codes")
+
+    timeout = None
+    total_timeout = _as_int(grok.get("stream_total_timeout"))
+    if total_timeout and total_timeout > 0:
+        timeout = total_timeout
+    else:
+        chunk_timeout = _as_int(grok.get("stream_chunk_timeout"))
+        if chunk_timeout and chunk_timeout > 0:
+            timeout = chunk_timeout
+
+    if (
+        base_proxy_url
+        or asset_proxy_url
+        or cf_clearance
+        or temporary is not None
+        or thinking is not None
+        or dynamic_statsig is not None
+        or filter_tags is not None
+        or timeout is not None
+        or isinstance(retry_status_codes, list)
+    ):
+        out["grok"] = {}
+        if base_proxy_url:
+            out["grok"]["base_proxy_url"] = base_proxy_url
+        if asset_proxy_url:
+            out["grok"]["asset_proxy_url"] = asset_proxy_url
+        if cf_clearance:
+            out["grok"]["cf_clearance"] = cf_clearance
+        if temporary is not None:
+            out["grok"]["temporary"] = temporary
+        if thinking is not None:
+            out["grok"]["thinking"] = thinking
+        if dynamic_statsig is not None:
+            out["grok"]["dynamic_statsig"] = dynamic_statsig
+        if filter_tags is not None:
+            out["grok"]["filter_tags"] = filter_tags
+        if timeout is not None:
+            out["grok"]["timeout"] = timeout
+        if isinstance(retry_status_codes, list) and retry_status_codes:
+            out["grok"]["retry_status_codes"] = retry_status_codes
+
+    # === cache ===
+    # Legacy had separate limits; new uses a single total limit_mb.
+    image_mb = _as_int(global_.get("image_cache_max_size_mb")) or 0
+    video_mb = _as_int(global_.get("video_cache_max_size_mb")) or 0
+    if image_mb > 0 or video_mb > 0:
+        out["cache"] = {"limit_mb": max(1, image_mb + video_mb)}
+
+    return out
+
+
+def _apply_legacy_config(
+    config_data: Dict[str, Any],
+    legacy_cfg: Dict[str, Any],
+    defaults: Dict[str, Any],
+) -> bool:
+    """
+    Merge legacy settings into current config:
+    - fill missing keys
+    - override keys that are still default values
+    """
+
+    changed = False
+    for section, items in legacy_cfg.items():
+        if not isinstance(items, dict):
+            continue
+
+        current_section = config_data.get(section)
+        if not isinstance(current_section, dict):
+            current_section = {}
+            config_data[section] = current_section
+            changed = True
+
+        default_section = defaults.get(section) if isinstance(defaults.get(section), dict) else {}
+
+        for key, val in items.items():
+            if val is None:
+                continue
+            if key not in current_section:
+                current_section[key] = val
+                changed = True
+                continue
+
+            default_val = default_section.get(key) if isinstance(default_section, dict) else None
+            current_val = current_section.get(key)
+
+            # NOTE: The admin panel password default used to be `grok2api` in older versions.
+            # Treat it as "still default" so legacy `data/setting.toml` can override it during migration.
+            is_effective_default = current_val == default_val
+            if section == "app" and key == "app_key" and current_val == "grok2api":
+                is_effective_default = True
+
+            if is_effective_default and val != default_val:
+                current_section[key] = val
+                changed = True
+
+    return changed
+
+
+def _deep_merge(base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any]:
+    """深度合并字典：override 覆盖 base。"""
+    if not isinstance(base, dict):
+        return deepcopy(override) if isinstance(override, dict) else deepcopy(base)
+
+    result = deepcopy(base)
+    if not isinstance(override, dict):
+        return result
+
+    for key, val in override.items():
+        if isinstance(val, dict) and isinstance(result.get(key), dict):
+            result[key] = _deep_merge(result[key], val)
+        else:
+            result[key] = val
+    return result
+
+
+def _load_defaults() -> Dict[str, Any]:
+    """加载默认配置文件"""
+    if not DEFAULT_CONFIG_FILE.exists():
+        return {}
+    try:
+        with DEFAULT_CONFIG_FILE.open("rb") as f:
+            return tomllib.load(f)
+    except Exception as e:
+        logger.warning(f"Failed to load defaults from {DEFAULT_CONFIG_FILE}: {e}")
+        return {}
+
+
+class Config:
+    """配置管理器"""
+
+    _instance = None
+    _config = {}
+
+    def __init__(self):
+        self._config = {}
+        self._defaults = {}
+        self._defaults_loaded = False
+
+    def _ensure_defaults(self):
+        if self._defaults_loaded:
+            return
+        self._defaults = _load_defaults()
+        self._defaults_loaded = True
+
+    async def load(self):
+        """显式加载配置"""
+        try:
+            from app.core.storage import get_storage, LocalStorage
+
+            self._ensure_defaults()
+
+            storage = get_storage()
+            config_data = await storage.load_config()
+            from_remote = True
+
+            # 从本地 data/config.toml 初始化后端
+            if config_data is None:
+                local_storage = LocalStorage()
+                from_remote = False
+                try:
+                    config_data = await local_storage.load_config()
+                except Exception as e:
+                    logger.info(f"Failed to auto-init config from local: {e}")
+                    config_data = {}
+
+            config_data = config_data or {}
+            before_legacy = deepcopy(config_data)
+
+            # Legacy migration: data/setting.toml -> config schema
+            if LEGACY_CONFIG_FILE.exists():
+                try:
+                    with LEGACY_CONFIG_FILE.open("rb") as f:
+                        legacy_raw = tomllib.load(f) or {}
+                    legacy_cfg = _legacy_setting_to_config(legacy_raw)
+                    if legacy_cfg and _apply_legacy_config(config_data, legacy_cfg, self._defaults):
+                        logger.info(
+                            "Detected legacy data/setting.toml, migrated into config (missing/default keys)."
+                        )
+                except Exception as e:
+                    logger.warning(f"Failed to migrate legacy config from {LEGACY_CONFIG_FILE}: {e}")
+
+            merged = _deep_merge(self._defaults, config_data)
+
+            # 自动回填缺失配置到存储
+            should_persist = (not from_remote) or (merged != before_legacy)
+            if should_persist:
+                async with storage.acquire_lock("config_save", timeout=10):
+                    await storage.save_config(merged)
+                if not from_remote:
+                    logger.info(
+                        f"Initialized remote storage ({storage.__class__.__name__}) with config baseline."
+                    )
+
+            self._config = merged
+        except Exception as e:
+            logger.error(f"Error loading config: {e}")
+            self._config = {}
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        获取配置值
+
+        Args:
+            key: 配置键，格式 "section.key"
+            default: 默认值
+        """
+        if "." in key:
+            try:
+                section, attr = key.split(".", 1)
+                return self._config.get(section, {}).get(attr, default)
+            except (ValueError, AttributeError):
+                return default
+
+        return self._config.get(key, default)
+
+    async def update(self, new_config: dict):
+        """更新配置"""
+        from app.core.storage import get_storage
+
+        storage = get_storage()
+        async with storage.acquire_lock("config_save", timeout=10):
+            self._ensure_defaults()
+            base = _deep_merge(self._defaults, self._config or {})
+            merged = _deep_merge(base, new_config or {})
+            await storage.save_config(merged)
+            self._config = merged
+
+
+# 全局配置实例
+config = Config()
+
+
+def get_config(key: str, default: Any = None) -> Any:
+    """获取配置"""
+    return config.get(key, default)
+
+
+__all__ = ["Config", "config", "get_config"]

app/core/exceptions.py

@@ -0,0 +1,221 @@
+"""
+全局异常处理 - OpenAI 兼容错误格式
+"""
+
+from typing import Any, Optional
+from enum import Enum
+from fastapi import Request, HTTPException
+from fastapi.responses import JSONResponse
+from fastapi.exceptions import RequestValidationError
+
+from app.core.logger import logger
+
+
+# ============= 错误类型 =============
+
+class ErrorType(str, Enum):
+    """OpenAI 错误类型"""
+    INVALID_REQUEST = "invalid_request_error"
+    AUTHENTICATION = "authentication_error"
+    PERMISSION = "permission_error"
+    NOT_FOUND = "not_found_error"
+    RATE_LIMIT = "rate_limit_error"
+    SERVER = "server_error"
+    SERVICE_UNAVAILABLE = "service_unavailable_error"
+
+
+# ============= 辅助函数 =============
+
+def error_response(
+    message: str,
+    error_type: str = ErrorType.INVALID_REQUEST.value,
+    param: str = None,
+    code: str = None
+) -> dict:
+    """构建 OpenAI 错误响应"""
+    return {
+        "error": {
+            "message": message,
+            "type": error_type,
+            "param": param,
+            "code": code
+        }
+    }
+
+
+# ============= 异常类 =============
+
+class AppException(Exception):
+    """应用基础异常"""
+    
+    def __init__(
+        self,
+        message: str,
+        error_type: str = ErrorType.SERVER.value,
+        code: str = None,
+        param: str = None,
+        status_code: int = 500
+    ):
+        self.message = message
+        self.error_type = error_type
+        self.code = code
+        self.param = param
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class ValidationException(AppException):
+    """验证错误"""
+    
+    def __init__(self, message: str, param: str = None, code: str = None):
+        super().__init__(
+            message=message,
+            error_type=ErrorType.INVALID_REQUEST.value,
+            code=code or "invalid_value",
+            param=param,
+            status_code=400
+        )
+
+
+class AuthenticationException(AppException):
+    """认证错误"""
+    
+    def __init__(self, message: str = "Invalid API key"):
+        super().__init__(
+            message=message,
+            error_type=ErrorType.AUTHENTICATION.value,
+            code="invalid_api_key",
+            status_code=401
+        )
+
+
+class UpstreamException(AppException):
+    """上游服务错误"""
+    
+    def __init__(self, message: str, details: Any = None):
+        super().__init__(
+            message=message,
+            error_type=ErrorType.SERVER.value,
+            code="upstream_error",
+            status_code=502
+        )
+        self.details = details
+
+
+# ============= 异常处理器 =============
+
+async def app_exception_handler(request: Request, exc: AppException) -> JSONResponse:
+    """处理应用异常"""
+    logger.warning(f"AppException: {exc.error_type} - {exc.message}")
+    
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=error_response(
+            message=exc.message,
+            error_type=exc.error_type,
+            param=exc.param,
+            code=exc.code
+        )
+    )
+
+
+async def http_exception_handler(request: Request, exc: HTTPException) -> JSONResponse:
+    """处理 HTTP 异常"""
+    type_map = {
+        400: ErrorType.INVALID_REQUEST.value,
+        401: ErrorType.AUTHENTICATION.value,
+        403: ErrorType.PERMISSION.value,
+        404: ErrorType.NOT_FOUND.value,
+        429: ErrorType.RATE_LIMIT.value,
+    }
+    error_type = type_map.get(exc.status_code, ErrorType.SERVER.value)
+    
+    # 默认 code 映射
+    code_map = {
+        401: "invalid_api_key",
+        403: "insufficient_quota",
+        404: "model_not_found",
+        429: "rate_limit_exceeded",
+    }
+    code = code_map.get(exc.status_code, None)
+    
+    logger.warning(f"HTTPException: {exc.status_code} - {exc.detail}")
+    
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=error_response(
+            message=str(exc.detail),
+            error_type=error_type,
+            code=code
+        )
+    )
+
+
+async def validation_exception_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
+    """处理验证错误"""
+    errors = exc.errors()
+    
+    if errors:
+        first = errors[0]
+        loc = first.get("loc", [])
+        msg = first.get("msg", "Invalid request")
+        code = first.get("type", "invalid_value")
+        
+        # JSON 解析错误
+        if code == "json_invalid" or "JSON" in msg:
+            message = "Invalid JSON in request body. Please check for trailing commas or syntax errors."
+            param = "body"
+        else:
+            param_parts = [str(x) for x in loc if not (isinstance(x, int) or str(x).isdigit())]
+            param = ".".join(param_parts) if param_parts else None
+            message = msg
+    else:
+        param, message, code = None, "Invalid request", "invalid_value"
+    
+    logger.warning(f"ValidationError: {param} - {message}")
+    
+    return JSONResponse(
+        status_code=400,
+        content=error_response(
+            message=message,
+            error_type=ErrorType.INVALID_REQUEST.value,
+            param=param,
+            code=code
+        )
+    )
+
+
+async def generic_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    """处理未捕获异常"""
+    logger.exception(f"Unhandled: {type(exc).__name__}: {str(exc)}")
+    
+    return JSONResponse(
+        status_code=500,
+        content=error_response(
+            message="Internal server error",
+            error_type=ErrorType.SERVER.value,
+            code="internal_error"
+        )
+    )
+
+
+# ============= 注册 =============
+
+def register_exception_handlers(app):
+    """注册异常处理器"""
+    app.add_exception_handler(AppException, app_exception_handler)
+    app.add_exception_handler(HTTPException, http_exception_handler)
+    app.add_exception_handler(RequestValidationError, validation_exception_handler)
+    app.add_exception_handler(Exception, generic_exception_handler)
+    app.add_exception_handler(Exception, generic_exception_handler)
+
+
+__all__ = [
+    "ErrorType",
+    "AppException",
+    "ValidationException",
+    "AuthenticationException",
+    "UpstreamException",
+    "error_response",
+    "register_exception_handlers",
+]

app/core/legacy_migration.py

@@ -0,0 +1,285 @@
+"""
+Legacy data migrations for local deployments (python/docker).
+
+Goal: when upgrading the project, old on-disk data should still be readable and not lost.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+import time
+from pathlib import Path
+from typing import Any, Dict
+
+from app.core.logger import logger
+
+
+def migrate_legacy_cache_dirs(data_dir: Path | None = None) -> Dict[str, Any]:
+    """
+    Migrate old cache directory layout:
+
+    - legacy: data/temp/{image,video}
+    - current: data/tmp/{image,video}
+
+    This keeps existing cached files (not yet cleaned) available after upgrades.
+    """
+
+    data_root = data_dir or (Path(__file__).parent.parent.parent / "data")
+    legacy_root = data_root / "temp"
+    current_root = data_root / "tmp"
+
+    if not legacy_root.exists() or not legacy_root.is_dir():
+        return {"migrated": False, "reason": "no_legacy_dir"}
+
+    lock_dir = data_root / ".locks"
+    lock_dir.mkdir(parents=True, exist_ok=True)
+
+    done_marker = lock_dir / "legacy_cache_dirs_v1.done"
+    if done_marker.exists():
+        return {"migrated": False, "reason": "already_done"}
+
+    lock_file = lock_dir / "legacy_cache_dirs_v1.lock"
+
+    # Best-effort cross-process lock (works on Windows/Linux).
+    fd: int | None = None
+    try:
+        try:
+            fd = os.open(str(lock_file), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError:
+            # Another worker/process is migrating. Wait briefly for completion.
+            deadline = time.monotonic() + 30.0
+            while time.monotonic() < deadline:
+                if done_marker.exists():
+                    return {"migrated": False, "reason": "waited_for_other_process"}
+                time.sleep(0.2)
+            return {"migrated": False, "reason": "lock_timeout"}
+
+        current_root.mkdir(parents=True, exist_ok=True)
+
+        moved = 0
+        skipped = 0
+        errors = 0
+
+        for sub in ("image", "video"):
+            src_dir = legacy_root / sub
+            if not src_dir.exists() or not src_dir.is_dir():
+                continue
+
+            dst_dir = current_root / sub
+            dst_dir.mkdir(parents=True, exist_ok=True)
+
+            for item in src_dir.iterdir():
+                if not item.is_file():
+                    continue
+                target = dst_dir / item.name
+                if target.exists():
+                    skipped += 1
+                    continue
+                try:
+                    shutil.move(str(item), str(target))
+                    moved += 1
+                except Exception:
+                    errors += 1
+
+        # Cleanup empty legacy dirs (best-effort).
+        for sub in ("image", "video"):
+            p = legacy_root / sub
+            try:
+                if p.exists() and p.is_dir() and not any(p.iterdir()):
+                    p.rmdir()
+            except Exception:
+                pass
+        try:
+            if legacy_root.exists() and legacy_root.is_dir() and not any(legacy_root.iterdir()):
+                legacy_root.rmdir()
+        except Exception:
+            pass
+
+        if errors == 0:
+            done_marker.write_text(str(int(time.time())), encoding="utf-8")
+        if moved or skipped or errors:
+            logger.info(
+                f"Legacy cache migration complete: moved={moved}, skipped={skipped}, errors={errors}"
+            )
+        return {"migrated": True, "moved": moved, "skipped": skipped, "errors": errors}
+    finally:
+        try:
+            if fd is not None:
+                os.close(fd)
+        except Exception:
+            pass
+        try:
+            if lock_file.exists():
+                lock_file.unlink()
+        except Exception:
+            pass
+
+
+__all__ = ["migrate_legacy_cache_dirs", "migrate_legacy_account_settings"]
+
+
+async def migrate_legacy_account_settings(
+    concurrency: int = 10,
+    data_dir: Path | None = None,
+) -> Dict[str, Any]:
+    """
+    After legacy data migration, run a one-time TOS + BirthDate + NSFW pass for existing accounts.
+
+    This is best-effort and guarded by a cross-process lock + done marker.
+    """
+
+    data_root = data_dir or (Path(__file__).parent.parent.parent / "data")
+    lock_dir = data_root / ".locks"
+    lock_dir.mkdir(parents=True, exist_ok=True)
+
+    done_marker = lock_dir / "legacy_accounts_tos_birth_nsfw_v2.done"
+    if done_marker.exists():
+        return {"migrated": False, "reason": "already_done"}
+
+    lock_file = lock_dir / "legacy_accounts_tos_birth_nsfw_v2.lock"
+    fd: int | None = None
+
+    try:
+        try:
+            fd = os.open(str(lock_file), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError:
+            deadline = time.monotonic() + 30.0
+            while time.monotonic() < deadline:
+                if done_marker.exists():
+                    return {"migrated": False, "reason": "waited_for_other_process"}
+                await asyncio.sleep(0.2)
+            return {"migrated": False, "reason": "lock_timeout"}
+
+        from app.core.config import get_config
+        from app.core.storage import get_storage
+        from app.services.register.services import (
+            UserAgreementService,
+            BirthDateService,
+            NsfwSettingsService,
+        )
+
+        storage = get_storage()
+        try:
+            token_data = await storage.load_tokens()
+        except Exception as exc:
+            logger.warning("Legacy account migration: failed to load tokens: {}", exc)
+            return {"migrated": False, "reason": "load_tokens_failed"}
+
+        token_data = token_data or {}
+        tokens: list[str] = []
+        for items in token_data.values():
+            if not isinstance(items, list):
+                continue
+            for item in items:
+                if isinstance(item, str):
+                    tokens.append(item)
+                elif isinstance(item, dict):
+                    token_val = item.get("token")
+                    if isinstance(token_val, str):
+                        tokens.append(token_val)
+
+        # De-duplicate while preserving order.
+        tokens = list(dict.fromkeys([t.strip() for t in tokens if isinstance(t, str) and t.strip()]))
+        if not tokens:
+            done_marker.write_text(str(int(time.time())), encoding="utf-8")
+            return {"migrated": True, "total": 0, "ok": 0, "failed": 0}
+
+        try:
+            concurrency = max(1, int(concurrency))
+        except Exception:
+            concurrency = 10
+
+        cf_clearance = str(get_config("grok.cf_clearance", "") or "").strip()
+
+        def _extract_cookie_value(cookie_str: str, name: str) -> str | None:
+            needle = f"{name}="
+            if needle not in cookie_str:
+                return None
+            for part in cookie_str.split(";"):
+                part = part.strip()
+                if part.startswith(needle):
+                    return part[len(needle):].strip()
+            return None
+
+        def _normalize_tokens(raw_token: str) -> tuple[str, str]:
+            raw_token = raw_token.strip()
+            if ";" in raw_token:
+                sso_val = _extract_cookie_value(raw_token, "sso") or ""
+                sso_rw_val = _extract_cookie_value(raw_token, "sso-rw") or sso_val
+            else:
+                sso_val = raw_token[4:] if raw_token.startswith("sso=") else raw_token
+                sso_rw_val = sso_val
+            return sso_val, sso_rw_val
+
+        def _apply_settings(raw_token: str) -> bool:
+            sso_val, sso_rw_val = _normalize_tokens(raw_token)
+            if not sso_val:
+                return False
+
+            user_service = UserAgreementService(cf_clearance=cf_clearance)
+            birth_service = BirthDateService(cf_clearance=cf_clearance)
+            nsfw_service = NsfwSettingsService(cf_clearance=cf_clearance)
+
+            tos_result = user_service.accept_tos_version(
+                sso=sso_val,
+                sso_rw=sso_rw_val or sso_val,
+                impersonate="chrome120",
+            )
+            if not tos_result.get("ok"):
+                return False
+
+            birth_result = birth_service.set_birth_date(
+                sso=sso_val,
+                sso_rw=sso_rw_val or sso_val,
+                impersonate="chrome120",
+            )
+            if not birth_result.get("ok"):
+                return False
+
+            nsfw_result = nsfw_service.enable_nsfw(
+                sso=sso_val,
+                sso_rw=sso_rw_val or sso_val,
+                impersonate="chrome120",
+            )
+            return bool(nsfw_result.get("ok"))
+
+        sem = asyncio.Semaphore(concurrency)
+
+        async def _run_one(token: str) -> bool:
+            async with sem:
+                return await asyncio.to_thread(_apply_settings, token)
+
+        tasks = [_run_one(token) for token in tokens]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        ok = 0
+        failed = 0
+        for res in results:
+            if isinstance(res, Exception):
+                failed += 1
+            elif res:
+                ok += 1
+            else:
+                failed += 1
+
+        done_marker.write_text(str(int(time.time())), encoding="utf-8")
+        logger.info(
+            "Legacy account migration complete: total=%d, ok=%d, failed=%d",
+            len(tokens),
+            ok,
+            failed,
+        )
+        return {"migrated": True, "total": len(tokens), "ok": ok, "failed": failed}
+    finally:
+        try:
+            if fd is not None:
+                os.close(fd)
+        except Exception:
+            pass
+        try:
+            if lock_file.exists():
+                lock_file.unlink()
+        except Exception:
+            pass

app/core/logger.py

@@ -0,0 +1,117 @@
+"""
+结构化 JSON 日志 - 极简格式
+"""
+
+import sys
+import json
+import traceback
+from pathlib import Path
+from loguru import logger
+
+# 日志目录
+LOG_DIR = Path(__file__).parent.parent.parent / "logs"
+LOG_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _format_json(record) -> str:
+    """格式化日志"""
+    # ISO8601 时间
+    time_str = record["time"].strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3]
+    tz = record["time"].strftime("%z")
+    if tz:
+        time_str += tz[:3] + ":" + tz[3:]
+    
+    log_entry = {
+        "time": time_str,
+        "level": record["level"].name.lower(),
+        "msg": record["message"],
+        "caller": f"{record['file'].name}:{record['line']}",
+    }
+    
+    # trace 上下文
+    extra = record["extra"]
+    if extra.get("traceID"):
+        log_entry["traceID"] = extra["traceID"]
+    if extra.get("spanID"):
+        log_entry["spanID"] = extra["spanID"]
+    
+    # 其他 extra 字段
+    for key, value in extra.items():
+        if key not in ("traceID", "spanID") and not key.startswith("_"):
+            log_entry[key] = value
+    
+    # 错误及以上级别添加堆栈跟踪
+    if record["level"].no >= 40 and record["exception"]:
+        log_entry["stacktrace"] = "".join(traceback.format_exception(
+            record["exception"].type,
+            record["exception"].value,
+            record["exception"].traceback
+        ))
+    
+    return json.dumps(log_entry, ensure_ascii=False)
+
+
+def _make_json_sink(output):
+    """创建 JSON sink"""
+    def sink(message):
+        json_str = _format_json(message.record)
+        print(json_str, file=output, flush=True)
+    return sink
+
+
+def _file_json_sink(message):
+    """写入日志文件"""
+    record = message.record
+    json_str = _format_json(record)
+    log_file = LOG_DIR / f"app_{record['time'].strftime('%Y-%m-%d')}.log"
+    with open(log_file, "a", encoding="utf-8") as f:
+        f.write(json_str + "\n")
+
+
+def setup_logging(
+    level: str = "DEBUG",
+    json_console: bool = True,
+    file_logging: bool = True,
+):
+    """设置日志配置"""
+    logger.remove()
+    
+    # 控制台输出
+    if json_console:
+        logger.add(
+            _make_json_sink(sys.stdout),
+            level=level,
+            format="{message}",
+            colorize=False,
+        )
+    else:
+        logger.add(
+            sys.stdout,
+            level=level,
+            format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{file.name}:{line}</cyan> - <level>{message}</level>",
+            colorize=True,
+        )
+    
+    # 文件输出
+    if file_logging:
+        logger.add(
+            _file_json_sink,
+            level=level,
+            format="{message}",
+            enqueue=True,
+        )
+    
+    return logger
+
+
+def get_logger(trace_id: str = "", span_id: str = ""):
+    """获取绑定了 trace 上下文的 logger"""
+    bound = {}
+    if trace_id:
+        bound["traceID"] = trace_id
+    if span_id:
+        bound["spanID"] = span_id
+    return logger.bind(**bound) if bound else logger
+
+
+__all__ = ["logger", "setup_logging", "get_logger", "LOG_DIR"]

app/core/response_middleware.py

@@ -0,0 +1,71 @@
+"""
+响应中间件
+Response Middleware
+
+用于记录请求日志、生成 TraceID 和计算请求耗时
+"""
+
+import time
+import uuid
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.types import ASGIApp
+
+from app.core.logger import logger
+
+class ResponseLoggerMiddleware(BaseHTTPMiddleware):
+    """
+    请求日志/响应追踪中间件
+    Request Logging and Response Tracking Middleware
+    """
+    
+    async def dispatch(self, request: Request, call_next):
+        # 生成请求 ID
+        trace_id = str(uuid.uuid4())
+        request.state.trace_id = trace_id
+        
+        start_time = time.time()
+        
+        # 记录请求信息
+        logger.info(
+            f"Request: {request.method} {request.url.path}",
+            extra={
+                "traceID": trace_id,
+                "method": request.method,
+                "path": request.url.path
+            }
+        )
+        
+        try:
+            response = await call_next(request)
+            
+            # 计算耗时
+            duration = (time.time() - start_time) * 1000
+            
+            # 记录响应信息
+            logger.info(
+                f"Response: {request.method} {request.url.path} - {response.status_code} ({duration:.2f}ms)",
+                extra={
+                    "traceID": trace_id,
+                    "method": request.method,
+                    "path": request.url.path,
+                    "status": response.status_code,
+                    "duration_ms": round(duration, 2)
+                }
+            )
+            
+            return response
+            
+        except Exception as e:
+            duration = (time.time() - start_time) * 1000
+            logger.error(
+                f"Response Error: {request.method} {request.url.path} - {str(e)} ({duration:.2f}ms)",
+                extra={
+                    "traceID": trace_id,
+                    "method": request.method,
+                    "path": request.url.path,
+                    "duration_ms": round(duration, 2),
+                    "error": str(e)
+                }
+            )
+            raise e

app/core/storage.py

@@ -0,0 +1,720 @@
+"""
+统一存储服务 (Professional Storage Service)
+支持 Local (TOML), Redis, MySQL, PostgreSQL
+
+特性:
+- 全异步 I/O (Async I/O)
+- 连接池管理 (Connection Pooling)
+- 分布式/本地锁 (Distributed/Local Locking)
+- 内存优化 (序列化性能优化)
+"""
+
+import abc
+import os
+import asyncio
+import os
+import hashlib
+import time
+import tomllib
+from typing import Any, Dict, Optional
+from pathlib import Path
+from enum import Enum
+try:
+    import fcntl
+except ImportError:  # pragma: no cover - non-posix platforms
+    fcntl = None
+from contextlib import asynccontextmanager
+
+import orjson
+import aiofiles
+from app.core.logger import logger
+
+# 配置文件路径
+CONFIG_FILE = Path(__file__).parent.parent.parent / "data" / "config.toml"
+TOKEN_FILE = Path(__file__).parent.parent.parent / "data" / "token.json"
+LOCK_DIR = Path(__file__).parent.parent.parent / "data" / ".locks"
+
+# JSON 序列化优化助手函数
+def json_dumps(obj: Any) -> str:
+    return orjson.dumps(obj).decode("utf-8")
+
+def json_loads(obj: str | bytes) -> Any:
+    return orjson.loads(obj)
+
+class StorageError(Exception):
+    """存储服务基础异常"""
+    pass
+
+class BaseStorage(abc.ABC):
+    """存储基类"""
+
+    @abc.abstractmethod
+    async def load_config(self) -> Dict[str, Any]:
+        """加载配置"""
+        pass
+
+    @abc.abstractmethod
+    async def save_config(self, data: Dict[str, Any]):
+        """保存配置"""
+        pass
+
+    @abc.abstractmethod
+    async def load_tokens(self) -> Dict[str, Any]:
+        """加载所有 Token"""
+        pass
+
+    @abc.abstractmethod
+    async def save_tokens(self, data: Dict[str, Any]):
+        """保存所有 Token"""
+        pass
+
+    @abc.abstractmethod
+    async def close(self):
+        """关闭资源"""
+        pass
+    
+    @asynccontextmanager
+    async def acquire_lock(self, name: str, timeout: int = 10):
+        """
+        获取锁 (互斥访问)
+        用于读写操作的临界区保护
+        
+        Args:
+            name: 锁名称
+            timeout: 超时时间 (秒)
+        """
+        # 默认空实现，用于 fallback
+        yield
+
+    async def verify_connection(self) -> bool:
+        """健康检查"""
+        return True
+
+
+class LocalStorage(BaseStorage):
+    """
+    本地文件存储
+    - 使用 aiofiles 进行异步 I/O
+    - 使用 asyncio.Lock 进行进程内并发控制
+    - 如果需要多进程安全，需要系统级文件锁 (fcntl)
+    """
+    
+    def __init__(self):
+        self._lock = asyncio.Lock()
+        
+    @asynccontextmanager
+    async def acquire_lock(self, name: str, timeout: int = 10):
+        if fcntl is None:
+            try:
+                async with asyncio.timeout(timeout):
+                    async with self._lock:
+                        yield
+            except asyncio.TimeoutError:
+                logger.warning(f"LocalStorage: 获取锁 '{name}' 超时 ({timeout}s)")
+                raise StorageError(f"无法获取锁 '{name}'")
+            return
+
+        lock_path = LOCK_DIR / f"{name}.lock"
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+        fd = None
+        locked = False
+        start = time.monotonic()
+
+        async with self._lock:
+            try:
+                fd = open(lock_path, "a+")
+                while True:
+                    try:
+                        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                        locked = True
+                        break
+                    except BlockingIOError:
+                        if time.monotonic() - start >= timeout:
+                            raise StorageError(f"无法获取锁 '{name}'")
+                        await asyncio.sleep(0.05)
+                yield
+            except StorageError:
+                logger.warning(f"LocalStorage: 获取锁 '{name}' 超时 ({timeout}s)")
+                raise
+            finally:
+                if fd:
+                    if locked:
+                        try:
+                            fcntl.flock(fd, fcntl.LOCK_UN)
+                        except Exception:
+                            pass
+                    try:
+                        fd.close()
+                    except Exception:
+                        pass
+
+    async def load_config(self) -> Dict[str, Any]:
+        if not CONFIG_FILE.exists():
+            return {}
+        try:
+            async with aiofiles.open(CONFIG_FILE, "rb") as f:
+                content = await f.read()
+                return tomllib.loads(content.decode("utf-8"))
+        except Exception as e:
+            logger.error(f"LocalStorage: 加载配置失败: {e}")
+            return {}
+
+    async def save_config(self, data: Dict[str, Any]):
+        try:
+            lines = []
+            for section, items in data.items():
+                if not isinstance(items, dict): continue
+                lines.append(f"[{section}]")
+                for key, val in items.items():
+                    if isinstance(val, bool):
+                        val_str = "true" if val else "false"
+                    elif isinstance(val, str):
+                        escaped = val.replace('"', '\\"')
+                        val_str = f'"{escaped}"'
+                    elif isinstance(val, (int, float)):
+                        val_str = str(val)
+                    elif isinstance(val, (list, dict)):
+                        val_str = json_dumps(val)
+                    else:
+                        val_str = f'"{str(val)}"'
+                    lines.append(f"{key} = {val_str}")
+                lines.append("")
+            
+            content = "\n".join(lines)
+            
+            CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
+            async with aiofiles.open(CONFIG_FILE, "w", encoding="utf-8") as f:
+                await f.write(content)
+        except Exception as e:
+            logger.error(f"LocalStorage: 保存配置失败: {e}")
+            raise StorageError(f"保存配置失败: {e}")
+
+    async def load_tokens(self) -> Dict[str, Any]:
+        if not TOKEN_FILE.exists():
+            return {}
+        try:
+            async with aiofiles.open(TOKEN_FILE, "rb") as f:
+                content = await f.read()
+                return json_loads(content)
+        except Exception as e:
+            logger.error(f"LocalStorage: 加载 Token 失败: {e}")
+            return {}
+
+    async def save_tokens(self, data: Dict[str, Any]):
+        try:
+            TOKEN_FILE.parent.mkdir(parents=True, exist_ok=True)
+            temp_path = TOKEN_FILE.with_suffix('.tmp')
+            
+            # 原子写操作: 写入临时文件 -> 重命名
+            async with aiofiles.open(temp_path, "wb") as f:
+                await f.write(orjson.dumps(data, option=orjson.OPT_INDENT_2))
+            
+            # 使用 os.replace 保证原子性
+            os.replace(temp_path, TOKEN_FILE)
+            
+        except Exception as e:
+            logger.error(f"LocalStorage: 保存 Token 失败: {e}")
+            raise StorageError(f"保存 Token 失败: {e}")
+
+    async def close(self):
+        pass
+
+
+class RedisStorage(BaseStorage):
+    """
+    Redis 存储
+    - 使用 redis-py 异步客户端 (自带连接池)
+    - 支持分布式锁 (redis.lock)
+    - 扁平化数据结构优化性能
+    """
+    
+    def __init__(self, url: str):
+        try:
+            from redis import asyncio as aioredis
+            from redis.asyncio.lock import Lock
+        except ImportError:
+            raise ImportError("需要安装 redis 包: pip install redis")
+            
+        # 显式配置连接池
+        # 使用 decode_responses=True 简化字符串处理，但在处理复杂对象时使用 orjson
+        self.redis = aioredis.from_url(
+            url, 
+            decode_responses=True,
+            health_check_interval=30
+        )
+        self.config_key = "grok2api:config"       # Hash: section.key -> value_json
+        self.key_pools = "grok2api:pools"         # Set: pool_names
+        self.prefix_pool_set = "grok2api:pool:"   # Set: pool -> token_ids
+        self.prefix_token_hash = "grok2api:token:"# Hash: token_id -> token_data
+        self.lock_prefix = "grok2api:lock:"
+
+    @asynccontextmanager
+    async def acquire_lock(self, name: str, timeout: int = 10):
+        # 使用 Redis 分布式锁
+        lock_key = f"{self.lock_prefix}{name}"
+        lock = self.redis.lock(lock_key, timeout=timeout, blocking_timeout=5)
+        acquired = False
+        try:
+            acquired = await lock.acquire()
+            if not acquired:
+                raise StorageError(f"RedisStorage: 无法获取锁 '{name}'")
+            yield
+        finally:
+            if acquired:
+                try:
+                    await lock.release()
+                except Exception:
+                    # 锁可能已过期或被意外释放，忽略异常
+                    pass
+
+    async def verify_connection(self) -> bool:
+        try:
+            return await self.redis.ping()
+        except Exception:
+            return False
+
+    async def load_config(self) -> Dict[str, Any]:
+        """从 Redis Hash 加载配置"""
+        try:
+            raw_data = await self.redis.hgetall(self.config_key)
+            if not raw_data:
+                return None
+                
+            config = {}
+            for composite_key, val_str in raw_data.items():
+                if "." not in composite_key: continue
+                section, key = composite_key.split(".", 1)
+                
+                if section not in config: config[section] = {}
+                
+                try:
+                    val = json_loads(val_str)
+                except:
+                    val = val_str
+                config[section][key] = val
+            return config
+        except Exception as e:
+            logger.error(f"RedisStorage: 加载配置失败: {e}")
+            return None
+
+    async def save_config(self, data: Dict[str, Any]):
+        """保存配置到 Redis Hash"""
+        if not data: return
+        try:
+            mapping = {}
+            for section, items in data.items():
+                if not isinstance(items, dict): continue
+                for key, val in items.items():
+                    composite_key = f"{section}.{key}"
+                    mapping[composite_key] = json_dumps(val)
+            
+            if mapping:
+                await self.redis.hset(self.config_key, mapping=mapping)
+        except Exception as e:
+            logger.error(f"RedisStorage: 保存配置失败: {e}")
+            raise
+
+    async def load_tokens(self) -> Dict[str, Any]:
+        """加载所有 Token"""
+        try:
+            pool_names = await self.redis.smembers(self.key_pools)
+            if not pool_names: return None
+            
+            pools = {}
+            async with self.redis.pipeline() as pipe:
+                for pool_name in pool_names:
+                    # 获取该池下所有 Token ID
+                    pipe.smembers(f"{self.prefix_pool_set}{pool_name}")
+                pool_tokens_res = await pipe.execute()
+            
+            # 收集所有 Token ID 以便批量查询
+            all_token_ids = []
+            pool_map = {} # pool_name -> list[token_id]
+            
+            for i, pool_name in enumerate(pool_names):
+                tids = list(pool_tokens_res[i])
+                pool_map[pool_name] = tids
+                all_token_ids.extend(tids)
+                
+            if not all_token_ids:
+                return {name: [] for name in pool_names}
+
+            # 批量获取 Token 详情 (Hash)
+            async with self.redis.pipeline() as pipe:
+                for tid in all_token_ids:
+                    pipe.hgetall(f"{self.prefix_token_hash}{tid}")
+                token_data_list = await pipe.execute()
+                
+            # 重组数据结构
+            token_lookup = {}
+            for i, tid in enumerate(all_token_ids):
+                t_data = token_data_list[i]
+                if not t_data: continue
+                
+                # 恢复 tags (JSON -> List)
+                if "tags" in t_data:
+                    try: t_data["tags"] = json_loads(t_data["tags"])
+                    except: t_data["tags"] = []
+                
+                # 类型转换 (Redis 返回全 string)
+                for int_field in ["quota", "created_at", "use_count", "fail_count", "last_used_at", "last_fail_at", "last_sync_at"]:
+                    if t_data.get(int_field) and t_data[int_field] != "None":
+                         try: t_data[int_field] = int(t_data[int_field])
+                         except: pass
+                         
+                token_lookup[tid] = t_data
+
+            # 按 Pool 分组返回
+            for pool_name in pool_names:
+                pools[pool_name] = []
+                for tid in pool_map[pool_name]:
+                    if tid in token_lookup:
+                        pools[pool_name].append(token_lookup[tid])
+                        
+            return pools
+            
+        except Exception as e:
+            logger.error(f"RedisStorage: 加载 Token 失败: {e}")
+            return None
+
+    async def save_tokens(self, data: Dict[str, Any]):
+        """保存所有 Token"""
+        if data is None:
+            return
+        try:
+            new_pools = set(data.keys()) if isinstance(data, dict) else set()
+            pool_tokens_map = {}
+            new_token_ids = set()
+
+            for pool_name, tokens in (data or {}).items():
+                tids_in_pool = []
+                for t in tokens:
+                    token_str = t.get("token")
+                    if not token_str:
+                        continue
+                    tids_in_pool.append(token_str)
+                    new_token_ids.add(token_str)
+                pool_tokens_map[pool_name] = tids_in_pool
+
+            existing_pools = await self.redis.smembers(self.key_pools)
+            existing_pools = set(existing_pools) if existing_pools else set()
+
+            existing_token_ids = set()
+            if existing_pools:
+                async with self.redis.pipeline() as pipe:
+                    for pool_name in existing_pools:
+                        pipe.smembers(f"{self.prefix_pool_set}{pool_name}")
+                    pool_tokens_res = await pipe.execute()
+                for tokens in pool_tokens_res:
+                    existing_token_ids.update(list(tokens or []))
+
+            tokens_to_delete = existing_token_ids - new_token_ids
+            all_pools = existing_pools.union(new_pools)
+
+            async with self.redis.pipeline() as pipe:
+                # Reset pool index
+                pipe.delete(self.key_pools)
+                if new_pools:
+                    pipe.sadd(self.key_pools, *new_pools)
+
+                # Reset pool sets
+                for pool_name in all_pools:
+                    pipe.delete(f"{self.prefix_pool_set}{pool_name}")
+                for pool_name, tids_in_pool in pool_tokens_map.items():
+                    if tids_in_pool:
+                        pipe.sadd(f"{self.prefix_pool_set}{pool_name}", *tids_in_pool)
+
+                # Remove deleted token hashes
+                for token_str in tokens_to_delete:
+                    pipe.delete(f"{self.prefix_token_hash}{token_str}")
+
+                # Upsert token hashes
+                for pool_name, tokens in (data or {}).items():
+                    for t in tokens:
+                        token_str = t.get("token")
+                        if not token_str:
+                            continue
+                        t_flat = t.copy()
+                        if "tags" in t_flat:
+                            t_flat["tags"] = json_dumps(t_flat["tags"])
+                        status = t_flat.get("status")
+                        if isinstance(status, str) and status.startswith("TokenStatus."):
+                            t_flat["status"] = status.split(".", 1)[1].lower()
+                        elif isinstance(status, Enum):
+                            t_flat["status"] = status.value
+                        t_flat = {k: str(v) for k, v in t_flat.items() if v is not None}
+                        pipe.hset(f"{self.prefix_token_hash}{token_str}", mapping=t_flat)
+
+                await pipe.execute()
+                
+        except Exception as e:
+            logger.error(f"RedisStorage: 保存 Token 失败: {e}")
+            raise
+
+    async def close(self):
+        try:
+            await self.redis.close()
+        except (RuntimeError, asyncio.CancelledError, Exception):
+             # 忽略关闭时的 Event loop is closed 错误
+            pass
+
+
+class SQLStorage(BaseStorage):
+    """
+    SQL 数据库存储 (MySQL/PgSQL)
+    - 使用 SQLAlchemy 异步引擎
+    - 自动 Schema 初始化
+    - 内置连接池 (QueuePool)
+    """
+
+    def __init__(self, url: str):
+        try:
+            from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
+            from sqlalchemy import text, MetaData
+        except ImportError:
+            raise ImportError("需要安装 sqlalchemy 和 async 驱动: pip install sqlalchemy[asyncio]")
+
+        self.dialect = url.split(":", 1)[0].split("+", 1)[0].lower()
+        
+        # 配置 robust 的连接池
+        self.engine = create_async_engine(
+            url,
+            echo=False,
+            pool_size=20,
+            max_overflow=10,
+            pool_recycle=3600,
+            pool_pre_ping=True
+        )
+        self.async_session = async_sessionmaker(self.engine, expire_on_commit=False)
+        self._initialized = False 
+    
+    async def _ensure_schema(self):
+        """确保数据库表存在"""
+        if self._initialized: return
+        try:
+            async with self.engine.begin() as conn:
+                from sqlalchemy import text
+                
+                # Tokens 表 (通用 SQL)
+                await conn.execute(text("""
+                    CREATE TABLE IF NOT EXISTS tokens (
+                        token VARCHAR(512) PRIMARY KEY,
+                        pool_name VARCHAR(64) NOT NULL,
+                        data TEXT,
+                        updated_at BIGINT
+                    )
+                """))
+                
+                # 配置表
+                await conn.execute(text("""
+                    CREATE TABLE IF NOT EXISTS app_config (
+                        section VARCHAR(64) NOT NULL,
+                        key_name VARCHAR(64) NOT NULL,
+                        value TEXT,
+                        PRIMARY KEY (section, key_name)
+                    )
+                """))
+                
+                # 索引
+                try:
+                    await conn.execute(text("CREATE INDEX idx_tokens_pool ON tokens (pool_name)"))
+                except Exception:
+                    pass
+
+                # 尝试兼容旧表结构
+                try:
+                    if self.dialect in ("mysql", "mariadb"):
+                        await conn.execute(text("ALTER TABLE tokens MODIFY token VARCHAR(512)"))
+                        await conn.execute(text("ALTER TABLE tokens MODIFY data TEXT"))
+                    elif self.dialect in ("postgres", "postgresql", "pgsql"):
+                        await conn.execute(text("ALTER TABLE tokens ALTER COLUMN token TYPE VARCHAR(512)"))
+                        await conn.execute(text("ALTER TABLE tokens ALTER COLUMN data TYPE TEXT"))
+                except Exception:
+                    pass
+                    
+            self._initialized = True
+        except Exception as e:
+            logger.error(f"SQLStorage: Schema 初始化失败: {e}")
+            raise
+
+    @asynccontextmanager
+    async def acquire_lock(self, name: str, timeout: int = 10):
+        # SQL 分布式锁: MySQL GET_LOCK / PG advisory_lock
+        from sqlalchemy import text
+        lock_name = f"g2a:{hashlib.sha1(name.encode('utf-8')).hexdigest()[:24]}"
+        if self.dialect in ("mysql", "mariadb"):
+            async with self.async_session() as session:
+                res = await session.execute(
+                    text("SELECT GET_LOCK(:name, :timeout)"),
+                    {"name": lock_name, "timeout": timeout}
+                )
+                got = res.scalar()
+                if got != 1:
+                    raise StorageError(f"SQLStorage: 无法获取锁 '{name}'")
+                try:
+                    yield
+                finally:
+                    try:
+                        await session.execute(text("SELECT RELEASE_LOCK(:name)"), {"name": lock_name})
+                        await session.commit()
+                    except Exception:
+                        pass
+        elif self.dialect in ("postgres", "postgresql", "pgsql"):
+            lock_key = int.from_bytes(hashlib.sha256(name.encode("utf-8")).digest()[:8], "big", signed=False)
+            async with self.async_session() as session:
+                start = time.monotonic()
+                while True:
+                    res = await session.execute(
+                        text("SELECT pg_try_advisory_lock(:key)"),
+                        {"key": lock_key}
+                    )
+                    if res.scalar():
+                        break
+                    if time.monotonic() - start >= timeout:
+                        raise StorageError(f"SQLStorage: 无法获取锁 '{name}'")
+                    await asyncio.sleep(0.1)
+                try:
+                    yield
+                finally:
+                    try:
+                        await session.execute(text("SELECT pg_advisory_unlock(:key)"), {"key": lock_key})
+                        await session.commit()
+                    except Exception:
+                        pass
+        else:
+            yield
+
+    async def load_config(self) -> Dict[str, Any]:
+        await self._ensure_schema()
+        from sqlalchemy import text
+        try:
+            async with self.async_session() as session:
+                res = await session.execute(text("SELECT section, key_name, value FROM app_config"))
+                rows = res.fetchall()
+                if not rows: return None
+                
+                config = {}
+                for section, key, val_str in rows:
+                    if section not in config: config[section] = {}
+                    try:
+                        val = json_loads(val_str)
+                    except:
+                        val = val_str
+                    config[section][key] = val
+                return config
+        except Exception as e:
+            logger.error(f"SQLStorage: 加载配置失败: {e}")
+            return None
+
+    async def save_config(self, data: Dict[str, Any]):
+        await self._ensure_schema()
+        from sqlalchemy import text
+        try:
+            async with self.async_session() as session:
+                for section, items in data.items():
+                    if not isinstance(items, dict): continue
+                    for key, val in items.items():
+                        val_str = json_dumps(val)
+                        
+                        # Upsert 逻辑 (简单实现: Delete + Insert)
+                        await session.execute(
+                            text("DELETE FROM app_config WHERE section=:s AND key_name=:k"),
+                            {"s": section, "k": key}
+                        )
+                        await session.execute(
+                            text("INSERT INTO app_config (section, key_name, value) VALUES (:s, :k, :v)"),
+                            {"s": section, "k": key, "v": val_str}
+                        )
+                await session.commit()
+        except Exception as e:
+            logger.error(f"SQLStorage: 保存配置失败: {e}")
+            raise
+
+    async def load_tokens(self) -> Dict[str, Any]:
+        await self._ensure_schema()
+        from sqlalchemy import text
+        try:
+            async with self.async_session() as session:
+                res = await session.execute(text("SELECT pool_name, data FROM tokens"))
+                rows = res.fetchall()
+                if not rows: return None
+                
+                pools = {}
+                for pool_name, data_json in rows:
+                    if pool_name not in pools: pools[pool_name] = []
+                    
+                    try:
+                        if isinstance(data_json, str):
+                            t_data = json_loads(data_json)
+                        else:
+                            t_data = data_json
+                        pools[pool_name].append(t_data)
+                    except:
+                        pass
+                return pools
+        except Exception as e:
+            logger.error(f"SQLStorage: 加载 Token 失败: {e}")
+            return None
+
+    async def save_tokens(self, data: Dict[str, Any]):
+        await self._ensure_schema()
+        from sqlalchemy import text
+        try:
+            async with self.async_session() as session:
+                await session.execute(text("DELETE FROM tokens")) 
+                
+                params = []
+                for pool_name, tokens in data.items():
+                    for t in tokens:
+                        params.append({
+                            "token": t.get("token"),
+                            "pool_name": pool_name,
+                            "data": json_dumps(t),
+                            "updated_at": 0
+                        })
+                
+                if params:
+                    # 批量插入
+                    await session.execute(
+                        text("INSERT INTO tokens (token, pool_name, data, updated_at) VALUES (:token, :pool_name, :data, :updated_at)"),
+                        params
+                    )
+                await session.commit()
+        except Exception as e:
+            logger.error(f"SQLStorage: 保存 Token 失败: {e}")
+            raise
+
+    async def close(self):
+        await self.engine.dispose()
+
+
+class StorageFactory:
+    """存储后端工厂"""
+    _instance: Optional[BaseStorage] = None
+    
+    @classmethod
+    def get_storage(cls) -> BaseStorage:
+        """获取全局存储实例 (单例)"""
+        if cls._instance:
+            return cls._instance
+            
+        storage_type = os.getenv("SERVER_STORAGE_TYPE", "local").lower()
+        storage_url = os.getenv("SERVER_STORAGE_URL", "")
+        
+        logger.info(f"StorageFactory: 初始化存储后端: {storage_type}")
+        
+        if storage_type == "redis":
+            if not storage_url: raise ValueError("Redis 存储需要设置 SERVER_STORAGE_URL")
+            cls._instance = RedisStorage(storage_url)
+            
+        elif storage_type in ("mysql", "pgsql"):
+            if not storage_url: raise ValueError("SQL 存储需要设置 SERVER_STORAGE_URL")
+            cls._instance = SQLStorage(storage_url)
+            
+        else:
+            cls._instance = LocalStorage()
+            
+        return cls._instance
+
+def get_storage() -> BaseStorage:
+    return StorageFactory.get_storage()

app/services/api_keys.py

@@ -0,0 +1,432 @@
+"""API Key 管理器 - 多用户密钥管理"""
+
+import orjson
+import time
+import os
+import secrets
+import asyncio
+from datetime import datetime, timezone, timedelta
+from typing import List, Dict, Optional, Any, Tuple
+from pathlib import Path
+
+from app.core.logger import logger
+from app.core.config import get_config
+
+
+class ApiKeyManager:
+    """API Key 管理服务"""
+    
+    _instance = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+    
+    def __init__(self):
+        if hasattr(self, '_initialized'):
+            return
+            
+        self.file_path = Path(__file__).parents[2] / "data" / "api_keys.json"
+        self.usage_path = Path(__file__).parents[2] / "data" / "api_key_usage.json"
+        self._keys: List[Dict] = []
+        self._lock = asyncio.Lock()
+        self._loaded = False
+
+        self._usage: Dict[str, Dict[str, Dict[str, int]]] = {}
+        self._usage_lock = asyncio.Lock()
+        self._usage_loaded = False
+        
+        self._initialized = True
+        logger.debug(f"[ApiKey] 初始化完成: {self.file_path}")
+
+    async def init(self):
+        """初始化加载数据"""
+        if not self._loaded:
+            await self._load_data()
+        if not self._usage_loaded:
+            await self._load_usage_data()
+
+    async def _load_data(self):
+        """加载 API Keys"""
+        if self._loaded:
+            return
+
+        if not self.file_path.exists():
+            self._keys = []
+            self._loaded = True
+            return
+
+        try:
+            async with self._lock:
+                content = await asyncio.to_thread(self.file_path.read_bytes)
+                if content:
+                    data = orjson.loads(content)
+                    if isinstance(data, list):
+                        out: List[Dict[str, Any]] = []
+                        for item in data:
+                            if not isinstance(item, dict):
+                                continue
+                            row = self._normalize_key_row(item)
+                            if row.get("key"):
+                                out.append(row)
+                        self._keys = out
+                    else:
+                        self._keys = []
+                else:
+                    self._keys = []
+                self._loaded = True
+                logger.debug(f"[ApiKey] 加载了 {len(self._keys)} 个 API Key")
+        except Exception as e:
+            logger.error(f"[ApiKey] 加载失败: {e}")
+            self._keys = []
+            self._loaded = True # 即使加载失败也认为已尝试加载，防止后续保存清空数据（或者抛出异常）
+
+    async def _save_data(self):
+        """保存 API Keys"""
+        if not self._loaded:
+            logger.warning("[ApiKey] 尝试在数据未加载时保存，已取消操作以防覆盖数据")
+            return
+            
+        try:
+            # 确保目录存在
+            self.file_path.parent.mkdir(parents=True, exist_ok=True)
+            
+            async with self._lock:
+                content = orjson.dumps(self._keys, option=orjson.OPT_INDENT_2)
+                await asyncio.to_thread(self.file_path.write_bytes, content)
+        except Exception as e:
+            logger.error(f"[ApiKey] 保存失败: {e}")
+
+    def _normalize_limit(self, v: Any) -> int:
+        """Normalize a daily limit value. -1 means unlimited."""
+        if v is None or v == "":
+            return -1
+        try:
+            n = int(v)
+        except Exception:
+            return -1
+        return max(-1, n)
+
+    def _normalize_key_row(self, row: Dict[str, Any]) -> Dict[str, Any]:
+        out = dict(row or {})
+        out["key"] = str(out.get("key") or "").strip()
+        out["name"] = str(out.get("name") or "").strip()
+        try:
+            out["created_at"] = int(out.get("created_at") or int(time.time()))
+        except Exception:
+            out["created_at"] = int(time.time())
+        out["is_active"] = bool(out.get("is_active", True))
+
+        # Daily limits (-1 = unlimited)
+        out["chat_limit"] = self._normalize_limit(out.get("chat_limit", -1))
+        out["heavy_limit"] = self._normalize_limit(out.get("heavy_limit", -1))
+        out["image_limit"] = self._normalize_limit(out.get("image_limit", -1))
+        out["video_limit"] = self._normalize_limit(out.get("video_limit", -1))
+        return out
+
+    def _tz_offset_minutes(self) -> int:
+        raw = (os.getenv("CACHE_RESET_TZ_OFFSET_MINUTES", "") or "").strip()
+        try:
+            n = int(raw)
+        except Exception:
+            n = 480
+        return max(-720, min(840, n))
+
+    def _day_str(self, at_ms: Optional[int] = None, tz_offset_minutes: Optional[int] = None) -> str:
+        now_ms = int(at_ms if at_ms is not None else int(time.time() * 1000))
+        offset = self._tz_offset_minutes() if tz_offset_minutes is None else int(tz_offset_minutes)
+        dt = datetime.fromtimestamp(now_ms / 1000, tz=timezone.utc) + timedelta(minutes=offset)
+        return dt.strftime("%Y-%m-%d")
+
+    async def _load_usage_data(self):
+        """Load per-day per-key usage counters."""
+        if self._usage_loaded:
+            return
+
+        if not self.usage_path.exists():
+            self._usage = {}
+            self._usage_loaded = True
+            return
+
+        try:
+            async with self._usage_lock:
+                if self.usage_path.exists():
+                    content = await asyncio.to_thread(self.usage_path.read_bytes)
+                    if content:
+                        data = orjson.loads(content)
+                        if isinstance(data, dict):
+                            # { day: { key: { chat_used, ... } } }
+                            self._usage = data  # type: ignore[assignment]
+                        else:
+                            self._usage = {}
+                    else:
+                        self._usage = {}
+                self._usage_loaded = True
+        except Exception as e:
+            logger.error(f"[ApiKey] Usage 加载失败: {e}")
+            self._usage = {}
+            self._usage_loaded = True
+
+    async def _save_usage_data(self):
+        if not self._usage_loaded:
+            return
+        try:
+            self.usage_path.parent.mkdir(parents=True, exist_ok=True)
+            async with self._usage_lock:
+                content = orjson.dumps(self._usage, option=orjson.OPT_INDENT_2)
+                await asyncio.to_thread(self.usage_path.write_bytes, content)
+        except Exception as e:
+            logger.error(f"[ApiKey] Usage 保存失败: {e}")
+
+    def generate_key(self) -> str:
+        """生成一个新的 sk- 开头的 key"""
+        return f"sk-{secrets.token_urlsafe(24)}"
+
+    def generate_name(self) -> str:
+        """生成一个随机 key 名称"""
+        return f"key-{secrets.token_urlsafe(6)}"
+
+    async def add_key(
+        self,
+        name: str | None = None,
+        key: str | None = None,
+        limits: Optional[Dict[str, Any]] = None,
+        is_active: bool = True,
+    ) -> Dict[str, Any]:
+        """添加 API Key（支持自定义 key 与每日额度）"""
+        await self.init()
+
+        name_val = str(name or "").strip() or self.generate_name()
+        key_val = str(key or "").strip() or self.generate_key()
+
+        limits = limits or {}
+        new_key: Dict[str, Any] = {
+            "key": key_val,
+            "name": name_val,
+            "created_at": int(time.time()),
+            "is_active": bool(is_active),
+            "chat_limit": self._normalize_limit(limits.get("chat_limit", limits.get("chat_per_day", -1))),
+            "heavy_limit": self._normalize_limit(limits.get("heavy_limit", limits.get("heavy_per_day", -1))),
+            "image_limit": self._normalize_limit(limits.get("image_limit", limits.get("image_per_day", -1))),
+            "video_limit": self._normalize_limit(limits.get("video_limit", limits.get("video_per_day", -1))),
+        }
+
+        # Ensure uniqueness
+        if any(k.get("key") == key_val for k in self._keys):
+            raise ValueError("Key already exists")
+
+        self._keys.append(new_key)
+        await self._save_data()
+        logger.info(f"[ApiKey] 添加新Key: {name_val}")
+        return new_key
+
+    async def batch_add_keys(self, name_prefix: str, count: int) -> List[Dict]:
+        """批量添加 API Key"""
+        new_keys = []
+        for i in range(1, count + 1):
+            name = f"{name_prefix}-{i}" if count > 1 else name_prefix
+            new_keys.append({
+                "key": self.generate_key(),
+                "name": name,
+                "created_at": int(time.time()),
+                "is_active": True,
+                "chat_limit": -1,
+                "heavy_limit": -1,
+                "image_limit": -1,
+                "video_limit": -1,
+            })
+        
+        self._keys.extend(new_keys)
+        await self._save_data()
+        logger.info(f"[ApiKey] 批量添加 {count} 个 Key, 前缀: {name_prefix}")
+        return new_keys
+
+    async def delete_key(self, key: str) -> bool:
+        """删除 API Key"""
+        initial_len = len(self._keys)
+        self._keys = [k for k in self._keys if k["key"] != key]
+        
+        if len(self._keys) != initial_len:
+            await self._save_data()
+            logger.info(f"[ApiKey] 删除Key: {key[:10]}...")
+            return True
+        return False
+
+    async def batch_delete_keys(self, keys: List[str]) -> int:
+        """批量删除 API Key"""
+        initial_len = len(self._keys)
+        self._keys = [k for k in self._keys if k["key"] not in keys]
+        
+        deleted_count = initial_len - len(self._keys)
+        if deleted_count > 0:
+            await self._save_data()
+            logger.info(f"[ApiKey] 批量删除 {deleted_count} 个 Key")
+        return deleted_count
+
+    async def update_key_status(self, key: str, is_active: bool) -> bool:
+        """更新 Key 状态"""
+        for k in self._keys:
+            if k["key"] == key:
+                k["is_active"] = is_active
+                await self._save_data()
+                return True
+        return False
+        
+    async def batch_update_keys_status(self, keys: List[str], is_active: bool) -> int:
+        """批量更新 Key 状态"""
+        updated_count = 0
+        for k in self._keys:
+            if k["key"] in keys:
+                if k["is_active"] != is_active:
+                    k["is_active"] = is_active
+                    updated_count += 1
+        
+        if updated_count > 0:
+            await self._save_data()
+            logger.info(f"[ApiKey] 批量更新 {updated_count} 个 Key 状态为: {is_active}")
+        return updated_count
+
+    async def update_key_name(self, key: str, name: str) -> bool:
+        """更新 Key 备注"""
+        for k in self._keys:
+            if k["key"] == key:
+                k["name"] = name
+                await self._save_data()
+                return True
+        return False
+
+    async def update_key_limits(self, key: str, limits: Dict[str, Any]) -> bool:
+        """更新 Key 每日额度（-1 表示不限）"""
+        limits = limits or {}
+        for k in self._keys:
+            if k.get("key") != key:
+                continue
+            if "chat_limit" in limits or "chat_per_day" in limits:
+                k["chat_limit"] = self._normalize_limit(limits.get("chat_limit", limits.get("chat_per_day")))
+            if "heavy_limit" in limits or "heavy_per_day" in limits:
+                k["heavy_limit"] = self._normalize_limit(limits.get("heavy_limit", limits.get("heavy_per_day")))
+            if "image_limit" in limits or "image_per_day" in limits:
+                k["image_limit"] = self._normalize_limit(limits.get("image_limit", limits.get("image_per_day")))
+            if "video_limit" in limits or "video_per_day" in limits:
+                k["video_limit"] = self._normalize_limit(limits.get("video_limit", limits.get("video_per_day")))
+            await self._save_data()
+            return True
+        return False
+
+    def get_key_row(self, key: str) -> Optional[Dict[str, Any]]:
+        """获取 Key 原始记录（不要求 active）"""
+        for k in self._keys:
+            if k.get("key") == key:
+                return self._normalize_key_row(k)
+        return None
+
+    async def usage_for_day(self, day: str) -> Dict[str, Dict[str, int]]:
+        """返回指定 day 的 usage map: { key: {chat_used,...} }"""
+        await self.init()
+        if not self._usage_loaded:
+            await self._load_usage_data()
+        day_map = self._usage.get(day)
+        return day_map if isinstance(day_map, dict) else {}
+
+    async def usage_today(self) -> Tuple[str, Dict[str, Dict[str, int]]]:
+        day = self._day_str()
+        return day, await self.usage_for_day(day)
+
+    async def consume_daily_usage(
+        self,
+        key: str,
+        incs: Dict[str, int],
+        tz_offset_minutes: Optional[int] = None,
+    ) -> bool:
+        """
+        Consume per-day quota for the given API key.
+
+        incs keys: chat_used/heavy_used/image_used/video_used
+        """
+        await self.init()
+        row = self.get_key_row(key)
+        if not row or not row.get("is_active"):
+            # Unknown/disabled keys are already rejected by auth; keep best-effort safe here.
+            return True
+
+        if not self._usage_loaded:
+            await self._load_usage_data()
+
+        day = self._day_str(tz_offset_minutes=tz_offset_minutes)
+        at_ms = int(time.time() * 1000)
+
+        # Normalize incs
+        normalized: Dict[str, int] = {}
+        for k, v in (incs or {}).items():
+            try:
+                inc = int(v)
+            except Exception:
+                continue
+            if inc <= 0:
+                continue
+            normalized[k] = inc
+        if not normalized:
+            return True
+
+        limits = {
+            "chat_used": int(row.get("chat_limit", -1)),
+            "heavy_used": int(row.get("heavy_limit", -1)),
+            "image_used": int(row.get("image_limit", -1)),
+            "video_used": int(row.get("video_limit", -1)),
+        }
+
+        async with self._usage_lock:
+            day_map = self._usage.get(day)
+            if not isinstance(day_map, dict):
+                day_map = {}
+                self._usage[day] = day_map  # type: ignore[assignment]
+
+            usage = day_map.get(key)
+            if not isinstance(usage, dict):
+                usage = {"chat_used": 0, "heavy_used": 0, "image_used": 0, "video_used": 0, "updated_at": at_ms}
+                day_map[key] = usage  # type: ignore[assignment]
+
+            # Check all limits first (atomic for multi-bucket)
+            for bucket, inc in normalized.items():
+                lim = int(limits.get(bucket, -1))
+                used = int(usage.get(bucket, 0) or 0)
+                if lim >= 0 and used + inc > lim:
+                    return False
+
+            # Apply
+            for bucket, inc in normalized.items():
+                usage[bucket] = int(usage.get(bucket, 0) or 0) + inc
+            usage["updated_at"] = at_ms
+
+        await self._save_usage_data()
+        return True
+
+    def validate_key(self, key: str) -> Optional[Dict]:
+        """验证 Key，返回 Key 信息"""
+        # 1. 检查全局配置的 Key (作为默认 admin key)
+        global_key = str(get_config("app.api_key", "") or "").strip()
+        if global_key and key == global_key:
+            return {
+                "key": global_key,
+                "name": "默认管理员",
+                "is_active": True,
+                "is_admin": True
+            }
+            
+        # 2. 检查多 Key 列表
+        for k in self._keys:
+            if k["key"] == key:
+                if k["is_active"]:
+                    return {**k, "is_admin": False} # 普通 Key 也可以视为非管理员? 暂不区分权限，只做身份识别
+                return None
+                
+        return None
+
+    def get_all_keys(self) -> List[Dict]:
+        """获取所有 Keys"""
+        return [self._normalize_key_row(k) for k in self._keys]
+
+
+# 全局实例
+api_key_manager = ApiKeyManager()

app/services/base.py

@@ -0,0 +1,2 @@
+# Base service interface will be defined here
+# Placeholder for service abstraction with concurrency control

app/services/grok/assets.py

@@ -0,0 +1,875 @@
+"""
+Grok 文件资产服务
+"""
+
+import asyncio
+import base64
+import os
+import time
+import hashlib
+import re
+import uuid
+from pathlib import Path
+from contextlib import asynccontextmanager
+try:
+    import fcntl
+except ImportError:  # pragma: no cover - non-posix platforms
+    fcntl = None
+from typing import Tuple, List, Dict, Optional, Any
+from urllib.parse import urlparse
+
+import aiofiles
+from curl_cffi.requests import AsyncSession
+
+from app.core.logger import logger
+from app.core.config import get_config
+from app.core.exceptions import (
+    AppException, 
+    UpstreamException, 
+    ValidationException
+)
+from app.services.grok.statsig import StatsigService
+
+
+# ==================== 常量 ====================
+
+UPLOAD_API = "https://grok.com/rest/app-chat/upload-file"
+LIST_API = "https://grok.com/rest/assets"
+DELETE_API = "https://grok.com/rest/assets-metadata"
+DOWNLOAD_API = "https://assets.grok.com"
+LOCK_DIR = Path(__file__).parent.parent.parent.parent / "data" / ".locks"
+
+TIMEOUT = 120
+BROWSER = "chrome136"
+DEFAULT_MIME = "application/octet-stream"
+
+# 并发控制
+DEFAULT_MAX_CONCURRENT = 25
+DEFAULT_DELETE_BATCH_SIZE = 10
+_ASSETS_SEMAPHORE = asyncio.Semaphore(DEFAULT_MAX_CONCURRENT)
+_ASSETS_SEM_VALUE = DEFAULT_MAX_CONCURRENT
+
+def _get_assets_semaphore() -> asyncio.Semaphore:
+    global _ASSETS_SEMAPHORE, _ASSETS_SEM_VALUE
+    value = get_config("performance.assets_max_concurrent", DEFAULT_MAX_CONCURRENT)
+    try:
+        value = int(value)
+    except Exception:
+        value = DEFAULT_MAX_CONCURRENT
+    value = max(1, value)
+    if value != _ASSETS_SEM_VALUE:
+        _ASSETS_SEM_VALUE = value
+        _ASSETS_SEMAPHORE = asyncio.Semaphore(value)
+    return _ASSETS_SEMAPHORE
+
+def _get_delete_batch_size() -> int:
+    value = get_config("performance.assets_delete_batch_size", DEFAULT_DELETE_BATCH_SIZE)
+    try:
+        value = int(value)
+    except Exception:
+        value = DEFAULT_DELETE_BATCH_SIZE
+    return max(1, value)
+
+@asynccontextmanager
+async def _file_lock(name: str, timeout: int = 10):
+    if fcntl is None:
+        yield
+        return
+    LOCK_DIR.mkdir(parents=True, exist_ok=True)
+    lock_path = LOCK_DIR / f"{name}.lock"
+    fd = None
+    locked = False
+    start = time.monotonic()
+    try:
+        fd = open(lock_path, "a+")
+        while True:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                locked = True
+                break
+            except BlockingIOError:
+                if time.monotonic() - start >= timeout:
+                    break
+                await asyncio.sleep(0.05)
+        yield
+    finally:
+        if fd:
+            if locked:
+                try:
+                    fcntl.flock(fd, fcntl.LOCK_UN)
+                except Exception:
+                    pass
+            try:
+                fd.close()
+            except Exception:
+                pass
+
+MIME_TYPES = {
+    # 图片
+    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png',
+    '.gif': 'image/gif', '.webp': 'image/webp', '.bmp': 'image/bmp',
+    
+    # 文档
+    '.pdf': 'application/pdf', '.txt': 'text/plain', '.md': 'text/markdown',
+    '.doc': 'application/msword', 
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.rtf': 'application/rtf',
+    
+    # 表格
+    '.csv': 'text/csv', 
+    '.xls': 'application/vnd.ms-excel',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    
+    # 代码
+    '.py': 'text/x-python-script', '.js': 'application/javascript', '.ts': 'application/typescript',
+    '.java': 'text/x-java', '.cpp': 'text/x-c++', '.c': 'text/x-c',
+    '.go': 'text/x-go', '.rs': 'text/x-rust', '.rb': 'text/x-ruby',
+    '.php': 'text/x-php', '.sh': 'application/x-sh', '.html': 'text/html',
+    '.css': 'text/css', '.sql': 'application/sql',
+    
+    # 数据
+    '.json': 'application/json', '.xml': 'application/xml', '.yaml': 'application/x-yaml',
+    '.yml': 'application/x-yaml', '.toml': 'application/toml', '.ini': 'text/plain',
+    '.log': 'text/plain', '.tmp': 'application/octet-stream',
+    
+    # 其他
+    '.graphql': 'application/graphql', '.proto': 'application/x-protobuf',
+    '.latex': 'application/x-latex', '.wiki': 'text/plain', '.rst': 'text/x-rst',
+}
+
+IMAGE_EXTS = {'.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp'}
+VIDEO_EXTS = {'.mp4', '.mov', '.m4v', '.webm', '.avi', '.mkv'}
+
+
+# ==================== 基础服务 ====================
+
+class BaseService:
+    """基础服务类"""
+    
+    def __init__(self, proxy: str = None):
+        self.proxy = proxy or get_config("grok.asset_proxy_url") or get_config("grok.base_proxy_url", "")
+        self.timeout = get_config("grok.timeout", TIMEOUT)
+        self._session: Optional[AsyncSession] = None
+    
+    def _headers(self, token: str, referer: str = "https://grok.com/") -> dict:
+        """构建请求头"""
+        headers = {
+            "Accept": "*/*",
+            "Accept-Encoding": "gzip, deflate, br, zstd",
+            "Accept-Language": "zh-CN,zh;q=0.9",
+            "Baggage": "sentry-environment=production,sentry-release=d6add6fb0460641fd482d767a335ef72b9b6abb8,sentry-public_key=b311e0f2690c81f25e2c4cf6d4f7ce1c",
+            "Cache-Control": "no-cache",
+            "Content-Type": "application/json",
+            "Origin": "https://grok.com",
+            "Pragma": "no-cache",
+            "Priority": "u=1, i",
+            "Referer": referer,
+            "Sec-Ch-Ua": '"Google Chrome";v="136", "Chromium";v="136", "Not(A:Brand";v="24"',
+            "Sec-Ch-Ua-Arch": "arm",
+            "Sec-Ch-Ua-Bitness": "64",
+            "Sec-Ch-Ua-Mobile": "?0",
+            "Sec-Ch-Ua-Model": "",
+            "Sec-Ch-Ua-Platform": '"macOS"',
+            "Sec-Fetch-Dest": "empty",
+            "Sec-Fetch-Mode": "cors",
+            "Sec-Fetch-Site": "same-origin",
+            "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
+        }
+        
+        # Statsig ID
+        headers["x-statsig-id"] = StatsigService.gen_id()
+        headers["x-xai-request-id"] = str(uuid.uuid4())
+        
+        # Cookie
+        token = token[4:] if token.startswith("sso=") else token
+        cf = get_config("grok.cf_clearance", "")
+        headers["Cookie"] = f"sso={token};cf_clearance={cf}" if cf else f"sso={token}"
+        
+        return headers
+    
+    def _proxies(self) -> Optional[dict]:
+        """构建代理配置"""
+        return {"http": self.proxy, "https": self.proxy} if self.proxy else None
+    
+    def _dl_headers(self, token: str, file_path: str) -> dict:
+        """构建下载请求头"""
+        headers = {
+            "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
+            "Sec-Fetch-Dest": "document",
+            "Sec-Fetch-Mode": "navigate",
+            "Sec-Fetch-Site": "same-site",
+            "Sec-Fetch-User": "?1",
+            "Upgrade-Insecure-Requests": "1",
+            "Referer": "https://grok.com/",
+        }
+        
+        # Cookie
+        token = token[4:] if token.startswith("sso=") else token
+        cf = get_config("grok.cf_clearance", "")
+        headers["Cookie"] = f"sso={token};cf_clearance={cf}" if cf else f"sso={token}"
+        
+        return headers
+    
+    async def _get_session(self) -> AsyncSession:
+        """获取复用 Session"""
+        if self._session is None:
+            self._session = AsyncSession()
+        return self._session
+    
+    async def close(self):
+        """关闭 Session"""
+        if self._session:
+            await self._session.close()
+            self._session = None
+    
+    @staticmethod
+    def is_url(input_str: str) -> bool:
+        """检查是否为 URL"""
+        try:
+            result = urlparse(input_str)
+            return all([result.scheme, result.netloc]) and result.scheme in ['http', 'https']
+        except:
+            return False
+    
+    @staticmethod
+    async def fetch(url: str) -> Tuple[str, str, str]:
+        """
+        获取远程资源并转 Base64
+        
+        Raises:
+            UpstreamException: 当获取失败时
+        """
+        try:
+            async with AsyncSession() as session:
+                response = await session.get(url, timeout=10)
+                if response.status_code >= 400:
+                    raise UpstreamException(
+                        message=f"Failed to fetch resource: {response.status_code}",
+                        details={"url": url, "status": response.status_code}
+                    )
+                
+                filename = url.split('/')[-1].split('?')[0] or 'download'
+                content_type = response.headers.get('content-type', DEFAULT_MIME).split(';')[0]
+                b64 = base64.b64encode(response.content).decode()
+                
+                logger.debug(f"Fetched: {url} -> {filename}")
+                return filename, b64, content_type
+        except Exception as e:
+            logger.error(f"Fetch failed: {url} - {e}")
+            if isinstance(e, AppException):
+                raise e
+            raise UpstreamException(f"Resource fetch failed: {str(e)}", details={"url": url})
+    
+    @staticmethod
+    def parse_b64(data_uri: str) -> Tuple[str, str, str]:
+        """解析 Base64 数据"""
+        if data_uri.startswith("data:"):
+            match = re.match(r"data:([^;]+);base64,(.+)", data_uri)
+            if match:
+                mime = match.group(1)
+                b64 = match.group(2)
+                ext = mime.split('/')[-1] if '/' in mime else 'bin'
+                return f"file.{ext}", b64, mime
+        return "file.bin", data_uri, DEFAULT_MIME
+    
+    @staticmethod
+    def to_b64(file_path: Path, mime_type: str) -> str:
+        """将本地文件转为 base64 data URI"""
+        try:
+            b64_data = base64.b64encode(file_path.read_bytes()).decode()
+            return f"data:{mime_type};base64,{b64_data}"
+        except Exception as e:
+            logger.error(f"File to base64 failed: {file_path} - {e}")
+            raise AppException(f"Failed to read file: {file_path}", code="file_read_error")
+
+
+# ==================== 上传服务 ====================
+
+class UploadService(BaseService):
+    """文件上传服务"""
+    
+    async def upload(self, file_input: str, token: str) -> Tuple[str, str]:
+        """
+        上传文件到 Grok
+        
+        Returns:
+            (file_id, file_uri)
+            
+        Raises:
+            ValidationException: 输入无效
+            UpstreamException: 上传失败
+        """
+        async with _get_assets_semaphore():
+            try:
+                # 处理输入
+                if self.is_url(file_input):
+                    filename, b64, mime = await self.fetch(file_input)
+                else:
+                    filename, b64, mime = self.parse_b64(file_input)
+                
+                if not b64:
+                    raise ValidationException("Invalid file input: empty content")
+                
+                # 构建请求
+                headers = self._headers(token)
+                payload = {
+                    "fileName": filename,
+                    "fileMimeType": mime,
+                    "content": b64,
+                }
+                
+                # 执行上传
+                session = await self._get_session()
+                response = await session.post(
+                    UPLOAD_API,
+                    headers=headers,
+                    json=payload,
+                    impersonate=BROWSER,
+                    timeout=self.timeout,
+                    proxies=self._proxies(),
+                )
+                
+                if response.status_code == 200:
+                    result = response.json()
+                    file_id = result.get("fileMetadataId", "")
+                    file_uri = result.get("fileUri", "")
+                    logger.info(f"Upload success: {filename} -> {file_id}", extra={"file_id": file_id})
+                    return file_id, file_uri
+                
+                logger.error(
+                    f"Upload failed: {filename} - {response.status_code}", 
+                    extra={"response": response.text[:200]}
+                )
+                raise UpstreamException(
+                    message=f"Upload failed with status {response.status_code}",
+                    details={"status": response.status_code, "response": response.text[:200]}
+                )
+            
+            except Exception as e:
+                logger.error(f"Upload error: {e}")
+                if isinstance(e, AppException):
+                    raise e
+                raise UpstreamException(f"Upload process error: {str(e)}")
+
+
+# ==================== 列表服务 ====================
+
+class ListService(BaseService):
+    """文件列表查询服务"""
+    
+    async def iter_assets(self, token: str):
+        """
+        分页迭代资产列表
+        """
+        headers = self._headers(token, referer="https://grok.com/files")
+        base_params = {
+            "pageSize": 50,
+            "orderBy": "ORDER_BY_LAST_USE_TIME",
+            "source": "SOURCE_ANY",
+            "isLatest": "true",
+        }
+        page_token = None
+        seen_tokens = set()
+
+        async with AsyncSession() as session:
+            while True:
+                params = dict(base_params)
+                if page_token:
+                    if page_token in seen_tokens:
+                        logger.warning("List pagination stopped due to repeated page token")
+                        break
+                    seen_tokens.add(page_token)
+                    params["pageToken"] = page_token
+
+                response = await session.get(
+                    LIST_API,
+                    headers=headers,
+                    params=params,
+                    impersonate=BROWSER,
+                    timeout=self.timeout,
+                    proxies=self._proxies(),
+                )
+
+                if response.status_code != 200:
+                    logger.error(f"List failed: {response.status_code}")
+                    raise UpstreamException(
+                        message=f"List assets failed: {response.status_code}",
+                        details={"status": response.status_code}
+                    )
+
+                result = response.json()
+                page_assets = result.get("assets", [])
+                yield page_assets
+
+                page_token = result.get("nextPageToken")
+                if not page_token:
+                    break
+
+    async def list(self, token: str) -> List[Dict]:
+        """
+        查询文件列表
+        
+        Raises:
+            UpstreamException: 查询失败
+        """
+        try:
+            assets: List[Dict] = []
+            async for page_assets in self.iter_assets(token):
+                assets.extend(page_assets)
+
+            logger.info(f"List success: {len(assets)} files")
+            return assets
+        
+        except Exception as e:
+            logger.error(f"List error: {e}")
+            if isinstance(e, AppException):
+                raise e
+            raise UpstreamException(f"List assets error: {str(e)}")
+
+    async def count(self, token: str) -> int:
+        """
+        统计资产数量（不保留明细）
+        """
+        try:
+            total = 0
+            async for page_assets in self.iter_assets(token):
+                total += len(page_assets)
+            return total
+        except Exception as e:
+            logger.error(f"List count error: {e}")
+            if isinstance(e, AppException):
+                raise e
+            raise UpstreamException(f"List assets error: {str(e)}")
+
+
+# ==================== 删除服务 ====================
+
+class DeleteService(BaseService):
+    """文件删除服务"""
+    
+    async def delete(self, token: str, asset_id: str) -> bool:
+        """
+        删除单个文件
+        
+        Raises:
+            UpstreamException: 删除失败
+        """
+        async with _get_assets_semaphore():
+            try:
+                headers = self._headers(token, referer="https://grok.com/files")
+                url = f"{DELETE_API}/{asset_id}"
+                
+                session = await self._get_session()
+                response = await session.delete(
+                    url,
+                    headers=headers,
+                    impersonate=BROWSER,
+                    timeout=self.timeout,
+                    proxies=self._proxies(),
+                )
+                
+                if response.status_code == 200:
+                    logger.debug(f"Delete success: {asset_id}")
+                    return True
+                
+                logger.error(f"Delete failed: {asset_id} - {response.status_code}")
+                #: Note: Returning False or raising Exception? 
+                #: Assuming caller handles Exception for stricter control, or False for loose control.
+                #: Given "optimization" and "standardization", raising exceptions is better for API feedback.
+                raise UpstreamException(
+                    message=f"Delete failed: {asset_id}",
+                    details={"status": response.status_code}
+                )
+            
+            except Exception as e:
+                logger.error(f"Delete error: {asset_id} - {e}")
+                if isinstance(e, AppException):
+                    raise e
+                raise UpstreamException(f"Delete error: {str(e)}")
+    
+    async def delete_all(self, token: str) -> Dict[str, int]:
+        """
+        删除所有文件
+        """
+        total = 0
+        success = 0
+        failed = 0
+        list_service = ListService(self.proxy)
+        try:
+            async for assets in list_service.iter_assets(token):
+                if not assets:
+                    continue
+                total += len(assets)
+
+                # 批量并发删除
+                async def _delete_one(asset: Dict, index: int) -> bool:
+                    await asyncio.sleep(0.01 * index)
+                    asset_id = asset.get("assetId", "")
+                    if asset_id:
+                        try:
+                            return await self.delete(token, asset_id)
+                        except:
+                            return False
+                    return False
+
+                batch_size = _get_delete_batch_size()
+                for i in range(0, len(assets), batch_size):
+                    batch = assets[i:i + batch_size]
+                    results = await asyncio.gather(*[
+                        _delete_one(asset, idx) for idx, asset in enumerate(batch)
+                    ])
+                    success += sum(results)
+                    failed += len(batch) - sum(results)
+
+            if total == 0:
+                logger.info("No assets to delete")
+                return {"total": 0, "success": 0, "failed": 0, "skipped": True}
+        except Exception as e:
+            logger.error(f"Delete all failed during list: {e}")
+            return {"total": total, "success": success, "failed": failed}
+        finally:
+            await list_service.close()
+
+        logger.info(f"Delete all: total={total}, success={success}, failed={failed}")
+        return {"total": total, "success": success, "failed": failed}
+
+
+# ==================== 下载服务 ====================
+
+class DownloadService(BaseService):
+    """文件下载服务"""
+    
+    def __init__(self, proxy: str = None):
+        super().__init__(proxy)
+        # 创建缓存目录
+        self.base_dir = Path(__file__).parent.parent.parent.parent / "data" / "tmp"
+        self.legacy_base_dir = Path(__file__).parent.parent.parent.parent / "data" / "temp"
+        self.legacy_image_dir = self.legacy_base_dir / "image"
+        self.legacy_video_dir = self.legacy_base_dir / "video"
+        self.image_dir = self.base_dir / "image"
+        self.video_dir = self.base_dir / "video"
+        self.image_dir.mkdir(parents=True, exist_ok=True)
+        self.video_dir.mkdir(parents=True, exist_ok=True)
+        self._cleanup_running = False
+    
+    def _cache_path(self, file_path: str, media_type: str) -> Path:
+        """获取缓存路径"""
+        cache_dir = self.image_dir if media_type == "image" else self.video_dir
+        filename = file_path.lstrip('/').replace('/', '-')
+        return cache_dir / filename
+
+    def _legacy_cache_path(self, file_path: str, media_type: str) -> Path:
+        """Legacy cache path (data/temp)."""
+        cache_dir = self.legacy_image_dir if media_type == "image" else self.legacy_video_dir
+        filename = file_path.lstrip("/").replace("/", "-")
+        return cache_dir / filename
+    
+    async def download(self, file_path: str, token: str, media_type: str = "image") -> Tuple[Optional[Path], str]:
+        """
+        下载文件到本地
+        
+        Raises:
+            UpstreamException: 下载失败
+        """
+        async with _get_assets_semaphore():
+            try:
+                # Be forgiving: callers may pass absolute URLs.
+                if isinstance(file_path, str) and file_path.startswith("http"):
+                    try:
+                        file_path = urlparse(file_path).path
+                    except Exception:
+                        pass
+
+                cache_path = self._cache_path(file_path, media_type)
+                
+                # 如果已缓存
+                if cache_path.exists():
+                    logger.debug(f"Cache hit: {cache_path}")
+                    mime_type = MIME_TYPES.get(cache_path.suffix.lower(), DEFAULT_MIME)
+                    return cache_path, mime_type
+
+                legacy_path = self._legacy_cache_path(file_path, media_type)
+                if legacy_path.exists():
+                    logger.debug(f"Legacy cache hit: {legacy_path}")
+                    mime_type = MIME_TYPES.get(legacy_path.suffix.lower(), DEFAULT_MIME)
+                    return legacy_path, mime_type
+
+                lock_name = f"download_{media_type}_{hashlib.sha1(str(cache_path).encode('utf-8')).hexdigest()[:16]}"
+                async with _file_lock(lock_name, timeout=10):
+                    # Double-check after lock
+                    if cache_path.exists():
+                        logger.debug(f"Cache hit after lock: {cache_path}")
+                        mime_type = MIME_TYPES.get(cache_path.suffix.lower(), DEFAULT_MIME)
+                        return cache_path, mime_type
+
+                    # 下载文件
+                    if not file_path.startswith("/"):
+                        file_path = f"/{file_path}"
+                        
+                    url = f"{DOWNLOAD_API}{file_path}"
+                    headers = self._dl_headers(token, file_path)
+                    
+                    session = await self._get_session()
+                    response = await session.get(
+                        url,
+                        headers=headers,
+                        proxies=self._proxies(),
+                        timeout=self.timeout,
+                        allow_redirects=True,
+                        impersonate=BROWSER,
+                        stream=True,
+                    )
+                    
+                    if response.status_code != 200:
+                        raise UpstreamException(
+                            message=f"Download failed: {response.status_code}",
+                            details={"path": file_path, "status": response.status_code}
+                        )
+                    
+                    # 保存文件（分块写入，避免大文件占用内存）
+                    tmp_path = cache_path.with_suffix(cache_path.suffix + ".tmp")
+                    try:
+                        async with aiofiles.open(tmp_path, "wb") as f:
+                            if hasattr(response, "aiter_content"):
+                                async for chunk in response.aiter_content():
+                                    if chunk:
+                                        await f.write(chunk)
+                            elif hasattr(response, "aiter_bytes"):
+                                async for chunk in response.aiter_bytes():
+                                    if chunk:
+                                        await f.write(chunk)
+                            elif hasattr(response, "aiter_raw"):
+                                async for chunk in response.aiter_raw():
+                                    if chunk:
+                                        await f.write(chunk)
+                            else:
+                                await f.write(response.content)
+                        os.replace(tmp_path, cache_path)
+                    finally:
+                        if tmp_path.exists() and not cache_path.exists():
+                            try:
+                                tmp_path.unlink()
+                            except Exception:
+                                pass
+                    mime_type = response.headers.get('content-type', DEFAULT_MIME).split(';')[0]
+                    
+                    logger.info(f"Download success: {file_path}")
+                    
+                    # 检查缓存限制
+                    asyncio.create_task(self.check_limit())
+                    
+                    return cache_path, mime_type
+            
+            except Exception as e:
+                logger.error(f"Download failed: {file_path} - {e}")
+                if isinstance(e, AppException):
+                    raise e
+                raise UpstreamException(f"Download error: {str(e)}")
+    
+    async def to_base64(
+        self, 
+        file_path: str, 
+        token: str, 
+        media_type: str = "image"
+    ) -> str:
+        """
+        下载文件并转为 base64
+        """
+        try:
+            cache_path, mime_type = await self.download(file_path, token, media_type)
+            
+            if not cache_path or not cache_path.exists():
+                raise AppException("File download returned invalid path")
+            
+            # 使用基础服务的工具方法转换
+            data_uri = self.to_b64(cache_path, mime_type)
+            
+            # 默认保留文件到本地缓存，便于后台“缓存管理”统计与复用；
+            # 如需转为临时模式，可通过 cache.keep_base64_cache=false 关闭保留。
+            keep_cache = get_config("cache.keep_base64_cache", True)
+            if data_uri and not keep_cache:
+                try:
+                    cache_path.unlink()
+                except Exception as e:
+                    logger.warning(f"Delete temp file failed: {e}")
+            
+            return data_uri
+        
+        except Exception as e:
+            logger.error(f"To base64 failed: {file_path} - {e}")
+            if isinstance(e, AppException):
+                raise e
+            raise AppException(f"Base64 conversion failed: {str(e)}")
+
+    def get_stats(self, media_type: str = "image") -> Dict[str, Any]:
+        """获取缓存统计"""
+        cache_dir = self.image_dir if media_type == "image" else self.video_dir
+        if not cache_dir.exists():
+            return {"count": 0, "size_mb": 0.0}
+        
+        # 统计目录下所有文件（有些资产路径可能不带标准后缀名）
+        files = [f for f in cache_dir.glob("*") if f.is_file()]
+        total_size = sum(f.stat().st_size for f in files)
+        
+        return {
+            "count": len(files),
+            "size_mb": round(total_size / 1024 / 1024, 2)
+        }
+
+    def list_files(self, media_type: str = "image", page: int = 1, page_size: int = 1000) -> Dict[str, Any]:
+        """列出本地缓存文件"""
+        cache_dir = self.image_dir if media_type == "image" else self.video_dir
+        if not cache_dir.exists():
+            return {"total": 0, "page": page, "page_size": page_size, "items": []}
+
+        files = [f for f in cache_dir.glob("*") if f.is_file()]
+        items = []
+        for f in files:
+            try:
+                stat = f.stat()
+                items.append({
+                    "name": f.name,
+                    "size_bytes": stat.st_size,
+                    "mtime_ms": int(stat.st_mtime * 1000),
+                })
+            except Exception:
+                continue
+
+        items.sort(key=lambda x: x["mtime_ms"], reverse=True)
+        total = len(items)
+        start = max(0, (page - 1) * page_size)
+        end = start + page_size
+        paged = items[start:end]
+
+        if media_type == "image":
+            for item in paged:
+                item["view_url"] = f"/v1/files/image/{item['name']}"
+        else:
+            preview_map = {}
+            if self.image_dir.exists():
+                for img in self.image_dir.glob("*"):
+                    if img.is_file() and img.suffix.lower() in IMAGE_EXTS:
+                        preview_map.setdefault(img.stem, img.name)
+            for item in paged:
+                item["view_url"] = f"/v1/files/video/{item['name']}"
+                preview_name = preview_map.get(Path(item["name"]).stem)
+                if preview_name:
+                    item["preview_url"] = f"/v1/files/image/{preview_name}"
+
+        return {"total": total, "page": page, "page_size": page_size, "items": paged}
+
+    def delete_file(self, media_type: str, name: str) -> Dict[str, Any]:
+        """删除单个缓存文件"""
+        cache_dir = self.image_dir if media_type == "image" else self.video_dir
+        safe_name = name.replace("/", "-")
+        file_path = cache_dir / safe_name
+        if not file_path.exists():
+            return {"deleted": False}
+        try:
+            file_path.unlink()
+            return {"deleted": True}
+        except Exception:
+            return {"deleted": False}
+    
+    def clear(self, media_type: str = "image") -> Dict[str, Any]:
+        """清空��存"""
+        cache_dir = self.image_dir if media_type == "image" else self.video_dir
+        if not cache_dir.exists():
+            return {"count": 0, "size_mb": 0.0}
+            
+        files = list(cache_dir.glob("*"))
+        total_size = sum(f.stat().st_size for f in files)
+        count = 0
+        
+        for f in files:
+            try:
+                f.unlink()
+                count += 1
+            except Exception as e:
+                logger.error(f"Failed to delete {f}: {e}")
+                
+        return {
+            "count": count,
+            "size_mb": round(total_size / 1024 / 1024, 2)
+        }
+        
+    async def check_limit(self):
+        """检查并清理缓存限制"""
+        if self._cleanup_running:
+            return
+        self._cleanup_running = True
+        try:
+            async with _file_lock("cache_cleanup", timeout=5):
+                if not get_config("cache.enable_auto_clean", True):
+                    return
+
+                limit_mb = get_config("cache.limit_mb", 1024)
+
+                # 统计总大小
+                total_size = 0
+                all_files = []
+                
+                for d in [self.image_dir, self.video_dir]:
+                    if d.exists():
+                        for f in d.glob("*"):
+                            try:
+                                stat = f.stat()
+                                total_size += stat.st_size
+                                all_files.append((f, stat.st_mtime, stat.st_size))
+                            except:
+                                pass
+                
+                current_mb = total_size / 1024 / 1024
+                if current_mb <= limit_mb:
+                    return
+                    
+                # 需要清理
+                logger.info(f"Cache limit exceeded ({current_mb:.2f}MB > {limit_mb}MB), cleaning up...")
+                
+                # 按时间排序
+                all_files.sort(key=lambda x: x[1])
+                
+                deleted_count = 0
+                deleted_size = 0
+                target_mb = limit_mb * 0.8  # 清理到 80%
+                
+                for f, _, size in all_files:
+                    try:
+                        f.unlink()
+                        deleted_count += 1
+                        deleted_size += size
+                        total_size -= size
+                        
+                        if (total_size / 1024 / 1024) <= target_mb:
+                            break
+                    except Exception as e:
+                        logger.error(f"Cleanup failed for {f}: {e}")
+                        
+                logger.info(f"Cache cleanup: deleted {deleted_count} files ({deleted_size/1024/1024:.2f}MB)")
+        finally:
+            self._cleanup_running = False
+
+    def get_public_url(self, file_path: str) -> str:
+        """
+        获取文件的公共访问 URL
+        
+        如果配置了 app_url，则返回自托管 URL，否则返回 Grok 原始 URL
+        """
+        app_url = get_config("app.app_url", "")
+        if not app_url:
+            return f"{DOWNLOAD_API}{file_path if file_path.startswith('/') else '/' + file_path}"
+            
+        if not file_path.startswith("/"):
+            file_path = f"/{file_path}"
+            
+        # 自动添加 /v1/files 前缀
+        return f"{app_url.rstrip('/')}/v1/files{file_path}"
+
+
+__all__ = [
+    "BaseService",
+    "UploadService",
+    "ListService",
+    "DeleteService",
+    "DownloadService",
+]

app/services/grok/chat.py

@@ -0,0 +1,571 @@
+"""
+Grok Chat 服务
+"""
+
+import asyncio
+import uuid
+import orjson
+from typing import Dict, List, Any
+from dataclasses import dataclass
+
+from curl_cffi.requests import AsyncSession
+
+from app.core.logger import logger
+from app.core.config import get_config
+from app.core.exceptions import (
+    AppException, 
+    UpstreamException,
+    ValidationException,
+    ErrorType
+)
+from app.services.grok.statsig import StatsigService
+from app.services.grok.model import ModelService
+from app.services.grok.assets import UploadService
+from app.services.grok.processor import StreamProcessor, CollectProcessor
+from app.services.grok.retry import retry_on_status
+from app.services.token import get_token_manager
+from app.services.request_stats import request_stats
+
+
+CHAT_API = "https://grok.com/rest/app-chat/conversations/new"
+TIMEOUT = 120
+BROWSER = "chrome136"
+
+
+@dataclass
+class ChatRequest:
+    """聊天请求数据"""
+    model: str
+    messages: List[Dict[str, Any]]
+    stream: bool = None
+    think: bool = None
+
+
+class MessageExtractor:
+    """消息内容提取器"""
+    
+    # 需要上传的类型
+    UPLOAD_TYPES = {"image_url", "input_audio", "file"}
+    # 视频模式不支持的类型
+    VIDEO_UNSUPPORTED = {"input_audio", "file"}
+    
+    @staticmethod
+    def extract(messages: List[Dict[str, Any]], is_video: bool = False) -> tuple[str, List[str]]:
+        """
+        从 OpenAI 消息格式提取内容
+        
+        Args:
+            messages: OpenAI 格式消息列表
+            is_video: 是否为视频模型
+            
+        Returns:
+            (text, attachments): 拼接后的文本和需要上传的附件列表
+            
+        Raises:
+            ValueError: 视频模型遇到不支持的内容类型
+        """
+        texts = []
+        attachments = []  # 需要上传的附件 (URL 或 base64)
+
+        # 先抽取每条消息的文本，保留角色信息用于合并
+        extracted: List[Dict[str, str]] = []
+
+        for msg in messages:
+            role = msg.get("role", "")
+            content = msg.get("content", "")
+            parts = []
+
+            # 简单字符串内容
+            if isinstance(content, str):
+                if content.strip():
+                    parts.append(content)
+
+            # 列表格式内容
+            elif isinstance(content, list):
+                for item in content:
+                    item_type = item.get("type", "")
+
+                    # 文本类型
+                    if item_type == "text":
+                        text = item.get("text", "")
+                        if text.strip():
+                            parts.append(text)
+
+                    # 图片类型
+                    elif item_type == "image_url":
+                        image_data = item.get("image_url", {})
+                        url = image_data.get("url", "") if isinstance(image_data, dict) else str(image_data)
+                        if url:
+                            attachments.append(("image", url))
+
+                    # 音频类型
+                    elif item_type == "input_audio":
+                        if is_video:
+                            raise ValueError("视频模型不支持 input_audio 类型")
+                        audio_data = item.get("input_audio", {})
+                        data = audio_data.get("data", "") if isinstance(audio_data, dict) else str(audio_data)
+                        if data:
+                            attachments.append(("audio", data))
+
+                    # 文件类型
+                    elif item_type == "file":
+                        if is_video:
+                            raise ValueError("视频模型不支持 file 类型")
+                        file_data = item.get("file", {})
+                        # file 可能是 URL 或 base64
+                        url = file_data.get("url", "") or file_data.get("data", "")
+                        if isinstance(file_data, str):
+                            url = file_data
+                        if url:
+                            attachments.append(("file", url))
+
+            if parts:
+                extracted.append({"role": role, "text": "\n".join(parts)})
+
+        # 合并文本
+        last_user_index = None
+        for i in range(len(extracted) - 1, -1, -1):
+            if extracted[i]["role"] == "user":
+                last_user_index = i
+                break
+
+        for i, item in enumerate(extracted):
+            role = item["role"] or "user"
+            text = item["text"]
+            if i == last_user_index:
+                texts.append(text)
+            else:
+                texts.append(f"{role}: {text}")
+
+        # 换行拼接文本
+        message = "\n\n".join(texts)
+        return message, attachments
+    
+    @staticmethod
+    def extract_text_only(messages: List[Dict[str, Any]]) -> str:
+        """仅提取文本内容"""
+        text, _ = MessageExtractor.extract(messages, is_video=True)
+        return text
+
+
+class ChatRequestBuilder:
+    """请求构造器"""
+    
+    @staticmethod
+    def build_headers(token: str) -> Dict[str, str]:
+        """构造请求头"""
+        headers = {
+            "Accept": "*/*",
+            "Accept-Encoding": "gzip, deflate, br, zstd",
+            "Accept-Language": "zh-CN,zh;q=0.9",
+            "Baggage": "sentry-environment=production,sentry-release=d6add6fb0460641fd482d767a335ef72b9b6abb8,sentry-public_key=b311e0f2690c81f25e2c4cf6d4f7ce1c",
+            "Cache-Control": "no-cache",
+            "Content-Type": "application/json",
+            "Origin": "https://grok.com",
+            "Pragma": "no-cache",
+            "Priority": "u=1, i",
+            "Referer": "https://grok.com/",
+            "Sec-Ch-Ua": '"Google Chrome";v="136", "Chromium";v="136", "Not(A:Brand";v="24"',
+            "Sec-Ch-Ua-Arch": "arm",
+            "Sec-Ch-Ua-Bitness": "64",
+            "Sec-Ch-Ua-Mobile": "?0",
+            "Sec-Ch-Ua-Model": "",
+            "Sec-Ch-Ua-Platform": '"macOS"',
+            "Sec-Fetch-Dest": "empty",
+            "Sec-Fetch-Mode": "cors",
+            "Sec-Fetch-Site": "same-origin",
+            "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
+        }
+        
+        # Statsig ID
+        headers["x-statsig-id"] = StatsigService.gen_id()
+        headers["x-xai-request-id"] = str(uuid.uuid4())
+        
+        # Cookie
+        token = token[4:] if token.startswith("sso=") else token
+        cf = get_config("grok.cf_clearance", "")
+        headers["Cookie"] = f"sso={token};cf_clearance={cf}" if cf else f"sso={token}"
+        
+        return headers
+    
+    @staticmethod
+    def build_payload(
+        message: str, 
+        model: str, 
+        mode: str, 
+        think: bool = None,
+        file_attachments: List[str] = None,
+        image_attachments: List[str] = None
+    ) -> Dict[str, Any]:
+        """
+        构造请求体
+        
+        Args:
+            message: 消息文本
+            model: 模型名称
+            mode: 模型模式
+            think: 是否开启思考
+            file_attachments: 文件附件 ID 列表
+            image_attachments: 图片附件 URL 列表
+        """
+        temporary = get_config("grok.temporary", True)
+        if think is None:
+            think = get_config("grok.thinking", False)
+
+        # Upstream payload expects image attachments merged into fileAttachments.
+        merged_attachments: List[str] = []
+        if file_attachments:
+            merged_attachments.extend(file_attachments)
+        if image_attachments:
+            merged_attachments.extend(image_attachments)
+        
+        return {
+            "temporary": temporary,
+            "modelName": model,
+            "modelMode": mode,
+            "message": message,
+            "fileAttachments": merged_attachments,
+            "imageAttachments": [],
+            "disableSearch": False,
+            "enableImageGeneration": True,
+            "returnImageBytes": False,
+            "returnRawGrokInXaiRequest": False,
+            "enableImageStreaming": True,
+            "imageGenerationCount": 2,
+            "forceConcise": False,
+            "toolOverrides": {},
+            "enableSideBySide": True,
+            "sendFinalMetadata": True,
+            "isReasoning": False,
+            "disableTextFollowUps": False,
+            "responseMetadata": {
+                "modelConfigOverride": {"modelMap": {}},
+                "requestModelDetails": {"modelId": model}
+            },
+            "disableMemory": False,
+            "forceSideBySide": False,
+            "isAsyncChat": False,
+            "disableSelfHarmShortCircuit": False,
+            "deviceEnvInfo": {
+                "darkModeEnabled": False,
+                "devicePixelRatio": 2,
+                "screenWidth": 2056,
+                "screenHeight": 1329,
+                "viewportWidth": 2056,
+                "viewportHeight": 1083
+            }
+        }
+
+
+# ==================== Grok 服务 ====================
+
+class GrokChatService:
+    """Grok API 调用服务"""
+    
+    def __init__(self, proxy: str = None):
+        self.proxy = proxy or get_config("grok.base_proxy_url", "")
+    
+    async def chat(
+        self,
+        token: str,
+        message: str,
+        model: str = "grok-3",
+        mode: str = "MODEL_MODE_FAST",
+        think: bool = None,
+        stream: bool = None,
+        file_attachments: List[str] = None,
+        image_attachments: List[str] = None
+    ):
+        """
+        发送聊天请求
+        
+        Args:
+            token: 认证 Token
+            message: 消息文本
+            model: Grok 模型名称
+            mode: 模型模式
+            think: 是否开启思考
+            stream: 是否流式
+            file_attachments: 文件附件 ID 列表
+            image_attachments: 图片附件 URL 列表
+        
+        Raises:
+            UpstreamException: 当 Grok API 返回错误且重试耗尽时
+        """
+        if stream is None:
+            stream = get_config("grok.stream", True)
+        
+        headers = ChatRequestBuilder.build_headers(token)
+        payload = ChatRequestBuilder.build_payload(
+            message, model, mode, think, 
+            file_attachments, image_attachments
+        )
+        proxies = {"http": self.proxy, "https": self.proxy} if self.proxy else None
+        timeout = get_config("grok.timeout", TIMEOUT)
+        
+        # 状态码提取器
+        def extract_status(e: Exception) -> int | None:
+            if isinstance(e, UpstreamException) and e.details:
+                return e.details.get("status")
+            return None
+        
+        # 建立连接函数
+        async def establish_connection():
+            """建立连接并返回 response 对象"""
+            session = AsyncSession(impersonate=BROWSER)
+            try:
+                response = await session.post(
+                    CHAT_API,
+                    headers=headers,
+                    data=orjson.dumps(payload),
+                    timeout=timeout,
+                    stream=True,
+                    proxies=proxies
+                )
+                
+                if response.status_code != 200:
+                    try:
+                        content = await response.text()
+                        content = content[:1000] # 限制长度避免日志过大
+                    except:
+                        content = "Unable to read response content"
+
+                    logger.error(
+                        f"Chat failed: {response.status_code}, {content}",
+                        extra={"status": response.status_code, "token": token[:10] + "..."}
+                    )
+                    # 关闭 session 并抛出异常
+                    try:
+                        await session.close()
+                    except:
+                        pass
+                    raise UpstreamException(
+                        message=f"Grok API request failed: {response.status_code}",
+                        details={"status": response.status_code}
+                    )
+                
+                # 返回 session 和 response
+                return session, response
+                
+            except UpstreamException:
+                # 已经处理过的异常，直接抛出
+                raise
+            except Exception as e:
+                # 其他异常，关闭 session 并包装
+                logger.error(f"Chat request error: {e}")
+                try:
+                    await session.close()
+                except:
+                    pass
+                raise UpstreamException(
+                    message=f"Chat connection failed: {str(e)}",
+                    details={"error": str(e)}
+                )
+        
+        # 建立连接
+        session = None
+        response = None
+        try:
+            session, response = await retry_on_status(
+                establish_connection,
+                extract_status=extract_status
+            )
+        except Exception as e:
+            # 记录失败
+            status_code = extract_status(e)
+            if status_code:
+                token_mgr = await get_token_manager()
+                await token_mgr.record_fail(token, status_code, str(e))
+            raise
+        
+        # 流式传输
+        async def stream_response():
+            try:
+                async for line in response.aiter_lines():
+                    yield line
+            finally:
+                if session:
+                    await session.close()
+        
+        return stream_response()
+    
+    async def chat_openai(self, token: str, request: ChatRequest):
+        """OpenAI 兼容接口"""
+        model_info = ModelService.get(request.model)
+        if not model_info:
+            raise ValidationException(f"Unknown model: {request.model}")
+        
+        grok_model = model_info.grok_model
+        mode = model_info.model_mode
+        is_video = model_info.is_video
+        
+        # 提取消息和附件
+        try:
+            message, attachments = MessageExtractor.extract(request.messages, is_video=is_video)
+        except ValueError as e:
+            raise ValidationException(str(e))
+        
+        # 处理附件上传
+        file_ids = []
+        image_ids = []
+        
+        if attachments:
+            upload_service = UploadService()
+            try:
+                for attach_type, attach_data in attachments:
+                    # 获取 ID
+                    file_id, _ = await upload_service.upload(attach_data, token)
+                    
+                    if attach_type == "image":
+                        # 图片 imageAttachments
+                        image_ids.append(file_id)
+                        logger.debug(f"Image uploaded: {file_id}")
+                    else:
+                        # 文件 fileAttachments
+                        file_ids.append(file_id)
+                        logger.debug(f"File uploaded: {file_id}")
+            finally:
+                await upload_service.close()
+        
+        stream = request.stream if request.stream is not None else get_config("grok.stream", True)
+        think = request.think if request.think is not None else get_config("grok.thinking", False)
+        
+        response = await self.chat(
+            token, message, grok_model, mode, think, stream,
+            file_attachments=file_ids,
+            image_attachments=image_ids
+        )
+        
+        return response, stream, request.model
+
+
+# ==================== Chat 业务服务 ====================
+
+class ChatService:
+    """Chat 业务服务"""
+    
+    @staticmethod
+    async def completions(
+        model: str,
+        messages: List[Dict[str, Any]],
+        stream: bool = None,
+        thinking: str = None
+    ):
+        """
+        Chat Completions 入口
+        
+        Args:
+            model: 模型名称
+            messages: 消息列表
+            stream: 是否流式
+            thinking: 思考模式
+            
+        Returns:
+            AsyncGenerator 或 dict
+        """
+        # 获取 token
+        try:
+            token_mgr = await get_token_manager()
+            await token_mgr.reload_if_stale()
+            token = token_mgr.get_token_for_model(model)
+        except Exception as e:
+            logger.error(f"Failed to get token: {e}")
+            try:
+                await request_stats.record_request(model, success=False)
+            except Exception:
+                pass
+            raise AppException(
+                message="Internal service error obtaining token",
+                error_type=ErrorType.SERVER.value,
+                code="internal_error"
+            )
+
+        if not token:
+            try:
+                await request_stats.record_request(model, success=False)
+            except Exception:
+                pass
+            raise AppException(
+                message="No available tokens. Please try again later.",
+                error_type=ErrorType.RATE_LIMIT.value,
+                code="rate_limit_exceeded",
+                status_code=429
+            )
+        
+        # 解析参数
+        think = None
+        if thinking == "enabled":
+            think = True
+        elif thinking == "disabled":
+            think = False
+        
+        is_stream = stream if stream is not None else get_config("grok.stream", True)
+        
+        # 构造请求
+        chat_request = ChatRequest(
+            model=model,
+            messages=messages,
+            stream=is_stream,
+            think=think
+        )
+        
+        # 请求 Grok
+        service = GrokChatService()
+        try:
+            response, _, model_name = await service.chat_openai(token, chat_request)
+        except AppException:
+            try:
+                await request_stats.record_request(model, success=False)
+            except Exception:
+                pass
+            raise
+        except Exception as e:
+            logger.error(f"Chat service error: {e}")
+            try:
+                await request_stats.record_request(model, success=False)
+            except Exception:
+                pass
+            raise UpstreamException(
+                message=f"Service processing failed: {str(e)}",
+                details={"error": str(e)}
+            )
+        
+        # 处理响应
+        if is_stream:
+            processor = StreamProcessor(model_name, token, think).process(response)
+
+            async def _wrapped_stream():
+                completed = False
+                try:
+                    async for chunk in processor:
+                        yield chunk
+                    completed = True
+                finally:
+                    # Only count as "success" when the stream ends naturally.
+                    try:
+                        if completed:
+                            await token_mgr.sync_usage(token, model_name, consume_on_fail=True, is_usage=True)
+                            await request_stats.record_request(model_name, success=True)
+                        else:
+                            await request_stats.record_request(model_name, success=False)
+                    except Exception:
+                        pass
+
+            return _wrapped_stream()
+
+        result = await CollectProcessor(model_name, token).process(response)
+        try:
+            await token_mgr.sync_usage(token, model_name, consume_on_fail=True, is_usage=True)
+            await request_stats.record_request(model_name, success=True)
+        except Exception:
+            pass
+        return result
+
+
+__all__ = [
+    "GrokChatService",
+    "ChatRequest",
+    "ChatRequestBuilder",
+    "MessageExtractor",
+    "ChatService",
+]

app/services/grok/imagine_experimental.py

@@ -0,0 +1,416 @@
+"""
+Experimental imagine/image-edit upstream calls.
+
+This module provides:
+- WebSocket imagine generation (ws/imagine/listen)
+- Experimental image-edit payloads via conversations/new
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+import uuid
+from typing import Any, Awaitable, Callable, Dict, Iterable, List, Optional
+from urllib.parse import urlparse
+
+import orjson
+from curl_cffi.requests import AsyncSession
+
+from app.core.config import get_config
+from app.core.exceptions import UpstreamException
+from app.core.logger import logger
+from app.services.grok.assets import DownloadService
+from app.services.grok.chat import BROWSER, CHAT_API, ChatRequestBuilder
+
+
+IMAGE_METHOD_LEGACY = "legacy"
+IMAGE_METHOD_IMAGINE_WS_EXPERIMENTAL = "imagine_ws_experimental"
+IMAGE_METHODS = {IMAGE_METHOD_LEGACY, IMAGE_METHOD_IMAGINE_WS_EXPERIMENTAL}
+IMAGE_METHOD_ALIASES = {
+    "imagine_ws": IMAGE_METHOD_IMAGINE_WS_EXPERIMENTAL,
+    "experimental": IMAGE_METHOD_IMAGINE_WS_EXPERIMENTAL,
+    "new": IMAGE_METHOD_IMAGINE_WS_EXPERIMENTAL,
+    "new_method": IMAGE_METHOD_IMAGINE_WS_EXPERIMENTAL,
+}
+
+IMAGINE_WS_API = "wss://grok.com/ws/imagine/listen"
+ASSET_API = "https://assets.grok.com"
+TIMEOUT = 120
+
+ProgressCallback = Callable[[int, float], Optional[Awaitable[None] | None]]
+CompletedCallback = Callable[[int, str], Optional[Awaitable[None] | None]]
+
+
+def resolve_image_generation_method(raw: Any) -> str:
+    candidate = str(raw or "").strip().lower()
+    if candidate in IMAGE_METHODS:
+        return candidate
+    mapped = IMAGE_METHOD_ALIASES.get(candidate)
+    if mapped:
+        return mapped
+    return IMAGE_METHOD_LEGACY
+
+
+def _normalize_asset_path(raw_url: str) -> str:
+    raw = str(raw_url or "").strip()
+    if not raw:
+        return "/"
+    if raw.startswith("http://") or raw.startswith("https://"):
+        try:
+            path = urlparse(raw).path or "/"
+        except Exception:
+            path = "/"
+    else:
+        path = raw
+    if not path.startswith("/"):
+        path = f"/{path}"
+    return path
+
+
+class ImagineExperimentalService:
+    def __init__(self, proxy: str | None = None):
+        self.proxy = proxy or get_config("grok.base_proxy_url", "")
+        self.timeout = int(get_config("grok.timeout", TIMEOUT) or TIMEOUT)
+
+    def _proxies(self) -> Optional[dict]:
+        return {"http": self.proxy, "https": self.proxy} if self.proxy else None
+
+    def _headers(self, token: str, referer: str = "https://grok.com/imagine") -> Dict[str, str]:
+        headers = ChatRequestBuilder.build_headers(token)
+        headers["Referer"] = referer
+        headers["Origin"] = "https://grok.com"
+        return headers
+
+    @staticmethod
+    def _build_ws_payload(
+        prompt: str,
+        request_id: str,
+        aspect_ratio: str = "2:3",
+    ) -> Dict[str, Any]:
+        return {
+            "type": "conversation.item.create",
+            "timestamp": int(time.time() * 1000),
+            "item": {
+                "type": "message",
+                "content": [
+                    {
+                        "requestId": request_id,
+                        "text": prompt,
+                        "type": "input_scroll",
+                        "properties": {
+                            "section_count": 0,
+                            "is_kids_mode": False,
+                            "enable_nsfw": True,
+                            "skip_upsampler": False,
+                            "is_initial": False,
+                            "aspect_ratio": aspect_ratio,
+                        },
+                    }
+                ],
+            },
+        }
+
+    @staticmethod
+    def _extract_url(msg: Dict[str, Any]) -> str:
+        for key in ("url", "imageUrl", "image_url"):
+            value = msg.get(key)
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+        return ""
+
+    @staticmethod
+    def _extract_progress(msg: Dict[str, Any]) -> Optional[float]:
+        for key in ("progress", "percentage_complete", "percentageComplete"):
+            value = msg.get(key)
+            if value is None:
+                continue
+            try:
+                pct = float(value)
+                if pct < 0:
+                    pct = 0
+                if pct > 100:
+                    pct = 100
+                return pct
+            except Exception:
+                continue
+        return None
+
+    @staticmethod
+    def _is_completed(msg: Dict[str, Any], progress: Optional[float]) -> bool:
+        status = str(msg.get("current_status") or msg.get("currentStatus") or "").strip().lower()
+        if status in {"completed", "done", "success"}:
+            return True
+        if progress is not None and progress >= 100:
+            return True
+        return False
+
+    async def generate_ws(
+        self,
+        token: str,
+        prompt: str,
+        n: int = 2,
+        aspect_ratio: str = "2:3",
+        progress_cb: Optional[ProgressCallback] = None,
+        completed_cb: Optional[CompletedCallback] = None,
+        timeout: Optional[int] = None,
+    ) -> List[str]:
+        request_id = str(uuid.uuid4())
+        target_count = max(1, int(n or 1))
+        effective_timeout = max(10, int(timeout or self.timeout))
+        payload = self._build_ws_payload(
+            prompt=prompt,
+            request_id=request_id,
+            aspect_ratio=aspect_ratio,
+        )
+
+        session = AsyncSession(impersonate=BROWSER)
+        ws = None
+        started_at = time.monotonic()
+        image_indices: Dict[str, int] = {}
+        final_urls: Dict[str, str] = {}
+
+        try:
+            ws = await session.ws_connect(
+                IMAGINE_WS_API,
+                headers=self._headers(token),
+                timeout=effective_timeout,
+                proxies=self._proxies(),
+                impersonate=BROWSER,
+            )
+            await ws.send_json(payload)
+
+            while time.monotonic() - started_at < effective_timeout:
+                remain = max(1.0, effective_timeout - (time.monotonic() - started_at))
+                try:
+                    msg = await ws.recv_json(timeout=min(5.0, remain))
+                except asyncio.TimeoutError:
+                    continue
+                except Exception as e:
+                    raise UpstreamException(f"Imagine websocket receive failed: {e}") from e
+
+                if not isinstance(msg, dict):
+                    continue
+
+                msg_request_id = str(msg.get("request_id") or msg.get("requestId") or "")
+                if msg_request_id and msg_request_id != request_id:
+                    continue
+
+                msg_type = str(msg.get("type") or "").lower()
+                status = str(msg.get("current_status") or msg.get("currentStatus") or "").lower()
+                if msg_type == "error" or status == "error":
+                    err_code = str(msg.get("err_code") or msg.get("errCode") or "unknown")
+                    err_msg = str(
+                        msg.get("err_message") or msg.get("err_msg") or msg.get("error") or "unknown error"
+                    )
+                    raise UpstreamException(
+                        message=f"Imagine websocket error ({err_code}): {err_msg}",
+                        details={"code": err_code, "message": err_msg},
+                    )
+
+                image_id = str(msg.get("id") or msg.get("imageId") or msg.get("image_id") or "")
+                if not image_id:
+                    image_id = f"image-{len(image_indices)}"
+                if image_id not in image_indices:
+                    image_indices[image_id] = len(image_indices)
+
+                progress = self._extract_progress(msg)
+                if progress is not None and progress_cb is not None:
+                    try:
+                        maybe_coro = progress_cb(image_indices[image_id], progress)
+                        if asyncio.iscoroutine(maybe_coro):
+                            await maybe_coro
+                    except Exception as e:
+                        logger.debug(f"Imagine progress callback failed: {e}")
+
+                image_url = self._extract_url(msg)
+                if image_url and self._is_completed(msg, progress):
+                    is_new = image_id not in final_urls
+                    final_urls.setdefault(image_id, image_url)
+                    if is_new and completed_cb is not None:
+                        try:
+                            maybe_coro = completed_cb(image_indices[image_id], image_url)
+                            if asyncio.iscoroutine(maybe_coro):
+                                await maybe_coro
+                        except Exception as e:
+                            logger.debug(f"Imagine completion callback failed: {e}")
+                    if len(final_urls) >= target_count:
+                        break
+
+            if not final_urls:
+                raise UpstreamException("Imagine websocket returned no completed images")
+
+            return list(final_urls.values())
+        finally:
+            if ws is not None:
+                try:
+                    await ws.close()
+                except Exception:
+                    pass
+            try:
+                await session.close()
+            except Exception:
+                pass
+
+    async def convert_urls(self, token: str, urls: Iterable[str], response_format: str = "b64_json") -> List[str]:
+        mode = str(response_format or "b64_json").strip().lower()
+        out: List[str] = []
+        dl = DownloadService(self.proxy)
+        try:
+            for raw in urls:
+                raw = str(raw or "").strip()
+                if not raw:
+                    continue
+                if mode == "url":
+                    path = _normalize_asset_path(raw)
+                    if path in {"", "/"}:
+                        continue
+                    await dl.download(path, token, "image")
+                    app_url = str(get_config("app.app_url", "") or "").strip()
+                    local_path = f"/v1/files/image{path}"
+                    if app_url:
+                        out.append(f"{app_url.rstrip('/')}{local_path}")
+                    else:
+                        out.append(local_path)
+                    continue
+
+                data_uri = await dl.to_base64(raw, token, "image")
+                if not data_uri:
+                    continue
+                if "," in data_uri:
+                    out.append(data_uri.split(",", 1)[1])
+                else:
+                    out.append(data_uri)
+            return out
+        finally:
+            await dl.close()
+
+    async def convert_url(self, token: str, url: str, response_format: str = "b64_json") -> str:
+        items = await self.convert_urls(token=token, urls=[url], response_format=response_format)
+        return items[0] if items else ""
+
+    @staticmethod
+    def _to_asset_urls(file_uris: List[str]) -> List[str]:
+        out = []
+        for uri in file_uris:
+            value = str(uri or "").strip()
+            if not value:
+                continue
+            if value.startswith("http://") or value.startswith("https://"):
+                out.append(value)
+            else:
+                out.append(f"{ASSET_API}/{value.lstrip('/')}")
+        return out
+
+    @staticmethod
+    def _build_edit_payload(prompt: str, image_urls: List[str], model_name: str) -> Dict[str, Any]:
+        model_map = {
+            "imageEditModel": "imagine",
+            "imageEditModelConfig": {
+                "imageReferences": image_urls,
+            },
+        }
+        payload: Dict[str, Any] = {
+            "temporary": True,
+            "modelName": model_name,
+            "message": prompt,
+            "fileAttachments": [],
+            "imageAttachments": [],
+            "disableSearch": False,
+            "enableImageGeneration": True,
+            "returnImageBytes": False,
+            "returnRawGrokInXaiRequest": False,
+            "enableImageStreaming": True,
+            "imageGenerationCount": 2,
+            "forceConcise": False,
+            "toolOverrides": {"imageGen": True},
+            "enableSideBySide": True,
+            "sendFinalMetadata": True,
+            "isReasoning": False,
+            "disableTextFollowUps": False,
+            "disableMemory": False,
+            "forceSideBySide": False,
+            "isAsyncChat": False,
+            "responseMetadata": {
+                "modelConfigOverride": {
+                    "modelMap": model_map,
+                },
+                "requestModelDetails": {
+                    "modelId": model_name,
+                },
+            },
+        }
+        if model_name == "grok-3":
+            payload["modelMode"] = "MODEL_MODE_FAST"
+        return payload
+
+    async def chat_edit(
+        self,
+        token: str,
+        prompt: str,
+        file_uris: List[str],
+    ):
+        image_urls = self._to_asset_urls(file_uris)
+        if not image_urls:
+            raise UpstreamException("Experimental image edit requires at least one uploaded image")
+
+        headers = self._headers(token, referer="https://grok.com/imagine")
+        proxies = self._proxies()
+        timeout = self.timeout
+
+        payloads = [
+            self._build_edit_payload(prompt, image_urls, "imagine-image-edit"),
+            self._build_edit_payload(prompt, image_urls, "grok-3"),
+        ]
+
+        last_error: Optional[Exception] = None
+        for payload in payloads:
+            session = AsyncSession(impersonate=BROWSER)
+            response = None
+            try:
+                response = await session.post(
+                    CHAT_API,
+                    headers=headers,
+                    data=orjson.dumps(payload),
+                    timeout=timeout,
+                    stream=True,
+                    proxies=proxies,
+                )
+                if response.status_code != 200:
+                    try:
+                        body = await response.text()
+                    except Exception:
+                        body = ""
+                    raise UpstreamException(
+                        message=f"Experimental image edit request failed: {response.status_code}",
+                        details={"status": response.status_code, "body": body[:500]},
+                    )
+
+                async def _stream_response():
+                    try:
+                        async for line in response.aiter_lines():
+                            yield line
+                    finally:
+                        await session.close()
+
+                return _stream_response()
+            except Exception as e:
+                last_error = e
+                try:
+                    await session.close()
+                except Exception:
+                    pass
+                continue
+
+        if isinstance(last_error, Exception):
+            raise last_error
+        raise UpstreamException("Experimental image edit request failed")
+
+
+__all__ = [
+    "ImagineExperimentalService",
+    "IMAGE_METHOD_LEGACY",
+    "IMAGE_METHOD_IMAGINE_WS_EXPERIMENTAL",
+    "IMAGE_METHODS",
+    "resolve_image_generation_method",
+]

app/services/grok/imagine_generation.py

@@ -0,0 +1,137 @@
+"""
+Shared helpers for experimental imagine generation flows.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Awaitable, Callable, List, Optional
+
+from app.core.exceptions import UpstreamException
+from app.core.logger import logger
+from app.services.grok.imagine_experimental import ImagineExperimentalService
+
+
+def resolve_aspect_ratio(size: Optional[str]) -> str:
+    value = str(size or "").strip().lower()
+    if value in {"16:9", "9:16", "1:1", "2:3", "3:2"}:
+        return value
+
+    mapping = {
+        "1024x1024": "1:1",
+        "512x512": "1:1",
+        "1024x576": "16:9",
+        "1280x720": "16:9",
+        "1536x864": "16:9",
+        "576x1024": "9:16",
+        "720x1280": "9:16",
+        "864x1536": "9:16",
+        "1024x1536": "2:3",
+        "1024x1792": "2:3",
+        "512x768": "2:3",
+        "768x1024": "2:3",
+        "1536x1024": "3:2",
+        "1792x1024": "3:2",
+        "768x512": "3:2",
+        "1024x768": "3:2",
+    }
+    return mapping.get(value, "2:3")
+
+
+def is_valid_image_value(value: Any) -> bool:
+    return isinstance(value, str) and bool(value) and value != "error"
+
+
+def dedupe_images(images: List[str]) -> List[str]:
+    out: List[str] = []
+    seen: set[str] = set()
+    for image in images:
+        if not isinstance(image, str):
+            continue
+        if image in seen:
+            continue
+        seen.add(image)
+        out.append(image)
+    return out
+
+
+async def gather_limited(
+    task_factories: List[Callable[[], Awaitable[List[str]]]],
+    max_concurrency: int,
+) -> List[Any]:
+    sem = asyncio.Semaphore(max(1, int(max_concurrency or 1)))
+
+    async def _run(factory: Callable[[], Awaitable[List[str]]]) -> Any:
+        async with sem:
+            return await factory()
+
+    return await asyncio.gather(*[_run(factory) for factory in task_factories], return_exceptions=True)
+
+
+async def call_experimental_generation_once(
+    token: str,
+    prompt: str,
+    response_format: str = "b64_json",
+    n: int = 4,
+    aspect_ratio: str = "2:3",
+) -> List[str]:
+    service = ImagineExperimentalService()
+    raw_urls = await service.generate_ws(
+        token=token,
+        prompt=prompt,
+        n=n,
+        aspect_ratio=aspect_ratio,
+    )
+    return await service.convert_urls(token=token, urls=raw_urls, response_format=response_format)
+
+
+async def collect_experimental_generation_images(
+    token: str,
+    prompt: str,
+    n: int,
+    response_format: str,
+    aspect_ratio: str,
+    concurrency: int,
+) -> List[str]:
+    calls_needed = max(1, (n + 3) // 4)
+    task_factories: List[Callable[[], Awaitable[List[str]]]] = []
+    remain = n
+    for _ in range(calls_needed):
+        target_n = max(1, min(4, remain))
+        remain -= target_n
+        task_factories.append(
+            lambda target_n=target_n: call_experimental_generation_once(
+                token,
+                prompt,
+                response_format=response_format,
+                n=target_n,
+                aspect_ratio=aspect_ratio,
+            )
+        )
+
+    results = await gather_limited(
+        task_factories,
+        max_concurrency=min(calls_needed, max(1, int(concurrency or 1))),
+    )
+    all_images: List[str] = []
+    for result in results:
+        if isinstance(result, Exception):
+            logger.warning(f"Experimental imagine websocket call failed: {result}")
+            continue
+        if isinstance(result, list):
+            all_images.extend(result)
+
+    all_images = dedupe_images(all_images)
+    if not any(is_valid_image_value(item) for item in all_images):
+        raise UpstreamException("Experimental imagine websocket returned no images")
+    return all_images
+
+
+__all__ = [
+    "resolve_aspect_ratio",
+    "is_valid_image_value",
+    "dedupe_images",
+    "gather_limited",
+    "call_experimental_generation_once",
+    "collect_experimental_generation_images",
+]

app/services/grok/media.py

@@ -0,0 +1,512 @@
+"""
+Grok 视频生成服务
+"""
+
+import asyncio
+import uuid
+from typing import AsyncGenerator, Optional
+
+import orjson
+from curl_cffi.requests import AsyncSession
+
+from app.core.logger import logger
+from app.core.config import get_config
+from app.core.exceptions import UpstreamException, AppException, ValidationException, ErrorType
+from app.services.grok.statsig import StatsigService
+from app.services.grok.model import ModelService
+from app.services.token import get_token_manager
+from app.services.grok.processor import VideoStreamProcessor, VideoCollectProcessor
+from app.services.request_stats import request_stats
+
+# API 端点
+CREATE_POST_API = "https://grok.com/rest/media/post/create"
+CHAT_API = "https://grok.com/rest/app-chat/conversations/new"
+
+# 常量
+BROWSER = "chrome136"
+TIMEOUT = 300
+DEFAULT_MAX_CONCURRENT = 50
+_MEDIA_SEMAPHORE = asyncio.Semaphore(DEFAULT_MAX_CONCURRENT)
+_MEDIA_SEM_VALUE = DEFAULT_MAX_CONCURRENT
+
+def _get_media_semaphore() -> asyncio.Semaphore:
+    global _MEDIA_SEMAPHORE, _MEDIA_SEM_VALUE
+    value = get_config("performance.media_max_concurrent", DEFAULT_MAX_CONCURRENT)
+    try:
+        value = int(value)
+    except Exception:
+        value = DEFAULT_MAX_CONCURRENT
+    value = max(1, value)
+    if value != _MEDIA_SEM_VALUE:
+        _MEDIA_SEM_VALUE = value
+        _MEDIA_SEMAPHORE = asyncio.Semaphore(value)
+    return _MEDIA_SEMAPHORE
+
+
+class VideoService:
+    """视频生成服务"""
+    
+    def __init__(self, proxy: str = None):
+        self.proxy = proxy or get_config("grok.base_proxy_url", "")
+        self.timeout = get_config("grok.timeout", TIMEOUT)
+    
+    def _build_headers(self, token: str, referer: str = "https://grok.com/imagine") -> dict:
+        """构建请求头"""
+        headers = {
+            "Accept": "*/*",
+            "Accept-Encoding": "gzip, deflate, br, zstd",
+            "Accept-Language": "zh-CN,zh;q=0.9",
+            "Baggage": "sentry-environment=production,sentry-release=d6add6fb0460641fd482d767a335ef72b9b6abb8,sentry-public_key=b311e0f2690c81f25e2c4cf6d4f7ce1c",
+            "Cache-Control": "no-cache",
+            "Content-Type": "application/json",
+            "Origin": "https://grok.com",
+            "Pragma": "no-cache",
+            "Priority": "u=1, i",
+            "Referer": referer,
+            "Sec-Ch-Ua": '"Google Chrome";v="136", "Chromium";v="136", "Not(A:Brand";v="24"',
+            "Sec-Ch-Ua-Arch": "arm",
+            "Sec-Ch-Ua-Bitness": "64",
+            "Sec-Ch-Ua-Mobile": "?0",
+            "Sec-Ch-Ua-Model": "",
+            "Sec-Ch-Ua-Platform": '"macOS"',
+            "Sec-Fetch-Dest": "empty",
+            "Sec-Fetch-Mode": "cors",
+            "Sec-Fetch-Site": "same-origin",
+            "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
+        }
+        
+        # Statsig ID
+        headers["x-statsig-id"] = StatsigService.gen_id()
+        headers["x-xai-request-id"] = str(uuid.uuid4())
+        
+        # Cookie
+        token = token[4:] if token.startswith("sso=") else token
+        cf = get_config("grok.cf_clearance", "")
+        headers["Cookie"] = f"sso={token};cf_clearance={cf}" if cf else f"sso={token}"
+        
+        return headers
+    
+    def _build_proxies(self) -> Optional[dict]:
+        """构建代理"""
+        return {"http": self.proxy, "https": self.proxy} if self.proxy else None
+    
+    async def create_post(self, token: str, prompt: str, media_type: str = "MEDIA_POST_TYPE_VIDEO", media_url: str = None) -> str:
+        """
+        创建媒体帖子
+        
+        Args:
+            token: 认证 Token
+            prompt: 提示词（视频生成用）
+            media_type: 媒体类型 (MEDIA_POST_TYPE_VIDEO 或 MEDIA_POST_TYPE_IMAGE)
+            media_url: 媒体 URL（图片模式用）
+            
+        Returns:
+            post ID
+        """
+        try:
+            headers = self._build_headers(token)
+            
+            # 根据类型构建不同的载荷
+            if media_type == "MEDIA_POST_TYPE_IMAGE" and media_url:
+                payload = {
+                    "mediaType": media_type,
+                    "mediaUrl": media_url
+                }
+            else:
+                payload = {
+                    "mediaType": media_type,
+                    "prompt": prompt
+                }
+            
+            async with AsyncSession() as session:
+                response = await session.post(
+                    CREATE_POST_API,
+                    headers=headers,
+                    json=payload,
+                    impersonate=BROWSER,
+                    timeout=30,
+                    proxies=self._build_proxies()
+                )
+            
+            if response.status_code != 200:
+                logger.error(f"Create post failed: {response.status_code}")
+                raise UpstreamException(f"Failed to create post: {response.status_code}")
+            
+            data = response.json()
+            post_id = data.get("post", {}).get("id", "")
+            
+            if not post_id:
+                raise UpstreamException("No post ID in response")
+            
+            logger.info(f"Media post created: {post_id} (type={media_type})")
+            return post_id
+            
+        except Exception as e:
+            logger.error(f"Create post error: {e}")
+            if isinstance(e, AppException):
+                raise e
+            raise UpstreamException(f"Create post error: {str(e)}")
+    
+    async def create_image_post(self, token: str, image_url: str) -> str:
+        """
+        创建图片帖子
+        
+        Args:
+            token: 认证 Token
+            image_url: 完整的图片 URL (https://assets.grok.com/...)
+            
+        Returns:
+            post ID
+        """
+        return await self.create_post(
+            token, 
+            prompt="", 
+            media_type="MEDIA_POST_TYPE_IMAGE", 
+            media_url=image_url
+        )
+    
+    def _build_payload(
+        self,
+        prompt: str,
+        post_id: str,
+        aspect_ratio: str = "3:2",
+        video_length: int = 6,
+        resolution: str = "SD",
+        preset: str = "normal"
+    ) -> dict:
+        """构建视频生成载荷"""
+        mode_flag = "--mode=custom"
+        if preset == "fun":
+            mode_flag = "--mode=extremely-crazy"
+        elif preset == "normal":
+            mode_flag = "--mode=normal"
+        elif preset == "spicy":
+            mode_flag = "--mode=extremely-spicy-or-crazy"
+            
+        full_prompt = f"{prompt} {mode_flag}"
+        
+        return {
+            "temporary": True,
+            "modelName": "grok-3",
+            "message": full_prompt,
+            "toolOverrides": {"videoGen": True},
+            "enableSideBySide": True,
+            "responseMetadata": {
+                "experiments": [],
+                "modelConfigOverride": {
+                    "modelMap": {
+                        "videoGenModelConfig": {
+                            "parentPostId": post_id,
+                            "aspectRatio": aspect_ratio,
+                            "videoLength": video_length,
+                            "videoResolution": resolution
+                        }
+                    }
+                }
+            }
+        }
+    
+    async def generate(
+        self,
+        token: str,
+        prompt: str,
+        aspect_ratio: str = "3:2",
+        video_length: int = 6,
+        resolution: str = "SD",
+        stream: bool = True,
+        preset: str = "normal"
+    ) -> AsyncGenerator[bytes, None]:
+        """
+        生成视频
+        
+        Args:
+            token: 认证 Token
+            prompt: 视频描述
+            aspect_ratio: 宽高比
+            video_length: 视频时长
+            resolution: 分辨率
+            stream: 是否流式
+            preset: 预设
+            
+        Returns:
+            AsyncGenerator，流式传输
+            
+        Raises:
+            UpstreamException: 连接失败时
+        """
+        async with _get_media_semaphore():
+            session = None
+            try:
+                # Step 1: 创建帖子
+                post_id = await self.create_post(token, prompt)
+                
+                # Step 2: 建立连接
+                headers = self._build_headers(token)
+                payload = self._build_payload(prompt, post_id, aspect_ratio, video_length, resolution, preset)
+                
+                session = AsyncSession(impersonate=BROWSER)
+                response = await session.post(
+                    CHAT_API,
+                    headers=headers,
+                    data=orjson.dumps(payload),
+                    timeout=self.timeout,
+                    stream=True,
+                    proxies=self._build_proxies()
+                )
+                
+                if response.status_code != 200:
+                    logger.error(f"Video generation failed: {response.status_code}")
+                    try:
+                        await session.close()
+                    except:
+                        pass
+                    raise UpstreamException(
+                        message=f"Video generation failed: {response.status_code}",
+                        details={"status": response.status_code}
+                    )
+                
+                # Step 3: 流式传输
+                async def stream_response():
+                    try:
+                        async for line in response.aiter_lines():
+                            yield line
+                    finally:
+                        if session:
+                            await session.close()
+                
+                return stream_response()
+                    
+            except Exception as e:
+                if session:
+                    try:
+                        await session.close()
+                    except:
+                        pass
+                logger.error(f"Video generation error: {e}")
+                if isinstance(e, AppException):
+                    raise e
+                raise UpstreamException(f"Video generation error: {str(e)}")
+    
+    async def generate_from_image(
+        self,
+        token: str,
+        prompt: str,
+        image_url: str,
+        aspect_ratio: str = "3:2",
+        video_length: int = 6,
+        resolution: str = "SD",
+        stream: bool = True,
+        preset: str = "normal"
+    ) -> AsyncGenerator[bytes, None]:
+        """
+        从图片生成视频
+        
+        Args:
+            token: 认证 Token
+            prompt: 视频描述
+            image_url: 图片 URL
+            aspect_ratio: 宽高比
+            video_length: 视频时长
+            resolution: 分辨率
+            stream: 是否流式
+            preset: 预设
+            
+        Returns:
+            AsyncGenerator，流式传输
+        """
+        async with _get_media_semaphore():
+            session = None
+            try:
+                # Step 1: 创建帖子
+                post_id = await self.create_image_post(token, image_url)
+                
+                # Step 2: 建立连接
+                headers = self._build_headers(token)
+                payload = self._build_payload(prompt, post_id, aspect_ratio, video_length, resolution, preset)
+                
+                session = AsyncSession(impersonate=BROWSER)
+                response = await session.post(
+                    CHAT_API,
+                    headers=headers,
+                    data=orjson.dumps(payload),
+                    timeout=self.timeout,
+                    stream=True,
+                    proxies=self._build_proxies()
+                )
+                
+                if response.status_code != 200:
+                    logger.error(f"Video from image failed: {response.status_code}")
+                    try:
+                        await session.close()
+                    except:
+                        pass
+                    raise UpstreamException(
+                        message=f"Video from image failed: {response.status_code}",
+                        details={"status": response.status_code}
+                    )
+                
+                # Step 3: 流式传输
+                async def stream_response():
+                    try:
+                        async for line in response.aiter_lines():
+                            yield line
+                    finally:
+                        if session:
+                            await session.close()
+                
+                return stream_response()
+                    
+            except Exception as e:
+                if session:
+                    try:
+                        await session.close()
+                    except:
+                        pass
+                logger.error(f"Video from image error: {e}")
+                if isinstance(e, AppException):
+                    raise e
+                raise UpstreamException(f"Video from image error: {str(e)}")
+    
+    @staticmethod
+    async def completions(
+        model: str,
+        messages: list,
+        stream: bool = None,
+        thinking: str = None,
+        aspect_ratio: str = "3:2",
+        video_length: int = 6,
+        resolution: str = "SD",
+        preset: str = "normal"
+    ):
+        """
+        视频生成入口
+        
+        Args:
+            model: 模型名称
+            messages: 消息列表
+            stream: 是否流式
+            thinking: 思考模式
+            aspect_ratio: 宽高比
+            video_length: 视频时长
+            resolution: 分辨率
+            preset: 预设模式
+            
+        Returns:
+            AsyncGenerator (流式) 或 dict (非流式)
+        """
+        # 获取 token
+        try:
+            token_mgr = await get_token_manager()
+            await token_mgr.reload_if_stale()
+            token = token_mgr.get_token_for_model(model)
+        except Exception as e:
+            logger.error(f"Failed to get token: {e}")
+            try:
+                await request_stats.record_request(model, success=False)
+            except Exception:
+                pass
+            raise AppException(
+                message="Internal service error obtaining token",
+                error_type=ErrorType.SERVER.value,
+                code="internal_error"
+            )
+        
+        if not token:
+            try:
+                await request_stats.record_request(model, success=False)
+            except Exception:
+                pass
+            raise AppException(
+                message="No available tokens. Please try again later.",
+                error_type=ErrorType.RATE_LIMIT.value,
+                code="rate_limit_exceeded",
+                status_code=429
+        )
+        
+        # 解析参数
+        think = None
+        if thinking == "enabled":
+            think = True
+        elif thinking == "disabled":
+            think = False
+        
+        is_stream = stream if stream is not None else get_config("grok.stream", True)
+        
+        # 提取内容
+        from app.services.grok.chat import MessageExtractor
+        from app.services.grok.assets import UploadService
+        
+        try:
+            prompt, attachments = MessageExtractor.extract(messages, is_video=True)
+        except ValueError as e:
+            raise ValidationException(str(e))
+        
+        # 处理图片附件
+        image_url = None
+        if attachments:
+            upload_service = UploadService()
+            try:
+                for attach_type, attach_data in attachments:
+                    if attach_type == "image":
+                        # 上传图片
+                        _, file_uri = await upload_service.upload(attach_data, token)
+                        image_url = f"https://assets.grok.com/{file_uri}"
+                        logger.info(f"Image uploaded for video: {image_url}")
+                        break  # 视频模型只使用第一张图片
+            finally:
+                await upload_service.close()
+        
+        # 生成视频
+        service = VideoService()
+        
+        try:
+            # 图片转视频
+            if image_url:
+                response = await service.generate_from_image(
+                    token, prompt, image_url,
+                    aspect_ratio, video_length, resolution, stream, preset
+                )
+            else:
+                response = await service.generate(
+                    token, prompt,
+                    aspect_ratio, video_length, resolution, stream, preset
+                )
+        except Exception:
+            try:
+                await request_stats.record_request(model, success=False)
+            except Exception:
+                pass
+            raise
+        
+        # 处理响应
+        if is_stream:
+            processor = VideoStreamProcessor(model, token, think).process(response)
+
+            async def _wrapped_stream():
+                completed = False
+                try:
+                    async for chunk in processor:
+                        yield chunk
+                    completed = True
+                finally:
+                    try:
+                        if completed:
+                            await token_mgr.sync_usage(token, model, consume_on_fail=True, is_usage=True)
+                            await request_stats.record_request(model, success=True)
+                        else:
+                            await request_stats.record_request(model, success=False)
+                    except Exception:
+                        pass
+
+            return _wrapped_stream()
+
+        result = await VideoCollectProcessor(model, token).process(response)
+        try:
+            await token_mgr.sync_usage(token, model, consume_on_fail=True, is_usage=True)
+            await request_stats.record_request(model, success=True)
+        except Exception:
+            pass
+        return result
+
+
+__all__ = ["VideoService"]

app/services/grok/model.py

@@ -0,0 +1,226 @@
+"""
+Grok 模型管理服务
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional, Tuple
+from pydantic import BaseModel, Field
+
+from app.core.exceptions import ValidationException
+
+
+class Tier(str, Enum):
+    """模型档位"""
+    BASIC = "basic"
+    SUPER = "super"
+
+
+class Cost(str, Enum):
+    """计费类型"""
+    LOW = "low"
+    HIGH = "high"
+
+
+class ModelInfo(BaseModel):
+    """模型信息"""
+    model_id: str
+    grok_model: str
+    rate_limit_model: str
+    model_mode: str
+    tier: Tier = Field(default=Tier.BASIC)
+    cost: Cost = Field(default=Cost.LOW)
+    display_name: str
+    description: str = ""
+    is_video: bool = False
+    is_image: bool = False
+
+
+class ModelService:
+    """模型管理服务"""
+    
+    MODELS = [
+        ModelInfo(
+            model_id="grok-3",
+            grok_model="grok-3",
+            rate_limit_model="grok-3",
+            model_mode="MODEL_MODE_GROK_3",
+            cost=Cost.LOW,
+            display_name="Grok 3"
+        ),
+        ModelInfo(
+            model_id="grok-3-mini",
+            grok_model="grok-3",
+            rate_limit_model="grok-3",
+            model_mode="MODEL_MODE_GROK_3_MINI_THINKING",
+            cost=Cost.LOW,
+            display_name="Grok 3 Mini"
+        ),
+        ModelInfo(
+            model_id="grok-3-thinking",
+            grok_model="grok-3",
+            rate_limit_model="grok-3",
+            model_mode="MODEL_MODE_GROK_3_THINKING",
+            cost=Cost.LOW,
+            display_name="Grok 3 Thinking"
+        ),
+        ModelInfo(
+            model_id="grok-4",
+            grok_model="grok-4",
+            rate_limit_model="grok-4",
+            model_mode="MODEL_MODE_GROK_4",
+            cost=Cost.LOW,
+            display_name="Grok 4"
+        ),
+        ModelInfo(
+            model_id="grok-4-mini",
+            grok_model="grok-4-mini",
+            rate_limit_model="grok-4-mini",
+            model_mode="MODEL_MODE_GROK_4_MINI_THINKING",
+            cost=Cost.LOW,
+            display_name="Grok 4 Mini"
+        ),
+        ModelInfo(
+            model_id="grok-4-thinking",
+            grok_model="grok-4",
+            rate_limit_model="grok-4",
+            model_mode="MODEL_MODE_GROK_4_THINKING",
+            cost=Cost.LOW,
+            display_name="Grok 4 Thinking"
+        ),
+        ModelInfo(
+            model_id="grok-4-heavy",
+            grok_model="grok-4",
+            rate_limit_model="grok-4-heavy",
+            model_mode="MODEL_MODE_HEAVY",
+            cost=Cost.HIGH,
+            tier=Tier.SUPER,
+            display_name="Grok 4 Heavy"
+        ),
+        ModelInfo(
+            model_id="grok-4.1-mini",
+            grok_model="grok-4-1-thinking-1129",
+            rate_limit_model="grok-4-1-thinking-1129",
+            model_mode="MODEL_MODE_GROK_4_1_MINI_THINKING",
+            cost=Cost.LOW,
+            display_name="Grok 4.1 Mini"
+        ),
+        ModelInfo(
+            model_id="grok-4.1-fast",
+            grok_model="grok-4-1-thinking-1129",
+            rate_limit_model="grok-4-1-thinking-1129",
+            model_mode="MODEL_MODE_FAST",
+            cost=Cost.LOW,
+            display_name="Grok 4.1 Fast"
+        ),
+        ModelInfo(
+            model_id="grok-4.1-expert",
+            grok_model="grok-4-1-thinking-1129",
+            rate_limit_model="grok-4-1-thinking-1129",
+            model_mode="MODEL_MODE_EXPERT",
+            cost=Cost.HIGH,
+            display_name="Grok 4.1 Expert"
+        ),
+        ModelInfo(
+            model_id="grok-4.1-thinking",
+            grok_model="grok-4-1-thinking-1129",
+            rate_limit_model="grok-4-1-thinking-1129",
+            model_mode="MODEL_MODE_GROK_4_1_THINKING",
+            cost=Cost.HIGH, 
+            display_name="Grok 4.1 Thinking"
+        ),
+        ModelInfo(
+            model_id="grok-4.20-beta",
+            grok_model="grok-420",
+            rate_limit_model="grok-420",
+            model_mode="MODEL_MODE_GROK_420",
+            cost=Cost.LOW,
+            display_name="Grok 4.20 Beta"
+        ),
+        ModelInfo(
+            model_id="grok-imagine-1.0",
+            grok_model="grok-3",
+            rate_limit_model="grok-3",
+            model_mode="MODEL_MODE_FAST",
+            cost=Cost.HIGH,
+            display_name="Grok Image",
+            description="Image generation model",
+            is_image=True
+        ),
+        ModelInfo(
+            model_id="grok-imagine-1.0-edit",
+            grok_model="imagine-image-edit",
+            rate_limit_model="grok-3",
+            model_mode="MODEL_MODE_FAST",
+            cost=Cost.HIGH,
+            display_name="Grok Image Edit",
+            description="Image edit model",
+            is_image=True
+        ),
+        ModelInfo(
+            model_id="grok-imagine-1.0-video",
+            grok_model="grok-3",
+            rate_limit_model="grok-3",
+            model_mode="MODEL_MODE_FAST",
+            cost=Cost.HIGH,
+            display_name="Grok Video",
+            description="Video generation model",
+            is_video=True
+        ),
+    ]
+    
+    _map = {m.model_id: m for m in MODELS}
+    
+    @classmethod
+    def get(cls, model_id: str) -> Optional[ModelInfo]:
+        """获取模型信息"""
+        return cls._map.get(model_id)
+    
+    @classmethod
+    def list(cls) -> list[ModelInfo]:
+        """获取所有模型"""
+        return list(cls._map.values())
+    
+    @classmethod
+    def valid(cls, model_id: str) -> bool:
+        """模型是否有效"""
+        return model_id in cls._map
+
+    @classmethod
+    def to_grok(cls, model_id: str) -> Tuple[str, str]:
+        """转换为 Grok 参数"""
+        model = cls.get(model_id)
+        if not model:
+            raise ValidationException(f"Invalid model ID: {model_id}")
+        return model.grok_model, model.model_mode
+
+    @classmethod
+    def rate_limit_model_for(cls, model_id: str) -> str:
+        """用于 /rest/rate-limits 的 modelName 映射。"""
+        model = cls.get(model_id)
+        return model.rate_limit_model if model else model_id
+
+    @classmethod
+    def is_heavy_bucket_model(cls, model_id: str) -> bool:
+        """是否使用 heavy 配额桶（目前仅 grok-4-heavy）。"""
+        return model_id == "grok-4-heavy"
+
+    @classmethod
+    def pool_for_model(cls, model_id: str) -> str:
+        """根据模型选择 Token 池"""
+        model = cls.get(model_id)
+        if model and model.tier == Tier.SUPER:
+            return "ssoSuper"
+        return "ssoBasic"
+
+    @classmethod
+    def pool_candidates_for_model(cls, model_id: str) -> list[str]:
+        """按优先级返回可用 Token 池列表。"""
+        model = cls.get(model_id)
+        if model and model.tier == Tier.SUPER:
+            return ["ssoSuper"]
+        return ["ssoBasic", "ssoSuper"]
+
+
+__all__ = ["ModelService"]

app/services/grok/processor.py

@@ -0,0 +1,596 @@
+"""
+OpenAI 响应格式处理器
+"""
+import time
+import uuid
+import random
+import html
+import orjson
+from typing import Any, AsyncGenerator, Optional, AsyncIterable, List
+
+from app.core.config import get_config
+from app.core.logger import logger
+from app.services.grok.assets import DownloadService
+
+
+ASSET_URL = "https://assets.grok.com/"
+
+
+def _build_video_poster_preview(video_url: str, thumbnail_url: str = "") -> str:
+    """将 <video> 替换为可点击的 Poster 预览图（用于前端展示）"""
+    safe_video = html.escape(video_url or "", quote=True)
+    safe_thumb = html.escape(thumbnail_url or "", quote=True)
+
+    if not safe_video:
+        return ""
+
+    if not safe_thumb:
+        return f'<a href="{safe_video}" target="_blank" rel="noopener noreferrer">{safe_video}</a>'
+
+    return f'''<a href="{safe_video}" target="_blank" rel="noopener noreferrer" style="display:inline-block;position:relative;max-width:100%;text-decoration:none;">
+  <img src="{safe_thumb}" alt="video" style="max-width:100%;height:auto;border-radius:12px;display:block;" />
+  <span style="position:absolute;inset:0;display:flex;align-items:center;justify-content:center;">
+    <span style="width:64px;height:64px;border-radius:9999px;background:rgba(0,0,0,.55);display:flex;align-items:center;justify-content:center;">
+      <span style="width:0;height:0;border-top:12px solid transparent;border-bottom:12px solid transparent;border-left:18px solid #fff;margin-left:4px;"></span>
+    </span>
+  </span>
+</a>'''
+
+
+class BaseProcessor:
+    """基础处理器"""
+    
+    def __init__(self, model: str, token: str = ""):
+        self.model = model
+        self.token = token
+        self.created = int(time.time())
+        self.app_url = get_config("app.app_url", "")
+        self._dl_service: Optional[DownloadService] = None
+
+    def _get_dl(self) -> DownloadService:
+        """获取下载服务实例（复用）"""
+        if self._dl_service is None:
+            self._dl_service = DownloadService()
+        return self._dl_service
+
+    async def close(self):
+        """释放下载服务资源"""
+        if self._dl_service:
+            await self._dl_service.close()
+            self._dl_service = None
+
+    async def process_url(self, path: str, media_type: str = "image") -> str:
+        """处理资产 URL"""
+        # 处理可能的绝对路径
+        if path.startswith("http"):
+            from urllib.parse import urlparse
+            path = urlparse(path).path
+            
+        if not path.startswith("/"):
+            path = f"/{path}"
+
+        # Invalid root path is not a displayable image URL.
+        if path in {"", "/"}:
+            return ""
+
+        # Always materialize to local cache endpoint so callers don't rely on
+        # direct assets.grok.com access (often blocked without upstream cookies).
+        dl_service = self._get_dl()
+        await dl_service.download(path, self.token, media_type)
+        local_path = f"/v1/files/{media_type}{path}"
+        if self.app_url:
+            return f"{self.app_url.rstrip('/')}{local_path}"
+        return local_path
+            
+    def _sse(self, content: str = "", role: str = None, finish: str = None) -> str:
+        """构建 SSE 响应 (StreamProcessor 通用)"""
+        if not hasattr(self, 'response_id'):
+            self.response_id = None
+        if not hasattr(self, 'fingerprint'):
+            self.fingerprint = ""
+            
+        delta = {}
+        if role:
+            delta["role"] = role
+            delta["content"] = ""
+        elif content:
+            delta["content"] = content
+        
+        chunk = {
+            "id": self.response_id or f"chatcmpl-{uuid.uuid4().hex[:24]}",
+            "object": "chat.completion.chunk",
+            "created": self.created,
+            "model": self.model,
+            "system_fingerprint": self.fingerprint if hasattr(self, 'fingerprint') else "",
+            "choices": [{"index": 0, "delta": delta, "logprobs": None, "finish_reason": finish}]
+        }
+        return f"data: {orjson.dumps(chunk).decode()}\n\n"
+
+
+class StreamProcessor(BaseProcessor):
+    """流式响应处理器"""
+    
+    def __init__(self, model: str, token: str = "", think: bool = None):
+        super().__init__(model, token)
+        self.response_id: Optional[str] = None
+        self.fingerprint: str = ""
+        self.think_opened: bool = False
+        self.role_sent: bool = False
+        self.filter_tags = get_config("grok.filter_tags", [])
+        self.image_format = get_config("app.image_format", "url")
+        
+        if think is None:
+            self.show_think = get_config("grok.thinking", False)
+        else:
+            self.show_think = think
+    
+    async def process(self, response: AsyncIterable[bytes]) -> AsyncGenerator[str, None]:
+        """处理流式响应"""
+        try:
+            async for line in response:
+                if not line:
+                    continue
+                try:
+                    data = orjson.loads(line)
+                except orjson.JSONDecodeError:
+                    continue
+                
+                resp = data.get("result", {}).get("response", {})
+                
+                # 元数据
+                if (llm := resp.get("llmInfo")) and not self.fingerprint:
+                    self.fingerprint = llm.get("modelHash", "")
+                if rid := resp.get("responseId"):
+                    self.response_id = rid
+                
+                # 首次发送 role
+                if not self.role_sent:
+                    yield self._sse(role="assistant")
+                    self.role_sent = True
+                
+                # 图像生成进度
+                if img := resp.get("streamingImageGenerationResponse"):
+                    if self.show_think:
+                        if not self.think_opened:
+                            yield self._sse("<think>\n")
+                            self.think_opened = True
+                        idx = img.get('imageIndex', 0) + 1
+                        progress = img.get('progress', 0)
+                        yield self._sse(f"正在生成第{idx}张图片中，当前进度{progress}%\n")
+                    continue
+                
+                # modelResponse
+                if mr := resp.get("modelResponse"):
+                    if self.think_opened and self.show_think:
+                        if msg := mr.get("message"):
+                            yield self._sse(msg + "\n")
+                        yield self._sse("</think>\n")
+                        self.think_opened = False
+                    
+                    # 处理生成的图片
+                    for url in mr.get("generatedImageUrls", []):
+                        parts = url.split("/")
+                        img_id = parts[-2] if len(parts) >= 2 else "image"
+                        
+                        if self.image_format == "base64":
+                            dl_service = self._get_dl()
+                            base64_data = await dl_service.to_base64(url, self.token, "image")
+                            if base64_data:
+                                yield self._sse(f"![{img_id}]({base64_data})\n")
+                            else:
+                                final_url = await self.process_url(url, "image")
+                                yield self._sse(f"![{img_id}]({final_url})\n")
+                        else:
+                            final_url = await self.process_url(url, "image")
+                            yield self._sse(f"![{img_id}]({final_url})\n")
+                    
+                    if (meta := mr.get("metadata", {})).get("llm_info", {}).get("modelHash"):
+                        self.fingerprint = meta["llm_info"]["modelHash"]
+                    continue
+                
+                # 普通 token
+                if (token := resp.get("token")) is not None:
+                    if token and not (self.filter_tags and any(t in token for t in self.filter_tags)):
+                        yield self._sse(token)
+                        
+            if self.think_opened:
+                yield self._sse("</think>\n")
+            yield self._sse(finish="stop")
+            yield "data: [DONE]\n\n"
+        except Exception as e:
+            logger.error(f"Stream processing error: {e}", extra={"model": self.model})
+            raise
+        finally:
+            await self.close()
+
+
+class CollectProcessor(BaseProcessor):
+    """非流式响应处理器"""
+    
+    def __init__(self, model: str, token: str = ""):
+        super().__init__(model, token)
+        self.image_format = get_config("app.image_format", "url")
+    
+    async def process(self, response: AsyncIterable[bytes]) -> dict[str, Any]:
+        """处理并收集完整响应"""
+        response_id = ""
+        fingerprint = ""
+        content = ""
+        
+        try:
+            async for line in response:
+                if not line:
+                    continue
+                try:
+                    data = orjson.loads(line)
+                except orjson.JSONDecodeError:
+                    continue
+                
+                resp = data.get("result", {}).get("response", {})
+                
+                if (llm := resp.get("llmInfo")) and not fingerprint:
+                    fingerprint = llm.get("modelHash", "")
+                
+                if mr := resp.get("modelResponse"):
+                    response_id = mr.get("responseId", "")
+                    content = mr.get("message", "")
+                    
+                    if urls := mr.get("generatedImageUrls"):
+                        content += "\n"
+                        for url in urls:
+                            parts = url.split("/")
+                            img_id = parts[-2] if len(parts) >= 2 else "image"
+                            
+                            if self.image_format == "base64":
+                                dl_service = self._get_dl()
+                                base64_data = await dl_service.to_base64(url, self.token, "image")
+                                if base64_data:
+                                    content += f"![{img_id}]({base64_data})\n"
+                                else:
+                                    final_url = await self.process_url(url, "image")
+                                    content += f"![{img_id}]({final_url})\n"
+                            else:
+                                final_url = await self.process_url(url, "image")
+                                content += f"![{img_id}]({final_url})\n"
+                    
+                    if (meta := mr.get("metadata", {})).get("llm_info", {}).get("modelHash"):
+                        fingerprint = meta["llm_info"]["modelHash"]
+                            
+        except Exception as e:
+            logger.error(f"Collect processing error: {e}", extra={"model": self.model})
+        finally:
+            await self.close()
+        
+        return {
+            "id": response_id,
+            "object": "chat.completion",
+            "created": self.created,
+            "model": self.model,
+            "system_fingerprint": fingerprint,
+            "choices": [{
+                "index": 0,
+                "message": {"role": "assistant", "content": content, "refusal": None, "annotations": []},
+                "finish_reason": "stop"
+            }],
+            "usage": {
+                "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0,
+                "prompt_tokens_details": {"cached_tokens": 0, "text_tokens": 0, "audio_tokens": 0, "image_tokens": 0},
+                "completion_tokens_details": {"text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 0}
+            }
+        }
+
+
+class VideoStreamProcessor(BaseProcessor):
+    """视频流式响应处理器"""
+    
+    def __init__(self, model: str, token: str = "", think: bool = None):
+        super().__init__(model, token)
+        self.response_id: Optional[str] = None
+        self.think_opened: bool = False
+        self.role_sent: bool = False
+        self.video_format = get_config("app.video_format", "url")
+        
+        if think is None:
+            self.show_think = get_config("grok.thinking", False)
+        else:
+            self.show_think = think
+    
+    def _build_video_html(self, video_url: str, thumbnail_url: str = "") -> str:
+        """构建视频 HTML 标签"""
+        if get_config("grok.video_poster_preview", False):
+            return _build_video_poster_preview(video_url, thumbnail_url)
+        poster_attr = f' poster="{thumbnail_url}"' if thumbnail_url else ""
+        return f'''<video id="video" controls="" preload="none"{poster_attr}>
+  <source id="mp4" src="{video_url}" type="video/mp4">
+</video>'''
+    
+    async def process(self, response: AsyncIterable[bytes]) -> AsyncGenerator[str, None]:
+        """处理视频流式响应"""
+        try:
+            async for line in response:
+                if not line:
+                    continue
+                try:
+                    data = orjson.loads(line)
+                except orjson.JSONDecodeError:
+                    continue
+                
+                resp = data.get("result", {}).get("response", {})
+                
+                if rid := resp.get("responseId"):
+                    self.response_id = rid
+                
+                # 首次发送 role
+                if not self.role_sent:
+                    yield self._sse(role="assistant")
+                    self.role_sent = True
+                
+                # 视频生成进度
+                if video_resp := resp.get("streamingVideoGenerationResponse"):
+                    progress = video_resp.get("progress", 0)
+                    
+                    if self.show_think:
+                        if not self.think_opened:
+                            yield self._sse("<think>\n")
+                            self.think_opened = True
+                        yield self._sse(f"正在生成视频中，当前进度{progress}%\n")
+                    
+                    if progress == 100:
+                        video_url = video_resp.get("videoUrl", "")
+                        thumbnail_url = video_resp.get("thumbnailImageUrl", "")
+                        
+                        if self.think_opened and self.show_think:
+                            yield self._sse("</think>\n")
+                            self.think_opened = False
+                        
+                        if video_url:
+                            final_video_url = await self.process_url(video_url, "video")
+                            final_thumbnail_url = ""
+                            if thumbnail_url:
+                                final_thumbnail_url = await self.process_url(thumbnail_url, "image")
+                            
+                            video_html = self._build_video_html(final_video_url, final_thumbnail_url)
+                            yield self._sse(video_html)
+                            
+                            logger.info(f"Video generated: {video_url}")
+                    continue
+                        
+            if self.think_opened:
+                yield self._sse("</think>\n")
+            yield self._sse(finish="stop")
+            yield "data: [DONE]\n\n"
+        except Exception as e:
+            logger.error(f"Video stream processing error: {e}", extra={"model": self.model})
+        finally:
+            await self.close()
+
+
+class VideoCollectProcessor(BaseProcessor):
+    """视频非流式响应处理器"""
+    
+    def __init__(self, model: str, token: str = ""):
+        super().__init__(model, token)
+        self.video_format = get_config("app.video_format", "url")
+    
+    def _build_video_html(self, video_url: str, thumbnail_url: str = "") -> str:
+        if get_config("grok.video_poster_preview", False):
+            return _build_video_poster_preview(video_url, thumbnail_url)
+        poster_attr = f' poster="{thumbnail_url}"' if thumbnail_url else ""
+        return f'''<video id="video" controls="" preload="none"{poster_attr}>
+  <source id="mp4" src="{video_url}" type="video/mp4">
+</video>'''
+    
+    async def process(self, response: AsyncIterable[bytes]) -> dict[str, Any]:
+        """处理并收集视频响应"""
+        response_id = ""
+        content = ""
+        
+        try:
+            async for line in response:
+                if not line:
+                    continue
+                try:
+                    data = orjson.loads(line)
+                except orjson.JSONDecodeError:
+                    continue
+                
+                resp = data.get("result", {}).get("response", {})
+                
+                if video_resp := resp.get("streamingVideoGenerationResponse"):
+                    if video_resp.get("progress") == 100:
+                        response_id = resp.get("responseId", "")
+                        video_url = video_resp.get("videoUrl", "")
+                        thumbnail_url = video_resp.get("thumbnailImageUrl", "")
+                        
+                        if video_url:
+                            final_video_url = await self.process_url(video_url, "video")
+                            final_thumbnail_url = ""
+                            if thumbnail_url:
+                                final_thumbnail_url = await self.process_url(thumbnail_url, "image")
+                            
+                            content = self._build_video_html(final_video_url, final_thumbnail_url)
+                            logger.info(f"Video generated: {video_url}")
+                            
+        except Exception as e:
+            logger.error(f"Video collect processing error: {e}", extra={"model": self.model})
+        finally:
+            await self.close()
+        
+        return {
+            "id": response_id,
+            "object": "chat.completion",
+            "created": self.created,
+            "model": self.model,
+            "choices": [{
+                "index": 0,
+                "message": {"role": "assistant", "content": content, "refusal": None},
+                "finish_reason": "stop"
+            }],
+            "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
+        }
+
+
+class ImageStreamProcessor(BaseProcessor):
+    """图片生成流式响应处理器"""
+    
+    def __init__(
+        self,
+        model: str,
+        token: str = "",
+        n: int = 1,
+        response_format: str = "b64_json",
+    ):
+        super().__init__(model, token)
+        self.partial_index = 0
+        self.n = n
+        self.target_index = random.randint(0, 1) if n == 1 else None
+        self.response_format = (response_format or "b64_json").lower()
+        if self.response_format == "url":
+            self.response_field = "url"
+        elif self.response_format == "base64":
+            self.response_field = "base64"
+        else:
+            self.response_field = "b64_json"
+    
+    def _sse(self, event: str, data: dict) -> str:
+        """构建 SSE 响应 (覆盖基类)"""
+        return f"event: {event}\ndata: {orjson.dumps(data).decode()}\n\n"
+    
+    async def process(self, response: AsyncIterable[bytes]) -> AsyncGenerator[str, None]:
+        """处理流式响应"""
+        final_images = []
+        
+        try:
+            async for line in response:
+                if not line:
+                    continue
+                try:
+                    data = orjson.loads(line)
+                except orjson.JSONDecodeError:
+                    continue
+                
+                resp = data.get("result", {}).get("response", {})
+                
+                # 图片生成进度
+                if img := resp.get("streamingImageGenerationResponse"):
+                    image_index = img.get("imageIndex", 0)
+                    progress = img.get("progress", 0)
+                    
+                    if self.n == 1 and image_index != self.target_index:
+                        continue
+                    
+                    out_index = 0 if self.n == 1 else image_index
+                    
+                    yield self._sse("image_generation.partial_image", {
+                        "type": "image_generation.partial_image",
+                        self.response_field: "",
+                        "index": out_index,
+                        "progress": progress
+                    })
+                    continue
+                
+                # modelResponse
+                if mr := resp.get("modelResponse"):
+                    if urls := mr.get("generatedImageUrls"):
+                        for url in urls:
+                            if self.response_format == "url":
+                                processed = await self.process_url(url, "image")
+                                if processed:
+                                    final_images.append(processed)
+                                continue
+                            dl_service = self._get_dl()
+                            base64_data = await dl_service.to_base64(url, self.token, "image")
+                            if base64_data:
+                                if "," in base64_data:
+                                    b64 = base64_data.split(",", 1)[1]
+                                else:
+                                    b64 = base64_data
+                                final_images.append(b64)
+                    continue
+                    
+            for index, b64 in enumerate(final_images):
+                if self.n == 1:
+                    if index != self.target_index:
+                        continue
+                    out_index = 0
+                else:
+                    out_index = index
+                
+                yield self._sse("image_generation.completed", {
+                    "type": "image_generation.completed",
+                    self.response_field: b64,
+                    "index": out_index,
+                    "usage": {
+                        "total_tokens": 50,
+                        "input_tokens": 25,
+                        "output_tokens": 25,
+                        "input_tokens_details": {"text_tokens": 5, "image_tokens": 20}
+                    }
+                })
+        except Exception as e:
+            logger.error(f"Image stream processing error: {e}")
+            raise
+        finally:
+            await self.close()
+
+
+class ImageCollectProcessor(BaseProcessor):
+    """图片生成非流式响应处理器"""
+    
+    def __init__(
+        self,
+        model: str,
+        token: str = "",
+        response_format: str = "b64_json",
+    ):
+        super().__init__(model, token)
+        self.response_format = (response_format or "b64_json").lower()
+    
+    async def process(self, response: AsyncIterable[bytes]) -> List[str]:
+        """处理并收集图片"""
+        images = []
+        
+        try:
+            async for line in response:
+                if not line:
+                    continue
+                try:
+                    data = orjson.loads(line)
+                except orjson.JSONDecodeError:
+                    continue
+                
+                resp = data.get("result", {}).get("response", {})
+                
+                if mr := resp.get("modelResponse"):
+                    if urls := mr.get("generatedImageUrls"):
+                        for url in urls:
+                            if self.response_format == "url":
+                                processed = await self.process_url(url, "image")
+                                if processed:
+                                    images.append(processed)
+                                continue
+                            dl_service = self._get_dl()
+                            base64_data = await dl_service.to_base64(url, self.token, "image")
+                            if base64_data:
+                                if "," in base64_data:
+                                    b64 = base64_data.split(",", 1)[1]
+                                else:
+                                    b64 = base64_data
+                                images.append(b64)
+                                
+        except Exception as e:
+            logger.error(f"Image collect processing error: {e}")
+        finally:
+            await self.close()
+        
+        return images
+
+
+__all__ = [
+    "StreamProcessor",
+    "CollectProcessor",
+    "VideoStreamProcessor",
+    "VideoCollectProcessor",
+    "ImageStreamProcessor",
+    "ImageCollectProcessor",
+]

app/services/grok/retry.py

@@ -0,0 +1,178 @@
+"""
+Grok API 重试工具
+
+提供可配置的重试机制，支持:
+- 可配置的重试次数
+- 可配置的重试状态码
+- 仅记录最后一次失败
+"""
+
+import asyncio
+from typing import Callable, Any, Optional, List
+from functools import wraps
+
+from app.core.logger import logger
+from app.core.config import get_config
+from app.core.exceptions import UpstreamException
+
+
+class RetryConfig:
+    """重试配置"""
+    
+    @staticmethod
+    def get_max_retry() -> int:
+        """获取最大重试次数"""
+        return get_config("grok.max_retry", 1)
+    
+    @staticmethod
+    def get_retry_codes() -> List[int]:
+        """获取可重试的状态码"""
+        return get_config("grok.retry_status_codes", [401, 429, 403])
+
+
+class RetryContext:
+    """重试上下文"""
+    
+    def __init__(self):
+        self.attempt = 0
+        self.max_retry = RetryConfig.get_max_retry()
+        self.retry_codes = RetryConfig.get_retry_codes()
+        self.last_error = None
+        self.last_status = None
+    
+    def should_retry(self, status_code: int) -> bool:
+        """判断是否重试"""
+        return (
+            self.attempt < self.max_retry and 
+            status_code in self.retry_codes
+        )
+    
+    def record_error(self, status_code: int, error: Exception):
+        """记录错误信息"""
+        self.last_status = status_code
+        self.last_error = error
+        self.attempt += 1
+
+
+async def retry_on_status(
+    func: Callable,
+    *args,
+    extract_status: Callable[[Exception], Optional[int]] = None,
+    on_retry: Callable[[int, int, Exception], None] = None,
+    **kwargs
+) -> Any:
+    """
+    通用重试函数
+    
+    Args:
+        func: 重试的异步函数
+        *args: 函数参数
+        extract_status: 异常提取状态码的函数
+        on_retry: 重试时的回调函数
+        **kwargs: 函数关键字参数
+        
+    Returns:
+        函数执行结果
+        
+    Raises:
+        最后一次失败的异常
+    """
+    ctx = RetryContext()
+    
+    # 状态码提取器
+    if extract_status is None:
+        def extract_status(e: Exception) -> Optional[int]:
+            if isinstance(e, UpstreamException):
+                return e.details.get("status") if e.details else None
+            return None
+    
+    while ctx.attempt <= ctx.max_retry:
+        try:
+            result = await func(*args, **kwargs)
+            
+            # 记录日志
+            if ctx.attempt > 0:
+                logger.info(
+                    f"Retry succeeded after {ctx.attempt} attempts"
+                )
+            
+            return result
+            
+        except Exception as e:
+            # 提取状态码
+            status_code = extract_status(e)
+            
+            if status_code is None:
+                # 错误无法识别
+                logger.error(f"Non-retryable error: {e}")
+                raise
+            
+            # 记录错误
+            ctx.record_error(status_code, e)
+            
+            # 判断是否重试
+            if ctx.should_retry(status_code):
+                delay = 0.5 * (ctx.attempt + 1)  # 渐进延迟
+                logger.warning(
+                    f"Retry {ctx.attempt}/{ctx.max_retry} for status {status_code}, "
+                    f"waiting {delay}s"
+                )
+                
+                # 回调
+                if on_retry:
+                    on_retry(ctx.attempt, status_code, e)
+                
+                await asyncio.sleep(delay)
+                continue
+            else:
+                # 不可重试或重试次数耗尽
+                if status_code in ctx.retry_codes:
+                    # 打印当前尝试次数（包括最后一次）
+                    logger.warning(
+                        f"Retry {ctx.attempt}/{ctx.max_retry} for status {status_code}, failed"
+                    )
+                    logger.error(
+                        f"Retry exhausted after {ctx.max_retry} attempts, "
+                        f"last status: {status_code}"
+                    )
+                else:
+                    logger.error(
+                        f"Non-retryable status code: {status_code}"
+                    )
+                
+                # 抛出最后一次的错误
+                raise
+
+
+def with_retry(
+    extract_status: Callable[[Exception], Optional[int]] = None,
+    on_retry: Callable[[int, int, Exception], None] = None
+):
+    """
+    重试装饰器
+    
+    Usage:
+        @with_retry()
+        async def my_api_call():
+            ...
+    """
+    def decorator(func: Callable):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            return await retry_on_status(
+                func,
+                *args,
+                extract_status=extract_status,
+                on_retry=on_retry,
+                **kwargs
+            )
+        return wrapper
+    return decorator
+
+
+__all__ = [
+    "RetryConfig",
+    "RetryContext",
+    "retry_on_status",
+    "with_retry",
+]

app/services/grok/statsig.py

@@ -0,0 +1,46 @@
+"""
+Statsig ID 生成服务
+"""
+
+import base64
+import random
+import string
+
+from app.core.config import get_config
+
+
+class StatsigService:
+    """Statsig ID 生成服务"""
+    
+    @staticmethod
+    def _rand(length: int, alphanumeric: bool = False) -> str:
+        """生成随机字符串"""
+        chars = string.ascii_lowercase + string.digits if alphanumeric else string.ascii_lowercase
+        return "".join(random.choices(chars, k=length))
+    
+    @staticmethod
+    def gen_id() -> str:
+        """
+        生成 Statsig ID
+        
+        Returns:
+            Base64 编码的 ID
+        """
+        # 读取配置
+        dynamic = get_config("grok.dynamic_statsig", True)
+        
+        if not dynamic:
+            return "ZTpUeXBlRXJyb3I6IENhbm5vdCByZWFkIHByb3BlcnRpZXMgb2YgdW5kZWZpbmVkIChyZWFkaW5nICdjaGlsZE5vZGVzJyk="
+        
+        # 随机格式
+        if random.choice([True, False]):
+            rand = StatsigService._rand(5, alphanumeric=True)
+            message = f"e:TypeError: Cannot read properties of null (reading 'children['{rand}']')"
+        else:
+            rand = StatsigService._rand(10)
+            message = f"e:TypeError: Cannot read properties of undefined (reading '{rand}')"
+        
+        return base64.b64encode(message.encode()).decode()
+
+
+__all__ = ["StatsigService"]

app/services/grok/usage.py

@@ -0,0 +1,162 @@
+"""
+Grok 用量服务
+"""
+
+import asyncio
+import uuid
+from typing import Dict
+
+import orjson
+from curl_cffi.requests import AsyncSession
+
+from app.core.logger import logger
+from app.core.config import get_config
+from app.core.exceptions import UpstreamException, AppException
+from app.services.grok.statsig import StatsigService
+from app.services.grok.retry import retry_on_status
+
+
+LIMITS_API = "https://grok.com/rest/rate-limits"
+BROWSER = "chrome136"
+TIMEOUT = 10
+DEFAULT_MAX_CONCURRENT = 25
+_USAGE_SEMAPHORE = asyncio.Semaphore(DEFAULT_MAX_CONCURRENT)
+_USAGE_SEM_VALUE = DEFAULT_MAX_CONCURRENT
+
+def _get_usage_semaphore() -> asyncio.Semaphore:
+    global _USAGE_SEMAPHORE, _USAGE_SEM_VALUE
+    value = get_config("performance.usage_max_concurrent", DEFAULT_MAX_CONCURRENT)
+    try:
+        value = int(value)
+    except Exception:
+        value = DEFAULT_MAX_CONCURRENT
+    value = max(1, value)
+    if value != _USAGE_SEM_VALUE:
+        _USAGE_SEM_VALUE = value
+        _USAGE_SEMAPHORE = asyncio.Semaphore(value)
+    return _USAGE_SEMAPHORE
+
+
+class UsageService:
+    """用量查询服务"""
+    
+    def __init__(self, proxy: str = None):
+        self.proxy = proxy or get_config("grok.base_proxy_url", "")
+        self.timeout = get_config("grok.timeout", TIMEOUT)
+    
+    def _build_headers(self, token: str) -> dict:
+        """构建请求头"""
+        headers = {
+            "Accept": "*/*",
+            "Accept-Encoding": "gzip, deflate, br, zstd",
+            "Accept-Language": "zh-CN,zh;q=0.9",
+            "Baggage": "sentry-environment=production,sentry-release=d6add6fb0460641fd482d767a335ef72b9b6abb8,sentry-public_key=b311e0f2690c81f25e2c4cf6d4f7ce1c",
+            "Cache-Control": "no-cache",
+            "Content-Type": "application/json",
+            "Origin": "https://grok.com",
+            "Pragma": "no-cache",
+            "Priority": "u=1, i",
+            "Referer": "https://grok.com/",
+            "Sec-Ch-Ua": '"Google Chrome";v="136", "Chromium";v="136", "Not(A:Brand";v="24"',
+            "Sec-Ch-Ua-Arch": "arm",
+            "Sec-Ch-Ua-Bitness": "64",
+            "Sec-Ch-Ua-Mobile": "?0",
+            "Sec-Ch-Ua-Model": "",
+            "Sec-Ch-Ua-Platform": '"macOS"',
+            "Sec-Fetch-Dest": "empty",
+            "Sec-Fetch-Mode": "cors",
+            "Sec-Fetch-Site": "same-origin",
+            "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36",
+        }
+        
+        # Statsig ID
+        headers["x-statsig-id"] = StatsigService.gen_id()
+        headers["x-xai-request-id"] = str(uuid.uuid4())
+        
+        # Cookie
+        token = token[4:] if token.startswith("sso=") else token
+        cf = get_config("grok.cf_clearance", "")
+        headers["Cookie"] = f"sso={token};cf_clearance={cf}" if cf else f"sso={token}"
+        
+        return headers
+    
+    def _build_proxies(self) -> dict:
+        """构建代理配置"""
+        return {"http": self.proxy, "https": self.proxy} if self.proxy else None
+    
+    async def get(self, token: str, model_name: str = "grok-4-1-thinking-1129") -> Dict:
+        """
+        获取速率限制信息
+        
+        Args:
+            token: 认证 Token
+            model_name: 模型名称
+            
+        Returns:
+            响应数据
+            
+        Raises:
+            UpstreamException: 当获取失败且重试耗尽时
+        """
+        async with _get_usage_semaphore():
+            # 定义状态码提取器
+            def extract_status(e: Exception) -> int | None:
+                if isinstance(e, UpstreamException) and e.details:
+                    return e.details.get("status")
+                return None
+            
+            # 定义实际的请求函数
+            async def do_request():
+                try:
+                    headers = self._build_headers(token)
+                    payload = {
+                        "requestKind": "DEFAULT",
+                        "modelName": model_name
+                    }
+                    
+                    async with AsyncSession() as session:
+                        response = await session.post(
+                            LIMITS_API,
+                            headers=headers,
+                            json=payload,
+                            impersonate=BROWSER,
+                            timeout=self.timeout,
+                            proxies=self._build_proxies()
+                        )
+                    
+                    if response.status_code == 200:
+                        data = response.json()
+                        remaining = data.get('remainingTokens', 0)
+                        logger.info(f"Usage: quota {remaining} remaining")
+                        return data
+                    
+                    logger.error(f"Usage failed: {response.status_code}")
+
+                    raise UpstreamException(
+                        message=f"Failed to get usage stats: {response.status_code}",
+                        details={"status": response.status_code}
+                    )
+                    
+                except Exception as e:
+                    if isinstance(e, UpstreamException):
+                        raise
+                    logger.error(f"Usage error: {e}")
+                    raise UpstreamException(
+                        message=f"Usage service error: {str(e)}",
+                        details={"error": str(e)}
+                    )
+            
+            # 带重试的执行
+            try:
+                result = await retry_on_status(
+                    do_request,
+                    extract_status=extract_status
+                )
+                return result
+                
+            except Exception as e:
+                # 最后一次失败已经被记录
+                raise
+
+
+__all__ = ["UsageService"]

app/services/quota.py

@@ -0,0 +1,70 @@
+"""
+API Key daily quota enforcement (local/docker runtime)
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Dict
+
+from app.core.config import get_config
+from app.core.exceptions import AppException, ErrorType
+from app.services.api_keys import api_key_manager
+from app.services.grok.model import ModelService
+
+
+async def enforce_daily_quota(
+    api_key: Optional[str],
+    model: str,
+    *,
+    image_count: Optional[int] = None,
+) -> None:
+    """
+    Enforce per-day quotas for a non-admin API key.
+
+    - chat/heavy/video: count by request (1)
+    - image: count by generated images
+      - chat endpoint + image model: charge 2 images per request
+      - image endpoint: charge `image_count` (n)
+    - heavy: consumes both heavy + chat buckets
+    """
+
+    token = str(api_key or "").strip()
+    if not token:
+        return
+
+    global_key = str(get_config("app.api_key", "") or "").strip()
+    if global_key and token == global_key:
+        return
+
+    model_info = ModelService.get(model)
+    incs: Dict[str, int] = {}
+    bucket_name = "chat"
+
+    if model == "grok-4-heavy":
+        incs = {"heavy_used": 1, "chat_used": 1}
+        bucket_name = "heavy/chat"
+    elif model_info and model_info.is_video:
+        incs = {"video_used": 1}
+        bucket_name = "video"
+    elif model_info and model_info.is_image:
+        # grok image model via chat endpoint: upstream usually returns up to 2 images
+        incs = {"image_used": max(1, int(image_count or 2))}
+        bucket_name = "image"
+    else:
+        incs = {"chat_used": 1}
+        bucket_name = "chat"
+
+    ok = await api_key_manager.consume_daily_usage(token, incs)
+    if ok:
+        return
+
+    raise AppException(
+        message=f"Daily quota exceeded: {bucket_name}",
+        error_type=ErrorType.RATE_LIMIT.value,
+        code="daily_quota_exceeded",
+        status_code=429,
+    )
+
+
+__all__ = ["enforce_daily_quota"]
+

app/services/register/__init__.py

@@ -0,0 +1,5 @@
+"""Auto registration services."""
+
+from app.services.register.manager import get_auto_register_manager, AutoRegisterManager
+
+__all__ = ["AutoRegisterManager", "get_auto_register_manager"]

app/services/register/account_settings_refresh.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Iterable, Any
+
+from app.core.config import get_config
+from app.core.logger import logger
+from app.services.register.services import (
+    UserAgreementService,
+    BirthDateService,
+    NsfwSettingsService,
+)
+from app.services.token.manager import TokenManager, get_token_manager
+
+
+DEFAULT_NSFW_REFRESH_CONCURRENCY = 10
+DEFAULT_NSFW_REFRESH_RETRIES = 3
+DEFAULT_IMPERSONATE = "chrome120"
+
+
+def _extract_cookie_value(cookie_str: str, name: str) -> str | None:
+    needle = f"{name}="
+    if needle not in cookie_str:
+        return None
+    for part in cookie_str.split(";"):
+        part = part.strip()
+        if part.startswith(needle):
+            value = part[len(needle):].strip()
+            return value or None
+    return None
+
+
+def parse_sso_pair(raw_token: str) -> tuple[str, str]:
+    raw = str(raw_token or "").strip()
+    if not raw:
+        return "", ""
+
+    if ";" in raw:
+        sso = _extract_cookie_value(raw, "sso") or ""
+        sso_rw = _extract_cookie_value(raw, "sso-rw") or sso
+        return sso.strip(), sso_rw.strip()
+
+    sso = raw[4:].strip() if raw.startswith("sso=") else raw
+    sso_rw = sso
+    return sso, sso_rw
+
+
+def normalize_sso_token(raw_token: str) -> str:
+    sso, _ = parse_sso_pair(raw_token)
+    return sso
+
+
+def _coerce_concurrency(value: Any, default: int = DEFAULT_NSFW_REFRESH_CONCURRENCY) -> int:
+    try:
+        n = int(value)
+    except Exception:
+        n = default
+    return max(1, n)
+
+
+def _coerce_retries(value: Any, default: int = DEFAULT_NSFW_REFRESH_RETRIES) -> int:
+    try:
+        n = int(value)
+    except Exception:
+        n = default
+    return max(0, n)
+
+
+def _format_step_error(result: dict, fallback: str = "unknown error") -> str:
+    if not isinstance(result, dict):
+        return fallback
+
+    text = str(result.get("error") or "").strip()
+    if text:
+        return text
+
+    status_code = result.get("status_code")
+    if status_code is not None:
+        return f"HTTP {status_code}"
+
+    grpc_status = result.get("grpc_status")
+    if grpc_status is not None:
+        return f"gRPC {grpc_status}"
+
+    response_text = str(result.get("response_text") or "").strip()
+    if response_text:
+        return response_text
+
+    return fallback
+
+
+class AccountSettingsRefreshService:
+    def __init__(self, token_manager: TokenManager, cf_clearance: str = "") -> None:
+        self.token_manager = token_manager
+        self.cf_clearance = (cf_clearance or "").strip()
+
+    def _apply_once(self, raw_token: str) -> tuple[bool, str, str]:
+        sso, sso_rw = parse_sso_pair(raw_token)
+        if not sso:
+            return False, "parse", "missing sso"
+        if not sso_rw:
+            sso_rw = sso
+
+        user_service = UserAgreementService(cf_clearance=self.cf_clearance)
+        birth_service = BirthDateService(cf_clearance=self.cf_clearance)
+        nsfw_service = NsfwSettingsService(cf_clearance=self.cf_clearance)
+
+        tos_result = user_service.accept_tos_version(
+            sso=sso,
+            sso_rw=sso_rw,
+            impersonate=DEFAULT_IMPERSONATE,
+        )
+        if not tos_result.get("ok"):
+            return False, "tos", _format_step_error(tos_result, "accept_tos failed")
+
+        birth_result = birth_service.set_birth_date(
+            sso=sso,
+            sso_rw=sso_rw,
+            impersonate=DEFAULT_IMPERSONATE,
+        )
+        if not birth_result.get("ok"):
+            return False, "birth", _format_step_error(birth_result, "set_birth_date failed")
+
+        nsfw_result = nsfw_service.enable_nsfw(
+            sso=sso,
+            sso_rw=sso_rw,
+            impersonate=DEFAULT_IMPERSONATE,
+        )
+        if not nsfw_result.get("ok"):
+            return False, "nsfw", _format_step_error(nsfw_result, "enable_nsfw failed")
+
+        return True, "", ""
+
+    async def refresh_tokens(
+        self,
+        tokens: Iterable[str],
+        concurrency: int = DEFAULT_NSFW_REFRESH_CONCURRENCY,
+        retries: int = DEFAULT_NSFW_REFRESH_RETRIES,
+    ) -> dict[str, Any]:
+        resolved_concurrency = _coerce_concurrency(concurrency)
+        resolved_retries = _coerce_retries(retries)
+
+        unique_tokens: list[str] = []
+        seen: set[str] = set()
+        for token in tokens:
+            normalized = normalize_sso_token(str(token or "").strip())
+            if not normalized or normalized in seen:
+                continue
+            seen.add(normalized)
+            unique_tokens.append(normalized)
+
+        if not unique_tokens:
+            return {
+                "summary": {"total": 0, "success": 0, "failed": 0, "invalidated": 0},
+                "failed": [],
+            }
+
+        semaphore = asyncio.Semaphore(resolved_concurrency)
+
+        async def _run_one(token: str) -> dict[str, Any]:
+            max_attempts = resolved_retries + 1
+            last_step = "unknown"
+            last_error = "unknown error"
+
+            async with semaphore:
+                for attempt in range(1, max_attempts + 1):
+                    try:
+                        ok, step, error = await asyncio.to_thread(self._apply_once, token)
+                    except Exception as exc:
+                        ok, step, error = False, "exception", str(exc)
+
+                    if ok:
+                        updated = await self.token_manager.mark_token_account_settings_success(
+                            token,
+                            save=False,
+                        )
+                        if not updated:
+                            logger.warning(
+                                "Account settings refresh succeeded but token not found: {}...",
+                                token[:10],
+                            )
+                        return {
+                            "token": token,
+                            "ok": True,
+                            "attempts": attempt,
+                        }
+
+                    last_step = step or "unknown"
+                    last_error = error or "unknown error"
+
+                reason = (
+                    f"account_settings_refresh_failed step={last_step} "
+                    f"attempts={max_attempts} error={last_error}"
+                )
+                invalidated = await self.token_manager.set_token_invalid(
+                    token,
+                    reason=reason,
+                    save=False,
+                )
+                return {
+                    "token": token,
+                    "ok": False,
+                    "attempts": max_attempts,
+                    "step": last_step,
+                    "error": last_error,
+                    "invalidated": bool(invalidated),
+                }
+
+        results = await asyncio.gather(*[_run_one(token) for token in unique_tokens])
+
+        try:
+            await self.token_manager.commit()
+        except Exception as exc:
+            logger.warning("Account settings refresh commit failed: {}", exc)
+
+        success = sum(1 for item in results if item.get("ok"))
+        failed_items = [item for item in results if not item.get("ok")]
+        invalidated = sum(1 for item in failed_items if item.get("invalidated"))
+
+        summary = {
+            "total": len(unique_tokens),
+            "success": success,
+            "failed": len(failed_items),
+            "invalidated": invalidated,
+        }
+
+        return {"summary": summary, "failed": failed_items}
+
+
+async def refresh_account_settings_for_tokens(
+    tokens: Iterable[str],
+    concurrency: int | None = None,
+    retries: int | None = None,
+) -> dict[str, Any]:
+    resolved_concurrency = _coerce_concurrency(
+        concurrency if concurrency is not None else get_config(
+            "token.nsfw_refresh_concurrency",
+            DEFAULT_NSFW_REFRESH_CONCURRENCY,
+        ),
+        default=DEFAULT_NSFW_REFRESH_CONCURRENCY,
+    )
+    resolved_retries = _coerce_retries(
+        retries if retries is not None else get_config(
+            "token.nsfw_refresh_retries",
+            DEFAULT_NSFW_REFRESH_RETRIES,
+        ),
+        default=DEFAULT_NSFW_REFRESH_RETRIES,
+    )
+
+    token_manager = await get_token_manager()
+    cf_clearance = str(get_config("grok.cf_clearance", "") or "").strip()
+    service = AccountSettingsRefreshService(token_manager, cf_clearance=cf_clearance)
+    return await service.refresh_tokens(
+        tokens=tokens,
+        concurrency=resolved_concurrency,
+        retries=resolved_retries,
+    )
+
+
+__all__ = [
+    "AccountSettingsRefreshService",
+    "parse_sso_pair",
+    "normalize_sso_token",
+    "refresh_account_settings_for_tokens",
+    "DEFAULT_NSFW_REFRESH_CONCURRENCY",
+    "DEFAULT_NSFW_REFRESH_RETRIES",
+]

app/services/register/manager.py

@@ -0,0 +1,332 @@
+"""Auto registration manager."""
+from __future__ import annotations
+
+import asyncio
+import queue
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from app.core.config import get_config
+from app.core.logger import logger
+from app.services.token.manager import get_token_manager
+from app.services.register.runner import RegisterRunner
+from app.services.register.solver import SolverConfig, TurnstileSolverProcess
+
+
+@dataclass
+class RegisterJob:
+    job_id: str
+    total: int
+    pool: str
+    register_threads: int = 10
+    status: str = "starting"
+    started_at: float = field(default_factory=time.time)
+    finished_at: Optional[float] = None
+    completed: int = 0
+    added: int = 0
+    errors: int = 0
+    error: Optional[str] = None
+    last_error: Optional[str] = None
+    tokens: List[str] = field(default_factory=list)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+    stop_event: threading.Event = field(default_factory=threading.Event, repr=False)
+
+    def record_success(self, token: str) -> None:
+        with self._lock:
+            self.completed += 1
+            self.tokens.append(token)
+
+    def record_added(self) -> None:
+        with self._lock:
+            self.added += 1
+
+    def record_error(self, message: str) -> None:
+        message = (message or "").strip()
+        if len(message) > 500:
+            message = message[:500] + "..."
+        with self._lock:
+            self.errors += 1
+            if message:
+                self.last_error = message
+
+    def to_dict(self) -> Dict[str, object]:
+        with self._lock:
+            return {
+                "job_id": self.job_id,
+                "status": self.status,
+                "pool": self.pool,
+                "total": self.total,
+                "concurrency": self.register_threads,
+                "completed": self.completed,
+                "added": self.added,
+                "errors": self.errors,
+                "error": self.error,
+                "last_error": self.last_error,
+                "started_at": int(self.started_at * 1000),
+                "finished_at": int(self.finished_at * 1000) if self.finished_at else None,
+            }
+
+
+class AutoRegisterManager:
+    """Single job manager for auto registration."""
+
+    _instance: Optional["AutoRegisterManager"] = None
+
+    def __init__(self) -> None:
+        self._lock = asyncio.Lock()
+        self._job: Optional[RegisterJob] = None
+        self._task: Optional[asyncio.Task] = None
+        self._solver: Optional[TurnstileSolverProcess] = None
+
+    async def start_job(
+        self,
+        count: int,
+        pool: str,
+        concurrency: Optional[int] = None,
+    ) -> RegisterJob:
+        async with self._lock:
+            if self._job and self._job.status in {"starting", "running", "stopping"}:
+                raise RuntimeError("Auto registration already running")
+
+            default_threads = get_config("register.register_threads", 10)
+            try:
+                default_threads = max(1, int(default_threads))
+            except Exception:
+                default_threads = 10
+
+            threads = concurrency if isinstance(concurrency, int) and concurrency > 0 else default_threads
+
+            job = RegisterJob(
+                job_id=uuid.uuid4().hex[:8],
+                total=count,
+                pool=pool,
+                register_threads=threads,
+            )
+            self._job = job
+            self._task = asyncio.create_task(self._run_job(job))
+            return job
+
+    def get_status(self, job_id: Optional[str] = None) -> Dict[str, object]:
+        if not self._job:
+            return {"status": "idle"}
+        if job_id and self._job.job_id != job_id:
+            return {"status": "not_found"}
+        return self._job.to_dict()
+
+    async def stop_job(self) -> None:
+        """Best-effort stop for the current job (used on shutdown)."""
+        async with self._lock:
+            job = self._job
+            task = self._task
+            solver = self._solver
+
+            if not job or job.status not in {"starting", "running"}:
+                return
+            job.status = "stopping"
+            job.stop_event.set()
+
+        # Stop solver first to avoid noisy retries.
+        if solver:
+            try:
+                await asyncio.to_thread(solver.stop)
+            except Exception:
+                pass
+
+        # Give the runner a short grace period to exit.
+        if task:
+            try:
+                await asyncio.wait_for(task, timeout=5.0)
+            except Exception:
+                # Don't block shutdown; the process is exiting anyway.
+                pass
+
+    async def _run_job(self, job: RegisterJob) -> None:
+        job.status = "starting"
+
+        solver_url = get_config("register.solver_url", "http://127.0.0.1:5072")
+        solver_threads = get_config("register.solver_threads", 5)
+        try:
+            solver_threads = max(1, int(solver_threads))
+        except Exception:
+            solver_threads = 5
+
+        auto_start_solver = get_config("register.auto_start_solver", True)
+        if not isinstance(auto_start_solver, bool):
+            auto_start_solver = str(auto_start_solver).lower() in {"1", "true", "yes", "on"}
+
+        # Auto-start only for local solver endpoints.
+        try:
+            from urllib.parse import urlparse
+
+            host = urlparse(str(solver_url)).hostname or ""
+            if host and host not in {"127.0.0.1", "localhost", "::1", "0.0.0.0"}:
+                auto_start_solver = False
+        except Exception:
+            pass
+
+        solver_debug = get_config("register.solver_debug", False)
+        if not isinstance(solver_debug, bool):
+            solver_debug = str(solver_debug).lower() in {"1", "true", "yes", "on"}
+
+        browser_type = str(get_config("register.solver_browser_type", "chromium") or "chromium").strip().lower()
+        if browser_type not in {"chromium", "chrome", "msedge", "camoufox"}:
+            browser_type = "chromium"
+
+        solver_cfg = SolverConfig(
+            url=str(solver_url or "http://127.0.0.1:5072"),
+            threads=solver_threads,
+            browser_type=browser_type,
+            debug=solver_debug,
+            auto_start=auto_start_solver,
+        )
+        solver = TurnstileSolverProcess(solver_cfg)
+        self._solver = solver
+
+        use_yescaptcha = bool(str(get_config("register.yescaptcha_key", "") or "").strip())
+        if use_yescaptcha:
+            # When YesCaptcha is configured we don't need a local solver process.
+            auto_start_solver = False
+            solver.config.auto_start = False
+
+        # Safety limits to avoid endless loops when upstream is broken.
+        max_errors = get_config("register.max_errors", 0)
+        try:
+            max_errors = int(max_errors)
+        except Exception:
+            max_errors = 0
+        if max_errors <= 0:
+            # Default: allow retries, but stop instead of looping "forever".
+            max_errors = max(30, int(job.total) * 5)
+
+        max_runtime_minutes = get_config("register.max_runtime_minutes", 0)
+        try:
+            max_runtime_minutes = float(max_runtime_minutes)
+        except Exception:
+            max_runtime_minutes = 0
+        max_runtime_sec = max_runtime_minutes * 60 if max_runtime_minutes and max_runtime_minutes > 0 else 0
+
+        token_queue: queue.Queue[object] = queue.Queue()
+        sentinel = object()
+
+        async def _consume_tokens() -> None:
+            mgr = await get_token_manager()
+            while True:
+                item = await asyncio.to_thread(token_queue.get)
+                if item is sentinel:
+                    break
+                token = str(item or "").strip()
+                if not token:
+                    continue
+                try:
+                    if await mgr.add(token, pool_name=job.pool):
+                        job.record_added()
+                except Exception as exc:
+                    job.record_error(f"save token failed: {exc}")
+
+        def _on_error(msg: str) -> None:
+            job.record_error(msg)
+            # Called from worker threads; keep it simple and thread-safe.
+            with job._lock:
+                if job.status in {"starting", "running"} and job.errors >= max_errors:
+                    job.status = "error"
+                    job.error = f"Too many failures ({job.errors}/{max_errors}). Check register config/solver."
+                    job.stop_event.set()
+
+        async def _watchdog() -> None:
+            if not max_runtime_sec:
+                return
+            while True:
+                await asyncio.sleep(1.0)
+                if job.stop_event.is_set():
+                    return
+                if job.status not in {"starting", "running"}:
+                    return
+                if (time.time() - job.started_at) >= max_runtime_sec:
+                    with job._lock:
+                        if job.status in {"starting", "running"}:
+                            job.status = "error"
+                            job.error = f"Timeout after {max_runtime_minutes:g} minutes."
+                            job.stop_event.set()
+                    return
+
+        try:
+            if auto_start_solver:
+                try:
+                    await asyncio.to_thread(solver.start)
+                except Exception as exc:
+                    if not use_yescaptcha:
+                        raise
+                    logger.warning("Solver start failed, continuing with YesCaptcha: {}", exc)
+
+            job.status = "running"
+            watchdog_task = asyncio.create_task(_watchdog())
+            consumer_task = asyncio.create_task(_consume_tokens())
+            runner = RegisterRunner(
+                target_count=job.total,
+                thread_count=job.register_threads,
+                stop_event=job.stop_event,
+                on_success=lambda _email, _password, token, _done, _total: (
+                    job.record_success(token),
+                    token_queue.put(token),
+                ),
+                on_error=_on_error,
+            )
+
+            await asyncio.to_thread(runner.run)
+
+            # Drain token consumer.
+            token_queue.put(sentinel)
+            await consumer_task
+            if job.status == "stopping":
+                job.status = "stopped"
+            elif job.status != "error":
+                # If we returned without reaching the target, treat it as a failure.
+                # This makes issues like "TOS/BirthDate/NSFW not enabled" visible to the UI as a failed job.
+                if job.completed < job.total:
+                    job.status = "error"
+                    suffix = f" Last error: {job.last_error}" if job.last_error else ""
+                    job.error = f"Registration ended early ({job.completed}/{job.total}).{suffix}".strip()
+                else:
+                    job.status = "completed"
+        except Exception as exc:
+            job.status = "error"
+            job.error = str(exc)
+            logger.exception("Auto registration failed")
+        finally:
+            job.finished_at = time.time()
+            # Ensure consumer exits even on exceptions.
+            try:
+                token_queue.put(sentinel)
+            except Exception:
+                pass
+            try:
+                if "consumer_task" in locals():
+                    await asyncio.wait_for(consumer_task, timeout=10)
+            except Exception:
+                try:
+                    consumer_task.cancel()
+                except Exception:
+                    pass
+            try:
+                if "watchdog_task" in locals():
+                    watchdog_task.cancel()
+            except Exception:
+                pass
+            self._solver = None
+            if auto_start_solver:
+                try:
+                    await asyncio.to_thread(solver.stop)
+                except Exception:
+                    pass
+
+
+def get_auto_register_manager() -> AutoRegisterManager:
+    if AutoRegisterManager._instance is None:
+        AutoRegisterManager._instance = AutoRegisterManager()
+    return AutoRegisterManager._instance
+
+
+__all__ = ["AutoRegisterManager", "get_auto_register_manager"]

app/services/register/runner.py

@@ -0,0 +1,415 @@
+"""Grok account registration runner."""
+from __future__ import annotations
+
+import concurrent.futures
+import random
+import re
+import string
+import struct
+import threading
+import time
+from typing import Callable, Dict, List, Optional, Tuple
+from urllib.parse import urljoin
+
+from bs4 import BeautifulSoup
+from curl_cffi import requests as curl_requests
+
+from app.core.logger import logger
+from app.services.register.services import (
+    EmailService,
+    TurnstileService,
+    UserAgreementService,
+    BirthDateService,
+    NsfwSettingsService,
+)
+
+
+SITE_URL = "https://accounts.x.ai"
+DEFAULT_IMPERSONATE = "chrome120"
+
+CHROME_PROFILES = [
+    {"impersonate": "chrome110", "version": "110.0.0.0", "brand": "chrome"},
+    {"impersonate": "chrome119", "version": "119.0.0.0", "brand": "chrome"},
+    {"impersonate": "chrome120", "version": "120.0.0.0", "brand": "chrome"},
+    {"impersonate": "edge99", "version": "99.0.1150.36", "brand": "edge"},
+    {"impersonate": "edge101", "version": "101.0.1210.47", "brand": "edge"},
+]
+
+
+def _random_chrome_profile() -> Tuple[str, str]:
+    profile = random.choice(CHROME_PROFILES)
+    if profile.get("brand") == "edge":
+        chrome_major = profile["version"].split(".")[0]
+        chrome_version = f"{chrome_major}.0.0.0"
+        ua = (
+            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+            "AppleWebKit/537.36 (KHTML, like Gecko) "
+            f"Chrome/{chrome_version} Safari/537.36 Edg/{profile['version']}"
+        )
+    else:
+        ua = (
+            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+            "AppleWebKit/537.36 (KHTML, like Gecko) "
+            f"Chrome/{profile['version']} Safari/537.36"
+        )
+    return profile["impersonate"], ua
+
+
+def _generate_random_name() -> str:
+    length = random.randint(4, 6)
+    return random.choice(string.ascii_uppercase) + "".join(
+        random.choice(string.ascii_lowercase) for _ in range(length - 1)
+    )
+
+
+def _generate_random_string(length: int = 15) -> str:
+    return "".join(random.choice(string.ascii_lowercase + string.digits) for _ in range(length))
+
+
+def _encode_grpc_message(field_id: int, string_value: str) -> bytes:
+    key = (field_id << 3) | 2
+    value_bytes = string_value.encode("utf-8")
+    payload = struct.pack("B", key) + struct.pack("B", len(value_bytes)) + value_bytes
+    return b"\x00" + struct.pack(">I", len(payload)) + payload
+
+
+def _encode_grpc_message_verify(email: str, code: str) -> bytes:
+    p1 = struct.pack("B", (1 << 3) | 2) + struct.pack("B", len(email)) + email.encode("utf-8")
+    p2 = struct.pack("B", (2 << 3) | 2) + struct.pack("B", len(code)) + code.encode("utf-8")
+    payload = p1 + p2
+    return b"\x00" + struct.pack(">I", len(payload)) + payload
+
+
+class RegisterRunner:
+    """Threaded registration runner."""
+
+    def __init__(
+        self,
+        target_count: int = 100,
+        thread_count: int = 8,
+        on_success: Optional[Callable[[str, str, str, int, int], None]] = None,
+        on_error: Optional[Callable[[str], None]] = None,
+        stop_event: Optional[threading.Event] = None,
+    ) -> None:
+        self.target_count = max(1, int(target_count))
+        self.thread_count = max(1, int(thread_count))
+        self.on_success = on_success
+        self.on_error = on_error
+        self.stop_event = stop_event or threading.Event()
+
+        self._post_lock = threading.Lock()
+        self._result_lock = threading.Lock()
+
+        self._success_count = 0
+        self._start_time = 0.0
+        self._tokens: List[str] = []
+        self._accounts: List[Dict[str, str]] = []
+
+        self._config: Dict[str, Optional[str]] = {
+            "site_key": "0x4AAAAAAAhr9JGVDZbrZOo0",
+            "action_id": None,
+            "state_tree": "%5B%22%22%2C%7B%22children%22%3A%5B%22(app)%22%2C%7B%22children%22%3A%5B%22(auth)%22%2C%7B%22children%22%3A%5B%22sign-up%22%2C%7B%22children%22%3A%5B%22__PAGE__%22%2C%7B%7D%2C%22%2Fsign-up%22%2C%22refresh%22%5D%7D%5D%7D%2Cnull%2Cnull%5D%7D%2Cnull%2Cnull%5D%7D%2Cnull%2Cnull%2Ctrue%5D",
+        }
+
+    @property
+    def success_count(self) -> int:
+        return self._success_count
+
+    @property
+    def tokens(self) -> List[str]:
+        return list(self._tokens)
+
+    @property
+    def accounts(self) -> List[Dict[str, str]]:
+        return list(self._accounts)
+
+    def _record_success(self, email: str, password: str, token: str) -> None:
+        with self._result_lock:
+            if self._success_count >= self.target_count:
+                if not self.stop_event.is_set():
+                    self.stop_event.set()
+                return
+
+            self._success_count += 1
+            self._tokens.append(token)
+            self._accounts.append({"email": email, "password": password, "token": token})
+
+            avg = (time.time() - self._start_time) / max(1, self._success_count)
+            logger.info(
+                "Register success: {} | sso={}... | avg={:.1f}s ({}/{})",
+                email,
+                token[:12],
+                avg,
+                self._success_count,
+                self.target_count,
+            )
+
+            if self.on_success:
+                try:
+                    self.on_success(email, password, token, self._success_count, self.target_count)
+                except Exception:
+                    pass
+
+            if self._success_count >= self.target_count and not self.stop_event.is_set():
+                self.stop_event.set()
+
+    def _record_error(self, message: str) -> None:
+        if self.on_error:
+            try:
+                self.on_error(message)
+            except Exception:
+                pass
+
+    def _init_config(self) -> None:
+        logger.info("Register: initializing action config...")
+        start_url = f"{SITE_URL}/sign-up"
+
+        with curl_requests.Session(impersonate=DEFAULT_IMPERSONATE) as session:
+            html = session.get(start_url, timeout=15).text
+
+            key_match = re.search(r'sitekey":"(0x4[a-zA-Z0-9_-]+)"', html)
+            if key_match:
+                self._config["site_key"] = key_match.group(1)
+
+            tree_match = re.search(r'next-router-state-tree":"([^"]+)"', html)
+            if tree_match:
+                self._config["state_tree"] = tree_match.group(1)
+
+            soup = BeautifulSoup(html, "html.parser")
+            js_urls = [
+                urljoin(start_url, script["src"])
+                for script in soup.find_all("script", src=True)
+                if "_next/static" in script["src"]
+            ]
+            for js_url in js_urls:
+                js_content = session.get(js_url, timeout=15).text
+                match = re.search(r"7f[a-fA-F0-9]{40}", js_content)
+                if match:
+                    self._config["action_id"] = match.group(0)
+                    logger.info("Register: Action ID found: {}", self._config["action_id"])
+                    break
+
+        if not self._config.get("action_id"):
+            raise RuntimeError("Register init failed: missing action_id")
+
+    def _send_email_code(self, session: curl_requests.Session, email: str) -> bool:
+        url = f"{SITE_URL}/auth_mgmt.AuthManagement/CreateEmailValidationCode"
+        data = _encode_grpc_message(1, email)
+        headers = {
+            "content-type": "application/grpc-web+proto",
+            "x-grpc-web": "1",
+            "x-user-agent": "connect-es/2.1.1",
+            "origin": SITE_URL,
+            "referer": f"{SITE_URL}/sign-up?redirect=grok-com",
+        }
+        try:
+            res = session.post(url, data=data, headers=headers, timeout=15)
+            return res.status_code == 200
+        except Exception as exc:
+            self._record_error(f"send code error: {email} - {exc}")
+            return False
+
+    def _verify_email_code(self, session: curl_requests.Session, email: str, code: str) -> bool:
+        url = f"{SITE_URL}/auth_mgmt.AuthManagement/VerifyEmailValidationCode"
+        data = _encode_grpc_message_verify(email, code)
+        headers = {
+            "content-type": "application/grpc-web+proto",
+            "x-grpc-web": "1",
+            "x-user-agent": "connect-es/2.1.1",
+            "origin": SITE_URL,
+            "referer": f"{SITE_URL}/sign-up?redirect=grok-com",
+        }
+        try:
+            res = session.post(url, data=data, headers=headers, timeout=15)
+            return res.status_code == 200
+        except Exception as exc:
+            self._record_error(f"verify code error: {email} - {exc}")
+            return False
+
+    def _register_single_thread(self) -> None:
+        time.sleep(random.uniform(0, 5))
+
+        try:
+            email_service = EmailService()
+            turnstile_service = TurnstileService()
+            user_agreement_service = UserAgreementService()
+            birth_date_service = BirthDateService()
+            nsfw_service = NsfwSettingsService()
+        except Exception as exc:
+            self._record_error(f"service init failed: {exc}")
+            return
+
+        final_action_id = self._config.get("action_id")
+        if not final_action_id:
+            self._record_error("missing action id")
+            return
+
+        while not self.stop_event.is_set():
+            try:
+                impersonate_fingerprint, account_user_agent = _random_chrome_profile()
+
+                with curl_requests.Session(impersonate=impersonate_fingerprint) as session:
+                    try:
+                        session.get(SITE_URL, timeout=10)
+                    except Exception:
+                        pass
+
+                    password = _generate_random_string()
+
+                    jwt, email = email_service.create_email()
+                    if not email:
+                        self._record_error("create_email failed")
+                        time.sleep(5)
+                        continue
+
+                    if self.stop_event.is_set():
+                        return
+
+                    if not self._send_email_code(session, email):
+                        self._record_error(f"send_email_code failed: {email}")
+                        time.sleep(5)
+                        continue
+
+                    verify_code = None
+                    for _ in range(30):
+                        time.sleep(1)
+                        if self.stop_event.is_set():
+                            return
+                        content = email_service.fetch_first_email(jwt)
+                        if content:
+                            match = re.search(r">([A-Z0-9]{3}-[A-Z0-9]{3})<", content)
+                            if match:
+                                verify_code = match.group(1).replace("-", "")
+                                break
+
+                    if not verify_code:
+                        self._record_error(f"verify_code not received: {email}")
+                        time.sleep(3)
+                        continue
+
+                    if not self._verify_email_code(session, email, verify_code):
+                        self._record_error(f"verify_email_code failed: {email}")
+                        time.sleep(3)
+                        continue
+
+                    for _ in range(3):
+                        if self.stop_event.is_set():
+                            return
+
+                        try:
+                            task_id = turnstile_service.create_task(f"{SITE_URL}/sign-up", self._config["site_key"] or "")
+                        except Exception as exc:
+                            self._record_error(f"turnstile create_task failed: {exc}")
+                            time.sleep(2)
+                            continue
+
+                        token = turnstile_service.get_response(task_id, stop_event=self.stop_event)
+
+                        if not token:
+                            self._record_error(f"turnstile failed: {turnstile_service.last_error or 'no token'}")
+                            time.sleep(2)
+                            continue
+
+                        headers = {
+                            "user-agent": account_user_agent,
+                            "accept": "text/x-component",
+                            "content-type": "text/plain;charset=UTF-8",
+                            "origin": SITE_URL,
+                            "referer": f"{SITE_URL}/sign-up",
+                            "cookie": f"__cf_bm={session.cookies.get('__cf_bm','')}",
+                            "next-router-state-tree": self._config["state_tree"] or "",
+                            "next-action": final_action_id,
+                        }
+                        payload = [
+                            {
+                                "emailValidationCode": verify_code,
+                                "createUserAndSessionRequest": {
+                                    "email": email,
+                                    "givenName": _generate_random_name(),
+                                    "familyName": _generate_random_name(),
+                                    "clearTextPassword": password,
+                                    "tosAcceptedVersion": "$undefined",
+                                },
+                                "turnstileToken": token,
+                                "promptOnDuplicateEmail": True,
+                            }
+                        ]
+
+                        with self._post_lock:
+                            res = session.post(
+                                f"{SITE_URL}/sign-up",
+                                json=payload,
+                                headers=headers,
+                                timeout=20,
+                            )
+
+                        if res.status_code != 200:
+                            self._record_error(f"sign_up http {res.status_code}")
+                            time.sleep(3)
+                            continue
+
+                        match = re.search(r'(https://[^" \s]+set-cookie\?q=[^:" \s]+)1:', res.text)
+                        if not match:
+                            self._record_error("sign_up missing set-cookie redirect")
+                            break
+
+                        verify_url = match.group(1)
+                        session.get(verify_url, allow_redirects=True, timeout=15)
+
+                        sso = session.cookies.get("sso")
+                        sso_rw = session.cookies.get("sso-rw")
+                        if not sso:
+                            self._record_error("sign_up missing sso cookie")
+                            break
+
+                        tos_result = user_agreement_service.accept_tos_version(
+                            sso=sso,
+                            sso_rw=sso_rw or "",
+                            impersonate=impersonate_fingerprint,
+                            user_agent=account_user_agent,
+                        )
+                        if not tos_result.get("ok") or not tos_result.get("hex_reply"):
+                            self._record_error(f"accept_tos failed: {tos_result.get('error') or 'unknown'}")
+                            break
+
+                        birth_result = birth_date_service.set_birth_date(
+                            sso=sso,
+                            sso_rw=sso_rw or "",
+                            impersonate=impersonate_fingerprint,
+                            user_agent=account_user_agent,
+                        )
+                        if not birth_result.get("ok"):
+                            self._record_error(
+                                f"set_birth_date failed: {birth_result.get('error') or 'unknown'}"
+                            )
+                            break
+
+                        nsfw_result = nsfw_service.enable_nsfw(
+                            sso=sso,
+                            sso_rw=sso_rw or "",
+                            impersonate=impersonate_fingerprint,
+                            user_agent=account_user_agent,
+                        )
+                        if not nsfw_result.get("ok") or not nsfw_result.get("hex_reply"):
+                            self._record_error(f"enable_nsfw failed: {nsfw_result.get('error') or 'unknown'}")
+                            break
+
+                        self._record_success(email, password, sso)
+                        break
+
+            except Exception as exc:
+                self._record_error(f"thread error: {str(exc)[:80]}")
+                time.sleep(3)
+
+    def run(self) -> List[str]:
+        """Run the registration process and return collected tokens."""
+        self._init_config()
+        self._start_time = time.time()
+
+        logger.info("Register: starting {} threads, target {}", self.thread_count, self.target_count)
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=self.thread_count) as executor:
+            futures = [executor.submit(self._register_single_thread) for _ in range(self.thread_count)]
+            concurrent.futures.wait(futures)
+
+        return list(self._tokens)

app/services/register/services/__init__.py

@@ -0,0 +1,15 @@
+"""Registration helper services."""
+
+from app.services.register.services.email_service import EmailService
+from app.services.register.services.turnstile_service import TurnstileService
+from app.services.register.services.user_agreement_service import UserAgreementService
+from app.services.register.services.birth_date_service import BirthDateService
+from app.services.register.services.nsfw_service import NsfwSettingsService
+
+__all__ = [
+    "EmailService",
+    "TurnstileService",
+    "UserAgreementService",
+    "BirthDateService",
+    "NsfwSettingsService",
+]

app/services/register/services/birth_date_service.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import datetime
+import random
+from typing import Any, Dict, Optional
+
+from curl_cffi import requests
+
+DEFAULT_USER_AGENT = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) "
+    "Chrome/120.0.0.0 Safari/537.36"
+)
+
+
+def generate_random_birthdate() -> str:
+    """Generate a random birth date between 20 and 40 years old."""
+    today = datetime.date.today()
+    age = random.randint(20, 40)
+    birth_year = today.year - age
+    birth_month = random.randint(1, 12)
+    birth_day = random.randint(1, 28)
+    return f"{birth_year}-{birth_month:02d}-{birth_day:02d}T16:00:00.000Z"
+
+
+class BirthDateService:
+    """Set account birth date via Grok REST API."""
+
+    def __init__(self, cf_clearance: str = ""):
+        self.cf_clearance = (cf_clearance or "").strip()
+
+    def set_birth_date(
+        self,
+        sso: str,
+        sso_rw: str,
+        impersonate: str,
+        user_agent: Optional[str] = None,
+        cf_clearance: Optional[str] = None,
+        timeout: int = 15,
+    ) -> Dict[str, Any]:
+        if not sso:
+            return {
+                "ok": False,
+                "status_code": None,
+                "response_text": "",
+                "error": "missing sso",
+            }
+        if not sso_rw:
+            return {
+                "ok": False,
+                "status_code": None,
+                "response_text": "",
+                "error": "missing sso-rw",
+            }
+
+        url = "https://grok.com/rest/auth/set-birth-date"
+        cookies = {
+            "sso": sso,
+            "sso-rw": sso_rw,
+        }
+        clearance = (cf_clearance if cf_clearance is not None else self.cf_clearance).strip()
+        if clearance:
+            cookies["cf_clearance"] = clearance
+
+        headers = {
+            "content-type": "application/json",
+            "origin": "https://grok.com",
+            "referer": "https://grok.com/",
+            "user-agent": user_agent or DEFAULT_USER_AGENT,
+        }
+        payload = {"birthDate": generate_random_birthdate()}
+
+        try:
+            response = requests.post(
+                url,
+                headers=headers,
+                cookies=cookies,
+                json=payload,
+                impersonate=impersonate or "chrome120",
+                timeout=timeout,
+            )
+            status_code = response.status_code
+            response_text = response.text or ""
+            ok = status_code == 200
+            return {
+                "ok": ok,
+                "status_code": status_code,
+                "response_text": response_text,
+                "error": None if ok else f"HTTP {status_code}",
+            }
+        except Exception as e:
+            return {
+                "ok": False,
+                "status_code": None,
+                "response_text": "",
+                "error": str(e),
+            }

app/services/register/services/email_service.py

@@ -0,0 +1,90 @@
+"""Email service for temporary inbox creation."""
+from __future__ import annotations
+
+import os
+import random
+import string
+from typing import Tuple, Optional
+
+import requests
+
+from app.core.config import get_config
+
+
+class EmailService:
+    """Email service wrapper."""
+
+    def __init__(
+        self,
+        worker_domain: Optional[str] = None,
+        email_domain: Optional[str] = None,
+        admin_password: Optional[str] = None,
+    ) -> None:
+        self.worker_domain = (
+            (worker_domain or get_config("register.worker_domain", "") or os.getenv("WORKER_DOMAIN", "")).strip()
+        )
+        self.email_domain = (
+            (email_domain or get_config("register.email_domain", "") or os.getenv("EMAIL_DOMAIN", "")).strip()
+        )
+        self.admin_password = (
+            (admin_password or get_config("register.admin_password", "") or os.getenv("ADMIN_PASSWORD", "")).strip()
+        )
+
+        if not all([self.worker_domain, self.email_domain, self.admin_password]):
+            raise ValueError(
+                "Missing required email settings: register.worker_domain, register.email_domain, "
+                "register.admin_password"
+            )
+
+    def _generate_random_name(self) -> str:
+        letters1 = "".join(random.choices(string.ascii_lowercase, k=random.randint(4, 6)))
+        numbers = "".join(random.choices(string.digits, k=random.randint(1, 3)))
+        letters2 = "".join(random.choices(string.ascii_lowercase, k=random.randint(0, 5)))
+        return letters1 + numbers + letters2
+
+    def create_email(self) -> Tuple[Optional[str], Optional[str]]:
+        """Create a temporary mailbox. Returns (jwt, address)."""
+        url = f"https://{self.worker_domain}/admin/new_address"
+        try:
+            random_name = self._generate_random_name()
+            res = requests.post(
+                url,
+                json={
+                    "enablePrefix": True,
+                    "name": random_name,
+                    "domain": self.email_domain,
+                },
+                headers={
+                    "x-admin-auth": self.admin_password,
+                    "Content-Type": "application/json",
+                },
+                timeout=10,
+            )
+            if res.status_code == 200:
+                data = res.json()
+                return data.get("jwt"), data.get("address")
+            print(f"[-] Email create failed: {res.status_code} - {res.text}")
+        except Exception as exc:  # pragma: no cover - network/remote errors
+            print(f"[-] Email create error ({url}): {exc}")
+        return None, None
+
+    def fetch_first_email(self, jwt: str) -> Optional[str]:
+        """Fetch the first email content for the mailbox."""
+        try:
+            res = requests.get(
+                f"https://{self.worker_domain}/api/mails",
+                params={"limit": 10, "offset": 0},
+                headers={
+                    "Authorization": f"Bearer {jwt}",
+                    "Content-Type": "application/json",
+                },
+                timeout=10,
+            )
+            if res.status_code == 200:
+                data = res.json()
+                if data.get("results"):
+                    return data["results"][0].get("raw")
+            return None
+        except Exception as exc:  # pragma: no cover - network/remote errors
+            print(f"Email fetch failed: {exc}")
+            return None

app/services/register/services/nsfw_service.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from typing import Optional, Dict, Any
+
+from curl_cffi import requests
+
+DEFAULT_USER_AGENT = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) "
+    "Chrome/120.0.0.0 Safari/537.36"
+)
+
+
+class NsfwSettingsService:
+    """开启 NSFW 相关设置（线程安全，无全局状态）。"""
+
+    def __init__(self, cf_clearance: str = ""):
+        self.cf_clearance = (cf_clearance or "").strip()
+
+    def enable_nsfw(
+        self,
+        sso: str,
+        sso_rw: str,
+        impersonate: str,
+        user_agent: Optional[str] = None,
+        cf_clearance: Optional[str] = None,
+        timeout: int = 15,
+    ) -> Dict[str, Any]:
+        """
+        启用 always_show_nsfw_content。
+        返回: {
+            ok: bool,
+            hex_reply: str,
+            status_code: int | None,
+            grpc_status: str | None,
+            error: str | None
+        }
+        """
+        if not sso:
+            return {
+                "ok": False,
+                "hex_reply": "",
+                "status_code": None,
+                "grpc_status": None,
+                "error": "缺少 sso",
+            }
+        if not sso_rw:
+            return {
+                "ok": False,
+                "hex_reply": "",
+                "status_code": None,
+                "grpc_status": None,
+                "error": "缺少 sso-rw",
+            }
+
+        url = "https://grok.com/auth_mgmt.AuthManagement/UpdateUserFeatureControls"
+
+        cookies = {
+            "sso": sso,
+            "sso-rw": sso_rw,
+        }
+        clearance = (cf_clearance if cf_clearance is not None else self.cf_clearance).strip()
+        if clearance:
+            cookies["cf_clearance"] = clearance
+
+        headers = {
+            "content-type": "application/grpc-web+proto",
+            "origin": "https://grok.com",
+            "referer": "https://grok.com/?_s=data",
+            "x-grpc-web": "1",
+            "user-agent": user_agent or DEFAULT_USER_AGENT,
+        }
+
+        data = (
+            b"\x00\x00\x00\x00"
+            b"\x20"
+            b"\x0a\x02\x10\x01"
+            b"\x12\x1a"
+            b"\x0a\x18"
+            b"always_show_nsfw_content"
+        )
+
+        try:
+            response = requests.post(
+                url,
+                headers=headers,
+                cookies=cookies,
+                data=data,
+                impersonate=impersonate or "chrome120",
+                timeout=timeout,
+            )
+            hex_reply = response.content.hex()
+            grpc_status = response.headers.get("grpc-status")
+
+            error = None
+            ok = response.status_code == 200 and (grpc_status in (None, "0"))
+            if response.status_code == 403:
+                error = "403 Forbidden"
+            elif response.status_code != 200:
+                error = f"HTTP {response.status_code}"
+            elif grpc_status not in (None, "0"):
+                error = f"gRPC {grpc_status}"
+
+            return {
+                "ok": ok,
+                "hex_reply": hex_reply,
+                "status_code": response.status_code,
+                "grpc_status": grpc_status,
+                "error": error,
+            }
+        except Exception as e:
+            return {
+                "ok": False,
+                "hex_reply": "",
+                "status_code": None,
+                "grpc_status": None,
+                "error": str(e),
+            }

app/services/register/services/turnstile_service.py

@@ -0,0 +1,161 @@
+"""Turnstile solving service."""
+from __future__ import annotations
+
+import os
+import time
+from typing import Optional
+
+from app.core.logger import logger
+
+import requests
+
+from app.core.config import get_config
+
+
+class TurnstileService:
+    """Turnstile solver wrapper (local solver or YesCaptcha)."""
+
+    def __init__(
+        self,
+        solver_url: Optional[str] = None,
+        yescaptcha_key: Optional[str] = None,
+    ) -> None:
+        self.yescaptcha_key = (
+            (yescaptcha_key or get_config("register.yescaptcha_key", "") or os.getenv("YESCAPTCHA_KEY", "")).strip()
+        )
+        self.solver_url = (
+            solver_url
+            or get_config("register.solver_url", "")
+            or os.getenv("TURNSTILE_SOLVER_URL", "")
+            or "http://127.0.0.1:5072"
+        ).strip()
+        self.yescaptcha_api = "https://api.yescaptcha.com"
+        self.last_error: Optional[str] = None
+
+    def create_task(self, siteurl: str, sitekey: str) -> str:
+        """Create a Turnstile task and return task ID."""
+        self.last_error = None
+        if self.yescaptcha_key:
+            url = f"{self.yescaptcha_api}/createTask"
+            payload = {
+                "clientKey": self.yescaptcha_key,
+                "task": {
+                    "type": "TurnstileTaskProxyless",
+                    "websiteURL": siteurl,
+                    "websiteKey": sitekey,
+                },
+            }
+            response = requests.post(url, json=payload, timeout=20)
+            response.raise_for_status()
+            data = response.json()
+            if data.get("errorId") != 0:
+                desc = data.get("errorDescription") or "unknown"
+                self.last_error = f"YesCaptcha createTask failed: {desc}"
+                raise RuntimeError(self.last_error)
+            return data["taskId"]
+
+        response = requests.get(
+            f"{self.solver_url}/turnstile",
+            params={"url": siteurl, "sitekey": sitekey},
+            timeout=20,
+        )
+        response.raise_for_status()
+        data = response.json()
+        task_id = data.get("taskId")
+        if not task_id:
+            self.last_error = data.get("errorDescription") or data.get("errorCode") or "missing taskId"
+            raise RuntimeError(f"Solver create task failed: {self.last_error}")
+        return task_id
+
+    def get_response(
+        self,
+        task_id: str,
+        max_retries: int = 30,
+        initial_delay: int = 5,
+        retry_delay: int = 2,
+        stop_event: object | None = None,
+    ) -> Optional[str]:
+        """Fetch a Turnstile solution token."""
+        self.last_error = None
+        # Make shutdown/cancel responsive.
+        if initial_delay > 0:
+            for _ in range(int(initial_delay * 10)):
+                if stop_event is not None and getattr(stop_event, "is_set", lambda: False)():
+                    return None
+                time.sleep(0.1)
+
+        for _ in range(max_retries):
+            if stop_event is not None and getattr(stop_event, "is_set", lambda: False)():
+                return None
+            try:
+                if self.yescaptcha_key:
+                    url = f"{self.yescaptcha_api}/getTaskResult"
+                    payload = {"clientKey": self.yescaptcha_key, "taskId": task_id}
+                    response = requests.post(url, json=payload, timeout=20)
+                    response.raise_for_status()
+                    data = response.json()
+
+                    if data.get("errorId") != 0:
+                        self.last_error = str(data.get("errorDescription") or "unknown")
+                        logger.warning("YesCaptcha getTaskResult failed: {}", self.last_error)
+                        return None
+
+                    status = data.get("status")
+                    if status == "ready":
+                        token = data.get("solution", {}).get("token")
+                        if token:
+                            return token
+                        self.last_error = "YesCaptcha returned empty token"
+                        logger.warning(self.last_error)
+                        return None
+                    if status == "processing":
+                        if retry_delay > 0:
+                            for _ in range(int(retry_delay * 10)):
+                                if stop_event is not None and getattr(stop_event, "is_set", lambda: False)():
+                                    return None
+                                time.sleep(0.1)
+                        continue
+                    self.last_error = f"YesCaptcha unexpected status: {status}"
+                    logger.warning(self.last_error)
+                    if retry_delay > 0:
+                        for _ in range(int(retry_delay * 10)):
+                            if stop_event is not None and getattr(stop_event, "is_set", lambda: False)():
+                                return None
+                            time.sleep(0.1)
+                    continue
+
+                response = requests.get(
+                    f"{self.solver_url}/result",
+                    params={"id": task_id},
+                    timeout=20,
+                )
+                response.raise_for_status()
+                data = response.json()
+
+                # Solver error -> stop early (avoid polling forever on unsolvable tasks).
+                error_id = data.get("errorId")
+                if error_id is not None and error_id != 0:
+                    self.last_error = str(data.get("errorDescription") or data.get("errorCode") or "solver error")
+                    return None
+
+                token = data.get("solution", {}).get("token")
+                if token:
+                    if token != "CAPTCHA_FAIL":
+                        return token
+                    self.last_error = "CAPTCHA_FAIL"
+                    return None
+                if retry_delay > 0:
+                    for _ in range(int(retry_delay * 10)):
+                        if stop_event is not None and getattr(stop_event, "is_set", lambda: False)():
+                            return None
+                        time.sleep(0.1)
+            except Exception as exc:  # pragma: no cover - network/remote errors
+                self.last_error = str(exc)
+                logger.debug("Turnstile response error: {}", exc)
+                if retry_delay > 0:
+                    for _ in range(int(retry_delay * 10)):
+                        if stop_event is not None and getattr(stop_event, "is_set", lambda: False)():
+                            return None
+                        time.sleep(0.1)
+
+        return None

app/services/register/services/user_agreement_service.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from typing import Optional, Dict, Any
+
+from curl_cffi import requests
+
+DEFAULT_USER_AGENT = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) "
+    "Chrome/120.0.0.0 Safari/537.36"
+)
+
+
+class UserAgreementService:
+    """处理账号协议同意流程（线程安全，无全局状态）。"""
+
+    def __init__(self, cf_clearance: str = ""):
+        self.cf_clearance = (cf_clearance or "").strip()
+
+    def accept_tos_version(
+        self,
+        sso: str,
+        sso_rw: str,
+        impersonate: str,
+        user_agent: Optional[str] = None,
+        cf_clearance: Optional[str] = None,
+        timeout: int = 15,
+    ) -> Dict[str, Any]:
+        """
+        同意 TOS 版本。
+        返回: {
+            ok: bool,
+            hex_reply: str,
+            status_code: int | None,
+            grpc_status: str | None,
+            error: str | None
+        }
+        """
+        if not sso:
+            return {
+                "ok": False,
+                "hex_reply": "",
+                "status_code": None,
+                "grpc_status": None,
+                "error": "缺少 sso",
+            }
+        if not sso_rw:
+            return {
+                "ok": False,
+                "hex_reply": "",
+                "status_code": None,
+                "grpc_status": None,
+                "error": "缺少 sso-rw",
+            }
+
+        url = "https://accounts.x.ai/auth_mgmt.AuthManagement/SetTosAcceptedVersion"
+
+        cookies = {
+            "sso": sso,
+            "sso-rw": sso_rw,
+        }
+        clearance = (cf_clearance if cf_clearance is not None else self.cf_clearance).strip()
+        if clearance:
+            cookies["cf_clearance"] = clearance
+
+        headers = {
+            "content-type": "application/grpc-web+proto",
+            "origin": "https://accounts.x.ai",
+            "referer": "https://accounts.x.ai/accept-tos",
+            "x-grpc-web": "1",
+            "user-agent": user_agent or DEFAULT_USER_AGENT,
+        }
+
+        data = (
+            b"\x00\x00\x00\x00"  # 头部
+            b"\x02"  # 长度
+            b"\x10\x01"  # Field 2 = 1
+        )
+
+        try:
+            response = requests.post(
+                url,
+                headers=headers,
+                cookies=cookies,
+                data=data,
+                impersonate=impersonate or "chrome120",
+                timeout=timeout,
+            )
+            hex_reply = response.content.hex()
+            grpc_status = response.headers.get("grpc-status")
+
+            error = None
+            ok = response.status_code == 200 and (grpc_status in (None, "0"))
+            if response.status_code == 403:
+                error = "403 Forbidden"
+            elif response.status_code != 200:
+                error = f"HTTP {response.status_code}"
+            elif grpc_status not in (None, "0"):
+                error = f"gRPC {grpc_status}"
+
+            return {
+                "ok": ok,
+                "hex_reply": hex_reply,
+                "status_code": response.status_code,
+                "grpc_status": grpc_status,
+                "error": error,
+            }
+        except Exception as e:
+            return {
+                "ok": False,
+                "hex_reply": "",
+                "status_code": None,
+                "grpc_status": None,
+                "error": str(e),
+            }

app/services/register/solver.py

@@ -0,0 +1,296 @@
+"""Local Turnstile solver process manager."""
+from __future__ import annotations
+
+import socket
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse
+
+from app.core.logger import logger
+
+
+def _wait_for_port(host: str, port: int, timeout: float = 20.0) -> bool:
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            with socket.create_connection((host, port), timeout=1):
+                return True
+        except Exception:
+            time.sleep(0.5)
+    return False
+
+
+@dataclass
+class SolverConfig:
+    url: str
+    threads: int = 5
+    browser_type: str = "chromium"
+    debug: bool = False
+    auto_start: bool = True
+
+
+class TurnstileSolverProcess:
+    """Start/stop a local Turnstile solver."""
+
+    def __init__(self, config: SolverConfig) -> None:
+        self.config = config
+        self._process: Optional[subprocess.Popen] = None
+        self._started_by_us = False
+        self._repo_root = Path(__file__).resolve().parents[3]
+        self._python_exe: str = sys.executable
+        self._actual_browser_type: str = config.browser_type
+
+    def _script_path(self) -> Path:
+        return self._repo_root / "scripts" / "turnstile_solver" / "api_solver.py"
+
+    def _can_import(self, python_exe: str, modules: list[str]) -> bool:
+        """Check whether a python executable can import given modules."""
+        code = "; ".join([f"import {m}" for m in modules])
+        try:
+            subprocess.check_call(
+                [python_exe, "-c", code],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            return True
+        except Exception:
+            return False
+
+    def _windows_where_python(self) -> list[str]:
+        """List python.exe candidates on Windows using `where python` (best-effort)."""
+        if not sys.platform.startswith("win"):
+            return []
+        try:
+            out = subprocess.check_output(
+                ["where", "python"],
+                stderr=subprocess.DEVNULL,
+                text=True,
+                encoding="utf-8",
+                errors="ignore",
+            )
+        except Exception:
+            return []
+
+        paths: list[str] = []
+        seen: set[str] = set()
+        for line in out.splitlines():
+            p = (line or "").strip().strip('"')
+            if not p:
+                continue
+            key = p.lower()
+            if key in seen:
+                continue
+            seen.add(key)
+            paths.append(p)
+        return paths
+
+    def _select_runtime(self) -> None:
+        """Pick python executable + browser type to run solver with.
+
+        Practical notes (Windows):
+        - The API server may run in a venv (e.g. Python 3.13).
+        - Many users install the solver dependencies (camoufox/patchright) into their
+          system python (e.g. Python 3.12) and start the solver via a `.bat`.
+
+        To match that workflow, we prefer an interpreter that has `patchright` when
+        available (it tends to have better anti-bot compatibility). For camoufox,
+        we also require `camoufox` import to succeed.
+        """
+        desired = (self.config.browser_type or "chromium").strip().lower()
+        if desired not in {"chromium", "chrome", "msedge", "camoufox"}:
+            desired = "chromium"
+
+        # Collect python candidates.
+        #
+        # NOTE: When the API server runs under `uv run`, `python` on PATH usually points to
+        # the venv python, not the system python. On Windows, use `where python` to discover
+        # other interpreters (e.g. Python312) where users installed camoufox/patchright.
+        candidates: list[str] = [sys.executable]
+        for p in self._windows_where_python():
+            if p.lower() != sys.executable.lower():
+                candidates.append(p)
+        # As a last resort, try PATH resolution.
+        candidates.append("python")
+
+        # De-duplicate while preserving order.
+        dedup: list[str] = []
+        seen: set[str] = set()
+        for p in candidates:
+            k = p.lower()
+            if k in seen:
+                continue
+            seen.add(k)
+            dedup.append(p)
+        candidates = dedup
+
+        def _pick_with(modules: list[str]) -> str | None:
+            for exe in candidates:
+                if self._can_import(exe, modules):
+                    return exe
+            return None
+
+        self._actual_browser_type = desired
+
+        if desired == "camoufox":
+            # Prefer patchright if possible.
+            exe = _pick_with(["quart", "camoufox", "patchright"])
+            if exe:
+                self._python_exe = exe
+                return
+
+            exe = _pick_with(["quart", "camoufox", "playwright"])
+            if exe:
+                self._python_exe = exe
+                return
+
+            # No camoufox in any known interpreter; fallback to chromium.
+            logger.warning("Camoufox not available. Falling back solver browser to chromium.")
+            self._actual_browser_type = "chromium"
+
+        # For chromium/chrome/msedge, prefer patchright if available.
+        exe = _pick_with(["quart", "patchright"])
+        if exe:
+            self._python_exe = exe
+            return
+
+        exe = _pick_with(["quart", "playwright"])
+        if exe:
+            self._python_exe = exe
+            return
+
+        # Last resort: current interpreter (may fail fast with a clear error from the solver process).
+        self._python_exe = sys.executable
+
+    def _ensure_playwright_browsers(self, python_exe: str) -> None:
+        """Ensure Playwright browser binaries exist (best-effort).
+
+        We only auto-install for bundled Chromium. Branded channels (chrome/msedge)
+        rely on system-installed browsers.
+        """
+        if self._actual_browser_type != "chromium":
+            return
+
+        lock_dir = self._repo_root / "data" / ".locks"
+        lock_dir.mkdir(parents=True, exist_ok=True)
+        lock_path = lock_dir / "playwright_chromium_v1.lock"
+        if lock_path.exists():
+            return
+
+        try:
+            logger.info("Installing Playwright Chromium (first run)...")
+            args = [python_exe, "-m", "playwright", "install"]
+            # On Linux (Docker), install system deps as well.
+            if sys.platform.startswith("linux"):
+                args.append("--with-deps")
+            args.append("chromium")
+            subprocess.check_call(args, cwd=str(self._repo_root))
+            lock_path.write_text(str(time.time()), encoding="utf-8")
+        except Exception as exc:
+            # Don't create lock file; let next run retry.
+            raise RuntimeError(f"Playwright browser install failed: {exc}") from exc
+
+    def _parse_host_port(self) -> tuple[str, int]:
+        parsed = urlparse(self.config.url)
+        host = parsed.hostname or "127.0.0.1"
+        port = parsed.port or 5072
+        return host, int(port)
+
+    def start(self) -> None:
+        if not self.config.auto_start:
+            return
+
+        host, port = self._parse_host_port()
+
+        def _spawn() -> None:
+            script = self._script_path()
+            if not script.exists():
+                raise RuntimeError(f"Solver script not found: {script}")
+
+            # Ensure Playwright browsers are present before starting the solver process.
+            self._ensure_playwright_browsers(self._python_exe)
+
+            cmd = [
+                self._python_exe,
+                str(script),
+                "--browser_type",
+                self._actual_browser_type,
+                "--thread",
+                str(self.config.threads),
+            ]
+            if self.config.debug:
+                cmd.append("--debug")
+            cmd += ["--host", host, "--port", str(port)]
+
+            logger.info("Starting Turnstile solver: {}", " ".join(cmd))
+            self._process = subprocess.Popen(
+                cmd,
+                cwd=str(script.parent),
+            )
+            self._started_by_us = True
+
+            if not _wait_for_port(host, port, timeout=60.0):
+                exit_code = self._process.poll() if self._process else None
+                self.stop()
+                if exit_code is not None:
+                    raise RuntimeError(
+                        f"Turnstile solver exited early (code {exit_code}). "
+                        "Please check solver dependencies."
+                    )
+                raise RuntimeError("Turnstile solver did not become ready in time")
+
+        # Decide runtime + browser strategy before checking readiness.
+        self._select_runtime()
+        logger.info(
+            "Turnstile solver runtime selected: python={} browser_type={}",
+            self._python_exe,
+            self._actual_browser_type,
+        )
+
+        if _wait_for_port(host, port, timeout=1.0):
+            logger.info("Turnstile solver already running at {}:{}", host, port)
+            self._started_by_us = False
+            return
+
+        try:
+            _spawn()
+            return
+        except Exception as exc:
+            # camoufox is not always stable/available across environments (notably Docker).
+            # Fall back to chromium instead of failing the whole auto-register workflow.
+            if self._actual_browser_type != "camoufox":
+                raise
+            logger.warning("Camoufox solver failed to start; falling back to chromium: {}", exc)
+            try:
+                self.stop()
+            except Exception:
+                pass
+            self.config.browser_type = "chromium"
+            self._actual_browser_type = "chromium"
+            self._select_runtime()
+            logger.info(
+                "Turnstile solver runtime selected: python={} browser_type={}",
+                self._python_exe,
+                self._actual_browser_type,
+            )
+            _spawn()
+
+    def stop(self) -> None:
+        if not self._process or not self._started_by_us:
+            return
+
+        try:
+            logger.info("Stopping Turnstile solver...")
+            self._process.terminate()
+            self._process.wait(timeout=10)
+        except Exception:
+            try:
+                self._process.kill()
+            except Exception:
+                pass
+        finally:
+            self._process = None
+            self._started_by_us = False

app/services/request_logger.py

@@ -0,0 +1,143 @@
+"""请求日志审计 - 记录近期请求"""
+
+import time
+import asyncio
+import orjson
+from typing import List, Dict, Deque
+from collections import deque
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+from app.core.logger import logger
+
+@dataclass
+class RequestLog:
+    id: str
+    time: str
+    timestamp: float
+    ip: str
+    model: str
+    duration: float
+    status: int
+    key_name: str
+    token_suffix: str
+    error: str = ""
+
+class RequestLogger:
+    """请求日志记录器"""
+    
+    _instance = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+    
+    def __init__(self, max_len: int = 1000):
+        if hasattr(self, '_initialized'):
+            return
+            
+        self.file_path = Path(__file__).parents[2] / "data" / "logs.json"
+        self._logs: Deque[Dict] = deque(maxlen=max_len)
+        self._lock = asyncio.Lock()
+        self._loaded = False
+        
+        self._initialized = True
+
+    async def init(self):
+        """初始化加载数据"""
+        if not self._loaded:
+            await self._load_data()
+
+    async def _load_data(self):
+        """从磁盘加载日志数据"""
+        if self._loaded:
+            return
+
+        if not self.file_path.exists():
+            self._loaded = True
+            return
+
+        try:
+            async with self._lock:
+                content = await asyncio.to_thread(self.file_path.read_bytes)
+                if content:
+                    data = orjson.loads(content)
+                    if isinstance(data, list):
+                        self._logs.clear()
+                        self._logs.extend(data)
+                    self._loaded = True
+                    logger.debug(f"[Logger] 加载日志成功: {len(self._logs)} 条")
+        except Exception as e:
+            logger.error(f"[Logger] 加载日志失败: {e}")
+            self._loaded = True
+
+    async def _save_data(self):
+        """保存日志数据到磁盘"""
+        if not self._loaded:
+            return
+
+        try:
+            # 确保目录存在
+            self.file_path.parent.mkdir(parents=True, exist_ok=True)
+            
+            async with self._lock:
+                # 转换为列表保存
+                content = orjson.dumps(list(self._logs))
+                await asyncio.to_thread(self.file_path.write_bytes, content)
+        except Exception as e:
+            logger.error(f"[Logger] 保存日志失败: {e}")
+
+    async def add_log(self, 
+                     ip: str, 
+                     model: str, 
+                     duration: float, 
+                     status: int, 
+                     key_name: str, 
+                     token_suffix: str = "",
+                     error: str = ""):
+        """添加日志"""
+        if not self._loaded:
+            await self.init()
+            
+        try:
+            now = time.time()
+            # 格式化时间
+            time_str = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(now))
+            
+            log = {
+                "id": str(int(now * 1000)),
+                "time": time_str,
+                "timestamp": now,
+                "ip": ip,
+                "model": model,
+                "duration": round(duration, 2),
+                "status": status,
+                "key_name": key_name,
+                "token_suffix": token_suffix,
+                "error": error
+            }
+            
+            async with self._lock:
+                self._logs.appendleft(log) # 最新的在前
+                
+            # 异步保存
+            asyncio.create_task(self._save_data())
+                
+        except Exception as e:
+            logger.error(f"[Logger] 记录日志失败: {e}")
+
+    async def get_logs(self, limit: int = 1000) -> List[Dict]:
+        """获取日志"""
+        async with self._lock:
+            return list(self._logs)[:limit]
+    
+    async def clear_logs(self):
+        """清空日志"""
+        async with self._lock:
+            self._logs.clear()
+        await self._save_data()
+
+
+# 全局实例
+request_logger = RequestLogger()

app/services/request_stats.py

@@ -0,0 +1,205 @@
+"""请求统计模块 - 按小时/天统计请求数据"""
+
+import time
+import asyncio
+import orjson
+from datetime import datetime
+from typing import Dict, Any
+from pathlib import Path
+from collections import defaultdict
+
+from app.core.logger import logger
+
+
+class RequestStats:
+    """请求统计管理器（单例）"""
+    
+    _instance = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+    
+    def __init__(self):
+        if hasattr(self, '_initialized'):
+            return
+        
+        self.file_path = Path(__file__).parents[2] / "data" / "stats.json"
+        
+        # 统计数据
+        self._hourly: Dict[str, Dict[str, int]] = defaultdict(lambda: {"total": 0, "success": 0, "failed": 0})
+        self._daily: Dict[str, Dict[str, int]] = defaultdict(lambda: {"total": 0, "success": 0, "failed": 0})
+        self._models: Dict[str, int] = defaultdict(int)
+        
+        # 保留策略
+        self._hourly_keep = 48  # 保留48小时
+        self._daily_keep = 30   # 保留30天
+        
+        self._lock = asyncio.Lock()
+        self._loaded = False
+        self._initialized = True
+
+    async def init(self):
+        """初始化加载数据"""
+        if not self._loaded:
+            await self._load_data()
+
+    async def _load_data(self):
+        """从磁盘加载统计数据"""
+        if self._loaded:
+            return
+
+        if not self.file_path.exists():
+            self._loaded = True
+            return
+
+        try:
+            async with self._lock:
+                content = await asyncio.to_thread(self.file_path.read_bytes)
+                if content:
+                    data = orjson.loads(content)
+                    
+                    # 恢复 defaultdict 结构
+                    self._hourly = defaultdict(lambda: {"total": 0, "success": 0, "failed": 0})
+                    self._hourly.update(data.get("hourly", {}))
+                    
+                    self._daily = defaultdict(lambda: {"total": 0, "success": 0, "failed": 0})
+                    self._daily.update(data.get("daily", {}))
+                    
+                    self._models = defaultdict(int)
+                    self._models.update(data.get("models", {}))
+                    
+                    self._loaded = True
+                    logger.debug(f"[Stats] 加载统计数据成功")
+        except Exception as e:
+            logger.error(f"[Stats] 加载数据失败: {e}")
+            self._loaded = True # 防止覆盖
+
+    async def _save_data(self):
+        """保存统计数据到磁盘"""
+        if not self._loaded:
+            return
+
+        try:
+            # 确保目录存在
+            self.file_path.parent.mkdir(parents=True, exist_ok=True)
+            
+            async with self._lock:
+                data = {
+                    "hourly": dict(self._hourly),
+                    "daily": dict(self._daily),
+                    "models": dict(self._models)
+                }
+                content = orjson.dumps(data)
+                await asyncio.to_thread(self.file_path.write_bytes, content)
+        except Exception as e:
+            logger.error(f"[Stats] 保存数据失败: {e}")
+    
+    async def record_request(self, model: str, success: bool) -> None:
+        """记录一次请求"""
+        if not self._loaded:
+            await self.init()
+            
+        now = datetime.now()
+        hour_key = now.strftime("%Y-%m-%dT%H")
+        day_key = now.strftime("%Y-%m-%d")
+        
+        # 小时统计
+        self._hourly[hour_key]["total"] += 1
+        if success:
+            self._hourly[hour_key]["success"] += 1
+        else:
+            self._hourly[hour_key]["failed"] += 1
+        
+        # 天统计
+        self._daily[day_key]["total"] += 1
+        if success:
+            self._daily[day_key]["success"] += 1
+        else:
+            self._daily[day_key]["failed"] += 1
+        
+        # 模型统计
+        self._models[model] += 1
+        
+        # 定期清理旧数据
+        self._cleanup()
+        
+        # 异步保存
+        asyncio.create_task(self._save_data())
+    
+    def _cleanup(self) -> None:
+        """清理过期数据"""
+        now = datetime.now()
+        
+        # 清理小时数据
+        hour_keys = list(self._hourly.keys())
+        if len(hour_keys) > self._hourly_keep:
+            for key in sorted(hour_keys)[:-self._hourly_keep]:
+                del self._hourly[key]
+        
+        # 清理天数据
+        day_keys = list(self._daily.keys())
+        if len(day_keys) > self._daily_keep:
+            for key in sorted(day_keys)[:-self._daily_keep]:
+                del self._daily[key]
+    
+    def get_stats(self, hours: int = 24, days: int = 7) -> Dict[str, Any]:
+        """获取统计数据"""
+        now = datetime.now()
+        
+        # 获取最近N小时数据
+        hourly_data = []
+        for i in range(hours - 1, -1, -1):
+            from datetime import timedelta
+            dt = now - timedelta(hours=i)
+            key = dt.strftime("%Y-%m-%dT%H")
+            data = self._hourly.get(key, {"total": 0, "success": 0, "failed": 0})
+            hourly_data.append({
+                "hour": dt.strftime("%H:00"),
+                "date": dt.strftime("%m-%d"),
+                **data
+            })
+        
+        # 获取最近N天数据
+        daily_data = []
+        for i in range(days - 1, -1, -1):
+            from datetime import timedelta
+            dt = now - timedelta(days=i)
+            key = dt.strftime("%Y-%m-%d")
+            data = self._daily.get(key, {"total": 0, "success": 0, "failed": 0})
+            daily_data.append({
+                "date": dt.strftime("%m-%d"),
+                **data
+            })
+        
+        # 模型统计（取 Top 10）
+        model_data = sorted(self._models.items(), key=lambda x: x[1], reverse=True)[:10]
+        
+        # 总计
+        total_requests = sum(d["total"] for d in self._hourly.values())
+        total_success = sum(d["success"] for d in self._hourly.values())
+        total_failed = sum(d["failed"] for d in self._hourly.values())
+        
+        return {
+            "hourly": hourly_data,
+            "daily": daily_data,
+            "models": [{"model": m, "count": c} for m, c in model_data],
+            "summary": {
+                "total": total_requests,
+                "success": total_success,
+                "failed": total_failed,
+                "success_rate": round(total_success / total_requests * 100, 1) if total_requests > 0 else 0
+            }
+        }
+    
+    async def reset(self) -> None:
+        """重置所有统计"""
+        self._hourly.clear()
+        self._daily.clear()
+        self._models.clear()
+        await self._save_data()
+
+
+# 全局实例
+request_stats = RequestStats()

app/services/token/__init__.py

@@ -0,0 +1,36 @@
+"""Token 服务模块"""
+
+from app.services.token.models import (
+    TokenInfo,
+    TokenStatus,
+    TokenPoolStats,
+    EffortType,
+    DEFAULT_QUOTA,
+    EFFORT_COST
+)
+from app.services.token.pool import TokenPool
+from app.services.token.manager import TokenManager, get_token_manager
+from app.services.token.service import TokenService
+from app.services.token.scheduler import TokenRefreshScheduler, get_scheduler
+
+__all__ = [
+    # Models
+    "TokenInfo",
+    "TokenStatus", 
+    "TokenPoolStats", 
+    "EffortType", 
+    "DEFAULT_QUOTA",
+    "EFFORT_COST",
+    
+    # Core
+    "TokenPool",
+    "TokenManager",
+    
+    # API
+    "TokenService",
+    "get_token_manager",
+    
+    # Scheduler
+    "TokenRefreshScheduler",
+    "get_scheduler",
+]

app/services/token/manager.py

@@ -0,0 +1,654 @@
+"""Token 管理服务"""
+
+import asyncio
+import time
+from datetime import datetime
+from typing import Dict, List, Optional
+
+from app.core.logger import logger
+from app.services.token.models import TokenInfo, EffortType, TokenPoolStats, FAIL_THRESHOLD, TokenStatus
+from app.core.storage import get_storage
+from app.core.config import get_config
+from app.services.token.pool import TokenPool
+
+# 批量刷新配置
+REFRESH_INTERVAL_HOURS = 8
+REFRESH_BATCH_SIZE = 10
+REFRESH_CONCURRENCY = 5
+
+
+class TokenManager:
+    """管理 Token 的增删改查和配额同步"""
+    
+    _instance: Optional["TokenManager"] = None
+    _lock = asyncio.Lock()
+    
+    def __init__(self):
+        self.pools: Dict[str, TokenPool] = {}
+        self.initialized = False
+        self._save_lock = asyncio.Lock()
+        self._dirty = False
+        self._save_task: Optional[asyncio.Task] = None
+        self._save_delay = 0.5
+        self._last_reload_at = 0.0
+    
+    @classmethod
+    async def get_instance(cls) -> "TokenManager":
+        """获取单例实例"""
+        if cls._instance is None:
+            async with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+                    await cls._instance._load()
+        return cls._instance
+
+    async def _load(self):
+        """初始化加载"""
+        if not self.initialized:
+            try:
+                storage = get_storage()
+                data = await storage.load_tokens()
+                
+                # 如果后端返回 None 或空数据，尝试从本地 data/token.json 初始化后端
+                if not data:
+                    from app.core.storage import LocalStorage
+                    local_storage = LocalStorage()
+                    local_data = await local_storage.load_tokens()
+                    if local_data:
+                        data = local_data
+                        await storage.save_tokens(local_data)
+                        logger.info(f"Initialized remote token storage ({storage.__class__.__name__}) with local tokens.")
+                    else:
+                        data = {}
+
+                self.pools = {}
+                for pool_name, tokens in data.items():
+                    pool = TokenPool(pool_name)
+                    for token_data in tokens:
+                        try:
+                            # 统一存储裸 token
+                            if isinstance(token_data, dict):
+                                raw_token = token_data.get("token")
+                                if isinstance(raw_token, str) and raw_token.startswith("sso="):
+                                    token_data["token"] = raw_token[4:]
+                            token_info = TokenInfo(**token_data)
+                            pool.add(token_info)
+                        except Exception as e:
+                            logger.warning(f"Failed to load token in pool '{pool_name}': {e}")
+                            continue
+                    pool._rebuild_index()
+                    self.pools[pool_name] = pool
+                    
+                self.initialized = True
+                self._last_reload_at = time.monotonic()
+                total = sum(p.count() for p in self.pools.values())
+                logger.info(f"TokenManager initialized: {len(self.pools)} pools with {total} tokens")
+            except Exception as e:
+                logger.error(f"Failed to initialize TokenManager: {e}")
+                self.pools = {}
+                self.initialized = True
+
+    async def reload(self):
+        """重新加载 Token 池数据"""
+        async with self.__class__._lock:
+            self.initialized = False
+            await self._load()
+
+    async def reload_if_stale(self):
+        """在多 worker 场景下保持短周期一致性"""
+        interval = get_config("token.reload_interval_sec", 30)
+        try:
+            interval = float(interval)
+        except Exception:
+            interval = 30.0
+        if interval <= 0:
+            return
+        if time.monotonic() - self._last_reload_at < interval:
+            return
+        await self.reload()
+
+    async def _save(self):
+        """保存变更"""
+        async with self._save_lock:
+            try:
+                data = {}
+                for pool_name, pool in self.pools.items():
+                    data[pool_name] = [
+                        info.model_dump() for info in pool.list()
+                    ]
+                
+                storage = get_storage()
+                async with storage.acquire_lock("tokens_save", timeout=10):
+                    await storage.save_tokens(data)
+            except Exception as e:
+                logger.error(f"Failed to save tokens: {e}")
+
+    def _schedule_save(self):
+        """合并高频保存请求，减少写入开销"""
+        delay_ms = get_config("token.save_delay_ms", 500)
+        try:
+            delay_ms = float(delay_ms)
+        except Exception:
+            delay_ms = 500
+        self._save_delay = max(0.0, delay_ms / 1000.0)
+        self._dirty = True
+        if self._save_delay == 0:
+            if self._save_task and not self._save_task.done():
+                return
+            self._save_task = asyncio.create_task(self._save())
+            return
+        if self._save_task and not self._save_task.done():
+            return
+        self._save_task = asyncio.create_task(self._flush_loop())
+
+    async def _flush_loop(self):
+        try:
+            while True:
+                await asyncio.sleep(self._save_delay)
+                if not self._dirty:
+                    break
+                self._dirty = False
+                await self._save()
+        finally:
+            self._save_task = None
+            if self._dirty:
+                self._schedule_save()
+
+    @staticmethod
+    def _extract_cookie_value(cookie_str: str, name: str) -> str | None:
+        needle = f"{name}="
+        if needle not in cookie_str:
+            return None
+        for part in cookie_str.split(";"):
+            part = part.strip()
+            if part.startswith(needle):
+                value = part[len(needle):].strip()
+                return value or None
+        return None
+
+    @classmethod
+    def _normalize_input_token(cls, token_str: str) -> str:
+        raw = str(token_str or "").strip()
+        if not raw:
+            return ""
+        if ";" in raw:
+            return (cls._extract_cookie_value(raw, "sso") or "").strip()
+        if raw.startswith("sso="):
+            return raw[4:].strip()
+        return raw
+
+    def _find_token_info(self, token_str: str) -> tuple[Optional[TokenInfo], str]:
+        raw_token = self._normalize_input_token(token_str)
+        if not raw_token:
+            return None, ""
+        for pool in self.pools.values():
+            token = pool.get(raw_token)
+            if token:
+                return token, raw_token
+        return None, raw_token
+
+    def get_token(self, pool_name: str = "ssoBasic") -> Optional[str]:
+        """
+        获取可用 Token
+        
+        Args:
+            pool_name: Token 池名称
+            
+        Returns:
+            Token 字符串或 None
+        """
+        pool = self.pools.get(pool_name)
+        if not pool:
+            logger.warning(f"Pool '{pool_name}' not found")
+            return None
+            
+        token_info = pool.select()
+        if not token_info:
+            logger.warning(f"No available token in pool '{pool_name}'")
+            return None
+            
+        token = token_info.token
+        if token.startswith("sso="):
+            return token[4:]
+        return token
+
+    def get_token_for_model(self, model_id: str) -> Optional[str]:
+        """按模型选择可用 Token（包含 basic->super 回退与 heavy 配额桶选择）。"""
+        from app.services.grok.model import ModelService
+
+        bucket = "heavy" if ModelService.is_heavy_bucket_model(model_id) else "normal"
+        for pool_name in ModelService.pool_candidates_for_model(model_id):
+            pool = self.pools.get(pool_name)
+            if not pool:
+                continue
+            token_info = pool.select(bucket=bucket)
+            if not token_info:
+                continue
+            token = token_info.token
+            return token[4:] if token.startswith("sso=") else token
+
+        logger.warning(f"No available token for model '{model_id}'")
+        return None
+
+    async def consume(self, token_str: str, effort: EffortType = EffortType.LOW, bucket: str = "normal") -> bool:
+        """
+        消耗配额（本地预估）
+        
+        Args:
+            token_str: Token 字符串
+            effort: 消耗力度
+            
+        Returns:
+            是否成功
+        """
+        raw_token = token_str.replace("sso=", "")
+
+        for pool in self.pools.values():
+            token = pool.get(raw_token)
+            if token:
+                consumed = token.consume_heavy(effort) if bucket == "heavy" else token.consume(effort)
+                logger.debug(
+                    f"Token {raw_token[:10]}...: consumed {consumed} quota (bucket={bucket}), use_count={token.use_count}"
+                )
+                self._schedule_save()
+                return True
+        
+        logger.warning(f"Token {raw_token[:10]}...: not found for consumption")
+        return False
+
+    async def sync_usage(
+        self, 
+        token_str: str, 
+        model_id: str, 
+        fallback_effort: EffortType = EffortType.LOW,
+        consume_on_fail: bool = True,
+        is_usage: bool = True
+    ) -> bool:
+        """
+        同步 Token 用量
+        
+        优先从 API 获取最新配额，失败则降级到本地预估
+        
+        Args:
+            token_str: Token 字符串（可带 sso= 前缀）
+            model_name: 模型名称（用于 API 查询）
+            fallback_effort: 降级时的消耗力度
+            consume_on_fail: 失败时是否降��扣费
+            is_usage: 是否记录为一次使用（影响 use_count）
+            
+        Returns:
+            是否成功
+        """
+        raw_token = token_str.replace("sso=", "")
+        
+        # 查找 Token 对象
+        target_token: Optional[TokenInfo] = None
+        for pool in self.pools.values():
+            target_token = pool.get(raw_token)
+            if target_token:
+                break
+        
+        if not target_token:
+            logger.warning(f"Token {raw_token[:10]}...: not found for sync")
+            return False
+
+        from app.services.grok.model import ModelService
+
+        bucket = "heavy" if ModelService.is_heavy_bucket_model(model_id) else "normal"
+        rate_limit_model = ModelService.rate_limit_model_for(model_id)
+
+        # 尝试 API 同步
+        try:
+            from app.services.grok.usage import UsageService
+            
+            usage_service = UsageService()
+            result = await usage_service.get(token_str, model_name=rate_limit_model)
+            
+            if result and "remainingTokens" in result:
+                try:
+                    new_quota = int(result["remainingTokens"])
+                except Exception:
+                    new_quota = 0
+
+                if bucket == "heavy":
+                    old_quota = target_token.heavy_quota
+                    target_token.update_heavy_quota(new_quota)
+                else:
+                    old_quota = target_token.quota
+                    target_token.update_quota(new_quota)
+
+                target_token.record_success(is_usage=is_usage)
+
+                consumed = max(0, old_quota - new_quota) if old_quota >= 0 else 0
+                logger.info(
+                    f"Token {raw_token[:10]}...: synced quota (bucket={bucket}, model={rate_limit_model}) "
+                    f"{old_quota} -> {new_quota} (consumed: {consumed}, use_count: {target_token.use_count})"
+                )
+                
+                self._schedule_save()
+                return True
+                
+        except Exception as e:
+            logger.warning(f"Token {raw_token[:10]}...: API sync failed, fallback to local ({e})")
+            
+        # 降级：本地预估扣费
+        if consume_on_fail:
+            logger.debug(f"Token {raw_token[:10]}...: using local consumption")
+            return await self.consume(token_str, fallback_effort, bucket=bucket)
+        else:
+            logger.debug(f"Token {raw_token[:10]}...: sync failed, skipping local consumption")
+            return False
+
+    async def record_fail(self, token_str: str, status_code: int = 401, reason: str = "") -> bool:
+        """
+        记录 Token 失败
+        
+        Args:
+            token_str: Token 字符串
+            status_code: HTTP 状态码
+            reason: 失败原因
+            
+        Returns:
+            是否成功
+        """
+        raw_token = token_str.replace("sso=", "")
+        
+        for pool in self.pools.values():
+            token = pool.get(raw_token)
+            if token:
+                if status_code == 401:
+                    token.record_fail(status_code, reason)
+                    logger.warning(
+                        f"Token {raw_token[:10]}...: recorded 401 failure "
+                        f"({token.fail_count}/{FAIL_THRESHOLD}) - {reason}"
+                    )
+                else:
+                    logger.info(
+                        f"Token {raw_token[:10]}...: non-401 error ({status_code}) - {reason} (not counted)"
+                    )
+                self._schedule_save()
+                return True
+        
+        logger.warning(f"Token {raw_token[:10]}...: not found for failure record")
+        return False
+
+    # ========== 管理功能 ==========
+
+    async def add(self, token: str, pool_name: str = "ssoBasic") -> bool:
+        """
+        添加 Token
+        
+        Args:
+            token: Token 字符串（不含 sso= 前缀）
+            pool_name: 池名称
+            
+        Returns:
+            是否成功
+        """
+        if pool_name not in self.pools:
+            self.pools[pool_name] = TokenPool(pool_name)
+            logger.info(f"Pool '{pool_name}': created")
+            
+        pool = self.pools[pool_name]
+        
+        token = token[4:] if token.startswith("sso=") else token
+        if pool.get(token):
+            logger.warning(f"Pool '{pool_name}': token already exists")
+            return False
+            
+        pool.add(TokenInfo(token=token))
+        await self._save()
+        logger.info(f"Pool '{pool_name}': token added")
+        return True
+
+    async def mark_asset_clear(self, token: str) -> bool:
+        """Record online asset cleanup timestamp."""
+        info, _ = self._find_token_info(token)
+        if info:
+            info.last_asset_clear_at = int(datetime.now().timestamp() * 1000)
+            self._schedule_save()
+            return True
+        return False
+
+    async def set_token_invalid(self, token_str: str, reason: str = "", save: bool = True) -> bool:
+        """Mark a token as expired/invalid."""
+        token, raw_token = self._find_token_info(token_str)
+        if not token:
+            logger.warning(f"Token {raw_token[:10]}...: not found for invalidation")
+            return False
+
+        token.status = TokenStatus.EXPIRED
+        token.fail_count = max(token.fail_count, FAIL_THRESHOLD)
+        token.last_fail_at = int(datetime.now().timestamp() * 1000)
+        if reason:
+            token.last_fail_reason = str(reason)[:500]
+
+        if save:
+            await self._save()
+        return True
+
+    async def mark_token_account_settings_success(self, token_str: str, save: bool = True) -> bool:
+        """Reset failure state after account-settings flow succeeded."""
+        token, raw_token = self._find_token_info(token_str)
+        if not token:
+            logger.warning(f"Token {raw_token[:10]}...: not found for account-settings success")
+            return False
+
+        token.fail_count = 0
+        token.last_fail_at = None
+        token.last_fail_reason = None
+        token.last_sync_at = int(datetime.now().timestamp() * 1000)
+        token.status = TokenStatus.COOLING if token.quota == 0 else TokenStatus.ACTIVE
+
+        if save:
+            await self._save()
+        return True
+
+    async def commit(self):
+        """Persist current in-memory token state."""
+        await self._save()
+
+    async def remove(self, token: str) -> bool:
+        """
+        删除 Token
+        
+        Args:
+            token: Token 字符串
+            
+        Returns:
+            是否成功
+        """
+        for pool_name, pool in self.pools.items():
+            if pool.remove(token):
+                await self._save()
+                logger.info(f"Pool '{pool_name}': token removed")
+                return True
+        
+        logger.warning(f"Token not found for removal")
+        return False
+
+    async def reset_all(self):
+        """重置所有 Token 配额"""
+        count = 0
+        for pool in self.pools.values():
+            for token in pool:
+                token.reset()
+                count += 1
+        
+        await self._save()
+        logger.info(f"Reset all: {count} tokens updated")
+
+    async def reset_token(self, token_str: str) -> bool:
+        """
+        重置单个 Token
+        
+        Args:
+            token_str: Token 字符串
+            
+        Returns:
+            是否成功
+        """
+        raw_token = token_str.replace("sso=", "")
+        
+        for pool in self.pools.values():
+            token = pool.get(raw_token)
+            if token:
+                token.reset()
+                await self._save()
+                logger.info(f"Token {raw_token[:10]}...: reset completed")
+                return True
+        
+        logger.warning(f"Token {raw_token[:10]}...: not found for reset")
+        return False
+
+    def get_stats(self) -> Dict[str, dict]:
+        """获取统计信息"""
+        stats = {}
+        for name, pool in self.pools.items():
+            pool_stats = pool.get_stats()
+            stats[name] = pool_stats.model_dump()
+        return stats
+    
+    def get_pool_tokens(self, pool_name: str = "ssoBasic") -> List[TokenInfo]:
+        """
+        获取指定池的所有 Token
+        
+        Args:
+            pool_name: 池名称
+            
+        Returns:
+            Token 列表
+        """
+        pool = self.pools.get(pool_name)
+        if not pool:
+            return []
+        return pool.list()
+    
+    async def refresh_cooling_tokens(self) -> Dict[str, int]:
+        """
+        批量刷新 cooling 状态的 Token 配额
+        
+        Returns:
+            {"checked": int, "refreshed": int, "recovered": int, "expired": int}
+        """
+        from app.services.grok.usage import UsageService
+        
+        # 收集需要刷新的 token
+        to_refresh: List[TokenInfo] = []
+        for pool in self.pools.values():
+            for token in pool:
+                if token.need_refresh(REFRESH_INTERVAL_HOURS):
+                    to_refresh.append(token)
+        
+        if not to_refresh:
+            logger.debug("Refresh check: no tokens need refresh")
+            return {"checked": 0, "refreshed": 0, "recovered": 0, "expired": 0}
+        
+        logger.info(f"Refresh check: found {len(to_refresh)} cooling tokens to refresh")
+        
+        # 批量并发刷新
+        semaphore = asyncio.Semaphore(REFRESH_CONCURRENCY)
+        usage_service = UsageService()
+        refreshed = 0
+        recovered = 0
+        expired = 0
+        
+        async def _refresh_one(token_info: TokenInfo) -> dict:
+            """刷新单个 token"""
+            async with semaphore:
+                token_str = token_info.token
+                if token_str.startswith("sso="):
+                    token_str = token_str[4:]
+                
+                # 重试逻辑：最多 2 次重试
+                for retry in range(3):  # 0, 1, 2
+                    try:
+                        result = await usage_service.get(token_str)
+                        
+                        if result and "remainingTokens" in result:
+                            new_quota = result["remainingTokens"]
+                            old_quota = token_info.quota
+                            old_status = token_info.status
+                            
+                            token_info.update_quota(new_quota)
+                            token_info.mark_synced()
+                            
+                            logger.info(
+                                f"Token {token_info.token[:10]}...: refreshed "
+                                f"{old_quota} -> {new_quota}, status: {old_status} -> {token_info.status}"
+                            )
+                            
+                            return {
+                                "recovered": new_quota > 0 and old_quota == 0,
+                                "expired": False
+                            }
+                        
+                        token_info.mark_synced()
+                        return {"recovered": False, "expired": False}
+                        
+                    except Exception as e:
+                        error_str = str(e)
+                        
+                        # 检查是否为 401 错误
+                        if "401" in error_str or "Unauthorized" in error_str:
+                            if retry < 2:
+                                logger.warning(
+                                    f"Token {token_info.token[:10]}...: 401 error, "
+                                    f"retry {retry + 1}/2..."
+                                )
+                                await asyncio.sleep(0.5)
+                                continue
+                            else:
+                                # 重试 2 次后仍然 401，标记为 expired
+                                logger.error(
+                                    f"Token {token_info.token[:10]}...: 401 after 2 retries, "
+                                    f"marking as expired"
+                                )
+                                token_info.status = TokenStatus.EXPIRED
+                                token_info.mark_synced()
+                                return {"recovered": False, "expired": True}
+                        else:
+                            logger.warning(
+                                f"Token {token_info.token[:10]}...: refresh failed ({e})"
+                            )
+                            token_info.mark_synced()
+                            return {"recovered": False, "expired": False}
+                
+                token_info.mark_synced()
+                return {"recovered": False, "expired": False}
+        
+        # 批量处理
+        for i in range(0, len(to_refresh), REFRESH_BATCH_SIZE):
+            batch = to_refresh[i:i + REFRESH_BATCH_SIZE]
+            results = await asyncio.gather(*[_refresh_one(t) for t in batch])
+            refreshed += len(batch)
+            recovered += sum(r["recovered"] for r in results)
+            expired += sum(r["expired"] for r in results)
+            
+            # 批次间延迟
+            if i + REFRESH_BATCH_SIZE < len(to_refresh):
+                await asyncio.sleep(1)
+        
+        await self._save()
+        
+        logger.info(
+            f"Refresh completed: "
+            f"checked={len(to_refresh)}, refreshed={refreshed}, "
+            f"recovered={recovered}, expired={expired}"
+        )
+        
+        return {
+            "checked": len(to_refresh),
+            "refreshed": refreshed,
+            "recovered": recovered,
+            "expired": expired
+        }
+
+
+# 便捷函数
+async def get_token_manager() -> TokenManager:
+    """获取 TokenManager 单例"""
+    return await TokenManager.get_instance()
+
+
+__all__ = ["TokenManager", "get_token_manager"]

app/services/token/models.py

@@ -0,0 +1,221 @@
+"""
+Token 数据模型
+
+额度规则:
+- 新号默认 80 配额
+- 重置后恢复 80
+- lowEffort 扣 1，highEffort 扣 4
+"""
+
+from enum import Enum
+from typing import Optional, List
+from pydantic import BaseModel, Field
+from datetime import datetime
+
+
+# 默认配额
+DEFAULT_QUOTA = 80
+
+# 失败阈值
+FAIL_THRESHOLD = 5
+
+
+class TokenStatus(str, Enum):
+    """Token 状态"""
+    ACTIVE = "active"
+    DISABLED = "disabled"
+    EXPIRED = "expired"
+    COOLING = "cooling"
+
+
+class EffortType(str, Enum):
+    """请求消耗类型"""
+    LOW = "low"    # 扣 1
+    HIGH = "high"  # 扣 4
+
+
+EFFORT_COST = {
+    EffortType.LOW: 1,
+    EffortType.HIGH: 4,
+}
+
+
+class TokenInfo(BaseModel):
+    """Token 信息"""
+    
+    token: str
+    status: TokenStatus = TokenStatus.ACTIVE
+    quota: int = DEFAULT_QUOTA
+    heavy_quota: int = -1
+    
+    # 统计
+    created_at: int = Field(default_factory=lambda: int(datetime.now().timestamp() * 1000))
+    last_used_at: Optional[int] = None
+    use_count: int = 0
+    
+    # 失败追踪
+    fail_count: int = 0
+    last_fail_at: Optional[int] = None
+    last_fail_reason: Optional[str] = None
+    
+    # 冷却管理
+    last_sync_at: Optional[int] = None  # 上次同步时间
+    
+    # 扩展
+    tags: List[str] = Field(default_factory=list)
+    note: str = ""
+    last_asset_clear_at: Optional[int] = None
+    
+    def is_available(self) -> bool:
+        """检查是否可用（状态正常且配额 > 0）"""
+        return self.status == TokenStatus.ACTIVE and self.quota > 0
+    
+    def consume(self, effort: EffortType = EffortType.LOW) -> int:
+        """
+        消耗配额
+        
+        Args:
+            effort: LOW 扣 1，HIGH 扣 4
+            
+        Returns:
+            实际扣除的配额
+        """
+        cost = EFFORT_COST[effort]
+        actual_cost = min(cost, self.quota)
+        
+        self.last_used_at = int(datetime.now().timestamp() * 1000)
+        self.use_count += 1
+        self.quota = max(0, self.quota - cost)
+        
+        # 成功消耗后清空失败计数
+        self.fail_count = 0
+        self.last_fail_reason = None
+        
+        if self.quota == 0:
+            self.status = TokenStatus.COOLING
+        elif self.status in [TokenStatus.COOLING, TokenStatus.EXPIRED]:
+            self.status = TokenStatus.ACTIVE
+            
+        return actual_cost
+    
+    def update_quota(self, new_quota: int):
+        """
+        更新配额（用于 API 同步）
+        
+        Args:
+            new_quota: 新的配额值
+        """
+        self.quota = max(0, new_quota)
+        
+        if self.quota == 0:
+            self.status = TokenStatus.COOLING
+        elif self.quota > 0 and self.status in [TokenStatus.COOLING, TokenStatus.EXPIRED]:
+            self.status = TokenStatus.ACTIVE
+
+    def update_heavy_quota(self, new_quota: int):
+        """
+        更新 heavy 配额（用于 grok-4-heavy 的 rate-limits 同步）。
+
+        注意：heavy 配额不参与 status 计算，避免误伤普通模型可用性。
+        """
+        try:
+            v = int(new_quota)
+        except Exception:
+            v = 0
+        self.heavy_quota = max(0, v)
+
+    def consume_heavy(self, effort: EffortType = EffortType.LOW) -> int:
+        """
+        消耗 heavy 配额（本地预估）。
+
+        当 heavy_quota 为 -1（未知）时，不扣减配额，仅记录一次使用。
+        """
+        cost = EFFORT_COST[effort]
+
+        self.last_used_at = int(datetime.now().timestamp() * 1000)
+        self.use_count += 1
+
+        # 成功消耗后清空失败计数
+        self.fail_count = 0
+        self.last_fail_reason = None
+
+        if self.heavy_quota < 0:
+            return 0
+
+        actual_cost = min(cost, self.heavy_quota)
+        self.heavy_quota = max(0, self.heavy_quota - actual_cost)
+        return actual_cost
+
+    def reset(self):
+        """重置配额到默认值"""
+        self.quota = DEFAULT_QUOTA
+        self.heavy_quota = -1
+        self.status = TokenStatus.ACTIVE
+        self.fail_count = 0
+        self.last_fail_reason = None
+    
+    def record_fail(self, status_code: int = 401, reason: str = ""):
+        """记录失败，达到阈值后自动标记为 expired"""
+        # 仅 401 错误才计入失败
+        if status_code != 401:
+            return
+        
+        self.fail_count += 1
+        self.last_fail_at = int(datetime.now().timestamp() * 1000)
+        self.last_fail_reason = reason
+        
+        if self.fail_count >= FAIL_THRESHOLD:
+            self.status = TokenStatus.EXPIRED
+    
+    def record_success(self, is_usage: bool = True):
+        """记录成功，清空失败计数并根据配额更新状态"""
+        self.fail_count = 0
+        self.last_fail_at = None
+        self.last_fail_reason = None
+        
+        if is_usage:
+            self.use_count += 1
+            self.last_used_at = int(datetime.now().timestamp() * 1000)
+        
+        if self.quota == 0:
+            self.status = TokenStatus.COOLING
+        else:
+            self.status = TokenStatus.ACTIVE
+    
+    def need_refresh(self, interval_hours: int = 8) -> bool:
+        """检查是否需要刷新配额"""
+        if self.status != TokenStatus.COOLING:
+            return False
+        
+        if self.last_sync_at is None:
+            return True
+        
+        now = int(datetime.now().timestamp() * 1000)
+        interval_ms = interval_hours * 3600 * 1000
+        return (now - self.last_sync_at) >= interval_ms
+    
+    def mark_synced(self):
+        """标记已同步"""
+        self.last_sync_at = int(datetime.now().timestamp() * 1000)
+
+
+class TokenPoolStats(BaseModel):
+    """Token 池统计"""
+    total: int = 0
+    active: int = 0
+    disabled: int = 0
+    expired: int = 0
+    cooling: int = 0
+    total_quota: int = 0
+    avg_quota: float = 0.0
+
+
+__all__ = [
+    "TokenStatus",
+    "TokenInfo",
+    "TokenPoolStats",
+    "EffortType",
+    "EFFORT_COST",
+    "DEFAULT_QUOTA",
+    "FAIL_THRESHOLD",
+]

app/services/token/pool.py

@@ -0,0 +1,112 @@
+"""Token 池管理"""
+
+import random
+from typing import Dict, List, Optional, Iterator
+
+from app.services.token.models import TokenInfo, TokenStatus, TokenPoolStats
+
+
+class TokenPool:
+    """Token 池（管理一组 Token）"""
+    
+    def __init__(self, name: str):
+        self.name = name
+        self._tokens: Dict[str, TokenInfo] = {}
+    
+    def add(self, token: TokenInfo):
+        """添加 Token"""
+        self._tokens[token.token] = token
+    
+    def remove(self, token_str: str) -> bool:
+        """删除 Token"""
+        if token_str in self._tokens:
+            del self._tokens[token_str]
+            return True
+        return False
+        
+    def get(self, token_str: str) -> Optional[TokenInfo]:
+        """获取 Token"""
+        return self._tokens.get(token_str)
+        
+    def select(self, bucket: str = "normal") -> Optional[TokenInfo]:
+        """
+        选择一个可用 Token
+        策略: 
+        1. 选择 active 状态且有配额的 token
+        2. 优先选择剩余额度最多的
+        3. 如果额度相同，随机选择（避免并发冲突）
+        """
+        # 选择 token
+        if bucket == "heavy":
+            available = [
+                t
+                for t in self._tokens.values()
+                if t.status in (TokenStatus.ACTIVE, TokenStatus.COOLING) and t.heavy_quota != 0
+            ]
+
+            if not available:
+                return None
+
+            unknown = [t for t in available if t.heavy_quota < 0]
+            if unknown:
+                return random.choice(unknown)
+
+            max_quota = max(t.heavy_quota for t in available)
+            candidates = [t for t in available if t.heavy_quota == max_quota]
+            return random.choice(candidates)
+
+        available = [
+            t for t in self._tokens.values() 
+            if t.status == TokenStatus.ACTIVE and t.quota > 0
+        ]
+        
+        if not available:
+            return None
+            
+        # 找到最大额度
+        max_quota = max(t.quota for t in available)
+        
+        # 筛选最大额度
+        candidates = [t for t in available if t.quota == max_quota]
+        
+        # 随机选择
+        return random.choice(candidates)
+        
+    def count(self) -> int:
+        """Token 数量"""
+        return len(self._tokens)
+        
+    def list(self) -> List[TokenInfo]:
+        """获取所有 Token"""
+        return list(self._tokens.values())
+    
+    def get_stats(self) -> TokenPoolStats:
+        """获取池统计信息"""
+        stats = TokenPoolStats(total=len(self._tokens))
+        
+        for token in self._tokens.values():
+            stats.total_quota += token.quota
+            
+            if token.status == TokenStatus.ACTIVE:
+                stats.active += 1
+            elif token.status == TokenStatus.DISABLED:
+                stats.disabled += 1
+            elif token.status == TokenStatus.EXPIRED:
+                stats.expired += 1
+            elif token.status == TokenStatus.COOLING:
+                stats.cooling += 1
+        
+        if stats.total > 0:
+            stats.avg_quota = stats.total_quota / stats.total
+            
+        return stats
+        
+    def _rebuild_index(self):
+        """重建索引（预留接口，用于加载时调用）"""
+        pass
+        
+    def __iter__(self) -> Iterator[TokenInfo]:
+        return iter(self._tokens.values())
+
+
+__all__ = ["TokenPool"]

app/services/token/scheduler.py

@@ -0,0 +1,104 @@
+"""Token 刷新调度器"""
+
+import asyncio
+from typing import Optional
+
+from app.core.logger import logger
+from app.core.storage import get_storage, StorageError, RedisStorage
+from app.services.token.manager import get_token_manager
+
+
+class TokenRefreshScheduler:
+    """Token 自动刷新调度器"""
+    
+    def __init__(self, interval_hours: int = 8):
+        self.interval_hours = interval_hours
+        self.interval_seconds = interval_hours * 3600
+        self._task: Optional[asyncio.Task] = None
+        self._running = False
+    
+    async def _refresh_loop(self):
+        """刷新循环"""
+        logger.info(f"Scheduler: started (interval: {self.interval_hours}h)")
+        
+        while self._running:
+            try:
+                await asyncio.sleep(self.interval_seconds)
+                storage = get_storage()
+                lock_acquired = False
+                lock = None
+
+                if isinstance(storage, RedisStorage):
+                    # Redis: non-blocking lock to avoid multi-worker duplication
+                    lock_key = "grok2api:lock:token_refresh"
+                    lock = storage.redis.lock(lock_key, timeout=self.interval_seconds + 60, blocking_timeout=0)
+                    lock_acquired = await lock.acquire(blocking=False)
+                else:
+                    try:
+                        async with storage.acquire_lock("token_refresh", timeout=0):
+                            lock_acquired = True
+                    except StorageError:
+                        lock_acquired = False
+
+                if not lock_acquired:
+                    logger.info("Scheduler: skipped (lock not acquired)")
+                    continue
+
+                try:
+                    logger.info("Scheduler: starting token refresh...")
+                    manager = await get_token_manager()
+                    result = await manager.refresh_cooling_tokens()
+                    
+                    logger.info(
+                        f"Scheduler: refresh completed - "
+                        f"checked={result['checked']}, "
+                        f"refreshed={result['refreshed']}, "
+                        f"recovered={result['recovered']}, "
+                        f"expired={result['expired']}"
+                    )
+                finally:
+                    if lock is not None and lock_acquired:
+                        try:
+                            await lock.release()
+                        except Exception:
+                            pass
+                
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Scheduler: refresh error - {e}")
+    
+    def start(self):
+        """启动调度器"""
+        if self._running:
+            logger.warning("Scheduler: already running")
+            return
+        
+        self._running = True
+        self._task = asyncio.create_task(self._refresh_loop())
+        logger.info("Scheduler: enabled")
+    
+    def stop(self):
+        """停止调度器"""
+        if not self._running:
+            return
+        
+        self._running = False
+        if self._task:
+            self._task.cancel()
+        logger.info("Scheduler: stopped")
+
+
+# 全局单例
+_scheduler: Optional[TokenRefreshScheduler] = None
+
+
+def get_scheduler(interval_hours: int = 8) -> TokenRefreshScheduler:
+    """获取调度器单例"""
+    global _scheduler
+    if _scheduler is None:
+        _scheduler = TokenRefreshScheduler(interval_hours)
+    return _scheduler
+
+
+__all__ = ["TokenRefreshScheduler", "get_scheduler"]

app/services/token/service.py

@@ -0,0 +1,156 @@
+"""Token 服务外观（Facade）"""
+
+from typing import List, Optional, Dict
+
+from app.services.token.manager import get_token_manager
+from app.services.token.models import TokenInfo, EffortType
+
+
+class TokenService:
+    """
+    Token 服务外观
+    
+    提供简化的 API，隐藏内部实现细节
+    """
+    
+    @staticmethod
+    async def get_token(pool_name: str = "ssoBasic") -> Optional[str]:
+        """
+        获取可用 Token
+        
+        Args:
+            pool_name: Token 池名称
+            
+        Returns:
+            Token 字符串（不含 sso= 前缀）或 None
+        """
+        manager = await get_token_manager()
+        return manager.get_token(pool_name)
+    
+    @staticmethod
+    async def consume(token: str, effort: EffortType = EffortType.LOW) -> bool:
+        """
+        消耗 Token 配额（本地预估）
+        
+        Args:
+            token: Token 字符串
+            effort: 消耗力度
+            
+        Returns:
+            是否成功
+        """
+        manager = await get_token_manager()
+        return await manager.consume(token, effort)
+    
+    @staticmethod
+    async def sync_usage(
+        token: str, 
+        model: str, 
+        effort: EffortType = EffortType.LOW
+    ) -> bool:
+        """
+        同步 Token 使用量（优先 API，降级本地）
+        
+        Args:
+            token: Token 字符串
+            model: 模型名称
+            effort: 降级时的消耗力度
+            
+        Returns:
+            是否成功
+        """
+        manager = await get_token_manager()
+        return await manager.sync_usage(token, model, effort)
+    
+    @staticmethod
+    async def record_fail(token: str, status_code: int = 401, reason: str = "") -> bool:
+        """
+        记录 Token 失败
+        
+        Args:
+            token: Token 字符串
+            status_code: HTTP 状态码
+            reason: 失败原因
+            
+        Returns:
+            是否成功
+        """
+        manager = await get_token_manager()
+        return await manager.record_fail(token, status_code, reason)
+    
+    @staticmethod
+    async def add_token(token: str, pool_name: str = "ssoBasic") -> bool:
+        """
+        添加 Token
+        
+        Args:
+            token: Token 字符串
+            pool: Token 池名称
+            
+        Returns:
+            是否成功
+        """
+        manager = await get_token_manager()
+        return await manager.add(token, pool_name)
+    
+    @staticmethod
+    async def remove_token(token: str) -> bool:
+        """
+        删除 Token
+        
+        Args:
+            token: Token 字符串
+            
+        Returns:
+            是否成功
+        """
+        manager = await get_token_manager()
+        return await manager.remove(token)
+    
+    @staticmethod
+    async def reset_token(token: str) -> bool:
+        """
+        重置单个 Token
+        
+        Args:
+            token: Token 字符串
+            
+        Returns:
+            是否成功
+        """
+        manager = await get_token_manager()
+        return await manager.reset_token(token)
+    
+    @staticmethod
+    async def reset_all():
+        """重置所有 Token"""
+        manager = await get_token_manager()
+        await manager.reset_all()
+    
+    @staticmethod
+    async def get_stats() -> Dict[str, dict]:
+        """
+        获取统计信息
+        
+        Returns:
+            各池的统计信息
+        """
+        manager = await get_token_manager()
+        return manager.get_stats()
+    
+    @staticmethod
+    async def list_tokens(pool_name: str = "ssoBasic") -> List[TokenInfo]:
+        """
+        获取指定池的所有 Token
+        
+        Args:
+            pool_name: Token 池名称
+            
+        Returns:
+            Token 列表
+        """
+        manager = await get_token_manager()
+        return manager.get_pool_tokens(pool_name)
+
+
+__all__ = ["TokenService"]

app/static/.assetsignore

@@ -0,0 +1,2 @@
+_worker.js
+

app/static/_worker.js

@@ -0,0 +1,4 @@
+import worker from "../../src/index.ts";
+
+export default worker;
+