MaaFw 4.4.0b1__py3-none-manylinux2014_x86_64.whl → 5.4.0__py3-none-manylinux2014_x86_64.whl

maa/custom_action.py

@@ -8,6 +8,20 @@ from .define import *
 
 
 class CustomAction(ABC):
+    """自定义动作基类 / Custom action base class
+
+    用于实现自定义的 Pipeline 动作。继承此类并实现 run 方法，
+    然后通过 Resource.register_custom_action 或 AgentServer.register_custom_action 注册。
+    Used to implement custom Pipeline actions. Inherit this class and implement the run method,
+    then register via Resource.register_custom_action or AgentServer.register_custom_action.
+
+    Example:
+        class MyAction(CustomAction):
+            def run(self, context, argv):
+                context.tasker.controller.post_click(100, 100).wait()
+                return True
+    """
+
     _handle: MaaCustomActionCallback
 
     def __init__(self):
@@ -15,6 +29,17 @@ class CustomAction(ABC):
 
     @dataclass
     class RunArg:
+        """run 方法的参数 / Arguments for run method
+
+        Attributes:
+            task_detail: 当前任务详情 / Current task detail
+            node_name: 当前节点名 / Current node name
+            custom_action_name: 自定义动作名 / Custom action name
+            custom_action_param: 自定义动作参数 (JSON 字符串) / Custom action parameter (JSON string)
+            reco_detail: 前序识别详情 / Previous recognition detail
+            box: 前序识别位置 / Previous recognition box
+        """
+
         task_detail: TaskDetail
         node_name: str
         custom_action_name: str
@@ -24,6 +49,12 @@ class CustomAction(ABC):
 
     @dataclass
     class RunResult:
+        """run 方法的返回结果 / Return result of run method
+
+        Attributes:
+            success: 动作是否执行成功 / Whether the action executed successfully
+        """
+
         success: bool
 
     @abstractmethod
@@ -32,6 +63,15 @@ class CustomAction(ABC):
         context: Context,
         argv: RunArg,
     ) -> Union[RunResult, bool]:
+        """执行自定义动作 / Execute custom action
+
+        Args:
+            context: 任务上下文，可用于执行其他操作 / Task context, can be used to execute other operations
+            argv: 动作参数 / Action arguments
+
+        Returns:
+            Union[RunResult, bool]: 执行结果，可返回 RunResult 或 bool / Execution result, can return RunResult or bool
+        """
         raise NotImplementedError
 
     @property
@@ -88,5 +128,8 @@ class CustomAction(ABC):
         elif isinstance(result, bool):
             return int(result)
 
+        elif result is None:
+            return int(True)
+
         else:
             raise TypeError(f"Invalid return type: {result!r}")

maa/custom_recognition.py

@@ -1,7 +1,7 @@
 import ctypes
+import json
 from dataclasses import dataclass
 from abc import ABC, abstractmethod
-from typing import Tuple
 
 import numpy
 
@@ -11,6 +11,20 @@ from .define import *
 
 
 class CustomRecognition(ABC):
+    """自定义识别器基类 / Custom recognition base class
+
+    用于实现自定义的 Pipeline 识别算法。继承此类并实现 analyze 方法，
+    然后通过 Resource.register_custom_recognition 或 AgentServer.register_custom_recognition 注册。
+    Used to implement custom Pipeline recognition algorithms. Inherit this class and implement the analyze method,
+    then register via Resource.register_custom_recognition or AgentServer.register_custom_recognition.
+
+    Example:
+        class MyRecognition(CustomRecognition):
+            def analyze(self, context, argv):
+                # 返回识别到的位置，或 None 表示未识别到
+                return (100, 100, 50, 50)
+    """
+
     _handle: MaaCustomRecognitionCallback
 
     def __init__(self):
@@ -18,6 +32,17 @@ class CustomRecognition(ABC):
 
     @dataclass
     class AnalyzeArg:
+        """analyze 方法的参数 / Arguments for analyze method
+
+        Attributes:
+            task_detail: 当前任务详情 / Current task detail
+            node_name: 当前节点名 / Current node name
+            custom_recognition_name: 自定义识别器名 / Custom recognition name
+            custom_recognition_param: 自定义识别器参数 (JSON 字符串) / Custom recognition parameter (JSON string)
+            image: 待识别的图像 (BGR 格式) / Image to recognize (BGR format)
+            roi: 识别区域 / Recognition region of interest
+        """
+
         task_detail: TaskDetail
         node_name: str
         custom_recognition_name: str
@@ -27,8 +52,15 @@ class CustomRecognition(ABC):
 
     @dataclass
     class AnalyzeResult:
+        """analyze 方法的返回结果 / Return result of analyze method
+
+        Attributes:
+            box: 识别到的位置，None 表示未识别到 / Recognized position, None means not recognized
+            detail: 识别详情，会被记录到识别结果中 / Recognition details, will be recorded in recognition result
+        """
+
         box: Optional[RectType]
-        detail: str
+        detail: dict
 
     @abstractmethod
     def analyze(
@@ -36,6 +68,18 @@ class CustomRecognition(ABC):
         context: Context,
         argv: AnalyzeArg,
     ) -> Union[AnalyzeResult, Optional[RectType]]:
+        """执行自定义识别 / Execute custom recognition
+
+        Args:
+            context: 任务上下文，可用于执行其他操作 / Task context, can be used to execute other operations
+            argv: 识别参数 / Recognition arguments
+
+        Returns:
+            Union[AnalyzeResult, Optional[RectType]]: 识别结果。可返回 AnalyzeResult、RectType 或 None。
+            返回 None 表示未识别到。
+            Recognition result. Can return AnalyzeResult, RectType, or None.
+            Return None means not recognized.
+        """
         raise NotImplementedError
 
     @property
@@ -92,21 +136,29 @@ class CustomRecognition(ABC):
         if isinstance(result, CustomRecognition.AnalyzeResult):
             if result.box:
                 rect_buffer.set(result.box)
-            detail_buffer.set(result.detail)
+            detail_buffer.set(json.dumps(result.detail, ensure_ascii=False))
             return int(result.box is not None)
 
-        elif result is None:
-            return int(False)
-
         # RectType
         elif (
             isinstance(result, Rect)
-            or (isinstance(result, list) and len(result) == 4 and all(isinstance(x, int) for x in result))
+            or (
+                isinstance(result, list)
+                and len(result) == 4
+                and all(isinstance(x, int) for x in result)
+            )
             or (isinstance(result, numpy.ndarray) and result.size == 4)
-            or (isinstance(result, tuple) and len(result) == 4 and all(isinstance(x, int) for x in result))
+            or (
+                isinstance(result, tuple)
+                and len(result) == 4
+                and all(isinstance(x, int) for x in result)
+            )
         ):
             rect_buffer.set(result)
             return int(True)
 
+        elif result is None:
+            return int(False)
+
         else:
-            raise ValueError("Invalid return type")
+            raise TypeError(f"Invalid return type: {result!r}")