35e - 嵌入式 Steering 规则与反模式

┌─────────────────────────────────────────────────────────────────┐
│  层级 3：模块级规则                                               │
│  针对特定外设/驱动的约束                                          │
│  示例：SPI 驱动必须使用 DMA、ADC 采样必须在 ISR 中触发            │
│  文件：.kiro/steering/drivers/*.md 或 CLAUDE.md 子节             │
├─────────────────────────────────────────────────────────────────┤
│  层级 2：平台级规则                                               │
│  针对特定 MCU/RTOS 的约束                                        │
│  示例：ESP32 任务栈最小 4KB、STM32 HAL 回调命名规范               │
│  文件：.kiro/steering/platform-esp32.md                          │
├─────────────────────────────────────────────────────────────────┤
│  层级 1：项目级通用规则                                           │
│  所有嵌入式项目通用的约束                                         │
│  示例：禁止动态分配、ISR 中禁止阻塞、必须启用看门狗               │
│  文件：CLAUDE.md / .kiro/steering/embedded-base.md               │
└─────────────────────────────────────────────────────────────────┘

# 嵌入式项目 Steering 规则（通用）
 
## 项目概述
- 目标平台：[MCU 型号，如 STM32F407VGT6]
- RTOS：[FreeRTOS / Zephyr / 裸机]
- 语言：C11（主要）/ C++17（仅限应用层）
- 编译器：[GCC ARM / IAR / Keil MDK]
- Flash 预算：[如 512KB，当前使用 320KB]
- RAM 预算：[如 128KB，当前使用 96KB]
- 栈大小：[主栈 2KB，任务栈 1KB-4KB]
- 安全标准：[MISRA C:2012 / IEC 61508 SIL 2 / 无]
 
## 🚫 绝对禁止（违反即拒绝）
 
### 内存管理
- 禁止使用 `malloc()`、`calloc()`、`realloc()`、`free()`
- 禁止使用 C++ `new`、`delete`
- 禁止使用 `alloca()`（栈上动态分配）
- 禁止使用可变长数组（VLA）
- 禁止在栈上分配超过 256 字节的局部变量
- 所有缓冲区必须静态分配，大小在编译时确定
 
### 中断安全
- ISR 中禁止调用任何可能阻塞的函数
- ISR 中禁止使用 `printf()`、`sprintf()`、`malloc()`
- ISR 中禁止调用非 FromISR 后缀的 RTOS API
- ISR 中禁止执行超过 10μs 的操作
- 禁止在 ISR 中进行浮点运算（除非 MCU 支持惰性浮点上下文保存）
 
### 编码标准
- 禁止使用 `goto`（除 MISRA 允许的错误清理模式）
- 禁止隐式类型转换（所有转换必须显式）
- 禁止使用递归（栈深度不可预测）
- 禁止使用 `#pragma once`（使用传统 include guard）
- 所有 switch 必须有 default 分支
- 所有 if-else 链必须有 else 分支
 
### 安全关键
- 禁止忽略函数返回值（特别是 HAL 函数）
- 禁止使用未初始化的变量
- 禁止使用魔术数字（必须用 `#define` 或 `enum`）
- 禁止无限循环中缺少看门狗喂狗
 
## ⚠️ 必须遵守（强制规则）
 
### 内存
- 所有数组必须有明确的大小定义
- 所有字符串操作必须使用带长度限制的版本（`strncpy` 而非 `strcpy`）
- 共享数据必须使用 volatile 修饰或适当的同步机制
- DMA 缓冲区必须对齐到缓存行（通常 32 字节）
 
### 中断
- 所有 ISR 必须尽快返回（设置标志 + 延迟处理）
- 中断优先级必须在系统初始化时统一配置
- 共享资源访问必须使用临界区保护
- 嵌套中断必须明确文档化优先级关系
 
### RTOS
- 每个任务必须有明确的栈大小计算依据
- 任务优先级分配必须有文档说明
- 互斥锁必须使用优先级继承协议
- 所有 RTOS API 调用必须检查返回值
 
### 看门狗
- 系统必须启用看门狗定时器
- 主循环和所有关键任务必须定期喂狗
- 看门狗超时时间 = 最大正常周期 × 2
- 看门狗喂狗不得在 ISR 中执行（防止主循环死锁时 ISR 仍在喂狗）
 
## 📝 代码风格
 
### 命名规范
- 函数：`模块_动作_对象`（如 `UART_Send_Byte`、`ADC_Read_Channel`）
- 宏定义：全大写 + 下划线（如 `MAX_BUFFER_SIZE`）
- 全局变量：`g_` 前缀（如 `g_systemState`）
- 静态变量：`s_` 前缀（如 `s_txBuffer`）
- ISR 回调：`模块_IRQHandler`（如 `USART1_IRQHandler`）
 
### 文件组织
- 每个外设驱动一个 .c/.h 文件对
- 头文件必须有 include guard
- 公共 API 在 .h 中声明，内部函数用 static
- 配置参数集中在 `config.h` 或 `*_conf.h`
 
### 注释
- 每个函数必须有 Doxygen 风格注释
- ISR 必须注释触发源和预期执行时间
- 寄存器操作必须注释位域含义
- 魔术数字必须注释来源（数据手册页码）

## 内存管理 Steering 规则（补充）
 
### 静态分配策略
- 使用内存池（memory pool）替代 malloc
  - FreeRTOS：使用 `pvPortMalloc()` + heap_1（仅分配不释放）
  - Zephyr：使用 `K_MEM_POOL_DEFINE` 或 `k_heap`
  - 裸机：使用编译时固定大小的数组池
- 字符串缓冲区：预分配固定大小，使用 `snprintf` 限制写入长度
- 环形缓冲区：大小必须是 2 的幂（便于取模优化）
 
### 栈使用规则
- 主栈（MSP）：仅用于 ISR 和初始化，最小 1KB
- 任务栈（PSP）：根据调用深度计算，预留 20% 安全余量
- 栈使用量验证：使用栈涂色（stack painting）技术定期检查高水位
- 禁止在栈上分配大数组：超过 64 字节的数组必须用 static 修饰
 
### 内存对齐
- DMA 缓冲区：`__attribute__((aligned(32)))` 或 `ALIGN(32)`
- RTOS 任务栈：按 8 字节对齐（ARM Cortex-M 要求）
- 外设寄存器结构体：使用 `__packed` 或手动填充确保布局正确

## 中断安全 Steering 规则（补充）
 
### ISR 设计原则
- ISR 执行时间预算：
  - 硬实时系统：< 1μs（仅设置标志）
  - 软实时系统：< 10μs（简单数据搬运）
  - 非实时系统：< 100μs（允许简单处理）
- ISR 中允许的操作：
  ✅ 读写 volatile 标志
  ✅ 写入环形缓冲区
  ✅ 调用 FromISR 后缀的 RTOS API
  ✅ 清除中断标志
  ❌ 任何可能阻塞的操作
  ❌ 浮点运算（除非有硬件 FPU 惰性保存）
  ❌ 动态内存分配
  ❌ 标准库 I/O 函数
 
### 中断优先级规划
- 使用优先级分组表，在项目初始化时统一配置
- 预留最高优先级给安全关键中断（看门狗、故障处理）
- RTOS 管理的中断优先级必须 ≥ configMAX_SYSCALL_INTERRUPT_PRIORITY
- 文档化所有中断的优先级、触发源和预期频率
 
### 共享资源保护
- ISR 与任务共享数据：使用 volatile + 临界区
- 任务间共享数据：使用互斥锁（带优先级继承）
- 多字节原子操作：使用 `__disable_irq()` / `__enable_irq()` 包裹
- 避免长时间关中断：临界区内代码不超过 10 条指令

## MISRA C:2012 核心规则子集（AI 必须遵守）
 
### 必须规则（Required）
- Rule 1.3：不得出现未定义行为
- Rule 2.1：不得有不可达代码
- Rule 8.13：指向不修改对象的指针参数应声明为 const
- Rule 10.1：操作数不得有不适当的基本类型
- Rule 10.3：表达式的值不得赋给更窄的基本类型
- Rule 11.3：不得在指向不同对象类型的指针之间进行转换
- Rule 12.2：移位运算的右操作数不得为负或超过位宽
- Rule 14.3：控制表达式不得是不变的
- Rule 17.7：不得丢弃非 void 函数的返回值
- Rule 18.1：指针算术不得产生越界指针
- Rule 21.3：不得使用 <stdlib.h> 的内存分配函数
- Rule 21.6：不得使用 <stdio.h> 的输入/输出函数
 
### 建议规则（Advisory，强烈推荐）
- Rule 2.7：函数中不应有未使用的参数
- Rule 4.1：不应使用八进制和十六进制转义序列
- Rule 8.7：仅在一个翻译单元中引用的函数和对象应在内部链接中定义
- Rule 15.7：所有 if...else if 结构应以 else 子句终止

## 安全关键 Steering 规则
 
### 防御性编程
- 所有外部输入必须验证范围和类型
- 所有指针使用前必须检查非 NULL
- 所有数组访问必须检查边界
- 所有除法操作必须检查除数非零
- 使用 `static_assert` 验证编译时假设
 
### 故障检测与恢复
- 关键数据使用 CRC 或校验和保护
- RAM 中的关键变量使用互补存储（变量 + 反码）
- 状态机必须有"无效状态"处理
- 通信协议必须有超时和重试机制
 
### 看门狗策略
- 独立看门狗（IWDG）：硬件级，不依赖系统时钟
- 窗口看门狗（WWDG）：检测过早和过晚的喂狗
- 软件看门狗：每个任务有独立的活跃度监控
- 看门狗喂狗条件：所有关键任务都在正常运行时才喂狗

# ESP32 (ESP-IDF) 平台 Steering 规则
 
## 平台信息
- SDK：ESP-IDF v5.3+
- 双核：PRO_CPU (Core 0) + APP_CPU (Core 1)
- Flash：通常 4-16MB（QSPI）
- PSRAM：可选 2-8MB（SPIRAM）
- FreeRTOS：ESP-IDF 内置（SMP 版本）
 
## ESP32 专用禁止规则
- 禁止在 Core 0 上运行长时间计算任务（Core 0 负责 Wi-Fi/BT 协议栈）
- 禁止在 ISR 中调用 `ESP_LOG*` 宏（使用 `ESP_EARLY_LOG*` 或 `ESP_DRAM_LOG*`）
- 禁止在 IRAM 函数中访问 Flash 中的常量（使用 `DRAM_ATTR`）
- 禁止使用 `delay()` 替代 `vTaskDelay()`（Arduino 兼容层陷阱）
- Wi-Fi/BT 回调中禁止执行耗时操作（使用事件队列转发）
 
## ESP32 专用必须规则
- 任务栈最小 4096 字节（ESP-IDF 开销较大）
- Wi-Fi 任务固定在 Core 0，应用任务优先放 Core 1
- 使用 `esp_timer` 替代 FreeRTOS 软件定时器（精度更高）
- NVS 操作必须检查返回值（Flash 磨损可能导致失败）
- OTA 更新必须验证固件签名和版本号
- 使用 `CONFIG_ESP_TASK_WDT` 启用任务看门狗
- PSRAM 中的数据不得用于 DMA（除非使用 `heap_caps_malloc(size, MALLOC_CAP_DMA)`）
 
## ESP32 内存分区
- IRAM：中断处理函数、热路径代码（约 200KB 可用）
- DRAM：全局变量、堆（约 320KB 可用）
- PSRAM：大缓冲区、非实时数据（2-8MB）
- Flash：代码、只读数据（4-16MB）
- 使用 `IRAM_ATTR` 标记需要快速执行的函数
- 使用 `DRAM_ATTR` 标记 ISR 中访问的数据

# STM32 (HAL/LL) 平台 Steering 规则
 
## 平台信息
- SDK：STM32CubeHAL v1.x / LL 驱动
- 工具链：STM32CubeIDE / GCC ARM + CMake
- 调试：ST-Link + OpenOCD / J-Link
- 配置：STM32CubeMX 生成初始化代码
 
## STM32 专用禁止规则
- 禁止手动修改 CubeMX 生成的 `/* USER CODE BEGIN */` 之外的代码
- 禁止在 HAL 回调中执行耗时操作（使用标志 + 主循环处理）
- 禁止直接操作 RCC 寄存器（使用 HAL_RCC 或 LL_RCC API）
- 禁止在未启用外设时钟的情况下访问外设寄存器
- 禁止使用 `HAL_Delay()` 在 ISR 中（依赖 SysTick，会死锁）
- 禁止忽略 `HAL_StatusTypeDef` 返回值
 
## STM32 专用必须规则
- 所有 GPIO 初始化必须通过 CubeMX 或 HAL_GPIO_Init
- DMA 传输完成必须使用回调（`HAL_*_TxCpltCallback`），不得轮询
- 低功耗模式进入前必须：关闭未使用外设时钟、配置唤醒源、保存上下文
- 使用 LL 驱动替代 HAL 驱动的场景：高频中断处理、精确时序控制
- Flash 编程必须在临界区中执行（Flash 操作期间不能读取 Flash）
- 使用 `__HAL_DBGMCU_FREEZE_*` 在调试时冻结看门狗和定时器
 
## STM32 HAL 回调命名规范
- 传输完成：`HAL_{外设}_TxCpltCallback` / `HAL_{外设}_RxCpltCallback`
- 半传输：`HAL_{外设}_TxHalfCpltCallback`
- 错误：`HAL_{外设}_ErrorCallback`
- 中断：`{外设}_IRQHandler`（在 `stm32*_it.c` 中）

# Arduino 平台 Steering 规则
 
## 平台信息
- 框架：Arduino Core（AVR / ESP32 / RP2040 / STM32）
- IDE：Arduino IDE 2.x / PlatformIO
- 语言：C++（Arduino 方言）
 
## Arduino 专用禁止规则
- 禁止在 `loop()` 中使用 `delay()` 超过 10ms（使用 millis() 非阻塞模式）
- 禁止使用 `String` 类（堆碎片化）——使用 `char[]` + `snprintf`
- 禁止在 ISR 中使用 `Serial.print()`
- 禁止使用 `analogRead()` 在时间关键路径（AVR 上约 100μs）
- 禁止假设 `int` 是 32 位（AVR 上 `int` 是 16 位）
- 禁止使用 `new` / `delete`（使用静态分配）
 
## Arduino 专用必须规则
- 使用 `F()` 宏将字符串常量存储在 Flash（AVR 平台节省 RAM）
- 使用 `PROGMEM` 存储大型查找表
- 使用 `volatile` 修饰 ISR 中修改的变量
- 使用 `millis()` 实现非阻塞定时：
  ```cpp
  // ✅ 正确：非阻塞定时
  static uint32_t lastTime = 0;
  if (millis() - lastTime >= INTERVAL) {
      lastTime = millis();
      // 执行周期任务
  }

### 3.4 Zephyr RTOS Steering 规则

```markdown
# Zephyr RTOS 平台 Steering 规则

## 平台信息
- 版本：Zephyr v4.x+
- 构建系统：west + CMake + Kconfig + Devicetree
- 支持平台：500+ 开发板
- 许可证：Apache 2.0

## Zephyr 专用禁止规则
- 禁止直接操作硬件寄存器（使用 Zephyr 设备驱动 API）
- 禁止在 Kconfig 中启用不需要的子系统（增加 Flash/RAM 占用）
- 禁止硬编码引脚号（使用 Devicetree 别名和标签）
- 禁止在 ISR 中调用 `k_sleep()` 或 `k_sem_take()` 带超时
- 禁止使用 POSIX API 除非启用了 `CONFIG_POSIX_API`

## Zephyr 专用必须规则
- 使用 Devicetree 定义所有硬件配置（引脚、时钟、外设）
- 使用 Kconfig 管理所有编译时配置选项
- 线程栈使用 `K_THREAD_STACK_DEFINE` 宏定义（确保 MPU 对齐）
- 使用 `__ASSERT` 和 `__ASSERT_NO_MSG` 进行运行时断言
- 日志使用 Zephyr Logging API（`LOG_MODULE_REGISTER` + `LOG_INF/WRN/ERR`）
- 使用 `k_mutex` 替代自旋锁（除非在 ISR 上下文）
- 设备驱动必须遵循 Zephyr 设备模型（`DEVICE_DT_DEFINE`）
- 使用 `CONFIG_WATCHDOG` 启用看门狗支持

## Zephyr Devicetree 规范
- 板级覆盖文件：`boards/{board}.overlay`
- 应用覆盖文件：`app.overlay`
- 引用节点：使用 `DT_NODELABEL()` 或 `DT_ALIAS()`
- 获取属性：使用 `DT_PROP()` 宏

# Raspberry Pi Pico 平台 Steering 规则
 
## 平台信息
- MCU：RP2040（双核 Cortex-M0+，264KB SRAM）/ RP2350（双核 Cortex-M33）
- SDK：Pico SDK v2.x
- 构建：CMake + GCC ARM
- 特色：PIO（可编程 I/O）状态机
 
## Pico 专用禁止规则
- 禁止两个核心同时访问同一 Flash 扇区（Flash 是 XIP，写入时全局暂停）
- 禁止在 Core 1 上使用 `printf`（默认 USB/UART 绑定 Core 0）
- 禁止假设 `float` 运算快速（RP2040 无硬件 FPU，RP2350 有）
- 禁止直接操作 SIO 寄存器进行核间通信（使用 `multicore_fifo_*` API）
 
## Pico 专用必须规则
- 使用 PIO 处理精确时序协议（WS2812、自定义串行协议）
- 核间通信使用 FIFO 或 `mutex_*` API
- Flash 写入必须在临界区中执行（`flash_range_erase` / `flash_range_program`）
- 使用 `sleep_ms()` / `sleep_us()` 而非 busy-wait（支持低功耗）
- DMA 通道分配使用 `dma_claim_unused_channel()`（避免冲突）
- 使用 `watchdog_enable()` 启用硬件看门狗
- 多核启动：Core 0 先初始化，通过 `multicore_launch_core1()` 启动 Core 1

// ❌ AI 典型错误：在栈上分配大缓冲区
void process_sensor_data(void) {
    uint8_t buffer[4096];        // 4KB！可能超过整个任务栈
    char log_message[512];       // 又 512 字节
    float calibration_table[256]; // 1KB 浮点数组
    
    // ... 处理逻辑
    read_sensor(buffer, sizeof(buffer));
    sprintf(log_message, "Data: %d", buffer[0]);  // sprintf 本身也消耗栈
    printf("%s\n", log_message);                    // printf 栈消耗约 1KB
}

// ❌ AI 典型错误：递归调用
int parse_json(const char *json, int depth) {
    char key[128];
    char value[256];
    // 每层递归消耗 ~400 字节栈空间
    // 嵌套 5 层 = 2KB，可能溢出
    if (*json == '{') {
        return parse_json(json + 1, depth + 1);
    }
    // ...
}

// ✅ 正确：使用静态缓冲区 + 限制栈使用
static uint8_t s_sensorBuffer[4096];  // 静态分配，不占用栈
static char s_logMessage[128];         // 缩小到实际需要的大小
 
void process_sensor_data(void) {
    // 栈上只有少量局部变量
    uint16_t dataLen = 0;
    HAL_StatusTypeDef status;
    
    status = read_sensor(s_sensorBuffer, sizeof(s_sensorBuffer), &dataLen);
    if (status != HAL_OK) {
        error_handler(ERR_SENSOR_READ);
        return;
    }
    
    snprintf(s_logMessage, sizeof(s_logMessage), 
             "Data[0]=%u, len=%u", s_sensorBuffer[0], dataLen);
    log_output(s_logMessage);  // 使用轻量级日志，非 printf
}
 
// ✅ 正确：用迭代替代递归
int parse_json_iterative(const char *json, size_t len) {
    int depth = 0;
    #define MAX_DEPTH 8
    
    for (size_t i = 0; i < len; i++) {
        if (json[i] == '{') {
            depth++;
            if (depth > MAX_DEPTH) {
                return ERR_TOO_DEEP;
            }
        } else if (json[i] == '}') {
            depth--;
        }
        // ... 迭代处理
    }
    return 0;
}

## 栈溢出防护规则
- 禁止在栈上分配超过 256 字节的局部变量
- 禁止使用递归（使用迭代 + 显式栈替代）
- 禁止使用 printf/sprintf（使用 snprintf + 轻量级日志）
- 所有大缓冲区必须声明为 static 或全局
- 每个任务栈大小必须有计算依据（调用深度 × 最大帧大小 × 1.5 安全系数）

// ❌ AI 典型错误：在嵌入式中使用动态分配
void handle_mqtt_message(const char *topic, const char *payload) {
    // 动态分配——嵌入式大忌
    char *topic_copy = strdup(topic);           // malloc 内部
    char *parsed = malloc(strlen(payload) + 1); // 显式 malloc
    
    if (topic_copy == NULL || parsed == NULL) {
        // AI 可能连 NULL 检查都忘了
        return;  // 内存泄漏！topic_copy 可能已分配
    }
    
    strcpy(parsed, payload);
    process_message(topic_copy, parsed);
    
    free(topic_copy);  // 如果 process_message 异常返回，泄漏
    free(parsed);
}
 
// ❌ AI 典型错误：C++ 中使用 STL 容器
#include <vector>
#include <string>
 
void collect_readings(void) {
    std::vector<float> readings;  // 内部使用 new/delete
    std::string label = "sensor"; // 动态分配
    
    for (int i = 0; i < 100; i++) {
        readings.push_back(read_adc());  // 可能触发 realloc
    }
}

// ✅ 正确：使用静态缓冲区和内存池
#define MAX_TOPIC_LEN    64
#define MAX_PAYLOAD_LEN  256
#define MSG_POOL_SIZE    8
 
typedef struct {
    char topic[MAX_TOPIC_LEN];
    char payload[MAX_PAYLOAD_LEN];
    bool in_use;
} MqttMessage_t;
 
static MqttMessage_t s_msgPool[MSG_POOL_SIZE];
 
static MqttMessage_t* msg_pool_alloc(void) {
    for (int i = 0; i < MSG_POOL_SIZE; i++) {
        if (!s_msgPool[i].in_use) {
            s_msgPool[i].in_use = true;
            return &s_msgPool[i];
        }
    }
    return NULL;  // 池已满
}
 
static void msg_pool_free(MqttMessage_t *msg) {
    if (msg != NULL) {
        msg->in_use = false;
    }
}
 
void handle_mqtt_message(const char *topic, const char *payload) {
    MqttMessage_t *msg = msg_pool_alloc();
    if (msg == NULL) {
        log_error("Message pool exhausted");
        return;
    }
    
    strncpy(msg->topic, topic, MAX_TOPIC_LEN - 1);
    msg->topic[MAX_TOPIC_LEN - 1] = '\0';
    strncpy(msg->payload, payload, MAX_PAYLOAD_LEN - 1);
    msg->payload[MAX_PAYLOAD_LEN - 1] = '\0';
    
    process_message(msg);
    msg_pool_free(msg);
}
 
// ✅ 正确：C++ 中使用固定大小容器
#include <array>
#include <etl/vector.h>  // Embedded Template Library
 
void collect_readings(void) {
    etl::vector<float, 100> readings;  // 编译时固定容量，无动态分配
    static const char label[] = "sensor";  // 编译时常量
    
    for (int i = 0; i < 100; i++) {
        if (!readings.full()) {
            readings.push_back(read_adc());
        }
    }
}

## 无界分配防护规则
- 禁止使用 malloc/calloc/realloc/free/strdup
- 禁止使用 C++ new/delete
- 禁止使用 std::vector/std::string/std::map 等动态容器
- 使用 ETL（Embedded Template Library）替代 STL
- 所有缓冲区大小必须在编译时确定
- 使用内存池模式管理同类型对象
- 链接时使用 --wrap=malloc 捕获意外的动态分配

// ❌ AI 典型错误：使用二值信号量替代互斥锁（无优先级继承）
SemaphoreHandle_t g_sensorLock;
 
void init(void) {
    g_sensorLock = xSemaphoreCreateBinary();  // ❌ 二值信号量无优先级继承
    xSemaphoreGive(g_sensorLock);
}
 
// 低优先级任务（优先级 1）
void task_logging(void *param) {
    while (1) {
        xSemaphoreTake(g_sensorLock, portMAX_DELAY);
        // 长时间操作：写入 SD 卡（可能 50-200ms）
        write_log_to_sd();
        xSemaphoreGive(g_sensorLock);
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}
 
// 高优先级任务（优先级 3）
void task_control(void *param) {
    while (1) {
        xSemaphoreTake(g_sensorLock, portMAX_DELAY);
        // 关键控制逻辑
        read_sensor_and_actuate();  // 必须在 10ms 内完成
        xSemaphoreGive(g_sensorLock);
        vTaskDelay(pdMS_TO_TICKS(10));
    }
}
 
// 中优先级任务（优先级 2）——罪魁祸首
void task_display(void *param) {
    while (1) {
        update_lcd();  // 耗时 100ms，抢占 task_logging
        vTaskDelay(pdMS_TO_TICKS(500));
    }
}
// 结果：task_control 等待锁 → task_logging 持有锁但被 task_display 抢占
// → task_control 被间接阻塞 100ms+，违反 10ms 截止时间

// ✅ 正确：使用互斥锁（带优先级继承）
SemaphoreHandle_t g_sensorMutex;
 
void init(void) {
    g_sensorMutex = xSemaphoreCreateMutex();  // ✅ 互斥锁自带优先级继承
    configASSERT(g_sensorMutex != NULL);
}
 
// 低优先级任务（优先级 1）
void task_logging(void *param) {
    while (1) {
        // 当 task_control 等待此锁时，task_logging 的优先级
        // 会被临时提升到 3（task_control 的优先级），
        // 防止 task_display 抢占
        if (xSemaphoreTake(g_sensorMutex, pdMS_TO_TICKS(100)) == pdTRUE) {
            write_log_to_sd();
            xSemaphoreGive(g_sensorMutex);
        } else {
            log_warning("Sensor mutex timeout in logging task");
        }
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}
 
// 高优先级任务（优先级 3）
void task_control(void *param) {
    while (1) {
        if (xSemaphoreTake(g_sensorMutex, pdMS_TO_TICKS(10)) == pdTRUE) {
            read_sensor_and_actuate();
            xSemaphoreGive(g_sensorMutex);
        } else {
            // 超时处理：进入安全状态
            enter_safe_state();
            log_error("Control task mutex timeout - entering safe state");
        }
        vTaskDelay(pdMS_TO_TICKS(10));
    }
}

## 优先级反转防护规则
- 禁止使用二值信号量保护共享资源（使用互斥锁）
- 互斥锁必须使用 xSemaphoreCreateMutex()（FreeRTOS）或 k_mutex（Zephyr）
- 所有互斥锁获取必须有超时（禁止 portMAX_DELAY）
- 超时后必须有错误处理（进入安全状态或重试）
- 持有互斥锁的时间必须最小化（< 1ms 为佳）
- 任务优先级分配必须有文档，包含优先级反转分析

// ❌ AI 典型错误：ISR 中的各种阻塞操作
void USART1_IRQHandler(void) {
    if (__HAL_UART_GET_FLAG(&huart1, UART_FLAG_RXNE)) {
        uint8_t data = huart1.Instance->DR;
        
        // ❌ 错误 1：ISR 中使用 printf（内部有锁、缓冲区分配）
        printf("Received: 0x%02X\n", data);
        
        // ❌ 错误 2：ISR 中使用 HAL_Delay（依赖 SysTick 中断，会死锁）
        HAL_Delay(1);
        
        // ❌ 错误 3：ISR 中使用非 FromISR 的 RTOS API
        xSemaphoreTake(g_mutex, portMAX_DELAY);
        process_data(data);
        xSemaphoreGive(g_mutex);
        
        // ❌ 错误 4：ISR 中使用 malloc
        char *msg = malloc(64);
        sprintf(msg, "Data: %d", data);
        send_to_cloud(msg);  // 网络操作！
        free(msg);
    }
}

// ✅ 正确：ISR 最小化 + 延迟处理
// 环形缓冲区（静态分配）
#define RX_BUF_SIZE 256  // 必须是 2 的幂
static volatile uint8_t s_rxBuffer[RX_BUF_SIZE];
static volatile uint16_t s_rxHead = 0;
static volatile uint16_t s_rxTail = 0;
 
// ISR：仅做数据搬运，< 1μs
void USART1_IRQHandler(void) {
    BaseType_t xHigherPriorityTaskWoken = pdFALSE;
    
    if (__HAL_UART_GET_FLAG(&huart1, UART_FLAG_RXNE)) {
        uint8_t data = (uint8_t)(huart1.Instance->DR & 0xFF);
        
        // 写入环形缓冲区
        uint16_t nextHead = (s_rxHead + 1) & (RX_BUF_SIZE - 1);
        if (nextHead != s_rxTail) {  // 缓冲区未满
            s_rxBuffer[s_rxHead] = data;
            s_rxHead = nextHead;
        }
        // 溢出时静默丢弃（或设置错误标志）
        
        // 通知处理任务（使用 FromISR 版本）
        vTaskNotifyGiveFromISR(g_uartTaskHandle, &xHigherPriorityTaskWoken);
    }
    
    // 如果唤醒了更高优先级任务，触发上下文切换
    portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}
 
// 处理任务：在任务上下文中安全地处理数据
void task_uart_process(void *param) {
    while (1) {
        // 等待 ISR 通知
        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
        
        // 在任务上下文中安全地处理所有待处理数据
        while (s_rxTail != s_rxHead) {
            uint8_t data = s_rxBuffer[s_rxTail];
            s_rxTail = (s_rxTail + 1) & (RX_BUF_SIZE - 1);
            
            // 这里可以安全地使用 printf、mutex、malloc 等
            process_and_log(data);
        }
    }
}

## ISR 阻塞防护规则
- ISR 中仅允许：读写 volatile 变量、写入环形缓冲区、调用 FromISR API、清除中断标志
- ISR 中禁止：printf/sprintf、HAL_Delay、malloc/free、非 FromISR 的 RTOS API、浮点运算、网络操作
- ISR 执行时间预算：硬实时 < 1μs，软实时 < 10μs
- 所有 ISR 必须注释预期执行时间和触发频率
- 使用"ISR 设置标志 + 任务处理"模式（Deferred Interrupt Handling）

// ❌ AI 典型错误 1：完全没有看门狗
int main(void) {
    HAL_Init();
    SystemClock_Config();
    MX_GPIO_Init();
    MX_USART1_UART_Init();
    // 没有看门狗初始化！
    
    while (1) {
        read_sensors();
        process_data();
        send_to_cloud();  // 如果网络超时，系统卡死
        HAL_Delay(1000);
    }
}
 
// ❌ AI 典型错误 2：在 ISR 中喂狗（掩盖主循环死锁）
void SysTick_Handler(void) {
    HAL_IncTick();
    HAL_IWDG_Refresh(&hiwdg);  // ❌ 每 1ms 喂狗，即使主循环已死
}
 
// ❌ AI 典型错误 3：无条件喂狗（不检查系统健康状态）
while (1) {
    HAL_IWDG_Refresh(&hiwdg);  // ❌ 总是喂狗，即使子系统已故障
    maybe_broken_function();
    HAL_Delay(100);
}

// ✅ 正确：多层看门狗策略
// === 硬件看门狗初始化 ===
static IWDG_HandleTypeDef hiwdg;
 
void watchdog_init(void) {
    hiwdg.Instance = IWDG;
    hiwdg.Init.Prescaler = IWDG_PRESCALER_64;
    hiwdg.Init.Reload = 1000;  // 约 2 秒超时
    HAL_StatusTypeDef status = HAL_IWDG_Init(&hiwdg);
    configASSERT(status == HAL_OK);
}
 
// === 软件看门狗：每个任务独立监控 ===
#define NUM_TASKS 4
typedef struct {
    volatile uint32_t lastFeedTime;
    uint32_t timeoutMs;
    const char *taskName;
    bool enabled;
} TaskWatchdog_t;
 
static TaskWatchdog_t s_taskWdg[NUM_TASKS];
 
void task_watchdog_feed(uint8_t taskId) {
    if (taskId < NUM_TASKS) {
        s_taskWdg[taskId].lastFeedTime = HAL_GetTick();
    }
}
 
bool task_watchdog_check_all(void) {
    uint32_t now = HAL_GetTick();
    for (int i = 0; i < NUM_TASKS; i++) {
        if (s_taskWdg[i].enabled) {
            if ((now - s_taskWdg[i].lastFeedTime) > s_taskWdg[i].timeoutMs) {
                log_error("Task watchdog timeout: %s", s_taskWdg[i].taskName);
                return false;  // 有任务超时
            }
        }
    }
    return true;  // 所有任务健康
}
 
// === 主看门狗任务：仅在所有子系统健康时喂硬件看门狗 ===
void task_watchdog_monitor(void *param) {
    while (1) {
        bool allHealthy = task_watchdog_check_all();
        
        if (allHealthy) {
            HAL_IWDG_Refresh(&hiwdg);  // ✅ 仅在所有任务健康时喂狗
        } else {
            // 不喂狗 → 硬件看门狗将在 2 秒后复位系统
            log_error("System unhealthy, watchdog reset pending");
            // 可选：保存故障信息到 Flash，供复位后诊断
            save_crash_info_to_flash();
        }
        
        vTaskDelay(pdMS_TO_TICKS(500));  // 每 500ms 检查一次
    }
}
 
// === 各任务中喂软件看门狗 ===
void task_sensor(void *param) {
    while (1) {
        read_sensors();
        process_data();
        task_watchdog_feed(TASK_ID_SENSOR);  // ✅ 任务正常完成一个周期后喂狗
        vTaskDelay(pdMS_TO_TICKS(100));
    }
}

## 看门狗防护规则
- 系统必须启用独立看门狗（IWDG），不依赖系统时钟
- 禁止在 ISR 中喂看门狗（防止主循环死锁时 ISR 仍在喂狗）
- 禁止无条件喂狗（必须先检查系统健康状态）
- 每个关键任务必须有独立的软件看门狗监控
- 看门狗超时 = 最大正常周期 × 2（留足余量）
- 系统复位前必须保存故障信息（复位原因、最后运行的任务、栈指针）
- main() 启动后的前 5 行内必须初始化看门狗

// ❌ AI 典型错误：非原子操作 + 缺少 volatile
uint32_t g_sensorValue = 0;  // 缺少 volatile
 
void TIM2_IRQHandler(void) {
    g_sensorValue = ADC1->DR;  // ISR 中写入
    HAL_TIM_IRQHandler(&htim2);
}
 
void task_display(void *param) {
    while (1) {
        // 在 32 位 MCU 上，32 位读取是原子的，但编译器可能优化掉重复读取
        uint32_t val = g_sensorValue;  // 可能读到缓存值
        update_display(val);
        vTaskDelay(pdMS_TO_TICKS(100));
    }
}
 
// ❌ AI 典型错误：多字节非原子操作
struct {
    uint16_t temperature;  // 2 字节
    uint16_t humidity;     // 2 字节
    uint32_t timestamp;    // 4 字节
} g_sensorData;  // 8 字节结构体，读写非原子
 
void ISR_update(void) {
    g_sensorData.temperature = read_temp();
    // ← 如果此时任务读取 g_sensorData，会得到半新半旧的数据
    g_sensorData.humidity = read_humidity();
    g_sensorData.timestamp = get_tick();
}

// ✅ 正确：volatile + 临界区保护
static volatile uint32_t s_sensorValue = 0;  // volatile 防止编译器优化
 
void TIM2_IRQHandler(void) {
    s_sensorValue = ADC1->DR;  // 32 位原子写入（Cortex-M 保证）
    HAL_TIM_IRQHandler(&htim2);
}
 
// ✅ 正确：多字节数据使用双缓冲 + 原子标志
typedef struct {
    uint16_t temperature;
    uint16_t humidity;
    uint32_t timestamp;
} SensorData_t;
 
static volatile SensorData_t s_sensorBuf[2];  // 双缓冲
static volatile uint8_t s_activeBuffer = 0;    // 原子标志
 
void ISR_update(void) {
    uint8_t writeIdx = 1 - s_activeBuffer;  // 写入非活跃缓冲区
    s_sensorBuf[writeIdx].temperature = read_temp();
    s_sensorBuf[writeIdx].humidity = read_humidity();
    s_sensorBuf[writeIdx].timestamp = get_tick();
    s_activeBuffer = writeIdx;  // 原子切换（单字节写入是原子的）
}
 
SensorData_t task_read_sensor(void) {
    uint8_t readIdx = s_activeBuffer;  // 读取活跃缓冲区索引
    return s_sensorBuf[readIdx];       // 读取一致的数据快照
}

## 竞态条件防护规则
- ISR 与任务共享的变量必须声明为 volatile
- 多字节共享数据必须使用临界区或双缓冲保护
- 禁止在未保护的情况下进行 read-modify-write 操作
- 使用原子操作（__LDREX/__STREX）处理计数器和标志
- 所有共享资源必须在设计文档中标注访问者和保护机制

// ❌ AI 典型错误：编造寄存器地址和位域
// AI 可能混淆不同 STM32 系列的寄存器
void configure_adc(void) {
    // ❌ 这个寄存器地址可能是 STM32F1 的，不适用于 STM32F4
    *(volatile uint32_t *)0x40012400 = 0x00000001;
    
    // ❌ 位域定义可能是错误的
    ADC1->CR2 |= (1 << 22);  // AI 说这是"启用 DMA"，但实际位可能不同
    
    // ❌ 配置序列可能遗漏关键步骤
    ADC1->CR2 |= ADC_CR2_ADON;  // 忘记先配置通道和采样时间
}

// ✅ 正确：使用 HAL/LL API + 官方头文件定义
void configure_adc(void) {
    // 使用 CubeMX 生成的初始化代码或 HAL API
    ADC_ChannelConfTypeDef sConfig = {0};
    
    hadc1.Instance = ADC1;
    hadc1.Init.Resolution = ADC_RESOLUTION_12B;
    hadc1.Init.ScanConvMode = DISABLE;
    hadc1.Init.ContinuousConvMode = DISABLE;
    hadc1.Init.ExternalTrigConvEdge = ADC_EXTERNALTRIGCONVEDGE_NONE;
    hadc1.Init.DataAlign = ADC_DATAALIGN_RIGHT;
    hadc1.Init.NbrOfConversion = 1;
    
    HAL_StatusTypeDef status = HAL_ADC_Init(&hadc1);
    configASSERT(status == HAL_OK);
    
    sConfig.Channel = ADC_CHANNEL_0;
    sConfig.Rank = 1;
    sConfig.SamplingTime = ADC_SAMPLETIME_84CYCLES;
    status = HAL_ADC_ConfigChannel(&hadc1, &sConfig);
    configASSERT(status == HAL_OK);
}

## 硬件寄存器幻觉防护规则
- 禁止直接使用硬编码寄存器地址（使用 CMSIS/HAL 头文件定义）
- 禁止手动定义位域（使用官方 SDK 提供的宏）
- 所有寄存器操作必须注释数据手册章节和页码
- 外设初始化优先使用 HAL API 或 CubeMX 生成代码
- 必须在 Steering 规则中指定确切的 MCU 型号和 SDK 版本

// ❌ AI 典型错误：busy-wait 轮询
while (1) {
    if (HAL_GPIO_ReadPin(BUTTON_GPIO_Port, BUTTON_Pin) == GPIO_PIN_SET) {
        handle_button();
    }
    // CPU 100% 占用，持续消耗 50-100mA
}
 
// ❌ AI 典型错误：未关闭未使用外设
void init(void) {
    __HAL_RCC_GPIOA_CLK_ENABLE();
    __HAL_RCC_GPIOB_CLK_ENABLE();
    __HAL_RCC_GPIOC_CLK_ENABLE();  // 可能只用了 GPIOA
    __HAL_RCC_USART1_CLK_ENABLE();
    __HAL_RCC_USART2_CLK_ENABLE(); // 可能只用了 USART1
    __HAL_RCC_SPI1_CLK_ENABLE();   // 可能根本没用 SPI
}

// ✅ 正确：中断驱动 + 低功耗模式
void init(void) {
    // 仅启用需要的外设时钟
    __HAL_RCC_GPIOA_CLK_ENABLE();
    __HAL_RCC_USART1_CLK_ENABLE();
    
    // 配置按钮为中断触发
    HAL_NVIC_SetPriority(EXTI0_IRQn, 5, 0);
    HAL_NVIC_EnableIRQ(EXTI0_IRQn);
}
 
void EXTI0_IRQHandler(void) {
    HAL_GPIO_EXTI_IRQHandler(BUTTON_Pin);
}
 
void HAL_GPIO_EXTI_Callback(uint16_t GPIO_Pin) {
    if (GPIO_Pin == BUTTON_Pin) {
        BaseType_t xHigherPriorityTaskWoken = pdFALSE;
        vTaskNotifyGiveFromISR(g_buttonTaskHandle, &xHigherPriorityTaskWoken);
        portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
    }
}
 
// 空闲任务钩子：进入低功耗模式
void vApplicationIdleHook(void) {
    __WFI();  // Wait For Interrupt：CPU 休眠直到下一个中断
}

## 功耗管理规则
- 禁止使用 busy-wait 轮询（使用中断或 RTOS 事件等待）
- 仅启用实际使用的外设时钟
- 空闲时必须进入低功耗模式（WFI/WFE/Stop/Standby）
- 通信完成后关闭收发器电源
- 使用 RTC 唤醒替代定时器轮询

// ❌ AI 典型错误：不安全的字符串操作
void build_response(const char *cmd, const char *data) {
    char response[64];
    strcpy(response, "OK:");     // 不检查长度
    strcat(response, cmd);        // 不检查长度
    strcat(response, ":");        // 不检查长度
    strcat(response, data);       // 如果 data 很长 → 溢出
    uart_send(response);
}
 
// ❌ AI 典型错误：不验证接收数据长度
void handle_packet(uint8_t *packet) {
    uint8_t len = packet[0];      // 长度字段来自外部输入
    char payload[128];
    memcpy(payload, &packet[1], len);  // 如果 len > 128 → 溢出
}

// ✅ 正确：安全的字符串操作
void build_response(const char *cmd, const char *data) {
    char response[64];
    int written = snprintf(response, sizeof(response), "OK:%s:%s", cmd, data);
    
    if (written < 0 || (size_t)written >= sizeof(response)) {
        // 截断警告
        log_warning("Response truncated");
    }
    uart_send(response, strnlen(response, sizeof(response)));
}
 
// ✅ 正确：验证外部输入长度
#define MAX_PAYLOAD_LEN 128
 
bool handle_packet(const uint8_t *packet, size_t packetLen) {
    if (packetLen < 1) return false;
    
    uint8_t len = packet[0];
    if (len > MAX_PAYLOAD_LEN || len > (packetLen - 1)) {
        log_error("Invalid packet length: %u", len);
        return false;
    }
    
    uint8_t payload[MAX_PAYLOAD_LEN];
    memcpy(payload, &packet[1], len);
    // 安全处理
    return process_payload(payload, len);
}

## 缓冲区溢出防护规则
- 禁止使用 strcpy/strcat/sprintf（使用 strncpy/strncat/snprintf）
- 所有 memcpy/memmove 必须先验证长度参数
- 外部输入的长度字段必须验证范围
- 所有数组访问必须检查边界
- 使用 MISRA Rule 18.1 检查指针算术

// ❌ AI 典型错误：硬编码波特率分频器（不考虑实际时钟频率）
void uart_init(void) {
    // AI 假设 APB1 时钟是 42MHz，但实际可能是 36MHz 或 84MHz
    USART1->BRR = 0x1D4C;  // 硬编码值，换个时钟配置就错了
}
 
// ❌ AI 典型错误：定时器周期计算错误
void timer_init_1ms(void) {
    // AI 假设系统时钟 168MHz，但可能是 72MHz
    htim2.Init.Prescaler = 167;     // 168MHz / 168 = 1MHz
    htim2.Init.Period = 999;         // 1MHz / 1000 = 1kHz = 1ms
    // 如果实际时钟是 72MHz，定时周期变成 2.33ms
}

// ✅ 正确：使用 HAL 宏获取实际时钟频率
void uart_init(uint32_t baudrate) {
    // HAL 自动根据实际 APB 时钟计算 BRR
    huart1.Init.BaudRate = baudrate;
    HAL_StatusTypeDef status = HAL_UART_Init(&huart1);
    configASSERT(status == HAL_OK);
}
 
// ✅ 正确：基于实际时钟频率计算定时器参数
void timer_init_1ms(void) {
    uint32_t timerClock = HAL_RCC_GetPCLK1Freq();
    // 如果 APB1 预分频器 > 1，定时器时钟 = APB1 × 2
    if ((RCC->CFGR & RCC_CFGR_PPRE1) != 0) {
        timerClock *= 2;
    }
    
    htim2.Init.Prescaler = (timerClock / 1000000) - 1;  // 分频到 1MHz
    htim2.Init.Period = 999;                              // 1MHz / 1000 = 1ms
    HAL_StatusTypeDef status = HAL_TIM_Base_Init(&htim2);
    configASSERT(status == HAL_OK);
}

## 时钟配置规则
- 禁止硬编码时钟分频器和波特率寄存器值
- 使用 HAL_RCC_GetSysClockFreq() 等 API 获取实际时钟
- 时钟树配置必须通过 CubeMX 生成或有详细计算文档
- 所有定时器初始化必须基于运行时获取的时钟频率计算
- 串口初始化后必须验证实际波特率误差 < 2%

// ❌ AI 典型错误：DMA 缓冲区未对齐 + 缓存一致性问题
uint8_t rxBuffer[256];  // 可能未对齐到缓存行
 
void start_dma_receive(void) {
    HAL_UART_Receive_DMA(&huart1, rxBuffer, 256);
}
 
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) {
    // ❌ 在有 D-Cache 的 MCU 上（如 STM32H7），
    // CPU 可能读到缓存中的旧数据，而非 DMA 写入的新数据
    process_data(rxBuffer, 256);
}

// ✅ 正确：对齐 + 缓存管理
// 对齐到 32 字节缓存行，放在非缓存区域或手动管理缓存
__attribute__((aligned(32)))
static uint8_t s_rxBuffer[256];
 
void start_dma_receive(void) {
    // 在启动 DMA 前使缓存无效（确保 DMA 写入的数据可见）
    SCB_InvalidateDCache_by_Addr((uint32_t *)s_rxBuffer, sizeof(s_rxBuffer));
    HAL_UART_Receive_DMA(&huart1, s_rxBuffer, sizeof(s_rxBuffer));
}
 
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) {
    // DMA 完成后，使缓存无效以读取最新数据
    SCB_InvalidateDCache_by_Addr((uint32_t *)s_rxBuffer, sizeof(s_rxBuffer));
    process_data(s_rxBuffer, sizeof(s_rxBuffer));
}

## DMA 配置规则
- DMA 缓冲区必须 32 字节对齐（`__attribute__((aligned(32)))`）
- 有 D-Cache 的 MCU：DMA 传输前后必须管理缓存一致性
- DMA 缓冲区必须声明为 static 或全局（不能在栈上）
- DMA 传输期间禁止 CPU 访问同一缓冲区
- 使用双缓冲或乒乓缓冲实现连续 DMA 传输

// ❌ AI 典型错误：不验证固件完整性和来源
void ota_update(const char *url) {
    uint8_t *firmware = download_file(url);  // 动态分配！
    // 没有签名验证
    // 没有版本检查
    // 没有回滚机制
    flash_write(FIRMWARE_ADDR, firmware, firmware_size);
    system_reset();  // 如果固件损坏，设备变砖
}

// ✅ 正确：安全的 OTA 更新流程
typedef struct {
    uint32_t magic;          // 固件标识
    uint32_t version;        // 版本号
    uint32_t size;           // 固件大小
    uint8_t  sha256[32];     // SHA-256 哈希
    uint8_t  signature[64];  // Ed25519 签名
} FirmwareHeader_t;
 
ota_status_t ota_update_safe(const char *url) {
    // 1. 下载到备用分区（A/B 分区方案）
    ota_status_t status = download_to_partition(OTA_PARTITION_INACTIVE, url);
    if (status != OTA_OK) return status;
    
    // 2. 验证固件头
    FirmwareHeader_t header;
    flash_read(OTA_PARTITION_INACTIVE, &header, sizeof(header));
    
    if (header.magic != FIRMWARE_MAGIC) return OTA_ERR_INVALID;
    if (header.version <= get_current_version()) return OTA_ERR_OLD_VERSION;
    
    // 3. 验证 SHA-256 哈希
    if (!verify_sha256(OTA_PARTITION_INACTIVE, &header)) return OTA_ERR_CHECKSUM;
    
    // 4. 验证数字签名
    if (!verify_signature(&header, OTA_PUBLIC_KEY)) return OTA_ERR_SIGNATURE;
    
    // 5. 标记新分区为待验证，设置回滚计数器
    set_boot_partition(OTA_PARTITION_INACTIVE);
    set_rollback_counter(3);  // 3 次启动失败后自动回滚
    
    // 6. 重启到新固件
    system_reset();
    return OTA_OK;
}

## OTA 更新安全规则
- OTA 必须使用 A/B 分区方案（保留可回滚的旧固件）
- 固件必须验证数字签名（Ed25519 或 ECDSA）
- 固件必须验证完整性哈希（SHA-256）
- 必须检查版本号（禁止降级攻击）
- 必须有自动回滚机制（启动失败 N 次后回滚）
- OTA 下载使用流式写入，不在 RAM 中缓存整个固件

## 新项目 Steering 规则设置清单
 
### 第一步：项目信息收集
- [ ] 确定目标 MCU 型号和系列
- [ ] 确定 SDK/框架版本（ESP-IDF / STM32 HAL / Zephyr / Arduino）
- [ ] 确定 RTOS 选择（FreeRTOS / Zephyr / 裸机）
- [ ] 确定资源预算（Flash / RAM / 栈大小）
- [ ] 确定安全标准要求（MISRA / IEC 61508 / ISO 26262 / 无）
- [ ] 确定功耗要求（电池供电 / 市电 / 太阳能）
 
### 第二步：创建基础规则文件
- [ ] 创建 CLAUDE.md 或 .kiro/steering/embedded-base.md
- [ ] 填写项目概述（MCU、RTOS、语言、编译器、资源预算）
- [ ] 添加"绝对禁止"规则（内存、中断、编码标准）
- [ ] 添加"必须遵守"规则（RTOS、看门狗、命名规范）
- [ ] 添加代码风格规则（命名、文件组织、注释）
 
### 第三步：添加平台专用规则
- [ ] 创建平台规则文件（如 .kiro/steering/platform-esp32.md）
- [ ] 添加平台特定的禁止规则
- [ ] 添加平台特定的必须规则
- [ ] 添加平台特定的内存分区说明
 
### 第四步：配置检测工具
- [ ] 配置静态分析工具（Cppcheck / PC-lint）
- [ ] 配置编译器警告级别（-Wall -Wextra -Werror）
- [ ] 配置栈使用分析（-fstack-usage）
- [ ] 配置链接器 map 文件输出
- [ ] 配置 CI/CD 中的自动检查
 
### 第五步：验证规则有效性
- [ ] 让 AI 生成一段测试代码，检查是否遵守规则
- [ ] 故意违反规则，检查 AI 是否被规则约束
- [ ] 运行静态分析，确认无违规

## 代码审查 Steering 规则验证清单
 
### 内存安全
- [ ] 无 malloc/calloc/realloc/free 调用
- [ ] 无 C++ new/delete 调用
- [ ] 无可变长数组（VLA）
- [ ] 所有局部变量总大小 < 256 字节
- [ ] 大缓冲区使用 static 或全局声明
- [ ] 字符串操作使用带长度限制的版本
 
### 中断安全
- [ ] ISR 中无阻塞操作
- [ ] ISR 中无 printf/sprintf/malloc
- [ ] ISR 中使用 FromISR 后缀的 RTOS API
- [ ] ISR 执行时间在预算内
- [ ] 中断优先级配置正确
 
### RTOS 安全
- [ ] 互斥锁使用 xSemaphoreCreateMutex（非二值信号量）
- [ ] 所有锁获取有超时
- [ ] 任务栈大小有计算依据
- [ ] 任务优先级分配有文档
 
### 看门狗
- [ ] 看门狗已初始化
- [ ] 喂狗不在 ISR 中
- [ ] 喂狗前检查系统健康状态
- [ ] 看门狗超时设置合理
 
### 编码标准
- [ ] 无递归调用
- [ ] 所有 switch 有 default
- [ ] 所有函数返回值已检查
- [ ] 无魔术数字
- [ ] 命名符合项目规范
 
### 硬件交互
- [ ] 无硬编码寄存器地址
- [ ] 使用 HAL/LL API 或官方宏
- [ ] DMA 缓冲区正确对齐
- [ ] 时钟配置基于运行时获取的频率

你是一位嵌入式系统安全审查专家。请审查以下 [平台] 代码，检查以下问题：

1. 内存安全：是否有动态分配、栈溢出风险、缓冲区溢出
2. 中断安全：ISR 中是否有阻塞操作、优先级配置是否正确
3. RTOS 安全：是否有优先级反转风险、死锁风险
4. 看门狗：是否正确配置和使用
5. MISRA C 合规：是否违反关键 MISRA 规则
6. 功耗：是否有不必要的 busy-wait 或未关闭的外设

目标平台：[MCU 型号]
RTOS：[FreeRTOS / Zephyr / 裸机]
RAM 预算：[大小]
栈大小：[大小]

对每个发现的问题，请提供：
- 问题严重级别（🔴 致命 / 🟡 警告 / 🔵 建议）
- 问题描述
- 修复建议（含代码）

代码：
[粘贴代码]

请为以下嵌入式项目生成完整的 Steering 规则文件（CLAUDE.md 格式）：

项目信息：
- MCU：[型号]
- SDK：[名称和版本]
- RTOS：[名称或裸机]
- 语言：[C / C++ / Rust]
- Flash：[大小]，当前使用 [大小]
- RAM：[大小]，当前使用 [大小]
- 安全标准：[MISRA / IEC 61508 / 无]
- 功耗要求：[电池供电 / 市电]
- 关键外设：[UART, SPI, I2C, ADC, ...]

请生成包含以下部分的规则：
1. 项目概述
2. 绝对禁止规则（内存、中断、编码标准、安全）
3. 必须遵守规则（RTOS、看门狗、命名）
4. 平台专用规则
5. 代码风格规则

请分析以下嵌入式代码，检测是否存在以下反模式：

1. 栈溢出风险（大局部变量、递归）
2. 无界分配（malloc/new/STL 容器）
3. 中断优先级反转（二值信号量保护共享资源）
4. ISR 中阻塞（printf、delay、非 FromISR API）
5. 缺少看门狗（无 WDT 初始化或错误的喂狗策略）
6. 竞态条件（缺少 volatile、未保护的共享数据）
7. 硬件寄存器幻觉（硬编码地址、错误位域）
8. 功耗失控（busy-wait、未关闭外设时钟）
9. 缓冲区溢出（不安全的字符串操作、未验证长度）
10. 时钟配置错误（硬编码分频器）

对每个检测到的反模式，输出：
- 反模式编号和名称
- 代码位置（行号）
- 严重程度
- 修复代码

代码：
[粘贴代码]

# CLAUDE.md — ESP32-S3 智能家居网关
 
## 项目概述
- MCU：ESP32-S3-WROOM-1（N16R8）
- SDK：ESP-IDF v5.3.1
- RTOS：FreeRTOS（ESP-IDF 内置 SMP 版本）
- 语言：C11
- Flash：16MB（当前使用 ~3.2MB，预算 8MB）
- PSRAM：8MB（用于 Web 服务器缓冲区和 BLE 扫描结果）
- 内部 SRAM：512KB（当前使用 ~280KB）
- 安全标准：无强制标准，但遵循 MISRA C 核心子集
- 功耗：市电供电，但需考虑 Wi-Fi 省电模式
 
## 🚫 绝对禁止
- 禁止使用 malloc/free（使用 ESP-IDF 的 heap_caps_malloc 或静态分配）
- 禁止在 ISR 中使用 ESP_LOG*（使用 ESP_DRAM_LOGE）
- 禁止在 Core 0 上运行应用任务（Core 0 专用于 Wi-Fi/BT 协议栈）
- 禁止在 IRAM 函数中访问 Flash 常量
- 禁止使用 Arduino 兼容层的 delay()
- 禁止在 Wi-Fi/BLE 回调中执行耗时操作
- 禁止硬编码 Wi-Fi 密码或 MQTT 凭证（使用 NVS 加密存储）
 
## ⚠️ 必须遵守
- 任务栈最小 4096 字节
- 所有网络操作必须有超时（默认 10 秒）
- MQTT 重连必须使用指数退避（1s → 2s → 4s → ... → 60s max）
- OTA 更新必须验证固件签名（使用 esp_secure_boot）
- 使用 esp_task_wdt 启用任务看门狗，超时 30 秒
- 所有 NVS 操作必须检查返回值
- BLE 扫描结果存储在 PSRAM（heap_caps_malloc + MALLOC_CAP_SPIRAM）
- Web 服务器响应缓冲区存储在 PSRAM
 
## 任务优先级分配
| 优先级 | 任务 | 核心 | 栈大小 | 说明 |
|--------|------|------|--------|------|
| 24 | Wi-Fi/BT | Core 0 | 系统管理 | ESP-IDF 内部 |
| 10 | MQTT 客户端 | Core 1 | 8192 | 云端通信 |
| 8 | Zigbee 网关 | Core 1 | 8192 | 设备控制 |
| 6 | BLE 扫描 | Core 1 | 4096 | 传感器数据采集 |
| 4 | Web 服务器 | Core 1 | 8192 | 本地配置 |
| 2 | 日志记录 | Core 1 | 4096 | 写入 SD 卡 |
| 1 | 看门狗监控 | Core 1 | 2048 | 系统健康检查 |

.kiro/
└── steering/
    ├── embedded-base.md          # inclusion: always
    ├── platform-esp32-s3.md      # inclusion: always
    ├── driver-zigbee.md          # inclusion: auto（匹配 src/zigbee/**）
    ├── driver-ble.md             # inclusion: auto（匹配 src/ble/**）
    └── security-ota.md           # inclusion: auto（匹配 src/ota/**）

---
inclusion: always
---
 
# 嵌入式基础规则
 
## 内存管理
- 禁止标准 malloc/free，使用 heap_caps_malloc 指定内存类型
- 大缓冲区（>1KB）分配到 PSRAM
- DMA 缓冲区必须在内部 SRAM 且 32 字节对齐
 
## 中断安全
- ISR 中仅允许：设置标志、写入环形缓冲区、调用 FromISR API
- ISR 执行时间 < 10μs
 
## 错误处理
- 所有 ESP-IDF API 调用必须检查 esp_err_t 返回值
- 使用 ESP_ERROR_CHECK() 或自定义错误处理

请为 MQTT 消息处理模块编写代码，接收传感器数据并转发到云端。