Orca 的 orca-emulator 技能如何工作：发现桩、版本匹配指南与模拟器命令面

本篇围绕 skills/orca-emulator/SKILL.md 展开，讲清 Orca 项目中 iOS 模拟器控制技能的两层结构：仓库里落地的“发现桩”（discovery stub）只负责路由与引导，而完整、与二进制版本匹配的参考指南由 orca 可执行文件本身通过 ORCA skills get orca-emulator 提供。读完本文，你能掌握在 Orca 会话中正确解析 CLI 可执行文件的方法、加载版本匹配指南的标准流程、老版本二进制的有限回退策略，以及这一机制在源码中的生成管线与命令规格依据。

1. orca-emulator 技能解决什么问题

orca-emulator 技能面向在 Orca 应用内驱动移动端（iOS）模拟器 / 模拟器流的场景：点击（taps）、手势（gestures）、键入（typing）、硬件按键（hardware buttons）、摄像头注入（camera injection）、运行时权限（permissions）、无障碍树（accessibility tree）等操作——全程可在 Orca 的模拟器面板（emulator pane）中看到实时画面。

技能 frontmatter 中给出的定位是：在 Orca 内部运行 agent 时，优先使用 orca CLI 的模拟器命令面，而不是裸的 npx serve-sim 或直接 simctl——因为 Orca 这一层负责设备范围（device scoping）、helper 生命周期（helper lifecycle）和 worktree 上下文（worktree context）。它与负责终端、worktree 和内嵌浏览器的 orca-cli 技能互补（参见 skills/orca-cli/SKILL.md），Android 侧则由 skills/orca-emulator-android/SKILL.md 覆盖。

2. 为什么 SKILL.md 本身只是“发现桩”

打开 skills/orca-emulator/SKILL.md 会看到一句关键声明：

This file is a discovery stub, not the usage guide. The full, version-matched Orca emulator reference is served by the orca binary itself — kept out of this file on purpose so it can never drift from the binary that will actually run your commands.

也就是说，这个文件被刻意设计得“薄”：它不提供子命令清单，只提供三条能力——说明何时该启用该技能、如何解析本次会话的 CLI 可执行文件、以及如何在运行任何模拟器命令之前加载完整指南。这样做的收益是：安装到各 agent 目录的桩文件永远不可能与将要执行命令的那个二进制漂移（drift）。

从源码结构看，这不是人工约定而是生成产物。config/scripts/generate-bundled-skill-guides.mjs 维护了一个 STUB_TOPICS 列表（包含 orca-emulator），其注释写道：

a stubbed topic ships a hybrid discovery stub as its installable projection while orca skills get <topic> still serves the full version-matched guide from the binary

具体管线在 buildArtifacts 中：

• 完整指南源文件位于 skill-guides/orca-emulator.md（必须与 CANONICAL_GUIDE_NAMES 清单精确一致）；
• 桩正文位于 skill-stubs/orca-emulator.md；
• composeStubProjection 复用指南自身的 frontmatter（name 与 description 必须与指南逐字节一致，保持发现面不变），只替换正文为桩内容，投影写入 skills/orca-emulator/SKILL.md；
• 完整指南同时被序列化进 src/cli/bundled-skill-guides.ts（文件头部标注 “Generated by config/scripts/generate-bundled-skill-guides.mjs. Do not edit.”），供 CLI 在运行时提供。

生成器还带防漂移校验：不带 --write 运行时会执行 verifyArtifacts，逐字节比对生成物与仓库现有文件，发现不一致即报 “Generated bundled skill guides are stale”。

3. 会话内解析 CLI 可执行文件

桩文档要求“一次选择、全程复用”同一可执行文件，判定顺序如下（与 skills/orca-emulator/SKILL.md 的 “Resolve the CLI for this session” 一节一致）：

1. 若设置了环境变量 ORCA_CLI_COMMAND，直接使用其值。Orca 会为受管理的 WSL 会话导出该变量。
2. 否则，在暴露 ORCA_DEV_REPO_ROOT 的开发检出（dev checkout）中，使用 orca-dev。
3. 否则，在 Linux 且位于 Orca 受管终端之外时，使用 orca-ide。切勿在那里直接运行裸 orca——在 Orca 终端之外，orca 通常会解析到 GNOME 的 Orca 读屏器（/usr/bin/orca），并会在用户机器上开始语音播报。
4. 其余情况，使用 orca。

文档中反复出现的 ORCA 是一个文档占位符：运行前必须用你解析出的可执行文件替换它；不要创建 shell 变量、也不要字面执行 ORCA。该替换约定在 POSIX shell、PowerShell 和 cmd.exe 中行为一致（命令块刻意保持 shell 中立）。

还有一条硬性失败策略：若选定的可执行文件无法运行，报告其精确错误并停止；不要退而求其次换另一个可执行文件，因为那可能静默地把命令打到另一个 Orca 构建上（例如开发会话误达生产 CLI）。

4. 运行模拟器命令前：加载完整指南

桩文档规定的加载方式是：

ORCA skills get orca-emulator

这会由即将处理你后续命令的那个二进制打印出完整的、版本匹配的指南——涵盖设备启动、点击与手势、键入、硬件按键、摄像头注入、权限、无障碍树等内容。文档明确要求先读完整指南，再执行你真正需要的那条具体命令。

配套的行为约束：

• 不要凭记忆或缓存的桩副本猜测子命令和 flag。它们在不同 Orca 版本之间会变，桩文件已刻意不再列出；
• 用 ORCA status --json 确认应用在运行（必要时用 ORCA open --json 启动）；
• agent 驱动的调用一律优先 --json。

skills get 的实现位于 src/cli/handlers/skills.ts：handler 懒加载 ../bundled-skill-guides.js（注释解释原因是避免大表拖累无关命令的启动路径），通过 requireTopic 按名称或别名查表（别名是“兼容性账本”，见生成器中 GUIDE_ALIASES 的注释），--full 时输出 fullMarkdown，--json 时输出 { name, full, markdown } 信封。这也解释了桩文档中“老版本不识别 skills get”这种失败模式从何而来——该命令是较新二进制才有的表面。

5. 老版本 Orca 不识别 skills get 时的回退

桩文档专门用一节定义了唯一允许的回退，条件苛刻：只有当所选二进制明确报告 skills get 是未知命令时才能走这条路径。其他任何失败都不是“二进制太老”的证据——应如实报告，而不是猜测或换可执行文件。

对确认属于“指南前”（pre-guide）二进制的场景，只允许执行这个有界、只读的启动探查：

ORCA status --json
ORCA emulator list --json

随后告知用户：更新 Orca 即可通过 ORCA skills get orca-emulator 恢复完整的版本匹配指南。超出这两条命令的范围，应向用户提问，而不是猜测该老版本二进制可能不支持的命令面。

6. 完整指南的内容边界（由二进制提供，桩只做路由）

orca skills get orca-emulator 输出的完整指南（源见 skill-guides/orca-emulator.md，内嵌于 src/cli/bundled-skill-guides.ts）覆盖了桩文档不承载的实操细节，要点包括：

• 架构心智模型：orca emulator ... 命令经 RPC 到达主进程的 EmulatorBridge；bridge 启动并持有 serve-sim helper 进程（每设备一个）并维护每个 worktree 的“活动模拟器”状态，使无限定命令“开箱即用”；helper 通过 WebSocket 控制通道驱动模拟器，帧缓冲走 60fps 的 H.264/MJPEG 流，渲染进程用 serve-sim 客户端消费该流作为实时面板。
• 常见操作表：list、attach（可 --focus，默认不抢焦点）、tap（归一化 0..1 坐标，单击优先于 gesture）、gesture（begin/move/end 序列）、type（仅 US ASCII）、button（home、swipe_home、app_switcher、lock、siri、side_button）、rotate、camera（webcam/file/placeholder，可能重启目标 App）、permissions（grant/revoke/reset/list）、ax（serve-sim 原始 AX 树，最多 500 节点，frame 归一化 0..1，点击元素取其 frame 中心）、exec（原始透传，命令串里不需要 serve-sim 前缀，bridge 会注入活动设备上下文）、kill。
• 关键陷阱：单击优先用 tap（gesture 的 begin/end 分离可能因 WS 开销被解释为长按）；坐标永远是归一化 0..1（左上原点），绝不使用像素；每个 worktree 只有一个“活动”模拟器（类比活动浏览器标签）；type 仅 US 键盘；摄像头注入常需重启目标 App；私有 API（SimulatorKit 等）对 Xcode 版本敏感。
• 目标寻址：默认是当前 worktree 的活动模拟器；显式 --worktree id:<repoId>::<path> 或 active、--device <udid|name>（bridge 会尽早把名称解析成 UDID，规避 serve-sim 的一个控制端缺陷）、--emulator <id>（list 返回的 Orca 生成 id，适合脚本持久化）；--worktree all 仅用于 list。
• 前置条件：macOS 主机 + Xcode Command Line Tools（xcrun --version）、已启动的模拟器、Node 可用；摄像头注入完整功能建议 macOS 14+；缺失时 Orca 会给出明确错误。

7. 模拟器命令面的实际规格

CLI 命令注册在 src/cli/specs/emulator.ts，与指南描述相互印证。当前实现的命令面包括：

命令	用途	主要 flag
emulator list	列出可用/运行中的模拟器（Orca 管理 + 裸 serve-sim）	--worktree
emulator devices	跨 iOS 与 Android 列出所有设备/AVD	--worktree
emulator attach [device]	附加/启动 helper 并设为该 worktree 活动	--focus --device --worktree
emulator tap <x> <y>	归一化 0..1 坐标单击（单击首选）	--device --emulator --worktree
emulator type <text>	键入文本（仅 US ASCII）	同上
emulator gesture <json>	多点手势序列	同上
emulator button <name>	硬件按键（home、side_button 等）	同上
emulator rotate <orientation>	旋转设备	同上
emulator exec --command <cmd>	原始透传（如 tap 0.5 0.7、ca-debug blended on）	同上
emulator kill	停止某设备的 helper	--device --emulator --worktree
emulator shutdown	停止 helper 并关机模拟器设备	同上
emulator install <apkPath>	安装 APK（Android）	--reinstall
emulator launch <package>	启动 Android 应用（可带 --activity）	同上
emulator permissions <op> ...	Android 运行时权限 grant/revoke/reset	--device
emulator ax	无障碍树（Android uiautomator；iOS serve-sim AX，frame 0..1）	--device --worktree
emulator logcat	Android 一次性 logcat 抓取	--lines

注意 iOS 与 Android 共享同一 emulator 命名空间，由设备类型路由到不同后端；ax 在两个平台都可用但输出格式不同。agent 的典型工作循环是：ORCA status --json → ORCA emulator list --json → ORCA emulator attach "iPhone 16 Pro" --json，然后 tap/type/button 等操作，配合 Orca 实时面板观察结果；操作后需要重新获取状态（类似浏览器 snapshot-interact 循环）。结束工作时用 ORCA emulator kill --device "..." --json 或依赖 Orca 退出时的孤儿清理。

8. 小结：一个可复用的“技能分发”模式

orca-emulator 技能体现了 Orca 对 agent 技能分发的一条设计原则：发现面与内容面分离。仓库里可安装的 skills/orca-emulator/SKILL.md 由生成器从 skill-stubs/orca-emulator.md 投影而来，只承担“何时启用、如何解析 CLI、如何取指南、失败时如何停止”四件事；真正随版本演化的命令参考内嵌在二进制中，由 ORCA skills get orca-emulator 按需吐出。对写 agent 提示词或技能文件的人来说，这是一条值得借鉴的防漂移策略：把会随发布变化的细节从静态文件移入运行时自描述，静态文件只保留不变的引导逻辑。