ErisPulse 2.8.0.dev2__tar.gz → 2.8.2__tar.gz

{erispulse-2.8.0.dev2 → erispulse-2.8.2}/.gitignore

@@ -3,6 +3,7 @@ devs/videos
 main.py
 plugins/
 venvs
+config.full.example
 config.toml
 uv.lock
 snapshots/
@@ -16,6 +17,7 @@ config/config.db
 config/config.db-journal
 config/config.db-wal
 config/config.db-shm
+.erispulse_config.lock
 
 # site-packages
 config/.packages

{erispulse-2.8.0.dev2 → erispulse-2.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ErisPulse
-Version: 2.8.0.dev2
+Version: 2.8.2
 Summary: Event-driven modular async bot framework — write once, deploy to any platform | 事件驱动的模块化异步机器人框架，一次编写，多平台部署
 Project-URL: Homepage, https://github.com/ErisPulse/ErisPulse
 Project-URL: Documentation, https://www.erisdev.com#docs
@@ -57,6 +57,8 @@ An event-driven, multi-platform chatbot development framework based on the OneBo
 
 [![PyPI](https://img.shields.io/pypi/v/ErisPulse?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/ErisPulse/)
 [![Python](https://img.shields.io/badge/Python-3.10+-FFD43B?style=for-the-badge&logo=python&logoColor=blue)](https://pypi.org/project/ErisPulse/)
+[![OneBot 11](https://img.shields.io/badge/OneBot-11-black?style=for-the-badge)](https://github.com/botuniverse/onebot-11)
+[![OneBot 12](https://img.shields.io/badge/OneBot-12-black?style=for-the-badge)](https://12.onebot.dev/)
 [![License](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](https://github.com/ErisPulse/ErisPulse/blob/main/LICENSE)
 [![Docs](https://img.shields.io/badge/docs-erisdev.com-FF6B9D?style=for-the-badge&logo=bookstack&logoColor=white)](https://www.erisdev.com)
 [![Stars](https://img.shields.io/github/stars/ErisPulse/ErisPulse?style=for-the-badge&logo=github&color=brightgreen)](https://github.com/ErisPulse/ErisPulse)

{erispulse-2.8.0.dev2 → erispulse-2.8.2}/README.pypi.md

@@ -6,6 +6,8 @@ An event-driven, multi-platform chatbot development framework based on the OneBo
 
 [![PyPI](https://img.shields.io/pypi/v/ErisPulse?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/ErisPulse/)
 [![Python](https://img.shields.io/badge/Python-3.10+-FFD43B?style=for-the-badge&logo=python&logoColor=blue)](https://pypi.org/project/ErisPulse/)
+[![OneBot 11](https://img.shields.io/badge/OneBot-11-black?style=for-the-badge)](https://github.com/botuniverse/onebot-11)
+[![OneBot 12](https://img.shields.io/badge/OneBot-12-black?style=for-the-badge)](https://12.onebot.dev/)
 [![License](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](https://github.com/ErisPulse/ErisPulse/blob/main/LICENSE)
 [![Docs](https://img.shields.io/badge/docs-erisdev.com-FF6B9D?style=for-the-badge&logo=bookstack&logoColor=white)](https://www.erisdev.com)
 [![Stars](https://img.shields.io/github/stars/ErisPulse/ErisPulse?style=for-the-badge&logo=github&color=brightgreen)](https://github.com/ErisPulse/ErisPulse)

{erispulse-2.8.0.dev2 → erispulse-2.8.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ErisPulse"
-version = "2.8.0-dev.2"
+version = "2.8.2"
 description = "Event-driven modular async bot framework — write once, deploy to any platform | 事件驱动的模块化异步机器人框架，一次编写，多平台部署"
 readme = "README.pypi.md"
 requires-python = ">=3.10"

{erispulse-2.8.0.dev2 → erispulse-2.8.2}/src/ErisPulse/CLI/commands/create.py

@@ -166,6 +166,8 @@ class Main(BaseModule):
             description={{\"i18n\": \"module.{name}.meta.description\", \"default\": \"{name} module\"}},
             version=\"0.1.0\",
             author=\"ErisDev\",
+            # 最低 SDK 版本（可选）：不满足时框架在加载期明确报错并跳过本模块
+            min_sdk_version=\"2.8.0\",
             group=\"default\",
             tags=[\"{name}\"],
             # 对外服务白名单（可选）：声明后其他模块可经 sdk.module.call() 调用这些方法；
@@ -297,6 +299,9 @@ class {name}(BaseAdapter):
     depends: ClassVar[dict] = {{}}
     optional_modules: ClassVar[list] = []
 
+    # 声明所需最低 SDK 版本：不满足时框架在加载期明确报错并跳过本适配器（可选）
+    min_sdk_version = "2.8.0"
+
     # {text[adapter.config_hint]}
     @dataclass
     class ConfigClass(BaseConfig):

{erispulse-2.8.0.dev2 → erispulse-2.8.2}/src/ErisPulse/CLI/commands/run.py

@@ -16,11 +16,11 @@ from pathlib import Path
 
 from rich.panel import Panel
 
+from ...runtime.file_watcher import FileSystemEventHandler, PollingObserver
 from ..base import Command
 from ..console import console
 from ..constants import ENV_SUPERVISED, HARD_RESTART_EXIT_CODE
 from ..i18n import i18n
-from ..utils.file_watcher import FileSystemEventHandler, PollingObserver
 
 
 class ReloadHandler(FileSystemEventHandler):

{erispulse-2.8.0.dev2 → erispulse-2.8.2}/src/ErisPulse/CLI/utils/package_manager.py

@@ -26,54 +26,8 @@ from ..console import console
 from ..constants import PYPI_PACKAGE_JSON_URL_TEMPLATE
 from ..i18n import i18n
 
-# 版本号解析正则（PEP 440 子集，纯标准库，不依赖 packaging）：
-# 支持 epoch (1!)、release 段、预发布后缀 (dev/a/alpha/b/beta/rc/c/pre)、
-# post 版本 (1.0.postN) 与本地版本 (1.0+local)。
-# 例如 2.5.0-dev.1 / 2.5.0a1 / 1.0rc1 / 1.0.post1 / 1.0+local / 1!1.0 均可解析。
-# 不支持的格式（如 1.0.post1.dev1 这类 post 后跟 dev）由 _parse_version 返回 None 退化处理。
-_VERSION_RE = re.compile(
-    r"^\s*v?(?P<epoch>\d+!)?(?P<release>\d+(?:\.\d+)*)"
-    r"(?:[-._]?(?P<pre>dev|alpha|beta|rc|a|b|c|pre)[-._]?(?P<num>\d*))?"
-    r"(?:[-._]?post[-._]?(?P<post>\d+))?"
-    r"(?:\+(?P<local>[a-zA-Z0-9]+(?:[.-][a-zA-Z0-9]+)*))?",
-    re.IGNORECASE,
-)
-# 预发布类型排序权重：正式版 > rc > beta > alpha > dev
-_PRE_RELEASE_RANK = {
-    "dev": 0,
-    "alpha": 1,
-    "a": 1,
-    "beta": 2,
-    "b": 2,
-    "rc": 3,
-    "c": 3,
-    "pre": 3,
-}
-
-
-def _parse_version(version: str) -> dict | None:
-    """
-    将版本号解析为结构化组件（PEP 440 子集，纯标准库）。
-
-    与 :meth:`PackageManager._version_key` / :meth:`PackageManager._is_pre_release`
-    共用同一解析口径，避免不同正则导致判定分歧（如 ``1.0c2`` 此前在
-    ``_is_pre_release`` 与 ``_version_key`` 间判定口径不一致）。
-
-    :param version: [str] 版本号字符串
-    :return: [Optional[dict]] 含 epoch/release/pre_type/pre_num/post/local 的字典，
-             无法解析时返回 None
-    """
-    match = _VERSION_RE.match(str(version).strip().lstrip("vV"))
-    if not match:
-        return None
-    return {
-        "epoch": int((match.group("epoch") or "0").rstrip("!") or 0),
-        "release": match.group("release"),
-        "pre_type": match.group("pre"),
-        "pre_num": match.group("num"),
-        "post": match.group("post"),
-        "local": match.group("local"),
-    }
+# 版本号解析与比较的唯一实现在 runtime/version.py（PEP 440 子集，纯标准库）；
+# 本模块经下方方法级委托复用同一解析口径，避免双正则导致判定分歧
 
 
 class PackageManager:
@@ -853,63 +807,28 @@ class PackageManager:
         """
         将版本号解析为可比较的元组键
 
-        遵循项目命名规则排序：正式版 > post > rc > beta > alpha > dev；
-        epoch 优先于一切 release 段；本地版本 (+local) 不影响主排序，
-        但同一版本号带 local 段者 > 不带 local 段者。
-        例如 2.4.5-dev.1 先于 2.4.5 正式版，1.0 < 1.0.post1 < 1.1。
+        委托 :func:`ErisPulse.runtime.version.version_key`（框架内唯一实现）。
 
         :param version: [str] 版本号字符串
-        :return: [tuple] 可直接用于排序/比较的元组键
+        :return: [tuple] 逐段可比较的比较键元组
         """
-        parsed = _parse_version(version)
-        if parsed is None:
-            # 无法解析时退化为基础键，保证不抛异常
-            return (0, (0, 0, 0, 0), (1,), (0,), ((1, str(version).lower()),))
-
-        release = tuple(int(x) for x in parsed["release"].split("."))
-        # release 段对齐到固定长度，确保 (2.5) 与 (2.5.0) 可正确比较
-        padded = release + (0,) * max(0, 4 - len(release))
-
-        pre_type = parsed["pre_type"]
-        if pre_type is None:
-            # 正式版：预发布键高于任何预发布版本
-            pre_key = (1,)
-        else:
-            rank = _PRE_RELEASE_RANK.get(pre_type.lower(), 1)
-            pre_num = int(parsed["pre_num"] or 0)
-            pre_key = (0, rank, pre_num)
-
-        # post 段：无 post 视为 post0，保证 1.0 == 1.0.post0 < 1.0.post1
-        post_num = int(parsed["post"] or 0)
-        post_key = (post_num,)
-
-        local = parsed["local"]
-        if local:
-            # 本地段按 "数值段 < 字母段" 拆分，避免 int/str 直接比较抛异常
-            local_key = tuple(
-                (0, int(part)) if part.isdigit() else (1, part.lower())
-                for part in local.split(".")
-            )
-        else:
-            local_key = ()
+        from ...runtime.version import version_key
 
-        return (parsed["epoch"], padded, pre_key, post_key, local_key)
+        return version_key(version)
 
     def _compare_versions(self, version1: str, version2: str) -> int:
         """
         比较两个版本号的大小
 
+        委托 :func:`ErisPulse.runtime.version.compare_versions`（框架内唯一实现）。
+
         :param version1: [str] 第一个版本号
         :param version2: [str] 第二个版本号
         :return: [int] version1 大于/等于/小于 version2 时分别返回 1/0/-1
         """
-        k1 = self._version_key(version1)
-        k2 = self._version_key(version2)
-        if k1 > k2:
-            return 1
-        if k1 < k2:
-            return -1
-        return 0
+        from ...runtime.version import compare_versions
+
+        return compare_versions(version1, version2)
 
     def _check_sdk_compatibility(self, min_sdk_version: str) -> tuple[bool, str]:
         """
@@ -1435,14 +1354,16 @@ class PackageManager:
         """
         判断版本号是否为预发布版本
 
-        与 :meth:`_version_key` 复用同一解析口径（:func:`_parse_version`）：
-        仅当版本含预发布段 (dev/alpha/beta/rc/c/pre) 时返回 True；
-        post 版本 (1.0.post1) 与本地版本 (1.0+local) 不计为预发布。
+        与 :meth:`_version_key` 共用同一解析口径（:func:`ErisPulse.runtime.version.parse_version`）。
+        当版本号含预发布段 (dev/alpha/beta/rc/c/pre) 时返回 True。
+        post 版本 (1.0.post1) 与本地版本 (1.0+local) 不视为预发布版本
 
         :param version: [str] 版本号字符串
-        :return: [bool] 是预发布版本返回 True
+        :return: [bool] 是预发布版本时返回 True
         """
-        parsed = _parse_version(version)
+        from ...runtime.version import parse_version
+
+        parsed = parse_version(version)
         return parsed is not None and parsed["pre_type"] is not None
 
     def update_self(self, target_version: str | None = None, force: bool = False) -> bool:

{erispulse-2.8.0.dev2 → erispulse-2.8.2}/src/ErisPulse/Core/Bases/__init__.py

@@ -18,14 +18,17 @@ from .errors import (
     ClientConnectionError,
     ClientTimeoutError,
     HTTPStatusError,
+    InteractionCancelled,
     InteractionError,
     ModuleCallError,
     ModuleCallTimeoutError,
     ModuleError,
     ModuleNotAvailableError,
     ServiceNotProvidedError,
+    SessionOccupiedError,
     StorageError,
     StorageUnreachableError,
+    StrictModeError,
     WebSocketError,
     WebSocketDisconnect,
 )
@@ -76,6 +79,7 @@ __all__ = [
     # i18n 单键声明
     "I18nKey",
     "AsyncBridge",
+    "InteractionCancelled",
     "InteractionError",
     "KVQueryBuilder",
     "ModuleCallError",
@@ -88,9 +92,11 @@ __all__ = [
     "SendContext",
     "SendDSL",
     "ServiceNotProvidedError",
+    "SessionOccupiedError",
     "SseEmitter",
     "StorageError",
     "StorageUnreachableError",
+    "StrictModeError",
     "WSMessage",
     "WebSocketConnection",
     "WebSocketConnectionBase",

{erispulse-2.8.0.dev2 → erispulse-2.8.2}/src/ErisPulse/Core/Bases/errors.py

@@ -10,7 +10,6 @@ ErisPulse 异常体系
 3. 底层库异常（aiohttp.ClientError 等）不会泄露到业务代码
 {!--< /tips >!--}
 """
-
 from __future__ import annotations
 
 
@@ -30,14 +29,31 @@ class ClientError(ErisPulseError):
     所有 HTTP/WS 客户端请求相关的异常基类。
     可用于统一捕获所有客户端错误。
 
+    :attribute url: 请求 URL（构建异常时提供则非空）
+    :attribute method: 请求方法（GET / POST 等，构建异常时提供则非空）
+    :attribute attempts: 已尝试的请求次数（重试耗尽时提供）
+
     :example:
     >>> from ErisPulse.Core.Bases.errors import ClientError
     >>> try:
     ...     resp = await sdk.client.get("https://example.com")
     ... except ClientError as e:
-    ...     print(f"请求失败: {e}")
+    ...     print(f"请求失败: {e} url={e.url}")
     """
 
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        url: str | None = None,
+        method: str | None = None,
+        attempts: int | None = None,
+    ):
+        self.url = url
+        self.method = method
+        self.attempts = attempts
+        super().__init__(message)
+
 
 
 
@@ -115,8 +131,26 @@ class StorageUnreachableError(StorageError):
 
     后端连接池创建在自动重试耗尽后仍失败（数据库不可达 / 凭据错误 /
     网络隔离等）。框架保持运行，存储操作在冷却期内快速失败并自动重连。
+
+    连接状态变化的运行时感知推荐订阅生命周期事件
+    ``storage.unreachable`` / ``storage.recovered``（本异常主要供
+    直接操作存储底层的场景捕获）。
+
+    :attribute backend: 存储后端名（sqlite / mysql / postgres）
+    :attribute cooldown: 冷却时长（秒，进入冷却时提供）
     """
 
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        backend: str = "",
+        cooldown: float | None = None,
+    ):
+        self.backend = backend
+        self.cooldown = cooldown
+        super().__init__(message or "storage unreachable")
+
 
 class InteractionError(ErisPulseError):
     """
@@ -176,8 +210,21 @@ class ModuleCallTimeoutError(ModuleCallError):
     模块间调用超时
 
     目标方法在超时时限内未返回时抛出。
+
+    :attribute timeout: 超时时限（秒）
     """
 
+    def __init__(
+        self,
+        module: str = "",
+        method: str = "",
+        message: str = "",
+        *,
+        timeout: float | None = None,
+    ):
+        self.timeout = timeout
+        super().__init__(module, method, message)
+
 
 
 class WebSocketDisconnect(WebSocketError):
@@ -204,18 +251,78 @@ class WebSocketDisconnect(WebSocketError):
         super().__init__(f"code={self.code}, reason={self.reason}")
 
 
+class InteractionCancelled(InteractionError):
+    """
+    交互会话被取消
+
+    挂起的 ``wait_reply`` / 租约因非超时原因终止时设置到 future 上，
+    等待方可捕获本异常获取原因；上层 ``wait_reply`` 将其转换为返回 None。
+
+    :attribute reason: 取消原因（conflict / owner_unload / platform_stop / revoked / cancelled / cleared）
+    :attribute wait_key: 关联的会话键
+    """
+
+    def __init__(self, reason: str, wait_key: str = ""):
+        self.reason = reason
+        self.wait_key = wait_key
+        super().__init__(f"{reason}: {wait_key}" if wait_key else reason)
+
+
+class SessionOccupiedError(InteractionError):
+    """
+    会话已被其他模块占用
+
+    :meth:`InteractionManager.hold` 获取互斥租约失败时抛出。
+
+    :attribute wait_key: 会话键
+    :attribute owner: 当前占用者（模块名 / 平台名，未知时为 None）
+    """
+
+    def __init__(
+        self,
+        wait_key: str = "",
+        owner: str | None = None,
+        message: str = "",
+    ):
+        self.wait_key = wait_key
+        self.owner = owner
+        super().__init__(
+            message or f"session occupied by {owner!r}: {wait_key}"
+        )
+
+
+class StrictModeError(ErisPulseError):
+    """
+    严格模式致命错误
+
+    当严格模式级别为 2（致命）且检测到违规时，在检查点抛出此异常，
+    用于中止整个启动流程。
+
+    {!--< tips >!--}
+    此异常不应被加载器捕获吞掉，应向上传播至初始化协调器
+    {!--< /tips >!--}
+    """
+
+    def __init__(self, message: str, violations: list | None = None):
+        super().__init__(message)
+        self.violations: list = violations if violations is not None else []
+
+
 __all__ = [
     "ClientConnectionError",
     "ClientError",
     "ClientTimeoutError",
     "ErisPulseError",
     "HTTPStatusError",
+    "InteractionCancelled",
     "InteractionError",
     "ModuleCallError",
     "ModuleCallTimeoutError",
     "ModuleError",
     "ModuleNotAvailableError",
     "ServiceNotProvidedError",
+    "SessionOccupiedError",
+    "StrictModeError",
     "WebSocketDisconnect",
     "WebSocketError",
 ]

{erispulse-2.8.0.dev2 → erispulse-2.8.2}/src/ErisPulse/Core/Bases/kv_builder.py

@@ -22,11 +22,13 @@ ErisPulse KV 查询构建器
 """
 
 import json
-from typing import Any
+from typing import Any, TypeVar
 
 from ..i18n import i18n
 from .storage import BaseQueryBuilder
 
+T = TypeVar("T")
+
 _TABLE_PREFIX = "__erispulse_sql__"
 
 
@@ -200,18 +202,22 @@ class KVQueryBuilder(BaseQueryBuilder):
             return self._exec_delete()
         raise ValueError(i18n.t("core.kvbuilder.unknown_operation", op=self._operation))
 
+    def _require_data(self, expected: type[T], key: str) -> T:
+        """{!--< internal-use >!--} 校验构建器数据形态并返回（同步/异步执行路径共用，兼作类型收窄）"""
+        if not isinstance(self._data, expected):
+            raise ValueError(i18n.t(key))
+        return self._data
+
     def _exec_insert(self) -> int:
-        if not isinstance(self._data, dict):
-            raise ValueError(i18n.t("core.kvbuilder.insert_needs_dict"))
+        data = self._require_data(dict, "core.kvbuilder.insert_needs_dict")
         row_id = self._get_next_id()
-        self._storage.set(self._row_key(row_id), json.dumps(self._data, ensure_ascii=False))
+        self._storage.set(self._row_key(row_id), json.dumps(data, ensure_ascii=False))
         return 1
 
     def _exec_insert_multi(self) -> int:
-        if not isinstance(self._data, list):
-            raise ValueError(i18n.t("core.kvbuilder.insert_multi_needs_list"))
+        rows = self._require_data(list, "core.kvbuilder.insert_multi_needs_list")
         count = 0
-        for row in self._data:
+        for row in rows:
             row_id = self._get_next_id()
             self._storage.set(self._row_key(row_id), json.dumps(row, ensure_ascii=False))
             count += 1
@@ -245,12 +251,11 @@ class KVQueryBuilder(BaseQueryBuilder):
         return [tuple(r.values()) for _, r in rows]
 
     def _exec_update(self) -> int:
-        if not isinstance(self._data, dict):
-            raise ValueError(i18n.t("core.kvbuilder.update_needs_dict"))
+        data = self._require_data(dict, "core.kvbuilder.update_needs_dict")
         count = 0
         for row_id, row in self._scan_rows():
             if self._match_row(row):
-                row.update(self._data)
+                row.update(data)
                 self._storage.set(self._row_key(row_id), json.dumps(row, ensure_ascii=False))
                 count += 1
         return count
@@ -308,16 +313,14 @@ class KVQueryBuilder(BaseQueryBuilder):
     async def aExecute(self) -> list[tuple] | int:
         """异步执行查询"""
         if self._operation == "insert":
-            if not isinstance(self._data, dict):
-                raise ValueError(i18n.t("core.kvbuilder.insert_needs_dict"))
+            data = self._require_data(dict, "core.kvbuilder.insert_needs_dict")
             row_id = self._get_next_id()
-            await self._storage.aset(self._row_key(row_id), json.dumps(self._data, ensure_ascii=False))
+            await self._storage.aset(self._row_key(row_id), json.dumps(data, ensure_ascii=False))
             return 1
         if self._operation == "insert_multi":
-            if not isinstance(self._data, list):
-                raise ValueError(i18n.t("core.kvbuilder.insert_multi_needs_list"))
+            rows = self._require_data(list, "core.kvbuilder.insert_multi_needs_list")
             count = 0
-            for row in self._data:
+            for row in rows:
                 row_id = self._get_next_id()
                 await self._storage.aset(self._row_key(row_id), json.dumps(row, ensure_ascii=False))
                 count += 1
@@ -325,12 +328,11 @@ class KVQueryBuilder(BaseQueryBuilder):
         if self._operation == "select":
             return await self._aexec_select()
         if self._operation == "update":
-            if not isinstance(self._data, dict):
-                raise ValueError(i18n.t("core.kvbuilder.update_needs_dict"))
+            data = self._require_data(dict, "core.kvbuilder.update_needs_dict")
             count = 0
             for row_id, row in await self._ascan_rows():
                 if self._match_row(row):
-                    row.update(self._data)
+                    row.update(data)
                     await self._storage.aset(self._row_key(row_id), json.dumps(row, ensure_ascii=False))
                     count += 1
             return count

{erispulse-2.8.0.dev2 → erispulse-2.8.2}/src/ErisPulse/Core/Bases/module.py

@@ -51,6 +51,7 @@ class ModuleMeta:
     tags: list[str] = field(default_factory=list)
     commands: list[str] | None = None
     services: "list[str | dict[str, Any]] | None" = None
+    min_sdk_version: str | None = None
 
     def to_dict(self) -> dict[str, Any]:
         """
@@ -112,6 +113,8 @@ class BaseModule(ABC):
             - 简单形态：``["get_history", "translate"]``（方法名，介绍自动取 docstring 首行）
             - 完整形态：``[{"name": "get_history", "description": "查询会话历史"}]``
               （``description`` 支持纯字符串或 i18n 字典，声明后覆盖 docstring）
+        - ``min_sdk_version``: 运行时所需最低 SDK 版本（如 ``"2.8.1"``；
+            SDK 低于该版本时框架在加载期明确报错并跳过本模块）
 
         **i18n 支持**：字段值可为纯字符串，或 i18n 字典
         ``{"i18n": "key.path", "default": "兜底文本"}``（与配置 description 约定一致）。

{erispulse-2.8.0.dev2 → erispulse-2.8.2}/src/ErisPulse/Core/Bases/router.py

@@ -590,7 +590,9 @@ class SseEmitter:
         import json as _json
 
         if self._closed:
-            raise RuntimeError("SSE connection is closed")
+            from ..i18n import i18n
+
+            raise RuntimeError(i18n.t("core.router.sse_closed"))
 
         payload_parts = []
 

{erispulse-2.8.0.dev2 → erispulse-2.8.2}/src/ErisPulse/Core/Bases/sql_base.py

@@ -26,12 +26,16 @@ from typing import Any
 
 from ..constants import (
     DEFAULT_KV_TABLE_NAME,
+    EVENT_STORAGE_READY,
+    EVENT_STORAGE_RECOVERED,
+    EVENT_STORAGE_UNREACHABLE,
     STORAGE_MAX_LIST_INDEX,
     STORAGE_POOL_CREATE_BACKOFF_SECS,
     STORAGE_POOL_CREATE_RETRIES,
     STORAGE_POOL_FAIL_COOLDOWN_SECS,
 )
 from ..i18n import i18n
+from ..lifecycle import lifecycle
 from ..logger import logger
 from .errors import StorageUnreachableError
 from .storage import _SENTINEL, BaseQueryBuilder, BaseStorage, _current_txn
@@ -694,9 +698,14 @@ class SQLStorageBase(BaseStorage):
 
         # 冷却期内快速失败：连接不可达时不阻塞调用方（框架继续运行，仅存储暂不可用）
         failed_until = getattr(self, "_resource_failed_until", 0.0)
+        was_cooling = failed_until > 0
         if failed_until > time.monotonic():
+            logger.trace(
+                i18n.t("core.storage.cooldown_fast_fail", backend=self.dialect.name)
+            )
             raise StorageUnreachableError(
-                f"{self.dialect.name}: 连接不可达（冷却期内，稍后自动重连）"
+                i18n.t("core.storage.cooldown", backend=self.dialect.name),
+                backend=self.dialect.name,
             )
 
         # 指数退避重试，规避远端瞬时拒绝（连接数限流、数据库重启窗口等）
@@ -732,8 +741,16 @@ class SQLStorageBase(BaseStorage):
                     error=last_error,
                 )
             )
+            await self._emit_storage_event(
+                EVENT_STORAGE_UNREACHABLE,
+                backend=self.dialect.name,
+                error=str(last_error),
+                cooldown=self._RESOURCE_FAIL_COOLDOWN_SECS,
+            )
             raise StorageUnreachableError(
-                f"{self.dialect.name}: {last_error}"
+                f"{self.dialect.name}: {last_error}",
+                backend=self.dialect.name,
+                cooldown=self._RESOURCE_FAIL_COOLDOWN_SECS,
             ) from last_error
 
         with self._resources_lock:
@@ -744,8 +761,27 @@ class SQLStorageBase(BaseStorage):
             self._loop_resources[loop] = resource
         # 建池成功：清除失败冷却（若曾进入冷却，此番重连试探成功即恢复）
         self._resource_failed_until = 0.0
+        logger.debug(i18n.t("core.storage.pool_ready", backend=self.dialect.name))
+        await self._emit_storage_event(EVENT_STORAGE_READY, backend=self.dialect.name)
+        if was_cooling:
+            logger.info(i18n.t("core.storage.recovered", backend=self.dialect.name))
+            await self._emit_storage_event(EVENT_STORAGE_RECOVERED, backend=self.dialect.name)
         return resource
 
+    async def _emit_storage_event(self, event: str, **data: Any) -> None:
+        """
+        {!--< internal-use >!--}
+        发出存储生命周期事件（``storage.ready`` / ``storage.unreachable`` /
+        ``storage.recovered``），供外部感知连接状态变化（如 Dashboard 告警）。
+
+        后台发射（fire）：存储操作绝不等待观测者；lifecycle 未就绪或
+        处理异常时静默跳过，不影响存储操作本身。
+        """
+        try:
+            lifecycle.fire(event, data)
+        except Exception:
+            pass
+
     @asynccontextmanager
     async def _acquire(self) -> AsyncIterator[Any]:
         """