♻️ refactor(llm): 重构 LLM 服务架构，引入中间件与组件化适配器

- 【重构】LLM 服务核心架构：
    - 引入中间件管道，统一处理请求生命周期（重试、密钥选择、日志、网络请求）。
    - 适配器重构为组件化设计，分离配置映射、消息转换、响应解析和工具序列化逻辑。
    - 移除 `with_smart_retry` 装饰器，其功能由中间件接管。
    - 移除 `LLMToolExecutor`，工具执行逻辑集成到 `ToolInvoker`。
- 【功能】增强配置系统：
    - `LLMGenerationConfig` 采用组件化结构（Core, Reasoning, Visual, Output, Safety, ToolConfig）。
    - 新增 `GenConfigBuilder` 提供语义化配置构建方式。
    - 新增 `LLMEmbeddingConfig` 用于嵌入专用配置。
    - `CommonOverrides` 迁移并更新至新配置结构。
- 【功能】强化工具系统：
    - 引入 `ToolInvoker` 实现更灵活的工具执行，支持回调与结构化错误。
    - `function_tool` 装饰器支持动态 Pydantic 模型创建和依赖注入 (`ToolParam`, `RunContext`)。
    - 平台原生工具支持 (`GeminiCodeExecution`, `GeminiGoogleSearch`, `GeminiUrlContext`)。
- 【功能】高级生成与嵌入：
    - `generate_structured` 方法支持 In-Context Validation and Repair (IVR) 循环和 AutoCoT (思维链) 包装。
    - 新增 `embed_query` 和 `embed_documents` 便捷嵌入 API。
    - `OpenAIImageAdapter` 支持 OpenAI 兼容的图像生成。
    - `SmartAdapter` 实现模型名称智能路由。
- 【重构】消息与类型系统：
    - `LLMContentPart` 扩展支持更多模态和代码执行相关内容。
    - `LLMMessage` 和 `LLMResponse` 结构更新，支持 `content_parts` 和思维链签名。
    - 统一 `LLMErrorCode` 和用户友好错误消息，提供更详细的网络/代理错误提示。
    - `pyproject.toml` 移除 `bilireq`，新增 `json_repair`。
- 【优化】日志与调试：
    - 引入 `DebugLogOptions`，提供细粒度日志脱敏控制。
    - 增强日志净化器，处理更多敏感数据和长字符串。
- 【清理】删除废弃模块：
    - `zhenxun/services/llm/memory.py`
    - `zhenxun/services/llm/executor.py`
    - `zhenxun/services/llm/config/presets.py`
    - `zhenxun/services/llm/types/content.py`
    - `zhenxun/services/llm/types/enums.py`
    - `zhenxun/services/llm/tools/__init__.py`
    - `zhenxun/services/llm/tools/manager.py`

zhenxun/services/llm/config/__init__.py

@@ -5,13 +5,12 @@ LLM 配置模块
 """
 
 from .generation import (
+    CommonOverrides,
+    GenConfigBuilder,
+    LLMEmbeddingConfig,
     LLMGenerationConfig,
-    ModelConfigOverride,
-    apply_api_specific_mappings,
-    create_generation_config_from_kwargs,
     validate_override_params,
 )
-from .presets import CommonOverrides
 from .providers import (
     LLMConfig,
     get_gemini_safety_threshold,
@@ -23,11 +22,10 @@ from .providers import (
 
 __all__ = [
     "CommonOverrides",
+    "GenConfigBuilder",
     "LLMConfig",
+    "LLMEmbeddingConfig",
     "LLMGenerationConfig",
-    "ModelConfigOverride",
-    "apply_api_specific_mappings",
-    "create_generation_config_from_kwargs",
     "get_gemini_safety_threshold",
     "get_llm_config",
     "register_llm_configs",

zhenxun/services/llm/config/generation.py

@@ -3,209 +3,397 @@ LLM 生成配置相关类和函数
 """
 
 from collections.abc import Callable
-from typing import Any
+from enum import Enum
+from typing import Any, Literal
+from typing_extensions import Self
 
 from pydantic import BaseModel, ConfigDict, Field
 
 from zhenxun.services.log import logger
-from zhenxun.utils.pydantic_compat import model_dump
+from zhenxun.utils.pydantic_compat import model_copy, model_dump, model_validate
 
-from ..types import LLMResponse
-from ..types.enums import ResponseFormat
+from ..types import LLMResponse, ResponseFormat, StructuredOutputStrategy
 from ..types.exceptions import LLMErrorCode, LLMException
+from .providers import get_gemini_safety_threshold
 
 
-class ModelConfigOverride(BaseModel):
-    """模型配置覆盖参数"""
+class ReasoningEffort(str, Enum):
+    """推理努力程度枚举"""
+
+    LOW = "LOW"
+    MEDIUM = "MEDIUM"
+    HIGH = "HIGH"
+
+
+class ImageAspectRatio(str, Enum):
+    """图像宽高比枚举"""
+
+    SQUARE = "1:1"
+    LANDSCAPE_16_9 = "16:9"
+    PORTRAIT_9_16 = "9:16"
+    LANDSCAPE_4_3 = "4:3"
+    PORTRAIT_3_4 = "3:4"
+    LANDSCAPE_3_2 = "3:2"
+    PORTRAIT_2_3 = "2:3"
+
+
+class ImageResolution(str, Enum):
+    """图像分辨率/质量枚举"""
+
+    STANDARD = "STANDARD"
+    HD = "HD"
+
+
+class CoreConfig(BaseModel):
+    """核心生成参数"""
 
     temperature: float | None = Field(
         default=None, ge=0.0, le=2.0, description="生成温度"
     )
+    """生成温度"""
     max_tokens: int | None = Field(default=None, gt=0, description="最大输出token数")
+    """最大输出token数"""
     top_p: float | None = Field(default=None, ge=0.0, le=1.0, description="核采样参数")
+    """核采样参数"""
     top_k: int | None = Field(default=None, gt=0, description="Top-K采样参数")
+    """Top-K采样参数"""
     frequency_penalty: float | None = Field(
         default=None, ge=-2.0, le=2.0, description="频率惩罚"
     )
+    """频率惩罚"""
     presence_penalty: float | None = Field(
         default=None, ge=-2.0, le=2.0, description="存在惩罚"
     )
+    """存在惩罚"""
     repetition_penalty: float | None = Field(
         default=None, ge=0.0, le=2.0, description="重复惩罚"
     )
-
+    """重复惩罚"""
     stop: list[str] | str | None = Field(default=None, description="停止序列")
+    """停止序列"""
+
+
+class ReasoningConfig(BaseModel):
+    """推理能力配置"""
+
+    effort: ReasoningEffort | None = Field(
+        default=None, description="推理努力程度 (适用于 O1, Gemini 3)"
+    )
+    """推理努力程度 (适用于 O1, Gemini 3)"""
+    budget_tokens: int | None = Field(
+        default=None, description="具体的思考 Token 预算 (适用于 Gemini 2.5)"
+    )
+    """具体的思考 Token 预算 (适用于 Gemini 2.5)"""
+    show_thoughts: bool | None = Field(
+        default=None, description="是否在响应中显式包含思维链内容"
+    )
+    """是否在响应中显式包含思维链内容"""
+
+
+class VisualConfig(BaseModel):
+    """视觉生成配置"""
+
+    aspect_ratio: ImageAspectRatio | str | None = Field(
+        default=None, description="宽高比"
+    )
+    """宽高比"""
+    resolution: ImageResolution | str | None = Field(
+        default=None, description="生成质量/分辨率"
+    )
+    """生成质量/分辨率"""
+    media_resolution: str | None = Field(
+        default=None,
+        description="输入媒体的解析度 (Gemini 3+): 'LOW', 'MEDIUM', 'HIGH'",
+    )
+    """输入媒体的解析度 (Gemini 3+): 'LOW', 'MEDIUM', 'HIGH'"""
+    style: str | None = Field(
+        default=None, description="图像风格 (如 DALL-E 3 vivid/natural)"
+    )
+    """图像风格 (如 DALL-E 3 vivid/natural)"""
+
+
+class OutputConfig(BaseModel):
+    """输出格式控制"""
 
     response_format: ResponseFormat | dict[str, Any] | None = Field(
         default=None, description="期望的响应格式"
     )
+    """期望的响应格式"""
     response_mime_type: str | None = Field(
         default=None, description="响应MIME类型（Gemini专用）"
     )
+    """响应MIME类型（Gemini专用）"""
     response_schema: dict[str, Any] | None = Field(
         default=None, description="JSON响应模式"
     )
-    thinking_budget: float | None = Field(
-        default=None, ge=0.0, le=1.0, description="思考预算"
-    )
-    include_thoughts: bool | None = Field(
-        default=None, description="是否在响应中包含思维过程（Gemini专用）"
-    )
-    safety_settings: dict[str, str] | None = Field(default=None, description="安全设置")
+    """JSON响应模式"""
     response_modalities: list[str] | None = Field(
-        default=None, description="响应模态类型"
+        default=None, description="响应模态类型 (TEXT, IMAGE, AUDIO)"
     )
+    """响应模态类型 (TEXT, IMAGE, AUDIO)"""
+    structured_output_strategy: StructuredOutputStrategy | str | None = Field(
+        default=None, description="结构化输出策略 (NATIVE/TOOL_CALL/PROMPT)"
+    )
+    """结构化输出策略 (NATIVE/TOOL_CALL/PROMPT)"""
 
-    enable_code_execution: bool | None = Field(
-        default=None, description="是否启用代码执行"
+
+class SafetyConfig(BaseModel):
+    """安全设置"""
+
+    safety_settings: dict[str, str] | None = Field(default=None, description="安全设置")
+    """安全设置"""
+
+
+class ToolConfig(BaseModel):
+    """工具调用控制配置"""
+
+    mode: Literal["AUTO", "ANY", "NONE"] = Field(
+        default="AUTO",
+        description="工具调用模式: AUTO(自动), ANY(强制), NONE(禁用)",
     )
-    enable_grounding: bool | None = Field(
-        default=None, description="是否启用信息来源关联"
+    """工具调用模式: AUTO(自动), ANY(强制), NONE(禁用)"""
+    allowed_function_names: list[str] | None = Field(
+        default=None,
+        description="当 mode 为 ANY 时，允许调用的函数名称白名单",
     )
+    """当 mode 为 ANY 时，允许调用的函数名称白名单"""
+
+
+class LLMGenerationConfig(BaseModel):
+    """
+    LLM 生成配置
+    采用组件化设计，不再扁平化参数。
+    """
+
+    core: CoreConfig | None = Field(default=None, description="基础生成参数")
+    """基础生成参数"""
+    reasoning: ReasoningConfig | None = Field(default=None, description="推理能力配置")
+    """推理能力配置"""
+    visual: VisualConfig | None = Field(default=None, description="视觉生成配置")
+    """视觉生成配置"""
+    output: OutputConfig | None = Field(default=None, description="输出格式配置")
+    """输出格式配置"""
+    safety: SafetyConfig | None = Field(default=None, description="安全配置")
+    """安全配置"""
+    tool_config: ToolConfig | None = Field(default=None, description="工具调用策略配置")
+    """工具调用策略配置"""
+
     enable_caching: bool | None = Field(default=None, description="是否启用响应缓存")
+    """是否启用响应缓存"""
 
     custom_params: dict[str, Any] | None = Field(default=None, description="自定义参数")
+    """自定义参数"""
 
     validation_policy: dict[str, Any] | None = Field(
         default=None, description="声明式的响应验证策略 (例如: {'require_image': True})"
     )
+    """声明式的响应验证策略 (例如: {'require_image': True})"""
     response_validator: Callable[[LLMResponse], None] | None = Field(
-        default=None, description="一个高级回调函数，用于验证响应，验证失败时应抛出异常"
+        default=None,
+        description="一个高级回调函数，用于验证响应，验证失败时应抛出异常",
     )
+    """一个高级回调函数，用于验证响应，验证失败时应抛出异常"""
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
+    @classmethod
+    def builder(cls) -> "GenConfigBuilder":
+        """创建一个新的配置构建器"""
+        return GenConfigBuilder()
+
     def to_dict(self) -> dict[str, Any]:
-        """转换为字典，排除None值"""
+        """
+        转换为字典，排除None值。
+        注意：这会返回嵌套结构的字典。适配器需要处理这种嵌套。
+        """
+        return model_dump(self, exclude_none=True)
 
-        model_data = model_dump(self, exclude_none=True)
+    def merge_with(self, other: "LLMGenerationConfig | None") -> "LLMGenerationConfig":
+        """
+        与另一个配置对象进行深度合并。
+        other 中的非 None 字段会覆盖当前配置中的对应字段。
+        返回一个新的配置对象，原对象不变。
+        """
+        if not other:
+            return model_copy(self, deep=True)
 
-        result = {}
-        for key, value in model_data.items():
-            if key == "custom_params" and isinstance(value, dict):
-                result.update(value)
-            else:
-                result[key] = value
+        new_config = model_copy(self, deep=True)
 
-        return result
+        def _merge_component(base_comp, override_comp, comp_cls):
+            if override_comp is None:
+                return base_comp
+            if base_comp is None:
+                return override_comp
+            updates = model_dump(override_comp, exclude_none=True)
+            return model_copy(base_comp, update=updates)
 
-    def merge_with_base_config(
+        new_config.core = _merge_component(new_config.core, other.core, CoreConfig)
+        new_config.reasoning = _merge_component(
+            new_config.reasoning, other.reasoning, ReasoningConfig
+        )
+        new_config.visual = _merge_component(
+            new_config.visual, other.visual, VisualConfig
+        )
+        new_config.output = _merge_component(
+            new_config.output, other.output, OutputConfig
+        )
+        new_config.safety = _merge_component(
+            new_config.safety, other.safety, SafetyConfig
+        )
+        new_config.tool_config = _merge_component(
+            new_config.tool_config, other.tool_config, ToolConfig
+        )
+
+        if other.enable_caching is not None:
+            new_config.enable_caching = other.enable_caching
+
+        if other.custom_params:
+            if new_config.custom_params is None:
+                new_config.custom_params = {}
+            new_config.custom_params.update(other.custom_params)
+
+        if other.validation_policy:
+            if new_config.validation_policy is None:
+                new_config.validation_policy = {}
+            new_config.validation_policy.update(other.validation_policy)
+
+        if other.response_validator:
+            new_config.response_validator = other.response_validator
+
+        return new_config
+
+
+class LLMEmbeddingConfig(BaseModel):
+    """Embedding 专用配置"""
+
+    task_type: str | None = Field(default=None, description="任务类型 (Gemini/Jina)")
+    """任务类型 (Gemini/Jina)"""
+    output_dimensionality: int | None = Field(
+        default=None, description="输出维度/压缩维度 (Gemini/Jina/OpenAI)"
+    )
+    """输出维度/压缩维度 (Gemini/Jina/OpenAI)"""
+    title: str | None = Field(
+        default=None, description="仅用于 Gemini RETRIEVAL_DOCUMENT 任务的标题"
+    )
+    """仅用于 Gemini RETRIEVAL_DOCUMENT 任务的标题"""
+    encoding_format: str | None = Field(
+        default="float", description="编码格式 (float/base64)"
+    )
+    """编码格式 (float/base64)"""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+class GenConfigBuilder:
+    """
+    LLM 生成配置的语义化构建器。
+    设计原则：高频业务场景优先，低频参数命名空间化。
+    """
+
+    def __init__(self):
+        self._config = LLMGenerationConfig()
+
+    def _ensure_core(self) -> CoreConfig:
+        if self._config.core is None:
+            self._config.core = CoreConfig()
+        return self._config.core
+
+    def _ensure_output(self) -> OutputConfig:
+        if self._config.output is None:
+            self._config.output = OutputConfig()
+        return self._config.output
+
+    def _ensure_reasoning(self) -> ReasoningConfig:
+        if self._config.reasoning is None:
+            self._config.reasoning = ReasoningConfig()
+        return self._config.reasoning
+
+    def as_json(self, schema: dict[str, Any] | None = None) -> Self:
+        """
+        [高频] 强制模型输出 JSON 格式。
+        """
+        out = self._ensure_output()
+        out.response_format = ResponseFormat.JSON
+        if schema:
+            out.response_schema = schema
+        return self
+
+    def enable_thinking(
+        self, budget_tokens: int = -1, show_thoughts: bool = False
+    ) -> Self:
+        """
+        [高频] 启用模型的思考/推理能力 (如 Gemini 2.0 Flash Thinking, DeepSeek R1)。
+        """
+        reasoning = self._ensure_reasoning()
+        reasoning.budget_tokens = budget_tokens
+        reasoning.show_thoughts = show_thoughts
+        return self
+
+    def config_core(
         self,
-        base_temperature: float | None = None,
-        base_max_tokens: int | None = None,
-    ) -> dict[str, Any]:
-        """与基础配置合并，覆盖参数优先"""
-        merged = {}
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        top_p: float | None = None,
+        top_k: int | None = None,
+        stop: list[str] | str | None = None,
+        frequency_penalty: float | None = None,
+        presence_penalty: float | None = None,
+    ) -> Self:
+        """
+        [低频] 配置核心生成参数。
+        """
+        core = self._ensure_core()
+        if temperature is not None:
+            core.temperature = temperature
+        if max_tokens is not None:
+            core.max_tokens = max_tokens
+        if top_p is not None:
+            core.top_p = top_p
+        if top_k is not None:
+            core.top_k = top_k
+        if stop is not None:
+            core.stop = stop
+        if frequency_penalty is not None:
+            core.frequency_penalty = frequency_penalty
+        if presence_penalty is not None:
+            core.presence_penalty = presence_penalty
+        return self
 
-        if base_temperature is not None:
-            merged["temperature"] = base_temperature
-        if base_max_tokens is not None:
-            merged["max_tokens"] = base_max_tokens
+    def config_safety(self, settings: dict[str, str]) -> Self:
+        """
+        [低频] 配置安全过滤设置。
+        """
+        if self._config.safety is None:
+            self._config.safety = SafetyConfig()
+        self._config.safety.safety_settings = settings
+        return self
 
-        override_dict = self.to_dict()
-        merged.update(override_dict)
+    def config_visual(
+        self,
+        aspect_ratio: ImageAspectRatio | str | None = None,
+        resolution: ImageResolution | str | None = None,
+    ) -> Self:
+        """
+        [低频] 配置视觉生成参数 (DALL-E 3 / Gemini Imagen)。
+        """
+        if self._config.visual is None:
+            self._config.visual = VisualConfig()
+        if aspect_ratio:
+            self._config.visual.aspect_ratio = aspect_ratio
+        if resolution:
+            self._config.visual.resolution = resolution
+        return self
 
-        return merged
+    def set_custom_param(self, key: str, value: Any) -> Self:
+        """设置特定于厂商的自定义参数"""
+        if self._config.custom_params is None:
+            self._config.custom_params = {}
+        self._config.custom_params[key] = value
+        return self
 
-
-class LLMGenerationConfig(ModelConfigOverride):
-    """LLM 生成配置，继承模型配置覆盖参数"""
-
-    def to_api_params(self, api_type: str, model_name: str) -> dict[str, Any]:
-        """转换为API参数，支持不同API类型的参数名映射"""
-        _ = model_name
-        params = {}
-
-        if self.temperature is not None:
-            params["temperature"] = self.temperature
-
-        if self.max_tokens is not None:
-            if api_type == "gemini":
-                params["maxOutputTokens"] = self.max_tokens
-            else:
-                params["max_tokens"] = self.max_tokens
-
-        if api_type == "gemini":
-            if self.top_k is not None:
-                params["topK"] = self.top_k
-            if self.top_p is not None:
-                params["topP"] = self.top_p
-        else:
-            if self.top_k is not None:
-                params["top_k"] = self.top_k
-            if self.top_p is not None:
-                params["top_p"] = self.top_p
-
-        if api_type in ["openai", "deepseek", "zhipu", "general_openai_compat"]:
-            if self.frequency_penalty is not None:
-                params["frequency_penalty"] = self.frequency_penalty
-            if self.presence_penalty is not None:
-                params["presence_penalty"] = self.presence_penalty
-
-            if self.repetition_penalty is not None:
-                if api_type == "openai":
-                    logger.warning("OpenAI官方API不支持repetition_penalty参数，已忽略")
-                else:
-                    params["repetition_penalty"] = self.repetition_penalty
-
-        if self.response_format is not None:
-            if isinstance(self.response_format, dict):
-                if api_type in ["openai", "zhipu", "deepseek", "general_openai_compat"]:
-                    params["response_format"] = self.response_format
-                    logger.debug(
-                        f"为 {api_type} 使用自定义 response_format: "
-                        f"{self.response_format}"
-                    )
-            elif self.response_format == ResponseFormat.JSON:
-                if api_type in ["openai", "zhipu", "deepseek", "general_openai_compat"]:
-                    params["response_format"] = {"type": "json_object"}
-                    logger.debug(f"为 {api_type} 启用 JSON 对象输出模式")
-                elif api_type == "gemini":
-                    params["responseMimeType"] = "application/json"
-                    if self.response_schema:
-                        params["responseSchema"] = self.response_schema
-                    logger.debug(f"为 {api_type} 启用 JSON MIME 类型输出模式")
-
-        if self.custom_params:
-            custom_mapped = apply_api_specific_mappings(self.custom_params, api_type)
-            params.update(custom_mapped)
-
-        if api_type == "gemini":
-            if (
-                self.response_format != ResponseFormat.JSON
-                and self.response_mime_type is not None
-            ):
-                params["responseMimeType"] = self.response_mime_type
-                logger.debug(
-                    f"使用显式设置的 responseMimeType: {self.response_mime_type}"
-                )
-
-            if self.response_schema is not None and "responseSchema" not in params:
-                params["responseSchema"] = self.response_schema
-
-            if self.thinking_budget is not None or self.include_thoughts is not None:
-                thinking_config = params.setdefault("thinkingConfig", {})
-
-                if self.thinking_budget is not None:
-                    max_budget = 24576
-                    budget_value = int(self.thinking_budget * max_budget)
-                    thinking_config["thinkingBudget"] = budget_value
-                    logger.debug(
-                        f"已将 thinking_budget (float: {self.thinking_budget}) "
-                        f"转换为 Gemini API 的整数格式: {budget_value}"
-                    )
-
-                if self.include_thoughts is not None:
-                    thinking_config["includeThoughts"] = self.include_thoughts
-                    logger.debug(f"已设置 includeThoughts: {self.include_thoughts}")
-
-            if self.safety_settings is not None:
-                params["safetySettings"] = self.safety_settings
-            if self.response_modalities is not None:
-                params["responseModalities"] = self.response_modalities
-
-        logger.debug(f"为{api_type}转换配置参数: {len(params)}个参数")
-        return params
+    def build(self) -> LLMGenerationConfig:
+        """构建最终的配置对象"""
+        return self._config
 
 
 def validate_override_params(
@@ -215,12 +403,12 @@ def validate_override_params(
     if override_config is None:
         return LLMGenerationConfig()
 
+    if isinstance(override_config, LLMGenerationConfig):
+        return override_config
+
     if isinstance(override_config, dict):
         try:
-            filtered_config = {
-                k: v for k, v in override_config.items() if v is not None
-            }
-            return LLMGenerationConfig(**filtered_config)
+            return model_validate(LLMGenerationConfig, override_config)
         except Exception as e:
             logger.warning(f"覆盖配置参数验证失败: {e}")
             raise LLMException(
@@ -229,56 +417,107 @@ def validate_override_params(
                 cause=e,
             )
 
-    return override_config
+    raise LLMException(
+        f"不支持的配置类型: {type(override_config)}",
+        code=LLMErrorCode.CONFIGURATION_ERROR,
+    )
 
 
-def apply_api_specific_mappings(
-    params: dict[str, Any], api_type: str
-) -> dict[str, Any]:
-    """应用API特定的参数映射"""
-    mapped_params = params.copy()
+class CommonOverrides:
+    """常用的配置覆盖预设"""
 
-    if api_type == "gemini":
-        if "max_tokens" in mapped_params:
-            mapped_params["maxOutputTokens"] = mapped_params.pop("max_tokens")
-        if "top_k" in mapped_params:
-            mapped_params["topK"] = mapped_params.pop("top_k")
-        if "top_p" in mapped_params:
-            mapped_params["topP"] = mapped_params.pop("top_p")
+    @staticmethod
+    def gemini_json() -> LLMGenerationConfig:
+        """Gemini JSON模式：强制JSON输出"""
+        return LLMGenerationConfig(
+            core=CoreConfig(),
+            output=OutputConfig(
+                response_format=ResponseFormat.JSON,
+                response_mime_type="application/json",
+            ),
+        )
 
-        unsupported = ["frequency_penalty", "presence_penalty", "repetition_penalty"]
-        for param in unsupported:
-            if param in mapped_params:
-                logger.warning(f"Gemini 原生API不支持参数 '{param}'，已忽略")
-                mapped_params.pop(param)
+    @staticmethod
+    def gemini_2_5_thinking(tokens: int = -1) -> LLMGenerationConfig:
+        """Gemini 2.5 思考模式：默认 -1 (动态思考)，0 为禁用，>=1024 为固定预算"""
+        return LLMGenerationConfig(
+            core=CoreConfig(temperature=1.0),
+            reasoning=ReasoningConfig(budget_tokens=tokens, show_thoughts=True),
+        )
 
-    elif api_type in ["openai", "deepseek", "zhipu", "general_openai_compat"]:
-        if "repetition_penalty" in mapped_params and api_type == "openai":
-            logger.warning("OpenAI官方API不支持repetition_penalty参数，已忽略")
-            mapped_params.pop("repetition_penalty")
+    @staticmethod
+    def gemini_3_thinking(level: str = "HIGH") -> LLMGenerationConfig:
+        """Gemini 3 深度思考模式：使用思考等级"""
+        try:
+            effort = ReasoningEffort(level.upper())
+        except ValueError:
+            effort = ReasoningEffort.HIGH
 
-        if "stop" in mapped_params:
-            stop_value = mapped_params["stop"]
-            if isinstance(stop_value, str):
-                mapped_params["stop"] = [stop_value]
+        return LLMGenerationConfig(
+            core=CoreConfig(),
+            reasoning=ReasoningConfig(effort=effort, show_thoughts=True),
+        )
 
-    return mapped_params
+    @staticmethod
+    def gemini_structured(schema: dict[str, Any]) -> LLMGenerationConfig:
+        """Gemini 结构化输出：自定义JSON模式"""
+        return LLMGenerationConfig(
+            core=CoreConfig(),
+            output=OutputConfig(
+                response_mime_type="application/json", response_schema=schema
+            ),
+        )
 
+    @staticmethod
+    def gemini_safe() -> LLMGenerationConfig:
+        """Gemini 安全模式：使用配置的安全设置"""
+        threshold = get_gemini_safety_threshold()
+        return LLMGenerationConfig(
+            core=CoreConfig(),
+            safety=SafetyConfig(
+                safety_settings={
+                    "HARM_CATEGORY_HARASSMENT": threshold,
+                    "HARM_CATEGORY_HATE_SPEECH": threshold,
+                    "HARM_CATEGORY_SEXUALLY_EXPLICIT": threshold,
+                    "HARM_CATEGORY_DANGEROUS_CONTENT": threshold,
+                }
+            ),
+        )
 
-def create_generation_config_from_kwargs(**kwargs) -> LLMGenerationConfig:
-    """从关键字参数创建生成配置"""
-    model_fields = getattr(LLMGenerationConfig, "model_fields", {})
-    known_fields = set(model_fields.keys())
-    known_params = {}
-    custom_params = {}
+    @staticmethod
+    def gemini_code_execution() -> LLMGenerationConfig:
+        """Gemini 代码执行模式：启用代码执行功能"""
+        return LLMGenerationConfig(
+            core=CoreConfig(),
+            custom_params={"code_execution_timeout": 30},
+        )
 
-    for key, value in kwargs.items():
-        if key in known_fields:
-            known_params[key] = value
-        else:
-            custom_params[key] = value
+    @staticmethod
+    def gemini_grounding() -> LLMGenerationConfig:
+        """Gemini 信息来源关联模式：启用Google搜索"""
+        return LLMGenerationConfig(
+            core=CoreConfig(),
+            custom_params={
+                "grounding_config": {"dynamicRetrievalConfig": {"mode": "MODE_DYNAMIC"}}
+            },
+        )
 
-    if custom_params:
-        known_params["custom_params"] = custom_params
+    @staticmethod
+    def gemini_nano_banana(aspect_ratio: str = "16:9") -> LLMGenerationConfig:
+        """Gemini Nano Banana Pro：自定义比例生图"""
+        try:
+            ar = ImageAspectRatio(aspect_ratio)
+        except ValueError:
+            ar = ImageAspectRatio.LANDSCAPE_16_9
 
-    return LLMGenerationConfig(**known_params)
+        return LLMGenerationConfig(
+            core=CoreConfig(),
+            visual=VisualConfig(aspect_ratio=ar),
+        )
+
+    @staticmethod
+    def gemini_high_res() -> LLMGenerationConfig:
+        """Gemini 3: 强制使用高解析度处理输入媒体"""
+        return LLMGenerationConfig(
+            visual=VisualConfig(media_resolution="HIGH", resolution=ImageResolution.HD)
+        )

zhenxun/services/llm/config/presets.py

@@ -1,172 +0,0 @@
-"""
-LLM 预设配置
-
-提供常用的配置预设，特别是针对 Gemini 的高级功能。
-"""
-
-from typing import Any
-
-from .generation import LLMGenerationConfig
-
-
-class CommonOverrides:
-    """常用的配置覆盖预设"""
-
-    @staticmethod
-    def creative() -> LLMGenerationConfig:
-        """创意模式：高温度，鼓励创新"""
-        return LLMGenerationConfig(temperature=0.9, top_p=0.95, frequency_penalty=0.1)
-
-    @staticmethod
-    def precise() -> LLMGenerationConfig:
-        """精确模式：低温度，确定性输出"""
-        return LLMGenerationConfig(temperature=0.1, top_p=0.9, frequency_penalty=0.0)
-
-    @staticmethod
-    def balanced() -> LLMGenerationConfig:
-        """平衡模式：中等温度"""
-        return LLMGenerationConfig(temperature=0.5, top_p=0.9, frequency_penalty=0.0)
-
-    @staticmethod
-    def concise(max_tokens: int = 100) -> LLMGenerationConfig:
-        """简洁模式：限制输出长度"""
-        return LLMGenerationConfig(
-            temperature=0.3,
-            max_tokens=max_tokens,
-            stop=["\n\n", "。", "！", "？"],
-        )
-
-    @staticmethod
-    def detailed(max_tokens: int = 2000) -> LLMGenerationConfig:
-        """详细模式：鼓励详细输出"""
-        return LLMGenerationConfig(
-            temperature=0.7, max_tokens=max_tokens, frequency_penalty=-0.1
-        )
-
-    @staticmethod
-    def gemini_json() -> LLMGenerationConfig:
-        """Gemini JSON模式：强制JSON输出"""
-        return LLMGenerationConfig(
-            temperature=0.3, response_mime_type="application/json"
-        )
-
-    @staticmethod
-    def gemini_thinking(budget: float = 0.8) -> LLMGenerationConfig:
-        """Gemini 思考模式：使用思考预算"""
-        return LLMGenerationConfig(temperature=0.7, thinking_budget=budget)
-
-    @staticmethod
-    def gemini_creative() -> LLMGenerationConfig:
-        """Gemini 创意模式：高温度创意输出"""
-        return LLMGenerationConfig(temperature=0.9, top_p=0.95)
-
-    @staticmethod
-    def gemini_structured(schema: dict[str, Any]) -> LLMGenerationConfig:
-        """Gemini 结构化输出：自定义JSON模式"""
-        return LLMGenerationConfig(
-            temperature=0.3,
-            response_mime_type="application/json",
-            response_schema=schema,
-        )
-
-    @staticmethod
-    def gemini_safe() -> LLMGenerationConfig:
-        """Gemini 安全模式：使用配置的安全设置"""
-        from .providers import get_gemini_safety_threshold
-
-        threshold = get_gemini_safety_threshold()
-        return LLMGenerationConfig(
-            temperature=0.5,
-            safety_settings={
-                "HARM_CATEGORY_HARASSMENT": threshold,
-                "HARM_CATEGORY_HATE_SPEECH": threshold,
-                "HARM_CATEGORY_SEXUALLY_EXPLICIT": threshold,
-                "HARM_CATEGORY_DANGEROUS_CONTENT": threshold,
-            },
-        )
-
-    @staticmethod
-    def gemini_multimodal() -> LLMGenerationConfig:
-        """Gemini 多模态模式：优化多模态处理"""
-        return LLMGenerationConfig(temperature=0.6, max_tokens=2048, top_p=0.8)
-
-    @staticmethod
-    def gemini_code_execution() -> LLMGenerationConfig:
-        """Gemini 代码执行模式：启用代码执行功能"""
-        return LLMGenerationConfig(
-            temperature=0.3,
-            max_tokens=4096,
-            enable_code_execution=True,
-            custom_params={"code_execution_timeout": 30},
-        )
-
-    @staticmethod
-    def gemini_grounding() -> LLMGenerationConfig:
-        """Gemini 信息来源关联模式：启用Google搜索"""
-        return LLMGenerationConfig(
-            temperature=0.5,
-            max_tokens=4096,
-            enable_grounding=True,
-            custom_params={
-                "grounding_config": {"dynamicRetrievalConfig": {"mode": "MODE_DYNAMIC"}}
-            },
-        )
-
-    @staticmethod
-    def gemini_cached() -> LLMGenerationConfig:
-        """Gemini 缓存模式：启用响应缓存"""
-        return LLMGenerationConfig(
-            temperature=0.3,
-            max_tokens=2048,
-            enable_caching=True,
-        )
-
-    @staticmethod
-    def gemini_advanced() -> LLMGenerationConfig:
-        """Gemini 高级模式：启用所有高级功能"""
-        return LLMGenerationConfig(
-            temperature=0.5,
-            max_tokens=4096,
-            enable_code_execution=True,
-            enable_grounding=True,
-            enable_caching=True,
-            custom_params={
-                "code_execution_timeout": 30,
-                "grounding_config": {
-                    "dynamicRetrievalConfig": {"mode": "MODE_DYNAMIC"}
-                },
-            },
-        )
-
-    @staticmethod
-    def gemini_research() -> LLMGenerationConfig:
-        """Gemini 研究模式：思考+搜索+结构化输出"""
-        return LLMGenerationConfig(
-            temperature=0.6,
-            max_tokens=4096,
-            thinking_budget=0.8,
-            enable_grounding=True,
-            response_mime_type="application/json",
-            custom_params={
-                "grounding_config": {"dynamicRetrievalConfig": {"mode": "MODE_DYNAMIC"}}
-            },
-        )
-
-    @staticmethod
-    def gemini_analysis() -> LLMGenerationConfig:
-        """Gemini 分析模式：深度思考+详细输出"""
-        return LLMGenerationConfig(
-            temperature=0.4,
-            max_tokens=6000,
-            thinking_budget=0.9,
-            top_p=0.8,
-        )
-
-    @staticmethod
-    def gemini_fast_response() -> LLMGenerationConfig:
-        """Gemini 快速响应模式：低延迟+简洁输出"""
-        return LLMGenerationConfig(
-            temperature=0.3,
-            max_tokens=512,
-            top_p=0.8,
-        )

zhenxun/services/llm/config/providers.py

@@ -13,6 +13,7 @@ from zhenxun.configs.config import Config
 from zhenxun.configs.utils import parse_as
 from zhenxun.services.log import logger
 from zhenxun.utils.manager.priority_manager import PriorityLifecycle
+from zhenxun.utils.pydantic_compat import model_dump
 
 from ..core import key_store
 from ..tools import tool_provider_manager
@@ -22,6 +23,39 @@ AI_CONFIG_GROUP = "AI"
 PROVIDERS_CONFIG_KEY = "PROVIDERS"
 
 
+class DebugLogOptions(BaseModel):
+    """调试日志细粒度控制"""
+
+    show_tools: bool = Field(
+        default=True, description="是否在日志中显示工具定义(JSON Schema)"
+    )
+    show_schema: bool = Field(
+        default=True, description="是否在日志中显示结构化输出Schema(response_format)"
+    )
+    show_safety: bool = Field(
+        default=True, description="是否在日志中显示安全设置(safetySettings)"
+    )
+
+    def __bool__(self) -> bool:
+        """支持 bool(debug_options) 的语法，方便兼容旧逻辑。"""
+        return self.show_tools or self.show_schema or self.show_safety
+
+
+class ClientSettings(BaseModel):
+    """LLM 客户端通用设置"""
+
+    timeout: int = Field(default=300, description="API请求超时时间（秒）")
+    max_retries: int = Field(default=3, description="请求失败时的最大重试次数")
+    retry_delay: int = Field(default=2, description="请求重试的基础延迟时间（秒）")
+    structured_retries: int = Field(
+        default=2, description="结构化生成校验失败时的最大重试次数 (IVR)"
+    )
+    proxy: str | None = Field(
+        default=None,
+        description="网络代理，例如 http://127.0.0.1:7890",
+    )
+
+
 class LLMConfig(BaseModel):
     """LLM 服务配置类"""
 
@@ -29,20 +63,16 @@ class LLMConfig(BaseModel):
         default=None,
         description="LLM服务全局默认使用的模型名称 (格式: ProviderName/ModelName)",
     )
-    proxy: str | None = Field(
-        default=None,
-        description="LLM服务请求使用的网络代理，例如 http://127.0.0.1:7890",
-    )
-    timeout: int = Field(default=180, description="LLM服务API请求超时时间（秒）")
-    max_retries_llm: int = Field(
-        default=3, description="LLM服务请求失败时的最大重试次数"
-    )
-    retry_delay_llm: int = Field(
-        default=2, description="LLM服务请求重试的基础延迟时间（秒）"
+    client_settings: ClientSettings = Field(
+        default_factory=ClientSettings, description="客户端连接与重试配置"
     )
     providers: list[ProviderConfig] = Field(
         default_factory=list, description="配置多个 AI 服务提供商及其模型信息"
     )
+    debug_log: DebugLogOptions | bool = Field(
+        default_factory=DebugLogOptions,
+        description="LLM请求日志详情开关。支持 bool (全开/全关) 或 dict (细粒度控制)。",
+    )
 
     def get_provider_by_name(self, name: str) -> ProviderConfig | None:
         """根据名称获取提供商配置
@@ -226,36 +256,29 @@ def register_llm_configs():
     )
     Config.add_plugin_config(
         AI_CONFIG_GROUP,
-        "proxy",
-        llm_config.proxy,
-        help="LLM服务请求使用的网络代理，例如 http://127.0.0.1:7890",
-        type=str,
+        "client_settings",
+        model_dump(llm_config.client_settings),
+        help=(
+            "LLM客户端高级设置。\n"
+            "包含: timeout(超时秒数), max_retries(重试次数), "
+            "retry_delay(重试延迟), structured_retries(结构化生成重试), proxy(代理)"
+        ),
+        type=dict,
     )
     Config.add_plugin_config(
         AI_CONFIG_GROUP,
-        "timeout",
-        llm_config.timeout,
-        help="LLM服务API请求超时时间（秒）",
-        type=int,
-    )
-    Config.add_plugin_config(
-        AI_CONFIG_GROUP,
-        "max_retries_llm",
-        llm_config.max_retries_llm,
-        help="LLM服务请求失败时的最大重试次数",
-        type=int,
-    )
-    Config.add_plugin_config(
-        AI_CONFIG_GROUP,
-        "retry_delay_llm",
-        llm_config.retry_delay_llm,
-        help="LLM服务请求重试的基础延迟时间（秒）",
-        type=int,
+        "debug_log",
+        {"show_tools": True, "show_schema": True, "show_safety": True},
+        help=(
+            "LLM日志详情开关。示例: {'show_tools': True, 'show_schema': False, "
+            "'show_safety': False}"
+        ),
+        type=dict,
     )
     Config.add_plugin_config(
         AI_CONFIG_GROUP,
         "gemini_safety_threshold",
-        "BLOCK_MEDIUM_AND_ABOVE",
+        "BLOCK_NONE",
         help=(
             "Gemini 安全过滤阈值 "
             "(BLOCK_LOW_AND_ABOVE: 阻止低级别及以上, "
@@ -270,7 +293,20 @@ def register_llm_configs():
         AI_CONFIG_GROUP,
         PROVIDERS_CONFIG_KEY,
         get_default_providers(),
-        help="配置多个 AI 服务提供商及其模型信息",
+        help=(
+            "配置多个 AI 服务提供商及其模型信息。\n"
+            "注意：可以在特定模型配置下添加 'api_type' 以覆盖提供商的全局设置。\n"
+            "支持的 api_type 包括:\n"
+            "- 'openai': 标准 OpenAI 格式 (DeepSeek, SiliconFlow, Moonshot 等)\n"
+            "- 'gemini': Google Gemini API\n"
+            "- 'zhipu': 智谱 AI (GLM)\n"
+            "- 'ark': 字节跳动火山引擎 (Doubao)\n"
+            "- 'openrouter': OpenRouter 聚合平台\n"
+            "- 'openai_image': OpenAI 兼容的图像生成接口 (DALL-E)\n"
+            "- 'openai_responses': 支持新版 responses 格式的 OpenAI 兼容接口\n"
+            "- 'smart': 智能路由模式 (主要用于第三方中转场景，自动根据模型名"
+            "分发请求到 openai 或 gemini)"
+        ),
         default_value=[],
         type=list[ProviderConfig],
     )
@@ -278,15 +314,21 @@ def register_llm_configs():
 
 @lru_cache(maxsize=1)
 def get_llm_config() -> LLMConfig:
-    """获取 LLM 配置实例，不再加载 MCP 工具配置"""
+    """获取 LLM 配置实例"""
     ai_config = get_ai_config()
 
+    raw_debug = ai_config.get("debug_log", False)
+    if isinstance(raw_debug, bool):
+        debug_log_val = DebugLogOptions(
+            show_tools=raw_debug, show_schema=raw_debug, show_safety=raw_debug
+        )
+    else:
+        debug_log_val = raw_debug
+
     config_data = {
         "default_model_name": ai_config.get("default_model_name"),
-        "proxy": ai_config.get("proxy"),
-        "timeout": ai_config.get("timeout", 180),
-        "max_retries_llm": ai_config.get("max_retries_llm", 3),
-        "retry_delay_llm": ai_config.get("retry_delay_llm", 2),
+        "client_settings": ai_config.get("client_settings", {}),
+        "debug_log": debug_log_val,
         PROVIDERS_CONFIG_KEY: ai_config.get(PROVIDERS_CONFIG_KEY, []),
     }
 
@@ -314,14 +356,14 @@ def validate_llm_config() -> tuple[bool, list[str]]:
     try:
         llm_config = get_llm_config()
 
-        if llm_config.timeout <= 0:
+        if llm_config.client_settings.timeout <= 0:
             errors.append("timeout 必须大于 0")
 
-        if llm_config.max_retries_llm < 0:
-            errors.append("max_retries_llm 不能小于 0")
+        if llm_config.client_settings.max_retries < 0:
+            errors.append("max_retries 不能小于 0")
 
-        if llm_config.retry_delay_llm <= 0:
-            errors.append("retry_delay_llm 必须大于 0")
+        if llm_config.client_settings.retry_delay <= 0:
+            errors.append("retry_delay 必须大于 0")
 
         if not llm_config.providers:
             errors.append("至少需要配置一个 AI 服务提供商")