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.2IDF 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/application.*主事件循环、协议生命周期与高层行为编排main/device_state_machine.*合法的运行时状态迁移main/boards/common/板卡抽象接口与可复用的硬件/网络辅助实现main/boards/**/各板卡的引脚定义、初始化逻辑与构建变体main/audio/音频编解码器、音频任务、引擎、唤醒词与队列main/protocols/传输无关的 API 抽象以及 WebSocket、MQTT/UDP 实现main/display/、main/led/可复用的 UI 与灯效实现main/mcp_server.*设备侧公共 MCP 工具与分发main/Kconfig.projbuild板卡与功能特性配置menuconfig 入口main/CMakeLists.txt源文件、板卡目录、语言、字体与资源选择scripts/build.py规范的板卡/变体构建入口其中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_128X32y ] }, { name: bread-compact-wifi-128x64, sdkconfig_append: [ CONFIG_OLED_SSD1306_128X64y ] } ] }字段语义type顶层上报的板卡类型OTA 兼容性关键标识只允许小写字母、数字、.与-脚本会对全仓库做重复类型、重复名称、重复 (type, name) 身份的三重查重校验。target目标芯片如esp32s3。builds一个板卡下的一个或多个构建变体每个变体用name区分name同样是 OTA 上报标识并通过sdkconfig_append追加该变体专属的 Kconfig 配置——上例即通过追加CONFIG_OLED_SSD1306_128X32y与CONFIG_OLED_SSD1306_128X64y区分两种 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_styledefault / wechat / emote与multiline_chat仅当板卡源码引用了LcdDisplay时出现emote动画风格只对白名单板卡开放aec_modeoff / device仅当板卡出现在CONFIG_USE_DEVICE_AEC的依赖列表中wifi_provisioninghotspot / blufiWi-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_WORDWakenet 模型、无 AFE支持 C3/C5/C6 及带 PSRAM 的 ESP32、USE_AFE_WAKE_WORD带 AEC需 S3/P4/S31 PSRAM、USE_CUSTOM_WAKE_WORDMultinet 自定义唤醒词。自定义唤醒词相关参数包括CUSTOM_WAKE_WORD默认xiao tu dou中文用拼音空格分隔、CUSTOM_WAKE_WORD_DISPLAY默认小土豆唤醒后上报服务器的问候语与CUSTOM_WAKE_WORD_THRESHOLD1–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.cccustom_wake_word.cc其余芯片编译lite_audio_engine.ccesp_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/vversion_name.zip--json以 JSON 输出列表结果便于 CI/Agent 消费--select-changed从 stdin 读取变更文件列表输出受影响的变体 JSON供 CI 按 diff 精准挑选构建目标——scripts/tests/test_build.py 中对这套逻辑有专门的测试覆盖。构建脚本还会在XIAOZHI_BUILD_STAGES1环境下输出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.mdSDK 兼容性含 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.mdCI 矩阵.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 xiaozhi-esp32 固件工程开发指南：源码架构、板卡构建链路与开发规范
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.2IDF 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/application.*主事件循环、协议生命周期与高层行为编排main/device_state_machine.*合法的运行时状态迁移main/boards/common/板卡抽象接口与可复用的硬件/网络辅助实现main/boards/**/各板卡的引脚定义、初始化逻辑与构建变体main/audio/音频编解码器、音频任务、引擎、唤醒词与队列main/protocols/传输无关的 API 抽象以及 WebSocket、MQTT/UDP 实现main/display/、main/led/可复用的 UI 与灯效实现main/mcp_server.*设备侧公共 MCP 工具与分发main/Kconfig.projbuild板卡与功能特性配置menuconfig 入口main/CMakeLists.txt源文件、板卡目录、语言、字体与资源选择scripts/build.py规范的板卡/变体构建入口其中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_128X32y ] }, { name: bread-compact-wifi-128x64, sdkconfig_append: [ CONFIG_OLED_SSD1306_128X64y ] } ] }字段语义type顶层上报的板卡类型OTA 兼容性关键标识只允许小写字母、数字、.与-脚本会对全仓库做重复类型、重复名称、重复 (type, name) 身份的三重查重校验。target目标芯片如esp32s3。builds一个板卡下的一个或多个构建变体每个变体用name区分name同样是 OTA 上报标识并通过sdkconfig_append追加该变体专属的 Kconfig 配置——上例即通过追加CONFIG_OLED_SSD1306_128X32y与CONFIG_OLED_SSD1306_128X64y区分两种 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_styledefault / wechat / emote与multiline_chat仅当板卡源码引用了LcdDisplay时出现emote动画风格只对白名单板卡开放aec_modeoff / device仅当板卡出现在CONFIG_USE_DEVICE_AEC的依赖列表中wifi_provisioninghotspot / blufiWi-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_WORDWakenet 模型、无 AFE支持 C3/C5/C6 及带 PSRAM 的 ESP32、USE_AFE_WAKE_WORD带 AEC需 S3/P4/S31 PSRAM、USE_CUSTOM_WAKE_WORDMultinet 自定义唤醒词。自定义唤醒词相关参数包括CUSTOM_WAKE_WORD默认xiao tu dou中文用拼音空格分隔、CUSTOM_WAKE_WORD_DISPLAY默认小土豆唤醒后上报服务器的问候语与CUSTOM_WAKE_WORD_THRESHOLD1–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.cccustom_wake_word.cc其余芯片编译lite_audio_engine.ccesp_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/vversion_name.zip--json以 JSON 输出列表结果便于 CI/Agent 消费--select-changed从 stdin 读取变更文件列表输出受影响的变体 JSON供 CI 按 diff 精准挑选构建目标——scripts/tests/test_build.py 中对这套逻辑有专门的测试覆盖。构建脚本还会在XIAOZHI_BUILD_STAGES1环境下输出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.mdSDK 兼容性含 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.mdCI 矩阵.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考