核心用法
本 Skill 是围绕 pyatv（atvremote）和 Airfoil 的轻量级工作流封装，专为 macOS 用户设计，用于发现并控制 Apple 媒体生态系统设备：
- 设备发现：通过
./scripts/scan.sh或./scan-json.js扫描本地网络，获取 HomePod、Apple TV、AirPlay 音箱的 IP、设备 ID 和型号信息 - 音箱控制（推荐路径）：集成 Airfoil Skill，提供可靠的 HomePod/AirPlay 音箱连接、断开和音量调节，避免 pyatv 的认证限制
- Apple TV 遥控：使用
atvremote执行播放控制（play_pause）、电源管理（turn_on/off）及状态查询（playing）
显著优点
1. 双工具互补设计：pyatv 负责设备发现和 Apple TV 深层控制，Airfoil 专攻音频路由，扬长避短
2. 开箱即用的脚本封装：提供扫描、连接、音量调节等 Shell/Node 脚本，降低命令行操作门槛
3. JSON 结构化输出：scan-json.js 将扫描结果转为机器可读的设备清单，便于自动化集成
潜在局限
- HomePod 控制受限：pyatv 对 HomePod 的播放/音量控制常需认证配对，功能不完整，必须回退到 Airfoil
- macOS 独占：依赖 Airfoil 和 pyatv 的特定平台实现，无法跨平台使用
- Python 版本锁定：需固定 Python 3.12 运行环境，规避 3.14 的 asyncio 兼容性问题
- 网络环境依赖：设备发现依赖 mDNS/Bonjour，复杂网络（VLAN隔离、多子网）可能导致扫描失败
适合人群
- macOS 深度用户，已拥有 HomePod/Apple TV/AirPlay 音箱生态
- 希望通过脚本或自动化工具（如 Alfred、Raycast、Hammerspoon）快捷控制客厅媒体设备的效率用户
- 智能家居集成开发者，需将 Apple 设备纳入现有自动化工作流
常规风险
| 风险项 | 说明 |
|--------|------|
| 网络暴露 | 扫描和控制命令在本地网络明文传输（部分设备支持加密配对） |
| 认证凭证 | Apple TV 配对可能生成持久化凭证，需妥善存储避免泄露 |
| 误操作风险 | 音量脚本无二次确认，过高音量可能损伤设备或听力 |
| 依赖维护 | pyatv 需跟进 tvOS/iOS 协议变更，存在未来兼容性风险 |