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

@@ -1,8 +1,10 @@
+from __future__ import annotations
+
 """
 运行时（Run）相关核心类型定义
 """
 
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Callable
 import json
 from typing import Any, Generic, cast
 from typing_extensions import TypeVar
@@ -10,12 +12,16 @@ from typing_extensions import TypeVar
 from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
 
 from zhenxun.services.ai.core.messages import AgentMessage, LLMMessage, UsageInfo
+from zhenxun.services.ai.core.options import BaseOutputDefinition
+from zhenxun.services.ai.core.protocols.tool import ToolResolvable
 from zhenxun.services.ai.core.stream_events import (
     AgentStreamEvent,
     EventBus,
     ToolCallStartEvent,
     ToolStreamChunkEvent,
 )
+from zhenxun.services.ai.guardrails import BaseGuardrail, GuardrailSource
+from zhenxun.services.ai.tools.core.tool import BaseTool
 from zhenxun.utils.pydantic_compat import model_dump, model_validator
 
 
@@ -37,7 +43,7 @@ class ToolSummary(BaseModel):
     """工具执行失败次数"""
     total_latency_ms: float = 0.0
     """工具执行总耗时（毫秒）"""
-    by_name: dict[str, dict[str, Any]] = Field(default_factory=dict)
+    by_name: dict[str, dict[str, float | int]] = Field(default_factory=dict)
     """按工具名称细分的执行状态统计"""
 
 
@@ -126,9 +132,8 @@ class StreamedRunResult(Generic[OutputDataT]):
         self.is_complete: bool = False
         self._result: AgentRunResult[OutputDataT] | None = None
 
-    async def stream_events(self) -> AsyncIterator[Any]:
+    async def stream_events(self) -> "AsyncIterator[AgentStreamEvent]":
         """获取底层的所有原始事件（包含工具调用过程等）"""
-        from zhenxun.services.ai.run.models import AgentRunEnd, AgentRunError
 
         async for event in self._event_bus:
             if isinstance(event, AgentRunEnd):
@@ -214,24 +219,6 @@ class StreamedRunResult(Generic[OutputDataT]):
         return await self.get_run_result()
 
 
-class TaskResult(BaseModel):
-    """单个数据契约任务的执行结果"""
-
-    task_id: str
-    """关联的任务唯一 ID"""
-
-    output: Any
-    """任务的实际产出（如果是结构化任务，则为解析后的 Pydantic 实例；否则为纯文本）"""
-
-    raw_response: str | None = None
-    """大模型返回的原始纯文本内容"""
-
-    usage: UsageInfo = Field(default_factory=UsageInfo)
-    """该任务执行期间的 Token 消耗统计"""
-
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-
 class AgentTask(BaseModel):
     """标准化数据契约（意图载体 Payload），定义大模型需要做什么及产出什么格式"""
 
@@ -247,23 +234,25 @@ class AgentTask(BaseModel):
     expected_output: str
     """预期输出的自然语言描述（指导大模型如何组织最终答案）"""
 
-    response_model: Any | None = None
+    response_model: type[BaseModel] | BaseOutputDefinition | None = None
     """强制要求返回的强类型结构 (Pydantic Model) 或
     OutputDefinition，为空则返回普通文本"""
 
-    tools: list[str | Any] | None = None
+    tools: list[str | Callable | dict[str, Any] | BaseTool | ToolResolvable] | None = (
+        None
+    )
     """针对此特定任务动态追加或覆盖的工具列表"""
 
-    guardrails: list[Any] | None = None
+    guardrails: list[GuardrailSource] | None = None
     """护栏验证列表。支持传入函数、BaseGuardrail 实例，
     或直接传入自然语言字符串规则（自动转为 LLM 裁判）"""
 
-    _parsed_guardrails: list[Any] = PrivateAttr(default_factory=list)
+    _parsed_guardrails: list[BaseGuardrail] = PrivateAttr(default_factory=list)
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
     @model_validator(mode="after")
-    def _parse_and_set_guardrails(self) -> "AgentTask":
+    def _parse_and_set_guardrails(self) -> AgentTask:
         from zhenxun.services.ai.guardrails import parse_guardrails
 
         self._parsed_guardrails = parse_guardrails(self.guardrails)
@@ -275,5 +264,4 @@ __all__ = [
     "AgentTask",
     "OutputDataT",
     "StreamedRunResult",
-    "TaskResult",
 ]