feat: Enhance OpenAI compatibility and introduce unified LLM service data models

- Refactored model fetching logic to support various authentication methods for OpenAI-compatible APIs.
- Introduced new data models for LLM service requests and responses to standardize interactions across layers.
- Added an adapter base class for unified request execution across different providers.
- Implemented utility functions for building OpenAI-compatible client configurations and request overrides.

src/llm_models/payload_content/message.py

@@ -1,133 +1,280 @@
+from dataclasses import dataclass, field
 from enum import Enum
-from typing import List, Optional
+from typing import List, Tuple
 
 from .tool_option import ToolCall
 
 
-# 设计这系列类的目的是为未来可能的扩展做准备
+class RoleType(str, Enum):
+    """消息角色类型。"""
 
-
-class RoleType(Enum):
     System = "system"
     User = "user"
     Assistant = "assistant"
     Tool = "tool"
 
 
-SUPPORTED_IMAGE_FORMATS = ["jpg", "jpeg", "png", "webp", "gif"]  # openai支持的图片格式
+SUPPORTED_IMAGE_FORMATS = ["jpg", "jpeg", "png", "webp", "gif"]
+"""默认支持的图片格式列表。"""
 
 
+@dataclass(slots=True)
+class TextMessagePart:
+    """文本消息片段。"""
+
+    text: str
+
+    def __post_init__(self) -> None:
+        """执行文本片段的基础校验。
+
+        Raises:
+            ValueError: 当文本为空时抛出。
+        """
+        if self.text == "":
+            raise ValueError("文本消息片段不能为空字符串")
+
+
+@dataclass(slots=True)
+class ImageMessagePart:
+    """Base64 图片消息片段。"""
+
+    image_format: str
+    image_base64: str
+
+    def __post_init__(self) -> None:
+        """执行图片片段的基础校验。
+
+        Raises:
+            ValueError: 当图片格式或 Base64 数据无效时抛出。
+        """
+        if self.image_format.lower() not in SUPPORTED_IMAGE_FORMATS:
+            raise ValueError("不受支持的图片格式")
+        if not self.image_base64:
+            raise ValueError("图片的 base64 编码不能为空")
+
+    @property
+    def normalized_image_format(self) -> str:
+        """获取规范化后的图片格式。
+
+        Returns:
+            str: 规范化后的图片格式。`jpg` 会被统一为 `jpeg`。
+        """
+        image_format = self.image_format.lower()
+        if image_format in {"jpg", "jpeg"}:
+            return "jpeg"
+        return image_format
+
+
+MessagePart = TextMessagePart | ImageMessagePart
+
+
+@dataclass(slots=True)
 class Message:
-    def __init__(
-        self,
-        role: RoleType,
-        content: str | list[tuple[str, str] | str],
-        tool_call_id: str | None = None,
-        tool_calls: Optional[List[ToolCall]] = None,
-    ):
+    """统一消息模型。"""
+
+    role: RoleType
+    parts: List[MessagePart] = field(default_factory=list)
+    tool_call_id: str | None = None
+    tool_calls: List[ToolCall] | None = None
+
+    def __post_init__(self) -> None:
+        """执行消息对象的基础校验。
+
+        Raises:
+            ValueError: 当消息内容或工具调用信息不完整时抛出。
         """
-        初始化消息对象
-        （不应直接修改Message类，而应使用MessageBuilder类来构建对象）
+        if not self.parts and not (self.role == RoleType.Assistant and self.tool_calls):
+            raise ValueError("消息内容不能为空")
+        if self.role == RoleType.Tool and not self.tool_call_id:
+            raise ValueError("Tool 角色的工具调用 ID 不能为空")
+
+    @property
+    def content(self) -> str | List[Tuple[str, str] | str]:
+        """获取兼容旧逻辑的内容视图。
+
+        Returns:
+            str | List[Tuple[str, str] | str]: 当仅包含一个文本片段时返回字符串，
+            否则返回混合列表，其中图片片段表示为 `(format, base64)` 元组。
         """
-        self.role: RoleType = role
-        self.content: str | list[tuple[str, str] | str] = content
-        self.tool_call_id: str | None = tool_call_id
-        self.tool_calls: Optional[List[ToolCall]] = tool_calls
+        if len(self.parts) == 1 and isinstance(self.parts[0], TextMessagePart):
+            return self.parts[0].text
+        content_items: List[Tuple[str, str] | str] = []
+        for part in self.parts:
+            if isinstance(part, TextMessagePart):
+                content_items.append(part.text)
+            else:
+                content_items.append((part.image_format, part.image_base64))
+        return content_items
+
+    def get_text_content(self) -> str:
+        """提取消息中的所有文本片段。
+
+        Returns:
+            str: 以原始顺序拼接后的文本内容。
+        """
+        return "".join(part.text for part in self.parts if isinstance(part, TextMessagePart))
 
     def __str__(self) -> str:
+        """生成便于调试的字符串表示。
+
+        Returns:
+            str: 当前消息对象的可读摘要。
+        """
         return (
-            f"Role: {self.role}, Content: {self.content}, "
+            f"Role: {self.role}, Parts: {self.parts}, "
             f"Tool Call ID: {self.tool_call_id}, Tool Calls: {self.tool_calls}"
         )
 
 
 class MessageBuilder:
-    def __init__(self):
+    """消息构建器。"""
+
+    def __init__(self) -> None:
+        """初始化构建器。"""
         self.__role: RoleType = RoleType.User
-        self.__content: list[tuple[str, str] | str] = []
+        self.__parts: List[MessagePart] = []
         self.__tool_call_id: str | None = None
-        self.__tool_calls: Optional[List[ToolCall]] = None
+        self.__tool_calls: List[ToolCall] | None = None
 
     def set_role(self, role: RoleType = RoleType.User) -> "MessageBuilder":
-        """
-        设置角色（默认为User）
-        :param role: 角色
-        :return: MessageBuilder对象
+        """设置消息角色。
+
+        Args:
+            role: 目标角色，默认为 `user`。
+
+        Returns:
+            MessageBuilder: 当前构建器实例。
         """
         self.__role = role
         return self
 
+    def add_text_part(self, text: str) -> "MessageBuilder":
+        """追加文本片段。
+
+        Args:
+            text: 文本内容。
+
+        Returns:
+            MessageBuilder: 当前构建器实例。
+        """
+        self.__parts.append(TextMessagePart(text=text))
+        return self
+
     def add_text_content(self, text: str) -> "MessageBuilder":
+        """追加文本片段。
+
+        Args:
+            text: 文本内容。
+
+        Returns:
+            MessageBuilder: 当前构建器实例。
         """
-        添加文本内容
-        :param text: 文本内容
-        :return: MessageBuilder对象
+        return self.add_text_part(text)
+
+    def add_image_base64_part(
+        self,
+        image_format: str,
+        image_base64: str,
+        support_formats: List[str] = SUPPORTED_IMAGE_FORMATS,
+    ) -> "MessageBuilder":
+        """追加 Base64 图片片段。
+
+        Args:
+            image_format: 图片格式。
+            image_base64: 图片的 Base64 编码。
+            support_formats: 允许的图片格式列表。
+
+        Returns:
+            MessageBuilder: 当前构建器实例。
+
+        Raises:
+            ValueError: 当图片格式不被支持时抛出。
         """
-        self.__content.append(text)
+        if image_format.lower() not in support_formats:
+            raise ValueError("不受支持的图片格式")
+        self.__parts.append(ImageMessagePart(image_format=image_format, image_base64=image_base64))
         return self
 
     def add_image_content(
         self,
         image_format: str,
         image_base64: str,
-        support_formats: list[str] = SUPPORTED_IMAGE_FORMATS,  # 默认支持格式
+        support_formats: List[str] = SUPPORTED_IMAGE_FORMATS,
     ) -> "MessageBuilder":
-        """
-        添加图片内容
-        :param image_format: 图片格式
-        :param image_base64: 图片的base64编码
-        :return: MessageBuilder对象
-        """
-        if image_format.lower() not in support_formats:
-            raise ValueError("不受支持的图片格式")
-        if not image_base64:
-            raise ValueError("图片的base64编码不能为空")
-        self.__content.append((image_format, image_base64))
-        return self
+        """追加 Base64 图片片段。
 
-    def add_tool_call(self, tool_call_id: str) -> "MessageBuilder":
+        Args:
+            image_format: 图片格式。
+            image_base64: 图片的 Base64 编码。
+            support_formats: 允许的图片格式列表。
+
+        Returns:
+            MessageBuilder: 当前构建器实例。
         """
-        添加工具调用指令（调用时请确保已设置为Tool角色）
-        :param tool_call_id: 工具调用指令的id
-        :return: MessageBuilder对象
+        return self.add_image_base64_part(
+            image_format=image_format,
+            image_base64=image_base64,
+            support_formats=support_formats,
+        )
+
+    def set_tool_call_id(self, tool_call_id: str) -> "MessageBuilder":
+        """设置工具结果消息引用的工具调用 ID。
+
+        Args:
+            tool_call_id: 工具调用 ID。
+
+        Returns:
+            MessageBuilder: 当前构建器实例。
+
+        Raises:
+            ValueError: 当当前角色不是 `tool` 或 ID 为空时抛出。
         """
         if self.__role != RoleType.Tool:
-            raise ValueError("仅当角色为Tool时才能添加工具调用ID")
+            raise ValueError("仅当角色为 Tool 时才能设置工具调用 ID")
         if not tool_call_id:
-            raise ValueError("工具调用ID不能为空")
+            raise ValueError("工具调用 ID 不能为空")
         self.__tool_call_id = tool_call_id
         return self
 
-    def set_tool_calls(self, tool_calls: List[ToolCall]) -> "MessageBuilder":
+    def add_tool_call(self, tool_call_id: str) -> "MessageBuilder":
+        """设置工具结果消息引用的工具调用 ID。
+
+        Args:
+            tool_call_id: 工具调用 ID。
+
+        Returns:
+            MessageBuilder: 当前构建器实例。
         """
-        设置助手消息的工具调用列表
-        :param tool_calls: 工具调用列表
-        :return: MessageBuilder对象
+        return self.set_tool_call_id(tool_call_id)
+
+    def set_tool_calls(self, tool_calls: List[ToolCall]) -> "MessageBuilder":
+        """设置助手消息中的工具调用列表。
+
+        Args:
+            tool_calls: 工具调用列表。
+
+        Returns:
+            MessageBuilder: 当前构建器实例。
+
+        Raises:
+            ValueError: 当当前角色不是 `assistant` 或列表为空时抛出。
         """
         if self.__role != RoleType.Assistant:
-            raise ValueError("仅当角色为Assistant时才能设置工具调用列表")
+            raise ValueError("仅当角色为 Assistant 时才能设置工具调用列表")
         if not tool_calls:
             raise ValueError("工具调用列表不能为空")
-        self.__tool_calls = tool_calls
+        self.__tool_calls = list(tool_calls)
         return self
 
     def build(self) -> Message:
-        """
-        构建消息对象
-        :return: Message对象
-        """
-        if len(self.__content) == 0 and not (self.__role == RoleType.Assistant and self.__tool_calls):
-            raise ValueError("内容不能为空")
-        if self.__role == RoleType.Tool and self.__tool_call_id is None:
-            raise ValueError("Tool角色的工具调用ID不能为空")
+        """构建消息对象。
 
+        Returns:
+            Message: 构建完成的消息对象。
+        """
         return Message(
             role=self.__role,
-            content=(
-                self.__content[0]
-                if (len(self.__content) == 1 and isinstance(self.__content[0], str))
-                else self.__content
-            ),
+            parts=list(self.__parts),
             tool_call_id=self.__tool_call_id,
-            tool_calls=self.__tool_calls,
+            tool_calls=list(self.__tool_calls) if self.__tool_calls else None,
         )

src/llm_models/payload_content/resp_format.py

@@ -1,51 +1,40 @@
+from copy import deepcopy
 from enum import Enum
-from typing import Optional, Any
+from typing import Any, Dict, List, Mapping, Optional, Type, cast
 
 from pydantic import BaseModel
-from typing_extensions import TypedDict, Required
+from typing_extensions import Required, TypedDict
 
 
 class RespFormatType(Enum):
-    TEXT = "text"  # 文本
-    JSON_OBJ = "json_object"  # JSON
-    JSON_SCHEMA = "json_schema"  # JSON Schema
+    """响应格式类型。"""
+
+    TEXT = "text"
+    JSON_OBJ = "json_object"
+    JSON_SCHEMA = "json_schema"
 
 
 class JsonSchema(TypedDict, total=False):
+    """内部使用的 JSON Schema 包装结构。"""
+
     name: Required[str]
-    """
-    The name of the response format.
-
-    Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length
-    of 64.
-    """
-
     description: Optional[str]
-    """
-    A description of what the response format is for, used by the model to determine
-    how to respond in the format.
-    """
-
-    schema: dict[str, object]
-    """
-    The schema for the response format, described as a JSON Schema object. Learn how
-    to build JSON schemas [here](https://json-schema.org/).
-    """
-
+    schema: Dict[str, Any]
     strict: Optional[bool]
-    """
-    Whether to enable strict schema adherence when generating the output. If set to
-    true, the model will always follow the exact schema defined in the `schema`
-    field. Only a subset of JSON Schema is supported when `strict` is `true`. To
-    learn more, read the
-    [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs).
-    """
 
 
-def _json_schema_type_check(instance) -> str | None:
+def _json_schema_type_check(instance: Mapping[str, Any]) -> str | None:
+    """检查 JSON Schema 包装结构是否合法。
+
+    Args:
+        instance: 待检查的 JSON Schema 包装字典。
+
+    Returns:
+        str | None: 不合法时返回错误信息，合法时返回 `None`。
+    """
     if "name" not in instance:
         return "schema必须包含'name'字段"
-    elif not isinstance(instance["name"], str) or instance["name"].strip() == "":
+    if not isinstance(instance["name"], str) or instance["name"].strip() == "":
         return "schema的'name'字段必须是非空字符串"
     if "description" in instance and (
         not isinstance(instance["description"], str) or instance["description"].strip() == ""
@@ -53,164 +42,198 @@ def _json_schema_type_check(instance) -> str | None:
         return "schema的'description'字段只能填入非空字符串"
     if "schema" not in instance:
         return "schema必须包含'schema'字段"
-    elif not isinstance(instance["schema"], dict):
+    if not isinstance(instance["schema"], dict):
         return "schema的'schema'字段必须是字典，详见https://json-schema.org/"
     if "strict" in instance and not isinstance(instance["strict"], bool):
         return "schema的'strict'字段只能填入布尔值"
-
     return None
 
 
-def _remove_title(schema: dict[str, Any] | list[Any]) -> dict[str, Any] | list[Any]:
-    """
-    递归移除JSON Schema中的title字段
+def _remove_title(schema: Dict[str, Any] | List[Any]) -> Dict[str, Any] | List[Any]:
+    """递归移除 JSON Schema 中的 `title` 字段。
+
+    Args:
+        schema: 待处理的 Schema 树。
+
+    Returns:
+        Dict[str, Any] | List[Any]: 处理后的 Schema 树。
     """
     if isinstance(schema, list):
-        # 如果当前Schema是列表，则对所有dict/list子元素递归调用
-        for idx, item in enumerate(schema):
+        for index, item in enumerate(schema):
             if isinstance(item, (dict, list)):
-                schema[idx] = _remove_title(item)
-    elif isinstance(schema, dict):
-        # 是字典，移除title字段，并对所有dict/list子元素递归调用
-        if "title" in schema:
-            del schema["title"]
-        for key, value in schema.items():
-            if isinstance(value, (dict, list)):
-                schema[key] = _remove_title(value)
+                schema[index] = _remove_title(item)
+        return schema
 
+    if "title" in schema:
+        del schema["title"]
+    for key, value in schema.items():
+        if isinstance(value, (dict, list)):
+            schema[key] = _remove_title(value)
     return schema
 
 
-def _link_definitions(schema: dict[str, Any]) -> dict[str, Any]:
-    """
-    链接JSON Schema中的definitions字段
+def _link_definitions(schema: Dict[str, Any]) -> Dict[str, Any]:
+    """展开 Schema 中的本地 `$defs`/`$ref` 引用。
+
+    Args:
+        schema: 待处理的根 Schema。
+
+    Returns:
+        Dict[str, Any]: 展开后的 Schema。
     """
 
     def link_definitions_recursive(
-        path: str, sub_schema: list[Any] | dict[str, Any], defs: dict[str, Any]
-    ) -> dict[str, Any]:
-        """
-        递归链接JSON Schema中的definitions字段
-        :param path: 当前路径
-        :param sub_schema: 子Schema
-        :param defs: Schema定义集
-        :return:
+        path: str,
+        sub_schema: Dict[str, Any] | List[Any],
+        definitions: Dict[str, Any],
+    ) -> Dict[str, Any] | List[Any]:
+        """递归展开局部定义。
+
+        Args:
+            path: 当前递归路径。
+            sub_schema: 当前子 Schema。
+            definitions: 已收集的定义字典。
+
+        Returns:
+            Dict[str, Any] | List[Any]: 展开后的子 Schema。
         """
         if isinstance(sub_schema, list):
-            # 如果当前Schema是列表，则遍历每个元素
-            for i in range(len(sub_schema)):
-                if isinstance(sub_schema[i], dict):
-                    sub_schema[i] = link_definitions_recursive(f"{path}/{str(i)}", sub_schema[i], defs)
-        else:
-            # 否则为字典
-            if "$defs" in sub_schema:
-                # 如果当前Schema有$def字段，则将其添加到defs中
-                key_prefix = f"{path}/$defs/"
-                for key, value in sub_schema["$defs"].items():
-                    def_key = key_prefix + key
-                    if def_key not in defs:
-                        defs[def_key] = value
-                del sub_schema["$defs"]
-            if "$ref" in sub_schema:
-                # 如果当前Schema有$ref字段，则将其替换为defs中的定义
-                def_key = sub_schema["$ref"]
-                if def_key in defs:
-                    sub_schema = defs[def_key]
-                else:
-                    raise ValueError(f"Schema中引用的定义'{def_key}'不存在")
-            # 遍历键值对
-            for key, value in sub_schema.items():
-                if isinstance(value, (dict, list)):
-                    # 如果当前值是字典或列表，则递归调用
-                    sub_schema[key] = link_definitions_recursive(f"{path}/{key}", value, defs)
+            for index, item in enumerate(sub_schema):
+                if isinstance(item, (dict, list)):
+                    sub_schema[index] = link_definitions_recursive(f"{path}/{index}", item, definitions)
+            return sub_schema
 
+        if "$defs" in sub_schema:
+            key_prefix = f"{path}/$defs/"
+            defs_payload = cast(Dict[str, Any], sub_schema["$defs"])
+            for key, value in defs_payload.items():
+                definition_key = key_prefix + key
+                if definition_key not in definitions:
+                    definitions[definition_key] = value
+            del sub_schema["$defs"]
+
+        if "$ref" in sub_schema:
+            definition_key = cast(str, sub_schema["$ref"])
+            if definition_key in definitions:
+                return definitions[definition_key]
+            raise ValueError(f"Schema中引用的定义'{definition_key}'不存在")
+
+        for key, value in sub_schema.items():
+            if isinstance(value, (dict, list)):
+                sub_schema[key] = link_definitions_recursive(f"{path}/{key}", value, definitions)
         return sub_schema
 
-    return link_definitions_recursive("#", schema, {})
+    return cast(Dict[str, Any], link_definitions_recursive("#", schema, {}))
 
 
-def _remove_defs(schema: dict[str, Any]) -> dict[str, Any]:
-    """
-    递归移除JSON Schema中的$defs字段
+def _remove_defs(schema: Dict[str, Any] | List[Any]) -> Dict[str, Any] | List[Any]:
+    """递归移除 JSON Schema 中的 `$defs` 字段。
+
+    Args:
+        schema: 待处理的 Schema 树。
+
+    Returns:
+        Dict[str, Any] | List[Any]: 处理后的 Schema 树。
     """
     if isinstance(schema, list):
-        # 如果当前Schema是列表，则对所有dict/list子元素递归调用
-        for idx, item in enumerate(schema):
+        for index, item in enumerate(schema):
             if isinstance(item, (dict, list)):
-                schema[idx] = _remove_title(item)
-    elif isinstance(schema, dict):
-        # 是字典，移除title字段，并对所有dict/list子元素递归调用
-        if "$defs" in schema:
-            del schema["$defs"]
-        for key, value in schema.items():
-            if isinstance(value, (dict, list)):
-                schema[key] = _remove_title(value)
+                schema[index] = _remove_defs(item)
+        return schema
 
+    if "$defs" in schema:
+        del schema["$defs"]
+    for key, value in schema.items():
+        if isinstance(value, (dict, list)):
+            schema[key] = _remove_defs(value)
     return schema
 
 
 class RespFormat:
-    """
-    响应格式
-    """
+    """统一响应格式定义。"""
 
     @staticmethod
-    def _generate_schema_from_model(schema):
-        json_schema = {
-            "name": schema.__name__,
-            "schema": _remove_defs(_link_definitions(_remove_title(schema.model_json_schema()))),
+    def _generate_schema_from_model(schema_model: Type[BaseModel]) -> JsonSchema:
+        """从 Pydantic 模型生成内部 JSON Schema 包装结构。
+
+        Args:
+            schema_model: Pydantic 模型类。
+
+        Returns:
+            JsonSchema: 内部统一 JSON Schema 包装结构。
+        """
+        schema_tree = deepcopy(schema_model.model_json_schema())
+        json_schema: JsonSchema = {
+            "name": schema_model.__name__,
+            "schema": cast(
+                Dict[str, Any],
+                _remove_defs(_link_definitions(cast(Dict[str, Any], _remove_title(schema_tree)))),
+            ),
             "strict": False,
         }
-        if schema.__doc__:
-            json_schema["description"] = schema.__doc__
+        if schema_model.__doc__:
+            json_schema["description"] = schema_model.__doc__
         return json_schema
 
     def __init__(
         self,
         format_type: RespFormatType = RespFormatType.TEXT,
-        schema: type | JsonSchema | None = None,
-    ):
-        """
-        响应格式
-        :param format_type: 响应格式类型（默认为文本）
-        :param schema: 模板类或JsonSchema（仅当format_type为JSON Schema时有效）
+        schema: Type[BaseModel] | JsonSchema | None = None,
+    ) -> None:
+        """初始化响应格式对象。
+
+        Args:
+            format_type: 响应格式类型。
+            schema: 模型类或 JSON Schema 包装结构，仅 `JSON_SCHEMA` 模式使用。
         """
         self.format_type: RespFormatType = format_type
+        self.schema_source: Type[BaseModel] | JsonSchema | None = schema
+        self.schema: JsonSchema | None = None
 
-        if format_type == RespFormatType.JSON_SCHEMA:
-            if schema is None:
-                raise ValueError("当format_type为'JSON_SCHEMA'时，schema不能为空")
-            if isinstance(schema, dict):
-                if check_msg := _json_schema_type_check(schema):
-                    raise ValueError(f"schema格式不正确，{check_msg}")
+        if format_type != RespFormatType.JSON_SCHEMA:
+            return
+        if schema is None:
+            raise ValueError("当format_type为'JSON_SCHEMA'时，schema不能为空")
+        if isinstance(schema, dict):
+            if check_msg := _json_schema_type_check(schema):
+                raise ValueError(f"schema格式不正确，{check_msg}")
+            self.schema = cast(JsonSchema, deepcopy(schema))
+            return
+        if isinstance(schema, type) and issubclass(schema, BaseModel):
+            try:
+                self.schema = self._generate_schema_from_model(schema)
+            except Exception as exc:
+                raise ValueError(
+                    f"自动生成JSON Schema时发生异常，请检查模型类{schema.__name__}的定义，详细信息：\n"
+                    f"{schema.__name__}:\n"
+                ) from exc
+            return
+        raise ValueError("schema必须是BaseModel的子类或JsonSchema")
 
-                self.schema = schema
-            elif issubclass(schema, BaseModel):
-                try:
-                    json_schema = self._generate_schema_from_model(schema)
+    def get_schema_object(self) -> Dict[str, Any] | None:
+        """获取内部包装中的对象级 JSON Schema。
 
-                    self.schema = json_schema
-                except Exception as e:
-                    raise ValueError(
-                        f"自动生成JSON Schema时发生异常，请检查模型类{schema.__name__}的定义，详细信息：\n"
-                        f"{schema.__name__}:\n"
-                    ) from e
-            else:
-                raise ValueError("schema必须是BaseModel的子类或JsonSchema")
-        else:
-            self.schema = None
-
-    def to_dict(self):
+        Returns:
+            Dict[str, Any] | None: 对象级 JSON Schema；不存在时返回 `None`。
         """
-        将响应格式转换为字典
-        :return: 字典
+        if self.schema is None:
+            return None
+        schema_payload = self.schema.get("schema")
+        if isinstance(schema_payload, dict):
+            return cast(Dict[str, Any], deepcopy(schema_payload))
+        return None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """将响应格式转换为字典。
+
+        Returns:
+            Dict[str, Any]: 序列化后的响应格式字典。
         """
         if self.schema:
             return {
                 "format_type": self.format_type.value,
                 "schema": self.schema,
             }
-        else:
-            return {
-                "format_type": self.format_type.value,
-            }
+        return {
+            "format_type": self.format_type.value,
+        }

src/llm_models/payload_content/tool_option.py

@@ -1,83 +1,368 @@
+from copy import deepcopy
+from dataclasses import dataclass, field
 from enum import Enum
+from typing import Any, Dict, List, Tuple, TypeAlias, cast
 
 
-class ToolParamType(Enum):
+class ToolParamType(str, Enum):
+    """工具参数类型。"""
+
+    STRING = "string"
+    INTEGER = "integer"
+    NUMBER = "number"
+    FLOAT = "number"
+    BOOLEAN = "boolean"
+    ARRAY = "array"
+    OBJECT = "object"
+
+
+LegacyToolParameterTuple = Tuple[str, ToolParamType, str, bool, List[str] | None]
+"""旧版工具参数元组格式。"""
+
+
+def normalize_tool_param_type(raw_value: ToolParamType | str | None) -> ToolParamType:
+    """将任意输入值规范化为内部工具参数类型。
+
+    Args:
+        raw_value: 原始参数类型值。
+
+    Returns:
+        ToolParamType: 规范化后的参数类型。未知值会回退为 `STRING`。
     """
-    工具调用参数类型
+    if isinstance(raw_value, ToolParamType):
+        return raw_value
+
+    normalized_value = str(raw_value or "").strip().lower()
+    if normalized_value in {"integer", "int"}:
+        return ToolParamType.INTEGER
+    if normalized_value in {"number", "float"}:
+        return ToolParamType.NUMBER
+    if normalized_value in {"boolean", "bool"}:
+        return ToolParamType.BOOLEAN
+    if normalized_value == "array":
+        return ToolParamType.ARRAY
+    if normalized_value == "object":
+        return ToolParamType.OBJECT
+    return ToolParamType.STRING
+
+
+def _is_object_schema(schema: Dict[str, Any]) -> bool:
+    """判断输入字典是否已经是对象级 JSON Schema。
+
+    Args:
+        schema: 待判断的字典。
+
+    Returns:
+        bool: 为对象级 JSON Schema 时返回 `True`。
     """
-
-    STRING = "string"  # 字符串
-    INTEGER = "integer"  # 整型
-    FLOAT = "float"  # 浮点型
-    BOOLEAN = "bool"  # 布尔型
+    return schema.get("type") == "object" or "properties" in schema or "required" in schema
 
 
+def _build_parameters_schema_from_property_map(property_map: Dict[str, Any]) -> Dict[str, Any]:
+    """将属性映射转换为对象级 JSON Schema。
+
+    Args:
+        property_map: 仅包含属性定义的映射。
+
+    Returns:
+        Dict[str, Any]: 对象级 JSON Schema。
+    """
+    required_names: List[str] = []
+    normalized_properties: Dict[str, Any] = {}
+    for property_name, property_schema in property_map.items():
+        if not isinstance(property_schema, dict):
+            continue
+
+        property_schema_copy = deepcopy(property_schema)
+        is_required = bool(property_schema_copy.pop("required", False))
+        if is_required:
+            required_names.append(str(property_name))
+        normalized_properties[str(property_name)] = property_schema_copy
+
+    parameters_schema: Dict[str, Any] = {
+        "type": "object",
+        "properties": normalized_properties,
+    }
+    if required_names:
+        parameters_schema["required"] = required_names
+    return parameters_schema
+
+
+@dataclass(slots=True)
 class ToolParam:
-    """
-    工具调用参数
-    """
+    """工具参数定义。"""
 
-    def __init__(
-        self,
+    name: str
+    param_type: ToolParamType
+    description: str
+    required: bool
+    enum_values: List[Any] | None = None
+    items_schema: Dict[str, Any] | None = None
+    properties: Dict[str, Dict[str, Any]] | None = None
+    required_properties: List[str] = field(default_factory=list)
+    additional_properties: bool | Dict[str, Any] | None = None
+    default: Any = None
+
+    def __post_init__(self) -> None:
+        """执行参数定义的基础校验。
+
+        Raises:
+            ValueError: 当参数名称或复杂类型定义不合法时抛出。
+        """
+        if not self.name:
+            raise ValueError("参数名称不能为空")
+        if self.param_type == ToolParamType.ARRAY and self.items_schema is None:
+            raise ValueError("数组参数必须提供 items_schema")
+        if self.param_type == ToolParamType.OBJECT and self.properties is None:
+            self.properties = {}
+
+    @classmethod
+    def from_legacy_tuple(cls, parameter: LegacyToolParameterTuple) -> "ToolParam":
+        """从旧版五元组参数定义构建工具参数。
+
+        Args:
+            parameter: 旧版参数元组。
+
+        Returns:
+            ToolParam: 规范化后的工具参数对象。
+        """
+        return cls(
+            name=parameter[0],
+            param_type=parameter[1],
+            description=parameter[2],
+            required=parameter[3],
+            enum_values=parameter[4],
+        )
+
+    @classmethod
+    def from_dict(
+        cls,
         name: str,
-        param_type: ToolParamType,
-        description: str,
-        required: bool,
-        enum_values: list[str] | None = None,
-    ):
+        parameter_schema: Dict[str, Any],
+        *,
+        required: bool = False,
+    ) -> "ToolParam":
+        """从属性级 JSON Schema 或结构化参数字典构建工具参数。
+
+        Args:
+            name: 参数名称。
+            parameter_schema: 参数对应的 Schema 或结构化定义。
+            required: 参数是否必填。
+
+        Returns:
+            ToolParam: 规范化后的工具参数对象。
         """
-        初始化工具调用参数
-        （不应直接修改ToolParam类，而应使用ToolOptionBuilder类来构建对象）
-        :param name: 参数名称
-        :param param_type: 参数类型
-        :param description: 参数描述
-        :param required: 是否必填
+        raw_required_properties = parameter_schema.get("required_properties")
+        if raw_required_properties is None and isinstance(parameter_schema.get("required"), list):
+            raw_required_properties = parameter_schema.get("required")
+        return cls(
+            name=name,
+            param_type=normalize_tool_param_type(parameter_schema.get("param_type") or parameter_schema.get("type")),
+            description=str(parameter_schema.get("description", "") or ""),
+            required=required,
+            enum_values=deepcopy(parameter_schema.get("enum_values") or parameter_schema.get("enum")),
+            items_schema=deepcopy(parameter_schema.get("items_schema") or parameter_schema.get("items")),
+            properties=deepcopy(parameter_schema.get("properties")),
+            required_properties=list(raw_required_properties or []),
+            additional_properties=deepcopy(
+                parameter_schema["additional_properties"]
+                if "additional_properties" in parameter_schema
+                else parameter_schema.get("additionalProperties")
+            ),
+            default=deepcopy(parameter_schema.get("default")),
+        )
+
+    def to_json_schema(self) -> Dict[str, Any]:
+        """将参数定义转换为 JSON Schema。
+
+        Returns:
+            Dict[str, Any]: 参数对应的 JSON Schema 片段。
         """
-        self.name: str = name
-        self.param_type: ToolParamType = param_type
-        self.description: str = description
-        self.required: bool = required
-        self.enum_values: list[str] | None = enum_values
+        schema: Dict[str, Any] = {
+            "type": self.param_type.value,
+            "description": self.description,
+        }
+        if self.enum_values:
+            schema["enum"] = list(self.enum_values)
+        if self.default is not None:
+            schema["default"] = deepcopy(self.default)
+        if self.param_type == ToolParamType.ARRAY and self.items_schema is not None:
+            schema["items"] = deepcopy(self.items_schema)
+        if self.param_type == ToolParamType.OBJECT:
+            schema["properties"] = deepcopy(self.properties or {})
+            if self.required_properties:
+                schema["required"] = list(self.required_properties)
+            if self.additional_properties is not None:
+                schema["additionalProperties"] = deepcopy(self.additional_properties)
+        return schema
 
 
+@dataclass(slots=True)
 class ToolOption:
-    """
-    工具调用项
-    """
+    """工具定义。"""
 
-    def __init__(
-        self,
-        name: str,
-        description: str,
-        params: list[ToolParam] | None = None,
-    ):
+    name: str
+    description: str
+    params: List[ToolParam] | None = None
+    parameters_schema_override: Dict[str, Any] | None = None
+
+    def __post_init__(self) -> None:
+        """执行工具定义的基础校验。
+
+        Raises:
+            ValueError: 当工具名称、描述或参数 Schema 不合法时抛出。
         """
-        初始化工具调用项
-        （不应直接修改ToolOption类，而应使用ToolOptionBuilder类来构建对象）
-        :param name: 工具名称
-        :param description: 工具描述
-        :param params: 工具参数列表
+        if not self.name:
+            raise ValueError("工具名称不能为空")
+        if not self.description:
+            raise ValueError("工具描述不能为空")
+        if self.parameters_schema_override is not None:
+            schema_type = self.parameters_schema_override.get("type")
+            if schema_type != "object":
+                raise ValueError("工具参数 Schema 必须是 object 类型")
+
+    @classmethod
+    def from_definition(cls, definition: Dict[str, Any]) -> "ToolOption":
+        """从任意支持的工具定义字典构建内部工具对象。
+
+        支持以下输入形状：
+        - `{"name", "description", "parameters_schema"}`
+        - `{"name", "description", "parameters"}`
+        - OpenAI function tool：`{"type": "function", "function": {...}}`
+        - 仅属性映射的对象参数定义：`{"query": {"type": "string"}}`
+
+        Args:
+            definition: 原始工具定义字典。
+
+        Returns:
+            ToolOption: 规范化后的工具定义对象。
+
+        Raises:
+            ValueError: 当工具定义缺少必要字段时抛出。
         """
-        self.name: str = name
-        self.description: str = description
-        self.params: list[ToolParam] | None = params
+        if definition.get("type") == "function" and isinstance(definition.get("function"), dict):
+            function_definition = cast(Dict[str, Any], definition["function"])
+            return cls.from_definition(
+                {
+                    "name": function_definition.get("name", ""),
+                    "description": function_definition.get("description", ""),
+                    "parameters_schema": function_definition.get("parameters"),
+                }
+            )
+
+        name = str(definition.get("name", "") or "").strip()
+        description = str(definition.get("description", "") or "").strip()
+        if not name:
+            raise ValueError("工具定义缺少 name")
+        if not description:
+            description = f"工具 {name}"
+
+        parameters_schema = definition.get("parameters_schema")
+        if isinstance(parameters_schema, dict):
+            normalized_schema = deepcopy(parameters_schema)
+            if not _is_object_schema(normalized_schema):
+                normalized_schema = _build_parameters_schema_from_property_map(normalized_schema)
+            return cls(
+                name=name,
+                description=description,
+                params=None,
+                parameters_schema_override=normalized_schema,
+            )
+
+        raw_parameters = definition.get("parameters")
+        if isinstance(raw_parameters, dict):
+            normalized_schema = deepcopy(raw_parameters)
+            if not _is_object_schema(normalized_schema):
+                normalized_schema = _build_parameters_schema_from_property_map(normalized_schema)
+            return cls(
+                name=name,
+                description=description,
+                params=None,
+                parameters_schema_override=normalized_schema,
+            )
+
+        if isinstance(raw_parameters, list):
+            params: List[ToolParam] = []
+            for raw_parameter in raw_parameters:
+                if isinstance(raw_parameter, tuple) and len(raw_parameter) == 5:
+                    params.append(ToolParam.from_legacy_tuple(raw_parameter))
+                    continue
+                if isinstance(raw_parameter, dict):
+                    parameter_name = str(raw_parameter.get("name", "") or "").strip()
+                    if not parameter_name:
+                        continue
+                    params.append(
+                        ToolParam.from_dict(
+                            parameter_name,
+                            raw_parameter,
+                            required=bool(raw_parameter.get("required", False)),
+                        )
+                    )
+            return cls(
+                name=name,
+                description=description,
+                params=params or None,
+                parameters_schema_override=None,
+            )
+
+        return cls(name=name, description=description, params=None, parameters_schema_override=None)
+
+    @property
+    def parameters_schema(self) -> Dict[str, Any] | None:
+        """获取工具参数的对象级 JSON Schema。
+
+        Returns:
+            Dict[str, Any] | None: 工具参数 Schema。无参数工具时返回 `None`。
+        """
+        if self.parameters_schema_override is not None:
+            return deepcopy(self.parameters_schema_override)
+        if not self.params:
+            return None
+        return {
+            "type": "object",
+            "properties": {param.name: param.to_json_schema() for param in self.params},
+            "required": [param.name for param in self.params if param.required],
+        }
+
+    def to_openai_function_schema(self) -> Dict[str, Any]:
+        """转换为 OpenAI function calling 结构。
+
+        Returns:
+            Dict[str, Any]: OpenAI 兼容的工具定义。
+        """
+        function_schema: Dict[str, Any] = {
+            "name": self.name,
+            "description": self.description,
+        }
+        if self.parameters_schema is not None:
+            function_schema["parameters"] = self.parameters_schema
+        return {
+            "type": "function",
+            "function": function_schema,
+        }
 
 
 class ToolOptionBuilder:
-    """
-    工具调用项构建器
-    """
+    """工具定义构建器。"""
 
-    def __init__(self):
+    def __init__(self) -> None:
+        """初始化构建器。"""
         self.__name: str = ""
         self.__description: str = ""
-        self.__params: list[ToolParam] = []
+        self.__params: List[ToolParam] = []
+        self.__parameters_schema_override: Dict[str, Any] | None = None
 
     def set_name(self, name: str) -> "ToolOptionBuilder":
-        """
-        设置工具名称
-        :param name: 工具名称
-        :return: ToolBuilder实例
+        """设置工具名称。
+
+        Args:
+            name: 工具名称。
+
+        Returns:
+            ToolOptionBuilder: 当前构建器实例。
+
+        Raises:
+            ValueError: 当名称为空时抛出。
         """
         if not name:
             raise ValueError("工具名称不能为空")
@@ -85,35 +370,76 @@ class ToolOptionBuilder:
         return self
 
     def set_description(self, description: str) -> "ToolOptionBuilder":
-        """
-        设置工具描述
-        :param description: 工具描述
-        :return: ToolBuilder实例
+        """设置工具描述。
+
+        Args:
+            description: 工具描述。
+
+        Returns:
+            ToolOptionBuilder: 当前构建器实例。
+
+        Raises:
+            ValueError: 当描述为空时抛出。
         """
         if not description:
             raise ValueError("工具描述不能为空")
         self.__description = description
         return self
 
+    def set_parameters_schema(self, schema: Dict[str, Any]) -> "ToolOptionBuilder":
+        """直接设置完整的参数对象 Schema。
+
+        Args:
+            schema: 完整的对象级 JSON Schema。
+
+        Returns:
+            ToolOptionBuilder: 当前构建器实例。
+
+        Raises:
+            ValueError: 当 schema 不是 object 类型时抛出。
+        """
+        if schema.get("type") != "object":
+            raise ValueError("工具参数 Schema 必须是 object 类型")
+        self.__parameters_schema_override = deepcopy(schema)
+        self.__params.clear()
+        return self
+
     def add_param(
         self,
         name: str,
         param_type: ToolParamType,
         description: str,
         required: bool = False,
-        enum_values: list[str] | None = None,
+        enum_values: List[Any] | None = None,
+        *,
+        items_schema: Dict[str, Any] | None = None,
+        properties: Dict[str, Dict[str, Any]] | None = None,
+        required_properties: List[str] | None = None,
+        additional_properties: bool | Dict[str, Any] | None = None,
+        default: Any = None,
     ) -> "ToolOptionBuilder":
-        """
-        添加工具参数
-        :param name: 参数名称
-        :param param_type: 参数类型
-        :param description: 参数描述
-        :param required: 是否必填（默认为False）
-        :return: ToolBuilder实例
-        """
-        if not name or not description:
-            raise ValueError("参数名称/描述不能为空")
+        """添加一个参数定义。
 
+        Args:
+            name: 参数名称。
+            param_type: 参数类型。
+            description: 参数描述。
+            required: 参数是否必填。
+            enum_values: 可选的枚举值列表。
+            items_schema: 数组参数的元素 Schema。
+            properties: 对象参数的属性定义。
+            required_properties: 对象参数内部的必填字段。
+            additional_properties: 对象参数是否允许额外字段。
+            default: 参数默认值。
+
+        Returns:
+            ToolOptionBuilder: 当前构建器实例。
+
+        Raises:
+            ValueError: 当构建器已经设置完整 Schema 时抛出。
+        """
+        if self.__parameters_schema_override is not None:
+            raise ValueError("已设置完整参数 Schema，不能再逐项添加参数")
         self.__params.append(
             ToolParam(
                 name=name,
@@ -121,43 +447,83 @@ class ToolOptionBuilder:
                 description=description,
                 required=required,
                 enum_values=enum_values,
+                items_schema=deepcopy(items_schema),
+                properties=deepcopy(properties),
+                required_properties=list(required_properties or []),
+                additional_properties=deepcopy(additional_properties),
+                default=deepcopy(default),
             )
         )
-
         return self
 
-    def build(self):
-        """
-        构建工具调用项
-        :return: 工具调用项
-        """
-        if self.__name == "" or self.__description == "":
-            raise ValueError("工具名称/描述不能为空")
+    def build(self) -> ToolOption:
+        """构建工具定义。
 
+        Returns:
+            ToolOption: 构建完成的工具定义。
+
+        Raises:
+            ValueError: 当工具名称或描述缺失时抛出。
+        """
+        if not self.__name or not self.__description:
+            raise ValueError("工具名称和描述不能为空")
         return ToolOption(
             name=self.__name,
             description=self.__description,
-            params=None if len(self.__params) == 0 else self.__params,
+            params=None if not self.__params else list(self.__params),
+            parameters_schema_override=deepcopy(self.__parameters_schema_override),
         )
 
 
-class ToolCall:
-    """
-    来自模型反馈的工具调用
-    """
+ToolDefinitionInput: TypeAlias = ToolOption | Dict[str, Any]
+"""统一的工具定义输入类型。"""
 
-    def __init__(
-        self,
-        call_id: str,
-        func_name: str,
-        args: dict | None = None,
-    ):
+
+def normalize_tool_option(tool_definition: ToolDefinitionInput) -> ToolOption:
+    """将任意支持的工具输入规范化为内部 `ToolOption`。
+
+    Args:
+        tool_definition: 原始工具定义输入。
+
+    Returns:
+        ToolOption: 规范化后的工具定义对象。
+    """
+    if isinstance(tool_definition, ToolOption):
+        return tool_definition
+    return ToolOption.from_definition(tool_definition)
+
+
+def normalize_tool_options(
+    tool_definitions: List[ToolDefinitionInput] | None,
+) -> List[ToolOption] | None:
+    """批量规范化工具定义列表。
+
+    Args:
+        tool_definitions: 原始工具定义列表。
+
+    Returns:
+        List[ToolOption] | None: 规范化后的工具列表；输入为空时返回 `None`。
+    """
+    if not tool_definitions:
+        return None
+    return [normalize_tool_option(tool_definition) for tool_definition in tool_definitions]
+
+
+@dataclass(slots=True)
+class ToolCall:
+    """来自模型输出的工具调用。"""
+
+    call_id: str
+    func_name: str
+    args: Dict[str, Any] | None = None
+
+    def __post_init__(self) -> None:
+        """执行工具调用的基础校验。
+
+        Raises:
+            ValueError: 当工具调用标识或函数名缺失时抛出。
         """
-        初始化工具调用
-        :param call_id: 工具调用ID
-        :param func_name: 要调用的函数名称
-        :param args: 工具调用参数
-        """
-        self.call_id: str = call_id
-        self.func_name: str = func_name
-        self.args: dict | None = args
+        if not self.call_id:
+            raise ValueError("工具调用 ID 不能为空")
+        if not self.func_name:
+            raise ValueError("工具函数名称不能为空")