Gathin23/cleanyourtv 43,068★:11 天冲上周榜第一的电视清场工具——532 KB 的桌面、345 个机型清单,和那条「先装新桌面再关旧桌面」的硬规矩

今天 GitHub 上这个项目的数字是:43,068★、5,258 个 fork、222 个未关 issue、1,436 个已合并 PR,主语言 Python,许可 MIT,建仓时间 2026 年 10 月 17 日——到今天刚好 11 天。仓库里 examples/ 目录下有 345 个文件夹,一个文件夹就是一台电视的实测清单。

更夸张的是仓库自己记的起源:作者 10 月 17 日把父母家电视清理前后的对比图发在 X 上,那条帖子拿到 740 万次浏览;四天里两百多个贡献者塞进来 170 多个机型清单;10 月 19 日仓库从 tv-vibehack 改名成 cleanyourtv;Trendshift 把它记成 10 月 19 日到 25 日的周榜第一。官网首页现在挂着"42,900+ 星、5,200+ fork、430+ 贡献者、345 个机型来自 94 个品牌、313 篇媒体报道",最近三个版本 v2.7.0、v3.0.0、v3.1.0 分别发在 10 月 23、25、27 日。

这个东西解决的是一个很具体的家庭矛盾:电视越来越便宜,但它开机以后那块屏幕不完全属于你。CleanYourTV 的做法是把电视自己提供给机主的开关批量按一遍,然后换一块干净的桌面。

一句话定位:它不刷机,只是把电视本来就给你的开关批量按一遍

• 三件事:备份当前状态、用 pm disable-user 停用广告与预装包、装一个小桌面并把它设成 Home。整个流程不需要 root、不刷固件、不绕任何锁,仓库里也没有厂商固件或 APK。
• “禁用"和"卸载"是两回事,这是它能做到"一条命令反悔"的全部原因。包还在系统里,只是对当前用户停用,所以 restore.sh 能把每一步原样恢复。
• 它的主体不是 App,是一份提示词加一套脚本。根目录的 PROMPT.md 是给编码助手看的作业指导书,tools/ 里是禁用、恢复、审计、测速的脚本,launcher/ 才是一个真正的 Android 应用。
• 所以官方推荐的用法有点反直觉:不是下载安装包,而是把仓库 clone 到电脑上,让 Claude Code、Codex、Gemini CLI 这类带 shell 的助手照着 PROMPT.md 去干。官方估的时间是十五分钟。

核心一:备份、禁用、装桌面,每一步都留了退路

• 第一步是备份,而且是"能反做"的备份。脚本先把完整包列表、已禁用包列表、getprop 输出和各项设置存下来,再写一份恢复脚本。恢复记录落在 ~/.cleanyourtv/,不在电视上。
• 第二步分批禁用,清单是纯文本。一行一个包名,# 后面可以写注释,想留哪个就注释掉哪行;disable.sh 在动手之前会先写恢复记录,所以中途拔网线也不会留下"关了但记不住"的状态。
• 第三步才换桌面,而且顺序被写死在脚本里:launcher/build-and-install.sh 构建一个约 532 KB 的 release、安装、切 Home,切不过去就自己回滚。原因在下面"安全边界"一节会讲,这是整个项目最容易翻车的地方。
• 固件升级之后还有一条补救路:tools/check.py 拿电视当前状态和你当初应用的清单对比,列出被升级装回来的包,加 --fix 一次性补回去。

核心二:532 KB 的桌面,做的是减法

• 体积和依赖:纯 Java,release 约 532 KB,没有网络权限、没有后台服务、没有模糊和视频背景,官方说它是给 1 GB 内存的电视准备的,最低要求 Android 8.0(API 26)。
• 视觉上照着 Apple TV 抄了结构:底部一条圆角玻璃带放四到七个常用 App,往上是一行大字显示当前焦点 App 的名字、背景用封面取色的氛围光,按遥控器下键才滑出全部应用的网格,焦点由一个玻璃高亮块在磁贴之间弹跳。
• 三个磨砂按钮是有实际用途的:输入源(HDMI 会显示你在电视设置里改过的名字、还有 AV 和 Live TV)、网络(Wi-Fi 或以太网加网络名)、设置。也就是说换掉原桌面以后,电视该有的入口一个不少。
• 该有的细节都在:时钟和日期、防烧屏的漂移时钟屏保、可选的一行 CPU / 空闲内存 / 空闲存储(只在 Home 可见时刷新)、10 套主题(推一个 config.json 就换,不用重新编译)、29 种语言(含希伯来语的整页镜像布局)、可选的 App 库和长按磁贴的移动菜单。
• 模块卡是留给生态的口子:任何电视 App 都可以申请在桌面上占一个磁贴,但每一个都要你亲手批准一次。

一个桌面做到 532 KB 意味着什么?意味着它在一台 2018 年的 1 GB 内存电视上也不会成为新的卡顿来源。这一点比"看起来像 Apple TV"重要得多——很多人换桌面的初衷是去掉广告,结果装了一个更吃内存的启动器,等于把问题换了个形状。

核心三:345 个机型清单,才是这项目最硬的资产

examples/ 下每个文件夹里有一份 debloat.txt(禁用清单)和一份 tv.json(机型、系统、备注)。这不是文档,是可以直接执行的输入。

拿最多人关心的小米举例。examples/xiaomi-mi-tv-4a/ 对应 MiTV-MOOQ1、Android TV 10、固件 QTG3.200305.006.2591,清单里 21 个包,分成五类:

清单开头还写了一个很典型的国产固件坑:这台机器的 default_input_method 指向 com.baidu.input,而那个输入法根本没装,所以搜索框里不弹键盘,得自己去设一个 Gboard。这种一句话,比任何评测都值钱——它是别人在自己电视上踩出来的。

用法就两行:

1
2

TV_HOST=192.168.1.50 tools/disable.sh examples/xiaomi-mi-tv-4a/debloat.txt
TV_HOST=192.168.1.50 tools/restore.sh examples/xiaomi-mi-tv-4a/debloat.txt

清单也可以放在仓库外面,路径按你运行命令的目录算,绝对路径也认。这点很关键:你给自己那台电视调出来的清单,不必提交给上游,也不必和别人共用。

怎么用起来:三条路,选一条

路线 A,官方推荐,有编码助手(约 15 分钟)。

1. 电视上开开发者选项:设置 → 设备偏好设置 → 关于 → 在"内部版本号"上连按七次,返回后进开发者选项,打开 USB 调试;如果有"网络调试 / ADB 调试"开关也一并打开,电视保持开机。
2. 电脑和电视连同一个 Wi-Fi,git clone 仓库,把 PROMPT.md 贴进助手,填上你的机型。
3. 电视上弹出"允许 USB 调试"时点允许,然后回答一份清单:平时用哪些 App、dock 放几个、要不要保留语音助手、Chromecast、系统更新。

必须 clone 的原因值得单独说:助手会复用仓库里的 tools/disable.sh 和 launcher/build-and-install.sh,而备份、Home 守卫、恢复记录这些安全机制全都在这两个脚本里。不 clone,助手就只能凭提示词自己写一套,那等于把安全网拆了。

路线 B,没有助手,自己敲。 工具只要 Python 3:

1
2
3
4
5

python3 -m venv tools/venv && tools/venv/bin/pip install -r tools/requirements.txt
export TV_HOST=192.168.1.50
tools/venv/bin/python -I tools/tv.py --probe            # 机型、Android 版本、固件
tools/venv/bin/python -I tools/tv.py 'pm list packages' # 在电视上跑一条 shell
TV_HOST=192.168.1.50 launcher/build-and-install.sh      # 构建桌面并接管 Home

tools/tv.py 是一个纯 Python 的 ADB 客户端,不依赖系统里的 adb 可执行文件——这不是洁癖,macOS 的本地网络隐私会直接拦掉 adb connect,作者干脆绕开它。只有"无线调试”、没有 5555 端口的机型(Chromecast with Google TV、Google TV Streamer)要先配对一次,再 adb tcpip 5555。Windows 下每个脚本旁边都有一个 PowerShell 双胞胎。仓库不提供预编译 APK,必须自己构建,官方给的理由是"你控制装到电视上的东西"。

路线 C,只有一台安卓手机。 社区里有人做了 Clean Your TV app,连上电视、先给方案、存恢复点、只关不卸,五分钟。它不是官方仓库的一部分,但 README 里明说了这条路的入口。

安全边界:它守的不是"不坏",是"不把自己关死"

• Home 守卫。脚本只会停用它认识的四类原桌面:com.google.android.tvlauncher、com.google.android.apps.tv.launcherx、com.google.android.leanbacklauncher,以及小米的 PatchWall com.mitv.tvhome。如果你的清单里包含当前拥有 Home 的那个包,而电视上又没有别的 App 能应答 HOME 键,脚本会跳过这一条并说明原因,先把其余包关掉,等你装好新桌面再跑一次。FORCE_HOME=1 可以强制关。
• Google TV 上的 setupwraith 是真正的雷。com.google.android.tungsten.setupwraith 会抢在已安装但还不是 Home 的桌面之前应答 HOME,禁用旧桌面以后它可能接管并让系统崩溃循环。更麻烦的是:如果家里的 Wi-Fi 是首次开机时由它保存的,禁用它等于把网络配置删掉。在 Chromecast 和 Google TV Streamer 上,还会顺带失去手机投屏。
• ADB 5555 是个明文端口。官方的说法很直白:有些固件上,同一个局域网里任何设备都能拿到 shell。所以干完活要按步骤关掉 USB 调试、网络调试、无线调试,撤销授权,重启,再跑 python3 tools/adb-closed.py <电视IP> 确认端口已经关掉(退出码 0 表示拒绝连接、1 表示还开着、2 表示没应答或检查本身没跑成)。
• 固件更新会推翻一切。升级包会覆盖在清理过的系统上,清单里的包回来、Home 回到原桌面,还会冒出新预装。有些清单干脆把更新服务也关了,那就意味着你要自己决定什么时候开回来。
• 合法性它自己划了线:只用开发者选项、ADB 和 Android 自带的 pm disable-user(跟设置里"停用应用"同一个开关),不 root、不刷机、不绕 DRM,但改装电视软件可能影响保修。

你的电视在不在名单里

345 个机型听起来很多,但摊到具体型号就不一定了。动手之前先搜你的型号,搜不到也不是不能做——PROMPT.md 的设计就是让助手自己去探测电视上有什么、在关之前问你。只是那份"关之前问你"的质量,取决于你回答得清不清楚。

和 Aerial 这类"只换桌面"的方案比

同一周还有另一个国产向项目:pengchujin/aerial-tv,7,264★,10 月 20 日建仓,MIT,官网 aerial.qust.me,同样不 root、不动系统应用。它的思路是只做桌面:下载 APK、按品牌开 ADB(小米/Redmi 在"账号与安全"里开 ADB 调试,TCL/雷鸟在"关于"里按上下左右,海尔在工厂菜单里开),装上以后开机自动接管。功能上它更"消费级":手机扫码整理桌面、114 段苹果航拍屏保、支持 Android TV 5.0+。

两条路不冲突:先用 CleanYourTV 关掉 PatchWall 和遥测,再换成你更喜欢的桌面,或者反过来只关不换。真正要先想清楚的是第二步——关掉旧桌面之前,你必须已经有一个能应答 HOME 的新桌面,这也是官方把顺序写死在脚本里的原因。

我的判断:谁该上,谁再等等,谁别碰

该上的。 家里是 Android TV 或 Google TV,尤其小米、Redmi 这类 PatchWall 机型,对首页推荐位和开机广告已经忍到极限的人。这个项目的价值不在桌面好看,而在于 345 份清单把"哪些包能关"这件事从玄学变成了一份可以对照的文本;你先看清单、再决定关哪几行,风险就可控。另一类是想远程帮父母弄的人:官方给了 Tailscale 的路径,但明确写了绝对不要在路由器上开 ADB 端口。

再等等的。 家里只有一台电视、还是全家唯一娱乐设备,而且没人愿意在出问题时花半小时恢复的人。中国版 TCL 也建议先翻清单头部,看有没有"拒绝安装桌面"的说明。Fire TV 用户如果目标是换桌面,这个项目给不了,只能做前半段。

别碰的。 三星 Tizen、LG webOS、Roku、Vizio、海信 VIDAA——不是难,是根本没有 ADB 这条路,硬试只会浪费时间。还在保修期内的新机,以及期待"一键彻底去广告"的人也别抱错期待:它管的是 Home 和预装,YouTube 视频里的广告不在此列;官方提过用 Private DNS 挡一部分,代价是那个 DNS 会看到电视发出的全部查询。

成本算下来很清楚:软件 0 元,有编码助手十五分钟、纯手工半小时到四十分钟,真正的成本是"读一遍你要关的清单"。十一天前它只是一个把父母家电视清理干净、顺手发在社交媒体上的对比图,今天变成三百多份可执行的机型清单。

如果你还想看看"让编码助手干具体活"这件事其他人在怎么做,站里给 AI 前端立闸门的那篇讲的是交付前怎么卡质量,以及装任何 skill 或脚本之前先看代码的那篇讲的审计方法——后者放在这件事上格外合适,因为你要跑的是一段会改电视系统的脚本。

本文由拾光札记编辑部整理,勘误请联系我们