SimMirror

SimMirror

通过 Claude Code、命令行 Agent 和浏览器镜像并操控 iOS 模拟器、真实 iPhone 和 Android 设备。

真实会话，四倍速播放。完整录像 时长 1 分 39 秒。

在任意浏览器标签页或网页中查看实时 iOS 模拟器——也可以是通过数据线连接的 iPhone，或 Android 模拟器或手机——并显示动画光标，准确指出 AI Agent 即将点击的位置；还可获取节省 Token 的 UI 快照，让 Agent 以精简文本而非截图读取屏幕。将任意屏幕录制为 MP4 或 GIF，用于 Pull Request。支持 Claude Code、Codex、Cursor 和其他任何 MCP 客户端。

状态：2.4。 Agent 工具、查看器、协议和嵌入 API 均已稳定，并且每个版本都会按照SimMirror 承诺不会破坏的内容进行检查。2.0 在模拟器之外支持真实 iPhone 和 iPad——通过数据线实时连接，并通过 WebDriverAgent 操控——还能将任意屏幕录制为 MP4 或 GIF。2.1 支持读取和触控横屏应用，避免点击被标签栏遮挡的区域，在 Agent 工作的 worktree 中构建应用，并为 Agent 不得更改的账户提供观察模式。2.2 增加 Android 模拟器和手机，共用同一查看器、光标和工具。拔掉的数据线重新接上后，2.3 会自动重新连接真实设备，向 Agent 说明无法触控设备的原因，并在运行前通过 sim_device health 检查设备。2.4 会让被人取回的手机保持原样，按实际运行时长录制，在不锁住 WebDriverAgent 的情况下读取长屏幕，等待精确匹配的文字，并允许一次仅由一个 Agent 操控真实设备。它没有移除 1.x 承诺提供的任何功能。

为什么选择 SimMirror

• 随时随地查看模拟器。 在 Chrome 标签页、iframe 或 <sim-mirror> Web 组件中查看实时 H.264 或 JPEG 视频流，并支持触控、滚动、输入、硬件按钮以及浅色和深色模式。
• 查看 Agent 的操作。 每个 Agent 手势都会在执行前显示，查看器中的光标会先滑向目标位置——你可以跟随操作并随时介入：Agent 会等待，直到你的手停止操作。
• 减少 Token 消耗。 Agent 可读取带有稳定元素引用和屏幕间差异的无障碍快照，配合等待批量执行操作，只有遇到视觉问题时才会使用截图。
• 读取无障碍功能无法识别的屏幕内容。 游戏或画布可通过像素读取内容，开发中的应用也可共享自己的视图，因此仅有图标的按钮和手绘控件也能按名称识别。
• 在真实 iPhone 上测试。 插上设备，它就会和模拟器并列显示：通过数据线以最高 60 fps 实时运行，可通过浏览器或 Agent 触控和输入，并会还原 SimMirror 对设备所做的所有更改。
• 展示操作过程。 将操作流程录制为 MP4 或 GIF，并在其中绘制每次触控，然后将录制内容添加到 Pull Request 中。

安装

Claude Code，搭配插件（工具、教授快照优先用法的技能，以及 /sim-mirror:open）：

/plugin marketplace add AndrewKochulab/sim-mirror
/plugin install sim-mirror@sim-mirror

任何 MCP 客户端，作为 stdio 服务：

claude mcp add sim-mirror -- uvx --from sim-mirror==2.4.0 sim-mirror mcp

Codex、Cursor 和 其他客户端的配置。

命令行工具，用于 sim-mirror open、doctor 等命令：

uv tool install sim-mirror==2.4.0
# or
brew install andrewkochulab/tap/sim-mirror

查看器库，供你自己的页面使用：npm install @andrewkochulab/sim-mirror （npm）。SimMirror 本身可在 PyPI 和 Homebrew tap 获取。

**要求：**Apple Silicon Mac、Xcode 26 或更高版本，以及 uv 或 Homebrew。无需其他条件：SimMirror 使用随软件包附带的专属辅助工具驱动模拟器。真机 iPhone 需要开启开发者模式，并且需要使用 Apple 开发团队。详情请参阅安装。

快速入门

sim-mirror doctor     # check this Mac, ending with a real tap on a simulator
sim-mirror open       # this project's simulator, live in a browser tab

然后向你的 Agent 提问：

打开“设置”→“通用”→“关于本机”，告诉我这台模拟器运行的是哪个 iOS 版本。请使用 sim_snapshot，而不是屏幕截图。

如果 iPhone 已连接、已解锁并处于开发者模式：

切换到我的 iPhone，在上面构建并运行应用，完成注册流程，并将过程录制为 GIF。

首次使用时，在查看器中按 Set up touch：它会使用你项目自己的签名团队构建 WebDriverAgent。

开始使用介绍了整个过程。

功能

**实时查看器。**页面支持解码时使用 WebCodecs 传输 H.264，否则使用 JPEG；每个连接会协商使用哪种方式。支持触控、拖动、滚动、输入和粘贴、主屏幕和锁定、浅色和深色模式，以及设备选择器。连接短暂中断后会自动重新连接；模拟器关闭时也会明确提示。

**Agent 光标。**每个 Agent 手势——轻点、长按、滑动、拖动、输入——都会在执行前传到查看器，查看器自身的指针也会先滑到目标位置（agent.cursor_lead_ms）。不会移动 Mac 的指针。

**屏幕理解。**快照只有几行——e2 button "General" (201,319)——包含可在滚动过程中保持与元素对应关系的引用、摘要和差异。sim_act 可在一次调用中执行多达 20 个步骤，并等待指定文本出现、消失或屏幕稳定下来——即使要等待的是加载动画，或永不停歇的脉动圆点。应用转为横屏后，会按其自身坐标读取和触控；sim_device rotate 可旋转模拟器；如果轻点目标被标签栏、工具栏或键盘遮挡，系统会拒绝操作并说明如何到达该位置。详见屏幕理解。

**观察模式。**在 Agent 不得更改的账户上进行操作演示时，agent.observe 会拒绝轻点看起来像“删除”“保存”“发送”或“退出登录”的控件——支持英语和另外 12 种语言，也会识别应用中标记为危险操作的样式——除非调用明确确认。详见安全性。

**读取像素。**如果屏幕的辅助功能信息为空——例如游戏、画布或仍在加载的应用——系统会将 macOS Vision 识别到的文字作为屏幕内容，并提供可轻点的引用和可供等待的文本；查看器还可以框出识别到的内容（perception.ocr）。详见从像素读取。

**应用 SDK。**正在开发的应用可以链接轻量级 Swift 软件包 SimMirrorKit，并调用 SimMirror.start()：在模拟器上的 Debug 构建中，它会共享应用自身的 UIKit 和 SwiftUI 视图，因此仅有图标的按钮、带轻点手势的卡片或手绘控件都能按名称识别；.simMirror("Settings") 则可为 SwiftUI 视图命名。此功能可选，Release 构建中不会包含任何相关内容。详见应用 SDK。 **真实设备。**通过线缆连接的 iPhone 或 iPad 会与模拟器一同显示，Agent 可以切换到它 （sim_device list 和 choose）：通过线缆实时显示屏幕，帧率约为每秒 55 帧；通过 Xcode 的 devicectl 查看其应用、日志、外观和位置；通过 WebDriverAgent 触控、输入文字并查看其元素树。WebDriverAgent 只需点击一次即可完成设置，并使用项目自己的团队签名——点击后约三分之一秒即可生效。设备只能通过线缆访问；释放设备时，SimMirror 会还原对其所做的更改。请参阅真实设备。

**Android。**Android 模拟器和手机会与模拟器并列显示，并使用相同的查看器、光标和工具：adb 可列出、启动并操控设备；scrcpy 的服务端只需点击一次即可完成设置，并可实时显示屏幕；UI Automator 可读取界面并生成快照；sim_build_run 和 sim_test 可使用项目自带的 wrapper 构建 Gradle 项目。手机不会被启动或关闭；SimMirror 对其所做的更改也会还原。请参阅Android。

**录制。**使用查看器中的 Record 按钮、sim_record 或 sim-mirror record，即可将设备屏幕保存为 MP4、GIF 或两者兼有，并在每次触控的位置绘制标记，还会显示 9:41 状态栏；使用 preset: "pr" 可生成足够小的文件，方便附加到拉取请求中。请参阅录制。

**连接器。**SimMirror 自带的原生辅助程序无需安装即可提供完整控制；也可以使用 idb_companion。如果两者都不可用，simctl 连接器会以只读方式镜像屏幕视图，并说明原因。auto 会使用可用的最快连接器，并在其失效时回退。还可以通过入口点接入更多连接器。请参阅连接器。

**嵌入。**通过带有一次性票据的 iframe、使用 CSS 自定义属性设置主题的 <sim-mirror> 元素，或在自己的 Python 应用中嵌入 SimMirror 并使用其独立登录。

设置面板。sim-mirror open --settings 会在查看器中提供所有设置，只需点击即可访问；每个部分都有独立标签页，设置可保存到单个项目或所有项目，并会在确认前应用。决定运行哪些内容或谁可以访问守护进程的设置，必须先输入 sim-mirror settings confirm 提供的代码才能应用。请参阅设置面板。

**诊断。**检查 Xcode、其 Simulator 框架、运行时、原生辅助程序和 idb_companion、Device Hub 和桌面会话、文本读取器及应用的共享层级结构，然后验证点击操作确实能传达到模拟器。请参阅诊断。

**安全。**仅限环回地址、Host 允许列表、精确的 Origin 检查、仅对列出的来源启用 CORS 和框架嵌入、经过哈希处理且有作用域限制的令牌，以及放在 URL 片段中的一次性代码。请参阅安全。

构建和测试。sim_build_run 和 sim_test 会使用 xcodebuild 为 Agent 的模拟器构建、安装并启动应用，回复中只会说明失败内容和位置——逐一列出失败的测试，以便单独重新运行；按要求也可在另一台模拟器上运行——并提供构建所用的文件夹、分支和提交。它们会使用 Agent 工作所在的 git worktree，以及其方案运行时使用的配置进行构建。此功能默认关闭，因为它会运行命令：sim-mirror config set build.tools true。

测量 token 成本

benchmarks/tool_budget.py 会通过客户端使用的同一 MCP 中继调用每个只读工具，并在你自己的屏幕上打印每个回答的字节数、预估 token 数和延迟；请参阅 token 预算示例。在显示“设置”→“通用”的 iPhone 17 Pro 模拟器上（iOS 26.5，idb 连接器），每项调用 5 次（2026-09-16）：

调用	工具	字节数	Token（预估）	p50 毫秒	p95 毫秒
设备信息	sim_device	265	46	2.9	3.6
快照，完整	sim_snapshot	561	112	64.8	76.4
快照，未变化屏幕的差异	sim_snapshot	83	5	63.2	64.8
截屏，宽 400 px	sim_screenshot	62222	469	8.2	8.9
截屏，宽 1200 px	sim_screenshot	276472	4181	20.4	21.9

字节数是完整回答的大小，包含图像的 base64；token 数为预估值（文本约每 4 个字符 1 个 token，图像约每 750 像素 1 个 token）。

兼容性

	预期可用
macOS	26（搭配 Xcode 16.4 的 15，仅查看）
Xcode	26 和 27
连接器	原生辅助工具（完整控制）、idb_companion 1.5（完整控制）、simctl（仅查看）
真机	Xcode 的 devicectl 可连接的 iPhone 或 iPad，通过线缆连接（没有 WebDriverAgent 时仅查看）
Android	adb 可连接的模拟器和手机，需 Android SDK；实时屏幕需 scrcpy 5.0.1；支持 Gradle 构建
App SDK	iOS Simulator 上的调试构建，iOS 16 或更高版本
客户端	Claude Code、Codex、Cursor，以及任何 stdio MCP 客户端
浏览器	Chrome、Safari、Firefox、Edge

在真机上验证过的行会在 兼容性 中标注验证状态和日期。

从 1.0 起，工具、协议、嵌入 API、查看器包、设置和命令行均遵循 SimMirror 承诺不会破坏的内容：每个版本只添加功能，绝不造成破坏；2.0 没有破坏任何内容。连接器是例外，会固定到次要版本。

文档

全部文档：快速入门、客户端、嵌入、屏幕理解、连接器、安全、架构，以及 工具、配置、命令行和协议参考。

路线图

里程碑	带来的功能
v0.1（预览版）	实时查看器、Agent 光标、人员和 Agent 控制、MCP 工具、sim-mirror doctor、idb 和 simctl 连接器，以及作为预览版进行构建和测试
v0.2	构建、运行和测试工具，设置面板，通过 mcpbridge 查看 Xcode 27 的 UI 层级结构，以及供多个主机共用的守护进程
v1.0	稳定的协议和嵌入 API，通过检查来确保稳定；PyPI、npm 和 MCP Registry；Agent 工作时保持显示的光标
v1.2	使用 SimMirror 自带的原生辅助程序替代 idb_companion，通过屏幕像素读取屏幕并在动画结束后稳定下来，可选的应用内调试 SDK，以及 Homebrew tap
v2.0	真正的 iPhone 和 iPad：通过线缆传输实时屏幕，无需签名即可使用应用、日志、外观和位置；通过 WebDriverAgent 实现完整控制；将屏幕录制为 MP4 或 GIF
v2.1	将应用切换为横屏和 sim_device rotate，避免点击被状态栏遮挡的区域，构建 Agent 的工作树，观察模式，sim-mirror stop，以及适合拉取请求的录屏尺寸
v2.2	Android 模拟器和手机，使用相同的查看器、光标和工具：adb、scrcpy 的实时屏幕，以及 Gradle 构建
v2.3	线缆拔出后可自行恢复的真实设备、sim_device health、告知 Agent 设备为何无法操作，以及不会因缓慢读取而锁定设备的文本读取器
v2.4（当前）	能在真实 iPhone 上可靠运行的 Agent：人员拿回手机后不再干预 WebDriverAgent，按实际运行时长录制，读取长屏幕时不会卡住，支持精确匹配和正则等待，点击前检查 refs，支持 iOS 27 的浮动搜索栏，以及每台设备同时只运行一个 Agent
网站和发布	落地页、视频教程和指南

请参阅 ROADMAP.md 和里程碑。关于 SimMirror 与其他工具的关系，请参阅比较。

贡献

欢迎贡献。请阅读 CONTRIBUTING.md 和行为准则；AI 编码 Agent 请阅读 AGENTS.md。请按照 SECURITY.md 中的说明私下报告安全问题。 如有疑问，请前往讨论区。

许可证

Apache-2.0。请参阅 NOTICE 和 THIRD_PARTY_LICENSES.md。

SimMirror 是一个独立项目，与 Apple 或 Anthropic 没有关联。iOS、iPhone、Xcode 和 Simulator 是 Apple Inc. 的商标；Claude 和 Claude Code 是 Anthropic PBC 的商标。