内容
# phonefast — 将手机作为 AI 智能体的原生设备
phonefast 将您的安卓手机变成 AI 智能体的原生外设，就像键盘、鼠标和显示器是人类的原生外设一样。它结合了 scrcpy 视频流媒体和适合手机的操作语义，支持 MCP 协议集成和本地 CLI 使用。
**核心功能：**
- 🚀 **守护进程模式** — 后台持久进程，Unix 套接字 JSON-RPC，瞬间命令响应
- 📱 **直接模式** — 无守护进程，每次创建新连接，适合临时操作
- 🔌 **MCP 协议** — SSE / STDIO 双重传输，AI 助手可以直接控制手机
- 💓 **三级保活** — TCP 保活 + 应用心跳 + 写触发恢复，10 秒内自动重连
- 📝 **异步日志** — 基于协程的文件写入，记录所有关键操作和功能上下文
---
## Live Demo: Claude Code + phonefast
> **4 倍速** — Claude Code + phonefast 真实执行。
> 提示：`使用 phonefast 技能：打开 Google Play 并安装 Instagram`
---
## 性能
phonefast 的守护进程模式在所有操作中始终保持低延迟。下面是 **12 小时压力测试** 的结果（v1.0.11，145,843 次操作，100% 成功率，零重连）：
| 操作 | P50 | P95 | P99 | 备注 |
|-----------|:---:|:---:|:---:|-------|
| `tap` | **13ms** | 13ms | 14ms | 点击坐标 |
| `back` / `home` / `press_key` | **12-13ms** | 13ms | 14ms | 硬件按键事件 |
| `screenshot` | **28ms** | 126ms | 128ms | H.264 关键帧 → PNG |
| `observe` | **28ms** | 126ms | 129ms | 截图 + UI（原子） |
| `get_ui_elements` | **46ms** | 132ms | 151ms | 通过 UISocketHandler 获取 UI 树 |
| `swipe` | **318ms** | 322ms | 323ms | 滑动手势（包括 300ms 时长） |
| `type_text` / `launch_app` / `status` | **1ms** | 1-2ms | 2-4ms | 发射即忘语义 |
| `wait` | **33ms** | 33ms | 33ms | 睡眠命令 |
**关键基准：**
- 守护进程模式响应时间：**<13ms** 用于触摸和按键操作
- 截图 P50：**28ms** （比 v1.0.0 的 121ms 快 4.3 倍）
- 实际物理内存：**~16MB** 稳定状态（通过 vmmap 验证）
- 12 小时压力测试：**145,843 次操作，100% 成功，0 次重连**
- 连续 200 张截图：**P50 = 12ms，P95 = 13ms** （热解码器）
> 详细的基准测试历史、版本比较和方法论见 [docs/benchmark.md](docs/benchmark.md)。
---
## 入门指南
### 安装
**前提条件：** Go 1.21+，`adb`，`ffmpeg`，`git`
```bash
# 从源代码构建
bash scripts/build.sh # 当前平台
bash scripts/build.sh --all # 跨平台构建 + 打包
# 或从 GitHub Releases 下载预构建二进制文件
# https://github.com/gezihua123/phonefast/releases
```
> 构建细节（交叉编译、FFmpeg 静态链接）→ [docs/DEV.md](docs/DEV.md)
### 快速开始
```bash
# 列出连接的设备
phonefast devices
# 默认守护进程模式 — 瞬间响应（<10ms）
phonefast tap 540 960
phonefast back
phonefast screenshot /tmp/screen.png
# 直接模式 — 每次新建连接（~2.5s），添加 --foreground
phonefast --foreground tap 100 200
# 启动 MCP 服务器（用于 AI 助手）
phonefast serve
```
---
## 命令参考
### 格式
```bash
phonefast [--foreground|--daemon] <command> [args...]
```
- 默认使用守护进程模式（自动启动守护进程），延迟 <10ms。
- `--foreground` / `--direct` — 直接模式，每次创建新的 scrcpy 连接，约 2.5s。
- `--daemon` — 显式指定守护进程模式（与默认相同，保留兼容性）。
---
### 触摸操作
#### `tap` — 点击坐标
```bash
phonefast [--foreground|--daemon] tap <x> <y>
```
| 参数 | 描述 |
|-----------|-------------|
| `x` | X 坐标（像素） |
| `y` | Y 坐标（像素） |
```bash
phonefast tap 540 960 # 点击屏幕中心
phonefast --foreground tap 100 200 # 直接模式
```
#### `tap_element` — 点击 UI 元素
```bash
phonefast [--foreground|--daemon] tap_element <index|text>
```
| 参数 | 描述 |
|-----------|-------------|
| `index` | UI 元素索引（来自 `ui` 命令） |
| `text` | UI 元素文本或描述（模糊搜索） |
```bash
phonefast tap_element 5 # 点击第 5 个 UI 元素
phonefast tap_element "设置" # 点击包含 "设置" 文本的元素
```
#### `swipe` — 滑动手势
```bash
phonefast [--foreground|--daemon] swipe <x1> <y1> <x2> <y2> [duration_ms]
```
| 参数 | 描述 | 默认值 |
|-----------|-------------|---------|
| `x1` `y1` | 起始坐标 | — |
| `x2` `y2` | 结束坐标 | — |
| `duration_ms` | 滑动时长（毫秒） | 500 |
```bash
phonefast swipe 540 1600 540 400 500 # 向上滑动
phonefast swipe 200 500 800 500 300 # 向右滑动 300ms
```
---
### 文本输入
#### `type` — 输入文本
```bash
phonefast [--foreground|--daemon] type <text>
```
在当前聚焦的输入字段中输入文本。
```bash
phonefast type "Hello World"
phonefast type "搜索关键词"
```
---
### 按键操作
#### `back` — 后退键
```bash
phonefast [--foreground|--daemon] back
```
#### `home` — 首页键
```bash
phonefast [--foreground|--daemon] home
```
#### `key` — 发送按键事件
```bash
phonefast [--foreground|--daemon] key <keyname|keycode>
```
**支持的按键名称：**
| 按键名称 | 描述 |
|----------|-------------|
| `enter` | 回车 |
| `tab` | 制表键 |
| `delete` / `backspace` | 删除 |
| `space` | 空格 |
| `escape` / `esc` | 逃脱键 |
| `volume_up` / `volume_down` | 音量 +/- |
| `volume_mute` | 静音 |
| `power` | 电源按钮 |
| `menu` | 菜单键 |
| `search` | 搜索键 |
| `camera` | 摄像头键 |
| `back` | 后退（与后退命令相同） |
| `home` | 首页（与首页命令相同） |
| `dpad_up` / `dpad_down` / `dpad_left` / `dpad_right` / `dpad_center` | 方向键 |
| `page_up` / `page_down` | 上/下翻页 |
| `media_play_pause` / `media_stop` / `media_next` / `media_previous` | 媒体控制 |
```bash
phonefast key enter
phonefast key backspace
phonefast key volume_up
phonefast key power
phonefast key dpad_down
# 也可以直接使用按键码
phonefast key 4 # 后退
phonefast key 3 # 首页
phonefast key 66 # 回车
```
---
### 应用操作
#### `launch` — 启动应用
```bash
phonefast [--foreground|--daemon] launch <package>
```
使用 Android 包名（不支持显示名称，如 "设置" 或 "Chrome"）。
```bash
phonefast launch com.android.settings # 设置
phonefast launch com.android.chrome # Chrome
phonefast launch com.tencent.mm # 微信
```
---
### 屏幕捕获与分析
#### `screenshot` — 截图
```bash
phonefast [--foreground|--daemon] screenshot [file]
```
| 参数 | 描述 | 默认值 |
|-----------|-------------|---------|
| `file` | 保存路径 | stdout（base64） |
```bash
phonefast screenshot /tmp/screen.png # 保存为 PNG
phonefast screenshot # 输出 base64
```
#### `ui` — UI 元素列表
```bash
phonefast [--foreground|--daemon] ui
```
输出当前屏幕上的所有交互式 UI 元素（最多 50 个），包括索引、文本、资源 ID、类名和可点击状态。
```
[0] id="content" (FrameLayout)
[1] id="webView" (FrameLayout)
[2] text="搜索" (EditText) [可点击]
[3] text="设置" id="settings_btn" (Button) [可点击]
```
#### `observe` — 截图 + UI
```bash
phonefast [--foreground|--daemon] observe
```
在单个调用中同时捕获截图和 UI 数据，以获取完整的屏幕状态快照。
---
### 实用命令
#### `wait` — 等待
```bash
phonefast [--foreground|--daemon] wait <ms>
```
| 参数 | 描述 | 默认值 |
|-----------|-------------|---------|
| `ms` | 等待毫秒数 | 1000 |
#### `status` — 守护进程状态
```bash
phonefast [--foreground|--daemon] status
```
```bash
# 示例输出
守护进程运行中（pid 60977）
设备： 13709314CF044927 （488x1080）
控制： true
UI： true
```
#### `devices` — 设备列表
```bash
phonefast devices
```
```bash
# 示例输出
已连接设备：
13709314CF044927 设备 [TECNO_KL8h]
```
#### `run` — JSON 单个操作
```bash
phonefast [--foreground|--daemon] run '<json>'
```
适用于脚本自动化。
```bash
phonefast run '{"action":"tap","args":{"x":540,"y":960}}'
phonefast run '{"action":"screenshot"}'
phonefast run '{"action":"back"}'
phonefast run '{"action":"list_devices"}'
```
支持的操作：`tap`、`tap_element`、`swipe`、`back`、`home`、`type_text`、`press_key`、`launch_app`、`screenshot`、`get_ui_elements`、`observe`、`list_devices`、`wait`。
---
## 守护进程管理
守护进程是一个后台持久进程，持有长期设备连接，并通过 Unix Socket 接收 JSON-RPC 请求。
```bash
# 启动守护进程（后台）
phonefast daemon
# 前台模式（查看实时日志）
phonefast daemon --foreground
# 指定设备序列号
phonefast daemon --serial 13709314CF044927
# 自定义套接字/PID 文件路径
phonefast daemon --socket /tmp/my-phone.sock
# 检查守护进程状态
phonefast daemon --status
# 停止守护进程
phonefast daemon --stop
```
**自动管理：**
- 执行带有 `--daemon` 标志的命令时，如果守护进程未运行，则会自动启动
- 如果守护进程存在但无响应，则会自动杀死并重启
- 多次调用 `phonefast daemon` 不会启动重复实例（如果已经运行则退出）
- 三级保活机制检测连接故障并在 10 秒内恢复
> 详细的守护进程生命周期、启动流程和恢复机制 → [docs/CLI.md#5-daemon-management](docs/CLI.md)
---
## MCP 服务器
phonefast 可以作为 MCP（Model Context Protocol）服务器，允许像 Claude Desktop 这样的 AI 助手直接控制手机。
```bash
# SSE 模式（默认端口 8019）
phonefast serve
# 自定义端口
phonefast serve --port 8080
# 自定义路径
phonefast serve --path /mcp
# STDIO 模式（Claude Desktop 集成）
phonefast serve --transport stdio
```
### 客户端配置
**SSE 模式：**
```json
{
"mcpServers": {
"phonefast": {
"url": "http://localhost:8019/Phone/sse"
}
}
}
```
**STDIO 模式：**
```json
{
"mcpServers": {
"phonefast": {
"command": "phonefast",
"args": ["serve", "--transport", "stdio"]
}
}
}
```
### MCP 工具列表
| 工具 | 参数 | 描述 |
|------|------------|-------------|
| `list_devices` | — | 列出连接的安卓设备 |
| `screenshot` | — | 捕获当前屏幕（base64 PNG） |
| `get_ui_elements` | — | 获取交互式 UI 元素 |
| `observe` | — | 截图 + UI 元素（单个调用） |
| `tap` | `x`、`y` | 点击坐标 |
| `tap_element` | `index` 或 `text` | 点击 UI 元素 |
| `swipe` | `start_x`、`start_y`、`end_x`、`end_y`、`duration_ms` | 滑动手势 |
| `type_text` | `text` | 输入文本 |
| `back` | — | 后退键 |
| `home` | — | 首页键 |
| `press_key` | `keycode` 或 `key` | 发送按键事件 |
| `launch_app` | `package` | 启动应用（仅限包名，如 `com.android.settings`） |
| `wait` | `duration_ms` | 等待 N 毫秒 |
---
## 模式比较
| | 守护进程模式 | 直接模式 |
|------|-------------|-------------|
| 命令格式 | `phonefast <cmd>`（默认） | `phonefast --foreground <cmd>` |
| 响应速度 | <10ms | ~2.5s |
| 资源使用 | 单个后台守护进程 | 每次创建/销毁连接 |
| 用例 | 批量操作、脚本自动化 | 临时单个操作 |
| 自动管理 | 自动启动/重启/恢复 | 无状态 |
---
## 参考文档
| 文档 | 内容 |
|----------|---------|
| [docs/CLI.md](docs/CLI.md) | 完整的 CLI 手册：安装、命令、守护进程、MCP、架构、日志、恢复 |
| [docs/DEV.md](docs/DEV.md) | 开发笔记：架构决策、构建和发布、交叉编译 |
| [docs/benchmark.md](docs/benchmark.md) | 完整的基准测试历史：版本比较、方法论、内存分析 |
| [docs/phonefast.md](docs/phonefast.md) | 产品比较：phonefast vs agent-device vs adb |
| [CHANGELOG.md](CHANGELOG.md) | 版本发布历史 |
---
## 许可证
MIT
