♻️ refactor(core): 重构 AI 能力与定时任务调度系统 (#2148)

* ♻️ refactor(core): 重构 AI 能力与定时任务调度系统

- 【AI 能力与工具】重构 Capability 注册与管理机制，引入 CapabilityManager 统一管理
- 移除全局能力注册表，改用声明式装饰器 `@capability` 进行解耦注册
- 重构工具解析器链，使用统一的 BaseToolResolver 代替原有的多个特定解析器
- 增强工具查询过滤，支持通配符匹配、工具箱过滤和排除标签
- 【定时任务调度】重构定时任务管理器，引入 SchedulerRegistry 统一管理任务元数据
- 引入 JobConfig 聚合定时任务配置，支持用户维度的定时任务调度
- 重构执行分发器，支持并发限制、串行间隔和随机延迟打散
- 【运行上下文】引入 ScheduledDeps 以支持后台和定时任务环境下的依赖注入
- 优化 RunContext，支持从定时任务上下文快速构造，并提供 emit 辅助方法
- 【日志与监控】引入 AILoggerProxy，实现 AI 各模块的专属日志输出
- 将各模块的全局 logger 替换为对应的模块专属日志代理
- 【其他优化】修复 Pydantic V1 兼容层中 model_validator 的装饰器兼容性问题
- 在非交互式环境（如定时任务）中自动隐藏 HITL 交互工具以节省 Token

* ♻️ refactor(core): 优化内部导入路径并提升 Pydantic 兼容性

- 【重构】将 `services/ai` 模块内的绝对导入重构为相对导入，优化包结构
- 【重构】移除不必要的 `if TYPE_CHECKING` 保护，通过 `from __future__ import annotations` 直接导入类型
- 【清理】清理 `core/messages/types.py` 中未使用的 `AssistantContentUnion` 等联合类型定义
- 【优化】在 `utils/pydantic_compat.py` 中新增 `model_rebuild` 兼容函数，统一 Pydantic V1/V2 的模型重建逻辑
- 【优化】将部分函数内部的延迟导入提升至模块顶部，规范代码结构

* ♻️ refactor(imports): 优化导入路径为相对导入并清理冗余导入

- 【重构】将 AI 服务相关模块中的绝对导入路径修改为相对导入，提升模块内聚性与可移植性
- 【清理】移除多处函数内部或类方法中未使用的冗余导入，避免循环引用和资源浪费
- 【格式化】微调部分工具装饰器和返回语句的格式与尾随逗号

* 🚨 auto fix by pre-commit hooks

---------

Co-authored-by: webjoin111 <455457521@qq.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

zhenxun/services/ai/tools/engine/executor.py

@@ -6,7 +6,7 @@ import asyncio
 from contextlib import asynccontextmanager
 import inspect
 import json
-from typing import TYPE_CHECKING, Any, cast
+from typing import Any, cast
 
 import json_repair
 from nonebot.adapters import Message as PlatformMessage
@@ -26,8 +26,9 @@ from zhenxun.services.ai.core.stream_events import (
     UserCustomEvent,
 )
 from zhenxun.services.ai.message_builder import MessageBuilder
-from zhenxun.services.ai.run.context import RunContext
+from zhenxun.services.ai.run.context import RunContext, set_run_context
 from zhenxun.services.ai.run.di import DependencyInjector
+from zhenxun.services.ai.tools.core.tool import BaseTool, register_tool_runner
 from zhenxun.services.ai.tools.models import (
     StateSyncResult,
     ToolOptions,
@@ -35,11 +36,9 @@ from zhenxun.services.ai.tools.models import (
     ToolResultChunk,
     ValidatedToolCall,
 )
-from zhenxun.services.log import logger
+from zhenxun.services.ai.utils.logger import log_tool as logger
 
-if TYPE_CHECKING:
-    from zhenxun.services.ai.tools.core.tool import BaseTool
-    from zhenxun.services.ai.tools.engine.registry import ToolCollection
+from .registry import ToolCollection
 
 
 class ToolExecutor:
@@ -49,6 +48,7 @@ class ToolExecutor:
     """
 
     def __init__(self):
+        """初始化工具执行器。"""
         pass
 
     def _get_combined_capability(
@@ -126,8 +126,7 @@ class ToolExecutor:
                                 arguments, parsed_successfully = parsed, True
                                 logger.debug(
                                     "⚒️ 成功修复损坏的工具参数: "
-                                    f"{args_str} -> {repaired_str}",
-                                    "ToolExecutor",
+                                    f"{args_str} -> {repaired_str}"
                                 )
                         except Exception:
                             pass
@@ -145,7 +144,7 @@ class ToolExecutor:
         tool_name: str,
         executable: Any,
         event_bus: EventBus | None,
-        available_tools: "ToolCollection | dict[str, Any] | None" = None,
+        available_tools: ToolCollection | dict[str, Any] | None = None,
     ) -> RunContext:
         """准备/克隆工具调用所使用的隔离 RunContext"""
         safe_context = (
@@ -163,7 +162,7 @@ class ToolExecutor:
     async def validate_tool_call(
         self,
         tool_call: ToolCallPart,
-        available_tools: "ToolCollection | dict[str, Any] | None",
+        available_tools: ToolCollection | dict[str, Any] | None,
         context: RunContext | None = None,
         event_bus: EventBus | None = None,
     ) -> ValidatedToolCall:
@@ -213,8 +212,6 @@ class ToolExecutor:
 
         async def inner_validate(args_inner):
             if isinstance(args_inner, dict) and hasattr(executable, "validate_args"):
-                import inspect
-
                 sig = inspect.signature(executable.validate_args)
                 if "context" in sig.parameters:
                     return await executable.validate_args(
@@ -247,7 +244,7 @@ class ToolExecutor:
     async def execute_tool_call(
         self,
         validated: ValidatedToolCall,
-        available_tools: "ToolCollection | dict[str, Any] | None",
+        available_tools: ToolCollection | dict[str, Any] | None,
         context: RunContext | None = None,
         model_name: str | None = None,
         max_retries: int = 0,
@@ -285,8 +282,6 @@ class ToolExecutor:
             available_tools,
         )
 
-        from zhenxun.services.ai.run.context import set_run_context
-
         combined_cap = self._get_combined_capability(executable, safe_context)
 
         async def inner_handler(args_inner: dict) -> Any:
@@ -322,7 +317,7 @@ class ToolExecutor:
     async def execute_batch(
         self,
         tool_calls: list[ToolCallPart],
-        available_tools: "ToolCollection | dict[str, Any] | None",
+        available_tools: ToolCollection | dict[str, Any] | None,
         context: RunContext | None = None,
         model_name: str | None = None,
         max_retries: int = 0,
@@ -415,11 +410,12 @@ class ToolExecutor:
 
 class ToolExecutionPolicy:
     """
-    工具执行策略 (Strategy Pattern)。
+    工具执行策略。
     负责解析工具私有配置与系统全局配置，决定最大重试次数、Fallback 路由目标等流转行为。
     """
 
     def __init__(self, tool: BaseTool, global_max_retries: int = 0):
+        """初始化工具执行策略。"""
         self.tool = tool
         self.settings: ToolOptions = getattr(tool, "settings", ToolOptions())
         self.metadata: dict[str, Any] = (
@@ -449,6 +445,7 @@ class ToolRunner(ABC):
     async def run(
         self, tool: BaseTool, context: RunContext, **kwargs: Any
     ) -> ToolResult:
+        """执行工具调用的抽象方法。"""
         pass
 
 
@@ -461,6 +458,7 @@ class NativeToolRunner(ToolRunner):
     async def run(
         self, tool: BaseTool, context: RunContext, **kwargs: Any
     ) -> ToolResult:
+        """运行原生 Python 函数工具并返回结果。"""
         target_func = tool.get_execute_target()
         signature_target = tool.get_signature_target()
 
@@ -498,8 +496,8 @@ class NativeToolRunner(ToolRunner):
                         if tool and hasattr(tool, "settings")
                         else False
                     )
-                    if context.run.event_bus and not is_silent:
-                        await context.run.event_bus.emit(
+                    if not is_silent:
+                        await context.run.emit(
                             ToolStreamChunkEvent(
                                 tool_name=tool.name,
                                 content=chunk_obj.content,
@@ -521,8 +519,7 @@ class NativeToolRunner(ToolRunner):
                     else res
                 )
                 parts = await MessageBuilder.unimsg_to_llm_parts(uni_msg)
-                if context and context.run.event_bus:
-                    await context.run.event_bus.emit(UserCustomEvent(display=uni_msg))
+                await context.run.emit(UserCustomEvent(display=uni_msg))
                 final_result = ToolResult(output=parts)
             else:
                 final_result = ToolResult(output=res)
@@ -530,6 +527,4 @@ class NativeToolRunner(ToolRunner):
         return final_result
 
 
-from zhenxun.services.ai.tools.core.tool import register_tool_runner
-
 register_tool_runner(NativeToolRunner)