zhongerxin/iPhone-use

해결하는 문제

실제 iPhone을 손으로 제어하는 것은 느리고 반복적입니다. 이 프로젝트는 Codex, WorkBuddy 또는 豆包工作 같은 AI 코딩 어시스턴트가 USB를 통해 실제 iPhone을 작동할 수 있게 하여, 일반 언어로 작업을 설명하면 어시스턴트가 앱을 열고, 화면을 읽고, 탭하고, 스크롤하고, 입력을 자동으로 수행합니다. 또한 사이드바에 전화 화면을 표시하여 실시간 모니터링을 제공합니다.

작동 방식

이 프로젝트는 iPhone 자체에서 실행되는 오픈 소스 자동화 서비스인 WebDriverAgent(WDA)를 사용합니다. 어시스턴트는 로컬 MCP(모델 컨텍스트 프로토콜) 서버를 통해 WDA와 통신하며, 이 서버는 USB를 통해 명령을 전달하고 화면을 스트리밍합니다. 일회성 설정으로 Apple 계정과 Xcode를 사용하여 WDA를 휴대폰에 설치하고 서명합니다. 설정 후 어시스턴트는 18개의 도구를 호출하여 화면 검사, UI 요소 찾기, 탭, 스와이프, 텍스트 입력, 배치 작업, 실패 복구를 수행할 수 있습니다. 요소 위치 찾기가 실패하면 스크린샷을 보고 좌표로 탭하는 폴백으로 전환됩니다. 화면 미리보기 위젯은 어시스턴트의 사이드바에서 실행되며 직접 클릭, 드래그, 스크롤을 지원합니다.

대상 사용자

macOS에서 Codex, WorkBuddy 또는 豆包工作을 사용하고 USB로 연결된 실제 iPhone에서 작업을 자동화하려는 개발자와 고급 사용자. 전체 Xcode가 설치된 Mac, Python 3.9 이상, Node.js 및 npm, 서명용 Apple 개발자 계정, 개발자 모드가 활성화된 잠금 해제된 iPhone이 필요합니다.

주요 기능

• 로컬 USB 연결: 모든 트래픽은 Mac에 유지됩니다. 클라우드나 Appium 서버가 필요 없습니다.
• 기존 작업 재사용: 정상적인 WDA 세션과 이전 빌드를 재사용하여 반복 설정을 피합니다.
• 간결한 관찰 및 결합 작업: 제어 트리가 단순화되고 스크린샷은 필요할 때만 촬영되며 배치/스크롤/수집 도구가 어시스턴트 왕복을 줄입니다.
• 비동기 설정: 다운로드, 빌드, 시작은 쿼리 가능한 작업 ID를 반환하여 중복 시작을 방지합니다.
• 스크린샷 폴백: 요소 조회가 실패하면 시스템이 스크린샷을 반환하고 어시스턴트는 픽셀-포인트 변환으로 탭 지점을 선택합니다.
• 명확한 실패 의미론: 작업 잠금이 충돌 작업을 방지하고 모호한 결과는 표시되어 어시스턴트가 재시도 전에 실제 상태를 읽습니다.
• 일시 중지/재개가 있는 실시간 화면: 미리보기는 iPhone 셸, 상태, 제스처를 표시합니다. 사용자가 잠금 해제나 인증을 해야 하면 마스크가 화면을 덮고 자동으로 재개됩니다.