Parámetros comunes y objetos devueltos

Esta página describe las opciones options, el objeto de tarea, el objeto de resultado y los estados de error compartidos por las API de la serie LCC.assist.

Campos de options

Campo	Tipo	Valor predeterminado	Descripción
`type`	string	`"text"`	Tipo de solicitud. Se reconocen `"text"`/`"text-reply"`, `"point"`/`"pick-point"` y `"control"`/`"device-control"`. Los envoltorios abreviados lo establecen automáticamente.
`title`	string	`"脚本请求人工辅助"`	Título de la tarjeta en el control central.
`text` / `prompt`	string	`""`	Instrucciones para el operador. Deben indicar una acción concreta; no escribas «información adicional».
`timeout`	number	`300`	Segundos de espera; también se usa como tiempo de expiración del backend al crear la tarea.
`pollIntervalMs`	number	`1000`	Intervalo de sondeo en milisegundos; los valores menores que `250` se tratan como `250`.
`screenshotLocalPath`	string		Archivo de captura local del dispositivo; el SDK lo sube al control central `files/_temp/assist/lua-script/<udid>/<request-id>/...`.
`screenshotPath`	string		Ruta relativa de la imagen bajo la raíz `files` del control central.
`screenshotImage` / `image`	ImageObject		Objeto de imagen de XXTouch. El SDK lo exporta como data URL y lo escribe en `input.imageSrc`.
`screenshotImageData` / `imageData`	string		Datos binarios de imagen PNG/JPEG. El SDK los convierte en una data URL y los escribe en `input.imageSrc`.
`screenshotImageFormat` / `imageFormat`	string	`"jpeg"`	Formato de exportación de `screenshotImage`; puede ser `"jpeg"` o `"png"`.
`screenshotImageQuality` / `imageQuality`	number	`0.7`	Calidad de `screenshotImage` al exportarla como JPEG, en el intervalo `0.0` a `1.0`.
`screenshotImageMimeType` / `imageMimeType`	string	Detección automática	Tipo MIME de `screenshotImageData`; normalmente no es necesario proporcionarlo para datos PNG/JPEG.
`imageRect`	table		Se usa para reasignar una imagen recortada a las coordenadas del dispositivo, por ejemplo, `{ left = 100, top = 200, width = 300, height = 120 }`.
`input`	table	`{}`	Información estructurada adicional que se reenviará al control central. El SDK añadirá `requestType` y `scriptRequestId`.

screenshotLocalPath tiene prioridad sobre screenshotPath. Si se proporciona screenshotLocalPath en esta llamada, el SDK sube el archivo y usa la ruta resultante.

Si no se proporciona input.imageSrc ni screenshotLocalPath / screenshotPath, el SDK intentará convertir screenshotImage o screenshotImageData en input.imageSrc. El llamador administra ImageObject; el SDK no ejecuta destroy() automáticamente.

Pasar directamente un 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

Pasar directamente datos de imagen

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,
})

Pasar directamente una dirección de imagen

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

input.imageSrc no sube ningún archivo ni escribe en screenshotPath.

Para evitar ocupar memoria durante mucho tiempo, el control central elimina imageSrc del input de la tarea cuando esta se envía, cancela o expira. La imagen sigue mostrándose con normalidad mientras se procesa la solicitud.

Objeto de tarea

task es la tarea de asistencia guardada en el control central. Sus campos habituales son los siguientes:

{
    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,
}

Los campos de tiempo son marcas de tiempo en milisegundos. Las solicitudes creadas por el script incluyen automáticamente deviceId = device.udid() y source = "lua-script".

Objeto de resultado

Cuando la respuesta de texto tiene éxito:

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

Cuando la selección de coordenadas tiene éxito:

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

x e y son coordenadas físicas del dispositivo y pueden usarse directamente con touch.tap. imageX e imageY son coordenadas dentro de la captura de pantalla.

Cuando el control remoto manual hace clic en «Completado»:

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

Cuando el control remoto manual abre «Enviar resultado manualmente» y envía un JSON válido, result es el valor Lua correspondiente a ese JSON. Por ejemplo:

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

El script recibe:

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

Cuando el control remoto manual envía texto normal que no es JSON:

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

Enviar manualmente un contenido vacío no envía la tarea; el script continúa esperando.

Errores y estados

Cuando la espera falla, devuelve:

nil, err, task

err habituales:

"cancelled": cancelación por parte del usuario o del script.
"expired": la tarea del backend ha expirado.
"timeout": se agotó el tiempo de espera del script y el SDK intentó cancelar la tarea.
"not found": la tarea no existe, posiblemente porque se reinició el backend o se limpió la tarea.
Otras cadenas: texto de error devuelto por la red, la subida de la captura o la interfaz del backend.

Solo el estado submitted devuelve result. cancelled, expired y timeout deben considerarse como ausencia de resultado humano.

Campos de options​

Pasar directamente un ImageObject​

Pasar directamente datos de imagen​

Pasar directamente una dirección de imagen​

Objeto de tarea​

Objeto de resultado​

Errores y estados​