# 盒子桌面安装说明（给 AI Agent）

你在帮用户把 **盒子桌面**（包名 `com.hzzm.app`）装到 Android 电视上，并让它成为开机进入的桌面。整个过程通过电脑上的 adb 完成，电视不需要 root。盒子桌面要求 **Android 5.0+**（SDK ≥ 21）；更老的系统不支持（没有 Lite 包）。

## 下载地址从哪来（必须遵守）

**本说明故意不写死 APK URL**（后台一发版就变）。安装包只认下面两种来源，**不要**用 Aerial 官网（aerial.qust.me）、GitHub 或网上搜到的旧包：

1. **用户提示词里的两行**（首页 / 盒子桌面页「安装与升级提示词」自动填好的，同源后台 `app.app_nurl`）：
   - `优先安装（standard…）：https://…` → `<APK_URL_STANDARD>`（应用 **10001**）
   - `备用安装（guard…）：https://…` → `<APK_URL_GUARD>`（应用 **10004**）
2. **用户自己点的按钮**：https://box.nihaohezi.com/ （或 `?bbs&cat=1`）顶部 **「下载 standard」/「下载 guard」**，把链接贴给你。和提示词、应用内 `act=ini` 更新是同一条 `app_nurl`。

跑 `install.sh` 时**必须**带 `APK_URL=<上面对应的链接>`。没有 URL 就请用户重新复制提示词或点下载按钮，不要猜、不要用 `templates/app-*-release.apk` 之类过期路径。

### 本站工具（已本地化，不要去 aerial.qust.me 拉）

脚本都在 **https://box.nihaohezi.com/extend/plugins/zhuomian/tools/**（对应服务器目录 `www/extend/plugins/zhuomian/tools/`）：

| 文件 | 用途 |
|---|---|
| `install.sh` | 安装 / 授权 / 接管；`bash -s standard\|guard\|repair`；远程执行时务必 `APK_URL=…`；Android 11+ 无线调试支持 `ADB_PAIR`/`ADB_CODE`/`ADB_CONNECT` |
| `restore.sh` | 还原桌面接管；可加 `--uninstall` |
| `report.sh` | 只读诊断，生成 `aerial-report-<机型>.md` |
| `selftest.sh` | 主页键 / 守护自检，生成 `aerial-selftest-<机型>.md`（可选 `STANDBY=1` / `REBOOT=1` / `INPUTS=1`） |
| `perf.py` | 帧耗时剖析（配合 ConfigReceiver `skip_layers` 等） |
| `tcast-push.py` | TCL 多屏互动推送（Windows 手装时用） |
| `get.sh` | **已停用**远程一键；会提示改用 `install.sh` + `APK_URL` |
| `index.html` | 浏览器打开本目录时的文件说明 |
| `make-cities.py` / `icon-library.py` / `render-brand.py` / `qr-from-screenshot.swift` | 站点/资源构建用，**装电视时不要跑** |
| `tvs.env.example` | 本机多台电视 IP 示例，勿提交密钥 |

一行命令示例：`curl -fsSL https://box.nihaohezi.com/extend/plugins/zhuomian/tools/install.sh | APK_URL=<APK_URL> KEEP_ADB=1 TV=<IP> bash -s standard`

## 选哪个包（必须遵守）

两个包**包名相同**（都是 `com.hzzm.app`），差别只在是否声明桌面：

| 版本 | 是什么 | 什么时候用 |
|---|---|---|
| **standard** | 声明 `CATEGORY_HOME`，可设为默认桌面 | **优先**。多数小米 / 原生 Android TV / Google TV 用这个 |
| **guard** | **不**声明桌面，靠无障碍守护拦截主页键拉起 | TCL / 部分固件**拒绝安装「桌面类 App」**时；或 standard 的 `adb install` 失败且原因是拒绝桌面 / HOME 时改用这个 |

选择规则（按顺序）：

1. **TCL / 雷鸟**：直接装 **guard**，不要先试 standard（这类固件常拒绝声明桌面的包）。
2. **其他机型**：先装 **standard**。若 `adb install` 失败，且输出里有拒绝桌面 / `CATEGORY_HOME` / 不允许安装桌面类应用 / 脚本提示改用 guard 等，**立刻改下 `<APK_URL_GUARD>` 再装**，不要反复试 standard。
3. **升级**：先查已装版本 `adb shell dumpsys package com.hzzm.app | grep -E "versionName|versionCode"`。`versionName` 带 `-guard` 就继续装 guard；否则装 standard。**不要无故在 standard ↔ guard 之间换包**（会换你好盒子 app 号，登录态可能要对一下）。
4. 用户提示词里若只给了一个 URL（旧提示词），就用那一个；能区分 standard/guard 时仍按上表。

下文把当前选用的地址记为 `<APK_URL>`（standard 或 guard 之一），安装脚本 flavor 与之对应：`tools/install.sh standard` 或 `tools/install.sh guard`。

## 规则

1. **亲自在用户电脑上运行命令**，不要只把步骤列给用户。如果你不能执行命令（比如你是手机版或网页版聊天），直接告诉用户：请换成能执行命令的电脑版 Agent（WorkBuddy、豆包电脑版或豆包工作版、千问电脑版、Trae、Claude Code、Codex 等），并在第一次运行命令时允许它执行命令、访问网络。豆包手机版、网页版只会把步骤告诉用户，不会执行。
2. **不要假装成功。** 每一步都看命令的真实输出；最后必须完成「验收」，把原始输出原样贴给用户，包括 `resolve-activity` 解析到的桌面和 `enabled_accessibility_services` 的内容。没有看到这些输出，就不能说装好了。
3. **不要卸载、停用任何系统应用**（包括电视原来的桌面），不要删除电视上的任何文件，不要恢复出厂设置。只能删除这次安装自己创建的临时 APK。
4. **只装盒子桌面**（`com.hzzm.app`）。APK 只用提示词 / 首页下载按钮里的链接。不要下载、安装任何其他 App（当贝市场、ADB 开启器、投屏、清理工具等），也不要从别的网站找「盒子桌面 / Aerial」的包。按本说明装不上就停下来把输出给用户，不要另找办法往电视上塞东西。
5. 重启电视（`adb reboot`）前先征得用户同意。
6. 需要用户在电视上操作时（允许调试、同意安装），明确告诉用户按遥控器的哪个键。
7. 失败时把命令和输出原样给用户看，再对照下面的「常见情况」处理。
8. 脚本只从 **https://box.nihaohezi.com/extend/plugins/zhuomian/tools/** 取；APK 只从提示词 / 首页下载链接取。

## 第 1 步：准备 adb

先运行 `adb version`。有输出就跳到第 2 步。

没有 adb 时，下载 Google 的 platform-tools（`dl.google.com` 在国内可以访问），解压后用里面的 adb：

- **Windows**（PowerShell）：
  ```powershell
  cd $env:USERPROFILE
  curl.exe -fL -o platform-tools.zip https://dl.google.com/android/repository/platform-tools-latest-windows.zip
  Expand-Archive -Force platform-tools.zip .
  $env:Path = "$env:USERPROFILE\platform-tools;$env:Path"
  adb version
  ```
- **macOS**：`brew install android-platform-tools`；没有 Homebrew 时可以跳过，第 3 步的一行命令会自己下载 adb。
- **Linux**：用系统的包管理器装 `adb` 或 `android-tools`；或者跳过，第 3 步的一行命令会自己下载。

## 第 2 步：连接电视

电脑和电视要在同一个网络。用户给你的电视 IP 记为 `<IP>`。

```
adb connect <IP>:5555
adb devices
```

`adb devices` 里这台电视后面是 `device` 才算连上。

- **`unauthorized`**：电视上弹出了「允许 USB 调试吗？」，请用户选「允许」并勾选「始终允许」，再运行一次 `adb devices`。
- **`failed to connect` / `Connection refused` / 超时**：电视的 ADB 调试没打开，或 IP 不对。让用户按下表打开，再试。
- **5555 连不上、电视里只有「无线调试」没有 USB 调试**（索尼 BRAVIA Android 14、部分 TCL Android 11+ 等）：要先配对。让用户打开 开发者选项 → 无线调试 → **使用配对码配对设备**，要来两组「IP:端口」和 6 位配对码——一组在配对码屏幕上，一组在无线调试主屏幕上（**两个端口不一样**，每次进页面都会变）。然后：
  ```
  adb pair <配对屏IP:端口> <配对码>
  adb connect <主屏IP:端口>
  adb devices
  adb tcpip 5555
  adb connect <IP>:5555
  ```
  以后一般不用再配对。本站 `install.sh` 已支持：交互输入，或先设 `ADB_PAIR=<ip:端口> ADB_CODE=<配对码> ADB_CONNECT=<ip:端口>` 再跑。部分 TCL（Q10M、鹤 7 Pro 等无配对码入口）只能用 **USB 数据线**连电脑执行一次 `adb tcpip 5555`。

| 电视 | 怎么打开 ADB |
|---|---|
| 小米 / Redmi | 设置 → 关于 → **产品型号**，连续按确认键，直到提示进入开发者模式。再到 设置 → 账号与安全，打开 **ADB 调试** 和 **安装未知来源的应用** |
| TCL / 雷鸟 | 设置 → 关于 → **本机信息**，依次按遥控器 **上、下、左、右**（间隔不超过 1 秒），底部出现「更多」，在里面打开 **ADB** |
| OPPO 电视（含 S1） | 设置 → 系统 → 关于本机 → **设备型号**，依次按 **上、上、右、右**，再按确认；然后到 设置 → 系统 → **开发者选项**，打开 **USB 调试**（有的机型叫 ADB 调试）。用户反馈；ColorOS TV 在 OPPO K9 上验证过 |
| 海尔 / 模卡（MOOKA） | 按**电视机身**上的信号源键，弹出信号源菜单后，用遥控器依次按 **左、左、上、右**，进入「海尔工厂菜单」，把 **ADB 调试开关** 设为开（有的机型在第二页 Other Option → adb debug）。只改这一项，别动其他选项，尤其不要选「工厂复位」。（ZNDS 用户反馈，模卡 U65H3 等，未验证） |
| 极米 H3 | 设置里没有开发者选项。请用户在手机上下载第三方 ADB 开启器 APK，用极米手机 App 上传并安装，打开一次。**不要代用户下载或运行该工具**。5555 显示 `device` 后再继续 |
| 极米 Z7X | 设置里没有开发者选项。请用户**自己**用 U 盘装第三方 ADB 开启器并打开一次。**不要代用户下载或安装**这类工具；5555 显示 `device` 后再继续 |
| 原生 Android TV / Google TV、索尼、海信等 | 设置 → 设备偏好设置 → 关于 → 连续按 **内部版本号**（Build，不是「Android 版本」，按错了会出彩蛋，按返回键退出即可）7 次，再到开发者选项打开 **USB 调试**（也可能叫「网络调试」） |

电视的 IP 一般在 设置 → 网络 → 已连接的网络 里（OPPO S1 在这一页最下面）。

**打不开 ADB 的机型**：老乐视、荣耀智慧屏、老康佳（看不到版本号）等，目前没有办法就直接告诉用户不支持，不要反复尝试，也不要代装第三方开启器。

**用户没有电脑**：有用户用手机上的「甲壳虫 ADB 助手」「超级小爱」装成功过，本项目没有逐一实测。可以让用户照本说明第 2、3 步在手机上操作（手机 ADB 工具一般不能执行全部命令），装好后尽量再用电脑或你跑一遍「验收」。

## 第 2½ 步：确认系统版本

```
adb shell getprop ro.build.version.sdk
adb shell getprop ro.build.version.release
```

- **SDK ≥ 21**（Android 5.0+）：继续第 3 步。
- **更低**：不支持，告诉用户盒子桌面最低 Android 5.0，停止安装。
- **没有输出**：先查连接（`adb devices` 是否为 `device`），不要猜版本。

## 第 3 步：安装

按上面「选哪个包」定好 `<APK_URL>` 和 flavor（`standard` 或 `guard`）。也可以本仓库本地编译（**不要**从 Aerial 官网 / GitHub 下载）。

### macOS / Linux（一行命令，无需仓库）

```bash
# 多数电视：standard
curl -fsSL https://box.nihaohezi.com/extend/plugins/zhuomian/tools/install.sh | APK_URL=<APK_URL_STANDARD> KEEP_ADB=1 TV=<IP> bash -s standard
# TCL，或 standard 装不上：改用 guard
# curl -fsSL https://box.nihaohezi.com/extend/plugins/zhuomian/tools/install.sh | APK_URL=<APK_URL_GUARD> KEEP_ADB=1 TV=<IP> bash -s guard
```

安装脚本从盒子桌面服务器下（https://box.nihaohezi.com/extend/plugins/zhuomian/tools/ ）；**APK 必须用提示词里的 URL**。有仓库 checkout 时也可：`cd <本仓库根目录> && APK_URL=<APK_URL> KEEP_ADB=1 TV=<IP> tools/install.sh standard`（或 `guard`）；本地编译：`BUILD=1 KEEP_ADB=1 TV=<IP> tools/install.sh`（默认 standard）或 `… tools/install.sh guard`。

- **TCL** 会走多屏互动推送：请用户看电视上提示，**先按遥控器「右」选中「同意」，再按确认**。请直接用 **guard**。

跑完后去做「验收」。

### Windows：逐条运行

在 PowerShell 里运行（`adb` 是第 1 步准备好的）。先按「选哪个包」下载对应 APK：

```powershell
# 多数电视：standard
curl.exe -fL -o hzzm-standard.apk "<APK_URL_STANDARD>"
# TCL / standard 装不上：
# curl.exe -fL -o hzzm-guard.apk "<APK_URL_GUARD>"

# 或本机编译
# .\gradlew assembleStandardRelease   → app\build\outputs\apk\standard\release\app-standard-release.apk
# .\gradlew assembleGuardRelease      → app\build\outputs\apk\guard\release\app-guard-release.apk
```

或（Git Bash / WSL）：`APK_URL=<APK_URL> KEEP_ADB=1 TV=<IP> bash <(curl -fsSL https://box.nihaohezi.com/extend/plugins/zhuomian/tools/install.sh) standard`（或 `guard`）。

1. 安装：`adb install -r hzzm-standard.apk`（或 `hzzm-guard.apk`），输出 `Success` 继续。失败时：
   - 正在装 **standard**，且固件拒绝桌面类 App / 脚本提示改用 guard：改下 **guard** 包再装，从本步重来。
   - 输出里有 **`INSTALL_FAILED_DUPLICATE_PERMISSION`** 且提到 `launcher categories` / `App installation is banned`（常见 OPPO）：改用 **guard**。
   - 输出里有 **`INSTALL_FAILED_VERIFICATION_FAILURE`**：这是 TCL，按下面「TCL 安装」处理（用 **guard**），装好后从第 3 条继续。
   - 输出里有 **`INSTALL_FAILED_USER_RESTRICTED`**（创维等）：见「常见情况」里的创维一条，处理后再装。
   - 其他失败：把失败输出记下来，先看「常见情况」再处理。

2. 授予只有 adb 能给的权限（某条报错可以忽略，继续下一条）：
   ```
   adb shell pm grant com.hzzm.app android.permission.ACCESS_FINE_LOCATION
   adb shell pm grant com.hzzm.app android.permission.WRITE_SECURE_SETTINGS
   adb shell appops set com.hzzm.app SYSTEM_ALERT_WINDOW allow
   adb shell appops set com.hzzm.app WRITE_SETTINGS allow
   adb shell appops set com.hzzm.app REQUEST_INSTALL_PACKAGES allow
   adb shell appops set com.hzzm.app GET_USAGE_STATS allow
   adb shell appops set com.hzzm.app android:get_usage_stats allow
   adb shell cmd notification allow_listener com.hzzm.app/com.hzzm.app.guard.RevivalListener
   adb shell appops set com.hzzm.app APP_AUTO_START allow
   adb shell appops set com.hzzm.app APP_ASSOC_START allow
   adb shell appops set com.hzzm.app AUTO_START allow
   adb shell appops set com.hzzm.app ASSOC_START allow
   ```
   最后四条 `appops` 只有 TCL / 雷鸟认（不同固件认其中两条），别的电视报错是正常的。

   再启动一次盒子桌面，等 5 秒后编译（要几十秒，让盒子桌面在电视上更流畅；有的电视要先启动过一次，编译才有效）：
   ```
   adb shell am start -W -n com.hzzm.app/.MainActivity
   adb shell cmd package compile -m speed -f com.hzzm.app
   ```

4. 屏保：运行 `adb shell settings get secure screensaver_enabled`。结果是 `1` 时再运行：
   ```
   adb shell settings put secure screensaver_components com.hzzm.app/com.hzzm.app.dream.AerialDream
   adb shell am broadcast -a com.hzzm.app.CONFIG -n com.hzzm.app/.guard.ConfigReceiver --ez own_screensaver true
   ```

5. 保持 ADB 常开（用户同意时；小米待机唤醒后会自己关掉 ADB，开了这项以后升级更方便）：
   ```
   adb shell am broadcast -a com.hzzm.app.CONFIG -n com.hzzm.app/.guard.ConfigReceiver --ez keep_adb true
   ```

6. 启动盒子桌面：`adb shell am start -W -n com.hzzm.app/.MainActivity`，输出里要有 `Status: ok`。

7. 设为默认桌面（装的是 guard 版时跳过）：
   ```
   adb shell cmd role add-role-holder --user 0 android.app.role.HOME com.hzzm.app
   ```
   报错时改用 `adb shell cmd package set-home-activity --user 0 com.hzzm.app/.MainActivity`。小米、TCL 等固件会无视这一步，没关系，下一步的桌面守护会接管。

   **海信 VIDAA**：先运行 `adb shell getprop persist.vt.use_home_pkg`。有输出（比如 `com.jamdeo.tv.vod`）且不是 `com.hzzm.app` 时，记下原值并改成盒子桌面：
   ```
   adb shell settings put global aerial_vt_home_pkg <原值>
   adb shell setprop persist.vt.use_home_pkg com.hzzm.app
   ```
   没有输出就跳过，其他电视没有这个属性。

8. 桌面守护：盒子桌面启动时会自己打开它。运行 `adb shell settings get secure enabled_accessibility_services`，结果里应该有 `com.hzzm.app/com.hzzm.app.guard.HomeGuardService`。没有时手动加上，**保留原来的内容**，用冒号连接：
   ```powershell
   adb shell "settings put secure enabled_accessibility_services '<原来的值>:com.hzzm.app/com.hzzm.app.guard.HomeGuardService'"
   adb shell settings put secure accessibility_enabled 1
   ```
   原来的值是 `null` 或空时，只写 `com.hzzm.app/com.hzzm.app.guard.HomeGuardService`。在 PowerShell 里，原来的值中如果有 `$`，要写成 `` `$ ``。

   有的固件上 `settings` 命令会卡住不返回（腾讯极光盒子 6 / Q5043，等 120 秒后断开）：那就跳过这一步，改用 `adb shell dumpsys accessibility` 看 `Enabled services` 里有没有盒子桌面，盒子桌面拿到授权后会自己打开守护。

### TCL 安装（adb 装不上时）

TCL 只能通过电视自带的「多屏互动」安装，**必须用 guard 版**（不要装 standard）。macOS / Linux 的一行命令会自动处理，Windows 上需要 Python 3（`python --version`；没有就让用户先装 Python）：

```powershell
# 用用户提示词「备用安装（guard…）」的地址；推送脚本仍从盒子桌面服务器取
curl.exe -fL -o Aerial.apk "<APK_URL_GUARD>"
curl.exe -fL -o tcast-push.py "https://box.nihaohezi.com/extend/plugins/zhuomian/tools/tcast-push.py"
adb reverse tcp:8765 tcp:8765
Start-Process python -ArgumentList '-m','http.server','8765','--bind','127.0.0.1' -WindowStyle Hidden
python tcast-push.py <IP> http://127.0.0.1:8765/Aerial.apk com.hzzm.app 盒子桌面 0 180
```

运行最后一条后，请用户在电视右上角的提示里**先按「右」再按确认，选「同意」**。脚本打印装好后，结束 `python -m http.server` 进程，运行 `adb reverse --remove tcp:8765`，再回到上面授权步骤。

电视上没有多屏互动时：`adb push Aerial.apk /sdcard/Download/Aerial.apk`，再请用户用电视上**已有的**文件管理器或当贝「本地安装」打开它安装。电视上没有这类应用时，停下来告诉用户，**不要去下载安装当贝市场或其他应用商店**。

## 验收（必须做）

逐条运行，把**原始输出**贴给用户：

```
adb shell "dumpsys package com.hzzm.app | grep versionName"
adb shell "cmd package resolve-activity --brief -a android.intent.action.MAIN -c android.intent.category.HOME -c android.intent.category.DEFAULT"
adb shell settings get secure enabled_accessibility_services
adb shell "dumpsys accessibility | grep -c -E 'label=(盒子桌面|com.hzzm.app)'"
adb shell input keyevent KEYCODE_HOME
adb shell "sleep 8; dumpsys window | grep mCurrentFocus"
```

- 第 1 条有 `versionName`：已安装。
- 第 2 条是系统给出的默认桌面。小米仍然是 PatchWall（`com.mitv.tvhome`）、TCL 仍然是自己的桌面时正常，守护接管；是 `com.hzzm.app` 更好。
- 第 3 条有 `com.hzzm.app/com.hzzm.app.guard.HomeGuardService`：守护已打开（原生 Android TV 已是默认桌面时可能没有，看第 6 条即可）。
- 第 4 条大于 0：守护正在运行。
- **第 6 条包含 `com.hzzm.app`：按主页键进入盒子桌面，安装成功。** 这一条不满足，就不能告诉用户装好了。有的固件按主页键后自家桌面要停几秒，守护才把盒子桌面拉回来（OPPO ColorOS TV 约 5 秒）：第 6 条是原桌面时，再运行一次 `adb shell "sleep 5; dumpsys window | grep mCurrentFocus"`，两次都不是 `com.hzzm.app` 才算失败。
- 第 2、3、6 条的原始输出必须贴给用户，不要只说「成功」。第 2 条报错（老系统没有 `cmd`）时，改用 `adb shell pm resolve-activity --brief -a android.intent.action.MAIN -c android.intent.category.HOME -c android.intent.category.DEFAULT`。

第 6 条不是 `com.hzzm.app` 时，等 5 秒再运行一次第 5、6 条（有的电视守护启动得慢）。还不是，看「常见情况」。

`input keyevent` 模拟的主页键不经过守护的按键过滤，在少数电视上（索尼 Android 9）结果和实体遥控器不同：这时请用户用实体遥控器按一次主页键，再只运行第 6 条，以这次为准。

都通过后，征得用户同意再 `adb reboot`，等一两分钟电视开机后重新 `adb connect <IP>:5555`，再跑一次第 6 条，确认开机直接进入盒子桌面。

## 还原

```bash
# 一行命令（无需仓库，脚本从盒子桌面服务器下载）
curl -fsSL https://box.nihaohezi.com/extend/plugins/zhuomian/tools/restore.sh | TV=<IP> bash
# 顺便卸载：curl -fsSL https://box.nihaohezi.com/extend/plugins/zhuomian/tools/restore.sh | TV=<IP> bash -s -- --uninstall
# 有仓库时也可本地执行：TV=<IP> tools/restore.sh
```

Windows 也可用上面命令（Git Bash / WSL），或逐条运行：

```
adb shell am broadcast -a com.hzzm.app.CONFIG -n com.hzzm.app/.guard.ConfigReceiver --ez keep_adb false --ez own_screensaver false
adb shell cmd notification disallow_listener com.hzzm.app/com.hzzm.app.guard.RevivalListener
adb shell pm revoke com.hzzm.app android.permission.WRITE_SECURE_SETTINGS
adb shell appops set com.hzzm.app SYSTEM_ALERT_WINDOW default
adb shell appops set com.hzzm.app REQUEST_INSTALL_PACKAGES default
adb shell appops set com.hzzm.app APP_AUTO_START default
adb shell appops set com.hzzm.app APP_ASSOC_START default
adb shell appops set com.hzzm.app AUTO_START default
adb shell appops set com.hzzm.app ASSOC_START default
adb shell am force-stop com.hzzm.app
adb shell cmd role remove-role-holder --user 0 android.app.role.HOME com.hzzm.app
```

然后：

- `adb shell settings get secure screensaver_components` 是 `com.hzzm.app/...` 时，用 `adb shell settings get secure screensaver_default_component` 的结果写回去：`adb shell settings put secure screensaver_components <默认值>`。
- `adb shell settings get secure enabled_accessibility_services`：从结果里去掉 `com.hzzm.app/com.hzzm.app.guard.HomeGuardService`（和它前后多余的冒号），其他服务原样保留写回；只剩它自己时运行 `adb shell settings delete secure enabled_accessibility_services`。
- 海信 VIDAA：`adb shell settings get global aerial_vt_home_pkg` 有值（不是 `null`）时，运行 `adb shell setprop persist.vt.use_home_pkg <这个值>` 和 `adb shell settings delete global aerial_vt_home_pkg`。没有值、但 `adb shell getprop persist.vt.use_home_pkg` 是 `com.hzzm.app`（1.15 及以前手动改过）并且装有 `com.jamdeo.tv.vod` 时，运行 `adb shell setprop persist.vt.use_home_pkg com.jamdeo.tv.vod`。
- 要卸载时 `adb uninstall com.hzzm.app`。
- 最后 `adb shell input keyevent KEYCODE_HOME`，电视回到原来的桌面。

## 常见情况

- **小米**：`resolve-activity` 仍然显示 PatchWall（`com.mitv.tvhome`）是正常的，由桌面守护接管。千万不要停用 `com.mitv.tvhome`。建议开 `KEEP_ADB`。
- **小米 Android 9 低内存机型（`adb shell getprop ro.config.low_ram` 是 `true`，比如 MFTP0）**：系统不许任何第三方通知监听，`allow_listener` 没有输出但不生效，这是正常的，不要反复重试。小米待机时会强停盒子桌面，1.21 起盒子桌面改由系统的同步服务在强停后约 30–60 秒拉回来，之后守护会把 ADB 也打开。所以待机超过一分钟再唤醒，直接是盒子桌面；只待机十几秒就唤醒，会先看到原桌面，最多再等一分钟左右才切回盒子桌面。测待机时请待机 1 分钟以上，唤醒后等 30 秒再看结果，不要在这期间按主页键或打开别的 App。1.20 及更早的版本在这类电视上待机后回不来。
- **TCL**：`adb install` 一定失败（`INSTALL_FAILED_VERIFICATION_FAILURE`），按「TCL 安装」走多屏互动。用户没看到电视上的提示时，重新运行一次。
- **创维（比如 7T631_T60，Android 13）**：`adb install` 报 `INSTALL_FAILED_USER_RESTRICTED` 时，是固件在校验 adb 安装。先用 `adb shell settings get global verifier_verify_adb_installs` 记下原值，再运行 `adb shell settings put global verifier_verify_adb_installs 0`，然后重新安装（macOS / Linux 重新运行一行命令）。装好后把原值写回去（原值是 `null` 时用 `adb shell settings delete global verifier_verify_adb_installs`），以后升级时再关一次。这条来自用户反馈，没有在创维真机上验证过。
- **雷鸟 55S595C Ultra（MT9655）等只有「无线调试」的机型**：拿不到授权，能装但接管不了主页键。
- **海信 VIDAA**：第 7 步改了 `persist.vt.use_home_pkg` 以后，主页键直接进盒子桌面；但开机仍会先进聚好看（固件在开机完成前拦截第三方 App），按一次主页键即可。
- **Vidda 其他系统、OPPO K9、雷鸟鹤 6**：能装，但开机进不了盒子桌面（固件只认自家桌面，除非删掉原桌面，这里不做）。可以把盒子桌面当普通 App 用。
- **验收第 4 条是 0，但第 3 条里有盒子桌面**：常见于升级之后，系统还在找旧的安装目录（小米 Android 9）。运行 `adb shell am force-stop com.hzzm.app`，等 3 秒，再 `adb shell am start -W -n com.hzzm.app/.MainActivity`，然后重新验收。或远程修复：`curl -fsSL https://box.nihaohezi.com/extend/plugins/zhuomian/tools/install.sh | TV=<IP> bash -s repair`。
- **用了一段时间后按主页键又回到原桌面**：同上，先试一次上面的强停再打开。
- **验收第 4 条是 0，第 3 条里也没有盒子桌面**：有的固件拦截侧载的无障碍服务。请用户在电视的安全中心或权限管理里允许盒子桌面自启动、无障碍，然后重新运行 `adb shell am start -n com.hzzm.app/.MainActivity` 再验收。
- **忘了家长密码**：`adb shell am broadcast -a com.hzzm.app.CONFIG -n com.hzzm.app/.guard.ConfigReceiver --ez clear_pin true`，密码就关掉了。
- **不支持**：LG webOS、三星 Tizen、华为智慧屏（鸿蒙）、Android 4.4 及更老的电视（盒子桌面最低要 Android 5.0）。老乐视、荣耀智慧屏、老康佳（看不到版本号）等打不开 ADB 的机型也暂时没办法。

## 用户常问

- **会员和 App 还在吗？** 在。盒子桌面只换桌面，电视里的 App、账号和会员都不变，从盒子桌面里打开即可。小米 / TCL 的会员、小爱同学、小米账号、有线电视都不受影响。
- **原来的桌面还能用吗？** 能。原来的桌面作为一个 App 留在盒子桌面的 App 列表里（小米的 PatchWall 也在，从「桌面」磁贴进入），打开就是原来的界面和推荐内容。小米影视、PatchWall 的内容都在。
- **开机广告能去掉吗？** 不能。开机广告是固件在盒子桌面启动之前播的。
- **以后怎么升级？** 控制中心出现「有新版本」时点「下载并安装」（地址来自你好盒子 `app_nurl`，与首页下载同源）。电视不让 App 安装应用时，用提示词里的 URL 再跑一次：`curl -fsSL https://box.nihaohezi.com/extend/plugins/zhuomian/tools/install.sh | APK_URL=<对应包> KEEP_ADB=1 TV=<IP> bash -s standard`（或 `guard`）；有仓库也可 `BUILD=1 TV=<IP> tools/install.sh`。设置都会保留。
- **装好了但有地方不对（主页键、待机、开机、信号源、亮度）**：按 https://box.nihaohezi.com/extend/plugins/zhuomian/templates/adapt.md 做机型适配：自检、当场改能改的、整理成报告。
- **电视上有问题**：`curl -fsSL https://box.nihaohezi.com/extend/plugins/zhuomian/tools/report.sh | TV=<IP> bash` 生成诊断文件；或手机页「反馈问题」复制诊断信息。发到 https://box.nihaohezi.com/?bbs&cat=1&st=follow ，不要往上游 Aerial GitHub 提 issue（除非用户明确要求）。报告只读不改。