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​

Type | API | Use case | Typical script action
--- | --- | --- | ---
Text reply | `LCC.assist.ask_text()` | Captcha, SMS code, passcode, one-time token | Input `result.text` into the focused field
Pick point | `LCC.assist.pick_point()` | The operator needs to decide where to tap, such as a visual button or abnormal dialog | Call `touch.tap(result.x, result.y)`
Remote control | `LCC.assist.request_control()` | Slider verification, human check, login, security check, permission prompt, or other unstable flow | Wait 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​

- Common Options and Return Objects
- Create an Assist Request `LCC.assist.create()`
- Wait for an Assist Result `LCC.assist.wait()`
- Create and Wait `LCC.assist.request()`
- Request a Text Reply `LCC.assist.ask_text()`
- Request a Picked Point `LCC.assist.pick_point()`
- Request Remote Control `LCC.assist.request_control()`
- Cancel One Request `LCC.assist.cancel()`
- Cancel Current Script Requests `LCC.assist.cancel_all()`