♻️ refactor!: 重构LLM服务架构并统一Pydantic兼容性处理 (#2002)

* ♻️ refactor(pydantic): 提取 Pydantic 兼容函数到独立模块

* ♻️ refactor!(llm): 重构LLM服务，引入现代化工具和执行器架构

🏗️ **架构变更**
- 引入ToolProvider/ToolExecutable协议，取代ToolRegistry
- 新增LLMToolExecutor，分离工具调用逻辑
- 新增BaseMemory抽象，解耦会话状态管理

🔄 **API重构**
- 移除：analyze, analyze_multimodal, pipeline_chat
- 新增：generate_structured, run_with_tools
- 重构：chat, search, code变为无状态调用

🛠️ **工具系统**
- 新增@function_tool装饰器
- 统一工具定义到ToolExecutable协议
- 移除MCP工具系统和mcp_tools.json

---------

Co-authored-by: webjoin111 <455457521@qq.com>

zhenxun/services/llm/config/__init__.py

@@ -14,7 +14,6 @@ from .generation import (
 from .presets import CommonOverrides
 from .providers import (
     LLMConfig,
-    ToolConfig,
     get_gemini_safety_threshold,
     get_llm_config,
     register_llm_configs,
@@ -27,7 +26,6 @@ __all__ = [
     "LLMConfig",
     "LLMGenerationConfig",
     "ModelConfigOverride",
-    "ToolConfig",
     "apply_api_specific_mappings",
     "create_generation_config_from_kwargs",
     "get_gemini_safety_threshold",

zhenxun/services/llm/config/generation.py

@@ -7,6 +7,7 @@ from typing import Any
 from pydantic import BaseModel, Field
 
 from zhenxun.services.log import logger
+from zhenxun.utils.pydantic_compat import model_dump
 
 from ..types.enums import ResponseFormat
 from ..types.exceptions import LLMErrorCode, LLMException
@@ -45,6 +46,9 @@ class ModelConfigOverride(BaseModel):
     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="安全设置")
     response_modalities: list[str] | None = Field(
         default=None, description="响应模态类型"
@@ -62,22 +66,16 @@ class ModelConfigOverride(BaseModel):
 
     def to_dict(self) -> dict[str, Any]:
         """转换为字典，排除None值"""
+
+        model_data = model_dump(self, exclude_none=True)
+
         result = {}
-        model_data = getattr(self, "model_dump", lambda: {})()
-        if not model_data:
-            model_data = {}
-            for field_name, _ in self.__class__.__dict__.get(
-                "model_fields", {}
-            ).items():
-                value = getattr(self, field_name, None)
-                if value is not None:
-                    model_data[field_name] = value
         for key, value in model_data.items():
-            if value is not None:
-                if key == "custom_params" and isinstance(value, dict):
-                    result.update(value)
-                else:
-                    result[key] = value
+            if key == "custom_params" and isinstance(value, dict):
+                result.update(value)
+            else:
+                result[key] = value
+
         return result
 
     def merge_with_base_config(
@@ -157,6 +155,10 @@ class LLMGenerationConfig(ModelConfigOverride):
                         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
@@ -169,17 +171,28 @@ class LLMGenerationConfig(ModelConfigOverride):
 
             if self.response_schema is not None and "responseSchema" not in params:
                 params["responseSchema"] = self.response_schema
-            if self.thinking_budget is not None:
-                params["thinkingBudget"] = self.thinking_budget
+
+            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
 
-        if self.custom_params:
-            custom_mapped = apply_api_specific_mappings(self.custom_params, api_type)
-            params.update(custom_mapped)
-
         logger.debug(f"为{api_type}转换配置参数: {len(params)}个参数")
         return params
 

zhenxun/services/llm/config/providers.py

@@ -5,33 +5,19 @@ LLM 提供商配置管理
 """
 
 from functools import lru_cache
-import json
-import sys
 from typing import Any
 
 from pydantic import BaseModel, Field
 
 from zhenxun.configs.config import Config
-from zhenxun.configs.path_config import DATA_PATH
 from zhenxun.configs.utils import parse_as
 from zhenxun.services.log import logger
 from zhenxun.utils.manager.priority_manager import PriorityLifecycle
 
 from ..core import key_store
+from ..tools import tool_provider_manager
 from ..types.models import ModelDetail, ProviderConfig
 
-
-class ToolConfig(BaseModel):
-    """MCP类型工具的配置定义"""
-
-    type: str = "mcp"
-    name: str = Field(..., description="工具的唯一名称标识")
-    description: str | None = Field(None, description="工具功能的描述")
-    mcp_config: dict[str, Any] | BaseModel = Field(
-        ..., description="MCP服务器的特定配置"
-    )
-
-
 AI_CONFIG_GROUP = "AI"
 PROVIDERS_CONFIG_KEY = "PROVIDERS"
 
@@ -57,9 +43,6 @@ class LLMConfig(BaseModel):
     providers: list[ProviderConfig] = Field(
         default_factory=list, description="配置多个 AI 服务提供商及其模型信息"
     )
-    mcp_tools: list[ToolConfig] = Field(
-        default_factory=list, description="配置可用的外部MCP工具"
-    )
 
     def get_provider_by_name(self, name: str) -> ProviderConfig | None:
         """根据名称获取提供商配置
@@ -218,33 +201,6 @@ def get_default_providers() -> list[dict[str, Any]]:
     ]
 
 
-def get_default_mcp_tools() -> dict[str, Any]:
-    """
-    获取默认的MCP工具配置，用于在文件不存在时创建。
-    包含了 baidu-map, Context7, 和 sequential-thinking.
-    """
-    return {
-        "mcpServers": {
-            "baidu-map": {
-                "command": "npx",
-                "args": ["-y", "@baidumap/mcp-server-baidu-map"],
-                "env": {"BAIDU_MAP_API_KEY": "<YOUR_BAIDU_MAP_API_KEY>"},
-                "description": "百度地图工具，提供地理编码、路线规划等功能。",
-            },
-            "sequential-thinking": {
-                "command": "npx",
-                "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
-                "description": "顺序思维工具，用于帮助模型进行多步骤推理。",
-            },
-            "Context7": {
-                "command": "npx",
-                "args": ["-y", "@upstash/context7-mcp@latest"],
-                "description": "Upstash 提供的上下文管理和记忆工具。",
-            },
-        }
-    }
-
-
 def register_llm_configs():
     """注册 LLM 服务的配置项"""
     logger.info("注册 LLM 服务的配置项")
@@ -312,88 +268,9 @@ def register_llm_configs():
 
 @lru_cache(maxsize=1)
 def get_llm_config() -> LLMConfig:
-    """获取 LLM 配置实例，现在会从新的 JSON 文件加载 MCP 工具"""
+    """获取 LLM 配置实例，不再加载 MCP 工具配置"""
     ai_config = get_ai_config()
 
-    llm_data_path = DATA_PATH / "llm"
-    mcp_tools_path = llm_data_path / "mcp_tools.json"
-
-    mcp_tools_list = []
-    mcp_servers_dict = {}
-
-    if not mcp_tools_path.exists():
-        logger.info(f"未找到 MCP 工具配置文件，将在 '{mcp_tools_path}' 创建一个。")
-        llm_data_path.mkdir(parents=True, exist_ok=True)
-        default_mcp_config = get_default_mcp_tools()
-        try:
-            with mcp_tools_path.open("w", encoding="utf-8") as f:
-                json.dump(default_mcp_config, f, ensure_ascii=False, indent=2)
-            mcp_servers_dict = default_mcp_config.get("mcpServers", {})
-        except Exception as e:
-            logger.error(f"创建默认 MCP 配置文件失败: {e}", e=e)
-            mcp_servers_dict = {}
-    else:
-        try:
-            with mcp_tools_path.open("r", encoding="utf-8") as f:
-                mcp_data = json.load(f)
-                mcp_servers_dict = mcp_data.get("mcpServers", {})
-                if not isinstance(mcp_servers_dict, dict):
-                    logger.warning(
-                        f"'{mcp_tools_path}' 中的 'mcpServers' 键不是一个字典，"
-                        f"将使用空配置。"
-                    )
-                    mcp_servers_dict = {}
-
-        except json.JSONDecodeError as e:
-            logger.error(f"解析 MCP 配置文件 '{mcp_tools_path}' 失败: {e}", e=e)
-        except Exception as e:
-            logger.error(f"读取 MCP 配置文件时发生未知错误: {e}", e=e)
-            mcp_servers_dict = {}
-
-    if sys.platform == "win32":
-        logger.debug("检测到Windows平台，正在调整MCP工具的npx命令...")
-        for name, config in mcp_servers_dict.items():
-            if isinstance(config, dict) and config.get("command") == "npx":
-                logger.info(f"为工具 '{name}' 包装npx命令以兼容Windows。")
-                original_args = config.get("args", [])
-                config["command"] = "cmd"
-                config["args"] = ["/c", "npx", *original_args]
-
-    if mcp_servers_dict:
-        mcp_tools_list = [
-            {
-                "name": name,
-                "type": "mcp",
-                "description": config.get("description", f"MCP tool for {name}"),
-                "mcp_config": config,
-            }
-            for name, config in mcp_servers_dict.items()
-            if isinstance(config, dict)
-        ]
-
-    from ..tools.registry import tool_registry
-
-    for tool_dict in mcp_tools_list:
-        if isinstance(tool_dict, dict):
-            tool_name = tool_dict.get("name")
-            if not tool_name:
-                continue
-
-            config_model = tool_registry.get_mcp_config_model(tool_name)
-            if not config_model:
-                logger.debug(
-                    f"MCP工具 '{tool_name}' 没有注册其配置模型，"
-                    f"将跳过特定配置验证，直接使用原始配置字典。"
-                )
-                continue
-
-            mcp_config_data = tool_dict.get("mcp_config", {})
-            try:
-                parsed_mcp_config = parse_as(config_model, mcp_config_data)
-                tool_dict["mcp_config"] = parsed_mcp_config
-            except Exception as e:
-                raise ValueError(f"MCP工具 '{tool_name}' 的 `mcp_config` 配置错误: {e}")
-
     config_data = {
         "default_model_name": ai_config.get("default_model_name"),
         "proxy": ai_config.get("proxy"),
@@ -401,7 +278,6 @@ def get_llm_config() -> LLMConfig:
         "max_retries_llm": ai_config.get("max_retries_llm", 3),
         "retry_delay_llm": ai_config.get("retry_delay_llm", 2),
         PROVIDERS_CONFIG_KEY: ai_config.get(PROVIDERS_CONFIG_KEY, []),
-        "mcp_tools": mcp_tools_list,
     }
 
     return parse_as(LLMConfig, config_data)
@@ -504,12 +380,17 @@ def set_default_model(provider_model_name: str | None) -> bool:
 async def _init_llm_config_on_startup():
     """
     在服务启动时主动调用一次 get_llm_config 和 key_store.initialize，
-    以触发必要的初始化操作。
+    并预热工具提供者管理器。
     """
     logger.info("正在初始化 LLM 配置并加载密钥状态...")
     try:
         get_llm_config()
         await key_store.initialize()
-        logger.info("LLM 配置和密钥状态初始化完成。")
+        logger.debug("LLM 配置和密钥状态初始化完成。")
+
+        logger.debug("正在预热 LLM 工具提供者管理器...")
+        await tool_provider_manager.initialize()
+        logger.debug("LLM 工具提供者管理器预热完成。")
+
     except Exception as e:
         logger.error(f"LLM 配置或密钥状态初始化时发生错误: {e}", e=e)