ksaa 2025.6.8.0__tar.gz → 2025.6.28.0__tar.gz

{ksaa-2025.6.8.0/ksaa.egg-info → ksaa-2025.6.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ksaa
-Version: 2025.6.8.0
+Version: 2025.6.28.0
 Summary: Kotones Auto Assistant(kaa) is a script for game 'Gakuen Idol M@ster' that automates the dailies and produces.
 Requires-Python: ~=3.10
 Description-Content-Type: text/markdown
@@ -106,6 +106,9 @@ kaa 的开发主要用到了以下开源项目：
 ](https://github.com/AllenHeartcore/GkmasObjectManager)：用于提取游戏图像资源，以 GPLv3 协议开源。
 * [gakumasu-diff](https://github.com/vertesan/gakumasu-diff)：游戏数据。
 
+kaa 的开发还参考了以下开源项目：
+* [EmulatorExtras](https://github.com/MaaXYZ/EmulatorExtras)：MuMu 与雷电模拟器的截图与控制接口定义。
+* [blue_archive_auto_script](https://github.com/pur1fying/blue_archive_auto_script)：MuMu 与雷电模拟器的截图与控制接口的 Python 实现，以及各模拟器的控制实现。
 
 ## 免责声明
 **请在使用本项目前仔细阅读以下内容。使用本脚本将带来包括但不限于账号被封禁的风险。**

{ksaa-2025.6.8.0 → ksaa-2025.6.28.0}/README.md

@@ -76,6 +76,9 @@ kaa 的开发主要用到了以下开源项目：
 ](https://github.com/AllenHeartcore/GkmasObjectManager)：用于提取游戏图像资源，以 GPLv3 协议开源。
 * [gakumasu-diff](https://github.com/vertesan/gakumasu-diff)：游戏数据。
 
+kaa 的开发还参考了以下开源项目：
+* [EmulatorExtras](https://github.com/MaaXYZ/EmulatorExtras)：MuMu 与雷电模拟器的截图与控制接口定义。
+* [blue_archive_auto_script](https://github.com/pur1fying/blue_archive_auto_script)：MuMu 与雷电模拟器的截图与控制接口的 Python 实现，以及各模拟器的控制实现。
 
 ## 免责声明
 **请在使用本项目前仔细阅读以下内容。使用本脚本将带来包括但不限于账号被封禁的风险。**

{ksaa-2025.6.8.0 → ksaa-2025.6.28.0}/WHATS_NEW.md

@@ -1,5 +1,52 @@
 # 更新日志
 ## kaa
+### v2025.6.28.0
+脚本：
+* [修复] 修正 debug_entry 脚本路径处理逻辑（#b53a055）
+* [修复] 修复清理日志功能失效的问题（#ad5c7b7）
+* [修复] 修复 debug_entry 执行的脚本没有正确输出日志的问题（#3ceae4c）
+
+界面：
+* [新增] 优化日志导出功能（#9574d20）
+* [新增] 为 UI 增加部分配置有效性验证（#08a7e71）
+* [新增] 加入调试模式警告提示（#a01c37d）
+* [新增] 画面 Tab 刷新机制由自动改为手动（#2469fc0）
+* [新增] MuMu12 保活模式可选开启（#71170e5）
+
+框架：
+* [修复] 修复 Device 中缩放与截图 Hook 的处理顺序不正确问题
+* [修复] 修复 NemuIpc 在多显示器下的坐标系问题（#87da282）
+* [修复] 修复当目标分辨率与实际分辨率旋转不同时截图会强制拉伸的问题（#e62e65d）
+* [修复] 缩放处理支持自动识别旋转（#677932a）
+* [修复] 修复 NemuIpc 截图无法响应屏幕旋转导致的分辨率变化（#105a894）
+* [新增] NemuIpcImpl 获取显示器 ID 支持自动重试（#0c94acf）
+* [新增] 支持 MuMu12 后台保活模式（#e232826）
+* [新增] 引入 Nemu 截图与控制方式（#f0b9181）
+* [新增] 移除 WindowsImpl 中的分辨率缩放（#415a8df）
+* [新增] 支持等比例分辨率缩放（#bb7f603）
+* [重构] 组装 Device 改用 recipe 方案（#f01e022）
+* [重构] 将传递的 MuMu 路径从 shell 目录改为 MuMu 根目录（#784b8ed）
+
+其他：
+* [其他] HsvRangeTool 支持从剪贴板粘贴图片（#1397587）
+* [其他] VSCode 新增不初始化 context 的启动配置（#0718678）
+* [其他] 调整部分日志输出格式（#bcd8cf2）
+
+### v2025.6.23.0
+脚本：
+* [新增] 优化了培育开始的逻辑，修复若干 bug（#86313ec）
+
+框架：
+* [修复] 修复由于分离 AndroidDevice 方法导致的 typing 问题（#4d76e1a）
+* [重构] 将 Commandable 分离为 WindowsCommandable 与 AndroidCommandable（#16a267d）
+* [重构] 将启动 remote_server 的逻辑移动到 kaa cli 中（#b8b5ba8）
+* [重构] 提取三个 adb-based 截图方法的工厂函数的共同部分（#bd57dc4）
+* [重构] 将创建设备的逻辑从 init_context 中移除（#f2599e6）
+* [重构] 重构 Device 与 Impl 的创建方式（#2fc9ad5）
+
+其他：
+* [其他] 更新上游 submodules（#810c341）
+
 ### v2025.6.8.0
 脚本：
 * [新增] 新增支持自动禁用与恢复 Gakumasu Localify 汉化插件（#264dac2）

{ksaa-2025.6.8.0 → ksaa-2025.6.28.0}/kotonebot/backend/context/context.py

@@ -25,7 +25,7 @@ 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 (
@@ -46,12 +46,10 @@ 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.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.backend.preprocessor import PreprocessorProtocol
 from kotonebot.primitives import Rect
 
@@ -717,9 +715,10 @@ 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):
@@ -746,26 +745,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)
@@ -773,14 +788,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,
@@ -891,8 +899,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 模块。
@@ -903,8 +910,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
@@ -913,8 +918,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

{ksaa-2025.6.8.0 → ksaa-2025.6.28.0}/kotonebot/backend/debug/server.py

@@ -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)

{ksaa-2025.6.8.0 → ksaa-2025.6.28.0}/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

ksaa-2025.6.28.0/kotonebot/backend/loop.py

@@ -0,0 +1,277 @@
+import time
+from functools import lru_cache, partial
+from typing import Callable, Any, overload, Literal, Generic, TypeVar, cast, get_args, get_origin
+
+from cv2.typing import MatLike
+
+from kotonebot.util import Interval
+from kotonebot import device, image, ocr
+from kotonebot.backend.core import Image
+from kotonebot.backend.ocr import TextComparator
+from kotonebot.client.protocol import ClickableObjectProtocol
+
+
+class LoopAction:
+    def __init__(self, loop: 'Loop', func: Callable[[], ClickableObjectProtocol | None]):
+        self.loop = loop
+        self.func = func
+        self.result: ClickableObjectProtocol | None = None
+
+    @property
+    def found(self):
+        """
+        是否找到结果。若父 Loop 未在运行中，则返回 False。
+        """
+        if not self.loop.running:
+            return False
+        return bool(self.result)
+
+    def __bool__(self):
+        return self.found
+
+    def reset(self):
+        """
+        重置 LoopAction，以复用此对象。
+        """
+        self.result = None
+
+    def do(self):
+        """
+        执行 LoopAction。
+        :return: 执行结果。
+        """
+        if not self.loop.running:
+            return
+        if self.loop.found_anything:
+            # 本轮循环已执行任意操作，因此不需要再继续检测
+            return
+        self.result = self.func()
+        if self.result:
+            self.loop.found_anything = True
+
+    def click(self, *, at: tuple[int, int] | None = None):
+        """
+        点击寻找结果。若结果为空，会跳过执行。
+
+        :return:
+        """
+        if self.result:
+            if at is not None:
+                device.click(*at)
+            else:
+                device.click(self.result)
+
+    def call(self, func: Callable[[ClickableObjectProtocol], Any]):
+        pass
+
+
+class Loop:
+    def __init__(
+            self,
+            *,
+            timeout: float = 300,
+            interval: float = 0.3,
+            auto_screenshot: bool = True
+    ):
+        self.running = True
+        self.found_anything = False
+        self.auto_screenshot = auto_screenshot
+        """
+        是否在每次循环开始时（Loop.tick() 被调用时）截图。
+        """
+        self.__last_loop: float = -1
+        self.__interval = Interval(interval)
+        self.screenshot: MatLike | None = None
+        """上次截图时的图像数据。"""
+
+    def __iter__(self):
+        self.__interval.reset()
+        return self
+
+    def __next__(self):
+        if not self.running:
+            raise StopIteration
+        self.found_anything = False
+        self.__last_loop = time.time()
+        return self.tick()
+
+    def tick(self):
+        self.__interval.wait()
+        if self.auto_screenshot:
+            self.screenshot = device.screenshot()
+        self.__last_loop = time.time()
+        self.found_anything = False
+        return self
+
+    def exit(self):
+        """
+        结束循环。
+        """
+        self.running = False
+
+    @overload
+    def when(self, condition: Image) -> LoopAction:
+        ...
+
+    @overload
+    def when(self, condition: TextComparator) -> LoopAction:
+        ...
+
+    def when(self, condition: Any):
+        """
+        判断某个条件是否成立。
+
+        :param condition:
+        :return:
+        """
+        if isinstance(condition, Image):
+            func = partial(image.find, condition)
+        elif isinstance(condition, TextComparator):
+            func = partial(ocr.find, condition)
+        else:
+            raise ValueError('Invalid condition type.')
+        la = LoopAction(self, func)
+        la.reset()
+        la.do()
+        return la
+
+    def until(self, condition: Any):
+        """
+        当满足指定条件时，结束循环。
+
+        等价于 ``loop.when(...).call(lambda _: loop.exit())``
+        """
+        return self.when(condition).call(lambda _: self.exit())
+
+    def click_if(self, condition: Any, *, at: tuple[int, int] | None = None):
+        """
+        检测指定对象是否出现，若出现，点击该对象或指定位置。
+
+        ``click_if()`` 等价于 ``loop.when(...).click(...)``。
+
+        :param condition: 检测目标。
+        :param at: 点击位置。若为 None，表示点击找到的目标。
+        """
+        return self.when(condition).click(at=at)
+
+StateType = TypeVar('StateType')
+class StatedLoop(Loop, Generic[StateType]):
+    def __init__(
+        self,
+        states: list[Any] | None = None,
+        initial_state: StateType | None = None,
+        *,
+        timeout: float = 300,
+        interval: float = 0.3,
+        auto_screenshot: bool = True
+    ):
+        self.__tmp_states = states
+        self.__tmp_initial_state = initial_state
+        self.state: StateType
+        super().__init__(timeout=timeout, interval=interval, auto_screenshot=auto_screenshot)
+
+    def __iter__(self):
+        # __retrive_state_values() 只能在非 __init__ 中调用
+        self.__retrive_state_values()
+        return super().__iter__()
+
+    def __retrive_state_values(self):
+        # HACK: __orig_class__ 是 undocumented 属性
+        if not hasattr(self, '__orig_class__'):
+            # 如果 Foo 不是以参数化泛型的方式实例化的，可能没有 __orig_class__
+            if self.state is None:
+                raise ValueError('Either specify `states` or use StatedLoop[Literal[...]] syntax.')
+        else:
+            generic_type_args = get_args(self.__orig_class__) # type: ignore
+            if len(generic_type_args) != 1:
+                raise ValueError('StatedLoop must have exactly one generic type argument.')
+            state_values = get_args(generic_type_args[0])
+            if not state_values:
+                raise ValueError('StatedLoop must have at least one state value.')
+            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)

ksaa-2025.6.28.0/kotonebot/client/__init__.py

@@ -0,0 +1,10 @@
+from .device import Device
+from .registration import DeviceImpl
+
+# 确保所有实现都被注册
+from . import implements  # noqa: F401
+
+__all__ = [
+    'Device',
+    'DeviceImpl',
+]