ErisPulse 2.10.2__tar.gz → 2.11.0.dev0__tar.gz

{erispulse-2.10.2 → erispulse-2.11.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ErisPulse
-Version: 2.10.2
+Version: 2.11.0-dev.0
 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.10.2 → erispulse-2.11.0.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ErisPulse"
-version = "2.10.2"
+version = "2.11.0-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.10.2 → erispulse-2.11.0.dev0}/src/ErisPulse/CLI/commands/init.py

@@ -231,6 +231,16 @@ class InitCommand(Command):
                 with config_file.open("w", encoding="utf-8") as f:
                     f.write(st.initial_config_toml())
 
+            # 配置目录自带 .gitignore：配置含令牌等敏感信息，全部文件不入库
+            # （规则仅一行 *——忽略文件自身也在排除范围内）
+            config_gitignore = project_path / "config" / ".gitignore"
+            if not config_gitignore.exists():
+                with config_gitignore.open("w", encoding="utf-8") as f:
+                    f.write(
+                        "# ErisPulse: sensitive config — keep out of VCS / 配置含敏感信息，全部不入库\n"
+                        "*\n"
+                    )
+
             example_file = project_path / "config" / "config.full.example"
             if not example_file.exists():
                 with example_file.open("w", encoding="utf-8") as f:
@@ -295,6 +305,7 @@ class InitCommand(Command):
                         f"{st.t('init.gitignore_section_runtime')}\n"
                         "config/\n"
                         "logs/\n"
+                        ".erispulse/\n"
                         "\n"
                         f"{st.t('init.gitignore_section_editor')}\n"
                         ".idea/\n"

{erispulse-2.10.2 → erispulse-2.11.0.dev0}/src/ErisPulse/CLI/commands/run.py

@@ -32,6 +32,7 @@ from ..constants import (
     RUN_RESTART_PAUSE_SECS,
 )
 from ..i18n import i18n
+from ..utils import runtime_state
 from ..utils.package_manager import (
     resolve_target_python,
     warn_if_uv_isolated,
@@ -310,29 +311,35 @@ class RunCommand(Command):
         """
 
         if reload_mode:
+            # 运行状态登记（epsdk stop / restart 的定位依据）；内联模式监督者 = 当前进程
+            runtime_state.write(os.getpid(), argv=sys.argv)
+            try:
 
-            async def _run():
-                """
-                设置文件监控并运行 SDK
+                async def _run():
+                    """
+                    设置文件监控并运行 SDK
 
-                :return: [None] 无返回值
-                """
-                from ... import sdk
+                    :return: [None] 无返回值
+                    """
+                    from ... import sdk
 
-                loop = asyncio.get_running_loop()
-                self._setup_watchdog(".", loop)
-                await sdk.run(keep_running=True)
+                    loop = asyncio.get_running_loop()
+                    self._setup_watchdog(".", loop)
+                    await sdk.run(keep_running=True)
 
-            try:
-                asyncio.run(_run())
-            except KeyboardInterrupt:
-                pass
+                try:
+                    asyncio.run(_run())
+                except KeyboardInterrupt:
+                    pass
             finally:
                 if hasattr(self, "_observer"):
                     self._observer.stop()
                     self._observer.join()
+                runtime_state.clear()
             return
 
+        runtime_state.write(os.getpid(), argv=sys.argv)
+
         cmd = [
             getattr(self, "python_exe", sys.executable),
             "-c",
@@ -354,6 +361,8 @@ class RunCommand(Command):
                 child_env = dict(os.environ)
                 child_env[ENV_SUPERVISED] = "cli"
                 process = subprocess.Popen(cmd, env=child_env)
+                # 每次拉起新子进程都更新状态文件（stop 先断子进程再停监督者）
+                runtime_state.update_child(process.pid)
                 process.wait()
 
                 if process.returncode == self._RESTART_EXIT_CODE:
@@ -406,6 +415,7 @@ class RunCommand(Command):
                 except subprocess.TimeoutExpired:
                     process.kill()
                     process.wait()
+            runtime_state.clear()
 
     def _run_script(self, script_path: str, reload_mode: bool):
         """
@@ -417,17 +427,25 @@ class RunCommand(Command):
         script_path_abs = str(Path(script_path).resolve())
 
         if reload_mode:
-            self._run_script_with_reload(script_path_abs)
+            runtime_state.write(os.getpid(), argv=sys.argv)
+            try:
+                self._run_script_with_reload(script_path_abs)
+            finally:
+                runtime_state.clear()
         else:
-            script_dir = str(Path(script_path_abs).parent)
-            if script_dir not in sys.path:
-                sys.path.insert(0, script_dir)
+            runtime_state.write(os.getpid(), argv=sys.argv)
             try:
-                runpy.run_path(script_path_abs, run_name="__main__")
-            except SystemExit:
-                pass
-            except KeyboardInterrupt:
-                pass
+                script_dir = str(Path(script_path_abs).parent)
+                if script_dir not in sys.path:
+                    sys.path.insert(0, script_dir)
+                try:
+                    runpy.run_path(script_path_abs, run_name="__main__")
+                except SystemExit:
+                    pass
+                except KeyboardInterrupt:
+                    pass
+            finally:
+                runtime_state.clear()
 
     def _run_script_with_reload(self, script_path_abs: str):
         """
@@ -453,6 +471,7 @@ class RunCommand(Command):
             reload_state["process"] = subprocess.Popen(
                 [getattr(self, "python_exe", sys.executable), script_path_abs]
             )
+            runtime_state.update_child(reload_state["process"].pid)
 
         class _ScriptReloadHandler(FileSystemEventHandler):
             """

erispulse-2.11.0.dev0/src/ErisPulse/CLI/commands/runtime.py

@@ -0,0 +1,153 @@
+"""
+Stop / Restart 命令实现
+
+控制由 ``epsdk run`` 启动的运行实例：``.erispulse/runtime.json`` 状态文件
+记录监督进程 PID、当前子进程 PID 与原始启动命令，``stop`` 优雅终止实例，
+``restart`` 停止后按原参数重新启动。
+
+POSIX 停止走 SIGINT（监督进程按 Ctrl+C 同款路径收尾，finally 链终止子进程），
+超时逐级升级 SIGTERM / SIGKILL；Windows 无优雅信号语义，先断子进程再终止
+监督进程（避免监督者把强杀误判为崩溃重新拉起）。
+"""
+
+import subprocess
+import sys
+from argparse import ArgumentParser, Namespace
+
+from ..base import Command
+from ..console import console
+from ..i18n import i18n
+from ..utils import runtime_state
+
+
+def _stop_instance(state: dict, force: bool = False) -> bool:
+    """
+    停止一个运行实例（子进程先断，监督进程优雅收尾后逐级升级）
+
+    :param state: 状态字典（pid / child_pid）
+    :param force: 跳过优雅信号直接强制终止
+    :return: 是否成功停止
+    """
+    pid = state.get("pid")
+    child_pid = state.get("child_pid")
+    if not isinstance(pid, int) or not runtime_state.pid_alive(pid):
+        return False
+
+    # 1. 先断框架子进程：Windows 强停监督进程前必须先断子，
+    #    否则监督者会把强杀误判为崩溃而按退避策略重新拉起
+    if isinstance(child_pid, int) and runtime_state.pid_alive(child_pid):
+        runtime_state.terminate(child_pid, force=force or os_needs_force())
+        if not runtime_state.wait_gone(child_pid, runtime_state.FORCE_TIMEOUT_SECS):
+            runtime_state.kill_tree_hard(child_pid)
+
+    # 2. 停监督进程：优雅信号 → 等待 → 强制
+    if not force:
+        runtime_state.terminate(pid, force=False)
+        if runtime_state.wait_gone(pid, runtime_state.GRACEFUL_TIMEOUT_SECS):
+            return True
+        console.print(f"[warning]{i18n.t('cli.stop.graceful_timeout')}[/]")
+    runtime_state.terminate(pid, force=True)
+    if runtime_state.wait_gone(pid, runtime_state.FORCE_TIMEOUT_SECS):
+        return True
+    runtime_state.kill_tree_hard(pid)
+    return not runtime_state.pid_alive(pid)
+
+
+def os_needs_force() -> bool:
+    """Windows 无优雅信号语义：子进程直接强停"""
+    return sys.platform.startswith("win")
+
+
+class StopCommand(Command):
+    """
+    stop 命令
+
+    停止正在运行的 ErisPulse 实例（由 ``epsdk run`` 启动）
+    """
+
+    name = "stop"
+    description = i18n.t("cli.stop.description")
+    aliases: list = []
+    category = "project"
+
+    def add_arguments(self, parser: ArgumentParser):
+        parser.add_argument(
+            "--force",
+            action="store_true",
+            default=False,
+            help=i18n.t("cli.stop.force_help"),
+        )
+        parser.add_argument(
+            "--pid",
+            type=int,
+            default=None,
+            help=i18n.t("cli.stop.pid_help"),
+        )
+
+    def execute(self, args: Namespace):
+        state = runtime_state.read()
+        if args.pid is not None:
+            state = {"pid": args.pid, "child_pid": None}
+        if state is None or not runtime_state.pid_alive(state.get("pid", -1)):
+            console.print(f"[warning]{i18n.t('cli.stop.not_running')}[/]")
+            runtime_state.clear()
+            return
+
+        pid = state.get("pid")
+        console.print(f"[info]{i18n.t('cli.stop.stopping', pid=pid)}[/]")
+        if _stop_instance(state, force=bool(args.force)):
+            runtime_state.clear()
+            console.print(f"[success]{i18n.t('cli.stop.stopped')}[/]")
+        else:
+            console.print(f"[error]{i18n.t('cli.stop.failed', pid=pid)}[/]")
+            raise SystemExit(1)
+
+
+class RestartCommand(Command):
+    """
+    restart 命令
+
+    重启正在运行的 ErisPulse 实例（停止后按原参数重新启动，前台接管控制台）
+    """
+
+    name = "restart"
+    description = i18n.t("cli.restart.description")
+    aliases: list = []
+    category = "project"
+
+    def add_arguments(self, parser: ArgumentParser):
+        parser.add_argument(
+            "--force",
+            action="store_true",
+            default=False,
+            help=i18n.t("cli.stop.force_help"),
+        )
+        parser.add_argument(
+            "--pid",
+            type=int,
+            default=None,
+            help=i18n.t("cli.stop.pid_help"),
+        )
+
+    def execute(self, args: Namespace):
+        state = runtime_state.read()
+        if args.pid is not None:
+            state = {"pid": args.pid, "child_pid": None}
+
+        if state is None or not runtime_state.pid_alive(state.get("pid", -1)):
+            console.print(f"[warning]{i18n.t('cli.restart.not_running_hint')}[/]")
+            runtime_state.clear()
+            return
+
+        argv = state.get("argv") or [sys.argv[0], "run"]
+        console.print(f"[info]{i18n.t('cli.stop.stopping', pid=state.get('pid'))}[/]")
+        if not _stop_instance(state, force=bool(args.force)):
+            console.print(f"[error]{i18n.t('cli.stop.failed', pid=state.get('pid'))}[/]")
+            raise SystemExit(1)
+        runtime_state.clear()
+        console.print(f"[info]{i18n.t('cli.restart.starting_new', cmd=' '.join(argv))}[/]")
+        # 前台接管：新实例写自己的状态文件，退出码透传
+        raise SystemExit(subprocess.call(argv))
+
+
+__all__ = ["StopCommand", "RestartCommand"]

{erispulse-2.10.2 → erispulse-2.11.0.dev0}/src/ErisPulse/CLI/i18n/locales/en.py

@@ -373,6 +373,17 @@ TRANSLATIONS = {
     "cli.self_update.invalid_selection": "Invalid version number or version string",
     # ==================== run command ====================
     "cli.run.description": "Run the main program",
+    "cli.stop.description": "Stop a running ErisPulse instance (started via epsdk run)",
+    "cli.stop.force_help": "Skip graceful shutdown and terminate forcefully",
+    "cli.stop.pid_help": "Target process PID (overrides the runtime state file)",
+    "cli.stop.not_running": "No running instance found — execute from the project directory with an instance started via epsdk run (processes started via python main.py must be managed with system tools)",
+    "cli.stop.stopping": "Stopping instance (PID {pid})...",
+    "cli.stop.graceful_timeout": "Graceful shutdown timed out, escalating to force kill...",
+    "cli.stop.stopped": "Instance stopped",
+    "cli.stop.failed": "Failed to stop instance (PID {pid}); please check the process manually",
+    "cli.restart.description": "Restart a running ErisPulse instance (stop, then relaunch with the original arguments)",
+    "cli.restart.not_running_hint": "No running instance found — just run epsdk run to start one",
+    "cli.restart.starting_new": "Stopped. Relaunching with the original arguments: {cmd}",
     "cli.run.script_help": "Script path to run (default: run SDK directly)",
     "cli.run.reload_help": "Enable hot reload mode",
     "cli.run.strict_help": "Temporarily enable strict mode: exit on preflight failure, framework strict level raised to at least 1 (skip non-compliant components) for this run; defaults to ErisPulse.framework.strict_mode, --no-strict disables temporarily",

{erispulse-2.10.2 → erispulse-2.11.0.dev0}/src/ErisPulse/CLI/i18n/locales/ja.py

@@ -373,6 +373,17 @@ TRANSLATIONS = {
     "cli.self_update.invalid_selection": "無効なバージョン番号またはバージョン文字列です",
     # ==================== run コマンド ====================
     "cli.run.description": "メインプログラムを実行",
+    "cli.stop.description": "稼働中の ErisPulse インスタンスを停止します（epsdk run で起動したもの）",
+    "cli.stop.force_help": "グレースフル停止をスキップし、強制終了します",
+    "cli.stop.pid_help": "対象プロセスの PID を直接指定（ランタイム状態ファイルを上書き）",
+    "cli.stop.not_running": "稼働中のインスタンスが見つかりません——プロジェクトディレクトリで実行し、epsdk run で起動したインスタンスを対象にしてください（python main.py 直起動のプロセスは OS のツールで管理してください）",
+    "cli.stop.stopping": "インスタンスを停止中 (PID {pid})...",
+    "cli.stop.graceful_timeout": "グレースフル停止がタイムアウト、強制終了に移行します...",
+    "cli.stop.stopped": "インスタンスを停止しました",
+    "cli.stop.failed": "インスタンスの停止に失敗しました (PID {pid})。手動でプロセス状態を確認してください",
+    "cli.restart.description": "稼働中の ErisPulse インスタンスを再起動します（停止後、元の引数で再起動）",
+    "cli.restart.not_running_hint": "稼働中のインスタンスが見つかりません——epsdk run で起動してください",
+    "cli.restart.starting_new": "停止しました。元の引数で再起動します: {cmd}",
     "cli.run.script_help": "実行するスクリプトパス（省略時は SDK を直接実行）",
     "cli.run.reload_help": "ホットリロードモードを有効化",
     "cli.run.strict_help": "厳格モードを一時有効化：起動前チェック失敗時に終了し、フレームワークの厳格レベルを今回のみ 1 以上に引き上げます。デフォルトは ErisPulse.framework.strict_mode に従い、--no-strict で一時無効化",

{erispulse-2.10.2 → erispulse-2.11.0.dev0}/src/ErisPulse/CLI/i18n/locales/ru.py

@@ -373,6 +373,17 @@ TRANSLATIONS = {
     "cli.self_update.invalid_selection": "Неверный номер версии или строка версии",
     # ==================== команда run ====================
     "cli.run.description": "Запустить основную программу",
+    "cli.stop.description": "Остановить запущенный экземпляр ErisPulse (запущенный через epsdk run)",
+    "cli.stop.force_help": "Пропустить плавную остановку и завершить принудительно",
+    "cli.stop.pid_help": "Указать PID целевого процесса напрямую (вместо файла состояния)",
+    "cli.stop.not_running": "Работающий экземпляр не найден — выполняйте из каталога проекта для экземпляра, запущенного через epsdk run (процессы, запущенные через python main.py, управляйте системными средствами)",
+    "cli.stop.stopping": "Остановка экземпляра (PID {pid})...",
+    "cli.stop.graceful_timeout": "Истекло время плавной остановки, переход к принудительному завершению...",
+    "cli.stop.stopped": "Экземпляр остановлен",
+    "cli.stop.failed": "Не удалось остановить экземпляр (PID {pid}); проверьте процесс вручную",
+    "cli.restart.description": "Перезапустить работающий экземпляр ErisPulse (остановка и повторный запуск с исходными аргументами)",
+    "cli.restart.not_running_hint": "Работающий экземпляр не найден — просто выполните epsdk run",
+    "cli.restart.starting_new": "Остановлено. Перезапуск с исходными аргументами: {cmd}",
     "cli.run.script_help": "Путь к скрипту для запуска (по умолчанию: запуск SDK напрямую)",
     "cli.run.reload_help": "Включить режим горячей перезагрузки",
     "cli.run.strict_help": "Временное включение строгого режима: выход при провале проверки, уровень строгости фреймворка не ниже 1 (пропуск несоответствующих компонентов) для этого запуска; по умолчанию следует ErisPulse.framework.strict_mode, --no-strict временно отключает",

{erispulse-2.10.2 → erispulse-2.11.0.dev0}/src/ErisPulse/CLI/i18n/locales/zh_cn.py

@@ -373,6 +373,17 @@ TRANSLATIONS = {
     "cli.self_update.invalid_selection": "无效的版本序号或版本号",
     # ==================== run 命令 ====================
     "cli.run.description": "运行主程序",
+    "cli.stop.description": "停止正在运行的 ErisPulse 实例（由 epsdk run 启动）",
+    "cli.stop.force_help": "跳过优雅停止，直接强制终止",
+    "cli.stop.pid_help": "直接指定目标进程 PID（覆盖运行状态文件）",
+    "cli.stop.not_running": "未找到运行中的实例——请在项目目录下执行，且实例由 epsdk run 启动（python main.py 直启的进程请用系统工具管理）",
+    "cli.stop.stopping": "正在停止实例 (PID {pid})...",
+    "cli.stop.graceful_timeout": "优雅停止超时，升级为强制终止...",
+    "cli.stop.stopped": "实例已停止",
+    "cli.stop.failed": "停止实例失败 (PID {pid})，请手动检查进程状态",
+    "cli.restart.description": "重启正在运行的 ErisPulse 实例（停止后按原参数重新启动）",
+    "cli.restart.not_running_hint": "未找到运行中的实例——直接执行 epsdk run 启动即可",
+    "cli.restart.starting_new": "已停止，正在按原参数重新启动: {cmd}",
     "cli.run.script_help": "要运行的主程序路径 (不指定则直接运行 SDK)",
     "cli.run.reload_help": "启用热重载模式",
     "cli.run.strict_help": "临时开启严格模式：自检失败即退出，框架严格级别本次至少为 1（跳过不合规组件）；缺省跟随 ErisPulse.framework.strict_mode，--no-strict 临时关闭",

{erispulse-2.10.2 → erispulse-2.11.0.dev0}/src/ErisPulse/CLI/i18n/locales/zh_tw.py

@@ -373,6 +373,17 @@ TRANSLATIONS = {
     "cli.self_update.invalid_selection": "無效的版本序號或版本號",
     # ==================== run 命令 ====================
     "cli.run.description": "執行主程式",
+    "cli.stop.description": "停止正在執行的 ErisPulse 實例（由 epsdk run 啟動）",
+    "cli.stop.force_help": "跳過優雅停止，直接強制終止",
+    "cli.stop.pid_help": "直接指定目標程序 PID（覆蓋執行狀態檔）",
+    "cli.stop.not_running": "未找到執行中的實例——請在專案目錄下執行，且實例由 epsdk run 啟動（python main.py 直啟的程序請用系統工具管理）",
+    "cli.stop.stopping": "正在停止實例 (PID {pid})...",
+    "cli.stop.graceful_timeout": "優雅停止逾時，升級為強制終止...",
+    "cli.stop.stopped": "實例已停止",
+    "cli.stop.failed": "停止實例失敗 (PID {pid})，請手動檢查程序狀態",
+    "cli.restart.description": "重啟正在執行的 ErisPulse 實例（停止後按原參數重新啟動）",
+    "cli.restart.not_running_hint": "未找到執行中的實例——直接執行 epsdk run 啟動即可",
+    "cli.restart.starting_new": "已停止，正在按原參數重新啟動: {cmd}",
     "cli.run.script_help": "要執行的主程式路徑 (不指定則直接執行 SDK)",
     "cli.run.reload_help": "啟用熱重載模式",
     "cli.run.strict_help": "臨時開啟嚴格模式：自檢失敗即退出，框架嚴格級別本次至少為 1（跳過不合規元件）；缺省跟隨 ErisPulse.framework.strict_mode，--no-strict 臨時關閉",

erispulse-2.11.0.dev0/src/ErisPulse/CLI/utils/runtime_state.py

@@ -0,0 +1,208 @@
+"""
+运行实例状态文件（pidfile）工具
+
+``epsdk run`` 启动时把监督进程 PID、当前子进程 PID 与原始 argv 写入
+``.erispulse/runtime.json``（工作目录维度，多项目互不干扰）；
+``epsdk stop`` / ``epsdk restart`` 据此定位并控制运行中的实例。
+
+跨平台语义：
+- POSIX：优先 SIGINT（监督进程按 Ctrl+C 同款路径优雅收尾——finally 链
+  终止子进程），超时升级 SIGTERM → SIGKILL
+- Windows：无进程信号语义，``os.kill(pid, SIGTERM)`` 即 TerminateProcess
+  （强制终止）；stop 命令先断子进程再停监督进程，避免监督者把强杀误判
+  为崩溃而重新拉起
+
+{!--< internal-use >!--}
+供 CLI run / stop / restart 命令使用；状态文件损坏时按不存在处理。
+{!--< /internal-use >!--}
+"""
+
+import json
+import os
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+# 状态文件位置（相对当前工作目录；epsdk run / stop / restart 须在同一项目下执行）
+STATE_DIR = Path(".erispulse")
+STATE_FILE = STATE_DIR / "runtime.json"
+
+# 优雅停止的等待预算（秒）：SIGINT 后等待监督进程自行收尾，超时逐级升级
+GRACEFUL_TIMEOUT_SECS = 8.0
+FORCE_TIMEOUT_SECS = 3.0
+
+
+def state_path() -> Path:
+    """
+    获取状态文件绝对路径（当前工作目录维度）
+
+    :return: Path 状态文件路径
+    """
+    return Path.cwd() / STATE_DIR / STATE_FILE
+
+
+def read() -> "dict | None":
+    """
+    读取运行实例状态
+
+    :return: 状态字典 ``{"pid", "child_pid", "argv", "cwd", "started_at"}``；
+             不存在或损坏时返回 None
+    """
+    path = state_path()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if isinstance(data, dict) and isinstance(data.get("pid"), int):
+            return data
+    except Exception:
+        pass
+    return None
+
+
+def write(pid: int, argv: "list[str] | None" = None, child_pid: "int | None" = None) -> None:
+    """
+    写入/覆盖运行实例状态
+
+    :param pid: 监督进程 PID（``epsdk run`` 自身；``--reload`` 内联模式为当前进程）
+    :param argv: 启动命令（restart 按此重放）
+    :param child_pid: 当前框架子进程 PID（无则省略）
+    """
+    try:
+        state_path().parent.mkdir(parents=True, exist_ok=True)
+        state_path().write_text(
+            json.dumps(
+                {
+                    "pid": pid,
+                    "child_pid": child_pid,
+                    "argv": list(argv or sys.argv),
+                    "cwd": str(Path.cwd()),
+                    "started_at": time.time(),
+                },
+                ensure_ascii=False,
+            ),
+            encoding="utf-8",
+        )
+    except Exception:
+        pass
+
+
+def update_child(child_pid: int) -> None:
+    """
+    更新当前框架子进程 PID（监督进程每次拉起新子进程时调用）
+
+    :param child_pid: 子进程 PID
+    """
+    data = read()
+    if data is None:
+        return
+    data["child_pid"] = child_pid
+    try:
+        state_path().write_text(
+            json.dumps(data, ensure_ascii=False), encoding="utf-8"
+        )
+    except Exception:
+        pass
+
+
+def clear() -> None:
+    """清除状态文件（不存在时静默）"""
+    try:
+        state_path().unlink(missing_ok=True)
+    except Exception:
+        pass
+
+
+def pid_alive(pid: int) -> bool:
+    """
+    判断进程是否存活
+
+    :param pid: 进程 PID
+    :return: 是否存活
+    """
+    if pid <= 0:
+        return False
+    if os.name == "nt":
+        import ctypes
+
+        PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+        STILL_ACTIVE = 259
+        kernel32 = ctypes.windll.kernel32
+        handle = kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
+        if not handle:
+            return False
+        try:
+            exit_code = ctypes.c_ulong()
+            if kernel32.GetExitCodeProcess(handle, ctypes.byref(exit_code)):
+                return exit_code.value == STILL_ACTIVE
+            return False
+        finally:
+            kernel32.CloseHandle(handle)
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+
+
+def terminate(pid: int, force: bool = False) -> bool:
+    """
+    终止进程
+
+    POSIX：默认 SIGINT（监督进程按 Ctrl+C 同款路径优雅收尾）；``force=True``
+    直接 SIGKILL。Windows：无优雅语义，``os.kill`` 即 TerminateProcess。
+
+    :param pid: 目标进程 PID
+    :param force: 是否跳过优雅信号直接强制终止
+    :return: 是否已发送终止信号
+    """
+    try:
+        if os.name == "nt":
+            os.kill(pid, signal.SIGTERM)
+            return True
+        if force:
+            os.kill(pid, signal.SIGKILL)
+        else:
+            os.kill(pid, signal.SIGINT)
+        return True
+    except (ProcessLookupError, PermissionError, OSError):
+        return False
+
+
+def wait_gone(pid: int, timeout: float) -> bool:
+    """
+    等待进程退出
+
+    :param pid: 进程 PID
+    :param timeout: 最长等待秒数
+    :return: 是否已在时限内退出
+    """
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if not pid_alive(pid):
+            return True
+        time.sleep(0.15)
+    return not pid_alive(pid)
+
+
+def kill_tree_hard(pid: int) -> None:
+    """
+    强制终止进程（Windows 下连带其直接子进程的兜底清理）
+
+    :param pid: 进程 PID
+    """
+    if os.name == "nt":
+        try:
+            subprocess.run(
+                ["taskkill", "/PID", str(pid), "/T", "/F"],
+                capture_output=True,
+                check=False,
+            )
+            return
+        except Exception:
+            pass
+    terminate(pid, force=True)

{erispulse-2.10.2 → erispulse-2.11.0.dev0}/src/ErisPulse/Core/Event/__init__.py

@@ -59,6 +59,7 @@ from .session_type import (
     unregister_custom_type,
     unregister_custom_types_by_owner,
 )
+from .command_flow import CommandFlow
 from .wrapper import (
     CONFIRM_NO_WORDS,
     CONFIRM_YES_WORDS,
@@ -118,6 +119,7 @@ __all__ = [
     "SendType",
     "SessionOccupiedError",
     "clear_custom_types",
+    "CommandFlow",
     "command",
     "convert_to_receive_type",
     "convert_to_send_type",

{erispulse-2.10.2 → erispulse-2.11.0.dev0}/src/ErisPulse/Core/Event/base.py

@@ -109,6 +109,14 @@ async def _invoke_handler(handler_info: dict, event: Event) -> None:
     # 注入 owner 上下文：handler 执行期间 current_owner = 模块 owner，
     # 使其内部发起的出站调用（Send / Api / Request）能被作用域权限识别与按 owner 清理
     _owner_token = current_owner.set(_owner) if _owner else None
+    if _owner:
+        # 活跃度埋点（懒加载休眠清扫判定）：owner 已定位，一次字典写入
+        try:
+            from ..module import module as _module_manager
+
+            _module_manager.touch_activity(_owner)
+        except Exception:
+            pass
     try:
         # 依赖注入解析（Depends）：上下文为 Event；依赖异常走本函数统一错误路径
         _depends = handler_info.get("depends")