ErisPulse 2.4.2.dev0__py3-none-any.whl → 2.4.2.dev1__py3-none-any.whl

ErisPulse/Core/adapter.py

@@ -51,6 +51,9 @@ class AdapterManager(ManagerBase):
         # Bot状态存储 - {platform: {bot_id: {"status": str, "last_active": float, "info": dict}}}
         self._bots: dict[str, dict[str, dict]] = {}
 
+        # 标记是否正在关闭，避免重复提交离线事件
+        self._is_being_shutdown = False
+
     def set_sdk_ref(self, sdk) -> bool:
         """
         设置 SDK 引用
@@ -287,127 +290,134 @@ class AdapterManager(ManagerBase):
         >>> # 关闭多个适配器
         >>> await adapter.shutdown(["Platform1", "Platform2"])
         """
-        if platforms is None:
-            platforms = list(self._adapters.keys())
-        if not isinstance(platforms, list):
-            platforms = [platforms]
-        for platform in platforms:
-            if platform not in self._adapters:
-                raise ValueError(f"平台 {platform} 未注册")
-
-        logger.info(f"关闭适配器 {platforms}")
-
-        # 提交适配器关闭开始事件
-        await lifecycle.submit_event(
-            "adapter.stop", msg="开始关闭适配器", data={"platforms": platforms}
-        )
-
-        from .router import router
-
-        # 需要收集受影响的 adapter 实例（因为多个平台可能共享同一个实例）
-        affected_adapters = set()
-        bots_to_offline = []  # [(platform, bot_id), ...]
+        # 设置关闭标志，避免重复提交离线事件
+        self._is_being_shutdown = True
 
-        # 取消目标平台的后台启动任务
-        for platform in platforms:
-            task = self._adapter_tasks.pop(platform, None)
-            if task and not task.done():
-                task.cancel()
-                logger.debug(f"已取消平台 {platform} 的后台启动任务")
-
-        for platform in platforms:
-            adapter_instance = self._adapters[platform]
-            affected_adapters.add(adapter_instance)
-
-            # 收集该平台下需要标记为离线的 Bot
-            if platform in self._bots:
-                for bot_id, bot_info in self._bots[platform].items():
-                    if bot_info.get("status") != "offline":
-                        bots_to_offline.append((platform, bot_id))
+        try:
+            if platforms is None:
+                platforms = list(self._adapters.keys())
+            if not isinstance(platforms, list):
+                platforms = [platforms]
+            for platform in platforms:
+                if platform not in self._adapters:
+                    raise ValueError(f"平台 {platform} 未注册")
 
-        # 对每个受影响的 adapter 实例执行 shutdown（如果尚未关闭）
-        for adapter_instance in affected_adapters:
-            if adapter_instance in self._started_instances:
-                # 找到该实例对应的平台名（用于事件提交）
-                instance_platforms = [
-                    p for p, a in self._adapters.items() if a is adapter_instance
-                ]
-                platform_label = (
-                    instance_platforms[0]
-                    if instance_platforms
-                    else str(id(adapter_instance))
-                )
+            logger.info(f"关闭适配器 {platforms}")
 
-                # 提交适配器状态变化事件（stopping）
-                for p in instance_platforms:
-                    if p in platforms:
-                        await lifecycle.submit_event(
-                            "adapter.status.change",
-                            msg=f"适配器 {p} 状态变化: stopping",
-                            data={"platform": p, "status": "stopping"},
-                        )
+            # 提交适配器关闭开始事件
+            await lifecycle.submit_event(
+                "adapter.stop", msg="开始关闭适配器", data={"platforms": platforms}
+            )
 
-                try:
-                    await adapter_instance.shutdown()
-                    self._started_instances.remove(adapter_instance)
+            from .router import router
+
+            # 需要收集受影响的 adapter 实例（因为多个平台可能共享同一个实例）
+            affected_adapters = set()
+            bots_to_offline = []  # [(platform, bot_id), ...]
+
+            # 取消目标平台的后台启动任务
+            for platform in platforms:
+                task = self._adapter_tasks.pop(platform, None)
+                if task and not task.done():
+                    task.cancel()
+                    logger.debug(f"已取消平台 {platform} 的后台启动任务")
+
+            for platform in platforms:
+                adapter_instance = self._adapters[platform]
+                affected_adapters.add(adapter_instance)
+
+                # 收集该平台下需要标记为离线的 Bot
+                if platform in self._bots:
+                    for bot_id, bot_info in self._bots[platform].items():
+                        if bot_info.get("status") != "offline":
+                            bots_to_offline.append((platform, bot_id))
+
+            # 对每个受影响的 adapter 实例执行 shutdown（如果尚未关闭）
+            for adapter_instance in affected_adapters:
+                if adapter_instance in self._started_instances:
+                    # 找到该实例对应的平台名（用于事件提交）
+                    instance_platforms = [
+                        p for p, a in self._adapters.items() if a is adapter_instance
+                    ]
+                    platform_label = (
+                        instance_platforms[0]
+                        if instance_platforms
+                        else str(id(adapter_instance))
+                    )
 
-                    # 提交适配器状态变化事件（stopped）
+                    # 提交适配器状态变化事件（stopping）
                     for p in instance_platforms:
                         if p in platforms:
                             await lifecycle.submit_event(
                                 "adapter.status.change",
-                                msg=f"适配器 {p} 状态变化: stopped",
-                                data={"platform": p, "status": "stopped"},
+                                msg=f"适配器 {p} 状态变化: stopping",
+                                data={"platform": p, "status": "stopping"},
                             )
-                except Exception as e:
-                    logger.error(f"关闭适配器实例 {id(adapter_instance)} 失败: {e}")
 
-                    # 提交适配器状态变化事件（stop_failed）
-                    for p in instance_platforms:
-                        if p in platforms:
-                            await lifecycle.submit_event(
-                                "adapter.status.change",
-                                msg=f"适配器 {p} 状态变化: stop_failed",
-                                data={
-                                    "platform": p,
-                                    "status": "stop_failed",
-                                    "error": str(e),
-                                },
-                            )
+                    try:
+                        await adapter_instance.shutdown()
+                        self._started_instances.remove(adapter_instance)
+
+                        # 提交适配器状态变化事件（stopped）
+                        for p in instance_platforms:
+                            if p in platforms:
+                                await lifecycle.submit_event(
+                                    "adapter.status.change",
+                                    msg=f"适配器 {p} 状态变化: stopped",
+                                    data={"platform": p, "status": "stopped"},
+                                )
+                    except Exception as e:
+                        logger.error(f"关闭适配器实例 {id(adapter_instance)} 失败: {e}")
+
+                        # 提交适配器状态变化事件（stop_failed）
+                        for p in instance_platforms:
+                            if p in platforms:
+                                await lifecycle.submit_event(
+                                    "adapter.status.change",
+                                    msg=f"适配器 {p} 状态变化: stop_failed",
+                                    data={
+                                        "platform": p,
+                                        "status": "stop_failed",
+                                        "error": str(e),
+                                    },
+                                )
+
+            # 清理被关闭平台的路由
+            for platform in platforms:
+                result = router.unregister_all_by_namespace(platform)
+                if result["http_count"] > 0 or result["websocket_count"] > 0:
+                    logger.debug(
+                        f"已清理平台 {platform} 的路由: HTTP={result['http_count']}, WebSocket={result['websocket_count']}"
+                    )
 
-        # 清理被关闭平台的路由
-        for platform in platforms:
-            result = router.unregister_all_by_namespace(platform)
-            if result["http_count"] > 0 or result["websocket_count"] > 0:
-                logger.debug(
-                    f"已清理平台 {platform} 的路由: HTTP={result['http_count']}, WebSocket={result['websocket_count']}"
-                )
+            # 停止路由器（仅当所有适配器都关闭时）
+            if not self._started_instances:
+                await router.stop()
 
-        # 停止路由器（仅当所有适配器都关闭时）
-        if not self._started_instances:
-            await router.stop()
-
-        # 将相关 Bot 标记为离线
-        for platform, bot_id in bots_to_offline:
-            if platform in self._bots and bot_id in self._bots[platform]:
-                self._bots[platform][bot_id]["status"] = "offline"
-                # 提交 Bot 离线事件
-                await lifecycle.submit_event(
-                    "adapter.bot.offline",
-                    msg=f"Bot {platform}/{bot_id} 离线",
-                    data={"platform": platform, "bot_id": bot_id, "status": "offline"},
-                )
+            # 将相关 Bot 标记为离线
+            for platform, bot_id in bots_to_offline:
+                if platform in self._bots and bot_id in self._bots[platform]:
+                    self._bots[platform][bot_id]["status"] = "offline"
+                    # 提交 Bot 离线事件
+                    await lifecycle.submit_event(
+                        "adapter.bot.offline",
+                        msg=f"Bot {platform}/{bot_id} 离线",
+                        data={"platform": platform, "bot_id": bot_id, "status": "offline"},
+                    )
 
-        # 如果所有适配器都关闭了，清理事件处理器
-        if not self._started_instances:
-            self._onebot_handlers.clear()
-            self._raw_handlers.clear()
-            self._onebot_middlewares.clear()
+            # 如果所有适配器都关闭了，清理事件处理器
+            if not self._started_instances:
+                self._onebot_handlers.clear()
+                self._raw_handlers.clear()
+                self._onebot_middlewares.clear()
 
-        # 提交适配器关闭完成事件
-        await lifecycle.submit_event(
-            "adapter.stopped", msg="适配器关闭完成", data={"platforms": platforms}
-        )
+            # 提交适配器关闭完成事件
+            await lifecycle.submit_event(
+                "adapter.stopped", msg="适配器关闭完成", data={"platforms": platforms}
+            )
+        finally:
+            # 清除关闭标志
+            self._is_being_shutdown = False
 
     def clear(self) -> None:
         """
@@ -473,12 +483,11 @@ class AdapterManager(ManagerBase):
 
     def exists(self, platform: str) -> bool:
         """
-        检查平台是否存在
+        检查平台是否已注册
 
         :param platform: 平台名称
-        :return: [bool] 平台是否存在
+        :return: 平台是否已注册（即 adapter.register() 已被调用）
         """
-        # 检查平台是否已注册（在 _adapters 中）
         return platform in self._adapters
 
     def is_enabled(self, platform: str) -> bool:
@@ -486,20 +495,25 @@ class AdapterManager(ManagerBase):
         检查平台适配器是否启用
 
         :param platform: 平台名称
-        :return: [bool] 平台适配器是否启用
+        :return: 平台适配器是否启用
+
+        {!--< tips >!--}
+        适配器启用条件：
+        1. 适配器在配置文件中（ErisPulse.adapters.status.{platform} 存在）
+        2. 配置值为启用状态
+
+        如果适配器未在配置中，返回 False
+        {!--< /tips >!--}
         """
-        # 不使用默认值，如果配置不存在则返回 None
+        from .config import parse_bool_config
+
         status = config.getConfig(f"ErisPulse.adapters.status.{platform}")
 
-        # 如果状态不存在，说明是新适配器
+        # 适配器未在配置中，返回 False
         if status is None:
-            return False  # 新适配器默认不启用，需要在初始化时处理
-
-        # 处理字符串形式的布尔值
-        if isinstance(status, str):
-            return status.lower() not in ("false", "0", "no", "off")
+            return False
 
-        return bool(status)
+        return parse_bool_config(status)
 
     def enable(self, platform: str) -> bool:
         """
@@ -541,7 +555,7 @@ class AdapterManager(ManagerBase):
         :return: 是否取消成功
 
         {!--< internal-use >!--}
-        注意：此方法仅取消注册，不关闭已启动的适配器
+        注意: 此方法仅取消注册, 不关闭已启动的适配器
         {!--< /internal-use >!--}
         """
         if platform not in self._adapters:
@@ -837,13 +851,15 @@ class AdapterManager(ManagerBase):
                 )
 
         if status == "offline":
-            asyncio.ensure_future(
-                lifecycle.submit_event(
-                    "adapter.bot.offline",
-                    msg=f"Bot {platform}/{bot_id} 离线",
-                    data={"platform": platform, "bot_id": bot_id, "status": "offline"},
+            # 只有在非主动关闭的情况下才提交事件（避免与 shutdown() 重复）
+            if not self._is_being_shutdown:
+                asyncio.ensure_future(
+                    lifecycle.submit_event(
+                        "adapter.bot.offline",
+                        msg=f"Bot {platform}/{bot_id} 离线",
+                        data={"platform": platform, "bot_id": bot_id, "status": "offline"},
+                    )
                 )
-            )
 
     def _update_bot_heartbeat(self, platform: str, self_info: dict) -> None:
         """

ErisPulse/Core/adapter.pyi

@@ -104,10 +104,10 @@ class AdapterManager(ManagerBase):
         ...
     def exists(self: object, platform: str) -> bool:
         """
-        检查平台是否存在
+        检查平台是否已注册
         
         :param platform: 平台名称
-        :return: [bool] 平台是否存在
+        :return: 平台是否已注册（即 adapter.register() 已被调用）
         """
         ...
     def is_enabled(self: object, platform: str) -> bool:
@@ -115,7 +115,15 @@ class AdapterManager(ManagerBase):
         检查平台适配器是否启用
         
         :param platform: 平台名称
-        :return: [bool] 平台适配器是否启用
+        :return: 平台适配器是否启用
+        
+        {!--< tips >!--}
+        适配器启用条件：
+        1. 适配器在配置文件中（ErisPulse.adapters.status.{platform} 存在）
+        2. 配置值为启用状态
+        
+        如果适配器未在配置中，返回 False
+        {!--< /tips >!--}
         """
         ...
     def enable(self: object, platform: str) -> bool:

ErisPulse/Core/config.py

@@ -24,8 +24,9 @@ class ConfigManager:
         self._cache_timestamp = 0  # 缓存时间戳
         self._cache_timeout = 60  # 缓存超时时间（秒）
         self._write_delay = 5  # 写入延迟（秒）
-        self._write_timer = None  # 写入定时器
+        self._write_timer: threading.Timer | None = None  # 写入定时器
         self._lock = threading.RLock()  # 线程安全锁
+        self._file_lock = threading.RLock()  # 文件操作锁，确保原子性
         self._migrate_config()  # 迁移旧配置文件
         self._load_config()  # 初始化时加载配置
 
@@ -138,56 +139,79 @@ class ConfigManager:
     def _flush_config(self) -> None:
         """
         将待写入的配置刷新到文件
+        
+        使用文件锁确保多线程环境下的原子性操作
         """
         with self._lock:
             if not self._dirty_keys:
                 return  # 没有需要写入的内容
 
-            try:
-                # 从文件读取完整配置
-                if os.path.exists(self.CONFIG_FILE):
-                    with open(self.CONFIG_FILE, "r", encoding="utf-8") as f:
-                        config = toml.load(f)
-                else:
-                    config = {}
-
-                # 应用待写入的更改
-                for key, value in self._dirty_keys.items():
-                    keys = key.split(".")
-                    current = config
-                    for k in keys[:-1]:
-                        if k not in current:
-                            current[k] = {}
-                        current = current[k]
-                    current[keys[-1]] = value
-
-                # 对配置字典进行排序，确保同一模块的配置项排列在一起
-                sorted_config = self._sort_config_dict(config)
-
-                # 写入文件
-                with open(self.CONFIG_FILE, "w", encoding="utf-8") as f:
-                    toml.dump(sorted_config, f)
-
-                # 更新缓存并清除待写入队列
-                self._cache = sorted_config
-                self._cache_timestamp = time.time()
-                self._dirty_keys.clear()
+            with self._file_lock:  # 确保文件操作原子性
+                try:
+                    # 从文件读取完整配置
+                    if os.path.exists(self.CONFIG_FILE):
+                        with open(self.CONFIG_FILE, "r", encoding="utf-8") as f:
+                            config = toml.load(f)
+                    else:
+                        config = {}
+
+                    # 应用待写入的更改
+                    for key, value in self._dirty_keys.items():
+                        keys = key.split(".")
+                        current = config
+                        for k in keys[:-1]:
+                            if k not in current:
+                                current[k] = {}
+                            current = current[k]
+                        current[keys[-1]] = value
+
+                    # 对配置字典进行排序，确保同一模块的配置项排列在一起
+                    sorted_config = self._sort_config_dict(config)
+
+                    # 写入临时文件，确保原子性
+                    temp_file = self.CONFIG_FILE + ".tmp"
+                    with open(temp_file, "w", encoding="utf-8") as f:
+                        toml.dump(sorted_config, f)
+
+                    # 原子性重命名（跨平台兼容）
+                    if os.name == 'nt':  # Windows
+                        if os.path.exists(self.CONFIG_FILE):
+                            os.replace(temp_file, self.CONFIG_FILE)
+                        else:
+                            os.rename(temp_file, self.CONFIG_FILE)
+                    else:  # Unix/Linux/macOS
+                        os.rename(temp_file, self.CONFIG_FILE)
+
+                    # 更新缓存并清除待写入队列
+                    self._cache = sorted_config
+                    self._cache_timestamp = time.time()
+                    self._dirty_keys.clear()
 
-            except Exception as e:
-                from .logger import logger
+                except Exception as e:
+                    from .logger import logger
 
-                logger.error(f"写入配置文件 {self.CONFIG_FILE} 失败: {e}")
+                    logger.error(f"写入配置文件 {self.CONFIG_FILE} 失败: {e}")
+                    # 清理临时文件
+                    temp_file = self.CONFIG_FILE + ".tmp"
+                    if os.path.exists(temp_file):
+                        try:
+                            os.remove(temp_file)
+                        except Exception:
+                            pass
 
     def _schedule_write(self) -> None:
         """
         安排延迟写入
+        
+        线程安全：使用锁保护 Timer 的取消和创建
         """
-        if self._write_timer:
-            self._write_timer.cancel()
+        with self._lock:
+            if self._write_timer:
+                self._write_timer.cancel()
 
-        self._write_timer = threading.Timer(self._write_delay, self._flush_config)
-        self._write_timer.daemon = True
-        self._write_timer.start()
+            self._write_timer = threading.Timer(self._write_delay, self._flush_config)
+            self._write_timer.daemon = True
+            self._write_timer.start()
 
     def _check_cache_validity(self) -> None:
         """
@@ -268,4 +292,30 @@ class ConfigManager:
 
 config: ConfigManager = ConfigManager()
 
-__all__ = ["config"]
+
+def parse_bool_config(value: Any) -> bool:
+    """
+    解析配置中的布尔值
+
+    :param value: 配置值（可以是 bool, int, str 等）
+    :return: 解析后的布尔值
+
+    支持的值：
+    - True: True, 1, "true", "True", "1", "yes", "Yes", "on", "On"
+    - False: False, 0, "false", "False", "0", "no", "No", "off", "Off"
+    """
+    if isinstance(value, bool):
+        return value
+
+    if isinstance(value, int):
+        return value != 0
+
+    if isinstance(value, str):
+        normalized = value.lower().strip()
+        return normalized in ("true", "1", "yes", "on")
+
+    # 其他类型尝试转换为布尔值
+    return bool(value)
+
+
+__all__ = ["config", "parse_bool_config"]

ErisPulse/Core/config.pyi

@@ -46,11 +46,15 @@ class ConfigManager:
     def _flush_config(self: object) -> None:
         """
         将待写入的配置刷新到文件
+        
+        使用文件锁确保多线程环境下的原子性操作
         """
         ...
     def _schedule_write(self: object) -> None:
         """
         安排延迟写入
+        
+        线程安全：使用锁保护 Timer 的取消和创建
         """
         ...
     def _check_cache_validity(self: object) -> None:
@@ -87,3 +91,16 @@ class ConfigManager:
         ...
 
 config: ConfigManager
+
+def parse_bool_config(value: Any) -> bool:
+    """
+    解析配置中的布尔值
+    
+    :param value: 配置值（可以是 bool, int, str 等）
+    :return: 解析后的布尔值
+    
+    支持的值：
+    - True: True, 1, "true", "True", "1", "yes", "Yes", "on", "On"
+    - False: False, 0, "false", "False", "0", "no", "No", "off", "Off"
+    """
+    ...

ErisPulse/Core/module.py

@@ -272,15 +272,17 @@ class ModuleManager(ManagerBase):
 
     def exists(self, module_name: str) -> bool:
         """
-        检查模块是否存在（已注册或在配置中）
+        检查模块是否已注册
 
-        :param module_name: [str] 模块名称
-        :return: [bool] 模块是否存在
+        :param module_name: 模块名称
+        :return: 模块是否已注册（即 module.register() 已被调用）
+
+        {!--< tips >!--}
+        exists() 只检查模块类是否已注册到管理器，用于验证模块是否可以加载。
+        如需检查模块是否启用，请使用 is_enabled()。
+        {!--< /tips >!--}
         """
-        if module_name in self._module_classes:
-            return True
-        module_statuses = config.getConfig("ErisPulse.modules.status", {})
-        return module_name in module_statuses
+        return module_name in self._module_classes
 
     def is_loaded(self, module_name: str) -> bool:
         """
@@ -350,9 +352,9 @@ class ModuleManager(ManagerBase):
         {!--< internal-use >!--}
         此方法仅供内部使用
 
-        :param module_name: [str] 模块名称
-        :param enabled: [bool] 是否启用模块 (默认: False)
-        :return: [bool] 操作是否成功
+        :param module_name: 模块名称
+        :param enabled: 是否启用模块 (默认: False)
+        :return: 操作是否成功
         """
         if self.exists(module_name):
             return True
@@ -367,18 +369,27 @@ class ModuleManager(ManagerBase):
         """
         检查模块是否启用
 
-        :param module_name: [str] 模块名称
-        :return: [bool] 模块是否启用
+        :param module_name: 模块名称
+        :return: 模块是否启用
+
+        {!--< tips >!--}
+        模块启用条件：
+        1. 模块在配置文件中（ErisPulse.modules.status.{module_name} 存在）
+        2. 配置值为启用状态
+
+        如果模块未在配置中，返回 False
+        {!--< /tips >!--}
         """
-        if (
-            status := config.getConfig(f"ErisPulse.modules.status.{module_name}")
-        ) is None:
-            return False
+        from .config import parse_bool_config
+
+        status = config.getConfig(f"ErisPulse.modules.status.{module_name}")
 
-        if isinstance(status, str):
-            return status.lower() not in ("false", "0", "no", "off")
+        # 模块未在配置中，返回 False
+        if status is None:
+            return False
 
-        return bool(status)
+        # 解析配置值
+        return parse_bool_config(status)
 
     def enable(self, module_name: str) -> bool:
         """

ErisPulse/Core/module.pyi

@@ -91,10 +91,15 @@ class ModuleManager(ManagerBase):
         ...
     def exists(self: object, module_name: str) -> bool:
         """
-        检查模块是否存在（已注册或在配置中）
+        检查模块是否已注册
         
-        :param module_name: [str] 模块名称
-        :return: [bool] 模块是否存在
+        :param module_name: 模块名称
+        :return: 模块是否已注册（即 module.register() 已被调用）
+        
+        {!--< tips >!--}
+        exists() 只检查模块类是否已注册到管理器，用于验证模块是否可以加载。
+        如需检查模块是否启用，请使用 is_enabled()。
+        {!--< /tips >!--}
         """
         ...
     def is_loaded(self: object, module_name: str) -> bool:
@@ -155,8 +160,16 @@ class ModuleManager(ManagerBase):
         """
         检查模块是否启用
         
-        :param module_name: [str] 模块名称
-        :return: [bool] 模块是否启用
+        :param module_name: 模块名称
+        :return: 模块是否启用
+        
+        {!--< tips >!--}
+        模块启用条件：
+        1. 模块在配置文件中（ErisPulse.modules.status.{module_name} 存在）
+        2. 配置值为启用状态
+        
+        如果模块未在配置中，返回 False
+        {!--< /tips >!--}
         """
         ...
     def enable(self: object, module_name: str) -> bool:

ErisPulse/Core/router.py

@@ -485,9 +485,14 @@ class RouterManager:
             self._server_task.cancel()
             try:
                 await asyncio.wait_for(self._server_task, timeout=5.0)
-            except (asyncio.CancelledError, asyncio.TimeoutError, Exception):
-                 logger.info("路由服务器已停止")
-            self._server_task = None
+            except asyncio.CancelledError:
+                logger.info("路由服务器已被取消")
+            except asyncio.TimeoutError:
+                logger.warning("路由服务器停止超时，强制终止")
+            except Exception as e:
+                logger.error(f"路由服务器停止时发生错误: {e}", exc_info=True)
+            finally:
+                self._server_task = None
 
         # 清理所有注册的路由
         logger.debug("清理所有注册的路由...")

ErisPulse/loaders/module.py

@@ -549,11 +549,15 @@ class LazyModule:
         """
         确保模块已初始化
 
-        :raises RuntimeError: 当模块需要异步初始化时抛出
-
         {!--< internal-use >!--}
         内部方法，检查并确保模块已初始化
         {!--< /internal-use >!--}
+        
+        设计说明：
+        - 支持同步/异步透明的懒加载机制，用户无需感知差异
+        - BaseModule 在同步上下文中使用 asyncio.run() 确保初始化完成
+        - 非 BaseModule 保持原有逻辑，支持同步初始化
+        {!--< internal-use >!--}
         """
         if not object.__getattribute__(self, "_initialized"):
             try:
@@ -561,8 +565,12 @@ class LazyModule:
                 
                 if object.__getattribute__(self, "_is_base_module"):
                     # BaseModule 必须通过 manager.load() 异步初始化
-                    # 同步创建实例后调度异步 on_load 会导致双重实例化
-                    loop.create_task(self._initialize())
+                    # 在同步上下文中，使用 asyncio.run() 确保初始化完成
+                    # 在异步上下文中，使用 loop.create_task() 避免阻塞
+                    if loop.is_running():
+                        loop.create_task(self._initialize())
+                    else:
+                        asyncio.run(self._initialize())
                     return
 
                 init_method = getattr(

ErisPulse/sdk.py

@@ -144,8 +144,17 @@ class SDK:
             return object.__getattribute__(self, name)
         except AttributeError:
             from .Core.logger import logger as _logger
-            _logger.error(f"[SDK] 未找到属性 {name}, 您可能使用了错误的SDK注册对象")
-            raise AttributeError
+
+            # 区分不同场景，提供更准确的错误提示
+            if not name.startswith('_'):
+                if name in self.module._module_classes:
+                    _logger.error(f"[SDK] 模块 '{name}' 已注册但未加载或未启用，请检查模块配置")
+                elif name in self.adapter._adapters:
+                    _logger.error(f"[SDK] 适配器 '{name}' 已注册但未启用，请检查适配器配置")
+                else:
+                    _logger.error(f"[SDK] 未找到属性或模块/适配器 '{name}'，请检查名称是否正确")
+
+            raise AttributeError(f"ErisPulse SDK has no attribute '{name}'")
 
     def __repr__(self) -> str:
         """
@@ -363,55 +372,37 @@ class SDK:
                 loaded_modules = module_manager.list_loaded()
                 if loaded_modules:
                     await module_manager.unload()
-                
+
                 # 3. 收集 SDK 对象上的模块属性（在 clear 之前）
                 instance_dict = object.__getattribute__(self._sdk, '__dict__')
                 module_properties_to_clear = set()
-                
+
                 # 收集已加载模块的属性名
                 for module_name in loaded_modules:
                     if module_name in instance_dict:
                         module_properties_to_clear.add(module_name)
-                
-                # 收集所有 LazyModule 代理的属性名（包括从未被访问过的）
+
+                # 处理已初始化的 LazyModule（已访问过，有实例）
                 for attr_name, attr_value in list(instance_dict.items()):
                     if attr_name.startswith('_'):
                         continue
                     from .loaders.module import LazyModule
                     if isinstance(attr_value, LazyModule):
-                        lm_name = object.__getattribute__(attr_value, '_module_name')
-                        if lm_name not in module_properties_to_clear:
-                            # LazyModule 从未被触发初始化，需要手动调用 on_unload
-                            try:
-                                lm_class = object.__getattribute__(attr_value, '_module_class')
-                                lm_manager = object.__getattribute__(attr_value, '_manager_instance')
-                                lm_info = object.__getattribute__(attr_value, '_module_info')
-                                lm_initialized = object.__getattribute__(attr_value, '_initialized')
-                                lm_is_base = object.__getattribute__(attr_value, '_is_base_module')
-                                
-                                if lm_is_base and not lm_initialized:
+                        # 只处理已初始化的 LazyModule
+                        lm_initialized = object.__getattribute__(attr_value, '_initialized')
+                        if lm_initialized:
+                            lm_name = object.__getattribute__(attr_value, '_module_name')
+                            instance = object.__getattribute__(attr_value, '_instance')
+                            if hasattr(instance, 'on_unload'):
+                                try:
                                     import inspect
-                                    try:
-                                        if lm_manager._sdk is None:
-                                            lm_sdk = self._sdk
-                                        else:
-                                            lm_sdk = lm_manager._sdk
-                                        
-                                        params = [p for p in inspect.signature(lm_class.__init__).parameters.values() if p.name != "self"]
-                                        tmp_instance = lm_class(lm_sdk) if params else lm_class()
-                                        if tmp_instance is None:
-                                            raise ValueError(f"模块 {lm_name} __init__ 返回 None")
-                                        if hasattr(tmp_instance, 'on_unload'):
-                                            if inspect.iscoroutinefunction(tmp_instance.on_unload):
-                                                await tmp_instance.on_unload({"module_name": lm_name})
-                                            else:
-                                                tmp_instance.on_unload({"module_name": lm_name})
-                                    except Exception as e:
-                                        logger.warning(f"清理未初始化懒加载模块 {lm_name} 的 on_unload 失败: {e}")
-                            except Exception as e:
-                                logger.warning(f"清理未初始化懒加载模块 {lm_name} 失败: {e}")
-                        
-                        module_properties_to_clear.add(attr_name)
+                                    if inspect.iscoroutinefunction(instance.on_unload):
+                                        await instance.on_unload({"module_name": lm_name})
+                                    else:
+                                        instance.on_unload({"module_name": lm_name})
+                                except Exception as e:
+                                    logger.warning(f"清理懒加载模块 {lm_name} 的 on_unload 失败: {e}")
+                            module_properties_to_clear.add(attr_name)
                 
                 # 4. 清理所有事件处理器
                 Event._clear_all_handlers()
@@ -460,10 +451,13 @@ class SDK:
                         "module_properties_to_clear": list(module_properties_to_clear),
                     },
                 )
-                
-                # 9. 清理生命周期事件处理器（在所有事件提交之后）
+
+                # 等待一小段时间，确保事件处理完成
+                await asyncio.sleep(0.1)
+
+                # 9. 清理生命周期事件处理器（在所有事件完成之后）
                 lifecycle._handlers.clear()
-                
+
                 logger.info(f"SDK反初始化成功 (耗时: {duration_str})")
                 return True
                 
@@ -478,6 +472,13 @@ class SDK:
                         "error": str(e),
                     },
                 )
+
+                # 等待一小段时间，确保事件处理完成
+                await asyncio.sleep(0.1)
+
+                # 清理生命周期事件处理器（即使在失败时也要清理）
+                lifecycle._handlers.clear()
+
                 if "attached to a different loop" in str(e):
                     # 这是一个常见的错误，通常是由于SDK在另一个事件循环中运行而导致的。
                     # 在这种情况下，我们直接返回True即可
@@ -734,20 +735,51 @@ if __name__ == "__main__":
     async def restart(self) -> bool:
         """
         SDK 重新启动
-        
-        执行完整的反初始化后再初始化过程，并重新启动适配器
-        
-        {!--< tips >!--}
-        使用 asyncio.ensure_future 将重启任务注册到事件循环调度器，
-        与调用栈完全解耦，确保即使调用方被取消，重启流程也能完整执行。
 
-        注意：设计上就是如此，不需要进行更改 | 针对场景：事件内的模块进行ErisPulse的restart调用
+        执行完整的反初始化后再初始化过程，并重新启动适配器。
+
+        {!--< tips >!--}
+        **重要设计说明**：
+
+        此方法使用 `asyncio.ensure_future()` 将重启任务注册到事件循环调度器，
+        与调用栈完全解耦。这是有意为之的设计，原因如下：
+
+        1. **事件链路保护**：如果模块在事件处理器内部调用 `restart()`，而重启过程
+           是同步等待的，那么重启会中断当前事件链路，导致事件处理不完整。
+
+        2. **后台执行**：重启是一个耗时操作（需要关闭适配器、卸载模块、重新加载），
+           使用 `ensure_future` 可以让它在后台执行，不阻塞调用者。
+
+        3. **返回值语义**：方法立即返回 `True` 表示"重启任务已成功调度"，
+           而不是"重启已完成"。实际的重启过程在后台进行。
+
+        **使用场景示例**：
+
+        >>> # 场景1: 在模块的事件处理器中调用重启
+        >>> @Event.on("message")
+        >>> async def handle_reload_command(event):
+        >>>     if event["message"] == "/reload":
+        >>>         # 使用 ensure_future 确保事件链路不被中断
+        >>>         await sdk.restart()  # ✅ 正确
+        >>>         # 不要使用 await sdk.restart()，这会导致事件链路中断
+        >>>
+        >>> # 场景2: 等待重启完成
+        >>> # 如果需要等待重启完成，可以使用生命周期事件监听
+        >>> @lifecycle.on("core.init.complete")
+        >>> async def on_restart_complete(event):
+        >>>     if event["data"]["success"]:
+        >>>         logger.info("重启成功！")
+        >>>
+        >>> # 场景3: 命令触发重启
+        >>> @command("restart")
+        >>> async def restart_command():
+        >>>     logger.info("正在重启 SDK...")
+        >>>     await sdk.restart()
+        >>>     logger.info("重启任务已调度，将在后台执行")
         {!--< /tips >!--}
-        
-        :return: bool 重新加载是否成功
-        
-        :raises RuntimeError: 当初始化失败时抛出
-        
+
+        :return: bool 重启任务是否成功调度（并非重启是否完成）
+
         :example:
         >>> await sdk.restart()
         """

ErisPulse/sdk.pyi

@@ -141,18 +141,49 @@ class SDK:
         """
         SDK 重新启动
         
-        执行完整的反初始化后再初始化过程，并重新启动适配器
+        执行完整的反初始化后再初始化过程，并重新启动适配器。
         
         {!--< tips >!--}
-        使用 asyncio.ensure_future 将重启任务注册到事件循环调度器，
-        与调用栈完全解耦，确保即使调用方被取消，重启流程也能完整执行。
-        
-        注意：设计上就是如此，不需要进行更改 | 针对场景：事件内的模块进行ErisPulse的restart调用
+        **重要设计说明**：
+        
+        此方法使用 `asyncio.ensure_future()` 将重启任务注册到事件循环调度器，
+        与调用栈完全解耦。这是有意为之的设计，原因如下：
+        
+        1. **事件链路保护**：如果模块在事件处理器内部调用 `restart()`，而重启过程
+           是同步等待的，那么重启会中断当前事件链路，导致事件处理不完整。
+        
+        2. **后台执行**：重启是一个耗时操作（需要关闭适配器、卸载模块、重新加载），
+           使用 `ensure_future` 可以让它在后台执行，不阻塞调用者。
+        
+        3. **返回值语义**：方法立即返回 `True` 表示"重启任务已成功调度"，
+           而不是"重启已完成"。实际的重启过程在后台进行。
+        
+        **使用场景示例**：
+        
+        >>> # 场景1: 在模块的事件处理器中调用重启
+        >>> @Event.on("message")
+        >>> async def handle_reload_command(event):
+        >>>     if event["message"] == "/reload":
+        >>>         # 使用 ensure_future 确保事件链路不被中断
+        >>>         await sdk.restart()  # ✅ 正确
+        >>>         # 不要使用 await sdk.restart()，这会导致事件链路中断
+        >>>
+        >>> # 场景2: 等待重启完成
+        >>> # 如果需要等待重启完成，可以使用生命周期事件监听
+        >>> @lifecycle.on("core.init.complete")
+        >>> async def on_restart_complete(event):
+        >>>     if event["data"]["success"]:
+        >>>         logger.info("重启成功！")
+        >>>
+        >>> # 场景3: 命令触发重启
+        >>> @command("restart")
+        >>> async def restart_command():
+        >>>     logger.info("正在重启 SDK...")
+        >>>     await sdk.restart()
+        >>>     logger.info("重启任务已调度，将在后台执行")
         {!--< /tips >!--}
         
-        :return: bool 重新加载是否成功
-        
-        :raises RuntimeError: 当初始化失败时抛出
+        :return: bool 重启任务是否成功调度（并非重启是否完成）
         
         :example:
         >>> await sdk.restart()

{erispulse-2.4.2.dev0.dist-info → erispulse-2.4.2.dev1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ErisPulse
-Version: 2.4.2.dev0
+Version: 2.4.2.dev1
 Summary: ErisPulse 是一个模块化、可扩展的异步 Python SDK 框架，主要用于构建高效、可维护的机器人应用程序。
 Author-email: ErisDev <erisdev@88.com>
 Maintainer-email: "艾莉丝·格雷拉特(WSu2059)" <wsu2059@qq.com>

{erispulse-2.4.2.dev0.dist-info → erispulse-2.4.2.dev1.dist-info}/RECORD

@@ -2,8 +2,8 @@ ErisPulse/__init__.py,sha256=rIEPa-80J1wlolAE5IavBEAkKh3S5EGpW4TTlbQmDEM,1504
 ErisPulse/__init__.pyi,sha256=P5aOKFk9OttVVNQFqENMxGT4A4DneWa6BpVls4ktUMw,656
 ErisPulse/__main__.py,sha256=7tGYe9fBPUWFYH0wZEnk5M2OhcQI6SvbUTo9HvXNsdk,359
 ErisPulse/__main__.pyi,sha256=ShpCRAsyNREan4WzZUe5ImB5az453DokFzZrcnVM2LM,431
-ErisPulse/sdk.py,sha256=4xrdGe0spMcEcWZyxAHmoNb3ZHYb-4PzfTSkDc-fHwU,28584
-ErisPulse/sdk.pyi,sha256=ch1HhmvAXbUr0pY5Ydk6SsJxkXK4O6N7yZAkzHSIfHk,5061
+ErisPulse/sdk.py,sha256=7bYuAcC8FC-QcQiTSW6s3Yh4UYPTg4nvz2FTdza7dQ4,29419
+ErisPulse/sdk.pyi,sha256=WT9Rbo9alhO4ztu1k2_X_RktwmE7UGHvVPozxuRrntA,6641
 ErisPulse/CLI/__init__.py,sha256=LcGh1t4r_YBt0IPrTI9WdsOcWb3hIhGvLHaX4Tl0-QI,94
 ErisPulse/CLI/__init__.pyi,sha256=MwfRkbzA9MSDQpVl5HYnLq-BN2snw1LfM2asW7-K5xg,192
 ErisPulse/CLI/base.py,sha256=G3IXDGlsbILoEze0mJcjvvjWDcIxYsKgPJ-t8CwGgDk,1103
@@ -38,17 +38,17 @@ ErisPulse/CLI/utils/package_manager.py,sha256=Sc4UwP4Rbzye9g3lL05kzo5AsfJ_pHFQOl
 ErisPulse/CLI/utils/package_manager.pyi,sha256=rinvIBxjR5gn3bhCEJ6K0iLyrCXYo2ttMmtJulDHXiM,8147
 ErisPulse/Core/__init__.py,sha256=eFY-q8j8fiN9_ie-syvglcy_tPQ5qrIufPC2n7LZXpc,1958
 ErisPulse/Core/__init__.pyi,sha256=8ADqzF23pS8uGZLpRu2dGOjhHsl7WaI0kLm0TvF3PXY,736
-ErisPulse/Core/adapter.py,sha256=YrsTbBOV23PVWeffeJSgazCK6ybU2E8Mv6TBLNlxeIw,41657
-ErisPulse/Core/adapter.pyi,sha256=J1n950M4oT0btziG43PM2JaXGmAezmNUadsT6n3NP6c,12563
-ErisPulse/Core/config.py,sha256=ZmtutKXVv4RP4CRud2bTUrVI4mjHCVOE-0KTEX8FdcQ,8717
-ErisPulse/Core/config.pyi,sha256=Wu41o9MpglvVKgQQX-QT2SzsLGTOQB3MDD3tYwLYsnQ,2579
+ErisPulse/Core/adapter.py,sha256=w4HmnBmhlM4E3hpTWFi7MXboISk8tVPWUwB7E82ofBU,42572
+ErisPulse/Core/adapter.pyi,sha256=YQz5JXZ-76JFG3xUhacSWVUc11ChY7GYZoFnSnSrkPM,12876
+ErisPulse/Core/config.py,sha256=ylv9F4sVhYOsI_x1bVbI0rLWw4K6bE08-JAjNMLQlws,10699
+ErisPulse/Core/config.pyi,sha256=hMPispd42iVB-_0rJbtzo3I_wvOJ7VKdysjsB6XZOH0,3092
 ErisPulse/Core/lifecycle.py,sha256=lJOGL2AI8UkEksX5tQ4hJRm3pT5_IBCVs5AyYUtNv-I,6444
 ErisPulse/Core/lifecycle.pyi,sha256=nvsgCPy5179OW_J8__7cxX_OPBAJcGqKEC36sIvK0RU,2678
 ErisPulse/Core/logger.py,sha256=rrof9Iaap9EwX56NfqKqvyKzErmlxlcl9EbgJ9uehRM,15522
 ErisPulse/Core/logger.pyi,sha256=bobxpD0abXiwC8FD4RaPxGYBa7H2vEY7oNMwJdtAQAM,9117
-ErisPulse/Core/module.py,sha256=2vMQuG8yFNcPNsg2qqRNFz88FuQvvlIDc_qeD7kgdFI,18197
-ErisPulse/Core/module.pyi,sha256=fMGvzhCl6y-SYGnjpranL6McSCWmZTNrnESuyuHoo7M,7021
-ErisPulse/Core/router.py,sha256=5olQLEszKbdTFIaYxh4VXQ0obbgnI9eF1Yx6Lae0E-U,18440
+ErisPulse/Core/module.py,sha256=nSSB2-MUIFIYZpJXnl1oAKYvBFUw54NQVS50F14UM2U,18524
+ErisPulse/Core/module.pyi,sha256=OxFR_y8hcLeMY5c4sRikri0zYd1wApG_1no_UtxhL_Q,7516
+ErisPulse/Core/router.py,sha256=RW8bDVzzD_AJ8BQUeCSqTjODuqFH3AADH6QhIKzOtCw,18675
 ErisPulse/Core/router.pyi,sha256=zU0Y8uRzU8t_us_zA6S0Yd1_0dqk1CV9V3YsjhuC07c,5316
 ErisPulse/Core/storage.py,sha256=f2W_yJHONEwHTDYIHYdXiJZj-LDEIbnv8Was1JWyACA,17478
 ErisPulse/Core/storage.pyi,sha256=1MHAVo-luTn8Bn3I2mMdHBFN6fbf9HXTxNgQnoFiAgE,6178
@@ -94,7 +94,7 @@ ErisPulse/loaders/__init__.py,sha256=LGNzCHnCRKDgIYtWjCbsk2hZ020TKner48dGCIlDQXM
 ErisPulse/loaders/__init__.pyi,sha256=rwvQW2XJTRR5woGsoOyOFgQEdjEfwye6QZARj0Q8QbY,424
 ErisPulse/loaders/adapter.py,sha256=Ai-78zXTdpE-xLBdgNngL8C5F3XpJ96QtbCY4YaiTBc,8336
 ErisPulse/loaders/adapter.pyi,sha256=RBmlw1CG-g9FowLWC8QfHah18WOJMEIGfGRuhfAeAiE,3062
-ErisPulse/loaders/module.py,sha256=JJl7kbZ9iiKKtyhRcd0lGXv24yNNxAEi2dZTRKbLQZk,27850
+ErisPulse/loaders/module.py,sha256=npTZ4EH5rZNguaj9CRhmpK8mItGgZRzfa6sQJE1BX9E,28292
 ErisPulse/loaders/module.pyi,sha256=UUxcQx7fa_-FgtE_WB1MtpvYWb9L0qWwFdxH2X6ozoQ,6020
 ErisPulse/loaders/strategy.py,sha256=T7pPKlsc4RHs5dbg_JDU-PjIa0x4w7hYlN8ihH3rW8Y,3343
 ErisPulse/loaders/strategy.pyi,sha256=jVEAgOeR1zNXdX60fHQcCQECgQDYP-J564mrkBBfFgQ,2409
@@ -110,8 +110,8 @@ ErisPulse/runtime/exceptions.py,sha256=ODQuetLnWUdq4qHgk4b-SxgGri-GrgYs9sALCB_qu
 ErisPulse/runtime/exceptions.pyi,sha256=I9N3S4sNYMjdqVfUCOG6Jwq0nbMHh6biHh7BfY6Ts1o,1588
 ErisPulse/runtime/frame_config.py,sha256=GN4-e72KU9SVIuXQCDFHZJR8HWXHb5nxzvtQk8ezOsc,5573
 ErisPulse/runtime/frame_config.pyi,sha256=x_lrPZAfl9hHDs_9NUTom430SaDLcevpjIkomssiJ78,2011
-erispulse-2.4.2.dev0.dist-info/METADATA,sha256=KSdZqqf9rCrujGpAVR0olcv02fKngwG0ibkYuz-YHvY,10625
-erispulse-2.4.2.dev0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-erispulse-2.4.2.dev0.dist-info/entry_points.txt,sha256=NiOwT6-XQ7KIH1r6J8odjRO-uaKHfr_Vz_UIG96EWXg,187
-erispulse-2.4.2.dev0.dist-info/licenses/LICENSE,sha256=c2XbbDpZFu8YVuWV5mBZnGxE1IlYyelE1qW9TJADHV4,1071
-erispulse-2.4.2.dev0.dist-info/RECORD,,
+erispulse-2.4.2.dev1.dist-info/METADATA,sha256=PDkmHxqAb45pGhwHbC9P8H0iWiSwb22WdMvyT4gHBkw,10625
+erispulse-2.4.2.dev1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+erispulse-2.4.2.dev1.dist-info/entry_points.txt,sha256=NiOwT6-XQ7KIH1r6J8odjRO-uaKHfr_Vz_UIG96EWXg,187
+erispulse-2.4.2.dev1.dist-info/licenses/LICENSE,sha256=c2XbbDpZFu8YVuWV5mBZnGxE1IlYyelE1qW9TJADHV4,1071
+erispulse-2.4.2.dev1.dist-info/RECORD,,