Skip to main content

Human Assist

LCC.assist lets a device script ask the control center for human assistance. A request can include a screenshot and clear instructions, block until the operator submits a result, and then continue.

Request Types​

TypeAPIUse caseTypical script action
Text replyLCC.assist.ask_text()Captcha, SMS code, passcode, one-time tokenInput result.text into the focused field
Pick pointLCC.assist.pick_point()The operator needs to decide where to tap, such as a visual button or abnormal dialogCall touch.tap(result.x, result.y)
Remote controlLCC.assist.request_control()Slider verification, human check, login, security check, permission prompt, or other unstable flowWait for the operator to finish, then capture the new screen and continue

Instructions shown to the operator should be concrete and actionable. Do not use vague text such as "provide more information". Use direct instructions such as "remote-control the device, finish the current verification, then click Done", "enter the captcha in the screenshot", or "pick the center of the confirm button".

Screenshot Sources​

An assist request can include an image in several ways:

  • screenshotLocalPath: local image path on the device. The SDK uploads it to files/_temp/assist/lua-script/<udid>/<request-id>/....
  • screenshotPath: an existing relative path under the control center files root.
  • screenshotImage: an XXTouch ImageObject. The SDK converts it to a data URL without saving a file first.
  • screenshotImageData: PNG/JPEG binary image data. The SDK converts it to a data URL.
  • input.imageSrc: a data:image/..., http(s)://..., or /api/... image URL already available to the script.

The SDK does not overwrite input.imageSrc. If input.imageSrc and path-based screenshots are not provided, the SDK converts screenshotImage or screenshotImageData into input.imageSrc.

Lifecycle​

A request starts as pending, becomes active when opened in a control-center tool, and becomes submitted when the operator submits the result. User cancellation, script cancellation, wait timeout, or expiration moves it to cancelled / expired.

The script side has two cleanup paths:

  • LCC.assist.request() cancels the request and returns nil, "timeout", task when the wait timeout is reached.
  • When the script exits, XXTLanControl.lua calls cancel_all() and cancels unfinished requests created by the current script.

When the control center receives a script-stopped state for a device, it also cancels pending / active requests from that same device with source = "lua-script". It does not cancel requests from other devices and does not modify submitted requests.

Assist tasks use the current in-memory task store. Unfinished tasks are lost if the backend restarts.

If a request uses input.imageSrc, screenshotImage, or screenshotImageData for an inline image, the control center drops the inline image content after the task is submitted, cancelled, or expired. The task status, result, and other structured metadata remain available.

If the app exits abnormally and is opened again, unfinished tasks are not restored. On startup, the control center removes screenshots uploaded by script assist requests under files/_temp/assist/lua-script/. It also cleans legacy files/assist/lua-script/ and files/assist/<udid>/<request-id>/ directories when the request ID segment is a UUID.

API List​