ESP32增量开发xiaozhi-esp32LVGL可回滚

ESP32 增量开发安全流程(esp32-incremental-feature-safeguard)

在已经跑通、验证过的 ESP32(尤其小智 ESP32 / ESP-IDF / LVGL 小屏)项目上加新功能,做到「不影响既有功能 + 可快速回滚」。

一、这个 skill 是做什么的

在已经跑通的 ESP32 项目上加新功能(比如加个 AHT20 温湿度传感器、改一下 UI 布局、加个自动滚动),最大的风险不是「写不出来」,而是「改坏了原本好用的东西」以及「凭猜动手 → 反复返工」。实战里有人加「定位+天气显示」因没做前置分析改了 5 轮,而用本流程加 AHT20 传感器一轮通过、零编译错误、零回滚。

它提供一套把返工压到最小的流程:先做「三查」分析再写代码、设计建议必须做可用性推演、改文件之前先建回滚点、只增不改地零侵入编码、交付前自己先编译验证。一句话——先想清楚,再动手,还能一键退回。

二、什么时候用它

三、前置条件 / 准备

四、具体用法(步骤)

阶段 0.5:设计建议先做「可用性推演」

当你(或 AI大模型或AI智能体)想主动推荐某个「自动行为」时,必须先站在用户真实场景推演:用户此刻在做什么?设备输入输出有时序差吗(语音设备文字要钉在最新,不能自动往回滚)?有没有「自行加戏」偏离用户原话?真实教训:语音设备推荐「缓慢上滚回顾历史」方向完全反了,让用户跟不上。

阶段 0:三查(先分析,不写代码)

输出含「决策点 + 影响评估」的方案,待你确认。

阶段 1:回滚机制先行(改文件之前)

先把要改的文件备份到 .rollback/ 目录,并写一个一键回滚脚本(恢复备份 + 删新增文件)。这一步成本极低,却能把「最坏情况」的恢复时间从半小时硬修降到双击 5 秒。

BK=".rollback/$(date +%Y-%m-%d)_<feature>" mkdir -p "$BK" cp main/display/xxx.cc main/display/xxx.h main/CMakeLists.txt "$BK/"

阶段 2:零侵入编码

只增不改(新功能独立成文件,对既有文件只加行不改逻辑);复用已验证几何与架构(后台任务 + mutex 快照 + UI 侧拉取);成对改动(改字体/字号时创建处与 SetTheme 两处都要改)。

阶段 3:自验证前置(交付你之前必须跑通)

先做语法检查,再完整 idf.py -B build build 必须 BUILD_EXIT=0。Windows 编译若报 cc1.exe: cannot open ...Permission denied,taskkill //F //IM ninja.exe + 把 TMP/TEMP 指独立目录 + 单进程编译。

阶段 4:交付 + 验证清单

交付物含源码 + 部署指南 + 回滚脚本 + 编译产物。给你串口关键日志、屏幕观察点、回归项(如语音唤醒是否正常)。

五、可直接照用的示例

你直接对 AI大模型或AI智能体 说:「我这个 xiaozhi 板子已经能用了,想加个 AHT20 温湿度显示在屏幕上,别把我原来的功能弄坏。」

AI大模型或AI智能体 会:先做三查——查 GPIO 看 I2C 总线是否空闲(AHT20 走 I2C,地址 0x38)、查 UI 哪一行能塞下、查 datasheet 确认时序与公式;给你方案确认后,先建 .rollback/ 备份 + 回滚脚本,再零侵入加一个独立驱动文件并在显示处只加行;最后自己编译通过、确认唤醒等原功能仍在,再交付。

你直接对 AI大模型或AI智能体 说:「对话界面改多行后,能不能自动往回滚回顾一下历史?」

AI大模型或AI智能体 会:先做可用性推演——这是语音设备,文字总跑在语音前面,自动上滚会把「还没朗读」的文字推出屏幕,你其实要的是「时刻最新」。因此不建议自动往回滚,改为让文字始终钉在最新。若你坚持回顾,会先说明风险再动手。

你直接对 AI大模型或AI智能体 说:「新功能加崩了,怎么最快退回原样?」

AI大模型或AI智能体 会:运行阶段 1 留的一键回滚脚本——恢复 .rollback/ 下的备份文件并删除新增文件,5 秒回到改动前状态,原功能完好。

六、常见注意 / 避坑

设计建议必做可用性推演:技术「能做」很容易,难的是判断「该不该做、做成什么样」。语音设备的文字必须钉在最新,不要做自动往回滚;别因为技术可行就自行加戏偏离用户原话。

七、相关 skill / 延伸

← 返回 SKILL 库