<p align="center"><img src="https://raw.githubusercontent.com/kilolonion/agent-vscreen/HEAD/docs/logo.svg" width="96" alt="Agent-VScreen"></p>
Agent-VScreen
<p align="center">
<a href="https://github.com/kilolonion/agent-vscreen/releases/latest"><img src="https://img.shields.io/github/v/release/kilolonion/agent-vscreen" alt="최신 안정 버전"></a>
<a href="LICENSE"><img src="https://img.shields.io/github/license/kilolonion/agent-vscreen" alt="라이선스"></a>
<img src="https://img.shields.io/badge/Android-11%2B-3DDC84?logo=android&logoColor=white" alt="Android 11+">
<img src="https://img.shields.io/badge/root-not%20required-blue" alt="루트 불필요">
<img src="https://img.shields.io/badge/MCP-supported-8A2BE2" alt="MCP 지원">
</p>
모든 휴대폰 에이전트를 위한 배경 보조 화면입니다.
中文 · English
Agent-VScreen은 투명한 가상 디스플레이에서 다른 앱을 열고 구동하여, 사용자의 실제 화면은 그대로 유지되도록 합니다. 사용자에게 보이는 것은 AI가 무엇을 하고 있는지 보여주는 작은 플로팅 창뿐이며, 이 창은 언제든지 사용자가 직접 제어하거나 중지할 수 있습니다.
휴대폰의 모든 에이전트가 이를 사용할 수 있습니다: 터미널을 사용하는 에이전트는 vscreen CLI를 사용하고, MCP를 사용하는 에이전트는 MCP를 사용하며, 자체 코드는 일반 HTTP를 사용할 수 있습니다.
<p align="center"><img src="https://raw.githubusercontent.com/kilolonion/agent-vscreen/HEAD/docs/app.en.png" width="760" alt="Agent-VScreen Now, Connect, Records and Settings screens"></p>
<p align="center"><sub>앱의 기능: Now (배경 화면에서 에이전트가 수행하는 작업, 제어 또는 중지, 최근 실행), Connect (연결된 에이전트, 원격 액세스, 토큰), Records (모든 작업, 질문 및 단계별 썸네일이 포함된 계획 기록), Settings (누가 연결할 수 있는지, 에이전트가 얼마나 많은 작업을 할 수 있는지, 앱 규칙, 플로팅 창).</sub></p>
<p align="center"><img src="https://raw.githubusercontent.com/kilolonion/agent-vscreen/HEAD/docs/agents.png" width="860" alt="Minis, Eta, RikkaHub 및 Muse가 모두 vscreen을 통해 백그라운드 화면에서 포럼 앱을 구동하는 모습"></p>
<p align="center"><sub style="font-size: 1em;">하나의 설치 명령으로 네 가지 다른 Android 에이전트(Minis, Eta, RikkaHub, Muse)가 모두 연결되어 백그라운드 화면을 구동합니다.</sub></p>
<p align="center"><img src="https://raw.githubusercontent.com/kilolonion/agent-vscreen/HEAD/docs/demo.gif" width="760" alt="사용자가 메인 화면에서 웹 페이지를 스크롤하는 동안, 에이전트가 백그라운드 화면에서 시계(Clock)를 열고 10분 타이머를 시작하며, 플로팅 창에 이를 실시간으로 미러링합니다."></p>
<p align="center"><sub style="font-size: 1em;">백그라운드에서: 에이전트가 백그라운드 화면에 시계(Clock)를 열고, 10분 타이머를 설정하고 시작하는 동안 사용자는 Chrome에서 계속 읽기를 합니다. 터미널에는 실제 <code class="vscreen">vscreen</code> 명령(대기 시간은 6배속으로 처리됨)이 표시됩니다. <a href="docs/promo/background.mp4?raw=true">MP4 다운로드</a></sub></p>
<p align="center"><img src="https://raw.githubusercontent.com/kilolonion/agent-vscreen/HEAD/docs/takeover.gif" width="760" alt="사용자가 플로팅 창을 길게 눌러 백그라운드 화면 제어권을 가져가 스크롤하고 탭한 후, 다시 에이전트에게 넘겨주면 에이전트가 작업을 계속합니다."></p>
<p align="center"><sub style="font-size: 1em;">언제든지 제어권 확보: 플로팅 창을 길게 눌러 백그라운드 화면을 직접 구동하고, 다시 에이전트에게 넘겨주면 에이전트가 화면을 재인식하여 작업을 계속합니다. <a href="docs/promo/takeover.mp4?raw=true">MP4 다운로드</a></sub></p>
<p align="center"><img src="https://raw.githubusercontent.com/kilolonion/agent-vscreen/HEAD/docs/tour.gif" width="760" alt="앱의 'Now', 'Connect', 'Records', 'Settings' 탭 둘러보기"></p>
<p align="center"><sub style="font-size: small;">에이전트가 작동하는 동안의 앱 둘러보기. <a href="docs/promo/tour.mp4?raw=true">MP4 다운로드</a></sub></p>
<p align="center"><sub style="font-size: small;">세 개의 MP4에는 음악이 포함되어 있으며, 34초 분량의 조합된 영상(combined cut)이 있습니다. 음악: Kevin MacLeod (incompetech.com)의 "Wallpaper", <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a> 라이선스 적용.</sub></p>
main 브랜치 버전: 1.4.2-beta3 (versionCode 54) · 베타 APK · 최신 안정화 APK
- 패키지:
com.kilon.agentvscreen
- Android 11 이상 (Android 14 이상 권장), arm64
- 권한: 기본적으로 Shizuku 사용 (루트 필요 없음) 또는 이미 루트된 휴대폰에 대한 직접적인 루트 접근
기능 소개
- 백그라운드에서 앱 구동: 배경 화면에서 앱을 열고, 탭하고, 스와이프하고, 타이핑하고, 키를 누른 다음 화면 변화를 기다립니다. 모든 단계가 확인되며, 작동하지 않은 단계는 실행을 중단하고 현재 화면에 표시되는 내용을 알려줍니다.
- 에이전트에게 화면 전달: 모든 응답은 현재의 화면(화면에 있는 단어, 탭 가능한 요소 및 스크린샷)을 포함합니다. 앱은 어떤 AI 모델도 호출하지 않으며, 에이전트 자체 모델이 화면의 의미를 결정합니다.
- 대기 및 관찰: 동작 후 단어가 나타나거나 사라지거나, 또는 화면이 안정될 때까지 기다릴 수 있습니다. 턴(turn) 이후에는 계속 관찰하며 조건이 발생하면 사용자에게 알리거나 에이전트를 깨울 수 있습니다.
- 사용자와 협업: 에이전트는 사용자에게 화면의 특정 부분을 가리키도록 요청할 수 있습니다(
ask) 또는 한 번 보여주고 이를 학습으로 유지하도록 할 수 있습니다(teach); 비밀번호나 코드가 필요한 단계는 사용자의 자체 화면으로 이동합니다.
- 플로팅 창(Floating window): 테두리는 누가 화면을 가지고 있는지 표시합니다(무지개색: AI가 작동 중, 파란색: 대기 중, 녹색: 사용자가 장악, 빨간색: 중단됨). 드래그하여 이동하고, 핀치하여 크기를 조정하며, 가장자리로 플링(fling)하여 탭으로 접을 수 있습니다. 사진을 0.5초 동안 길게 누르면 장악할 수 있으며, 전체 화면을 열어 자체 키보드로 타이핑할 수 있습니다.
- 사용자의 도구는 건드리지 않음: 앱은 adb를 장악하거나 무선 디버깅을 변경하지 않으므로, 에이전트 자체의 adb 또는 Shizuku가 계속 작동합니다.
에이전트가 할 수 있는 작업
이 목록과 에이전트가 받는 메모는 하나의 능력 테이블(Abilities.kt)에서 오며 테스트를 통해 작성되었으므로 수동으로 편집하지 마십시오.
- 사용자가 휴대폰에서 원하는 모든 작업(앱 열기, 정보 검색, 페이지 읽기, 양식 작성, 앱 테스트 등)을 할 때:
vscreen launch <app>은 앱을 열고 내용을 확인하며, vscreen act "<steps>"는 탭, 스와이프, 타이핑 및 키 입력을 수행합니다. 모든 응답에는 스크린샷과 요소가 포함됩니다.
- 휴대폰을 사용하는 시간 기반 작업(사용자가 매일 또는 8시에 요청하는 체크인/주기적 확인, 또는 사용자가 설정한 타이머, cron 또는 알림): 둘 다 설정할 수 있습니다. (타이머는 휴대폰이 아닌 나를 깨웁니다.)
vscreen schedule "<when>" --name <name>으로 같은 시간을 예약하고, 둘 다 한 번에 변경하거나 취소할 수 있습니다.
- 나중에 발생할 일(재입고, 가격 하락, 답장, 다운로드 완료 등)이나 잠시 후 다시 확인하고 싶을 때:
vscreen act --stop "text:In stock" --keep notify는 휴대폰이 계속 감시하며 발견 시 사용자에게 알림을 보냅니다. (--keep wake는 나를 깨우고; vscreen events로 가져올 수 있습니다.)
- 긴 목록이나 전체 페이지를 읽어야 할 때(모든 주문 내역, 채팅 기록, 검색 결과, 댓글):
vscreen collect --pages 10을 사용하여 페이지별로 이동하며 모든 항목을 한 번씩 반환합니다.
- 사용자 의도가 화면의 어떤 것(어떤 항목, 버튼, 메시지)인지 불분명하거나 사용자가 하나를 선택해야 할 때:
vscreen ask "Which one do you mean?"은 사용자가 휴대폰 화면 이미지에서 직접 탭할 수 있게 합니다. (--choose, --text도 가능합니다.)
- 흐름을 설명하기 어렵거나, 계속 실패하거나, 사용자가 더 잘 아는 경우:
vscreen teach "what to show"는 사용자에게 화면에서 한 번 수행하도록 요청하며, 이는 세그먼트로 저장됩니다. 이후 act "use <name> <values>"로 이를 재생합니다.
- 동일한 앱이 반복적으로 나타나는 경우(고정된 진입 방식, 방문 시마다 팝업, 먼저 일시 중지해야 하는 이미지, 또는 기계적인 타이밍으로 인해 흐트러지는 경우):
vscreen note는 앱에 대해 내가 배운 것들(저장된 단계(note save), 전/후 단계 및 인간의 속도 조절)을 기억합니다. 다음 실행 시 이를 목록으로 보여줍니다.
• 사용자만 할 수 있는 단계(비밀번호, 코드, 얼굴 인식, 스캔)이거나 사용자가 현재 사용하는 앱인 경우: vscreen handoff out은 수행할 작업을 사용자 화면에 앱으로 표시하고; vscreen handoff in은 사용자 화면에서 앱을 가져옵니다.
• 앱에 소리가 없거나, 사용자가 앱의 소리를 음소거하거나 다시 활성화하려는 경우: vscreen sound는 이를 보여주며, sound mute|unmute <app>은 음소거 또는 음소거 해제 기능을 수행합니다.
• 앱 전환 또는 보관(Park)하기: vscreen tasks는 작업을 목록으로 표시하고; launch --keep은 재실행 없이 전환하며; handoff park/unpark는 앱을 따로 보관하거나 복원합니다.
• 텍스트가 너무 작거나 아이콘이 있거나, 아예 텍스트가 없는 경우(게임, 캔버스, 차트), 또는 방금 무슨 일이 일어났는지 보고 싶은 경우: vscreen look은 사진을 요청합니다. (현재 화면, 근거리 영역, 또는 녹화본); vscreen spots는 터치 가능한 색상 패치를 찾습니다.
• 휴대폰에 접근할 수 없거나, 명령이 계속 실패하거나, 이상한 일이 발생하는 경우: 고장으로 인한 첫 번째 경고 메시지부터 시작합니다. 실행되지 않음, 서비스 비활성화 또는 숨김은 사용자의 선택입니다. 사용자에게 앱을 열도록 지시하며, 수정할 것은 없습니다. vscreen status가 ready false인 경우만이 오류이며, vscreen fix는 나열된 항목을 수리하고 음소거되었던 앱에 소리를 되돌려줍니다.
<!-- abilities:end -->
백그라운드 화면에서 앱 전환하기
vscreen tasks를 사용하여 패키지 이름, 작업 ID, 그리고 어떤 앱이 전면에 있는지 확인합니다. vscreen launch <app> --keep은 기존 작업을 재시작하지 않고 앞으로 가져옵니다. 만약 해당 앱이 화면에 없다면, 새로운 작업을 엽니다.
vscreen handoff park <app>을 사용하여 앱 작업을 숨겨진 디스플레이에 배치하고, vscreen handoff unpark <app>을 사용하여 이를 전경으로 다시 가져옵니다. 보관된 작업은 tasks에서 표시되지 않습니다. 만약 보관된 앱이 여전히 현재 목표라면, 다른 앱을 복원하거나 선택할 때까지 look과 act는 APP_PARKED를 반환합니다. 종료(완료 또는 비활성), 중지, 그리고 사용자 인계가 보관된 작업을 닫습니다. 보관은 영구적이지 않습니다.
작동 원리
- 시간 감지(A sense of time): 에이전트가 작동하는 동안 화면은 초당 약 5번 관찰되고, 타임스탬프와 함께 초당 약 1번 읽힙니다. 각 응답의 [Meanwhile] 섹션은 마지막 응답 이후(에이전트가 생각하는 시간 포함) 무엇이 나타나거나 사라지거나 깜빡였는지, 화면이 어디서 얼마나 오랫동안 바뀌었는지를 알려줍니다. 카운트다운, 로딩, 팝업도 놓치지 않습니다.
- 명확한 시야 확보(Seeing clearly): 접근성 트리(accessibility tree)와 온디바이스 OCR (PP-OCRv6, ML Kit 포함)이 좌표가 지정된 요소의 단일 번호 목록으로 병합됩니다.
tap #N과 tap <화면의 단어> 모두 작동합니다. look은 특정 영역을 확대하거나 녹화를 재생하며, collect는 전체 페이지를 스크롤하여 모든 항목을 한 번에 수집합니다.
- 단일 단계 언어(One step language): 스크립트, 저장된 세그먼트 및 레슨에서 공유되는
try, if, repeat … until, 와일드카드(*), 그리고 두 번째 위치를 위한 words@2 등의 언어를 지원합니다. 각 앱은 메모와 저장된 단계를 유지하며, 다음에 열릴 때 목록으로 표시됩니다.
- 다수의 에이전트, 충돌 없음(Many agents, no mix-ups): 연결된 모든 에이전트는 자체 토큰과 기록을 가집니다. 하나의 세션이 한 번에 화면을 점유하며 다른 세션은
BUSY 상태가 됩니다. 앱은 차단되거나 읽기 전용으로 설정할 수 있으며, 결제 단계는 휴대폰에서 사용자가 확인하기를 기다립니다.
- 모든 모델 지원(Any model): 아무것도 모델을 전화기에서 실행하지 않으므로, 모든 에이전트와 모든 모델이 이를 사용할 수 있습니다.
설치 (Install)
<p align="center"><a href="docs/promo/tutorial.en.mp4?raw=true"><img src="https://raw.githubusercontent.com/kilolonion/agent-vscreen/HEAD/docs/tutorial.en.png" width="760" alt="시작하기 비디오: 접근 권한 부여, 에이전트 연결, 첫 작업 할당, 제어권 인수, 수행 내용 검토"></a></p>
<p align="center"><sub style="font-size: smaller;">시작하기 비디오 (영어 UI 및 음성 해설, 2분 미만): 접근 권한 부여부터 에이전트의 첫 작업까지. <a href="docs/promo/tutorial.en.mp4?raw=true">MP4 다운로드</a></sub></p>
- APK를 설치하고 Agent-VScreen을 실행합니다.
- **설정(Setup)**에서 하나의 권한 소스를 선택합니다:
- Shizuku (기본값): Shizuku를 시작한 다음, **Shizuku 권한 부여(Grant Shizuku)**를 탭합니다. 휴대폰 재부팅 후에는 Shizuku를 다시 시작해야 합니다.
- 루트(Root): 휴대폰이 이미 루팅된 경우, **루팅됨? 대신 루트 사용(Rooted? Use root instead)**을 탭하고 루트 관리자의 프롬프트를 승인합니다. Shizuku 설치는 필요하지 않습니다. 나중에 **설정(Settings) › 권한 소스(Permission source)**에서 전환할 수 있습니다. 전환 시 현재 백그라운드 화면이 닫힙니다.
- 오버레이(overlay), 알림(notifications), 읽기 전용 접근성(read-only accessibility), 배터리 최적화(battery optimization), 백그라운드 실행을 위해 **원탭 설정(One-tap setup)**을 탭합니다. Honor, Huawei, Xiaomi, OPPO, vivo 및 유사한 휴대폰의 경우, 백그라운드 관리도 열고 자동 시작 및 백그라운드 활동을 허용해야 합니다. 그렇지 않으면 시스템이 앱을 백그라운드에서 동결시킬 수 있습니다.
앱은 중국어와 영어(설정에서 System / 中文 / English)를 사용하며, 에이전트에게 알려주는 모든 것도 마찬가지입니다.
다운로드된 APK 확인하기
설치하기 전에 Android SDK Build Tools에서 apksigner를 실행합니다. downloaded.apk를 사용자의 APK 경로로 대체하십시오:
apksigner verify --print-certs downloaded.apk