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
Install
npx skills add https://github.com/dengyie/awesome-skills/tree/main/phone-playwright
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install dengyie-awesome-skills@llmmart
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 的移动端语义感知与确定性交互自动化框架。
🌟 核心特性
视口感知树剪枝与蒸馏 (Viewport-Aware Semantic Pruning)
- 原生 Android uiautomator / iOS WDA 树体积庞大 (~45,000 字符),经过剪枝后提取为超轻量紧凑语义清单 (~600 字符,Token 压缩率 \(\ge 90\%\))。
- 彻底剪除所有视口外幽灵节点,杜绝 AI 操作幻觉。
- 智能语义提升 (Semantic Hoisting):自动将卡片内部文字提升至可点击父容器,保持语义完整。
双模混合感知 (Dual-Mode Hybrid Perception)
- 无障碍优先 (80ms 极速响应):常规页面秒级感知,0 额外推理算力开销。
- 本地 OCR 兜底 (按需激活):遇复杂 Canvas / Flutter / 游戏或稀疏页面自动激活轻量 ONNX OCR,补全纯视觉文字框
@v1, @v2。
Playwright 风格 Auto-waiting 状态机
- 5 阶段动作就绪检查:
Attached -> Visible -> Stable (连续多周期坐标静止) -> Enabled -> Center Dispatch。 - 彻底杜绝进场动画未完成、页面正在滑动时的空点与漂移。
- 5 阶段动作就绪检查:
双模运行栈 (Sync & Async SDK)
- 异步核心 (
async_api) 支持高并发、单进程多设备调度。 - 同步封装 (
sync_api) 线程桥接,无缝支持快速脚本与交互式调试。
- 异步核心 (
混合 WebView CDP 穿透 (Hybrid CDP Tunneling)
- 自动探测
/proc/net/unix抽象套接字,自适应优先路由当前前台应用。 - 跨进程查询
window.devicePixelRatio精确计算 DOM 元素至 Android 物理屏幕坐标。 - 故障屏障保证端口转发原子注销,杜绝 ADB 守护进程描述符泄漏。
- 自动探测
生物力学手势与多点触控 (Biomechanical Gestures)
- 三次贝塞尔曲线(Cubic Bézier)离散化模拟人体加速度与制动阻尼。
- 原生
input draganddrop连续拖拽,消除离散抬手断流。 - 多指缩放(Pinch)全视口边缘边界夹紧(Margin \(\ge 10\text{px}\))。
流式时序 Trace 录制器 (Playwright Tracing)
- 捕获动作耗时、点击热区、失败事件(
{verb}_failed)与 DOM/Accessibility 快照。 - SHA-256 内容寻址资源库,生成标准免解压可读的
trace.zip。
- 捕获动作耗时、点击热区、失败事件(
Set-of-Mark (SoM) 视觉锚定与链式选择器
- 自动计算对比度适配多模态模型视觉标记(Tag ID)。
- 原生支持链式定位管道(
header >> button)与索引过滤(first(),last(),nth())。
原生 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. 深入阅读
- 架构设计与理论推导:
references/architecture.md - 完整 API 接口字典:
references/api-reference.md - 真实设备踩坑指南:
references/pitfalls.md
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.
Reviews (0)
No reviews yet.
No comments yet.