Add workflow upload func.

2025-12-18 05:21:19 +00:00 · 2025-12-08 19:12:05 +08:00
parent ced961050d
commit 16ee3de086
32 changed files with 811 additions and 222 deletions
--- a/unilabos/workflow/init.py
+++ b/unilabos/workflow/init.py
--- a/unilabos/workflow/common.py
+++ b/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],
-                                        variable_sources: Dict[str, Dict[str, Any]],
-                                        target_node_id: str, base_path: List[str]):
+    def _materialize_wiring_into_inputs(
+        self,
+        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,
-                                      source_handle_io=src.get("output_name", "result"),
-                                      target_handle_io=key)
+                        self.add_edge(
+                            str(src["node_id"]),
+                            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,
-                          node_id: int,
-                          *,
-                          device_key: Optional[str] = None,          # 实例名，如 "ser"
-                          resource_name: Optional[str] = None,       # registry key（原 device_class）
-                          module: Optional[str] = None,
-                          template_name: Optional[str] = None,       # 动作/模板名（原 action_key）
-                          params: Dict[str, Any],
-                          variable_sources: Dict[str, Dict[str, Any]],
-                          add_ready_if_no_vars: bool = True,
-                          prev_node_id: Optional[int] = None,
-                          **extra_attrs) -> None:
+    def add_workflow_node(
+        self,
+        node_id: int,
+        *,
+        device_key: Optional[str] = None,  # 实例名，如 "ser"
+        resource_name: Optional[str] = None,  # registry key（原 device_class）
+        module: Optional[str] = None,
+        template_name: Optional[str] = None,  # 动作/模板名（原 action_key）
+        params: Dict[str, Any],
+        variable_sources: Dict[str, Dict[str, Any]],
+        add_ready_if_no_vars: bool = True,
+        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})
-        return {"directed": True, "multigraph": False, "graph": {}, "nodes": nodes_list, "edges": self.edges, "links": self.edges}
+            nodes_list.append({"uuid": node_id, **node_attrs})
+        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)
-        if not template:
+        template_name = OPERATION_MAPPING.get(operation)
+        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")
-        tp = edge.get("target_port")
+        sp = edge.get("source_handle_key") or edge.get("source_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)
-                or self.module_class_to_resource.get(class_name.lower()))
+        return self.module_class_to_resource.get(class_name) 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, {})
-                .get("class", {})
-                .get("action_value_mappings", {})) or {}
+        return (self.device_registry.get(resource_name, {}).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")
--- a/unilabos/workflow/convert_from_json.py
+++ b/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
--- a/unilabos/workflow/from_labwares_and_steps.py
+++ b/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",
-    )
--- a/unilabos/workflow/wf_utils.py
+++ b/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")