ksaa 2025.7.20.0__py3-none-any.whl → 2025.7.27.0__py3-none-any.whl

kotonebot/backend/bot.py

@@ -12,6 +12,15 @@ from kotonebot.client import Device
 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
+
+
+@dataclass
+class PostTaskContext:
+    has_error: bool
+    exception: Exception | None
+
 
 log_stream = io.StringIO()
 stream_handler = logging.StreamHandler(log_stream)
@@ -19,10 +28,11 @@ stream_handler.setFormatter(logging.Formatter('[%(asctime)s] [%(levelname)s] [%(
 logging.getLogger('kotonebot').addHandler(stream_handler)
 logger = logging.getLogger(__name__)
 
+TaskStatusValue = Literal['pending', 'running', 'finished', 'error', 'cancelled', 'stopped']
 @dataclass
 class TaskStatus:
     task: Task
-    status: Literal['pending', 'running', 'finished', 'error', 'cancelled']
+    status: TaskStatusValue
 
 @dataclass
 class RunStatus:
@@ -73,7 +83,7 @@ class Event(Generic[Params, Return]):
 class KotoneBotEvents:
     def __init__(self):
         self.task_status_changed = Event[
-            [Task, Literal['pending', 'running', 'finished', 'error', 'cancelled']], None
+            [Task, TaskStatusValue], None
         ]()
         self.task_error = Event[
             [Task, Exception], None
@@ -171,42 +181,80 @@ class KotoneBot:
         self._on_after_init_context()
         vars.flow.clear_interrupt()
 
+        pre_tasks = [task for task in tasks if task.run_at == 'pre']
+        regular_tasks = [task for task in tasks if task.run_at == 'regular']
+        post_tasks = [task for task in tasks if task.run_at == 'post']
+
         if by_priority:
-            tasks = sorted(tasks, key=lambda x: x.priority, reverse=True)
-        for task in tasks:
+            pre_tasks = sorted(pre_tasks, key=lambda x: x.priority, reverse=True)
+            regular_tasks = sorted(regular_tasks, key=lambda x: x.priority, reverse=True)
+            post_tasks = sorted(post_tasks, key=lambda x: x.priority, reverse=True)
+
+        all_tasks = pre_tasks + regular_tasks + post_tasks
+        for task in all_tasks:
             self.events.task_status_changed.trigger(task, 'pending')
 
-        for task in tasks:
+        has_error = False
+        exception: Exception | None = None
+
+        for task in all_tasks:
             logger.info(f'Task started: {task.name}')
             self.events.task_status_changed.trigger(task, 'running')
 
             if self.debug:
-                task.func()
+                if task.run_at == 'post':
+                    task.func(PostTaskContext(has_error, exception))
+                else:
+                    task.func()
             else:
                 try:
-                    task.func()
+                    if task.run_at == 'post':
+                        task.func(PostTaskContext(has_error, exception))
+                    else:
+                        task.func()
                     self.events.task_status_changed.trigger(task, 'finished')
+                except StopCurrentTask:
+                    logger.info(f'Task skipped/stopped: {task.name}')
+                    self.events.task_status_changed.trigger(task, 'stopped')
                 # 用户中止
                 except KeyboardInterrupt as e:
                     logger.exception('Keyboard interrupt detected.')
-                    for task1 in tasks[tasks.index(task):]:
+                    for task1 in all_tasks[all_tasks.index(task):]:
                         self.events.task_status_changed.trigger(task1, 'cancelled')
                     vars.flow.clear_interrupt()
                     break
+                # 用户可以自行处理的错误
+                except UserFriendlyError as e:
+                    logger.error(f'Task failed: {task.name}')
+                    logger.exception(f'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)
                 # 其他错误
                 except Exception as e:
                     logger.error(f'Task failed: {task.name}')
                     logger.exception(f'Error: ')
+                    has_error = True
+                    exception = e
                     report_path = None
                     if self.auto_save_error_report:
                         raise NotImplementedError
                     self.events.task_status_changed.trigger(task, 'error')
                     if not self.resume_on_error:
-                        for task1 in tasks[tasks.index(task)+1:]:
+                        for task1 in all_tasks[all_tasks.index(task)+1:]:
                             self.events.task_status_changed.trigger(task1, 'cancelled')
                         break
-            logger.info(f'Task finished: {task.name}')
-        logger.info('All tasks finished.')
+            logger.info(f'Task ended: {task.name}')
+        logger.info('All tasks ended.')
         self.events.finished.trigger()
 
     def run_all(self) -> None:
@@ -228,7 +276,7 @@ class KotoneBot:
             self.events.finished -= _on_finished
             self.events.task_status_changed -= _on_task_status_changed
 
-        def _on_task_status_changed(task: Task, status: Literal['pending', 'running', 'finished', 'error', 'cancelled']):
+        def _on_task_status_changed(task: Task, status: TaskStatusValue):
             def _find(task: Task) -> TaskStatus:
                 for task_status in run_status.tasks:
                     if task_status.task == task:

kotonebot/backend/context/task_action.py

@@ -1,19 +1,18 @@
 import logging
-from typing import Callable, ParamSpec, TypeVar, overload, Concatenate, Literal
+from typing import Callable, ParamSpec, TypeVar, overload, Literal
 from dataclasses import dataclass
-from typing_extensions import deprecated
 
-import cv2
-from cv2.typing import MatLike
 
 from .context import ContextStackVars, ScreenshotMode
-from ..dispatch import dispatcher as dispatcher_decorator, DispatcherContext
 from ...errors import TaskNotFoundError
 
 P = ParamSpec('P')
 R = TypeVar('R')
 logger = logging.getLogger(__name__)
 
+TaskRunAtType = Literal['pre', 'post', 'manual', 'regular'] | str
+
+
 @dataclass
 class Task:
     name: str
@@ -24,6 +23,8 @@ class Task:
     """
     任务优先级，数字越大优先级越高。
     """
+    run_at: TaskRunAtType = 'regular'
+
 
 @dataclass
 class Action:
@@ -51,6 +52,7 @@ def task(
     pass_through: bool = False,
     priority: int = 0,
     screenshot_mode: ScreenshotMode = 'auto',
+    run_at: TaskRunAtType = 'regular'
 ):
     """
     `task` 装饰器，用于标记一个函数为任务函数。
@@ -62,6 +64,7 @@ def task(
         默认情况下， @task 装饰器会包裹任务函数，跟踪其执行情况。
         如果不想跟踪，则设置此参数为 False。
     :param priority: 任务优先级，数字越大优先级越高。
+    :param run_at: 任务运行时间。
     """
     # 设置 ID
     # 获取 caller 信息
@@ -70,7 +73,7 @@ def task(
         description = description or func.__doc__ or ''
         # TODO: task_id 冲突检测
         task_id = task_id or func.__name__
-        task = Task(name, task_id, description, _placeholder, priority)
+        task = Task(name, task_id, description, _placeholder, priority, run_at)
         task_registry[name] = task
         logger.debug(f'Task "{name}" registered.')
         if pass_through:
@@ -98,7 +101,6 @@ def action(
     pass_through: bool = False,
     priority: int = 0,
     screenshot_mode: ScreenshotMode | None = None,
-    dispatcher: Literal[False] = False,
 ) -> Callable[[Callable[P, R]], Callable[P, R]]:
     """
     `action` 装饰器，用于标记一个函数为动作函数。
@@ -110,38 +112,6 @@ def action(
         如果不想跟踪，则设置此参数为 False。
     :param priority: 动作优先级，数字越大优先级越高。
     :param screenshot_mode: 截图模式。
-    :param dispatcher: 
-        是否为分发器模式。默认为假。
-        如果使用分发器，则函数的第一个参数必须为 `ctx: DispatcherContext`。
-    """
-    ...
-
-@overload
-@deprecated('使用普通 while 循环代替')
-def action(
-    name: str,
-    *,
-    description: str|None = None,
-    pass_through: bool = False,
-    priority: int = 0,
-    screenshot_mode: ScreenshotMode | None = None,
-    dispatcher: Literal[True, 'fragment'] = True,
-) -> Callable[[Callable[Concatenate[DispatcherContext, P], R]], Callable[P, R]]:
-    """
-    `action` 装饰器，用于标记一个函数为动作函数。
-
-    此重载启用了分发器模式。被装饰函数的第一个参数必须为 `ctx: DispatcherContext`。
-
-    :param name: 动作名称。如果为 None，则使用函数的名称作为名称。
-    :param description: 动作描述。如果为 None，则使用函数的 docstring 作为描述。
-    :param pass_through: 
-        默认情况下， @action 装饰器会包裹动作函数，跟踪其执行情况。
-        如果不想跟踪，则设置此参数为 False。
-    :param priority: 动作优先级，数字越大优先级越高。
-    :param screenshot_mode: 截图模式，必须为 `'manual' / None`。
-    :param dispatcher: 
-        是否为分发器模式。默认为假。
-        如果使用分发器，则函数的第一个参数必须为 `ctx: DispatcherContext`。
     """
     ...
 
@@ -176,11 +146,6 @@ def action(*args, **kwargs):
         pass_through = kwargs.get('pass_through', False)
         priority = kwargs.get('priority', 0)
         screenshot_mode = kwargs.get('screenshot_mode', None)
-        dispatcher = kwargs.get('dispatcher', False)
-        if dispatcher == True or dispatcher == 'fragment':
-            if not (screenshot_mode is None or screenshot_mode == 'manual'):
-                raise ValueError('`screenshot_mode` must be None or "manual" when `dispatcher=True`.')
-            screenshot_mode = 'manual'
         def _action_decorator(func: Callable):
             nonlocal pass_through
             action = _register(_placeholder, name, description)
@@ -188,8 +153,6 @@ def action(*args, **kwargs):
             if pass_through:
                 return func
             else:
-                if dispatcher:
-                    func = dispatcher_decorator(func, fragment=(dispatcher == 'fragment')) # type: ignore
                 def _wrapper(*args: P.args, **kwargs: P.kwargs):
                     current_callstack.append(action)
                     vars = ContextStackVars.push(screenshot_mode=screenshot_mode)

kotonebot/backend/dispatch.py

@@ -1,12 +1,7 @@
 import time
-import uuid
 import logging
-import inspect
-from logging import Logger
-from types import CodeType
 from dataclasses import dataclass
-from typing import Annotated, Any, Callable, Concatenate, Sequence, TypeVar, ParamSpec, Literal, Protocol, cast
-from typing_extensions import deprecated
+from typing import Any, Callable, Literal
 
 from dataclasses import dataclass
 
@@ -16,104 +11,6 @@ from kotonebot.primitives import Rect, is_rect
 from .core import Image
 
 logger = logging.getLogger(__name__)
-P = ParamSpec('P')
-R = TypeVar('R')
-ThenAction = Literal['click', 'log']
-DoAction = Literal['click']
-# TODO: 需要找个地方统一管理这些属性名
-ATTR_DISPATCHER_MARK = '__kb_dispatcher_mark'
-ATTR_ORIGINAL_FUNC = '_kb_inner'
-
-
-class DispatchFunc: pass
-
-wrapper_to_func: dict[Callable, Callable] = {}
-
-class DispatcherContext:
-    def __init__(self):
-        self.finished: bool = False
-        self._first_run: bool = True
-    
-    def finish(self):
-        """标记已完成 dispatcher 循环。循环将在下次条件检测时退出。"""
-        self.finished = True
-
-    def expand(self, func: Annotated[Callable[[], Any], DispatchFunc], ignore_finish: bool = True):
-        """
-        调用其他 dispatcher 函数。
-
-        使用 `expand` 和直接调用的区别是：
-        * 直接调用会执行 while 循环，直到满足结束条件
-        * 而使用 `expand` 则只会执行一次。效果类似于将目标函数里的代码直接复制粘贴过来。
-        """
-        # 获取原始函数
-        original_func = func
-        while not getattr(original_func, ATTR_DISPATCHER_MARK, False):
-            original_func = getattr(original_func, ATTR_ORIGINAL_FUNC)
-        original_func = getattr(original_func, ATTR_ORIGINAL_FUNC)
-
-        if not original_func:
-            raise ValueError(f'{repr(func)} is not a dispatcher function.')
-        elif not callable(original_func):
-            raise ValueError(f'{repr(original_func)} is not callable.')
-        original_func = cast(Callable[[DispatcherContext], Any], original_func)
-
-        old_finished = self.finished
-        ret = original_func(self)
-        if ignore_finish:
-            self.finished = old_finished
-        return ret
-
-    @property
-    def beginning(self) -> bool:
-        """是否为第一次运行"""
-        return self._first_run
-    
-    @property
-    def finishing(self) -> bool:
-        """是否即将结束运行"""
-        return self.finished
-
-@deprecated('使用 SimpleDispatcher 类或 while 循环替代')
-def dispatcher(
-        func: Callable[Concatenate[DispatcherContext, P], R],
-        *,
-        fragment: bool = False
-    ) -> Annotated[Callable[P, R], DispatchFunc]:
-    """
-    注意：\n
-    此装饰器必须在应用 @action/@task 装饰器后再应用，且 `screenshot_mode='manual'` 参数必须设置。
-    或者也可以使用 @action/@task 装饰器中的 `dispatcher=True` 参数，
-    那么就没有上面两个要求了。
-
-    :param fragment:
-        片段模式，默认不启用。
-        启用后，被装饰函数将会只执行依次，
-        而不会一直循环到 ctx.finish() 被调用。
-    """
-    def wrapper(*args: P.args, **kwargs: P.kwargs):
-        ctx = DispatcherContext()
-        while not ctx.finished:
-            from kotonebot import device
-            device.screenshot()
-            ret = func(ctx, *args, **kwargs)
-            ctx._first_run = False
-        return ret
-    def fragment_wrapper(*args: P.args, **kwargs: P.kwargs):
-        ctx = DispatcherContext()
-        from kotonebot import device
-        device.screenshot()
-        return func(ctx, *args, **kwargs)
-    setattr(wrapper, ATTR_ORIGINAL_FUNC, func)
-    setattr(fragment_wrapper, ATTR_ORIGINAL_FUNC, func)
-    setattr(wrapper, ATTR_DISPATCHER_MARK, True)
-    setattr(fragment_wrapper, ATTR_DISPATCHER_MARK, True)
-    wrapper_to_func[wrapper] = func
-    if fragment:
-        return fragment_wrapper
-
-    else:
-        return wrapper
 
 @dataclass
 class ClickParams:

kotonebot/backend/flow_controller.py

@@ -95,7 +95,7 @@ class FlowController:
         logger.info('Interrupt requested.')
         self.interrupt_event.set()
     
-    def request_pause(self) -> None:
+    def request_pause(self, *, wait_resume: bool = False) -> None:
         """
         请求暂停任务。
 
@@ -106,6 +106,8 @@ class FlowController:
             if not self.paused:
                 logger.info('Pause requested.')
                 self.paused = True
+            if wait_resume:
+                self.check()
     
     def request_resume(self) -> None:
         """

kotonebot/errors.py

@@ -1,9 +1,41 @@
+from typing import Callable
+
+
 class KotonebotError(Exception):
     pass
 
 class KotonebotWarning(Warning):
     pass
 
+class UserFriendlyError(KotonebotError):
+    def __init__(
+        self,
+        message: str,
+        actions: list[tuple[int, str, Callable[[], None]]] = [],
+        *args, **kwargs
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self.message = message
+        self.actions = actions or []
+
+    @property
+    def action_buttons(self) -> list[tuple[int, str]]:
+        """
+        以 (id: int, btn_text: str) 的形式返回所有按钮定义。
+        """
+        return [(id, text) for id, text, _ in self.actions]
+    
+    def invoke(self, action_id: int):
+        """
+        执行指定 ID 的 action。
+        """
+        for id, _, func in self.actions:
+            if id == action_id:
+                func()
+                break
+        else:
+            raise ValueError(f'Action with id {action_id} not found.')
+
 class UnrecoverableError(KotonebotError):
     pass
 
@@ -31,7 +63,10 @@ class UnscalableResolutionError(KotonebotError):
         self.screen_size = screen_size
         super().__init__(f'Cannot scale to target resolution {target_resolution}. '
                          f'Screen size: {screen_size}')
-        
+
 class ContextNotInitializedError(KotonebotError):
     def __init__(self, msg: str = 'Context not initialized'):
-        super().__init__(msg)
+        super().__init__(msg)
+
+class StopCurrentTask(KotonebotError):
+    pass