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

kotonebot/backend/bot.py

@@ -32,7 +32,7 @@ class RunStatus:
     callstack: list[Task | Action] = field(default_factory=list)
 
     def interrupt(self):
-        vars.interrupted.set()
+        vars.flow.request_interrupt()
 
 # Modified from https://stackoverflow.com/questions/70982565/how-do-i-make-an-event-listener-with-decorators-in-python
 Params = ParamSpec('Params')
@@ -158,7 +158,7 @@ class KotoneBot:
         d = self._on_create_device()
         init_context(config_path=self.config_path, config_type=self.config_type, target_device=d)
         self._on_after_init_context()
-        vars.interrupted.clear()
+        vars.flow.clear_interrupt()
 
         if by_priority:
             tasks = sorted(tasks, key=lambda x: x.priority, reverse=True)
@@ -180,7 +180,7 @@ class KotoneBot:
                     logger.exception('Keyboard interrupt detected.')
                     for task1 in tasks[tasks.index(task):]:
                         self.events.task_status_changed.trigger(task1, 'cancelled')
-                    vars.interrupted.clear()
+                    vars.flow.clear_interrupt()
                     break
                 # 其他错误
                 except Exception as e:

kotonebot/backend/context/context.py

@@ -3,6 +3,7 @@ import re
 import time
 import logging
 import warnings
+import threading
 from datetime import datetime
 from threading import Event
 from typing import (
@@ -24,7 +25,8 @@ from typing_extensions import deprecated
 import cv2
 from cv2.typing import MatLike
 
-from kotonebot.client.device import Device
+from kotonebot.client.device import Device, AndroidDevice, WindowsDevice
+from kotonebot.backend.flow_controller import FlowController
 import kotonebot.backend.image as raw_image
 from kotonebot.backend.image import (
     TemplateMatchResult,
@@ -44,12 +46,12 @@ from kotonebot.backend.color import (
 from kotonebot.backend.ocr import (
     Ocr, OcrResult, OcrResultList, jp, en, StringMatchFunction
 )
-from kotonebot.client.factory import create_device
+from kotonebot.client.registration import AdbBasedImpl, create_device
 from kotonebot.config.manager import load_config, save_config
 from kotonebot.config.base_config import UserConfig
 from kotonebot.backend.core import Image, HintBox
 from kotonebot.errors import KotonebotWarning
-from kotonebot.client.factory import DeviceImpl
+from kotonebot.client import DeviceImpl
 from kotonebot.backend.preprocessor import PreprocessorProtocol
 from kotonebot.primitives import Rect
 
@@ -126,8 +128,7 @@ def interruptible(func: Callable[P, T]) -> Callable[P, T]:
     """
     def _decorator(*args: P.args, **kwargs: P.kwargs) -> T:
         global vars
-        if vars.interrupted.is_set():
-            raise KeyboardInterrupt("User requested interrupt.")
+        vars.flow.check()
         return func(*args, **kwargs)
     return _decorator
 
@@ -145,15 +146,13 @@ def interruptible_class(cls: Type[T]) -> Type[T]:
 
 def sleep(seconds: float, /):
     """
-    可中断的 sleep 函数。
+    可中断和可暂停的 sleep 函数。
 
     建议使用本函数代替 `time.sleep()`，
-    这样能以最快速度响应用户请求中断。
+    这样能以最快速度响应用户请求中断和暂停。
     """
     global vars
-    vars.interrupted.wait(timeout=seconds)
-    if vars.interrupted.is_set():
-        raise KeyboardInterrupt("User requested interrupt.")
+    vars.flow.sleep(seconds)
 
 def warn_manual_screenshot_mode(name: str, alternative: str):
     """
@@ -175,8 +174,8 @@ def is_manual_screenshot_mode() -> bool:
 class ContextGlobalVars:
     def __init__(self):
         self.__vars = dict[str, Any]()
-        self.interrupted: Event = Event()
-        """用户请求中断事件"""
+        self.flow: FlowController = FlowController()
+        """流程控制器，负责停止、暂停、恢复等操作"""
 
     def __getitem__(self, key: str) -> Any:
         return self.__vars[key]
@@ -198,6 +197,17 @@ class ContextGlobalVars:
 
     def clear(self):
         self.__vars.clear()
+        self.flow.reset()  # 重置流程控制器
+
+def check_flow_control():
+    """
+    统一的流程控制检查函数。
+
+    检查用户是否请求中断或暂停，如果是则相应处理：
+    - 如果请求中断，抛出 KeyboardInterrupt 异常
+    - 如果请求暂停，等待直到恢复
+    """
+    vars.flow.check()
 
 class ContextStackVars:
     stack: list['ContextStackVars'] = []
@@ -707,15 +717,17 @@ class Forwarded:
             raise ValueError(f"Forwarded object {self._FORWARD_name} called before initialization.")
         setattr(self._FORWARD_getter(), name, value)
 
-# HACK: 这应该要有个更好的实现方式
-class ContextDevice(Device):
-    def __init__(self, device: Device):
+
+T_Device = TypeVar('T_Device', bound=Device)
+class ContextDevice(Generic[T_Device], Device):
+    def __init__(self, device: T_Device):
         self._device = device
 
     def screenshot(self, *, force: bool = False):
         """
         截图。返回截图数据，同时更新当前上下文的截图数据。
         """
+        check_flow_control()
         global next_wait, last_screenshot_time, next_wait_time
         current = ContextStackVars.ensure_current()
         if force:
@@ -735,26 +747,42 @@ class ContextDevice(Device):
         current._screenshot = img
         return img
 
-    def __getattribute__(self, name: str) -> Any:
-        if name in ['_device', 'screenshot']:
+    def __getattribute__(self, name: str):
+        if name in ['_device', 'screenshot', 'of_android', 'of_windows']:
             return object.__getattribute__(self, name)
         else:
             return getattr(self._device, name)
         
     def __setattr__(self, name: str, value: Any):
-        if name in ['_device', 'screenshot']:
+        if name in ['_device', 'screenshot', 'of_android', 'of_windows']:
             return object.__setattr__(self, name, value)
         else:
             return setattr(self._device, name, value)
 
+    def of_android(self) -> 'ContextDevice | AndroidDevice':
+        """
+        确保此 ContextDevice 底层为 Android 平台。
+        同时通过返回的对象可以调用 Android 平台特有的方法。
+        """
+        if not isinstance(self._device, AndroidDevice):
+            raise ValueError("Device is not AndroidDevice")
+        return self
+
+    def of_windows(self) -> 'ContextDevice | WindowsDevice':
+        """
+        确保此 ContextDevice 底层为 Windows 平台。
+        同时通过返回的对象可以调用 Windows 平台特有的方法。
+        """
+        if not isinstance(self._device, WindowsDevice):
+            raise ValueError("Device is not WindowsDevice")
+        return self
 
 class Context(Generic[T]):
     def __init__(
         self,
         config_path: str,
         config_type: Type[T],
-        screenshot_impl: Optional[DeviceImpl] = None,
-        device: Optional[Device] = None
+        device: Device
     ):
         self.__ocr = ContextOcr(self)
         self.__image = ContextImage(self)
@@ -762,14 +790,7 @@ class Context(Generic[T]):
         self.__vars = ContextGlobalVars()
         self.__debug = ContextDebug(self)
         self.__config = ContextConfig[T](self, config_path, config_type)
-        
-        ip = self.config.current.backend.adb_ip
-        port = self.config.current.backend.adb_port
-        # TODO: 处理链接失败情况
-        if screenshot_impl is None:
-            screenshot_impl = self.config.current.backend.screenshot_impl
-        logger.info(f'Using "{screenshot_impl}" as screenshot implementation')
-        self.__device = ContextDevice(device or create_device(f'{ip}:{port}', screenshot_impl))
+        self.__device = ContextDevice(device)
 
     def inject(
         self,
@@ -880,8 +901,7 @@ def init_context(
     config_path: str = 'config.json',
     config_type: Type[T] = dict[str, Any],
     force: bool = False,
-    screenshot_impl: Optional[DeviceImpl] = None,
-    target_device: Device | None = None,
+    target_device: Device,
 ):
     """
     初始化 Context 模块。
@@ -892,8 +912,6 @@ def init_context(
         默认为 `dict[str, Any]`，即普通的 JSON 数据，不包含任何类型信息。
     :param force:  是否强制重新初始化。
         若为 `True`，则忽略已存在的 Context 实例，并重新创建一个新的实例。
-    :param screenshot_impl: 截图实现。
-        若为 `None`，则使用默认配置文件中指定的截图实现。
     :param target_device: 目标设备
     """
     global _c, device, ocr, image, color, vars, debug, config
@@ -902,8 +920,7 @@ def init_context(
     _c = Context(
         config_path=config_path,
         config_type=config_type,
-        screenshot_impl=screenshot_impl,
-        device=target_device
+        device=target_device,
     )
     device._FORWARD_getter = lambda: _c.device # type: ignore
     ocr._FORWARD_getter = lambda: _c.ocr # type: ignore
@@ -950,5 +967,4 @@ def manual_context(screenshot_mode: ScreenshotMode = 'auto') -> ManualContextMan
     默认情况下，Context* 类仅允许在 @task/@action 函数中使用。
     如果想要在其他地方使用，使用此函数手动创建一个上下文。
     """
-    return ManualContextManager(screenshot_mode)
-
+    return ManualContextManager(screenshot_mode)

kotonebot/backend/debug/server.py

@@ -115,7 +115,7 @@ async def run_code(request: RunCodeRequest):
         except KeyboardInterrupt as e:
             result = {"status": "error", "result": stdout.getvalue(), "message": str(e), "traceback": traceback.format_exc()}
         finally:
-            context_vars.interrupted.clear()
+            context_vars.flow.clear_interrupt()
         event.set()
     threading.Thread(target=_runner, daemon=True).start()
     await event.wait()
@@ -124,8 +124,8 @@ async def run_code(request: RunCodeRequest):
 @app.get("/api/code/stop")
 async def stop_code():
     from kotonebot.backend.context import vars
-    vars.interrupted.set()
-    while vars.interrupted.is_set():
+    vars.flow.request_interrupt()
+    while vars.flow.is_interrupted:
         await asyncio.sleep(0.1)
     return {"status": "ok"}
 
@@ -216,8 +216,6 @@ def wait_message_all_done():
         threading.Thread(target=_wait, daemon=True).start()
 
 if __name__ == "__main__":
-    from kotonebot.backend.context import init_context
-    init_context()
     debug_vars.debug.hide_server_log = False
     process = subprocess.Popen(["pylsp", "--port", "5479", "--ws"])
     print("LSP started. PID=", process.pid)

kotonebot/backend/dispatch.py

@@ -328,20 +328,4 @@ class SimpleDispatcher:
                     self.result = self.timeout_result
                     break
             device.screenshot()
-        return self.result
-
-if __name__ == '__main__':
-    from .context.task_action import action
-    from .context import init_context
-    init_context()
-    @action('inner', dispatcher=True)
-    def inner(ctx: DispatcherContext):
-        print('inner')
-        ctx.finish()
-
-    @action('test', dispatcher=True)
-    def test(ctx: DispatcherContext):
-        print('test')
-        inner()
-        ctx.finish()
-    test()
+        return self.result

kotonebot/backend/flow_controller.py

@@ -0,0 +1,195 @@
+import time
+import logging
+import threading
+from typing import Literal
+
+logger = logging.getLogger(__name__)
+
+class FlowController:
+    """
+    一个用于控制任务执行流程（如停止、暂停、恢复）的类。
+
+    这个类是线程安全的，提供了以下功能：
+
+    * 停止任务执行（通过中断信号）
+    * 暂停/恢复任务执行
+    * 可中断和可暂停的 sleep 功能
+    * 流程状态检查
+
+    使用方法::
+
+        controller = FlowController()
+
+        # 在任务的关键路径上调用检查
+        controller.check()
+
+        # 使用可控制的 sleep
+        controller.sleep(1.0)
+
+        # 外部控制
+        controller.request_pause()  # 暂停
+        controller.request_resume()  # 恢复
+        controller.request_stop()   # 停止
+    """
+    
+    def __init__(self):
+        self.interrupt_event: threading.Event = threading.Event()
+        """中断事件，用于停止任务"""
+
+        self.paused: bool = False
+        """暂停标志"""
+
+        self.pause_condition: threading.Condition = threading.Condition()
+        """暂停条件变量，用于线程间同步"""
+    
+    def check(self) -> None:
+        """
+        检查当前流程状态。
+
+        如果收到停止请求，则抛出 KeyboardInterrupt 异常。
+        如果收到暂停请求，则阻塞直到恢复。
+
+        这是核心的检查点方法，应在任务的关键路径上（如循环或等待前）调用。
+
+        :raises KeyboardInterrupt: 当收到停止请求时
+        """
+        # 优先检查中断信号
+        if self.interrupt_event.is_set():
+            raise KeyboardInterrupt("User requested interrupt.")
+        
+        # 检查暂停状态
+        with self.pause_condition:
+            while self.paused:
+                self.pause_condition.wait()
+    
+    def sleep(self, seconds: float) -> None:
+        """
+        一个可被中断和暂停的 sleep 方法。
+
+        与标准的 time.sleep() 不同，这个方法会响应停止和暂停请求。
+        在暂停状态下，计时器会暂停，恢复后继续计时。
+
+        :param seconds: 睡眠时间（秒）
+        :raises KeyboardInterrupt: 当收到停止请求时
+        """
+        with self.pause_condition:
+            end_time = time.time() + seconds
+            while True:
+                self.check()  # 每次循环都检查状态
+                remaining = end_time - time.time()
+                if remaining <= 0:
+                    break
+                # 等待指定时间或直到被唤醒
+                self.pause_condition.wait(timeout=remaining)
+        
+        # 结束后再次检查状态
+        self.check()
+    
+    def request_interrupt(self) -> None:
+        """
+        请求停止任务。
+
+        设置中断信号，所有正在执行的任务将在下一个检查点停止。
+        停止的优先级高于暂停。
+        """
+        logger.info('Interrupt requested.')
+        self.interrupt_event.set()
+    
+    def request_pause(self) -> None:
+        """
+        请求暂停任务。
+
+        设置暂停标志，所有正在执行的任务将在下一个检查点暂停。
+        如果任务已经暂停，此操作无效果。
+        """
+        with self.pause_condition:
+            if not self.paused:
+                logger.info('Pause requested.')
+                self.paused = True
+    
+    def request_resume(self) -> None:
+        """
+        请求恢复任务。
+
+        清除暂停标志并通知所有等待的线程恢复执行。
+        如果任务没有暂停，此操作无效果。
+        """
+        with self.pause_condition:
+            if self.paused:
+                logger.info('Resume requested.')
+                self.paused = False
+                self.pause_condition.notify_all()
+    
+    def toggle_pause(self) -> bool:
+        """
+        切换暂停/恢复状态。
+
+        :returns: 操作后的暂停状态。True 表示已暂停，False 表示已恢复。
+        """
+        with self.pause_condition:
+            logger.info('Pause toggled.')
+            if self.paused:
+                self.paused = False
+                self.pause_condition.notify_all()
+                return False
+            else:
+                self.paused = True
+                return True
+    
+    def clear_interrupt(self) -> None:
+        """
+        清除中断信号。
+
+        用于任务正常结束或重启时重置状态。
+        通常在开始新任务前调用。
+        """
+        self.interrupt_event.clear()
+        logger.info('Interrupt cleared.')
+    
+    def reset(self) -> None:
+        """
+        重置流程控制器到初始状态。
+
+        清除所有信号和状态，相当于重新创建一个新的控制器。
+        """
+        self.interrupt_event.clear()
+        with self.pause_condition:
+            if self.paused:
+                self.paused = False
+                self.pause_condition.notify_all()
+        logger.info('FlowController reset.')
+    
+    @property
+    def is_interrupted(self) -> bool:
+        """
+        检查是否收到中断请求。
+
+        :returns: True 表示已收到中断请求
+        """
+        return self.interrupt_event.is_set()
+    
+    @property
+    def is_paused(self) -> bool:
+        """
+        检查是否处于暂停状态。
+
+        :returns: True 表示当前处于暂停状态
+        """
+        return self.paused
+    
+    @property
+    def status(self) -> Literal['running', 'paused', 'interrupted']:
+        """
+        获取当前状态的字符串描述。
+
+        :returns: 状态描述，可能的值：'running', 'paused', 'interrupted'
+        """
+        if self.is_interrupted:
+            return 'interrupted'
+        elif self.is_paused:
+            return 'paused'
+        else:
+            return 'running'
+    
+    def __repr__(self) -> str:
+        return f"FlowController(status='{self.status}')"