674 个实体、157 个“不可用”：我让 Agent 给 Home Assistant 做了次大扫除

智能家居用久了，会慢慢变成一种很奇怪的东西：家里每个角落都有传感器，打开管理页面，却要先想一想，自己究竟要找哪个开关。

2026 年 10 月 25 日，我让 Agent 给家里的 Home Assistant 做了一次只读体检。结果是：674 个实体，157 个显示“不可用”，126 个状态未知。天气没有有效数据，早年写的自动化还在引用已经搬了位置的传感器，停用的扫地机器人仍然留下整套配置。

第二天，面包机、洗衣机、家庭用电、无线网络和基础设施陆续接进来。我发现，真正值得做的事情，是给这些能力重新安排位置：让日常开关容易找到，让设备故障有地方检查，让一个按钮为什么不能按这件事有合理解释。

这篇文章记录两天的整理，也记录几次“看起来已经好了，换个角度验收又发现没好”的过程。

图 1：本文原创配图。674 和 157 是初次检查时的快照；后续接入继续进行，实体总数也继续增长。

一、问题出在“东西都有，就是不好用”

我以前写过 防盗门长时间未关闭时自动提醒，也写过 安装 HACS。那时关注的主要问题，是一个设备能不能接进来、一条自动化能不能跑起来。

时间一长，家里的系统变成了好几代配置叠在一起：有旧仪表盘，有新集成，有同一台设备的多个入口，还有已经退役、却没有把配置一并收走的设备。

像家里的抽屉，买一件东西就往里放，放进去的时候都很合理；等到剪刀、充电线、发票和旧钥匙挤在一起，问题就出现了。抽屉没坏，东西也未必坏，找东西的成本已经高得不适合日常使用。

这次先把两类问题分开：设备和自动化是否真的正常，以及界面是否让人容易找到它们。两件事都要检查，换皮肤只能处理其中很小一部分。

图 2：整理后真实运行的首页，手机使用独立页面截图。天气位置等隐私已用不透明色块遮挡；截图只做裁切和脱敏，没有补造状态。桌面图可点击放大。

二、157 个“不可用”，为什么不能批量删除

最容易出现的冲动，是让 Agent 把所有灰色项目删掉，直到页面不再报错。

初查结果恰恰说明，必须先弄清楚这些状态在表达什么。

这里有个生活里的例子：电话没有正在通话时，“挂断”不能用，是正常的。面包机也是一样，待机时没有正在制作的酸奶，“取消制作”不可用很合理；真正开始运行后，“开始”又可能暂时不可用。

如果只看一个状态字符串就删除，清理掉的可能正是需要保留的能力。

图 3：同样显示灰色，处理方法可能完全不同。restored 也只是线索，不能单独充当删除依据。

实际清理时，我确认停用的扫地机器人可以移除，相关 17 个注册实体、无人扫地规则和两个脚本一起收走；另外删除了 133 个恢复占位项，停用了 12 个仍由集成生成的不可用项目。几组数字来自不同处理集合，存在交叉，不应该简单相加成“总共删除多少”。

面包机的条件控制则保留在设备详情里，首页只展示运行状态、故障和温度。家里的历史数据库也没有因为这次整理被清空。

还有一件容易漏掉的事：删除实体以后，要处理它的生成来源。旧设备仍在集成的发现范围里，下次重启又被创建回来，表面上的“大扫除”就只维持了十分钟。此次把退役设备排除，并在重启后复查，才算把这一环做完。

三、先按房间找，再按系统管理

最初的新面板有四个主要入口：概览、房间、环境、管理。

后来增加网络、设施、电脑和 AI 配额时，也继续沿用这个顺序：先给日常使用一个入口，再把专业细节放进对应页面。家里人找厨房的灯，不需要先知道它属于哪个协议、经过哪个网关。

这相当于给抽屉贴上“厨房”“卧室”的标签，再单独留一个工具箱。日常物品放在顺手的位置，维修工具仍然保留，只是不用每天铺满餐桌。

图 4：真实房间视图。房间本身就是目录，进入以后再看具体设备，不用在几百个实体里搜索。

这里有两个小选择很实用。摄像头在首页保留按需查看入口，避免打开首页就加载视频；旧仪表盘先保留，只把重复入口收起来，方便发现遗漏时对照。

厨房详情里，冷冻室门、开关、洗碗机、热水器分别成组。查看状态和调整参数的入口集中在设备所在的房间。具体到会加热、会停机的操作，仍然需要知道按钮会做什么；界面整齐不等于可以随意自动执行。

图 5：真实厨房页面。这张图证明设备与控件已经显示，不能单凭截图推导所有物理动作都经过测试。

四、一个门磁，暴露了配置会“过期”的问题

这次最有代表性的发现，是一条名字还叫防盗门提醒的规则，引用的传感器已经搬到了冰箱冷冻室。

设备还在，实体也在，语法甚至未必有错，规则表达的生活含义已经变了。

软件很擅长检查“这个编号存不存在”，却不会自动知道“这块门磁现在贴在冰箱上”。就像通讯录里保存着同一个电话号码，对方换了职业，你不能继续按旧身份给他安排事情。

确认安装位置以后，规则改成“冷冻室忘记关门提醒”：持续开门一分钟后播报；每隔两分钟复查，仍未关门才继续提醒；关门就结束等待和重复。HA 启动时如果门仍然开着，也需要延迟检查，避免只依赖一次开门事件。

图 6：提醒应该像一个会复查的闹钟。等待期间也关注关门，才能避免已经关好了还继续催。

验收同样要分层。规则已启用、重启后能加载，是配置验收；关门状态下执行测试，轨迹停在门状态条件，没有进入播报，是分支验收。实际开门超时以后能否听到声音、重复间隔是否符合预期，还需要人在现场测试。

本次记录没有完成最后这一项，所以文章也不把“规则已启用”写成“所有提醒都已送达”。这条边界，比再加一张漂亮卡片更重要。

五、天气恢复了，位置也必须对

初查有 43 个天气、预报和生活指数实体不可用。整理时换用 Open-Meteo，保留原天气实体 ID，当前天气和每日预报重新有了数据，原来引用它的卡片也能继续使用。

Open-Meteo 的 HA 集成不要求先注册账号或配置 API Key，但它需要联网，仍然是外部天气服务。这和文末整理脚本只连接本地 HA，是两件不同的事。

这里还发生过一次返工：为了降低精确位置外传的风险，最初用了城市里另一片区域的位置，后来发现距离实际需要的区域偏差过大。最终改为更合适的粗粒度位置，并重新读取预报。本文和截图都省略具体位置与坐标。

这个错误很像给自己看天气，却翻到了同城另一所学校的值日表。表格格式没错，也有数据，拿来安排今天要不要带伞却可能不合适。

图 7：真实环境页。把温度、湿度和历史曲线放在一起，可以回答“现在怎样”和“什么时候开始变化”两个问题。

六、“刚才还在”的电费实体，为什么重启就没了

第二天把家庭用电接进来后，出现了一个很典型的问题：几张卡片之前有数据，HA Core 重启以后却提示找不到实体。

根因在数据进入 HA 的方式。部分汇总数据由加载项调用 POST /api/states/<entity_id> 推入状态机。这可以让一个状态立即出现，却不会自动替它创建完整的集成、注册身份和启动恢复逻辑。

可以把状态机想成教室前面的白板。有人写上“本月电费”，大家当时都看得到；重新布置教室以后，白板上的字可能没有了。只有负责写字的人再来写一次，内容才重新出现。

当时加载项按小时从缓存重推，重启恰好发生在两次推送之间，于是出现了一个真实的空窗期。浏览器刷新无法解决，因为服务端当下确实没有那个实体。

修复方式是增加可恢复的触发式模板镜像，让汇总卡片引用镜像；收到有效数值再更新，暂时缺数时保留上一次已知值，不把未知转成零。随后用已经核实的缓存值初始化，并回读检查卡片引用。

图 8：保存住一个值，还要交代这个值是什么时候的。恢复机制解决存在性，更新时间解决新鲜度。

这一点也提醒我，卡片上写“最近一天”要比随手写“今日”更诚实。电网数据本来可能滞后一到两天；AI 配额摘要在这次接入里也来自另一面板最近一次刷新的缓存，HA 轮询缓存不等于上游刚刚刷新。

界面里最好明确写数据日期或“几分钟前更新”。否则，一个保存得非常可靠的旧数字，反而更容易让人误判为实时数字。

图 9：真实用电卡片的局部截图。用电数值和金额全部遮挡，只展示信息组织方式，没有用演示数字替换家庭数据。

七、网络设备“在线”，也不能保证指标可信

无线网络接进来以后，可以按房间看 AP 是否在线、连接设备数、负载和上下行带宽。路由器的两条 WAN 也分别展示，避免一个笼统的“网络正常”掩盖其中一条线路的问题。

其中有个值得保留的限制：不同型号的 AP，接口计数行为并不完全一样。现场已经观察到，部分设备的网桥接口会少统计一个方向的流量。因此，这里的带宽用于观察趋势和排查异常，不能当作精确的运营商计费依据。

DHCP 列表也有类似的小坑。接口返回时间的时区语义存在偏差，刚拿到地址的设备，看起来竟然已经过期。后来按剩余租期推算获取与到期时间，才和现场时间对应起来。“动态设备”则依据现场地址池范围筛选，这个判断规则不能原封不动套到所有家庭。

图 10：真实网络页面的局部截图。私有设备标识和线路地址已遮挡。页面能显示指标以后，还要核对指标究竟统计什么。

这些设施接入以只读为原则，路由、虚拟化和存储使用相应的只读权限。电脑唤醒与关机则放在另一个明确的控制页面，按钮带确认步骤。本次整理记录没有实际点击线上唤醒和关机，不能把“接口已接好”写成“所有电脑已验证开关机”。

八、61 个信息按钮，也会把历史数据库“喂胖”

设备接得多，下一件事就是历史记录。

这次检查发现，61 个小米 Miot 信息按钮产生了不少没有必要长期保存的记录。处理方式是在 recorder 中排除相应实体的录制，按钮本身继续保留。

如果你的配置已经有 recorder，应合并进现有配置；不要复制出第二个同名顶层键。下面是本次规则的结构，实际匹配范围应先在自己的实体清单里核对：

recorder:
  purge_keep_days: 30
  exclude:
    entity_globs:
      - "button.*_info*"

重启后的三分钟观察里，这些按钮没有新增录制记录，其他实体仍然写入了 643 条，录制器没有积压。这个对照比“配置文件里已经加了一行”更能说明排除规则生效，也没有顺手停掉整个录制器。

现场按当时写入量估算，保留三十天详细历史，稳定后数据库约 2.1 GB，较之前估算少约 0.7 GB。这是容量预测，不是等满三十天以后测得的结果，更不是其他家庭可以直接照抄的大小。

图 11：不录制一个按钮，不影响按钮存在；清理短期历史，也不等于把所有长期统计一起删除。

可以把详细历史理解成每天的购物小票，把长期统计理解成家庭月账本。小票保留一段时间，账本可以留得更久。HA 对符合条件的数值传感器支持长期统计，需要正确的单位和 state_class 等语义；不能给任何数字随手贴一个类型，就认为电量一定算对了。

例如，“某一天用了多少度电”和“电表累计到了多少度”是两种数据。total_increasing 有单调递增、回零的解释规则，选错以后，图虽然能画出来，统计结果也可能不对。

动态租约列表这种变化频繁、主要用来查看当前状态的大属性，同样需要考虑是否真的有录制价值。减少不必要的写入，比把保留天数无限缩短更合理。

九、备份成功，也要问备份里到底有什么

管理页里集中放了低电量、自动化、日志和备份入口。一个小细节是，AC 入口曾经比旁边按钮大了一圈，后来补齐同样的图标尺寸才一致。做完功能以后，这种真实页面上的检查仍然值得做。

图 12：真实管理页。维护信息留在明确的位置，日常使用时不需要反复穿过这些菜单。

这次还检查了自动备份的内容：原来覆盖 HA 配置、数据库、加载项和证书目录，后来补上共享目录、媒体目录和本地加载项目录，并按新设置立即完成一次加密备份。

但“备份任务成功”和“能完整恢复”之间，仍有距离。需要保存好解密资料，需要有独立的副本，也需要在临时环境做一次恢复演练。此次没有完成恢复演练，所以我不会写“已经保证百分之百恢复”。

备份像一只应急行李箱。打包机器说“拉链拉好了”，不代表里面已经有身份证、充电线和药；更不代表出门时一定能找到钥匙把箱子打开。

十、普通读者怎样复现：手动整理与本地自动脚本

不需要复制我家的任何地址、设备名称或第三方集成。比较容易复用的是整理方法。

方法 A：在 HA 界面人工完成

1. 在“设置 → 系统 → 备份”创建并检查一份当前备份，确认需要的目录与加载项包含在内。
2. 在“设备与服务 → 实体”按来源核对不可用项目；确认设备退役以后，再查自动化、脚本和面板引用，决定移除、停用还是修复。
3. 在“区域”里把设备放回正确房间。设备区域和单独实体区域可能不同，要看实际需要。
4. 新建一个独立仪表盘，优先用原生 Sections、Tile、实体列表和历史图。先放七成最常用的信息，再逐步补充。
5. 用电脑和手机分别打开，检查卡片引用、状态含义、数据时间；涉及真实设备动作时，按设备逐项做现场验证。

先做一个新面板，能让旧界面在核对期间继续使用。新界面确认合适以后，再决定是否设成默认入口。

方法 B：运行文章配套的三个系统脚本

我为本文另外写了一份可下载的整理工具。它复用“盘点 → 按区域分组 → 新建面板 → 回读验证”的流程，不包含我家的协议代码、账号、地址或个性化自动化。

下载 完整脚本包 和 SHA-256 校验文件，完整解压到一个私人目录。三个启动脚本调用同一份 Python 标准库实现，不需要 pip、HACS 卡片、云端 AI 或外部中转服务。共同前提是已安装 Python 3.11 以上版本、能直接访问自己的 HA，并持有管理员的长期访问令牌。macOS 也需要事先准备 Python，脚本不会替你安装软件。

还可阅读 公共实现源码 与 完整说明。启动脚本需要与公共实现放在同一目录，单独下载一只启动脚本不能工作。

人工自动执行时，三选一运行下面的命令。程序会询问 HA 地址，并在隐藏输入提示中读取令牌，不要把令牌直接写进命令。

Windows 11：

powershell -NoProfile -ExecutionPolicy Bypass -File .\run-windows11.ps1 --apply

这里的执行策略只针对本次 PowerShell 进程，不修改系统的永久策略。

Ubuntu 26.04：

bash ./run-ubuntu2604.sh --apply

macOS 27：

zsh ./run-macos27.zsh --apply

去掉 --apply，程序只读取并生成本地方案。加上它以后，会创建一个新的、仅管理员可见的房间面板，并通过 HA API 回读比较。卡片点击打开详情，不直接切换设备；已有面板、自动化、实体和历史记录保持原样。

它按当前区域关系生成页面，把隐藏、诊断、未知或不可用的项目排除在日常卡片之外，同时在私人输出清单中保留注册信息供复核。生成的是当时的快照，之后状态恢复或新增设备，需要重新生成或手动调整；不会自动持续维护房间分类。

图 13：自动化负责重复劳动，设备是否退役、哪个指标适合给家人看，仍要由了解这个家的人判断。

如果要撤销工具新建且尚未修改的面板，可以凭它保存的回执执行：

python3 ha_dashboard.py --rollback ./ha-dashboard-output/receipt.json

Windows 可使用 py -3 代替 python3。撤销会核对生成路径、面板 ID 和配置哈希；已经被手动修改的面板会拒绝自动删除，改到 HA 界面核对后处理。若创建成功而保存中途失败，也应根据回执到界面检查新面板。

测试边界也说明白：macOS 27 已实际执行启动脚本并连接真实 HA 完成只读生成；本地模拟 HA 测试覆盖 WebSocket 认证、分片与心跳、创建回读、撤销及拒绝删除已修改面板。Ubuntu 启动脚本通过 Bash 语法检查。Windows 11 和 Ubuntu 26.04 没有完成原生系统实跑，也没有用工具向家里的 HA 写入测试面板。

方法 C：让 Agent 自动配置

把工具解压到本地以后，可以把下面这段任务交给 Agent。地址由自己通过 HA_URL 提供，令牌只通过 HOME_ASSISTANT_TOKEN 提供；不要把私人输出目录上传给别人。

请使用当前目录中的 ha_dashboard.py 整理我的 Home Assistant。
从 HA_URL 读取地址，从 HOME_ASSISTANT_TOKEN 读取管理员令牌，不打印凭据。

先执行只读计划：
python3 ha_dashboard.py --non-interactive --out ./ha-private-output

核对房间分组和排除项以后，创建一个独立面板：
python3 ha_dashboard.py --non-interactive --apply --out ./ha-private-output

保留现有面板、实体、自动化和历史，不触发设备动作，不重启 HA。
在电脑和手机宽度检查实际页面，回报缺失引用、不可用项与数据更新时间。
不要把正常按钮的 unknown 或条件不可用直接判成故障。
保存回执，并说明真实验证完成的项目和仍需人工验证的项目。

Agent 能减少搬运配置和检查引用的时间。家庭语义仍需要人告诉它：扫地机器人已经退役，门磁搬进了冷冻室，待机时取消按钮不可用是正常行为。这些信息，藏在你的生活里，不在设备 API 里。

十一、最后用什么证明整理有效

我没有把“没有灰色卡片”当成唯一指标。

截至本文复查时，系统继续接入新能力，状态实体已经有 1,135 个；当前家庭面板的 267 个静态实体引用全部存在，缺失为零，其中仍有一个按钮不可用。这个检查只统计直接配置的实体引用，不代表把所有模板、所有可能状态和所有设备动作都测了一遍。

这两天对我最大的改变，是开始把 HA 当成一个持续有人使用的家庭产品来维护。接入成功以后，还有命名、分组、时效、状态解释、数据保留和恢复这些工作。

下次家里再多一台设备，我会先问它应该出现在哪个房间、什么情况下需要提醒、数据要留多久，然后再去研究它支持什么协议。

Q&A

一定要安装很多第三方卡片吗？

不需要。此次界面主要靠原生分区、磁贴、实体列表、Markdown 和历史图完成。先让信息结构清楚，再考虑主题和特效，会更容易维护。

把不可用项从首页移走，会不会掩盖故障？

所以要保留管理和诊断入口，并区分条件控制、停用设备与真实失联。日常界面减少噪声，维护界面继续展示待处理项，两边都要有明确职责。

能不能让 Agent 自动删除所有失效配置？

它可以自动盘点和检查引用，但删除还需要退役意图和来源信息。本文工具主动把自动写入范围限制在新面板，避免把一个通用脚本误当作了解全部家庭历史的管理员。

数据不见时，先刷新浏览器还是重启 HA？

先看服务端实体是否存在、集成是否加载、来源最后一次更新时间，再看浏览器。临时 REST 推送状态在重启后消失，就是一个继续重启也解决不了的例子。

这套方法完全离线吗？

整理工具运行时只连接自己的 HA，不调用云端 AI 或第三方服务。家里的天气、电网以及某些家电集成本身仍可能依赖外部网络；是否本地运行，要按每条数据链路分别判断。

参考资料

以下为本文核对行为时参考的 Home Assistant 官方资料；现场数字来自 10 月 25—26 日的实际操作记录与写稿时复查。

• Home Assistant REST API：状态读写与动作调用
• Home Assistant WebSocket API：认证与命令响应
• Sections 仪表盘
• Open-Meteo 集成
• 模板实体及恢复行为
• Recorder 保留与排除配置
• 长期统计
• Sensor state class
• 备份集成

文中的 Home Assistant 标志来自官方品牌资产。原理图为本文原创；界面截图均来自本次真实运行环境，已裁切并遮挡位置、地址、设备标识及账单数据。