跳到主要内容

# 通用参数与返回对象

本页说明 `LCC.assist` 系列 API 共用的 `options`、任务对象、结果对象和错误状态。

## options 字段​

字段 | 类型 | 默认值 | 说明
--- | --- | --- | ---
`type` | string | `"text"` | 请求类型。`"text"`/`"text-reply"`、`"point"`/`"pick-point"`、`"control"`/`"device-control"` 都可识别。便捷封装会自动设置。
`title` | string | `"脚本请求人工辅助"` | 中控端卡片标题。
`text` / `prompt` | string | `""` | 给操作人员看的说明。应写具体操作，不要写“补充信息”。
`timeout` | number | `300` | 等待秒数；创建任务时也会作为后端过期时间。
`pollIntervalMs` | number | `1000` | 轮询间隔毫秒；小于 `250` 会按 `250` 处理。
`screenshotLocalPath` | string |  | 设备本地截图文件，SDK 会上传到中控 `files/_temp/assist/lua-script/<udid>/<request-id>/...`。
`screenshotPath` | string |  | 已在中控 `files` 根目录下的图片相对路径。
`screenshotImage` / `image` | ImageObject |  | XXTouch 图片对象。SDK 会导出为 data URL 并写入 `input.imageSrc`。
`screenshotImageData` / `imageData` | string |  | PNG/JPEG 图片二进制数据。SDK 会转成 data URL 并写入 `input.imageSrc`。
`screenshotImageFormat` / `imageFormat` | string | `"jpeg"` | `screenshotImage` 的导出格式，可选 `"jpeg"` 或 `"png"`。
`screenshotImageQuality` / `imageQuality` | number | `0.7` | `screenshotImage` 导出为 JPEG 时的质量，范围 `0.0` 到 `1.0`。
`screenshotImageMimeType` / `imageMimeType` | string | 自动识别 | `screenshotImageData` 的 MIME 类型；PNG/JPEG 数据通常不需要传。
`imageRect` | table |  | 裁剪图映射回设备坐标时使用，例如 `{ left = 100, top = 200, width = 300, height = 120 }`。
`input` | table | `{}` | 额外结构化信息，会透传给中控端。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` 都应视为没有拿到人工结果。