前言

为什么写这本书

可视化流程编排正在成为 Agent 编排、数据管道、自动化工作流等领域的标配能力。然而在 Rust 桌面端，构建一个类 ReactFlow 的流程设计器仍然意味着从零拼装：图模型、布局算法、边路径几何、交互状态机、属性面板——每一层都需要架构决策。

`rust-agent-flow` 的诞生，源于一个朴素的目标：**让 Rust 开发者能够用一套类型安全、框架无关的组件库，在 GPUI 应用中快速嵌入一个生产级流程设计器**，而无需重新发明布局算法与边路径几何。

本书不是 API 手册的堆砌，而是一份**面向产品形态的开发者指南**——它告诉你框架如何思考、如何组织代码、如何在真实项目中解决实际问题，以及如何从入门者成长为能够驾驭整个框架、扩展专属节点的开发者。

本书适合谁

| 读者画像 | 你将获得什么 | |---------|-------------| | 在 GPUI 中嵌入流程设计器的团队 | 渐进式集成路径，从 demo 到生产的最短距离 | | Rust 中级开发者，首次构建可视化编辑器 | 图模型/布局/交互/渲染的完整知识体系，避免反复试错 | | 架构师与技术负责人 | 分层边界、扩展点设计与 trait 注入模式的决策依据 | | Agent / 工作流平台构建者 | 图灵完备控制流节点（顺序/分支/循环）的可视化范式 |

如何阅读本书

本书严格遵循**渐进式披露**原则：

1. **第一至二章**——建立全局认知，10 分钟内跑起第一个流程设计器 2. **第三至四章**——理解设计哲学与架构全景，知道「为什么这样设计」 3. **第五至七章**——深入核心数据模型：图、Schema、几何与布局 4. **第八至十章**——掌握节点系统：从内置节点到自定义开发 5. **第十一至十三章**——理解渲染与交互：主视图、状态机、边渲染 6. **第十四至十五章**——用属性面板与扩展点体系定制产品形态 7. **第十六章**——通过最佳实践与 Demo 案例融会贯通

每章开头的 `INDEX.md` 是小节目录；遇到不熟悉的名词，先读该章 INDEX，再按需跳转到具体小节，不必线性通读。

约定与符号

- 代码示例默认使用 `use rust_agent_flow::*;` / `use rust_agent_flow_gpui::*;` 统一导入 - `✅` 表示推荐做法，`❌` 表示常见错误 - 端口标识写作 `"out"` / `"if_0"` / `"loop_in"`，与 Schema 端口 ID 一致 - 示例项目 `demo` 贯穿全书，可通过 `cargo run -p rust-agent-flow-demo` 本地体验 - 逻辑坐标指文档坐标系（缩放前），屏幕坐标指 GPUI 像素坐标系（缩放后）

致谢

`rust-agent-flow` 站在多个开源项目的肩膀上：`gpui` 与 `gpui-component` 提供桌面 UI 基座，`dagre`（Rust 移植版）提供 Sugiyama 分层布局算法，边路径算法移植自 ReactFlow 的 `@xyflow/xyflow`。感谢所有开源贡献者。

现在，让我们从第一章开始。