换启动器到底难在哪？Shield Optimizer 的多策略 Home 切换与 Setup Wraith 陷阱-开发者社区

【免费下载链接】shield_optimizer

项目地址：https://gitcode.com/gh_mirrors/sh/shield_optimizer

Shield Optimizer是一款面向 Android TV / Nvidia Shield 的开源电视优化工具（桌面版现名 ATV Optimizer）。本文讲清它最"硬核"的功能之一：更换电视启动器（Launcher）。换启动器看似只是"设置默认应用"，但 Android TV 各机型行为差异极大，甚至藏着一个叫Setup Wraith的系统陷阱。Shield Optimizer 用一条"策略阶梯"加层层安全网，把换启动器这件高风险操作变得可逆、可控。

1️⃣ 换启动器为什么不是"点一下"的事

Android 里按 Home 键打开哪个应用，由系统的HOME 角色决定。但各厂商、各 Android 版本的 ADB 命令表现并不一致：

有的机型执行cmd role add-role-holder（Home 角色 API）立刻生效；
有的机型命令返回 "Success"，实际却纹丝不动（所谓"接受但忽略"）；
有些老版本根本没有 role 命令，只能退回set-home-activity或发送 HOME intent。

这意味着"一条命令切启动器"在任何一台电视上都可能是错的，工具必须逐级尝试并逐一验证。

2️⃣ 多策略 Home 切换：四步阶梯逐级验证

v2 桌面版把切换实现为一条阶梯（核心实现在 v2/crates/core/src/commands/launcher.rs）：

顺序	策略	做法
1	启用目标	`pm enable`，先解开之前被禁用的启动器
2	Home 角色 API	`cmd role add-role-holder android.app.role.HOME <pkg>`，Android 10+ 首选
3	注册 Home 活动	对发现的/猜测的 HOME 活动尝试`set-home-activity`两种命令写法
4	禁用原生启动器接管	上三步都被"接受但忽略"时，经你明确确认后才禁用 Stock 启动器

几个关键设计：

每一步都回读验证——通过resolve-activity和 role 查询重新确认"现在到底谁在当 Home"，而不是听信命令的返回值；
原生启动器快速通道——实测发现（Shield / Android 11），启用状态的原生启动器会压过一切设置命令，所以检测到它仍占位时直接跳到接管流程，不浪费时间；
全程可回滚——禁用后验证失败，自动pm enable恢复原生启动器，电视绝不会被留在"半切换"状态。

3️⃣ 真正的陷阱：Setup Wraith 抢走 Home 键

Google TV 内置一个首启设置向导，包名是com.google.android.tungsten.setupwraith，社区叫它Setup Wraith。问题在于：它声明了一个 HOME 屏幕，而且意图过滤器优先级很高。

后果是：当你禁用原生启动器后，如果 Setup Wraith 还开着，它立刻抢占 Home 键——电视回到设置向导或黑屏。更迷惑的是，此时 Android 的意图解析器会一直把它报成"当前 Home 应用"，让你误以为切换失败（这是 issue #122 的典型场景）。

Shield Optimizer 的解法有三层：

配对联动：在 launchers.json 中，Google TV 原生启动器声明了"disable_with": ["com.google.android.tungsten.setupwraith"]。切换流程只有在你的新启动器已确认接管 Home 之后，才顺带禁用 Setup Wraith，并再验证一次；任何一步失败，原生启动器和 Setup Wraith一起恢复，绝不留半路。
状态可视化：Launcher 页始终显示 Setup Wraith 是开是关。若它开着而原生启动器已关，界面给出橙色风险警告和一键"Turn it off"；关掉了则提供"Re-enable Setup Wraith"按钮——因为 Google 要求重新登录或配对遥控器时，你还需要它。
判断"当前 Home"只看 role holder：读取 pick_current_home 优先采用 HOME role holder（Home 键真正打开的东西），只有老系统没有 role 命令时才退回解析器结果，避免被 Setup Wraith 的高优先级干扰。

这套行为的完整推演（抢占、一键修复、回滚、Shield 不受影响）可以在这两个场景文件中看到：42-setup-wraith.mjs 与 40-launcher.mjs。

4️⃣ 安全底线：绝不让你"没有家"

无论走哪条切换路径，Shield Optimizer 都有几道硬约束：

🔒拒绝禁用最后一个真实启动器：只剩一个 HOME 应用时，任何禁用都会被拒（Settings 恢复兜底和 Setup Wraith 都不算"家"）；
🔒永不触碰 Safety 兜底：com.android.tv.settings这类恢复入口永远不会被禁用；
🔒禁用前确认 + 禁用后验证：确认对话框会明确写出"也会关闭 Setup Wraith"这类副作用；
✅一切可逆：所有改动都是"禁用"而非"卸载"，配合 Emergency Recovery 一键全量恢复；
✅Shield 零影响：Nvidia Shield 上 Setup Wraith 本来就默认禁用，不显示该行、不发任何相关命令，行为与旧版本完全一致。

5️⃣ 小结

换启动器的难点不在"命令"，而在机型差异 × 系统行为 × 隐藏陷阱的组合：有的机器装样子成功，有的机器 Home 键会被设置向导抢走。Shield Optimizer 的答案是多策略阶梯 + 逐步回读验证 + 失败自动回滚，再用 Setup Wraith 的配对联动把这个最隐蔽的坑直接填平。想亲手验证这套逻辑，可以从 v2/crates/core/src/engine/launcher.rs 的纯函数实现和 v2/e2e/scenarios/42-setup-wraith.mjs 的模拟场景读起。