---
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)