Claude Skill

phone-playwright

Use when controlling, inspecting, automating, or building AI agents for Android or iOS mobile devices — using Playwright-style lazy locators, viewport-aware semantic distillation, auto-waiting actionability state machines, warm-cache fast dispatch, scroll_into_view, Chinese clipb

LLM Mart · 0 points · 3 views 0 listing impressions 0 install-command copies
Download dengyie-awesome-skills-phone-playwright-a5d5e22.zip · 180 KB

Install

skills CLI npx skills add https://github.com/dengyie/awesome-skills/tree/main/phone-playwright
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install dengyie-awesome-skills@llmmart
Git git clone https://github.com/dengyie/awesome-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole dengyie/awesome-skills collection as a plugin from our marketplace. Git is the plain clone.

README

Phone-Playwright 📱🎭

Playwright for Mobile:面向大模型与自主 Agent 的移动端语义感知与确定性交互自动化框架。


🌟 核心特性

  1. 视口感知树剪枝与蒸馏 (Viewport-Aware Semantic Pruning)

    • 原生 Android uiautomator / iOS WDA 树体积庞大 (~45,000 字符),经过剪枝后提取为超轻量紧凑语义清单 (~600 字符,Token 压缩率 \(\ge 90\%\))。
    • 彻底剪除所有视口外幽灵节点,杜绝 AI 操作幻觉。
    • 智能语义提升 (Semantic Hoisting):自动将卡片内部文字提升至可点击父容器,保持语义完整。
  2. 双模混合感知 (Dual-Mode Hybrid Perception)

    • 无障碍优先 (80ms 极速响应):常规页面秒级感知,0 额外推理算力开销。
    • 本地 OCR 兜底 (按需激活):遇复杂 Canvas / Flutter / 游戏或稀疏页面自动激活轻量 ONNX OCR,补全纯视觉文字框 @v1, @v2。
  3. Playwright 风格 Auto-waiting 状态机

    • 5 阶段动作就绪检查:Attached -> Visible -> Stable (连续多周期坐标静止) -> Enabled -> Center Dispatch。
    • 彻底杜绝进场动画未完成、页面正在滑动时的空点与漂移。
  4. 双模运行栈 (Sync & Async SDK)

    • 异步核心 (async_api) 支持高并发、单进程多设备调度。
    • 同步封装 (sync_api) 线程桥接,无缝支持快速脚本与交互式调试。
  5. 混合 WebView CDP 穿透 (Hybrid CDP Tunneling)

    • 自动探测 /proc/net/unix 抽象套接字,自适应优先路由当前前台应用。
    • 跨进程查询 window.devicePixelRatio 精确计算 DOM 元素至 Android 物理屏幕坐标。
    • 故障屏障保证端口转发原子注销,杜绝 ADB 守护进程描述符泄漏。
  6. 生物力学手势与多点触控 (Biomechanical Gestures)

    • 三次贝塞尔曲线(Cubic Bézier)离散化模拟人体加速度与制动阻尼。
    • 原生 input draganddrop 连续拖拽,消除离散抬手断流。
    • 多指缩放(Pinch)全视口边缘边界夹紧(Margin \(\ge 10\text{px}\))。
  7. 流式时序 Trace 录制器 (Playwright Tracing)

    • 捕获动作耗时、点击热区、失败事件({verb}_failed)与 DOM/Accessibility 快照。
    • SHA-256 内容寻址资源库,生成标准免解压可读的 trace.zip。
  8. Set-of-Mark (SoM) 视觉锚定与链式选择器

    • 自动计算对比度适配多模态模型视觉标记(Tag ID)。
    • 原生支持链式定位管道(header >> button)与索引过滤(first(), last(), nth())。
  9. 原生 Model Context Protocol (MCP) 支持

    • 提供标准 STDIO JSON-RPC 2.0 服务端。
    • 暴露 phone_list_devices、phone_inspect_screen、phone_interact 工具,供 ZCode、Claude Code、Cursor 等直接接入驱动真实手机。

🚀 快速上手 (Quick Start)

1. 同步 SDK 示例

from phone_playwright import sync_phone_playwright

with sync_phone_playwright() as p:
    # 扫描并连接局域网设备 (如 OnePlus 7T)
    device = p.connect("192.168.1.3:43037")
    page = device.current_page()

    # 获取精炼快照 (极省 Token)
    snapshot = page.snapshot()
    print(snapshot.to_markdown())

    # 语义交互 (内置 Auto-waiting)
    page.locator("@2").fill("降噪耳机")
    page.locator("@1").click()

    # 支持系统手势与快捷语义
    page.get_by_text("搜索").click()
    page.swipe("down")
    page.press_back()

2. 启动 MCP 服务端

在 host 终端直接运行:

phone-playwright-mcp
# 或
python -m phone_playwright.mcp.server

在 AI Agent 的 mcpServers 配置中注册:

{
  "mcpServers": {
    "phone-playwright": {
      "command": "python",
      "args": ["-m", "phone_playwright.mcp.server"],
      "cwd": "/path/to/phone-playwright"
    }
  }
}

📐 架构设计与文档索引

Skill manifest

Phone-Playwright: 移动端 AI 原生无障碍感知与确定性交互框架

Phone-Playwright 是一个专为 AI Agent 与自动化开发者打造的“手机版 Playwright”。它将现代化 Web 自动化的核心范式(惰性定位器 Locator、可用性自动等待 Actionability Auto-Waiting、视口感知语义蒸馏 Semantic Pruning)深度移植至移动端(Android ADB / iOS WDA),彻底解决了移动端 UI 自动化中“元素动态漂移”、“渲染动画抖动丢失点击”、“Token 消耗巨大”与“Wi-Fi ADB 端口动态改变”等生产难题。


1. 核心架构与创新指标

  • 🚀 极速首击优化 (Warm-Cache Fast Dispatch):针对 AI 决策流中 snapshot() -> click() 模式,通过 1.0s TTL 快照温热缓存,跳过冗余 Dump 与稳定度循环,将首击物理动作耗时从 7640ms 降至 141ms(提升 54 倍)!
  • 📉 视口感知语义蒸馏 (O(N) DFS Pruning):物理屏幕视口几何相交裁剪、空无交互容器折叠、后代标签向父卡片提升,将上万字符的冗长 XML 压缩为极简的 @1, @2, ... Markdown 元素表,Token 消耗降低 ≥90%。
  • 🛡️ 严格 5 阶段动作守卫 (Actionability State Machine):Attached -> Visible in Viewport -> Stable [jitter < ε] -> Enabled -> Dispatch,杜绝页面转场过程中的幽灵点击。
  • 🔍 无界视口事后诊断与动态滚动:长列表深层元素超时失败时,通过百万像素无界视口精确识别 OffscreenElementError 与 SelectorNotFoundError;搭配 .scroll_into_view() 自动滑动居中可视。
  • 🌐 双通道混合感知 (Hybrid Perception):以 80ms 零 GPU 开销的无障碍树为主,在极端精简或 Webview 容器下自动无缝接入本地极轻量 ONNX OCR 兜底。
  • 🔌 生产级跨平台 MCP Server:原生支持 Claude / ZCode 的 STDIO JSON-RPC 2.0 协议,采用异步线程池隔离技术彻底免疫 Windows IOCP 管道崩溃。

2. 目录与自包含组件

本 Skill 经过严格工程化解耦,完全自包含(Self-Contained):

phone-playwright/
├── SKILL.md                          # 本文档:架构概述、快速上手与使用规范
├── pyproject.toml                    # 独立依赖与打包构建规范 (仅需 pydantic)
├── src/                              # 核心源码包 (可独立 pip install)
│   └── phone_playwright/
│       ├── api/                      # 异步/同步高层 SDK (PhonePage, PhoneLocator)
│       ├── core/                     # 状态机、语义蒸馏器、选择器解析器
│       ├── drivers/                  # 硬件驱动桥接 (Android ADB, iOS WDA)
│       ├── fleet/                    # 多设备管理、看门狗探针、mDNS 服务发现
│       ├── mcp/                      # 标准 MCP STDIO JSON-RPC 2.0 服务端
│       └── models/                   # 几何数据结构、动作结果与异常模型
├── scripts/                          # 开箱即用便捷脚本
│   ├── cli.py                        # 全功能 CLI 交互式与单步命令工具 (含 REPL/MCP)
│   └── inspect_ui.py                 # 快速 UI 视口元素检查与截图导出工具
├── docs/                             # v2 进阶系统与子系统详细工程规格书
│   ├── README.md                     # 规格书体系导航与开发原则
│   └── specs/                        # 输入子系统/SoM视觉/手势/CDP/断言/Trace 规格
├── references/                       # 生产架构与深度手册
│   ├── architecture.md               # 完整分层架构、状态机模型与优化算法剖析
│   ├── api-reference.md              # Async / Sync Page & Locator API 全量字典
│   └── pitfalls.md                   # 生产实战硬核避坑手册 (Dump延时/端口漂移/中文输入)
└── tests/                            # 自动化单元测试与类型守卫套件 (42 项全绿)

3. 快速上手

方式一:便捷命令行 (CLI & REPL)

无需编写任何脚本,直接使用自带 CLI 即可调试手机:

# 查看当前屏幕的紧凑语义元素表 (设备 ID 缺省时自动探测 adb devices 中的唯一在线设备)
python scripts/cli.py --device 192.168.1.3:43037 snapshot

# 点击元素 (支持 text=, @index, resource-id= 等选择器)
python scripts/cli.py --device 192.168.1.3:43037 click "text=设置"

# 安全输入文本 (中文/Emoji/空格全兼容;剪贴板通道失败时显式报错而非注入乱码)
python scripts/cli.py --device 192.168.1.3:43037 fill "resource-id=search_src_text" "无线局域网"

# 自动滚动长列表直到目标可见
python scripts/cli.py --device 192.168.1.3:43037 scroll "text=关于本机"

# 启动交互式 REPL 控制台
python scripts/cli.py --device 192.168.1.3:43037 repl

方式二:Python 异步代码调用 (Async SDK)

import asyncio
from phone_playwright.api.async_api import AsyncPhonePlaywright

async def main():
    async with AsyncPhonePlaywright() as pw:
        # 1. 连接设备 (支持无线 ADB IP:端口,或 USB 设备序列号)
        page = await pw.connect("192.168.1.3:43037")

        # 2. 获取紧凑快照 (同时温热 1.0s 执行缓存)
        snapshot = await page.snapshot()
        print(f"当前 Activity: {snapshot.activity_name}")
        print(snapshot.summary_markdown)

        # 3. 极速响应点击 (利用快照缓存,~140ms 极速下发)
        await page.locator("text=无线网络").click()

        # 4. 深层长列表滚动与链式交互
        await page.get_by_text("高级设置").scroll_into_view().click()

        # 5. 安全中文输入
        await page.locator("role=Input").fill("办公专用WiFi")

asyncio.run(main())

方式三:Python 同步脚本 (Sync SDK)

from phone_playwright.api.sync_api import SyncPhonePlaywright

with SyncPhonePlaywright() as pw:
    page = pw.connect("192.168.1.3:43037")
    page.locator("text=蓝牙").click()
    page.press_back()

方式四:启动 MCP STDIO 服务供 Agent 驱动

在 AI 客户端配置中加入该 MCP 服务器:

{
  "mcpServers": {
    "phone-playwright": {
      "command": "python",
      "args": ["<path-to-skill>/scripts/cli.py", "--device", "192.168.1.3:43037", "mcp"]
    }
  }
}

4. 选择器语法速查表

选择器类型 示例语法 匹配行为
紧凑数字引用 @1, @5, @12 匹配最新快照列表中指定索引号的元素
文本内容 text=设置, text=确定 模糊匹配节点的 text 或 content-desc 属性
控件标识符 resource-id=com.android.settings:id/search 匹配 Android resource-id
语义角色 role=Button, role=Input 匹配标准 UI 角色类型
复合过滤 role=Button[name='取消'] 组合角色与显示文本属性进行精确过滤

5. 深入阅读

Files (awesome-skills)
  • docs
    • specs
      • 01-architecture-v2.md 7.9 KB
        Loading…
      • 02-input-subsystem.md 8.3 KB
        Loading…
      • 03-vision-som-multimodal.md 5.4 KB
        Loading…
      • 04-gesture-engine.md 4.1 KB
        Loading…
      • 05-cdp-hybrid-traversal.md 5.6 KB
        Loading…
      • 06-expect-assertions-and-trace.md 5.7 KB
        Loading…
    • ALGORITHMS.md 8.3 KB
      Loading…
    • API_SPEC.md 4.3 KB
      Loading…
    • ARCHITECTURE_SKELETON.md 23.2 KB
      Loading…
    • DESIGN.md 8.6 KB
      Loading…
    • DEVELOPER_GUIDE.md 35 KB
      Loading…
    • FLEET_AND_DRIVERS.md 4.4 KB
      Loading…
    • HYBRID_VISION_AND_EFFICIENCY.md 4.6 KB
      Loading…
    • README.md 2.6 KB
      Loading…
  • references
    • api-reference.md 7.1 KB
      Loading…
    • architecture.md 6.3 KB
      Loading…
    • pitfalls.md 10 KB
      Loading…
  • scripts
    • cli.py 8.3 KB
      Loading…
    • inspect_ui.py 2 KB
      Loading…
    • live_regression.py 4.7 KB
      Loading…
  • src
    • phone_playwright
      • api
        • async_api.py 16.9 KB
          Loading…
        • sync_api.py 13.6 KB
          Loading…
      • core
        • assertions.py 8.1 KB
          Loading…
        • cdp.py 15.7 KB
          Loading…
        • gesture.py 7.5 KB
          Loading…
        • locator.py 10 KB
          Loading…
        • pruner.py 5.4 KB
          Loading…
        • selector.py 7.6 KB
          Loading…
        • som.py 6.5 KB
          Loading…
        • state_machine.py 15 KB
          Loading…
        • vision.py 3.2 KB
          Loading…
        • __init__.py 1.2 KB
          Loading…
      • drivers
        • android_adb.py 23.2 KB
          Loading…
        • base.py 2.1 KB
          Loading…
        • ios_wda.py 5.9 KB
          Loading…
        • __init__.py 408 B
          Loading…
      • fleet
        • manager.py 5.5 KB
          Loading…
        • mdns.py 2.5 KB
          Loading…
        • watchdog.py 5.4 KB
          Loading…
        • __init__.py 312 B
          Loading…
      • mcp
        • server.py 5.4 KB
          Loading…
        • tools.py 9.1 KB
          Loading…
        • __init__.py 231 B
          Loading…
      • models
        • actions.py 1.6 KB
          Loading…
        • exceptions.py 2.3 KB
          Loading…
        • geometry.py 2.1 KB
          Loading…
        • schema.py 5.1 KB
          Loading…
        • trace.py 1.7 KB
          Loading…
        • __init__.py 898 B
          Loading…
      • tracing
        • recorder.py 6.2 KB
          Loading…
        • __init__.py 160 B
          Loading…
      • __init__.py 1.6 KB
        Loading…
  • tests
    • test_android_driver.py 10.4 KB
      Loading…
    • test_cdp.py 7.3 KB
      Loading…
    • test_expect_and_trace.py 7.3 KB
      Loading…
    • test_fleet_and_watchdog.py 6.7 KB
      Loading…
    • test_geometry.py 898 B
      Loading…
    • test_locator_features.py 5.7 KB
      Loading…
    • test_mcp_server.py 9.1 KB
      Loading…
    • test_phone_playwright_package.py 2.2 KB
      Loading…
    • test_pruner.py 2.5 KB
      Loading…
    • test_robustness.py 3.3 KB
      Loading…
    • test_selector.py 3.5 KB
      Loading…
    • test_som_and_gesture.py 5.4 KB
      Loading…
    • test_state_machine.py 14.1 KB
      Loading…
    • test_sync_api.py 5.8 KB
      Loading…
  • .gitignore 102 B · in bundle
  • pyproject.toml 1.1 KB
    Loading…
  • README.md 4.3 KB
    # Phone-Playwright 📱🎭
    
    > **Playwright for Mobile**:面向大模型与自主 Agent 的移动端语义感知与确定性交互自动化框架。
    
    ---
    
    ## 🌟 核心特性
    
    1. **视口感知树剪枝与蒸馏 (Viewport-Aware Semantic Pruning)**
       - 原生 Android uiautomator / iOS WDA 树体积庞大 (~45,000 字符),经过剪枝后提取为超轻量紧凑语义清单 (~600 字符,**Token 压缩率 $\ge 90\%$**)。
       - 彻底剪除所有视口外幽灵节点,杜绝 AI 操作幻觉。
       - 智能语义提升 (Semantic Hoisting):自动将卡片内部文字提升至可点击父容器,保持语义完整。
    
    2. **双模混合感知 (Dual-Mode Hybrid Perception)**
       - **无障碍优先 (80ms 极速响应)**:常规页面秒级感知,0 额外推理算力开销。
       - **本地 OCR 兜底 (按需激活)**:遇复杂 Canvas / Flutter / 游戏或稀疏页面自动激活轻量 ONNX OCR,补全纯视觉文字框 `@v1, @v2`。
    
    3. **Playwright 风格 Auto-waiting 状态机**
       - 5 阶段动作就绪检查:`Attached -> Visible -> Stable (连续多周期坐标静止) -> Enabled -> Center Dispatch`。
       - 彻底杜绝进场动画未完成、页面正在滑动时的空点与漂移。
    
    4. **双模运行栈 (Sync & Async SDK)**
       - 异步核心 (`async_api`) 支持高并发、单进程多设备调度。
       - 同步封装 (`sync_api`) 线程桥接,无缝支持快速脚本与交互式调试。
    
    5. **混合 WebView CDP 穿透 (Hybrid CDP Tunneling)**
       - 自动探测 `/proc/net/unix` 抽象套接字,自适应优先路由当前前台应用。
       - 跨进程查询 `window.devicePixelRatio` 精确计算 DOM 元素至 Android 物理屏幕坐标。
       - 故障屏障保证端口转发原子注销,杜绝 ADB 守护进程描述符泄漏。
    
    6. **生物力学手势与多点触控 (Biomechanical Gestures)**
       - 三次贝塞尔曲线(Cubic Bézier)离散化模拟人体加速度与制动阻尼。
       - 原生 `input draganddrop` 连续拖拽,消除离散抬手断流。
       - 多指缩放(Pinch)全视口边缘边界夹紧(Margin $\ge 10\text{px}$)。
    
    7. **流式时序 Trace 录制器 (Playwright Tracing)**
       - 捕获动作耗时、点击热区、失败事件(`{verb}_failed`)与 DOM/Accessibility 快照。
       - SHA-256 内容寻址资源库,生成标准免解压可读的 `trace.zip`。
    
    8. **Set-of-Mark (SoM) 视觉锚定与链式选择器**
       - 自动计算对比度适配多模态模型视觉标记(Tag ID)。
       - 原生支持链式定位管道(`header >> button`)与索引过滤(`first()`, `last()`, `nth()`)。
    
    9. **原生 Model Context Protocol (MCP) 支持**
       - 提供标准 STDIO JSON-RPC 2.0 服务端。
       - 暴露 `phone_list_devices`、`phone_inspect_screen`、`phone_interact` 工具,供 ZCode、Claude Code、Cursor 等直接接入驱动真实手机。
    
    ---
    
    ## 🚀 快速上手 (Quick Start)
    
    ### 1. 同步 SDK 示例
    
    ```python
    from phone_playwright import sync_phone_playwright
    
    with sync_phone_playwright() as p:
        # 扫描并连接局域网设备 (如 OnePlus 7T)
        device = p.connect("192.168.1.3:43037")
        page = device.current_page()
    
        # 获取精炼快照 (极省 Token)
        snapshot = page.snapshot()
        print(snapshot.to_markdown())
    
        # 语义交互 (内置 Auto-waiting)
        page.locator("@2").fill("降噪耳机")
        page.locator("@1").click()
    
        # 支持系统手势与快捷语义
        page.get_by_text("搜索").click()
        page.swipe("down")
        page.press_back()
    ```
    
    ### 2. 启动 MCP 服务端
    
    在 host 终端直接运行:
    
    ```bash
    phone-playwright-mcp
    # 或
    python -m phone_playwright.mcp.server
    ```
    
    在 AI Agent 的 `mcpServers` 配置中注册:
    
    ```json
    {
      "mcpServers": {
        "phone-playwright": {
          "command": "python",
          "args": ["-m", "phone_playwright.mcp.server"],
          "cwd": "/path/to/phone-playwright"
        }
      }
    }
    ```
    
    ---
    
    ## 📐 架构设计与文档索引
    
    * [架构、代码与数据层骨架规范 (ARCHITECTURE_SKELETON.md)](docs/ARCHITECTURE_SKELETON.md)
    * [API 契约与 MCP 协议规范 (API_SPEC.md)](docs/API_SPEC.md)
    * [剪枝与状态机算法实现 (ALGORITHMS.md)](docs/ALGORITHMS.md)
    * [集群自愈与跨平台驱动设计 (FLEET_AND_DRIVERS.md)](docs/FLEET_AND_DRIVERS.md)
    * [混合视觉兜底与效能基准分析 (HYBRID_VISION_AND_EFFICIENCY.md)](docs/HYBRID_VISION_AND_EFFICIENCY.md)
    
  • SKILL.md 7.7 KB
    ---
    name: phone-playwright
    description: Use when controlling, inspecting, automating, or building AI agents for Android or iOS mobile devices — using Playwright-style lazy locators, viewport-aware semantic distillation, auto-waiting actionability state machines, warm-cache fast dispatch, scroll_into_view, Chinese clipboard typing, or MCP stdio JSON-RPC mobile servers. Triggers: 手机自动化, phone playwright, 手机UI自动化, adb 控制, 手机点击, 手机无障碍, 手机 agent, mobile playwright, 手机端自动化, 移动端自动化.
    ---
    
    # Phone-Playwright: 移动端 AI 原生无障碍感知与确定性交互框架
    
    Phone-Playwright 是一个专为 AI Agent 与自动化开发者打造的“手机版 Playwright”。它将现代化 Web 自动化的核心范式(**惰性定位器 Locator**、**可用性自动等待 Actionability Auto-Waiting**、**视口感知语义蒸馏 Semantic Pruning**)深度移植至移动端(Android ADB / iOS WDA),彻底解决了移动端 UI 自动化中“元素动态漂移”、“渲染动画抖动丢失点击”、“Token 消耗巨大”与“Wi-Fi ADB 端口动态改变”等生产难题。
    
    ---
    
    ## 1. 核心架构与创新指标
    
    - 🚀 **极速首击优化 (Warm-Cache Fast Dispatch)**:针对 AI 决策流中 `snapshot() -> click()` 模式,通过 1.0s TTL 快照温热缓存,跳过冗余 Dump 与稳定度循环,**将首击物理动作耗时从 7640ms 降至 141ms(提升 54 倍)**!
    - 📉 **视口感知语义蒸馏 (O(N) DFS Pruning)**:物理屏幕视口几何相交裁剪、空无交互容器折叠、后代标签向父卡片提升,将上万字符的冗长 XML 压缩为极简的 `@1, @2, ...` Markdown 元素表,**Token 消耗降低 ≥90%**。
    - 🛡️ **严格 5 阶段动作守卫 (Actionability State Machine)**:`Attached -> Visible in Viewport -> Stable [jitter < ε] -> Enabled -> Dispatch`,杜绝页面转场过程中的幽灵点击。
    - 🔍 **无界视口事后诊断与动态滚动**:长列表深层元素超时失败时,通过百万像素无界视口精确识别 `OffscreenElementError` 与 `SelectorNotFoundError`;搭配 `.scroll_into_view()` 自动滑动居中可视。
    - 🌐 **双通道混合感知 (Hybrid Perception)**:以 80ms 零 GPU 开销的无障碍树为主,在极端精简或 Webview 容器下自动无缝接入本地极轻量 ONNX OCR 兜底。
    - 🔌 **生产级跨平台 MCP Server**:原生支持 Claude / ZCode 的 STDIO JSON-RPC 2.0 协议,采用异步线程池隔离技术彻底免疫 Windows IOCP 管道崩溃。
    
    ---
    
    ## 2. 目录与自包含组件
    
    本 Skill 经过严格工程化解耦,完全**自包含(Self-Contained)**:
    
    ```text
    phone-playwright/
    ├── SKILL.md                          # 本文档:架构概述、快速上手与使用规范
    ├── pyproject.toml                    # 独立依赖与打包构建规范 (仅需 pydantic)
    ├── src/                              # 核心源码包 (可独立 pip install)
    │   └── phone_playwright/
    │       ├── api/                      # 异步/同步高层 SDK (PhonePage, PhoneLocator)
    │       ├── core/                     # 状态机、语义蒸馏器、选择器解析器
    │       ├── drivers/                  # 硬件驱动桥接 (Android ADB, iOS WDA)
    │       ├── fleet/                    # 多设备管理、看门狗探针、mDNS 服务发现
    │       ├── mcp/                      # 标准 MCP STDIO JSON-RPC 2.0 服务端
    │       └── models/                   # 几何数据结构、动作结果与异常模型
    ├── scripts/                          # 开箱即用便捷脚本
    │   ├── cli.py                        # 全功能 CLI 交互式与单步命令工具 (含 REPL/MCP)
    │   └── inspect_ui.py                 # 快速 UI 视口元素检查与截图导出工具
    ├── docs/                             # v2 进阶系统与子系统详细工程规格书
    │   ├── README.md                     # 规格书体系导航与开发原则
    │   └── specs/                        # 输入子系统/SoM视觉/手势/CDP/断言/Trace 规格
    ├── references/                       # 生产架构与深度手册
    │   ├── architecture.md               # 完整分层架构、状态机模型与优化算法剖析
    │   ├── api-reference.md              # Async / Sync Page & Locator API 全量字典
    │   └── pitfalls.md                   # 生产实战硬核避坑手册 (Dump延时/端口漂移/中文输入)
    └── tests/                            # 自动化单元测试与类型守卫套件 (42 项全绿)
    ```
    
    ---
    
    ## 3. 快速上手
    
    ### 方式一:便捷命令行 (CLI & REPL)
    
    无需编写任何脚本,直接使用自带 CLI 即可调试手机:
    
    ```bash
    # 查看当前屏幕的紧凑语义元素表 (设备 ID 缺省时自动探测 adb devices 中的唯一在线设备)
    python scripts/cli.py --device 192.168.1.3:43037 snapshot
    
    # 点击元素 (支持 text=, @index, resource-id= 等选择器)
    python scripts/cli.py --device 192.168.1.3:43037 click "text=设置"
    
    # 安全输入文本 (中文/Emoji/空格全兼容;剪贴板通道失败时显式报错而非注入乱码)
    python scripts/cli.py --device 192.168.1.3:43037 fill "resource-id=search_src_text" "无线局域网"
    
    # 自动滚动长列表直到目标可见
    python scripts/cli.py --device 192.168.1.3:43037 scroll "text=关于本机"
    
    # 启动交互式 REPL 控制台
    python scripts/cli.py --device 192.168.1.3:43037 repl
    ```
    
    ### 方式二:Python 异步代码调用 (Async SDK)
    
    ```python
    import asyncio
    from phone_playwright.api.async_api import AsyncPhonePlaywright
    
    async def main():
        async with AsyncPhonePlaywright() as pw:
            # 1. 连接设备 (支持无线 ADB IP:端口,或 USB 设备序列号)
            page = await pw.connect("192.168.1.3:43037")
    
            # 2. 获取紧凑快照 (同时温热 1.0s 执行缓存)
            snapshot = await page.snapshot()
            print(f"当前 Activity: {snapshot.activity_name}")
            print(snapshot.summary_markdown)
    
            # 3. 极速响应点击 (利用快照缓存,~140ms 极速下发)
            await page.locator("text=无线网络").click()
    
            # 4. 深层长列表滚动与链式交互
            await page.get_by_text("高级设置").scroll_into_view().click()
    
            # 5. 安全中文输入
            await page.locator("role=Input").fill("办公专用WiFi")
    
    asyncio.run(main())
    ```
    
    ### 方式三:Python 同步脚本 (Sync SDK)
    
    ```python
    from phone_playwright.api.sync_api import SyncPhonePlaywright
    
    with SyncPhonePlaywright() as pw:
        page = pw.connect("192.168.1.3:43037")
        page.locator("text=蓝牙").click()
        page.press_back()
    ```
    
    ### 方式四:启动 MCP STDIO 服务供 Agent 驱动
    
    在 AI 客户端配置中加入该 MCP 服务器:
    
    ```json
    {
      "mcpServers": {
        "phone-playwright": {
          "command": "python",
          "args": ["<path-to-skill>/scripts/cli.py", "--device", "192.168.1.3:43037", "mcp"]
        }
      }
    }
    ```
    
    ---
    
    ## 4. 选择器语法速查表
    
    | 选择器类型 | 示例语法 | 匹配行为 |
    |---|---|---|
    | **紧凑数字引用** | `@1`, `@5`, `@12` | 匹配最新快照列表中指定索引号的元素 |
    | **文本内容** | `text=设置`, `text=确定` | 模糊匹配节点的 `text` 或 `content-desc` 属性 |
    | **控件标识符** | `resource-id=com.android.settings:id/search` | 匹配 Android `resource-id` |
    | **语义角色** | `role=Button`, `role=Input` | 匹配标准 UI 角色类型 |
    | **复合过滤** | `role=Button[name='取消']` | 组合角色与显示文本属性进行精确过滤 |
    
    ---
    
    ## 5. 深入阅读
    
    - 架构设计与理论推导:[`references/architecture.md`](references/architecture.md)
    - 完整 API 接口字典:[`references/api-reference.md`](references/api-reference.md)
    - 真实设备踩坑指南:[`references/pitfalls.md`](references/pitfalls.md)
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.