Homey

核心用法

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 做仲裁 |

核心用法

Homey CLI 是 Athom Homey 智能家居系统的官方命令行控制工具，通过 Cloud API 实现设备管理、场景触发和环境监控。核心工作流分为三步：

1. 认证配置：从 Athom 开发者平台 获取 Personal Access Token，通过 HOMEY_TOKEN 环境变量或 ~/.homey/config.json 配置
2. 设备发现：使用 homeycli snapshot --json 获取全屋设备快照，或 homeycli devices --match "关键词" --json 模糊搜索特定设备
3. 精准控制：支持开关 (onoff)、调光 (dim 0-1)、色温/色相 (light_temperature/light_hue)、温控 (target_temperature)、门锁 (locked) 等常见能力值

关键特性包括：模糊匹配（支持 typo-tolerant 的 Levenshtein 距离算法）、JSON 模式（便于 AI 解析和 jq 处理）、Flow 触发（场景自动化）。

显著优点

• 官方生态：基于 homey-api v3.15.0 官方 SDK，API 兼容性有保障
• 全平台覆盖：支持 Homey Pro、Homey Cloud、Homey Bridge 三种形态
• 安全设计：Token 通过环境变量/配置文件传入，无硬编码凭证；全链路 HTTPS/WSS 加密
• 开发者友好：JSON 输出配合 jq 可实现复杂查询，如过滤所有灯光设备

潜在局限

• 云依赖：所有控制指令需经由 Athom 云端，非纯本地方案；断网或 Athom 服务故障时不可用
• T3 来源：由个人开发者 Max Sumrall 维护，非官方 Athom 或知名组织背书，长期维护稳定性需观察
• 无内置限流：批量操作可能触发 Athom API 速率限制
• Token 管理：需手动管理 90 天轮换周期，无自动刷新机制

适合人群

• Homey 重度用户：已通过 Homey 构建全屋智能，需要脚本化/自动化扩展
• 极客玩家：熟悉命令行和 jq，希望将智能家居集成到现有 CLI 工作流
• AI Agent 开发者：需要结构化（JSON）方式控制实体设备，构建语音/LLM 交互场景

常规风险

| 风险项 | 说明 | 缓解建议 |

|--------|------|----------|

| Token 泄露 | Bearer Token 拥有设备控制权 | 使用密码管理器存储，定期轮换，避免提交到 Git |

| 云服务商风险 | Athom 云服务可用性影响设备控制 | 评估本地 API 方案作为备选 |

| 权限边界 | Token 默认拥有全设备访问权限 | Athom 平台可创建受限权限 Token |

| 供应链安全 | 依赖 4 个 npm 包（homey-api、commander、chalk、cli-table3）| 启用 Dependabot 监控 |

安全认证评分 S 级（92分），代码无危险函数、无恶意行为，但来源可信度为 T3（个人开发者），建议生产环境使用前进行代码审查。