13 KiB

Raw Blame History

feature_id

title

status

version

owners

last_updated

source

IDS

意图驱动话术流程（Intent-Driven Script）需求规范

draft

1.0.0

product

backend

frontend

2026-02-28

type	ref
conversation	话术流程配置合理性讨论

意图驱动话术流程需求规范（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'

验收测试:

// 示例：灵活模式步骤配置
{
  "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 模板示例:

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 根据上下文生成变量值
替换模板中的变量占位符

示例:

# 模板
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 必须) 描述: 端到端测试意图驱动流程的执行

测试场景:

创建灵活模式流程
启动流程，验证首步话术生成
输入用户消息，验证流程推进和话术生成
验证对话历史正确传递

AC-IDS-13: 向后兼容性测试

优先级: P0 (MVP 必须) 描述: 验证现有固定话术流程不受影响

测试场景:

加载现有流程（无 script_mode 字段）
执行流程，验证话术正常返回
验证 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 模式

13 KiB Raw Blame History Unescape Escape

意图驱动话术流程需求规范（IDS）

1. 背景与目标

1.1 背景

1.2 目标

1.3 非目标（Out of Scope）

2. 用户故事（User Stories）

US-IDS-01: 配置意图驱动的话术步骤

US-IDS-02: 灵活话术的实时生成

US-IDS-03: 向后兼容现有流程

US-IDS-04: 模板话术的变量填充

3. 验收标准详细说明（Acceptance Criteria）

Phase 1: 数据模型与 API 扩展

AC-IDS-01: 扩展 ScriptFlow 数据模型

AC-IDS-02: 扩展 Admin API 契约

Phase 2: 后端话术生成引擎

AC-IDS-03: 实现话术生成引擎

AC-IDS-04: 实现灵活模式的 Prompt 构建

AC-IDS-05: 实现 Fallback 机制

AC-IDS-06: 实现模板模式的变量填充

Phase 3: 前端配置界面

AC-IDS-07: 前端类型定义扩展

AC-IDS-08: 配置界面增加模式选择

AC-IDS-09: 约束条件管理组件

AC-IDS-10: 流程预览增强

Phase 4: 测试与验证

AC-IDS-11: 单元测试覆盖

AC-IDS-12: 集成测试

AC-IDS-13: 向后兼容性测试

4. 接口映射表（API Mapping）

5. 非功能性需求（NFR）

NFR-IDS-01: 性能要求

NFR-IDS-02: 可靠性要求

NFR-IDS-03: 兼容性要求

6. 数据迁移方案

6.1 数据库变更

6.2 现有数据处理

7. 风险与缓解措施

8. 发布计划

8.1 Phase 划分

8.2 里程碑

9. 附录

9.1 术语表

9.2 参考文档

13 KiB

Raw Blame History