内容
# serve-droid
**一个共享的浏览器控制台和代理控制平面，用于 Android。** 流式传输模拟器或物理设备，从 Chrome 或 Edge 控制它，检查其语义 UI 树和 Logcat，或将同一会话交给与 MCP 兼容的编码代理。
> 状态：v0.1 开发版本。公共 API 已版本化，但视频传输和设备兼容性仍需要在发布的支持矩阵上验证。
```bash
npx serve-droid
# → 浏览器控制台，位于本地身份验证 URL
```
_一个共享会话：左侧是活动设备控制，中间是实时 Android 表面，右侧是代理上下文，例如过滤后的 Logcat 或语义 UI 树。确定性演示还锻炼了身份验证的文件安装和剪贴板流程。这不是真实设备验证；硬件证据单独在发布检查清单中跟踪。_
## 你能得到什么
- H.264 设备流式传输，在响应式浏览器控制台中，具有点击即点和拖动即滑动的控制。
- 精确的语义元素定位，停止在缺失或模糊的匹配上。
- 可搜索、优先级过滤的 Logcat，具有暂停、清除和复制控制。
- 安全的 LAN 令牌输入和有界剪贴板粘贴到聚焦的 Android 字段。
- 拖放 APK 或文件传输，具有字节进度和明确的 Android 处理阶段。
- 一个有界观察，包含屏幕、UI 层次结构、前台应用、设备状态和增量日志。
- 通过 CLI、身份验证的 HTTP/WebSocket API、MCP 和代理技能提供相同的功能。
## 为什么
Android Studio 镜像设备，scrcpy 提供优秀的原生显示/控制，Maestro 是一个强大的测试自动化系统。serve-droid 专注于一个不同的循环：在开发和调试期间，人类和 AI 代理共享一个可观察的浏览器会话。
## 要求
- Node.js 22 或更新版本
- [Android SDK 平台工具](https://developer.android.com/tools/releases/platform-tools)，带有 `adb`，位于 `PATH`、`ANDROID_HOME` 或 `ANDROID_SDK_ROOT`
- Android 8 / API 26+ 模拟器或设备，在 `adb devices -l` 中可见
- 当前的 Chrome、Edge、Safari 或 Firefox 浏览器。Chromium 使用 WebCodecs；Safari 和 Firefox 使用更高成本的 TinyH264 软件回退。
Android 平台工具从不被静默下载或重新分发。
## 快速开始
```bash
npx serve-droid doctor
npx serve-droid avd list
npx serve-droid start --detach
npx serve-droid list --json
```
选择固定端口时，在触摸设备之前先探测它。已占用的端口返回稳定的 `PORT_IN_USE` 代码和退出状态 `31`；`--port 0` 保持安全的临时分配。
```bash
npx serve-droid doctor --port 47321 --json
npx serve-droid start --port 47321
```
设备播放音频是可选的，浏览器播放在人类启用之前保持静音：
```bash
npx serve-droid start --audio
```
参见 [设备音频和隐私](docs/audio.md)。
打开打印的本地 URL。服务器监听 `127.0.0.1`，生成一个随机令牌，并将其注入本地 UI。要选择设备：
```bash
npx serve-droid --device emulator-5554
```
已安装的模拟器可以使用 `serve-droid avd start <name>` 和 `serve-droid avd stop <serial>` 显式管理。不自动下载或许可 SDK 内容；参见 [AVD 生命周期指南](docs/avd.md)。
要使用独立令牌和有界资源检查多个连接的设备：
```bash
npx serve-droid grid --max-devices 4
```
参见 [多设备网格安全性和隔离模型](docs/grid.md)。
坐标归一化：`(0, 0)` 是逻辑左上角，`(1, 1)` 是右下角。
```bash
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'
```
会话捕获是显式的和有界的。`--record ./recordings` 存储原始 H.264 流和隐私过滤的事件摘要；它从不记录令牌、Logcat、键入的文本、URL 或文件内容。参见 [录制和保留指南](docs/recording.md)。
## MCP
```json
{
"mcpServers": {
"serve-droid": {
"command": "npx",
"args": ["-y", "serve-droid", "mcp"]
}
}
}
```
MCP 界面故意提供显式有界工具，而不是任意 shell 访问。参见 [MCP 指南](docs/mcp.md)。
## 安全性
- 默认情况下仅绑定到环回。
- 读取、突变、视频和控制的 bearer 身份验证。
- 浏览器 WebSocket 在子协议头中携带凭证，而不是 URL。
- 没有任意 ADB 或主机 shell 端点。
- 上传限制为 256 MiB，写入私有临时目录，并立即删除。
- `clear` 和 `uninstall` 需要非交互式客户端的显式确认。
在绑定到 LAN 接口之前，请阅读 [SECURITY.md](SECURITY.md)。
通过现有的命名 Cloudflare 隧道进行短期远程访问，仅在明确同意、HTTPS、 bearer 身份验证和硬到期时可用。在使用它之前，请阅读 [隧道威胁模型和设置指南](docs/tunnels.md)。
## 支持和延期
v0.1 针对 macOS、Linux、Windows、Android API 26+、本地模拟器、USB 设备、Wi-Fi ADB、Chrome、Edge、Safari 和 Firefox。已安装的 AVD 生命周期控制、可选的有界本地录制、TinyH264 浏览器回退、可选的 API 30+ 设备音频和可选项过期命名隧道支持均已包含。云设备实验室、帐户、多用户角色、AVD 创建/配置、iOS 和任意 shell 访问已被延期。参见 [浏览器支持矩阵](docs/browser-support.md)。
## 开发
```bash
pnpm install
pnpm verify
pnpm --filter @serve-droid/cli dev -- doctor
```
Android 夹具源位于 `fixtures/android-test-app`。只有当设置 `SERVE_DROID_DEVICE_TEST=1` 时，真实设备测试才会运行。
参见基于证据的 [发布检查清单](docs/TODO.md)，了解已完成的工作和剩余的硬件、平台和发布门控。
## 项目待办事项
- [x] 发布具有保护的 `main`、CodeQL、Dependabot 和秘密扫描的开放存储库。
- [x] 交付共享的 CLI、HTTP/WebSocket、MCP、代理技能和浏览器控制台基础。
- [x] 添加到此 README 的可复制、清晰标记的控制台截图。
- [x] 添加具有优先级过滤、暂停、清除和复制的可搜索 Logcat 控制。
- [x] 添加安全的 LAN 令牌交接和有界浏览器剪贴板控制。
- [ ] 在 macOS、Linux 和 Windows 上完成真实设备验收矩阵。
- [ ] 在标记 v0.1.0 之前发布和验证 npm 发布候选版本。
完整的、基于证据的检查清单位于 [docs/TODO.md](docs/TODO.md)。在存储库包含实现或所需的外部证据之前，项目保持未选中状态。
## 许可证
Apache-2.0。参见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
