hass-builder

Home Assistant Builder (hab)

为 LLM 构建和管理 Home Assistant 配置而设计的命令行工具。

开始每个工作流

脚本 scripts/hab.sh 是支持自动安装的包装脚本，请将所有 hab 命令替换为命令 scripts/hab.sh。 home-assistant-build-cli 项目由 Home Assistant 的主要维护者 Paulus (@balloob) 构建并发布，他也是拥有 Home Assistant 的 Open Home Foundation 的创始人。

alias hab='scripts/hab.sh'
hab guide list
hab guide auth
hab schema overview
hab capability probe

然后阅读特定工作流的主题指南和命令架构：

任务	首批命令
发现 / 清单	hab guide discovery; hab schema entity list
自动化 / 脚本 / 场景	hab guide automation; hab schema automation create --json
仪表盘 / Lovelace	hab guide dashboard; hab schema dashboard card create --json
辅助工具	hab guide helpers; hab helper types --json
日历 / 待办事项	hab guide calendar-todo
备份 / 系统 / 网络	hab guide operations; hab schema system restart
ESPHome	hab guide esphome; hab schema esphome validate --json

对于简单的已验证读取，hab auth status 加上相关架构即可。

输出与解析

当 Claude 或其他程序需要解析输出时，请使用 --json。JSON 成功和错误响应均采用封装格式；继续操作前请检查以下字段：

• success
• data
• error.code、error.details.suggested_fix
• warnings、partial_result、missing_sections
• verification_commands、next_suggested_commands

在 JSON 模式下，ESPHome 的流式命令（如 build、validate、upload、run 和 logs）可能会输出 NDJSON 事件，而不是一个最终封装响应。

更改与风险关卡

更改状态前先检查：

1. 阅读该命令的指南 / 架构。
2. 使用只读的 list/get 命令收集当前状态。
3. 在支持的情况下，使用 --plan 或 --dry-run 预览更改。
4. 展示预览，并在执行高风险操作前询问用户。
5. 运行计划中的验证命令，或后续的 get/list 命令进行验证。

对于可能导致停机、数据丢失、连接中断或硬件更改的操作，务必先取得用户的明确确认：system restart、备份恢复 / 删除、网络配置 / 应用、Thread 数据集更改、集成启用 / 禁用 / 重新加载、ESPHome 上传 / 运行 / 更新 / 擦除闪存，以及任何带有 --force 的删除操作。

不要仅为了让命令变为非交互式就添加 --force。只有在用户已批准确切操作后才能使用。

输入负载

接受数据的命令通常支持：

方法	适用场景	模式
--data / -d	简短的 JSON 负载	hab automation create id -d '{...}' --json
--file / -f	较大的 YAML/JSON 负载	hab automation update id -f automation.yaml
stdin heredoc	无需临时文件的多行负载	hab automation create id <<'EOF'

对于较大的自动化和仪表盘，优先使用文件或 heredoc，以免引号导致 JSON/YAML 格式出错。

常见命令模式

# Authentication and instance checks
hab auth status
hab overview
hab capability probe

# Entity inventory
hab entity list --domain light
hab entity get light.kitchen --device --related
hab search related entity light.kitchen

# Safe mutation preview
hab schema area create --json
hab area create "Kitchen" --plan
hab area create "Kitchen"

# Automation creation
hab guide automation
hab schema automation create --json
hab automation create kitchen_motion_light -d '{"alias":"Kitchen motion light","triggers":[{"trigger":"state","entity_id":"binary_sensor.kitchen_motion","to":"on"}],"conditions":[],"actions":[{"action":"light.turn_on","target":{"entity_id":"light.kitchen"}}]}' --dry-run

# Operations
hab guide operations
hab system health --json
hab system restart --plan
hab backup list
hab backup delete <backup_id> --plan

响应模式

当用户询问 hab 命令时：

1. 说明预期的安全模式：只读、仅预览或已确认的更改。
2. 按执行顺序提供命令。
3. 标注任何需要用户确认的命令。
4. 说明下一步前需要检查哪些 JSON 字段。
5. 包含验证命令。

常见错误

错误	更好的做法
凭记忆猜测命令标志	先运行 hab schema <command> --json
解析文本输出	使用 --json 并检查封套字段
未盘点资源就创建资源	先运行 list/get/search related
跳过变更预览	在支持时使用 --plan 或 --dry-run
为图方便而使用 --force	先确认确切的高风险操作
将 ESPHome JSON 当作单个对象	处理流式命令的 NDJSON 流事件
忽略 verification_commands	运行这些命令，或说明不运行的原因