jev-phone 0.1.1__tar.gz

jev_phone-0.1.1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Dongxin and Jev Phone contributors
+Copyright (c) 2026 Dongxin and ai-phone contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jev_phone-0.1.1/NOTICE.md

@@ -0,0 +1,7 @@
+# Attribution
+
+Jev Phone derives selected device-channel and image-comparison implementations from [dongxinsuperman/ai-phone](https://github.com/dongxinsuperman/ai-phone), under the MIT License. Original copyright attribution is retained in LICENSE.
+
+The project uses UiAutomator2, hmdriver2, HTTPX and Pillow as installed dependencies; they are not vendored here and retain their respective licenses. iOS connects to user-provided WebDriverAgent; WDA source is not bundled.
+
+Demo screenshots and the cropped GIF are supplied project demonstration assets. Their source and experimental context are described in docs/素材说明.md. Jev Phone does not claim affiliation with OpenAI or other platform vendors.

jev_phone-0.1.1/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: jev-phone
+Version: 0.1.1
+Summary: Independent multimodal tap SDK for Android, iOS and HarmonyOS
+Author: Dongxin
+License: MIT License
+        
+        Copyright (c) 2026 Dongxin and Jev Phone contributors
+        Copyright (c) 2026 Dongxin and ai-phone contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Repository, https://github.com/dongxinsuperman/jev-phone
+Project-URL: Issues, https://github.com/dongxinsuperman/jev-phone/issues
+Keywords: mobile,multimodal,android,ios,harmonyos,automation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE.md
+Requires-Dist: httpx>=0.28
+Requires-Dist: Pillow>=10.1
+Provides-Extra: android
+Requires-Dist: uiautomator2==3.7.0; extra == "android"
+Provides-Extra: harmony
+Requires-Dist: hmdriver2==1.4.4; extra == "harmony"
+Provides-Extra: demo
+Requires-Dist: uiautomator2==3.7.0; extra == "demo"
+Requires-Dist: fastapi>=0.115; extra == "demo"
+Requires-Dist: uvicorn>=0.30; extra == "demo"
+Dynamic: license-file
+
+<h1 align="center">Jev Phone</h1>
+<p align="center"><strong>毫秒级本地处理的三端多模态点击 SDK</strong></p>
+<p align="center">Android · iOS · HarmonyOS</p>
+<p align="center"><strong>经济、快速、准确</strong></p>
+<p align="center"><a href="https://github.com/dongxinsuperman/jev-phone/blob/main/README.md">中文</a> · <a href="https://github.com/dongxinsuperman/jev-phone/blob/main/README.en.md">English</a></p>
+
+Jev Phone 将 Jev 多模态决策接到三端设备上，为已有 Agent、测试平台和脚本提供可独立调用的手机点击能力。**调用方给出点击目标，SDK 完成当前画面的定位和执行。**
+
+它承接从“知道要操作什么”到“实际点到设备上”的这一段。你可以继续使用自己的任务规划、缓存和业务判断，不需要引入完整 AI Phone 框架。
+
+![多模态决策驱动的三端视觉交互通道](https://raw.githubusercontent.com/dongxinsuperman/jev-phone/main/docs/media/readme/overview.zh.png)
+
+## 实机演示：预览难度并保存
+
+安卓真机连续执行四步：基础 → 中等 → 困难 → 保存修改。起始画面已打开难度弹窗，最终保存为困难。秒表按真实时间连续计时，视频未加速。
+
+![实机演示：预览难度并保存](https://raw.githubusercontent.com/dongxinsuperman/jev-phone/main/docs/media/demo-default-difficulty-fast.gif)
+
+<table align="center">
+<thead><tr><th align="center">步骤</th><th align="center">模型往返</th><th align="center">SDK本地处理</th><th align="center">页面稳定等待</th><th align="center">整步合计</th></tr></thead>
+<tbody>
+<tr><td align="center">基础</td><td align="center">763.28 ms</td><td align="center">490.99 ms</td><td align="center">658.00 ms</td><td align="center">1,912.27 ms</td></tr>
+<tr><td align="center">中等</td><td align="center">646.39 ms</td><td align="center">289.80 ms</td><td align="center">665.00 ms</td><td align="center">1,601.19 ms</td></tr>
+<tr><td align="center">困难</td><td align="center">647.78 ms</td><td align="center">296.26 ms</td><td align="center">702.00 ms</td><td align="center">1,646.04 ms</td></tr>
+<tr><td align="center">保存修改</td><td align="center">706.62 ms</td><td align="center">301.97 ms</td><td align="center">0.00 ms</td><td align="center">1,008.59 ms</td></tr>
+</tbody>
+</table>
+
+整步合计包含点击后的页面稳定等待，通过连续截图对比判断画面是否稳定；末步没有后续步骤，因此不追加等待。第一步低于2秒，其余三步均低于1.7秒；整轮实际耗时 **6,170.82ms**。本地 SDK 已实现毫秒级处理；模型往返耗时则受你的网络状况与模型服务响应影响，是整步耗时波动的主要来源。
+
+[MP4](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/media/demo-default-difficulty-fast.mp4) · [JSON](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/media/demo-default-difficulty-fast.json)
+
+## 性能
+
+已有安卓实验中，本地候选处理、画框与编码耗时 **15–50ms**；非模型整轮中位为 **620ms**，同一导航样本9轮范围为 **493–729ms**。这些数据不包含模型请求、初始化与页面稳定。
+
+每一步整体耗时还包括设备采集、候选处理、模型往返、点击和该步后续衔接。[完整分段记录](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E6%BC%94%E7%A4%BA%E8%80%97%E6%97%B6%E6%98%8E%E7%BB%86.md)分别列出这些时间。
+
+![毫秒级通道处理与分段计时](https://raw.githubusercontent.com/dongxinsuperman/jev-phone/main/docs/media/readme/timing.zh.png)
+
+## 工作原理：Jev 选择，组件执行
+
+当前接入的多模态 Jev 采用 **有限选项决策接口**：它结合图像选择给定候选，这种接入方式并不直接返回设备操作指令或可执行的点击坐标。因此，从模型选中目标到设备实际点击，还需要组件完成定位与动作绑定。
+
+我们先从系统树中提取可操作元素的边界，用四角在截图上勾勒出矩形，并为每个区域标记编号。Jev 接收当前目标和带编号的图像，只需选出对应编号；组件再根据编号找回元素边界，计算中心坐标，交给平台驱动执行点击。代码保存左上角与右下角坐标，由此确定矩形四角。 实际编号图还以中心红点和引线标明点击位置，编号会避让，重叠展示框会围绕原中心缩小；这些绘图处理不会改变候选的原始边界和点击坐标。
+
+![从点击目标到编号选择，再到设备坐标点击](https://raw.githubusercontent.com/dongxinsuperman/jev-phone/main/docs/media/readme/target-to-tap.zh.svg)
+
+## 为什么结合系统树与截图
+
+矩形的位置来自系统树，目标的文字、图标和外观语义来自截图。例如，节点文字为空，但画面中显示的是头像：Jev 可以依据图像识别头像并选择它的编号，组件则用同一编号找回已知边界。这样，多模态选项决策就能对应到真实可操作元素，而不需要模型自己生成坐标。
+
+![几何约束与视觉语义融合](https://raw.githubusercontent.com/dongxinsuperman/jev-phone/main/docs/media/readme/geometry.zh.png)
+
+## 三端支持与设备准备
+
+目前已完成三端适配：安卓使用 UiAutomator2，iOS 使用 WDA / XCTest，鸿蒙使用 UITest / hmdriver2。组件把各端的系统层级、截图、显示尺寸与点击通道接入同一候选定位流程，并处理 iOS 截图像素与 WDA point 的坐标映射。三端均支持真机与虚拟机，使用同一接口完成单步和连续点击。
+
+使用前，需要准备已授权、保持解锁的设备及对应平台服务，再提供所选模型通道的 Key：
+
+| 平台 | 需要准备 |
+|---|---|
+| Android | ADB 能识别设备，USB 调试已授权，UiAutomator2 服务可运行。 |
+| iOS | 真机已开启开发者模式并完成信任，签名后的 WDA 服务已运行且地址可访问。 |
+| HarmonyOS | HDC 能识别并连接已授权设备，UITest / hmdriver2 服务可用。 |
+
+具体操作见[三端设备准备](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E4%B8%89%E7%AB%AF%E8%AE%BE%E5%A4%87%E5%87%86%E5%A4%87.md)。下面保留三端原始图例，展示候选编号与可执行区域的绑定。
+
+![三端视觉定位与执行验证](https://raw.githubusercontent.com/dongxinsuperman/jev-phone/main/docs/media/readme/platforms.zh.png)
+
+## 独立组件接入
+
+把手机点击能力接到你已有的程序中：准备好设备服务和模型 Key，创建目标平台的 Clicker。单个点击目标调用 `click(target)`，一组有序目标调用 `run(text)`；组件返回选中区域、坐标、驱动状态和分段耗时，让你的程序继续处理后续流程。
+
+接入不需要运行 Demo 网页或数据库。安卓、iOS、鸿蒙分别使用 `AndroidClicker`、`IOSClicker`、`HarmonyClicker`，模型通道配置和异常处理见接入指南。
+
+[SDK接入指南](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E6%8E%A5%E5%85%A5%E6%8C%87%E5%8D%97.md) · [三端设备准备](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E4%B8%89%E7%AB%AF%E8%AE%BE%E5%A4%87%E5%87%86%E5%A4%87.md) · [调用示例](https://github.com/dongxinsuperman/jev-phone/blob/main/examples/click.py) · [多设备并行](https://github.com/dongxinsuperman/jev-phone/blob/main/examples/parallel.py)
+
+## 当前能力与后续承接
+
+当前支持 Android、iOS、HarmonyOS 真机与虚拟机上的单步和连续点击，完成画面采集、候选生成、模型选择、点击执行，并返回结果与计时。
+
+后续可扩展输入、滚动、长按等动作。任务规划、业务断言、应用启动和设备调度由现有系统承接，可以围绕点击组件继续集成。
+
+[版本、升级与维护](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E5%8D%87%E7%BA%A7%E4%B8%8E%E7%BB%B4%E6%8A%A4.md) · 当前版本 **0.1.1**。
+
+## 接入代码
+
+需要 **Python 3.10+**（例如 `python3.11`）；下面命令适用于 macOS / Linux。克隆前需具备仓库访问权限并完成 GitHub Git 认证；也可使用源码包或 wheel，安装方法见[升级与维护](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E5%8D%87%E7%BA%A7%E4%B8%8E%E7%BB%B4%E6%8A%A4.md)。从仓库安装固定版本：
+
+```sh
+git clone https://github.com/dongxinsuperman/jev-phone.git
+cd jev-phone
+git checkout v0.1.1
+python3.11 -m venv .venv
+.venv/bin/pip install -e '.[android]'
+```
+
+安卓安装 `.[android]`，iOS 安装 `.`，鸿蒙安装 `.[harmony]`；同时接三端使用 `.[android,harmony]`。先按[三端设备准备](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E4%B8%89%E7%AB%AF%E8%AE%BE%E5%A4%87%E5%87%86%E5%A4%87.md)启动对应设备服务并解锁设备、打开目标应用。将示例 serial 替换为 `adb devices -l` 中的真实编号；示例步骤要求当前应用中存在对应按钮。默认使用 OpenRouter Decisions，输入该账号的 Key；该账号须能调用所配置的模型接口。SDK 不会启动应用或替你登录。
+
+```python
+from getpass import getpass
+from jev_phone import AndroidClicker
+
+with AndroidClicker(
+    serial="YOUR_DEVICE_SERIAL",
+    api_key=getpass("OpenRouter Key: "),
+    provider="openrouter",
+) as phone:
+    report = phone.run("打开默认难度设置；选择中等难度；保存修改")
+    print(report["results"])
+```
+
+[SDK接入指南](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E6%8E%A5%E5%85%A5%E6%8C%87%E5%8D%97.md) · [三端设备准备](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E4%B8%89%E7%AB%AF%E8%AE%BE%E5%A4%87%E5%87%86%E5%A4%87.md) · [验证概览](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E9%AA%8C%E8%AF%81%E6%A6%82%E8%A7%88.md) · [完整计时记录](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E6%BC%94%E7%A4%BA%E8%80%97%E6%97%B6%E6%98%8E%E7%BB%86.md) · [页面源码](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/readme-site/manual.zh.html) · [MIT](https://github.com/dongxinsuperman/jev-phone/blob/main/LICENSE)

jev_phone-0.1.1/README.md

@@ -0,0 +1,114 @@
+<h1 align="center">Jev Phone</h1>
+<p align="center"><strong>毫秒级本地处理的三端多模态点击 SDK</strong></p>
+<p align="center">Android · iOS · HarmonyOS</p>
+<p align="center"><strong>经济、快速、准确</strong></p>
+<p align="center"><a href="README.md">中文</a> · <a href="README.en.md">English</a></p>
+
+Jev Phone 将 Jev 多模态决策接到三端设备上，为已有 Agent、测试平台和脚本提供可独立调用的手机点击能力。**调用方给出点击目标，SDK 完成当前画面的定位和执行。**
+
+它承接从“知道要操作什么”到“实际点到设备上”的这一段。你可以继续使用自己的任务规划、缓存和业务判断，不需要引入完整 AI Phone 框架。
+
+![多模态决策驱动的三端视觉交互通道](docs/media/readme/overview.zh.png)
+
+## 实机演示：预览难度并保存
+
+安卓真机连续执行四步：基础 → 中等 → 困难 → 保存修改。起始画面已打开难度弹窗，最终保存为困难。秒表按真实时间连续计时，视频未加速。
+
+![实机演示：预览难度并保存](docs/media/demo-default-difficulty-fast.gif)
+
+<table align="center">
+<thead><tr><th align="center">步骤</th><th align="center">模型往返</th><th align="center">SDK本地处理</th><th align="center">页面稳定等待</th><th align="center">整步合计</th></tr></thead>
+<tbody>
+<tr><td align="center">基础</td><td align="center">763.28 ms</td><td align="center">490.99 ms</td><td align="center">658.00 ms</td><td align="center">1,912.27 ms</td></tr>
+<tr><td align="center">中等</td><td align="center">646.39 ms</td><td align="center">289.80 ms</td><td align="center">665.00 ms</td><td align="center">1,601.19 ms</td></tr>
+<tr><td align="center">困难</td><td align="center">647.78 ms</td><td align="center">296.26 ms</td><td align="center">702.00 ms</td><td align="center">1,646.04 ms</td></tr>
+<tr><td align="center">保存修改</td><td align="center">706.62 ms</td><td align="center">301.97 ms</td><td align="center">0.00 ms</td><td align="center">1,008.59 ms</td></tr>
+</tbody>
+</table>
+
+整步合计包含点击后的页面稳定等待，通过连续截图对比判断画面是否稳定；末步没有后续步骤，因此不追加等待。第一步低于2秒，其余三步均低于1.7秒；整轮实际耗时 **6,170.82ms**。本地 SDK 已实现毫秒级处理；模型往返耗时则受你的网络状况与模型服务响应影响，是整步耗时波动的主要来源。
+
+[MP4](docs/media/demo-default-difficulty-fast.mp4) · [JSON](docs/media/demo-default-difficulty-fast.json)
+
+## 性能
+
+已有安卓实验中，本地候选处理、画框与编码耗时 **15–50ms**；非模型整轮中位为 **620ms**，同一导航样本9轮范围为 **493–729ms**。这些数据不包含模型请求、初始化与页面稳定。
+
+每一步整体耗时还包括设备采集、候选处理、模型往返、点击和该步后续衔接。[完整分段记录](docs/演示耗时明细.md)分别列出这些时间。
+
+![毫秒级通道处理与分段计时](docs/media/readme/timing.zh.png)
+
+## 工作原理：Jev 选择，组件执行
+
+当前接入的多模态 Jev 采用 **有限选项决策接口**：它结合图像选择给定候选，这种接入方式并不直接返回设备操作指令或可执行的点击坐标。因此，从模型选中目标到设备实际点击，还需要组件完成定位与动作绑定。
+
+我们先从系统树中提取可操作元素的边界，用四角在截图上勾勒出矩形，并为每个区域标记编号。Jev 接收当前目标和带编号的图像，只需选出对应编号；组件再根据编号找回元素边界，计算中心坐标，交给平台驱动执行点击。代码保存左上角与右下角坐标，由此确定矩形四角。 实际编号图还以中心红点和引线标明点击位置，编号会避让，重叠展示框会围绕原中心缩小；这些绘图处理不会改变候选的原始边界和点击坐标。
+
+![从点击目标到编号选择，再到设备坐标点击](docs/media/readme/target-to-tap.zh.svg)
+
+## 为什么结合系统树与截图
+
+矩形的位置来自系统树，目标的文字、图标和外观语义来自截图。例如，节点文字为空，但画面中显示的是头像：Jev 可以依据图像识别头像并选择它的编号，组件则用同一编号找回已知边界。这样，多模态选项决策就能对应到真实可操作元素，而不需要模型自己生成坐标。
+
+![几何约束与视觉语义融合](docs/media/readme/geometry.zh.png)
+
+## 三端支持与设备准备
+
+目前已完成三端适配：安卓使用 UiAutomator2，iOS 使用 WDA / XCTest，鸿蒙使用 UITest / hmdriver2。组件把各端的系统层级、截图、显示尺寸与点击通道接入同一候选定位流程，并处理 iOS 截图像素与 WDA point 的坐标映射。三端均支持真机与虚拟机，使用同一接口完成单步和连续点击。
+
+使用前，需要准备已授权、保持解锁的设备及对应平台服务，再提供所选模型通道的 Key：
+
+| 平台 | 需要准备 |
+|---|---|
+| Android | ADB 能识别设备，USB 调试已授权，UiAutomator2 服务可运行。 |
+| iOS | 真机已开启开发者模式并完成信任，签名后的 WDA 服务已运行且地址可访问。 |
+| HarmonyOS | HDC 能识别并连接已授权设备，UITest / hmdriver2 服务可用。 |
+
+具体操作见[三端设备准备](docs/三端设备准备.md)。下面保留三端原始图例，展示候选编号与可执行区域的绑定。
+
+![三端视觉定位与执行验证](docs/media/readme/platforms.zh.png)
+
+## 独立组件接入
+
+把手机点击能力接到你已有的程序中：准备好设备服务和模型 Key，创建目标平台的 Clicker。单个点击目标调用 `click(target)`，一组有序目标调用 `run(text)`；组件返回选中区域、坐标、驱动状态和分段耗时，让你的程序继续处理后续流程。
+
+接入不需要运行 Demo 网页或数据库。安卓、iOS、鸿蒙分别使用 `AndroidClicker`、`IOSClicker`、`HarmonyClicker`，模型通道配置和异常处理见接入指南。
+
+[SDK接入指南](docs/接入指南.md) · [三端设备准备](docs/三端设备准备.md) · [调用示例](examples/click.py) · [多设备并行](examples/parallel.py)
+
+## 当前能力与后续承接
+
+当前支持 Android、iOS、HarmonyOS 真机与虚拟机上的单步和连续点击，完成画面采集、候选生成、模型选择、点击执行，并返回结果与计时。
+
+后续可扩展输入、滚动、长按等动作。任务规划、业务断言、应用启动和设备调度由现有系统承接，可以围绕点击组件继续集成。
+
+[版本、升级与维护](docs/升级与维护.md) · 当前版本 **0.1.1**。
+
+## 接入代码
+
+需要 **Python 3.10+**（例如 `python3.11`）；下面命令适用于 macOS / Linux。克隆前需具备仓库访问权限并完成 GitHub Git 认证；也可使用源码包或 wheel，安装方法见[升级与维护](docs/升级与维护.md)。从仓库安装固定版本：
+
+```sh
+git clone https://github.com/dongxinsuperman/jev-phone.git
+cd jev-phone
+git checkout v0.1.1
+python3.11 -m venv .venv
+.venv/bin/pip install -e '.[android]'
+```
+
+安卓安装 `.[android]`，iOS 安装 `.`，鸿蒙安装 `.[harmony]`；同时接三端使用 `.[android,harmony]`。先按[三端设备准备](docs/三端设备准备.md)启动对应设备服务并解锁设备、打开目标应用。将示例 serial 替换为 `adb devices -l` 中的真实编号；示例步骤要求当前应用中存在对应按钮。默认使用 OpenRouter Decisions，输入该账号的 Key；该账号须能调用所配置的模型接口。SDK 不会启动应用或替你登录。
+
+```python
+from getpass import getpass
+from jev_phone import AndroidClicker
+
+with AndroidClicker(
+    serial="YOUR_DEVICE_SERIAL",
+    api_key=getpass("OpenRouter Key: "),
+    provider="openrouter",
+) as phone:
+    report = phone.run("打开默认难度设置；选择中等难度；保存修改")
+    print(report["results"])
+```
+
+[SDK接入指南](docs/接入指南.md) · [三端设备准备](docs/三端设备准备.md) · [验证概览](docs/验证概览.md) · [完整计时记录](docs/演示耗时明细.md) · [页面源码](docs/readme-site/manual.zh.html) · [MIT](LICENSE)

jev_phone-0.1.1/README.pypi.md

@@ -0,0 +1,114 @@
+<h1 align="center">Jev Phone</h1>
+<p align="center"><strong>毫秒级本地处理的三端多模态点击 SDK</strong></p>
+<p align="center">Android · iOS · HarmonyOS</p>
+<p align="center"><strong>经济、快速、准确</strong></p>
+<p align="center"><a href="https://github.com/dongxinsuperman/jev-phone/blob/main/README.md">中文</a> · <a href="https://github.com/dongxinsuperman/jev-phone/blob/main/README.en.md">English</a></p>
+
+Jev Phone 将 Jev 多模态决策接到三端设备上，为已有 Agent、测试平台和脚本提供可独立调用的手机点击能力。**调用方给出点击目标，SDK 完成当前画面的定位和执行。**
+
+它承接从“知道要操作什么”到“实际点到设备上”的这一段。你可以继续使用自己的任务规划、缓存和业务判断，不需要引入完整 AI Phone 框架。
+
+![多模态决策驱动的三端视觉交互通道](https://raw.githubusercontent.com/dongxinsuperman/jev-phone/main/docs/media/readme/overview.zh.png)
+
+## 实机演示：预览难度并保存
+
+安卓真机连续执行四步：基础 → 中等 → 困难 → 保存修改。起始画面已打开难度弹窗，最终保存为困难。秒表按真实时间连续计时，视频未加速。
+
+![实机演示：预览难度并保存](https://raw.githubusercontent.com/dongxinsuperman/jev-phone/main/docs/media/demo-default-difficulty-fast.gif)
+
+<table align="center">
+<thead><tr><th align="center">步骤</th><th align="center">模型往返</th><th align="center">SDK本地处理</th><th align="center">页面稳定等待</th><th align="center">整步合计</th></tr></thead>
+<tbody>
+<tr><td align="center">基础</td><td align="center">763.28 ms</td><td align="center">490.99 ms</td><td align="center">658.00 ms</td><td align="center">1,912.27 ms</td></tr>
+<tr><td align="center">中等</td><td align="center">646.39 ms</td><td align="center">289.80 ms</td><td align="center">665.00 ms</td><td align="center">1,601.19 ms</td></tr>
+<tr><td align="center">困难</td><td align="center">647.78 ms</td><td align="center">296.26 ms</td><td align="center">702.00 ms</td><td align="center">1,646.04 ms</td></tr>
+<tr><td align="center">保存修改</td><td align="center">706.62 ms</td><td align="center">301.97 ms</td><td align="center">0.00 ms</td><td align="center">1,008.59 ms</td></tr>
+</tbody>
+</table>
+
+整步合计包含点击后的页面稳定等待，通过连续截图对比判断画面是否稳定；末步没有后续步骤，因此不追加等待。第一步低于2秒，其余三步均低于1.7秒；整轮实际耗时 **6,170.82ms**。本地 SDK 已实现毫秒级处理；模型往返耗时则受你的网络状况与模型服务响应影响，是整步耗时波动的主要来源。
+
+[MP4](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/media/demo-default-difficulty-fast.mp4) · [JSON](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/media/demo-default-difficulty-fast.json)
+
+## 性能
+
+已有安卓实验中，本地候选处理、画框与编码耗时 **15–50ms**；非模型整轮中位为 **620ms**，同一导航样本9轮范围为 **493–729ms**。这些数据不包含模型请求、初始化与页面稳定。
+
+每一步整体耗时还包括设备采集、候选处理、模型往返、点击和该步后续衔接。[完整分段记录](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E6%BC%94%E7%A4%BA%E8%80%97%E6%97%B6%E6%98%8E%E7%BB%86.md)分别列出这些时间。
+
+![毫秒级通道处理与分段计时](https://raw.githubusercontent.com/dongxinsuperman/jev-phone/main/docs/media/readme/timing.zh.png)
+
+## 工作原理：Jev 选择，组件执行
+
+当前接入的多模态 Jev 采用 **有限选项决策接口**：它结合图像选择给定候选，这种接入方式并不直接返回设备操作指令或可执行的点击坐标。因此，从模型选中目标到设备实际点击，还需要组件完成定位与动作绑定。
+
+我们先从系统树中提取可操作元素的边界，用四角在截图上勾勒出矩形，并为每个区域标记编号。Jev 接收当前目标和带编号的图像，只需选出对应编号；组件再根据编号找回元素边界，计算中心坐标，交给平台驱动执行点击。代码保存左上角与右下角坐标，由此确定矩形四角。 实际编号图还以中心红点和引线标明点击位置，编号会避让，重叠展示框会围绕原中心缩小；这些绘图处理不会改变候选的原始边界和点击坐标。
+
+![从点击目标到编号选择，再到设备坐标点击](https://raw.githubusercontent.com/dongxinsuperman/jev-phone/main/docs/media/readme/target-to-tap.zh.svg)
+
+## 为什么结合系统树与截图
+
+矩形的位置来自系统树，目标的文字、图标和外观语义来自截图。例如，节点文字为空，但画面中显示的是头像：Jev 可以依据图像识别头像并选择它的编号，组件则用同一编号找回已知边界。这样，多模态选项决策就能对应到真实可操作元素，而不需要模型自己生成坐标。
+
+![几何约束与视觉语义融合](https://raw.githubusercontent.com/dongxinsuperman/jev-phone/main/docs/media/readme/geometry.zh.png)
+
+## 三端支持与设备准备
+
+目前已完成三端适配：安卓使用 UiAutomator2，iOS 使用 WDA / XCTest，鸿蒙使用 UITest / hmdriver2。组件把各端的系统层级、截图、显示尺寸与点击通道接入同一候选定位流程，并处理 iOS 截图像素与 WDA point 的坐标映射。三端均支持真机与虚拟机，使用同一接口完成单步和连续点击。
+
+使用前，需要准备已授权、保持解锁的设备及对应平台服务，再提供所选模型通道的 Key：
+
+| 平台 | 需要准备 |
+|---|---|
+| Android | ADB 能识别设备，USB 调试已授权，UiAutomator2 服务可运行。 |
+| iOS | 真机已开启开发者模式并完成信任，签名后的 WDA 服务已运行且地址可访问。 |
+| HarmonyOS | HDC 能识别并连接已授权设备，UITest / hmdriver2 服务可用。 |
+
+具体操作见[三端设备准备](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E4%B8%89%E7%AB%AF%E8%AE%BE%E5%A4%87%E5%87%86%E5%A4%87.md)。下面保留三端原始图例，展示候选编号与可执行区域的绑定。
+
+![三端视觉定位与执行验证](https://raw.githubusercontent.com/dongxinsuperman/jev-phone/main/docs/media/readme/platforms.zh.png)
+
+## 独立组件接入
+
+把手机点击能力接到你已有的程序中：准备好设备服务和模型 Key，创建目标平台的 Clicker。单个点击目标调用 `click(target)`，一组有序目标调用 `run(text)`；组件返回选中区域、坐标、驱动状态和分段耗时，让你的程序继续处理后续流程。
+
+接入不需要运行 Demo 网页或数据库。安卓、iOS、鸿蒙分别使用 `AndroidClicker`、`IOSClicker`、`HarmonyClicker`，模型通道配置和异常处理见接入指南。
+
+[SDK接入指南](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E6%8E%A5%E5%85%A5%E6%8C%87%E5%8D%97.md) · [三端设备准备](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E4%B8%89%E7%AB%AF%E8%AE%BE%E5%A4%87%E5%87%86%E5%A4%87.md) · [调用示例](https://github.com/dongxinsuperman/jev-phone/blob/main/examples/click.py) · [多设备并行](https://github.com/dongxinsuperman/jev-phone/blob/main/examples/parallel.py)
+
+## 当前能力与后续承接
+
+当前支持 Android、iOS、HarmonyOS 真机与虚拟机上的单步和连续点击，完成画面采集、候选生成、模型选择、点击执行，并返回结果与计时。
+
+后续可扩展输入、滚动、长按等动作。任务规划、业务断言、应用启动和设备调度由现有系统承接，可以围绕点击组件继续集成。
+
+[版本、升级与维护](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E5%8D%87%E7%BA%A7%E4%B8%8E%E7%BB%B4%E6%8A%A4.md) · 当前版本 **0.1.1**。
+
+## 接入代码
+
+需要 **Python 3.10+**（例如 `python3.11`）；下面命令适用于 macOS / Linux。克隆前需具备仓库访问权限并完成 GitHub Git 认证；也可使用源码包或 wheel，安装方法见[升级与维护](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E5%8D%87%E7%BA%A7%E4%B8%8E%E7%BB%B4%E6%8A%A4.md)。从仓库安装固定版本：
+
+```sh
+git clone https://github.com/dongxinsuperman/jev-phone.git
+cd jev-phone
+git checkout v0.1.1
+python3.11 -m venv .venv
+.venv/bin/pip install -e '.[android]'
+```
+
+安卓安装 `.[android]`，iOS 安装 `.`，鸿蒙安装 `.[harmony]`；同时接三端使用 `.[android,harmony]`。先按[三端设备准备](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E4%B8%89%E7%AB%AF%E8%AE%BE%E5%A4%87%E5%87%86%E5%A4%87.md)启动对应设备服务并解锁设备、打开目标应用。将示例 serial 替换为 `adb devices -l` 中的真实编号；示例步骤要求当前应用中存在对应按钮。默认使用 OpenRouter Decisions，输入该账号的 Key；该账号须能调用所配置的模型接口。SDK 不会启动应用或替你登录。
+
+```python
+from getpass import getpass
+from jev_phone import AndroidClicker
+
+with AndroidClicker(
+    serial="YOUR_DEVICE_SERIAL",
+    api_key=getpass("OpenRouter Key: "),
+    provider="openrouter",
+) as phone:
+    report = phone.run("打开默认难度设置；选择中等难度；保存修改")
+    print(report["results"])
+```
+
+[SDK接入指南](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E6%8E%A5%E5%85%A5%E6%8C%87%E5%8D%97.md) · [三端设备准备](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E4%B8%89%E7%AB%AF%E8%AE%BE%E5%A4%87%E5%87%86%E5%A4%87.md) · [验证概览](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E9%AA%8C%E8%AF%81%E6%A6%82%E8%A7%88.md) · [完整计时记录](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/%E6%BC%94%E7%A4%BA%E8%80%97%E6%97%B6%E6%98%8E%E7%BB%86.md) · [页面源码](https://github.com/dongxinsuperman/jev-phone/blob/main/docs/readme-site/manual.zh.html) · [MIT](https://github.com/dongxinsuperman/jev-phone/blob/main/LICENSE)

jev_phone-0.1.1/jev_phone/__init__.py

@@ -0,0 +1,4 @@
+"""Independent multi-platform visual click component."""
+from .core import PhoneClicker, AndroidClicker, IOSClicker, HarmonyClicker, ClickFailure, RunFailure, split_steps
+from .adapters import DeviceAdapter, Observation, AndroidAdapter, IOSAdapter, HarmonyAdapter
+__all__=['PhoneClicker','AndroidClicker','IOSClicker','HarmonyClicker','ClickFailure','RunFailure','split_steps','DeviceAdapter','Observation','AndroidAdapter','IOSAdapter','HarmonyAdapter']

jev_phone-0.1.1/jev_phone/adapters/__init__.py

@@ -0,0 +1,5 @@
+from .base import DeviceAdapter, Observation
+from .android import AndroidAdapter
+from .ios import IOSAdapter
+from .harmony import HarmonyAdapter
+__all__=['DeviceAdapter','Observation','AndroidAdapter','IOSAdapter','HarmonyAdapter']

jev_phone-0.1.1/jev_phone/adapters/android.py

@@ -0,0 +1,53 @@
+import base64
+import io
+from PIL import Image
+from .base import Observation
+
+class AndroidAdapter:
+    platform = 'android'
+    model_note = ''
+    recheck_before_click = False
+    def __init__(self, serial=None, device=None):
+        if device is None:
+            try:import uiautomator2 as u2
+            except ImportError as e:raise RuntimeError('Install jev-phone[android].') from e
+            device=u2.connect(serial)
+        self.device=device
+        self.serial=serial or getattr(device,'serial','android-device')
+        self.identity='android:'+self.serial
+
+    def viewport(self):
+        # Same live dimensions and exceptional fallback as V3.
+        try:
+            info = self.device.info
+            width, height = info['displayWidth'], info['displayHeight']
+            if type(width) is not int or type(height) is not int or min(width, height) <= 0:
+                raise ValueError('Invalid UiAutomator display dimensions')
+            return width, height
+        except Exception:
+            return tuple(self.device.window_size())
+
+    def screenshot(self):
+        raw=self.device.jsonrpc.takeScreenshot(1,95)
+        if not raw:raise RuntimeError('UiAutomator2 未返回截图。')
+        return base64.b64decode(raw)
+
+    def observe(self,stage,frame=None):
+        viewport=stage('capture',self.viewport)
+        tree=stage('tree',lambda:self.device.dump_hierarchy(compressed=False,pretty=False,max_depth=100,root_in_active=True))
+        frame=frame if frame is not None else stage('screenshot',self.screenshot)
+        if Image.open(io.BytesIO(frame)).size!=viewport:
+            raise RuntimeError('安卓层级视口与截图尺寸不一致，未执行点击。')
+        return Observation(tree,frame,viewport)
+
+    def observe_with_frame(self,stage,frame):
+        # V3 already supplied this exact settled frame; reuse its pixel dimensions.
+        viewport=stage('capture',lambda:Image.open(io.BytesIO(frame)).size)
+        tree=stage('tree',lambda:self.device.dump_hierarchy(compressed=False,pretty=False,max_depth=100,root_in_active=True))
+        return Observation(tree,frame,viewport)
+
+    def click(self,x,y,observation):
+        result=self.device.click(int(x),int(y))
+        if result is False:
+            raise RuntimeError('UiAutomator2 rejected coordinate click')
+    def close(self):pass  # Do not stop a shared device-side UiAutomator2 service.

jev_phone-0.1.1/jev_phone/adapters/base.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass, field
+from typing import Protocol, Callable, Any
+
+@dataclass
+class Observation:
+    tree: str
+    image: bytes
+    viewport: tuple
+    metadata: dict = field(default_factory=dict)
+
+class DeviceAdapter(Protocol):
+    """Adapters return screenshot pixels and execute clicks in that same frame."""
+    identity: str
+    platform: str
+    def observe(self, stage: Callable[[str, Callable], Any]) -> Observation: ...
+    def viewport(self) -> tuple: ...
+    def click(self, x: int, y: int, observation: Observation) -> None: ...
+    def screenshot(self) -> bytes: ...
+    def close(self) -> None: ...

jev_phone-0.1.1/jev_phone/adapters/harmony.py

@@ -0,0 +1,110 @@
+import io
+import re
+import tempfile
+import time
+import json
+import types
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from PIL import Image
+from .base import Observation
+
+class HarmonyAdapter:
+    """Thin hmdriver2 adapter; no VM, account, or application management."""
+    platform='harmony'
+    recheck_before_click = False
+    model_note='以截图可见控件为准，候选可能包括可点击容器中的独立图片区域。'
+    def __init__(self,serial=None,driver=None):
+        if driver is None:
+            try:from hmdriver2.driver import Driver
+            except ImportError as e:raise RuntimeError('Install jev-phone[harmony] and configure HDC.') from e
+            driver=Driver(serial)
+        self.driver=driver
+        self.serial=serial or driver.serial
+        self.identity='harmony:'+self.serial
+
+    def viewport(self):
+        # V3 refreshes dimensions once; no rotation probe or delayed retry.
+        for name in ('display_size','display_rotation'):
+            self.driver.__dict__.pop(name,None)
+        return tuple(self.driver.display_size)
+
+    def screenshot(self):
+        with tempfile.TemporaryDirectory(prefix='jev-phone-hm-') as directory:
+            path=Path(directory)/'screen.jpeg';self.driver.screenshot(str(path));return path.read_bytes()
+
+    @staticmethod
+    def convert(tree):
+        def flag(value):return str(value).lower()=='true'
+        def convert_node(item,parent_click=False,parent_bounds=None):
+            a=item.get('attributes',{})
+            b=list(map(int,re.findall(r'-?\d+',str(a.get('bounds','')))))
+            valid=len(b)==4
+            if valid and parent_bounds:
+                b=[max(b[0],parent_bounds[0]),max(b[1],parent_bounds[1]),min(b[2],parent_bounds[2]),min(b[3],parent_bounds[3])]
+            valid=valid and b[2]>b[0] and b[3]>b[1]
+            native=flag(a.get('clickable',False));visible=flag(a.get('visible',True))
+            active=(native or (parent_click and a.get('type')=='Image')) and visible and valid
+            attrs={'text':str(a.get('text','')),'content-desc':str(a.get('description','')),'resource-id':str(a.get('id','')),'class':str(a.get('type','')),
+                'clickable':str(active).lower(),'enabled':str(flag(a.get('enabled',False))).lower(),'visible-to-user':str(visible).lower(),
+                'bounds':f'[{b[0]},{b[1]}][{b[2]},{b[3]}]' if valid else ''}
+            out=ET.Element('node',attrs)
+            for child in item.get('children',[]):out.append(convert_node(child,parent_click or native,b if valid else parent_bounds))
+            return out
+        root=ET.Element('hierarchy');root.append(convert_node(tree));return ET.tostring(root,encoding='unicode')
+
+    def raw_tree(self):
+        # V3's captureLayout reader, adapted to this instance's device lock.
+        client = self.driver._client
+        original = client._recv_msg
+
+        def receive(_client, buff_size=4096, decode=False, print=True):
+            payload = bytearray()
+            sock = _client.sock
+            old_timeout = sock.gettimeout()
+            deadline = time.monotonic() + 5.0
+            try:
+                while True:
+                    remaining = deadline - time.monotonic()
+                    if remaining <= 0:
+                        raise TimeoutError('Harmony hierarchy deadline')
+                    sock.settimeout(remaining)
+                    chunk = sock.recv(65536)
+                    if not chunk:
+                        raise ConnectionError('Harmony hierarchy connection closed')
+                    payload.extend(chunk)
+                    if len(payload) > 16 * 1024 * 1024:
+                        raise ValueError('Harmony hierarchy exceeds size limit')
+                    try:
+                        text = payload.decode('utf-8')
+                        json.loads(text)
+                    except (UnicodeDecodeError, json.JSONDecodeError):
+                        continue
+                    return text if decode else payload
+            finally:
+                sock.settimeout(old_timeout)
+
+        client._recv_msg = types.MethodType(receive, client)
+        try:
+            return client.invoke_captures('captureLayout').result
+        finally:
+            client._recv_msg = original
+
+    def source(self):return self.convert(self.raw_tree())
+
+    def observe(self,stage,frame=None):
+        viewport=stage('capture',self.viewport)
+        frame=frame if frame is not None else stage('screenshot',self.screenshot)
+        tree=stage('tree',self.source)
+        if Image.open(io.BytesIO(frame)).size!=viewport:
+            raise RuntimeError('Harmony viewport and screenshot dimensions disagree.')
+        return Observation(tree,frame,viewport)
+
+    def observe_with_frame(self,stage,frame):
+        return self.observe(stage,frame)
+
+    def click(self,x,y,observation):
+        # V3 direct UITest completion; bypass hmdriver2's @delay (600ms).
+        return self.driver._invoke('Driver.click',args=[int(x),int(y)])
+
+    def close(self):pass  # Shared device service remains owned by the caller.