♻️ 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>
2026-10-20 03:30:11 +08:00 · 2026-07-10 09:14:06 +08:00
parent 0b32d69c9c
commit 922d092650
132 changed files with 2372 additions and 1972 deletions
@@ -10,69 +10,66 @@ from __future__ import annotations
 from collections.abc import Awaitable, Callable, Coroutine
 from datetime import datetime
 import inspect
+import json
 from typing import Any, ClassVar
 import uuid

-from arclet.alconna import Alconna, Option
+from arclet.alconna import Alconna
 import nonebot
 from nonebot.adapters import Bot
-from pydantic import BaseModel
+from pydantic import BaseModel, ValidationError

 from zhenxun.configs.config import Config
 from zhenxun.models.scheduled_job import ScheduledJob
 from zhenxun.services.log import logger
-from zhenxun.utils.pydantic_compat import model_dump, model_validate
+from zhenxun.utils.pydantic_compat import dump_json_safely, model_dump, model_validate

-from .engine import APSchedulerAdapter
+from .engine import APSchedulerAdapter, _execute_persistent_job
+from .registry import scheduler_registry
 from .repository import ScheduleRepository
 from .targeting import (
    ScheduleTargeter,
+    _resolve_all_groups,
+    _resolve_global_or_user,
+    _resolve_group,
+    _resolve_tag,
+    _resolve_user,
 )
 from .types import (
    BaseTrigger,
    EphemeralJobDeclaration,
-    ExecutionOptions,
    ExecutionPolicy,
+    JobConfig,
    ScheduleContext,
    ScheduledJobDeclaration,
+    TargetType,
+    Trigger,
 )


 class SchedulerManager:
-    ALL_GROUPS: ClassVar[str] = "__ALL_GROUPS__"
-    _registered_tasks: ClassVar[
-        dict[
-            str,
-            dict[str, Callable | type[BaseModel] | int | list[Option] | Alconna | None],
-        ]
-    ] = {}
-    _declared_tasks: ClassVar[list[ScheduledJobDeclaration]] = []
-    _ephemeral_declared_tasks: ClassVar[list[EphemeralJobDeclaration]] = []
-    _running_tasks: ClassVar[set] = set()
-    _target_resolvers: ClassVar[
-        dict[str, Callable[[str, Bot], Awaitable[list[str | None]]]]
-    ] = {}
+    ALL_GROUPS: ClassVar[str] = scheduler_registry.ALL_GROUPS

    def __init__(self):
        self._register_builtin_resolvers()

    def _register_builtin_resolvers(self):
        """在管理器初始化时注册所有内置的目标解析器。"""
-        from .targeting import (
-            _resolve_all_groups,
-            _resolve_global_or_user,
-            _resolve_group,
-            _resolve_tag,
-            _resolve_user,
-        )
-
-        if "GROUP" in self._target_resolvers:
+        if TargetType.GROUP.value in scheduler_registry.target_resolvers:
            return
-        self.register_target_resolver("GROUP", _resolve_group)
-        self.register_target_resolver("TAG", _resolve_tag)
-        self.register_target_resolver("ALL_GROUPS", _resolve_all_groups)
-        self.register_target_resolver("GLOBAL", _resolve_global_or_user)
-        self.register_target_resolver("USER", _resolve_user)
+        scheduler_registry.register_target_resolver(
+            TargetType.GROUP.value, _resolve_group
+        )
+        scheduler_registry.register_target_resolver(TargetType.TAG.value, _resolve_tag)
+        scheduler_registry.register_target_resolver(
+            TargetType.ALL_GROUPS.value, _resolve_all_groups
+        )
+        scheduler_registry.register_target_resolver(
+            TargetType.GLOBAL.value, _resolve_global_or_user
+        )
+        scheduler_registry.register_target_resolver(
+            TargetType.USER.value, _resolve_user
+        )
        logger.debug("已注册所有内置的定时任务目标解析器。")

    def register_target_resolver(
@@ -83,20 +80,14 @@ class SchedulerManager:
        """
        注册一个新的目标类型解析器。
        """
-        if target_type in self._target_resolvers:
+        if target_type in scheduler_registry.target_resolvers:
            logger.warning(f"目标解析器 '{target_type}' 已存在，将被覆盖。")
-        self._target_resolvers[target_type.upper()] = resolver_func
-        logger.info(f"已注册新的定时任务目标解析器: '{target_type}'")
+        scheduler_registry.register_target_resolver(target_type, resolver_func)
+        logger.debug(f"已注册新的定时任务目标解析器: '{target_type}'")

    def target(self, **filters: Any) -> ScheduleTargeter:
        """
        创建目标选择器以执行批量操作
-
-        参数:
-            **filters: 过滤条件，支持plugin_name、group_id、bot_id等字段。
-
-        返回:
-            ScheduleTargeter: 目标选择器对象，可用于批量操作。
        """
        return ScheduleTargeter(self, **filters)

@@ -112,7 +103,20 @@ class SchedulerManager:
        default_interval: int | None = None,
    ):
        """
-        声明式定时任务的统一装饰器。
+        声明式定时任务的统一装饰器
+
+        参数:
+            trigger: 定时触发器配置。
+            group_id: 默认目标群号，如果不指定则为全局任务。
+            bot_id: 执行此任务时应优先匹配的 Bot 标识符。
+            default_params: 任务函数的默认参数模型实例。
+            policy: 执行和重试策略配置。
+            default_jitter: 默认抖动延迟时间（秒）。
+            default_spread: 默认并发散列随机延迟打散的最大延迟范围（秒）。
+            default_interval: 默认串行派发任务时的固定等待间隔（秒）。
+
+        返回:
+            Callable: 装饰器函数，用于包裹并注册声明式任务。
        """

        def decorator(func: Callable[..., Coroutine]) -> Callable[..., Coroutine]:
@@ -123,7 +127,6 @@ class SchedulerManager:
                plugin_name = plugin.name

                params_model = None
-                from .types import ScheduleContext

                for param in inspect.signature(func).parameters.values():
                    if (
@@ -134,9 +137,9 @@ class SchedulerManager:
                        params_model = param.annotation
                        break

-                if plugin_name in self._registered_tasks:
+                if plugin_name in scheduler_registry.tasks:
                    logger.warning(f"插件 '{plugin_name}' 的定时任务已被重复注册。")
-                self._registered_tasks[plugin_name] = {
+                scheduler_registry.tasks[plugin_name] = {
                    "func": func,
                    "model": params_model,
                    "default_jitter": default_jitter,
@@ -155,7 +158,7 @@ class SchedulerManager:
                    trigger=trigger,
                    job_kwargs=job_kwargs,
                )
-                self._declared_tasks.append(task_declaration)
+                scheduler_registry.persistent_declarations.append(task_declaration)
                logger.debug(
                    f"发现声明式定时任务 '{plugin_name}'，将在启动时进行注册。"
                )
@@ -178,7 +181,9 @@ class SchedulerManager:
                    raise ValueError(f"函数 {func.__name__} 不在任何已加载的插件中。")
                plugin_name = plugin.name

-                self._registered_tasks[f"ephemeral::{plugin_name}::{func.__name__}"] = {
+                scheduler_registry.tasks[
+                    f"ephemeral::{plugin_name}::{func.__name__}"
+                ] = {
                    "func": func,
                    "model": None,
                }
@@ -188,7 +193,7 @@ class SchedulerManager:
                    func=func,
                    trigger=trigger,
                )
-                self._ephemeral_declared_tasks.append(declaration)
+                scheduler_registry.ephemeral_declarations.append(declaration)
                logger.debug(
                    f"发现临时定时任务 '{plugin_name}:{func.__name__}'，将在启动时调度"
                )
@@ -211,12 +216,24 @@ class SchedulerManager:
    ) -> Callable:
        """
        注册可调度的任务函数
+
+        参数:
+            plugin_name: 插件名称。
+            params_model: 参数的模型定义，如为 None 则任务不接收额外参数。
+            cli_parser: 用于解析命令行参数的 Alconna 解析器。
+            default_permission: 运行此定时任务所需的默认权限等级。
+            default_jitter: 默认抖动延迟时间（秒）。
+            default_spread: 默认并发散列随机延迟打散的最大延迟范围（秒）。
+            default_interval: 默认串行派发任务时的固定等待间隔（秒）。
+
+        返回:
+            Callable: 装饰器函数，用于包裹并注册任务。
        """

        def decorator(func: Callable[..., Coroutine]) -> Callable[..., Coroutine]:
-            if plugin_name in self._registered_tasks:
+            if plugin_name in scheduler_registry.tasks:
                logger.warning(f"插件 '{plugin_name}' 的定时任务已被重复注册。")
-            self._registered_tasks[plugin_name] = {
+            scheduler_registry.tasks[plugin_name] = {
                "func": func,
                "model": params_model,
                "cli_parser": cli_parser,
@@ -237,7 +254,7 @@ class SchedulerManager:
        """
        获取已注册插件列表
        """
-        return list(self._registered_tasks.keys())
+        return list(scheduler_registry.tasks.keys())

    async def run_at(self, func: Callable[..., Coroutine], trigger: BaseTrigger) -> str:
        """
@@ -252,14 +269,18 @@ class SchedulerManager:
            bot_id=None,
            platform_scope=None,
            group_id=None,
+            user_id=None,
            job_kwargs={},
        )

+        trigger_config_dict = json.loads(dump_json_safely(trigger))
+        trigger_config_dict.pop("trigger_type", None)
+
        APSchedulerAdapter.add_ephemeral_job(
            job_id=job_id,
            func=func,
            trigger_type=trigger.trigger_type,
-            trigger_config=model_dump(trigger, exclude={"trigger_type"}),
+            trigger_config=trigger_config_dict,
            context=context,
        )
        logger.info(f"已动态调度一个临时任务 (ID: {job_id})，将在 {trigger} 触发。")
@@ -279,26 +300,40 @@ class SchedulerManager:
        required_permission: int = 5,
    ) -> "ScheduledJob | None":
        """
-        编程式API，用于动态调度一个持久化的、一次性的任务。
+        编程式API，用于动态调度一个持久化的、一次性的任务
+
+        参数:
+            func: 待执行的协程函数。
+            trigger: 定时触发器配置。
+            user_id: 目标用户 ID，与 group_id 互斥。
+            group_id: 目标群号，与 user_id 互斥。
+            bot_id: 指定运行此任务的 Bot 标识符。
+            job_kwargs: 传递给任务函数的实际参数字典。
+            name: 任务的可读别名。
+            created_by: 任务创建者的标识。
+            required_permission: 运行该任务需要的最低权限等级。
+
+        返回:
+            ScheduledJob | None: 持久化定时任务的数据模型实例，如果失败则返回 None。
        """
        if user_id and group_id:
            raise ValueError("user_id 和 group_id 不能同时提供。")

        temp_plugin_name = f"runtime_one_off__{func.__module__}.{func.__name__}__{uuid.uuid4().hex[:8]}"  # noqa: E501

-        self._registered_tasks[temp_plugin_name] = {"func": func, "model": None}
+        scheduler_registry.tasks[temp_plugin_name] = {"func": func, "model": None}
        logger.debug(f"为一次性任务动态注册临时插件: '{temp_plugin_name}'")

-        target_type = "USER" if user_id else ("GROUP" if group_id else "GLOBAL")
+        target_type = (
+            TargetType.USER.value
+            if user_id
+            else (TargetType.GROUP.value if group_id else TargetType.GLOBAL.value)
+        )
        target_identifier = user_id or group_id or ""

-        return await self.add_schedule(
-            plugin_name=temp_plugin_name,
-            target_type=target_type,
-            target_identifier=target_identifier,
-            trigger_type=trigger.trigger_type,
-            trigger_config=model_dump(trigger, exclude={"trigger_type"}),
-            job_kwargs=job_kwargs,
+        config = JobConfig(
+            trigger=trigger,
+            job_kwargs=job_kwargs or {},
            bot_id=bot_id,
            name=name,
            created_by=created_by,
@@ -306,6 +341,13 @@ class SchedulerManager:
            is_one_off=True,
        )

+        return await self.add_schedule(
+            plugin_name=temp_plugin_name,
+            target_type=target_type,
+            target_identifier=target_identifier,
+            config=config,
+        )
+
    async def add_daily_task(
        self,
        plugin_name: str,
@@ -318,6 +360,18 @@ class SchedulerManager:
    ) -> "ScheduledJob | None":
        """
        添加每日定时任务
+
+        参数:
+            plugin_name: 插件名称。
+            group_id: 目标群号，如果不指定则为全局任务。
+            hour: 触发的小时数（0-23）。
+            minute: 触发的分钟数（0-59）。
+            second: 触发的秒数（0-59）。
+            job_kwargs: 传递给任务函数的参数字典。
+            bot_id: 运行此任务的首选 Bot。
+
+        返回:
+            ScheduledJob | None: 定时任务的数据模型对象，如果失败则返回 None。
        """
        trigger_config = {
            "hour": hour,
@@ -325,14 +379,15 @@ class SchedulerManager:
            "second": second,
            "timezone": Config.get_config("SchedulerManager", "SCHEDULER_TIMEZONE"),
        }
+
+        trigger = Trigger.cron(**trigger_config)
        return await self.add_schedule(
            plugin_name,
-            target_type="GROUP" if group_id else "GLOBAL",
+            target_type=TargetType.GROUP.value if group_id else TargetType.GLOBAL.value,
            target_identifier=group_id or "",
-            trigger_type="cron",
-            trigger_config=trigger_config,
-            job_kwargs=job_kwargs,
-            bot_id=bot_id,
+            config=JobConfig(
+                trigger=trigger, job_kwargs=job_kwargs or {}, bot_id=bot_id
+            ),
        )

    async def add_interval_task(
@@ -351,6 +406,21 @@ class SchedulerManager:
    ) -> "ScheduledJob | None":
        """
        添加间隔性定时任务
+
+        参数:
+            plugin_name: 插件名称。
+            group_id: 目标群号，如果不指定则为全局任务。
+            weeks: 间隔的周数。
+            days: 间隔的天数。
+            hours: 间隔的小时数。
+            minutes: 间隔的分钟数。
+            seconds: 间隔的秒数。
+            start_date: 间隔计算的起始时间。
+            job_kwargs: 传递给任务函数的参数字典。
+            bot_id: 运行此任务的首选 Bot。
+
+        返回:
+            ScheduledJob | None: 定时任务的数据模型对象，如果失败则返回 None。
        """
        trigger_config = {
            "weeks": weeks,
@@ -361,23 +431,22 @@ class SchedulerManager:
            "start_date": start_date,
        }
        trigger_config = {k: v for k, v in trigger_config.items() if v}
+
+        trigger = Trigger.interval(**trigger_config)
        return await self.add_schedule(
            plugin_name,
-            target_type="GROUP" if group_id else "GLOBAL",
+            target_type=TargetType.GROUP.value if group_id else TargetType.GLOBAL.value,
            target_identifier=group_id or "",
-            trigger_type="interval",
-            trigger_config=trigger_config,
-            job_kwargs=job_kwargs,
-            bot_id=bot_id,
+            config=JobConfig(
+                trigger=trigger, job_kwargs=job_kwargs or {}, bot_id=bot_id
+            ),
        )

    def _validate_and_prepare_kwargs(
        self, plugin_name: str, job_kwargs: dict | None
    ) -> tuple[bool, str | dict]:
        """验证并准备任务参数，应用默认值"""
-        from pydantic import ValidationError
-
-        task_meta = self._registered_tasks.get(plugin_name)
+        task_meta = scheduler_registry.tasks.get(plugin_name)
        if not task_meta:
            return False, f"插件 '{plugin_name}' 未注册。"

@@ -410,17 +479,7 @@ class SchedulerManager:
        plugin_name: str,
        target_type: str,
        target_identifier: str,
-        trigger_type: str,
-        trigger_config: dict,
-        job_kwargs: dict | None = None,
-        bot_id: str | None = None,
-        *,
-        name: str | None = None,
-        created_by: str | None = None,
-        required_permission: int = 5,
-        source: str = "USER",
-        is_one_off: bool = False,
-        execution_options: dict | None = None,
+        config: JobConfig,
    ) -> "ScheduledJob | None":
        """
        添加定时任务（通用方法）
@@ -429,51 +488,43 @@ class SchedulerManager:
            plugin_name: 插件名称。
            target_type: 目标类型 (GROUP, USER, TAG, ALL_GROUPS, GLOBAL)。
            target_identifier: 目标标识符。
-            trigger_type: 触发器类型 (cron, interval, date)。
-            trigger_config: 触发器配置字典。
-            job_kwargs: 传递给任务函数的额外参数。
-            bot_id: Bot ID约束。
-            name: 任务别名。
-            created_by: 创建者ID。
-            required_permission: 管理此任务所需的权限。
-            source: 任务来源 (USER, PLUGIN_DEFAULT)。
-            is_one_off: 是否为一次性任务。
-            execution_options: 任务执行的额外选项 (例如: jitter, spread)。
-
-        返回:
-            ScheduledJob | None: 创建的任务信息，失败时返回None。
+            config: JobConfig 参数配置聚合对象。
        """
-        if plugin_name not in self._registered_tasks:
+        if plugin_name not in scheduler_registry.tasks:
            logger.error(f"插件 '{plugin_name}' 没有注册可用的定时任务。")
            return None

-        is_valid, result = self._validate_and_prepare_kwargs(plugin_name, job_kwargs)
+        is_valid, result = self._validate_and_prepare_kwargs(
+            plugin_name, config.job_kwargs
+        )
        if not is_valid:
            logger.error(f"任务参数校验失败: {result}")
            return None

-        options_dict = execution_options or {}
-        validated_options = ExecutionOptions(**options_dict)
-
        search_kwargs = {
            "plugin_name": plugin_name,
            "target_type": target_type,
            "target_identifier": target_identifier,
        }
-        if bot_id:
-            search_kwargs["bot_id"] = bot_id
+        if config.bot_id:
+            search_kwargs["bot_id"] = config.bot_id
+
+        trigger_config_dict = json.loads(dump_json_safely(config.trigger))
+        trigger_config_dict.pop("trigger_type", None)

        defaults = {
-            "name": name,
-            "trigger_type": trigger_type,
-            "trigger_config": trigger_config,
+            "name": config.name,
+            "trigger_type": config.trigger.trigger_type,
+            "trigger_config": trigger_config_dict,
            "job_kwargs": result,
            "is_enabled": True,
-            "created_by": created_by,
-            "required_permission": required_permission,
-            "source": source,
-            "is_one_off": is_one_off,
-            "execution_options": model_dump(validated_options, exclude_none=True),
+            "created_by": config.created_by,
+            "required_permission": config.required_permission,
+            "source": config.source,
+            "is_one_off": config.is_one_off,
+            "execution_options": model_dump(
+                config.execution_options, exclude_none=True
+            ),
        }

        defaults = {k: v for k, v in defaults.items() if v is not None}
@@ -485,7 +536,7 @@ class SchedulerManager:

        action_str = "创建" if created else "更新"
        logger.info(
-            f"已成功{action_str}任务 '{name or plugin_name}' (ID: {schedule.id})"
+            f"已成功{action_str}任务 '{config.name or plugin_name}' (ID: {schedule.id})"
        )
        return schedule

@@ -494,7 +545,15 @@ class SchedulerManager:
    ) -> tuple[list[ScheduledJob], int]:
        """
        根据条件获取定时任务列表
-        """
+
+        参数:
+            page: 分页页码，从 1 开始。
+            page_size: 每页的任务数量。
+            **filters: 过滤条件，支持 plugin_name, target_type, is_enabled 等字段。
+
+        返回:
+            tuple[list[ScheduledJob], int]: 包含任务对象列表和总符合条件的任务数量的元组。
+        """  # noqa: E501
        cleaned_filters = {k: v for k, v in filters.items() if v is not None}
        return await ScheduleRepository.query_schedules(
            page=page, page_size=page_size, **cleaned_filters
@@ -523,7 +582,7 @@ class SchedulerManager:
                status_dict.update(status_from_scheduler)
                status_dict["is_enabled"] = (
                    "运行中"
-                    if schedule_id in self._running_tasks
+                    if schedule_id in scheduler_registry.running_tasks
                    else ("启用" if schedule.is_enabled else "暂停")
                )
                statuses.append(status_dict)
@@ -539,6 +598,15 @@ class SchedulerManager:
    ) -> tuple[bool, str]:
        """
        更新定时任务配置
+
+        参数:
+            schedule_id: 定时任务的ID。
+            trigger_type: 触发器类型，例如 'cron' 或 'interval'。
+            trigger_config: 触发器配置字典。
+            job_kwargs: 更新后的任务参数字典。
+
+        返回:
+            tuple[bool, str]: 包含执行结果（成功为 True）和对应状态消息的元组。
        """
        schedule = await ScheduleRepository.get_by_id(schedule_id)
        if not schedule:
@@ -589,7 +657,7 @@ class SchedulerManager:

        status_text = (
            "运行中"
-            if schedule_id in self._running_tasks
+            if schedule_id in scheduler_registry.running_tasks
            else ("启用" if schedule.is_enabled else "暂停")
        )

@@ -636,16 +704,14 @@ class SchedulerManager:
        """
        立即手动触发指定的定时任务
        """
-        from .engine import _execute_job
-
        schedule = await ScheduleRepository.get_by_id(schedule_id)
        if not schedule:
            return False, f"未找到 ID 为 {schedule_id} 的定时任务。"
-        if schedule.plugin_name not in self._registered_tasks:
+        if schedule.plugin_name not in scheduler_registry.tasks:
            return False, f"插件 '{schedule.plugin_name}' 没有注册可用的定时任务。"

        try:
-            await _execute_job(schedule.id, force=True)
+            await _execute_persistent_job(schedule.id, force=True)
            return True, f"已手动触发任务 (ID: {schedule.id})。"
        except Exception as e:
            logger.error(f"手动触发任务失败: {e}")
@@ -654,12 +720,6 @@ class SchedulerManager:
    async def get_schedule_by_id(self, schedule_id: int) -> "ScheduledJob | None":
        """
        通过ID获取任务对象的公共方法。
-
-        参数:
-            schedule_id: 任务ID。
-
-        返回:
-            ScheduledJob | None: 任务对象，不存在时返回None。
        """
        return await ScheduleRepository.get_by_id(schedule_id)