docs: init openapi contract [AC-IDS-01]
This commit is contained in:
MerCry
parent
d30043e5e3
commit
e10cbc2321
|
|
@ -0,0 +1,415 @@
|
||||||
|
openapi: 3.1.0
|
||||||
|
info:
|
||||||
|
title: "Intent-Driven Script Flow API Extension"
|
||||||
|
description: |
|
||||||
|
[AC-IDS-02] 意图驱动话术流程的 API 扩展规范
|
||||||
|
|
||||||
|
本文档描述对现有 ScriptFlow API 的扩展，增加意图驱动话术生成能力。
|
||||||
|
这是对 `spec/ai-service/openapi.admin.yaml` 的向后兼容扩展。
|
||||||
|
|
||||||
|
**变更摘要**:
|
||||||
|
- 扩展 `FlowStep` schema，增加意图驱动字段
|
||||||
|
- 所有新字段均为可选（optional），确保向后兼容
|
||||||
|
- 复用现有的 CRUD 接口，无需新增接口
|
||||||
|
|
||||||
|
**影响接口**:
|
||||||
|
- POST /admin/script-flows
|
||||||
|
- PUT /admin/script-flows/{id}
|
||||||
|
- GET /admin/script-flows/{id}
|
||||||
|
version: "1.0.0"
|
||||||
|
x-contract-level: L1
|
||||||
|
x-extends: "../ai-service/openapi.admin.yaml"
|
||||||
|
|
||||||
|
components:
|
||||||
|
schemas:
|
||||||
|
# [AC-IDS-01] 扩展的 FlowStep Schema
|
||||||
|
FlowStepExtended:
|
||||||
|
type: object
|
||||||
|
required: [stepNo, content]
|
||||||
|
properties:
|
||||||
|
# === 原有字段（保持不变）===
|
||||||
|
stepNo:
|
||||||
|
type: integer
|
||||||
|
description: "步骤序号（从1开始）"
|
||||||
|
example: 1
|
||||||
|
|
||||||
|
content:
|
||||||
|
type: string
|
||||||
|
description: |
|
||||||
|
话术内容。根据 script_mode 的不同有不同含义：
|
||||||
|
- fixed 模式：固定话术文本
|
||||||
|
- flexible 模式：fallback 话术（LLM 生成失败时使用）
|
||||||
|
- template 模式：话术模板（包含 {变量名} 占位符）
|
||||||
|
example: "您好，请问怎么称呼您？"
|
||||||
|
|
||||||
|
waitInput:
|
||||||
|
type: boolean
|
||||||
|
default: true
|
||||||
|
description: "是否等待用户输入"
|
||||||
|
|
||||||
|
timeoutSeconds:
|
||||||
|
type: integer
|
||||||
|
default: 120
|
||||||
|
description: "等待超时时间（秒）"
|
||||||
|
minimum: 10
|
||||||
|
maximum: 600
|
||||||
|
|
||||||
|
timeoutAction:
|
||||||
|
type: string
|
||||||
|
enum: [repeat, skip, transfer]
|
||||||
|
default: repeat
|
||||||
|
description: |
|
||||||
|
超时后的动作：
|
||||||
|
- repeat: 重复当前步骤
|
||||||
|
- skip: 跳过进入下一步
|
||||||
|
- transfer: 转人工
|
||||||
|
|
||||||
|
nextConditions:
|
||||||
|
type: array
|
||||||
|
description: "条件跳转配置"
|
||||||
|
items:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
keywords:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
description: "关键词列表"
|
||||||
|
pattern:
|
||||||
|
type: string
|
||||||
|
description: "正则表达式模式"
|
||||||
|
gotoStep:
|
||||||
|
type: integer
|
||||||
|
description: "跳转到的步骤号"
|
||||||
|
|
||||||
|
defaultNext:
|
||||||
|
type: integer
|
||||||
|
nullable: true
|
||||||
|
description: "默认下一步（null 表示顺序执行）"
|
||||||
|
|
||||||
|
# === 新增字段（意图驱动）===
|
||||||
|
script_mode:
|
||||||
|
type: string
|
||||||
|
enum: [fixed, flexible, template]
|
||||||
|
default: fixed
|
||||||
|
description: |
|
||||||
|
[AC-IDS-01] 话术模式：
|
||||||
|
- fixed: 固定话术（向后兼容，默认模式）
|
||||||
|
- flexible: 灵活话术（AI 根据意图和上下文生成）
|
||||||
|
- template: 模板话术（AI 填充变量）
|
||||||
|
example: "flexible"
|
||||||
|
|
||||||
|
intent:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
description: |
|
||||||
|
[AC-IDS-01] 步骤意图（flexible 模式必填）
|
||||||
|
描述这一步要达到的目的，而不是具体说什么话。
|
||||||
|
example: "获取用户真实姓名"
|
||||||
|
|
||||||
|
intent_description:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
description: |
|
||||||
|
[AC-IDS-01] 意图详细说明（可选）
|
||||||
|
提供更详细的上下文信息，帮助 AI 更好地理解意图。
|
||||||
|
example: "需要获取用户的真实姓名用于后续身份确认，如果用户已经说了姓名则直接确认，如果没说则礼貌询问"
|
||||||
|
|
||||||
|
script_constraints:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
description: |
|
||||||
|
[AC-IDS-01] 话术约束条件（flexible 模式推荐配置）
|
||||||
|
对生成话术的限制条件，例如语气、风格、长度等。
|
||||||
|
example:
|
||||||
|
- "必须礼貌"
|
||||||
|
- "语气自然，不要生硬"
|
||||||
|
- "如果用户已经说了姓名，直接确认即可"
|
||||||
|
- "如果用户拒绝，不要强迫"
|
||||||
|
|
||||||
|
expected_variables:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
description: |
|
||||||
|
[AC-IDS-01] 期望提取的变量（可选）
|
||||||
|
这一步期望从用户输入中提取的变量名称。
|
||||||
|
example: ["user_name"]
|
||||||
|
|
||||||
|
# 扩展的 ScriptFlowCreate（用于创建流程）
|
||||||
|
ScriptFlowCreateExtended:
|
||||||
|
type: object
|
||||||
|
required: [name, steps]
|
||||||
|
properties:
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
description: "流程名称"
|
||||||
|
example: "客户信息收集流程"
|
||||||
|
|
||||||
|
description:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
description: "流程描述"
|
||||||
|
example: "收集客户姓名、电话、需求等基本信息"
|
||||||
|
|
||||||
|
steps:
|
||||||
|
type: array
|
||||||
|
description: "流程步骤列表"
|
||||||
|
items:
|
||||||
|
$ref: "#/components/schemas/FlowStepExtended"
|
||||||
|
|
||||||
|
isEnabled:
|
||||||
|
type: boolean
|
||||||
|
default: true
|
||||||
|
description: "是否启用"
|
||||||
|
|
||||||
|
# 扩展的 ScriptFlowDetail（用于返回流程详情）
|
||||||
|
ScriptFlowDetailExtended:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
description: "流程ID"
|
||||||
|
|
||||||
|
name:
|
||||||
|
type: string
|
||||||
|
description: "流程名称"
|
||||||
|
|
||||||
|
description:
|
||||||
|
type: string
|
||||||
|
nullable: true
|
||||||
|
description: "流程描述"
|
||||||
|
|
||||||
|
steps:
|
||||||
|
type: array
|
||||||
|
description: "流程步骤列表"
|
||||||
|
items:
|
||||||
|
$ref: "#/components/schemas/FlowStepExtended"
|
||||||
|
|
||||||
|
isEnabled:
|
||||||
|
type: boolean
|
||||||
|
description: "是否启用"
|
||||||
|
|
||||||
|
stepCount:
|
||||||
|
type: integer
|
||||||
|
description: "步骤数量"
|
||||||
|
|
||||||
|
linkedRuleCount:
|
||||||
|
type: integer
|
||||||
|
description: "关联的意图规则数量"
|
||||||
|
|
||||||
|
createdAt:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
description: "创建时间"
|
||||||
|
|
||||||
|
updatedAt:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
description: "更新时间"
|
||||||
|
|
||||||
|
examples:
|
||||||
|
# 示例1：固定话术模式（向后兼容）
|
||||||
|
FixedModeStep:
|
||||||
|
summary: "固定话术步骤（传统模式）"
|
||||||
|
value:
|
||||||
|
stepNo: 1
|
||||||
|
content: "您好，请问您贵姓？"
|
||||||
|
waitInput: true
|
||||||
|
timeoutSeconds: 60
|
||||||
|
script_mode: "fixed"
|
||||||
|
|
||||||
|
# 示例2：灵活话术模式
|
||||||
|
FlexibleModeStep:
|
||||||
|
summary: "灵活话术步骤（意图驱动）"
|
||||||
|
value:
|
||||||
|
stepNo: 1
|
||||||
|
script_mode: "flexible"
|
||||||
|
intent: "获取用户真实姓名"
|
||||||
|
intent_description: "需要获取用户的真实姓名用于后续身份确认，如果用户已经说了姓名则直接确认，如果没说则礼貌询问"
|
||||||
|
script_constraints:
|
||||||
|
- "必须礼貌"
|
||||||
|
- "语气自然，不要生硬"
|
||||||
|
- "如果用户已经说了姓名，直接确认即可"
|
||||||
|
- "如果用户拒绝，不要强迫"
|
||||||
|
expected_variables:
|
||||||
|
- "user_name"
|
||||||
|
content: "您好，请问怎么称呼您？" # fallback 话术
|
||||||
|
waitInput: true
|
||||||
|
timeoutSeconds: 60
|
||||||
|
|
||||||
|
# 示例3：模板话术模式
|
||||||
|
TemplateModeStep:
|
||||||
|
summary: "模板话术步骤"
|
||||||
|
value:
|
||||||
|
stepNo: 2
|
||||||
|
script_mode: "template"
|
||||||
|
content: "好的{user_name}，请问您{inquiry_style}？"
|
||||||
|
intent: "询问用户需求"
|
||||||
|
script_constraints:
|
||||||
|
- "根据用户姓名调整称呼方式"
|
||||||
|
- "询问方式要自然"
|
||||||
|
expected_variables:
|
||||||
|
- "user_requirement"
|
||||||
|
waitInput: true
|
||||||
|
|
||||||
|
# 示例4：完整流程（混合模式）
|
||||||
|
MixedModeFlow:
|
||||||
|
summary: "混合模式流程（包含固定、灵活、模板三种步骤）"
|
||||||
|
value:
|
||||||
|
name: "客户信息收集流程"
|
||||||
|
description: "收集客户基本信息并了解需求"
|
||||||
|
steps:
|
||||||
|
- stepNo: 1
|
||||||
|
script_mode: "fixed"
|
||||||
|
content: "您好，欢迎咨询！"
|
||||||
|
waitInput: false
|
||||||
|
|
||||||
|
- stepNo: 2
|
||||||
|
script_mode: "flexible"
|
||||||
|
intent: "获取用户姓名"
|
||||||
|
intent_description: "礼貌询问用户姓名"
|
||||||
|
script_constraints:
|
||||||
|
- "必须礼貌"
|
||||||
|
- "语气自然"
|
||||||
|
content: "请问怎么称呼您？"
|
||||||
|
waitInput: true
|
||||||
|
expected_variables: ["user_name"]
|
||||||
|
|
||||||
|
- stepNo: 3
|
||||||
|
script_mode: "template"
|
||||||
|
content: "好的{user_name}，请问您有什么需要帮助的吗？"
|
||||||
|
intent: "询问用户需求"
|
||||||
|
waitInput: true
|
||||||
|
expected_variables: ["user_requirement"]
|
||||||
|
|
||||||
|
# 接口路径说明（复用现有接口，无需新增）
|
||||||
|
paths:
|
||||||
|
/admin/script-flows:
|
||||||
|
post:
|
||||||
|
summary: "创建话术流程"
|
||||||
|
description: |
|
||||||
|
[AC-IDS-02] 创建新的话术流程。
|
||||||
|
支持意图驱动的步骤配置（通过 FlowStepExtended schema）。
|
||||||
|
operationId: createScriptFlow
|
||||||
|
parameters:
|
||||||
|
- $ref: "../ai-service/openapi.admin.yaml#/components/parameters/XTenantId"
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: "#/components/schemas/ScriptFlowCreateExtended"
|
||||||
|
examples:
|
||||||
|
mixedMode:
|
||||||
|
$ref: "#/components/examples/MixedModeFlow"
|
||||||
|
responses:
|
||||||
|
"201":
|
||||||
|
description: "创建成功"
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: "#/components/schemas/ScriptFlowDetailExtended"
|
||||||
|
"400":
|
||||||
|
description: "请求参数错误"
|
||||||
|
"401":
|
||||||
|
$ref: "../ai-service/openapi.admin.yaml#/components/responses/Unauthorized"
|
||||||
|
|
||||||
|
/admin/script-flows/{id}:
|
||||||
|
get:
|
||||||
|
summary: "获取话术流程详情"
|
||||||
|
description: |
|
||||||
|
[AC-IDS-02] 获取指定流程的详细信息。
|
||||||
|
返回包含意图驱动字段的完整步骤配置。
|
||||||
|
operationId: getScriptFlow
|
||||||
|
parameters:
|
||||||
|
- $ref: "../ai-service/openapi.admin.yaml#/components/parameters/XTenantId"
|
||||||
|
- name: id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
responses:
|
||||||
|
"200":
|
||||||
|
description: "获取成功"
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: "#/components/schemas/ScriptFlowDetailExtended"
|
||||||
|
"404":
|
||||||
|
description: "流程不存在"
|
||||||
|
|
||||||
|
put:
|
||||||
|
summary: "更新话术流程"
|
||||||
|
description: |
|
||||||
|
[AC-IDS-02] 更新现有流程的配置。
|
||||||
|
支持修改步骤的话术模式和意图配置。
|
||||||
|
operationId: updateScriptFlow
|
||||||
|
parameters:
|
||||||
|
- $ref: "../ai-service/openapi.admin.yaml#/components/parameters/XTenantId"
|
||||||
|
- name: id
|
||||||
|
in: path
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: string
|
||||||
|
format: uuid
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: "#/components/schemas/ScriptFlowCreateExtended"
|
||||||
|
responses:
|
||||||
|
"200":
|
||||||
|
description: "更新成功"
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: "#/components/schemas/ScriptFlowDetailExtended"
|
||||||
|
"404":
|
||||||
|
description: "流程不存在"
|
||||||
|
|
||||||
|
# 向后兼容性说明
|
||||||
|
x-compatibility:
|
||||||
|
backward-compatible: true
|
||||||
|
migration-required: false
|
||||||
|
notes: |
|
||||||
|
本扩展完全向后兼容：
|
||||||
|
|
||||||
|
1. **数据兼容性**
|
||||||
|
- 所有新字段均为可选（nullable）
|
||||||
|
- 未指定 script_mode 时默认为 'fixed'
|
||||||
|
- 现有流程数据无需迁移即可正常工作
|
||||||
|
|
||||||
|
2. **API 兼容性**
|
||||||
|
- 复用现有接口，无需修改接口路径
|
||||||
|
- 请求体向后兼容（新字段可选）
|
||||||
|
- 响应体向后兼容（新字段可能为 null）
|
||||||
|
|
||||||
|
3. **客户端兼容性**
|
||||||
|
- 旧版客户端可以忽略新字段
|
||||||
|
- 新版客户端可以处理缺失的新字段
|
||||||
|
|
||||||
|
4. **执行兼容性**
|
||||||
|
- 未指定 script_mode 的步骤按 fixed 模式执行
|
||||||
|
- 保持与现有流程完全相同的行为
|
||||||
|
|
||||||
|
# 验收标准映射
|
||||||
|
x-acceptance-criteria:
|
||||||
|
- id: AC-IDS-01
|
||||||
|
description: "扩展 ScriptFlow 数据模型"
|
||||||
|
schema: FlowStepExtended
|
||||||
|
status: defined
|
||||||
|
|
||||||
|
- id: AC-IDS-02
|
||||||
|
description: "扩展 Admin API 契约"
|
||||||
|
paths:
|
||||||
|
- POST /admin/script-flows
|
||||||
|
- PUT /admin/script-flows/{id}
|
||||||
|
- GET /admin/script-flows/{id}
|
||||||
|
status: defined
|
||||||
Loading…
Reference in New Issue