# Workflow 用户指南

本文档帮助您了解和使用 LangBot 的 Workflow（工作流）功能，通过可视化方式构建自动化的对话处理流程。

## 目录

- [功能介绍](#功能介绍)
- [快速入门](#快速入门)
- [节点类型说明](#节点类型说明)
- [编辑器使用指南](#编辑器使用指南)
- [调试功能](#调试功能)
- [常见问题解答](#常见问题解答)

---

## 功能介绍

### 什么是 Workflow？

Workflow（工作流）是 LangBot 提供的可视化自动化编排系统。通过拖拽节点、连接边的方式，您可以：

- 📝 **构建复杂的对话流程**：使用条件分支、循环等控制节点
- 🤖 **调用 AI 能力**：集成 LLM、知识库检索、参数提取
- 🔗 **连接外部服务**：集成 Dify、n8n、Coze 等平台
- ⚡ **自动化任务执行**：消息触发、定时触发、Webhook 触发

### Workflow vs Pipeline

| 对比项 | Pipeline | Workflow |
|-------|----------|----------|
| 配置方式 | 表单配置 | 可视化拖拽 |
| 流程控制 | 线性执行 | 支持分支、循环、并行 |
| 适用场景 | 简单对话 | 复杂流程 |
| 学习曲线 | 低 | 中等 |

---

## 快速入门

### 第一步：创建 Workflow

1. 在侧边栏点击 **Workflow** 进入工作流列表
2. 点击右上角 **创建工作流** 按钮
3. 填写基本信息：
   - **名称**：给工作流起一个描述性的名字
   - **描述**：可选，说明工作流的用途
   - **图标**：选择一个 emoji 作为标识

### 第二步：添加节点

进入编辑器后，左侧是节点面板，中间是画布区域，右侧是属性面板。

1. **添加触发节点**：从左侧面板拖拽一个"消息触发"节点到画布
2. **添加 AI 节点**：拖拽一个"LLM 调用"节点
3. **添加回复节点**：拖拽一个"回复消息"节点

### 第三步：连接节点

1. 将鼠标悬停在触发节点的输出端口（右侧小圆点）
2. 按住鼠标拖拽到 LLM 节点的输入端口（左侧小圆点）
3. 同样方式连接 LLM 节点和回复节点

```
[消息触发] ──▶ [LLM 调用] ──▶ [回复消息]
```

### 第四步：配置节点

点击 LLM 调用节点，在右侧属性面板配置：

- **运行方式**：选择"本地 Agent"
- **系统提示词**：描述 AI 的角色和行为
- **模型**：选择要使用的 LLM 模型

点击回复消息节点配置：

- **消息内容**：设置为 `{{nodes.llm_call.outputs.response}}`（引用 LLM 输出）

### 第五步：保存并绑定

1. 点击工具栏的 **保存** 按钮
2. 返回 Bot 配置页面
3. 在 Bot 的绑定设置中选择 **Workflow**，然后选择刚创建的工作流

恭喜！您已经创建了第一个 Workflow。

---

## 节点类型说明

### 触发节点 (Trigger)

触发节点是工作流的入口，定义何时启动执行。

| 节点 | 说明 | 输出 |
|-----|------|------|
| 消息触发 | 收到消息时触发 | message, sender_id, platform |
| 定时触发 | 按 Cron 表达式定时触发 | timestamp |
| Webhook 触发 | 收到 HTTP 请求时触发 | request_body, headers |
| 事件触发 | 系统事件触发 | event_type, event_data |

**消息触发配置示例**：

```yaml
触发条件:
  - 关键词匹配: ["帮助", "help"]
  - 平台: ["wechat", "qq"]
```

### AI 节点

AI 节点用于调用各种 AI 能力。

| 节点 | 说明 | 典型用途 |
|-----|------|---------|
| LLM 调用 | 调用大语言模型 | 生成回复、理解意图 |
| 问题分类器 | 对用户问题分类 | 路由到不同处理分支 |
| 参数提取器 | 从文本提取结构化数据 | 提取订单号、日期等 |
| 知识库检索 | 查询知识库 | RAG 增强回复 |

**LLM 调用配置示例**：

```yaml
运行方式: 本地 Agent
模型: gpt-4
系统提示词: |
  你是一个友好的客服助手。
  请根据用户的问题提供帮助。
温度: 0.7
最大 Token 数: 2000
```

### 处理节点 (Process)

处理节点用于数据处理和外部调用。

| 节点 | 说明 | 典型用途 |
|-----|------|---------|
| 代码执行 | 执行 Python/JavaScript 代码 | 数据处理、格式转换 |
| HTTP 请求 | 发送 HTTP 请求 | 调用外部 API |
| 数据转换 | JSON/模板转换 | 数据格式化 |

**HTTP 请求配置示例**：

```yaml
URL: https://api.example.com/data
方法: POST
请求头:
  Content-Type: application/json
  Authorization: Bearer {{variables.api_key}}
请求体: |
  {"query": "{{message.content}}"}
```

### 控制节点 (Control)

控制节点用于流程控制。

| 节点 | 说明 | 用途 |
|-----|------|------|
| 条件分支 | 二选一分支 | if-else 逻辑 |
| 多路分支 | 多选一分支 | switch-case 逻辑 |
| 循环 | 遍历数组 | 批量处理 |
| 并行 | 同时执行多分支 | 并发处理 |
| 等待 | 暂停执行 | 延时处理 |
| 合并 | 合并多个分支 | 汇总结果 |

**条件分支配置示例**：

```yaml
条件表达式: "{{nodes.classifier.outputs.category}}" == "complaint"
真分支: 投诉处理
假分支: 普通咨询
```

### 动作节点 (Action)

动作节点执行具体操作。

| 节点 | 说明 | 用途 |
|-----|------|------|
| 发送消息 | 主动发送消息 | 通知、推送 |
| 回复消息 | 回复当前消息 | 对话回复 |
| 存储数据 | 保存数据到存储 | 持久化 |
| 调用 Pipeline | 调用现有 Pipeline | 复用现有流程 |

**回复消息配置示例**：

```yaml
消息内容: |
  感谢您的咨询！
  
  {{nodes.llm_call.outputs.response}}
  
  如有其他问题，随时联系我。
```

### 集成节点 (Integration)

集成节点连接外部平台。

| 节点 | 说明 | 平台 |
|-----|------|------|
| Dify 工作流 | 调用 Dify 应用 | Dify |
| Dify 知识库 | 查询 Dify 知识库 | Dify |
| n8n 工作流 | 调用 n8n 流程 | n8n |
| Langflow | 调用 Langflow 流程 | Langflow |
| Coze Bot | 调用扣子 Bot | Coze |

**Dify 工作流配置示例**：

```yaml
API 地址: https://api.dify.ai/v1
API Key: sk-xxxxx
应用类型: workflow
同步对话历史: true
```

---

## 编辑器使用指南

### 画布操作

| 操作 | 方式 |
|-----|------|
| 平移画布 | 按住鼠标中键/空格+左键 拖拽 |
| 缩放画布 | 鼠标滚轮 / 工具栏按钮 |
| 框选多个节点 | 按住 Shift + 拖拽框选 |
| 适应视图 | 点击工具栏"适应"按钮 |

### 节点操作

| 操作 | 方式 |
|-----|------|
| 添加节点 | 从左侧面板拖拽到画布 |
| 移动节点 | 点击节点拖拽 |
| 删除节点 | 选中后按 Delete / 点击工具栏删除 |
| 复制节点 | 选中后 Ctrl+C / 工具栏复制 |
| 粘贴节点 | Ctrl+V / 工具栏粘贴 |

### 连接操作

| 操作 | 方式 |
|-----|------|
| 创建连接 | 从输出端口拖拽到输入端口 |
| 删除连接 | 点击连接线后按 Delete |
| 选中连接 | 点击连接线 |

### 快捷键

| 快捷键 | 功能 |
|-------|------|
| Ctrl + Z | 撤销 |
| Ctrl + Shift + Z | 重做 |
| Ctrl + C | 复制 |
| Ctrl + V | 粘贴 |
| Delete | 删除选中 |
| Ctrl + S | 保存 |

### 工具栏功能

```
[撤销] [重做] | [放大] [缩小] [适应] | [复制] [粘贴] [删除] | [保存] [调试]
```

---

## 调试功能

### 启动调试

1. 点击工具栏的 **调试** 按钮
2. 在调试面板中配置初始数据：
   - **输入消息**：模拟用户发送的消息
   - **会话 ID**：可选，用于测试会话变量
   - **变量**：设置初始变量值

3. 点击 **开始调试** 按钮

### 调试控制

| 按钮 | 功能 |
|-----|------|
| ▶️ 开始/继续 | 开始或继续执行 |
| ⏸️ 暂停 | 暂停执行 |
| ⏹️ 停止 | 停止执行 |
| ⏭️ 单步 | 执行下一个节点 |

### 断点

- **设置断点**：点击节点上的断点图标
- **断点触发**：执行到断点时自动暂停
- **查看状态**：在暂停时查看节点的输入输出

### 执行日志

调试面板下方显示实时日志：

```
[INFO] 2024-01-15 10:30:00 - Starting debug execution
[INFO] 2024-01-15 10:30:00 - Executing node: message_trigger
[DEBUG] 2024-01-15 10:30:00 - Node inputs: {"message": "你好"}
[INFO] 2024-01-15 10:30:01 - Node completed in 50ms
[INFO] 2024-01-15 10:30:01 - Executing node: llm_call
...
```

### 节点状态颜色

| 颜色 | 状态 |
|-----|------|
| 灰色 | 待执行 |
| 蓝色 | 执行中 |
| 绿色 | 已完成 |
| 红色 | 失败 |
| 黄色 | 已跳过 |

---

## 常见问题解答

### Q1：如何在节点间传递数据？

使用表达式语法引用其他节点的输出：

```
{{nodes.节点ID.outputs.输出名称}}
```

例如：
- `{{nodes.llm_call.outputs.response}}` - 引用 LLM 节点的响应
- `{{nodes.http_request.outputs.body}}` - 引用 HTTP 请求的响应体

### Q2：如何使用变量？

Workflow 支持三种变量类型：

1. **工作流变量**：`{{variables.变量名}}`
2. **会话变量**：`{{conversation_variables.变量名}}`
3. **消息上下文**：`{{message.content}}`、`{{message.sender_id}}`

### Q3：条件分支如何写条件表达式？

支持以下运算符：

- 比较：`==`, `!=`, `>`, `<`, `>=`, `<=`
- 逻辑：`and`, `or`, `not`
- 包含：`in`

示例：
```python
# 字符串比较
"{{nodes.classifier.outputs.intent}}" == "purchase"

# 数值比较
{{nodes.extractor.outputs.amount}} > 1000

# 包含检查
"退款" in "{{message.content}}"
```

### Q4：如何处理错误？

1. **节点级重试**：在节点配置中设置重试次数
2. **全局错误处理**：在 Workflow 设置中配置错误处理策略
3. **条件分支**：使用条件节点检查上一节点的状态

### Q5：如何查看执行历史？

1. 进入 Workflow 详情页
2. 点击 **执行历史** 标签
3. 查看每次执行的状态、耗时、输入输出

### Q6：Workflow 可以被多个 Bot 使用吗？

是的。一个 Workflow 可以被多个 Bot 绑定使用，但每个 Bot 只能绑定一个处理单元（Pipeline 或 Workflow）。

### Q7：如何复制现有的 Workflow？

在 Workflow 列表页，点击工作流卡片右上角的菜单，选择"复制"即可创建副本。

### Q8：支持版本回滚吗？

支持。每次保存都会创建新版本。在 Workflow 详情页可以查看版本历史并回滚到指定版本。

---

## 最佳实践

### 1. 合理命名

- 为节点和 Workflow 使用描述性名称
- 使用统一的命名规范

### 2. 模块化设计

- 将复杂流程拆分为多个小 Workflow
- 使用"调用 Pipeline"节点复用现有流程

### 3. 错误处理

- 为关键节点设置重试机制
- 使用条件分支处理异常情况
- 添加日志记录便于排查问题

### 4. 测试先行

- 使用调试功能充分测试
- 准备多种测试场景
- 检查边界情况

### 5. 性能优化

- 避免不必要的节点
- 使用并行节点提高效率
- 合理设置超时时间

---

## 更多资源

- [开发者文档](../development/workflow-system.md)
- [设计文档](../../../plans/langbot-workflow-design.md)
- [API 文档](../service-api-openapi.json)