ai-robot-core/docs/script-flow-usage.md

# 话术流程管理使用指南

## 1. 概述

话术流程（Script Flow）是 AI 中台的多轮对话引导系统，用于按照预定义的步骤引导用户完成信息收集、问题诊断或业务流程。它通过状态机机制实现结构化的对话流程控制。

### 1.1 核心特性

- ✅ **多步骤编排**：支持创建包含多个步骤的对话流程
- ✅ **拖拽排序**：可视化拖拽调整步骤顺序
- ✅ **等待输入控制**：每个步骤可配置是否等待用户回复
- ✅ **超时处理**：支持超时重复、跳过或转人工
- ✅ **变量占位符**：话术内容支持动态变量替换
- ✅ **流程预览**：可视化预览流程执行效果
- ✅ **意图触发**：通过意图规则自动触发流程
- ✅ **状态管理**：自动跟踪流程执行进度

### 1.2 典型应用场景

| 场景 | 说明 | 示例 |
|------|------|------|
| **订单处理** | 收集订单信息并确认 | 收集收货地址 → 确认商品 → 选择支付方式 → 确认下单 |
| **退货流程** | 引导用户完成退货申请 | 确认订单号 → 选择退货原因 → 上传凭证 → 提交申请 |
| **问题诊断** | 逐步排查用户问题 | 确认设备型号 → 检查网络连接 → 重启设备 → 测试结果 |
| **信息采集** | 收集用户需求或反馈 | 询问需求类型 → 收集详细描述 → 确认联系方式 → 提交工单 |
| **预约服务** | 引导用户完成预约 | 选择服务类型 → 选择时间 → 填写联系方式 → 确认预约 |

---

## 2. 功能介绍

### 2.1 流程列表页面

**访问路径**：AI 中台管理后台 → 智能路由 → 话术流程管理

**页面功能**：
- 查看所有话术流程列表
- 显示流程名称、描述、步骤数、关联规则数、状态、更新时间
- 快速启用/禁用流程
- 创建、编辑、预览、删除流程

**列表字段说明**：

| 字段 | 说明 |
|------|------|
| 流程名称 | 流程的唯一标识名称 |
| 描述 | 流程的用途说明（可选） |
| 步骤数 | 流程包含的步骤总数 |
| 关联规则 | 触发该流程的意图规则数量 |
| 状态 | 启用/禁用开关 |
| 更新时间 | 最后修改时间 |

### 2.2 流程编辑器

**核心组件**：
1. **基本信息区**：配置流程名称、描述、启用状态
2. **步骤编辑区**：可视化编辑流程步骤
3. **拖拽排序**：通过拖拽图标调整步骤顺序
4. **步骤配置**：为每个步骤配置详细参数

### 2.3 流程预览器

**功能**：
- 时间轴可视化展示流程步骤
- 模拟流程执行过程
- 高亮显示当前步骤
- 查看步骤配置详情
- 支持上一步/下一步/重置操作

---

## 3. 使用步骤

### 3.1 创建话术流程

#### 步骤 1：进入创建页面

1. 点击页面右上角的 **"新建流程"** 按钮
2. 弹出流程编辑对话框

#### 步骤 2：填写基本信息

```
流程名称：退货流程引导        （必填，建议简洁明确）
描述：引导用户完成退货申请    （可选，说明流程用途）
启用状态：✓ 启用              （默认启用）
```

#### 步骤 3：添加流程步骤

点击 **"添加步骤"** 按钮，配置每个步骤：

**步骤 1 配置示例**：
```
话术内容：您好，我来帮您处理退货申请。请提供您的订单号。
等待输入：✓ 开启
超时时间：60 秒
超时动作：重复当前步骤
```

**步骤 2 配置示例**：
```
话术内容：收到订单号 {{order_id}}，请问您的退货原因是什么？
1. 商品质量问题
2. 不符合预期
3. 其他原因
等待输入：✓ 开启
超时时间：120 秒
超时动作：转人工
```

**步骤 3 配置示例**：
```
话术内容：好的，已记录您的退货原因。请上传商品照片或相关凭证。
等待输入：✓ 开启
超时时间：180 秒
超时动作：跳过进入下一步
```

**步骤 4 配置示例**：
```
话术内容：感谢您的配合！退货申请已提交，工单号为 {{ticket_id}}。我们将在 1-3 个工作日内处理，请保持手机畅通。
等待输入：✗ 关闭
```

#### 步骤 4：调整步骤顺序

- 鼠标悬停在步骤左侧的 **拖拽图标** 上
- 按住鼠标左键拖动步骤到目标位置
- 释放鼠标完成排序

#### 步骤 5：保存流程

- 点击 **"创建"** 按钮保存流程
- 系统自动分配流程 ID
- 返回流程列表页面

### 3.2 编辑话术流程

1. 在流程列表中找到目标流程
2. 点击 **"编辑"** 按钮
3. 修改流程信息或步骤配置
4. 点击 **"保存"** 按钮

**注意事项**：
- 修改后立即生效，影响正在执行的流程
- 建议在低峰期修改重要流程
- 修改前可先禁用流程，测试无误后再启用

### 3.3 预览话术流程

1. 在流程列表中找到目标流程
2. 点击 **"预览"** 按钮
3. 在右侧抽屉中查看流程时间轴
4. 使用 **上一步/下一步** 按钮模拟流程执行
5. 查看每个步骤的配置详情

**预览功能**：
- 时间轴可视化展示所有步骤
- 当前步骤高亮显示（蓝色边框）
- 已完成步骤显示为绿色
- 未执行步骤显示为灰色
- 显示步骤的等待输入、超时配置

### 3.4 删除话术流程

1. 在流程列表中找到目标流程
2. 点击 **"删除"** 按钮
3. 确认删除操作

**警告**：
- 删除操作不可恢复
- 如果有意图规则关联该流程，删除后规则将失效
- 建议先禁用流程观察一段时间，确认无影响后再删除

### 3.5 启用/禁用流程

**方式 1：列表页快速切换**
- 直接点击流程列表中的 **状态开关**
- 立即生效

**方式 2：编辑页面修改**
- 进入流程编辑页面
- 修改 **启用状态** 开关
- 保存后生效

**禁用效果**：
- 禁用后，意图规则无法触发该流程
- 正在执行的流程实例不受影响，继续执行完成
- 流程数据保留，可随时重新启用

---

## 4. 步骤配置详解

### 4.1 话术内容

**功能**：定义该步骤向用户展示的话术文本。

**支持变量占位符**：
```
语法：{{variable_name}}

示例：
- 您的订单号是 {{order_id}}
- 尊敬的 {{customer_name}}，您好！
- 当前时间：{{current_time}}
- 渠道：{{channel_type}}
```

**变量来源**：
- 会话上下文变量
- 用户输入提取的信息
- 系统内置变量（时间、渠道等）

**最佳实践**：
- 话术简洁明了，避免过长
- 使用礼貌用语，保持专业
- 明确告知用户需要做什么
- 提供选项时使用编号列表

### 4.2 等待用户输入

**功能**：控制该步骤是否需要等待用户回复。

**开启（✓）**：
- 系统发送话术后，等待用户回复
- 收到用户回复后，根据条件推进到下一步
- 如果超时未回复，执行超时动作

**关闭（✗）**：
- 系统发送话术后，立即推进到下一步
- 适用于纯信息告知的步骤（如确认信息、结束语）

**使用场景**：
- ✓ 需要收集信息：订单号、退货原因、联系方式
- ✓ 需要用户确认：是/否、选择选项
- ✗ 纯信息展示：流程说明、结果通知、感谢语

### 4.3 超时时间

**功能**：设置等待用户回复的最长时间（单位：秒）。

**取值范围**：5 - 300 秒

**推荐配置**：
- **简单问题**（如是/否）：30-60 秒
- **需要查找信息**（如订单号）：60-120 秒
- **需要操作**（如上传图片）：120-180 秒
- **复杂问题**（如详细描述）：180-300 秒

**注意事项**：
- 超时时间过短：用户体验差，容易误触发超时
- 超时时间过长：流程卡住时间长，影响效率
- 根据实际业务场景调整

### 4.4 超时动作

**功能**：定义超时后的处理策略。

#### 选项 1：重复当前步骤

**行为**：重新发送当前步骤的话术，再次等待用户回复。

**适用场景**：
- 用户可能暂时离开，需要提醒
- 问题简单，用户可能忘记回复
- 重要信息收集，不能跳过

**示例话术**：
```
首次：请提供您的订单号。
重复：您还在吗？请提供您的订单号，以便我帮您处理。
```

#### 选项 2：跳过进入下一步

**行为**：跳过当前步骤，直接进入下一步。

**适用场景**：
- 可选信息收集（如备注、补充说明）
- 有默认值或兜底方案
- 不影响流程继续执行

**注意事项**：
- 确保下一步不依赖当前步骤的输入
- 在后续步骤中处理缺失信息的情况

#### 选项 3：转人工

**行为**：结束流程，将会话转接到人工客服。

**适用场景**：
- 关键信息收集失败
- 用户长时间无响应
- 流程无法继续执行

**效果**：
- 设置 `shouldTransfer=true`
- 返回转人工提示语
- 流程实例标记为"已完成"

---

## 5. 与意图规则关联

### 5.1 创建触发规则

话术流程需要通过 **意图规则** 触发。

**步骤**：
1. 进入 **意图规则管理** 页面
2. 点击 **"新建规则"** 按钮
3. 配置规则信息：

```
规则名称：退货意图
关键词：退货、退款、不想要了、申请退货
正则表达式：退.*货、如何.*退、想.*退
优先级：100
响应类型：启动话术流程
关联流程：选择 "退货流程引导"
启用状态：✓ 启用
```

4. 保存规则

### 5.2 触发流程

**触发条件**：
- 用户消息匹配意图规则的关键词或正则表达式
- 规则的响应类型为 `flow`
- 规则和流程均为启用状态

**触发流程**：
```
用户输入：我想退货
    ↓
意图识别：命中 "退货意图" 规则
    ↓
启动流程：创建 "退货流程引导" 实例
    ↓
执行步骤 1：发送第一步话术
    ↓
等待用户输入：收集订单号
    ↓
执行步骤 2：发送第二步话术
    ↓
...
    ↓
流程完成：恢复正常对话
```

### 5.3 流程执行优先级

**优先级规则**：
1. **进行中的流程** > 意图识别 > RAG 检索
2. 如果会话存在进行中的流程实例，优先处理流程逻辑
3. 流程完成后，恢复正常的意图识别和 RAG 流程

**示例**：
```
会话状态：退货流程进行中（步骤 2）
用户输入：营业时间是什么？
系统行为：忽略 "营业时间" 意图，继续处理流程步骤 2
```

---

## 6. 最佳实践

### 6.1 流程设计原则

#### 1. 步骤数量适中
- **推荐**：3-7 个步骤
- **避免**：步骤过多（>10 步）导致用户疲劳
- **避免**：步骤过少（<3 步）无法体现流程价值

#### 2. 话术简洁明确
- 每个步骤的话术控制在 50-100 字
- 明确告知用户需要做什么
- 提供示例或选项帮助用户理解

#### 3. 合理设置超时
- 根据任务复杂度设置超时时间
- 重要步骤使用 "重复" 或 "转人工"
- 可选步骤使用 "跳过"

#### 4. 提供退出机制
- 在话术中告知用户如何退出流程
- 示例："如需退出流程，请回复 '退出' 或 '转人工'"

### 6.2 话术编写技巧

#### 1. 使用礼貌用语
```
✓ 好的：您好，我来帮您处理退货申请。
✗ 不好：提供订单号。
```

#### 2. 明确指令
```
✓ 好的：请提供您的订单号（格式：20240227001）。
✗ 不好：请提供信息。
```

#### 3. 提供选项
```
✓ 好的：请选择退货原因：
        1. 商品质量问题
        2. 不符合预期
        3. 其他原因
✗ 不好：为什么要退货？
```

#### 4. 确认信息
```
✓ 好的：您的订单号是 {{order_id}}，退货原因是 {{reason}}，确认无误吗？（是/否）
✗ 不好：信息已记录。
```

### 6.3 测试与优化

#### 1. 测试流程
- 创建流程后，先设置为 "禁用" 状态
- 使用测试账号模拟完整流程
- 测试各种用户输入场景（正常、异常、超时）
- 确认无误后再启用

#### 2. 监控数据
- 定期查看流程执行统计
- 关注步骤完成率、超时率、转人工率
- 识别用户卡住的步骤

#### 3. 持续优化
- 根据数据调整话术和超时配置
- 优化步骤顺序和数量
- 收集用户反馈改进流程

### 6.4 常见问题处理

#### 问题 1：用户中途退出流程
**解决方案**：
- 在话术中明确告知退出方式
- 设置关键词触发退出（如 "退出"、"转人工"）
- 超时后自动转人工

#### 问题 2：用户输入不符合预期
**解决方案**：
- 在话术中提供示例和格式说明
- 使用选项列表限制用户输入
- 设置输入验证和错误提示

#### 问题 3：流程执行时间过长
**解决方案**：
- 减少步骤数量，合并相似步骤
- 缩短超时时间
- 将复杂流程拆分为多个子流程

#### 问题 4：流程与意图规则冲突
**解决方案**：
- 提高流程触发规则的优先级
- 在流程执行期间，系统自动优先处理流程逻辑
- 避免创建过于宽泛的意图规则

---

## 7. API 参考

### 7.1 列表查询

**接口**：`GET /admin/script-flows`

**请求参数**：
```json
{
  "is_enabled": true  // 可选，筛选启用/禁用的流程
}
```

**响应示例**：
```json
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "退货流程引导",
      "description": "引导用户完成退货申请",
      "step_count": 4,
      "is_enabled": true,
      "linked_rule_count": 2,
      "created_at": "2026-02-27T10:00:00",
      "updated_at": "2026-02-27T15:30:00"
    }
  ]
}
```

### 7.2 创建流程

**接口**：`POST /admin/script-flows`

**请求示例**：
```json
{
  "name": "退货流程引导",
  "description": "引导用户完成退货申请",
  "is_enabled": true,
  "steps": [
    {
      "step_id": "step_001",
      "order": 1,
      "content": "您好，我来帮您处理退货申请。请提供您的订单号。",
      "wait_for_input": true,
      "timeout_seconds": 60,
      "timeout_action": "repeat",
      "next_conditions": []
    },
    {
      "step_id": "step_002",
      "order": 2,
      "content": "收到订单号 {{order_id}}，请问您的退货原因是什么？",
      "wait_for_input": true,
      "timeout_seconds": 120,
      "timeout_action": "transfer",
      "next_conditions": []
    }
  ]
}
```

**响应示例**：
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "退货流程引导",
  "description": "引导用户完成退货申请",
  "step_count": 2,
  "is_enabled": true,
  "created_at": "2026-02-27T16:00:00",
  "updated_at": "2026-02-27T16:00:00"
}
```

### 7.3 查询详情

**接口**：`GET /admin/script-flows/{flow_id}`

**响应示例**：
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "退货流程引导",
  "description": "引导用户完成退货申请",
  "is_enabled": true,
  "steps": [
    {
      "step_id": "step_001",
      "order": 1,
      "content": "您好，我来帮您处理退货申请。请提供您的订单号。",
      "wait_for_input": true,
      "timeout_seconds": 60,
      "timeout_action": "repeat",
      "next_conditions": []
    }
  ],
  "created_at": "2026-02-27T16:00:00",
  "updated_at": "2026-02-27T16:00:00"
}
```

### 7.4 更新流程

**接口**：`PUT /admin/script-flows/{flow_id}`

**请求示例**：
```json
{
  "name": "退货流程引导（优化版）",
  "is_enabled": true,
  "steps": [
    // 更新后的步骤列表
  ]
}
```

### 7.5 删除流程

**接口**：`DELETE /admin/script-flows/{flow_id}`

**响应**：204 No Content

---

## 8. 数据模型

### 8.1 ScriptFlow（流程实体）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | UUID | 自动生成 | 流程唯一标识 |
| `tenant_id` | string | ✅ | 租户 ID |
| `name` | string | ✅ | 流程名称 |
| `description` | string | ❌ | 流程描述 |
| `steps` | FlowStep[] | ✅ | 步骤列表 |
| `is_enabled` | boolean | ✅ | 是否启用（默认 true） |
| `created_at` | datetime | 自动 | 创建时间 |
| `updated_at` | datetime | 自动 | 更新时间 |

### 8.2 FlowStep（步骤实体）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `step_id` | string | ✅ | 步骤唯一标识 |
| `order` | int | ✅ | 步骤顺序（从 1 开始） |
| `content` | string | ✅ | 话术内容 |
| `wait_for_input` | boolean | ✅ | 是否等待用户输入 |
| `timeout_seconds` | int | ❌ | 超时时间（5-300 秒） |
| `timeout_action` | string | ❌ | 超时动作：repeat/skip/transfer |
| `next_conditions` | NextCondition[] | ❌ | 下一步条件（预留） |

### 8.3 超时动作枚举

| 值 | 说明 |
|------|------|
| `repeat` | 重复当前步骤 |
| `skip` | 跳过进入下一步 |
| `transfer` | 转人工 |

---

## 9. 总结

话术流程管理是 AI 中台的核心功能之一，通过可视化的流程编排，实现结构化的多轮对话引导。

### 9.1 核心价值

- **提升效率**：自动化处理标准流程，减少人工介入
- **保证质量**：标准化话术，确保服务一致性
- **优化体验**：引导式对话，降低用户操作难度
- **数据收集**：结构化收集信息，便于后续处理

### 9.2 使用流程

创建流程 → 配置步骤 → 关联意图规则 → 测试验证 → 启用上线 → 监控优化

### 9.3 注意事项

1. 流程设计要简洁，避免步骤过多
2. 话术要清晰明确，提供必要的示例
3. 合理设置超时时间和超时动作
4. 测试充分后再上线
5. 定期监控数据并优化流程

---

**文档版本**：v1.0
**生成时间**：2026-02-27
**维护状态**：✅ 活跃维护
**相关文档**：
- [意图规则使用指南](./intent-rule-usage.md)
- [AI 中台对接文档](../AI中台对接文档.md)
- [Prompt 模板管理分析](./prompt-template-analysis.md)