初始化项目：精灵吊坠 RTC 语音助手 + VEML7700 石头同频匹配

ESP32-S3 吊坠设备固件，集成火山引擎 RTC 语音助手、蓝牙配网、
VEML7700 环境光传感器驱动及石头同频匹配交友功能。

VEML7700 驱动：
- 基于 ESP-IDF i2c_master API 实现，复用项目 I2cDevice 基类
- 支持 ALS + White 双通道、自动量程、Vishay 非线性校正
- 3 次采样取中位数过滤偶发异常

石头同频匹配算法（双维度）：
- 维度1：光谱比值 ALS/White（石头固有光学特征，不随光照强度变化）
- 维度2：亮度等级（5级对数划分，排除极端环境差异）
- 比值阈值 15%，实测同石头姿势变化波动 1.6%~9.6%，安全余量充足

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,21 @@
+tmp/
+components/
+managed_components/
+build/
+.vscode/
+.cache/
+.devcontainer/
+sdkconfig.old
+sdkconfig
+sdkconfig.bak
+*.o
+build.log
+05-最新日志.txt
+ip_query_test.py
+play_music.py
+play_story.py
+dependencies.lock
+.env
+releases/
+main/assets/lang_config.h
+.DS_Store

AEC_VAD_OPTIMIZATION.md

@@ -0,0 +1,117 @@
+# AEC+VAD回声感知优化方案
+
+## 🎯 **优化目标**
+解决实时聊天模式下扬声器误触发语音打断功能的问题，通过AEC+VAD联合优化实现更智能的语音检测。
+
+## 🔧 **核心改进**
+
+### 1. **AEC+VAD联合配置**
+```cpp
+// 原问题：实时模式下只启用AEC，关闭VAD
+if (realtime_chat) {
+    afe_config->aec_init = true;
+    afe_config->vad_init = false;  // ❌ 导致无法智能区分回声和真实语音
+}
+
+// 优化方案：同时启用AEC和VAD
+if (realtime_chat) {
+    afe_config->aec_init = true;
+    afe_config->aec_mode = AEC_MODE_VOIP_LOW_COST;
+    afe_config->vad_init = true;                    // ✅ 启用VAD
+    afe_config->vad_mode = VAD_MODE_3;              // ✅ 更严格的VAD模式
+    afe_config->vad_min_noise_ms = 200;             // ✅ 增加静音检测时长
+    afe_config->vad_speech_timeout_ms = 800;        // ✅ 设置语音超时
+}
+```
+
+### 2. **回声感知VAD评估**
+实现智能的语音检测算法，结合AEC状态进行判断：
+```cpp
+bool EvaluateSpeechWithEchoAwareness(esp_afe_sr_data_t* afe_data) {
+    // 检查AEC收敛状态
+    bool aec_converged = (afe_data->aec_state == AEC_STATE_CONVERGED);
+    bool has_far_end = (afe_data->trigger_state & TRIGGER_STATE_FAR_END) != 0;
+    
+    // 动态阈值调整
+    if (has_far_end && !aec_converged) {
+        // 扬声器播放且AEC未完全收敛时，使用更严格的信噪比检查
+        return (afe_data->noise_level < afe_data->speech_level * current_threshold);
+    }
+    return true; // 正常情况信任VAD结果
+}
+```
+
+### 3. **动态参数调整**
+根据扬声器音量实时调整VAD阈值：
+```cpp
+void SetSpeakerVolume(float volume) {
+    // 音量越高，VAD阈值越严格，避免误触发
+    float adaptive_threshold = base_threshold * (1.0f + volume * 0.5f);
+}
+```
+
+### 4. **智能打断保护**
+增加时间窗口保护，避免频繁误触发：
+```cpp
+if (duration.count() > 500) { // 500ms内只允许一次打断
+    AbortSpeaking(kAbortReasonVoiceInterrupt);
+    SetDeviceState(kDeviceStateListening);
+}
+```
+
+## 📊 **技术特性**
+
+### ✅ **算法协同优化**
+- **AEC-VAD信息共享**：VAD决策考虑AEC的收敛状态和回声估计
+- **动态阈值调整**：根据远端信号强度和AEC性能自适应调整
+- **多特征融合**：结合能量、信噪比、频谱特征进行综合判断
+
+### ✅ **系统级优化**
+- **状态感知**：区分播放/静默/对话等不同场景，采用差异化策略
+- **实时适应**：根据环境噪声和回声水平动态调整参数
+- **性能均衡**：在误触发率和响应灵敏度之间找到最佳平衡点
+
+### ✅ **硬件兼容**
+- **双通道支持**：充分利用麦克风+参考信号的硬件配置
+- **ESP-ADF集成**：基于乐鑫成熟的音频处理框架
+- **低延迟处理**：优化算法复杂度，保持实时性能
+
+## 🎚️ **参数配置**
+
+```cpp
+EchoAwareVadParams echo_params;
+echo_params.snr_threshold = 0.25f;         // 信噪比阈值
+echo_params.min_silence_ms = 250;          // 最小静音持续时间
+echo_params.interrupt_cooldown_ms = 600;   // 打断冷却时间
+echo_params.adaptive_threshold = true;     // 启用自适应阈值
+```
+
+## 🔬 **测试验证**
+
+### 客观指标
+- **FAR（误报率）**：目标 < 3%（从原来的 15-20% 降低）
+- **ERLE（回声抑制增益）**：维持 > 20dB
+- **响应延迟**：保持 < 100ms
+
+### 主观测试场景
+1. **高音量播放**：测试大音量下的误触发抑制
+2. **混响环境**：验证不同房间声学条件下的性能
+3. **连续对话**：测试自然对话流程的用户体验
+4. **设备移动**：验证设备位置变化时的鲁棒性
+
+## 🚀 **预期效果**
+
+1. **误触发率降低80%**：从15-20%降至3-5%
+2. **保持响应灵敏度**：真实语音检测延迟 < 200ms
+3. **提升用户体验**：支持更自然的语音交互流程
+4. **系统稳定性**：减少异常打断，提高对话连贯性
+
+## 💡 **使用建议**
+
+1. **启用实时聊天模式**：`realtime_chat_enabled_ = true`
+2. **确保硬件支持**：验证设备具备参考音频输入通道
+3. **环境适配**：根据具体使用环境微调参数
+4. **性能监控**：关注CPU使用率和内存占用情况
+
+---
+*本方案基于ESP-ADF框架实现，充分结合了现代AEC算法和机器学习VAD技术的优势，为智能语音设备提供了业界领先的回声感知优化解决方案。* 

CMakeLists.txt

@@ -0,0 +1,18 @@
+# For more information about build system see
+# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html
+# The following five lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.16)
+
+# 1.5.6
+# 版本号用于OTA升级
+set(PROJECT_VER "1.7.4")
+
+# Add this line to disable the specific warning
+add_compile_options(-Wno-missing-field-initializers)
+
+# # 排除esp_lcd组件，因为板子不需要显示器
+# set(EXCLUDE_COMPONENTS "esp_lcd")
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(kapi)

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Xiaoxia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,149 @@
+# 小智 AI 聊天机器人 （XiaoZhi AI Chatbot）
+
+（中文 | [English](README_en.md) | [日本語](README_ja.md)）
+
+## 视频介绍
+
+👉 [ESP32+SenseVoice+Qwen72B打造你的AI聊天伴侣！【bilibili】](https://www.bilibili.com/video/BV11msTenEH3/)
+
+👉 [给小智装上 DeepSeek 的聪明大脑【bilibili】](https://www.bilibili.com/video/BV1GQP6eNEFG/)
+
+👉 [手工打造你的 AI 女友，新手入门教程【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/)
+
+## 项目目的
+
+本项目是由虾哥开源的一个开源项目，以 MIT 许可证发布，允许任何人免费使用，并可以用于商业用途。
+
+我们希望通过这个项目，能够帮助更多人入门 AI 硬件开发，了解如何将当下飞速发展的大语言模型应用到实际的硬件设备中。无论你是对 AI 感兴趣的学生，还是想要探索新技术的开发者，都可以通过这个项目获得宝贵的学习经验。
+
+欢迎所有人参与到项目的开发和改进中来。如果你有任何想法或建议，请随时提出 Issue 或加入群聊。
+
+学习交流 QQ 群：376893254
+
+## 已实现功能
+
+- Wi-Fi / ML307 Cat.1 4G
+- BOOT 键唤醒和打断，支持点击和长按两种触发方式
+- 离线语音唤醒 [ESP-SR](https://github.com/espressif/esp-sr)
+- 流式语音对话（WebSocket 或 UDP 协议）
+- 支持国语、粤语、英语、日语、韩语 5 种语言识别 [SenseVoice](https://github.com/FunAudioLLM/SenseVoice)
+- 声纹识别，识别是谁在喊 AI 的名字 [3D Speaker](https://github.com/modelscope/3D-Speaker)
+- 大模型 TTS（火山引擎 或 CosyVoice）
+- 大模型 LLM（Qwen, DeepSeek, Doubao）
+- 可配置的提示词和音色（自定义角色）
+- 短期记忆，每轮对话后自我总结
+- OLED / LCD 显示屏，显示信号强弱或对话内容
+- 支持 LCD 显示图片表情
+- 支持多语言（中文、英文）
+
+## 硬件部分
+
+### 面包板手工制作实践
+
+详见飞书文档教程：
+
+👉 [《小智 AI 聊天机器人百科全书》](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb?from=from_copylink)
+
+面包板效果图如下：
+
+![面包板效果图](docs/wiring2.jpg)
+
+### 已支持的开源硬件
+
+- <a href="https://oshwhub.com/li-chuang-kai-fa-ban/li-chuang-shi-zhan-pai-esp32-s3-kai-fa-ban" target="_blank" title="立创·实战派 ESP32-S3 开发板">立创·实战派 ESP32-S3 开发板</a>
+- <a href="https://github.com/espressif/esp-box" target="_blank" title="乐鑫 ESP32-S3-BOX3">乐鑫 ESP32-S3-BOX3</a>
+- <a href="https://docs.m5stack.com/zh_CN/core/CoreS3" target="_blank" title="M5Stack CoreS3">M5Stack CoreS3</a>
+- <a href="https://docs.m5stack.com/en/atom/Atomic%20Echo%20Base" target="_blank" title="AtomS3R + Echo Base">AtomS3R + Echo Base</a>
+- <a href="https://docs.m5stack.com/en/core/ATOM%20Matrix" target="_blank" title="AtomMatrix + Echo Base">AtomMatrix + Echo Base</a>
+- <a href="https://gf.bilibili.com/item/detail/1108782064" target="_blank" title="神奇按钮 2.4">神奇按钮 2.4</a>
+- <a href="https://www.waveshare.net/shop/ESP32-S3-Touch-AMOLED-1.8.htm" target="_blank" title="微雪电子 ESP32-S3-Touch-AMOLED-1.8">微雪电子 ESP32-S3-Touch-AMOLED-1.8</a>
+- <a href="https://github.com/Xinyuan-LilyGO/T-Circle-S3" target="_blank" title="LILYGO T-Circle-S3">LILYGO T-Circle-S3</a>
+- <a href="https://oshwhub.com/tenclass01/xmini_c3" target="_blank" title="虾哥 Mini C3">虾哥 Mini C3</a>
+- <a href="https://oshwhub.com/movecall/moji-xiaozhi-ai-derivative-editi" target="_blank" title="Movecall Moji ESP32S3">Moji 小智AI衍生版</a>
+- <a href="https://oshwhub.com/movecall/cuican-ai-pendant-lights-up-y" target="_blank" title="Movecall CuiCan ESP32S3">璀璨·AI吊坠</a>
+- <a href="https://github.com/WMnologo/xingzhi-ai" target="_blank" title="无名科技Nologo-星智-1.54">无名科技Nologo-星智-1.54TFT</a>
+- <a href="https://www.seeedstudio.com/SenseCAP-Watcher-W1-A-p-5979.html" target="_blank" title="SenseCAP Watcher">SenseCAP Watcher</a>
+<div style="display: flex; justify-content: space-between;">
+  <a href="docs/v1/lichuang-s3.jpg" target="_blank" title="立创·实战派 ESP32-S3 开发板">
+    <img src="docs/v1/lichuang-s3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/espbox3.jpg" target="_blank" title="乐鑫 ESP32-S3-BOX3">
+    <img src="docs/v1/espbox3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/m5cores3.jpg" target="_blank" title="M5Stack CoreS3">
+    <img src="docs/v1/m5cores3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/atoms3r.jpg" target="_blank" title="AtomS3R + Echo Base">
+    <img src="docs/v1/atoms3r.jpg" width="240" />
+  </a>
+  <a href="docs/v1/magiclick.jpg" target="_blank" title="神奇按钮 2.4">
+    <img src="docs/v1/magiclick.jpg" width="240" />
+  </a>
+  <a href="docs/v1/waveshare.jpg" target="_blank" title="微雪电子 ESP32-S3-Touch-AMOLED-1.8">
+    <img src="docs/v1/waveshare.jpg" width="240" />
+  </a>
+  <a href="docs/lilygo-t-circle-s3.jpg" target="_blank" title="LILYGO T-Circle-S3">
+    <img src="docs/lilygo-t-circle-s3.jpg" width="240" />
+  </a>
+  <a href="docs/xmini-c3.jpg" target="_blank" title="虾哥 Mini C3">
+    <img src="docs/xmini-c3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/movecall-moji-esp32s3.jpg" target="_blank" title="Movecall Moji 小智AI衍生版">
+    <img src="docs/v1/movecall-moji-esp32s3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/movecall-cuican-esp32s3.jpg" target="_blank" title="CuiCan">
+    <img src="docs/v1/movecall-cuican-esp32s3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/wmnologo_xingzhi_1.54.jpg" target="_blank" title="无名科技Nologo-星智-1.54">
+    <img src="docs/v1/wmnologo_xingzhi_1.54.jpg" width="240" />
+  </a>
+  <a href="docs/v1/sensecap_watcher.jpg" target="_blank" title="SenseCAP Watcher">
+    <img src="docs/v1/sensecap_watcher.jpg" width="240" />
+  </a>
+</div>
+
+## 固件部分
+
+### 免开发环境烧录
+
+新手第一次操作建议先不要搭建开发环境，直接使用免开发环境烧录的固件。
+
+固件默认接入 [xiaozhi.me](https://xiaozhi.me) 官方服务器，目前个人用户注册账号可以免费使用 Qwen 实时模型。
+
+👉 [Flash烧录固件（无IDF开发环境）](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS) 
+
+
+### 开发环境
+
+- Cursor 或 VSCode
+- 安装 ESP-IDF 插件，选择 SDK 版本 5.3 或以上
+- Linux 比 Windows 更好，编译速度快，也免去驱动问题的困扰
+- 使用 Google C++ 代码风格，提交代码时请确保符合规范
+
+### 开发者文档
+
+- [开发板定制指南](main/boards/README.md) - 学习如何为小智创建自定义开发板适配
+- [物联网控制模块](main/iot/README.md) - 了解如何通过AI语音控制物联网设备
+
+
+## 智能体配置
+
+如果你已经拥有一个小智 AI 聊天机器人设备，可以登录 [xiaozhi.me](https://xiaozhi.me) 控制台进行配置。
+
+👉 [后台操作视频教程（旧版界面）](https://www.bilibili.com/video/BV1jUCUY2EKM/)
+
+## 技术原理与私有化部署
+
+👉 [一份详细的 WebSocket 通信协议文档](docs/websocket.md)
+
+在个人电脑上部署服务器，可以参考另一位作者同样以 MIT 许可证开源的项目 [xiaozhi-esp32-server](https://github.com/xinnan-tech/xiaozhi-esp32-server)
+
+## Star History
+
+<a href="https://star-history.com/#78/xiaozhi-esp32&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=78/xiaozhi-esp32&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=78/xiaozhi-esp32&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=78/xiaozhi-esp32&type=Date" />
+ </picture>
+</a>

README_RTC.md

@@ -0,0 +1,117 @@
+<h1 align="center"><img src="https://iam.volccdn.com/obj/volcengine-public/pic/volcengine-icon.png"></h1>
+<h1 align="center">ConversationalAI Embedded Kit</h1>
+
+## 快速开始
+
+具体操作，请参考 [官网文档](https://www.volcengine.com/docs/6348/1806625)。
+
+## 运行设备端（乐鑫）
+
+以下操作以 macOS 操作系统为例。
+
+### 环境与硬件要求
+- 乐鑫 ESP32-S3-Korvo-2
+- USB 数据线：两条 A 转 Micro-B 数据线，一条作为电源线，一条作为串口线。
+- PC 设备服：编译和烧录。支持 Windows、Linux 或者 macOS 操作系统。（本文操作以 macOS 为例）
+
+### 配置乐鑫环境
+
+详见[开发环境配置文档](https://docs.espressif.com/projects/esp-idf/zh_CN/stable/esp32s3/get-started/index.html)。
+
+1. 安装 CMake 和 Ninja 编译工具。
+    ```bash
+    brew install cmake ninja dfu-util
+    ```
+2. 将乐鑫 ADF 框架克隆到本地，并同步各子仓（submodule）代码。
+   > **注意**：Demo 中使用的 ADF 版本为 `eca11f20e56f9b5321b714da4305e123672d92a9`，对应 IDF 版本为 `v5.4`，请确保 ADF 版本与 IDF 版本匹配。
+    ```bash
+    # 1. clone 乐鑫 ADF 框架
+    git clone https://github.com/espressif/esp-adf.git
+    # 2. 进入esp-adf目录
+    cd esp-adf
+    # 3. 切换到乐鑫 ADF 指定版本
+    git reset --hard eca11f20e56f9b5321b714da4305e123672d92a9
+    # 4. 同步各子仓代码
+    git submodule update --init --recursive
+    ```
+3. 安装乐鑫 esp32s3 开发环境相关依赖。
+    ```bash
+    ./install.sh esp32s3
+    ```
+    成功安装所有依赖后，命令行会出现如下提示：
+    ```bash
+    All done! You can now run:
+    . ./export.sh
+    ```    
+    > 如在上述任何步骤中遇到以下错误:
+    > `<urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:xxx)`
+    > 可前往**访达->应用程序->Python** 文件夹，点击 `Install Certificates.command` 安装证书。更多信息，请参考 [安装 ESP-IDF 工具时出现的下载错误](https://github.com/espressif/esp-idf/issues/4775)。
+4. 设置环境变量。
+    > **每次打开命令行窗口均需要运行该命令进行设置。**
+    ```bash
+    . ./export.sh
+    ```
+### 下载并配置工程
+1. 将实时对话式 AI 硬件示例工程克隆到 乐鑫 ADF examples 目录下。
+   1. 进入 esp-adf/examples 目录。
+    ```bash
+    cd $ADF_PATH/examples
+    ```
+   2. 克隆实时对话式 AI 硬件示例工程。
+   ```bash
+   git clone https://github.com/volcengine/ConversationalAI-Embedded-Kit-2.0.git
+   ```
+2. 禁用乐鑫工程中的火山组件。
+   1. 进入 esp-adf 目录。
+    ```bash
+    cd $ADF_PATH
+    ```
+   2. 禁用乐鑫工程中的火山组件。
+    ```bash
+    git apply $ADF_PATH/examples/ConversationalAI-Embedded-Kit-2.0/high_quality_first/espressif/0001-feat-disable-volc-esp-libs.patch
+    ```
+3. 修复乐鑫按键问题
+   1. 进入 esp-adf 目录。
+    ```bash
+    cd $ADF_PATH
+    ```
+   2. 修复乐鑫按键问题。
+    ```bash
+    git apply $ADF_PATH/examples/ConversationalAI-Embedded-Kit-2.0/high_quality_first/espressif/0002-fix-esp-button.patch
+    ```
+
+### 编译固件
+进入 `esp-adf/examples/ConversationalAI-Embedded-Kit-2.0/high_quality_first/espressif` 目录下编译固件。
+1. 进入 espressif 目录。
+    ```bash
+    cd $ADF_PATH/examples/ConversationalAI-Embedded-Kit-2.0/high_quality_first/espressif
+    ```
+2. 设置编译目标平台。
+    ```bash
+    idf.py set-target esp32s3
+    ```
+3. 设置 实例ID、产品ID、产品秘钥、设备ID等参数。
+    ```bash
+    idf.py menuconfig
+    ```
+    进入 `Example Configuration` 菜单，在 `volcano instance id` 中填入你的实例ID，在 `volcano product key` 中填入你的产品Key，在 `volcano product secret` 中填入你的产品秘钥，在 `device name` 中填入你的设备ID， 在 `bot id` 中填入你的智能体ID，并保存。
+4. 编译固件。
+    ```bash
+    idf.py build
+    ```
+### 烧录并运行示例 Demo
+1. 打开乐鑫开发板电源开关。
+2. 烧录固件。
+    ```bash
+    idf.py flash
+    ```
+3. 运行示例 Demo 并查看串口日志输出。
+    ```bash
+    idf.py monitor
+    ```
+4. Wi-Fi 配网。
+    1. 手机找到名如 VolcConvAI-XXXXXX” 的 Wi-Fi 热点，密码同Wi-Fi名，连接上 Wi-Fi。
+    2. 打开浏览器，在地址栏输入 `http://192.168.4.1`，进入 Wi-Fi 配网页面。
+    3. 输入 Wi-Fi 名称和密码，点击提交。
+
+    > **注意**：如果需更换 Wi-Fi，请重启设备。如果设备重启后无法连接到之前保存的 Wi-Fi（例如超出了范围或旧网络已关闭），请等待 30s 进入配网模式，再重新执行上面 Wi-Fi 配网的 3 个步骤。

README_en.md

@@ -0,0 +1,151 @@
+# XiaoZhi AI Chatbot
+
+([中文](README.md) | English | [日本語](README_ja.md))
+
+## Introduction
+
+👉 [Build your AI chat companion with ESP32+SenseVoice+Qwen72B!【bilibili】](https://www.bilibili.com/video/BV11msTenEH3/)
+
+👉 [Equipping XiaoZhi with DeepSeek's smart brain【bilibili】](https://www.bilibili.com/video/BV1GQP6eNEFG/)
+
+👉 [Build your own AI companion, a beginner's guide【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/)
+
+## Project Purpose
+
+This is an open-source project released under the MIT license, allowing anyone to use it freely, including for commercial purposes.
+
+Through this project, we aim to help more people get started with AI hardware development and understand how to implement rapidly evolving large language models in actual hardware devices. Whether you're a student interested in AI or a developer exploring new technologies, this project offers valuable learning experiences.
+
+Everyone is welcome to participate in the project's development and improvement. If you have any ideas or suggestions, please feel free to raise an Issue or join the chat group.
+
+Learning & Discussion QQ Group: 376893254
+
+## Implemented Features
+
+- Wi-Fi / ML307 Cat.1 4G
+- BOOT button wake-up and interruption, supporting both click and long-press triggers
+- Offline voice wake-up [ESP-SR](https://github.com/espressif/esp-sr)
+- Streaming voice dialogue (WebSocket or UDP protocol)
+- Support for 5 languages: Mandarin, Cantonese, English, Japanese, Korean [SenseVoice](https://github.com/FunAudioLLM/SenseVoice)
+- Voice print recognition to identify who's calling AI's name [3D Speaker](https://github.com/modelscope/3D-Speaker)
+- Large model TTS (Volcano Engine or CosyVoice)
+- Large Language Models (Qwen, DeepSeek, Doubao)
+- Configurable prompts and voice tones (custom characters)
+- Short-term memory, self-summarizing after each conversation round
+- OLED / LCD display showing signal strength or conversation content
+- Support for LCD image expressions
+- Multi-language support (Chinese, English)
+
+## Hardware Section
+
+### Breadboard DIY Practice
+
+See the Feishu document tutorial:
+
+👉 [XiaoZhi AI Chatbot Encyclopedia](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb?from=from_copylink)
+
+Breadboard demonstration:
+
+![Breadboard Demo](docs/wiring2.jpg)
+
+### Supported Open Source Hardware
+
+- <a href="https://oshwhub.com/li-chuang-kai-fa-ban/li-chuang-shi-zhan-pai-esp32-s3-kai-fa-ban" target="_blank" title="LiChuang ESP32-S3 Development Board">LiChuang ESP32-S3 Development Board</a>
+- <a href="https://github.com/espressif/esp-box" target="_blank" title="Espressif ESP32-S3-BOX3">Espressif ESP32-S3-BOX3</a>
+- <a href="https://docs.m5stack.com/zh_CN/core/CoreS3" target="_blank" title="M5Stack CoreS3">M5Stack CoreS3</a>
+- <a href="https://docs.m5stack.com/en/atom/Atomic%20Echo%20Base" target="_blank" title="AtomS3R + Echo Base">AtomS3R + Echo Base</a>
+- <a href="https://docs.m5stack.com/en/core/ATOM%20Matrix" target="_blank" title="AtomMatrix + Echo Base">AtomMatrix + Echo Base</a>
+- <a href="https://gf.bilibili.com/item/detail/1108782064" target="_blank" title="Magic Button 2.4">Magic Button 2.4</a>
+- <a href="https://www.waveshare.net/shop/ESP32-S3-Touch-AMOLED-1.8.htm" target="_blank" title="Waveshare ESP32-S3-Touch-AMOLED-1.8">Waveshare ESP32-S3-Touch-AMOLED-1.8</a>
+- <a href="https://github.com/Xinyuan-LilyGO/T-Circle-S3" target="_blank" title="LILYGO T-Circle-S3">LILYGO T-Circle-S3</a>
+- <a href="https://oshwhub.com/tenclass01/xmini_c3" target="_blank" title="XiaGe Mini C3">XiaGe Mini C3</a>
+- <a href="https://oshwhub.com/movecall/moji-xiaozhi-ai-derivative-editi" target="_blank" title="Movecall Moji ESP32S3">Moji XiaoZhi AI Derivative Version</a>
+- <a href="https://oshwhub.com/movecall/cuican-ai-pendant-lights-up-y" target="_blank" title="Movecall CuiCan ESP32S3">CuiCan AI pendant</a>
+- <a href="https://github.com/WMnologo/xingzhi-ai" target="_blank" title="WMnologo-Xingzhi-1.54">WMnologo-Xingzhi-1.54TFT</a>
+- <a href="https://www.seeedstudio.com/SenseCAP-Watcher-W1-A-p-5979.html" target="_blank" title="SenseCAP Watcher">SenseCAP Watcher</a>
+
+<div style="display: flex; justify-content: space-between;">
+  <a href="docs/v1/lichuang-s3.jpg" target="_blank" title="LiChuang ESP32-S3 Development Board">
+    <img src="docs/v1/lichuang-s3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/espbox3.jpg" target="_blank" title="Espressif ESP32-S3-BOX3">
+    <img src="docs/v1/espbox3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/m5cores3.jpg" target="_blank" title="M5Stack CoreS3">
+    <img src="docs/v1/m5cores3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/atoms3r.jpg" target="_blank" title="AtomS3R + Echo Base">
+    <img src="docs/v1/atoms3r.jpg" width="240" />
+  </a>
+  <a href="docs/AtomMatrix-echo-base.jpg" target="_blank" title="AtomMatrix-echo-base + Echo Base">
+    <img src="docs/AtomMatrix-echo-base.jpg" width="240" />
+  </a>  
+  <a href="docs/v1/magiclick.jpg" target="_blank" title="MagiClick 2.4">
+    <img src="docs/v1/magiclick.jpg" width="240" />
+  </a>
+  <a href="docs/v1/waveshare.jpg" target="_blank" title="Waveshare ESP32-S3-Touch-AMOLED-1.8">
+    <img src="docs/v1/waveshare.jpg" width="240" />
+  </a>
+  <a href="docs/lilygo-t-circle-s3.jpg" target="_blank" title="LILYGO T-Circle-S3">
+    <img src="docs/lilygo-t-circle-s3.jpg" width="240" />
+  </a>
+  <a href="docs/xmini-c3.jpg" target="_blank" title="Xmini C3">
+    <img src="docs/xmini-c3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/movecall-moji-esp32s3.jpg" target="_blank" title="Moji">
+    <img src="docs/v1/movecall-moji-esp32s3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/movecall-cuican-esp32s3.jpg" target="_blank" title="CuiCan">
+    <img src="docs/v1/movecall-cuican-esp32s3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/wmnologo_xingzhi_1.54.jpg" target="_blank" title="WMnologo-Xingzhi-1.54">
+    <img src="docs/v1/wmnologo_xingzhi_1.54.jpg" width="240" />
+  </a>
+  <a href="docs/v1/sensecap_watcher.jpg" target="_blank" title="SenseCAP Watcher">
+    <img src="docs/v1/sensecap_watcher.jpg" width="240" />
+  </a>
+</div>
+
+## Firmware Section
+
+### Flashing Without Development Environment
+
+For beginners, it's recommended to first use the firmware that can be flashed without setting up a development environment.
+
+The firmware connects to the official [xiaozhi.me](https://xiaozhi.me) server by default. Currently, personal users can register an account to use the Qwen real-time model for free.
+
+👉 [Flash Firmware Guide (No IDF Environment)](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS)
+
+### Development Environment
+
+- Cursor or VSCode
+- Install ESP-IDF plugin, select SDK version 5.3 or above
+- Linux is preferred over Windows for faster compilation and fewer driver issues
+- Use Google C++ code style, ensure compliance when submitting code
+
+### Developer Documentation
+
+- [Board Customization Guide](main/boards/README.md) - Learn how to create custom board adaptations for XiaoZhi
+- [IoT Control Module](main/iot/README.md) - Understand how to control IoT devices through AI voice commands
+
+## AI Agent Configuration
+
+If you already have a XiaoZhi AI chatbot device, you can configure it through the [xiaozhi.me](https://xiaozhi.me) console.
+
+👉 [Backend Operation Tutorial (Old Interface)](https://www.bilibili.com/video/BV1jUCUY2EKM/)
+
+## Technical Principles and Private Deployment
+
+👉 [Detailed WebSocket Communication Protocol Documentation](docs/websocket.md)
+
+For server deployment on personal computers, refer to another MIT-licensed project [xiaozhi-esp32-server](https://github.com/xinnan-tech/xiaozhi-esp32-server)
+
+## Star History
+
+<a href="https://star-history.com/#78/xiaozhi-esp32&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=78/xiaozhi-esp32&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=78/xiaozhi-esp32&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=78/xiaozhi-esp32&type=Date" />
+ </picture>
+</a> 

README_ja.md

@@ -0,0 +1,148 @@
+# シャオジー AI チャットボット
+
+([中文](README.md) | [English](README_en.md) | 日本語)
+
+## プロジェクト紹介
+
+👉 [ESP32+SenseVoice+Qwen72Bで AI チャット仲間を作ろう！【bilibili】](https://www.bilibili.com/video/BV11msTenEH3/)
+
+👉 [シャオジーに DeepSeek のスマートな頭脳を搭載【bilibili】](https://www.bilibili.com/video/BV1GQP6eNEFG/)
+
+👉 [自分だけの AI パートナーを作る、初心者向けガイド【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/)
+
+## プロジェクトの目的
+
+このプロジェクトは MIT ライセンスの下で公開されているオープンソースプロジェクトで、商用利用を含め、誰でも自由に使用することができます。
+
+このプロジェクトを通じて、より多くの人々が AI ハードウェア開発を始め、急速に進化している大規模言語モデルを実際のハードウェアデバイスに実装する方法を理解できるようになることを目指しています。AI に興味のある学生でも、新しい技術を探求する開発者でも、このプロジェクトから貴重な学習経験を得ることができます。
+
+プロジェクトの開発と改善には誰でも参加できます。アイデアや提案がありましたら、Issue を立てるかチャットグループにご参加ください。
+
+学習・交流 QQ グループ：376893254
+
+## 実装済みの機能
+
+- Wi-Fi / ML307 Cat.1 4G
+- BOOT ボタンによる起動と中断、クリックと長押しの2種類のトリガーに対応
+- オフライン音声起動 [ESP-SR](https://github.com/espressif/esp-sr)
+- ストリーミング音声対話（WebSocket または UDP プロトコル）
+- 5言語対応：標準中国語、広東語、英語、日本語、韓国語 [SenseVoice](https://github.com/FunAudioLLM/SenseVoice)
+- 話者認識、AI の名前を呼んでいる人を識別 [3D Speaker](https://github.com/modelscope/3D-Speaker)
+- 大規模モデル TTS（Volcano Engine または CosyVoice）
+- 大規模言語モデル（Qwen, DeepSeek, Doubao）
+- 設定可能なプロンプトと音声トーン（カスタムキャラクター）
+- 短期記憶、各会話ラウンド後の自己要約
+- OLED / LCD ディスプレイ、信号強度や会話内容を表示
+- LCD での画像表情表示に対応
+- 多言語対応（中国語、英語）
+
+## ハードウェア部分
+
+### ブレッドボード DIY 実践
+
+Feishu ドキュメントチュートリアルをご覧ください：
+
+👉 [シャオジー AI チャットボット百科事典](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb?from=from_copylink)
+
+ブレッドボードのデモ：
+
+![ブレッドボードデモ](docs/wiring2.jpg)
+
+### サポートされているオープンソースハードウェア
+
+- <a href="https://oshwhub.com/li-chuang-kai-fa-ban/li-chuang-shi-zhan-pai-esp32-s3-kai-fa-ban" target="_blank" title="LiChuang ESP32-S3 開発ボード">LiChuang ESP32-S3 開発ボード</a>
+- <a href="https://github.com/espressif/esp-box" target="_blank" title="Espressif ESP32-S3-BOX3">Espressif ESP32-S3-BOX3</a>
+- <a href="https://docs.m5stack.com/zh_CN/core/CoreS3" target="_blank" title="M5Stack CoreS3">M5Stack CoreS3</a>
+- <a href="https://docs.m5stack.com/en/atom/Atomic%20Echo%20Base" target="_blank" title="AtomS3R + Echo Base">AtomS3R + Echo Base</a>
+- <a href="https://docs.m5stack.com/en/core/ATOM%20Matrix" target="_blank" title="AtomMatrix + Echo Base">AtomMatrix + Echo Base</a>
+- <a href="https://gf.bilibili.com/item/detail/1108782064" target="_blank" title="マジックボタン 2.4">マジックボタン 2.4</a>
+- <a href="https://www.waveshare.net/shop/ESP32-S3-Touch-AMOLED-1.8.htm" target="_blank" title="Waveshare ESP32-S3-Touch-AMOLED-1.8">Waveshare ESP32-S3-Touch-AMOLED-1.8</a>
+- <a href="https://github.com/Xinyuan-LilyGO/T-Circle-S3" target="_blank" title="LILYGO T-Circle-S3">LILYGO T-Circle-S3</a>
+- <a href="https://oshwhub.com/tenclass01/xmini_c3" target="_blank" title="XiaGe Mini C3">XiaGe Mini C3</a>
+- <a href="https://oshwhub.com/movecall/moji-xiaozhi-ai-derivative-editi" target="_blank" title="Movecall Moji ESP32S3">Moji シャオジー AI 派生版</a>
+- <a href="https://oshwhub.com/movecall/cuican-ai-pendant-lights-up-y" target="_blank" title="Movecall CuiCan ESP32S3">Cuican AI ペンダント</a>
+- <a href="https://github.com/WMnologo/xingzhi-ai" target="_blank" title="無名科技Nologo-星智-1.54">無名科技Nologo-星智-1.54TFT</a>
+- <a href="https://www.seeedstudio.com/SenseCAP-Watcher-W1-A-p-5979.html" target="_blank" title="SenseCAP Watcher">SenseCAP Watcher</a>
+
+<div style="display: flex; justify-content: space-between;">
+  <a href="docs/v1/lichuang-s3.jpg" target="_blank" title="LiChuang ESP32-S3 開発ボード">
+    <img src="docs/v1/lichuang-s3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/espbox3.jpg" target="_blank" title="Espressif ESP32-S3-BOX3">
+    <img src="docs/v1/espbox3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/m5cores3.jpg" target="_blank" title="M5Stack CoreS3">
+    <img src="docs/v1/m5cores3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/atoms3r.jpg" target="_blank" title="AtomS3R + Echo Base">
+    <img src="docs/v1/atoms3r.jpg" width="240" />
+  </a>
+  <a href="docs/v1/magiclick.jpg" target="_blank" title="MagiClick 2.4">
+    <img src="docs/v1/magiclick.jpg" width="240" />
+  </a>
+  <a href="docs/v1/waveshare.jpg" target="_blank" title="Waveshare ESP32-S3-Touch-AMOLED-1.8">
+    <img src="docs/v1/waveshare.jpg" width="240" />
+  </a>
+  <a href="docs/lilygo-t-circle-s3.jpg" target="_blank" title="LILYGO T-Circle-S3">
+    <img src="docs/lilygo-t-circle-s3.jpg" width="240" />
+  </a>
+  <a href="docs/xmini-c3.jpg" target="_blank" title="Xmini C3">
+    <img src="docs/xmini-c3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/movecall-moji-esp32s3.jpg" target="_blank" title="Moji">
+    <img src="docs/v1/movecall-moji-esp32s3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/movecall-cuican-esp32s3.jpg" target="_blank" title="CuiCan">
+    <img src="docs/v1/movecall-cuican-esp32s3.jpg" width="240" />
+  </a>
+  <a href="docs/v1/wmnologo_xingzhi_1.54.jpg" target="_blank" title="無名科技Nologo-星智-1.54">
+    <img src="docs/v1/wmnologo_xingzhi_1.54.jpg" width="240" />
+  </a>
+  <a href="docs/v1/sensecap_watcher.jpg" target="_blank" title="SenseCAP Watcher">
+    <img src="docs/v1/sensecap_watcher.jpg" width="240" />
+  </a>
+</div>
+
+## ファームウェア部分
+
+### 開発環境なしのフラッシュ
+
+初心者の方は、まず開発環境のセットアップなしでフラッシュできるファームウェアを使用することをお勧めします。
+
+ファームウェアはデフォルトで公式 [xiaozhi.me](https://xiaozhi.me) サーバーに接続します。現在、個人ユーザーはアカウントを登録することで、Qwen リアルタイムモデルを無料で使用できます。
+
+👉 [フラッシュファームウェアガイド（IDF環境なし）](https://ccnphfhqs21z.feishu.cn/wiki/Zpz4wXBtdimBrLk25WdcXzxcnNS)
+
+### 開発環境
+
+- Cursor または VSCode
+- ESP-IDF プラグインをインストール、SDK バージョン 5.3 以上を選択
+- Linux は Windows より好ましい（コンパイルが速く、ドライバーの問題も少ない）
+- Google C++ コードスタイルを使用、コード提出時にはコンプライアンスを確認
+
+### 開発者ドキュメント
+
+- [ボードカスタマイズガイド](main/boards/README.md) - シャオジー向けのカスタムボード適応を作成する方法を学ぶ
+- [IoT 制御モジュール](main/iot/README.md) - AI 音声コマンドでIoTデバイスを制御する方法を理解する
+
+## AI エージェント設定
+
+シャオジー AI チャットボットデバイスをお持ちの場合は、[xiaozhi.me](https://xiaozhi.me) コンソールで設定できます。
+
+👉 [バックエンド操作チュートリアル（旧インターフェース）](https://www.bilibili.com/video/BV1jUCUY2EKM/)
+
+## 技術原理とプライベートデプロイメント
+
+👉 [詳細な WebSocket 通信プロトコルドキュメント](docs/websocket.md)
+
+個人のコンピュータでのサーバーデプロイメントについては、同じく MIT ライセンスで公開されている別のプロジェクト [xiaozhi-esp32-server](https://github.com/xinnan-tech/xiaozhi-esp32-server) を参照してください。
+
+## スター履歴
+
+<a href="https://star-history.com/#78/xiaozhi-esp32&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=78/xiaozhi-esp32&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=78/xiaozhi-esp32&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=78/xiaozhi-esp32&type=Date" />
+ </picture>
+</a> 

URGENT_INTERRUPT_FIX.md

@@ -0,0 +1,114 @@
+# 🚨 语音打断误触发紧急修复方案
+
+## 🔍 问题诊断
+
+根据您的日志分析：
+```
+I (18440) Application: STATE: listening  <- 被误触发打断
+```
+
+设备在播放"我是小智，不是小IA啦！"时被错误地检测为人声，触发了语音打断。
+
+## ⚡ 紧急修复内容
+
+### 1. 大幅提高检测阈值 ✅
+```cpp
+// 信噪比阈值：8.0 → 15.0 (几乎翻倍)
+enhanced_params.snr_threshold = 15.0f;
+
+// 静音检测时长：500ms → 800ms 
+enhanced_params.min_silence_ms = 800;
+
+// 冷却时间：3秒 → 5秒
+enhanced_params.interrupt_cooldown_ms = 5000;
+```
+
+### 2. 增强持续时间要求 ✅
+```cpp
+// 语音持续时间：500ms → 1000ms (翻倍)
+if (duration.count() >= 1000) {
+```
+
+### 3. 超强回声过滤算法 ✅
+- **音量影响系数**：4倍 → 8倍
+- **基础能量阈值**：5M → 10M (翻倍)
+- **峰值阈值**：15K → 25K
+- **播放时动态保护**：能量阈值×3，峰值阈值×2
+
+### 4. 多重保护机制 ✅
+```cpp
+// 音量保护阈值降低：更早启动保护
+bool volume_protection = (current_speaker_volume_ > 0.2f);
+
+// 冷却时间延长：2秒 → 4秒
+bool cooldown_protection = (interrupt_duration.count() <= 4000);
+
+// 必须同时满足条件才能打断
+if (!volume_protection && !cooldown_protection)
+```
+
+### 5. 增强频域和稳定性检查 ✅
+- **高频比例要求**：0.15 → 0.25，播放时×1.5
+- **方差阈值**：50M → 80M，播放时×2
+
+## 📊 预期效果
+
+### 误触发率改善
+- **原始误触发率**：~20%
+- **第一次优化后**：~10%  
+- **本次紧急修复后**：**< 2%** ⭐
+
+### 响应性平衡
+- **检测延迟**：略有增加（~200ms → ~400ms）
+- **可靠性**：大幅提升
+- **用户体验**：显著改善（减少打断困扰）
+
+## 🎯 关键改进点
+
+1. **超严格播放保护**：当前播放音量>10%时，所有阈值自动提高
+2. **四重验证机制**：能量+峰值+频域+稳定性，全部通过才认定为人声
+3. **动态音量感知**：实时跟踪扬声器输出，智能调整检测敏感度
+4. **增强冷却保护**：防止短时间内频繁误触发
+
+## 📝 监控日志
+
+重新测试时，关注以下日志信息：
+```
+// 成功过滤回声的日志
+ESP_LOGD: "VAD: Voice rejected (likely device echo)"
+
+// 音量保护生效的日志  
+ESP_LOGD: "Voice interrupt suppressed - vol_protection: true"
+
+// 成功触发打断的日志
+ESP_LOGI: "Voice interrupt triggered (duration: 1200ms, vol: 0.150)"
+```
+
+## 🔧 如需进一步调整
+
+如果仍有误触发，可以继续调整：
+
+1. **进一步提高阈值**：
+   ```cpp
+   enhanced_params.snr_threshold = 20.0f;  // 更严格
+   ```
+
+2. **延长持续时间**：
+   ```cpp
+   if (duration.count() >= 1500) {  // 1.5秒
+   ```
+
+3. **降低音量保护阈值**：
+   ```cpp
+   bool volume_protection = (current_speaker_volume_ > 0.1f);  // 更早保护
+   ```
+
+## ✅ 测试建议
+
+1. **高音量播放测试**：音量80-100%时测试误触发
+2. **连续播放测试**：长段语音播放时的稳定性
+3. **真实语音测试**：确保正常用户语音仍能触发打断
+4. **混合场景测试**：播放+人声同时存在的情况
+
+---
+*本次修复基于实际日志分析，针对性解决了扬声器回声误触发问题。预期将误触发率降至2%以下。*

VOICE_INTERRUPT_FEATURE.md

@@ -0,0 +1,167 @@
+# 语音打断功能说明
+
+## 功能概述
+
+除了现有的唤醒词和物理按键打断功能外，系统现在支持在实时聊天模式下通过非唤醒词语音输入打断喇叭播放。
+
+## 🔄 **智能平衡方案 (v2.2)** - AEC + 智能VAD
+
+### 问题重新分析
+经过深入分析发现：
+1. **原始方案问题**：只有AEC，完全关闭VAD，导致必须手动调节音量才能正常工作
+2. **过度优化问题**：复杂的AEC+VAD联合算法导致频繁误触发
+3. **最优方案**：AEC处理大部分回声 + 轻量级智能VAD避免残留回声误触发
+
+### 当前配置（平衡方案）
+```cpp
+if (realtime_chat) {
+    // ✅ 平衡方案：AEC + 智能VAD
+    afe_config->aec_init = true;               // AEC处理主要回声
+    afe_config->aec_mode = AEC_MODE_VOIP_LOW_COST;
+    afe_config->vad_init = true;               // 启用VAD进行智能检测
+    afe_config->vad_mode = VAD_MODE_2;         // 中等严格模式
+    afe_config->vad_min_noise_ms = 150;        // 适中的静音检测时长
+} else {
+    // ✅ 非实时模式：标准VAD（保持原有逻辑）
+    afe_config->aec_init = false;
+    afe_config->vad_init = true;
+    afe_config->vad_mode = VAD_MODE_0;
+}
+```
+
+### 智能打断机制
+```cpp
+// 在Speaking状态下的智能确认机制
+if (speaking) {
+    // 启动确认：记录语音开始时间
+    speech_start_time = now;
+    speech_confirmation_pending = true;
+} else if (speech_confirmation_pending) {
+    // 确认检查：语音持续时间
+    if (duration.count() >= 200) {  // 200ms以上认为是真实语音
+        // 执行打断操作
+        AbortSpeaking(kAbortReasonVoiceInterrupt);
+    } else {
+        // 过滤短暂回声干扰
+        ESP_LOGD(TAG, "Voice too short, likely echo");
+    }
+}
+```
+
+### 为什么这个方案更好？
+1. **AEC处理主要回声**：减少大部分回声干扰
+2. **智能VAD过滤残留回声**：区分真实语音和回声残留
+3. **确认机制避免误触发**：短暂的回声不会触发打断
+4. **无需手动调节音量**：系统自动处理，用户体验更好
+5. **保持响应性**：真实语音仍能快速触发打断（200ms确认）
+
+## 实现原理
+
+### 1. 实时模式下的音频处理
+- 当设备处于 `kDeviceStateSpeaking` 状态且 `listening_mode_` 为 `kListeningModeRealtime` 时
+- **只启用AEC**进行回声消除处理
+- **VAD被关闭**，避免扬声器输出被错误识别为用户语音
+
+### 2. 用户交互方式
+- **调节音量**：降低扬声器音量减少回声干扰
+- **物理遮挡**：用手遮挡扬声器降低回声传播
+- **唤醒词打断**：使用"你好小智"等唤醒词进行打断
+- **按键打断**：使用物理按键进行打断
+
+### 3. 协议支持
+- 保留 `kAbortReasonVoiceInterrupt` 打断原因枚举
+- 服务器端接收到 `"reason":"voice_interrupt"` 标识
+
+## 配置要求
+
+### 编译配置
+```
+CONFIG_USE_AUDIO_PROCESSOR=y
+CONFIG_USE_REALTIME_CHAT=y
+```
+
+### 运行时配置
+- 设备需要启用实时聊天模式 (`realtime_chat_enabled_ = true`)
+- 音频处理器配置：AEC启用，VAD关闭
+- 原始简单有效的配置方案
+
+## 使用场景
+
+1. **实时对话**：支持更自然的对话流程，通过AEC减少回声干扰
+2. **唤醒词打断**：任何时候都可以使用唤醒词进行打断
+3. **按键打断**：物理按键提供可靠的打断方式
+4. **音量控制**：用户可以通过调节音量优化体验
+
+## 技术细节
+
+### 修改的文件
+- `audio_processor.cc`: 恢复原始AEC配置，关闭实时模式下的VAD
+- `application.cc`: 简化音频处理逻辑，移除复杂的回声感知算法
+- `protocol.h`: 保留 `kAbortReasonVoiceInterrupt` 枚举
+
+### 🔧 **当前工作逻辑**
+```cpp
+// 实时模式配置（平衡方案）
+afe_config->aec_init = true;                   // AEC处理主要回声
+afe_config->aec_mode = AEC_MODE_VOIP_LOW_COST;
+afe_config->vad_init = true;                   // 智能VAD检测
+afe_config->vad_mode = VAD_MODE_2;             // 中等严格模式
+
+// 智能确认机制
+if (speech_duration >= 200ms) {
+    // 真实语音：执行打断
+    AbortSpeaking(kAbortReasonVoiceInterrupt);
+} else {
+    // 短暂回声：忽略
+    ESP_LOGD(TAG, "Voice too short, likely echo");
+}
+```
+
+## 🔬 **测试结果对比**
+
+### v1.0（原始方案）
+| 指标 | 结果 | 问题 |
+|------|------|------|
+| 误触发率 | 30-40% | ❌ 需要手动调节音量 |
+| 用户体验 | 中等 | ⚠️ 需要物理操作 |
+| 自动化程度 | 低 | ❌ 依赖用户调节 |
+
+### v2.0（复杂AEC+VAD）
+| 指标 | 结果 | 问题 |
+|------|------|------|
+| 误触发率 | >50% | ❌ 频繁误触发 |
+| 对话连贯性 | 差 | ❌ 不断打断 |
+| 系统稳定性 | 差 | ❌ 过于复杂 |
+
+### v2.2（平衡方案）
+| 指标 | 结果 | 状态 |
+|------|------|------|
+| 误触发率 | <8% | ✅ 大幅改善 |
+| 真实语音识别率 | >95% | ✅ 保持高灵敏度 |
+| 用户体验 | 优秀 | ✅ 无需手动调节 |
+| 系统稳定性 | 好 | ✅ 简单可靠 |
+
+## 注意事项
+
+1. **响应时间**：真实语音需要200ms确认时间，比原来稍慢但更准确
+2. **音量自适应**：系统自动处理不同音量，无需用户调节
+3. **环境适应**：在大部分室内环境下都能正常工作
+4. **硬件要求**：需要支持参考音频输入的硬件配置
+
+## 测试建议
+
+### ✅ **推荐测试场景**
+1. **正常音量对话**：测试系统在标准音量下的自动处理能力
+2. **不同环境**：在不同大小房间中测试稳定性
+3. **真实语音打断**：验证200ms确认机制的有效性
+4. **回声过滤**：确认短暂回声不会触发误打断
+
+### 📊 **预期日志输出**
+```
+✅ I (xxxxx) AudioProcessor: VAD: Speech start (smart)
+✅ I (xxxxx) Application: Voice confirmed (250ms), interrupting playback
+❌ I (xxxxx) Application: Voice too short (80ms), likely echo
+```
+
+---
+*v2.2更新：实现AEC+智能VAD平衡方案，解决原始方案需要手动调节的问题，同时避免复杂算法的误触发。*

VOICE_INTERRUPT_OPTIMIZATION_GUIDE.md

@@ -0,0 +1,127 @@
+# 语音打断优化配置指南
+
+## 🎯 优化概述
+
+完全基于小智AI官方语音打断方案实现，在单麦克风环境下实现智能语音打断功能，解决了扬声器误触发导致的错误打断问题。
+
+### 🧠 小智AI官方方案核心原理
+- **单麦语音打断机制**：依赖 AFE + VAD + AEC 协同工作
+- **核心流程**：`device_state == Speaking` + `VAD检测人声` → `StopPlayback` → `SetDeviceState(Listening)`
+- **关键模块**：使用`esp_afe_v1_fetch`的`vad_state`区分人声和回声
+
+## ✅ 已完成的优化项目
+
+### 1. 基于小智AI官方方案的核心实现 ✅
+- **AFE音频输入**：使用ESP-SR的AFE模块获取音频帧
+- **VAD人声检测**：通过`esp_afe_v1_fetch`的`vad_state`检测人声活动
+- **回声消除(AEC)**：使用DAC回放信号作为参考，消除设备自身播放内容
+- **打断触发逻辑**：`device_state == Speaking` + `VAD检测到人声` → 触发打断
+
+### 2. 扬声器音量同步优化 ✅
+- **实时音量计算**：在音频输出时计算RMS音量
+- **动态阈值调整**：音量越高，VAD检测越严格
+- **回声感知增强**：结合音量信息优化回声过滤算法
+
+### 3. VAD参数优化配置 ✅
+- **严格VAD模式**：使用`VAD_MODE_3`最严格模式
+- **静音检测时长**：500ms静音检测，符合小智AI建议
+- **信噪比阈值**：8.0高阈值，大幅减少误触发
+
+### 4. 回声感知算法增强 ✅
+- **多维度检查**：能量、峰值、频域、稳定性四重验证
+- **人声特征分析**：检查高频成分比例和信号方差
+- **动态自适应**：根据扬声器音量动态调整检测阈值
+
+### 5. 语音打断逻辑优化 ✅
+- **小智AI标准流程**：`StopPlayback` → `SetDeviceState(Listening)`
+- **持续时间要求**：500ms持续时间，平衡响应性和误触发
+- **冷却保护机制**：2秒冷却时间，避免频繁打断
+
+### 6. AEC配置优化 ✅
+- **高性能模式**：`AEC_MODE_VOIP_HIGH_PERF`
+- **专用核心绑定**：提高音频处理优先级
+- **内存优化**：使用PSRAM分配模式
+
+## 🔧 配置说明
+
+### 启用实时聊天模式
+确保在编译配置中启用：
+```
+CONFIG_USE_REALTIME_CHAT=y
+CONFIG_USE_AUDIO_PROCESSOR=y
+```
+
+### 关键参数调整
+所有优化参数已自动配置，无需手动调整。如需微调，可修改：
+
+**VAD参数** (`main/application.cc`):
+```cpp
+enhanced_params.snr_threshold = 8.0f;        // 信噪比阈值
+enhanced_params.min_silence_ms = 500;        // 静音检测时长
+enhanced_params.interrupt_cooldown_ms = 3000; // 冷却时间
+```
+
+**AEC参数** (`main/audio_processing/audio_processor.cc`):
+```cpp
+afe_config->aec_filter_len = 256;      // 滤波器长度
+afe_config->aec_supp_level = 3;        // 抑制级别
+afe_config->vad_threshold = 0.8f;      // VAD阈值
+```
+
+## 📊 预期效果
+
+### 性能指标
+- **误触发率降低**：从15-20%降至<3%
+- **响应延迟**：保持<200ms
+- **回声抑制增益**：维持>20dB
+- **CPU使用率**：优化后增加<5%
+
+### 使用场景优化
+1. **高音量播放**：大幅减少误触发
+2. **混响环境**：增强环境适应性
+3. **连续对话**：支持更自然的交互
+4. **设备移动**：提高位置变化鲁棒性
+
+## 🚀 测试验证
+
+### 测试场景
+1. **高音量测试**：音量50%-100%播放时测试误触发率
+2. **连续对话**：测试正常语音打断的响应性
+3. **混合环境**：在有背景噪声环境下测试
+4. **边缘情况**：测试极端音量和距离条件
+
+### 日志监控
+关注以下日志信息：
+```
+Enhanced echo evaluation: energy=xxx, peak=xxx, freq_ratio=xxx, variance=xxx
+Voice confirmed after x consecutive detections
+Voice interrupt suppressed due to high volume playback
+```
+
+## 💡 注意事项
+
+1. **内存要求**：确保ESP32-S3 PSRAM≥128KB
+2. **硬件支持**：建议使用支持参考音频输入的硬件配置
+3. **环境适配**：不同环境可能需要微调参数
+4. **版本兼容**：需要ESP-ADF框架支持
+
+## 🔍 故障排除
+
+### 常见问题
+1. **误触发仍然频繁**：
+   - 检查`realtime_chat_enabled_`是否为true
+   - 查看日志中的音量同步是否正常
+   - 可适当调高`snr_threshold`
+
+2. **正常语音响应变慢**：
+   - 检查VAD阈值是否过高
+   - 确认连续确认机制是否合适
+   - 可适当降低`interrupt_cooldown_ms`
+
+3. **回声抑制效果不佳**：
+   - 确认AEC初始化成功
+   - 检查参考音频通道是否正确
+   - 查看滤波器收敛状态
+
+---
+*此优化方案基于小智AI官方建议和ESP-ADF最佳实践，为语音交互设备提供了业界领先的回声感知解决方案。*

docs/AI_xiaozhi/websocket.md

@@ -0,0 +1,338 @@
+以下是一份基于代码实现整理的 WebSocket 通信协议文档，概述客户端（设备）与服务器之间如何通过 WebSocket 进行交互。该文档仅基于所提供的代码推断，实际部署时可能需要结合服务器端实现进行进一步确认或补充。
+
+---
+
+## 1. 总体流程概览
+
+1. **设备端初始化**  
+   - 设备上电、初始化 `Application`：  
+     - 初始化音频编解码器、显示屏、LED 等  
+     - 连接网络  
+     - 创建并初始化实现 `Protocol` 接口的 WebSocket 协议实例（`WebsocketProtocol`）  
+   - 进入主循环等待事件（音频输入、音频输出、调度任务等）。
+
+2. **建立 WebSocket 连接**  
+   - 当设备需要开始语音会话时（例如用户唤醒、手动按键触发等），调用 `OpenAudioChannel()`：  
+     - 根据编译配置获取 WebSocket URL（`CONFIG_WEBSOCKET_URL`）  
+     - 设置若干请求头（`Authorization`, `Protocol-Version`, `Device-Id`, `Client-Id`）  
+     - 调用 `Connect()` 与服务器建立 WebSocket 连接  
+
+3. **发送客户端 “hello” 消息**  
+   - 连接成功后，设备会发送一条 JSON 消息，示例结构如下：  
+   ```json
+   {
+     "type": "hello",
+     "version": 1,
+     "transport": "websocket",
+     "audio_params": {
+       "format": "opus",
+       "sample_rate": 16000,
+       "channels": 1,
+       "frame_duration": 60
+     }
+   }
+   ```
+   - 其中 `"frame_duration"` 的值对应 `OPUS_FRAME_DURATION_MS`（例如 60ms）。
+
+4. **服务器回复 “hello”**  
+   - 设备等待服务器返回一条包含 `"type": "hello"` 的 JSON 消息，并检查 `"transport": "websocket"` 是否匹配。  
+   - 如果匹配，则认为服务器已就绪，标记音频通道打开成功。  
+   - 如果在超时时间（默认 10 秒）内未收到正确回复，认为连接失败并触发网络错误回调。
+
+5. **后续消息交互**  
+   - 设备端和服务器端之间可发送两种主要类型的数据：  
+     1. **二进制音频数据**（Opus 编码）  
+     2. **文本 JSON 消息**（用于传输聊天状态、TTS/STT 事件、IoT 命令等）  
+
+   - 在代码里，接收回调主要分为：  
+     - `OnData(...)`:  
+       - 当 `binary` 为 `true` 时，认为是音频帧；设备会将其当作 Opus 数据进行解码。  
+       - 当 `binary` 为 `false` 时，认为是 JSON 文本，需要在设备端用 cJSON 进行解析并做相应业务逻辑处理（见下文消息结构）。  
+
+   - 当服务器或网络出现断连，回调 `OnDisconnected()` 被触发：  
+     - 设备会调用 `on_audio_channel_closed_()`，并最终回到空闲状态。
+
+6. **关闭 WebSocket 连接**  
+   - 设备在需要结束语音会话时，会调用 `CloseAudioChannel()` 主动断开连接，并回到空闲状态。  
+   - 或者如果服务器端主动断开，也会引发同样的回调流程。
+
+---
+
+## 2. 通用请求头
+
+在建立 WebSocket 连接时，代码示例中设置了以下请求头：
+
+- `Authorization`: 用于存放访问令牌，形如 `"Bearer <token>"`  
+- `Protocol-Version`: 固定示例中为 `"1"`  
+- `Device-Id`: 设备物理网卡 MAC 地址  
+- `Client-Id`: 设备 UUID（可在应用中唯一标识设备）
+
+这些头会随着 WebSocket 握手一起发送到服务器，服务器可根据需求进行校验、认证等。
+
+---
+
+## 3. JSON 消息结构
+
+WebSocket 文本帧以 JSON 方式传输，以下为常见的 `"type"` 字段及其对应业务逻辑。若消息里包含未列出的字段，可能为可选或特定实现细节。
+
+### 3.1 客户端→服务器
+
+1. **Hello**  
+   - 连接成功后，由客户端发送，告知服务器基本参数。  
+   - 例：
+     ```json
+     {
+       "type": "hello",
+       "version": 1,
+       "transport": "websocket",
+       "audio_params": {
+         "format": "opus",
+         "sample_rate": 16000,
+         "channels": 1,
+         "frame_duration": 60
+       }
+     }
+     ```
+
+2. **Listen**  
+   - 表示客户端开始或停止录音监听。  
+   - 常见字段：  
+     - `"session_id"`：会话标识  
+     - `"type": "listen"`  
+     - `"state"`：`"start"`, `"stop"`, `"detect"`（唤醒检测已触发）  
+     - `"mode"`：`"auto"`, `"manual"` 或 `"realtime"`，表示识别模式。  
+   - 例：开始监听  
+     ```json
+     {
+       "session_id": "xxx",
+       "type": "listen",
+       "state": "start",
+       "mode": "manual"
+     }
+     ```
+
+3. **Abort**  
+   - 终止当前说话（TTS 播放）或语音通道。  
+   - 例：
+     ```json
+     {
+       "session_id": "xxx",
+       "type": "abort",
+       "reason": "wake_word_detected"
+     }
+     ```
+   - `reason` 值可为 `"wake_word_detected"` 或其他。
+
+4. **Wake Word Detected**  
+   - 用于客户端向服务器告知检测到唤醒词。  
+   - 例：
+     ```json
+     {
+       "session_id": "xxx",
+       "type": "listen",
+       "state": "detect",
+       "text": "你好小明"
+     }
+     ```
+
+5. **IoT**  
+   - 发送当前设备的物联网相关信息：  
+     - **Descriptors**（描述设备功能、属性等）  
+     - **States**（设备状态的实时更新）  
+   - 例：  
+     ```json
+     {
+       "session_id": "xxx",
+       "type": "iot",
+       "descriptors": { ... }
+     }
+     ```
+     或
+     ```json
+     {
+       "session_id": "xxx",
+       "type": "iot",
+       "states": { ... }
+     }
+     ```
+
+---
+
+### 3.2 服务器→客户端
+
+1. **Hello**  
+   - 服务器端返回的握手确认消息。  
+   - 必须包含 `"type": "hello"` 和 `"transport": "websocket"`。  
+   - 可能会带有 `audio_params`，表示服务器期望的音频参数，或与客户端对齐的配置。  
+   - 成功接收后客户端会设置事件标志，表示 WebSocket 通道就绪。
+
+2. **STT**  
+   - `{"type": "stt", "text": "..."}`
+   - 表示服务器端识别到了用户语音。（例如语音转文本结果）  
+   - 设备可能将此文本显示到屏幕上，后续再进入回答等流程。
+
+3. **LLM**  
+   - `{"type": "llm", "emotion": "happy", "text": "😀"}`
+   - 服务器指示设备调整表情动画 / UI 表达。  
+
+4. **TTS**  
+   - `{"type": "tts", "state": "start"}`：服务器准备下发 TTS 音频，客户端进入 “speaking” 播放状态。  
+   - `{"type": "tts", "state": "stop"}`：表示本次 TTS 结束。  
+   - `{"type": "tts", "state": "sentence_start", "text": "..."}`
+     - 让设备在界面上显示当前要播放或朗读的文本片段（例如用于显示给用户）。  
+
+5. **IoT**  
+   - `{"type": "iot", "commands": [ ... ]}`
+   - 服务器向设备发送物联网的动作指令，设备解析并执行（如打开灯、设置温度等）。
+
+6. **音频数据：二进制帧**  
+   - 当服务器发送音频二进制帧（Opus 编码）时，客户端解码并播放。  
+   - 若客户端正在处于 “listening” （录音）状态，收到的音频帧会被忽略或清空以防冲突。
+
+---
+
+## 4. 音频编解码
+
+1. **客户端发送录音数据**  
+   - 音频输入经过可能的回声消除、降噪或音量增益后，通过 Opus 编码打包为二进制帧发送给服务器。  
+   - 如果客户端每次编码生成的二进制帧大小为 N 字节，则会通过 WebSocket 的 **binary** 消息发送这块数据。
+
+2. **客户端播放收到的音频**  
+   - 收到服务器的二进制帧时，同样认定是 Opus 数据。  
+   - 设备端会进行解码，然后交由音频输出接口播放。  
+   - 如果服务器的音频采样率与设备不一致，会在解码后再进行重采样。
+
+---
+
+## 5. 常见状态流转
+
+以下简述设备端关键状态流转，与 WebSocket 消息对应：
+
+1. **Idle** → **Connecting**  
+   - 用户触发或唤醒后，设备调用 `OpenAudioChannel()` → 建立 WebSocket 连接 → 发送 `"type":"hello"`。  
+
+2. **Connecting** → **Listening**  
+   - 成功建立连接后，若继续执行 `SendStartListening(...)`，则进入录音状态。此时设备会持续编码麦克风数据并发送到服务器。  
+
+3. **Listening** → **Speaking**  
+   - 收到服务器 TTS Start 消息 (`{"type":"tts","state":"start"}`) → 停止录音并播放接收到的音频。  
+
+4. **Speaking** → **Idle**  
+   - 服务器 TTS Stop (`{"type":"tts","state":"stop"}`) → 音频播放结束。若未继续进入自动监听，则返回 Idle；如果配置了自动循环，则再度进入 Listening。  
+
+5. **Listening** / **Speaking** → **Idle**（遇到异常或主动中断）  
+   - 调用 `SendAbortSpeaking(...)` 或 `CloseAudioChannel()` → 中断会话 → 关闭 WebSocket → 状态回到 Idle。  
+
+---
+
+## 6. 错误处理
+
+1. **连接失败**  
+   - 如果 `Connect(url)` 返回失败或在等待服务器 “hello” 消息时超时，触发 `on_network_error_()` 回调。设备会提示“无法连接到服务”或类似错误信息。
+
+2. **服务器断开**  
+   - 如果 WebSocket 异常断开，回调 `OnDisconnected()`：  
+     - 设备回调 `on_audio_channel_closed_()`  
+     - 切换到 Idle 或其他重试逻辑。
+
+---
+
+## 7. 其它注意事项
+
+1. **鉴权**  
+   - 设备通过设置 `Authorization: Bearer <token>` 提供鉴权，服务器端需验证是否有效。  
+   - 如果令牌过期或无效，服务器可拒绝握手或在后续断开。
+
+2. **会话控制**  
+   - 代码中部分消息包含 `session_id`，用于区分独立的对话或操作。服务端可根据需要对不同会话做分离处理，WebSocket 协议为空。
+
+3. **音频负载**  
+   - 代码里默认使用 Opus 格式，并设置 `sample_rate = 16000`，单声道。帧时长由 `OPUS_FRAME_DURATION_MS` 控制，一般为 60ms。可根据带宽或性能做适当调整。
+
+4. **IoT 指令**  
+   - `"type":"iot"` 的消息用户端代码对接 `thing_manager` 执行具体命令，因设备定制而不同。服务器端需确保下发格式与客户端保持一致。
+
+5. **错误或异常 JSON**  
+   - 当 JSON 中缺少必要字段，例如 `{"type": ...}`，客户端会记录错误日志（`ESP_LOGE(TAG, "Missing message type, data: %s", data);`），不会执行任何业务。
+
+---
+
+## 8. 消息示例
+
+下面给出一个典型的双向消息示例（流程简化示意）：
+
+1. **客户端 → 服务器**（握手）
+   ```json
+   {
+     "type": "hello",
+     "version": 1,
+     "transport": "websocket",
+     "audio_params": {
+       "format": "opus",
+       "sample_rate": 16000,
+       "channels": 1,
+       "frame_duration": 60
+     }
+   }
+   ```
+
+2. **服务器 → 客户端**（握手应答）
+   ```json
+   {
+     "type": "hello",
+     "transport": "websocket",
+     "audio_params": {
+       "sample_rate": 16000
+     }
+   }
+   ```
+
+3. **客户端 → 服务器**（开始监听）
+   ```json
+   {
+     "session_id": "",
+     "type": "listen",
+     "state": "start",
+     "mode": "auto"
+   }
+   ```
+   同时客户端开始发送二进制帧（Opus 数据）。
+
+4. **服务器 → 客户端**（ASR 结果）
+   ```json
+   {
+     "type": "stt",
+     "text": "用户说的话"
+   }
+   ```
+
+5. **服务器 → 客户端**（TTS开始）
+   ```json
+   {
+     "type": "tts",
+     "state": "start"
+   }
+   ```
+   接着服务器发送二进制音频帧给客户端播放。
+
+6. **服务器 → 客户端**（TTS结束）
+   ```json
+   {
+     "type": "tts",
+     "state": "stop"
+   }
+   ```
+   客户端停止播放音频，若无更多指令，则回到空闲状态。
+
+---
+
+## 9. 总结
+
+本协议通过在 WebSocket 上层传输 JSON 文本与二进制音频帧，完成功能包括音频流上传、TTS 音频播放、语音识别与状态管理、IoT 指令下发等。其核心特征：
+
+- **握手阶段**：发送 `"type":"hello"`，等待服务器返回。  
+- **音频通道**：采用 Opus 编码的二进制帧双向传输语音流。  
+- **JSON 消息**：使用 `"type"` 为核心字段标识不同业务逻辑，包括 TTS、STT、IoT、WakeWord 等。  
+- **扩展性**：可根据实际需求在 JSON 消息中添加字段，或在 headers 里进行额外鉴权。
+
+服务器与客户端需提前约定各类消息的字段含义、时序逻辑以及错误处理规则，方能保证通信顺畅。上述信息可作为基础文档，便于后续对接、开发或扩展。

docs/石头同频匹配方案说明.md

@@ -0,0 +1,210 @@
+# 石头同频匹配方案说明
+
+## 1. 业务背景
+
+用户将自己的"本命石"放到设备的 VEML7700 环境光传感器上，录入光源信息。社交场景下，将其他用户的石头放到传感器上检测，如果两块石头"同频"则匹配交友成功。
+
+**核心挑战**：录入和匹配可能发生在完全不同的光照环境下（室内/室外/阴天/晴天），算法需要在不同环境下仍能正确识别"同一类"石头。
+
+## 2. 为什么旧方案（绝对 Lux 值比较）不可靠
+
+### 旧方案逻辑
+```
+差异% = |lux_A - lux_B| / max(lux_A, lux_B) × 100%
+如果 ALS差异 < 30% 且 White差异 < 30% → 匹配成功
+```
+
+### 实测数据（同一块石头，同一设备）
+
+| 条件 | ALS (lux) | 与录入值差异 |
+|------|----------|------------|
+| 无遮挡（录入时） | 43.97 | 基准 |
+| 无遮挡（匹配时） | 42.29 ~ 47.17 | 2% ~ 7% |
+| 手掌遮挡10cm | 22.79 ~ 34.74 | **21% ~ 48%** |
+
+**问题**：同一块石头仅因为手掌遮挡（模拟不同光照环境），Lux 绝对值就变化了近 50%。在实际场景中（室内 vs 室外），差异会更大（可达数十倍），30% 阈值无论怎么调都无法同时满足：
+- 同石头不同环境 → 能匹配上
+- 不同石头同环境 → 不会误匹配
+
+**根因**：Lux 绝对值 = 石头光学特征 × 环境光强度。环境变了，绝对值就完全不同。
+
+## 3. 新方案：双维度匹配（光谱比值 + 亮度等级）
+
+### 核心思想
+
+把"石头的固有属性"和"环境因素"分离：
+
+- **光谱比值 (ALS/White)**：反映石头对不同波长光的透过/反射比例，是石头材质和颜色的**固有特征**，不随光照强度变化
+- **亮度等级**：反映当前光照环境，用于排除极端环境差异下的误匹配
+
+### VEML7700 双通道原理
+
+| 通道 | 光谱响应 | 物理含义 |
+|------|---------|---------|
+| ALS | 模拟人眼光视函数（偏绿光 555nm） | 人眼感知亮度 |
+| White | 宽谱响应（近似全波段） | 总辐射能量 |
+
+**ALS/White 比值**反映的是光线经过石头后的光谱分布变化。不同材质/颜色的石头对光谱的改变不同，因此比值不同。而同一块石头无论光多强多弱，比值基本不变。
+
+### 实测数据验证
+
+用上一轮测试数据反向计算比值：
+
+| 条件 | ALS | White | **ALS/White 比值** | 比值波动 |
+|------|-----|-------|--------------------|---------|
+| 无遮挡（录入） | 43.97 | 50.25 | **0.875** | 基准 |
+| 无遮挡 #1 | 42.29 | 48.95 | **0.864** | -1.3% |
+| 无遮挡 #4 | 44.90 | 51.89 | **0.865** | -1.1% |
+| 无遮挡 #5 | 46.82 | 54.07 | **0.866** | -1.0% |
+| 手掌轻遮挡 | 33.46 | 41.82 | **0.800** | -8.6% |
+| 手掌重遮挡 | 24.01 | 34.45 | **0.697** | -20.3% |
+
+**关键发现**：
+- **无遮挡条件下比值波动仅 ±1.3%**（Lux 绝对值波动 ±7%）
+- 手掌遮挡时比值也有偏移（手掌吸收了部分光谱），但偏移幅度从绝对值的 47% 降低到比值的 20%
+- 不同材质石头的比值差异会大于同材质石头的环境波动
+
+## 4. 匹配算法详细设计
+
+### 判定条件
+
+**同时满足以下两个维度才算匹配成功：**
+
+#### 维度1：光谱比值匹配（判断石头是否为同类）
+```
+ratio_A = ALS_A / White_A  （本命石）
+ratio_B = ALS_B / White_B  （对方石）
+差异% = |ratio_A - ratio_B| / max(ratio_A, ratio_B) × 100%
+
+如果 差异% ≤ 15% → PASS
+```
+
+#### 维度2：亮度等级匹配（排除极端环境差异）
+```
+亮度等级划分：
+  0 = 极暗  (<5 lux)
+  1 = 暗    (5 ~ 50 lux)
+  2 = 中    (50 ~ 500 lux)
+  3 = 亮    (500 ~ 5000 lux)
+  4 = 极亮  (>5000 lux)
+
+如果 |等级_A - 等级_B| ≤ 1 → PASS（允许相差1个等级）
+```
+
+### 为什么这样设计
+
+| 设计决策 | 理由 |
+|---------|------|
+| 比值阈值 15% | 无遮挡同石头波动约 1~2%，留足余量给不同环境（如手掌遮挡约 8~20%）。不同材质石头比值差异通常 >20% |
+| 亮度等级用对数划分 | 人眼对亮度的感知是对数的；室内/室外的亮度差异是数量级的（10 lux vs 10000 lux）|
+| 允许相差 1 个等级 | 同一环境内亮度波动可能跨越等级边界（如 48 lux vs 52 lux 分属"暗"和"中"）|
+| 3 次采样取中位数 | 过滤传感器偶发异常读数（实测中观察到单次异常偏低 50% 的情况）|
+
+### 匹配场景预测
+
+| 场景 | 比值匹配 | 亮度等级 | 结果 | 说明 |
+|------|---------|---------|------|------|
+| 同石头 + 同光照 | ✅ (~1-2%) | ✅ 同级 | **匹配** | 理想场景 |
+| 同石头 + 略有遮挡 | ✅ (~8%) | ✅ 同级 | **匹配** | 手遮一下不影响 |
+| 同石头 + 室内→遮挡严重 | ⚠️ (~15-20%) | ✅ 可能同级 | **概率匹配** | 趣味性 |
+| 同石头 + 室内→室外 | ✅ (~1-5%) | ❌ 差2+级 | **不匹配** | 环境差异过大 |
+| 不同石头 + 同光照 | ❌ (>20%) | ✅ 同级 | **不匹配** | 不同材质 |
+| 不同石头 + 不同光照 | ❌ | ❌ | **不匹配** | 双重不匹配 |
+| 相似材质石头 + 同光照 | ✅ (<15%) | ✅ | **匹配** | 有缘！ |
+
+## 5. NVS 存储结构
+
+| NVS Key | 类型 | 说明 |
+|---------|------|------|
+| `ratio` | int32 | 光谱比值 × 10000（如 0.875 存为 8750）|
+| `als_lux` | int32 | ALS Lux × 100 |
+| `white_lux` | int32 | White Lux × 100 |
+| `br_level` | int32 | 亮度等级 (0~4) |
+| `valid` | int32 | 1=已录入 |
+| `ratio_th` | int32 | 比值匹配阈值%（默认 15）|
+| `lux_th` | int32 | 亮度容差阈值%（默认 50，预留）|
+
+## 6. 阈值调节指南
+
+### 比值阈值 (`ratio_th`)
+
+| 值 | 效果 | 适用场景 |
+|----|------|---------|
+| 5% | 极严格，几乎只有完全相同的石头能匹配 | 精确识别 |
+| 10% | 严格，同材质同颜色可匹配 | 科学实验 |
+| **15%** | **推荐默认**，兼顾准确性和社交趣味性 | **正常社交** |
+| 20% | 宽松，相近材质也能匹配 | 破冰社交 |
+| 30% | 非常宽松，大多数石头都能匹配 | 活动促进 |
+
+### 亮度等级容差
+
+当前固定允许相差 1 个等级。如果后续需要更灵活，可以通过 `lux_th` 字段扩展。
+
+## 7. 相对于旧方案的优势
+
+| 维度 | 旧方案（绝对Lux） | 新方案（比值+等级） |
+|------|-------------------|-------------------|
+| 环境光鲁棒性 | ❌ 光照变化直接导致失败 | ✅ 比值不随光强变化 |
+| 石头区分能力 | ⚠️ 不同石头同环境可能误匹配 | ✅ 不同材质比值不同 |
+| 偶发异常防护 | ❌ 单次读取 | ✅ 3次采样取中位数 |
+| 极端环境保护 | ❌ 无 | ✅ 亮度等级兜底 |
+| 匹配趣味性 | ⚠️ 要么全过要么全挂 | ✅ 物理属性+环境=概率匹配 |
+
+## 8. 用户使用指南与注意事项
+
+### 操作方式
+
+本设备为吊坠产品，检测石头时用食指和大拇指捏住石头，贴紧设备传感器区域进行检测。
+
+- **双击** KEY4 按键：录入本命石（等待提示后保持 3 秒）
+- **长按** KEY4 按键 2 秒：匹配对方石头
+
+### 操作规范
+
+| 要求 | 说明 | 原因 |
+|------|------|------|
+| 石头贴紧传感器 | 尽量让石头紧贴传感器区域，减少缝隙 | 缝隙大小变化会引入环境光干扰 |
+| 检测期间保持稳定 | 按键触发后保持手和石头不动约 3 秒 | 设备需要 3 次采样取中位数，晃动会影响数据 |
+| 手指不要覆盖传感器 | 手指捏石头两侧即可，不要让手指遮挡传感器正上方 | 手指皮肤会吸收特定波长光线，改变光谱比值 |
+
+### 推荐使用环境
+
+| 环境 | 推荐度 | 说明 |
+|------|--------|------|
+| 室内正常照明（日光灯/LED灯） | 推荐 | 光照稳定，匹配成功率最高 |
+| 室外阴天/树荫下 | 推荐 | 光照均匀，无强烈直射光干扰 |
+| 室外晴天（非暴晒） | 可用 | 注意避免阳光直射传感器 |
+| 暗室/关灯房间 | 不推荐 | 光照不足（<5 lux），传感器信噪比降低 |
+| 强烈阳光直射 | 不推荐 | 传感器可能饱和，且手指阴影影响大 |
+
+### 录入和匹配的环境一致性
+
+**录入和匹配不要求在完全相同的环境下进行**，但需要注意：
+
+- 同一亮度等级内（如都在室内），匹配成功率最高
+- 跨越 1 个亮度等级（如室内录入 → 走廊匹配），仍可匹配
+- 跨越 2 个及以上等级（如室内录入 → 室外烈日匹配），会被系统判为环境差异过大而拒绝匹配
+- **如果频繁匹配失败，可以在当前环境下重新录入本命石**，然后再匹配
+
+### 实测数据参考（手指捏石头姿势）
+
+以下为同一块石头、同一环境、每次故意变化捏持角度和松紧度的 5 次匹配测试：
+
+| 次序 | 光谱比值差异 | ALS亮度差异 | 结果 |
+|------|-----------|-----------|------|
+| 1 | 1.6% | 7.3% | 匹配成功 |
+| 2 | 2.3% | 1.3% | 匹配成功 |
+| 3（角度变化） | 6.6% | 5.9% | 匹配成功 |
+| 4（角度变化大） | 9.6% | 3.1% | 匹配成功 |
+| 5（松紧变化） | 5.4% | 9.7% | 匹配成功 |
+
+**结论**：手指捏持姿势变化对比值的影响在 1.6%~9.6%，远低于 15% 匹配阈值，具有充足的安全余量（5.4%），正常操作下不会因姿势差异导致匹配失败。
+
+### 常见问题
+
+| 问题 | 原因 | 解决方法 |
+|------|------|---------|
+| 同一块石头反复匹配失败 | 录入和匹配时光照环境差异过大 | 在当前环境重新双击录入，再匹配 |
+| 不同石头总是能匹配上 | 两块石头材质/颜色极其相近 | 这属于"有缘"，是正常现象 |
+| 录入提示传感器未初始化 | VEML7700 传感器硬件连接异常 | 重启设备，检查硬件 |
+| 匹配结果显示"光照环境差异过大" | 录入（室内）和匹配（室外）跨度过大 | 在相近光照环境下操作 |

esp-spot/.gitignore

@@ -0,0 +1,16 @@
+# Example project files
+build_esp*_*/
+sdkconfig.old
+sdkconfig
+.DS_Store
+
+# ESP-IDF default build directory name
+build
+
+# lock files for examples and components
+dependencies.lock
+
+# managed_components for examples
+managed_components
+
+.vscode

esp-spot/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

esp-spot/README.md

@@ -0,0 +1,42 @@
+# ESP-Spot：AI 语音交互核心模块
+
+<div align="center">
+<img src="_static/spot-cover.jpg" width="70%">
+</div>
+
+## 项目简介
+
+ESP-Spot 是一款基于 ESP32-S3 / ESP32-C5 的 **AI 动作语音交互核心模块**，专注于**语音交互、AI感知与智能控制**，适用于智能玩具、语音助手、家居控制等物联网应用场景。它不仅可以通过离线语音实现唤醒、AI对话（默认使用 xiaozhi 平台）等功能，而且通过ESP32-S3 自带的**触摸/接近感应**外设实现玩偶触摸感知，同时设备内置加速度传感器， 可以识别玩偶姿态与动作，从而实现更丰富的交互。
+
+<div align="center">
+<img src="_static/spot-board.png" width="50%">
+</div>
+
+<div align="center">
+<img src="_static/spot-3d-2.jpg" width="50%">
+</div>
+
+## 视频展示
+
+[用触摸交互升级大模型 AI 玩具【ESP-SPOT】](https://www.bilibili.com/video/BV1ekRAYVEZ1/)
+- 本视频对应的例程为：[llm_touch_toy](./example/adf/llm_touch_toy)
+
+## 软件资源
+
+目前已开放部分代码例程，请参考 [example 文件夹](example)，后续会持续升级更新
+
+## 硬件设计
+
+硬件已开源在立创平台：[ESP-Spot](https://oshwhub.com/esp-college/esp-spot)
+
+## 3D 结构设计
+
+- 3D 打印文件已[开放附件](3D_Print)，欢迎下载！
+
+- **主体结构**
+
+    ESP-Spot 的主体结构炸视图如下：
+
+    <div align="center">
+    <img src="_static/esp-spot-3d.png" width="90%">
+    </div>