style: 统一使用 PEP 604/585 现代类型语法

- Optional[X] → X | None
- Dict[X, Y] → dict[X, Y]
- List[X] → list[X]
- Tuple[X, Y] → tuple[X, Y]
- Set[X] → set[X]

涉及 10 个文件，共约 50 处改动。

src/api/handlers/base/base_handler.py

@@ -10,18 +10,18 @@
         self,
         request: Any,                           # 解析后的请求模型
         http_request: Request,                  # FastAPI Request 对象
-        original_headers: Dict[str, str],       # 原始请求头
-        original_request_body: Dict[str, Any],  # 原始请求体
-        query_params: Optional[Dict[str, str]] = None,  # 查询参数
+        original_headers: dict[str, str],       # 原始请求头
+        original_request_body: dict[str, Any],  # 原始请求体
+        query_params: dict[str, str] | None = None,  # 查询参数
     ) -> StreamingResponse: ...
 
     async def process_sync(
         self,
         request: Any,
         http_request: Request,
-        original_headers: Dict[str, str],
-        original_request_body: Dict[str, Any],
-        query_params: Optional[Dict[str, str]] = None,
+        original_headers: dict[str, str],
+        original_request_body: dict[str, Any],
+        query_params: dict[str, str] | None = None,
     ) -> JSONResponse: ...
 """
 

src/api/handlers/base/chat_adapter_base.py

@@ -565,7 +565,7 @@ class ChatAdapterBase(ApiAdapter):
                 "cache_cost": float,
                 "request_cost": float,
                 "total_cost": float,
-                "tier_index": Optional[int],  # 命中的阶梯索引
+                "tier_index": int | None,  # 命中的阶梯索引
             }
         """
         # 计算总输入上下文（使用子类可覆盖的方法）

src/api/handlers/gemini/adapter.py

@@ -61,9 +61,9 @@ class GeminiChatAdapter(ChatAdapterBase):
 
     def detect_capability_requirements(
         self,
-        headers: Dict[str, str],  # noqa: ARG002 - 预留
-        request_body: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, bool]:
+        headers: dict[str, str],  # noqa: ARG002 - 预留
+        request_body: dict[str, Any] | None = None,
+    ) -> dict[str, bool]:
         """检测是否需要 Gemini Files API 能力"""
         if request_body and extract_file_names_from_request(request_body):
             return {"gemini_files_api": True}

src/api/handlers/gemini/handler.py

@@ -27,8 +27,8 @@ class GeminiChatHandler(ChatHandlerBase):
     async def _resolve_preferred_key_ids(
         self,
         model_name: str,  # noqa: ARG002 - 仅做文件绑定
-        request_body: Optional[Dict[str, Any]] = None,
-    ) -> Optional[list[str]]:
+        request_body: dict[str, Any] | None = None,
+    ) -> list[str] | None:
         """
         从 files/xxx 绑定关系中解析优先 Key ID 列表。
 

src/api/public/gemini_files.py

@@ -60,7 +60,7 @@ HEADERS_TO_REMOVE = frozenset({
 })
 
 
-def _extract_gemini_api_key(request: Request) -> Optional[str]:
+def _extract_gemini_api_key(request: Request) -> str | None:
     """
     从请求中提取 Gemini API Key
 
@@ -76,9 +76,9 @@ def _extract_gemini_api_key(request: Request) -> Optional[str]:
 
 
 def _build_upstream_headers(
-    original_headers: Dict[str, str],
+    original_headers: dict[str, str],
     upstream_api_key: str,
-) -> Dict[str, str]:
+) -> dict[str, str]:
     """
     构建上游请求头
 
@@ -105,7 +105,7 @@ def _build_upstream_headers(
 def _build_upstream_url(
     base_url: str,
     path: str,
-    query_params: Optional[Dict[str, Any]] = None,
+    query_params: dict[str, Any] | None = None,
     is_upload: bool = False,
 ) -> str:
     """
@@ -145,8 +145,8 @@ def _build_upstream_url(
 def _resolve_files_model_name(
     db: Session,
     user_api_key: ApiKey,
-    user: Optional[User],
-) -> Optional[str]:
+    user: User | None,
+) -> str | None:
     """
     为 Files API 选择一个可用的模型名（用于 Key 选择与权限过滤）
 
@@ -188,7 +188,7 @@ async def _select_provider_candidate(
     db: Session,
     user_api_key: ApiKey,
     model_name: str,
-) -> Optional[ProviderCandidate]:
+) -> ProviderCandidate | None:
     """选择支持 Files API 的 Provider/Endpoint/Key 组合"""
     scheduler = CacheAwareScheduler()
     candidates, _global_model_id = await scheduler.list_all_candidates(
@@ -210,7 +210,7 @@ async def _select_provider_candidate(
 async def _resolve_upstream_context(
     request: Request,
     db: Session,
-) -> Tuple[str, str, str]:
+) -> tuple[str, str, str]:
     """
     解析上游 Key 与 Base URL
 
@@ -291,10 +291,10 @@ async def _resolve_upstream_context(
 async def _proxy_request(
     method: str,
     upstream_url: str,
-    headers: Dict[str, str],
-    content: Optional[bytes] = None,
-    json_body: Optional[Dict[str, Any]] = None,
-    file_key_id: Optional[str] = None,
+    headers: dict[str, str],
+    content: bytes | None = None,
+    json_body: dict[str, Any] | None = None,
+    file_key_id: str | None = None,
 ) -> Response:
     """
     代理请求到上游 Gemini API
@@ -461,8 +461,8 @@ async def upload_file(
 async def list_files(
     request: Request,
     db: Session = Depends(get_db),
-    pageSize: Optional[int] = None,
-    pageToken: Optional[str] = None,
+    pageSize: int | None = None,
+    pageToken: str | None = None,
 ):
     """
     列出已上传的文件