agent-Specialization/api_doc/openapi.yaml

openapi: 3.0.3
info:
  title: Agents API v1
  version: "1.0"
  description: |
    后台任务 + HTTP 轮询进度 + 文件上传/下载。

    - 鉴权：Authorization: Bearer <token>（token 为自定义字符串，服务端存 SHA256）
    - 事件流：与网页端 WebSocket 同粒度（text_chunk、tool_start 等）    
servers:
  - url: http://localhost:8091

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
  schemas:
    ErrorResponse:
      type: object
      properties:
        success: { type: boolean, example: false }
        error: { type: string, example: "无效的 Token" }
      required: [success, error]

    CreateConversationResponse:
      type: object
      properties:
        success: { type: boolean, example: true }
        conversation_id: { type: string, example: "conv_20260123_234245_036" }
      required: [success, conversation_id]

    SendMessageRequest:
      type: object
      properties:
        message:
          type: string
          description: 用户消息文本（message 与 images 至少其一不为空）
        images:
          type: array
          items: { type: string }
          description: 图片路径列表（相对 project 根目录）
        conversation_id:
          type: string
          description: 对话 ID；不传则自动创建
        model_key:
          type: string
          nullable: true
          description: 模型 key（可选，取决于服务端配置）
        run_mode:
          type: string
          nullable: true
          description: 运行模式：fast | thinking | deep；若传入则优先使用
        thinking_mode:
          type: boolean
          nullable: true
          description: 是否开启思考模式（true/false）
        max_iterations:
          type: integer
          nullable: true
          description: 最大迭代次数（最多允许多少轮模型调用/工具循环）
      additionalProperties: false

    SendMessageResponse:
      type: object
      properties:
        success: { type: boolean, example: true }
        task_id: { type: string, example: "60322db3-f884-4a1e-a9b3-6eeb07fbab47" }
        conversation_id: { type: string, example: "conv_20260123_234245_036" }
        status: { type: string, example: "running" }
        created_at: { type: number, format: double, example: 1769182965.3038778 }
      required: [success, task_id, conversation_id, status, created_at]

    TaskEvent:
      type: object
      properties:
        idx: { type: integer, example: 12 }
        type: { type: string, example: "text_chunk" }
        data:
          type: object
          additionalProperties: true
        ts: { type: number, format: double, example: 1769182968.154797 }
      required: [idx, type, data, ts]

    TaskPollResponse:
      type: object
      properties:
        success: { type: boolean, example: true }
        data:
          type: object
          properties:
            task_id: { type: string }
            status: { type: string, example: "running" }
            created_at: { type: number, format: double }
            updated_at: { type: number, format: double }
            error: { type: string, nullable: true }
            events:
              type: array
              items: { $ref: "#/components/schemas/TaskEvent" }
            next_offset: { type: integer, example: 3 }
          required: [task_id, status, created_at, updated_at, error, events, next_offset]
      required: [success, data]

    CancelResponse:
      type: object
      properties:
        success: { type: boolean, example: true }
      required: [success]

    UploadResponse:
      type: object
      properties:
        success: { type: boolean, example: true }
        path: { type: string, example: "inputs/hello.txt" }
        filename: { type: string, example: "hello.txt" }
        size: { type: integer, example: 16 }
        sha256: { type: string, example: "0f5bd6..." }
      required: [success, path, filename]

    ListFilesItem:
      type: object
      properties:
        name: { type: string, example: "hello.txt" }
        is_dir: { type: boolean, example: false }
        size: { type: integer, example: 16 }
        modified_at: { type: number, format: double, example: 1769182550.594278 }
        path: { type: string, example: "inputs/hello.txt" }
      required: [name, is_dir, size, modified_at, path]

    ListFilesResponse:
      type: object
      properties:
        success: { type: boolean, example: true }
        base: { type: string, example: "." }
        items:
          type: array
          items: { $ref: "#/components/schemas/ListFilesItem" }
      required: [success, base, items]

security:
  - bearerAuth: []

paths:
  /api/v1/conversations:
    post:
      summary: 创建对话
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/CreateConversationResponse" }
        "401":
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }

  /api/v1/messages:
    post:
      summary: 发送消息并创建后台任务
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/SendMessageRequest" }
      responses:
        "202":
          description: Accepted
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SendMessageResponse" }
        "400":
          description: Bad Request
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }
        "401":
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }
        "409":
          description: Conflict (已有运行任务)
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }

  /api/v1/tasks/{task_id}:
    get:
      summary: 轮询任务事件
      security: [{ bearerAuth: [] }]
      parameters:
        - in: path
          name: task_id
          required: true
          schema: { type: string }
        - in: query
          name: from
          required: false
          schema: { type: integer, default: 0 }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/TaskPollResponse" }
        "401":
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }
        "404":
          description: Not Found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }

  /api/v1/tasks/{task_id}/cancel:
    post:
      summary: 请求停止任务
      security: [{ bearerAuth: [] }]
      parameters:
        - in: path
          name: task_id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/CancelResponse" }
        "401":
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }
        "404":
          description: Not Found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }

  /api/v1/files/upload:
    post:
      summary: 上传文件到 user_upload
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                filename:
                  type: string
                dir:
                  type: string
                  description: user_upload 下子目录
              required: [file]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/UploadResponse" }
        "400":
          description: Bad Request
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }
        "401":
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }

  /api/v1/files:
    get:
      summary: 列出 user_upload 目录内容
      security: [{ bearerAuth: [] }]
      parameters:
        - in: query
          name: path
          required: false
          schema: { type: string, default: "" }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ListFilesResponse" }
        "400":
          description: Bad Request
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }
        "401":
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }
        "404":
          description: Not Found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }

  /api/v1/files/download:
    get:
      summary: 下载文件或目录（目录会打包成 zip）
      security: [{ bearerAuth: [] }]
      parameters:
        - in: query
          name: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
            application/zip:
              schema:
                type: string
                format: binary
        "400":
          description: Bad Request
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }
        "401":
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }
        "404":
          description: Not Found
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }