# flow.yaml 节点布局建议

本文档说明如何在 flow.yaml 中通过 `ui.nodePositions` 排布节点，使流程图**易读、不挤成一条线**。供编辑或生成 flow 时参考。

---

## 1. 布局定义位置

在 flow.yaml 末尾通过 `ui.nodePositions` 为每个节点指定坐标：

```yaml
ui:
  nodePositions:
    start:
      x: -300
      'y': 190
    agent_plan:
      x: 0
      'y': 200
    # ... 每个 instanceId 对应一个 { x, y }
  description: 可选，整图简短说明
```

- 坐标单位为像素（或画布单位），从左到右 x 增大，从上到下 y 增大。
- 未出现在 `nodePositions` 中的节点由渲染端自行排布，可能挤在一起或成一条线。

---

## 2. 避免「一条线」

**不推荐**：所有节点共线（同一 y 或同一 x），例如：

- 全部同一 y、只改 x → 一条横线，分支和汇合难以区分。
- 全部同一 x、只改 y → 一条竖线，顺序感弱、边易重叠。

**推荐**：利用**二维平面**，让主流程、分支、环在 x 与 y 上都有区分。

---

## 3. 布局原则

### 3.1 主流程沿 x 递进

- **主链路**（如 Start → A → B → … → End）的节点 **x 递增**，便于从左到右阅读。
- 同一条主链上的节点 **y 接近**（可设为基础 y，如 200），不要上下跳动过大。

### 3.2 分支用 y 错开

- **并行分支**：不同分支用不同 y（例如上支 y 小、下支 y 大），避免多条边叠在同一水平线。
- **If 的 next1 / next2**：true/false 两支可一上一下（如 next1 略上、next2 略下），再在后方汇合。

### 3.3 环与回流

- **入环/复入环**（如 AnyOne）：可放在主链左侧或与主链同 x，其 next 指向的「检查」节点 x 更大。
- **回流边**（修复 → 再检查）：从右回到左时，**回流节点 y 与主链明显不同**（例如主链 y≈200，修复链 y≈450），这样环在图上呈「下层回流」而不是与主链重叠成一条线。

### 3.4 辅助节点集中一侧

- **provide_***、**SaveKey/LoadKey** 等不参与主链的节点，可放在**左侧或下方**固定区域（例如 x 较小、y 按 300/400 排布），与主链在视觉上分离。

### 3.5 间距

- 同层节点之间 **x 差** 建议不少于约 150～250，避免节点重叠、边难以辨认。
- 上下层之间 **y 差** 建议不少于约 80～120，分支与主链区分清晰。

---

## 4. 简要对照

| 目标           | 做法                         | 避免                     |
|----------------|------------------------------|--------------------------|
| 主流程清晰     | 主链节点 x 递增、y 接近      | 主链节点 y 乱跳          |
| 分支可辨       | 不同分支用不同 y            | 所有分支同一 y（一条线） |
| 环可见         | 回流节点 y 与主链错开       | 环与主链叠在同一行       |
| 辅助节点不抢戏 | 放左侧或下方、x 小或 y 大   | 与主链混在同一列         |

---

## 5. 参考示例

- 主链从左到右（入口 `workspace_run` 在最左，x 依次递增），provide/collect 等数据源偏左，分支路径在 y 上错开。
- **builtin/pipelines/module-migrate/flow.yaml**：主链沿 x 递增；provide/SaveKey 在左侧（x≈50～240）；静态环与编译环在 y 上分层（如 agent_fix_todo、control_if_fixed 等 y≈460～470，与主链 y≈100～280 分开），回流不压在主链一条线上。

生成或手改 `ui.nodePositions` 时，可先按「主链 x 递增 + 分支/环 y 错开」排一版，再微调间距与对齐。