小智 AI 源码编译与 ESP-IDF 版本边界
官方 README 的第一句忠告：新手第一次操作建议先不要搭建开发环境，直接使用免开发环境烧录的固件。官方 Q&A 也写明「普通用户不需要安装配置IDF开发环境，开发者或者学习编程用户才需要配置」。所以动手前先确认自己确实要改代码——改板级配置、加功能、做自定义板——不满足这些场景的用户用现成固件即可。
版本边界按 2026-11-12 抓取的官方 main 分支口径，当前要求与旧版口径对照如下：
| 项 | 当前口径 | 旧版口径 |
|---|---|---|
| ESP-IDF 最低版本 | 项目要求 ESP-IDF 最低 v6.0.1 | — |
| 推荐分支 | 推荐使用 release/v6.1 分支 | — |
| ESP-IDF 5.x | 不再支持 ESP-IDF 5.x | 官方早期 Q&A 写的「小智AI开源项目是基于 ESP-IDF 5.3 版本使用C/C++语言开发的AI应用」属于旧版口径，不得当作当前要求 |
| v6.1 发布标签 | 避免使用，该标签在 ESP32-C3 上存在 Wi-Fi 初始化失败的报告（issue #2344） | — |
官方还说明 Linux 比 Windows 更好，编译速度快，也免去驱动问题的困扰，条件允许优先在 Linux 下编译。本项目使用 Google C++ 代码风格，提交代码时请确保符合规范。另外官方板指南开头写「小智AI支持70多种ESP32系列开发板」，这也是文档旧口径，仅代表该文档写就时点的板数，不代表当前数量。
- 确认必要性：只想让设备跑起来的用户直接用现成固件，本页到此为止。预期结果：能写出要修改的代码位置或功能点；写不出来就说明还不需要搭环境。
- 安装编辑器与插件：使用 Cursor 或 VSCode，安装 ESP-IDF 插件，SDK 检出 release/v6.1 分支（满足最低 v6.0.1；不用 5.x；不用 v6.1 发布标签）。预期结果：编辑器内能打开 ESP-IDF 终端并加载本项目，SDK 分支与上述口径一致。
- 切换 SDK 版本后的固定动作：在 ESP-IDF 目录执行
git submodule update --init --recursive，重新加载其export.sh，再回到本项目执行idf.py fullclean后重新编译。预期结果：子模块拉取完成且无报错，fullclean 清空旧构建产物，随后一次编译从头进行。 - 选择目标芯片（首次配置或更换芯片时）：按板型执行
idf.py set-target esp32s3、idf.py set-target esp32c3或idf.py set-target esp32。预期结果：命令执行完毕，项目按所选芯片重新生成配置。 - 选择板卡：执行
idf.py menuconfig，在菜单中导航到 Xiaozhi Assistant -> Board Type，选中你的开发板并保存退出。预期结果：配置保存成功，后续编译按该板型进行。 - 编译：执行
idf.py build。预期结果：编译完成，产出可烧录的固件文件。 - 烧录并观察日志：执行
idf.py flash monitor。预期结果：固件写入开发板，串口监视器持续输出启动日志，可据此判断板卡初始化是否正常，确认后退出监视器。
官方板指南的四条补充边界：
- 若开发板目录下有 config.json，可用
python scripts/build.py my-custom-board自动完成配置和编译；脚本读取 config.json 中的 target，仅当已有 build 目录的目标芯片不同时才执行清理，因此切换目标芯片重建后，不要假设 build/ 目录里还是上一个目标的产物。语言与唤醒词可用python scripts/build.py --list-languages与python scripts/build.py --list-wake-words查询（均支持 --json 输出）。 - 若编译的是自定义板型，当 IO 配置与原有开发板不同时，切勿直接覆盖原有开发板的配置编译固件，必须新建板类型或通过 config.json 的 builds 配置不同的 name 与 sdkconfig 宏，否则 OTA 升级时自定义固件会被原有板的标准固件覆盖，设备无法正常工作。
- managed_components/ 变更时先执行
idf.py reconfigure再编译；唤醒词列表从当前已解析的 ESP-SR 组件读取，尚未生成 managed_components/ 时同样要先运行一次 reconfigure。 - Windows 编译若因编译器命令超过 32,767 字符上限出现 Ninja CreateProcess 错误，在同一个工程目录、同一个 ESP-IDF 终端中执行
idf.py -D CMAKE_NINJA_FORCE_RESPONSE_FILE=ON reconfigure，再执行idf.py build；执行idf.py fullclean或清空 CMake 缓存后，需要重新执行上述 reconfigure 命令。