Mobile Harness 详细部署教程

Mobile Harness 是一款创新的 Android 应用，它能在你的手机上创建一个完整的、自包含的 Ubuntu Linux 开发环境，并集成了 Claude Code 等 AI 编程助手。让你可以随时随地进行代码编写、运行和预览。本文将详细介绍从下载到完成首次项目配置的完整流程。

一、准备工作：了解你的设备

在开始安装前，请先确认你的 Android 设备满足以下基本要求，以确保应用能流畅运行：

操作系统：Android 9.0 (API level 28) 或更高版本。
CPU 架构：必须为 64 位 ARM (arm64-v8a)。这是目前绝大多数中高端手机使用的架构。
运行内存 (RAM)：建议 4 GB 起步，8 GB 或以上体验更佳（大型项目编译会更流畅）。
可用存储空间：
- 基础运行环境：至少需要 2.5 GB 空闲空间。
- 完整工具链：如果计划安装 Python、Android SDK 等所有可选工具，建议预留 8 GB 或更多。
网络：首次启动时需要稳定的网络连接以下载核心运行环境 (约 800MB+)。

二、下载与安装 APK

Mobile Harness 提供两个版本，可根据你的网络情况选择。

访问发布页面：在手机浏览器中打开项目的 GitHub Releases 页面：https://github.com/techjarves/Mobile-Harness/releases
选择并下载 APK：
- 在线版 (Online Edition，约 44.6 MB)：推荐。体积小，核心、Python 和 Android 运行库会在首次设置时按需下载。
- 离线版 (Offline Edition，约 818.5 MB)：适合网络受限或希望一次性下载全部组件的用户。注意：超大文件，请确保在 Wi-Fi 环境下下载。
安装 APK：下载完成后，点击 APK 文件进行安装。系统可能会提示“未知来源”或“安装未知应用”，请根据提示，允许“浏览器”或“文件管理器”的安装权限，然后继续安装。此过程无需 root 权限。

三、首次启动与引导配置

首次打开 Mobile Harness，会进入一个交互式设置向导，整个过程大约需要 10 分钟。

系统就绪检查：应用会自动检查设备的存储空间、CPU 架构和后台服务权限。请根据提示，允许应用获取必要的权限（如存储、后台活动等）。
下载核心运行环境 (Ubuntu 子系统)：
- 这是最关键的一步。应用会下载一个完整的 Ubuntu 20.04 LTS ARM64 镜像 (rootfs)。
- 下载体积较大 (数百 MB)，请务必连接稳定的 Wi-Fi，并保持应用在前台运行，避免下载中断。
- 下载完成后，应用会自动在 PRoot 环境中解压和配置这个 Ubuntu 子系统。
选择并安装可选工具链：
- 根据你的开发需求，可以勾选安装额外的工具包：
  - Python 套件：Python 3.10、pip、virtualenv 等。
  - Android & JVM：OpenJDK 17 和 Gradle 构建工具（用于在手机上直接编译 Android 应用）。
  - C/C++ 编译器：GCC、Clang、Make 等。
  - PHP 开发：PHP CLI、Composer 等。
- 提示：如果不确定，可以暂时只选择“核心”环境，后续在应用“设置”中随时添加。
配置 AI 提供商：
- Mobile Harness 原生集成了 Claude Code。你需要在此步骤中输入你的 Anthropic API Key。
- 应用也支持 OpenRouter、DeepSeek（需兼容 Anthropic 的端点）或自定义 API 网关。根据你的情况选择并填入对应的 API 密钥。
- 安全提示：所有 API 密钥都会使用 Android 硬件级 Keystore (AES-256 GCM) 进行加密存储，仅在内存中使用时解密，安全性较高。

四、创建你的第一个项目

完成引导配置后，就可以开始使用 Mobile Harness 了。

启动并创建项目：
- 在应用主界面，点击 “New Project” (新建项目) 按钮。
- 为你的项目命名，并选择工作空间。应用会自动在 Ubuntu 子系统的用户目录下创建对应的项目文件夹。
打开 AI 工作区 (AI Workspace)：
- 进入项目后，点击 “AI Workspace” 选项，这将启动集成的 Claude Code 代理界面。
- 你可以在这里用自然语言描述你想要开发的应用或功能，AI 代理会理解你的需求，并自动执行文件创建、代码编写、命令运行等一系列操作。你可以实时查看它的思考过程和执行步骤。
查看与管理项目：
- 你可以在 “Projects” 界面查看所有项目，并随时切换。
- “Terminal” 界面提供了一个 Linux 终端，你可以在此手动执行任何命令 (如 ls, git clone, npm install)。
- 通过 “Files” 浏览器，你可以浏览、编辑、搜索项目内的所有文件，并且支持通过 Android 存储访问框架 (SAF) 导入或导出文件。

五、高级功能：在手机上编译 Android 应用

这是 Mobile Harness 的一大亮点。你可以在手机上完成 Android 应用的编译和安装。

准备工作：在引导配置中，确保已安装 “Android & JVM” 工具链。
编写代码：通过 AI 代理或手动编辑，在项目目录中创建标准的 Android 项目结构 (包含 build.gradle 等文件)。
执行构建：在应用的“Terminal”中，进入 Android 项目根目录，运行 ./gradlew assembleDebug 命令。Mobile Harness 会在其 Ubuntu 环境中调用 Gradle 进行编译。
安装 APK：编译成功后，无需 USB 调试或 ADB 配对，你只需点击应用界面上的 “构建并运行” (Build and Run) 按钮。系统会弹出 Android 的包安装器，允许来自“Mobile Harness”的安装请求后，APK 就会被安装到你的手机上，并可直接启动。

常见问题与故障排除

“CPU 架构不兼容”提示：应用仅支持 arm64-v8a。如果你的设备是 32 位 ARM 或 x86 架构，则无法安装。
下载 Ubuntu 环境失败或中断：检查网络连接，确保 Wi-Fi 稳定且有足够存储空间。可以尝试切换 Wi-Fi 或使用手机网络（注意流量）。如果问题依旧，可考虑下载“离线版”APK 重新安装。
应用运行缓慢或卡顿：
- 大型编译任务确实会消耗较多资源，请耐心等待。
- 建议在手机 设置 -> 电池 中，将 Mobile Harness 加入“未优化应用”列表，避免系统限制其后台性能。
AI 代理无法连接或调用工具：
- 检查你输入的 API Key 是否正确且有效。
- 确认你使用的模型和 API 端点支持 Anthropic 兼容的工具调用 (Tool Calling) 功能。
无法输入命令或终端显示异常：当前的终端模拟通过进程桥接实现，而非完整的 PTY 仿真。对于 vim、top 等全屏交互式程序，可能存在显示异常。建议使用 nano 等更简单的编辑器，或通过文件浏览器直接编辑。