kotonebot 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

kotonebot/backend/bot.py

@@ -13,7 +13,16 @@ from kotonebot.client.host.protocol import Instance
 from kotonebot.backend.context import init_context, vars
 from kotonebot.backend.context import task_registry, action_registry, Task, Action
 from kotonebot.errors import StopCurrentTask, UserFriendlyError
-from kotonebot.interop.win.task_dialog import TaskDialog
+from kotonebot.util import is_windows
+
+# 条件导入 TaskDialog（仅在 Windows 上）
+if is_windows():
+    try:
+        from kotonebot.interop.win.task_dialog import TaskDialog
+    except ImportError:
+        TaskDialog = None
+else:
+    TaskDialog = None
 
 
 @dataclass
@@ -226,19 +235,20 @@ class KotoneBot:
                 # 用户可以自行处理的错误
                 except UserFriendlyError as e:
                     logger.error(f'Task failed: {task.name}')
-                    logger.exception(f'Error: ')
+                    logger.exception('Error: ')
                     has_error = True
                     exception = e
-                    dialog = TaskDialog(
-                        title='琴音小助手',
-                        common_buttons=0,
-                        main_instruction='任务执行失败',
-                        content=e.message,
-                        custom_buttons=e.action_buttons,
-                        main_icon='error'
-                    )
-                    result_custom, _, _ = dialog.show()
-                    e.invoke(result_custom)
+                    if TaskDialog:
+                        dialog = TaskDialog(
+                            title='琴音小助手',
+                            common_buttons=0,
+                            main_instruction='任务执行失败',
+                            content=e.message,
+                            custom_buttons=e.action_buttons,
+                            main_icon='error'
+                        )
+                        result_custom, _, _ = dialog.show()
+                        e.invoke(result_custom)
                 # 其他错误
                 except Exception as e:
                     logger.error(f'Task failed: {task.name}')

kotonebot/backend/context/context.py

@@ -175,6 +175,8 @@ class ContextGlobalVars:
         self.__vars = dict[str, Any]()
         self.flow: FlowController = FlowController()
         """流程控制器，负责停止、暂停、恢复等操作"""
+        self.screenshot_data: MatLike | None = None
+        """截图数据"""
 
     def __getitem__(self, key: str) -> Any:
         return self.__vars[key]
@@ -197,6 +199,7 @@ class ContextGlobalVars:
     def clear(self):
         self.__vars.clear()
         self.flow.reset()  # 重置流程控制器
+        self.screenshot_data = None
 
 def check_flow_control():
     """
@@ -220,45 +223,40 @@ class ContextStackVars:
             自动截图。即调用 `color`、`image`、`ocr` 上的方法时，会自动更新截图。
         * `manual`
             完全手动截图，不自动截图。如果在没有截图数据的情况下调用 `color` 等的方法，会抛出异常。
-        * `manual-inherit`：
-            第一张截图继承自调用者，此后同手动截图。
-            如果调用者没有截图数据，则继承的截图数据为空。
-            如果在没有截图数据的情况下调用 `color` 等的方法，会抛出异常。
+        * ~~`manual-inherit`~~：
+            已废弃。
         """
-        self._screenshot: MatLike | None = None
-        """截图数据"""
-        self._inherit_screenshot: MatLike | None = None
-        """继承的截图数据"""
 
     @property
     def screenshot(self) -> MatLike:
         match self.screenshot_mode:
-            case 'manual':
-                if self._screenshot is None:
-                    raise ValueError("No screenshot data found.")
-                return self._screenshot
-            case 'manual-inherit':
-                # TODO: 这一部分要考虑和 device.screenshot() 合并
-                if self._inherit_screenshot is not None:
-                    self._screenshot = self._inherit_screenshot
-                    self._inherit_screenshot = None
-                if self._screenshot is None:
-                    raise ValueError("No screenshot data found.")
-                return self._screenshot
+            case 'manual' | 'manual-inherit':
+                if vars.screenshot_data is None:
+                    raise ValueError("No screenshot data found. Did you forget to call `device.screenshot()`?")
+                return vars.screenshot_data
             case 'auto':
-                self._screenshot = device.screenshot()
-                return self._screenshot
+                device.screenshot()
+                if vars.screenshot_data is None:
+                    raise ValueError("No screenshot data found. Did you forget to call `device.screenshot()`?")
+                return vars.screenshot_data
             case _:
                 raise ValueError(f"Invalid screenshot mode: {self.screenshot_mode}")
 
+    @property
+    @deprecated('Use `vars.screenshot_data` instead.')
+    def _screenshot(self) -> MatLike | None:
+        return vars.screenshot_data
+
+    @_screenshot.setter
+    @deprecated('Use `vars.screenshot_data` instead.')
+    def _screenshot(self, value: MatLike | None) -> None:
+        vars.screenshot_data = value
+
     @staticmethod
     def push(*, screenshot_mode: ScreenshotMode | None = None) -> 'ContextStackVars':
         vars = ContextStackVars()
         if screenshot_mode is not None:
             vars.screenshot_mode = screenshot_mode
-        current = ContextStackVars.current()
-        if current and vars.screenshot_mode == 'manual-inherit':
-            vars._inherit_screenshot = current._screenshot
         ContextStackVars.stack.append(vars)
         return vars
 
@@ -266,7 +264,7 @@ class ContextStackVars:
     def pop() -> 'ContextStackVars':
         last = ContextStackVars.stack.pop()
         return last
-    
+
     @staticmethod
     def current() -> 'ContextStackVars | None':
         if len(ContextStackVars.stack) == 0:
@@ -331,7 +329,7 @@ class ContextOcr:
         )
         self.context.device.last_find = ret.original_rect if ret else None
         return ret
-    
+
     def find_all(
         self,
         patterns: Sequence[str | re.Pattern | StringMatchFunction],
@@ -366,7 +364,7 @@ class ContextOcr:
         ret = engine.expect(ContextStackVars.ensure_current().screenshot, pattern, rect=rect, hint=hint)
         self.context.device.last_find = ret.original_rect if ret else None
         return ret
-    
+
     def expect_wait(
         self,
         pattern: str | re.Pattern | StringMatchFunction,
@@ -447,7 +445,7 @@ class ContextImage:
         等待指定图像出现。
         """
         is_manual = is_manual_screenshot_mode()
-        
+
         start_time = time.time()
         while True:
             if is_manual:
@@ -702,7 +700,7 @@ class ContextConfig(Generic[T]):
     def current(self) -> UserConfig[T]:
         """
         当前配置数据。
-        
+
         如果当前配置不存在，则使用默认值自动创建一个新配置。
         （不推荐，建议在 UI 中启动前要求用户手动创建，或自行创建一个默认配置。）
         """
@@ -729,7 +727,7 @@ class Forwarded:
         if self._FORWARD_getter is None:
             raise ContextNotInitializedError(f"Forwarded object {self._FORWARD_name} called before initialization.")
         return getattr(self._FORWARD_getter(), name)
-    
+
     def __setattr__(self, name: str, value: Any):
         if name.startswith('_FORWARD_'):
             return object.__setattr__(self, name, value)
@@ -761,25 +759,20 @@ class ContextDevice(Generic[T_Device], Device):
         """
         check_flow_control()
         global next_wait, last_screenshot_time, next_wait_time
-        current = ContextStackVars.ensure_current()
-        if force:
-            current._inherit_screenshot = None
-        if current._inherit_screenshot is not None:
-            img = current._inherit_screenshot
-            current._inherit_screenshot = None
-        else:
-            if self._screenshot_interval is not None:
-                self._screenshot_interval.wait()
-
-            if next_wait == 'screenshot':
-                delta = time.time() - last_screenshot_time
-                if delta < next_wait_time:
-                    sleep(next_wait_time - delta)
-                last_screenshot_time = time.time()
-                next_wait_time = 0
-                next_wait = None
-            img = self._device.screenshot()
-        current._screenshot = img
+        ContextStackVars.ensure_current()
+
+        if self._screenshot_interval is not None:
+            self._screenshot_interval.wait()
+
+        if next_wait == 'screenshot':
+            delta = time.time() - last_screenshot_time
+            if delta < next_wait_time:
+                sleep(next_wait_time - delta)
+            last_screenshot_time = time.time()
+            next_wait_time = 0
+            next_wait = None
+        img = self._device.screenshot()
+        vars.screenshot_data = img
         return img
 
     def __getattribute__(self, name: str):
@@ -787,7 +780,7 @@ class ContextDevice(Generic[T_Device], Device):
             return object.__getattribute__(self, name)
         else:
             return getattr(self._device, name)
-        
+
     def __setattr__(self, name: str, value: Any):
         if name in ['_device', 'screenshot', 'of_android', 'of_windows']:
             return object.__setattr__(self, name, value)
@@ -853,7 +846,7 @@ class Context(Generic[T]):
         if vars is not None:
             self.__vars = vars
         if debug is not None:
-            self.__debug = debug    
+            self.__debug = debug
         if config is not None:
             self.__config = config
 
@@ -864,7 +857,7 @@ class Context(Generic[T]):
     @property
     def ocr(self) -> 'ContextOcr':
         return self.__ocr
-    
+
     @property
     def image(self) -> 'ContextImage':
         return self.__image
@@ -876,7 +869,7 @@ class Context(Generic[T]):
     @property
     def vars(self) -> 'ContextGlobalVars':
         return self.__vars
-    
+
     @property
     def debug(self) -> 'ContextDebug':
         return self.__debug
@@ -895,7 +888,7 @@ def rect_expand(rect: Rect, left: int = 0, top: int = 0, right: int = 0, bottom:
 def use_screenshot(*args: MatLike | None) -> MatLike:
     for img in args:
         if img is not None:
-            ContextStackVars.ensure_current()._screenshot = img # HACK
+            vars.screenshot_data = img
             return img
     return device.screenshot()
 
@@ -1006,4 +999,4 @@ def manual_context(screenshot_mode: ScreenshotMode = 'auto') -> ManualContextMan
     默认情况下，Context* 类仅允许在 @task/@action 函数中使用。
     如果想要在其他地方使用，使用此函数手动创建一个上下文。
     """
-    return ManualContextManager(screenshot_mode)
+    return ManualContextManager(screenshot_mode)

kotonebot/backend/context/task_action.py

@@ -1,6 +1,8 @@
 import logging
-from typing import Callable, ParamSpec, TypeVar, overload, Literal
+import warnings
 from dataclasses import dataclass
+from typing_extensions import deprecated
+from typing import Callable, ParamSpec, TypeVar, overload, Literal
 
 
 from .context import ContextStackVars, ScreenshotMode
@@ -93,6 +95,17 @@ def task(
 @overload
 def action(func: Callable[P, R]) -> Callable[P, R]: ...
 
+@deprecated('Use `action` with screenshot_mode=`manual` instead.')
+@overload
+def action(
+    name: str,
+    *,
+    description: str|None = None,
+    pass_through: bool = False,
+    priority: int = 0,
+    screenshot_mode: Literal['manual-inherit'],
+) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+
 @overload
 def action(
     name: str,
@@ -115,9 +128,6 @@ def action(
     """
     ...
 
-# TODO: 需要找个地方统一管理这些属性名
-ATTR_ORIGINAL_FUNC = '_kb_inner'
-ATTR_ACTION_MARK = '__kb_action_mark'
 def action(*args, **kwargs):
     def _register(func: Callable, name: str, description: str|None = None, priority: int = 0) -> Action:
         description = description or func.__doc__ or ''
@@ -136,8 +146,6 @@ def action(*args, **kwargs):
             ContextStackVars.pop()
             current_callstack.pop()
             return ret
-        setattr(_wrapper, ATTR_ORIGINAL_FUNC, func)
-        setattr(_wrapper, ATTR_ACTION_MARK, True)
         action.func = _wrapper
         return _wrapper
     else:
@@ -146,6 +154,8 @@ def action(*args, **kwargs):
         pass_through = kwargs.get('pass_through', False)
         priority = kwargs.get('priority', 0)
         screenshot_mode = kwargs.get('screenshot_mode', None)
+        if screenshot_mode == 'manual-inherit':
+            warnings.warn('`screenshot_mode=manual-inherit` is deprecated. Use `screenshot_mode=manual` instead.')
         def _action_decorator(func: Callable):
             nonlocal pass_through
             action = _register(_placeholder, name, description)
@@ -160,8 +170,6 @@ def action(*args, **kwargs):
                     ContextStackVars.pop()
                     current_callstack.pop()
                     return ret
-                setattr(_wrapper, ATTR_ORIGINAL_FUNC, func)
-                setattr(_wrapper, ATTR_ACTION_MARK, True)
                 action.func = _wrapper
                 return _wrapper
         return _action_decorator

kotonebot/backend/core.py

@@ -1,6 +1,7 @@
 import logging
 from functools import cache
 from typing import Callable
+from typing_extensions import deprecated
 
 import cv2
 from cv2.typing import MatLike
@@ -9,6 +10,7 @@ from kotonebot.util import cv2_imread
 from kotonebot.primitives import RectTuple, Rect, Point
 from kotonebot.errors import ResourceFileMissingError
 
+@deprecated('unused')
 class Ocr:
     def __init__(
         self,
@@ -19,7 +21,8 @@ class Ocr:
         self.text = text
         self.language = language
 
-
+# TODO: 这个类和 kotonebot.primitives.Image 重复了
+@deprecated('Use kotonebot.primitives.Image instead.')
 class Image:
     def __init__(
         self,
@@ -65,7 +68,7 @@ class Image:
         else:
             return f'<Image: "{self.name}" at {self.path}>'
 
-
+# TODO: 这里的其他类应该移动到 primitives 模块下面
 class HintBox(Rect):
     def __init__(
         self,

kotonebot/backend/loop.py

@@ -1,6 +1,7 @@
 import time
 from functools import lru_cache, partial
 from typing import Callable, Any, overload, Literal, Generic, TypeVar, cast, get_args, get_origin
+from typing_extensions import deprecated
 
 from cv2.typing import MatLike
 
@@ -9,8 +10,9 @@ from kotonebot import device, image, ocr
 from kotonebot.backend.core import Image
 from kotonebot.backend.ocr import TextComparator
 from kotonebot.client.protocol import ClickableObjectProtocol
+from .context import vars
 
-
+@deprecated('No longer used.')
 class LoopAction:
     def __init__(self, loop: 'Loop', func: Callable[[], ClickableObjectProtocol | None]):
         self.loop = loop
@@ -81,15 +83,16 @@ class Loop:
         是否在每次循环开始时（Loop.tick() 被调用时）截图。
         """
         self.__last_loop: float = -1
-        self.__interval = Interval(interval)
+        self.interval = interval
+        """每次循环后等待的时间。"""
         self.screenshot: MatLike | None = None
         """上次截图时的图像数据。"""
         self.__skip_first_wait = skip_first_wait
         self.__is_first_tick = True
 
     def __iter__(self):
-        self.__interval.reset()
         self.__is_first_tick = True
+        vars.flow.check()
         return self
 
     def __next__(self):
@@ -101,7 +104,7 @@ class Loop:
 
     def tick(self):
         if not (self.__is_first_tick and self.__skip_first_wait):
-            self.__interval.wait()
+            time.sleep(self.interval)
         self.__is_first_tick = False
 
         if self.auto_screenshot:
@@ -117,13 +120,16 @@ class Loop:
         self.running = False
 
     @overload
+    @deprecated('Use plain if statement instead.')
     def when(self, condition: Image) -> LoopAction:
         ...
 
     @overload
+    @deprecated('Use plain if statement instead.')
     def when(self, condition: TextComparator) -> LoopAction:
         ...
 
+    @deprecated('Use plain if statement instead.')
     def when(self, condition: Any):
         """
         判断某个条件是否成立。
@@ -142,6 +148,7 @@ class Loop:
         la.do()
         return la
 
+    @deprecated('Use plain if statement instead.')
     def until(self, condition: Any):
         """
         当满足指定条件时，结束循环。
@@ -150,6 +157,7 @@ class Loop:
         """
         return self.when(condition).call(lambda _: self.exit())
 
+    @deprecated('Use image.find() and device.click() instead.')
     def click_if(self, condition: Any, *, at: tuple[int, int] | None = None):
         """
         检测指定对象是否出现，若出现，点击该对象或指定位置。
@@ -198,87 +206,3 @@ class StatedLoop(Loop, Generic[StateType]):
             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/device.py

@@ -239,7 +239,8 @@ class Device:
         调用前确保 `orientation` 属性与设备方向一致，
         否则点击位置会不正确。
         """
-        x, y = self.screen_size[0] // 2, self.screen_size[1] // 2
+        size = self.target_resolution or self.screen_size
+        x, y = size[0] // 2, size[1] // 2
         self.click(x, y)
     
     @overload

kotonebot/client/host/adb_common.py

@@ -28,11 +28,15 @@ def connect_adb(
     if disconnect:
         logger.debug('adb disconnect %s:%d', ip, port)
         adb.disconnect(f'{ip}:{port}')
+    else:
+        logger.debug('Skip adb disconnect.')
     if connect:
         logger.debug('adb connect %s:%d', ip, port)
         result = adb.connect(f'{ip}:{port}')
         if 'cannot connect to' in result:
             raise ValueError(result)
+    else:
+        logger.debug('Skip adb connect.')
     serial = device_serial or f'{ip}:{port}'
     logger.debug('adb wait for %s', serial)
     adb.wait_for(serial, timeout=timeout)
@@ -56,15 +60,20 @@ class CommonAdbCreateDeviceMixin(ABC):
         self.adb_port: int
         self.adb_name: str
     
-    def create_device(self, recipe: AdbRecipes, config: AdbHostConfig) -> Device:
+    def create_device(self, recipe: AdbRecipes, config: AdbHostConfig, *, connect: bool = True, disconnect: bool = True) -> Device:
         """
         创建 ADB 设备。
+
+        :param recipe: 连接方式配方名称。
+        :param config: ADB 配置。
+        :param connect: 创建设备实例前，是否连接 ADB（执行 adb connect）。
+        :param disconnect: 创建设备实例前，是否先断开已有 ADB 连接（执行 adb disconnect）。
         """
         connection = connect_adb(
             self.adb_ip,
             self.adb_port,
-            connect=True,
-            disconnect=True,
+            connect=connect,
+            disconnect=disconnect,
             timeout=config.timeout,
             device_serial=self.adb_name
         )

kotonebot/client/host/leidian_host.py

@@ -77,7 +77,7 @@ class LeidianInstance(CommonAdbCreateDeviceMixin, Instance[AdbHostConfig]):
         if self.adb_port is None:
             raise ValueError("ADB port is not set and is required.")
 
-        return super().create_device(impl, host_config)
+        return super().create_device(impl, host_config, connect=False, disconnect=False)
 
 class LeidianHost(HostProtocol[LeidianRecipes]):
     @staticmethod

kotonebot/client/host/windows_common.py

@@ -4,6 +4,7 @@ from typing_extensions import assert_never
 
 from kotonebot import logging
 from kotonebot.client.device import WindowsDevice
+from kotonebot.util import require_windows
 from .protocol import Device, WindowsHostConfig, RemoteWindowsHostConfig
 
 logger = logging.getLogger(__name__)
@@ -19,11 +20,13 @@ class CommonWindowsCreateDeviceMixin(ABC):
     """
     def __init__(self, *args, **kwargs) -> None:
         super().__init__(*args, **kwargs)
+        require_windows('CommonWindowsCreateDeviceMixin', self.__class__)
     
     def create_device(self, recipe: WindowsRecipes, config: WindowsHostConfigs) -> Device:
         """
         创建 Windows 设备。
         """
+        require_windows('CommonWindowsCreateDeviceMixin.create_device', self.__class__)
         match recipe:
             case 'windows':
                 if not isinstance(config, WindowsHostConfig):

kotonebot/client/implements/__init__.py

@@ -1,7 +1,15 @@
-# 导入所有内置实现，以触发它们的 @register_impl 装饰器
+from kotonebot.util import is_windows, require_windows
+
+# 基础实现
 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
-from . import nemu_ipc  # noqa: F401
+
+# Windows 实现（默认仅在 Windows 上导入）
+if is_windows():
+    try:
+        from . import nemu_ipc  # noqa: F401
+        from . import windows  # noqa: F401
+        from . import remote_windows  # noqa: F401
+    except ImportError:
+        require_windows('"windows" and "remote_windows" implementations')

kotonebot/client/implements/remote_windows.py

@@ -1,10 +1,6 @@
-"""
-Remote Windows implementation using XML-RPC.
-
-This module provides:
-1. RemoteWindowsImpl - Client implementation that connects to a remote Windows machine
-2. RemoteWindowsServer - Server implementation that exposes a WindowsImpl instance via XML-RPC
-"""
+# ruff: noqa: E402
+from kotonebot.util import require_windows
+require_windows('"RemoteWindowsImpl" implementation')
 
 import io
 import base64

kotonebot/client/implements/windows.py

@@ -1,3 +1,7 @@
+# ruff: noqa: E402
+from kotonebot.util import require_windows
+require_windows('"WindowsImpl" implementation')
+
 from ctypes import windll
 from typing import Literal
 from importlib import resources

kotonebot/interop/win/__init__.py

@@ -0,0 +1,3 @@
+# ruff: noqa: E402
+from kotonebot.util import require_windows
+require_windows('kotonebot.interop.win module')

kotonebot/interop/win/task_dialog.py

@@ -1,3 +1,47 @@
+"""
+Windows Task Dialog interop module.
+
+This module provides Windows TaskDialog functionality and is only available on Windows systems.
+"""
+
+import platform
+import warnings
+
+from kotonebot.util import is_windows
+
+# 检查是否在 Windows 平台上
+if not is_windows():
+    _WINDOWS_ONLY_MSG = (
+        f"TaskDialog is only available on Windows systems. "
+        f"Current system: non-Windows\n"
+        "To use Windows TaskDialog features, please run this code on a Windows system."
+    )
+
+    
+    # 提供虚拟类以避免导入错误
+    class TaskDialog:
+        def __init__(self, *args, **kwargs):
+            raise ImportError(_WINDOWS_ONLY_MSG)
+    
+    # 导出所有常量作为 None
+    __all__ = [
+        "TaskDialog",
+        "TDCBF_OK_BUTTON", "TDCBF_YES_BUTTON", "TDCBF_NO_BUTTON", "TDCBF_CANCEL_BUTTON",
+        "TDCBF_RETRY_BUTTON", "TDCBF_CLOSE_BUTTON",
+        "IDOK", "IDCANCEL", "IDABORT", "IDRETRY", "IDIGNORE", "IDYES", "IDNO", "IDCLOSE",
+        "TD_WARNING_ICON", "TD_ERROR_ICON", "TD_INFORMATION_ICON", "TD_SHIELD_ICON"
+    ]
+    
+    # 设置所有常量为 None 或保留为模块级变量
+    TDCBF_OK_BUTTON = TDCBF_YES_BUTTON = TDCBF_NO_BUTTON = TDCBF_CANCEL_BUTTON = None
+    TDCBF_RETRY_BUTTON = TDCBF_CLOSE_BUTTON = None
+    IDOK = IDCANCEL = IDABORT = IDRETRY = IDIGNORE = IDYES = IDNO = IDCLOSE = None
+    TD_WARNING_ICON = TD_ERROR_ICON = TD_INFORMATION_ICON = TD_SHIELD_ICON = None
+    
+    # 阻止模块加载
+    raise ImportError(_WINDOWS_ONLY_MSG)
+
+# 如果是 Windows，继续正常加载
 import ctypes
 from ctypes import wintypes
 import time

kotonebot/ui/user.py

@@ -4,7 +4,12 @@ import time
 
 import cv2
 from cv2.typing import MatLike
-from win11toast import toast
+from kotonebot.util import is_windows
+if is_windows():
+    from win11toast import toast
+else:
+    def toast(title: str, message: str | None = None, buttons: list[str] | None = None):
+        raise ImportError('toast notification is only available on Windows')
 
 from .pushkit import Wxpusher
 from .. import logging

kotonebot/util.py

@@ -4,6 +4,7 @@ import pstats
 import typing
 import logging
 import cProfile
+import platform
 from importlib import resources
 from functools import lru_cache
 from typing import Literal, Callable, TYPE_CHECKING, TypeGuard
@@ -17,6 +18,32 @@ if TYPE_CHECKING:
     from kotonebot.client.protocol import Device
 
 logger = logging.getLogger(__name__)
+_WINDOWS_ONLY_MSG = (
+    "This feature is only available on Windows. "
+    f"You are using {platform.system()}.\n"
+    "The requested feature is: {feature_name}\n"
+)
+
+def is_windows() -> bool:
+    """检查当前是否为 Windows 系统"""
+    return platform.system() == 'Windows'
+
+def is_linux() -> bool:
+    """检查当前是否为 Linux 系统"""
+    return platform.system() == 'Linux'
+
+def is_macos() -> bool:
+    """检查当前是否为 macOS 系统"""
+    return platform.system() == 'Darwin'
+
+def require_windows(feature_name: str | None = None, class_: type | None = None) -> None:
+    """要求必须在 Windows 系统上运行，否则抛出 ImportError"""
+    if not is_windows():
+        feature_name = feature_name or 'not specified'
+        if class_:
+            full_name = '.'.join([class_.__module__, class_.__name__])
+            feature_name += f' ({full_name})'
+        raise ImportError(_WINDOWS_ONLY_MSG.format(feature_name=feature_name))
 
 
 

{kotonebot-0.3.1.dist-info → kotonebot-0.4.0.dist-info}/METADATA

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: kotonebot
-Version: 0.3.1
-Summary: Kotonebot is game/app automation library based on computer vision technology, works for Windows and Android.
+Version: 0.4.0
+Summary: Kotonebot is game automation library based on computer vision technology, works for Windows and Android.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: opencv-python~=4.10
 Requires-Dist: rapidocr_onnxruntime~=1.4
-Requires-Dist: av~=14.0
 Requires-Dist: scikit-image~=0.25
 Requires-Dist: thefuzz~=0.22
 Requires-Dist: pydantic~=2.10
@@ -17,24 +16,26 @@ Requires-Dist: python-dotenv~=1.0
 Requires-Dist: onnxruntime~=1.14
 Requires-Dist: numpy
 Provides-Extra: android
-Requires-Dist: adbutils~=2.8; extra == "android"
-Requires-Dist: uiautomator2~=3.2; extra == "android"
+Requires-Dist: adbutils>=2.8; extra == "android"
+Requires-Dist: uiautomator2>=3.2; extra == "android"
 Provides-Extra: windows
 Requires-Dist: pywin32; extra == "windows"
-Requires-Dist: ahk~=1.8; extra == "windows"
-Requires-Dist: win11toast~=0.35; extra == "windows"
-Requires-Dist: psutil~=6.1; extra == "windows"
+Requires-Dist: ahk>=1.8; extra == "windows"
+Requires-Dist: win11toast>=0.35; extra == "windows"
+Requires-Dist: psutil>=6.1; extra == "windows"
 Provides-Extra: dev
 Requires-Dist: fastapi~=0.115; extra == "dev"
 Requires-Dist: uvicorn~=0.34; extra == "dev"
 Requires-Dist: python-multipart~=0.0; extra == "dev"
 Requires-Dist: websockets~=14.1; extra == "dev"
 Requires-Dist: psutil~=6.1; extra == "dev"
-Requires-Dist: gradio~=5.21; extra == "dev"
-Requires-Dist: snakeviz; extra == "dev"
+Requires-Dist: twine~=6.1; extra == "dev"
 Requires-Dist: build; extra == "dev"
+Requires-Dist: snakeviz; extra == "dev"
+Requires-Dist: jinja2~=3.1; extra == "dev"
+Requires-Dist: tqdm~=4.67; extra == "dev"
 Provides-Extra: all
-Requires-Dist: kotonebot[android,windows]; extra == "all"
+Requires-Dist: kotonebot[android,dev,windows]; extra == "all"
 Dynamic: license-file
 
 # kotonebot
@@ -67,6 +68,10 @@ pip install kotonebot[dev]
 ## 快速开始
 WIP
 
+### 协同开发
+有时候你可能想以源码方式安装 kotonebot，以便与自己的项目一起调试修改。此时，如果你以 `pip install -e /path/to/kotonebot` 的方式安装，Pylance 可能无法正常静态分析。
+解决方案是在 VSCode 里搜索 `python.analysis.extraPaths` 并将其设置为你本地 kotonebot 的根目录。
+
 ## 文档
 WIP
 

{kotonebot-0.3.1.dist-info → kotonebot-0.4.0.dist-info}/RECORD

@@ -1,53 +1,53 @@
 kotonebot/__init__.py,sha256=DWS8zZAWH-MQZxk6bDm9uNAfY9UVmtd7Q928suujpiQ,636
 kotonebot/errors.py,sha256=1mZLFhNNxtRkm66y80rPzOeFjCgR0TgxgCDGo9ByZek,2294
-kotonebot/util.py,sha256=MyJYVNrKcZy7I9bK0rhW15ivPLoiA3B7_hM9svWIfNc,13360
+kotonebot/util.py,sha256=ftWhlnZ3qJ80x2wVCHYr2wW299JQkYDOREP1mA-n1vg,14370
 kotonebot/backend/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kotonebot/backend/bot.py,sha256=q7nVPru_A8kg8_o_MMpMfECchKqU8_AFpGIQk8-q5pY,11585
+kotonebot/backend/bot.py,sha256=Ph0pfAubr_TV4MmqkyYL0P0hLbXdFEkzlQ0V2B1niZI,11870
 kotonebot/backend/color.py,sha256=KqFISc6puMNbsyB5diu5PcqNjdkLwUeryVsMmeAJG4Q,20125
-kotonebot/backend/core.py,sha256=pn1XORbU6_ddfgLJQpLSmiGL2MjnF5iCk5GBdrq3GYE,3783
+kotonebot/backend/core.py,sha256=A0f2i1KO9PXn4ndRDOBbADtB_beVxD1P0g4FYioxUY0,4026
 kotonebot/backend/dispatch.py,sha256=t3eqkOVNNrdaeXSMLxDbReYhVRoAlSRNxb7oO2clRsQ,7423
 kotonebot/backend/flow_controller.py,sha256=sbr6JiuYXErevY_BPrzw7hUCfxLGVrz0W_KNbXIxe9Q,6228
 kotonebot/backend/image.py,sha256=jXYGVXa9K1zBCJBG1Btsf2AG5XI9A0DMy5uYy6KOusk,28111
-kotonebot/backend/loop.py,sha256=HlgMON1LcBPZP710w5uHeziMRSF5Dhwv3UKUdjCkouk,9594
+kotonebot/backend/loop.py,sha256=e4STYQ6sbUp53xcYJXyhz4vOyEzXds1MKR0xebqU228,6638
 kotonebot/backend/ocr.py,sha256=IE_LUCdD4i00a02xgLkSRPcYYo3R2MBfZKKQHjOFfgM,18058
 kotonebot/backend/preprocessor.py,sha256=YmAbLa-XXES2AchMJtsBpPZwIIGHuYapwpXpw0YSpbA,3423
 kotonebot/backend/context/__init__.py,sha256=0X9jzM0ftGQUgjoXCk98xf1inoCqHqaUwT0wcHn9P5s,168
-kotonebot/backend/context/context.py,sha256=dvGD_kKaThYdwIuC21Gd2P0uYwyh3yRgMYqkZ5_Ap3w,34472
-kotonebot/backend/context/task_action.py,sha256=7fKy6ZOtOaDW87hketiub72_eND9yorJqBP3Z5b8fX8,6259
+kotonebot/backend/context/context.py,sha256=R91knq7Ry5MSWaFhOj3HIF13u8bomOOsGk59yPOG4aw,33780
+kotonebot/backend/context/task_action.py,sha256=LdxyeW-1ie71ludnAN36ltlcAw4AX3Lb9ua7I5xK4yY,6444
 kotonebot/backend/debug/__init__.py,sha256=pcSpwzU2YwGrogOoHmsI035nkA_-kDLfm-lfBxHuQ-c,43
 kotonebot/backend/debug/entry.py,sha256=_sIGi9_LegbaM2DCcDTvGJhrkyUqF6W2Al4nYmkb9rM,2833
 kotonebot/backend/debug/mock.py,sha256=0fTiJeqVTanQv6L3TPbldgbJRBPmunZOjlzKtVicJ_M,2118
 kotonebot/backend/debug/server.py,sha256=9PEpczIrwCnD4c_FAtiojwk27aKkkzTtRySCsdho4Rs,7517
 kotonebot/backend/debug/vars.py,sha256=3wtbkH2WFNXyT2ZNu-8en3S0pAb40h-SefYyScRMLnM,10912
 kotonebot/client/__init__.py,sha256=1eXyGopBFpYoucNTNkTo-7nIeDyasyETfHJ8DWuaNTo,192
-kotonebot/client/device.py,sha256=5BVa1dXVI_jH5gLCL61tJ_MXG6BVSt_mETqyUVlutWo,19370
+kotonebot/client/device.py,sha256=bb49Gbo-zcF1SaeBbRljxkuKGMp5e9umPiguAbV1kok,19405
 kotonebot/client/fast_screenshot.py,sha256=q69AX15VXRuB0U2qFJKfoTOBgG4nVBCUcaN1CX0VsUc,13647
 kotonebot/client/protocol.py,sha256=x05llULFI3MddbvBX_c0sYWlSzCyWa3hped24ktq2Ko,2300
 kotonebot/client/registration.py,sha256=XK424QEWbJKfNdkiDoIJUh_JIy8ryk4I4I3hrWUXCX8,848
 kotonebot/client/host/__init__.py,sha256=WsDNAugbr4k1fMCHBdaYZmrifrq6WmSQByp1qOFbV_I,579
-kotonebot/client/host/adb_common.py,sha256=b9t5bbiIYGARpqB8qayptAzznQaWtzWt533yqoAAyvQ,3280
+kotonebot/client/host/adb_common.py,sha256=_S2LKpsNnRUREUpzO71OfMIB8Dt0pmxKdSbcmpqss-4,3750
 kotonebot/client/host/custom.py,sha256=_r2GAtJ20CoEx8JO7wVa4jr6KT8YgO5wzrFHLFtOgZE,4079
-kotonebot/client/host/leidian_host.py,sha256=EoogcI1XN1akE1zKLaZCNMvs7uIRrraZsg6ib5cRwAU,7696
+kotonebot/client/host/leidian_host.py,sha256=H1yNhKRBdjzyY8_UjqohuJwjj-gVvN1s3dnQfKgFdW8,7729
 kotonebot/client/host/mumu12_host.py,sha256=cWlbZiV0HdN2S42L1Nd5Jcv3bw-b1oxjX4_3y5JE-tI,14444
 kotonebot/client/host/protocol.py,sha256=x2TbnDELDQpqxSKWUHLT3Pez8Qx6IzL4wyUfgf9mFyk,8051
-kotonebot/client/host/windows_common.py,sha256=sz2uxfYa4by4uNM7_7qHS1kfvyu9iYxd5DgJ8ThQAKA,2223
-kotonebot/client/implements/__init__.py,sha256=w9Yz_nVEnby_7eCS2FT1oYp1IuO3yqSdvhZEu6iJcvk,303
+kotonebot/client/host/windows_common.py,sha256=_Hf4CvHKNgiMIVY3ZPr3wF71r6nMErNi84Y_fswUjBc,2431
+kotonebot/client/implements/__init__.py,sha256=_qZNM-2wEr4Q-_2kWisyuc4AUoqpRB_gAC_hr8_RkSY,511
 kotonebot/client/implements/adb.py,sha256=OcATiRGj84KMM9mEuQLzLoNyDBaZRJugR-BFrlWjB-c,3145
 kotonebot/client/implements/adb_raw.py,sha256=zUTI9QscmdN031tbBbInUN8G-LrgQv-cTc_Yl0zaZQU,6307
-kotonebot/client/implements/remote_windows.py,sha256=tc9R0kcKAwLwWt4Qu8Gt8wLZJCS94MnFzTvKuCbM9Wo,6902
+kotonebot/client/implements/remote_windows.py,sha256=SRq97cuXdUVvFIhsazZt4djMeGSLfYS88IUyzmlpaww,6756
 kotonebot/client/implements/uiautomator2.py,sha256=ER4cNLI_cCpIGKWIXeuaUPmVtz50JuFO5Kx-ZwCGI1s,2575
-kotonebot/client/implements/windows.py,sha256=-xS2qN5RdHB_X4R1a8Oi5tM2Wh5YI774wNAJ21lYirQ,6623
+kotonebot/client/implements/windows.py,sha256=-P5nFiUbCxz9qMM-WZPtw-Q2xYc3Tmym5MNK3gBwoB4,6738
 kotonebot/client/implements/nemu_ipc/__init__.py,sha256=vSZzv75bn38Wch86PYs5UDOCLwxxoDGm2v1jrwff_S8,200
 kotonebot/client/implements/nemu_ipc/external_renderer_ipc.py,sha256=YsfKf0-qorfAf2YvNuxpLb9af-HJFsu97bnXABshhbA,10643
 kotonebot/client/implements/nemu_ipc/nemu_ipc.py,sha256=LhUUyfB28MDnRg8z2FyGah1hTeOMFiX7w8LZLAAjLF8,12082
 kotonebot/config/__init__.py,sha256=-jATUOdrpUrBRT9RiTRQho2-2zeet50qQggsVMVpqNE,35
 kotonebot/config/base_config.py,sha256=NpJuUmzgjUHelzm55bbVvk9x9MdwuKwfxwpaJFp-9iw,3438
 kotonebot/config/manager.py,sha256=XBtriAU9eo-wv2iKOwyDqu8tzhbKqFCuy0jsAM9T9uU,1061
-kotonebot/interop/win/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kotonebot/interop/win/__init__.py,sha256=jH8E0iqT1lOs4C_i5yl4bJ7z7iZh2ieGOF1lu8raJ30,111
 kotonebot/interop/win/message_box.py,sha256=R06GSu936Bx_Wg7ddn6LOvazD9_Gt3mhz4_oUuIoYO0,8635
 kotonebot/interop/win/reg.py,sha256=xw35d1xl8ucITT4bOMFgHmMkAUhak7x3lzegR3g3S48,1347
 kotonebot/interop/win/shortcut.py,sha256=f1u6IWvpw6Kxt014wnHz5Z94rVK1qf4kLtRsI9bJYnk,1764
-kotonebot/interop/win/task_dialog.py,sha256=pJMEf94pXzHmVpjhfuCeSZ0ztJ8DARsSHTcDOXa1dLQ,18608
+kotonebot/interop/win/task_dialog.py,sha256=Ezi1CsjFSbnKccvYfIRaJoCGHUsJnnIpHb0gtKR603E,20191
 kotonebot/logging/__init__.py,sha256=r0q4z59yYy_bQnHTwJYsiPGwOGIgEOrcXH1mNs1h_N0,142
 kotonebot/logging/log.py,sha256=PLb6r_hlW1mvqU_kx6_89zaQ1IpamgHWG3sQ0ZnlrCI,555
 kotonebot/primitives/__init__.py,sha256=R11AoTQQU6ql86oaVjZJkH2-kkxf5kr9xY8gnqPjLgM,355
@@ -56,15 +56,15 @@ kotonebot/primitives/visual.py,sha256=fZbNgaM03wCaR1Rb0QgeAQIfNsBBXPoUp2-E2IYFsL
 kotonebot/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kotonebot/tools/mirror.py,sha256=jlGpeX_WkFpcZxojxDzT5QqVeIpd_UIDzSMR2K31VJ0,13820
 kotonebot/ui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kotonebot/ui/user.py,sha256=kiEWKpR6XAFh7LUu_HK3NPCioLeA2tEJZRY8iKza6ac,4249
+kotonebot/ui/user.py,sha256=aP6Va3iHaVA0-AHViNa04a3HDpLLiovZjV5_AMGY4cI,4485
 kotonebot/ui/file_host/sensio.py,sha256=QyH8DpyO3sf2Hz4NuOW9oDt1V3G06XMO7yKfgLwq1oE,914
 kotonebot/ui/file_host/tmp_send.py,sha256=SwzTUGIjZXaP1_H86qahuLwUd8VeHGWW86XKaC__WKI,1802
 kotonebot/ui/pushkit/__init__.py,sha256=xDUctRUL3euvge-yl8IhFYMlxIxQXsjxcyGN5tUwPtE,73
 kotonebot/ui/pushkit/image_host.py,sha256=nB6BCOA5ZgSGi-ntgqQp49H1UZDk8qC41O_PTLPzZ-E,2581
 kotonebot/ui/pushkit/protocol.py,sha256=KVZ-xr0sMdiuri7AiYqugpZRRtefBsosXm6zouScUR4,266
 kotonebot/ui/pushkit/wxpusher.py,sha256=U7WKxyf9pVgGvppmBxwMRuBuFkQG3NC3tkdRh7_-IOw,1732
-kotonebot-0.3.1.dist-info/licenses/LICENSE,sha256=gcuuhKKc5-dwvyvHsXjlC9oM6N5gZ6umYbC8ewW1Yvg,35821
-kotonebot-0.3.1.dist-info/METADATA,sha256=x2hYu3ZdsflywLK_3BJ2PwbNTw7R9PaYuLg8xTOChqQ,2788
-kotonebot-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-kotonebot-0.3.1.dist-info/top_level.txt,sha256=QUWAZdbBndoojkrs6RcNytLAn7a0ns4YNF4tLx2Nc4s,10
-kotonebot-0.3.1.dist-info/RECORD,,
+kotonebot-0.4.0.dist-info/licenses/LICENSE,sha256=gcuuhKKc5-dwvyvHsXjlC9oM6N5gZ6umYbC8ewW1Yvg,35821
+kotonebot-0.4.0.dist-info/METADATA,sha256=4P-5GBc-v3VEtDlQqx0F3pUJXC7D9p2b0cmPbVZ91NE,3207
+kotonebot-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kotonebot-0.4.0.dist-info/top_level.txt,sha256=QUWAZdbBndoojkrs6RcNytLAn7a0ns4YNF4tLx2Nc4s,10
+kotonebot-0.4.0.dist-info/RECORD,,