422 lines
13 KiB
Markdown
422 lines
13 KiB
Markdown
---
|
||
feature_id: "IDS"
|
||
title: "意图驱动话术流程（Intent-Driven Script）需求规范"
|
||
status: "draft"
|
||
version: "1.0.0"
|
||
owners:
|
||
- "product"
|
||
- "backend"
|
||
- "frontend"
|
||
last_updated: "2026-02-28"
|
||
source:
|
||
type: "conversation"
|
||
ref: "话术流程配置合理性讨论"
|
||
---
|
||
|
||
# 意图驱动话术流程需求规范（IDS）
|
||
|
||
## 1. 背景与目标
|
||
|
||
### 1.1 背景
|
||
当前话术流程采用"固定话术"模式，每个步骤配置的 `content` 字段是预设的固定文本。这种模式存在以下问题：
|
||
- **缺乏灵活性**：无法根据对话上下文调整话术，显得生硬
|
||
- **意图不明确**：配置中只有"说什么"，没有"为什么说"
|
||
- **维护成本高**：需要为不同场景配置多个相似的流程
|
||
|
||
实际业务需求是：每个步骤有固定的**目的**（例如"获取用户姓名"），但具体**话术**应该根据上下文灵活调整。
|
||
|
||
### 1.2 目标
|
||
- 支持"意图驱动"的话术生成模式，AI 根据步骤意图和上下文实时生成话术
|
||
- 保持向后兼容，现有固定话术流程不受影响
|
||
- 提供三种话术模式：固定、灵活、模板，满足不同场景需求
|
||
- 前端配置界面支持意图配置和模式切换
|
||
|
||
### 1.3 非目标（Out of Scope）
|
||
- 不涉及用户输入的意图识别（已有 IntentRule 模块）
|
||
- 不改变流程状态机的核心逻辑
|
||
- 不涉及 LLM 模型选择和切换
|
||
- 不涉及话术生成的性能优化（缓存、预生成等）
|
||
|
||
---
|
||
|
||
## 2. 用户故事（User Stories）
|
||
|
||
### US-IDS-01: 配置意图驱动的话术步骤
|
||
**作为** 话术流程配置人员
|
||
**我想要** 在配置步骤时指定"意图"而不是固定话术
|
||
**以便** AI 能根据对话上下文灵活生成合适的话术
|
||
|
||
**验收标准**：
|
||
- 前端配置界面支持选择话术模式（固定/灵活/模板）
|
||
- 灵活模式下可以配置步骤意图、意图说明、话术约束
|
||
- 配置保存后能正确存储到数据库
|
||
|
||
### US-IDS-02: 灵活话术的实时生成
|
||
**作为** 对话系统
|
||
**我想要** 根据步骤意图和对话历史生成话术
|
||
**以便** 提供更自然、更符合上下文的对话体验
|
||
|
||
**验收标准**：
|
||
- 执行灵活模式步骤时，调用 LLM 生成话术
|
||
- 生成时考虑步骤意图、约束条件、对话历史
|
||
- 生成失败时有明确的 fallback 机制
|
||
|
||
### US-IDS-03: 向后兼容现有流程
|
||
**作为** 系统管理员
|
||
**我想要** 现有的固定话术流程继续正常工作
|
||
**以便** 不影响已上线的业务
|
||
|
||
**验收标准**：
|
||
- 现有流程数据不需要迁移即可正常执行
|
||
- 未指定 script_mode 的步骤默认为 fixed 模式
|
||
- API 响应包含新字段但不破坏现有客户端
|
||
|
||
### US-IDS-04: 模板话术的变量填充
|
||
**作为** 话术流程配置人员
|
||
**我想要** 配置话术模板，让 AI 填充变量部分
|
||
**以便** 在保持话术框架的同时增加灵活性
|
||
|
||
**验收标准**：
|
||
- 支持在话术中使用 `{变量名}` 标记
|
||
- AI 根据上下文填充变量
|
||
- 模板语法错误时有明确提示
|
||
|
||
---
|
||
|
||
## 3. 验收标准详细说明（Acceptance Criteria）
|
||
|
||
### Phase 1: 数据模型与 API 扩展
|
||
|
||
#### AC-IDS-01: 扩展 ScriptFlow 数据模型
|
||
**优先级**: P0 (MVP 必须)
|
||
**描述**: 在 `ScriptFlow.steps` JSON 字段中增加意图驱动相关字段
|
||
|
||
**技术要求**:
|
||
- 在 `FlowStep` 类型定义中增加以下字段：
|
||
- `intent?: string` - 步骤意图（例如："获取用户姓名"）
|
||
- `intent_description?: string` - 意图详细说明
|
||
- `script_mode?: 'fixed' | 'flexible' | 'template'` - 话术模式
|
||
- `script_constraints?: string[]` - 话术约束条件
|
||
- `expected_variables?: string[]` - 期望提取的变量
|
||
- 保持 `content` 字段向后兼容
|
||
- 默认 `script_mode = 'fixed'`
|
||
|
||
**验收测试**:
|
||
```json
|
||
// 示例：灵活模式步骤配置
|
||
{
|
||
"step_id": "step_1",
|
||
"step_no": 1,
|
||
"script_mode": "flexible",
|
||
"intent": "获取用户真实姓名",
|
||
"intent_description": "需要获取用户的真实姓名用于后续身份确认",
|
||
"script_constraints": [
|
||
"必须礼貌",
|
||
"语气自然，不要生硬",
|
||
"如果用户已经说了姓名，直接确认即可"
|
||
],
|
||
"expected_variables": ["user_name"],
|
||
"content": "您好，请问怎么称呼您？", // fallback 话术
|
||
"wait_input": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### AC-IDS-02: 扩展 Admin API 契约
|
||
**优先级**: P0 (MVP 必须)
|
||
**描述**: 更新 `openapi.admin.yaml` 中 ScriptFlow 相关接口的 schema
|
||
|
||
**技术要求**:
|
||
- 更新 `FlowStepSchema` 定义，增加新字段
|
||
- 所有新字段标记为 `optional`
|
||
- 更新接口文档说明
|
||
- 保持 API 版本不变（向后兼容扩展）
|
||
|
||
**影响接口**:
|
||
- `POST /admin/script-flows` - 创建流程
|
||
- `PUT /admin/script-flows/{id}` - 更新流程
|
||
- `GET /admin/script-flows/{id}` - 获取流程详情
|
||
|
||
---
|
||
|
||
### Phase 2: 后端话术生成引擎
|
||
|
||
#### AC-IDS-03: 实现话术生成引擎
|
||
**优先级**: P0 (MVP 必须)
|
||
**描述**: 在 `FlowEngine` 中实现根据 `script_mode` 生成话术的逻辑
|
||
|
||
**技术要求**:
|
||
- 在 `FlowEngine` 中新增方法 `_generate_step_content(step, context, history)`
|
||
- 实现三种模式的生成逻辑：
|
||
- `fixed`: 直接返回 `step.content`
|
||
- `flexible`: 调用 LLM 生成话术
|
||
- `template`: 使用模板引擎填充变量
|
||
- 在 `start()` 和 `advance()` 方法中调用话术生成
|
||
|
||
**代码位置**: `ai-service/app/services/flow/engine.py`
|
||
|
||
**验收测试**:
|
||
- 固定模式：返回原始 content
|
||
- 灵活模式：生成的话术符合意图和约束
|
||
- 模板模式：正确填充变量
|
||
|
||
---
|
||
|
||
#### AC-IDS-04: 实现灵活模式的 Prompt 构建
|
||
**优先级**: P0 (MVP 必须)
|
||
**描述**: 为灵活模式构建合适的 LLM Prompt
|
||
|
||
**技术要求**:
|
||
- Prompt 包含：步骤意图、约束条件、对话历史（最近 3 轮）、会话上下文
|
||
- 明确指示 AI 生成简洁的话术（不超过 50 字）
|
||
- 包含 fallback 指令（生成失败时的处理）
|
||
|
||
**Prompt 模板示例**:
|
||
```python
|
||
prompt = f"""
|
||
你是一个客服对话系统，当前需要执行以下步骤：
|
||
|
||
【步骤目标】{intent}
|
||
【详细说明】{intent_description}
|
||
【约束条件】
|
||
{'\n'.join(f'- {c}' for c in constraints)}
|
||
|
||
【对话历史】
|
||
{format_history(history[-3:])}
|
||
|
||
【会话上下文】
|
||
{format_context(context)}
|
||
|
||
请生成一句符合目标和约束的话术（不超过50字）。
|
||
只返回话术内容，不要解释。
|
||
"""
|
||
```
|
||
|
||
---
|
||
|
||
#### AC-IDS-05: 实现 Fallback 机制
|
||
**优先级**: P0 (MVP 必须)
|
||
**描述**: 当话术生成失败时，使用 fallback 策略
|
||
|
||
**技术要求**:
|
||
- LLM 调用超时（2秒）时，返回 `step.content` 作为 fallback
|
||
- LLM 返回错误时，记录日志并返回 fallback
|
||
- Fallback 话术不为空时使用，否则返回默认提示
|
||
|
||
**验收测试**:
|
||
- 模拟 LLM 超时，验证返回 fallback 话术
|
||
- 模拟 LLM 错误，验证日志记录和 fallback
|
||
|
||
---
|
||
|
||
#### AC-IDS-06: 实现模板模式的变量填充
|
||
**优先级**: P1 (可选)
|
||
**描述**: 支持在 `content` 中使用 `{变量名}` 标记，AI 填充变量
|
||
|
||
**技术要求**:
|
||
- 解析模板中的变量（正则匹配 `{...}`）
|
||
- 调用 LLM 根据上下文生成变量值
|
||
- 替换模板中的变量占位符
|
||
|
||
**示例**:
|
||
```python
|
||
# 模板
|
||
content = "您好{greeting_style}，请问您{polite_form}？"
|
||
|
||
# AI 生成
|
||
greeting_style = "，很高兴为您服务"
|
||
polite_form = "贵姓"
|
||
|
||
# 结果
|
||
"您好，很高兴为您服务，请问您贵姓？"
|
||
```
|
||
|
||
---
|
||
|
||
### Phase 3: 前端配置界面
|
||
|
||
#### AC-IDS-07: 前端类型定义扩展
|
||
**优先级**: P0 (MVP 必须)
|
||
**描述**: 更新 `script-flow.ts` 类型定义
|
||
|
||
**技术要求**:
|
||
- 在 `FlowStep` 接口中增加新字段
|
||
- 定义 `ScriptMode` 枚举类型
|
||
- 更新相关的 Create/Update 类型
|
||
|
||
**代码位置**: `ai-service-admin/src/types/script-flow.ts`
|
||
|
||
---
|
||
|
||
#### AC-IDS-08: 配置界面增加模式选择
|
||
**优先级**: P0 (MVP 必须)
|
||
**描述**: 在步骤配置表单中增加话术模式选择
|
||
|
||
**技术要求**:
|
||
- 增加 Radio Group 选择话术模式
|
||
- 根据选择的模式动态显示对应配置项
|
||
- 固定模式：显示 `content` 输入框
|
||
- 灵活模式：显示 `intent`、`intent_description`、`constraints` 配置
|
||
- 模板模式：显示 `content` 输入框（带模板语法提示）
|
||
|
||
**代码位置**: `ai-service-admin/src/views/admin/script-flow/index.vue`
|
||
|
||
**UI 要求**:
|
||
- 模式切换时保留已填写的数据
|
||
- 提供模式说明的 Tooltip
|
||
- 约束条件支持标签式添加/删除
|
||
|
||
---
|
||
|
||
#### AC-IDS-09: 约束条件管理组件
|
||
**优先级**: P0 (MVP 必须)
|
||
**描述**: 实现约束条件的添加、删除、编辑
|
||
|
||
**技术要求**:
|
||
- 使用 `el-tag` 显示已添加的约束
|
||
- 支持点击删除约束
|
||
- 输入框回车添加新约束
|
||
- 约束不能为空或重复
|
||
|
||
**UI 示例**:
|
||
```
|
||
话术约束: [必须礼貌 ×] [语气自然 ×] [不要生硬 ×]
|
||
[输入新约束...]
|
||
```
|
||
|
||
---
|
||
|
||
#### AC-IDS-10: 流程预览增强
|
||
**优先级**: P1 (可选)
|
||
**描述**: 在流程预览中显示步骤的意图信息
|
||
|
||
**技术要求**:
|
||
- 在 `FlowPreview.vue` 中显示步骤的 `script_mode`
|
||
- 灵活模式显示意图和约束
|
||
- 固定模式显示话术内容
|
||
|
||
**代码位置**: `ai-service-admin/src/views/admin/script-flow/components/FlowPreview.vue`
|
||
|
||
---
|
||
|
||
### Phase 4: 测试与验证
|
||
|
||
#### AC-IDS-11: 单元测试覆盖
|
||
**优先级**: P0 (MVP 必须)
|
||
**描述**: 为话术生成引擎编写单元测试
|
||
|
||
**技术要求**:
|
||
- 测试三种模式的话术生成
|
||
- 测试 fallback 机制
|
||
- 测试边界情况（空配置、无效配置）
|
||
|
||
**测试文件**: `ai-service/tests/services/flow/test_engine_script_generation.py`
|
||
|
||
---
|
||
|
||
#### AC-IDS-12: 集成测试
|
||
**优先级**: P0 (MVP 必须)
|
||
**描述**: 端到端测试意图驱动流程的执行
|
||
|
||
**测试场景**:
|
||
1. 创建灵活模式流程
|
||
2. 启动流程，验证首步话术生成
|
||
3. 输入用户消息，验证流程推进和话术生成
|
||
4. 验证对话历史正确传递
|
||
|
||
---
|
||
|
||
#### AC-IDS-13: 向后兼容性测试
|
||
**优先级**: P0 (MVP 必须)
|
||
**描述**: 验证现有固定话术流程不受影响
|
||
|
||
**测试场景**:
|
||
1. 加载现有流程（无 script_mode 字段）
|
||
2. 执行流程，验证话术正常返回
|
||
3. 验证 API 响应包含新字段但值为 null
|
||
|
||
---
|
||
|
||
## 4. 接口映射表（API Mapping）
|
||
|
||
| 验收标准 | 接口路径 | 方法 | 变更类型 | 说明 |
|
||
|---------|---------|------|---------|------|
|
||
| AC-IDS-02 | `/admin/script-flows` | POST | 扩展请求体 | steps 增加意图字段 |
|
||
| AC-IDS-02 | `/admin/script-flows/{id}` | PUT | 扩展请求体 | 同上 |
|
||
| AC-IDS-02 | `/admin/script-flows/{id}` | GET | 扩展响应体 | 返回意图字段 |
|
||
| AC-IDS-03 | 内部方法 | - | 新增 | `_generate_step_content()` |
|
||
| AC-IDS-05 | 内部方法 | - | 修改 | `start()`, `advance()` |
|
||
|
||
---
|
||
|
||
## 5. 非功能性需求（NFR）
|
||
|
||
### NFR-IDS-01: 性能要求
|
||
- 话术生成延迟 < 2 秒（P95）
|
||
- LLM 调用超时设置为 2 秒
|
||
- API 响应时间增加 < 10%
|
||
|
||
### NFR-IDS-02: 可靠性要求
|
||
- 话术生成失败率 < 1%
|
||
- Fallback 机制 100% 可用
|
||
- 无数据丢失
|
||
|
||
### NFR-IDS-03: 兼容性要求
|
||
- 现有流程无需迁移即可运行
|
||
- API 向后兼容（新字段可选）
|
||
- 前端支持旧版本数据
|
||
|
||
---
|
||
|
||
## 6. 数据迁移方案
|
||
|
||
### 6.1 数据库变更
|
||
**无需数据库 Schema 变更**，因为 `steps` 字段已经是 JSON 类型，可以直接扩展。
|
||
|
||
### 6.2 现有数据处理
|
||
- 现有流程数据保持不变
|
||
- 执行时默认 `script_mode = 'fixed'`
|
||
- 无需运行迁移脚本
|
||
|
||
---
|
||
|
||
## 7. 风险与缓解措施
|
||
|
||
| 风险 | 影响 | 概率 | 缓解措施 |
|
||
|------|------|------|---------|
|
||
| LLM 生成话术不稳定 | 用户体验差 | 中 | 提供 fallback 到固定话术 |
|
||
| 生成延迟过高 | 对话不流畅 | 中 | 设置 2 秒超时，超时返回 fallback |
|
||
| 约束条件理解偏差 | 话术不符合预期 | 低 | 提供详细的 Prompt 指导 |
|
||
| 向后兼容性问题 | 现有流程失效 | 低 | 充分测试，默认 fixed 模式 |
|
||
|
||
---
|
||
|
||
## 8. 发布计划
|
||
|
||
### 8.1 Phase 划分
|
||
- **Phase 1**: 数据模型与 API 扩展（AC-IDS-01 ~ AC-IDS-02）
|
||
- **Phase 2**: 后端话术生成引擎（AC-IDS-03 ~ AC-IDS-06）
|
||
- **Phase 3**: 前端配置界面（AC-IDS-07 ~ AC-IDS-10）
|
||
- **Phase 4**: 测试与验证（AC-IDS-11 ~ AC-IDS-13）
|
||
|
||
### 8.2 里程碑
|
||
- **M1**: 后端 MVP 完成（Phase 1 + Phase 2 核心功能）
|
||
- **M2**: 前端配置完成（Phase 3）
|
||
- **M3**: 测试通过，可发布（Phase 4）
|
||
|
||
---
|
||
|
||
## 9. 附录
|
||
|
||
### 9.1 术语表
|
||
- **意图（Intent）**: 步骤要达到的目的，例如"获取用户姓名"
|
||
- **话术（Script）**: 实际发送给用户的文本内容
|
||
- **约束（Constraint）**: 对话术的限制条件，例如"必须礼貌"
|
||
- **Fallback**: 当主要方案失败时的备用方案
|
||
|
||
### 9.2 参考文档
|
||
- [功能定界](./scope.md)
|
||
- [现有 FlowEngine 实现](../../ai-service/app/services/flow/engine.py)
|
||
- [现有前端配置界面](../../ai-service-admin/src/views/admin/script-flow/index.vue)
|