homebridge-agent-atv

一个Homebridge插件，可以让人工智能代理驱动苹果电视。它公开了一个经过身份验证的HTTP API agent-atv CLI与：远程键，应用程序启动， 键盘文本输入，等待条件，电量，音量，查找和可选屏幕阅读（聚焦） 元素，以及屏幕截图)。它还发布了一个最小的HomeKit电视配件。

它补充了 homebridge-appletv-enhanced: 插件是关于HomeKit控制，这是一个API代理。两者可以并排运行。

完整的指南（设置、配对、屏幕阅读、CLI、安全性、故障排除）是 主要的自述。

需求

• Homebridge 1.8或2。x, Node.js 22.12+， 24或26。
• Python 3.10到3.13中的 venv 模块(sudo apt-get install python3-venv 在Debian/Ubuntu上)和 OpenSSL 3.0 +。第一次启动插件创建自己的虚拟环境 <storage>/agent-atv/.venv 然后安装固定 pyatv 0.18.0依赖于 PyPI。这在树莓派上只需要几分钟。
• 屏幕读取（可选）：大约350 MB <storage>/agent-atv/.venv-screen，约100 MB 每台苹果电视的内存。在Python 3.10-3.12中，安装只编译一个包，所以主机需要 build-essential python3-dev libssl-dev （Debian/Raspberry Pi OS）。

设置

1. 从Homebridge UI安装插件(或 npm i -g homebridge-agent-atv)，并添加平台。

2. 打开插件设置。网络上的Apple tv出现在设备表中。点击 一对，然后输入 密码显示在电视上。该插件首先配对同伴，然后AirPlay如果同伴凭证 不适合AirPlay（第二个PIN），然后当它打开时屏幕读取（另一个PIN）。检查 还支持屏幕读取 在配对之前从那里打开它。

3. 从同一页面复制API令牌，然后在代理的机器上：

   npm i -g agent-atv
   agent-atv config set url http://<homebridge-host>:8787
   agent-atv config set token -     # paste the token, Enter, Ctrl-D
   agent-atv doctor
   

安全

API是带有承载令牌的普通HTTP。这个令牌可以完全远程控制每台配对的苹果电视。

• 首选将API绑定到主机的API Tailscale 知识产权(api.bind)，用于加密 交通。在局域网中，任何可以嗅探网络的人都可以读取令牌。
• 令牌存储在 <storage>/agent-atv/token （模式0600），并显示在插件设置中。它是 从来没有记录。要旋转它，请删除该文件并重新启动Homebridge，或设置 api.token (32 +字符)。
• 配对证书保留 <storage>/agent-atv/devices/ (0600)模式。它们从不出现在日志和API中 响应或设置UI。
• 没有遥测：这个插件只与你的苹果电视和PyPI对话，同时安装它的固定包。

配置

HomeKit配件作为外部配件发布：将它添加到Home应用中 添加配件>更多选项 以及Homebridge的设置代码。

HTTP API在 DESIGN.md。

许可证

麻省理工学院