♻️ 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-10 22:30:02 +08:00 · 2026-07-10 09:14:06 +08:00
parent 0b32d69c9c
commit 922d092650
132 changed files with 2372 additions and 1972 deletions
@@ -6,7 +6,14 @@ from zhenxun.models.level_user import LevelUser
 from zhenxun.models.scheduled_job import ScheduledJob
 from zhenxun.services import scheduler_manager
 from zhenxun.services.log import logger
+from zhenxun.services.scheduler.registry import scheduler_registry
 from zhenxun.services.scheduler.repository import ScheduleRepository
+from zhenxun.services.scheduler.types import (
+    BaseTrigger,
+    ExecutionOptions,
+    JobConfig,
+    TargetType,
+)
 from zhenxun.utils.pydantic_compat import model_dump, model_validate

 from . import presenters
@@ -58,7 +65,7 @@ class SchedulerAdminService:
        targets: list[str],
        creator_permission_level: int,
        plugin_name: str,
-        trigger_info: tuple[str, dict],
+        trigger: BaseTrigger,
        job_kwargs: dict,
        permission: int,
        bot_id: str,
@@ -69,7 +76,6 @@ class SchedulerAdminService:
        created_by: str,
    ) -> str:
        """创建或更新一个定时任务"""
-        trigger_type, trigger_config = trigger_info
        success_targets = []
        failed_targets = []
        permission_denied_targets = []
@@ -103,7 +109,7 @@ class SchedulerAdminService:
                )
                continue

-            if target_type in ["TAG", "ALL_GROUPS"]:
+            if target_type in [TargetType.TAG.value, TargetType.ALL_GROUPS.value]:
                logger.debug(
                    f"检测到多目标任务 (类型: {target_type})，"
                    f"将所需权限强制提升至超级用户级别。"
@@ -111,18 +117,26 @@ class SchedulerAdminService:
                permission = 9

            try:
+                exec_opts = (
+                    model_validate(ExecutionOptions, execution_options)
+                    if execution_options
+                    else model_validate(ExecutionOptions, {})
+                )
+
+                config = JobConfig(
+                    trigger=trigger,
+                    job_kwargs=job_kwargs,
+                    bot_id=bot_id,
+                    name=job_name,
+                    created_by=created_by,
+                    required_permission=permission,
+                    execution_options=exec_opts,
+                )
                schedule = await scheduler_manager.add_schedule(
                    plugin_name=plugin_name,
                    target_type=target_type,
                    target_identifier=target_id,
-                    trigger_type=trigger_type,
-                    trigger_config=trigger_config,
-                    job_kwargs=job_kwargs,
-                    bot_id=bot_id,
-                    required_permission=permission,
-                    name=job_name,
-                    created_by=created_by,
-                    execution_options=execution_options if execution_options else None,
+                    config=config,
                )
                if schedule:
                    success_targets.append((target_desc, schedule.id))
@@ -150,7 +164,10 @@ class SchedulerAdminService:
            permission_denied = False
            if all_flag or global_flag:
                permission_denied = True
-            elif targeter._filters.get("target_type") in ["TAG", "ALL_GROUPS"]:
+            elif targeter._filters.get("target_type") in [
+                TargetType.TAG.value,
+                TargetType.ALL_GROUPS.value,
+            ]:
                permission_denied = True

            if permission_denied:
@@ -202,11 +219,16 @@ class SchedulerAdminService:
        )

    async def update_schedule(
-        self, schedule: ScheduledJob, trigger_info: tuple | None, kwargs_str: str | None
+        self,
+        schedule: ScheduledJob,
+        trigger: BaseTrigger | None,
+        kwargs_str: str | None,
    ) -> str:
        """更新一个任务的配置"""
-        trigger_type = trigger_info[0] if trigger_info else None
-        trigger_config = trigger_info[1] if trigger_info else None
+        trigger_type = trigger.trigger_type if trigger else None
+        trigger_config = (
+            model_dump(trigger, exclude={"trigger_type"}) if trigger else None
+        )
        job_kwargs = await self._parse_and_validate_kwargs_for_update(
            schedule.plugin_name, kwargs_str
        )
@@ -243,7 +265,7 @@ class SchedulerAdminService:

    def _generate_view_title(self, filters: dict) -> str:
        title = "定时任务"
-        if filters.get("target_type") == "ALL_GROUPS":
+        if filters.get("target_type") == TargetType.ALL_GROUPS.value:
            title = "全局定时任务"
        elif "target_identifier" in filters:
            title = f"群 {filters['target_identifier']} 的定时任务"
@@ -253,12 +275,12 @@ class SchedulerAdminService:

    def _resolve_target_descriptor(self, target_desc: str) -> tuple[str, str]:
        if target_desc == scheduler_manager.ALL_GROUPS:
-            return "ALL_GROUPS", scheduler_manager.ALL_GROUPS
+            return TargetType.ALL_GROUPS.value, scheduler_manager.ALL_GROUPS
        if target_desc.startswith("tag:"):
-            return "TAG", target_desc[4:]
+            return TargetType.TAG.value, target_desc[4:]
        if target_desc.isdigit():
-            return "GROUP", target_desc
-        return "USER", target_desc
+            return TargetType.GROUP.value, target_desc
+        return TargetType.USER.value, target_desc

    def _format_set_result_message(
        self, targets: list, success: list, failed: list, permission_denied: list
@@ -286,7 +308,7 @@ class SchedulerAdminService:
        if not kwargs_str:
            return {}

-        task_meta = scheduler_manager._registered_tasks.get(plugin_name)
+        task_meta = scheduler_registry.tasks.get(plugin_name)
        if not task_meta:
            raise ValueError(f"插件 '{plugin_name}' 未注册。")

@@ -22,6 +22,8 @@ from zhenxun.configs.config import Config
 from zhenxun.models.level_user import LevelUser
 from zhenxun.models.scheduled_job import ScheduledJob
 from zhenxun.services import scheduler_manager
+from zhenxun.services.scheduler.registry import scheduler_registry
+from zhenxun.services.scheduler.types import BaseTrigger, TargetType, Trigger
 from zhenxun.utils.time_utils import TimeUtils


@@ -103,7 +105,7 @@ def parse_daily_time(time_str: str) -> dict:
        raise ValueError("时间格式错误，请使用 'HH:MM' 或 'HH:MM:SS' 格式。")


-def _parse_trigger_from_arparma(arp: Arparma) -> tuple[str, dict] | None:
+def _parse_trigger_from_arparma(arp: Arparma) -> BaseTrigger | None:
    """从 Arparma 中解析时间触发器配置"""
    subcommand_name = next(iter(arp.subcommands.keys()), None)
    if not subcommand_name:
@@ -111,19 +113,22 @@ def _parse_trigger_from_arparma(arp: Arparma) -> tuple[str, dict] | None:

    try:
        if cron_expr := arp.query[str](f"{subcommand_name}.cron.cron_expr", None):
-            return "cron", dict(
-                zip(
-                    ["minute", "hour", "day", "month", "day_of_week"], cron_expr.split()
+            return Trigger.cron(
+                **dict(
+                    zip(
+                        ["minute", "hour", "day", "month", "day_of_week"],
+                        cron_expr.split(),
+                    )
                )
            )
        if interval_expr := arp.query[str](
            f"{subcommand_name}.interval.interval_expr", None
        ):
-            return "interval", TimeUtils.parse_interval_to_dict(interval_expr)
+            return Trigger.interval(**TimeUtils.parse_interval_to_dict(interval_expr))
        if date_expr := arp.query[str](f"{subcommand_name}.date.date_expr", None):
-            return "date", {"run_date": datetime.fromisoformat(date_expr)}
+            return Trigger.date(run_date=datetime.fromisoformat(date_expr))
        if daily_expr := arp.query[str](f"{subcommand_name}.daily.daily_expr", None):
-            return "cron", parse_daily_time(daily_expr)
+            return Trigger.cron(**parse_daily_time(daily_expr))
    except ValueError as e:
        raise ValueError(f"时间参数解析错误: {e}") from e
    return None
@@ -132,12 +137,12 @@ def _parse_trigger_from_arparma(arp: Arparma) -> tuple[str, dict] | None:
 async def GetTriggerInfo(
    matcher: AlconnaMatcher,
    arp: Arparma = AlconnaMatches(),
-) -> tuple[str, dict]:
+) -> BaseTrigger:
    """依赖注入函数：解析并验证时间触发器"""
    try:
-        trigger_info = _parse_trigger_from_arparma(arp)
-        if trigger_info:
-            return trigger_info
+        trigger = _parse_trigger_from_arparma(arp)
+        if trigger:
+            return trigger
    except ValueError as e:
        await matcher.finish(f"时间参数解析错误: {e}")

@@ -199,24 +204,24 @@ async def GetTargeter(
        filters["plugin_name"] = plugin_name.result

    if global_flag:
-        filters["target_type"] = "ALL_GROUPS"
+        filters["target_type"] = TargetType.ALL_GROUPS.value
        filters["target_identifier"] = scheduler_manager.ALL_GROUPS
    elif user_id.available:
-        filters["target_type"] = "USER"
+        filters["target_type"] = TargetType.USER.value
        filters["target_identifier"] = user_id.result
    elif all_enabled:
        pass
    elif tag_name.available:
-        filters["target_type"] = "TAG"
+        filters["target_type"] = TargetType.TAG.value
        filters["target_identifier"] = tag_name.result
    elif group_ids.available:
        gids = [str(gid) for gid in group_ids.result]
-        filters["target_type"] = "GROUP"
+        filters["target_type"] = TargetType.GROUP.value
        filters["target_identifier__in"] = gids
    else:
        current_group_id = getattr(event, "group_id", None)
        if current_group_id:
-            filters["target_type"] = "GROUP"
+            filters["target_type"] = TargetType.GROUP.value
            filters["target_identifier"] = str(current_group_id)

    return scheduler_manager.target(**filters)
@@ -230,7 +235,7 @@ async def GetValidatedJobKwargs(
 ) -> dict:
    """依赖注入函数：解析、合并和验证任务的关键字参数"""
    p_name = plugin_name.result
-    task_meta = scheduler_manager._registered_tasks.get(p_name)
+    task_meta = scheduler_registry.tasks.get(p_name)
    if not task_meta:
        await matcher.finish(f"插件 '{p_name}' 未注册可定时执行的任务。")

@@ -311,7 +316,7 @@ async def GetFinalPermission(

    else:
        base_permission = effective_user_level
-        task_meta = scheduler_manager._registered_tasks.get(plugin_name.result)
+        task_meta = scheduler_registry.tasks.get(plugin_name.result)
        if task_meta and "default_permission" in task_meta:
            default_perm = task_meta.get("default_permission")
            if isinstance(default_perm, int):
@@ -16,6 +16,8 @@ from nonebot_plugin_uninfo import Uninfo
 from zhenxun.configs.config import Config
 from zhenxun.models.scheduled_job import ScheduledJob
 from zhenxun.services import scheduler_manager
+from zhenxun.services.scheduler.registry import scheduler_registry
+from zhenxun.services.scheduler.types import BaseTrigger
 from zhenxun.utils.message import MessageUtils

 from .commands import schedule_cmd
@@ -66,7 +68,7 @@ async def handle_set(
    interval: Match[int] = AlconnaMatch("interval_seconds"),
    job_name: Match[str] = AlconnaMatch("job_name"),
    bot_id_to_operate: str = Depends(GetBotId),
-    trigger_info: tuple[str, dict] = Depends(GetTriggerInfo),
+    trigger: BaseTrigger = Depends(GetTriggerInfo),
    job_kwargs: dict = Depends(GetValidatedJobKwargs),
    creator_permission_level: int = Depends(GetCreatorPermissionLevel),
    final_permission: int = Depends(GetFinalPermission),
@@ -86,7 +88,7 @@ async def handle_set(
    )

    if is_multi_target:
-        task_meta = scheduler_manager._registered_tasks.get(p_name)
+        task_meta = scheduler_registry.tasks.get(p_name)
        if jitter_val is None:
            if task_meta and task_meta.get("default_jitter") is not None:
                jitter_val = cast(int | None, task_meta["default_jitter"])
@@ -114,7 +116,7 @@ async def handle_set(
        targets=target_groups,
        creator_permission_level=creator_permission_level,
        plugin_name=p_name,
-        trigger_info=trigger_info,
+        trigger=trigger,
        job_kwargs=job_kwargs,
        permission=final_permission,
        bot_id=bot_id_to_operate,
@@ -210,14 +212,14 @@ async def handle_update(
    kwargs_str: Match[str] = AlconnaMatch("kwargs_str"),
 ):
    """处理 '更新' 子命令"""
-    trigger_info = _parse_trigger_from_arparma(arp)
-    if not trigger_info and not kwargs_str.available:
+    trigger = _parse_trigger_from_arparma(arp)
+    if not trigger and not kwargs_str.available:
        await schedule_cmd.finish(
            "请提供需要更新的时间 (--cron/--interval/--date/--daily) 或参数 (--kwargs)"
        )

    result_message = await scheduler_admin_service.update_schedule(
-        schedule, trigger_info, kwargs_str.result if kwargs_str.available else None
+        schedule, trigger, kwargs_str.result if kwargs_str.available else None
    )
    await schedule_cmd.finish(result_message)

@@ -3,6 +3,8 @@ from typing import Any
 from zhenxun import ui
 from zhenxun.models.scheduled_job import ScheduledJob
 from zhenxun.services import scheduler_manager
+from zhenxun.services.scheduler.registry import scheduler_registry
+from zhenxun.services.scheduler.types import TargetType
 from zhenxun.ui.models import StatusBadgeCell, TextCell
 from zhenxun.utils.pydantic_compat import model_json_schema

@@ -173,15 +175,15 @@ async def format_schedule_list_as_image(

 def format_target_info(target_type: str, target_identifier: str) -> str:
    """格式化目标信息以供显示"""
-    if target_type == "GLOBAL":
+    if target_type == TargetType.GLOBAL.value:
        return "全局"
-    elif target_type == "ALL_GROUPS":
+    elif target_type == TargetType.ALL_GROUPS.value:
        return "所有群组"
-    elif target_type == "TAG":
+    elif target_type == TargetType.TAG.value:
        return f"标签: {target_identifier}"
-    elif target_type == "GROUP":
+    elif target_type == TargetType.GROUP.value:
        return f"群: {target_identifier}"
-    elif target_type == "USER":
+    elif target_type == TargetType.USER.value:
        return f"用户: {target_identifier}"
    else:
        return f"{target_type}: {target_identifier}"
@@ -215,7 +217,7 @@ async def format_plugins_list() -> str:

    message_parts = ["📋 已注册的定时任务插件:"]
    for i, plugin_name in enumerate(registered_plugins, 1):
-        task_meta = scheduler_manager._registered_tasks[plugin_name]
+        task_meta = scheduler_registry.tasks[plugin_name]
        params_model = task_meta.get("model")

        param_info_str = "无参数"