云柚

文档中心

自动化接口参考

最近更新:2026/11/13

北向自动化接口的基础地址是 https://app.yunyoo.ai/api,下文的路径都接在它后面。请求带 Authorization: Bearer <机器 token>,机器 token 的签发与作用域见自动化概览。

平台对这些接口校验请求签名,官方命令行会自动签名。自己编写的程序请改用 MCP 远程形态,或经命令行工具调用;签名方式目前不对外提供。

返回体统一为 {"code": 0, "data": …, "msg": "…"},code 为 0 表示成功,其它值见错误码。限流时返回 HTTP 429、错误码 53009 与 Retry-After 响应头。平台开启强制确认时,高风险的动作会先挂起并返回 53010,data.confirmation 给出确认单;用户批准后,带请求头 X-Yunyoo-Confirmation: <确认单编号> 重发同一请求。请求头 X-Yunyoo-Intent 可以写明这次操作的意图,确认页会显示给用户;带上 traceparent 时,同一追踪编号会记进运行报告。

会话

列出设备

GET /cloudphone/automation/envs

列出凭据范围内的设备:环境 ID、名称与状态。

权限:env.view(查看环境)。

返回的 data:EnvSummary[]。

列出节点

GET /cloudphone/automation/nodes

列出凭据可见的节点摘要。

作用域:observe。权限:env.view(查看环境)。

参数位置类型必填说明
providerId查询integer否只看这个节点

返回的 data:NodeSummary[]。

校验凭据

GET /cloudphone/automation/whoami

返回凭据所属的用户、作用域、设备范围与这个凭据可用的 MCP 工具。

返回的 data:WhoAmIResp

观测

证明状态

GET /cloudphone/automation/envs/{id}/attestation

只读查询设备的证明状态。

作用域:observe。权限:env.view(查看环境)。

参数位置类型必填说明
id路径integer是环境 ID

返回的 data:{attestation: AttestationView}。

截图

GET /cloudphone/automation/envs/{id}/screenshot

截取设备屏幕。带 max_edge、format、quality、annotate 任一参数时返回压缩后的图像与原始分辨率、缩放比例(缺省 JPEG、长边 1024);都不带时返回旧版的原始截图。

作用域:observe。权限:env.remote.screenshot(截图)。

参数位置类型必填说明
id路径integer是环境 ID
max_edge查询integer否长边像素,256–2048,缺省 1024
format查询string否jpeg(缺省)或 png
quality查询integer否JPEG 质量,1–100,缺省 75
annotate查询boolean否为 true 时在图上标出最近一次读取界面的元素编号

返回的 data:ScreenshotView

自动化状态

GET /cloudphone/automation/envs/{id}/status

查询设备是否可交互、能力位与控制状态;动作前或动作失败时调用,按能力位判断可用的动作。

作用域:observe。权限:env.view(查看环境)。

参数位置类型必填说明
id路径integer是环境 ID

返回的 data:StatusView

读取界面

GET /cloudphone/automation/envs/{id}/ui-tree

读取设备当前界面。带 format、scope、under、depth、max 任一参数时返回紧凑快照(缺省)或结构化树;都不带时返回旧版的原始界面树,新接入请带 format。

作用域:observe。权限:env.remote.screenshot(截图)。

参数位置类型必填说明
id路径integer是环境 ID
includeInvisible查询boolean否为 true 时包含不可见的元素
format查询string否compact(缺省,紧凑快照)或 json(结构化树)
scope查询string否interactive(缺省,只列可交互或带文字的元素)或 all(全部元素)
under查询string否只看这个元素编号下的子树
depth查询integer否子树深度上限,1–100
max查询integer否最多列出的元素行数,1–2000,缺省 150

返回的 data:UITreeView

查找元素

POST /cloudphone/automation/envs/{id}/ui/find

按文字、正则、资源 ID、描述或类名在当前界面查找元素,条件之间取「且」;返回命中元素的紧凑行与在当前界面唯一的选择器建议,没有命中时返回空结果。

作用域:observe。权限:env.remote.screenshot(截图)。

参数位置类型必填说明
id路径integer是环境 ID
请求体UIFindInput是查找条件

返回的 data:UIFindView

界面动作

清空输入框

POST /cloudphone/automation/envs/{id}/ui/clear

清空焦点输入框或 selector 指定的输入框。

作用域:ui-action。权限:env.remote.control(远程操控)。

参数位置类型必填说明
id路径integer是环境 ID
请求体UIActionInput是动作参数

返回的 data:UIActionResult

输入法动作

POST /cloudphone/automation/envs/{id}/ui/editor

对焦点输入框执行输入法动作 editorAction(Android 的 IME 动作编号,如 2 前往、3 搜索、4 发送、6 完成)

作用域:ui-action。权限:env.remote.control(远程操控)。

参数位置类型必填说明
id路径integer是环境 ID
请求体UIActionInput是动作参数

返回的 data:UIActionResult

按键

POST /cloudphone/automation/envs/{id}/ui/key

发送 Android 按键码 code(66 回车、4 返回、3 回到桌面、67 删除)

作用域:ui-action。权限:env.remote.control(远程操控)。

参数位置类型必填说明
id路径integer是环境 ID
请求体UIActionInput是动作参数

返回的 data:UIActionResult

滑动

POST /cloudphone/automation/envs/{id}/ui/swipe

从 from 滑到 to(归一化坐标 0..1),durationMs 为滑动时长;用于翻页、滚动列表或下拉刷新。

作用域:ui-action。权限:env.remote.control(远程操控)。

参数位置类型必填说明
id路径integer是环境 ID
请求体UIActionInput是动作参数

返回的 data:UIActionResult

点按

POST /cloudphone/automation/envs/{id}/ui/tap

点按元素;优先用元素编号(带上快照版本)、资源 ID、文字或描述定位,没有可用元素时才用归一化坐标 point;longPressMs 大于 0 时长按;平台判定为高风险的点按可能先挂起并返回确认单。

作用域:ui-action。权限:env.remote.control(远程操控)。

参数位置类型必填说明
id路径integer是环境 ID
请求体UIActionInput是动作参数

返回的 data:UIActionResult

输入文本

POST /cloudphone/automation/envs/{id}/ui/type

向焦点输入框(或 selector 指定的元素)输入 text;clear 为 true 时先清空,submit 为 true 时输入后发送回车;能力位不含 textInput 时只能输入 ASCII。

作用域:ui-action。权限:env.remote.control(远程操控)。

参数位置类型必填说明
id路径integer是环境 ID
请求体UIActionInput是动作参数

返回的 data:UIActionResult

等待条件

POST /cloudphone/automation/envs/{id}/ui/wait

等待一个条件成立:selector 指定的元素出现,或 until 为 gone(元素消失)、idle(界面保持 idleMs 毫秒不变)、animation(动画结束)、package(应用到前台);一次只等一种条件,timeoutMs 为等待上限,超时返回 1003。

作用域:ui-action。权限:env.remote.control(远程操控)。

参数位置类型必填说明
id路径integer是环境 ID
请求体UIActionInput是动作参数

返回的 data:UIActionResult

批量动作、流程宏与运行报告

运行流程宏

POST /cloudphone/automation/envs/{id}/flows

校验流程宏 yunyoo.flow/2 后作为异步任务执行,返回任务编号,用查询任务跟踪;偏离时任务以 53019 结束并带偏离报告。

作用域:ui-action。权限:env.remote.control(远程操控)。

参数位置类型必填说明
id路径integer是环境 ID
请求体FlowRunInput是流程宏与变量

返回的 data:FlowStarted

批量动作

POST /cloudphone/automation/envs/{id}/ui/batch

一次提交多步界面与应用动作并逐步执行,步骤结构与流程宏 yunyoo.flow/2 相同,最多 50 步、60 秒;缺省遇到首个失败即停,返回逐步结果与失败位置;需要确认时返回确认单与续跑位置(from、at、sub)

作用域:ui-action。权限:env.remote.control(远程操控)。

参数位置类型必填说明
id路径integer是环境 ID
请求体UIBatchInput是步骤与变量

返回的 data:FlowView

校验流程宏

POST /cloudphone/automation/flows/check

只校验流程宏或步骤列表的格式,返回步数、运行时要传入的变量与用到的密码占位名,不执行。

作用域:ui-action。权限:env.remote.control(远程操控)。

参数位置类型必填说明
请求体FlowCheckInput是流程宏或步骤列表

返回的 data:FlowCheckView

列出运行记录

GET /cloudphone/automation/runs

按时间倒序列出运行记录。

权限:automation.report.view(查看自动化运行记录)。

参数位置类型必填说明
env查询integer否只看这台设备
limit查询integer否最多返回的条数

返回的 data:{list: RunView[]}。

运行报告

GET /cloudphone/automation/runs/{rid}

取一次运行的报告:各步的工具、参数摘要、目标元素、生效判定、结果码与耗时。

权限:automation.report.view(查看自动化运行记录)。

参数位置类型必填说明
rid路径string是运行编号

返回的 data:RunView

生成流程宏草稿

GET /cloudphone/automation/runs/{rid}/flow

从一次运行记录生成流程宏草稿;只取成功的动作,输入文字不能照录时改为变量 INPUT_n。

权限:automation.report.view(查看自动化运行记录)。

参数位置类型必填说明
rid路径string是运行编号

返回的 data:Drafted

确认单与人工交接

查询确认单

GET /cloudphone/automation/confirmations/{cid}

查询确认单的状态;带 wait 时最多等待这么多秒,直到状态不再是 pending。

权限:env.view(查看环境)。

参数位置类型必填说明
cid路径string是确认单编号
wait查询integer否最长等待秒数,0–60

返回的 data:ConfirmationView

撤回确认单

POST /cloudphone/automation/confirmations/{cid}/cancel

撤回还在等待的确认单;撤回后带它重发返回 53011。

权限:env.view(查看环境)。

参数位置类型必填说明
cid路径string是确认单编号

返回的 data:ConfirmationView

人工交接

POST /cloudphone/automation/envs/{id}/handoff

请用户接手这台设备,reason 写明原因;交接期间动作类接口返回 53014,用户在查看器里交还后恢复;不带 reason 时只查询当前控制状态。

作用域:ui-action。权限:env.remote.control(远程操控)。

参数位置类型必填说明
id路径integer是环境 ID
请求体HandoffReq否交接原因

返回的 data:ControlView

应用

应用操作

POST /cloudphone/automation/envs/{id}/app-op

启动、停止、清除数据、卸载或更新应用;卸载与清除数据属于高风险操作,需要用户确认时返回确认单。

作用域:app。权限:其中之一:app.operate(启动与停止应用)、app.remove(卸载应用)、app.install(安装应用)。

参数位置类型必填说明
id路径integer是环境 ID
请求体AppOpInput是操作与包名

返回的 data:RunCommandResult

列出应用

GET /cloudphone/automation/envs/{id}/apps

format=list 时返回包名与可读名称;不带时返回旧版的设备侧列举结果,新接入请带 format=list。

作用域:app。权限:app.view(浏览应用)。

参数位置类型必填说明
id路径integer是环境 ID
format查询string否list

返回的 data:AppListView

安装应用

POST /cloudphone/automation/envs/{id}/apps

从应用库安装应用,返回安装任务,用查询任务跟踪。

作用域:app。权限:app.install(安装应用)。

参数位置类型必填说明
id路径integer是环境 ID
请求体AppInstallReq是应用库里的应用编号

返回的 data:AgentTask

文件

取回文件

POST /cloudphone/automation/envs/{id}/files/pull

从设备取回一个文件,返回任务;任务完成后,查询任务给出 15 分钟内有效的下载链接。

作用域:file。权限:env.file.download(下载文件)。

参数位置类型必填说明
id路径integer是环境 ID
请求体FilePullReq是设备上的文件路径

返回的 data:AgentTask

推送文件

POST /cloudphone/automation/envs/{id}/files/push

把已上传的文件推到设备的下载目录,返回推送任务。

作用域:file。权限:env.file.upload(上传文件)。

参数位置类型必填说明
id路径integer是环境 ID
请求体FilePushReq是上传会话的 token

返回的 data:AgentTask

创建上传会话

POST /cloudphone/automation/envs/{id}/files/upload-session

为要推到设备的文件创建上传会话;按返回的地址上传后,用其中的 token 调用推送文件。

作用域:file。权限:env.file.upload(上传文件)。

参数位置类型必填说明
id路径integer是环境 ID
请求体FileSessionReq是文件名与大小

返回的 data:UploadSessionResp

开关机与任务

暂停

POST /cloudphone/automation/envs/{id}/pause

暂停运行并保留内存状态,只适用于本地节点上的环境;返回任务。

作用域:lifecycle。权限:env.stop(停止环境)。

参数位置类型必填说明
id路径integer是环境 ID

返回的 data:{status: string, taskId: integer}。

重启

POST /cloudphone/automation/envs/{id}/reboot

重启设备,在后台进行。

作用域:lifecycle。权限:env.start(启动环境)、env.stop(停止环境)。

参数位置类型必填说明
id路径integer是环境 ID

返回的 data 为空。

继续运行

POST /cloudphone/automation/envs/{id}/resume

让暂停的环境继续运行;返回任务。

作用域:lifecycle。权限:env.start(启动环境)。

参数位置类型必填说明
id路径integer是环境 ID

返回的 data:{status: string, taskId: integer}。

开机

POST /cloudphone/automation/envs/{id}/start

开机,在后台进行。

作用域:lifecycle。权限:env.start(启动环境)。

参数位置类型必填说明
id路径integer是环境 ID

返回的 data 为空。

关机

POST /cloudphone/automation/envs/{id}/stop

关机,在后台进行。

作用域:lifecycle。权限:env.stop(停止环境)。

参数位置类型必填说明
id路径integer是环境 ID

返回的 data 为空。

同步到云端

POST /cloudphone/automation/envs/{id}/sync

把本地节点上环境的数据同步到云端。

作用域:lifecycle。权限:env.sync(同步到云端)。

参数位置类型必填说明
id路径integer是环境 ID
请求体EnvSyncReq否同步参数

返回的 data 为空。

查询任务

GET /cloudphone/automation/tasks/{id}

查询异步任务(开关机、备份、文件推拉、应用安装、流程宏)的状态与结果,所需作用域随任务类型而定;文件取回完成且有下载文件权限时附 15 分钟内有效的下载链接。

权限:env.view(查看环境)。

参数位置类型必填说明
id路径integer是任务编号

返回的 data:TaskView

备份与可移植包

列出备份

GET /cloudphone/automation/backups

列出一台设备的备份。

作用域:backup。权限:env.backup.view(查看备份)。

参数位置类型必填说明
env查询integer是环境 ID
kind查询string否只看这种类型的备份

返回的 data:{list: EnvBackup[]}。

封装可移植包

POST /cloudphone/automation/backups/{id}/package

把一份备份封装为可移植包,返回包编号与封装任务。

作用域:backup。权限:env.backup.export(导出备份)。

参数位置类型必填说明
id路径integer是备份 ID
请求体PackageCreateReq是封装参数

返回的 data:PackageCreateResult

还原应用级备份

POST /cloudphone/automation/backups/{id}/restore-app

立即用应用级备份还原该应用,返回任务;属于高风险操作,需要用户确认时返回确认单。

作用域:backup。权限:env.backup.restore(还原备份)。

参数位置类型必填说明
id路径integer是备份 ID
请求体AppRestoreReq否还原参数

返回的 data:{taskId: integer}。

创建整机备份

POST /cloudphone/automation/envs/{id}/backups

为设备创建整机备份。

作用域:backup。权限:env.backup.create(创建备份)。

参数位置类型必填说明
id路径integer是环境 ID
请求体BackupCreateReq是备份参数

返回的 data:EnvBackup

创建应用级备份

POST /cloudphone/automation/envs/{id}/backups/app

只备份一个应用的数据。

作用域:backup。权限:env.backup.create(创建备份)。

参数位置类型必填说明
id路径integer是环境 ID
请求体AppBackupCreateReq是应用与备份参数

返回的 data:EnvBackup

设置待还原备份

POST /cloudphone/automation/envs/{id}/restore

设置一份整机备份在下次开机时还原,backupId 为空时取消;属于高风险操作,需要用户确认时返回确认单。

作用域:backup。权限:env.backup.restore(还原备份)。

参数位置类型必填说明
id路径integer是环境 ID
请求体RestoreSetReq是要还原的备份

返回的 data 为空。

包详情

GET /cloudphone/automation/packages/{pid}

查询可移植包的详情与分享情况。

作用域:backup。权限:env.backup.view(查看备份)。

参数位置类型必填说明
pid路径string是包编号

返回的 data:PackageDetail

下载包

GET /cloudphone/automation/packages/{pid}/download

以 302 跳转到包的预签名下载地址。

作用域:backup。权限:env.backup.export(导出备份)。

参数位置类型必填说明
pid路径string是包编号

返回 HTTP 302,跳转到下载地址。

分享备份包

POST /cloudphone/automation/packages/{pid}/shares

为包创建分享链接,令牌只在这次返回;需要用户确认时返回确认单。

作用域:backup。权限:env.backup.share(分享备份)。

参数位置类型必填说明
pid路径string是包编号
请求体ShareCreateReq否有效期与下载次数

返回的 data:ShareCreateResult

导入包

POST /cloudphone/automation/packages/import

把包导入为还原、数据环境、应用、档案或新环境;目标环境须在凭据范围内;dryRun 为 true 时只返回导入计划。

作用域:backup。权限:env.backup.import(导入备份)。

参数位置类型必填说明
请求体PackageImportReq是导入目标与参数

返回的 data:PackageImportResult

检视上传的包

POST /cloudphone/automation/packages/inspect

读取已上传的包的元数据,导入前用它确认内容。

作用域:backup。权限:env.backup.import(导入备份)。

参数位置类型必填说明
请求体PackageInspectReq是上传会话

返回的 data:PackageDetail

创建包上传会话

POST /cloudphone/automation/packages/upload-session

为要导入的包创建上传会话。

作用域:backup。权限:env.backup.import(导入备份)。

参数位置类型必填说明
请求体PackageUploadReq是文件名与大小

返回的 data:packageUploadSession

多设备批量

多设备批量动作

POST /cloudphone/automation/batch

对分组、标签或设备列表选中的多台设备执行同一个界面动作、应用操作或命令,逐台返回结果,一台失败不影响其它设备;所需作用域随 kind 而定。

权限:。

参数位置类型必填说明
请求体BatchInput是选择器与动作

返回的 data:BatchItemResult[]。

逃生舱

本地通道桥接

POST /cloudphone/automation/envs/{id}/connect

建立本地通道桥接会话;逃生舱,需要 local-bridge 作用域,缺省不授予;建立后经 tunnel 连接数据面。

作用域:local-bridge。权限:env.adb.connect(ADB 连接)。

参数位置类型必填说明
id路径integer是环境 ID

返回的 data:ConnectResp

执行命令

POST /cloudphone/automation/envs/{id}/run-command

在设备上执行命令;逃生舱,需要 run-command 作用域,缺省不授予;只在界面与应用接口做不到时使用。

作用域:run-command。权限:env.shell(终端与执行命令)。

参数位置类型必填说明
id路径integer是环境 ID
请求体RunCommandInput是命令与参数

返回的 data:RunCommandView

桥接数据面

GET /cloudphone/automation/envs/{id}/tunnel

升级为 WebSocket 后双向转发桥接的字节流。

作用域:local-bridge。权限:env.adb.connect(ADB 连接)。

参数位置类型必填说明
id路径integer是环境 ID

返回 HTTP 101,已升级为 WebSocket。

数据类型

下面是请求体与返回中用到的数据类型,按名称排序。

AgentTask

字段类型必填说明
IDinteger否主键ID
backupIdinteger否
createdAtstring否创建时间
detailstring否
envIdinteger否
errorCodestring否
expiresAtstring否
messagestring否
parentIdinteger否
percentinteger否
providerIdinteger否
sessionIdinteger否
stagestring否
statusstring否
typestring否
updatedAtstring否更新时间

AppBackupCreateReq

字段类型必填说明
includeObbboolean否同时备份应用的 OBB 数据
packagestring是应用包名
targetstring否存放位置:cloud(缺省)或 local(只存在环境所在的本地节点)

AppInstallReq

字段类型必填说明
appIdsinteger[]是应用库里的应用编号

AppItem

字段类型必填说明
labelstring否可读名称
packagestring否包名
versionNamestring否版本名

AppListView

字段类型必填说明
appsAppItem[]否已安装的应用
devicestring否设备,写作 env:<环境 ID>
notestring否改为设备侧列举时的说明
sourcestring否清单来源:platform(平台清单)或 device(设备侧列举)

AppOpInput

字段类型必填说明
activitystring否启动时指定的页面
keepDataboolean否卸载时保留数据
opstring是操作:launch、stop、clear、uninstall 或 update
packagestring是应用包名

AppRestoreReq

字段类型必填说明
ignoreVersionboolean否应用版本与备份不一致时照常还原

AttestationView

字段类型必填说明
checkAttestCheckView否
deliverystring否
enrollmentStatusstring否
keyboxFingerprintstring否
keyboxRefinteger否
keyboxStatusstring否
leaseStatusstring否
lockedboolean否
modestring否
runtimeModestring否
sourcestring否
strongIntegrityboolean否
supplystring否
truststring否

AttestCheckView

字段类型必填说明
checkedAtstring否
failedstring否
keyboxMatchboolean否
rootKindstring否
statestring否

AttestSource

字段类型必填说明
keyboxIdinteger否kind 为 user 时的 keybox 编号
kindstring否pool(平台,缺省)或 user(自己的 keybox)

automation.Bounds

字段类型必填说明
bottomnumber否
leftnumber否
rightnumber否
topnumber否

automation.Selector

字段类型必填说明
classstring否类名
descstring否描述
idstring否资源 ID
indexinteger否同样条件命中多个时的序号,从 0 起
textstring否文字等于
textContainsstring否文字包含
textRegexstring否文字匹配的正则

BackupCreateReq

字段类型必填说明
dataEnvIdinteger否要备份的数据环境,缺省为当前使用的数据环境
ignoreWindowboolean否本地 Linux 节点上不等备份时间窗,立即执行
kindstring否备份类型:full(缺省)或 incremental
namestring否备份名称
parentBackupIdinteger否增量备份所基于的备份
targetstring否存放位置:cloud(缺省)或 local(只存在环境所在的本地节点)

BackupShare

字段类型必填说明
IDinteger否主键ID
createdAtstring否创建时间
createdByinteger否
downloadCountinteger否
expiresAtstring否
lastDownloadAtstring否
maxDownloadsinteger否
packageIdinteger否
requireLoginboolean否
revokedAtstring否
updatedAtstring否更新时间

BatchInput

字段类型必填说明
appOpAppOpInput否kind 为 app-op 时的应用操作
commandRunCommandInput否kind 为 run-command 时的命令
kindstring是动作类型:ui-action、app-op 或 run-command
selectorSelectorSpec否选中的设备
uiActionUIActionInput否kind 为 ui-action 时的界面动作

BatchItemResult

字段类型必填说明
envIdinteger否环境 ID
errorstring否失败原因
okboolean否这台设备是否成功
resultany否这台设备的结果,结构与单台接口相同

Candidate

字段类型必填说明
linestring否元素的紧凑行
refstring否元素编号
scorenumber否
selectorsautomation.Selector[]否在当前界面唯一的选择器建议

ConfirmationView

字段类型必填说明
actionstring否被挂起的动作
categoriesstring[]否风险类别
clientNamestring否发起方客户端
createdAtstring否创建时间
decidedAtstring否决定时间
envIdinteger否环境 ID
executedAtstring否执行时间
expiresAtstring否过期时间
idstring否确认单编号
intentstring否调用方声明的意图
skillNamestring否发起方 Skill
statusstring否pending、approved、denied、expired、cancelled 或 executed
summarystring否动作摘要
thumbstring否动作前的截图
tokenKindstring否发起方凭据的种类
tokenNamestring否发起方凭据的名称
urlstring否确认页地址

ConnectResp

字段类型必填说明
expiresAtstring否过期时间
hintstring否使用说明
sessionIdstring否桥接会话编号

ControlView

字段类型必填说明
byYouboolean否是否由当前用户接管
enabledboolean否是否开启了人工接管
envIdinteger否环境 ID
lastActionAtstring否最近一次自动化动作的时间
reasonstring否交接原因
sincestring否进入当前状态的时间
statestring否控制状态:free、automating、human 或 waiting-human
urlstring否查看器地址

Deviation

字段类型必填说明
candidatesCandidate[]否
commandstring否
expectIdentity否
foregroundstring否
foundHit否
pathstring否
reasonstring否
resumeinteger否
screenstring否
selectorflow.Selector否
stepinteger否

Drafted

字段类型必填说明
flow流程宏 yunyoo.flow/2否生成的流程宏
skippedinteger否没有收进草稿的步数
varsstring[]否运行时要传入的变量,对应不能照录的输入

EnvBackup

字段类型必填说明
IDinteger否主键ID
actorUserIdinteger否
androidVersionstring否
appPackagestring否
appVersionCodeinteger否
boundPackagestring否
chainDepthinteger否
createdAtstring否创建时间
dataEnvIdinteger否
deviceProfilestring否
envIdinteger否
errorCodestring否
expiresAtstring否
formatinteger否
hasRuntimeStateboolean否
hasSecureStateboolean否
identityMatchboolean否
importPackageIdinteger否
kindstring否
locationstring否
namestring否
nodeIdinteger否
parentBackupIdinteger否
plainSizeinteger否
purposestring否
remarkstring否
retryCountinteger否
rootVariantstring否
scheduledAtstring否
sourcestring否
statusstring否
updatedAtstring否更新时间
usedBytesinteger否

EnvScopeSpec

字段类型必填说明
envIdsinteger[]否kind 为 env 时的环境
groupIdsinteger[]否kind 为 group 时的分组
kindstring否范围:all、group 或 env

EnvSummary

字段类型必填说明
groupIdinteger否分组 ID
idinteger否环境 ID
statusstring否状态
titlestring否名称

EnvSyncReq

字段类型必填说明
stopAndSyncboolean否为 true 时先关机再同步

FilePullReq

字段类型必填说明
pathstring是设备上的文件路径

FilePushReq

字段类型必填说明
tokenstring是上传会话返回的 token

FileSessionReq

字段类型必填说明
namestring是文件名
sizeinteger是文件字节数

flow.Selector

字段类型必填说明
classstring否类名
descstring否描述
idstring否资源 ID
indexinteger否同样条件命中多个时的序号,从 0 起
pointPoint否元素定位不到时的后备坐标,取屏幕宽高的比例
textstring否文字等于
textContainsstring否文字包含
textRegexstring否文字匹配的正则

FlowCheckInput

字段类型必填说明
flowobject否要校验的流程宏,与 steps 二选一
stepsobject[]否要校验的步骤列表
varsobject否已知的变量取值

FlowCheckView

字段类型必填说明
secretsstring[]否用到的密码占位名,值由调用方在本机取得
stepsinteger否步数
varsstring[]否运行时要传入的变量

FlowRunInput

字段类型必填说明
atstring否暂停时返回的步骤位置
confirmationstring否已批准的确认单编号,与暂停时返回的 pause 一起续跑
flowobject否流程宏 yunyoo.flow/2 的内容
frominteger否续跑时从第几个顶层步骤开始,从 1 起
secretsobject否密码占位的取值,只在内存中保存到运行结束
subinteger否暂停时返回的受控动作序号
varsobject否变量取值

FlowStarted

字段类型必填说明
runIdstring否运行编号
stepsinteger否步数
taskIdinteger否任务编号,用查询任务跟踪

FlowView

字段类型必填说明
codeinteger否没有通过时的错误码
confirmationConfirmationView否等待批准的确认单
deviationDeviation否偏离报告:步骤位置、期望的元素、当前界面摘要与相近元素
failedStepResult否第一个失败的步骤
inspectstring否结束时的紧凑快照
messagestring否没有通过的原因
pausePause否需要确认时暂停的位置,续跑时带上
resumeinteger否续跑时从第几步开始,从 1 起;0 表示从头
runIdstring否运行编号
statusstring否passed、failed、deviated、paused、cancelled 或 limited
stepsStepResult[]否逐步结果

HandoffReq

字段类型必填说明
reasonstring否交接原因,显示给接手的用户;为空时只查询当前控制状态

Hit

字段类型必填说明
linestring否元素的紧凑行
refstring否元素编号
selectorsautomation.Selector[]否在当前界面唯一的选择器建议

Identity

字段类型必填说明
classstring否
descstring否
idstring否
textstring否

ImportEnvSpec

字段类型必填说明
attestationSourceAttestSource否证明来源,缺省为平台
bindAckboolean否确认改为绑定后,绑定应用之外的第三方应用会被停用
bindAppIdinteger否绑定的应用,缺省沿用包的来源
dataGibinteger否磁盘档位(GiB)
deviceIdinteger否本地节点上的槽位
deviceSourcestring否设备来源:owned(已购设备)或 temporary(临时设备)
egressConfirmstring否预检返回的出口确认令牌,代理与包内锚点需要确认时使用
groupIdinteger否分组
proxyIdinteger否代理
remarkstring否备注
skuIdinteger否规格编号
tagIdsinteger[]否标签
titlestring否名称

ImportPlan

字段类型必填说明
anchorobject否包内的出口锚点
attestationstring否证明来源
bindAckboolean否目标环境已绑定应用而包的来源未绑定,正式导入时须带 bindAck
boundPackagestring否以包新建环境时沿用的绑定应用包名;来源未绑定时为空
confirmTokenstring否出口需要确认时的确认令牌,正式导入时作为 egressConfirm 传入
deviceProfilestring否包对应的机型
formatinteger否包格式版本
hasSeedboolean否包内是否带设备身份种子
identitystring否身份处理结果
identityPublicobject否包内设备身份的公开派生值,已脱敏
kindstring否包的类型
modestring否导入方式
proxyGradestring否代理与锚点的一致程度
rootVariantstring否包对应的变体
runtimeStateboolean否是否会恢复运行态
secureStateboolean否是否会恢复安全状态
skuNamestring否新建环境的规格名称
titlestring否新建环境的名称
verifyboolean否正式导入时须带账号密码复核

ImportTarget

字段类型必填说明
envImportEnvSpec否mode 为 env 时新环境的参数
envIdinteger否目标环境;mode 为 env 时不填
modestring是导入方式:restore、data-env、app、profile 或 env(新建环境)

Node

字段类型必填说明
boundsautomation.Bounds否元素在屏幕上的范围(像素)
checkableboolean否
checkedboolean否
childrenNode[]否子元素
classNamestring否类名
clickableboolean否
contentDescstring否描述
editableboolean否
elementIdstring否稳定元素标识
enabledboolean否
focusableboolean否
focusedboolean否
longClickableboolean否
packagestring否所属应用包名
passwordboolean否是否为密码框,密码框不返回文字
refstring否元素编号
resourceIdstring否资源 ID
scrollableboolean否
selectedboolean否
textstring否文字

NodeDoctor

字段类型必填说明
failedstring[]否没有通过的检查项
okboolean否体检是否通过

NodeSlots

字段类型必填说明
totalinteger否槽位总数
usedinteger否已用槽位

NodeSummary

字段类型必填说明
doctorNodeDoctor否本地节点的体检结果
execModestring否本地节点的运行方式
lastSeenAtstring否最近一次在线的时间
namestring否名称
nodeTypestring否节点类型
onlineboolean否是否在线
platformstring否本地节点的系统平台
providerIdinteger否节点 ID
scopestring否cloud(云端节点)或 local(本地节点)
slotsNodeSlots否槽位用量

NormPoint

字段类型必填说明
xnumber否横坐标,占屏幕宽度的比例,0–1
ynumber否纵坐标,占屏幕高度的比例,0–1

PackageCreateReq

字段类型必填说明
escrowboolean否旧格式口令包托管成员密钥,以便找回口令;只对付费用户开放
identityTransferboolean否同意把包内的设备身份转移给导入方
includeSecureStateboolean否是否携带安全状态,整机包缺省携带
includeSeedboolean否是否携带设备身份种子
kdfPackageKDF否派生 wrapKeyB64 所用的参数
passwordstring否账号密码,携带设备身份时用于复核
wrapKeyB64string否旧格式口令包的包装密钥(base64),由口令在本机派生;平台开启密封导出时不需要

PackageCreateResult

字段类型必填说明
fileNamestring否包文件名
packageIdstring否包编号
taskIdinteger否封装任务编号

PackageDetail

字段类型必填说明
IDinteger否主键ID
actorUserIdinteger否
androidVersionstring否
appPackagestring否
backupIdinteger否
createdAtstring否创建时间
deviceProfilestring否
downloadCountinteger否
envIdinteger否
envSegmentboolean否
errorCodestring否
errorMsgstring否
escrowboolean否
expiresAtstring否
fileNamestring否
formatinteger否
hasRuntimeStateboolean否
hasSecureStateboolean否
hasSeedboolean否
identityTransferboolean否
kdfPackageKDF否
keyIdstring否
kindstring否
originShareIdinteger否
packageIdstring否
rewrapCountinteger否
rootVariantstring否
sharesBackupShare[]否
sizeBytesinteger否
sourcestring否
statusstring否
taskIdinteger否
updatedAtstring否更新时间

PackageImportReq

字段类型必填说明
bindAckboolean否目标环境已绑定应用而包的来源未绑定时确认导入,绑定应用之外的第三方应用会被停用
dataEnvNamestring否导入为数据环境时的名称
dryRunboolean否为 true 时只返回导入计划,不创建任务
fileNamestring否上传的文件名
identityModestring否导入为档案时的身份处理:template(只取设置,身份不变)或 transfer(改持包内身份)
identityTransferboolean否机器凭据改持包内身份时必须为 true
ignoreVersionboolean否版本不一致时照常导入
packageIdstring否已有的包编号,与 uploadSessionId 二选一
passwordstring否账号密码,用于敏感操作复核
restoreIdentityboolean否是否改持包内的设备身份,缺省为 true
targetImportTarget是导入目标
uploadSessionIdstring否上传会话编号
wrapKeyB64string否旧格式口令包的包装密钥,按检视结果里的 kdf 在本机派生;平台密封的包不需要

PackageImportResult

字段类型必填说明
packageIdstring否包编号
planImportPlan否dryRun 时的导入计划
taskIdinteger否导入任务编号;dryRun 时为空

PackageInspectReq

字段类型必填说明
fileNamestring否包文件名
uploadSessionIdstring是上传会话编号

PackageKDF

字段类型必填说明
iterationsinteger否迭代次数
saltB64string否盐(base64)

PackageUploadReq

字段类型必填说明
fileNamestring是包文件名,扩展名为 .wp
sizeinteger是包字节数

packageUploadSession

字段类型必填说明
headersobject否上传时要带的请求头
modestring否上传方式
partSizeinteger否分片大小(字节)
partsUploadPartURL[]否分片上传地址
uploadSessionIdstring否上传会话编号
urlstring否整体上传的地址

Pause

字段类型必填说明
confirmationstring否等待批准的确认单编号
pathstring否暂停的步骤位置
stepinteger否暂停的顶层步骤号
subinteger否这一步里第几个受控动作,从 0 起

Point

字段类型必填说明
xnumber否
ynumber否

provider.Bounds

字段类型必填说明
bottomnumber否
leftnumber否
rightnumber否
topnumber否

RefCandidate

字段类型必填说明
boundsprovider.Bounds否
classNamestring否
contentDescstring否
refstring否
resourceIdstring否
textstring否

RestoreSetReq

字段类型必填说明
backupIdinteger否要还原的整机备份,为空时取消待还原
bindAckboolean否目标环境已绑定应用而备份来源未绑定时确认还原,绑定应用之外的第三方应用会被停用
passwordstring否账号密码,用于敏感操作复核

RunCommandInput

字段类型必填说明
argvstring[]是命令与参数
cwdstring否工作目录
envobject否附加的环境变量
modestring否sync(缺省,等待结果)或 async(立即返回任务)
shellboolean否为 true 时经 shell 解释
timeoutMsinteger否超时上限,毫秒

RunCommandResult

字段类型必填说明
channelstring否执行通道
duration_msinteger否耗时,毫秒
exit_codeinteger否退出码
invoke_idstring否调用编号
output_bytesinteger否输出字节数
statusstring否succeeded、failed 或 timed_out
stderrstring否标准错误输出
stderr_truncatedboolean否标准错误输出是否被截断
stdoutstring否标准输出
stdout_truncatedboolean否标准输出是否被截断

RunCommandView

字段类型必填说明
channelstring否执行通道
durationMsinteger否耗时,毫秒
exitCodeinteger否退出码
invokeIdstring否调用编号
outputBytesinteger否输出字节数
outputUrlstring否输出过大时转存的下载地址
statusstring否succeeded、failed、timed_out 或 accepted(async 已受理)
stderrstring否标准错误输出
stderrTruncatedboolean否标准错误输出是否被截断
stdoutstring否标准输出
stdoutTruncatedboolean否标准输出是否被截断
taskIdinteger否mode 为 async 时的任务编号,用查询任务跟踪

RunView

字段类型必填说明
clientNamestring否客户端
endedAtstring否结束时间
entrystring否入口
envIdinteger否环境 ID
failedStepsinteger否失败的步数
idstring否运行编号
itemsStepView[]否各步记录
skillNamestring否Skill
startedAtstring否开始时间
statusstring否运行结果
stepsinteger否步数
tokenKindstring否凭据种类
tokenNamestring否凭据名称

ScreenshotView

字段类型必填说明
annotatedboolean否是否标出了元素编号
formatstring否jpeg 或 png
heightinteger否图像高度
image_base64string否图像内容(base64)
notesstring[]否处理说明
scalenumber否图像相对原始分辨率的缩放比例
snapshotinteger否标注所用的快照版本
source_heightinteger否屏幕原始高度
source_widthinteger否屏幕原始宽度
widthinteger否图像宽度

SelectorSpec

字段类型必填说明
envIdsinteger[]否选中这些环境
groupIdinteger否选中这个分组里的设备
tagIdinteger否选中带这个标签的设备

ShareCreateReq

字段类型必填说明
expiresInHoursinteger否有效小时数
identityTransferboolean否同意包内的设备身份随分享转移;带设备身份的包必须为 true
maxDownloadsinteger否最多下载次数
requireLoginboolean否已不再生效,领取一律要求登录

ShareCreateResult

字段类型必填说明
expiresAtstring否过期时间
shareIdinteger否分享编号
shareUrlstring否分享链接,领取要求登录
tokenstring否分享令牌,只在这次返回

StatusView

字段类型必填说明
capabilitiesstring[]否能力位,如 textInput、refIdentity
controlstring否控制状态:free、automating、human 或 waiting-human
degradedboolean否是否为降级档
interactableboolean否当前是否可交互
protocolstring否自动化协议版本

StepResult

字段类型必填说明
codeinteger否错误码
commandstring否步骤命令
durationMsinteger否耗时,毫秒
effectstring否生效判定
labelstring否步骤标签
messagestring否失败原因
okboolean否是否成功
pathstring否步骤位置,如 steps[3]
skippedboolean否是否跳过
stepinteger否顶层步骤号,从 1 起

StepView

字段类型必填说明
atstring否时间
codeinteger否结果码
confirmationstring否关联的确认单
durationMsinteger否耗时,毫秒
effectstring否生效判定
entrystring否入口
identitystring否目标元素的标识
intentstring否调用方声明的意图
paramsstring否参数摘要
seqinteger否步序号
targetstring否目标元素
thumbstring否动作后的截图
toolstring否工具
tracestring否追踪编号

TaskView

字段类型必填说明
IDinteger否主键ID
backupIdinteger否
createdAtstring否创建时间
detailstring否
envIdinteger否
errorCodestring否
expiresAtstring否
messagestring否
parentIdinteger否
percentinteger否
providerIdinteger否
resultobject否任务结果;流程宏为执行报告
sessionIdinteger否
stagestring否
statusstring否
typestring否
updatedAtstring否更新时间

UIActionInput

字段类型必填说明
actionstring否动作名;单台设备的动作接口由路径决定,可以不填;多设备批量时必填:tap、swipe、type 或 key
activitystring否until 为 package 时一并要求的页面
clearboolean否为 true 时先清空输入框
codeinteger否Android 按键码
durationMsinteger否滑动时长,毫秒
editorActioninteger否输入法动作编号
fromNormPoint否滑动起点,归一化坐标
idleMsinteger否until 为 idle 时,界面要保持不变的毫秒数
longPressMsinteger否大于 0 时长按这么多毫秒
packagestring否until 为 package 时要等到前台的应用包名
pointNormPoint否归一化坐标,没有可用的元素时代替 selector
selectorobject否元素选择器:{"by":"element","id":"e12","snapshot":7}(元素编号,带上快照版本)、{"by":"resourceId","value":"…"}、{"by":"text","value":"…"}、{"by":"contentDesc","value":"…"} 或 {"by":"point","point":{"x":0.5,"y":0.5}}
submitboolean否为 true 时输入后发送回车
textstring否要输入的文本
timeoutMsinteger否等待上限,毫秒
toNormPoint否滑动终点,归一化坐标
untilstring否等待条件:gone、idle、animation 或 package;为空时等 selector 指定的元素出现
verifyboolean否为 true 时等界面稳定后判定动作是否生效

UIActionResult

字段类型必填说明
activitystring否动作后的前台页面
candidatesRefCandidate[]否目标不唯一时的候选元素
effectstring否生效判定:changed 为界面有变化,unchanged 为没有变化,unverified 为没有判定
error_codeinteger否未完成时的错误码
matchedboolean否等待时是否等到了目标
messagestring否未完成的原因
okboolean否动作是否完成
packagestring否动作后的前台应用包名
snapshotobject否部分环境在动作后附带的界面结构
snapshot_versioninteger否动作后的快照版本
targetRefCandidate否实际操作的元素
timed_outboolean否是否等待超时

UIBatchInput

字段类型必填说明
atstring否暂停时返回的步骤位置
confirmationstring否已批准的确认单编号,与暂停时返回的 pause 一起续跑
frominteger否续跑时从第几个顶层步骤开始,从 1 起
inspectAtEndboolean否为 true 时在结果里附上结束时的紧凑快照
keepGoingboolean否为 true 时某步失败后继续执行
secretsobject否密码占位的取值,只在内存中保存到运行结束
stepsobject[]否步骤列表,结构与流程宏 yunyoo.flow/2 的 steps 相同
subinteger否暂停时返回的受控动作序号
varsobject否变量取值

UIFindInput

字段类型必填说明
allboolean否为 true 时也在屏幕外与不可见的元素中查找
classstring否类名,可只写最后一段
descstring否描述包含这段内容,不区分大小写
idstring否资源 ID,可省略包名前缀
maxinteger否最多返回的命中数
regexstring否文字或描述匹配这个正则
textstring否文字包含这段内容,不区分大小写

UIFindView

字段类型必填说明
devicestring否设备,写作 env:<环境 ID>
hitsHit[]否命中的元素,最多 max 个
snapshotinteger否快照版本
textstring否命中元素的紧凑行,一行一个
totalinteger否命中总数

UITreeView

字段类型必填说明
activitystring否前台页面
capabilitiesstring[]否能力位,如 textInput、refIdentity
degradedboolean否是否为降级档
devicestring否设备,写作 env:<环境 ID>
formatstring否compact 或 json
heightinteger否屏幕高度(像素)
packagestring否前台应用包名
protocolstring否自动化协议版本
rootNode否format 为 json 时的界面树
snapshotinteger否快照版本,按元素编号操作时带上
textstring否format 为 compact 时的紧凑快照
widthinteger否屏幕宽度(像素)

UploadPartURL

字段类型必填说明
partNumberinteger否
urlstring否

UploadSessionResp

字段类型必填说明
headersobject否上传时要带的请求头
tokenstring否推送文件时使用的 token
urlstring否上传地址,用 PUT 上传文件内容

WhoAmIResp

字段类型必填说明
appsstring[]否委派令牌允许操作的应用包名
dialogsstring[]否应用名单之外照常允许的系统对话框包名
envScopeEnvScopeSpec否凭据可以操作的设备范围
scopesstring[]否凭据的作用域
sealedPackageboolean否为 true 时新导出的包由平台密封,封装不需要口令
tokenIdinteger否凭据 ID
toolsstring[]否这个凭据可用的 MCP 工具,按工具清单的顺序
uidstring否用户编号
userIdinteger否用户 ID