refactor: 重构 API 格式相关代码到统一的 api_format 模块

- 新增 src/core/api_format/ 模块，整合所有 API 格式相关功能
  - enums.py: APIFormat 枚举定义
  - metadata.py: API 格式元数据注册
  - headers.py: 请求头处理逻辑
  - detection.py: API 格式检测
  - conversion/: 格式转换器（Claude/OpenAI/Gemini 互转）
- 删除分散在各处的旧实现
  - src/core/api_format_metadata.py
  - src/core/headers.py
  - src/api/handlers/*/converter.py
  - src/api/handlers/base/format_converter_registry.py
- 更新所有引用路径，使用新的统一模块
- 新增 cli_handler_base 中的格式转换支持

src/api/admin/models/routing.py

@@ -402,7 +402,7 @@ class AdminGetModelRoutingPreviewAdapter(AdminApiAdapter):
                 )
 
             # 按 APIFormat 枚举定义的顺序排序 Endpoints
-            from src.core.enums import APIFormat
+            from src.core.api_format import APIFormat
 
             format_order = {fmt.value: i for i, fmt in enumerate(APIFormat)}
             endpoint_infos.sort(key=lambda e: format_order.get(e.api_format, 999))

src/api/admin/provider_query.py

@@ -12,7 +12,7 @@ from sqlalchemy.orm import Session, joinedload
 
 from src.config.constants import TimeoutDefaults
 from src.core.crypto import crypto_service
-from src.core.headers import get_extra_headers_from_endpoint
+from src.core.api_format import get_extra_headers_from_endpoint
 from src.core.logger import logger
 from src.database.database import get_db
 from src.models.database import Provider, ProviderEndpoint, User

src/api/admin/system.py

@@ -711,8 +711,7 @@ class AdminTriggerCleanupAdapter(AdminApiAdapter):
 class AdminGetApiFormatsAdapter(AdminApiAdapter):
     async def handle(self, context):  # type: ignore[override]
         """获取所有可用的API格式"""
-        from src.core.api_format_metadata import API_FORMAT_DEFINITIONS
-        from src.core.enums import APIFormat
+        from src.core.api_format import API_FORMAT_DEFINITIONS, APIFormat
 
         _ = context  # 参数保留以符合接口规范
 

src/api/handlers/base/base_handler.py

@@ -35,8 +35,7 @@ from fastapi.responses import JSONResponse, StreamingResponse
 from sqlalchemy.orm import Session
 
 from src.clients.redis_client import get_redis_client_sync
-from src.core.api_format_metadata import resolve_api_format
-from src.core.enums import APIFormat
+from src.core.api_format import APIFormat, resolve_api_format
 from src.core.logger import logger
 from src.services.orchestration.fallback_orchestrator import FallbackOrchestrator
 from src.services.provider.format import normalize_api_format

src/api/handlers/base/chat_adapter_base.py

@@ -28,7 +28,7 @@ from fastapi.responses import JSONResponse
 from src.api.base.adapter import ApiAdapter, ApiMode
 from src.api.base.context import ApiRequestContext
 from src.api.handlers.base.chat_handler_base import ChatHandlerBase
-from src.core.enums import APIFormat
+from src.core.api_format import APIFormat
 from src.core.exceptions import (
     InvalidRequestException,
     ModelNotSupportedException,
@@ -40,7 +40,7 @@ from src.core.exceptions import (
     QuotaExceededException,
     UpstreamClientException,
 )
-from src.core.headers import (
+from src.core.api_format import (
     build_adapter_base_headers,
     build_adapter_headers,
     extract_client_api_key,

src/api/handlers/base/cli_adapter_base.py

@@ -26,7 +26,7 @@ from fastapi.responses import JSONResponse
 from src.api.base.adapter import ApiAdapter, ApiMode
 from src.api.base.context import ApiRequestContext
 from src.api.handlers.base.cli_handler_base import CliMessageHandlerBase
-from src.core.enums import APIFormat
+from src.core.api_format import APIFormat
 from src.core.exceptions import (
     InvalidRequestException,
     ModelNotSupportedException,
@@ -38,7 +38,7 @@ from src.core.exceptions import (
     QuotaExceededException,
     UpstreamClientException,
 )
-from src.core.headers import (
+from src.core.api_format import (
     build_adapter_base_headers,
     build_adapter_headers,
     extract_client_api_key,

src/api/handlers/base/cli_handler_base.py

@@ -19,6 +19,7 @@ from typing import (
     AsyncGenerator,
     Callable,
     Dict,
+    List,
     Optional,
 )
 
@@ -671,10 +672,11 @@ class CliMessageHandlerBase(BaseMessageHandler):
 
                     # 格式转换或直接透传
                     if needs_conversion:
-                        converted_line = self._convert_sse_line(ctx, line, events)
-                        if converted_line:
-                            self._mark_first_output(ctx, output_state)
-                            yield (converted_line + "\n").encode("utf-8")
+                        converted_lines = self._convert_sse_line(ctx, line, events)
+                        for converted_line in converted_lines:
+                            if converted_line:
+                                self._mark_first_output(ctx, output_state)
+                                yield (converted_line + "\n").encode("utf-8")
                     else:
                         self._mark_first_output(ctx, output_state)
                         yield (line + "\n").encode("utf-8")
@@ -999,10 +1001,11 @@ class CliMessageHandlerBase(BaseMessageHandler):
 
                     # 格式转换或直接透传
                     if needs_conversion:
-                        converted_line = self._convert_sse_line(ctx, line, events)
-                        if converted_line:
-                            self._mark_first_output(ctx, output_state)
-                            yield (converted_line + "\n").encode("utf-8")
+                        converted_lines = self._convert_sse_line(ctx, line, events)
+                        for converted_line in converted_lines:
+                            if converted_line:
+                                self._mark_first_output(ctx, output_state)
+                                yield (converted_line + "\n").encode("utf-8")
                     else:
                         self._mark_first_output(ctx, output_state)
                         yield (line + "\n").encode("utf-8")
@@ -1073,10 +1076,11 @@ class CliMessageHandlerBase(BaseMessageHandler):
 
                     # 格式转换或直接透传
                     if needs_conversion:
-                        converted_line = self._convert_sse_line(ctx, line, events)
-                        if converted_line:
-                            self._mark_first_output(ctx, output_state)
-                            yield (converted_line + "\n").encode("utf-8")
+                        converted_lines = self._convert_sse_line(ctx, line, events)
+                        for converted_line in converted_lines:
+                            if converted_line:
+                                self._mark_first_output(ctx, output_state)
+                                yield (converted_line + "\n").encode("utf-8")
                     else:
                         self._mark_first_output(ctx, output_state)
                         yield (line + "\n").encode("utf-8")
@@ -1760,7 +1764,7 @@ class CliMessageHandlerBase(BaseMessageHandler):
                 and api_format
                 and provider_api_format.upper() != api_format.upper()
             ):
-                from src.api.handlers.base.format_converter_registry import converter_registry
+                from src.core.api_format import converter_registry
 
                 try:
                     response_json = converter_registry.convert_response(
@@ -1923,28 +1927,32 @@ class CliMessageHandlerBase(BaseMessageHandler):
         self,
         ctx: StreamContext,
         line: str,
-        events: list,
-    ) -> Optional[str]:
+        events: list,  # noqa: ARG002 - 预留给上下文感知转换
+    ) -> List[str]:
         """
         将 SSE 行从 Provider 格式转换为客户端格式
 
         Args:
             ctx: 流上下文
             line: 原始 SSE 行
-            events: 解析后的事件列表
+            events: 当前累积的事件列表（预留参数，用于未来上下文感知转换如合并相邻事件）
 
         Returns:
-            转换后的 SSE 行，如果无法转换则返回 None
+            转换后的 SSE 行列表（一入多出），空列表表示跳过该行
         """
-        from src.api.handlers.base.format_converter_registry import converter_registry
+        from src.core.api_format import (
+            GeminiStreamConversionState,
+            StreamConversionState,
+            converter_registry,
+        )
 
         # 如果是空行或特殊控制行，直接返回
         if not line or line.strip() == "" or line == "data: [DONE]":
-            return line
+            return [line] if line else []
 
         # 如果不是 data 行，直接透传
         if not line.startswith("data:"):
-            return line
+            return [line]
 
         # 提取 data 内容
         data_content = line[5:].strip()  # 去掉 "data:" 前缀
@@ -1954,17 +1962,40 @@ class CliMessageHandlerBase(BaseMessageHandler):
             data_obj = json.loads(data_content)
         except json.JSONDecodeError:
             # 无法解析，直接透传
-            return line
+            return [line]
 
-        # 使用注册表进行格式转换
+        # 类型断言：当 needs_conversion=True 调用此方法时，格式字段必定有值
+        provider_format = ctx.provider_api_format or ""
+        client_format = ctx.client_api_format or ""
+
+        # 初始化流式转换状态（首次调用时，根据 Provider 格式选择状态类）
+        if ctx.stream_conversion_state is None:
+            if provider_format.upper() == "GEMINI":
+                ctx.stream_conversion_state = GeminiStreamConversionState(
+                    model=ctx.mapped_model or ctx.model or "",
+                    message_id=ctx.response_id or ctx.request_id or "",
+                )
+            else:
+                ctx.stream_conversion_state = StreamConversionState(
+                    model=ctx.mapped_model or ctx.model or "",
+                    message_id=ctx.response_id or ctx.request_id or "",
+                )
+
+        # 使用注册表进行格式转换（严格模式，返回 List[Dict]）
         try:
-            converted_obj = converter_registry.convert_stream_chunk(
+            converted_events = converter_registry.convert_stream_chunk_strict(
                 data_obj,
-                ctx.provider_api_format,
-                ctx.client_api_format,
+                provider_format,
+                client_format,
+                state=ctx.stream_conversion_state,
             )
-            # 重新构建 SSE 行
-            return f"data: {json.dumps(converted_obj, ensure_ascii=False)}"
+
+            # 转换为 SSE 行列表
+            result = []
+            for evt in converted_events:
+                result.append(f"data: {json.dumps(evt, ensure_ascii=False)}")
+            return result
+
         except Exception as e:
             logger.warning(f"格式转换失败，透传原始数据: {e}")
-            return line
+            return [line]

src/api/handlers/base/endpoint_checker.py

@@ -27,7 +27,7 @@ from collections import defaultdict
 import httpx
 
 from src.core.logger import logger
-from src.core.headers import CORE_REDACT_HEADERS, merge_headers_with_protection, redact_headers_for_log
+from src.core.api_format import CORE_REDACT_HEADERS, merge_headers_with_protection, redact_headers_for_log
 from src.utils.ssl_utils import get_ssl_context
 
 

src/api/handlers/base/format_converter_registry.py

@@ -1,279 +0,0 @@
-"""
-格式转换器注册表
-
-自动管理不同 API 格式之间的转换器，支持：
-- 请求转换：客户端格式 → Provider 格式
-- 响应转换：Provider 格式 → 客户端格式
-
-使用方法：
-1. 实现 Converter 类（需要有 convert_request 和/或 convert_response 方法）
-2. 调用 registry.register() 注册转换器
-3. 在 Handler 中调用 registry.convert_request/convert_response
-
-示例：
-    from src.api.handlers.base.format_converter_registry import converter_registry
-
-    # 注册转换器
-    converter_registry.register("CLAUDE", "GEMINI", ClaudeToGeminiConverter())
-    converter_registry.register("GEMINI", "CLAUDE", GeminiToClaudeConverter())
-
-    # 使用转换器
-    gemini_request = converter_registry.convert_request(claude_request, "CLAUDE", "GEMINI")
-    claude_response = converter_registry.convert_response(gemini_response, "GEMINI", "CLAUDE")
-"""
-
-from typing import Any, Dict, Optional, Protocol, Tuple
-
-from src.core.logger import logger
-
-
-
-class RequestConverter(Protocol):
-    """请求转换器协议"""
-
-    def convert_request(self, request: Dict[str, Any]) -> Dict[str, Any]: ...
-
-
-class ResponseConverter(Protocol):
-    """响应转换器协议"""
-
-    def convert_response(self, response: Dict[str, Any]) -> Dict[str, Any]: ...
-
-
-class StreamChunkConverter(Protocol):
-    """流式响应块转换器协议"""
-
-    def convert_stream_chunk(self, chunk: Dict[str, Any]) -> Dict[str, Any]: ...
-
-
-class FormatConverterRegistry:
-    """
-    格式转换器注册表
-
-    管理不同 API 格式之间的双向转换器
-    """
-
-    def __init__(self):
-        # key: (source_format, target_format), value: converter instance
-        self._converters: Dict[Tuple[str, str], Any] = {}
-
-    def register(
-        self,
-        source_format: str,
-        target_format: str,
-        converter: Any,
-    ) -> None:
-        """
-        注册格式转换器
-
-        Args:
-            source_format: 源格式（如 "CLAUDE", "OPENAI", "GEMINI"）
-            target_format: 目标格式
-            converter: 转换器实例（需要有 convert_request/convert_response 方法）
-        """
-        key = (source_format.upper(), target_format.upper())
-        self._converters[key] = converter
-        logger.info(f"[ConverterRegistry] 注册转换器: {source_format} -> {target_format}")
-
-    def get_converter(
-        self,
-        source_format: str,
-        target_format: str,
-    ) -> Optional[Any]:
-        """
-        获取转换器
-
-        Args:
-            source_format: 源格式
-            target_format: 目标格式
-
-        Returns:
-            转换器实例，如果不存在返回 None
-        """
-        key = (source_format.upper(), target_format.upper())
-        return self._converters.get(key)
-
-    def has_converter(
-        self,
-        source_format: str,
-        target_format: str,
-    ) -> bool:
-        """检查是否存在转换器"""
-        key = (source_format.upper(), target_format.upper())
-        return key in self._converters
-
-    def convert_request(
-        self,
-        request: Dict[str, Any],
-        source_format: str,
-        target_format: str,
-    ) -> Dict[str, Any]:
-        """
-        转换请求
-
-        Args:
-            request: 原始请求字典
-            source_format: 源格式（客户端格式）
-            target_format: 目标格式（Provider 格式）
-
-        Returns:
-            转换后的请求字典，如果无需转换或没有转换器则返回原始请求
-        """
-        # 同格式无需转换
-        if source_format.upper() == target_format.upper():
-            return request
-
-        converter = self.get_converter(source_format, target_format)
-        if converter is None:
-            logger.warning(f"[ConverterRegistry] 未找到请求转换器: {source_format} -> {target_format}，返回原始请求")
-            return request
-
-        if not hasattr(converter, "convert_request"):
-            logger.warning(f"[ConverterRegistry] 转换器缺少 convert_request 方法: {source_format} -> {target_format}")
-            return request
-
-        try:
-            converted = converter.convert_request(request)
-            logger.debug(f"[ConverterRegistry] 请求转换成功: {source_format} -> {target_format}")
-            return converted
-        except Exception as e:
-            logger.error(f"[ConverterRegistry] 请求转换失败: {source_format} -> {target_format}: {e}")
-            return request
-
-    def convert_response(
-        self,
-        response: Dict[str, Any],
-        source_format: str,
-        target_format: str,
-    ) -> Dict[str, Any]:
-        """
-        转换响应
-
-        Args:
-            response: 原始响应字典
-            source_format: 源格式（Provider 格式）
-            target_format: 目标格式（客户端格式）
-
-        Returns:
-            转换后的响应字典，如果无需转换或没有转换器则返回原始响应
-        """
-        # 同格式无需转换
-        if source_format.upper() == target_format.upper():
-            return response
-
-        converter = self.get_converter(source_format, target_format)
-        if converter is None:
-            logger.warning(f"[ConverterRegistry] 未找到响应转换器: {source_format} -> {target_format}，返回原始响应")
-            return response
-
-        if not hasattr(converter, "convert_response"):
-            logger.warning(f"[ConverterRegistry] 转换器缺少 convert_response 方法: {source_format} -> {target_format}")
-            return response
-
-        try:
-            converted = converter.convert_response(response)
-            logger.debug(f"[ConverterRegistry] 响应转换成功: {source_format} -> {target_format}")
-            return converted
-        except Exception as e:
-            logger.error(f"[ConverterRegistry] 响应转换失败: {source_format} -> {target_format}: {e}")
-            return response
-
-    def convert_stream_chunk(
-        self,
-        chunk: Dict[str, Any],
-        source_format: str,
-        target_format: str,
-    ) -> Dict[str, Any]:
-        """
-        转换流式响应块
-
-        Args:
-            chunk: 原始流式响应块
-            source_format: 源格式（Provider 格式）
-            target_format: 目标格式（客户端格式）
-
-        Returns:
-            转换后的流式响应块
-        """
-        # 同格式无需转换
-        if source_format.upper() == target_format.upper():
-            return chunk
-
-        converter = self.get_converter(source_format, target_format)
-        if converter is None:
-            return chunk
-
-        # 优先使用专门的流式转换方法
-        if hasattr(converter, "convert_stream_chunk"):
-            try:
-                return converter.convert_stream_chunk(chunk)
-            except Exception as e:
-                logger.error(f"[ConverterRegistry] 流式块转换失败: {source_format} -> {target_format}: {e}")
-                return chunk
-
-        # 降级到普通响应转换
-        if hasattr(converter, "convert_response"):
-            try:
-                return converter.convert_response(chunk)
-            except Exception:
-                return chunk
-
-        return chunk
-
-    def list_converters(self) -> list[Tuple[str, str]]:
-        """列出所有已注册的转换器"""
-        return list(self._converters.keys())
-
-
-# 全局单例
-converter_registry = FormatConverterRegistry()
-
-
-def register_all_converters():
-    """
-    注册所有内置的格式转换器
-
-    在应用启动时调用此函数
-    """
-    # Claude <-> OpenAI
-    try:
-        from src.api.handlers.claude.converter import OpenAIToClaudeConverter
-        from src.api.handlers.openai.converter import ClaudeToOpenAIConverter
-
-        converter_registry.register("OPENAI", "CLAUDE", OpenAIToClaudeConverter())
-        converter_registry.register("CLAUDE", "OPENAI", ClaudeToOpenAIConverter())
-    except ImportError as e:
-        logger.warning(f"[ConverterRegistry] 无法加载 Claude/OpenAI 转换器: {e}")
-
-    # Claude <-> Gemini
-    try:
-        from src.api.handlers.gemini.converter import (
-            ClaudeToGeminiConverter,
-            GeminiToClaudeConverter,
-        )
-
-        converter_registry.register("CLAUDE", "GEMINI", ClaudeToGeminiConverter())
-        converter_registry.register("GEMINI", "CLAUDE", GeminiToClaudeConverter())
-    except ImportError as e:
-        logger.warning(f"[ConverterRegistry] 无法加载 Claude/Gemini 转换器: {e}")
-
-    # OpenAI <-> Gemini
-    try:
-        from src.api.handlers.gemini.converter import (
-            GeminiToOpenAIConverter,
-            OpenAIToGeminiConverter,
-        )
-
-        converter_registry.register("OPENAI", "GEMINI", OpenAIToGeminiConverter())
-        converter_registry.register("GEMINI", "OPENAI", GeminiToOpenAIConverter())
-    except ImportError as e:
-        logger.warning(f"[ConverterRegistry] 无法加载 OpenAI/Gemini 转换器: {e}")
-
-    logger.info(f"[ConverterRegistry] 已注册 {len(converter_registry.list_converters())} 个格式转换器")
-
-
-__all__ = [
-    "FormatConverterRegistry",
-    "converter_registry",
-    "register_all_converters",
-]

src/api/handlers/base/parsers.py

@@ -16,6 +16,9 @@ from src.api.handlers.base.response_parser import (
 )
 from src.api.handlers.base.utils import extract_cache_creation_tokens
 
+# is_cli_format 权威定义在 core 层
+from src.core.api_format import is_cli_format
+
 
 def _check_nested_error(response: Dict[str, Any]) -> Tuple[bool, Optional[Dict[str, Any]]]:
     """
@@ -571,11 +574,6 @@ def get_parser_for_format(format_id: str) -> ResponseParser:
     return _PARSERS[format_id]()
 
 
-def is_cli_format(format_id: str) -> bool:
-    """判断是否为 CLI 格式"""
-    return format_id.upper().endswith("_CLI")
-
-
 __all__ = [
     "OpenAIResponseParser",
     "OpenAICliResponseParser",

src/api/handlers/base/request_builder.py

@@ -17,7 +17,7 @@ from abc import ABC, abstractmethod
 from typing import Any, Dict, FrozenSet, Optional, Tuple
 
 from src.core.crypto import crypto_service
-from src.core.headers import HeaderBuilder, UPSTREAM_DROP_HEADERS
+from src.core.api_format import HeaderBuilder, UPSTREAM_DROP_HEADERS
 
 # ==============================================================================
 # 统一的头部配置常量
@@ -125,7 +125,7 @@ class PassthroughRequestBuilder(RequestBuilder):
         """
         透传请求头 - 清理敏感头部（黑名单），透传其他所有头部
         """
-        from src.core.api_format_metadata import get_auth_config, resolve_api_format
+        from src.core.api_format import get_auth_config, resolve_api_format
 
         # 1. 根据 API 格式自动设置认证头
         decrypted_key = crypto_service.decrypt(key.api_key)

src/api/handlers/base/stream_context.py

@@ -10,7 +10,10 @@
 
 import time
 from dataclasses import dataclass, field
-from typing import Any, Dict, List, Optional
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
+
+if TYPE_CHECKING:
+    from src.core.api_format import GeminiStreamConversionState, StreamConversionState
 
 
 @dataclass
@@ -82,6 +85,11 @@ class StreamContext:
     chunk_count: int = 0
     parsed_chunks: List[Dict[str, Any]] = field(default_factory=list)
 
+    # 流式格式转换状态（跨 chunk 追踪）
+    stream_conversion_state: Optional[
+        Union["StreamConversionState", "GeminiStreamConversionState"]
+    ] = None
+
     def reset_for_retry(self) -> None:
         """
         重试时重置状态
@@ -109,6 +117,7 @@ class StreamContext:
         self.response_id = None
         self.final_usage = None
         self.final_response = None
+        self.stream_conversion_state = None
 
     @property
     def collected_text(self) -> str:

src/api/handlers/base/utils.py

@@ -6,7 +6,7 @@ import json
 from typing import Any, Dict, Optional
 
 from src.core.exceptions import EmbeddedErrorException, ProviderNotAvailableException
-from src.core.headers import filter_response_headers
+from src.core.api_format import filter_response_headers
 from src.core.logger import logger
 
 

src/api/handlers/claude/adapter.py

@@ -14,7 +14,7 @@ from src.api.base.adapter import ApiAdapter, ApiMode
 from src.api.base.context import ApiRequestContext
 from src.api.handlers.base.chat_adapter_base import ChatAdapterBase, register_adapter
 from src.api.handlers.base.chat_handler_base import ChatHandlerBase
-from src.core.headers import get_header_value
+from src.core.api_format import get_header_value
 from src.core.logger import logger
 from src.core.optimization_utils import TokenCounter
 from src.models.claude import ClaudeMessagesRequest, ClaudeTokenCountRequest

src/api/handlers/claude/converter.py

@@ -1,490 +0,0 @@
-"""
-OpenAI -> Claude 格式转换器
-
-将 OpenAI Chat Completions API 格式转换为 Claude Messages API 格式。
-"""
-
-from __future__ import annotations
-
-import json
-import time
-import uuid
-from typing import Any, Dict, List, Optional, Union
-
-from pydantic import BaseModel
-
-
-class OpenAIToClaudeConverter:
-    """
-    OpenAI -> Claude 格式转换器
-
-    支持：
-    - 请求转换：OpenAI Chat Request -> Claude Request
-    - 响应转换：OpenAI Chat Response -> Claude Response
-    - 流式转换：OpenAI SSE -> Claude SSE
-    """
-
-    # 内容类型常量
-    CONTENT_TYPE_TEXT = "text"
-    CONTENT_TYPE_IMAGE = "image"
-    CONTENT_TYPE_TOOL_USE = "tool_use"
-    CONTENT_TYPE_TOOL_RESULT = "tool_result"
-
-    # 停止原因映射（OpenAI -> Claude）
-    FINISH_REASON_MAP = {
-        "stop": "end_turn",
-        "length": "max_tokens",
-        "tool_calls": "tool_use",
-        "function_call": "tool_use",
-        "content_filter": "end_turn",
-    }
-
-    def __init__(self, model_mapping: Optional[Dict[str, str]] = None):
-        """
-        Args:
-            model_mapping: OpenAI 模型到 Claude 模型的映射
-        """
-        self._model_mapping = model_mapping or {}
-
-    # ==================== 请求转换 ====================
-
-    def convert_request(self, request: Union[Dict[str, Any], BaseModel]) -> Dict[str, Any]:
-        """
-        将 OpenAI 请求转换为 Claude 格式
-
-        Args:
-            request: OpenAI 请求（Dict 或 Pydantic 模型）
-
-        Returns:
-            Claude 格式的请求字典
-        """
-        if hasattr(request, "model_dump"):
-            data = request.model_dump(exclude_none=True)
-        else:
-            data = dict(request)
-
-        # 模型映射
-        model = data.get("model", "")
-        claude_model = self._model_mapping.get(model, model)
-
-        # 处理消息
-        system_content: Optional[str] = None
-        claude_messages: List[Dict[str, Any]] = []
-
-        for message in data.get("messages", []):
-            role = message.get("role")
-
-            # 提取 system 消息
-            if role == "system":
-                system_content = self._collapse_content(message.get("content"))
-                continue
-
-            # 转换其他消息
-            converted = self._convert_message(message)
-            if converted:
-                claude_messages.append(converted)
-
-        # 构建 Claude 请求
-        result: Dict[str, Any] = {
-            "model": claude_model,
-            "messages": claude_messages,
-            "max_tokens": data.get("max_tokens") or 4096,
-        }
-
-        # 可选参数
-        if data.get("temperature") is not None:
-            result["temperature"] = data["temperature"]
-        if data.get("top_p") is not None:
-            result["top_p"] = data["top_p"]
-        if data.get("stream"):
-            result["stream"] = data["stream"]
-        if data.get("stop"):
-            result["stop_sequences"] = self._convert_stop(data["stop"])
-        if system_content:
-            result["system"] = system_content
-
-        # 工具转换
-        tools = self._convert_tools(data.get("tools"))
-        if tools:
-            result["tools"] = tools
-
-        tool_choice = self._convert_tool_choice(data.get("tool_choice"))
-        if tool_choice:
-            result["tool_choice"] = tool_choice
-
-        return result
-
-    def _convert_message(self, message: Dict[str, Any]) -> Optional[Dict[str, Any]]:
-        """转换单条消息"""
-        role = message.get("role")
-
-        if role == "user":
-            return self._convert_user_message(message)
-        if role == "assistant":
-            return self._convert_assistant_message(message)
-        if role == "tool":
-            return self._convert_tool_message(message)
-
-        return None
-
-    def _convert_user_message(self, message: Dict[str, Any]) -> Dict[str, Any]:
-        """转换用户消息"""
-        content = message.get("content")
-
-        if isinstance(content, str) or content is None:
-            return {"role": "user", "content": content or ""}
-
-        # 转换内容数组
-        claude_content: List[Dict[str, Any]] = []
-        for item in content:
-            item_type = item.get("type")
-
-            if item_type == "text":
-                claude_content.append(
-                    {"type": self.CONTENT_TYPE_TEXT, "text": item.get("text", "")}
-                )
-            elif item_type == "image_url":
-                image_url = (item.get("image_url") or {}).get("url", "")
-                claude_content.append(self._convert_image_url(image_url))
-
-        return {"role": "user", "content": claude_content}
-
-    def _convert_assistant_message(self, message: Dict[str, Any]) -> Dict[str, Any]:
-        """转换助手消息"""
-        content_blocks: List[Dict[str, Any]] = []
-
-        # 处理文本内容
-        content = message.get("content")
-        if isinstance(content, str):
-            content_blocks.append({"type": self.CONTENT_TYPE_TEXT, "text": content})
-        elif isinstance(content, list):
-            for part in content:
-                if part.get("type") == "text":
-                    content_blocks.append(
-                        {"type": self.CONTENT_TYPE_TEXT, "text": part.get("text", "")}
-                    )
-
-        # 处理工具调用
-        for tool_call in message.get("tool_calls") or []:
-            if tool_call.get("type") == "function":
-                function = tool_call.get("function", {})
-                arguments = function.get("arguments", "{}")
-                try:
-                    input_data = json.loads(arguments)
-                except json.JSONDecodeError:
-                    input_data = {"raw": arguments}
-
-                content_blocks.append(
-                    {
-                        "type": self.CONTENT_TYPE_TOOL_USE,
-                        "id": tool_call.get("id", ""),
-                        "name": function.get("name", ""),
-                        "input": input_data,
-                    }
-                )
-
-        # 简化单文本内容
-        if not content_blocks:
-            return {"role": "assistant", "content": ""}
-        if len(content_blocks) == 1 and content_blocks[0]["type"] == self.CONTENT_TYPE_TEXT:
-            return {"role": "assistant", "content": content_blocks[0]["text"]}
-
-        return {"role": "assistant", "content": content_blocks}
-
-    def _convert_tool_message(self, message: Dict[str, Any]) -> Dict[str, Any]:
-        """转换工具结果消息"""
-        tool_content = message.get("content", "")
-
-        # 尝试解析 JSON
-        parsed_content = tool_content
-        if isinstance(tool_content, str):
-            try:
-                parsed_content = json.loads(tool_content)
-            except json.JSONDecodeError:
-                pass
-
-        tool_block = {
-            "type": self.CONTENT_TYPE_TOOL_RESULT,
-            "tool_use_id": message.get("tool_call_id", ""),
-            "content": parsed_content,
-        }
-
-        return {"role": "user", "content": [tool_block]}
-
-    def _convert_tools(
-        self, tools: Optional[List[Dict[str, Any]]]
-    ) -> Optional[List[Dict[str, Any]]]:
-        """转换工具定义"""
-        if not tools:
-            return None
-
-        result: List[Dict[str, Any]] = []
-        for tool in tools:
-            if tool.get("type") != "function":
-                continue
-
-            function = tool.get("function", {})
-            result.append(
-                {
-                    "name": function.get("name", ""),
-                    "description": function.get("description"),
-                    "input_schema": function.get("parameters") or {},
-                }
-            )
-
-        return result if result else None
-
-    def _convert_tool_choice(
-        self, tool_choice: Optional[Union[str, Dict[str, Any]]]
-    ) -> Optional[Dict[str, Any]]:
-        """转换工具选择"""
-        if tool_choice is None:
-            return None
-        if tool_choice == "none":
-            return {"type": "none"}
-        if tool_choice == "auto":
-            return {"type": "auto"}
-        if tool_choice == "required":
-            return {"type": "any"}
-        if isinstance(tool_choice, dict) and tool_choice.get("type") == "function":
-            function = tool_choice.get("function", {})
-            return {"type": "tool_use", "name": function.get("name", "")}
-
-        return {"type": "auto"}
-
-    def _convert_image_url(self, image_url: str) -> Dict[str, Any]:
-        """转换图片 URL"""
-        if image_url.startswith("data:"):
-            header, _, data = image_url.partition(",")
-            media_type = "image/jpeg"
-            if ";" in header:
-                media_type = header.split(";")[0].split(":")[-1]
-
-            return {
-                "type": self.CONTENT_TYPE_IMAGE,
-                "source": {
-                    "type": "base64",
-                    "media_type": media_type,
-                    "data": data,
-                },
-            }
-
-        return {"type": self.CONTENT_TYPE_TEXT, "text": f"[Image: {image_url}]"}
-
-    def _convert_stop(self, stop: Optional[Union[str, List[str]]]) -> Optional[List[str]]:
-        """转换停止序列"""
-        if stop is None:
-            return None
-        if isinstance(stop, str):
-            return [stop]
-        return stop
-
-    # ==================== 响应转换 ====================
-
-    def convert_response(self, response: Dict[str, Any]) -> Dict[str, Any]:
-        """
-        将 OpenAI 响应转换为 Claude 格式
-
-        Args:
-            response: OpenAI 响应字典
-
-        Returns:
-            Claude 格式的响应字典
-        """
-        choices = response.get("choices", [])
-        if not choices:
-            return self._empty_claude_response(response)
-
-        choice = choices[0]
-        message = choice.get("message", {})
-
-        # 构建 content 数组
-        content: List[Dict[str, Any]] = []
-
-        # 处理文本
-        text_content = message.get("content")
-        if text_content:
-            content.append(
-                {
-                    "type": self.CONTENT_TYPE_TEXT,
-                    "text": text_content,
-                }
-            )
-
-        # 处理工具调用
-        for tool_call in message.get("tool_calls") or []:
-            if tool_call.get("type") == "function":
-                function = tool_call.get("function", {})
-                arguments = function.get("arguments", "{}")
-                try:
-                    input_data = json.loads(arguments)
-                except json.JSONDecodeError:
-                    input_data = {"raw": arguments}
-
-                content.append(
-                    {
-                        "type": self.CONTENT_TYPE_TOOL_USE,
-                        "id": tool_call.get("id", ""),
-                        "name": function.get("name", ""),
-                        "input": input_data,
-                    }
-                )
-
-        # 转换 finish_reason
-        finish_reason = choice.get("finish_reason")
-        stop_reason = self.FINISH_REASON_MAP.get(finish_reason, "end_turn")
-
-        # 转换 usage
-        usage = response.get("usage", {})
-        claude_usage = {
-            "input_tokens": usage.get("prompt_tokens", 0),
-            "output_tokens": usage.get("completion_tokens", 0),
-        }
-
-        return {
-            "id": f"msg_{response.get('id', uuid.uuid4().hex[:8])}",
-            "type": "message",
-            "role": "assistant",
-            "model": response.get("model", ""),
-            "content": content,
-            "stop_reason": stop_reason,
-            "stop_sequence": None,
-            "usage": claude_usage,
-        }
-
-    def _empty_claude_response(self, response: Dict[str, Any]) -> Dict[str, Any]:
-        """构建空的 Claude 响应"""
-        return {
-            "id": f"msg_{response.get('id', uuid.uuid4().hex[:8])}",
-            "type": "message",
-            "role": "assistant",
-            "model": response.get("model", ""),
-            "content": [],
-            "stop_reason": "end_turn",
-            "stop_sequence": None,
-            "usage": {"input_tokens": 0, "output_tokens": 0},
-        }
-
-    # ==================== 流式转换 ====================
-
-    def convert_stream_chunk(
-        self,
-        chunk: Dict[str, Any],
-        model: str = "",
-        message_id: Optional[str] = None,
-        message_started: bool = False,
-    ) -> List[Dict[str, Any]]:
-        """
-        将 OpenAI SSE chunk 转换为 Claude SSE 事件
-
-        Args:
-            chunk: OpenAI SSE chunk
-            model: 模型名称
-            message_id: 消息 ID
-            message_started: 是否已发送 message_start
-
-        Returns:
-            Claude SSE 事件列表
-        """
-        events: List[Dict[str, Any]] = []
-
-        choices = chunk.get("choices", [])
-        if not choices:
-            return events
-
-        choice = choices[0]
-        delta = choice.get("delta", {})
-        finish_reason = choice.get("finish_reason")
-
-        # 处理角色（第一个 chunk）
-        role = delta.get("role")
-        if role and not message_started:
-            msg_id = message_id or f"msg_{uuid.uuid4().hex[:8]}"
-            events.append(
-                {
-                    "type": "message_start",
-                    "message": {
-                        "id": msg_id,
-                        "type": "message",
-                        "role": role,
-                        "model": model,
-                        "content": [],
-                        "stop_reason": None,
-                        "stop_sequence": None,
-                    },
-                }
-            )
-
-        # 处理文本内容
-        content_delta = delta.get("content")
-        if isinstance(content_delta, str):
-            events.append(
-                {
-                    "type": "content_block_delta",
-                    "index": 0,
-                    "delta": {"type": "text_delta", "text": content_delta},
-                }
-            )
-
-        # 处理工具调用
-        tool_calls = delta.get("tool_calls", [])
-        for tool_call in tool_calls:
-            index = tool_call.get("index", 0)
-
-            # 工具调用开始
-            if "id" in tool_call:
-                function = tool_call.get("function", {})
-                events.append(
-                    {
-                        "type": "content_block_start",
-                        "index": index,
-                        "content_block": {
-                            "type": self.CONTENT_TYPE_TOOL_USE,
-                            "id": tool_call["id"],
-                            "name": function.get("name", ""),
-                        },
-                    }
-                )
-
-            # 工具调用参数增量
-            function = tool_call.get("function", {})
-            if "arguments" in function:
-                events.append(
-                    {
-                        "type": "content_block_delta",
-                        "index": index,
-                        "delta": {
-                            "type": "input_json_delta",
-                            "partial_json": function.get("arguments", ""),
-                        },
-                    }
-                )
-
-        # 处理结束
-        if finish_reason:
-            stop_reason = self.FINISH_REASON_MAP.get(finish_reason, "end_turn")
-            events.append(
-                {
-                    "type": "message_delta",
-                    "delta": {"stop_reason": stop_reason},
-                }
-            )
-
-        return events
-
-    # ==================== 工具方法 ====================
-
-    def _collapse_content(
-        self, content: Optional[Union[str, List[Dict[str, Any]]]]
-    ) -> Optional[str]:
-        """折叠内容为字符串"""
-        if isinstance(content, str):
-            return content
-        if not content:
-            return None
-
-        text_parts = [part.get("text", "") for part in content if part.get("type") == "text"]
-        return "\n\n".join(filter(None, text_parts)) or None
-
-
-__all__ = ["OpenAIToClaudeConverter"]

src/api/handlers/claude/handler.py

@@ -74,7 +74,7 @@ class ClaudeChatHandler(ChatHandlerBase):
         Returns:
             ClaudeMessagesRequest 对象
         """
-        from src.api.handlers.claude.converter import OpenAIToClaudeConverter
+        from src.core.api_format import OpenAIToClaudeConverter
         from src.models.claude import ClaudeMessagesRequest
         from src.models.openai import OpenAIRequest
 

src/api/handlers/gemini/__init__.py

@@ -5,14 +5,14 @@ Gemini API Handler 模块
 """
 
 from src.api.handlers.gemini.adapter import GeminiChatAdapter, build_gemini_adapter
-from src.api.handlers.gemini.converter import (
+from src.api.handlers.gemini.handler import GeminiChatHandler
+from src.api.handlers.gemini.stream_parser import GeminiStreamParser
+from src.core.api_format import (
     ClaudeToGeminiConverter,
     GeminiToClaudeConverter,
     GeminiToOpenAIConverter,
     OpenAIToGeminiConverter,
 )
-from src.api.handlers.gemini.handler import GeminiChatHandler
-from src.api.handlers.gemini.stream_parser import GeminiStreamParser
 
 __all__ = [
     "GeminiChatAdapter",

src/api/handlers/gemini/converter.py

@@ -1,548 +0,0 @@
-"""
-Gemini 格式转换器
-
-提供 Gemini 与其他 API 格式（Claude、OpenAI）之间的转换
-"""
-
-from typing import Any, Dict, List, Optional
-
-
-class ClaudeToGeminiConverter:
-    """
-    Claude -> Gemini 请求转换器
-
-    将 Claude Messages API 格式转换为 Gemini generateContent 格式
-    """
-
-    def convert_request(self, claude_request: Dict[str, Any]) -> Dict[str, Any]:
-        """
-        将 Claude 请求转换为 Gemini 请求
-
-        Args:
-            claude_request: Claude 格式的请求字典
-
-        Returns:
-            Gemini 格式的请求字典
-        """
-        gemini_request: Dict[str, Any] = {
-            "contents": self._convert_messages(claude_request.get("messages", [])),
-        }
-
-        # 转换 system prompt
-        system = claude_request.get("system")
-        if system:
-            gemini_request["system_instruction"] = self._convert_system(system)
-
-        # 转换生成配置
-        generation_config = self._build_generation_config(claude_request)
-        if generation_config:
-            gemini_request["generation_config"] = generation_config
-
-        # 转换工具
-        tools = claude_request.get("tools")
-        if tools:
-            gemini_request["tools"] = self._convert_tools(tools)
-
-        return gemini_request
-
-    def _convert_messages(self, messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-        """转换消息列表"""
-        contents = []
-        for msg in messages:
-            role = msg.get("role", "user")
-            # Gemini 使用 "model" 而不是 "assistant"
-            gemini_role = "model" if role == "assistant" else "user"
-
-            content = msg.get("content", "")
-            parts = self._convert_content_to_parts(content)
-
-            contents.append(
-                {
-                    "role": gemini_role,
-                    "parts": parts,
-                }
-            )
-        return contents
-
-    def _convert_content_to_parts(self, content: Any) -> List[Dict[str, Any]]:
-        """将 Claude 内容转换为 Gemini parts"""
-        if isinstance(content, str):
-            return [{"text": content}]
-
-        if isinstance(content, list):
-            parts: List[Dict[str, Any]] = []
-            for block in content:
-                if isinstance(block, str):
-                    parts.append({"text": block})
-                elif isinstance(block, dict):
-                    block_type = block.get("type")
-                    if block_type == "text":
-                        parts.append({"text": block.get("text", "")})
-                    elif block_type == "image":
-                        # 转换图片
-                        source = block.get("source", {})
-                        if source.get("type") == "base64":
-                            parts.append(
-                                {
-                                    "inline_data": {
-                                        "mime_type": source.get("media_type", "image/png"),
-                                        "data": source.get("data", ""),
-                                    }
-                                }
-                            )
-                    elif block_type == "tool_use":
-                        # 转换工具调用
-                        parts.append(
-                            {
-                                "function_call": {
-                                    "name": block.get("name", ""),
-                                    "args": block.get("input", {}),
-                                }
-                            }
-                        )
-                    elif block_type == "tool_result":
-                        # 转换工具结果
-                        parts.append(
-                            {
-                                "function_response": {
-                                    "name": block.get("tool_use_id", ""),
-                                    "response": {"result": block.get("content", "")},
-                                }
-                            }
-                        )
-            return parts
-
-        return [{"text": str(content)}]
-
-    def _convert_system(self, system: Any) -> Dict[str, Any]:
-        """转换 system prompt"""
-        if isinstance(system, str):
-            return {"parts": [{"text": system}]}
-
-        if isinstance(system, list):
-            parts = []
-            for item in system:
-                if isinstance(item, str):
-                    parts.append({"text": item})
-                elif isinstance(item, dict) and item.get("type") == "text":
-                    parts.append({"text": item.get("text", "")})
-            return {"parts": parts}
-
-        return {"parts": [{"text": str(system)}]}
-
-    def _build_generation_config(self, claude_request: Dict[str, Any]) -> Optional[Dict[str, Any]]:
-        """构建生成配置"""
-        config: Dict[str, Any] = {}
-
-        if "max_tokens" in claude_request:
-            config["max_output_tokens"] = claude_request["max_tokens"]
-        if "temperature" in claude_request:
-            config["temperature"] = claude_request["temperature"]
-        if "top_p" in claude_request:
-            config["top_p"] = claude_request["top_p"]
-        if "top_k" in claude_request:
-            config["top_k"] = claude_request["top_k"]
-        if "stop_sequences" in claude_request:
-            config["stop_sequences"] = claude_request["stop_sequences"]
-
-        return config if config else None
-
-    def _convert_tools(self, tools: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-        """转换工具定义"""
-        function_declarations = []
-        for tool in tools:
-            func_decl = {
-                "name": tool.get("name", ""),
-            }
-            if "description" in tool:
-                func_decl["description"] = tool["description"]
-            if "input_schema" in tool:
-                func_decl["parameters"] = tool["input_schema"]
-            function_declarations.append(func_decl)
-
-        return [{"function_declarations": function_declarations}]
-
-
-class GeminiToClaudeConverter:
-    """
-    Gemini -> Claude 响应转换器
-
-    将 Gemini generateContent 响应转换为 Claude Messages API 格式
-    """
-
-    def convert_response(self, gemini_response: Dict[str, Any]) -> Dict[str, Any]:
-        """
-        将 Gemini 响应转换为 Claude 响应
-
-        Args:
-            gemini_response: Gemini 格式的响应字典
-
-        Returns:
-            Claude 格式的响应字典
-        """
-        candidates = gemini_response.get("candidates", [])
-        if not candidates:
-            return self._create_empty_response()
-
-        candidate = candidates[0]
-        content = candidate.get("content", {})
-        parts = content.get("parts", [])
-
-        # 转换内容块
-        claude_content = self._convert_parts_to_content(parts)
-
-        # 转换使用量
-        usage = self._convert_usage(gemini_response.get("usageMetadata", {}))
-
-        # 转换停止原因
-        stop_reason = self._convert_finish_reason(candidate.get("finishReason"))
-
-        return {
-            "id": f"msg_{gemini_response.get('modelVersion', 'gemini')}",
-            "type": "message",
-            "role": "assistant",
-            "content": claude_content,
-            "model": gemini_response.get("modelVersion", "gemini"),
-            "stop_reason": stop_reason,
-            "stop_sequence": None,
-            "usage": usage,
-        }
-
-    def _convert_parts_to_content(self, parts: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-        """将 Gemini parts 转换为 Claude content blocks"""
-        content = []
-        for part in parts:
-            if "text" in part:
-                content.append(
-                    {
-                        "type": "text",
-                        "text": part["text"],
-                    }
-                )
-            elif "functionCall" in part:
-                func_call = part["functionCall"]
-                content.append(
-                    {
-                        "type": "tool_use",
-                        "id": f"toolu_{func_call.get('name', '')}",
-                        "name": func_call.get("name", ""),
-                        "input": func_call.get("args", {}),
-                    }
-                )
-        return content
-
-    def _convert_usage(self, usage_metadata: Dict[str, Any]) -> Dict[str, int]:
-        """转换使用量信息"""
-        return {
-            "input_tokens": usage_metadata.get("promptTokenCount", 0),
-            "output_tokens": usage_metadata.get("candidatesTokenCount", 0),
-            "cache_creation_input_tokens": 0,
-            "cache_read_input_tokens": usage_metadata.get("cachedContentTokenCount", 0),
-        }
-
-    def _convert_finish_reason(self, finish_reason: Optional[str]) -> Optional[str]:
-        """转换停止原因"""
-        mapping = {
-            "STOP": "end_turn",
-            "MAX_TOKENS": "max_tokens",
-            "SAFETY": "content_filtered",
-            "RECITATION": "content_filtered",
-            "OTHER": "stop_sequence",
-        }
-        if finish_reason is None:
-            return "end_turn"
-        return mapping.get(finish_reason, "end_turn")
-
-    def _create_empty_response(self) -> Dict[str, Any]:
-        """创建空响应"""
-        return {
-            "id": "msg_empty",
-            "type": "message",
-            "role": "assistant",
-            "content": [],
-            "model": "gemini",
-            "stop_reason": "end_turn",
-            "stop_sequence": None,
-            "usage": {
-                "input_tokens": 0,
-                "output_tokens": 0,
-            },
-        }
-
-
-class OpenAIToGeminiConverter:
-    """
-    OpenAI -> Gemini 请求转换器
-
-    将 OpenAI Chat Completions API 格式转换为 Gemini generateContent 格式
-    """
-
-    def convert_request(self, openai_request: Dict[str, Any]) -> Dict[str, Any]:
-        """
-        将 OpenAI 请求转换为 Gemini 请求
-
-        Args:
-            openai_request: OpenAI 格式的请求字典
-
-        Returns:
-            Gemini 格式的请求字典
-        """
-        messages = openai_request.get("messages", [])
-
-        # 分离 system 消息和其他消息
-        system_messages = []
-        other_messages = []
-        for msg in messages:
-            if msg.get("role") == "system":
-                system_messages.append(msg)
-            else:
-                other_messages.append(msg)
-
-        gemini_request: Dict[str, Any] = {
-            "contents": self._convert_messages(other_messages),
-        }
-
-        # 转换 system messages
-        if system_messages:
-            system_text = "\n".join(msg.get("content", "") for msg in system_messages)
-            gemini_request["system_instruction"] = {"parts": [{"text": system_text}]}
-
-        # 转换生成配置
-        generation_config = self._build_generation_config(openai_request)
-        if generation_config:
-            gemini_request["generation_config"] = generation_config
-
-        # 转换工具
-        tools = openai_request.get("tools")
-        if tools:
-            gemini_request["tools"] = self._convert_tools(tools)
-
-        return gemini_request
-
-    def _convert_messages(self, messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-        """转换消息列表"""
-        contents = []
-        for msg in messages:
-            role = msg.get("role", "user")
-            gemini_role = "model" if role == "assistant" else "user"
-
-            content = msg.get("content", "")
-            parts = self._convert_content_to_parts(content)
-
-            # 处理工具调用
-            tool_calls = msg.get("tool_calls", [])
-            for tc in tool_calls:
-                if tc.get("type") == "function":
-                    func = tc.get("function", {})
-                    import json
-
-                    try:
-                        args = json.loads(func.get("arguments", "{}"))
-                    except json.JSONDecodeError:
-                        args = {}
-                    parts.append(
-                        {
-                            "function_call": {
-                                "name": func.get("name", ""),
-                                "args": args,
-                            }
-                        }
-                    )
-
-            if parts:
-                contents.append(
-                    {
-                        "role": gemini_role,
-                        "parts": parts,
-                    }
-                )
-        return contents
-
-    def _convert_content_to_parts(self, content: Any) -> List[Dict[str, Any]]:
-        """将 OpenAI 内容转换为 Gemini parts"""
-        if content is None:
-            return []
-
-        if isinstance(content, str):
-            return [{"text": content}]
-
-        if isinstance(content, list):
-            parts: List[Dict[str, Any]] = []
-            for item in content:
-                if isinstance(item, str):
-                    parts.append({"text": item})
-                elif isinstance(item, dict):
-                    item_type = item.get("type")
-                    if item_type == "text":
-                        parts.append({"text": item.get("text", "")})
-                    elif item_type == "image_url":
-                        # OpenAI 图片 URL 格式
-                        image_url = item.get("image_url", {})
-                        url = image_url.get("url", "")
-                        if url.startswith("data:"):
-                            # base64 数据 URL
-                            # 格式: data:image/png;base64,xxxxx
-                            try:
-                                header, data = url.split(",", 1)
-                                mime_type = header.split(":")[1].split(";")[0]
-                                parts.append(
-                                    {
-                                        "inline_data": {
-                                            "mime_type": mime_type,
-                                            "data": data,
-                                        }
-                                    }
-                                )
-                            except (ValueError, IndexError):
-                                pass
-            return parts
-
-        return [{"text": str(content)}]
-
-    def _build_generation_config(self, openai_request: Dict[str, Any]) -> Optional[Dict[str, Any]]:
-        """构建生成配置"""
-        config: Dict[str, Any] = {}
-
-        if "max_tokens" in openai_request:
-            config["max_output_tokens"] = openai_request["max_tokens"]
-        if "temperature" in openai_request:
-            config["temperature"] = openai_request["temperature"]
-        if "top_p" in openai_request:
-            config["top_p"] = openai_request["top_p"]
-        if "stop" in openai_request:
-            stop = openai_request["stop"]
-            if isinstance(stop, str):
-                config["stop_sequences"] = [stop]
-            elif isinstance(stop, list):
-                config["stop_sequences"] = stop
-        if "n" in openai_request:
-            config["candidate_count"] = openai_request["n"]
-
-        return config if config else None
-
-    def _convert_tools(self, tools: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
-        """转换工具定义"""
-        function_declarations = []
-        for tool in tools:
-            if tool.get("type") == "function":
-                func = tool.get("function", {})
-                func_decl = {
-                    "name": func.get("name", ""),
-                }
-                if "description" in func:
-                    func_decl["description"] = func["description"]
-                if "parameters" in func:
-                    func_decl["parameters"] = func["parameters"]
-                function_declarations.append(func_decl)
-
-        return [{"function_declarations": function_declarations}]
-
-
-class GeminiToOpenAIConverter:
-    """
-    Gemini -> OpenAI 响应转换器
-
-    将 Gemini generateContent 响应转换为 OpenAI Chat Completions API 格式
-    """
-
-    def convert_response(self, gemini_response: Dict[str, Any]) -> Dict[str, Any]:
-        """
-        将 Gemini 响应转换为 OpenAI 响应
-
-        Args:
-            gemini_response: Gemini 格式的响应字典
-
-        Returns:
-            OpenAI 格式的响应字典
-        """
-        import time
-
-        candidates = gemini_response.get("candidates", [])
-        choices = []
-
-        for i, candidate in enumerate(candidates):
-            content = candidate.get("content", {})
-            parts = content.get("parts", [])
-
-            # 提取文本内容
-            text_parts = []
-            tool_calls = []
-
-            for part in parts:
-                if "text" in part:
-                    text_parts.append(part["text"])
-                elif "functionCall" in part:
-                    func_call = part["functionCall"]
-                    import json
-
-                    tool_calls.append(
-                        {
-                            "id": f"call_{func_call.get('name', '')}_{i}",
-                            "type": "function",
-                            "function": {
-                                "name": func_call.get("name", ""),
-                                "arguments": json.dumps(func_call.get("args", {})),
-                            },
-                        }
-                    )
-
-            message: Dict[str, Any] = {
-                "role": "assistant",
-                "content": "".join(text_parts) if text_parts else None,
-            }
-
-            if tool_calls:
-                message["tool_calls"] = tool_calls
-
-            finish_reason = self._convert_finish_reason(candidate.get("finishReason"))
-
-            choices.append(
-                {
-                    "index": i,
-                    "message": message,
-                    "finish_reason": finish_reason,
-                }
-            )
-
-        # 转换使用量
-        usage = self._convert_usage(gemini_response.get("usageMetadata", {}))
-
-        return {
-            "id": f"chatcmpl-{gemini_response.get('modelVersion', 'gemini')}",
-            "object": "chat.completion",
-            "created": int(time.time()),
-            "model": gemini_response.get("modelVersion", "gemini"),
-            "choices": choices,
-            "usage": usage,
-        }
-
-    def _convert_usage(self, usage_metadata: Dict[str, Any]) -> Dict[str, int]:
-        """转换使用量信息"""
-        prompt_tokens = usage_metadata.get("promptTokenCount", 0)
-        completion_tokens = usage_metadata.get("candidatesTokenCount", 0)
-        return {
-            "prompt_tokens": prompt_tokens,
-            "completion_tokens": completion_tokens,
-            "total_tokens": prompt_tokens + completion_tokens,
-        }
-
-    def _convert_finish_reason(self, finish_reason: Optional[str]) -> str:
-        """转换停止原因"""
-        mapping = {
-            "STOP": "stop",
-            "MAX_TOKENS": "length",
-            "SAFETY": "content_filter",
-            "RECITATION": "content_filter",
-            "OTHER": "stop",
-        }
-        if finish_reason is None:
-            return "stop"
-        return mapping.get(finish_reason, "stop")
-
-
-__all__ = [
-    "ClaudeToGeminiConverter",
-    "GeminiToClaudeConverter",
-    "OpenAIToGeminiConverter",
-    "GeminiToOpenAIConverter",
-]

src/api/handlers/gemini/handler.py

@@ -62,7 +62,7 @@ class GeminiChatHandler(ChatHandlerBase):
         Returns:
             GeminiRequest 对象
         """
-        from src.api.handlers.gemini.converter import (
+        from src.core.api_format import (
             ClaudeToGeminiConverter,
             OpenAIToGeminiConverter,
         )

src/api/handlers/openai/converter.py

@@ -1,424 +0,0 @@
-"""
-Claude -> OpenAI 格式转换器
-
-将 Claude Messages API 格式转换为 OpenAI Chat Completions API 格式。
-"""
-
-from __future__ import annotations
-
-import json
-import time
-import uuid
-from typing import Any, Dict, List, Optional, Union
-
-from pydantic import BaseModel
-
-
-class ClaudeToOpenAIConverter:
-    """
-    Claude -> OpenAI 格式转换器
-
-    支持：
-    - 请求转换：Claude Request -> OpenAI Chat Request
-    - 响应转换：Claude Response -> OpenAI Chat Response
-    - 流式转换：Claude SSE -> OpenAI SSE
-    """
-
-    # 内容类型常量
-    CONTENT_TYPE_TEXT = "text"
-    CONTENT_TYPE_IMAGE = "image"
-    CONTENT_TYPE_TOOL_USE = "tool_use"
-    CONTENT_TYPE_TOOL_RESULT = "tool_result"
-
-    # 停止原因映射
-    STOP_REASON_MAP = {
-        "end_turn": "stop",
-        "max_tokens": "length",
-        "stop_sequence": "stop",
-        "tool_use": "tool_calls",
-    }
-
-    def __init__(self, model_mapping: Optional[Dict[str, str]] = None):
-        """
-        Args:
-            model_mapping: Claude 模型到 OpenAI 模型的映射
-        """
-        self._model_mapping = model_mapping or {}
-
-    # ==================== 请求转换 ====================
-
-    def convert_request(self, request: Union[Dict[str, Any], BaseModel]) -> Dict[str, Any]:
-        """
-        将 Claude 请求转换为 OpenAI 格式
-
-        Args:
-            request: Claude 请求（Dict 或 Pydantic 模型）
-
-        Returns:
-            OpenAI 格式的请求字典
-        """
-        if hasattr(request, "model_dump"):
-            data = request.model_dump(exclude_none=True)
-        else:
-            data = dict(request)
-
-        # 模型映射
-        model = data.get("model", "")
-        openai_model = self._model_mapping.get(model, model)
-
-        # 构建消息列表
-        messages: List[Dict[str, Any]] = []
-
-        # 处理 system 消息
-        system_content = self._extract_text_content(data.get("system"))
-        if system_content:
-            messages.append({"role": "system", "content": system_content})
-
-        # 处理对话消息
-        for message in data.get("messages", []):
-            converted = self._convert_message(message)
-            if converted:
-                messages.append(converted)
-
-        # 构建 OpenAI 请求
-        result: Dict[str, Any] = {
-            "model": openai_model,
-            "messages": messages,
-        }
-
-        # 可选参数
-        if data.get("max_tokens"):
-            result["max_tokens"] = data["max_tokens"]
-        if data.get("temperature") is not None:
-            result["temperature"] = data["temperature"]
-        if data.get("top_p") is not None:
-            result["top_p"] = data["top_p"]
-        if data.get("stream"):
-            result["stream"] = data["stream"]
-        if data.get("stop_sequences"):
-            result["stop"] = data["stop_sequences"]
-
-        # 工具转换
-        tools = self._convert_tools(data.get("tools"))
-        if tools:
-            result["tools"] = tools
-
-        tool_choice = self._convert_tool_choice(data.get("tool_choice"))
-        if tool_choice:
-            result["tool_choice"] = tool_choice
-
-        return result
-
-    def _convert_message(self, message: Dict[str, Any]) -> Optional[Dict[str, Any]]:
-        """转换单条消息"""
-        role = message.get("role")
-
-        if role == "user":
-            return self._convert_user_message(message)
-        if role == "assistant":
-            return self._convert_assistant_message(message)
-
-        return None
-
-    def _convert_user_message(self, message: Dict[str, Any]) -> Dict[str, Any]:
-        """转换用户消息"""
-        content = message.get("content")
-
-        if isinstance(content, str):
-            return {"role": "user", "content": content}
-
-        openai_content: List[Dict[str, Any]] = []
-        for block in content or []:
-            block_type = block.get("type")
-
-            if block_type == self.CONTENT_TYPE_TEXT:
-                openai_content.append({"type": "text", "text": block.get("text", "")})
-            elif block_type == self.CONTENT_TYPE_IMAGE:
-                source = block.get("source", {})
-                media_type = source.get("media_type", "image/jpeg")
-                data = source.get("data", "")
-                openai_content.append(
-                    {"type": "image_url", "image_url": {"url": f"data:{media_type};base64,{data}"}}
-                )
-            elif block_type == self.CONTENT_TYPE_TOOL_RESULT:
-                tool_content = block.get("content", "")
-                rendered = self._render_tool_content(tool_content)
-                openai_content.append({"type": "text", "text": f"Tool result: {rendered}"})
-
-        # 简化单文本内容
-        if len(openai_content) == 1 and openai_content[0]["type"] == "text":
-            return {"role": "user", "content": openai_content[0]["text"]}
-
-        return {"role": "user", "content": openai_content or ""}
-
-    def _convert_assistant_message(self, message: Dict[str, Any]) -> Dict[str, Any]:
-        """转换助手消息"""
-        content = message.get("content")
-        text_parts: List[str] = []
-        tool_calls: List[Dict[str, Any]] = []
-
-        if isinstance(content, str):
-            text_parts.append(content)
-        else:
-            for idx, block in enumerate(content or []):
-                block_type = block.get("type")
-
-                if block_type == self.CONTENT_TYPE_TEXT:
-                    text_parts.append(block.get("text", ""))
-                elif block_type == self.CONTENT_TYPE_TOOL_USE:
-                    tool_calls.append(
-                        {
-                            "id": block.get("id", f"call_{idx}"),
-                            "type": "function",
-                            "function": {
-                                "name": block.get("name", ""),
-                                "arguments": json.dumps(block.get("input", {}), ensure_ascii=False),
-                            },
-                        }
-                    )
-
-        result: Dict[str, Any] = {"role": "assistant"}
-
-        message_content = "\n".join([p for p in text_parts if p]) or None
-        if message_content:
-            result["content"] = message_content
-
-        if tool_calls:
-            result["tool_calls"] = tool_calls
-
-        return result
-
-    def _convert_tools(
-        self, tools: Optional[List[Dict[str, Any]]]
-    ) -> Optional[List[Dict[str, Any]]]:
-        """转换工具定义"""
-        if not tools:
-            return None
-
-        result: List[Dict[str, Any]] = []
-        for tool in tools:
-            result.append(
-                {
-                    "type": "function",
-                    "function": {
-                        "name": tool.get("name", ""),
-                        "description": tool.get("description"),
-                        "parameters": tool.get("input_schema", {}),
-                    },
-                }
-            )
-        return result
-
-    def _convert_tool_choice(
-        self, tool_choice: Optional[Dict[str, Any]]
-    ) -> Optional[Union[str, Dict[str, Any]]]:
-        """转换工具选择"""
-        if tool_choice is None:
-            return None
-
-        choice_type = tool_choice.get("type")
-        if choice_type in ("tool", "tool_use"):
-            return {"type": "function", "function": {"name": tool_choice.get("name", "")}}
-        if choice_type == "any":
-            return "required"
-        if choice_type == "auto":
-            return "auto"
-
-        return tool_choice
-
-    # ==================== 响应转换 ====================
-
-    def convert_response(self, response: Dict[str, Any]) -> Dict[str, Any]:
-        """
-        将 Claude 响应转换为 OpenAI 格式
-
-        Args:
-            response: Claude 响应字典
-
-        Returns:
-            OpenAI 格式的响应字典
-        """
-        # 提取内容
-        content_parts: List[str] = []
-        tool_calls: List[Dict[str, Any]] = []
-
-        for idx, block in enumerate(response.get("content", [])):
-            block_type = block.get("type")
-
-            if block_type == self.CONTENT_TYPE_TEXT:
-                content_parts.append(block.get("text", ""))
-            elif block_type == self.CONTENT_TYPE_TOOL_USE:
-                tool_calls.append(
-                    {
-                        "id": block.get("id", f"call_{idx}"),
-                        "type": "function",
-                        "function": {
-                            "name": block.get("name", ""),
-                            "arguments": json.dumps(block.get("input", {}), ensure_ascii=False),
-                        },
-                    }
-                )
-
-        # 构建消息
-        message: Dict[str, Any] = {"role": "assistant"}
-        text_content = "\n".join([p for p in content_parts if p]) or None
-        if text_content:
-            message["content"] = text_content
-        if tool_calls:
-            message["tool_calls"] = tool_calls
-
-        # 转换停止原因
-        stop_reason = response.get("stop_reason")
-        finish_reason = self.STOP_REASON_MAP.get(stop_reason, stop_reason)
-
-        # 转换 usage
-        usage = response.get("usage", {})
-        openai_usage = {
-            "prompt_tokens": usage.get("input_tokens", 0),
-            "completion_tokens": usage.get("output_tokens", 0),
-            "total_tokens": (usage.get("input_tokens", 0) + usage.get("output_tokens", 0)),
-        }
-
-        return {
-            "id": f"chatcmpl-{response.get('id', uuid.uuid4().hex[:8])}",
-            "object": "chat.completion",
-            "created": int(time.time()),
-            "model": response.get("model", ""),
-            "choices": [
-                {
-                    "index": 0,
-                    "message": message,
-                    "finish_reason": finish_reason,
-                }
-            ],
-            "usage": openai_usage,
-        }
-
-    # ==================== 流式转换 ====================
-
-    def convert_stream_event(
-        self,
-        event: Dict[str, Any],
-        model: str = "",
-        message_id: Optional[str] = None,
-    ) -> Optional[Dict[str, Any]]:
-        """
-        将 Claude SSE 事件转换为 OpenAI 格式
-
-        Args:
-            event: Claude SSE 事件
-            model: 模型名称
-            message_id: 消息 ID
-
-        Returns:
-            OpenAI 格式的 SSE chunk，如果无法转换返回 None
-        """
-        event_type = event.get("type")
-        chunk_id = f"chatcmpl-{(message_id or 'stream')[-8:]}"
-
-        if event_type == "message_start":
-            message = event.get("message", {})
-            return self._base_chunk(
-                chunk_id,
-                model or message.get("model", ""),
-                {"role": "assistant"},
-            )
-
-        if event_type == "content_block_start":
-            content_block = event.get("content_block", {})
-            if content_block.get("type") == self.CONTENT_TYPE_TOOL_USE:
-                delta = {
-                    "tool_calls": [
-                        {
-                            "index": event.get("index", 0),
-                            "id": content_block.get("id", ""),
-                            "type": "function",
-                            "function": {
-                                "name": content_block.get("name", ""),
-                                "arguments": "",
-                            },
-                        }
-                    ]
-                }
-                return self._base_chunk(chunk_id, model, delta)
-            return None
-
-        if event_type == "content_block_delta":
-            delta_payload = event.get("delta", {})
-            delta_type = delta_payload.get("type")
-
-            if delta_type == "text_delta":
-                delta = {"content": delta_payload.get("text", "")}
-                return self._base_chunk(chunk_id, model, delta)
-
-            if delta_type == "input_json_delta":
-                delta = {
-                    "tool_calls": [
-                        {
-                            "index": event.get("index", 0),
-                            "function": {"arguments": delta_payload.get("partial_json", "")},
-                        }
-                    ]
-                }
-                return self._base_chunk(chunk_id, model, delta)
-            return None
-
-        if event_type == "message_delta":
-            delta = event.get("delta", {})
-            stop_reason = delta.get("stop_reason")
-            finish_reason = self.STOP_REASON_MAP.get(stop_reason, stop_reason)
-            return self._base_chunk(chunk_id, model, {}, finish_reason=finish_reason)
-
-        if event_type == "message_stop":
-            return self._base_chunk(chunk_id, model, {}, finish_reason="stop")
-
-        return None
-
-    def _base_chunk(
-        self,
-        chunk_id: str,
-        model: str,
-        delta: Dict[str, Any],
-        finish_reason: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """构建基础 OpenAI chunk"""
-        return {
-            "id": chunk_id,
-            "object": "chat.completion.chunk",
-            "created": int(time.time()),
-            "model": model,
-            "system_fingerprint": None,
-            "choices": [
-                {
-                    "index": 0,
-                    "delta": delta,
-                    "finish_reason": finish_reason,
-                }
-            ],
-        }
-
-    # ==================== 工具方法 ====================
-
-    def _extract_text_content(
-        self, content: Optional[Union[str, List[Dict[str, Any]]]]
-    ) -> Optional[str]:
-        """提取文本内容"""
-        if isinstance(content, str):
-            return content
-        if isinstance(content, list):
-            parts = [
-                block.get("text", "")
-                for block in content
-                if block.get("type") == self.CONTENT_TYPE_TEXT
-            ]
-            return "\n\n".join(filter(None, parts)) or None
-        return None
-
-    def _render_tool_content(self, tool_content: Any) -> str:
-        """渲染工具内容"""
-        if isinstance(tool_content, list):
-            return json.dumps(tool_content, ensure_ascii=False)
-        return str(tool_content)
-
-
-__all__ = ["ClaudeToOpenAIConverter"]

src/api/handlers/openai/handler.py

@@ -73,7 +73,7 @@ class OpenAIChatHandler(ChatHandlerBase):
         Returns:
             OpenAIRequest 对象
         """
-        from src.api.handlers.openai.converter import ClaudeToOpenAIConverter
+        from src.core.api_format import ClaudeToOpenAIConverter
         from src.models.claude import ClaudeMessagesRequest
         from src.models.openai import OpenAIRequest
 

src/api/public/catalog.py

@@ -609,8 +609,7 @@ class PublicApiFormatHealthMonitorAdapter(PublicApiAdapter):
             )
 
             # 获取本站入口路径
-            from src.core.api_format_metadata import get_local_path
-            from src.core.enums import APIFormat
+            from src.core.api_format import APIFormat, get_local_path
 
             try:
                 api_format_enum = APIFormat(api_format)

src/api/public/claude.py

@@ -15,8 +15,7 @@ from src.api.handlers.claude import (
     ClaudeTokenCountAdapter,
     build_claude_adapter,
 )
-from src.core.api_format_metadata import get_api_format_definition
-from src.core.enums import APIFormat
+from src.core.api_format import APIFormat, get_api_format_definition
 from src.database import get_db
 
 _claude_def = get_api_format_definition(APIFormat.CLAUDE)

src/api/public/gemini.py

@@ -16,8 +16,7 @@ from sqlalchemy.orm import Session
 from src.api.base.pipeline import ApiRequestPipeline
 from src.api.handlers.gemini import build_gemini_adapter
 from src.api.handlers.gemini_cli import build_gemini_cli_adapter
-from src.core.api_format_metadata import get_api_format_definition
-from src.core.enums import APIFormat
+from src.core.api_format import APIFormat, get_api_format_definition
 from src.database import get_db
 
 # 从配置获取路径前缀

src/api/public/models.py

@@ -20,8 +20,12 @@ from src.api.base.models_service import (
     get_available_provider_ids,
     list_available_models,
 )
-from src.core.api_format_metadata import API_FORMAT_DEFINITIONS, ApiFormatDefinition
-from src.core.enums import APIFormat
+from src.core.api_format import (
+    API_FORMAT_DEFINITIONS,
+    APIFormat,
+    ApiFormatDefinition,
+    detect_format_and_key_from_starlette,
+)
 from src.core.logger import logger
 from src.database import get_db
 from src.models.database import ApiKey, User
@@ -72,26 +76,7 @@ def _detect_api_format_and_key(request: Request) -> Tuple[str, Optional[str]]:
     Returns:
         (api_format, api_key) 元组
     """
-    # Claude: x-api-key + anthropic-version (必须同时存在)
-    claude_def = API_FORMAT_DEFINITIONS[APIFormat.CLAUDE]
-    claude_key = _extract_api_key_from_request(request, claude_def)
-    if claude_key and request.headers.get("anthropic-version"):
-        return "claude", claude_key
-
-    # Gemini: x-goog-api-key (header 类型) 或 ?key=
-    gemini_def = API_FORMAT_DEFINITIONS[APIFormat.GEMINI]
-    gemini_key = _extract_api_key_from_request(request, gemini_def)
-    if gemini_key:
-        return "gemini", gemini_key
-
-    # OpenAI: Authorization: Bearer (默认)
-    # 注意: 如果只有 x-api-key 但没有 anthropic-version，也走 OpenAI 格式
-    openai_def = API_FORMAT_DEFINITIONS[APIFormat.OPENAI]
-    openai_key = _extract_api_key_from_request(request, openai_def)
-    # 如果 OpenAI 格式没有 key，但有 x-api-key，也用它（兼容）
-    if not openai_key and claude_key:
-        openai_key = claude_key
-    return "openai", openai_key
+    return detect_format_and_key_from_starlette(request)
 
 
 def _get_formats_for_api(api_format: str) -> list[str]:

src/api/public/openai.py

@@ -13,8 +13,7 @@ from sqlalchemy.orm import Session
 from src.api.base.pipeline import ApiRequestPipeline
 from src.api.handlers.openai import OpenAIChatAdapter
 from src.api.handlers.openai_cli import OpenAICliAdapter
-from src.core.api_format_metadata import get_api_format_definition
-from src.core.enums import APIFormat
+from src.core.api_format import APIFormat, get_api_format_definition
 from src.database import get_db
 
 _openai_def = get_api_format_definition(APIFormat.OPENAI)