Merge branch 'dev' into prcix9320

unilabos/utils/decorator.py

@@ -182,3 +182,94 @@ def get_all_subscriptions(instance) -> list:
         except Exception:
             pass
     return subscriptions
+
+
+def always_free(func: F) -> F:
+    """
+    标记动作为永久闲置(不受busy队列限制)的装饰器
+
+    被此装饰器标记的 action 方法，在执行时不会受到设备级别的排队限制，
+    任何时候请求都可以立即执行。适用于查询类、状态读取类等轻量级操作。
+
+    Example:
+        class MyDriver:
+            @always_free
+            def query_status(self, param: str):
+                # 这个动作可以随时执行，不需要排队
+                return self._status
+
+            def transfer(self, volume: float):
+                # 这个动作会按正常排队逻辑执行
+                pass
+
+    Note:
+        - 可以与其他装饰器组合使用，@always_free 应放在最外层
+        - 仅影响 WebSocket 调度层的 busy/free 判断，不影响 ROS2 层
+    """
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+
+    wrapper._is_always_free = True  # type: ignore[attr-defined]
+
+    return wrapper  # type: ignore[return-value]
+
+
+def is_always_free(func) -> bool:
+    """
+    检查函数是否被标记为永久闲置
+
+    Args:
+        func: 被检查的函数
+
+    Returns:
+        如果函数被 @always_free 装饰则返回 True，否则返回 False
+    """
+    return getattr(func, "_is_always_free", False)
+
+
+def not_action(func: F) -> F:
+    """
+    标记方法为非动作的装饰器
+
+    用于装饰 driver 类中的方法，使其在 complete_registry 时不被识别为动作。
+    适用于辅助方法、内部工具方法等不应暴露为设备动作的公共方法。
+
+    Example:
+        class MyDriver:
+            @not_action
+            def helper_method(self):
+                # 这个方法不会被注册为动作
+                pass
+
+            def actual_action(self, param: str):
+                # 这个方法会被注册为动作
+                self.helper_method()
+
+    Note:
+        - 可以与其他装饰器组合使用，@not_action 应放在最外层
+        - 仅影响 complete_registry 的动作识别，不影响方法的正常调用
+    """
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+
+    # 在函数上附加标记
+    wrapper._is_not_action = True  # type: ignore[attr-defined]
+
+    return wrapper  # type: ignore[return-value]
+
+
+def is_not_action(func) -> bool:
+    """
+    检查函数是否被标记为非动作
+
+    Args:
+        func: 被检查的函数
+
+    Returns:
+        如果函数被 @not_action 装饰则返回 True，否则返回 False
+    """
+    return getattr(func, "_is_not_action", False)

unilabos/utils/import_manager.py

@@ -29,6 +29,7 @@ from ast import Constant
 
 from unilabos.resources.resource_tracker import PARAM_SAMPLE_UUIDS
 from unilabos.utils import logger
+from unilabos.utils.decorator import is_not_action, is_always_free
 
 
 class ImportManager:
@@ -278,6 +279,9 @@ class ImportManager:
                 elif not name.startswith("_"):
                     # 其他非_开头的方法归类为action
                     method_info = self._analyze_method_signature(method)
+                    # 检查是否被 @always_free 装饰器标记
+                    if is_always_free(method):
+                        method_info["always_free"] = True
                     result["action_methods"][name] = method_info
 
         return result
@@ -332,6 +336,9 @@ class ImportManager:
                         result["status_methods"][actual_name] = method_info
                 else:
                     # 其他非_开头的方法归类为action
+                    # 检查是否被 @always_free 装饰器标记
+                    if self._is_always_free_method(node):
+                        method_info["always_free"] = True
                     result["action_methods"][method_name] = method_info
         return result
 
@@ -460,6 +467,20 @@ class ImportManager:
                 return True
         return False
 
+    def _is_not_action_method(self, node: ast.FunctionDef) -> bool:
+        """检查是否是@not_action装饰的方法"""
+        for decorator in node.decorator_list:
+            if isinstance(decorator, ast.Name) and decorator.id == "not_action":
+                return True
+        return False
+
+    def _is_always_free_method(self, node: ast.FunctionDef) -> bool:
+        """检查是否是@always_free装饰的方法"""
+        for decorator in node.decorator_list:
+            if isinstance(decorator, ast.Name) and decorator.id == "always_free":
+                return True
+        return False
+
     def _get_property_name_from_setter(self, node: ast.FunctionDef) -> str:
         """从setter装饰器中获取属性名"""
         for decorator in node.decorator_list:

unilabos/utils/log.py

@@ -193,6 +193,7 @@ def configure_logger(loglevel=None, working_dir=None):
     root_logger.addHandler(console_handler)
 
     # 如果指定了工作目录，添加文件处理器
+    log_filepath = None
     if working_dir is not None:
         logs_dir = os.path.join(working_dir, "logs")
         os.makedirs(logs_dir, exist_ok=True)
@@ -213,6 +214,7 @@ def configure_logger(loglevel=None, working_dir=None):
 
     logging.getLogger("asyncio").setLevel(logging.INFO)
     logging.getLogger("urllib3").setLevel(logging.INFO)
+    return log_filepath
 
 
 # 配置日志系统