ksaa 2025.5.16.1__py3-none-any.whl → 2025.5.23.1__py3-none-any.whl

kotonebot/client/device.py

@@ -8,10 +8,10 @@ from adbutils import adb
 from cv2.typing import MatLike
 from adbutils._device import AdbDevice as AdbUtilsDevice
 
+from ..backend.debug import result
 from kotonebot.backend.core import HintBox
-from kotonebot.util import Rect, Point, is_rect, is_point
+from kotonebot.primitives import Rect, Point, is_point
 from .protocol import ClickableObjectProtocol, Commandable, Touchable, Screenshotable
-from ..backend.debug import result
 
 logger = logging.getLogger(__name__)
 
@@ -119,14 +119,7 @@ class Device:
         点击屏幕上的某个点
         """
         ...
-
-    @overload
-    def click(self, hint_box: HintBox) -> None:
-        """
-        点击屏幕上的某个矩形区域
-        """
-        ...
-
+    
     @overload
     def click(self, rect: Rect) -> None:
         """
@@ -136,7 +129,6 @@ class Device:
 
     @overload
     def click(self, clickable: ClickableObjectProtocol) -> None:
-
         """
         点击屏幕上的某个可点击对象
         """
@@ -147,9 +139,7 @@ class Device:
         arg2 = args[1] if len(args) > 1 else None
         if arg1 is None:
             self.__click_last()
-        elif isinstance(arg1, HintBox):
-            self.__click_hint_box(arg1)
-        elif is_rect(arg1):
+        elif isinstance(arg1, Rect):
             self.__click_rect(arg1)
         elif is_point(arg1):
             self.__click_point_tuple(arg1)
@@ -167,8 +157,8 @@ class Device:
 
     def __click_rect(self, rect: Rect) -> None:
         # 从矩形中心的 60% 内部随机选择一点
-        x = rect[0] + rect[2] // 2 + np.random.randint(-int(rect[2] * 0.3), int(rect[2] * 0.3))
-        y = rect[1] + rect[3] // 2 + np.random.randint(-int(rect[3] * 0.3), int(rect[3] * 0.3))
+        x = rect.x1 + rect.w // 2 + np.random.randint(-int(rect.w * 0.3), int(rect.w * 0.3))
+        y = rect.y1 + rect.h // 2 + np.random.randint(-int(rect.h * 0.3), int(rect.h * 0.3))
         x = int(x)
         y = int(y)
         self.click(x, y)
@@ -196,9 +186,6 @@ class Device:
     def __click_clickable(self, clickable: ClickableObjectProtocol) -> None:
         self.click(clickable.rect)
 
-    def __click_hint_box(self, hint_box: HintBox) -> None:
-        self.click(hint_box.rect)
-
     def click_center(self) -> None:
         """
         点击屏幕中心。
@@ -234,7 +221,7 @@ class Device:
     def double_click(self, *args, **kwargs) -> None:
         from kotonebot import sleep
         arg0 = args[0]
-        if is_rect(arg0) or isinstance(arg0, ClickableObjectProtocol):
+        if isinstance(arg0, Rect) or isinstance(arg0, ClickableObjectProtocol):
             rect = arg0
             interval = kwargs.get('interval', 0.4)
             self.click(rect)

kotonebot/client/factory.py

@@ -1,4 +1,4 @@
-from enum import Enum
+from time import sleep
 from typing import Literal
 
 from .implements.adb import AdbImpl
@@ -15,12 +15,38 @@ DeviceImpl = Literal['adb', 'adb_raw', 'uiautomator2', 'windows', 'remote_window
 def create_device(
     addr: str,
     impl: DeviceImpl,
+    *,
+    connect: bool = True,
+    disconnect: bool = True,
+    device_serial: str | None = None,
+    timeout: float = 180,
 ) -> Device:
+    """
+    根据指定的实现方式创建 Device 实例。
+    
+    :param addr: 设备地址，如 `127.0.0.1:5555`。
+        仅当通过无线方式连接 Android 设备，或者使用 `remote_windows` 时有效。
+    :param impl: 实现方式。
+    :param connect: 是否在创建时连接设备，默认为 True。
+        仅对 ADB-based 的实现方式有效。
+    :param disconnect: 是否在连接前先断开设备，默认为 True。
+        仅对 ADB-based 的实现方式有效。
+    :param device_serial: 设备序列号，默认为 None。
+        若为非 None，则当存在多个设备时通过该值判断是否为目标设备。
+        仅对 ADB-based 的实现方式有效。
+    :param timeout: 连接超时时间，默认为 180 秒。
+        仅对 ADB-based 的实现方式有效。
+    """
     if impl in ['adb', 'adb_raw', 'uiautomator2']:
-        result = adb.connect(addr)
-        if 'cannot connect to' in result:
-            raise ValueError(result)
-        d = [d for d in adb.device_list() if d.serial == addr]
+        if disconnect:
+            adb.disconnect(addr)
+        if connect:
+            result = adb.connect(addr)
+            if 'cannot connect to' in result:
+                raise ValueError(result)
+        serial = device_serial or addr
+        adb.wait_for(serial, timeout=timeout)
+        d = [d for d in adb.device_list() if d.serial == serial]
         if len(d) == 0:
             raise ValueError(f"Device {addr} not found")
         d = d[0]
@@ -55,4 +81,6 @@ def create_device(
         remote_impl = RemoteWindowsImpl(device, host, port)
         device._touch = remote_impl
         device._screenshot = remote_impl
+    else:
+        raise ValueError(f"Unsupported device implementation: {impl}")
     return device

kotonebot/client/host/__init__.py

@@ -1,4 +1,11 @@
 from .protocol import HostProtocol, Instance
 from .custom import CustomInstance, create as create_custom
+from .mumu12_host import Mumu12Host, Mumu12Instance
+from .leidian_host import LeidianHost, LeidianInstance
 
-__all__ = ['HostProtocol', 'Instance', 'CustomInstance', 'create_custom']
+__all__ = [
+    'HostProtocol', 'Instance',
+    'CustomInstance', 'create_custom',
+    'Mumu12Host', 'Mumu12Instance',
+    'LeidianHost', 'LeidianInstance'
+]

kotonebot/client/host/custom.py

@@ -6,6 +6,7 @@ from typing import Optional, ParamSpec, TypeVar, TypeGuard
 from typing_extensions import override
 
 from kotonebot import logging
+from kotonebot.client.device import Device
 
 logger = logging.getLogger(__name__)
 
@@ -55,6 +56,10 @@ class CustomInstance(Instance):
             else:
                 return False
 
+    @override
+    def refresh(self):
+        pass
+
     def __repr__(self) -> str:
         return f'CustomInstance(#{self.id}# at "{self.exe_path}" with {self.adb_ip}:{self.adb_port})'
 
@@ -63,8 +68,8 @@ def _type_check(ins: Instance) -> CustomInstance:
         raise ValueError(f'Instance {ins} is not a CustomInstance')
     return ins
 
-def create(exe_path: str, adb_ip: str, adb_port: int, adb_emulator_name: str, emulator_args: str = "") -> CustomInstance:
-    return CustomInstance(exe_path, emulator_args=emulator_args, id='custom', name='Custom', adb_ip=adb_ip, adb_port=adb_port, adb_emulator_name=adb_emulator_name)
+def create(exe_path: str, adb_ip: str, adb_port: int, adb_name: str, emulator_args: str = "") -> CustomInstance:
+    return CustomInstance(exe_path, emulator_args=emulator_args, id='custom', name='Custom', adb_ip=adb_ip, adb_port=adb_port, adb_name=adb_name)
 
 
 if __name__ == '__main__':

kotonebot/client/host/leidian_host.py

@@ -0,0 +1,200 @@
+import os
+import subprocess
+from functools import lru_cache
+from typing_extensions import override
+
+from kotonebot import logging
+from kotonebot.client import DeviceImpl, create_device
+from kotonebot.client.device import Device
+from kotonebot.util import Countdown, Interval
+from .protocol import HostProtocol, Instance, copy_type
+
+logger = logging.getLogger(__name__)
+
+if os.name == 'nt':
+    from ...interop.win.reg import read_reg
+else:
+    def read_reg(key, subkey, name, *, default=None, **kwargs):
+        """Stub for read_reg on non-Windows platforms."""
+        return default
+
+class LeidianInstance(Instance):
+    @copy_type(Instance.__init__)
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._args = args
+        self.index: int | None = None
+        self.is_running: bool = False
+
+    @override
+    def refresh(self):
+        ins = LeidianHost.query(id=self.id)
+        assert isinstance(ins, LeidianInstance), f'Expected LeidianInstance, got {type(ins)}'
+        if ins is not None:
+            self.adb_port = ins.adb_port
+            self.adb_ip = ins.adb_ip
+            self.adb_name = ins.adb_name
+            self.is_running = ins.is_running
+            logger.debug('Refreshed Leidian instance: %s', repr(ins))
+
+    @override
+    def start(self):
+        if self.running():
+            logger.warning('Instance is already running.')
+            return
+        logger.info('Starting Leidian instance %s', self)
+        LeidianHost._invoke_manager(['launch', '--index', str(self.index)])
+        self.refresh()
+
+    @override
+    def stop(self):
+        if not self.running():
+            logger.warning('Instance is not running.')
+            return
+        logger.info('Stopping Leidian instance id=%s name=%s...', self.id, self.name)
+        LeidianHost._invoke_manager(['quit', '--index', str(self.index)])
+        self.refresh()
+
+    @override
+    def wait_available(self, timeout: float = 180):
+        cd = Countdown(timeout)
+        it = Interval(5)
+        while not cd.expired() and not self.running():
+            it.wait()
+        if not self.running():
+            raise TimeoutError(f'Leidian instance "{self.name}" is not available.')
+
+    @override
+    def running(self) -> bool:
+        result = LeidianHost._invoke_manager(['isrunning', '--index', str(self.index)])
+        return result.strip() == 'running'
+
+    @override
+    def create_device(self, impl: DeviceImpl, *, timeout: float = 180) -> 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=False,
+            timeout=timeout
+        )
+
+class LeidianHost(HostProtocol):
+    @staticmethod
+    @lru_cache(maxsize=1)
+    def _read_install_path() -> str | None:
+        """
+        从注册表中读取雷电模拟器的安装路径。
+
+        :return: 安装路径，如果未找到则返回 None。
+        """
+        if os.name != 'nt':
+            return None
+
+        try:
+            icon_path = read_reg('HKCU', r'Software\leidian\LDPlayer9', 'DisplayIcon', default=None)
+            if icon_path and isinstance(icon_path, str):
+                icon_path = icon_path.replace('"', '')
+                path = os.path.dirname(icon_path)
+                logger.debug('Leidian installation path (from DisplayIcon): %s', path)
+                return path
+            install_dir = read_reg('HKCU', r'Software\leidian\LDPlayer9', 'InstallDir', default=None)
+            if install_dir and isinstance(install_dir, str):
+                install_dir = install_dir.replace('"', '')
+                logger.debug('Leidian installation path (from InstallDir): %s', install_dir)
+                return install_dir
+        except Exception as e:
+            logger.error(f'Failed to read Leidian installation path from registry: {e}')
+
+        return None
+
+    @staticmethod
+    def _invoke_manager(args: list[str]) -> str:
+        """
+        调用 ldconsole.exe。
+        
+        参考文档：https://www.ldmnq.com/forum/30.html，以及命令行帮助。
+        另外还有个 ld.exe，封装了 adb.exe，可以直接执行 adb 命令。（https://www.ldmnq.com/forum/9178.html）
+
+        :param args: 命令行参数列表。
+        :return: 命令执行的输出。
+        """
+        install_path = LeidianHost._read_install_path()
+        if install_path is None:
+            raise RuntimeError('Leidian is not installed.')
+        manager_path = os.path.join(install_path, 'ldconsole.exe')
+        logger.debug('ldconsole execute: %s', repr(args))
+        output = subprocess.run(
+            [manager_path] + args,
+            capture_output=True,
+            text=True,
+            # encoding='utf-8', # 居然不是 utf-8 编码
+            # https://stackoverflow.com/questions/6011235/run-a-program-from-python-and-have-it-continue-to-run-after-the-script-is-kille
+            creationflags=subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
+        )
+        if output.returncode != 0:
+            raise RuntimeError(f'Failed to invoke ldconsole: {output.stderr}')
+        return output.stdout
+
+    @staticmethod
+    def installed() -> bool:
+        return LeidianHost._read_install_path() is not None
+
+    @staticmethod
+    def list() -> list[Instance]:
+        output = LeidianHost._invoke_manager(['list2'])
+        instances = []
+
+        # 解析 list2 命令的输出
+        # 格式: 索引,标题,顶层窗口句柄,绑定窗口句柄,是否进入android,进程PID,VBox进程PID
+        for line in output.strip().split('\n'):
+            if not line:
+                continue
+
+            parts = line.split(',')
+            if len(parts) < 5:
+                logger.warning(f'Invalid list2 output line: {line}')
+                continue
+
+            index = parts[0]
+            name = parts[1]
+            is_android_started = parts[4] == '1'
+            # 端口号规则 https://help.ldmnq.com/docs/LD9adbserver#a67730c2e7e2e0400d40bcab37d0e0cf
+            adb_port = 5554 + (int(index) * 2)
+
+            instance = LeidianInstance(
+                id=index,
+                name=name,
+                adb_port=adb_port,
+                adb_ip='127.0.0.1',
+                adb_name=f'emulator-{adb_port}'
+            )
+            instance.index = int(index)
+            instance.is_running = is_android_started
+            logger.debug('Leidian instance: %s', repr(instance))
+            instances.append(instance)
+
+        return instances
+
+    @staticmethod
+    def query(*, id: str) -> Instance | None:
+        instances = LeidianHost.list()
+        for instance in instances:
+            if instance.id == id:
+                return instance
+        return None
+
+if __name__ == '__main__':
+    logging.basicConfig(level=logging.DEBUG, format='[%(asctime)s] [%(levelname)s] [%(name)s] [%(funcName)s] [%(lineno)d] %(message)s')
+    print(LeidianHost._read_install_path())
+    print(LeidianHost.installed())
+    print(LeidianHost.list())
+    print(ins:=LeidianHost.query(id='0'))
+    assert isinstance(ins, LeidianInstance)
+    ins.start()
+    ins.wait_available()
+    print('status', ins.running(), ins.adb_port, ins.adb_ip)
+    # ins.stop()
+    # print('status', ins.running(), ins.adb_port, ins.adb_ip)

kotonebot/client/host/mumu12_host.py

@@ -0,0 +1,177 @@
+import os
+import json
+import subprocess
+from functools import lru_cache
+from typing import Any
+from typing_extensions import override
+
+from kotonebot import logging
+from kotonebot.client import DeviceImpl, Device
+from kotonebot.util import Countdown, Interval
+from .protocol import HostProtocol, Instance, copy_type
+
+logger = logging.getLogger(__name__)
+
+if os.name == 'nt':
+    from ...interop.win.reg import read_reg
+else:
+    def read_reg(key, subkey, name, *, default=None, **kwargs):
+        """Stub for read_reg on non-Windows platforms."""
+        return default
+
+class Mumu12Instance(Instance):
+    @copy_type(Instance.__init__)
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._args = args
+        self.index: int | None = None
+        self.is_android_started: bool = False
+    
+    @override
+    def refresh(self):
+        ins = Mumu12Host.query(id=self.id)
+        assert isinstance(ins, Mumu12Instance), f'Expected Mumu12Instance, got {type(ins)}'
+        if ins is not None:
+            self.adb_port = ins.adb_port
+            self.adb_ip = ins.adb_ip
+            self.adb_name = ins.adb_name
+            self.is_android_started = ins.is_android_started
+            logger.debug('Refreshed MuMu12 instance: %s', repr(ins))
+    
+    @override
+    def start(self):
+        if self.running():
+            logger.warning('Instance is already running.')
+            return
+        logger.info('Starting MuMu12 instance %s', self)
+        Mumu12Host._invoke_manager(['control', '-v', self.id, 'launch'])
+        self.refresh()
+    
+    @override
+    def stop(self):
+        if not self.running():
+            logger.warning('Instance is not running.')
+            return
+        logger.info('Stopping MuMu12 instance id=%s name=%s...', self.id, self.name)
+        Mumu12Host._invoke_manager(['control', '-v', self.id, 'shutdown'])
+        self.refresh()
+    
+    @override
+    def wait_available(self, timeout: float = 180):
+        cd = Countdown(timeout)
+        it = Interval(5)
+        while not cd.expired() and not self.running():
+            it.wait()
+            self.refresh()
+        if not self.running():
+            raise TimeoutError(f'MuMu12 instance "{self.name}" is not available.')
+    
+    @override
+    def running(self) -> bool:
+        return self.is_android_started
+
+class Mumu12Host(HostProtocol):
+    @staticmethod
+    @lru_cache(maxsize=1)
+    def _read_install_path() -> str | None:
+        """
+        Reads the installation path (DisplayIcon) of MuMu Player 12 from the registry.
+
+        :return: The path to the display icon if found, otherwise None.
+        """
+        if os.name != 'nt':
+            return None
+
+        uninstall_subkeys = [
+            r'SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\MuMuPlayer-12.0',
+            # TODO: 支持国际版 MuMu
+            # r'SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\MuMuPlayerGlobal-12.0'
+        ]
+
+        for subkey in uninstall_subkeys:
+            icon_path = read_reg('HKLM', subkey, 'DisplayIcon', default=None)
+            if icon_path and isinstance(icon_path, str):
+                icon_path = icon_path.replace('"', '')
+                path = os.path.dirname(icon_path)
+                logger.debug('MuMu Player 12 installation path: %s', path)
+                return path
+        return None
+
+    @staticmethod
+    def _invoke_manager(args: list[str]) -> str:
+        """
+        调用 MuMuManager.exe。
+        
+        :param args: 命令行参数列表。
+        :return: 命令执行的输出。
+        """
+        install_path = Mumu12Host._read_install_path()
+        if install_path is None:
+            raise RuntimeError('MuMu Player 12 is not installed.')
+        manager_path = os.path.join(install_path, 'MuMuManager.exe')
+        logger.debug('MuMuManager execute: %s', repr(args))
+        output = subprocess.run(
+            [manager_path] + args,
+            capture_output=True,
+            text=True,
+            encoding='utf-8',
+            # https://stackoverflow.com/questions/6011235/run-a-program-from-python-and-have-it-continue-to-run-after-the-script-is-kille
+            creationflags=subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
+        )
+        if output.returncode != 0:
+            # raise RuntimeError(f'Failed to invoke MuMuManager: {output.stderr}')
+            logger.warning('Failed to invoke MuMuManager: %s', output.stderr)
+        return output.stdout
+
+    @staticmethod
+    def installed() -> bool:
+        return Mumu12Host._read_install_path() is not None
+
+    @staticmethod
+    def list() -> list[Instance]:
+        output = Mumu12Host._invoke_manager(['info', '-v', 'all'])
+        logger.debug('MuMuManager.exe output: %s', output)
+        
+        try:
+            data: dict[str, dict[str, Any]] = json.loads(output)
+            if 'name' in data.keys():
+                # 这里有个坑：
+                # 如果只有一个实例，返回的 JSON 结构是单个对象而不是数组
+                data = { '0': data }
+            instances = []
+            for index, instance_data in data.items():
+                instance = Mumu12Instance(
+                    id=index,
+                    name=instance_data['name'],
+                    adb_port=instance_data.get('adb_port'),  
+                    adb_ip=instance_data.get('adb_host_ip', '127.0.0.1'), 
+                    adb_name=None
+                )
+                instance.index = int(index)
+                instance.is_android_started = instance_data.get('is_android_started', False)
+                logger.debug('Mumu12 instance: %s', repr(instance))
+                instances.append(instance)
+            return instances
+        except json.JSONDecodeError as e:
+            raise RuntimeError(f'Failed to parse output: {e}')
+    
+    @staticmethod
+    def query(*, id: str) -> Instance | None:
+        instances = Mumu12Host.list()
+        for instance in instances:
+            if instance.id == id:
+                return instance
+        return None
+    
+if __name__ == '__main__':
+    logging.basicConfig(level=logging.DEBUG, format='[%(asctime)s] [%(levelname)s] [%(name)s] [%(funcName)s] [%(lineno)d] %(message)s')
+    print(Mumu12Host._read_install_path())
+    print(Mumu12Host.installed())
+    print(Mumu12Host.list())
+    print(ins:=Mumu12Host.query(id='2'))
+    assert isinstance(ins, Mumu12Instance)
+    ins.start()
+    ins.wait_available()
+    print('status', ins.running(), ins.adb_port, ins.adb_ip)
+    ins.stop()
+    print('status', ins.running(), ins.adb_port, ins.adb_ip)