mirror of
https://github.com/78/xiaozhi-esp32.git
synced 2026-07-21 02:05:52 +00:00
3dea6e7f84
* feat: migrate firmware to xiaozhi-fonts 2.0.0 * fix: restart scrolling subtitles on text change * docs: add AGENTS.md for project overview, architecture, rules, and commands - Introduced AGENTS.md to document the XiaoZhi voice-assistant firmware architecture, required rules for development, board configuration process, and validation steps. - Included detailed sections on project structure, commands for building and testing, and authoritative documentation references. * feat: finalize glyph push protocol * fix: remove stale emoji font include * build: use xiaozhi-fonts 2.0.0 * fix: decouple custom fonts from glyph push * refactor: improve wake word invocation handling - Introduced BeginWakeWordInvoke method to streamline the wake word processing flow. - Updated HandleWakeWordDetectedEvent to utilize the new method, ensuring proper state transitions and scheduling. - Enhanced error handling to prevent the device from getting stuck in the connecting state. - Refactored audio channel management to improve responsiveness during wake word detection. --------- Co-authored-by: Xiaoxia <terrence.huang@tenclass.com>
95 lines
4.8 KiB
Markdown
95 lines
4.8 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project
|
|
|
|
XiaoZhi is an ESP-IDF C/C++ voice-assistant firmware supporting many chips, boards, displays, audio devices, and network transports. A build selects exactly one board implementation.
|
|
|
|
Use ESP-IDF v6.0.2 when possible. IDF 5.5.x is retained only for documented legacy boards.
|
|
|
|
## Architecture
|
|
|
|
- `main/application.*`: main event loop, protocol lifecycle, and high-level behavior.
|
|
- `main/device_state_machine.*`: legal runtime state transitions.
|
|
- `main/boards/common/`: board interfaces and reusable hardware/network helpers.
|
|
- `main/boards/**/`: board-specific pins, initialization, and build variants.
|
|
- `main/audio/`: codecs, audio tasks, engines, wake words, and queues.
|
|
- `main/protocols/`: transport-neutral API plus WebSocket and MQTT/UDP.
|
|
- `main/display/` and `main/led/`: reusable UI implementations.
|
|
- `main/mcp_server.*`: common device-side MCP tools and dispatch.
|
|
- `main/Kconfig.projbuild`: board and feature configuration.
|
|
- `main/CMakeLists.txt`: source, board, locale, font, and asset selection.
|
|
- `scripts/release.py`: canonical board/variant build entry point.
|
|
|
|
Read the closest existing implementation before adding a new one. Prefer the narrowest owning layer; do not put board-specific behavior into core modules.
|
|
|
|
## Required Rules
|
|
|
|
- Preserve unrelated worktree changes and keep patches focused.
|
|
- A build must export exactly one board factory through `DECLARE_BOARD(...)`.
|
|
- Never alter an existing board's pins to support different hardware. Add a uniquely named board or release variant; board identity affects OTA compatibility.
|
|
- Core code depends on `Board` interfaces, never a concrete board class or board `config.h`.
|
|
- Treat camera, backlight, display, LED, battery, and similar capabilities as optional.
|
|
- Change runtime state through `Application::SetDeviceState()` and the state machine.
|
|
- Callbacks may run outside the main task. Schedule application mutations with `Application::Schedule()` or event bits.
|
|
- Do not block the main event loop or audio tasks. Avoid unbounded queues and repeated large allocations in audio paths.
|
|
- Keep shared message semantics in `Protocol`; verify both transports when changing its contract.
|
|
- Validate network input and preserve `cJSON` ownership. NVS keys are persistent API and require migration when changed.
|
|
- Guard target-specific features with Kconfig/component rules. Do not assume every target has PSRAM or S3/P4 resources.
|
|
- Do not manually edit generated/vendor output: `build/`, `releases/`, `managed_components/`, `components/`, `sdkconfig*`, `main/assets/lang_config.h`, or generated mmap headers.
|
|
- Format only touched C/C++ files with the repository `.clang-format`; avoid unrelated mass formatting.
|
|
|
|
## Boards and Configuration
|
|
|
|
Board selection is a coupled chain:
|
|
|
|
`config.json` -> `scripts/release.py` -> `main/Kconfig.projbuild` -> `main/CMakeLists.txt` -> board source and `config.h`.
|
|
|
|
When adding a board or variant, update every relevant link in that chain. Include a unique board identity, correct chip target, flash/partition settings, exactly one `DECLARE_BOARD`, and board documentation. Follow `docs/custom-board.md`.
|
|
|
|
## Commands
|
|
|
|
Source the intended ESP-IDF environment first:
|
|
|
|
```sh
|
|
source /path/to/esp-idf/export.sh
|
|
idf.py --version
|
|
```
|
|
|
|
```sh
|
|
# Discover exact board and variant names
|
|
python3 scripts/release.py --list-boards
|
|
|
|
# Canonical variant build
|
|
python3 scripts/release.py <board-directory> --name <variant-name>
|
|
|
|
# Host-side release tests
|
|
python3 -m unittest discover -s scripts/tests -v
|
|
|
|
# Format/check touched files
|
|
clang-format -i <files>
|
|
clang-format --dry-run -Werror <files>
|
|
```
|
|
|
|
The release script changes local `sdkconfig` and build state. Do not assume the build directory still represents a previous target.
|
|
|
|
## Validation
|
|
|
|
- Board-only change: build affected variants and smoke-test changed hardware.
|
|
- Core, common-board, audio, protocol, display, dependency, Kconfig, or CMake change: run host tests and build representative affected chip/network paths.
|
|
- Protocol changes: verify WebSocket and MQTT/UDP when shared behavior changes.
|
|
- Audio changes: verify capture, playback, wake/VAD, interruption, reconnect, and applicable AEC modes.
|
|
- UI/assets changes: verify applicable no-display/OLED/LVGL paths and partition size.
|
|
- Always report what was tested and what still needs physical hardware. A successful build is not hardware validation.
|
|
|
|
## Authoritative Documentation
|
|
|
|
- Overview and SDK policy: `README.md`
|
|
- SDK compatibility: `docs/esp-idf-6-migration.md`
|
|
- Board guide: `docs/custom-board.md`
|
|
- Audio design: `main/audio/README.md`
|
|
- Code style: `docs/code_style.md`
|
|
- Protocols: `docs/websocket.md`, `docs/mqtt-udp.md`, `docs/mcp-protocol.md`
|
|
- CI matrix: `.github/workflows/build.yml`
|
|
|
|
Keep detailed or fast-changing information in those files, not here. Add a nested `AGENTS.md` only when a subsystem needs specialized instructions.
|