名称： homey-cli
描述： 通过命令行控制 Homey 家庭自动化中心。适用于需要控制智能家居设备（灯光、温控器、插座等）、检查设备状态、列出区域、触发流程或执行任何 Homey 自动化任务的场景。支持开关、调光、颜色调节、温度控制及设备查看。仅允许安全且经过能力白名单验证的操作。

Homey CLI

安全、适配智能助手的命令行工具，用于控制 Homey 家庭自动化中心。

功能概览

• 设备控制：开关设备、调光、调节颜色、设置温度
• 设备查看：列出设备、检查状态、读取能力值
• 区域管理：列出区域及各区域内的设备
• 流程控制：列出并触发自动化流程
• 整体概览：获取家庭中心的完整信息摘要

设置步骤

1. 安装依赖

cd skills/homey-cli
npm install

2. 创建 Homey 应用凭据

1. 访问 https://tools.developer.homey.app/tools/app
2. 创建一个新应用，需设置：
   - 回调 URL：http://localhost:8787/callback
   - 记录下你的 客户端 ID 和 客户端密钥

3. 配置环境变量

创建 .env 文件：

export HOMEY_CLIENT_ID="你的客户端ID"
export HOMEY_CLIENT_SECRET="你的客户端密钥"
export HOMEY_REDIRECT_URL="http://localhost:8787/callback"

4. 登录授权

bash run.sh auth login

在浏览器中完成 OAuth 授权流程。授权令牌将保存在 ~/.config/homey-cli/ 目录下。

使用指南

列出 Homey 设备

bash run.sh homey list

选择当前使用的 Homey

bash run.sh homey use <homeyId>

设备操作

# 列出所有设备
bash run.sh devices list

# 以 JSON 格式列出设备
bash run.sh devices list --json

# 查看特定设备详情
bash run.sh devices get <deviceId>

# 读取设备能力值
bash run.sh devices read <deviceId> onoff

# 控制设备
bash run.sh devices on <deviceId>
bash run.sh devices off <deviceId>
bash run.sh devices dim <deviceId> 0.4
bash run.sh devices color <deviceId> #FF8800
bash run.sh devices temperature <deviceId> 21.5

流程操作

# 列出所有自动化流程
bash run.sh flows list

# 触发特定流程
bash run.sh flows trigger <flowId>

获取完整清单

bash run.sh inventory --json

安全机制

为确保安全，写入操作均受 能力白名单 限制：

• 默认允许的能力：onoff、dim、light_hue、light_saturation、light_temperature、target_temperature
• 自定义白名单：通过 export HOMEY_CLI_ALLOWED_CAPABILITIES=onoff,dim,target_temperature 覆盖

不支持 任何破坏性操作（如删除设备、修改流程、更改应用设置）。

常见查询示例

当用户提出以下请求时，可对应操作：
- “打开厨房灯” → 列出设备，找到对应设备，执行 devices on <deviceId>
- “将客厅灯光调暗至 50%” → 找到设备，执行 devices dim <deviceId> 0.5
- “卧室温度是多少？” → 找到设备，执行 devices read <deviceId> measure_temperature
- “列出我所有的灯” → 使用 devices list --json 并按设备类别或能力进行筛选

配置存储位置

• 授权令牌：~/.config/homey-cli/credentials.json
• 当前 Homey：~/.config/homey-cli/config.json

故障排除

• 授权错误：重新运行 bash run.sh auth login
• 找不到设备：使用 bash run.sh devices list 核对设备名称或 ID
• 能力不被允许：将其添加到 HOMEY_CLI_ALLOWED_CAPABILITIES 环境变量，或确认该能力是否为只读