自动化

用项目内 Python 自动化框架对虚拟 iPhone 做非侵入式 E2E 操作——venv 约定、vphone-auto CLI 与会话编程。

自动化

仓库 automation/ 是宿主侧的 Python 自动化包：经 HostControl Unix socket 对运行中的虚拟 iPhone 做非侵入式 E2E 自动化——截图 + 视觉感知定位 + 触摸/硬件键/文本注入 + 轮询验证闭环。不注入被测 App、不依赖 accessibility 接口，所有定位都基于截图像素空间。文本输入依赖的键盘扩展已跨变体可选（默认安装，仅 less 不含），不再限 DEV 变体。

venv 约定（重要）

一律使用项目 venv，禁止往全局 Python 装依赖。

source .venv/bin/activate

.venv 由 make setup_tools 创建，依赖固定在 requirements.txt。感知能力的可选依赖：OCR 需要 PyObjC（pyobjc-framework-Vision），模板/AKAZE 匹配依赖 opencv-python；缺失时对应通道降级为不可用而不是崩溃。

Python 代码统一写到文件里运行（不要在命令行内联 python），解析二进制结构体、算偏移、进制转换也用 python 计算。

快速上手

链路：Python 端一行 JSON → vm/vphone.sock → 宿主 HostControl → 合成鼠标事件或经 vsock 转发给 vphoned。socket 路径解析顺序：显式参数 → VPHONE_HOST_CONTROL_SOCKET 环境变量 → 默认 vm/vphone.sock。

# 截图与触摸
vphone-auto screenshot-full /tmp/screen.png
vphone-auto tap 645 400
vphone-auto swipe 645 2000 645 800 --ms 300
vphone-auto key home

# 应用与文本
vphone-auto list                          # 应用列表
vphone-auto launch com.apple.Preferences
vphone-auto type "你好世界 🎉"             # Unicode 需键盘扩展（见下）
vphone-auto type "Hello" --field-x 645 --field-y 400

# 感知
vphone-auto perceive --source ocr
vphone-auto perceive --find "Settings"

# 网络观测
vphone-auto status
vphone-auto flows

全局选项：--socket/-s 指定 socket 路径、--json 机器可读输出、--verbose/-v。

感知与定位

识别通道按成本从轻到重级联执行，有结果即融合返回：

通道 机制 默认
Template OpenCV 模板匹配 开
AKAZE 特征点 + Homography 开
OCR macOS Vision（PyObjC），中日韩英 开
YOLO / Grounding DINO / OmniParser 深度学习检测 关（enable_heavy_models 开启）

坐标系统一为屏幕像素空间（默认 1290×2796，左上角原点），调用方无需处理 Retina 分辨率、窗口缩放或 Y 轴翻转——识别结果直接喂给 tap 即可。

会话编程

在 Python 脚本里用 Session 组合感知、执行、验证三步闭环：

from automation.controller.session import Session

session = Session()
session.key("home")
session.verifier.wait_for_stable(frames=3)      # 连续 3 帧相似判稳
if session.find_and_tap(text="Settings"):
    session.verifier.wait_for_text("Wi-Fi", timeout=10)
element = session.find("搜索")
if element:
    session.tap(element.x, element.y)
    session.type_text("Wi-Fi")
session.show_overlay()   # 把识别结果画到 VM 窗口上调试
session.close()

Verifier 用轮询替代固定 time.sleep()：wait_for_text / wait_for_stable / wait_for_app / wait_for_element，超时返回 False 由调用方决定重试。

Unicode 文本输入（键盘扩展）

iOS 虚拟机无物理键盘，Host 端 HID 不支持中文/Emoji。文本输入走自定义键盘扩展：HostControl type → vphoned broker → App Group UDS → 键盘扩展 insertText()。所有非 less 变体默认安装（创建时 --no-keyboard 可关）。

首次使用需在 guest 内手动配置三步：

  1. 设置 → 通用 → 键盘 → 添加新键盘 → VPhoneKeyboard；
  2. VPhoneKeyboard → 打开"允许完全访问"（否则无法连 App Group）；
  3. 输入时长按 globe 键切换到 VPhoneKeyboard。

脚本回放

# 录制（可选锚点录制，回放时用元素文本重新定位，抗坐标漂移）
vphone-auto record start --anchors
vphone-auto record stop

# 执行动作管线
vphone-auto script --file actions.json
vphone-auto script --file actions.json --smart    # 锚点智能回放

# 导出屏幕上下文给 LLM 生成脚本
vphone-auto llm-context --goal "登录 App" --out ctx.json

restore 桥

项目内 Python 仅剩一处仍承担生产职责：DFU restore 桥 scripts/pipeline/pymobiledevice3_bridge.py，它是对第三方库 pymobiledevice3 的封装，由 DFU restore 流程（make restore* / vm create）内部调用。普通自动化不需要直接触碰它；如果你确实要用，保持其 CLI 接口稳定，且只在项目 venv 里跑（pymobiledevice3 由 requirements.txt 固定版本）。其余 CFW/内核补丁能力已全部 Swift 化。

测试

source .venv/bin/activate
python -m pytest automation/tests/          # 单元测试（mock socket）
python -m pytest automation/tests/ --e2e    # e2e，需 VM socket 在线