使用 hab/Home Assistant CLI…

在通过 `hab`/`scripts/hab.sh` CLI 检查、创建、更新、删除、操作或排障 Home Assistant 资源时使用。

适用场景

解决思路

1. 将所有 `hab` 命令替换为 `scripts/hab.sh`（该 wrapper 支持自动安装）。
2. 可先执行 `alias hab='scripts/hab.sh'`，以便后续按 `hab` 形式调用。
3. 开始每个工作流先运行 `hab guide list`。
4. 开始每个工作流先运行 `hab guide auth`。
5. 开始每个工作流先运行 `hab schema overview`。
6. 开始每个工作流先运行 `hab capability probe`。
7. Discovery / inventory：先运行 `hab guide discovery`，再运行 `hab schema entity list`。
8. Automation / script / scene：先运行 `hab guide automation`，再运行 `hab schema automation create --json`。
9. Dashboard / Lovelace：先运行 `hab guide dashboard`，再运行 `hab schema dashboard card create --json`。
10. Helpers：先运行 `hab guide helpers`，再运行 `hab helper types --json`。
11. Calendar / to-do：先运行 `hab guide calendar-todo`。
12. Backups / system / network：先运行 `hab guide operations`，再运行 `hab schema system restart`。
13. ESPHome：先运行 `hab guide esphome`，再运行 `hab schema esphome validate --json`。
14. 对于简单的已认证读取，执行 `hab auth status` 加相关 schema 即可。
15. 当 Claude 或其他程序会解析输出时，使用 `--json`。
16. 检查 JSON 成功/错误 envelope 的 `success` 字段。
17. 检查 `data` 字段。
18. 检查 `error.code` 和 `error.details.suggested_fix` 字段。
19. 检查 `warnings`、`partial_result`、`missing_sections` 字段。
20. 检查 `verification_commands`、`next_suggested_commands` 字段。
21. ESPHome 流式命令 `build`、`validate`、`upload`、`run`、`logs` 在 JSON 模式可能输出 NDJSON 事件，而不是单个最终 envelope。
22. 改变状态前，先阅读该命令的 guide/schema。
23. 改变状态前，用只读 list/get 命令收集当前状态。
24. 改变状态前，在支持时用 `--plan` 或 `--dry-run` 预览变更。
25. 改变状态前，展示预览并在执行风险操作前询问用户。
26. 改变状态后，运行计划中的验证命令或后续 get/list 命令。
27. 对可能导致停机、数据丢失、连接丢失或硬件变更的操作，总是要求明确用户确认：`system restart`、backup restore/delete、network configure/apply、Thread dataset changes、integration enable/disable/reload、ESPHome upload/run/update/erase-flash，以及任何带 `--force` 的 delete。
28. 不要仅为让命令非交互而添加 `--force`；仅在用户批准确切操作后使用。
29. 短 JSON payload 使用 `--data` 或 `-d`，模式：`hab automation create id -d '{...}' --json`。
30. 更大的 YAML/JSON payload 使用 `--file` 或 `-f`，模式：`hab automation update id -f automation.yaml`。
31. 多行 payload 且不想用临时文件时使用 stdin heredoc，模式：`hab automation create id <<'EOF'`。
32. 大型 automations 和 dashboards 优先使用文件或 heredocs，避免引号破坏 JSON/YAML。
33. 认证与实例检查命令：`hab auth status`。
34. 认证与实例检查命令：`hab overview`。
35. 认证与实例检查命令：`hab capability probe`。
36. 实体 inventory 命令：`hab entity list --domain light`。
37. 实体 inventory 命令：`hab entity get light.kitchen --device --related`。
38. 实体 inventory 命令：`hab search related entity light.kitchen`。
39. 安全 mutation 预览命令：`hab schema area create --json`。
40. 安全 mutation 预览命令：`hab area create "Kitchen" --plan`。
41. 安全 mutation 预览后执行：`hab area create "Kitchen"`。
42. Automation 创建流程：`hab guide automation`。
43. Automation 创建流程：`hab schema automation create --json`。
44. Automation 创建流程：`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`。
45. Operations 流程：`hab guide operations`。
46. Operations 流程：`hab system health --json`。
47. Operations 流程：`hab system restart --plan`。
48. Operations 流程：`hab backup list`。
49. Operations 流程：`hab backup delete <backup_id> --plan`。
50. 当回答用户询问 `hab` 命令时，说明预期安全模式：read-only、preview-only 或 confirmed mutation。
51. 当回答用户询问 `hab` 命令时，按执行顺序提供命令。
52. 当回答用户询问 `hab` 命令时，标记任何需要用户确认的命令。
53. 当回答用户询问 `hab` 命令时，说明下一步前要检查哪些 JSON 字段。
54. 当回答用户询问 `hab` 命令时，包含验证命令。
55. 不要凭记忆猜命令 flags；先运行 `hab schema <command> --json`。
56. 不要解析文本输出；使用 `--json` 并检查 envelope 字段。
57. 不要在无 inventory 的情况下创建资源；先执行 `list/get/search related`。
58. 不要跳过 mutation 预览；支持时使用 `--plan` 或 `--dry-run`。
59. 不要为了方便使用 `--force`；先确认确切风险操作。
60. 不要将 ESPHome JSON 当作单个对象；对 streaming commands 处理 NDJSON 流事件。
61. 不要忽略 `verification_commands`；运行它们或解释为什么不运行。

适用边界 · 注意事项

• 没有 Home Assistant 实例、无法安装或运行 `scripts/hab.sh` / `hab` CLI 时，不适用。
• 需要完全无人值守且不能对高风险操作做用户确认时，不适用。
• 只需普通 shell 操作或非 Home Assistant 配置管理时，不适用。