跳到主要内容

# 人工辅助

`LCC.assist` 用于让设备脚本向中控端发起人工辅助请求。脚本可以附带截图和说明文字，阻塞等待人工提交结果，然后继续执行。

## 请求类型​

类型 | API | 适合场景 | 脚本通常怎么处理
--- | --- | --- | ---
文本回复 | `LCC.assist.ask_text()` | 验证码、短信码、口令、一次性令牌 | 将 `result.text` 输入到当前输入框
选择坐标 | `LCC.assist.pick_point()` | 需要人工判断点哪里，例如图形按钮、异常弹窗按钮 | 直接 `touch.tap(result.x, result.y)`
人工远控 | `LCC.assist.request_control()` | 滑块、人机验证、登录、安全校验、权限弹窗等不稳定流程 | 等人工远控完成后重新截图继续判断

给操作人员看的说明要具体可执行，不要写“补充信息”这类抽象说明。建议写成“请远控完成当前验证后点击完成”“请输入截图里的验证码”“请点选确认按钮中心”。

## 截图来源​

辅助请求可以用多种方式带图：

- `screenshotLocalPath`：设备本地图片路径，SDK 会上传到中控 `files/_temp/assist/lua-script/<udid>/<request-id>/...`。
- `screenshotPath`：图片已经在中控 `files` 根目录下时，直接传相对路径。
- `screenshotImage`：XXTouch `ImageObject`，SDK 会转成 data URL，不需要先保存到文件。
- `screenshotImageData`：PNG/JPEG 图片二进制数据，SDK 会转成 data URL。
- `input.imageSrc`：脚本已经有 `data:image/...`、`http(s)://...` 或 `/api/...` 图片地址时，可放在 `input` 中透传给前端显示。

`input.imageSrc` 不会被 SDK 覆盖。未传 `input.imageSrc` 且未传路径截图时，SDK 才会把 `screenshotImage` 或 `screenshotImageData` 转成 `input.imageSrc`。

## 生命周期​

一个请求从 `pending` 开始，中控端打开工具后会变为 `active`，提交结果后变为 `submitted`。用户取消、脚本主动取消、等待超时或过期会进入 `cancelled` / `expired`。

脚本侧有两层清理：

- `LCC.assist.request()` 等待超时时，会撤销本次请求并返回 `nil, "timeout", task`。
- 脚本结束时，`XXTLanControl.lua` 会调用 `cancel_all()`，撤销当前脚本仍未完成的请求。

中控端收到某个设备脚本停止状态时，也会撤销该设备 `source = "lua-script"` 且仍处于 `pending` / `active` 的请求；不会取消其它设备的请求，也不会改动已提交的请求。

任务存储沿用中控当前的内存任务存储，后端重启后未完成任务不会保留。

如果请求使用 `input.imageSrc`、`screenshotImage` 或 `screenshotImageData` 传入内联图片，任务进入提交、取消或过期状态后，中控会释放内联图片内容，只保留任务状态、结果和其它结构化信息。

如果软件异常退出后重新打开，未完成任务本身不会恢复；启动时会清理脚本辅助请求上传到 `files/_temp/assist/lua-script/` 下的截图文件，也会兼容清理旧版本上传到 `files/assist/lua-script/` 或 `files/assist/<udid>/<request-id>/` 且请求 ID 为 UUID 的目录。

## API 列表​

- 通用参数与返回对象
- 创建人工辅助请求 `LCC.assist.create()`
- 等待人工辅助结果 `LCC.assist.wait()`
- 创建并等待请求 `LCC.assist.request()`
- 请求文本回复 `LCC.assist.ask_text()`
- 请求选择坐标 `LCC.assist.pick_point()`
- 请求人工远控 `LCC.assist.request_control()`
- 撤销指定请求 `LCC.assist.cancel()`
- 撤销当前脚本请求 `LCC.assist.cancel_all()`