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

@@ -5,10 +5,13 @@ from .base import (
     WrapToolExecuteHandler,
     WrapToolValidateHandler,
 )
+from .manager import CapabilityQuery, CapabilitySource, capability
 from .wrappers import CombinedCapability, DynamicCapability, WrapperCapability
 
 __all__ = [
     "AbstractCapability",
+    "CapabilityQuery",
+    "CapabilitySource",
     "CombinedCapability",
     "DynamicCapability",
     "WrapModelRequestHandler",
@@ -16,4 +19,5 @@ __all__ = [
     "WrapToolExecuteHandler",
     "WrapToolValidateHandler",
     "WrapperCapability",
+    "capability",
 ]

zhenxun/services/ai/capabilities/base.py

@@ -2,20 +2,20 @@ from __future__ import annotations
 
 from collections.abc import Awaitable, Callable, Sequence
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, ClassVar, Literal, Union
+from typing import TYPE_CHECKING, Any, Literal, Union
 
 from zhenxun.services.ai.core.messages import ChatRequest, ChatResponse
+from zhenxun.services.ai.core.models import LLMContext
 from zhenxun.services.ai.core.options import GenerationConfig
 
 if TYPE_CHECKING:
-    from zhenxun.services.ai.core.models import LLMContext
     from zhenxun.services.ai.run import AgentRunResult, RunContext
 
 WrapRunHandler = Callable[[], Awaitable["AgentRunResult[Any]"]]
 """整个 Agent 运行过程包裹的处理函数类型"""
 
 WrapModelRequestHandler = Callable[
-    ["LLMContext[ChatRequest, ChatResponse]"], Awaitable[ChatResponse]
+    [LLMContext[ChatRequest, ChatResponse]], Awaitable[ChatResponse]
 ]
 """单次大模型 API 请求包裹的处理函数类型"""
 
@@ -52,34 +52,14 @@ class CapabilityOrdering:
 class AbstractCapability:
     """
     Agent 能力组件基类协议。
-    所有业务逻辑拦截（限流、权限、动态 Prompt）请在此实现。
-    底层网络重试、并发控制等请勿在此处理。
     """
 
-    @classmethod
-    def get_serialization_name(cls) -> str | None:
-        """用于 YAML/JSON 反序列化的注册标识符"""
-        return cls.__name__
-
-    @classmethod
-    def from_spec(cls, **kwargs) -> "AbstractCapability":
-        """从 Spec 的 kwargs 中实例化对象"""
-        return cls(**kwargs)
-
-    def __init_subclass__(cls, **kwargs):
-        """自动将继承此类的所有拦截器注册到中心表"""
-        super().__init_subclass__(**kwargs)
-        CapabilityRegistry.register(cls)
-
     def get_ordering(self) -> CapabilityOrdering | None:
         """获取该拦截器的拓扑排序约束。子类可重写此方法以锁定执行顺序。"""
         return None
 
     async def for_run(self, context: RunContext) -> "AbstractCapability":
-        """获取专用于单次运行的实例。
-        默认返回自身(无状态)。
-        若需要记录单次运行的上下文状态，请返回深/浅拷贝(如 return copy.copy(self))。
-        """
+        """获取专用于单次运行的实例,默认返回自身(无状态)。"""
         return self
 
     async def get_generation_config(
@@ -89,9 +69,11 @@ class AbstractCapability:
         return None
 
     async def get_system_prompts(self, context: RunContext) -> list[str]:
+        """获取该能力提供的系统提示词列表。"""
         return []
 
     async def get_tools(self, context: RunContext) -> list[Any]:
+        """获取该能力附带的工具列表。"""
         return []
 
     async def prepare_tools(
@@ -135,19 +117,3 @@ class AbstractCapability:
     ) -> Any:
         """包裹单一工具的执行 (洋葱模型)。"""
         return await handler(arguments)
-
-
-class CapabilityRegistry:
-    """Capability 序列化注册表"""
-
-    _registry: ClassVar[dict[str, type[AbstractCapability]]] = {}
-
-    @classmethod
-    def register(cls, cap_cls: type[AbstractCapability]):
-        name = cap_cls.get_serialization_name()
-        if name:
-            cls._registry[name] = cap_cls
-
-    @classmethod
-    def get(cls, name: str) -> type[AbstractCapability] | None:
-        return cls._registry.get(name)

zhenxun/services/ai/capabilities/builtin.py

@@ -5,11 +5,6 @@ import json
 from typing import Any, cast
 
 from zhenxun.models.user_console import UserConsole
-from zhenxun.services.ai.capabilities import (
-    AbstractCapability,
-    WrapModelRequestHandler,
-    WrapToolExecuteHandler,
-)
 from zhenxun.services.ai.config import get_llm_config
 from zhenxun.services.ai.core.exceptions import (
     AbortException,
@@ -33,10 +28,17 @@ from zhenxun.services.ai.core.messages import (
 from zhenxun.services.ai.core.models import LLMContext
 from zhenxun.services.ai.run.context import RunContext
 from zhenxun.services.ai.utils import PermissionUtils
-from zhenxun.services.log import logger
+from zhenxun.services.ai.utils.logger import log_capability as logger
 from zhenxun.utils.enum import GoldHandle
 from zhenxun.utils.exception import InsufficientGold
 
+from .base import (
+    AbstractCapability,
+    WrapModelRequestHandler,
+    WrapToolExecuteHandler,
+)
+from .manager import capability
+
 
 def _get_tool_meta(tool: Any, key: str, default: Any = None) -> Any:
     """辅助方法：安全地提取工具元数据中指定的键值"""
@@ -47,6 +49,7 @@ def _get_tool_meta(tool: Any, key: str, default: Any = None) -> Any:
     return meta.get(key, default)
 
 
+@capability(namespace="global", auto_apply=True)
 class StuckDetectionCapability(AbstractCapability):
     """死循环检测：使用前置请求拦截防止 LLM 陷入无限重试"""
 
@@ -120,6 +123,7 @@ class StuckDetectionCapability(AbstractCapability):
         return await handler(llm_context)
 
 
+@capability(namespace="global", auto_apply=True)
 class GlobalCycleLimitCapability(AbstractCapability):
     """全局防死循环检测中间件：跨 Agent 追踪大模型调用总次数"""
 
@@ -152,6 +156,7 @@ class GlobalCycleLimitCapability(AbstractCapability):
         return await handler(llm_context)
 
 
+@capability(namespace="global", auto_apply=True)
 class PermissionCapability(AbstractCapability):
     """权限校验中间件：在执行前根据确定参数进行动态鉴权"""
 
@@ -182,6 +187,7 @@ class PermissionCapability(AbstractCapability):
         return await handler(arguments)
 
 
+@capability(namespace="global", auto_apply=True)
 class BillingCapability(AbstractCapability):
     """经济系统中间件：执行前扣除金币"""
 
@@ -221,6 +227,7 @@ class BillingCapability(AbstractCapability):
         return await handler(arguments)
 
 
+@capability(namespace="global", auto_apply=True)
 class ToolRetryAndReflectionCapability(AbstractCapability):
     """
     重试与自愈反思中间件。
@@ -267,6 +274,7 @@ class ToolRetryAndReflectionCapability(AbstractCapability):
             return ToolResult(output=f"执行发生异常: {e}").as_error()
 
 
+@capability(namespace="global", auto_apply=True)
 class ReflexionCapability(AbstractCapability):
     """自愈反思与验证引擎 (Reflexion Engine)。
     统一处理结构化解析失败和语义护栏拦截。"""

zhenxun/services/ai/capabilities/manager.py

@@ -0,0 +1,206 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+import fnmatch
+from typing import Any, cast
+from typing_extensions import Self
+
+from pydantic import BaseModel, Field
+
+from zhenxun.services.ai.utils.logger import log_capability as logger
+from zhenxun.services.ai.utils.utils import parse_routing_string
+from zhenxun.utils.utils import infer_plugin_namespace
+
+from .base import AbstractCapability
+from .wrappers import DynamicCapability
+
+
+class CapabilityQuery(BaseModel):
+    """
+    拦截器/能力组件的声明式查询对象。
+    用于在 Agent 中精确或批量筛选加载特定命名空间、特定标签的能力。
+    """
+
+    name: str | list[str] | None = Field(default=None)
+    """如果提供，则能力的名称必须等于该字符串或在列表中。支持 * / ? 通配符。"""
+    tags: list[str] | None = Field(default=None)
+    """如果提供，则能力必须包含这里列出的所有标签 (交集/AND匹配)。"""
+    exclude_tags: list[str] | None = Field(default=None)
+    """如果提供，则能力不能包含这里列出的任何标签 (排斥过滤)。"""
+    namespace: str | None = Field(default=None)
+    """限制搜索的插件命名空间。如果不指定，将自动推导为调用者所在的插件；
+    'global' 将跨全插件搜索，'*' 代表所有插件。"""
+
+
+CapabilitySource = (
+    str | Callable | AbstractCapability | type[AbstractCapability] | CapabilityQuery
+)
+"""能力/拦截器来源
+
+支持字符串别名/标签、普通函数、Capability类或实例，以及声明式 Query 对象。
+"""
+
+
+@dataclass
+class CapabilityEntry:
+    """能力组件元数据载体"""
+
+    cls: type[AbstractCapability]
+    """能力类"""
+    name: str
+    """能力名称"""
+    namespace: str
+    """能力所在的命名空间"""
+    tags: list[str] = field(default_factory=list)
+    """能力标签列表"""
+    auto_apply: bool = False
+    """是否自动挂载该能力"""
+
+
+class CapabilityManager:
+    """能力组件全局注册与发现中心 (单例)"""
+
+    _instance: "CapabilityManager | None" = None
+    _entries: list[CapabilityEntry]
+
+    def __new__(cls) -> Self:
+        """单例模式：获取或创建全局唯一的能力管理器实例"""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._entries = []
+        return cast(Self, cls._instance)
+
+    def register(
+        self,
+        cls: type[AbstractCapability],
+        name: str,
+        namespace: str,
+        tags: list[str],
+        auto_apply: bool,
+    ) -> None:
+        """注册一个能力组件到管理器中"""
+        self._entries.append(
+            CapabilityEntry(
+                cls=cls,
+                name=name,
+                namespace=namespace,
+                tags=tags,
+                auto_apply=auto_apply,
+            )
+        )
+        tag_str = f" | Tags: {tags}" if tags else ""
+        logger.debug(
+            f"已注册 Capability: '{name}' -> Namespace: '{namespace}'{tag_str})"
+        )
+
+    def get_auto_apply_capabilities(self, namespace: str) -> list[AbstractCapability]:
+        """获取指定命名空间及其它全局命名空间下自动挂载的能力实例"""
+        instances = []
+        for entry in self._entries:
+            if entry.auto_apply and entry.namespace in ("global", namespace):
+                try:
+                    instances.append(entry.cls())
+                except Exception as e:
+                    logger.error(f"实例化自动装配能力 {entry.name} 失败: {e}")
+        return instances
+
+    def query_capabilities(
+        self, query: CapabilityQuery, default_namespace: str
+    ) -> list[AbstractCapability]:
+        """根据声明式查询条件筛选并实例化匹配的能力组件"""
+        matched = []
+        ns = query.namespace or default_namespace
+
+        for entry in self._entries:
+            if ns != "*" and entry.namespace != ns:
+                continue
+
+            if query.name:
+                names = [query.name] if isinstance(query.name, str) else query.name
+                name_matched = False
+                for pattern in names:
+                    if fnmatch.fnmatch(entry.name, pattern):
+                        name_matched = True
+                        break
+                if not name_matched:
+                    continue
+
+            if query.tags:
+                if not all(tag in entry.tags for tag in query.tags):
+                    continue
+
+            if query.exclude_tags:
+                if any(tag in entry.tags for tag in query.exclude_tags):
+                    continue
+
+            try:
+                matched.append(entry.cls())
+            except Exception as e:
+                logger.error(f"实例化能力 {entry.name} 失败: {e}")
+
+        return matched
+
+    def resolve_capabilities(
+        self, sources: list[Any], default_namespace: str
+    ) -> list[AbstractCapability]:
+        """解析多种类型的能力来源并实例化为能力组件列表"""
+        resolved = []
+        for source in sources:
+            if isinstance(source, AbstractCapability):
+                resolved.append(source)
+            elif callable(source) and not isinstance(source, type):
+                resolved.append(DynamicCapability(source))
+            elif isinstance(source, CapabilityQuery):
+                resolved.extend(self.query_capabilities(source, default_namespace))
+            elif isinstance(source, str):
+                s = cast(str, source)
+                parsed_args = parse_routing_string(s, default_namespace)
+                q = CapabilityQuery(**parsed_args)
+                resolved.extend(self.query_capabilities(q, default_namespace))
+            elif isinstance(source, type) and issubclass(source, AbstractCapability):
+                try:
+                    resolved.append(source())
+                except Exception as e:
+                    logger.error(f"实例化能力 {source.__name__} 失败: {e}")
+            else:
+                raise TypeError(f"不支持的 Capability 来源: {type(source)}")
+        return resolved
+
+
+capability_manager = CapabilityManager()
+
+
+def capability(
+    name: str | None = None,
+    tags: list[str] | None = None,
+    auto_apply: bool = False,
+    namespace: str | None = None,
+) -> Callable:
+    """
+    类装饰器：声明式地注册一个 Capability 到全局能力池中。
+    允许第三方插件通过字符串别名或标签进行引用，彻底解耦模块依赖。
+
+    参数:
+        name: 能力的名称，如果为None则默认使用类名。
+        tags: 能力的标签列表，用于分类或批量筛选。
+        auto_apply: 是否自动应用挂载该能力。
+        namespace: 能力的命名空间，如果为None则自动推导为调用者所在的插件。
+
+    返回:
+        Callable: 装饰器函数，用于包装 AbstractCapability 类。
+    """
+
+    def decorator(cls: type[AbstractCapability]):
+        """装饰器内部函数，实现类注册"""
+        final_name = name or cls.__name__
+        final_tags = tags or []
+        ns = (
+            namespace
+            if namespace is not None
+            else infer_plugin_namespace(default="global")
+        )
+        capability_manager.register(
+            cls, name=final_name, namespace=ns, tags=final_tags, auto_apply=auto_apply
+        )
+        return cls
+
+    return decorator

zhenxun/services/ai/capabilities/wrappers.py

@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING, Any
 from nonebot.utils import is_coroutine_callable
 
 from zhenxun.services.ai.core.messages import ChatRequest, ChatResponse
+from zhenxun.services.ai.core.models import LLMContext
 from zhenxun.services.ai.core.options import GenerationConfig
 
 from .base import (
@@ -20,7 +21,6 @@ from .base import (
 )
 
 if TYPE_CHECKING:
-    from zhenxun.services.ai.core.models import LLMContext
     from zhenxun.services.ai.run import AgentRunResult, RunContext
 
 
@@ -266,11 +266,6 @@ class DynamicCapability(AbstractCapability):
         """初始化动态能力"""
         self.capability_func = capability_func
 
-    @classmethod
-    def get_serialization_name(cls) -> str | None:
-        """获取反序列化标识"""
-        return None
-
     async def for_run(self, context: RunContext) -> "AbstractCapability":
         """在运行时基于当前上下文动态实例化并执行真正的 Capability"""
         if is_coroutine_callable(self.capability_func):
@@ -292,11 +287,6 @@ class WrapperCapability(AbstractCapability):
         """初始化代理包装器"""
         self.wrapped = wrapped
 
-    @classmethod
-    def get_serialization_name(cls) -> str | None:
-        """获取反序列化标识"""
-        return None
-
     async def for_run(self, context: RunContext) -> "AbstractCapability":
         """对内部包裹的实例执行运行时解析并深度克隆"""
         new_wrapped = await self.wrapped.for_run(context)