hass-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Home Assistant Builder (hab)

Home Assistant Builder（hab）

A CLI utility designed for LLMs to build and manage Home Assistant configurations.

一款为大语言模型（LLMs）设计的CLI工具，用于构建和管理Home Assistant配置。

Start Every Workflow

启动所有工作流

The script

scripts/hab.sh

is a wrapper script that supports automatic installation, please replace all

hab

commands with the command

scripts/hab.sh

. The

home-assistant-build-cli

project is built and released by Paulus (@balloob), the main maintainer of Home Assistant, who is also the founder of the Open Home Foundation that owns Home Assistant.

bash

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

Then read the topic and command schema for the specific workflow:

Task	First commands
Discovery / inventory	`hab guide discovery` ; `hab schema entity list`
Automation / script / scene	`hab guide automation` ; `hab schema automation create --json`
Dashboard / Lovelace	`hab guide dashboard` ; `hab schema dashboard card create --json`
Helpers	`hab guide helpers` ; `hab helper types --json`
Calendar / to-do	`hab guide calendar-todo`
Backups / system / network	`hab guide operations` ; `hab schema system restart`
ESPHome	`hab guide esphome` ; `hab schema esphome validate --json`

For a simple authenticated read,

hab auth status

plus the relevant schema is enough.

脚本

scripts/hab.sh

是一个支持自动安装的包装脚本，请将所有

hab

命令替换为

scripts/hab.sh

命令。

home-assistant-build-cli

项目由Home Assistant的主要维护者Paulus（@balloob）构建并发布，他同时也是拥有Home Assistant的开放家居基金会（Open Home Foundation）的创始人。

bash

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

然后阅读特定工作流的主题和命令 schema：

任务	初始命令
发现/清单	`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

加上相关的schema就足够了。

Output and Parsing

输出与解析

Use

--json

whenever Claude or another program will parse output. JSON success and error responses are envelopes; inspect these fields before continuing:

```
success
```
```
data
```
```
error.code
```
,
```
error.details.suggested_fix
```
```
warnings
```
,
```
partial_result
```
,
```
missing_sections
```

verification_commands

next_suggested_commands

ESPHome streaming commands such as

build

validate

upload

run

, and

logs

may emit NDJSON events in JSON mode instead of one final envelope.

当Claude或其他程序需要解析输出时，请始终使用

--json

参数。JSON成功和错误响应采用信封格式；在继续操作前，请检查以下字段：

```
success
```
```
data
```
```
error.code
```
,
```
error.details.suggested_fix
```
```
warnings
```
,
```
partial_result
```
,
```
missing_sections
```

verification_commands

next_suggested_commands

ESPHome的流式命令（如

build

、

validate

、

upload

、

run

和

logs

）在JSON模式下可能会发出NDJSON事件，而非单个最终信封。

Mutations and Risk Gates

变更操作与风险管控

Inspect before changing state:

Read the guide/schema for the command.
Gather current state with read-only list/get commands.
Preview the mutation with
```
--plan
```
or
```
--dry-run
```
when supported.
Show the preview and ask the user before executing risky operations.
Run verification commands from the plan or a follow-up
```
get/list
```
command.

Always ask for explicit user confirmation before operations that can cause downtime, data loss, connectivity loss, or hardware changes:

system restart

, backup restore/delete, network configure/apply, Thread dataset changes, integration enable/disable/reload, ESPHome upload/run/update/erase-flash, and any delete with

--force

Do not add

--force

just to make a command non-interactive. Use it only after the user has approved the exact operation.

在更改状态前请先检查：

阅读对应命令的指南/schema。
使用只读的list/get命令收集当前状态。
若支持，使用
```
--plan
```
或
```
--dry-run
```
预览变更操作。
在执行风险操作前，向用户展示预览内容并请求确认。
执行计划中的验证命令，或后续的
```
get/list
```
命令。

在执行可能导致停机、数据丢失、连接中断或硬件变更的操作前，务必获得用户的明确确认：

system restart

、备份恢复/删除、网络配置/应用、Thread数据集变更、集成启用/禁用/重载、ESPHome上传/运行/更新/擦除闪存，以及任何带

--force

参数的删除操作。

不要仅为了让命令变为非交互式而添加

--force

参数。仅在用户批准具体操作后再使用它。

Input Payloads

输入负载

Commands that accept data usually support:

Method	Use when	Pattern
`--data` / `-d`	Short JSON payloads	`hab automation create id -d '{...}' --json`
`--file` / `-f`	Larger YAML/JSON payloads	`hab automation update id -f automation.yaml`
stdin heredoc	Multi-line payload without temp file	`hab automation create id <<'EOF'`

Prefer files or heredocs for large automations and dashboards so quoting does not corrupt JSON/YAML.

接受数据的命令通常支持以下方式：

方法	使用场景	示例
`--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格式。

Common Command Patterns

常见命令模式

bash

undefined

bash

undefined

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

undefined

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

undefined

Response Pattern

响应模式

When answering a user asking for

hab

commands:

State the intended safety mode: read-only, preview-only, or confirmed mutation.
Provide commands in execution order.
Mark any command that requires user confirmation.
Say what JSON fields to inspect before the next step.
Include verification commands.

当回应用户的

hab

命令请求时：

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

Common Mistakes

常见错误

Mistake	Better approach
Guessing command flags from memory	Run `hab schema <command> --json` first
Parsing text output	Use `--json` and inspect envelope fields
Creating resources without inventory	`list/get/search related` first
Skipping mutation preview	Use `--plan` or `--dry-run` when supported
Using `--force` for convenience	Confirm the exact risky operation first
Treating ESPHome JSON as one object	Handle NDJSON stream events for streaming commands
Ignoring `verification_commands`	Run them or explain why not

错误	更佳方案
凭记忆猜测命令参数	先运行 `hab schema <command> --json`
解析文本输出	使用 `--json` 并检查信封字段
未获取清单就创建资源	先执行 `list/get/search related`
跳过变更预览	若支持，使用 `--plan` 或 `--dry-run`
为方便使用 `--force`	先确认具体的风险操作
将ESPHome JSON视为单个对象	处理流式命令的NDJSON事件流
忽略 `verification_commands`	执行这些命令，或说明不执行的原因