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

kotonebot/client/implements/nemu_ipc/nemu_ipc.py

@@ -0,0 +1,327 @@
+import os
+import ctypes
+import logging
+import time
+from dataclasses import dataclass
+from time import sleep
+from typing import Literal
+from typing_extensions import override
+
+import cv2
+import numpy as np
+from cv2.typing import MatLike
+
+from ...device import AndroidDevice, Device
+from ...protocol import Touchable, Screenshotable
+from ...registration import ImplConfig
+from .external_renderer_ipc import ExternalRendererIpc
+from kotonebot.errors import KotonebotError
+
+logger = logging.getLogger(__name__)
+
+
+class NemuIpcIncompatible(Exception):
+    """MuMu12 版本过低或 dll 不兼容"""
+    pass
+
+
+class NemuIpcError(KotonebotError):
+    """调用 IPC 过程中发生错误"""
+    pass
+
+
+@dataclass
+class NemuIpcImplConfig(ImplConfig):
+    """nemu_ipc 能力的配置模型。"""
+    nemu_folder: str
+    r"""MuMu12 根目录（如 F:\Apps\Netease\MuMuPlayer-12.0）。"""
+    instance_id: int
+    """模拟器实例 ID。"""
+    display_id: int | None = 0
+    """目标显示器 ID，默认为 0（主显示器）。若为 None 且设置了 target_package_name，则自动获取对应的 display_id。"""
+    target_package_name: str | None = None
+    """目标应用包名，用于自动获取 display_id。"""
+    app_index: int = 0
+    """多开应用索引，传给 get_display_id 方法。"""
+    wait_package_timeout: float = 60  # 单位秒，-1 表示永远等待，0 表示不等待，立即抛出异常
+    wait_package_interval: float = 0.1  # 单位秒
+
+
+class NemuIpcImpl(Touchable, Screenshotable):
+    """
+    利用 MuMu12 提供的 external_renderer_ipc.dll 进行截图与触摸控制。
+    """
+
+    def __init__(self, config: NemuIpcImplConfig):
+        self.config = config
+        self.__width: int = 0
+        self.__height: int = 0
+        self.__connected: bool = False
+        self._connect_id: int = 0
+        self.nemu_folder = config.nemu_folder
+
+        # --------------------------- DLL 封装 ---------------------------
+        self._ipc = ExternalRendererIpc(config.nemu_folder)
+        logger.info("ExternalRendererIpc initialized and DLL loaded")
+
+    @property
+    def width(self) -> int:
+        """
+        屏幕宽度。
+        
+        若为 0，表示未连接或未获取到分辨率。
+        """
+        return self.__width
+    
+    @property
+    def height(self) -> int:
+        """
+        屏幕高度。
+        
+        若为 0，表示未连接或未获取到分辨率。
+        """
+        return self.__height
+    
+    @property
+    def connected(self) -> bool:
+        """是否已连接。"""
+        return self.__connected
+
+    # ------------------------------------------------------------------
+    # 基础控制
+    # ------------------------------------------------------------------
+
+    def _ensure_connected(self) -> None:
+        if not self.__connected:
+            self.connect()
+
+    def _get_display_id(self) -> int:
+        """获取有效的 display_id。"""
+        # 如果配置中直接指定了 display_id，直接返回
+        if self.config.display_id is not None:
+            return self.config.display_id
+
+        # 如果设置了 target_package_name，实时获取 display_id
+        if self.config.target_package_name:
+            self._ensure_connected()
+
+            timeout = self.config.wait_package_timeout
+            interval = self.config.wait_package_interval
+            if timeout == -1:
+                timeout = float('inf')
+            start_time = time.time()
+            while True:
+                display_id = self._ipc.get_display_id(
+                    self._connect_id,
+                    self.config.target_package_name,
+                    self.config.app_index
+                )
+                if display_id >= 0:
+                    return display_id
+                elif display_id == -1:
+                    # 可以继续等
+                    pass
+                else:
+                    # 未知错误
+                    raise NemuIpcError(f"Failed to get display_id for package '{self.config.target_package_name}', error code={display_id}")
+                if time.time() - start_time > timeout:
+                    break
+                sleep(interval)
+            
+            raise NemuIpcError(f"Failed to get display_id for package '{self.config.target_package_name}' within {timeout}s")
+
+        # 如果都没有设置，抛出错误
+        raise NemuIpcError("display_id is None and target_package_name is not set. Please set display_id or target_package_name in config.")
+
+    def connect(self) -> None:
+        """连接模拟器。"""
+        if self.__connected:
+            return
+
+        connect_id = self._ipc.connect(self.nemu_folder, self.config.instance_id)
+        if connect_id == 0:
+            raise NemuIpcError("nemu_connect failed, please check if the emulator is running and the instance ID is correct.")
+
+        self._connect_id = connect_id
+        self.__connected = True
+        logger.debug("NemuIpc connected, connect_id=%d", connect_id)
+
+    def disconnect(self) -> None:
+        """断开连接。"""
+        if not self.__connected:
+            return
+        self._ipc.disconnect(self._connect_id)
+        self.__connected = False
+        self._connect_id = 0
+        logger.debug("NemuIpc disconnected.")
+
+    # ------------------------------------------------------------------
+    # Screenshotable 接口实现
+    # ------------------------------------------------------------------
+    @property
+    def screen_size(self) -> tuple[int, int]:
+        """获取屏幕分辨率。"""
+        if self.__width == 0 or self.__height == 0:
+            self._refresh_resolution()
+        if self.__width == 0 or self.__height == 0:
+            raise NemuIpcError("Screen resolution not obtained, please connect to the emulator first.")
+        return self.__width, self.__height
+
+    @override
+    def detect_orientation(self):
+        return self.get_display_orientation(self._get_display_id())
+
+    def get_display_orientation(self, display_id: int = 0) -> Literal['portrait', 'landscape'] | None:
+        """获取指定显示屏的方向。"""
+        width, height = self.query_resolution(display_id)
+        if width > height:
+            return "landscape"
+        if height > width:
+            return "portrait"
+        return None
+
+    @override
+    def screenshot(self) -> MatLike:
+        self._ensure_connected()
+
+        # 必须每次都更新分辨率，因为屏幕可能会旋转
+        self._refresh_resolution()
+
+        length = self.__width * self.__height * 4 # RGBA
+        buf_type = ctypes.c_ubyte * length
+        buffer = buf_type()
+
+        w_ptr = ctypes.pointer(ctypes.c_int(self.__width))
+        h_ptr = ctypes.pointer(ctypes.c_int(self.__height))
+
+        ret = self._ipc.capture_display(
+            self._connect_id,
+            self._get_display_id(),
+            length,
+            ctypes.cast(w_ptr, ctypes.c_void_p),
+            ctypes.cast(h_ptr, ctypes.c_void_p),
+            ctypes.cast(buffer, ctypes.c_void_p),
+        )
+        if ret != 0:
+            raise NemuIpcError(f"nemu_capture_display screenshot failed, error code={ret}")
+
+        # 读入并转换数据
+        img = np.ctypeslib.as_array(buffer).reshape((self.__height, self.__width, 4))
+        # RGBA -> BGR
+        img = cv2.cvtColor(img, cv2.COLOR_RGBA2BGR)
+        cv2.flip(img, 0, dst=img)
+        return img
+
+    # --------------------------- 内部工具 -----------------------------
+
+    def _refresh_resolution(self) -> None:
+        """刷新分辨率信息。"""
+        display_id = self._get_display_id()
+        self.__width, self.__height = self.query_resolution(display_id)
+
+    def query_resolution(self, display_id: int = 0) -> tuple[int, int]:
+        """
+        查询指定显示屏的分辨率。
+        
+        :param display_id: 显示屏 ID。
+        :return: 分辨率 (width, height)。
+        :raise NemuIpcError: 查询失败。
+        """
+        self._ensure_connected()
+
+        w_ptr = ctypes.pointer(ctypes.c_int(0))
+        h_ptr = ctypes.pointer(ctypes.c_int(0))
+        ret = self._ipc.capture_display(
+            self._connect_id,
+            display_id,
+            0,
+            ctypes.cast(w_ptr, ctypes.c_void_p),
+            ctypes.cast(h_ptr, ctypes.c_void_p),
+            ctypes.c_void_p(),
+        )
+        if ret != 0:
+            raise NemuIpcError(f"Call nemu_capture_display failed. Return value={ret}")
+
+        return w_ptr.contents.value, h_ptr.contents.value
+
+    # ------------------------------------------------------------------
+    # Touchable 接口实现
+    # ------------------------------------------------------------------
+    def __convert_pos(self, x: int, y: int) -> tuple[int, int]:
+        # Android 显示屏有两套坐标：逻辑坐标与物理坐标。
+        # 逻辑坐标原点始终是画面左上角，而物理坐标原点则始终是显示屏的左上角。
+        # 如果屏幕画面旋转，会导致两个坐标的原点不同，坐标也不同。
+        # ========
+        # 这里传给 MuMu 的是逻辑坐标，ExternalRendererIpc DLL 内部会
+        # 自动判断旋转，并转换为物理坐标。但是这部分有个 bug：
+        # 旋转没有考虑到多显示器，只是以主显示器为准，若两个显示器旋转不一致，
+        # 会导致错误地转换坐标。因此需要在 Python 层面 workaround 这个问题。
+        # 通过判断主显示器与当前显示器的旋转，将坐标进行预转换，抵消 DLL 层的错误转换。
+        display_id = self._get_display_id()
+        if display_id == 0:
+            return x, y
+        else:
+            primary = self.get_display_orientation(0)
+            primary_size = self.query_resolution(0)
+            current = self.get_display_orientation(display_id)
+            if primary == current:
+                return x, y
+            else:
+                # 如果旋转不一致，视为顺时针旋转了 90°
+                # 因此我们要提前逆时针旋转 90°
+                self._refresh_resolution()
+                x, y = y, primary_size[1] - x
+                return x, y
+    
+    @override
+    def click(self, x: int, y: int) -> None:
+        self._ensure_connected()
+        display_id = self._get_display_id()
+        x, y = self.__convert_pos(x, y)
+        self._ipc.input_touch_down(self._connect_id, display_id, x, y)
+        sleep(0.01)
+        self._ipc.input_touch_up(self._connect_id, display_id)
+
+    @override
+    def swipe(
+        self,
+        x1: int,
+        y1: int,
+        x2: int,
+        y2: int,
+        duration: float | None = None,
+    ) -> None:
+        self._ensure_connected()
+
+        duration = duration or 0.3
+        steps = max(int(duration / 0.01), 2)
+        display_id = self._get_display_id()
+        x1, y1 = self.__convert_pos(x1, y1)
+        x2, y2 = self.__convert_pos(x2, y2)
+
+        xs = np.linspace(x1, x2, steps, dtype=int)
+        ys = np.linspace(y1, y2, steps, dtype=int)
+
+        # 按下第一点
+        self._ipc.input_touch_down(self._connect_id, display_id, xs[0], ys[0])
+        sleep(0.01)
+        # 中间移动
+        for px, py in zip(xs[1:-1], ys[1:-1]):
+            self._ipc.input_touch_down(self._connect_id, display_id, px, py)
+            sleep(0.01)
+
+        # 最终抬起
+        self._ipc.input_touch_up(self._connect_id, display_id)
+        sleep(0.01)
+        
+if __name__ == '__main__':
+    nemu = NemuIpcImpl(NemuIpcImplConfig(
+        r'F:\Apps\Netease\MuMuPlayer-12.0', 0, None,
+        target_package_name='com.android.chrome',
+    ))
+    nemu.connect()
+    # while True:
+    #     nemu.click(0, 0)
+    nemu.click(100, 100)
+    nemu.click(100*3, 100)
+    nemu.click(100*3, 100*3)

kotonebot/client/implements/remote_windows.py

@@ -14,6 +14,7 @@ import xmlrpc.server
 from typing import Literal, cast, Any, Tuple
 from functools import cached_property
 from threading import Thread
+from dataclasses import dataclass
 
 import cv2
 import numpy as np
@@ -22,10 +23,18 @@ from cv2.typing import MatLike
 from kotonebot import logging
 from ..device import Device, WindowsDevice
 from ..protocol import Touchable, Screenshotable
-from .windows import WindowsImpl
+from ..registration import ImplConfig
+from .windows import WindowsImpl, WindowsImplConfig
 
 logger = logging.getLogger(__name__)
 
+# 定义配置模型
+@dataclass
+class RemoteWindowsImplConfig(ImplConfig):
+    windows_impl_config: WindowsImplConfig
+    host: str = "localhost"
+    port: int = 8000
+
 def _encode_image(image: MatLike) -> str:
     """Encode an image as a base64 string."""
     success, buffer = cv2.imencode('.png', image)
@@ -48,13 +57,17 @@ class RemoteWindowsServer:
     This class wraps a WindowsImpl instance and exposes its methods via XML-RPC.
     """
 
-    def __init__(self, host="localhost", port=8000):
+    def __init__(self, windows_impl_config: WindowsImplConfig, host="localhost", port=8000):
         """Initialize the server with the given host and port."""
         self.host = host
         self.port = port
         self.server = None
         self.device = WindowsDevice()
-        self.impl = WindowsImpl(self.device)
+        self.impl = WindowsImpl(
+            WindowsDevice(),
+            ahk_exe_path=windows_impl_config.ahk_exe_path,
+            window_title=windows_impl_config.window_title
+        )
         self.device._screenshot = self.impl
         self.device._touch = self.impl
 
@@ -177,21 +190,4 @@ class RemoteWindowsImpl(Touchable, Screenshotable):
     def swipe(self, x1: int, y1: int, x2: int, y2: int, duration: float | None = None) -> None:
         """Swipe from (x1, y1) to (x2, y2) on the remote server."""
         if not self.proxy.swipe(x1, y1, x2, y2, duration):
-            raise RuntimeError(f"Failed to swipe from ({x1}, {y1}) to ({x2}, {y2})")
-
-
-if __name__ == "__main__":
-    import argparse
-
-    parser = argparse.ArgumentParser(description="Remote Windows XML-RPC Server")
-    parser.add_argument("--host", default="0.0.0.0", help="Host to bind to")
-    parser.add_argument("--port", type=int, default=8000, help="Port to bind to")
-    args = parser.parse_args()
-
-    logging.basicConfig(level=logging.INFO)
-
-    server = RemoteWindowsServer(args.host, args.port)
-    try:
-        server.start()
-    except KeyboardInterrupt:
-        logger.info("Server stopped by user")
+            raise RuntimeError(f"Failed to swipe from ({x1}, {y1}) to ({x2}, {y2})")

kotonebot/client/implements/uiautomator2.py

@@ -4,6 +4,7 @@ from typing import Literal
 import numpy as np
 import uiautomator2 as u2
 from cv2.typing import MatLike
+from adbutils._device import AdbDevice as AdbUtilsDevice
 
 from kotonebot import logging
 from ..device import Device
@@ -14,9 +15,8 @@ logger = logging.getLogger(__name__)
 SCREENSHOT_INTERVAL = 0.2
 
 class UiAutomator2Impl(Screenshotable, Commandable, Touchable):
-    def __init__(self, device: Device):
-        self.device = device
-        self.u2_client = u2.Device(device.adb.serial)
+    def __init__(self, adb_connection: AdbUtilsDevice):
+        self.u2_client = u2.Device(adb_connection.serial)
         self.__last_screenshot_time = 0
         
     def screenshot(self) -> MatLike:
@@ -38,10 +38,7 @@ class UiAutomator2Impl(Screenshotable, Commandable, Touchable):
     def screen_size(self) -> tuple[int, int]:
         info = self.u2_client.info
         sizes = info['displayWidth'], info['displayHeight']
-        if self.device.orientation == 'landscape':
-            return (max(sizes), min(sizes))
-        else:
-            return (min(sizes), max(sizes))
+        return sizes
     
     def detect_orientation(self) -> Literal['portrait', 'landscape'] | None:
         """
@@ -82,4 +79,4 @@ class UiAutomator2Impl(Screenshotable, Commandable, Touchable):
         """
         滑动屏幕
         """
-        self.u2_client.swipe(x1, y1, x2, y2, duration=duration or 0.1)
+        self.u2_client.swipe(x1, y1, x2, y2, duration=duration or 0.1)

kotonebot/client/implements/windows.py

@@ -2,6 +2,7 @@ from ctypes import windll
 from typing import Literal
 from importlib import resources
 from functools import cached_property
+from dataclasses import dataclass
 
 import cv2
 import win32ui
@@ -10,14 +11,21 @@ import numpy as np
 from ahk import AHK, MsgBoxIcon
 from cv2.typing import MatLike
 
-from ..device import Device
+from ..device import Device, WindowsDevice
 from ..protocol import Commandable, Touchable, Screenshotable
+from ..registration import ImplConfig
+
+# 1. 定义配置模型
+@dataclass
+class WindowsImplConfig(ImplConfig):
+    window_title: str
+    ahk_exe_path: str
 
 class WindowsImpl(Touchable, Screenshotable):
-    def __init__(self, device: Device):
+    def __init__(self, device: Device, window_title: str, ahk_exe_path: str):
         self.__hwnd: int | None = None
-        # TODO: 硬编码路径
-        self.ahk = AHK(executable_path=str(resources.files('kaa.res.bin') / 'AutoHotkey.exe'))
+        self.window_title = window_title
+        self.ahk = AHK(executable_path=ahk_exe_path)
         self.device = device
 
         # 设置 DPI aware，否则高缩放显示器上返回的坐标会错误
@@ -43,21 +51,12 @@ class WindowsImpl(Touchable, Screenshotable):
         # 将点击坐标设置为相对 Client
         self.ahk.set_coord_mode('Mouse', 'Client')
 
-    @cached_property
-    def scale_ratio(self) -> float:
-        """
-        缩放比例。截图与模拟输入前都会根据这个比例缩放。
-        """
-        left, _, right, _ = self.__client_rect()
-        w = right - left
-        return 720 / w
-
     @property
     def hwnd(self) -> int:
         if self.__hwnd is None:
-            self.__hwnd = win32gui.FindWindow(None, 'gakumas')
+            self.__hwnd = win32gui.FindWindow(None, self.window_title)
             if self.__hwnd is None or self.__hwnd == 0:
-                raise RuntimeError('Failed to find window')
+                raise RuntimeError(f'Failed to find window: {self.window_title}')
         return self.__hwnd
 
     def __client_rect(self) -> tuple[int, int, int, int]:
@@ -73,8 +72,8 @@ class WindowsImpl(Touchable, Screenshotable):
         return win32gui.ClientToScreen(hwnd, (x, y))
 
     def screenshot(self) -> MatLike:
-        if not self.ahk.win_is_active('gakumas'):
-            self.ahk.win_activate('gakumas')
+        if not self.ahk.win_is_active(self.window_title):
+            self.ahk.win_activate(self.window_title)
         hwnd = self.hwnd
 
         # TODO: 需要检查下面这些 WinAPI 的返回结果
@@ -116,21 +115,17 @@ class WindowsImpl(Touchable, Screenshotable):
 
         # 将 RGBA 转换为 RGB
         cropped_im = cv2.cvtColor(cropped_im, cv2.COLOR_RGBA2RGB)
-        # 缩放
-        cropped_im = cv2.resize(cropped_im, None, fx=self.scale_ratio, fy=self.scale_ratio)
         return cropped_im
 
     @property
     def screen_size(self) -> tuple[int, int]:
-        # 因为截图和点击的坐标都被缩放了，
-        # 因此这里只要返回固定值即可
-        if self.device.orientation == 'landscape':
-            return 1280, 720
-        else:
-            return 720, 1280
+        left, top, right, bot = self.__client_rect()
+        w = right - left
+        h = bot - top
+        return w, h
 
     def detect_orientation(self) -> None | Literal['portrait'] | Literal['landscape']:
-        pos = self.ahk.win_get_position('gakumas')
+        pos = self.ahk.win_get_position(self.window_title)
         if pos is None:
             return None
         w, h = pos.width, pos.height
@@ -146,25 +141,22 @@ class WindowsImpl(Touchable, Screenshotable):
             x = 2
         if y == 0:
             y = 2
-        x, y = int(x / self.scale_ratio), int(y / self.scale_ratio)
-        if not self.ahk.win_is_active('gakumas'):
-            self.ahk.win_activate('gakumas')
+        if not self.ahk.win_is_active(self.window_title):
+            self.ahk.win_activate(self.window_title)
         self.ahk.click(x, y)
 
     def swipe(self, x1: int, y1: int, x2: int, y2: int, duration: float | None = None) -> None:
-        if not self.ahk.win_is_active('gakumas'):
-            self.ahk.win_activate('gakumas')
-        x1, y1 = int(x1 / self.scale_ratio), int(y1 / self.scale_ratio)
-        x2, y2 = int(x2 / self.scale_ratio), int(y2 / self.scale_ratio)
+        if not self.ahk.win_is_active(self.window_title):
+            self.ahk.win_activate(self.window_title)
         # TODO: 这个 speed 的单位是什么？
         self.ahk.mouse_drag(x2, y2, from_position=(x1, y1), coord_mode='Client', speed=10)
 
-
 if __name__ == '__main__':
     from ..device import Device
-    from time import sleep
     device = Device()
-    impl = WindowsImpl(device)
+    # 在测试环境中直接使用默认路径
+    ahk_path = str(resources.files('kaa.res.bin') / 'AutoHotkey.exe')
+    impl = WindowsImpl(device, window_title='gakumas', ahk_exe_path=ahk_path)
     device._screenshot = impl
     device._touch = impl
     device.swipe_scaled(0.5, 0.8, 0.5, 0.2)

kotonebot/client/protocol.py

@@ -28,6 +28,19 @@ class Commandable(Protocol):
     def launch_app(self, package_name: str) -> None: ...
     def current_package(self) -> str | None: ...
 
+@runtime_checkable
+class AndroidCommandable(Protocol):
+    """定义 Android 平台的特定命令"""
+    def launch_app(self, package_name: str) -> None: ...
+    def current_package(self) -> str | None: ...
+    def adb_shell(self, cmd: str) -> str: ...
+
+@runtime_checkable
+class WindowsCommandable(Protocol):
+    """定义 Windows 平台的特定命令"""
+    def get_foreground_window(self) -> tuple[int, str]: ...
+    def exec_command(self, command: str) -> tuple[int, str, str]: ...
+
 @runtime_checkable
 class Screenshotable(Protocol):
     def __init__(self, device: 'Device'): ...

kotonebot/client/registration.py

@@ -0,0 +1,24 @@
+from dataclasses import dataclass
+from typing import TypeVar, Callable, Dict, Type, Any, overload, Literal, cast, TYPE_CHECKING
+
+from ..errors import KotonebotError
+from .device import Device
+if TYPE_CHECKING:
+    from .implements.adb import AdbImplConfig
+    from .implements.remote_windows import RemoteWindowsImplConfig
+    from .implements.windows import WindowsImplConfig
+    from .implements.nemu_ipc import NemuIpcImplConfig
+
+AdbBasedImpl = Literal['adb', 'adb_raw', 'uiautomator2']
+DeviceImpl = str | AdbBasedImpl | Literal['windows', 'remote_windows', 'nemu_ipc']
+
+# --- 核心类型定义 ---
+
+class ImplRegistrationError(KotonebotError):
+    """与 impl 注册相关的错误"""
+    pass
+
+@dataclass
+class ImplConfig:
+    """所有设备实现配置模型的名义上的基类，便于类型约束。"""
+    pass

kotonebot/config/base_config.py

@@ -3,10 +3,10 @@ from typing import Generic, TypeVar, Literal
 
 from pydantic import BaseModel, ConfigDict
 
-from kotonebot.client.factory import DeviceImpl
 
 T = TypeVar('T')
 BackendType = Literal['custom', 'mumu12', 'leidian', 'dmm']
+DeviceRecipes = Literal['adb', 'adb_raw', 'uiautomator2', 'windows', 'remote_windows', 'nemu_ipc']
 
 class ConfigBaseModel(BaseModel):
     model_config = ConfigDict(use_attribute_docstrings=True)
@@ -27,7 +27,7 @@ class BackendConfig(ConfigBaseModel):
     雷电模拟器需要设置正确的模拟器名，否则 自动启动模拟器 功能将无法正常工作。
     其他功能不受影响。
     """
-    screenshot_impl: DeviceImpl = 'adb'
+    screenshot_impl: DeviceRecipes = 'adb'
     """
     截图方法。暂时推荐使用【adb】截图方式。
 
@@ -44,6 +44,12 @@ class BackendConfig(ConfigBaseModel):
     """模拟器 exe 文件路径"""
     emulator_args: str = ""
     """模拟器启动时的命令行参数"""
+    windows_window_title: str = 'gakumas'
+    """Windows 截图方式的窗口标题"""
+    windows_ahk_path: str | None = None
+    """Windows 截图方式的 AutoHotkey 可执行文件路径，为 None 时使用默认路径"""
+    mumu_background_mode: bool = False
+    """MuMu12 模拟器后台保活模式"""
 
 class PushConfig(ConfigBaseModel):
     """推送配置。"""

kotonebot/debug_entry.py

@@ -1,3 +1,5 @@
+import sys
+sys.path.append('./projects')
 import runpy
 import logging
 import argparse
@@ -12,15 +14,20 @@ def run_script(script_path: str) -> None:
     Args:
         script_path: Python 脚本的路径
     """
+    logging.basicConfig(level=logging.INFO, format='[%(asctime)s] [%(levelname)s] [%(name)s] [%(funcName)s] [%(lineno)d] %(message)s')
     # 获取模块名
-    module_name = script_path.strip('.py').replace('\\', '/').strip('/').replace('/', '.')
+    module_name = script_path.strip('.py').lstrip('projects/').replace('\\', '/').strip('/').replace('/', '.')
 
     print(f"正在运行脚本: {script_path}")
     # 运行脚本
-    from kotonebot.backend.context import init_context
-    logging.basicConfig(level=logging.INFO, format='[%(asctime)s] [%(levelname)s] [%(name)s] [%(funcName)s] [%(lineno)d] %(message)s')
+    from kotonebot.backend.context import init_context, manual_context
+    from kotonebot.kaa.main.kaa import Kaa
     logging.getLogger('kotonebot').setLevel(logging.DEBUG)
-    init_context(config_type=BaseConfig)
+    config_path = './config.json'
+    kaa_instance = Kaa(config_path)
+    init_context(config_type=BaseConfig, target_device=kaa_instance._on_create_device())
+    kaa_instance._on_after_init_context()
+    manual_context().begin()
     runpy.run_module(module_name, run_name="__main__")
 
 def main():

kotonebot/errors.py

@@ -24,3 +24,10 @@ class TaskNotFoundError(KotonebotError):
     def __init__(self, task_id: str):
         self.task_id = task_id
         super().__init__(f'Task "{task_id}" not found.')
+
+class UnscalableResolutionError(KotonebotError):
+    def __init__(self, target_resolution: tuple[int, int], screen_size: tuple[int, int]):
+        self.target_resolution = target_resolution
+        self.screen_size = screen_size
+        super().__init__(f'Cannot scale to target resolution {target_resolution}. '
+                         f'Screen size: {screen_size}')