@baimingtao/lbs-agent 1.0.0

package/runtime/orchestration/runtime/process_registry.py

@@ -0,0 +1,605 @@
+"""后台进程注册表 v2 — 增强版。
+
+Hermes ProcessRegistry 的简化实现，增加 PTY / checkpoint / watch_patterns 支持。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import signal
+import subprocess
+import threading
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+
+# ── 常量 ──
+
+_CHECKPOINT_PATH = Path.home() / ".lbs" / "process_checkpoint.json"
+_MAX_PROCESSES = 128
+_WATCH_RATE_LIMIT = 15.0  # seconds between watch notifications
+_WATCH_STRIKE_LIMIT = 3
+
+
+# ═══════════════════════════════════════════
+# 类型定义
+# ═══════════════════════════════════════════
+
+
+class ProcessStatus(Enum):
+    CREATED = "created"
+    RUNNING = "running"
+    STOPPING = "stopping"
+    STOPPED = "stopped"
+    CRASHED = "crashed"
+
+
+@dataclass
+class ProcessSession:
+    """流程会话 — 跟踪进程输出、PTY、watch_patterns。"""
+
+    name: str
+    process: subprocess.Popen | None = None
+    pid: int | None = None
+    status: ProcessStatus = ProcessStatus.CREATED
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc).astimezone())
+    started_at: datetime | None = None
+    stopped_at: datetime | None = None
+    exit_code: int | None = None
+    log_path: str | None = None
+    cmd: list[str] = field(default_factory=list)
+    cwd: str | None = None
+    env: dict[str, str] | None = None
+    error: str = ""
+    tags: dict[str, str] = field(default_factory=dict)
+
+    # 输出缓冲
+    output_buffer: list[str] = field(default_factory=list)
+    output_lines: int = 0
+
+    # PTY
+    pty: bool = False
+    pty_master_fd: int | None = None
+
+    # Watch
+    watch_patterns: list[str] = field(default_factory=list)
+    _last_watch_at: float = 0.0
+    _watch_strikes: int = 0
+    _watcher_alive: bool = True
+
+    # Stop event
+    _stop_event: threading.Event = field(default_factory=threading.Event, repr=False)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+
+    @property
+    def uptime(self) -> str:
+        if not self.started_at:
+            return "0s"
+        duration = (datetime.now(timezone.utc).astimezone() - self.started_at).total_seconds()
+        return fmt_uptime(int(duration))
+
+    @property
+    def running(self) -> bool:
+        return self.status == ProcessStatus.RUNNING
+
+    @property
+    def alive(self) -> bool:
+        """进程还在运行（包括可能已经自行结束）"""
+        if self.process and self.process.poll() is None:
+            return True
+        if self.process and self.process.poll() is not None:
+            self.exit_code = self.process.returncode
+            self.status = ProcessStatus.CRASHED if self.exit_code != 0 else ProcessStatus.STOPPED
+            return False
+        return False
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "pid": self.pid,
+            "status": getattr(self.status, "value", self.status),
+            "cmd": self.cmd,
+            "cwd": self.cwd,
+            "log_path": self.log_path,
+            "created_at": self.created_at.isoformat(),
+            "started_at": self.started_at.isoformat() if self.started_at else None,
+            "stopped_at": self.stopped_at.isoformat() if self.stopped_at else None,
+            "exit_code": self.exit_code,
+            "error": self.error,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ProcessSession":
+        s = cls(
+            name=data["name"],
+            pid=data.get("pid"),
+            status=ProcessStatus(data.get("status", "created")),
+            cmd=data.get("cmd", []),
+            cwd=data.get("cwd"),
+            log_path=data.get("log_path"),
+            error=data.get("error", ""),
+        )
+        if data.get("created_at"):
+            s.created_at = datetime.fromisoformat(data["created_at"])
+        if data.get("started_at"):
+            s.started_at = datetime.fromisoformat(data["started_at"])
+        if data.get("stopped_at"):
+            s.stopped_at = datetime.fromisoformat(data["stopped_at"])
+        s.exit_code = data.get("exit_code")
+        return s
+
+
+# ═══════════════════════════════════════════
+# 辅助函数
+# ═══════════════════════════════════════════
+
+
+def fmt_uptime(seconds: int) -> str:
+    if seconds < 60:
+        return f"{seconds}s"
+    m = seconds // 60
+    s = seconds % 60
+    if m < 60:
+        return f"{m}m{s}s"
+    h = m // 60
+    m = m % 60
+    return f"{h}h{m}m"
+
+
+def _is_pid_alive(pid: int | None) -> bool:
+    if pid is None:
+        return False
+    try:
+        os.kill(pid, 0)
+        return True
+    except (OSError, PermissionError):
+        return False
+
+
+def _clean_output(text: str) -> str:
+    """去除终端控制字符。"""
+    return re.sub(r"\x1b\[[0-9;]*[a-zA-Z]", "", text)
+
+
+# ═══════════════════════════════════════════
+# ProcessRegistry v2
+# ═══════════════════════════════════════════
+
+
+class ProcessRegistry:
+    """全局后台进程注册表。支持注册、启动、停止、健康检查、
+    PTY 输出读取、watch_patterns监控、checkpoint持久化。"""
+
+    def __init__(self, checkpoint_path: str | None = None):
+        self._processes: dict[str, ProcessSession] = {}
+        self._lock = threading.Lock()
+        self._checkpoint_path = Path(checkpoint_path or _CHECKPOINT_PATH)
+        self._reader_threads: list[threading.Thread] = []
+
+    # ── 注册 / 启动 ──
+
+    def register(self, name: str, cmd: list[str], *,
+                 cwd: str | None = None,
+                 env: dict[str, str] | None = None,
+                 log_path: str | None = None,
+                 tags: dict[str, str] | None = None) -> ProcessSession:
+        with self._lock:
+            if name in self._processes:
+                old = self._processes[name]
+                if old.running:
+                    raise RuntimeError(f"进程 {name} 正在运行中 (PID={old.pid})")
+            session = ProcessSession(
+                name=name, cmd=cmd, cwd=cwd, env=env,
+                log_path=log_path, tags=tags or {},
+            )
+            self._processes[name] = session
+            return session
+
+    def start(self, name: str, *, pty: bool = False,
+              watch_patterns: list[str] | None = None) -> ProcessSession:
+        """启动注册的进程。
+
+        Args:
+            name: 进程名
+            pty: 是否启用 PTY 模式
+            watch_patterns: 输出监控模式列表，匹配时触发回调
+        """
+        with self._lock:
+            session = self._processes.get(name)
+            if not session:
+                raise KeyError(f"进程 {name} 未注册")
+            if session.running:
+                raise RuntimeError(f"进程 {name} 已在运行")
+
+            # 创建子进程
+            kwargs: dict = {"stdout": subprocess.PIPE, "stderr": subprocess.PIPE}
+            if pty and os.name != "nt":
+                import os as _os
+                master, slave = _os.openpty()
+                session.pty = True
+                session.pty_master_fd = master
+                kwargs["stdin"] = slave
+                kwargs["stdout"] = slave
+                kwargs["stderr"] = slave
+                kwargs["start_new_session"] = True
+
+            log_f = None
+            if session.log_path:
+                log_f = open(session.log_path, "ab", buffering=0)
+
+            proc = subprocess.Popen(
+                session.cmd,
+                cwd=session.cwd,
+                env=session.env,
+                stdin=subprocess.PIPE if not pty else slave,
+                **{k: v for k, v in kwargs.items() if k not in ("stdin",)},
+            )
+
+            session.process = proc
+            session.pid = proc.pid
+            session.status = ProcessStatus.RUNNING
+            session.started_at = datetime.now(timezone.utc).astimezone()
+            session.watch_patterns = watch_patterns or []
+
+            # 启动输出读取线程
+            if pty:
+                t = threading.Thread(target=self._pty_reader_loop, args=(session,), daemon=True)
+            else:
+                t = threading.Thread(target=self._reader_loop, args=(session, log_f), daemon=True)
+            t.start()
+            self._reader_threads.append(t)
+
+            return session
+
+    # ── PTY 输出读取 ──
+
+    def _pty_reader_loop(self, session: ProcessSession) -> None:
+        """读取 PTY 输出并缓冲。仅 Unix 有效。"""
+        import os as _os
+        import select
+        fd = session.pty_master_fd
+        if fd is None or os.name == "nt":
+            return
+        try:
+            while not session._stop_event.is_set():
+                r, _, _ = select.select([fd], [], [], 0.5)
+                if r:
+                    data = _os.read(fd, 4096)
+                    if not data:
+                        break
+                    text = data.decode("utf-8", errors="replace")
+                    for line in text.splitlines():
+                        session.output_buffer.append(line)
+                    session.output_lines += text.count("\n")
+                    self._check_watch_patterns(session, text)
+                    if session.log_path:
+                        try:
+                            with open(session.log_path, "a", encoding="utf-8") as lf:
+                                lf.write(text)
+                        except OSError:
+                            pass
+        except (OSError, ValueError):
+            pass
+        finally:
+            try:
+                _os.close(fd)
+            except OSError:
+                pass
+
+    def _reader_loop(self, session: ProcessSession, log_f) -> None:
+        """读取标准输出/错误并缓冲。
+
+        使用 threading.Thread 逐行读取（兼容 Windows pipe 不支持 select）。
+        """
+        def _read_stream(stream, stream_name: str):
+            try:
+                for raw_line in stream:
+                    if session._stop_event.is_set():
+                        break
+                    text = raw_line.decode("utf-8", errors="replace").rstrip("\r\n")
+                    session.output_buffer.append(text)
+                    session.output_lines += 1
+                    self._check_watch_patterns(session, text)
+                    if log_f:
+                        try:
+                            log_f.write(raw_line)
+                        except OSError:
+                            pass
+            except (ValueError, OSError):
+                pass
+
+        threads = []
+        if session.process and session.process.stdout:
+            t = threading.Thread(target=_read_stream, args=(session.process.stdout, "stdout"), daemon=True)
+            t.start()
+            threads.append(t)
+        if session.process and session.process.stderr:
+            t = threading.Thread(target=_read_stream, args=(session.process.stderr, "stderr"), daemon=True)
+            t.start()
+            threads.append(t)
+
+        # 等待输出读取线程 + 进程结束
+        for t in threads:
+            t.join(timeout=5)
+        if session.process:
+            try:
+                session.process.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                session.process.kill()
+                session.process.wait(timeout=5)
+            session.exit_code = session.process.returncode
+
+        with self._lock:
+            session.status = ProcessStatus.STOPPED if session.exit_code == 0 else ProcessStatus.CRASHED
+            session.stopped_at = datetime.now(timezone.utc).astimezone()
+            self._write_checkpoint()
+
+        if log_f:
+            try:
+                log_f.close()
+            except OSError:
+                pass
+
+    # ── Watch Patterns ──
+
+    def _check_watch_patterns(self, session: ProcessSession, text: str) -> None:
+        """检测输出是否匹配监控模式。"""
+        if not session.watch_patterns or not session._watcher_alive:
+            return
+
+        now = time.time()
+        if now - session._last_watch_at < _WATCH_RATE_LIMIT:
+            session._watch_strikes += 1
+            if session._watch_strikes >= _WATCH_STRIKE_LIMIT:
+                session._watcher_alive = False
+            return
+
+        for pattern in session.watch_patterns:
+            if pattern in text:
+                session._last_watch_at = now
+                session._watch_strikes = 0
+                self._emit_watch_match(session, pattern, text)
+                break
+
+    def _emit_watch_match(self, session: ProcessSession, pattern: str, matched: str) -> None:
+        """触发监控匹配事件。"""
+        evt = {
+            "type": "process.watch_match",
+            "name": session.name,
+            "pid": session.pid,
+            "pattern": pattern,
+            "matched": matched[:200],
+            "ts": time.time(),
+        }
+        # Can be captured by EventBus later
+
+    # ── 停止 / 杀死 ──
+
+    def stop(self, name: str, timeout: float = 5.0) -> dict:
+        """优雅停止进程。"""
+        with self._lock:
+            session = self._processes.get(name)
+            if not session:
+                return {"ok": False, "error": f"进程 {name} 未注册"}
+
+            if not session.running:
+                return {"ok": True, "status": getattr(session.status, "value", session.status)}
+
+            proc = session.process
+            if not proc:
+                return {"ok": False, "error": "No process handle"}
+
+            session._stop_event.set()
+            session.status = ProcessStatus.STOPPING
+
+        # Windows: CTRL_BREAK_EVENT; Unix: SIGTERM
+        try:
+            if os.name == "nt":
+                proc.send_signal(signal.CTRL_BREAK_EVENT)
+            else:
+                proc.terminate()
+            proc.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait(timeout=5)
+        except OSError:
+            pass
+
+        with self._lock:
+            session.exit_code = proc.returncode
+            session.status = ProcessStatus.STOPPED if proc.returncode == 0 else ProcessStatus.CRASHED
+            session.stopped_at = datetime.now(timezone.utc).astimezone()
+            self._write_checkpoint()
+
+        return {"ok": True, "exit_code": session.exit_code, "status": getattr(session.status, "value", session.status)}
+
+    def kill(self, name: str) -> dict:
+        """强制杀死进程。"""
+        with self._lock:
+            session = self._processes.get(name)
+            if not session or not session.process:
+                return {"ok": False, "error": f"进程 {name} 未注册或已经结束"}
+
+            session._stop_event.set()
+            try:
+                session.process.kill()
+                session.process.wait(timeout=5)
+            except (subprocess.TimeoutExpired, OSError):
+                pass
+
+            session.exit_code = session.process.returncode
+            session.status = ProcessStatus.CRASHED
+            session.stopped_at = datetime.now(timezone.utc).astimezone()
+            self._write_checkpoint()
+
+        return {"ok": True, "exit_code": session.exit_code}
+
+    # ── 查询 ──
+
+    def get(self, name: str) -> ProcessSession | None:
+        with self._lock:
+            session = self._processes.get(name)
+            if session:
+                session.alive  # 触发状态同步
+            return session
+
+    def list(self, status: str | None = None) -> list[dict]:
+        """列出所有进程。"""
+        result = []
+        with self._lock:
+            for session in self._processes.values():
+                if status and getattr(session.status, "value", session.status) != status:
+                    continue
+                d = session.to_dict()
+                d["uptime"] = session.uptime
+                d["output_lines"] = session.output_lines
+                result.append(d)
+        return result
+
+    def count_running(self) -> int:
+        """当前运行的进程数。"""
+        count = 0
+        with self._lock:
+            for session in self._processes.values():
+                if session.running:
+                    count += 1
+        return count
+
+    def has_active(self) -> bool:
+        """是否有活动进程。"""
+        return self.count_running() > 0
+
+    # ── 输出 ──
+
+    def read_output(self, name: str, offset: int = 0, limit: int = 50) -> list[str]:
+        """读取进程缓冲输出。"""
+        session = self.get(name)
+        if not session:
+            return []
+        buf = session.output_buffer
+        return buf[offset:offset + limit]
+
+    # ── Stale cleanup ──
+
+    def cleanup(self, max_age_seconds: float = 3600) -> int:
+        """清理已经结束的进程。"""
+        now = datetime.now(timezone.utc).astimezone()
+        removed = 0
+        for name in list(self._processes.keys()):
+            session = self._processes.get(name)
+            if not session:
+                continue
+            if session.status in (ProcessStatus.STOPPED, ProcessStatus.CRASHED):
+                if session.stopped_at and (now - session.stopped_at).total_seconds() > max_age_seconds:
+                    self.remove(name)
+                    removed += 1
+        return removed
+
+    def remove(self, name: str) -> bool:
+        """移除进程记录。"""
+        with self._lock:
+            session = self._processes.get(name)
+            if session and session.running:
+                return False  # 不能移除正在运行的进程
+            return self._processes.pop(name, None) is not None
+
+    # ── Checkpoint 持久化 ──
+
+    def _write_checkpoint(self) -> None:
+        """将进程状态写入检查点文件。"""
+        try:
+            data = []
+            for session in self._processes.values():
+                if session.status in (ProcessStatus.STOPPED, ProcessStatus.CRASHED):
+                    data.append(session.to_dict())
+            self._checkpoint_path.parent.mkdir(parents=True, exist_ok=True)
+            self._checkpoint_path.write_text(
+                json.dumps(data, ensure_ascii=False, indent=2, default=str),
+                encoding="utf-8",
+            )
+        except (OSError, json.JSONEncodeError):
+            pass
+
+    def recover_from_checkpoint(self) -> int:
+        """从检查点恢复已完成的进程记录。"""
+        if not self._checkpoint_path.exists():
+            return 0
+        try:
+            data = json.loads(self._checkpoint_path.read_text(encoding="utf-8"))
+            count = 0
+            for item in data:
+                session = ProcessSession.from_dict(item)
+                name = session.name
+                if name not in self._processes:
+                    self._processes[name] = session
+                    count += 1
+            return count
+        except (OSError, json.JSONDecodeError, KeyError, ValueError):
+            return 0
+
+    # ── Kill all ──
+
+    def kill_all(self) -> int:
+        """杀死所有正在运行的进程。"""
+        count = 0
+        for name in list(self._processes.keys()):
+            session = self._processes.get(name)
+            if session and session.running:
+                self.kill(name)
+                count += 1
+        return count
+
+    def shutdown(self) -> None:
+        """关闭注册表——停止所有进程、保存 checkpoint。"""
+        self.kill_all()
+        self._write_checkpoint()
+
+
+# ═══════════════════════════════════════════
+# 全局单例
+# ═══════════════════════════════════════════
+
+_registry: ProcessRegistry | None = None
+_lock = threading.Lock()
+
+
+def get_registry() -> ProcessRegistry:
+    global _registry
+    with _lock:
+        if _registry is None:
+            _registry = ProcessRegistry()
+            _registry.recover_from_checkpoint()
+        return _registry
+
+
+def reset_registry() -> None:
+    global _registry
+    with _lock:
+        if _registry:
+            _registry.shutdown()
+        _registry = None
+
+
+# ── 格式化通知 — Hermes compatibility ──
+
+def format_process_notification(evt: dict) -> str | None:
+    """格式化进程事件通知。 Hermes 兼容。"""
+    t = evt.get("type")
+    name = evt.get("name", "?")
+    if t == "process.watch_match":
+        pat = evt.get("pattern", "?")
+        m = evt.get("matched", "")[:100]
+        return f"[WATCH] {name}: pattern={pat!r} matched={m!r}"
+    if t == "process.finished":
+        ec = evt.get("exit_code")
+        icon = "OK" if ec == 0 else "FAIL"
+        up = evt.get("uptime", "")
+        return f"[{icon}] {name} exited={ec} uptime={up}"
+    return None