核心用法
Homey CLI 是一个基于 Node.js 的命令行工具，用于通过 Athom 官方 Cloud API 远程控制 Homey 智能家居系统。用户需先在开发者平台创建 Personal Access Token，通过环境变量或配置文件完成认证后即可使用。
主要功能模块：
- 设备控制：开关、调光、调色温、设置温度、门锁控制等，支持模糊名称匹配和精确 ID 操作
- 状态查询：实时获取传感器数据（温度、湿度、运动检测等），JSON 输出便于 AI 解析
- 流程自动化：列出并触发 Homey Flows，实现场景化控制（如"晚安模式""观影模式"）
- 区域管理：查询房间/区域信息
- 快照功能：一键导出全屋设备状态和流程配置，适合 AI Agent 做上下文感知
典型工作流：
# 早间场景 homeycli device "Bedroom Light" on homeycli device "Thermostat" set target_temperature 20 homeycli flow trigger "Good Morning"
显著优点
1. 官方 API 支持：基于 Athom 官方 homey-api npm 包（v3.15.0），非逆向工程，稳定性有保障
2. 模糊匹配友好：支持 Levenshtein 距离的 typo-tolerant 搜索，"livng light" 也能正确识别
3. JSON 管道化：所有命令支持 --json 输出，与 jq 等工具链无缝集成，适合自动化脚本
4. 跨平台兼容：支持 Homey Pro（本地）、Homey Cloud（云端）、Homey Bridge（桥接）三种形态
5. 能力模型清晰：标准化 capability 系统（onoff、dim、target_temperature 等），设备行为可预测
潜在缺点与局限性
1. Token 管理负担：Bearer token 长期有效，泄露风险高；无 OAuth 刷新机制，需手动轮换
2. 单 Homey 限制：默认连接用户第一个 Homey，多设备家庭需显式指定 ID
3. 网络依赖：Cloud API 模式需外网连接，本地 Pro 版若配置不当也可能走云端
4. 功能边界：不支持创建/修改 Flows，仅支持触发；不支持设备配对或删除
5. 调试门槛：模糊匹配冲突时需人工介入选择设备 ID，纯自动化场景可能中断
适合人群
- 已有 Homey 生态的中高级用户，追求脚本化/自动化控制
- 需要将智能家居接入自研 AI Agent 或家庭服务器的开发者
- 习惯命令行工作流、熟悉 Node.js 工具链的技术用户
- 希望跨平台统一管理 Homey Pro/Cloud/Bridge 的多设备用户
常规风险
| 风险类型 | 描述 | 缓解建议 |
|---------|------|---------|
| **凭证泄露** | Bearer token 存储于环境变量或明文 JSON，权限等同于完整账户 | 使用专用低权限 token，避免提交到版本控制，定期轮换 |
| **误操作触发** | 模糊匹配可能命中非预期设备（如"Bedroom"匹配到"Bedroom Light"和"Bedroom Fan"） | 生产脚本使用设备 ID 而非名称，或添加确认逻辑 |
| **网络中间人** | Cloud API 走 HTTPS，但本地 Pro 版若配置 HTTP 代理可能被窃听 | 验证 TLS 证书，避免使用明文 HTTP 代理 |
| **速率限制** | 频繁轮询可能触发 Athom API 限流 | 合理使用快照缓存，避免高频状态查询 |
| **设备状态竞争** | 多客户端（App + CLI + 自动化）同时操作可能导致状态不一致 | 设计幂等操作，或引入 Homey 原生 Flows 做仲裁 |