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