lxe/phoneuse

项目介绍

phoneuse 让 Linux 桌面看到并操作一部未越狱的 iPhone。手机画面通过 UxPlay 以 AirPlay 接收，显示为桌面窗口；电脑同时作为蓝牙 HID 鼠标和键盘，点击镜像窗口即触屏点按，拖动即滑动，键盘输入直接进入手机。同一镜像还会在 http://localhost:8777 的浏览器页面中提供。

手机端无需越狱、开发者账号、数据线或安装 App，只依赖 iPhone 自带的屏幕镜像和辅助触控（AssistiveTouch）。除了手动操作，每个动作也都是子命令，脚本和 Agent 可以截图、把屏幕读成带坐标的文本，再执行点按、滑动、输入或打开应用。仓库还提供 MCP 服务器和 Claude Code 技能。

安装准备

README 明确说明这是为单一环境快速搭建的技术演示：iPhone 17 Pro、Arch Linux、Hyprland、NVIDIA GPU。依赖包括 BlueZ、Hyprland（窗口几何和光标来自其 IPC）、UxPlay、GStreamer 与 GTK 4 及 gtk4paintablesink、Python 3.11+ 及若干包，截图需要 grim；uv 只在可选的屏幕识别模型时需要。手机与电脑须在同一网络以使用 AirPlay，电脑蓝牙须能连到手机。

1. 克隆仓库并把命令放到 PATH（安装步骤）：

   git clone https://github.com/lxe/phoneuse.git ~/phoneuse
   ln -s ~/phoneuse/bin/phoneuse ~/.local/bin/phoneuse
   

2. 以 sudo 运行 phoneuse install，它会调整 bluetoothd 以输出 HID，并启动 phoneuse-hid 服务。README 提醒这会禁用 bluetoothd 自带的输入和主机名插件，因此该电脑将不再接收自己的蓝牙键鼠。
3. 若启用防火墙，放行 TCP 7000、7001、7100 与 UDP 6000、6001、7011。
4. 在 iPhone 上打开设置 → 辅助功能 → 触控 → 辅助触控，关闭停留控制（Dwell Control）。若要使用调试/遥测工具，将指针调成橙色、大号，并关闭自动隐藏。
5. 在设置 → 蓝牙中配对 PhoneUse；首个配对的设备会通过 /etc/phoneuse/allowed 被信任。
6. 运行 phoneuse up，然后在 iPhone 控制中心 → 屏幕镜像中选择 PhoneUse，桌面出现手机形状的窗口。

使用方式

镜像窗口中获得焦点时，手机指针会跟随光标：单击点按、拖动滑动、滚轮滚动，按住黑色边框可从屏幕边缘开始滑动（从底部边框向上即回主屏）。按 Super 相当于 Cmd。手机连接电脑键盘时会隐藏自带键盘，phoneuse keyboard 或浏览器镜像上的按钮可切换。若从没有该按键的旧版本升级，需在 iPhone 蓝牙设置中忽略 PhoneUse 后重新配对。

对 Agent 和脚本，动作都是子命令，phoneuse --help 可列出。典型流程为 phoneuse open Settings、phoneuse text、phoneuse tap-on "Wi-Fi"、phoneuse screenshot shot.png、phoneuse back（CLI 示例）。使用 MCP 时先运行 scripts/setup-mcp.sh，再用 claude mcp add --scope user phoneuse ~/phoneuse/bin/phoneuse-mcp 注册；每个动作在屏幕稳定后返回截图和带坐标的文本。skill/SKILL.md 是现成的 Claude Code 技能，docs/RECIPES.md 记录哪些手势可用、哪些不可用及原因。

手机锁屏时，phoneuse unlock 会先通过浏览器横幅和桌面通知征求同意，批准后才输入一次密码；密码保存在仅本人可读的 ~/.config/phoneuse/passcode。

配置与限制

可选配置位于 ~/.config/phoneuse/config.toml，包括蓝牙/AirPlay 设备名、用于非测试机型屏幕尺寸的 screen_points、GStreamer 解码器、镜像窗口宽度和 web_port。修改 name 后需重新运行 phoneuse install。浏览器镜像只监听本机。

项目自称是为单一环境快速完成的技术演示，其他环境可能需要修改，功能也可能随时变化或损坏；测试过的 iPhone 与 Linux 组合应视为基线而非其他硬件或合成器的保证。许可证为 MIT。

HotRepo 点评

在 HotRepo 新项目榜 2026-11-07 的 Python 记录中，phoneuse 获得 102 个 Star 和 9 个 Fork，当日新增 102 个 Star，但尚无全语言日榜名次。目前只有一次快照且没有讨论记录，不足以判断热度走势；真正值得关注的是它的思路：把未越狱 iPhone、AirPlay 镜像和蓝牙 HID 组合成一个可脚本化、可被 Agent 调用的远程操作界面。