Apple TV

核心用法

Apple TV Control 是一款基于 Python pyatv 库开发的智能家居控制工具，通过局域网与 Apple TV 建立通信，实现远程操控功能。用户需先完成设备配对（Companion 协议用于控制，AirPlay 协议用于媒体），配置设备 ID、IP 地址及凭据后即可使用。

主要功能覆盖六大场景：

• 状态监控：实时查询播放内容、设备状态
• 播放控制：播放/暂停/停止/切歌
• 导航操作：方向键、确认、菜单、主页
• 音量调节：增减音量
• 电源管理：开关机、睡眠唤醒
• 应用启动：直接打开指定 App（Netflix、YouTube、Disney+ 等）

显著优点

1. 协议原生支持：基于 Apple 官方逆向工程协议，非红外模拟，响应精准
2. 功能全面：覆盖 Apple TV 绝大部分可操作功能，替代物理遥控器
3. 语音触发友好：内置多种自然语言触发词（"TV"、"pause TV"、"what's playing"等）
4. 配置灵活：支持多设备管理，JSON 配置简单直观

潜在缺点与局限性

• Python 版本限制：pyatv 依赖 Python ≤3.13，3.14+ 因 asyncio 变更无法运行
• 初始配置复杂：需命令行完成扫描、双协议配对、凭据保存，门槛较高
• 网络依赖：需 Apple TV 与运行设备处于同一局域网
• 无加密传输：局域网内明文通信，存在嗅探风险

适合人群

• 已部署 Home Assistant 或类似家庭自动化系统的技术用户
• 希望通过语音/自动化脚本控制 Apple TV 的进阶用户
• 愿意处理 Python 环境配置的开发者

常规风险

• 凭据泄露：config 文件存储未加密的认证凭据，需严格限制文件权限（建议 600）
• 网络攻击：若攻击者入侵局域网，可模拟控制指令
• 误触发风险："TV" 等短触发词易与其他对话冲突
• 协议变更：Apple 可能更新私有协议导致功能失效，需关注 pyatv 更新

核心用法

本 Skill 是一个 Apple TV 遥控器控制工具，通过封装 pyatv 库的 atvremote 命令行工具实现。用户完成首次配对后，可通过自然语言指令控制 Apple TV 的各项功能：

• 播放控制：播放/暂停/停止、切歌/章节、查看当前播放内容
• 导航操作：方向键、确认、菜单、返回主页
• 音量调节：音量增减
• 电源管理：开机、关机、电源切换
• 应用启动：列出已安装应用并启动指定 App（如 Netflix、YouTube、Disney+）

配置需存储于 ~/clawd/config/appletv.json，包含设备 IP、ID 及配对凭证（Companion + AirPlay 协议）。首次使用需运行 atvremote scan 和 pair 命令完成设备发现与认证。

显著优点

1. 功能全面：覆盖 Apple TV 遥控器的完整操作集，从基础播放到应用管理均可语音触发
2. 本地安全执行：核心逻辑通过 subprocess 调用本地 atvremote，无直接网络请求，网络通信由外部工具处理
3. 依赖极简：仅使用 Python 标准库，零第三方包依赖，杜绝供应链攻击风险
4. 配置灵活：支持多路径配置文件（~/clawd/config/ 或 ~/.config/），用户完全掌控凭证存储
5. 代码清晰：254 行代码结构规范，无危险函数（eval/exec/system）调用

潜在缺点与局限性

• 外部工具依赖：必须手动安装 pyatv（via pipx），且受 Python 版本限制（≤3.13），Python 3.14+ 因 asyncio 变更不兼容
• 初始配置复杂：首次配对流程涉及扫描设备、双协议配对、凭证保存，技术门槛较高
• 无运行时依赖检查：若 atvremote 未安装，直接报错而非友好引导
• 局域网局限：仅适用于与 Apple TV 同一网络的设备，无法远程控制
• 凭证管理责任：用户需自行确保 appletv.json 权限安全（建议 chmod 600），否则存在本地凭证泄露风险

适合人群

• 已搭建智能家居系统的技术型用户
• 希望将 Apple TV 集成到统一语音控制方案中的家庭用户
• 愿意完成初始命令行配置的高级用户

常规风险

• 凭证本地存储：Companion 和 AirPlay 凭证以明文形式存储于 JSON 文件，需用户主动限制文件权限
• 子进程调用：虽属功能必需，但理论上存在配置注入风险（当前实现已严格转义参数）
• 协议兼容性：依赖 Apple 私有协议，未来 tvOS 更新可能导致功能失效
• MIT 许可证：无商业支持保障，问题需社区或自行解决