# 核心概念

本节介绍 MASFactory 的核心概念：节点、边、图、工作流、节点变量、消息流和控制流。

## 系统架构概览

<ThemedDiagram
  light="/imgs/architecture/system-overview.png"
  dark="/imgs/architecture/system-overview.png"
  alt="MASFactory 系统架构概览"
/>

## 节点

节点（Node）是 MASFactory 中的基本计算单元，是构成工作流的核心要素。所有在 MASFactory 图中执行计算的组件都是节点的派生类。
### 节点的执行机制

当一个节点被执行时，将运行以下步骤：
1. **就绪检查**：检查所有入边是否已有消息且闸门打开
2. **消息聚合**：将所有入边的消息聚合为统一输入
3. **计算处理**：调用 `_forward` 方法执行核心计算逻辑
4. **消息分发**：将计算结果通过所有出边发送给下游节点
5. **状态更新**：更新节点和边的状态，为下一轮执行做准备
::: tip 节点的派生类
节点的派生类主要是对节点的`计算处理`逻辑也就是`_forward`函数进行了重载，少数组件（如`Switch`组件）也重载消息聚合函数和消息分发函数。
:::
### 节点类型

MASFactory 提供了多种节点类型：
- **Agent 节点**：封装大语言模型的智能体节点，支持工具调用和记忆机制
- **Graph 节点**：子图节点，可以嵌套其他节点形成复杂的工作流结构
- **Switch 节点**：条件分支节点，根据逻辑或语义判断选择执行路径
- **CustomNode**：自定义节点，允许用户通过回调函数定义特定的计算逻辑

## 边

边（Edge）连接两个节点，负责流程控制和消息传递。

### 边的主要功能

- **流程控制**：定义节点之间的执行顺序和依赖关系
- **消息传递**：处理上游节点的输出并传递给下游节点
- **数据过滤**：通过 `keys` 参数指定需要传递的特定字段
- **格式转换**：使用 `MessageFormatter` 对消息进行格式化处理

### 边的组成

- **发送节点（sender）**：消息的来源节点
- **接收节点（receiver）**：消息的目标节点
- **键映射（keys）**：定义需要传递的字段及其自然语言描述
- **消息格式化（formatter）**：处理消息格式转换


## 图 与 工作流

图（Graph）是节点和边的集合，是由节点和边组成的有向无环图（Loop中的`Controller`环路除外），提供了工作流的组织和管理能力。图本身也是节点的一种，支持嵌套和复用。

### 图的类型

- **RootGraph**：顶层可执行图，是工作流的入口点，可以被用户直接实例化和调用
- **Graph**：子图节点，可以嵌套在其他图中，提供模块化的工作流组织
- **Loop**：循环图，提供迭代控制和循环终止判断功能

### 图的主要功能

- **节点管理**：通过 `create_node` 方法创建和管理图中的节点
- **边管理**：通过 `create_edge` 系列方法创建节点间的连接关系
- **基础约束检查**：在建边/构建过程中处理重复边、非法环路、保留名称等基础约束
- **执行控制**：管理图内节点的执行顺序和消息传递

### 图的约束条件

为确保图的正确执行，建议满足以下约束：
1. 尽量避免悬空/无路径节点；当前框架不会统一做“孤立节点拒绝”校验
2. 不能出现非法环路结构（如需循环，应使用 Loop 组件）
3. 图上的边所连接的两个节点必须都是这个图内部的节点
4. 入口和出口连接必须使用专用的边创建接口

### 工作流

工作流（Workflow）是使用`RootGraph`图实现的一整套多智能体编排工作流程。<br>
子工作流是使用`Graph`或`Loop`等子图组件实现的局部多智能体编排工作流程。

## 生命周期

MASFactory 工作流的生命周期包括编排、构建、执行三个主要阶段。

### 编排阶段（Orchestration Phase）

在这个阶段，运行用户编写的构图代码来创建工作流的结构：
1. **图创建**：实例化 Graph 或 RootGraph 对象
2. **节点定义**：使用 `create_node` 方法创建各类节点
3. **边连接**：使用 `create_edge` 系列方法建立节点间的连接关系
4. **结构组织**：定义图的层次结构和嵌套关系

### 构建阶段（Build Phase）

在这个阶段，系统调用 `build()` 函数完成整图的预设配置。

### 执行阶段（Execution Phase）

在调用 `invoke()` 后，智能体工作流开始执行，采用基于就绪状态的调度机制：
1. **就绪检查**：持续扫描所有节点的就绪状态
2. **节点执行**：按就绪顺序执行节点的计算逻辑
3. **消息传递**：将计算结果传递给下游节点
4. **状态更新**：更新节点和边的状态信息
5. **终止判断**：检查是否满足工作流终止条件

## 节点变量

节点变量（Node Attributes）是 MASFactory 中的共享状态机制，允许节点间共享和传递状态信息。节点变量采用分层设计，支持从上层环境继承变量，并可以将计算结果回写到上层和本层的环境中。
### 节点变量的管理机制

节点变量是统一的状态管理机制，每个节点都有自己的 `_attributes_store` 来存储变量：

- **变量存储**：每个节点维护独立的 `_attributes_store` 变量存储空间
- **变量传递**：母图（上层环境）的变量会传递给子节点，形成嵌套的变量作用域
- **变量继承**：子节点可以通过 `pull_keys` 从上层环境获取需要的变量
- **变量回写**：节点可以通过 `push_keys` 将计算结果更新到本地和上层变量存储空间

### 变量控制机制

节点变量通过三个核心参数进行精确控制：

#### pull_keys（变量提取控制）
控制从上层环境（outer_env）提取哪些变量字段到本地环境：

- **`None`**：完全继承上层环境的所有变量（`self._attributes_store = outer_env.copy()`）
- **`非空字典`**：按字典中指定的键从上层环境提取对应字段（键为变量名，值为描述）
- **`空字典`**：不继承任何上层变量（`self._attributes_store = {}`）

#### push_keys（变量回写控制）
控制节点执行完成后，将哪些输出字段回写到本地和上层环境：

- **`None`**：回写策略取决于 `pull_keys` 的设置
  - 当 `pull_keys` 为 `None` 时：回写输出中与本地 `attributes` 共同存在的所有键
  - 当 `pull_keys` 为非空字典时：仅回写 `pull_keys` 中指定的键
  - 当 `pull_keys` 为空字典时：不回写任何变量
- **`非空字典`**：仅回写字典中指定的键（键为变量名，值为描述）
- **`空字典`**：不回写任何变量

#### attributes（初始本地变量）
节点的初始本地变量，不受 `pull_keys` 和 `push_keys` 影响，在节点初始化时直接设置到 `_attributes_store` 中。

### 节点类型差异

::: warning 重要提醒
不同类型节点的 `pull_keys` 与 `push_keys` 默认值不同：

- **Agent 节点**：两者默认值均为空字典 `{}`，意味着默认不继承也不回写变量
- **非 Agent 节点**：两者默认值均为 `None`，意味着默认全量继承和回写变量
:::

### 节点变量在节点执行时的作用阶段

节点在执行过程中，变量处理遵循以下流程：

1. **变量提取阶段**（`_pull_attributes`）
   - 在节点执行开始时调用
   - 根据 `pull_keys` 规则从上层环境提取变量到本地

2. **业务逻辑处理**
   - 执行节点的 `_forward` 方法
   - 使用本地变量进行计算

3. **变量回写阶段**
   - **本地回写**（`_attributes_push_local`）：将输出回写到本地 `_attributes_store`
   - **上层回写**（`_attributes_push_outer`）：将本地变量回写到上层环境


### Agent 节点的特殊处理

对于 Agent 节点，`pull_keys` 和 `push_keys` 中的描述信息具有特殊意义：

- **pull_keys 的描述**：会被添加到 Agent 的 prompt 中，告知 Agent 可以访问哪些变量及其含义
- **push_keys 的描述**：会被添加到 Agent 的 prompt 中，指导 Agent 应该输出哪些字段及其用途

### 变量的使用场景

- **状态共享**：在多个节点间共享计算状态和中间结果
- **参数传递**：将配置参数和初始数据传递给子组件
- **结果汇总**：收集和聚合各节点的计算结果到上层环境
- **条件判断**：为分支节点和控制节点提供判断依据
- **上下文传递**：在嵌套图结构中传递执行上下文
- **记忆机制**：在循环和迭代过程中保持状态连续性

## 消息流

消息流（Message Flow）描述了数据在工作流中的传递过程和格式转换机制。
更细粒度的“水平传递（edge）+ 垂直传递（attributes）”可参考：
[`消息更新与传递（水平 / 垂直）`](/zh/guide/message_passing)。

### 两层消息模型（推荐心智模型）

- **水平消息（Edge）**：节点输出字段沿边传递，由 `keys` 决定下游可见字段。
- **垂直消息（attributes）**：节点通过 `pull_keys/push_keys` 读写图上下文状态。

推荐分工：

- 业务 payload（正文、评分、结果）优先放**水平消息**
- 流程状态（计数、重试、阶段标记）优先放**垂直消息**

相关示例：

- 水平为主：`/zh/examples/sequential_workflow`、`/zh/examples/parallel_branching`
- 垂直为主：`/zh/examples/attributes`
- 混合模式：`/zh/examples/looping`

### 消息的基本概念

- **消息对象**：封装数据内容和格式信息的载体
- **消息格式化器**：负责消息格式转换的组件
- **消息聚合**：将多个输入消息合并为统一格式
- **消息分发**：将输出消息发送给所有下游节点

### 消息处理流程

1. **消息生成**：上游节点产生输出消息
2. **格式化**：通过 MessageFormatter 进行格式转换
3. **传输**：消息通过边传递给下游节点
4. **聚合**：下游节点聚合所有输入消息
5. **解析**：将消息内容解析为节点可处理的格式

### 消息格式类型

- **JSON 格式**：结构化数据的标准格式
- **文本格式**：简单字符串消息
- **自定义格式**：通过自定义 MessageFormatter 支持特殊格式

## 控制流

控制流（Control Flow）定义了节点执行的顺序和条件，是工作流调度的核心机制。

### 基于状态的调度

MASFactory 采用基于节点状态的动态调度：
- **就绪条件**：所有入边有消息且`Gate`状态为`Open`
- **执行队列**：维护当前可执行节点的队列
- **并发执行**：支持多个就绪节点的并发处理

### 控制结构

- **顺序控制**：节点按依赖关系顺序执行
- **分支控制**：通过 Switch 节点实现条件分支
- **循环控制**：通过 Loop 图实现迭代逻辑
- **并行控制**：独立分支的并发执行
