{"owner":"78","repo":"xiaozhi-esp32","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\n## Project\n\nXiaoZhi 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.\n\nUse ESP-IDF v6.0.2 when possible. IDF 5.5.x is retained only for documented legacy boards.\n\n## Architecture\n\n- `main/application.*`: main event loop, protocol lifecycle, and high-level behavior.\n- `main/device_state_machine.*`: legal runtime state transitions.\n- `main/boards/common/`: board interfaces and reusable hardware/network helpers.\n- `main/boards/**/`: board-specific pins, initialization, and build variants.\n- `main/audio/`: codecs, audio tasks, engines, wake words, and queues.\n- `main/protocols/`: transport-neutral API plus WebSocket and MQTT/UDP.\n- `main/display/` and `main/led/`: reusable UI implementations.\n- `main/mcp_server.*`: common device-side MCP tools and dispatch.\n- `main/Kconfig.projbuild`: board and feature configuration.\n- `main/CMakeLists.txt`: source, board, locale, font, and asset selection.\n- `scripts/build.py`: canonical board/variant build entry point.\n\nRead the closest existing implementation before adding a new one. Prefer the narrowest owning layer; do not put board-specific behavior into core modules.\n\n## Required Rules\n\n- Preserve unrelated worktree changes and keep patches focused.\n- A build must export exactly one board factory through `DECLARE_BOARD(...)`.\n- Never alter an existing board's pins to support different hardware. Add a uniquely named board or release variant; board identity affects OTA compatibility.\n- Core code depends on `Board` interfaces, never a concrete board class or board `config.h`.\n- Treat camera, backlight, display, LED, battery, and similar capabilities as optional.\n- Change runtime state through `Application::SetDeviceState()` and the state machine.\n- Callbacks may run outside the main task. Schedule application mutations with `Application::Schedule()` or event bits.\n- Do not block the main event loop or audio tasks. Avoid unbounded queues and repeated large allocations in audio paths.\n- Keep shared message semantics in `Protocol`; verify both transports when changing its contract.\n- Validate network input and preserve `cJSON` ownership. NVS keys are persistent API and require migration when changed.\n- Guard target-specific features with Kconfig/component rules. Do not assume every target has PSRAM or S3/P4 resources.\n- Do not manually edit generated/vendor output: `build/`, `releases/`, `managed_components/`, `components/`, `sdkconfig*`, `main/assets/lang_config.h`, or generated mmap headers.\n- Format only touched C/C++ files with the repository `.clang-format`; avoid unrelated mass formatting.\n\n## Boards and Configuration\n\nBoard selection is a coupled chain:\n\n`config.json` -> `scripts/build.py` -> `main/Kconfig.projbuild` -> `main/CMakeLists.txt` -> board source and `config.h`.\n\nWhen 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`.\n\n## Commands\n\nSource the intended ESP-IDF environment first:\n\n```sh\nsource /path/to/esp-idf/export.sh\nidf.py --version\n```\n\n```sh\n# Discover exact board and variant names\npython3 scripts/build.py --list-boards\n\n# Canonical variant build\npython3 scripts/build.py <board-directory> --name <variant-name>\n\n# Host-side build tests\npython3 -m unittest discover -s scripts/tests -v\n\n# Format/check touched files\nclang-format -i <files>\nclang-format --dry-run -Werror <files>\n```\n\nThe build script changes local `sdkconfig` and build state. Do not assume the build directory still represents a previous target.\n\n## Validation\n\n- Board-only change: build affected variants and smoke-test changed hardware.\n- Core, common-board, audio, protocol, display, dependency, Kconfig, or CMake change: run host tests and build representative affected chip/network paths.\n- Protocol changes: verify WebSocket and MQTT/UDP when shared behavior changes.\n- Audio changes: verify capture, playback, wake/VAD, interruption, reconnect, and applicable AEC modes.\n- UI/assets changes: verify applicable no-display/OLED/LVGL paths and partition size.\n- Always report what was tested and what still needs physical hardware. A successful build is not hardware validation.\n\n## Authoritative Documentation\n\n- Overview and SDK policy: `README.md`\n- SDK compatibility: `docs/esp-idf-6-migration.md`\n- Board guide: `docs/custom-board.md`\n- Audio design: `main/audio/README.md`\n- Code style: `docs/code_style.md`\n- Protocols: `docs/websocket.md`, `docs/mqtt-udp.md`, `docs/mcp-protocol.md`\n- CI matrix: `.github/workflows/build.yml`\n\nKeep detailed or fast-changing information in those files, not here. Add a nested `AGENTS.md` only when a subsystem needs specialized instructions.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\n## Project\n\nXiaoZhi 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.\n\nUse ESP-IDF v6.0.2 when possible. IDF 5.5.x is retained only for documented legacy boards.\n\n## Architecture\n\n- `main/application.*`: main event loop, protocol lifecycle, and high-level behavior.\n- `main/device_state_machine.*`: legal runtime state transitions.\n- `main/boards/common/`: board interfaces and reusable hardware/network helpers.\n- `main/boards/**/`: board-specific pins, initialization, and build variants.\n- `main/audio/`: codecs, audio tasks, engines, wake words, and queues.\n- `main/protocols/`: transport-neutral API plus WebSocket and MQTT/UDP.\n- `main/display/` and `main/led/`: reusable UI implementations.\n- `main/mcp_server.*`: common device-side MCP tools and dispatch.\n- `main/Kconfig.projbuild`: board and feature configuration.\n- `main/CMakeLists.txt`: source, board, locale, font, and asset selection.\n- `scripts/build.py`: canonical board/variant build entry point.\n\nRead the closest existing implementation before adding a new one. Prefer the narrowest owning layer; do not put board-specific behavior into core modules.\n\n## Required Rules\n\n- Preserve unrelated worktree changes and keep patches focused.\n- A build must export exactly one board factory through `DECLARE_BOARD(...)`.\n- Never alter an existing board's pins to support different hardware. Add a uniquely named board or release variant; board identity affects OTA compatibility.\n- Core code depends on `Board` interfaces, never a concrete board class or board `config.h`.\n- Treat camera, backlight, display, LED, battery, and similar capabilities as optional.\n- Change runtime state through `Application::SetDeviceState()` and the state machine.\n- Callbacks may run outside the main task. Schedule application mutations with `Application::Schedule()` or event bits.\n- Do not block the main event loop or audio tasks. Avoid unbounded queues and repeated large allocations in audio paths.\n- Keep shared message semantics in `Protocol`; verify both transports when changing its contract.\n- Validate network input and preserve `cJSON` ownership. NVS keys are persistent API and require migration when changed.\n- Guard target-specific features with Kconfig/component rules. Do not assume every target has PSRAM or S3/P4 resources.\n- Do not manually edit generated/vendor output: `build/`, `releases/`, `managed_components/`, `components/`, `sdkconfig*`, `main/assets/lang_config.h`, or generated mmap headers.\n- Format only touched C/C++ files with the repository `.clang-format`; avoid unrelated mass formatting.\n\n## Boards and Configuration\n\nBoard selection is a coupled chain:\n\n`config.json` -> `scripts/build.py` -> `main/Kconfig.projbuild` -> `main/CMakeLists.txt` -> board source and `config.h`.\n\nWhen 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`.\n\n## Commands\n\nSource the intended ESP-IDF environment first:\n\n```sh\nsource /path/to/esp-idf/export.sh\nidf.py --version\n```\n\n```sh\n# Discover exact board and variant names\npython3 scripts/build.py --list-boards\n\n# Canonical variant build\npython3 scripts/build.py <board-directory> --name <variant-name>\n\n# Host-side build tests\npython3 -m unittest discover -s scripts/tests -v\n\n# Format/check touched files\nclang-format -i <files>\nclang-format --dry-run -Werror <files>\n```\n\nThe build script changes local `sdkconfig` and build state. Do not assume the build directory still represents a previous target.\n\n## Validation\n\n- Board-only change: build affected variants and smoke-test changed hardware.\n- Core, common-board, audio, protocol, display, dependency, Kconfig, or CMake change: run host tests and build representative affected chip/network paths.\n- Protocol changes: verify WebSocket and MQTT/UDP when shared behavior changes.\n- Audio changes: verify capture, playback, wake/VAD, interruption, reconnect, and applicable AEC modes.\n- UI/assets changes: verify applicable no-display/OLED/LVGL paths and partition size.\n- Always report what was tested and what still needs physical hardware. A successful build is not hardware validation.\n\n## Authoritative Documentation\n\n- Overview and SDK policy: `README.md`\n- SDK compatibility: `docs/esp-idf-6-migration.md`\n- Board guide: `docs/custom-board.md`\n- Audio design: `main/audio/README.md`\n- Code style: `docs/code_style.md`\n- Protocols: `docs/websocket.md`, `docs/mqtt-udp.md`, `docs/mcp-protocol.md`\n- CI matrix: `.github/workflows/build.yml`\n\nKeep detailed or fast-changing information in those files, not here. Add a nested `AGENTS.md` only when a subsystem needs specialized instructions.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\n## Project\n\nXiaoZhi 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.\n\nUse ESP-IDF v6.0.2 when possible. IDF 5.5.x is retained only for documented legacy boards.\n\n## Architecture\n\n- `main/application.*`: main event loop, protocol lifecycle, and high-level behavior.\n- `main/device_state_machine.*`: legal runtime state transitions.\n- `main/boards/common/`: board interfaces and reusable hardware/network helpers.\n- `main/boards/**/`: board-specific pins, initialization, and build variants.\n- `main/audio/`: codecs, audio tasks, engines, wake words, and queues.\n- `main/protocols/`: transport-neutral API plus WebSocket and MQTT/UDP.\n- `main/display/` and `main/led/`: reusable UI implementations.\n- `main/mcp_server.*`: common device-side MCP tools and dispatch.\n- `main/Kconfig.projbuild`: board and feature configuration.\n- `main/CMakeLists.txt`: source, board, locale, font, and asset selection.\n- `scripts/build.py`: canonical board/variant build entry point.\n\nRead the closest existing implementation before adding a new one. Prefer the narrowest owning layer; do not put board-specific behavior into core modules.\n\n## Required Rules\n\n- Preserve unrelated worktree changes and keep patches focused.\n- A build must export exactly one board factory through `DECLARE_BOARD(...)`.\n- Never alter an existing board's pins to support different hardware. Add a uniquely named board or release variant; board identity affects OTA compatibility.\n- Core code depends on `Board` interfaces, never a concrete board class or board `config.h`.\n- Treat camera, backlight, display, LED, battery, and similar capabilities as optional.\n- Change runtime state through `Application::SetDeviceState()` and the state machine.\n- Callbacks may run outside the main task. Schedule application mutations with `Application::Schedule()` or event bits.\n- Do not block the main event loop or audio tasks. Avoid unbounded queues and repeated large allocations in audio paths.\n- Keep shared message semantics in `Protocol`; verify both transports when changing its contract.\n- Validate network input and preserve `cJSON` ownership. NVS keys are persistent API and require migration when changed.\n- Guard target-specific features with Kconfig/component rules. Do not assume every target has PSRAM or S3/P4 resources.\n- Do not manually edit generated/vendor output: `build/`, `releases/`, `managed_components/`, `components/`, `sdkconfig*`, `main/assets/lang_config.h`, or generated mmap headers.\n- Format only touched C/C++ files with the repository `.clang-format`; avoid unrelated mass formatting.\n\n## Boards and Configuration\n\nBoard selection is a coupled chain:\n\n`config.json` -> `scripts/build.py` -> `main/Kconfig.projbuild` -> `main/CMakeLists.txt` -> board source and `config.h`.\n\nWhen 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`.\n\n## Commands\n\nSource the intended ESP-IDF environment first:\n\n```sh\nsource /path/to/esp-idf/export.sh\nidf.py --version\n```\n\n```sh\n# Discover exact board and variant names\npython3 scripts/build.py --list-boards\n\n# Canonical variant build\npython3 scripts/build.py <board-directory> --name <variant-name>\n\n# Host-side build tests\npython3 -m unittest discover -s scripts/tests -v\n\n# Format/check touched files\nclang-format -i <files>\nclang-format --dry-run -Werror <files>\n```\n\nThe build script changes local `sdkconfig` and build state. Do not assume the build directory still represents a previous target.\n\n## Validation\n\n- Board-only change: build affected variants and smoke-test changed hardware.\n- Core, common-board, audio, protocol, display, dependency, Kconfig, or CMake change: run host tests and build representative affected chip/network paths.\n- Protocol changes: verify WebSocket and MQTT/UDP when shared behavior changes.\n- Audio changes: verify capture, playback, wake/VAD, interruption, reconnect, and applicable AEC modes.\n- UI/assets changes: verify applicable no-display/OLED/LVGL paths and partition size.\n- Always report what was tested and what still needs physical hardware. A successful build is not hardware validation.\n\n## Authoritative Documentation\n\n- Overview and SDK policy: `README.md`\n- SDK compatibility: `docs/esp-idf-6-migration.md`\n- Board guide: `docs/custom-board.md`\n- Audio design: `main/audio/README.md`\n- Code style: `docs/code_style.md`\n- Protocols: `docs/websocket.md`, `docs/mqtt-udp.md`, `docs/mcp-protocol.md`\n- CI matrix: `.github/workflows/build.yml`\n\nKeep detailed or fast-changing information in those files, not here. Add a nested `AGENTS.md` only when a subsystem needs specialized instructions.\n","category":"root","tokens":1221}]}