MaaFw 4.4.0a3__py3-none-macosx_13_0_x86_64.whl → 5.0.0b2__py3-none-macosx_13_0_x86_64.whl

maa/agent/agent_server.py

@@ -1,9 +1,8 @@
 import ctypes
-import sys
 
 from ..define import *
 from ..library import Library
-from ..buffer import StringBuffer
+from ..event_sink import EventSink
 
 
 class AgentServer:
@@ -88,12 +87,94 @@ class AgentServer:
         Library.agent_server().MaaAgentServerJoin()
 
     @staticmethod
-    def detach(self) -> None:
+    def detach() -> None:
 
         AgentServer._set_api_properties()
 
         Library.agent_server().MaaAgentServerDetach()
 
+    _sink_holder: Dict[int, "EventSink"] = {}
+
+    @staticmethod
+    def resource_sink():
+        def wrapper_sink(sink):
+            AgentServer.add_resource_sink(sink=sink())
+            return sink
+
+        return wrapper_sink
+
+    @staticmethod
+    def add_resource_sink(sink: "ResourceEventSink") -> None:
+        sink_id = int(
+            Library.agent_server().MaaAgentServerAddResourceSink(
+                *EventSink._gen_c_param(sink)
+            )
+        )
+        if sink_id == MaaInvalidId:
+            return None
+
+        AgentServer._sink_holder[sink_id] = sink
+
+    @staticmethod
+    def controller_sink():
+        def wrapper_sink(sink):
+            AgentServer.add_controller_sink(sink=sink())
+            return sink
+
+        return wrapper_sink
+
+    @staticmethod
+    def add_controller_sink(sink: "ControllerEventSink") -> None:
+        sink_id = int(
+            Library.agent_server().MaaAgentServerAddControllerSink(
+                *EventSink._gen_c_param(sink)
+            )
+        )
+        if sink_id == MaaInvalidId:
+            return None
+
+        AgentServer._sink_holder[sink_id] = sink
+
+    @staticmethod
+    def tasker_sink():
+        def wrapper_sink(sink):
+            AgentServer.add_tasker_sink(sink=sink())
+            return sink
+
+        return wrapper_sink
+
+    @staticmethod
+    def add_tasker_sink(sink: "TaskerEventSink") -> None:
+        sink_id = int(
+            Library.agent_server().MaaAgentServerAddTaskerSink(
+                *EventSink._gen_c_param(sink)
+            )
+        )
+        if sink_id == MaaInvalidId:
+            return None
+
+        AgentServer._sink_holder[sink_id] = sink
+
+    @staticmethod
+    def context_sink():
+        def wrapper_sink(sink):
+            AgentServer.add_context_sink(sink=sink())
+            return sink
+
+        return wrapper_sink
+
+    @staticmethod
+    def add_context_sink(sink: "ContextEventSink") -> None:
+        sink_id = int(
+            Library.agent_server().MaaAgentServerAddContextSink(
+                *EventSink._gen_c_param(sink)
+            )
+        )
+        if sink_id == MaaInvalidId:
+            return None
+
+        AgentServer._sink_holder[sink_id] = sink
+
     _api_properties_initialized: bool = False
 
     @staticmethod
@@ -130,3 +211,27 @@ class AgentServer:
 
         Library.agent_server().MaaAgentServerDetach.restype = None
         Library.agent_server().MaaAgentServerDetach.argtypes = []
+
+        Library.agent_server().MaaAgentServerAddResourceSink.restype = MaaSinkId
+        Library.agent_server().MaaAgentServerAddResourceSink.argtypes = [
+            MaaEventCallback,
+            ctypes.c_void_p,
+        ]
+
+        Library.agent_server().MaaAgentServerAddControllerSink.restype = MaaSinkId
+        Library.agent_server().MaaAgentServerAddControllerSink.argtypes = [
+            MaaEventCallback,
+            ctypes.c_void_p,
+        ]
+
+        Library.agent_server().MaaAgentServerAddTaskerSink.restype = MaaSinkId
+        Library.agent_server().MaaAgentServerAddTaskerSink.argtypes = [
+            MaaEventCallback,
+            ctypes.c_void_p,
+        ]
+
+        Library.agent_server().MaaAgentServerAddContextSink.restype = MaaSinkId
+        Library.agent_server().MaaAgentServerAddContextSink.argtypes = [
+            MaaEventCallback,
+            ctypes.c_void_p,
+        ]

maa/agent_client.py

@@ -3,6 +3,8 @@ import ctypes
 from .define import *
 from .library import Library
 from .resource import Resource
+from .controller import Controller
+from .tasker import Tasker
 from .buffer import StringBuffer
 
 
@@ -47,6 +49,30 @@ class AgentClient:
             )
         )
 
+    def register_sink(
+        self, resource: Resource, controller: Controller, tasker: Tasker
+    ) -> bool:
+        # avoid gc
+        self._sinks = [resource, controller, tasker]
+
+        return (
+            bool(
+                Library.agent_client().MaaAgentClientRegisterResourceSink(
+                    self._handle, resource._handle
+                )
+            )
+            and bool(
+                Library.agent_client().MaaAgentClientRegisterControllerSink(
+                    self._handle, controller._handle
+                )
+            )
+            and bool(
+                Library.agent_client().MaaAgentClientRegisterTaskerSink(
+                    self._handle, tasker._handle
+                )
+            )
+        )
+
     def connect(self) -> bool:
         return bool(Library.agent_client().MaaAgentClientConnect(self._handle))
 
@@ -62,7 +88,11 @@ class AgentClient:
         return bool(Library.agent_client().MaaAgentClientAlive(self._handle))
 
     def set_timeout(self, milliseconds: int) -> bool:
-        return bool(Library.agent_client().MaaAgentClientSetTimeout(self._handle, ctypes.c_int64(milliseconds)))
+        return bool(
+            Library.agent_client().MaaAgentClientSetTimeout(
+                self._handle, ctypes.c_int64(milliseconds)
+            )
+        )
 
     _api_properties_initialized: bool = False
 
@@ -96,6 +126,24 @@ class AgentClient:
             MaaResourceHandle,
         ]
 
+        Library.agent_client().MaaAgentClientRegisterResourceSink.restype = MaaBool
+        Library.agent_client().MaaAgentClientRegisterResourceSink.argtypes = [
+            MaaAgentClientHandle,
+            MaaResourceHandle,
+        ]
+
+        Library.agent_client().MaaAgentClientRegisterControllerSink.restype = MaaBool
+        Library.agent_client().MaaAgentClientRegisterControllerSink.argtypes = [
+            MaaAgentClientHandle,
+            MaaControllerHandle,
+        ]
+
+        Library.agent_client().MaaAgentClientRegisterTaskerSink.restype = MaaBool
+        Library.agent_client().MaaAgentClientRegisterTaskerSink.argtypes = [
+            MaaAgentClientHandle,
+            MaaTaskerHandle,
+        ]
+
         Library.agent_client().MaaAgentClientConnect.restype = MaaBool
         Library.agent_client().MaaAgentClientConnect.argtypes = [
             MaaAgentClientHandle,

maa/context.py

@@ -1,13 +1,15 @@
 import ctypes
 import json
-from typing import Dict, Optional, Tuple
+from typing import Any, Dict, Optional, Tuple, Union
 
 import numpy
 
+from .event_sink import EventSink, NotificationType
 from .buffer import ImageBuffer, RectBuffer, StringBuffer, StringListBuffer
 from .define import *
 from .library import Library
 from .tasker import Tasker
+from .pipeline import JPipelineData, JPipelineParser
 from .job import JobWithResult
 
 
@@ -32,6 +34,15 @@ class Context:
     def run_task(
         self, entry: str, pipeline_override: Dict = {}
     ) -> Optional[TaskDetail]:
+        """同步执行任务 / Synchronously execute task
+
+        Args:
+            entry: 任务入口 / Task entry
+            pipeline_override: 用于覆盖的 json / JSON for overriding
+
+        Returns:
+            Optional[TaskDetail]: 任务详情，执行失败则返回 None / Task detail, or None if execution failed
+        """
         task_id = int(
             Library.framework().MaaContextRunTask(
                 self._handle, *Context._gen_post_param(entry, pipeline_override)
@@ -43,8 +54,24 @@ class Context:
         return self.tasker.get_task_detail(task_id)
 
     def run_recognition(
-        self, entry: str, image: numpy.ndarray, pipeline_override: Dict = {}
+        self,
+        entry: str,
+        image: numpy.ndarray,
+        pipeline_override: Dict = {},
     ) -> Optional[RecognitionDetail]:
+        """同步执行识别逻辑 / Synchronously execute recognition logic
+
+        不会执行后续操作, 不会执行后续 next
+        Will not execute subsequent operations or next steps
+
+        Args:
+            entry: 任务名 / Task name
+            image: 前序截图 / Previous screenshot
+            pipeline_override: 用于覆盖的 json / JSON for overriding
+
+        Returns:
+            Optional[RecognitionDetail]: 识别详情，执行失败则返回 None / Recognition detail, or None if execution failed
+        """
         image_buffer = ImageBuffer()
         image_buffer.set(image)
         reco_id = int(
@@ -66,6 +93,20 @@ class Context:
         reco_detail: str = "",
         pipeline_override: Dict = {},
     ) -> Optional[NodeDetail]:
+        """同步执行操作逻辑 / Synchronously execute action logic
+
+        不会执行后续 next
+        Will not execute subsequent next steps
+
+        Args:
+            entry: 任务名 / Task name
+            box: 前序识别位置 / Previous recognition position
+            reco_detail: 前序识别详情 / Previous recognition details
+            pipeline_override: 用于覆盖的 json / JSON for overriding
+
+        Returns:
+            Optional[NodeDetail]: 节点详情，执行失败则返回 None / Node detail, or None if execution failed
+        """
         rect = RectBuffer()
         rect.set(box)
 
@@ -84,14 +125,36 @@ class Context:
         return self.tasker.get_node_detail(node_id)
 
     def override_pipeline(self, pipeline_override: Dict) -> bool:
+        """覆盖 pipeline / Override pipeline_override
+
+        Args:
+            pipeline_override: 用于覆盖的 json / JSON for overriding
+
+        Returns:
+            bool: 是否成功 / Whether successful
+        """
+        pipeline_json = json.dumps(pipeline_override, ensure_ascii=False)
+
         return bool(
             Library.framework().MaaContextOverridePipeline(
                 self._handle,
-                json.dumps(pipeline_override, ensure_ascii=False).encode(),
+                pipeline_json.encode(),
             )
         )
 
     def override_next(self, name: str, next_list: List[str]) -> bool:
+        """覆盖任务的 next 列表 / Override the next list of task
+
+        如果节点不存在，此方法会失败
+        This method will fail if the node does not exist
+
+        Args:
+            name: 任务名 / Task name
+            next_list: next 列表 / Next list
+
+        Returns:
+            bool: 成功返回 True，如果节点不存在则返回 False / Returns True on success, False if node does not exist
+        """
         list_buffer = StringListBuffer()
         list_buffer.set(next_list)
 
@@ -101,7 +164,34 @@ class Context:
             )
         )
 
-    def get_node_data(self, name: str) -> Optional[dict]:
+    def override_image(self, image_name: str, image: numpy.ndarray) -> bool:
+        """覆盖图片 / Override the image corresponding to image_name
+
+        Args:
+            image_name: 图片名 / Image name
+            image: 图片数据 / Image data
+
+        Returns:
+            bool: 是否成功 / Whether successful
+        """
+        image_buffer = ImageBuffer()
+        image_buffer.set(image)
+
+        return bool(
+            Library.framework().MaaContextOverrideImage(
+                self._handle, image_name.encode(), image_buffer._handle
+            )
+        )
+
+    def get_node_data(self, name: str) -> Optional[Dict]:
+        """获取任务当前的定义 / Get the current definition of task
+
+        Args:
+            name: 任务名 / Task name
+
+        Returns:
+            Optional[Dict]: 任务定义字典，如果不存在则返回 None / Task definition dict, or None if not exists
+        """
         string_buffer = StringBuffer()
         if not Library.framework().MaaContextGetNodeData(
             self._handle, name.encode(), string_buffer._handle
@@ -117,11 +207,32 @@ class Context:
         except json.JSONDecodeError:
             return None
 
+    def get_node_object(self, name: str) -> Optional[JPipelineData]:
+        node_data = self.get_node_data(name)
+
+        if not node_data:
+            return None
+
+        return JPipelineParser.parse_pipeline_data(node_data)
+
     @property
     def tasker(self) -> Tasker:
+        """获取实例 / Get instance
+
+        Returns:
+            Tasker: 实例对象 / Instance object
+        """
         return self._tasker
 
     def get_task_job(self) -> JobWithResult:
+        """获取对应任务号的任务作业 / Get task job for corresponding task id
+
+        Returns:
+            JobWithResult: 任务作业对象 / Task job object
+
+        Raises:
+            ValueError: 如果任务 id 为 None
+        """
         task_id = Library.framework().MaaContextGetTaskId(self._handle)
         if not task_id:
             raise ValueError("task_id is None")
@@ -129,6 +240,14 @@ class Context:
         return self.tasker._gen_task_job(task_id)
 
     def clone(self) -> "Context":
+        """复制上下文 / Clone context
+
+        Returns:
+            Context: 复制的上下文对象 / Cloned context object
+
+        Raises:
+            ValueError: 如果克隆失败
+        """
         cloned_handle = Library.framework().MaaContextClone(self._handle)
         if not cloned_handle:
             raise ValueError("cloned_handle is None")
@@ -145,9 +264,11 @@ class Context:
 
     @staticmethod
     def _gen_post_param(entry: str, pipeline_override: Dict) -> Tuple[bytes, bytes]:
+        pipeline_json = json.dumps(pipeline_override, ensure_ascii=False)
+
         return (
             entry.encode(),
-            json.dumps(pipeline_override, ensure_ascii=False).encode(),
+            pipeline_json.encode(),
         )
 
     _api_properties_initialized: bool = False
@@ -196,6 +317,13 @@ class Context:
             MaaStringListBufferHandle,
         ]
 
+        Library.framework().MaaContextOverrideImage.restype = MaaBool
+        Library.framework().MaaContextOverrideImage.argtypes = [
+            MaaContextHandle,
+            ctypes.c_char_p,
+            MaaImageBufferHandle,
+        ]
+
         Library.framework().MaaContextGetNodeData.restype = MaaBool
         Library.framework().MaaContextGetNodeData.argtypes = [
             MaaContextHandle,
@@ -217,3 +345,87 @@ class Context:
         Library.framework().MaaContextClone.argtypes = [
             MaaContextHandle,
         ]
+
+
+class ContextEventSink(EventSink):
+
+    @dataclass
+    class NodeNextListDetail:
+        task_id: int
+        name: str
+        next_list: list[str]
+        focus: Any
+
+    def on_node_next_list(
+        self,
+        context: Context,
+        noti_type: NotificationType,
+        detail: NodeNextListDetail,
+    ):
+        pass
+
+    @dataclass
+    class NodeRecognitionDetail:
+        task_id: int
+        reco_id: int
+        name: str
+        focus: Any
+
+    def on_node_recognition(
+        self,
+        context: Context,
+        noti_type: NotificationType,
+        detail: NodeRecognitionDetail,
+    ):
+        pass
+
+    @dataclass
+    class NodeActionDetail:
+        task_id: int
+        node_id: int
+        name: str
+        focus: Any
+
+    def on_node_action(
+        self, context: Context, noti_type: NotificationType, detail: NodeActionDetail
+    ):
+        pass
+
+    def on_raw_notification(self, context: Context, msg: str, details: dict):
+        pass
+
+    def _on_raw_notification(self, handle: ctypes.c_void_p, msg: str, details: dict):
+
+        context = Context(handle=handle)
+        self.on_raw_notification(context, msg, details)
+
+        noti_type = EventSink._notification_type(msg)
+        if msg.startswith("Node.NextList"):
+            detail = self.NodeNextListDetail(
+                task_id=details["task_id"],
+                name=details["name"],
+                next_list=details["list"],
+                focus=details["focus"],
+            )
+            self.on_node_next_list(context, noti_type, detail)
+
+        elif msg.startswith("Node.Recognition"):
+            detail = self.NodeRecognitionDetail(
+                task_id=details["task_id"],
+                reco_id=details["reco_id"],
+                name=details["name"],
+                focus=details["focus"],
+            )
+            self.on_node_recognition(context, noti_type, detail)
+
+        elif msg.startswith("Node.Action"):
+            detail = self.NodeActionDetail(
+                task_id=details["task_id"],
+                node_id=details["node_id"],
+                name=details["name"],
+                focus=details["focus"],
+            )
+            self.on_node_action(context, noti_type, detail)
+
+        else:
+            self.on_unknown_notification(context, msg, details)