# 桌面配置与恢复

[首页](../README.md)  [应用管理](APP_MANAGEMENT.md)  [兼容范围](COMPATIBILITY.md)

当前开发源码采用电脑 AI 配置：首次安装、升级均直接进入桌面；技术配置、守护权限、ADB 连接和系统软件禁用不再出现在电视日常界面。旧安装包不会随文档更新获得新接口。原有偏好、恢复基线、操作记录和暂停选择保留，不因收起界面重新配置或清数据。

## 安装与维护

AI 按 [Agent 安装说明](AGENT_INSTALL.zh-CN.md)使用统一安装入口完成选包、签名与文件校验、保留数据安装，以及获准的系统 HOME／兼容守护配置。必要的电视系统授权、实体遥控器和电源测试仍由用户配合。应用提供受 `WRITE_SECURE_SETTINGS` 保护的电脑维护接口，不接受任意 shell 指令。

电脑上的 `device_maintenance.py` 提供检查、修复、暂停、原桌面恢复、单个应用禁用／恢复和本机信号源配置，默认只读或预览，加 `--apply` 才写入。软件精简独立于安装和接管，按用户明确选择逐个处理；使用当前 APK 的固件规则和保护条件，不把上游包名清单当作操作资格。详见 [电脑维护步骤](AGENT_INSTALL.zh-CN.md#电脑维护检查修复与恢复)。

| 档位 | 日常界面 | 电脑维护差异 |
| --- | --- | --- |
| 安卓5及以上标准档、relay／专用包 | 日常管理与帮助恢复 | 守护依赖实际 APK、机型和权限；用实际包名调用 |
| 安卓4.4 | 同样收起技术入口，保留日常管理与帮助恢复 | 无标准守护、通知恢复或开机跳板；原生 HOME 及已支持的特殊主页键能力另行核对 |

## 覆盖升级

本轮修复尚未随新 APK 发布。包含修复的同包名、同签名递增构建，只有在固件、HOME 形态、原桌面及助手版本未变时才迁移原路线；保留暂停和 ADB 选择，活动代理重新握手，不重新执行首次配置。原环境变化需重新核对；旧实体场景验收清为待验证。升级后核对接管、守护、ADB 和恢复记录，网络 ADB 的重启可达性另验，详见[升级与恢复规则](DEVICE_ADAPTATION.zh-CN.md)。

## 帮助与恢复

“应用管理 → 更多 → 帮助与恢复”提供安装页地址、暂停桌面接管和恢复原桌面。暂停不会改变系统默认 HOME；恢复先暂停接管，再检查保存的原桌面是否可用。如果系统 HOME 已是原桌面，打开该组件；否则进入系统默认桌面选择页。系统无该入口时可临时打开原桌面，并明确提示需电脑完成默认 HOME 恢复。没有可靠记录、原桌面已禁用或组件不可用时提示电脑恢复，不猜测或盲目启用。

电脑恢复同样先暂停，按已保存的原组件及实际系统能力切换 HOME 并读回。历史专项接管或已禁用原桌面由工具核对原记录后恢复对应变更，保留已选择的 ADB 保持；不把当前 Quiet TV HOME 写成原桌面，也不覆盖既有基线。新安装接管前把原组件同步到应用内恢复记录；旧 APK 缺接口时保留电脑记录并明确提示。

## 桌面守护（实验）

后台守护继续复用既有实现，不因移除界面改变接管策略。直接 HOME、原主页中转、独立代理、开机跳板和按键补偿各有适用条件；系统 HOME 已指向 Quiet TV 不代表厂商实体 HOME 一定遵循。原主页须依据本机组件、已保存记录及固件规则识别；多个无法判定的候选交给 AI 引导确认，不按品牌猜测。依赖原桌面的中转必须保留原桌面。

无障碍已授权、服务绑定、事件可用、请求已分发、首页回调和实际画面分别判断。关闭、暂停、锁屏、其他前台窗口及播放场景继续遵守现有条件。用户主动暂停桌面接管后，检查修复不自动开启接管；只有明确要求恢复才使用 `repair --resume`。升级和诊断不擅自恢复暂停的接管。

Android 4.4 不开放标准守护。已有精确海信 API19 主页键补偿，仍需系统无障碍授权及实体按键测试；AI 可引导打开系统无障碍设置，不在桌面常规设置中加入技术开关。后台恢复、原桌面及依赖保护均沿用既有规则。

### 通过电脑配置守护

新安装优先用统一安装入口；已有配置修复优先用维护工具。需要指定已确认原组件等专项参数时，继续使用 [configure_home_guard.py](../scripts/configure_home_guard.py)：

```sh
python3 scripts/configure_home_guard.py --serial "$TV_SERIAL" --user "$TV_USER" --package "$QUIET_PACKAGE" --home "$ORIGINAL_HOME"
```

先核对预览，在既有配置授权内用 `--apply --record "$NEW_PRIVATE_RECORD"` 执行；此底层命令明确开启守护，不能在只读诊断、仅更新或主动暂停时随意调用。电脑 ADB 和历史应用内 ADB 是不同授权，电脑已能配置时不要求电视再连接本机 ADB。实际 APK 缺入口就说明需新版，不写应用私有文件绕过。

TCL 自启动 AppOp、旧安卓用量统计、无障碍与通知恢复按现有命名探测、原值记录和读回处理；不使用跨固件猜测的数字 ID。默认 AI 安装配置包括 ADB 常开，独立于桌面接管的暂停状态。安卓5及以上标准档根据 APK 能力与实际权限恢复调试开关，开机广播完成前执行恢复；原有同步回调和进程内开关监听继续恢复。仅小米／Redmi 的安卓5～10旧 TCP 恢复路径保存实际端口，不扩大厂商端口策略、不默认 5555、不把配对端口当连接端口。Android11+无线调试独立于 USB 调试开关，设置读回不能证明重启后的网络连接可用。实际重启重连未通过时，ADB 常开目标仍未完成。详见 [ADB 常开与重启验收](AGENT_INSTALL.zh-CN.md#adb-常开与重启验收)。

## 问题排查与验收

“应用管理 → 诊断日志”继续提供只读状态及限时扫码导出，不包含操作开关。电脑侧使用 [Agent 问题排查](AGENT_DIAGNOSE.zh-CN.md)；收集日志不自动修复、重新安装或上传完整设备信息。

分别记录系统 HOME、实体 HOME、正常重启、断电冷启动、短／长待机唤醒，以及 HDMI／播放不被打断。模拟器、编译、配置返回和系统解析不能代替厂商真机验收。电源测试按用户授权执行，未执行明确写未执行。

## 原状态与数据

电脑记录使用新的私有目录，保存每次预览、拟修改目标、原值、执行尝试及读回结果。应用内旧 `files/setup-state.json`、`files/app-operations.jsonl` 保留，不是应用数据备份。中断后先读状态，不自动续做、重放、清数据或恢复出厂。

原桌面及关键系统组件继续受保护。一般软件禁用工具不处理原桌面；专项接管仍须精确规则、本机可恢复路径及明确范围。恢复软件使用本次禁用记录，精确区分默认启用值 0 和手动启用值 1；版本或状态变化时停止并说明。禁用保留安装与数据，本维护工具不执行卸载。

## 电脑适配与自检

[适配指南](AGENT_ADAPT.zh-CN.md)统一说明自检报告、本机信号源配置、同签名 HOME 代理修复及专项恢复。`device_selftest.py` 默认只读，按授权选择模拟 HOME、信号源、待机或重启，并支持同机修复前后对比。配置、请求回执、实际网络重连和实体画面分别验收。上述技术操作不增加电视端设置入口。