连接规则

本文档介绍节点编辑器中节点连线（连接）的校验与行为规则。

连接前置条件

尝试连接两个连接器时，满足以下任一条件即直接拒绝：

条件	说明
同一连接器	连接器不能与自身连接
同一节点	同一节点内部的连接器不能互相连接
用途相同	两个连接器用途相同（同为输入或同为输出）
连接器被禁用	任一连接器处于禁用状态（例如运行时只读连接器）

方向规则

• 连线方向统一为「输出连接器 → 输入连接器」：即使从输入连接器开始拖拽到输出连接器，最终也会规范为从输出连接器指向输入连接器。
• 输入连接器同一时刻只能拥有一条连线；建立新连线前，会自动移除该输入连接器上已有的连线（替换式连接），替换操作可以整体撤销。
• 输出连接器可以同时连接多个输入连接器。

数据类型匹配规则

连线时实际校验的是连接器背后的数据类型。除「通用回退规则」外，以下组合按顺序检查，命中即允许；全部未命中时拒绝连接，并弹出「数据类型不匹配」错误提示。

匹配规则

输出连接器类型	输入连接器类型	结果
流程控制	流程控制	✔ 允许
流程控制	其他任意	✘ 拒绝
其他任意	流程控制	✘ 拒绝
整数	浮点数	✔ 允许
浮点数	整数	✔ 允许
二维整数向量	二维浮点数向量	✔ 允许
二维浮点数向量	二维整数向量	✔ 允许
四维整数向量	四维浮点数向量	✔ 允许
四维浮点数向量	四维整数向量	✔ 允许
布尔、整数、浮点数、字符串、JSON值、JSON数组、JSON对象、二维整数向量、二维浮点数向量、四维整数向量、四维浮点数向量	JSON值	✔ 允许
JSON值	JSON值、整数、浮点数、字符串、布尔、JSON数组、JSON对象、二维整数向量、二维浮点数向量、四维整数向量、四维浮点数向量	✔ 允许（运行时检查数据兼容性，不匹配将报错）
图像、ONNX、文本识别引擎、视频流	同类型	✔ 允许（不同类型拒绝）
其他组合	其他组合	见「通用回退规则」

向量与 JSON值 的互转

向量（二维/四维整数或浮点向量）并非 JSON 规范定义的类型——JSON 规范仅包含对象、数组、数字、字符串、布尔与空值。向量与 JSON值 互转时以 JSON对象 为中间形式：向量以 JSON对象 表示，而 JSON对象 属于 JSON 规范类型、可由 JSON值 承载，因此向量连接器可以与 JSON值 连接器互连：

• 向量以 JSON对象 形式接入 JSON值，例如二维向量表示为 {"x": 100, "y": 200}。
• 从 JSON值 读取、或从 JSON 文本解析 JSON值 时，形状满足以下条件的 JSON对象 会还原为对应类型的向量：
  • 仅含 x、y 两个字段且均为数字的对象 → 二维向量；两个值均为 整数 时还原为 二维整数向量，否则还原为 二维浮点数向量。
  • 仅含 x、y、z、w 四个字段且均为数字的对象 → 四维向量；四个值均为 整数 时还原为 四维整数向量，否则还原为 四维浮点数向量。
  • 其余形状的 JSON对象 仍按 JSON对象 读取。
• 向量序列化为 JSON 文本时同样表现为该 JSON对象 形式。

通用回退规则

未命中上述任何规则时，按连接器背后的数据类型判断：

1. 输入连接器数据类型为 字符串 → 允许任意数据输出连接（流程控制 除外）。
2. 输出与输入数据类型相同 → 允许。
3. 其余情况 → 拒绝。

典型效果：

• 任意输出 → 字符串 输入：一律允许（流程控制 除外）。
• 字符串 输出 → 整数、向量等输入：拒绝。
• 布尔 → 布尔、整数 → 整数、字符串 → 字符串、JSON对象 → JSON对象、图像 → 图像：数据类型相同，允许。

常见组合示例

组合	结果	依据
整数 → 浮点数	✔	整数 与 浮点数 可互连
整数 → JSON值	✔	整数 可连接 JSON值 输入
JSON值 → 整数	✔	JSON值 可连接 整数 输入
二维整数向量 → 二维浮点数向量	✔	同维度向量可互连
整数 → 字符串	✔	字符串 输入接受任意输出
字符串 → 整数	✘	字符串 与 整数 不互通
图像 → 文本识别引擎	✘	类型不同
视频流 → 视频流	✔	类型相同

说明

以上规则为当前版本的行为，后续版本可能调整。