云柚

文档中心

MCP 工具参考

最近更新:2026/11/13

yunyoo 的 MCP 工具有三种形态,用的是同一套工具,只有少数工具和参数因形态不同而有差别:远程形态的接入地址是 https://mcp.yunyoo.ai;本机云端形态由 yunyoo mcp 启动,经平台操作云端与本地节点上的环境;本机本地形态由 yunyoo mcp --local 启动,经桌面端操作这台电脑上的本地节点。各客户端的接入方法见 MCP。

下面按工具清单的顺序列出全部工具。说明与参数在各形态不同时分开写出;凭据的作用域不包含某个工具时,工具清单里不会出现它。

工具

device_list

列出设备

远程、本机云端:列出可以操作的设备:环境 ID、名称与状态;开始操作前先调用,把结果里的环境 ID 写作 env:<环境 ID> 作为后续调用的 device。

本机本地:列出本机可达的环境:设备引用 ref、名称、是否在线、所在节点与同步状态;开始操作前先调用,把 ref 作为后续调用的 device。

形态:远程、本机云端、本机本地;只读;幂等。

没有参数。

返回的字段如下。

字段说明
devices可操作的设备:云端形态每项有 id、title、status;本机形态每项有 ref、kind、name、online,另带 node 与 sync

device_use

选定设备

远程:核对设备可用并返回其摘要;远程没有会话,之后每次调用仍要带 device。

本机云端:选定本进程的当前设备,之后不带 device 的调用都作用于它;只操作一台设备时先调用一次,device 写作 env:<环境 ID>。

本机本地:选定本进程的当前设备(env:<环境 ID>),之后不带 device 的调用都作用于它;只操作一台设备时先调用一次。

形态:远程、本机云端、本机本地;只读;幂等。

参数类型必填说明
devicestring是远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:设备:env:<环境 ID> 或环境 ID(device_list 可列出)

status

自动化状态

远程、本机云端:查询设备的自动化状态:是否可交互、能力位与控制状态;动作前或动作失败时调用,按能力位判断可用的动作(没有 textInput 时只能输入 ASCII)

本机本地:查询桌面端本地 API 的版本、能力与联网状态;连不上设备或动作失败时先调用。

形态:远程、本机云端、本机本地;只读;幂等。

参数类型必填说明
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env

返回:云端形态为设备的自动化状态;本机形态为桌面端本地 API 的版本、能力与联网状态。

字段说明
capabilities能力位,如 textInput、refIdentity
control控制状态:free、automating、human 或 waiting-human
degraded是否为降级档
device设备,写作 env:<环境 ID>
flavor本机形态:桌面端风味
interactable当前是否可交互
online本机形态:桌面端是否联网
protocol自动化协议版本
version本机形态:桌面端版本

ui_inspect

读取界面元素

远程、本机云端:读取设备当前界面;缺省返回紧凑快照:首行是快照版本、屏幕与前台应用,其后一行一个元素(编号、类名、文字、描述、资源 ID、中心坐标与状态);动作前先调用,按其中的编号或文字定位;format=json 返回结构化树,scope=all 列出全部元素,under 只看某个元素下的子树。

本机本地:读取设备(本机可达的环境)当前界面;缺省返回紧凑快照,一行一个元素;动作前先调用,按其中的编号或文字定位;format=json 返回结构化树;桌面端版本较旧时只返回结构化树。

形态:远程、本机云端、本机本地;只读;幂等。

参数类型必填说明
allboolean否同时取屏幕外与不可见的元素
depthinteger否从起点往下列出的层数,1–100
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
formatstring否compact(缺省)或 json
maxinteger否最多列出的元素数,1–2000,缺省 150
scopestring否interactive(缺省,只列可交互或带文字的元素)或 all(列出全部元素)
understring否只列该编号元素下的子树

ui_find

查找界面元素

远程、本机云端:在当前界面按文字、正则、资源 ID、描述或类名查找元素,条件之间取「且」;界面元素多、只关心其中几个时用它代替 ui_inspect;返回命中元素的紧凑行与在当前界面唯一的选择器建议(可写进流程宏),没有命中时返回空结果。

本机本地:在设备(本机可达的环境)当前界面按文字、正则、资源 ID、描述或类名查找元素;界面元素多、只关心其中几个时用它代替 ui_inspect;返回命中元素的紧凑行与唯一的选择器建议;需要新版桌面端。

形态:远程、本机云端、本机本地;只读;幂等。

参数类型必填说明
allboolean否同时在屏幕外与不可见的元素中查找
classstring否类名,可省略包名
descstring否描述包含,不区分大小写
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
idstring否资源 ID,可省略包名
maxinteger否最多返回的命中数,1–100,缺省 20
regexstring否正则,匹配文字或描述
textstring否文字包含,不区分大小写

screenshot

截图。截取设备屏幕,返回压缩后的图像(缺省 JPEG、长边 1024)与原始分辨率、缩放比例;界面结构读不出内容(图片、视频、游戏画面)时使用;annotate 为真时在图上标出最近一次 ui_inspect 的元素编号,max_edge、format、quality 控制尺寸与画质。

形态:远程、本机云端、本机本地;只读。

参数类型必填说明
annotateboolean否在图上标出最近一次 ui_inspect 的元素编号
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
formatstring否图像格式:jpeg(缺省)或 png
max_edgeinteger否长边像素,256–2048,缺省 1024
qualityinteger否JPEG 质量 1–100,缺省 75

ui_tap

点按。点按设备上的元素;优先用元素编号(带上快照版本 snapshot)、资源 ID、文字或描述定位,没有可用元素时才用归一化坐标 x、y;long_press_ms 大于 0 时长按;结果的 effect 说明界面是否有变化;付款、转账、下单、修改账号与安全设置这类按钮不要点,用 handoff 交给用户本人,用户说不用问也一样;平台判定为高风险的点按可能先挂起并返回确认单。

形态:远程、本机云端、本机本地;有破坏性。

参数类型必填说明
confirmation_idstring否被挂起后用户已批准的确认单编号;带上它以原参数重新调用,动作执行一次
descstring否描述选择器
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
elementstring否元素编号(ui_inspect 返回的 elementId)
intentstring否这一步的意图说明,写进确认单与运行记录;只能增加风险类别,不能减少
long_press_msinteger否长按毫秒数;不给时为单击
resource_idstring否资源 ID 选择器
snapshotinteger否远程:元素所属快照版本(ui_inspect 返回的 snapshot;带 element 时必填);本机:元素所属快照版本(ui_inspect 返回的 snapshot;缺省取本进程对该设备最近一次 ui_inspect 的版本)
textstring否文本选择器
verifyboolean否判定动作是否生效,缺省开:结果的 effect 为 changed 或 unchanged;关掉时只派发,effect 为 unverified
xnumber否归一化坐标 x,没有可用元素时使用(0..1)
ynumber否归一化坐标 y,没有可用元素时使用(0..1)

返回:界面动作的结果。

字段说明
activity动作后的前台页面
candidates目标不唯一时的候选元素
device设备,写作 env:<环境 ID>
effect生效判定:changed 为界面有变化,unchanged 为没有变化,unverified 为没有判定
error_code未完成时的错误码
matched等待时是否等到了目标
message未完成的原因
ok动作是否完成
package动作后的前台应用包名
snapshot_version动作后的快照版本
target实际操作的元素:编号、类名、资源 ID、文字、描述与边界
timed_out是否等待超时

ui_swipe

滑动。在设备上从一点滑到另一点(归一化坐标 0..1),用于翻页、滚动列表或下拉刷新;from_x、from_y 是起点,to_x、to_y 是终点,duration_ms 是滑动时长。

形态:远程、本机云端、本机本地;有破坏性。

参数类型必填说明
confirmation_idstring否被挂起后用户已批准的确认单编号;带上它以原参数重新调用,动作执行一次
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
duration_msinteger否远程:滑动时长毫秒(默认 300);本机:滑动时长毫秒(缺省 300)
from_xnumber是
from_ynumber是
intentstring否这一步的意图说明,写进确认单与运行记录;只能增加风险类别,不能减少
to_xnumber是
to_ynumber是
verifyboolean否判定动作是否生效,缺省开:结果的 effect 为 changed 或 unchanged;关掉时只派发,effect 为 unverified

返回:界面动作的结果。

字段说明
activity动作后的前台页面
candidates目标不唯一时的候选元素
device设备,写作 env:<环境 ID>
effect生效判定:changed 为界面有变化,unchanged 为没有变化,unverified 为没有判定
error_code未完成时的错误码
matched等待时是否等到了目标
message未完成的原因
ok动作是否完成
package动作后的前台应用包名
snapshot_version动作后的快照版本
target实际操作的元素:编号、类名、资源 ID、文字、描述与边界
timed_out是否等待超时

ui_type

输入文本。向焦点输入框(或 element 指定的元素)输入文本;clear 为真时先清空,submit 为真时输入后发送回车;能力位不含 textInput 时只能输入 ASCII;密码、验证码与支付信息不要代为输入,用 handoff 交给用户本人。

形态:远程、本机云端、本机本地;有破坏性。

参数类型必填说明
clearboolean否输入前清空
confirmation_idstring否被挂起后用户已批准的确认单编号;带上它以原参数重新调用,动作执行一次
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
elementstring否目标元素编号(缺省当前焦点)
intentstring否这一步的意图说明,写进确认单与运行记录;只能增加风险类别,不能减少
snapshotinteger否远程:元素所属快照版本(ui_inspect 返回的 snapshot;带 element 时必填);本机:元素所属快照版本(缺省取本进程对该设备最近一次 ui_inspect 的版本)
submitboolean否输入后发送回车(提交搜索或表单)
textstring是远程:要输入的文本;本机:要输入的文本;设备的 capabilities 不含 textInput 时只支持 ASCII
verifyboolean否判定动作是否生效,缺省开:结果的 effect 为 changed 或 unchanged;关掉时只派发,effect 为 unverified

返回:界面动作的结果。

字段说明
activity动作后的前台页面
candidates目标不唯一时的候选元素
device设备,写作 env:<环境 ID>
effect生效判定:changed 为界面有变化,unchanged 为没有变化,unverified 为没有判定
error_code未完成时的错误码
matched等待时是否等到了目标
message未完成的原因
ok动作是否完成
package动作后的前台应用包名
snapshot_version动作后的快照版本
target实际操作的元素:编号、类名、资源 ID、文字、描述与边界
timed_out是否等待超时

ui_key

按键。向设备发送按键,code 为 Android 按键码(66 回车、4 返回、3 回到桌面、67 删除)

形态:远程、本机云端、本机本地;有破坏性。

参数类型必填说明
codeinteger是Android 按键码
confirmation_idstring否被挂起后用户已批准的确认单编号;带上它以原参数重新调用,动作执行一次
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
intentstring否这一步的意图说明,写进确认单与运行记录;只能增加风险类别,不能减少
verifyboolean否判定动作是否生效,缺省开:结果的 effect 为 changed 或 unchanged;关掉时只派发,effect 为 unverified

返回:界面动作的结果。

字段说明
activity动作后的前台页面
candidates目标不唯一时的候选元素
device设备,写作 env:<环境 ID>
effect生效判定:changed 为界面有变化,unchanged 为没有变化,unverified 为没有判定
error_code未完成时的错误码
matched等待时是否等到了目标
message未完成的原因
ok动作是否完成
package动作后的前台应用包名
snapshot_version动作后的快照版本
target实际操作的元素:编号、类名、资源 ID、文字、描述与边界
timed_out是否等待超时

ui_wait

等待元素。等待一个条件成立,用于确认上一步的结果:元素出现(选择器同 ui_tap)、gone 元素消失、idle_ms 界面保持不变、animation 动画结束、package 应用到前台;一次只等一种条件,timeout_ms 为等待上限(一次最长 30 秒,需要更久就再调用一次),超时返回 1003。

形态:远程、本机云端、本机本地;只读;幂等。

参数类型必填说明
activitystring否与 package 同用:等待该页面到前台
animationboolean否等待动画结束
descstring否描述选择器
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
elementstring否元素编号(ui_inspect 返回的 elementId)
goneobject否等待该元素消失:写法同出现条件的选择器,如 {"text":"加载中"}
idle_msinteger否等待界面保持不变的毫秒数(缺省 800)
packagestring否等待该应用到前台
resource_idstring否资源 ID 选择器
snapshotinteger否远程:元素所属快照版本(ui_inspect 返回的 snapshot;带 element 时必填);本机:元素所属快照版本(ui_inspect 返回的 snapshot;缺省取本进程对该设备最近一次 ui_inspect 的版本)
textstring否文本选择器
timeout_msinteger否等待上限毫秒(缺省 5000,最长 30000)
xnumber否归一化坐标 x,没有可用元素时使用(0..1)
ynumber否归一化坐标 y,没有可用元素时使用(0..1)

返回:界面动作的结果。

字段说明
activity动作后的前台页面
candidates目标不唯一时的候选元素
device设备,写作 env:<环境 ID>
effect生效判定:changed 为界面有变化,unchanged 为没有变化,unverified 为没有判定
error_code未完成时的错误码
matched等待时是否等到了目标
message未完成的原因
ok动作是否完成
package动作后的前台应用包名
snapshot_version动作后的快照版本
target实际操作的元素:编号、类名、资源 ID、文字、描述与边界
timed_out是否等待超时

ui_batch

批量动作

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

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

本机本地:一次提交多步界面与应用动作,由桌面端在设备(本机可达的环境)上逐步执行,用于已知的固定步骤;步骤结构与流程宏 yunyoo.flow/2 相同,最多 50 步、60 秒;缺省遇到首个失败即停,返回逐步结果与失败位置;需要确认时返回确认单与续跑位置;需要新版桌面端。

形态:远程、本机云端、本机本地;有破坏性。

参数类型必填说明
atstring否暂停那一步的位置,取自上次结果的 pause.path
confirmation_idstring否被挂起后用户已批准的确认单编号;带上它以原参数重新调用,动作执行一次
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
frominteger否从第几步开始(从 1 起),确认或偏离后续跑时用
inspect_at_endboolean否结束时附上紧凑快照
intentstring否这一步的意图说明,写进确认单与运行记录;只能增加风险类别,不能减少
keep_goingboolean否某步失败或偏离后继续执行后面的步骤
stepsobject[]是远程:步骤列表,如 [{"tapOn":"搜索"},{"inputText":"${QUERY}"}];本机:步骤列表,结构与流程宏 yunyoo.flow/2 的步骤相同,如 [{"tapOn":"登录"},{"back":{}}];最多 50 步、60 秒
subinteger否暂停那一步里第几个受控动作,取自上次结果的 pause.sub
varsobject否远程:变量取值,键为变量名;本机:变量取值,键为变量名;未给出的再取环境变量 YUNYOO_VAR_<NAME>

返回:批量动作的执行报告。

字段说明
code没有通过时的错误码
confirmation等待批准的确认单
deviation偏离报告:步骤位置、期望的元素、当前界面摘要与相近元素
device设备,写作 env:<环境 ID>
failed第一个失败的步骤
inspect结束时的紧凑快照
message没有通过的原因
pause需要确认时暂停的位置(path 与 sub),续跑时带上
resume续跑时从第几步开始
runId运行编号
statuspassed、failed、deviated、paused、cancelled 或 limited
steps逐步结果

app_list

列出应用

远程、本机云端:列出设备已安装的应用:包名与可读名称;启动、停止或卸载前用它确认包名;平台清单不可用时改为设备侧列举,名称为空并在 note 里注明。

本机本地:列出设备已安装的应用(设备侧列举,只有包名);启动、停止或卸载前用它确认包名。

形态:远程、本机云端、本机本地;只读;幂等。

参数类型必填说明
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env

返回的字段如下。

字段说明
apps已安装的应用:包名与可读名称
device设备,写作 env:<环境 ID>
note
output改为设备侧列举时的原始输出,每行 package:包名
source清单来源

app_launch

启动应用。启动应用到前台,package 为包名(见 app_list);名单内的敏感应用可能要先经用户确认。

形态:远程、本机云端、本机本地;幂等。

参数类型必填说明
confirmation_idstring否被挂起后用户已批准的确认单编号;带上它以原参数重新调用,动作执行一次
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
intentstring否这一步的意图说明,写进确认单与运行记录;只能增加风险类别,不能减少
packagestring是应用包名

返回:应用操作的结果。

字段说明
channel执行通道
device设备,写作 env:<环境 ID>
durationMs
exitCode退出码
invokeId
outputBytes
statussucceeded、failed 或 timed_out
stderr设备错误输出
stderrTruncated
stdout设备输出
stdoutTruncated
taskId

app_stop

停止应用。强制停止应用,package 为包名;应用卡住或要从头开始时使用。

形态:远程、本机云端、本机本地;幂等。

参数类型必填说明
confirmation_idstring否被挂起后用户已批准的确认单编号;带上它以原参数重新调用,动作执行一次
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
intentstring否这一步的意图说明,写进确认单与运行记录;只能增加风险类别,不能减少
packagestring是应用包名

返回:应用操作的结果。

字段说明
channel执行通道
device设备,写作 env:<环境 ID>
durationMs
exitCode退出码
invokeId
outputBytes
statussucceeded、failed 或 timed_out
stderr设备错误输出
stderrTruncated
stdout设备输出
stdoutTruncated
taskId

app_install

安装应用

远程、本机云端:从应用库安装应用,app_ids 为应用库里的应用编号;返回安装任务,用 job_get 跟踪。

本机本地:在设备上安装应用:path 为本机安装包路径(只适用于本地节点上的环境),或 app_ids 为应用库里的应用编号(经桌面端转发平台,等待安装结果)

形态:远程、本机云端、本机本地;幂等。

参数类型必填说明
app_idsinteger[]远程必填应用库里的应用编号
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
pathstring否本机的安装包路径,只在本机形态可用;只在本机形态

返回:应用安装的结果。

字段说明
device设备,写作 env:<环境 ID>
hint
items本机形态:各应用的安装结果
ok本机形态:桌面端是否已完成
status任务状态
task平台任务编号,用 job_get 查询进度与结果
taskId本机形态:桌面端转发平台时的任务编号

app_uninstall

卸载应用。卸载应用,keep_data 为真时保留数据;属于高风险操作,需要用户确认时返回确认单。

形态:远程、本机云端、本机本地;有破坏性;幂等。

参数类型必填说明
confirmation_idstring否被挂起后用户已批准的确认单编号;带上它以原参数重新调用,动作执行一次
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
intentstring否这一步的意图说明,写进确认单与运行记录;只能增加风险类别,不能减少
keep_databoolean否保留应用数据
packagestring是应用包名

返回:应用操作的结果。

字段说明
channel执行通道
device设备,写作 env:<环境 ID>
durationMs
exitCode退出码
invokeId
outputBytes
statussucceeded、failed 或 timed_out
stderr设备错误输出
stderrTruncated
stdout设备输出
stdoutTruncated
taskId

app_clear

清除应用数据。清除应用的全部数据,应用回到刚安装的状态;属于高风险操作,需要用户确认时返回确认单。

形态:远程、本机云端、本机本地;有破坏性;幂等。

参数类型必填说明
confirmation_idstring否被挂起后用户已批准的确认单编号;带上它以原参数重新调用,动作执行一次
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
intentstring否这一步的意图说明,写进确认单与运行记录;只能增加风险类别,不能减少
packagestring是应用包名

返回:应用操作的结果。

字段说明
channel执行通道
device设备,写作 env:<环境 ID>
durationMs
exitCode退出码
invokeId
outputBytes
statussucceeded、failed 或 timed_out
stderr设备错误输出
stderrTruncated
stdout设备输出
stdoutTruncated
taskId

file_push

推送文件

远程:把一个文件推到设备的下载目录:name 为文件名,content_base64 为文件内容的 base64(最大 2 MB);返回推送任务,用 job_get 跟踪。

本机云端:把本机的一个文件推到设备的下载目录:local_path 为本机路径,name 为设备上的文件名(缺省沿用本机文件名);返回推送任务。

本机本地:把本机的一个文件推到设备的下载目录(/sdcard/Download),local_path 为本机路径,name 只能是文件名。

形态:远程、本机云端、本机本地;有破坏性;幂等。

参数类型必填说明
content_base64string是文件内容的 base64;只在远程形态
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
namestring远程必填远程:文件名;本机:设备上的文件名(放在下载目录),缺省沿用本机文件名
local_pathstring是本机文件路径;只在本机形态

返回:文件推送的结果。

字段说明
device设备,写作 env:<环境 ID>
hint
ok本机形态:桌面端是否已完成
status任务状态
task平台任务编号,用 job_get 查询进度与结果
taskId本机形态:桌面端转发平台时的任务编号

file_pull

取回文件

远程:从设备取回一个文件,path 为设备上的路径;返回任务,完成后 job_get 给出 15 分钟内有效的下载链接。

本机云端:从设备取回一个文件,path 为设备上的路径;返回任务,用 job_get 查看进度,完成后在网页端或桌面端下载。

本机本地:从设备取回一个文件,path 为设备上的路径,写到本机的 local_path。

形态:远程、本机云端、本机本地;只读。

参数类型必填说明
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
pathstring是设备上的文件路径
local_pathstring否本机保存路径;本机形态必填,云端形态取回后用 job_get 拿下载链接;只在本机形态

返回:文件取回的结果。

字段说明
device设备,写作 env:<环境 ID>
hint
ok本机形态:桌面端是否已完成
status任务状态
task平台任务编号,用 job_get 查询进度与结果
taskId本机形态:桌面端转发平台时的任务编号

env_start

开机

远程、本机云端:开机;返回任务编号时用 job_get 跟踪进度;开机要几分钟,status 显示可交互后再操作。

本机本地:开机(经桌面端转发平台);开机要几分钟,用 device_list 确认在线后再操作。

形态:远程、本机云端、本机本地;幂等。

参数类型必填说明
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env

返回:环境生命周期操作的结果。

字段说明
device设备,写作 env:<环境 ID>
opstart、stop、reboot、pause、resume 或 sync
result平台或桌面端返回的原始结果
status任务状态
task平台任务编号,用 job_get 查询进度与结果

env_resume

继续运行

远程、本机云端:让暂停的环境继续运行;返回任务编号时用 job_get 跟踪进度。

本机本地:让暂停的环境继续运行(经桌面端转发平台)

形态:远程、本机云端、本机本地;幂等。

参数类型必填说明
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env

返回:环境生命周期操作的结果。

字段说明
device设备,写作 env:<环境 ID>
opstart、stop、reboot、pause、resume 或 sync
result平台或桌面端返回的原始结果
status任务状态
task平台任务编号,用 job_get 查询进度与结果

env_stop

关机

远程、本机云端:关机;返回时环境可能还没停完,先用 device_list 确认已停止,再做依赖关机的操作(如还原备份);返回任务编号时用 job_get 跟踪进度。

本机本地:关机(经桌面端转发平台);返回时环境可能还没停完,先用 device_list 确认已停止,再做依赖关机的操作。

形态:远程、本机云端、本机本地;有破坏性;幂等。

参数类型必填说明
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env

返回:环境生命周期操作的结果。

字段说明
device设备,写作 env:<环境 ID>
opstart、stop、reboot、pause、resume 或 sync
result平台或桌面端返回的原始结果
status任务状态
task平台任务编号,用 job_get 查询进度与结果

env_pause

暂停

远程、本机云端:暂停运行并保留内存状态,只适用于本地节点上的环境;用 env_resume 继续。

本机本地:暂停运行并保留内存状态,只适用于本地节点上的环境(经桌面端转发平台);用 env_resume 继续。

形态:远程、本机云端、本机本地;有破坏性;幂等。

参数类型必填说明
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env

返回:环境生命周期操作的结果。

字段说明
device设备,写作 env:<环境 ID>
opstart、stop、reboot、pause、resume 或 sync
result平台或桌面端返回的原始结果
status任务状态
task平台任务编号,用 job_get 查询进度与结果

env_reboot

重启

远程、本机云端:重启环境;界面卡死或设置要重启后生效时使用。

本机本地:重启环境(经桌面端转发平台);界面卡死或设置要重启后生效时使用。

形态:远程、本机云端、本机本地;有破坏性。

参数类型必填说明
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env

返回:环境生命周期操作的结果。

字段说明
device设备,写作 env:<环境 ID>
opstart、stop、reboot、pause、resume 或 sync
result平台或桌面端返回的原始结果
status任务状态
task平台任务编号,用 job_get 查询进度与结果

env_sync

同步到云端

远程、本机云端:把本地节点上环境的数据同步到云端;stop 为真时先关机再同步。

本机本地:把本地节点上环境的数据同步到云端(经桌面端转发平台);stop 为真时先关机再同步。

形态:远程、本机云端、本机本地;幂等。

参数类型必填说明
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
stopboolean否运行中或已暂停时先关机再同步

返回:环境生命周期操作的结果。

字段说明
device设备,写作 env:<环境 ID>
opstart、stop、reboot、pause、resume 或 sync
result平台或桌面端返回的原始结果
status任务状态
task平台任务编号,用 job_get 查询进度与结果

backup_list

列出备份

远程、本机云端:列出环境的备份:id、名称、类型与状态;还原前用它找备份 id。

本机本地:列出环境的备份(经桌面端转发平台):id、名称、类型与状态;还原前用它找备份 id。

形态:远程、本机云端、本机本地;只读;幂等。

参数类型必填说明
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env

返回的字段如下。

字段说明
backups
device设备,写作 env:<环境 ID>

backup_create

创建备份

远程、本机云端:为环境创建备份:给出 package 时只备份该应用的数据,否则为整机备份,name 为备份名称。

本机本地:为环境创建备份(经桌面端转发平台):给出 package 时只备份该应用的数据,否则为整机备份。

形态:远程、本机云端、本机本地。

参数类型必填说明
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
namestring否整机备份的名称
packagestring否应用包名:只做该应用的应用级备份

返回:备份记录。

字段说明
appPackage应用级备份的包名
createdAt创建时间
device设备,写作 env:<环境 ID>
envId
id备份 id
kindfull 为整机备份,app-sandbox 为应用级备份
name
purposesync 为同步副本,migrate 为迁移备份,空为用户备份
status

backup_restore

还原备份

远程、本机云端:用环境的一份备份还原,backup_id 来自 backup_list:整机备份在下次开机时还原,应用级备份立即还原该应用;属于高风险操作,需要用户确认时返回确认单。

本机本地:用环境的一份备份还原(经桌面端转发平台),backup_id 来自 backup_list:应用级备份立即还原该应用;属于高风险操作,需要用户确认时返回确认单。

形态:远程、本机云端、本机本地;有破坏性。

参数类型必填说明
backup_idinteger是备份 id
confirmation_idstring否被挂起后用户已批准的确认单编号;带上它以原参数重新调用,动作执行一次
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
ignore_versionboolean否应用级还原不检查版本
intentstring否这一步的意图说明,写进确认单与运行记录;只能增加风险类别,不能减少

返回:备份还原的结果。

字段说明
device设备,写作 env:<环境 ID>
hint
pending整机备份:下次开机时还原的备份
status
task平台任务编号,用 job_get 查询进度与结果
taskId应用级还原的任务编号

backup_share

分享备份包

远程、本机云端:为环境的备份包创建分享链接,领取一律要求登录;package_id 为包 id,expires_hours 为有效小时数(缺省 24),max_downloads 为最多下载次数(缺省 5);需要用户确认时返回确认单。

本机本地:为环境的备份包创建分享链接(经桌面端转发平台),领取一律要求登录;需要用户确认时返回确认单。

形态:远程、本机云端、本机本地。

参数类型必填说明
confirmation_idstring否被挂起后用户已批准的确认单编号;带上它以原参数重新调用,动作执行一次
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
expires_hoursinteger否有效小时数(缺省 24)
intentstring否这一步的意图说明,写进确认单与运行记录;只能增加风险类别,不能减少
max_downloadsinteger否最多下载次数(缺省 5)
package_idstring是包 id

返回:分享链接。

字段说明
device设备,写作 env:<环境 ID>
expiresAt过期时间
shareId
shareUrl分享链接,领取要求登录
token

job_get

查询任务

远程:查询平台异步任务(开关机、备份、文件推拉、应用安装、流程宏)的状态与结果,task 为任务编号;文件取回完成且有下载文件权限时附 15 分钟内有效的下载链接。

本机云端:查询平台异步任务(开关机、备份、文件推拉、应用安装、流程宏)的状态与结果,task 为任务编号。

本机本地:查询本机流程任务(macro_run 返回的 job_ 编号)的状态与结果;需要新版桌面端。

形态:远程、本机云端、本机本地;只读;幂等。

参数类型必填说明
taskstring是远程:任务编号;本机:任务编号:平台任务为数字,本机流程任务以 job_ 开头

返回:任务的状态与结果。

字段说明
ID平台任务编号
device设备,写作 env:<环境 ID>
expiresIn下载链接的有效秒数
job本机流程任务编号
message
percent
result任务结果;流程宏为执行报告
size
stage
status任务状态
type任务类型
url文件取回完成时的下载链接

macro_run

运行流程宏

远程:运行流程宏 yunyoo.flow/2,flow 为内联内容:先校验格式,再作为平台异步任务执行,返回任务编号,用 job_get 跟踪;偏离时任务以 53019 结束并带偏离报告;远程不支持密码占位。

本机云端:运行流程宏 yunyoo.flow/2,flow 为内联内容或 file 为本机文件:先校验格式,再作为异步任务执行,返回任务编号,用 job_get 跟踪;偏离时任务以 53019 结束并带偏离报告;密码占位在本机取值(YUNYOO_SECRET_<名称> 或钥匙串),值不会出现在结果里。

本机本地:运行流程宏 yunyoo.flow/2,flow 为内联内容或 file 为本机文件:先校验格式,再由桌面端作为本机流程任务执行,返回任务编号(job_ 开头),用 job_get 跟踪;密码占位在本机取值(YUNYOO_SECRET_<名称> 或钥匙串),值不会出现在结果里;需要新版桌面端。

形态:远程、本机云端、本机本地;有破坏性。

参数类型必填说明
atstring否暂停那一步的位置,取自上次结果的 pause.path
confirmation_idstring否被挂起后用户已批准的确认单编号;带上它以原参数重新调用,动作执行一次
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
flowobject远程必填远程:流程宏内容(schema 为 yunyoo.flow/2);本机:流程宏内容(schema 为 yunyoo.flow/2),与 file 二选一
frominteger否从第几步开始(从 1 起),确认或偏离后续跑时用
intentstring否这一步的意图说明,写进确认单与运行记录;只能增加风险类别,不能减少
subinteger否暂停那一步里第几个受控动作,取自上次结果的 pause.sub
varsobject否远程:变量取值,优先于流程里的 env 缺省值;本机:变量取值,优先于环境变量 YUNYOO_VAR_<NAME> 与流程里的 env 缺省值
filestring否本机上的流程宏文件(.json 或 .yaml),与 flow 二选一;只在本机形态

macro_save

生成宏草稿

远程、本机云端:从一次运行记录生成流程宏草稿,run 为运行编号(见 run_report);只取成功的动作,输入文字不能照录时改为变量 INPUT_n。

本机本地:从一次运行记录生成流程宏草稿,run 为运行编号(见 run_report);只取成功的动作,输入文字不能照录时改为变量 INPUT_n;需要新版桌面端。

形态:远程、本机云端、本机本地;只读;幂等。

参数类型必填说明
runstring是运行编号,见 run_report

run_report

运行报告

远程、本机云端:取一次运行的报告:各步的工具、参数摘要、目标元素、生效判定、结果码与耗时;不带 run 时取最近一次运行,带 device 时只看该设备。

本机本地:取一次运行的报告:各步的工具、参数摘要、目标元素、生效判定、结果码与耗时;不带 run 时取最近一次运行;需要新版桌面端。

形态:远程、本机云端、本机本地;只读;幂等。

参数类型必填说明
devicestring否目标设备:env:<环境 ID> 或环境 ID;不带 run 时只看该设备上最近一次运行
runstring否运行编号

confirm_wait

等待确认结果

远程、本机云端:等待一张确认单的决定(单次最长 60 秒),返回 pending、approved、denied、expired、cancelled 或 executed;工具返回 53010 后调用,批准后以原参数加 confirmation_id 重新调用被挂起的工具。

本机本地:等待一张确认单的决定(单次最长 60 秒),返回 pending、approved、denied、expired、cancelled 或 executed;工具返回 53010 后调用,批准后以原参数加 confirmation_id 重新调用;需要新版桌面端。

形态:远程、本机云端、本机本地;只读;幂等。

参数类型必填说明
confirmation_idstring是确认单编号
wait_msinteger否最长等待毫秒,0–60000,缺省 30000

返回:确认单的状态。

字段说明
action
categories风险类别
createdAt创建时间
decidedAt决定时间
envId
executedAt执行时间
expiresAt过期时间
id确认单编号
intent
statuspending、approved、denied、expired、cancelled 或 executed
summary动作摘要
url确认页地址

confirm_cancel

撤回确认

远程、本机云端:撤回一张还在等待的确认单;撤回后带它重新调用返回 53011。

本机本地:撤回一张还在等待的确认单;撤回后带它重新调用返回 53011;需要新版桌面端。

形态:远程、本机云端、本机本地;幂等。

参数类型必填说明
confirmation_idstring是确认单编号

handoff

人工交接

远程、本机云端:请用户接手这台设备:遇到付款、转账、下单,要输入密码、验证码或支付信息,要修改账号与安全设置,以及人机验证、登录这类要用户本人处理的界面时使用,用户说不用问也照此处理;reason 写明原因;交接期间动作类工具返回 53014,用户在查看器里交还后恢复;不带 reason 时只查询当前状态。

本机本地:请用户接手这台设备:遇到付款、转账、下单,要输入密码、验证码或支付信息,要修改账号与安全设置,以及人机验证、登录这类要用户本人处理的界面时使用,用户说不用问也照此处理;reason 写明原因;交接期间动作类工具返回 53014,用户交还后恢复;不带 reason 时只查询当前状态;需要新版桌面端。

形态:远程、本机云端、本机本地;幂等。

参数类型必填说明
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
reasonstring否需要用户处理的原因;不带时只查询当前状态

run_command

执行命令

远程:在设备上执行命令(逃生舱,需要执行命令作用域);只在界面与应用工具做不到时使用;argv 为命令与参数,shell 为真时经 shell 解释;本地通道桥接在远程形态不提供,需要时在命令行用 connect 子命令。

本机云端:在设备上执行命令(逃生舱,需要执行命令作用域);只在界面与应用工具做不到时使用;argv 为命令与参数,shell 为真时经 shell 解释,timeout_ms 为执行上限。

本机本地:在设备上执行命令(argv;本地节点上的环境由桌面端直接执行,云端节点上的环境转平台并受执行命令作用域约束);只在界面与应用工具做不到时使用。

形态:远程、本机云端、本机本地;有破坏性。

参数类型必填说明
argvstring[]是命令与参数(argv)
confirmation_idstring否被挂起后用户已批准的确认单编号;带上它以原参数重新调用,动作执行一次
devicestring远程必填远程:目标设备:env:<环境 ID> 或环境 ID(device_list 可列出);本机:目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
intentstring否这一步的意图说明,写进确认单与运行记录;只能增加风险类别,不能减少
shellboolean否经 shell 解释执行
timeout_msinteger否执行超时毫秒

connect

本地通道桥接。建立本地通道桥接(逃生舱,需要本地通道桥接作用域);只在其它工具都做不到时使用。

形态:本机云端。

参数类型必填说明
devicestring否目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env

env_power

开关机与暂停。已弃用,下一个次版本移除,改用 env_start、env_stop、env_reboot、env_pause、env_resume;开机、关机、重启、暂停或继续环境(经桌面端转发平台)

形态:本机本地;有破坏性。

参数类型必填说明
devicestring否目标设备:env:<环境 ID> 或环境 ID;缺省取 device_use 选定的设备或启动参数 --device/--env
opstring是start、stop、reboot、pause 或 resume

返回:环境生命周期操作的结果。

字段说明
device设备,写作 env:<环境 ID>
opstart、stop、reboot、pause、resume 或 sync
result平台或桌面端返回的原始结果
status任务状态
task平台任务编号,用 job_get 查询进度与结果