跳到主要内容

通用参数与返回对象

本页说明 LCC.assist 系列 API 共用的 options、任务对象、结果对象和错误状态。

options 字段​

字段类型默认值说明
typestring"text"请求类型。"text"/"text-reply"、"point"/"pick-point"、"control"/"device-control" 都可识别。便捷封装会自动设置。
titlestring"脚本请求人工辅助"中控端卡片标题。
text / promptstring""给操作人员看的说明。应写具体操作，不要写“补充信息”。
timeoutnumber300等待秒数；创建任务时也会作为后端过期时间。
pollIntervalMsnumber1000轮询间隔毫秒；小于 250 会按 250 处理。
screenshotLocalPathstring设备本地截图文件，SDK 会上传到中控 files/_temp/assist/lua-script/<udid>/<request-id>/...。
screenshotPathstring已在中控 files 根目录下的图片相对路径。
screenshotImage / imageImageObjectXXTouch 图片对象。SDK 会导出为 data URL 并写入 input.imageSrc。
screenshotImageData / imageDatastringPNG/JPEG 图片二进制数据。SDK 会转成 data URL 并写入 input.imageSrc。
screenshotImageFormat / imageFormatstring"jpeg"screenshotImage 的导出格式，可选 "jpeg" 或 "png"。
screenshotImageQuality / imageQualitynumber0.7screenshotImage 导出为 JPEG 时的质量，范围 0.0 到 1.0。
screenshotImageMimeType / imageMimeTypestring自动识别screenshotImageData 的 MIME 类型；PNG/JPEG 数据通常不需要传。
imageRecttable裁剪图映射回设备坐标时使用，例如 { left = 100, top = 200, width = 300, height = 120 }。
inputtable{}额外结构化信息，会透传给中控端。SDK 会追加 requestType 和 scriptRequestId。

screenshotLocalPath 优先级高于 screenshotPath。如果本次传了 screenshotLocalPath，SDK 会上传文件并使用上传后的路径。

未传 input.imageSrc 且未传 screenshotLocalPath / screenshotPath 时，SDK 会尝试把 screenshotImage 或 screenshotImageData 转成 input.imageSrc。ImageObject 由调用方管理，SDK 不会自动 destroy()。

直接传 ImageObject​

local img = screen.image()
local result, err = LCC.assist.request_control({
    title = "需要人工处理",
    text = "请远控完成当前验证后点击完成",
    screenshotImage = img,
    screenshotImageQuality = 0.6,
})
if img.destroy then
    img:destroy()
end

直接传图片数据​

local img = screen.image()
local data = img:png_data()
if img.destroy then
    img:destroy()
end

local result, err = LCC.assist.request_control({
    title = "需要人工处理",
    text = "请远控完成当前验证后点击完成",
    screenshotImageData = data,
})

直接传图片地址​

local result, err = LCC.assist.request_control({
    title = "需要人工处理",
    text = "请远控完成当前验证后点击完成",
    input = {
        imageSrc = "data:image/jpeg;base64,...",
    },
})

input.imageSrc 不会上传文件，也不会写入 screenshotPath。

为避免长时间占用内存，任务进入提交、取消或过期状态后，中控会从任务 input 中移除 imageSrc。请求处理期间图片仍会正常展示。

任务对象​

task 是中控端保存的辅助任务，常用字段如下：

{
    id = "assist_xxx",
    kind = "text-reply",
    title = "输入验证码",
    prompt = "请查看截图并输入验证码",
    status = "pending",
    deviceId = "设备 UDID",
    source = "lua-script",
    screenshotPath = "assist/...",
    input = {},
    result = nil,
    createdAt = 1781196058792,
    updatedAt = 1781196058792,
    expiresAt = 1781196358792,
}

时间字段是毫秒时间戳。脚本创建的请求会自动写入 deviceId = device.udid() 和 source = "lua-script"。

结果对象​

文本回复成功时：

{ kind = "text-reply", text = "1234" }

选择坐标成功时：

{
    kind = "pick-point",
    x = 123,
    y = 456,
    imageX = 123,
    imageY = 456,
    color = "AABBCC",
}

x、y 是设备物理坐标，可直接用于 touch.tap。imageX、imageY 是截图内坐标。

人工远控点击“已完成”时：

{ kind = "device-control", completed = true }

人工远控展开“手动提交结果”并提交合法 JSON 时，result 是该 JSON 对应的 Lua 值。例如提交：

{"allowed":true,"reason":"人工确认"}

脚本会收到：

{ allowed = true, reason = "人工确认" }

人工远控手动提交非 JSON 普通文本时：

{ note = "普通文本内容" }

手动提交空内容不会提交任务，脚本会继续等待。

错误和状态​

等待失败时返回：

nil, err, task

常见 err：

  • "cancelled"：用户或脚本取消。
  • "expired"：后端任务过期。
  • "timeout"：脚本等待超时，SDK 已尝试撤销任务。
  • "not found"：任务不存在，可能是后端重启或任务已被清理。
  • 其它字符串：网络、上传截图、后端接口返回的错误文本。

只有 submitted 状态会返回 result。cancelled、expired、timeout 都应视为没有拿到人工结果。