ksaa 2025.6.8.0__py3-none-any.whl → 2025.6.28.0__py3-none-any.whl

kotonebot/client/host/protocol.py

@@ -1,14 +1,15 @@
 import time
 import socket
 from abc import ABC, abstractmethod
-from typing_extensions import ParamSpec, Concatenate
-from typing import Callable, TypeVar, Generic, Protocol, runtime_checkable, Type, Any
+from typing import Callable, TypeVar, Protocol, Any, Generic
+from dataclasses import dataclass
 
 from adbutils import adb, AdbTimeout, AdbError
 from adbutils._device import AdbDevice
 
 from kotonebot import logging
-from kotonebot.client import Device, create_device, DeviceImpl
+from kotonebot.client import Device, DeviceImpl
+
 from kotonebot.util import Countdown, Interval
 
 logger = logging.getLogger(__name__)
@@ -17,6 +18,28 @@ _T = TypeVar("_T")
 def copy_type(_: _T) -> Callable[[Any], _T]:
     return lambda x: x
 
+# --- 定义专用的 HostConfig 数据类 ---
+@dataclass
+class AdbHostConfig:
+    """由外部为基于 ADB 的主机提供的配置。"""
+    timeout: float = 180
+
+@dataclass
+class WindowsHostConfig:
+    """由外部为 Windows 实现提供配置。"""
+    window_title: str
+    ahk_exe_path: str
+
+@dataclass
+class RemoteWindowsHostConfig:
+    """由外部为远程 Windows 实现提供配置。"""
+    windows_host_config: WindowsHostConfig
+    host: str
+    port: int
+
+# --- 使用泛型改造 Instance 协议 ---
+T_HostConfig = TypeVar("T_HostConfig")
+
 def tcp_ping(host: str, port: int, timeout: float = 1.0) -> bool:
     """
     通过 TCP ping 检查主机和端口是否可达。
@@ -36,7 +59,11 @@ def tcp_ping(host: str, port: int, timeout: float = 1.0) -> bool:
         return False
 
 
-class Instance(ABC):
+class Instance(Generic[T_HostConfig], ABC):
+    """
+    代表一个可运行环境的实例（如一个模拟器）。
+    使用泛型来约束 create_device 方法的配置参数类型。
+    """
     def __init__(self,
         id: str,
         name: str,
@@ -68,7 +95,7 @@ class Instance(ABC):
         启动模拟器实例。
         """
         raise NotImplementedError()
-    
+
     @abstractmethod
     def stop(self):
         """
@@ -80,21 +107,16 @@ class Instance(ABC):
     def running(self) -> bool:
         raise NotImplementedError()
 
-    def create_device(self, impl: DeviceImpl, *, timeout: float = 180) -> Device:
+    @abstractmethod
+    def create_device(self, impl: DeviceImpl, host_config: T_HostConfig) -> Device:
         """
-        创建 Device 实例，可用于控制模拟器系统。
-        
-        :return: Device 实例
+        根据实现名称和类型化的主机配置创建设备。
+
+        :param impl: 设备实现的名称。
+        :param host_config: 一个类型化的数据对象，包含创建所需的所有外部配置。
+        :return: 配置好的 Device 实例。
         """
-        if self.adb_port is None:
-            raise ValueError("ADB port is not set and is required.")
-        return create_device(
-            addr=f'{self.adb_ip}:{self.adb_port}',
-            impl=impl,
-            device_serial=self.adb_name,
-            connect=True,
-            timeout=timeout
-        )
+        raise NotImplementedError()
 
     def wait_available(self, timeout: float = 180):
         logger.info('Starting to wait for emulator %s(127.0.0.1:%d) to be available...', self.name, self.adb_port)
@@ -173,7 +195,8 @@ class Instance(ABC):
     def __repr__(self) -> str:
         return f'{self.__class__.__name__}(name="{self.name}", id="{self.id}", adb="{self.adb_ip}:{self.adb_port}"({self.adb_name}))'
 
-class HostProtocol(Protocol):
+Recipe = TypeVar('Recipe', bound=str)
+class HostProtocol(Generic[Recipe], Protocol):
     @staticmethod
     def installed() -> bool: ...
     
@@ -183,6 +206,8 @@ class HostProtocol(Protocol):
     @staticmethod
     def query(*, id: str) -> Instance | None: ...
 
+    @staticmethod
+    def recipes() -> 'list[Recipe]': ...
 
 if __name__ == '__main__':
     pass

kotonebot/client/host/windows_common.py

@@ -0,0 +1,55 @@
+from abc import ABC
+from typing import Literal
+from typing_extensions import assert_never
+
+from kotonebot import logging
+from kotonebot.client.device import WindowsDevice
+from .protocol import Device, WindowsHostConfig, RemoteWindowsHostConfig
+
+logger = logging.getLogger(__name__)
+WindowsRecipes = Literal['windows', 'remote_windows']
+
+# Windows 相关的配置类型联合
+WindowsHostConfigs = WindowsHostConfig | RemoteWindowsHostConfig
+
+class CommonWindowsCreateDeviceMixin(ABC):
+    """
+    通用 Windows 创建设备的 Mixin。
+    该 Mixin 定义了创建 Windows 设备的通用接口。
+    """
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+    
+    def create_device(self, recipe: WindowsRecipes, config: WindowsHostConfigs) -> Device:
+        """
+        创建 Windows 设备。
+        """
+        match recipe:
+            case 'windows':
+                if not isinstance(config, WindowsHostConfig):
+                    raise ValueError(f"Expected WindowsHostConfig for 'windows' recipe, got {type(config)}")
+                from kotonebot.client.implements.windows import WindowsImpl
+                d = WindowsDevice()
+                impl = WindowsImpl(
+                    device=d,
+                    window_title=config.window_title,
+                    ahk_exe_path=config.ahk_exe_path
+                )
+                d._screenshot = impl
+                d._touch = impl
+                return d
+            case 'remote_windows':
+                if not isinstance(config, RemoteWindowsHostConfig):
+                    raise ValueError(f"Expected RemoteWindowsHostConfig for 'remote_windows' recipe, got {type(config)}")
+                from kotonebot.client.implements.remote_windows import RemoteWindowsImpl
+                d = WindowsDevice()
+                impl = RemoteWindowsImpl(
+                    device=d,
+                    host=config.host,
+                    port=config.port
+                )
+                d._screenshot = impl
+                d._touch = impl
+                return d
+            case _:
+                assert_never(f'Unsupported Windows recipe: {recipe}')

kotonebot/client/implements/__init__.py

@@ -0,0 +1,7 @@
+# 导入所有内置实现，以触发它们的 @register_impl 装饰器
+from . import adb  # noqa: F401
+from . import adb_raw  # noqa: F401
+from . import remote_windows  # noqa: F401
+from . import uiautomator2  # noqa: F401
+from . import windows  # noqa: F401
+from . import nemu_ipc  # noqa: F401

kotonebot/client/implements/adb.py

@@ -5,16 +5,27 @@ from typing_extensions import override
 import cv2
 import numpy as np
 from cv2.typing import MatLike
+from adbutils._device import AdbDevice as AdbUtilsDevice
 
-from ..device import Device
-from ..protocol import Commandable, Touchable, Screenshotable
+from ..device import AndroidDevice
+from ..protocol import AndroidCommandable, Touchable, Screenshotable
+from ..registration import ImplConfig
+from dataclasses import dataclass
 
 logger = logging.getLogger(__name__)
 
-class AdbImpl(Commandable, Touchable, Screenshotable):
-    def __init__(self, device: Device):
-        self.device = device
-        self.adb = device.adb
+# 定义配置模型
+@dataclass
+class AdbImplConfig(ImplConfig):
+    addr: str
+    connect: bool = True
+    disconnect: bool = True
+    device_serial: str | None = None
+    timeout: float = 180
+
+class AdbImpl(AndroidCommandable, Touchable, Screenshotable):
+    def __init__(self, adb_connection: AdbUtilsDevice):
+        self.adb = adb_connection
 
     @override
     def launch_app(self, package_name: str) -> None:
@@ -36,6 +47,10 @@ class AdbImpl(Commandable, Touchable, Screenshotable):
         package = activity.split('/')[0]
         return package
 
+    def adb_shell(self, cmd: str) -> str:
+        """执行 ADB shell 命令"""
+        return cast(str, self.adb.shell(cmd))
+
     @override
     def detect_orientation(self):
         # 判断方向：https://stackoverflow.com/questions/10040624/check-if-device-is-landscape-via-adb
@@ -50,7 +65,9 @@ class AdbImpl(Commandable, Touchable, Screenshotable):
     def screen_size(self) -> tuple[int, int]:
         ret = cast(str, self.adb.shell("wm size")).strip('Physical size: ')
         spiltted = tuple(map(int, ret.split("x")))
-        landscape = self.device.orientation == 'landscape'
+        # 检测当前方向
+        orientation = self.detect_orientation()
+        landscape = orientation == 'landscape'
         spiltted = tuple(sorted(spiltted, reverse=landscape))
         if len(spiltted) != 2:
             raise ValueError(f"Invalid screen size: {ret}")

kotonebot/client/implements/adb_raw.py

@@ -12,7 +12,7 @@ from cv2.typing import MatLike
 from adbutils._utils import adb_path
 
 from .adb import AdbImpl
-from ..device import Device
+from adbutils._device import AdbDevice as AdbUtilsDevice
 from kotonebot import logging
 
 logger = logging.getLogger(__name__)
@@ -27,8 +27,8 @@ done
 """
 
 class AdbRawImpl(AdbImpl):
-    def __init__(self, device: Device):
-        super().__init__(device)
+    def __init__(self, adb_connection: AdbUtilsDevice):
+        super().__init__(adb_connection)
         self.__worker: Thread | None = None
         self.__process: subprocess.Popen | None = None
         self.__data: MatLike | None = None

kotonebot/client/implements/nemu_ipc/__init__.py

@@ -0,0 +1,8 @@
+from .external_renderer_ipc import ExternalRendererIpc
+from .nemu_ipc import NemuIpcImpl, NemuIpcImplConfig
+
+__all__ = [
+    "ExternalRendererIpc",
+    "NemuIpcImpl",
+    "NemuIpcImplConfig",
+]

kotonebot/client/implements/nemu_ipc/external_renderer_ipc.py

@@ -0,0 +1,280 @@
+import ctypes
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+
+class NemuIpcIncompatible(RuntimeError):
+    """MuMu12 IPC 环境不兼容或 DLL 加载失败"""
+
+
+class ExternalRendererIpc:
+    r"""对 `external_renderer_ipc.dll` 的轻量封装。
+
+    该类仅处理 DLL 加载与原型声明，并提供带有类型提示的薄包装方法，
+    方便在其他模块中调用且保持类型安全。
+    传入参数为 MuMu 根目录（如 F:\Apps\Netease\MuMuPlayer-12.0）。
+    """
+
+    def __init__(self, mumu_root_folder: str):
+        if os.name != "nt":
+            raise NemuIpcIncompatible("ExternalRendererIpc only supports Windows.")
+
+        self.lib = self.__load_dll(mumu_root_folder)
+        self.raise_on_error: bool = True
+        """是否在调用 DLL 函数失败时抛出异常。"""
+        self.__declare_prototypes()
+
+    def connect(self, nemu_folder: str, instance_id: int) -> int:
+        """
+        建立连接。
+
+        API 原型：
+        `int nemu_connect(const wchar_t* path, int index)`
+
+        :param nemu_folder: 模拟器安装路径。
+        :param instance_id: 模拟器实例 ID。
+        :return: 成功返回连接 ID，失败返回 0。
+        """
+        return self.lib.nemu_connect(nemu_folder, instance_id)
+
+    def disconnect(self, connect_id: int) -> None:
+        """
+        断开连接。
+
+        API 原型：
+        `void nemu_disconnect(int handle)`
+
+        :param connect_id: 连接 ID。
+        :return: 无返回值。
+        """
+        return self.lib.nemu_disconnect(connect_id)
+
+    def get_display_id(self, connect_id: int, pkg: str, app_index: int) -> int:
+        """
+        获取指定包的 display id。
+
+        API 原型：
+        `int nemu_get_display_id(int handle, const char* pkg, int appIndex)`
+
+        :param connect_id: 连接 ID。
+        :param pkg: 包名。
+        :param app_index: 多开应用索引。
+        :return: <0 表示失败，>=0 表示有效 display id。
+        """
+        return self.lib.nemu_get_display_id(connect_id, pkg.encode('utf-8'), app_index)
+
+    def capture_display(
+        self,
+        connect_id: int,
+        display_id: int,
+        buf_len: int,
+        width_ptr: ctypes.c_void_p,
+        height_ptr: ctypes.c_void_p,
+        buffer_ptr: ctypes.c_void_p,
+    ) -> int:
+        """
+        截取指定显示屏内容。
+
+        API 原型：
+        `int nemu_capture_display(int handle, unsigned int displayid, int buffer_size, int *width, int *height, unsigned char* pixels)`
+
+        :param connect_id: 连接 ID。
+        :param display_id: 显示屏 ID。
+        :param buf_len: 缓冲区长度（字节）。
+        :param width_ptr: 用于接收宽度的指针（ctypes.c_void_p/int 指针）。
+        :param height_ptr: 用于接收高度的指针（ctypes.c_void_p/int 指针）。
+        :param buffer_ptr: 用于接收像素数据的指针（ctypes.c_void_p/unsigned char* 指针）。
+        :return: 0 表示成功，>0 表示失败。
+        """
+        return self.lib.nemu_capture_display(
+            connect_id,
+            display_id,
+            buf_len,
+            width_ptr,
+            height_ptr,
+            buffer_ptr,
+        )
+
+    def input_text(self, connect_id: int, text: str) -> int:
+        """
+        输入文本。
+
+        API 原型：
+        `int nemu_input_text(int handle, int size, const char* buf)`
+
+        :param connect_id: 连接 ID。
+        :param text: 输入文本（utf-8）。
+        :return: 0 表示成功，>0 表示失败。
+        """
+        buf = text.encode('utf-8')
+        return self.lib.nemu_input_text(connect_id, len(buf), buf)
+
+    def input_touch_down(self, connect_id: int, display_id: int, x: int, y: int) -> int:
+        """
+        发送触摸按下事件。
+
+        API 原型：
+        `int nemu_input_event_touch_down(int handle, int displayid, int x_point, int y_point)`
+
+        :param connect_id: 连接 ID。
+        :param display_id: 显示屏 ID。
+        :param x: 触摸点 X 坐标。
+        :param y: 触摸点 Y 坐标。
+        :return: 0 表示成功，>0 表示失败。
+        """
+        return self.lib.nemu_input_event_touch_down(connect_id, display_id, x, y)
+
+    def input_touch_up(self, connect_id: int, display_id: int) -> int:
+        """
+        发送触摸抬起事件。
+
+        API 原型：
+        `int nemu_input_event_touch_up(int handle, int displayid)`
+
+        :param connect_id: 连接 ID。
+        :param display_id: 显示屏 ID。
+        :return: 0 表示成功，>0 表示失败。
+        """
+        return self.lib.nemu_input_event_touch_up(connect_id, display_id)
+
+    def input_key_down(self, connect_id: int, display_id: int, key_code: int) -> int:
+        """
+        发送按键按下事件。
+
+        API 原型：
+        `int nemu_input_event_key_down(int handle, int displayid, int key_code)`
+
+        :param connect_id: 连接 ID。
+        :param display_id: 显示屏 ID。
+        :param key_code: 按键码。
+        :return: 0 表示成功，>0 表示失败。
+        """
+        return self.lib.nemu_input_event_key_down(connect_id, display_id, key_code)
+
+    def input_key_up(self, connect_id: int, display_id: int, key_code: int) -> int:
+        """
+        发送按键抬起事件。
+
+        API 原型：
+        `int nemu_input_event_key_up(int handle, int displayid, int key_code)`
+
+        :param connect_id: 连接 ID。
+        :param display_id: 显示屏 ID。
+        :param key_code: 按键码。
+        :return: 0 表示成功，>0 表示失败。
+        """
+        return self.lib.nemu_input_event_key_up(connect_id, display_id, key_code)
+
+    def input_finger_touch_down(self, connect_id: int, display_id: int, finger_id: int, x: int, y: int) -> int:
+        """
+        多指触摸按下。
+
+        API 原型：
+        `int nemu_input_event_finger_touch_down(int handle, int displayid, int finger_id, int x_point, int y_point)`
+
+        :param connect_id: 连接 ID。
+        :param display_id: 显示屏 ID。
+        :param finger_id: 手指编号（1-10）。
+        :param x: 触摸点 X 坐标。
+        :param y: 触摸点 Y 坐标。
+        :return: 0 表示成功，>0 表示失败。
+        """
+        return self.lib.nemu_input_event_finger_touch_down(connect_id, display_id, finger_id, x, y)
+
+    def input_finger_touch_up(self, connect_id: int, display_id: int, finger_id: int) -> int:
+        """
+        多指触摸抬起。
+
+        API 原型：
+        `int nemu_input_event_finger_touch_up(int handle, int displayid, int slot_id)`
+
+        :param connect_id: 连接 ID。
+        :param display_id: 显示屏 ID。
+        :param finger_id: 手指编号（1-10）。
+        :return: 0 表示成功，>0 表示失败。
+        """
+        return self.lib.nemu_input_event_finger_touch_up(connect_id, display_id, finger_id)
+
+    # ------------------------------------------------------------------
+    # 内部工具
+    # ------------------------------------------------------------------
+
+    def __load_dll(self, mumu_root_folder: str) -> ctypes.CDLL:
+        """尝试多条路径加载 DLL。传入为 MuMu 根目录。"""
+        candidate_paths = [
+            os.path.join(mumu_root_folder, "shell", "sdk", "external_renderer_ipc.dll"),
+            os.path.join(
+                mumu_root_folder,
+                "shell",
+                "nx_device",
+                "12.0",
+                "sdk",
+                "external_renderer_ipc.dll",
+            ),
+        ]
+        for p in candidate_paths:
+            if not os.path.exists(p):
+                continue
+            try:
+                return ctypes.CDLL(p)
+            except OSError as e:  # pragma: no cover
+                logger.warning("Failed to load DLL (%s): %s", p, e)
+        raise NemuIpcIncompatible("external_renderer_ipc.dll not found or failed to load.")
+
+    def __declare_prototypes(self) -> None:
+        """声明 DLL 函数原型，确保 ctypes 类型安全。"""
+        # 连接 / 断开
+        self.lib.nemu_connect.argtypes = [ctypes.c_wchar_p, ctypes.c_int]
+        self.lib.nemu_connect.restype = ctypes.c_int
+
+        self.lib.nemu_disconnect.argtypes = [ctypes.c_int]
+        self.lib.nemu_disconnect.restype = None
+
+        # 获取 display id
+        self.lib.nemu_get_display_id.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int]
+        self.lib.nemu_get_display_id.restype = ctypes.c_int
+
+        # 截图
+        self.lib.nemu_capture_display.argtypes = [
+            ctypes.c_int,
+            ctypes.c_uint,
+            ctypes.c_int,
+            ctypes.c_void_p,
+            ctypes.c_void_p,
+            ctypes.c_void_p,
+        ]
+        self.lib.nemu_capture_display.restype = ctypes.c_int
+
+        # 输入文本
+        self.lib.nemu_input_text.argtypes = [ctypes.c_int, ctypes.c_int, ctypes.c_char_p]
+        self.lib.nemu_input_text.restype = ctypes.c_int
+
+        # 触摸
+        self.lib.nemu_input_event_touch_down.argtypes = [
+            ctypes.c_int,
+            ctypes.c_int,
+            ctypes.c_int,
+            ctypes.c_int,
+        ]
+        self.lib.nemu_input_event_touch_down.restype = ctypes.c_int
+
+        self.lib.nemu_input_event_touch_up.argtypes = [ctypes.c_int, ctypes.c_int]
+        self.lib.nemu_input_event_touch_up.restype = ctypes.c_int
+
+        # 按键
+        self.lib.nemu_input_event_key_down.argtypes = [ctypes.c_int, ctypes.c_int, ctypes.c_int]
+        self.lib.nemu_input_event_key_down.restype = ctypes.c_int
+
+        self.lib.nemu_input_event_key_up.argtypes = [ctypes.c_int, ctypes.c_int, ctypes.c_int]
+        self.lib.nemu_input_event_key_up.restype = ctypes.c_int
+
+        # 多指触摸
+        self.lib.nemu_input_event_finger_touch_down.argtypes = [ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int]
+        self.lib.nemu_input_event_finger_touch_down.restype = ctypes.c_int
+
+        self.lib.nemu_input_event_finger_touch_up.argtypes = [ctypes.c_int, ctypes.c_int, ctypes.c_int]
+        self.lib.nemu_input_event_finger_touch_up.restype = ctypes.c_int
+
+        logger.debug("DLL function prototypes declared")