SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场home-assistant-manager

home-assistant-manager

部署与运维

查看项目

更新于 10-15 12:36

技能介绍

Home Assistant Manager 用于精确操作远程 Home Assistant 实例：做出修改、让它生效、并证明它确实工作，同时尽量减少安全往返次数。

用途

该技能面向需要编辑和部署 Home Assistant 配置的场景。它假定你正在编辑的仓库就是 HA 的 /config 目录，并通过 git 与实例相连；在实例上执行 git pull 之前，编辑不会生效。示例中的 root@homeassistant.local 是占位符，需要先解析真实的用户和主机（可通过项目 CLAUDE.md、~/.ssh/config 或直接询问），如果尚未记录在项目 CLAUDE.md 中，应补充记录，以便后续会话跳过此步骤。

主要能力

  • 编辑并部署 YAML 配置，涵盖自动化、蓝图、脚本、场景、模板、MQTT 等。
  • 通过 ha core check 进行校验，通过 ha core restart 重启，通过 git pull 使推送的更改生效。
  • 支持三种远程访问方式：SSH ha（始终可用，无需本地环境，用于 ha core check|restart|logs|info）、hass-cli（REST，用于状态和服务调用，但需要会话开始前在 shell 中设置 HASS_SERVER/HASS_TOKEN）、MCP 服务器（可用时优先，提供实时状态/控制的一等工具，无需环境变量折腾；官方 mcp_server 集成需 HA core ≥2025.2，社区 ha-mcp 更丰富，有 80+ 工具）。
  • 提供部署流水线：本地编辑 YAML → 校验 → 提交并推送 → 在实例上 git pull → 应用（重载或重启）→ 验证。
  • 支持快速迭代：跳过 git，直接用 scp 传到实例，然后重载，适合仪表盘和紧凑测试循环；稳定后再提交到 git。
  • 提供重载与重启的决策表：自动化、脚本、场景、分组、模板实体、主题可重载对应域；configuration.yaml 核心、新集成、平台传感器（min/max）、MQTT sensor/binary_sensor 平台、仪表盘注册表（lovelace_dashboards）需要重启。
  • 强调验证：重载/重启正确的域；对自动化可手动触发以获得即时反馈；读取过滤后的日志；确认设备/传感器状态或询问用户通知类动作。
  • 提供自动化现代语法指导：HA 2024.10 重命名了键，新代码应使用顶层 triggers:/conditions:/actions:（复数），触发器内用 trigger: 而非 platform:，服务调用用 action: 而非 service:；每个自动化应有稳定的 id: 和 alias。
  • 提供模板精度规则：比较前始终强制类型转换，如 states('sensor.x') | int(0) < 7；裸 states 是字符串，'5' < 7 会引发 TypeError；提供默认值（int(0)）避免启动时 None 报错；在 Developer Tools → Template 中测试；state_attr(...) 在实体/属性缺失时返回 None，需要防护。
  • 提供仪表盘管理：Lovelace 仪表盘位于 .storage/lovelace.*（JSON）；UI 编辑在浏览器刷新后显示；直接文件编辑（scp/git）可能需要 ha core restart 才出现，因为 HA 在内存中缓存 lovelace 存储；向 .storage/lovelace_dashboards 添加新仪表盘也需要重启；scp + 刷新是快速循环；部署前先用 python3 -m json.tool 校验 JSON；部署后在浏览器中视觉验证 UI。

使用方式

基本流程为：本地编辑 YAML → 校验（ssh root@homeassistant.local "ha core check"，较慢，约 30-60 秒）→ 提交并推送（git add … && git commit -m "…" && git push）→ 使更改生效（ssh root@homeassistant.local "cd /config && git pull"）→ 应用（重载或重启）→ 验证。

快速迭代可跳过 git，直接 scp 到实例然后重载：scp automations.yaml root@homeassistant.local:/config/ → 重载。

何时跳过 ha core check：它会解析整个配置且较慢。对于你确信的孤立 YAML 编辑，域重载能更快暴露错误，日志会立即告诉你。在重启前或修改 configuration.yaml 时始终运行它。

重载与重启：优先重载。没有通过 ha core check 绝不重启。在风险更改（核心 configuration.yaml 手术、移除集成）前先快照：ssh root@homeassistant.local "ha backups new --name pre-<change>"。

验证：重载/重启正确的域；对自动化可手动触发：hass-cli service call automation.trigger --arguments entity_id=automation.<id>（默认绕过条件，证明动作而非门控；要测试条件可传 skip_condition: false 或走真实触发器，然后在 UI 中读取自动化跟踪）；读取过滤日志：ssh root@homeassistant.local "ha core logs | grep -iE '<name>|error' | tail -20"；确认真实结果：设备/传感器状态（hass-cli state get <entity>），或对通知类动作询问用户。出错时：修复 → 重新拉取/scp → 重载 → 重新检查，循环直到干净。

约定：外科手术式编辑；保留注释；2 空格缩进；重启前校验；优先重载；从日志验证；在非平凡或不熟悉的配置前使用 context7 MCP 获取当前 HA 文档。

适用场景

适用于需要远程管理 Home Assistant 配置的开发者或高级用户，尤其是涉及自动化、脚本、场景、模板、MQTT、仪表盘等 YAML 或 JSON 配置的编辑与部署。也适用于需要安全校验、快速迭代和日志验证的工作流。

限制

只编辑 .yaml/.yml/.md 文件。绝不读取/写入 .env 或 secrets.yaml；使用 !secret。hass-cli 需要 HASS_SERVER/HASS_TOKEN 在会话开始前设置，否则会回退到错误主机（localhost）并报错，此时不要重试，检查一次 [ -n "$HASS_TOKEN" ]，然后改用 SSH 或 MCP。MCP 可用时优先使用。仪表盘直接文件编辑可能不会立即显示，需要重启。其他具体限制暂未提供。