{
  "schema_version": 2,
  "title": "云手机 API 能力目录",
  "introduction": "通过 API 将 Android 云手机的创建、日常操作、应用分发、文件传输和备份接入自己的业务系统。",
  "availability_note": "具体可用操作受设备与交付环境影响；设备操作提交后需查询任务及每台设备的结果，受理成功不代表设备已执行完成。",
  "integration": {
    "introduction": "可由自己的业务系统接入 Core API，也可使用 Web Base 标准工作台管理云手机。",
    "steps": [
      "先按本目录的功能模块确认业务需要，重点核对镜像、文件和备份的适用范围。",
      "确定合作后，由技术人员对接服务地址、访问授权、目标设备范围和异步任务结果。",
      "使用自己的业务页面或标准工作台完成联调，再按实际设备与交付环境验收。"
    ]
  },
  "modules": [
    {
      "id": "cloud-phones",
      "title": "云机管理",
      "summary": "管理云手机从创建、日常运行到回收的全过程，并调整设备与网络配置。",
      "kind": "primary",
      "notes": [],
      "capabilities": [
        {
          "id": "phone-list",
          "title": "查询云机列表",
          "summary": "按名称、分组或状态等条件查找云手机，支持分页查看。",
          "notes": [],
          "keywords": ["云手机", "列表", "筛选", "分页"],
          "references": [
            {
              "operation_id": "listEnvs",
              "method": "GET",
              "path": "/api/v1/envs"
            }
          ],
          "anchor": "capability-phone-list"
        },
        {
          "id": "phone-details",
          "title": "查看云机详情",
          "summary": "查看单台云手机的基础信息、所属资源和最近同步的状态。",
          "notes": [],
          "keywords": ["详情", "状态", "设备信息"],
          "references": [
            {
              "operation_id": "getEnv",
              "method": "GET",
              "path": "/api/v1/envs/{resource_id}"
            }
          ],
          "anchor": "capability-phone-details"
        },
        {
          "id": "phone-statistics",
          "title": "查看云机统计",
          "summary": "汇总云手机数量、开关机状态及运行可用数量。",
          "notes": [
            "运行可用需要同时满足开机和网络可用；最近同步状态不保证此刻可连接或可投屏。"
          ],
          "keywords": ["统计", "数量", "运行可用"],
          "references": [
            {
              "operation_id": "getEnvStats",
              "method": "GET",
              "path": "/api/v1/envs-stats"
            }
          ],
          "anchor": "capability-phone-statistics"
        },
        {
          "id": "phone-create",
          "title": "创建云机",
          "summary": "在选定云卡上按已有镜像和机型创建一台或多台云手机。",
          "notes": [],
          "keywords": ["创建", "新建", "批量创建", "容量"],
          "references": [
            {
              "operation_id": "getEnvCreateOptions",
              "method": "GET",
              "path": "/api/v1/boxes/{box_id}/create-options"
            },
            {
              "operation_id": "createTask",
              "action": "create",
              "request_schema": "TaskCreateRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskCreateRequest"
            }
          ],
          "anchor": "capability-phone-create"
        },
        {
          "id": "phone-start",
          "title": "开机",
          "summary": "启动选定的云手机，支持对多台设备发起操作。",
          "notes": [],
          "keywords": ["开机", "启动", "批量开机"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "start",
              "request_schema": "TaskStartRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskStartRequest"
            }
          ],
          "anchor": "capability-phone-start"
        },
        {
          "id": "phone-stop",
          "title": "关机",
          "summary": "关闭选定的云手机，支持对多台设备发起操作。",
          "notes": [],
          "keywords": ["关机", "停止", "批量关机"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "stop",
              "request_schema": "TaskStopRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskStopRequest"
            }
          ],
          "anchor": "capability-phone-stop"
        },
        {
          "id": "phone-restart",
          "title": "重启",
          "summary": "重新启动选定的云手机。",
          "notes": [],
          "keywords": ["重启", "重新启动"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "restart",
              "request_schema": "TaskRestartRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskRestartRequest"
            }
          ],
          "anchor": "capability-phone-restart"
        },
        {
          "id": "phone-name",
          "title": "修改云机名称",
          "summary": "为云手机设置便于业务识别的名称。",
          "notes": [],
          "keywords": ["名称", "重命名", "备注"],
          "references": [
            {
              "operation_id": "updateEnvMetadata",
              "method": "PATCH",
              "path": "/api/v1/envs/{env_id}"
            }
          ],
          "anchor": "capability-phone-name"
        },
        {
          "id": "phone-groups",
          "title": "管理云机分组",
          "summary": "查看已有分组，并调整云手机的分组归属。",
          "notes": [],
          "keywords": ["分组", "分类", "归属"],
          "references": [
            {
              "operation_id": "listEnvGroups",
              "method": "GET",
              "path": "/api/v1/env-groups"
            },
            {
              "operation_id": "updateEnvMetadata",
              "method": "PATCH",
              "path": "/api/v1/envs/{env_id}"
            }
          ],
          "anchor": "capability-phone-groups"
        },
        {
          "id": "phone-recycle",
          "title": "回收云机",
          "summary": "将暂不使用的云手机移入回收站。",
          "notes": [],
          "keywords": ["回收", "回收站"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "recycle",
              "request_schema": "TaskRecycleRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskRecycleRequest"
            }
          ],
          "anchor": "capability-phone-recycle"
        },
        {
          "id": "phone-restore",
          "title": "恢复回收云机",
          "summary": "将回收站中的云手机恢复使用。",
          "notes": [
            "此功能恢复回收站中的原云机；从备份创建新云机请查看备份管理。"
          ],
          "keywords": ["恢复", "回收站", "恢复使用"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "restore",
              "request_schema": "TaskRestoreRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskRestoreRequest"
            }
          ],
          "anchor": "capability-phone-restore"
        },
        {
          "id": "phone-remove",
          "title": "永久删除云机",
          "summary": "永久移除不再需要的云手机。",
          "notes": [],
          "keywords": ["删除", "永久删除", "移除"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "remove",
              "request_schema": "TaskRemoveRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskRemoveRequest"
            }
          ],
          "anchor": "capability-phone-remove"
        },
        {
          "id": "phone-repair",
          "title": "修复云机",
          "summary": "对异常云手机发起修复操作。",
          "notes": [
            "修复不会自动开关机或恢复出厂；操作后仍需确认设备是否恢复正常。"
          ],
          "keywords": ["修复", "故障", "异常"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "repair",
              "request_schema": "TaskRepairRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskRepairRequest"
            }
          ],
          "anchor": "capability-phone-repair"
        },
        {
          "id": "phone-factory-reset",
          "title": "恢复出厂",
          "summary": "清除云手机中的应用和数据，保留基础硬件标识。",
          "notes": [],
          "keywords": ["恢复出厂", "清空", "重置"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "factory_reset",
              "request_schema": "TaskFactoryResetRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskFactoryResetRequest"
            }
          ],
          "anchor": "capability-phone-factory-reset"
        },
        {
          "id": "phone-new-device",
          "title": "一键新机",
          "summary": "清除应用和数据，并重新生成基础配置及硬件标识。",
          "notes": [],
          "keywords": ["一键新机", "新机", "硬件标识"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "new_device",
              "request_schema": "TaskNewDeviceRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskNewDeviceRequest"
            }
          ],
          "anchor": "capability-phone-new-device"
        },
        {
          "id": "phone-operation-availability",
          "title": "查询可用操作",
          "summary": "查看某台云手机支持哪些操作，以及当前是否具备执行条件。",
          "notes": [],
          "keywords": ["支持能力", "可用操作", "执行条件"],
          "references": [
            {
              "operation_id": "getEnvCapabilities",
              "method": "GET",
              "path": "/api/v1/envs/{env_id}/capabilities"
            }
          ],
          "anchor": "capability-phone-operation-availability"
        },
        {
          "id": "phone-network-details",
          "title": "查看内网地址",
          "summary": "查看云手机最近读取到的内网地址，辅助连接和网络排查。",
          "notes": [],
          "keywords": ["网络", "内网", "IP地址"],
          "references": [
            {
              "operation_id": "getEnvNetwork",
              "method": "GET",
              "path": "/api/v1/envs/{env_id}/network"
            }
          ],
          "anchor": "capability-phone-network-details"
        },
        {
          "id": "phone-current-configuration",
          "title": "查看当前配置",
          "summary": "查看云手机最近读取到的分辨率、代理和域名解析设置。",
          "notes": [],
          "keywords": ["配置", "分辨率", "代理", "DNS"],
          "references": [
            {
              "operation_id": "getEnvConfiguration",
              "method": "GET",
              "path": "/api/v1/envs/{env_id}/configuration"
            }
          ],
          "anchor": "capability-phone-current-configuration"
        },
        {
          "id": "phone-resolution",
          "title": "设置分辨率",
          "summary": "调整云手机画面尺寸，或恢复设备默认分辨率。",
          "notes": [],
          "keywords": ["分辨率", "画面尺寸", "显示"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "resolution",
              "request_schema": "TaskResolutionRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskResolutionRequest"
            }
          ],
          "anchor": "capability-phone-resolution"
        },
        {
          "id": "phone-screen-orientation",
          "title": "设置屏幕方向",
          "summary": "将云手机设置为横屏、竖屏或反向显示。",
          "notes": [],
          "keywords": ["横屏", "竖屏", "屏幕方向"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "rotation",
              "request_schema": "TaskRotationRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskRotationRequest"
            }
          ],
          "anchor": "capability-phone-screen-orientation"
        },
        {
          "id": "phone-device-profile-read",
          "title": "查看设备档案",
          "summary": "查看可调整的设备档案字段与经过脱敏的现有值。",
          "notes": [],
          "keywords": ["设备档案", "设备信息", "硬件信息"],
          "references": [
            {
              "operation_id": "getDeviceProfileFields",
              "method": "GET",
              "path": "/api/v1/device-profile-fields"
            },
            {
              "operation_id": "getEnvDeviceProfile",
              "method": "GET",
              "path": "/api/v1/envs/{env_id}/device-profile"
            }
          ],
          "anchor": "capability-phone-device-profile-read"
        },
        {
          "id": "phone-device-profile-update",
          "title": "修改设备档案",
          "summary": "按指定内容或随机方式调整支持的设备标识档案。",
          "notes": [],
          "keywords": ["设备档案", "随机档案", "自定义档案"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "device_profile",
              "request_schema": "TaskDeviceProfileRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskDeviceProfileRequest"
            }
          ],
          "anchor": "capability-phone-device-profile-update"
        },
        {
          "id": "phone-saved-configuration",
          "title": "管理保存配置",
          "summary": "查看或修改云手机保存的系统、网络、位置及设备标识等配置。",
          "notes": [
            "保存配置不会自动重启云手机，也不表示运行中的设备已采用新值。"
          ],
          "keywords": ["系统", "语言", "时区", "位置", "SIM", "保存配置"],
          "references": [
            {
              "operation_id": "getEnvContainerConfig",
              "method": "GET",
              "path": "/api/v1/envs/{env_id}/container-config"
            },
            {
              "operation_id": "createTask",
              "action": "container_config",
              "request_schema": "TaskContainerConfigRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskContainerConfigRequest"
            }
          ],
          "anchor": "capability-phone-saved-configuration"
        },
        {
          "id": "phone-proxy",
          "title": "设置网络代理",
          "summary": "为云手机保存网络代理设置，或改为直连。",
          "notes": [],
          "keywords": ["代理", "网络代理", "直连"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "proxy",
              "request_schema": "TaskProxyRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskProxyRequest"
            }
          ],
          "anchor": "capability-phone-proxy"
        },
        {
          "id": "phone-proxy-check",
          "title": "检测代理出口",
          "summary": "检测机房通过指定代理或直连方式访问外网的出口。",
          "notes": ["检测结果反映机房出口，不证明云手机已经采用该代理设置。"],
          "keywords": ["代理检测", "出口", "连通性"],
          "references": [
            {
              "operation_id": "checkEnvProxy",
              "method": "POST",
              "path": "/api/v1/envs/{env_id}/proxy-check"
            }
          ],
          "anchor": "capability-phone-proxy-check"
        },
        {
          "id": "phone-dns",
          "title": "设置域名解析",
          "summary": "为云手机保存域名解析服务器设置。",
          "notes": [],
          "keywords": ["DNS", "域名解析", "网络配置"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "dns",
              "request_schema": "TaskDnsRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskDnsRequest"
            }
          ],
          "anchor": "capability-phone-dns"
        },
        {
          "id": "phone-simulated-sms",
          "title": "模拟接收短信",
          "summary": "向云手机注入指定发送方和内容的模拟短信。",
          "notes": [
            "这是模拟接收能力，不提供真实手机号、短信收发服务或验证码通道。"
          ],
          "keywords": ["短信", "模拟短信", "接收短信"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "sms",
              "request_schema": "TaskSmsRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskSmsRequest"
            }
          ],
          "anchor": "capability-phone-simulated-sms"
        }
      ],
      "anchor": "module-cloud-phones"
    },
    {
      "id": "images",
      "title": "镜像管理",
      "summary": "查看当前可用的系统镜像与机型，并用于创建云手机。",
      "kind": "primary",
      "notes": [
        "当前提供已有镜像的查询和选择，不包含镜像上传、制作、版本发布或分发管理。",
        "镜像与机型列表来自最近同步的候选信息，创建时会再次核对实际条件。"
      ],
      "capabilities": [
        {
          "id": "image-options",
          "title": "查询可用镜像",
          "summary": "查看指定云卡当前提供的系统镜像候选。",
          "notes": [],
          "keywords": ["镜像", "系统镜像", "候选"],
          "references": [
            {
              "operation_id": "getEnvCreateOptions",
              "method": "GET",
              "path": "/api/v1/boxes/{box_id}/create-options"
            }
          ],
          "anchor": "capability-image-options"
        },
        {
          "id": "image-compatible-models",
          "title": "查看兼容机型",
          "summary": "查看可选设备型号及其允许使用的镜像范围。",
          "notes": [],
          "keywords": ["机型", "型号", "品牌", "镜像兼容"],
          "references": [
            {
              "operation_id": "getEnvCreateOptions",
              "method": "GET",
              "path": "/api/v1/boxes/{box_id}/create-options"
            }
          ],
          "anchor": "capability-image-compatible-models"
        },
        {
          "id": "image-create-phone",
          "title": "使用镜像创建云机",
          "summary": "从已有镜像和兼容机型中选择组合，创建新的云手机。",
          "notes": [],
          "keywords": ["镜像创建", "创建云机", "机型选择"],
          "references": [
            {
              "operation_id": "getEnvCreateOptions",
              "method": "GET",
              "path": "/api/v1/boxes/{box_id}/create-options"
            },
            {
              "operation_id": "createTask",
              "action": "create",
              "request_schema": "TaskCreateRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskCreateRequest"
            }
          ],
          "anchor": "capability-image-create-phone"
        }
      ],
      "anchor": "module-images"
    },
    {
      "id": "tasks",
      "title": "任务管理",
      "summary": "跟踪云手机操作的执行过程，查看每台设备的结果并处理异常反馈。",
      "kind": "primary",
      "notes": [
        "任务管理跟踪已提交的设备操作，不提供定时调度或多步骤自动化工作流。"
      ],
      "capabilities": [
        {
          "id": "task-preflight",
          "title": "检查操作条件",
          "summary": "在提交前检查选定设备的权限和当前执行条件。",
          "notes": [],
          "keywords": ["预检", "权限", "执行条件"],
          "references": [
            {
              "operation_id": "preflightTask",
              "method": "POST",
              "path": "/api/v1/tasks/preflight"
            }
          ],
          "anchor": "capability-task-preflight"
        },
        {
          "id": "task-submit",
          "title": "提交单台或批量操作",
          "summary": "将选定设备的操作提交为可持续查询的任务。",
          "notes": [],
          "keywords": ["任务", "批量", "提交"],
          "references": [
            {
              "operation_id": "createTask",
              "method": "POST",
              "path": "/api/v1/tasks"
            }
          ],
          "anchor": "capability-task-submit"
        },
        {
          "id": "task-progress",
          "title": "查看进度与结果",
          "summary": "查询任务进度，并分别查看每台设备的成功、失败或待确认结果。",
          "notes": [],
          "keywords": ["进度", "结果", "逐台", "批量结果"],
          "references": [
            {
              "operation_id": "getTask",
              "method": "GET",
              "path": "/api/v1/tasks/{task_id}"
            }
          ],
          "anchor": "capability-task-progress"
        },
        {
          "id": "task-history",
          "title": "查询任务历史",
          "summary": "分页查看过去提交的操作及其目标和结果。",
          "notes": [],
          "keywords": ["历史", "记录", "任务列表"],
          "references": [
            {
              "operation_id": "listTasks",
              "method": "GET",
              "path": "/api/v1/tasks"
            }
          ],
          "anchor": "capability-task-history"
        },
        {
          "id": "task-cancel",
          "title": "请求取消任务",
          "summary": "取消尚未发出的操作，并对已发出的操作记录取消请求。",
          "notes": ["已发出的设备操作不保证停止，仍需查询原任务确认结果。"],
          "keywords": ["取消", "取消任务"],
          "references": [
            {
              "operation_id": "cancelTask",
              "method": "POST",
              "path": "/api/v1/tasks/{task_id}/cancel"
            }
          ],
          "anchor": "capability-task-cancel"
        },
        {
          "id": "task-find-original",
          "title": "找回原提交结果",
          "summary": "提交后未收到明确答复时，按原请求标识查找已受理的任务。",
          "notes": [],
          "keywords": ["响应丢失", "找回任务", "重复提交"],
          "references": [
            {
              "operation_id": "getTaskByIdempotency",
              "method": "GET",
              "path": "/api/v1/tasks/by-idempotency/{key}"
            }
          ],
          "anchor": "capability-task-find-original"
        },
        {
          "id": "task-reconcile",
          "title": "核实结果不明的操作",
          "summary": "查询原操作的处理情况或已生成文件，补全任务结果。",
          "notes": ["此功能查询原操作，不会再次执行同一设备操作。"],
          "keywords": ["结果未知", "核实", "对账", "回执"],
          "references": [
            {
              "operation_id": "reconcileTask",
              "method": "POST",
              "path": "/api/v1/tasks/{task_id}/reconcile"
            }
          ],
          "anchor": "capability-task-reconcile"
        }
      ],
      "anchor": "module-tasks"
    },
    {
      "id": "apps",
      "title": "应用管理",
      "summary": "查询应用、分发安装包，并管理云手机上的应用运行和无障碍服务。",
      "kind": "primary",
      "notes": [],
      "capabilities": [
        {
          "id": "app-installed",
          "title": "查询已安装应用",
          "summary": "查看云手机中已经安装的应用。",
          "notes": [],
          "keywords": ["已安装", "应用列表", "安装查询"],
          "references": [
            {
              "operation_id": "listEnvApps",
              "method": "GET",
              "path": "/api/v1/envs/{env_id}/apps"
            }
          ],
          "anchor": "capability-app-installed"
        },
        {
          "id": "app-catalog",
          "title": "浏览可安装应用",
          "summary": "浏览交付环境提供的可安装应用目录。",
          "notes": [
            "应用目录由交付方配置；未配置目录时，仍可使用安装包或链接安装。"
          ],
          "keywords": ["应用目录", "应用商店", "安装来源"],
          "references": [
            {
              "operation_id": "getAppCatalog",
              "method": "GET",
              "path": "/api/v1/app-catalog"
            }
          ],
          "anchor": "capability-app-catalog"
        },
        {
          "id": "app-install-file",
          "title": "安装已上传应用",
          "summary": "将云端文件库中已上传完成的安装包安装到选定云手机。",
          "notes": [],
          "keywords": ["安装", "APK", "安装包", "上传安装"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "app_install",
              "request_schema": "TaskAppInstallRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskAppInstallRequest"
            }
          ],
          "anchor": "capability-app-install-file"
        },
        {
          "id": "app-install-url",
          "title": "通过链接安装应用",
          "summary": "从下载链接获取安装包并安装到选定云手机。",
          "notes": [],
          "keywords": ["链接安装", "下载安装", "应用分发"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "app_install_url",
              "request_schema": "TaskAppInstallUrlRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskAppInstallUrlRequest"
            }
          ],
          "anchor": "capability-app-install-url"
        },
        {
          "id": "app-start",
          "title": "启动应用",
          "summary": "启动云手机上指定的已安装应用。",
          "notes": [],
          "keywords": ["启动应用", "打开应用"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "app_start",
              "request_schema": "TaskAppStartRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskAppStartRequest"
            }
          ],
          "anchor": "capability-app-start"
        },
        {
          "id": "app-stop",
          "title": "停止应用",
          "summary": "停止云手机上指定应用的运行。",
          "notes": [],
          "keywords": ["停止应用", "关闭应用"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "app_stop",
              "request_schema": "TaskAppStopRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskAppStopRequest"
            }
          ],
          "anchor": "capability-app-stop"
        },
        {
          "id": "app-restart",
          "title": "重启应用",
          "summary": "重新启动云手机上的指定应用。",
          "notes": [],
          "keywords": ["重启应用", "重新打开"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "app_restart",
              "request_schema": "TaskAppRestartRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskAppRestartRequest"
            }
          ],
          "anchor": "capability-app-restart"
        },
        {
          "id": "app-uninstall",
          "title": "卸载应用",
          "summary": "从选定云手机中移除指定应用。",
          "notes": [],
          "keywords": ["卸载", "删除应用"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "app_uninstall",
              "request_schema": "TaskAppUninstallRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskAppUninstallRequest"
            }
          ],
          "anchor": "capability-app-uninstall"
        },
        {
          "id": "app-accessibility-services",
          "title": "查询应用无障碍服务",
          "summary": "查看应用提供的无障碍服务及其状态。",
          "notes": [],
          "keywords": ["无障碍", "服务列表", "辅助功能"],
          "references": [
            {
              "operation_id": "getEnvAccessibilityServices",
              "method": "GET",
              "path": "/api/v1/envs/{env_id}/accessibility-services"
            }
          ],
          "anchor": "capability-app-accessibility-services"
        },
        {
          "id": "app-accessibility-toggle",
          "title": "设置应用无障碍服务",
          "summary": "启用或关闭指定的应用无障碍服务。",
          "notes": [],
          "keywords": ["无障碍", "启用服务", "关闭服务"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "accessibility_service",
              "request_schema": "TaskAccessibilityServiceRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskAccessibilityServiceRequest"
            }
          ],
          "anchor": "capability-app-accessibility-toggle"
        },
        {
          "id": "app-accessibility-open",
          "title": "打开应用无障碍入口",
          "summary": "为指定应用打开其无障碍入口。",
          "notes": [],
          "keywords": ["无障碍入口", "打开入口"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "accessibility_enable",
              "request_schema": "TaskAccessibilityEnableRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskAccessibilityEnableRequest"
            }
          ],
          "anchor": "capability-app-accessibility-open"
        },
        {
          "id": "app-accessibility-hide",
          "title": "隐藏应用无障碍入口",
          "summary": "隐藏指定应用的无障碍入口。",
          "notes": ["隐藏无障碍入口不等于隐藏应用。"],
          "keywords": ["无障碍入口", "隐藏入口"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "accessibility_hide",
              "request_schema": "TaskAccessibilityHideRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskAccessibilityHideRequest"
            }
          ],
          "anchor": "capability-app-accessibility-hide"
        }
      ],
      "anchor": "module-apps"
    },
    {
      "id": "files",
      "title": "文件管理",
      "summary": "管理当前云卡的云端文件，并将文件或素材传送到云手机。",
      "kind": "primary",
      "notes": [
        "上传完成只表示文件已保存到云端；安装应用或下发到手机需要另行发起操作。",
        "云端文件库按当前云卡管理，不是跨云卡公共文件库；当前接口不提供手机内部文件的完整浏览、拉取或移动管理。"
      ],
      "capabilities": [
        {
          "id": "file-upload",
          "title": "上传文件",
          "summary": "将安装包、图片、视频等文件上传到当前云卡的云端文件库，支持分片传输和完整性校验。",
          "notes": [],
          "keywords": ["上传", "分片", "素材", "安装包"],
          "references": [
            {
              "operation_id": "createFileUpload",
              "method": "POST",
              "path": "/api/v1/files/uploads"
            },
            {
              "operation_id": "uploadFilePart",
              "method": "PUT",
              "path": "/api/v1/files/{file_id}/parts/{part_number}"
            },
            {
              "operation_id": "completeFileUpload",
              "method": "POST",
              "path": "/api/v1/files/{file_id}/complete"
            }
          ],
          "anchor": "capability-file-upload"
        },
        {
          "id": "file-list",
          "title": "查询云端文件",
          "summary": "分页查看当前云卡文件库中的文件，并按名称或类型筛选。",
          "notes": [],
          "keywords": ["文件库", "列表", "筛选"],
          "references": [
            {
              "operation_id": "listFiles",
              "method": "GET",
              "path": "/api/v1/files"
            }
          ],
          "anchor": "capability-file-list"
        },
        {
          "id": "file-status",
          "title": "查看文件状态",
          "summary": "查看单个云端文件的信息，确认是否已完成上传并可使用。",
          "notes": [],
          "keywords": ["文件状态", "上传进度", "文件信息"],
          "references": [
            {
              "operation_id": "getFile",
              "method": "GET",
              "path": "/api/v1/files/{file_id}"
            }
          ],
          "anchor": "capability-file-status"
        },
        {
          "id": "file-download",
          "title": "下载云端文件",
          "summary": "下载已经就绪的云端文件，或生成有时效的下载链接。",
          "notes": [],
          "keywords": ["下载", "下载链接", "分享下载"],
          "references": [
            {
              "operation_id": "createFileTransfer",
              "method": "POST",
              "path": "/api/v1/files/{file_id}/transfers"
            },
            {
              "operation_id": "downloadFile",
              "method": "GET",
              "path": "/api/v1/files/{file_id}/content"
            },
            {
              "operation_id": "readFileTransfer",
              "method": "GET",
              "path": "/api/v1/file-transfers/{token}"
            }
          ],
          "anchor": "capability-file-download"
        },
        {
          "id": "file-delete",
          "title": "删除云端文件",
          "summary": "删除当前文件库中不再需要的文件。",
          "notes": [],
          "keywords": ["删除文件", "清理文件"],
          "references": [
            {
              "operation_id": "deleteFile",
              "method": "DELETE",
              "path": "/api/v1/files/{file_id}"
            }
          ],
          "anchor": "capability-file-delete"
        },
        {
          "id": "file-push-uploaded",
          "title": "下发已上传文件",
          "summary": "将云端文件库中的文件发送到云手机的下载、图片、视频等指定类别目录。",
          "notes": [],
          "keywords": ["下发", "推送", "传文件", "手机目录"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "file_push",
              "request_schema": "TaskFilePushRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskFilePushRequest"
            }
          ],
          "anchor": "capability-file-push-uploaded"
        },
        {
          "id": "file-push-url",
          "title": "通过链接下发文件",
          "summary": "从下载链接获取文件并发送到云手机的指定类别目录。",
          "notes": [],
          "keywords": ["链接下发", "下载推送", "素材分发"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "file_push_url",
              "request_schema": "TaskFilePushUrlRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskFilePushUrlRequest"
            }
          ],
          "anchor": "capability-file-push-url"
        },
        {
          "id": "file-screenshot",
          "title": "获取云机截图",
          "summary": "截取云手机画面，并通过云端文件获取图片。",
          "notes": [],
          "keywords": ["截图", "画面", "图片"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "screenshot",
              "request_schema": "TaskScreenshotRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskScreenshotRequest"
            },
            {
              "operation_id": "getFile",
              "method": "GET",
              "path": "/api/v1/files/{file_id}"
            },
            {
              "operation_id": "createFileTransfer",
              "method": "POST",
              "path": "/api/v1/files/{file_id}/transfers"
            }
          ],
          "anchor": "capability-file-screenshot"
        }
      ],
      "anchor": "module-files"
    },
    {
      "id": "backups",
      "title": "备份管理",
      "summary": "将云手机导出为备份，管理备份文件，并使用已有备份创建新云手机。",
      "kind": "primary",
      "notes": [
        "当前提供按需备份与恢复，不包含自动备份策略或定时保留管理；备份内容范围与恢复兼容性在交付时确认。"
      ],
      "capabilities": [
        {
          "id": "backup-availability",
          "title": "查询备份可用性",
          "summary": "确认指定云手机当前是否支持备份及相关执行条件。",
          "notes": [],
          "keywords": ["备份支持", "备份条件", "可用性"],
          "references": [
            {
              "operation_id": "getEnvBackupAvailability",
              "method": "GET",
              "path": "/api/v1/envs/{env_id}/backup-availability"
            }
          ],
          "anchor": "capability-backup-availability"
        },
        {
          "id": "backup-create",
          "title": "创建备份",
          "summary": "对选定云手机发起备份导出，并将生成文件交付到云端。",
          "notes": [],
          "keywords": ["创建备份", "导出", "数据备份"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "backup_export",
              "request_schema": "TaskBackupExportRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskBackupExportRequest"
            }
          ],
          "anchor": "capability-backup-create"
        },
        {
          "id": "backup-history",
          "title": "查看备份历史",
          "summary": "分页查看已经生成并交付完成的备份。",
          "notes": ["尚未完成的备份导出进度请查看原任务。"],
          "keywords": ["备份历史", "备份列表", "历史记录"],
          "references": [
            {
              "operation_id": "listBackups",
              "method": "GET",
              "path": "/api/v1/backups"
            }
          ],
          "anchor": "capability-backup-history"
        },
        {
          "id": "backup-download",
          "title": "下载备份",
          "summary": "为已就绪的备份获取有时效的下载地址。",
          "notes": [],
          "keywords": ["下载备份", "下载地址"],
          "references": [
            {
              "operation_id": "getBackupDownload",
              "method": "GET",
              "path": "/api/v1/backups/{backup_id}/download"
            }
          ],
          "anchor": "capability-backup-download"
        },
        {
          "id": "backup-delete",
          "title": "删除备份",
          "summary": "删除不再需要的备份文件。",
          "notes": [],
          "keywords": ["删除备份", "清理备份"],
          "references": [
            {
              "operation_id": "deleteBackup",
              "method": "DELETE",
              "path": "/api/v1/backups/{backup_id}"
            }
          ],
          "anchor": "capability-backup-delete"
        },
        {
          "id": "backup-restore-new-phone",
          "title": "从备份创建云机",
          "summary": "将已有且可使用的备份导入指定云卡，创建新的云手机。",
          "notes": [
            "恢复会创建新云机，保留原云机；需有权使用备份和目标云卡，跨机房兼容性须在交付时确认。"
          ],
          "keywords": ["备份恢复", "还原", "导入", "新建云机"],
          "references": [
            {
              "operation_id": "restoreBackupToBox",
              "method": "POST",
              "path": "/api/v1/boxes/{box_id}/backup-restores"
            },
            {
              "operation_id": "createTask",
              "action": "backup_restore",
              "request_schema": "TaskBackupRestoreRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskBackupRestoreRequest"
            }
          ],
          "anchor": "capability-backup-restore-new-phone"
        }
      ],
      "anchor": "module-backups"
    },
    {
      "id": "media",
      "title": "投屏与预览",
      "summary": "为业务页面提供云手机画面查看、交互操作及相机素材设置。",
      "kind": "support",
      "notes": [],
      "capabilities": [
        {
          "id": "media-interactive-stream",
          "title": "投屏并操作云机",
          "summary": "获取云手机投屏连接，让获授权的用户查看画面并操作设备。",
          "notes": ["当前投屏连接包含设备控制能力，需要相应操作授权。"],
          "keywords": ["投屏", "远程控制", "实时画面"],
          "references": [
            {
              "operation_id": "createMediaSession",
              "method": "POST",
              "path": "/api/v1/envs/{env_id}/media-sessions"
            }
          ],
          "anchor": "capability-media-interactive-stream"
        },
        {
          "id": "media-preview",
          "title": "查看只读预览",
          "summary": "为多台云手机获取短时只读画面预览。",
          "notes": ["预览不提供设备控制；离线或关机时不保证能取得画面。"],
          "keywords": ["预览", "只读", "多设备", "缩略图"],
          "references": [
            {
              "operation_id": "createPreviewGrants",
              "method": "POST",
              "path": "/api/v1/preview-grants"
            }
          ],
          "anchor": "capability-media-preview"
        },
        {
          "id": "media-camera-image",
          "title": "设置相机图片",
          "summary": "使用上传文件或图片链接为云手机设置相机底图。",
          "notes": [],
          "keywords": ["相机", "图片", "二维码", "相机底图"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "qrcode",
              "request_schema": "TaskQrcodeRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskQrcodeRequest"
            }
          ],
          "anchor": "capability-media-camera-image"
        },
        {
          "id": "media-camera-source",
          "title": "设置相机素材",
          "summary": "用支持的图片或视频素材替换指定摄像头的画面来源。",
          "notes": ["设置后需在云手机上确认实际相机画面。"],
          "keywords": ["相机", "视频", "摄像头", "换源"],
          "references": [
            {
              "operation_id": "createTask",
              "action": "flow_play",
              "request_schema": "TaskFlowPlayRequest",
              "method": "POST",
              "path": "/api/v1/tasks",
              "schema_ref": "#/components/schemas/TaskFlowPlayRequest"
            }
          ],
          "anchor": "capability-media-camera-source"
        }
      ],
      "anchor": "module-media"
    },
    {
      "id": "resources",
      "title": "云卡与机房资源",
      "summary": "查看承载云手机的云卡资源及所属机房，辅助安排创建和运维。",
      "kind": "support",
      "notes": [],
      "capabilities": [
        {
          "id": "resource-card-list",
          "title": "查询云卡列表",
          "summary": "查看当前可访问的云卡资源，并按条件筛选。",
          "notes": [],
          "keywords": ["云卡", "资源列表", "筛选"],
          "references": [
            {
              "operation_id": "listBoxes",
              "method": "GET",
              "path": "/api/v1/boxes"
            }
          ],
          "anchor": "capability-resource-card-list"
        },
        {
          "id": "resource-card-details",
          "title": "查看云卡详情",
          "summary": "查看单张云卡的信息与资源归属。",
          "notes": [],
          "keywords": ["云卡详情", "资源归属"],
          "references": [
            {
              "operation_id": "getBox",
              "method": "GET",
              "path": "/api/v1/boxes/{resource_id}"
            }
          ],
          "anchor": "capability-resource-card-details"
        },
        {
          "id": "resource-card-statistics",
          "title": "查看云卡统计",
          "summary": "汇总当前范围内云卡的数量与状态。",
          "notes": [],
          "keywords": ["云卡统计", "资源数量"],
          "references": [
            {
              "operation_id": "getBoxStats",
              "method": "GET",
              "path": "/api/v1/boxes-stats"
            }
          ],
          "anchor": "capability-resource-card-statistics"
        },
        {
          "id": "resource-room-list",
          "title": "查看所属机房",
          "summary": "查看可见机房的名称和在线状态。",
          "notes": [],
          "keywords": ["机房", "机房状态", "在线"],
          "references": [
            {
              "operation_id": "listRooms",
              "method": "GET",
              "path": "/api/v1/rooms"
            }
          ],
          "anchor": "capability-resource-room-list"
        }
      ],
      "anchor": "module-resources"
    },
    {
      "id": "access",
      "title": "使用授权",
      "summary": "将指定设备范围、操作权限和使用期限接入自己的业务登录体系。",
      "kind": "support",
      "notes": [
        "撤销 API 使用授权不保证立即切断已建立的投屏连接，既有投屏票据按期限失效。"
      ],
      "capabilities": [
        {
          "id": "access-create",
          "title": "开通受限使用授权",
          "summary": "为业务用户发放限定设备范围、操作权限和有效期限的访问授权。",
          "notes": [],
          "keywords": ["授权", "用户接入", "权限", "期限"],
          "references": [
            {
              "operation_id": "createAccessSession",
              "method": "POST",
              "path": "/api/v1/access-sessions"
            }
          ],
          "anchor": "capability-access-create"
        },
        {
          "id": "access-replace",
          "title": "调整使用授权",
          "summary": "更新既有用户授权的设备范围、权限或有效期限。",
          "notes": [],
          "keywords": ["更新授权", "权限调整", "期限调整"],
          "references": [
            {
              "operation_id": "replaceAccessSession",
              "method": "PUT",
              "path": "/api/v1/access-sessions/{session_id}"
            }
          ],
          "anchor": "capability-access-replace"
        },
        {
          "id": "access-find",
          "title": "查询业务登录授权",
          "summary": "根据自己的业务登录记录查找对应的使用授权。",
          "notes": [],
          "keywords": ["查询授权", "登录记录", "会话"],
          "references": [
            {
              "operation_id": "getAccessSessionByReference",
              "method": "GET",
              "path": "/api/v1/access-sessions/by-reference"
            }
          ],
          "anchor": "capability-access-find"
        },
        {
          "id": "access-revoke",
          "title": "撤销指定授权",
          "summary": "撤销某次使用授权，阻止其继续发起新的 API 访问。",
          "notes": [],
          "keywords": ["撤销授权", "退出", "停用"],
          "references": [
            {
              "operation_id": "revokeAccessSession",
              "method": "DELETE",
              "path": "/api/v1/access-sessions/{session_id}"
            }
          ],
          "anchor": "capability-access-revoke"
        },
        {
          "id": "access-revoke-login",
          "title": "撤销业务登录授权",
          "summary": "按业务登录记录撤销对应授权，用于业务退出或停用。",
          "notes": [],
          "keywords": ["业务退出", "登录撤销", "停用"],
          "references": [
            {
              "operation_id": "revokeBusinessSession",
              "method": "POST",
              "path": "/api/v1/access-session-revocations"
            }
          ],
          "anchor": "capability-access-revoke-login"
        }
      ],
      "anchor": "module-access"
    }
  ],
  "technical_only": [
    {
      "id": "technical-start-compatibility",
      "title": "兼容开机入口",
      "reason": "保留既有客户端兼容入口；客户目录统一介绍开机能力，避免重复展示。",
      "references": [
        {
          "operation_id": "requestPower",
          "method": "POST",
          "path": "/api/v1/power-requests"
        }
      ]
    },
    {
      "id": "technical-core-capabilities",
      "title": "平台版本与能力查询",
      "reason": "供技术人员确认 Core 版本和全局接入能力，不作为客户业务模块。",
      "references": [
        {
          "operation_id": "getCapabilities",
          "method": "GET",
          "path": "/api/v1/capabilities"
        }
      ]
    },
    {
      "id": "technical-service-credentials",
      "title": "服务凭据维护",
      "reason": "用于可信服务端接入和管理员凭据生命周期管理，由技术人员操作。",
      "references": [
        {
          "operation_id": "createServiceCredential",
          "method": "POST",
          "path": "/api/v1/admin/service-credentials"
        },
        {
          "operation_id": "disableServiceCredential",
          "method": "DELETE",
          "path": "/api/v1/admin/service-credentials/{credential_id}"
        }
      ]
    },
    {
      "id": "technical-resource-handover",
      "title": "云卡分配与释放交接",
      "reason": "用于管理员完成资源预留、分配及清理交接，不等同于云机回收或客户使用授权。",
      "references": [
        {
          "operation_id": "reserveBox",
          "method": "POST",
          "path": "/api/v1/admin/boxes/{box_id}/reservations"
        },
        {
          "operation_id": "allocateBox",
          "method": "POST",
          "path": "/api/v1/admin/boxes/{box_id}/allocations"
        },
        {
          "operation_id": "requestBoxRelease",
          "method": "POST",
          "path": "/api/v1/admin/boxes/{box_id}/release-requests"
        },
        {
          "operation_id": "confirmBoxRelease",
          "method": "POST",
          "path": "/api/v1/admin/boxes/{box_id}/release-confirmations"
        }
      ]
    },
    {
      "id": "technical-health",
      "title": "服务健康与后台就绪检查",
      "reason": "供部署监控检查进程、数据依赖和任务后台，不代表具体设备可用。",
      "references": [
        {
          "operation_id": "getLiveness",
          "method": "GET",
          "path": "/health/live"
        },
        {
          "operation_id": "getReadiness",
          "method": "GET",
          "path": "/health/ready"
        },
        {
          "operation_id": "getWorkerReadiness",
          "method": "GET",
          "path": "/health/worker"
        }
      ]
    },
    {
      "id": "technical-room-credentials",
      "title": "机房凭据维护",
      "reason": "用于机房接入身份的查询、发放、轮换、停用和吊销，由平台技术人员维护。",
      "references": [
        {
          "operation_id": "getRoomCredential",
          "method": "GET",
          "path": "/api/v1/admin/room-credentials/{server_id}"
        },
        {
          "operation_id": "issueRoomCredential",
          "method": "POST",
          "path": "/api/v1/admin/room-credentials/{server_id}"
        },
        {
          "operation_id": "rotateRoomCredential",
          "method": "POST",
          "path": "/api/v1/admin/room-credentials/{server_id}/rotations"
        },
        {
          "operation_id": "disableRoomCredential",
          "method": "POST",
          "path": "/api/v1/admin/room-credentials/{server_id}/disable"
        },
        {
          "operation_id": "revokeRoomCredential",
          "method": "POST",
          "path": "/api/v1/admin/room-credentials/{server_id}/revocations"
        }
      ]
    },
    {
      "id": "technical-media-configuration",
      "title": "机房媒体入口配置",
      "reason": "属于投屏基础设施接线，不作为用户投屏操作展示。",
      "references": [
        {
          "operation_id": "configureRoomMedia",
          "method": "PUT",
          "path": "/api/v1/admin/rooms/{server_id}/media"
        }
      ]
    },
    {
      "id": "technical-task-recovery",
      "title": "未知任务后续操作恢复",
      "reason": "需要明确人工确认，仅允许继续后续操作；保留原结果未知及清理约束，不等于重试、成功或取消。",
      "references": [
        {
          "operation_id": "recoverTask",
          "method": "POST",
          "path": "/api/v1/tasks/{task_id}/recovery"
        }
      ]
    },
    {
      "id": "technical-adb-shell",
      "title": "设备命令执行",
      "reason": "面向具有设备调试权限的技术人员，不作为半技术客户的日常业务功能展开。",
      "references": [
        {
          "operation_id": "createTask",
          "action": "adb_shell",
          "request_schema": "TaskAdbShellRequest",
          "method": "POST",
          "path": "/api/v1/tasks",
          "schema_ref": "#/components/schemas/TaskAdbShellRequest"
        }
      ]
    }
  ],
  "locale": "zh-CN",
  "text_sha256": "8f33347383cacda41abbae876b909247d5c720c729be9501b023d6c624ea86c4",
  "contract_version": "0.2.0",
  "spec_sha256": "f8a9a88337fc14c7df5eee3822d39c8094bdedaeffc51065db1b5dcd000cbcf2",
  "catalog_sha256": "f2e2b4f3ccb54345faa78157eee68c6808aac6cb634a6c410d83e47b9f598d7e"
}