AGENTS.md

1# AGENTS.md
2 
3## Project
4 
5XiaoZhi 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.
6 
7Use ESP-IDF v6.0.2 when possible. IDF 5.5.x is retained only for documented legacy boards.
8 
9## Architecture
10 
11- `main/application.*`: main event loop, protocol lifecycle, and high-level behavior.
12- `main/device_state_machine.*`: legal runtime state transitions.
13- `main/boards/common/`: board interfaces and reusable hardware/network helpers.
14- `main/boards/**/`: board-specific pins, initialization, and build variants.
15- `main/audio/`: codecs, audio tasks, engines, wake words, and queues.
16- `main/protocols/`: transport-neutral API plus WebSocket and MQTT/UDP.
17- `main/display/` and `main/led/`: reusable UI implementations.
18- `main/mcp_server.*`: common device-side MCP tools and dispatch.
19- `main/Kconfig.projbuild`: board and feature configuration.
20- `main/CMakeLists.txt`: source, board, locale, font, and asset selection.
21- `scripts/build.py`: canonical board/variant build entry point.
22 
23Read the closest existing implementation before adding a new one. Prefer the narrowest owning layer; do not put board-specific behavior into core modules.
24 
25## Required Rules
26 
27- Preserve unrelated worktree changes and keep patches focused.
28- A build must export exactly one board factory through `DECLARE_BOARD(...)`.
29- Never alter an existing board's pins to support different hardware. Add a uniquely named board or release variant; board identity affects OTA compatibility.
30- Core code depends on `Board` interfaces, never a concrete board class or board `config.h`.
31- Treat camera, backlight, display, LED, battery, and similar capabilities as optional.
32- Change runtime state through `Application::SetDeviceState()` and the state machine.
33- Callbacks may run outside the main task. Schedule application mutations with `Application::Schedule()` or event bits.
34- Do not block the main event loop or audio tasks. Avoid unbounded queues and repeated large allocations in audio paths.
35- Keep shared message semantics in `Protocol`; verify both transports when changing its contract.
36- Validate network input and preserve `cJSON` ownership. NVS keys are persistent API and require migration when changed.
37- Guard target-specific features with Kconfig/component rules. Do not assume every target has PSRAM or S3/P4 resources.
38- Do not manually edit generated/vendor output: `build/`, `releases/`, `managed_components/`, `components/`, `sdkconfig*`, `main/assets/lang_config.h`, or generated mmap headers.
39- Format only touched C/C++ files with the repository `.clang-format`; avoid unrelated mass formatting.
40 
41## Boards and Configuration
42 
43Board selection is a coupled chain:
44 
45`config.json` -> `scripts/build.py` -> `main/Kconfig.projbuild` -> `main/CMakeLists.txt` -> board source and `config.h`.
46 
47When 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`.
48 
49## Commands
50 
51Source the intended ESP-IDF environment first:
52 
53```sh
54source /path/to/esp-idf/export.sh
55idf.py --version
56```
57 
58```sh
59# Discover exact board and variant names
60python3 scripts/build.py --list-boards
61 
62# Canonical variant build
63python3 scripts/build.py <board-directory> --name <variant-name>
64 
65# Host-side build tests
66python3 -m unittest discover -s scripts/tests -v
67 
68# Format/check touched files
69clang-format -i <files>
70clang-format --dry-run -Werror <files>
71```
72 
73The build script changes local `sdkconfig` and build state. Do not assume the build directory still represents a previous target.
74 
75## Validation
76 
77- Board-only change: build affected variants and smoke-test changed hardware.
78- Core, common-board, audio, protocol, display, dependency, Kconfig, or CMake change: run host tests and build representative affected chip/network paths.
79- Protocol changes: verify WebSocket and MQTT/UDP when shared behavior changes.
80- Audio changes: verify capture, playback, wake/VAD, interruption, reconnect, and applicable AEC modes.
81- UI/assets changes: verify applicable no-display/OLED/LVGL paths and partition size.
82- Always report what was tested and what still needs physical hardware. A successful build is not hardware validation.
83 
84## Authoritative Documentation
85 
86- Overview and SDK policy: `README.md`
87- SDK compatibility: `docs/esp-idf-6-migration.md`
88- Board guide: `docs/custom-board.md`
89- Audio design: `main/audio/README.md`
90- Code style: `docs/code_style.md`
91- Protocols: `docs/websocket.md`, `docs/mqtt-udp.md`, `docs/mcp-protocol.md`
92- CI matrix: `.github/workflows/build.yml`
93 
94Keep detailed or fast-changing information in those files, not here. Add a nested `AGENTS.md` only when a subsystem needs specialized instructions.
95