Orca Mobile 开发实战双进程联调、配对调试与版本化协议兼容性设计【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and VPS.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca本文基于 Orca 仓库中的 mobile/README.md 展开介绍 Orca 的 React Native 移动端Orca Mobile如何与桌面端 Electron 协同工作从双进程本地开发环境的搭建、局域网/模拟器配对流程到无需真机的终端流复现脚本与 mock 服务器调试手段并结合 mobile/src/transport/protocol-version.ts 等源码深入讲解移动端与桌面端之间的版本化协议兼容性契约帮助你在手机上监控 worktree、查看终端输出并下发命令的完整技术栈跑起来。双进程架构桌面 RPC 服务器 Expo MetroOrca Mobile 是一个伴随应用companion app在手机上监控 worktree 状态、查看终端输出、向桌面端 agent 发送命令。它的本地开发依赖两个并行进程这是理解整个开发流程的关键前提桌面端 OrcaElectron从仓库根目录启动内部承载移动端的 WebSocket RPC 服务器监听端口6768Expo Metro从mobile/目录启动在端口8081上提供 React Native 应用的热更新 bundle。两条进程链是解耦的Metro 的热重载只影响移动端的 JavaScript bundle而 Electron 主进程代码包括 RPC 服务器的改动必须重启桌面端才能生效。README 特别强调这一点因为它是移动端调试中最常见的“改了没生效”原因。环境要求Node.js 24pnpmXcode 和/或 Android Studio 工具链模拟器或真机构建手机上的 Expo Go或需要原生模块时的 development client 构建测试真机时手机与桌面需处于同一局域网LAN启动桌面端从仓库根目录执行pnpm install pnpm dev确认移动端 RPC 服务器处于监听状态lsof -nP -iTCP:6768 -sTCP:LISTEN注意修改 Electron 主进程代码后需要重启pnpm devMetro 热重载仅适用于移动端 JS bundle。启动移动端以下命令默认在mobile/目录下执行README 约定“除非命令另有说明移动端命令都在mobile/目录运行”cd mobile pnpm install pnpm start用 iOS 手机相机或 Android 上的 Expo Go 扫描 Expo 二维码即可加载应用。对于需要原生模块的 dev client 构建pnpm exec expo run:android pnpm exec expo run:ios pnpm start --dev-client这些脚本在 mobile/package.json 中有对应定义start实际由 mobile/scripts/start-expo.mjs 驱动android/ios则直接映射到expo run:android/expo run:ios此外postinstall会自动构建终端 WebView 引擎build-terminal-webview-engine.mjs与 mermaid WebView 引擎这也是移动端能用 WebView 承载 xterm 终端的前提。与桌面端配对Pairing配对流程是移动端连接桌面的入口共四步打开 Orca 桌面端进入Settings Mobile设置页用手机端扫描配对二维码确认移动端记录的 host 端点为ws://desktop-ip:6768。不同连接目标下的端点取值场景端点Android 模拟器ws://10.0.2.2:6768局域网真机ws://192.168.0.179:6768示例取桌面 LAN IP如果手机上残留了过期的 host 条目需要在 App 中删除后重新配对。从仓库结构看配对相关的端点解析逻辑集中在 mobile/src/transport/host-endpoint.ts、mobile/src/transport/pairing.ts 等文件中桌面端对ws://前缀、IPv6 方括号、自定义地址如100.126.117.25:6768的归一化行为在 src/shared/mobile-pairing-custom-address.test.ts 等测试中有覆盖说明二维码中编码的端点会经历严格解析后再入库。各开发路径速查Android 真机安装 Expo Go →pnpm start后用 Expo Go 扫码涉及原生模块时改用pnpm exec expo run:android并以pnpm start --dev-client运行。iOS 模拟器安装 Xcode 后执行pnpm start --ios即可直接在 iOS Simulator 中打开应用。无真机调试手段README 中最具实战价值的部分是两类“不需要手机”的调试通道。它们的共同思路是把问题定位拆分成“桌面运行时/PTY 侧”和“移动端 WebView/UI 侧”两个独立故障域。用 connected device 工具链驱动真机即使面对真机也可以直接用 Orca CLI 通过已连接设备工具进行检查与交互orca snapshot --json orca click --element e3 --json orca fill --element e1 --value ls --json orca screenshot --json工作方法是先用snapshot获取当前元素引用element refs再用click/fill操作这些引用。修改移动端文件后Metro 通常会自动热重载但由于终端订阅在会话屏进入时才会重新发起terminal.subscribe在会话屏之间退出再返回一次往往能触发重新订阅是排查终端内容不刷新问题的实用技巧。终端流复现无手机当终端输出在设备上渲染不出来时用该脚本区分“服务端流式传输 bug”还是“WebView/UI bug”cd mobile ORCA_MOBILE_WS_URLws://127.0.0.1:6768 pnpm exec tsx scripts/test-subscribe.ts deviceToken serverPublicKeyB64也可以传入 worktree 选择器作为第三个参数支持三种形式pnpm exec tsx scripts/test-subscribe.ts deviceToken serverPublicKeyB64 id:worktreeId pnpm exec tsx scripts/test-subscribe.ts deviceToken serverPublicKeyB64 path:/absolute/worktree/path pnpm exec tsx scripts/test-subscribe.ts deviceToken serverPublicKeyB64 name:my-worktree脚本对应 mobile/scripts/test-subscribe.ts。预期结果包含两行标记streamSawMarker: true readSawMarker: true诊断结论是明确二分的若复现失败说明问题在桌面 runtime/PTY 路径应先修桌面侧若复现通过但手机屏幕空白则问题在移动端会话屏或TerminalWebView的就绪/排队readiness/queueing路径。该二分法避免了在错误的故障域里空耗排查时间。终端颜色复现无手机针对“切换标签页后终端颜色丢失”的问题README 提供了专门的复现脚本先在目标 worktree 中打开一个 Claude Code 终端和至少另一个终端然后执行cd mobile ORCA_MOBILE_WS_URLws://127.0.0.1:6768 pnpm exec tsx scripts/repro-terminal-colors.ts \ deviceToken serverPublicKeyB64 id:worktreeId脚本mobile/scripts/repro-terminal-colors.ts会按A → B → A序列抓取terminal.subscribe快照并把原始快照写入mobile/terminal-color-repro/目录。判定逻辑同样清晰两次 A 快照的sgrColor计数不同→ 桌面端快照在切换过程中发生了变化问题在桌面侧两次 A 快照一致→ ANSI 颜色数据仍在问题在移动端回放/渲染路径。版本化协议兼容性设计由于移动端经 App Store 更新通常比桌面端滞后 24–48 小时Orca 让移动端和桌面端在status.get时互换版本号使得真正不兼容的组合会硬阻断hard-block而不是静默错乱。这是移动端协议设计中最值得借鉴的部分。四组版本常量常量分置于两个文件因为 Metro 无法解析mobile/之外的模块文件常量src/shared/protocol-version.tsDESKTOP_PROTOCOL_VERSION、MIN_COMPATIBLE_MOBILE_VERSIONmobile/src/transport/protocol-version.tsMOBILE_PROTOCOL_VERSION、MIN_COMPATIBLE_DESKTOP_VERSION从当前仓库源码看两侧文件均已落地桌面端文件实际上以RUNTIME_PROTOCOL_VERSION为主体并导出别名DESKTOP_PROTOCOL_VERSION RUNTIME_PROTOCOL_VERSION、MIN_COMPATIBLE_MOBILE_VERSION MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION当前值为3/2移动端文件中MOBILE_PROTOCOL_VERSION 3、MIN_COMPATIBLE_DESKTOP_VERSION 2。移动端文件头部的注释也解释了重复维护的原因“这些常量预计每季度提升不到一次手工同步可以接受”。兼容性判定逻辑判定函数evaluateCompat位于 mobile/src/transport/protocol-compat.ts并明确镜像自桌面端受 CI vitest 覆盖的版本。其逻辑仅两条规则若MOBILE_PROTOCOL_VERSION requiredMobile桌面声明的最低移动端版本→ 返回{ kind: blocked, reason: mobile-too-old }若桌面上报版本 MIN_COMPATIBLE_DESKTOP_VERSION→ 返回{ kind: blocked, reason: desktop-too-old }否则返回{ kind: ok }。以当前仓库四个常量取值3/2 对 3/2计算evaluateCompat始终返回{ kind: ok }—— 即 README 所述“什么也不会被阻断线上格式wire format已就位需要时只需拨动开关”。当判定结果为blocked时mobile/src/components/ProtocolBlockScreen.tsx 会渲染一个阻断页把用户导向 App Store移动端过旧或 GitHub Releases桌面端过旧。何时提升版本号README 给出的规则是明确的应为以下破坏性变更提升DESKTOP_PROTOCOL_VERSION并在相关时同步移动端镜像MOBILE_PROTOCOL_VERSION移除移动端正在使用的 RPC 方法或必填参数改变移动端读取的既有字段的语义单位、可空性变更加密、分帧或鉴权握手。不应为以下增量变更提升版本号新增 RPC 方法既有方法新增可选字段terminal.subscribe新增事件类型。MIN_COMPATIBLE_MOBILE_VERSION是一个“kill-switch”当桌面端发布了需要最低移动端版本才能安全工作的变更时设置它MIN_COMPATIBLE_DESKTOP_VERSION则是移动端方向的对称机制。移动端源码注释进一步细化当移动端开始依赖某个运行时协议版本才新增的服务器特性时提升MIN_COMPATIBLE_DESKTOP_VERSION从而对配对了旧服务器的用户触发硬阻断页。本地演练阻断页将 mobile/src/transport/protocol-version.ts 中的MIN_COMPATIBLE_DESKTOP_VERSION临时设为999重新构建后与任意桌面端配对即可看到阻断屏合并前务必还原。Mock 服务器不依赖桌面端开发移动端README 提供了独立于真实 Orca 桌面实例的完整开发路径pnpm mock-server # 在端口 6768 启动 mock WebSocket 服务器App 使用端点ws://localhost:6768、tokenmock-device-token连接。mock-server脚本定义于 mobile/package.json实际入口是 mobile/scripts/mock-server.ts。从源码看这个 mock 服务器并非玩具级端口取PORT环境变量缺省即6768与真实桌面端一致因此 App 侧代码路径完全复用每条连接先走与真实运行时一致的E2EE 握手首条消息必须是明文e2ee_hello携带 32 字节 base64 公钥服务器回复e2ee_ready随后所有消息用派生共享密钥加解密客户端须发送加密的e2ee_auth并通过mock-device-token认证才能进入 RPC 阶段RPC 处理由 mobile/scripts/mock-server-rpc-handlers.ts 承接返回贴近真实运行时形状的假数据。环境变量MOCK_NATIVE_CHAT1提供 native-chat 场景一个实时 agent 标签、空 transcript、图片上传替代默认终端 fixtureMOCK_SERVER_KEY_FILE跨重启持久化服务器密钥对使已配对设备保留其公钥 pin。文件缺失或无效时会重新换钥并给出警告从而强制重新配对——这与真实世界的密钥 pin 语义保持一致。场景控制文件不重启切换行为三类场景文件在每次请求时读取因此可以在会话中途改变 mock 行为而无需重启重启会重新换 E2EE 密钥并强制重新配对。把对应模式写入文件即可删除文件则回到默认行为环境变量默认临时文件名取值与效果MOCK_SEND_MODE_FILE系统临时目录下orca-mock-send-modeaccept默认接受发送error以mobile_input_floor_unavailable失败其他值报发送被拒绝MOCK_TERMINAL_LIST_MODE_FILEorca-mock-terminal-list-modeomit返回空终端列表other返回省略 chat handle 的列表其他值正常列出MOCK_TERMINAL_STREAM_MODE_FILEorca-mock-terminal-stream-modedead对 subscribe 回复subscribed后接end模拟 PTY 已消失用于验证 rearm bound 与终端剪枝其他值正常流式这套“模式文件”机制让移动端的重连、降级、终端失效等边界路径可以在无桌面端、无真机的情况下稳定复现。连接真实 Orca以 WebSocket transport 启用状态启动 Orca 桌面端在 Orca 中进入 Settings Mobile用 App 扫描配对二维码二维码编码了连接端点、设备 token 与 TLS 指纹。提交前验证与项目结构提交移动端终端相关改动前README 要求依次执行cd mobile pnpm exec tsc --noEmit pnpm lint cd .. pnpm typecheck:node即移动端类型检查tsc --noEmit、移动端 lintoxlint以及回到仓库根目录后对桌面侧的typecheck:node—— 这呼应了前文“双进程、双代码库”的结构移动端改动可能牵动桌面 runtime 的 RPC 契约。项目结构继承自 README 并对照仓库实际目录mobile/ ├── app/ # Expo Router 屏幕文件式路由 │ ├── _layout.tsx # 带导航栈的根布局 │ ├── index.tsx # 首页——已配对主机列表 │ └── pair-scan.tsx # 二维码扫描屏 ├── src/ │ ├── terminal/ # 终端 WebView 与 xterm 桥接 │ └── transport/ # WebSocket RPC 客户端 ├── scripts/ │ ├── test-subscribe.ts # 无手机的桌面流式复现 │ └── mock-server.ts # 独立 mock WebSocket 服务器 └── assets/ # 应用图标与启动屏从仓库实际目录看mobile/src/transport/远不止“一个 RPC 客户端”它包含了完整的 E2EE 会话如 mobile/src/transport/mobile-e2ee-v2-client-session.ts、relay 中继连接与直连升级控制mobile-relay-direct-upgrade.ts、重连调度、配对 keychain、连接健康度与诊断日志等子系统mobile/src/terminal/则承载终端渲染层。理解这些模块的存在能解释为何 README 把“桌面流 vs WebView”的故障二分法写得如此具体——每个二分域背后都有对应的、带测试的实现层。小结mobile/README.md 虽然篇幅不长但把 Orca 移动端开发的完整闭环讲清楚了双进程6768 8081本地环境、四类设备连接路径Expo Go、dev client、iOS 模拟器、真机 CLI 驱动、两套无真机复现脚本流复现 颜色复现以及版本化协议兼容性契约。结合 mobile/src/transport/protocol-compat.ts、mobile/scripts/mock-server.ts 等源码可以看到README 中的每一条调试建议背后都有对应的可运行实现与测试这套文档与源码的对应关系本身就是一个移动终端类应用联调流程的良好范本。【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and VPS.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考