391 lines
11 KiB
YAML
391 lines
11 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: SmartFlow 智能体历史记录接口
|
||
version: 0.8.1
|
||
description: 最新的会话历史接口规范，包含持久化后的推理内容。
|
||
|
||
servers:
|
||
- url: http://localhost:8080
|
||
|
||
paths:
|
||
/api/v1/agent/chat:
|
||
post:
|
||
tags:
|
||
- 智能体
|
||
summary: 流式聊天回复
|
||
description: |
|
||
发起一轮智能体聊天请求。
|
||
重试仍使用同一个接口，并通过 extra 字段传递重试元数据。
|
||
security:
|
||
- BearerAuth: []
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AgentChatRequest'
|
||
examples:
|
||
normal:
|
||
value:
|
||
conversation_id: 8df59142-29a2-4bf6-85b6-c5e3f4e9cb89
|
||
message: 帮我看看明天的任务安排。
|
||
model: worker
|
||
thinking: true
|
||
extra: {}
|
||
retry:
|
||
value:
|
||
conversation_id: 8df59142-29a2-4bf6-85b6-c5e3f4e9cb89
|
||
message: 帮我看看明天的任务安排。
|
||
model: worker
|
||
thinking: true
|
||
extra:
|
||
request_mode: retry
|
||
retry_group_id: retry-group-001
|
||
retry_from_user_message_id: 123
|
||
retry_from_assistant_message_id: 456
|
||
responses:
|
||
'200':
|
||
description: SSE 流式响应
|
||
'400':
|
||
description: 请求参数非法
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
'401':
|
||
description: 未授权
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
|
||
/api/v1/agent/conversation-list:
|
||
get:
|
||
tags:
|
||
- 智能体
|
||
summary: 获取会话列表
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: page
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
example: 1
|
||
- name: page_size
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 100
|
||
example: 20
|
||
- name: limit
|
||
in: query
|
||
required: false
|
||
description: page_size 的别名。
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 100
|
||
example: 20
|
||
- name: status
|
||
in: query
|
||
required: false
|
||
schema:
|
||
type: string
|
||
enum: [active, archived]
|
||
example: active
|
||
responses:
|
||
'200':
|
||
description: 成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ConversationListEnvelope'
|
||
'400':
|
||
description: 请求参数非法
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
'401':
|
||
description: 未授权
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
|
||
/api/v1/agent/conversation-history:
|
||
get:
|
||
tags:
|
||
- 智能体
|
||
summary: 获取会话历史
|
||
description: |
|
||
返回指定会话的聊天历史。
|
||
服务会先校验归属关系，再优先读取 Redis，必要时回退到 MySQL。
|
||
reasoning_content 现已支持在缓存命中和数据库历史两种场景下返回（若可用）。
|
||
reasoning_duration_seconds 由服务端计算，并以秒为单位持久化。
|
||
重试分组通过 retry_group_id、retry_index 和 retry_total 返回。
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: conversation_id
|
||
in: query
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
example: 8df59142-29a2-4bf6-85b6-c5e3f4e9cb89
|
||
responses:
|
||
'200':
|
||
description: 成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ConversationHistoryEnvelope'
|
||
examples:
|
||
success:
|
||
value:
|
||
status: "10000"
|
||
info: 成功
|
||
data:
|
||
- id: 101
|
||
role: user
|
||
content: 帮我看看明天最重要的任务是什么。
|
||
created_at: "2026-03-24T22:15:01+08:00"
|
||
reasoning_content: ""
|
||
reasoning_duration_seconds: 0
|
||
retry_group_id: retry-group-001
|
||
retry_index: 1
|
||
retry_total: 2
|
||
- id: 102
|
||
role: assistant
|
||
content: 明天你应该优先处理数据库联调和接口校验。
|
||
created_at: "2026-03-24T22:15:06+08:00"
|
||
reasoning_content: "阶段：request.accepted\n用户请求已接收。\n\n阶段：task_query.reflecting\n正在对比检索到的任务并选择截止时间最紧的事项。"
|
||
reasoning_duration_seconds: 5
|
||
retry_group_id: retry-group-001
|
||
retry_index: 2
|
||
retry_total: 2
|
||
'400':
|
||
description: 缺少参数或会话不存在
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
'401':
|
||
description: 未授权
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
|
||
components:
|
||
securitySchemes:
|
||
BearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
|
||
schemas:
|
||
AgentChatRequest:
|
||
type: object
|
||
required:
|
||
- message
|
||
properties:
|
||
conversation_id:
|
||
type: string
|
||
format: uuid
|
||
nullable: true
|
||
message:
|
||
type: string
|
||
model:
|
||
type: string
|
||
nullable: true
|
||
example: worker
|
||
thinking:
|
||
type: boolean
|
||
example: true
|
||
extra:
|
||
$ref: '#/components/schemas/AgentChatExtra'
|
||
|
||
AgentChatExtra:
|
||
type: object
|
||
additionalProperties: true
|
||
properties:
|
||
request_mode:
|
||
type: string
|
||
description: 当需要重新生成上一版回答时，使用 retry。
|
||
example: retry
|
||
retry_group_id:
|
||
type: string
|
||
nullable: true
|
||
example: retry-group-001
|
||
retry_from_user_message_id:
|
||
type: integer
|
||
nullable: true
|
||
example: 123
|
||
retry_from_assistant_message_id:
|
||
type: integer
|
||
nullable: true
|
||
example: 456
|
||
|
||
ErrorResponse:
|
||
type: object
|
||
required:
|
||
- status
|
||
- info
|
||
properties:
|
||
status:
|
||
type: string
|
||
example: "40005"
|
||
info:
|
||
type: string
|
||
example: 参数类型错误
|
||
|
||
ConversationListEnvelope:
|
||
type: object
|
||
required:
|
||
- status
|
||
- info
|
||
- data
|
||
properties:
|
||
status:
|
||
type: string
|
||
example: "10000"
|
||
info:
|
||
type: string
|
||
example: 成功
|
||
data:
|
||
$ref: '#/components/schemas/ConversationListResponse'
|
||
|
||
ConversationListResponse:
|
||
type: object
|
||
required:
|
||
- list
|
||
- page
|
||
- page_size
|
||
- limit
|
||
- total
|
||
- has_more
|
||
properties:
|
||
list:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ConversationListItem'
|
||
page:
|
||
type: integer
|
||
example: 1
|
||
page_size:
|
||
type: integer
|
||
example: 20
|
||
limit:
|
||
type: integer
|
||
example: 20
|
||
total:
|
||
type: integer
|
||
format: int64
|
||
example: 56
|
||
has_more:
|
||
type: boolean
|
||
example: true
|
||
|
||
ConversationListItem:
|
||
type: object
|
||
required:
|
||
- conversation_id
|
||
- title
|
||
- has_title
|
||
- message_count
|
||
- status
|
||
properties:
|
||
conversation_id:
|
||
type: string
|
||
format: uuid
|
||
title:
|
||
type: string
|
||
example: 明日任务复盘
|
||
has_title:
|
||
type: boolean
|
||
example: true
|
||
message_count:
|
||
type: integer
|
||
example: 14
|
||
last_message_at:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
status:
|
||
type: string
|
||
example: active
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
|
||
ConversationHistoryEnvelope:
|
||
type: object
|
||
required:
|
||
- status
|
||
- info
|
||
- data
|
||
properties:
|
||
status:
|
||
type: string
|
||
example: "10000"
|
||
info:
|
||
type: string
|
||
example: 成功
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ConversationHistoryItem'
|
||
|
||
ConversationHistoryItem:
|
||
type: object
|
||
required:
|
||
- role
|
||
- content
|
||
properties:
|
||
id:
|
||
type: integer
|
||
description: 数据库主键。纯缓存命中场景下可能为空。
|
||
example: 102
|
||
role:
|
||
type: string
|
||
enum: [user, assistant, system]
|
||
example: assistant
|
||
content:
|
||
type: string
|
||
example: 明天你应该优先处理数据库联调和接口校验。
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
nullable: true
|
||
reasoning_content:
|
||
type: string
|
||
description: 聚合后的推理文本，包含模型流式推理内容或阶段级思考文本。
|
||
example: "阶段：request.accepted\n用户请求已接收。"
|
||
reasoning_duration_seconds:
|
||
type: integer
|
||
description: 由服务端计算的推理耗时，单位为秒。
|
||
example: 5
|
||
retry_group_id:
|
||
type: string
|
||
nullable: true
|
||
description: 原始回答与所有重试版本共享的重试分组标识。
|
||
example: retry-group-001
|
||
retry_index:
|
||
type: integer
|
||
nullable: true
|
||
description: 在重试分组内的版本序号，从 1 开始。
|
||
example: 2
|
||
retry_total:
|
||
type: integer
|
||
nullable: true
|
||
description: 当前重试分组内的总版本数。
|
||
example: 2
|