homeassistant-ops

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Home Assistant Ops

Home Assistant 运维操作

Use this skill as the operator's playbook for making bulk, reviewable changes to a Home Assistant instance without SSHing into the host.

Requires Node.js 22+ (uses built-in

fetch

WebSocket

; no npm deps).

将此工具作为运维手册使用，无需通过SSH登录主机，即可对Home Assistant实例进行可审核的批量变更。

要求 Node.js 22+（使用内置的

fetch

WebSocket

；无需npm依赖）。

Default workflow (plan -> apply -> validate)

默认工作流（规划 -> 应用 -> 验证）

Inventory the current state (API) and/or registries (backup).
Propose an explicit change set (entity_ids, names, automation ids, etc).
Apply via API with validation (small batches, dry-run first).
Smoke-test the specific behavior (traces + event tail).
Record a timestamped log + a rollback mapping.
(Optional) Snapshot before/after for diff/rollback.

盘点当前状态（通过API）和/或注册表（通过备份）。
提交明确的变更集（entity_id、名称、自动化ID等）。
通过API应用变更并验证（小批量执行，先进行试运行）。
对特定行为进行冒烟测试（跟踪记录 + 事件实时监控）。
记录带时间戳的日志 + 回滚映射表。
（可选）在变更前后创建快照，用于差异对比/回滚。

Setup

安装配置

Set environment variables (never pass tokens on the command line):

bash

export HA_URL="http://<home-assistant-host>:8123"
export HA_TOKEN="<long-lived-access-token>"

Run scripts using

node

bash

node scripts/ha_ops.js --help

Keep logs in a working folder (scripts write timestamped

.md

files by default).

设置环境变量（切勿在命令行中传递令牌）：

bash

export HA_URL="http://<home-assistant-host>:8123"
export HA_TOKEN="<long-lived-access-token>"

使用

node

运行脚本：

bash

node scripts/ha_ops.js --help

将日志保存在工作目录中（脚本默认会写入带时间戳的

.md

文件）。

First questions (to avoid rework)

前期确认问题（避免重复工作）

What's the HA version and deployment type (OS / Container / Core)?
Which Zigbee stack is used (ZHA vs Zigbee2MQTT) and which devices are affected?
Which parts are YAML-managed vs UI-managed (automations, scripts, scenes, dashboards)?
Do we have a recent backup to inspect before making bulk changes?
Is the goal UI clarity, automation correctness, performance/latency, or all of the above?

当前HA版本和部署类型是什么（OS / 容器 / 核心版）？
使用的是哪种Zigbee栈（ZHA vs Zigbee2MQTT），哪些设备会受影响？
哪些部分是通过YAML管理的，哪些是通过UI管理的（自动化、脚本、场景、仪表板）？
我们是否有最近的备份可在进行批量变更前检查？
目标是提升UI清晰度、确保自动化正确性、优化性能/延迟，还是以上所有？

Core concepts (what to change where)

核心概念（变更位置说明）

Entity registry: source of truth for friendly-name overrides, entity_id renames, hidden/disabled, and some area assignment.
Device registry: best place to assign areas for physical devices (entity area often inherits).
Blueprint inputs: not templatable; state triggers need a static entity list at config-load time.
HA "group helpers": great for UI/targeting/maintenance, but they don't make Zigbee unicast faster (they expand to member calls).

实体注册表：是友好名称覆盖、entity_id重命名、隐藏/禁用以及部分区域分配的可信数据源。
设备注册表：是为物理设备分配区域的最佳位置（实体区域通常会继承此设置）。
蓝图输入：不支持模板化；状态触发器需要在配置加载时使用静态实体列表。
HA「群组助手」：非常适合UI展示、目标定位和维护，但无法提升Zigbee单播速度（它们会展开为对成员设备的调用）。

Scripts

脚本说明

All scripts read

HA_URL

and

HA_TOKEN

from environment variables.

所有脚本均从环境变量中读取

HA_URL

和

HA_TOKEN

。

ha_ops.js

- Single CLI with subcommands

ha_ops.js

- 包含子命令的单一CLI工具

All operations are available under a single CLI:

bash

undefined

所有操作均可通过单一CLI执行：

bash

undefined

List commands

列出所有命令

node scripts/ha_ops.js --help

Command help

查看命令帮助

node scripts/ha_ops.js cleanup --help

undefined

node scripts/ha_ops.js cleanup --help

undefined

ha_ops.js cleanup

- Bulk cleanup (dry-run by default)

ha_ops.js cleanup

- 批量清理（默认试运行）

bash

undefined

bash

undefined

Dry-run all default steps (default)

试运行所有默认步骤（默认行为）

node scripts/ha_ops.js cleanup

Apply specific steps

应用指定步骤

node scripts/ha_ops.js cleanup --apply
--steps rename-switch-suffix,prefix-lights-cove

Prefix custom patterns with area names

用区域名称为自定义模式添加前缀

node scripts/ha_ops.js cleanup --apply
--steps prefix-generic
--pattern "Thermometer:^Thermometer"
--pattern "Blinds:^Blinds"

Output proposed changes as JSON

以JSON格式输出拟变更内容

node scripts/ha_ops.js cleanup --json


Available steps:

- `rename-switch-suffix`: Rename "Lights ... Switch" to "Lights ..."
- `create-groups`: Create/update switch groups for sync automations
- `prefix-lights-cove`: Prefix Lights/Cove names with area
- `prefix-generic`: Prefix entities matching `--pattern` with area

node scripts/ha_ops.js cleanup --json


可用步骤：

- `rename-switch-suffix`: 将「Lights ... Switch」重命名为「Lights ...」
- `create-groups`: 为同步自动化创建/更新开关群组
- `prefix-lights-cove`: 为灯光/嵌入式灯带名称添加区域前缀
- `prefix-generic`: 为匹配`--pattern`的实体添加区域前缀

ha_ops.js snapshot

- Capture state for diffing

ha_ops.js snapshot

- 捕获状态用于差异对比

bash

undefined

bash

undefined

Full snapshot

完整快照

node scripts/ha_ops.js snapshot

Skip noisy sections

跳过冗余部分

node scripts/ha_ops.js snapshot
--no-lovelace --no-scenes

Include runtime states (noisy for diffs)

包含运行时状态（会增加差异对比的冗余信息）

node scripts/ha_ops.js snapshot --include-states

undefined

node scripts/ha_ops.js snapshot --include-states

undefined

ha_ops.js rollback

- Revert registry changes from a snapshot

ha_ops.js rollback

- 通过快照还原注册表变更

bash

undefined

bash

undefined

Preview what would be rolled back

预览将回滚的内容

node scripts/ha_ops.js rollback
snapshot_before.json --dry-run

Apply rollback

执行回滚

node scripts/ha_ops.js rollback
snapshot_before.json --yes

undefined

node scripts/ha_ops.js rollback
snapshot_before.json --yes

undefined

ha_ops.js find-references

- Find entity_id usage

ha_ops.js find-references

- 查找entity_id的使用情况

bash

undefined

bash

undefined

Search for entity references before renaming

重命名前搜索实体引用

node scripts/ha_ops.js find-references
--needle "switch.bedroom_lights"

Search from a rename mapping file

通过重命名映射文件搜索

node scripts/ha_ops.js find-references
--map-json rename_map.json --backup-root /path/to/backup

undefined

node scripts/ha_ops.js find-references
--map-json rename_map.json --backup-root /path/to/backup

undefined

ha_ops.js tail-events

- Monitor events in real-time

ha_ops.js tail-events

- 实时监控事件

bash

undefined

bash

undefined

Tail state changes

跟踪状态变更

node scripts/ha_ops.js tail-events

Filter to specific entities

过滤特定实体

node scripts/ha_ops.js tail-events
--entity switch.bedroom_lights --entity switch.bedroom_lights_2

Include ZHA events

包含ZHA事件

node scripts/ha_ops.js tail-events
--event-type state_changed --event-type zha_event

undefined

node scripts/ha_ops.js tail-events
--event-type state_changed --event-type zha_event

undefined

ha_ops.js name-review-from-backup

- Offline naming analysis

ha_ops.js name-review-from-backup

- 离线命名分析

bash

undefined

bash

undefined

Analyze backup for naming candidates

分析备份以获取命名优化候选

node scripts/ha_ops.js name-review-from-backup
--backup-root /path/to/backup

undefined

node scripts/ha_ops.js name-review-from-backup
--backup-root /path/to/backup

undefined

Error recovery

错误恢复

If a script fails mid-way:

Check the log file for what was applied before the failure.
Use
```
ha_ops.js rollback
```
with your before-snapshot to revert registry changes.
Fix the underlying issue (network, permissions, entity conflicts).
Re-run the script (operations are generally idempotent).

如果脚本中途失败：

查看日志文件，确认失败前已应用的变更。
使用
```
ha_ops.js rollback
```
命令结合变更前的快照，还原注册表变更。
修复根本问题（网络、权限、实体冲突等）。
重新运行脚本（操作通常具有幂等性）。

Resources

参考资源

API reference:
```
references/api.md
```
Ops playbook:
```
references/playbook.md
```
Entity ID conventions:
```
references/id_conventions.md
```

API参考文档：
```
references/api.md
```
运维手册：
```
references/playbook.md
```
Entity ID命名规范：
```
references/id_conventions.md
```

Logging convention

日志规范

Prefer one markdown log per run (timestamped), listing every entity/automation changed and the before/after values.

每次运行生成一个带时间戳的Markdown日志，记录所有被修改的实体/自动化以及变更前后的值。