hqz-2024 ESP-IDF Skills 模块（ESP-IDF 5.5.4）
1. Skills 描述（给 AI 用）
作用
该 Skills 用于生成 ESP-IDF 5.5.4 工程级代码，确保代码满足官方推荐开发规范，默认使用官方 API、标准组件化结构、统一错误处理与日志机制，输出代码可直接 idf.py build。
适用范围
- WiFi（STA/AP，默认 STA）
- BLE（NimBLE / Bluedroid）
- GPIO（输入/输出/中断）
- OTA（
esp_https_ota） - NVS（
nvs_flash） - FreeRTOS（任务、队列、事件组、互斥量）
- 事件机制（
esp_event） - 网络基础（
esp_netif）
使用约束
- 必须基于 ESP-IDF 5.5.4。
- 禁止生成 Arduino 风格 API。
- 禁止使用 legacy/过时初始化路径（除非用户明确要求）。
- 输出必须为工程代码风格，不得生成教学 Demo 话术或伪代码。
- 每个函数必须可复用，优先返回
esp_err_t。
2. 全局编码规范（强约束）
- 必须使用 ESP-IDF 日志宏：
ESP_LOGI/ESP_LOGW/ESP_LOGE。 - 禁止 Arduino 风格 API（如
pinMode/digitalWrite/WiFi.begin）。 - 所有外设初始化必须使用官方 driver（如
driver/gpio.h）。 - 错误处理必须使用
ESP_ERROR_CHECK或标准错误码返回（esp_err_t）。 - FreeRTOS 任务必须规范创建：
xTaskCreatePinnedToCore（或tskNO_AFFINITY）。 - 禁止直接访问底层寄存器（除非用户特别说明且隔离到专用模块）。
- 禁止把多模块逻辑全部塞入
app_main，必须模块化。
3. 项目结构模板（必须严格遵守）
espidf_skills_project/
├─ CMakeLists.txt
├─ sdkconfig.defaults
├─ main/
│ ├─ CMakeLists.txt
│ └─ main.c
└─ components/
└─ espidf_skills/
├─ CMakeLists.txt
├─ include/
│ └─ espidf_skills.h
└─ espidf_skills.c
4. 常用功能模板（可复用函数要求）
必须包含并优先复用以下接口：
skills_nvs_init()：NVS 初始化skills_event_loop_init()：事件循环与网络栈初始化skills_wifi_sta_start()：WiFi STA 初始化与连接skills_gpio_output_init()/skills_gpio_input_init()/skills_gpio_set_level()：GPIO 输入输出skills_task_create_pinned()：FreeRTOS 任务规范创建skills_ota_https_start()：OTA 基础结构（esp_https_ota）
调用方（如 main.c）必须通过这些接口组装业务逻辑，不允许重复造轮子。
5. API 使用约束（非常重要）
- WiFi 必须使用：
esp_netif + esp_event + esp_wifi - 事件机制必须基于：
esp_event_handler_instance_register - 禁止直接操作寄存器（除非特别说明）
- BLE 必须使用 NimBLE 或 Bluedroid（推荐 NimBLE）
- OTA 必须使用官方
esp_https_ota - 存储必须使用
nvs_flash
6. 代码风格要求
- 语言：C99
- 模块化函数设计
- 工程代码风格（非示例代码风格）
- 每个函数必须可复用
- 每个函数必须带简要注释（功能与用法）
- include 不允许省略
- 禁止伪代码
7. 输出格式约束（给 AI）
- 输出使用 Markdown
- 所有代码块必须完整可编译
- 必须包含完整 include
- 不写伪代码
- 目录结构与 CMake 依赖必须完整
生成策略（执行指令）
- 优先生成组件：
components/<module>/include/*.h+*.c main.c只做编排，不堆业务实现- 所有初始化函数可重复调用时需保证幂等或返回明确错误
- 所有字符串参数做空指针和长度检查
- 关键步骤打印日志，错误日志必须含
esp_err_to_name(err) - 可失败函数统一返回
esp_err_t - 仅在入口层使用
ESP_ERROR_CHECK
模板文件位置
本 Skills 附带完整模板工程，路径如下：
templates/espidf_skills_project/
直接复制该目录到目标工作区后执行：
idf.py build