muse-driver-framework 1.0.0__py3-none-any.whl

muse_driver_framework/driver_framework.py

@@ -0,0 +1,1442 @@
+"""MUSE Python 程序可复用的异步 TCP 设备框架。
+
+这个文件提供通用连接生命周期和实时帧组件，不直接依赖 ``mojo.context``：
+
+* ``AsyncTcpDeviceManager`` 创建一个后台线程和一个共享 asyncio Event Loop；
+* 每台设备对应一个 ``AsyncTcpDeviceClient``，在共享 Event Loop 中运行；
+* 每台设备有独立的监听、发送队列、状态轮询和断线重连任务；
+* ``MeterStream`` 提供与传输无关的只读表头整帧缓存和限频发布；
+* 具体协议如何登录、如何生成命令、如何解析反馈，由 ``index.py`` 中的子类实现。
+"""
+
+# asyncio 提供协程、Event Loop、异步 TCP 连接和异步队列。
+import asyncio
+
+# json 用于在管理器基类中读取通用设备配置。
+import json
+import inspect
+import math
+import time
+import uuid
+
+# threading 用来把 asyncio Event Loop 放进独立后台线程，避免阻塞 MUSE 主线程。
+import threading
+
+# ABC 和 abstractmethod 用来声明必须由具体设备驱动实现的接口。
+from abc import ABC, abstractmethod
+
+
+CONTROL_TYPE_SCHEMA_VERSION = 1
+CONTROL_TYPE_DEFINITIONS = {
+    "slider": {"family": "number", "delivery": "continuous"},
+    "level": {"family": "number", "delivery": "continuous"},
+    "volume": {"family": "number", "delivery": "continuous"},
+    # Meter is read-only realtime telemetry, not a writable numeric control.
+    "meter": {"family": "number", "delivery": "realtime", "access": "ro"},
+    "dimmer": {"family": "number", "delivery": "continuous"},
+    "position": {"family": "number", "delivery": "continuous"},
+    "toggle": {"family": "boolean", "delivery": "discrete"},
+    "mute": {"family": "boolean", "delivery": "discrete"},
+    "power": {"family": "boolean", "delivery": "discrete"},
+    "text": {"family": "text", "delivery": "discrete"},
+    "string": {"family": "text", "delivery": "discrete"},
+    "source": {"family": "enum", "delivery": "discrete"},
+    "preset": {"family": "enum", "delivery": "discrete"},
+}
+
+
+def export_control_type_contract():
+    """Return the versioned UI contract mirrored into the ControlPanel npm package."""
+    return {
+        "schemaVersion": CONTROL_TYPE_SCHEMA_VERSION,
+        "types": CONTROL_TYPE_DEFINITIONS,
+    }
+
+
+def meter_route_from_descriptor(descriptor):
+    """Return validated Meter delivery metadata from a program descriptor.
+
+    A numeric ``.type`` alone cannot distinguish gain from realtime signal
+    telemetry.  Meter therefore uses explicit ``.metadata.meter`` delivery
+    metadata, while the ordinary ``controlType`` hint remains unused.
+    """
+    if not isinstance(descriptor, dict) or descriptor.get(".kind") != "param":
+        return None
+    metadata = descriptor.get(".metadata", {})
+    route = metadata.get("meter") if isinstance(metadata, dict) else None
+    if route is None:
+        return None
+    if (
+        descriptor.get(".access") != "ro"
+        or descriptor.get(".type") not in ("integer", "float")
+        or descriptor.get(".enums")
+    ):
+        raise ValueError("meter descriptors must be readonly numeric parameters")
+    minimum = descriptor.get(".min")
+    maximum = descriptor.get(".max")
+    if (
+        not isinstance(minimum, (int, float)) or isinstance(minimum, bool)
+        or not isinstance(maximum, (int, float)) or isinstance(maximum, bool)
+        or not math.isfinite(minimum) or not math.isfinite(maximum)
+        or minimum >= maximum
+        or (descriptor.get(".type") == "integer" and
+            (type(minimum) is not int or type(maximum) is not int))
+    ):
+        raise ValueError("meter descriptors require finite increasing bounds")
+    if not isinstance(route, dict):
+        raise ValueError("meter metadata must be an object")
+
+    stream_id = route.get("streamId")
+    event_path = route.get("eventPath")
+    manifest_path = route.get("manifestPath")
+    if (
+        not isinstance(stream_id, str) or not 1 <= len(stream_id.strip()) <= 255
+        or not isinstance(event_path, str) or not event_path.startswith("//")
+        or not isinstance(manifest_path, str) or not manifest_path.startswith("//")
+        or event_path == manifest_path
+    ):
+        raise ValueError("meter metadata requires streamId, eventPath and manifestPath")
+    return {
+        "streamId": stream_id.strip(),
+        "eventPath": event_path,
+        "manifestPath": manifest_path,
+    }
+
+
+class MeterStream:
+    """Bounded, latest-only numeric telemetry; publishers are supplied by adapters.
+
+    ``points`` maps paths to standard readonly numeric descriptors. Offering
+    samples never schedules a task. One consumer calls ``run`` or ``take_frame``.
+    """
+
+    def __init__(self, stream_id, points, unit="", publish_hz=30,
+                 layout_version=1, clock=time.monotonic):
+        if not isinstance(stream_id, str) or not 1 <= len(stream_id.strip()) <= 255:
+            raise ValueError("stream_id must be a nonempty string of at most 255 characters")
+        if not isinstance(points, dict) or not 1 <= len(points) <= 256:
+            raise ValueError("points must contain 1..256 readonly numeric descriptors")
+        if not self._number(publish_hz) or not 1 <= publish_hz <= 60:
+            raise ValueError("publish_hz must be between 1 and 60")
+        if type(layout_version) is not int or not 1 <= layout_version <= 2147483647:
+            raise ValueError("layout_version must be a positive 32-bit integer")
+        if not isinstance(unit, str) or len(unit) > 32:
+            raise ValueError("unit must be a string of at most 32 characters")
+
+        self.stream_id = stream_id.strip()
+        self.publish_hz = publish_hz
+        self.layout_version = layout_version
+        self._clock = clock
+        self._points = []
+        paths = set()
+        for path, descriptor in points.items():
+            if not isinstance(path, str) or not 1 <= len(path.strip("/")) <= 1024:
+                raise ValueError("meter paths must be nonempty strings")
+            path = "/" + path.strip("/")
+            if path in paths:
+                raise ValueError("duplicate meter path")
+            paths.add(path)
+            if not isinstance(descriptor, dict) or descriptor.get(".kind") != "param" or \
+                    descriptor.get(".access") != "ro" or \
+                    descriptor.get(".type") not in ("integer", "float") or descriptor.get(".enums"):
+                raise ValueError("meters require readonly numeric parameters without enums")
+            minimum, maximum = descriptor.get(".min"), descriptor.get(".max")
+            if not self._number(minimum) or not self._number(maximum) or minimum >= maximum:
+                raise ValueError("meter descriptors require finite increasing bounds")
+            if descriptor[".type"] == "integer" and \
+                    (type(minimum) is not int or type(maximum) is not int):
+                raise ValueError("integer meter bounds must be integers")
+            self._points.append({"path": path, "type": descriptor[".type"],
+                                 "min": minimum, "max": maximum, "unit": unit})
+
+        self._lock = threading.Lock()
+        self._epoch = uuid.uuid4().hex
+        self._seq = 0
+        self._latest = None
+        self._pending = False
+        self._next_publish_at = 0
+        self._closed = False
+        self._running = False
+        self._offered = self._overwritten = self._taken = 0
+
+    @staticmethod
+    def _number(value):
+        if type(value) is int:
+            return abs(value) <= 9007199254740991
+        return type(value) is float and math.isfinite(value)
+
+    @staticmethod
+    def _copy_frame(frame):
+        return None if frame is None else {**frame, "values": list(frame["values"]),
+                                           "valid": list(frame["valid"])}
+
+    def manifest(self):
+        with self._lock:
+            return {"kind": "meter-manifest", "streamId": self.stream_id,
+                    "epoch": self._epoch, "layoutVersion": self.layout_version,
+                    "publishHz": self.publish_hz, "clock": "monotonic-ms",
+                    "points": [dict(point) for point in self._points]}
+
+    def offer_frame(self, values, valid=None, sample_time=None):
+        """Validate the entire frame before replacing the latest slot, from any thread."""
+        if not isinstance(values, (list, tuple)) or len(values) != len(self._points):
+            raise ValueError("frame length must match the meter manifest")
+        valid = [True] * len(values) if valid is None else valid
+        if not isinstance(valid, (list, tuple)) or len(valid) != len(values) or \
+                any(type(flag) is not bool for flag in valid):
+            raise ValueError("valid must contain one boolean per meter")
+        normalized = []
+        for point, value, flag in zip(self._points, values, valid):
+            if not flag:
+                normalized.append(None)
+                continue
+            if not self._number(value) or not point["min"] <= value <= point["max"] or \
+                    (point["type"] == "integer" and type(value) is not int):
+                raise ValueError("valid meter samples must match their numeric descriptor")
+            normalized.append(value)
+        sample_time = self._clock() * 1000 if sample_time is None else sample_time
+        if not self._number(sample_time) or sample_time < 0:
+            raise ValueError("sample_time must be finite nonnegative monotonic milliseconds")
+        with self._lock:
+            if self._closed:
+                return False
+            self._replace(normalized, list(valid), sample_time)
+        return True
+
+    def _replace(self, values, valid, sample_time):
+        self._overwritten += int(self._pending)
+        self._offered += 1
+        self._seq += 1
+        self._latest = {"kind": "meter-frame", "streamId": self.stream_id,
+                        "epoch": self._epoch, "seq": self._seq,
+                        "layoutVersion": self.layout_version, "sampleTime": sample_time,
+                        "values": values, "valid": valid}
+        self._pending = True
+
+    def snapshot(self):
+        with self._lock:
+            return self._copy_frame(self._latest)
+
+    def take_frame(self):
+        """Return at most one current frame per period; never catch up missed periods."""
+        with self._lock:
+            now = self._clock()
+            if self._closed or not self._pending or now < self._next_publish_at:
+                return None
+            self._pending = False
+            self._next_publish_at = now + 1 / self.publish_hz
+            self._taken += 1
+            return self._copy_frame(self._latest)
+
+    def reset(self):
+        """Invalidate all channels and change epoch after a source reconnect."""
+        with self._lock:
+            if self._closed:
+                return False
+            self._epoch = uuid.uuid4().hex
+            self._seq = 0
+            self._next_publish_at = 0
+            self._replace([None] * len(self._points), [False] * len(self._points),
+                          self._clock() * 1000)
+        return True
+
+    def stats(self):
+        with self._lock:
+            return {"offered": self._offered, "overwritten": self._overwritten,
+                    "taken": self._taken, "pending": int(self._pending)}
+
+    def close(self):
+        with self._lock:
+            self._closed = True
+            self._pending = False
+            self._latest = None
+
+    async def run(self, publish):
+        """One adapter-owned publisher task; exceptions propagate to its supervisor."""
+        if not callable(publish):
+            raise ValueError("publish must be callable")
+        with self._lock:
+            if self._running:
+                raise RuntimeError("meter stream already has a publisher")
+            self._running = True
+        try:
+            while not self._closed:
+                frame = self.take_frame()
+                if frame is not None:
+                    result = publish(frame)
+                    if inspect.isawaitable(result):
+                        await result
+                await asyncio.sleep(1 / self.publish_hz)
+        finally:
+            with self._lock:
+                self._running = False
+
+
+class ProgramControl:
+    """一个由 program.json metadata 描述的可控参数。"""
+
+    def __init__(self, path, descriptor):
+        metadata = descriptor.get(".metadata", {})
+        if not isinstance(metadata, dict):
+            metadata = {}
+
+        self.path = "/" + str(path).strip("/")
+        self.name = self.path.rsplit("/", 1)[-1]
+        self.value_type = descriptor.get(".type")
+        self.access = descriptor.get(".access", "c")
+        self.minimum = descriptor.get(".min")
+        self.maximum = descriptor.get(".max")
+        self.enums = tuple(descriptor.get(".enums", ()))
+        self.meter = meter_route_from_descriptor(descriptor)
+        self.control_type = infer_control_type(descriptor)
+        definition = CONTROL_TYPE_DEFINITIONS.get(self.control_type, {})
+        self.control_family = definition.get("family", "")
+        self.control_delivery = definition.get("delivery", "")
+        # 在普通 descriptor 中这是最终协议号；声明了
+        # protocolChannelMode=per-element 的数组会在注册表展开时把它解释为
+        # 通道内编号，再换算成最终协议号。
+        self.protocol_channel_ordinal = self._parse_optional_int(
+            metadata.get("protocolChannel")
+        )
+        self.protocol_channel = self.protocol_channel_ordinal
+        self.requires_ack = self._parse_bool(metadata.get("requiresAck", False))
+
+        self._refresh_key()
+
+    def _refresh_key(self):
+        """根据当前的最终协议号重建发送队列 key。"""
+        if self.control_type and self.protocol_channel is not None:
+            self.key = f"{self.control_type}:{self.protocol_channel}"
+        else:
+            self.key = f"{self.control_type}:{self.path}"
+
+    def set_protocol_channel(self, protocol_channel):
+        """设置数组展开后的最终协议号，并同步更新队列 key。"""
+        self.protocol_channel = int(protocol_channel)
+        self._refresh_key()
+
+    @staticmethod
+    def _parse_optional_int(value):
+        if value is None or value == "":
+            return None
+        try:
+            return int(value)
+        except (TypeError, ValueError) as ex:
+            raise ValueError(f"protocolChannel must be an integer: {value!r}") from ex
+
+    @staticmethod
+    def _parse_bool(value):
+        if isinstance(value, bool):
+            return value
+        return str(value).strip().lower() in ("1", "true", "yes", "on")
+
+
+def infer_control_type(descriptor):
+    """Infer the transport family from a standard parameter descriptor.
+
+    ``controlType`` used to be an optional driver hint. It is deliberately not
+    consulted here: the descriptor's value type, enum list, and finite bounds
+    are the source of truth shared with the visual binding catalog.
+    """
+    if not isinstance(descriptor, dict) or descriptor.get(".kind") != "param":
+        return ""
+    if meter_route_from_descriptor(descriptor) is not None:
+        return "meter"
+    value_type = str(descriptor.get(".type", "")).strip().lower()
+    enums = descriptor.get(".enums", ())
+    has_enums = isinstance(enums, (list, tuple)) and bool(enums)
+    minimum = descriptor.get(".min")
+    maximum = descriptor.get(".max")
+    if value_type == "boolean":
+        return "toggle"
+    if value_type == "integer" and minimum == 0 and maximum == 1 and not has_enums:
+        return "toggle"
+    if value_type == "enum" or (has_enums and value_type in ("integer", "string")):
+        return "source"
+    if value_type in ("integer", "float"):
+        return "slider"
+    if value_type in ("string", "dstring"):
+        return "text"
+    return ""
+
+
+class ProgramControlRegistry:
+    """从 MUSE program descriptor 建立可控参数索引。
+
+    标准字段决定类型、范围和读写权限，``.metadata`` 只补充协议编号和 ACK 策略。
+    不把具体参数名称写死在驱动代码中。
+    """
+
+    def __init__(self, descriptor):
+        if not isinstance(descriptor, dict):
+            raise ValueError("program descriptor must be an object")
+        self.descriptor = descriptor
+        self.controls = []
+        self._by_path = {}
+        self._walk(descriptor, [])
+
+    @staticmethod
+    def _normalize_path(path):
+        return "/" + str(path).strip("/")
+
+    @classmethod
+    def _protocol_channel_ordinals(cls, node):
+        """读取一个数组 prototype 中声明的通道内协议编号。"""
+        if not isinstance(node, dict):
+            return []
+        if node.get(".kind") == "param":
+            metadata = node.get(".metadata", {})
+            if not isinstance(metadata, dict):
+                return []
+            ordinal = ProgramControl._parse_optional_int(
+                metadata.get("protocolChannel")
+            )
+            return [ordinal] if ordinal is not None else []
+        if node.get(".kind") == "array":
+            return []
+
+        ordinals = []
+        for name, child in node.items():
+            if not str(name).startswith("."):
+                ordinals.extend(cls._protocol_channel_ordinals(child))
+        return ordinals
+
+    @classmethod
+    def _array_protocol_stride(cls, node):
+        """验证 per-element 编号为 1..n，并返回 n。"""
+        metadata = node.get(".metadata", {}) if isinstance(node, dict) else {}
+        if not isinstance(metadata, dict) or metadata.get("protocolChannelMode") != "per-element":
+            return None
+
+        ordinals = cls._protocol_channel_ordinals(node.get(".prototype"))
+        expected = list(range(1, len(ordinals) + 1))
+        if not ordinals or sorted(ordinals) != expected:
+            raise ValueError(
+                "per-element protocolChannel values must be a unique sequence 1..n"
+            )
+        return len(ordinals)
+
+    def _walk(self, node, path, array_protocol=None):
+        if not isinstance(node, dict):
+            return
+
+        kind = node.get(".kind")
+        if kind == "array":
+            prototype = node.get(".prototype")
+            size = node.get(".size", 0)
+            if isinstance(size, int) and size > 0 and prototype is not None:
+                stride = self._array_protocol_stride(node)
+                for index in range(size):
+                    child_protocol = array_protocol
+                    if stride is not None:
+                        child_protocol = {
+                            "offset": index * stride,
+                            "stride": stride,
+                        }
+                    self._walk(
+                        prototype,
+                        path + [str(index)],
+                        child_protocol,
+                    )
+            return
+
+        if kind == "param":
+            control = ProgramControl("/".join(path), node)
+            if control.control_type:
+                if array_protocol and control.protocol_channel is not None:
+                    ordinal = control.protocol_channel
+                    if not 1 <= ordinal <= array_protocol["stride"]:
+                        raise ValueError(
+                            f"protocolChannel must be between 1 and "
+                            f"{array_protocol['stride']} for {control.path}"
+                        )
+                    control.set_protocol_channel(
+                        array_protocol["offset"] + ordinal
+                    )
+                self.controls.append(control)
+                self._by_path[control.path] = control
+            return
+
+        # Root descriptor 和 obj 都只递归用户定义的非点号字段。
+        for name, child in node.items():
+            if not str(name).startswith("."):
+                self._walk(child, path + [str(name)], array_protocol)
+
+    def resolve(self, path):
+        """按 MUSE 内部零起始路径查找一个 metadata 控件。"""
+        return self._by_path.get(self._normalize_path(path))
+
+    def protocol_channels(self, control_types=None):
+        """返回 metadata 中声明过的协议控制号。"""
+        allowed = None
+        if control_types is not None:
+            allowed = {str(item).strip().lower() for item in control_types}
+
+        channels = {
+            control.protocol_channel
+            for control in self.controls
+            if control.protocol_channel is not None
+            and (allowed is None or control.control_type in allowed)
+        }
+        return tuple(sorted(channels))
+
+    def control_types_for_channel(self, protocol_channel):
+        return {
+            control.control_type
+            for control in self.controls
+            if control.protocol_channel == int(protocol_channel)
+        }
+
+    def paths_for(self, processor_slot, control_type, protocol_channel):
+        """返回某设备/协议控制号对应的所有 descriptor 参数路径。"""
+        prefix = f"/processors/{int(processor_slot)}/"
+        normalized_type = str(control_type).strip().lower()
+        return tuple(
+            control.path
+            for control in self.controls
+            if control.path.startswith(prefix)
+            and control.control_type == normalized_type
+            and control.protocol_channel == int(protocol_channel)
+        )
+
+
+class AsyncTcpDeviceClient(ABC):
+    """一台 TCP 设备的通用连接客户端。
+    子类必须实现 ``handle_feedback``，通常还会覆盖 ``status_commands``。
+    需要登录的设备可覆盖 ``handshake``；使用二进制或非逐行协议的设备可覆盖
+    ``read_message`` 和 ``encode_command``。
+    """
+
+    # 离散控制必须逐条保序；连续控制只需要追踪每个控制号的最新目标。
+    DISCRETE_CONTROL_TYPES = frozenset(
+        ("discrete", "power", "source", "preset", "toggle")
+    )
+    CONTINUOUS_CONTROL_TYPES = frozenset(
+        ("continuous", "slider", "dimmer", "position")
+    )
+
+    def __init__(self, manager, config):
+        # 保存所属管理器；客户端通过管理器取得日志、Event Loop 和调度能力。
+        self.manager = manager
+
+        # 可选的 program.json 控件索引由具体 manager 注入；没有描述符的旧驱动
+        # 仍可继续使用连接和发送框架。
+        self.control_registry = getattr(manager, "control_registry", None)
+
+        # slot 是设备在 Script-as-Device 数组中的固定索引。
+        self.slot = config["slot"]
+
+        # device_id 用于日志和设备身份识别，name 是面向用户的名称。
+        self.device_id = config["id"]
+        self.name = config["name"]
+
+        # 目标设备的 TCP 地址。
+        self.host = config["host"]
+        self.port = config["port"]
+
+        # 登录信息是可选项；不需要登录的协议保持为空字符串。
+        self.username = config.get("username", "")
+        self.password = config.get("password", "")
+
+        # 连接失败后的等待时间，以及协议登录阶段的超时时间。
+        self.reconnect_delay = config.get("reconnect_delay_seconds", 10)
+        self.login_timeout = config.get("login_timeout_seconds", 10)
+
+        # 状态轮询间隔；0 表示关闭定时轮询。
+        self.status_poll = config.get("status_poll_seconds", 0)
+
+        # 是否在 TCP 登录完成后主动执行一次 status_commands()。
+        self.query_on_connect = config.get("query_on_connect", True)
+
+        # 限制待发送命令数量，防止设备响应慢时队列无限增长。
+        self.command_queue_size = config.get("command_queue_size", 100)
+
+        # 高频可合并命令的最小发送间隔；0.04 秒即每秒最多 25 次更新。
+        self.latest_command_interval = config.get(
+            "latest_command_interval_seconds",
+            0.04,
+        )
+
+        # 高频命令和反馈日志只用于现场排查，正常运行默认关闭以减少 I/O 开销。
+        self.traffic_debug = config.get("traffic_debug", False)
+
+        # reader/writer 由 asyncio.open_connection() 建立连接后赋值。
+        self.reader = None
+        self.writer = None
+
+        # connected_event 表示当前连接可用；command_queue 串行保存发送任务。
+        self.connected_event = None
+        self.command_queue = None
+
+        # 高频参数（如音量滑块）可按 key 合并，队列中只保留同 key 的最新值。
+        self._latest_commands = {}
+        self._queued_latest_keys = set()
+        self._latest_command_marker = object()
+        self._latest_sent_at = {}
+
+        # is_online 是提供给上层发布的布尔状态。
+        self.is_online = False
+
+        # running 控制永久重连循环；设为 False 后不再重连。
+        self.running = True
+
+    @property
+    def log_name(self):
+        """返回同时包含设备 ID 和数组槽位的日志名称。"""
+        return f"{self.device_id}[{self.slot}]"
+
+    async def connect_loop(self, initial_delay=0):
+        """持续执行连接、运行、清理和延时重连的完整生命周期。"""
+        # Event 和 Queue 必须在实际运行它们的 Event Loop 线程中创建。
+        self.connected_event = asyncio.Event()
+        self.command_queue = asyncio.Queue(maxsize=self.command_queue_size)
+
+        # 多设备启动时错开连接，避免瞬间同时创建大量 TCP 连接。
+        if initial_delay:
+            await asyncio.sleep(initial_delay)
+
+        # 每次连接断开后，只要 running 仍为 True，就继续下一轮重连。
+        while self.running:
+            # 保存本次连接创建的监听、发送和轮询任务，方便统一取消和回收。
+            connection_tasks = []
+            try:
+                # 输出当前连接目标，便于在 MUSE 日志中定位具体设备。
+                self.manager.log.info(
+                    f"{self.log_name} connecting to {self.host}:{self.port}"
+                )
+
+                # 异步建立 TCP 连接；等待期间不会阻塞其他设备任务。
+                self.reader, self.writer = await asyncio.open_connection(
+                    self.host,
+                    self.port,
+                )
+
+                # 执行子类定义的登录或初始化握手；默认实现什么也不做。
+                await self.handshake()
+
+                # 握手成功后才把设备标记为可发送命令和在线。
+                self.connected_event.set()
+                self._publish_online(True)
+
+                # 某些设备查询会返回大量反馈；是否上线即查询由配置决定。
+                if self.query_on_connect:
+                    initial_commands = self.status_commands()
+                    if initial_commands:
+                        await self._send_sequence_direct(initial_commands)
+
+                # 监听任务负责收反馈；发送任务负责按队列顺序写 socket。
+                connection_tasks = [
+                    asyncio.create_task(self._socket_listener()),
+                    asyncio.create_task(self._socket_sender()),
+                ]
+
+                # status_poll 大于 0 时，再增加一个周期状态查询任务。
+                if self.status_poll > 0:
+                    connection_tasks.append(
+                        asyncio.create_task(self._status_poll_loop())
+                    )
+
+                # 任一任务结束通常表示连接已失效，需要结束同组其他任务并重连。
+                done, pending = await asyncio.wait(
+                    connection_tasks,
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
+
+                # 取消仍在运行的同连接任务。
+                for task in pending:
+                    task.cancel()
+
+                # 读取已结束任务的结果；其中的异常会进入下面的异常处理。
+                for task in done:
+                    task.result()
+            except asyncio.CancelledError:
+                # 外部取消 connect_loop 时永久退出，不再进入重连流程。
+                self.running = False
+                raise
+            except Exception as ex:
+                # 网络、登录、读取或发送错误都在这里记录，然后进入 finally 清理。
+                self.manager.log.warn(f"{self.log_name} connection error: {ex}")
+            finally:
+                # 确保本次连接的所有子任务都已取消。
+                for task in connection_tasks:
+                    if not task.done():
+                        task.cancel()
+
+                # 等待取消完成，并收集异常，避免出现未处理的 Task 警告。
+                if connection_tasks:
+                    await asyncio.gather(
+                        *connection_tasks,
+                        return_exceptions=True,
+                    )
+
+                # 清除在线事件，后续进入队列的命令将被拒绝。
+                if self.connected_event:
+                    self.connected_event.clear()
+
+                # 向具体驱动发布离线状态，关闭 socket，并丢弃旧连接遗留命令。
+                self._publish_online(False)
+                await self._close_writer()
+                self._clear_command_queue()
+
+            # 正常断线或异常后，等待配置的时间再尝试下一次连接。
+            if self.running:
+                self.manager.log.info(
+                    f"{self.log_name} reconnecting in "
+                    f"{self.reconnect_delay} seconds"
+                )
+                await asyncio.sleep(self.reconnect_delay)
+
+    async def handshake(self):
+        """可选的协议登录或初始化钩子，由具体设备子类覆盖。"""
+
+    async def read_message(self):
+        """读取一行文本反馈；其他分帧方式应在子类中覆盖。"""
+
+        # readline() 等待换行符；远端关闭连接时会返回空字节串。
+        data = await self.reader.readline()
+        if not data:
+            return None
+
+        # 忽略无法解码的字节，并去掉行尾换行符及空白。
+        return data.decode("utf-8", "ignore").strip()
+
+    def encode_command(self, command):
+        """把命令转换为字节；二进制协议可以在子类中覆盖。"""
+
+        # 已经是 bytes 时直接返回，避免重复编码。
+        if isinstance(command, bytes):
+            return command
+
+        # 字符串及其他对象统一转成 UTF-8 文本字节。
+        return str(command).encode("utf-8")
+
+    def status_commands(self):
+        """返回 ``(发送前延时秒数, 命令)`` 列表；默认没有状态命令。"""
+        return []
+
+    @abstractmethod
+    def handle_feedback(self, response):
+        """解析并发布一条完整反馈；具体设备驱动必须实现。"""
+
+    async def _socket_listener(self):
+        """持续读取 socket，并把完整消息交给协议层处理。"""
+        while True:
+            # read_message() 允许子类自定义文本行、定长包或其他分帧方式。
+            response = await self.read_message()
+
+            # None 表示远端已关闭 socket，本任务返回后会触发重连。
+            if response is None:
+                return
+
+            # 空消息不处理；非空消息交给具体协议解析。
+            if response:
+                self.handle_feedback(response)
+
+    async def _socket_sender(self):
+        """从本设备的命令队列逐组取出并串行发送。"""
+        while True:
+            # 队列为空时异步等待，不会占用 CPU。
+            queue_item = await self.command_queue.get()
+            try:
+                commands = queue_item
+                latest_key = None
+
+                # latest 标记不直接携带命令。必要时先等待发送窗口，再取得
+                # 该 key 此刻最新的值，避免发送滑杆移动过程中已经过期的中间值。
+                if (
+                    isinstance(queue_item, tuple)
+                    and len(queue_item) == 2
+                    and queue_item[0] is self._latest_command_marker
+                ):
+                    latest_key = queue_item[1]
+                    last_sent = self._latest_sent_at.get(latest_key)
+                    if last_sent is not None and self.latest_command_interval:
+                        elapsed = asyncio.get_running_loop().time() - last_sent
+                        remaining = self.latest_command_interval - elapsed
+                        if remaining > 0:
+                            await asyncio.sleep(remaining)
+
+                    commands = self._latest_commands.pop(latest_key, None)
+
+                # 断线清理等情况可能已经移除待发值。
+                if not commands:
+                    if latest_key is not None:
+                        self._queued_latest_keys.discard(latest_key)
+                    continue
+
+                # 同一组命令按照指定延时和顺序发送，避免 socket 写入交叉。
+                await self._send_sequence_direct(commands)
+
+                if latest_key is not None:
+                    self._latest_sent_at[latest_key] = (
+                        asyncio.get_running_loop().time()
+                    )
+
+                    # 发送期间又收到新值时，把同一个标记放到队尾；这样其他
+                    # 按键或通道也有机会先发送，同时该 key 仍不会产生多个标记。
+                    if latest_key in self._latest_commands:
+                        try:
+                            self.command_queue.put_nowait(
+                                (self._latest_command_marker, latest_key)
+                            )
+                        except asyncio.QueueFull:
+                            self.manager.log.warn(
+                                f"{self.log_name} command queue is full"
+                            )
+                            self._latest_commands.pop(latest_key, None)
+                            self._queued_latest_keys.discard(latest_key)
+                    else:
+                        self._queued_latest_keys.discard(latest_key)
+            finally:
+                # 无论发送成功还是异常，都通知 Queue 当前项目已处理完。
+                self.command_queue.task_done()
+
+    async def _status_poll_loop(self):
+        """按照配置间隔周期性地把状态查询放入发送队列。"""
+        while True:
+            # 异步休眠不会阻塞其他设备的网络任务。
+            await asyncio.sleep(self.status_poll)
+
+            # 每次重新生成查询命令，允许子类根据当前状态动态决定内容。
+            commands = self.status_commands()
+            if commands:
+                # 走统一队列，确保轮询命令不会与控制命令同时写 socket。
+                await self.command_queue.put(commands)
+
+    async def _send_sequence_direct(self, commands):
+        """在当前协程中按顺序发送一组带延时的命令。
+
+        普通项目为 ``(delay, command)``。需要协议 ACK 的离散命令可以使用
+        ``(delay, command, True)``；子类同时覆盖 ``wait_for_command_ack``。
+        """
+        for item in commands:
+            if len(item) == 2:
+                delay, command = item
+                requires_ack = False
+            elif len(item) == 3:
+                delay, command, requires_ack = item
+            else:
+                raise ValueError("command item must contain 2 or 3 values")
+
+            if delay:
+                await asyncio.sleep(delay)
+            await self._send_direct(command)
+
+            # ACK 等待发生在同一设备的串行 sender 中，因此后一条离散命令
+            # 不会越过当前命令。监听协程仍可并行读取并唤醒子类的 ACK Event。
+            if requires_ack:
+                await self.wait_for_command_ack(command)
+
+    async def wait_for_command_ack(self, command):
+        """等待一条离散命令的协议 ACK；需要 ACK 的子类必须覆盖。"""
+        raise NotImplementedError(
+            f"{self.log_name} requires wait_for_command_ack()"
+        )
+
+    async def _send_direct(self, command):
+        """向当前已连接的 socket 写入一条命令。"""
+
+        # writer 不存在或正在关闭时，主动抛错并触发连接生命周期重建。
+        if not self.writer or self.writer.is_closing():
+            raise ConnectionError("socket writer is not ready")
+
+        # 现场排查时才记录每条原始命令；滑杆运行时逐条写日志会增加延迟。
+        if self.traffic_debug:
+            self.manager.log.info(f"{self.log_name} sending: {command}")
+
+        # 协议层负责把命令编码为 bytes；write() 只写入本地发送缓冲区。
+        self.writer.write(self.encode_command(command))
+
+        # drain() 等待缓冲区可继续写，形成异步流控。
+        await self.writer.drain()
+
+    async def enqueue(self, commands):
+        """把一组命令加入本设备发送队列。"""
+
+        # 离线时不缓存控制命令，避免重连后执行已经过期的操作。
+        if not self.connected_event or not self.connected_event.is_set():
+            self.manager.log.warn(f"{self.log_name} command dropped while offline")
+            return False
+
+        try:
+            # 使用非阻塞入队；队列满时立即报告，而不是无限等待。
+            self.command_queue.put_nowait(commands)
+            return True
+        except asyncio.QueueFull:
+            self.manager.log.warn(f"{self.log_name} command queue is full")
+            return False
+
+    async def enqueue_latest(self, key, commands):
+        """按 key 合并高频命令，队列尚未发送时只保留最新一组。"""
+        if not self.connected_event or not self.connected_event.is_set():
+            self.manager.log.warn(f"{self.log_name} command dropped while offline")
+            return False
+
+        # 无论 key 是否已在队列中，都先用最新命令覆盖旧值。
+        self._latest_commands[key] = commands
+
+        # 该 key 已有一个队列标记时，不再额外占用队列位置。
+        if key in self._queued_latest_keys:
+            return True
+
+        try:
+            self.command_queue.put_nowait((self._latest_command_marker, key))
+            self._queued_latest_keys.add(key)
+            return True
+        except asyncio.QueueFull:
+            self._latest_commands.pop(key, None)
+            self.manager.log.warn(f"{self.log_name} command queue is full")
+            return False
+
+    async def _close_writer(self):
+        """关闭当前 StreamWriter，并清空 reader/writer 引用。"""
+
+        # 先保存局部引用，再立即清空实例状态，防止其他逻辑继续使用旧连接。
+        writer = self.writer
+        self.reader = None
+        self.writer = None
+
+        # 从未建连成功时没有 writer，无需继续处理。
+        if not writer:
+            return
+
+        try:
+            # 请求关闭 socket，并等待底层资源释放完成。
+            writer.close()
+            await writer.wait_closed()
+        except Exception as ex:
+            # 关闭阶段的异常只记录，不阻止后续重连。
+            self.manager.log.warn(f"{self.log_name} socket close error: {ex}")
+
+    def _clear_command_queue(self):
+        """断线时清除队列，避免重连后发送旧命令。"""
+
+        # 初始化连接失败时队列可能尚不可用。
+        if not self.command_queue:
+            self._latest_commands.clear()
+            self._queued_latest_keys.clear()
+            return
+
+        # 持续非阻塞取出，直到 QueueEmpty 表示已经清空。
+        while True:
+            try:
+                self.command_queue.get_nowait()
+                self.command_queue.task_done()
+            except asyncio.QueueEmpty:
+                break
+
+        self._latest_commands.clear()
+        self._queued_latest_keys.clear()
+        self._latest_sent_at.clear()
+
+    def _publish_online(self, value):
+        """仅在在线状态实际变化时通知上层管理器。"""
+        value = bool(value)
+
+        # 状态没有变化时不重复触发 export.update。
+        if self.is_online == value:
+            return
+
+        # 保存新状态并输出设备级日志。
+        self.is_online = value
+        self.manager.log.info(
+            f"{self.log_name} online state changed to {value}"
+        )
+
+        # 具体管理器决定如何向 MUSE Script-as-Device 发布状态。
+        self.manager.online_state_changed(self)
+
+    def query_status(self):
+        """把当前设备的状态查询命令加入发送队列。"""
+
+        # 由具体协议生成查询命令。
+        commands = self.status_commands()
+        if not commands:
+            return False
+
+        # 通过管理器跨线程安全地送入共享 Event Loop。
+        return self.manager.schedule(self, commands)
+
+    def send_control(
+        self,
+        control_type,
+        key,
+        commands,
+        requires_ack=False,
+    ):
+        """按控件语义选择离散 FIFO 或连续 latest-wins 策略。
+
+        ``key`` 对连续控制必须稳定且唯一，例如 ``slider:2``。同一设备、
+        同一 key 在队列里最多只有一个标记，尚未发送的旧目标会被覆盖。
+        """
+        normalized_type = str(control_type).strip().lower()
+        commands = list(commands)
+
+        if normalized_type in self.CONTINUOUS_CONTROL_TYPES:
+            if requires_ack:
+                raise ValueError("continuous controls cannot wait for ACK")
+            if not key:
+                raise ValueError("continuous controls require a stable key")
+            return self.manager.schedule_latest(self, str(key), commands)
+
+        if normalized_type in self.DISCRETE_CONTROL_TYPES:
+            if requires_ack:
+                commands = [
+                    (delay, command, True)
+                    for delay, command in commands
+                ]
+            return self.manager.schedule(self, commands)
+
+        raise ValueError(f"unsupported control type: {control_type}")
+
+    def normalize_control_value(self, control, value):
+        """按 descriptor 的标准类型和范围校验/规范化一个输入值。"""
+        value_type = control.value_type
+        if value_type == "boolean":
+            if isinstance(value, bool):
+                normalized = value
+            elif isinstance(value, (int, float)) and value in (0, 1):
+                normalized = value == 1
+            elif isinstance(value, str):
+                normalized_value = value.strip().lower()
+                if normalized_value in ("true", "1", "on"):
+                    normalized = True
+                elif normalized_value in ("false", "0", "off"):
+                    normalized = False
+                else:
+                    raise ValueError(f"invalid boolean value: {value!r}")
+            else:
+                raise ValueError(f"invalid boolean value: {value!r}")
+        elif value_type == "integer":
+            normalized = int(value)
+        elif value_type == "float":
+            normalized = float(value)
+        else:
+            normalized = str(value)
+
+        if isinstance(normalized, (int, float)) and not isinstance(normalized, bool):
+            if control.minimum is not None:
+                normalized = max(control.minimum, normalized)
+            if control.maximum is not None:
+                normalized = min(control.maximum, normalized)
+
+        if control.enums and normalized not in control.enums:
+            raise ValueError(f"value {normalized!r} is not in {control.enums!r}")
+        return normalized
+
+    def send_descriptor_control(self, control, value):
+        """按标准 descriptor 选择策略，再交给协议子类编码实际设备命令。"""
+        if control is None or not control.control_type:
+            raise ValueError("control type could not be inferred from descriptor")
+        if control.control_type == "meter" or control.meter:
+            raise ValueError("meter controls are read-only realtime telemetry")
+        if control.access not in ("rw", "wo"):
+            raise ValueError(f"control is not writable: {control.path}")
+
+        normalized = self.normalize_control_value(control, value)
+        commands = self.encode_descriptor_control(control, normalized)
+        return self.send_control(
+            control.control_type,
+            control.key,
+            commands,
+            requires_ack=control.requires_ack,
+        )
+
+    def encode_descriptor_control(self, control, value):
+        """把 metadata 控件编码为协议命令；由具体设备子类实现。"""
+        raise NotImplementedError(
+            f"{self.log_name} does not implement {control.control_type!r} control"
+        )
+
+    def send_raw(self, data):
+        """不修改内容，直接把一条原始命令加入发送队列。"""
+        return self.manager.schedule(self, [(0, data)])
+
+
+class AsyncTcpDeviceManager(ABC):
+    """在一个后台线程和共享 asyncio Event Loop 中管理多台 TCP 设备。"""
+
+    # 这些字段属于所有持久 TCP 设备的通用连接配置。
+    DEFAULT_DEVICE_CONFIG = {
+        "username": "",
+        "password": "",
+        "reconnect_delay_seconds": 10,
+        "login_timeout_seconds": 10,
+        "status_poll_seconds": 30,
+        "query_on_connect": True,
+        "command_queue_size": 100,
+        "latest_command_interval_seconds": 0.04,
+        "traffic_debug": False,
+    }
+
+    @classmethod
+    def load_config(
+        cls,
+        config_path,
+        entries_key="devices",
+        max_devices=100,
+        id_prefix="device",
+    ):
+        """读取并标准化多台 TCP 设备的通用 JSON 配置。
+
+        具体驱动只需指定设备数组名称、最大数量和默认 ID 前缀。
+        协议通道、命令编号等设备特有信息不应放在这个通用加载器中。
+        """
+
+        # 读取项目目录中由具体驱动传入的 config.json。
+        with open(config_path, "r", encoding="utf-8") as config_file:
+            raw_config = json.load(config_file)
+
+        if not isinstance(raw_config, dict):
+            raise ValueError("config root must be an object")
+
+        file_defaults = raw_config.get("defaults", {})
+        entries = raw_config.get(entries_key)
+
+        if not isinstance(file_defaults, dict):
+            raise ValueError("config.defaults must be an object")
+        if not isinstance(entries, list):
+            raise ValueError(f"config.{entries_key} must be an array")
+        if len(entries) > max_devices:
+            raise ValueError(
+                f"At most {max_devices} {entries_key} are supported"
+            )
+
+        # 用户的 defaults 可以覆盖基类默认值，单台设备又可以继续覆盖。
+        defaults = dict(cls.DEFAULT_DEVICE_CONFIG)
+        defaults.update(file_defaults)
+
+        connection_stagger = float(
+            raw_config.get("connection_stagger_seconds", 0.05)
+        )
+        if connection_stagger < 0:
+            raise ValueError("connection_stagger_seconds cannot be negative")
+
+        normalized_entries = []
+        used_slots = set()
+        used_ids = set()
+
+        for position, entry in enumerate(entries):
+            if not isinstance(entry, dict):
+                raise ValueError(f"{entries_key}[{position}] must be an object")
+
+            config = dict(defaults)
+            config.update(entry)
+            config.setdefault("slot", position)
+            config.setdefault("enabled", True)
+
+            try:
+                slot = int(config["slot"])
+            except (TypeError, ValueError) as ex:
+                raise ValueError(
+                    f"{entries_key}[{position}].slot must be an integer"
+                ) from ex
+
+            config.setdefault("id", f"{id_prefix}-{slot + 1:03d}")
+            config.setdefault("name", config["id"])
+
+            device_id = str(config["id"]).strip()
+            enabled = config["enabled"]
+            traffic_debug = config["traffic_debug"]
+            query_on_connect = config["query_on_connect"]
+
+            if not isinstance(enabled, bool):
+                raise ValueError(
+                    f"{entries_key}[{position}].enabled must be a boolean"
+                )
+            if not isinstance(traffic_debug, bool):
+                raise ValueError(
+                    f"{entries_key}[{position}].traffic_debug must be a boolean"
+                )
+            if not isinstance(query_on_connect, bool):
+                raise ValueError(
+                    f"{entries_key}[{position}].query_on_connect must be a boolean"
+                )
+            if slot < 0 or slot >= max_devices:
+                raise ValueError(
+                    f"{entries_key}[{position}].slot must be 0-{max_devices - 1}"
+                )
+            if slot in used_slots:
+                raise ValueError(f"Duplicate {entries_key} slot: {slot}")
+            if not device_id:
+                raise ValueError(f"{entries_key}[{position}].id cannot be empty")
+            if device_id in used_ids:
+                raise ValueError(f"Duplicate {entries_key} id: {device_id}")
+
+            config["slot"] = slot
+            config["id"] = device_id
+            config["name"] = str(config["name"])
+            config["enabled"] = enabled
+
+            # disabled 条目只作为保留槽位，不必提供网络参数。
+            if enabled:
+                missing = [
+                    key for key in ("host", "port") if key not in config
+                ]
+                if missing:
+                    raise ValueError(
+                        f"{device_id} is missing: {', '.join(missing)}"
+                    )
+
+                try:
+                    config["host"] = str(config["host"]).strip()
+                    config["port"] = int(config["port"])
+                    config["username"] = str(config["username"])
+                    config["password"] = str(config["password"])
+                    config["reconnect_delay_seconds"] = float(
+                        config["reconnect_delay_seconds"]
+                    )
+                    config["login_timeout_seconds"] = float(
+                        config["login_timeout_seconds"]
+                    )
+                    config["status_poll_seconds"] = float(
+                        config["status_poll_seconds"]
+                    )
+                    config["command_queue_size"] = int(
+                        config["command_queue_size"]
+                    )
+                    config["latest_command_interval_seconds"] = float(
+                        config["latest_command_interval_seconds"]
+                    )
+                except (TypeError, ValueError) as ex:
+                    raise ValueError(
+                        f"{device_id} contains an invalid connection value"
+                    ) from ex
+
+                if not config["host"]:
+                    raise ValueError(f"{device_id} host cannot be empty")
+                if not 1 <= config["port"] <= 65535:
+                    raise ValueError(f"{device_id} has an invalid port")
+                if bool(config["username"]) != bool(config["password"]):
+                    raise ValueError(
+                        f"{device_id} needs both username and password"
+                    )
+                if config["reconnect_delay_seconds"] <= 0:
+                    raise ValueError(
+                        f"{device_id} reconnect delay must be positive"
+                    )
+                if config["login_timeout_seconds"] <= 0:
+                    raise ValueError(
+                        f"{device_id} login timeout must be positive"
+                    )
+                if config["status_poll_seconds"] < 0:
+                    raise ValueError(
+                        f"{device_id} status poll cannot be negative"
+                    )
+                if config["command_queue_size"] <= 0:
+                    raise ValueError(
+                        f"{device_id} command queue size must be positive"
+                    )
+                if config["latest_command_interval_seconds"] < 0:
+                    raise ValueError(
+                        f"{device_id} latest command interval cannot be negative"
+                    )
+
+            used_slots.add(slot)
+            used_ids.add(device_id)
+            normalized_entries.append(config)
+
+        return {
+            "connection_stagger_seconds": connection_stagger,
+            entries_key: normalized_entries,
+        }
+
+    def __init__(
+        self,
+        entries,
+        connection_stagger,
+        log,
+        thread_name="AsyncTcpDeviceLoop",
+        device_label="device",
+    ):
+        # entries 是已经由具体驱动验证和标准化的设备配置列表。
+        self.entries = entries
+
+        # 每台设备初次连接之间的错开时间。
+        self.connection_stagger = connection_stagger
+
+        # 日志对象由具体 MUSE 驱动注入，框架本身不导入 mojo。
+        self.log = log
+
+        # 后台线程名称和日志中显示的设备类型名称。
+        self.thread_name = thread_name
+        self.device_label = device_label
+
+        # 只为 enabled=True 的配置创建客户端，以 slot 为键快速查找。
+        self.clients = {
+            item["slot"]: self.create_client(item)
+            for item in entries
+            if item["enabled"]
+        }
+
+        # 最小启用 slot 作为兼容顶层路径所控制的主设备。
+        self.primary_slot = min(self.clients) if self.clients else None
+
+        # Event Loop 和线程在 start() 后创建。
+        self.loop = None
+        self.thread = None
+        self._tasks = []
+        self._stop_requested = False
+
+    @abstractmethod
+    def create_client(self, config):
+        """根据一条标准化配置创建具体客户端；子类必须实现。"""
+
+    def start(self):
+        """启动唯一的后台线程；重复调用不会重复启动。"""
+
+        # 没有启用设备时不浪费一个线程和 Event Loop。
+        if not self.clients:
+            self.log.warn(f"No enabled {self.device_label} devices are configured")
+            return
+
+        # 已经启动并仍然存活时直接返回，保证 start() 幂等。
+        if self.thread and self.thread.is_alive():
+            return
+
+        self._stop_requested = False
+        for client in self.clients.values():
+            client.running = True
+
+        # 一个管理器只创建一个 daemon 后台线程。
+        self.thread = threading.Thread(
+            target=self._thread_main,
+            name=self.thread_name,
+            daemon=True,
+        )
+
+        # 真正执行 _thread_main，并在那里创建共享 Event Loop。
+        self.thread.start()
+
+    def _thread_main(self):
+        """后台线程入口：创建 Event Loop，并为每台设备启动连接任务。"""
+
+        # 为当前后台线程创建独立的 asyncio Event Loop。
+        self.loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self.loop)
+
+        # 记录该 Event Loop 将管理多少台启用设备。
+        self.log.info(
+            f"{self.device_label} shared asyncio loop started for "
+            f"{len(self.clients)} devices"
+        )
+
+        try:
+            # 每台设备只创建一个长期运行的 connect_loop 主任务。
+            for position, client in enumerate(self.clients.values()):
+                if self._stop_requested:
+                    break
+                # 按设备顺序计算首次连接延时，削平大量连接的瞬时负载。
+                initial_delay = position * self.connection_stagger
+                self._tasks.append(
+                    self.loop.create_task(client.connect_loop(initial_delay))
+                )
+
+            # 让 Event Loop 永久运行，持续服务所有设备协程。
+            self.loop.run_forever()
+        finally:
+            # 热重载或显式 stop() 时回收连接任务、socket 和 Event Loop，避免
+            # 同一 Python 进程中留下旧的后台线程。
+            pending = asyncio.all_tasks(self.loop)
+            for task in pending:
+                task.cancel()
+            if pending:
+                self.loop.run_until_complete(
+                    asyncio.gather(*pending, return_exceptions=True)
+                )
+            self._tasks.clear()
+            self.loop.close()
+            asyncio.set_event_loop(None)
+            self.loop = None
+
+    def stop(self, timeout=5):
+        """停止后台连接循环并回收 Event Loop；可安全从 MUSE 主线程调用。"""
+
+        self._stop_requested = True
+        for client in self.clients.values():
+            client.running = False
+
+        loop = self.loop
+        if loop and loop.is_running():
+            loop.call_soon_threadsafe(loop.stop)
+
+        if self.thread and self.thread.is_alive() and \
+                threading.current_thread() is not self.thread:
+            self.thread.join(timeout)
+
+        if self.thread and not self.thread.is_alive():
+            self.thread = None
+
+    def get_client(self, slot):
+        """通过数组槽位取得启用的设备客户端。"""
+        try:
+            # Automator 路径传来的 slot 可能是字符串，统一转换为整数。
+            slot = int(slot)
+        except (TypeError, ValueError):
+            self.log.warn(f"Invalid {self.device_label} slot: {slot}")
+            return None
+
+        # 未配置或 disabled 的设备不会出现在 clients 中。
+        client = self.clients.get(slot)
+        if not client:
+            self.log.warn(
+                f"{self.device_label} slot {slot} is not configured and enabled"
+            )
+        return client
+
+    def get_primary_client(self):
+        """返回最低启用 slot 对应的兼容主设备。"""
+        if self.primary_slot is None:
+            self.log.warn(f"No primary {self.device_label} is available")
+            return None
+        return self.clients[self.primary_slot]
+
+    def schedule(self, client, commands):
+        """从 MUSE 主线程安全地把命令提交到后台 Event Loop。"""
+
+        # 脚本刚启动、Event Loop 尚未就绪时拒绝命令。
+        if not self.loop or not self.loop.is_running():
+            self.log.warn(
+                f"{client.log_name} command dropped before loop startup"
+            )
+            return False
+
+        # run_coroutine_threadsafe 是主线程跨到 asyncio 线程的安全桥梁。
+        future = asyncio.run_coroutine_threadsafe(
+            client.enqueue(commands),
+            self.loop,
+        )
+
+        # 异步入队完成后检查是否有未处理异常。
+        future.add_done_callback(self._log_schedule_result)
+        return True
+
+    def schedule_latest(self, client, key, commands):
+        """跨线程提交可合并命令，同一 key 只保留队列中的最新值。"""
+        if not self.loop or not self.loop.is_running():
+            self.log.warn(
+                f"{client.log_name} command dropped before loop startup"
+            )
+            return False
+
+        future = asyncio.run_coroutine_threadsafe(
+            client.enqueue_latest(key, commands),
+            self.loop,
+        )
+        future.add_done_callback(self._log_schedule_result)
+        return True
+
+    def _log_schedule_result(self, future):
+        """读取跨线程 Future 的结果并记录调度异常。"""
+        try:
+            future.result()
+        except Exception as ex:
+            self.log.warn(f"{self.device_label} command scheduling error: {ex}")
+
+    def online_state_changed(self, client):
+        """在线状态发布钩子，由具体 MUSE 管理器按需要覆盖。"""
+
+    def query_all(self):
+        """向所有启用设备分别提交状态查询。"""
+        for client in self.clients.values():
+            client.query_status()