更跟手，反而更省 CPU：把监控面板空闲占用从 3% 压到 0.4%

轮询（Poll）：  线程 ──每 66ms──▶ 问一次「有按键吗？」──▶ 没有，睡 66ms
                       │
                       └─ 99.9% 的唤醒都扑空，但设备只在变化时才有数据

阻塞（Block）： 线程 ──hid_read_timeout()──▶ 睡在 USB 内核传输里
                       │
                       └─ 设备一有变化，内核立刻唤醒它：零轮询、零等待
# generated by hugo AI

class Device(Transport.Device):
    def read(self, length: int) -> bytes | None:
        """Performs a read of a HID In report from an open HID device."""
        with self.mutex:                          # 与 write 共用同一把锁
            return self.hidapi.read(self.device_handle, length)

    def write(self, payload: bytes) -> int:
        """Writes a HID Out report to an open HID device."""
        with self.mutex:                          # 同一把锁
            return self.hidapi.write(self.device_handle, payload)
# generated by hugo AI

import ctypes
import threading
from typing import TYPE_CHECKING, Callable

if TYPE_CHECKING:
    from StreamDeck.Devices.StreamDeck import StreamDeck

READER_TIMEOUT_MS = 250  # 仅用于退出时能醒来，不是采样周期


class BlockingReader:
    """Reads HID reports with hid_read_timeout, bypassing the SDK's mutexes.

    The SDK calls hid_read while holding Device.mutex and Library.mutex, so a
    blocking read there would stall image writes and deadlock shutdown. We read
    the raw handle directly instead: the device only raises a report on a key
    change, so the thread sleeps in the kernel while idle (~0 CPU).
    """

    def __init__(
        self, deck: "StreamDeck", on_key: Callable, log: Callable[[str], None]
    ) -> None:
        self._deck = deck
        self._on_key = on_key
        self._log = log
        self._stop = threading.Event()
        self._thread: threading.Thread | None = None

    def start(self) -> bool:
        """Takes over the reader; returns False if the transport can't do it."""
        device = self._deck.device
        library = getattr(device, "hidapi", None)
        handle = getattr(device, "device_handle", None)
        hidapi = getattr(library, "hidapi", None)
        if handle is None or hidapi is None or not hasattr(hidapi, "hid_read_timeout"):
            return False

        hidapi.hid_read_timeout.argtypes = [
            ctypes.c_void_p,
            ctypes.POINTER(ctypes.c_char),
            ctypes.c_size_t,
            ctypes.c_int,
        ]
        hidapi.hid_read_timeout.restype = ctypes.c_int
        self._library, self._handle = hidapi, handle

        # Stop the SDK poller only AFTER we know we can replace it, so the
        # polling fallback still works if this transport is unsupported.
        self._deck._setup_reader(None)
        self._thread = threading.Thread(target=self._loop, name="sd-reader", daemon=True)
        self._thread.start()
        return True

    def _loop(self) -> None:
        """Block on the handle until a key changes, then dispatch it."""
        key_count = self._deck.key_count()
        buffer = ctypes.create_string_buffer(1 + key_count)
        # Seed from the state the SDK poller last saw, so a key held across the
        # hand-over is still tracked and its release is delivered.
        last = list(self._deck.key_states()[:key_count])

        while not self._stop.is_set():
            result = self._library.hid_read_timeout(
                self._handle, buffer, len(buffer), READER_TIMEOUT_MS
            )
            if self._stop.is_set() or result < 0:
                break
            if result == 0:
                continue
            raw = buffer.raw[:result]
            for key in range(min(key_count, len(raw) - 1)):
                pressed = bool(raw[1 + key])
                if pressed == last[key]:
                    continue
                last[key] = pressed
                self._deck.last_key_states[key] = pressed  # keep SDK-side checks consistent
                self._on_key(self._deck, key, pressed)

    def stop(self) -> None:
        """Wake the blocking read with a timeout and join the thread."""
        self._stop.set()
        if self._thread is not None:
            self._thread.join(timeout=READER_TIMEOUT_MS / 1000.0 + 1.0)
# generated by hugo AI