172 行
11 KiB
Markdown
172 行
11 KiB
Markdown
# RTOS 手表真机调试桥
|
||
|
||
通过 Android 手机上已配对的 Wear Engine 服务，让电脑安装 Glyphix 手表应用、查询设备、采集官方截图，并开展有证据的 UI 验证。适合已经拥有合法配对设备、希望反复安装和验收自己手表应用的开发者。
|
||
|
||
**源码公开 · PolyForm Noncommercial 1.0.0 · 仅限许可允许的非商业用途。** 商业用途须另获许可。完整条款见 [LICENSE](LICENSE)，版权及第三方条款见 [NOTICE.md](NOTICE.md)。
|
||
|
||
当前发布：**手机桥 0.2.0 / versionCode 3**，配套探针 **1.0.4 / 10004**。这是开发测试版，APK 安装到手机；手表安装 `bundle.pkg`。已测组合为 P30PRO + OPPO Watch S2 / OWW265，其他型号和固件需自行验收。
|
||
|
||
|
||
|
||
上图是 S2 官方截屏导出，用户手动触摸后计数变为 1；画面中的“待实测”是每次运行的请求状态文案。本次另外完成了实体观察：无触摸静置至少 159 秒后仍亮屏。两者均不能替代通用远程输入验证。
|
||
|
||
## 下载和反馈
|
||
|
||
- [发布页：APK、探针包、源码与完整工具包](https://git2.sydxky.cn/sydxky/rtos-watch-debug-bridge/releases)
|
||
- [已有问题与建议](https://git2.sydxky.cn/sydxky/rtos-watch-debug-bridge/issues)
|
||
- [免注册提交问题与建议](https://git2.sydxky.cn/feedback/sydxky/rtos-watch-debug-bridge)
|
||
- [完整操作说明](phone-debug-bridge/README.md) · [真机验收记录](docs/VALIDATION.md) · [隐私与安全](docs/PRIVACY.md)
|
||
|
||
Git2 允许免登录浏览、克隆和下载，当前关闭注册，由所有者维护代码与发行版。
|
||
|
||
```powershell
|
||
git clone https://git2.sydxky.cn/sydxky/rtos-watch-debug-bridge.git
|
||
cd rtos-watch-debug-bridge
|
||
```
|
||
|
||
## 工作方式
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
PC[电脑 bridge.py / ui.py] -->|已授权 ADB forward| APK[手机调试桥：回环认证 API]
|
||
APK -->|bindService + Binder.transact| WE[手机运动健康 Wear Engine]
|
||
WE -->|厂商配对传输| WATCH[S2 / Glyphix 应用]
|
||
PC -->|正常导航手机健康 UI| SHOT[官方手表截屏并导出]
|
||
```
|
||
|
||
RTOS 手表不需要 Android ADB。手机必须先在受支持的官方配套应用中正常配对，桥接工具不会替你完成配对，也不会绕过系统安装确认或厂商消息授权。
|
||
|
||
## 能力与实测范围
|
||
|
||
| 能力 | 当前结果 |
|
||
| --- | --- |
|
||
| 手机 APK 安装、回读 hash、Binder 绑定 | P30PRO 已通过 |
|
||
| 等待手表上线、查询型号及运行时版本 | S2 已通过；OWW265 / runtime 0.8.0-5 |
|
||
| Glyphix 应用检查、安装 | S2 探针 1.0.4 已实装，回调成功并显示实际页面 |
|
||
| 官方手表截屏 | 电脑导航健康界面并导出 480×464 JPEG，已通过 |
|
||
| 图片导入、原比例预览、安全区辅助线、PNG 导出校验 | 手机已通过 |
|
||
| 手表探针手动触摸 | 官方截图确认计数 0→1，已通过 |
|
||
| 探针内前台调试常亮 | 1.0.4 静置至少 159 秒后，截图及用户实体观察通过 |
|
||
| 手机控件树、点击、滑动和步骤报告 | 支持，作用于 Android 手机 |
|
||
| Inspector 控件检查、点击和截图 | 圆/方原生模拟器通过；真机隧道尚未打通 |
|
||
| S2 通用远程点击/滑动 | 尚未打通 |
|
||
| 远程打开手表应用到前台 | 回调 200 仍可能停在表盘，目前需手动从图标进入 |
|
||
| READY/TAP JS console、自动测试 RPC | 未通过；部分 RPC 返回 3000 |
|
||
| 消息和文件互联 | 需要匹配 appId/license，默认 test/test 不构成授权 |
|
||
|
||
`phone`、`watch-health`、`watch-import`、`inspector` 必须显式选择，避免把手机或模拟器结果误认为 S2 真机证据。
|
||
|
||
## 开始使用
|
||
|
||
准备 Windows PowerShell 7、Python 3（标准库即可）、Android platform-tools，并将 `adb` 放入 PATH。先把 P30PRO 与 S2 在运动健康中正常配对，解锁手机并让手表唤醒。
|
||
|
||
1. 从发布页下载 APK，安装到 **Android 手机**；华为手机可能需要本机点击“继续安装”。
|
||
2. 在手机开启并授权 USB 调试，运行 `adb devices -l`，确认手机序列号。也可使用自己已授权的网络 ADB；地址会变化。
|
||
3. 打开运动健康，等待手表连接。多设备环境始终指定手机 `--serial`。
|
||
4. 在仓库的 `phone-debug-bridge` 目录运行：
|
||
|
||
```powershell
|
||
$phone = 'YOUR_PHONE_SERIAL'
|
||
adb -s $phone install -r '..\downloads\RTOS-Phone-Bridge-0.2.0-debug.apk'
|
||
python bridge.py --serial $phone connect
|
||
python bridge.py --serial $phone wait-link --seconds 45
|
||
python bridge.py --serial $phone info
|
||
python ui.py --target watch-health --serial $phone screenshot --output artifacts/s2.jpg
|
||
```
|
||
|
||
将示例 APK 路径改为自己的实际下载位置。也可用 `bridge.py setup --apk <文件>` 安装并启动桥。手机上仅监听 `127.0.0.1:18765`，PC 经 `adb forward` 访问，令牌由工具通过已授权 ADB 读取，不需要手动复制。
|
||
|
||
### 安装并验证探针
|
||
|
||
解压发行版 `S2-DeviceProbe-1.0.4-dist.zip`，保留每种屏幕完整的 `bundle.pkg`、`manifest.json`、`icon.png`。S2 本轮使用圆屏配置：
|
||
|
||
```powershell
|
||
python bridge.py --serial $phone install '..\downloads\dist\generic-watch-466x466-quickapp\com.sydxky.rtos.deviceprobe\bundle.pkg'
|
||
python bridge.py --serial $phone check com.sydxky.rtos.deviceprobe
|
||
python bridge.py --serial $phone launch com.sydxky.rtos.deviceprobe
|
||
```
|
||
|
||
启动返回成功后仍需检查实际画面。若仍是表盘，请在手表图标列表打开“真机链路验证”。页面显示版本、常亮请求状态、点击次数和按钮；手动点一下再截图，核对计数变化。
|
||
|
||
1.0.4 使用 `setKeepScreenOn(true)` 配合 `wakeScreenOn({screenOn:true})` 前台 15 秒续期；隐藏/销毁停止续期并释放。它没有永久改写系统设置，不保证所有固件或系统覆盖界面下都常亮。退出探针即可结束应用内调试常亮。
|
||
|
||
### 截图和 UI 检查
|
||
|
||
`watch-health` 正常进入运动健康“设备 → 更多功能 → 手表截屏”，读取本次生成的官方公开图片；不会在失败时拿手机截图冒充手表图。手机图片检查页可通过系统文件选择器导入截图、显示圆屏安全区、导出 PNG。
|
||
|
||
```powershell
|
||
python ui.py --target phone --serial $phone tree --output artifacts/phone.tree.json
|
||
python ui.py --target phone --serial $phone screenshot --output artifacts/phone.png
|
||
python ui.py --target watch-import --serial $phone screenshot --output artifacts/imported.png
|
||
```
|
||
|
||
后两种图必须按来源解释：手机截图属于手机；任意导入图片本身不构成手表身份背书。JPEG 转 PNG 会改变字节和 SHA-256。步骤 JSON 的 `click`、`scroll`、`assert-visible`、`screenshot` 示例见 [examples](phone-debug-bridge/examples)。
|
||
|
||
## 从源码构建
|
||
|
||
仓库包含手机工程、PC 工具、探针及测试，不含厂商 SDK、Android SDK、JDK 或健康 APK。
|
||
|
||
### 手机 APK
|
||
|
||
需要 JDK 17、Android SDK Platform 35 及对应 Build Tools。工程使用 Gradle 8.13、AGP 8.13.1，minSdk 27 / targetSdk 34 / compileSdk 35。
|
||
|
||
```powershell
|
||
cd phone-debug-bridge
|
||
.\build.ps1 -JavaHome 'C:\path\to\jdk17' -AndroidSdk 'C:\path\to\Android\Sdk'
|
||
python -m unittest discover -s tests -v
|
||
```
|
||
|
||
APK 输出 `phone-debug-bridge/artifacts/RTOS-Phone-Bridge-0.2.0-debug.apk`。这是 Android Debug 签名工具，不是商店上架包；自行构建会使用自己的 debug 证书，与作者发布版可能不同。
|
||
|
||
### Glyphix 探针
|
||
|
||
自行按厂商许可取得完整 Windows Glyphix SDK，将含 `bin/gx.exe` 和 `share/` 的 SDK 放在仓库根 `temp/glyphix-v0.7.2-windows-x64/`。本次验证 CLI v0.10.1 / 3ed38835，目录名保留历史命名；不要仅凭目录名判断实际版本。
|
||
|
||
```powershell
|
||
cd com.sydxky.rtos.deviceprobe
|
||
node --test tests/screen-lifecycle.cjs
|
||
.\build.ps1 -QuickAppOnly
|
||
```
|
||
|
||
输出在 `.glyphix-work/dist/generic-watch-466x466-quickapp/` 和 `generic-watch-390x450-quickapp/`，每屏必须保留完整三个文件。这些是 Glyphix QuickApp，不是 APK 或 HAP。
|
||
|
||
原生 UI 验收需厂商模拟器和初始化的 global/launcher 镜像。先按官方教程构建普通探针镜像并初始化模拟器资源，再显式提供 `--seed`：
|
||
|
||
```powershell
|
||
python phone-debug-bridge/tests/native_ui.py --seed 'C:\path\to\initialized-image' --output work/native-ui
|
||
```
|
||
|
||
脚本拒绝占用中的 Inspector 14201，只终止自己启动的模拟器。相关资源不会随源码分发。完整路径、工具链及测试边界见[工程说明](phone-debug-bridge/README.md)。
|
||
|
||
## 发布文件
|
||
|
||
| 文件 | 内容 |
|
||
| --- | --- |
|
||
| `RTOS-Phone-Bridge-0.2.0-debug.apk` | 手机 APK，安装到 P30PRO 等 Android 手机 |
|
||
| `S2-DeviceProbe-1.0.4-dist.zip` | 圆/方各三文件，安装 bundle.pkg 到手表 |
|
||
| `RTOS-Phone-Bridge-0.2.0-source.zip` | 独立源码、构建脚本、完整许可和文档 |
|
||
| `RTOS-S2-DebugKit-0.2.0.zip` | APK、探针、源码、文档及脱敏证据 |
|
||
| `SHA256SUMS.txt` / `KIT-SHA256.txt` | 逐文件与完整工具包校验 |
|
||
|
||
APK SHA-256：`316221A6751C9ED8A23BD1FA4381F8AA35620AB1A85123468F8DD04811F880E0`。
|
||
|
||
可用 `Get-FileHash -Algorithm SHA256 <文件>` 对照发布校验表。发布附件中包含 LICENSE、NOTICE 及第三方许可，使用和再分发遵守各自条款。
|
||
|
||
## 常见问题
|
||
|
||
**Binder 已绑定但手表不在线：** 先在健康确认已连接，再执行 `wait-link`；绑定成功早于蓝牙重连。`bind_rejected` 时先正常打开已配对的健康。
|
||
|
||
**请求超时或返回 3000：** 先查同一个作业的实际结果，不要自动重复安装。已有一次会话通过保留配对数据重启健康并等待上线恢复，但内部根因尚未确定。
|
||
|
||
**安装回调成功却找不到应用：** 从图标列表检查实际入口，结合官方截图核实。回调 200 不代表远程调至前台。
|
||
|
||
**截图无法导出：** 当前适配健康 6.10.15 的公开截图目录和 JPEG 编号规则；其他版本可能需要重新适配。手机锁屏时先在本机解锁，不绕过锁屏。
|
||
|
||
**为什么没有通用手表遥控：** 当前接口没有取得可验证的真机通用触摸或 Inspector 隧道。手机 ADB 输入和模拟器自动化不会被计为 S2 遥控成功。
|
||
|
||
结束调试：先 `logs off`（若开启过），再执行 `disconnect`、`cleanup`、`stop`，并退出手表探针。清理只删除调试桥上传缓存，不删除健康配对、用户图片或其他应用数据。
|
||
|
||
## 参考与许可
|
||
|
||
参考 [Glyphix 教程](https://docs.xfaith-tech.com/glyphix/docs/tutorials/)、[亮度接口](https://docs.xfaith-tech.com/glyphix/docs/api/system-brightness.html)、[测试框架](https://docs.xfaith-tech.com/glyphix/docs/api/system-test.html) 和 [oppo-watch-s-sideload](https://github.com/chengchengking/oppo-watch-s-sideload)。本项目独立实现手机桥和 PC 工具，保留上游 MIT 署名；厂商 SDK 和第三方构建工具不受本项目自研部分许可重新授权。完整声明见 [NOTICE.md](NOTICE.md)。
|