수동 지원
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: XXTouchImageObject입니다. SDK가 data URL로 변환하므로 먼저 파일로 저장할 필요가 없습니다.screenshotImageData: PNG/JPEG 이미지 바이너리 데이터입니다. SDK가 data URL로 변환합니다.input.imageSrc: 스크립트에 이미data:image/...,http(s)://...또는/api/...이미지 주소가 있으면input에 넣어 프런트엔드 표시용으로 그대로 전달할 수 있습니다.
SDK는 input.imageSrc를 덮어쓰지 않습니다. 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인 디렉터리도 호환 방식으로 정리합니다.