refactor(runtime): activate managed resources on demand (#6334)

app/adapters/system/display/__init__.py

@@ -0,0 +1,53 @@
+"""虚拟显示适配器及旧 DisplayHelper 兼容入口。"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+from app.foundation.singleton import Singleton
+from app.runtime.log import logger
+from app.runtime.managed_resources import (
+    acquire_managed_resource,
+    stop_managed_resource,
+)
+
+
+DISPLAY_CAPABILITY_ID = "host.display"
+
+
+class DisplayHelper(metaclass=Singleton):
+    """保留旧构造 API，并把资源所有权委托给 host.display 能力。"""
+
+    def __init__(self) -> None:
+        """显式构造旧门面时激活虚拟显示，失败保持旧 API 的日志语义。"""
+        try:
+            acquire_managed_resource(
+                DISPLAY_CAPABILITY_ID,
+                reason="legacy_display_helper",
+                retry=True,
+            )
+        except Exception as error:
+            logger.error("DisplayHelper init error: %s", error)
+
+    def stop(self) -> None:
+        """停止已激活的虚拟显示；未配置 Runtime 时保持幂等。"""
+        stop_managed_resource(
+            DISPLAY_CAPABILITY_ID,
+            reason="legacy_display_helper_stop",
+        )
+
+
+__all__ = ["DISPLAY_CAPABILITY_ID", "DisplayHelper", "VirtualDisplayResource"]
+
+
+def __getattr__(name: str) -> Any:
+    """按需公开资源实现，普通兼容导入不加载显示后端。"""
+    if name != "VirtualDisplayResource":
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(
+        import_module("app.adapters.system.display.resource"),
+        "VirtualDisplayResource",
+    )
+    globals()[name] = value
+    return value

app/adapters/system/display/capability.toml

@@ -0,0 +1,12 @@
+schema_version = 1
+id = "host.display"
+kind = "managed_resource.sync"
+entrypoint = "app.adapters.system.display.resource:VirtualDisplayResource"
+depends_on = []
+
+[metadata]
+name = "Virtual Display"
+
+[activation]
+policy = "on_first_use"
+watch = []

app/adapters/system/display/resource.py

@@ -0,0 +1,45 @@
+"""虚拟显示进程的托管资源实现。"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+from app.adapters.system.host import SystemUtils
+from app.runtime.log import logger
+
+
+class VirtualDisplayResource:
+    """按需拥有一个容器内虚拟显示进程。"""
+
+    def __init__(self) -> None:
+        self._display: Optional[Any] = None
+
+    @property
+    def display(self) -> Optional[Any]:
+        """返回当前拥有的显示对象；未启动或已停止时为 None。"""
+        return self._display
+
+    def start(self) -> None:
+        """仅在容器环境启动虚拟显示，重复启动保持幂等。"""
+        if self._display is not None or not SystemUtils.is_docker():
+            return
+        from pyvirtualdisplay import Display
+
+        display = Display(
+            visible=False,
+            size=(1024, 768),
+            extra_args=[os.environ["DISPLAY"]],
+        )
+        self._display = display
+        display.start()
+
+    def stop(self) -> None:
+        """停止当前资源拥有的显示进程，失败时保留句柄供 Runtime 重试。"""
+        display = self._display
+        if display is None:
+            return
+        logger.info("正在停止虚拟显示...")
+        display.stop()
+        self._display = None
+        logger.info("虚拟显示已停止")