| name | firmware-dev-executor |
| description | 基于项目记忆、硬件接口、需求和本地构建工具实现、编译、调试和修复 MCU 固件。适用于生成 BSP/driver/app 代码、维护 Keil/CMake/Make 工程、解析编译错误、实现协议解析、参数存储、校准、UI 逻辑、第三方库移植或执行“最小测试闭环”的嵌入式开发任务。强调人管物理世界，AI 管信息世界。 |
固件开发执行
先读项目记忆、硬件接口和产品需求，再写固件。必须从底层往上，小步验证。
核心边界：人管物理世界，AI 管信息世界。
- 人负责：上电、带载、观察、温升、过流、异常声音、真实安全、关键产品判断。
- AI 负责：读资料、看源码、看日志、收敛假设、生成最小改动、设计下一轮最小测试。
不要把编译通过当成硬件验证，不要把 AI 的推断当成板端事实。
必要上下文
- MCU 型号、封装、板卡版本。
- 硬件接口速查表、开发板资源模型和危险输出清单。
- 产品行为需求和验收标准。
- 现有项目结构和构建命令。
- 代码分层和命名规则。
- 验证方式：编译日志、串口输出、调试器/SWD、示波器、人工观察。
缺关键上下文时，先建立 TODO 或提出一个聚焦问题，不要编造硬件事实。
开发顺序
- 编译/运行基线。
- GPIO 安全默认态。
- UART 日志或最小调试通道。
- 逐个外设：ADC、PWM、I2C、SPI、定时器、中断、DMA。
- BSP 抽象：有效电平、板级语义、安全动作。
- component：parser、CRC、环形缓冲、滤波、参数存储。
- app 功能模块。
- app_workflow 业务编排。
- 集成测试并更新调试记录。
底层外设未验证前，不要直接写业务逻辑。
最小测试闭环
每一轮只推进一个最小目标，不要一次改一堆。
标准闭环：
-
明确一个最小目标
例如“让 USART1 打印 BOOT OK”“让 LED0 按 1Hz 闪烁”“读取 W25Q128 ID”“按键按下打印事件”。
-
明确当前证据
读取接口表、需求、手册摘录、现有代码和编译日志，说明依据。
-
只做最小改动
修改最少文件、最少逻辑。不要顺手重构无关模块。
-
编译或静态检查
能编译就编译；不能编译要说明缺什么工具链。
-
给出板端验证步骤
明确人要观察什么：串口输出、LED、波形、电压、继电器动作、温升。
-
等待反馈再进入下一轮
没有反馈前，不要继续叠加更多功能。
输出格式：
## 本轮最小目标
- ...
## 修改范围
- ...
## 验证方法
- 编译:
- 上板:
- 期望现象:
## 需要人工反馈
- ...
## 下一轮候选
- ...
架构规则
main.c 只做初始化、tick 消费、周期任务调度。driver 只表达 MCU 外设机制。bsp 表达板级含义：引脚、有效电平、安全默认态、硬件资源。component 必须产品无关。app 模块负责产品行为。app_workflow 负责跨模块编排。- 私有全局变量和私有函数优先使用
static。
- 避免失控的全局变量和隐藏跨模块依赖。
- ISR 中不要阻塞，不做复杂耗时逻辑。
- ISR/main 或多任务共享数据必须考虑临界区、锁、队列或原子访问。
- 检查错误码、超时、部分读写、缓冲区边界。
安全规则
- 危险输出必须先初始化到安全状态，再使能外设。
- 继电器、电机、加热、阀、高压 PWM、电源使能在未验证前不得带真实负载冒进测试。
- 首次验证危险输出时，优先空载、断开功率级、限流电源或示波器测信号。
- AI 不得声称“硬件已验证”，只能说“代码已编译/逻辑已检查/建议这样验证”。
- 需要板端观察时，明确告诉工程师要看什么。
编译修复闭环
- 有构建命令就运行。
- 完整读取错误和日志。
- 按根因分组。
- 修改最小责任范围。
- 重新构建。
- 记录改动原因。
同类错误反复出现时，不要盲改，先检查工程文件、include 路径、生成文件、宏、链接脚本和工具链配置。
硬件反馈格式
需要工程师反馈现象时，要求使用：
## 现象
- 上电行为:
- 串口输出:
- 指示灯/屏幕/继电器/电机:
- 测量值/波形:
- 是否发热/异响/过流:
## 复现步骤
1. ...
## 期望行为
- ...
常见任务的最小目标示例
- GPIO/LED：只验证一个引脚能按安全电平翻转。
- UART：只验证启动打印和回显，不同时加入完整协议。
- I2C：只扫描/读取一个器件 ID 或固定寄存器，不先写复杂业务。
- SPI Flash：只读取 JEDEC ID，不先写擦除。
- PWM：先空载输出低频低占空比波形，不直接接功率负载。
- ADC：先读取固定通道原始值和参考电压，不先做复杂滤波。
- 参数存储：先读默认值和 CRC 校验，不先写入真实生产参数。
- OLED/UI：先显示一行固定文本，再做菜单和按键导航。
- 协议解析：先解析一帧固定样例，再接真实串口流。
常见坑
- 代码能编译，但上电不安全。
- 有效电平猜错，继电器或负载误动作。
- 一轮改动太大，无法判断哪个修改引入问题。
- 产品行为没定义清楚，导致代码反复改。
- 小屏 UI 代码逻辑正确，但布局和体验不对。
- 构建、下载、反馈通道没稳定就追求全自动。
