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

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 register_impl, 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}")
@@ -66,3 +83,46 @@ class AdbImpl(Commandable, Touchable, Screenshotable):
         if duration is not None:
             logger.warning("Swipe duration is not supported with AdbDevice. Ignoring duration.")
         self.adb.shell(f"input touchscreen swipe {x1} {y1} {x2} {y2}")
+
+
+def _create_adb_device_base(config: AdbImplConfig, impl_class: type) -> AndroidDevice:
+    """
+    通用的 ADB 设备创建工厂函数。
+    其他任意基于 ADB 的 Impl 可以直接复用这个函数。
+
+    :param config: ADB 实现配置
+    :param impl_class: 实现类或工厂函数。构造函数接收 adb_connection 参数。
+    """
+    from adbutils import adb
+
+    if config.disconnect:
+        logger.debug('adb disconnect %s', config.addr)
+        adb.disconnect(config.addr)
+    if config.connect:
+        logger.debug('adb connect %s', config.addr)
+        result = adb.connect(config.addr)
+        if 'cannot connect to' in result:
+            raise ValueError(result)
+    serial = config.device_serial or config.addr
+    logger.debug('adb wait for %s', serial)
+    adb.wait_for(serial, timeout=config.timeout)
+    devices = adb.device_list()
+    logger.debug('adb device_list: %s', devices)
+    d = [d for d in devices if d.serial == serial]
+    if len(d) == 0:
+        raise ValueError(f"Device {config.addr} not found")
+    d = d[0]
+
+    device = AndroidDevice(d)
+    impl = impl_class(d)
+    device._touch = impl
+    device._screenshot = impl
+    device.commands = impl
+
+    return device
+
+
+@register_impl('adb', config_model=AdbImplConfig)
+def create_adb_device(config: AdbImplConfig) -> AndroidDevice:
+    """AdbImpl 工厂函数"""
+    return _create_adb_device_base(config, AdbImpl)

kotonebot/client/implements/adb_raw.py

@@ -11,8 +11,9 @@ import numpy as np
 from cv2.typing import MatLike
 from adbutils._utils import adb_path
 
-from .adb import AdbImpl
-from ..device import Device
+from .adb import AdbImpl, AdbImplConfig, _create_adb_device_base
+from adbutils._device import AdbDevice as AdbUtilsDevice
+from ..registration import register_impl
 from kotonebot import logging
 
 logger = logging.getLogger(__name__)
@@ -27,8 +28,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
@@ -156,4 +157,10 @@ class AdbRawImpl(AdbImpl):
         logger.verbose(f"adb raw screenshot wait time: {time.time() - start_time:.4f}s")
         data = self.__data
         self.__data = None
-        return data
+        return data
+
+
+@register_impl('adb_raw', config_model=AdbImplConfig)
+def create_adb_raw_device(config: AdbImplConfig):
+    """AdbRawImpl 工厂函数"""
+    return _create_adb_device_base(config, AdbRawImpl)

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 register_impl, ImplConfig
+from .windows import WindowsImpl, WindowsImplConfig, create_windows_device
 
 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,13 @@ 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 = create_windows_device(windows_impl_config)
         self.device._screenshot = self.impl
         self.device._touch = self.impl
 
@@ -180,18 +189,11 @@ class RemoteWindowsImpl(Touchable, Screenshotable):
             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")
+# 编写并注册创建函数
+@register_impl('remote_windows', config_model=RemoteWindowsImplConfig)
+def create_remote_windows_device(config: RemoteWindowsImplConfig) -> Device:
+    device = WindowsDevice()
+    remote_impl = RemoteWindowsImpl(device, config.host, config.port)
+    device._touch = remote_impl
+    device._screenshot = remote_impl
+    return device

kotonebot/client/implements/uiautomator2.py

@@ -8,6 +8,8 @@ from cv2.typing import MatLike
 from kotonebot import logging
 from ..device import Device
 from ..protocol import Screenshotable, Commandable, Touchable
+from ..registration import register_impl
+from .adb import AdbImplConfig, _create_adb_device_base
 
 logger = logging.getLogger(__name__)
 
@@ -83,3 +85,9 @@ class UiAutomator2Impl(Screenshotable, Commandable, Touchable):
         滑动屏幕
         """
         self.u2_client.swipe(x1, y1, x2, y2, duration=duration or 0.1)
+
+
+@register_impl('uiautomator2', config_model=AdbImplConfig)
+def create_uiautomator2_device(config: AdbImplConfig) -> Device:
+    """UiAutomator2Impl 工厂函数"""
+    return _create_adb_device_base(config, UiAutomator2Impl)

kotonebot/client/implements/windows.py

@@ -2,31 +2,51 @@ 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
 import win32gui
 import numpy as np
-from ahk import AHK
+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 register_impl, 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
-        self.emergency = False
 
         # 设置 DPI aware，否则高缩放显示器上返回的坐标会错误
         windll.user32.SetProcessDPIAware()
-        def toggle_emergency():
-            self.emergency = True
-            self.ahk.msg_box('已启用紧急暂停模式')
-        self.ahk.add_hotkey('^F4', toggle_emergency)
+        # TODO: 这个应该移动到其他地方去
+        def _stop():
+            from kotonebot.backend.context.context import vars
+            vars.flow.request_interrupt()
+            self.ahk.msg_box('任务已停止。', title='琴音小助手', icon=MsgBoxIcon.EXCLAMATION)
+
+        def _toggle_pause():
+            from kotonebot.backend.context.context import vars
+            if vars.flow.is_paused:
+                self.ahk.msg_box('任务即将恢复。\n关闭此消息框后将会继续执行', title='琴音小助手', icon=MsgBoxIcon.EXCLAMATION)
+                vars.flow.request_resume()
+            else:
+                vars.flow.request_pause()
+                self.ahk.msg_box('任务已暂停。\n关闭此消息框后再按一次快捷键恢复执行。', title='琴音小助手', icon=MsgBoxIcon.EXCLAMATION)
+
+        self.ahk.add_hotkey('^F4', _toggle_pause) # Ctrl+F4 暂停/恢复
+        self.ahk.add_hotkey('^F3', _stop)  # Ctrl+F3 停止
         self.ahk.start_hotkeys()
         # 将点击坐标设置为相对 Client
         self.ahk.set_coord_mode('Mouse', 'Client')
@@ -43,9 +63,9 @@ class WindowsImpl(Touchable, Screenshotable):
     @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]:
@@ -60,14 +80,9 @@ class WindowsImpl(Touchable, Screenshotable):
         """将 Client 区域坐标转换为屏幕坐标"""
         return win32gui.ClientToScreen(hwnd, (x, y))
 
-    def __wait_not_emergency(self):
-        from time import sleep # TODO: 改为 kotonebot.backend.context.sleep
-        while self.emergency:
-            sleep(0.2)
-
     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 的返回结果
@@ -123,7 +138,7 @@ class WindowsImpl(Touchable, Screenshotable):
             return 720, 1280
 
     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
@@ -133,7 +148,6 @@ class WindowsImpl(Touchable, Screenshotable):
             return 'portrait'
 
     def click(self, x: int, y: int) -> None:
-        self.__wait_not_emergency()
         # x, y = self.__client_to_screen(self.hwnd, x, y)
         # (0, 0) 很可能会点到窗口边框上
         if x == 0:
@@ -141,25 +155,39 @@ class WindowsImpl(Touchable, Screenshotable):
         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:
-        self.__wait_not_emergency()
-        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)
         x1, y1 = int(x1 / self.scale_ratio), int(y1 / self.scale_ratio)
         x2, y2 = int(x2 / self.scale_ratio), int(y2 / self.scale_ratio)
         # TODO: 这个 speed 的单位是什么？
         self.ahk.mouse_drag(x2, y2, from_position=(x1, y1), coord_mode='Client', speed=10)
 
 
+# 3. 编写并注册创建函数
+@register_impl('windows', config_model=WindowsImplConfig)
+def create_windows_device(config: WindowsImplConfig) -> Device:
+    device = WindowsDevice()
+    impl = WindowsImpl(
+        device,
+        window_title=config.window_title,
+        ahk_exe_path=config.ahk_exe_path
+    )
+    device._touch = impl
+    device._screenshot = impl
+    return device
+
+
 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,89 @@
+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
+
+AdbBasedImpl = Literal['adb', 'adb_raw', 'uiautomator2']
+DeviceImpl = str | AdbBasedImpl | Literal['windows', 'remote_windows']
+
+# --- 核心类型定义 ---
+
+class ImplRegistrationError(KotonebotError):
+    """与 impl 注册相关的错误"""
+    pass
+
+@dataclass
+class ImplConfig:
+    """所有设备实现配置模型的名义上的基类，便于类型约束。"""
+    pass
+
+T_Config = TypeVar("T_Config", bound=ImplConfig)
+
+# 定义两种创建者函数类型
+CreatorWithConfig = Callable[[Any], Device]
+CreatorWithoutConfig = Callable[[], Device]
+
+# --- 底层 API: 公开的注册表 ---
+
+# 注册表结构: {'impl_name': (创建函数, 配置模型类 或 None)}
+DEVICE_CREATORS: Dict[str, tuple[Callable[..., Device], Type[ImplConfig] | None]] = {}
+
+
+def register_impl(name: str, config_model: Type[ImplConfig] | None = None) -> Callable[..., Any]:
+    """
+    一个统一的装饰器，用于向 DEVICE_CREATORS 注册表中注册一个设备实现。
+
+    :param name: 实现的名称 (e.g., 'windows', 'adb')
+    :param config_model: (可选) 与该实现关联的 dataclass 配置模型
+    """
+    def decorator(creator_func: Callable[..., Device]) -> Callable[..., Device]:
+        if name in DEVICE_CREATORS:
+            raise ImplRegistrationError(f"实现 '{name}' 已被注册。")
+        DEVICE_CREATORS[name] = (creator_func, config_model)
+        return creator_func
+    return decorator
+
+
+# --- 高层 API: 带 overload 的便利函数 ---
+
+# 为需要配置的已知 impl 提供 overload
+@overload
+def create_device(impl_name: Literal['windows'], config: 'WindowsImplConfig') -> Device: ...
+
+@overload
+def create_device(impl_name: Literal['remote_windows'], config: 'RemoteWindowsImplConfig') -> Device: ...
+
+@overload
+def create_device(impl_name: AdbBasedImpl, config: 'AdbImplConfig') -> Device: ...
+
+# 函数的实际实现
+def create_device(impl_name: DeviceImpl, config: ImplConfig | None = None) -> Device:
+    """
+    根据名称和可选的配置对象，统一创建设备。
+    """
+    creator_tuple = DEVICE_CREATORS.get(impl_name)
+    if not creator_tuple:
+        raise ImplRegistrationError(f"未找到名为 '{impl_name}' 的实现。")
+
+    creator_func, registered_config_model = creator_tuple
+
+    # 情况 A: 实现需要配置
+    if registered_config_model is not None:
+        creator_with_config = cast(CreatorWithConfig, creator_func)
+        if config is None:
+            raise ValueError(f"实现 '{impl_name}' 需要一个配置对象，但传入的是 None。")
+        if not isinstance(config, registered_config_model):
+            raise TypeError(f"为 '{impl_name}' 传入的配置类型错误，应为 '{registered_config_model.__name__}'，实际为 '{type(config).__name__}'。")
+        return creator_with_config(config)
+    
+    # 情况 B: 实现无需配置
+    else:
+        creator_without_config = cast(CreatorWithoutConfig, creator_func)
+        if config is not None:
+            print(f"提示：实现 '{impl_name}' 无需配置，但你提供了一个配置对象，它将被忽略。")
+        return creator_without_config()

kotonebot/config/base_config.py

@@ -3,7 +3,7 @@ from typing import Generic, TypeVar, Literal
 
 from pydantic import BaseModel, ConfigDict
 
-from kotonebot.client.factory import DeviceImpl
+from kotonebot.client import DeviceImpl
 
 T = TypeVar('T')
 BackendType = Literal['custom', 'mumu12', 'leidian', 'dmm']
@@ -44,6 +44,10 @@ class BackendConfig(ConfigBaseModel):
     """模拟器 exe 文件路径"""
     emulator_args: str = ""
     """模拟器启动时的命令行参数"""
+    windows_window_title: str = 'gakumas'
+    """Windows 截图方式的窗口标题"""
+    windows_ahk_path: str | None = None
+    """Windows 截图方式的 AutoHotkey 可执行文件路径，为 None 时使用默认路径"""
 
 class PushConfig(ConfigBaseModel):
     """推送配置。"""

kotonebot/debug_entry.py

@@ -17,10 +17,15 @@ def run_script(script_path: str) -> None:
 
     print(f"正在运行脚本: {script_path}")
     # 运行脚本
-    from kotonebot.backend.context import init_context
+    from kotonebot.backend.context import init_context, manual_context
+    from kotonebot.kaa.main.kaa import Kaa
     logging.basicConfig(level=logging.INFO, format='[%(asctime)s] [%(levelname)s] [%(name)s] [%(funcName)s] [%(lineno)d] %(message)s')
     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/kaa/clear_logs.py

@@ -28,7 +28,4 @@ def clear_logs():
     logger.info('Clearing logs done.')
 
 if __name__ == '__main__':
-    from kotonebot.backend.context import init_context, manual_context
-    init_context()
-    manual_context().begin()
     clear_logs()

kotonebot/kaa/common.py

@@ -425,6 +425,20 @@ class StartGameConfig(ConfigBaseModel):
 
     kuyo_package_name: str = 'org.kuyo.game'
     """Kuyo包名"""
+    
+    disable_gakumas_localify: bool = False
+    """
+    自动检测并禁用 Gakumas Localify 汉化插件。
+    
+    （目前仅对 DMM 版有效。）
+    """
+    
+    dmm_game_path: str | None = None
+    """
+    DMM 版游戏路径。若不填写，会自动检测。
+    
+    例：`F:\\Games\\gakumas\\gakumas.exe`
+    """
 
 class EndGameConfig(ConfigBaseModel):
     exit_kaa: bool = False
@@ -439,6 +453,13 @@ class EndGameConfig(ConfigBaseModel):
     """关闭系统"""
     hibernate: bool = False
     """休眠系统"""
+    restore_gakumas_localify: bool = False
+    """
+    恢复 Gakumas Localify 汉化插件状态至启动前。通常与
+    `disable_gakumas_localify` 配对使用。
+    
+    （目前仅对 DMM 版有效。）
+    """
 
 class BaseConfig(ConfigBaseModel):
     purchase: PurchaseConfig = PurchaseConfig()

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