# homebridge-agent-atv 中文文档

规范地址：https://npmcn.com/package/homebridge-agent-atv/

版本：0\.2\.0
npm 元数据更新时间：2026-11-03T17:43:44.080Z
中文译文更新时间：2026-11-03T21:03:26.759Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/homebridge-agent-atv
原文对照：https://npmcn.com/package/homebridge-agent-atv/?lang=original
项目主页：https://github.com/AlexDemzz/agent-atv/tree/main/packages/homebridge-agent-atv#readme
源码仓库：https://github.com/AlexDemzz/agent-atv

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：466 kB，76 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：^22\.12\.0 \|\| ^24\.0\.0 \|\| ^26\.0\.0
- 运行依赖：1 个
- 首次发布：2026-11-02T06:57:15.706Z
- 最新版本发布：2026-11-03T17:43:43.910Z
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

通过AI代理控制Apple TV：一个经过身份验证的HTTP API （pyatv bridge）、键盘输入、等待条件、可选的屏幕读取（焦点元素、截图）和一个最小的HomeKit TV配件。

## 安装

```sh
npm install homebridge-agent-atv
```

也可以使用：`pnpm add homebridge-agent-atv`、`yarn add homebridge-agent-atv`、`bun add homebridge-agent-atv`

## README

# homebridge-agent-atv

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

它补充了 [homebridge-appletv-enhanced](https://github.com/maxileith/homebridge-appletv-enhanced): 插件是关于HomeKit控制，这是一个API代理。两者可以并排运行。

完整的指南（设置、配对、屏幕阅读、CLI、安全性、故障排除）是 [主要的自述](https://github.com/AlexDemzz/agent-atv#readme)。

## 需求

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

## 配置

| 关键 | 默认的 | 意义 |
| --- | --- | --- |
| `api.port` | `8787` | HTTP API端口 |
| `api.bind` | `0.0.0.0` | 听地址，例如： `127.0.0.1`LAN IP或Tailscale IP |
| `api.token` | `""` | 覆盖生成的标记（32+字符） |
| `discovery.enabled` | `true` | 开始扫描，每5分钟扫描一次 |
| `discovery.hosts` | `[]` | 直接扫描的ip（其他子网，Tailscale） |
| `devices[]` | `[]` | 种每设备 `id`， `name`， `address`， `homekit` |
| `homekit.enabled` | `true` | 每个配对的Apple TV发布一个HomeKit电视配件 |
| `homekit.inputs` / `homekit.maxInputs` | `[]` / `12` | 应用程序暴露为电视输入 |
| `screen.enabled` | `false` | 屏幕阅读：前景应用程序，焦点元素，截图 |
| `python.executable` | `python3` | 用于构建venv的解释器 |
| `python.forceVenvRecreate` | `false` | 在下次开始重建venv |
| `debug` | `false` | 在信息级别记录调试行 |

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

HTTP API在 [DESIGN.md](https://github.com/AlexDemzz/agent-atv/blob/main/DESIGN.md#3-http-api-plugin)。

## 许可证

[麻省理工学院](https://github.com/AlexDemzz/agent-atv/blob/main/LICENSE)

## 常见问题

### homebridge-agent-atv 是什么？

通过AI代理控制Apple TV：一个经过身份验证的HTTP API （pyatv bridge）、键盘输入、等待条件、可选的屏幕读取（焦点元素、截图）和一个最小的HomeKit TV配件。

### 如何安装 homebridge-agent-atv？

在项目目录运行 npm install homebridge-agent-atv，或使用 pnpm add / yarn add / bun add。

### homebridge-agent-atv 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/homebridge-agent-atv 是否存在。

### homebridge-agent-atv 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### homebridge-agent-atv 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.12\.0 \|\| ^24\.0\.0 \|\| ^26\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### homebridge-agent-atv 可以商用吗？

homebridge-agent-atv 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### homebridge-agent-atv 还在维护吗？

最新版本 0\.2\.0 发布于 2026/11/04（今天）；至今共发布 5 个版本，其中过去 12 个月发布了 5 个；首次发布于 2026/11/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。