一天一个开源项目（第248篇）：CleanYourTV —— 让 AI 编程助手通过 Wi-Fi 给安卓电视去广告、换上 Apple TV 风格主屏

引言

电视是你买的，首页上的广告位却不是你选的。

这是"一天一个开源项目"系列的第 248 篇文章。今天带你了解的项目是 CleanYourTV（Gathin23/cleanyourtv）。

作者发了一条推文：用 Claude Code 通过 Wi-Fi 把父母家电视的首页清理干净，前后对比图。这条推文据 README 所述获得了 740 万次浏览，很多人照着做，回复里的电视型号和清单最后变成了仓库里的内容。项目 2026 年 10 月 17 日创建，写这篇文章时已经有近 3.8 万 Star、4500 多个 Fork。

它有意思的地方不在"又一个去广告脚本"，而在于交付方式：仓库本身是一套带安全护栏的工具，加上一份交给编程助手的提示词。助手负责在你的电视上"发现"有哪些预装应用，并在动到你可能在用的东西之前先问你。

你将学到什么

• CleanYourTV 做了什么，以及"停用而不是卸载"为什么是它的安全底线
• "备份 → 停用 → 安装启动器"三步流程的具体机制
• 一个只有 523 KB 的原生启动器是怎么设计的，主题、模块卡片、插件怎么扩展
• 它如何保证"不会把电视搞到没有主屏幕"，以及怎么一行命令还原
• 固件更新后怎么检测并修复"漂移"
• 适用范围与已知限制

前置知识

• 知道 Android 的 ADB（Android Debug Bridge）是什么，会在终端里敲命令
• 了解 pm disable-user 这类包管理命令的大致含义（不了解也可以，下文会解释）
• 对"让 AI 编程助手操作真实硬件"这件事感兴趣

项目背景

项目简介

CleanYourTV 针对的是 Android TV 和 Google TV。这类电视出厂时往往带着厂商的遥测服务、广告服务、内容推荐栏和一批没人要的预装应用，首页还会插入赞助内容。

项目的思路很直接：安卓电视和安卓手机一样有调试桥。在电视的开发者选项里打开 USB 调试，在电脑上授权一次，之后用的全是标准 Android 工具。

没有 root，没有数据线，没有卸载任何东西，后悔了有一行命令还原。

作者与社区

• 作者：Gathin23（GitHub 用户，项目主页 cleanyour.tv）
• 创建时间：2026-10-17
• 前身：仓库原名 tv-vibehack，10 月 19 日改名，旧链接仍然有效
• 社区：README 自述四天内收到 200 多位贡献者提交的 170 多款电视清单；项目卡片上的数据是 316 款电视、89 个品牌、28 种语言

另外值得一提的是，项目官网明确声明：cleanyourtv.com 等其他同名域名不由本项目运营。

项目数据

数据取自 2026-10-26 的 GitHub 页面，增长很快，仅供参考：

• ⭐ GitHub Stars: 约 37,800
• 🍴 Forks: 约 4,500
• 📦 最新版本: v3.0.0（2026-10-25 发布，此前 10 月 20 日至 23 日连发了 v2.4 到 v2.7）
• 📄 License: MIT（字体 Outfit 使用 SIL OFL）
• 🌐 官网: cleanyour.tv
• 💻 语言构成: Python、Java、Kotlin、Shell、PowerShell

主要功能

核心作用

做两件事：

"去臃肿"这一半对不同品牌差异很大，所以项目没有给一份通用清单，而是让编程助手在你的电视上先发现有什么，再逐项确认。

使用场景

快速开始

需要和电视在同一 Wi-Fi 的电脑，以及一个有 shell 权限的编程助手（Claude Code、Codex 或 Gemini CLI 均可）。

第 1 步，在电视上：设置 → 设备偏好 → 关于 → 连按 7 次"版本号" → 返回 → 开发者选项 → 打开 USB 调试（如果有"网络调试 / ADB 调试"开关也一并打开），电视保持开机。

第 2 步，在电脑上：克隆仓库，用助手打开这个目录，然后把 PROMPT.md 的内容贴给它，填上电视型号。

git clone https://github.com/Gathin23/cleanyourtv
cd cleanyourtv
# 用你的编程助手打开此目录，再粘贴 PROMPT.md 并填写电视型号

第 3 步，跟着走：在电视上点"允许 USB 调试"，然后回答助手的清单：你常用哪些应用、dock 放几个、要不要保留语音助手、Chromecast 和系统更新。

必须克隆仓库的原因是：助手会复用仓库里的 tools/disable.sh 和 launcher/build-and-install.sh，而不是自己临场写脚本。备份、主屏保护和还原记录都在这些脚本里。

手动方式

助手做的所有事，你也可以手动执行。工具链只依赖 Python 3：

python3 -m venv tools/venv && tools/venv/bin/pip install -r tools/requirements.txt
export TV_HOST=192.168.1.50 # 电视的 IP

tools/venv/bin/python -I tools/tv.py –probe # 型号、安卓版本、固件
tools/disable.sh examples/xiaomi-mi-tv-4a/debloat.txt # 应用一份去臃肿清单
tools/restore.sh examples/xiaomi-mi-tv-4a/debloat.txt # 撤销，换回原厂主屏
TV_HOST=192.168.1.50 launcher/build-and-install.sh # 构建并安装启动器，设为主屏
tools/theme.sh themes/aurora # 推送主题，–reset 移除

核心特性

项目优势

为什么值得看？

• 它把"让 AI 操作真实设备"这件事放进了一套有边界的工具里，而不是让模型自由发挥
• 全部走电视自己对所有者开放的接口，不绕过任何锁、DRM 或版权保护
• 社区贡献的清单让"下一个同型号的人"不用重新摸索

项目详细剖析

三步流程的底层机制

README 把整个过程概括成一张表：

关键在第二步。pm disable-user 和你在"设置 → 应用 → 停用"里点的那个按钮是同一个开关，应用文件并没有被删除，只是在当前用户下被禁用。这是整个项目可逆性的来源。

保护主屏：不能让电视"没有首页"

去臃肿最危险的一类事故，是把当前主屏应用停用了，而新的启动器还没就位，结果主屏落到一个工厂测试应用上，甚至系统循环崩溃。

项目在脚本里做了几层防护：

• 安装脚本会询问电视当前哪个应用拥有 Home，并且只停用它认识的原厂启动器，也就是 KNOWN_STOCK_LAUNCHERS 中的四个：com.google.android.tvlauncher、com.google.android.apps.tv.launcherx、com.google.android.leanbacklauncher，以及小米的 com.mitv.tvhome
• tools/disable.sh 在停用任何东西之前先做同样的检查：如果清单里包含拥有 Home 的应用，而电视上没有其他应用响应 HOME，就跳过这一项并说明原因，继续处理其余条目
• 设置向导、设置应用、厂商的 FallbackHome 和工厂测试应用虽然也会响应 HOME，但不算数
• 启动器安装后如果 Home 没有落到它身上，脚本会回滚

对 Google TV 还有一个坑：开机向导 setupwraith 在原厂启动器被停用后可能抢到 Home 并导致系统崩溃循环，所以要一并停用。但如果 Wi-Fi 网络是在开机向导里保存的，这个网络归 setupwraith 所有，停用它会删掉网络。所以 disable.sh 会先检查，在你重新加入 Wi-Fi 之前跳过它。

这些细节说明作者踩过很多坑，脚本里的每个 if 基本都对应一次真实事故。

还原机制：先写记录，再动手

tools/disable.sh 在改动任何东西之前，会把电视当前的样子写进 ~/.cleanyourtv/，每台电视、每份清单一个文件：

• 清单中每个包当时是启用、已停用还是未安装
• 哪个组件拥有 Home
• 三个动画缩放值

还原时重放这份记录，因此你自己之前手动停用的包会保持停用，Home 也会回到原来的组件。再次运行同一份清单时，工具保留第一次的记录，而不是用"已清理"的状态覆盖它。

没有记录的话（旧版本运行过，或记录被删），脚本会明确提示，然后退回到"启用整份清单并把缩放值重置为 1.0"。

如果电视已经连不上，电视自带的"设置 → 应用"页面同样可以重新启用这些包。

启动器：523 KB 的原生 Java

启动器是整个项目另一半的核心：

• 体积约 523 KB，纯 Java，为只有 1 GB 内存的电视设计
• 没有模糊效果，没有视频，没有网络权限，没有后台服务
• 电视需要 Android 8.0（API 26）及以上，minSdk 是编译期下限，安装脚本会先查询 ro.build.version.sdk，版本不够时直接提示两个数字，而不是在 pm install 时失败

"没有网络权限"这一点对一个声称要去掉遥测的工具来说很重要：它从根本上无法往外发数据。

配置分三层：

模块卡片与插件：把扩展点交给用户批准

任何电视应用都可以声明自己的图块（标签、说明、光晕颜色）。启动器每个应用只问你一次，默认隐藏，并把你的答案和该应用的签名密钥、卡片名绑定。想改主意，长按 Settings 进入 Module cards。

插件放在 addons/ 目录，作为模块卡片接入，不会被编进启动器本体。tools/manage.py 可以列出所有插件、主题和开关，查看电视上装了哪些，并通过运行创作者自己的脚本来安装、更新或移除。

这种"默认关闭、逐个授权"的扩展模型，让体积和隐私承诺不会被插件悄悄破坏。

遥测审计：不猜，只给证据

tools/privacy.py 解决的问题是"这些包里哪个在听我说话"。README 对此的态度很克制：许多机型上大部分包以 android.uid.system 运行，权限扫描会显示五十个包都有 RECORD_AUDIO，但没一个真的在录音；有的电视麦克风在遥控器里而不在机身里；ACR（自动内容识别）客户端只靠 INTERNET 权限就能从画面识别内容。

所以这个工具按证据分三组列出语音、ACR 和遥测候选，每项给出：

• 是否被固件自己的 voice_interaction_service 点名，或匹配 examples/ 中已知组件，还是仅仅名字相似
• 是否声明 RECORD_AUDIO、是否共享系统 UID
• AppOps 历史里是否出现过麦克风访问

加 –write privacy.txt 可以把已确认的候选转成标准清单，用 disable.sh 和 restore.sh 应用和撤销。仅靠名字匹配的包默认不写入，除非加 –include-low。

README 也坦白说明了工具的边界：它证明不了意图。AppOps 能说明某个操作被触碰过，不能说明数据流之后去了哪里。关掉语音助手也有代价，比如遥控器的麦克风键和应用内语音搜索会失效，所以报告会逐个包写明代价，而不是把它当成"赢"。

固件更新后的"漂移"检测

固件更新会覆盖已清理的系统：被停用的包回来、Home 回到原厂启动器、冒出清单里没有的新预装。

tools/check.py 把电视和你应用过的清单对比，退出码有明确含义：

加 –fix 会重新应用清单：先把 Home 切回不被停用的启动器，再停用回来的包，并读回确认。它不会自己写新的还原记录，因为只有第一次的记录里才有"清理之前"的状态；有记录时，它会先把新增项补进去，保证之后 restore.sh 仍能回到原厂。

这个设计允许你把检查丢进 cron，每周一跑一次。但文档也诚实地提醒：要让定时任务工作，电视得一直开着网络 ADB，而网络 ADB 本身是个安全隐患，需要权衡。

性能工具：把"流畅"变成可测量的东西

仓库里有一组专门度量启动器的工具：

• tools/bench.py：测量按键延迟、焦点移动、卡顿帧、冷启动、返回主屏耗时，以及空闲时的 CPU 和内存占用，不修改电视，把每次按键的原始数据写成 JSON
• tools/trace.py / trace_report.py：录制 Perfetto 跟踪并报告时间花在哪
• tools/flamechart.py：为 PR 画前后对比火焰图
• tools/screendiff.py：逐像素对比前后截图，并把你的 Wi-Fi 名称模糊掉

仓库的 tests/ 目录也有 170 多个测试文件，从 ADB 密钥权限、清单路径到文档里的数据是否与 examples/ 一致。表格（品牌统计、电视列表）由 tools/gen_tables.py 从各目录的 tv.json 生成，所以 README 里的数字不靠手改。对一个九天内涌入几百位贡献者的仓库来说，这些自动检查是它还没散架的原因之一。

适用范围与局限

README 对这部分写得相当坦诚，值得单独列出来：

• Fire TV：只有去臃肿这一半可用，因为 Fire OS 不允许第三方启动器接管 Home；2015 款 Fire TV Box（Fire OS 5）连这一半也不行，所有 pm 途径都被拒绝
• 部分中国市场的 TCL 机型：拒绝安装任何启动器，对应清单的头部会写明
• 三星（Tizen）和 LG（webOS）：系统不同，不适用；SHOWCASE.md 里有三个 webOS 移植，三星 2021 款没有 ADB，也就没有 pm disable-user
• 网络 ADB 是明文：监听 5555 端口，固件如果是 ro.adb.secure=0，局域网内任何设备都能拿到 shell，所以用完要关掉，并用 tools/adb-closed.py 验证端口确实已关闭
• 风险在于"停用了系统依赖的东西"：所以清单要分小批应用，并随时备好还原脚本；如果电视已经无法启动到能用 ADB 的程度，通常只能通过恢复菜单恢复出厂设置，这会清掉你自己的应用和账号
• 没有预编译 APK：必须自己构建，作者的理由是你应该清楚自己电视上装的是什么
• 应用内广告基本不管：可以用 Android 的私有 DNS 指向 AdGuard DNS 之类的解析器，但那个解析器会看到电视的所有 DNS 查询，而且去不掉 YouTube 广告，因为广告和视频来自同一批服务器

另外有一点要自己判断：让编程助手拿着 shell 去操作你的电视，本身是一次授权。建议先读一遍 PROMPT.md 和 tools/disable.sh，再决定放权到什么程度。

项目地址与资源

官方资源

• 🌟 GitHub: https://github.com/Gathin23/cleanyourtv
• 🌐 官网: https://cleanyour.tv
• 📚 故障排查: 仓库内 docs/TROUBLESHOOTING.md
• 💬 讨论区: GitHub Discussions
• 🐛 Issues: https://github.com/Gathin23/cleanyourtv/issues

相关资源

• 社区手机 App: cleanyour.tv/app
• 主题与插件: cleanyour.tv/addons
• 衍生项目合集: 仓库内 SHOWCASE.md
• 远程帮家人清理: 仓库内 docs/REMOTE.md

总结与展望

核心要点回顾

适用人群

• 想清理自家安卓电视或电视盒子的人，尤其是被首页广告和推荐栏困扰的
• 想看"AI 编程助手 + 受限工具集"如何落到真实硬件上的开发者
• 做 Android TV 启动器、想参考配置和主题机制的开发者
• 手里有一款还没被收录的电视，愿意贡献清单的人

使用建议

先在 examples/ 里找你的电视型号，对照里面的 debloat.txt 看一遍都停用了什么，再决定要不要让助手代劳。第一次操作时务必保留还原记录，并在完成后关闭电视上的调试开关。

探索 PrimeSkills —— 精选 AI agent 和技能工具，每一个都经过真实工作流验证。没有炒作，只有真正好用的工具。

访问我的个人主页，获取更多见解和有趣的产品。 加粗样式