couch-tv Bridge 架构解析:Python 微服务如何通过 ADB 控制你的电视(完整指南)
couch-tv Bridge 架构解析:Python 微服务如何通过 ADB 控制你的电视(完整指南)
couch-tv 是一个开源的自制 Google TV 家庭主页与手机遥控器项目,其核心是一个运行在家用电脑上的 Python 微服务——bridge(桥接服务)。它通过 Android TV Remote 协议与 ADB 双通道连接电视,实现开关机、音量、按键、一键开播等控制。这篇文章带你拆解 couch-tv Bridge 的完整架构:数据如何从手机流向电视、ADB 在其中扮演什么角色、一个服务又如何同时支持 10 多个品牌的电视。
1️⃣ 什么是 couch-tv Bridge:一个常驻电脑的 Python 小服务
couch-tv 有三种运行方式,Bridge 是其中「方式 B」的核心:
| 方式 | 说明 | 是否需要 Bridge |
|---|---|---|
| A. 仅 TV 主页 | 新主页装在电视上,用原电视遥控器 | ❌ |
| B. 电脑 Bridge | 主页 + 手机遥控器 + "播放 Bluey" 语音点播 + 跨应用续播 | ✅ 一台常开电脑 |
| C. 住在电视上 | Bridge 逻辑打包进电视 App,无需电脑 | ❌ |
在方式 B 中,一台 Mac、Linux 主机或树莓派长期运行一个 Python 服务,成为手机遥控器、电视主页和 AI 助手与电视之间的唯一通道。整个项目的分工如下(各模块职责一览见 docs/HOW-IT-WORKS.md):
| 目录 | 角色 | 运行位置 |
|---|---|---|
| bridge/ | Python 微服务,唯一与电视对话的组件 | 常开的家用电脑 |
| remote/ | 手机遥控器(Web App,装进手机浏览器) | 手机 |
| tv-home/ | 电视主页(Android TV 应用 + Web 界面) | 电视 |
2️⃣ 整体数据流:一个 HTTP 服务是通往电视的唯一路径
Bridge 的入口是 bridge/server.py,一个基于 aiohttp 的异步 HTTP 服务,默认监听 5400 端口(见 bridge/server.py#L51)。它同时承担三件事:
/—— 托管手机遥控器(remote/dist/)/tv/—— 托管电视主页(tv-home/web/)/api/*—— 核心 REST 接口,完整契约写在 bridge/API.md
/api/ 下大约有 50 个端点,涵盖:/api/now(当前在放什么)、/api/key(按键)、/api/volume、/api/play(点播)、/api/power(开关机)、/api/screenshot(截图)、/api/ask(AI 助手)等。每个响应都是统一的 JSON 结构:成功 {"ok": true, ...},失败 {"ok": false, "error": "简短原因"}。
官方文档一句话点明了架构铁律(bridge/API.md#L3):"The bridge is the only thing that talks to the TV"——手机和电视主页从不直连电视,全部请求经过 Bridge 这一个入口。
多电视场景也很简单:每个请求可带 ?tv=<id> 指定目标电视,服务内部用 Python 的 contextvars 为每个请求绑定当前电视,状态(正在播放、休眠计时器等)按电视隔离(bridge/server.py#L57-L95)。
3️⃣ 双通道控制电视:Android TV Remote + ADB over Wi-Fi
这是 Bridge 架构最精彩的部分。bridge/tv.py 的模块注释开门见山:一条电视连接,两条通道。
通道一:Android TV Remote 协议 v2(基础遥控器)
基于 androidtvremote2 库,走电视的 6466 端口。首次使用 bridge/pair_tv.py 在电视屏幕上输入一个 6 位配对码,为该电脑生成证书(bridge/data/cert.pem),之后这条通道长期可用。它能做到:
- 发送所有遥控器按键(方向、OK、返回、音量、电源……键名映射表在 bridge/tv.py#L61-L73)
- 读取电源状态、当前前台应用、音量
- 发送文本输入(手机遥控器打字)
- 打开 https 链接
通道二:ADB over Wi-Fi(进阶能力)
couch-tv 没有调用系统里的 adb 可执行程序,而是用纯 Python 的 adb-shell 库直连电视的 5555 端口(bridge/tv.py#L381-L407),用该电脑自己的 ~/.android/adbkey 密钥认证——这样连 macOS 的本地网络权限问题都绕开了。ADB 提供了遥控器协议给不了的能力:
| 能力 | 实现方式 |
|---|---|
| 按包名精确启动任意应用 | monkey -p <package>(bridge/tv.py#L414-L423) |
| 打开深度链接(直达某集) | am start + intent:// URI(bridge/tv.py#L425-L448) |
| 截图 | exec-out screencap -p(bridge/tv.py#L501-L509) |
| 已装应用列表 | pm list packages |
| 当前屏幕真实前台应用 | dumpsys activity activities(比协议上报快得多) |
优雅降级与命令注入防护
- 降级:ADB 是可选的。没开 ADB 时,遥控器按键、音量、开关机全部可用,只是"精确开播、截图"等进阶功能退化为打开整个 App(模块注释原话:"everything still works without it, just less")。
- 防护:任何会传进电视 shell 的包名都必须先过正则白名单
check_package,只允许字母.数字.下划线形式的 Android 包名——这是针对一次真实漏洞(畸形包名注入 shell 命令)加的护栏(bridge/tv.py#L30-L43)。 - 自愈:电视断电重连、Wi-Fi 换 IP,都有后台任务每 3 秒探测端口、断线自动重连(bridge/tv.py#L204-L224)。
4️⃣ 一个服务接 10+ 品牌电视:make_tv 工厂模式
Google TV 之外的电视不用 ADB,各有各的网络控制协议。Bridge 用一个轻量工厂函数 make_tv 按配置分发(bridge/server.py#L63-L90):
kind: "samsung" → bridge/samsung.py
kind: "lg" → bridge/lg.py
kind: "roku" → bridge/roku.py
kind: "vidaa" → bridge/vidaa.py
kind: "philips" → bridge/philips.py(Titan OS / Saphi)
kind: "vega" → bridge/vega.py
kind: "vizio" → bridge/vizio.py
kind: "panasonic"→ bridge/panasonic.py
kind: "tivo" → bridge/tivo.py
kind: "appletv" → bridge/appletv.py
(缺省) → bridge/tv.py(Android/Google TV,即上面的双通道)
每个品牌一个文件,各自封装官方网络接口(如 Samsung 的 Remote Access、LG 的 webOS 协议、Roku 的 ECP),但对上层暴露统一的方法签名。这就是为什么 config.example.json 里加一台卧室电视只需几行配置,而手机遥控器、/api/ 接口、AI 助手完全无感。
5️⃣ "播放 Bluey" 的完整链路:从名字到屏幕
对着手机说"put on Bluey",Bridge 内部经历了这样一条流水线:
- 查库:bridge/finder.py 调用 JustWatch 的公开 GraphQL 接口(无需 API key),查出这部剧在配置国家里由哪些平台提供,并拿到每个平台的 Android TV 深度链接(
intent://URI,bridge/finder.py#L30-L39)。 - 过滤:bridge/server.py 的
play()只保留"这部剧能看、且该 App 已装在这台电视上"的候选;付费链接不会直接跳转购买页,而是打开商店页让人自己决定。 - 开播:优先走 ADB 的
am start精确打开 intent 深度链接(可直接定位到指定季集);ADB 不可用时降级为打开 App 的搜索页。 - 验证:轮询
dumpsys确认目标 App 真的出现在前台(wait_for_app,bridge/tv.py#L320-L329),才向手机报告started: true。 - 续播:播过的进度、每人的观看历史都存在电脑本地
bridge/data/,电视主页的 Keep watching 栏和"继续观看"按钮都从这里取数,全程不出家门。
不同 App 的深度链接脾气各异(有的直达剧集、有的只有 App 内搜索),各家的适配细节汇总在 bridge/DEEPLINKS.md。
6️⃣ 可选扩展:Claude 助手与 MCP 工具层
想玩"放点搞笑的"这种模糊指令,Bridge 提供了一个可选的 AI 层,设计上有两条巧思:
- 本地子进程,不走官方 API:bridge/claude.py 直接调用你本机的
claude -p命令行(用你自己的 Claude 订阅),并刻意剥离ANTHROPIC_API_KEY,工作目录也挪到工作区之外——电视请求永远不会加载你的 agent 钩子。 - MCP 工具只是 HTTP 薄封装:bridge/mcp_server.py 把
now、play、key、volume、launch等工具全部实现为对 Bridge 自身 HTTP API 的一次调用,保证"只有 Bridge 能碰电视"的铁律不被 AI 打破。 - 眼睛和手:bridge/agentic.py 通过 ADB 的
uiautomator dump把屏幕读成文本(ui工具)并按标签点击(tap),让 Claude 能处理"打开 App 里某节目"这类需要看屏幕的任务;同时有硬性红线——不付费、不注册、不输密码,遇到登录/付款页就停下交还给人。
7️⃣ 安全设计:为什么这个 Bridge 可以放心放在家庭网络
Bridge 只在局域网明文 HTTP 运行(官方明确要求绝不做端口转发到公网),但针对"家里还有别的设备"的场景做了多层防护(详见 bridge/API.md):
- 配对密钥:
config.json里设置pairing_key后,受保护端点需 Bearer Token;错误密钥连续 5 次的地址会被限流 1 分钟(429)。 - DNS rebinding 防护:
Host头是 Bridge 不认识的名字直接 403。 - CORS 白名单:只允许 Bridge 自身来源、本地开发端口和 TV Web 容器的特殊 Origin(
null、file://),恶意网页的跨域请求到不了处理函数。 - 数据私有:配置在
config.json、密钥在.env、观看历史在bridge/data/,三者全部被 git 忽略,永不上传(bridge/config.py#L33-L37)。
8️⃣ 上手路线:从哪几个文件开始读
想动手体验或深入源码,按这个顺序最高效:
- 跑起来:
python3 -m venv .venv && .venv/bin/pip install -r bridge/requirements.txt(依赖只有 8 个包,见 bridge/requirements.txt),然后用 scripts/find-tvs.py 找出局域网里的电视。 - 配对:bridge/pair_tv.py 完成遥控器配对,加
--adb再完成 ADB 授权。 - 启动:
.venv/bin/python bridge/server.py,手机浏览器打开http://<电脑名>.local:5400。 - 读契约:bridge/API.md 是理解一切请求响应的地图,改动都会先写在这里。
- 读核心:bridge/tv.py 双通道实现 → bridge/server.py 路由与编排 → bridge/finder.py 播控查询。
couch-tv 的 Bridge 用一个不到几千行的 Python 服务,把"手机一句话、电视放起来"这件事拆成了清晰的分层:HTTP API 是唯一门面,双通道是通往电视的腿,工厂函数换来了全品牌兼容,本地 AI 工具层负责最后的智能。如果你也想让电视拥有自己的主页和一个真正听话的遥控器,这套架构值得逐文件精读。


