Home Assistant 技能

通过位于 {baseDir}/scripts/homeassistant-cli.py 的 Python CLI 工具，使用 Home Assistant REST API 控制智能家居设备。无需外部依赖——仅使用 Python 标准库。

设置

通过环境变量或命令行参数进行配置（参数优先级更高）：

bash

可选：环境变量

通过参数传递（覆盖环境变量）

使用任意命令的 --help 查看详情：python3 {baseDir}/scripts/homeassistant-cli.py light --help

安全规则

在以下操作前务必与用户确认： 锁定/解锁门锁，布防/撤防报警面板，打开/关闭车库门或大门，禁用安全自动化。

命令参考

所有命令遵循格式：python3 {baseDir}/scripts/homeassistant-cli.py [--server URL] [--token TOKEN] [args]

发现与状态

bash
check # 检查 API 连接
entities # 列出所有实体
entities --domain light # 按域列出实体（light、switch、sensor 等）
state # 获取完整实体状态 JSON
areas # 列出所有区域
area-entities [--domain light] # 区域内的实体，可选过滤
area-of # 查找实体所属区域
floors # 列出所有楼层及其区域
services [--domain light] # 列出可用服务
dashboard # 快速概览：灯光状态、门、温度、门锁、人员
presence [--trackers] # 谁在家（--trackers 用于设备追踪器）
weather [--forecast daily|hourly] [-e entity] # 当前天气或预报

设备控制

bash
switch on|turnoff|toggle>
light on|turnoff> [--brightness 80] [--rgb 255,150,50] [--color-temp 300]
fan on|turnoff> [--percentage 50]
cover position> id> [--position 50]
lock
media pause|volume> id> [--level 0.5]
vacuum
climate temp|setmode> [--temperature 72] [--mode auto]
alarm home|disarm> id> [--code 1234]
scene

自动化与脚本

bash
automation [entity_id]
script [entity_id] [--variables {key: value}]

通知

bash
notify list # 列出通知目标
notify send message [--title title] # 发送通知

输入辅助

bash
input boolean # 切换
input number # 设置数值
input select option # 设置选择
input text value # 设置文本
input datetime 07:30:00 # 设置时间

日历与 TTS

bash
calendar list # 列出日历
calendar events [--days 14] # 即将到来的事件
tts entity> player_entity> message # 文本转语音

模板、历史与日志

bash
template {{ states.light | list | count }} lights # 评估 Jinja2
history [--start ISO8601] [--end ISO8601] # 状态历史
logbook [--entity entity_id] [--limit 20] # 日志条目

模板函数：states()、isstate()、stateattr()、areas()、areaentities()、areaname()、floors()、floorareas()、labels()、labelentities()、devices()、deviceentities()、now()、relativetime()。

通用服务调用

bash
service --data {entityid: light.livingroom}

批量：传递实体 ID 数组

特斯拉

实体：sensor.maodoubattery、devicetracker.maodoulocationtracker、devicetracker.maodoudestinationlocationtracker、automation.teslabatterybelow20

bash
tesla battery # 电池电量
tesla location # GPS 坐标、方向、速度
tesla destination # 目的地位置
tesla automations # 列出特斯拉相关实体

实体域

HTTP 状态码

注意事项

• - 长期令牌不会过期——请安全存储
• 先用 entities --domain 测试实体 ID
• 对于专用命令未覆盖的操作，使用 service 命令
• 服务调用返回受影响实体状态的 JSON 数组；错误信息输出到 stderr