ErisPulse 2.7.1.dev2__tar.gz → 2.7.1.dev3__tar.gz

{erispulse-2.7.1.dev2 → erispulse-2.7.1.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ErisPulse
-Version: 2.7.1.dev2
+Version: 2.7.1.dev3
 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.1.dev2 → erispulse-2.7.1.dev3}/pyproject.toml

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

{erispulse-2.7.1.dev2 → erispulse-2.7.1.dev3}/src/ErisPulse/Core/Event/base.py

@@ -288,7 +288,7 @@ class BaseEventHandler:
                     "elapsed_ms": round(_elapsed_0 * 1000, 2),
                     "processed": event.is_processed(),
                 })
-                if event.is_processed():
+                if event.is_stopped():
                     break
                 continue
 
@@ -325,8 +325,8 @@ class BaseEventHandler:
                             "handler": _h_name,
                             "owner": _h_owner,
                         })
-                if copy.is_processed():
-                    event.mark_processed()
+                # _processed / _propagation_stopped 已由上方字段合并循环传播，
+                # 此处不再调用 mark_processed()（其默认会触发 _propagation_stopped 副作用）
 
             # 冲突告警：同一 field 被多个同优先级 handler 修改
             for field, mods in _modified_tracker.items():
@@ -345,7 +345,7 @@ class BaseEventHandler:
                             )
                         )
 
-            if event.is_processed():
+            if event.is_stopped():
                 break
 
         # 输出事件链路追踪日志

{erispulse-2.7.1.dev2 → erispulse-2.7.1.dev3}/src/ErisPulse/Core/Event/command.py

@@ -14,7 +14,10 @@ ErisPulse 命令处理模块
 import asyncio
 import inspect
 from collections.abc import Awaitable, Callable
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .wrapper import Event
 
 from ...runtime import get_event_config
 from ...runtime.context import current_owner, handler_waits
@@ -375,6 +378,11 @@ class CommandHandler:
 
         :param event: 消息事件数据
         """
+        # 防御性归一化：确保 event 为 Event 实例，使 mark_processed 等方法可用
+        from .wrapper import Event as _Event
+
+        if not isinstance(event, _Event):
+            event = _Event(event)
 
         # 检查是否已经被其他处理器标记为已处理
         if event.get("_processed"):
@@ -399,7 +407,7 @@ class CommandHandler:
             )
             return
 
-        async def _process_text_for_command(event: dict[str, Any], text: str) -> bool:
+        async def _process_text_for_command(event: "Event", text: str) -> bool:
             """
             处理文本内容，尝试匹配并执行命令
 
@@ -501,7 +509,7 @@ class CommandHandler:
         return
 
     async def _try_execute_command(
-        self, event: dict[str, Any], original_text: str, check_text: str, prefix: str
+        self, event: "Event", original_text: str, check_text: str, prefix: str
     ) -> bool:
         """
         尝试执行命令
@@ -611,8 +619,8 @@ class CommandHandler:
 
             event["command"] = command_info
 
-            # 标记事件已被处理
-            event["_processed"] = True
+            # 标记事件已被处理（认领 + 阻断，阻止低优先级处理器再介入）
+            event.mark_processed()
 
             # 钩子: 命令匹配
             from ..lifecycle import lifecycle
@@ -694,7 +702,7 @@ class CommandHandler:
         )
         return False
 
-    async def _check_pending_reply(self, event: dict[str, Any]):
+    async def _check_pending_reply(self, event: "Event"):
         """
         检查是否是等待回复的消息
 
@@ -745,8 +753,8 @@ class CommandHandler:
             # 清理等待信息
             del self._waiting_replies[wait_key]
 
-            # 标记事件已被处理
-            event["_processed"] = True
+            # 标记事件已被处理（认领 + 阻断，阻止低优先级处理器再介入）
+            event.mark_processed()
 
     async def _send_permission_denied(self, event: dict[str, Any]):
         """

{erispulse-2.7.1.dev2 → erispulse-2.7.1.dev3}/src/ErisPulse/Core/Event/wrapper.py

@@ -1684,11 +1684,14 @@ class Event(dict):
 
     def to_dict(self) -> dict[str, Any]:
         """
-        转换为字典
+        转换为字典（过滤内部键）
+
+        过滤以 ``_`` 开头的内部键（如 ``_processed``/``_propagation_stopped``），
+        只返回事件数据。
 
         :return: 事件数据字典
         """
-        return dict(self)
+        return {k: v for k, v in self.items() if not k.startswith("_")}
 
     def is_processed(self) -> bool:
         """
@@ -1698,11 +1701,71 @@ class Event(dict):
         """
         return self.get("_processed", False)
 
-    def mark_processed(self):
+    def mark_processed(self, claim: bool = True, stop: bool = True):
         """
-        标记为已处理
+        标记事件为已处理
+
+        认领与阻断是两个**正交**的语义，可独立控制：
+
+        - **认领（claim）**：标记事件已被本处理器处理（写入 ``_processed``）。
+          命令分发器看到已认领的事件会跳过去重，避免同一消息被多个命令处理器
+          重复处理。典型场景：命令匹配成功后认领，阻止命令分发器再介入。
+        - **阻断（stop）**：阻止事件向更低优先级处理器传播（写入
+          ``_propagation_stopped``）。低优先级处理器（如 ``on_message``）将不再
+          看到该事件。典型场景：高优先级处理器已完整处理事件，不希望低优先级再执行。
+
+        参数组合：
+        - ``mark_processed()``：认领 + 阻断（默认）
+        - ``mark_processed(stop=False)``：仅认领，不阻断 —— 事件继续流向低优先级观察者
+        - ``mark_processed(claim=False)``：仅阻断，不认领 —— 低优先级不执行，但不做去重
+
+        :param claim: 是否认领事件（标记已处理，命令分发去重）（默认 True）
+        :param stop: 是否阻断向低优先级处理器传播（默认 True）
+
+        :example:
+        >>> event.mark_processed()            # 认领 + 阻断（默认）
+        >>> event.mark_processed(stop=False)  # 仅认领，低优先级仍能看到
+        >>> event.mark_processed(claim=False) # 仅阻断，不标记已处理
+        """
+        if claim:
+            self["_processed"] = True
+        if stop:
+            self["_propagation_stopped"] = True
+
+    def done(self, claim: bool = True, stop: bool = True):
+        """
+        标记事件完成（:meth:`mark_processed` 的别名）
+
+        与 :meth:`mark_processed` 完全等价，提供更简洁的写法。
+
+        :param claim: 是否认领事件（标记已处理，命令分发去重）（默认 True）
+        :param stop: 是否阻断向低优先级处理器传播（默认 True）
+
+        :example:
+        >>> @command("help")
+        ... async def help_cmd(event):
+        ...     event.done()            # 认领 + 阻断（命令处理完的标准做法）
+        >>>
+        >>> @message.on_message(priority=50)
+        ... async def observer(event):
+        ...     event.done(stop=False)  # 仅认领，低优先级仍能看到（日志/统计）
+        >>>
+        >>> @message.on_message(priority=100)
+        ... async def firewall(event):
+        ...     if denied(event):
+        ...         event.done(claim=False)  # 仅阻断，不标记已处理
+        """
+        self.mark_processed(claim=claim, stop=stop)
+
+    def is_stopped(self) -> bool:
+        """
+        事件传播是否已被阻断（是否已停止向低优先级处理器传播）
+
+        对应 ``done(stop=True)`` / ``mark_processed(stop=True)`` 的阻断效果。
+
+        :return: 是否已阻断传播
         """
-        self["_processed"] = True
+        return self.get("_propagation_stopped", False)
 
     # ==================== 魔术方法 ====================
 

{erispulse-2.7.1.dev2 → erispulse-2.7.1.dev3}/src/ErisPulse/Core/constants.py

@@ -635,14 +635,34 @@ DEFAULT_PROACTIVE_GC_INTERVAL_SECS: Final[int] = 300
 
 # 主动 GC 分代（generation）。
 # 运行时行为。gc.collect(generation) 只回收指定代及更年轻的对象：0=最年轻代（最轻量），
-# 1=中年代，2=最老代（覆盖最全）。默认 2 兼顾覆盖面与频率可控。
+# 1=中年代，2=最老代（覆盖最全，等价于全量 gc.collect()）。默认 0 使常规轮次保持轻量；
+# 深度回收由 proactive_gc_full_every 周期性触发。
 # 修改影响: 设低减少单次扫描开销但回收不彻底，设高（2）覆盖更全但单次更重。
-DEFAULT_PROACTIVE_GC_GENERATION: Final[int] = 2
+DEFAULT_PROACTIVE_GC_GENERATION: Final[int] = 0
 
 # 主动 GC 全量收集周期（每 N 轮做一次全量 gc.collect()）。
 # 运行时行为。0 表示禁用（仅按 generation 回收），N>0 表示每 N 轮额外触发一次全量回收。
+# 全量回收受 proactive_gc_memory_growth_mb 内存增长门限约束，无增长时跳过。
 # 修改影响: 设低（如 5）确保周期性深度回收，设高或 0 减少长尾暂停。
-DEFAULT_PROACTIVE_GC_FULL_EVERY: Final[int] = 0
+DEFAULT_PROACTIVE_GC_FULL_EVERY: Final[int] = 20
+
+# 主动 GC 全量回收的内存增长门限（MB）。
+# 运行时行为。周期性全量回收前，对比上次全量后的内存基线（优先 tracemalloc，其次 RSS），
+# 仅当增长超过此值才真正触发 gc.collect()，避免内存稳定时空转。0 表示不设门限（每轮都回收）。
+# 修改影响: 设小更频繁深度回收（更多暂停），设大更保守（内存峰值略高但 CPU 开销更低）。
+DEFAULT_PROACTIVE_GC_MEMORY_GROWTH_MB: Final[int] = 32
+
+# 主动 GC 空闲门控（仅在事件处理器空闲时执行 Python GC）。
+# 运行时行为。开启后，若 adapter 存在未完成的 pending handler task（事件洪峰），
+# 本轮跳过 Python GC，避免 GC 停顿与消息处理竞争。内部资源回收不受影响。
+# 修改影响: 开启降低洪峰期延迟，但可能推迟内存回收。
+DEFAULT_PROACTIVE_GC_IDLE_ONLY: Final[bool] = False
+
+# 主动 GC 常规轮次的 gen0 垃圾量下限。
+# 运行时行为。gc.get_count()[0] 低于此值时跳过 Python GC（无意义空转），
+# 高于此值才按 generation 回收。0 表示始终回收。
+# 修改影响: 设高（如 700=跟随 Python 自动回收节奏）更多轮次被跳过，设低更积极回收。
+DEFAULT_PROACTIVE_GC_GEN0_MIN: Final[int] = 500
 
 # shutdown 时等待在途事件处理器完成的最长时间（秒）。
 # 运行时行为。适配器关闭时取消所有 pending handler tasks 后等待它们退出的耐心时间。
@@ -755,8 +775,11 @@ __all__ = [
     "DEFAULT_MODULE_PRIORITY",
     "DEFAULT_OFFLINE_BOT_EXPIRY_SECS",
     "DEFAULT_PROACTIVE_GC_FULL_EVERY",
+    "DEFAULT_PROACTIVE_GC_GEN0_MIN",
     "DEFAULT_PROACTIVE_GC_GENERATION",
+    "DEFAULT_PROACTIVE_GC_IDLE_ONLY",
     "DEFAULT_PROACTIVE_GC_INTERVAL_SECS",
+    "DEFAULT_PROACTIVE_GC_MEMORY_GROWTH_MB",
     "DEFAULT_RATE_LIMIT_CLEANUP_INTERVAL_SECS",
     "DEFAULT_RATE_LIMIT_MAX_REQUESTS",
     "DEFAULT_RATE_LIMIT_WINDOW_SECS",

{erispulse-2.7.1.dev2 → erispulse-2.7.1.dev3}/src/ErisPulse/Core/i18n/locales/en.py

@@ -51,6 +51,8 @@ TRANSLATIONS = {
     "core.sdk.uninit.critical_error": "SDK uninitialization critical error: {error}",
     "core.sdk.uninit.client_close_failed": "Failed to close HTTP client connection pool: {error}",
     "core.sdk.gc.collected": "[GC] Python collected {collected} object(s), evicted {evicted} offline bot(s)",
+    "core.sdk.gc.skipped": "[GC] Round skipped (reason: {reason})",
+    "core.sdk.gc.config_changed": "[GC] Proactive GC config changed, restarting task",
     # ==================== SDK Environment Preparation ====================
     "core.sdk.prepare.start": "Starting initialization",
     "core.sdk.prepare.starting": "Preparing initialization environment...",

{erispulse-2.7.1.dev2 → erispulse-2.7.1.dev3}/src/ErisPulse/Core/i18n/locales/ja.py

@@ -51,6 +51,8 @@ TRANSLATIONS = {
     "core.sdk.uninit.critical_error": "SDK 非初期化の重大なエラー: {error}",
     "core.sdk.uninit.client_close_failed": "HTTP クライアント接続プールのクローズに失敗しました: {error}",
     "core.sdk.gc.collected": "[GC] Python が {collected} 個のオブジェクトを回収し、{evicted} 個のオフライン Bot を削除しました",
+    "core.sdk.gc.skipped": "[GC] このラウンドはスキップされました（理由: {reason}）",
+    "core.sdk.gc.config_changed": "[GC] アクティブ GC 設定が変更されたため、タスクを再起動します",
     # ==================== SDK 環境準備 ====================
     "core.sdk.prepare.start": "初期化を開始します",
     "core.sdk.prepare.starting": "初期化環境を準備しています...",

{erispulse-2.7.1.dev2 → erispulse-2.7.1.dev3}/src/ErisPulse/Core/i18n/locales/ru.py

@@ -51,6 +51,8 @@ TRANSLATIONS = {
     "core.sdk.uninit.critical_error": "Критическая ошибка деинициализации SDK: {error}",
     "core.sdk.uninit.client_close_failed": "Не удалось закрыть пул соединений HTTP-клиента: {error}",
     "core.sdk.gc.collected": "[GC] Python собрал {collected} объект(ов), удалено {evicted} автономных бот(ов)",
+    "core.sdk.gc.skipped": "[GC] Цикл пропущен (причина: {reason})",
+    "core.sdk.gc.config_changed": "[GC] Конфигурация активного GC изменена, перезапуск задачи",
     # ==================== Подготовка окружения SDK ====================
     "core.sdk.prepare.start": "Начало инициализации",
     "core.sdk.prepare.starting": "Подготовка окружения инициализации...",

{erispulse-2.7.1.dev2 → erispulse-2.7.1.dev3}/src/ErisPulse/Core/i18n/locales/zh_cn.py

@@ -51,6 +51,8 @@ TRANSLATIONS = {
     "core.sdk.uninit.critical_error": "SDK反初始化严重错误: {error}",
     "core.sdk.uninit.client_close_failed": "关闭 HTTP 客户端连接池失败: {error}",
     "core.sdk.gc.collected": "[GC] Python 回收了 {collected} 个对象，清理了 {evicted} 个离线 Bot",
+    "core.sdk.gc.skipped": "[GC] 本轮跳过回收（原因: {reason}）",
+    "core.sdk.gc.config_changed": "[GC] 主动 GC 配置已变更，重启回收任务",
     # ==================== SDK 环境准备 ====================
     "core.sdk.prepare.start": "开始初始化",
     "core.sdk.prepare.starting": "准备初始化环境...",

{erispulse-2.7.1.dev2 → erispulse-2.7.1.dev3}/src/ErisPulse/Core/i18n/locales/zh_tw.py

@@ -51,6 +51,8 @@ TRANSLATIONS = {
     "core.sdk.uninit.critical_error": "SDK反初始化嚴重錯誤: {error}",
     "core.sdk.uninit.client_close_failed": "關閉 HTTP 客戶端連線池失敗: {error}",
     "core.sdk.gc.collected": "[GC] Python 回收了 {collected} 個物件，清理了 {evicted} 個離線 Bot",
+    "core.sdk.gc.skipped": "[GC] 本輪略過回收（原因: {reason}）",
+    "core.sdk.gc.config_changed": "[GC] 主動 GC 配置已變更，重新啟動回收任務",
     # ==================== SDK 環境準備 ====================
     "core.sdk.prepare.start": "開始初始化",
     "core.sdk.prepare.starting": "準備初始化環境...",

{erispulse-2.7.1.dev2 → erispulse-2.7.1.dev3}/src/ErisPulse/runtime/frame_config.py

@@ -22,8 +22,11 @@ from ..Core.constants import (
     DEFAULT_MESSAGE_IGNORE_SELF,
     DEFAULT_OFFLINE_BOT_EXPIRY_SECS,
     DEFAULT_PROACTIVE_GC_FULL_EVERY,
+    DEFAULT_PROACTIVE_GC_GEN0_MIN,
     DEFAULT_PROACTIVE_GC_GENERATION,
+    DEFAULT_PROACTIVE_GC_IDLE_ONLY,
     DEFAULT_PROACTIVE_GC_INTERVAL_SECS,
+    DEFAULT_PROACTIVE_GC_MEMORY_GROWTH_MB,
     DEFAULT_SERVER_AUTO_START,
     DEFAULT_SERVER_HOST,
     DEFAULT_SERVER_PORT,
@@ -83,6 +86,9 @@ DEFAULT_ERISPULSE_CONFIG = {
         "proactive_gc_interval": DEFAULT_PROACTIVE_GC_INTERVAL_SECS,
         "proactive_gc_generation": DEFAULT_PROACTIVE_GC_GENERATION,
         "proactive_gc_full_every": DEFAULT_PROACTIVE_GC_FULL_EVERY,
+        "proactive_gc_memory_growth_mb": DEFAULT_PROACTIVE_GC_MEMORY_GROWTH_MB,
+        "proactive_gc_idle_only": DEFAULT_PROACTIVE_GC_IDLE_ONLY,
+        "proactive_gc_gen0_min": DEFAULT_PROACTIVE_GC_GEN0_MIN,
         "offline_bot_expiry": DEFAULT_OFFLINE_BOT_EXPIRY_SECS,
     },
     "i18n": {

{erispulse-2.7.1.dev2 → erispulse-2.7.1.dev3}/src/ErisPulse/runtime/memory.py

@@ -12,6 +12,7 @@
 
 from __future__ import annotations
 
+from collections import OrderedDict
 from typing import Any
 
 __all__ = [
@@ -21,8 +22,12 @@ __all__ = [
     "snapshot",
 ]
 
-# 各 label 上一次快照的 RSS（MB），用于计算增量
-_prev_rss: dict[str, float] = {}
+# 快照标签的最大缓存数。防止使用动态 label 调用 snapshot() 时
+# _prev_rss 无限增长，超出部分按最早写入顺序淘汰。
+_MAX_SNAPSHOT_LABELS = 128
+
+# 各 label 上一次快照的 RSS（MB），用于计算增量。按写入顺序淘汰。
+_prev_rss: OrderedDict[str, float] = OrderedDict()
 
 
 def get_rss_mb() -> float | None:
@@ -81,10 +86,14 @@ def snapshot(label: str = "") -> dict[str, Any]:
 
     delta: float | None = None
     key = label or "__default__"
-    if rss is not None and key in _prev_rss:
-        delta = rss - _prev_rss[key]
     if rss is not None:
+        if key in _prev_rss:
+            delta = rss - _prev_rss[key]
+        # 记录并限制缓存上限，避免动态标签导致无界增长
         _prev_rss[key] = rss
+        _prev_rss.move_to_end(key)
+        while len(_prev_rss) > _MAX_SNAPSHOT_LABELS:
+            _prev_rss.popitem(last=False)
 
     return {
         "label": label,

{erispulse-2.7.1.dev2 → erispulse-2.7.1.dev3}/src/ErisPulse/sdk.py

@@ -24,8 +24,11 @@ from typing import TYPE_CHECKING, Any
 
 from .Core.constants import (
     DEFAULT_PROACTIVE_GC_FULL_EVERY,
+    DEFAULT_PROACTIVE_GC_GEN0_MIN,
     DEFAULT_PROACTIVE_GC_GENERATION,
+    DEFAULT_PROACTIVE_GC_IDLE_ONLY,
     DEFAULT_PROACTIVE_GC_INTERVAL_SECS,
+    DEFAULT_PROACTIVE_GC_MEMORY_GROWTH_MB,
     DEFAULT_UNINIT_TIMEOUT_SECS,
     HARD_RESTART_EXIT_CODE,
     LIFECYCLE_TIMER_CORE_INIT,
@@ -193,6 +196,7 @@ class SDK:
         self._initializer: SDK.Initializer | None = None
         self._initialized: bool = False
         self._gc_task: asyncio.Task | None = None  # 主动 GC 后台任务
+        self._gc_config_snapshot: tuple | None = None  # 主动 GC 配置快照（变更检测）
         self._shutdown_event: asyncio.Event | None = None  # 优雅关闭事件
 
     @property
@@ -753,6 +757,15 @@ class SDK:
                 adapter_manager.clear()
                 module_manager.clear()
 
+                # 6.5 立即回收一次，尽早释放模块/适配器实例与循环引用，
+                # 降低 uninit 与 hard_restart 之间的内存驻留
+                try:
+                    import gc
+
+                    gc.collect()
+                except Exception:
+                    pass
+
                 # 获取清理耗时
                 uninit_duration = self.lifecycle.stop_timer(LIFECYCLE_TIMER_CORE_UNINIT)
 
@@ -871,66 +884,97 @@ class SDK:
         定期执行 Python GC 和内部资源回收（离线 Bot 清理等），
         防止长期运行时的内存增长。
 
-        GC 行为由三项框架配置控制（均支持热更新）：
+        GC 行为由多项框架配置控制（均支持热更新，变更时即时重启任务）：
 
         - ``proactive_gc_interval``: 回收间隔秒数（0 禁用）
-        - ``proactive_gc_generation``: 回收分代（0/1/2，默认 2=最老代）
-        - ``proactive_gc_full_every``: 每 N 轮额外做一次全量回收（0 禁用）
+        - ``proactive_gc_generation``: 常规轮次回收分代（0/1/2，钳制到 0..2）
+        - ``proactive_gc_full_every``: 每 N 轮做一次全量回收（0 禁用）
+        - ``proactive_gc_memory_growth_mb``: 全量回收的内存增长门限（0 不设限）
+        - ``proactive_gc_idle_only``: 事件洪峰时跳过 Python GC（避免停顿竞争）
+        - ``proactive_gc_gen0_min``: gen0 垃圾量下限，低于则跳过回收（空转轮次零开销）
 
         初始化阶段已调用 ``gc.freeze()`` 将框架对象移入永久代，
         此处 ``gc.collect()`` 仅扫描运行期新建对象。
         """
-        # 停止已有的 GC 任务
+        # 停止已有的 GC 任务（含反注册配置钩子）
         self._stop_proactive_gc()
 
-        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
-
-                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, generation, full_every
+        # 注册配置变更钩子：proactive_gc_* 变化时即时重启任务。
+        # 修复旧实现"interval 切到 0 后无法再启用"的问题。
+        try:
+            self.lifecycle.register("config.set", self._on_gc_config_event)
+            self.lifecycle.register("config.updated", self._on_gc_config_event)
+        except Exception:
+            pass
 
-        if _read_gc_config()[0] <= 0:
+        self._gc_config_snapshot = self._read_gc_config()
+        if self._gc_config_snapshot[0] <= 0:
             return  # 配置禁用
 
         async def _gc_loop():
             import gc
 
             round_count = 0
+            memory_baseline: float | None = None
             while True:
                 try:
-                    # 每轮重新读取配置，支持热更新
-                    interval, generation, full_every = _read_gc_config()
+                    # 每轮重新读取配置，支持热更新；常规变更已由配置钩子即时重启任务
+                    cfg = self._read_gc_config()
+                    interval = cfg[0]
                     if interval <= 0:
                         # 配置运行时禁用了 GC，停止循环
                         break
                     await asyncio.sleep(interval)
                     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. 内部资源回收
+
+                    # 1. 内部资源回收（廉价，始终执行）
+                    evicted = 0
                     try:
-                        adapter_mgr = self.adapter
-                        evicted = adapter_mgr._evict_offline_bots()
-                        if collected > 0 or evicted > 0:
-                            self.logger.trace(
-                                i18n.t("core.sdk.gc.collected", collected=collected, evicted=evicted)
-                            )
+                        evicted = self.adapter._evict_offline_bots()
                     except Exception:
                         pass
-                    # 3. 内存快照（TRACE），便于长期观察内存变化趋势
+
+                    # 2. 空闲门控：事件洪峰时跳过 Python GC，避免停顿与消息处理竞争
+                    if cfg[4] and self._has_handler_backlog():
+                        self.logger.trace(
+                            i18n.t("core.sdk.gc.skipped", reason="busy")
+                        )
+                        if evicted > 0:
+                            self.logger.trace(
+                                i18n.t(
+                                    "core.sdk.gc.collected", collected=0, evicted=evicted
+                                )
+                            )
+                        continue
+
+                    # 3. 垃圾量门控：gen0 无足够垃圾时跳过回收（空转轮次近乎零开销）
+                    if gc.get_count()[0] < cfg[5]:
+                        if evicted > 0:
+                            self.logger.trace(
+                                i18n.t(
+                                    "core.sdk.gc.collected", collected=0, evicted=evicted
+                                )
+                            )
+                        continue
+
+                    # 4. 周期性全量（受内存增长门限约束）或常规分代回收
+                    is_full = cfg[2] > 0 and round_count % cfg[2] == 0
+                    if is_full:
+                        collected, memory_baseline = self._run_full_gc_collection(
+                            gc, memory_baseline, cfg[3]
+                        )
+                    else:
+                        collected = gc.collect(cfg[1])
+
+                    if collected > 0 or evicted > 0:
+                        self.logger.trace(
+                            i18n.t(
+                                "core.sdk.gc.collected",
+                                collected=collected,
+                                evicted=evicted,
+                            )
+                        )
+                    # 5. 内存快照（TRACE），便于长期观察内存变化趋势
                     try:
                         from .runtime.memory import log_snapshot
 
@@ -951,12 +995,148 @@ class SDK:
     def _stop_proactive_gc(self) -> None:
         """
         {!--< internal-use >!--}
-        停止主动 GC 后台任务
+        停止主动 GC 后台任务，并反注册配置变更钩子
         """
+        try:
+            self.lifecycle.unregister("config.set", self._on_gc_config_event)
+            self.lifecycle.unregister("config.updated", self._on_gc_config_event)
+        except Exception:
+            pass
+        self._gc_config_snapshot = None
         if self._gc_task is not None and not self._gc_task.done():
             self._gc_task.cancel()
         self._gc_task = None
 
+    @staticmethod
+    def _read_gc_config() -> tuple[float, int, int, int, bool, int]:
+        """
+        {!--< internal-use >!--}
+        读取并钳制主动 GC 相关框架配置
+
+        :return: ``(interval, generation, full_every, growth_mb, idle_only, gen0_min)``
+                 元组，值均已钳制到合法范围；``interval`` 为秒（支持小数）
+        """
+        interval = DEFAULT_PROACTIVE_GC_INTERVAL_SECS
+        generation = DEFAULT_PROACTIVE_GC_GENERATION
+        full_every = DEFAULT_PROACTIVE_GC_FULL_EVERY
+        growth_mb = DEFAULT_PROACTIVE_GC_MEMORY_GROWTH_MB
+        idle_only = DEFAULT_PROACTIVE_GC_IDLE_ONLY
+        gen0_min = DEFAULT_PROACTIVE_GC_GEN0_MIN
+        try:
+            from .runtime import get_framework_config
+
+            fw = get_framework_config()
+            raw_interval = fw.get("proactive_gc_interval", interval)
+            interval = float(raw_interval) if raw_interval is not None else interval
+            generation = int(fw.get("proactive_gc_generation", generation))
+            full_every = int(fw.get("proactive_gc_full_every", full_every))
+            growth_mb = int(fw.get("proactive_gc_memory_growth_mb", growth_mb))
+            idle_only = bool(fw.get("proactive_gc_idle_only", idle_only))
+            gen0_min = int(fw.get("proactive_gc_gen0_min", gen0_min))
+        except Exception:
+            pass
+        return (
+            max(0.0, float(interval)),
+            max(0, min(2, generation)),
+            max(0, full_every),
+            max(0, growth_mb),
+            idle_only,
+            max(0, gen0_min),
+        )
+
+    def _on_gc_config_event(self, _data: dict) -> None:
+        """
+        {!--< internal-use >!--}
+        ``config.set`` / ``config.updated`` 回调：proactive_gc_* 配置变化时重启 GC 任务
+
+        相比旧实现"每轮重读"，此钩子使配置变更（含 0→N 重新启用）即时生效。
+        从后台线程（如 config watcher）触发时，调度回主事件循环再重启。
+        """
+        try:
+            current = self._read_gc_config()
+            if (
+                self._gc_config_snapshot is None
+                or current == self._gc_config_snapshot
+            ):
+                return
+        except Exception:
+            return
+
+        def _restart() -> None:
+            try:
+                self._start_proactive_gc()
+            except Exception:
+                pass
+
+        try:
+            # 当前线程有运行中的事件循环：直接重启
+            asyncio.get_running_loop()
+            _restart()
+        except RuntimeError:
+            # 非事件循环线程（如 config watcher）：调度回主循环执行
+            from .runtime.tasks import _get_main_loop
+
+            main_loop = _get_main_loop()
+            if main_loop is not None and main_loop.is_running():
+                main_loop.call_soon_threadsafe(_restart)
+            else:
+                # 无可用主循环：跳过本次重启，循环自身每轮重读配置兜底
+                pass
+
+    @staticmethod
+    def _has_handler_backlog() -> bool:
+        """
+        {!--< internal-use >!--}
+        事件处理器洪峰检测
+
+        :return: 存在未完成的 pending handler task 时返回 True
+        """
+        try:
+            from .Core.adapter import adapter as _adapter
+
+            return len(getattr(_adapter, "_pending_handler_tasks", ())) > 0
+        except Exception:
+            return False
+
+    @staticmethod
+    def _run_full_gc_collection(
+        gc_module: Any, baseline: float | None, growth_mb: int
+    ) -> tuple[int, float | None]:
+        """
+        {!--< internal-use >!--}
+        执行一次全量回收（受内存增长门限约束）
+
+        优先使用 tracemalloc 追踪值，不可用则回退 RSS。当 ``growth_mb > 0``
+        且距上次全量回收基线增长不足时跳过回收，避免内存稳定时空转。
+
+        :param gc_module: ``gc`` 模块（便于测试注入）
+        :param baseline: 上次全量回收后的内存基线（MB），None 表示首次
+        :param growth_mb: 内存增长门限（MB），0 表示不设门限
+        :return: ``(collected, 新基线)``
+        """
+        current: float | None = None
+        try:
+            from .runtime.memory import get_rss_mb, get_traced_mb
+
+            current = get_traced_mb()
+            if current is None:
+                current = get_rss_mb()
+        except Exception:
+            pass
+
+        if current is not None:
+            if growth_mb > 0 and baseline is not None:
+                # 内存稳定：增长未达门限，跳过本次全量回收
+                if (current - baseline) < growth_mb:
+                    return 0, baseline
+            baseline = current
+
+        try:
+            collected = gc_module.collect()
+        except Exception:
+            collected = 0
+        return collected, baseline
+
     def dump_state(self) -> dict:
         """
         导出框架当前运行状态的快照