企业官网建设流程全解析

xiaozhi-esp32 固件工程开发指南：源码架构、板卡构建链路与开发规范

【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32

本指南以仓库根目录的 AGENTS.md 为核心骨架，系统梳理 xiaozhi-esp32 这套基于 ESP-IDF 的 C/C++ 语音助手固件的工程组织方式。你将了解固件模块如何分层、板卡选择如何从config.json一路贯通到DECLARE_BOARD宏、构建脚本build.py的完整命令用法，以及维护者规定的开发红线与验证要求，从而具备独立新增板卡、定制变体与安全提交代码的实战能力。

项目定位与开发环境前提

xiaozhi-esp32 是一个支持多种芯片（ESP32、ESP32-C3/C5/C6、ESP32-S3、ESP32-P4、ESP32-S31）、多类开发板、显示屏、音频器件与网络传输方式的语音助手固件。其工程形态的关键特征是：一次构建恰好只选择一个板卡实现，所有硬件差异通过"板卡目录 + Kconfig 配置"在编译期收敛，核心业务代码不感知具体硬件。

在动手前，需要明确两条环境约束：

• 优先使用 ESP-IDF v6.0.2；IDF 5.5.x 仅保留给文档明确标注的历史板卡。构建脚本scripts/build.py内部也将默认 IDF 版本设为(6, 0, 2)（见 scripts/build.py），且支持按idf_version表达式对构建变体做版本门控（如<6.0、>=6.0.1）。
• 每个构建必须通过DECLARE_BOARD(...)恰好导出一个板卡工厂。该宏定义在 main/boards/common/board.h，其本质是生成一个void* create_board()工厂函数，返回对应板卡类实例，供应用层统一创建。

固件源码架构分层

仓库的核心代码集中在main/目录，模块职责划分清晰，遵循"越具体的实现越靠近底层、越通用的逻辑越靠近核心"的原则：

其中main/boards/common/是架构上的关键约束点：wifi_board.cc、ml307_board.cc、nt26_board.cc、dual_network_board.cc、ethernet_board.cc、rndis_board.cc等分别抽象了不同的网络承载方式，adc_battery_monitor.cc、axp2101.cc、backlight.cc、button.cc、knob.cc、sy6970.cc等则是通用外设实现。新增板卡时，应优先阅读距离自己最近的既有实现并继承最贴近的基类，不要把板卡特有行为写进核心模块——核心代码只允许依赖Board接口，绝不能依赖某个具体板卡类或板卡目录下的config.h。

板卡与配置：一条耦合的构建链路

AGENTS.md 明确指出，板卡选择是一条必须整体维护的耦合链路：

config.json -> scripts/build.py -> main/Kconfig.projbuild -> main/CMakeLists.txt -> board source 与 config.h

第一环：config.json 声明板卡身份与变体

每个板卡目录下都有一个config.json，它声明了 OTA 兼容性敏感的板卡身份。以 main/boards/bread-compact-wifi/config.json 为例：

{ "type": "bread-compact-wifi", "target": "esp32s3", "builds": [ { "name": "bread-compact-wifi", "sdkconfig_append": [ "CONFIG_OLED_SSD1306_128X32=y" ] }, { "name": "bread-compact-wifi-128x64", "sdkconfig_append": [ "CONFIG_OLED_SSD1306_128X64=y" ] } ] }

字段语义：

• type：顶层上报的板卡类型（OTA 兼容性关键标识），只允许小写字母、数字、.与-；脚本会对全仓库做重复类型、重复名称、重复 (type, name) 身份的三重查重校验。
• target：目标芯片，如esp32s3。
• builds：一个板卡下的一个或多个构建变体，每个变体用name区分（name同样是 OTA 上报标识），并通过sdkconfig_append追加该变体专属的 Kconfig 配置——上例即通过追加CONFIG_OLED_SSD1306_128X32=y与CONFIG_OLED_SSD1306_128X64=y区分两种 OLED 分辨率。
• 位于厂商子目录（如waveshare/...）的板卡必须在config.json中声明与目录一致的manufacturer，产物名会自动拼接厂商前缀。

第二环：build.py 解析并校验配置

scripts/build.py会遍历main/boards/下所有config.json，完成身份校验、解析 Kconfig 符号（如通过解析main/CMakeLists.txt的if(CONFIG_BOARD_TYPE_*)分支反查BOARD_DIR），并为每个变体按板卡能力动态暴露构建选项。可暴露的语义化选项包括：

• display_model：仅当板卡 Kconfig 关联了DISPLAY_OLED_TYPE/DISPLAY_LCD_TYPE选择时才出现；
• display_style（default / wechat / emote）与multiline_chat：仅当板卡源码引用了LcdDisplay时出现，emote动画风格只对白名单板卡开放；
• aec_mode（off / device）：仅当板卡出现在CONFIG_USE_DEVICE_AEC的依赖列表中；
• wifi_provisioning（hotspot / blufi）：Wi-Fi 板卡可用，但 ESP32-P4 因网络来自协处理芯片而被显式排除；
• camera_hmirror/camera_vflip：面向带摄像头且非运行时动态翻转的板卡。

第三环：Kconfig.projbuild 提供菜单化配置

main/Kconfig.projbuild 是工程特性配置的总入口，包含大量与板卡强耦合的配置项：

• BOARD_TYPE选择：按芯片目标给出默认板卡（如 ESP32-S3 默认BREAD_COMPACT_WIFI、ESP32-C6 默认WAVESHARE_ESP32_C6_TOUCH_AMOLED_2_06），每个条目通过depends on IDF_TARGET_*限定芯片。
• 唤醒词实现类型：WAKE_WORD_DISABLED、USE_ESP_WAKE_WORD（Wakenet 模型、无 AFE，支持 C3/C5/C6 及带 PSRAM 的 ESP32）、USE_AFE_WAKE_WORD（带 AEC，需 S3/P4/S31 + PSRAM）、USE_CUSTOM_WAKE_WORD（Multinet 自定义唤醒词）。自定义唤醒词相关参数包括CUSTOM_WAKE_WORD（默认xiao tu dou，中文用拼音空格分隔）、CUSTOM_WAKE_WORD_DISPLAY（默认小土豆，唤醒后上报服务器的问候语）与CUSTOM_WAKE_WORD_THRESHOLD（1–99，默认 20，越小越灵敏）。
• 音频处理：USE_AUDIO_PROCESSOR（共享 AFE 上行链路，含 AEC 与 VAD，需 S3/P4/S31 + PSRAM）、USE_DEVICE_AEC（设备侧 AEC，需扬声器参考通路与物理隔音）、USE_SERVER_AEC（服务器侧 AEC，标注为不稳定）。
• 配网方式：USE_HOTSPOT_WIFI_PROVISIONING（热点配网，默认开启）与USE_ESP_BLUFI_WIFI_PROVISIONING（基于 ESP-IDF 6 PSA Crypto 的 BluFi，要求配网客户端支持 ffdhe3072、SHA-256 与 AES-CTR）。
• 显示风格：DISPLAY_STYLE下的默认消息风格 / 微信消息风格 / Emote 动画风格，以及默认消息风格下的多行聊天消息开关USE_MULTILINE_CHAT_MESSAGE。
• 资源与语言：Flash Assets 四种模式（不烧录/默认/自定义/Emote）、默认语言选择（覆盖数十种语言）、OTA_URL默认 OTA 地址。

第四环：CMakeLists.txt 落地板卡目录与身份

main/CMakeLists.txt 通过一长串if(CONFIG_BOARD_TYPE_*)分支把 Kconfig 符号映射为BOARD_DIR（板卡源目录），再file(GLOB ...)收集该目录下的.cc/.c源文件参与编译。同一份文件还承担了：

• 按芯片家族选择音频引擎：S3/P4/S31 编译afe_audio_engine.cc+custom_wake_word.cc，其余芯片编译lite_audio_engine.cc+esp_wake_word.cc；
• 从config.json读取type/manufacturer作为上报身份，并通过target_compile_definitions注入BOARD_TYPE、BOARD_NAME、BOARD_MANUFACTURER与内置字体信息；
• 根据CONFIG_LANGUAGE_*选择语言目录、收集该语言的.ogg音频（缺失文件自动回退到en-US），并调用scripts/gen_lang.py生成lang_config.h；
• 按FLASH_DEFAULT_ASSETS/FLASH_CUSTOM_ASSETS/FLASH_EXPRESSION_ASSETS三种模式生成并烧写 assets 分区。

需要特别注意的是：构建时scripts/build.py会把config.json的sdkconfig_append合并成build/xiaozhi-build.sdkconfig.defaults片段，再以SDKCONFIG_DEFAULTS传入idf.py reconfigure，从而改写本地sdkconfig与构建状态。因此不要假设构建目录仍代表上一次的目标，切换板卡或目标后必须重新配置。

开发硬性规则

AGENTS.md 规定了一系列不可逾越的工程红线，违反它们会破坏 OTA 兼容性或引发维护灾难：

• 保持补丁聚焦：保留无关的工作区改动，不扩大改动面。
• 单板卡工厂：一次构建必须恰好导出一个DECLARE_BOARD(...)。
• 不得改既有板卡的引脚去适配不同硬件：应新增唯一命名的板卡或发布变体，因为板卡身份直接影响 OTA 兼容性。
• 核心代码只依赖Board接口：绝不依赖具体板卡类或板卡config.h。
• 外设可选化：摄像头、背光、显示、LED、电池等能力一律视为可选，不能假设存在。
• 状态迁移收口：运行时状态必须通过Application::SetDeviceState()与状态机变更。
• 回调线程安全：回调可能在主任务之外执行，应用变更需通过Application::Schedule()或事件位调度。
• 实时性约束：不得阻塞主事件循环与音频任务，音频路径避免无界队列与反复的大块分配。
• 协议契约统一：共享消息语义保持在Protocol中，改动契约时必须同时验证两种传输（WebSocket 与 MQTT/UDP）。
• 输入与资源所有权：校验网络输入，维护cJSON所有权；NVS 键是持久化 API，变更需迁移。
• 目标特性门控：用 Kconfig/组件规则守护目标特有特性，不能假定所有目标都有 PSRAM 或 S3/P4 资源。
• 禁止手工编辑生成物：build/、releases/、managed_components/、components/、sdkconfig*、main/assets/lang_config.h及生成的 mmap 头文件均不可手工修改。
• 格式化范围：只对触碰过的 C/C++ 文件使用仓库.clang-format格式化，避免无关的大范围重排。

常用命令

开发前先激活目标 ESP-IDF 环境：

source /path/to/esp-idf/export.sh idf.py --version

随后即可使用规范的构建入口scripts/build.py：

# 发现确切的板卡与变体名称 python3 scripts/build.py --list-boards # 规范变体构建 python3 scripts/build.py <board-directory> --name <variant-name> # 主机侧构建测试 python3 -m unittest discover -s scripts/tests -v # 格式化/检查触碰过的文件 clang-format -i <files> clang-format --dry-run -Werror <files>

结合 scripts/build.py 的 CLI 定义，构建脚本还支持以下高频参数：

• --list-languages：列出--language可接受的全部语言（如zh-CN、en-US，自动做大小写与下划线归一化），脚本会交叉校验main/CMakeLists.txt的映射、main/Kconfig.projbuild的符号与main/assets/locales/目录三者一致；
• --list-wake-words：列出当前 ESP-SR 组件提供的 WakeNet 模型表（需先idf.py reconfigure解析 managed components），特殊值有nihaoxiaozhi与disabled；
• --wake-word <MODEL>：构建时选择唤醒词模型，例如wn9_jarvis_tts、nihaoxiaozhi或disabled；目标芯片与模型家族不匹配（如 C3 上使用非wn9s_模型）会直接报错；
• --build-options-json <JSON>：传入语义化构建选项，接受的键由--list-boards --json按变体上报，非法键或非法值会被拒绝；
• --language <LOCALE>：覆盖固件显示语言；
• --zip：同时把build/merged-binary.bin打包为releases/v<version>_<name>.zip；
• --json：以 JSON 输出列表结果（便于 CI/Agent 消费）；
• --select-changed：从 stdin 读取变更文件列表，输出受影响的变体 JSON，供 CI 按 diff 精准挑选构建目标——scripts/tests/test_build.py 中对这套逻辑有专门的测试覆盖。

构建脚本还会在XIAOZHI_BUILD_STAGES=1环境下输出XIAOZHI_STAGE <stage>机器可读的阶段标记（如dependencies_resolving、compiling、packaging），供云端构建流水线跟踪进度。

验证与测试要求

提交变更前，必须按改动范围选择对应的验证策略：

• 仅板卡改动：构建受影响的变体，并对改动的硬件做冒烟测试。
• 核心/公共板卡/音频/协议/显示/依赖/Kconfig/CMake 改动：运行主机侧测试（python3 -m unittest discover -s scripts/tests -v），并构建有代表性的受影响芯片/网络路径。
• 协议改动：共享行为变化时，必须同时验证 WebSocket 与 MQTT/UDP 两条路径。
• 音频改动：验证采集、播放、唤醒/VAD、打断、重连及适用的 AEC 模式。
• UI/资源改动：验证适用的无显示/OLED/LVGL 路径与分区大小。
• 报告中必须说明已测试什么、还缺什么真实硬件验证——"构建成功"不等于硬件验证通过。

新增板卡或变体时，需要更新链路中的每一环：唯一的板卡身份、正确的芯片目标、flash/分区设置、恰好一个DECLARE_BOARD，以及板卡文档，具体流程以 docs/custom-board.md 为准。

权威文档索引

AGENTS.md 明确要求把详细或高频变化的信息放在专项文档而非 AGENTS.md 中，读者可按需深入：

• 项目概览与 SDK 策略：README.md
• SDK 兼容性（含 ESP-IDF 6 迁移细节）：docs/esp-idf-6-migration.md
• 板卡接入指南：docs/custom-board.md
• 音频设计：main/audio/README.md
• 代码风格：docs/code_style.md
• 协议：docs/websocket.md、docs/mqtt-udp.md、docs/mcp-protocol.md
• CI 矩阵：.github/workflows/build.yml

这套"板卡目录驱动 + Kconfig 门控 + 单工厂导出"的架构，使 xiaozhi-esp32 能在大量异质硬件上复用同一套核心代码。无论是为个人硬件接入新板卡，还是为既有板卡新增变体，只要沿config.json → build.py → Kconfig → CMakeLists → board source这条链路逐环补齐，并遵守上述开发红线，就能安全地融入这套固件工程体系。

【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32