awesome-ios-sim

简体中文 · Guía de MCP · DeepSeek Harness · Arquitectura

Estado del simulador como código para desarrolladores de iOS, pipelines de CI y agentes de IA.

awesome-ios-sim convierte la configuración de un simulador de iOS en un perfil versionado que se puede capturar, comparar, planificar, revisar y aplicar de forma segura. Proporciona tanto una CLI determinista como un servidor MCP stdio. También se puede instalar como un paquete dsh-plugin para DeepSeek Harness.

Estado del proyecto: alfa. El esquema de estado es v1alpha1. Revisa los planes generados antes de aplicarlos, especialmente los planes que contengan operaciones de erase o eliminación de aplicaciones.

Por qué existe

La automatización del simulador suele estar dispersa en scripts de shell, valores predeterminados no documentados y configuración manual. Esto hace que los entornos de prueba sean difíciles de reproducir y proporciona a los agentes de IA una superficie de shell insegura y sin tipo.

Este proyecto introduce un flujo de trabajo:

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

• Declarativo: confirma los perfiles del simulador junto con las pruebas y el código de la aplicación.

• Revisable: inspecciona el plan de operaciones ordenadas exacto antes de la mutación.

• Seguro para agentes: las herramientas MCP usan JSON Schema y simulator_apply por defecto en modo de prueba (dry-run).

• Consciente de capacidades: el estado exacto, de mejor esfuerzo y no soportado se informa explícitamente.

• Solo API pública: las mutaciones pasan por xcrun simctl de Apple; no hay frameworks privados de CoreSimulator.

• Local primero: sin demonio, cuenta en la nube, telemetría ni clave API.

Related MCP server: Shotter

Arquitectura

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

El motor de estado no tiene dependencia de Xcode y se prueba con fixtures. Solo SimctlDriver toca el límite del proceso anfitrión. La CLI y el servidor MCP comparten el mismo planificador, validación y puertas de aplicación.

Requisitos

• macOS 13 o posterior.

• Swift 6.

• Xcode completo con un runtime de simulador de iOS para operaciones de inventario, instantánea o aplicación en vivo.

• xcode-select configurado para la instalación de Xcode deseada.

Solo las herramientas de línea de comandos pueden compilar el paquete, pero no proporcionan CoreSimulator ni simctl.

Instalar

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

Los ejecutables se generan en:

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

Se planea la distribución mediante Homebrew y artefactos de lanzamiento firmados una vez que el esquema se estabilice.

Inicio rápido

Lista los simuladores disponibles:

swift run ios-sim-state inventory

Captura un simulador:

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

Genera un plan sin conexión a partir del ejemplo incluido:

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

Previsualiza el comportamiento de aplicación sin mutación (el valor predeterminado):

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

Aplica un plan revisado y conserva un registro de ejecución:

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

apply se detiene en la primera operación que falla. Cada recibo contiene los arrays de argumentos ejecutados, el código de salida, stdout, stderr y marcas de tiempo.

Perfil de estado

Los perfiles son documentos JSON validados contra schemas/v1alpha1/simulator-state.schema.json. Los campos con valores predeterminados seguros pueden omitirse.

{
  "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" restaura el estado de alimentación original después de un trabajo temporal. Cuando se planifica un borrado, un dispositivo encendido se apaga primero. Las operaciones de arranque esperan a simctl bootstatus -b antes del trabajo dependiente.

CLI

Toda la salida orientada a máquina es JSON. Usa --compact para una salida en una sola línea.

MCP para agentes de IA

Compila el ejecutable MCP y apunta cualquier cliente MCP compatible con stdio a su ruta absoluta:

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

El servidor expone cinco herramientas:

El servidor stdio implementa el modelo de solicitud sin estado MCP 2026-07-28, incluyendo server/discover, _meta por solicitud, listas de herramientas cacheables, resultType y JSON Schema 2020-12. También acepta el handshake de inicialización heredado usado por los clientes de herramientas 2025-11-25, 2025-06-18 y 2024-11-05. Consulta la guía de MCP para ver ejemplos de cable y el subconjunto soportado exacto.

Complemento de DeepSeek Harness

Instala el repositorio como un paquete DSH e inicia el perfil Web:

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

Harness puentea el servidor MCP existente y expone herramientas con espacio de nombres como mcp__ios_sim__simulator_inventory y mcp__ios_sim__simulator_plan. El adaptador se prueba actualmente contra @deepseek-ai/dsh 0.1.0-rc.7. Fija una etiqueta o commit en entornos reproducibles porque Harness aún está en vista previa para desarrolladores.

Consulta la guía de DeepSeek Harness para configuración, desarrollo, nombres de herramientas, pasos de desinstalación y el límite de seguridad del proceso anfitrión.

Cobertura de estado

El planificador nunca actualiza silenciosamente datos de mejor esfuerzo a estado exacto. La falta de lectura produce metadatos de capacidad, escrituras idempotentes repetidas o una advertencia, en lugar de una afirmación falsa de convergencia.

Modelo de seguridad

• No se invoca ningún shell; el ejecutable y los argumentos se pasan por separado.

• diff, plan y apply por defecto no pueden mutar un simulador.

• La CLI de apply requiere --confirm; MCP apply requiere el booleano confirm: true.

• Las operaciones se serializan y se detienen ante el primer fallo.

• Un simulador encendido se apaga antes de un borrado.

• Los arranques temporales restauran el estado de alimentación solicitado o final original.

• Los esquemas de herramientas rechazan argumentos de nivel superior desconocidos.

• No se realiza carga de frameworks privados, eliminación de directorios huérfanos ni limpieza del sistema de archivos.

Trata los archivos de plan como intenciones ejecutables. Revisa los cambios en los UDID de destino, las rutas de las aplicaciones, las operaciones de borrado y los dominios de preferencias antes de la confirmación.

Por qué Swift

El trabajo con simuladores está dominado por la latencia del proceso de Xcode y CoreSimulator, no por el tiempo de CPU a nivel de lenguaje. Swift proporciona distribución nativa en macOS, modelos Codable sólidos y alineación directa con las herramientas de iOS sin añadir un runtime. Rust sería una opción sólida para un indexador portátil con uso intensivo de CPU, pero no aceleraría materialmente simctl boot, install o erase. El paquete mantiene el motor de estado puro y el límite del proceso separados para que se pueda introducir un helper especializado más adelante si la creación de perfiles lo justifica.

Desarrollo

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

Consulta CONTRIBUTING.md, SECURITY.md y las notas de arquitectura. Por favor, no añadas APIs privadas de CoreSimulator.

Hoja de ruta

• Estabilizar el esquema de perfil y publicar binarios etiquetados.

• Añadir distribución mediante Homebrew y artefactos universales firmados.

• Añadir capas de perfil reutilizables y ajustes preestablecidos.

• Expandir ajustes conscientes de capacidades sin frameworks privados.

• Construir una aplicación complementaria nativa en SwiftUI sobre el mismo motor de estado.

Licencia

MIT. Consulta LICENSE.