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

maa/__init__.py

@@ -1,10 +1,12 @@
 import os
+from pathlib import Path
 
 from .library import Library
 
-__PATH = os.path.join(os.path.dirname(__file__), "bin")
+env_path = os.environ.get("MAAFW_BINARY_PATH")
+if env_path:
+    __PATH = Path(env_path)
+else:
+    __PATH = Path(Path(__file__).parent, "bin")
 
-if os.path.exists(__PATH):
-    ver = Library.open(__PATH)
-    if ver:
-        print(f"MaaFw version: {ver}")
+Library.open(__PATH, agent_server=False)

maa/agent/__init__.py

@@ -0,0 +1,12 @@
+import os
+from pathlib import Path
+
+from ..library import Library
+
+env_path = os.environ.get("MAAFW_BINARY_PATH")
+if env_path:
+    __PATH = Path(env_path)
+else:
+    __PATH = Path(Path(__file__).parent.parent, "bin")
+
+Library.open(__PATH, agent_server=True)

maa/agent/agent_server.py

@@ -0,0 +1,350 @@
+import ctypes
+
+from ..define import *
+from ..library import Library
+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(
+                name=name, recognition=recognition()
+            )
+            return recognition
+
+        return wrapper_recognition
+
+    _custom_recognition_holder = {}
+
+    @staticmethod
+    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()
+
+        # avoid gc
+        AgentServer._custom_recognition_holder[name] = recognition
+
+        return bool(
+            Library.agent_server().MaaAgentServerRegisterCustomRecognition(
+                name.encode(),
+                recognition.c_handle,
+                recognition.c_arg,
+            )
+        )
+
+    @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())
+            return action
+
+        return wrapper_action
+
+    _custom_action_holder = {}
+
+    @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()
+
+        # avoid gc
+        AgentServer._custom_action_holder[name] = action
+
+        return bool(
+            Library.agent_server().MaaAgentServerRegisterCustomAction(
+                name.encode(),
+                action.c_handle,
+                action.c_arg,
+            )
+        )
+
+    @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()
+
+        return bool(Library.agent_server().MaaAgentServerStartUp(identifier.encode()))
+
+    @staticmethod
+    def shut_down() -> None:
+        """关闭 Agent 服务 / Shut down Agent service"""
+
+        AgentServer._set_api_properties()
+
+        Library.agent_server().MaaAgentServerShutDown()
+
+    @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() -> 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
+    def _set_api_properties():
+        if AgentServer._api_properties_initialized:
+            return
+
+        AgentServer._api_properties_initialized = True
+
+        Library.agent_server().MaaAgentServerRegisterCustomRecognition.restype = MaaBool
+        Library.agent_server().MaaAgentServerRegisterCustomRecognition.argtypes = [
+            ctypes.c_char_p,
+            MaaCustomRecognitionCallback,
+            ctypes.c_void_p,
+        ]
+
+        Library.agent_server().MaaAgentServerRegisterCustomAction.restype = MaaBool
+        Library.agent_server().MaaAgentServerRegisterCustomAction.argtypes = [
+            ctypes.c_char_p,
+            MaaCustomActionCallback,
+            ctypes.c_void_p,
+        ]
+
+        Library.agent_server().MaaAgentServerStartUp.restype = MaaBool
+        Library.agent_server().MaaAgentServerStartUp.argtypes = [
+            ctypes.c_char_p,
+        ]
+
+        Library.agent_server().MaaAgentServerShutDown.restype = None
+        Library.agent_server().MaaAgentServerShutDown.argtypes = []
+
+        Library.agent_server().MaaAgentServerJoin.restype = None
+        Library.agent_server().MaaAgentServerJoin.argtypes = []
+
+        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

@@ -0,0 +1,291 @@
+import ctypes
+from typing import List
+
+from .define import *
+from .library import Library
+from .resource import Resource
+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:
+            id_buffer = StringBuffer()
+            id_buffer.set(identifier)
+            id_buffer_handle = id_buffer._handle
+        else:
+            id_buffer_handle = None
+
+        self._handle = Library.agent_client().MaaAgentClientCreateV2(id_buffer_handle)
+        if not self._handle:
+            raise RuntimeError("Failed to create agent client.")
+
+    def __del__(self):
+        if self._handle:
+            Library.agent_client().MaaAgentClientDestroy(self._handle)
+
+    @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
+        ):
+            return None
+
+        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
+
+        return bool(
+            Library.agent_client().MaaAgentClientBindResource(
+                self._handle, resource._handle
+            )
+        )
+
+    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
+    def _set_api_properties():
+        if AgentClient._api_properties_initialized:
+            return
+
+        if Library.is_agent_server():
+            raise RuntimeError("AgentClient is not available in AgentServer.")
+
+        AgentClient._api_properties_initialized = True
+
+        Library.agent_client().MaaAgentClientCreateV2.restype = MaaAgentClientHandle
+        Library.agent_client().MaaAgentClientCreateV2.argtypes = [
+            MaaStringBufferHandle,
+        ]
+
+        Library.agent_client().MaaAgentClientIdentifier.restype = MaaBool
+        Library.agent_client().MaaAgentClientIdentifier.argtypes = [
+            MaaAgentClientHandle,
+            MaaStringBufferHandle,
+        ]
+
+        Library.agent_client().MaaAgentClientDestroy.restype = None
+        Library.agent_client().MaaAgentClientDestroy.argtypes = [MaaAgentClientHandle]
+
+        Library.agent_client().MaaAgentClientBindResource.restype = MaaBool
+        Library.agent_client().MaaAgentClientBindResource.argtypes = [
+            MaaAgentClientHandle,
+            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,
+        ]
+
+        Library.agent_client().MaaAgentClientDisconnect.restype = MaaBool
+        Library.agent_client().MaaAgentClientDisconnect.argtypes = [
+            MaaAgentClientHandle,
+        ]
+
+        Library.agent_client().MaaAgentClientConnected.restype = MaaBool
+        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,
+        ]