Orca 中 orca-emulator 技能桩解析：如何用 `orca skills get` 获取版本匹配的 iOS 模拟器驱动指南

本文以仓库中的技能发现桩 skill-stubs/orca-emulator.md 为主体，讲解 Orca 项目"stub + 二进制内置完整指南"的技能分发机制：为什么这个桩文件故意不包含命令清单、如何为当前会话正确解析出 Orca CLI 可执行文件（ORCA_CLI_COMMAND / orca-dev / orca-ide / orca 四级决策）、如何用 ORCA skills get orca-emulator 加载版本匹配的完整参考，以及旧版二进制不识别 skills get 时的有界降级流程。读完后你可以复现一条从"发现技能"到"驱动 iOS 模拟器"的完整可验证路径，并理解其背后的生成管线与源码实现。

一、这是一个"发现桩"，不是使用指南

skill-stubs/orca-emulator.md 开篇第一句就明确了它的定位："This file is a discovery stub, not the usage guide."（本文件是发现桩，不是使用指南）。完整的、与版本匹配的 Orca 模拟器参考文档由 orca 二进制自身提供——这是有意为之，保证指南永远不会与实际执行命令的二进制发生漂移。

该桩面向的场景是：你在 Orca 应用内部通过 Agent 驱动一台 iOS 模拟器/仿真器流——点击、手势、输入、硬件按键、相机注入、运行时权限、可访问性树等——同时实时画面停留在 Orca 的模拟器面板（emulator pane）中。文档明确建议：在 Orca 内运行 Agent 时优先使用 orca emulator ... 表面，而不是裸的 serve-sim 或直接的 simctl，因为 Orca 会替你处理设备作用域（device scoping）、辅助进程生命周期（helper lifecycle）和 worktree 上下文。它与 orca-cli 技能互补：后者负责终端、worktree 与内置浏览器。

这种"桩负责路由、二进制负责正文"的设计在源码层面有完整支撑。构建脚本 config/scripts/generate-bundled-skill-guides.mjs 中的注释说明了机制：被桩化的主题以"混合发现桩"的形式作为可安装投影，而 orca skills get <topic> 仍从二进制输出完整的、与版本匹配的指南。桩正文存放在 skill-stubs/<topic>.md，投影复用指南自身的 frontmatter（name + description 保持字节级一致，作为不变的发现表面），仅替换正文。STUB_TOPICS 列表中 orca-emulator 在列，且注释强调此类迁移"实质上是单向的"：早期胖安装依赖桩落地来收敛，所以条目只增不删。同一脚本还维护 GUIDE_ALIASES 别名兼容账本——旧发现桩可能在主题改名后长期存留，因此别名与规范名共用一张查找表，只追加、不删除。

完整指南的源头位于 skills/orca-emulator/SKILL.md（工作副本）与 skill-guides/orca-emulator.md（同源参考副本），构建时被内嵌进 CLI，最终产物见 src/cli/bundled-skill-guides.ts：该文件头部注明"Generated by config/scripts/generate-bundled-skill-guides.mjs. Do not edit."，其中 BUNDLED_SKILL_GUIDES 数组收录了 orca-emulator 条目（markdown 与 fullMarkdown 目前字节级相同，因为当前没有任何指南附带引用文档）。

二、为当前会话解析 CLI：四级决策规则

这是桩文档中最具实操价值、也是最容易被 Agent 踩坑的部分。核心原则是：一次性选定可执行文件，之后所有命令都复用它。文档给出的决策顺序如下：

1. ORCA_CLI_COMMAND 环境变量已设置 → 直接使用它的值。Orca 会为受管理的 WSL 会话导出这个变量。
2. 否则，在暴露了 ORCA_DEV_REPO_ROOT 的开发检出中 → 使用 orca-dev。
3. 否则，在 Orca 受管终端之外的 Linux 上 → 使用 orca-ide。此时绝不能直接运行裸 orca——在 Orca 终端之外，/usr/bin/orca 通常解析为 GNOME Orca 屏幕阅读器，会在用户机器上开启语音朗读。
4. 否则 → 使用 orca。

文档对占位符用法有严格的措辞要求：下文所有 ORCA 都是占位符，执行前必须替换为上面解析出的可执行文件；不要创建 shell 变量、也不要字面运行 ORCA。这套替换方式在 POSIX shell、PowerShell 和 cmd.exe 下行为一致。

错误处理规则同样关键：如果选定的可执行文件无法运行，报告其精确错误并停止。不要"透传"（fall through）到另一个可执行文件——那可能静默地把命令指向另一个 Orca 构建（例如开发会话打到了生产安装），造成难以察觉的行为分叉。仓库中 WSL 环境组装逻辑（src/main/pty/wsl-orca-env.ts、src/main/ipc/pty/host-env/assembly.ts 等）正是 ORCA_CLI_COMMAND 在受管会话中被导出与透传的实现位置。

三、先加载完整指南，再执行具体命令

桩文档规定的标准工作流只有一行：

ORCA skills get orca-emulator

它会为"即将处理你下一条命令的那个精确二进制"打印完整的、版本匹配的指南，覆盖设备启动、点击与手势、输入、硬件按键、相机注入、权限、可访问性树。文档要求先读它，再运行你需要的具体命令，并明确警告：不要凭记忆或从这份桩的缓存副本猜测子命令或标志——它们在 Orca 版本之间会变，本文件已刻意不再列出它们。

执行前的状态确认也写在桩中：用 ORCA status --json 确认应用已启动（必要时先 ORCA open --json 拉起），Agent 驱动的调用一律优先 --json。

从源码看这条命令的落地路径：skills get 的 handler 位于 src/cli/handlers/skills.ts，其 requireTopic 函数把 name 与所有 aliases 平铺进同一张 Map 做查找——这与生成脚本注释中"安装到磁盘的桩可能永久保留旧主题名，所以别名和规范名共用一张查找表"的设计一一对应；找不到时抛出 invalid_argument 并列出全部可用主题。orca-emulator 正是 BUNDLED_SKILL_GUIDES 中的合法 topic 之一。

完整指南覆盖什么（来自内嵌副本的印证）

由于桩指向的正文就躺在仓库里，skills/orca-emulator/SKILL.md 给出了 skills get 输出的实质内容，值得完整了解其覆盖面：

• 架构心智模型：ORCA emulator ...（或 ORCA emulator exec 直通）封装开源的 serve-sim 工具。底层 helper 通过私有 SimulatorKit / IOSurface 抓取真实仿真器帧缓冲（低延迟 60fps H.264 或 MJPEG），并暴露 WebSocket 控制通道；Orca 的 EmulatorBridge（主进程）拥有 helper 进程与每个 worktree 的"活动模拟器"状态，使不带限定符的命令天然作用于当前 worktree 的设备/面板。

• 常见操作表（--json 输出，默认工作区作用域）：

  目标	命令	备注
  列出可用/运行中	ORCA emulator list [--worktree <sel>]	显示 Orca 托管 + 裸 serve-sim 流，用于显式 --device/--emulator
  附加/设为活动	ORCA emulator attach "iPhone 16 Pro" [--worktree <sel>] [--focus]	需要时启动 helper；--focus 可选，默认不抢 UI 焦点
  单击	ORCA emulator tap <x> <y> [--device <id>]	归一化 0..1 坐标；单击优先于 gesture
  多步手势	ORCA emulator gesture '<json>'	begin/move/end；单击请用 tap
  输入文本	ORCA emulator type "text" [--device <id>]	仅 US ASCII
  硬件按键	ORCA emulator button home [--device <id>]	home、swipe_home、app_switcher、lock、siri、side_button
  旋转	ORCA emulator rotate landscape_left	后续手势沿用该方向
  相机注入	ORCA emulator camera com.acme.App --webcam	或 --file、placeholder，可热切换；可能重启 app
  权限	ORCA emulator permissions grant camera com.acme.App	grant/revoke/reset/list
  可访问性树	ORCA emulator ax [--device <id>]	原始 serve-sim AX 树，上限 500 节点，frame 归一化 0..1
  原始直通	ORCA emulator exec --command "tap 0.5 0.7"	命令串内不需要 "serve-sim" 前缀；bridge 注入活动设备上下文
  停止	ORCA emulator kill [--device <id>]	或依赖面板关闭/退出时清理

• 关键陷阱（供 Agent 教育）：单击优先 tap 而非 gesture（分发的 gesture begin/end 因 WS 开销可能被解释为长按）；坐标一律 0..1 归一化、左上角原点、绝不像素；每个 worktree 一个"活动"模拟器（类似活动浏览器标签）；type 仅 US 键盘，不支持字符会明确报错；相机注入常需（重）启动目标 app 包；视觉面板与 CLI 共享同一底层流，关面板可能停流（可配置）；底层依赖私有 API（SimulatorKit 等），对 Xcode 版本敏感。

• 设备与 worktree 定位：默认为当前 worktree 的活动模拟器；--worktree id:<fullWorktreeId> 需要 ORCA worktree list --json 返回的完整 <repo-id>::<path> 值（裸 repo id 无效）；--device <udid|name>；--emulator <id> 使用 list 返回的 Orca 生成 id（类似 browserPageId，适合脚本持久化）；--worktree all 仅用于 list。

• 与实时面板集成：打开面板或 attach 即把该流设为活动流；面板展示真实 60fps 流；CLI attach 默认不抢焦点（--focus 才切换，与浏览器行为一致）；多设备时面板可网格化。

• Agent 友好示例：ORCA status --json → ORCA emulator list --json → ORCA emulator attach "iPhone 16 Pro" --json → ORCA emulator tap 0.5 0.8 --json → ORCA emulator type "[e-mail]" --json → ORCA emulator button home --json → ORCA emulator camera com.acme.MyApp --file /tmp/test.mp4 --json → ORCA emulator permissions grant camera com.acme.MyApp --json → ORCA emulator ax --json → ORCA emulator exec --command "ca-debug blended on" --json。

四、旧版 Orca 不识别 skills get 时的降级流程

桩文档最后一段定义了严格受限的向后兼容路径，其约束值得逐条继承：

• 仅当选定二进制明确报告 skills get 是未知命令时，才走该回退。其他任何失败都不是"二进制过旧"的证据——此时应报告错误，而不是猜测或更换可执行文件。

• 对已确认的"指南前"二进制，只允许运行这两条有界的、只读的引导命令来建立方向感：

  ORCA status --json
  ORCA emulator list --json
  

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

这套"不猜命令、不造命令、不静默降级"的纪律与桩文件前半段的错误处理规则（执行文件失败即停止，不透传）是同一设计哲学的两个面：Agent 在版本分叉面前宁可停下，也不能把指令送进一个语义不同的构建。

五、小结：验证清单

把桩文档的完整工作流压缩为一条可验证链路：

1. 按四级规则选定可执行文件（ORCA_CLI_COMMAND → orca-dev → Linux 非受管的 orca-ide → orca），会话内保持不变；
2. ORCA status --json 确认运行中（未运行则 ORCA open --json）；
3. ORCA skills get orca-emulator 读取版本匹配的完整指南（其内容即 skills/orca-emulator/SKILL.md 所对应的内嵌副本）；
4. 按指南执行 ORCA emulator ... 具体命令，优先 --json；
5. 若第 3 步明确报"未知命令"，只跑 ORCA status --json 与 ORCA emulator list --json，然后建议用户升级。

这条链路上每个环节都有仓库内证据：桩文件 skill-stubs/orca-emulator.md、指南源 skills/orca-emulator/SKILL.md、生成脚本 config/scripts/generate-bundled-skill-guides.mjs、内嵌产物 src/cli/bundled-skill-guides.ts 与命令 handler src/cli/handlers/skills.ts。理解了这个"桩—二进制—指南"三位一体的分发模型，你就掌握了 Orca 保证 Agent 文档与运行时零漂移的核心机制——这也是它敢于让安装到磁盘的技能文件"永久只放路由、不放正文"的底气所在。