ZSeven-W/dsh-ios

DeepSeek Harness (DSH) plugin: a live iOS Simulator — and a USB-connected iPhone — inside the conversation. 22 agent tools for booting, building, driving the UI by accessibility identity, OCR text or list rows, plus a streaming sidebar panel you can tap and drag on.

DSH iOS 시뮬레이터 – AI 에이전트 기반 iOS 장치 보기

무엇인가요 – DeepSeek Harness (DSH) 대화 플랫폼용 플러그인 (@zseven-w/dsh-ios)으로, LLM 기반 에이전트(또는 사용자)가 채팅 창 내에서 iOS 시뮬레이터 또는 실제 iPhone 을 제어할 수 있게 합니다. 장치 화면은 지속적인 오른쪽 패널에 MJPEG 비디오로 스트리밍되며, 22개의 JSON 기반 에이전트 도구 (부팅, 빌드, UI 트리, OCR, 탭, 로그, SwiftUI 핫리로드 등)를 통해 모델이 장치를 안전하고 상호작용적으로 시각화하고 제어할 수 있습니다.

핵심 아이디어

아이디어	작동 방식
실시간 시각 피드백	시뮬레이터(또는 USB 연결된 iPhone)는 서명된 루프백 전용 URL(`/_dsh/dsh-ios/*`)을 통해 비디오를 스트리밍합니다. 브라우저는 시뮬레이터 포트에 직접 연결되지 않으며, 모든 바이트는 DSH 웹서버를 통해 프록시됩니다.
에이전트 친화적 도구	각 기능은 단순한 JSON 도구(예: `ios_sim_boot`, `ios_sim_interact`, `ios_sim_ui_tree`)로 노출됩니다. LLM은 도구를 호출하고 구조화된 출력을 얻어 다음 단계를 결정할 수 있어, 완전히 자율적인 UI 자동화가 가능합니다.
실기기 지원	실제 iPhone이 USB로 연결되면 플러그인은 전화기에서 WebDriverAgent 를 빌드하고 시작하며, USB-mux 루프백을 통해 제어 및 MJPEG 포트를 터널링하고, 동일한 UI 패널과 도구 세트를 재사용합니다.
안전 장치	모든 탭은 접근성 카운터, OCR 텍스트, 또는 명시적 `expect_*` 매개변수로 검증됩니다. 타겟이 유일하게 식별되지 않으면 실제 기기 탭은 차단됩니다.
SwiftUI 핫리로드	`ios_sim_preview` 는 일시적 호스트 앱을 생성하고 SwiftUI 미리보기를 dylib로 빌드한 후 실행 중인 시뮬레이터에 약 2~5초 내에 핫스왑하여, 에이전트가 UI 변경을 즉시 확인할 수 있게 합니다.

주요 기능 그룹

그룹	대표 도구	할 수 있는 일
장치 라이프사이클	`ios_sim_devices`, `ios_sim_boot`, `ios_sim_shutdown`	시뮬레이터 목록 확인, 시작/정지, 화면 스트리밍
앱 관리	`ios_sim_list_apps`, `ios_sim_launch_app`, `ios_sim_build_run`	설치된 앱 탐색, 실행, 또는 Xcode 프로젝트를 소스에서 빌드하여 시뮬레이터 또는 실제 전화기에서 실행
상호작용	`ios_sim_interact`, `ios_sim_tap_element`, `ios_sim_tap_text`, `ios_sim_find_text`, `ios_sim_tap_row`	접근성 식별자, OCR 검출 텍스트, 또는 리스트 행 좌표를 사용하여 탭, 입력, 하드웨어 버튼 누름, 스크롤, 제스처
UI 검사	`ios_sim_ui_tree`, `ios_sim_ui_rows`	접근성 계층 구조 덤프 또는 고수준 리스트 뷰(리스트 스타일 앱용 파싱된 카운터 포함)
진단	`ios_sim_logs`, `ios_sim_processes`, `ios_sim_backtrace`, `ios_sim_leaks`, `ios_sim_app_info`	통합 로그 추출, 프로세스 목록, 백트레이스 캡처, Xcode의 릭 탐지기 실행, 앱 번들 정보 쿼리
미리보기	`ios_sim_preview`	앱 재시작 없이 SwiftUI 미리보기 핫리로드
실기기 브리지	`ios_real_start_wda`	연결된 iPhone에서 WebDriverAgent 빌드 및 시작, 시뮬레이터와 동일한 제어 및 비디오 스트림 노출

시작 방법

npm 패키지 설치

npm i -g @zseven-w/dsh-ios   # 또는 프로젝트 종속성에 추가

DSH 세션 실행 – DeepSeek Harness(대화 UI를 실행하는 호스트)를 시작합니다. DSH 버전이 0.1.5-rc.1 이상이면 플러그인은 자동으로 탐지됩니다.
시뮬레이터 부팅 (예: JSON 도구 호출)
```
{ "tool": "ios_sim_boot", "args": { "udid": "iPhone-14-Simulator" } }
```
오른쪽 패널에 부팅된 장치의 실시간 MJPEG 뷰가 나타납니다.
상호작용 – ios_sim_interact 를 사용해 탭, 입력, 홈 버튼 누름, 또는 ios_sim_ui_tree 를 호출해 접근성 맵을 얻은 후 ios_sim_tap_element 로 레이블로 버튼을 누릅니다.
자신의 코드 실행 – ios_sim_build_run 으로 Xcode 프로젝트나 Swift 패키지 지정, 또는 ios_sim_preview 로 SwiftUI 미리보기 시작.
실제 iPhone – 전화기를 연결하고 UDID를 지정해 ios_real_start_wda 를 실행하면 동일한 상호작용 도구가 물리적 장치에서 작동합니다.

제한 사항 및 주의사항

macOS 전용 시뮬레이터 제어 – simctl/serve-sim 와 통신하는 도구는 Mac이 필요합니다. 다른 OS에서는 도구는 등록되지만 설명이 포함된 오류를 반환합니다.
USB 장치는 잠금 해제된 전화기 필요하며 사용자는 "탭 전 식별" 권한을 부여해야 합니다. 실기기의 모든 탭은 실수 조작을 방지하기 위해 검증됩니다.
루프백 전용 전송 – 모든 트래픽은 127.0.0.1 내에서만 유지됩니다. 추가 터널링 없이 네트워크를 통해 사용할 수 없습니다.
성능 – 실제 기기에서 깊은 접근성 스냅샷은 몇 초(제한 없이 최대 약 30초) 소요될 수 있습니다. 리스트 행 추출(ios_sim_ui_rows)도 유사하게 무겁습니다. 가벼운 도구(ios_sim_find_text, ios_sim_ui_tree에 낮은 깊이)를 먼저 사용하세요.
핫리로드 미리보기 – SwiftUI 미리보기 전용입니다. 일시적 호스트 앱을 ~/Library/Caches/dsh-ios 에 빌드하고 소스 파일을 감시합니다. 동시에 하나의 미리보기 세션만 가능.
보안 – 서명된 URL은 10분 후 만료됩니다. DSH 서버는 모든 요청에서 Host, Fetch-Metadata, HMAC을 검증합니다.

누구에게 적합한가요

iOS UI 테스트, 자동 UI 회귀 검사, 채팅 내에서 앱 동작을 시연해야 하는 LLM 기반 AI 에이전트.
SwiftUI 코드를 대화형 인터페이스로 반복할 때 개발자가 빠른 시각 피드백(시뮬레이터 또는 실제 기기)을 원하는 경우.
XCUITest 스크립트를 작성하지 않고 프로그래밍 가능한 JSON 기반 방식으로 iOS UI를 제어하고 싶은 QA 엔지니어.

빠른 참조 표 (선택 도구)

도구	주요 목적	핵심 인수
`ios_sim_devices`	사용 가능한 시뮬레이터 및 연결된 iPhone 목록	–
`ios_sim_boot`	시뮬레이터 시작 및 스트리밍 시작	`udid` (또는 장치 이름)
`ios_sim_interact`	일반적인 탭/제스처/키보드 작업	`action`, `x`, `y`, `text`, …
`ios_sim_ui_tree`	접근성 계층 구조 덤프	`udid`, `max_depth`, `filter`
`ios_sim_tap_element`	레이블/식별자로 요소 탭	`identifier` / `label`, 선택적 검증 플래그
`ios_sim_find_text`	현재 화면 OCR	`query`, `min_confidence`
`ios_sim_tap_row`	카운터 검증을 통해 리스트/피드 행 내 탭	`index`, `x`, `y`, `expect_count`
`ios_sim_preview`	SwiftUI 핫리로드 미리보기	`packagePath`, `action` (`start`/`status`/`stop`)
`ios_real_start_wda`	USB iPhone에서 WebDriverAgent 시작	`udid`

요약

DSH iOS 시뮬레이터 는 iOS 시뮬레이터 또는 실제 iPhone을 AI 에이전트가 간단한 JSON 호출로 시각화하고 제어할 수 있는 실시간 이미지 없는 시각 엔드포인트로 전환합니다. 모든 미디어를 서명된 루프백 URL 뒤에 두고 안전 검증된 상호작용 도구를 제공함으로써, 대화형 AI 워크플로우 내에서 자율적인 iOS UI 자동화를 현실로 만듭니다.