home-assistant-manager

Home Assistant 管理器

精确操作远程 Home Assistant 实例：进行更改，使其生效，并验证结果。 以尽可能少的安全往返操作为目标。

前提

• 你正在编辑的仓库就是 HA /config 目录，并通过 git 连接到实例。 更改需在实例上拉取后才会生效。
• 示例中的 [email protected] 是占位符。请通过项目 CLAUDE.md、~/.ssh/config 或询问来确定实际用户和主机，并在尚未记录到项目 CLAUDE.md 时添加记录，以便后续会话无需重复此步骤。
• 可通过以下一种或多种方式访问：hass-cli（REST）、SSH ha 或 MCP 服务（见下文）。
• 仅编辑 .yaml/.yml/.md。绝不要读取或写入 .env 或 secrets.yaml；请使用 !secret。

远程访问——选择合适的工具

• SSH ha——始终可用，无需本地环境变量。用于 ha core check|restart|logs|info。
• hass-cli（REST）——用于状态和服务调用，但需要在会话启动前于 shell 中设置 HASS_SERVER/HASS_TOKEN。如果未设置，hass-cli 会回退到错误的主机（localhost）并报错——不要重试，只检查一次 [ -n "$HASS_TOKEN" ]，然后改用 SSH 或 MCP。
• MCP（有条件时优先使用）——提供用于实时状态和控制的一流工具，无需折腾环境变量。使用官方 mcp_server 集成（HA core ≥2025.2）或社区版 ha-mcp（功能更丰富，提供 80 多个工具）。如果有 MCP 服务，请使用它，而不是通过 shell 调用命令。

部署流程（唯一标准流程）

完成第 4 步后，更改才会生效。

1. 在本地编辑 YAML。
2. 验证：ssh [email protected] "ha core check"（速度较慢，约 30-60 秒——见下文“何时跳过”）。
3. 提交并推送：git add … && git commit -m "…" && git push。
4. 使更改生效： ssh [email protected] "cd /config && git pull"。
5. 应用更改：尽可能重新加载，否则重启（见下表）。
6. 验证（见下一节）。

**快速迭代：**跳过 git，直接用 scp 传到实例，然后重新加载——适用于仪表盘和密集测试循环。稳定后再提交到 git。 scp automations.yaml [email protected]:/config/ → 重新加载。

**何时跳过 ha core check：**该命令会解析整个配置，速度较慢。对于你确信无误的独立 YAML 编辑，重新加载对应域可以更快地暴露错误，并且日志会立即提供信息。重启前或更改 configuration.yaml 时，始终运行该命令。

重新加载还是重启

更改	操作
自动化、脚本、场景、组、模板实体、主题	重新加载对应域（如 hass-cli service call automation.reload）
configuration.yaml 核心配置、新集成、平台传感器（min/max）、MQTT 传感器/二进制传感器平台、仪表盘注册表（lovelace_dashboards）	重启（ssh … "ha core restart"，约 30 秒）

优先重新加载。未通过 ha core check 时，绝不要重启。进行高风险更改前（修改核心 configuration.yaml、移除集成），先创建快照——这很快： ssh [email protected] "ha backups new --name pre-<change>"。

验证——不要想当然地认为它已生效

1. 重新加载或重启正确的域。
2. 对于自动化，手动触发以即时获取反馈： hass-cli service call automation.trigger --arguments entity_id=automation.<id> （或通过 MCP 调用服务）。默认情况下，这会绕过 conditions——它验证的是操作，而不是触发条件。若要同时测试条件，请传入 skip_condition: false，或实际触发自动化，然后在 UI 中查看自动化的跟踪记录。
3. 查看筛选出与更改相关内容的日志： ssh [email protected] "ha core logs | grep -iE '<name>|error' | tail -20"。 正常：Running automation actions、Executing step …。异常：Invalid data for call_service、TypeError、Template variable warning、Error executing script。
4. 确认实际结果：设备/传感器状态（hass-cli state get <entity>），或对于通知类操作，询问用户。
5. 出错时：修复 → 重新拉取/使用 scp → 重新加载 → 再次检查。重复此流程，直到没有问题为止。

自动化 — 编写现代语法

HA 2024.10 重命名了这些键；旧版语法仍然有效，但新代码中不要使用： 顶层使用 triggers:/conditions:/actions:（复数），触发器中使用 trigger: 而不是 platform:， 调用时使用 action: 而不是 service:。每个自动化都必须有稳定的 id:（追踪和 UI 编辑 需要它）以及 alias。

自动化完整参考（语法表、mode: 行为、蓝图、追踪调试、 常见问题）→ 编写或调试自动化时，请阅读 reference/automations.md。

模板 — 精确性规则

• 比较前始终转换类型：states('sensor.x') | int(0) < 7。裸状态是 字符串；'5' < 7 会引发 TypeError。请提供默认值（int(0)），以避免启动时的 None 导致错误。
• 提交前在 开发者工具 → 模板 中测试。
• 如果实体或属性不存在，state_attr(...) 会返回 None — 请添加保护判断。

约定

• 只做必要的修改；保留注释；使用 2 个空格缩进。
• 重启前先验证；优先使用重新加载；通过日志确认。
• 进行非简单或不熟悉的配置前，使用 context7 MCP 查看最新的 HA 文档。

仪表盘

Lovelace 仪表盘存储在 .storage/lovelace.*（JSON）中。UI 编辑会在浏览器刷新后显示； 直接编辑文件（scp/git）可能要等到执行 ha core restart 后才会显示 — HA 会在内存中缓存 Lovelace 存储。将新仪表盘添加到 .storage/lovelace_dashboards 也需要重启。scp 后刷新是最快的迭代方式；先验证 JSON： python3 -m json.tool .storage/lovelace.x > /dev/null。部署后，在浏览器中直观验证 UI （参见参考文档） — 日志和状态无法发现卡片损坏或弹出窗口排序错误。

仪表盘完整参考（视图类型、卡片目录、模板卡片、平板布局、 常见问题、调试）→ 进行 UI 工作时，请阅读 reference/dashboards.md。现代 HA：原生的 sections 视图（拖放网格、徽章、heading 卡片）和 功能丰富的 tile 卡片现在已能满足大多数需求，无需自定义卡片；只有在需要 Mushroom 的特定外观时才使用它。

快速参考

# Validate / apply
ssh [email protected] "ha core check"
ssh [email protected] "ha core restart"
ssh [email protected] "cd /config && git pull"     # make pushed changes live

# Logs
ssh [email protected] "ha core logs | grep -iE 'error|<name>' | tail -20"

# State / services (needs env loaded, or use MCP)
hass-cli state get <entity>
hass-cli service call <domain>.reload
hass-cli service call automation.trigger --arguments entity_id=automation.<id>

# Rapid deploy
scp <file>.yaml [email protected]:/config/ && hass-cli service call automation.reload