kilolonion/agent-vscreen
AI 工程给 Android AI Agent 一块隐形副屏,让它在后台操作 App,你继续用自己的屏幕。
项目介绍
Agent-VScreen 给 Android 上的 AI Agent 提供一块不可见的虚拟屏幕。Agent 在这块屏上启动应用、点击、滑动、输入和按按键,你的手机主屏仍归自己使用。每个动作都会返回当前屏幕、可见文字、可点击元素和截图,Agent 因此能逐步核对结果 README。
App 自身不调用任何模型,屏幕内容由调用方的模型理解。它同时提供 vscreen CLI、MCP 和普通 HTTP 三种接口,终端型 Agent、MCP 客户端或自己写的代码都能接入。一个小浮动窗实时显示后台屏,你可以随时接管或停止 AI。
在虚拟屏之外,它还做了时间感知(约每秒读一次文字并标注时间戳)、until 等待条件、按应用拦截或只读的规则、支付确认、多 Agent 会话轮换,以及“做一遍就录成步骤”的教学功能。项目面向手机端 Agent,不是桌面自动化。
快速使用
前提:arm64 的 Android 11+ 设备(建议 14+)、正在运行的 Shizuku,以及从 Releases 下载的 APK。
- 安装 APK 并打开 Agent-VScreen。
- 确认 Shizuku 在运行,点击 Grant Shizuku。
- 点击 One-tap setup,授予悬浮窗、通知、只读无障碍、电池优化和后台运行权限。荣耀、华为、小米、OPPO、vivo 等机型还要在系统后台管理中允许自启动和后台活动。
- 在 Connect agent 中点击 Copy message for agent,把内容原样发给你的 Agent。它会安装
vscreen命令,并把一份使用说明存进长期记忆。
随后可以试:
vscreen launch Settings
vscreen act "tap Search; type About phone; key enter until text:About phone"
vscreen help all
以 Operit 这类 MCP 客户端为例,默认地址是 http://127.0.0.1:18765/mcp,连接类型 httpStream,Bearer Token 从 App 的 MCP 页面复制;客户端与 App 必须在同一台手机上 MCP 接入说明。完整的 CLI、MCP 和 HTTP 参考见 API.md。
使用约束
- 服务默认只监听
127.0.0.1:18765。跨设备访问需要选择 Tailscale(内置节点或 Tailscale App)或 SSH 端口转发,App 不提供公网链接。 - MCP Token 等同于手机控制权,不要粘贴进公开配置、角色卡或截图。
- App 界面目前以中文为主,首页可切换中文/英文;本文按钮名为翻译后的名称。
- 权限只依赖 Shizuku,不需要 root,也不占用 adb 或无线调试。
- 后台屏里的应用会被静音。部分厂商的后台管理可能拦截冻结应用的精确闹钟和唤醒广播;静音对个别播放器和 MagicOS 的效果未经验证。
- 权限分「hands-off」(只对花钱步骤确认)和「careful」(删除等不可逆操作也确认)两级,并支持按应用规则和按 Agent 发放 Token。
- 采用 MIT 许可证;内置 PaddleOCR 模型保持其 Apache-2.0 许可。
从源码构建
需要 JDK 17 和 Android SDK(compileSdk 36):
echo "sdk.dir=/path/to/android-sdk" > local.properties
./gradlew :app:assembleRelease
内置 Tailscale 是一个可选的 Go 程序,先运行 tsbridge/build.sh 生成 libtsbridge.so;不做这一步 APK 仍可构建,只是没有内置 Tailscale。
HotRepo 点评
本站暂无该仓库的日榜名次或 Star 历史记录,因此没有站内热度趋势可讲。技术上值得关注的是它的结构:虚拟屏通过 CLI、MCP 和 HTTP 三种方式对外暴露,感知层把无障碍树与端侧 OCR 合并成可编号的元素,每一步都返回带状态的结构化结果,因此它更像 Android 手机 Agent 的通用底座,而不是某个 Agent 的专属插件——Operit 的教程也被明确标注为只是示例。更新记录里还给出了 Honor Magic 7 真机回归任务集,让稳定性说法有了具体的测试依据。代价主要在中文界面,以及对 Shizuku 和厂商后台策略的依赖,这两点更多影响首次配置而不是 API 本身。
本文由 AI 根据项目 README 生成,更新于 ,以项目官方文档为准。
相关推荐
- AcidGr/agent-mobile-use在 Android 后台虚拟副屏中运行应用,让 Agent 在不打扰物理主屏的情况下操控手机。
- guzhou079-arch/deepseek-harness-android把 DeepSeek Harness 打包成安卓 APK,免 Termux、免 root,内置读屏、虚拟屏、定时任务和 27 款技能。
- KnifeLemon/Droidline用 Python、Node.js、C#、命令行、HTTP 或 Appium 驱动真实 Android 手机做自动化和测试,无需 ADB、USB 或 root。
- ybblab/Droidance一款开源安卓 AI 智能体,在后台虚拟屏里看屏幕、点应用,替你完成手机上的日常操作。
- kuafuai/andee一个住进 Android 手机或 Mac 的本地智能体,借助无障碍服务像用户一样操作任意 App,无需集成或 Root。