{
  "openapi": "3.0.3",
  "info": {
    "title": "云机基础 Core API",
    "version": "0.2.0",
    "description": "云机基础 Core HTTP API，供可信服务端、管理员工作台及受限业务会话调用。字段使用 snake_case；资源 ID 使用字符串；时间使用 UTC RFC3339。\n\n默认鉴权：每次请求同时发送 X-Core-Key 和 X-Core-Secret。普通业务接口也允许 `Authorization: Bearer <受限会话令牌>`，两种方式互斥，不能混用。x-core-public 表示允许受限业务会话使用，并不表示匿名开放。服务凭据与会话管理接口只接受 Key/Secret；健康检查不需要凭据，文件传输链接使用自身短期票据。\n\n状态读取约定：云机 status 是容器状态，wifi_status 是网络观测状态；只有两者都为 running 才可展示运行可用。常见设备值为 created / running，离线、缺少观测或其他 provider 的状态请按字段说明处理。\n\n设备动作是异步任务：HTTP 202 仅表示 Core 已持久受理，后续查询 task_id；按 items[] 读取逐目标结果。任务成功不自动等于云机已联网、可投屏或备份已交付，须结合动作 result、observation 与文件 ready 状态判断。结果未知时查询原任务或按原 Idempotency-Key 查询，不自动以新键重复写入设备。Core 设备操作始终经登记机房执行。"
  },
  "servers": [
    {
      "url": "http://127.0.0.1:3100",
      "description": "隔离本地示例；生产由宿主服务端配置私网地址"
    }
  ],
  "security": [
    {
      "serviceKey": [],
      "serviceSecret": []
    }
  ],
  "paths": {
    "/api/v1/boxes": {
      "get": {
        "operationId": "listBoxes",
        "summary": "分页查询云卡",
        "x-core-public": true,
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "maximum": 1000000
            },
            "description": "页码，从 1 开始。"
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            },
            "description": "每页条数，响应 meta.page_size 返回实际采用值。"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "id",
                "-id",
                "updated_at",
                "-updated_at",
                "ip",
                "-ip",
                "ip_numeric",
                "-ip_numeric"
              ],
              "description": "排序字段；不带 - 为升序，前缀 - 为降序。id=Core ID，updated_at=更新时间，ip=地址文本，ip_numeric=数值 IP 顺序，idx=机房槽位，title=名称，status=容器状态；仅接受本接口枚举中列出的字段。"
            },
            "description": "排序字段；不带 - 为升序，前缀 - 为降序。id=Core ID，updated_at=更新时间，ip=地址文本，ip_numeric=数值 IP 顺序，idx=机房槽位，title=名称，status=容器状态；仅接受本接口枚举中列出的字段。"
          },
          {
            "name": "box_id",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云卡 ID（字符串）。"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "云卡在线状态：online=在线；offline=离线。与云机的 created/running 状态不同。"
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 128,
              "minLength": 1
            },
            "description": "按接口支持的名称或地址字段搜索；不改变当前授权范围。"
          },
          {
            "name": "server_id",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "登记机房的 server_id。"
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}(,[1-9][0-9]{0,19}){0,199}$"
            }
          },
          {
            "name": "server_ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 4999
            }
          },
          {
            "name": "group_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 128
            },
            "description": "精确匹配 Core 云机分组名称。"
          },
          {
            "name": "recycled",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "description": "true=仅回收站；false=排除回收站。未传时按接口默认范围。"
            },
            "description": "true=仅回收站；false=排除回收站。未传时按接口默认范围。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Box"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ListMeta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["云卡与云机"]
      }
    },
    "/api/v1/boxes-stats": {
      "get": {
        "operationId": "getBoxStats",
        "summary": "查询云卡状态统计",
        "x-core-public": true,
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "id",
                "-id",
                "updated_at",
                "-updated_at",
                "ip",
                "-ip",
                "ip_numeric",
                "-ip_numeric"
              ],
              "description": "排序字段；不带 - 为升序，前缀 - 为降序。id=Core ID，updated_at=更新时间，ip=地址文本，ip_numeric=数值 IP 顺序，idx=机房槽位，title=名称，status=容器状态；仅接受本接口枚举中列出的字段。"
            },
            "description": "排序字段；不带 - 为升序，前缀 - 为降序。id=Core ID，updated_at=更新时间，ip=地址文本，ip_numeric=数值 IP 顺序，idx=机房槽位，title=名称，status=容器状态；仅接受本接口枚举中列出的字段。"
          },
          {
            "name": "box_id",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云卡 ID（字符串）。"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "云卡在线状态：online=在线；offline=离线。与云机的 created/running 状态不同。"
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 128,
              "minLength": 1
            },
            "description": "按接口支持的名称或地址字段搜索；不改变当前授权范围。"
          },
          {
            "name": "server_id",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "登记机房的 server_id。"
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}(,[1-9][0-9]{0,19}){0,199}$"
            }
          },
          {
            "name": "server_ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 4999
            }
          },
          {
            "name": "group_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 128
            },
            "description": "精确匹配 Core 云机分组名称。"
          },
          {
            "name": "recycled",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "description": "true=仅回收站；false=排除回收站。未传时按接口默认范围。"
            },
            "description": "true=仅回收站；false=排除回收站。未传时按接口默认范围。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Stats"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["云卡与云机"]
      }
    },
    "/api/v1/envs": {
      "get": {
        "operationId": "listEnvs",
        "summary": "分页查询云机",
        "x-core-public": true,
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "maximum": 1000000
            },
            "description": "页码，从 1 开始。"
          },
          {
            "name": "page_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            },
            "description": "每页条数，响应 meta.page_size 返回实际采用值。"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "id",
                "-id",
                "updated_at",
                "-updated_at",
                "idx",
                "-idx",
                "title",
                "-title",
                "status",
                "-status"
              ],
              "description": "排序字段；不带 - 为升序，前缀 - 为降序。id=Core ID，updated_at=更新时间，ip=地址文本，ip_numeric=数值 IP 顺序，idx=机房槽位，title=名称，status=容器状态；仅接受本接口枚举中列出的字段。"
            },
            "description": "排序字段；不带 - 为升序，前缀 - 为降序。id=Core ID，updated_at=更新时间，ip=地址文本，ip_numeric=数值 IP 顺序，idx=机房槽位，title=名称，status=容器状态；仅接受本接口枚举中列出的字段。"
          },
          {
            "name": "box_id",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云卡 ID（字符串）。"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "容器同步状态筛选，常见 created=已创建但未运行，running=已开机；offline=离线，unknown=缺少可信状态。状态为开放字符串，保留机房其他状态。筛选在线可用云机还须同时 wifi_status=running。"
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 128,
              "minLength": 1
            },
            "description": "按接口支持的名称或地址字段搜索；不改变当前授权范围。"
          },
          {
            "name": "server_id",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "登记机房的 server_id。"
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}(,[1-9][0-9]{0,19}){0,199}$"
            }
          },
          {
            "name": "server_ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 4999
            }
          },
          {
            "name": "group_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 128
            },
            "description": "精确匹配 Core 云机分组名称。"
          },
          {
            "name": "recycled",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "description": "true=仅回收站；false=排除回收站。未传时按接口默认范围。"
            },
            "description": "true=仅回收站；false=排除回收站。未传时按接口默认范围。"
          },
          {
            "name": "wifi_status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "网络观测状态筛选，常见 created=网络未就绪，running=网络可用；unknown=无可信网络观测。与 status=running 一起使用可筛选运行可用的云机。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Env"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ListMeta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "description": "status 是机房同步的容器状态，wifi_status 是网络观测状态。常见 created 表示关机或网络尚不可用，running 分别表示开机或网络可用。仅 status=running 且 wifi_status=running 才属于运行可用；库存同步不保证实时可连接或可投屏。",
        "tags": ["云卡与云机"]
      }
    },
    "/api/v1/envs-stats": {
      "get": {
        "operationId": "getEnvStats",
        "summary": "查询云机状态与运行可用数量",
        "x-core-public": true,
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "id",
                "-id",
                "updated_at",
                "-updated_at",
                "idx",
                "-idx",
                "title",
                "-title",
                "status",
                "-status"
              ],
              "description": "排序字段；不带 - 为升序，前缀 - 为降序。id=Core ID，updated_at=更新时间，ip=地址文本，ip_numeric=数值 IP 顺序，idx=机房槽位，title=名称，status=容器状态；仅接受本接口枚举中列出的字段。"
            },
            "description": "排序字段；不带 - 为升序，前缀 - 为降序。id=Core ID，updated_at=更新时间，ip=地址文本，ip_numeric=数值 IP 顺序，idx=机房槽位，title=名称，status=容器状态；仅接受本接口枚举中列出的字段。"
          },
          {
            "name": "box_id",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云卡 ID（字符串）。"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "容器同步状态筛选，常见 created=已创建但未运行，running=已开机；offline=离线，unknown=缺少可信状态。状态为开放字符串，保留机房其他状态。筛选在线可用云机还须同时 wifi_status=running。"
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 128,
              "minLength": 1
            },
            "description": "按接口支持的名称或地址字段搜索；不改变当前授权范围。"
          },
          {
            "name": "server_id",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "登记机房的 server_id。"
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}(,[1-9][0-9]{0,19}){0,199}$"
            }
          },
          {
            "name": "server_ids",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 4999
            }
          },
          {
            "name": "group_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 128
            },
            "description": "精确匹配 Core 云机分组名称。"
          },
          {
            "name": "recycled",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "description": "true=仅回收站；false=排除回收站。未传时按接口默认范围。"
            },
            "description": "true=仅回收站；false=排除回收站。未传时按接口默认范围。"
          },
          {
            "name": "wifi_status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "网络观测状态筛选，常见 created=网络未就绪，running=网络可用；unknown=无可信网络观测。与 status=running 一起使用可筛选运行可用的云机。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Stats"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["云卡与云机"]
      }
    },
    "/api/v1/power-requests": {
      "post": {
        "operationId": "requestPower",
        "summary": "兼容开机入口：创建持久任务",
        "x-core-public": true,
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "本次主动操作的唯一幂等键。重传相同请求保留原键；响应未知先查原键，不能自动换新键重新写入。"
          }
        ],
        "responses": {
          "202": {
            "description": "Core 已持久受理异步任务；不是设备执行成功。按返回 task_id 查询原任务及逐目标结果。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Task"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PowerRequest"
              }
            }
          }
        },
        "description": "兼容入口，目前仅支持 action=start。HTTP 202 仅表示任务已受理；开机后需另读云机 status 与 wifi_status，两者都为 running 才表示运行可用。",
        "tags": ["持久化任务"]
      }
    },
    "/api/v1/tasks/{task_id}": {
      "get": {
        "operationId": "getTask",
        "summary": "查询任务及逐目标结果",
        "x-core-public": true,
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Core 持久任务 ID；查询原任务不会重复执行设备操作。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Task"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "description": "status 是整批汇总，混合结果必须检查 items[]。结果未知、远端仍运行、文件中心交付等情况请结合 items[].result 与 observation，不以 updated_at 或普通库存 running 推断本次操作成功。",
        "tags": ["持久化任务"]
      }
    },
    "/api/v1/access-sessions": {
      "post": {
        "operationId": "createAccessSession",
        "summary": "创建受限会话",
        "x-core-public": false,
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [],
        "responses": {
          "201": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AccessSession"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccessSessionRequest"
              }
            }
          }
        },
        "tags": ["受限会话"]
      }
    },
    "/api/v1/access-sessions/{session_id}": {
      "put": {
        "operationId": "replaceAccessSession",
        "summary": "按版本替换受限会话",
        "x-core-public": false,
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AccessSession"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccessSessionUpdate"
              }
            }
          }
        },
        "tags": ["受限会话"]
      },
      "delete": {
        "operationId": "revokeAccessSession",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          }
        ],
        "responses": {
          "204": {
            "description": "已撤销（终态）"
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "summary": "撤销受限会话",
        "tags": ["受限会话"]
      }
    },
    "/api/v1/access-session-revocations": {
      "post": {
        "operationId": "revokeBusinessSession",
        "x-core-public": false,
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [],
        "responses": {
          "204": {
            "description": "成功"
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SessionRevocationRequest"
              }
            }
          }
        },
        "summary": "撤销业务登录引用",
        "tags": ["受限会话"]
      }
    },
    "/api/v1/admin/service-credentials": {
      "post": {
        "operationId": "createServiceCredential",
        "x-core-public": false,
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [],
        "responses": {
          "201": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ServiceCredential"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ServiceCredentialRequest"
              }
            }
          }
        },
        "summary": "创建服务 Key/Secret",
        "tags": ["服务与机房凭据"]
      }
    },
    "/api/v1/admin/service-credentials/{credential_id}": {
      "delete": {
        "operationId": "disableServiceCredential",
        "x-core-public": false,
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [
          {
            "name": "credential_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          }
        ],
        "responses": {
          "204": {
            "description": "成功"
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "summary": "停用服务凭据",
        "tags": ["服务与机房凭据"]
      }
    },
    "/api/v1/admin/boxes/{box_id}/reservations": {
      "post": {
        "operationId": "reserveBox",
        "x-core-public": false,
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "本次主动操作的唯一幂等键。重传相同请求保留原键；响应未知先查原键，不能自动换新键重新写入。"
          },
          {
            "name": "box_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Core 云卡 ID（字符串）。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "云卡预留成功回执。返回预留引用、期限和本次版本，不返回 reservation.state；preparing、active、consumed、expired 是内部预留账本状态，不能据此向响应补造 state 字段。返回成功时已完成本次交接检查；相同幂等键返回原回执。",
                      "properties": {
                        "reservation_id": {
                          "type": "string",
                          "description": "本次创建的预留 ID；有效预留用于 allocateBox。"
                        },
                        "box_id": {
                          "type": "string",
                          "description": "本次操作的云卡 ID。"
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time",
                          "description": "预留到期时间（UTC RFC3339）。到期后不能再进行新分配；同幂等键的历史成功回执不替代后续分配时的有效性校验。"
                        },
                        "version": {
                          "type": "integer",
                          "description": "本次命令成功后返回的 allocation_version；用于后续命令的 expected_version。相同幂等键重放返回原回执，不保证它仍是当前最新版本。"
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReservationRequest"
              }
            }
          }
        },
        "summary": "预留云卡并开始技术交接",
        "tags": ["云卡分配与交接"]
      }
    },
    "/api/v1/admin/boxes/{box_id}/allocations": {
      "post": {
        "operationId": "allocateBox",
        "x-core-public": false,
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "本次主动操作的唯一幂等键。重传相同请求保留原键；响应未知先查原键，不能自动换新键重新写入。"
          },
          {
            "name": "box_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Core 云卡 ID（字符串）。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "将有效预留消费为正式技术分配后的成功回执。响应不返回 state；成功时云卡 allocation_state 变为 allocated，内部预留变为 consumed。相同幂等键返回原回执，当前分配状态应读取云卡资源。",
                      "properties": {
                        "box_id": {
                          "type": "string",
                          "description": "本次操作的云卡 ID。"
                        },
                        "allocation_ref": {
                          "type": "string",
                          "description": "新建的分配技术引用。后续会话授权、操作和文件归属使用该引用；释放或换代后旧引用失效。"
                        },
                        "not_after": {
                          "type": "string",
                          "format": "date-time",
                          "description": "本次分配的授权截止时间（UTC RFC3339），来自请求的 not_after。"
                        },
                        "version": {
                          "type": "integer",
                          "description": "本次命令成功后返回的 allocation_version；用于后续命令的 expected_version。相同幂等键重放返回原回执，不保证它仍是当前最新版本。"
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AllocationRequest"
              }
            }
          }
        },
        "summary": "将预留云卡分配给服务身份",
        "tags": ["云卡分配与交接"]
      }
    },
    "/api/v1/admin/boxes/{box_id}/release-requests": {
      "post": {
        "operationId": "requestBoxRelease",
        "x-core-public": false,
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "本次主动操作的唯一幂等键。重传相同请求保留原键；响应未知先查原键，不能自动换新键重新写入。"
          },
          {
            "name": "box_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Core 云卡 ID（字符串）。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "开始资源释放的成功回执；只确认进入释放流程，不表示清理已经完成或资源已可重新分配。相同幂等键重放返回原回执，读取当前云卡以确认最新状态。",
                      "properties": {
                        "box_id": {
                          "type": "string",
                          "description": "本次操作的云卡 ID。"
                        },
                        "allocation_ref": {
                          "type": "string",
                          "description": "正在释放的原分配技术引用。"
                        },
                        "state": {
                          "type": "string",
                          "enum": ["releasing"],
                          "description": "releasing=原分配已进入释放与清理确认阶段；云卡尚不可重新分配，需完成清理并提交 confirmBoxRelease。"
                        },
                        "version": {
                          "type": "integer",
                          "description": "本次命令成功后返回的 allocation_version；用于后续命令的 expected_version。相同幂等键重放返回原回执，不保证它仍是当前最新版本。"
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReleaseRequest"
              }
            }
          }
        },
        "summary": "开始释放云卡",
        "tags": ["云卡分配与交接"]
      }
    },
    "/api/v1/admin/boxes/{box_id}/release-confirmations": {
      "post": {
        "operationId": "confirmBoxRelease",
        "x-core-public": false,
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "本次主动操作的唯一幂等键。重传相同请求保留原键；响应未知先查原键，不能自动换新键重新写入。"
          },
          {
            "name": "box_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Core 云卡 ID（字符串）。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "接受调用方清理确认与证据引用、并通过交接检查后的成功回执。原分配账本变为 released，云卡 allocation_state 变为 unallocated 并生成新的 management_ref。相同幂等键返回原回执，不代表云卡之后未再分配。",
                      "properties": {
                        "box_id": {
                          "type": "string",
                          "description": "本次操作的云卡 ID。"
                        },
                        "state": {
                          "type": "string",
                          "enum": ["released"],
                          "description": "released=本次原分配的释放已经确认。该值属于释放命令回执；云卡资源本身使用 allocation_state=unallocated，不使用 released。"
                        },
                        "version": {
                          "type": "integer",
                          "description": "本次命令成功后返回的 allocation_version；用于后续命令的 expected_version。相同幂等键重放返回原回执，不保证它仍是当前最新版本。"
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReleaseConfirmation"
              }
            }
          }
        },
        "summary": "确认清理并完成云卡释放",
        "tags": ["云卡分配与交接"]
      }
    },
    "/api/v1/access-sessions/by-reference": {
      "get": {
        "operationId": "getAccessSessionByReference",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [
          {
            "name": "business_session_ref",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          },
          {
            "name": "actor_ref",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          }
        ],
        "responses": {
          "200": {
            "description": "当前有效受限会话，仅供签发服务身份读取",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AccessSession"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "summary": "按业务登录引用查询受限会话",
        "tags": ["受限会话"]
      }
    },
    "/health/live": {
      "get": {
        "operationId": "getLiveness",
        "x-core-public": false,
        "security": [],
        "responses": {
          "200": {
            "description": "状态和已实现能力",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": ["status"],
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": ["live"],
                          "description": "live=当前 API 进程能响应；不代表数据库、机房、设备或 Worker 可用。"
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "parameters": [],
        "summary": "进程存活检查",
        "tags": ["状态与能力"]
      }
    },
    "/health/ready": {
      "get": {
        "operationId": "getReadiness",
        "x-core-public": false,
        "security": [],
        "responses": {
          "200": {
            "description": "状态和已实现能力",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": ["status"],
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": ["ready"],
                          "description": "ready=本次数据库/schema 与 Redis 检查通过；不保证设备或媒体链路可用。"
                        },
                        "worker": {
                          "oneOf": [
                            {
                              "$ref": "#/components/schemas/FcBackgroundHealth"
                            },
                            {
                              "type": "string",
                              "enum": ["separate_process"],
                              "description": "独立 Worker 宿主，当前 HTTP 进程无法确认后台状态。"
                            }
                          ]
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "parameters": [],
        "summary": "数据库与 Redis 就绪检查",
        "description": "证明当前 Core 数据库/schema 与 Redis 检查通过。FC 宿主另附 worker.global_ready；API 就绪不等于任务后台就绪，后台监控使用 /health/worker。",
        "tags": ["状态与能力"]
      }
    },
    "/health/worker": {
      "get": {
        "operationId": "getWorkerReadiness",
        "x-core-public": false,
        "security": [],
        "parameters": [],
        "summary": "全局后台任务就绪检查",
        "description": "检查数据库/schema、Redis 和共享调度租约。只有已完成启动且租约有效的后台返回 200；全局待命、迁移暂停或无法确认后台时返回 503。多实例中的普通 standby 在其他实例为健康 leader 时仍返回 200。独立 API/Worker 宿主无法从此处确认后台，返回 503；不触发后台启用、迁移或设备操作。",
        "tags": ["状态与能力"],
        "responses": {
          "200": {
            "description": "共享后台可执行任务；不代表具体机房/设备操作成功。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": ["status", "worker"],
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": ["ready", "unavailable"]
                        },
                        "worker": {
                          "oneOf": [
                            {
                              "$ref": "#/components/schemas/FcBackgroundHealth"
                            },
                            {
                              "type": "string",
                              "enum": ["separate_process"],
                              "description": "独立 Worker 宿主，当前 HTTP 进程无法确认后台状态。"
                            }
                          ]
                        },
                        "code": {
                          "type": "string",
                          "enum": ["CORE_WORKER_UNAVAILABLE"]
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "共享后台不可用或未能确认；data.code 为 CORE_WORKER_UNAVAILABLE。数据库/schema 检查失败时使用 Problem Details。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": ["status", "worker"],
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": ["ready", "unavailable"]
                        },
                        "worker": {
                          "oneOf": [
                            {
                              "$ref": "#/components/schemas/FcBackgroundHealth"
                            },
                            {
                              "type": "string",
                              "enum": ["separate_process"],
                              "description": "独立 Worker 宿主，当前 HTTP 进程无法确认后台状态。"
                            }
                          ]
                        },
                        "code": {
                          "type": "string",
                          "enum": ["CORE_WORKER_UNAVAILABLE"]
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              },
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/capabilities": {
      "get": {
        "operationId": "getCapabilities",
        "x-core-public": true,
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "状态和已实现能力",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "power": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": ["start", "stop", "restart"],
                            "description": "start=开机；stop=关机；restart=重启。"
                          },
                          "description": "全局开关机动作集合：start=开机；stop=关机；restart=重启。不包括 repair；具体目标是否可执行仍查云机 capabilities。"
                        },
                        "h265": {
                          "type": "boolean",
                          "description": "true=Core 配置启用此能力；false=未启用。不能代替真实机房、设备或存储链路验收。"
                        },
                        "tcg": {
                          "type": "boolean",
                          "description": "true=Core 配置启用此能力；false=未启用。不能代替真实机房、设备或存储链路验收。"
                        },
                        "oss": {
                          "type": "boolean",
                          "description": "true=Core 配置启用此能力；false=未启用。不能代替真实机房、设备或存储链路验收。"
                        },
                        "task_actions": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "start",
                              "stop",
                              "restart",
                              "repair",
                              "create",
                              "remove",
                              "recycle",
                              "restore",
                              "factory_reset",
                              "new_device",
                              "app_install",
                              "app_start",
                              "app_stop",
                              "app_restart",
                              "app_uninstall",
                              "file_push",
                              "screenshot",
                              "backup_export",
                              "backup_restore",
                              "proxy",
                              "adb_shell",
                              "resolution",
                              "rotation",
                              "device_profile",
                              "accessibility_service",
                              "sms",
                              "app_install_url",
                              "file_push_url",
                              "qrcode",
                              "flow_play",
                              "accessibility_enable",
                              "accessibility_hide",
                              "dns",
                              "container_config"
                            ],
                            "description": "本次持久请求的技术动作名称。单个任务内全部目标使用同一动作；权限、支持provider、参数和成功语义随动作而定。\n\n动作取值：start=开机；stop=关机；restart=重启；repair=修复云机（不隐式开关机或重置）；create=在云卡创建新云机；remove=永久移除云机；recycle=移入回收站；restore=从回收站恢复；factory_reset=恢复出厂（清除应用和数据，保留基础硬件 ID）；new_device=一键新机（另重新生成基础配置和硬件 ID）；app_install=从 Core 安装包安装应用；app_start=启动应用；app_stop=停止应用；app_restart=重启应用；app_uninstall=卸载应用；file_push=将 Core 文件推送到云机；screenshot=截图；backup_export=导出备份并交付到 Core；backup_restore=向云卡导入备份并创建新云机；proxy=保存代理配置；adb_shell=执行 ADB shell 命令；resolution=设置分辨率；rotation=设置屏幕方向；device_profile=旧设备档案修改；accessibility_service=设置指定无障碍服务；sms=向云机发送模拟接收短信；app_install_url=从链接下载安装应用；file_push_url=从链接下载并推送到云机；qrcode=设置相机底图；flow_play=视频摄像头换源；accessibility_enable=打开应用无障碍入口；accessibility_hide=隐藏应用无障碍入口（不等于隐藏应用）；dns=保存 DNS 配置；container_config=保存六组容器配置。"
                          },
                          "description": "当前 Core 已识别的持久任务动作集合；不代表所有机房、provider、目标和身份均可执行。"
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "parameters": [],
        "summary": "查询 Core 版本与全局能力",
        "tags": ["状态与能力"]
      }
    },
    "/api/v1/admin/room-credentials/{server_id}": {
      "get": {
        "operationId": "getRoomCredential",
        "summary": "查询机房凭据状态（不返回密钥）",
        "description": "仅返回数据库机房专属凭据元数据，不返回密钥或摘要；无记录返回404。auth_mode描述当前统一鉴权模式。",
        "x-core-public": false,
        "x-core-visibility": "service",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [
          {
            "name": "server_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^(?!sn-)[A-Za-z0-9_-]{1,24}$",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "登记机房的 server_id。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RoomCredentialInfo"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["服务与机房凭据"]
      },
      "post": {
        "operationId": "issueRoomCredential",
        "summary": "首次发放机房凭据",
        "description": "首次签发或导入机房专属凭据；已有记录返回409。shared模式允许预配数据库记录，但不改变shared鉴权。room_key仅在此次成功响应返回，写请求不自动重试。",
        "x-core-public": false,
        "x-core-visibility": "service",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [
          {
            "name": "server_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^(?!sn-)[A-Za-z0-9_-]{1,24}$",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "登记机房的 server_id。"
          }
        ],
        "responses": {
          "201": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/IssuedRoomCredential"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoomCredentialIssueRequest"
              }
            }
          }
        },
        "tags": ["服务与机房凭据"]
      }
    },
    "/api/v1/admin/room-credentials/{server_id}/rotations": {
      "post": {
        "operationId": "rotateRoomCredential",
        "summary": "轮换机房凭据",
        "description": "以expected_version做CAS并签发新专属密钥；新密钥仅在此次成功响应返回，写请求不自动重试。shared模式不受单机房记录变更影响。",
        "x-core-public": false,
        "x-core-visibility": "service",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [
          {
            "name": "server_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^(?!sn-)[A-Za-z0-9_-]{1,24}$",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "登记机房的 server_id。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/IssuedRoomCredential"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoomCredentialVersionRequest"
              }
            }
          }
        },
        "tags": ["服务与机房凭据"]
      }
    },
    "/api/v1/admin/room-credentials/{server_id}/disable": {
      "post": {
        "operationId": "disableRoomCredential",
        "summary": "停用机房凭据",
        "description": "以expected_version停用数据库专属凭据；仅database统一鉴权模式受单机房状态限制。",
        "x-core-public": false,
        "x-core-visibility": "service",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [
          {
            "name": "server_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^(?!sn-)[A-Za-z0-9_-]{1,24}$",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "登记机房的 server_id。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RoomCredentialInfo"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoomCredentialVersionRequest"
              }
            }
          }
        },
        "tags": ["服务与机房凭据"]
      }
    },
    "/api/v1/admin/room-credentials/{server_id}/revocations": {
      "post": {
        "operationId": "revokeRoomCredential",
        "summary": "吊销机房凭据",
        "description": "以expected_version吊销数据库专属凭据；仅database统一鉴权模式受单机房状态限制。",
        "x-core-public": false,
        "x-core-visibility": "service",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [
          {
            "name": "server_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^(?!sn-)[A-Za-z0-9_-]{1,24}$",
              "minLength": 1,
              "maxLength": 24
            },
            "description": "登记机房的 server_id。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RoomCredentialInfo"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RoomCredentialVersionRequest"
              }
            }
          }
        },
        "tags": ["服务与机房凭据"]
      }
    },
    "/api/v1/boxes/{resource_id}": {
      "get": {
        "operationId": "getBox",
        "summary": "查询云卡详情",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "resource_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Box"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["云卡与云机"]
      }
    },
    "/api/v1/envs/{resource_id}": {
      "get": {
        "operationId": "getEnv",
        "summary": "查询云机详情",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "resource_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Env"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "description": "返回最近一次机房同步库存；判断运行可用须同时检查 status 与 wifi_status 为 running，不能仅依据其中一个字段。",
        "tags": ["云卡与云机"]
      }
    },
    "/api/v1/env-groups": {
      "get": {
        "operationId": "listEnvGroups",
        "summary": "查询云机分组",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "box_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云卡 ID（字符串）。"
          },
          {
            "name": "server_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "登记机房的 server_id。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          }
                        },
                        "required": ["id", "name"],
                        "additionalProperties": false
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["云卡与云机"]
      }
    },
    "/api/v1/rooms": {
      "get": {
        "operationId": "listRooms",
        "summary": "查询可见机房",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "server_id": {
                            "type": "string",
                            "description": "已登记机房标识。"
                          },
                          "name": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": ["online", "offline"],
                            "description": "online=登记机房在线；offline=机房离线。不是云机的开关机或网络状态。"
                          }
                        },
                        "required": ["id", "server_id", "name", "status"],
                        "additionalProperties": false
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["云卡与云机"]
      }
    },
    "/api/v1/envs/{env_id}": {
      "patch": {
        "operationId": "updateEnvMetadata",
        "summary": "更新 Core 云机名称或分组",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云机 ID（字符串），不是 MXWeb 容器编号。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Env"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EnvMetadataRequest"
              }
            }
          }
        },
        "tags": ["云卡与云机"]
      }
    },
    "/api/v1/envs/{env_id}/capabilities": {
      "get": {
        "operationId": "getEnvCapabilities",
        "summary": "查询云机各动作的支持与可执行状态",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云机 ID（字符串），不是 MXWeb 容器编号。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EnvCapabilities"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["设备读取与配置"]
      }
    },
    "/api/v1/envs/{env_id}/apps": {
      "get": {
        "operationId": "listEnvApps",
        "summary": "查询云机已安装应用",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云机 ID（字符串），不是 MXWeb 容器编号。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": false,
                        "required": ["package_name"],
                        "properties": {
                          "package_name": {
                            "type": "string",
                            "description": "Android 应用包名；启动、停止或卸载时使用此真实包名。"
                          },
                          "system": {
                            "type": "boolean",
                            "description": "true=已核实为系统应用；false=已核实为用户应用；字段缺省=无法确认分类，不要默认成用户应用。"
                          },
                          "label": {
                            "type": "string",
                            "maxLength": 255,
                            "description": "可可靠读取时返回的应用名称；缺省时可展示包名，不编造名称。"
                          },
                          "version_name": {
                            "type": "string",
                            "maxLength": 255,
                            "description": "可可靠读取时返回的应用版本名称；缺省不等于版本为 0。"
                          }
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["设备读取与配置"]
      }
    },
    "/api/v1/tasks/preflight": {
      "post": {
        "operationId": "preflightTask",
        "summary": "预检固定目标（不执行设备操作）",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Preflight"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskRequest"
              }
            }
          }
        },
        "description": "只核对全部固定目标的权限、资源版本及动作条件，不创建任务、不修改设备。executable=true 只表示本次预检可执行，提交时仍会再次校验。",
        "tags": ["持久化任务"]
      }
    },
    "/api/v1/tasks": {
      "post": {
        "operationId": "createTask",
        "summary": "创建异步设备任务",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "本次主动操作的唯一幂等键。重传相同请求保留原键；响应未知先查原键，不能自动换新键重新写入。"
          }
        ],
        "responses": {
          "202": {
            "description": "Core 已持久受理异步任务；不是设备执行成功。按返回 task_id 查询原任务及逐目标结果。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Task"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskRequest"
              }
            }
          }
        },
        "description": "HTTP 202 表示 Core 已持久受理，并非设备执行成功。保存 task_id 与原 Idempotency-Key，随后查询任务；按 items[].status/result/observation 展示逐目标结果。未知响应只查询原键，不能自动换新键重复提交。",
        "tags": ["持久化任务"]
      },
      "get": {
        "operationId": "listTasks",
        "summary": "分页查询任务历史",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "页码，从 1 开始。"
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            },
            "description": "每页条数，响应 meta.page_size 返回实际采用值。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Task"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "description": "分页来自持久任务历史；每条记录包括原固定目标和逐目标结果。total 是任务总数，不是云机数。",
        "tags": ["持久化任务"]
      }
    },
    "/api/v1/tasks/{task_id}/cancel": {
      "post": {
        "operationId": "cancelTask",
        "summary": "请求取消任务（不等于取消远端操作）",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Core 持久任务 ID；查询原任务不会重复执行设备操作。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Task"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "description": "尚未派发的项目可标记 cancelled；已派发项目仅设置 cancel_requested=true，不保证机房或设备命令停止，仍需查询原任务。",
        "tags": ["持久化任务"]
      }
    },
    "/api/v1/tasks/{task_id}/reconcile": {
      "post": {
        "operationId": "reconcileTask",
        "summary": "查询原机房操作并对账（不重新执行）",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Core 持久任务 ID；查询原任务不会重复执行设备操作。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Task"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "description": "只读取原 operation_id 的回执、状态或已生成制品并应用结果；不会重新提交设备写操作。",
        "tags": ["持久化任务"]
      }
    },
    "/api/v1/files/uploads": {
      "post": {
        "operationId": "createFileUpload",
        "summary": "创建云端文件上传会话",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [],
        "responses": {
          "201": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/FileDescriptor"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UploadRequest"
              }
            }
          }
        },
        "description": "上传只保存到 Core 当前云卡文件库，不会自动推送文件到云机或安装 APK；后续另建 file_push / app_install 等任务。",
        "tags": ["文件传输"]
      }
    },
    "/api/v1/files/{file_id}": {
      "get": {
        "operationId": "getFile",
        "summary": "查询云端文件状态",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Core 文件 ID；只有 ready 文件可用于下载或设备任务。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/FileDescriptor"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["文件传输"]
      },
      "delete": {
        "operationId": "deleteFile",
        "summary": "删除云端文件",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Core 文件 ID；只有 ready 文件可用于下载或设备任务。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "file_id": {
                          "type": "string",
                          "description": "Core 文件 ID，用于查询文件或申请下载；不直接表示文件已 ready。"
                        },
                        "status": {
                          "type": "string",
                          "enum": ["deleted"],
                          "description": "deleted=Core 云端文件已删除；不表示云机内已推送的副本被删除。"
                        }
                      },
                      "required": ["file_id", "status"],
                      "additionalProperties": false
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["文件传输"]
      }
    },
    "/api/v1/files": {
      "get": {
        "operationId": "listFiles",
        "summary": "分页查询当前云卡文件库",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云机 ID（字符串），不是 MXWeb 容器编号。"
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["file", "app", "backup", "screenshot"],
              "description": "file=普通文件；app=APK 安装包；backup=备份文件；screenshot=截图文件。"
            }
          },
          {
            "name": "box_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云卡 ID（字符串）。"
          },
          {
            "name": "kinds",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^(file|app|backup|screenshot)(,(file|app|backup|screenshot)){0,3}$"
            },
            "description": "Unique comma-separated kinds; cannot be combined with kind."
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            },
            "description": "按文件名进行服务端搜索。"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000000,
              "default": 1
            },
            "description": "页码，从 1 开始。"
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 20
            },
            "description": "每页条数，响应 meta.page_size 返回实际采用值。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "oneOf": [
                        {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/FileDescriptor"
                          }
                        },
                        {
                          "$ref": "#/components/schemas/FilePage"
                        }
                      ]
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "description": "env_id and box_id are mutually exclusive. The env_id query retains the legacy array response. The box_id query returns a page in data, scoped to the current technical reference; pagination/name/kinds apply only to box_id. kind and kinds are mutually exclusive.",
        "tags": ["文件传输"]
      }
    },
    "/api/v1/files/{file_id}/complete": {
      "post": {
        "operationId": "completeFileUpload",
        "summary": "合并分片并校验文件",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Core 文件 ID；只有 ready 文件可用于下载或设备任务。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/FileDescriptor"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "description": "分片合并、大小与 SHA-256 校验成功后文件才进入 ready；只有 ready 才能下载或用于设备任务。",
        "tags": ["文件传输"]
      }
    },
    "/api/v1/files/{file_id}/transfers": {
      "post": {
        "operationId": "createFileTransfer",
        "summary": "签发短期文件下载票据",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Core 文件 ID；只有 ready 文件可用于下载或设备任务。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/FileTransfer"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "tags": ["文件传输"]
      }
    },
    "/api/v1/files/{file_id}/content": {
      "get": {
        "operationId": "downloadFile",
        "summary": "读取已就绪文件内容",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Core 文件 ID；只有 ready 文件可用于下载或设备任务。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["文件传输"]
      }
    },
    "/api/v1/files/{file_id}/parts/{part_number}": {
      "put": {
        "operationId": "uploadFilePart",
        "summary": "上传单个文件分片",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Core 文件 ID；只有 ready 文件可用于下载或设备任务。"
          },
          {
            "name": "part_number",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "单个分片已持久接收的回执；不代表整个文件 ready，也不代表已推送到设备。",
                      "properties": {
                        "file_id": {
                          "type": "string",
                          "description": "原 Core 上传文件 ID。"
                        },
                        "part_number": {
                          "type": "integer",
                          "description": "本次接收的分片序号，从 1 开始。"
                        },
                        "size_bytes": {
                          "type": "integer",
                          "description": "本分片实际接收的字节数，不是完整文件大小。"
                        },
                        "sha256": {
                          "type": "string",
                          "description": "本分片实际内容的 SHA-256；完整文件还需 complete 校验。"
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "tags": ["文件传输"]
      }
    },
    "/api/v1/envs/{env_id}/media-sessions": {
      "post": {
        "operationId": "createMediaSession",
        "summary": "签发 H.265 云机播放会话",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云机 ID（字符串），不是 MXWeb 容器编号。"
          }
        ],
        "responses": {
          "201": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/MediaSession"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "control": {
                    "type": "boolean",
                    "description": "仅支持控制模式；省略与 true 等价，false 不签发票据。"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "description": "签发最长 5 分钟的 Maxia 票据。成功票据允许设备控制，必须具有 stream:view 和 stream:control 权限；control=false 返回 MEDIA_VIEW_ONLY_UNSUPPORTED。关闭投屏由客户端关闭 WebSocket，Core 不主动断流。",
        "tags": ["投屏与预览"]
      }
    },
    "/api/v1/admin/rooms/{server_id}/media": {
      "put": {
        "operationId": "configureRoomMedia",
        "summary": "配置机房媒体入口",
        "x-core-public": false,
        "x-core-visibility": "service",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          }
        ],
        "parameters": [
          {
            "name": "server_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "登记机房的 server_id。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {},
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "media_url": {
                    "type": "string"
                  },
                  "signing_secret": {
                    "type": "string",
                    "minLength": 32,
                    "maxLength": 128
                  },
                  "runtime_owner": {
                    "type": "string",
                    "enum": ["preinstalled", "managed"],
                    "description": "preinstalled=复用机房已安装的媒体运行环境；managed=机房负责管理媒体运行环境。"
                  }
                },
                "required": ["media_url", "signing_secret", "runtime_owner"],
                "additionalProperties": false
              }
            }
          }
        },
        "tags": ["投屏与预览"]
      }
    },
    "/api/v1/file-transfers/{token}": {
      "get": {
        "operationId": "readFileTransfer",
        "summary": "凭短期票据读取文件",
        "x-core-public": false,
        "x-core-visibility": "internal",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{43}$"
            },
            "description": "短期文件传输票据；只允许读取指定文件，过期后须重新申请。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["文件传输"]
      }
    },
    "/api/v1/boxes/{box_id}/create-options": {
      "get": {
        "operationId": "getEnvCreateOptions",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "box_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云卡 ID（字符串）。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "box_id",
                        "allocation_version",
                        "images",
                        "models",
                        "executable"
                      ],
                      "properties": {
                        "box_id": {
                          "type": "string",
                          "pattern": "^[1-9][0-9]{0,19}$",
                          "description": "Core 云卡资源 ID（字符串）。"
                        },
                        "allocation_ref": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 128,
                          "description": "原技术分配引用；与授权及文件归属绑定，不可跨分配复用。"
                        },
                        "allocation_version": {
                          "type": "integer",
                          "description": "云卡技术分配版本；云卡级动作使用此值进行版本预检。"
                        },
                        "storage_backend": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 128,
                          "description": "机房报告的存储 provider，当前创建仅 local 可执行；ceph-bcache 表示 Ceph/bcache 扩展路径，其他值需兼容且按 executable 判断，不自动回退。"
                        },
                        "images": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": ["tag"],
                            "additionalProperties": false,
                            "properties": {
                              "tag": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 100,
                                "description": "创建请求 profile.tag 使用的镜像标识，须从当前候选选择。"
                              },
                              "status": {
                                "type": "integer",
                                "description": "镜像原始整数状态；当前 1 或缺省时可选，其他值不可作为可用镜像。机房未统一其他整数含义，客户端不要自行编造。"
                              }
                            }
                          },
                          "description": "当前机房提供的镜像候选列表。"
                        },
                        "models": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": ["tag"],
                            "additionalProperties": false,
                            "properties": {
                              "tag": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 100,
                                "description": "创建请求 profile.model 使用的型号标识。"
                              },
                              "detail": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 200,
                                "description": "型号详情文案。"
                              },
                              "brand": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 200,
                                "description": "设备品牌信息。"
                              },
                              "ver": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 200,
                                "description": "机房报告的设备版本描述，不是 Core 资源版本。"
                              },
                              "prefixes": {
                                "type": "array",
                                "maxItems": 32,
                                "uniqueItems": true,
                                "items": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 100
                                },
                                "description": "机型允许使用的镜像标签前缀。Android N 的标准工作台要求 ver 等于 Android N，且本数组包含 `mx<N>-`；镜像 tag 同时须以该前缀开头。缺失或空数组不能推断兼容。"
                              }
                            }
                          },
                          "description": "当前机房提供的设备型号候选列表。"
                        },
                        "capacity": {
                          "type": "object",
                          "properties": {
                            "total": {
                              "type": "integer",
                              "nullable": true,
                              "description": "符合当前筛选和授权范围的记录总数，不是当前页条数。"
                            },
                            "available": {
                              "type": "integer",
                              "nullable": true,
                              "description": "当前机房报告的剩余云机容量；null=没有可靠容量数据，不等于 0。"
                            }
                          },
                          "description": "当前机房容量观察；total/available 可为 null，表示未提供可靠数值。不是长期预留或执行成功保证。"
                        },
                        "create_power": {
                          "type": "string",
                          "enum": ["poweroff", "poweron", "unknown"],
                          "description": "默认创建后的电源行为：poweroff=停机创建；poweron=创建后启动；unknown=机房未提供可确认的电源行为。它不是某台现有云机的当前状态，也不是新云机已启动的证明。"
                        },
                        "executable": {
                          "type": "boolean",
                          "description": "true=当前云卡存在可用镜像、型号与创建条件；false=暂不可创建。即使 true，提交任务仍会复核权限和版本。"
                        },
                        "reason_code": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 128,
                          "description": "稳定机器可读原因码；仅在受阻或不可用时提供。开放字符串，客户端应兼容未知码。"
                        },
                        "defaults": {
                          "type": "object",
                          "required": ["profile"],
                          "additionalProperties": false,
                          "properties": {
                            "profile": {
                              "type": "object",
                              "additionalProperties": false,
                              "properties": {
                                "tag": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 100,
                                  "description": "默认镜像标识，仍须在当前候选中有效。"
                                },
                                "model": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 100,
                                  "description": "默认型号标识，仍须在当前候选中有效。"
                                },
                                "timezone": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 100,
                                  "description": "默认系统时区；auto 表示由机房按其现有自动行为处理，具体时区使用 IANA 名称。"
                                },
                                "language": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 100,
                                  "description": "默认系统语言；auto 表示由机房自动处理，具体语言使用有效语言标识。"
                                },
                                "dns": {
                                  "type": "array",
                                  "minItems": 1,
                                  "maxItems": 5,
                                  "items": {
                                    "type": "string",
                                    "format": "ipv4"
                                  },
                                  "description": "默认 IPv4 DNS 地址列表；缺少 defaults 不表示不支持此字段。"
                                }
                              }
                            }
                          },
                          "description": "Validated defaults for the fixed create profile contract; missing defaults do not restrict supported fields."
                        },
                        "kind": {
                          "type": "string",
                          "enum": ["create_options"]
                        },
                        "source": {
                          "type": "string",
                          "enum": ["core_snapshot", "unavailable"]
                        },
                        "snapshot_state": {
                          "type": "string",
                          "enum": [
                            "fresh",
                            "stale",
                            "missing",
                            "expired",
                            "epoch_changed"
                          ]
                        },
                        "snapshot_id": {
                          "type": "string",
                          "nullable": true
                        },
                        "collected_at": {
                          "type": "string",
                          "nullable": true
                        },
                        "received_at": {
                          "type": "string",
                          "nullable": true
                        },
                        "last_sync_error_code": {
                          "type": "string",
                          "nullable": true
                        },
                        "last_failure_at": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "summary": "读取当前云卡的创建选项与容量",
        "description": "只读取 Backend 启动后及每 10 分钟推送到 Core 的创建候选快照，GET 不访问机房，也不触发采集。缺失、过期或旧 epoch 时 executable=false；fresh 15分钟，stale最多24小时。重新读取只查询 Core；真正创建仍由机房实时复核。",
        "tags": ["云卡与云机"]
      }
    },
    "/api/v1/tasks/by-idempotency/{key}": {
      "get": {
        "operationId": "getTaskByIdempotency",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "原提交请求使用的 Idempotency-Key。"
          },
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "start",
                "stop",
                "restart",
                "repair",
                "create",
                "remove",
                "recycle",
                "restore",
                "factory_reset",
                "new_device",
                "app_install",
                "app_start",
                "app_stop",
                "app_restart",
                "app_uninstall",
                "file_push",
                "screenshot",
                "backup_export",
                "backup_restore",
                "proxy",
                "adb_shell",
                "resolution",
                "rotation",
                "device_profile",
                "accessibility_service",
                "sms",
                "app_install_url",
                "file_push_url",
                "qrcode",
                "flow_play",
                "accessibility_enable",
                "accessibility_hide",
                "dns",
                "container_config"
              ],
              "description": "原动作：start=开机；stop=关机；restart=重启；repair=修复云机（不隐式开关机或重置）；create=在云卡创建新云机；remove=永久移除云机；recycle=移入回收站；restore=从回收站恢复；factory_reset=恢复出厂（清除应用和数据，保留基础硬件 ID）；new_device=一键新机（另重新生成基础配置和硬件 ID）；app_install=从 Core 安装包安装应用；app_start=启动应用；app_stop=停止应用；app_restart=重启应用；app_uninstall=卸载应用；file_push=将 Core 文件推送到云机；screenshot=截图；backup_export=导出备份并交付到 Core；backup_restore=向云卡导入备份并创建新云机；proxy=保存代理配置；adb_shell=执行 ADB shell 命令；resolution=设置分辨率；rotation=设置屏幕方向；device_profile=旧设备档案修改；accessibility_service=设置指定无障碍服务；sms=向云机发送模拟接收短信；app_install_url=从链接下载安装应用；file_push_url=从链接下载并推送到云机；qrcode=设置相机底图；flow_play=视频摄像头换源；accessibility_enable=打开应用无障碍入口；accessibility_hide=隐藏应用无障碍入口（不等于隐藏应用）；dns=保存 DNS 配置；container_config=保存六组容器配置。"
            },
            "description": "原提交的任务动作，需与原幂等键一起查询。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "meta"],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Task"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "summary": "按原幂等键查找已受理任务",
        "description": "提交响应丢失时，携带原 Idempotency-Key 和原 action 查询受理结果；未查到任务也不能证明之前的设备操作一定没有发生。",
        "tags": ["持久化任务"]
      }
    },
    "/api/v1/tasks/{task_id}/recovery": {
      "post": {
        "operationId": "recoverTask",
        "summary": "恢复后续操作，保留原任务未知结果与清理门槛",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "Core 持久任务 ID；查询原任务不会重复执行设备操作。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Task"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expected_item_ids": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 200,
                    "uniqueItems": true,
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 128
                    },
                    "description": "本次要确认结束等待的原未知项目 item_id 精确集合，防止将新出现的未知项一并处理。"
                  },
                  "confirm_unfinished": {
                    "type": "boolean",
                    "enum": [true],
                    "description": "必须为 true：用户明确确认结束原未知项等待；不证明原设备命令已停止或成功。"
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500,
                    "description": "本次明确结束未知等待的原因，保存到审计；不能用于自动重做原命令。"
                  }
                },
                "required": ["expected_item_ids", "confirm_unfinished"],
                "additionalProperties": false
              }
            }
          }
        },
        "description": "明确确认后，仅允许后续操作继续；原项目保留 released_unknown 与审计事实，不代表原设备动作成功、失败或已取消，也不会重派原命令。",
        "tags": ["持久化任务"]
      }
    },
    "/api/v1/envs/{env_id}/network": {
      "get": {
        "operationId": "getEnvNetwork",
        "summary": "读取云机内网 IPv4 观测",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云机 ID（字符串），不是 MXWeb 容器编号。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Network"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["设备读取与配置"]
      }
    },
    "/api/v1/device-profile-fields": {
      "get": {
        "operationId": "getDeviceProfileFields",
        "summary": "查询旧设备档案可用字段",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DeviceProfileFields"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["设备读取与配置"]
      }
    },
    "/api/v1/envs/{env_id}/device-profile": {
      "get": {
        "operationId": "getEnvDeviceProfile",
        "summary": "读取脱敏设备档案",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云机 ID（字符串），不是 MXWeb 容器编号。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DeviceProfile"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["设备读取与配置"]
      }
    },
    "/api/v1/envs/{env_id}/accessibility-services": {
      "get": {
        "operationId": "getEnvAccessibilityServices",
        "summary": "查询应用无障碍服务",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云机 ID（字符串），不是 MXWeb 容器编号。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "services": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "service_key": {
                                "type": "string",
                                "description": "从设备读取的无障碍服务组件名（包名/服务类），设置时使用此真实值，不手工猜测。"
                              },
                              "enabled": {
                                "type": "boolean",
                                "description": "true=该服务当前处于启用列表；false=当前未启用，不代表该应用不存在。"
                              }
                            },
                            "required": ["service_key", "enabled"],
                            "additionalProperties": true
                          }
                        },
                        "env_id": {
                          "type": "string",
                          "description": "Core 云机资源 ID（字符串），不是机房容器编号。"
                        }
                      },
                      "required": ["services", "env_id"],
                      "additionalProperties": false
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["设备读取与配置"]
      }
    },
    "/api/v1/envs/{env_id}/backup-availability": {
      "get": {
        "operationId": "getEnvBackupAvailability",
        "summary": "查询备份功能可用性",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云机 ID（字符串），不是 MXWeb 容器编号。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/BackupAvailability"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["备份"]
      }
    },
    "/api/v1/app-catalog": {
      "get": {
        "operationId": "getAppCatalog",
        "summary": "查询可安装应用目录",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AppCatalog"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["设备读取与配置"]
      }
    },
    "/api/v1/backups": {
      "get": {
        "operationId": "listBackups",
        "summary": "分页查询已交付的备份历史",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "source_env_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "页码，从 1 开始。"
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            },
            "description": "每页条数，响应分页字段为 per_page。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/BackupList"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "description": "这里只列出 Core 内已就绪的备份文件。status=completed 表示该历史条目交付完成，不是原备份任务的任务状态；尚未完成的导出请查询原任务。",
        "tags": ["备份"]
      }
    },
    "/api/v1/backups/{backup_id}/download": {
      "get": {
        "operationId": "getBackupDownload",
        "summary": "获取就绪备份的短期下载地址",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "backup_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "备份条目 ID，对应已交付的 Core 备份文件。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/BackupDownload"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["备份"]
      }
    },
    "/api/v1/backups/{backup_id}": {
      "delete": {
        "operationId": "deleteBackup",
        "summary": "删除备份文件",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "backup_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "备份条目 ID，对应已交付的 Core 备份文件。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "backup_id": {
                          "type": "string"
                        },
                        "file_id": {
                          "type": "string",
                          "description": "Core 文件 ID，用于查询文件或申请下载；不直接表示文件已 ready。"
                        },
                        "status": {
                          "type": "string",
                          "enum": ["deleted"],
                          "description": "deleted=Core 备份文件已删除；不删除原云机，也不撤回已恢复的新云机。"
                        }
                      },
                      "required": ["backup_id", "file_id", "status"],
                      "additionalProperties": false
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["备份"]
      }
    },
    "/api/v1/boxes/{box_id}/backup-restores": {
      "post": {
        "operationId": "restoreBackupToBox",
        "summary": "在指定云卡导入备份并创建新云机",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "box_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云卡 ID（字符串）。"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "description": "本次主动操作的唯一幂等键。重传相同请求保留原键；响应未知先查原键，不能自动换新键重新写入。"
          }
        ],
        "responses": {
          "202": {
            "description": "Core 已持久受理异步任务；不是设备执行成功。按返回 task_id 查询原任务及逐目标结果。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Task"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "file_id": {
                        "type": "string",
                        "pattern": "^file_[A-Za-z0-9_-]+$",
                        "description": "Core 文件 ID，用于查询文件或申请下载；不直接表示文件已 ready。"
                      },
                      "expected_box_version": {
                        "type": "integer",
                        "minimum": 0
                      }
                    },
                    "required": ["expected_box_version", "file_id"],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "expected_box_version": {
                        "type": "integer",
                        "minimum": 0
                      },
                      "backup_id": {
                        "type": "string",
                        "pattern": "^file_[A-Za-z0-9_-]+$"
                      }
                    },
                    "required": ["expected_box_version", "backup_id"],
                    "additionalProperties": false
                  }
                ]
              }
            }
          }
        },
        "description": "将当前技术归属下的 ready 备份导入指定云卡并创建新云机，不能理解为覆盖原云机。202 仅表示受理，后续查原任务与新增库存。",
        "tags": ["备份"]
      }
    },
    "/api/v1/envs/{env_id}/configuration": {
      "get": {
        "operationId": "getEnvConfiguration",
        "summary": "读取分辨率、脱敏代理与 DNS 观测",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云机 ID（字符串），不是 MXWeb 容器编号。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/DeviceConfiguration"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["设备读取与配置"]
      }
    },
    "/api/v1/preview-grants": {
      "post": {
        "operationId": "createPreviewGrants",
        "summary": "为当前目标签发只读预览票据",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "实际浏览器 Origin（协议、主机、端口），用于预览票据来源校验。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PreviewRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Per-room success and per-target rejection; Cache-Control: no-store",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "enum": ["no-store"],
                  "description": "no-store=禁止缓存此授权或探测响应，避免跨身份复用短票或敏感观察。"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/PreviewGrants"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "description": "Requires stream:view and a current technical reference; powered-off/offline targets are permitted, stream:control and H.265 are not required. Maximum 50 unique env IDs. Tickets expire within 60 seconds and existing session/grant/allocation deadlines. Core persists expiry under resource locks before independently registering each room via its trusted /internal endpoint; failed/unknown rooms never return a ticket. HTTPS frontends require WSS; insecure WS is allowed only for loopback fixtures.",
        "tags": ["投屏与预览"]
      }
    },
    "/api/v1/envs/{env_id}/container-config": {
      "get": {
        "operationId": "getEnvContainerConfig",
        "summary": "读取六组脱敏容器保存配置",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云机 ID（字符串），不是 MXWeb 容器编号。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ContainerConfiguration"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "tags": ["设备读取与配置"]
      }
    },
    "/api/v1/envs/{env_id}/proxy-check": {
      "post": {
        "operationId": "checkEnvProxy",
        "summary": "检测机房代理出口（不保存云机配置）",
        "x-core-public": true,
        "x-core-visibility": "public",
        "security": [
          {
            "serviceKey": [],
            "serviceSecret": []
          },
          {
            "restrictedSession": []
          }
        ],
        "parameters": [
          {
            "name": "env_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "Core 云机 ID（字符串），不是 MXWeb 容器编号。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ProxyCheckResult"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "required": ["data", "meta"],
                  "additionalProperties": false
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "enum": ["no-store"],
                  "description": "no-store=禁止缓存此授权或探测响应，避免跨身份复用短票或敏感观察。"
                }
              }
            }
          },
          "default": {
            "description": "Problem Details 错误响应；status 是 HTTP 状态码，code 是稳定错误码，detail 用于解释，request_id 用于排查。",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProxyCheckRequest"
              }
            }
          }
        },
        "description": "Requires env:configure, a current resource version and technical reference. Scope is the machine-room outbound proxy/direct egress, not proof that the cloud device has adopted these settings. Credentials and raw diagnostics are never returned.",
        "tags": ["设备读取与配置"]
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "required": ["type", "title", "status", "code", "request_id"],
        "properties": {
          "type": {
            "type": "string",
            "description": "Problem 类型标识（URI）；用于描述错误类别。"
          },
          "title": {
            "type": "string",
            "description": "错误类型的简短标题。"
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599,
            "description": "本次错误响应的 HTTP 状态码，例如 401=未认证、403=无权限、404=不存在、409=版本或资源冲突、422=参数/业务前置条件不满足、5xx=服务端或依赖故障。不是云机状态或任务状态。"
          },
          "code": {
            "type": "string",
            "description": "稳定机器可读错误码，用于程序判断；这是开放字符串，新增错误码不应导致客户端崩溃。"
          },
          "detail": {
            "type": "string",
            "description": "本次错误的具体解释；可用于辅助提示，不作为稳定逻辑判断依据。"
          },
          "request_id": {
            "type": "string",
            "description": "本次 HTTP 请求的关联 ID，供日志排查；不是任务 ID 或幂等键。"
          },
          "errors": {
            "type": "object",
            "additionalProperties": true,
            "description": "可选的结构化错误补充，不同错误码内容不同。"
          },
          "invalid_params": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["name", "reason"],
              "additionalProperties": false,
              "properties": {
                "name": {
                  "type": "string",
                  "description": "出错参数名或字段路径。"
                },
                "reason": {
                  "type": "string",
                  "description": "该参数无效的原因。"
                }
              }
            },
            "description": "可定位到字段的参数校验错误列表，供表单就近展示。"
          }
        },
        "description": "统一错误响应。status 表示 HTTP 错误码，不是云机或任务状态；调用方按 code 分支，detail 可用于提示，request_id 用于关联日志。"
      },
      "BoxGrant": {
        "description": "单张云卡的受限授权；已分配资源使用 allocation_ref，未分配库存使用 management_ref，两者必须且只能提供一个。",
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "box_id",
              "allocation_ref",
              "not_after",
              "permissions"
            ],
            "properties": {
              "box_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[1-9][0-9]{0,19}$",
                "description": "Core 云卡资源 ID（字符串）。"
              },
              "allocation_ref": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "description": "原技术分配引用；与授权及文件归属绑定，不可跨分配复用。"
              },
              "not_after": {
                "type": "string",
                "format": "date-time"
              },
              "permissions": {
                "type": "array",
                "minItems": 1,
                "maxItems": 17,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "enum": [
                    "box:read",
                    "env:read",
                    "env:update",
                    "env:power",
                    "task:read",
                    "file:read",
                    "env:create",
                    "env:manage",
                    "env:apps",
                    "env:files",
                    "env:backup",
                    "env:configure",
                    "env:adb",
                    "file:write",
                    "task:cancel",
                    "stream:view",
                    "stream:control"
                  ],
                  "description": "权限代码：box:read=读取云卡，env:read=读取云机，env:update=修改名称/分组等元数据，env:power=开关机/重启，env:create=创建云机，env:manage=修复/重置/回收/恢复/删除等管理动作，env:apps=应用操作，env:files=设备文件/截图操作，env:backup=备份导出/恢复，env:configure=设备与网络配置，env:adb=ADB 命令，file:read=读取 Core 文件/下载，file:write=上传/删除 Core 文件，task:read=读取任务，task:cancel=请求取消任务，stream:view=只读预览，stream:control=可控制媒体会话。权限还受有效技术引用、授权期限和资源版本约束。"
                }
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "box_id",
              "management_ref",
              "not_after",
              "permissions"
            ],
            "properties": {
              "box_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[1-9][0-9]{0,19}$",
                "description": "Core 云卡资源 ID（字符串）。"
              },
              "management_ref": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "description": "未分配库存的当前管理引用；与 allocation_ref 互斥使用，交接后会改变。"
              },
              "not_after": {
                "type": "string",
                "format": "date-time"
              },
              "permissions": {
                "type": "array",
                "minItems": 1,
                "maxItems": 17,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "enum": [
                    "box:read",
                    "env:read",
                    "env:update",
                    "env:power",
                    "task:read",
                    "file:read",
                    "env:create",
                    "env:manage",
                    "env:apps",
                    "env:files",
                    "env:backup",
                    "env:configure",
                    "env:adb",
                    "file:write",
                    "task:cancel",
                    "stream:view",
                    "stream:control"
                  ],
                  "description": "权限代码：box:read=读取云卡，env:read=读取云机，env:update=修改名称/分组等元数据，env:power=开关机/重启，env:create=创建云机，env:manage=修复/重置/回收/恢复/删除等管理动作，env:apps=应用操作，env:files=设备文件/截图操作，env:backup=备份导出/恢复，env:configure=设备与网络配置，env:adb=ADB 命令，file:read=读取 Core 文件/下载，file:write=上传/删除 Core 文件，task:read=读取任务，task:cancel=请求取消任务，stream:view=只读预览，stream:control=可控制媒体会话。权限还受有效技术引用、授权期限和资源版本约束。"
                }
              }
            }
          }
        ]
      },
      "AccessSessionRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "business_session_ref",
          "actor_ref",
          "authorization_revision",
          "box_grants"
        ],
        "properties": {
          "business_session_ref": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "actor_ref": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "authorization_revision": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647
          },
          "box_grants": {
            "type": "array",
            "maxItems": 1000,
            "items": {
              "$ref": "#/components/schemas/BoxGrant"
            }
          }
        }
      },
      "AccessSessionUpdate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "business_session_ref",
          "actor_ref",
          "authorization_revision",
          "box_grants",
          "expected_version"
        ],
        "properties": {
          "business_session_ref": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "actor_ref": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "authorization_revision": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2147483647
          },
          "box_grants": {
            "type": "array",
            "maxItems": 1000,
            "items": {
              "$ref": "#/components/schemas/BoxGrant"
            }
          },
          "expected_version": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "AccessSession": {
        "type": "object",
        "required": [
          "session_id",
          "access_token",
          "expires_at",
          "authorization_revision",
          "session_version"
        ],
        "properties": {
          "session_id": {
            "type": "string",
            "description": "Core 受限会话 ID，用于替换或撤销，不是业务用户 ID。"
          },
          "access_token": {
            "type": "string",
            "description": "受限 opaque access token，以 `Authorization: Bearer <token>` 发送；不是 JWT，也不是服务 Secret。"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "此会话、文件或票据的到期时间（UTC RFC3339）；到期后不得继续复用。"
          },
          "authorization_revision": {
            "type": "integer",
            "description": "业务授权修订号；范围、动作或技术引用变化时由可信宿主递增。"
          },
          "session_version": {
            "type": "integer",
            "minimum": 1,
            "description": "当前会话版本，替换时用作 expected_version 防止并发覆盖。"
          }
        },
        "description": "由可信服务端创建的受限会话；用 access_token 作为 Bearer，仅允许授权云卡、动作与期限内的调用。"
      },
      "Meta": {
        "type": "object",
        "required": ["request_id"],
        "properties": {
          "request_id": {
            "type": "string",
            "description": "本次 HTTP 请求的关联 ID，供日志排查；不是任务 ID 或幂等键。"
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "description": "当前页码，从 1 开始。"
          },
          "page_size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "description": "当前页每页条数。"
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "符合当前筛选和授权范围的记录总数，不是当前页条数。"
          }
        }
      },
      "Box": {
        "type": "object",
        "required": ["id", "server_id", "status", "version"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Core 云卡资源 ID（字符串）；不是机房编号或设备容器 ID。"
          },
          "server_id": {
            "type": "string",
            "description": "已登记机房标识。"
          },
          "status": {
            "type": "string",
            "description": "云卡的库存在线状态：online=同步标记为在线，offline=同步标记为离线。该值不表示卡内每台云机或 WiFi 已运行。",
            "enum": ["online", "offline"]
          },
          "allocation_ref": {
            "type": "string",
            "nullable": true,
            "description": "原技术分配引用；与授权及文件归属绑定，不可跨分配复用。"
          },
          "management_ref": {
            "type": "string",
            "nullable": true,
            "description": "未分配库存的当前管理引用；与 allocation_ref 互斥使用，交接后会改变。"
          },
          "version": {
            "type": "integer",
            "description": "当前云卡 allocation_version 的兼容别名。云卡级操作的 expected_version / expected_versions 使用此技术版本。"
          },
          "name": {
            "type": "string",
            "description": "云卡展示名称。"
          },
          "ip": {
            "type": "string",
            "nullable": true,
            "description": "云卡节点地址；可为 null，客户端不应据此绕过 Core 直接调用设备。"
          },
          "allocation_state": {
            "type": "string",
            "description": "云卡技术分配状态：unallocated=未分配，使用 management_ref 管理；reserved=已预留、正在交接，拒绝新的设备操作；allocated=已分配，使用有效 allocation_ref；releasing=释放与清理确认中，拒绝新的设备操作。",
            "enum": ["unallocated", "reserved", "allocated", "releasing"]
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "该记录最后更新时间（UTC RFC3339），不是设备实时心跳或操作完成证明。"
          },
          "allocation_not_after": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "当前技术分配的有效截止时间；null 表示无当前分配期限，不代表无限业务套餐。"
          },
          "allocation_version": {
            "type": "integer",
            "minimum": 0,
            "description": "云卡技术分配版本；云卡级动作使用此值进行版本预检。"
          },
          "total_envs": {
            "type": "integer",
            "minimum": 0,
            "description": "该云卡当前库存中未删除且未回收的云机数量。"
          },
          "running_envs": {
            "type": "integer",
            "minimum": 0,
            "description": "该云卡当前库存中容器 status=running 的云机数量；不要求 wifi_status=running，不能直接当作可用云机数。"
          },
          "ready_envs": {
            "type": "integer",
            "minimum": 0,
            "description": "该云卡当前库存中未删除且未回收、容器 status 与 wifi_status 都为 running 的云机数量；是最近同步库存的统计，不是实时健康检查。"
          }
        },
        "description": "最近同步的云卡库存与当前技术分配信息。status 表示云卡在线情况；allocation_state 表示技术归属，两者独立。"
      },
      "Env": {
        "type": "object",
        "required": ["id", "box_id", "status", "version"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Core 云机资源 ID（字符串）；调用 Core 时使用此 ID，不要替换为 idx/cloud_id/ipd。"
          },
          "box_id": {
            "type": "string",
            "description": "Core 云卡资源 ID（字符串）。"
          },
          "status": {
            "type": "string",
            "description": "机房同步的容器状态，原样来自 sync_status。常见值：created=已创建但未运行（关机）；running=容器已开机；offline=机房离线或当前位置不可用；unknown=尚无可信状态。此字段是开放字符串，机房/provider 的其他值须兼容，不能误判为运行中。只有 status 与 wifi_status 同时为 running 才可展示运行可用；这仍不是实时连接或投屏验收。",
            "example": "running",
            "x-enumDescriptions": {
              "created": "已创建但未运行（关机）",
              "running": "容器已开机",
              "offline": "离线或当前位置不可用",
              "unknown": "尚无可信容器状态"
            }
          },
          "version": {
            "type": "integer",
            "description": "当前 resource_version 的兼容别名，用于提交前的版本预检。"
          },
          "name": {
            "type": "string",
            "description": "云机展示名称，当前优先 title，再使用设备地址等回退值；不是固定物理身份。"
          },
          "server_id": {
            "type": "string",
            "description": "已登记机房标识。"
          },
          "cloud_id": {
            "type": "string",
            "nullable": true,
            "description": "机房同步的物理云机标识；用于区分槽位重用，不是 Core 云机 ID。"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "该记录最后更新时间（UTC RFC3339），不是设备实时心跳或操作完成证明。"
          },
          "title": {
            "type": "string",
            "description": "Core 保存的用户自定义名称；不等同 MXWeb 容器 remark。"
          },
          "group_name": {
            "type": "string",
            "description": "Core 保存的云机分组名称；空字符串表示未分组。"
          },
          "model": {
            "type": "string",
            "description": "机房同步的设备型号信息；缺少时不应虚构默认型号。"
          },
          "ip": {
            "type": "string",
            "description": "云卡节点 IPv4；不是云机内网 IPv4，也不是代理出口 IP。"
          },
          "ipd": {
            "type": "string",
            "description": "云机设备地址，通常为 IP:端口，是工作台主要展示地址；不授予调用方直连 ADB 的权限。"
          },
          "idx": {
            "type": "integer",
            "minimum": 0,
            "description": "机房/MXWeb 的本地容器槽位编号；设备操作由机房根据固定目标使用，不能当作 Core env_id。"
          },
          "resource_version": {
            "type": "integer",
            "minimum": 0,
            "description": "云机资源版本；提交操作时通过 expected_versions 校验，版本改变后需刷新，不是时间戳。"
          },
          "lease_id": {
            "type": "string",
            "nullable": true,
            "description": "机房/provider 租约标识；可为 null，用于固定物理目标，不是业务订单号。"
          },
          "recycled_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "回收时间；null=未回收，非空=已移入回收站。回收与容器开关机状态是不同维度。"
          },
          "wifi_status": {
            "type": "string",
            "description": "机房同步的 WiFi/网络就绪状态。常见值：created=网络尚未就绪或不可用；running=网络已就绪；offline=离线；unknown=机房未提供有效网络观测或尚无法确认。此字段是开放字符串，保留机房/provider 的其他值。只有 wifi_status 与 status 同时为 running 才可展示运行可用，不可仅凭其中一项推断设备可连接。",
            "example": "running",
            "x-enumDescriptions": {
              "created": "网络尚未就绪或不可用",
              "running": "网络已就绪",
              "offline": "离线",
              "unknown": "尚无可信网络观测"
            }
          },
          "box_last_sync_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "所属云卡同步通道最后接收时间；不是此云机实时观测时间"
          },
          "sync_source": {
            "type": "string",
            "enum": ["box_state_cursor"],
            "description": "库存观测来源。box_state_cursor=所属云卡的 box-state 同步游标；box_last_sync_at 仅为该云卡同步通道的最后接收时间，不是逐台云机的实时观测。"
          }
        },
        "description": "最近一次机房同步的云机库存。容器开关机、网络就绪、回收状态和任务执行是不同维度。判断运行可用须 status 与 wifi_status 都为 running。",
        "example": {
          "id": "11",
          "box_id": "2",
          "status": "running",
          "wifi_status": "created",
          "version": 3,
          "resource_version": 3,
          "ipd": "192.0.2.41:12003"
        }
      },
      "Stats": {
        "type": "object",
        "required": ["total", "by_status"],
        "properties": {
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "符合当前筛选和授权范围的记录总数，不是当前页条数。"
          },
          "by_status": {
            "type": "object",
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "按库存状态统计的数量字典。云卡使用 online/offline；云机使用机房同步的容器 status 原值，不结合 wifi_status。未知键应原样处理。"
          },
          "ready_envs": {
            "type": "integer",
            "minimum": 0,
            "description": "当前筛选与授权范围中 status 和 wifi_status 同时为 running 的未删除、未回收云机数量；by_status 仍只按容器状态统计。"
          }
        },
        "description": "当前筛选和授权范围的库存统计。total / by_status 按资源列表统计；ready_envs 专门统计双 running 的云机，不能把 by_status.running 当成网络可用数量。"
      },
      "PowerRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["env_ids", "action", "expected_versions"],
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["start"],
            "description": "任务动作：start=开机。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          }
        }
      },
      "Task": {
        "type": "object",
        "required": ["task_id", "status"],
        "properties": {
          "task_id": {
            "type": "string",
            "description": "Core生成的持久任务标识（不透明字符串）；保存此值用于刷新、查询和原任务恢复，不与机房旧数字任务ID互换。",
            "example": "tsk_example"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "running",
              "succeeded",
              "failed",
              "cancel_requested",
              "cancelled",
              "needs_reconciliation",
              "released_unknown"
            ],
            "description": "整批聚合状态。优先级为needs_reconciliation > running > pending > released_unknown > 全部cancelled/全部succeeded/其余failed；不是逐台成功率。 枚举：pending=已持久受理，仍有目标等待派发；running=仍有目标正在执行，或Core正在接收机房已生成的文件；不等于Android已运行；succeeded=所有目标按各动作的成功合同完成；动作ACK不自动证明设备可用；failed=没有待执行、执行中或待确认项，且结果未达到全部成功；可含部分成功或成功与取消混合，必须查看逐项结果；cancel_requested=兼容保留值；当前实现将取消请求记录为items[].cancel_requested，不单独生成此任务状态；cancelled=全部目标均在派发前取消，未发出设备操作；needs_reconciliation=至少一个目标结果待确认，或机房文件尚未完成中心交付；保留原任务/operation查询，不能当作失败或自动重发设备写；released_unknown=没有更高优先级的未完成项，且至少一个未知项已由用户确认结束等待；原结果仍未知，不表示操作成功、失败或远端已停止。",
            "x-enumDescriptions": {
              "pending": "已持久受理，仍有目标等待派发",
              "running": "仍有目标正在执行，或Core正在接收机房已生成的文件；不等于Android已运行",
              "succeeded": "所有目标按各动作的成功合同完成；动作ACK不自动证明设备可用",
              "failed": "没有待执行、执行中或待确认项，且结果未达到全部成功；可含部分成功或成功与取消混合，必须查看逐项结果",
              "cancel_requested": "兼容保留值；当前实现将取消请求记录为items[].cancel_requested，不单独生成此任务状态",
              "cancelled": "全部目标均在派发前取消，未发出设备操作",
              "needs_reconciliation": "至少一个目标结果待确认，或机房文件尚未完成中心交付；保留原任务/operation查询，不能当作失败或自动重发设备写",
              "released_unknown": "没有更高优先级的未完成项，且至少一个未知项已由用户确认结束等待；原结果仍未知，不表示操作成功、失败或远端已停止"
            }
          },
          "result": {
            "description": "兼容预留字段；当前TaskService.view不输出顶层汇总结果，动作结果位于items[].result。客户端不应依赖此字段存在。"
          },
          "error_code": {
            "type": "string",
            "nullable": true,
            "description": "兼容预留字段；当前TaskService.view不输出顶层错误码。应读取items[].result.code和detail，并结合逐项status处理。"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["env_id", "box_id", "status", "operation_id"],
              "properties": {
                "env_id": {
                  "type": "string",
                  "nullable": true,
                  "description": "云机资源ID，保持字符串。create及backup_restore是云卡级任务，此值为null；不把新创建云机ID提前填入原任务。"
                },
                "box_id": {
                  "type": "string",
                  "description": "固定目标或目标云机所属的云卡资源ID，保持字符串；不能当作MXWeb容器编号。"
                },
                "status": {
                  "type": "string",
                  "description": "当前目标项状态；比result.status更适合判断当前生命周期，后者可能保留上次回执。 枚举：pending=已受理，尚未派发此目标；只有此阶段的取消可确认未执行设备写；running=此目标已交给执行器，或正在接收原机房制品；不保证远端仍在线执行；succeeded=此目标满足对应动作成功合同；例如保存配置只表示已保存，修复只表示接口确认，截图/备份还需中心文件ready；failed=此目标有明确失败结果或派发前校验失败；不把网络超时、丢ACK或交付受阻直接归为此状态；cancelled=此目标在派发前取消，未派发设备操作；needs_reconciliation=至少一个目标结果待确认，或机房文件尚未完成中心交付；保留原任务/operation查询，不能当作失败或自动重发设备写；released_unknown=用户确认结束此目标的未知等待；保留原未知结果和可能迟到的回执，不宣称成功或远端终止。",
                  "enum": [
                    "pending",
                    "running",
                    "succeeded",
                    "failed",
                    "cancelled",
                    "needs_reconciliation",
                    "released_unknown"
                  ],
                  "x-enumDescriptions": {
                    "pending": "已受理，尚未派发此目标；只有此阶段的取消可确认未执行设备写",
                    "running": "此目标已交给执行器，或正在接收原机房制品；不保证远端仍在线执行",
                    "succeeded": "此目标满足对应动作成功合同；例如保存配置只表示已保存，修复只表示接口确认，截图/备份还需中心文件ready",
                    "failed": "此目标有明确失败结果或派发前校验失败；不把网络超时、丢ACK或交付受阻直接归为此状态",
                    "cancelled": "此目标在派发前取消，未派发设备操作",
                    "needs_reconciliation": "至少一个目标结果待确认，或机房文件尚未完成中心交付；保留原任务/operation查询，不能当作失败或自动重发设备写",
                    "released_unknown": "用户确认结束此目标的未知等待；保留原未知结果和可能迟到的回执，不宣称成功或远端终止"
                  }
                },
                "operation_id": {
                  "type": "string",
                  "description": "此目标的固定机房持久操作ID；未知结果只能查询这个原operation，不能生成新ID重发设备写。用户明确发起新的尝试才创建新任务。"
                },
                "result": {
                  "$ref": "#/components/schemas/TaskItemResult"
                },
                "item_id": {
                  "type": "string",
                  "description": "Core持久目标项ID，用于原任务未知项恢复时的expected_item_ids精确集合匹配。"
                },
                "action": {
                  "type": "string",
                  "description": "兼容预留字段；当前目标项view未输出此字段，动作取Task.action。"
                },
                "cancel_requested": {
                  "type": "boolean",
                  "description": "是否收到取消请求。true不证明已派发的设备命令被取消或远端停止；只有逐项status=cancelled才确认派发前取消。"
                },
                "observation": {
                  "$ref": "#/components/schemas/TaskObservation"
                }
              },
              "description": "一个固定技术目标的执行项。当前序列化不重复输出action，动作继承Task.action；item_id标识Core目标项，operation_id标识机房持久操作。"
            },
            "description": "固定目标的逐项执行视图。批量任务可能部分成功，不能只检查顶层status。每个元素均有独立operation_id；创建和备份恢复目标是云卡，env_id为null。"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Core持久受理任务的UTC RFC3339时间；不是设备开始执行时间。"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Core任务聚合状态最近写入时间；不充当远端心跳、逐台实时状态或文件传输进度时间。"
          },
          "action": {
            "type": "string",
            "enum": [
              "start",
              "stop",
              "restart",
              "repair",
              "create",
              "remove",
              "recycle",
              "restore",
              "factory_reset",
              "new_device",
              "app_install",
              "app_start",
              "app_stop",
              "app_restart",
              "app_uninstall",
              "file_push",
              "screenshot",
              "backup_export",
              "backup_restore",
              "proxy",
              "adb_shell",
              "resolution",
              "rotation",
              "device_profile",
              "accessibility_service",
              "sms",
              "app_install_url",
              "file_push_url",
              "qrcode",
              "flow_play",
              "accessibility_enable",
              "accessibility_hide",
              "dns",
              "container_config"
            ],
            "description": "本次持久请求的技术动作名称。单个任务内全部目标使用同一动作；权限、支持provider、参数和成功语义随动作而定。\n\n动作取值：start=开机；stop=关机；restart=重启；repair=修复云机（不隐式开关机或重置）；create=在云卡创建新云机；remove=永久移除云机；recycle=移入回收站；restore=从回收站恢复；factory_reset=恢复出厂（清除应用和数据，保留基础硬件 ID）；new_device=一键新机（另重新生成基础配置和硬件 ID）；app_install=从 Core 安装包安装应用；app_start=启动应用；app_stop=停止应用；app_restart=重启应用；app_uninstall=卸载应用；file_push=将 Core 文件推送到云机；screenshot=截图；backup_export=导出备份并交付到 Core；backup_restore=向云卡导入备份并创建新云机；proxy=保存代理配置；adb_shell=执行 ADB shell 命令；resolution=设置分辨率；rotation=设置屏幕方向；device_profile=旧设备档案修改；accessibility_service=设置指定无障碍服务；sms=向云机发送模拟接收短信；app_install_url=从链接下载安装应用；file_push_url=从链接下载并推送到云机；qrcode=设置相机底图；flow_play=视频摄像头换源；accessibility_enable=打开应用无障碍入口；accessibility_hide=隐藏应用无障碍入口（不等于隐藏应用）；dns=保存 DNS 配置；container_config=保存六组容器配置。"
          },
          "item_count": {
            "type": "integer",
            "minimum": 0,
            "description": "兼容可选字段；当前view不输出。目标数量可取items.length；不代表创建成功数。"
          },
          "requested_amount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "description": "仅create任务返回：每张目标云卡持久申请的创建数量，1至20。不是已创建数量、成功数量或已同步新库存数；批量多卡不能直接当作总量。"
          },
          "command": {
            "type": "string",
            "maxLength": 4096,
            "description": "仅adb_shell返回持久化的原命令文本，保留管道和换行。其他动作参数不回显；命令内容不代表已执行或成功。"
          }
        },
        "description": "持久任务视图。HTTP 202仅表示已受理，不表示设备动作成功；任务状态由目标项聚合，实际结果和错误见items[].result。读取、取消、对账与恢复均沿用原task_id及逐项operation_id。",
        "example": {
          "task_id": "tsk_example",
          "action": "repair",
          "status": "pending",
          "items": [
            {
              "item_id": "itm_example",
              "env_id": "11",
              "box_id": "2",
              "status": "pending",
              "operation_id": "op_example",
              "cancel_requested": false,
              "result": null
            }
          ]
        }
      },
      "ReservationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["expected_version", "ttl_seconds"],
        "properties": {
          "expected_version": {
            "type": "integer",
            "minimum": 0
          },
          "ttl_seconds": {
            "type": "integer",
            "minimum": 1,
            "maximum": 900
          }
        }
      },
      "AllocationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["expected_version", "reservation_id", "not_after"],
        "properties": {
          "expected_version": {
            "type": "integer",
            "minimum": 0
          },
          "reservation_id": {
            "type": "string",
            "minLength": 1
          },
          "not_after": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ReleaseRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["expected_version", "allocation_ref"],
        "properties": {
          "expected_version": {
            "type": "integer",
            "minimum": 0
          },
          "allocation_ref": {
            "type": "string",
            "minLength": 1,
            "description": "原技术分配引用；与授权及文件归属绑定，不可跨分配复用。"
          }
        }
      },
      "ReleaseConfirmation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "expected_version",
          "allocation_ref",
          "cleanup_confirmed",
          "evidence_ref"
        ],
        "properties": {
          "expected_version": {
            "type": "integer",
            "minimum": 0
          },
          "allocation_ref": {
            "type": "string",
            "minLength": 1,
            "description": "原技术分配引用；与授权及文件归属绑定，不可跨分配复用。"
          },
          "cleanup_confirmed": {
            "type": "boolean",
            "enum": [true],
            "description": "必须为 true，表示调用方明确确认已完成本次资源释放要求的清理，并通过 evidence_ref 提供证据引用；不是 Core 自动完成擦除的声明。"
          },
          "evidence_ref": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          }
        }
      },
      "ServiceCredentialRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name"],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          }
        }
      },
      "ServiceCredential": {
        "type": "object",
        "required": ["credential_id", "key", "secret"],
        "properties": {
          "credential_id": {
            "type": "string",
            "description": "凭据记录 ID，用于停用；不能代替请求头中的 key。"
          },
          "key": {
            "type": "string",
            "description": "请求头 X-Core-Key 的值。"
          },
          "secret": {
            "type": "string",
            "description": "请求头 X-Core-Secret 的值；只在创建时返回，不能通过后续查询取回。"
          }
        },
        "description": "新发放的服务凭据。key 与 secret 必须配对使用，secret 仅在创建响应中返回，应由可信服务端安全保管。"
      },
      "SessionRevocationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["business_session_ref", "actor_ref"],
        "properties": {
          "business_session_ref": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "actor_ref": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          }
        }
      },
      "ListMeta": {
        "type": "object",
        "required": ["request_id", "page", "page_size", "total"],
        "properties": {
          "request_id": {
            "type": "string",
            "description": "本次 HTTP 请求的关联 ID，供日志排查；不是任务 ID 或幂等键。"
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "description": "当前页码，从 1 开始。"
          },
          "page_size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "description": "当前页每页条数。"
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "符合当前筛选和授权范围的记录总数，不是当前页条数。"
          }
        }
      },
      "RoomCredentialInfo": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "server_id",
          "source",
          "auth_mode",
          "status",
          "version",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "server_id": {
            "type": "string",
            "pattern": "^(?!sn-)[A-Za-z0-9_-]{1,24}$",
            "minLength": 1,
            "maxLength": 24,
            "description": "已登记机房标识。"
          },
          "source": {
            "type": "string",
            "enum": ["database"],
            "description": "凭据记录来源。database=Core 的机房凭据数据库记录；不包含机房库存或设备凭据。"
          },
          "auth_mode": {
            "type": "string",
            "enum": ["shared", "database"],
            "description": "当前 Core 机房认证模式：shared=配置了全局共享机房密钥；database=未配置共享密钥，使用数据库中各机房的专属凭据。该字段说明当前认证路径，不等于此凭据记录的启停状态。"
          },
          "status": {
            "type": "string",
            "enum": ["active", "disabled", "revoked"],
            "description": "数据库机房凭据状态：active=有效可用，disabled=已停用，revoked=已吊销。disabled/revoked 均拒绝使用该记录认证；不表示机房或云卡的在线状态。当 auth_mode=shared 时，实际认证使用全局共享 Key，数据库记录的启停状态不改变共享 Key 的接入结果。"
          },
          "version": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4294967295,
            "description": "数据库机房凭据记录版本；轮换、停用与吊销时用 expected_version 防止并发覆盖。不是机房设备库存版本。"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "该记录创建时间（UTC RFC3339）。"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "该记录最后更新时间（UTC RFC3339），不是设备实时心跳或操作完成证明。"
          }
        }
      },
      "IssuedRoomCredential": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "server_id",
          "source",
          "auth_mode",
          "status",
          "version",
          "created_at",
          "updated_at",
          "room_key"
        ],
        "properties": {
          "server_id": {
            "type": "string",
            "pattern": "^(?!sn-)[A-Za-z0-9_-]{1,24}$",
            "minLength": 1,
            "maxLength": 24,
            "description": "已登记机房标识。"
          },
          "source": {
            "type": "string",
            "enum": ["database"],
            "description": "凭据记录来源。database=Core 的机房凭据数据库记录；不包含机房库存或设备凭据。"
          },
          "auth_mode": {
            "type": "string",
            "enum": ["shared", "database"],
            "description": "当前 Core 机房认证模式：shared=配置了全局共享机房密钥；database=未配置共享密钥，使用数据库中各机房的专属凭据。该字段说明当前认证路径，不等于此凭据记录的启停状态。"
          },
          "status": {
            "type": "string",
            "enum": ["active", "disabled", "revoked"],
            "description": "数据库机房凭据状态：active=有效可用，disabled=已停用，revoked=已吊销。disabled/revoked 均拒绝使用该记录认证；不表示机房或云卡的在线状态。当 auth_mode=shared 时，实际认证使用全局共享 Key，数据库记录的启停状态不改变共享 Key 的接入结果。"
          },
          "version": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4294967295,
            "description": "本次发放或轮换后的数据库凭据记录版本；后续管理动作使用此值作 expected_version。"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "该记录创建时间（UTC RFC3339）。"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "该记录最后更新时间（UTC RFC3339），不是设备实时心跳或操作完成证明。"
          },
          "room_key": {
            "type": "string",
            "minLength": 16,
            "maxLength": 128,
            "description": "本次发放或轮换的机房专属 Key，只在本次响应返回。当前认证是否使用它仍取决于 auth_mode；shared 模式仍用全局共享 Key。"
          }
        }
      },
      "RoomCredentialIssueRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "room_key": {
            "type": "string",
            "minLength": 16,
            "maxLength": 128,
            "description": "可选导入已有机房密钥；按原值保存摘要，不trim。省略时随机生成。"
          }
        }
      },
      "RoomCredentialVersionRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["expected_version"],
        "properties": {
          "expected_version": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4294967295
          }
        }
      },
      "EnvMetadataRequest": {
        "type": "object",
        "properties": {
          "expected_version": {
            "type": "integer",
            "minimum": 0
          },
          "title": {
            "type": "string",
            "maxLength": 128
          },
          "group_name": {
            "type": "string",
            "maxLength": 128
          }
        },
        "required": ["expected_version"],
        "additionalProperties": false
      },
      "ActionCapability": {
        "type": "object",
        "properties": {
          "supported": {
            "type": "boolean",
            "description": "当前 Core/机房适配器与存储 provider 是否支持此动作。true 只表示具备实现路径，不代表本次目标、状态与权限允许立即执行。"
          },
          "executable": {
            "type": "boolean",
            "description": "当前目标状态、权限和适配器条件下是否可以提交此动作。false 时查看 reason_code；true 仍须提交时做权限、版本和目标复核，不保证设备执行成功。"
          },
          "reason_code": {
            "type": "string",
            "description": "不可执行或不支持的原因：CEPH_OPERATION_NOT_SUPPORTED=当前 Ceph provider 不支持该动作；CREATE_PROVIDER_UNSUPPORTED/CONTAINER_CONFIG_PROVIDER_UNSUPPORTED/REPAIR_PROVIDER_UNSUPPORTED=对应动作要求 local provider；ROOM_ADAPTER_UNCONFIGURED=机房适配器未配置；RESOURCE_UNAVAILABLE=云机、云卡或机房不可用；ENV_RECYCLED=云机已回收；ENV_NOT_RUNNING=动作要求容器运行；ACTION_FORBIDDEN=当前身份无动作权限；ENV_NOT_RECYCLED=目标不满足回收站恢复条件。客户端应兼容后续原因码。"
          }
        },
        "required": ["supported", "executable"],
        "additionalProperties": false
      },
      "EnvCapabilities": {
        "type": "object",
        "properties": {
          "env_id": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "Core 云机资源 ID（字符串），不是机房容器编号。"
          },
          "resource_version": {
            "type": "integer",
            "minimum": 0,
            "description": "云机资源版本；提交操作时通过 expected_versions 校验，版本改变后需刷新，不是时间戳。"
          },
          "actions": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/ActionCapability"
            },
            "description": "按技术动作名称索引的能力字典。逐项判断 supported / executable，不要只依据全局 task_actions 或菜单存在就认为可执行。"
          }
        },
        "required": ["env_id", "resource_version", "actions"],
        "additionalProperties": false
      },
      "TaskStartRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["start"],
            "description": "任务动作：start=开机。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false
      },
      "TaskStopRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["stop"],
            "description": "任务动作：stop=关机。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false
      },
      "TaskRestartRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["restart"],
            "description": "任务动作：restart=重启。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false
      },
      "TaskCreateRequest": {
        "type": "object",
        "properties": {
          "box_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云卡 ID 列表；用于创建云机或导入备份。"
          },
          "action": {
            "type": "string",
            "enum": ["create"],
            "description": "任务动作：create=在云卡创建新云机。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "integer",
                "minimum": 1,
                "maximum": 20
              },
              "profile": {
                "type": "object",
                "additionalProperties": false,
                "required": ["tag", "model", "dns"],
                "properties": {
                  "tag": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "model": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "dns": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 5,
                    "items": {
                      "type": "string"
                    }
                  },
                  "timezone": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "language": {
                    "type": "string",
                    "maxLength": 100
                  }
                }
              }
            },
            "required": ["amount", "profile"],
            "additionalProperties": false
          }
        },
        "required": ["box_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskRemoveRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["remove"],
            "description": "任务动作：remove=永久移除云机。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false
      },
      "TaskRecycleRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["recycle"],
            "description": "任务动作：recycle=移入回收站。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false
      },
      "TaskRestoreRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["restore"],
            "description": "任务动作：restore=从回收站恢复。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false
      },
      "TaskFactoryResetRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["factory_reset"],
            "description": "任务动作：factory_reset=恢复出厂，清除应用和数据，保留基础硬件 ID；需要重新生成硬件 ID 时使用 new_device。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "preserve_proxy": {
                "type": "boolean"
              },
              "preserve_device_profile": {
                "type": "boolean"
              }
            },
            "required": [],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false,
        "description": "恢复出厂清除云机中的应用和数据，保留基础硬件 ID。沿用已有可选 preserve_proxy/preserve_device_profile 快照恢复行为；不等于一键新机，也不构成独立安全擦除证明。"
      },
      "TaskAppInstallRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["app_install"],
            "description": "任务动作：app_install=从 Core 安装包安装应用。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "file_id": {
                "type": "string",
                "pattern": "^file_[A-Za-z0-9_-]+$",
                "description": "Core 文件 ID，用于查询文件或申请下载；不直接表示文件已 ready。"
              },
              "existing_app_policy": {
                "type": "string",
                "enum": [
                  "skip",
                  "replace",
                  "fail",
                  "overwrite",
                  "upgrade",
                  "reinstall"
                ],
                "description": "目标已有同包名应用时：skip=保留并跳过；fail=明确失败；replace/reinstall=先卸载再安装（可能清除原应用数据）；overwrite/upgrade=覆盖安装。skip/fail/replace/reinstall 需要 package_name 才能判断原应用。"
              },
              "package_name": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$",
                "maxLength": 255
              },
              "start_if_stopped": {
                "type": "boolean"
              },
              "keep_running": {
                "type": "boolean"
              },
              "md5": {
                "type": "string",
                "pattern": "^[a-fA-F0-9]{32}$"
              }
            },
            "required": ["file_id"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskAppStartRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["app_start"],
            "description": "任务动作：app_start=启动应用。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "package_name": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$",
                "maxLength": 255
              }
            },
            "required": ["package_name"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskAppStopRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["app_stop"],
            "description": "任务动作：app_stop=停止应用。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "package_name": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$",
                "maxLength": 255
              }
            },
            "required": ["package_name"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskAppRestartRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["app_restart"],
            "description": "任务动作：app_restart=重启应用。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "package_name": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$",
                "maxLength": 255
              }
            },
            "required": ["package_name"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskAppUninstallRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["app_uninstall"],
            "description": "任务动作：app_uninstall=卸载应用。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "package_name": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$",
                "maxLength": 255
              }
            },
            "required": ["package_name"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskFilePushRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["file_push"],
            "description": "任务动作：file_push=将 Core 文件推送到云机。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "file_id": {
                "type": "string",
                "pattern": "^file_[A-Za-z0-9_-]+$",
                "description": "Core 文件 ID，用于查询文件或申请下载；不直接表示文件已 ready。"
              },
              "destination": {
                "type": "string",
                "enum": [
                  "download",
                  "downloads",
                  "pictures",
                  "movies",
                  "music",
                  "documents"
                ],
                "description": "download=Download 目录（兼容别名）；downloads=Download 目录；pictures=Pictures 图片目录；movies=Movies 视频目录；music=Music 音乐目录；documents=Documents 文档目录。"
              },
              "overwrite": {
                "type": "boolean"
              },
              "scan_media": {
                "type": "boolean"
              }
            },
            "required": ["file_id", "destination"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskScreenshotRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["screenshot"],
            "description": "任务动作：screenshot=截图。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "level": {
                "type": "string",
                "enum": ["high"],
                "description": "high=高画质截图（当前支持档位）。"
              },
              "save_to_album": {
                "type": "boolean"
              }
            },
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false
      },
      "TaskBackupExportRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["backup_export"],
            "description": "任务动作：backup_export=导出备份并交付到 Core。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false
      },
      "TaskBackupRestoreRequest": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": ["backup_restore"],
            "description": "任务动作：backup_restore=向云卡导入备份并创建新云机。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "file_id": {
                "type": "string",
                "pattern": "^file_[A-Za-z0-9_-]+$",
                "description": "Core 文件 ID，用于查询文件或申请下载；不直接表示文件已 ready。"
              }
            },
            "required": ["file_id"],
            "additionalProperties": false
          },
          "box_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云卡 ID 列表；用于创建云机或导入备份。"
          }
        },
        "required": ["box_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskProxyRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["proxy"],
            "description": "任务动作：proxy=保存代理配置。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "oneOf": [
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["direct"],
                    "description": "direct=直连，不使用代理。"
                  }
                },
                "additionalProperties": true,
                "description": "Remove proxy; all other options are ignored."
              },
              {
                "type": "object",
                "required": ["type", "host", "port"],
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["http", "https", "socks4", "socks5"],
                    "description": "http=HTTP 代理；https=HTTPS 代理；socks4=SOCKS4 代理；socks5=SOCKS5 代理。"
                  },
                  "host": {
                    "type": "string",
                    "maxLength": 253,
                    "pattern": "^[A-Za-z0-9.:-]+$",
                    "minLength": 1
                  },
                  "port": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 65535
                  },
                  "user": {
                    "type": "string",
                    "maxLength": 255,
                    "pattern": "^[^\\u0000-\\u001f\\u007f]*$"
                  },
                  "password": {
                    "type": "string",
                    "maxLength": 255,
                    "pattern": "^[^\\u0000-\\u001f\\u007f]*$"
                  },
                  "sync_device_properties": {
                    "type": "boolean"
                  },
                  "timezone_ip_auto": {
                    "type": "boolean"
                  },
                  "language_ip_auto": {
                    "type": "boolean"
                  },
                  "location_ip_auto": {
                    "type": "boolean"
                  },
                  "simipauto": {
                    "type": "boolean"
                  },
                  "timezone": {
                    "type": "string",
                    "maxLength": 128
                  },
                  "language": {
                    "type": "string",
                    "maxLength": 128
                  },
                  "latitude": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^-?(?:\\d+(?:\\.\\d*)?|\\.\\d+)$",
                    "description": "纬度，单位度，范围 -90 至 90；与经度成对使用。"
                  },
                  "longitude": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^-?(?:\\d+(?:\\.\\d*)?|\\.\\d+)$",
                    "description": "经度，单位度，范围 -180 至 180；与纬度成对使用。"
                  },
                  "accuracy": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^-?(?:\\d+(?:\\.\\d*)?|\\.\\d+)$"
                  },
                  "credentials_mode": {
                    "type": "string",
                    "enum": ["preserve", "replace", "clear"],
                    "description": "Omit for legacy behavior. preserve re-reads matching endpoint credentials in the room; replace needs both values; clear removes authentication."
                  }
                }
              }
            ]
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskAdbShellRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["adb_shell"],
            "description": "任务动作：adb_shell=执行 ADB shell 命令。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "command": {
                "type": "string",
                "minLength": 1,
                "maxLength": 4096
              }
            },
            "required": ["command"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskResolutionRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["resolution"],
            "description": "任务动作：resolution=设置分辨率。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "reset": {
                    "type": "boolean",
                    "enum": [true],
                    "description": "true=恢复设备默认分辨率，不同时提交自定义尺寸。"
                  }
                },
                "required": ["reset"],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "width": {
                    "type": "integer",
                    "minimum": 16,
                    "maximum": 8192
                  },
                  "height": {
                    "type": "integer",
                    "minimum": 16,
                    "maximum": 8192
                  },
                  "reset": {
                    "type": "boolean",
                    "enum": [false],
                    "description": "false=使用明确提交的自定义分辨率。"
                  }
                },
                "required": ["width", "height"],
                "additionalProperties": false
              }
            ]
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskRotationRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["rotation"],
            "description": "任务动作：rotation=设置屏幕方向。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "rotation": {
                "type": "string",
                "enum": [
                  "portrait",
                  "landscape",
                  "reverse_portrait",
                  "reverse_landscape"
                ],
                "description": "portrait=竖屏；landscape=横屏；reverse_portrait=反向竖屏；reverse_landscape=反向横屏。"
              }
            },
            "required": ["rotation"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskDeviceProfileRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["device_profile"],
            "description": "任务动作：device_profile=旧设备档案修改。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "mode": {
                "type": "string",
                "enum": ["random", "custom"],
                "description": "random=随机生成设备档案；custom=按明确提交的字段自定义。"
              },
              "profile": {
                "type": "object",
                "properties": {
                  "iccid": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "imei": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "imsi": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "serial_number": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "bluetooth_address": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "bluetooth_name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "wifi_mac": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "wifi_name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "oaid": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "aaid": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "vaid": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  }
                },
                "additionalProperties": false
              }
            },
            "required": ["mode"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskAccessibilityServiceRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["accessibility_service"],
            "description": "任务动作：accessibility_service=设置指定无障碍服务。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "service_key": {
                "type": "string",
                "pattern": "^[A-Za-z0-9_-]{1,512}$"
              },
              "enabled": {
                "type": "boolean"
              }
            },
            "required": ["service_key", "enabled"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskSmsRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["sms"],
            "description": "任务动作：sms=向云机发送模拟接收短信。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "from": {
                "type": "string",
                "pattern": "^\\+?[1-9]\\d{3,14}$"
              },
              "message": {
                "type": "string",
                "minLength": 1,
                "maxLength": 1000
              },
              "slot": {
                "type": "integer",
                "enum": [1, 2],
                "description": "SIM 卡槽：1=第一卡槽；2=第二卡槽。只允许设备真实存在的卡槽。"
              },
              "date": {
                "type": "string",
                "maxLength": 64
              }
            },
            "required": ["from", "message"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskRequest": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/TaskStartRequest"
          },
          {
            "$ref": "#/components/schemas/TaskStopRequest"
          },
          {
            "$ref": "#/components/schemas/TaskRestartRequest"
          },
          {
            "$ref": "#/components/schemas/TaskRepairRequest"
          },
          {
            "$ref": "#/components/schemas/TaskCreateRequest"
          },
          {
            "$ref": "#/components/schemas/TaskRemoveRequest"
          },
          {
            "$ref": "#/components/schemas/TaskRecycleRequest"
          },
          {
            "$ref": "#/components/schemas/TaskRestoreRequest"
          },
          {
            "$ref": "#/components/schemas/TaskFactoryResetRequest"
          },
          {
            "$ref": "#/components/schemas/TaskNewDeviceRequest"
          },
          {
            "$ref": "#/components/schemas/TaskAppInstallRequest"
          },
          {
            "$ref": "#/components/schemas/TaskAppStartRequest"
          },
          {
            "$ref": "#/components/schemas/TaskAppStopRequest"
          },
          {
            "$ref": "#/components/schemas/TaskAppRestartRequest"
          },
          {
            "$ref": "#/components/schemas/TaskAppUninstallRequest"
          },
          {
            "$ref": "#/components/schemas/TaskFilePushRequest"
          },
          {
            "$ref": "#/components/schemas/TaskScreenshotRequest"
          },
          {
            "$ref": "#/components/schemas/TaskBackupExportRequest"
          },
          {
            "$ref": "#/components/schemas/TaskBackupRestoreRequest"
          },
          {
            "$ref": "#/components/schemas/TaskProxyRequest"
          },
          {
            "$ref": "#/components/schemas/TaskAdbShellRequest"
          },
          {
            "$ref": "#/components/schemas/TaskResolutionRequest"
          },
          {
            "$ref": "#/components/schemas/TaskRotationRequest"
          },
          {
            "$ref": "#/components/schemas/TaskDeviceProfileRequest"
          },
          {
            "$ref": "#/components/schemas/TaskAccessibilityServiceRequest"
          },
          {
            "$ref": "#/components/schemas/TaskSmsRequest"
          },
          {
            "$ref": "#/components/schemas/TaskAppInstallUrlRequest"
          },
          {
            "$ref": "#/components/schemas/TaskFilePushUrlRequest"
          },
          {
            "$ref": "#/components/schemas/TaskQrcodeRequest"
          },
          {
            "$ref": "#/components/schemas/TaskAccessibilityEnableRequest"
          },
          {
            "$ref": "#/components/schemas/TaskAccessibilityHideRequest"
          },
          {
            "$ref": "#/components/schemas/TaskFlowPlayRequest"
          },
          {
            "$ref": "#/components/schemas/TaskDnsRequest"
          },
          {
            "$ref": "#/components/schemas/TaskContainerConfigRequest"
          }
        ]
      },
      "TaskList": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Task"
            },
            "description": "本分页模型中的任务数组；实际GET /tasks返回字段名为data。"
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "符合当前身份和权限范围的任务总数。"
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "description": "从1开始的页码。"
          },
          "page_size": {
            "type": "integer",
            "minimum": 1,
            "description": "本页请求数量上限，不是实际返回数量。"
          }
        },
        "required": ["items", "total", "page", "page_size"],
        "additionalProperties": false,
        "description": "兼容任务分页模型；当前GET /tasks实际使用{data:[Task],meta:{page,page_size,total,request_id}}，不应将此未引用模型误认为该路由的真实返回外壳。"
      },
      "FileDescriptor": {
        "type": "object",
        "properties": {
          "file_id": {
            "type": "string",
            "description": "Core文件标识；设备动作通过此ID引用，不能当作设备路径。"
          },
          "env_id": {
            "type": "string",
            "nullable": true,
            "description": "来源云机ID；云卡级上传可为null，不表示目标设备不存在。"
          },
          "box_id": {
            "type": "string",
            "description": "文件所属云卡ID；文件复用仍受当前云卡和技术引用约束。"
          },
          "allocation_ref": {
            "type": "string",
            "description": "创建或登记文件时的有效技术引用，用于隔离分配和未分配管理库存；不作商业归属判断。"
          },
          "resource_version": {
            "type": "integer",
            "minimum": 0,
            "description": "文件登记时保存的技术版本；云卡级使用对应allocation_version；当前读取仍重新检查有效引用。"
          },
          "kind": {
            "type": "string",
            "enum": ["file", "app", "backup", "screenshot"],
            "description": "文件用途分类：file普通文件、app应用安装包、backup备份、screenshot截图；不会因选择分类自动推送或安装。"
          },
          "name": {
            "type": "string",
            "description": "文件显示名称，非机房或Android绝对路径。"
          },
          "size_bytes": {
            "type": "integer",
            "minimum": 0,
            "description": "文件声明或已校验的字节大小；ready状态下可用于核对完整性，不是已传输进度。"
          },
          "sha256": {
            "type": "string",
            "description": "文件内容SHA-256十六进制摘要；ready时与已接收内容校验，不是签名或访问凭据。"
          },
          "status": {
            "type": "string",
            "description": "Core文件生命周期；只有ready允许下载或作为设备任务输入，列表通常仅返回ready，单文件读取可显示未完成上传。 枚举：uploading=文件已登记，仍等待分片或完整性校验；ready=完整内容已保存并通过大小/摘要校验，可按当前权限使用；deleted=文件已被逻辑删除，不再可下载或用于设备任务；expired=未完成上传已过有效期并清理暂存，不能作为ready文件使用。",
            "enum": ["uploading", "ready", "deleted", "expired"],
            "x-enumDescriptions": {
              "uploading": "文件已登记，仍等待分片或完整性校验",
              "ready": "完整内容已保存并通过大小/摘要校验，可按当前权限使用",
              "deleted": "文件已被逻辑删除，不再可下载或用于设备任务",
              "expired": "未完成上传已过有效期并清理暂存，不能作为ready文件使用"
            }
          },
          "chunk_size": {
            "type": "integer",
            "minimum": 0,
            "description": "上传协商的分片字节上限；机房产生的文件为0，不用于推断文件大小或接收进度。"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Core登记文件记录的UTC时间；上传文件时不等于上传完成时间，任务制品在登记ready时创建。"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "未完成上传的失效时间；ready文件通常为null。不同于下载短票的expires_at。"
          }
        },
        "required": [
          "file_id",
          "env_id",
          "box_id",
          "allocation_ref",
          "resource_version",
          "kind",
          "name",
          "size_bytes",
          "sha256",
          "status"
        ],
        "additionalProperties": false,
        "description": "Core文件库的脱敏文件元信息。status=ready才可下载或用于设备操作；不表示已推送到云机。"
      },
      "UploadRequest": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "env_id": {
                "type": "string",
                "pattern": "^[1-9][0-9]{0,19}$",
                "description": "Core 云机资源 ID（字符串），不是机房容器编号。"
              },
              "kind": {
                "type": "string",
                "enum": ["file", "app", "backup"],
                "description": "上传用途：file=普通文件，app=APK 等应用安装包，backup=备份归档。这里只创建 Core 云端文件上传，不直接推送、安装或恢复云机。"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255
              },
              "size_bytes": {
                "type": "integer",
                "minimum": 1,
                "maximum": 50000000000,
                "description": "文件大小，单位字节；不能当作分片大小。"
              },
              "sha256": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$",
                "description": "文件完整内容的 SHA-256，64 位小写十六进制，用于完整性校验。"
              },
              "chunk_size": {
                "type": "integer",
                "minimum": 65536,
                "maximum": 16777216,
                "description": "上传分片大小，单位字节；独立于单文件总大小上限。"
              }
            },
            "required": ["kind", "name", "size_bytes", "sha256", "env_id"],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": ["file", "app", "backup"],
                "description": "上传用途：file=普通文件，app=APK 等应用安装包，backup=备份归档。这里只创建 Core 云端文件上传，不直接推送、安装或恢复云机。"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255
              },
              "size_bytes": {
                "type": "integer",
                "minimum": 1,
                "maximum": 50000000000,
                "description": "文件大小，单位字节；不能当作分片大小。"
              },
              "sha256": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$",
                "description": "文件完整内容的 SHA-256，64 位小写十六进制，用于完整性校验。"
              },
              "chunk_size": {
                "type": "integer",
                "minimum": 65536,
                "maximum": 16777216,
                "description": "上传分片大小，单位字节；独立于单文件总大小上限。"
              },
              "box_id": {
                "type": "string",
                "pattern": "^[1-9][0-9]{0,19}$",
                "description": "Core 云卡资源 ID（字符串）。"
              }
            },
            "required": ["kind", "name", "size_bytes", "sha256", "box_id"],
            "additionalProperties": false
          }
        ]
      },
      "FileTransfer": {
        "type": "object",
        "properties": {
          "file_id": {
            "type": "string",
            "description": "本短票对应的原Core ready文件ID；票过期时重新取此文件的票，不重做设备任务。"
          },
          "method": {
            "type": "string",
            "enum": ["GET"],
            "description": "读取短票内容使用GET。"
          },
          "path": {
            "type": "string",
            "description": "Core签发的固定下载路径，含短期文件票；按Core地址解析，不拼接服务Key/Secret到URL。"
          },
          "headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "下载此短票所需请求头；当前为空对象，不放入一级服务凭据。"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "文件短票失效时间；当前最长5分钟且不晚于受限会话到期。与文件本身保留期限不同。"
          },
          "size_bytes": {
            "type": "integer",
            "minimum": 0,
            "description": "原ready文件的字节大小，用于下载完整性检查。"
          },
          "sha256": {
            "type": "string",
            "description": "原ready文件的SHA-256摘要，用于下载内容校验。"
          }
        },
        "required": [
          "file_id",
          "method",
          "path",
          "headers",
          "expires_at",
          "size_bytes",
          "sha256"
        ],
        "additionalProperties": false
      },
      "MediaSession": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Core 媒体会话记录 ID。"
          },
          "env_id": {
            "type": "string",
            "description": "Core 云机资源 ID（字符串），不是机房容器编号。"
          },
          "box_id": {
            "type": "string",
            "description": "Core 云卡资源 ID（字符串）。"
          },
          "kind": {
            "type": "string",
            "enum": ["maxia-h265-v1"],
            "description": "maxia-h265-v1=使用独立 Maxia 媒体服务的 H.265 短期授权会话，不是预览帧通道。"
          },
          "protocol": {
            "type": "string",
            "enum": ["h265"],
            "description": "h265=此会话使用 H.265 媒体传输协议。"
          },
          "codec": {
            "type": "string",
            "enum": ["h265"],
            "description": "h265=媒体视频编码为 H.265/HEVC。"
          },
          "wss_url": {
            "type": "string",
            "description": "播放器连接的已登记 Maxia WSS 地址。连接建立不等于已有首帧或可控制。"
          },
          "ticket": {
            "type": "string",
            "description": "短期媒体授权票据；按播放器协议发送，不能作为 Core 服务凭据。"
          },
          "resource_id": {
            "type": "string",
            "description": "媒体服务所需设备资源标识，不等同 Core env_id。"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "此会话、文件或票据的到期时间（UTC RFC3339）；到期后不得继续复用。"
          },
          "can_control": {
            "type": "boolean",
            "enum": [true],
            "description": "固定 true=当前 Maxia 协议签发的是可控制授权，要求 stream:control；不能将此会话当作受服务端只读限制的投屏会话。"
          },
          "runtime_owner": {
            "type": "string",
            "enum": ["preinstalled", "managed"],
            "description": "设备媒体运行方式：preinstalled=等待已有设备端点，进程启动由外部负责人保障；managed=Maxia 按需启动机房已安装的媒体程序。此字段本身不会启动进程。"
          }
        },
        "required": [
          "id",
          "env_id",
          "box_id",
          "kind",
          "protocol",
          "codec",
          "wss_url",
          "ticket",
          "resource_id",
          "expires_at",
          "can_control",
          "runtime_owner"
        ],
        "additionalProperties": false
      },
      "Preflight": {
        "type": "object",
        "required": ["executable", "action", "items"],
        "properties": {
          "executable": {
            "type": "boolean",
            "description": "本次全部目标预检是否通过；当前成功响应固定true，任一目标未通过时返回Problem错误。"
          },
          "action": {
            "type": "string",
            "enum": [
              "start",
              "stop",
              "restart",
              "repair",
              "create",
              "remove",
              "recycle",
              "restore",
              "factory_reset",
              "new_device",
              "app_install",
              "app_start",
              "app_stop",
              "app_restart",
              "app_uninstall",
              "file_push",
              "screenshot",
              "backup_export",
              "backup_restore",
              "proxy",
              "adb_shell",
              "resolution",
              "rotation",
              "device_profile",
              "accessibility_service",
              "sms",
              "app_install_url",
              "file_push_url",
              "qrcode",
              "flow_play",
              "accessibility_enable",
              "accessibility_hide",
              "dns",
              "container_config"
            ],
            "description": "本次预检动作，应与随后提交的动作一致；预检不能替代任务受理。\n\n动作取值：start=开机；stop=关机；restart=重启；repair=修复云机（不隐式开关机或重置）；create=在云卡创建新云机；remove=永久移除云机；recycle=移入回收站；restore=从回收站恢复；factory_reset=恢复出厂（清除应用和数据，保留基础硬件 ID）；new_device=一键新机（另重新生成基础配置和硬件 ID）；app_install=从 Core 安装包安装应用；app_start=启动应用；app_stop=停止应用；app_restart=重启应用；app_uninstall=卸载应用；file_push=将 Core 文件推送到云机；screenshot=截图；backup_export=导出备份并交付到 Core；backup_restore=向云卡导入备份并创建新云机；proxy=保存代理配置；adb_shell=执行 ADB shell 命令；resolution=设置分辨率；rotation=设置屏幕方向；device_profile=旧设备档案修改；accessibility_service=设置指定无障碍服务；sms=向云机发送模拟接收短信；app_install_url=从链接下载安装应用；file_push_url=从链接下载并推送到云机；qrcode=设置相机底图；flow_play=视频摄像头换源；accessibility_enable=打开应用无障碍入口；accessibility_hide=隐藏应用无障碍入口（不等于隐藏应用）；dns=保存 DNS 配置；container_config=保存六组容器配置。"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["executable", "resource_version", "allocation_ref"],
              "properties": {
                "env_id": {
                  "type": "string",
                  "pattern": "^[1-9][0-9]{0,19}$",
                  "description": "云机级动作的固定目标ID；云卡级动作不返回此字段。"
                },
                "box_id": {
                  "type": "string",
                  "pattern": "^[1-9][0-9]{0,19}$",
                  "description": "云卡级create/backup_restore的固定目标ID；当前云机级预检不额外返回此字段。"
                },
                "executable": {
                  "type": "boolean",
                  "description": "此固定目标当前预检通过；成功响应为true。"
                },
                "resource_version": {
                  "type": "integer",
                  "description": "本次实际检查的技术版本；云机级为resource_version，云卡级为allocation_version。提交仍须用expected_versions并重新校验。"
                },
                "allocation_ref": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "description": "当前有效技术引用；可能是allocation_ref或未分配库存的management_ref，不是业务订单ID。"
                }
              }
            },
            "description": "按本次固定目标返回技术引用与版本；不能把首台配置用作整批设备配置。"
          }
        },
        "description": "只检查当前身份、固定目标、技术版本、动作参数和能力；executable=true不创建任务、不执行设备操作，也不保证稍后提交一定成功。提交仍会重新检查。"
      },
      "TaskAppInstallUrlRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["app_install_url"],
            "description": "任务动作：app_install_url=从链接下载安装应用。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri",
                "maxLength": 4096
              },
              "existing_app_policy": {
                "type": "string",
                "enum": [
                  "skip",
                  "replace",
                  "fail",
                  "overwrite",
                  "upgrade",
                  "reinstall"
                ],
                "description": "目标已有同包名应用时：skip=保留并跳过；fail=明确失败；replace/reinstall=先卸载再安装（可能清除原应用数据）；overwrite/upgrade=覆盖安装。skip/fail/replace/reinstall 需要 package_name 才能判断原应用。"
              },
              "package_name": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$",
                "maxLength": 255
              },
              "start_if_stopped": {
                "type": "boolean"
              },
              "keep_running": {
                "type": "boolean"
              },
              "md5": {
                "type": "string",
                "pattern": "^[a-fA-F0-9]{32}$"
              }
            },
            "required": ["url"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskFilePushUrlRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["file_push_url"],
            "description": "任务动作：file_push_url=从链接下载并推送到云机。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri",
                "maxLength": 4096
              },
              "destination": {
                "type": "string",
                "enum": [
                  "download",
                  "downloads",
                  "pictures",
                  "movies",
                  "music",
                  "documents"
                ],
                "description": "download=Download 目录（兼容别名）；downloads=Download 目录；pictures=Pictures 图片目录；movies=Movies 视频目录；music=Music 音乐目录；documents=Documents 文档目录。"
              },
              "overwrite": {
                "type": "boolean"
              },
              "scan_media": {
                "type": "boolean"
              }
            },
            "required": ["url", "destination"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskQrcodeRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["qrcode"],
            "description": "任务动作：qrcode=设置相机底图。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 4096
                  }
                },
                "required": ["url"],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "file_id": {
                    "type": "string",
                    "pattern": "^file_[A-Za-z0-9_-]+$",
                    "description": "Core 文件 ID，用于查询文件或申请下载；不直接表示文件已 ready。"
                  }
                },
                "required": ["file_id"],
                "additionalProperties": false
              }
            ]
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskAccessibilityEnableRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["accessibility_enable"],
            "description": "任务动作：accessibility_enable=打开应用无障碍入口。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "package_name": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$",
                "maxLength": 255
              }
            },
            "required": ["package_name"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "TaskAccessibilityHideRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["accessibility_hide"],
            "description": "任务动作：accessibility_hide=隐藏应用无障碍入口（不等于隐藏应用）。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {
              "package_name": {
                "type": "string",
                "pattern": "^[A-Za-z][A-Za-z0-9_]*(\\.[A-Za-z][A-Za-z0-9_]*)+$",
                "maxLength": 255
              }
            },
            "required": ["package_name"],
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "DeviceProfile": {
        "type": "object",
        "properties": {
          "env_id": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "Core 云机资源 ID（字符串），不是机房容器编号。"
          },
          "mode": {
            "type": "string",
            "enum": ["random", "custom"],
            "nullable": true,
            "description": "旧设备档案模式：random=最近成功任务为随机生成；custom=最近成功任务为自定义修改；null=没有可确认的当前模式。读取只回显允许公开的字段，不代表敏感原值缺失。"
          },
          "profile": {
            "type": "object",
            "nullable": true,
            "additionalProperties": {
              "type": "string"
            },
            "description": "仅允许公开的旧档案字段快照；不会回显 IMEI、MAC、广告标识等敏感原值。"
          },
          "snapshot_available": {
            "type": "boolean",
            "description": "是否成功获得当前 MXWeb 设备档案的非敏感快照。false 时 profile 为空；不能用提交草稿伪装成读取结果。"
          },
          "profile_version": {
            "type": "integer",
            "minimum": 0,
            "nullable": true,
            "description": "最近成功写入旧设备档案任务关联的版本；不是最新库存 resource_version，也不能代替读取时间。"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "该记录最后更新时间（UTC RFC3339），不是设备实时心跳或操作完成证明。"
          },
          "observed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "实际读取或观测时间（UTC RFC3339）；无可信观测时可为 null。"
          },
          "source": {
            "type": "string",
            "enum": ["mxweb", "unavailable"],
            "description": "档案快照来源：mxweb=经登记机房读取 MXWeb 的当前档案；unavailable=未取得可靠快照。Core 不直接连接 MXWeb。"
          }
        },
        "required": [
          "env_id",
          "mode",
          "profile",
          "snapshot_available",
          "profile_version",
          "updated_at"
        ],
        "additionalProperties": false
      },
      "DeviceProfileFields": {
        "type": "object",
        "properties": {
          "fields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "description": "旧档案字段名，作为 profile 对象的键提交。"
                },
                "sensitive": {
                  "type": "boolean",
                  "description": "true=敏感设备档案字段，不回显当前原值；false=允许在授权读取中返回当前值。"
                },
                "max_length": {
                  "type": "integer",
                  "minimum": 1,
                  "description": "该字段允许的最大字符串长度。"
                }
              },
              "required": ["key", "sensitive", "max_length"],
              "additionalProperties": false
            },
            "description": "当前旧设备档案接口允许提交的白名单字段；与 container_config 的配置组合同分别管理。"
          },
          "modes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["random", "custom"],
              "description": "旧设备档案支持的编辑模式：random=随机生成，custom=自定义字段。与 container_config 容器配置编辑是不同接口。"
            },
            "description": "旧档案支持的编辑模式。"
          }
        },
        "required": ["fields", "modes"],
        "additionalProperties": false
      },
      "BackupAvailability": {
        "type": "object",
        "properties": {
          "env_id": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "用于读取备份能力的云机ID。"
          },
          "available": {
            "type": "boolean",
            "description": "当前与can_create相同，仅表示此云机现在可提交备份导出。"
          },
          "can_create": {
            "type": "boolean",
            "description": "backup_export能力当前executable；仍需提交时复核权限、引用与版本。"
          },
          "can_restore": {
            "type": "boolean",
            "description": "当前仅取backup_restore.supported，表示provider有恢复能力；不等于当前用户已有完整恢复权限或选定目标可执行。恢复要对目标云卡单独预检。"
          },
          "reason_code": {
            "type": "string",
            "description": "当前不能创建备份时的稳定机器码；开放字符串，新增原因须兼容，不能只凭文案分支。"
          },
          "reason_message": {
            "type": "string",
            "description": "当前创建受限的简短说明；不替代机器码和提交错误。"
          }
        },
        "required": ["env_id", "available", "can_create", "can_restore"],
        "additionalProperties": false,
        "description": "基于当前授权与目标能力的备份入口提示，不是备份任务结果，也不承诺恢复目标必然可执行。"
      },
      "Backup": {
        "type": "object",
        "properties": {
          "file_id": {
            "type": "string",
            "description": "Core文件标识；设备动作通过此ID引用，不能当作设备路径。"
          },
          "env_id": {
            "type": "string",
            "nullable": true,
            "description": "来源云机ID；云卡级上传可为null，不表示目标设备不存在。"
          },
          "box_id": {
            "type": "string",
            "description": "文件所属云卡ID；文件复用仍受当前云卡和技术引用约束。"
          },
          "allocation_ref": {
            "type": "string",
            "description": "创建或登记文件时的有效技术引用，用于隔离分配和未分配管理库存；不作商业归属判断。"
          },
          "resource_version": {
            "type": "integer",
            "minimum": 0,
            "description": "文件登记时保存的技术版本；云卡级使用对应allocation_version；当前读取仍重新检查有效引用。"
          },
          "kind": {
            "type": "string",
            "enum": ["backup"],
            "description": "备份历史固定为backup；普通文件/app/screenshot不进入此历史接口。"
          },
          "name": {
            "type": "string",
            "description": "文件显示名称，非机房或Android绝对路径。"
          },
          "size_bytes": {
            "type": "integer",
            "minimum": 0,
            "description": "文件声明或已校验的字节大小；ready状态下可用于核对完整性，不是已传输进度。"
          },
          "sha256": {
            "type": "string",
            "description": "文件内容SHA-256十六进制摘要；ready时与已接收内容校验，不是签名或访问凭据。"
          },
          "status": {
            "type": "string",
            "description": "备份历史状态；本接口只列Core文件已ready的备份。 枚举：completed=备份文件已交付Core且可按当前权限下载/恢复；不表示后来恢复的新云机已创建同步或启动。",
            "enum": ["completed"],
            "x-enumDescriptions": {
              "completed": "备份文件已交付Core且可按当前权限下载/恢复；不表示后来恢复的新云机已创建同步或启动"
            }
          },
          "chunk_size": {
            "type": "integer",
            "minimum": 0,
            "description": "上传协商的分片字节上限；机房产生的文件为0，不用于推断文件大小或接收进度。"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Core登记文件记录的UTC时间；上传文件时不等于上传完成时间，任务制品在登记ready时创建。"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "未完成上传的失效时间；ready文件通常为null。不同于下载短票的expires_at。"
          },
          "backup_id": {
            "type": "string",
            "description": "备份标识，当前与file_id相同；不使用MXWeb原文件名作公开备份ID。"
          },
          "source_env_id": {
            "type": "string",
            "nullable": true,
            "description": "备份来源云机ID，与env_id对应；来源不等于恢复目标。"
          },
          "source_box_id": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "备份来源云卡ID，与box_id对应；恢复目标通过单独box_id指定。"
          },
          "task_id": {
            "type": "string",
            "nullable": true,
            "description": "产生此文件的原Core任务ID；手动上传或无原operation关联时可为null。"
          },
          "completed_at": {
            "type": "string",
            "format": "date-time",
            "description": "当前实现取Core文件created_at，表示此历史文件的登记时间；不是独立采集的MXWeb导出完成时间。"
          }
        },
        "required": [
          "file_id",
          "env_id",
          "box_id",
          "allocation_ref",
          "resource_version",
          "kind",
          "name",
          "size_bytes",
          "sha256",
          "status",
          "backup_id",
          "source_env_id",
          "source_box_id",
          "task_id",
          "completed_at"
        ],
        "additionalProperties": false,
        "description": "备份历史中的已完成文件；来源是当前技术引用下kind=backup且Core文件ready的记录。status固定completed，不与通用文件status=ready混用。"
      },
      "BackupList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Backup"
            },
            "description": "当前页已交付Core且仍可见的备份数组；不含机房已完成但Core交付待确认的任务。"
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "当前授权和技术引用下全部ready备份总数。"
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "description": "从1开始的页码。"
          },
          "per_page": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "description": "每页上限，最大200；不等于当前页实际记录数。"
          }
        },
        "required": ["data", "total", "page", "per_page"],
        "additionalProperties": false
      },
      "BackupDownload": {
        "type": "object",
        "properties": {
          "backup_id": {
            "type": "string",
            "description": "原备份ID，当前等于file_id。"
          },
          "file_id": {
            "type": "string",
            "description": "原Core ready备份文件ID；票刷新继续引用此ID。"
          },
          "download_path": {
            "type": "string",
            "description": "Core签发的原文件下载短票路径；失效后重新获取短票，不重新导出备份。"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "此次下载短票到期时间，不是备份文件删除时间。"
          },
          "size_bytes": {
            "type": "integer",
            "minimum": 0,
            "description": "备份文件字节大小，用于完整性校验。"
          },
          "sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "description": "备份文件SHA-256摘要。"
          }
        },
        "required": [
          "backup_id",
          "file_id",
          "download_path",
          "expires_at",
          "size_bytes",
          "sha256"
        ],
        "additionalProperties": false
      },
      "AppCatalog": {
        "type": "object",
        "properties": {
          "configured": {
            "type": "boolean",
            "description": "是否配置了 Core 技术应用目录；false 时目录可为空，仍可使用其他已有 APK 安装入口。"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Core 应用目录项 ID；不是已安装应用的 Android 包名。"
                },
                "name": {
                  "type": "string",
                  "description": "应用目录中的展示名称。"
                },
                "version": {
                  "type": "string",
                  "description": "应用目录中安装包的展示版本，不是 Core 资源版本。"
                },
                "package_name": {
                  "type": "string",
                  "description": "Android 包名；可缺省，不能用应用展示名称替代。"
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "maxLength": 4096,
                  "description": "该目录安装包的下载链接；安装通过 Core 任务交给机房执行。"
                },
                "icon": {
                  "type": "string",
                  "format": "uri",
                  "maxLength": 4096,
                  "description": "应用图标 URL；可缺省，客户端应提供占位样式。"
                }
              },
              "required": ["id", "name", "version", "url"],
              "additionalProperties": false
            },
            "description": "可安装应用目录项；为空不影响本地 APK 或链接安装能力。"
          }
        },
        "required": ["configured", "items"],
        "additionalProperties": false
      },
      "Network": {
        "type": "object",
        "properties": {
          "env_id": {
            "type": "string",
            "description": "Core 云机资源 ID（字符串），不是机房容器编号。"
          },
          "observed_at": {
            "type": "string",
            "format": "date-time",
            "description": "本次网络信息读取响应时间（非空 UTC RFC3339）；机房未提供采集时间时由 Core 使用本次响应时间填充。source=mxweb_cache 时不表示缓存原值的采集时间。"
          },
          "ipv4": {
            "type": "string",
            "description": "云机内网 IPv4 观察值，与云卡节点 ip、设备地址 ipd 和代理公网出口不同。"
          },
          "source": {
            "type": "string",
            "enum": ["adb", "mxweb_cache"],
            "description": "私网 IPv4 的读取来源：adb=机房在设备内实际读取；mxweb_cache=机房缓存中有效的私网 IPv4。缓存来源不表示进行了新的设备内读取。"
          }
        },
        "required": ["env_id", "observed_at", "ipv4", "source"],
        "additionalProperties": false
      },
      "TaskObservation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "state",
          "phase",
          "observed_at",
          "last_checked_at",
          "remote_updated_at",
          "observation_expired"
        ],
        "properties": {
          "state": {
            "type": "string",
            "enum": ["remote_running", "unknown", "resolved", "not_observed"],
            "description": "远端观测分类。 枚举：remote_running=未知/待确认项最近有尚未过期的远端执行中观测；不是Android running状态；unknown=结果待确认或已结束未知等待，当前没有有效远端执行中证据；不证明操作失败或远端停止；resolved=目标项为succeeded、failed或cancelled；resolved表示结果已归类，不能单独视为成功；not_observed=当前生命周期不属于上述远端观测分类，常见于pending或本地running阶段（含文件接收）；不等于设备离线或从未读取过远端。",
            "x-enumDescriptions": {
              "remote_running": "未知/待确认项最近有尚未过期的远端执行中观测；不是Android running状态",
              "unknown": "结果待确认或已结束未知等待，当前没有有效远端执行中证据；不证明操作失败或远端停止",
              "resolved": "目标项为succeeded、failed或cancelled；resolved表示结果已归类，不能单独视为成功",
              "not_observed": "当前生命周期不属于上述远端观测分类，常见于pending或本地running阶段（含文件接收）；不等于设备离线或从未读取过远端"
            }
          },
          "phase": {
            "type": "string",
            "nullable": true,
            "description": "最近保存的动作阶段，允许空值；开放字符串，不能作为穷尽枚举或精确百分比。常见accepted、renewing、starting、stopping、repairing、saving_container_config、waiting_backup、receiving_artifact、completed；未知阶段应兼容显示。"
          },
          "observed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "最近可用的机房回执观测时间；缺少回执时间时可回退为对账尝试记录时间。null表示没有保存的观测/尝试时间，不能单凭此时间推断远端仍执行。"
          },
          "last_checked_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "最近真实查询或对账尝试的UTC时间（成功或未确认均可能更新），按自动对账、手动查询记录、机房回执时间依次选取；不使用Task.updated_at冒充。"
          },
          "remote_updated_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "原机房回执记录的阶段/结果更新时间；来自有效receipt.updated_at，未知或无效时为null。与本地查询时间不同。"
          },
          "observation_expired": {
            "type": "boolean",
            "description": "原先remote_running观测是否已超过有效期。true仅表示观测过期，需要查询原operation；不能推断远端已经停止。"
          }
        },
        "description": "独立于任务状态的远端观测摘要，用于判断原操作是否仍有有效运行观测。时间来自真实回执或对账尝试，不能用Task.updated_at替代。"
      },
      "DeviceConfiguration": {
        "type": "object",
        "required": ["env_id", "resolution", "proxy", "dns"],
        "additionalProperties": false,
        "properties": {
          "env_id": {
            "type": "string",
            "description": "Core 云机资源 ID（字符串），不是机房容器编号。"
          },
          "resolution": {
            "type": "object",
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "properties": {
              "available": {
                "type": "boolean",
                "description": "是否取得格式有效且带真实读取时间的分辨率当前值。false 时 source、observed_at、value 均为 null，并提供 reason_code；不填造默认值。"
              },
              "source": {
                "type": "string",
                "enum": ["adb"],
                "nullable": true,
                "description": "adb=机房通过设备内 wm size 读取当前实际分辨率；null=不可用。"
              },
              "observed_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "实际读取或观测时间（UTC RFC3339）；无可信观测时可为 null。"
              },
              "value": {
                "type": "object",
                "nullable": true,
                "required": ["width", "height"],
                "additionalProperties": false,
                "properties": {
                  "width": {
                    "type": "integer",
                    "minimum": 16,
                    "maximum": 8192,
                    "description": "读取到的实际屏幕宽度，单位像素。"
                  },
                  "height": {
                    "type": "integer",
                    "minimum": 16,
                    "maximum": 8192,
                    "description": "读取到的实际屏幕高度，单位像素。"
                  }
                },
                "description": "该组的可信观测值；available=false 时为 null。字段缺省表示未取得该字段，不是要求清空或采用默认配置。"
              },
              "reason_code": {
                "type": "string",
                "description": "RESOLUTION_READ_UNAVAILABLE=当前未取得可靠分辨率配置，可能是机房读取失败、设备状态不满足或返回格式不合法。",
                "enum": ["RESOLUTION_READ_UNAVAILABLE"]
              }
            },
            "description": "实际分辨率观测组。"
          },
          "proxy": {
            "type": "object",
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "properties": {
              "available": {
                "type": "boolean",
                "description": "是否取得格式有效且带真实读取时间的代理当前值。false 时 source、observed_at、value 均为 null，并提供 reason_code；不填造默认值。"
              },
              "source": {
                "type": "string",
                "enum": ["mxweb"],
                "nullable": true,
                "description": "mxweb=经登记机房读取 MXWeb 已保存的代理配置；null=不可用。保存配置不等于已在运行中的云机生效。"
              },
              "observed_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "实际读取或观测时间（UTC RFC3339）；无可信观测时可为 null。"
              },
              "value": {
                "type": "object",
                "nullable": true,
                "required": ["type", "has_credentials"],
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["direct", "http", "https", "socks4", "socks5"],
                    "description": "已保存的代理类型：direct=不使用代理；http/https=相应 HTTP 代理；socks4/socks5=相应 SOCKS 代理。配置存在不证明当前代理连接或出口已生效。"
                  },
                  "host": {
                    "type": "string",
                    "maxLength": 253,
                    "pattern": "^[A-Za-z0-9.:-]+$",
                    "minLength": 1,
                    "description": "已保存的代理主机；直连时可以缺省。"
                  },
                  "port": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 65535,
                    "description": "已保存的代理端口；直连时可以缺省。"
                  },
                  "has_credentials": {
                    "type": "boolean",
                    "nullable": true,
                    "description": "true=已保存代理认证信息；false=无认证信息或为直连；null=旧机房未提供可靠的认证存在标记。不会返回用户名或密码原值。"
                  }
                },
                "description": "该组的可信观测值；available=false 时为 null。字段缺省表示未取得该字段，不是要求清空或采用默认配置。"
              },
              "reason_code": {
                "type": "string",
                "description": "PROXY_READ_UNAVAILABLE=当前未取得可靠代理配置，可能是机房读取失败、设备状态不满足或返回格式不合法。",
                "enum": ["PROXY_READ_UNAVAILABLE"]
              }
            },
            "description": "已保存的脱敏代理观测组；不回显账号密码。"
          },
          "dns": {
            "type": "object",
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "properties": {
              "available": {
                "type": "boolean",
                "description": "是否取得格式有效且带真实读取时间的DNS当前值。false 时 source、observed_at、value 均为 null，并提供 reason_code；不填造默认值。"
              },
              "source": {
                "type": "string",
                "enum": ["mxweb"],
                "nullable": true,
                "description": "mxweb=经登记机房读取 MXWeb 已保存的DNS配置；null=不可用。保存配置不等于已在运行中的云机生效。"
              },
              "observed_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "实际读取或观测时间（UTC RFC3339）；无可信观测时可为 null。"
              },
              "value": {
                "type": "object",
                "nullable": true,
                "required": ["dns"],
                "additionalProperties": false,
                "properties": {
                  "dns": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 5,
                    "items": {
                      "type": "string",
                      "format": "ipv4"
                    },
                    "description": "已保存的 IPv4 DNS 地址列表，保留配置顺序。"
                  }
                },
                "description": "该组的可信观测值；available=false 时为 null。字段缺省表示未取得该字段，不是要求清空或采用默认配置。"
              },
              "reason_code": {
                "type": "string",
                "description": "DNS_READ_UNAVAILABLE=当前未取得可靠DNS配置，可能是机房读取失败、设备状态不满足或返回格式不合法。",
                "enum": ["DNS_READ_UNAVAILABLE"]
              }
            },
            "description": "已保存的 DNS 观测组；不承诺运行中的网络已经应用。"
          }
        },
        "description": "三组独立观测：resolution 为设备内实际分辨率；proxy / dns 为机房读取的保存配置。每组 available/source/observed_at/value 独立，不可用时不能填造默认值。"
      },
      "EnvCreateResult": {
        "type": "object",
        "required": [
          "target_box_id",
          "requested_amount",
          "create_accepted",
          "new_env_sync"
        ],
        "additionalProperties": false,
        "properties": {
          "target_box_id": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "原请求固定的目标云卡 ID；不是新云机 ID。"
          },
          "requested_amount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "description": "在该目标云卡原申请创建的数量；不是实际已创建或已同步数量。"
          },
          "create_accepted": {
            "type": "boolean",
            "description": "A positive MXWeb acknowledgement was confirmed; false does not prove that no write happened."
          },
          "new_env_sync": {
            "type": "string",
            "enum": ["pending"],
            "description": "pending=机房创建请求已确认，新增云机仍等待独立库存同步；不代表列表已出现新云机或云机已启动。查询原任务和库存，不因未同步而自动重复创建。"
          }
        }
      },
      "TaskFlowPlayRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["flow_play"],
            "description": "任务动作：flow_play=视频摄像头换源。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": false,
                "required": ["file_id"],
                "properties": {
                  "file_id": {
                    "type": "string",
                    "pattern": "^file_[A-Za-z0-9_-]+$",
                    "description": "Core 文件 ID，用于查询文件或申请下载；不直接表示文件已 ready。"
                  },
                  "facing": {
                    "type": "string",
                    "enum": ["front", "back"],
                    "default": "back",
                    "description": "front=前置摄像头；back=后置摄像头。"
                  }
                }
              },
              {
                "type": "object",
                "additionalProperties": false,
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "maxLength": 4096,
                    "pattern": "^https://[^\\s/@?#\\\\]+(?:[/?][^#\\s\\\\]*)?$",
                    "description": "无用户名、密码、fragment的公网HTTPS素材URL；机房校验DNS、大小和下载期限，不跟重定向。"
                  },
                  "facing": {
                    "type": "string",
                    "enum": ["front", "back"],
                    "default": "back",
                    "description": "front=前置摄像头；back=后置摄像头。"
                  }
                }
              }
            ]
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false,
        "description": "摄像头文件换源持久任务；完成只表示换源请求已受理，不证明设备相机出图。视频须为H.264/avc1的MP4/MOV，或JPEG。"
      },
      "PreviewRequest": {
        "type": "object",
        "properties": {
          "targets": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "items": {
              "type": "object",
              "properties": {
                "env_id": {
                  "type": "string",
                  "pattern": "^[1-9][0-9]{0,19}$",
                  "description": "Core 云机资源 ID（字符串），不是机房容器编号。"
                },
                "resource_version": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 4294967295,
                  "description": "云机资源版本；提交操作时通过 expected_versions 校验，版本改变后需刷新，不是时间戳。"
                }
              },
              "required": ["env_id", "resource_version"],
              "additionalProperties": false
            },
            "description": "本次申请只读预览的固定云机与各自当前资源版本；逐目标校验权限和技术绑定。"
          }
        },
        "required": ["targets"],
        "additionalProperties": false
      },
      "PreviewTarget": {
        "type": "object",
        "properties": {
          "env_id": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "Core 云机资源 ID（字符串），不是机房容器编号。"
          },
          "resource_version": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4294967295,
            "description": "云机资源版本；提交操作时通过 expected_versions 校验，版本改变后需刷新，不是时间戳。"
          },
          "binding_id": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "description": "只读预览的目标绑定标识，由 Core 签发，客户端不得自造设备地址。"
          }
        },
        "required": ["env_id", "resource_version", "binding_id"],
        "additionalProperties": false
      },
      "PreviewRoom": {
        "type": "object",
        "properties": {
          "server_id": {
            "type": "string",
            "description": "已登记机房标识。"
          },
          "ws_url": {
            "type": "string",
            "format": "uri",
            "description": "该机房已登记的只读预览 WebSocket 地址；不是 H.265 操作会话。"
          },
          "grant_id": {
            "type": "string",
            "description": "本次只读预览授权 ID。"
          },
          "ticket": {
            "type": "string",
            "description": "短期只读预览票据，受当前目标、来源和到期时间限制。"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "此会话、文件或票据的到期时间（UTC RFC3339）；到期后不得继续复用。"
          },
          "targets": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/PreviewTarget"
            },
            "description": "本次签票允许预览的固定目标与版本；不包括未通过授权的目标。"
          }
        },
        "required": [
          "server_id",
          "ws_url",
          "grant_id",
          "ticket",
          "expires_at",
          "targets"
        ],
        "additionalProperties": false
      },
      "PreviewGrants": {
        "type": "object",
        "properties": {
          "protocol": {
            "type": "string",
            "enum": ["preview.v1"],
            "description": "preview.v1=受限实时预览帧通道协议，与 H.265 媒体会话独立；仅用于预览，不提供设备控制。"
          },
          "rooms": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/PreviewRoom"
            },
            "description": "按机房分组的成功授权；使用各项 ws_url、ticket 和固定 targets 建立只读预览。空数组表示本次无成功授权。"
          },
          "rejected": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "object",
              "properties": {
                "env_id": {
                  "type": "string",
                  "pattern": "^[1-9][0-9]{0,19}$",
                  "description": "Core 云机资源 ID（字符串），不是机房容器编号。"
                },
                "code": {
                  "type": "string",
                  "enum": [
                    "forbidden",
                    "version_conflict",
                    "binding_unavailable",
                    "room_unavailable"
                  ],
                  "description": "逐目标拒绝原因：forbidden=当前身份无预览权限或目标不可访问；version_conflict=云机资源版本改变；binding_unavailable=技术引用或目标绑定不可用；room_unavailable=机房登记/通信暂不可用。"
                },
                "retryable": {
                  "type": "boolean",
                  "description": "true=允许在刷新版本、恢复绑定或机房可用后重新申请预览，不保证重试立即成功；false=当前权限或资源交接限制，不应持续重试。"
                }
              },
              "required": ["env_id", "code", "retryable"],
              "additionalProperties": false
            },
            "description": "本次未取得授权的云机及原因；不会出现在成功授权的 targets 中。"
          }
        },
        "required": ["protocol", "rooms", "rejected"],
        "additionalProperties": false,
        "description": "逐目标预览签票结果。rooms 为成功登记的机房授权，rejected 为未取得授权的目标；同批可以部分成功。收到票据不代表 WebSocket 已连接或已有预览帧。"
      },
      "TaskDnsRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["dns"],
            "description": "任务动作：dns=保存 DNS 配置。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "required": ["dns"],
            "additionalProperties": false,
            "properties": {
              "dns": {
                "type": "array",
                "minItems": 1,
                "maxItems": 5,
                "items": {
                  "type": "string",
                  "format": "ipv4"
                }
              }
            }
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "FilePage": {
        "type": "object",
        "required": ["data", "total", "page", "page_size"],
        "additionalProperties": false,
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FileDescriptor"
            },
            "description": "当前云卡和技术引用下匹配过滤的ready文件数组；上传仍不等于推送到云机。"
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "同一授权和过滤条件下的文件总数。"
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "description": "从1开始的页码。"
          },
          "page_size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "description": "每页请求数量上限，最大200。"
          }
        }
      },
      "ContainerCountry": {
        "type": "string",
        "enum": [
          "ad",
          "ae",
          "af",
          "ag",
          "ai",
          "al",
          "am",
          "ao",
          "aq",
          "ar",
          "as",
          "at",
          "au",
          "aw",
          "ax",
          "az",
          "ba",
          "bb",
          "bd",
          "be",
          "bf",
          "bg",
          "bh",
          "bi",
          "bj",
          "bl",
          "bm",
          "bn",
          "bo",
          "bq",
          "br",
          "bs",
          "bt",
          "bv",
          "bw",
          "by",
          "bz",
          "ca",
          "cc",
          "cd",
          "cf",
          "cg",
          "ch",
          "ci",
          "ck",
          "cl",
          "cm",
          "cn",
          "co",
          "cr",
          "cu",
          "cv",
          "cw",
          "cx",
          "cy",
          "cz",
          "de",
          "dj",
          "dk",
          "dm",
          "do",
          "dz",
          "ec",
          "ee",
          "eg",
          "eh",
          "er",
          "es",
          "et",
          "fi",
          "fj",
          "fk",
          "fm",
          "fo",
          "fr",
          "ga",
          "gb",
          "gd",
          "ge",
          "gf",
          "gg",
          "gh",
          "gi",
          "gl",
          "gm",
          "gn",
          "gp",
          "gq",
          "gr",
          "gs",
          "gt",
          "gu",
          "gw",
          "gy",
          "hk",
          "hm",
          "hn",
          "hr",
          "ht",
          "hu",
          "id",
          "ie",
          "il",
          "im",
          "in",
          "io",
          "iq",
          "ir",
          "is",
          "it",
          "je",
          "jm",
          "jo",
          "jp",
          "ke",
          "kg",
          "kh",
          "ki",
          "km",
          "kn",
          "kp",
          "kr",
          "kw",
          "ky",
          "kz",
          "la",
          "lb",
          "lc",
          "li",
          "lk",
          "lr",
          "ls",
          "lt",
          "lu",
          "lv",
          "ly",
          "ma",
          "mc",
          "md",
          "me",
          "mf",
          "mg",
          "mh",
          "mk",
          "ml",
          "mm",
          "mn",
          "mo",
          "mp",
          "mq",
          "mr",
          "ms",
          "mt",
          "mu",
          "mv",
          "mw",
          "mx",
          "my",
          "mz",
          "na",
          "nc",
          "ne",
          "nf",
          "ng",
          "ni",
          "nl",
          "no",
          "np",
          "nr",
          "nu",
          "nz",
          "om",
          "pa",
          "pe",
          "pf",
          "pg",
          "ph",
          "pk",
          "pl",
          "pm",
          "pn",
          "pr",
          "ps",
          "pt",
          "pw",
          "py",
          "qa",
          "re",
          "ro",
          "rs",
          "ru",
          "rw",
          "sa",
          "sb",
          "sc",
          "sd",
          "se",
          "sg",
          "sh",
          "si",
          "sj",
          "sk",
          "sl",
          "sm",
          "sn",
          "so",
          "sr",
          "ss",
          "st",
          "sv",
          "sx",
          "sy",
          "sz",
          "tc",
          "td",
          "tf",
          "tg",
          "th",
          "tj",
          "tk",
          "tl",
          "tm",
          "tn",
          "to",
          "tr",
          "tt",
          "tv",
          "tw",
          "tz",
          "ua",
          "ug",
          "um",
          "us",
          "uy",
          "uz",
          "va",
          "vc",
          "ve",
          "vg",
          "vi",
          "vn",
          "vu",
          "wf",
          "ws",
          "ye",
          "yt",
          "za",
          "zm",
          "zw"
        ],
        "description": "ISO 3166-1 alpha-2 国家或地区代码，使用小写，例如 cn=中国、us=美国、jp=日本；仅接受本枚举中的标准代码。"
      },
      "ContainerSystem": {
        "type": "object",
        "properties": {
          "timezone": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$",
            "format": "iana-timezone",
            "description": "Specific Intl-supported IANA timezone; auto and numeric offsets are rejected."
          },
          "locale": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$",
            "format": "language-tag",
            "description": "Valid locale; underscores normalize to hyphens."
          }
        },
        "required": [],
        "additionalProperties": false,
        "minProperties": 1
      },
      "ContainerLocation": {
        "type": "object",
        "properties": {
          "latitude": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "description": "纬度，单位度，范围 -90 至 90；与经度成对使用。"
          },
          "longitude": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "description": "经度，单位度，范围 -180 至 180；与纬度成对使用。"
          },
          "altitude": {
            "type": "number",
            "description": "海拔，单位米；未提交时保留原值。"
          },
          "bearing": {
            "type": "number",
            "minimum": 0,
            "maximum": 360,
            "exclusiveMaximum": true,
            "description": "方向角，单位度，范围 [0, 360)；未提交时保留原值。"
          },
          "speed": {
            "type": "number",
            "minimum": 0,
            "description": "速度，单位米/秒，非负；未提交时保留原值。"
          }
        },
        "required": ["latitude", "longitude"],
        "additionalProperties": false
      },
      "ContainerConfigOptions": {
        "type": "object",
        "properties": {
          "system": {
            "$ref": "#/components/schemas/ContainerSystem"
          },
          "dns": {
            "type": "array",
            "minItems": 1,
            "maxItems": 5,
            "items": {
              "type": "string",
              "format": "ipv4"
            }
          },
          "wifi": {
            "type": "object",
            "properties": {
              "ssid": {
                "type": "string",
                "minLength": 1,
                "maxLength": 64,
                "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$"
              },
              "mac": {
                "type": "string",
                "pattern": "^[0-9a-fA-F]{2}([:-])[0-9a-fA-F]{2}(?:\\1[0-9a-fA-F]{2}){4}$",
                "description": "Six octets; normalize to uppercase colon notation."
              },
              "ap": {
                "type": "string",
                "pattern": "^[0-9a-fA-F]{2}([:-])[0-9a-fA-F]{2}(?:\\1[0-9a-fA-F]{2}){4}$",
                "description": "Six octets; normalize to uppercase colon notation."
              }
            },
            "required": [],
            "additionalProperties": false,
            "minProperties": 1
          },
          "location": {
            "$ref": "#/components/schemas/ContainerLocation"
          },
          "sim": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": ["manual"],
                    "description": "manual=只更新显式提交的已有卡槽字段。号码必须与国家成对提交；IMEI 可单独修改；未提交字段保持原值。"
                  },
                  "slots": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 2,
                    "items": {
                      "oneOf": [
                        {
                          "type": "object",
                          "properties": {
                            "slot": {
                              "type": "integer",
                              "enum": [1, 2],
                              "description": "已有 SIM 卡槽编号：1=第一卡槽，2=第二卡槽；不可通过此接口新增不存在的卡槽。"
                            },
                            "phone": {
                              "type": "string",
                              "pattern": "^\\+[1-9]\\d{1,14}$"
                            },
                            "country": {
                              "$ref": "#/components/schemas/ContainerCountry"
                            },
                            "imei": {
                              "type": "string",
                              "pattern": "^\\d{15}$",
                              "format": "imei",
                              "description": "15 digits with a valid Luhn checksum."
                            }
                          },
                          "required": ["slot", "phone", "country"],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "slot": {
                              "type": "integer",
                              "enum": [1, 2],
                              "description": "已有 SIM 卡槽编号：1=第一卡槽，2=第二卡槽；不可通过此接口新增不存在的卡槽。"
                            },
                            "imei": {
                              "type": "string",
                              "pattern": "^\\d{15}$",
                              "format": "imei",
                              "description": "15 digits with a valid Luhn checksum."
                            }
                          },
                          "required": ["slot", "imei"],
                          "additionalProperties": false
                        }
                      ]
                    },
                    "description": "Distinct slot IDs. Only slots present in the saved profile may be changed."
                  }
                },
                "required": ["mode", "slots"],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "mode": {
                    "type": "string",
                    "enum": ["timezone"],
                    "description": "timezone=根据本次显式选择的系统时区重建全部已有 SIM 卡槽的号码与运营商信息，保留有效 IMEI；必须同时提供 system.timezone，不能与手动 slots 参数混用。"
                  }
                },
                "required": ["mode"],
                "additionalProperties": false,
                "description": "Requires an explicit system.timezone in the same request; regenerates all existing SIM slots."
              }
            ]
          },
          "identifiers": {
            "type": "object",
            "properties": {
              "oaid": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$"
              },
              "vaid": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$"
              },
              "uaid": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$"
              },
              "aaid": {
                "type": "string",
                "format": "uuid",
                "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$"
              }
            },
            "required": [],
            "additionalProperties": false,
            "minProperties": 1
          }
        },
        "required": [],
        "additionalProperties": false,
        "minProperties": 1,
        "description": "Only explicitly changed groups. Unknown fields are rejected. No automatic restart; sensitive values are never echoed. Timezone SIM mode requires system.timezone in this request."
      },
      "TaskContainerConfigRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["container_config"],
            "description": "任务动作：container_config=保存六组容器配置。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "$ref": "#/components/schemas/ContainerConfigOptions"
          }
        },
        "required": ["env_ids", "action", "expected_versions", "options"],
        "additionalProperties": false
      },
      "ContainerConfigResult": {
        "type": "object",
        "properties": {
          "accepted": {
            "type": "boolean",
            "enum": [true],
            "description": "固定 true=MXWeb 已以严格数值成功回执确认本次配置请求；不代表运行中的配置已立即生效。"
          },
          "saved": {
            "type": "boolean",
            "enum": [true],
            "description": "固定 true=本次配置保存已确认。保存后的读取失败不能把提交草稿当作已读回的当前配置。"
          },
          "requires_restart": {
            "type": "boolean",
            "enum": [true],
            "description": "固定 true=本次修改需下次启动或重启生效；保存动作本身不自动重启云机。"
          },
          "saved_groups": {
            "type": "array",
            "minItems": 1,
            "maxItems": 6,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "system",
                "dns",
                "wifi",
                "location",
                "sim",
                "identifiers"
              ],
              "description": "本次已确认保存的分组：system=时区/语言，dns=DNS，wifi=WiFi 信息，location=位置，sim=SIM 卡，identifiers=设备标识。仅列本次提交并确认保存的分组。"
            },
            "description": "本次实际确认保存的配置分组，不代表未提交的分组也被修改。"
          }
        },
        "required": ["accepted", "saved", "requires_restart", "saved_groups"],
        "additionalProperties": false,
        "description": "容器保存配置的成功回执。只确认保存，不确认运行中的实际设置已改变；saved_groups 必须与原请求分组一致。"
      },
      "ContainerConfiguration": {
        "type": "object",
        "properties": {
          "env_id": {
            "type": "string",
            "description": "Core 云机资源 ID（字符串），不是机房容器编号。"
          },
          "system": {
            "type": "object",
            "properties": {
              "available": {
                "type": "boolean",
                "description": "true=该配置组存在并已读到合法的脱敏保存值；false=该组不存在、读取失败或返回值无法确认。不可用组的 source、observed_at、value 均为 null，不影响其他组的可靠值。"
              },
              "source": {
                "type": "string",
                "enum": ["mxweb"],
                "nullable": true,
                "description": "mxweb=经登记机房读取 MXWeb 的已保存容器配置；null=此组不可用。此值不表示保存配置已在运行中的云机生效，也不表示 Core 直连 MXWeb。"
              },
              "observed_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "实际读取或观测时间（UTC RFC3339）；无可信观测时可为 null。"
              },
              "value": {
                "type": "object",
                "properties": {
                  "timezone": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$",
                    "format": "iana-timezone",
                    "description": "Specific Intl-supported IANA timezone; auto and numeric offsets are rejected."
                  },
                  "locale": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$",
                    "format": "language-tag",
                    "description": "Valid locale; underscores normalize to hyphens."
                  }
                },
                "required": [],
                "additionalProperties": false,
                "nullable": true,
                "description": "该组的可信观测值；available=false 时为 null。字段缺省表示未取得该字段，不是要求清空或采用默认配置。"
              },
              "reason_code": {
                "type": "string",
                "enum": [
                  "CONTAINER_CONFIG_GROUP_ABSENT",
                  "CONTAINER_CONFIG_READ_UNAVAILABLE"
                ],
                "description": "CONTAINER_CONFIG_GROUP_ABSENT=原容器配置组或所需卡槽真实不存在；CONTAINER_CONFIG_READ_UNAVAILABLE=读取失败或格式不合法，无法确认当前值。读取失败不能按空配置或默认配置提交覆盖。"
              }
            },
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "description": "系统时区与语言保存配置观测组。"
          },
          "dns": {
            "type": "object",
            "properties": {
              "available": {
                "type": "boolean",
                "description": "true=该配置组存在并已读到合法的脱敏保存值；false=该组不存在、读取失败或返回值无法确认。不可用组的 source、observed_at、value 均为 null，不影响其他组的可靠值。"
              },
              "source": {
                "type": "string",
                "enum": ["mxweb"],
                "nullable": true,
                "description": "mxweb=经登记机房读取 MXWeb 的已保存容器配置；null=此组不可用。此值不表示保存配置已在运行中的云机生效，也不表示 Core 直连 MXWeb。"
              },
              "observed_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "实际读取或观测时间（UTC RFC3339）；无可信观测时可为 null。"
              },
              "value": {
                "type": "object",
                "properties": {
                  "dns": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 5,
                    "items": {
                      "type": "string",
                      "format": "ipv4"
                    },
                    "description": "已保存的 DNS IPv4 列表，保留原顺序及重复项。"
                  }
                },
                "required": ["dns"],
                "additionalProperties": false,
                "nullable": true,
                "description": "该组的可信观测值；available=false 时为 null。字段缺省表示未取得该字段，不是要求清空或采用默认配置。"
              },
              "reason_code": {
                "type": "string",
                "enum": [
                  "CONTAINER_CONFIG_GROUP_ABSENT",
                  "CONTAINER_CONFIG_READ_UNAVAILABLE"
                ],
                "description": "CONTAINER_CONFIG_GROUP_ABSENT=原容器配置组或所需卡槽真实不存在；CONTAINER_CONFIG_READ_UNAVAILABLE=读取失败或格式不合法，无法确认当前值。读取失败不能按空配置或默认配置提交覆盖。"
              }
            },
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "description": "DNS 保存配置观测组。"
          },
          "wifi": {
            "type": "object",
            "properties": {
              "available": {
                "type": "boolean",
                "description": "true=该配置组存在并已读到合法的脱敏保存值；false=该组不存在、读取失败或返回值无法确认。不可用组的 source、observed_at、value 均为 null，不影响其他组的可靠值。"
              },
              "source": {
                "type": "string",
                "enum": ["mxweb"],
                "nullable": true,
                "description": "mxweb=经登记机房读取 MXWeb 的已保存容器配置；null=此组不可用。此值不表示保存配置已在运行中的云机生效，也不表示 Core 直连 MXWeb。"
              },
              "observed_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "实际读取或观测时间（UTC RFC3339）；无可信观测时可为 null。"
              },
              "value": {
                "type": "object",
                "properties": {
                  "ssid": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 64,
                    "pattern": "^(?=.*\\S)[^\\u0000-\\u001f\\u007f]+$",
                    "description": "允许公开的 WiFi 名称；未回显 MAC、BSSID、密码原值。"
                  },
                  "has_mac": {
                    "type": "boolean",
                    "description": "true=对应敏感配置已存在；false=未配置或未检测到该值。仅返回存在标记，不回显 MAC/BSSID/密码原值。"
                  },
                  "has_ap": {
                    "type": "boolean",
                    "description": "true=对应敏感配置已存在；false=未配置或未检测到该值。仅返回存在标记，不回显 MAC/BSSID/密码原值。"
                  },
                  "has_password": {
                    "type": "boolean",
                    "description": "true=对应敏感配置已存在；false=未配置或未检测到该值。仅返回存在标记，不回显 MAC/BSSID/密码原值。"
                  }
                },
                "required": ["has_mac", "has_ap", "has_password"],
                "additionalProperties": false,
                "nullable": true,
                "description": "该组的可信观测值；available=false 时为 null。字段缺省表示未取得该字段，不是要求清空或采用默认配置。"
              },
              "reason_code": {
                "type": "string",
                "enum": [
                  "CONTAINER_CONFIG_GROUP_ABSENT",
                  "CONTAINER_CONFIG_READ_UNAVAILABLE"
                ],
                "description": "CONTAINER_CONFIG_GROUP_ABSENT=原容器配置组或所需卡槽真实不存在；CONTAINER_CONFIG_READ_UNAVAILABLE=读取失败或格式不合法，无法确认当前值。读取失败不能按空配置或默认配置提交覆盖。"
              }
            },
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "description": "WiFi 保存配置观测组；敏感值仅返回存在标记。"
          },
          "location": {
            "type": "object",
            "properties": {
              "available": {
                "type": "boolean",
                "description": "true=已取得合法的读取结果；位置可为空对象，SIM 可为空 slots 数组，不保证存在可修改的原组或卡槽。false=当前无法可靠读取。只有真实存在的原配置项/卡槽才能修改，不能依据 available=true 自造默认配置。"
              },
              "source": {
                "type": "string",
                "enum": ["mxweb"],
                "nullable": true,
                "description": "mxweb=经登记机房读取 MXWeb 的已保存容器配置；null=此组不可用。此值不表示保存配置已在运行中的云机生效，也不表示 Core 直连 MXWeb。"
              },
              "observed_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "实际读取或观测时间（UTC RFC3339）；无可信观测时可为 null。"
              },
              "value": {
                "type": "object",
                "properties": {
                  "latitude": {
                    "type": "number",
                    "minimum": -90,
                    "maximum": 90,
                    "description": "纬度，单位度，范围 -90 至 90；与经度成对使用。"
                  },
                  "longitude": {
                    "type": "number",
                    "minimum": -180,
                    "maximum": 180,
                    "description": "经度，单位度，范围 -180 至 180；与纬度成对使用。"
                  },
                  "altitude": {
                    "type": "number",
                    "description": "海拔，单位米；未提交时保留原值。"
                  },
                  "bearing": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 360,
                    "exclusiveMaximum": true,
                    "description": "方向角，单位度，范围 [0, 360)；未提交时保留原值。"
                  },
                  "speed": {
                    "type": "number",
                    "minimum": 0,
                    "description": "速度，单位米/秒，非负；未提交时保留原值。"
                  }
                },
                "required": [],
                "additionalProperties": false,
                "nullable": true,
                "description": "该组的可信观测值；available=false 时为 null。字段缺省表示未取得该字段，不是要求清空或采用默认配置。"
              },
              "reason_code": {
                "type": "string",
                "enum": [
                  "CONTAINER_CONFIG_GROUP_ABSENT",
                  "CONTAINER_CONFIG_READ_UNAVAILABLE"
                ],
                "description": "CONTAINER_CONFIG_GROUP_ABSENT=原容器配置组或所需卡槽真实不存在；CONTAINER_CONFIG_READ_UNAVAILABLE=读取失败或格式不合法，无法确认当前值。读取失败不能按空配置或默认配置提交覆盖。"
              }
            },
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "description": "位置保存配置观测组；合法空对象不等于有可修改的 GPS 原配置。"
          },
          "sim": {
            "type": "object",
            "properties": {
              "available": {
                "type": "boolean",
                "description": "true=已取得合法的读取结果；位置可为空对象，SIM 可为空 slots 数组，不保证存在可修改的原组或卡槽。false=当前无法可靠读取。只有真实存在的原配置项/卡槽才能修改，不能依据 available=true 自造默认配置。"
              },
              "source": {
                "type": "string",
                "enum": ["mxweb"],
                "nullable": true,
                "description": "mxweb=经登记机房读取 MXWeb 的已保存容器配置；null=此组不可用。此值不表示保存配置已在运行中的云机生效，也不表示 Core 直连 MXWeb。"
              },
              "observed_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "实际读取或观测时间（UTC RFC3339）；无可信观测时可为 null。"
              },
              "value": {
                "type": "object",
                "properties": {
                  "slots": {
                    "type": "array",
                    "maxItems": 2,
                    "items": {
                      "type": "object",
                      "properties": {
                        "slot": {
                          "type": "integer",
                          "enum": [1, 2],
                          "description": "现有 SIM 卡槽编号：1=第一卡槽，2=第二卡槽；只返回真实存在的卡槽，不生成虚拟默认卡槽。"
                        },
                        "country": {
                          "$ref": "#/components/schemas/ContainerCountry"
                        },
                        "has_phone": {
                          "type": "boolean",
                          "description": "true=此卡槽中对应敏感配置已存在；false=未配置或未检测到该值。不会回显号码或 IMEI 原值。"
                        },
                        "has_imei": {
                          "type": "boolean",
                          "description": "true=此卡槽中对应敏感配置已存在；false=未配置或未检测到该值。不会回显号码或 IMEI 原值。"
                        }
                      },
                      "required": ["slot", "has_phone", "has_imei"],
                      "additionalProperties": false
                    },
                    "description": "设备真实存在的 SIM 卡槽数组；空数组表示当前没有可供此接口修改的卡槽。"
                  }
                },
                "required": ["slots"],
                "additionalProperties": false,
                "nullable": true,
                "description": "该组的可信观测值；available=false 时为 null。字段缺省表示未取得该字段，不是要求清空或采用默认配置。"
              },
              "reason_code": {
                "type": "string",
                "enum": [
                  "CONTAINER_CONFIG_GROUP_ABSENT",
                  "CONTAINER_CONFIG_READ_UNAVAILABLE"
                ],
                "description": "CONTAINER_CONFIG_GROUP_ABSENT=原容器配置组或所需卡槽真实不存在；CONTAINER_CONFIG_READ_UNAVAILABLE=读取失败或格式不合法，无法确认当前值。读取失败不能按空配置或默认配置提交覆盖。"
              }
            },
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "description": "SIM 保存配置观测组；只返回真实存在的卡槽，不生成默认卡槽。"
          },
          "identifiers": {
            "type": "object",
            "properties": {
              "available": {
                "type": "boolean",
                "description": "true=该配置组存在并已读到合法的脱敏保存值；false=该组不存在、读取失败或返回值无法确认。不可用组的 source、observed_at、value 均为 null，不影响其他组的可靠值。"
              },
              "source": {
                "type": "string",
                "enum": ["mxweb"],
                "nullable": true,
                "description": "mxweb=经登记机房读取 MXWeb 的已保存容器配置；null=此组不可用。此值不表示保存配置已在运行中的云机生效，也不表示 Core 直连 MXWeb。"
              },
              "observed_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "实际读取或观测时间（UTC RFC3339）；无可信观测时可为 null。"
              },
              "value": {
                "type": "object",
                "properties": {
                  "has_oaid": {
                    "type": "boolean",
                    "description": "true=对应设备标识已存在；false=未配置或未检测到该值。仅返回存在标记，不回显标识原值。"
                  },
                  "has_vaid": {
                    "type": "boolean",
                    "description": "true=对应设备标识已存在；false=未配置或未检测到该值。仅返回存在标记，不回显标识原值。"
                  },
                  "has_uaid": {
                    "type": "boolean",
                    "description": "true=对应设备标识已存在；false=未配置或未检测到该值。仅返回存在标记，不回显标识原值。"
                  },
                  "has_aaid": {
                    "type": "boolean",
                    "description": "true=对应设备标识已存在；false=未配置或未检测到该值。仅返回存在标记，不回显标识原值。"
                  }
                },
                "required": ["has_oaid", "has_vaid", "has_uaid", "has_aaid"],
                "additionalProperties": false,
                "nullable": true,
                "description": "该组的可信观测值；available=false 时为 null。字段缺省表示未取得该字段，不是要求清空或采用默认配置。"
              },
              "reason_code": {
                "type": "string",
                "enum": [
                  "CONTAINER_CONFIG_GROUP_ABSENT",
                  "CONTAINER_CONFIG_READ_UNAVAILABLE"
                ],
                "description": "CONTAINER_CONFIG_GROUP_ABSENT=原容器配置组或所需卡槽真实不存在；CONTAINER_CONFIG_READ_UNAVAILABLE=读取失败或格式不合法，无法确认当前值。读取失败不能按空配置或默认配置提交覆盖。"
              }
            },
            "required": ["available", "source", "observed_at", "value"],
            "additionalProperties": false,
            "description": "设备标识保存配置观测组；只返回存在标记。"
          }
        },
        "required": [
          "env_id",
          "system",
          "dns",
          "wifi",
          "location",
          "sim",
          "identifiers"
        ],
        "additionalProperties": false,
        "description": "六组独立的容器已保存配置快照，经过白名单与脱敏。不是所有 Android 运行时实际效果的读取；配置保存后需下次启动或重启才生效。"
      },
      "ProxyConnection": {
        "oneOf": [
          {
            "type": "object",
            "required": ["type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["direct"],
                "description": "代理连接类型：direct=不使用代理；http/https=相应 HTTP 代理；socks4/socks5=相应 SOCKS 代理。不得据此推断云机运行时代理已生效。"
              }
            },
            "additionalProperties": true,
            "description": "Remove proxy; all other options are ignored."
          },
          {
            "type": "object",
            "required": ["type", "host", "port"],
            "additionalProperties": false,
            "properties": {
              "type": {
                "type": "string",
                "enum": ["http", "https", "socks4", "socks5"],
                "description": "代理连接类型：direct=不使用代理；http/https=相应 HTTP 代理；socks4/socks5=相应 SOCKS 代理。不得据此推断云机运行时代理已生效。"
              },
              "host": {
                "type": "string",
                "maxLength": 253,
                "pattern": "^[A-Za-z0-9.:-]+$",
                "minLength": 1
              },
              "port": {
                "type": "integer",
                "minimum": 1,
                "maximum": 65535
              },
              "user": {
                "type": "string",
                "maxLength": 255,
                "pattern": "^[^\\u0000-\\u001f\\u007f]*$"
              },
              "password": {
                "type": "string",
                "maxLength": 255,
                "pattern": "^[^\\u0000-\\u001f\\u007f]*$"
              },
              "credentials_mode": {
                "type": "string",
                "enum": ["preserve", "replace", "clear"],
                "description": "认证信息处理方式：preserve=机房按匹配的代理端点重新读取并保留原认证；replace=用同时提供的用户名和密码替换；clear=移除认证。省略时保留旧调用行为；不会将原认证明文返回浏览器。"
              }
            }
          }
        ]
      },
      "ProxyCheckRequest": {
        "type": "object",
        "required": ["expected_version", "proxy"],
        "additionalProperties": false,
        "properties": {
          "expected_version": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4294967295
          },
          "proxy": {
            "$ref": "#/components/schemas/ProxyConnection"
          }
        }
      },
      "ProxyCheckResult": {
        "type": "object",
        "required": [
          "env_id",
          "resource_version",
          "success",
          "scope",
          "checked_at"
        ],
        "additionalProperties": false,
        "properties": {
          "env_id": {
            "type": "string",
            "pattern": "^[1-9][0-9]{0,19}$",
            "description": "Core 云机资源 ID（字符串），不是机房容器编号。"
          },
          "resource_version": {
            "type": "integer",
            "minimum": 0,
            "description": "云机资源版本；提交操作时通过 expected_versions 校验，版本改变后需刷新，不是时间戳。"
          },
          "success": {
            "type": "boolean",
            "description": "true=本次机房侧探测请求成功；不表示代理配置已保存或云机运行时流量已使用该出口。配置草稿探测与保存为独立操作。"
          },
          "scope": {
            "type": "string",
            "enum": ["room_direct", "room_proxy"],
            "description": "探测位置：room_direct=从机房直接探测公网出口；room_proxy=从机房经本次指定代理探测公网出口。两者都不是云机内应用的网络实测。"
          },
          "checked_at": {
            "type": "string",
            "format": "date-time",
            "description": "本次机房出口探测的真实 UTC 时间，不是配置保存时间。"
          },
          "ip": {
            "type": "string",
            "maxLength": 45,
            "description": "本次机房出口探测得到的公网 IP；不是云卡节点或云机内网 IP。"
          },
          "country": {
            "type": "string",
            "maxLength": 128,
            "description": "探测服务返回并经白名单处理的国家或地区信息，可缺省；不是由 Core 为设备自动设置的国家。"
          },
          "city": {
            "type": "string",
            "maxLength": 128,
            "description": "探测服务返回的城市信息，可缺省。"
          },
          "timezone": {
            "type": "string",
            "maxLength": 128,
            "description": "探测到的时区信息，可缺省；不表示云机系统时区已修改。"
          },
          "language": {
            "type": "string",
            "maxLength": 128,
            "description": "探测到的语言信息，可缺省；不表示云机系统语言已修改。"
          },
          "latitude": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "description": "纬度，单位度，范围 -90 至 90；与经度成对使用。"
          },
          "longitude": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "description": "经度，单位度，范围 -180 至 180；与纬度成对使用。"
          }
        }
      },
      "TaskRepairRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["repair"],
            "description": "任务动作：repair=修复云机（不隐式开关机或重置）。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false,
        "description": "Repair the fixed cloud-phone target through the registered local room. Requires env:manage; stopped containers are allowed. Does not implicitly start, stop or factory-reset the target. Successful repair_accepted confirms only the room repair response, not device health. Unknown outcomes must query the original operation without replaying the write."
      },
      "TaskArtifactDeliveryError": {
        "type": "object",
        "description": "原机房文件交付到Core受阻的事实明细。错误只描述此阶段，不能抹掉机房已生成文件的事实；恢复优先读取原artifact，不重发backup_export或screenshot。",
        "additionalProperties": true,
        "properties": {
          "code": {
            "type": "string",
            "description": "稳定机器错误码，开放字符串。常见UPLOAD_TOO_LARGE、ARTIFACT_TRANSFER_FAILED、ARTIFACT_TRANSFER_ABORTED、ALLOCATION_STALE；按已知码处理并兼容新码。"
          },
          "detail": {
            "type": "string",
            "description": "本次交付受阻的可读说明，不替代code作程序判断。"
          },
          "stage": {
            "type": "string",
            "description": "错误发生阶段，开放字符串；当前中心文件接收使用receiving_artifact，不是Android执行状态。"
          },
          "occurred_at": {
            "type": "string",
            "description": "记录本次交付错误的UTC时间，不是机房文件生成时间。",
            "format": "date-time"
          },
          "actual_bytes": {
            "type": "integer",
            "description": "超限时已知的实际大小或已收到的累计字节数；可能大于较小的声明大小。",
            "minimum": 0
          },
          "limit_bytes": {
            "type": "integer",
            "description": "本次执行时Core生效的单文件字节上限；与机房上限分别配置，不能将二者混为同一限制。",
            "minimum": 1
          }
        }
      },
      "TaskArtifactDelivery": {
        "type": "object",
        "description": "机房产物到Core文件库的交付状态，与room_result_status及设备动作分开。只有ready且已有Core file_id才能提供用户下载或恢复。字节进度只描述传输，不代表整个设备操作百分比。",
        "additionalProperties": true,
        "properties": {
          "status": {
            "type": "string",
            "description": "中心交付生命周期。 枚举：pending=机房文件已生成，等待中心接收原artifact；receiving=Core正在接收并校验原文件；逐项任务可显示running；blocked=交付受阻或被交接/取消/失权，保留机房完成事实和错误；不等于设备导出失败；ready=完整内容已登记为Core ready文件，可按当前权限下载或恢复。",
            "enum": ["pending", "receiving", "blocked", "ready"],
            "x-enumDescriptions": {
              "pending": "机房文件已生成，等待中心接收原artifact",
              "receiving": "Core正在接收并校验原文件；逐项任务可显示running",
              "blocked": "交付受阻或被交接/取消/失权，保留机房完成事实和错误；不等于设备导出失败",
              "ready": "完整内容已登记为Core ready文件，可按当前权限下载或恢复"
            }
          },
          "received_bytes": {
            "type": "integer",
            "description": "本次接收尝试累计读取的真实字节数；新的原文件接收尝试可从0重新计数，不能当作断点续传偏移。ready时应等于文件总大小。",
            "minimum": 0
          },
          "total_bytes": {
            "type": "integer",
            "description": "原机房artifact声明并待校验的总字节数；不是整个操作预计工作量。",
            "minimum": 0
          },
          "last_progress_at": {
            "type": "string",
            "description": "最后一次收到非零新字节的记录时间；尚无真实传输进展时为null，不能用任务updated_at伪造进度。",
            "format": "date-time",
            "nullable": true
          },
          "error": {
            "$ref": "#/components/schemas/TaskArtifactDeliveryError"
          }
        }
      },
      "TaskRoomArtifact": {
        "type": "object",
        "description": "尚在机房保存、等待交付Core的原制品描述。出现此对象不代表浏览器可下载或文件已ready；客户端应等待Core file_id，不直接请求机房私有路径。",
        "additionalProperties": true,
        "properties": {
          "name": {
            "type": "string",
            "description": "机房原制品的安全文件名；非设备或服务器绝对路径。"
          },
          "content_type": {
            "type": "string",
            "description": "机房原制品的MIME类型，例如image/png或application/octet-stream。"
          },
          "size_bytes": {
            "type": "integer",
            "description": "机房已生成原文件的字节数；中心接收后仍校验大小。",
            "minimum": 1
          },
          "sha256": {
            "type": "string",
            "description": "机房原文件SHA-256十六进制摘要；中心接收后再次验证。",
            "pattern": "^[a-f0-9]{64}$"
          },
          "download_path": {
            "type": "string",
            "description": "固定原operation的机房/internal制品路径，供Core服务端使用；不是浏览器公开下载地址，也不能由用户改成任意URL。"
          }
        }
      },
      "TaskRoomObservation": {
        "type": "object",
        "description": "最近一次只读机房查询尝试的记录。即使查询失败或结果未知，也可能有observed_at；应结合TaskObservation.state判断有效远端运行证据。",
        "additionalProperties": true,
        "properties": {
          "code": {
            "type": "string",
            "description": "本次观测或未确认原因的开放机器码；null表示本次没有错误码。",
            "nullable": true
          },
          "detail": {
            "type": "string",
            "description": "本次观测或未确认原因的可读说明。",
            "nullable": true
          },
          "observed_at": {
            "type": "string",
            "description": "真实执行机房查询/对账尝试后记录的UTC时间，不表示远端结果已终结。",
            "format": "date-time"
          }
        }
      },
      "TaskAutoReconciliation": {
        "type": "object",
        "description": "Core对原operation的后台只读对账信息；不代表重做设备写操作，也不承诺next_check_at时一定得到终态。",
        "additionalProperties": true,
        "properties": {
          "attempts": {
            "type": "integer",
            "description": "已进行的原operation自动查询次数；不是设备动作执行次数。",
            "minimum": 0
          },
          "last_checked_at": {
            "type": "string",
            "description": "最后一次自动对账实际检查时间。",
            "format": "date-time"
          },
          "next_check_at": {
            "type": "string",
            "description": "按退避策略安排的下次只读检查时间；不是完成时间或进度预测。",
            "format": "date-time"
          },
          "last_code": {
            "type": "string",
            "description": "最后一次查询得到的开放机器码或DEVICE_RESULT_UNKNOWN；新增码需兼容。"
          },
          "claim_token": {
            "type": "string",
            "description": "当前自动只读对账的内部租约标识，可能短暂出现在查询结果；不是访问凭据、进度或稳定业务标识，调用方不应回传或依赖。"
          }
        }
      },
      "TaskUnknownRecovery": {
        "type": "object",
        "description": "用户明确确认结束未知等待的审计事实；原结果仍保留，后续迟到回执只记录，不覆盖released_unknown或新的任务。",
        "additionalProperties": true,
        "properties": {
          "reason": {
            "type": "string",
            "description": "用户提供或默认采用的结束等待原因。"
          },
          "actor_ref": {
            "type": "string",
            "description": "发起确认的宿主用户引用，不是访问凭据。"
          },
          "credential_id": {
            "type": "string",
            "description": "发起确认的Core凭据记录ID，不是Key或Secret。"
          },
          "released_at": {
            "type": "string",
            "description": "用户确认结束等待的UTC时间；不是远端命令结束时间。",
            "format": "date-time"
          }
        }
      },
      "TaskItemResult": {
        "type": "object",
        "description": "逐目标持久结果及最近观测的开放对象；pending时可为null，字段按动作和阶段选择性出现。没有某字段不等于false。结果可能保留已完成子步骤而总项仍待确认；items[].status是当前生命周期，result.status可能是上一回执。未知/超时/丢ACK只查询原task/operation，不能自动再次执行设备写；动作成功仅以对应ACK/文件/观察合同为界，不伪装为真实设备或生产验收。",
        "additionalProperties": true,
        "properties": {
          "status": {
            "type": "string",
            "description": "原动作回执或本地结果快照的状态，可能落后于items[].status（例如文件接收中、released_unknown保留原未知回执）；当前生命周期以items[].status为准。 枚举：succeeded=该次结果确认满足动作合同；文件动作仍须结合Core交付ready；failed=该次结果有明确失败事实；needs_reconciliation=该次结果未确认或文件交付尚未完成，只查原operation；cancelled=在派发前取消的本地结果。",
            "enum": [
              "succeeded",
              "failed",
              "needs_reconciliation",
              "cancelled"
            ],
            "x-enumDescriptions": {
              "succeeded": "该次结果确认满足动作合同；文件动作仍须结合Core交付ready",
              "failed": "该次结果有明确失败事实",
              "needs_reconciliation": "该次结果未确认或文件交付尚未完成，只查原operation",
              "cancelled": "在派发前取消的本地结果"
            }
          },
          "code": {
            "type": "string",
            "description": "稳定机器码，开放字符串。未知结果、兼容性拒绝、业务失败和文件交付受阻均可能出现；不应看到code就一律显示设备操作失败。"
          },
          "detail": {
            "type": "string",
            "description": "本次结果的可读说明；程序判断使用状态和code，不能依赖文案。"
          },
          "phase": {
            "type": "string",
            "description": "最近动作或交付阶段，开放字符串。常见accepted、repairing、renewing、starting、stopping、waiting_stopped、waiting_running、waiting_backup、artifact_ready、receiving_artifact、completed；阶段不构成精确整体百分比。",
            "nullable": true
          },
          "room_operation_id": {
            "type": "string",
            "description": "此结果对应的原机房operation ID，应与目标项operation_id一致。后续只读恢复继续使用原ID。"
          },
          "room_observed_at": {
            "type": "string",
            "description": "最近收到并校验原机房回执时的Core观测时间；不是远端回执更新时间或设备心跳。",
            "format": "date-time"
          },
          "room_updated_at": {
            "type": "string",
            "description": "原机房回执的阶段/结果更新时间；未提供有效时间时可为null。",
            "format": "date-time",
            "nullable": true
          },
          "remote_running": {
            "type": "boolean",
            "description": "是否有近期机房回执表明原operation仍执行；表示操作执行而非云机Android running。false也可能只是观测过期或当前无证据，不能推断远端已停止。"
          },
          "remote_running_until": {
            "type": "string",
            "description": "该次远端执行中观测的有效截止时间；不是操作预计完成时间，缺少值或过期要结合TaskObservation判断。",
            "format": "date-time",
            "nullable": true
          },
          "remote_running_observation_expired": {
            "type": "boolean",
            "description": "原执行中观测已过期；view可将remote_running归为false并保留此标记，但不修改远端事实。"
          },
          "room_observation": {
            "$ref": "#/components/schemas/TaskRoomObservation"
          },
          "auto_reconciliation": {
            "$ref": "#/components/schemas/TaskAutoReconciliation"
          },
          "recovery": {
            "$ref": "#/components/schemas/TaskUnknownRecovery"
          },
          "late_result": {
            "type": "object",
            "description": "结束未知等待后到达的原operation迟到回执；仅为审计保留，不覆盖released_unknown或后续新任务结果。",
            "additionalProperties": true,
            "properties": {}
          },
          "late_result_at": {
            "type": "string",
            "description": "记录原operation迟到回执的UTC时间，不代表重新执行。",
            "format": "date-time"
          },
          "room_result_status": {
            "type": "string",
            "description": "机房产物阶段的已确认结果，与Core交付分开；当前仅在确认机房成功生成制品时设置。 枚举：succeeded=原截图或备份在机房已生成，中心仍可能pending/receiving/blocked，不能据此提供下载。",
            "enum": ["succeeded"],
            "x-enumDescriptions": {
              "succeeded": "原截图或备份在机房已生成，中心仍可能pending/receiving/blocked，不能据此提供下载"
            }
          },
          "room_completed_at": {
            "type": "string",
            "description": "原机房文件生成/动作完成时间，取机房completed_at或receipt.updated_at，缺失时可为null；不是中心交付完成时间。",
            "format": "date-time",
            "nullable": true
          },
          "artifact": {
            "$ref": "#/components/schemas/TaskRoomArtifact"
          },
          "artifact_delivery": {
            "$ref": "#/components/schemas/TaskArtifactDelivery"
          },
          "file_id": {
            "type": "string",
            "description": "Core文件ID；截图/备份产物成功接收后出现。必须确认对应Core文件ready才能提供下载或恢复；输入文件动作也可回报原输入file_id。"
          },
          "name": {
            "type": "string",
            "description": "Core已接收的产物显示文件名；不当作设备绝对路径。"
          },
          "size_bytes": {
            "type": "integer",
            "description": "已接收产物或被校验输入文件的字节大小。不是整体任务进度。",
            "minimum": 0
          },
          "sha256": {
            "type": "string",
            "description": "已确认输入文件或Core产物的SHA-256摘要，用于完整性校验。",
            "pattern": "^[a-f0-9]{64}$"
          },
          "actual_bytes": {
            "type": "integer",
            "description": "容量失败时观察到的实际或累计字节数；不是成功生成的文件大小承诺。",
            "minimum": 0
          },
          "limit_bytes": {
            "type": "integer",
            "description": "发生容量限制时实际生效的字节上限。",
            "minimum": 1
          },
          "failed_stage": {
            "type": "string",
            "description": "容量失败发生的阶段，开放字符串；例如saving_artifact。"
          },
          "mxweb_backup_name": {
            "type": "string",
            "description": "原MXWeb备份文件名，用于定位已生成文件；不能当作Core ready备份ID或直接重发导出的理由。"
          },
          "artifact_name": {
            "type": "string",
            "description": "原产物的安全名称，仅辅助定位。"
          },
          "target_box_id": {
            "type": "string",
            "description": "create或backup_restore的固定目标云卡ID，非新云机ID。"
          },
          "requested_amount": {
            "type": "integer",
            "description": "仅create结果：原申请在该张云卡创建的数量，不是实际创建或同步数。",
            "minimum": 1,
            "maximum": 20
          },
          "create_accepted": {
            "type": "boolean",
            "description": "create接口是否有匹配原目标和申请数量的严格正向ACK；true仅确认创建请求被机房接口接受，不承诺已同步全部新云机。"
          },
          "import_accepted": {
            "type": "boolean",
            "description": "备份导入接口已确认接受；同卡创建新云机，新库存通过独立同步出现，不覆盖原云机，不代表新机已启动或同步。"
          },
          "new_env_sync": {
            "type": "string",
            "description": "新云机库存同步与机房创建/导入ACK独立。当前结果仅记录pending，查询任务不会据此伪造新库存已完成。 枚举：pending=原创建或导入已受理，等待独立库存同步；应刷新云机列表确认实际新云机。",
            "enum": ["pending"],
            "x-enumDescriptions": {
              "pending": "原创建或导入已受理，等待独立库存同步；应刷新云机列表确认实际新云机"
            }
          },
          "repair_accepted": {
            "type": "boolean",
            "description": "只有严格MXWeb布尔true才为true，表示修复接口确认处理；不证明云机已恢复运行或可以连接。"
          },
          "accepted": {
            "type": "boolean",
            "description": "对应动作接口已确认接受或配置已保存；具体意义取决于Task.action，不能通用解释为设备实际效果已生效。"
          },
          "target_status": {
            "type": "string",
            "description": "该动作请求或保留的目标容器状态，需结合动作确认方式和库存独立观察；不是WiFi状态。 枚举：running=请求/观测到容器运行；start仅接口受理，仍需独立确认；stopped=请求/保留容器停止；备份导出和重置可主动保持停机。",
            "enum": ["running", "stopped"],
            "x-enumDescriptions": {
              "running": "请求/观测到容器运行；start仅接口受理，仍需独立确认",
              "stopped": "请求/保留容器停止；备份导出和重置可主动保持停机"
            }
          },
          "restarted": {
            "type": "boolean",
            "description": "机房重启处理器已完成原目标停止再启动的有界状态观察；Core库存/WiFi就绪仍独立同步。"
          },
          "removed": {
            "type": "boolean",
            "description": "机房确认原固定云机已移除；不表示云卡或其他云机被删除。"
          },
          "saved": {
            "type": "boolean",
            "description": "container_config的配置已确认写入；不证明正在运行的Android已加载新配置。"
          },
          "requires_restart": {
            "type": "boolean",
            "description": "container_config成功固定true：需下次启动或用户另行重启后生效，不自动执行重启。"
          },
          "saved_groups": {
            "type": "array",
            "description": "本次container_config实际保存且与原申请完全匹配的配置分块名；不公开敏感原值。",
            "items": {
              "type": "string",
              "description": "六类配置分块。 枚举：system=时区和语言；dns=DNS地址；wifi=WiFi名称/MAC/BSSID；location=位置；sim=SIM卡；identifiers=设备标识。",
              "enum": [
                "system",
                "dns",
                "wifi",
                "location",
                "sim",
                "identifiers"
              ],
              "x-enumDescriptions": {
                "system": "时区和语言",
                "dns": "DNS地址",
                "wifi": "WiFi名称/MAC/BSSID",
                "location": "位置",
                "sim": "SIM卡",
                "identifiers": "设备标识"
              }
            },
            "uniqueItems": true
          },
          "dns": {
            "type": "array",
            "description": "已保存的1至5个IPv4 DNS，保留原顺序和重复项；保存成功不代表重启后网络效果已验。",
            "items": {
              "type": "string",
              "description": "IPv4地址。",
              "format": "ipv4"
            },
            "minItems": 1,
            "maxItems": 5
          },
          "proxy_saved": {
            "type": "boolean",
            "description": "代理配置已保存的独立事实；后续SIM同步失败/未知也必须保留true，不能当作保存未发生。"
          },
          "proxy_type": {
            "type": "string",
            "description": "本次保存且匹配原申请的代理类型。 枚举：direct=直连，不使用代理；http=HTTP代理；https=HTTPS代理；socks4=SOCKS4代理；socks5=SOCKS5代理。",
            "enum": ["direct", "http", "https", "socks4", "socks5"],
            "x-enumDescriptions": {
              "direct": "直连，不使用代理",
              "http": "HTTP代理",
              "https": "HTTPS代理",
              "socks4": "SOCKS4代理",
              "socks5": "SOCKS5代理"
            }
          },
          "sim_updated": {
            "type": "boolean",
            "description": "代理联动SIM：true确认更新，false明确未完成，null表示保存代理后SIM更新结果未知；字段缺失表示未报告此联动结果。",
            "nullable": true
          },
          "network": {
            "type": "object",
            "description": "机房代理出口的脱敏探测观察，不是设备内网络实际生效证明；只在有有效探测结果时返回，不含代理账号密码。",
            "additionalProperties": true,
            "properties": {
              "state": {
                "type": "string",
                "description": "此可选探测快照的结果分类，当前仅成功观察可进入公开结果。 枚举：succeeded=机房代理/直连出口探测成功，不代表云机内代理已启用。",
                "enum": ["succeeded"],
                "x-enumDescriptions": {
                  "succeeded": "机房代理/直连出口探测成功，不代表云机内代理已启用"
                }
              },
              "scope": {
                "type": "string",
                "description": "探测发生的范围。 枚举：room_proxy=机房通过此代理探测出口；room_direct=机房直连出口探测。",
                "enum": ["room_proxy", "room_direct"],
                "x-enumDescriptions": {
                  "room_proxy": "机房通过此代理探测出口",
                  "room_direct": "机房直连出口探测"
                }
              },
              "checked_at": {
                "type": "string",
                "description": "真实出口探测UTC时间。",
                "format": "date-time"
              },
              "ip": {
                "type": "string",
                "description": "机房探测到的出口IP，非云机ipd。"
              },
              "country": {
                "type": "string",
                "description": "探测服务报告的国家信息，可缺失。"
              },
              "city": {
                "type": "string",
                "description": "探测服务报告的城市信息，可缺失。"
              },
              "timezone": {
                "type": "string",
                "description": "探测到且校验有效的具体时区，不表示设备已应用。"
              },
              "language": {
                "type": "string",
                "description": "探测到且校验有效的语言，不表示设备已应用。"
              },
              "latitude": {
                "type": "number",
                "description": "探测报告的纬度，不表示设备位置已应用。"
              },
              "longitude": {
                "type": "number",
                "description": "探测报告的经度，不表示设备位置已应用。"
              }
            }
          },
          "output": {
            "type": "string",
            "description": "adb_shell返回的原命令输出；可为空，成功不保证有文本。应展示给用户，并结合exit_code判断；不从操作成功通知推断输出内容。"
          },
          "exit_code": {
            "type": "integer",
            "description": "adb_shell的进程退出码，0通常表示命令进程成功；非0为命令退出失败，不等同于网络异常或未知执行结果。"
          },
          "installed": {
            "type": "boolean",
            "description": "应用安装处理器确认本次安装完成；不表示应用已启动或可用性已验证。"
          },
          "skipped": {
            "type": "boolean",
            "description": "按existing_app_policy=skip保留已安装应用而跳过安装；不是新安装成功，常伴随APP_ALREADY_INSTALLED。"
          },
          "reason_code": {
            "type": "string",
            "description": "动作分支的开放机器码，例如应用已存在而跳过；不必然表示任务失败。"
          },
          "package_name": {
            "type": "string",
            "description": "应用动作所处理的Android包名；某些来源无法确认包名时可缺失。"
          },
          "media_scan": {
            "type": "string",
            "description": "文件推送后媒体扫描的结果，与文件复制结果分别报告。 枚举：succeeded=媒体扫描成功；failed=文件已复制但媒体扫描失败；not_requested=本次未请求媒体扫描。",
            "enum": ["succeeded", "failed", "not_requested"],
            "x-enumDescriptions": {
              "succeeded": "媒体扫描成功",
              "failed": "文件已复制但媒体扫描失败",
              "not_requested": "本次未请求媒体扫描"
            }
          },
          "album": {
            "type": "object",
            "description": "截图可选保存到设备相册的独立结果；Core截图ready不等于相册保存成功。",
            "additionalProperties": true,
            "properties": {
              "requested": {
                "type": "boolean",
                "description": "本次是否要求保存到设备相册。"
              },
              "saved": {
                "type": "boolean",
                "description": "是否确认已复制到设备并完成相册扫描；未请求时通常false。"
              },
              "path": {
                "type": "string",
                "description": "设备相册内的目标路径；仅保存成功时提供，不是浏览器下载地址。"
              },
              "media_scan": {
                "type": "string",
                "description": "相册媒体扫描结果。 枚举：succeeded=相册扫描确认成功；failed=相册保存或扫描未确认，查看error_code。",
                "enum": ["succeeded", "failed"],
                "x-enumDescriptions": {
                  "succeeded": "相册扫描确认成功",
                  "failed": "相册保存或扫描未确认，查看error_code"
                }
              },
              "error_code": {
                "type": "string",
                "description": "相册保存的开放错误码，例如ALBUM_SAVE_FAILED；不抹掉Core截图文件已经生成的事实。"
              }
            }
          },
          "source": {
            "type": "string",
            "description": "截图原内容来源；Core仍通过登记机房执行，不直接访问MXWeb/ADB。 枚举：mxweb=机房从MXWeb获得PNG；adb=机房本地通过ADB获得PNG。",
            "enum": ["mxweb", "adb"],
            "x-enumDescriptions": {
              "mxweb": "机房从MXWeb获得PNG",
              "adb": "机房本地通过ADB获得PNG"
            }
          },
          "path": {
            "type": "string",
            "description": "特定文件/图片动作回报的设备内目标路径，不是Core文件下载路径，不允许浏览器据此发起任意文件访问。"
          },
          "reset_accepted": {
            "type": "boolean",
            "description": "factory_reset 恢复出厂接口已确认接受：清除应用和数据，保留基础硬件 ID。不同于 new_device 一键新机；仍须结合 erasure_verified，不能当作安全擦除证明。"
          },
          "erasure_verified": {
            "type": "boolean",
            "description": "是否有独立安全擦除验证；当前factory_reset固定false，不能仅凭重置接口成功便满足资源交接擦除门槛。"
          },
          "flow_play_accepted": {
            "type": "boolean",
            "description": "文件摄像头素材切换请求的严格受理确认；不等于相机已经出图。"
          },
          "camera_output_confirmed": {
            "type": "boolean",
            "description": "当前文件摄像头成功合同固定false；没有建立真实相机帧验收，不能显示已确认出图。"
          },
          "state": {
            "type": "string",
            "description": "动作相关的开放状态字符串。restart 成功可返回容器观测 running；flow_play 可返回换源初始状态（例如 preparing/starting），Core 排除明确失败/停止状态后才接受。它不是 Task.status，不能当成统一设备可用状态或最终相机出图证明。"
          },
          "generation": {
            "type": "integer",
            "description": "文件摄像头此次换源的正整数代次，用于区分原素材会话；不表示帧数或进度。",
            "minimum": 1
          },
          "facing": {
            "type": "string",
            "description": "文件摄像头请求并确认对应的摄像头方向。 枚举：front=前置；back=后置。",
            "enum": ["front", "back"],
            "x-enumDescriptions": {
              "front": "前置",
              "back": "后置"
            }
          },
          "mode": {
            "type": "string",
            "description": "device_profile的操作模式，保留旧兼容。 枚举：random=随机生成设备档案；custom=应用用户明确提供的白名单档案字段。",
            "enum": ["random", "custom"],
            "x-enumDescriptions": {
              "random": "随机生成设备档案",
              "custom": "应用用户明确提供的白名单档案字段"
            }
          },
          "applied_fields": {
            "type": "array",
            "description": "旧device_profile实际报告处理的字段名；字段值仍按敏感边界过滤，不能因为字段名存在就回显原IMEI/MAC等。",
            "items": {
              "type": "string",
              "description": "档案白名单字段名；兼容扩展字符串。"
            }
          },
          "snapshot_available": {
            "type": "boolean",
            "description": "旧device_profile是否取得可用档案快照；不承诺所有字段在前端可读取，敏感值仍隐藏。"
          },
          "profile": {
            "type": "object",
            "description": "旧device_profile公开的脱敏快照，Core仅保留bluetooth_name和wifi_name，不回显IMEI/MAC/广告标识等敏感值。",
            "additionalProperties": true,
            "properties": {
              "bluetooth_name": {
                "type": "string",
                "description": "允许公开的蓝牙显示名称。"
              },
              "wifi_name": {
                "type": "string",
                "description": "允许公开的WiFi显示名称。"
              }
            },
            "nullable": true
          },
          "reset": {
            "type": "boolean",
            "description": "resolution动作是否请求恢复默认分辨率；true时不要求width/height。"
          },
          "width": {
            "type": "integer",
            "description": "resolution动作提交的宽度像素；此字段回执不替代设备实际分辨率重新读取。",
            "minimum": 16,
            "maximum": 8192
          },
          "height": {
            "type": "integer",
            "description": "resolution动作提交的高度像素；此字段回执不替代设备实际分辨率重新读取。",
            "minimum": 16,
            "maximum": 8192
          },
          "rotation": {
            "type": "string",
            "description": "rotation动作确认接受的屏幕方向。 枚举：portrait=竖屏；landscape=横屏；reverse_portrait=反向竖屏；reverse_landscape=反向横屏。",
            "enum": [
              "portrait",
              "landscape",
              "reverse_portrait",
              "reverse_landscape"
            ],
            "x-enumDescriptions": {
              "portrait": "竖屏",
              "landscape": "横屏",
              "reverse_portrait": "反向竖屏",
              "reverse_landscape": "反向横屏"
            }
          },
          "proxy": {
            "type": "object",
            "additionalProperties": true,
            "description": "factory_reset中原代理配置的可选恢复结果，不回显凭据或敏感标识。",
            "properties": {
              "reapplied": {
                "type": "boolean",
                "description": "是否实际重新应用了请求保留的原配置；false可能表示未请求保留，不自动等同失败。"
              }
            }
          },
          "device_profile": {
            "type": "object",
            "additionalProperties": true,
            "description": "factory_reset中原设备档案配置的可选恢复结果，不回显凭据或敏感标识。",
            "properties": {
              "reapplied": {
                "type": "boolean",
                "description": "是否实际重新应用了请求保留的原配置；false可能表示未请求保留，不自动等同失败。"
              }
            }
          },
          "file": {
            "type": "object",
            "additionalProperties": true,
            "description": "backup_restore的原输入备份文件元信息，不是新创建云机；机房会另确认file_id/size_bytes/sha256与原输入匹配。",
            "properties": {
              "file_name": {
                "type": "string",
                "description": "原输入备份的显示文件名。"
              },
              "size_bytes": {
                "type": "integer",
                "minimum": 0,
                "description": "原输入备份字节大小。"
              },
              "sha256": {
                "type": "string",
                "description": "原输入备份SHA-256摘要。"
              }
            }
          },
          "files": {
            "description": "backup_restore透传的机房导入文件回执，不是已创建云机列表；具体形状由原机房导入合同决定，不凭此推断新库存已同步。"
          },
          "new_device_accepted": {
            "type": "boolean",
            "description": "new_device 一键新机接口返回明确成功回执时为严格 true；不证明设备可连接或实际硬件 ID 变化已被独立验证。"
          },
          "hardware_ids_verified": {
            "type": "boolean",
            "description": "是否独立验证一键新机后的实际基础硬件 ID 变化；当前 new_device 固定 false，不能将接口成功回执当成设备效果验证。"
          }
        },
        "nullable": true
      },
      "TaskNewDeviceRequest": {
        "type": "object",
        "properties": {
          "env_ids": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[1-9][0-9]{0,19}$"
            },
            "description": "本次固定操作的 Core 云机 ID 列表；不会在执行中按当前列表或选择重新取目标。"
          },
          "action": {
            "type": "string",
            "enum": ["new_device"],
            "description": "任务动作：new_device=一键新机，清除应用和数据，并重新生成基础配置及硬件 ID；与保留硬件 ID 的恢复出厂不同。"
          },
          "expected_versions": {
            "type": "object",
            "minProperties": 1,
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "description": "固定目标 ID 到当前版本的映射。云机动作使用 resource_version，云卡动作使用 allocation_version；不匹配时拒绝提交。"
          },
          "options": {
            "type": "object",
            "properties": {},
            "additionalProperties": false,
            "description": "严格空对象；不接受恢复代理或设备档案参数，不回写旧硬件标识。"
          }
        },
        "required": ["env_ids", "action", "expected_versions"],
        "additionalProperties": false,
        "description": "一键新机：通过登记 local 机房对固定云机调用 GET /api/1_0/renew/:id。权限 env:manage，停机可提交；清除应用和数据，并重新生成基础配置及硬件 ID。不会额外开关机，也不回写旧配置。成功 new_device_accepted:true 只确认接口成功回执，hardware_ids_verified:false 表示未独立验证实际硬件 ID；超时、断线和异常回执只查询原 operation，不自动再次执行。旧机房不支持时明确 NEW_DEVICE_UNSUPPORTED，不回退恢复出厂。"
      },
      "FcBackgroundHealth": {
        "type": "object",
        "required": [
          "mode",
          "release_id",
          "role",
          "lease_valid",
          "global_ready",
          "allowed_release",
          "holder_release",
          "lease_remaining_ms",
          "reason"
        ],
        "properties": {
          "mode": {
            "type": "string",
            "enum": ["fc_combined"]
          },
          "release_id": {
            "type": "string",
            "description": "处理本次 HTTP 请求的实例制品标识。"
          },
          "role": {
            "type": "string",
            "enum": ["standby", "starting", "leader", "draining", "stopped"],
            "description": "本实例角色；standby 不代表其他实例没有正常运行的 Worker。"
          },
          "lease_valid": {
            "type": "boolean",
            "description": "本实例当前是否持有调度租约。"
          },
          "global_ready": {
            "type": "boolean",
            "description": "共享后台已完成启动，且允许版本、持有版本、代际和有效租约均匹配。"
          },
          "allowed_release": {
            "type": "string",
            "nullable": true,
            "description": "被允许运行后台的制品；null 表示尚未启用或迁移期间已暂停。"
          },
          "holder_release": {
            "type": "string",
            "nullable": true,
            "description": "当前租约持有者的制品；不暴露实例标识、租约令牌或内部连接信息。"
          },
          "lease_remaining_ms": {
            "type": "integer",
            "minimum": 0
          },
          "reason": {
            "type": "string",
            "enum": [
              "ready",
              "disabled",
              "no_leader",
              "starting",
              "lease_mismatch",
              "unavailable"
            ],
            "description": "ready=共享后台就绪；disabled=未启用；no_leader=无有效持有者；starting=启动未完成；lease_mismatch=许可与租约不匹配；unavailable=无法确认共享状态。"
          }
        },
        "description": "FC 合并宿主的后台健康状态。调度租约不证明已发送的设备命令已经结束；独立 API/Worker 宿主不提供共享后台健康状态。"
      }
    },
    "securitySchemes": {
      "serviceKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Core-Key",
        "description": "默认服务鉴权的 Key。必须与 X-Core-Secret 同时提供，用于可信服务端或管理员独立工作台；不能与 Bearer 混用。"
      },
      "serviceSecret": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Core-Secret",
        "description": "默认服务鉴权的 Secret。必须与 X-Core-Key 同时提供；不要写入公开源码、URL 或普通业务用户的前端配置。"
      },
      "restrictedSession": {
        "type": "http",
        "scheme": "bearer",
        "description": "可选的受限 opaque access token，由可信服务端使用 Key/Secret 创建，限制云卡、权限及期限。普通业务接口可使用；管理接口不接受。不能同时发送服务 Key/Secret。"
      }
    }
  },
  "tags": [
    {
      "name": "状态与能力"
    },
    {
      "name": "云卡与云机"
    },
    {
      "name": "设备读取与配置"
    },
    {
      "name": "持久化任务"
    },
    {
      "name": "文件传输"
    },
    {
      "name": "备份"
    },
    {
      "name": "投屏与预览"
    },
    {
      "name": "受限会话"
    },
    {
      "name": "服务与机房凭据"
    },
    {
      "name": "云卡分配与交接"
    }
  ]
}