♻️ 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/api.py

@@ -2,6 +2,7 @@
 LLM 服务的高级 API 接口 - 便捷函数入口 (无状态)
 """
 
+from collections.abc import Awaitable, Callable
 from pathlib import Path
 from typing import Any, TypeVar, overload
 
@@ -11,19 +12,24 @@ from pydantic import BaseModel
 from zhenxun.services.log import logger
 
 from .config import CommonOverrides
-from .config.generation import LLMGenerationConfig, create_generation_config_from_kwargs
+from .config.generation import (
+    GenConfigBuilder,
+    LLMEmbeddingConfig,
+    LLMGenerationConfig,
+    OutputConfig,
+)
 from .manager import get_model_instance
 from .session import AI
-from .tools.manager import tool_provider_manager
 from .types import (
-    EmbeddingTaskType,
     LLMContentPart,
     LLMErrorCode,
     LLMException,
     LLMMessage,
     LLMResponse,
     ModelName,
+    ToolChoice,
 )
+from .types.exceptions import get_user_friendly_error_message
 from .utils import create_multimodal_message
 
 T = TypeVar("T", bound=BaseModel)
@@ -34,9 +40,10 @@ async def chat(
     *,
     model: ModelName = None,
     instruction: str | None = None,
-    tools: list[dict[str, Any] | str] | None = None,
-    tool_choice: str | dict[str, Any] | None = None,
-    **kwargs: Any,
+    tools: list[Any] | None = None,
+    tool_choice: str | dict[str, Any] | ToolChoice | None = None,
+    config: LLMGenerationConfig | GenConfigBuilder | None = None,
+    timeout: float | None = None,
 ) -> LLMResponse:
     """
     无状态的聊天对话便捷函数，通过临时的AI会话实例与LLM模型交互。
@@ -47,14 +54,13 @@ async def chat(
         instruction: 系统指令，用于指导AI的行为和回复风格。
         tools: 可用的工具列表，支持字典配置或字符串标识符。
         tool_choice: 工具选择策略，控制AI如何选择和使用工具。
-        **kwargs: 额外的生成配置参数，会被转换为LLMGenerationConfig。
+        config: (可选) 生成配置对象，将与默认配置合并后传递。
+        timeout: (可选) HTTP 请求超时时间（秒）。
 
     返回:
         LLMResponse: 包含AI回复内容、使用信息和工具调用等的完整响应对象。
     """
     try:
-        config = create_generation_config_from_kwargs(**kwargs) if kwargs else None
-
         ai_session = AI()
 
         return await ai_session.chat(
@@ -64,12 +70,14 @@ async def chat(
             tools=tools,
             tool_choice=tool_choice,
             config=config,
+            timeout=timeout,
         )
     except LLMException:
         raise
     except Exception as e:
-        logger.error(f"执行 chat 函数失败: {e}", e=e)
-        raise LLMException(f"聊天执行失败: {e}", cause=e)
+        friendly_msg = get_user_friendly_error_message(e)
+        logger.error(f"执行 chat 函数失败: {e} | 建议: {friendly_msg}", e=e)
+        raise LLMException(f"聊天执行失败: {friendly_msg}", cause=e)
 
 
 async def code(
@@ -77,7 +85,6 @@ async def code(
     *,
     model: ModelName = None,
     timeout: int | None = None,
-    **kwargs: Any,
 ) -> LLMResponse:
     """
     无状态的代码执行便捷函数，支持在沙箱环境中执行代码。
@@ -86,66 +93,25 @@ async def code(
         prompt: 代码执行的提示词，描述要执行的代码任务。
         model: 要使用的模型名称，默认使用Gemini/gemini-2.0-flash。
         timeout: 代码执行超时时间（秒），防止长时间运行的代码阻塞。
-        **kwargs: 额外的生成配置参数。
 
     返回:
         LLMResponse: 包含代码执行结果的完整响应对象。
     """
-    resolved_model = model or "Gemini/gemini-2.0-flash"
+    resolved_model = model
 
     config = CommonOverrides.gemini_code_execution()
     if timeout:
         config.custom_params = config.custom_params or {}
         config.custom_params["code_execution_timeout"] = timeout
 
-    final_config = config.to_dict()
-    final_config.update(kwargs)
-
-    return await chat(prompt, model=resolved_model, **final_config)
-
-
-async def search(
-    query: str | UniMessage | LLMMessage | list[LLMContentPart],
-    *,
-    model: ModelName = None,
-    instruction: str = (
-        "你是一位强大的信息检索和整合专家。请利用可用的搜索工具，"
-        "根据用户的查询找到最相关的信息，并进行总结和回答。"
-    ),
-    **kwargs: Any,
-) -> LLMResponse:
-    """
-    无状态的信息搜索便捷函数，利用搜索工具获取实时信息。
-
-    参数:
-        query: 搜索查询内容，支持多种输入格式。
-        model: 要使用的模型名称，如果为None则使用默认模型。
-        instruction: 搜索任务的系统指令，指导AI如何处理搜索结果。
-        **kwargs: 额外的生成配置参数。
-
-    返回:
-        LLMResponse: 包含搜索结果和AI整合回复的完整响应对象。
-    """
-    logger.debug("执行无状态 'search' 任务...")
-    search_config = CommonOverrides.gemini_grounding()
-
-    final_config = search_config.to_dict()
-    final_config.update(kwargs)
-
-    return await chat(
-        query,
-        model=model,
-        instruction=instruction,
-        **final_config,
-    )
+    return await chat(prompt, model=resolved_model, config=config)
 
 
 async def embed(
     texts: list[str] | str,
     *,
     model: ModelName = None,
-    task_type: EmbeddingTaskType | str = EmbeddingTaskType.RETRIEVAL_DOCUMENT,
-    **kwargs: Any,
+    config: LLMEmbeddingConfig | None = None,
 ) -> list[list[float]]:
     """
     无状态的文本嵌入便捷函数，将文本转换为向量表示。
@@ -153,8 +119,7 @@ async def embed(
     参数:
         texts: 要生成嵌入的文本内容，支持单个字符串或字符串列表。
         model: 要使用的嵌入模型名称，如果为None则使用默认模型。
-        task_type: 嵌入任务类型，影响向量的优化方向（如检索、分类等）。
-        **kwargs: 额外的模型配置参数。
+        config: 嵌入配置对象。
 
     返回:
         list[list[float]]: 文本对应的嵌入向量列表，每个向量为浮点数列表。
@@ -164,27 +129,71 @@ async def embed(
     if not texts:
         return []
 
+    final_config = config or LLMEmbeddingConfig()
+
     try:
         async with await get_model_instance(model) as model_instance:
-            return await model_instance.generate_embeddings(
-                texts, task_type=task_type, **kwargs
-            )
+            return await model_instance.generate_embeddings(texts, config=final_config)
     except LLMException:
         raise
     except Exception as e:
-        logger.error(f"文本嵌入失败: {e}", e=e)
+        friendly_msg = get_user_friendly_error_message(e)
+        logger.error(f"文本嵌入失败: {e} | 建议: {friendly_msg}", e=e)
         raise LLMException(
-            f"文本嵌入失败: {e}", code=LLMErrorCode.EMBEDDING_FAILED, cause=e
+            f"文本嵌入失败: {friendly_msg}",
+            code=LLMErrorCode.EMBEDDING_FAILED,
+            cause=e,
         )
 
 
+async def embed_query(
+    text: str,
+    *,
+    model: ModelName = None,
+    dimensions: int | None = None,
+) -> list[float]:
+    """
+    语义化便捷 API：为检索查询生成嵌入。
+    """
+    config = LLMEmbeddingConfig(
+        task_type="RETRIEVAL_QUERY",
+        output_dimensionality=dimensions,
+    )
+    vectors = await embed([text], model=model, config=config)
+    return vectors[0] if vectors else []
+
+
+async def embed_documents(
+    texts: list[str],
+    *,
+    model: ModelName = None,
+    dimensions: int | None = None,
+    title: str | None = None,
+) -> list[list[float]]:
+    """
+    语义化便捷 API：为文档集合生成嵌入。
+    """
+    config = LLMEmbeddingConfig(
+        task_type="RETRIEVAL_DOCUMENT",
+        output_dimensionality=dimensions,
+        title=title,
+    )
+    return await embed(texts, model=model, config=config)
+
+
 async def generate_structured(
     message: str | LLMMessage | list[LLMContentPart],
     response_model: type[T],
     *,
     model: ModelName = None,
+    tools: list[Any] | None = None,
+    tool_choice: str | dict[str, Any] | ToolChoice | None = None,
+    max_validation_retries: int | None = None,
+    validation_callback: Callable[[T], Any | Awaitable[Any]] | None = None,
+    error_prompt_template: str | None = None,
+    auto_thinking: bool = False,
     instruction: str | None = None,
-    **kwargs: Any,
+    timeout: float | None = None,
 ) -> T:
     """
     无状态地生成结构化响应，并自动解析为指定的Pydantic模型。
@@ -192,39 +201,48 @@ async def generate_structured(
     参数:
         message: 用户输入的消息内容，支持多种格式。
         response_model: 用于解析和验证响应的Pydantic模型类。
+        max_validation_retries: 校验失败时的最大重试次数，默认为 None (使用全局配置)。
+        validation_callback: 自定义校验回调函数，抛出异常视为校验失败。
+        error_prompt_template: 自定义错误反馈提示词模板。
+        auto_thinking: 是否自动开启思维链 (CoT) 包装。适用于不支持原生思考的模型
         model: 要使用的模型名称，如果为None则使用默认模型。
         instruction: 系统指令，用于指导AI生成符合要求的结构化输出。
-        **kwargs: 额外的生成配置参数。
+        timeout: HTTP 请求超时时间（秒）。
 
     返回:
         T: 解析后的Pydantic模型实例，类型为response_model指定的类型。
     """
     try:
-        config = create_generation_config_from_kwargs(**kwargs) if kwargs else None
-
         ai_session = AI()
 
         return await ai_session.generate_structured(
             message,
             response_model,
             model=model,
+            tools=tools,
+            tool_choice=tool_choice,
+            max_validation_retries=max_validation_retries,
+            validation_callback=validation_callback,
+            error_prompt_template=error_prompt_template,
+            auto_thinking=auto_thinking,
             instruction=instruction,
-            config=config,
+            timeout=timeout,
         )
     except LLMException:
         raise
     except Exception as e:
-        logger.error(f"生成结构化响应失败: {e}", e=e)
-        raise LLMException(f"生成结构化响应失败: {e}", cause=e)
+        friendly_msg = get_user_friendly_error_message(e)
+        logger.error(f"生成结构化响应失败: {e} | 建议: {friendly_msg}", e=e)
+        raise LLMException(f"生成结构化响应失败: {friendly_msg}", cause=e)
 
 
 async def generate(
     messages: list[LLMMessage],
     *,
     model: ModelName = None,
-    tools: list[dict[str, Any] | str] | None = None,
-    tool_choice: str | dict[str, Any] | None = None,
-    **kwargs: Any,
+    tools: list[Any] | None = None,
+    tool_choice: str | dict[str, Any] | ToolChoice | None = None,
+    config: LLMGenerationConfig | GenConfigBuilder | None = None,
 ) -> LLMResponse:
     """
     根据完整的消息列表生成一次性响应，这是一个无状态的底层函数。
@@ -234,103 +252,57 @@ async def generate(
         model: 要使用的模型名称，如果为None则使用默认模型。
         tools: 可用的工具列表，支持字典配置或字符串标识符。
         tool_choice: 工具选择策略，控制AI如何选择和使用工具。
-        **kwargs: 额外的生成配置参数，会覆盖默认配置。
+        config: (可选) 生成配置对象，将与默认配置合并后传递。
 
     返回:
         LLMResponse: 包含AI回复内容、使用信息和工具调用等的完整响应对象。
     """
     try:
+        if isinstance(config, GenConfigBuilder):
+            config = config.build()
+
         async with await get_model_instance(
-            model, override_config=kwargs
+            model, override_config=None
         ) as model_instance:
             return await model_instance.generate_response(
                 messages,
-                tools=tools,  # type: ignore
+                config=config,
+                tools=tools,  # type: ignore[arg-type]
                 tool_choice=tool_choice,
             )
     except LLMException:
         raise
     except Exception as e:
-        logger.error(f"生成响应失败: {e}", e=e)
-        raise LLMException(f"生成响应失败: {e}", cause=e)
-
-
-async def run_with_tools(
-    message: str | UniMessage | LLMMessage | list[LLMContentPart],
-    *,
-    model: ModelName = None,
-    instruction: str | None = None,
-    tools: list[str],
-    max_cycles: int = 5,
-    **kwargs: Any,
-) -> LLMResponse:
-    """
-    无状态地执行一个带本地Python函数的LLM调用循环。
-
-    参数:
-        message: 用户输入。
-        model: 使用的模型。
-        instruction: 系统指令。
-        tools: 要使用的本地函数工具名称列表 (必须已通过 @function_tool 注册)。
-        max_cycles: 最大工具调用循环次数。
-        **kwargs: 额外的生成配置参数。
-
-    返回:
-        LLMResponse: 包含最终回复的响应对象。
-    """
-    from .executor import ExecutionConfig, LLMToolExecutor
-    from .utils import normalize_to_llm_messages
-
-    messages = await normalize_to_llm_messages(message, instruction)
-
-    async with await get_model_instance(
-        model, override_config=kwargs
-    ) as model_instance:
-        resolved_tools = await tool_provider_manager.get_function_tools(tools)
-        if not resolved_tools:
-            logger.warning(
-                "run_with_tools 未找到任何可用的本地函数工具，将作为普通聊天执行。"
-            )
-            return await model_instance.generate_response(messages, tools=None)
-
-        executor = LLMToolExecutor(model_instance)
-        config = ExecutionConfig(max_cycles=max_cycles)
-        final_history = await executor.run(messages, resolved_tools, config)
-
-        for msg in reversed(final_history):
-            if msg.role == "assistant":
-                text = msg.content if isinstance(msg.content, str) else str(msg.content)
-                return LLMResponse(text=text, tool_calls=msg.tool_calls)
-
-    raise LLMException(
-        "带工具的执行循环未能产生有效的助手回复。", code=LLMErrorCode.GENERATION_FAILED
-    )
+        friendly_msg = get_user_friendly_error_message(e)
+        logger.error(f"生成响应失败: {e} | 建议: {friendly_msg}", e=e)
+        raise LLMException(f"生成响应失败: {friendly_msg}", cause=e)
 
 
 async def _generate_image_from_message(
     message: UniMessage,
     model: ModelName = None,
-    **kwargs: Any,
+    config: LLMGenerationConfig | GenConfigBuilder | None = None,
 ) -> LLMResponse:
     """
     [内部] 从 UniMessage 生成图片的核心辅助函数。
     """
     from .utils import normalize_to_llm_messages
 
-    config = (
-        create_generation_config_from_kwargs(**kwargs)
-        if kwargs
-        else LLMGenerationConfig()
-    )
+    if isinstance(config, GenConfigBuilder):
+        config = config.build()
+
+    config = config or LLMGenerationConfig()
 
     config.validation_policy = {"require_image": True}
-    config.response_modalities = ["IMAGE", "TEXT"]
+    if config.output is None:
+        config.output = OutputConfig()
+    config.output.response_modalities = ["IMAGE", "TEXT"]
 
     try:
         messages = await normalize_to_llm_messages(message)
 
         async with await get_model_instance(model) as model_instance:
-            if not model_instance.can_generate_images():
+            if not model_instance.can_generate_images:
                 raise LLMException(
                     f"模型 '{model_instance.provider_name}/{model_instance.model_name}'"
                     f"不支持图片生成",
@@ -347,8 +319,9 @@ async def _generate_image_from_message(
     except LLMException:
         raise
     except Exception as e:
-        logger.error(f"执行图片生成时发生未知错误: {e}", e=e)
-        raise LLMException(f"图片生成失败: {e}", cause=e)
+        friendly_msg = get_user_friendly_error_message(e)
+        logger.error(f"执行图片生成时发生未知错误: {e} | 建议: {friendly_msg}", e=e)
+        raise LLMException(f"图片生成失败: {friendly_msg}", cause=e)
 
 
 @overload
@@ -357,7 +330,6 @@ async def create_image(
     *,
     images: None = None,
     model: ModelName = None,
-    **kwargs: Any,
 ) -> LLMResponse:
     """根据文本提示生成一张新图片。"""
     ...
@@ -369,7 +341,6 @@ async def create_image(
     *,
     images: list[Path | bytes | str] | Path | bytes | str,
     model: ModelName = None,
-    **kwargs: Any,
 ) -> LLMResponse:
     """在给定图片的基础上，根据文本提示进行编辑或重新生成。"""
     ...
@@ -380,7 +351,7 @@ async def create_image(
     *,
     images: list[Path | bytes | str] | Path | bytes | str | None = None,
     model: ModelName = None,
-    **kwargs: Any,
+    config: LLMGenerationConfig | GenConfigBuilder | None = None,
 ) -> LLMResponse:
     """
     智能图片生成/编辑函数。
@@ -400,4 +371,42 @@ async def create_image(
 
     message = create_multimodal_message(text=text_prompt, images=image_list)
 
-    return await _generate_image_from_message(message, model=model, **kwargs)
+    return await _generate_image_from_message(message, model=model, config=config)
+
+
+async def search(
+    query: str | UniMessage | LLMMessage | list[LLMContentPart],
+    *,
+    model: ModelName = None,
+    instruction: str = (
+        "你是一位强大的信息检索和整合专家。请利用可用的搜索工具，"
+        "根据用户的查询找到最相关的信息，并进行总结和回答。"
+    ),
+    config: LLMGenerationConfig | GenConfigBuilder | None = None,
+) -> LLMResponse:
+    """
+    无状态的信息搜索便捷函数，利用搜索工具获取实时信息。
+
+    参数:
+        query: 搜索查询内容，支持多种输入格式。
+        model: 要使用的模型名称，如果为None则使用默认模型。
+        config: (可选) 生成配置对象，将与预设配置合并后传递。
+        instruction: 搜索任务的系统指令，指导AI如何处理搜索结果。
+
+    返回:
+        LLMResponse: 包含搜索结果和AI整合回复的完整响应对象。
+    """
+    logger.debug("执行无状态 'search' 任务...")
+    search_config = CommonOverrides.gemini_grounding()
+
+    if isinstance(config, GenConfigBuilder):
+        config = config.build()
+
+    final_config = search_config.merge_with(config)
+
+    return await chat(
+        query,
+        model=model,
+        instruction=instruction,
+        config=final_config,
+    )