eas-simulator

EAS Simulator

**EAS 服务会产生费用。**会话会计入你账户的定价和限额，并会在达到最长时长后停止。任务完成后，使用 eas simulator:stop 停止会话。当前条款请参阅 https://expo.dev/pricing。

EAS Simulator 可在 EAS 基础设施上运行远程 iOS 模拟器或 Android 模拟器，并让你通过自己的机器操控它——可通过 CLI、AI Agent（使用 agent-device）和浏览器预览进行操作。它能解锁无法在本地运行模拟器的环境（Linux 机器、Cursor Cloud 等云端／后台 Agent），还可以让 Agent 在真实设备上验证更改，而不仅仅是推理代码。

simulator:* 命令目前属于实验性隐藏命令，需要较新版本的 eas-cli（撰写本文时为 ≥ 20.3.0），因此此技能会通过 npx --yes eas-cli@latest 运行所有命令。标志和动词可能会改变；应以相关子命令的 --help 输出为准。

适用场景

frontmatter 中的 description 包含触发短语。简而言之，可用此工具将用户的应用部署到云端模拟器并与之交互——尤其适用于没有 Mac 的环境或云端／沙盒 Agent。不适用于本地模拟器（expo run:ios、Xcode、Android Studio）、应用商店构建／签名（应使用 EAS Build）或实体设备。如需了解 macOS 情况，请参阅下一节 云端与本地。

云端与本地：先做判断

• **明确要求使用云端／远程／可共享环境：**检查访问权限后，在任何主机上使用 EAS Simulator。
• **一般性的模拟器请求：**如果有合适的本地模拟器，则使用本地模拟器。如果主机无法运行所需的模拟器（例如 Linux 上的 iOS 模拟器或云端沙盒），则检查访问权限后使用 EAS Simulator。非 macOS 主机仍可能支持本地 Android 模拟器。
• 尊重用户明确选择的本地环境；酌情使用 expo run:ios / Xcode / Android Studio。仅当所请求的环境仍不明确且会影响任务时，才进行澄清。

用户要求使用 EAS Simulator 或云端模拟器时，立即启动会话并完成所请求的工作，无需再次询问。工作完成后停止会话。只有当用户设定的限制即将被超出，或工作范围超出用户要求时，才需与用户确认。

前置条件

• 通过 npx --yes eas-cli@latest … 运行每条 eas 命令——确保使用包含 simulator:* 的新版 CLI（全局安装的 eas 通常太旧），而 --yes 可跳过 npx 的提示。（如果 eas --version 显示的是当前版本，也可以直接使用 eas。）
• 已完成身份验证。 交互式机器 → npx --yes eas-cli@latest login。云沙盒 / CI / 无头 Agent 无法通过浏览器登录——请改为在环境变量中设置 EXPO_TOKEN（前往 expo.dev → Account → Access Tokens）。无论使用哪种方式，都通过 npx --yes eas-cli@latest whoami 验证。
• 在 Expo 项目目录中运行。全新应用需要一次性设置：运行 npx --yes eas-cli@latest init 创建 / 关联项目（没有 projectId 时），如果应用配置中缺少 ios.bundleIdentifier，也需要设置它——新建的 create-expo-app 通常没有此项，而 prebuild / eas build 需要它（缺少时会提示或失败；例如 dev.<owner>.<slug>）。运行 npx expo config --json 查看当前配置（配置也可能位于 app.config.js 中）。首次 Mode-C 运行会比较慢（需要原生构建）；后续运行会复用构建结果。
• 用于操控设备的控制器。本技能使用 agent-device（开源，MIT），按需通过 npx agent-device@latest 运行——无需全局安装。Appium 和 argent 是其他自动化接口；web-preview-only 不提供自动化接口。详见 references/controllers.md。
• .env.eas-simulator 由 eas-cli 写入和管理（而非本技能）：其中保存会话 ID（EAS_SIMULATOR_SESSION_ID）和守护进程 URL / token，因此 get / stop / exec 默认使用该会话（通常省略 --id；要指定其他会话，请传入 --id <id>）。文件中包含 token → 请确保将其加入 gitignore（eas-cli 会将其标记为“不要提交”，但可能不会添加忽略规则，而且新应用的 .gitignore 不会涵盖它——如果缺少，请添加 .env.eas-simulator）。
• 命令块默认使用 POSIX shell（bash/zsh）——printf、lsof、$(seq …) 循环无法在 cmd/PowerShell 中运行。在 Windows 上，请在 WSL 或 Git Bash 中运行，或边运行边转换命令（eas-cli / agent-device 调用本身支持跨平台）。

会话生命周期

• --max-duration-minutes N 是自动停止的硬性时限。任何套餐都可以设置此值，但不得超过套餐限制（Free 套餐为 40 分钟，付费套餐为 115 分钟）。计时从会话就绪时开始。
• --max-idle-time-minutes N 会在会话闲置指定分钟数后停止会话。省略此参数表示不设闲置超时：会话将持续运行，直到达到最长时长或被明确停止。
• 控制器活动会重置闲置计时器（agent-device、argent 和 Appium 命令，这些命令会作为生产者为 appium 的会话事件记录）。浏览器预览活动不会重置计时器。 对于由用户操作的浏览器预览，请依靠最长时长而非闲置时间来限制会话时长。

先检查是否可用

EAS Simulator 是一项访问受限的 EAS 功能，目前仍在逐步推出，因此并非所有账户都已启用。请在启动会话前检查访问权限；此只读命令不会创建会话。

npx --yes eas-cli@latest simulator:availability --json
# → {"available": true, ...}  enabled → continue to the core loop
# → {"available": false, ...} not enabled → do NOT start a session

如果不可用，请勿调用 simulator:start（该命令会失败）。请改为妥善转交任务，以便在不使用本技能的情况下继续推进：

• 告知用户其账户尚未启用 EAS Simulator——该功能即将推出。
• 针对实际目标，改用常规本地方案——例如使用 expo run:ios / Xcode / Android Studio 运行本地模拟器 / 仿真器、进行 EAS Build，或采用其他合适方案。不要让任务卡在云端模拟器上；用户几乎从来不会特别要求“必须使用 EAS Simulator”。

（如果无法识别 simulator:availability，说明 CLI 太旧——请升级；或者，如果 simulator:start 报错 not enabled for this account，也按同样方式处理：停止并改用其他方案。）

核心循环（始终相同）

一个会话包含：启动 →（安装你的应用）→ 操作 → 停止。 eas-cli 负责管理会话；设备操作（打开／点击／截图）由控制器提供，npx --yes eas-cli@latest simulator:exec 会为你运行控制器，并加载会话的连接环境变量。

# 1. Start a session (boots the remote sim + agent-device daemon; writes .env.eas-simulator).
# If the dotenv names a session, inspect it with simulator:get --json first. Reuse it when it
# belongs to this run; stop it only when it is in scope and no longer needed. An IN_PROGRESS
# session may be intentionally concurrent, so preserve its id/config before resetting the dotenv.
# Continue below only after choosing how to handle that existing session.
printf '# managed by eas-cli\n' > .env.eas-simulator   # clear only after resolving any live session
npx --yes eas-cli@latest simulator:start --platform ios --type agent-device --non-interactive \
  --name "Checkout flow screenshots"   # always name it — see 'Always name the session'
#    Then confirm it's live: simulator:get --json → status IN_PROGRESS (bounded poll in run-your-app.md).

# 2. Drive it through `exec` (loads the session env, then runs the command you give it).
#    agent-device runs on demand via npx — nothing installed globally.
npx --yes eas-cli@latest simulator:exec npx agent-device@latest open <app-or-url> --platform ios
npx --yes eas-cli@latest simulator:exec npx agent-device@latest snapshot -i          # interactive UI tree → @e1, @e2 refs
npx --yes eas-cli@latest simulator:exec npx agent-device@latest press @e2            # tap a ref (use 'press' or 'click')
npx --yes eas-cli@latest simulator:exec npx agent-device@latest screenshot ./shot.png

# 3. Stop the session and reset the dotenv. Omit --id to target the dotenv session.
npx --yes eas-cli@latest simulator:stop
printf '# managed by eas-cli\n' > .env.eas-simulator

要实时查看，请将 start 输出的 webPreviewUrl 提供给用户（在 --json 中为 remoteConfig.webPreviewUrl；对于 web-preview-only 会话，则为 remoteConfig.previewUrl）。所有当前会话类型都包含浏览器预览，支持 iOS 和 Android；agent-device、appium 和 argent 还提供自动化功能，而 web-preview-only 不提供自动化接口。在 Android 上，expo.dev 会话页面目前还不会内嵌显示预览：Open preview 会在新标签页中打开预览。Android 支持仍在开发中，因此部分 iOS 功能可能无法在 Android 上使用。此 URL 供用户的浏览器使用——你无法代替用户打开它，而且绝不能在模拟器中打开：

• “在这里打开”（Cursor/VS Code） → 单独一行输出 URL，并告知用户打开 Simple Browser（Cmd/Ctrl+Shift+P → “Simple Browser: Show”）并粘贴 URL。然后停止：不要调用系统浏览器或 Cursor/VS Code URL 处理程序，也不要询问“是否打开了标签页？”——你无法确认，交接到此为止。
• 绝不要在模拟器中 open webPreviewUrl。 这是浏览器预览，不是深层链接，也不是 agent-device open 的参数；将其路由到设备会导致浏览器中嵌套浏览器（这是过去实际发生过的问题）。
• 无头 Agent（无显示器）→ 直接将 URL 作为交付内容返回。
• 让用户继续操作并保持会话运行 → 使用 --max-duration-minutes N（最多不超过计划限制）。浏览器预览活动不会重置 --max-idle-time-minutes，因此对于这种情况，空闲超时不能可靠地作为会话时长上限。根据 CLI 报告的时长或到期时间告知用户会话何时过期。对于用户请求的预览，请保持会话运行；对于一次性任务创建的会话，则在任务完成后停止。

start 还会输出一个作业运行 URL。

始终为会话命名

每次运行 simulator:start 时，都传入 --name "<description>"。该名称会显示在 simulator:list、simulator:get 和 expo.dev 上的 Simulator sessions 页面中，并取代每一行上的通用标题。若不命名，每一行都会显示“Simulator session”和一个随机 ID——满屏都是无法区分、无从查找的相同条目。命名时要考虑几天后浏览列表的人，而不是这次运行中的自己。

用几个简单的词说明会话的用途：

--name "Checkout flow screenshots"     # what you did
--name "Dev build — dark mode fix"     # what you were testing
--name "Login repro for issue 412"     # why it exists

规则：

• 根据用户的请求来命名，不要根据模式或工具来命名。Mode C session、agent-device ios 和 test 都毫无信息量。
• 长度：建议 3–6 个词、约 40 个字符，并将 50 个字符视为实际限制。 名称会显示在窄表格列中的单行标题里，过长就会被截断。API 最多接受 255 个字符，并会拒绝空名称或仅含空白字符的名称，但 255 是绝不能接近的上限，而不是目标。使用一个名词短语，不要写完整句子。
• 在长度限制内尽量具体。如果有工单或 PR 编号，请加上。
• 句首字母大写： 只将第一个词的首字母大写，标识符保持其原有大小写（Dev build for expo-router v4、Repro for EXPO-1234）。这是行标题，因此不要使用标题式大小写、全小写，也不要在末尾加句号。
• 不要重复表格中已有的信息。 每一行都会显示会话 ID、平台、开始时间、持续时间和创建者，因此不要写 ID、iOS、日期或你自己的名字。将全部字数用于说明这些列无法表达的内容：用途。
• 如果用户为会话指定了名称，请原样使用。
• 会话按次运行区分，因此每次新运行都要根据该次运行命名。不要将旧名称用于不同的工作。

--name 比 simulator:start 本身更新，因此较旧版本的已安装 eas-cli 可能会拒绝该参数。若发生这种情况，请通过 npx --yes eas-cli@latest 运行，或升级；作为最后的手段，不带 --name 重试一次（会话将以未命名状态启动）。请参阅 references/troubleshooting.md。

命令速览

在使用非默认启动标志、机器可读／配置输出、列表筛选条件或会话事件之前，请查询已安装 CLI 当前完整的标志集合：

# Replace `start` with the simulator subcommand you are about to run.
npx --yes eas-cli@latest simulator:start --help

以下示例涵盖常见工作流；它们有意不完整复制 CLI 的所有功能。即使根据 --help 构造命令，也要保留此技能中的非显而易见行为指南，尤其是会话生命周期。

命令	用途
npx --yes eas-cli@latest simulator:availability [--json] [--non-interactive]	检查访问权限，不创建会话。
npx --yes eas-cli@latest simulator:start --platform ios|android --name "<description>" [flags]	创建会话；启动模拟器和所选界面；默认写入 .env.eas-simulator；打印预览和作业运行 URL。始终传入 --name。--json 不会禁止写入 dotenv；如果不应写入文件，请使用 --out-config-type env（它只打印控制器的 export 行，不包含 EAS_SIMULATOR_SESSION_ID，因此需传入 --id 才能执行 get／stop／events）。
npx --yes eas-cli@latest simulator:exec <cmd> [args…]	加载 .env.eas-simulator，然后使用其中的环境变量运行 <cmd>。这是连接控制器的桥梁。
npx --yes eas-cli@latest simulator:get [--id <id>] [--json] [--non-interactive]	显示会话状态和连接详情，包括会话名称。用它确认就绪状态（参见操作原则）。
npx --yes eas-cli@latest simulator:list [filters] [--limit N] [--after <cursor>] [--json]	列出项目会话并分页；可按状态、类型、平台、名称前缀和标签筛选。
npx --yes eas-cli@latest simulator:events [--id <id>] [--follow|--json]	显示记录的活动事件；--follow 会持续监视，直到会话结束。
npx --yes eas-cli@latest simulator:stop [--id <id>] [--json] [--non-interactive]	停止会话（可重复执行）。

运行用户的应用 — 选择一种模式

远程模拟器启动时是空白的 — 没有 Expo Go，也没有任何应用。先安装构建产物，再操作应用 — 但首先要让构建类型与目标相匹配（见下方方框）；实时会话运行出问题，往往就是因为这里没选对。完整流程：references/run-your-app.md — 运行某种模式前请先阅读。

**安装任何内容之前，先让构建与目标相匹配 — 实时会话运行出问题，往往就是因为这里没选对。**有两个陷阱，根源相同（拿到的构建不符合请求）：

1. **类型错误。**实时编辑（模式 C）需要开发构建。静态构建 — 本地 Release（A）、默认的 EAS 模拟器构建（B），或之前运行截图时留在模拟器上的任何构建 — 都会在构建时冻结其 JS，永远无法热重载。对于实时请求，完全忽略现有构建，并安装一个开发构建（本地 Debug，或 developmentClient: true 的 EAS 构建）。绝不要把 Metro 重新连接到静态构建并指望它会重新加载 — 它不会。
2. **过时。**静态外观必须与当前源码一致 — 只有指纹匹配的构建才能复用，否则就重新构建；复用必须是明确要求的。

因此，遗留的 EAS/Release 构建不能用来走捷径实现“实时迭代” — 它是错误的二进制文件。构建存在并不意味着它就是正确的构建。

模式	内容	适用情况	支持实时编辑？
A — 本地 Release 构建	在本地构建 Release .app，并用 agent-device install 安装（上传）	用户有 Mac 工具链，并希望快速“在云端设备上运行我当前的代码”	否（要查看更改，需重新构建）
B — EAS 构建（少见，仅限明确要求）	使用 eas build 构建模拟器版本，再用 agent-device install-from-source <url> 安装（由 VM 下载）	仅在用户明确要求时 — 用户指定了现有/EAS 构建，或需要用于 CI/共享的静态 EAS 构建产物。不要用于“给我看看”/“迭代”（请使用 C）。模拟器构建无需凭据。	否
C — 本地开发构建 + 隧道	开发（Debug）构建 + EXPO_UNSTABLE_TUNNEL_V2=1 expo start --tunnel + 将开发客户端连接到 Metro	Agent 式的编辑并查看循环 — 修改代码并实时查看（Fast Refresh）	是

快速决策 — 默认选 C；A 和 B 仅限明确要求：

• **C（几乎所有情况）：**迭代、交互、操作应用、实时编辑 — 以及大多数“给我看看我的应用”（当前代码无论如何都需要构建，因此实时且最新更合适）。有 Mac → 在本地构建开发客户端；没有 Mac → 在 EAS 上构建（developmentClient: true）。不确定 → 选 C。
• A：仅适用于在 Mac 上明确要求的一次性静态截图。
• **B：**仅当用户指定现有/EAS 构建，或需要静态 EAS 构建产物（CI/共享）时使用 — 关于静态构建为何不适合“迭代”，请参阅上方方框。

启动模式 C 隧道或连接开发客户端之前，请阅读隧道范围与审批。在创建隧道、建立连接和进行实时编辑时，沿用针对本项目远程开发传输的现有授权；在任何审批请求中，说明授权来源及具体的数据流。

控制设备（agent-device）

如果控制器无法下载录制文件，请从 EAS 会话产物中获取。

agent-device 是控制器。常用动词（每条都以 npx --yes eas-cli@latest simulator:exec npx agent-device@latest <verb> 运行）：

动词	功能
apps --platform ios	列出用户安装的应用（空白模拟器中不会显示任何应用）；添加 --all 可包含系统应用
install <appId> <path> --platform ios	安装本地 .app（会上传该文件）
install-from-source <url> --platform ios	从 URL 安装——由 VM 下载（用于 EAS 产物）
open <appId|deep-link> --platform ios	启动应用（bundle id）或打开应用深层链接（exp+slug://…）。首次打开深层链接时会弹出系统 **“在‘’中打开？”**对话框——请预期会出现（不要为了发现它而浪费快照），并运行 press 'label="Open"' 以继续；该操作可能较慢，因此请使用 agent-device 自带的 --timeout 限定时间（例如 press 'label="Open"' --timeout 120000）——不要用 shell timeout 包装器（macOS 没有 timeout 二进制文件）。（模式 C 通过“手动输入 URL”绕过 Metro 连接链接的此对话框——参见 run-your-app.md。）不要用于 webPreviewUrl——那是供用户使用的浏览器预览，不是设备。
snapshot -i	交互式无障碍树 → @e1 样式的引用
press <ref|selector>	点击（例如 press @e2 或 press 'label="Open"'）。click <target> 也可用。请使用 press 或 click：tap 是隐藏别名，旧版本会拒绝该命令
fill <ref> "text"	在字段中输入文本
screenshot <path>	将屏幕截取为本地 PNG（从守护进程下载）——需要先打开应用（先运行 open）。在 iOS 上，默认使用 1x 逻辑点（iPhone 17 上为 402x874）；添加 --pixel-density 3 可获取完整分辨率
record start [path] / record stop	将屏幕录制为视频，保存到 record start 指定的路径（record stop 不接受路径）——用于动态画面（动画、手势、过渡、时序），这些内容无法通过单张截图捕捉
metro prepare / metro reload	将开发客户端指向 Metro / 重新加载（模式 C）

截图与视频。静态状态默认使用 screenshot，但凡是会动的内容——动画、过渡、手势或时序/卡顿问题——都应录制视频并检查其中的帧；静态图无法证明动态效果。两种控制器都支持录制（agent-device record start/stop，argent screen-recording-start/stop）。录制以约 30fps 采样——足以观察明显卡顿，但无法证明低于单帧时长的 60/120Hz 卡顿。具体到时序，argent 默认会丢弃静态帧（关闭 trimStatic 即可）；这一点以及各控制器的其他注意事项，参见 references/controllers.md。

完整动词列表以及 argent 控制器替代方案，请参见 references/controllers.md。

应用崩溃时：设备日志和崩溃报告（iOS）

当应用崩溃或启动时关闭，请先读取 iOS 会话的崩溃报告和设备日志，再根据截图猜测。请从 simulator:get --json 返回的预览 API URL 中读取。这一 URL 携带会话令牌，因此切勿打印。

**重现崩溃前先保留设备日志。**如果不先保留，虽然会生成崩溃报告，但日志尾部将为空。命令、字段和回退方案参见 references/logs-and-crashes.md。

操作原则

值得内化的非显而易见的心智模型。具体的错误→修复对照（动词挂起、tap 被拒绝、--platform、--json、pod install 区域设置、孤立会话、启动差异）见 references/troubleshooting.md。

1. 先确认事实，再重置——不要反复打补丁。 切勿假设现有会话或 Metro 是你启动的，或运行正常。操作前，请确认：

   • cwd — 你位于预期的 Expo 项目目录中（方向错误的 start/exec 会为错误的应用创建会话，并留下一个多余的 .env.eas-simulator；使用 pwd / 检查 app.json）。
   • 会话运行中 — 通过 simulator:get --json 确认状态为 IN_PROGRESS（已停止的会话仍保留其 id 和 remoteConfig，因此仅凭 dotenv 文件不能证明会话仍在运行）。
   • Metro 使用独立端口 — 只有在本次会话中由你启动的 Metro 才能复用；否则请在空闲端口上启动一个（使用 --port <N>，例如 8082），不要为了重新占用 :8081 而终止其他服务（见 run-your-app.md）。
   • 构建符合预期 — 发布构建无法实时重新加载；如果需要实时编辑，而当前安装的是发布构建，请安装开发构建，不要重新连接。

   如果首次连接后当前代码仍未渲染，请停止尝试操作实时状态：重置到基线状态（停止会话 → 清除 dotenv → 终止你的 Metro），然后再执行一次该模式；如果第二次仍失败 → 停止并报告。切勿原地重启 Metro、重复连接超过一次、为了修复 JS/连接问题而重建原生客户端，或在状态未知时显示预览 URL。（守护进程断开——ERR_NGROK_3200 / Remote daemon is unavailable——处理方式也相同：重置，不要重试。）

2. exec 是包装器，不是驱动程序。 simulator:exec 会加载 .env.eas-simulator 并启动你传入的命令；设备动词来自控制器（npx agent-device@latest）。不存在 simulator:tap。

3. 立即操作；不要让会话闲置。 会话生命周期很短——在 start 后立即安装并操作。让会话闲置会导致隧道/守护进程断开（→ 按照 #1 重置）。

4. 任务完成或失败后，停止你创建的会话并重置 dotenv。 任务结束时，--non-interactive 不会停止会话。对于用户要求的实时预览，请遵循上方的时长指导。启动缓慢时，请轮询现有会话；启动另一个会话会创建额外会话并覆盖 dotenv 中的会话 id。

5. 仅对正确且最新的构建截图。 仅在开发客户端连接到 Metro 后，才使用模式 C；模式 A/B 仅使用与当前源代码匹配的构建——复用预先存在的构建是“我的修改没有显示”的首要原因（见上方的构建注意事项）。（状态栏中的 9:41 是模拟器默认值，不代表内容过时。）

停止并清理

任务结束后，停止你创建的会话并重置 dotenv，以免后续运行尝试复用已失效的会话。若用户要求实时预览，则改为在约定的时长内保持预览可用：

npx --yes eas-cli@latest simulator:stop          # omit --id → stops the dotenv session (or pass --id <id>)
printf '# managed by eas-cli\n' > .env.eas-simulator   # clear the stale session id so it isn't reused
# if you started Metro for Mode C, stop it too (Ctrl+C in its terminal, or kill the expo process)

参考资料

• references/run-your-app.md — 模式 A、B 和 C 的完整命令序列（运行某个模式前请先阅读）。
• references/controllers.md — agent-device 动词参考和 argent 替代方案。
• references/logs-and-crashes.md — iOS 会话中的设备日志和崩溃报告（应用崩溃或行为异常时请阅读）。
• references/troubleshooting.md — 常见错误及修复方法。

事实来源：Expo 文档和 eas / agent-device CLI（npx --yes eas-cli@latest simulator:* --help、npx --yes eas-cli@latest simulator:exec npx agent-device@latest help [topic]；在 simulator:exec 后使用 --help 会显示 EAS CLI 帮助）。本技能介绍如何应用这些工具；它不能取代这些工具。

提交反馈

如果你在此技能中发现错误、误导性信息或过时信息，请进行报告，以便 Expo 改进：

npx --yes @expo/agent-cli@latest feedback --category skills --subject "eas-simulator" "<actionable feedback>"

仅在有具体且可执行的内容需要报告时提交。请尽可能提供相关背景信息。 如果 Agent 在 Expo 任务中反复失败，或用户不得不介入，请使用 --category evals，并将相关的 Expo 包或命令作为 --subject，简要报告任务、预期结果以及出现的问题。