电费接进 Home Assistant，重启后却没了：一次 Agent 接入网上国网的两天实战
我原本只想在 Home Assistant 的“我的家”面板里，加上每天用了多少电。
Agent 安装采集器，账号由我自己填写，验证码第二次尝试通过，用电数据陆续进入 HA。六张电量、电费卡片和一张日用电列表也出现了。看起来，这件事已经做完。
随后，另一个配置任务重启了 HA。电费余额、月度和年度汇总卡片，变成了“找不到实体”。
这两天最值得记录的，并不是“终于拿到电费”，而是我如何发现：登录成功、卡片有数字、重启能恢复、历史能保留，其实是四道不同的验收题。
图 1：本文原创配图。文章依据 10 月 25—26 日的本机 Agent 记录、配置变更和写作时的只读核对整理。文中没有公开真实设备地址、计算机名称、内部域名、户号、账号或凭据。
一、我想看的，是每天的用电，不是再造一个电网 App
家里的 Home Assistant 已经能显示家电和环境状态。电费却需要另外打开网上国网查询。我希望把最常看的信息放到同一个入口：最近一个有数据的用电日、电费余额、最近已出账单月份的用电和电费，以及今年的累计情况。
需求听起来很小，实际牵涉三件事：从网上国网取得数据、让 HA 接住数据、让家人能看懂数据。
这次使用的是社区项目 ARC-MX/sgcc_electricity_new，现场加载项版本为 1.8.1。它不是国家电网官方的 HA 集成，也不是电表的本地实时接口。它通过网页自动化登录查询，再用 HA 的 REST API 推送结果。网页、登录策略或地区业务变化，都可能影响可用性。
图 2：首次接入后的真实 HA 截图裁切。户号、账单金额和具体读数已使用不透明色块遮盖，卡片和列表没有重绘。五行日记录说明当时拿到了五个日期的数据，不代表已经积累了十四天。
日常面板只展示需要查看的目标用电账户。读数进入 HA 以后，还要检查字段是否完整：取得最近一天，不等于取得完整逐日列表。不同账户和地区的可用数据可能存在差异，不能因为一张卡片成功显示，就宣布全部能力一致。
如果从零开始，可以按这个顺序准备采集端：
- 先在网上国网 App 或官网绑定自己的户号，人工确认能查询。项目面向国家电网业务，南方电网账户不能直接照搬。
- HA OS 用户在“设置 → 加载项 → 加载项商店 → 仓库”添加上游仓库地址并安装；HA Container 用户按上游说明另起采集容器，保存其数据目录。
- 配置自己的
HASS_URL和专用HASS_TOKEN，端口以实际 HA 入口为准。国网登录信息只在私有配置页填写；视觉接口选用自己已有或自建的服务。 - 启动后逐户检查登录结果、业务日期和六类来源实体。先完成一次真实查询，再启用合理的定时采集、缓存与开机启动。
安装材料可以从公开仓库获取，日常配置脚本不需要托管自动化平台。想完全避免第三方 AI 服务时，视觉端也需要自行部署；仅把脚本搬到本机，并不会消除远端模型调用。
早年我写过 在 Home Assistant 里安装 HACS。但这次用的是 Supervisor 加载项仓库，和 HACS 的自定义集成不是同一个安装入口。HA Container 用户通常需要单独运行采集容器，不能照着 HA OS 的加载项按钮寻找功能。
图 3：把接入拆成三段。前一段成功，只能证明前一段，不能替后一段签收。
二、第一个门槛：验证码能过，不代表接入已经可靠
现场最先遇到的是网络问题：HA 所在环境访问 GitHub 不顺畅，加载项最终通过项目提供的 Gitee 镜像安装。这里解决的是“从哪里取得安装材料”，不会改变后面数据是否正确的问题。
登录环节使用了现场已有的模型网关。账号和密码由我在加载项配置页自行填写，Agent 随后启动加载项、检查登录结果和各户推送记录。首次运行的验证码在第二次尝试通过。
一个容易忽略的细节是输出预算。现场记录显示，点击验证码调用只给了很短的输出上限，约 50 个 token。有些带较长推理过程的模型，在这个预算下没有留下可供程序解析的最终答案。单独测试时“这个模型能看图”，并不能证明它能在该调用的提示词、图片、返回格式和预算下完成任务。
可以把它想成让同学回答一道题：你只给一张便签的空间，程序又只接受坐标。对方写了一大段解题思路，最后的坐标没写出来，程序仍然无法执行。该检查的是完整的输入输出约定，不能只比较模型名气。
这也有一个必须说清的边界：现场确实调用过已有的视觉模型接口，这段过程不是“完全离线”。项目 README 开头还留着早期离线识别的介绍，后面的现行流程已经写明视觉模型方案，阅读时要结合当前代码，而不是摘一句旧说明下结论。
如果希望不使用第三方 AI 服务，可以自行部署支持图片输入的兼容接口，并设置 LLM_BASE_URL、LLM_MODEL 和本地服务要求的认证参数。兼容接口的格式不等于模型一定能答对，仍要验证返回内容。本文下载脚本不调用模型，也不代填国网密码；它自动处理的是数据进入 HA 之后的持久化和验收。
图 4：上游源码真实浏览器截图，固定到提交 bef030a。republish() 读取缓存，并检查缓存日期，说明“缓存再推一遍”和“重新登录采集”是两条不同路径。
重复登录也不是一个好诊断方法。项目维护者明确提醒，平台有每日登录限制。验证码正确之后仍然登录失败，应结合返回结果、会话和限制情况分析，不能无限重试，更不应把某次成功写成长期免维护的保证。
三、第二个误会：“今天看到的数据”，未必是今天用的电
接通以后，我看到的是几天前的日用电。这并不自动说明采集器坏了。国网的日数据在这次使用中存在一到两天滞后，有时实际间隔还需要继续观察；最可靠的依据是 App、网页与接口携带的业务日期是否一致。
这里要分清三个日期：用电发生日、平台出数日、HA 收到日。
像买了一件快递：周一下单，周二发货，周三签收。你不能因为快递周三到家，就把购物账本里的购买日改成周三。同样，周一的用电周三才推到 HA，日用电明细仍应记在周一。
图 5：普通传感器的历史和统计通常记录 HA 收到状态的时间；一个叫 last_reset 的属性，也不会自动把记录搬回真实用电日。
现场的日用电模板按照来源给出的日期，把每天的读数整理成一个列表，保留最近 120 条。相同日期再次到达就更新那一天，晚到的旧日期插回对应位置，不重复累加；没有取得的日期留空，不补一个看起来好看的零。
写作时只读核对，这份列表实际包含 10 月 19—23 日五行记录。初次变更记录曾写过更宽的回填范围，但后来用于验证的一条测试记录已经清理，因此本文以当前真实列表为准。
上月用电也要读清业务含义：这里展示的是平台最近已经出账的完整账单月份，不是“从这个月一号到现在”的滚动用电。不同地区、计费方式下，余额字段还可能表示应交金额，不能把所有账户都套进同一种解释。
更不能把“每天用了 8 度、6 度、9 度”当成“电表累计到了 8、6、9”。前者是三天各自的份额，后者是不断往上走的总表。给它们贴上相同的累计统计标签，会让 HA 误判下降、重置和增量。
四、真正的转折：重启之后，卡片为什么消失？
当时加载项的推送已经成功，HA 也能通过 API 读到状态。随后其他配置工作重启 Core，几张汇总卡片开始提示找不到实体；原先已经做成触发模板的日明细仍在。
这个差别把排查方向从“国网是不是又登录失败”，转向了“这些状态是谁在 HA 启动时重新创建”。
图 6：官方说明，POST /api/states/<entity_id> 创建或替换状态。接口成功不等于替你安装一个负责启动、恢复和轮询的传感器集成。
可以把 HA 当前状态想成教室白板。采集器通过 REST API 写上“电费余额”，家人马上就能看到。Core 重启以后，这块运行时白板被重新建立；如果没有真正的集成、模板或重新推送把那一行写回来，卡片就暂时没有可引用的状态。
数据库里曾经记下过这句话，也不会让所有临时状态自动回到白板上。“记录历史”和“启动时恢复实体”是不同机制。
现场早期记录把问题概括成“没有 unique_id”。更准确的根因是：这些汇总读数通过状态接口进入运行时，没有由相应实体平台在启动时重建。即使请求 JSON 里写了一个 unique_id 字段，也不能把状态接口变成实体注册接口。单独补这个字段，不足以修复生命周期。
采集器有定时从缓存重推的机制，现场配置约每 60 分钟尝试一次。但这不是每分钟实时查询，也不保证重启后立即出现。上游代码还会核对缓存日期，不能把“有缓存”理解成任何时候都必然能重推成功。
五、先把显示稳住：保存最后一次有效值，而不是补零
当时的修复是在独立 package 里增加触发式模板镜像。来源更新时，镜像接受有效数字；来源暂时不存在、未知或不可用时，保留自己已有的有效状态。
图 7：官方文档明确说明，触发式模板实体的状态与属性可以在 HA 重启后恢复。这里使用的是传感器；不要把该结论随意推广到所有实体类型。
下面是一个余额镜像的简化例子。xxxx 是占位标记，需要替换成自己的来源实体；余额可能为负数，不能用“大于零”判断它是否有效。
template:
- triggers:
- trigger: state
entity_id: sensor.electricity_charge_balance_xxxx
sensor:
- name: SGCC cached balance
unique_id: sgcc_cached_balance
unit_of_measurement: CNY
device_class: monetary
state: >-
{% set v = states('sensor.electricity_charge_balance_xxxx') %}
{{ v if is_number(v) else this.state }}
第一次还没有任何有效来源时，镜像可以没有读数。它不应该为了让卡片不报空，就凭空显示零元。已经取得的合法零值，则当然应当接受。
图 8：缓存的作用是保留上次答案。一个恢复出来的旧读数，不能证明今天已经成功登录，也不能保证余额仍然最新。
这次模板先经过配置校验，再用 template.reload 加载，没有为了这一段修改主动重启 Core。不过，“不需要重启就能加载模板”与“已经做过独立的重启验收”仍然是两件事。写文章期间我只做了只读核对，没有再去重启家里的 HA。
六、第三个坑：保住卡片，还要保住“怎么算”
后续我又提出一个需求：国网用电数据能不能一直保留？现场 Recorder 的原始状态保留期为 30 天。只盯着“30 天”三个字，很容易把不同的数据混为一谈。
原先新增的中文名称模板没有 state_class。它能恢复当前值，也能携带近期日明细，但不会因此自动建立长期统计。采集器的原始传感器则带了统计相关属性，现场后续把六张主卡片切回原始实体，并增加了两张年度累计量的月增量图。
这一点必须如实记录：截至写作时，主面板的六张磁贴使用原始来源，旧的镜像和日明细还在。它保留了已有统计 ID，但原始 REST 状态重启后的短暂空窗，仍是这个最终接线方式需要面对的边界。不能把中途镜像修复的效果，直接当成最终面板已经完成的保证。
图 9：写作时重新打开 HA 得到的真实截图。两张月图只有基线，没有补画往月的账单。首个累计读数是统计的起点，不能倒推出它到来之前每个月各用了多少电。
更稳妥的后续结构，是让日常卡片使用可恢复的镜像，同时保留经过验证的原始统计流；需要新建带统计的持久实体时，也必须逐项确认语义和 ID 迁移影响。本文套件将镜像放在独立面板，不替换旧统计实体，避免读者一键操作后意外断掉已有曲线。
图 10：三个抽屉分别存“逐条变化”“近期按日小账本”“按小时汇总的长期趋势”。120 条模板明细仍是滚动缓存，不是永久档案。
长期统计默认不会因为原始历史过了 30 天就被自动清掉，但前提是传感器符合统计要求、数值和单位有效，而且没有被 Recorder 排除。已有数据库、统计数据和备份也仍需要维护，“默认不清理”不等于任何情况下都不会丢。
还有一个账单精度问题：从年度累计量计算月增量，通常按状态到达 HA 的时间分桶。月底的电量到下月才上报，就可能跨月归属。日常看趋势可以使用，精确对账应保留按真实用电日期整理的明细或正式账单，不能简单宣称“对总量影响很小，所以月份无所谓”。
图 11：官方长期统计文档真实截图。当前值能显示、存在统计属性、统计页实际接收数据，应该逐层确认。
七、把能自动化的部分做成下载包
我把这次可复用的数据处理方式整理成 SGCC 本地持久化套件，也可以先读 完整使用说明 或 Python 源码。
包内有 Windows 11 PowerShell、Ubuntu 26.04 Bash、macOS 27 Bash 三个入口，共用一个只使用 Python 标准库的实现。它不调用云端 Agent、不使用第三方自动化服务、不请求视觉模型；联网操作只针对你自己的 HA API。安装包和 Python 本身需要提前准备，网上国网查询当然仍需要连接电力平台。
自动化覆盖的是：生成六个可恢复的传感器，保存按日期去重的日明细，增加独立电量面板，修改前备份，校验失败回滚，以及按需重启和只读验收。它不安装采集器、不替你通过国网登录，也不会把 Windows 或 Mac 自动变成 HA OS。
方法一：人填参数，脚本自动配置
先完成采集器安装和个人账号登录，确认六类来源都有正确数值。然后把 HA 的真实配置目录以已有的文件共享或容器卷方式挂载到执行电脑，确保脚本操作的目录就是 HA 实际读取的目录。
复制 mapping.example.json 为 mapping.local.json，填自己的六个来源实体。户号不要放进公开示例。daily_date_attribute 默认是此采集器使用的 last_reset，必须确认它实际携带 YYYY-MM-DD 的用电日。
再在自己的终端私下设置 HOME_ASSISTANT_URL、HOME_ASSISTANT_TOKEN、HA_CONFIG_DIR。建议使用专用、可撤销的令牌；这些值不需要发给文章作者，也不要贴到公开评论里。
# Windows 11：先查看生成结果，再执行配置。
Copy-Item mapping.example.json mapping.local.json
# 编辑 mapping.local.json，并私下设置上面三个环境变量。
.\windows-11.ps1 plan
.\windows-11.ps1 check
.\windows-11.ps1 apply --restart
.\windows-11.ps1 check --require-mirrors
# Ubuntu 26.04：完成参数配置后执行。
bash ubuntu-26.04.sh plan
bash ubuntu-26.04.sh check
bash ubuntu-26.04.sh apply --restart
bash ubuntu-26.04.sh check --require-mirrors
# macOS 27：完成参数配置后执行。
bash macos-27.sh plan
bash macos-27.sh check
bash macos-27.sh apply --restart
bash macos-27.sh check --require-mirrors
plan 只生成文件，不修改 HA。apply 会备份、写入并调用 HA 配置校验；校验失败恢复文件。--restart 明确表示这次执行允许重启 Core，首次添加侧边栏面板需要加载新配置；正在做其他维护时，可以省略这个参数，另选时间重启。
来源已存在且有效时，镜像在状态变化或五分钟的定时检查后取得值。check --require-mirrors 应在数据进入后再执行。它验证来源、数字、单位、日期和镜像可用性，不会把一个 API 200 当成账号采集已经成功。
兼容范围也有限：常见的内联 packages 和 !include_dir_named 布局可以自动接入；更复杂的外置 include 会拒绝修改，留下生成文件供人或 Agent 审阅。脚本不应为了“全自动”覆盖掉陌生配置。回滚会校验文件哈希，发现执行后又有别的修改，就不会强行覆盖后来的工作。
方法二：把验收要求交给已有 Agent
下载包里也附了任务说明。可以将下面这段交给你已经在使用的本地 Agent；模型选择不影响验收标准。
目标：在现有国网采集器之上，建立可恢复的电量面板。
先只读核对安装方式、版本、户号数量、六类来源实体、单位、真实用电日期。
账号密码由我在本地配置；令牌只从环境变量读取，不打印或复制到报告。
运行本地套件 plan，审阅 package 和 dashboard，保留其他配置和已有统计 ID。
确认年度来源的累计语义，再决定是否开启 yearly_counter_verified。
在维护窗口执行 apply，要求配置校验通过，再按本次授权安排重启。
等待真实采集推送，检查各户结果、数据日期、卡片和重启恢复。
缺数据不填零，不伪造日记录，不把缓存恢复写成新采集成功。
交付变更清单、备份位置、配置校验、逐项验收和仍未验证的边界。
这份提示词把 Agent 当成能操作工具的工程助手。它可以省下重复工作，但账号归属、业务含义和上线验收仍然需要有人负责。
八、我会怎样判断“这次真的做完了”
图 12：六项检查比“面板截图很好看”更有用。每次修改后，应当能说明哪几项已经验证，哪几项还在等待。
对这次现场，已经有证据的是：首次登录成功、目标账户数据完成推送、目标户面板可见、按日期整理的近期日明细存在，以及后续原始统计实体被面板引用。仍需持续观察的是下一次定时采集、跨月归属、长期统计随新数据增长，以及最终面板接线方式下的重启空窗。
对文章下载包，已运行 15 项自动检查，覆盖同日纠正、迟到数据、缺失值、有效零值、保留上限、配置保留、失败回滚、重复执行和保护后续修改等情况。公共模板还通过 HA 的真实模板渲染接口完成 17 项核对；配置写入流程在隔离目录模拟验证，不会借写文章去重配家里的运行环境。
macOS 27 上执行了脚本核心和 Bash 入口检查。Windows 11 入口经过静态审阅，没有 Windows 11 实机结果；Ubuntu 26.04 入口使用同一 Bash 和 Python 实现，但本文不把其他 Linux 的测试冒充 Ubuntu 26.04 真机验收。下载包是可审阅的配置工具，不是三种系统都已经替你部署成功的证明。
Q&A：可能比安装命令更有用的几个问题
这能显示家里现在用了多少瓦吗？
不能。这里是延迟的电量和账单数据，kWh 表示用掉多少电，W 表示此刻用电有多快。像水桶里的累计水量与水龙头当前流速，两者有关，但不能直接互换。实时功率需要合适的计量硬件或其他实时数据源。
为什么不每分钟登录一次，让数字更新快一点？
平台还没出新日数据，反复登录不会让数据提前出现，反而可能碰到限制。采集频率应匹配业务更新节奏；缓存重推可以修复显示空窗，但不能制造新账单。
中文名称的模板不行，英文名称的就行？
名字和语言都不是决定因素。决定能否恢复的是实体实现，决定统计是否正确的是数值、单位、state_class、重置语义与 Recorder 配置。把同一个问题翻译成英文，问题仍然存在。
给所有读数加 total_increasing，是不是最省事？
余额会充值、扣减，也可能为负数；每天各自的用电有高有低；完整月份的账单也不是连续累计表。它们都不应该为了“能画图”随手加上递增标签。套件默认不为这些镜像创建累计统计；年度电量也要明确确认后才开启。
120 天明细和长期统计，能替代正式账单吗？
不能。前者是有上限的近期缓存，后者通常是按到达时间生成的汇总。精确、长期的按日账本应单独按真实日期存储和备份，需要时再做经过验证的历史导入。
多户号最容易遗漏什么？
逐户成功率、业务日期和字段完整度。另一个风险是来源命名只使用户号末几位，存在后缀碰撞的可能；扩展到更多账号时要审查映射是否唯一。显示哪一户和采集哪几户，也应分别配置。
这次接入让我更愿意把自动化的终点往后挪一点：账号能登录以后，还要问数字是哪天的、失败时会怎样、重启后谁负责恢复、半年后留下的又是什么。把这些问题回答清楚，家里的电费卡片才有资格成为一个可以信赖的入口。
参考资料
- SGCC Electricity 社区项目：安装方式、支持范围与登录说明；采集器受地区和平台变化影响。
- 本文核对的固定版本源码：状态推送、缓存和统计属性。
- 国家电网网上营业厅：账号和原始账单核对入口。
- Home Assistant REST API：状态接口的实际职责。
- 触发式模板实体：状态与属性恢复行为。
- Recorder 与 长期统计：历史保留、统计条件与时间分桶。
- Sensor 状态分类：测量、总量与递增总量的语义。
本文六张真实截图来自本人 HA 页面、上游 GitHub 源码和 HA 官方文档，均作了必要裁切；私人页面另做不透明脱敏。其余六张为本文原创双语 SVG 配图，封面另提供 WebP。资料核对日期为 2026 年 10 月 26 日。