EvanBacon/serve-sim

# serve-sim Apple Simulators 的 `npx serve`。 托管你的模拟器，以便与 Codex、Cursor 或 Claude Desktop 等 Agent 工具配合使用 —— 支持本地使用、通过局域网使用，或托管在远程 Mac 上并穿透到任何地方。 ``` npx serve-sim # → 预览地址为 http://localhost:3200 ``` https://github.com/user-attachments/assets/fbf890f4-c8c7-4684-82be-d677b8a188f8 `serve-sim` 会启动一个小型的 Swift 辅助程序，该程序通过 `simctl io` 捕获模拟器的 framebuffer，将其作为 MJPEG stream + WebSocket 控制通道公开，并在上层提供 React 预览 UI。它适用于任何已启动的 iOS Simulator —— 无需 Xcode 插件，也无需在你的应用中进行检测。 ## 功能 - 浏览器中完整的 60 FPS 视频流。 - 从底部滑动以返回主屏幕。 - 按住 option 键可执行双指缩放等手势操作。 - 模拟器日志会转发到浏览器，供 browser-use MCP 工具读取。 - 拖放视频和图像以将它们添加到模拟器设备中。 - 键盘命令和快捷键会转发到模拟器，包括使用 CMD+SHIFT+H 返回主屏幕。 - 支持 Apple Watch、iPad 和 iOS。 ## 为什么？ 托管的模拟器可能很难测试，`serve-sim` 让你能够在本地先测试托管的基础设施，从而加快迭代速度。当你准备好远程托管模拟器时，只需穿透提供的 URL，用户就可以像在本地设备上运行一样与模拟器进行交互。 我开发 Expo 框架，但这个工具与 React Native 完全无关，可用于你需要的任何 iOS 交互。 ## 安装 需要配备 Xcode command line tools (`xcrun simctl`) 的 macOS 以及 Node.js 18+。运行 CLI **不**需要 `bun`。摄像头注入使用的是为 macOS 14+ 构建的主机端辅助程序。 ## CLI ``` serve-sim [device...] Start preview server (default: localhost:3200) serve-sim --no-preview [device...] Stream in foreground without a preview server serve-sim gesture '' [-d udid] Send a touch gesture serve-sim button [name] [-d udid] Send a button press (default: home) serve-sim type [-d udid] Type text via the simulator keyboard (US keyboard only; also --stdin / --file ) serve-sim rotate [-d udid] portrait | portrait_upside_down | landscape_left | landscape_right serve-sim ca-debug [-d udid] Toggle a CoreAnimation debug flag (blended|copies|misaligned|offscreen|slow-animations) serve-sim memory-warning [-d udid] Simulate a memory warning serve-sim camera [-d udid] [source-options] Inject a synthetic camera feed and (re)launch the app serve-sim camera switch [arg] [-d udid] Hot-swap the running helper's source (no relaunch) serve-sim camera mirror [-d udid] Hot-swap preview-layer mirror mode serve-sim camera status [-d udid] Print helper state as JSON ({alive, source, ...}) serve-sim camera --list-webcams List host camera devices serve-sim camera --stop-webcam [-d udid] Stop the camera helper for a device Options: -p, --port Starting port (preview default: 3200, stream default: 3100) -d, --detach Spawn helper and exit (daemon mode) -q, --quiet JSON-only output --no-preview Skip the web UI; stream in foreground only --list [device] List running streams --kill [device] Kill running stream(s) Camera options (used with `serve-sim camera `): -f, --file Image or video file (kind auto-detected from extension/magic bytes; videos loop at native FPS) --webcam [name] Live host webcam (defaults to the built-in front camera when [name] is omitted) --mirror [on|off|auto] Override preview-layer mirroring (default: auto = front mirrored, back not). Data-output buffers are never auto-mirrored, matching AVF defaults. --no-mirror Shortcut for --mirror off --build Rebuild the dylib + helper from source ``` ### 示例 ``` serve-sim # auto-detect booted sim, open preview serve-sim "iPhone 16 Pro" # target a specific device serve-sim --detach # start a background helper, return JSON serve-sim --list # show running streams serve-sim --kill # stop all helpers # 在聚焦的输入框中输入文本 serve-sim type "Hello, world!" echo "from stdin" | serve-sim type --stdin serve-sim type --file ./snippet.txt # Camera injection serve-sim camera com.acme.MyApp # animated placeholder serve-sim camera com.acme.MyApp --webcam # default webcam serve-sim camera com.acme.MyApp --webcam "MacBook Pro Camera" serve-sim camera com.acme.MyApp --file ~/Pictures/face.png # static image serve-sim camera com.acme.MyApp --file ~/Movies/loop.mp4 # looping video # 在正在运行的 helper 上热替换 source（无需重新启动 app） serve-sim camera switch placeholder serve-sim camera switch webcam serve-sim camera switch ~/Movies/loop.mp4 # auto-detects file kind # 其他 helpers serve-sim camera mirror on serve-sim camera status # JSON: alive, source, mirror serve-sim camera --list-webcams serve-sim camera --stop-webcam ``` 支持多个已启动的模拟器 —— 传入多个设备名称，或留空以附加到所有设备。 ### 摄像头 `serve-sim camera ` 会替换单个应用的模拟器摄像头画面。一个小型的主机端辅助程序将 BGRA 帧写入 POSIX 共享内存区域；一个注入的 dylib (`DYLD_INSERT_LIBRARIES`) 在模拟器进程内 swizzle AVFoundation，以便应用从该内存区域读取数据，而不是从模拟器的存根摄像头读取。 该辅助程序是每个设备对应的，并且其生命周期长于任何单个应用的启动，因此同一模拟器上的多个应用可以共享该数据流 —— 只需再次运行 `serve-sim camera ` 即可启动下一个应用并附加 dylib。源更改 (`camera switch`) 和镜像更改 (`camera mirror`) 通过辅助程序的控制 socket 传递，不会重新启动应用。 来源： - **placeholder** — 动画程序化帧（默认）。 - **file** — 图像（PNG/JPEG/HEIC/…）或视频（mp4/mov/m4v/webm/…）。CLI 通过扩展名判断类型，对于没有扩展名的文件则回退到通过 magic bytes 判断。 - **webcam** — 实时 `AVCaptureDevice`（内置、Continuity、外部设备）。 ## 连接器 `serve-sim` 可以与开发服务器、浏览器和 AI 编辑器结合使用，实现更无缝的集成。 ### Agent Skill [`skills/serve-sim`](skills/serve-sim) 中内置了一个 [Agent Skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) —— 它教会 AI 编码 Agent（Claude Code、Cursor、Codex CLI、Gemini CLI 以及任何实现了开放 Agent Skills 标准的宿主）如何通过 CLI 驱动模拟器：点击、手势、硬件按钮、旋转、摄像头注入，以及将数据流移交至宿主的预览面板。 ``` bunx add-skill EvanBacon/serve-sim # 在 Claude Code 中： /plugin marketplace add EvanBacon/serve-sim ``` 完整功能列表请参阅 [`skills/serve-sim/README.md`](skills/serve-sim/README.md)。 ### Claude Code Desktop 创建一个 `.claude/launch.json` 并定义一个服务器： ``` { "version": "0.0.1", "configurations": [ { "name": "Apple", "runtimeExecutable": "npx", "runtimeArgs": ["serve-sim"], "port": 3200 } ] } ``` ### Expo 使用 `npx expo start` 自动启动 serve-sim 进程，并通过 `http://localhost:8081/.sim` 访问该 URL。 首先，自定义 `metro.config.js` 文件（`bunx expo customize`）： ``` // Learn more https://docs.expo.io/guides/customizing-metro const { getDefaultConfig } = require("expo/metro-config"); const connect = require("connect"); const { simMiddleware } = require("serve-sim/middleware"); /** @type {import('expo/metro-config').MetroConfig} */ const config = getDefaultConfig(__dirname); config.server = config.server || {}; const originalEnhanceMiddleware = config.server.enhanceMiddleware; config.server.enhanceMiddleware = (metroMiddleware, server) => { const middleware = originalEnhanceMiddleware ? originalEnhanceMiddleware(metroMiddleware, server) : metroMiddleware; const app = connect(); app.use(simMiddleware({ basePath: "/.sim" })); app.use(middleware); return app; }; module.exports = config; ``` ## 嵌入到你的开发服务器中 `serve-sim/middleware` 是一个 Connect 风格的 middleware，可以将相同的预览 UI 挂载到你现有的开发服务器（Metro、Vite、Next、纯 Express 等）中。运行一次 `serve-sim --detach` 以启动流式传输辅助程序，然后添加该 middleware： ``` import { simMiddleware } from "serve-sim/middleware"; app.use(simMiddleware({ basePath: "/.sim" })); // → preview HTML at /.sim // → state JSON at /.sim/api // → SSE logs at /.sim/logs ``` middleware 从 `$TMPDIR/serve-sim/` 读取辅助程序的状态，并将用户的浏览器转发到实时的 MJPEG + WebSocket endpoint。辅助程序上的 CORS 是完全开放的，因此无需代理即可渲染页面。 ## 工作原理 ``` ┌──────────────┐ simctl io ┌─────────────────┐ MJPEG / WS ┌─────────┐ │ iOS Simulator│ ────────────► │ serve-sim-bin │ ───────────► │ Browser │ └──────────────┘ (Swift) │ (per-device) │ └─────────┘ └─────────────────┘ ▲ state file in $TMPDIR/serve-sim/ ▲ ┌──────────────────┐ │ serve-sim CLI / │ │ middleware │ └──────────────────┘ ``` Swift 辅助程序（`bin/serve-sim-bin`）是一个小型的独立二进制文件 —— 在 runtime 无需依赖 Xcode。CLI 通过 `bun build --compile` 将其嵌入，因此只需安装该 npm 包即可。 ## 开发 ``` bun install bun run --filter serve-sim build # build the JS bundles bun run --filter serve-sim build:swift # rebuild the Swift helper bun run --filter serve-sim dev # watch mode ``` ## 许可证 Apache-2.0

标签：iOS模拟器, MITM代理, React, SOC Prime, Swift, Syscalls, 开发工具, 移动开发, 自动化攻击, 远程桌面