hsandhu/mobilecode · 上手攻略

  • 仓库：hsandhu/mobilecode
  • 链接：https://github.com/hsandhu/mobilecode
  • 分类：devtools
  • 作者：Tom
  • 更新：2026-09-11

这是什么

MobileCode 是一个基于 opencode 的开源 AI 编程助手 fork，专注于移动端项目（iOS + Android）的实时预览与构建。它让 AI 编程助手能够直接感知、移动、运行你的 iOS 和 Android 项目，并在编程界面旁边内嵌实时模拟器/模拟器画面——一个 Play 按钮同时驱动 React Native 的 iOS 和 Android 两端构建。

本质上是把 opencode 的 AI 编程能力与移动端开发工作流（Xcode、Gradle、Metro、CocoaPods、Expo）深度集成，让 AI 在修改代码后能直接看到移动端运行效果，而不需要开发者手动切换窗口、启动模拟器、粘贴日志。

解决什么问题

主流 AI 编程助手（Claude Code、Copilot 等）在桌面/Web 项目上表现出色，但在移动端开发中存在几个盲区：

  • 日志反馈闭环断裂：AI 修改代码后需要开发者手动启动模拟器、运行、观察，失败后再粘贴日志给 AI——这个循环效率极低。
  • 平台差异隐性成本：iOS 用 xcodebuild / CocoaPods，Android 用 Gradle / AVD，React Native 需要 Metro——这些工具链差异对 AI 来说是黑盒。
  • 双平台同步维护难：一个功能要在 iOS 和 Android 同时跑，往往要开两个终端、两套工具链，AI 无法感知两端状态。

MobileCode 的解法是：让 AI 自己执行设备构建与预览流程，并通过内嵌的模拟器画面实时看到结果。AI 可以自主调用 device_run 工具，读取编译错误和日志尾，从而自己修复构建失败——而不需要开发者充当中间人。

快速安装

方式一：一键安装脚本（推荐）

curl -fsSL https://raw.githubusercontent.com/hsandhu/mobilecode/main/install | bash

安装脚本将二进制文件放置于 ~/.mobilecode/bin 并自动添加到 shell PATH。安装完成后直接运行：

mobilecode

⚠️ 注意：这是从 GitHub release 下载预编译二进制，需要 macOS + Xcode 环境（iOS 开发）或 Android SDK（Android 开发）。

方式二：从源码构建

git clone https://github.com/hsandhu/mobilecode.git
cd mobilecode
bun install
bun run --cwd packages/opencode src/index.ts

⚠️ 注意：需要 Node.js 20 或更新版本（源码构建会通过 nvm 自动处理版本）。桌面应用构建命令为 bun run build:macos，产出 MobileCode.app + .dmg / .zip 到 packages/desktop/dist。

方式三：Web UI（不需要 Electron）

bun run --cwd packages/opencode src/index.ts serve --port 4096  # 后端
bun --cwd packages/app dev -- --port 4444                         # Web UI → http://localhost:4444

前置依赖

平台 必需环境
iOS macOS + Xcode（含 xcodebuild）+ Node.js 20+（serve-sim 需要）
Android Android SDK platform-tools + 至少一个已创建的 AVD + 支持项目 Gradle 版本的 JDK
通用 opencode 的配置格式（~/.config/opencode）和 provider credentials（与 opencode 完全兼容）

核心用法

1. 基本启动

mobilecode

启动后会检测当前目录是否包含 iOS/Android 项目，找到后自动在 UI 旁打开设备预览面板（device pane）。

2. Play/Stop/Status 操作（iOS）

在项目目录下打开 MobileCode 后，标题栏会显示平台运行控制按钮：

  • Play（▶️）：执行 xcodebuild → simctl install → simctl launch，构建并启动 iOS 应用
  • Stop（⏹️）：取消正在进行的构建，或终止已在运行的 App
  • Status：依次经过 Building → Installing → Launching → Running；构建失败时显示第一条编译器错误

3. Play/Stop/Status 操作（Android）

  • Play：执行 ./gradlew ::assembleDebug → adb install -r -g → 发送 launch intent
  • Stop：同上，取消或终止
  • Status：同 iOS，显示构建状态和错误

4. React Native / Expo 项目

当检测到 Expo 或裸 React Native 项目时，MobileCode 会：

  1. 用 expo prebuild 生成原生项目（如需要）
  2. 安装 CocoaPods（iOS）和 Gradle 依赖
  3. 启动 Metro bundler（一个 Metro 同时服务 iOS 和 Android）
  4. 通过 adb reverse 将模拟器连接到 Metro
# MobileCode 自动处理，无需手动干预
# 可通过 HTTP API 触发：
POST /api/device-preview/start  { "platform": "ios" | "android" }
POST /api/device-preview/run     { "platform": "ios" | "android" }
POST /api/device-preview/stop    { "platform": "ios" | "android" }
GET  /api/device-preview?location[directory]=<项目路径>

5. AI Agent 驱动的设备运行（device_run）

device_run 是 MobileCode 为 AI 提供的核心工具：

  • AI 自主触发构建和启动，等待结果
  • 读取构建错误和日志尾
  • 无需开发者粘贴日志——AI 自己读、自己修、自己重跑
# device_run 工具由 MobileCode 自动暴露给 AI，
# AI 通过它可以：
# 1. 启动模拟器/模拟器
# 2. 构建项目
# 3. 读取错误日志
# 4. 自主修复并重试

6. 配置与兼容性

MobileCode 完全兼容 opencode 的配置体系：

# 配置文件位置（与 opencode 相同）
~/.config/opencode/        # 配置
~/.local/share/opencode/   # 数据
OPENCODE_*                 # 环境变量前缀

# 如果你已有 opencode.json、provider credentials、plugins、skills，
# 迁移到 MobileCode 后无需任何改动

典型适用场景

场景 说明
React Native 双平台开发 一个 Metro 同时服务 iOS + Android，AI 修改后两端同时预览
iOS 原生 App 开发 Xcode 项目 + CocoaPods，AI 可自主构建、读错误、修代码
Android 原生 App 开发 Gradle 项目，AI 可自主编译、安装、启动、读日志
跨平台 UI 调试 同时在 iOS Simulator 和 Android Emulator 中观察同一功能的渲染差异
AI 结对编程（移动端） AI 有设备级上下文，不仅看到代码，还能看到运行效果
移动端 TDD / 红绿重构循环 AI 写测试、跑构建、读失败日志、修复，再跑——全流程自主闭环

坑与注意

  1. macOS 专属（iOS）：iOS 构建只能在 macOS 上进行，因为需要 Xcode 工具链。如果你在 Linux/Windows 上使用 MobileCode，只能操作 Android。
  2. 一次只能跑一个项目：simulator、emulator 和 Metro port 是共享资源，切换项目会自动停止前一个项目的 App。
  3. Node.js 版本要求：serve-sim（iOS 模拟器流）需要 Node 20+，旧版 Node 会导致 iOS 预览失效。
  4. Android AVD 需提前创建：MobileCode 不会自动创建 AVD，需要你先用 avdmanager 或 Android Studio 创建好至少一个模拟器。
  5. 签名问题（macOS）：构建产物默认未签名，首次运行需右键"打开"（Open）。如需签名分发，需要传入 --sign 参数并配置 Developer ID 证书及相关 API key。
  6. 配置不兼容 opencode 分叉版本：MobileCode 兼容 opencode 配置，但如果之前用的是 opencode 的其他 fork（如带自定义插件的版本），配置可能不完全兼容。
  7. device_run 依赖 AI 模型能力：device_run 的有效性取决于 AI 模型是否愿意主动调用该工具——不是所有 AI 模型都会自发使用它。

REST API 进阶

MobileCode 暴露了完整的设备预览 HTTP API，支持在 CI/CD 或外部脚本中调用：

# 启动设备预览服务（不触发构建）
curl -X POST http://localhost:4096/api/device-preview/start \
  -H "Content-Type: application/json" \
  -d '{ "platform": "ios" }'

# 直接运行（构建 + 安装 + 启动）
curl -X POST http://localhost:4096/api/device-preview/run \
  -H "Content-Type: application/json" \
  -d '{ "platform": "android" }'

# 停止
curl -X POST http://localhost:4096/api/device-preview/stop \
  -H "Content-Type: application/json" \
  -d '{ "platform": "ios" }'

# 查询状态
curl "http://localhost:4096/api/device-preview?location[directory]=/path/to/project"

这些 API 让 MobileCode 可以被集成到自动化流程中，例如：CI 阶段自动跑构建、测试服务器上按需启动模拟器等场景。

⚠️ 注意：API 端口默认为 4096（与 opencode 相同），可通过 --port 参数覆盖。

与同类对比

工具 定位 AI 集成度 移动预览 iOS 支持 Android 支持
MobileCode opencode fork，专注移动端 ⭐⭐⭐⭐⭐ AI 原生 内嵌实时预览 ✅ macOS Xcode ✅ AVD
Expo React Native 开发平台 ⭐⭐⭐ 辅助 Web/设备 ✅ ✅
Flutter 跨平台 UI 框架 ⭐⭐ 无内置 AI 热重载 ✅ ✅
opencode 通用 AI 编程助手 ⭐⭐⭐⭐⭐ ❌ 无 ❌ 无 ❌ 无
Claude Code 通用 AI 编程助手 ⭐⭐⭐⭐⭐ ❌ 无 ❌ 无 ❌ 无
Cursor AI 代码编辑器 ⭐⭐⭐⭐ ❌ 无 ❌ 无 ❌ 无

核心差异：MobileCode 是目前唯一将 AI 编程助手与移动设备预览深度集成的开源方案。它不替代 opencode，而是在 opencode 基础上填补了移动端工作流这个空白。

一句话推荐结论

如果你用 opencode 做移动端开发（尤其是 React Native），MobileCode 是目前最顺滑的方案——AI 改代码后直接看到双平台运行效果，构建错误由 AI 自己读日志修复，开发者从"粘贴日志的中间人"变成真正的"旁观者"。