chartflow 0.1__py3-none-any.whl

chartflow/node/node_canvas.py

@@ -0,0 +1,1730 @@
+"""
+节点画布模块 - 主视图组件
+处理所有的用户交互：拖拽、选择、连接、右键菜单等
+"""
+
+from chartflow.node.enums import NodeShape
+import random
+from chartflow.node.layout_utils import DenseLayoutEngine
+import os
+from PyQt6.QtGui import QColor
+
+
+import math
+import json
+from typing import Optional, List, Dict, Any
+from dataclasses import dataclass, field
+
+from PyQt6.QtWidgets import (
+    QGraphicsView, QGraphicsScene, QGraphicsItem,
+    QGraphicsPathItem, QMessageBox, QApplication
+)
+from PyQt6.QtCore import Qt, QPointF, QRectF, pyqtSignal
+from PyQt6.QtGui import (
+    QPainter, QBrush, QPen, QColor, QPainterPath, QTransform,
+    QContextMenuEvent, QMouseEvent, QKeyEvent, QWheelEvent
+)
+
+from chartflow.node.node_item import QNodeItem
+from chartflow.node.connection_item import ConnectionItem
+from chartflow.node.arrow_item import ArrowItem
+from chartflow.node.port_item import QNodePort
+from chartflow.node.selection_rect import SelectionRect
+from chartflow.node.style_panel import StylePanel
+from chartflow.node.enums import NodeShape, ConnectionType
+from chartflow.node.layout_utils import DenseLayoutEngine, ViewportFitter
+from chartflow.node.popmenu import QCanvasPopMenu, QLinePopMenu, QNodePopMenu
+
+
+def _build_temp_bezier(source_pos: QPointF, scene_pos: QPointF) -> QPainterPath:
+    """构造拖拽时的临时贝塞尔虚线(从 source_pos 指向 scene_pos)。
+
+    node 外环拖拽与 port 拖拽共用, 控制点算法与
+    ConnectionItem._updateBezierPath 保持一致。
+    """
+    path = QPainterPath()
+    path.moveTo(source_pos)
+
+    dx = scene_pos.x() - source_pos.x()
+    dy = scene_pos.y() - source_pos.y()
+    distance = math.sqrt(dx * dx + dy * dy)
+    offset = min(distance * 0.5, 150)
+
+    if abs(dx) > abs(dy):
+        ctrl1 = QPointF(source_pos.x() + offset * (1 if dx > 0 else -1), source_pos.y())
+        ctrl2 = QPointF(scene_pos.x() - offset * (1 if dx > 0 else -1), scene_pos.y())
+    else:
+        ctrl1 = QPointF(source_pos.x(), source_pos.y() + offset * (1 if dy > 0 else -1))
+        ctrl2 = QPointF(scene_pos.x(), scene_pos.y() - offset * (1 if dy > 0 else -1))
+
+    path.cubicTo(ctrl1, ctrl2, scene_pos)
+    return path
+
+
+def _resolve_port(node, side, name):
+    """按 (side, name) 在 node._port_items 中找回对应的 ``QNodePort``。
+
+    用于 importData 还原 port↔port 连线。side/name 任一缺失、或该侧无
+    匹配 name 的端口时返回 None(连接退化为 node 边缘锚定)。
+    """
+    if not side or not name:
+        return None
+    items = node._port_items.get(side, [])
+    for it in items:
+        if it.spec.name == name:
+            return it
+    return None
+
+
+# 跨节点可连接性(linkables)的全部合法键。按连线两端点类型分类:
+#   - 两端均无 port          -> "node->node"
+#   - 仅目标端有 port         -> "node->port"
+#   - 仅源端有 port           -> "port->node"
+#   - 两端均 port, 按 side 组合 -> "{src_side}->{tgt_side}"
+#     (left->right / right->left / left->left / right->right)
+# 仅作用于跨节点连线(同节点自指由各节点 selfrefs 控制)。
+_LINKABLES_KEYS = (
+    "node->node",
+    "node->port",
+    "port->node",
+    "left->right",
+    "right->left",
+    "left->left",
+    "right->right",
+)
+
+# 默认值 = 既有逻辑: 端口异极(left↔right)允许, 同极(left->left / right->right)
+# 禁止, 含/不含 node 的端点组合均允许。
+_LINKABLES_DEFAULTS: Dict[str, bool] = {
+    "node->node": True,
+    "node->port": True,
+    "port->node": True,
+    "left->right": True,
+    "right->left": True,
+    "left->left": False,
+    "right->right": False,
+}
+
+
+def _linkable_key(source_port, target_port) -> Optional[str]:
+    """将一条跨节点连线的两端点类型分类为 linkables 键。
+
+    Args:
+        source_port: 源端 QNodePort, None 表示锚定到节点边缘。
+        target_port: 目标端 QNodePort, None 表示锚定到节点边缘。
+
+    Returns:
+        linkables 键字符串(见 _LINKABLES_KEYS); 端点 side 非 left/right 时
+        返回 None(理论上不会发生, 视为不可分类)。
+    """
+    if source_port is None and target_port is None:
+        return "node->node"
+    if source_port is None:
+        return "node->port"
+    if target_port is None:
+        return "port->node"
+    key = f"{source_port.side}->{target_port.side}"
+    return key if key in _LINKABLES_DEFAULTS else None
+
+
+@dataclass
+class AtomOperation:
+    """原子操作 - 记录单个可追踪的修改"""
+    NULL: str = field(default="</$NULL>", repr=False)
+
+    old: Any = None
+    new: Any = None
+    jpath: List[str] = field(default_factory=list)
+    act: bool = True
+
+    def __postInit(self):
+        """初始化后将 NULL 字符串转为常量引用"""
+        if self.old == "</$NULL>":
+            self.old = AtomOperation.NULL
+        if self.new == "</$NULL>":
+            self.new = AtomOperation.NULL
+
+
+class QNodeCanvas(QGraphicsView):
+    """
+    节点画布 - 主视图组件
+    处理所有的用户交互：拖拽、选择、连接、右键菜单等
+    """
+    
+    nodeSelected = pyqtSignal(object)  # 节点选中信号
+    connectionCreated = pyqtSignal(object)  # 连接创建信号
+    
+    def __init__(self, parent: Optional['QWidget'] = None) -> None:
+        super().__init__(parent)
+
+        # 创建场景
+        self._scene: QGraphicsScene = QGraphicsScene(self)
+        self._scene.setSceneRect(-5000, -5000, 10000, 10000)
+        self.setScene(self._scene)
+
+        # 连接场景的选择改变信号
+        self._scene.selectionChanged.connect(self._onSelectionChanged)
+        
+        # 设置渲染选项
+        self.setRenderHints(QPainter.RenderHint.Antialiasing | QPainter.RenderHint.SmoothPixmapTransform)
+        self.setViewportUpdateMode(QGraphicsView.ViewportUpdateMode.FullViewportUpdate)
+        self.setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOn)
+        self.setVerticalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOn)
+        self.setTransformationAnchor(QGraphicsView.ViewportAnchor.AnchorUnderMouse)
+        self.setResizeAnchor(QGraphicsView.ViewportAnchor.AnchorViewCenter)
+        
+        # 拖拽模式
+        self.setDragMode(QGraphicsView.DragMode.NoDrag)
+        
+        # 状态变量
+        self._nodes: List[QNodeItem] = []
+        self._connections: List[ConnectionItem] = []
+        self._start_node: Optional[QNodeItem] = None  # 起点节点
+        self._drag_start_pos: Optional[QPointF] = None
+        self._temp_connection: Optional[QGraphicsPathItem] = None
+        self._source_node_for_connection: Optional[QNodeItem] = None
+        self._selection_rect: Optional[SelectionRect] = None
+        self._selection_start_pos: Optional[QPointF] = None
+        self._is_panning: bool = False
+        self._pan_start_pos: Optional[QPointF] = None
+        self._space_panning: bool = False  # 按住 Space + 左键拖拽 = 平移（中键不可用时的可靠替代）
+        self._is_creating_connection: bool = False
+
+        # port 连线拖拽状态(port 优先级高于 node 外环)
+        self._is_creating_port_connection: bool = False
+        self._source_port_for_connection: Optional[QNodePort] = None
+        self._temp_port_connection: Optional[QGraphicsPathItem] = None
+        # 连线拖拽中光标命中的目标 port(画布接管移动事件, hover 不再由场景派发,
+        # 故由画布手动追踪并驱动目标 port 的描边/label)
+        self._hovered_target_port: Optional[QNodePort] = None
+        # 连线拖拽中光标命中的目标 node(未命中 port 时, 让被捕获的节点描边)
+        self._hovered_target_node: Optional[QNodeItem] = None
+        
+        # 框选状态（修改：不需要按alt，直接拖动即可框选）
+        self._is_selecting: bool = False
+        
+        # 箭头拖拽状态
+        self._dragged_arrow: Optional[ArrowItem] = None
+        self._original_connection: Optional[ConnectionItem] = None
+        self._original_is_bidirectional: bool = False
+        self._temp_new_connection: Optional[QGraphicsPathItem] = None
+
+        # 修改追踪系统
+        self._changed: bool = False
+        self._json_file_path: Optional[str] = None
+
+        # 跨节点可连接性规则: 控制不同节点之间哪些端点类型组合允许建线。
+        # 与各节点的 selfrefs(同节点自指)互补 —— linkables 只作用于跨节点连线。
+        # 默认值 = 既有逻辑(见 _LINKABLES_DEFAULTS); 修改后(通过 linkables 赋值
+        # 或 setLinkables)会自动移除已不合规的连接。
+        self._linkables: Dict[str, bool] = dict(_LINKABLES_DEFAULTS)
+
+        # 拖拽位置追踪
+        self._drag_start_positions: Dict[int, QPointF] = {}
+
+        # 创建样式面板（初始隐藏）
+        self._style_panel: StylePanel = StylePanel(self)
+        self._style_panel.setGeometry(
+            10, self.height() - StylePanel.PANEL_HEIGHT - 10,
+            self.width() - 20, StylePanel.PANEL_HEIGHT,
+        )
+        self._style_panel.hide()
+
+        # 连接样式改变信号
+        self._style_panel.styleChanged.connect(self._onStyleChanged)
+
+        # 设置背景
+        self._setupBackground()
+
+        # 启用鼠标跟踪
+        self.setMouseTracking(True)
+
+        # 接受键盘焦点，使 Space+左键平移等键盘交互可用
+        self.setFocusPolicy(Qt.FocusPolicy.StrongFocus)
+
+        # 右键菜单(空白画布菜单长期持有; 连线菜单每次右键重构, 见 contextMenuEvent)
+        self.menu: QCanvasPopMenu = QCanvasPopMenu(self, self)
+        self.lmenu: Optional[QLinePopMenu] = None
+    
+    def _setupBackground(self) -> None:
+        """设置画布背景"""
+        # Use the centralized theme color so the canvas harmonizes with the
+        # surrounding chrome; fall back to the legacy light gray if the theme
+        # module is unavailable.
+        try:
+            from chartflow.theme import canvasBackground as _canvas_bg
+            bg = _canvas_bg()
+        except Exception:
+            bg = QColor("#F0F0F0")
+        self.setBackgroundBrush(QBrush(bg))
+    
+    @property
+    def changed(self) -> bool:
+        """画布是否有未保存的修改"""
+        return self._changed
+
+    @changed.setter
+    def changed(self, value: bool) -> None:
+        """设置修改状态，自动更新窗口标题"""
+        if self._changed != value:
+            self._changed = value
+            self._updateWindowTitle()
+
+    def _updateWindowTitle(self) -> None:
+        """更新窗口标题显示"""
+        parent = self.parent()
+        while parent and parent.parent() is not None:
+            parent = parent.parent()
+
+        if parent and hasattr(parent, 'setWindowTitle'):
+            software_name = "NodeCanvasWidget"
+
+            if self._json_file_path:
+                file_name = os.path.basename(self._json_file_path)
+            else:
+                file_name = "New Graph"
+
+            title = f"{software_name} - {file_name}"
+            if self._changed:
+                title += " *"
+
+            parent.setWindowTitle(title)
+
+    def setJsonFilePath(self, file_path: Optional[str]) -> None:
+        """设置当前 JSON 文件路径"""
+        if self._json_file_path != file_path:
+            self._json_file_path = file_path
+            self._updateWindowTitle()
+
+    def getJsonFilePath(self) -> Optional[str]:
+        """获取当前 JSON 文件路径"""
+        return self._json_file_path
+
+    def resetChangedState(self) -> None:
+        """重置修改状态（Save 成功后调用）"""
+        self.changed = False
+
+    def _onSelectionChanged(self) -> None:
+        """选择改变时更新样式面板"""
+        selected_nodes = [item for item in self._scene.selectedItems() if isinstance(item, QNodeItem)]
+        self._style_panel.setSelectedNodes(selected_nodes)
+        self.nodeSelected.emit(selected_nodes[0] if selected_nodes else None)
+
+    def _onStyleChanged(self) -> None:
+        """样式改变时设置修改状态"""
+        self.changed = True
+
+    @property
+    def nodes(self) -> List[QNodeItem]:
+        """获取所有节点"""
+        return self._nodes.copy()
+    
+    @property
+    def connections(self) -> List[ConnectionItem]:
+        """获取所有连接"""
+        return self._connections.copy()
+
+    # ------------------------------------------------------------------ #
+    # 跨节点可连接性(linkables)
+    # ------------------------------------------------------------------ #
+    @property
+    def linkables(self) -> Dict[str, bool]:
+        """跨节点可连接性规则: 控制不同节点之间哪些端点类型组合允许建线。
+
+        与各节点的 ``selfrefs``(同节点自指)互补 —— linkables 只作用于
+        **跨节点**连线(同节点自指由 source 节点的 selfrefs 控制)。
+
+        七个键(默认值 = 既有逻辑):
+
+        - ``"node->node"`` (默认 True): 源节点边缘 → 目标节点边缘。
+        - ``"node->port"`` (默认 True): 源节点边缘 → 目标 port。
+        - ``"port->node"`` (默认 True): 源 port → 目标节点边缘。
+        - ``"left->right"`` (默认 True): 源 left port → 目标 right port。
+        - ``"right->left"`` (默认 True): 源 right port → 目标 left port。
+        - ``"left->left"`` (默认 False): 源 left port → 目标 left port。
+        - ``"right->right"`` (默认 False): 源 right port → 目标 right port。
+
+        可读可写:
+
+        - **读取**返回内部 dict(**非副本**), 可直接改值, 但直接改值**不会**
+          自动清理已有连接(与 selfrefs 一致)。若需改值后立即清理, 改完调用
+          :meth:`enforceLinkables`, 或改用整体赋值/setLinkables。
+        - **整体赋值**(``canvas.linkables = {...}``)或 :meth:`setLinkables`
+          会校验键集、合并未知键的默认值, 并**自动移除**已不合规的连接::
+
+              canvas.linkables = {"left->left": True, "right->right": False}
+              # 部分修改 + 立即清理:
+              canvas.setLinkables(left__right=False)
+        """
+        return self._linkables
+
+    @linkables.setter
+    def linkables(self, value: Dict[str, bool]) -> None:
+        """整体设置 linkables(覆盖式): 校验后自动清理不合规连接。"""
+        self._applyLinkables(value, merge=False)
+        self.enforceLinkables()
+
+    def setLinkables(self, merge: bool = True, **kwargs: bool) -> None:
+        """设置 linkables, 默认**合并**(只改传入的键, 其余保持原值)。
+
+        Args:
+            merge: True=部分修改(默认); False=整体覆盖(未给出的键取默认值)。
+            **kwargs: 要改的键值, 如 ``left__right=False``。
+                (Python 标识符不能含 ``->``, 用双下划线 ``__`` 代替,
+                例如 ``left__right`` 对应键 ``"left->right"``。)
+
+        修改后自动调用 :meth:`enforceLinkables` 清理不合规连接。
+        """
+        updates: Dict[str, bool] = {}
+        for k, v in kwargs.items():
+            key = k.replace("__", "->")
+            if key not in _LINKABLES_DEFAULTS:
+                raise KeyError(f"未知 linkables 键: {k!r} (-> {key!r})")
+            updates[key] = bool(v)
+        self._applyLinkables(updates if merge else {**_LINKABLES_DEFAULTS, **updates},
+                             merge=merge)
+        self.enforceLinkables()
+
+    def _applyLinkables(self, value: Dict[str, bool], merge: bool) -> None:
+        """校验并写入 _linkables。merge=True 时保留未给出的键。"""
+        if not isinstance(value, dict):
+            raise TypeError(f"linkables 必须是 dict，得到 {type(value).__name__}")
+        for k, v in value.items():
+            if k not in _LINKABLES_DEFAULTS:
+                raise KeyError(f"未知 linkables 键: {k!r}")
+            if not isinstance(v, bool):
+                raise TypeError(f"linkables[{k!r}] 必须是 bool，得到 {type(v).__name__}")
+        if merge:
+            self._linkables.update(value)
+        else:
+            # 整体覆盖: 以默认值打底, 再叠加传入项, 保证 7 个键齐全
+            self._linkables = {**_LINKABLES_DEFAULTS, **value}
+
+    def isLinkable(self, source_node: QNodeItem, target_node: QNodeItem,
+                   source_port=None, target_port=None) -> bool:
+        """判定一条(潜在的)跨节点连线是否符合当前 linkables 规则。
+
+        同节点自指不在 linkables 范畴(由 source 节点 selfrefs 控制), 直接
+        返回 True, 交由 addConnection 的自指分支裁决。
+        """
+        if source_node is target_node:
+            return True
+        key = _linkable_key(source_port, target_port)
+        if key is None:
+            return False
+        return self._linkables.get(key, _LINKABLES_DEFAULTS.get(key, False))
+
+    def enforceLinkables(self) -> List[ConnectionItem]:
+        """按当前 linkables 规则清理**跨节点**连线, 移除已不合规者。
+
+        同节点自指不受 linkables 影响(由 selfrefs 控制), 跳过。
+
+        Returns:
+            被移除的连接列表(便于测试/日志)。
+        """
+        removed: List[ConnectionItem] = []
+        for conn in self._connections[:]:  # connections 副本, 可安全边删边遍历
+            if conn.sourceNode is conn.targetNode:
+                continue  # 自指: 由 selfrefs 管, linkables 不干预
+            if not self.isLinkable(conn.sourceNode, conn.targetNode,
+                                   conn.sourcePort, conn.targetPort):
+                self.removeConnection(conn)
+                removed.append(conn)
+        return removed
+
+    @property
+    def startNode(self) -> Optional[QNodeItem]:
+        """获取起点节点"""
+        return self._start_node
+
+    @startNode.setter
+    def startNode(self, node: Optional[QNodeItem]) -> None:
+        """设置起点节点"""
+        # 清除旧的起点标记
+        if self._start_node is not None and self._start_node != node:
+            self._start_node.setStartMarkerVisible(False)
+
+        self._start_node = node
+
+        # 设置新的起点标记
+        if node is not None:
+            node.setStartMarkerVisible(True)
+    
+    def addNode(self, name: str, position: Optional[QPointF] = None, 
+                shape: NodeShape = NodeShape.ELLIPSE) -> QNodeItem:
+        """
+        添加一个新节点
+
+        Args:
+            name: 节点名称
+            position: 节点位置，默认为画布中心
+            shape: 节点形状
+
+        Returns:
+            创建的节点项
+        """
+        if position is None:
+            position = self.mapToScene(self.viewport().rect().center())
+
+        node = QNodeItem(name, position, shape)
+        self._scene.addItem(node)
+        self._nodes.append(node)
+        
+        # 连接节点信号
+        node.editRequested.connect(self._onNodeEditRequested)
+
+        # 注入节点右键菜单(此时 node 已加入 self._scene, canvas 引用可用)
+        node.menu = QNodePopMenu(self, node)
+
+        self.changed = True
+        return node
+    
+    def removeNode(self, node: QNodeItem) -> None:
+        """移除节点"""
+        if node not in self._nodes:
+            return
+        
+        # 移除相关连接
+        connections_to_remove = [conn for conn in self._connections 
+                                if conn.sourceNode == node or conn.targetNode == node]
+        for conn in connections_to_remove:
+            self.removeConnection(conn)
+        
+        # 从场景中移除
+        self._scene.removeItem(node)
+        self._nodes.remove(node)
+        
+        # 如果删除的是起点节点，清除起点标记
+        if self._start_node == node:
+            self._start_node = None
+        
+        self.changed = True
+    
+    def _flashReject(self, source_node, target_node, source_port, target_port) -> None:
+        """规则拒绝(selfrefs/linkables/connectable)时, 闪烁两端 node/port。
+
+        某端绑定 port 则闪 port, 否则闪 node。供 addConnection 在不合规拒绝点调用。
+        """
+        src_item = source_port if source_port is not None else source_node
+        tgt_item = target_port if target_port is not None else target_node
+        if src_item is not None:
+            src_item.flashError()
+        if tgt_item is not None:
+            tgt_item.flashError()
+
+    def addConnection(self, source_node: QNodeItem, target_node: QNodeItem,
+                      is_bidirectional: bool = False,
+                      connection_type: ConnectionType = ConnectionType.BEZIER,
+                      *, check_partners: bool = True,
+                      source_port=None, target_port=None) -> Optional[ConnectionItem]:
+        """
+        添加两个节点之间的连接
+
+        Args:
+            source_node: 源节点
+            target_node: 目标节点
+            is_bidirectional: 是否是双向连接
+            connection_type: 连线类型
+            check_partners: 是否检查源节点的伙伴节点（拖拽箭头时为False）
+            source_port: 源端端口(QNodePort), 端点锚定到该 port; None=节点边缘
+            target_port: 目标端端口(QNodePort), 端点锚定到该 port; None=节点边缘
+
+        Returns:
+            创建的连接线项，如果连接已存在则返回已存在的连接；
+            若是 port 自指(任意一端为 port 且两端同节点)则返回 None。
+        """
+        # 自指规则(同节点): 按 source_node.selfrefs 判定 6 类自指是否允许。
+        #   - node->node: 两端均无 port
+        #   - port->port: 两端均 port 且同极/同一 port(不含异极)
+        #   - node->port: 源无 port、目标有 port
+        #   - port->node: 源有 port、目标无 port
+        #   - left->right: 源=left port、目标=right port
+        #   - right->left: 源=right port、目标=left port
+        # 被允许的自指由 ConnectionItem 绘制为环/椭圆环。
+        if source_node is target_node:
+            sr = source_node.selfrefs
+            if source_port is None and target_port is None:
+                # node→node 自环
+                if not sr.get("node->node", True):
+                    self._flashReject(source_node, target_node, source_port, target_port)
+                    return None
+            elif source_port is not None and target_port is not None:
+                # port→port: 异极按方向(left->right / right->left), 同极/同 port 走 port->port
+                if source_port.side != target_port.side:
+                    key = "right->left" if source_port.side == "right" else "left->right"
+                    if not sr.get(key, True):
+                        self._flashReject(source_node, target_node, source_port, target_port)
+                        return None
+                else:
+                    if not sr.get("port->port", False):
+                        self._flashReject(source_node, target_node, source_port, target_port)
+                        return None
+            elif source_port is not None:
+                # port→node (源 port、目标节点边缘)
+                if not sr.get("port->node", False):
+                    self._flashReject(source_node, target_node, source_port, target_port)
+                    return None
+            else:  # target_port is not None
+                # node→port (源节点边缘、目标 port)
+                if not sr.get("node->port", False):
+                    self._flashReject(source_node, target_node, source_port, target_port)
+                    return None
+
+        # 跨节点可连接性规则(linkables): 按 (源端点类型, 目标端点类型) 分类,
+        # 对照 canvas.linkables 判定是否允许。默认值等价于旧逻辑(同极 port 禁止、
+        # 异极 port / 含 node 的端点组合允许); 同节点自指已由上面 selfrefs 处理。
+        if source_node is not target_node:
+            if not self.isLinkable(source_node, target_node, source_port, target_port):
+                self._flashReject(source_node, target_node, source_port, target_port)
+                return None
+
+        # 任一端点不可连线则拒绝(拖拽创建 / 箭头重连 / 导入都经过此处)
+        if not source_node.isConnectable() or not target_node.isConnectable():
+            self._flashReject(source_node, target_node, source_port, target_port)
+            return None
+
+        # 检查是否已存在连接(按 (node, port) 精确判重; port 为 None 时退化为 node 级)
+        # NOTE: 自指(right→left 与 left→right 等)是相互独立的边, 不做反向合并,
+        # 故仅对非自指连线执行"反向连接转双向"。
+        is_selfref = source_node is target_node
+        for conn in self._connections:
+            # 1. 检查源端点到目标端点的直接连接（严格重复）
+            same_forward = (
+                conn.sourceNode == source_node and conn.sourcePort is source_port
+                and conn.targetNode == target_node and conn.targetPort is target_port
+            )
+            if same_forward:
+                conn.flashError()  # 闪烁显示错误
+                return conn
+
+            # 2. 检查反向连接（目标到源的连接）— 自指连线跳过(方向独立, 不合并)
+            if is_selfref:
+                continue
+            same_reverse = (
+                conn.sourceNode == target_node and conn.sourcePort is target_port
+                and conn.targetNode == source_node and conn.targetPort is source_port
+            )
+            if same_reverse:
+                # 反向连接已存在，将其转换为双向连线
+                if conn.isBidirectional:
+                    conn.flashError()  # 已经是双向，闪烁错误
+                    return conn
+                conn.isBidirectional = True
+                conn.updatePath()
+                self.changed = True
+                return conn
+
+        connection = ConnectionItem(
+            source_node, target_node, is_bidirectional, connection_type,
+            source_port=source_port, target_port=target_port,
+        )
+        self._scene.addItem(connection)
+        self._connections.append(connection)
+        
+        # 添加箭头到场景
+        self._scene.addItem(connection.targetArrow)
+        if connection.sourceArrow:
+            self._scene.addItem(connection.sourceArrow)
+        
+        # 设置箭头拖拽回调
+        connection.setArrowDragCallbacks(
+            started=self._onArrowDragStarted,
+            moved=self._onArrowDragMoved,
+            finished=self._onArrowDragFinished
+        )
+        
+        self.changed = True
+        self.connectionCreated.emit(connection)
+        return connection
+    
+    def removeConnection(self, connection: ConnectionItem) -> None:
+        """移除连接"""
+        if connection not in self._connections:
+            return
+        
+        # 移除箭头
+        connection.removeArrows()
+        
+        # 从场景中移除
+        self._scene.removeItem(connection)
+        self._connections.remove(connection)
+        
+        self.changed = True
+    
+    def _onNodeEditRequested(self, node: QNodeItem) -> None:
+        """节点编辑请求回调"""
+        # 如果节点有自定义编辑器，打开它
+        if node.editorClass:
+            editor = node.editorClass(node)
+            editor.setWindowTitle(editor.getTitle())
+            editor.show()
+    
+    def _updateHoveredTargetPort(self, new_target: Optional[QNodePort]) -> None:
+        """连线拖拽中更新光标命中的目标 port 高亮(描边 + label)。
+
+        连线拖拽期间场景 hover 派发被压制, 故由画布手动追踪并驱动目标 port
+        的描边。仅在目标变化时刷新, 离开旧目标时清除其高亮态。
+        """
+        if new_target is self._hovered_target_port:
+            return
+        if self._hovered_target_port is not None:
+            self._hovered_target_port.setDropTarget(False)
+        self._hovered_target_port = new_target
+        if new_target is not None:
+            new_target.setDropTarget(True)
+
+    def _updateHoveredTargetNode(self, new_target: Optional[QNodeItem]) -> None:
+        """连线拖拽中更新光标命中的目标节点高亮(描边)。
+
+        与 port 落点高亮互斥: 命中 port 时由调用方传 ``None`` 取消节点高亮。
+        仅在目标变化时刷新, 离开旧目标时清除其描边态。
+        """
+        if new_target is self._hovered_target_node:
+            return
+        if self._hovered_target_node is not None:
+            self._hovered_target_node.setDropTarget(False)
+        self._hovered_target_node = new_target
+        if new_target is not None:
+            new_target.setDropTarget(True)
+
+    def _onPortConnectionDragStart(self, port_graphic: QNodePort, scene_pos: QPointF) -> None:
+        """port 被左键按下: 开始 port 连线拖拽。
+
+        镜像 node 外环拖拽的初始化, 但起点端点是 port 而非 node。
+        后续的 move/release 由本视图的 mouseMoveEvent/mouseReleaseEvent 接管。
+        """
+        self._is_creating_port_connection = True
+        self._source_port_for_connection = port_graphic
+        self._drag_start_pos = scene_pos
+
+        # 创建临时虚线连接线(与 node 拖拽一致)
+        self._temp_port_connection = QGraphicsPathItem()
+        pen = QPen(QColor("#666666"), 2, Qt.PenStyle.DashLine)
+        self._temp_port_connection.setPen(pen)
+        self._temp_port_connection.setZValue(5)
+        self._scene.addItem(self._temp_port_connection)
+
+    def _onArrowDragStarted(self, pos: QPointF) -> None:
+        """箭头拖拽开始回调"""
+        # 找到当前被拖拽的箭头
+        for conn in self._connections:
+            for arrow in conn.arrows:
+                if arrow.isDragging:
+                    self._dragged_arrow = arrow
+                    self._original_connection = arrow.connection
+                    self._original_is_bidirectional = arrow.connection.isBidirectional
+
+                    # 创建临时连接线
+                    self._temp_new_connection = QGraphicsPathItem()
+                    pen = QPen(QColor("#666666"), 2, Qt.PenStyle.DashLine)
+                    self._temp_new_connection.setPen(pen)
+                    self._temp_new_connection.setZValue(5)
+                    self._scene.addItem(self._temp_new_connection)
+                    return
+    
+    def _onArrowDragMoved(self, pos: QPointF) -> None:
+        """箭头拖拽移动回调"""
+        if self._dragged_arrow and self._temp_new_connection and self._original_connection:
+            # 根据拖拽的箭头类型确定虚线起点
+            if self._dragged_arrow.isSourceArrow:
+                # 拖拽源端箭头（反向箭头），从目标节点中心发出
+                start_pos = self._original_connection.targetNode.sceneBoundingRect().center()
+            else:
+                # 拖拽目标端箭头（正向箭头），从源节点中心发出
+                start_pos = self._original_connection.sourceNode.sceneBoundingRect().center()
+
+            path = QPainterPath()
+            path.moveTo(start_pos)
+            path.lineTo(pos)
+            self._temp_new_connection.setPath(path)
+    
+    def _onArrowDragFinished(self, pos: QPointF, is_success: bool) -> None:
+        """箭头拖拽结束回调"""
+        # 移除临时连接线
+        if self._temp_new_connection:
+            self._scene.removeItem(self._temp_new_connection)
+            self._temp_new_connection = None
+
+        if self._dragged_arrow and self._original_connection:
+            connection = self._original_connection
+
+            if is_success:
+                # 查找目标节点
+                item = self._scene.itemAt(pos, QTransform())
+                target_node = None
+                while item:
+                    if isinstance(item, QNodeItem):
+                        target_node = item
+                        break
+                    item = item.parentItem()
+
+                if target_node:
+                    # 确定新连接的源节点和目标节点
+                    # 从箭头的起点创建新连接
+                    # isSourceArrow=False: targetArrow 从 sourceNode 发出 -> 新源节点是 sourceNode
+                    # isSourceArrow=True: sourceArrow 从 targetNode 发出 -> 新源节点是 targetNode
+                    if self._dragged_arrow.isSourceArrow:
+                        # 拖拽的是源端箭头（从 targetNode 发出，指向 sourceNode）
+                        # 新源节点是 targetNode
+                        new_source = connection.targetNode
+                        new_target = target_node
+                    else:
+                        # 拖拽的是目标端箭头（从 sourceNode 发出，指向 targetNode）
+                        # 新源节点是 sourceNode
+                        new_source = connection.sourceNode
+                        new_target = target_node
+
+                    # 检查是否是同一连接
+                    if new_source != new_target:
+                        # 保存原始连接的状态
+                        orig_source = connection.sourceNode
+                        orig_target = connection.targetNode
+                        orig_is_source_arrow = self._dragged_arrow.isSourceArrow
+                        orig_is_bidirectional = self._original_is_bidirectional
+
+                        # 检查是否拖拽回同一个目标（连接未改变）
+                        same_target = (new_source == orig_source and new_target == orig_target) or \
+                           (orig_is_bidirectional and new_source == orig_target and new_target == orig_source)
+                        if same_target:
+                            # 拖拽回同一目标，不做任何操作
+                            new_conn = None
+                        else:
+                            # 检查目标连接是否已存在
+                            target_exists = any(
+                                c.sourceNode == new_source and c.targetNode == new_target
+                                for c in self._connections
+                            )
+                            if target_exists:
+                                # 目标连接已存在，闪烁错误但不删除原连接
+                                connection.flashError()
+                                new_conn = None
+                            else:
+                                # 先尝试创建新连接（如果失败会闪烁）
+                                # 拖拽箭头时，不检查源节点的双向伙伴（checkPartners=False）
+                                new_conn = self.addConnection(new_source, new_target, check_partners=False)
+
+                        if new_conn is not None and new_conn != connection:
+                            # 新连接创建成功
+                            # 处理原始连接：如果是双向连接，保留未拖拽方向的连接
+                            if orig_is_bidirectional:
+                                # 双向连接需要特殊处理：保留未拖拽方向的连接
+                                if orig_is_source_arrow:
+                                    # 拖拽的是源端箭头 (B->A)
+                                    # 原连接: targetArrow=A->B, sourceArrow=B->A
+                                    # 需要保留: A->B (targetArrow)
+                                    # 移除: B->A (sourceArrow)
+                                    # 直接设置为单向即可，会移除 sourceArrow
+                                    connection.isBidirectional = False
+                                else:
+                                    # 拖拽的是目标端箭头 (A->B)
+                                    # 原连接: targetArrow=A->B, sourceArrow=B->A
+                                    # 需要保留: B->A (sourceArrow)
+                                    # 移除: A->B (targetArrow)
+                                    # 先交换方向，使要保留的箭头成为 targetArrow
+                                    connection.swapDirection()
+                                    # 然后设置为单向，这会移除 sourceArrow (原 targetArrow)
+                                    connection.isBidirectional = False
+                            else:
+                                # 单向连接，直接删除
+                                self.removeConnection(connection)
+                        # 如果 new_conn == connection，说明是已存在的连接被返回
+                        # addConnection 内部已经闪烁了已存在的连接，这里不再闪烁
+                    else:
+                        # 连接到同一节点，恢复并闪烁
+                        connection.flashError()
+                else:
+                    # 没有连接到节点，恢复并闪烁
+                    connection.flashError()
+            else:
+                # 连接失败，恢复并闪烁
+                connection.flashError()
+
+            self._dragged_arrow = None
+            self._original_connection = None
+            self._original_is_bidirectional = False
+    
+    def mousePressEvent(self, event: QMouseEvent) -> None:
+        """鼠标按下事件"""
+        scene_pos = self.mapToScene(event.pos())
+
+        # 检查是否有节点正在编辑名称
+        for node in self._nodes:
+            if node.isEditingName:
+                # 检查点击是否在代理控件内
+                proxy = getattr(node, '_name_edit_proxy', None)
+                if proxy and proxy.sceneBoundingRect().contains(scene_pos):
+                    # 点击在编辑区域内，不处理
+                    break
+                else:
+                    # 点击在编辑区域外，完成编辑
+                    node._finishNameEdit()
+                    # 继续处理其他鼠标事件
+                    break
+
+        if event.button() == Qt.MouseButton.MiddleButton:
+            # 中键按下 - 开始平移
+            self._is_panning = True
+            self._pan_start_pos = event.pos()
+            self.setCursor(Qt.CursorShape.ClosedHandCursor)
+            event.accept()
+            return
+
+        elif self._space_panning and event.button() == Qt.MouseButton.LeftButton:
+            # 空格 + 左键拖拽 - 平移（轨迹板 / 无中键设备的可靠平移方式）
+            self._is_panning = True
+            self._pan_start_pos = event.pos()
+            self.setCursor(Qt.CursorShape.ClosedHandCursor)
+            event.accept()
+            return
+
+        elif event.button() == Qt.MouseButton.LeftButton:
+            # 获取点击位置的图元
+            items = self._scene.items(scene_pos)
+            mods = event.modifiers()
+
+            # Alt+左键 = 平移画布（Alt 在本组件全局无冲突）
+            if mods & Qt.KeyboardModifier.AltModifier:
+                self._is_panning = True
+                self._pan_start_pos = event.pos()
+                self.setCursor(Qt.CursorShape.ClosedHandCursor)
+                event.accept()
+                return
+
+            # 检查是否点击了箭头
+            arrow_clicked = False
+            for item in items:
+                if isinstance(item, ArrowItem):
+                    arrow_clicked = True
+                    break
+            
+            if not arrow_clicked:
+                # port 优先(port z=90 高于 node z=50): 仅当光标落在某 port 的 dot
+                # 实际几何(shape() 故意放大到 12px 以便 hover, 会误吞节点外环点击)
+                # 上时, 才发起 port 连线拖拽; 否则继续判定 node 边缘/内部/框选。
+                port_on_dot = None
+                for item in items:
+                    if isinstance(item, QNodePort) and item.isPointOnDot(scene_pos):
+                        port_on_dot = item
+                        break
+                if port_on_dot is not None:
+                    # 命中 port dot 本身: 转发按下事件给场景 -> 派发给该 QNodePort
+                    # -> QNodePort.mousePressEvent -> _onPortConnectionDragStart
+                    super().mousePressEvent(event)
+                    return
+
+                # 检查是否点击了节点（用于创建连接）
+                node_clicked = None
+                for item in items:
+                    if isinstance(item, QNodeItem):
+                        node_clicked = item
+                        break
+                
+                if node_clicked:
+                    # 检查是否点击在节点边缘（用于创建连接）
+                    if self._is_on_node_edge(node_clicked, scene_pos):
+                        # 从边缘拖拽 - 创建连接
+                        self._is_creating_connection = True
+                        self._source_node_for_connection = node_clicked
+                        self._drag_start_pos = scene_pos
+
+                        # 创建临时连接线
+                        self._temp_connection = QGraphicsPathItem()
+                        pen = QPen(QColor("#666666"), 2, Qt.PenStyle.DashLine)
+                        self._temp_connection.setPen(pen)
+                        self._temp_connection.setZValue(5)
+                        self._scene.addItem(self._temp_connection)
+
+                        event.accept()
+                        return
+                    else:
+                        # 从内部拖拽 - 移动节点
+                        # 记录拖拽起始位置用于移动追踪
+                        self._drag_start_positions[id(node_clicked)] = node_clicked.pos()
+                        # 调用父类处理拖拽
+                        super().mousePressEvent(event)
+                        return
+                else:
+                    # 命中检测未返回节点: 光标可能落在节点 shape() 之外、但仍处
+                    # 于"外环"边缘区域(椭圆/矩形外 0~5% 容差, _is_on_node_edge 判定)。
+                    # 遍历所有节点做边缘判定, 命中则发起 node→? 连线, 而非框选。
+                    edge_node = None
+                    for node in self._nodes:
+                        if self._is_on_node_edge(node, scene_pos):
+                            edge_node = node
+                            break
+
+                    if edge_node is not None:
+                        # 从外环拖拽 - 创建连接
+                        self._is_creating_connection = True
+                        self._source_node_for_connection = edge_node
+                        self._drag_start_pos = scene_pos
+
+                        # 创建临时连接线
+                        self._temp_connection = QGraphicsPathItem()
+                        pen = QPen(QColor("#666666"), 2, Qt.PenStyle.DashLine)
+                        self._temp_connection.setPen(pen)
+                        self._temp_connection.setZValue(5)
+                        self._scene.addItem(self._temp_connection)
+
+                        event.accept()
+                        return
+
+                    # 没有点击节点，开始框选
+                    self._is_selecting = True
+                    self._selection_start_pos = scene_pos
+                    
+                    # 创建框选矩形
+                    self._selection_rect = SelectionRect()
+                    self._selection_rect.setRect(QRectF(scene_pos, scene_pos))
+                    self._scene.addItem(self._selection_rect)
+                    
+                    # 如果没有按住Ctrl，清除当前选中
+                    if not (event.modifiers() & Qt.KeyboardModifier.ControlModifier):
+                        for node in self._nodes:
+                            node.setSelected(False)
+                    
+                    event.accept()
+                    return
+        
+        super().mousePressEvent(event)
+    
+    def mouseMoveEvent(self, event: QMouseEvent) -> None:
+        """鼠标移动事件"""
+        scene_pos = self.mapToScene(event.pos())
+
+        # 悬停光标：Alt 按住时，光标在节点上显示「调整大小」光标，空白处显示抓手
+        self._updateHoverCursor(event)
+
+        if self._is_panning and self._pan_start_pos is not None:
+            # 平移画布（注意：QPoint(0,0) 在 Python 中为假，必须用 is not None 判断，
+            # 否则在视口左上角附近按下中键时 _pan_start_pos 为 QPoint(0,0) 会被误判为空）
+            delta = event.pos() - self._pan_start_pos
+            self.horizontalScrollBar().setValue(
+                self.horizontalScrollBar().value() - delta.x()
+            )
+            self.verticalScrollBar().setValue(
+                self.verticalScrollBar().value() - delta.y()
+            )
+            self._pan_start_pos = event.pos()
+            event.accept()
+            return
+
+        elif self._is_creating_port_connection and self._temp_port_connection:
+            # port 连线拖拽: 虚线从起点 port 中心跟随光标
+            if self._source_port_for_connection is not None:
+                source_pos = self._source_port_for_connection.scenePos()
+                self._temp_port_connection.setPath(_build_temp_bezier(source_pos, scene_pos))
+            # 手动追踪光标下的目标 port/node(场景 hover 派发已被压制)。
+            # 不排除起点 port 及其所属节点: 允许 port→port / port→node 自指
+            # (鼠标离开起点后再次回到起点 port/节点时, 能作为落点创建自指)。
+            # 是否允许由 addConnection 的 selfrefs 规则把关。
+            new_target = None
+            new_target_node = None
+            source_node = (self._source_port_for_connection._node
+                           if self._source_port_for_connection is not None else None)
+            for item in self._scene.items(scene_pos):
+                if isinstance(item, QNodePort):
+                    new_target = item
+                    break
+                if isinstance(item, QNodeItem):
+                    new_target_node = item
+                    break
+            self._updateHoveredTargetPort(new_target)
+            # 未命中 port 时, 让被捕获的目标节点也描边(port 优先, 两者不同时高亮)
+            if new_target is not None:
+                self._updateHoveredTargetNode(None)
+            else:
+                self._updateHoveredTargetNode(new_target_node)
+            event.accept()
+            return
+
+        elif self._is_creating_connection and self._temp_connection:
+            # 更新临时连接线(从源节点中心出发)
+            if self._source_node_for_connection:
+                source_pos = self._source_node_for_connection.sceneBoundingRect().center()
+                self._temp_connection.setPath(_build_temp_bezier(source_pos, scene_pos))
+            # 手动追踪光标下的目标(edge 连线拖拽场景 hover 同样被压制)。
+            # 与 port→? 拖拽对称: 优先命中 port dot 本身(isPointOnDot, 避免 12px
+            # 放大命中区误吞节点外环), 命中 port 则只高亮 port; 否则再判 NodeItem,
+            # 允许落在源节点自身(node→node 自环); 最后兜底外环容差区域。
+            new_target_port = None
+            new_target_node = None
+            for item in self._scene.items(scene_pos):
+                if isinstance(item, QNodePort) and item.isPointOnDot(scene_pos):
+                    new_target_port = item
+                    break
+                if isinstance(item, QNodeItem):
+                    new_target_node = item
+                    break
+            if new_target_node is None:
+                for node in self._nodes:
+                    if self._is_on_node_edge(node, scene_pos):
+                        new_target_node = node
+                        break
+            # port 与 node 高亮互斥: 命中 port 时取消节点高亮
+            if new_target_port is not None:
+                self._updateHoveredTargetNode(None)
+            else:
+                self._updateHoveredTargetPort(None)
+                self._updateHoveredTargetNode(new_target_node)
+            self._updateHoveredTargetPort(new_target_port)
+            event.accept()
+            return
+        
+        elif self._is_selecting and self._selection_rect:
+            # 更新框选矩形
+            rect = QRectF(self._selection_start_pos, scene_pos).normalized()
+            self._selection_rect.setRect(rect)
+            
+            # 选中矩形内的节点
+            for node in self._nodes:
+                node_rect = node.sceneBoundingRect()
+                if rect.intersects(node_rect):
+                    node.setSelected(True)
+                else:
+                    # 如果没有按住Ctrl，取消选中矩形外的节点
+                    if not (event.modifiers() & Qt.KeyboardModifier.ControlModifier):
+                        node.setSelected(False)
+            
+            event.accept()
+            return
+        
+        super().mouseMoveEvent(event)
+    
+    def mouseReleaseEvent(self, event: QMouseEvent) -> None:
+        """鼠标释放事件"""
+        scene_pos = self.mapToScene(event.pos())
+
+        # 结束平移：中键释放，或 (空格/Alt+) 左键释放
+        if event.button() == Qt.MouseButton.MiddleButton or (
+            self._is_panning and event.button() == Qt.MouseButton.LeftButton
+        ):
+            self._is_panning = False
+            self._pan_start_pos = None
+            # 释放后按当前修饰键重新计算光标（Alt 仍在按则按节点位置显示）
+            self._updateHoverCursor(event)
+            event.accept()
+            return
+
+        elif event.button() == Qt.MouseButton.LeftButton:
+            if self._is_creating_port_connection:
+                # 完成 port 连线拖拽
+                if self._temp_port_connection:
+                    self._scene.removeItem(self._temp_port_connection)
+                    self._temp_port_connection = None
+
+                src_port = self._source_port_for_connection
+                # 命中检测: 光标是否落在 port 上(优先用拖拽中追踪到的目标)。
+                # 不排除起点 port: 允许 port→port 同 port 自指(离开起点再回来)。
+                # 用 isPointOnDot 精确命中(与 node 边缘拖拽一致, 避免 12px 放大区误吞)。
+                target_port = self._hovered_target_port
+                if target_port is None and src_port is not None:
+                    for item in self._scene.items(scene_pos):
+                        if isinstance(item, QNodePort) and item.isPointOnDot(scene_pos):
+                            target_port = item
+                            break
+
+                if target_port is not None and src_port is not None:
+                    # 创建 port→port 连线(端点锚定到两 port 中心; 同 port 时自指)
+                    self.addConnection(
+                        src_port._node, target_port._node,
+                        source_port=src_port, target_port=target_port,
+                    )
+                elif src_port is not None:
+                    # 未命中 port: 检查是否落在某个节点(含外环) -> 创建 port→node 连线。
+                    # 不排除起点 port 所属节点: 允许 port→node 同节点自指。
+                    target_node = None
+                    for item in self._scene.items(scene_pos):
+                        if isinstance(item, QNodeItem):
+                            target_node = item
+                            break
+                    # 外环容差: 光标落在节点 shape() 外的边缘区域
+                    if target_node is None:
+                        for node in self._nodes:
+                            if self._is_on_node_edge(node, scene_pos):
+                                target_node = node
+                                break
+                    if target_node is not None:
+                        self.addConnection(
+                            src_port._node, target_node,
+                            source_port=src_port, target_port=None,
+                        )
+
+                # 清理: 无论成功失败都清除起点 port 的 active 描边态
+                if src_port is not None:
+                    src_port.setActive(False)
+                # 清除目标 port 的落点高亮态
+                self._updateHoveredTargetPort(None)
+                # 清除目标节点的落点描边态
+                self._updateHoveredTargetNode(None)
+                self._is_creating_port_connection = False
+                self._source_port_for_connection = None
+                self._drag_start_pos = None
+                event.accept()
+                return
+
+            elif self._is_creating_connection:
+                # 完成连接创建
+                if self._temp_connection:
+                    self._scene.removeItem(self._temp_connection)
+                    self._temp_connection = None
+
+                src_node = self._source_node_for_connection
+                items = self._scene.items(scene_pos)
+
+                # 优先命中 port dot 本身(isPointOnDot, 避免 12px 放大命中区误吞):
+                # 命中则创建 node→port 连接(source_port=None, target_port=port),
+                # 与 port→? 拖拽对称。
+                target_port = self._hovered_target_port
+                if target_port is None and src_node is not None:
+                    for item in items:
+                        if isinstance(item, QNodePort) and item.isPointOnDot(scene_pos):
+                            target_port = item
+                            break
+
+                if target_port is not None and src_node is not None:
+                    self.addConnection(
+                        src_node, target_port._node,
+                        source_port=None, target_port=target_port,
+                    )
+                else:
+                    # 未命中 port: 查找目标节点(允许落在源节点自身 -> node→node 自环)
+                    target_node = None
+                    for item in items:
+                        if isinstance(item, QNodeItem):
+                            target_node = item
+                            break
+                    # 外环容差: 光标可能落在节点 shape() 之外的边缘区域
+                    # (_is_on_node_edge 判定), 此时 scene.items 不返回节点, 需遍历补判
+                    if target_node is None:
+                        for node in self._nodes:
+                            if self._is_on_node_edge(node, scene_pos):
+                                target_node = node
+                                break
+
+                    if target_node is not None and src_node is not None:
+                        # 创建连接(同节点时 addConnection 允许并绘制为自环)
+                        self.addConnection(src_node, target_node)
+
+                # 清除拖拽期间的落点高亮态(port 与 node)
+                self._updateHoveredTargetPort(None)
+                self._updateHoveredTargetNode(None)
+                self._is_creating_connection = False
+                self._source_node_for_connection = None
+                self._drag_start_pos = None
+                event.accept()
+                return
+            
+            elif self._is_selecting:
+                # 完成框选
+                if self._selection_rect:
+                    self._scene.removeItem(self._selection_rect)
+                    self._selection_rect = None
+                
+                self._is_selecting = False
+                self._selection_start_pos = None
+                event.accept()
+                return
+        
+        super().mouseReleaseEvent(event)
+
+    def _updateHoverCursor(self, event: QMouseEvent) -> None:
+        """根据当前修饰键与光标位置刷新画布光标。
+
+        - 平移进行中：不动（保持 ClosedHandCursor）
+        - Alt 按住 + 光标在节点内：SizeAllCursor（调整大小样式）
+        - Alt 按住 + 空白处：OpenHandCursor（提示可平移）
+        - 空格平移模式：OpenHandCursor
+        - 其它：ArrowCursor
+        """
+        if self._is_panning:
+            return  # 平移中保持抓手闭合光标
+        if event.modifiers() & Qt.KeyboardModifier.AltModifier:
+            scene_pos = self.mapToScene(event.pos())
+            on_node = any(isinstance(it, QNodeItem) for it in self._scene.items(scene_pos))
+            self.setCursor(
+                Qt.CursorShape.SizeAllCursor if on_node
+                else Qt.CursorShape.OpenHandCursor
+            )
+        elif self._space_panning:
+            self.setCursor(Qt.CursorShape.OpenHandCursor)
+        else:
+            self.setCursor(Qt.CursorShape.ArrowCursor)
+
+    def mouseDoubleClickEvent(self, event: QMouseEvent) -> None:
+        """鼠标双击事件"""
+        scene_pos = self.mapToScene(event.pos())
+        items = self._scene.items(scene_pos)
+        
+        # 查找双击的节点
+        for item in items:
+            if isinstance(item, QNodeItem):
+                # 如果节点有自定义编辑器，打开它
+                if item.editorClass:
+                    editor = item.editorClass(item)
+                    editor.setWindowTitle(editor.getTitle())
+                    editor.show()
+                else:
+                    # 默认行为：发射编辑请求信号
+                    item.editRequested.emit(item)
+                event.accept()
+                return
+        
+        super().mouseDoubleClickEvent(event)
+    
+    def wheelEvent(self, event: QWheelEvent) -> None:
+        """鼠标滚轮事件 - 缩放"""
+        # 获取当前缩放因子
+        current_transform = self.transform()
+        current_scale = current_transform.m11()
+        
+        # 计算新的缩放因子
+        delta = event.angleDelta().y()
+        scale_factor = 1.1 if delta > 0 else 0.9
+        new_scale = current_scale * scale_factor
+        
+        # 限制缩放范围
+        if 0.1 <= new_scale <= 5.0:
+            self.scale(scale_factor, scale_factor)
+        
+        event.accept()
+    
+    def contextMenuEvent(self, event: QContextMenuEvent) -> None:
+        """右键菜单事件 - 根据点击位置委托给对应的弹出菜单
+
+        - 命中节点 -> node.menu(QNodePopMenu)
+        - 命中连线/箭头 -> lmenu(QLinePopMenu, 每次按两端点重构)
+        - 空白画布 -> menu(QCanvasPopMenu)
+        """
+        scene_pos = self.mapToScene(event.pos())
+        item = self._scene.itemAt(scene_pos, QTransform())
+
+        # 向上查找顶层图元
+        top_item = item
+        while top_item and top_item.parentItem():
+            top_item = top_item.parentItem()
+
+        # 检查是否是连接线的子项（箭头）
+        connection_parent = None
+        check_item = item
+        while check_item:
+            if isinstance(check_item, ConnectionItem):
+                connection_parent = check_item
+                break
+            check_item = check_item.parentItem()
+
+        if isinstance(top_item, QNodeItem):
+            # 在节点上右键
+            top_item.menu.exec(event.globalPos(), self)
+        elif isinstance(top_item, (ArrowItem, ConnectionItem)) or connection_parent:
+            # 在连线/箭头上右键(连线菜单每次按两端点重构)
+            if isinstance(top_item, ArrowItem):
+                conn = top_item.connection
+            elif isinstance(top_item, ConnectionItem):
+                conn = top_item
+            else:
+                conn = connection_parent
+            self.lmenu = QLinePopMenu(
+                self,
+                conn.sourcePort or conn.sourceNode,
+                conn.targetPort or conn.targetNode,
+            )
+            self.lmenu.exec(event.globalPos())
+        else:
+            # 在空白画布上右键
+            self.menu.exec(event.globalPos(), scene_pos)
+
+    def _onAddNodeAt(self, pos: QPointF) -> None:
+        """在指定位置添加节点"""
+        node_count = len(self._nodes)
+        name = f"Node{node_count + 1}"
+        self.addNode(name, pos)
+    
+    def _onLayout(self, strategy: str) -> None:
+        """执行自动布局"""
+        engine = DenseLayoutEngine(self)
+        engine.autoLayout(strategy)
+    
+    def _onFitViewport(self) -> None:
+        """自动适应视口"""
+        fitter = ViewportFitter(self)
+        fitter.fitViewport()
+
+    def _is_on_node_edge(self, node: QNodeItem, pos: QPointF) -> bool:
+        """检查位置是否在节点"外环"边缘区域内(用于发起/接收连线)。
+
+        外环 = 节点可悬停命中区(shape(), 含描边半宽 + 外环厚度)内、且处于
+        内部 75% 区域之外的部分。统一用 node.shape().contains() 做外边界
+        判定(与 hover/hit 完全一致, 避免容差不一致), 内边界按各形状的 75%
+        缩放几何判定。
+        """
+        local_pos = node.mapFromScene(pos)
+        # 外边界: 必须落在节点 shape() 内(即 hover/hit 能覆盖的区域)
+        if not node.shape().contains(local_pos):
+            return False
+
+        center = node.rect().center()
+        shape = node.nodeShape
+        rect = node.rect()
+        # 内部 75% 区域(反向缩放: 以中心为锚, 各向 75%)
+        inner_ratio = 0.75
+
+        if shape == NodeShape.ELLIPSE:
+            radius = node.radius
+            distance = math.sqrt(
+                (local_pos.x() - center.x()) ** 2 +
+                (local_pos.y() - center.y()) ** 2
+            )
+            # 边缘区域: 内圈 75% 半径之外(外圈已由 shape().contains 保证)
+            return distance >= radius * inner_ratio
+
+        elif shape == NodeShape.RECTANGLE:
+            half_w = rect.width() / 2
+            half_h = rect.height() / 2
+            dx = local_pos.x() - center.x()
+            dy = local_pos.y() - center.y()
+            adx = abs(dx)
+            ady = abs(dy)
+            # 内矩形(75%): 在其内则视为"内部", 不是边缘
+            inner_w = half_w * inner_ratio
+            inner_h = half_h * inner_ratio
+            if adx <= inner_w and ady <= inner_h:
+                return False
+            return True
+
+        elif shape == NodeShape.DIAMOND:
+            radius = node.radius
+            dx = abs(local_pos.x() - center.x())
+            dy = abs(local_pos.y() - center.y())
+            # 菱形边界 |dx|+|dy| <= radius(外圈已由 shape 保证);
+            # 内菱形(75%): |dx|+|dy| <= radius*0.75 -> 在其内视为内部
+            return (dx + dy) > radius * inner_ratio
+
+        return False
+
+    def keyPressEvent(self, event: QKeyEvent) -> None:
+        """键盘按下事件"""
+        if event.key() == Qt.Key.Key_Space and not event.isAutoRepeat():
+            # 按住 Space 进入平移模式（左键拖拽平移）；此时不应自动重复触发
+            if not self._space_panning:
+                self._space_panning = True
+                self.setCursor(Qt.CursorShape.OpenHandCursor)
+            event.accept()
+            return
+
+        if event.key() == Qt.Key.Key_Delete:
+            # 删除选中的节点和连接
+            self._deleteSelected()
+            event.accept()
+            return
+
+        super().keyPressEvent(event)
+
+    def keyReleaseEvent(self, event: QKeyEvent) -> None:
+        """键盘释放事件"""
+        if event.key() == Qt.Key.Key_Space and not event.isAutoRepeat():
+            self._space_panning = False
+            if not self._is_panning:
+                self.setCursor(Qt.CursorShape.ArrowCursor)
+            event.accept()
+            return
+        super().keyReleaseEvent(event)
+    
+    def _deleteSelected(self) -> None:
+        """删除选中的节点和连接"""
+        # 删除选中的节点
+        nodes_to_remove = [node for node in self._nodes if node.isSelected()]
+        for node in nodes_to_remove:
+            self.removeNode(node)
+        
+        # 删除选中的连接（通过箭头）
+        connections_to_remove = []
+        for conn in self._connections:
+            if conn.targetArrow.isSelected():
+                connections_to_remove.append(conn)
+            elif conn.sourceArrow and conn.sourceArrow.isSelected():
+                connections_to_remove.append(conn)
+        
+        for conn in connections_to_remove:
+            self.removeConnection(conn)
+    
+    def export(self, filter_empty: bool = False) -> dict:
+        """
+        导出画布数据为字典
+
+        Args:
+            filter_empty: 是否过滤空内容
+
+        Returns:
+            包含画布数据的字典
+        """
+        data = {
+            "nodes": [],
+            "connections": [],
+            "start_node_id": None
+        }
+
+        # 导出节点
+        for node in self._nodes:
+            node_data = node.toDict()
+            data["nodes"].append(node_data)
+
+        # 导出连接
+        for conn in self._connections:
+            conn_data = {
+                "source_id": conn.sourceNode.id,
+                "target_id": conn.targetNode.id,
+                "is_bidirectional": conn.isBidirectional,
+                "connection_type": conn.connectionType.name
+            }
+            # port 绑定(若任一端锚定到 port): 记录 side + name, 供导入时按
+            # name 在该侧找回 QNodePort。空 name 的端口无法引用, 不记录。
+            sp = conn.sourcePort
+            if sp is not None and sp.spec.name:
+                conn_data["source_port_side"] = sp.side
+                conn_data["source_port_name"] = sp.spec.name
+            tp = conn.targetPort
+            if tp is not None and tp.spec.name:
+                conn_data["target_port_side"] = tp.side
+                conn_data["target_port_name"] = tp.spec.name
+            # 连线样式(颜色/线宽): 仅在被自定义过时序列化, 避免污染默认导出。
+            # 此前连线 style 完全不持久化, 导出再导入后定制颜色/粗细退回默认。
+            style_data = conn.styleToDict()
+            if style_data:
+                conn_data["style"] = style_data
+            data["connections"].append(conn_data)
+
+        # 导出起点节点
+        if self._start_node:
+            data["start_node_id"] = self._start_node.id
+
+        # 导出跨节点可连接性规则(仅当与默认值不同时序列化, 避免污染默认导出)。
+        # 与节点 selfrefs 的序列化策略一致。
+        linkables_diff = {
+            k: v for k, v in self._linkables.items()
+            if v != _LINKABLES_DEFAULTS.get(k)
+        }
+        if linkables_diff:
+            data["linkables"] = linkables_diff
+
+        return data
+
+    def exportToJson(self, filter_empty: bool = False) -> str:
+        """
+        导出画布数据为 JSON 字符串
+
+        Args:
+            filter_empty: 是否过滤空内容
+
+        Returns:
+            JSON 字符串
+        """
+        return json.dumps(self.export(filter_empty), indent=2, ensure_ascii=False)
+
+    def _importDict(self, data: dict):
+        """
+        从字典数据构造画布节点和连接。
+        将 code、targets、decorates 直接存入 node.data。
+
+        参数:
+            data (dict): 包含 'node_id': {code, targets, decorates} 的结构化数据
+        """
+        # 清除现有内容
+        self.clear()
+
+        node_map = {}  # 用于存储已创建的节点 ID 到 NodeItem 的映射
+
+        # 第一步：创建所有节点并存储自定义数据
+        for node_id, node_info in data.items():
+            # 提取数据字段
+            code_val = node_info.get('code', '')
+            targets_val = node_info.get('targets', [])
+            decorates_val = node_info.get('decorates', [])
+
+            # 生成默认位置（避免重叠，实际可结合布局算法）
+            x = random.randint(50, 800)
+            y = random.randint(50, 600)
+
+            # 创建节点，名称使用 node_id
+            new_node = self.addNode(node_id, QPointF(x, y))
+            node_map[node_id] = new_node
+
+            # 将原始数据结构存入 node.data
+            new_node.data['code'] = code_val
+            new_node.data['targets'] = targets_val
+            new_node.data['decorates'] = decorates_val
+
+        # 第二步：根据 targets 创建连接
+        for node_id, node_info in data.items():
+            source_node = node_map.get(node_id)
+            if not source_node:
+                continue
+
+            targets_list = node_info.get('targets', [])
+            for target_id in targets_list:
+                target_node = node_map.get(target_id)
+                if target_node:
+                    # 添加单向连接
+                    self.addConnection(source_node, target_node, is_bidirectional=False)
+
+        # 第三步：处理特殊装饰器逻辑（如 'listen'）
+        # 此处仅做标记或初始化相关逻辑，具体实现取决于外部事件系统
+        for node_id, node_info in data.items():
+            decorates_list = node_info.get('decorates', [])
+            if 'listen' in decorates_list:
+                node_item = node_map.get(node_id)
+                if node_item:
+                    # 标记该节点为监听器，方便后续逻辑判断
+                    node_item.data['is_listener'] = True
+                    # 可根据需要在此处绑定信号槽或初始化监听状态
+
+        # 可选：应用紧凑布局使节点整齐排列。
+        # DenseLayoutEngine 已在模块顶部 import, 此前用 except ImportError 兜底
+        # 是失效的(永远捕获不到); autoLayout 抛出的真实异常会冒泡到 importData
+        # 的 except Exception, 被误报为"数据既非 json 也非 dict"。这里改为捕获
+        # 所有异常, 布局失败仅告警、不影响已导入的节点与连接。
+        try:
+            engine = DenseLayoutEngine(self)
+            engine.autoLayout("compact")
+        except Exception as e:
+            print(f"[chartflow] 紧凑布局失败, 节点保留随机位置: {e}")
+
+    def importData(self, data: dict | str) -> None:
+        """
+        从数据导入画布
+
+        Args:
+            data: 字典或 JSON 字符串
+        """
+        # 如果传入的是字符串，解析为字典
+        if isinstance(data, str):
+            try:
+                data = json.loads(data)
+            except json.JSONDecodeError as e:
+                QMessageBox.critical(self, "Error", f"Invalid JSON: {e}")
+                return
+
+        if data.get("nodes") is None:
+            # 非 nodes/connections 结构, 尝试按 {node_id: {code,targets,decorates}}
+            # 的扁平 dict 导入(由 _importDict 处理)。
+            try:
+                self._importDict(data)
+            except Exception as e:
+                print(
+                    f"[chartflow] 导入失败: 数据既非 nodes/connections 结构, "
+                    f"也无法按扁平 dict 解析。Details: {e}"
+                )
+            return
+        # 清除现有内容
+        self.clear()
+        
+        # 创建节点映射（旧id -> 新节点）
+        node_map = {}
+
+        # 导入节点
+        for node_data in data.get("nodes", []):
+            name = node_data.get("name", "Unnamed")
+            pos_data = node_data.get("position", {"x": 0, "y": 0})
+            position = QPointF(pos_data.get("x", 0), pos_data.get("y", 0))
+            shape_name = node_data.get("shape", "ELLIPSE")
+            try:
+                shape = NodeShape[shape_name]
+            except KeyError:
+                shape = NodeShape.ELLIPSE
+            
+            node = self.addNode(name, position, shape)
+
+            # 用 fromDict 统一恢复节点全部状态: name / shape / position / data /
+            # ports / style / custom 标记 / 外环可见性 / 连线能力。
+            # 此前 importData 逐字段手动复制, 遗漏了 ports 与 style, 导致导出后
+            # 节点的端口丢失、port↔port 连接无法还原。
+            node.fromDict(node_data)
+
+            old_id = node_data.get("id")
+            if old_id is not None:
+                node_map[old_id] = node
+        
+        # 导入连接
+        for conn_data in data.get("connections", []):
+            source_id = conn_data.get("source_id")
+            target_id = conn_data.get("target_id")
+            is_bidirectional = conn_data.get("is_bidirectional", False)
+            connection_type_name = conn_data.get("connection_type", "BEZIER")
+            try:
+                connection_type = ConnectionType[connection_type_name]
+            except KeyError:
+                connection_type = ConnectionType.BEZIER
+
+            if source_id in node_map and target_id in node_map:
+                source_node = node_map[source_id]
+                target_node = node_map[target_id]
+                # 端点之一不可连线时, addConnection 会静默返回 None, 该连接被丢弃。
+                # 此处显式告警, 便于定位外部/手工编辑产生的无法还原的连线。
+                if not source_node.isConnectable() or not target_node.isConnectable():
+                    print(
+                        f"[chartflow] 警告: 导入连接 {source_id!r} -> {target_id!r} "
+                        f"被跳过 —— 端点节点 connectable=False (无法参与连线)。"
+                    )
+                # 按导出时记录的 side + name 找回 port(找不到则退化为 node 边缘)
+                source_port = _resolve_port(
+                    source_node,
+                    conn_data.get("source_port_side"),
+                    conn_data.get("source_port_name"),
+                )
+                target_port = _resolve_port(
+                    target_node,
+                    conn_data.get("target_port_side"),
+                    conn_data.get("target_port_name"),
+                )
+                conn = self.addConnection(
+                    source_node, target_node, is_bidirectional, connection_type,
+                    source_port=source_port, target_port=target_port,
+                )
+                # 还原连线样式(颜色/线宽); addConnection 可能因判重返回已存在
+                # 的连线(也会返回 None, 此时跳过)。
+                if conn is not None and conn_data.get("style"):
+                    conn.applyStyleFromDict(conn_data["style"])
+        
+        # 设置起点节点
+        start_node_id = data.get("start_node_id")
+        if start_node_id in node_map:
+            self.startNode = node_map[start_node_id]
+
+        # 恢复跨节点可连接性规则(以默认值打底, 叠加导入的差异项, 保证 7 键齐全)
+        if isinstance(data.get("linkables"), dict):
+            self._applyLinkables(
+                {**_LINKABLES_DEFAULTS, **data["linkables"]}, merge=False
+            )
+            # 导入的连接可能违反新规则(例如旧文件允许某组合而当前规则禁止),
+            # 交由 enforceLinkables 清理; 违规者被移除并告警。
+            removed = self.enforceLinkables()
+            for c in removed:
+                print(
+                    f"[chartflow] 警告: 导入连接 {c.sourceNode.name!r} -> "
+                    f"{c.targetNode.name!r} 因 linkables 规则被移除。"
+                )
+
+        self.changed = False
+    
+    def clear(self) -> None:
+        """清空画布"""
+        # 移除所有连接
+        for conn in self._connections[:]:
+            self.removeConnection(conn)
+
+        # 移除所有节点
+        for node in self._nodes[:]:
+            self._scene.removeItem(node)
+        self._nodes.clear()
+
+        self._start_node = None
+        self.changed = False
+
+    def resizeEvent(self, event) -> None:
+        """窗口大小改变事件 - 更新样式面板位置"""
+        super().resizeEvent(event)
+        # 更新样式面板位置（贴合底部，margin 10）
+        if hasattr(self, '_style_panel'):
+            panel_height = StylePanel.PANEL_HEIGHT
+            panel_y = self.height() - panel_height - 10
+            self._style_panel.setGeometry(10, panel_y, self.width() - 20, panel_height)