跪拜 Guibai
← Back to the summary

CleanYourTV: AI-Driven Android TV Debloating Meets a 523 KB Apple TV-Style Launcher

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

作者: 冬奇Lab

标签: 开源, 资讯

引言

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

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

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

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

你将学到什么

前置知识

项目背景

项目简介

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

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

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

作者与社区

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

项目数据

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

主要功能

核心作用

做两件事：

  1. 去臃肿（debloat）：停用厂商的遥测、广告服务、内容栏目和预装垃圾应用
  2. 换主屏：安装一个体积很小的原生启动器，设为默认主屏幕，外观类似 Apple TV

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

使用场景

  1. 清理自己家的电视

    • 电脑和电视在同一 Wi-Fi，助手大约十五分钟完成备份、停用、安装和逐步截图验证

  2. 只有一部安卓手机的人

    • 社区作者 udhaykumarbala 做了一个免费开源的手机 App，连接电视、先展示计划、保存还原点，再执行清理

  3. 帮家人远程清理

    • 通过私有的 Tailscale 链路，而不是在路由器上开放 ADB 端口

  4. 给自己的电视型号贡献清单

    • 每款电视一个目录，放在 examples/ 下，后来的人可以直接复用

  5. 在此基础上二次开发

    • 项目的 SHOWCASE.md 收录了 121 个衍生项目：主屏、Fork、插件、工具和其他平台的移植

快速开始

需要和电视在同一 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 移除

核心特性

  1. 纯黑主屏 + 底部 dock

    • 四个常用应用放在圆角 dock 里，位置和 Apple TV 一致

  2. Top shelf 与环境光

    • 聚焦的应用名用大字显示，背后的光晕取自应用图标的主色

  3. 一块浮动的玻璃高光

    • 在图块之间弹性移动，聚焦的图块会抬起并显示名称

  4. 主题不用重新构建

    • 颜色、壁纸、dock 和列数通过 config.json 经 Wi-Fi 推送，仓库自带十个主题

  5. 28 种语言

    • 跟随电视语言，希伯来语是完整镜像的从右到左布局

  6. 模块卡片（Module cards）

    • 任何电视应用都可以声明自己的图块，但每个应用要经你批准一次才会显示

  7. 应用库与图块菜单

    • 长按 OK 可以移动图块、从首页移除、查看应用信息

  8. 时钟屏保

    • 缓慢漂移的时钟，避免烧屏

项目优势

对比项 CleanYourTV 手动逐条敲 adb 命令 刷机或 root
门槛 助手代劳，回答几个问题 要自己查每个包名 高，且各品牌方法不同
可逆性 先记录状态，一行命令还原 取决于你有没有记下来 可能影响保修，难回退
品牌适配 社区清单 + 助手现场发现 全靠自己 因机型而异
主屏体验 附带启动器 无 取决于刷入的系统

为什么值得看？

项目详细剖析

三步流程的底层机制

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

步骤 做什么
备份 已安装包列表和系统设置
停用 用 pm disable-user 停用厂商遥测、广告服务、内容栏目和预装垃圾
安装 安装小型原生启动器，设为默认主屏

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

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

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

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

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

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

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

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

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

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

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

启动器：523 KB 的原生 Java

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

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

配置分三层：

层次 内容
config.xml dock 顺序、隐藏的应用、直播电视应用、每行 4 到 7 个图块、减少动画
主题 config.json 同样的配置项，外加背景色和壁纸，经 Wi-Fi 推送，无需重新构建
电视上的启动器设置 长按 OK 进入，调整每行数量、dock 透明度、动画、开机自动打开的应用等

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

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

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

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

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

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

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

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

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

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

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

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

退出码 含义
0 电视仍与清单一致
1 发生了漂移
2 根本没能检查（电视没响应、没人点允许、清单路径不对等）

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

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

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

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

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

适用范围与局限

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

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

项目地址与资源

官方资源

相关资源

总结与展望

核心要点回顾

  1. 停用而不是卸载：pm disable-user 与系统设置里的"停用"同源，配合先写后改的还原记录，让整个流程可逆
  2. 助手负责发现，脚本负责安全：不同品牌的预装差异交给 AI 现场判断，而主屏保护、备份、回滚这些关键动作固化在脚本里
  3. 启动器极度克制：523 KB、纯 Java、没有网络权限，扩展一律默认关闭、逐项授权
  4. 社区清单是护城河：每款电视一个目录，加上自动生成的表格和大量测试，让增长不至于失控
  5. 边界写得清楚：Fire TV、三星、LG 的限制，以及网络 ADB 的风险，都在文档里直说

适用人群

使用建议

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

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

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