♻️ 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/sandbox/addons/base.py

@@ -3,7 +3,7 @@ from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 from typing import TYPE_CHECKING, Any
 
-from zhenxun.services.log import logger
+from zhenxun.services.ai.utils.logger import log_sandbox as logger
 
 if TYPE_CHECKING:
     from zhenxun.services.ai.sandbox.drivers.base import BaseSandboxSession

zhenxun/services/ai/sandbox/addons/mcp_proxy.py

@@ -7,12 +7,13 @@ from anyio import create_memory_object_stream, create_task_group
 from mcp.shared.message import SessionMessage
 from mcp.types import JSONRPCMessage
 
-from zhenxun.services.ai.sandbox.addons.base import BaseMcpProxyExtension
 from zhenxun.services.ai.sandbox.protocols import SupportsStreamExecution
 from zhenxun.services.ai.sandbox.registry import SandboxRegistry
-from zhenxun.services.log import logger
+from zhenxun.services.ai.utils.logger import log_sandbox as logger
 from zhenxun.utils.pydantic_compat import model_dump_json, model_validate
 
+from .base import BaseMcpProxyExtension
+
 
 class UniversalMcpExtension(BaseMcpProxyExtension):
     """通用 MCP 代理扩展类，用于在沙箱内连接 MCP 服务"""

zhenxun/services/ai/sandbox/drivers/docker.py

@@ -24,7 +24,7 @@ from zhenxun.services.ai.sandbox.protocols import (
     SandboxProcessStream,
 )
 from zhenxun.services.ai.sandbox.storage import RESOLVE_PATH_HELPER, coerce_posix_path
-from zhenxun.services.log import logger
+from zhenxun.services.ai.utils.logger import log_sandbox as logger
 
 from .base import BaseSandboxClient, BaseSandboxSession
 
@@ -388,8 +388,6 @@ class DockerSandboxSession(BaseSandboxSession):
             await self.container.put_archive(sandbox_target_path, tar_bytes)
             return True
         except Exception as e:
-            from zhenxun.services.log import logger
-
             logger.error(f"[Docker I/O] 上传目录失败: {e}")
             return False
 
@@ -552,10 +550,7 @@ class DockerSandboxClient(BaseSandboxClient):
 
                 DockerSandboxClient._containers[eff_cname] = container
                 DockerSandboxClient._jupyter_ports[eff_cname] = jupyter_port
-                logger.info(
-                    f"[DockerSandbox] 已启动物理隔离容器: {eff_cname} "
-                    f"(镜像: {eff_image})"
-                )
+                logger.info(f"已启动物理隔离容器: {eff_cname} (镜像: {eff_image})")
 
         state = SandboxSessionState(
             session_id=session_id,
@@ -575,10 +570,7 @@ class DockerSandboxClient(BaseSandboxClient):
             "test -x /global_env/python_venv/bin/pip"
         )
         if check_venv.exit_code != 0:
-            logger.info(
-                f"正在初始化/修复容器 [{eff_cname}] 的共享 Python 虚拟环境...",
-                command="SandboxManager",
-            )
+            logger.info(f"正在初始化/修复容器 [{eff_cname}] 的共享 Python 虚拟环境...")
             init_res = await session.run_process(
                 "rm -rf /global_env/python_venv && "
                 "uv venv --seed --system-site-packages /global_env/python_venv || "
@@ -586,8 +578,7 @@ class DockerSandboxClient(BaseSandboxClient):
             )
             if init_res.exit_code != 0:
                 logger.error(
-                    f"初始化虚拟环境失败: {init_res.stderr or init_res.stdout}",
-                    command="SandboxManager",
+                    f"初始化虚拟环境失败: {init_res.stderr or init_res.stdout}"
                 )
 
         return session
@@ -615,17 +606,14 @@ class DockerSandboxClient(BaseSandboxClient):
                 await self._containers[cname].delete(force=True)
                 self._containers.pop(cname, None)
                 self._jupyter_ports.pop(cname, None)
-                logger.info(
-                    f"[DockerSandbox] 物理容器 {cname} "
-                    "已长时间闲置，已触发彻底销毁释放内存。"
-                )
+                logger.info(f"物理容器 {cname} 已长时间闲置，已触发彻底销毁释放内存。")
             except Exception as e:
                 self._containers.pop(cname, None)
                 self._jupyter_ports.pop(cname, None)
                 if getattr(e, "status", None) == 404 or "No such container" in str(e):
-                    logger.debug(f"[DockerSandbox] 物理容器 {cname} 已不存在。")
+                    logger.debug(f"物理容器 {cname} 已不存在。")
                 else:
-                    logger.error(f"[DockerSandbox] 闲置销毁物理容器 {cname} 失败: {e}")
+                    logger.error(f"闲置销毁物理容器 {cname} 失败: {e}")
 
     @classmethod
     async def close_env(cls):
@@ -663,8 +651,6 @@ class DockerSandboxClient(BaseSandboxClient):
                     except Exception:
                         pass
                 if count > 0:
-                    from zhenxun.services.log import logger
-
                     logger.info(
                         f"静默清理：已成功回收 {count} 个上次异常退出遗留的沙箱容器。",
                         command="SandboxManager",

zhenxun/services/ai/sandbox/environments.py

@@ -1,11 +1,11 @@
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any, ClassVar
 
-from zhenxun.services.log import logger
+from zhenxun.services.ai.utils.logger import log_sandbox as logger
 
 if TYPE_CHECKING:
-    from zhenxun.services.ai.sandbox.drivers.base import BaseSandboxSession
-    from zhenxun.services.ai.sandbox.models import SandboxBlueprint
+    from .drivers.base import BaseSandboxSession
+    from .models import SandboxBlueprint
 
 
 class BaseProvisioner(ABC):

zhenxun/services/ai/sandbox/manager.py

@@ -4,11 +4,11 @@ from typing import Any, cast
 import nonebot
 
 from zhenxun.services.ai.config import get_llm_config
-from zhenxun.services.ai.sandbox.models import SandboxBlueprint
-from zhenxun.services.log import logger
+from zhenxun.services.ai.utils.logger import log_sandbox as logger
 from zhenxun.utils.lifespan import LifespanManager
 
 from .drivers.base import BaseSandboxClient, BaseSandboxSession
+from .models import SandboxBlueprint
 from .registry import SandboxRegistry
 
 _startup_tasks = set()
@@ -84,10 +84,7 @@ class SandboxManager:
                 session = self._active_sessions[session_id]
                 is_alive = await session.is_alive()
                 if not is_alive:
-                    logger.warning(
-                        f"⚠️ Session '{session_id}' 容器已死亡，重建中。",
-                        command="SandboxManager",
-                    )
+                    logger.warning(f"⚠️ Session '{session_id}' 容器已死亡，重建中。")
                     await self.release_resource(session_id)
                 else:
                     session.touch()
@@ -98,9 +95,7 @@ class SandboxManager:
                         await session.mount_extension(p)
                     return session
 
-            logger.info(
-                f"为 Session '{session_id}' 创建沙箱环境...", command="SandboxManager"
-            )
+            logger.info(f"为 Session '{session_id}' 创建沙箱环境...")
             client = self._get_client(blueprint)
             try:
                 session = await client.create(session_id, blueprint)
@@ -121,10 +116,7 @@ class SandboxManager:
                 from zhenxun.services.ai.core.exceptions import SandboxFatalError
 
                 err_msg = str(e) or type(e).__name__
-                logger.error(
-                    f"创建 Session 失败: {err_msg}\n{traceback.format_exc()}",
-                    command="SandboxManager",
-                )
+                logger.error(f"创建 Session 失败: {err_msg}\n{traceback.format_exc()}")
                 if not isinstance(e, SandboxFatalError):
                     raise SandboxFatalError(f"沙箱初始化异常: {err_msg}") from e
                 raise e
@@ -134,15 +126,12 @@ class SandboxManager:
     ) -> bool:
         """统一扫描指定工作区，通过 Provisioner 体系完成环境装配"""
         if session_id not in self._active_sessions:
-            logger.warning(
-                f"找不到活跃的 Session '{session_id}'，无法配置环境。",
-                command="SandboxManager",
-            )
+            logger.warning(f"找不到活跃的 Session '{session_id}'，无法配置环境。")
             return False
 
         session = self._active_sessions[session_id]
 
-        from zhenxun.services.ai.sandbox.environments import ProvisionerRegistry
+        from .environments import ProvisionerRegistry
 
         for prov in ProvisionerRegistry.get_all().values():
             await prov.scan_and_setup_workspace(cast(Any, session), workspace_dir)
@@ -157,10 +146,7 @@ class SandboxManager:
                 client = client_cls()
                 await client.delete(cast(Any, session))
             except Exception as e:
-                logger.error(
-                    f"销毁沙箱环境失败 (Session: {resource_id}): {e}",
-                    command="SandboxManager",
-                )
+                logger.error(f"销毁沙箱环境失败 (Session: {resource_id}): {e}")
 
     async def close_session(self, session_id: str) -> None:
         """从生存期管理器中注销并销毁指定会话的沙箱环境"""

zhenxun/services/ai/sandbox/models.py

@@ -12,11 +12,11 @@ from typing import TYPE_CHECKING, Annotated, Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from zhenxun.services.log import logger
+from zhenxun.services.ai.utils.logger import log_sandbox as logger
 from zhenxun.utils.pydantic_compat import model_dump
 
 if TYPE_CHECKING:
-    from zhenxun.services.ai.sandbox.drivers.base import BaseSandboxSession
+    from .drivers.base import BaseSandboxSession
 
 
 class LanguageProfile(BaseModel):
@@ -337,7 +337,6 @@ class SandboxBlueprint(BaseModel):
 
     def with_local_dir(self, path: str, local_dir: str) -> "SandboxBlueprint":
         """声明预置本地宿主机完整目录"""
-        from zhenxun.services.log import logger
 
         for bm in self.bind_mounts:
             if path.startswith(bm.sandbox_path) or bm.sandbox_path.startswith(path):
@@ -370,8 +369,6 @@ class SandboxBlueprint(BaseModel):
         """声明宿主机物理目录双向挂载 (Bind Mount)"""
         from pathlib import Path
 
-        from zhenxun.services.log import logger
-
         if remote_path in self.entries:
             logger.warning(
                 f"⚠️ [Sandbox] 目标沙箱路径 '{remote_path}' "

zhenxun/services/ai/sandbox/protocols.py

@@ -5,7 +5,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Protocol, runtime_checkable
 
-from zhenxun.services.ai.sandbox.models import SandboxExecutionResult
+from .models import SandboxExecutionResult
 
 
 class InteractiveTerminalSession(Protocol):

zhenxun/services/ai/sandbox/registry.py

@@ -1,10 +1,10 @@
 from typing import TYPE_CHECKING, ClassVar
 
-from zhenxun.services.log import logger
+from zhenxun.services.ai.utils.logger import log_sandbox as logger
 
 if TYPE_CHECKING:
-    from zhenxun.services.ai.sandbox.addons.base import BaseSandboxExtension
-    from zhenxun.services.ai.sandbox.drivers.base import BaseSandboxClient
+    from .addons.base import BaseSandboxExtension
+    from .drivers.base import BaseSandboxClient
 
 
 class SandboxRegistry:

zhenxun/services/ai/sandbox/runtimes.py

@@ -7,13 +7,14 @@ import uuid
 
 import aiohttp
 
-from zhenxun.services.ai.sandbox.drivers.base import BaseSandboxSession
-from zhenxun.services.ai.sandbox.models import (
+from zhenxun.services.ai.utils.logger import log_sandbox as logger
+from zhenxun.utils.utils import infer_plugin_namespace
+
+from .drivers.base import BaseSandboxSession
+from .models import (
     LanguageProfile,
     SandboxExecutionResult,
 )
-from zhenxun.services.log import logger
-from zhenxun.utils.utils import infer_plugin_namespace
 
 
 def parse_shebang(script_path: str | Path) -> str | None: