simframe

simframe

为操控 iOS Simulator 或 Android 模拟器的编码 Agent 提供眼睛、双手和记忆。 Agent 可将屏幕内容作为带点击位置的文本读取，一次调用即可运行完整流程，还能记住见过的屏幕，因此不必为每一步都支付截图、模型往返和重新读取的开销。

同一应用会话，Token 消耗仅为一小部分。 在真实的 React Native 实地应用中，Agent 端到端完成了两项工作并真实提交：创建服务请求，以及添加资产。以下为 2026-10-03 每次运行的测量数据：

操控者	两项工作均完成	工具调用次数	截图数	Token 数
使用 Claude Code 内置模拟器工具的 Opus，不使用 simframe	是	~176	112	296k
使用 simframe 的 Opus	服务请求（会话因资产上传而受阻）	~50	≥4	118k
使用 simframe 向 Sonnet 操控者（插件的操控 Agent）下达指令的 Opus	是	~88	少量	128k，使用成本更低的模型

使用同一模型，有无 simframe 的对比：Token 减少 2.5×，调用次数减少 3.5×。 Sonnet 操控者完成了不使用 simframe 时的全部工作，Token 减少 2.3×，调用次数减半，而图片只用了少量（不使用 simframe 时用了 112 张）。每种配置仅运行了一次，因此应将其视为测量示例，而非普遍比率；完整说明（包括未展示的内容）见 docs/BENCHMARKS.md。它的速度还远不及人类，这一点也有测量数据。 熟悉该应用的人完成同样两项工作只用了约 1.5 分钟（五次运行的中位数分别为 39 秒和 49 秒）。Agent 耗时 13–16 分钟，慢了 9–10×，因为它们会读取并验证每一步，而且每轮模型调用都要耗费数秒。减少每个流程的轮次，以及从记忆中重放流程，正是路线图的重点。

十秒内完成安装

你需要一台安装了 Xcode 的 Mac（如果你有模拟器，就说明你有 Xcode）和 Node 18+。 不需要其他任何东西——不需要 idb、Appium 或 Python。

Claude Code — 作为插件安装，插件会一并安装 MCP 服务和 技能，在一次安装中教会 Agent 使用该协议：

claude plugin marketplace add lvlrSajjad/simframe
claude plugin install simframe@simframe

或者只安装 MCP 服务：

claude mcp add --scope user simframe -- npx -y simframe mcp

插件还附带一个驱动 Agent（simframe:simframe-driver）：主会话把目标交给它，它就会使用 Sonnet 和 simframe 的工具来操作模拟器，然后返回简短报告。它仅限使用 simframe，因此即使是小模型也能胜任；如果开放所有工具，Haiku 就做不到。**驱动 Agent 需要先安装上面的插件。**它绑定到插件自己的工具名称，因此单独使用 claude mcp add 添加服务并不能启用它。

二选一，不要两种都装：安装两次意味着两个服务会操作同一台设备。如果之前用 claude mcp add 添加过，请先运行 claude mcp remove simframe。

Claude Desktop — 打开 Settings → Developer → Edit Config，然后添加：

{
  "mcpServers": {
    "simframe": { "command": "npx", "args": ["-y", "simframe", "mcp"] }
  }
}

Cursor — 或将相同的 simframe 配置块添加到 ~/.cursor/mcp.json。

Codex、Windsurf、Zed、VS Code，以及其他任何支持 MCP 的客户端 — 使用相同的 JSON 配置块，放在该客户端存放 mcpServers 的位置。

然后启动模拟器，并让 Agent 执行某项操作：“打开我的应用，完成注册流程”、“Orders 标签页里的列表正在加载吗？”、“为什么点 Save 按钮没有反应？”。首次调用时会从源代码构建一个小型 Swift 守护进程——大约 15 秒，只需一次。

CLI 是不经过 Agent 的同一套功能，也是检查安装是否成功的最省事方法：

npm install -g simframe
simframe doctor          # every layer, and which engine carries it
simframe ui              # the current screen as a numbered text map

如果启动了多个模拟器，请使用 --device=<udid> 或 export SIMFRAME_DEVICE=<udid> 指定目标设备；simframe 不会猜测，因为选错设备时可能执行的操作就是点击。

它带来的改变

Agent 操作模拟器很慢，原因有三个，而只有第一个显而易见。每次查看都要等待（simctl io screenshot 需要约 130 ms，每次查看都要付出这个代价）。每一步都需要一次模型往返。并且系统不会记住任何内容，因此每次出现同一屏幕时，都要重新读取和推理。还有第四个纯粹的浪费：用图像询问屏幕上有什么，代价最高，而且仍然无法说明哪些位置可以点击。

	不使用 simframe	使用 simframe
查看屏幕	截图需要约 130–400 ms，且会阻塞	约 20 ms，已提前捕获
“有什么变化吗？”	一张完整图像	约 2 ms，仅文本
读取屏幕	一张图像，约 1,600 个 token，没有点击位置	约 330 个 token 的文本，包含点击位置
10 步流程	10 轮，10 张图像	1 轮，0 张图像
再次执行同一流程	每次运行都从头开始	从记忆中重放，每一步都经过验证，零次模型调用
实际的双任务应用会话	约 176 次调用、112 张截图、296k 个 token	约 50 次调用、118k 个 token（相同模型）

数据是在 iPhone 17 Pro 模拟器、iOS 26.5、Apple Silicon 上，针对一款实际生产应用测得的；包含 N、median 和 p95 的完整表格见 docs/BENCHMARKS.md。

Agent 收到的不是图片，而是以下内容：

iPhone 17 Pro · 402x874pt · screen a1b2c3d4 "Inbox" (known, 3 known exits)
last action: [2] tap — ok: matches the outcome seen 5x before
nav-bar:
  #1 button    24,64      Back
  #2 text      201,64     Inbox
content:
  #3 cell      201,140    Weekly digest
  #4 field     201,196    Search = weekly ~ weekly|
  #5 switch    201,252    Notifications = 1
tab-bar:
  #6 text      62,835     Inbox
  #7 text      201,835    Settings
next: settled; nothing ambiguous — chain the next steps in one sim_do without looking again.

区域、类型、标签、内容、点击位置，以及下次调用可用作选择器的编号。= value 表示无障碍树报告的控件内容；~ value 表示 OCR 从像素中识别出的内容。两者不一致之处，正是关键所在。

工具

工具	功能
sim_ui	从这里开始。 屏幕内容如上方带编号的文本地图所示。
sim_do	主要工具。 一次调用即可完成整个流程 — 点击、输入、滚动、等待、断言 — 每一步都会先稳定下来再执行下一步，并根据上次执行的结果进行验证。备用选择器、可选步骤和范围受限的 seek 可让批处理在遇到意外时继续运行，而不是中途交还控制权。
sim_state	自上次查看后是否发生变化，以及哪些区域移动了。
sim_goto · sim_flow_run	前往 simframe 之前到过的屏幕；重放已保存的流程，无需调用模型。
sim_goal	说明要到达的位置；simframe 会在本地驱动操作，并在某个里程碑处返回 — 已完成且有证据、被障碍阻挡、情况不明确，或未找到。
sim_map	默认以只读模式在无人值守的情况下遍历应用，并记录每个屏幕和转换，让后续工作可以利用记忆执行。绝不会跨越验证屏障或离开应用。
sim_find · sim_tap · sim_type_into · sim_scroll_to · sim_wait_for · sim_assert	单步操作，仅在确实只需执行一个步骤时使用。
sim_launch · sim_open_url · sim_permission	启动（已确认切换到前台）、打开深层链接、授予隐私权限而不点击警告提示。
sim_look	唯一会返回图像的工具，图像上限为 1024 px — 用于查看布局、颜色和间距。
sim_recall · sim_strip · sim_storage	以文本或联系表形式查看过去一分钟内发生的情况；查看应用保存的内容（UserDefaults、AsyncStorage），即使设备已关机也可以。
sim_wait · sim_capture · sim_devices	等待变化后再稳定下来；管理捕获；列出模拟器和仿真器。

在任何需要指定控件的位置，都有三种命名方式："Save"（按意图解析 — 动词、拼写错误、同义词，以及按常见名称识别的纯图标控件）、#3（地图为控件分配的编号，仅在该屏幕上有效），或 @120,400（原始坐标，仅在前两种方式不适用时使用）。与危险操作词汇匹配的标签 — Delete、Pay、Send、Sign out — 永远不会被替代或猜测。

软件包随附一个 Claude Code 技能，用于教授 CLI 路径，开销更低：输出只有几行，而不是工具结果；直到使用工具时，MCP 架构才会进入上下文。

Android

第二个后端可通过相同的命令、屏幕地图和记忆驱动 Android 仿真器。帧通过仿真器控制台以约 41 ms 的间隔到达；点击、滑动、文本、按键和剪贴板均可正常使用；simframe devices 会将仿真器与模拟器一起列出。Android 不具备的是无障碍树，因此它的屏幕只能依靠 OCR 和 CV 读取 — simframe doctor 会如实说明这一点，而不会假装支持。详情、成本和原理请参阅指南。

简要说明其工作原理

每台设备运行一个 Swift 守护进程；当显示器报告损坏时，该进程会直接从 IOSurface 读取模拟器的帧缓冲区，在同一表面上运行 Apple 的 Vision OCR，在主机端读取无障碍树，并通过 HID 通道发送真实的按下／移动／抬起序列来执行点击 — 无需 PNG、文件或启动子进程。帧存储在 ~/.simframe/<udid>/ 中，输入通过 0600 Unix 套接字传输，MCP 服务和 CLI 则是连接这两者的轻量客户端。

屏幕记忆通过结构指纹为合并后的元素地图建立索引，因此再次看到之前出现过的屏幕时，只需读取文件。转换图会记录哪个操作使流程从哪个屏幕转到哪个屏幕，因此 sim_goto 可以规划路线，已保存的流程也可以在模型不参与的情况下重放。

每一层都会降级而不是失败，并且绝不会悄无声息：simframe doctor 会报告每一层的状态，而 --strict 会将任何降级转为非零退出。守护进程链接的私有框架及其证据记录在 docs/PRIVATE_API.md 中。

延伸阅读

docs/GUIDE.md	完整指南：无需往返即可恢复、屏幕记忆和两个哈希值、凭记忆导航、命令行、诊断卡住的模拟器、控制会话成本、路线图
docs/BENCHMARKS.md	每项数据，包含 N、中位数、p95、机器和测量陷阱
docs/EXPERIMENTS.md	测量前的设想，以及它们有十四次都是错的
docs/DECISIONS.md	改变计划的判断，包括一个被自身测量结果取消的阶段
docs/DEFERRED.md	所有已知缺陷，无论开放还是已关闭，并附有证据
docs/ARTICLE.md	Agent 不该眨眼——对整个项目的总结论述

这里几乎所有决定都由测量结果而非争论得出，而且有几次测量推翻了已经发布的决定。两项重要结果：预热后的转移图可减少 Agent 约 27% 的大模型往返次数；而对守护进程已计算出的一个数值应用单行阈值，作为步骤监督器的表现胜过所有尝试过的本地模型——准确率达 95%，而它们为 77–91%，且延迟为零。

局限性

• 仅支持模拟器和仿真器；无法连接任何实体设备。
• 守护进程链接了私有框架。这些框架经受住了 iOS 26 的升级，但升级 Xcode 可能会导致符号变动；doctor 会指出出错的层，而 --engine=screenshot 仍可使用。
• Android 没有无障碍树，因此其屏幕身份仅依赖 OCR 几何信息：比 iOS 更粗略，也更嘈杂。
• 硬件按钮：仅支持 home。其他代码未经验证，错误代码可能导致设备崩溃，因此会返回错误，而非猜测。
• 确认操作的词汇（OK、Save、Done……）为英文。
• 它能加快确认修复，而非定位修复。陈旧闭包中的错误不会出现在任何帧中。

完整列表及每项背后的测量数据，请参阅指南。

发布

只有 npm version 可以用于升级版本——它的钩子会同步更新 server.json——而 git push --follow-tags 会运行一个工作流，在不使用机密信息的情况下发布到 npm 和官方 MCP Registry。关于这种设计的原因，以及曾经消失一周的那次发布，请参阅指南。

许可证

MIT