OpenDroidWindow 是一个 macOS 菜单栏工具，用于发现已授权的 Android 设备，把应用启动到 scrcpy 虚拟显示窗口，并为 Mobile MCP 自动化提供可发现的 displayId 会话。
仓库还包含：
- Windows 10/11 x64 WPF 客户端；
- 对原生 HarmonyOS 设备的有限 HDC 管理；
- 一个与 Android 虚拟显示主线分离的 iPhone WhatsApp 导出实验性 PoC。
- USB ADB / Wi‑Fi 或 Tailscale ADB 设备发现；
- 应用库、搜索、收藏、隐藏和第三方应用卸载；
- 在独立 scrcpy 虚拟显示中启动应用，或镜像整个 Android 设备；
- 触控板滚动速度、整机镜像键盘模式和 Touch ID 辅助输入；
- 保存会话与虚拟显示 ID，供 MCP companion 查找。
OpenDroidWindow 使用 scrcpy 4.1+ 的虚拟显示能力，scrcpy 作为外部进程运行，不重新实现其视频、音频或控制协议。
| 平台 | 当前能力 |
|---|---|
| macOS 13+ | Android ADB + scrcpy 完整主线；原生 HarmonyOS HDC 设备发现、应用枚举和启动 |
| Windows 10 22H2 / 11 x64 | Android 设备发现、应用启动、虚拟显示、整机镜像、Wi‑Fi/Tailscale ADB、托盘和会话 |
| 原生 HarmonyOS | 通过 HDC 枚举和启动 Bundle；不支持 scrcpy 投屏、Android 虚拟显示或 displayId |
| iOS | 不接入 Android 设备管理和 displayId；仅提供独立的 WhatsApp 导出 PoC |
要求 macOS 13+、推荐 Android 12+、已开启 USB 调试并授权电脑，以及 Android Platform Tools。首次构建还需要 Xcode Command Line Tools。
brew install android-platform-tools git cmake meson ninja pkg-config autoconf automake libtool
adb devices
swift build
./scripts/build-app.sh
open dist/OpenDroidWindow.app应用优先使用系统 scrcpy 和 App Bundle 中的 adb；可用 ADB_PATH、SCRCPY_PATH 指定自定义工具。只调试 Swift 可执行文件时可运行 swift run。
连接设备后，在菜单栏设备菜单中选择应用即可启动；选择“镜像整个设备”可操作锁屏和系统界面。
安装 DevEco Studio 或包含 HDC 的 HarmonyOS SDK，并确认：
hdc list targets
HDC_PATH=/path/to/hdc swift runHDC 设备支持发现、读取设备信息、枚举 Bundle 和通过 Ability Assistant 启动应用；不支持 scrcpy 镜像、Android 虚拟显示、传统 adb tcpip 5555 或 Mobile MCP displayId。详见 docs/hdc.md。
安装 MSI 后，在手机开启 USB 调试并授权电脑，打开 OpenDroidWindow，点击“刷新”，选择应用并点击“打开”。完整的安装包构建、工具版本、Wi‑Fi/Tailscale ADB、会话目录和签名说明见 docs/windows.md。
首次切换需要 USB 数据线。应用会优先尝试手机的 Tailscale IPv4（100.64.0.0/10），否则使用普通局域网地址，并通过 TCP 5555 连接。Mac、手机和 Tailnet ACL/防火墙必须允许该端口。成功的 endpoint 会保存并在后续刷新时自动重连。
可录入手机当前已有的数字 PIN，之后用 Mac Touch ID 读取并通过 Android 物理键盘注入。它不会创建或修改手机 PIN，也不会绕过 Android 安全锁屏；PIN 不写入剪贴板、偏好设置、会话文件、命令行参数或日志。
Touch ID PIN 需要 macOS Data Protection Keychain，因此发布包必须带有效的 Apple 签名和 com.apple.application-identifier entitlement。swift run 或 ad-hoc 包仍可用于 ADB/镜像，但不能启用 Touch ID PIN 存储：
CODESIGN_IDENTITY="身份名称" CODESIGN_APP=required ./scripts/build-app.shmacOS 提供柔和（0.15×）、自然（0.30×，默认）和快速（0.55×）三档滚动。整机镜像默认使用 UHID 键盘模式，遇到兼容性问题时可切换到 SDK 兼容模式。外部 scrcpy 不支持 --scroll-scale 时，滚动优化会自动停用但窗口仍可使用。
macOS 会话文件位于：
~/Library/Application Support/OpenDroidWindow/sessions.json
Windows 会话文件位于：
%LOCALAPPDATA%\OpenDroidWindow\sessions.json
本仓库记录并暴露虚拟显示 ID，但不包含 Mobile MCP Android 适配器本身。适配器仍需将 displayId 传给截图、UI 树、点击和输入操作；当前设计与限制见 docs/mobile-mcp-display.md。
iOS 没有 scrcpy 级可编程镜像或每应用虚拟显示，因此 iOS 不属于 OpenDroidWindow 的 Android 设备管理主线。需要从真实 iPhone 归档 WhatsApp 时，仓库提供独立的 Mac MCP 服务和 iOS Share Extension：
tools/ios-whatsapp-mcp/：Appium/XCUITest 自动化、配对、任务状态和局域网接收；tools/ios-export-receiver/：iOS 主 App 与 Share Extension；docs/ios-whatsapp-export.md：架构、安装和安全边界；docs/ios-whatsapp-multi-device-runbook.md：换机、多设备和排障记录。
该 PoC 只走 WhatsApp 官方“导出聊天”流程，不读取数据库、不绕过锁屏，也不承诺无人值守生产运行。免费 Apple ID 仅适合验证，正式部署需要稳定的签名方案；导出文件只接收并保存到指定 Mac。
OpenDroidWindow 只操作用户已授权的设备，通过官方调试协议和正常应用 UI 执行操作，不读取应用私有数据库。自动化前请确认设备、应用和操作目标均已获得用户授权。HDC、Android ADB 和 iOS PoC 的协议与能力彼此隔离，iOS 导出不会获得 Android displayId 能力。
OpenDroidWindow is a macOS menu-bar launcher and Windows 10/11 x64 client for Android apps running in scrcpy virtual displays. It supports ADB, Wi‑Fi/Tailscale ADB, full-device mirroring, session displayId records, and limited native HarmonyOS management through HDC. iOS is separate: this repository includes an experimental WhatsApp export PoC using official chat export, Appium/XCUITest, and a paired Mac receiver; it is not an iOS virtual-display implementation.