♻️ 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/context/memory/builder.py

@@ -1,33 +1,31 @@
 from __future__ import annotations
 
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Any
+from typing import Any
 from typing_extensions import Self
 
 from pydantic import BaseModel
 
-if TYPE_CHECKING:
-    from zhenxun.services.ai.context.memory.models import MemorySlot
-    from zhenxun.services.ai.context.memory.storage.interfaces import (
-        BaseChatContext,
-        BaseMemoryIngestionMiddleware,
-        BaseSlotContext,
-    )
-    from zhenxun.services.ai.context.rag.backends import Embedder, StorageBackend
-    from zhenxun.services.ai.context.rag.engine import ScopedRAGClient
-
 from zhenxun.services.ai.context.memory.compression import MemoryPolicy
 from zhenxun.services.ai.context.memory.models import (
     ContextCompressionConfig,
     IngestionConfig,
     LongTermConfig,
     MemoryConfig,
+    MemorySlot,
     ShortTermConfig,
     SlotMemoryConfig,
 )
+from zhenxun.services.ai.context.memory.storage.interfaces import (
+    BaseChatContext,
+    BaseMemoryIngestionMiddleware,
+    BaseSlotContext,
+)
 from zhenxun.services.ai.context.memory.types import (
     AutoRecallPolicy,
 )
+from zhenxun.services.ai.context.rag.backends import Embedder, StorageBackend
+from zhenxun.services.ai.context.rag.engine import ScopedRAGClient
 from zhenxun.services.ai.utils.scope import ScopeBuilder
 
 
@@ -51,7 +49,7 @@ class MemoryBuilder:
         )
 
     @classmethod
-    def auto(cls) -> "MemoryBuilder":
+    def auto(cls) -> MemoryBuilder:
         """
         创建一个开箱即用的默认记忆配置构建器。
 
@@ -61,7 +59,7 @@ class MemoryBuilder:
 
     @classmethod
     def resolve(
-        cls, memory: bool | MemoryConfig | "MemoryBuilder" | None
+        cls, memory: bool | MemoryConfig | MemoryBuilder | None
     ) -> MemoryConfig:
         if isinstance(memory, MemoryConfig):
             return memory
@@ -85,7 +83,7 @@ class MemoryBuilder:
         self,
         enable: bool = True,
         isolation: ScopeBuilder | None = None,
-        backend: "str | BaseChatContext | None" = None,
+        backend: str | BaseChatContext | None = None,
     ) -> Self:
         """
         配置短期对话历史记忆。
@@ -107,8 +105,8 @@ class MemoryBuilder:
         self,
         enable: bool = True,
         scopes: dict[str, ScopeBuilder] | None = None,
-        default_slots: list["MemorySlot"] | None = None,
-        backend: "str | BaseSlotContext | None" = None,
+        default_slots: list[MemorySlot] | None = None,
+        backend: str | BaseSlotContext | None = None,
         instructions: str | None = None,
     ) -> Self:
         """
@@ -136,9 +134,9 @@ class MemoryBuilder:
         self,
         enable: bool = True,
         scopes: dict[str, ScopeBuilder] | None = None,
-        engine: "ScopedRAGClient | None" = None,
-        backend: "str | StorageBackend | None" = None,
-        embedder: "Embedder | str | None" = None,
+        engine: ScopedRAGClient | None = None,
+        backend: str | StorageBackend | None = None,
+        embedder: Embedder | str | None = None,
         agentic: bool = True,
         auto_recall: AutoRecallPolicy = False,
         instructions: str | None = None,
@@ -250,7 +248,7 @@ class MemoryBuilder:
         return self
 
     def with_ingestion_middlewares(
-        self, *middlewares: "BaseMemoryIngestionMiddleware"
+        self, *middlewares: BaseMemoryIngestionMiddleware
     ) -> Self:
         """
         配置记忆入库管线中间件。

zhenxun/services/ai/context/memory/compression.py

@@ -4,9 +4,6 @@ from typing import Any, Generic, TypeVar
 
 from pydantic import BaseModel, Field
 
-from zhenxun.services.ai.context.memory.storage.interfaces import (
-    BaseMemoryReducer,
-)
 from zhenxun.services.ai.core.engine.token_counter import token_counter
 from zhenxun.services.ai.core.messages import (
     AudioPart,
@@ -18,9 +15,13 @@ from zhenxun.services.ai.core.messages import (
     VideoPart,
 )
 from zhenxun.services.ai.llm.manager import get_default_model
-from zhenxun.services.log import logger
+from zhenxun.services.ai.utils.logger import log_memory as logger
 from zhenxun.utils.pydantic_compat import model_copy
 
+from .storage.interfaces import (
+    BaseMemoryReducer,
+)
+
 
 class MultimodalPlaceholderReducer(BaseMemoryReducer):
     """视觉媒体降级：将超过一定轮数的老图片/视频替换为 <图片> 占位符文本"""
@@ -126,7 +127,7 @@ class MessageDropper(BaseMemoryReducer):
             return messages, False, current_tokens
 
         logger.info(
-            "✂️ [MemoryCompression] 触发硬截断丢弃策略 | 原因: "
+            "✂️ 触发硬截断丢弃策略 | 原因: "
             f"当前 Token 预估 ({current_tokens}) 仍超过硬性上限 ({self.trigger_tokens})，"  # noqa: E501
             "开始丢弃最旧的历史对话..."
         )
@@ -198,9 +199,7 @@ class ToolPrunerReducer(BaseMemoryReducer):
         if is_turn_exceeded:
             reasons.append(f"工具调用轮数超限 ({tool_turns} > {self.max_turns})")
 
-        logger.info(
-            f"✂️ [MemoryCompression] 触发工具结果修剪策略 | 原因: {' 且 '.join(reasons)}"
-        )
+        logger.info(f"✂️ 触发工具结果修剪策略 | 原因: {' 且 '.join(reasons)}")
 
         from zhenxun.services.ai.core.messages import ToolReturnPart
 

zhenxun/services/ai/context/memory/engine.py

@@ -1,17 +1,18 @@
 from collections.abc import Sequence
 from typing import Any, cast
 
-from zhenxun.services.ai.context.memory.compression import (
-    CondenserPipeline,
-)
-from zhenxun.services.ai.context.memory.manager import memory_manager
-from zhenxun.services.ai.context.memory.models import MemoryConfig
-from zhenxun.services.ai.context.memory.types import SessionMetadata
 from zhenxun.services.ai.core.engine.context_renderer import ContextConverter
 from zhenxun.services.ai.core.messages import AgentMessage
-from zhenxun.services.log import logger
+from zhenxun.services.ai.utils.logger import log_memory as logger
 from zhenxun.utils.pydantic_compat import model_copy
 
+from .compression import (
+    CondenserPipeline,
+)
+from .manager import memory_manager
+from .models import MemoryConfig
+from .types import SessionMetadata
+
 
 class MemoryReader:
     """

zhenxun/services/ai/context/memory/facades.py

@@ -1,29 +1,30 @@
-from collections.abc import Sequence
-from typing import TYPE_CHECKING, Literal
+from __future__ import annotations
 
-from zhenxun.services.ai.context.memory.types import (
+from collections.abc import Sequence
+from typing import Literal
+
+from zhenxun.services.ai.core.messages import AgentMessage, LLMMessage
+
+from .manager import GlobalMemoryManager
+from .storage.interfaces import (
+    BaseChatContext,
+    BaseSlotContext,
+)
+from .types import (
     MemorySlot,
     SessionMetadata,
 )
-from zhenxun.services.ai.core.messages import AgentMessage, LLMMessage
-
-if TYPE_CHECKING:
-    from zhenxun.services.ai.context.memory.manager import GlobalMemoryManager
-    from zhenxun.services.ai.context.memory.storage.interfaces import (
-        BaseChatContext,
-        BaseSlotContext,
-    )
 
 
 class ChatHistoryFacade:
     """短期对话历史门面"""
 
-    def __init__(self, manager: "GlobalMemoryManager", session_meta: SessionMetadata):
+    def __init__(self, manager: GlobalMemoryManager, session_meta: SessionMetadata):
         self.manager = manager
         self.session_meta = session_meta
 
     @property
-    def _backend(self) -> "BaseChatContext | None":
+    def _backend(self) -> BaseChatContext | None:
         return self.manager.get_chat_context(
             None, self.session_meta.namespace or "global"
         )
@@ -56,12 +57,12 @@ class ChatHistoryFacade:
 class SlotFacade:
     """中期记忆槽门面"""
 
-    def __init__(self, manager: "GlobalMemoryManager", session_meta: SessionMetadata):
+    def __init__(self, manager: GlobalMemoryManager, session_meta: SessionMetadata):
         self.manager = manager
         self.session_meta = session_meta
 
     @property
-    def _backend(self) -> "BaseSlotContext | None":
+    def _backend(self) -> BaseSlotContext | None:
         """获取底层槽位存储后端"""
         return self.manager.get_slot_context(
             None, self.session_meta.namespace or "global"
@@ -115,7 +116,7 @@ class AgentSessionFacade:
     提供给第三方开发者的会话记忆访问聚合门面 (Facade)。
     """
 
-    def __init__(self, manager: "GlobalMemoryManager", session_meta: SessionMetadata):
+    def __init__(self, manager: GlobalMemoryManager, session_meta: SessionMetadata):
         self.manager = manager
         self.session_meta = session_meta
         self.history = ChatHistoryFacade(manager, session_meta)

zhenxun/services/ai/context/memory/manager.py

@@ -1,18 +1,20 @@
 from collections.abc import Callable
 from typing import Any, cast
 
-from zhenxun.services.ai.context.memory.models import MemoryConfig
-from zhenxun.services.ai.context.memory.storage.backends import (
+from zhenxun.services.ai.context.rag.backends import Embedder, StorageBackend
+from zhenxun.services.ai.utils.logger import log_memory as logger
+from zhenxun.services.ai.utils.scope import BaseScopeBuilder
+from zhenxun.utils.utils import infer_plugin_namespace
+
+from .models import MemoryConfig
+from .storage.backends import (
     InMemoryChatContext,
     MemoryScope,
 )
-from zhenxun.services.ai.context.memory.storage.interfaces import (
+from .storage.interfaces import (
     BaseChatContext,
     BaseSlotContext,
 )
-from zhenxun.services.ai.context.rag.backends import Embedder, StorageBackend
-from zhenxun.services.ai.utils.scope import BaseScopeBuilder
-from zhenxun.utils.utils import infer_plugin_namespace
 
 
 class MemoryCleaner(BaseScopeBuilder["MemoryCleaner"]):
@@ -64,14 +66,11 @@ class MemoryCleaner(BaseScopeBuilder["MemoryCleaner"]):
 
     async def clear_all(self):
         """一键清理指定范围下的所有生命周期记忆（对话、槽位、RAG）"""
-        from zhenxun.services.log import logger
-
         await self.clear_short_term()
         await self.clear_slots()
         await self.clear_long_term()
         logger.info(
-            f"🧹 [MemoryCleaner] 成功清理作用域 '{self._selector.scope_prefix}'"
-            "下的所有记忆痕迹！"
+            f"🧹 成功清理作用域 '{self._selector.scope_prefix}'下的所有记忆痕迹！"
         )
 
 
@@ -189,7 +188,7 @@ class GlobalMemoryManager:
         if embedder:
             builder.with_embedder(embedder)
 
-        from zhenxun.services.ai.context.memory.models import MemoryScoringConfig
+        from .models import MemoryScoringConfig
 
         scoring_cfg = MemoryScoringConfig()
 

zhenxun/services/ai/context/memory/models.py

@@ -6,21 +6,22 @@ from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from zhenxun.services.ai.context.memory.storage.interfaces import (
+from zhenxun.services.ai.context.rag.backends import Embedder, StorageBackend
+from zhenxun.services.ai.context.rag.engine import ScopedRAGClient
+from zhenxun.services.ai.utils.scope import ScopeBuilder
+
+from .storage.interfaces import (
     BaseChatContext,
     BaseMemoryIngestionMiddleware,
     BaseMemoryReducer,
     BaseSlotContext,
 )
-from zhenxun.services.ai.context.memory.types import (
+from .types import (
     AutoRecallPolicy,
     Isolation,
     MemorySlot,
     SessionMetadata,
 )
-from zhenxun.services.ai.context.rag.backends import Embedder, StorageBackend
-from zhenxun.services.ai.context.rag.engine import ScopedRAGClient
-from zhenxun.services.ai.utils.scope import ScopeBuilder
 
 
 class SlotMemoryConfig(BaseModel):

zhenxun/services/ai/context/memory/storage/backends.py

@@ -1,26 +1,22 @@
+from __future__ import annotations
+
 import asyncio
 import base64
 from collections.abc import Callable
 import datetime
 from pathlib import Path
 import time
-from typing import TYPE_CHECKING, Any, cast
-
-if TYPE_CHECKING:
-    from zhenxun.services.ai.context.rag.engine import ScopedRAGClient
+from typing import Any, cast
 
 from nonebot.utils import is_coroutine_callable
 from tortoise import fields
 from tortoise.timezone import now
 
-from zhenxun.services.ai.context.memory.storage.interfaces import (
-    BaseChatContext,
-    BaseSlotContext,
-)
 from zhenxun.services.ai.context.memory.types import (
     MemorySlot,
     SessionMetadata,
 )
+from zhenxun.services.ai.context.rag.engine import ScopedRAGClient
 from zhenxun.services.ai.context.rag.models import BaseRecord, SearchResult
 from zhenxun.services.ai.core.messages import (
     AssistantMessage,
@@ -35,6 +31,11 @@ from zhenxun.services.ai.utils.scope import ScopeSelector
 from zhenxun.services.db_context import Model
 from zhenxun.utils.pydantic_compat import TypeAdapter, model_dump
 
+from .interfaces import (
+    BaseChatContext,
+    BaseSlotContext,
+)
+
 
 class AbstractMemoryRecord(Model):
     """Tortoise ORM 短期记忆持久化基类 (Mixin)。"""
@@ -129,7 +130,7 @@ class MemoryScope:
 
     def __init__(
         self,
-        rag_client: "ScopedRAGClient",
+        rag_client: ScopedRAGClient,
     ):
         """初始化长期记忆作用域与 RAG 客户端"""
         self.rag_client = rag_client