couch-tv Bridge 架构解析:Python 微服务如何通过 ADB 控制你的电视(完整指南)

原创2026-11-14 18:59:051,367 阅读

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 界面) 电视

couch-tv 电视主页效果:Night 场景下的玻璃时钟、续播栏与应用坞

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 这一个入口。

couch-tv 手机遥控器:Remote 标签页的按键区与 Watch 标签页的续播栏

多电视场景也很简单:每个请求可带 ?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 助手完全无感。

couch-tv 电视主页的设置界面:语言、外观场景、应用与人员均可在电视上直接修改

5️⃣ "播放 Bluey" 的完整链路:从名字到屏幕

对着手机说"put on Bluey",Bridge 内部经历了这样一条流水线:

  1. 查库:bridge/finder.py 调用 JustWatch 的公开 GraphQL 接口(无需 API key),查出这部剧在配置国家里由哪些平台提供,并拿到每个平台的 Android TV 深度链接(intent:// URI,bridge/finder.py#L30-L39)。
  2. 过滤:bridge/server.py 的 play() 只保留"这部剧能看、且该 App 已装在这台电视上"的候选;付费链接不会直接跳转购买页,而是打开商店页让人自己决定。
  3. 开播:优先走 ADB 的 am start 精确打开 intent 深度链接(可直接定位到指定季集);ADB 不可用时降级为打开 App 的搜索页。
  4. 验证:轮询 dumpsys 确认目标 App 真的出现在前台(wait_for_app,bridge/tv.py#L320-L329),才向手机报告 started: true。
  5. 续播:播过的进度、每人的观看历史都存在电脑本地 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️⃣ 上手路线:从哪几个文件开始读

想动手体验或深入源码,按这个顺序最高效:

  1. 跑起来:python3 -m venv .venv && .venv/bin/pip install -r bridge/requirements.txt(依赖只有 8 个包,见 bridge/requirements.txt),然后用 scripts/find-tvs.py 找出局域网里的电视。
  2. 配对:bridge/pair_tv.py 完成遥控器配对,加 --adb 再完成 ADB 授权。
  3. 启动:.venv/bin/python bridge/server.py,手机浏览器打开 http://<电脑名>.local:5400。
  4. 读契约:bridge/API.md 是理解一切请求响应的地图,改动都会先写在这里。
  5. 读核心:bridge/tv.py 双通道实现 → bridge/server.py 路由与编排 → bridge/finder.py 播控查询。

couch-tv 的 Bridge 用一个不到几千行的 Python 服务,把"手机一句话、电视放起来"这件事拆成了清晰的分层:HTTP API 是唯一门面,双通道是通往电视的腿,工厂函数换来了全品牌兼容,本地 AI 工具层负责最后的智能。如果你也想让电视拥有自己的主页和一个真正听话的遥控器,这套架构值得逐文件精读。

登录后查看全文
couch-tv