iphone-cli 0.1.8

Let AI agents read and operate any app on a real iPhone through the accessibility tree. No XCUITest, WebDriverAgent or Xcode signing.
Documentation
# 동작 원리

현재 구현의 연결·읽기·입력 경로를 설명합니다. 명령 사용법은 [README](../README.ko.md), 준비와 점검은 [onboarding.md](onboarding.md)에 있습니다. 접근성 속성 번호와 입력 대기 시간은 iOS 버전에 따라 달라질 수 있습니다.

## 1. 터널과 상주 프로세스

CLI와 MCP는 폰별 상주 프로세스(`iph daemon`)에 요청합니다. 상주 프로세스는 첫 요청 때 자동으로 시작하며, 터널·접근성 구독·입력 세션을 유지하고 요청을 차례대로 처리합니다. 통신에는 macOS의 유닉스 소켓, Windows의 named pipe를 씁니다.

```text
USB: Apple usbmuxd 전송
Wi-Fi: 발견·저장 주소 → 직접 TCP + iph heartbeat
  → lockdown → CoreDeviceProxy → CDTunnel
  → 사용자 공간 TCP 스택 → RSD(서비스 목록)
```

루트 권한이나 호스트의 터널 인터페이스 없이 연결하며, 서비스 포트는 RSD에서 이름으로 찾습니다. USB 전송과 페어링 기록은 Apple 서비스에서 얻습니다. Wi-Fi는 Apple 목록의 주소와 마지막으로 검증한 저장 주소 모두 같은 직접 TCP 경로를 사용합니다. IPv6 링크 로컬 주소의 인터페이스 범위도 보존합니다. 목록 조회가 실패해도 선택한 UDID의 저장 주소를 시도하며, TLS 페어링 세션의 UDID가 일치하고 heartbeat에 응답한 뒤 개발자 서비스를 엽니다. 연결 준비 실패는 다음 후보로 넘어갈 수 있지만 사용자 명령을 재실행하지 않습니다. USB가 기본 우선이고 `IPH_PREFER=wifi`이면 Wi-Fi 후보가 우선입니다.

`[daemon] idle_exit_secs`의 기본값은 1800초입니다. macOS의 상태 파일은 `~/Library/Application Support/iph/`, Windows는 `%LOCALAPPDATA%\iph\`에 저장합니다.

구현: [daemon.rs](../src/daemon.rs), [conn.rs](../src/device/conn.rs), [config.rs](../src/config.rs).

## 2. 화면 읽기

`com.apple.accessibility.axAuditDaemon.remoteAXService`에 DTX로 연결하고 `clientNeedsAccessibility:`를 보내면 `processDataFromRemoteDevice:`로 화면 덤프가 옵니다.

- 첫 덤프(`AXPTreeDumpTypeInitialDump`)에는 이름표·위치·역할·특성·값·힌트가 있습니다. 추가 덤프(`AXPTreeDumpTypeAdditionalData`)에는 식별자 등이 포함됩니다. `read --full`은 추가 덤프를 기다립니다.
- 응답은 즉시 오지 않습니다. 요청을 자주 보내면 폰의 덤프 대기가 다시 시작되므로 한 번 요청한 뒤 기다리고, 6.5초 동안 응답이 없을 때 다시 요청합니다.
- 요청 후 0.7초 안에 도착한 덤프는 이전 요청의 응답이나 자발적인 덤프일 수 있어 새 응답으로 쓰지 않습니다.
- 탭 뒤에는 기본 0.48초 기다렸다 화면을 요청합니다. 최근에 자발적인 덤프가 왔거나 여러 번 누르기·글 입력을 수행한 경우에는 다시 읽어 화면을 비교합니다.
- 탭 대상 확인에는 최근 화면을 재사용할 수 있습니다. 1.5초가 넘고 10초 이내인 화면은 요소별 질문으로 보이는 자식과 대상 위치를 확인하고, 맞지 않거나 응답이 없으면 전체를 다시 읽습니다.
- 스크립트·batch의 탭은 대상 위치가 멈췄는지 확인합니다. `readField`는 값을 추가로 읽어 비교합니다.

요소별 질문은 `processDataFromHost:`로 보내며 전체 덤프를 기다리지 않고 속성이나 위치를 확인하는 데 씁니다.

### 덤프 형식과 속성

덤프는 `bplist00` NSKeyedArchive 두 겹입니다. 바깥 `NSMutableData`의 바이트를 다시 풀면 `AXPTranslatorResponse`와 `treeDump`를 얻습니다. 요소는 `(pid, objectID)`로 구분하고 자식 속성으로 트리를 잇습니다.

| 번호 | 뜻 |
|---|---|
| 3 / 33 | 이름표 / 일반 문자열 이름표 |
| 8 / 9 | 전체 자식 / 보이는 자식 |
| 21 | 논리 포인트 위치 `{{x, y}, {w, h}}` |
| 23 | 힌트 |
| 25 | 접근성 식별자 |
| 45 | 역할 번호 |
| 53 | 값 |
| 77 | `UIAccessibilityTraits` 비트 |

`enabled`, `selected`, `focused`는 각각 비활성·선택·편집 특성에서 계산합니다. 알 수 없는 속성은 `iph read --raw`에서 확인할 수 있습니다. 계산기 표시 창처럼 값이 식별자에 들어가는 요소도 있습니다.

기본 출력에서는 화면과 겹치지 않는 요소를 뺍니다(`--all`로 포함). 앱이 화면 밖 행을 트리에 넣지 않는 경우에는 `scroll --until`로 찾아야 합니다. 아카이브 해석에는 객체 확장 횟수 상한을 두고, 파싱은 비동기 실행 스레드 밖에서 수행합니다.

구현: [ax.rs](../src/device/ax.rs), [session.rs](../src/device/session.rs), [attrs.rs](../src/ax/attrs.rs), [archive.rs](../src/ax/archive.rs).

## 3. 터치·키보드·버튼

합성 HID 입력을 받게 하려면 `displayservice`의 화면 공유 미디어 세션이 필요합니다. 기본은 오디오 스트림만 열고 받은 패킷을 버립니다. `[daemon] screen_video = true`이면 영상도 받습니다. 통화·녹화 등으로 오디오가 거부되는 오류 9022가 오면 영상 스트림으로 전환합니다.

- 터치는 `hid.universalhidservice`로 보냅니다. 논리 포인트를 화면 크기에 따라 0~65535로 정규화합니다.
- 세션을 열 때는 터치 연결 하나만 맺고, 키보드와 버튼 연결은 처음 쓸 때 만듭니다.
- 새 HID 연결의 장치 목록 응답을 기다린 뒤 기본 0.3초 준비 시간을 둡니다. 폰이 터치 장치를 열기 전에 받은 보고를 한꺼번에 내보내는 일을 줄이기 위한 대기입니다. 첫 보고에는 손가락을 대지 않은 '뗌' 보고를 씁니다.
- 미디어 스트림의 첫 패킷도 기다립니다. 2.5초 동안 패킷이 없으면 세션을 다시 엽니다.
- 기본 탭은 닿음 → 50ms → 뗌입니다. 다음 터치와는 최소 150ms 간격을 둡니다.
- `scroll`과 감속 끌기는 끝에서 속도를 줄이고 멈춘 뒤 떼어 관성을 줄입니다. 일반 `swipe`는 일정 속도로 밀어 관성을 남깁니다.
- `pinch`는 같은 터치 장치에 손가락 둘(식별자 0과 1; 한 손가락 터치는 2)을 한 보고에 담아 보냅니다. 좌표는 포인트로 계산한 뒤 축마다 따로 정규화해서 세로로 긴 화면에서도 원이 찌그러지지 않습니다. 시작에 두 손가락을 함께 대고 40ms 쉰 뒤 움직이고, 끝에서 멈춘 채 몇 번 더 보내고 뗍니다. 보고 하나가 실패해도 두 손가락을 반드시 뗍니다.
- 하드웨어 버튼은 `hid.indigo`, 키보드는 universal HID의 임시 키보드로 보냅니다. 임시 키보드를 등록한 뒤 첫 키까지 0.7초 기다리며, 등록된 동안 화면 키보드는 내려갑니다.

`[daemon] input_idle_secs`의 기본값은 120초이며, 입력이 없으면 미디어 세션을 닫습니다. 0이면 명령마다 닫습니다.

구현: [input.rs](../src/device/input.rs), [actions.rs](../src/actions.rs), [session.rs](../src/device/session.rs).

## 4. 글 입력과 클립보드

1. 키보드가 올라온 입력 칸을 하나 찾습니다. 없거나 여러 개면 보내지 않습니다.
2. 입력 세션을 준비하고, 클립보드 보관과 임시 키보드 등록을 진행합니다.
3. 입력할 글을 클립보드에 넣고 ⌘V로 붙여 넣습니다. `--clear`이면 먼저 ⌘A와 삭제를 보냅니다.
4. 칸의 값을 요소별 질문으로 읽고, 응답이 없으면 전체 화면을 읽습니다. 동시에 클립보드 복원을 시도합니다.
5. `--submit`이고 입력 효과에 관측 경고가 없으면 Return을 보냅니다. 경고가 있으면 Return을 보류하고 `unknown` / `type_not_verified`로 반환해 스크립트와 batch를 멈춥니다. 임시 키보드는 두 경우 모두 제거합니다.
6. 입력 전과 임시 키보드를 제거한 후의 접근성 트리를 비교해 `screen_changed`를 보고합니다. 비교할 화면을 읽지 못하면 `null`입니다.

결과의 `value_before`와 `value`는 원래 칸의 입력 전과 입력 후(Return 전) 값입니다. `""`은 읽을 수 있는 빈 문자열, `null`은 읽기 불가이며 값의 공백을 보존합니다. 다른 칸에 포커스가 옮겨가도 그 값을 대신 보고하지 않습니다. 앱이 서식·가림·자동 고침을 적용할 수 있으므로 입력 문자열과 같다고 판정하지 않습니다. `verified`는 기존처럼 입력 후 칸 값을 읽었는지를 나타내며, `value_changed`는 두 값을 비교할 수 있으면 `true` · `false`, 없으면 `null`입니다.

값 불변·읽기 불가·빈 결과 등은 `warning: {code, message, hint}`로 알립니다. 붙여넣기 권한이 원인일 수 있지만 관측만으로 확정하지 않습니다. `--submit`이 없으면 경고가 있어도 명령 완료(`ok: true`, `outcome: "done"`)를 유지합니다. 자동 재입력은 중복 입력을 일으킬 수 있으므로 하지 않습니다. 같은 글의 `--clear --submit`도 제출을 보류하지만, 지우기만 하는 명령은 빈 값을 읽으면 제출할 수 있습니다. 모든 필드와 경고의 의미는 [README](../README.ko.md#결과)에 있습니다.

클립보드는 서비스가 직접 가진 일반 텍스트나 그림만 보관합니다. 앱에서 복사한 서식 있는 내용처럼 바이트를 별도로 요청해야 하는 형식은 읽기가 멈출 수 있어 보관하지 않습니다. 복원할 수 없으면 입력 뒤 클립보드를 비우고 `clipboard_restored: false`와 `clipboard_note`로 알립니다. 그 사이 사용자가 다른 내용을 복사했으면 덮어쓰지 않습니다.

구현: [actions.rs](../src/actions.rs).

## 5. 앱·스크립트·목록

앱 실행은 `appservice`의 `launchapplication`, 목록은 `streamapplist`를 씁니다. 실행 후 화면에서 해당 pid가 앞에 나왔는지 확인합니다. 스크린샷은 `screencaptureservice`에서 PNG로 받습니다.

스크립트는 내장 QuickJS에서 실행합니다. 개인 스크립트를 기본 예제보다 먼저 찾고, 파일·네트워크·다른 프로세스에 접근하는 기능은 제공하지 않습니다. 실행 시간과 메모리는 `[script] timeout_secs`(기본 300초)와 `memory_mb`(기본 64MB)로 제한합니다.

`launch` 뒤 다른 앱이 앞에 나오면 스크립트·batch의 입력과 필드·목록 읽기는 `unexpected_app`으로 멈춥니다. 입력 결과가 `unknown`인 호출 뒤에는 예외를 잡아도 다음 호출을 보내지 않습니다.

`readList`는 화면 사이의 겹치는 행으로 목록을 잇습니다. 읽는 동안 글자가 바뀌는 행은 `key`로 식별할 칸을 지정합니다. 끝 확인에서는 마지막 행 너머의 행만 추가하고, 앞뒤 화면을 맞출 수 없으면 다시 읽은 뒤 `list_uncertain`으로 실패합니다.

구현: [script.rs](../src/script.rs), [steps.rs](../src/steps.rs), [actions.rs](../src/actions.rs).

## 6. 연결과 화면 읽기 복구

Wi-Fi heartbeat의 종료·SleepyTime·응답 시간 초과를 관측하면 캐시된 터널·접근성·입력 세션을 폐기합니다. 다음 요청에서 다시 연결하고, 스크립트·batch에 기억된 실행 앱은 새 화면으로 확인합니다. 다만 이미 나갔을 수 있는 입력은 자동으로 재전송하지 않습니다. `outcome: "unknown"`이면 현재 화면을 확인해야 합니다.

화면 읽기 서비스가 응답하지 않거나 빈 덤프만 보내면 `[daemon] restart_accessibility`에 따라 `axauditd`를 종료하고 새 서비스로 읽기를 시도합니다. 기본은 켜져 있으며, 재시작 간격은 최소 2분입니다. 빈 덤프만 오는 경우에는 먼저 잠금 상태를 확인합니다.

마지막 화면이 홈 화면·제어 센터 같은 시스템 화면이면 서비스를 종료하지 않습니다. 재시작이 실패했거나 도움이 되지 않았을 때도 다음 읽기가 성공할 때까지 재시작을 반복하지 않습니다.

화면 녹화 중에는 제어 센터 읽기가 응답하지 않을 수 있습니다. 이때는 `iph button home`으로 닫거나 `iph launch`로 앱을 앞으로 가져온 뒤 다시 읽습니다. 폰이 잠겼다고 확인된 경우를 제외하면, 화면 읽기가 `ax_timeout`으로 실패해도 좌표 탭·좌표 밀기·버튼을 마지막 화면 크기로 보낼 수 있습니다. 결과에는 `verified: false`와 `note`가 붙습니다. 이름표 탭은 화면 읽기가 필요합니다.

구현: [session.rs](../src/device/session.rs), [actions.rs](../src/actions.rs).

## 7. 방해금지 모드

`iph dnd on|off|status`는 제어 센터의 집중 모드 항목을 조작합니다. 일반 명령과 스크립트는 방해금지 모드를 자동으로 바꾸지 않습니다.

- 화면 오른쪽 위에서 감속 끌기로 제어 센터를 열고, 집중 모드 항목을 길게 눌러 모드 목록을 엽니다.
- `on`은 방해금지 모드를 선택합니다. 바꾸기 전에 이전 집중 모드를 파일에 저장합니다.
- `off`는 기록된 집중 모드로 되돌립니다. 기록은 상주 프로세스가 종료되어도 남습니다.
- `status`도 제어 센터를 열어 현재 상태를 읽은 뒤 닫습니다.
- 제어 센터 첫 페이지에 집중 모드 항목이 있어야 합니다. 한국어·영어 이외의 이름은 설정의 `[dnd] control`과 `focus`로 지정합니다.

알림 배너는 앱의 접근성 트리에 나오지 않아 탭을 가로챌 수 있습니다. 방해금지 모드에서도 허용된 알림·알람·시스템 팝업은 남을 수 있습니다. 전환이 실패하면 `control_center: "may still be open"`이 반환될 수 있으므로 화면을 확인합니다.

구현: [dnd.rs](../src/dnd.rs).