openapi: 3.0.3
info:
  title: OpenKitty AgentOS API
  version: 1.0.0
  description: |
    使用 SiCurrent 钱包中创建的用户 API Key 调用 OpenKitty AgentOS。
    服务采用异步任务模型：创建对话并提交 first_message，随后轮询任务状态或订阅 SSE 事件流。
    API Key 可随时在钱包中禁用或删除。请求正文、附件和任务结果不会写入 API 访问审计日志。
servers:
  - url: https://sicurrent.com
security:
  - bearerAuth: []
  - apiKeyHeader: []
paths:
  /api/v1/agentos:
    get:
      summary: 查看服务元数据和可用工作模式
      responses:
        '200':
          description: AgentOS API 元数据
          content:
            application/json:
              schema:
                type: object
  /api/v1/agentos/agents:
    get:
      summary: 获取 AgentOS 可用 Agent 角色
      responses:
        '200':
          description: 可用 Agent 列表
  /api/v1/agentos/conversations:
    get:
      summary: 获取当前 API Key 所属账号的 AgentOS 对话
      responses:
        '200':
          description: 对话列表
    post:
      summary: 创建对话并可立即提交首个任务
      description: |
        传入 first_message 时会立即创建异步 AgentOS 任务，响应中的 task.id 用于状态轮询。
        不传 first_message 时只创建空对话。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConversationRequest'
            examples:
              general:
                summary: 通用 AgentOS 任务
                value:
                  title: 市场研究
                  first_message: 调研上海地区适合中小企业使用的智能客服产品，并给出比较表。
                  agent_mode: auto
      responses:
        '201':
          description: 对话已创建，首个任务已提交或消息已安全保存
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationTaskResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v1/agentos/conversations/{conversationId}:
    patch:
      summary: 修改对话标题
      parameters:
        - $ref: '#/components/parameters/ConversationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title]
              properties:
                title:
                  type: string
      responses:
        '200':
          description: 对话已更新
    delete:
      summary: 删除对话
      parameters:
        - $ref: '#/components/parameters/ConversationId'
      responses:
        '200':
          description: 对话已删除
  /api/v1/agentos/conversations/{conversationId}/messages:
    get:
      summary: 获取对话消息和任务结果
      parameters:
        - $ref: '#/components/parameters/ConversationId'
      responses:
        '200':
          description: 消息列表
    post:
      summary: 在现有对话中提交新任务
      parameters:
        - $ref: '#/components/parameters/ConversationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessageRequest'
      responses:
        '201':
          description: 消息已保存，任务已提交
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationTaskResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v1/agentos/conversations/{conversationId}/tasks/{taskId}:
    get:
      summary: 获取任务状态和已完成结果
      parameters:
        - $ref: '#/components/parameters/ConversationId'
        - $ref: '#/components/parameters/TaskId'
      responses:
        '200':
          description: 任务状态；完成后 message.content 为结果
  /api/v1/agentos/conversations/{conversationId}/tasks/{taskId}/events:
    get:
      summary: 订阅任务事件流
      description: 返回 text/event-stream；连接会保持到任务结束或客户端断开。
      parameters:
        - $ref: '#/components/parameters/ConversationId'
        - $ref: '#/components/parameters/TaskId'
      responses:
        '200':
          description: Server-Sent Events
          content:
            text/event-stream:
              schema:
                type: string
  /api/v1/agentos/conversations/{conversationId}/tasks/{taskId}/cancel:
    post:
      summary: 停止尚未结束的任务
      parameters:
        - $ref: '#/components/parameters/ConversationId'
        - $ref: '#/components/parameters/TaskId'
      responses:
        '200':
          description: 任务已停止
  /api/v1/agentos/attachments:
    post:
      summary: 上传 AgentOS 输入附件
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '201':
          description: 上传成功；将返回的 attachment 放入消息 attachments 数组
  /api/v1/agentos/files:
    get:
      summary: 下载当前账号 AgentOS 生成的文件
      parameters:
        - name: path
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 文件内容
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Authorization: Bearer ak_xxx'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
  parameters:
    ConversationId:
      name: conversationId
      in: path
      required: true
      schema:
        type: integer
        minimum: 1
    TaskId:
      name: taskId
      in: path
      required: true
      schema:
        type: string
        maxLength: 128
  schemas:
    Attachment:
      type: object
      required: [name, path, size]
      properties:
        name:
          type: string
        path:
          type: string
        mime_type:
          type: string
        size:
          type: integer
          format: int64
    CreateConversationRequest:
      type: object
      properties:
        title:
          type: string
          maxLength: 60
        first_message:
          type: string
          maxLength: 20000
        agent_mode:
          type: string
          enum: [auto, ppt, solution, fundraising, prospecting, project_delivery, quotation_builder, luck_rich, med_guid, mental_health, relationship_guidance, digital_employee, companion, multi_agent]
        attachments:
          type: array
          maxItems: 5
          items:
            $ref: '#/components/schemas/Attachment'
        collaboration:
          type: object
          description: multi_agent 模式的结构化协作配置
    CreateMessageRequest:
      type: object
      required: [content]
      properties:
        content:
          type: string
          maxLength: 20000
        agent_mode:
          type: string
        attachments:
          type: array
          maxItems: 5
          items:
            $ref: '#/components/schemas/Attachment'
        collaboration:
          type: object
    ConversationTaskResponse:
      type: object
      properties:
        status:
          type: string
        conversation:
          type: object
        message:
          type: object
        assistant_message:
          type: object
        task:
          type: object
          properties:
            id:
              type: string
            status:
              type: string
            phase:
              type: string
        inference_error:
          type: string
  responses:
    BadRequest:
      description: 请求内容无效
    Unauthorized:
      description: API Key 缺失、无效、已禁用或所属账号不可用
    RateLimited:
      description: 超出速率限制。响应包含 Retry-After 与 X-RateLimit-* 头。
