用途
本技能用于调试 ESP32 固件问题，适用于以下情形：在 ESP-IDF 项目中遇到编译错误；出现运行时 panic 或 “Guru Meditation Error” 消息；发生内存相关崩溃或栈溢出；遇到 I2C/SPI/UART 通信失败；需要帮助解读串口监视器输出。参数 $ARGUMENTS 可包含错误消息或问题上下文。
调试流程
先询问上下文
如果从 $ARGUMENTS 无法看清错误，先请用户提供：完整错误消息或 panic 输出、正在构建的项目、最近的代码改动。
1. 编译错误分析
运行一次全新构建以捕获错误：
just <project>::build 2>&1 | tail -100
- 缺失头文件：
fatal error: driver/gpio.h: No such file or directory。修复方式是在 main/CMakeLists.txt 的 REQUIRES 中加入该组件：
idf_component_register(
SRCS "main.c"
REQUIRES driver
)
- 未定义引用：
undefined reference to 'some_function'。修复方式是确保包含该函数的组件出现在 REQUIRES 或 PRIV_REQUIRES 中。 - 类型错误：检查函数声明与实现之间的类型是否匹配。
2. 运行时 panic 分析
Guru Meditation Error 常见模式：
| 错误 | 原因 | 修复 |
|---|---|---|
| StoreProhibited | 写入无效内存 | 检查指针初始化 |
| LoadProhibited | 读取无效内存 | 检查空指针 |
| InstrFetchProhibited | 函数指针被破坏 | 检查回调赋值 |
| IntegerDivideByZero | 除以零 | 增加零值检查 |
| Double exception、backtrace CORRUPTED、A0 为可识别常量（如 0x10000000） | 栈缓冲区向上溢出到调用者帧——VLA 或局部数组越界索引；canary 只监视低端 | 阅读最后一条日志与 panic 之间的代码；在刚调用的驱动中查找 A0 的最高字节。参见 .claude/rules/gated-init-paths.md |
栈溢出：
Guru Meditation Error: Core 0 panic'ed (Stack overflow)
修复方式是在创建任务时增大栈大小：
xTaskCreatePinnedToCore(task_fn, "name", 4096, NULL, 5, NULL, 0);
// ^^^^ increase this
栈破坏（Stack smashing）：Stack smashing detected。修复方式是检查局部缓冲区溢出——检查数组边界与字符串操作。该消息需要启用 CONFIG_COMPILER_STACK_CHECK_MODE_*。若关闭（robocar-unified 默认），同样的溢出会报告为双重异常并伴随损坏的 backtrace——见上表。可用主机测试固定修复：在 -fsanitize=address 下原样编译该文件（模板为 packages/robocar/unified/test/test_pca9685_multi.c）。
3. 内存调试
检查堆使用：
ESP_LOGI(TAG, "Free heap: %lu", esp_get_free_heap_size());
ESP_LOGI(TAG, "Min free heap: %lu", esp_get_minimum_free_heap_size());
常见内存问题：内存泄漏（malloc() 后缺少 free()）；双重释放（同一内存释放两次）；释放后使用（访问已释放内存）。
4. 通信调试
I2C 问题：E (1234) i2c: i2c_master_cmd_begin(xxx): I2C_NUM error。检查清单：核对 I2C 地址（7 位与 8 位格式）；检查 SDA/SCL GPIO 引脚；确保存在上拉电阻（典型 4.7K）；核对时钟频率兼容性。
串口/UART 问题：波特率不匹配；TX/RX 接反；缺少接地连接。
双控制器同步（I2C）：检查两个控制器都在运行；核对 I2C 地址匹配；检查 GPIO 引脚配置。
5. 用于调试的构建命令
# Clean build to eliminate stale objects
just <project>::clean && just <project>::build
# Start serial monitor
just <project>::monitor PORT=/dev/cu.usbserial-0001
6. 有用的 ESP-IDF 配置选项
在 sdkconfig.defaults 中或通过 menuconfig 启用：
- CONFIG_ESP_SYSTEM_PANIC_PRINT_REBOOT — 重启前打印 panic 信息
- CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK — 更早检测栈溢出
- CONFIG_HEAP_POISONING_COMPREHENSIVE — 检测堆损坏
常见修复对照
| 症状 | 修复 |
|---|---|
| 栈溢出 | 在 xTaskCreate 中增大任务栈大小 |
| 内存泄漏 | 检查缺失的 free() 调用 |
| I2C 超时 | 核对连接、上拉电阻、地址 |
| 启动时崩溃 | 将 CONFIG_ESP_MAIN_TASK_STACK_SIZE 增大到 8192+ |
适用场景与限制
适用于 ESP-IDF 项目的 ESP32 固件调试，覆盖编译、运行时 panic、内存与通信四类问题。技能依赖 just 构建命令与串口监视器，具体项目名与端口需按实际情况替换。资料未提供该技能的安装方式、收费信息或平台支持范围。