mirror of
https://github.com/xinnan-tech/xiaozhi-esp32-server.git
synced 2026-07-25 00:23:53 +08:00
1087 lines
27 KiB
YAML
1087 lines
27 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: 小智ESP32后端服务API
|
|
description: |
|
|
小智ESP32智能硬件后端管理服务API文档
|
|
|
|
## 认证方式
|
|
- JWT Bearer Token认证
|
|
- 通过 `/user/login` 接口获取token
|
|
|
|
## 权限级别
|
|
- `sys:role:normal`: 普通用户权限
|
|
- `sys:role:superAdmin`: 超级管理员权限
|
|
version: 1.0.0
|
|
contact:
|
|
name: 小智ESP32项目组
|
|
license:
|
|
name: MIT
|
|
|
|
servers:
|
|
- url: http://localhost:8002
|
|
description: 本地开发环境
|
|
- url: https://api.xiaozhi.com
|
|
description: 生产环境
|
|
|
|
security:
|
|
- BearerAuth: []
|
|
|
|
paths:
|
|
# =================== 认证相关 ===================
|
|
/user/login:
|
|
post:
|
|
tags:
|
|
- 用户认证
|
|
summary: 用户登录
|
|
description: 用户登录获取JWT令牌
|
|
operationId: userLogin
|
|
security: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/LoginDTO'
|
|
responses:
|
|
'200':
|
|
description: 登录成功
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Result'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
$ref: '#/components/schemas/TokenDTO'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
|
|
/user/register:
|
|
post:
|
|
tags:
|
|
- 用户认证
|
|
summary: 用户注册
|
|
operationId: userRegister
|
|
security: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/LoginDTO'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Success'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
|
|
/user/info:
|
|
get:
|
|
tags:
|
|
- 用户认证
|
|
summary: 获取当前用户信息
|
|
operationId: getUserInfo
|
|
responses:
|
|
'200':
|
|
description: 用户信息
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Result'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
$ref: '#/components/schemas/UserDetail'
|
|
|
|
/user/captcha:
|
|
get:
|
|
tags:
|
|
- 用户认证
|
|
summary: 获取图片验证码
|
|
operationId: getCaptcha
|
|
security: []
|
|
parameters:
|
|
- name: uuid
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: uuid-12345
|
|
responses:
|
|
'200':
|
|
description: 验证码图片
|
|
content:
|
|
image/jpeg:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
|
|
# =================== 智能体管理 ===================
|
|
/agent/list:
|
|
get:
|
|
tags:
|
|
- 智能体管理
|
|
summary: 获取用户智能体列表
|
|
operationId: getUserAgentList
|
|
responses:
|
|
'200':
|
|
description: 智能体列表
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Result'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/AgentDTO'
|
|
|
|
/agent:
|
|
post:
|
|
tags:
|
|
- 智能体管理
|
|
summary: 创建智能体
|
|
operationId: createAgent
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AgentCreateDTO'
|
|
responses:
|
|
'200':
|
|
description: 创建成功，返回智能体ID
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Result'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: string
|
|
example: AGT_1234567890
|
|
|
|
/agent/{id}:
|
|
get:
|
|
tags:
|
|
- 智能体管理
|
|
summary: 获取智能体详情
|
|
operationId: getAgentDetails
|
|
parameters:
|
|
- $ref: '#/components/parameters/AgentId'
|
|
responses:
|
|
'200':
|
|
description: 智能体详情
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Result'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
$ref: '#/components/schemas/AgentInfoVO'
|
|
|
|
put:
|
|
tags:
|
|
- 智能体管理
|
|
summary: 更新智能体
|
|
operationId: updateAgent
|
|
parameters:
|
|
- $ref: '#/components/parameters/AgentId'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AgentUpdateDTO'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Success'
|
|
|
|
delete:
|
|
tags:
|
|
- 智能体管理
|
|
summary: 删除智能体
|
|
operationId: deleteAgent
|
|
parameters:
|
|
- $ref: '#/components/parameters/AgentId'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Success'
|
|
|
|
/agent/saveMemory/{macAddress}:
|
|
put:
|
|
tags:
|
|
- 智能体管理
|
|
summary: 更新智能体记忆
|
|
operationId: updateAgentMemory
|
|
parameters:
|
|
- name: macAddress
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: 'AA:BB:CC:DD:EE:FF'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AgentMemoryDTO'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Success'
|
|
|
|
/agent/template:
|
|
get:
|
|
tags:
|
|
- 智能体管理
|
|
summary: 获取智能体模板列表
|
|
operationId: getAgentTemplates
|
|
responses:
|
|
'200':
|
|
description: 模板列表
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Result'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/AgentTemplateEntity'
|
|
|
|
# =================== 设备管理 ===================
|
|
/device/register:
|
|
post:
|
|
tags:
|
|
- 设备管理
|
|
summary: 设备注册
|
|
operationId: registerDevice
|
|
security: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DeviceRegisterDTO'
|
|
responses:
|
|
'200':
|
|
description: 注册成功，返回验证码
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Result'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: string
|
|
example: '123456'
|
|
description: 6位数验证码
|
|
|
|
/device/bind/{agentId}/{deviceCode}:
|
|
post:
|
|
tags:
|
|
- 设备管理
|
|
summary: 绑定设备到智能体
|
|
operationId: bindDevice
|
|
parameters:
|
|
- $ref: '#/components/parameters/AgentId'
|
|
- name: deviceCode
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: '123456'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Success'
|
|
|
|
/device/bind/{agentId}:
|
|
get:
|
|
tags:
|
|
- 设备管理
|
|
summary: 获取智能体绑定的设备列表
|
|
operationId: getBoundDevices
|
|
parameters:
|
|
- $ref: '#/components/parameters/AgentId'
|
|
responses:
|
|
'200':
|
|
description: 绑定设备列表
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Result'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/DeviceEntity'
|
|
|
|
/device/unbind:
|
|
post:
|
|
tags:
|
|
- 设备管理
|
|
summary: 解绑设备
|
|
operationId: unbindDevice
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DeviceUnBindDTO'
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Success'
|
|
|
|
# =================== OTA管理 ===================
|
|
/ota/:
|
|
post:
|
|
tags:
|
|
- OTA管理
|
|
summary: 设备OTA检查
|
|
operationId: checkOTA
|
|
security: []
|
|
parameters:
|
|
- name: Device-Id
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: device123
|
|
- name: Client-Id
|
|
in: header
|
|
schema:
|
|
type: string
|
|
example: client456
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DeviceReportReqDTO'
|
|
responses:
|
|
'200':
|
|
description: OTA检查结果
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Result'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
$ref: '#/components/schemas/DeviceReportRespDTO'
|
|
|
|
get:
|
|
tags:
|
|
- OTA管理
|
|
summary: 获取OTA状态
|
|
operationId: getOTAStatus
|
|
security: []
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Success'
|
|
|
|
/ota/activate:
|
|
post:
|
|
tags:
|
|
- OTA管理
|
|
summary: 设备快速激活检查
|
|
operationId: quickActivateCheck
|
|
security: []
|
|
parameters:
|
|
- name: Device-Id
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: Client-Id
|
|
in: header
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
$ref: '#/components/responses/Success'
|
|
|
|
# =================== 模型管理 ===================
|
|
/models/names:
|
|
get:
|
|
tags:
|
|
- 模型管理
|
|
summary: 获取模型名称列表
|
|
operationId: getModelNames
|
|
parameters:
|
|
- name: modelType
|
|
in: query
|
|
schema:
|
|
type: string
|
|
example: LLM
|
|
- name: modelName
|
|
in: query
|
|
schema:
|
|
type: string
|
|
example: ChatGLM
|
|
responses:
|
|
'200':
|
|
description: 模型名称列表
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Result'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ModelBasicInfoDTO'
|
|
|
|
/models/{modelType}/provideTypes:
|
|
get:
|
|
tags:
|
|
- 模型管理
|
|
summary: 获取模型提供商类型
|
|
operationId: getModelProviderTypes
|
|
security:
|
|
- BearerAuth: ['sys:role:superAdmin']
|
|
parameters:
|
|
- name: modelType
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: LLM
|
|
responses:
|
|
'200':
|
|
description: 提供商类型列表
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Result'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ModelProviderDTO'
|
|
|
|
/models/list:
|
|
get:
|
|
tags:
|
|
- 模型管理
|
|
summary: 获取模型配置列表
|
|
operationId: getModelConfigList
|
|
security:
|
|
- BearerAuth: ['sys:role:superAdmin']
|
|
parameters:
|
|
- name: modelType
|
|
in: query
|
|
schema:
|
|
type: string
|
|
- name: modelName
|
|
in: query
|
|
schema:
|
|
type: string
|
|
- $ref: '#/components/parameters/Page'
|
|
- $ref: '#/components/parameters/Limit'
|
|
responses:
|
|
'200':
|
|
description: 模型配置分页列表
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Result'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
$ref: '#/components/schemas/PageData'
|
|
|
|
# =================== 服务端管理 ===================
|
|
/admin/server/server-list:
|
|
get:
|
|
tags:
|
|
- 服务端管理
|
|
summary: 获取WebSocket服务器列表
|
|
operationId: getWebSocketServerList
|
|
security:
|
|
- BearerAuth: ['sys:role:superAdmin']
|
|
responses:
|
|
'200':
|
|
description: WebSocket服务器地址列表
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Result'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example:
|
|
- 'ws://192.168.1.100:8000/xiaozhi/v1/'
|
|
- 'ws://192.168.1.101:8000/xiaozhi/v1/'
|
|
|
|
/admin/server/emit-action:
|
|
post:
|
|
tags:
|
|
- 服务端管理
|
|
summary: 通知Python服务端更新配置
|
|
description: 向指定WebSocket服务端发送操作指令，如重启服务或更新配置
|
|
operationId: emitServerAction
|
|
security:
|
|
- BearerAuth: ['sys:role:superAdmin']
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/EmitSeverActionDTO'
|
|
responses:
|
|
'200':
|
|
description: 操作执行成功
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Result'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: boolean
|
|
example: true
|
|
'400':
|
|
description: 请求参数错误或目标WebSocket地址无效
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Result'
|
|
- type: object
|
|
properties:
|
|
code:
|
|
example: 400
|
|
msg:
|
|
example: 目标WebSocket地址不存在
|
|
'500':
|
|
description: WebSocket连接失败
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Result'
|
|
- type: object
|
|
properties:
|
|
code:
|
|
example: 500
|
|
msg:
|
|
example: WebSocket连接失败或连接超时
|
|
|
|
components:
|
|
securitySchemes:
|
|
BearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
|
|
parameters:
|
|
AgentId:
|
|
name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
example: AGT_1234567890
|
|
|
|
Page:
|
|
name: page
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 1
|
|
example: 1
|
|
|
|
Limit:
|
|
name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 10
|
|
example: 10
|
|
|
|
responses:
|
|
Success:
|
|
description: 操作成功
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Result'
|
|
example:
|
|
code: 200
|
|
msg: success
|
|
data: null
|
|
|
|
BadRequest:
|
|
description: 请求参数错误
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Result'
|
|
example:
|
|
code: 400
|
|
msg: 参数错误
|
|
data: null
|
|
|
|
Unauthorized:
|
|
description: 未授权
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Result'
|
|
example:
|
|
code: 401
|
|
msg: 未授权，请先登录
|
|
data: null
|
|
|
|
schemas:
|
|
# =================== 通用响应结构 ===================
|
|
Result:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: integer
|
|
description: 响应码
|
|
example: 200
|
|
msg:
|
|
type: string
|
|
description: 响应消息
|
|
example: success
|
|
data:
|
|
description: 响应数据
|
|
required:
|
|
- code
|
|
- msg
|
|
|
|
PageData:
|
|
type: object
|
|
properties:
|
|
total:
|
|
type: integer
|
|
description: 总记录数
|
|
example: 100
|
|
list:
|
|
type: array
|
|
description: 数据列表
|
|
items:
|
|
type: object
|
|
required:
|
|
- total
|
|
- list
|
|
|
|
# =================== 认证相关 ===================
|
|
LoginDTO:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
description: 手机号码
|
|
example: '13800138000'
|
|
password:
|
|
type: string
|
|
description: 密码
|
|
example: password123
|
|
captcha:
|
|
type: string
|
|
description: 图片验证码
|
|
example: AB3C
|
|
mobileCaptcha:
|
|
type: string
|
|
description: 短信验证码
|
|
example: '123456'
|
|
captchaId:
|
|
type: string
|
|
description: 验证码唯一标识
|
|
example: uuid-captcha-id-12345
|
|
required:
|
|
- username
|
|
- password
|
|
- captcha
|
|
- captchaId
|
|
|
|
TokenDTO:
|
|
type: object
|
|
properties:
|
|
token:
|
|
type: string
|
|
description: JWT访问令牌
|
|
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
|
expire:
|
|
type: integer
|
|
format: int64
|
|
description: 过期时间戳(毫秒)
|
|
example: 1640995200000
|
|
required:
|
|
- token
|
|
- expire
|
|
|
|
UserDetail:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
example: USER_123
|
|
username:
|
|
type: string
|
|
example: '13800138000'
|
|
mobile:
|
|
type: string
|
|
example: '13800138000'
|
|
email:
|
|
type: string
|
|
example: user@example.com
|
|
realName:
|
|
type: string
|
|
example: 张三
|
|
avatar:
|
|
type: string
|
|
example: 'https://example.com/avatar.jpg'
|
|
status:
|
|
type: integer
|
|
example: 1
|
|
createDate:
|
|
type: string
|
|
format: date-time
|
|
example: '2023-01-01T00:00:00Z'
|
|
|
|
# =================== 智能体相关 ===================
|
|
AgentCreateDTO:
|
|
type: object
|
|
properties:
|
|
agentName:
|
|
type: string
|
|
description: 智能体名称
|
|
example: 客服助手
|
|
required:
|
|
- agentName
|
|
|
|
AgentUpdateDTO:
|
|
type: object
|
|
properties:
|
|
agentCode:
|
|
type: string
|
|
description: 智能体编码
|
|
example: AGT_1234567890
|
|
agentName:
|
|
type: string
|
|
description: 智能体名称
|
|
example: 客服助手Pro
|
|
asrModelId:
|
|
type: string
|
|
description: 语音识别模型ID
|
|
example: asr_model_02
|
|
vadModelId:
|
|
type: string
|
|
description: 语音活动检测模型ID
|
|
example: vad_model_02
|
|
llmModelId:
|
|
type: string
|
|
description: 大语言模型ID
|
|
example: llm_model_02
|
|
vllmModelId:
|
|
type: string
|
|
description: 视觉语言模型ID
|
|
example: vllm_model_02
|
|
ttsModelId:
|
|
type: string
|
|
description: 语音合成模型ID
|
|
example: tts_model_02
|
|
ttsVoiceId:
|
|
type: string
|
|
description: 音色ID
|
|
example: voice_02
|
|
memModelId:
|
|
type: string
|
|
description: 记忆模型ID
|
|
example: mem_model_02
|
|
intentModelId:
|
|
type: string
|
|
description: 意图识别模型ID
|
|
example: intent_model_02
|
|
functions:
|
|
type: array
|
|
description: 插件函数配置列表
|
|
items:
|
|
$ref: '#/components/schemas/FunctionInfo'
|
|
systemPrompt:
|
|
type: string
|
|
description: 系统提示词/角色设定
|
|
example: 你是一个专业的客服助手，负责回答用户问题并提供帮助。
|
|
summaryMemory:
|
|
type: string
|
|
description: 记忆总结配置
|
|
example: 根据对话记录，总结user的重要信息，以便在未来的对话中提供更个性化的服务。
|
|
chatHistoryConf:
|
|
type: integer
|
|
description: 聊天记录配置 (0=不记录, 1=仅文本, 2=文本+语音)
|
|
example: 2
|
|
langCode:
|
|
type: string
|
|
description: 语言编码
|
|
example: zh_CN
|
|
language:
|
|
type: string
|
|
description: 交互语言名称
|
|
example: 中文
|
|
sort:
|
|
type: integer
|
|
description: 排序值
|
|
example: 1
|
|
|
|
FunctionInfo:
|
|
type: object
|
|
properties:
|
|
pluginId:
|
|
type: string
|
|
description: 插件ID
|
|
example: weather_plugin
|
|
paramInfo:
|
|
type: object
|
|
description: 插件参数配置
|
|
additionalProperties: true
|
|
example:
|
|
api_key: your_api_key
|
|
default_location: 北京
|
|
|
|
AgentMemoryDTO:
|
|
type: object
|
|
properties:
|
|
summaryMemory:
|
|
type: string
|
|
description: 记忆摘要内容
|
|
example: 用户喜欢听音乐，经常询问天气信息。
|
|
required:
|
|
- summaryMemory
|
|
|
|
AgentDTO:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
example: AGT_1234567890
|
|
agentCode:
|
|
type: string
|
|
example: AGT_1234567890
|
|
agentName:
|
|
type: string
|
|
example: 客服助手
|
|
systemPrompt:
|
|
type: string
|
|
example: 你是一个专业的客服助手
|
|
createDate:
|
|
type: string
|
|
format: date-time
|
|
|
|
AgentInfoVO:
|
|
allOf:
|
|
- $ref: '#/components/schemas/AgentDTO'
|
|
- type: object
|
|
properties:
|
|
asrModelName:
|
|
type: string
|
|
example: FunASR
|
|
llmModelName:
|
|
type: string
|
|
example: ChatGLM
|
|
ttsModelName:
|
|
type: string
|
|
example: EdgeTTS
|
|
|
|
AgentTemplateEntity:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
example: TPL_001
|
|
templateName:
|
|
type: string
|
|
example: 客服助手模板
|
|
systemPrompt:
|
|
type: string
|
|
example: 你是一个专业的客服助手
|
|
description:
|
|
type: string
|
|
example: 适用于客服场景的智能助手模板
|
|
|
|
# =================== 设备相关 ===================
|
|
DeviceRegisterDTO:
|
|
type: object
|
|
properties:
|
|
macAddress:
|
|
type: string
|
|
description: 设备MAC地址
|
|
example: 'AA:BB:CC:DD:EE:FF'
|
|
required:
|
|
- macAddress
|
|
|
|
DeviceUnBindDTO:
|
|
type: object
|
|
properties:
|
|
deviceId:
|
|
type: string
|
|
description: 设备ID
|
|
example: DEV_123456
|
|
agentId:
|
|
type: string
|
|
description: 智能体ID
|
|
example: AGT_1234567890
|
|
required:
|
|
- deviceId
|
|
- agentId
|
|
|
|
DeviceEntity:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
example: DEV_123456
|
|
deviceName:
|
|
type: string
|
|
example: 客厅音箱
|
|
macAddress:
|
|
type: string
|
|
example: 'AA:BB:CC:DD:EE:FF'
|
|
deviceType:
|
|
type: string
|
|
example: ESP32
|
|
status:
|
|
type: integer
|
|
example: 1
|
|
createDate:
|
|
type: string
|
|
format: date-time
|
|
|
|
DeviceReportReqDTO:
|
|
type: object
|
|
properties:
|
|
version:
|
|
type: string
|
|
example: 1.0.0
|
|
deviceType:
|
|
type: string
|
|
example: ESP32
|
|
macAddress:
|
|
type: string
|
|
example: 'AA:BB:CC:DD:EE:FF'
|
|
|
|
DeviceReportRespDTO:
|
|
type: object
|
|
properties:
|
|
hasUpdate:
|
|
type: boolean
|
|
example: true
|
|
version:
|
|
type: string
|
|
example: 1.0.1
|
|
downloadUrl:
|
|
type: string
|
|
example: 'https://example.com/firmware.bin'
|
|
updateMessage:
|
|
type: string
|
|
example: 修复了音频处理bug
|
|
|
|
# =================== 模型相关 ===================
|
|
ModelBasicInfoDTO:
|
|
type: object
|
|
properties:
|
|
modelId:
|
|
type: string
|
|
example: llm_model_01
|
|
modelName:
|
|
type: string
|
|
example: ChatGLM-4
|
|
modelType:
|
|
type: string
|
|
example: LLM
|
|
providerName:
|
|
type: string
|
|
example: 智谱AI
|
|
isDefault:
|
|
type: boolean
|
|
example: true
|
|
status:
|
|
type: integer
|
|
example: 1
|
|
|
|
ModelProviderDTO:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
example: PROV_001
|
|
providerCode:
|
|
type: string
|
|
example: chatglm
|
|
providerName:
|
|
type: string
|
|
example: 智谱AI
|
|
description:
|
|
type: string
|
|
example: 智谱AI大模型服务商
|
|
apiEndpoint:
|
|
type: string
|
|
example: 'https://open.bigmodel.cn/api/paas/v4/'
|
|
|
|
# =================== 服务端管理相关 ===================
|
|
EmitSeverActionDTO:
|
|
type: object
|
|
properties:
|
|
targetWs:
|
|
type: string
|
|
description: 目标WebSocket服务器地址
|
|
example: 'ws://192.168.1.100:8000/xiaozhi/v1/'
|
|
action:
|
|
$ref: '#/components/schemas/ServerActionEnum'
|
|
required:
|
|
- targetWs
|
|
- action
|
|
|
|
ServerActionEnum:
|
|
type: string
|
|
enum:
|
|
- restart
|
|
- update_config
|
|
description: |
|
|
服务端操作类型:
|
|
- restart: 重启服务
|
|
- update_config: 更新配置
|
|
example: update_config
|
|
|
|
tags:
|
|
- name: 用户认证
|
|
description: 用户登录、注册、认证相关接口
|
|
- name: 智能体管理
|
|
description: 智能体的创建、配置、管理相关接口
|
|
- name: 设备管理
|
|
description: 设备注册、绑定、管理相关接口
|
|
- name: OTA管理
|
|
description: 固件更新、设备激活相关接口
|
|
- name: 模型管理
|
|
description: AI模型配置、管理相关接口
|
|
- name: 服务端管理
|
|
description: 服务端状态、配置管理相关接口
|