serve-droid

一个适用于 Android 的共享浏览器驾驶舱与智能体控制平面。 你可以流式传输模拟器或实体设备，从 Chrome 或 Edge 操控它，检查它的语义化 UI 树和 Logcat，或把同一会话交给兼容 MCP 的编码智能体。

状态：v0.1 开发预览版。公共 API 已版本化，但视频传输和设备兼容性仍需对准发布版运行环境，等待完整验证。

npx serve-droid
# → Browser cockpit at a local authenticated URL

一个共享会话：紧凑的活跃设备控件留在左侧，而实时 Android 画面占据主要工作区。在宽屏上，智能体检查器以上下文相关的方式浮动在右侧，在过滤后的 Logcat、语义化 UI 和隐私安全的 Activity 之间切换；在较窄窗口中，它叠加到设备下方，而不缩小交互区域。确定性演示也练习了已认证的文件安装和剪贴板流程。这不是真实设备验证；硬件证据在发布检查清单中单独跟踪。

你将获得什么

• 响应式浏览器驾驶舱中的 H.264 设备流，直接指针 DOWN、合并的 MOVE 以及 UP/CANCEL 事件由同一实时 scrcpy 会话承载。

• 鼠标滚轮和触控板在设备上滚动，合并为有界的 scrcpy 触摸手势，因此，高分辨率浏览器输入无法创建设备指令积压。

• 一键截取实时解码帧，支持已认证的设备回退、预览、下载，以及浏览器支持的剪贴板操作。

• 精确的语义化元素定位，在缺失或不明确的匹配处停止。

• 可搜索、按优先级过滤的 Logcat，支持暂停、清除和复制。

• 设备专用音量降低/提高控制，独立于浏览器播放静音。

• 隐私过滤的内存中 Activity 时间线，线上记录最近的结构化会话、设备和控制事件。

• 安全的局域网令牌输入，以及有界的粘贴到焦点集中于 Android 字段。

• 拖放 APK 或文件传输，显示字节进度并留有显式的 Android 处理阶段。

• 一次有界的观测量，包含屏幕、UI 层级、前台应用、设备状态和增量日志。

• 通过 CLI、认证 HTTP/WebSocket API、MCP 和 Agent Skill 获得相同能力。

Related MCP server: phone-mcp-server

为什么

Android Studio 可以镜像设备，scrcpy 提供优秀的原生显示/控制，Maestro 是不错的测试自动化系统。serve-droid 的关注点不同：让人类和 AI 智能体在开发和调试期间共享一个可观测的浏览器会话。

灵感

浏览器优先的驾驶舱方向受 Evan Bacon 的 serve-sim 启发。serve-droid 是一个独立的、面向 Android 的实现，构建在 ADB、scrcpy 传输、Logcat、语义化观察和 MCP 之上。

要求

• Node.js 22 或更新。

• Android SDK 平台工具，其中 adb 存在于 PATH、ANDROID_HOME 或 ANDROID_SDK_ROOT。

• 在 adb devices -l 中可连接的 Android 8 / 26+ 模拟器或设备。

• 当前 Chrome、Edge、Safari 或 Firefox。Chromium 使用 WebCodecs；Safari 和 Firefox 使用成本更高的 TinyH264 软件回退。

Android 平台工具永远不会被静默下载或重新分发。

快速开始

npx serve-droid doctor
npx serve-droid doctor --browser
npx serve-droid avd list
npx serve-droid start --detach
npx serve-droid list --json
npx serve-droid activity --since 0 --json

serve-droid activity 读取与浏览器检查器显示相同的、有界且已通过隐私过滤的活动日志。它选择一个活动会话，在该会话内部认证，并支持不暴露持有者令牌的光标恢复。请参阅 Activity 指南。

选择固定端口时，请先探测端口，再操作设备。被占用的端口会返回稳定的 PORT_IN_USE 代码和退出状态 31；--port 0 则使用安全的随机端口。

npx serve-droid doctor --port 47321 --json
npx serve-droid start --port 47321

设备播放音频是可选功能，在用户主动开启前，浏览器播放将保持静音：

npx serve-droid start --audio

请参阅 设备音频与隐私。

打开打印的本地 URL。服务器监听在 127.0.0.1，并生成随机令牌，然后注入到本地 UI。要选择设备：

npx serve-droid --device emulator-5554

已安装的模拟器可以通过 serve-droid avd start <name> 和 serve-droid avd stop <serial> 显式管理。不会自动完成下载或购买任何 SDK 内容；请参阅 AVD 生命周期指南。

要管理多台独立令牌和受限资源的设备：

npx serve-droid grid --max-devices 4

请参阅 多设备安全与隔离模型。

坐标已归一化：(0, 0) 是逻辑画布左上角，(1, 1) 是逻辑画布右下角。

npx serve-droid tap 0.5 0.5
npx serve-droid swipe 0.5 0.8 0.5 0.2 --duration 350
npx serve-droid app deep-link 'servedroid://fixture/example'

当 ADB 交互失败时，如果 Android 没有明确报告锁屏或输入策略证据，则保留通用错误。请参阅 交互失败诊断 中的 DEVICE_LOCKED、SECURE_SCREEN 和 INPUT_RESTRICTED 合同。

浏览器指针输入现在通过控制 WebSocket 流式传输经过认证的 begin → move* → end 生命周期，而指针仍在移动。浏览器保持一个请求和一个最新待移动事件，服务器赋予该流对一只 scrcpy 独享手指的所有权，并将其映射到固定的编码帧尺寸。如果 scrcpy 在 begin 之前不可用，则请求会在设备输入激发前被忽略的实际；活检舱随后重新使用它现有的受限释放行为。begin 成功后，失败绝不会通过 ADB 重放。一种稀疏的同点心跳可保持连续的长按有效，而放弃的流会在两秒延迟后收到尽力而为的取消。

在浏览器中，悬停 Android 表面并使用鼠标滚轮或双指触控板。突发内容合并为一次有界由光标锚定的触摸滑动，修饰浏览器缩放手势在触控板上不拥挤通过。

录制会话是显式且有界的。--record ./recordings 保存原始 H.264 视频流以及隐私过滤之后的事件摘要；它绝不会记录令牌、Logcat、输入文本、URL 或文件内容。请改用 --record-controls ./recordings 来授权浏览器启动/停止录制，而不会立即录制；驾驶舱不选择主机路径或限制。请参阅录制与保留指南。你可以用 serve-droid recording trace 将已完成的录制导出为可以上网在 Perfetto 中检查片刻时间线。

MCP

{
  "mcpServers": {
    "serve-droid": {
      "command": "npx",
      "args": ["-y", "serve-droid", "mcp"]
    }
  }
}

MCP 区域故意只提供明确而有界的事物，而不是任意 shell 访问。请参阅 MCP 指南。

安全性

• 默认仅绑定回环地址。

• 读取、变更、视频和控制均使用 Bearer 认证。

• 浏览器 WebSocket 在子协议头中传递凭据，而不是使用 URL。

• 没有任意的 ADB 或主机 shell 端点。

• 上传最大为 256 MiB，限制在私有临时目录中，并随后立即删除。

• 对于非交互客户端，close 和 uninstall 需要显式确认。

在绑定 LAN 接口之前，请阅读 安全使用说明。

通过现有命名 Cloudflare Tunnel 的短期远程访问，仅在所有安全要求（显式同意、HTTPS、Bearer 认证和硬过期）都满足时免除。使用前，请阅读 隧道威胁模型和设置指南。

支持与暂缓

v0.1 支持 macOS、Linux、Windows、Android API 26+、本地模拟器、USB 设备、Wi-Fi ADB、Chrome、Edge、Safari 和 Firefox。已包含已安装 AVD 生命周期控件、可选的有界本地录制、TinyH264 浏览器后备、API 30+ 的可选设备音频，以及可选的实践恢复回隧道支持。台架云设备、账号、多用户角色、AVD 创建/精简内容、iOS 和任意 shell 访问暂不涉及。请参阅浏览器支持矩阵。

开发

pnpm install
pnpm verify
pnpm --filter @serve-droid/cli dev -- doctor

Android 专项源代码位于 fixtures/android-app。只有当设置 SERVE_DROID_DEVICE_TEST=1 时，才运行真机测试。

查看基于证据的发布检查表 以及剩下的硬件、完成、平台发布任务和发布检查表。

项目 TODO

• 发布带受保护的 main 分支、CodeQL、Dependabot 和密钥扫描的公开仓库。

• 提供共享 CLI、HTTP/WebSocket、MCP、Agent Skill 和浏览器驾驶舱基础。

• 为 README 添加一份可复现、清晰的驾驶舱截图。

• 将浏览器驾驶舱优化为设备优先的响应工作区，并配有上下文区域 Inspector。

• 添加带优先级过滤、暂停、清除和复制控制的可搜索线程日志 Logcat。

• 在浏览器、CLI 和认证 HTTP 中提供受限且隐私安全的 Activity 体验。

• 添加安全的局域网令牌移交，以及对浏览器剪贴板的边界在对应控件。

• 添加 Android 表面上的滚轮合并，以及触摸板滚动。

• 将浏览器指针和手势输入通过可使用的 scrcpy 控制通道路由。

• 在正式发布前先发送指针移动，并使用有界的合并和取消。

• 在 macOS、Linux 和 Windows 上完成真实设备验收矩阵。

• 在标签 v0.1.0 之前发布并验证 npm 候选版。

完整的、基于证据的清单位于 docs/TODO.md 中。在仓库中的实现成果来自用户不应。 在包含原始实现内部或外部证据之前，项目会保持未选中状态。

许可证

Apache-2.0。请看 THIRD_PARTY_NOTICES.md。