awesome-ios-sim

简体中文 · MCP 指南 · DeepSeek Harness · 架构

面向 iOS 开发者、CI 流水线和 AI 代理的“模拟器状态即代码”。

awesome-ios-sim 将 iOS 模拟器配置转化为可版本化的配置文件，支持捕获、差异比较、规划、审查和安全应用。它同时提供确定性的 CLI 和 MCP stdio 服务器。也可作为 dsh-plugin 包安装到 DeepSeek Harness。

项目状态：alpha。 状态模式为 v1alpha1。在应用生成的计划前请进行审查，尤其是包含 erase 或应用删除操作的计划。

为什么存在

模拟器自动化通常分散在 shell 脚本、未记录的默认值和手动设置中。这使得测试环境难以复现，并给 AI 代理提供了一个不安全、无类型的 shell 接口。

本项目引入了一个工作流：

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

• 声明式： 将模拟器配置文件与测试和应用代码一起提交。

• 可审查： 在变更前检查精确的有序操作计划。

• 代理安全： MCP 工具使用 JSON Schema，simulator_apply 默认进行空运行。

• 能力感知： 精确、尽力而为和不支持的状态会被明确报告。

• 仅限公共 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。

• 完整的 Xcode（含 iOS 模拟器运行时）用于实时清单、快照或应用操作。

• xcode-select 已配置为预期的 Xcode 安装。

仅命令行工具可以构建包，但它们不提供 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 和时间戳。

状态配置文件

配置文件是 JSON 文档，根据 schemas/v1alpha1/simulator-state.schema.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" 在临时工作后恢复原始电源状态。当计划擦除时，已启动的设备会先关闭。启动操作会等待 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 包并启动 Web 配置文件：

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 指南。

状态覆盖范围

规划器永远不会将尽力而为的数据静默升级为精确状态。缺失的回读会产生能力元数据、重复的幂等写入或警告，而不是虚假的收敛声明。

安全模型

• 不调用 shell；可执行文件和参数分开传递。

• diff、plan 和默认的 apply 不能变更模拟器。

• CLI apply 需要 --confirm；MCP apply 需要布尔值 confirm: true。

• 操作串行执行，并在第一个失败处停止。

• 已启动的模拟器在擦除前会关闭。

• 临时启动会恢复请求的或原始的最终电源状态。

• 工具模式禁止未知的顶级参数。

• 不加载私有框架、不删除孤立目录、不执行文件系统清理。

将计划文件视为可执行意图。在确认前，请审查目标 UDID、应用路径、擦除操作和偏好域的变化。

为什么选择 Swift

模拟器工作主要受 Xcode 和 CoreSimulator 进程延迟影响，而非语言级别的 CPU 时间。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。