Parâmetros comuns e objetos de retorno

Esta página descreve as opções options, os objetos de tarefa, os objetos de resultado e os estados de erro compartilhados pelas APIs da série LCC.assist.

Campos de options

Campo	Tipo	Valor padrão	Descrição
type	string	"text"	Tipo da solicitação. "text"/"text-reply", "point"/"pick-point" e "control"/"device-control" são reconhecidos. Os wrappers convenientes definem o valor automaticamente.
title	string	"脚本请求人工辅助"	Título do cartão no controle central.
text / prompt	string	""	Instruções para a pessoa que vai operar. Escreva uma ação concreta, não "informações adicionais".
timeout	number	300	Segundos de espera; ao criar a tarefa, também é usado como tempo de expiração no back-end.
pollIntervalMs	number	1000	Intervalo de consulta em milissegundos; valores menores que 250 são tratados como 250.
screenshotLocalPath	string		Arquivo de screenshot local do dispositivo; o SDK o envia para files/_temp/assist/lua-script/<udid>/<request-id>/... no controle central.
screenshotPath	string		Caminho relativo da imagem já localizada na raiz files do controle central.
screenshotImage / image	ImageObject		Objeto de imagem do XXTouch. O SDK o exporta como data URL e o grava em input.imageSrc.
screenshotImageData / imageData	string		Dados binários de imagem PNG/JPEG. O SDK os converte em data URL e os grava em input.imageSrc.
screenshotImageFormat / imageFormat	string	"jpeg"	Formato de exportação de screenshotImage, que pode ser "jpeg" ou "png".
screenshotImageQuality / imageQuality	number	0.7	Qualidade ao exportar screenshotImage como JPEG, de 0.0 a 1.0.
screenshotImageMimeType / imageMimeType	string	detecção automática	Tipo MIME de screenshotImageData; normalmente não é necessário informá-lo para dados PNG/JPEG.
imageRect	table		Usado para mapear uma imagem recortada de volta às coordenadas do dispositivo, por exemplo { left = 100, top = 200, width = 300, height = 120 }.
input	table	{}	Informações estruturadas adicionais, repassadas ao controle central. O SDK acrescenta requestType e scriptRequestId.

screenshotLocalPath tem prioridade sobre screenshotPath. Se screenshotLocalPath for informado, o SDK enviará o arquivo e usará o caminho enviado.

Quando input.imageSrc e screenshotLocalPath / screenshotPath não forem informados, o SDK tentará converter screenshotImage ou screenshotImageData em input.imageSrc. O ImageObject é gerenciado pelo chamador; o SDK não chama destroy() automaticamente.

Passar um ImageObject diretamente

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

Passar dados de imagem diretamente

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

Passar um endereço de imagem diretamente

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

input.imageSrc não envia arquivos nem grava em screenshotPath.

Para evitar manter memória ocupada por muito tempo, o controle central remove imageSrc de input da tarefa quando ela passa ao estado enviado, cancelado ou expirado. A imagem continua sendo exibida normalmente durante o processamento da solicitação.

Objeto de tarefa

task é a tarefa de assistência armazenada no controle central. Os campos mais usados são:

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

Os campos de tempo são timestamps em milissegundos. As solicitações criadas por scripts recebem automaticamente deviceId = device.udid() e source = "lua-script".

Objeto de resultado

Quando uma resposta de texto é enviada com sucesso:

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

Quando uma coordenada é selecionada com sucesso:

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

x e y são coordenadas físicas do dispositivo e podem ser usados diretamente com touch.tap. imageX e imageY são coordenadas dentro da screenshot.

Quando o controle remoto humano clica em "Concluído":

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

Quando o controle remoto humano expande "Enviar resultado manualmente" e envia um JSON válido, result é o valor Lua correspondente a esse JSON. Por exemplo, ao enviar:

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

o script receberá:

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

Quando o controle remoto humano envia manualmente um texto comum que não é JSON:

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

O envio manual de conteúdo vazio não envia a tarefa, e o script continua aguardando.

Erros e estados

Quando a espera falha, retorna:

nil, err, task

Valores comuns de err:

• "cancelled": cancelamento pelo usuário ou pelo script.
• "expired": a tarefa do back-end expirou.
• "timeout": a espera do script atingiu o tempo limite e o SDK tentou revogar a tarefa.
• "not found": a tarefa não existe, possivelmente porque o back-end foi reiniciado ou a tarefa foi limpa.
• Outras strings: texto de erro retornado pela rede, pelo upload da screenshot ou pela API do back-end.

Somente o estado submitted retorna result. cancelled, expired e timeout devem ser tratados como ausência de resultado humano.