适用场景与边界

适合的场景

1. Agent 编排设计器

rust-agent-flow 的首要场景是 **Agent 工作流的可视化编排**。Demo 项目演示了一个典型 Agent 流程：

Start → Planner（规划）→ Condition（条件判断）
  ├─ if_0 → Search（检索）
  ├─ if_1 → Notify（通知）
  └─ else → ToolCall（工具调用）
三路汇合 → Loop（循环处理）→ Summarize（汇总）→ End

Loop 节点的 `loop_body` 支持循环体支线，`loop_in` 回环边实现迭代闭环——这正是 Agent 编排中「规划→执行→反馈→迭代」的核心范式。

2. 数据管道设计

将数据处理步骤可视化为节点，用边表示数据流向：

- `Variable` 节点定义中间变量 - `Adapter` 节点做格式转换 - `Condition` 节点做数据分流 - `Action` 节点执行具体处理

Demo 中的 `DataPipeline` 数据源展示了这一用法。

3. 自动化工作流配置

需要用户可视化配置执行顺序、条件分支与循环的场景，如：

- CI/CD 流水线编辑器 - RPA（机器人流程自动化）设计器 - 规则引擎编排界面

4. 嵌入式流程编辑能力

你的 GPUI 应用需要一个**可嵌入的画布组件**，而非独立应用。rust-agent-flow 以 `FlowEditorView` 为单位，可作为窗口主体或子视图嵌入。

框架提供的「设计时」能力

rust-agent-flow 专注**设计时**（design-time），即流程的**可视化创建与编辑**：

| 能力 | 说明 | |------|------| | 图编辑 | 增删节点、连线、拖拽、缩放 | | 自动布局 | dagre Sugiyama 分层排版 | | 属性编辑 | Schema 驱动的属性面板 | | 数据持久化 | FlowDocument JSON 序列化 | | 节点扩展 | 自定义节点类型与端口 | | 工具栏扩展 | 注入业务按钮 |

框架不提供的「运行时」能力

**流程的执行（runtime）由调用侧自行实现**。框架只产出 `FlowDocument`（JSON），如何「跑」这个流程是你的职责：

// 框架产出：可序列化的流程定义
let doc: FlowDocument = graph.to_document("my-flow");
let json = serde_json::to_string_pretty(&doc).unwrap();

// 运行时执行：由你实现
// 例如遍历 doc.nodes，按 kind 分发到执行器

这种**设计时与运行时分离**是刻意的架构决策：

- 设计器可在任意桌面应用复用 - 运行时可选择任意执行策略（同步/异步/分布式） - 流程定义可跨语言消费（JSON 协议）

不适合的场景

| 场景 | 原因 | 替代方案 | |------|------|----------| | Web 端流程编辑 | GPUI 不支持浏览器 | ReactFlow / @xyflow | | 静态流程图展示（无编辑） | 框架交互能力是负担 | 直接 SVG/Cairo 绘制 | | 非 GPUI 桌面应用 | 渲染层绑定 GPUI | egui_flow / tauri + Web | | 极简节点（1-2 种，无分支循环） | 框架抽象成本不划算 | 手写少量 GPUI div | | 实时数据流（带数据采样） | 这是运行时可视化，非设计时 | 时序图组件 |

适用规模参考

| 规模 | 适配度 | 说明 | |------|--------|------| | 节点数 < 50，节点类型 < 8 | ✅ 完美 | 框架设计目标区间 | | 节点数 50-200 | ✅ 良好 | dagre 布局仍流畅，注意缓存优化 | | 节点数 > 200 | ⚠️ 需优化 | 需视口裁剪（当前未内置虚拟化） | | 节点类型 > 8 | ✅ 支持 | 通过 `NodeRegistry::register` 注册自定义节点 |

小结

rust-agent-flow 适合**在 GPUI 桌面应用中嵌入可编辑的流程设计器**，尤其擅长 Agent 编排与数据管道这类需要分支/循环的图灵完备流程。它负责设计时的一切，运行时执行留给你——这是清晰的关注点分离。

下一节：[生态与 Crate 全景](ecosystem-overview.md)