emoon-backend/docs/api/openapi/医梦AI中台开放平台接口-v1.2.openapi.yaml

openapi: 3.0.3
info:
  title: EMOON AI OpenPlatform External API
  version: 1.2.3
  description: 医梦 AI 中台对外接口契约 v1.2.3，正式联调基准版。P0/P1 为厂商联调主基线；P2 为受控规划接口。FHIR 映射从主 YAML 移出，避免误解为当前交付承诺。统一入口客户端调用 Agent 时可不传 agentId，由后端 AgentRouter 结合设备、场景、感知上下文和服务端推导的动线阶段决定最终智能体。
servers:
- url: https://api.{hospital}.emoon.local/api/v1
  variables:
    hospital:
      default: demo
- url: https://sandbox-api.emoon-ai.com/api/v1
security:
- BearerAuth: []
- HmacAuth: []
tags:
- name: Auth
- name: Platform
- name: Agent
- name: Conversation
- name: File
- name: Device
- name: Card
- name: MCP Tool
- name: Webhook
- name: Event
- name: Usage
- name: License
- name: Partner
- name: Contract
- name: Credit
- name: Billing
- name: Operation
- name: Audit
paths:
  /auth/token:
    post:
      summary: 获取短期访问 Token
      tags:
      - Auth
      x-emoon-priority: P0
      description: client_credentials 模式。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseToken'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /health:
    get:
      summary: 平台健康检查
      tags:
      - Platform
      x-emoon-priority: P0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseHealth'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /capabilities:
    get:
      summary: 查询项目已开通能力
      tags:
      - Platform
      x-emoon-priority: P0
      parameters: &id005
      - &id001
        $ref: '#/components/parameters/ProjectId'
      - &id002
        $ref: '#/components/parameters/PartnerId'
      - &id003
        $ref: '#/components/parameters/TraceId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseCapabilities'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agent/chat:
    post:
      summary: 智能体同步对话
      tags:
      - Agent
      x-emoon-priority: P0
      description: 首轮 conversationId 可为空，平台自动创建会话并返回。支持 Bearer Token；HMAC 模式需携带 X-Emoon-Timestamp、X-Emoon-Nonce、X-Emoon-Signature。
      parameters: &id004
      - *id001
      - *id002
      - *id003
      - &id006
        $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentChatRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseAgentChat'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agent/chat/stream:
    post:
      summary: 智能体流式对话 SSE
      tags:
      - Agent
      x-emoon-priority: P0
      description: POST + text/event-stream。断线后使用 conversationId 查询最终消息。
      parameters: *id004
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentChatRequest'
      responses:
        '200':
          description: SSE stream
          content:
            text/event-stream:
              schema:
                type: string
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations:
    post:
      summary: 创建会话
      tags:
      - Conversation
      x-emoon-priority: P0
      parameters: *id005
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationCreateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseConversation'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      summary: 查询会话列表
      tags:
      - Conversation
      x-emoon-priority: P1
      parameters:
      - *id001
      - *id002
      - *id003
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseConversationList'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/{conversationId}:
    get:
      summary: 查询会话详情
      tags:
      - Conversation
      x-emoon-priority: P0
      parameters:
      - $ref: '#/components/parameters/ConversationIdPath'
      - *id001
      - *id002
      - *id003
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseConversation'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/{conversationId}/messages:
    get:
      summary: 查询会话消息
      tags:
      - Conversation
      x-emoon-priority: P0
      parameters:
      - $ref: '#/components/parameters/ConversationIdPath'
      - *id001
      - *id002
      - *id003
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseMessageList'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /files/upload:
    post:
      summary: 上传图片/音频/文档
      tags:
      - File
      x-emoon-priority: P0
      description: multipart/form-data 上传，返回 fileId；后续 Agent 调用只传 fileId。
      parameters: *id004
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseFileUpload'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/FileUploadRequest'
  /files/{fileId}:
    get:
      summary: 查询文件元数据
      tags:
      - File
      x-emoon-priority: P0
      parameters:
      - $ref: '#/components/parameters/FileIdPath'
      - *id001
      - *id002
      - *id003
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseFileMeta'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: 删除或作废文件
      tags:
      - File
      x-emoon-priority: P1
      description: 删除或作废授权范围内未被锁定的文件。DELETE 本身应保持幂等；正式厂商联调要求传 X-Emoon-Idempotency-Key。同一文件重复删除返回首次处理结果或当前已删除状态。
      parameters:
      - $ref: '#/components/parameters/FileIdPath'
      - *id001
      - *id002
      - *id003
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /devices/register:
    post:
      summary: 设备注册或激活
      tags:
      - Device
      x-emoon-priority: P0
      parameters: *id005
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceRegisterRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseDeviceRegister'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /devices/{deviceId}/heartbeat:
    post:
      summary: 设备心跳
      tags:
      - Device
      x-emoon-priority: P0
      parameters:
      - $ref: '#/components/parameters/DeviceIdPath'
      - *id001
      - *id002
      - *id003
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceHeartbeatRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseDeviceHeartbeat'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /devices/{deviceId}/scene:
    get:
      summary: 获取设备当前场景配置
      tags:
      - Device
      x-emoon-priority: P0
      parameters:
      - $ref: '#/components/parameters/DeviceIdPath'
      - *id001
      - *id002
      - *id003
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseDeviceScene'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      summary: 更新设备场景绑定
      tags:
      - Device
      x-emoon-priority: P1
      parameters:
      - $ref: '#/components/parameters/DeviceIdPath'
      - *id001
      - *id002
      - *id003
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceSceneUpdateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseDeviceScene'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /devices/{deviceId}/events:
    post:
      summary: 上报设备事件
      tags:
      - Device
      x-emoon-priority: P0
      description: 异步事件，正常返回 202 Accepted。
      parameters:
      - $ref: '#/components/parameters/DeviceIdPath'
      - *id001
      - *id002
      - *id003
      - *id006
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceEventRequest'
      responses:
        '202':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseAccepted'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      summary: 查询设备事件
      tags:
      - Device
      x-emoon-priority: P1
      parameters:
      - $ref: '#/components/parameters/DeviceIdPath'
      - *id001
      - *id002
      - *id003
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseDeviceEventList'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /devices/{deviceId}/commands/poll:
    get:
      summary: 设备轮询待执行命令
      tags:
      - Device
      x-emoon-priority: P0
      parameters:
      - $ref: '#/components/parameters/DeviceIdPath'
      - *id001
      - *id002
      - *id003
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseDeviceCommands'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /devices/{deviceId}/commands/{commandId}/ack:
    post:
      summary: 设备命令执行回执
      tags:
      - Device
      x-emoon-priority: P0
      parameters:
      - $ref: '#/components/parameters/DeviceIdPath'
      - $ref: '#/components/parameters/CommandIdPath'
      - *id001
      - *id002
      - *id003
      - *id006
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceCommandAckRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /cards/{cardInstanceId}:
    get:
      summary: 查询卡片实例
      tags:
      - Card
      x-emoon-priority: P0
      parameters:
      - $ref: '#/components/parameters/CardInstanceIdPath'
      - *id001
      - *id002
      - *id003
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseCardInstance'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /cards/{cardInstanceId}/actions/{actionName}:
    post:
      summary: 执行卡片动作
      tags:
      - Card
      x-emoon-priority: P0
      description: 所有产生业务后果的卡片动作必须幂等，且必须携带 operator 与 deviceContext。
      parameters:
      - $ref: '#/components/parameters/CardInstanceIdPath'
      - $ref: '#/components/parameters/ActionNamePath'
      - *id001
      - *id002
      - *id003
      - *id006
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardActionRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseCardAction'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /tools/{toolName}/invoke:
    post:
      summary: 调用院内系统工具，面向受控适配方
      tags:
      - MCP Tool
      x-emoon-priority: P0
      description: 需要 tool:read 或 tool:write scope。普通设备厂商默认不开放。
      parameters:
      - $ref: '#/components/parameters/ToolNamePath'
      - *id001
      - *id002
      - *id003
      - *id006
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInvokeRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseToolInvoke'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-emoon-required-scopes:
      - tool:read
      - tool:write
      x-emoon-partner-level:
      - trusted_system_adapter
      - his_vendor
      - emoon_internal
  /usage/summary:
    get:
      summary: 查询用量汇总
      tags:
      - Usage
      x-emoon-priority: P0
      parameters:
      - *id001
      - *id002
      - *id003
      - $ref: '#/components/parameters/FromDate'
      - $ref: '#/components/parameters/ToDate'
      - $ref: '#/components/parameters/GroupBy'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseUsageSummary'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /meter/events:
    get:
      summary: 查询计量事件
      tags:
      - Usage
      x-emoon-priority: P0
      parameters:
      - *id001
      - *id002
      - *id003
      - $ref: '#/components/parameters/BillingEpisodeId'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/QueryTraceId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseMeterEvents'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: 查询计量事件。P0 阶段仅支持按 billingEpisodeId 或 traceId 做精确查询，用于联调排障和计量核验；不作为正式账单查询接口，不开放项目级、设备级、时间范围复杂过滤给普通厂商。
  /agents:
    get:
      summary: 查询可用智能体列表
      tags:
      - Agent
      x-emoon-priority: P1
      parameters:
      - *id001
      - *id002
      - *id003
      - $ref: '#/components/parameters/ScenarioCode'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseAgentList'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/{agentId}:
    get:
      summary: 查询智能体详情
      tags:
      - Agent
      x-emoon-priority: P1
      parameters:
      - $ref: '#/components/parameters/AgentIdPath'
      - *id001
      - *id002
      - *id003
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseAgentDetail'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /devices:
    get:
      summary: 查询设备列表
      tags:
      - Device
      x-emoon-priority: P1
      parameters:
      - *id001
      - *id002
      - *id003
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseDeviceList'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /devices/{deviceId}:
    get:
      summary: 查询设备详情
      tags:
      - Device
      x-emoon-priority: P1
      parameters:
      - $ref: '#/components/parameters/DeviceIdPath'
      - *id001
      - *id002
      - *id003
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseDeviceDetail'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /webhooks:
    post:
      summary: 注册 Webhook
      tags:
      - Webhook
      x-emoon-priority: P1
      parameters: *id005
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRegisterRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseWebhook'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      summary: 查询 Webhook 列表
      tags:
      - Webhook
      x-emoon-priority: P1
      parameters:
      - *id001
      - *id002
      - *id003
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseWebhookList'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /webhooks/{webhookId}:
    delete:
      summary: 删除 Webhook
      tags:
      - Webhook
      x-emoon-priority: P1
      parameters:
      - $ref: '#/components/parameters/WebhookIdPath'
      - *id001
      - *id002
      - *id003
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /events/ingest:
    post:
      summary: 接收外部系统业务事件
      tags:
      - Event
      x-emoon-priority: P1
      description: 用于 HIS、叫号、迪耐克/病房系统向医梦上报事件。
      parameters: *id004
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalEventRequest'
      responses:
        '202':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseAccepted'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /tools/catalog:
    get:
      summary: 查询授权工具目录
      tags:
      - MCP Tool
      x-emoon-priority: P1
      parameters: *id005
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseToolCatalog'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-emoon-required-scopes:
      - tool:read
  /licenses/devices:
    get:
      summary: 查询设备授权状态
      tags:
      - License
      x-emoon-priority: P1
      parameters:
      - *id001
      - *id002
      - *id003
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseDeviceLicenses'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /partners:
    post:
      summary: 创建合作方接入档案
      tags:
      - Partner
      x-emoon-priority: P2
      description: P2 规划接口，不建议进入春节前 MVP。
      parameters: *id005
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerCreateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /contracts:
    get:
      summary: 查询合同与套餐
      tags:
      - Contract
      x-emoon-priority: P2
      description: P2 规划接口，不建议进入春节前 MVP。
      parameters: *id005
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /credit/accounts:
    get:
      summary: 查询能力值账户
      tags:
      - Credit
      x-emoon-priority: P2
      description: P2 规划接口，不建议进入春节前 MVP。
      parameters: *id005
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /billing/invoices:
    get:
      summary: 查询账单
      tags:
      - Billing
      x-emoon-priority: P2
      description: P2 规划接口，不建议进入春节前 MVP。
      parameters: *id005
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /operation/reports:
    get:
      summary: 查询运营报告
      tags:
      - Operation
      x-emoon-priority: P2
      description: P2 规划接口，不建议进入春节前 MVP。
      parameters: *id005
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /audit/logs:
    get:
      summary: 查询审计日志
      tags:
      - Audit
      x-emoon-priority: P2
      description: P2 规划接口，不建议进入春节前 MVP。
      parameters: *id005
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /partners/{partnerId}:
    get:
      summary: 查询合作方档案
      tags:
      - Partner
      x-emoon-priority: P2
      parameters:
      - $ref: '#/components/parameters/PartnerIdPath'
      - *id001
      - *id002
      - *id003
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /credit/accounts/{accountId}/freeze:
    post:
      summary: 冻结能力值
      tags:
      - Credit
      x-emoon-priority: P2
      description: 内部高风险接口，通常不对外开放。
      parameters:
      - $ref: '#/components/parameters/AccountIdPath'
      - *id001
      - *id002
      - *id003
      - *id006
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditFreezeRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /credit/accounts/{accountId}/settle:
    post:
      summary: 结算能力值
      tags:
      - Credit
      x-emoon-priority: P2
      description: 内部高风险接口，通常不对外开放。
      parameters:
      - $ref: '#/components/parameters/AccountIdPath'
      - *id001
      - *id002
      - *id003
      - *id006
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditSettleRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    HmacAuth:
      type: apiKey
      in: header
      name: X-Emoon-Access-Key
      description: 项目 Access Key。同时必须携带 X-Emoon-Timestamp（Unix 毫秒）、X-Emoon-Nonce（随机 UUID）、X-Emoon-Signature（Base64(HMAC-SHA256)）。
  parameters:
    ProjectId:
      name: X-Emoon-Project-Id
      in: header
      required: true
      schema:
        type: string
      description: 项目/医院标识。
    PartnerId:
      name: X-Emoon-Partner-Id
      in: header
      required: true
      schema:
        type: string
      description: 合作厂商标识。
    TraceId:
      name: X-Emoon-Trace-Id
      in: header
      required: false
      schema:
        type: string
      description: 链路追踪 ID；不传则平台生成。
    IdempotencyKey:
      name: X-Emoon-Idempotency-Key
      in: header
      required: false
      schema:
        type: string
      description: 写操作和产生业务事实的请求必须传。
    Timestamp:
      name: X-Emoon-Timestamp
      in: header
      required: false
      schema:
        type: string
      description: HMAC 模式必填，Unix 毫秒时间戳。
    Nonce:
      name: X-Emoon-Nonce
      in: header
      required: false
      schema:
        type: string
      description: HMAC 模式必填，防重放随机串。
    Signature:
      name: X-Emoon-Signature
      in: header
      required: false
      schema:
        type: string
      description: HMAC 模式必填，HMAC-SHA256 签名。
    DeviceIdHeader:
      name: X-Emoon-Device-Id
      in: header
      required: false
      schema:
        type: string
      description: 设备调用建议传，作为 deviceContext 兜底。
    DeviceIdPath:
      name: deviceId
      in: path
      required: true
      schema:
        type: string
    ConversationIdPath:
      name: conversationId
      in: path
      required: true
      schema:
        type: string
    FileIdPath:
      name: fileId
      in: path
      required: true
      schema:
        type: string
    CardInstanceIdPath:
      name: cardInstanceId
      in: path
      required: true
      schema:
        type: string
    ActionNamePath:
      name: actionName
      in: path
      required: true
      schema:
        type: string
    CommandIdPath:
      name: commandId
      in: path
      required: true
      schema:
        type: string
    ToolNamePath:
      name: toolName
      in: path
      required: true
      schema:
        type: string
    WebhookIdPath:
      name: webhookId
      in: path
      required: true
      schema:
        type: string
    PartnerIdPath:
      name: partnerId
      in: path
      required: true
      schema:
        type: string
    AccountIdPath:
      name: accountId
      in: path
      required: true
      schema:
        type: string
    AgentIdPath:
      name: agentId
      in: path
      required: true
      schema:
        type: string
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        default: 1
    PageSize:
      name: pageSize
      in: query
      required: false
      schema:
        type: integer
        default: 20
        maximum: 200
    FromDate:
      name: from
      in: query
      required: true
      schema:
        type: string
        format: date
    ToDate:
      name: to
      in: query
      required: true
      schema:
        type: string
        format: date
    GroupBy:
      name: groupBy
      in: query
      required: false
      schema:
        type: string
        enum:
        - project
        - partner
        - agent
        - device
        - scenario
        - department
        - day
    BillingEpisodeId:
      name: billingEpisodeId
      in: query
      required: false
      schema:
        type: string
      description: 按 billingEpisodeId 查询同一业务 episode 下的计量事件。P0 阶段 /meter/events 仅支持 billingEpisodeId 或 traceId 这类精确查询，不开放项目级、设备级、时间范围复杂过滤。
    ScenarioCode:
      name: scenarioCode
      in: query
      required: false
      schema:
        type: string
    QueryTraceId:
      name: traceId
      in: query
      required: false
      schema:
        type: string
      description: 按 traceId 查询联调排障相关计量事件。P0 仅用于联调排障，不代表完整账单查询。
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: string
          example: OK
        message:
          type: string
          example: success
        traceId:
          type: string
        requestId:
          type: string
        details:
          type: object
          additionalProperties: true
        data:
          type: object
          additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          example: INVALID_PARAM
        message:
          type: string
        details:
          type: object
          additionalProperties: true
        traceId:
          type: string
        requestId:
          type: string
      required:
      - code
      - message
      - traceId
    ApiResponseAccepted:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/AcceptedData'
    AcceptedData:
      type: object
      properties:
        accepted:
          type: boolean
        eventId:
          type: string
        status:
          type: string
          enum:
          - accepted
          - duplicate
          - ignored
    TokenRequest:
      type: object
      required:
      - grantType
      - clientId
      - clientSecret
      - projectId
      properties:
        grantType:
          type: string
          enum:
          - client_credentials
        clientId:
          type: string
        clientSecret:
          type: string
        projectId:
          type: string
        scopes:
          type: array
          items:
            type: string
    TokenData:
      type: object
      properties:
        accessToken:
          type: string
        tokenType:
          type: string
          example: Bearer
        expiresIn:
          type: integer
          example: 7200
        scopes:
          type: array
          items:
            type: string
    ApiResponseToken:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/TokenData'
    HealthData:
      type: object
      properties:
        status:
          type: string
          enum:
          - UP
          - DOWN
          - DEGRADED
        timestamp:
          type: string
          format: date-time
        version:
          type: string
    ApiResponseHealth:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/HealthData'
    CapabilitiesData:
      type: object
      properties:
        projectId:
          type: string
        agents:
          type: array
          items:
            $ref: '#/components/schemas/AgentSummary'
        enabledFeatures:
          type: array
          items:
            type: string
        toolScopes:
          type: array
          items:
            type: string
        rateLimit:
          $ref: '#/components/schemas/RateLimitPolicy'
    ApiResponseCapabilities:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/CapabilitiesData'
    RateLimitPolicy:
      type: object
      properties:
        windowSeconds:
          type: integer
        limit:
          type: integer
    UserContext:
      type: object
      required:
      - externalUserId
      - role
      properties:
        externalUserId:
          type: string
        role:
          type: string
          enum:
          - patient
          - doctor
          - nurse
          - admin
          - system
          - anonymous
        patientId:
          type: string
          description: HIS 患者 ID，第一期可选。
        visitId:
          type: string
          description: 门诊/住院就诊 ID，第一期可选。
        encounterId:
          type: string
        authorizationId:
          type: string
          description: 患者授权记录 ID。
    DeviceContext:
      type: object
      properties:
        deviceId:
          type: string
        deviceType:
          type: string
          enum:
          - mobile_app
          - guide_screen
          - self_service_kiosk
          - robot
          - waiting_screen
          - clinic_door_screen
          - clinic_desktop_screen
          - doctor_station
          - four_diagnosis_device
          - nurse_pda
          - nursing_whiteboard
          - bedside_screen
          - ward_robot
          - unknown
          description: 设备类型。门诊类型可进入医梦统一入口直接管理；住院侧类型仅表示 AI 能力映射对象，不代表医梦接管住院硬件。
        locationCode:
          type: string
        sceneCode:
          type: string
        clientVersion:
          type: string
        managementMode:
          type: string
          enum:
          - emoon_managed
          - partner_managed
          - mapped_external
          description: 设备管理模式。emoon_managed=医梦统一入口客户端和 Device Registry 管理；partner_managed=合作设备厂商管理，医梦通过标准接口接入；mapped_external=迪耐克/鸿蒙病房等外部体系管理，医梦只做映射和事件互通。
        externalSystem:
          type: string
          description: 外部系统标识，例如 dinaike_ward、harmony_ward、his_queue。管理模式为 mapped_external 或 partner_managed 时建议填写。
        externalDeviceId:
          type: string
          description: 外部系统中的设备或终端 ID，用于住院互通和第三方设备映射。
      required:
      - deviceId
      description: 设备上下文。门诊设备原则上由医梦 Device Registry 管理；住院侧类型（nurse_pda / nursing_whiteboard / bedside_screen / ward_robot）通常通过迪耐克/鸿蒙病房体系映射接入，医梦只负责 AI 能力、事件互通和审计，不承担住院硬件基础管理责任。
    PerceptionContext:
      type: object
      description: 感知上下文。用于统一入口客户端上报最近一次身份、空间、业务、设备或风险感知事实；服务端仍以授权、HIS/叫号/任务状态为最终依据。P0 不允许上传连续轨迹。
      properties:
        identityBindingId:
          type: string
          description: 患者身份与终端/设备/会话绑定记录 ID。
        locationLevel:
          type: string
          enum:
          - L0
          - L1
          - L2
          - L3
          description: 感知级别。L0=扫码/人工；L1=NFC/刷卡；L2=BLE/Wi-Fi 区域；L3=星闪/鸿蒙/UWB 等高精度。
        zoneCode:
          type: string
          description: 服务区域编码，如 clinic_room_301_door、outpatient_hall_kiosk。
        source:
          type: string
          enum:
          - QR_SCANNED
          - NFC_TOUCH
          - CARD_READ
          - BLE_ZONE_DETECT
          - WIFI_ZONE_DETECT
          - MANUAL_CONFIRM
          - BUSINESS_STATE
          - DEVICE_EVENT
          - CUSTOM
        occurredAt:
          type: string
          format: date-time
        confidence:
          type: number
          format: double
          minimum: 0
          maximum: 1
    JourneyState:
      type: object
      readOnly: true
      description: 患者当前动线阶段。由服务端根据 VisitTimeline、TaskState、DeviceContext、DeviceEvent、CardAction 和院内系统状态推导；P0 仅用于服务端返回给客户端展示，客户端请求不得传入该对象，也不得据此自行放开高风险能力。
      properties:
        stageCode:
          type: string
          description: 动线阶段编码，如 WAITING_CHECKIN、WAITING_CALL、WAITING_PAYMENT、WAITING_EXAM、REPORT_READY、FOLLOW_UP。
        stageName:
          type: string
          description: 动线阶段中文名。
        nextAction:
          type: string
          description: 推荐下一步动作，如 CHECK_IN、PAYMENT_GUIDE、NAVIGATE_TO_EXAM、REPORT_EXPLAIN。
        source:
          type: string
          enum:
          - SERVER_DERIVED
          - HIS_STATE
          - CARD_ACTION
          - DEVICE_EVENT
        confidence:
          type: number
          format: double
          minimum: 0
          maximum: 1
        requiresConfirm:
          type: boolean
          description: 是否必须患者或医护确认后才能执行。
    BillingContext:
      type: object
      properties:
        scenarioCode:
          type: string
        billingEpisodeId:
          type: string
        chargePolicy:
          type: string
          enum:
          - customer_charge
          - license_covered
          - bundle_included
          - internal_cost
          - no_charge
    ChatMessage:
      type: object
      required:
      - type
      - text
      properties:
        type:
          type: string
          enum:
          - text
          - image
          - audio
          - file
        text:
          type: string
          description: 文本内容（type=text 时必填）。
        fileId:
          type: string
          description: 多模态文件推荐传 fileId（type=image/audio/file 时使用）。
        clientMessageId:
          type: string
          description: 客户端消息幂等 ID。
    AgentChatRequest:
      type: object
      required:
      - message
      properties:
        agentId:
          type: string
          nullable: true
          description: 对外智能体 ID。统一入口客户端可为空，由后端 AgentRouter 根据设备、场景、任务状态和输入内容决定。
        conversationId:
          type: string
          description: 首轮可为空，平台自动创建。
        user:
          $ref: '#/components/schemas/UserContext'
        deviceContext:
          $ref: '#/components/schemas/DeviceContext'
        perceptionContext:
          $ref: '#/components/schemas/PerceptionContext'
        message:
          $ref: '#/components/schemas/ChatMessage'
        inputs:
          type: object
          additionalProperties: true
        billingContext:
          $ref: '#/components/schemas/BillingContext'
    AgentChatData:
      type: object
      properties:
        conversationId:
          type: string
        messageId:
          type: string
        answer:
          type: string
        cards:
          type: array
          items:
            $ref: '#/components/schemas/CardRef'
        journeyState:
          $ref: '#/components/schemas/JourneyState'
        riskLevel:
          type: string
          enum:
          - low
          - medium
          - high
          - critical
          - unknown
        usage:
          $ref: '#/components/schemas/UsageBrief'
    CardRef:
      type: object
      properties:
        cardInstanceId:
          type: string
        cardKey:
          type: string
        status:
          type: string
    UsageBrief:
      type: object
      properties:
        meterEventId:
          type: string
        billingEpisodeId:
          type: string
        chargePolicy:
          type: string
        credits:
          type: number
    ApiResponseAgentChat:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/AgentChatData'
    ConversationCreateRequest:
      type: object
      properties:
        agentId:
          type: string
        user:
          $ref: '#/components/schemas/UserContext'
        deviceContext:
          $ref: '#/components/schemas/DeviceContext'
        title:
          type: string
        metadata:
          type: object
          additionalProperties: true
    Conversation:
      type: object
      properties:
        conversationId:
          type: string
        agentId:
          type: string
        title:
          type: string
        status:
          type: string
          enum:
          - active
          - closed
          - archived
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ApiResponseConversation:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/Conversation'
    ApiResponseConversationList:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/Conversation'
            page:
              $ref: '#/components/schemas/PageInfo'
    ConversationMessage:
      type: object
      properties:
        messageId:
          type: string
        role:
          type: string
          enum:
          - user
          - assistant
          - system
          - tool
        content:
          type: string
        cards:
          type: array
          items:
            $ref: '#/components/schemas/CardRef'
        createdAt:
          type: string
          format: date-time
    ApiResponseMessageList:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/ConversationMessage'
            page:
              $ref: '#/components/schemas/PageInfo'
    FileUploadRequest:
      type: object
      required:
      - file
      properties:
        file:
          type: string
          format: binary
        purpose:
          type: string
          enum:
          - tongue_diagnosis
          - face_diagnosis
          - report_interpretation
          - medical_record
          - audio_transcription
          - other
        user:
          $ref: '#/components/schemas/UserContext'
        deviceContext:
          $ref: '#/components/schemas/DeviceContext'
        metadata:
          type: object
          additionalProperties: true
        clientFileId:
          type: string
          description: 厂商侧文件唯一 ID。同一文件重试上传时必须保持不变，推荐用于文件上传幂等。
        sha256:
          type: string
          description: 文件 SHA-256 摘要。用于完整性校验、重复文件识别和审计。
        source:
          type: string
          enum:
          - patient_app
          - self_service_kiosk
          - robot
          - four_diagnosis_device
          - doctor_station
          - ward_terminal
          - third_party_system
          description: 文件来源终端或系统。
        retentionPolicy:
          type: string
          enum:
          - transient
          - episode
          - medical_record
          - audit_only
          description: 文件保存策略。transient=临时分析；episode=本次就诊 episode 内保存；medical_record=进入病历或正式医疗材料；audit_only=只保留审计摘要。
      description: 文件上传请求。正式联调推荐幂等键 projectId + partnerId + clientFileId；clientFileId 缺失时可降级使用 projectId + partnerId + sha256 + purpose + user.visitId。
    FileMeta:
      type: object
      properties:
        fileId:
          type: string
        fileType:
          type: string
          enum:
          - image
          - audio
          - document
          - other
        mimeType:
          type: string
        sizeBytes:
          type: integer
        sha256:
          type: string
        status:
          type: string
          enum:
          - uploaded
          - scanning
          - available
          - blocked
          - deleted
        uploadedAt:
          type: string
          format: date-time
        clientFileId:
          type: string
        purpose:
          type: string
        retentionPolicy:
          type: string
          enum:
          - transient
          - episode
          - medical_record
          - audit_only
        source:
          type: string
    ApiResponseFileUpload:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/FileMeta'
    ApiResponseFileMeta:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/FileMeta'
    DeviceRegisterRequest:
      type: object
      required:
      - deviceCode
      - deviceType
      - vendor
      - model
      - os
      - clientVersion
      properties:
        deviceCode:
          type: string
        deviceType:
          type: string
        vendor:
          type: string
        model:
          type: string
        os:
          type: string
          enum:
          - android
          - harmony
          - windows
          - linux
          - web
          - unknown
        clientVersion:
          type: string
        capabilities:
          $ref: '#/components/schemas/DeviceCapabilities'
        location:
          $ref: '#/components/schemas/DeviceLocation'
    DeviceCapabilities:
      type: object
      properties:
        touch:
          type: boolean
        screen:
          type: boolean
        voiceInput:
          type: boolean
        voiceOutput:
          type: boolean
        camera:
          type: boolean
        qrScan:
          type: boolean
        idCardReader:
          type: boolean
        medicalCardReader:
          type: boolean
        printer:
          type: boolean
        navigation:
          type: boolean
        nearbyDetect:
          type: boolean
    DeviceLocation:
      type: object
      properties:
        building:
          type: string
        floor:
          type: string
        area:
          type: string
        room:
          type: string
        bed:
          type: string
        locationCode:
          type: string
    DeviceRegisterData:
      type: object
      properties:
        deviceId:
          type: string
        deviceSecret:
          type: string
        activateStatus:
          type: string
          description: 设备准入状态。activated 可进入核心业务，pending 待人工审批，rejected 已拒绝。
          enum:
          - activated
          - pending
          - rejected
        admissionLevel:
          type: string
          description: 设备等级 A/B/C/D。
          enum:
          - A
          - B
          - C
          - D
        reason:
          type: string
          description: 当 activateStatus 为 pending 或 rejected 时，说明原因。
    ApiResponseDeviceRegister:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/DeviceRegisterData'
    DeviceHeartbeatRequest:
      type: object
      required:
      - status
      - clientVersion
      properties:
        status:
          type: string
          enum:
          - online
          - offline
          - error
          - maintenance
        clientVersion:
          type: string
        ip:
          type: string
        currentSceneCode:
          type: string
        metrics:
          type: object
          additionalProperties: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/DeviceError'
    DeviceError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        occurredAt:
          type: string
          format: date-time
    DeviceHeartbeatData:
      type: object
      properties:
        accepted:
          type: boolean
        serverTime:
          type: string
          format: date-time
        nextHeartbeatSeconds:
          type: integer
    ApiResponseDeviceHeartbeat:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/DeviceHeartbeatData'
    DeviceSceneData:
      type: object
      properties:
        deviceId:
          type: string
        deviceType:
          type: string
          description: 设备类型 robot/self_service_kiosk/guide_screen 等。
        sceneCode:
          type: string
        homeTemplate:
          type: string
          description: 首页 UI 模板标识。
        defaultAgent:
          type: string
          description: 默认智能体代码。
        allowedAgents:
          type: array
          items:
            type: string
          description: 该设备在当前场景下允许调用的智能体列表。
        blockedIntents:
          type: array
          items:
            type: string
          description: 该设备在当前场景下被阻止的意图列表。
        capabilities:
          type: array
          items:
            type: string
          description: 设备硬件能力列表（如 touch/camera/id_card_ocr/file_upload）。
        perceptionCapabilities:
          type: array
          items:
            type: string
            enum:
            - QR_IDENTITY_BINDING
            - NFC_TOUCH
            - CARD_READ
            - BLE_ZONE_DETECT
            - WIFI_ZONE_DETECT
            - HARMONY_NEARBY
            - MANUAL_CONFIRM
          description: 该设备支持的感知能力。P0 推荐 QR/NFC/刷卡/人工确认，BLE/鸿蒙近场仅作为可选试点。
        journeyPolicy:
          type: object
          description: 动线服务策略。用于终端决定是否展示动线区和服务找人入口，不能用于绕过后端权限。
          properties:
            mode:
              type: string
              enum:
              - DISABLED
              - MVP_STATIC
              - SERVER_DERIVED
            serviceFindPatientEnabled:
              type: boolean
            requiresPatientConfirm:
              type: boolean
        allowedCards:
          type: array
          items:
            type: string
          description: 该设备在当前场景下允许渲染的卡片类型列表。
    ApiResponseDeviceScene:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/DeviceSceneData'
    DeviceSceneUpdateRequest:
      type: object
      properties:
        sceneCode:
          type: string
        homeTemplate:
          type: string
          description: 首页 UI 模板标识。
        allowedAgents:
          type: array
          items:
            type: string
          description: 允许调用的智能体列表。
        allowedCards:
          type: array
          items:
            type: string
          description: 允许渲染的卡片类型列表。
        blockedIntents:
          type: array
          items:
            type: string
          description: 阻止的意图列表。
        effectiveAt:
          type: string
          format: date-time
    DeviceEventRequest:
      type: object
      required:
      - eventId
      - eventType
      - occurredAt
      properties:
        eventId:
          type: string
          description: 设备端生成的唯一事件 ID。
        eventType:
          type: string
          description: 设备事件类型。
          enum:
          - QR_SCANNED
          - CARD_READ
          - PRINT_COMPLETED
          - PRINT_FAILED
          - NEARBY_DETECTED
          - NAVIGATION_STARTED
          - NAVIGATION_COMPLETED
          - DEVICE_ERROR
          - TOUCH_INTERACTION
          - CUSTOM
        eventPayload:
          type: object
          additionalProperties: true
          description: 事件附加数据。按 eventType 校验必要字段：QR_SCANNED 建议 qrType/visitId；CARD_READ 建议 cardType；NEARBY_DETECTED 建议 zoneCode/level；TOUCH_INTERACTION 建议 screen/action。未识别扩展字段只作为审计摘要，不直接触发高风险业务。
        occurredAt:
          type: string
          format: date-time
        traceId:
          type: string
          description: 可选链路追踪 ID。
    DeviceCommand:
      type: object
      properties:
        commandId:
          type: string
        commandType:
          type: string
          enum:
          - show_page
          - render_card
          - play_tts
          - start_navigation
          - stop_navigation
          - return_dock
          - print_receipt
          - refresh_scene
          - upgrade_client
          - custom
        payload:
          type: object
          additionalProperties: true
        expiresAt:
          type: string
          format: date-time
    ApiResponseDeviceCommands:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          type: object
          properties:
            commands:
              type: array
              items:
                $ref: '#/components/schemas/DeviceCommand'
    DeviceCommandAckRequest:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          enum:
          - success
          - failed
          - processing
          - rejected
        message:
          type: string
        result:
          type: object
          additionalProperties: true
    CardInstance:
      type: object
      properties:
        cardInstanceId:
          type: string
        cardKey:
          type: string
        status:
          type: string
          enum:
          - active
          - submitted
          - processing
          - completed
          - failed
          - expired
          - cancelled
        renderPayload:
          type: object
          additionalProperties: true
        actions:
          type: array
          items:
            type: string
        expiresAt:
          type: string
          format: date-time
    ApiResponseCardInstance:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/CardInstance'
    OperatorContext:
      type: object
      required:
      - role
      - externalUserId
      properties:
        role:
          type: string
          enum:
          - patient
          - doctor
          - nurse
          - admin
          - system
        externalUserId:
          type: string
        patientId:
          type: string
        doctorId:
          type: string
        nurseId:
          type: string
    CardActionRequest:
      type: object
      required:
      - clientActionId
      - operator
      - deviceContext
      - payload
      properties:
        clientActionId:
          type: string
        operator:
          $ref: '#/components/schemas/OperatorContext'
        deviceContext:
          $ref: '#/components/schemas/DeviceContext'
        payload:
          type: object
          additionalProperties: true
        confirm:
          type: boolean
        billingContext:
          $ref: '#/components/schemas/BillingContext'
    CardActionData:
      type: object
      properties:
        cardInstanceId:
          type: string
        actionName:
          type: string
        status:
          type: string
          enum:
          - accepted
          - processing
          - completed
          - failed
          - duplicate
        result:
          type: object
          additionalProperties: true
        nextCard:
          $ref: '#/components/schemas/CardRef'
    ApiResponseCardAction:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/CardActionData'
    ToolInvokeRequest:
      type: object
      required:
      - toolCallId
      - context
      - input
      properties:
        toolCallId:
          type: string
        context:
          $ref: '#/components/schemas/ToolContext'
        input:
          type: object
          additionalProperties: true
        billingContext:
          $ref: '#/components/schemas/BillingContext'
        riskLevel:
          $ref: '#/components/schemas/ToolRiskLevel'
      description: 受控工具调用请求。仅开放给医梦 MCP Tool Server、HIS/EMR/LIS/PACS/叫号/支付等受控适配方；普通设备厂商不得直接调用。写操作必须幂等，并按 riskLevel 执行确认、权限和审计策略。
    ToolContext:
      type: object
      properties:
        projectId:
          type: string
        user:
          $ref: '#/components/schemas/UserContext'
        deviceContext:
          $ref: '#/components/schemas/DeviceContext'
        cardInstanceId:
          type: string
        traceId:
          type: string
    ToolInvokeData:
      type: object
      properties:
        toolCallId:
          type: string
        toolName:
          type: string
        status:
          type: string
          enum:
          - success
          - failed
          - timeout
          - forbidden
        result:
          type: object
          additionalProperties: true
        error:
          $ref: '#/components/schemas/ErrorResponse'
    ApiResponseToolInvoke:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/ToolInvokeData'
    WebhookRegisterRequest:
      type: object
      required:
      - url
      - eventTypes
      properties:
        url:
          type: string
          format: uri
        eventTypes:
          type: array
          items:
            type: string
        secret:
          type: string
        description:
          type: string
    WebhookData:
      type: object
      properties:
        webhookId:
          type: string
        url:
          type: string
        eventTypes:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
          - active
          - disabled
    ApiResponseWebhook:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/WebhookData'
    ApiResponseWebhookList:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/WebhookData'
            page:
              $ref: '#/components/schemas/PageInfo'
    ExternalEventRequest:
      type: object
      required:
      - eventId
      - eventType
      - occurredAt
      - sourceSystem
      properties:
        eventId:
          type: string
        eventType:
          type: string
        sourceSystem:
          type: string
        occurredAt:
          type: string
          format: date-time
        user:
          $ref: '#/components/schemas/UserContext'
        deviceContext:
          $ref: '#/components/schemas/DeviceContext'
        payload:
          type: object
          additionalProperties: true
    ToolCatalogItem:
      type: object
      properties:
        toolName:
          type: string
        toolType:
          type: string
          enum:
          - read
          - write
        description:
          type: string
        inputSchema:
          type: object
          additionalProperties: true
        outputSchema:
          type: object
          additionalProperties: true
        riskLevel:
          $ref: '#/components/schemas/ToolRiskLevel'
    ApiResponseToolCatalog:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          type: object
          properties:
            tools:
              type: array
              items:
                $ref: '#/components/schemas/ToolCatalogItem'
    UsageSummaryData:
      type: object
      properties:
        from:
          type: string
          format: date
        to:
          type: string
          format: date
        groupBy:
          type: string
        items:
          type: array
          items:
            type: object
            additionalProperties: true
    ApiResponseUsageSummary:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/UsageSummaryData'
    MeterEvent:
      type: object
      properties:
        meterEventId:
          type: string
        billingEpisodeId:
          type: string
        projectId:
          type: string
        partnerId:
          type: string
        agentId:
          type: string
        deviceId:
          type: string
        scenarioCode:
          type: string
        sourceType:
          type: string
          enum:
          - openplatform
          - dify
          - mcp
          - card
          - device
          - file
          - webhook
        sourceId:
          type: string
        meterItem:
          type: string
        rawQuantity:
          type: number
        credits:
          type: number
        chargePolicy:
          type: string
          enum:
          - customer_charge
          - license_covered
          - bundle_included
          - internal_cost
          - no_charge
        status:
          type: string
          enum:
          - pending
          - settled
          - reversed
          - failed
        occurredAt:
          type: string
          format: date-time
    ApiResponseMeterEvents:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/MeterEvent'
            page:
              $ref: '#/components/schemas/PageInfo'
    DeviceLicense:
      type: object
      properties:
        deviceId:
          type: string
        licenseStatus:
          type: string
          enum:
          - active
          - expired
          - suspended
          - not_bound
        licenseType:
          type: string
        validTo:
          type: string
          format: date
    ApiResponseDeviceLicenses:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/DeviceLicense'
            page:
              $ref: '#/components/schemas/PageInfo'
    AgentSummary:
      type: object
      properties:
        agentId:
          type: string
        name:
          type: string
        scenarioCode:
          type: string
        status:
          type: string
    ApiResponseAgentList:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/AgentSummary'
    AgentDetail:
      allOf:
      - $ref: '#/components/schemas/AgentSummary'
      properties:
        description:
          type: string
        supportedMessageTypes:
          type: array
          items:
            type: string
        supportedCards:
          type: array
          items:
            type: string
    ApiResponseAgentDetail:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/AgentDetail'
    DeviceDetail:
      type: object
      properties:
        deviceId:
          type: string
        deviceCode:
          type: string
        deviceType:
          type: string
        vendor:
          type: string
        model:
          type: string
        location:
          $ref: '#/components/schemas/DeviceLocation'
        capabilities:
          $ref: '#/components/schemas/DeviceCapabilities'
        status:
          type: string
        clientVersion:
          type: string
        lastHeartbeat:
          type: string
          format: date-time
    ApiResponseDeviceDetail:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          $ref: '#/components/schemas/DeviceDetail'
    ApiResponseDeviceList:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/DeviceDetail'
            page:
              $ref: '#/components/schemas/PageInfo'
    ApiResponseDeviceEventList:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      properties:
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/DeviceEventRequest'
            page:
              $ref: '#/components/schemas/PageInfo'
    PageInfo:
      type: object
      properties:
        page:
          type: integer
        pageSize:
          type: integer
        total:
          type: integer
    PartnerCreateRequest:
      type: object
      properties:
        partnerName:
          type: string
        partnerType:
          type: string
        scopes:
          type: array
          items:
            type: string
    CreditFreezeRequest:
      type: object
      properties:
        sourceEventId:
          type: string
        credits:
          type: number
        reason:
          type: string
    CreditSettleRequest:
      type: object
      properties:
        freezeId:
          type: string
        meterEventId:
          type: string
        actualCredits:
          type: number
    ToolRiskLevel:
      type: string
      enum:
      - L1_QUERY
      - L2_SENSITIVE_READ
      - L3_BUSINESS_WRITE
      - L4_FINANCIAL_ACTION
      - L5_MEDICAL_WRITE
      description: 工具风险等级。L1 查询、L2 敏感查询、L3 业务写入、L4 财务动作、L5 医疗正式写入。
x-emoon-api-version: 2026-05-29-v1.2
x-emoon-document-status: 正式联调基准版