ksaa 2025.7.5.0__py3-none-any.whl → 2025.7.9.0__py3-none-any.whl

kotonebot/backend/bot.py

@@ -145,6 +145,18 @@ class KotoneBot:
         """
         raise NotImplementedError('Implement `_create_device` before using Kotonebot.')
 
+    def _on_init_context(self) -> None:
+        """
+        初始化 Context 的钩子方法。子类可以重写此方法来自定义初始化逻辑。
+        默认实现调用 init_context 而不传入 target_screenshot_interval。
+        """
+        d = self._on_create_device()
+        init_context(
+            config_path=self.config_path,
+            config_type=self.config_type,
+            target_device=d
+        )
+
     def _on_after_init_context(self):
         """
         抽象方法，在 init_context() 被调用后立即执行。
@@ -155,8 +167,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_init_context()
         self._on_after_init_context()
         vars.flow.clear_interrupt()
 

kotonebot/backend/context/context.py

@@ -27,6 +27,7 @@ from cv2.typing import MatLike
 
 from kotonebot.client.device import Device, AndroidDevice, WindowsDevice
 from kotonebot.backend.flow_controller import FlowController
+from kotonebot.util import Interval
 import kotonebot.backend.image as raw_image
 from kotonebot.backend.image import (
     TemplateMatchResult,
@@ -284,11 +285,17 @@ class ContextOcr:
         self.context = context
         self.__engine = jp()
 
-    def raw(self, lang: OcrLanguage = 'jp') -> Ocr:
+    def _get_engine(self, lang: OcrLanguage | None = None) -> Ocr:
+        """获取指定语言的OCR引擎，如果lang为None则使用默认引擎。"""
+        return self.__engine if lang is None else self.raw(lang)
+
+    def raw(self, lang: OcrLanguage | None = None) -> Ocr:
         """
         返回 `kotonebot.backend.ocr` 中的 Ocr 对象。\n
         Ocr 对象与此对象（ContextOcr）的区别是，此对象会自动截图，而 Ocr 对象需要手动传入图像参数。
         """
+        if lang is None:
+            lang = 'jp'
         match lang:
             case 'jp':
                 return jp()
@@ -300,9 +307,11 @@ class ContextOcr:
     def ocr(
         self,
         rect: Rect | None = None,
+        lang: OcrLanguage | None = None,
     ) -> OcrResultList:
         """OCR 当前设备画面或指定图像。"""
-        return self.__engine.ocr(ContextStackVars.ensure_current().screenshot, rect=rect)
+        engine = self._get_engine(lang)
+        return engine.ocr(ContextStackVars.ensure_current().screenshot, rect=rect)
 
     def find(
         self,
@@ -310,9 +319,11 @@ class ContextOcr:
         *,
         hint: HintBox | None = None,
         rect: Rect | None = None,
+        lang: OcrLanguage | None = None,
     ) -> OcrResult | None:
         """检查当前设备画面是否包含指定文本。"""
-        ret = self.__engine.find(
+        engine = self._get_engine(lang)
+        ret = engine.find(
             ContextStackVars.ensure_current().screenshot,
             pattern,
             hint=hint,
@@ -327,9 +338,10 @@ class ContextOcr:
         *,
         hint: HintBox | None = None,
         rect: Rect | None = None,
-
+        lang: OcrLanguage | None = None,
     ) -> list[OcrResult | None]:
-        return self.__engine.find_all(
+        engine = self._get_engine(lang)
+        return engine.find_all(
             ContextStackVars.ensure_current().screenshot,
             list(patterns),
             hint=hint,
@@ -342,6 +354,7 @@ class ContextOcr:
         *,
         rect: Rect | None = None,
         hint: HintBox | None = None,
+        lang: OcrLanguage | None = None,
     ) -> OcrResult:
 
         """
@@ -349,7 +362,8 @@ class ContextOcr:
 
         与 `find()` 的区别在于，`expect()` 未找到时会抛出异常。
         """
-        ret = self.__engine.expect(ContextStackVars.ensure_current().screenshot, pattern, rect=rect, hint=hint)
+        engine = self._get_engine(lang)
+        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
     
@@ -718,8 +732,20 @@ class Forwarded:
 
 T_Device = TypeVar('T_Device', bound=Device)
 class ContextDevice(Generic[T_Device], Device):
-    def __init__(self, device: T_Device):
+    def __init__(self, device: T_Device, target_screenshot_interval: float | None = None):
+        """
+        :param device: 目标设备。
+        :param target_screenshot_interval: 见 `ContextDevice.target_screenshot_interval`。
+        """
         self._device = device
+        self.target_screenshot_interval: float | None = target_screenshot_interval
+        """
+        目标截图间隔，可用于限制截图速度。若两次截图实际间隔小于该值，则会自动等待。
+        为 None 时不限制截图速度。
+        """
+        self._screenshot_interval: Interval | None = None
+        if self.target_screenshot_interval is not None:
+            self._screenshot_interval = Interval(self.target_screenshot_interval)
 
     def screenshot(self, *, force: bool = False):
         """
@@ -734,6 +760,9 @@ class ContextDevice(Generic[T_Device], Device):
             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:
@@ -780,7 +809,8 @@ class Context(Generic[T]):
         self,
         config_path: str,
         config_type: Type[T],
-        device: Device
+        device: Device,
+        target_screenshot_interval: float | None = None
     ):
         self.__ocr = ContextOcr(self)
         self.__image = ContextImage(self)
@@ -788,7 +818,7 @@ class Context(Generic[T]):
         self.__vars = ContextGlobalVars()
         self.__debug = ContextDebug(self)
         self.__config = ContextConfig[T](self, config_path, config_type)
-        self.__device = ContextDevice(device)
+        self.__device = ContextDevice(device, target_screenshot_interval)
 
     def inject(
         self,
@@ -900,6 +930,7 @@ def init_context(
     config_type: Type[T] = dict[str, Any],
     force: bool = False,
     target_device: Device,
+    target_screenshot_interval: float | None = None,
 ):
     """
     初始化 Context 模块。
@@ -911,6 +942,7 @@ def init_context(
     :param force:  是否强制重新初始化。
         若为 `True`，则忽略已存在的 Context 实例，并重新创建一个新的实例。
     :param target_device: 目标设备
+    :param target_screenshot_interval: 见 `ContextDevice.target_screenshot_interval`。
     """
     global _c, device, ocr, image, color, vars, debug, config
     if _c is not None and not force:
@@ -919,6 +951,7 @@ def init_context(
         config_path=config_path,
         config_type=config_type,
         device=target_device,
+        target_screenshot_interval=target_screenshot_interval,
     )
     device._FORWARD_getter = lambda: _c.device # type: ignore
     ocr._FORWARD_getter = lambda: _c.ocr # type: ignore

kotonebot/config/base_config.py

@@ -50,6 +50,8 @@ class BackendConfig(ConfigBaseModel):
     """Windows 截图方式的 AutoHotkey 可执行文件路径，为 None 时使用默认路径"""
     mumu_background_mode: bool = False
     """MuMu12 模拟器后台保活模式"""
+    target_screenshot_interval: float | None = None
+    """最小截图间隔，单位为秒。为 None 时不限制截图速度。"""
 
 class PushConfig(ConfigBaseModel):
     """推送配置。"""