Common Options and Return Objects

This page describes the shared options, task object, result objects, and error statuses used by LCC.assist APIs.

options Fields

Field	Type	Default	Description
`type`	string	`"text"`	Request type. Recognized aliases: `"text"`/`"text-reply"`, `"point"`/`"pick-point"`, `"control"`/`"device-control"`. Convenience wrappers set this automatically.
`title`	string	`"脚本请求人工辅助"`	Title shown in the control center.
`text` / `prompt`	string	`""`	Instructions shown to the operator. Make them actionable; do not write vague text such as "provide more information".
`timeout`	number	`300`	Wait timeout in seconds; also used as the backend task expiration when creating the task.
`pollIntervalMs`	number	`1000`	Polling interval in milliseconds. Values below `250` are clamped to `250`.
`screenshotLocalPath`	string		Local screenshot file on the device. The SDK uploads it to `files/_temp/assist/lua-script/<udid>/<request-id>/...`.
`screenshotPath`	string		Existing image path under the control center `files` root.
`screenshotImage` / `image`	ImageObject		XXTouch image object. The SDK exports it as a data URL and writes it to `input.imageSrc`.
`screenshotImageData` / `imageData`	string		PNG/JPEG binary image data. The SDK converts it to a data URL and writes it to `input.imageSrc`.
`screenshotImageFormat` / `imageFormat`	string	`"jpeg"`	Export format for `screenshotImage`. Supported values are `"jpeg"` and `"png"`.
`screenshotImageQuality` / `imageQuality`	number	`0.7`	JPEG quality used when exporting `screenshotImage`, from `0.0` to `1.0`.
`screenshotImageMimeType` / `imageMimeType`	string	auto-detect	MIME type for `screenshotImageData`; PNG/JPEG data usually does not need this.
`imageRect`	table		Crop-to-device coordinate mapping, for example `{ left = 100, top = 200, width = 300, height = 120 }`.
`input`	table	`{}`	Extra structured metadata passed through to the control center. The SDK adds `requestType` and `scriptRequestId`.

screenshotLocalPath has higher priority than screenshotPath. If screenshotLocalPath is provided, the SDK uploads the file and uses the uploaded path.

If input.imageSrc, screenshotLocalPath, and screenshotPath are not provided, the SDK tries to convert screenshotImage or screenshotImageData into input.imageSrc. The caller owns the ImageObject; the SDK does not call destroy() automatically.

Pass an ImageObject Directly

local img = screen.image()
local result, err = LCC.assist.request_control({
    title = "Need human handling",
    text = "Remote-control the device, finish the current verification, then click Done",
    screenshotImage = img,
    screenshotImageQuality = 0.6,
})
if img.destroy then
    img:destroy()
end

Pass Image Data Directly

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

local result, err = LCC.assist.request_control({
    title = "Need human handling",
    text = "Remote-control the device, finish the current verification, then click Done",
    screenshotImageData = data,
})

Pass an Image URL Directly

local result, err = LCC.assist.request_control({
    title = "Need human handling",
    text = "Remote-control the device, finish the current verification, then click Done",
    input = {
        imageSrc = "data:image/jpeg;base64,...",
    },
})

input.imageSrc does not upload a file and does not populate screenshotPath.

To avoid long-lived memory usage, the control center removes imageSrc from task input after the task is submitted, cancelled, or expired. The image is still displayed normally while the request is being handled.

Task Object

task is the assist task stored by the control center. Common fields:

{
    id = "assist_xxx",
    kind = "text-reply",
    title = "Enter captcha",
    prompt = "Enter the captcha shown in the screenshot",
    status = "pending",
    deviceId = "device UDID",
    source = "lua-script",
    screenshotPath = "assist/...",
    input = {},
    result = nil,
    createdAt = 1781196058792,
    updatedAt = 1781196058792,
    expiresAt = 1781196358792,
}

Timestamp fields are milliseconds since epoch. Script-created requests automatically set deviceId = device.udid() and source = "lua-script".

Result Objects

Successful text reply:

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

Successful picked point:

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

x and y are physical device coordinates and can be used directly with touch.tap. imageX and imageY are coordinates inside the screenshot.

Remote control when the operator clicks Done:

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

When the operator expands Manual Submit and submits valid JSON, result is the Lua value decoded from that JSON. For example, submitting:

{"allowed":true,"reason":"confirmed by operator"}

returns:

{ allowed = true, reason = "confirmed by operator" }

When the operator manually submits non-JSON plain text:

{ note = "plain text content" }

Empty Manual Submit content is not submitted, so the script keeps waiting.

Errors and Statuses

On wait failure:

nil, err, task

Common err values:

"cancelled": cancelled by the user or script.
"expired": expired on the backend.
"timeout": the script wait timeout was reached; the SDK has attempted to cancel the task.
"not found": the task does not exist, often because the backend restarted or cleaned it up.
Other strings: network error, screenshot upload error, or backend response text.

Only submitted returns a result. Treat cancelled, expired, and timeout as no human result.

options Fields​

Pass an ImageObject Directly​

Pass Image Data Directly​

Pass an Image URL Directly​

Task Object​

Result Objects​

Errors and Statuses​