ErisPulse 2.7.1.dev1__tar.gz → 2.7.1.dev3__tar.gz

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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ErisPulse"
-version = "2.7.1-dev.1"
+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.dev1 → erispulse-2.7.1.dev3}/src/ErisPulse/CLI/commands/run.py

@@ -183,6 +183,7 @@ class RunCommand(Command):
         ]
 
         crash_count = 0
+        process = None
         try:
             while True:
                 process = subprocess.Popen(cmd)
@@ -208,6 +209,17 @@ class RunCommand(Command):
                 # 继续循环，重新启动子进程
         except KeyboardInterrupt:
             pass
+        finally:
+            # 运行器退出（Ctrl+C 等）前必须终止子进程，否则孤儿进程会继续持有
+            # 端口等资源，导致下次启动时端口被占用（如监听 8000 的残留进程）。
+            if process is not None and process.poll() is None:
+                console.print(f"[info]{i18n.t('cli.run.terminating_child')}[/]")
+                process.terminate()
+                try:
+                    process.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    process.kill()
+                    process.wait()
 
     def _run_script(self, script_path: str, reload_mode: bool):
         """

{erispulse-2.7.1.dev1 → erispulse-2.7.1.dev3}/src/ErisPulse/CLI/i18n/locales/en.py

@@ -277,6 +277,7 @@ TRANSLATIONS = {
     "cli.run.process_exited": "Process exited normally, waiting for file changes to restart",
     "cli.run.process_crashed": "Process crashed (exit code {code}), fix and save to restart",
     "cli.run.subprocess_crashed_retry": "Subprocess crashed, will auto-retry in {seconds}s...",
+    "cli.run.terminating_child": "Terminating the bot subprocess to release ports and resources...",
     # ==================== uninstall command ====================
     "cli.uninstall.description": "Uninstall module/adapter packages",
     "cli.uninstall.package_help": "Package name(s) to uninstall (multiple allowed)",

{erispulse-2.7.1.dev1 → erispulse-2.7.1.dev3}/src/ErisPulse/CLI/i18n/locales/ja.py

@@ -277,6 +277,7 @@ TRANSLATIONS = {
     "cli.run.process_exited": "プロセスが正常に終了しました。ファイルの変更を待機して再起動",
     "cli.run.process_crashed": "プロセスが異常終了しました（終了コード {code}）。修正して保存すると自動再起動",
     "cli.run.subprocess_crashed_retry": "サブプロセスが異常終了しました。{seconds} 秒後に自動再試行します...",
+    "cli.run.terminating_child": "ポートなどのリソースを解放するため、ボットの子プロセスを終了しています...",
     # ==================== uninstall コマンド ====================
     "cli.uninstall.description": "モジュール/アダプターパッケージをアンインストール",
     "cli.uninstall.package_help": "アンインストールするパッケージ名（複数指定可）",

{erispulse-2.7.1.dev1 → erispulse-2.7.1.dev3}/src/ErisPulse/CLI/i18n/locales/ru.py

@@ -277,6 +277,7 @@ TRANSLATIONS = {
     "cli.run.process_exited": "Процесс завершен нормально, ожидание изменений файлов для перезапуска",
     "cli.run.process_crashed": "Процесс аварийно завершен (код {code}), исправьте и сохраните для перезапуска",
     "cli.run.subprocess_crashed_retry": "Подпроцесс аварийно завершен, автоматическая перезагрузка через {seconds}с...",
+    "cli.run.terminating_child": "Завершение дочернего процесса бота для освобождения портов и ресурсов...",
     # ==================== команда uninstall ====================
     "cli.uninstall.description": "Удалить пакеты модулей/адаптеров",
     "cli.uninstall.package_help": "Имя(ена) пакета(ов) для удаления (можно указать несколько)",

{erispulse-2.7.1.dev1 → erispulse-2.7.1.dev3}/src/ErisPulse/CLI/i18n/locales/zh_cn.py

@@ -277,6 +277,7 @@ TRANSLATIONS = {
     "cli.run.process_exited": "进程已正常退出，等待文件变更后重启",
     "cli.run.process_crashed": "进程异常退出（退出码 {code}），修复后保存文件将自动重启",
     "cli.run.subprocess_crashed_retry": "子进程异常终止，将在 {seconds} 秒后自动重试...",
+    "cli.run.terminating_child": "正在终止机器人子进程，释放端口等资源...",
     # ==================== uninstall 命令 ====================
     "cli.uninstall.description": "卸载模块/适配器包",
     "cli.uninstall.package_help": "要卸载的包名（可指定多个）",

{erispulse-2.7.1.dev1 → erispulse-2.7.1.dev3}/src/ErisPulse/CLI/i18n/locales/zh_tw.py

@@ -277,6 +277,7 @@ TRANSLATIONS = {
     "cli.run.process_exited": "程式已正常退出，等待檔案變更後重啟",
     "cli.run.process_crashed": "程式異常退出（退出碼 {code}），修復後儲存檔案將自動重啟",
     "cli.run.subprocess_crashed_retry": "子程序異常終止，將在 {seconds} 秒後自動重試...",
+    "cli.run.terminating_child": "正在終止機器人子程序，釋放連接埠等資源...",
     # ==================== uninstall 命令 ====================
     "cli.uninstall.description": "解除安裝模組/適配器包",
     "cli.uninstall.package_help": "要解除安裝的包名（可指定多個）",

{erispulse-2.7.1.dev1 → 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.dev1 → 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.dev1 → 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.dev1 → erispulse-2.7.1.dev3}/src/ErisPulse/Core/constants.py

@@ -53,12 +53,6 @@ DEFAULT_SERVER_AUTO_START: Final[bool] = True
 # 修改影响: Ctrl+C 后等待 uvicorn 关闭的耐心时间。超时后强制终止。
 SERVER_SHUTDOWN_TIMEOUT_SECS: Final[float] = 5.0
 
-# 路由服务器启动时端口被占用后的自动顺延尝试次数（含起始端口）。
-# 运行时行为。启动时若端口被占用，自动依次尝试后续端口，
-# 直至找到可用端口或达到该上限。实际监听端口通过 router.base_url 暴露。
-# 修改影响: 设大允许更多顺延，设小更快放弃；设为 1 表示不顺延，占用即报错。
-DEFAULT_SERVER_PORT_RETRY_LIMIT: Final[int] = 50
-
 # ==============================================================================
 # 配置键模板
 #
@@ -641,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 后等待它们退出的耐心时间。
@@ -761,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",
@@ -772,7 +789,6 @@ __all__ = [
     "DEFAULT_SERVER_AUTO_START",
     "DEFAULT_SERVER_HOST",
     "DEFAULT_SERVER_PORT",
-    "DEFAULT_SERVER_PORT_RETRY_LIMIT",
     "DEFAULT_STRICT_MODE",
     "DEFAULT_UNINIT_TIMEOUT_SECS",
     "DEFAULT_USE_GLOBAL_DB",

{erispulse-2.7.1.dev1 → 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...",
@@ -257,8 +259,6 @@ TRANSLATIONS = {
     "core.router.start_failed_msg": "Router server startup failed",
     "core.router.start_failed": "Failed to start server: {error}",
     "core.router.port_in_use": "Port {host}:{port} is already in use; the router server could not start. Check whether another ErisPulse instance or another program is using this port (run `netstat -ano` to find the process holding it)",
-    "core.router.port_advance": "Port {host}:{requested} is already in use; automatically advanced to {host}:{port}",
-    "core.router.port_range_in_use": "Port {host}:{port} and the next {count} ports are all in use; the router server could not start. Check whether multiple ErisPulse instances or other programs are occupying these ports",
     "core.router.stopping": "Stopping router server...",
     "core.router.stopped_normal": "Router server stopped normally",
     "core.router.stopped_cancelled": "Router server was cancelled",

{erispulse-2.7.1.dev1 → 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": "初期化環境を準備しています...",
@@ -257,8 +259,6 @@ TRANSLATIONS = {
     "core.router.start_failed_msg": "ルーターサーバーの起動に失敗しました",
     "core.router.start_failed": "サーバーの起動に失敗しました: {error}",
     "core.router.port_in_use": "ポート {host}:{port} は既に使用されています。ルーターサーバーを起動できません。別の ErisPulse インスタンスや他のプログラムがこのポートを使用していないか確認してください（`netstat -ano` で使用中のプロセスを確認できます）",
-    "core.router.port_advance": "ポート {host}:{requested} は既に使用されています。{host}:{port} に自動で切り替えました",
-    "core.router.port_range_in_use": "ポート {host}:{port} とその後の {count} 個のポートがすべて使用中です。ルーターサーバーを起動できません。複数の ErisPulse インスタンスや他のプログラムがこれらのポートを占有していないか確認してください",
     "core.router.stopping": "ルーターサーバーを停止しています...",
     "core.router.stopped_normal": "ルーターサーバーは正常に停止しました",
     "core.router.stopped_cancelled": "ルーターサーバーはキャンセルされました",

{erispulse-2.7.1.dev1 → 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": "Подготовка окружения инициализации...",
@@ -257,8 +259,6 @@ TRANSLATIONS = {
     "core.router.start_failed_msg": "Ошибка запуска сервера маршрутизации",
     "core.router.start_failed": "Ошибка запуска сервера: {error}",
     "core.router.port_in_use": "Порт {host}:{port} уже занят, сервер маршрутизации не может запуститься. Проверьте, не использует ли этот порт другой экземпляр ErisPulse или другая программа (выполните `netstat -ano`, чтобы найти процесс, удерживающий порт)",
-    "core.router.port_advance": "Порт {host}:{requested} уже занят, автоматически переключено на {host}:{port}",
-    "core.router.port_range_in_use": "Порт {host}:{port} и последующие {count} портов заняты, сервер маршрутизации не может запуститься. Проверьте, не занимают ли эти порты несколько экземпляров ErisPulse или других программ",
     "core.router.stopping": "Остановка сервера маршрутизации...",
     "core.router.stopped_normal": "Сервер маршрутизации остановлен нормально",
     "core.router.stopped_cancelled": "Работа сервера маршрутизации была отменена",

{erispulse-2.7.1.dev1 → 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": "准备初始化环境...",
@@ -257,8 +259,6 @@ TRANSLATIONS = {
     "core.router.start_failed_msg": "路由服务器启动失败",
     "core.router.start_failed": "启动服务器失败: {error}",
     "core.router.port_in_use": "端口 {host}:{port} 已被占用，路由服务器无法启动。请检查是否有另一个 ErisPulse 实例或其他程序正在使用该端口（可执行 `netstat -ano` 查看占用进程）",
-    "core.router.port_advance": "端口 {host}:{requested} 已被占用，已自动顺延至 {host}:{port}",
-    "core.router.port_range_in_use": "端口 {host}:{port} 及其后 {count} 个端口均已被占用，无法启动路由服务器。请检查是否有多个 ErisPulse 实例或其他程序占用了这些端口",
     "core.router.stopping": "正在停止路由服务器...",
     "core.router.stopped_normal": "路由服务器已正常停止",
     "core.router.stopped_cancelled": "路由服务器已被取消",

{erispulse-2.7.1.dev1 → 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": "準備初始化環境...",
@@ -257,8 +259,6 @@ TRANSLATIONS = {
     "core.router.start_failed_msg": "路由伺服器啟動失敗",
     "core.router.start_failed": "啟動伺服器失敗: {error}",
     "core.router.port_in_use": "連接埠 {host}:{port} 已被占用，路由伺服器無法啟動。請檢查是否有另一個 ErisPulse 實例或其他程式正在使用該連接埠（可執行 `netstat -ano` 查看占用程序）",
-    "core.router.port_advance": "連接埠 {host}:{requested} 已被占用，已自動順延至 {host}:{port}",
-    "core.router.port_range_in_use": "連接埠 {host}:{port} 及其後 {count} 個連接埠均已被占用，無法啟動路由伺服器。請檢查是否有多個 ErisPulse 實例或其他程式占用了這些連接埠",
     "core.router.stopping": "正在停止路由伺服器...",
     "core.router.stopped_normal": "路由伺服器已正常停止",
     "core.router.stopped_cancelled": "路由伺服器已被取消",

{erispulse-2.7.1.dev1 → erispulse-2.7.1.dev3}/src/ErisPulse/Core/router.py

@@ -53,7 +53,6 @@ from .constants import (
     DEFAULT_SECURITY_HEADERS,
     DEFAULT_SERVER_HOST,
     DEFAULT_SERVER_PORT,
-    DEFAULT_SERVER_PORT_RETRY_LIMIT,
     DEFAULT_WS_AUTO_ACCEPT,
     FALLBACK_IPV4,
     FALLBACK_IPV6_HOST,
@@ -2601,26 +2600,23 @@ class RouterManager:
             self._get_local_ips()
             self._apply_config()
 
-            # 端口自动顺延：若端口被占用则依次尝试后续端口（类似 VNC 的 5099→5100）。
-            # uvicorn 在端口被占用时会执行 sys.exit(3)，其 SystemExit 会被事件循环
-            # 重新抛出并取消所有任务，导致进程异常退出并刷屏大量 "Task was destroyed
-            # but it is pending"。此处先同步 bind 探测并顺延，实际监听端口通过
-            # bind_port 暴露，uvicorn 启动时不会再次遇到占用错误。
-            bind_port = self._find_available_port(
-                host, port, DEFAULT_SERVER_PORT_RETRY_LIMIT
-            )
+            # 同步探测端口是否可绑定。uvicorn 在端口被占用时会执行 sys.exit(3)，
+            # 其 SystemExit 会被事件循环重新抛出并取消所有任务，导致进程异常退出并
+            # 刷屏大量 "Task was destroyed but it is pending"。此处先同步 bind 探测，
+            # 端口被占用时在启动前抛出清晰、可操作的错误，由上层按致命错误处理。
+            self._check_port_available(host, port)
 
             config = uvicorn.Config(
                 self.app,
                 host=host,
-                port=bind_port,
+                port=port,
                 log_level="warning",
                 ssl_certfile=ssl_certfile,
                 ssl_keyfile=ssl_keyfile,
             )
             self._uvicorn_server = uvicorn.Server(config)
 
-            self.base_url = f"http{'s' if ssl_certfile else ''}://{host}:{bind_port}"
+            self.base_url = f"http{'s' if ssl_certfile else ''}://{host}:{port}"
             display_url = self._format_display_url(self.base_url)
             http_count = sum(len(paths) for paths in self._http_routes.values())
             ws_count = sum(len(paths) for paths in self._websocket_routes.values())
@@ -2662,7 +2658,7 @@ class RouterManager:
                 data={
                     "base_url": self.base_url,
                     "host": host,
-                    "port": bind_port,
+                    "port": port,
                 },
             )
         except Exception as e:
@@ -2684,18 +2680,21 @@ class RouterManager:
             logger.error(i18n.t("core.router.start_failed", error=e))
             raise e
 
-    def _is_port_bindable(self, host: str, port: int) -> bool:
+    def _check_port_available(self, host: str, port: int) -> None:
         """
-        同步探测端口当前是否可绑定
+        同步探测端口是否可绑定，避免 uvicorn 异步启动失败后引发级联错误
 
         uvicorn 在端口被占用时会执行 ``sys.exit(STARTUP_FAILURE)``，其 SystemExit
         会被事件循环重新抛出并取消所有任务，导致进程异常退出并刷屏大量
-        "Task was destroyed but it is pending"。此处先同步 bind 探测端口是否空闲，
-        供启动前自动顺延使用。
+        "Task was destroyed but it is pending"。此处先同步 bind 探测端口，若被占用
+        则在启动前抛出清晰的 i18n 提示，由上层按致命错误处理（不自动顺延端口，
+        避免生产环境暴露的端口变化导致外部访问失败）。
 
         :param host: str 监听地址
         :param port: int 监听端口
-        :return: bool 端口当前可绑定返回 True，否则返回 False
+
+        :raises RuntimeError: 当端口被占用时抛出，携带友好的错误提示
+        :raises OSError: 其他绑定错误（如无权限绑定特权端口）
         """
         try:
             family = socket.AF_INET6 if ":" in host else socket.AF_INET
@@ -2704,46 +2703,12 @@ class RouterManager:
                 probe.bind((host, port))
             finally:
                 probe.close()
-            return True
-        except OSError:
-            return False
-
-    def _find_available_port(
-        self, host: str, port: int, retry_limit: int
-    ) -> int:
-        """
-        在 [port, port + retry_limit) 范围内寻找第一个可绑定的端口
-
-        端口被占用时自动顺延，实际监听端口通过
-        router.base_url 暴露给下游。若范围内全部被占用，抛出清晰的错误提示。
-
-        :param host: str 监听地址
-        :param port: int 期望端口（顺延起点）
-        :param retry_limit: int 尝试的端口个数（含起点），最小为 1
-        :return: int 实际可绑定的端口
-
-        :raises RuntimeError: 当范围内端口全部被占用时抛出
-        """
-        for candidate in range(port, port + max(1, retry_limit)):
-            if self._is_port_bindable(host, candidate):
-                if candidate != port:
-                    logger.warning(
-                        i18n.t(
-                            "core.router.port_advance",
-                            host=host,
-                            requested=port,
-                            port=candidate,
-                        )
-                    )
-                return candidate
-        raise RuntimeError(
-            i18n.t(
-                "core.router.port_range_in_use",
-                host=host,
-                port=port,
-                count=retry_limit,
-            )
-        )
+        except OSError as e:
+            if e.errno == errno.EADDRINUSE:
+                raise RuntimeError(
+                    i18n.t("core.router.port_in_use", host=host, port=port)
+                ) from e
+            raise
 
     def _start_rate_limit_cleanup(self) -> None:
         """

{erispulse-2.7.1.dev1 → 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": {