aiagent/条件节点功能说明.md

# 条件节点功能说明

## ✅ 已完成

已实现强大的条件节点表达式解析功能，支持复杂的条件判断。

## 功能特性

### 1. 条件表达式解析器 (`backend/app/services/condition_parser.py`)

- 支持多种比较运算符
- 支持逻辑运算符（and, or, not）
- 支持括号分组
- 支持嵌套路径访问
- 安全的表达式评估

### 2. 支持的运算符

#### 比较运算符
- `==`: 等于
- `!=`: 不等于
- `>`: 大于
- `>=`: 大于等于
- `<`: 小于
- `<=`: 小于等于
- `in`: 包含
- `not in`: 不包含
- `contains`: 字符串包含
- `not contains`: 字符串不包含

#### 逻辑运算符
- `and`: 逻辑与
- `or`: 逻辑或
- `not`: 逻辑非

### 3. 工作流引擎集成

- 条件节点根据表达式结果选择分支
- 动态过滤执行路径
- 只执行符合条件的分支节点

## 使用方法

### 1. 在工作流中添加条件节点

1. 打开工作流设计器
2. 从节点工具箱拖拽"条件"节点到画布
3. 配置条件表达式

### 2. 配置条件表达式

在节点配置面板中，输入条件表达式：

#### 简单条件
```
{value} > 10
{status} == 'active'
{count} >= 0
```

#### 逻辑组合
```
{value} > 10 and {value} < 20
{status} == 'active' or {status} == 'pending'
```

#### 复杂条件（括号分组）
```
({value} > 10 and {value} < 20) and {status} == 'active'
({status} == 'a' or {status} == 'b') and {count} > 0
```

### 3. 连接分支

条件节点有两个输出：
- **True分支**（绿色）：条件为真时执行
- **False分支**（红色）：条件为假时执行

连接方式：
1. 从条件节点的底部连接点拖出
2. 选择True或False分支
3. 连接到目标节点

## 表达式语法

### 变量引用

使用 `{key}` 引用输入数据中的字段：

```
{value} > 10
{user.name} == 'admin'
{items[0].price} > 100
```

### 值类型

支持多种值类型：
- **数字**: `10`, `3.14`
- **字符串**: `'active'`, `"pending"`
- **布尔值**: `true`, `false`
- **None**: `null`, `None`

### 嵌套路径

支持访问嵌套数据：
- `{user.name}`: 访问 `user.name`
- `{items[0]}`: 访问数组第一个元素
- `{items[0].price}`: 访问嵌套对象

## 示例

### 示例1: 数值范围判断

```
条件表达式: {value} > 10 and {value} < 20

输入: {"value": 15}
结果: True → 走True分支

输入: {"value": 5}
结果: False → 走False分支
```

### 示例2: 状态判断

```
条件表达式: {status} == 'active' or {status} == 'pending'

输入: {"status": "active"}
结果: True → 走True分支

输入: {"status": "inactive"}
结果: False → 走False分支
```

### 示例3: 复杂条件

```
条件表达式: ({value} > 10 and {value} < 20) and {status} == 'active'

输入: {"value": 15, "status": "active"}
结果: True → 走True分支

输入: {"value": 15, "status": "inactive"}
结果: False → 走False分支
```

### 示例4: 字符串包含

```
条件表达式: {message} contains 'error'

输入: {"message": "发生错误"}
结果: True → 走True分支

输入: {"message": "成功"}
结果: False → 走False分支
```

## 工作流示例

### 示例工作流：条件分支处理

```
开始 → LLM节点(分析) → 条件节点(判断) → [True] → 输出节点1
                                      → [False] → 输出节点2
```

**配置**:
1. LLM节点: 分析输入数据，返回结果
2. 条件节点: `{result} contains 'error'`
3. True分支: 处理错误情况
4. False分支: 处理正常情况

## 测试结果

### 测试覆盖

- ✅ 简单条件表达式 (8/8通过)
- ✅ 逻辑组合条件 (6/6通过)
- ✅ 复杂条件表达式 (4/4通过)
- ✅ 工作流中的条件节点 (通过)

### 测试用例

1. **数值比较**: `{value} > 10`, `{value} == 10`
2. **字符串比较**: `{status} == 'active'`
3. **逻辑组合**: `{value} > 10 and {value} < 20`
4. **或运算**: `{status} == 'active' or {status} == 'pending'`
5. **括号分组**: `({value} > 10 and {value} < 20) and {status} == 'active'`

## 注意事项

1. **变量名**: 使用 `{key}` 格式，key必须存在于输入数据中
2. **字符串值**: 字符串值需要用引号包裹：`'active'` 或 `"active"`
3. **运算符优先级**: `not` > `and` > `or`，可以使用括号改变优先级
4. **分支选择**: 条件节点会根据表达式结果自动选择True或False分支
5. **错误处理**: 如果表达式评估失败，默认返回False

## 安全特性

- 使用安全的表达式评估（限制可用的内置函数）
- 不支持危险的Python操作
- 只允许访问输入数据中的字段
- 自动处理类型转换

## 后续计划

- [ ] 支持更多运算符（如正则匹配）
- [ ] 支持函数调用（如 `len({items}) > 0`）
- [ ] 支持数组操作（如 `{items}.length > 0`）
- [ ] 可视化条件表达式编辑器

---

**状态**: ✅ 已完成
**时间**: 2024年