MaaFw 4.3.1__py3-none-macosx_13_0_x86_64.whl → 5.4.1__py3-none-macosx_13_0_x86_64.whl

maa/agent/agent_server.py

@@ -1,15 +1,38 @@
 import ctypes
-import sys
 
 from ..define import *
 from ..library import Library
-from ..buffer import StringBuffer
+from ..event_sink import EventSink
 
 
 class AgentServer:
+    """Agent 服务端 / Agent server
+
+    用于在独立进程中托管自定义识别器和动作，与 AgentClient 配合使用。
+    这允许将复杂的自定义逻辑与主程序分离运行。
+    Used to host custom recognitions and actions in a separate process, working with AgentClient.
+    This allows separating complex custom logic from the main program.
+
+    Example:
+        @AgentServer.custom_recognition("MyReco")
+        class MyRecognition(CustomRecognition):
+            def analyze(self, context, argv):
+                return (100, 100, 50, 50)
+
+        AgentServer.start_up(sock_id)
+        AgentServer.join()
+    """
 
     @staticmethod
     def custom_recognition(name: str):
+        """自定义识别器装饰器 / Custom recognition decorator
+
+        Args:
+            name: 识别器名称，需与 Pipeline 中的 custom_recognition 字段匹配 / Recognition name, should match the custom_recognition field in Pipeline
+
+        Returns:
+            装饰器函数 / Decorator function
+        """
 
         def wrapper_recognition(recognition):
             AgentServer.register_custom_recognition(
@@ -25,6 +48,15 @@ class AgentServer:
     def register_custom_recognition(
         name: str, recognition: "CustomRecognition"  # type: ignore
     ) -> bool:
+        """注册自定义识别器 / Register custom recognition
+
+        Args:
+            name: 识别器名称 / Recognition name
+            recognition: 自定义识别器实例 / Custom recognition instance
+
+        Returns:
+            bool: 是否成功 / Whether successful
+        """
 
         AgentServer._set_api_properties()
 
@@ -41,6 +73,14 @@ class AgentServer:
 
     @staticmethod
     def custom_action(name: str):
+        """自定义动作装饰器 / Custom action decorator
+
+        Args:
+            name: 动作名称，需与 Pipeline 中的 custom_action 字段匹配 / Action name, should match the custom_action field in Pipeline
+
+        Returns:
+            装饰器函数 / Decorator function
+        """
 
         def wrapper_action(action):
             AgentServer.register_custom_action(name=name, action=action())
@@ -52,6 +92,15 @@ class AgentServer:
 
     @staticmethod
     def register_custom_action(name: str, action: "CustomAction") -> bool:  # type: ignore
+        """注册自定义动作 / Register custom action
+
+        Args:
+            name: 动作名称 / Action name
+            action: 自定义动作实例 / Custom action instance
+
+        Returns:
+            bool: 是否成功 / Whether successful
+        """
 
         AgentServer._set_api_properties()
 
@@ -68,6 +117,14 @@ class AgentServer:
 
     @staticmethod
     def start_up(identifier: str) -> bool:
+        """启动 Agent 服务 / Start Agent service
+
+        Args:
+            identifier: 连接标识符，用于与 AgentClient 匹配 / Connection identifier for matching with AgentClient
+
+        Returns:
+            bool: 是否成功 / Whether successful
+        """
 
         AgentServer._set_api_properties()
 
@@ -75,6 +132,7 @@ class AgentServer:
 
     @staticmethod
     def shut_down() -> None:
+        """关闭 Agent 服务 / Shut down Agent service"""
 
         AgentServer._set_api_properties()
 
@@ -82,18 +140,154 @@ class AgentServer:
 
     @staticmethod
     def join() -> None:
+        """等待 Agent 服务结束 / Wait for Agent service to end
+
+        阻塞当前线程直到服务结束。
+        Blocks the current thread until the service ends.
+        """
 
         AgentServer._set_api_properties()
 
         Library.agent_server().MaaAgentServerJoin()
 
     @staticmethod
-    def detach(self) -> None:
+    def detach() -> None:
+        """分离 Agent 服务 / Detach Agent service
+
+        允许服务在后台运行而不阻塞。
+        Allows the service to run in the background without blocking.
+        """
 
         AgentServer._set_api_properties()
 
         Library.agent_server().MaaAgentServerDetach()
 
+    _sink_holder: Dict[int, "EventSink"] = {}
+
+    @staticmethod
+    def resource_sink():
+        """资源事件监听器装饰器 / Resource event sink decorator
+
+        Returns:
+            装饰器函数 / Decorator function
+        """
+
+        def wrapper_sink(sink):
+            AgentServer.add_resource_sink(sink=sink())
+            return sink
+
+        return wrapper_sink
+
+    @staticmethod
+    def add_resource_sink(sink: "ResourceEventSink") -> None:
+        """添加资源事件监听器 / Add resource event sink
+
+        Args:
+            sink: 资源事件监听器 / Resource event sink
+        """
+        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():
+        """控制器事件监听器装饰器 / Controller event sink decorator
+
+        Returns:
+            装饰器函数 / Decorator function
+        """
+
+        def wrapper_sink(sink):
+            AgentServer.add_controller_sink(sink=sink())
+            return sink
+
+        return wrapper_sink
+
+    @staticmethod
+    def add_controller_sink(sink: "ControllerEventSink") -> None:
+        """添加控制器事件监听器 / Add controller event sink
+
+        Args:
+            sink: 控制器事件监听器 / Controller event sink
+        """
+        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():
+        """任务器事件监听器装饰器 / Tasker event sink decorator
+
+        Returns:
+            装饰器函数 / Decorator function
+        """
+
+        def wrapper_sink(sink):
+            AgentServer.add_tasker_sink(sink=sink())
+            return sink
+
+        return wrapper_sink
+
+    @staticmethod
+    def add_tasker_sink(sink: "TaskerEventSink") -> None:
+        """添加任务器事件监听器 / Add tasker event sink
+
+        Args:
+            sink: 任务器事件监听器 / Tasker event sink
+        """
+        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():
+        """上下文事件监听器装饰器 / Context event sink decorator
+
+        Returns:
+            装饰器函数 / Decorator function
+        """
+
+        def wrapper_sink(sink):
+            AgentServer.add_context_sink(sink=sink())
+            return sink
+
+        return wrapper_sink
+
+    @staticmethod
+    def add_context_sink(sink: "ContextEventSink") -> None:
+        """添加上下文事件监听器 / Add context event sink
+
+        Args:
+            sink: 上下文事件监听器 / Context event sink
+        """
+        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 +324,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

@@ -1,15 +1,34 @@
 import ctypes
+from typing import List
 
 from .define import *
 from .library import Library
 from .resource import Resource
-from .buffer import StringBuffer
+from .controller import Controller
+from .tasker import Tasker
+from .buffer import StringBuffer, StringListBuffer
 
 
 class AgentClient:
+    """Agent 客户端 / Agent client
+
+    用于连接到 AgentServer，将自定义识别器和动作的执行委托给独立进程。
+    这允许将 MaaFW 本体与 Custom 逻辑分离至独立进程运行。
+    Used to connect to AgentServer, delegating custom recognition and action execution to a separate process.
+    This allows separating MaaFW core from Custom logic into independent processes.
+    """
+
     _handle: MaaAgentClientHandle
 
     def __init__(self, identifier: Optional[str] = None):
+        """创建 Agent 客户端 / Create Agent client
+
+        Args:
+            identifier: 可选的连接标识符，用于匹配特定的 AgentServer / Optional connection identifier for matching specific AgentServer
+
+        Raises:
+            RuntimeError: 如果创建失败
+        """
         self._set_api_properties()
 
         if identifier:
@@ -29,6 +48,11 @@ class AgentClient:
 
     @property
     def identifier(self) -> Optional[str]:
+        """获取连接标识符 / Get connection identifier
+
+        Returns:
+            Optional[str]: 连接标识符，如果未设置则返回 None / Connection identifier, or None if not set
+        """
         id_buffer = StringBuffer()
         if not Library.agent_client().MaaAgentClientIdentifier(
             self._handle, id_buffer._handle
@@ -38,6 +62,17 @@ class AgentClient:
         return id_buffer.get()
 
     def bind(self, resource: Resource) -> bool:
+        """绑定资源 / Bind resource
+
+        将 AgentServer 中注册的自定义识别器和动作绑定到资源上。
+        Bind custom recognitions and actions registered in AgentServer to the resource.
+
+        Args:
+            resource: 资源对象 / Resource object
+
+        Returns:
+            bool: 是否成功 / Whether successful
+        """
         # avoid gc
         self._resource = resource
 
@@ -47,16 +82,126 @@ class AgentClient:
             )
         )
 
+    def register_sink(
+        self, resource: Resource, controller: Controller, tasker: Tasker
+    ) -> bool:
+        """注册事件监听器 / Register event sinks
+
+        将资源、控制器、任务器的事件转发给 AgentServer。
+        Forward resource, controller, and tasker events to AgentServer.
+
+        Args:
+            resource: 资源对象 / Resource object
+            controller: 控制器对象 / Controller object
+            tasker: 任务器对象 / Tasker object
+
+        Returns:
+            bool: 是否全部注册成功 / Whether all registrations succeeded
+        """
+        # 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:
+        """连接到 AgentServer / Connect to AgentServer
+
+        Returns:
+            bool: 是否成功 / Whether successful
+        """
         return bool(Library.agent_client().MaaAgentClientConnect(self._handle))
 
     def disconnect(self) -> bool:
+        """断开与 AgentServer 的连接 / Disconnect from AgentServer
+
+        Returns:
+            bool: 是否成功 / Whether successful
+        """
         return bool(Library.agent_client().MaaAgentClientDisconnect(self._handle))
 
     @property
     def connected(self) -> bool:
+        """判断是否已连接 / Check if connected
+
+        Returns:
+            bool: 是否已连接 / Whether connected
+        """
         return bool(Library.agent_client().MaaAgentClientConnected(self._handle))
 
+    @property
+    def alive(self) -> bool:
+        """判断连接是否存活 / Check if connection is alive
+
+        Returns:
+            bool: 连接是否存活 / Whether connection is alive
+        """
+        return bool(Library.agent_client().MaaAgentClientAlive(self._handle))
+
+    def set_timeout(self, milliseconds: int) -> bool:
+        """设置超时时间 / Set timeout
+
+        Args:
+            milliseconds: 超时时间（毫秒） / Timeout in milliseconds
+
+        Returns:
+            bool: 是否成功 / Whether successful
+        """
+        return bool(
+            Library.agent_client().MaaAgentClientSetTimeout(
+                self._handle, ctypes.c_int64(milliseconds)
+            )
+        )
+
+    @property
+    def custom_recognition_list(self) -> List[str]:
+        """获取已注册的自定义识别器列表 / Get registered custom recognizer list
+
+        Returns:
+            list[str]: 自定义识别器名列表 / List of custom recognizer names
+
+        Raises:
+            RuntimeError: 如果获取失败
+        """
+        buffer = StringListBuffer()
+        if not Library.agent_client().MaaAgentClientGetCustomRecognitionList(
+            self._handle, buffer._handle
+        ):
+            raise RuntimeError("Failed to get custom recognition list.")
+        return buffer.get()
+
+    @property
+    def custom_action_list(self) -> List[str]:
+        """获取已注册的自定义操作列表 / Get registered custom action list
+
+        Returns:
+            list[str]: 自定义操作名列表 / List of custom action names
+
+        Raises:
+            RuntimeError: 如果获取失败
+        """
+        buffer = StringListBuffer()
+        if not Library.agent_client().MaaAgentClientGetCustomActionList(
+            self._handle, buffer._handle
+        ):
+            raise RuntimeError("Failed to get custom action list.")
+        return buffer.get()
+
     _api_properties_initialized: bool = False
 
     @staticmethod
@@ -89,6 +234,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,
@@ -103,3 +266,26 @@ class AgentClient:
         Library.agent_client().MaaAgentClientConnected.argtypes = [
             MaaAgentClientHandle,
         ]
+
+        Library.agent_client().MaaAgentClientAlive.restype = MaaBool
+        Library.agent_client().MaaAgentClientAlive.argtypes = [
+            MaaAgentClientHandle,
+        ]
+
+        Library.agent_client().MaaAgentClientSetTimeout.restype = MaaBool
+        Library.agent_client().MaaAgentClientSetTimeout.argtypes = [
+            MaaAgentClientHandle,
+            ctypes.c_int64,
+        ]
+
+        Library.agent_client().MaaAgentClientGetCustomRecognitionList.restype = MaaBool
+        Library.agent_client().MaaAgentClientGetCustomRecognitionList.argtypes = [
+            MaaAgentClientHandle,
+            MaaStringListBufferHandle,
+        ]
+
+        Library.agent_client().MaaAgentClientGetCustomActionList.restype = MaaBool
+        Library.agent_client().MaaAgentClientGetCustomActionList.argtypes = [
+            MaaAgentClientHandle,
+            MaaStringListBufferHandle,
+        ]