Phone-Eye 📱👁️

让你的 AI 智能体看到——并操作——一台真实的 Android 手机。

你的编码智能体能读代码、跑命令、查文档。但它能看到自己正在构建的应用，在真实手机上、以真实像素呈现的样子吗？Phone-Eye 给了它眼睛和手指。

phone_look("what's on screen, and where is the login button?")
  → "Login button at (540, 1830) — a green 'Sign in' …"
phone_tap(540, 1830)
phone_look("did the next page load?")

五个动词，无需框架：你的智能体把它们组合成任何它需要的工作流。适用于任何 MCP 客户端——Claude Code、Codex、Cursor、dsh 等。

为什么

如果你构建或测试任何最终会运行在手机上的东西，你一定熟悉这个循环：真机上的布局坏了，你手动截图，用文字描述屏幕（“右上角齿轮，账户图标旁边那个”），然后在智能体和手机之间扮演坐标解码器。Phone-Eye 关闭了这个循环——智能体像操作代码库一样直接与设备迭代。

两个通道，融合使用：

• 视觉——视觉模型回答关于实时截图的自然语言问题（适用于游戏画布、图片，任何像素能显示的内容）。

• UI 树——uiautomator 转储，在无障碍树可用时提供精确文本和边界。

视觉是可插拔的。 任何暴露 describe_image(path, question) 的 MCP 服务器都可以——开箱即用云端 GLM 视觉，或指向本地 Qwen-VL 端点，让像素永不离开你的局域网。

Related MCP server: scrcpy-mcp

安装

要求：Python 3.10+，adb（platform-tools / android-tools）在 PATH 中，开启 USB 调试的手机，以及任意 MCP 视觉服务器。

git clone https://github.com/boheastill/phone-eye
cd phone-eye
pip install -r requirements.txt

# env (defaults shown):
export ANDROID_SERIAL=""                      # empty = first adb device; or 192.168.x.x:5555
export PHONE_EYE_VISION_URL="http://127.0.0.1:8102/mcp"  # your vision MCP

将其接入你的客户端（stdio）：

// Claude Code / dsh-mcp-client / any stdio MCP config
{
  "mcpServers": {
    "phone-eye": { "command": "python", "args": ["/path/to/phone-eye/server.py"] }
  }
}

或者作为 HTTP 服务（streamable-http）运行在你自己的集群后面，并添加 http://<host>:8122/mcp——参见 docs/fleet.md。

连接手机（一次性）

USB 连接一次，之后永久 Wi-Fi：

adb devices                      # USB: accept the debugging prompt on the phone
adb tcpip 5555                   # switch to Wi-Fi mode
adb connect <phone-ip>:5555      # unplug and go

工具

是什么 / 不是什么

✔ 智能体在一台真实 Android 设备上的眼睛 + 手，零设备端安装，无需 root ✔ 视觉优先（在 UI 树无法看到的地方也能工作），结合树融合实现精确操作 ✔ 隐私选项：将视觉指向仅局域网模型

✘ 不是测试框架（没有 DSL/录制器——智能体就是逻辑） ✘ 不支持 iOS，不支持设备农场（尚未） ✘ 不是面向人类的移动 UI（那是另一个产品）

状态与路线图

阶段 1（当前）： 五个动词，单设备，可插拔视觉——已在真实硬件上端到端验证（Redmi K40 Gaming / Android 13）。它目前最喜欢的把戏：它自己发现了屏幕上的 USB 调试授权对话框，读取了按钮，然后自己点击了“允许”。

• 阶段 2：离线视觉快速入门，多设备寻址，重试/验证包装器

• 其他一切：请求驱动——提交 issue，它就会在队列中前移。

许可证

MIT

常见问题

视觉服务器？我没有。 任何暴露 describe_image(path, question) 的 MCP 服务器都可以。最快的云端选项是 GLM 视觉端点；完全离线的话，本地 Qwen-VL（llama.cpp / Ollama OpenAI 兼容 + 一个 20 行的适配器）能让每个像素都留在你的局域网内。

为什么不用 dsh 原生插件？ MCP 优先意味着同样的五个动词在每个客户端中都能工作。dsh 用户可以通过 @deepseek-ai/dsh-mcp-client 或 dsh plugin add 接入。

已验证设备

通过 PR 将你的设备添加到这个表格。