小智 AI 官方口径为什么对不上
小智 AI（78/xiaozhi-esp32）迭代频繁，官方文档、发布包与早期问答写作时间不同，同一个问题常并存多个口径。本页按 2026-11-12 抓取的官方 main 分支与 v2.5.2 发布包，把官方自己存在的四组矛盾列出来，说明各自来源与核对办法。每组冲突都不设唯一正确答案，引用任何数字前先确认口径。
冲突一：板卡与固件变体数量
| 来源 | 原文口径 | 数字或版本 |
|---|---|---|
| 自定义开发板指南（docs/custom-board_zh.md）开头 | 「支持 70 多种 ESP32 系列开发板」 | 70 多种 |
| README 硬件章节 | 「支持 138 个板卡目录、171 个固件发布变体」 | 138 个板卡目录、171 个固件发布变体 |
| v2.5.2 release 自述 | 「188 firmware variants for 154 board directories, built with ESP-IDF 6.1.0」 | 188、154、6.1.0 |
| 发布包内的 release-manifest.json | board_count 为 154、firmware_count 为 188、variants 列表共 188 条 | 154、188、188 条 |
三个数字分属不同时间点与统计口径（指南文本、README 矩阵、发布清单），官方没有统一改写，只能带口径引用。同一份指南内部也是新旧混杂：开头的「70 多种」是旧数字，而其中的 OTA 频道唯一性警告（IO 配置与原有开发板不同时切勿直接覆盖原板配置，必须新建板类型或在 config.json 的 builds 里用不同 name 和 sdkconfig 宏区分，否则自定义固件会被官方标准固件 OTA 覆盖）仍是必须遵守的现行规则。
冲突二：ESP-IDF 版本要求
| 来源 | 原文口径 | 数字或版本 |
|---|---|---|
| README 开发环境章节 | 要求 ESP-IDF 最低 v6.0.1、推荐 release/v6.1 分支、不再支持 5.x，并提醒不要使用 v6.1 发布标签（ESP32-C3 上有 Wi-Fi 初始化失败报告，见官方 issue #2344） | v6.0.1、release/v6.1、5.x、v6.1 |
| v2.5.2 发布包的 release-manifest.json | 写明 idf_version 为 6.1.0 | 6.1.0 |
| 官方早期问答（Q5） | 「小智AI开源项目是基于 ESP-IDF 5.3 版本使用C/C++语言开发的AI应用」 | 5.3 |
| 第三方教程 | 流传 v6.0.2、v5.5、v5.1+ 等说法 | v6.0.2、v5.5、v5.1+ |
早期问答是 v0.x 时代的口径，编译环境以 main 分支 README 为准；切换 SDK 后需要在 ESP-IDF 目录执行 git submodule update --init --recursive，重新加载 export.sh，并在本项目执行 idf.py fullclean 后重新编译。
冲突三：默认唤醒词
| 来源 | 原文口径 | 数字或版本 |
|---|---|---|
| 官方问答 Q9 | 「唤醒词默认是 你好小智，请确认是否正确（不是 小智你好 或 小智小智，也不是配置的角色名字）」 | 你好小智 |
| 官方 FAQ 页面 | 「默认唤醒词为'小智小智'」 | 小智小智 |
两个官方来源直接矛盾，任何页面写死其中一个都可能误导读者。可行做法是以设备实机首次播报或屏幕提示为准：烧录配网后唤醒一次，按播报内容确认当前固件的唤醒词。
冲突四：芯片平台口径
| 来源 | 原文口径 | 数字或版本 |
|---|---|---|
| 官方 FAQ「小智 AI 支持哪些硬件」一条 | 只列 ESP32、ESP32-S3、ESP32-C3，并写社区在拓展思澈、全志、移远等平台、推荐使用 ESP32-S3 获得最佳体验 | ESP32、ESP32-S3、ESP32-C3 |
| README 已实现功能列表 | 写支持 ESP32、ESP32-C3、ESP32-C5、ESP32-C6、ESP32-S3、ESP32-P4，近期更新还提到 ESP32-S31 变体需要 IDF 6.1 或以上版本、ESP32-P4 Rev1 和 Rev3 在 IDF 6 加 ESP-SR 2.4.7 下均支持 | IDF 6.1、IDF 6、ESP-SR 2.4.7 |
FAQ 为旧口径，芯片支持范围以 main 分支 README 与发布包为准。
怎么自己核对
- 打开 GitHub 上 78/xiaozhi-esp32 仓库 main 分支的 README，查看「已实现功能」「开发环境」「近期更新」章节的当前写法。main 分支 2026-11-12 仍在推送，这里反映主干当前状态。
- 打开最新 release（v2.5.2，发布于 2026-10-11）附件中的 release-manifest.json，核对 version、tag、source_sha、idf_version、board_count、firmware_count 字段。该 release 共 190 个 assets，另含 SHA256SUMS 可做文件校验；source_sha（49b4380b3faa0ceadd28a3e78aaf0f311c46c57e）标明构建所用 commit，可回到对应源码核对。
- 注意两者的时间差：release 发布于 2026-10-11，main 分支 2026-11-12 仍在推送，「最新发布版」与「主干当前状态」对应两个不同快照，引用前先确认核对的是哪一个。
- 默认唤醒词以设备实机首次播报或屏幕提示为准，不以任何文档文本为准。
官方早期教程中的接线、烧录、配网步骤仍可参考操作，但凡出现具体版本号（如 v0.9.7、v1.5.5、ESP-IDF 5.3）都按早期固件口径对待，当前固件以 v2.5.2 发布包为准。
第三方内容负面清单
以下写法常见于第三方教程，在官方 README、开发者文档与发布包中查不到出处，或与官方口径直接冲突：
- CONFIG_MCP_SERVER_URL、CONFIG_WAKE_WORD_CUSTOM、CONFIG_AUDIO_ENABLED 等配置项，以及在 sdkconfig.defaults 里写 Wi-Fi SSID 和密码的改法；
- 用 idf.py add-dependency "espressif/esp-sr" 添加唤醒词依赖的步骤；
- 「ESP-IDF v5.1+ / v5.5 可用」「v6.0.2 稳定版」，与 README 的最低 v6.0.1、推荐 release/v6.1 分支、不再支持 5.x 冲突；
- 「训练专属唤醒词模型，准确率 95%」「完全离线使用」，与项目依赖云端 ASR/LLM/TTS 的架构不符。
遇到与上述清单相同或相近的说法，回到官方仓库与发布包逐字核对后再采信；对版本、数量、唤醒词这类会随时间漂移的字段，始终以「main 分支当前状态」或「某个具体 release 的 manifest」加口径引用，第三方转述不能替代原始来源。