@fit-elsa/agent-flow：为 elsa 核心框架打造的高性能 React 流程图编排组件库

• 人工智能
• 大模型
• AI 应用
• 低代码
• 后端
• 前端
• 流程编排
• RAG

导读

@fit-elsa/agent-flow是 ModelEngine app-platform 仓库中基于 React 构建的前端应用模块，它为@fit-elsa/elsa核心框架提供完整的 React 封装与开箱即用的 UI 组件，是大模型应用可视化编排（节点拖拽、连线、配置抽屉、试运行、校验）的前端落地方案。阅读本文后，你将掌握如何通过JadeFlow快速嵌入流程图编辑器、通过createGraphOperator操作画布数据、通过MultiConversation实现多会话配置，并理解其基于 Context、React.memo与 Ant Design 表单/树组件封装的底层设计。

项目定位与架构总览

@fit-elsa/agent-flow的定位在 agent-flow/README.md 中写得很清楚：它是「基于 React 的前端应用模块，为 @fit-elsa/elsa 核心框架提供 React 封装和 UI 组件」。

从源码结构看，该模块是一个 Vite 库工程，核心导出集中在 src/index.js：

export {JadeFlow, NODE_STATUS, MultiConversation, MultiConversationContent, createGraphOperator};

也就是说，对外主要暴露五类能力：

• JadeFlow：流程图容器，负责新建、编辑、评估三种流程模式；
• createGraphOperator：纯数据层面的画布操纵器，不依赖 DOM；
• MultiConversation/MultiConversationContent：多会话配置组件；
• NODE_STATUS：节点运行状态常量集合。

构建层面，vite.config.js 将工程打包为可发布库（agent-flow.js/agent-flow.umd.cjs），并声明react、react-dom、@fit-elsa/elsa、antd等为 external 依赖，交由宿主项目提供。入口页 App.jsx 则演示了宿主项目中最典型的用法：先准备各节点类型的后端接口配置（configs），再调用JadeFlow.edit(...)把流程元数据渲染进指定 DOM 容器。

功能亮点：React 与 Ant Design 的深度整合

README 归纳了 agent-flow 的两大技术亮点，结合源码可以进一步看到它们的实际落点。

基于 Context 的上下文传递

整个模块依赖 React 的 Context 机制在组件树中传递流程数据与事件回调。典型示例是 MultiConversation.jsx：外层面板接收itemId、config、disabled、props等属性，再通过内部组件逐层透传给内容区；MultiConversationContent.jsx 则根据props.type.value动态渲染「按对话轮次」「按条数」「按 Token 大小」「按时间」「自定义」等记忆模式配置项，一级菜单切换时还会同步写入二级菜单的默认值（如轮次默认3、条数默认20、Token 默认1000）。

节点渲染缓存：React.memo + 自定义 shouldComponentUpdate

在画布节点较多（上限见下文）的场景下，为避免无关数据变更触发全量重渲染，节点组件通过React.memo配合自定义的shouldComponentUpdate进行渲染缓存，将画布交互保持在流畅水平。这是 README 明确宣称的能力，与 jadeFlowPage.js 中大量使用ignoreChange包裹状态更新的思路一致——只在真正需要刷新的时机触发重绘。

基于 Form 组件的实时校验提示系统

节点配置抽屉中的每一项参数都使用 Ant DesignForm.Item承载，并声明rules与validateTrigger='onBlur'，实现失焦即时校验。同时 agent-flow 还提供了一整套「导入后数据合法性校验」能力（详见后文「画布数据校验与导入校验」小节），其设计文档位于 agent-flow/docs/features/shape-data-validation/index.md，核心实现位于 agent-flow/src/data/ShapeDataValidationProcessor.js。

基于 Tree 组件封装的节点上下文观察者机制

节点之间的数据引用（如后置节点引用前置节点的输出）通过「可被观察对象（Observable）」机制管理。相关实现位于 jadeFlowPage.js 中的ObservableStore：每个节点可以registerObservable注册可监听项，其他节点通过observeTo订阅；数据更新时自动通知观察者，配合基于 Tree 组件封装的选择器（JadeReferenceTreeSelect、JadeReferenceMultiTreeSelect等）完成上下文变量的可视化引用。

安装

在宿主 React 项目中安装 agent-flow 及其核心依赖：

npm install @fit-elsa/agent-flow @fit-elsa/elsa

仓库内 agent-flow/package.json 显示其当前版本为1.0.0-alpha.8，同时依赖antd@4.24.13、react@^18.2.0、@tinymce/tinymce-react、monaco-editor等。模块还内置了中英文双语资源，可通过子路径直接引入：

import en from '@fit-elsa/agent-flow/locales/en.json'; import zh from '@fit-elsa/agent-flow/locales/zh.json';

国际化初始化逻辑见 agent-flow/src/i18n/i18n.js，本地翻译会与@fit-elsa/elsa核心翻译合并，本地优先级更高，默认语言为zh。

快速开始

基本用法：嵌入 JadeFlow 流程图

README 给出的最小可运行示例完整如下：

import React from 'react'; import { JadeFlow, createGraphOperator } from '@fit-elsa/agent-flow'; function MyFlowApp() { // 创建图形操作器 const graphOperator = createGraphOperator(); // 处理图形数据变更 const handleGraphChange = (graphData) => { console.log('图形数据已变更:', graphData); }; return ( <div style={{ width: '100%', height: '100vh' }}> <JadeFlow graphOperator={graphOperator} onGraphChange={handleGraphChange} height={600} width={800} /> </div> ); } export default MyFlowApp;

需要说明的是，仓库当前实际对外暴露的JadeFlow是一个命令式 API 对象而非受控组件：真正的接入方式是先准备好 DOM 容器，再调用JadeFlow.new(...)/JadeFlow.edit(...)/JadeFlow.evaluate(...)三种模式之一，返回一个流程控制代理（见 jadeFlowEntry.jsx）。仓库自带的 App.jsx 演示了标准接入方式：

JadeFlow.edit({ div: stage, // 目标 DOM 容器 tenant: '1111', appId: 'xxx', flowConfigData: graphData, // 流程元数据（JSON） configs: configs, // 各节点类型对应的后端接口配置 i18n: i18n, }).then(agent => { window.agent = agent; // agent 即流程控制代理 window.operator = createGraphOperator(JSON.stringify(graphData)); });

三种模式的适用场景如下：

多会话示例

开始节点支持多轮对话（记忆）配置，README 给出的组件级用法如下：

import React, { useState } from 'react'; import { MultiConversation, MultiConversationContent } from '@fit-elsa/agent-flow'; function MultiConvApp() { const [selectedConversation, setSelectedConversation] = useState(null); const conversations = [ { id: '1', title: '会话 1', content: '这是第一个会话的内容' }, { id: '2', title: '会话 2', content: '这是第二个会话的内容' } ]; return ( <div style={{ display: 'flex', height: '100vh' }}> <div style={{ width: '300px', borderRight: '1px solid #ccc' }}> <MultiConversation conversations={conversations} onSelectConversation={setSelectedConversation} selectedConversationId={selectedConversation?.id} /> </div> <div style={{ flex: 1, padding: '20px' }}> {selectedConversation && ( <MultiConversationContent conversation={selectedConversation} /> )} </div> </div> ); } export default MultiConvApp;

在仓库内部，MultiConversation组件实际接收的是itemId、config、className、disabled、props五类属性（见 MultiConversation.jsx），props.switch.value控制记忆开关，props.type.value控制记忆模式。对外属性conversations、onSelectConversation、selectedConversationId是 README 层面的简化封装描述，实际使用时两者可互相映射。

组件 API 详解

JadeFlow

主要的流程图组件，用于显示和编辑流程图。

属性（README 定义）：

• graphOperator: 图形操作器实例
• onGraphChange: 图形数据变更时的回调函数
• height: 流程图高度
• width: 流程图宽度
• readOnly: 是否只读模式
• locale: 语言设置

从源码看，JadeFlow的实际控制能力由jadeFlowAgent（jadeFlowEntry.jsx）承载，核心方法包括：

MultiConversation

多会话列表组件，用于显示和选择多个会话。

属性：

• conversations: 会话列表数据
• onSelectConversation: 选择会话时的回调函数
• selectedConversationId: 当前选中的会话ID

MultiConversationContent

会话内容组件，用于显示选中会话的详细内容。

属性：

• conversation: 会话对象数据

createGraphOperator

创建图形操作器的函数，用于管理图形数据和操作。它是 agent-flow 中最值得深入的数据层 API，下文单独展开。

createGraphOperator 源码级解析

createGraphOperator(graphString)的实现位于 agent-flow/src/data/GraphOperator.js。它接收一个画布 JSON 字符串（内部解析graph.pages[0].shapes），返回一个纯数据操纵器，核心 API 如下：

• getConfig(keys)：按「节点 ID + 参数名路径」读取配置。内部先找到节点，再依据节点类型定位入参来源——开始节点取flowMeta.inputParams，结束节点取flowMeta.callback.converter.entity.inputParams，其余节点取flowMeta.jober.converter.entity.inputParams（GraphOperator.js）。最终通过configToStruct将原始配置转换为结构体。

• update(keys, updates)：按路径修改配置（GraphOperator.js）。关键行为：

  • 若最后一层参数不存在，则自动创建新配置项（生成uuid，类型根据updates自动推导为Array/Object/String/Number/Boolean，见 GraphOperator.js）；
  • 对象类型更新会逐字段 diff：字段缺失则补齐，字段from为Reference类型时跳过不修改（避免覆盖用户引用），其余递归更新（GraphOperator.js）。

• getGraph()：将内部画布对象序列化回 JSON 字符串。

• getFormsToValidateInfo()：遍历所有节点，对每一类需要特殊校验的节点调用ShapeDataValidationProcessor(shape).extractValidationInfo()提取待校验信息，并按节点类型分组返回{type, nodeInfos: [{nodeId, nodeName, configs}]}（GraphOperator.js）。这是「导入应用后，无需加载流程即可提取校验信息」的入口。

• getStartNodeInputParams()：获取画布中开始节点的全部入参信息。

• getShapeIdsByType(type)：按节点类型返回对应节点 ID 列表。

节点体系与运行机制

节点类型与画布限制

jadeFlowGraph（agent-flow/src/flow/jadeFlowGraph.js）在初始化时注册了全部节点插件，覆盖：开始、结束、大模型（llm）、数据检索（retrieval）、知识检索、人工检查、FIT 调用、工具调用、条件分支、代码、HTTP、文本提取、问题优化、变量聚合、文本拼接、变量更新、循环、并行、智能表单、笔记、回复、文生图、HuggingFace 等。画布级限制也在该文件与 jadeFlowPage.js 中定义：

• 每种类型节点上限 19 个（sameTypeNodeNumLimit）；
• 画布总节点上限 99 个（allNodeNumLimit）；
• 开始节点全局唯一（创建第二个会直接抛错）；
• 节点 ID 统一以jade前缀开头，由initJadeId保证（jadeFlowPage.js）；
• 节点重名时自动追加_1、_2等序号（generateNodeName，jadeFlowPage.js）。

试运行状态机

节点试运行由 runners.js 中的三类 runner 驱动：

• standardRunner：常规节点。启动时置为UN_RUNNING并禁用；refreshRun(dataList)根据后端返回的{nodeId, status}逐节点刷新状态——有数据则设置运行状态并写入运行报告，无数据且所有前驱节点均SUCCESS时置为RUNNING；resetRun清空输出/输入/成本并恢复可编辑（runners.js）。
• conditionRunner：条件节点专用，在标准 runner 基础上额外控制分支禁用（runners.js）。
• inactiveNodeRunner：游离节点（不可达节点）专用，仅做禁用/恢复，不参与状态流转（runners.js）。

节点状态常量定义在 agent-flow/src/common/Consts.js：RUNNING、ERROR、SUCCESS('ARCHIVED')、DEFAULT、UN_RUNNING、TERMINATED。状态变更通过 statusManager.js 以 Proxy 拦截方式统一收集，并在微任务中批量刷新节点 UI。

流程校验

page.validate()（jadeFlowPage.js）执行完整的流程合法性校验：

1. 开始节点必须存在且唯一；
2. 从开始节点做 BFS 遍历，计算可达节点集合；
3. 节点总数不得少于 3 个（即至少开始 + 结束 + 一个业务节点）；
4. 对所有jadeNode并发执行节点级validate(linkNodeSet)，失败节点onError()标红；
5. 汇总所有errorFields后整体reject，供上层展示。

画布数据校验与导入校验

针对「应用导入后依赖的插件、模型、知识库、表单等信息需要查询后端接口确认」的场景，agent-flow 提供了不依赖流程加载的校验信息提取能力（设计文档：agent-flow/docs/features/shape-data-validation/index.md）：

1. 前端拿到 graph 后，调用createGraphOperator(graph).getFormsToValidateInfo()（或agent.validate）提取需要校验的信息（覆盖知识检索-知识库、大模型-模型/插件、插件节点、智能表单-表单、结束节点-表单）；
2. 前端将提取信息发送给后端接口做真实性校验；
3. 右侧浮窗展示校验结果，失败项高亮；
4. 进入编排页面后，含失败项的节点以红框包裹（失焦校验 / 页面级校验触发）；
5. 用户修改失败项后，对应校验项自动移除，节点红框恢复为蓝色；
6. 点击浮窗中的节点可将画布中心定位到该节点（scrollToShape）。

提取与有效性判定由 ShapeDataValidationProcessor.js 按节点类型分发实现（endNodeEnd、huggingFaceNodeState、knowledgeRetrievalNodeState、llmNodeState、manualCheckNodeState、retrievalNodeState、toolInvokeNodeState，其余走默认空实现）。validate(validateInfo, refresh)接口改造后支持传入既有校验信息，并通过递归 Proxy 监听其变化以驱动前端刷新（jadeFlowEntry.jsx）；onChange回调则会在数据变更时自动剔除已失效的校验项（jadeFlowEntry.jsx）。

开发与构建

在 agent-flow 目录下执行 README 提供的命令：

# 安装依赖 npm install # 启动开发服务器 npm run dev # 构建生产版本（产物输出到 build/，生成 agent-flow.js 与 agent-flow.umd.cjs） npm run build # 预览生产版本 npm run preview

此外package.json还提供了npm run lint（eslint 全量检查，--max-warnings 0）用于代码规范校验。仓库内的 App.jsx 自带一套完整的交互演示（validate / 调试 / reset / 创建各类节点 / 代码抽屉），可结合npm run dev直接体验 agent-flow 的完整能力。

许可证与版权

@fit-elsa/agent-flow遵循 MIT License，版权归属华为技术有限公司（ModelEngine 项目的一部分），详见 agent-flow/README.md 及 License.txt。

小结

@fit-elsa/agent-flow通过将@fit-elsa/elsa的画布能力封装为 React 组件与命令式代理，屏蔽了底层图形引擎的复杂度，同时以 Ant Design 表单与树组件为基座，落地了表单实时校验、节点上下文观察、导入数据合法性校验等大模型应用编排的关键能力。无论是嵌入完整的流程编排器（JadeFlow），还是仅操作画布数据（createGraphOperator），又或是复用多会话配置组件，开发者都能在宿主 React 工程中快速获得一套可扩展的 Agent 流程编排前端方案。

• 人工智能
• 大模型
• AI 应用
• 低代码
• 后端
• 前端
• 流程编排
• RAG