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