1实现原理 · 为什么它能做到
本体零代码：skill 不自带任何脚本，全部能力由『宿主工具 + 领域知识』兑现——操作远端 HA 实例靠三条既有通道，SKILL.md 只负责选择与编排它们。
skills/home-assistant-manager/SKILL.md
- Access via one or more of: `hass-cli` (REST), SSH `ha`, or an MCP server (see below).
这里在做什么：把『怎么连 HA』抽象成三种可选传输，skill 只写决策规则（何时用哪个）而不实现客户端。查证：全仓无 scripts/ 目录、无 .sh/.py/.js 文件，故「无代码」成立。
MCP 优先策略：若宿主接入了 MCP server，则用其一等工具做实时状态读取与服务调用，避免 hass-cli 的环境变量预加载摩擦；官方集成与社区服两条路都点名。
skills/home-assistant-manager/SKILL.md
juggling. Official `mcp_server` integration (HA core ≥2025.2) or community `ha-mcp`
这里在做什么：给出 MCP 的两个来源与版本门槛（HA core ≥2025.2 才有官方 mcp_server 集成），并注明社区 ha-mcp 工具更全（80+ tools）。注意 SKILL.md 只『声明偏好』，未给任何 MCP 安装/配置命令——真正可执行的 MCP 命令只有 README 里那条 context7。
部署流水线被固化成唯一的 6 步规范（edit→check→commit/push→pull→reload/restart→verify），并明确『第 4 步之后才算上线』——把远端 git pull 定义为生效动作。
skills/home-assistant-manager/SKILL.md
Changes are not live until step 4.
这里在做什么：假设用户 HA /config 本身就是一个 git 仓库，于是本地编辑 + push 只是暂存，必须在实例上 pull 才生效。这是本 skill 与通用『改文件』skill 的根本差别：它编的是双端一致性协议。
为短回环留了旁路：跳过 git，直接 scp 单文件到实例 /config 再 reload，用于仪表盘和试错密集的迭代；git 只在稳定后提交。
skills/home-assistant-manager/SKILL.md
**Rapid iteration:** skip git and `scp` straight to the instance, then reload
这里在做什么：用『快通道 vs 正规通道』两条腿平衡速度与可回溯性；代价是 scp 出去的文件在 git 提交前不属于版本控制，作者用 'Commit to git only once stable' 明确了这个折衷。
reload 与 restart 由变更类型查表决定，而非凭感觉：域级实体（automation/script/scene/template/theme）用 reload，核心 configuration.yaml、新集成、平台型传感器、MQTT 平台、仪表盘注册表用 restart。
skills/home-assistant-manager/SKILL.md
| automations, scripts, scenes, groups, template entities, themes | **reload** the domain (`hass-cli service call automation.reload`, etc.) |
这里在做什么：把 HA 的热加载语义变成可执行判断表，避免『一律 restart』导致的中断；下一条表行同时给出 restart 的适用集合与 ~30s 成本。
验证闭环不靠『应该好了』：先 reload/restart，再手动触发自动化拿即时反馈，再按变更名 grep 日志，最后确认实体状态；并显式点出 automation.trigger 默认跳过 conditions 的陷阱。
skills/home-assistant-manager/SKILL.md
`hass-cli service call automation.trigger --arguments entity_id=automation.<id>`
这里在做什么：本条命令下方紧接 'This **bypasses `conditions` by default** — it proves the actions, not the gate.'，要求再补 `skip_condition: false` 或走真实触发器 + 读 trace。这是把踩坑经验固化成纪律，而非泛泛地说『测试一下』。
知识分层：SKILL.md 保持薄（127 行，其中非空 107 行；release.txt 记 v1.0.0 时由 627 行瘦身至 106 行），自动化与 Lovelace 的深知识分别放进两个 reference 文件，由 SKILL.md 在对应场景显式指路，形成按需加载的渐进披露。
skills/home-assistant-manager/SKILL.md
**Full automation reference** (syntax table, `mode:` behavior, blueprints, trace debugging, pitfalls) → read [`reference/automations.md`](reference/automations.md) when writing or debugging automations.
这里在做什么：同样的指路句在 Dashboards 段复现一次指向 reference/dashboards.md；release.txt v1.0.0 记录 SKILL.md 由 627 行瘦身到 106 行、并把重复的部署/命令段移除，正对应这一分层策略。
安全纪律写进正文：编辑面收窄到 .yaml/.yml/.md，明令不读不写 .env 与 secrets.yaml（改用 !secret），restart 前必须 ha core check 通过，危险变更前先 ha backups new 快照。
skills/home-assistant-manager/SKILL.md
- Only edit `.yaml`/`.yml`/`.md`. Never read/write `.env` or `secrets.yaml`; use `!secret`.
这里在做什么：主动把凭证文件排除在 agent 的读写范围之外，属于少见但关键的自限设计；备份句 'it's cheap: `ssh [email protected] "ha backups new --name pre-<change>"`' 为其配套回滚网。
2核心能力
01实体状态查询与服务调用（经 hass-cli REST 或 MCP）
02自动化 YAML 编写：默认 2024.10+ 现代语法（triggers/conditions/actions、trigger:、action:），并要求稳定 id: + alias
03自动化 mode 语义与蓝图（use_blueprint）使用，含 blueprints 目录约定与 reload 语义
04Jinja2 模板类型安全规则：比较前强制转换（| int(0)/| float(0)）、给默认值防启动 None、state_attr 缺失需守卫
05Lovelace 仪表盘开发：sections/panel 视图选择、tile/heading/Mushroom 卡片选型、Jinja 模板卡片、平板栅格布局
06部署与热更新：git pull 上线 / scp 快投 + 域级 reload，并区分 .storage/lovelace.* 直改需 restart（内存缓存）
07故障排查：日志关键字模式（Good/Bad 两串）、自动化 trace 阅读、常见陷阱速查表（点击式症状→原因→修法）
08仪表盘变更的浏览器可视化验证：经 Claude-in-Chrome 驱动用户已登录浏览器，截图 + 坐标点击（shadow DOM 导致无法用无障碍树定位）
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| api | Home Assistant REST API（经 hass-cli 调用） |
| cli | hass-cli（homeassistant-cli，pipx 安装） |
| cli | ssh / scp / 远端 `ha` CLI（HA 宿主 [email protected] 为占位符） |
| api | Home Assistant MCP server（官方 mcp_server 集成 / 社区 ha-mcp） |
| network | Context7 MCP（HA 官方文档检索，可选） |
| network | GitHub（README 安装方式三：curl 下载仓库 tarball） |
| package | HACS（安装 custom:mushroom-* 卡片的前提） |
| cli | Claude-in-Chrome 浏览器扩展（原生浏览器验证通道，参考中说明不用 Playwright/MCP） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: ssh [email protected] "ha core check"（配置校验，~30-60s）
- 网络端点: 声明外部网络访问: http://homeassistant.local:8123 — Home Assistant REST API，hass-cli 经 HASS_S
- 本地工作目录: 文件读写与工件输出: HA 实例 /config 下的 .yaml/.yml（automations.yaml、scripts/scenes/templates、confi
审计说明： 橙色，使用需留意。判级依据：① 凭证/环境变量面真实存在——SKILL.md 要求判定 `[ -n "$HASS_TOKEN" ]`，README 要求 `export HASS_TOKEN=your_long_lived_access_token`（long-lived access token），该 token 是 HA 的全权 REST 凭据，落在宿主 shell 环境里由 hass-cli/MCP 消费；② 依赖第三方组件——社区 MCP server `ha-mcp`（SKILL.md 明确点名并称其 80+ tools）与 context7 远程 MCP（https://mcp.context7.com/mcp），均非本仓库资产；③ 网络外发是运维性质而非浏览性质——SSH/scp 到 HA 宿主、REST 到 homeassistant.local:8123，写操作直达用户的家居实例（restart、改配置、触发自动化），误操作代价是真实设备行为。缓解面：仓库零脚本、零可执行文件（glob 全量核对），不关 TLS、不绕反爬、无批量采集、无任意代码执行面，且作者主动设置了三重自限——只编辑 .yaml/.yml/.md、Never read/write `.env` 或 `secrets.yaml`、restart 前必须通过 ha core check、危险变更前先 ha backups new、浏览器验证 never enter credentials。故不升 red；因 token 与第三方 MCP 两项硬指标，不降 yellow。
5第二遍独立确认
- [ok] skill 目录与 SKILL.md 定位（任务提示为待定位） — 实际路径 skills/home-assistant-manager/SKILL.md 存在，frontmatter name: home-assistant-manager 与 description 与任务给的一字不差；同目录含 reference/{automations,dashboards}.md 与 dashboard.png。
- [ok] 『MCP 还是原生 REST？』的事实核对 — 两者都给，但性质不同：SKILL.md 只对 MCP 表达偏好（'MCP (preferred when available)'）并点名官方 mcp_server 集成与社区 ha-mcp，却未给任何 MCP 安装/配置命令；真正可直接执行的命令全是 hass-cli/ssh/scp。README 中唯一的 claude mcp add 是 context7（文档检索），不是 HA 控制通道。故『MCP 优先』属策略声明，可执行面是 CLI/SSH。
- [ok] 凭证读取【决定档位的关键项】 — HASS_TOKEN 全仓命中 4 处：SKILL.md 第 22/24 行（hass-cli 需 HASS_SERVER/HASS_TOKEN、判存在 `[ -n "$HASS_TOKEN" ]`）、README 第 83 行（前置条件列出两个环境变量）、README 第 328 行（export 占位值）。无任何要求打印、回显、上传或写入 token 的指令；同时 SKILL.md 明令不读不写 .env/secrets.yaml。结论：存在环境变量依赖但无外泄路径，仍因持 token 的 CLI/MCP 通道记 orange。
- [ok] 隐藏脚本 / 可执行代码核查 — glob 含隐藏文件全量结果仅 9 个：.gitignore、LICENSE、README.md、release.txt、SKILL.md、dashboard.png、reference/automations.md、reference/dashboards.md、.claude-plugin/{plugin,marketplace}.json、.github/FUNDING.yml。无 .sh/.py/.js/.ts，无 package.json，无 hook 配置。所以 security.scripts_executed 列出的都是 SKILL.md 指示宿主去跑的外部命令，不是仓库自带脚本。
- [ok] 网络端点清点（区分服务端点与文档链接） — 真实服务端点仅两个：http://homeassistant.local:8123（HA REST，README 第 327 行）与 https://mcp.context7.com/mcp（README 第 347 行）。其余 URL 为 shields 徽章、github.com 仓库/安装 tarball、home-assistant.io 文档、buymeacoffee 按钮、semver.org，均非 skill 运行所需的调用面。websocket 与 supervisor 全仓零命中——SKILL.md 未声称也不使用 WebSocket API 或 Supervisor API。
- [discrepancy] 功能声明 vs 实际能力（夸大检查） — README『Workflow Optimization』bullet 写 'No Restart for Dashboards'，而同仓库 dashboards.md 与 SKILL.md 都明确写直接文件编辑（scp/git）到 .storage/lovelace.* 可能不被识别、需 `ha core restart`（HA 缓存 lovelace store）。README 该 bullet 只在『UI 编辑 + 硬刷新』这一子情形下成立，属表述宽于实际；这是唯一发现的声明出入，不影响其余能力项（自动化语法、验证闭环、卡片选型等条条有正文支撑）。
- [ok] reference 分层是否真实被引用（而非死文件） — SKILL.md 正文对 reference/automations.md 与 reference/dashboards.md 各有一条显式指路句（'→ read [`reference/…`](reference/…)'），且两个文件首行都反向声明 'Core deploy/verify rules are in `../SKILL.md`'，双向链接成立。
- [ok] reload/restart 决策表与 HA 语义一致性 — 表内 reload 集合（automations/scripts/scenes/groups/template entities/themes）与 restart 集合（configuration.yaml core、新集成、platform sensors、MQTT 平台、lovelace_dashboards）与 automations.md 中 blueprint 改动需 reload、dashboard 注册需 restart 的说明自洽，无自相矛盾。
6结论
适合： 适合已把 HA /config 纳入 git、且具备 SSH（或 MCP/hass-cli）访问通道的自托管 Home Assistant 用户——尤其需要频繁写自动化 YAML、调模板类型错误、做平板/墙面仪表盘并要求改动可验证的进阶玩家；也适合作为『给 LLM 补 HA 领域纪律』的知识层，与已装的 HA MCP server 叠加使用（README 明确二者是互补而非替代）。
不适合： 不适合 HA 新手——它假定用户已有 SSH 免密、git-connected /config、以及能理解 reload/restart 与 .storage 语义，不提供从零搭建家庭自动化的教程。不适合没有远端访问通道、只在 HA Web UI 里点选的纯 GUI 用户（skill 的核心是 CLI/git 流程）。不适合期望 skill 自带可执行代码/自动化管线的场景：本仓库零脚本，一切动作都落在宿主工具上。也不适合把 HA 管理当作多用户/托管服务的场景——无多实例、无权限分级、无审计日志设计。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload home-assistant.tar.gz
sha256:
Option B · Copy Guide for Agent23d2cb212a09fcaf…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 21126796f5.