Roam（漫游）是一款macOS 原生的 Android 真机定位模拟工具。在 Mac 上画路线、选运动模式，通过 USB + ADB 将连续变化的 GPS 坐标注入 Android 真机，实现可复现的位置测试场景。
1. 系统要求
- macOS：macOS 15+（Apple Silicon），屏幕分辨率 ≥ 1280×800
- Android 真机：Android 10–16，已开启「开发者选项」→「USB 调试」
- ADB：需提前安装
adb命令行工具（推荐通过brew install android-platform-tools）
Android 真机需开启「开发者选项」中的「选择模拟位置信息应用」，指向 Roam Companion。
2. 安装与首次设置
2.1 安装 Roam
打开下载的安装包，将 Roam 拖入「应用程序」文件夹即可。首次打开时 macOS 可能会提示安全确认，在「系统设置 → 隐私与安全性」中允许即可。
2.2 连接手机
- 用 USB 数据线连接 Android 真机到 Mac。
- 手机弹出「允许 USB 调试」提示，勾选「始终允许」后确认。
- 打开 Roam，应用会自动检测 ADB 和设备。
2.3 三步引导
首次使用会进入 Setup 引导页，依次完成：
- 连接手机：确认设备已通过 USB 连接且显示为
device状态 - 安装 Companion：Roam 会自动检测手机上的 Companion 版本，如需安装/升级会提示
- 选择 Mock App：在手机开发者选项中确认「选择模拟位置信息应用」已设为 Roam Companion
右侧面板实时显示设备信息（型号、Android 版本、序列号脱敏显示等）。
3. 界面布局
Roam 采用单窗口三段式布局：
| 区域 | 位置 | 功能 |
|---|---|---|
| Sidebar（侧栏） | 左侧 | 设备状态、路线点列表、运动模式选择 |
| 地图 | 中间 | MapKit 地图，搜索、点击添加路线点，实时显示模拟位置 |
| Inspector（检查器） | 右侧 | 途经点详情、速度设置、开始模拟按钮 |
底部 PlaybackBar 在模拟过程中显示播放状态、进度、遥测数据和控制按钮。
4. 创建路线
4.1 搜索地点
使用左上角搜索框输入地址或地名，选中搜索结果后地图会自动定位到该位置。
4.2 添加路线点
- 在地图上单击任意位置即可添加途经点
- 第一个点为起点，后续点依次连接形成路线
- 在侧栏列表中可以拖动调整顺序、点击删除单个点
- 路线会自动尝试道路规划（调用 Apple MapKit MKDirections）；若道路规划失败，自动回退为直线连接
5. 运动模式
在右侧 Inspector 面板中选择运动 Profile，决定手机沿路线移动的速度：
| 模式 | 默认速度 | 适用场景 |
|---|---|---|
| 🚶 走路 | 5 km/h | 步行导航测试、计步器 |
| 🏃 跑步 | 10 km/h | 运动追踪、健身应用 |
| 🚴 骑行 | 20 km/h | 骑行路线、外卖配送 |
| 🚗 驾车 | 45 km/h | 导航、打车、物流 |
所有模式均支持自定义速度，输入任意 km/h 数值即可。
6. 播放控制
6.1 开始模拟
- 确认路线、运动模式和手机连接状态正常
- 点击「开始模拟」，Mac 端进入 Preparing 状态（显示"正在准备手机…"）
- 手机 Companion 启动 playback service 并返回 ready
- 进入 Playing 状态，手机开始以 1 Hz 频率接收更新坐标
6.2 控制操作
| 操作 | 按钮 | 快捷键 |
|---|---|---|
| 暂停 | 底部播放栏 ⏸️ | Space |
| 继续 | 底部播放栏 ▶️ | Space |
| 停止 | 底部播放栏 ⏹️ | ⌘. |
6.3 断连保护
USB 断连或 ADB 通道中断时：
- Mac 端 PlaybackBar 变黄，显示"等待 5 秒后手机将安全停止"
- 手机端心跳超时（默认 5 秒）后自动清除 Mock Location Provider，恢复真实 GPS
- 可在「设置 → 断连宽限时间」中调整超时（1–15 秒）
7. 实时遥测
模拟过程中，底部 PlaybackBar 实时显示：
- 当前坐标（经纬度）
- 当前速度（km/h）
- 移动方向（方位角）
- 定位精度
- 已用时间 / 剩余时间
- 路线进度条
- 注入状态指示灯
8. 诊断面板
遇到问题时，打开菜单栏「窗口 → 诊断」（或 ⌘D），可查看五项健康检查：
| 检查项 | 内容 | 状态语义 |
|---|---|---|
| ADB | ADB 是否可用、版本号 | 🟢 正常 / 🟡 警告 / 🔴 异常 |
| USB | 设备连接状态 | 🟢 device / 🟡 unauthorized / 🔴 offline |
| Companion | Companion 版本、安装状态 | 🟢 已安装 / 🔴 未安装或版本过旧 |
| Mock Location | Mock App 选择、权限 | 🟢 已配置 / 🔴 未选择 |
| Playback | 播放服务可启动性 | 🟢 可启动 / 🔴 异常 |
下方「事件时间线」按时间倒序列出关键事件（连接、断连、播放启动/停止、异常等）。点击「复制诊断」可将完整诊断信息复制到剪贴板，发给技术支持时使用（设备序列号和用户路径已自动脱敏）。
9. 设置
在菜单栏「Roam → 设置」中可配置：
- ADB 路径：手动指定
adb可执行文件路径（默认自动检测） - 断连宽限时间：USB 断连后手机侧等待多少秒后自动停止（默认 5 秒，范围 1–15 秒）
- 隐私说明：查看数据收集与隐私政策摘要
10. 重要声明
- Roam 走 Android 官方 Mock Location API，不隐藏
isMock标记。若被测应用检测到模拟位置并拒绝服务，这是被测应用的预期行为，不是 Roam 的缺陷。 - Roam 不涉及 root、不修改系统、不注入代码、不做反检测对抗。
- Roam 定位为开发与测试工具，不应用于考勤作弊、游戏区域解锁、社交定位伪造等用途。
- 使用 Roam 进行测试时，请确保手机上的其他应用不会因位置跳变产生意外行为（如打车应用可能误派单）。
11. 意见反馈
遇到问题、发现 Bug 或有功能建议，欢迎邮件联系 selfren@163.com。反馈时附上诊断面板的复制内容，能更快定位问题。