homey

用途

Homey 智能家居控制工具用于通过本地（LAN/VPN）或云端 API 控制 Athom Homey 设备，采用令牌认证方式。它适合在本机网络内运行的智能体（Agent），或部署在 VPS/无头主机上的场景，对 Homey 设备、自动化流程和房间区域进行统一操控。

主要能力

• 快照（Snapshot）：homeycli snapshot --json 输出整体状态，可选 --include-flows，适合智能体读取。
• 设备列表：homeycli devices 以表格输出，--json 输出 JSON（包含最新值），--match "kitchen" 可按名称模糊筛选。
• 设备控制：开关设备（homeycli device "Living Room Light" on / off），设置能力值，如 set dim 0.5（亮度）、set target_temperature 21（温度）、set light_hue 0.5（色相）、set locked true（锁）。
• 读取能力值：get measure_temperature、get alarm_motion，以及 values / get 获取设备全部数值。
• Flows（自动化）：homeycli flows 列出全部流程，--json 与 --match 支持过滤，flow trigger "Good Night" 或按 ID 触发。
• Zones（房间）：homeycli zones 列出区域，支持 --json。
• 状态查询：homeycli status 显示连接信息。

使用方式

需要 Node.js >= 18。连接方式分两种：

• 本地（LAN/VPN）：使用 Homey Web App 的本地 API key 加 Homey IP 地址。

  homeycli auth discover-local --save --pick 1
  echo "<LOCAL_API_KEY>" | homeycli auth set-local --stdin
  # 或交互式：homeycli auth set-local --prompt
  

• 云端（远程/无头）：使用 Developer Tools 生成的云端 token。

  echo "<CLOUD_TOKEN>" | homeycli auth set-token --stdin
  # 或交互式：homeycli auth set-token --prompt
  

检查认证：homeycli auth status；测试连接：homeycli status。所有命令可加 --json 获得机器可读输出，例如 homeycli devices --json | jq '.[] | select(.class == "light")'。

设备与流程名称支持模糊匹配：精确匹配、子串匹配以及 Levenshtein 距离（容错拼写错误）。若查询匹配到多个设备，CLI 会返回候选 ID 并要求按 ID 指定。

常见能力（Capabilities）

• onoff（布尔）：电源开关，如 true / false
• dim（数值）：亮度 0-1，如 0.5（50%）
• light_hue（数值）：色相 0-1，如 0.33（绿色）
• light_saturation（数值）：饱和度 0-1，如 1.0
• light_temperature（数值）：色温 0-1，如 0.5（中性）
• target_temperature（数值）：恒温器目标温度（°C），如 21
• measure_temperature（数值，只读）：当前温度
• locked（布尔）：锁状态，如 true / false
• alarm_motion（布尔，只读）：检测到移动
• alarm_contact（布尔，只读）：接触传感器
• volume_set（数值）：音量 0-1，如 0.5

使用 homeycli devices 查看每个设备支持的能力。

适用场景

• 家庭网络内的智能体自动化（推荐本地模式）。
• VPS 或无头主机上的远程控制（推荐云端模式）。
• 通过 JSON 输出与脚本、AI 解析或 jq 结合进行批处理。

限制与说明

• 本地模式需要 Homey IP 地址与本地 API key；云端模式需要云端 token。
• 只读能力需用 get，尝试对传感器使用 set 会报错（例如“Capability not supported”）。
• 云端 token 可在 Homey Developer Tools 创建：https://tools.developer.homey.app/api/clients
• 基于官方 homey-api npm 包（v3.15.0）；本地模式通过 HomeyAPI.createLocalAPI({ address, token })，云端模式通过 AthomCloudAPI 使用 bearer token（PAT）建立会话。
• 常见故障：未配置认证（“No auth configured”）、设备未找到或匹配歧义（“Device not found”/ambiguous match）、能力不支持（“Capability not supported”）。

关于支持的平台范围、具体价格与更多设备兼容性等细节，资料暂未提供。