awesome-ios-sim

简体中文 · MCP 가이드 · DeepSeek Harness · 아키텍처

iOS 개발자, CI 파이프라인 및 AI 에이전트를 위한 시뮬레이터 상태를 코드로 관리합니다.

awesome-ios-sim은 iOS 시뮬레이터 설정을 캡처, 비교(diff), 계획, 검토 및 안전하게 적용할 수 있는 버전 관리 프로필로 변환합니다. 결정론적 CLI와 MCP stdio 서버를 모두 제공합니다. 또한 DeepSeek Harness용 dsh-plugin 번들로 설치할 수 있습니다.

프로젝트 상태: 알파. 상태 스키마는 v1alpha1입니다. 생성된 계획을 적용하기 전에 검토하세요. 특히 erase 또는 앱 제거 작업이 포함된 계획은 주의하세요.

존재 이유

시뮬레이터 자동화는 일반적으로 셸 스크립트, 문서화되지 않은 기본값, 수동 설정에 의존합니다. 이로 인해 테스트 환경을 재현하기 어렵고 AI 에이전트에게 안전하지 않고 타입이 없는 셸 표면을 제공합니다.

이 프로젝트는 하나의 워크플로를 도입합니다:

profile + current snapshot -> diff -> deterministic plan -> explicit confirmation -> audited apply

• 선언적: 시뮬레이터 프로필을 테스트 및 애플리케이션 코드 옆에 커밋합니다.

• 검토 가능: 변경 전에 정확한 순서의 작업 계획을 검사할 수 있습니다.

• 에이전트 안전: MCP 도구는 JSON Schema와 simulator_apply 기본값을 사용하여 드라이런(dry-run)합니다.

• 기능 인식: 정확(exact), 최선(best-effort), 미지원(unsupported) 상태가 명시적으로 보고됩니다.

• 공개 API만 사용: 변경은 Apple의 xcrun simctl을 통해 이루어지며, 비공개 CoreSimulator 프레임워크는 사용하지 않습니다.

• 로컬 우선: 데몬, 클라우드 계정, 텔레메트리, API 키가 없습니다.

Related MCP server: Shotter

아키텍처

flowchart LR
    P[State profile] --> E[Pure Swift state engine]
    S[Live or saved snapshot] --> E
    E --> D[Diff]
    E --> PL[Ordered plan]
    PL --> C{Explicit confirm?}
    C -- No --> DR[Dry-run report]
    C -- Yes --> X[Typed simctl driver]
    X --> J[Execution receipts]
    CLI[CLI] --> E
    MCP[MCP stdio server] --> E

상태 엔진은 Xcode 의존성이 없으며 픽스처로 테스트됩니다. SimctlDriver만 호스트 프로세스 경계를 건드립니다. CLI와 MCP 서버는 동일한 플래너, 검증 및 적용 게이트를 공유합니다.

요구 사항

• macOS 13 이상.

• Swift 6.

• 라이브 인벤토리, 스냅샷 또는 적용 작업을 위한 iOS 시뮬레이터 런타임이 포함된 전체 Xcode.

• 의도한 Xcode 설치로 xcode-select가 구성되어 있어야 합니다.

Command Line Tools만으로 패키지를 빌드할 수 있지만, CoreSimulator 또는 simctl을 제공하지 않습니다.

설치

git clone https://github.com/qubyyang/awesome-ios-sim.git
cd awesome-ios-sim
swift build -c release

실행 파일은 다음 위치에 생성됩니다:

.build/release/ios-sim-state
.build/release/ios-sim-state-mcp

스키마가 안정화된 후 Homebrew 배포 및 서명된 릴리스 아티팩트가 계획되어 있습니다.

빠른 시작

사용 가능한 시뮬레이터 나열:

swift run ios-sim-state inventory

하나의 시뮬레이터 캡처:

swift run ios-sim-state snapshot --device <UDID> > simulator.snapshot.json

포함된 예제에서 오프라인 계획 생성:

swift run ios-sim-state plan \
  --profile Examples/ui-tests.profile.json \
  --snapshot Examples/ui-tests.snapshot.json > simulator.plan.json

변경 없이 적용 동작 미리보기 (기본값):

swift run ios-sim-state apply --plan simulator.plan.json

검토된 계획을 적용하고 실행 저널 보관:

swift run ios-sim-state apply \
  --plan simulator.plan.json \
  --confirm \
  --journal simulator.report.json

apply는 첫 번째 실패한 작업에서 중단됩니다. 각 영수증에는 실행된 인수 배열, 종료 코드, stdout, stderr 및 타임스탬프가 포함됩니다.

상태 프로필

프로필은 schemas/v1alpha1/simulator-state.schema.json에 대해 검증된 JSON 문서입니다. 안전한 기본값이 있는 필드는 생략할 수 있습니다.

{
  "apiVersion": "awesome-ios-sim/v1alpha1",
  "kind": "SimulatorState",
  "metadata": { "name": "ui-tests" },
  "target": {
    "name": "iPhone 17 Pro",
    "runtime": "com.apple.CoreSimulator.SimRuntime.iOS-27-0"
  },
  "spec": {
    "power": "shutdown",
    "applications": [
      {
        "bundleIdentifier": "com.example.app",
        "sourcePath": "/absolute/path/to/Example.app",
        "running": true,
        "launchArguments": ["--uitesting"]
      }
    ],
    "preferences": [
      {
        "domain": "com.example.app",
        "key": "hasSeenOnboarding",
        "value": false
      }
    ],
    "statusBar": { "time": "09:41", "batteryLevel": 100 }
  }
}

power: "unchanged"는 임시 작업 후 원래 전원 상태를 복원합니다. 지우기(erase)가 계획된 경우 부팅된 장치는 먼저 종료됩니다. 부팅 작업은 종속 작업 전에 simctl bootstatus -b를 기다립니다.

CLI

모든 기계 출력은 JSON입니다. 한 줄 출력에는 --compact를 사용하세요.

AI 에이전트용 MCP

MCP 실행 파일을 빌드하고 stdio 호환 MCP 클라이언트가 절대 경로를 가리키도록 설정하세요:

{
  "mcpServers": {
    "awesome-ios-sim": {
      "command": "/absolute/path/awesome-ios-sim/.build/release/ios-sim-state-mcp"
    }
  }
}

서버는 다섯 가지 도구를 제공합니다:

stdio 서버는 MCP 2026-07-28 무상태 요청 모델을 구현합니다. 여기에는 server/discover, 요청별 _meta, 캐시 가능한 도구 목록, resultType, JSON Schema 2020-12가 포함됩니다. 또한 2025-11-25, 2025-06-18, 2024-11-05 도구 클라이언트에서 사용하는 레거시 초기화 핸드셰이크도 허용합니다. 와이어 예제와 정확한 지원 하위 집합은 MCP 가이드를 참조하세요.

DeepSeek Harness 플러그인

리포지토리를 DSH 번들로 설치하고 웹 프로필을 시작하세요:

dsh plugin --profile web add github:qubyyang/awesome-ios-sim
dsh web

Harness는 기존 MCP 서버를 브리지하며 mcp__ios_sim__simulator_inventory 및 mcp__ios_sim__simulator_plan과 같은 네임스페이스 도구를 노출합니다. 어댑터는 현재 @deepseek-ai/dsh 0.1.0-rc.7에 대해 테스트되었습니다. Harness는 아직 개발자 프리뷰 상태이므로 재현 가능한 환경에서는 태그나 커밋을 고정하세요.

구성, 개발, 도구 이름, 제거 단계 및 호스트 프로세스 보안 경계에 대해서는 DeepSeek Harness 가이드를 참조하세요.

상태 적용 범위

플래너는 최선(best-effort) 데이터를 정확한 상태로 자동 승격하지 않습니다. 누락된 읽기는 기능 메타데이터, 반복된 멱등 쓰기 또는 수렴에 대한 잘못된 주장 대신 경고를 생성합니다.

안전 모델

• 셸이 호출되지 않습니다. 실행 파일과 인수는 별도로 전달됩니다.

• diff, plan 및 기본 apply는 시뮬레이터를 변경할 수 없습니다.

• CLI apply는 --confirm이 필요합니다. MCP apply는 부울 confirm: true가 필요합니다.

• 작업은 직렬화되며 첫 번째 실패에서 중단됩니다.

• 부팅된 시뮬레이터는 지우기 전에 종료됩니다.

• 임시 부팅은 요청된 또는 원래 최종 전원 상태를 복원합니다.

• 도구 스키마는 알 수 없는 최상위 인수를 허용하지 않습니다.

• 비공개 프레임워크 로딩, 고아 디렉터리 삭제 또는 파일 시스템 정리가 수행되지 않습니다.

계획 파일을 실행 가능한 의도로 취급하세요. 확인 전에 대상 UDID, 앱 경로, 지우기 작업 및 환경설정 도메인의 변경 사항을 검토하세요.

왜 Swift인가

시뮬레이터 작업은 언어 수준의 CPU 시간보다 Xcode 및 CoreSimulator 프로세스 지연 시간에 의해 지배됩니다. Swift는 런타임을 추가하지 않고 기본 macOS 배포, 강력한 Codable 모델 및 iOS 도구와의 직접적인 정렬을 제공합니다. Rust는 이식 가능하고 CPU 집약적인 인덱서에 좋은 선택이겠지만, simctl boot, 설치 또는 지우기를 실질적으로 가속화하지는 않습니다. 패키지는 순수 상태 엔진과 프로세스 경계를 분리하여 프로파일링이 정당화될 경우 나중에 특화된 헬퍼를 도입할 수 있도록 합니다.

개발

swift build
swift test
npm ci
npm test
npm run pack:check
swift run ios-sim-state plan \
  --profile Examples/ui-tests.profile.json \
  --snapshot Examples/ui-tests.snapshot.json

CONTRIBUTING.md, SECURITY.md 및 아키텍처 노트를 참조하세요. 비공개 CoreSimulator API를 추가하지 마세요.

로드맵

• 프로필 스키마 안정화 및 태그된 바이너리 게시.

• Homebrew 배포 및 서명된 유니버설 아티팩트 추가.

• 재사용 가능한 프로필 레이어 및 프리셋 추가.

• 비공개 프레임워크 없이 기능 인식 설정 확장.

• 동일한 상태 엔진 위에 네이티브 SwiftUI 동반 앱 구축.

라이선스

MIT. LICENSE를 참조하세요.