uihound 0.1.0__tar.gz

uihound-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: uihound
+Version: 0.1.0
+Summary: Browser-based Android UI inspector for HIL testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi<1.0,>=0.110
+Requires-Dist: pydantic<3.0,>=2.9
+Requires-Dist: pydantic-settings<3.0,>=2.5
+Requires-Dist: uvicorn[standard]<1.0,>=0.27
+Requires-Dist: uiautomator2<4.0,>=3.2
+Requires-Dist: adbutils<3.0,>=2.0
+Requires-Dist: lxml<7,>=4.9
+Requires-Dist: Pillow<12.0,>=10.0
+
+# UiHound · UI 猎犬
+
+UiHound 是用于 Android 调试与自动化测试的网页工具。在浏览器中查看设备画面和 UI 节点、复制定位表达式、远程操作设备，并完成取色、截图与录屏。
+
+## 功能
+
+| 功能 | 说明 |
+|---|---|
+| 元素检查 | UI 节点树、节点虚线边界、选中高亮、属性与坐标展示 |
+| 元素定位 | u2 selector / XPath 搜索与复制，优先生成唯一属性定位 |
+| 远程操作 | scrcpy 实时画面，点击、拖动、长按、双指滚动、主页、返回、后台任务 |
+| 颜色取样 | 像素放大镜、坐标、HEX、RGB、HSB、OpenCV HSV，多点记录与复制 |
+| 截图 | 全屏、元素和区域截图，选区移动、缩放及坐标微调 |
+| 录屏 | 录制设备画面，保存为无音频 WebM，支持视频预览 |
+| 文件管理 | 截图与录屏列表、复制文件、删除单个或全部、打开保存目录 |
+| 工作区 | 可调节分栏、白天 / 黑夜主题、偏好记忆 |
+
+## 安装与启动
+
+### 环境准备
+
+- Python 3.10 或以上版本。
+- Android Platform Tools，确保 `adb` 已加入 PATH。
+- macOS、Windows 或 Linux；新版 Chrome 或 Edge，使用本机地址访问。
+- Android 设备开启 USB / 无线调试，并接受调试授权。
+
+在终端执行 `adb devices`，确认设备状态为 `device`。无线连接可先执行 `adb connect 地址:端口`。
+
+### 安装
+
+安装并启动：
+
+```powershell
+pip install uihound
+uihound
+```
+
+服务启动后自动打开 `http://127.0.0.1:8000`。在网页中选择设备或填写设备地址，点击“连接设备”。
+
+启动参数：
+
+```powershell
+# 指定端口
+uihound --port 8080
+
+# 不自动打开浏览器
+uihound --no-browser
+```
+
+升级到新版本：
+
+```powershell
+pip install --upgrade uihound
+```
+
+升级后重启 `uihound`，刷新网页即可。
+
+## 使用方法
+
+### 检查元素：hierarchy
+
+点击设备画面上方的 hierarchy 图标，获取当前截图和 UI 节点树。点击画面或树节点查看属性，复制定位表达式；也可在搜索框输入 selector 或 XPath：
+
+```python
+resourceId="com.example:id/title"
+text="设置"
+//*[@resource-id="com.example:id/title"]
+```
+
+XPath 优先使用当前层级中唯一的 `resource-id`、`content-desc`、`text`，没有可用唯一属性时才使用层级路径。
+
+**hierarchy 是静态快照，设备页面变化后需点击刷新。** 动画结束、画面稳定后再获取，便于对齐画面和节点。画面上方的边框按钮可显示或隐藏节点虚线。
+
+### 操作设备：remote
+
+点击 remote 图标进入实时操作模式。鼠标点击对应轻触，按住对应长按，拖动或触摸板双指滚动对应滑动。侧栏提供主页、返回、后台任务等操作。
+
+点击冻结按钮暂停网页画面，暂停期间禁用触摸，再次点击恢复。文本输入在“常用操作”页完成，支持 `Ctrl+Enter` 发送。
+
+首次使用 remote 会下载 scrcpy-server v3.3.4。离线环境可预先下载同版本官方文件，并通过 `UIHOUND_SCRCPY_SERVER` 指定路径。
+
+### 取色：color
+
+点击 color 获取当前无损画面，移动鼠标查看像素与颜色值。方向键微调 1px，`Shift+方向键` 微调 10px；点击或按 Enter 保存取样。最新记录置顶，每项可单独复制。
+
+刷新或切换画面会清除取样记录。OpenCV HSV 为范围换算值，边界颜色可能存在 1 个单位的舍入差异。
+
+### 截图与文件管理
+
+通过侧栏保存全屏截图，或选中元素后点击“元素截图”。区域截图先点击框选按钮，再拖出选区；可拖动选区、调整八个边角、输入坐标或用方向键微调。保存成功后自动清除选区。
+
+hierarchy / color 截取当前静态画面；remote 全屏截图获取设备当前画面。截图不会包含节点边框。
+
+在“截图”页修改保存目录、查看缩略图、复制或删除文件。**删除会真实移除磁盘文件，操作前会确认；删除全部仅针对当前列表，不递归删除子目录。**
+
+“复制文件”后可在目标文件夹使用系统粘贴快捷键（Windows `Ctrl+V`，macOS `Command+V`）粘贴。“打开目录”直接打开保存位置。这两项需要浏览器和服务运行在同一台电脑；文件剪贴板复制支持 Windows 和 macOS，Linux 暂不支持。
+
+### 录屏
+
+点击侧栏圆形录屏按钮开始，再次点击停止并保存；非 remote 模式会自动连接 remote 后开始录制。
+
+录屏默认保存在用户主目录下的 `UiHound\recordings` 文件夹。“录屏”页支持修改保存目录、播放、复制文件、删除和打开目录。录制内容不包含节点边框；冻结网页画面时仍会录制设备新帧。
+
+切换模式或断开设备会停止并保存录屏。录屏接近 240 MiB 时自动停止。**关闭网页前请等待保存完成**；上传失败可在录屏页重试，强制关闭或刷新会丢失未保存的视频。
+
+## 常用设置
+
+截图和录屏页可选择对应根目录内的子目录。需要更换根目录或调整画质时，在启动前设置环境变量：
+
+```powershell
+$env:UIHOUND_SNAPSHOT_DIR = "D:\UiHoundData\snapshots"
+$env:UIHOUND_RECORDING_DIR = "D:\UiHoundData\recordings"
+$env:UIHOUND_SCRCPY_MAX_SIZE = "1920"
+$env:UIHOUND_SCRCPY_MAX_FPS = "60"
+$env:UIHOUND_SCRCPY_BIT_RATE = "8000000"
+uihound
+```
+
+默认文件位置固定在用户主目录下，不受启动目录或安装目录影响：
+
+| 文件 | Windows | macOS / Linux |
+|---|---|---|
+| 截图 | `%USERPROFILE%\UiHound\screenshots` | `~/UiHound/screenshots` |
+| 录屏 | `%USERPROFILE%\UiHound\recordings` | `~/UiHound/recordings` |
+
+环境变量可覆盖默认根目录。升级前保存的文件不会自动移动或删除；浏览器记住的路径若已不在当前允许的根目录内，会提示并切换到默认目录。
+
+remote 默认最长边 1920、目标 60 fps、码率 8 Mbps；实际流畅度取决于设备与连接状况。
+
+拖动分隔条调整设备、属性和节点树区域，顶部可重置布局。太阳 / 月亮按钮切换主题，浏览器会记住主题和分栏宽度。
+
+## 自动化调用
+
+| 请求 | 参数 |
+|---|---|
+| `GET /device/status` | 设备连接状态 |
+| `GET /snapshot/full` | 可选 `save_dir`、`filename` |
+| `GET /snapshot/element` | 必填 `selector`；可选 `save_dir`、`filename` |
+| `GET /snapshot/region` | 必填 `x1`、`y1`、`x2`、`y2`；可选 `save_dir`、`filename` |
+
+截图接口返回 `success`、`file_path`、`base64`、`timestamp`。`save_dir` 必须位于截图根目录内，`filename` 为 `.png` 文件名；同名文件不会覆盖。
+
+服务用于本机调试，请勿直接暴露到不受信任的网络。

uihound-0.1.0/README.md

@@ -0,0 +1,143 @@
+# UiHound · UI 猎犬
+
+UiHound 是用于 Android 调试与自动化测试的网页工具。在浏览器中查看设备画面和 UI 节点、复制定位表达式、远程操作设备，并完成取色、截图与录屏。
+
+## 功能
+
+| 功能 | 说明 |
+|---|---|
+| 元素检查 | UI 节点树、节点虚线边界、选中高亮、属性与坐标展示 |
+| 元素定位 | u2 selector / XPath 搜索与复制，优先生成唯一属性定位 |
+| 远程操作 | scrcpy 实时画面，点击、拖动、长按、双指滚动、主页、返回、后台任务 |
+| 颜色取样 | 像素放大镜、坐标、HEX、RGB、HSB、OpenCV HSV，多点记录与复制 |
+| 截图 | 全屏、元素和区域截图，选区移动、缩放及坐标微调 |
+| 录屏 | 录制设备画面，保存为无音频 WebM，支持视频预览 |
+| 文件管理 | 截图与录屏列表、复制文件、删除单个或全部、打开保存目录 |
+| 工作区 | 可调节分栏、白天 / 黑夜主题、偏好记忆 |
+
+## 安装与启动
+
+### 环境准备
+
+- Python 3.10 或以上版本。
+- Android Platform Tools，确保 `adb` 已加入 PATH。
+- macOS、Windows 或 Linux；新版 Chrome 或 Edge，使用本机地址访问。
+- Android 设备开启 USB / 无线调试，并接受调试授权。
+
+在终端执行 `adb devices`，确认设备状态为 `device`。无线连接可先执行 `adb connect 地址:端口`。
+
+### 安装
+
+安装并启动：
+
+```powershell
+pip install uihound
+uihound
+```
+
+服务启动后自动打开 `http://127.0.0.1:8000`。在网页中选择设备或填写设备地址，点击“连接设备”。
+
+启动参数：
+
+```powershell
+# 指定端口
+uihound --port 8080
+
+# 不自动打开浏览器
+uihound --no-browser
+```
+
+升级到新版本：
+
+```powershell
+pip install --upgrade uihound
+```
+
+升级后重启 `uihound`，刷新网页即可。
+
+## 使用方法
+
+### 检查元素：hierarchy
+
+点击设备画面上方的 hierarchy 图标，获取当前截图和 UI 节点树。点击画面或树节点查看属性，复制定位表达式；也可在搜索框输入 selector 或 XPath：
+
+```python
+resourceId="com.example:id/title"
+text="设置"
+//*[@resource-id="com.example:id/title"]
+```
+
+XPath 优先使用当前层级中唯一的 `resource-id`、`content-desc`、`text`，没有可用唯一属性时才使用层级路径。
+
+**hierarchy 是静态快照，设备页面变化后需点击刷新。** 动画结束、画面稳定后再获取，便于对齐画面和节点。画面上方的边框按钮可显示或隐藏节点虚线。
+
+### 操作设备：remote
+
+点击 remote 图标进入实时操作模式。鼠标点击对应轻触，按住对应长按，拖动或触摸板双指滚动对应滑动。侧栏提供主页、返回、后台任务等操作。
+
+点击冻结按钮暂停网页画面，暂停期间禁用触摸，再次点击恢复。文本输入在“常用操作”页完成，支持 `Ctrl+Enter` 发送。
+
+首次使用 remote 会下载 scrcpy-server v3.3.4。离线环境可预先下载同版本官方文件，并通过 `UIHOUND_SCRCPY_SERVER` 指定路径。
+
+### 取色：color
+
+点击 color 获取当前无损画面，移动鼠标查看像素与颜色值。方向键微调 1px，`Shift+方向键` 微调 10px；点击或按 Enter 保存取样。最新记录置顶，每项可单独复制。
+
+刷新或切换画面会清除取样记录。OpenCV HSV 为范围换算值，边界颜色可能存在 1 个单位的舍入差异。
+
+### 截图与文件管理
+
+通过侧栏保存全屏截图，或选中元素后点击“元素截图”。区域截图先点击框选按钮，再拖出选区；可拖动选区、调整八个边角、输入坐标或用方向键微调。保存成功后自动清除选区。
+
+hierarchy / color 截取当前静态画面；remote 全屏截图获取设备当前画面。截图不会包含节点边框。
+
+在“截图”页修改保存目录、查看缩略图、复制或删除文件。**删除会真实移除磁盘文件，操作前会确认；删除全部仅针对当前列表，不递归删除子目录。**
+
+“复制文件”后可在目标文件夹使用系统粘贴快捷键（Windows `Ctrl+V`，macOS `Command+V`）粘贴。“打开目录”直接打开保存位置。这两项需要浏览器和服务运行在同一台电脑；文件剪贴板复制支持 Windows 和 macOS，Linux 暂不支持。
+
+### 录屏
+
+点击侧栏圆形录屏按钮开始，再次点击停止并保存；非 remote 模式会自动连接 remote 后开始录制。
+
+录屏默认保存在用户主目录下的 `UiHound\recordings` 文件夹。“录屏”页支持修改保存目录、播放、复制文件、删除和打开目录。录制内容不包含节点边框；冻结网页画面时仍会录制设备新帧。
+
+切换模式或断开设备会停止并保存录屏。录屏接近 240 MiB 时自动停止。**关闭网页前请等待保存完成**；上传失败可在录屏页重试，强制关闭或刷新会丢失未保存的视频。
+
+## 常用设置
+
+截图和录屏页可选择对应根目录内的子目录。需要更换根目录或调整画质时，在启动前设置环境变量：
+
+```powershell
+$env:UIHOUND_SNAPSHOT_DIR = "D:\UiHoundData\snapshots"
+$env:UIHOUND_RECORDING_DIR = "D:\UiHoundData\recordings"
+$env:UIHOUND_SCRCPY_MAX_SIZE = "1920"
+$env:UIHOUND_SCRCPY_MAX_FPS = "60"
+$env:UIHOUND_SCRCPY_BIT_RATE = "8000000"
+uihound
+```
+
+默认文件位置固定在用户主目录下，不受启动目录或安装目录影响：
+
+| 文件 | Windows | macOS / Linux |
+|---|---|---|
+| 截图 | `%USERPROFILE%\UiHound\screenshots` | `~/UiHound/screenshots` |
+| 录屏 | `%USERPROFILE%\UiHound\recordings` | `~/UiHound/recordings` |
+
+环境变量可覆盖默认根目录。升级前保存的文件不会自动移动或删除；浏览器记住的路径若已不在当前允许的根目录内，会提示并切换到默认目录。
+
+remote 默认最长边 1920、目标 60 fps、码率 8 Mbps；实际流畅度取决于设备与连接状况。
+
+拖动分隔条调整设备、属性和节点树区域，顶部可重置布局。太阳 / 月亮按钮切换主题，浏览器会记住主题和分栏宽度。
+
+## 自动化调用
+
+| 请求 | 参数 |
+|---|---|
+| `GET /device/status` | 设备连接状态 |
+| `GET /snapshot/full` | 可选 `save_dir`、`filename` |
+| `GET /snapshot/element` | 必填 `selector`；可选 `save_dir`、`filename` |
+| `GET /snapshot/region` | 必填 `x1`、`y1`、`x2`、`y2`；可选 `save_dir`、`filename` |
+
+截图接口返回 `success`、`file_path`、`base64`、`timestamp`。`save_dir` 必须位于截图根目录内，`filename` 为 `.png` 文件名；同名文件不会覆盖。
+
+服务用于本机调试，请勿直接暴露到不受信任的网络。

uihound-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "uihound"
+version = "0.1.0"
+description = "Browser-based Android UI inspector for HIL testing"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.110,<1.0",
+    "pydantic>=2.9,<3.0",
+    "pydantic-settings>=2.5,<3.0",
+    "uvicorn[standard]>=0.27,<1.0",
+    "uiautomator2>=3.2,<4.0",
+    "adbutils>=2.0,<3.0",
+    "lxml>=4.9,<7",
+    "Pillow>=10.0,<12.0",
+]
+
+[project.scripts]
+uihound = "uihound.main:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+uihound = ["static/*"]

uihound-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

uihound-0.1.0/src/uihound/__init__.py

@@ -0,0 +1,3 @@
+"""Browser-based Android UI inspector."""
+
+__version__ = "0.1.0"

uihound-0.1.0/src/uihound/config.py

@@ -0,0 +1,34 @@
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="UIHOUND_")
+
+    host: str = "127.0.0.1"
+    port: int = Field(default=8000, ge=1, le=65535)
+    snapshot_dir: Path = Field(default_factory=lambda: Path.home() / "UiHound" / "screenshots")
+    recording_dir: Path = Field(default_factory=lambda: Path.home() / "UiHound" / "recordings")
+    log_dir: Path = Field(default_factory=lambda: Path.cwd() / "logs")
+    open_browser: bool = True
+    screenshot_quality: int = Field(default=90, ge=1, le=100)
+    screen_stream_fps: int = Field(default=12, ge=1, le=60)
+    screen_stream_quality: int = Field(default=80, ge=1, le=100)
+    scrcpy_max_size: int = Field(default=1920, ge=0, le=8192)
+    scrcpy_max_fps: int = Field(default=60, ge=1, le=120)
+    scrcpy_bit_rate: int = Field(default=8_000_000, ge=100_000, le=100_000_000)
+
+
+settings = Settings()
+BASE_DIR = Path(__file__).resolve().parent
+STATIC_DIR = BASE_DIR / "static"
+SNAPSHOT_DIR = settings.snapshot_dir.expanduser().resolve()
+RECORDING_DIR = settings.recording_dir.expanduser().resolve()
+LOG_DIR = settings.log_dir.expanduser().resolve()
+HOST = settings.host
+PORT = settings.port
+SCREENSHOT_QUALITY = settings.screenshot_quality
+SCREEN_STREAM_FPS = settings.screen_stream_fps
+SCREEN_STREAM_QUALITY = settings.screen_stream_quality

uihound-0.1.0/src/uihound/inspection.py

@@ -0,0 +1,123 @@
+"""Bounded, device-scoped screen snapshots used by hierarchy and color modes."""
+
+import base64
+import io
+import re
+import threading
+import time
+import uuid
+from collections import OrderedDict
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+
+from lxml import etree
+from PIL import Image
+from uiautomator2.xpath import PageSource
+
+from .inspector import Inspector
+
+
+@dataclass
+class Inspection:
+    device: Any
+    image: Image.Image
+    xml: str | None
+    hierarchy: dict[str, Any]
+    created: float
+
+
+class InspectionStore:
+    def __init__(self):
+        self._items: OrderedDict[str, Inspection] = OrderedDict()
+        self._lock = threading.Lock()
+
+    def capture(self, inspector: Inspector, with_hierarchy: bool) -> dict[str, Any]:
+        device = inspector.require_device()
+        image = inspector.screenshot().convert("RGB")
+        xml = device.dump_hierarchy() if with_hierarchy else None
+        hierarchy = inspector.hierarchy(xml) if xml is not None else {
+            "elements": [], "tree": None, "empty": True, "node_count": 0,
+        }
+        if inspector.device is not device:
+            raise RuntimeError("设备已切换，请重新获取画面")
+        snapshot_id = uuid.uuid4().hex
+        with self._lock:
+            self._items[snapshot_id] = Inspection(device, image, xml, hierarchy, time.monotonic())
+            while len(self._items) > 8:
+                self._items.popitem(last=False)
+        buffer = io.BytesIO()
+        image.save(buffer, format="PNG")
+        return {
+            **hierarchy, "snapshot_id": snapshot_id,
+            "image": base64.b64encode(buffer.getvalue()).decode("ascii"),
+            "width": image.width, "height": image.height,
+            "captured_at": datetime.now(timezone.utc).isoformat(),
+        }
+
+    def get(self, snapshot_id: str, inspector: Inspector) -> Inspection:
+        with self._lock:
+            item = self._items.get(snapshot_id)
+        if item is None or time.monotonic() - item.created > 1800:
+            raise ValueError("画面快照已过期，请点击刷新")
+        if item.device is not inspector.require_device():
+            raise ValueError("设备已切换，请点击刷新")
+        return item
+
+    def clear(self) -> None:
+        with self._lock:
+            self._items.clear()
+
+    def search(self, snapshot_id: str, query: str, inspector: Inspector) -> list[dict[str, Any]]:
+        item = self.get(snapshot_id, inspector)
+        if item.xml is None:
+            raise ValueError("当前为颜色快照，请点击 hierarchy 获取层级")
+        elements = item.hierarchy["elements"]
+        query = query.strip()
+        if query.startswith(("/", "(")):
+            source = PageSource.parse(item.xml)
+            try:
+                matches = source.root.xpath(query, namespaces={"re": "http://exslt.org/regular-expressions"})
+                if not isinstance(matches, list) or any(not isinstance(node, etree._Element) for node in matches):
+                    raise ValueError("XPath 必须返回元素节点")
+                matched = set(matches)
+                return [
+                    element for element in elements
+                    if any(node in matched for node in source.root.xpath(element["xpath"]))
+                ]
+            except etree.XPathError as exc:
+                raise ValueError(f"XPath 无效：{exc}") from exc
+        selector = Inspector.parse_selector(query)
+        instance = selector.pop("instance", None)
+        if instance is not None and (type(instance) is not int or instance < 0):
+            raise ValueError("instance 必须是非负整数")
+        aliases = {"description": "contentDescription"}
+        def matches(element: dict[str, Any]) -> bool:
+            for key, expected in selector.items():
+                operation = "exact"
+                for suffix in ("Contains", "Matches"):
+                    if key.endswith(suffix):
+                        key, operation = key[:-len(suffix)], suffix
+                        break
+                actual = element.get(aliases.get(key, key), "")
+                if operation == "Contains":
+                    if not isinstance(expected, str):
+                        raise ValueError("Contains 查询值必须是字符串")
+                    if expected not in str(actual):
+                        return False
+                elif operation == "Matches":
+                    if not isinstance(expected, str):
+                        raise ValueError("Matches 查询值必须是字符串")
+                    try:
+                        if not re.fullmatch(expected, str(actual)):
+                            return False
+                    except re.error as exc:
+                        raise ValueError(f"正则表达式无效：{exc}") from exc
+                elif actual != expected:
+                    return False
+            return True
+        found = [element for element in elements if matches(element)]
+        return found if instance is None else found[instance:instance + 1]
+
+
+inspections = InspectionStore()