feat(rtos): 安装前补传PNG图标并等待成功回调

2026-11-14 18:07:35 +08:00
@@ -0,0 +1,50 @@
+# 安装前补传桌面 PNG 图标（0.3.0）
+
+适用于本调试桥的 OPPO Watch S / S2 Glyphix 安装路径。手机 APK 为 0.3.0 / versionCode 4，Android 最低 API 27；探针保持 1.0.4。保留原有非商业许可与第三方声明。
+
+## 固定顺序
+
+```text
+读取 .pkg 的 CR 资源表与 manifest → 获取实际包名、icon 资源
+  ↓
+解码并等比例缩小为最长边 ≤192 的标准 PNG
+  ↓
+发送文件名 <包名>.png，目标 /user/jsapps/<包名>.png
+  ↓
+等待文件通道终态成功，并确认 JSON 数字 code == 200
+  ↓
+发送并安装 .pkg（remote://mass/bridge_<作业ID>.pkg）
+```
+
+`/user/jsapps/` 是 Glyphix 虚拟文件系统路径。设备资料中对应底层 `/user_data/gx/user/jsapps/`；传输参数始终使用前者，手机不写底层路径。传输复用已经绑定的 Wear Engine 文件通道：263 为 transaction 15，旧接口为 12，参数为只读文件描述符、文件名、目标路径、appId、回调。安装使用 263/16 或旧版/15。
+
+图标进度回调、100% 进度、Binder 调用正常返回都不构成图标已送达。只有终态成功回调中的数字 `code=200` 才继续；失败、缺少 code、字符串 code、异常、超时、断开连接均不会开始包安装。重复或旧会话图标回调不会重复触发安装。包安装自己的最终回调单独决定整个作业是否成功；图标送达不等于应用已安装。
+
+## PNG 与 PGF
+
+`.png` 后缀不代表内容真为 PNG。厂商打包工具会将包内 `assets/icon.png` 转为 `PGF\0`。手机使用 Android 图片解码器识别内容，等比例缩小后重新编码 PNG，不通过改扩展名伪装转换。输入上限 4 MiB、4096×4096；不会拉伸成正方形或放大小图。
+
+- 包内可解码图像：直接生成 PNG。
+- 包内 PGF：PC 优先读取同一 `dist/<设备>/<包名>/icon.png`；可通过 `--icon` 明确指定该应用对应的 PNG。手机单独选 PKG 时会提示再选本包的 PNG，选完才开始作业。
+- 没有对应 PNG、图片损坏或资源表不受支持：安装失败并保留具体原因。支持当前实测 CR 容器、JSON 清单与编译清单 v1；未知格式拒绝安装。
+- 外部图标无法仅凭像素证明归属，请使用同一次构建的完整 dist。不会复用其他应用上一次选过的图标，也不自动使用商店网络图片或通用占位图。
+
+## 使用
+
+```powershell
+# 保留完整 dist 三文件；自动配合同目录 icon.png。
+python bridge.py --serial YOUR_PHONE_SERIAL install 'downloads/dist/<设备>/<包名>/bundle.pkg'
+
+# 包与对应 PNG 分开保存时显式指定。
+python bridge.py --serial YOUR_PHONE_SERIAL install 'downloads/bundle.pkg' --icon 'downloads/my-app-icon.png'
+```
+
+手机端点也支持 `{"command":"install","file":"<已上传PKG名>","iconFile":"<已上传PNG名>"}`；`iconFile` 可省略，此时必须能解码包内图像。`verify.py --probe` 使用同一流程。作业事件 `install.stage` 依次记录 `prepare_icon`、`send_icon`、`install_package`；生成 PNG 和 PKG 快照互相独立，并在终态、断开或超时后清理。常规上传缓存仍可用 `cleanup` 清理。
+
+263 文件通道需要与目标应用匹配的 appId/license 互联授权。默认 `test/test` 是演示值，不能保证授权；授权未完成会停止并说明包尚未发送。保留现有配对和认证，不设置 `authentication_state`，不调用参考项目的 ftprobe 认证旁路。
+
+## 验证边界
+
+本版新增 Android 原生编解码与 Binder 顺序测试；测试使用显式模拟手表端点，不会写实体手表。当前构建的真实 Glyphix 探针包另作解析样本。具体执行结果见 [本版验收](ICON_VALIDATION_2026-11-14.md)。
+
+S2 既有的应用安装、官方截图和前台亮屏证据属于旧安装路径，不能证明新图标通道已送达。收到真实 `code=200` 后仍须在手表桌面核对实际图标；若固件有图标缓存，可记录重新打开桌面或由用户重启后的结果。工具不自动重启手表，不承诺所有固件立即刷新，也不把上传成功等同桌面显示成功。