两个"工程向"工具

tools/ 里的脚本大多面向电视本身，唯有 b64push.py 与 relay.py 面向"路"：一个管大文件怎么送过 ADB 通道，一个管助手够不着局域网时怎么把路牵过来。日常精简未必天天用到它们，但真遇到卡壳，没有它们还真过不去。

工具 解决的问题 关键词
b64push.py 大文件（如 APK）上传慢、易中断、无校验 base64 分块、checksum 校验
relay.py 沙箱助手够不到你的局域网 本地端口转发、只监听本机

b64push.py：大文件的安全绳

为什么大文件要特殊照顾

精简电视时偶尔要往电视上传大文件——比如你想自己装某个 launcher 或附加模块的 APK。直接推送大文件有几个老问题：通道慢，一个几百兆的文件能传到天荒地老；中途网络抖动就断，断了重头再来；传完了也不知道文件在电视侧是否完整，checksum 对不上就是白忙。

b64push.py 的思路是"化整为零、逐块校验"：把文件内容转成 base64，切成小块分批经 ADB 通道送达，电视侧重接收、重组，最后用 checksum 校验完整性。块传坏了只需重传那一块，不用整个文件推倒重来；校验通过，才算数。

使用步骤

  1. 连接就绪，用 tv.py 探活确认通道正常：python3 tools/tv.py --ip 192.168.1.50 shell。
  2. 记下本地大文件的路径和电视侧目标路径。
  3. 在项目根目录运行：
python3 tools/b64push.py <本地文件> <电视目标路径>

（参数名与写法以工具内 --help 和仓库 README 为准。）

  1. 盯着输出。预期看到：分块上传的进度反馈，一块块推进；全部传完后，进入 checksum 校验阶段，最终输出"校验通过"一类的结论（措辞以实际输出为准）。

校验失败怎么办

现象 处理
某一块反复失败 网络不稳，靠近路由器或换个时段再传
校验不通过 按脚本机制重传；连续失败先检查电视存储空间
电视空间不足 先在电视上清理空间，再重传

一个经验：上传前在电脑侧自己先算一遍文件 checksum（工具会给出算法与用法，以 --help 为准），与电视侧校验值互相对照，双保险。

使用场景提醒

常规的精简流程不涉及上传 APK——项目的核心是停用预装，不是装新东西。b64push.py 主要服务两类需求：一是手动安装 launcher 或 add-on 的场景（配合 ct-0405 的构建产物），二是你有自己的应用想推进电视时。日常用户知道有这把榔头即可，不必急着用。

relay.py：沙箱助手的桥

场景从哪儿来

第 3 章我们让 AI 助手全程代劳，但有一种环境会让助手"半身不遂"：助手运行在沙箱里，够不到你的局域网。它能读项目文件、能分析命令，但它的网络请求出不了沙箱，自然连不上 192.168.1.50 那台电视。

relay.py 就是为这个场景设计的桥：它把本机的一个端口转发到电视的 ADB 端口，让沙箱里的助手通过 localhost 间接连上电视。你在桥的这头，电视在桥的那头，助手走桥。

安全设计：只监听本机

端口转发听起来有点敏感，relay.py 的处理是收敛的：它只监听本机，不对局域网其他设备暴露。也就是说，这条桥只有你和跑在同一台电脑上的助手能走，外部设备扫描不到这个端口。桥随用随搭，用完随关，不给"后门"留时间窗。

使用步骤

  1. 先确认电脑本身能连电视（不搭桥时的直连）：python3 tools/tv.py --ip 192.168.1.50 shell 能进，说明通道没问题。
  2. 在项目根目录运行 relay.py，把本地端口指向电视的 ADB 端口（端口与参数写法以 --help 为准）：
python3 tools/relay.py
  1. 预期看到：脚本报告转发已建立，给出类似"本机某端口已转发到电视 ADB 端口"的提示（措辞以实际输出为准）。
  2. 让助手把连接目标改成本机的转发端口（IP 用 localhost 或 127.0.0.1），按第 3 章流程继续。预期：助手侧命令不再超时，能正常与电视对话。
  3. 流程结束或不再需要转发时，关掉 relay.py 进程。预期：转发断开，电视侧 ADB 通道随之关闭（或按第 3 章收尾方式关闭无线调试）。

使用纪律

纪律 理由
只在本机需要时开启 桥存在的时间越短，暴露面越小
用完立即关闭 防止后续流程误走这条通道
不把本地端口暴露给局域网 relay 只监听本机，别用额外手段改掉这个设定
转发前确认电视授权状态 授权是电视说了算，桥不改变授权边界

两把工具的对照

维度 b64push.py relay.py
作用对象 文件 网络端口
解决痛点 大文件上传慢、断、无校验 沙箱够不到局域网
使用时机 上传 APK 等大文件时 助手在沙箱环境时
关键保障 base64 分块 + checksum 只监听本机、用完即关
日常频率 低 低

常见问题

问：不用 relay.py，沙箱助手就完全没法工作吗？

答：可以变通：你在电脑这头执行助手给的命令，把输出贴回给它，人工当"中继"。慢，但可行。relay.py 的价值就是把这种"人肉中继"自动化。

问：relay.py 转发出去的数据，别的设备能截获吗？

答：它只监听本机，同一台电脑上的程序才连得到。ADB 通道本身在完成配对后是加密的（见 ct-0401），所以即使看在眼里，内容也是加密的。

问：b64push.py 只能传 APK 吗？

答：不是，任何大文件都适用。只是 APK 是这类场景里最典型的文件，项目文档才拿它举例。

小结

b64push.py 与 relay.py 是工具链的"工程补丁"：一个用分块加校验驯服大文件传输，一个用本机端口转发把沙箱助手牵到电视跟前。两者都不常驻你的日常流程，但请在工具箱里给它们留好位置——第 4 章的最后一篇 ct-0405，我们来看构建侧的两件套：docker-build.sh 与 theme.sh。