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

kotonebot/kaa/game_ui/common.py

@@ -2,10 +2,10 @@ import cv2
 import numpy as np
 from cv2.typing import MatLike
 
-from kotonebot import action, color, image
-from kotonebot.backend.color import HsvColor
-from kotonebot.primitives import RectTuple, Rect
+from kotonebot.primitives import Rect
 from kotonebot.backend.core import Image
+from kotonebot.backend.color import HsvColor
+from kotonebot import action, color, image, device
 from kotonebot.backend.preprocessor import HsvColorFilter
 
 
@@ -88,7 +88,4 @@ class WhiteFilter(HsvColorFilter):
 
 
 if __name__ == '__main__':
-    from kotonebot.backend.context import init_context, manual_context, device
-
-    init_context()
-    manual_context().begin()
+    pass

kotonebot/kaa/game_ui/dialog.py

@@ -1,45 +1,65 @@
+import logging
+
 from kotonebot.kaa.tasks import R
 from kotonebot import device, image
 
-def expect_yes():
+logger = logging.getLogger(__name__)
+
+def expect_yes(*, msg: str | None = None):
     """
     点击对话框上的✔️按钮。若不存在，会等待其出现，直至超时异常。
     
     前置条件：当前打开了任意对话框\n
     结束状态：点击了肯定意义按钮（✔️图标，橙色背景）后瞬间
+
+    :param msg: 成功点击后输出的日志信息。信息中的动词建议使用过去式。
     """
     device.click(image.expect(R.Common.IconButtonCheck))
+    if msg is not None:
+        logger.debug(msg)
 
-def yes() -> bool:
+def yes(*, msg: str | None = None) -> bool:
     """
     点击对话框上的✔️按钮。
 
     前置条件：当前打开了任意对话框\n
     结束状态：点击了肯定意义按钮（✔️图标，橙色背景）后瞬间
+
+    :param msg: 成功点击后输出的日志信息。信息中的动词建议使用过去式。
     """
     if image.find(R.Common.IconButtonCheck):
         device.click()
+        if msg is not None:
+            logger.debug(msg)
         return True
     return False
 
-def expect_no():
+def expect_no(*, msg: str | None = None):
     """
     点击对话框上的✖️按钮。若不存在，会等待其出现，直至超时异常。
     
     前置条件：当前打开了任意对话框\n
     结束状态：点击了否定意义按钮（✖️图标，白色背景）后瞬间
+
+    :param msg: 成功点击后输出的日志信息。信息中的动词建议使用过去式。
     """
     device.click(image.expect(R.Common.IconButtonCross))
+    if msg is not None:
+        logger.debug(msg)
 
-def no():
+def no(*, msg: str | None = None):
     """
     点击对话框上的✖️按钮。
 
     前置条件：当前打开了任意对话框\n
     结束状态：点击了否定意义按钮（✖️图标，白色背景）后瞬间
+
+    :param msg: 成功点击后输出的日志信息。信息中的动词建议使用过去式。
     """
     if image.find(R.Common.IconButtonCross):
         device.click()
+        if msg is not None:
+            logger.debug(msg)
         return True
     return False
 

kotonebot/kaa/game_ui/idols_overview.py

@@ -10,7 +10,8 @@ from kotonebot.kaa.util import paths
 from kotonebot.primitives import RectTuple, Rect
 from kotonebot.kaa.game_ui import Scrollable
 from kotonebot import device, action
-from kotonebot.kaa.image_db import ImageDatabase, HistDescriptor, FileDataSource
+from kotonebot.util import cv2_imread
+from kotonebot.kaa.image_db import ImageDatabase, HistDescriptor, FileDataSource, DatabaseQueryResult
 from kotonebot.backend.preprocessor import HsvColorsRemover
 
 logger = logging.getLogger(__name__)
@@ -106,8 +107,32 @@ def idols_db() -> ImageDatabase:
         _db = ImageDatabase(FileDataSource(str(path)), db_path, HistDescriptor(8), name='idols')
     return _db
 
+def match_idol(skin_id: str, idol_img: MatLike) -> DatabaseQueryResult | None:
+    """
+    将给定图像与指定偶像 ID 进行匹配。
+
+    :param skin_id: 偶像 ID。
+    :param idol_img: 待匹配偶像图像。
+    :return: 若匹配成功，则返回匹配结果，否则返回 None。
+    """
+    db = idols_db()
+    match = db.match(idol_img, 20)
+    if match and match.key.startswith(skin_id):
+        return match
+    else:
+        return None
+
 @action('定位偶像', screenshot_mode='manual-inherit')
-def locate_idol(skin_id: str):
+def locate_idol(skin_id: str) -> Rect | None:
+    """
+    定位并选中指定偶像。
+
+    前置条件：位于偶像总览界面。\n
+    结束状态：位于偶像总览界面。
+
+    :param skin_id: 目标偶像的 Skin ID
+    :return: 若成功，返回目标偶像的范围 (x, y, w, h)，否则返回 None。
+    """
     device.screenshot()
     logger.info('Locating idol %s', skin_id)
     x, y, w, h = R.Produce.BoxIdolOverviewIdols.xywh
@@ -146,15 +171,6 @@ def locate_idol(skin_id: str):
 
     # # 使用新函数绘制预览图
     # preview_img = draw_idol_preview(img, rects, db, path)
-    
-
-def test():
-    from kotonebot.backend.context import init_context, manual_context
-    init_context()
-    manual_context().begin()
-    locate_idol('i_card-skin-fktn-3-006')
 
 if __name__ == '__main__':
-    from kotonebot.util import cv2_imread
-
-    test()
+    locate_idol('i_card-skin-fktn-3-006')

kotonebot/kaa/game_ui/primary_button.py

@@ -0,0 +1,55 @@
+import cv2
+import numpy as np
+from typing import Optional
+from cv2.typing import MatLike
+
+from kotonebot import action, image, device
+from kotonebot.backend.core import Image
+from kotonebot.backend.image import TemplateMatchResult
+
+
+def primary_button_state(img: MatLike) -> Optional[bool]:
+    """
+    分析按钮图像并根据红色通道直方图返回按钮状态
+
+    :param img: 输入的按钮图像 (BGR格式)
+    :return: True - 启用状态
+             False - 禁用状态
+             None - 未知状态或输入无效
+    """
+    # 确保图像有效
+    if img is None or img.size == 0:
+        return None
+
+    # 计算红色通道直方图（五箱）
+    _, _, r = cv2.split(img)
+    hist = cv2.calcHist([r], [0], None, [5], [0, 256])
+    # 归一化并找出红色集中在哪一箱
+    hist = hist.ravel() / hist.sum()
+    max_idx = np.argmax(hist)
+
+    if max_idx == 3:
+        return False
+    elif max_idx == 4:
+        return True
+    else:
+        return None
+
+@action('寻找按钮', screenshot_mode='manual-inherit')
+def find_button(template: MatLike | Image, state: Optional[bool] = None) -> Optional[bool]:
+    """
+    在图像中寻找按钮并返回其状态
+
+    :param template: 按钮模板图像 (BGR格式)
+    :param state: 按钮状态 (True - 启用, False - 禁用, None - 任意)
+    :return: True - 启用状态
+             False - 禁用状态
+             None - 未找到按钮或状态未知
+    """
+    img = device.screenshot()
+    result = image.find(template)
+    if result is None:
+        return None
+    x, y, w, h = result.rect.xywh
+    button_img = img[y:y+h, x:x+w]
+    return primary_button_state(button_img)

kotonebot/kaa/game_ui/scrollable.py

@@ -327,12 +327,7 @@ class Scrollable:
         return ScrollableIterator(self, int(self.track_height * step), start, end, skip_first)
 
 if __name__ == '__main__':
-    from kotonebot.backend.context import init_context, manual_context, device
-    init_context()
-    manual_context().begin()
-    from kotonebot import device
     import cv2
-    from kotonebot.util import cv2_imread
     import time
     logger.setLevel(logging.DEBUG)
 

kotonebot/kaa/main/cli.py

@@ -1,13 +1,15 @@
 import os
 import sys
-import runpy
 import logging
 import argparse
 import importlib.metadata
 from datetime import datetime
 
 from .kaa import Kaa
+from ..util.paths import get_ahk_path
+from kotonebot.client.implements.windows import WindowsImplConfig
 from kotonebot.backend.context import tasks_from_id, task_registry
+from kotonebot.client.implements.remote_windows import RemoteWindowsServer
 
 version = importlib.metadata.version('ksaa')
 
@@ -90,9 +92,12 @@ def task_list() -> int:
 def remote_server() -> int:
     args = psr.parse_args()
     try:
-        # 使用runpy运行remote_windows.py模块
-        sys.argv = ['remote_windows.py', f'--host={args.host}', f'--port={args.port}']
-        runpy.run_module('kotonebot.client.implements.remote_windows', run_name='__main__')
+        ahk_path = get_ahk_path()
+        server = RemoteWindowsServer(WindowsImplConfig(window_title='gakumas', ahk_exe_path=ahk_path), args.host, args.port)
+        server.start()
+        return 0
+    except KeyboardInterrupt:
+        print("Server stopped by user")
         return 0
     except Exception as e:
         print(f'Error starting remote server: {e}')

kotonebot/kaa/main/dmm_host.py

@@ -1,11 +1,18 @@
+from importlib import resources
 from typing_extensions import override
 
-from kotonebot.client import Device, create_device
-from kotonebot.client import DeviceImpl, Device
+from kotonebot.client import Device, DeviceImpl
+from kotonebot.client.registration import create_device
+from kotonebot.client.implements.windows import WindowsImplConfig
+from kotonebot.client.implements.remote_windows import RemoteWindowsImplConfig
 from kotonebot.client.host import HostProtocol, Instance
+from kotonebot.client.host.protocol import WindowsHostConfig, RemoteWindowsHostConfig
+
+
+DmmHostConfigs = WindowsHostConfig | RemoteWindowsHostConfig
 
 # TODO: 可能应该把 start_game 和 end_game 里对启停的操作移动到这里来
-class DmmInstance(Instance):
+class DmmInstance(Instance[DmmHostConfigs]):
     def __init__(self):
         super().__init__('dmm', 'gakumas')
 
@@ -30,10 +37,29 @@ class DmmInstance(Instance):
         raise NotImplementedError()
 
     @override
-    def create_device(self, impl: DeviceImpl, *, timeout: float = 180) -> Device:
-        if impl not in ['windows', 'remote_windows']:
-            raise ValueError(f'Unsupported device implementation: {impl}')
-        return create_device('', impl, timeout=timeout)
+    def create_device(self, impl: DeviceImpl, host_config: DmmHostConfigs) -> Device:
+        if impl == 'windows':
+            assert isinstance(host_config, WindowsHostConfig)
+            win_config = WindowsImplConfig(
+                window_title=host_config.window_title,
+                ahk_exe_path=host_config.ahk_exe_path
+            )
+            return create_device(impl, win_config)
+
+        elif impl == 'remote_windows':
+            assert isinstance(host_config, RemoteWindowsHostConfig)
+            config = RemoteWindowsImplConfig(
+                windows_impl_config=WindowsImplConfig(
+                    window_title=host_config.windows_host_config.window_title,
+                    ahk_exe_path=host_config.windows_host_config.ahk_exe_path
+                ),
+                host=host_config.host,
+                port=host_config.port
+            )
+            return create_device(impl, config)
+
+        else:
+            raise ValueError(f'Unsupported impl for DMM: {impl}')
 
 class DmmHost(HostProtocol):
     instance = DmmInstance()

kotonebot/kaa/main/kaa.py

@@ -1,21 +1,30 @@
 import io
 import os
+import zipfile
 import logging
-import importlib.metadata
 import traceback
-import zipfile
+import importlib.metadata
 from datetime import datetime
+from typing_extensions import override
 
 import cv2
-from typing_extensions import override
 
-from .dmm_host import DmmHost
 from ...client import Device
 from kotonebot.ui import user
 from kotonebot import KotoneBot
+from ..util.paths import get_ahk_path
 from ..kaa_context import _set_instance
+from .dmm_host import DmmHost, DmmInstance
 from ..common import BaseConfig, upgrade_config
-from kotonebot.client.host import Mumu12Host, LeidianHost
+from kotonebot.config.base_config import UserConfig
+from kotonebot.client.host import (
+    Mumu12Host, LeidianHost, Mumu12Instance,
+    LeidianInstance, CustomInstance
+)
+from kotonebot.client.host.protocol import (
+    Instance, AdbHostConfig, WindowsHostConfig,
+    RemoteWindowsHostConfig
+)
 
 # 初始化日志
 log_formatter = logging.Formatter('[%(asctime)s][%(levelname)s][%(name)s] %(message)s')
@@ -104,23 +113,27 @@ class Kaa(KotoneBot):
             raise ValueError('Backend instance is not set.')
         _set_instance(self.backend_instance)
 
-    @override
-    def _on_create_device(self) -> Device:
+    def __get_backend_instance(self, config: UserConfig) -> Instance:
+        """
+        根据配置获取或创建 Instance。
+
+        :param config: 用户配置对象
+        :return: 后端实例
+        """
         from kotonebot.client.host import create_custom
-        from kotonebot.config.manager import load_config
-        # HACK: 硬编码
-        config = load_config(self.config_path, type=self.config_type)
-        config = config.user_configs[0]
-        logger.info('Checking backend...')
+
+        logger.info(f'Querying for backend: {config.backend.type}')
+
         if config.backend.type == 'custom':
             exe = config.backend.emulator_path
-            self.backend_instance = create_custom(
+            instance = create_custom(
                 adb_ip=config.backend.adb_ip,
                 adb_port=config.backend.adb_port,
                 adb_name=config.backend.adb_emulator_name,
                 exe_path=exe,
                 emulator_args=config.backend.emulator_args
             )
+            # 对于 custom 类型，需要额外验证模拟器路径
             if config.backend.check_emulator:
                 if exe is None:
                     user.error('「检查并启动模拟器」已开启但未配置「模拟器 exe 文件路径」。')
@@ -128,42 +141,101 @@ class Kaa(KotoneBot):
                 if not os.path.exists(exe):
                     user.error('「模拟器 exe 文件路径」对应的文件不存在！请检查路径是否正确。')
                     raise FileNotFoundError(f'Emulator executable not found: {exe}')
-                if not self.backend_instance.running():
-                    logger.info('Starting custom backend...')
-                    self.backend_instance.start()
-                    logger.info('Waiting for custom backend to be available...')
-                    self.backend_instance.wait_available()
-                else:
-                    logger.info('Custom backend "%s" already running.', self.backend_instance)
+            return instance
+
         elif config.backend.type == 'mumu12':
             if config.backend.instance_id is None:
                 raise ValueError('MuMu12 instance ID is not set.')
-            self.backend_instance = Mumu12Host.query(id=config.backend.instance_id)
-            if self.backend_instance is None:
+            instance = Mumu12Host.query(id=config.backend.instance_id)
+            if instance is None:
                 raise ValueError(f'MuMu12 instance not found: {config.backend.instance_id}')
-            if not self.backend_instance.running():
-                logger.info('Starting MuMu12 backend...')
-                self.backend_instance.start()
-                logger.info('Waiting for MuMu12 backend to be available...')
-                self.backend_instance.wait_available()
-            else:
-                logger.info('MuMu12 backend "%s" already running.', self.backend_instance)
+            return instance
+
         elif config.backend.type == 'leidian':
             if config.backend.instance_id is None:
                 raise ValueError('Leidian instance ID is not set.')
-            self.backend_instance = LeidianHost.query(id=config.backend.instance_id)
-            if self.backend_instance is None:
+            instance = LeidianHost.query(id=config.backend.instance_id)
+            if instance is None:
                 raise ValueError(f'Leidian instance not found: {config.backend.instance_id}')
-            if not self.backend_instance.running():
-                logger.info('Starting Leidian backend...')
-                self.backend_instance.start()
-                logger.info('Waiting for Leidian backend to be available...')
-                self.backend_instance.wait_available()
-            else:
-                logger.info('Leidian backend "%s" already running.', self.backend_instance)
+            return instance
+
         elif config.backend.type == 'dmm':
-            self.backend_instance = DmmHost.instance
+            return DmmHost.instance
+
         else:
             raise ValueError(f'Unsupported backend type: {config.backend.type}')
-        assert self.backend_instance is not None, 'Backend instance is not set.'
-        return self.backend_instance.create_device(config.backend.screenshot_impl)
+
+    def __ensure_instance_running(self, instance: Instance, config: UserConfig):
+        """
+        确保 Instance 正在运行。
+
+        :param instance: 后端实例
+        :param config: 用户配置对象
+        """
+        # DMM 实例不需要启动，直接返回
+        if isinstance(instance, DmmInstance):
+            logger.info('DMM backend does not require startup.')
+            return
+
+        # 对所有需要启动的后端（custom, mumu, leidian）使用统一逻辑
+        if config.backend.check_emulator and not instance.running():
+            logger.info(f'Starting backend "{instance}"...')
+            instance.start()
+            logger.info(f'Waiting for backend "{instance}" to be available...')
+            instance.wait_available()
+        else:
+            logger.info(f'Backend "{instance}" already running or check is disabled.')
+
+    @override
+    def _on_create_device(self) -> Device:
+        """
+        创建设备。
+        """
+        from kotonebot.config.manager import load_config
+
+        # 步骤1：加载配置
+        config = load_config(self.config_path, type=self.config_type)
+        user_config = config.user_configs[0]  # HACK: 硬编码
+
+        # 步骤2：获取实例
+        self.backend_instance = self.__get_backend_instance(user_config)
+        if self.backend_instance is None:
+            raise RuntimeError(f"Failed to find instance for backend '{user_config.backend.type}'")
+
+        # 步骤3：确保实例运行
+        self.__ensure_instance_running(self.backend_instance, user_config)
+
+        # 步骤4：准备 HostConfig 并创建 Device
+        impl_name = user_config.backend.screenshot_impl
+
+        if isinstance(self.backend_instance, DmmInstance):
+            if impl_name == 'windows':
+                ahk_path = get_ahk_path()
+                host_conf = WindowsHostConfig(
+                    window_title='gakumas',
+                    ahk_exe_path=ahk_path
+                )
+            elif impl_name == 'remote_windows':
+                ahk_path = get_ahk_path()
+                host_conf = RemoteWindowsHostConfig(
+                    windows_host_config=WindowsHostConfig(
+                        window_title='gakumas',
+                        ahk_exe_path=ahk_path
+                    ),
+                    host=user_config.backend.adb_ip,
+                    port=user_config.backend.adb_port
+                )
+            else:
+                raise ValueError(f"Impl of '{impl_name}' is not supported on DMM.")
+            return self.backend_instance.create_device(impl_name, host_conf)
+
+        # 统一处理所有基于 ADB 的后端
+        elif isinstance(self.backend_instance, (CustomInstance, Mumu12Instance, LeidianInstance)):
+            if impl_name in ['adb', 'adb_raw', 'uiautomator2']:
+                host_conf = AdbHostConfig(timeout=180)
+                return self.backend_instance.create_device(impl_name, host_conf)
+            else:
+                raise ValueError(f"{user_config.backend.type} backend does not support implementation '{impl_name}'")
+
+        else:
+            raise TypeError(f"Unknown instance type: {type(self.backend_instance)}")

kotonebot/kaa/metadata.py

@@ -1,6 +1,21 @@
 WHATS_NEW = """
 # 更新日志
 ## kaa
+### v2025.6.23.0
+脚本：
+* [新增] 优化了培育开始的逻辑，修复若干 bug（#86313ec）
+
+框架：
+* [修复] 修复由于分离 AndroidDevice 方法导致的 typing 问题（#4d76e1a）
+* [重构] 将 Commandable 分离为 WindowsCommandable 与 AndroidCommandable（#16a267d）
+* [重构] 将启动 remote_server 的逻辑移动到 kaa cli 中（#b8b5ba8）
+* [重构] 提取三个 adb-based 截图方法的工厂函数的共同部分（#bd57dc4）
+* [重构] 将创建设备的逻辑从 init_context 中移除（#f2599e6）
+* [重构] 重构 Device 与 Impl 的创建方式（#2fc9ad5）
+
+其他：
+* [其他] 更新上游 submodules（#810c341）
+
 ### v2025.6.8.0
 脚本：
 * [新增] 新增支持自动禁用与恢复 Gakumasu Localify 汉化插件（#264dac2）