#FlowGram Runtime 介绍

本文档将介绍 FlowGram Runtime 的基本概念、设计理念和核心功能，帮助业务接入方开发者了解和使用这个工作流运行时引擎的参考实现。

#什么是 FlowGram Runtime

FlowGram Runtime 是一个工作流运行时引擎的参考实现，旨在为业务接入方开发者提供运行时参考。能够解析和执行基于图结构的工作流，支持多种节点类型，包括 Start、End、LLM、Condition、Loop 等。

#项目定位与目标

FlowGram Runtime 定位为 demo 而非 SDK，主要目标是：

• 提供工作流运行时的设计和实现参考
• 展示如何构建和扩展工作流引擎
• 为开发者提供可以直接学习和修改的代码基础
• 支持快速原型开发和概念验证

作为参考实现，FlowGram Runtime 不会作为包发布，开发者需要 fork 代码库后，根据自己的业务场景和需求进行修改和扩展。

#核心概念

#工作流 (Workflow)

工作流是由节点和边组成的有向图，描述了一系列任务的执行顺序和逻辑关系。在 FlowGram Runtime 中，工作流使用 JSON 格式定义，包含节点和边两部分。

工作流定义示例：

{
  "nodes": [
    { "id": "start", "type": "Start", "meta": {}, "data": {} },
    { "id": "llm", "type": "LLM", "meta": {}, "data": { "systemPrompt": "你是助手", "userPrompt": "{{start.input}}" } },
    { "id": "end", "type": "End", "meta": {}, "data": {} }
  ],
  "edges": [
    { "sourceNodeID": "start", "targetNodeID": "llm" },
    { "sourceNodeID": "llm", "targetNodeID": "end" }
  ]
}

#节点 (Node)

节点是工作流中的基本执行单元，每个节点代表一个特定的操作或任务。FlowGram Runtime 支持多种节点类型，包括：

• Start 节点：工作流的起点，提供工作流输入
• End 节点：工作流的终点，收集工作流输出
• LLM 节点：调用大型语言模型，支持系统提示词和用户提示词
• Condition 节点：根据条件选择不同执行分支，支持多种比较操作符
• Loop 节点：对数组中的每个元素执行相同操作，支持子工作流

每个节点包含 ID、类型、元数据和数据等信息，不同类型的节点具有不同的配置选项和行为。

#边 (Edge)

边定义了节点之间的连接关系，表示数据和控制流的传递方向。每条边包含源节点、目标节点和可选的源端口信息。

边的定义决定了工作流的执行路径和数据流向，是构建复杂工作流逻辑的基础。

#执行引擎 (Engine)

执行引擎负责解析工作流定义，按照定义的逻辑顺序执行各个节点，并处理节点间的数据流转。是 FlowGram Runtime 的核心组件，管理整个工作流的生命周期。

#技术架构

FlowGram Runtime 采用领域驱动设计（DDD）架构，将系统分为多个领域：

• 文档 (Document)：工作流定义的数据结构，包括节点和边的模型
• 引擎 (Engine)：工作流执行的核心逻辑，负责工作流的解析和调度
• 执行器 (Executor)：负责执行各类节点的具体逻辑，如 LLM 调用、条件判断等
• 状态 (State)：维护工作流执行过程中的状态信息，包括执行历史和当前状态
• 变量 (Variable)：管理工作流执行过程中的变量数据，支持变量的存储和访问

#技术栈

FlowGram Runtime JS 版本基于以下技术栈构建：

• TypeScript：提供类型安全和现代 JavaScript 特性
• LangChain：集成大型语言模型和相关工具
• OpenAI API：提供 AI 模型调用能力
• Fastify：高性能的 Web 框架，用于 HTTP API 服务
• tRPC：类型安全的 API 框架

#模块组成

项目由三个核心模块组成：

1. js-core：核心运行时库，包含工作流引擎、节点执行器和状态管理
2. interface：接口定义，定义了 API 和数据模型
3. nodejs：NodeJS 服务实现，提供 HTTP API 和服务管理

#当前开发状态和限制 ⚠️

FlowGram Runtime 目前处于早期开发阶段，有以下状态和限制：

#开发状态

• 核心功能已经实现，包括工作流引擎、基本节点类型和主要 API
• 基本的 LLM 集成已完成，支持与 OpenAI 和 LangChain 的集成
• 提供了基本的错误处理和状态管理机制
• 包含测试用例和示例工作流，但文档相对有限

#已知限制

• API 不稳定：API 接口可能会有变更，不保证向后兼容
• 功能不完善：部分功能尚未完全实现，如 ServerInfo API 和 Validation API
• 错误处理：错误处理机制不够完善，某些边缘情况可能导致异常
• 存储机制：当前存储机制较为简单，不适合生产环境的持久化需求
• 安全机制：缺乏完善的安全机制，如认证、授权和输入验证

#未来开发计划

FlowGram Runtime 的未来发展计划包括：

#多语言支持

目前只有 JavaScript/TypeScript 版本，计划开发：

• Python 版本：适用于数据科学和机器学习场景
• Go 版本：适用于高性能服务端场景

#功能增强

• 支持固定布局
• 增加更多节点类型：代码节点、意图识别节点、批处理节点、终止循环节点、继续循环节点、HTTP节点
• 完善错误处理和异常恢复机制
• 完善的服务端校验接口，包括 schema 校验和输入校验等
• 支持 Docker 运行

#试运行优化

• 试运行支持输入表单
• 试运行输入参数校验
• 单节点调试