2562 lines
69 KiB
YAML
2562 lines
69 KiB
YAML
openapi: 3.1.0
|
||
info:
|
||
title: "AI Service Admin API"
|
||
description: "AI 中台管理类接口契约（Provider: ai-service），支持 ai-service-admin 模块进行知识库、Prompt 及 RAG 调试管理。"
|
||
version: "0.7.0"
|
||
x-contract-level: L1
|
||
components:
|
||
parameters:
|
||
XTenantId:
|
||
name: X-Tenant-Id
|
||
in: header
|
||
required: true
|
||
schema:
|
||
type: string
|
||
description: "租户ID，用于物理隔离知识库与数据"
|
||
responses:
|
||
Unauthorized:
|
||
description: "未认证（缺少或无效的认证信息）"
|
||
Forbidden:
|
||
description: "无权限（当前身份无权访问该资源）"
|
||
schemas:
|
||
DocumentInfo:
|
||
type: object
|
||
properties:
|
||
docId:
|
||
type: string
|
||
description: "文档ID"
|
||
kbId:
|
||
type: string
|
||
description: "知识库ID"
|
||
fileName:
|
||
type: string
|
||
description: "文件名"
|
||
status:
|
||
type: string
|
||
description: "文档状态"
|
||
enum: [pending, processing, completed, failed]
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
description: "创建时间"
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
description: "更新时间"
|
||
SessionInfo:
|
||
type: object
|
||
properties:
|
||
sessionId:
|
||
type: string
|
||
description: "会话ID"
|
||
status:
|
||
type: string
|
||
description: "会话状态"
|
||
enum: [active, closed, expired]
|
||
startTime:
|
||
type: string
|
||
format: date-time
|
||
description: "开始时间"
|
||
endTime:
|
||
type: string
|
||
format: date-time
|
||
description: "结束时间"
|
||
messageCount:
|
||
type: integer
|
||
description: "消息数量"
|
||
PageInfo:
|
||
type: object
|
||
properties:
|
||
page:
|
||
type: integer
|
||
description: "当前页码"
|
||
pageSize:
|
||
type: integer
|
||
description: "每页大小"
|
||
total:
|
||
type: integer
|
||
description: "总记录数"
|
||
totalPages:
|
||
type: integer
|
||
description: "总页数"
|
||
# v0.6.0 新增 schemas
|
||
KnowledgeBaseInfo:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: "知识库ID"
|
||
name:
|
||
type: string
|
||
description: "知识库名称"
|
||
kbType:
|
||
type: string
|
||
description: "知识库类型"
|
||
enum: [product, faq, script, policy, general]
|
||
description:
|
||
type: string
|
||
description: "描述"
|
||
priority:
|
||
type: integer
|
||
description: "优先级权重"
|
||
isEnabled:
|
||
type: boolean
|
||
description: "是否启用"
|
||
docCount:
|
||
type: integer
|
||
description: "文档数量"
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
KnowledgeBaseCreate:
|
||
type: object
|
||
required: [name, kbType]
|
||
properties:
|
||
name:
|
||
type: string
|
||
kbType:
|
||
type: string
|
||
enum: [product, faq, script, policy, general]
|
||
description:
|
||
type: string
|
||
priority:
|
||
type: integer
|
||
default: 0
|
||
KnowledgeBaseUpdate:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
kbType:
|
||
type: string
|
||
enum: [product, faq, script, policy, general]
|
||
description:
|
||
type: string
|
||
priority:
|
||
type: integer
|
||
isEnabled:
|
||
type: boolean
|
||
PromptTemplateInfo:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
name:
|
||
type: string
|
||
description: "模板名称"
|
||
scene:
|
||
type: string
|
||
description: "场景标签"
|
||
description:
|
||
type: string
|
||
isDefault:
|
||
type: boolean
|
||
publishedVersion:
|
||
type: integer
|
||
description: "当前发布版本号"
|
||
nullable: true
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
PromptTemplateCreate:
|
||
type: object
|
||
required: [name, scene, systemInstruction]
|
||
properties:
|
||
name:
|
||
type: string
|
||
scene:
|
||
type: string
|
||
description:
|
||
type: string
|
||
systemInstruction:
|
||
type: string
|
||
description: "系统指令内容，支持 {{variable}} 占位符"
|
||
variables:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
default:
|
||
type: string
|
||
description:
|
||
type: string
|
||
PromptTemplateDetail:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
name:
|
||
type: string
|
||
scene:
|
||
type: string
|
||
description:
|
||
type: string
|
||
currentVersion:
|
||
type: object
|
||
properties:
|
||
version:
|
||
type: integer
|
||
status:
|
||
type: string
|
||
enum: [draft, published, archived]
|
||
systemInstruction:
|
||
type: string
|
||
variables:
|
||
type: array
|
||
items:
|
||
type: object
|
||
versions:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
version:
|
||
type: integer
|
||
status:
|
||
type: string
|
||
enum: [draft, published, archived]
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
IntentRuleInfo:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
name:
|
||
type: string
|
||
description: "意图名称"
|
||
keywords:
|
||
type: array
|
||
items:
|
||
type: string
|
||
patterns:
|
||
type: array
|
||
items:
|
||
type: string
|
||
priority:
|
||
type: integer
|
||
responseType:
|
||
type: string
|
||
enum: [flow, rag, fixed, transfer]
|
||
targetKbIds:
|
||
type: array
|
||
items:
|
||
type: string
|
||
nullable: true
|
||
flowId:
|
||
type: string
|
||
nullable: true
|
||
fixedReply:
|
||
type: string
|
||
nullable: true
|
||
transferMessage:
|
||
type: string
|
||
nullable: true
|
||
isEnabled:
|
||
type: boolean
|
||
hitCount:
|
||
type: integer
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
IntentRuleCreate:
|
||
type: object
|
||
required: [name, responseType]
|
||
properties:
|
||
name:
|
||
type: string
|
||
keywords:
|
||
type: array
|
||
items:
|
||
type: string
|
||
patterns:
|
||
type: array
|
||
items:
|
||
type: string
|
||
priority:
|
||
type: integer
|
||
default: 0
|
||
responseType:
|
||
type: string
|
||
enum: [flow, rag, fixed, transfer]
|
||
targetKbIds:
|
||
type: array
|
||
items:
|
||
type: string
|
||
flowId:
|
||
type: string
|
||
fixedReply:
|
||
type: string
|
||
transferMessage:
|
||
type: string
|
||
ScriptFlowInfo:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
stepCount:
|
||
type: integer
|
||
isEnabled:
|
||
type: boolean
|
||
linkedRuleCount:
|
||
type: integer
|
||
description: "关联意图规则数"
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
ScriptFlowCreate:
|
||
type: object
|
||
required: [name, steps]
|
||
properties:
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
steps:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/FlowStep"
|
||
FlowStep:
|
||
type: object
|
||
required: [stepNo, content]
|
||
properties:
|
||
stepNo:
|
||
type: integer
|
||
content:
|
||
type: string
|
||
description: "话术内容"
|
||
waitInput:
|
||
type: boolean
|
||
default: true
|
||
timeoutSeconds:
|
||
type: integer
|
||
default: 120
|
||
timeoutAction:
|
||
type: string
|
||
enum: [repeat, skip, transfer]
|
||
default: repeat
|
||
nextConditions:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
keywords:
|
||
type: array
|
||
items:
|
||
type: string
|
||
pattern:
|
||
type: string
|
||
gotoStep:
|
||
type: integer
|
||
defaultNext:
|
||
type: integer
|
||
nullable: true
|
||
ForbiddenWordInfo:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
word:
|
||
type: string
|
||
category:
|
||
type: string
|
||
enum: [competitor, sensitive, political, custom]
|
||
strategy:
|
||
type: string
|
||
enum: [mask, replace, block]
|
||
replacement:
|
||
type: string
|
||
nullable: true
|
||
fallbackReply:
|
||
type: string
|
||
nullable: true
|
||
isEnabled:
|
||
type: boolean
|
||
hitCount:
|
||
type: integer
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
ForbiddenWordCreate:
|
||
type: object
|
||
required: [word, category, strategy]
|
||
properties:
|
||
word:
|
||
type: string
|
||
category:
|
||
type: string
|
||
enum: [competitor, sensitive, political, custom]
|
||
strategy:
|
||
type: string
|
||
enum: [mask, replace, block]
|
||
replacement:
|
||
type: string
|
||
fallbackReply:
|
||
type: string
|
||
BehaviorRuleInfo:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
ruleText:
|
||
type: string
|
||
description: "行为约束描述"
|
||
category:
|
||
type: string
|
||
enum: [compliance, tone, boundary, custom]
|
||
isEnabled:
|
||
type: boolean
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
BehaviorRuleCreate:
|
||
type: object
|
||
required: [ruleText, category]
|
||
properties:
|
||
ruleText:
|
||
type: string
|
||
category:
|
||
type: string
|
||
enum: [compliance, tone, boundary, custom]
|
||
|
||
# v0.7.0 新增 schemas - 测试与监控
|
||
FlowExecutionStep:
|
||
type: object
|
||
description: "流程执行步骤详情"
|
||
properties:
|
||
step:
|
||
type: integer
|
||
description: "步骤编号（1-12）"
|
||
name:
|
||
type: string
|
||
description: "步骤名称"
|
||
status:
|
||
type: string
|
||
enum: [success, failed, skipped]
|
||
description: "执行状态"
|
||
durationMs:
|
||
type: integer
|
||
description: "执行耗时（毫秒）"
|
||
input:
|
||
type: object
|
||
description: "步骤输入数据"
|
||
output:
|
||
type: object
|
||
description: "步骤输出数据"
|
||
error:
|
||
type: string
|
||
nullable: true
|
||
description: "错误信息（如果失败）"
|
||
metadata:
|
||
type: object
|
||
description: "步骤元数据"
|
||
|
||
FlowExecutionResult:
|
||
type: object
|
||
description: "完整流程执行结果"
|
||
properties:
|
||
executionId:
|
||
type: string
|
||
steps:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/FlowExecutionStep"
|
||
totalDurationMs:
|
||
type: integer
|
||
finalReply:
|
||
type: string
|
||
confidence:
|
||
type: number
|
||
format: float
|
||
shouldTransfer:
|
||
type: boolean
|
||
|
||
IntentRuleTestResult:
|
||
type: object
|
||
description: "意图规则测试结果"
|
||
properties:
|
||
matched:
|
||
type: boolean
|
||
description: "是否命中该规则"
|
||
matchedKeywords:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: "匹配的关键词列表"
|
||
matchedPatterns:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: "匹配的正则表达式列表"
|
||
priority:
|
||
type: integer
|
||
description: "规则优先级"
|
||
priorityRank:
|
||
type: integer
|
||
description: "在所有规则中的优先级排名"
|
||
conflictRules:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
ruleId:
|
||
type: string
|
||
ruleName:
|
||
type: string
|
||
priority:
|
||
type: integer
|
||
description: "同时命中的其他规则列表"
|
||
reason:
|
||
type: string
|
||
nullable: true
|
||
description: "未命中原因"
|
||
|
||
IntentRuleStats:
|
||
type: object
|
||
description: "意图规则监控统计"
|
||
properties:
|
||
ruleId:
|
||
type: string
|
||
ruleName:
|
||
type: string
|
||
hitCount:
|
||
type: integer
|
||
description: "命中次数"
|
||
hitRate:
|
||
type: number
|
||
format: float
|
||
description: "命中率"
|
||
avgResponseTime:
|
||
type: number
|
||
format: float
|
||
description: "平均响应时间（毫秒）"
|
||
lastHitTime:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
responseType:
|
||
type: string
|
||
enum: [flow, rag, fixed, transfer]
|
||
|
||
IntentRuleHitRecord:
|
||
type: object
|
||
description: "意图规则命中记录"
|
||
properties:
|
||
conversationId:
|
||
type: string
|
||
sessionId:
|
||
type: string
|
||
userMessage:
|
||
type: string
|
||
matchedKeywords:
|
||
type: array
|
||
items:
|
||
type: string
|
||
matchedPatterns:
|
||
type: array
|
||
items:
|
||
type: string
|
||
responseType:
|
||
type: string
|
||
executionResult:
|
||
type: string
|
||
enum: [success, failed]
|
||
hitTime:
|
||
type: string
|
||
format: date-time
|
||
|
||
PromptTemplatePreview:
|
||
type: object
|
||
description: "Prompt 模板预览结果"
|
||
properties:
|
||
templateId:
|
||
type: string
|
||
templateName:
|
||
type: string
|
||
version:
|
||
type: integer
|
||
rawContent:
|
||
type: string
|
||
description: "原始模板内容"
|
||
variables:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
value:
|
||
type: string
|
||
description: "变量列表及当前值"
|
||
renderedContent:
|
||
type: string
|
||
description: "渲染后的完整 Prompt"
|
||
estimatedTokens:
|
||
type: integer
|
||
description: "预估 Token 数量"
|
||
|
||
PromptTemplateStats:
|
||
type: object
|
||
description: "Prompt 模板监控统计"
|
||
properties:
|
||
templateId:
|
||
type: string
|
||
templateName:
|
||
type: string
|
||
scene:
|
||
type: string
|
||
usageCount:
|
||
type: integer
|
||
avgTokens:
|
||
type: number
|
||
format: float
|
||
avgPromptTokens:
|
||
type: number
|
||
format: float
|
||
avgCompletionTokens:
|
||
type: number
|
||
format: float
|
||
lastUsedTime:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
|
||
ScriptFlowSimulation:
|
||
type: object
|
||
description: "话术流程模拟执行结果"
|
||
properties:
|
||
simulationId:
|
||
type: string
|
||
flowId:
|
||
type: string
|
||
flowName:
|
||
type: string
|
||
currentStep:
|
||
type: integer
|
||
stepContent:
|
||
type: string
|
||
waitForInput:
|
||
type: boolean
|
||
nextConditions:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
keywords:
|
||
type: array
|
||
items:
|
||
type: string
|
||
nextStep:
|
||
type: integer
|
||
|
||
ScriptFlowStats:
|
||
type: object
|
||
description: "话术流程监控统计"
|
||
properties:
|
||
flowId:
|
||
type: string
|
||
flowName:
|
||
type: string
|
||
activationCount:
|
||
type: integer
|
||
completionCount:
|
||
type: integer
|
||
completionRate:
|
||
type: number
|
||
format: float
|
||
avgCompletionTime:
|
||
type: number
|
||
format: float
|
||
description: "平均完成时长（秒）"
|
||
interruptionCount:
|
||
type: integer
|
||
interruptionRate:
|
||
type: number
|
||
format: float
|
||
|
||
ScriptFlowExecution:
|
||
type: object
|
||
description: "话术流程执行记录"
|
||
properties:
|
||
executionId:
|
||
type: string
|
||
sessionId:
|
||
type: string
|
||
activationTime:
|
||
type: string
|
||
format: date-time
|
||
currentStep:
|
||
type: integer
|
||
status:
|
||
type: string
|
||
enum: [in_progress, completed, interrupted]
|
||
interruptionReason:
|
||
type: string
|
||
nullable: true
|
||
completionTime:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
|
||
GuardrailTestResult:
|
||
type: object
|
||
description: "输出护栏测试结果"
|
||
properties:
|
||
originalText:
|
||
type: string
|
||
processedText:
|
||
type: string
|
||
detectedWords:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
word:
|
||
type: string
|
||
category:
|
||
type: string
|
||
position:
|
||
type: integer
|
||
strategy:
|
||
type: string
|
||
enum: [mask, replace, block]
|
||
isBlocked:
|
||
type: boolean
|
||
blockReason:
|
||
type: string
|
||
nullable: true
|
||
|
||
GuardrailStats:
|
||
type: object
|
||
description: "输出护栏监控统计"
|
||
properties:
|
||
wordId:
|
||
type: string
|
||
word:
|
||
type: string
|
||
category:
|
||
type: string
|
||
blockCount:
|
||
type: integer
|
||
replaceCount:
|
||
type: integer
|
||
maskCount:
|
||
type: integer
|
||
lastBlockTime:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
|
||
GuardrailBlockRecord:
|
||
type: object
|
||
description: "禁词拦截记录"
|
||
properties:
|
||
blockId:
|
||
type: string
|
||
sessionId:
|
||
type: string
|
||
originalText:
|
||
type: string
|
||
processedText:
|
||
type: string
|
||
strategy:
|
||
type: string
|
||
enum: [mask, replace, block]
|
||
blockTime:
|
||
type: string
|
||
format: date-time
|
||
|
||
ConversationRecord:
|
||
type: object
|
||
description: "对话追踪记录"
|
||
properties:
|
||
conversationId:
|
||
type: string
|
||
sessionId:
|
||
type: string
|
||
userMessage:
|
||
type: string
|
||
aiReply:
|
||
type: string
|
||
triggeredRules:
|
||
type: array
|
||
items:
|
||
type: string
|
||
description: "触发的意图规则 ID 列表"
|
||
usedTemplate:
|
||
type: string
|
||
nullable: true
|
||
description: "使用的 Prompt 模板 ID"
|
||
usedFlow:
|
||
type: string
|
||
nullable: true
|
||
description: "使用的话术流程 ID"
|
||
executionTime:
|
||
type: integer
|
||
description: "执行耗时（毫秒）"
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
|
||
paths:
|
||
/admin/kb/documents:
|
||
get:
|
||
summary: "查询文档列表"
|
||
operationId: "listDocuments"
|
||
tags:
|
||
- KB Management
|
||
x-requirements: ["AC-ASA-08", "AC-AISVC-23"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: kbId
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
description: "知识库ID"
|
||
- name: status
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
enum: [pending, processing, completed, failed]
|
||
description: "文档状态"
|
||
- name: page
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: integer
|
||
default: 1
|
||
description: "页码"
|
||
- name: pageSize
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: integer
|
||
default: 20
|
||
description: "每页大小"
|
||
responses:
|
||
'200':
|
||
description: "文档列表"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/DocumentInfo"
|
||
pagination:
|
||
$ref: "#/components/schemas/PageInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
post:
|
||
summary: "上传/导入文档"
|
||
operationId: "uploadDocument"
|
||
tags:
|
||
- KB Management
|
||
x-requirements: ["AC-ASA-01", "AC-AISVC-21", "AC-AISVC-22"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
file:
|
||
type: string
|
||
format: binary
|
||
kbId:
|
||
type: string
|
||
responses:
|
||
'202':
|
||
description: "已接受上传请求，异步启动索引任务"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
jobId:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum: [pending, processing]
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
/admin/kb/index/jobs/{jobId}:
|
||
get:
|
||
summary: "查询索引任务详情"
|
||
operationId: "getIndexJob"
|
||
tags:
|
||
- KB Management
|
||
x-requirements: ["AC-ASA-02", "AC-AISVC-24"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: jobId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: "任务状态详情"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
jobId:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum: [pending, processing, completed, failed]
|
||
progress:
|
||
type: integer
|
||
minimum: 0
|
||
maximum: 100
|
||
errorMsg:
|
||
type: string
|
||
nullable: true
|
||
/admin/config/prompt-templates/{tplId}/publish:
|
||
post:
|
||
summary: "发布指定版本的 Prompt 模板"
|
||
operationId: "publishPromptTemplate"
|
||
tags:
|
||
- Prompt Management
|
||
x-requirements: ["AC-ASA-03"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: tplId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
version:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: "发布成功"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
/admin/rag/experiments/run:
|
||
post:
|
||
summary: "触发 RAG 调试实验"
|
||
operationId: "runRagExperiment"
|
||
tags:
|
||
- RAG Lab
|
||
x-requirements: ["AC-ASA-05", "AC-AISVC-25", "AC-AISVC-26"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
query:
|
||
type: string
|
||
kbIds:
|
||
type: array
|
||
items:
|
||
type: string
|
||
params:
|
||
type: object
|
||
description: "检索参数集"
|
||
responses:
|
||
'200':
|
||
description: "实验结果"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
retrievalResults:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
content:
|
||
type: string
|
||
score:
|
||
type: number
|
||
format: float
|
||
source:
|
||
type: string
|
||
finalPrompt:
|
||
type: string
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
/admin/sessions:
|
||
get:
|
||
summary: "查询会话列表"
|
||
operationId: "listSessions"
|
||
tags:
|
||
- Session Monitoring
|
||
x-requirements: ["AC-ASA-09", "AC-AISVC-27"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: status
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
enum: [active, closed, expired]
|
||
description: "会话状态"
|
||
- name: startTime
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
description: "开始时间"
|
||
- name: endTime
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
description: "结束时间"
|
||
- name: page
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: integer
|
||
default: 1
|
||
description: "页码"
|
||
- name: pageSize
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: integer
|
||
default: 20
|
||
description: "每页大小"
|
||
responses:
|
||
'200':
|
||
description: "会话列表"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/SessionInfo"
|
||
pagination:
|
||
$ref: "#/components/schemas/PageInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
/admin/sessions/{sessionId}:
|
||
get:
|
||
summary: "获取会话详情"
|
||
operationId: "getSessionDetail"
|
||
tags:
|
||
- Session Monitoring
|
||
x-requirements: ["AC-ASA-07", "AC-AISVC-28"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: sessionId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: "全链路会话详情"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
sessionId:
|
||
type: string
|
||
messages:
|
||
type: array
|
||
items:
|
||
type: object
|
||
trace:
|
||
type: object
|
||
description: "含检索、工具调用等追踪信息"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
# ========== v0.6.0 新增 paths ==========
|
||
|
||
/admin/kb/knowledge-bases:
|
||
get:
|
||
summary: "查询知识库列表"
|
||
operationId: "listKnowledgeBases"
|
||
tags:
|
||
- KB Management
|
||
x-requirements: ["AC-ASA-29", "AC-AISVC-59"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: kbType
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
enum: [product, faq, script, policy, general]
|
||
description: "知识库类型筛选"
|
||
- name: isEnabled
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: boolean
|
||
description: "启用状态筛选"
|
||
responses:
|
||
'200':
|
||
description: "知识库列表"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/KnowledgeBaseInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
post:
|
||
summary: "创建知识库"
|
||
operationId: "createKnowledgeBase"
|
||
tags:
|
||
- KB Management
|
||
x-requirements: ["AC-ASA-30", "AC-AISVC-59"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/KnowledgeBaseCreate"
|
||
responses:
|
||
'201':
|
||
description: "创建成功"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/KnowledgeBaseInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/kb/knowledge-bases/{kbId}:
|
||
put:
|
||
summary: "更新知识库"
|
||
operationId: "updateKnowledgeBase"
|
||
tags:
|
||
- KB Management
|
||
x-requirements: ["AC-ASA-32", "AC-AISVC-61"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/KnowledgeBaseUpdate"
|
||
responses:
|
||
'200':
|
||
description: "更新成功"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/KnowledgeBaseInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
delete:
|
||
summary: "删除知识库"
|
||
operationId: "deleteKnowledgeBase"
|
||
tags:
|
||
- KB Management
|
||
x-requirements: ["AC-ASA-33", "AC-AISVC-62"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: kbId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'204':
|
||
description: "删除成功"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/prompt-templates:
|
||
get:
|
||
summary: "查询 Prompt 模板列表"
|
||
operationId: "listPromptTemplates"
|
||
tags:
|
||
- Prompt Management
|
||
x-requirements: ["AC-ASA-23", "AC-AISVC-57"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: scene
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
description: "场景标签筛选"
|
||
responses:
|
||
'200':
|
||
description: "模板列表"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/PromptTemplateInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
post:
|
||
summary: "创建 Prompt 模板"
|
||
operationId: "createPromptTemplate"
|
||
tags:
|
||
- Prompt Management
|
||
x-requirements: ["AC-ASA-24", "AC-AISVC-52"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/PromptTemplateCreate"
|
||
responses:
|
||
'201':
|
||
description: "创建成功"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/PromptTemplateInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/prompt-templates/{tplId}:
|
||
get:
|
||
summary: "查询 Prompt 模板详情"
|
||
operationId: "getPromptTemplateDetail"
|
||
tags:
|
||
- Prompt Management
|
||
x-requirements: ["AC-ASA-28", "AC-AISVC-58"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: tplId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: "模板详情（含版本历史）"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/PromptTemplateDetail"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
put:
|
||
summary: "更新 Prompt 模板（自动创建新版本）"
|
||
operationId: "updatePromptTemplate"
|
||
tags:
|
||
- Prompt Management
|
||
x-requirements: ["AC-ASA-25", "AC-AISVC-53"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: tplId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/PromptTemplateCreate"
|
||
responses:
|
||
'200':
|
||
description: "更新成功，返回新版本信息"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/PromptTemplateInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/prompt-templates/{tplId}/publish:
|
||
post:
|
||
summary: "发布 Prompt 模板指定版本"
|
||
operationId: "publishPromptTemplateVersion"
|
||
tags:
|
||
- Prompt Management
|
||
x-requirements: ["AC-ASA-26", "AC-AISVC-54"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: tplId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [version]
|
||
properties:
|
||
version:
|
||
type: integer
|
||
description: "要发布的版本号"
|
||
responses:
|
||
'200':
|
||
description: "发布成功"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/prompt-templates/{tplId}/rollback:
|
||
post:
|
||
summary: "回滚 Prompt 模板到指定版本"
|
||
operationId: "rollbackPromptTemplate"
|
||
tags:
|
||
- Prompt Management
|
||
x-requirements: ["AC-ASA-27", "AC-AISVC-55"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: tplId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [version]
|
||
properties:
|
||
version:
|
||
type: integer
|
||
description: "要回滚到的版本号"
|
||
responses:
|
||
'200':
|
||
description: "回滚成功"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/intent-rules:
|
||
get:
|
||
summary: "查询意图规则列表"
|
||
operationId: "listIntentRules"
|
||
tags:
|
||
- Intent Rules
|
||
x-requirements: ["AC-ASA-34", "AC-AISVC-65"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: responseType
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
enum: [flow, rag, fixed, transfer]
|
||
description: "响应类型筛选"
|
||
- name: isEnabled
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: boolean
|
||
description: "启用状态筛选"
|
||
responses:
|
||
'200':
|
||
description: "规则列表"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/IntentRuleInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
post:
|
||
summary: "创建意图规则"
|
||
operationId: "createIntentRule"
|
||
tags:
|
||
- Intent Rules
|
||
x-requirements: ["AC-ASA-35", "AC-AISVC-66"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/IntentRuleCreate"
|
||
responses:
|
||
'201':
|
||
description: "创建成功"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/IntentRuleInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/intent-rules/{ruleId}:
|
||
put:
|
||
summary: "更新意图规则"
|
||
operationId: "updateIntentRule"
|
||
tags:
|
||
- Intent Rules
|
||
x-requirements: ["AC-ASA-36", "AC-AISVC-67"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: ruleId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/IntentRuleCreate"
|
||
responses:
|
||
'200':
|
||
description: "更新成功"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/IntentRuleInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
delete:
|
||
summary: "删除意图规则"
|
||
operationId: "deleteIntentRule"
|
||
tags:
|
||
- Intent Rules
|
||
x-requirements: ["AC-ASA-36", "AC-AISVC-68"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: ruleId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'204':
|
||
description: "删除成功"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/script-flows:
|
||
get:
|
||
summary: "查询话术流程列表"
|
||
operationId: "listScriptFlows"
|
||
tags:
|
||
- Script Flows
|
||
x-requirements: ["AC-ASA-37", "AC-AISVC-71"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: isEnabled
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: boolean
|
||
description: "启用状态筛选"
|
||
responses:
|
||
'200':
|
||
description: "流程列表"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/ScriptFlowInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
post:
|
||
summary: "创建话术流程"
|
||
operationId: "createScriptFlow"
|
||
tags:
|
||
- Script Flows
|
||
x-requirements: ["AC-ASA-38", "AC-AISVC-72"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ScriptFlowCreate"
|
||
responses:
|
||
'201':
|
||
description: "创建成功"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ScriptFlowInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/script-flows/{flowId}:
|
||
get:
|
||
summary: "查询话术流程详情"
|
||
operationId: "getScriptFlowDetail"
|
||
tags:
|
||
- Script Flows
|
||
x-requirements: ["AC-ASA-39", "AC-AISVC-73"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: flowId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: "流程详情（含完整步骤定义）"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
isEnabled:
|
||
type: boolean
|
||
steps:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/FlowStep"
|
||
linkedRuleCount:
|
||
type: integer
|
||
createdAt:
|
||
type: string
|
||
format: date-time
|
||
updatedAt:
|
||
type: string
|
||
format: date-time
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
put:
|
||
summary: "更新话术流程"
|
||
operationId: "updateScriptFlow"
|
||
tags:
|
||
- Script Flows
|
||
x-requirements: ["AC-ASA-38", "AC-AISVC-72"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: flowId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ScriptFlowCreate"
|
||
responses:
|
||
'200':
|
||
description: "更新成功"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ScriptFlowInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/guardrails/forbidden-words:
|
||
get:
|
||
summary: "查询禁词列表"
|
||
operationId: "listForbiddenWords"
|
||
tags:
|
||
- Guardrails
|
||
x-requirements: ["AC-ASA-41", "AC-AISVC-78"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: category
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
enum: [competitor, sensitive, political, custom]
|
||
description: "类别筛选"
|
||
- name: isEnabled
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: boolean
|
||
description: "启用状态筛选"
|
||
responses:
|
||
'200':
|
||
description: "禁词列表"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/ForbiddenWordInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
post:
|
||
summary: "添加禁词"
|
||
operationId: "createForbiddenWord"
|
||
tags:
|
||
- Guardrails
|
||
x-requirements: ["AC-ASA-42", "AC-AISVC-79"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ForbiddenWordCreate"
|
||
responses:
|
||
'201':
|
||
description: "添加成功"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ForbiddenWordInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/guardrails/forbidden-words/{wordId}:
|
||
put:
|
||
summary: "更新禁词"
|
||
operationId: "updateForbiddenWord"
|
||
tags:
|
||
- Guardrails
|
||
x-requirements: ["AC-ASA-42", "AC-AISVC-80"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: wordId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ForbiddenWordCreate"
|
||
responses:
|
||
'200':
|
||
description: "更新成功"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ForbiddenWordInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
delete:
|
||
summary: "删除禁词"
|
||
operationId: "deleteForbiddenWord"
|
||
tags:
|
||
- Guardrails
|
||
x-requirements: ["AC-ASA-42", "AC-AISVC-81"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: wordId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'204':
|
||
description: "删除成功"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/guardrails/behavior-rules:
|
||
get:
|
||
summary: "查询行为规则列表"
|
||
operationId: "listBehaviorRules"
|
||
tags:
|
||
- Guardrails
|
||
x-requirements: ["AC-ASA-43", "AC-AISVC-84"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: category
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
enum: [compliance, tone, boundary, custom]
|
||
description: "类别筛选"
|
||
responses:
|
||
'200':
|
||
description: "行为规则列表"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/BehaviorRuleInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
post:
|
||
summary: "添加行为规则"
|
||
operationId: "createBehaviorRule"
|
||
tags:
|
||
- Guardrails
|
||
x-requirements: ["AC-ASA-44", "AC-AISVC-85"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/BehaviorRuleCreate"
|
||
responses:
|
||
'201':
|
||
description: "添加成功"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/BehaviorRuleInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/guardrails/behavior-rules/{ruleId}:
|
||
put:
|
||
summary: "更新行为规则"
|
||
operationId: "updateBehaviorRule"
|
||
tags:
|
||
- Guardrails
|
||
x-requirements: ["AC-ASA-43", "AC-AISVC-85"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: ruleId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/BehaviorRuleCreate"
|
||
responses:
|
||
'200':
|
||
description: "更新成功"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/BehaviorRuleInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
delete:
|
||
summary: "删除行为规则"
|
||
operationId: "deleteBehaviorRule"
|
||
tags:
|
||
- Guardrails
|
||
x-requirements: ["AC-ASA-43", "AC-AISVC-85"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: ruleId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'204':
|
||
description: "删除成功"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
# v0.7.0 新增 paths - 测试与监控
|
||
/admin/test/flow-execution:
|
||
post:
|
||
summary: "完整流程测试"
|
||
operationId: "testFlowExecution"
|
||
tags:
|
||
- Testing
|
||
x-requirements: ["AC-ASA-49", "AC-AISVC-93", "AC-AISVC-94", "AC-AISVC-95"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [message]
|
||
properties:
|
||
message:
|
||
type: string
|
||
description: "测试消息"
|
||
sessionId:
|
||
type: string
|
||
description: "会话 ID（可选）"
|
||
compareConfigs:
|
||
type: array
|
||
description: "对比配置列表"
|
||
items:
|
||
type: object
|
||
properties:
|
||
templateId:
|
||
type: string
|
||
kbIds:
|
||
type: array
|
||
items:
|
||
type: string
|
||
retrievalParams:
|
||
type: object
|
||
responses:
|
||
'200':
|
||
description: "流程执行结果"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
oneOf:
|
||
- $ref: "#/components/schemas/FlowExecutionResult"
|
||
- type: object
|
||
properties:
|
||
comparisons:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/FlowExecutionResult"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/intent-rules/{ruleId}/test:
|
||
post:
|
||
summary: "测试意图规则"
|
||
operationId: "testIntentRule"
|
||
tags:
|
||
- Testing
|
||
x-requirements: ["AC-ASA-53", "AC-AISVC-96"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: ruleId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [message]
|
||
properties:
|
||
message:
|
||
type: string
|
||
description: "测试消息"
|
||
responses:
|
||
'200':
|
||
description: "测试结果"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/IntentRuleTestResult"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
/admin/monitoring/intent-rules:
|
||
get:
|
||
summary: "查询意图规则监控统计"
|
||
operationId: "getIntentRuleStats"
|
||
tags:
|
||
- Monitoring
|
||
x-requirements: ["AC-ASA-54", "AC-AISVC-97"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: startTime
|
||
in: query
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- name: endTime
|
||
in: query
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- name: responseType
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [flow, rag, fixed, transfer]
|
||
responses:
|
||
'200':
|
||
description: "规则统计列表"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/IntentRuleStats"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/monitoring/intent-rules/{ruleId}/hits:
|
||
get:
|
||
summary: "查询意图规则命中记录"
|
||
operationId: "getIntentRuleHits"
|
||
tags:
|
||
- Monitoring
|
||
x-requirements: ["AC-ASA-55", "AC-AISVC-98"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: ruleId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: page
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 1
|
||
- name: pageSize
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 20
|
||
responses:
|
||
'200':
|
||
description: "命中记录列表"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/IntentRuleHitRecord"
|
||
pagination:
|
||
$ref: "#/components/schemas/PageInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/prompt-templates/{tplId}/preview:
|
||
post:
|
||
summary: "预览 Prompt 模板"
|
||
operationId: "previewPromptTemplate"
|
||
tags:
|
||
- Testing
|
||
x-requirements: ["AC-ASA-56", "AC-AISVC-99"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: tplId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
variables:
|
||
type: object
|
||
description: "变量测试值（key-value 对）"
|
||
additionalProperties:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: "预览结果"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/PromptTemplatePreview"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/monitoring/prompt-templates:
|
||
get:
|
||
summary: "查询 Prompt 模板监控统计"
|
||
operationId: "getPromptTemplateStats"
|
||
tags:
|
||
- Monitoring
|
||
x-requirements: ["AC-ASA-58", "AC-AISVC-100"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: scene
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: "场景标签筛选"
|
||
- name: startTime
|
||
in: query
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- name: endTime
|
||
in: query
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
responses:
|
||
'200':
|
||
description: "模板统计列表"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/PromptTemplateStats"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/script-flows/{flowId}/simulate:
|
||
post:
|
||
summary: "模拟执行话术流程"
|
||
operationId: "simulateScriptFlow"
|
||
tags:
|
||
- Testing
|
||
x-requirements: ["AC-ASA-59", "AC-AISVC-101"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: flowId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: "模拟执行结果"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ScriptFlowSimulation"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/script-flows/{flowId}/simulate/{simulationId}/next:
|
||
post:
|
||
summary: "推进话术流程模拟"
|
||
operationId: "simulateScriptFlowNext"
|
||
tags:
|
||
- Testing
|
||
x-requirements: ["AC-ASA-59", "AC-AISVC-102"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: flowId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: simulationId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [userInput]
|
||
properties:
|
||
userInput:
|
||
type: string
|
||
description: "用户模拟输入"
|
||
responses:
|
||
'200':
|
||
description: "下一步结果"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ScriptFlowSimulation"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/monitoring/script-flows:
|
||
get:
|
||
summary: "查询话术流程监控统计"
|
||
operationId: "getScriptFlowStats"
|
||
tags:
|
||
- Monitoring
|
||
x-requirements: ["AC-ASA-60", "AC-AISVC-103"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: startTime
|
||
in: query
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- name: endTime
|
||
in: query
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
responses:
|
||
'200':
|
||
description: "流程统计列表"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/ScriptFlowStats"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/monitoring/script-flows/{flowId}/executions:
|
||
get:
|
||
summary: "查询话术流程执行记录"
|
||
operationId: "getScriptFlowExecutions"
|
||
tags:
|
||
- Monitoring
|
||
x-requirements: ["AC-ASA-61", "AC-AISVC-104"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: flowId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: status
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [in_progress, completed, interrupted]
|
||
- name: page
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 1
|
||
- name: pageSize
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 20
|
||
responses:
|
||
'200':
|
||
description: "执行记录列表"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/ScriptFlowExecution"
|
||
pagination:
|
||
$ref: "#/components/schemas/PageInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/guardrails/test:
|
||
post:
|
||
summary: "测试输出护栏"
|
||
operationId: "testGuardrail"
|
||
tags:
|
||
- Testing
|
||
x-requirements: ["AC-ASA-62", "AC-AISVC-105"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [text]
|
||
properties:
|
||
text:
|
||
type: string
|
||
description: "测试文本"
|
||
responses:
|
||
'200':
|
||
description: "测试结果"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/GuardrailTestResult"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/monitoring/guardrails:
|
||
get:
|
||
summary: "查询输出护栏监控统计"
|
||
operationId: "getGuardrailStats"
|
||
tags:
|
||
- Monitoring
|
||
x-requirements: ["AC-ASA-63", "AC-AISVC-106"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: category
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum: [competitor, sensitive, political, custom]
|
||
- name: startTime
|
||
in: query
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- name: endTime
|
||
in: query
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
responses:
|
||
'200':
|
||
description: "护栏统计列表"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/GuardrailStats"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/monitoring/guardrails/{wordId}/blocks:
|
||
get:
|
||
summary: "查询禁词拦截记录"
|
||
operationId: "getGuardrailBlocks"
|
||
tags:
|
||
- Monitoring
|
||
x-requirements: ["AC-ASA-64", "AC-AISVC-107"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: wordId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: page
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 1
|
||
- name: pageSize
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 20
|
||
responses:
|
||
'200':
|
||
description: "拦截记录列表"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/GuardrailBlockRecord"
|
||
pagination:
|
||
$ref: "#/components/schemas/PageInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/monitoring/conversations:
|
||
get:
|
||
summary: "查询对话追踪列表"
|
||
operationId: "getConversations"
|
||
tags:
|
||
- Monitoring
|
||
x-requirements: ["AC-ASA-65", "AC-AISVC-108"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: startTime
|
||
in: query
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- name: endTime
|
||
in: query
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- name: ruleId
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: "意图规则 ID 筛选"
|
||
- name: templateId
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: "Prompt 模板 ID 筛选"
|
||
- name: flowId
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: "话术流程 ID 筛选"
|
||
- name: page
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 1
|
||
- name: pageSize
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
default: 20
|
||
responses:
|
||
'200':
|
||
description: "对话记录列表"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/ConversationRecord"
|
||
pagination:
|
||
$ref: "#/components/schemas/PageInfo"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/monitoring/conversations/{conversationId}:
|
||
get:
|
||
summary: "查询对话执行链路详情"
|
||
operationId: "getConversationDetail"
|
||
tags:
|
||
- Monitoring
|
||
x-requirements: ["AC-ASA-66", "AC-AISVC-109"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
- name: conversationId
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: "对话执行链路详情"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/FlowExecutionResult"
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|
||
|
||
/admin/monitoring/conversations/export:
|
||
post:
|
||
summary: "导出对话记录"
|
||
operationId: "exportConversations"
|
||
tags:
|
||
- Monitoring
|
||
x-requirements: ["AC-ASA-68", "AC-AISVC-110"]
|
||
parameters:
|
||
- $ref: "#/components/parameters/XTenantId"
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
format:
|
||
type: string
|
||
enum: [json, csv]
|
||
default: json
|
||
startTime:
|
||
type: string
|
||
format: date-time
|
||
endTime:
|
||
type: string
|
||
format: date-time
|
||
filters:
|
||
type: object
|
||
properties:
|
||
ruleId:
|
||
type: string
|
||
templateId:
|
||
type: string
|
||
flowId:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: "导出文件"
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
downloadUrl:
|
||
type: string
|
||
description: "下载链接"
|
||
text/csv:
|
||
schema:
|
||
type: string
|
||
format: binary
|
||
'401':
|
||
$ref: "#/components/responses/Unauthorized"
|
||
'403':
|
||
$ref: "#/components/responses/Forbidden"
|