Gemeinsame Optionen und Rückgabeobjekte

Diese Seite beschreibt die von den LCC.assist-APIs gemeinsam verwendeten options, Aufgaben- und Ergebnisobjekte sowie Fehlerstatus.

options-Felder

Feld	Typ	Standardwert	Beschreibung
type	string	"text"	Anfragetyp. Die Aliase "text"/"text-reply", "point"/"pick-point" und "control"/"device-control" werden erkannt. Komfortfunktionen setzen den Typ automatisch.
title	string	"脚本请求人工辅助"	Kartentitel in der Zentrale.
text / prompt	string	""	Anweisung für die Bedienperson. Beschreiben Sie eine konkrete Aktion, nicht „Weitere Informationen“.
timeout	number	300	Wartezeit in Sekunden; beim Erstellen der Aufgabe auch deren Ablaufzeit im Backend.
pollIntervalMs	number	1000	Polling-Intervall in Millisekunden; Werte unter 250 werden als 250 behandelt.
screenshotLocalPath	string		Lokale Screenshotdatei auf dem Gerät; das SDK lädt sie zur Zentrale unter files/_temp/assist/lua-script/<udid>/<request-id>/... hoch.
screenshotPath	string		Relativer Bildpfad unter dem files-Stammverzeichnis der Zentrale.
screenshotImage / image	ImageObject		XXTouch-Bildobjekt. Das SDK exportiert es als Data-URL und schreibt es in input.imageSrc.
screenshotImageData / imageData	string		Binäre PNG-/JPEG-Bilddaten. Das SDK wandelt sie in eine Data-URL um und schreibt sie in input.imageSrc.
screenshotImageFormat / imageFormat	string	"jpeg"	Exportformat von screenshotImage; möglich sind "jpeg" und "png".
screenshotImageQuality / imageQuality	number	0.7	JPEG-Qualität beim Export von screenshotImage, im Bereich 0.0 bis 1.0.
screenshotImageMimeType / imageMimeType	string	automatisch	MIME-Typ von screenshotImageData; für PNG-/JPEG-Daten normalerweise nicht erforderlich.
imageRect	table		Wird für die Zuordnung eines zugeschnittenen Bildes zu Gerätekoordinaten verwendet, z. B. { left = 100, top = 200, width = 300, height = 120 }.
input	table	{}	Zusätzliche strukturierte Informationen, die an die Zentrale weitergereicht werden. Das SDK ergänzt requestType und scriptRequestId.

screenshotLocalPath hat Vorrang vor screenshotPath. Wenn screenshotLocalPath angegeben ist, lädt das SDK die Datei hoch und verwendet den hochgeladenen Pfad.

Wenn weder input.imageSrc noch screenshotLocalPath / screenshotPath übergeben wurde, versucht das SDK, screenshotImage oder screenshotImageData in input.imageSrc umzuwandeln. Der Aufrufer verwaltet das ImageObject; das SDK ruft destroy() nicht automatisch auf.

ImageObject direkt übergeben

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

Bilddaten direkt übergeben

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

Bild-URL direkt übergeben

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

input.imageSrc lädt keine Datei hoch und schreibt nichts in screenshotPath.

Um eine langfristige Speichernutzung zu vermeiden, entfernt die Zentrale input-Feld imageSrc, sobald die Aufgabe übermittelt, abgebrochen oder abgelaufen ist. Während der Bearbeitung wird das Bild weiterhin angezeigt.

Aufgabenobjekt

task ist die von der Zentrale gespeicherte Unterstützungsaufgabe. Häufig verwendete Felder sind:

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

Zeitfelder sind Zeitstempel in Millisekunden. Von einem Skript erstellte Anfragen setzen automatisch deviceId = device.udid() und source = "lua-script".

Ergebnisobjekte

Bei erfolgreicher Textantwort:

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

Bei erfolgreicher Koordinatenauswahl:

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

x und y sind physische Gerätekoordinaten und können direkt mit touch.tap verwendet werden. imageX und imageY sind Koordinaten innerhalb des Screenshots.

Wenn die Bedienperson bei der Fernsteuerung auf „Erledigt“ klickt:

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

Wenn die Bedienperson bei der Fernsteuerung „Manuell übermitteln“ öffnet und gültiges JSON übermittelt, ist result der zugehörige Lua-Wert. Beispiel für eine Übermittlung:

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

Das Skript erhält:

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

Wenn die Bedienperson bei der Fernsteuerung normalen Text ohne JSON übermittelt:

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

Leerer Inhalt unter „Manuell übermitteln“ wird nicht übermittelt; das Skript wartet weiter.

Fehler und Status

Bei einem Fehler während des Wartens wird zurückgegeben:

nil, err, task

Häufige err-Werte:

• "cancelled": vom Benutzer oder Skript abgebrochen.
• "expired": im Backend abgelaufen.
• "timeout": Das Warte-Timeout des Skripts wurde erreicht; das SDK hat versucht, die Aufgabe abzubrechen.
• "not found": Die Aufgabe existiert nicht, häufig weil das Backend neu gestartet oder sie bereinigt wurde.
• Andere Zeichenketten: Fehlertext aus Netzwerk, Screenshot-Upload oder Backend-Schnittstelle.

Nur der Status submitted gibt result zurück. cancelled, expired und timeout sind so zu behandeln, als wäre kein menschliches Ergebnis eingegangen.