Tham số chung và đối tượng trả về

Trang này mô tả options, đối tượng tác vụ, đối tượng kết quả và trạng thái lỗi dùng chung cho các API thuộc LCC.assist.

Các trường của options

Trường	Kiểu	Giá trị mặc định	Mô tả
`type`	string	`"text"`	Loại yêu cầu. Hỗ trợ `"text"`/`"text-reply"`, `"point"`/`"pick-point"` và `"control"`/`"device-control"`. Các hàm tiện ích sẽ tự động đặt giá trị này.
`title`	string	`"脚本请求人工辅助"`	Tiêu đề thẻ tại trung tâm điều khiển; giá trị mặc định có nghĩa là “Tập lệnh yêu cầu hỗ trợ thủ công”.
`text` / `prompt`	string	`""`	Hướng dẫn dành cho người vận hành. Cần mô tả thao tác cụ thể, không nên ghi nội dung mơ hồ như “thông tin bổ sung”.
`timeout`	number	`300`	Số giây chờ; khi tạo tác vụ, giá trị này cũng được dùng làm thời hạn hết hạn ở backend.
`pollIntervalMs`	number	`1000`	Khoảng thời gian thăm dò tính bằng mili giây; giá trị nhỏ hơn `250` sẽ được xử lý như `250`.
`screenshotLocalPath`	string		Tệp ảnh chụp cục bộ trên thiết bị; SDK sẽ tải lên `files/_temp/assist/lua-script/<udid>/<request-id>/...` tại trung tâm điều khiển.
`screenshotPath`	string		Đường dẫn tương đối của ảnh đã nằm dưới thư mục gốc `files` tại trung tâm điều khiển.
`screenshotImage` / `image`	ImageObject		Đối tượng ảnh XXTouch. SDK sẽ xuất thành data URL và ghi vào `input.imageSrc`.
`screenshotImageData` / `imageData`	string		Dữ liệu nhị phân của ảnh PNG/JPEG. SDK sẽ chuyển thành data URL và ghi vào `input.imageSrc`.
`screenshotImageFormat` / `imageFormat`	string	`"jpeg"`	Định dạng xuất của `screenshotImage`, có thể chọn `"jpeg"` hoặc `"png"`.
`screenshotImageQuality` / `imageQuality`	number	`0.7`	Chất lượng khi xuất `screenshotImage` thành JPEG, trong khoảng từ `0.0` đến `1.0`.
`screenshotImageMimeType` / `imageMimeType`	string	Tự động nhận diện	Kiểu MIME của `screenshotImageData`; thường không cần truyền với dữ liệu PNG/JPEG.
`imageRect`	table		Dùng khi ánh xạ ảnh đã cắt về tọa độ thiết bị, ví dụ `{ left = 100, top = 200, width = 300, height = 120 }`.
`input`	table	`{}`	Thông tin có cấu trúc bổ sung được chuyển nguyên trạng tới trung tâm điều khiển. SDK sẽ thêm `requestType` và `scriptRequestId`.

screenshotLocalPath được ưu tiên hơn screenshotPath. Nếu truyền screenshotLocalPath, SDK sẽ tải tệp lên và dùng đường dẫn sau khi tải lên.

Khi không truyền input.imageSrc, screenshotLocalPath hoặc screenshotPath, SDK sẽ thử chuyển screenshotImage hoặc screenshotImageData thành input.imageSrc. ImageObject do bên gọi quản lý; SDK không tự động gọi destroy().

Truyền trực tiếp ImageObject

local img = screen.image()
local result, err = LCC.assist.request_control({
    title = "Cần xử lý thủ công",
    text = "Hãy điều khiển từ xa để hoàn tất xác minh hiện tại, sau đó nhấp Hoàn tất",
    screenshotImage = img,
    screenshotImageQuality = 0.6,
})
if img.destroy then
    img:destroy()
end

Truyền trực tiếp dữ liệu ảnh

local img = screen.image()
local data = img:png_data()
if img.destroy then
    img:destroy()
end

local result, err = LCC.assist.request_control({
    title = "Cần xử lý thủ công",
    text = "Hãy điều khiển từ xa để hoàn tất xác minh hiện tại, sau đó nhấp Hoàn tất",
    screenshotImageData = data,
})

Truyền trực tiếp địa chỉ ảnh

local result, err = LCC.assist.request_control({
    title = "Cần xử lý thủ công",
    text = "Hãy điều khiển từ xa để hoàn tất xác minh hiện tại, sau đó nhấp Hoàn tất",
    input = {
        imageSrc = "data:image/jpeg;base64,...",
    },
})

input.imageSrc không tải tệp lên và cũng không ghi vào screenshotPath.

Để tránh chiếm bộ nhớ trong thời gian dài, sau khi tác vụ chuyển sang trạng thái đã gửi, bị hủy hoặc hết hạn, trung tâm điều khiển sẽ xóa imageSrc khỏi input của tác vụ. Ảnh vẫn hiển thị bình thường trong thời gian xử lý yêu cầu.

Đối tượng tác vụ

task là tác vụ hỗ trợ được lưu tại trung tâm điều khiển. Các trường thường dùng như sau:

{
    id = "assist_xxx",
    kind = "text-reply",
    title = "Nhập mã xác minh",
    prompt = "Hãy xem ảnh chụp màn hình và nhập mã xác minh",
    status = "pending",
    deviceId = "UDID thiết bị",
    source = "lua-script",
    screenshotPath = "assist/...",
    input = {},
    result = nil,
    createdAt = 1781196058792,
    updatedAt = 1781196058792,
    expiresAt = 1781196358792,
}

Các trường thời gian là dấu thời gian tính bằng mili giây. Yêu cầu do tập lệnh tạo sẽ tự động ghi deviceId = device.udid() và source = "lua-script".

Đối tượng kết quả

Khi phản hồi văn bản thành công:

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

Khi chọn tọa độ thành công:

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

x, y là tọa độ vật lý của thiết bị và có thể dùng trực tiếp với touch.tap. imageX, imageY là tọa độ trong ảnh chụp màn hình.

Khi người vận hành điều khiển từ xa nhấp “Hoàn tất”:

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

Khi người vận hành mở “Gửi thủ công” trong giao diện điều khiển từ xa và gửi JSON hợp lệ, result là giá trị Lua tương ứng với JSON đó. Ví dụ, nếu gửi:

{"allowed":true,"reason":"Xác nhận thủ công"}

tập lệnh sẽ nhận được:

{ allowed = true, reason = "Xác nhận thủ công" }

Khi người vận hành gửi thủ công văn bản thông thường không phải JSON:

{ note = "Nội dung văn bản thông thường" }

Gửi thủ công nội dung rỗng sẽ không gửi tác vụ; tập lệnh tiếp tục chờ.

Lỗi và trạng thái

Khi chờ thất bại, hàm trả về:

nil, err, task

Các giá trị err thường gặp:

"cancelled": Người dùng hoặc tập lệnh đã hủy.
"expired": Tác vụ backend đã hết hạn.
"timeout": Tập lệnh đã hết thời gian chờ; SDK đã thử hủy tác vụ.
"not found": Tác vụ không tồn tại, có thể do backend đã khởi động lại hoặc tác vụ đã được dọn dẹp.
Chuỗi khác: Nội dung lỗi do mạng, quá trình tải ảnh chụp màn hình hoặc API backend trả về.

Chỉ trạng thái submitted mới trả về result. Các trạng thái cancelled, expired và timeout đều phải được xem là chưa nhận được kết quả thủ công.

Các trường của options​

Truyền trực tiếp ImageObject​

Truyền trực tiếp dữ liệu ảnh​

Truyền trực tiếp địa chỉ ảnh​

Đối tượng tác vụ​

Đối tượng kết quả​

Lỗi và trạng thái​