RDK X5 电源控制与 USB 系统烧录
把“可控供电 → 串口进入 U-Boot → USB 导出 SD → 核对目标 → 写镜像 → 完整回读 → 冷启动 → 验收”串起来。供电走 Home Assistant 的 Xiaomi Home 集成；镜像数据经 USB 写入板端 SD。两条链路独立，不能把米家 API 当成烧录接口。
先确定本次模式
- 搭建或交接：先读 HA 与米家部署，创建无凭据配置并验证端口映射。
- 执行烧录：按 完整操作手册 执行，沿用用户已授权的镜像和电源端口。
- 只有断电/上电：使用下面的电源步骤，不引入烧录。
- 校验或启动异常：读 恢复与验收，只做证据支持的有限恢复。
- 追溯来源/验证边界：读 来源与验证记录。历史参数不是当前设备事实。
开始前建立本次设备绑定
核对并记录：板型、物理供电口对应的 switch.* 实体、HA URL、串口与波特率、SD 的 MMC 索引、当前 USB 磁盘名/协议/完整字节容量、镜像路径/大小/可信 SHA-256、用户授权范围及需保留数据。缺任何决定写盘目标的信息时先只读检查。
使用者只要求查看/重启时，不推导出擦写权限；已经明确要求重烧时，不反复询问同一授权。需要保留板端数据时先备份，备份路径和回读结果写入报告。不要把历史 C1、disk4、IP、32/64 GB 容量写死到新设备。
准备独立运行目录，所有脚本共用同一绝对路径操作锁。ha_power.py 和 flash_macos.py 用它互斥；锁不约束其他工具、其他主机或人手操作。写入/回读期间保持供电，禁止另一终端、HA 自动化或人手切电。
电源控制的必经步骤
- 查询目标实体状态；
unknown/unavailable、HTTP 401、超时都不能当作成功。 - 上电：
ha_power.py on，等待 HA 报告 on，再从串口确认板子实际启动。 - 断电：Linux 可响应时先
sync; poweroff，串口看到Power down后运行ha_power.py off --safe-to-cut。仅 SSH 断开不足以证明关机。 - 已停在 U-Boot、未进行存储操作时，可按已授权操作切电。死机无法关机时说明硬切电原因，确认现有授权覆盖此动作；不要伪造安全关机结果。
- 硬重启：
ha_power.py cycle --safe-to-cut等 off 确认，保持断电至少 5 秒，再 on。HA 状态只是一条证据；通过完整启动日志和 boot ID 变化证明板子重启。 - 不用
toggle或“全部端口”，避免状态不明或误断其他设备。
烧录闭环与停点
| 阶段 | 通过信号 | 失败后的动作 |
|---|---|---|
| 供电/串口 | 对应板启动，出现 Hobot> |
查电源、串口占用、波特率、接线；不发送猜测命令 |
| UMS | ums 0 mmc 1 被接受，Mac 出现匹配 UMS 整盘 |
重新枚举；USB gadget 出现不等于磁盘已可写 |
| 写前检查 | 外部 USB 整盘、名称/字节容量精确匹配、镜像哈希一致 | 拒绝写入；不靠 /dev/diskN 编号猜目标 |
| 写入/回读 | 镜像全长度 SHA-256 一致 | 保持供电；保存差异证据；不宣告成功、不直接启动 |
| 启动 | 退出 UMS 后进入 Linux，串口可登录 | 保存启动日志；不盲目重复刷写 |
| 验收 | boot ID、内核、根分区、LED、网络/目标功能的实际证据 | 分项标注未通过/未测试，不清 failed 标记冒充修复 |
flash_macos.py 默认只读计划；真正写入要 --write 和系统管理员权限。--repair-fat-after-automount 是可选的单次、限范围恢复：仅当本次观测到写后自动挂载、完整比对的所有差异块都在镜像 FAT 分区内、重复读取稳定且不超过 16 MiB，才从同一镜像恢复差异块；之后必须重新完整回读。其他差异一律停下诊断。
凭据与交付
- HA_TOKEN 由临时环境变量或隐藏输入传入；sudo/板端密码只走交互或既有认证。禁止写进 Skill、命令行参数、示例、报告或 ZIP。不要复制旧 WorkBuddy 脚本中的固化令牌。
- 不把 Home Assistant 的
config/打包给别人：里面可能含集成令牌和设备信息。 - 收尾释放自动化串口，并恢复用户原用的串口监视窗口；确认能看到当前 Linux 提示，不把历史报错当成现状。
- 报告分别给出“镜像与回读”“启动”“功能”结果，写明未通过项、未测试项和最终电源状态。BPU 旧闭源兼容通过用
PASS-WAIVER，不升级成全功能生产通过。
安装与调用
把整个 rdk-x5-usb-flash/ 放入使用者的 Skill 目录，例如 ~/.codex/skills/；其他支持 SKILL.md 的 Agent 按其加载目录安装。无需部署原用户的 WorkBuddy 或复制其私人资料。
调用示例：“使用 $rdk-x5-usb-flash，先帮我搭建 HA＋米家电源控制，然后按我指定的镜像通过 USB 烧录并验证 RDK X5。”实际首次 OAuth、管理员权限或新板的数据保留需求可能需要用户参与，不承诺无条件无人值守。
