ErisPulse 2.7.0.dev5__tar.gz → 2.7.1.dev0__tar.gz

{erispulse-2.7.0.dev5 → erispulse-2.7.1.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ErisPulse
-Version: 2.7.0.dev5
+Version: 2.7.1.dev0
 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

{erispulse-2.7.0.dev5 → erispulse-2.7.1.dev0}/pyproject.toml

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

{erispulse-2.7.0.dev5 → erispulse-2.7.1.dev0}/src/ErisPulse/CLI/commands/create.py

@@ -462,33 +462,50 @@ class {converter_name}(BaseConverter):
         return None
 """
 
-_README_MODULE = """# {name}
+_README_MODULE = """<div align="center">
 
-{description}
+<img src="https://raw.githubusercontent.com/ErisPulse/ErisPulse/main/.github/assets/ErisPulseLogo.png" width="180" alt="{name}" />
+
+# {name}
+
+**{description}**
+
+<p>
+  <a href="https://pypi.org/project/ErisPulse-{name}/"><img src="https://img.shields.io/pypi/v/ErisPulse-{name}?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI"></a>
+  <a href="https://pypi.org/project/ErisPulse-{name}/"><img src="https://img.shields.io/badge/Python-3.10+-FFD43B?style=for-the-badge&logo=python&logoColor=blue" alt="Python"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" alt="License"></a>
+  <a href="https://github.com/ErisPulse/ErisPulse"><img src="https://img.shields.io/badge/Powered_by-ErisPulse-FF6B9D?style=for-the-badge&logo=bookstack&logoColor=white" alt="ErisPulse"></a>
+</p>
+
+</div>
+
+---
 
 ## 安装
 
 ```bash
 epsdk install ErisPulse-{name}
 ```
+"""
 
-## 使用
+_README_ADAPTER = """<div align="center">
 
-模块会自动加载，你也可以通过 `sdk.{name}` 访问模块实例。
+<img src="https://raw.githubusercontent.com/ErisPulse/ErisPulse/main/.github/assets/ErisPulseLogo.png" width="180" alt="{name}" />
 
-## 配置
+# {name}
 
-在 `config.toml` 中添加:
+**{description}**
 
-```toml
-[{name}]
-enabled = true
-```
-"""
+<p>
+  <a href="https://pypi.org/project/ErisPulse-{name}/"><img src="https://img.shields.io/pypi/v/ErisPulse-{name}?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI"></a>
+  <a href="https://pypi.org/project/ErisPulse-{name}/"><img src="https://img.shields.io/badge/Python-3.10+-FFD43B?style=for-the-badge&logo=python&logoColor=blue" alt="Python"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" alt="License"></a>
+  <a href="https://github.com/ErisPulse/ErisPulse"><img src="https://img.shields.io/badge/Powered_by-ErisPulse-FF6B9D?style=for-the-badge&logo=bookstack&logoColor=white" alt="ErisPulse"></a>
+</p>
 
-_README_ADAPTER = """# {name}
+</div>
 
-{description}
+---
 
 ## 安装
 
@@ -561,6 +578,22 @@ def _validate_name(name: str) -> bool:
     return all(c.isalnum() or c == "_" for c in name)
 
 
+def _copy_erispulse_logo(project_dir: Path) -> None:
+    """
+    将 ErisPulseLogo.png 拷贝到项目的 .github/assets/ 目录
+
+    :param project_dir: [Path] 项目根目录
+    """
+    import shutil
+
+    logo_src = Path(__file__).parent.parent / "assets" / "ErisPulseLogo.png"
+    if not logo_src.exists():
+        return
+    dest = project_dir / ".github" / "assets" / "ErisPulseLogo.png"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(logo_src, dest)
+
+
 def _scaffold_text(name: str) -> dict:
     """
     构建当前语言的脚手架文案映射，并预填充 {name} 占位符

{erispulse-2.7.0.dev5 → erispulse-2.7.1.dev0}/src/ErisPulse/Core/Bases/config_schema.py

@@ -424,6 +424,58 @@ def dict_to_dataclass(config_class: type, data: dict):
     return config_class(**kwargs)
 
 
+def _notify_instance_config_update(
+    instance: Any,
+    old_dict: dict | None,
+    new_dict: dict | None,
+    *,
+    i18n_key: str,
+    log_params: dict,
+) -> None:
+    """
+    调用实例的 ``on_config_update`` 回调，传入类型安全的配置对象
+
+    若实例声明了 ``ConfigClass``，则将字典通过 :func:`dict_to_dataclass`
+    转换为 dataclass 实例；否则原样传入字典。回调中抛出的异常会被捕获
+    并按指定的 i18n 键记录日志，不会向上传播。
+
+    供 ``ModuleManager`` 与 ``AdapterManager`` 的配置热更新路由共用，
+    避免在两处重复实现字典→dataclass 转换 + 异常兜底逻辑。
+
+    {!--< internal-use >!--}
+    {!--< /internal-use >!--}
+
+    :param instance: 模块/适配器实例（需实现 ``on_config_update``）
+    :param old_dict: 变更前的配置字典（可能为 None）
+    :param new_dict: 变更后的配置字典（可能为 None）
+    :param i18n_key: 回调异常日志的 i18n 键（如 ``core.module.config_update_failed``）
+    :param log_params: 异常日志的额外格式化参数（如 ``{"name": "MyModule"}``）
+    """
+    config_class = getattr(instance, "ConfigClass", None)
+    try:
+        if config_class is not None:
+            old_config = (
+                dict_to_dataclass(config_class, old_dict) if old_dict else None
+            )
+            new_config = (
+                dict_to_dataclass(config_class, new_dict) if new_dict else None
+            )
+        else:
+            old_config = old_dict
+            new_config = new_dict
+        instance.on_config_update(old_config, new_config)
+    except Exception as e:
+        try:
+            from ErisPulse.Core.i18n import i18n
+            from ErisPulse.Core.logger import logger
+
+            params = dict(log_params)
+            params["error"] = e
+            logger.error(i18n.t(i18n_key, **params))
+        except Exception:
+            pass
+
+
 def validate_config(instance) -> list[str]:
     """
     校验 dataclass 实例

{erispulse-2.7.0.dev5 → erispulse-2.7.1.dev0}/src/ErisPulse/Core/Event/wrapper.py

@@ -1576,8 +1576,8 @@ class Event(dict):
                         future.set_result(raw)
                     except asyncio.InvalidStateError:
                         pass
-            except Exception:
-                pass
+            except Exception as _e:
+                logger.trace(f"[Event] onebot wait handler 异常: {_e}")
 
         handler_wrapper = {"func": _temp_handler, "platform": None}
         adapter._onebot_handlers[event_type].append(handler_wrapper)
@@ -1919,7 +1919,8 @@ class Conversation:
                 try:
                     if not cond(self.context):
                         continue
-                except Exception:
+                except Exception as _e:
+                    logger.trace(f"[Conversation] 字段 condition 执行异常，跳过: {_e}")
                     continue
             filtered_fields.append(f)
 
@@ -2115,8 +2116,8 @@ class Conversation:
                 if event:
                     self._event = event
                 return True
-        except Exception:
-            pass
+        except Exception as _e:
+            logger.trace(f"[Conversation] resume 失败: {_e}")
         return False
 
     async def clear_saved(self):
@@ -2133,8 +2134,8 @@ class Conversation:
             platform = self._event.get_platform()
             key = f"{CONVERSATION_KEY_PREFIX}:{platform}:{user_id}"
             storage.delete(key)
-        except Exception:
-            pass
+        except Exception as _e:
+            logger.trace(f"[Conversation] clear_saved 失败: {_e}")
 
 
 __all__ = [

{erispulse-2.7.0.dev5 → erispulse-2.7.1.dev0}/src/ErisPulse/Core/adapter.py

@@ -235,29 +235,15 @@ class AdapterManager(ManagerBase):
         {!--< internal-use >!--}
         调用适配器的 on_config_update 回调，传入类型安全的配置对象
         """
-        config_class = getattr(instance, "ConfigClass", None)
-        try:
-            if config_class is not None:
-                from ..runtime.config_schema import dict_to_dataclass
-
-                old_config = (
-                    dict_to_dataclass(config_class, old_dict) if old_dict else None
-                )
-                new_config = (
-                    dict_to_dataclass(config_class, new_dict) if new_dict else None
-                )
-            else:
-                old_config = old_dict
-                new_config = new_dict
-            instance.on_config_update(old_config, new_config)
-        except Exception as e:
-            logger.error(
-                i18n.t(
-                    "core.adapter.config_update_failed",
-                    platform=platform or instance.__class__.__name__,
-                    error=e,
-                )
-            )
+        from ..Core.Bases.config_schema import _notify_instance_config_update
+
+        _notify_instance_config_update(
+            instance,
+            old_dict,
+            new_dict,
+            i18n_key="core.adapter.config_update_failed",
+            log_params={"platform": platform or instance.__class__.__name__},
+        )
 
     # ==================== 适配器注册与管理 ====================
 

{erispulse-2.7.0.dev5 → erispulse-2.7.1.dev0}/src/ErisPulse/Core/config.py

@@ -50,6 +50,7 @@ class ConfigManager:
         self._lock = threading.RLock()  # 线程安全锁
         self._file_lock = threading.RLock()  # 文件操作锁
         self._atexit_registered = False  # atexit 钩子注册标记
+        self._last_self_write_mtime: float = 0.0  # 框架自身最后一次刷盘的 mtime
         self._migrate_config()  # 迁移旧配置文件
         self._load_config()  # 初始化时加载配置
         self._watch_config_file()  # 记录配置文件 mtime 以便后续监听
@@ -77,19 +78,21 @@ class ConfigManager:
                 if self._watcher_stop.is_set():
                     break
                 try:
-                    if self._check_file_change():
-                        # 文件被外部修改 → 取消待写入定时器并丢弃脏键，
-                        # 避免 _flush_config 回写旧值覆盖用户编辑。
-                        if self._write_timer:
-                            self._write_timer.cancel()
-                            self._write_timer = None
-                        self._dirty_keys.clear()
-                        with self._lock:
-                            old_cache = self._cache.copy() if self._cache else {}
-                        # 仅在成功加载时广播变更，半成品/语法错误的 TOML
-                        # 不再以空配置形式触发 config.updated
-                        if self._load_config():
-                            self._emit_config_updated(old_cache)
+                    with self._lock:
+                        # _check_file_change 已能区分"框架自身刷盘"与"外部修改"：
+                        # 自身刷盘的 mtime 与 _last_self_write_mtime 一致 → 返回 False
+                        if not self._check_file_change():
+                            continue
+                        # 真正的外部修改：重载文件到缓存。
+                        # 不清空 _dirty_keys、不取消 _write_timer —— 待写键会在
+                        # 下次 _flush_config 时与外部内容合并（脏键优先），
+                        # 避免丢失本进程尚未落盘的写入。
+                        old_cache = self._cache.copy() if self._cache else {}
+                        loaded = self._load_config()
+                    # 仅在成功加载时广播变更，半成品/语法错误的 TOML
+                    # 不再以空配置形式触发 config.updated
+                    if loaded:
+                        self._emit_config_updated(old_cache)
                 except Exception as e:
                     # 监听异常不再静默吞掉，便于排查 watcher 故障
                     self._log_config_error(
@@ -365,6 +368,7 @@ class ConfigManager:
                     # 从而重复触发 config.updated（与 config.set 路由重复调用 on_config_update）
                     try:
                         self._config_mtime = Path(self.CONFIG_FILE).stat().st_mtime
+                        self._last_self_write_mtime = self._config_mtime
                     except OSError:
                         pass
 
@@ -504,8 +508,10 @@ class ConfigManager:
         检测配置文件是否被外部程序或用户手动编辑
 
         对比记录的 mtime 与当前文件 mtime，若不一致说明文件已被外部修改。
+        若变化后的 mtime 与框架自身最后一次刷盘的 mtime（``_last_self_write_mtime``）
+        一致，则判定为框架自身的写入而非外部修改，返回 False。
 
-        :return: bool 文件是否已变化
+        :return: bool 文件是否被外部修改
 
         {!--< internal-use >!--}
         {!--< /internal-use >!--}
@@ -517,6 +523,10 @@ class ConfigManager:
             current_mtime = config_path.stat().st_mtime
             if current_mtime != self._config_mtime:
                 self._config_mtime = current_mtime
+                # 若 mtime 与框架自身最后一次刷盘一致，说明是 _flush_config 的
+                # 写入，不算外部修改（避免 watcher 误触发重载）
+                if current_mtime == self._last_self_write_mtime:
+                    return False
                 return True
         except OSError:
             pass

{erispulse-2.7.0.dev5 → erispulse-2.7.1.dev0}/src/ErisPulse/Core/constants.py

@@ -633,6 +633,17 @@ DEFAULT_OFFLINE_BOT_EXPIRY_SECS: Final[int] = 3600
 # 修改影响: 设大减少 CPU 中断但内存峰值更高，设小更频繁回收但增加开销。0 表示禁用。
 DEFAULT_PROACTIVE_GC_INTERVAL_SECS: Final[int] = 300
 
+# 主动 GC 分代（generation）。
+# 运行时行为。gc.collect(generation) 只回收指定代及更年轻的对象：0=最年轻代（最轻量），
+# 1=中年代，2=最老代（覆盖最全）。默认 2 兼顾覆盖面与频率可控。
+# 修改影响: 设低减少单次扫描开销但回收不彻底，设高（2）覆盖更全但单次更重。
+DEFAULT_PROACTIVE_GC_GENERATION: Final[int] = 2
+
+# 主动 GC 全量收集周期（每 N 轮做一次全量 gc.collect()）。
+# 运行时行为。0 表示禁用（仅按 generation 回收），N>0 表示每 N 轮额外触发一次全量回收。
+# 修改影响: 设低（如 5）确保周期性深度回收，设高或 0 减少长尾暂停。
+DEFAULT_PROACTIVE_GC_FULL_EVERY: Final[int] = 0
+
 # shutdown 时等待在途事件处理器完成的最长时间（秒）。
 # 运行时行为。适配器关闭时取消所有 pending handler tasks 后等待它们退出的耐心时间。
 # 修改影响: 设大确保处理器完整结束，设小加速关闭流程。
@@ -743,6 +754,8 @@ __all__ = [
     "DEFAULT_MODULE_ENABLED",
     "DEFAULT_MODULE_PRIORITY",
     "DEFAULT_OFFLINE_BOT_EXPIRY_SECS",
+    "DEFAULT_PROACTIVE_GC_FULL_EVERY",
+    "DEFAULT_PROACTIVE_GC_GENERATION",
     "DEFAULT_PROACTIVE_GC_INTERVAL_SECS",
     "DEFAULT_RATE_LIMIT_CLEANUP_INTERVAL_SECS",
     "DEFAULT_RATE_LIMIT_MAX_REQUESTS",

{erispulse-2.7.0.dev5 → erispulse-2.7.1.dev0}/src/ErisPulse/Core/module.py

@@ -184,27 +184,15 @@ class ModuleManager(ManagerBase):
         :param old_dict: 变更前的配置字典（可能为 None）
         :param new_dict: 变更后的配置字典（可能为 None）
         """
-        config_class = getattr(instance, "ConfigClass", None)
-        try:
-            if config_class is not None:
-                from ..runtime.config_schema import dict_to_dataclass
-
-                old_config = (
-                    dict_to_dataclass(config_class, old_dict) if old_dict else None
-                )
-                new_config = (
-                    dict_to_dataclass(config_class, new_dict) if new_dict else None
-                )
-            else:
-                old_config = old_dict
-                new_config = new_dict
-            instance.on_config_update(old_config, new_config)
-        except Exception as e:
-            logger.error(
-                i18n.t(
-                    "core.module.config_update_failed", name=module_name, error=e
-                )
-            )
+        from ..Core.Bases.config_schema import _notify_instance_config_update
+
+        _notify_instance_config_update(
+            instance,
+            old_dict,
+            new_dict,
+            i18n_key="core.module.config_update_failed",
+            log_params={"name": module_name},
+        )
 
     # ==================== 模块注册与管理 ====================
 

{erispulse-2.7.0.dev5 → erispulse-2.7.1.dev0}/src/ErisPulse/runtime/__init__.py

@@ -51,6 +51,8 @@ __all__ = [
     # 通用配置 Schema（适配器/模块/外部项目均可使用）
     "BaseConfig",
     "BotAccountConfig",
+    "I18nConfig",
+    "SECRET_REDACTED",
     # 异常处理
     "ExceptionHandler",
     "async_exception_handler",
@@ -78,6 +80,7 @@ __all__ = [
     # 异常诊断
     "log_diagnostic",
     "log_snapshot",
+    "redact_secret",
     "register_config_i18n",
     "resolve_config_schema",
     "setup_exception_handling",
@@ -99,10 +102,13 @@ _LAZY_FROM_CONFIG_SCHEMA = {
     "AdapterConfig",
     "BaseConfig",
     "BotAccountConfig",
+    "I18nConfig",
+    "SECRET_REDACTED",
     "dataclass_to_defaults_dict",
     "dataclass_to_toml_with_comments",
     "dict_to_dataclass",
     "get_config_schema",
+    "redact_secret",
     "register_config_i18n",
     "resolve_config_schema",
     "validate_config",

{erispulse-2.7.0.dev5 → erispulse-2.7.1.dev0}/src/ErisPulse/runtime/frame_config.py

@@ -21,6 +21,8 @@ from ..Core.constants import (
     DEFAULT_LOG_MEMORY_LIMIT,
     DEFAULT_MESSAGE_IGNORE_SELF,
     DEFAULT_OFFLINE_BOT_EXPIRY_SECS,
+    DEFAULT_PROACTIVE_GC_FULL_EVERY,
+    DEFAULT_PROACTIVE_GC_GENERATION,
     DEFAULT_PROACTIVE_GC_INTERVAL_SECS,
     DEFAULT_SERVER_AUTO_START,
     DEFAULT_SERVER_HOST,
@@ -79,6 +81,8 @@ DEFAULT_ERISPULSE_CONFIG = {
         # 性能优化与主动 GC 配置
         "handler_max_concurrency": DEFAULT_HANDLER_MAX_CONCURRENCY,
         "proactive_gc_interval": DEFAULT_PROACTIVE_GC_INTERVAL_SECS,
+        "proactive_gc_generation": DEFAULT_PROACTIVE_GC_GENERATION,
+        "proactive_gc_full_every": DEFAULT_PROACTIVE_GC_FULL_EVERY,
         "offline_bot_expiry": DEFAULT_OFFLINE_BOT_EXPIRY_SECS,
     },
     "i18n": {

{erispulse-2.7.0.dev5 → erispulse-2.7.1.dev0}/src/ErisPulse/sdk.py

@@ -23,6 +23,8 @@ from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
 
 from .Core.constants import (
+    DEFAULT_PROACTIVE_GC_FULL_EVERY,
+    DEFAULT_PROACTIVE_GC_GENERATION,
     DEFAULT_PROACTIVE_GC_INTERVAL_SECS,
     DEFAULT_UNINIT_TIMEOUT_SECS,
     HARD_RESTART_EXIT_CODE,
@@ -569,6 +571,16 @@ class SDK:
                     },
                 )
 
+                # 冻结框架对象：将当前所有已跟踪对象移入永久代，
+                # 后续 gc.collect() 不再扫描框架单例/缓存/模块/适配器实例，
+                # 仅回收运行期新建的临时对象，降低 GC 暂停与误回收风险。
+                import gc as _gc
+
+                try:
+                    _gc.freeze()
+                except Exception:
+                    pass
+
                 # 启动主动 GC 后台任务
                 self._sdk._start_proactive_gc()
 
@@ -834,39 +846,57 @@ class SDK:
         启动主动 GC 后台任务
 
         定期执行 Python GC 和内部资源回收（离线 Bot 清理等），
-        防止长期运行时的内存增长。间隔由框架配置 proactive_gc_interval 控制。
+        防止长期运行时的内存增长。
+
+        GC 行为由三项框架配置控制（均支持热更新）：
+
+        - ``proactive_gc_interval``: 回收间隔秒数（0 禁用）
+        - ``proactive_gc_generation``: 回收分代（0/1/2，默认 2=最老代）
+        - ``proactive_gc_full_every``: 每 N 轮额外做一次全量回收（0 禁用）
+
+        初始化阶段已调用 ``gc.freeze()`` 将框架对象移入永久代，
+        此处 ``gc.collect()`` 仅扫描运行期新建对象。
         """
         # 停止已有的 GC 任务
         self._stop_proactive_gc()
 
-        def _read_gc_interval() -> int:
+        def _read_gc_config() -> tuple[int, int, int]:
             interval = DEFAULT_PROACTIVE_GC_INTERVAL_SECS
+            generation = DEFAULT_PROACTIVE_GC_GENERATION
+            full_every = DEFAULT_PROACTIVE_GC_FULL_EVERY
             try:
                 from .runtime import get_framework_config
 
-                interval = get_framework_config().get(
-                    "proactive_gc_interval", interval
-                )
+                fw = get_framework_config()
+                interval = fw.get("proactive_gc_interval", interval)
+                generation = fw.get("proactive_gc_generation", generation)
+                full_every = fw.get("proactive_gc_full_every", full_every)
             except Exception:
                 pass
-            return interval
+            return interval, generation, full_every
 
-        if _read_gc_interval() <= 0:
+        if _read_gc_config()[0] <= 0:
             return  # 配置禁用
 
         async def _gc_loop():
             import gc
 
+            round_count = 0
             while True:
                 try:
-                    # 每轮重新读取间隔，支持 proactive_gc_interval 热更新
-                    interval = _read_gc_interval()
+                    # 每轮重新读取配置，支持热更新
+                    interval, generation, full_every = _read_gc_config()
                     if interval <= 0:
                         # 配置运行时禁用了 GC，停止循环
                         break
                     await asyncio.sleep(interval)
-                    # 1. Python GC
-                    collected = gc.collect()
+                    round_count += 1
+                    # 1. Python GC —— 按分代回收，可选周期性全量
+                    do_full = full_every > 0 and round_count % full_every == 0
+                    if do_full:
+                        collected = gc.collect()
+                    else:
+                        collected = gc.collect(generation)
                     # 2. 内部资源回收
                     try:
                         adapter_mgr = self.adapter