feat: Add SyringePump (SY-03B) driver with unified serial/TCP transport for chinwe device, including registry and test configurations.

修改了mix，仿真流程报错问题

README.md

@@ -39,7 +39,9 @@ Uni-Lab-OS recommends using `mamba` for environment management. Choose the appro
 
 ```bash
 # Create new environment
-mamba create -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
+mamba create -n unilab python=3.11.11
+mamba activate unilab
+mamba install -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
 ```
 
 ## Install Dev Uni-Lab-OS

README_zh.md

@@ -41,7 +41,9 @@ Uni-Lab-OS 建议使用 `mamba` 管理环境。根据您的操作系统选择适
 
 ```bash
 # 创建新环境
-mamba create -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
+mamba create -n unilab python=3.11.11
+mamba activate unilab
+mamba install -n unilab uni-lab::unilabos -c robostack-staging -c conda-forge
 ```
 
 2. 安装开发版 Uni-Lab-OS:

docs/user_guide/installation.md

@@ -317,45 +317,6 @@ unilab --help
 
 如果所有命令都正常输出，说明开发环境配置成功！
 
-### 开发工具推荐
-
-#### IDE
-
-- **PyCharm Professional**: 强大的 Python IDE，支持远程调试
-- **VS Code**: 轻量级，配合 Python 扩展使用
-- **Vim/Emacs**: 适合终端开发
-
-#### 推荐的 VS Code 扩展
-
-- Python
-- Pylance
-- ROS
-- URDF
-- YAML
-
-#### 调试工具
-
-```bash
-# 安装调试工具
-pip install ipdb pytest pytest-cov -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
-
-# 代码质量检查
-pip install black flake8 mypy -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
-```
-
-### 设置 pre-commit 钩子（可选）
-
-```bash
-# 安装 pre-commit
-pip install pre-commit -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
-
-# 设置钩子
-pre-commit install
-
-# 手动运行检查
-pre-commit run --all-files
-```
-
 ---
 
 ## 验证安装

test/workflow/merge_workflow.py

@@ -0,0 +1,35 @@
+import sys
+from datetime import datetime
+from pathlib import Path
+
+ROOT_DIR = Path(__file__).resolve().parents[2]
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+import pytest
+
+from unilabos.workflow.convert_from_json import (
+    convert_from_json,
+    normalize_steps as _normalize_steps,
+    normalize_labware as _normalize_labware,
+)
+from unilabos.workflow.common import draw_protocol_graph_with_ports
+
+
+@pytest.mark.parametrize(
+    "protocol_name",
+    [
+        "example_bio",
+        # "bioyond_materials_liquidhandling_1",
+        "example_prcxi",
+    ],
+)
+def test_build_protocol_graph(protocol_name):
+    data_path = Path(__file__).with_name(f"{protocol_name}.json")
+
+    graph = convert_from_json(data_path, workstation_name="PRCXi")
+
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M")
+    output_path = data_path.with_name(f"{protocol_name}_graph_{timestamp}.png")
+    draw_protocol_graph_with_ports(graph, str(output_path))
+    print(graph)

unilabos/app/main.py

@@ -20,6 +20,7 @@ if unilabos_dir not in sys.path:
 from unilabos.utils.banner_print import print_status, print_unilab_banner
 from unilabos.config.config import load_config, BasicConfig, HTTPConfig
 
+
 def load_config_from_file(config_path):
     if config_path is None:
         config_path = os.environ.get("UNILABOS_BASICCONFIG_CONFIG_PATH", None)
@@ -41,7 +42,7 @@ def convert_argv_dashes_to_underscores(args: argparse.ArgumentParser):
     for i, arg in enumerate(sys.argv):
         for option_string in option_strings:
             if arg.startswith(option_string):
-                new_arg = arg[:2] + arg[2:len(option_string)].replace("-", "_") + arg[len(option_string):]
+                new_arg = arg[:2] + arg[2 : len(option_string)].replace("-", "_") + arg[len(option_string) :]
                 sys.argv[i] = new_arg
                 break
 
@@ -155,32 +156,54 @@ def parse_args():
         default=False,
         help="Complete registry information",
     )
-
+    # workflow upload subcommand
-    # label
     workflow_parser = subparsers.add_parser(
         "workflow_upload",
+        aliases=["wf"],
         help="Upload workflow from xdl/json/python files",
     )
-    workflow_parser.add_argument("-t", "--labeltype", default="singlepoint", type=str,
+    workflow_parser.add_argument(
-                              help="QM calculation type, support 'singlepoint', 'optimize' and 'dimer' currently")
+        "-f",
+        "--workflow_file",
+        type=str,
+        required=True,
+        help="Path to the workflow file (JSON format)",
+    )
+    workflow_parser.add_argument(
+        "-n",
+        "--workflow_name",
+        type=str,
+        default=None,
+        help="Workflow name, if not provided will use the name from file or filename",
+    )
+    workflow_parser.add_argument(
+        "--tags",
+        type=str,
+        nargs="*",
+        default=[],
+        help="Tags for the workflow (space-separated)",
+    )
+    workflow_parser.add_argument(
+        "--published",
+        action="store_true",
+        default=False,
+        help="Whether to publish the workflow (default: False)",
+    )
     return parser
 
 
 def main():
     """主函数"""
     # 解析命令行参数
-    args = parse_args()
+    parser = parse_args()
-    convert_argv_dashes_to_underscores(args)
+    convert_argv_dashes_to_underscores(parser)
-    args_dict = vars(args.parse_args())
+    args = parser.parse_args()
-
+    args_dict = vars(args)
-    # 显示启动横幅
-    print_unilab_banner(args_dict)
 
     # 环境检查 - 检查并自动安装必需的包 (可选)
     if not args_dict.get("skip_env_check", False):
         from unilabos.utils.environment_check import check_environment
 
-        print_status("正在进行环境依赖检查...", "info")
         if not check_environment(auto_install=True):
             print_status("环境检查失败，程序退出", "error")
             os._exit(1)
@@ -233,17 +256,18 @@ def main():
         logger.info(f"Log level set to '{BasicConfig.log_level}' from config file.")
     configure_logger(loglevel=BasicConfig.log_level, working_dir=working_dir)
 
-    if args_dict["addr"] == "test":
+    if args.addr != parser.get_default("addr"):
-        print_status("使用测试环境地址", "info")
+        if args.addr == "test":
-        HTTPConfig.remote_addr = "https://uni-lab.test.bohrium.com/api/v1"
+            print_status("使用测试环境地址", "info")
-    elif args_dict["addr"] == "uat":
+            HTTPConfig.remote_addr = "https://uni-lab.test.bohrium.com/api/v1"
-        print_status("使用uat环境地址", "info")
+        elif args.addr == "uat":
-        HTTPConfig.remote_addr = "https://uni-lab.uat.bohrium.com/api/v1"
+            print_status("使用uat环境地址", "info")
-    elif args_dict["addr"] == "local":
+            HTTPConfig.remote_addr = "https://uni-lab.uat.bohrium.com/api/v1"
-        print_status("使用本地环境地址", "info")
+        elif args.addr == "local":
-        HTTPConfig.remote_addr = "http://127.0.0.1:48197/api/v1"
+            print_status("使用本地环境地址", "info")
-    else:
+            HTTPConfig.remote_addr = "http://127.0.0.1:48197/api/v1"
-        HTTPConfig.remote_addr = args_dict.get("addr", "")
+        else:
+            HTTPConfig.remote_addr = args.addr
 
     # 设置BasicConfig参数
     if args_dict.get("ak", ""):
@@ -254,18 +278,10 @@ def main():
         print_status("传入了sk参数，优先采用传入参数！", "info")
     BasicConfig.working_dir = working_dir
 
-    # 显示启动横幅
+    workflow_upload = args_dict.get("command") in ("workflow_upload", "wf")
-    print_unilab_banner(args_dict)
 
-    #####################################
-    ######## 启动设备接入端(主入口) ########
-    #####################################
-    launch(args_dict)
-
-
-def launch(args_dict: Dict[str, Any]):
     # 使用远程资源启动
-    if args_dict["use_remote_resource"]:
+    if not workflow_upload and args_dict["use_remote_resource"]:
         print_status("使用远程资源启动", "info")
         from unilabos.app.web import http_client
 
@@ -301,11 +317,36 @@ def launch(args_dict: Dict[str, Any]):
     from unilabos.resources.graphio import modify_to_backend_format
     from unilabos.ros.nodes.resource_tracker import ResourceTreeSet, ResourceDict
 
+    # 显示启动横幅
+    print_unilab_banner(args_dict)
+
     # 注册表
     lab_registry = build_registry(
-        args_dict["registry_path"], args_dict.get("complete_registry", False), args_dict["upload_registry"]
+        args_dict["registry_path"], args_dict.get("complete_registry", False), BasicConfig.upload_registry
     )
 
+    if BasicConfig.upload_registry:
+        # 设备注册到服务端 - 需要 ak 和 sk
+        if BasicConfig.ak and BasicConfig.sk:
+            print_status("开始注册设备到服务端...", "info")
+            try:
+                register_devices_and_resources(lab_registry)
+                print_status("设备注册完成", "info")
+            except Exception as e:
+                print_status(f"设备注册失败: {e}", "error")
+        else:
+            print_status("未提供 ak 和 sk，跳过设备注册", "info")
+    else:
+        print_status("本次启动注册表不报送云端，如果您需要联网调试，请在启动命令增加--upload_registry", "warning")
+
+    # 处理 workflow_upload 子命令
+    if workflow_upload:
+        from unilabos.workflow.wf_utils import handle_workflow_upload_command
+
+        handle_workflow_upload_command(args_dict)
+        print_status("工作流上传完成，程序退出", "info")
+        os._exit(0)
+
     if not BasicConfig.ak or not BasicConfig.sk:
         print_status("后续运行必须拥有一个实验室，请前往 https://uni-lab.bohrium.com 注册实验室！", "warning")
         os._exit(1)
@@ -382,20 +423,6 @@ def launch(args_dict: Dict[str, Any]):
     args_dict["devices_config"] = resource_tree_set
     args_dict["graph"] = graph_res.physical_setup_graph
 
-    if BasicConfig.upload_registry:
-        # 设备注册到服务端 - 需要 ak 和 sk
-        if BasicConfig.ak and BasicConfig.sk:
-            print_status("开始注册设备到服务端...", "info")
-            try:
-                register_devices_and_resources(lab_registry)
-                print_status("设备注册完成", "info")
-            except Exception as e:
-                print_status(f"设备注册失败: {e}", "error")
-        else:
-            print_status("未提供 ak 和 sk，跳过设备注册", "info")
-    else:
-        print_status("本次启动注册表不报送云端，如果您需要联网调试，请在启动命令增加--upload_registry", "warning")
-
     if args_dict["controllers"] is not None:
         args_dict["controllers_config"] = yaml.safe_load(open(args_dict["controllers"], encoding="utf-8"))
     else:
@@ -410,6 +437,7 @@ def launch(args_dict: Dict[str, Any]):
         comm_client = get_communication_client()
         if "websocket" in args_dict["app_bridges"]:
             args_dict["bridges"].append(comm_client)
+
             def _exit(signum, frame):
                 comm_client.stop()
                 sys.exit(0)
@@ -451,16 +479,13 @@ def launch(args_dict: Dict[str, Any]):
                 resource_visualization.start()
             except OSError as e:
                 if "AMENT_PREFIX_PATH" in str(e):
-                    print_status(
+                    print_status(f"ROS 2环境未正确设置，跳过3D可视化启动。错误详情: {e}", "warning")
-                        f"ROS 2环境未正确设置，跳过3D可视化启动。错误详情: {e}",
-                        "warning"
-                    )
                     print_status(
                         "建议解决方案：\n"
                         "1. 激活Conda环境: conda activate unilab\n"
                         "2. 或使用 --backend simple 参数\n"
                         "3. 或使用 --visual disable 参数禁用可视化",
-                        "info"
+                        "info",
                     )
                 else:
                     raise

unilabos/app/web/client.py

@@ -76,7 +76,8 @@ class HTTPClient:
             Dict[str, str]: 旧UUID到新UUID的映射关系 {old_uuid: new_uuid}
         """
         with open(os.path.join(BasicConfig.working_dir, "req_resource_tree_add.json"), "w", encoding="utf-8") as f:
-            f.write(json.dumps({"nodes": [x for xs in resources.dump() for x in xs], "mount_uuid": mount_uuid}, indent=4))
+            payload = {"nodes": [x for xs in resources.dump() for x in xs], "mount_uuid": mount_uuid}
+            f.write(json.dumps(payload, indent=4))
         # 从序列化数据中提取所有节点的UUID（保存旧UUID）
         old_uuids = {n.res_content.uuid: n for n in resources.all_nodes}
         if not self.initialized or first_add:
@@ -331,6 +332,67 @@ class HTTPClient:
                 logger.error(f"响应内容: {response.text}")
         return None
 
+    def workflow_import(
+        self,
+        name: str,
+        workflow_uuid: str,
+        workflow_name: str,
+        nodes: List[Dict[str, Any]],
+        edges: List[Dict[str, Any]],
+        tags: Optional[List[str]] = None,
+        published: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        导入工作流到服务器
+
+        Args:
+            name: 工作流名称（顶层）
+            workflow_uuid: 工作流UUID
+            workflow_name: 工作流名称（data内部）
+            nodes: 工作流节点列表
+            edges: 工作流边列表
+            tags: 工作流标签列表，默认为空列表
+            published: 是否发布工作流，默认为False
+
+        Returns:
+            Dict: API响应数据，包含 code 和 data (uuid, name)
+        """
+        # target_lab_uuid 暂时使用默认值，后续由后端根据 ak/sk 获取
+        payload = {
+            "target_lab_uuid": "28c38bb0-63f6-4352-b0d8-b5b8eb1766d5",
+            "name": name,
+            "data": {
+                "workflow_uuid": workflow_uuid,
+                "workflow_name": workflow_name,
+                "nodes": nodes,
+                "edges": edges,
+                "tags": tags if tags is not None else [],
+                "published": published,
+            },
+        }
+        # 保存请求到文件
+        with open(os.path.join(BasicConfig.working_dir, "req_workflow_upload.json"), "w", encoding="utf-8") as f:
+            f.write(json.dumps(payload, indent=4, ensure_ascii=False))
+
+        response = requests.post(
+            f"{self.remote_addr}/lab/workflow/owner/import",
+            json=payload,
+            headers={"Authorization": f"Lab {self.auth}"},
+            timeout=60,
+        )
+        # 保存响应到文件
+        with open(os.path.join(BasicConfig.working_dir, "res_workflow_upload.json"), "w", encoding="utf-8") as f:
+            f.write(f"{response.status_code}" + "\n" + response.text)
+
+        if response.status_code == 200:
+            res = response.json()
+            if "code" in res and res["code"] != 0:
+                logger.error(f"导入工作流失败: {response.text}")
+            return res
+        else:
+            logger.error(f"导入工作流失败: {response.status_code}, {response.text}")
+            return {"code": response.status_code, "message": response.text}
+
 
 # 创建默认客户端实例
 http_client = HTTPClient()

unilabos/app/ws_client.py

@@ -438,7 +438,7 @@ class MessageProcessor:
                     self.connected = True
                     self.reconnect_count = 0
 
-                    logger.info(f"[MessageProcessor] Connected to {self.websocket_url}")
+                    logger.trace(f"[MessageProcessor] Connected to {self.websocket_url}")
 
                     # 启动发送协程
                     send_task = asyncio.create_task(self._send_handler())
@@ -503,7 +503,7 @@ class MessageProcessor:
 
     async def _send_handler(self):
         """处理发送队列中的消息"""
-        logger.debug("[MessageProcessor] Send handler started")
+        logger.trace("[MessageProcessor] Send handler started")
 
         try:
             while self.connected and self.websocket:
@@ -965,7 +965,7 @@ class QueueProcessor:
 
     def _run(self):
         """运行队列处理主循环"""
-        logger.debug("[QueueProcessor] Queue processor started")
+        logger.trace("[QueueProcessor] Queue processor started")
 
         while self.is_running:
             try:
@@ -1175,7 +1175,6 @@ class WebSocketClient(BaseCommunicationClient):
         else:
             url = f"{scheme}://{parsed.netloc}/api/v1/ws/schedule"
 
-        logger.debug(f"[WebSocketClient] URL: {url}")
         return url
 
     def start(self) -> None:
@@ -1188,13 +1187,11 @@ class WebSocketClient(BaseCommunicationClient):
             logger.error("[WebSocketClient] WebSocket URL not configured")
             return
 
-        logger.info(f"[WebSocketClient] Starting connection to {self.websocket_url}")
-
         # 启动两个核心线程
         self.message_processor.start()
         self.queue_processor.start()
 
-        logger.info("[WebSocketClient] All threads started")
+        logger.trace("[WebSocketClient] All threads started")
 
     def stop(self) -> None:
         """停止WebSocket客户端"""

unilabos/config/config.py

@@ -21,7 +21,8 @@ class BasicConfig:
     startup_json_path = None  # 填写绝对路径
     disable_browser = False  # 禁止浏览器自动打开
     port = 8002  # 本地HTTP服务
-    log_level: Literal['TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] = "DEBUG"  # 'TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'
+    # 'TRACE', 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'
+    log_level: Literal["TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "DEBUG"
 
     @classmethod
     def auth_secret(cls):
@@ -41,7 +42,7 @@ class WSConfig:
 
 # HTTP配置
 class HTTPConfig:
-    remote_addr = "http://127.0.0.1:48197/api/v1"
+    remote_addr = "https://uni-lab.bohrium.com/api/v1"
 
 
 # ROS配置
@@ -65,13 +66,14 @@ def _update_config_from_module(module):
                     if not attr.startswith("_"):
                         setattr(obj, attr, getattr(getattr(module, name), attr))
 
+
 def _update_config_from_env():
     prefix = "UNILABOS_"
     for env_key, env_value in os.environ.items():
         if not env_key.startswith(prefix):
             continue
         try:
-            key_path = env_key[len(prefix):]  # Remove UNILAB_ prefix
+            key_path = env_key[len(prefix) :]  # Remove UNILAB_ prefix
             class_field = key_path.upper().split("_", 1)
             if len(class_field) != 2:
                 logger.warning(f"[ENV] 环境变量格式不正确：{env_key}")

unilabos/devices/liquid_handling/liquid_handler_abstract.py

@@ -988,6 +988,18 @@ class LiquidHandlerAbstract(LiquidHandlerMiddleware):
                 dis_vols = [float(dis_vols)]
             else:
                 dis_vols = [float(v) for v in dis_vols]
+
+        # 统一混合次数为标量，防止数组/列表与 int 比较时报错
+        if mix_times is not None and not isinstance(mix_times, (int, float)):
+            try:
+                mix_times = mix_times[0] if len(mix_times) > 0 else None
+            except Exception:
+                try:
+                    mix_times = next(iter(mix_times))
+                except Exception:
+                    pass
+        if mix_times is not None:
+            mix_times = int(mix_times)
             
             # 识别传输模式
             num_sources = len(sources)

unilabos/devices/liquid_handling/prcxi/prcxi.py

@@ -5,6 +5,7 @@ import json
 import os
 import socket
 import time
+import uuid
 from typing import Any, List, Dict, Optional, Tuple, TypedDict, Union, Sequence, Iterator, Literal
 
 from pylabrobot.liquid_handling import (
@@ -856,7 +857,30 @@ class PRCXI9300Api:
 
     def _raw_request(self, payload: str) -> str:
         if self.debug:
-            return " "
+            # 调试/仿真模式下直接返回可解析的模拟 JSON，避免后续 json.loads 报错
+            try:
+                req = json.loads(payload)
+                method = req.get("MethodName")
+            except Exception:
+                method = None
+
+            data: Any = True
+            if method in {"AddSolution"}:
+                data = str(uuid.uuid4())
+            elif method in {"AddWorkTabletMatrix", "AddWorkTabletMatrix2"}:
+                data = {"Success": True, "Message": "debug mock"}
+            elif method in {"GetErrorCode"}:
+                data = ""
+            elif method in {"RemoveErrorCodet", "Reset", "Start", "LoadSolution", "Pause", "Resume", "Stop"}:
+                data = True
+            elif method in {"GetStepStateList", "GetStepStatus", "GetStepState"}:
+                data = []
+            elif method in {"GetLocation"}:
+                data = {"X": 0, "Y": 0, "Z": 0}
+            elif method in {"GetResetStatus"}:
+                data = False
+
+            return json.dumps({"Success": True, "Msg": "debug mock", "Data": data})
         with contextlib.closing(socket.socket()) as sock:
             sock.settimeout(self.timeout)
             sock.connect((self.host, self.port))

unilabos/devices/separator/chinwe.py

@@ -1,282 +1,636 @@
-import sys
+# -*- coding: utf-8 -*-
-import threading
+"""
-import serial
+Contains drivers for:
-import serial.tools.list_ports
+1. SyringePump: Runze Fluid SY-03B (ASCII)
-import re
+2. EmmMotor: Emm V5.0 Closed-loop Stepper (Modbus-RTU variant)
-import time
+3. XKCSensor: XKC Non-contact Level Sensor (Modbus-RTU)
-from typing import Optional, List, Dict, Tuple
+"""
 
-class ChinweDevice:
+import socket
+import serial
+import time
+import threading
+import struct
+import re
+import traceback
+import queue
+from typing import Optional, Dict, List, Any
+
+try:
+    from unilabos.device_comms.universal_driver import UniversalDriver
+except ImportError:
+    import logging
+    class UniversalDriver:
+        def __init__(self):
+            self.logger = logging.getLogger(self.__class__.__name__)
+
+        def execute_command_from_outer(self, command: str):
+            pass
+
+# ==============================================================================
+# 1. Transport Layer (通信层)
+# ==============================================================================
+
+class TransportManager:
     """
-    ChinWe设备控制类
+    统一通信管理类。
-    提供串口通信、电机控制、传感器数据读取等功能
+    自动识别 串口 (Serial) 或 网络 (TCP) 连接。
     """
-    
+    def __init__(self, port: str, baudrate: int = 9600, timeout: float = 3.0, logger=None):
-    def __init__(self, port: str, baudrate: int = 115200, debug: bool = False):
-        """
-        初始化ChinWe设备
-        
-        Args:
-            port: 串口名称，如果为None则自动检测
-            baudrate: 波特率，默认115200
-        """
-        self.debug = debug
         self.port = port
         self.baudrate = baudrate
-        self.serial_port: Optional[serial.Serial] = None
+        self.timeout = timeout
-        self._voltage: float = 0.0
+        self.logger = logger
-        self._ec_value: float = 0.0
+        self.lock = threading.RLock() # 线程锁，确保多设备共用一个连接时不冲突
-        self._ec_adc_value: int = 0
+
+        self.is_tcp = False
+        self.serial = None
+        self.socket = None
+
+        # 简单判断: 如果包含 ':' (如 192.168.1.1:8899) 或者看起来像 IP，则认为是 TCP
+        if ':' in self.port or (self.port.count('.') == 3 and not self.port.startswith('/')):
+            self.is_tcp = True
+            self._connect_tcp()
+        else:
+            self._connect_serial()
+
+    def _log(self, msg):
+        if self.logger:
+             pass
+            # self.logger.debug(f"[Transport] {msg}")
+
+    def _connect_tcp(self):
+        try:
+            if ':' in self.port:
+                host, p = self.port.split(':')
+                self.tcp_host = host
+                self.tcp_port = int(p)
+            else:
+                self.tcp_host = self.port
+                self.tcp_port = 8899 # 默认端口
+
+            # if self.logger: self.logger.info(f"Connecting TCP {self.tcp_host}:{self.tcp_port} ...")
+            self.socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            self.socket.settimeout(self.timeout)
+            self.socket.connect((self.tcp_host, self.tcp_port))
+        except Exception as e:
+            raise ConnectionError(f"TCP connection failed: {e}")
+
+    def _connect_serial(self):
+        try:
+            # if self.logger: self.logger.info(f"Opening Serial {self.port} (Baud: {self.baudrate}) ...")
+            self.serial = serial.Serial(
+                port=self.port,
+                baudrate=self.baudrate,
+                timeout=self.timeout
+            )
+        except Exception as e:
+            raise ConnectionError(f"Serial open failed: {e}")
+
+    def close(self):
+        """关闭连接"""
+        if self.is_tcp and self.socket:
+            try: self.socket.close()
+            except: pass
+        elif not self.is_tcp and self.serial and self.serial.is_open:
+            self.serial.close()
+
+    def clear_buffer(self):
+        """清空缓冲区 (Thread-safe)"""
+        with self.lock:
+            if self.is_tcp:
+                self.socket.setblocking(False)
+                try:
+                    while True:
+                        if not self.socket.recv(1024): break
+                except: pass
+                finally: self.socket.settimeout(self.timeout)
+            else:
+                self.serial.reset_input_buffer()
+
+    def write(self, data: bytes):
+        """发送原始字节"""
+        with self.lock:
+            if self.is_tcp:
+                self.socket.sendall(data)
+            else:
+                self.serial.write(data)
+
+    def read(self, size: int) -> bytes:
+        """读取指定长度字节"""
+        if self.is_tcp:
+            data = b''
+            start = time.time()
+            while len(data) < size:
+                if time.time() - start > self.timeout: break
+                try:
+                    chunk = self.socket.recv(size - len(data))
+                    if not chunk: break
+                    data += chunk
+                except socket.timeout: break
+            return data
+        else:
+            return self.serial.read(size)
+
+    def send_ascii_command(self, command: str) -> str:
+        """
+        发送 ASCII 字符串命令 (如注射泵指令)，读取直到 '\r'。
+        """
+        with self.lock:
+            data = command.encode('ascii') if isinstance(command, str) else command
+            self.clear_buffer()
+            self.write(data)
+
+            # Read until \r
+            if self.is_tcp:
+                resp = b''
+                start = time.time()
+                while True:
+                    if time.time() - start > self.timeout: break
+                    try:
+                        char = self.socket.recv(1)
+                        if not char: break
+                        resp += char
+                        if char == b'\r': break
+                    except: break
+                return resp.decode('ascii', errors='ignore').strip()
+            else:
+                return self.serial.read_until(b'\r').decode('ascii', errors='ignore').strip()
+
+# ==============================================================================
+# 2. Syringe Pump Driver (注射泵)
+# ==============================================================================
+
+class SyringePump:
+    """SY-03B 注射泵驱动 (ASCII协议)"""
+
+    CMD_INITIALIZE = "Z{speed},{drain_port},{output_port}R"
+    CMD_SWITCH_VALVE = "I{port}R"
+    CMD_ASPIRATE = "P{vol}R"
+    CMD_DISPENSE = "D{vol}R"
+    CMD_DISPENSE_ALL = "A0R"
+    CMD_STOP = "TR"
+    CMD_QUERY_STATUS = "Q"
+    CMD_QUERY_PLUNGER = "?0"
+
+    def __init__(self, device_id: int, transport: TransportManager):
+        if not 1 <= device_id <= 15:
+            pass # Allow all IDs for now
+        self.id = str(device_id)
+        self.transport = transport
+
+    def _send(self, template: str, **kwargs) -> str:
+        cmd = f"/{self.id}" + template.format(**kwargs) + "\r"
+        return self.transport.send_ascii_command(cmd)
+
+    def is_busy(self) -> bool:
+        """查询繁忙状态"""
+        resp = self._send(self.CMD_QUERY_STATUS)
+        # 响应如 /0` (Ready, 0x60) 或 /0@ (Busy, 0x40)
+        if len(resp) >= 3:
+            status_byte = ord(resp[2])
+            # Bit 5: 1=Ready, 0=Busy
+            return (status_byte & 0x20) == 0
+        return False
+
+    def wait_until_idle(self, timeout=30):
+        """阻塞等待直到空闲"""
+        start = time.time()
+        while time.time() - start < timeout:
+            if not self.is_busy(): return
+            time.sleep(0.5)
+        # raise TimeoutError(f"Pump {self.id} wait idle timeout")
+        pass
+
+    def initialize(self, drain_port=0, output_port=0, speed=10):
+        """初始化"""
+        self._send(self.CMD_INITIALIZE, speed=speed, drain_port=drain_port, output_port=output_port)
+
+    def switch_valve(self, port: int):
+        """切换阀门 (1-8)"""
+        self._send(self.CMD_SWITCH_VALVE, port=port)
+
+    def aspirate(self, steps: int):
+        """吸液 (相对步数)"""
+        self._send(self.CMD_ASPIRATE, vol=steps)
+
+    def dispense(self, steps: int):
+        """排液 (相对步数)"""
+        self._send(self.CMD_DISPENSE, vol=steps)
+
+    def stop(self):
+        """停止"""
+        self._send(self.CMD_STOP)
+
+    def get_position(self) -> int:
+        """获取柱塞位置 (步数)"""
+        resp = self._send(self.CMD_QUERY_PLUNGER)
+        m = re.search(r'\d+', resp)
+        return int(m.group()) if m else -1
+
+# ==============================================================================
+# 3. Stepper Motor Driver (步进电机)
+# ==============================================================================
+
+class EmmMotor:
+    """Emm V5.0 闭环步进电机驱动"""
+
+    def __init__(self, device_id: int, transport: TransportManager):
+        self.id = device_id
+        self.transport = transport
+
+    def _send(self, func_code: int, payload: list) -> bytes:
+        with self.transport.lock:
+            self.transport.clear_buffer()
+            # 格式: [ID] [Func] [Data...] [Check=0x6B]
+            body = [self.id, func_code] + payload
+            body.append(0x6B) # Checksum
+            self.transport.write(bytes(body))
+
+            # 根据指令不同，读取不同长度响应
+            read_len = 10 if func_code in [0x31, 0x32, 0x35, 0x24, 0x27] else 4
+            return self.transport.read(read_len)
+
+    def enable(self, on=True):
+        """使能 (True=锁轴, False=松轴)"""
+        state = 1 if on else 0
+        self._send(0xF3, [0xAB, state, 0])
+
+    def run_speed(self, speed_rpm: int, direction=0, acc=10):
+        """速度模式运行"""
+        sp = struct.pack('>H', int(speed_rpm))
+        self._send(0xF6, [direction, sp[0], sp[1], acc, 0])
+
+    def run_position(self, pulses: int, speed_rpm: int, direction=0, acc=10, absolute=False):
+        """位置模式运行"""
+        sp = struct.pack('>H', int(speed_rpm))
+        pl = struct.pack('>I', int(pulses))
+        is_abs = 1 if absolute else 0
+        self._send(0xFD, [direction, sp[0], sp[1], acc, pl[0], pl[1], pl[2], pl[3], is_abs, 0])
+
+    def stop(self):
+        """停止"""
+        self._send(0xFE, [0x98, 0])
+
+    def set_zero(self):
+        """清零位置"""
+        self._send(0x0A, [])
+
+    def get_position(self) -> int:
+        """获取当前脉冲位置"""
+        resp = self._send(0x32, [])
+        if len(resp) >= 8:
+            sign = resp[2]
+            val = struct.unpack('>I', resp[3:7])[0]
+            return -val if sign == 1 else val
+        return 0
+
+# ==============================================================================
+# 4. Liquid Sensor Driver (液位传感器)
+# ==============================================================================
+
+class XKCSensor:
+    """XKC RS485 液位传感器 (Modbus RTU)"""
+
+    def __init__(self, device_id: int, transport: TransportManager, threshold: int = 300):
+        self.id = device_id
+        self.transport = transport
+        self.threshold = threshold
+
+    def _crc(self, data: bytes) -> bytes:
+        crc = 0xFFFF
+        for byte in data:
+            crc ^= byte
+            for _ in range(8):
+                if crc & 0x0001: crc = (crc >> 1) ^ 0xA001
+                else: crc >>= 1
+        return struct.pack('<H', crc)
+
+    def read_level(self) -> Optional[Dict[str, Any]]:
+        """
+        读取液位。
+        返回: {'level': bool, 'rssi': int}
+        """
+        with self.transport.lock:
+            self.transport.clear_buffer()
+            # Modbus Read Registers: 01 03 00 01 00 02 CRC
+            payload = struct.pack('>HH', 0x0001, 0x0002)
+            msg = struct.pack('BB', self.id, 0x03) + payload
+            msg += self._crc(msg)
+            self.transport.write(msg)
+
+            # Read header
+            h = self.transport.read(3) # Addr, Func, Len
+            if len(h) < 3: return None
+            length = h[2]
+
+            # Read body + CRC
+            body = self.transport.read(length + 2)
+            if len(body) < length + 2:
+                # Firmware bug fix specific to some modules
+                if len(body) == 4 and length == 4:
+                    pass
+                else:
+                    return None
+
+            data = body[:-2]
+            if len(data) == 2:
+                rssi = data[1]
+            elif len(data) >= 4:
+                rssi = (data[2] << 8) | data[3]
+            else:
+                return None
+
+            return {
+                'level': rssi > self.threshold,
+                'rssi': rssi
+            }
+
+# ==============================================================================
+# 5. Main Device Class (ChinweDevice)
+# ==============================================================================
+
+class ChinweDevice(UniversalDriver):
+    """
+    ChinWe 工作站主驱动
+    继承自 UniversalDriver，管理所有子设备（泵、电机、传感器）
+    """
+
+    def __init__(self, port: str = "192.168.1.200:8899", baudrate: int = 9600,
+                 pump_ids: List[int] = None, motor_ids: List[int] = None,
+                 sensor_id: int = 6, sensor_threshold: int = 300):
+        """
+        初始化 ChinWe 工作站
+        :param port: 串口号 或 IP:Port
+        :param baudrate: 串口波特率
+        :param pump_ids: 注射泵 ID列表 (默认 [1, 2, 3])
+        :param motor_ids: 步进电机 ID列表 (默认 [4, 5])
+        :param sensor_id: 液位传感器 ID (默认 6)
+        """
+        super().__init__()
+        self.port = port
+        self.baudrate = baudrate
+        self.mgr = None
         self._is_connected = False
-        self.connect()
+
-    
+        # 默认配置
+        if pump_ids is None: pump_ids = [1, 2, 3]
+        if motor_ids is None: motor_ids = [4, 5]
+
+        # 配置信息
+        self.pump_ids = pump_ids
+        self.motor_ids = motor_ids
+        self.sensor_id = sensor_id
+        self.sensor_threshold = sensor_threshold
+
+        # 子设备实例容器
+        self.pumps: Dict[int, SyringePump] = {}
+        self.motors: Dict[int, EmmMotor] = {}
+        self.sensor: Optional[XKCSensor] = None
+
+        # 轮询线程控制
+        self._stop_event = threading.Event()
+        self._poll_thread = None
+
+        # 实时状态缓存
+        self.status_cache = {
+             "sensor_rssi": 0,
+             "sensor_level": False,
+             "connected": False
+        }
+
+        # 自动连接
+        if self.port:
+            self.connect()
+
+    def connect(self) -> bool:
+        if self._is_connected: return True
+        try:
+            self.logger.info(f"Connecting to {self.port}...")
+            self.mgr = TransportManager(self.port, baudrate=self.baudrate, logger=self.logger)
+
+            # 初始化所有泵
+            for pid in self.pump_ids:
+                self.pumps[pid] = SyringePump(pid, self.mgr)
+
+            # 初始化所有电机
+            for mid in self.motor_ids:
+                self.motors[mid] = EmmMotor(mid, self.mgr)
+
+            # 初始化传感器
+            self.sensor = XKCSensor(self.sensor_id, self.mgr, self.sensor_threshold)
+
+            self._is_connected = True
+            self.status_cache["connected"] = True
+
+            # 启动轮询线程
+            self._start_polling()
+            return True
+        except Exception as e:
+            self.logger.error(f"Connection failed: {e}")
+            self._is_connected = False
+            self.status_cache["connected"] = False
+            return False
+
+    def disconnect(self):
+        self._stop_event.set()
+        if self._poll_thread:
+            self._poll_thread.join(timeout=2.0)
+
+        if self.mgr:
+            self.mgr.close()
+
+        self._is_connected = False
+        self.status_cache["connected"] = False
+        self.logger.info("Disconnected.")
+
+    def _start_polling(self):
+        """启动传感器轮询线程"""
+        if self._poll_thread and self._poll_thread.is_alive():
+            return
+
+        self._stop_event.clear()
+        self._poll_thread = threading.Thread(target=self._polling_loop, daemon=True, name="ChinwePoll")
+        self._poll_thread.start()
+
+    def _polling_loop(self):
+        """轮询主循环"""
+        self.logger.info("Sensor polling started.")
+        error_count = 0
+        while not self._stop_event.is_set():
+            if not self._is_connected or not self.sensor:
+                time.sleep(1)
+                continue
+
+            try:
+                # 获取传感器数据
+                data = self.sensor.read_level()
+                if data:
+                    self.status_cache["sensor_rssi"] = data['rssi']
+                    self.status_cache["sensor_level"] = data['level']
+                    error_count = 0
+                else:
+                    error_count += 1
+
+                # 降低轮询频率防止总线拥塞
+                time.sleep(0.2)
+
+            except Exception as e:
+                error_count += 1
+                if error_count > 10: # 连续错误记录日志
+                    # self.logger.error(f"Polling error: {e}")
+                    error_count = 0
+                time.sleep(1)
+
+    # --- 对外暴露属性 (Properties) ---
+
+    @property
+    def sensor_level(self) -> bool:
+        return self.status_cache["sensor_level"]
+
+    @property
+    def sensor_rssi(self) -> int:
+        return self.status_cache["sensor_rssi"]
+
     @property
     def is_connected(self) -> bool:
-        """获取连接状态"""
+        return self._is_connected
-        return self._is_connected and self.serial_port and self.serial_port.is_open
-    
-    @property
-    def voltage(self) -> float:
-        """获取电源电压值"""
-        return self._voltage
-    
-    @property
-    def ec_value(self) -> float:
-        """获取电导率值 (ms/cm)"""
-        return self._ec_value
 
-    @property
+    # --- 对外功能指令 (Actions) ---
-    def ec_adc_value(self) -> int:
-        """获取EC ADC原始值"""
-        return self._ec_adc_value
-    
 
-    @property
+    def pump_initialize(self, pump_id: int, drain_port=0, output_port=0, speed=10):
-    def device_status(self) -> Dict[str, any]:
+        """指定泵初始化"""
-        """
+        pump_id = int(pump_id)
-        获取设备状态信息
+        if pump_id in self.pumps:
-        
+            self.pumps[pump_id].initialize(drain_port, output_port, speed)
-        Returns:
+            self.pumps[pump_id].wait_until_idle()
-            包含设备状态的字典
-        """
-        return {
-            "connected": self.is_connected,
-            "port": self.port,
-            "baudrate": self.baudrate,
-            "voltage": self.voltage,
-            "ec_value": self.ec_value,
-            "ec_adc_value": self.ec_adc_value
-        }
-    
-    def connect(self, port: Optional[str] = None, baudrate: Optional[int] = None) -> bool:
-        """
-        连接到串口设备
-        
-        Args:
-            port: 串口名称，如果为None则使用初始化时的port或自动检测
-            baudrate: 波特率，如果为None则使用初始化时的baudrate
-            
-        Returns:
-            连接是否成功
-        """
-        if self.is_connected:
             return True
-            
+        return False
-        target_port = port or self.port
+
-        target_baudrate = baudrate or self.baudrate
+    def pump_aspirate(self, pump_id: int, volume: int, valve_port: int):
-        
+        """
-        try:
+        泵吸液 (阻塞)
-            self.serial_port = serial.Serial(target_port, target_baudrate, timeout=0.5)
+        :param valve_port: 阀门端口 (1-8)
-            self._is_connected = True
+        """
-            self.port = target_port
+        pump_id = int(pump_id)
-            self.baudrate = target_baudrate
+        valve_port = int(valve_port)
-            connect_allow_times = 5
+        if pump_id in self.pumps:
-            while not self.serial_port.is_open and connect_allow_times > 0:
+            pump = self.pumps[pump_id]
-                time.sleep(0.5)
+            # 1. 切换阀门
-                connect_allow_times -= 1
+            pump.switch_valve(valve_port)
-                print(f"尝试连接到 {target_port} @ {target_baudrate}，剩余尝试次数: {connect_allow_times}", self.debug)
+            pump.wait_until_idle()
-                raise ValueError("串口未打开，请检查设备连接")
+            # 2. 吸液
-            print(f"已连接到 {target_port} @ {target_baudrate}", self.debug)
+            pump.aspirate(volume)
-            threading.Thread(target=self._read_data, daemon=True).start()
+            pump.wait_until_idle()
             return True
-        except Exception as e:
+        return False
-            print(f"ChinweDevice连接失败: {e}")
+
-            self._is_connected = False
+    def pump_dispense(self, pump_id: int, volume: int, valve_port: int):
-            return False
-    
-    def disconnect(self) -> bool:
         """
-        断开串口连接
+        泵排液 (阻塞)
-        
+        :param valve_port: 阀门端口 (1-8)
-        Returns:
-            断开是否成功
         """
-        if self.serial_port and self.serial_port.is_open:
+        pump_id = int(pump_id)
-            try:
+        valve_port = int(valve_port)
-                self.serial_port.close()
+        if pump_id in self.pumps:
-                self._is_connected = False
+            pump = self.pumps[pump_id]
-                print("已断开串口连接")
+            # 1. 切换阀门
-                return True
+            pump.switch_valve(valve_port)
-            except Exception as e:
+            pump.wait_until_idle()
-                print(f"断开连接失败: {e}")
+            # 2. 排液
-                return False
+            pump.dispense(volume)
+            pump.wait_until_idle()
+            return True
+        return False
+
+    def pump_valve(self, pump_id: int, port: int):
+        """泵切换阀门 (阻塞)"""
+        pump_id = int(pump_id)
+        port = int(port)
+        if pump_id in self.pumps:
+            pump = self.pumps[pump_id]
+            pump.switch_valve(port)
+            pump.wait_until_idle()
+            return True
+        return False
+
+    def motor_run_continuous(self, motor_id: int, speed: int, direction: str = "顺时针"):
+        """
+        电机一直旋转 (速度模式)
+        :param direction: "顺时针" or "逆时针"
+        """
+        motor_id = int(motor_id)
+        if motor_id not in self.motors: return False
+
+        dir_val = 0 if direction == "顺时针" else 1
+        self.motors[motor_id].run_speed(speed, dir_val)
         return True
-    
+
-    def _send_motor_command(self, command: str) -> bool:
+    def motor_rotate_quarter(self, motor_id: int, speed: int = 60, direction: str = "顺时针"):
         """
-        发送电机控制命令
+        电机旋转1/4圈 (阻塞)
-        
+        假设电机设置为 3200 脉冲/圈，1/4圈 = 800脉冲
-        Args:
-            command: 电机命令字符串，例如 "M 1 CW 1.5"
-            
-        Returns:
-            发送是否成功
         """
-        if not self.is_connected:
+        motor_id = int(motor_id)
-            print("设备未连接")
+        if motor_id not in self.motors: return False
-            return False
+
-            
+        pulses = 800
-        try:
+        dir_val = 0 if direction == "顺时针" else 1
-            self.serial_port.write((command + "\n").encode('utf-8'))
+
-            print(f"发送命令: {command}")
+        self.motors[motor_id].run_position(pulses, speed, dir_val, absolute=False)
+
+        # 预估时间阻塞 (单位: 分钟 -> 秒)
+        # Time(s) = revs / (RPM/60). revs = 0.25. time = 15 / RPM.
+        estimated_time = 15.0 / max(1, speed)
+        time.sleep(estimated_time + 0.5)
+
+        return True
+
+    def motor_stop(self, motor_id: int):
+        """电机停止"""
+        motor_id = int(motor_id)
+        if motor_id in self.motors:
+            self.motors[motor_id].stop()
             return True
-        except Exception as e:
+        return False
-            print(f"发送命令失败: {e}")
-            return False
-    
-    def rotate_motor(self, motor_id: int, turns: float, clockwise: bool = True) -> bool:
-        """
-        使电机转动指定圈数
-        
-        Args:
-            motor_id: 电机ID（1, 2, 3...）
-            turns: 转动圈数，支持小数
-            clockwise: True为顺时针，False为逆时针
-            
-        Returns:
-            命令发送是否成功
-        """
-        if clockwise:
-            command = f"M {motor_id} CW {turns}"
-        else:
-            command = f"M {motor_id} CCW {turns}"
-        return self._send_motor_command(command)
 
-    def set_motor_speed(self, motor_id: int, speed: float) -> bool:
+    def wait_sensor_level(self, target_state: str = "有液", timeout: int = 30) -> bool:
         """
-        设置电机转速（如果设备支持）
+        等待传感器达到指定电平
-        
+        :param target_state: "有液" or "无液"
-        Args:
-            motor_id: 电机ID（1, 2, 3...）
-            speed: 转速值
-            
-        Returns:
-            命令发送是否成功
         """
-        command = f"M {motor_id} SPEED {speed}"
+        target_bool = True if target_state == "有液" else False
-        return self._send_motor_command(command)
 
-    def _read_data(self) -> List[str]:
+        self.logger.info(f"Wait sensor: {target_state} ({target_bool}), timeout: {timeout}")
-        """
+        start = time.time()
-        读取串口数据并解析
+        while time.time() - start < timeout:
-        
+            if self.sensor_level == target_bool:
-        Returns:
+                return True
-            读取到的数据行列表
+            time.sleep(0.1)
-        """
+        self.logger.warning("Wait sensor level timeout")
-        print("开始读取串口数据...")
+        return False
-        if not self.is_connected:
-            return []
-            
-        data_lines = []
-        try:
-            while self.serial_port.in_waiting:
-                time.sleep(0.1)  # 等待数据稳定
-                try:
-                    line = self.serial_port.readline().decode('utf-8', errors='ignore').strip()
-                    if line:
-                        data_lines.append(line)
-                        self._parse_sensor_data(line)
-                except Exception as ex:
-                    print(f"解码数据错误: {ex}")
-        except Exception as e:
-            print(f"读取串口数据错误: {e}")
-            
-        return data_lines
-    
-    def _parse_sensor_data(self, line: str) -> None:
-        """
-        解析传感器数据
-        
-        Args:
-            line: 接收到的数据行
-        """
-        # 解析电源电压
-        if "电源电压" in line:
-            try:
-                val = float(line.split("：")[1].replace("V", "").strip())
-                self._voltage = val
-                if self.debug:
-                    print(f"电源电压更新: {val}V")
-            except Exception:
-                pass
 
-        # 解析电导率和ADC原始值（支持两种格式）
+    def execute_command_from_outer(self, command_dict: Dict[str, Any]) -> bool:
-        if "电导率" in line and "ADC原始值" in line:
+        """支持标准 JSON 指令调用"""
-            try:
+        return super().execute_command_from_outer(command_dict)
-                # 支持格式如：电导率：2.50ms/cm, ADC原始值：2052
-                ec_match = re.search(r"电导率[:：]\s*([\d\.]+)", line)
-                adc_match = re.search(r"ADC原始值[:：]\s*(\d+)", line)
-                if ec_match:
-                    ec_val = float(ec_match.group(1))
-                    self._ec_value = ec_val
-                    if self.debug:
-                        print(f"电导率更新: {ec_val:.2f} ms/cm")
-                if adc_match:
-                    adc_val = int(adc_match.group(1))
-                    self._ec_adc_value = adc_val
-                    if self.debug:
-                        print(f"EC ADC原始值更新: {adc_val}")
-            except Exception:
-                pass
-        # 仅电导率，无ADC原始值
-        elif "电导率" in line:
-            try:
-                val = float(line.split("：")[1].replace("ms/cm", "").strip())
-                self._ec_value = val
-                if self.debug:
-                    print(f"电导率更新: {val:.2f} ms/cm")
-            except Exception:
-                pass
-        # 仅ADC原始值（如有分开回传场景）
-        elif "ADC原始值" in line:
-            try:
-                adc_val = int(line.split("：")[1].strip())
-                self._ec_adc_value = adc_val
-                if self.debug:
-                    print(f"EC ADC原始值更新: {adc_val}")
-            except Exception:
-                pass
-    
-    def spin_when_ec_ge_0():
-        pass
-    
 
-def main():
-    """测试函数"""
-    print("=== ChinWe设备测试 ===")
-    
-    # 创建设备实例
-    device = ChinweDevice("/dev/tty.usbserial-A5069RR4", debug=True)
-    try:
-        # 测试5: 发送电机命令
-        print("\n5. 发送电机命令测试:")
-        print("  5.3 使用通用函数控制电机20顺时针转2圈:")
-        device.rotate_motor(2, 20.0, clockwise=True)
-        time.sleep(0.5)
-    finally:
-        time.sleep(10)
-        # 测试7: 断开连接
-        print("\n7. 断开连接:")
-        device.disconnect()
 if __name__ == "__main__":
-    main()
+    # Test
+    logging.basicConfig(level=logging.INFO)
+    dev = ChinweDevice(port="192.168.31.201:8899")
+    try:
+        if dev.is_connected:
+            print(f"Status: Level={dev.sensor_level}, RSSI={dev.sensor_rssi}")
+
+            # Test pump 1
+            # dev.pump_valve(1, 1)
+            # dev.pump_move(1, 1000, "aspirate")
+
+            # Test motor 4
+             # dev.motor_run(4, 60, 0, 2)
+
+            for _ in range(5):
+                print(f"Level={dev.sensor_level}, RSSI={dev.sensor_rssi}")
+                time.sleep(1)
+    finally:
+        dev.disconnect()

unilabos/registry/devices/bioyond_dispensing_station.yaml

@@ -174,35 +174,6 @@ bioyond_dispensing_station:
           title: query_resource_by_name参数
           type: object
         type: UniLabJsonCommand
-      auto-transfer_materials_to_reaction_station:
-        feedback: {}
-        goal: {}
-        goal_default:
-          target_device_id: null
-          transfer_groups: null
-        handles: {}
-        placeholder_keys: {}
-        result: {}
-        schema:
-          description: ''
-          properties:
-            feedback: {}
-            goal:
-              properties:
-                target_device_id:
-                  type: string
-                transfer_groups:
-                  type: array
-              required:
-              - target_device_id
-              - transfer_groups
-              type: object
-            result: {}
-          required:
-          - goal
-          title: transfer_materials_to_reaction_station参数
-          type: object
-        type: UniLabJsonCommand
       auto-workflow_sample_locations:
         feedback: {}
         goal: {}

unilabos/registry/devices/chinwe.yaml

@@ -0,0 +1,323 @@
+separator.chinwe:
+  category:
+  - separator
+  - chinwe
+  class:
+    action_value_mappings:
+      motor_rotate_quarter:
+        goal:
+          direction: 顺时针
+          motor_id: 4
+          speed: 60
+        handles: {}
+        schema:
+          description: 电机旋转 1/4 圈
+          properties:
+            goal:
+              properties:
+                direction:
+                  default: 顺时针
+                  description: 旋转方向
+                  enum:
+                  - 顺时针
+                  - 逆时针
+                  type: string
+                motor_id:
+                  default: '4'
+                  description: 选择电机 (4:搅拌, 5:旋钮)
+                  enum:
+                  - '4'
+                  - '5'
+                  type: string
+                speed:
+                  default: 60
+                  description: 速度 (RPM)
+                  type: integer
+              required:
+              - motor_id
+              - speed
+              type: object
+        type: UniLabJsonCommand
+      motor_run_continuous:
+        goal:
+          direction: 顺时针
+          motor_id: 4
+          speed: 60
+        handles: {}
+        schema:
+          description: 电机一直旋转 (速度模式)
+          properties:
+            goal:
+              properties:
+                direction:
+                  default: 顺时针
+                  description: 旋转方向
+                  enum:
+                  - 顺时针
+                  - 逆时针
+                  type: string
+                motor_id:
+                  default: '4'
+                  description: 选择电机 (4:搅拌, 5:旋钮)
+                  enum:
+                  - '4'
+                  - '5'
+                  type: string
+                speed:
+                  default: 60
+                  description: 速度 (RPM)
+                  type: integer
+              required:
+              - motor_id
+              - speed
+              type: object
+        type: UniLabJsonCommand
+      motor_stop:
+        goal:
+          motor_id: 4
+        handles: {}
+        schema:
+          description: 停止指定步进电机
+          properties:
+            goal:
+              properties:
+                motor_id:
+                  default: '4'
+                  description: 选择电机
+                  enum:
+                  - '4'
+                  - '5'
+                  title: '注: 4=搅拌, 5=旋钮'
+                  type: string
+              required:
+              - motor_id
+              type: object
+        type: UniLabJsonCommand
+      pump_aspirate:
+        goal:
+          pump_id: 1
+          valve_port: 1
+          volume: 1000
+        handles: {}
+        schema:
+          description: 注射泵吸液
+          properties:
+            goal:
+              properties:
+                pump_id:
+                  default: '1'
+                  description: 选择泵
+                  enum:
+                  - '1'
+                  - '2'
+                  - '3'
+                  type: string
+                valve_port:
+                  default: '1'
+                  description: 阀门端口
+                  enum:
+                  - '1'
+                  - '2'
+                  - '3'
+                  - '4'
+                  - '5'
+                  - '6'
+                  - '7'
+                  - '8'
+                  type: string
+                volume:
+                  default: 1000
+                  description: 吸液步数
+                  type: integer
+              required:
+              - pump_id
+              - volume
+              - valve_port
+              type: object
+        type: UniLabJsonCommand
+      pump_dispense:
+        goal:
+          pump_id: 1
+          valve_port: 1
+          volume: 1000
+        handles: {}
+        schema:
+          description: 注射泵排液
+          properties:
+            goal:
+              properties:
+                pump_id:
+                  default: '1'
+                  description: 选择泵
+                  enum:
+                  - '1'
+                  - '2'
+                  - '3'
+                  type: string
+                valve_port:
+                  default: '1'
+                  description: 阀门端口
+                  enum:
+                  - '1'
+                  - '2'
+                  - '3'
+                  - '4'
+                  - '5'
+                  - '6'
+                  - '7'
+                  - '8'
+                  type: string
+                volume:
+                  default: 1000
+                  description: 排液步数
+                  type: integer
+              required:
+              - pump_id
+              - volume
+              - valve_port
+              type: object
+        type: UniLabJsonCommand
+      pump_initialize:
+        goal:
+          drain_port: 0
+          output_port: 0
+          pump_id: 1
+          speed: 10
+        handles: {}
+        schema:
+          description: 初始化指定注射泵
+          properties:
+            goal:
+              properties:
+                drain_port:
+                  default: 0
+                  description: 排液口索引
+                  type: integer
+                output_port:
+                  default: 0
+                  description: 输出口索引
+                  type: integer
+                pump_id:
+                  default: '1'
+                  description: 选择泵
+                  enum:
+                  - '1'
+                  - '2'
+                  - '3'
+                  title: '注: 1号泵, 2号泵, 3号泵'
+                  type: string
+                speed:
+                  default: 10
+                  description: 运动速度
+                  type: integer
+              required:
+              - pump_id
+              type: object
+        type: UniLabJsonCommand
+      pump_valve:
+        goal:
+          port: 1
+          pump_id: 1
+        handles: {}
+        schema:
+          description: 切换指定泵的阀门端口
+          properties:
+            goal:
+              properties:
+                port:
+                  default: '1'
+                  description: 阀门端口号 (1-8)
+                  enum:
+                  - '1'
+                  - '2'
+                  - '3'
+                  - '4'
+                  - '5'
+                  - '6'
+                  - '7'
+                  - '8'
+                  type: string
+                pump_id:
+                  default: '1'
+                  description: 选择泵
+                  enum:
+                  - '1'
+                  - '2'
+                  - '3'
+                  type: string
+              required:
+              - pump_id
+              - port
+              type: object
+        type: UniLabJsonCommand
+      wait_sensor_level:
+        goal:
+          target_state: 有液
+          timeout: 30
+        handles: {}
+        schema:
+          description: 等待传感器液位条件
+          properties:
+            goal:
+              properties:
+                target_state:
+                  default: 有液
+                  description: 目标液位状态
+                  enum:
+                  - 有液
+                  - 无液
+                  type: string
+                timeout:
+                  default: 30
+                  description: 超时时间 (秒)
+                  type: integer
+              required:
+              - target_state
+              type: object
+        type: UniLabJsonCommand
+    module: unilabos.devices.separator.chinwe:ChinweDevice
+    status_types:
+      is_connected: bool
+      sensor_level: bool
+      sensor_rssi: int
+    type: python
+  config_info: []
+  description: ChinWe 简易工作站控制器 (3泵, 2电机, 1传感器)
+  handles: []
+  icon: ''
+  init_param_schema:
+    goal:
+      baudrate:
+        default: 9600
+        description: 串口波特率
+        type: integer
+      motor_ids:
+        default:
+        - 4
+        - 5
+        description: 步进电机ID列表
+        items:
+          type: integer
+        type: array
+      port:
+        default: 192.168.1.200:8899
+        description: 串口号或 IP:Port
+        type: string
+      pump_ids:
+        default:
+        - 1
+        - 2
+        - 3
+        description: 注射泵ID列表
+        items:
+          type: integer
+        type: array
+      sensor_id:
+        default: 6
+        description: XKC传感器ID
+        type: integer
+      sensor_threshold:
+        default: 300
+        description: 传感器液位判定阈值
+        type: integer
+  version: 2.1.0

unilabos/registry/devices/liquid_handler.yaml

@@ -9333,7 +9333,34 @@ liquid_handler.prcxi:
           touch_tip: false
           use_channels:
           - 0
-        handles: {}
+        handles:
+          input:
+          - data_key: liquid
+            data_source: handle
+            data_type: resource
+            handler_key: sources
+            label: sources
+          - data_key: liquid
+            data_source: executor
+            data_type: resource
+            handler_key: targets
+            label: targets
+          - data_key: liquid
+            data_source: executor
+            data_type: resource
+            handler_key: tip_rack
+            label: tip_rack
+          output:
+          - data_key: liquid
+            data_source: handle
+            data_type: resource
+            handler_key: sources_out
+            label: sources
+          - data_key: liquid
+            data_source: executor
+            data_type: resource
+            handler_key: targets_out
+            label: targets
         placeholder_keys:
           sources: unilabos_resources
           targets: unilabos_resources

unilabos/registry/registry.py

@@ -222,7 +222,7 @@ class Registry:
         abs_path = Path(path).absolute()
         resource_path = abs_path / "resources"
         files = list(resource_path.glob("*/*.yaml"))
-        logger.debug(f"[UniLab Registry] resources: {resource_path.exists()}, total: {len(files)}")
+        logger.trace(f"[UniLab Registry] load resources? {resource_path.exists()}, total: {len(files)}")
         current_resource_number = len(self.resource_type_registry) + 1
         for i, file in enumerate(files):
             with open(file, encoding="utf-8", mode="r") as f:

unilabos/resources/graphio.py

@@ -42,7 +42,7 @@ def canonicalize_nodes_data(
     Returns:
         ResourceTreeSet: 标准化后的资源树集合
     """
-    print_status(f"{len(nodes)} Resources loaded:", "info")
+    print_status(f"{len(nodes)} Resources loaded", "info")
 
     # 第一步：基本预处理（处理graphml的label字段）
     outer_host_node_id = None

unilabos/ros/nodes/resource_tracker.py

@@ -66,8 +66,8 @@ class ResourceDict(BaseModel):
     klass: str = Field(alias="class", description="Resource class name")
     pose: ResourceDictPosition = Field(description="Resource position", default_factory=ResourceDictPosition)
     config: Dict[str, Any] = Field(description="Resource configuration")
-    data: Dict[str, Any] = Field(description="Resource data")
+    data: Dict[str, Any] = Field(description="Resource data, eg: container liquid data")
-    extra: Dict[str, Any] = Field(description="Extra data")
+    extra: Dict[str, Any] = Field(description="Extra data, eg: slot index")
 
     @field_serializer("parent_uuid")
     def _serialize_parent(self, parent_uuid: Optional["ResourceDict"]):

unilabos/test/experiments/chinwe.json

@@ -0,0 +1,34 @@
+{
+    "nodes": [
+        {
+            "id": "ChinWeStation",
+            "name": "分液工作站",
+            "children": [],
+            "parent": null,
+            "type": "device",
+            "class": "separator.chinwe",
+            "position": {
+                "x": 0,
+                "y": 0,
+                "z": 0
+            },
+            "config": {
+                "port": "192.168.31.13:8899",
+                "baudrate": 9600,
+                "pump_ids": [
+                    1,
+                    2,
+                    3
+                ],
+                "motor_ids": [
+                    4,
+                    5
+                ],
+                "sensor_id": 6,
+                "sensor_threshold": 300
+            },
+            "data": {}
+        }
+    ],
+    "links": []
+}

unilabos/test/workflow/merge_workflow.py

@@ -1,94 +0,0 @@
-import json
-import sys
-from datetime import datetime
-from pathlib import Path
-
-ROOT_DIR = Path(__file__).resolve().parents[2]
-if str(ROOT_DIR) not in sys.path:
-    sys.path.insert(0, str(ROOT_DIR))
-
-import pytest
-
-from unilabos.workflow.common import build_protocol_graph, draw_protocol_graph, draw_protocol_graph_with_ports
-
-
-ROOT_DIR = Path(__file__).resolve().parents[2]
-if str(ROOT_DIR) not in sys.path:
-    sys.path.insert(0, str(ROOT_DIR))
-
-
-def _normalize_steps(data):
-    normalized = []
-    for step in data:
-        action = step.get("action") or step.get("operation")
-        if not action:
-            continue
-        raw_params = step.get("parameters") or step.get("action_args") or {}
-        params = dict(raw_params)
-
-        if "source" in raw_params and "sources" not in raw_params:
-            params["sources"] = raw_params["source"]
-        if "target" in raw_params and "targets" not in raw_params:
-            params["targets"] = raw_params["target"]
-
-        description = step.get("description") or step.get("purpose")
-        step_dict = {"action": action, "parameters": params}
-        if description:
-            step_dict["description"] = description
-        normalized.append(step_dict)
-    return normalized
-
-
-def _normalize_labware(data):
-    labware = {}
-    for item in data:
-        reagent_name = item.get("reagent_name")
-        key = reagent_name or item.get("material_name") or item.get("name")
-        if not key:
-            continue
-        key = str(key)
-        idx = 1
-        original_key = key
-        while key in labware:
-            idx += 1
-            key = f"{original_key}_{idx}"
-
-        labware[key] = {
-            "slot": item.get("positions") or item.get("slot"),
-            "labware": item.get("material_name") or item.get("labware"),
-            "well": item.get("well", []),
-            "type": item.get("type", "reagent"),
-            "role": item.get("role", ""),
-            "name": key,
-        }
-    return labware
-
-
-@pytest.mark.parametrize("protocol_name", [
-    "example_bio",
-    # "bioyond_materials_liquidhandling_1",
-    "example_prcxi",
-])
-def test_build_protocol_graph(protocol_name):
-    data_path = Path(__file__).with_name(f"{protocol_name}.json")
-    with data_path.open("r", encoding="utf-8") as fp:
-        d = json.load(fp)
-
-    if "workflow" in d and "reagent" in d:
-        protocol_steps = d["workflow"]
-        labware_info = d["reagent"]
-    elif "steps_info" in d and "labware_info" in d:
-        protocol_steps = _normalize_steps(d["steps_info"])
-        labware_info = _normalize_labware(d["labware_info"])
-    else:
-        raise ValueError("Unsupported protocol format")
-
-    graph = build_protocol_graph(
-        labware_info=labware_info,
-        protocol_steps=protocol_steps,
-        workstation_name="PRCXi",
-    )
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M")
-    output_path = data_path.with_name(f"{protocol_name}_graph_{timestamp}.png")
-    draw_protocol_graph_with_ports(graph, str(output_path))
-    print(graph)

unilabos/workflow/common.py

@@ -10,6 +10,7 @@ Json = Dict[str, Any]
 
 # ---------------- Graph ----------------
 
+
 class WorkflowGraph:
     """简单的有向图实现：使用 params 单层参数；inputs 内含连线；支持 node-link 导出"""
 
@@ -21,20 +22,31 @@ class WorkflowGraph:
         self.nodes[node_id] = attrs
 
     def add_edge(self, source: str, target: str, **attrs):
+        # 将 source_port/target_port 映射为服务端期望的 source_handle_key/target_handle_key
+        source_handle_key = attrs.pop("source_port", "") or attrs.pop("source_handle_key", "")
+        target_handle_key = attrs.pop("target_port", "") or attrs.pop("target_handle_key", "")
+
         edge = {
             "source": source,
             "target": target,
             "source_node_uuid": source,
             "target_node_uuid": target,
+            "source_handle_key": source_handle_key,
             "source_handle_io": attrs.pop("source_handle_io", "source"),
+            "target_handle_key": target_handle_key,
             "target_handle_io": attrs.pop("target_handle_io", "target"),
-            **attrs
+            **attrs,
         }
         self.edges.append(edge)
 
-    def _materialize_wiring_into_inputs(self, obj: Any, inputs: Dict[str, Any],
+    def _materialize_wiring_into_inputs(
-                                        variable_sources: Dict[str, Dict[str, Any]],
+        self,
-                                        target_node_id: str, base_path: List[str]):
+        obj: Any,
+        inputs: Dict[str, Any],
+        variable_sources: Dict[str, Dict[str, Any]],
+        target_node_id: str,
+        base_path: List[str],
+    ):
         has_var = False
 
         def walk(node: Any, path: List[str]):
@@ -48,9 +60,12 @@ class WorkflowGraph:
                     if src:
                         key = ".".join(path)  # e.g. "params.foo.bar.0"
                         inputs[key] = {"node": src["node_id"], "output": src.get("output_name", "result")}
-                        self.add_edge(str(src["node_id"]), target_node_id,
+                        self.add_edge(
-                                      source_handle_io=src.get("output_name", "result"),
+                            str(src["node_id"]),
-                                      target_handle_io=key)
+                            target_node_id,
+                            source_handle_io=src.get("output_name", "result"),
+                            target_handle_io=key,
+                        )
                     return placeholder
                 return {k: walk(v, path + [k]) for k, v in node.items()}
             if isinstance(node, list):
@@ -60,18 +75,20 @@ class WorkflowGraph:
         replaced = walk(obj, base_path[:])
         return replaced, has_var
 
-    def add_workflow_node(self,
+    def add_workflow_node(
-                          node_id: int,
+        self,
-                          *,
+        node_id: int,
-                          device_key: Optional[str] = None,          # 实例名，如 "ser"
+        *,
-                          resource_name: Optional[str] = None,       # registry key（原 device_class）
+        device_key: Optional[str] = None,  # 实例名，如 "ser"
-                          module: Optional[str] = None,
+        resource_name: Optional[str] = None,  # registry key（原 device_class）
-                          template_name: Optional[str] = None,       # 动作/模板名（原 action_key）
+        module: Optional[str] = None,
-                          params: Dict[str, Any],
+        template_name: Optional[str] = None,  # 动作/模板名（原 action_key）
-                          variable_sources: Dict[str, Dict[str, Any]],
+        params: Dict[str, Any],
-                          add_ready_if_no_vars: bool = True,
+        variable_sources: Dict[str, Dict[str, Any]],
-                          prev_node_id: Optional[int] = None,
+        add_ready_if_no_vars: bool = True,
-                          **extra_attrs) -> None:
+        prev_node_id: Optional[int] = None,
+        **extra_attrs,
+    ) -> None:
         """添加工作流节点：params 单层；自动变量连线与 ready 串联；支持附加属性"""
         node_id_str = str(node_id)
         inputs: Dict[str, Any] = {}
@@ -87,9 +104,9 @@ class WorkflowGraph:
 
         node_obj = {
             "device_key": device_key,
-            "resource_name": resource_name,   # ✅ 新名字
+            "resource_name": resource_name,  # ✅ 新名字
             "module": module,
-            "template_name": template_name,   # ✅ 新名字
+            "template_name": template_name,  # ✅ 新名字
             "params": params,
             "inputs": inputs,
         }
@@ -100,13 +117,13 @@ class WorkflowGraph:
     def to_dict(self) -> List[Dict[str, Any]]:
         result = []
         for node_id, attrs in self.nodes.items():
-            node = {"id": node_id}
+            node = {"uuid": node_id}
             params = dict(attrs.get("parameters", {}) or {})
             flat = {k: v for k, v in attrs.items() if k != "parameters"}
             flat.update(params)
             node.update(flat)
             result.append(node)
-        return sorted(result, key=lambda n: int(n["id"]) if str(n["id"]).isdigit() else n["id"])
+        return sorted(result, key=lambda n: int(n["uuid"]) if str(n["uuid"]).isdigit() else n["uuid"])
 
     # node-link 导出（含 edges）
     def to_node_link_dict(self) -> Dict[str, Any]:
@@ -115,12 +132,27 @@ class WorkflowGraph:
             node_attrs = attrs.copy()
             params = node_attrs.pop("parameters", {}) or {}
             node_attrs.update(params)
-            nodes_list.append({"id": node_id, **node_attrs})
+            nodes_list.append({"uuid": node_id, **node_attrs})
-        return {"directed": True, "multigraph": False, "graph": {}, "nodes": nodes_list, "edges": self.edges, "links": self.edges}
+        return {
+            "directed": True,
+            "multigraph": False,
+            "graph": {},
+            "nodes": nodes_list,
+            "edges": self.edges,
+            "links": self.edges,
+        }
 
 
-def refactor_data(data: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+def refactor_data(
-    """统一的数据重构函数，根据操作类型自动选择模板"""
+    data: List[Dict[str, Any]],
+    action_resource_mapping: Optional[Dict[str, str]] = None,
+) -> List[Dict[str, Any]]:
+    """统一的数据重构函数，根据操作类型自动选择模板
+
+    Args:
+        data: 原始步骤数据列表
+        action_resource_mapping: action 到 resource_name 的映射字典，可选
+    """
     refactored_data = []
 
     # 定义操作映射，包含生物实验和有机化学的所有操作
@@ -157,43 +189,67 @@ def refactor_data(data: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
             times = step.get("times", step.get("parameters", {}).get("times", 1))
             sub_steps = step.get("steps", step.get("parameters", {}).get("steps", []))
             for i in range(int(times)):
-                sub_data = refactor_data(sub_steps)
+                sub_data = refactor_data(sub_steps, action_resource_mapping)
                 refactored_data.extend(sub_data)
             continue
 
         # 获取模板名称
-        template = OPERATION_MAPPING.get(operation)
+        template_name = OPERATION_MAPPING.get(operation)
-        if not template:
+        if not template_name:
             # 自动推断模板类型
             if operation.lower() in ["transfer", "incubation", "move_labware", "oscillation"]:
-                template = f"biomek-{operation}"
+                template_name = f"biomek-{operation}"
             else:
-                template = f"{operation}Protocol"
+                template_name = f"{operation}Protocol"
+
+        # 获取 resource_name
+        resource_name = f"device.{operation.lower()}"
+        if action_resource_mapping:
+            resource_name = action_resource_mapping.get(operation, resource_name)
+
+        # 获取步骤编号，生成 name 字段
+        step_number = step.get("step_number")
+        name = f"Step {step_number}" if step_number is not None else None
 
         # 创建步骤数据
         step_data = {
-            "template": template,
+            "template_name": template_name,
+            "resource_name": resource_name,
             "description": step.get("description", step.get("purpose", f"{operation} operation")),
             "lab_node_type": "Device",
-            "parameters": step.get("parameters", step.get("action_args", {})),
+            "param": step.get("parameters", step.get("action_args", {})),
+            "footer": f"{template_name}-{resource_name}",
         }
+        if name:
+            step_data["name"] = name
         refactored_data.append(step_data)
 
     return refactored_data
 
 
 def build_protocol_graph(
-    labware_info: List[Dict[str, Any]], protocol_steps: List[Dict[str, Any]], workstation_name: str
+    labware_info: List[Dict[str, Any]],
+    protocol_steps: List[Dict[str, Any]],
+    workstation_name: str,
+    action_resource_mapping: Optional[Dict[str, str]] = None,
 ) -> WorkflowGraph:
-    """统一的协议图构建函数，根据设备类型自动选择构建逻辑"""
+    """统一的协议图构建函数，根据设备类型自动选择构建逻辑
+
+    Args:
+        labware_info: labware 信息字典
+        protocol_steps: 协议步骤列表
+        workstation_name: 工作站名称
+        action_resource_mapping: action 到 resource_name 的映射字典，可选
+    """
     G = WorkflowGraph()
     resource_last_writer = {}
 
-    protocol_steps = refactor_data(protocol_steps)
+    protocol_steps = refactor_data(protocol_steps, action_resource_mapping)
     # 有机化学&移液站协议图构建
     WORKSTATION_ID = workstation_name
 
     # 为所有labware创建资源节点
+    res_index = 0
     for labware_id, item in labware_info.items():
         # item_id = item.get("id") or item.get("name", f"item_{uuid.uuid4()}")
         node_id = str(uuid.uuid4())
@@ -217,13 +273,16 @@ def build_protocol_graph(
             liquid_type = [labware_id]
             liquid_volume = [1e5]
 
+        res_index += 1
         G.add_node(
             node_id,
-            template_name=f"create_resource",
+            template_name="create_resource",
             resource_name="host_node",
+            name=f"Res {res_index}",
             description=description,
             lab_node_type=lab_node_type,
-            params={
+            footer="create_resource-host_node",
+            param={
                 "res_id": labware_id,
                 "device_id": WORKSTATION_ID,
                 "class_name": "container",
@@ -234,7 +293,6 @@ def build_protocol_graph(
                 "liquid_volume": liquid_volume,
                 "slot_on_deck": "",
             },
-            role=item.get("role", ""),
         )
         resource_last_writer[labware_id] = f"{node_id}:labware"
 
@@ -251,7 +309,7 @@ def build_protocol_graph(
         last_control_node_id = node_id
 
         # 物料流
-        params = step.get("parameters", {})
+        params = step.get("param", {})
         input_resources_possible_names = [
             "vessel",
             "to_vessel",
@@ -299,7 +357,7 @@ def draw_protocol_graph(protocol_graph: WorkflowGraph, output_path: str):
     G = nx.DiGraph()
 
     for node_id, attrs in protocol_graph.nodes.items():
-        label = attrs.get("description", attrs.get("template", node_id[:8]))
+        label = attrs.get("description", attrs.get("template_name", node_id[:8]))
         G.add_node(node_id, label=label, **attrs)
 
     for edge in protocol_graph.edges:
@@ -331,11 +389,13 @@ def draw_protocol_graph(protocol_graph: WorkflowGraph, output_path: str):
     print(f"  - Visualization saved to '{output_path}'")
 
 
-COMPASS = {"n","e","s","w","ne","nw","se","sw","c"}
+COMPASS = {"n", "e", "s", "w", "ne", "nw", "se", "sw", "c"}
+
 
 def _is_compass(port: str) -> bool:
     return isinstance(port, str) and port.lower() in COMPASS
 
+
 def draw_protocol_graph_with_ports(protocol_graph, output_path: str, rankdir: str = "LR"):
     """
     使用 Graphviz 端口语法绘制协议工作流图。
@@ -350,22 +410,22 @@ def draw_protocol_graph_with_ports(protocol_graph, output_path: str, rankdir: st
     # 1) 先用 networkx 搭建有向图，保留端口属性
     G = nx.DiGraph()
     for node_id, attrs in protocol_graph.nodes.items():
-        label = attrs.get("description", attrs.get("template", node_id[:8]))
+        label = attrs.get("description", attrs.get("template_name", node_id[:8]))
         # 保留一个干净的“中心标签”，用于放在 record 的中间槽
-        G.add_node(node_id, _core_label=str(label), **{k:v for k,v in attrs.items() if k not in ("label",)})
+        G.add_node(node_id, _core_label=str(label), **{k: v for k, v in attrs.items() if k not in ("label",)})
 
     edges_data = []
-    in_ports_by_node  = {}  # 收集命名输入端口
+    in_ports_by_node = {}  # 收集命名输入端口
     out_ports_by_node = {}  # 收集命名输出端口
 
     for edge in protocol_graph.edges:
         u = edge["source"]
         v = edge["target"]
-        sp = edge.get("source_port")
+        sp = edge.get("source_handle_key") or edge.get("source_port")
-        tp = edge.get("target_port")
+        tp = edge.get("target_handle_key") or edge.get("target_port")
 
         # 记录到图里（保留原始端口信息）
-        G.add_edge(u, v, source_port=sp, target_port=tp)
+        G.add_edge(u, v, source_handle_key=sp, target_handle_key=tp)
         edges_data.append((u, v, sp, tp))
 
         # 如果不是 compass，就按“命名端口”先归类，等会儿给节点造 record
@@ -377,7 +437,9 @@ def draw_protocol_graph_with_ports(protocol_graph, output_path: str, rankdir: st
     # 2) 转为 AGraph，使用 Graphviz 渲染
     A = to_agraph(G)
     A.graph_attr.update(rankdir=rankdir, splines="true", concentrate="false", fontsize="10")
-    A.node_attr.update(shape="box", style="rounded,filled", fillcolor="lightyellow", color="#999999", fontname="Helvetica")
+    A.node_attr.update(
+        shape="box", style="rounded,filled", fillcolor="lightyellow", color="#999999", fontname="Helvetica"
+    )
     A.edge_attr.update(arrowsize="0.8", color="#666666")
 
     # 3) 为需要命名端口的节点设置 record 形状与 label
@@ -386,18 +448,19 @@ def draw_protocol_graph_with_ports(protocol_graph, output_path: str, rankdir: st
         node = A.get_node(n)
         core = G.nodes[n].get("_core_label", n)
 
-        in_ports  = sorted(in_ports_by_node.get(n, []))
+        in_ports = sorted(in_ports_by_node.get(n, []))
         out_ports = sorted(out_ports_by_node.get(n, []))
 
         # 如果该节点涉及命名端口，则用 record；否则保留原 box
         if in_ports or out_ports:
+
             def port_fields(ports):
                 if not ports:
                     return " "  # 必须留一个空槽占位
                 # 每个端口一个小格子，<p> name
                 return "|".join(f"<{re.sub(r'[^A-Za-z0-9_:.|-]', '_', p)}> {p}" for p in ports)
 
-            left  = port_fields(in_ports)
+            left = port_fields(in_ports)
             right = port_fields(out_ports)
 
             # 三栏：左(入) | 中(节点名) | 右(出)
@@ -410,7 +473,7 @@ def draw_protocol_graph_with_ports(protocol_graph, output_path: str, rankdir: st
     # 4) 给边设置 headport / tailport
     #    - 若端口为 compass：直接用 compass（e.g., headport="e"）
     #    - 若端口为命名端口：使用在 record 中定义的 <port> 名（同名即可）
-    for (u, v, sp, tp) in edges_data:
+    for u, v, sp, tp in edges_data:
         e = A.get_edge(u, v)
 
         # Graphviz 属性：tail 是源，head 是目标
@@ -419,13 +482,13 @@ def draw_protocol_graph_with_ports(protocol_graph, output_path: str, rankdir: st
                 e.attr["tailport"] = sp.lower()
             else:
                 # 与 record label 中 <port> 名一致；特殊字符已在 label 中做了清洗
-                e.attr["tailport"] = re.sub(r'[^A-Za-z0-9_:.|-]', '_', str(sp))
+                e.attr["tailport"] = re.sub(r"[^A-Za-z0-9_:.|-]", "_", str(sp))
 
         if tp:
             if _is_compass(tp):
                 e.attr["headport"] = tp.lower()
             else:
-                e.attr["headport"] = re.sub(r'[^A-Za-z0-9_:.|-]', '_', str(tp))
+                e.attr["headport"] = re.sub(r"[^A-Za-z0-9_:.|-]", "_", str(tp))
 
         # 可选：若想让边更贴边缘，可设置 constraint/spline 等
         # e.attr["arrowhead"] = "vee"
@@ -433,11 +496,14 @@ def draw_protocol_graph_with_ports(protocol_graph, output_path: str, rankdir: st
     # 5) 输出
     A.draw(output_path, prog="dot")
     print(f"  - Port-aware workflow rendered to '{output_path}'")
+
+
 # ---------------- Registry Adapter ----------------
 
 
 class RegistryAdapter:
     """根据 module 的类名（冒号右侧）反查 registry 的 resource_name（原 device_class），并抽取参数顺序"""
+
     def __init__(self, device_registry: Dict[str, Any]):
         self.device_registry = device_registry or {}
         self.module_class_to_resource = self._build_module_class_index()
@@ -455,8 +521,7 @@ class RegistryAdapter:
     def resolve_resource_by_classname(self, class_name: str) -> Optional[str]:
         if not class_name:
             return None
-        return (self.module_class_to_resource.get(class_name)
+        return self.module_class_to_resource.get(class_name) or self.module_class_to_resource.get(class_name.lower())
-                or self.module_class_to_resource.get(class_name.lower()))
 
     def get_device_module(self, resource_name: Optional[str]) -> Optional[str]:
         if not resource_name:
@@ -466,9 +531,7 @@ class RegistryAdapter:
     def get_actions(self, resource_name: Optional[str]) -> Dict[str, Any]:
         if not resource_name:
             return {}
-        return (self.device_registry.get(resource_name, {})
+        return (self.device_registry.get(resource_name, {}).get("class", {}).get("action_value_mappings", {})) or {}
-                .get("class", {})
-                .get("action_value_mappings", {})) or {}
 
     def get_action_schema(self, resource_name: Optional[str], template_name: str) -> Optional[Json]:
         return (self.get_actions(resource_name).get(template_name) or {}).get("schema")

unilabos/workflow/convert_from_json.py

@@ -0,0 +1,356 @@
+"""
+JSON 工作流转换模块
+
+提供从多种 JSON 格式转换为统一工作流格式的功能。
+支持的格式：
+1. workflow/reagent 格式
+2. steps_info/labware_info 格式
+"""
+
+import json
+from os import PathLike
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set, Tuple, Union
+
+from unilabos.workflow.common import WorkflowGraph, build_protocol_graph
+from unilabos.registry.registry import lab_registry
+
+
+def get_action_handles(resource_name: str, template_name: str) -> Dict[str, List[str]]:
+    """
+    从 registry 获取指定设备和动作的 handles 配置
+
+    Args:
+        resource_name: 设备资源名称，如 "liquid_handler.prcxi"
+        template_name: 动作模板名称，如 "transfer_liquid"
+
+    Returns:
+        包含 source 和 target handler_keys 的字典:
+        {"source": ["sources_out", "targets_out", ...], "target": ["sources", "targets", ...]}
+    """
+    result = {"source": [], "target": []}
+
+    device_info = lab_registry.device_type_registry.get(resource_name, {})
+    if not device_info:
+        return result
+
+    action_mappings = device_info.get("class", {}).get("action_value_mappings", {})
+    action_config = action_mappings.get(template_name, {})
+    handles = action_config.get("handles", {})
+
+    if isinstance(handles, dict):
+        # 处理 input handles (作为 target)
+        for handle in handles.get("input", []):
+            handler_key = handle.get("handler_key", "")
+            if handler_key:
+                result["source"].append(handler_key)
+        # 处理 output handles (作为 source)
+        for handle in handles.get("output", []):
+            handler_key = handle.get("handler_key", "")
+            if handler_key:
+                result["target"].append(handler_key)
+
+    return result
+
+
+def validate_workflow_handles(graph: WorkflowGraph) -> Tuple[bool, List[str]]:
+    """
+    校验工作流图中所有边的句柄配置是否正确
+
+    Args:
+        graph: 工作流图对象
+
+    Returns:
+        (is_valid, errors): 是否有效，错误信息列表
+    """
+    errors = []
+    nodes = graph.nodes
+
+    for edge in graph.edges:
+        left_uuid = edge.get("source")
+        right_uuid = edge.get("target")
+        # target_handle_key是target, right的输入节点（入节点）
+        # source_handle_key是source, left的输出节点（出节点）
+        right_source_conn_key = edge.get("target_handle_key", "")
+        left_target_conn_key = edge.get("source_handle_key", "")
+
+        # 获取源节点和目标节点信息
+        left_node = nodes.get(left_uuid, {})
+        right_node = nodes.get(right_uuid, {})
+
+        left_res_name = left_node.get("resource_name", "")
+        left_template_name = left_node.get("template_name", "")
+        right_res_name = right_node.get("resource_name", "")
+        right_template_name = right_node.get("template_name", "")
+
+        # 获取源节点的 output handles
+        left_node_handles = get_action_handles(left_res_name, left_template_name)
+        target_valid_keys = left_node_handles.get("target", [])
+        target_valid_keys.append("ready")
+
+        # 获取目标节点的 input handles
+        right_node_handles = get_action_handles(right_res_name, right_template_name)
+        source_valid_keys = right_node_handles.get("source", [])
+        source_valid_keys.append("ready")
+
+        # 如果节点配置了 output handles，则 source_port 必须有效
+        if not right_source_conn_key:
+            node_name = left_node.get("name", left_uuid[:8])
+            errors.append(f"源节点 '{node_name}' 的 source_handle_key 为空，" f"应设置为: {source_valid_keys}")
+        elif right_source_conn_key not in source_valid_keys:
+            node_name = left_node.get("name", left_uuid[:8])
+            errors.append(
+                f"源节点 '{node_name}' 的 source 端点 '{right_source_conn_key}' 不存在，" f"支持的端点: {source_valid_keys}"
+            )
+
+        # 如果节点配置了 input handles，则 target_port 必须有效
+        if not left_target_conn_key:
+            node_name = right_node.get("name", right_uuid[:8])
+            errors.append(f"目标节点 '{node_name}' 的 target_handle_key 为空，" f"应设置为: {target_valid_keys}")
+        elif left_target_conn_key not in target_valid_keys:
+            node_name = right_node.get("name", right_uuid[:8])
+            errors.append(
+                f"目标节点 '{node_name}' 的 target 端点 '{left_target_conn_key}' 不存在，"
+                f"支持的端点: {target_valid_keys}"
+            )
+
+    return len(errors) == 0, errors
+
+
+# action 到 resource_name 的映射
+ACTION_RESOURCE_MAPPING: Dict[str, str] = {
+    # 生物实验操作
+    "transfer_liquid": "liquid_handler.prcxi",
+    "transfer": "liquid_handler.prcxi",
+    "incubation": "incubator.prcxi",
+    "move_labware": "labware_mover.prcxi",
+    "oscillation": "shaker.prcxi",
+    # 有机化学操作
+    "HeatChillToTemp": "heatchill.chemputer",
+    "StopHeatChill": "heatchill.chemputer",
+    "StartHeatChill": "heatchill.chemputer",
+    "HeatChill": "heatchill.chemputer",
+    "Dissolve": "stirrer.chemputer",
+    "Transfer": "liquid_handler.chemputer",
+    "Evaporate": "rotavap.chemputer",
+    "Recrystallize": "reactor.chemputer",
+    "Filter": "filter.chemputer",
+    "Dry": "dryer.chemputer",
+    "Add": "liquid_handler.chemputer",
+}
+
+
+def normalize_steps(data: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """
+    将不同格式的步骤数据规范化为统一格式
+
+    支持的输入格式：
+    - action + parameters
+    - action + action_args
+    - operation + parameters
+
+    Args:
+        data: 原始步骤数据列表
+
+    Returns:
+        规范化后的步骤列表，格式为 [{"action": str, "parameters": dict, "description": str?, "step_number": int?}, ...]
+    """
+    normalized = []
+    for idx, step in enumerate(data):
+        # 获取动作名称（支持 action 或 operation 字段）
+        action = step.get("action") or step.get("operation")
+        if not action:
+            continue
+
+        # 获取参数（支持 parameters 或 action_args 字段）
+        raw_params = step.get("parameters") or step.get("action_args") or {}
+        params = dict(raw_params)
+
+        # 规范化 source/target -> sources/targets
+        if "source" in raw_params and "sources" not in raw_params:
+            params["sources"] = raw_params["source"]
+        if "target" in raw_params and "targets" not in raw_params:
+            params["targets"] = raw_params["target"]
+
+        # 获取描述（支持 description 或 purpose 字段）
+        description = step.get("description") or step.get("purpose")
+
+        # 获取步骤编号（优先使用原始数据中的 step_number，否则使用索引+1）
+        step_number = step.get("step_number", idx + 1)
+
+        step_dict = {"action": action, "parameters": params, "step_number": step_number}
+        if description:
+            step_dict["description"] = description
+
+        normalized.append(step_dict)
+
+    return normalized
+
+
+def normalize_labware(data: List[Dict[str, Any]]) -> Dict[str, Dict[str, Any]]:
+    """
+    将不同格式的 labware 数据规范化为统一的字典格式
+
+    支持的输入格式：
+    - reagent_name + material_name + positions
+    - name + labware + slot
+
+    Args:
+        data: 原始 labware 数据列表
+
+    Returns:
+        规范化后的 labware 字典，格式为 {name: {"slot": int, "labware": str, "well": list, "type": str, "role": str, "name": str}, ...}
+    """
+    labware = {}
+    for item in data:
+        # 获取 key 名称（优先使用 reagent_name，其次是 material_name 或 name）
+        reagent_name = item.get("reagent_name")
+        key = reagent_name or item.get("material_name") or item.get("name")
+        if not key:
+            continue
+
+        key = str(key)
+
+        # 处理重复 key，自动添加后缀
+        idx = 1
+        original_key = key
+        while key in labware:
+            idx += 1
+            key = f"{original_key}_{idx}"
+
+        labware[key] = {
+            "slot": item.get("positions") or item.get("slot"),
+            "labware": item.get("material_name") or item.get("labware"),
+            "well": item.get("well", []),
+            "type": item.get("type", "reagent"),
+            "role": item.get("role", ""),
+            "name": key,
+        }
+
+    return labware
+
+
+def convert_from_json(
+    data: Union[str, PathLike, Dict[str, Any]],
+    workstation_name: str = "PRCXi",
+    validate: bool = True,
+) -> WorkflowGraph:
+    """
+    从 JSON 数据或文件转换为 WorkflowGraph
+
+    支持的 JSON 格式：
+    1. {"workflow": [...], "reagent": {...}} - 直接格式
+    2. {"steps_info": [...], "labware_info": [...]} - 需要规范化的格式
+
+    Args:
+        data: JSON 文件路径、字典数据、或 JSON 字符串
+        workstation_name: 工作站名称，默认 "PRCXi"
+        validate: 是否校验句柄配置，默认 True
+
+    Returns:
+        WorkflowGraph: 构建好的工作流图
+
+    Raises:
+        ValueError: 不支持的 JSON 格式 或 句柄校验失败
+        FileNotFoundError: 文件不存在
+        json.JSONDecodeError: JSON 解析失败
+    """
+    # 处理输入数据
+    if isinstance(data, (str, PathLike)):
+        path = Path(data)
+        if path.exists():
+            with path.open("r", encoding="utf-8") as fp:
+                json_data = json.load(fp)
+        elif isinstance(data, str):
+            # 尝试作为 JSON 字符串解析
+            json_data = json.loads(data)
+        else:
+            raise FileNotFoundError(f"文件不存在: {data}")
+    elif isinstance(data, dict):
+        json_data = data
+    else:
+        raise TypeError(f"不支持的数据类型: {type(data)}")
+
+    # 根据格式解析数据
+    if "workflow" in json_data and "reagent" in json_data:
+        # 格式1: workflow/reagent（已经是规范格式）
+        protocol_steps = json_data["workflow"]
+        labware_info = json_data["reagent"]
+    elif "steps_info" in json_data and "labware_info" in json_data:
+        # 格式2: steps_info/labware_info（需要规范化）
+        protocol_steps = normalize_steps(json_data["steps_info"])
+        labware_info = normalize_labware(json_data["labware_info"])
+    elif "steps" in json_data and "labware" in json_data:
+        # 格式3: steps/labware（另一种常见格式）
+        protocol_steps = normalize_steps(json_data["steps"])
+        if isinstance(json_data["labware"], list):
+            labware_info = normalize_labware(json_data["labware"])
+        else:
+            labware_info = json_data["labware"]
+    else:
+        raise ValueError(
+            "不支持的 JSON 格式。支持的格式：\n"
+            "1. {'workflow': [...], 'reagent': {...}}\n"
+            "2. {'steps_info': [...], 'labware_info': [...]}\n"
+            "3. {'steps': [...], 'labware': [...]}"
+        )
+
+    # 构建工作流图
+    graph = build_protocol_graph(
+        labware_info=labware_info,
+        protocol_steps=protocol_steps,
+        workstation_name=workstation_name,
+        action_resource_mapping=ACTION_RESOURCE_MAPPING,
+    )
+
+    # 校验句柄配置
+    if validate:
+        is_valid, errors = validate_workflow_handles(graph)
+        if not is_valid:
+            import warnings
+
+            for error in errors:
+                warnings.warn(f"句柄校验警告: {error}")
+
+    return graph
+
+
+def convert_json_to_node_link(
+    data: Union[str, PathLike, Dict[str, Any]],
+    workstation_name: str = "PRCXi",
+) -> Dict[str, Any]:
+    """
+    将 JSON 数据转换为 node-link 格式的字典
+
+    Args:
+        data: JSON 文件路径、字典数据、或 JSON 字符串
+        workstation_name: 工作站名称，默认 "PRCXi"
+
+    Returns:
+        Dict: node-link 格式的工作流数据
+    """
+    graph = convert_from_json(data, workstation_name)
+    return graph.to_node_link_dict()
+
+
+def convert_json_to_workflow_list(
+    data: Union[str, PathLike, Dict[str, Any]],
+    workstation_name: str = "PRCXi",
+) -> List[Dict[str, Any]]:
+    """
+    将 JSON 数据转换为工作流列表格式
+
+    Args:
+        data: JSON 文件路径、字典数据、或 JSON 字符串
+        workstation_name: 工作站名称，默认 "PRCXi"
+
+    Returns:
+        List: 工作流节点列表
+    """
+    graph = convert_from_json(data, workstation_name)
+    return graph.to_dict()
+
+
+# 为了向后兼容，保留下划线前缀的别名
+_normalize_steps = normalize_steps
+_normalize_labware = normalize_labware

unilabos/workflow/from_labwares_and_steps.py

@@ -1,24 +0,0 @@
-import json
-from os import PathLike
-
-from unilabos.workflow.common import build_protocol_graph
-
-
-def from_labwares_and_steps(data_path: PathLike):
-    with data_path.open("r", encoding="utf-8") as fp:
-        d = json.load(fp)
-
-    if "workflow" in d and "reagent" in d:
-        protocol_steps = d["workflow"]
-        labware_info = d["reagent"]
-    elif "steps_info" in d and "labware_info" in d:
-        protocol_steps = _normalize_steps(d["steps_info"])
-        labware_info = _normalize_labware(d["labware_info"])
-    else:
-        raise ValueError("Unsupported protocol format")
-
-    graph = build_protocol_graph(
-        labware_info=labware_info,
-        protocol_steps=protocol_steps,
-        workstation_name="PRCXi",
-    )

unilabos/workflow/wf_utils.py

@@ -0,0 +1,138 @@
+"""
+工作流工具模块
+
+提供工作流上传等功能
+"""
+
+import json
+import os
+import uuid
+from typing import Any, Dict, List, Optional
+
+from unilabos.utils.banner_print import print_status
+
+
+def _is_node_link_format(data: Dict[str, Any]) -> bool:
+    """检查数据是否为 node-link 格式"""
+    return "nodes" in data and "edges" in data
+
+
+def _convert_to_node_link(workflow_file: str, workflow_data: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    将非 node-link 格式的工作流数据转换为 node-link 格式
+
+    Args:
+        workflow_file: 工作流文件路径（用于日志）
+        workflow_data: 原始工作流数据
+
+    Returns:
+        node-link 格式的工作流数据
+    """
+    from unilabos.workflow.convert_from_json import convert_json_to_node_link
+
+    print_status(f"检测到非 node-link 格式，正在转换...", "info")
+    node_link_data = convert_json_to_node_link(workflow_data)
+    print_status(f"转换完成", "success")
+    return node_link_data
+
+
+def upload_workflow(
+    workflow_file: str,
+    workflow_name: Optional[str] = None,
+    tags: Optional[List[str]] = None,
+    published: bool = False,
+) -> Dict[str, Any]:
+    """
+    上传工作流到服务器
+
+    支持的输入格式：
+    1. node-link 格式: {"nodes": [...], "edges": [...]}
+    2. workflow/reagent 格式: {"workflow": [...], "reagent": {...}}
+    3. steps_info/labware_info 格式: {"steps_info": [...], "labware_info": [...]}
+    4. steps/labware 格式: {"steps": [...], "labware": [...]}
+
+    Args:
+        workflow_file: 工作流文件路径（JSON格式）
+        workflow_name: 工作流名称，如果不提供则从文件中读取或使用文件名
+        tags: 工作流标签列表，默认为空列表
+        published: 是否发布工作流，默认为False
+
+    Returns:
+        Dict: API响应数据
+    """
+    # 延迟导入，避免在配置文件加载之前初始化 http_client
+    from unilabos.app.web import http_client
+
+    if not os.path.exists(workflow_file):
+        print_status(f"工作流文件不存在: {workflow_file}", "error")
+        return {"code": -1, "message": f"文件不存在: {workflow_file}"}
+
+    # 读取工作流文件
+    try:
+        with open(workflow_file, "r", encoding="utf-8") as f:
+            workflow_data = json.load(f)
+    except json.JSONDecodeError as e:
+        print_status(f"工作流文件JSON解析失败: {e}", "error")
+        return {"code": -1, "message": f"JSON解析失败: {e}"}
+
+    # 自动检测并转换格式
+    if not _is_node_link_format(workflow_data):
+        try:
+            workflow_data = _convert_to_node_link(workflow_file, workflow_data)
+        except Exception as e:
+            print_status(f"工作流格式转换失败: {e}", "error")
+            return {"code": -1, "message": f"格式转换失败: {e}"}
+
+    # 提取工作流数据
+    nodes = workflow_data.get("nodes", [])
+    edges = workflow_data.get("edges", [])
+    workflow_uuid_val = workflow_data.get("workflow_uuid", str(uuid.uuid4()))
+    wf_name_from_file = workflow_data.get("workflow_name", os.path.basename(workflow_file).replace(".json", ""))
+
+    # 确定工作流名称
+    final_name = workflow_name or wf_name_from_file
+
+    print_status(f"正在上传工作流: {final_name}", "info")
+    print_status(f"  - 节点数量: {len(nodes)}", "info")
+    print_status(f"  - 边数量: {len(edges)}", "info")
+    print_status(f"  - 标签: {tags or []}", "info")
+    print_status(f"  - 发布状态: {published}", "info")
+
+    # 调用 http_client 上传
+    result = http_client.workflow_import(
+        name=final_name,
+        workflow_uuid=workflow_uuid_val,
+        workflow_name=final_name,
+        nodes=nodes,
+        edges=edges,
+        tags=tags,
+        published=published,
+    )
+
+    if result.get("code") == 0:
+        data = result.get("data", {})
+        print_status("工作流上传成功！", "success")
+        print_status(f"  - UUID: {data.get('uuid', 'N/A')}", "info")
+        print_status(f"  - 名称: {data.get('name', 'N/A')}", "info")
+    else:
+        print_status(f"工作流上传失败: {result.get('message', '未知错误')}", "error")
+
+    return result
+
+
+def handle_workflow_upload_command(args_dict: Dict[str, Any]) -> None:
+    """
+    处理 workflow_upload 子命令
+
+    Args:
+        args_dict: 命令行参数字典
+    """
+    workflow_file = args_dict.get("workflow_file")
+    workflow_name = args_dict.get("workflow_name")
+    tags = args_dict.get("tags", [])
+    published = args_dict.get("published", False)
+
+    if workflow_file:
+        upload_workflow(workflow_file, workflow_name, tags, published)
+    else:
+        print_status("未指定工作流文件路径，请使用 -f/--workflow_file 参数", "error")