名称： homey
描述： 通过本地（LAN/VPN）或云端 API 控制 Athom Homey 智能家居设备。可列出/控制设备、触发流程、查询区域。兼容 Homey Pro、Cloud 和 Bridge。
元数据： {"clawdbot":{"requires":{"bins":["homeycli"]},"install":[{"id":"homey-npm","kind":"node","package":".","bins":["homeycli"],"label":"安装 Homey CLI"}]}}

Homey 智能家居控制

通过本地（LAN/VPN）或云端 API，使用令牌认证控制 Athom Homey 设备。

设置

需要 Node.js >= 18。

1. 选择本地或云端模式

   • 本地模式（LAN/VPN）： 使用来自 Homey Web App 的本地 API 密钥和 Homey IP 地址。
   • 云端模式（远程/无头模式）： 使用来自开发者工具的云端令牌。

2. 配置

   本地模式（推荐在家庭网络中运行代理时使用）：

   ```bash
   homeycli auth discover-local --save --pick 1
   echo "" | homeycli auth set-local --stdin

   或交互式（隐藏输入）：homeycli auth set-local --prompt

   ```

   云端模式（推荐用于 VPS/无头托管）：

   ```bash
   echo "" | homeycli auth set-token --stdin

   或交互式（隐藏输入）：homeycli auth set-token --prompt

   ```

   检查状态：

   bash homeycli auth status

3. 测试连接

   bash homeycli status

命令

快照（推荐用于代理）

homeycli snapshot --json
homeycli snapshot --json --include-flows

列出设备

homeycli devices              # 美观的表格输出
homeycli devices --json       # 供 AI 解析的 JSON 输出（包含最新值）

# 按名称过滤（返回多个匹配项）
homeycli devices --match "kitchen" --json

控制设备

开关设备：

homeycli device "客厅灯" on
homeycli device "卧室台灯" off

设置特定能力：

homeycli device "调光灯" set dim 0.5                    # 50% 亮度
homeycli device "温控器" set target_temperature 21      # 设置温度
homeycli device "RGB 灯" set light_hue 0.5              # 色调 (0-1)
homeycli device "门锁" set locked true                  # 锁定设备

获取能力值：

homeycli device "温控器" get measure_temperature
homeycli device "运动传感器" get alarm_motion

# 获取设备的所有值（多传感器）
homeycli device "客厅空气质量" values
homeycli device "客厅空气质量" get

流程（自动化）

homeycli flows                        # 列出所有流程
homeycli flows --json                 # JSON 输出
homeycli flows --match "good" --json  # 按名称过滤流程
homeycli flow trigger "晚安模式"       # 按名称触发
homeycli flow trigger <流程ID>         # 按 ID 触发

区域（房间）

homeycli zones           # 列出所有区域/房间
homeycli zones --json    # JSON 输出

状态

homeycli status    # 显示 Homey 连接信息

常用能力

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

模糊匹配

设备和流程名称支持模糊匹配：
* 精确匹配： "客厅灯" → 找到 "客厅灯"
* 子字符串： "客厅" → 找到 "客厅灯"
* 莱文斯坦距离： "客听灯" → 找到 "客厅灯"（容错）

JSON 模式

在任何命令后添加 --json 以获得机器可读的输出：

homeycli devices --json | jq '.[] | select(.class == "light")'
homeycli status --json

示例

晨间例程：

homeycli device "卧室灯" on
homeycli device "卧室灯" set dim 0.3
homeycli device "温控器" set target_temperature 20

检查温度：

homeycli device "客厅" get measure_temperature

触发场景：

homeycli flow trigger "电影时间"

列出所有灯：

homeycli devices --json | jq '.[] | select(.class == "light") | .name'

故障排除

"未配置认证"

本地模式（LAN/VPN）：
* 保存本地配置：echo "<LOCAL_API_KEY>" | homeycli auth set-local --address http://<homey-ip> --stdin

云端模式（远程/无头）：
* 保存云端令牌：echo "<CLOUD_TOKEN>" | homeycli auth set-token --stdin
* 云端令牌可在 Homey 开发者工具中创建：https://tools.developer.homey.app/api/clients

"未找到设备" / 匹配不明确
* 使用 homeycli devices --json（或 homeycli devices --match <查询> --json）列出设备以找到正确的 id
* 如果查询匹配多个设备，CLI 将返回候选 ID 并要求您通过 ID 指定设备

"不支持的能力"
* 检查可用能力：homeycli devices 显示每个设备支持的能力
* 常见问题：尝试打开传感器（应使用 get 而非 set）

API 参考

CLI 使用官方的 homey-api npm 包 (v3.15.0)。

认证/连接模式：

• 本地模式： 使用 Homey Web App 本地 API 密钥，通过 HomeyAPI.createLocalAPI({ address, token }) 创建。
• 云端模式： 使用云端持有者令牌（PAT）通过 AthomCloudAPI 创建会话并访问设备/流程/区域。