PreviewAPK

PreviewAPK — 为 AI Agent 提供一部手机

你的 Agent 构建了一个 Android 应用，然后……你们谁也看不到它运行。 机器上没有模拟器，桌面上没有设备，而 Play Store 也不是反馈渠道。

PreviewAPK 为你的 Agent 提供一部真实的云端 Android 手机。 推送 APK 后，它几秒内就会在浏览器中启动。Agent 可以操控它——点击、输入、截图、查看日志——并在你查看之前验证自己的成果。你可以通过链接查看同一部手机，随时接管操作；每台设备都有一个永久预览链接，可交给客户或贴到 PR 中。

• 每台设备每月 $19，运行次数不限。每台设备一次运行一个应用；可随时切换应用。
• 链接始终为只读。只有所有者的密钥（Agent）或门户中的所有者可以操控设备——每个会话只有一名操作者，可在会话中通过明确交接来切换。
• 手机不包含 Google Play 服务。需要 Google 登录、Maps 或 FCM 的应用会受此限制；其他应用都能正常运行。

本仓库提供开源客户端：CLI 和 MCP 服务（两者都只有一个文件，且仅使用 Python 标准库）。PreviewAPK 服务本身托管在云端——你需要使用自己在 previewapk.siteport.site 帐户中的 API 密钥。目前 PreviewAPK 正处于候补名单 Beta 阶段；可在该网站加入候补名单。

快速开始 — CLI

curl -O https://previewapk.siteport.site/cli/previewapk.py
export PREVIEWAPK_API_KEY=pvk_…        # from your portal's Developers card

python3 previewapk.py devices          # see your devices
python3 previewapk.py use "Device 1"   # pick the working device (like cd)
python3 previewapk.py push app.apk --run
python3 previewapk.py tree             # the screen as an element tree
python3 previewapk.py tap --text "Log in"
python3 previewapk.py text "[email protected]"
python3 previewapk.py shot             # a screenshot you can open
python3 previewapk.py logs --errors    # the app's logcat, noise filtered
python3 previewapk.py relaunch         # app back in front, ~2s, no reboot
python3 previewapk.py handoff user     # hand the human the wheel
python3 previewapk.py links            # your permanent preview link

向正在运行的设备推送应用会热切换应用——在同一会话中完成安装并重新启动，无需重启设备。

坐标使用比例值（0–1），而非像素；CLI 和 API 会拒绝超出范围的值，而不会悄悄点错位置；如果没有聚焦字段，text 会拒绝输入，而不会把文字打进虚空。 Agent 可以信赖这些信号：错误会说明发生了什么以及应该怎么做。

快速开始 — MCP 服务

从此仓库下载 previewapk_mcp.py，然后在 MCP 客户端中注册。Claude Code：

claude mcp add previewapk \
  --env PREVIEWAPK_API_KEY=pvk_… \
  -- python3 /path/to/previewapk_mcp.py

Cursor / Claude Desktop / 其他 MCP 客户端（JSON 配置）：

{
  "mcpServers": {
    "previewapk": {
      "command": "python3",
      "args": ["/path/to/previewapk_mcp.py"],
      "env": { "PREVIEWAPK_API_KEY": "pvk_…" }
    }
  }
}

17 个工具：列出/使用设备、推送（对正在运行的设备进行热切换）、启动、停止、链接、按坐标或标签点击、滑动、按键、输入文字、重新启动、截图（返回真实图像，来自帧缓冲区——与层级结构一致）、UI 层级结构、会话日志、交接。

工作设备模型与 CLI 一致：Agent 会话选择一次设备（previewapk_use_device 或 previewapk_start），之后即可在该设备上操作，无需重复指定设备名称。设备没有默认值——未选择设备时，操作会被拒绝，因此构建结果绝不会因默认假设而发送到错误的手机上。

Agent 应如何操控设备

使用层级结构（元素树：类、标签、中心点、状态标志）进行导航和断言——快速、成本低、精准。通过截图验证视觉效果。操作后查看日志；崩溃的确切原因就在其中。模拟器噪声（虚拟 GPU 产生的图形栈垃圾信息）会被标记，并从仅显示错误的视图中排除；复制和下载的始终是完整原始日志。

完整文档：previewapk.siteport.site/docs（包含 API、CLI、MCP 指南，以及 CI 示例）。 Agent 入门说明：previewapk.siteport.site/agents

许可证

本仓库中的客户端工具采用 MIT 许可证（参见 LICENSE）。PreviewAPK 服务是独立托管的产品。