awesome-ios-sim

简体中文 · MCP-Leitfaden · DeepSeek Harness · Architektur

Simulatorzustand als Code für iOS-Entwickler, CI-Pipelines und KI-Agenten.

awesome-ios-sim verwandelt ein iOS-Simulator-Setup in ein versioniertes Profil, das erfasst, verglichen, geplant, überprüft und sicher angewendet werden kann. Es bietet sowohl ein deterministisches CLI als auch einen MCP-stdio-Server. Es ist auch als dsh-plugin-Bundle für DeepSeek Harness installierbar.

Projektstatus: Alpha. Das Zustandsschema ist v1alpha1. Überprüfen Sie generierte Pläne vor der Anwendung, insbesondere Pläne, die erase- oder App-Entfernungsvorgänge enthalten.

Warum es das gibt

Simulator-Automatisierung ist normalerweise über Shell-Skripte, undokumentierte Standardeinstellungen und manuelle Einrichtung verteilt. Das macht Testumgebungen schwer reproduzierbar und gibt KI-Agenten eine unsichere, untypisierte Shell-Oberfläche.

Dieses Projekt führt einen Workflow ein:

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

• Deklarativ: Simulator-Profile neben Tests und Anwendungscode committen.

• Überprüfbar: Den genauen geordneten Operationsplan vor der Mutation einsehen.

• Agentensicher: MCP-Tools verwenden JSON Schema und simulator_apply standardmäßig als Trockenlauf.

• Fähigkeitsbewusst: Exakter, bestmöglicher und nicht unterstützter Zustand wird explizit gemeldet.

• Nur öffentliche API: Mutationen erfolgen über Apples xcrun simctl; keine privaten CoreSimulator-Frameworks.

• Lokal zuerst: Kein Daemon, Cloud-Konto, Telemetrie oder API-Schlüssel.

Related MCP server: Shotter

Architektur

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

Die Zustandsmaschine hat keine Xcode-Abhängigkeit und wird mit Testdaten getestet. Nur SimctlDriver berührt die Host-Prozessgrenze. Das CLI und der MCP-Server teilen sich denselben Planer, dieselbe Validierung und dieselben Anwendungsgates.

Voraussetzungen

• macOS 13 oder neuer.

• Swift 6.

• Vollständiges Xcode mit einer iOS-Simulator-Laufzeitumgebung für Live-Inventar, Snapshot- oder Anwendungsvorgänge.

• xcode-select auf die gewünschte Xcode-Installation konfiguriert.

Allein die Befehlszeilenwerkzeuge können das Paket erstellen, aber sie bieten weder CoreSimulator noch simctl.

Installation

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

Die ausführbaren Dateien werden erstellt unter:

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

Homebrew-Distribution und signierte Release-Artefakte sind geplant, nachdem sich das Schema stabilisiert hat.

Schnellstart

Verfügbare Simulatoren auflisten:

swift run ios-sim-state inventory

Einen Simulator erfassen:

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

Einen Offline-Plan aus dem enthaltenen Beispiel erstellen:

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

Anwendungsverhalten ohne Mutation in der Vorschau anzeigen (Standard):

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

Einen überprüften Plan anwenden und ein Ausführungsjournal behalten:

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

apply stoppt beim ersten fehlgeschlagenen Vorgang. Jede Quittung enthält die ausgeführten Argumentarrays, den Exit- Code, stdout, stderr und Zeitstempel.

Zustandsprofil

Profile sind JSON-Dokumente, die gegen schemas/v1alpha1/simulator-state.schema.json validiert werden. Felder mit sicheren Standardwerten können weggelassen werden.

{
  "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" stellt den ursprünglichen Stromzustand nach temporärer Arbeit wieder her. Wenn ein Löschen geplant ist, wird ein gestartetes Gerät zuerst heruntergefahren. Boot-Vorgänge warten auf simctl bootstatus -b, bevor abhängige Arbeit beginnt.

CLI

Die gesamte maschinenorientierte Ausgabe ist JSON. Verwenden Sie --compact für einzeilige Ausgabe.

MCP für KI-Agenten

Erstellen Sie die MCP-ausführbare Datei und verweisen Sie einen beliebigen stdio-fähigen MCP-Client auf ihren absoluten Pfad:

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

Der Server stellt fünf Tools bereit:

Der stdio-Server implementiert das zustandslose Anfragemodell MCP 2026-07-28, einschließlich server/discover, _meta pro Anfrage, cachebare Tool-Listen, resultType und JSON Schema 2020-12. Er akzeptiert auch den Legacy-Initialize-Handshake, der von 2025-11-25, 2025-06-18 und 2024-11-05 Tool-Clients verwendet wird. Siehe den MCP-Leitfaden für Drahtbeispiele und die genaue unterstützte Teilmenge.

DeepSeek Harness-Plugin

Installieren Sie das Repository als DSH-Bundle und starten Sie das Web-Profil:

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

Harness überbrückt den vorhandenen MCP-Server und stellt namensräumliche Tools wie mcp__ios_sim__simulator_inventory und mcp__ios_sim__simulator_plan bereit. Der Adapter wird derzeit gegen @deepseek-ai/dsh 0.1.0-rc.7 getestet. Fixieren Sie in reproduzierbaren Umgebungen einen Tag oder Commit, da Harness sich noch in der Entwicklervorschau befindet.

Siehe den DeepSeek Harness-Leitfaden für Konfiguration, Entwicklung, Toolnamen, Deinstallationsschritte und die Host-Prozess-Sicherheitsgrenze.

Zustandsabdeckung

Der Planer stuft bestmögliche Daten niemals stillschweigend auf exakten Zustand hoch. Fehlendes Rücklesen erzeugt Fähigkeitsmetadaten, wiederholte idempotente Schreibvorgänge oder eine Warnung anstelle einer falschen Behauptung von Konvergenz.

Sicherheitsmodell

• Es wird keine Shell aufgerufen; ausführbare Datei und Argumente werden getrennt übergeben.

• diff, plan und das Standard-apply können keinen Simulator mutieren.

• CLI-apply erfordert --confirm; MCP-apply erfordert boolesches confirm: true.

• Operationen werden serialisiert und stoppen beim ersten Fehler.

• Ein gestarteter Simulator wird vor dem Löschen heruntergefahren.

• Temporäre Bootvorgänge stellen den angeforderten oder ursprünglichen endgültigen Stromzustand wieder her.

• Tool-Schemas verbieten unbekannte Argumente der obersten Ebene.

• Es wird kein privates Framework geladen, kein verwaistes Verzeichnis gelöscht und keine Dateisystembereinigung durchgeführt.

Behandeln Sie Plan-Dateien als ausführbare Absicht. Überprüfen Sie Änderungen an Ziel-UDIDs, App-Pfaden, Löschvorgängen und Präferenzdomänen vor der Bestätigung.

Warum Swift

Simulatorarbeit wird von Xcode- und CoreSimulator-Prozesslatenz dominiert, nicht von CPU-Zeit auf Sprachebene. Swift bietet native macOS-Verteilung, starke Codable-Modelle und direkte Ausrichtung an iOS-Tooling ohne eine Laufzeitumgebung hinzuzufügen. Rust wäre eine gute Wahl für einen portablen, CPU-intensiven Indexer, würde aber simctl boot, Installieren oder Löschen nicht wesentlich beschleunigen. Das Paket hält die reine Zustandsmaschine und Prozessgrenze getrennt, sodass später ein spezialisierter Helfer eingeführt werden kann, wenn das Profiling dies rechtfertigt.

Entwicklung

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

Siehe CONTRIBUTING.md, SECURITY.md und die Architekturnotizen. Bitte fügen Sie keine privaten CoreSimulator-APIs hinzu.

Fahrplan

• Das Profilschema stabilisieren und getaggte Binärdateien veröffentlichen.

• Homebrew-Verteilung und signierte universelle Artefakte hinzufügen.

• Wiederverwendbare Profilschichten und Voreinstellungen hinzufügen.

• Fähigkeitsbewusste Einstellungen ohne private Frameworks erweitern.

• Eine native SwiftUI-Begleit-App auf Basis derselben Zustandsmaschine erstellen.

Lizenz

MIT. Siehe LICENSE.