pymobiledevice3 iPhone 底层自动化

> 优先级：P0（已验证全通，立即可用）
> 适用智能体：Claude Code / Hermes / 任何有 Python 环境的智能体
> 前提：iPhone USB 连接 + 开发者模式（一次性配置）
> 验证设备：iPhone 16 Pro (iPhone18,1), iOS 26.5.1, macOS 26, pymobiledevice3 9.33.1

🆚 与旧方案（QuickTime 投屏）的差异

旧文档（011）仍可用作回退，但推荐优先使用本方案。

一、环境（已就绪，无需重新安装）

# venv 路径
~/.pymobiledevice3-venv/bin/pymobiledevice3

# 或 source 后直接用
source ~/.pymobiledevice3-venv/bin/activate
pymobiledevice3 <子命令>

已安装版本：pymobiledevice3 9.33.1，Python 3.14，安装大小约 ~300MB。

二、iPhone 前置条件（用户侧一次性操作）

2.1 硬件

• iPhone 用 USB 数据线 连接 Mac
• 解锁 iPhone（必须解锁状态）

2.2 开发者模式

iPhone 操作：设置 → 隐私与安全性 → 底部「开发者模式」→ 打开 → 重启 → 输密码解锁 → 弹出确认框点「打开」。

验证：

~/.pymobiledevice3-venv/bin/pymobiledevice3 amfi developer-mode-status
# 返回 true 即已开启

2.3 信任配对

~/.pymobiledevice3-venv/bin/pymobiledevice3 lockdown pair

iPhone 弹出「信任此电脑？」→ 点「信任」。

2.4 挂载开发者镜像（每次重新插拔后需要）

~/.pymobiledevice3-venv/bin/pymobiledevice3 mounter auto-mount

三、核心能力速查

> 关键规则：iOS 17+ 所有 developer 命令必须加 --userspace。

3.1 设备检测

pymobiledevice3 usbmux list

3.2 设备信息

pymobiledevice3 lockdown info

3.3 应用管理

pymobiledevice3 apps list                                              # 列出所有应用
pymobiledevice3 developer core-device launch-application <bundle_id> --userspace ''  # 启动
pymobiledevice3 developer dvt proclist --userspace                     # 运行中进程
pymobiledevice3 developer dvt kill <pid> --userspace                   # 杀死进程
pymobiledevice3 developer dvt pkill WeChat --userspace                 # 按名杀进程

常用 bundle ID：

3.4 截图（像素级原图，~5MB PNG）

pymobiledevice3 developer core-device screen-capture screenshot /path/to/output.png --userspace
# iPhone 16 Pro 分辨率约 1206×2622

3.5 剪贴板读写

pymobiledevice3 developer core-device paste --userspace                # 读取 iPhone 剪贴板
echo "内容" | pymobiledevice3 developer core-device copy --userspace   # Mac → iPhone 剪贴板

3.6 HID 硬件按键

# 支持：home, power, volume-up, volume-down, lock
pymobiledevice3 developer core-device hid button home --userspace
pymobiledevice3 developer core-device hid button power down --userspace  # 仅按下
pymobiledevice3 developer core-device hid button power up --userspace    # 仅抬起

3.7 文件系统（AFC）

pymobiledevice3 afc ls /                  # 根目录
pymobiledevice3 afc ls /DCIM              # 相册照片
pymobiledevice3 afc pull /DCIM/100APPLE/IMG_0001.JPG ~/Desktop/   # 下载文件
pymobiledevice3 afc push ~/Desktop/file.txt /Downloads/           # 上传文件

AFC 路径对应：/DCIM 相机照片、/Downloads Safari 下载、/Books Apple Books。

3.8 位置模拟

pymobiledevice3 developer dvt simulate-location set <lat> <lng> --userspace
pymobiledevice3 developer dvt simulate-location clear --userspace

3.9 SpringBoard

pymobiledevice3 springboard state get                  # 桌面图标布局
pymobiledevice3 springboard icon com.tencent.xin ~/wechat_icon.png  # 提取应用图标

3.10 HID 触控注入（⚠️ 待深入验证）

pymobiledevice3 developer core-device hid raw-button --help
pymobiledevice3 developer core-device universal-hid-service --help

多点触控坐标协议 API 已就绪，具体坐标注入待深入测试。

3.11 WebDriverAgent 高级 UI（⚠️ 需安装 WDA）

pymobiledevice3 developer wda status --userspace        # 检查 WDA 状态
pymobiledevice3 developer wda tap "微信" --userspace    # 点击元素
pymobiledevice3 developer wda swipe 200 500 200 200 --userspace  # 滑动
pymobiledevice3 developer wda type "你好" --userspace   # 输入文本

四、故障排查

五、完整工作流示例

示例1：截图 + 剪贴板循环

#!/bin/bash
source ~/.pymobiledevice3-venv/bin/activate
pymobiledevice3 mounter auto-mount 2>&1 | grep -q "mounted" || { echo "挂载失败"; exit 1; }
pymobiledevice3 developer core-device screen-capture screenshot ~/screenshot_$(date +%H%M%S).png --userspace
echo "--- 剪贴板 ---"
pymobiledevice3 developer core-device paste --userspace
echo "自动化时间: $(date)" | pymobiledevice3 developer core-device copy --userspace

示例2：打开微信 + 截图确认

#!/bin/bash
source ~/.pymobiledevice3-venv/bin/activate
pymobiledevice3 developer core-device launch-application com.tencent.xin --userspace ''
sleep 3
pymobiledevice3 developer core-device screen-capture screenshot ~/wechat_opened.png --userspace

示例3：批量导出应用列表

#!/bin/bash
source ~/.pymobiledevice3-venv/bin/activate
pymobiledevice3 apps list | python3 -c "
import sys, json
apps = json.load(sys.stdin)
for k, v in sorted(apps.items(), key=lambda x: x[1].get('CFBundleDisplayName','').lower()):
    name = v.get('CFBundleDisplayName', '?')
    version = v.get('CFBundleShortVersionString', '?')
    print(f'{name:<20s} {version:<10s} {k}')
" > ~/iphone_apps.txt

六、跨智能体协作

能力栈位置

业务逻辑层（微信操作/加好友/发消息）    ← 其他智能体编写
pymobiledevice3 底层通道              ← 本技能提供
Python venv + USB + 开发者模式        ← 本技能 一/二

其他智能体调用规则

1. 所有 developer 命令前确保已执行 mounter auto-mount
2. iOS 17+ 命令必须带 --userspace
3. iPhone 必须 USB 连接 + 解锁状态
4. 命令路径使用完整路径：~/.pymobiledevice3-venv/bin/pymobiledevice3

何时使用本技能 vs 旧方案

• 需要精确操作（截图/剪贴板/按键/文件）→ 本技能
• 需要高级 UI 操作（tap/swipe/type）→ 优先本技能 WDA（若已安装），否则回退旧方案
• 只需要看画面/不需要精确控制 → 旧方案仍可用

七、验证记录

已验证：设备检测、设备信息、信任配对、开发者模式、镜像挂载、应用列表、启动应用、截图、读剪贴板、写剪贴板、硬件按键、备选截图。

未验证：WDA（需安装 WebDriverAgent）、多点触控坐标协议（待深入测试）。

📂 相关文件

• 旧方案：~/_学习池/011_iPhone投屏自动化操作_规格.md（QuickTime 投屏）
• 详细参考文档：~/Desktop/学习池/012_pymobiledevice3_iPhone底层自动化.md
• 官方仓库：https://github.com/doronz88/pymobiledevice3
• venv 路径：~/.pymobiledevice3-venv/
• 设备配对文件：~/.pymobiledevice3/