tv.py 是什么

进入第 4 章，我们开始和 tools/ 目录里的工具链打交道。第一个登场的是 tv.py——项目自带的纯 Python ADB 客户端。说它"纯 Python"，意思是它不依赖官方 adb 可执行文件，用 Python 实现了与电视通信所需的 ADB 协议。整个工具链的连接底座，就是它。

ADB（Android Debug Bridge，安卓调试桥）是安卓设备的标准调试通道，CleanYourTV 的绝大多数操作——列应用、禁用应用、推文件、重启——最终都通过这条通道完成。tv.py 的使命，就是把这条通道装进一个跨平台、零外部依赖的脚本里。

为什么不用官方 adb

既然 ADB 是标准协议，为什么不直接装官方 adb？项目文档给出的理由很实际：在 macOS 上，系统的隐私与安全策略可能挡住官方 adb 二进制文件，用户要么和系统设置斗智斗勇，要么干脆用不了。tv.py 用纯 Python 重写了客户端，绕开了这层阻碍——在 macOS 上也能直接跑。

除此之外，自带客户端还有两个好处：一是行为可控，脚本之间调用时不必猜外部依赖装没装；二是接口统一，工具链里的其他脚本（disable.sh、recovery.py 等）都以它为基础通道，行为一致、排障路径一致。

在连接安全上，tv.py 支持完成配对后的 Google ADB 加密后端。也就是说，电视端按 ct-0303 完成配对授权后，后续通信走加密通道，与系统级 ADB 的安全级别对齐，不会因为"纯 Python"而打折扣。

上手前的三个认知

在把 tv.py 用熟之前，先建立三个认知，能省掉后面大半的困惑。

第一，tv.py 跑在电脑上，不跑在电视上。它的角色是遥控器，电视是被遥控的对象，所以你的电脑必须和电视在同一个网络里，这是一切命令生效的大前提；电视端要做的，只是提前打开无线调试并完成授权。第二，每条命令都以连接参数开头，先拨号、再说话：--ip 加电视地址是最基本的形态，端口不是通常的 5555 时，再按 --help 的说明补上端口参数。顺序固定下来，命令就不会记串。第三，--help 是最终裁判。本书给出的形态覆盖日常场景，但工具的参数以它自己输出的帮助信息为准；拿不准的时候，运行一次 python3 tools/tv.py --help，比翻任何教程都可靠。

功能一览

tv.py 把常用 ADB 操作收拢成一组子命令，形态统一：先给连接参数，再给子命令。

子命令 用途 预期看到什么
shell 在电视上执行命令 命令输出回显到对话框
batch 批量执行多条命令 逐条命令及其输出
push 从电脑上传文件到电视 传输完成的反馈，文件出现在电视侧
pull 从电视下载文件到电脑 本地出现对应文件
reboot 重启电视 电视黑屏并重新启动
截图 抓取电视当前画面 本地生成截图文件

此外，部分用法支持先按遥控键再执行命令——比如先按 HOME 键把电视唤醒到首页，再执行后续操作。这在电视休眠导致命令无响应的场景下很实用，具体参数形态以工具内 --help 输出为准。

基本连接形态

所有命令共享同一个连接前缀：先指定电视 IP，再指定要做的动作。最基本的探活命令是这样：

python3 tools/tv.py --ip 192.168.1.50 shell

拆开看：python3 tools/tv.py 是运行工具本体；--ip 192.168.1.50 告诉它电视的门牌号（换成你电视的真实 IP，见 ct-0302）；shell 是子命令，进入电视的命令行。如果电视的 ADB 端口不是通常的 5555，连接参数里还需要指定端口——具体参数名与写法以工具内 --help 和仓库 README 为准，不要凭感觉拼。

各子命令示例与预期

  1. 探活：python3 tools/tv.py --ip 192.168.1.50 shell。预期：连接成功后进入电视的 shell 环境，出现命令提示符，输入 exit 可退出。如果卡住不动，回到 ct-0303 的排查表。
  2. 批量执行：python3 tools/tv.py --ip 192.168.1.50 batch（配合清单文件使用）。预期：逐条输出执行结果，适合一次查多项状态。
  3. 上传文件：python3 tools/tv.py --ip 192.168.1.50 push <本地文件> <电视路径>。预期：传输完成，电视侧路径出现该文件。参数顺序以 --help 为准。
  4. 下载文件：python3 tools/tv.py --ip 192.168.1.50 pull <电视文件> <本地路径>。预期：本地路径出现该文件，常用于把备份记录取回来。
  5. 重启：python3 tools/tv.py --ip 192.168.1.50 reboot。预期：电视黑屏重启，几分钟后回到首页。执行前确认没有未完成的改动。
  6. 截图：python3 tools/tv.py --ip 192.168.1.50 screenshot（截图相关子命令名以 --help 为准）。预期：本地生成一张当前电视画面的图片，排查界面问题时比口头描述直观得多。

以上命令中的尖括号部分是占位符，实际使用时替换成真实路径；不确定的参数一律以工具内 --help 和仓库 README 为准，这是本书对所有工具的通用约定。

一条命令的旅程

理解 tv.py 的工作过程，排障时才能对症下药。当你在电脑上敲下 python3 tools/tv.py --ip 192.168.1.50 shell 并回车，接下来发生的事可以分成四步：电脑先解析参数，把目标地址和要做的动作分清楚；随后通过 ADB 协议向电视的 ADB 端口发起连接；电视侧校验这台电脑是否在已授权名单里，校验通过，通道建立；最后你的命令在电视的 shell 环境里执行，输出沿着同一条通道原路返回到你的屏幕上。

这四步也对应了四类典型的卡壳：参数解析问题表现为命令直接报错；连接问题表现为超时；授权问题表现为电视毫无反应或提示未授权；执行问题表现为命令能进、结果不对。下次遇到故障，先问自己"卡在哪一步"，再对照下文排障速查表，八九不离十。

在工具链中的位置

tv.py 不是孤胆英雄，它是整条工具链的"腿"：

flowchart LR
    A[tv.py 连接通道] --> B[disable.sh]
    A --> C[restore.sh]
    A --> D[recovery.py]
    A --> E[check.py]
    A --> F[b64push.py]
    A --> G[theme.sh]
    B --> H[电视上的 pm disable-user]
    C --> H
    D --> I[恢复记录]
    E --> J[固件升级核对]
    F --> K[大文件分块上传]
    G --> L[主题推送]

理解这张图，就理解了第 4 章的组织方式：tv.py 负责"连上去"，其余脚本负责"干什么"。AI 助手流程（第 3 章）里你感知不到 tv.py 的存在，是因为助手在替你调用它；手动进阶时，它就是你手中的方向盘。

排障速查

现象 先查什么
连接超时 IP、端口、无线调试开关、同一 Wi-Fi（ct-0303 排查表）
命令发出无回显 电视是否休眠；尝试先按 HOME 键再执行
文件上传中断 换 b64push.py 分块上传，见 ct-0404
助手（沙箱环境）连不上 用 relay.py 做端口转发，见 ct-0404
子命令参数记不清 python3 tools/tv.py --help，以实际输出为准

常见问题

问：tv.py 和官方 adb 能混用吗？

答：可以，两者协议一致。但为减少变量，一次操作尽量只用其一；混用时注意授权状态是跟着"电脑"走的，换客户端一般不需要重新授权。

问：为什么强调 macOS？

答：因为项目的 tv.py 方案最初就是为了解决 macOS 上官方 adb 被系统隐私策略挡住的问题。Windows 与 Linux 上当然也能用，一份脚本通吃三个平台正是它的优势。

问：--help 里参数比本书讲的多，要紧吗？

答：不要紧。本书只覆盖精简流程用得到的部分；高级参数留给有需要的人，用时以 --help 与 README 为准。

问：tv.py 能在电视上直接运行吗？

答：不能。它是电脑侧的工具，通过 ADB 通道遥控电视。电视端不需要安装任何东西，需要它做的只是在设置里打开无线调试并授权你的电脑。

问：截图生成的文件保存在哪里？

答：默认落在你运行命令时的当前目录（具体路径与命名以 --help 为准）。想换个地方存，就在运行前切换到你想要的目录，或按 --help 的说明指定输出位置。

小结

tv.py 是工具链的连接底座：纯 Python 实现，跨平台，在官方 adb 被挡的 macOS 上也能用，支持配对后的加密后端。掌握一个基本形态 python3 tools/tv.py --ip 192.168.1.50 shell，就掌握了与电视对话的起点。下一篇 ct-0402，我们看真正干活的两位：disable.sh 与 restore.sh。