@qubyyang/awesome-ios-sim
面向 iOS 开发者、CI 流水线、MCP 客户端和 DeepSeek Harness 的模拟器状态即代码
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:qubyyang/awesome-ios-sim#583ed4b4d11b75f4fe87abf872cff1a2ba07258cAwesome Ios Sim 以 @qubyyang/awesome-ios-sim 发布，当前版本为 0.2.0-dev。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
简体中文 · MCP guide · DeepSeek Harness · Signed distribution · Architecture
Simulator State as Code for iOS developers, CI pipelines, and AI agents.
awesome-ios-sim turns an iOS Simulator setup into a versioned profile that can be captured, diffed,
planned, reviewed, and safely applied. It provides both a deterministic CLI and an MCP stdio server.
It is also installable as a dsh-plugin bundle for DeepSeek Harness.
Project status: alpha. The state schema is
v1alpha1. Review generated plans before applying them, especially plans containingeraseor app removal operations.
Simulator automation is usually spread across shell scripts, undocumented defaults, and manual setup. That makes test environments difficult to reproduce and gives AI agents an unsafe, untyped shell surface.
This project introduces one workflow:
profile + current snapshot -> diff -> deterministic plan -> explicit confirmation -> audited apply
simulator_apply defaults to dry-run.xcrun simctl; no private CoreSimulator frameworks.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
The state engine has no Xcode dependency and is tested with fixtures. Only SimctlDriver touches the
host process boundary. The CLI and MCP server share the same planner, validation, and apply gates.
xcode-select configured to the intended Xcode installation.Command Line Tools alone can build the package, but they do not provide CoreSimulator or simctl.
git clone https://github.com/qubyyang/awesome-ios-sim.git
cd awesome-ios-sim
swift build -c release
The executables are produced at:
.build/release/ios-sim-state
.build/release/ios-sim-state-mcp
Checksummed native archives for Apple Silicon and Intel macOS are published on the Releases page. These initial archives are not yet code-signed or notarized. Install the current release through this repository's explicit Homebrew tap:
brew tap qubyyang/awesome-ios-sim https://github.com/qubyyang/awesome-ios-sim
brew install qubyyang/awesome-ios-sim/awesome-ios-sim
On a prerelease macOS version that Homebrew has not identified yet, an internal packages.*_dunno API error can
be bypassed with Homebrew's source-tap mode:
HOMEBREW_NO_INSTALL_FROM_API=1 \
brew install qubyyang/awesome-ios-sim/awesome-ios-sim
The next tagged distribution is gated on Developer ID signing and Apple notarization and will use one universal archive on both architectures. See the signed distribution guide for the trust model.
List available simulators:
swift run ios-sim-state inventory
Capture one simulator:
swift run ios-sim-state snapshot --device <UDID> > simulator.snapshot.json
Compose a target profile from reusable state before planning:
swift run ios-sim-state compose \
--profile Examples/ui-tests.profile.json \
--preset clean-status-bar \
--layer Examples/ui-tests.layer.json > simulator.composed.json
Generate an offline plan from the included example:
swift run ios-sim-state plan \
--profile Examples/ui-tests.profile.json \
--snapshot Examples/ui-tests.snapshot.json > simulator.plan.json
Preview apply behavior without mutation (the default):
swift run ios-sim-state apply --plan simulator.plan.json
Apply a reviewed plan and retain an execution journal:
swift run ios-sim-state apply \
--plan simulator.plan.json \
--confirm \
--journal simulator.report.json
apply stops at the first failing operation. Each receipt contains the executed argument arrays, exit
code, stdout, stderr, and timestamps.
Profiles are JSON documents validated against
schemas/v1alpha1/simulator-state.schema.json.
Fields with safe defaults may be omitted.
{
"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" restores the original power state after temporary work. When an erase is planned,
a booted device is shut down first. Boot operations wait for simctl bootstatus -b before dependent work.
Profile decoding is strict: unknown fields and empty identifiers are rejected. statusBar accepts only the
public simctl status_bar overrides and validates enum values and numeric ranges before planning.
A SimulatorStateLayer contains only reusable spec
fields and deliberately has no target. Apply --layer <file> and --preset <name> to compose, diff, or
plan; repeat and interleave these options in the exact order they should be merged. The base profile keeps
its metadata and target.
Merge behavior is deterministic: later scalar values win; applications replace earlier entries with the same
bundleIdentifier; preferences replace the same domain + key; status-bar fields merge by key. Application
and preference arrays are sorted in the composed output. Absence means “no opinion”; use an application with
presence: "absent" when an uninstall is intended. There is no general delete/tombstone operator in
v1alpha1.
Built-in presets are booted, clean-status-bar, and shutdown. Run ios-sim-state presets to discover
their descriptions. Examples/ui-tests.layer.json is a complete layer example.
| Command | Mutation | Purpose |
|---|---|---|
inventory | No | List runtimes and simulators as stable JSON. |
snapshot --device <UDID> | No | Capture managed state and capability metadata. |
presets | No | List built-in reusable presets. |
compose --profile <file> [overlays] | No | Materialize a complete profile from ordered layers and presets. |
diff --profile <file> [overlays] [--snapshot <file>] | No | Show desired/current differences. |
plan --profile <file> [overlays] [--snapshot <file> | --device <UDID>] | No | Produce an ordered operation plan. |
apply --plan <file> | No | Return a dry-run report. |
apply --plan <file> --confirm | Yes | Execute the reviewed plan serially. |
All machine-facing output is JSON. Use --compact for one-line output.
Build the MCP executable and point any stdio-capable MCP client at its absolute path:
{
"mcpServers": {
"awesome-ios-sim": {
"command": "/absolute/path/awesome-ios-sim/.build/release/ios-sim-state-mcp"
}
}
}
The server exposes seven tools:
| Tool | Behavior |
|---|---|
simulator_inventory | Read simulator inventory. |
simulator_snapshot | Capture one simulator. |
simulator_presets | List built-in reusable presets. |
simulator_compose | Materialize a complete profile from ordered overlays. |
simulator_diff | Compare a profile with saved or live state. |
simulator_plan | Generate a typed, ordered plan. |
simulator_apply | Dry-run by default; mutates only with confirm: true. |
The stdio server implements the MCP 2026-07-28 stateless request model, including
server/discover, per-request _meta, cacheable tool lists, resultType, and JSON Schema 2020-12.
It also accepts the legacy initialize handshake used by 2025-11-25, 2025-06-18, and 2024-11-05
tool clients. See the MCP guide for wire examples and the exact supported subset.
Install the repository as a DSH bundle and start the Web profile:
dsh plugin --profile web add github:qubyyang/awesome-ios-sim
dsh web
Harness bridges the existing MCP server and exposes namespaced tools such as
mcp__ios_sim__simulator_inventory and mcp__ios_sim__simulator_plan. The adapter is currently tested
against @deepseek-ai/dsh 0.1.0-rc.7. Pin a tag or commit in reproducible environments because Harness
is still in developer preview.
See the DeepSeek Harness guide for configuration, development, tool names, uninstall steps, and the host-process security boundary.
| State | Read | Write | Support |
|---|---|---|---|
| Power | Yes | Yes | Exact |
| Installed apps | Yes when listapps is available | Yes | Best effort |
| App running state | Not completely exposed by simctl | Launch/terminate | Best effort |
| Managed preference keys | No general readback | Scalar values and scalar arrays | Best effort |
| Status bar overrides | No complete readback | Yes, runtime-dependent | Best effort |
| Erase | N/A | Yes, explicit destructive operation | Exact mutation |
The planner never silently upgrades best-effort data to exact state. Missing readback produces capability metadata, repeated idempotent writes, or a warning rather than a false claim of convergence.
diff, plan, and default apply cannot mutate a simulator.--confirm; MCP apply requires boolean confirm: true.Treat plan files as executable intent. Review changes to target UDIDs, app paths, erase operations, and preference domains before confirmation.
Simulator work is dominated by Xcode and CoreSimulator process latency, not language-level CPU time.
Swift provides native macOS distribution, strong Codable models, and direct alignment with iOS tooling
without adding a runtime. Rust would be a strong choice for a portable, CPU-heavy indexer, but it would
not materially accelerate simctl boot, install, or erase. The package keeps the pure state engine and
process boundary separate so a specialized helper can be introduced later if profiling justifies it.
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
Run the opt-in live suite against a real Xcode Simulator runtime:
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer \
Scripts/live-integration-test.sh
It creates and exclusively targets a uniquely named temporary simulator, verifies the CLI and MCP paths,
checks dry-run safety and confirmed reconciliation, then deletes that exact device. Existing simulators are
not selected or modified. The script requires jq; artifacts are retained under .build/live-integration/.
Build and inspect a versioned native release archive locally:
Scripts/release/verify-version.sh
Scripts/release/build-artifact.sh
GitHub automation can run an unpublished release candidate from the default branch. Tag-driven runs build separate arm64 and x86_64 slices, merge and validate a universal archive, then require Developer ID signing, Apple notarization, a checksum-bound Homebrew Formula, and GitHub provenance before publishing. See the compatibility contract, distribution contract, and bilingual release process. No release is created from an untagged branch build.
See CONTRIBUTING.md, SECURITY.md, and the architecture notes. Please do not add private CoreSimulator APIs.
MIT. See LICENSE.