连接规则
本文档介绍节点编辑器中节点连线（连接）的校验与行为规则。
连接前置条件
尝试连接两个连接器时，满足以下任一条件即直接拒绝：
| 条件 | 说明 |
|---|---|
| 同一连接器 | 连接器不能与自身连接 |
| 同一节点 | 同一节点内部的连接器不能互相连接 |
| 用途相同 | 两个连接器用途相同（同为输入或同为输出） |
| 连接器被禁用 | 任一连接器处于禁用状态（例如运行时只读连接器） |
方向规则
- 连线方向统一为「输出连接器 → 输入连接器」：即使从输入连接器开始拖拽到输出连接器，最终也会规范为从输出连接器指向输入连接器。
- 输入连接器同一时刻只能拥有一条连线；建立新连线前，会自动移除该输入连接器上已有的连线（替换式连接），替换操作可以整体撤销。
- 输出连接器可以同时连接多个输入连接器。
数据类型匹配规则
连线时实际校验的是连接器背后的数据类型。除「通用回退规则」外，以下组合按顺序检查，命中即允许；全部未命中时拒绝连接，并弹出「数据类型不匹配」错误提示。
匹配规则
| 输出连接器类型 | 输入连接器类型 | 结果 |
|---|---|---|
流程控制 | 流程控制 | ✔ 允许 |
流程控制 | 其他任意 | ✘ 拒绝 |
| 其他任意 | 流程控制 | ✘ 拒绝 |
整数 | 浮点数 | ✔ 允许 |
浮点数 | 整数 | ✔ 允许 |
二维整数向量 | 二维浮点数向量 | ✔ 允许 |
二维浮点数向量 | 二维整数向量 | ✔ 允许 |
四维整数向量 | 四维浮点数向量 | ✔ 允许 |
四维浮点数向量 | 四维整数向量 | ✔ 允许 |
整数、浮点数 | 二维整数向量、二维浮点数向量、四维整数向量、四维浮点数向量 | ✔ 允许（将标量填充到每个分量） |
布尔、整数、浮点数、字符串、JSON值、JSON数组、JSON对象、二维整数向量、二维浮点数向量、四维整数向量、四维浮点数向量 | JSON值 | ✔ 允许 |
JSON值 | JSON值、整数、浮点数、字符串、布尔、JSON数组、JSON对象、二维整数向量、二维浮点数向量、四维整数向量、四维浮点数向量 | ✔ 允许（运行时检查数据兼容性，不匹配将报错） |
图像、ONNX、文本识别引擎、视频流 | 同类型 | ✔ 允许（不同类型拒绝） |
| 其他组合 | 其他组合 | 见「通用回退规则」 |
标量转为向量
将 整数 或 浮点数 输出连接到二维/四维向量输入时，标量会填充到目标向量的每个分量。例如，将整数 5 连接到二维整数向量输入，会得到 (5, 5)；连接到四维浮点数向量输入，会得到 (5.0, 5.0, 5.0, 5.0)。
标量与目标向量分量之间的数值类型不同时，沿用整数与浮点数的互转规则。该规则仅允许标量输出连接向量输入，不允许向量输出连接标量输入。
向量与 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对象形式。
通用回退规则
未命中上述任何规则时，按连接器背后的数据类型判断：
- 输入连接器数据类型为
字符串→ 允许任意数据输出连接（流程控制除外）。 - 输出与输入数据类型相同 → 允许。
- 其余情况 → 拒绝。
典型效果：
- 任意输出 →
字符串输入：一律允许（流程控制除外）。 字符串输出 →整数、向量等输入：拒绝。布尔→布尔、整数→整数、字符串→字符串、JSON对象→JSON对象、图像→图像：数据类型相同，允许。
常见组合示例
| 组合 | 结果 | 依据 |
|---|---|---|
整数 → 浮点数 | ✔ | 整数 与 浮点数 可互连 |
整数 → JSON值 | ✔ | 整数 可连接 JSON值 输入 |
JSON值 → 整数 | ✔ | JSON值 可连接 整数 输入 |
二维整数向量 → 二维浮点数向量 | ✔ | 同维度向量可互连 |
整数 → 二维整数向量 | ✔ | 将标量填充到每个分量 |
浮点数 → 四维整数向量 | ✔ | 将标量填充到每个分量，并按数值转换规则转换分量 |
整数 → 字符串 | ✔ | 字符串 输入接受任意输出 |
字符串 → 整数 | ✘ | 字符串 与 整数 不互通 |
二维整数向量 → 整数 | ✘ | 不支持向量转为标量 |
图像 → 文本识别引擎 | ✘ | 类型不同 |
视频流 → 视频流 | ✔ | 类型相同 |
说明
以上规则为当前版本的行为，后续版本可能调整。