跳至主要內容

通用參數與傳回物件

本頁說明 LCC.assist 系列 API 共用的 options、任務物件、結果物件和錯誤狀態。

options 欄位​

欄位類型預設值說明
typestring"text"請求類型。"text"/"text-reply"、"point"/"pick-point"、"control"/"device-control" 都可識別。便捷封裝會自動設定。
titlestring"脚本请求人工辅助"中控端卡片標題；此預設值是 SDK 固定的簡體中文字串。
text / promptstring""給操作人員看的說明。應寫具體操作，不要寫“補充資訊”。
timeoutnumber300等待秒數；建立任務時也會作為後端過期時間。
pollIntervalMsnumber1000輪詢間隔毫秒；小於 250 會按 250 處理。
screenshotLocalPathstring裝置本機截圖檔案，SDK 會上傳到中控 files/_temp/assist/lua-script/<udid>/<request-id>/...。
screenshotPathstring已在中控 files 根目錄下的圖片相對路徑。
screenshotImage / imageImageObjectXXTouch 圖片物件。SDK 會匯出為 data URL 並寫入 input.imageSrc。
screenshotImageData / imageDatastringPNG/JPEG 圖片二進位資料。SDK 會轉成 data URL 並寫入 input.imageSrc。
screenshotImageFormat / imageFormatstring"jpeg"screenshotImage 的匯出格式，可選 "jpeg" 或 "png"。
screenshotImageQuality / imageQualitynumber0.7screenshotImage 匯出為 JPEG 時的品質，範圍 0.0 到 1.0。
screenshotImageMimeType / imageMimeTypestring自動識別screenshotImageData 的 MIME 類型；PNG/JPEG 資料通常不需要傳。
imageRecttable裁剪圖映射回裝置座標時使用，例如 { left = 100, top = 200, width = 300, height = 120 }。
inputtable{}額外的結構化資訊，會原樣傳遞給中控端。SDK 會另外加入 requestType 和 scriptRequestId。

screenshotLocalPath 優先級高於 screenshotPath。如果本次傳了 screenshotLocalPath，SDK 會上傳檔案並使用上傳後的路徑。

未傳 input.imageSrc 且未傳 screenshotLocalPath / screenshotPath 時，SDK 會嘗試把 screenshotImage 或 screenshotImageData 轉成 input.imageSrc。ImageObject 由呼叫方管理，SDK 不會自動 destroy()。

直接傳 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

直接傳圖片資料​

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

直接傳圖片地址​

local result, err = LCC.assist.request_control({
    title = "需要人工處理",
    text = "請遠端控制完成目前驗證後點擊完成",
    input = {
        imageSrc = "data:image/jpeg;base64,...",
    },
})

input.imageSrc 不會上傳檔案，也不會寫入 screenshotPath。

為避免長時間佔用記憶體，任務進入提交、取消或過期狀態後，中控會從任務 input 中移除 imageSrc。請求處理期間圖片仍會正常展示。

任務物件​

task 是中控端儲存的輔助任務，常用欄位如下：

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

時間欄位是毫秒時間戳。腳本建立的請求會自動寫入 deviceId = device.udid() 和 source = "lua-script"。

結果物件​

文字回覆成功時：

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

選擇座標成功時：

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

x、y 是裝置物理座標，可直接用於 touch.tap。imageX、imageY 是截圖內座標。

人工遠端控制按一下“已完成”時：

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

人工遠端控制展開“手動提交結果”並提交合法 JSON 時，result 是該 JSON 對應的 Lua 值。例如提交：

{"allowed":true,"reason":"人工確認"}

腳本會收到：

{ allowed = true, reason = "人工確認" }

人工遠端控制手動提交非 JSON 普通文字時：

{ note = "一般文字內容" }

手動提交空內容不會提交任務，腳本會繼續等待。

錯誤和狀態​

等待失敗時傳回：

nil, err, task

常見 err：

  • "cancelled"：使用者或腳本取消。
  • "expired"：後端任務過期。
  • "timeout"：腳本等待逾時，SDK 已嘗試撤銷任務。
  • "not found"：任務不存在，可能是後端重新啟動或任務已被清理。
  • 其他字串：網路、上傳截圖、後端介面傳回的錯誤文字。

只有 submitted 狀態會傳回 result。cancelled、expired、timeout 都應視為沒有拿到人工結果。