ksaa 2025.5.23.3__py3-none-any.whl → 2025.6.23.0__py3-none-any.whl

kotonebot/backend/loop.py

@@ -0,0 +1,277 @@
+import time
+from functools import lru_cache, partial
+from typing import Callable, Any, overload, Literal, Generic, TypeVar, cast, get_args, get_origin
+
+from cv2.typing import MatLike
+
+from kotonebot.util import Interval
+from kotonebot import device, image, ocr
+from kotonebot.backend.core import Image
+from kotonebot.backend.ocr import TextComparator
+from kotonebot.client.protocol import ClickableObjectProtocol
+
+
+class LoopAction:
+    def __init__(self, loop: 'Loop', func: Callable[[], ClickableObjectProtocol | None]):
+        self.loop = loop
+        self.func = func
+        self.result: ClickableObjectProtocol | None = None
+
+    @property
+    def found(self):
+        """
+        是否找到结果。若父 Loop 未在运行中，则返回 False。
+        """
+        if not self.loop.running:
+            return False
+        return bool(self.result)
+
+    def __bool__(self):
+        return self.found
+
+    def reset(self):
+        """
+        重置 LoopAction，以复用此对象。
+        """
+        self.result = None
+
+    def do(self):
+        """
+        执行 LoopAction。
+        :return: 执行结果。
+        """
+        if not self.loop.running:
+            return
+        if self.loop.found_anything:
+            # 本轮循环已执行任意操作，因此不需要再继续检测
+            return
+        self.result = self.func()
+        if self.result:
+            self.loop.found_anything = True
+
+    def click(self, *, at: tuple[int, int] | None = None):
+        """
+        点击寻找结果。若结果为空，会跳过执行。
+
+        :return:
+        """
+        if self.result:
+            if at is not None:
+                device.click(*at)
+            else:
+                device.click(self.result)
+
+    def call(self, func: Callable[[ClickableObjectProtocol], Any]):
+        pass
+
+
+class Loop:
+    def __init__(
+            self,
+            *,
+            timeout: float = 300,
+            interval: float = 0.3,
+            auto_screenshot: bool = True
+    ):
+        self.running = True
+        self.found_anything = False
+        self.auto_screenshot = auto_screenshot
+        """
+        是否在每次循环开始时（Loop.tick() 被调用时）截图。
+        """
+        self.__last_loop: float = -1
+        self.__interval = Interval(interval)
+        self.screenshot: MatLike | None = None
+        """上次截图时的图像数据。"""
+
+    def __iter__(self):
+        self.__interval.reset()
+        return self
+
+    def __next__(self):
+        if not self.running:
+            raise StopIteration
+        self.found_anything = False
+        self.__last_loop = time.time()
+        return self.tick()
+
+    def tick(self):
+        self.__interval.wait()
+        if self.auto_screenshot:
+            self.screenshot = device.screenshot()
+        self.__last_loop = time.time()
+        self.found_anything = False
+        return self
+
+    def exit(self):
+        """
+        结束循环。
+        """
+        self.running = False
+
+    @overload
+    def when(self, condition: Image) -> LoopAction:
+        ...
+
+    @overload
+    def when(self, condition: TextComparator) -> LoopAction:
+        ...
+
+    def when(self, condition: Any):
+        """
+        判断某个条件是否成立。
+
+        :param condition:
+        :return:
+        """
+        if isinstance(condition, Image):
+            func = partial(image.find, condition)
+        elif isinstance(condition, TextComparator):
+            func = partial(ocr.find, condition)
+        else:
+            raise ValueError('Invalid condition type.')
+        la = LoopAction(self, func)
+        la.reset()
+        la.do()
+        return la
+
+    def until(self, condition: Any):
+        """
+        当满足指定条件时，结束循环。
+
+        等价于 ``loop.when(...).call(lambda _: loop.exit())``
+        """
+        return self.when(condition).call(lambda _: self.exit())
+
+    def click_if(self, condition: Any, *, at: tuple[int, int] | None = None):
+        """
+        检测指定对象是否出现，若出现，点击该对象或指定位置。
+
+        ``click_if()`` 等价于 ``loop.when(...).click(...)``。
+
+        :param condition: 检测目标。
+        :param at: 点击位置。若为 None，表示点击找到的目标。
+        """
+        return self.when(condition).click(at=at)
+
+StateType = TypeVar('StateType')
+class StatedLoop(Loop, Generic[StateType]):
+    def __init__(
+        self,
+        states: list[Any] | None = None,
+        initial_state: StateType | None = None,
+        *,
+        timeout: float = 300,
+        interval: float = 0.3,
+        auto_screenshot: bool = True
+    ):
+        self.__tmp_states = states
+        self.__tmp_initial_state = initial_state
+        self.state: StateType
+        super().__init__(timeout=timeout, interval=interval, auto_screenshot=auto_screenshot)
+
+    def __iter__(self):
+        # __retrive_state_values() 只能在非 __init__ 中调用
+        self.__retrive_state_values()
+        return super().__iter__()
+
+    def __retrive_state_values(self):
+        # HACK: __orig_class__ 是 undocumented 属性
+        if not hasattr(self, '__orig_class__'):
+            # 如果 Foo 不是以参数化泛型的方式实例化的，可能没有 __orig_class__
+            if self.state is None:
+                raise ValueError('Either specify `states` or use StatedLoop[Literal[...]] syntax.')
+        else:
+            generic_type_args = get_args(self.__orig_class__) # type: ignore
+            if len(generic_type_args) != 1:
+                raise ValueError('StatedLoop must have exactly one generic type argument.')
+            state_values = get_args(generic_type_args[0])
+            if not state_values:
+                raise ValueError('StatedLoop must have at least one state value.')
+            self.states = cast(tuple[StateType, ...], state_values)
+            self.state = self.__tmp_initial_state or self.states[0]
+            return state_values
+
+
+def StatedLoop2(states: StateType) -> StatedLoop[StateType]:
+    state_values = get_args(states)
+    return cast(StatedLoop[StateType], Loop())
+
+if __name__ == '__main__':
+    from kotonebot.kaa.tasks import R
+    from kotonebot.backend.ocr import contains
+    from kotonebot.backend.context import manual_context, init_context
+
+    # T = TypeVar('T')
+    # class Foo(Generic[T]):
+    #     def get_literal_params(self) -> list | None:
+    #         """
+    #         尝试获取泛型参数 T (如果它是 Literal 类型) 的参数列表。
+    #         """
+    #         # self.__orig_class__ 会是 Foo 的具体参数化类型，
+    #         # 例如 Foo[Literal['p0', 'p1', 'p2', 'p3', 'ap']]
+    #         if not hasattr(self, '__orig_class__'):
+    #             # 如果 Foo 不是以参数化泛型的方式实例化的，可能没有 __orig_class__
+    #             return None
+    #
+    #         # generic_type_args 是传递给 Foo 的类型参数元组
+    #         # 例如 (Literal['p0', 'p1', 'p2', 'p3', 'ap'],)
+    #         generic_type_args = get_args(self.__orig_class__)
+    #
+    #         if not generic_type_args:
+    #             # Foo 没有类型参数
+    #             return None
+    #
+    #         # T_type 是 Foo 的第一个类型参数
+    #         # 例如 Literal['p0', 'p1', 'p2', 'p3', 'ap']
+    #         t_type = generic_type_args[0]
+    #
+    #         # 检查 T_type 是否是 Literal 类型
+    #         if get_origin(t_type) is Literal:
+    #             # literal_args 是 Literal 类型的参数元组
+    #             # 例如 ('p0', 'p1', 'p2', 'p3', 'ap')
+    #             literal_args = get_args(t_type)
+    #             return list(literal_args)
+    #         else:
+    #             # T 不是 Literal 类型
+    #             return None
+    # f = Foo[Literal['p0', 'p1', 'p2', 'p3', 'ap']]()
+    # values = f.get_literal_params()
+    # 1
+
+    from typing_extensions import reveal_type
+    slp = StatedLoop[Literal['p0', 'p1', 'p2', 'p3', 'ap']]()
+    for l in slp:
+        reveal_type(l.states)
+
+    # init_context()
+    # manual_context().begin()
+    # for l in Loop():
+    #     l.when(R.Produce.ButtonUse).click()
+    #     l.when(R.Produce.ButtonRefillAP).click()
+    #     l.when(contains("123")).click()
+    #     l.click_if(contains("!23"), at=(1, 2))
+
+    # State = Literal['p0', 'p1', 'p2', 'p3', 'ap']
+    # for sl in StatedLoop[State]():
+    #     match sl.state:
+    #         case 'p0':
+    #             sl.click_if(R.Produce.ButtonProduce)
+    #             sl.click_if(contains('master'))
+    #             sl.when(R.Produce.ButtonPIdolOverview).goto('p1')
+    #             # AP 不足
+    #             sl.when(R.Produce.TextAPInsufficient).goto('ap')
+    #         case 'ap':
+    #             pass
+    #         # p1: 选择偶像
+    #         case 'p1':
+    #             sl.call(lambda _: select_idol(idol_skin_id), once=True)
+    #             sl.when(R.Produce.TextAnotherIdolAvailableDialog).call(dialog.no)
+    #             sl.click_if(R.Common.ButtonNextNoIcon)
+    #             sl.until(R.Produce.TextStepIndicator2).goto('p2')
+    #         case 'p2':
+    #             sl.when(contains("123")).click()
+    #         case 'p3':
+    #             sl.click_if(contains("!23"), at=(1, 2))
+    #         case _:
+    #             assert_never(sl.state)

kotonebot/client/__init__.py

@@ -1,5 +1,8 @@
 from .device import Device
-from .factory import create_device, DeviceImpl
+from .registration import create_device, DeviceImpl
+
+# 确保所有实现都被注册
+from . import implements  # noqa: F401
 
 __all__ = [
     'Device',

kotonebot/client/device.py

@@ -11,7 +11,7 @@ from adbutils._device import AdbDevice as AdbUtilsDevice
 from ..backend.debug import result
 from kotonebot.backend.core import HintBox
 from kotonebot.primitives import Rect, Point, is_point
-from .protocol import ClickableObjectProtocol, Commandable, Touchable, Screenshotable
+from .protocol import ClickableObjectProtocol, Commandable, Touchable, Screenshotable, AndroidCommandable, WindowsCommandable
 
 logger = logging.getLogger(__name__)
 
@@ -71,7 +71,6 @@ class Device:
         横屏时为 'landscape'，竖屏时为 'portrait'。
         """
 
-        self._command: Commandable
         self._touch: Touchable
         self._screenshot: Screenshotable
 
@@ -90,12 +89,6 @@ class Device:
     def adb(self, value: AdbUtilsDevice) -> None:
         self._adb = value
 
-    def launch_app(self, package_name: str) -> None:
-        """
-        根据包名启动 app
-        """
-        self._command.launch_app(package_name)
-    
     @overload
     def click(self) -> None:
         """
@@ -306,17 +299,6 @@ class Device:
         """
         return self._screenshot.screen_size
 
-    def current_package(self) -> str | None:
-        """
-        获取前台 APP 的包名。
-
-        :return: 前台 APP 的包名。如果获取失败，则返回 None。
-        :exception: 如果设备不支持此功能，则抛出 NotImplementedError。
-        """
-        ret = self._command.current_package()
-        logger.debug("current_package: %s", ret)
-        return ret
-
     def detect_orientation(self) -> Literal['portrait', 'landscape'] | None:
         """
         检测当前设备方向并设置 `self.orientation` 属性。
@@ -330,10 +312,30 @@ class AndroidDevice(Device):
     def __init__(self, adb_connection: AdbUtilsDevice | None = None) -> None:
         super().__init__('android')
         self._adb: AdbUtilsDevice | None = adb_connection
+        self.commands: AndroidCommandable
+        
+    def current_package(self) -> str | None:
+        """
+        获取前台 APP 的包名。
+
+        :return: 前台 APP 的包名。如果获取失败，则返回 None。
+        :exception: 如果设备不支持此功能，则抛出 NotImplementedError。
+        """
+        ret = self.commands.current_package()
+        logger.debug("current_package: %s", ret)
+        return ret
+
+    def launch_app(self, package_name: str) -> None:
+        """
+        根据包名启动 app
+        """
+        self.commands.launch_app(package_name)
+    
 
 class WindowsDevice(Device):
     def __init__(self) -> None:
         super().__init__('windows')
+        self.commands: WindowsCommandable
 
         
 if __name__ == "__main__":
@@ -346,10 +348,10 @@ if __name__ == "__main__":
     d = adb.device_list()[-1]
     d.shell("dumpsys activity top | grep ACTIVITY | tail -n 1")
     dd = AndroidDevice(d)
-    adb_imp = AdbRawImpl(dd)
-    dd._command = adb_imp
+    adb_imp = AdbRawImpl(d)
     dd._touch = adb_imp
     dd._screenshot = adb_imp
+    dd.commands = adb_imp
     # dd._screenshot = MinicapScreenshotImpl(dd)
     # dd._screenshot = UiAutomator2Impl(dd)
 

kotonebot/client/host/__init__.py

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

kotonebot/client/host/custom.py

@@ -1,19 +1,22 @@
 import os
 import subprocess
 from psutil import process_iter
-from .protocol import HostProtocol, Instance
-from typing import Optional, ParamSpec, TypeVar, TypeGuard
+from .protocol import Instance, AdbHostConfig
+from typing import ParamSpec, TypeVar, cast
 from typing_extensions import override
 
 from kotonebot import logging
+from kotonebot.client import DeviceImpl
 from kotonebot.client.device import Device
+from kotonebot.client.registration import AdbBasedImpl, create_device
+from kotonebot.client.implements.adb import AdbImplConfig
 
 logger = logging.getLogger(__name__)
 
 P = ParamSpec('P')
 T = TypeVar('T')
 
-class CustomInstance(Instance):
+class CustomInstance(Instance[AdbHostConfig]):
     def __init__(self, exe_path: str | None, emulator_args: str = "", *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.exe_path: str | None = exe_path
@@ -65,6 +68,26 @@ class CustomInstance(Instance):
     def refresh(self):
         pass
 
+    @override
+    def create_device(self, impl: DeviceImpl, host_config: AdbHostConfig) -> Device:
+        """为自定义实例创建 Device。"""
+        if self.adb_port is None:
+            raise ValueError("ADB port is not set and is required.")
+
+        # 为 ADB 相关的实现创建配置
+        if impl in ['adb', 'adb_raw', 'uiautomator2']:
+            config = AdbImplConfig(
+                addr=f'{self.adb_ip}:{self.adb_port}',
+                connect=True,
+                disconnect=True,
+                device_serial=self.adb_name,
+                timeout=host_config.timeout
+            )
+            impl = cast(AdbBasedImpl, impl) # make pylance happy
+            return create_device(impl, config)
+        else:
+            raise ValueError(f'Unsupported device implementation for Custom: {impl}')
+
     def __repr__(self) -> str:
         return f'CustomInstance(#{self.id}# at "{self.exe_path}" with {self.adb_ip}:{self.adb_port})'
 

kotonebot/client/host/leidian_host.py

@@ -1,13 +1,16 @@
 import os
 import subprocess
+from typing import cast
 from functools import lru_cache
 from typing_extensions import override
 
 from kotonebot import logging
-from kotonebot.client import DeviceImpl, create_device
+from kotonebot.client import DeviceImpl
 from kotonebot.client.device import Device
+from kotonebot.client.registration import AdbBasedImpl, create_device
+from kotonebot.client.implements.adb import AdbImplConfig
 from kotonebot.util import Countdown, Interval
-from .protocol import HostProtocol, Instance, copy_type
+from .protocol import HostProtocol, Instance, copy_type, AdbHostConfig
 
 logger = logging.getLogger(__name__)
 
@@ -18,7 +21,7 @@ else:
         """Stub for read_reg on non-Windows platforms."""
         return default
 
-class LeidianInstance(Instance):
+class LeidianInstance(Instance[AdbHostConfig]):
     @copy_type(Instance.__init__)
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -70,16 +73,24 @@ class LeidianInstance(Instance):
         return result.strip() == 'running'
 
     @override
-    def create_device(self, impl: DeviceImpl, *, timeout: float = 180) -> Device:
+    def create_device(self, impl: DeviceImpl, host_config: AdbHostConfig) -> Device:
+        """为雷电模拟器实例创建 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
-        )
+
+        # 为 ADB 相关的实现创建配置
+        if impl in ['adb', 'adb_raw', 'uiautomator2']:
+            config = AdbImplConfig(
+                addr=f'{self.adb_ip}:{self.adb_port}',
+                connect=False,  # 雷电模拟器不需要 adb connect
+                disconnect=False,
+                device_serial=self.adb_name,
+                timeout=host_config.timeout
+            )
+            impl = cast(AdbBasedImpl, impl) # make pylance happy
+            return create_device(impl, config)
+        else:
+            raise ValueError(f'Unsupported device implementation for Leidian: {impl}')
 
 class LeidianHost(HostProtocol):
     @staticmethod

kotonebot/client/host/mumu12_host.py

@@ -2,13 +2,15 @@ import os
 import json
 import subprocess
 from functools import lru_cache
-from typing import Any
+from typing import Any, cast
 from typing_extensions import override
 
 from kotonebot import logging
 from kotonebot.client import DeviceImpl, Device
+from kotonebot.client.registration import AdbBasedImpl, create_device
+from kotonebot.client.implements.adb import AdbImplConfig
 from kotonebot.util import Countdown, Interval
-from .protocol import HostProtocol, Instance, copy_type
+from .protocol import HostProtocol, Instance, copy_type, AdbHostConfig
 
 logger = logging.getLogger(__name__)
 
@@ -19,7 +21,7 @@ else:
         """Stub for read_reg on non-Windows platforms."""
         return default
 
-class Mumu12Instance(Instance):
+class Mumu12Instance(Instance[AdbHostConfig]):
     @copy_type(Instance.__init__)
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -70,6 +72,26 @@ class Mumu12Instance(Instance):
     def running(self) -> bool:
         return self.is_android_started
 
+    @override
+    def create_device(self, impl: DeviceImpl, host_config: AdbHostConfig) -> Device:
+        """为MuMu12模拟器实例创建 Device。"""
+        if self.adb_port is None:
+            raise ValueError("ADB port is not set and is required.")
+
+        # 为 ADB 相关的实现创建配置
+        if impl in ['adb', 'adb_raw', 'uiautomator2']:
+            config = AdbImplConfig(
+                addr=f'{self.adb_ip}:{self.adb_port}',
+                connect=True,
+                disconnect=True,
+                device_serial=self.adb_name,
+                timeout=host_config.timeout
+            )
+            impl = cast(AdbBasedImpl, impl) # make pylance happy
+            return create_device(impl, config)
+        else:
+            raise ValueError(f'Unsupported device implementation for MuMu12: {impl}')
+
 class Mumu12Host(HostProtocol):
     @staticmethod
     @lru_cache(maxsize=1)

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)

kotonebot/client/implements/__init__.py

@@ -0,0 +1,6 @@
+# 导入所有内置实现，以触发它们的 @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