Options communes et objets de retour

Cette page décrit les API de la série LCC.assist, ainsi que les options, l'objet de tâche, les objets de résultat et les états d'erreur communs.

Champs de options

Champ	Type	Valeur par défaut	Description
type	string	"text"	Type de demande. Les alias "text"/"text-reply", "point"/"pick-point" et "control"/"device-control" sont tous reconnus. Les fonctions pratiques le définissent automatiquement.
title	string	"脚本请求人工辅助"	Titre de la carte dans le centre de contrôle.
text / prompt	string	""	Instructions destinées à l'opérateur. Décrivez une action précise et n'écrivez pas « informations complémentaires ».
timeout	number	300	Délai d'attente en secondes ; sert aussi de délai d'expiration de la tâche côté serveur lors de sa création.
pollIntervalMs	number	1000	Intervalle d'interrogation en millisecondes ; toute valeur inférieure à 250 est ramenée à 250.
screenshotLocalPath	string		Fichier de capture local à l'appareil ; le SDK le téléverse vers files/_temp/assist/lua-script/<udid>/<request-id>/... du centre de contrôle.
screenshotPath	string		Chemin relatif d'une image déjà placée sous la racine files du centre de contrôle.
screenshotImage / image	ImageObject		Objet image XXTouch. Le SDK l'exporte au format data URL et l'écrit dans input.imageSrc.
screenshotImageData / imageData	string		Données binaires d'une image PNG/JPEG. Le SDK les convertit en data URL et les écrit dans input.imageSrc.
screenshotImageFormat / imageFormat	string	"jpeg"	Format d'export de screenshotImage, soit "jpeg", soit "png".
screenshotImageQuality / imageQuality	number	0.7	Qualité utilisée lors de l'export JPEG de screenshotImage, comprise entre 0.0 et 1.0.
screenshotImageMimeType / imageMimeType	string	détection automatique	Type MIME de screenshotImageData ; il est généralement inutile de le fournir pour des données PNG/JPEG.
imageRect	table		Sert à remapper une image recadrée vers les coordonnées de l'appareil, par exemple { left = 100, top = 200, width = 300, height = 120 }.
input	table	{}	Informations structurées supplémentaires transmises telles quelles au centre de contrôle. Le SDK ajoute requestType et scriptRequestId.

screenshotLocalPath est prioritaire sur screenshotPath. Si screenshotLocalPath est fourni, le SDK téléverse le fichier et utilise le chemin téléversé.

Si ni input.imageSrc ni screenshotLocalPath / screenshotPath ne sont fournis, le SDK tente de convertir screenshotImage ou screenshotImageData en input.imageSrc. ImageObject reste sous la responsabilité de l'appelant ; le SDK n'appelle pas automatiquement destroy().

Fournir directement 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

Fournir directement des données d'image

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

Fournir directement une adresse d'image

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

input.imageSrc ne téléverse aucun fichier et n'écrit rien dans screenshotPath.

Pour éviter de conserver inutilement de la mémoire, le centre de contrôle retire de input la valeur imageSrc lorsque la tâche passe à l'état envoyé, annulé ou expiré. L'image reste normalement affichée pendant le traitement de la demande.

Objet de tâche

task est la tâche d'assistance enregistrée par le centre de contrôle. Ses champs courants sont les suivants :

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

Les champs temporels sont des horodatages en millisecondes. Les demandes créées par un script reçoivent automatiquement deviceId = device.udid() et source = "lua-script".

Objet de résultat

En cas de succès d'une réponse textuelle :

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

En cas de succès d'une sélection de coordonnées :

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

x et y sont les coordonnées physiques de l'appareil et peuvent être utilisées directement avec touch.tap. imageX et imageY sont les coordonnées dans la capture d'écran.

Lorsque l'opérateur à distance clique sur « Terminé » :

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

Lorsque l'opérateur à distance ouvre « Envoyer manuellement le résultat » et envoie un JSON valide, result est la valeur Lua correspondant à ce JSON. Par exemple, pour :

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

le script reçoit :

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

Lorsque l'opérateur envoie un texte ordinaire qui n'est pas du JSON :

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

Un envoi manuel vide ne soumet pas la tâche ; le script continue d'attendre.

Erreurs et états

En cas d'échec de l'attente, la fonction renvoie :

nil, err, task

Valeurs courantes de err :

• "cancelled" : annulation par l'utilisateur ou le script.
• "expired" : tâche expirée côté serveur.
• "timeout" : attente du script dépassée ; le SDK a tenté de révoquer la tâche.
• "not found" : tâche inexistante, peut-être à cause d'un redémarrage du serveur ou d'un nettoyage.
• Toute autre chaîne : erreur réseau, téléversement de capture ou texte renvoyé par l'API du serveur.

Seul l'état submitted renvoie result. Les états cancelled, expired et timeout doivent tous être considérés comme une absence de résultat humain.