AGENTS

约 900 字大约 3 分钟

2026-08-03

AGENTS.md - ESP32 MicroPython 智能语音交互终端

项目定位

基于 ESP32 V5.5.1 + MicroPython V1.27 的智能语音交互终端。

实时语音对话（类小智AI）
服务器主动推送语音播报
远程消息接收与播发能力

技术架构

C 层：MQTT 长连接、SM2 签名验证、OTA 升级、LOG 标准输出（作为固件内置模块）
Python 层：语音交互逻辑、播报队列管理、应用状态机
应用管理：ebsx‑micro 管理 Python 应用层
守护进程：daemon 统一管理注册函数
通信模式：双向（终端主动发起 + 服务器主动推送）
C层守护：C层开启mqtt遗嘱，python层publish对应的online，服务器会根据情况自行判断是否需要下发sys消息reboot设备

目录上下文

~/ebs-fw/esp32s3/ ├── esp32-micropython/ # MicroPython V1.27 官方 Port + C 层固件模块 (ports/esp32) ├── ebsx-micro/ # Python 应用层代码 (业务逻辑/状态机/队列) └── esp32-daemon/ # C/Python 守护进程 (服务注册/资源监控/OTA触发)

📜 命名与工程规范 (AI 强制遵循)

核心原则：严格避开 C 标准库、FreeRTOS、ESP-IDF、MicroPython 内置模块及关键字的通用命名。凡涉及业务逻辑、自定义工具、配置、状态、通信等通用性概念，必须强制加入 ebsx_（应用/业务层）或 esp32_（硬件/底层/ESP-IDF适配）前缀。CMakeLists 构建文件同步遵循此规范。

1. C 层命名规范

类型	规则	正确示例	禁止示例 (通用名)
头/源文件	`ebsx_.c/.h` 或 `esp32_.c/.h`	`ebsx_mqtt.c`, `esp32_sm2.h`, `ebsx_log.c`	`mqtt.c`, `log.h`, `config.h`, `utils.c`
函数	`前缀_模块_动作()` 小写蛇形	`ebsx_mqtt_connect()`, `esp32_i2s_init()`	`init()`, `start()`, `parse_msg()`
宏/常量	`EBSX_` / `ESP32_` 全大写	`EBSX_MQTT_KEEPALIVE_S`, `ESP32_SM2_KEY_LEN`	`TIMEOUT`, `MAX_RETRY`, `KEY_SIZE`
结构体/枚举	`ebsx_xxx_ctx_t`, `ebsx_state_e`	`typedef struct ebsx_queue_node_t { ... } ebsx_queue_node_t;`	`struct config`, `enum state`, `msg_t`
组件目录	统一带前缀，与 CMake 注册名一致	`components/ebsx_mqtt/`	`components/mqtt/`

2. Python 层规范 (MicroPython V1.27)

类型	规则	正确示例	禁止示例 (通用名)
模块文件	`ebsx_.py` (业务) / `esp32_.py` (驱动封装)	`ebsx_voice.py`, `ebsx_queue.py`, `esp32_i2s_drv.py`	`main.py`, `config.py`, `mqtt.py`, `state.py`
类	`EBSX_` / `ESP32_` + PascalCase	`class EBSXVoiceHandler:`	`class Voice:`, `class StateMachine:`
函数/方法	导出函数必须带前缀	`def ebsx_handle_audio(buf):`	`def process():`, `def run():`
全局常量	`EBSX_` 全大写	`EBSX_SAMPLE_RATE = 16000`	`SAMPLE_RATE`, `CONFIG`

3. CMakeLists 构建规范

对象	规则	正确示例	禁止示例
变量	`EBSX_` / `ESP32_` 前缀，禁用通用缩写	`set(EBSX_APP_SRC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/src")`	`set(SRC ...)`, `set(INC ...)`, `set(LIBS ...)`
Target	明确前缀+功能，禁用 `app`/`lib`/`core`	`add_library(ebsx_voice_core STATIC src/ebsx_voice.c)`	`add_library(voice_lib ...)`
组件注册	`idf_component_register` 必须对齐文件前缀	`idf_component_register(SRCS "ebsx_mqtt.c" INCLUDE_DIRS "include")`	`idf_component_register(SRCS "*.c" INCLUDE_DIRS ".")`
路径引用	使用相对路径或带前缀的变量，禁用绝对路径	`target_include_directories(ebsx_core PUBLIC ${EBSX_INC_DIR})`	`target_include_directories(... PRIVATE /home/zhang/...)`

4. 冲突规避清单 (生成代码前必查)

AI 生成任何标识符前，若命中以下通用词，必须自动追加 ebsx_ 或 esp32_ 前缀：

C 层通用词：log, config, mqtt, ota, state, queue, task, timer, socket, parse, utils, common, main, app, init
Python 层通用词：sys, os, json, time, network, mqtt, config, state, main, app, run, thread, utils
系统 API：ESP_OK, xTaskCreate, pdTRUE, gpio_set_level 等原生接口可直调，但封装层/包装类/中间件必须加前缀。

🛠 构建与测试命令

固件构建（仅当修改 C 层时）

允许修改的目录：

esp32-micropython/ports/esp32/boards/（板级配置EBSX_ESP32S3_N16R8）
esp32-micropython/ports/esp32/components/（组件）
esp32-micropython/ports/esp32/（mian.c、modesp.c）
构建固件：
- make BOARD=EBSX_ESP32S3_N16R8 USER_C_MODULES=~/ebs-fw/esp32s3/esp32-daemon/ BOARD_VARIANT=SPIRAM_OCT # 编译
- make BOARD=EBSX_ESP32S3_N16R8 USER_C_MODULES=~/ebs-fw/esp32s3/esp32-daemon/ BOARD_VARIANT=SPIRAM_OCT erase deploy # 擦除并烧录
- make BOARD=EBSX_ESP32S3_N16R8 USER_C_MODULES=~/ebs-fw/esp32s3/esp32-daemon/ BOARD_VARIANT=SPIRAM_OCT deploy # 烧录

输出限定

涉及程序输出，需要添加必要的备注
test