Merge pull request #3295 from xinnan-tech/platform/m0-development-plan

docs: define unified FastAPI delivery plan

.dockerignore

@@ -4,4 +4,23 @@ __pycache__
 .env
 Dockerfile
 tmp/
-data/
+data/
+
+# Repository-local runtimes and test/build products are several gigabytes and
+# are never inputs to either manager-api-fastapi image.
+.runtime/
+.venv-*/
+**/.venv/
+**/.test-runtime/
+**/.pytest_cache/
+**/.mypy_cache/
+**/.ruff_cache/
+**/node_modules/
+**/dist/
+**/target/
+**/uploadfile/
+
+# Runtime state and local model assets must not enter the Docker build context.
+main/xiaozhi-server/mysql/
+main/xiaozhi-server/models/
+main/xiaozhi-server/data/

.github/PULL_REQUEST_TEMPLATE/unified-platform.md

@@ -0,0 +1,63 @@
+## 计划工作包
+
+- 里程碑：M?
+- 计划 PR：P??
+- 负责人角色：
+- 依赖 PR/Commit：
+- 目标分支：`refactor/unified-fastapi-platform`
+
+## 用户可见结果
+
+<!-- 描述完成后用户、设备或运维可以观察到的结果。 -->
+
+## 范围
+
+- 包含：
+- 不包含：
+- 临时文件所有权：
+
+## 契约影响
+
+- [ ] 不改变公开契约
+- [ ] REST API
+- [ ] OTA/设备鉴权
+- [ ] WebSocket/音频/MQTT 帧
+- [ ] 数据库/Redis/文件
+- [ ] Provider 配置或结果
+
+说明：
+
+## 验证证据
+
+```text
+# 列出可重复执行的命令及结果，不要只写“测试通过”。
+```
+
+- [ ] 相关 Tier A 门禁通过
+- [ ] 相关隔离集成/协议/差分通过
+- [ ] 文档和生成产物一致
+- [ ] 没有未解释的 skip、xfail 或 warning 增长
+
+## 风险与回滚
+
+- 风险登记项：
+- 失败表现：
+- 回滚方式：
+- 未执行项目及原因：
+
+## 审阅重点
+
+- [ ] 兼容性
+- [ ] 安全/密钥
+- [ ] 并发/取消/资源释放
+- [ ] 数据迁移
+- [ ] 部署/可观测性
+- [ ] 测试证据完整性
+
+## 合并检查
+
+- [ ] 已同步最新目标分支
+- [ ] 本 PR 的目标不是 `main`
+- [ ] 实现者与 Reviewer 不是同一角色
+- [ ] PR 只包含一个计划工作包或可独立回滚切片
+- [ ] 路线图状态和证据链接将在合并后更新

.gitignore

@@ -112,12 +112,17 @@ celerybeat.pid
 # Environments
 .env
 .venv
+/.venv-*/
 env/
 venv/
 ENV/
 env.bak/
 venv.bak/
 
+# Repository-local runtimes and package-manager caches
+/.runtime/
+/main/manager-web/.npm-cache/
+
 # Spyder project settings
 .spyderproject
 .spyproject
@@ -149,6 +154,7 @@ tmp
 .history
 .DS_Store
 main/xiaozhi-server/data
+main/xiaozhi-server/.claude
 
 main/manager-web/node_modules
 .config.yaml
@@ -186,4 +192,8 @@ uploadfile
 !main/manager-mobile/**/env/
 !main/manager-mobile/**/.env*
 !main/manager-mobile/**/*.json
-!main/xiaozhi-server/**/*.json
+!main/xiaozhi-server/**/*.json
+!main/digital-human/**/*.json
+main/digital-human/wakeword_runtime/models
+main/digital-human/wakeword_runtime/sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01
+sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01.tar.bz2

README.md

@@ -18,10 +18,10 @@
 
 <p align="center">
   <a href="./README.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-DBEDFA"></a>
-  <a href="./README_en.md"><img alt="README in English" src="https://img.shields.io/badge/English-DFE0E5"></a>
+  <a href="./docs/readme/README_en.md"><img alt="README in English" src="https://img.shields.io/badge/English-DFE0E5"></a>
-  <a href="./README_vi.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/Tiếng Việt-DFE0E5"></a>
+  <a href="./docs/readme/README_vi.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/Tiếng Việt-DFE0E5"></a>
-  <a href="./README_de.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-DFE0E5"></a>
+  <a href="./docs/readme/README_de.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-DFE0E5"></a>
-  <a href="./README_pt_BR.md"><img alt="Português (Brasil)" src="https://img.shields.io/badge/Português (Brasil)-DFE0E5"></a>
+  <a href="./docs/readme/README_pt_BR.md"><img alt="Português (Brasil)" src="https://img.shields.io/badge/Português (Brasil)-DFE0E5"></a>
   <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/releases">
     <img alt="GitHub Contributors" src="https://img.shields.io/github/v/release/xinnan-tech/xiaozhi-esp32-server?logo=docker" />
   </a>
@@ -53,113 +53,98 @@ Spearheaded by Professor Siyuan Liu's Team (South China University of Technology
 <table>
   <tr>
     <td>
-        <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
-         <picture>
+        <picture>
-           <img alt="响应速度感受" src="docs/images/demo9.png" />
+          <img alt="响应速度感受" src="docs/images/demo9.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1vchQzaEse" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1vchQzaEse" target="_blank">
-         <picture>
+        <picture>
-           <img alt="速度优化秘诀" src="docs/images/demo6.png" />
+          <img alt="速度优化秘诀" src="docs/images/demo6.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1C1tCzUEZh" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1WEcxzFEAT" target="_blank">
-         <picture>
+        <picture>
-           <img alt="复杂医疗场景" src="docs/images/demo1.png" />
+          <img alt="小智数字人 支持语音唤醒" src="docs/images/demo8.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1CKVz6UEuB" target="_blank">
-         <picture>
+        <picture>
-           <img alt="MQTT指令下发" src="docs/images/demo4.png" />
+          <img alt="设备呼叫设备，打电话" src="docs/images/demo0.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1C1tCzUEZh" target="_blank">
-         <picture>
+        <picture>
-           <img alt="声纹识别" src="docs/images/demo14.png" />
+          <img alt="复杂医疗场景" src="docs/images/demo1.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
   </tr>
   <tr>
     <td>
-        <a href="https://www.bilibili.com/video/BV1pNXWYGEx1" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
-         <picture>
+        <picture>
-           <img alt="控制家电开关" src="docs/images/demo5.png" />
+          <img alt="播放音乐查询天气播报新闻" src="docs/images/demo7.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
-         <picture>
-           <img alt="MCP接入点" src="docs/images/demo13.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-      <a href="https://www.bilibili.com/video/BV1TJ7WzzEo6" target="_blank">
-         <picture>
-           <img alt="多指令任务" src="docs/images/demo11.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
-         <picture>
-           <img alt="播放音乐" src="docs/images/demo7.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1Z8XuYZEAS" target="_blank">
-         <picture>
-           <img alt="天气插件" src="docs/images/demo8.png" />
-         </picture>
-        </a>
-    </td>
-  </tr>
-  <tr>
     <td>
       <a href="https://www.bilibili.com/video/BV12J7WzBEaH" target="_blank">
-         <picture>
+        <picture>
-           <img alt="实时打断" src="docs/images/demo10.png" />
+          <img alt="实时打断" src="docs/images/demo10.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
       <a href="https://www.bilibili.com/video/BV1Co76z7EvK" target="_blank">
-         <picture>
+        <picture>
-           <img alt="拍照识物品" src="docs/images/demo12.png" />
+          <img alt="拍照识物品" src="docs/images/demo12.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1pNXWYGEx1" target="_blank">
-         <picture>
+        <picture>
-           <img alt="自定义音色" src="docs/images/demo2.png" />
+          <img alt="控制家电开关" src="docs/images/demo5.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV12yA2egEaC" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1TJ7WzzEo6" target="_blank">
-         <picture>
+        <picture>
-           <img alt="使用粤语交流" src="docs/images/demo3.png" />
+          <img alt="多指令任务" src="docs/images/demo11.png" /></picture>
-         </picture>
+      </a>
-        </a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
+        <picture>
+          <img alt="MCP接入点" src="docs/images/demo13.png" /></picture>
+      </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV17LXWYvENb" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
-         <picture>
+        <picture>
-           <img alt="播报新闻" src="docs/images/demo0.png" />
+          <img alt="MQTT指令下发" src="docs/images/demo4.png" /></picture>
-         </picture>
+      </a>
-        </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
+        <picture>
+          <img alt="声纹识别" src="docs/images/demo14.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
+        <picture>
+          <img alt="自定义音色" src="docs/images/demo2.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV12yA2egEaC" target="_blank">
+        <picture>
+          <img alt="使用粤语交流" src="docs/images/demo3.png" /></picture>
+      </a>
     </td>
   </tr>
 </table>
@@ -214,8 +199,8 @@ Websocket接口地址: wss://2662r3426b.vicp.fun/xiaozhi/v1/
 |:---:|:---:|:---:|
 | ASR(语音识别) | FunASR(本地) | 👍XunfeiStreamASR(讯飞流式) |
 | LLM(大模型) | glm-4-flash(智谱) | 👍qwen-flash(阿里百炼) |
-| VLLM(视觉大模型) | glm-4v-flash(智谱) | 👍qwen2.5-vl-3b-instructh(阿里百炼) |
+| VLLM(视觉大模型) | glm-4v-flash(智谱) | 👍qwen3.5-flash(阿里百炼) |
-| TTS(语音合成) | ✅LinkeraiTTS(灵犀流式) | 👍HuoshanDoubleStreamTTS(火山流式) |
+| TTS(语音合成) | EdgeTTS(微软) | 👍HuoshanDoubleStreamTTS(火山流式) |
 | Intent(意图识别) | function_call(函数调用) | function_call(函数调用) |
 | Memory(记忆功能) | mem_local_short(本地短期记忆） | mem_local_short（本地短期记忆） |
 
@@ -226,7 +211,7 @@ Websocket接口地址: wss://2662r3426b.vicp.fun/xiaozhi/v1/
 
 | 工具名称 | 位置 | 使用方法 | 功能说明 |
 |:---:|:---|:---:|:---:|
-| 音频交互测试工具 | main》xiaozhi-server》test》test_page.html | 使用谷歌浏览器直接打开 | 测试音频播放和接收功能，验证Python端音频处理是否正常 |
+| 音频交互测试工具 | main》digital-human》index.html | 在 `main/digital-human` 执行 `python start.py` 后访问 `http://127.0.0.1:8006/index.html` | 测试音频播放和接收功能，验证Python端音频处理是否正常 |
 | 模型响应测试工具 | main》xiaozhi-server》performance_tester.py | 执行 `python performance_tester.py` | 测试ASR(语音识别)、LLM(大模型)、VLLM(视觉模型)、TTS(语音合成)三个核心模块的响应速度 |
 
 > 💡 提示：测试模型速度时，只会测试配置了密钥的模型。

docs/Deployment.md

@@ -241,7 +241,7 @@ LLM:
 250427 13:04:20[0.3.11_SiFuChTTnofu][__main__]-INFO-OTA接口是           http://192.168.4.123:8003/xiaozhi/ota/
 250427 13:04:20[0.3.11_SiFuChTTnofu][__main__]-INFO-Websocket地址是     ws://192.168.4.123:8000/xiaozhi/v1/
 250427 13:04:20[0.3.11_SiFuChTTnofu][__main__]-INFO-=======上面的地址是websocket协议地址，请勿用浏览器访问=======
-250427 13:04:20[0.3.11_SiFuChTTnofu][__main__]-INFO-如想测试websocket请用谷歌浏览器打开test目录下的test_page.html
+250427 13:04:20[0.3.11_SiFuChTTnofu][__main__]-INFO-如想测试websocket请启动digital-human模块，打开浏览器交互测试
 250427 13:04:20[0.3.11_SiFuChTTnofu][__main__]-INFO-=======================================================
 ```
 

docs/Deployment_all.md

@@ -198,7 +198,7 @@ docker logs -f xiaozhi-esp32-server
 ```
 25-02-23 12:01:09[core.websocket_server] - INFO - Websocket地址是      ws://xxx.xx.xx.xx:8000/xiaozhi/v1/
 25-02-23 12:01:09[core.websocket_server] - INFO - =======上面的地址是websocket协议地址，请勿用浏览器访问=======
-25-02-23 12:01:09[core.websocket_server] - INFO - 如想测试websocket请用谷歌浏览器打开test目录下的test_page.html
+25-02-23 12:01:09[core.websocket_server] - INFO - 如想测试websocket请启动digital-human模块，打开浏览器交互测试
 25-02-23 12:01:09[core.websocket_server] - INFO - =======================================================
 ```
 
@@ -418,7 +418,7 @@ manager-api:
   secret: 12345678-xxxx-xxxx-xxxx-123456789000
 ```
 
-## 5.运行项目
+## 9.运行项目
 
 ```
 # 确保在xiaozhi-server目录下执行
@@ -431,7 +431,7 @@ python app.py
 ```
 25-02-23 12:01:09[core.websocket_server] - INFO - Server is running at ws://xxx.xx.xx.xx:8000/xiaozhi/v1/
 25-02-23 12:01:09[core.websocket_server] - INFO - =======上面的地址是websocket协议地址，请勿用浏览器访问=======
-25-02-23 12:01:09[core.websocket_server] - INFO - 如想测试websocket请用谷歌浏览器打开test目录下的test_page.html
+25-02-23 12:01:09[core.websocket_server] - INFO - 如想测试websocket请启动digital-human模块，打开浏览器交互测试
 25-02-23 12:01:09[core.websocket_server] - INFO - =======================================================
 ```
 

docs/FAQ.md

@@ -40,8 +40,8 @@ conda install conda-forge::ffmpeg
 |:---:|:---:|:---:|
 | ASR(语音识别) | FunASR(本地) | 👍XunfeiStreamASR(讯飞流式) |
 | LLM(大模型) | glm-4-flash(智谱) | 👍qwen-flash(阿里百炼) |
-| VLLM(视觉大模型) | glm-4v-flash(智谱) | 👍qwen2.5-vl-3b-instructh(阿里百炼) |
+| VLLM(视觉大模型) | glm-4v-flash(智谱) | 👍qwen3.5-flash(阿里百炼) |
-| TTS(语音合成) | ✅LinkeraiTTS(灵犀流式) | 👍HuoshanDoubleStreamTTS(火山流式) |
+| TTS(语音合成) | EdgeTTS(微软) | 👍HuoshanDoubleStreamTTS(火山流式) |
 | Intent(意图识别) | function_call(函数调用) | function_call(函数调用) |
 | Memory(记忆功能) | mem_local_short(本地短期记忆） | mem_local_short（本地短期记忆） |
 
@@ -65,13 +65,14 @@ VAD:
 3、[如何部署MQTT网关开启MQTT+UDP协议](./mqtt-gateway-integration.md)<br/>
 4、[如何自动拉取本项目最新代码自动编译和启动](./dev-ops-integration.md)<br/>
 5、[如何与Nginx集成](https://github.com/xinnan-tech/xiaozhi-esp32-server/issues/791)<br/>
+6、[修改代码后怎么编译自己的Docker镜像](./docker-build.md)<br/>
 
-### 9、编译固件相关教程
+### 8、编译固件相关教程
 1、[如何自己编译小智固件](./firmware-build.md)<br/>
 2、[如何基于虾哥编译好的固件修改OTA地址](./firmware-setting.md)<br/>
 3、[单模块部署如何配置固件OTA自动升级](./ota-upgrade-guide.md)<br/>
 
-### 10、拓展相关教程
+### 9、拓展相关教程
 1、[如何开启手机号码注册智控台](./ali-sms-integration.md)<br/>
 2、[如何集成HomeAssistant实现智能家居控制](./homeassistant-integration.md)<br/>
 3、[如何开启视觉模型实现拍照识物](./mcp-vision-integration.md)<br/>
@@ -83,6 +84,13 @@ VAD:
 9、[知识库ragflow集成指南](./ragflow-integration.md)<br/>
 10、[如何部署上下文源](./context-provider-integration.md)<br/>
 11、[如何集成PowerMem智能记忆](./powermem-integration.md)<br/>
+12、[如何配置天气插件查询天气](./weather-integration.md)<br/>
+13、[如何开启设备呼叫插件](./device-call-guide.md)<br/>
+14、[如何开启联网搜索功能](./web-search-integration.md)<br/>
+
+### 10、数字人相关教程
+1、[数字人digital-human启动方法](./digital-human-wakeword.md)<br/>
+2、[如何在N100迷你主机上部署数字人digital-human](./all-in-one-digital-human-setup.md)<br/>
 
 ### 11、语音克隆、本地语音部署相关教程
 1、[如何在智控台克隆音色](./huoshan-streamTTS-voice-cloning.md)<br/>

docs/all-in-one-digital-human-setup.md

@@ -0,0 +1,442 @@
+# 一体机数字人配置指南
+
+本项目用于在 x86 架构设备（如迷你主机、工控机、普通电脑等）上部署一套完整的数字人展示系统，实现以下功能：
+- 开机自动进入 Kiosk 全屏浏览器，展示指定网页
+- 后台运行唤醒词检测服务，支持语音交互
+
+> **说明**：本文档以 **Intel N100 迷你主机（天虹 QN10-100B4）** 为例进行部署演示，其他 x86 设备可参考调整（注意网络配置和声卡设备差异）。
+
+## 适用环境
+
+| 项目 | 说明 |
+|------|------|
+| 示例硬件 | 天虹 QN10-100B4（Intel N100） |
+| 操作系统 | Ubuntu 24.04 LTS (Noble Numbat) |
+| 示例用户 | xz（请根据实际情况替换） |
+| 网络 | Wi-Fi 连接，固定 IP（可按需改为有线） |
+
+## 部署流程
+
+1. 系统初始化（换源、连网）
+2. 安装图形组件与 Kiosk 浏览器
+3. 配置自动登录与图形界面
+4. 部署唤醒词服务（Python 环境 + 麦克风）
+5. 优化开机速度与隐藏启动信息
+
+---
+
+
+### 系统初始化（换源、连网）
+
+```
+sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
+
+sudo tee /etc/apt/sources.list > /dev/null <<EOF
+deb http://mirrors.aliyun.com/ubuntu/ noble main restricted universe multiverse
+# deb-src http://mirrors.aliyun.com/ubuntu/ noble main restricted universe multiverse
+
+deb http://mirrors.aliyun.com/ubuntu/ noble-security main restricted universe multiverse
+# deb-src http://mirrors.aliyun.com/ubuntu/ noble-security main restricted universe multiverse
+
+deb http://mirrors.aliyun.com/ubuntu/ noble-updates main restricted universe multiverse
+# deb-src http://mirrors.aliyun.com/ubuntu/ noble-updates main restricted universe multiverse
+
+deb http://mirrors.aliyun.com/ubuntu/ noble-proposed main restricted universe multiverse
+# deb-src http://mirrors.aliyun.com/ubuntu/ noble-proposed main restricted universe multiverse
+
+deb http://mirrors.aliyun.com/ubuntu/ noble-backports main restricted universe multiverse
+# deb-src http://mirrors.aliyun.com/ubuntu/ noble-backports main restricted universe multiverse
+EOF
+
+echo 'Acquire::ForceIPv4 "true";' | sudo tee /etc/apt/apt.conf.d/99force-ipv4
+```
+
+
+安装网络管理工具（若已存在可忽略）
+
+Bash
+
+```
+sudo apt update
+sudo apt install network-manager -y
+sudo systemctl start NetworkManager
+sudo systemctl enable NetworkManager
+```
+
+
+设置wifi密码，固定ip
+
+> **提醒**：以下命令中的 Wi-Fi 名称、密码、IP 地址均为示例，请务必替换为你自己的实际信息。
+
+Bash
+
+```
+sudo nmcli device wifi connect "MERCURY_1812" password "12345678"
+
+sudo nmcli connection modify "MERCURY_1812" ipv4.addresses "192.168.0.86/24" ipv4.gateway "192.168.0.1" ipv4.dns "8.8.8.8,114.114.114.114" ipv4.method "manual"
+
+sudo nmcli connection up "MERCURY_1812"
+```
+
+
+### 第一步：安装核心图形组件与浏览器
+
+这里我们坚持“极简主义”，坚决不装多余的桌面环境（如 GNOME/KDE），只装底层驱动、最轻量的窗口管理器（Openbox）、隐藏鼠标工具以及 Chromium 浏览器。
+
+Bash
+
+```
+sudo timedatectl set-timezone Asia/Shanghai
+
+
+sudo apt install net-tools vim fonts-wqy-microhei fonts-wqy-zenhei alsa-utils pulseaudio -y
+sudo apt install --no-install-recommends xserver-xorg x11-xserver-utils xinit openbox unclutter -y
+
+wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+sudo apt install ./google-chrome-stable_current_amd64.deb -y
+rm google-chrome-stable_current_amd64.deb
+
+sudo apt purge snapd -y
+
+```
+
+### 第二步：配置 TTY1 开机免密自动登录
+
+为了避免手动输入账号密码的尴尬，我们通过修改 systemd 服务，让系统一开机就自动以 `xz` 的身份登录。这里使用一键写入命令，彻底避开由于 `nano` 或 `vi` 操作不当导致的保存失败问题。
+
+**1. 创建配置目录：**
+
+Bash
+
+```
+sudo mkdir -p /etc/systemd/system/getty@tty1.service.d/
+```
+
+**2. 写入自动登录规则：**
+
+Bash
+
+```
+echo -e "[Service]\nExecStart=\nExecStart=-/sbin/agetty --autologin xz --noclear %I \$TERM" | sudo tee /etc/systemd/system/getty@tty1.service.d/override.conf
+```
+
+**3. 重载服务并设置默认启动目标：**
+
+Bash
+
+```
+sudo systemctl daemon-reload
+sudo systemctl set-default multi-user.target
+```
+
+### 第三步：配置登录后自动启动图形界面
+
+系统自动登录后默认停留在黑底白字的命令行，我们需要配置脚本，让它一旦登录立马启动 X11 图形环境。
+
+**1. 触发 `startx` 的启动逻辑：**
+
+直接将触发代码追加写入你的个人环境配置文件中：
+
+Bash
+
+```
+cat << 'EOF' >> ~/.bash_profile
+if [ -z "$DISPLAY" ] && [ "$(fgconsole)" -eq 1 ]; then
+    exec startx
+fi
+EOF
+```
+
+**2. 告诉 `startx` 去启动 Openbox：**
+
+Bash
+
+```
+echo "exec openbox-session" > ~/.xinitrc
+```
+
+### 第四步：配置“铜墙铁壁”的 Openbox 与浏览器
+
+这是最核心的一步：关闭屏幕休眠、隐藏鼠标、全屏锁定浏览器，并写一个“死循环”保证浏览器被意外关闭后也能瞬间复活。
+
+**1. 创建 Openbox 配置目录：**
+
+Bash
+
+```
+mkdir -p ~/.config/openbox
+```
+
+**2. 写入自启动脚本 (`autostart`)：**
+
+复制以下整段代码并回车（这会自动把所有保护规则写进文件里）：
+
+Bash
+
+```
+cat << 'EOF' > ~/.config/openbox/autostart
+# 关闭屏幕保护
+xset -dpms
+xset s noblank
+xset s off
+
+# 隐藏鼠标
+unclutter -idle 0.1 -root &
+
+# 死循环启动 Chromium（崩溃或被关也能秒重启）
+while true; do
+    google-chrome \
+        --kiosk \
+        --no-first-run \
+        --no-default-browser-check \
+        --disable-infobars \
+        --disable-session-crashed-bubble \
+        --disable-translate \
+        --disable-external-intent-requests \
+        --autoplay-policy=no-user-gesture-required \
+        --use-fake-ui-for-media-stream \
+        "https://www.douyin.com"
+    sleep 2
+done &
+EOF
+```
+
+**3. 屏蔽 `Alt+F4` 退出快捷键：**
+
+为了防止别人插上键盘强行关掉窗口，我们把 Openbox 默认的系统快捷键干掉。
+
+Bash
+
+```
+cp /etc/xdg/openbox/rc.xml ~/.config/openbox/
+sed -i '/<keybind key="A-F4">/,/<\/keybind>/d' ~/.config/openbox/rc.xml
+```
+
+### 第五步：重启验收成果
+
+如果拔掉网线或不需要等待所有网络上线，可禁用网络等待服务，避免开机卡顿
+
+Bash
+
+```
+sudo systemctl mask systemd-networkd-wait-online.service
+sudo systemctl mask NetworkManager-wait-online.service
+```
+
+隐藏开机信息（GRUB）
+
+Bash
+
+```
+sudo sed -i 's/GRUB_CMDLINE_LINUX_DEFAULT=.*/GRUB_CMDLINE_LINUX_DEFAULT="quiet loglevel=3 systemd.show_status=false vt.global_cursor_default=0"/g' /etc/default/grub
+
+echo 'GRUB_TIMEOUT_STYLE="hidden"' | sudo tee -a /etc/default/grub
+echo 'GRUB_RECORDFAIL_TIMEOUT=0' | sudo tee -a /etc/default/grub
+
+sudo update-grub
+```
+
+声音设置成100%，然后 重启：
+
+Bash
+
+```
+amixer -q sset Master 100% unmute
+sudo reboot
+```
+
+### 部署唤醒词服务
+
+在一体机上部署唤醒词检测服务，需要安装 Python 环境、上传项目文件、配置 Camera 麦克风和开机自启。
+
+#### 1. 安装 Miniconda
+
+```bash
+wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
+bash Miniconda3-latest-Linux-x86_64.sh -b -p $HOME/miniconda3
+~/miniconda3/bin/conda init bash
+source ~/.bashrc
+rm Miniconda3-latest-Linux-x86_64.sh
+```
+
+
+确保登录时自动进入conda环境
+
+```bash
+if ! grep -q '.bashrc' ~/.bash_profile; then
+    cat << 'EOF' >> ~/.bash_profile
+
+if [ -f ~/.bashrc ]; then
+    . ~/.bashrc
+fi
+EOF
+fi
+```
+
+
+#### 2. 创建 Python 虚拟环境
+
+```bash
+conda create -n test python=3.10 -y
+conda activate test
+```
+
+若出现 Terms of Service have not been accepted 错误，执行：
+
+```bash
+conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
+conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r
+```
+
+#### 3. 上传项目文件
+
+将开发机上的 `main/digital-human/` 整个目录上传到一体机的 `~/digital-human/` 目录：
+
+```bash
+# 在开发机上执行（将 <一体机IP> 替换为实际 IP）
+scp -r main/digital-human/ xz@<一体机IP>:~/digital-human/
+```
+
+#### 4. 安装系统依赖
+
+唤醒词服务需要音频采集库和 ALSA PulseAudio 插件：
+
+```bash
+sudo apt install libportaudio2 portaudio19-dev libasound2-plugins -y
+```
+
+#### 5. 安装 Python 依赖
+
+```bash
+cd ~/digital-human/wakeword_runtime
+pip install numpy
+pip install -r requirements.txt
+```
+
+#### 6. 下载唤醒词模型
+
+模型文件不包含在项目中，需要单独下载配置，详见 [docs/digital-human-wakeword.md](digital-human-wakeword.md) 中的“模型下载”章节。
+
+#### 7. 修改 Openbox 自启动脚本
+
+需要在 autostart 中加上 PulseAudio 和 Camera 麦克风配置，并将 Chrome 地址改为测试页面。
+
+先确认 Camera 麦克风在 PulseAudio 中的设备名：
+
+```bash
+pulseaudio --start
+pactl list sources short
+```
+
+找到包含 `USB_Camera` 的那一行，记下完整名称，例如：
+
+```
+alsa_input.usb-SN0002_2K_USB_Camera_46435000_P030D00_SN0002-02.mono-fallback
+```
+
+然后用完整内容覆盖 autostart（将 `TARGET_MIC` 替换为你的实际设备名）：
+
+```bash
+cat << 'EOF' > ~/.config/openbox/autostart
+# 1. 启动声音服务并稍作等待
+pulseaudio --start
+sleep 1
+
+# 2. 锁定 Camera 的麦克风（请替换为你的实际设备名）
+TARGET_MIC="alsa_input.usb-SN0002_2K_USB_Camera_46435000_P030D00_SN0002-02.mono-fallback"
+
+# 3. 设为系统默认麦克风
+pactl set-default-source "$TARGET_MIC"
+
+# 4. 解除静音
+pactl set-source-mute "$TARGET_MIC" 0
+
+# 5. 音量拉到 100%
+pactl set-source-volume "$TARGET_MIC" 100%
+
+# --- 极简桌面与浏览器环境配置 ---
+
+# 关闭屏幕保护
+xset -dpms
+xset s noblank
+xset s off
+
+# 隐藏鼠标
+unclutter -idle 0.1 -root &
+
+# 死循环启动浏览器（崩溃或被关也能秒重启）
+while true; do
+    google-chrome \
+        --kiosk \
+        --no-first-run \
+        --no-default-browser-check \
+        --disable-infobars \
+        --disable-session-crashed-bubble \
+        --disable-translate \
+        --disable-external-intent-requests \
+        --autoplay-policy=no-user-gesture-required \
+        --use-fake-ui-for-media-stream \
+        "http://127.0.0.1:8006/index.html"
+    sleep 2
+done &
+EOF
+```
+
+#### 8. 配置唤醒词服务开机自启
+
+创建 systemd 服务文件，让唤醒词服务开机自动运行。
+
+先确认当前用户的 UID：
+
+```bash
+id -u $(whoami)
+```
+
+然后用查到的 UID 替换下面 `1000`（通常第一个用户就是 1000）：
+
+```bash
+sudo tee /etc/systemd/system/digital-human.service << 'EOF'
+[Unit]
+Description=Digital Human Runtime
+After=network.target sound.target
+
+[Service]
+Type=simple
+User=xz
+Environment=XDG_RUNTIME_DIR=/run/user/1000
+Environment=PULSE_SERVER=unix:/run/user/1000/pulse/native
+WorkingDirectory=/home/xz/digital-human
+ExecStartPre=/bin/sleep 10
+ExecStart=/home/xz/miniconda3/envs/test/bin/python start.py
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+EOF
+```
+
+> **重要说明**：
+> - `User=xz` — 替换为你的实际用户名
+> - `/run/user/1000` — 替换为你实际的 UID
+> - `WorkingDirectory` 和 `ExecStart` 中的路径 — 替换为你的实际部署路径
+> - `Environment` 中的 PulseAudio 环境变量**必须保留**，否则唤醒词服务和浏览器无法同时使用 Camera 麦克风
+
+启用并启动服务：
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable digital-human
+sudo systemctl start digital-human
+```
+
+#### 9. 常用服务管理命令
+
+```bash
+sudo systemctl start digital-human     # 立即启动
+sudo systemctl stop digital-human      # 停止
+sudo systemctl restart digital-human   # 重启
+sudo systemctl status digital-human    # 查看状态
+journalctl -u digital-human -f         # 查看实时日志
+```
+

docs/device-call-guide.md

@@ -0,0 +1,148 @@
+# 设备间相互呼叫插件使用指南
+
+## 概述
+
+设备呼叫功能允许两个已配置设备之间通过语音/数据通道进行双向通信。设备A呼叫设备B时，系统通过以下流程实现：
+
+```
+设备A → 授权校验 → MQTT网关 → 设备B远程唤醒 → 建立连接 → 通话建立
+```
+## 使用这个功能的前提条件
+1. 你必须要有至少两个设备，每个设备型号必须是`ESP32-S3`，因为只有`ESP32-S3`才支持远程唤醒功能。
+2. 你的设备必须要有`两个麦克风`。但是如果你的设备只有`单个麦克风`，你只是想体验一下这个功能，也是可以的，但是会有强烈的卡顿感。
+3. 你必须使用[全模块部署](Deployment_all.md)本项目，因为你需要`智控台`来管理设备的权限和通信。
+4. 你必须安装并配置好`2026年5月27日`以后的[MQTT网关服务](mqtt-gateway-integration.md)，如果你已经部署了MQTT网关服务，请确认代码的版本是`2026年5月27日`之后的版本。
+
+以上是使用这个功能的硬性条件，接下来会详细介绍。
+
+## 配置步骤
+
+### 第一步：开启通讯录功能
+
+1. 确认你的智控台版本是`0.9.4`或以上版本。
+2. 登录智控台后台
+3. 进入 **系统功能配置**
+4. 在左侧功能列表中勾选 **通讯录**
+5. 点击 **保存配置** 确认
+
+### 第二步：配置设备间呼叫权限
+
+1. 在智控台顶部菜单点击 **通讯录**
+2. 在左侧智能体下，设备列表中选择你的设备A（支持按 MAC地址 或 备注名 搜索）
+3. 在右侧详情面板中，找到目标设备B的称呼设置，例如 **"小王"**
+4. 勾选设备B的 **呼叫权限** 复选框
+5. 点击 **保存**
+
+**双向授权说明：** 如需设备A和设备B互相通信，必须在两侧智控台分别配置对方权限。例如：
+
+- 在设备A的配置中勾选设备B → 设备A可与设备B通信
+- 在设备B的配置中勾选设备A → 设备B可与设备A通信
+
+### 第三步：在智能体配置添加呼叫工具
+
+1. 在智控台顶部菜单点击 **智能体管理**
+2. 在刚刚配置设备联系人的相关智能体中点击 **编辑角色**
+3. 在右侧详情面板中，点击 **编辑功能**
+4. 勾选 **设备呼叫设备** 工具
+5. 点击 **保存配置** 确认
+6. 在外侧再次点击 **保存配置** ，随即重启设备
+
+### 第四步：固件端添加远程唤醒工具
+
+1. 在[xiaozhi-esp32](https://github.com/78/xiaozhi-esp32) 代码的基础上增加远程唤醒工具MCP，版本支持为2.1.0至2.2.6（2026年5月29日的版本）
+2. 在application.h文件中添加远程唤醒函数声明
+    ```cpp
+    void RemoteWakeup(const std::string& reason);
+    ```
+3. 在application.cc文件中添加远程唤醒函数
+    ```cpp
+    void Application::RemoteWakeup(const std::string& reason){
+        if (!protocol_) {
+            return;
+        }
+
+        auto state = GetDeviceState();
+        
+        if (state == kDeviceStateIdle) {
+            audio_service_.EncodeWakeWord();
+
+            if (!protocol_->IsAudioChannelOpened()) {
+                SetDeviceState(kDeviceStateConnecting);
+                if (!protocol_->OpenAudioChannel()) {
+                    audio_service_.EnableWakeWordDetection(true);
+                    return;
+                }
+            }
+            std::string wake_word = reason;
+    #if CONFIG_USE_AFE_WAKE_WORD || CONFIG_USE_CUSTOM_WAKE_WORD
+            // Encode and send the wake word data to the server
+            while (auto packet = audio_service_.PopWakeWordPacket()) {
+                protocol_->SendAudio(std::move(packet));
+            }
+            // Set the chat state to wake word detected
+            protocol_->SendWakeWordDetected(wake_word);
+            SetListeningMode(aec_mode_ == kAecOff ? kListeningModeAutoStop : kListeningModeRealtime);
+    #else
+            // Set flag to play popup sound after state changes to listening
+            // (PlaySound here would be cleared by ResetDecoder in EnableVoiceProcessing)
+            play_popup_on_listening_ = true;
+            SetListeningMode(aec_mode_ == kAecOff ? kListeningModeAutoStop : kListeningModeRealtime);
+    #endif
+        } else if (state == kDeviceStateSpeaking) {
+            AbortSpeaking(kAbortReasonWakeWordDetected);
+            SetDeviceState(kDeviceStateIdle);
+        } else if (state == kDeviceStateActivating) {
+            SetDeviceState(kDeviceStateIdle);
+        }
+    }
+    ```
+4. 在mcp_server.cc文件中添加远程唤醒工具
+    ```cpp
+    AddUserOnlyTool("self.remote_wakeup", "Remote wakeup function with configurable parameters",
+        PropertyList({
+            Property("reason", kPropertyTypeString, "Wakeup reason"),
+        }),
+        [this](const PropertyList& properties) -> ReturnValue {
+            std::string reason = properties["reason"].value<std::string>();
+            ESP_LOGI(TAG, "Wakeup reason=%s", reason.c_str());
+            auto& app = Application::GetInstance();
+            app.RemoteWakeup(reason);
+            return true;
+    ```
+5. 按照 [固件编译烧录指南](firmware-build.md) 完成固件烧录
+6. 无论你的设备是单麦还是双麦，请在编译环节，勾选开启AEC功能!
+7. 无论你的设备是单麦还是双麦，请在编译环节，勾选开启AEC功能!
+8. 无论你的设备是单麦还是双麦，请在编译环节，勾选开启AEC功能!
+
+### 第五步：配置MQTT网关服务
+
+1. 部署MQTT网关服务，参考 [MQTT网关集成文档](mqtt-gateway-integration.md)
+2. 如果已经部署请确认代码的版本是2026年5月27日的版本
+
+## 呼叫流程说明
+
+准备两个设备，在智控台上面配置好通讯权限和在智能体中添加呼叫工具之后，在其中一个小智对话那里对他说：”呼叫XXX“，观察设备B是否响应。
+
+## 常见问题
+
+### Q: 设备B没有响应呼叫？
+
+- 检查设备B是否在线（智控台设备状态）
+- 确认设备B的固件已正确集成远程唤醒工具
+- 检查MQTT网关连接是否正常
+- 验证双向权限配置是否完整
+
+### Q: 提示"无呼叫权限"？
+
+- 在智控台确认设备A已勾选设备B的呼叫权限
+- 确认配置已保存（非仅修改未保存）
+
+### Q: 如何确认通讯录功能已开启？
+
+- 智控台顶部菜单如显示"通讯录"入口，则表示已开启
+
+### Q: 我叫他呼叫"张山"，但是他老是识别成"张三"，怎么办？
+- 可以查阅你使用的asr服务的文档，确认是否支持热词识别。
+- 如果你用的是`FunASRServer`,可以在容器里的`热词文件`里添加"张山"，然后重启容器。
+- 如果你用的是`火山引擎`的服务，可以在`火山引擎的控制台`里添加`热词文件`，然后回到智控台的`模型配置页面`，把`热词文件名称`配置在`火山引擎的tts`上去。
+

docs/digital-human-wakeword.md

@@ -0,0 +1,220 @@
+# 数字人digital-human启动方法
+
+## 概述
+
+测试页面集成了基于 **Sherpa-ONNX** 的高精度语音唤醒功能，支持自定义唤醒词和实时检测。使用轻量级关键词检测模型，提供毫秒级响应速度。
+
+## 唤醒词模型
+
+### 模型下载（必需）
+
+**重要说明**: 项目不包含模型文件，需要提前下载配置。
+
+### 官方模型下载地址
+
+- **官方模型列表**: <https://csukuangfj.github.io/sherpa/onnx/kws/pretrained_models/index.html>
+- **推荐模型**: `sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01`
+
+### 下载和配置步骤
+
+#### 1. 下载模型包
+
+```bash
+# 方法1：直接下载（推荐）
+cd main/digital-human/wakeword_runtime/
+wget https://github.com/k2-fsa/sherpa-onnx/releases/download/kws-models/sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01.tar.bz2
+
+# 解压
+tar xvf sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01.tar.bz2
+
+# 方法2：使用ModelScope
+pip install modelscope
+python -c "
+from modelscope import snapshot_download
+snapshot_download('pkufool/sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01', cache_dir='./models')
+"
+```
+
+#### 2. 配置模型文件
+
+模型包下载后包含以下文件：
+
+```
+sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01/
+├── encoder-epoch-12-avg-2-chunk-16-left-64.int8.onnx    # 速度优先
+├── encoder-epoch-12-avg-2-chunk-16-left-64.onnx
+├── encoder-epoch-99-avg-1-chunk-16-left-64.int8.onnx    # 速度优先
+├── encoder-epoch-99-avg-1-chunk-16-left-64.onnx         # 精度优先
+├── decoder-epoch-12-avg-2-chunk-16-left-64.onnx
+├── decoder-epoch-99-avg-1-chunk-16-left-64.onnx         # 精度优先
+├── joiner-epoch-12-avg-2-chunk-16-left-64.int8.onnx     # 速度优先
+├── joiner-epoch-12-avg-2-chunk-16-left-64.onnx
+├── joiner-epoch-99-avg-1-chunk-16-left-64.int8.onnx     # 速度优先
+├── joiner-epoch-99-avg-1-chunk-16-left-64.onnx          # 精度优先
+├── tokens.txt                    # Token映射表（必需）
+├── keywords_raw.txt              # 模型包里可能附带（可选，runtime 不依赖）
+├── keywords.txt                  # 现成的
+├── test_wavs/                    # 测试音频（可选）
+├── configuration.json            # 模型元信息（可选）
+└── README.md                     # 说明文档（可选）
+```
+
+#### 3. 选择配置方案
+
+**方案一：精度优先（推荐）**
+
+```bash
+cd sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01
+
+# 创建模型目录
+mkdir -p ../models
+
+# 复制精度优先的epoch-99 fp32三件套
+cp encoder-epoch-99-avg-1-chunk-16-left-64.onnx ../models/encoder.onnx
+cp decoder-epoch-99-avg-1-chunk-16-left-64.onnx ../models/decoder.onnx
+cp joiner-epoch-99-avg-1-chunk-16-left-64.onnx ../models/joiner.onnx
+
+# 复制配套文件
+cp tokens.txt ../models/tokens.txt
+# keywords_raw.txt 如果模型包里附带，可自行保留；runtime 不依赖它
+```
+
+**方案二：速度优先**
+
+```bash
+cd sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01
+
+# 创建模型目录
+mkdir -p ../models
+
+# 复制速度优先的epoch-99 int8三件套
+cp encoder-epoch-99-avg-1-chunk-16-left-64.int8.onnx ../models/encoder.onnx
+cp decoder-epoch-99-avg-1-chunk-16-left-64.onnx ../models/decoder.onnx
+cp joiner-epoch-99-avg-1-chunk-16-left-64.int8.onnx ../models/joiner.onnx
+
+# 复制配套文件
+cp tokens.txt ../models/tokens.txt
+```
+
+**注意事项**:
+
+- **不要混用 fp32 与 int8**：三个模型文件必须保持一致的精度
+- **优先选择 epoch-99**：比 epoch-12 训练更充分，精度更高
+- **必需文件**：`encoder.onnx` + `decoder.onnx` + `joiner.onnx` + `tokens.txt` + `keywords.txt`
+
+### 最终模型文件结构
+
+配置完成后，模型文件应放在 `wakeword_runtime/models/` 目录下，完整路径为 `main/digital-human/wakeword_runtime/models/`：
+
+```
+wakeword_runtime/models/
+├── encoder.onnx      # 编码器模型（重命名后）
+├── decoder.onnx      # 解码器模型（重命名后）
+├── joiner.onnx       # 连接器模型（重命名后）
+├── tokens.txt        # 拼音 Token 映射表（228行版本）
+├── keywords.txt      # 关键词配置文件（首次启动自动生成）
+└── keywords_raw.txt  # 可选，runtime 不依赖
+```
+
+## 启动方式
+
+在 `main/digital-human` 目录执行：
+
+```bash
+pip install -r wakeword_runtime/requirements.txt
+python start.py
+```
+
+启动后默认地址：
+
+- 页面地址：`http://127.0.0.1:8006/index.html`
+- 事件桥地址：`ws://127.0.0.1:8006/wakeword-ws`
+- 健康检查：`http://127.0.0.1:8006/health`
+
+停止方式：
+
+- 在运行终端按 `Ctrl+C`
+- 会同时停止静态页面服务、事件桥和唤醒词检测流程
+
+## 配置文件说明
+
+配置文件位于 [main/digital-human/wakeword_runtime/config.json](../main/digital-human/wakeword_runtime/config.json)。
+
+当前主要配置项：
+
+```json
+{
+  "wakeword": {
+    "enabled": true
+  },
+  "model_dir": "models",
+  "audio": {
+    "input_device": null,
+    "sample_rate": 16000,
+    "channels": 1
+  },
+  "detector": {
+    "num_threads": 4,
+    "provider": "cpu",
+    "max_active_paths": 2,
+    "keywords_score": 1.8,
+    "keywords_threshold": 0.1,
+    "num_trailing_blanks": 1,
+    "cooldown_seconds": 1.5
+  },
+  "logging": {
+    "level": "INFO",
+    "dir": "logs",
+    "file": "wakeword-runtime.log"
+  }
+}
+```
+
+各字段含义：
+
+| 参数 | 说明 |
+| --- | --- |
+| `wakeword.enabled` | 是否启用本地唤醒词检测 |
+| `model_dir` | 模型和词表所在目录 |
+| `audio.input_device` | 麦克风输入设备，默认使用系统默认设备 |
+| `audio.sample_rate` | 采样率，默认 `16000` |
+| `audio.channels` | 声道数，默认 `1` |
+| `detector.num_threads` | 检测器线程数 |
+| `detector.provider` | 推理 provider，当前通常为 `cpu` |
+| `detector.max_active_paths` | 搜索路径数 |
+| `detector.keywords_score` | 关键词增强分数 |
+| `detector.keywords_threshold` | 检测阈值 |
+| `detector.num_trailing_blanks` | 尾随空白数量 |
+| `detector.cooldown_seconds` | 连续触发冷却时间 |
+| `logging.level` | 日志等级 |
+| `logging.dir` | 日志目录 |
+| `logging.file` | 日志文件名 |
+
+## 推荐使用流程
+
+### 首次使用
+
+1. 准备 `models/` 目录下的模型文件和 `tokens.txt`
+2. 确认 `models/keywords.txt` 存在
+3. 在 `digital-human` 目录运行 `python start.py`
+4. 浏览器打开 `http://127.0.0.1:8006/index.html`
+5. 进入设置页检查“唤醒词”配置
+
+### 修改唤醒词
+
+1. 打开数字人页面设置
+2. 切到“唤醒词”页签
+3. 修改启用状态或唤醒词列表
+4. 点击“应用唤醒词”
+5. 根据提示决定是否立即重启
+
+### 禁用唤醒词
+
+1. 将“启用本地唤醒词”改成禁用
+2. 点击“应用唤醒词”
+3. 建议立即重启一次
+
+禁用后：
+
+- 页面与事件桥仍然可用
+- 唤醒词检测不会继续运行

docs/docker-build.md

@@ -1,21 +1,74 @@
 # 本地编译docker镜像方法
 
-现在本项目已经使用github自动编译docker功能，本文档是提供给有本地编译docker镜像需求的朋友准备的。
+现在本项目已经使用`github`的`自动编译docker镜像`功能，如果您拉取的是项目发行的镜像，您没有自己编译镜像的需求，那就忽略本文档。
 
-1、安装docker
+如果您修改了源码，然后想采用`docker`的方式部署运行，可以参照以下步骤操作：
-```
+
+## 1、环境准备
+
+安装docker：
+```bash
 sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
 ```
-2、编译docker镜像
-```
-#进入项目根目录
-# 编译server
-docker build -t xiaozhi-esp32-server:server_latest -f ./Dockerfile-server .
-# 编译web
-docker build -t xiaozhi-esp32-server:web_latest -f ./Dockerfile-web .
 
-# 编译完成后，可以使用docker-compose启动项目
+## 2、编译镜像
-# docker-compose.yml你需要修改成自己编译的镜像版本
+
+当你修改好代码后，需要编译新的镜像时，需要按照以下步骤操作：
+
+准备好你的`你的用户名`和`新的版本号`。
+- 这个`你的用户名`是你在`docker hub`注册的用户名，例如`xiaozhi`。当然，如果你不需要推送到`docker hub`，你可以自由定义。
+- 这个`新的版本号`是你编译的镜像版本，例如`1.2.3`，你可以根据需要自定义或者使用日期格式（例如`20260609`）主要是方便和现在运行的版本号做区分，同时也方便下次回忆你是什么时候构建的，不要和现在你本机运行的版本号相同。
+
+进入`xiaozhi-esp32-server`项目根目录，编译 server 和 web 两个镜像：
+
+```bash
+cd 项目根目录
+
+# 编译server镜像
+docker build -f Dockerfile-server -t 你的用户名/xiaozhi-esp32-server:新的版本号 .
+
+# 编译web镜像
+docker build -f Dockerfile-web -t 你的用户名/xiaozhi-esp32-server-web:新的版本号 .
+
+```
+
+## 3、修改docker-compose配置
+
+```bash
 cd main/xiaozhi-server
-docker compose up -d
+```
+
+编辑 `docker-compose_all.yml` 文件，将镜像版本替换为你刚才编译的版本：
+
+```yaml
+services:
+  xiaozhi-esp32-server:
+    image: 你的用户名/xiaozhi-esp32-server:新的版本号   # 修改为你的镜像地址
+    ...
+
+  xiaozhi-esp32-server-web:
+    image: 你的用户名/xiaozhi-esp32-server-web:新的版本号   #修改为你的镜像地址
+    ...
+```
+
+## 4、重启服务
+
+```bash
+# 停止旧容器
+docker compose -f docker-compose_all.yml down
+
+# 启动新容器
+docker compose -f docker-compose_all.yml up -d
+```
+
+## 5、验证
+
+查看日志确认服务启动正常：
+
+```bash
+# 查看server日志
+docker logs -f -n 50 xiaozhi-esp32-server
+
+# 查看web日志
+docker logs -f -n 50 xiaozhi-esp32-server-web
 ```

docs/firmware-build.md

@@ -13,9 +13,9 @@ http://192.168.1.25:8003/xiaozhi/ota/
 ```
 如果显示“OTA接口运行正常，向设备发送的websocket地址是：ws://xxx:8000/xiaozhi/v1/
 
-你可以使用项目自带的`test_page.html`测试一下，是否能连上ota页面输出的websocket地址。
+你可以启动`digital-human`模块后打开`index.html`测试一下，是否能连上ota页面输出的websocket地址。
 
-如果访问不到，你需要到配置文件`.config.yaml`里修改`server.websocket`的地址，重启后再重新测试，直到`test_page.html`能正常访问。
+如果访问不到，你需要到配置文件`.config.yaml`里修改`server.websocket`的地址，重启后再重新测试，直到`index.html`能正常访问。
 
 成功后，请往下进行第2步
 

docs/manager-api-fastapi-compatibility.md

@@ -0,0 +1,267 @@
+# manager-api FastAPI 兼容性矩阵
+
+> 生成依据：`main/manager-api-fastapi/compatibility/java-routes.json`、
+> `main/manager-api-fastapi/compatibility/consumer-routes.json`、`route-surface-results.json`、
+> `authenticated-route-results.json`、`contract-results.json` 和当前 Java 源码。接口路径均省略
+> 共同前缀 `/xiaozhi`。
+
+## 结论与状态口径
+
+Java 基线共有 **154** 条 Spring MVC 路由；FastAPI 已注册 **154/154（100%）**，并由
+`tests/test_java_route_manifest.py` 对源码清单 freshness、数量和 method/path 注册闭合进行检查。
+此外实现 3 条仅由仓库消费者使用、Java Controller 中不存在的兼容路由，因此这 3 条不计入
+154 条 Java 覆盖率。三端 188 个调用点均能解析到 FastAPI 路由。
+
+矩阵状态必须按下列含义阅读：
+
+- `结构✓`：method/path 已注册且清单闭合；它不等于业务行为逐接口实测。
+- `请求面差分✓1`：本行已向隔离 Java/FastAPI 各发送一次缺少鉴权或安全非法输入，精确比较
+  HTTP status、body 与 Content-Type；最终为 **154/154 通过、0 失败、0 跳过**，且不发送成功写请求。
+- `认证业务面差分✓1`：本行已使用有效 DB Token、server-secret 或匿名身份，再向隔离
+  Java/FastAPI 各发送一次安全业务/校验请求，精确比较 HTTP status、body 与 Content-Type；
+  最终为 **154/154 通过、0 失败、0 跳过**，且不主动发送成功写请求。该状态不等于每条路由的
+  完整成功生命周期均已差分，完整副作用证据仍以 `差分✓N` 为准。
+- `领域✓(x，域级)`：该领域有 service/repository/协议自动测试，但不保证本行每条成功与错误路径
+  都被直接请求。`领域—` 表示除结构测试外没有可归属的域级直接测试证据。
+- `差分✓N`：本行除安全请求面外，还参与了成功、主要错误、协议或数据库副作用的深度对照；
+  括号说明覆盖面。深度结果为 **49/49 checks 通过、0 失败、0 跳过**，覆盖 **21/154** 条路由。
+  `差分间接✓` 表示 J125 作为下载链路的 URL 生成步骤被间接覆盖；`差分—` 表示没有深度对照，
+  不能把 154/154 请求面差分误读成 154 条全部成功路径与副作用都已逐接口对照。
+- 所有 `Result<T>` 均表示 `{code,msg,data}` envelope；原 Java 为 HTTP 200 的认证、权限、业务和
+  参数错误由全局兼容层维持 HTTP 200。二进制/OTA 裸响应在“响应类型”列单独标明。
+
+## 三端消费者闭合
+
+| 消费者 | 调用点 | 唯一结构路由 | 方法分布 |
+|---|---:|---:|---|
+| `manager-web` | 134 | 130 | DELETE 12、GET 59、POST 40、PUT 23 |
+| `manager-mobile` | 46 | 40 | DELETE 3、GET 26、POST 12、PUT 5 |
+| `xiaozhi-server` | 8 | 8 | GET 2、POST 6 |
+| **合计** | **188** | **140** | — |
+
+### 3 条消费者孤儿兼容路由
+
+| Method/path | 来源 | FastAPI 语义 | 鉴权 | 状态 |
+|---|---|---|---|---|
+| `GET /api/ping` | manager-mobile 环境设置探活 | `{code:0,msg:"success",data:"pong"}` | 匿名 | 实现✓；consumer resolve✓ |
+| `PUT /user/configDevice/{device_id}` | manager-web 遗留设备配置调用 | 按现有设备更新契约处理 body | DB Token | 实现✓；consumer resolve✓ |
+| `GET /device/address-book/lookup` | xiaozhi-server 管理客户端 | `callerMac/nickname/answer` 地址簿查询/呼叫兼容别名 | server-secret | 实现✓；consumer resolve✓；device 域测试✓ |
+
+`GET /admin/dict/data/type/FIRMWARE_TYPE` 是动态 Java 路由
+`GET /admin/dict/data/type/{dictType}` 的一个字面调用，不是第四条孤儿路由。
+
+## Java 基线静态盘点
+
+- Controller：24 个、154 条映射。按 Controller 的路由数为：`AdminController`(5)、`AgentChatHistoryController`(4)、`AgentController`(21)、`AgentMcpAccessPointController`(2)、`AgentSnapshotController`(4)、`AgentTemplateController`(6)、`AgentVoicePrintController`(4)、`ConfigController`(3)、`CorrectWordController`(7)、`DeviceController`(13)、`KnowledgeBaseController`(7)、`KnowledgeFilesController`(8)、`LoginController`(8)、`ModelController`(11)、`ModelProviderController`(5)、`OTAController`(3)、`OTAMagController`(9)、`ServerSideManageController`(2)、`SysDictDataController`(6)、`SysDictTypeController`(5)、`SysParamsController`(5)、`TimbreController`(4)、`VoiceCloneController`(6)、`VoiceResourceController`(6)。
+- 数据分层：`entity/` 29 个 Java 文件（28 个 `*Entity.java` 加 `BaseEntity`）、`dto/` 58 个、
+  `vo/` 14 个、`dao/` 29 个、`service/` 树 78 个文件（其中
+  `service/impl/` 38 个）。FastAPI 对应落在 `schemas/`、`repositories/`、
+  `services/`、`routers/`、`integrations/` 与 `jobs/`，没有把跨表事务放进路由。
+- MyBatis XML：20 个，分别是 `mapper/agent/AgentCorrectWordMappingDao.xml`、`mapper/agent/AgentDao.xml`、`mapper/agent/AgentPluginMappingMapper.xml`、`mapper/agent/AgentSnapshotDao.xml`、`mapper/agent/AgentTagDao.xml`、`mapper/agent/AgentTagRelationDao.xml`、`mapper/agent/AgentTemplateMapper.xml`、`mapper/agent/AiAgentChatHistoryDao.xml`、`mapper/correctword/CorrectWordItemDao.xml`、`mapper/device/DeviceAddressBookDao.xml`、`mapper/device/DeviceDao.xml`、`mapper/knowledge/KnowledgeBaseDao.xml`、`mapper/model/ModelConfigDao.xml`、`mapper/model/ModelProviderDao.xml`、`mapper/security/SysUserTokenDao.xml`、`mapper/sys/SysDictDataDao.xml`、`mapper/sys/SysDictTypeDao.xml`、`mapper/sys/SysParamsDao.xml`、`mapper/sys/SysUserDao.xml`、`mapper/voiceclone/VoiceCloneDao.xml`。
+- Liquibase：`db.changelog-master.yaml` 含 101 个 `changeSet` 引用，目录中恰有
+  101 个 SQL；Python 部署继续执行这 101 个原始 SQL，不改写历史。
+- 定时工作：`DocumentStatusSyncTask` 每次完成后延迟 30 秒，扫描 RAGFlow RUNNING 文档并
+  回写 SUCCESS/FAIL/CANCEL 与统计；当前 Java 源码另有 `AgentSnapshotRedactionRunner`，启动时
+  执行一次并在滚动部署期每 15 秒补偿脱敏旧快照。FastAPI 将工作移到独立 jobs 进程，并以
+  Redis 分布式锁/watchdog 防止多 worker 重复执行。
+- 外部集成：RAGFlow dataset/document/chunk/retrieval/upload；阿里云短信；火山语音克隆训练与
+  音频；声纹 HTTP；OpenAI-compatible LLM 摘要/标题；MQTT gateway HTTP；MCP/管理动作
+  WebSocket；OTA/WS/MQTT 的 HMAC、Base64、时间戳与下载文件存储。自动测试只访问可重复 mock，
+  未使用真实付费凭证。
+
+## 154 条 Java→FastAPI 逐接口矩阵
+
+副作用缩写：`DB-R/W`=数据库读/写，`Redis-R/W/DEL`=缓存读/写/失效，`文件-R/W`=文件
+读取/写入；外部调用均在 service/integration 层。权限为空时表示只需对应鉴权身份。
+
+| # | Method/path | Java Controller.handler | 请求面 | 响应类型 | 鉴权 / 权限 | DB/Redis/文件/外部副作用 | 实现与测试状态 |
+|---:|---|---|---|---|---|---|---|
+| J001 | `GET /admin/device/all` | `AdminController.pageDevice` | Query:params:Map<String, Object> | envelope <PageData<UserShowDeviceListVO>> | DB Token / `sys:role:superAdmin` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J002 | `POST /admin/dict/data/delete` | `SysDictDataController.delete` | Body:Long[] | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(dict cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J003 | `GET /admin/dict/data/page` | `SysDictDataController.page` | Query:params:Map<String, Object> | envelope <PageData<SysDictDataVO>> | DB Token / `sys:role:superAdmin` | DB-R; Redis-R/W(dict cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J004 | `POST /admin/dict/data/save` | `SysDictDataController.save` | Body:SysDictDataDTO | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(dict cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J005 | `GET /admin/dict/data/type/{dictType}` | `SysDictDataController.getDictDataByType` | Path:dictType | envelope <List<SysDictDataItem>> | DB Token / `sys:role:normal` | DB-R; Redis-R/W(dict cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J006 | `PUT /admin/dict/data/update` | `SysDictDataController.update` | Body:SysDictDataDTO | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(dict cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J007 | `GET /admin/dict/data/{id}` | `SysDictDataController.get` | Path:id | envelope <SysDictDataVO> | DB Token / `sys:role:superAdmin` | DB-R; Redis-R/W(dict cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J008 | `POST /admin/dict/type/delete` | `SysDictTypeController.delete` | Body:Long[] | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(dict cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J009 | `GET /admin/dict/type/page` | `SysDictTypeController.page` | Query:params:Map<String, Object> | envelope <PageData<SysDictTypeVO>> | DB Token / `sys:role:superAdmin` | DB-R; Redis-R/W(dict cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J010 | `POST /admin/dict/type/save` | `SysDictTypeController.save` | Body:SysDictTypeDTO | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(dict cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J011 | `PUT /admin/dict/type/update` | `SysDictTypeController.update` | Body:SysDictTypeDTO | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(dict cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J012 | `GET /admin/dict/type/{id}` | `SysDictTypeController.get` | Path:id | envelope <SysDictTypeVO> | DB Token / `sys:role:superAdmin` | DB-R; Redis-R/W(dict cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J013 | `POST /admin/params` | `SysParamsController.save` | Body:SysParamsDTO | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W; Redis-W/DEL | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J014 | `PUT /admin/params` | `SysParamsController.update` | Body:SysParamsDTO | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W; Redis-W; 外部-配置端点探测(按 paramCode) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J015 | `POST /admin/params/delete` | `SysParamsController.delete` | Body:String[] | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W; Redis-W/DEL | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J016 | `GET /admin/params/page` | `SysParamsController.page` | Query:params:Map<String, Object> | envelope <PageData<SysParamsDTO>> | DB Token / `sys:role:superAdmin` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J017 | `GET /admin/params/{id}` | `SysParamsController.get` | Path:id | envelope <SysParamsDTO> | DB Token / `sys:role:superAdmin` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J018 | `POST /admin/server/emit-action` | `ServerSideManageController.emitServerAction` | Body:EmitSeverActionDTO | envelope <Boolean> | DB Token / `sys:role:superAdmin` | DB/Redis-R(secret/WS); Redis-W(one-shot); 外部-WebSocket | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J019 | `GET /admin/server/server-list` | `ServerSideManageController.getWsServerList` | — | envelope <List<String>> | DB Token / `sys:role:superAdmin` | DB/Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J020 | `GET /admin/users` | `AdminController.pageUser` | Query:params:Map<String, Object> | envelope <PageData<AdminPageUserVO>> | DB Token / `sys:role:superAdmin` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分✓3（权限/序列化/非法分页） |
+| J021 | `PUT /admin/users/changeStatus/{status}` | `AdminController.changeStatus` | Path:status; Body:String[] | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W(user/password/status/token) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J022 | `DELETE /admin/users/{id}` | `AdminController.delete` | Path:id | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W(用户/token/device/agent 级联) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J023 | `PUT /admin/users/{id}` | `AdminController.update` | Path:id | envelope <String> | DB Token / `sys:role:superAdmin` | DB-W(user/password/status/token) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(sys，域级)；差分— |
+| J024 | `POST /agent` | `AgentController.save` | Body:AgentCreateDTO | envelope <String> | DB Token / `sys:role:normal` | DB-W(含快照/映射/标签事务); Redis-DEL | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J025 | `GET /agent/all` | `AgentController.adminAgentList` | Query:params:Map<String, Object> | envelope <PageData<AgentEntity>> | DB Token / `sys:role:superAdmin` | DB-R; Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J026 | `POST /agent/audio/{audioId}` | `AgentController.getAudioId` | Path:audioId | envelope <String> | DB Token / `sys:role:normal` | DB-R(audio); Redis-W(one-shot URL) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J027 | `GET /agent/chat-history/download/{uuid}/current` | `AgentChatHistoryController.downloadCurrentSession` | Path:uuid | 流式/二进制 + 原下载 headers | 匿名 / — | DB/Redis-R(one-shot); 文件-R/流式 | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J028 | `GET /agent/chat-history/download/{uuid}/previous` | `AgentChatHistoryController.downloadCurrentSessionWithPrevious` | Path:uuid | 流式/二进制 + 原下载 headers | 匿名 / — | DB/Redis-R(one-shot); 文件-R/流式 | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J029 | `POST /agent/chat-history/getDownloadUrl/{agentId}/{sessionId}` | `AgentChatHistoryController.getDownloadUrl` | Path:agentId,sessionId | envelope <String> | DB Token / — | DB-R(chat/session); Redis-W(download token TTL) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J030 | `POST /agent/chat-history/report` | `AgentChatHistoryController.uploadFile` | Body:AgentChatHistoryReportDTO | envelope <Boolean> | server-secret / — | DB-W(chat/session); server-secret | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J031 | `POST /agent/chat-summary/{sessionId}/save` | `AgentController.generateAndSaveChatSummary` | Path:sessionId | envelope <Void> | server-secret / — | DB-R/W(chat); 外部-OpenAI-compatible LLM | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J032 | `POST /agent/chat-title/{sessionId}/generate` | `AgentController.generateAndSaveChatTitle` | Path:sessionId | envelope <Void> | server-secret / — | DB-R/W(chat); 外部-OpenAI-compatible LLM | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J033 | `GET /agent/list` | `AgentController.getUserAgents` | Query:keyword:String,searchType:String | envelope <List<AgentDTO>> | DB Token / `sys:role:normal` | DB-R; Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分✓1 |
+| J034 | `GET /agent/mcp/address/{agentId}` | `AgentMcpAccessPointController.getAgentMcpAccessAddress` | Path:agentId | envelope <String> | DB Token / `sys:role:normal` | DB/Redis-R; AES token 生成 | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J035 | `GET /agent/mcp/tools/{agentId}` | `AgentMcpAccessPointController.getAgentMcpToolsList` | Path:agentId | envelope <List<String>> | DB Token / `sys:role:normal` | DB/Redis-R; 外部-WebSocket MCP | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J036 | `GET /agent/play/{uuid}` | `AgentController.playAudio` | Path:uuid | 流式/二进制 + 原下载 headers | 匿名 / — | DB/Redis-R(one-shot); 文件-R/流式 | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J037 | `PUT /agent/saveMemory/{macAddress}` | `AgentController.updateByDeviceId` | Path:macAddress; Body:AgentMemoryDTO | envelope <Void> | DB Token / `sys:role:normal` | DB-W(含快照/映射/标签事务); Redis-DEL | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J038 | `POST /agent/tag` | `AgentController.createTag` | Body:Map<String, String> | envelope <AgentTagEntity> | DB Token / `sys:role:normal` | DB-W(含快照/映射/标签事务); Redis-DEL | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J039 | `GET /agent/tag/list` | `AgentController.getAllTags` | — | envelope <List<AgentTagDTO>> | DB Token / `sys:role:normal` | DB-R; Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J040 | `DELETE /agent/tag/{id}` | `AgentController.deleteTag` | Path:id | envelope <Void> | DB Token / `sys:role:normal` | DB-W(含快照/映射/标签事务); Redis-DEL | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J041 | `GET /agent/template` | `AgentController.templateList` | — | envelope <List<AgentTemplateEntity>> | DB Token / `sys:role:normal` | DB-R; Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J042 | `POST /agent/template` | `AgentTemplateController.createAgentTemplate` | Body:AgentTemplateEntity | envelope <AgentTemplateEntity> | DB Token / `sys:role:superAdmin` | DB-W(含快照/映射/标签事务); Redis-DEL | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J043 | `PUT /agent/template` | `AgentTemplateController.updateAgentTemplate` | Body:AgentTemplateEntity | envelope <AgentTemplateEntity> | DB Token / `sys:role:superAdmin` | DB-W(含快照/映射/标签事务); Redis-DEL | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J044 | `POST /agent/template/batch-remove` | `AgentTemplateController.batchRemoveAgentTemplates` | Body:List<String> | envelope <String> | DB Token / `sys:role:superAdmin` | DB-W(含快照/映射/标签事务); Redis-DEL | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J045 | `GET /agent/template/page` | `AgentTemplateController.getAgentTemplatesPage` | Query:params:Map<String, Object> | envelope <PageData<AgentTemplateVO>> | DB Token / `sys:role:superAdmin` | DB-R; Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J046 | `DELETE /agent/template/{id}` | `AgentTemplateController.deleteAgentTemplate` | Path:id | envelope <String> | DB Token / `sys:role:superAdmin` | DB-W(含快照/映射/标签事务); Redis-DEL | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J047 | `GET /agent/template/{id}` | `AgentTemplateController.getAgentTemplateById` | Path:id | envelope <AgentTemplateVO> | DB Token / `sys:role:superAdmin` | DB-R; Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J048 | `POST /agent/voice-print` | `AgentVoicePrintController.save` | Body:AgentVoicePrintSaveDTO | envelope <Void> | DB Token / `sys:role:normal` | DB-W; 外部-voiceprint HTTP | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J049 | `PUT /agent/voice-print` | `AgentVoicePrintController.update` | Body:AgentVoicePrintUpdateDTO | envelope <Void> | DB Token / `sys:role:normal` | DB-W; 外部-voiceprint HTTP | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J050 | `GET /agent/voice-print/list/{id}` | `AgentVoicePrintController.list` | Path:id | envelope <List<AgentVoicePrintVO>> | DB Token / `sys:role:normal` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J051 | `DELETE /agent/voice-print/{id}` | `AgentVoicePrintController.delete` | Path:id | envelope <Void> | DB Token / `sys:role:normal` | DB-W; 外部-voiceprint HTTP | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J052 | `GET /agent/{agentId}/snapshots` | `AgentSnapshotController.page` | Path:agentId; Query:params:AgentSnapshotPageDTO | envelope <PageData<AgentSnapshotVO>> | DB Token / `sys:role:normal` | DB-R; Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J053 | `DELETE /agent/{agentId}/snapshots/{snapshotId}` | `AgentSnapshotController.deleteSnapshot` | Path:agentId,snapshotId | envelope <Void> | DB Token / `sys:role:normal` | DB-W(含快照/映射/标签事务); Redis-DEL | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J054 | `GET /agent/{agentId}/snapshots/{snapshotId}` | `AgentSnapshotController.getSnapshot` | Path:agentId,snapshotId | envelope <AgentSnapshotVO> | DB Token / `sys:role:normal` | DB-R; Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J055 | `POST /agent/{agentId}/snapshots/{snapshotId}/restore` | `AgentSnapshotController.restore` | Path:agentId,snapshotId; Body:AgentSnapshotRestoreDTO | envelope <Void> | DB Token / `sys:role:normal` | DB-W(含快照/映射/标签事务); Redis-DEL | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J056 | `DELETE /agent/{id}` | `AgentController.delete` | Path:id | envelope <Void> | DB Token / `sys:role:normal` | DB-W(含快照/映射/标签事务); Redis-DEL | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J057 | `GET /agent/{id}` | `AgentController.getAgentById` | Path:id | envelope <AgentInfoVO> | DB Token / `sys:role:normal` | DB-R; Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J058 | `PUT /agent/{id}` | `AgentController.update` | Path:id; Body:AgentUpdateDTO | envelope <Void> | DB Token / `sys:role:normal` | DB-W(含快照/映射/标签事务); Redis-DEL | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J059 | `GET /agent/{id}/chat-history/audio` | `AgentController.getContentByAudioId` | Path:id | envelope <String> | DB Token / `sys:role:normal` | DB-R; Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J060 | `GET /agent/{id}/chat-history/user` | `AgentController.getRecentlyFiftyByAgentId` | Path:id | envelope <List<AgentChatHistoryUserVO>> | DB Token / `sys:role:normal` | DB-R; Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J061 | `GET /agent/{id}/chat-history/{sessionId}` | `AgentController.getAgentChatHistory` | Path:id,sessionId | envelope <List<AgentChatHistoryDTO>> | DB Token / `sys:role:normal` | DB-R; Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J062 | `GET /agent/{id}/sessions` | `AgentController.getAgentSessions` | Path:id; Query:params:Map<String, Object> | envelope <PageData<AgentChatSessionDTO>> | DB Token / `sys:role:normal` | DB-R; Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J063 | `GET /agent/{id}/tags` | `AgentController.getAgentTags` | Path:id | envelope <List<AgentTagDTO>> | DB Token / `sys:role:normal` | DB-R; Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J064 | `PUT /agent/{id}/tags` | `AgentController.saveAgentTags` | Path:id; Body:Map<String, Object> | envelope <Void> | DB Token / `sys:role:normal` | DB-W(含快照/映射/标签事务); Redis-DEL | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(agent，域级)；差分— |
+| J065 | `POST /config/agent-models` | `ConfigController.getAgentModels` | Body:AgentModelsDTO | envelope <Object> | server-secret / — | DB-R; Redis-R/W(runtime/model/timbre cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(config，域级)；差分— |
+| J066 | `POST /config/correct-words` | `ConfigController.getCorrectWords` | Body:CorrectWordsDTO | envelope <Object> | server-secret / — | DB-R; Redis-R/W(runtime/model/timbre cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(config，域级)；差分— |
+| J067 | `POST /config/server-base` | `ConfigController.getConfig` | — | envelope <Object> | server-secret / — | DB-R; Redis-R/W(runtime/model/timbre cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(config，域级)；差分✓3（缺失/错误/正确 secret） |
+| J068 | `POST /correct-word/file` | `CorrectWordController.createFile` | Body:CorrectWordFileCreateDTO | envelope <CorrectWordFileVO> | DB Token / `sys:role:normal` | DB-W(file/items/mapping 事务) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(correctword，域级)；差分✓2（响应/DB） |
+| J069 | `POST /correct-word/file/batch-delete` | `CorrectWordController.batchDeleteFiles` | Body:List<String> | envelope <Void> | DB Token / `sys:role:normal` | DB-W(file/items/mapping 事务) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(correctword，域级)；差分— |
+| J070 | `GET /correct-word/file/download/{fileId}` | `CorrectWordController.downloadFile` | Path:fileId | 流式/二进制 + 原下载 headers | DB Token / `sys:role:normal` | DB-R(content); 二进制 | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(correctword，域级)；差分✓2（二进制/更新后下载） |
+| J071 | `GET /correct-word/file/list` | `CorrectWordController.listFiles` | Query:params:Map<String, Object> | envelope <PageData<CorrectWordFileVO>> | DB Token / `sys:role:normal` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(correctword，域级)；差分✓1 |
+| J072 | `GET /correct-word/file/select` | `CorrectWordController.listAllFiles` | — | envelope <List<CorrectWordFileVO>> | DB Token / `sys:role:normal` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(correctword，域级)；差分— |
+| J073 | `DELETE /correct-word/file/{fileId}` | `CorrectWordController.deleteFile` | Path:fileId | envelope <Void> | DB Token / `sys:role:normal` | DB-W(file/items/mapping 事务) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(correctword，域级)；差分✓1（级联副作用） |
+| J074 | `PUT /correct-word/file/{fileId}` | `CorrectWordController.updateFile` | Path:fileId; Body:CorrectWordFileCreateDTO | envelope <Void> | DB Token / `sys:role:normal` | DB-W(file/items/mapping 事务) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(correctword，域级)；差分✓2（响应/DB） |
+| J075 | `GET /datasets` | `KnowledgeBaseController.getPageList` | Query:name:String,page:Integer,page_size:Integer | envelope <PageData<KnowledgeBaseDTO>> | DB Token / `sys:role:normal` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(knowledge，域级)；差分— |
+| J076 | `POST /datasets` | `KnowledgeBaseController.save` | Body:KnowledgeBaseDTO | envelope <KnowledgeBaseDTO> | DB Token / `sys:role:normal` | DB-R/W; 外部-RAGFlow HTTP(upload/dataset/document/chunk/retrieval) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(knowledge，域级)；差分— |
+| J077 | `DELETE /datasets/batch` | `KnowledgeBaseController.deleteBatch` | Query:ids:String | envelope <Void> | DB Token / `sys:role:normal` | DB-R/W; 外部-RAGFlow HTTP(upload/dataset/document/chunk/retrieval) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(knowledge，域级)；差分— |
+| J078 | `GET /datasets/rag-models` | `KnowledgeBaseController.getRAGModels` | — | envelope <List<ModelConfigEntity>> | DB Token / `sys:role:normal` | DB-R(model config) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(knowledge，域级)；差分— |
+| J079 | `DELETE /datasets/{dataset_id}` | `KnowledgeBaseController.delete` | Path:dataset_id | envelope <Void> | DB Token / `sys:role:normal` | DB-R/W; 外部-RAGFlow HTTP(upload/dataset/document/chunk/retrieval) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(knowledge，域级)；差分— |
+| J080 | `GET /datasets/{dataset_id}` | `KnowledgeBaseController.getByDatasetId` | Path:dataset_id | envelope <KnowledgeBaseDTO> | DB Token / `sys:role:normal` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(knowledge，域级)；差分— |
+| J081 | `PUT /datasets/{dataset_id}` | `KnowledgeBaseController.update` | Path:dataset_id; Body:KnowledgeBaseDTO | envelope <KnowledgeBaseDTO> | DB Token / `sys:role:normal` | DB-R/W; 外部-RAGFlow HTTP(upload/dataset/document/chunk/retrieval) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(knowledge，域级)；差分— |
+| J082 | `POST /datasets/{dataset_id}/chunks` | `KnowledgeFilesController.parseDocuments` | Path:dataset_id; Body:Map<String, List<String>> | envelope <Void> | DB Token / `sys:role:normal` | DB-R/W; 外部-RAGFlow HTTP(upload/dataset/document/chunk/retrieval) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(knowledge，域级)；差分— |
+| J083 | `DELETE /datasets/{dataset_id}/documents` | `KnowledgeFilesController.delete` | Path:dataset_id; Body:DocumentDTO.BatchIdReq | envelope <Void> | DB Token / `sys:role:normal` | DB-R/W; 外部-RAGFlow HTTP(upload/dataset/document/chunk/retrieval) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(knowledge，域级)；差分— |
+| J084 | `GET /datasets/{dataset_id}/documents` | `KnowledgeFilesController.getPageList` | Path:dataset_id; Query:name:String,status:String,page:Integer,page_size:Integer | envelope <PageData<KnowledgeFilesDTO>> | DB Token / `sys:role:normal` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(knowledge，域级)；差分— |
+| J085 | `POST /datasets/{dataset_id}/documents` | `KnowledgeFilesController.uploadDocument` | Path:dataset_id; Query:name:String,chunkMethod:String,metaFields:String,parserConfig:String; Multipart:file | envelope <KnowledgeFilesDTO> | DB Token / `sys:role:normal` | DB-R/W; 外部-RAGFlow HTTP(upload/dataset/document/chunk/retrieval) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(knowledge，域级)；差分— |
+| J086 | `GET /datasets/{dataset_id}/documents/status/{status}` | `KnowledgeFilesController.getPageListByStatus` | Path:dataset_id,status; Query:page:Integer,page_size:Integer | envelope <PageData<KnowledgeFilesDTO>> | DB Token / `sys:role:normal` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(knowledge，域级)；差分— |
+| J087 | `DELETE /datasets/{dataset_id}/documents/{document_id}` | `KnowledgeFilesController.deleteSingle` | Path:dataset_id,document_id | envelope <Void> | DB Token / `sys:role:normal` | DB-R/W; 外部-RAGFlow HTTP(upload/dataset/document/chunk/retrieval) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(knowledge，域级)；差分— |
+| J088 | `GET /datasets/{dataset_id}/documents/{document_id}/chunks` | `KnowledgeFilesController.listChunks` | Path:dataset_id,document_id; Query:page:Integer,pageSize:Integer,keywords:String,id:String | envelope <ChunkDTO.ListVO> | DB Token / `sys:role:normal` | DB-R/W; 外部-RAGFlow HTTP(upload/dataset/document/chunk/retrieval) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(knowledge，域级)；差分— |
+| J089 | `POST /datasets/{dataset_id}/retrieval-test` | `KnowledgeFilesController.retrievalTest` | Path:dataset_id; Body:RetrievalDTO.TestReq | envelope <RetrievalDTO.ResultVO> | DB Token / `sys:role:normal` | DB-R/W; 外部-RAGFlow HTTP(upload/dataset/document/chunk/retrieval) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(knowledge，域级)；差分— |
+| J090 | `PUT /device/address-book/alias` | `DeviceController.updateAlias` | Body:DeviceAddressBookAliasDTO | envelope <Void> | DB Token / `sys:role:normal` | DB-W(device/bind/address-book); Redis-R/W | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分— |
+| J091 | `GET /device/address-book/call` | `DeviceController.callByNickname` | Query:callerMac:String,nickname:String,answer:boolean | envelope <Map<String, Object>> | server-secret / — | DB-R; 外部-MQTT gateway HTTP; server-secret | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分— |
+| J092 | `PUT /device/address-book/permission` | `DeviceController.updatePermission` | Body:DeviceAddressBookPermissionDTO | envelope <Void> | DB Token / `sys:role:normal` | DB-W(device/bind/address-book); Redis-R/W | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分— |
+| J093 | `GET /device/address-book/{macAddress}` | `DeviceController.getAddressBook` | Path:macAddress | envelope <Object> | DB Token / `sys:role:normal` | DB-R; Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分— |
+| J094 | `GET /device/bind/{agentId}` | `DeviceController.getUserDevices` | Path:agentId | envelope <List<UserShowDeviceListVO>> | DB Token / `sys:role:normal` | DB-R; Redis-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分✓1 |
+| J095 | `POST /device/bind/{agentId}` | `DeviceController.forwardToMqttGateway` | Path:agentId; Body:String | envelope <String> | DB Token / `sys:role:normal` | DB/Redis-R; 外部-MQTT gateway HTTP + daily auth | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分— |
+| J096 | `POST /device/bind/{agentId}/{deviceCode}` | `DeviceController.bindDevice` | Path:agentId,deviceCode | envelope <Void> | DB Token / `sys:role:normal` | DB-W(device/bind/address-book); Redis-R/W | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分— |
+| J097 | `POST /device/manual-add` | `DeviceController.manualAddDevice` | Body:DeviceManualAddDTO | envelope <Void> | DB Token / `sys:role:normal` | DB-W(device/bind/address-book); Redis-R/W | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分— |
+| J098 | `POST /device/register` | `DeviceController.registerDevice` | Body:DeviceRegisterDTO | envelope <String> | DB Token / — | DB-W(device/bind/address-book); Redis-R/W | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分— |
+| J099 | `POST /device/tools/call/{deviceId}` | `DeviceController.callDeviceTool` | Path:deviceId; Body:DeviceToolsCallReqDTO | envelope <Object> | DB Token / `sys:role:normal` | DB/Redis-R; 外部-MQTT gateway HTTP + daily auth | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分— |
+| J100 | `POST /device/tools/list/{deviceId}` | `DeviceController.getDeviceTools` | Path:deviceId | envelope <Object> | DB Token / `sys:role:normal` | DB/Redis-R; 外部-MQTT gateway HTTP + daily auth | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分✓2（响应/外呼格式） |
+| J101 | `POST /device/unbind` | `DeviceController.unbindDevice` | Body:DeviceUnBindDTO | envelope <Void> | DB Token / `sys:role:normal` | DB-W(device/bind/address-book); Redis-R/W | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分— |
+| J102 | `PUT /device/update/{id}` | `DeviceController.updateDeviceInfo` | Path:id; Body:DeviceUpdateDTO | envelope <Void> | DB Token / `sys:role:normal` | DB-W(device/bind/address-book); Redis-R/W | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分✓3（上下界/UTF-16 长度） |
+| J103 | `PUT /models/default/{id}` | `ModelController.setDefaultModel` | Path:id | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(model/config cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(model，域级)；差分— |
+| J104 | `PUT /models/enable/{id}/{status}` | `ModelController.enableModelConfig` | Path:id,status | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(model/config cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(model，域级)；差分— |
+| J105 | `GET /models/list` | `ModelController.getModelConfigList` | Query:modelType:String,modelName:String,page:String,limit:String | envelope <PageData<ModelConfigDTO>> | DB Token / `sys:role:superAdmin` | DB-R; Redis-R/W(model cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(model，域级)；差分— |
+| J106 | `GET /models/llm/names` | `ModelController.getLlmModelCodeList` | Query:modelName:String | envelope <List<LlmModelBasicInfoDTO>> | DB Token / `sys:role:normal` | DB-R; Redis-R/W(model cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(model，域级)；差分— |
+| J107 | `GET /models/names` | `ModelController.getModelNames` | Query:modelType:String,modelName:String | envelope <List<ModelBasicInfoDTO>> | DB Token / `sys:role:normal` | DB-R; Redis-R/W(model cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(model，域级)；差分— |
+| J108 | `GET /models/provider` | `ModelProviderController.getListPage` | Query:modelProviderDTO:ModelProviderDTO,page:String,limit:String | envelope <PageData<ModelProviderDTO>> | DB Token / `sys:role:superAdmin` | DB-R; Redis-R/W(model cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(model，域级)；差分✓1 |
+| J109 | `POST /models/provider` | `ModelProviderController.add` | Body:ModelProviderDTO | envelope <ModelProviderDTO> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(model/config cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(model，域级)；差分✓1（约束集合） |
+| J110 | `PUT /models/provider` | `ModelProviderController.edit` | Body:ModelProviderDTO | envelope <ModelProviderDTO> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(model/config cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(model，域级)；差分— |
+| J111 | `POST /models/provider/delete` | `ModelProviderController.delete` | Body:List<String> | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(model/config cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(model，域级)；差分— |
+| J112 | `GET /models/provider/plugin/names` | `ModelProviderController.getPluginNameList` | — | envelope <List<ModelProviderDTO>> | DB Token / — | DB-R; Redis-R/W(model cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(model，域级)；差分— |
+| J113 | `DELETE /models/{id}` | `ModelController.deleteModelConfig` | Path:id | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(model/config cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(model，域级)；差分— |
+| J114 | `GET /models/{id}` | `ModelController.getModelConfig` | Path:id | envelope <ModelConfigDTO> | DB Token / `sys:role:superAdmin` | DB-R; Redis-R/W(model cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(model，域级)；差分— |
+| J115 | `GET /models/{modelId}/voices` | `ModelController.getVoiceList` | Path:modelId; Query:voiceName:String | envelope <List<VoiceDTO>> | DB Token / `sys:role:normal` | DB-R; Redis-R/W(model cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(model，域级)；差分— |
+| J116 | `GET /models/{modelType}/provideTypes` | `ModelController.getModelProviderList` | Path:modelType | envelope <List<ModelProviderDTO>> | DB Token / `sys:role:superAdmin` | DB-R; Redis-R/W(model cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(model，域级)；差分— |
+| J117 | `POST /models/{modelType}/{provideCode}` | `ModelController.addModelConfig` | Path:modelType,provideCode; Body:ModelConfigBodyDTO | envelope <ModelConfigDTO> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(model/config cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(model，域级)；差分— |
+| J118 | `PUT /models/{modelType}/{provideCode}/{id}` | `ModelController.editModelConfig` | Path:modelType,provideCode,id; Body:ModelConfigBodyDTO | envelope <ModelConfigDTO> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(model/config cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(model，域级)；差分— |
+| J119 | `GET /ota/` | `OTAController.getOTA` | — | 裸 text/plain | 匿名 / — | — | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分✓1（MIME/body） |
+| J120 | `POST /ota/` | `OTAController.checkOTAVersion` | Header:Device-Id,Client-Id; Body:DeviceReportReqDTO | 裸 application/json | 匿名 / — | DB/Redis-R(设备/固件/配置); HMAC/Base64/时间戳凭证 | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分✓4（必填/格式/凭证/密码学） |
+| J121 | `POST /ota/activate` | `OTAController.activateDevice` | Header:Device-Id,Client-Id | 裸 application/json | 匿名 / — | DB-R/W(device activation); Redis-R/W(TTL) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分✓3 |
+| J122 | `GET /otaMag` | `OTAMagController.page` | Query:params:Map<String, Object> | envelope <PageData<OtaEntity>> | DB Token / `sys:role:superAdmin` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分— |
+| J123 | `POST /otaMag` | `OTAMagController.save` | Body:OtaEntity | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W(OTA metadata) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分✓2（响应/DB） |
+| J124 | `GET /otaMag/download/{uuid}` | `OTAMagController.downloadFirmware` | Path:uuid | 流式/二进制 + 原下载 headers | 匿名 / — | Redis-R/W(一次性/次数); 文件-R/流式 | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分✓4（次数限制及二进制） |
+| J125 | `GET /otaMag/getDownloadUrl/{id}` | `OTAMagController.getDownloadUrl` | Path:id | envelope <String> | DB Token / `sys:role:superAdmin` | DB-R; Redis-W(download token TTL) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分间接✓(供下载链路) |
+| J126 | `POST /otaMag/upload` | `OTAMagController.uploadFirmware` | Multipart:file | envelope <String> | DB Token / `sys:role:superAdmin` | 文件-W(MD5/扩展名/大小) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分✓2（上传/扩展名错误） |
+| J127 | `POST /otaMag/uploadAssetsBin` | `OTAMagController.uploadAssetsBin` | Multipart:file | envelope <String> | DB Token / `sys:role:normal` | 文件-W(MD5/扩展名/大小) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分— |
+| J128 | `DELETE /otaMag/{id}` | `OTAMagController.delete` | Path:id | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W(OTA metadata); 文件-DEL | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分— |
+| J129 | `GET /otaMag/{id}` | `OTAMagController.get` | Path:id | envelope <OtaEntity> | DB Token / `sys:role:superAdmin` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分— |
+| J130 | `PUT /otaMag/{id}` | `OTAMagController.update` | Path:id; Body:OtaEntity | envelope <?> | DB Token / `sys:role:superAdmin` | DB-W(OTA metadata) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(device，域级)；差分— |
+| J131 | `GET /ttsVoice` | `TimbreController.page` | Query:params:Map<String, Object> | envelope <PageData<TimbreDetailsVO>> | DB Token / `sys:role:superAdmin` | DB-R; Redis-R/W(timbre cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(timbre，域级)；差分— |
+| J132 | `POST /ttsVoice` | `TimbreController.save` | Body:TimbreDataDTO | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(timbre/config cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(timbre，域级)；差分— |
+| J133 | `POST /ttsVoice/delete` | `TimbreController.delete` | Body:String[] | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(timbre/config cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(timbre，域级)；差分— |
+| J134 | `PUT /ttsVoice/{id}` | `TimbreController.update` | Path:id; Body:TimbreDataDTO | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W; Redis-DEL(timbre/config cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(timbre，域级)；差分— |
+| J135 | `GET /user/captcha` | `LoginController.captcha` | Query:uuid:String | image/gif 二进制 | 匿名 / — | Redis-W(captcha TTL); GIF | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(security，域级)；差分— |
+| J136 | `PUT /user/change-password` | `LoginController.changePassword` | Body:PasswordDTO | envelope <?> | DB Token / — | DB-W(user/token); Redis-R/DEL(SMS) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(security，域级)；差分— |
+| J137 | `GET /user/info` | `LoginController.info` | — | envelope <UserDetail> | DB Token / — | DB-R; Redis-R/W(cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(security，域级)；差分✓9（七语言/过期 Token/Long） |
+| J138 | `POST /user/login` | `LoginController.login` | Body:LoginDTO | envelope <TokenDTO> | 匿名 / — | DB-R/W(token); Redis-R/DEL(captcha) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(security，域级)；差分— |
+| J139 | `GET /user/pub-config` | `LoginController.pubConfig` | — | envelope <Map<String, Object>> | 匿名 / — | DB-R; Redis-R/W(cache) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(security，域级)；差分✓1 |
+| J140 | `POST /user/register` | `LoginController.register` | Body:LoginDTO | envelope <Void> | 匿名 / — | DB-W(user/token); Redis-R/DEL(SMS) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(security，域级)；差分— |
+| J141 | `PUT /user/retrieve-password` | `LoginController.retrievePassword` | Body:RetrievePasswordDTO | envelope <?> | 匿名 / — | DB-W(user/token); Redis-R/DEL(SMS) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(security，域级)；差分— |
+| J142 | `POST /user/smsVerification` | `LoginController.smsVerification` | Body:SmsVerificationDTO | envelope <Void> | 匿名 / — | Redis-R/W(TTL/频控); 外部-Aliyun SMS | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(security，域级)；差分— |
+| J143 | `GET /voiceClone` | `VoiceCloneController.page` | Query:params:Map<String, Object> | envelope <PageData<VoiceCloneResponseDTO>> | DB Token / `sys:role:normal` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(voiceclone，域级)；差分— |
+| J144 | `POST /voiceClone/audio/{id}` | `VoiceCloneController.getAudioId` | Path:id | envelope <String> | DB Token / `sys:role:normal` | DB-R; Redis-W(one-shot URL) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(voiceclone，域级)；差分— |
+| J145 | `POST /voiceClone/cloneAudio` | `VoiceCloneController.cloneAudio` | Body:Map<String, String> | envelope <String> | DB Token / `sys:role:normal` | DB-R/W(train state); 文件-W; 外部-火山语音克隆 HTTP | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(voiceclone，域级)；差分— |
+| J146 | `GET /voiceClone/play/{uuid}` | `VoiceCloneController.playVoice` | Path:uuid | 流式/二进制 + 原下载 headers | 匿名 / — | Redis-R/DEL(one-shot); 文件/外部音频-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(voiceclone，域级)；差分— |
+| J147 | `POST /voiceClone/updateName` | `VoiceCloneController.updateName` | Body:Map<String, String> | envelope <String> | DB Token / `sys:role:normal` | DB-W(train record name) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(voiceclone，域级)；差分— |
+| J148 | `POST /voiceClone/upload` | `VoiceCloneController.uploadVoice` | Query:id:String; Multipart:voiceFile | envelope <String> | DB Token / `sys:role:normal` | DB-R/W(train state); 文件-W; 外部-火山语音克隆 HTTP | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(voiceclone，域级)；差分— |
+| J149 | `GET /voiceResource` | `VoiceResourceController.page` | Query:params:Map<String, Object> | envelope <PageData<VoiceCloneResponseDTO>> | DB Token / `sys:role:superAdmin` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(voiceclone，域级)；差分— |
+| J150 | `POST /voiceResource` | `VoiceResourceController.save` | Body:VoiceCloneDTO | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W(voice resource) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(voiceclone，域级)；差分— |
+| J151 | `GET /voiceResource/ttsPlatforms` | `VoiceResourceController.getTtsPlatformList` | — | envelope <List<Map<String, Object>>> | DB Token / `sys:role:superAdmin` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(voiceclone，域级)；差分— |
+| J152 | `GET /voiceResource/user/{userId}` | `VoiceResourceController.getByUserId` | Path:userId | envelope <List<VoiceCloneResponseDTO>> | DB Token / `sys:role:normal` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(voiceclone，域级)；差分— |
+| J153 | `DELETE /voiceResource/{id}` | `VoiceResourceController.delete` | Path:id | envelope <Void> | DB Token / `sys:role:superAdmin` | DB-W(voice resource) | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(voiceclone，域级)；差分— |
+| J154 | `GET /voiceResource/{id}` | `VoiceResourceController.get` | Path:id | envelope <VoiceCloneResponseDTO> | DB Token / `sys:role:superAdmin` | DB-R | 结构✓；请求面差分✓1；认证业务面差分✓1；领域✓(voiceclone，域级)；差分— |
+
+## 已观测差异与未覆盖面
+
+- 154 条安全请求面差分最终全部一致。首轮曾发现 5 个空 Body 映射差异；修复 FastAPI 对
+  Spring `HttpMessageNotReadableException` 的 code-500 语义后，重新从零执行才得到 154/154。
+- 154 条认证业务面差分最终全部一致；该轮使用有效鉴权与安全业务/校验输入，在不主动成功
+  写入的前提下逐路由对照。证据是 `authenticated-route-results.json`，渲染器会在结果不是
+  154/154、存在失败或跳过时硬失败。
+- 2026-07-20 的隔离差分报告未在 49 个 checks 中观测到响应/所选 headers/数据库副作用
+  不一致；证据是 `main/manager-api-fastapi/compatibility/contract-results.json`，不是人工推断。
+- Hibernate Validator 的 `ConstraintViolation Set` 首条消息无稳定顺序；模型 provider 必填
+  用例比较“消息属于 Java 声明约束集合”与相同错误码，而不伪造一个固定顺序。
+- OTA 时间戳/token 是动态值，差分先比较归一化结构，再分别校验两端 HMAC/Base64 密码学
+  有效性；这属于有意的测试归一化，不是声称字节恒等。
+- 深度差分未直接命中的 133 条中，J125 是下载链路间接覆盖，另 132 条标为 `差分—`；
+  它们有请求面、认证业务面与所属领域测试，但尚无逐路由成功+主要错误+副作用深度对照，不能据此宣称
+  每一种业务状态均已逐接口行为等价。
+- FastAPI 额外提供上述 3 条消费者兼容路由与 live/ready 健康检查；它们没有 Java
+  Controller 基线，属于明确、可回退的加法差异。
+- Java 把定时任务放在 Spring 进程；FastAPI 使用独立 jobs 进程和 Redis 分布式锁。这是
+  部署拓扑差异，业务状态和幂等目标保持一致。
+- RAGFlow、阿里云短信、火山语音克隆、真实声纹、真实 LLM、真实 MQTT/MCP/WS 均未用
+  生产凭证联调；自动化只证明 mock 请求格式、超时/错误映射/重试中的已覆盖场景。
+
+## 可复现检查
+
+```bash
+cd main/manager-api-fastapi
+.venv/bin/python scripts/extract_java_routes.py --output compatibility/java-routes.json
+.venv/bin/python scripts/extract_consumer_routes.py > /tmp/consumer-routes.json
+.venv/bin/pytest -q tests/test_java_route_manifest.py tests/test_consumer_route_manifest.py tests/test_compatibility_document.py
+```
+
+逐接口差分的启动、隔离库、mock 与执行命令见 `docs/manager-api-fastapi-test-report.md`；
+本文件只陈述已落盘的结果，不把缺少真实密钥的外部联调列为通过。

docs/manager-api-fastapi-migration.md

@@ -0,0 +1,290 @@
+# manager-api 到 FastAPI 迁移说明
+
+## 目标与边界
+
+`main/manager-api-fastapi` 是 `main/manager-api` 的兼容替代实现。迁移只替换管理 API
+进程，不改变 MySQL 表、Liquibase 历史、Redis 业务语义，也不要求 manager-web、
+manager-mobile 或 xiaozhi-server 修改现有 URL。Java 实现继续保留，作为行为基线和
+回滚实现。
+
+本次迁移不采用双写。灰度期间，每个业务域在任一时刻只有一个写入方；读流量可以按
+请求切分，写流量必须按业务域整体切换。
+
+## 架构
+
+```mermaid
+flowchart LR
+    C["Web / Mobile / xiaozhi-server / Device"] --> N["Nginx /xiaozhi"]
+    N --> A["FastAPI API workers"]
+    A --> R["Routers"]
+    R --> S["Services / transaction boundaries"]
+    S --> P["Repositories / SQLAlchemy async"]
+    S --> I["External integration clients"]
+    P --> M[("Existing MySQL schema")]
+    S --> D[("Redis Java compatibility layer")]
+    J["Standalone jobs worker"] --> S
+    L["Original Liquibase changelog"] --> X["Migration runner"]
+    X --> M
+```
+
+代码按职责分为：
+
+- `app/routers`：URL、HTTP 方法、Header/Query/Body 绑定和响应形态。
+- `app/services`：权限后的业务规则、事务边界、跨表级联和外部调用编排。
+- `app/repositories`：现有 MySQL 表上的参数化 SQL、行锁和分页。
+- `app/schemas`：兼容现有字段别名及请求模型。
+- `app/integrations`：LLM、MQTT gateway、MCP、RAGFlow、语音克隆和声纹客户端。
+- `app/jobs`：独立的定时任务进程；API worker 不启动定时任务。
+- `app/core`：数据库 Token 认证、国际化、Java JSON/Long 兼容、SM2、Redis 编解码、
+  Snowflake ID 和健康检查。
+
+所有业务路由保留 `/xiaozhi` 前缀。普通 API 返回 `{code,msg,data}`；认证过滤器、
+业务异常和请求校验均由兼容处理器转换，不把 FastAPI 默认的 401、403 或 422 直接
+暴露给客户端。OTA、播放和文件下载等原本返回裸 JSON、文本或二进制的接口继续保持
+其原始响应类型。
+
+## 数据库兼容策略
+
+### Schema 与迁移
+
+原目录 `main/manager-api/src/main/resources/db/changelog/` 仍是唯一 schema source of
+truth。不得把既有 changeset 改写成 Alembic，也不得修改已应用 changeset 的 ID、作者或
+校验和。
+
+Python 部署必须先运行独立迁移镜像或 `scripts/run-migrations.sh`。迁移 runner 直接打包
+原 Java Liquibase 资源，因此与保留的 Java 服务使用相同的 `DATABASECHANGELOG` 历史。
+宿主机执行脚本时，`JAVA_RESOURCES_DIR` 必须指向仓库中的
+`main/manager-api/src/main/resources`；不要使用只存在于应用镜像内的
+`/opt/xiaozhi/java-resources`。本机隔离数据库的完整命令见“配置与启动 / 本地”。
+
+`docker compose` 中 `manager-api-fastapi` 和 `manager-api-jobs` 都等待
+`manager-api-migrate` 成功退出，避免应用在未完成迁移时接流量。
+
+### 事务、锁与 ID
+
+- Service 层在一次事务中完成智能体创建/更新/删除、插件/标签/纠错词映射、设备解绑、
+  快照恢复及其他多表操作；异常时显式回滚。
+- 智能体更新和恢复先对 `ai_agent` 执行 `SELECT ... FOR UPDATE`，序列化同一智能体的
+  快照版本分配和状态令牌校验。
+- 快照版本仍使用 `(agent_id, version_no)` 唯一约束及同一事务内的 `MAX+1` 插入；行锁
+  防止并发恢复或更新竞争。
+- 需要 Long 主键的管理表继续使用与 Java epoch/node/sequence 布局一致的 Snowflake
+  生成器；原本使用 32 位 UUID 的业务表仍使用无连字符 UUID。
+- 不新增数据库外键，也不改表、索引、字符集或 MySQL 类型。
+
+### Java/Python 并存
+
+并存期必须给写请求建立确定的域路由，例如 `agent/*` 全部指向一个实现，不能把同一域
+中的增删改请求在 Java 与 Python 之间随机分配。建议域切换顺序为只读配置、系统管理、
+模型/音色、设备、智能体、知识库和外部集成。域回切前先停止该域的新写入并等待在途
+请求完成。
+
+## Redis 兼容策略
+
+默认继续使用 Java 已有 key 名称和 TTL。`app/core/redis.py` 实现 Spring Data
+`RedisSerializer.json()` 使用的 Jackson wire format，包括：
+
+- Map 的 `@class`、List/Set 的 wrapper-array；
+- Object 槽位中 Long 的 `java.lang.Long` 包装；
+- `java.util.Date` 的 epoch 毫秒包装；
+- Java DTO/Entity 缓存所需的具体类名和字段类型；
+- Hash 缓存写入后的 86400 秒默认 TTL。
+
+该兼容层使 Java 回滚进程可以读取 FastAPI 写入的缓存。应用启动和正常测试不会执行
+`FLUSHALL`；隔离测试脚本的 `reset` 只操作其自建 Redis 实例。定时任务使用 Redis
+分布式锁和自动续租 watchdog，即使启动多个 jobs 容器，同一个任务也只有一个执行者。
+
+## 安全与协议兼容
+
+- 用户 Token 仍保存在 `sys_user_token`，按数据库过期时间校验；没有替换为 JWT。
+- 登录密文继续使用 SM2 C1C3C2，黄金向量由 Java 和 Python 双向解密测试校验。
+- `/config/*`、聊天记录上报/摘要/标题及地址簿内部接口继续校验数据库中的
+  `server.secret` Bearer 值。
+- OTA、WebSocket 和 MQTT 保留原 HMAC、Base64、时间戳、Client-Id/Device-Id 及 token
+  格式。
+- 密钥只通过环境变量或原参数表提供；`.env.example` 和部署文档不包含真实凭证。
+
+## 配置与启动
+
+### 本地
+
+`.env.example` 是容器 Compose 模板，其中的 `mysql`、`redis` 是 Compose 服务名，
+`/opt/xiaozhi/java-resources` 是镜像内路径，不能原样复制后用于宿主机进程。下面的流程
+显式使用 `127.0.0.1:13316` 上的隔离 MySQL、`127.0.0.1:16379` 上的隔离 Redis，以及
+仓库原始 Liquibase/i18n 资源；不会连接或迁移现有开发数据库：
+
+```bash
+cd main/manager-api-fastapi
+uv sync --locked
+
+./scripts/isolated-env.sh start
+
+LIQUIBASE_URL='jdbc:mysql://127.0.0.1:13316/manager_fastapi_test?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&allowMultiQueries=true' \
+LIQUIBASE_USERNAME='xiaozhi_test' \
+LIQUIBASE_PASSWORD='isolated-test-only' \
+JAVA_RESOURCES_DIR="$PWD/../manager-api/src/main/resources" \
+MAVEN_BIN="$PWD/../../.runtime/maven/bin/mvn" \
+MAVEN_LOCAL_REPOSITORY="$PWD/../../.runtime/m2" \
+JAVA_HOME="$PWD/../../.runtime/jdk" \
+./scripts/run-migrations.sh
+
+eval "$(./scripts/isolated-env.sh env)"
+export APP_ENVIRONMENT=development
+export APP_DATABASE_URL="$TEST_FASTAPI_DATABASE_URL"
+export APP_REDIS_URL="$TEST_FASTAPI_REDIS_URL"
+export APP_JAVA_RESOURCES_DIR="$PWD/../manager-api/src/main/resources"
+export APP_UPLOAD_DIR="$PWD/.test-runtime/local-uploadfile"
+mkdir -p "$APP_UPLOAD_DIR"
+./scripts/start-api.sh
+```
+
+上述 `eval` 会得到明确的 localhost URL（FastAPI 测试库和 Redis DB 2）。定时任务必须
+作为单独进程启动；新终端需要重复 `eval` 及四个 `APP_*` 路径/URL 导出，不能让 jobs
+进程落回 `.env.example` 的 Docker DNS：
+
+```bash
+cd main/manager-api-fastapi
+eval "$(./scripts/isolated-env.sh env)"
+export APP_ENVIRONMENT=development
+export APP_DATABASE_URL="$TEST_FASTAPI_DATABASE_URL"
+export APP_REDIS_URL="$TEST_FASTAPI_REDIS_URL"
+export APP_JAVA_RESOURCES_DIR="$PWD/../manager-api/src/main/resources"
+export APP_UPLOAD_DIR="$PWD/.test-runtime/local-uploadfile"
+./scripts/start-jobs.sh
+```
+
+API 默认监听 `0.0.0.0:8002`，兼容根路径为
+`http://127.0.0.1:8002/xiaozhi`。`APP_WORKERS` 可以大于 1；任务不会随 API worker
+复制。验证结束后运行 `./scripts/isolated-env.sh stop`。生产环境不得设置
+`APP_ALLOW_START_WITHOUT_DEPENDENCIES=true`。
+
+仓库统一启动脚本继承当前 shell 的上述环境变量；FastAPI 是默认实现，保留的 Java
+实现可直接用于本地回滚：
+
+```bash
+cd "$(git rev-parse --show-toplevel)"
+scripts/restart-local-services.sh --manager-api fastapi --wait 180
+scripts/restart-local-services.sh --manager-api java --wait 180
+```
+
+### 容器
+
+下面的 `mysql`、`redis` 只在容器网络确实提供对应 DNS 名时有效，否则必须替换为该网络
+可访问的真实主机名。API 镜像内的 Java 资源路径是 `/opt/xiaozhi/java-resources`，迁移
+镜像则把同一仓库资源打包到 `/migration/java-resources`。以下示例中的凭证必须替换，
+并应通过部署平台的 secret 注入而不是提交到仓库：
+
+```bash
+cd main/manager-api-fastapi
+export LIQUIBASE_URL='jdbc:mysql://mysql:3306/xiaozhi_esp32_server?serverTimezone=Asia/Shanghai'
+export MYSQL_USER='xiaozhi'
+export MYSQL_PASSWORD='replace-me'
+export FASTAPI_DATABASE_URL='mysql+asyncmy://xiaozhi:replace-me@mysql:3306/xiaozhi_esp32_server?charset=utf8mb4'
+export REDIS_URL='redis://redis:6379/0'
+export MANAGER_API_UPSTREAM='manager-api-fastapi:8002'
+docker compose build
+docker compose up -d
+```
+
+若 `MANAGER_API_UPLOAD_SOURCE` 指向保留 Java 服务的宿主机上传目录，必须在启动前让 Java
+运行用户与容器 UID 10001 都具备读写和目录遍历权限；不要盲目 `chown -R` 导致 Java 失去
+访问权，应使用部署环境的共享组或 ACL。空 named volume 在 Docker 通常会继承镜像中
+`/data/uploads` 的 UID，但并非所有 OCI runtime 都实现相同 copy-up 语义；必须以容器内
+UID 10001 做一次写入预检。`/xiaozhi/health/ready` 同时检查上传目录可写性，权限不正确时
+返回 HTTP 503 和 `data.uploads=false`，不得绕过该检查接入流量。Apple Container 的一次性
+卷初始化实测命令和结果记录在测试报告中。
+
+`MANAGER_API_UPSTREAM` 默认值是 `manager-api-fastapi:8002`。修改变量后必须重建 Nginx
+容器才能重新渲染配置；切到 FastAPI 和整服务回滚到 Java 的命令分别为：
+
+```bash
+MANAGER_API_UPSTREAM='manager-api-fastapi:8002' \
+  docker compose up -d --no-deps --force-recreate manager-api-nginx
+
+MANAGER_API_UPSTREAM='<Nginx 容器可访问的 Java 主机名或 IP>:8002' \
+  docker compose up -d --no-deps --force-recreate manager-api-nginx
+```
+
+Java 地址必须能从 Nginx 容器网络解析和访问。内置 Nginx 的这个变量会切换整个
+`/xiaozhi`；逐业务域灰度需要在上层网关按路径配置两个 upstream，仍须遵守“同一业务域
+只有一个写入方”。
+
+API 镜像（包括 jobs 命令）和迁移镜像都声明 `USER 10001:10001`，以非 root 用户运行。
+Compose 还为 API/jobs 设置只读根文件系统和 `/tmp` tmpfs；`/data/uploads` 是它们唯一的
+持久写目录，并通过 `/app/uploadfile` 符号链接兼容数据库中的 Java 相对路径。迁移容器是
+一次性非 root 进程，但 Compose 没有把它标为只读根文件系统。Nginx 镜像没有声明
+非 root `USER`，不能将其描述为非 root 镜像；它通过 Compose 的 `read_only: true` 及
+`/var/cache/nginx`、`/var/run`、`/tmp` 三个 tmpfs 加固。Nginx 保留 `/xiaozhi/` 路径，
+关闭上传请求缓冲并设置 100 MiB 上限。健康检查分为：
+
+- `/xiaozhi/health/live`：进程存活；
+- `/xiaozhi/health/ready`：MySQL、Redis 和上传目录写权限都可用才返回 HTTP 200，否则
+  HTTP 503；`data.database`、`data.redis`、`data.uploads` 可直接定位失败项。
+
+SIGTERM 触发 Uvicorn 优雅关闭；compose 给 API 40 秒清理在途请求和连接池。
+
+### 容器验证边界
+
+本次仓库内的实际容器运行验证使用 Apple Container 1.0.0，覆盖镜像构建、隔离 MySQL
+迁移、双 API worker、独立 jobs、Nginx 路由、只读文件系统、上传卷和 SIGTERM 优雅
+关闭。`docker-compose.yml` 已通过 YAML 解析和自动化部署断言，但当前验证主机没有执行
+`docker compose up`，因此不能把 Apple Container 的运行结果表述为 Docker Compose
+端到端通过。镜像摘要、实际命令和运行结果见
+`docs/manager-api-fastapi-test-report.md`；在目标 Docker/Compose 环境切流前，仍需按上面
+命令执行一次迁移、ready 检查和 Nginx upstream 冒烟测试。
+
+## 灰度切流
+
+1. 备份当前配置并确认 Java 基线健康；不要停止 Java。
+2. 对目标数据库执行原 Liquibase runner，确认 changeset 数量和校验和无差异。
+3. 启动 FastAPI API 但暂不接写流量，检查 live/ready、日志和外部 mock。Python jobs
+   只在隔离环境验证后停止，生产中暂不持续运行，避免与 Java 调度器同时写入。
+4. 先镜像或回放脱敏的只读请求，比较状态、Body、Header、数据库读结果和缓存读取。
+5. 按业务域把只读流量从 1% 提升到 10%、50%、100%，监控错误码、P95、数据库连接、
+   Redis 命中与外部服务错误。
+6. 对一个完整业务域建立维护窗口，停止该域 Java 新写入，等待在途事务结束，然后把该域
+   写路由切到 FastAPI。记录切换时间和最后写入方。
+7. 逐域重复；稳定观察期内保留 Java 镜像、配置和回切路由。
+8. 所有域稳定后才把 jobs 所有权切给 Python；Java 的定时任务进程必须同时停用，避免
+   两套调度器并行。
+
+## 回滚
+
+1. 冻结待回滚业务域的新写入，等待 FastAPI 在途请求和 jobs 当前轮次结束。
+2. 停止 Python jobs，确认 Redis 分布式锁已释放；不要清空 Redis。
+3. 将该域的 Nginx upstream 切回原 Java `manager-api`，保持 `/xiaozhi` 路径不变。
+4. 用 Java 健康检查和代表性读请求确认 Token、缓存、上传文件与数据库数据可读。
+5. 恢复 Java 写流量并记录回滚边界；不要让 FastAPI 继续写该域。
+6. 若问题来自新 changeset，只能新增一个经评审的 Liquibase 前向修复；不得删除或改写
+   `DATABASECHANGELOG` 历史。
+
+容器整服务回滚时，先把 `<JAVA_UPSTREAM>` 替换为 Nginx 容器可访问的真实地址，再只
+重建代理；`--no-deps` 可避免回滚命令意外重启 FastAPI 或重复执行迁移：
+
+```bash
+MANAGER_API_UPSTREAM='<JAVA_UPSTREAM>:8002' \
+  docker compose up -d --no-deps --force-recreate manager-api-nginx
+```
+
+FastAPI 没有改变现有 schema，且 Redis 写入采用 Java 兼容格式，因此正常应用回滚不需要
+数据反向迁移。若外部系统已接收不可撤销操作，按对应供应商的业务补偿流程处理，不能用
+数据库回滚伪造外部成功或失败。
+
+## 隔离验证
+
+`scripts/isolated-env.sh` 只创建 `manager_java_test`、`manager_fastapi_test` 两个测试库和
+端口 `16379` 上的独立 Redis；其中的测试密码仅用于本机隔离环境。标准流程是：
+
+```bash
+cd main/manager-api-fastapi
+./scripts/isolated-env.sh start
+./scripts/isolated-env.sh reset
+./scripts/isolated-env.sh migrate
+eval "$(./scripts/isolated-env.sh env)"
+.venv/bin/pytest -m integration -q
+./scripts/isolated-env.sh stop
+```
+
+实际执行结果、差分用例和不能使用真实凭证完成的联调项记录在
+`docs/manager-api-fastapi-test-report.md`；逐接口状态记录在
+`docs/manager-api-fastapi-compatibility.md`。

docs/manager-api-fastapi-test-report.md

@@ -0,0 +1,582 @@
+# manager-api FastAPI 迁移测试报告
+
+> 执行日期：2026-07-20（Asia/Shanghai）
+>
+> 工作目录：`/Users/mie/Desktop/Repo/xiaozhi-esp32-server`
+>
+> FastAPI 目标：`main/manager-api-fastapi`
+> Java 基线：`main/manager-api`
+
+本报告只记录实际执行并有输出或落盘证据的检查。结构路由闭合、154 条未认证/非法请求面
+差分、154 条已认证安全业务/校验差分、领域测试和 49 条深度 Java/FastAPI 差分是不同强度
+的证据，不互相替代。生产外部服务和真实硬件没有验证的部分，均不会写成通过。
+
+## 1. 结果摘要
+
+| 检查项 | 通过 | 失败/错误 | 跳过 | 结论 |
+|---|---:|---:|---:|---|
+| Java 基线测试 | 98 | 0 | 0 | 最终复跑 `BUILD SUCCESS`，15.602 秒 |
+| FastAPI 全量 pytest（最终回归） | 139 | 0 | 0 | 12.75 秒；含上传卷 readiness 与证据脱敏回归 |
+| 隔离 MySQL/Redis 集成测试复跑 | 7 | 0 | 0 | 事务、锁、TTL、job 单实例与 watchdog 全绿 |
+| Java→FastAPI 未认证/非法请求面差分 | 154 | 0 | 0 | 每条 Java 路由各 1 个无成功写入的缺认证或非法请求，逐项比较 status/body/Content-Type |
+| Java→FastAPI 已认证安全业务/校验差分 | 154 | 0 | 0 | 每条 Java 路由各 1 个带正确认证的安全业务或校验请求；runner 有意不执行成功写入 |
+| Java→FastAPI 深度差分契约 | 49 | 0 | 0 | 成功、主要错误与数据库副作用；直接覆盖 21/154 条 Java 路由 |
+| 简单性能测试 | 480 请求 | 0 请求错误 | 不适用 | 4 场景 × 2 服务 × 60 次计量请求 |
+| Java 路由结构清单 | 154/154 | 0 | 0 | FastAPI 注册闭合；结构证据，不等同逐接口行为证据 |
+| 三端消费者调用点 | 188/188 | 0 | 0 | Web 134、Mobile 46、xiaozhi-server 8 个调用点均可解析 |
+| FastAPI Ruff | 通过 | 0 | 不适用 | `app tests scripts` |
+| FastAPI mypy | 70 个源文件 | 0 | 不适用 | strict 配置下通过 |
+| FastAPI compileall | 通过 | 0 | 不适用 | `app tests scripts` |
+| 锁文件与依赖同步 | 通过 | 0 | 不适用 | locked 环境共 55 packages |
+| Python sdist/wheel | 2 个产物 | 0 | 不适用 | 冷环境完整依赖安装后可导入，路由数 163 |
+| manager-web | i18n、5 unit、13 snapshot、build 全过 | 0 | 0 | build 有 4 条既有 size/precache warning |
+| manager-mobile | type、lint、14 snapshot、mp-weixin build 全过 | 0 | 0 | 使用仓库声明的 pnpm 10.10.0 |
+| xiaozhi-server | compileall 通过 | 0 | 不适用 | 除性能脚本外没有自动单测；8 个调用由 consumer 契约检查 |
+| 真实付费/生产外部服务 | 0 | 不适用 | 不适用 | 无真实凭证，不声称联调通过 |
+| 容器迁移、API、jobs 与 Nginx | 通过 | 0 | 0 | Apple Container 1.0.0 实际 build/run；Compose 仅做静态验证，未伪装为 `docker compose up` |
+
+最终可重复执行的全量测试、隔离差分、集成、构建和容器运行验证均为绿色。以下范围限制必须
+与绿色测试分开陈述：
+
+1. 全部 154 条 Java 路由均执行了两次差分：一次未认证/非法请求，一次已认证安全业务/校验
+   请求。第二个 runner 为保护隔离 fixture，有意不执行成功写入；49 个深度 checks 直接命中
+   21 条路由并覆盖代表性成功、错误和数据库副作用。因此两层全路由差分仍不等同于每条路由
+   的完整成功写入生命周期和全部错误路径差分。
+2. 没有真实凭证、生产网络或硬件的外部集成未被计入通过。
+
+## 2. 验证环境
+
+| 组件 | 实际版本/配置 |
+|---|---|
+| 主机 | macOS 27.0，arm64 |
+| Java | Oracle JDK 21.0.11 LTS |
+| Maven | 3.9.9，使用仓库 `.runtime/m2` |
+| Python | 3.10.20，`main/manager-api-fastapi/.venv` |
+| MySQL | Community Server 8.0.46；隔离端口 `13316` |
+| Redis | 8.8.0；隔离端口 `16379` |
+| Node.js | v24.18.0 |
+| npm | 11.16.0 |
+| manager-mobile pnpm | Corepack 解析的 10.10.0 |
+| OCI runtime | Apple Container 1.0.0；本机没有可用 Docker/Podman daemon |
+| 容器架构 | linux/arm64 |
+| 时区 | Asia/Shanghai |
+
+隔离测试只重置 `manager_java_test`、`manager_fastapi_test` 两个测试 schema 和端口
+`16379` 上的专用 Redis；没有连接、修改或清空开发 MySQL/Redis。Java 差分使用 Redis DB 1，
+FastAPI 使用 DB 2；Java 单元验证显式使用 DB 3。
+
+## 3. 实际执行命令
+
+### 3.1 Java 基线
+
+```bash
+cd main/manager-api && \
+JAVA_HOME=../../.runtime/jdk \
+PATH="../../.runtime/jdk/bin:../../.runtime/maven/bin:$PATH" \
+../../.runtime/maven/bin/mvn -o \
+  -Dmaven.repo.local=../../.runtime/m2 \
+  -Dspring.datasource.druid.url='jdbc:mysql://127.0.0.1:13316/manager_java_test?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&nullCatalogMeansCurrent=true&allowMultiQueries=true' \
+  -Dspring.datasource.druid.username=xiaozhi_test \
+  -Dspring.datasource.druid.password=isolated-test-only \
+  -Dspring.data.redis.host=127.0.0.1 \
+  -Dspring.data.redis.port=16379 \
+  -Dspring.data.redis.database=3 \
+  -Dspring.data.redis.password= \
+  -DskipTests=false test
+```
+
+最终复跑结果：98 tests，0 failures，0 errors，0 skipped，`BUILD SUCCESS`，15.602 秒。Surefire
+XML 位于 `main/manager-api/target/surefire-reports/`，各 suite 的 tests 合计为 98。
+
+### 3.2 FastAPI 全量测试
+
+```bash
+cd main/manager-api-fastapi && \
+eval "$(./scripts/isolated-env.sh env)" && \
+APP_DATABASE_URL="$TEST_FASTAPI_DATABASE_URL" \
+APP_REDIS_URL="$TEST_FASTAPI_REDIS_URL" \
+APP_ENVIRONMENT=test \
+.venv/bin/pytest -q
+```
+
+最终结果：139 passed、0 failed、0 skipped，12.75 秒。
+
+### 3.3 隔离集成、两层全路由差分、深度差分和性能测试
+
+```bash
+cd main/manager-api-fastapi && ./scripts/run-isolated-contract-tests.sh
+```
+
+最终执行结果为 exit 0。脚本实际完成以下阶段：
+
+- 启动并重置隔离 MySQL `13316`、Redis `16379`；
+- 对 Java 与 FastAPI 两个 schema 分别执行原 Liquibase 101 个 changeSets；
+- 启动 Java 基线 `18082`、FastAPI `18083`、确定性外部 mock `18084`；
+- 生成并镜像固定用户、DB Token、Long ID、设备、agent、模型、纠错词和 OTA fixture；
+- 执行 7 条隔离集成测试；
+- 对 154 条 Java 路由各执行一条未认证或非法的安全请求面差分，不产生成功写入；
+- 对 154 条 Java 路由各执行一条带正确认证的安全业务或校验差分，仍不产生成功写入；
+- 执行 49 条 Java/FastAPI 差分检查并写入 JSON；
+- 执行 480 次计量性能请求并写入 JSON；
+- 对 FastAPI/mock 日志执行 warning、traceback、error 门禁；
+- 退出时关闭 Java、FastAPI 和 mock，最终 `18082`～`18084` 没有监听进程。
+
+最终阶段摘要（两行 154 分别对应未认证/非法和已认证安全业务/校验）：
+
+```text
+7 passed
+{"total": 154, "passed": 154, "failed": 0, "skipped": 0}
+{"total": 154, "passed": 154, "failed": 0, "skipped": 0}
+{"total": 49, "passed": 49, "failed": 0, "skipped": 0}
+{"measurements": 8, "requests_measured": 480, "errors": 0}
+Isolated integration, two 154-route surfaces, deep differential, and performance tests passed.
+```
+
+机器结果：
+
+- `main/manager-api-fastapi/compatibility/route-surface-results.json`
+  - 生成时间：`2026-07-20T07:12:28.099864+00:00`
+  - 154 passed、0 failed、0 skipped
+- `main/manager-api-fastapi/compatibility/authenticated-route-results.json`
+  - 生成时间：`2026-07-20T07:12:30.818073+00:00`
+  - 154 passed、0 failed、0 skipped
+- `main/manager-api-fastapi/compatibility/contract-results.json`
+  - 生成时间：`2026-07-20T07:12:31.520810+00:00`
+  - 49 passed、0 failed、0 skipped
+- `main/manager-api-fastapi/compatibility/performance-results.json`
+  - 生成时间：`2026-07-20T07:12:33.158826+00:00`
+  - 480 requests、0 errors
+
+### 3.4 FastAPI 静态、依赖和构建验证
+
+```bash
+cd main/manager-api-fastapi
+.venv/bin/ruff check app tests scripts
+.venv/bin/mypy app
+.venv/bin/python -m compileall -q app tests scripts
+uv lock --check && uv sync --locked
+uv build --no-cache
+```
+
+结果：
+
+- Ruff 通过；
+- mypy：70 个源文件无问题；
+- compileall：exit 0；
+- lock check 与 locked sync：exit 0，共 55 packages；
+- 无缓存构建 sdist 与 wheel 均成功。
+
+构建产物另在临时冷虚拟环境验证。首次执行 `uv pip install --python
+<临时环境>/bin/python --no-deps <wheel>` 后直接 import，因刻意没有安装 FastAPI 等运行依赖而
+失败；这暴露的是冷 wheel 检查命令不完整，不是把失败隐藏为通过。随后执行带依赖的安装：
+
+```bash
+uv pip install --python <临时环境>/bin/python <wheel>
+```
+
+共安装 39 个锁定依赖。从仓库外 `/tmp` 导入成功，输出
+`xiaozhi-manager-api 163`，证明不是依赖当前工作目录导入源码。
+
+### 3.5 manager-web
+
+```bash
+cd main/manager-web && \
+npm run check:i18n && \
+npm run test:unit && \
+npm run test:snapshot && \
+npm run build
+```
+
+结果：
+
+- i18n：6 个 locale，每个 1527 keys，key 结构一致；
+- unit：5/5；
+- snapshot：13/13；
+- Vue 生产构建 exit 0（hash `71b64d002eb434ee`，1069 ms）；
+- 输出有 4 条既有 bundle size/precache warning，没有将 warning 写成失败，也没有删除或放宽
+  测试来取得绿色结果；另有 `caniuse-lite` 数据过期 17 个月提示，未擅自更新依赖。
+
+### 3.6 manager-mobile
+
+```bash
+cd main/manager-mobile && \
+corepack pnpm type-check && \
+corepack pnpm lint && \
+corepack pnpm test:snapshot && \
+corepack pnpm build:mp
+```
+
+结果：type-check exit 0、lint exit 0、snapshot 14/14、mp-weixin build exit 0。构建提示
+`caniuse-lite` 数据过期 20 个月及 uni-app 有新版本；两项均不影响退出码，未擅自更新依赖。
+
+一次较早的失败尝试直接调用普通 `pnpm`，环境解析到 v11，并因非 TTY 下依赖目录清理提示而
+终止；没有把该次尝试写成通过。最终命令显式使用 Corepack，解析到仓库声明的 pnpm 10.10.0。
+
+### 3.7 xiaozhi-server
+
+```bash
+cd main/xiaozhi-server && \
+../manager-api-fastapi/.venv/bin/python --version && \
+PYTHONPYCACHEPREFIX=/tmp/xiaozhi-server-pycache \
+  ../manager-api-fastapi/.venv/bin/python -m compileall -q . && \
+rg --files -g '*test*.py' -g '!performance_tester/**'
+```
+
+结果：Python 3.10.20，compileall exit 0。排除性能测试目录后没有自动单测文件，因此没有虚构
+pytest 通过数量；`xiaozhi-server` 的 8 个 manager-api 调用点由 consumer manifest 和 FastAPI
+兼容测试验证为可解析。
+
+首次误用不存在的 `../../.runtime/python/bin/python3.10`，结果为 exit 127；改用上面实际存在的
+FastAPI Python 3.10.20 后通过。
+
+## 4. 两层全路由差分与深度差分覆盖
+
+### 4.1 154 条未认证/非法安全请求面差分
+
+`tests/compatibility/route_surface_runner.py` 从 Java route manifest 逐条构造不发生成功写入的请求：
+133 条 DB Token 路由省略 Token，14 条匿名路由发送安全非法输入，7 条内部路由省略
+server-secret。Java 与 FastAPI 精确比较 HTTP status、解析后的 body 和 Content-Type；最终
+154 passed、0 failed、0 skipped。它证明每条 Java 路由至少有一个请求路径兼容，不代表每条
+路由的成功、全部错误与数据库副作用均已逐项对照。
+
+### 4.2 154 条已认证安全业务/校验差分
+
+`tests/compatibility/authenticated_route_runner.py` 使用与 Java 基线语义一致的 DB Token、
+server-secret 或匿名认证方式，对同一份 154 路由清单逐条发送安全业务/校验请求。runner 对
+动态管理员密码和 OTA 下载 UUID 先独立验证格式再做最小归一化，并同步会影响响应的固定审计
+时间；最终 154 passed、0 failed、0 skipped。为不污染 fixture 或产生不可逆副作用，该 runner
+有意选择资源不存在、单一约束失败、幂等空操作等不会成功写入的路径。因此这里的“已认证”
+证明请求已经越过认证层并进入业务/校验逻辑，不表示每条写接口都完成了一次成功写入。
+
+### 4.3 49 项深度结果分布
+
+| 类别 | 通过 | 失败 |
+|---|---:|---:|
+| configuration | 1 | 0 |
+| authentication-i18n | 7 | 0 |
+| authentication | 1 | 0 |
+| authorization | 1 | 0 |
+| serialization | 2 | 0 |
+| agent | 1 | 0 |
+| device | 1 | 0 |
+| model | 1 | 0 |
+| correct-word | 1 | 0 |
+| binary-download | 6 | 0 |
+| validation | 5 | 0 |
+| server-secret | 3 | 0 |
+| ota | 1 | 0 |
+| ota-validation | 2 | 0 |
+| ota-signing | 2 | 0 |
+| activation | 3 | 0 |
+| external-mock | 2 | 0 |
+| crud | 3 | 0 |
+| database-side-effect | 4 | 0 |
+| upload | 1 | 0 |
+| upload-validation | 1 | 0 |
+| **合计** | **49** | **0** |
+
+直接覆盖内容包括：
+
+- 默认语言、`zh-CN`、`zh-TW`、`en-US`、`de-DE`、`vi-VN`、`pt-BR` 七种
+  `Accept-Language` 情形；
+- 未登录、DB Token 过期、普通用户访问管理员接口；
+- Long ID 字符串、日期、Asia/Shanghai/UTC 兼容、null、别名和分页；
+- 缺字段、数字格式、最小/最大边界和 Java UTF-16 长度语义；
+- server-secret 缺失、错误和正确三条路径；
+- OTA health、缺失/非法 `Device-Id`、激活、WS/MQTT credential；
+- HMAC-SHA256、URL-safe Base64、MQTT Base64 密码的独立密码学验证；
+- 纠错词创建、更新、下载、删除及数据库副作用；
+- OTA multipart 上传、扩展名错误、元数据副作用、三次下载与第四次 404；
+- 二进制 MIME、`Content-Disposition`、`Content-Length` 和字节摘要；
+- MQTT mock 的请求 body 和按日期生成的 Authorization。
+
+### 4.4 有意的动态值处理
+
+- OTA timestamp、WebSocket token 和生成 UUID 先做最小范围归一化，再分别验证格式与 HMAC；
+  不是把动态字段全部忽略。
+- Hibernate Validator 使用无序 `ConstraintViolation Set`。模型 provider 空 body 用例要求
+  Java/FastAPI 均返回 HTTP 200、错误码 10034，消息必须属于 Java DTO 声明的五个精确约束，
+  不强行固定 Java 本身不稳定的首条消息。
+- 报告落盘前递归脱敏 `private_key`、server secret、MQTT signature key、Token、password 和
+  Authorization；比较与密码学验证仍使用未脱敏的内存值。
+
+### 4.5 覆盖边界
+
+Java 清单共有 154 条路由，FastAPI 结构注册为 154/154；另有 3 条消费者兼容路由。全部 154
+条均有一次未认证/非法差分和一次已认证安全业务/校验差分；49 个深度 checks 直接命中
+21/154 条 Java 路由，并对代表性成功、主要错误和数据库副作用做更完整的生命周期验证。
+其余路由虽有两层逐路由差分及相关领域 service/repository/protocol 测试，仍不能宣称其全部
+成功写入和错误路径均已逐项深度差分。逐行状态见
+`docs/manager-api-fastapi-compatibility.md`。
+
+## 5. 隔离数据库、Redis 和 job 测试
+
+7 条集成测试均连接隔离 MySQL/Redis，而不是纯 mock：
+
+1. MySQL 事务异常回滚；
+2. `SELECT FOR UPDATE` 在并发写入下串行化；
+3. Redis key TTL 到期且不删除无关 key；
+4. Redis 分布式锁只允许一个并发 job 执行；
+5. watchdog 在任务超过原始 lease 后续租，仍保持单实例；
+6. 实际 knowledge job 函数在 Redis 锁下只执行一次；
+7. Java hash 兼容写入的默认 TTL 为 86400 秒。
+
+差分 CRUD 另检查 Java/FastAPI 各自隔离 schema 的行级副作用；没有实施双写，也没有操作开发
+数据库。最终 FastAPI 与 external mock 日志没有 warning/error/traceback。两层全路由差分会
+让 Java 基线按其既有全局异常处理记录 36 条预期 ERROR，严格门禁将其精确分为 8 类：缺 body
+13 条、缺 `Device-Id` 5 条、对象/数组反序列化 8 条、缺 query 4 条、非 multipart 3 条、
+`callerMac` 空值 1 条、空消息 1 条及 `null` 消息 1 条。未分类 Java ERROR 为 0；任一类别数量
+变化或出现未分类日志都会使脚本失败。
+
+## 6. 性能对比
+
+参数：每个服务每场景先顺序 warmup 10 次，再以并发 6 计量 60 次；4 个场景、2 个服务共
+480 次计量请求。结果来自最终 `performance-results.json`：
+
+| 场景 | 服务 | p50 ms | p95 ms | 吞吐 req/s | 错误 |
+|---|---|---:|---:|---:|---:|
+| representative-read | Java | 7.662 | 16.239 | 601.128 | 0 |
+| representative-read | FastAPI | 6.749 | 12.552 | 751.538 | 0 |
+| representative-crud-update | Java | 9.331 | 15.302 | 543.013 | 0 |
+| representative-crud-update | FastAPI | 11.252 | 20.599 | 476.870 | 0 |
+| runtime-configuration | Java | 8.746 | 16.127 | 568.863 | 0 |
+| runtime-configuration | FastAPI | 6.488 | 13.722 | 765.126 | 0 |
+| ota-check-and-signing | Java | 11.301 | 19.854 | 454.655 | 0 |
+| ota-check-and-signing | FastAPI | 16.208 | 20.344 | 354.807 | 0 |
+
+FastAPI/Java 比率：读取 p50 `0.881`、p95 `0.773`、吞吐 `1.250`；CRUD p50 `1.206`、
+p95 `1.346`、吞吐 `0.878`；配置 p50 `0.742`、p95 `0.851`、吞吐 `1.345`；OTA p50
+`1.434`、p95 `1.025`、吞吐 `0.780`。因此不能笼统声称所有 FastAPI 接口都更快：本轮读取和
+配置场景更快，CRUD p50/p95 分别较慢约 20.6%/34.6%，OTA p50 较慢约 43.4%、p95 接近、
+吞吐低约 22.0%。
+
+这是同机、短时、固定 fixture 的简单对比，用于发现数量级回退，不是容量、长稳、生产网络或
+多 worker 极限测试。
+
+## 7. 三端兼容验证
+
+- `manager-web`：134 个调用点、130 条唯一结构路由；i18n、unit、snapshot 与 production build
+  均通过，现有调用无需修改 URL。
+- `manager-mobile`：46 个调用点、40 条唯一结构路由；type-check、lint、snapshot 与微信小程序
+  build 均通过。
+- `xiaozhi-server`：8 个调用点、8 条唯一结构路由；compileall 通过，consumer manifest 确认
+  全部能解析到 FastAPI。该模块没有可执行的一般单测，不能把 compileall 写成运行时集成通过。
+
+三端合计 188 个调用点、140 条唯一结构路由。此结论证明 path/method 解析闭合；全部 Java
+路由另有未认证/非法和已认证安全业务/校验两层差分，参与 49 项深度差分或领域测试的调用拥有
+更完整的成功、错误或副作用证据。
+
+## 8. 迁移验证过程中发现并修正的问题
+
+测试没有通过删除、跳过或放宽失败用例获得绿色。差分在实现过程中实际暴露并促成修复的兼容
+问题包括：分页 `total` 类型、运行时配置字段查询、设备日期时区、认证与 OTA MIME、缺失
+`Device-Id` envelope、provider 校验语义、非法分页消息、运行时配置 key 命名。修复后才生成
+当前 49/49 深度报告。
+
+154 路由请求面 runner 首次执行只有 149/154 通过，准确暴露 5 条“整个 JSON body 缺失”差异：
+`POST /ota/`、`POST /user/login`、`POST /user/register`、
+`POST /user/retrieve-password`、`POST /user/smsVerification`。Java 对整个 body 缺失返回
+HTTP 200、`code=500` 的通用 envelope，FastAPI 当时返回 `code=10034`。全局校验兼容层随后
+只对定位恰为 body 根节点的 missing 错误映射 `code=500`，字段级 missing 仍保持 `10034`；
+新增回归用例并完整重跑后才得到 154/154。
+
+已认证安全业务/校验 runner 首次执行为 111/154，通过实际差分先后修正了根 body 类型、必填
+query/multipart 的 Java envelope、knowledge/device/agent/voice resource 的检查顺序、权限与资源
+不存在语义，以及 DTO 单约束消息等差异；后续结果依次为 149/154、152/154，最终才达到
+154/154。对 Hibernate Validator 无序约束的请求，runner 改用只触发一个约束的定向 payload，
+没有跳过路由、忽略响应字段或放宽比较。该 runner 始终保持“已认证但不成功写入”的安全边界。
+
+另有测试基础设施、运行时和构建问题被明确记录：
+
+- Pydantic 2.13 与 FastAPI 0.116 的 TypeAdapter alias 路径产生
+  `UnsupportedFieldAttributeWarning`；依赖锁定到 Pydantic 2.11.7/core 2.33.2 后，实际 OTA
+  body alias 验证与最终日志门禁均无 warning。
+- 第一版日志门禁把 Logback 初始化文本 `ERROR_FILE` 误判为运行时 ERROR，虽然 7、49、480
+  阶段均绿，脚本仍按门禁返回 1。正则收紧为带完整日期的 Java 应用 ERROR 后，重新从头执行
+  完整流程并获得 exit 0；没有直接忽略门禁失败。
+- fixture 的 MySQL `VALUES()` upsert 产生 8.0 弃用 warning；改为 row alias 语法并重新执行后
+  无该 warning。
+- 已认证差分报告最初虽未含真实凭证，但 `paramCode=server.secret` / `paramValue` 结构仍写入了
+  隔离 fixture 值；递归脱敏器补充键值对识别及回归测试后，再次完整执行差分。最终四份 JSON
+  对 `contract-server-secret`、测试 Token 和测试数据库密码的扫描均为 0 命中。
+- Python 3.10 下 fixed-delay jobs 等待超时抛出 `asyncio.TimeoutError`；原捕获路径导致 worker
+  首轮后退出。worker 改为捕获该异常并增加 Python 3.10 回归测试；实际 jobs 容器随后观察到
+  knowledge job 跨 30 秒重复运行，snapshot redaction 多轮执行，SIGTERM 后干净退出。
+- API 镜像构建初期遇到 uv/pip registry 传输失败；Dockerfile 固定 uv 版本并增加 timeout、retry
+  与缓存后完成构建。迁移镜像的 Maven Central 并发下载两次卡住，改为串行 resolver、超时与
+  retry 后成功。Nginx 初版配置在镜像 build 期校验失败，改用 template + `envsubst` 并在 build
+  内执行 `nginx -t` 后通过。
+- Apple Container 自定义网络没有提供本次验证所需的容器名 DNS，host publish 和单文件挂载也
+  与 Docker 行为不同；验证改用容器 IP、显式 TCP bridge、named volume 和运行时 upstream 模板。它们
+  是测试 runtime 限制，不被记作应用通过或失败，也没有据此声称 Docker Compose 已实际启动。
+
+## 9. 外部服务与真实联调状态
+
+所有自动化外部调用只访问本地确定性 mock/fixture，不访问真实付费服务。
+
+| 外部能力 | 自动化证据 | 真实联调状态 |
+|---|---|---|
+| RAGFlow dataset/document/chunk/retrieval/upload | 请求 JSON/query/header、30 秒 timeout、强 DTO、Long/null、错误映射与补偿路径测试 | 无真实 RAGFlow 凭证/实例，未联调 |
+| 阿里云短信 | 配置、错误 envelope 与业务路径测试 | 无真实 AccessKey，不发送短信，未联调 |
+| 火山语音克隆/音频 | multipart/JSON、状态及错误映射 mock | 无真实付费凭证，未联调 |
+| 声纹 HTTP | Java multipart 形状与错误映射 mock | 无真实声纹服务，未联调 |
+| OpenAI-compatible LLM | 请求格式、thinking policy、摘要/标题相关 mock | 无真实模型 key，不访问付费模型，未联调 |
+| MQTT gateway HTTP | 差分验证 body、按日期 Authorization 和 401 retry 语义 | 无真实 MQTT broker/gateway，未联调 |
+| MCP/管理 WebSocket | token、URL、path/scheme/form 兼容测试 | 无真实远端 MCP/WS，未联调 |
+| OTA/WS/MQTT credential | 本地 HMAC/Base64/时间戳和下载行为实测 | 无 ESP32 真机和生产 broker，不属于硬件联调 |
+
+因此，本报告只证明 mock 下已覆盖的请求格式、超时、错误映射、重试和本地密码学行为；不能把
+任何一项写成供应商或生产环境端到端通过。
+
+## 10. 已知行为/部署差异
+
+- Java 的 Hibernate Validator 首条约束消息顺序不稳定；FastAPI 保持相同 envelope、错误码和
+  声明消息集合，而不是伪造固定顺序。
+- Java 在 Spring 进程内运行定时任务；FastAPI 把 jobs 分离为独立进程，并用 Redis 锁和
+  watchdog 防止多 worker 重复执行。集成测试验证单实例和续租语义，但部署拓扑有意不同。
+- FastAPI 增加 3 条消费者兼容路由和 live/ready health endpoints；它们没有 Java Controller
+  基线，属于明确的加法差异。
+- 49 项已执行深度差分中没有观测到响应、所选 header 或数据库副作用差异；这句话只适用于
+  报告中的 49 项，不外推为全部 154 条路由均完成了成功写入和全部错误路径生命周期验证。
+
+## 11. 实际容器与 Nginx 验证
+
+### 11.1 Runtime、镜像与 Compose 口径
+
+本机没有可用的 Docker/Podman daemon，实际 OCI build/run 使用 Apple Container 1.0.0 的
+linux/arm64 VM，并显式使用隔离 app/log/install root：
+
+```bash
+CLI=/Users/mie/.cache/xiaozhi-migration-tools/container-1.0.0-prefix/bin/container
+ROOT=/Users/mie/.cache/xiaozhi-migration-tools/container-1.0.0-prefix
+"$CLI" system start \
+  --app-root "$ROOT/runtime-data" \
+  --install-root "$ROOT" \
+  --log-root "$ROOT/runtime-logs" \
+  --disable-kernel-install
+"$CLI" builder start
+"$CLI" build --tag xiaozhi/manager-api-fastapi:0.1.0 \
+  --file main/manager-api-fastapi/Dockerfile .
+"$CLI" build --tag xiaozhi/manager-api-migrate:fastapi-0.1.0 \
+  --file main/manager-api-fastapi/Dockerfile.migrations .
+"$CLI" build --tag xiaozhi/manager-api-nginx:fastapi-0.1.0 \
+  --file main/manager-api-fastapi/Dockerfile.nginx .
+```
+
+三张镜像均实际构建并运行。迁移镜像 OCI index 为
+`sha256:613faace4314b03392e65b64d9b4a9ba7a694cdd751c1a45009824d55f0647f7`，其 arm64
+manifest 为 `sha256:6a10850841370d033a3b521fbb1100cb64b5cc6837fac35d00c4257343c0f2f9`；
+Nginx 镜像 OCI index 为
+`sha256:2e6a188ad6d38b62fa4e77329a629ada00c4e773da9ded73c5f3289e40da477a`，其 arm64
+manifest 为 `sha256:ff653bc2d11d4a3b1640747626055d6551fb33324500fb2e65b9333142da8526`。
+API 镜像在上传目录 readiness 最后一处源码变更后重新 build；最终 OCI index 为
+`sha256:04ae1a98307b7369368b9665c6caf9f0911c8b2a967f5a91f23c6dde7c7baa16`，其 arm64
+manifest 为 `sha256:c3267d307c9898975372539121f118549bfe51012c6c9bfdc3e84f99f3e56214`，
+config 为 `sha256:7c0b13757da041c0d118d14342e92c5310e4fb2140f029e385e97de9fe21d8cc`，
+manifest size 为 84,551,252 bytes，镜像配置创建时间为 `2026-07-20T07:04:45Z`。
+
+`docker-compose.yml` 已由 `tests/test_deployment_artifacts.py` 静态验证 migration dependency、
+read-only root、tmpfs、upload volume、healthcheck、graceful timeout 与可切换 upstream；Nginx
+镜像 build 内也实际执行 `nginx -t`。由于本机没有 Docker Compose runtime，本报告明确只把
+Compose 记为静态通过，不声称执行过 `docker compose up`。
+
+### 11.2 Liquibase migration
+
+迁移镜像以 UID 10001 一次性运行，只读取原 Java resources 内的 Liquibase 历史。目标为隔离
+schema `manager_container_test`；最终容器回归中再次运行并报告 101 个 changeSets 均
+up-to-date。随后实查 `DATABASECHANGELOG` 为 101 条、业务及 Liquibase 表合计 30 张，
+`DATABASECHANGELOGLOCK.LOCKED=0`，证明历史完整且锁已释放。没有连接、修改或清空开发数据库。
+
+### 11.3 API、jobs、health、卷与优雅关闭
+
+Apple Container VM 访问 host-only MySQL/Redis 时使用仓库内 TCP bridge，而不是暴露开发服务：
+
+```bash
+cd main/manager-api-fastapi
+.venv/bin/python -m tests.compatibility.tcp_proxy \
+  --listen-port 13317 --target-host 127.0.0.1 --target-port 13316
+.venv/bin/python -m tests.compatibility.tcp_proxy \
+  --listen-port 16380 --target-host 127.0.0.1 --target-port 16379
+```
+
+API 容器使用 `APP_WORKERS=2`、隔离 schema、Redis DB 4、read-only root、`/tmp` tmpfs 和
+named upload volume 启动。实测结果：
+
+- 容器内 UID 为 10001，最终层没有 `/bin/uv` 和 `/usr/bin/gcc`，应用路由数为 163；
+- 日志确认 2 个 Uvicorn worker（容器内 PID 3、4）；`/xiaozhi/health/live` 为 HTTP 200；
+- `Accept-Language: en-US` 的未认证业务请求保持 HTTP 200、英文 `{code:401,...}`；
+  `POST /xiaozhi/user/login` 整个 JSON body 缺失保持 Java 的 HTTP 200、`code=500`；
+- read-only root 生效。Apple Container 新建空 named volume 首次以其默认 root ownership 挂载，
+  新增 readiness 检查准确返回 HTTP 503、`database=true`、`redis=true`、`uploads=false`，没有让
+  无法上传的实例接流量；该失败没有伪装为通过。随后用一次性 root 容器仅对卷执行 `chown`
+  ownership 初始化，ready 变为 HTTP 200 且 `uploads=true`，UID 10001 的 API 成功写入，重启后
+  文件 SHA256 `1ad4cb4f879aa1ddf43a14e1a84cc5dbf8f65e91295165e126b8b08be3cd9a50` 保持不变；
+- 发送 SIGTERM 后 worker 完成 lifespan shutdown 并以 exit 0 退出，无 traceback/error。
+
+同一 API 镜像另以 `python -m app.jobs.worker`、read-only root 和 `/tmp` tmpfs 启动。实际等待
+超过 31 秒后，knowledge fixed-delay job 执行两次且相隔 30 秒，snapshot redaction 多次执行；
+这验证 Python 3.10 timeout 修复与真实调度循环。SIGTERM 后 jobs 也干净退出。API 多 worker
+本身不加载 jobs，独立 worker 再由 Redis lock/watchdog 保证单实例。
+
+上述 ownership 初始化是 Apple Container 空 named volume 的实测处理；本机没有 Docker
+Compose runtime，因此 Docker Compose 的 named-volume copy-up 行为没有实际验证，不能用
+Apple Container 的结果代替。
+
+### 11.4 Nginx 切流与 Java 回滚
+
+Nginx 镜像以 read-only root 和 `/var/cache/nginx`、`/var/run`、`/tmp` 三个 tmpfs 运行；其
+entrypoint 将 `MANAGER_API_UPSTREAM` 注入模板后 `exec nginx`。Apple Container 自定义网络在
+本次环境没有容器名 DNS，因此实测使用 runtime 分配的 API/Java 容器 IP，语义与生产 hostname
+upstream 相同。FastAPI upstream 下实际验证：
+
+- `/xiaozhi/health/ready` 为 HTTP 200；
+- `/xiaozhi` 精确返回 308 到 `/xiaozhi/`；
+- `Accept-Language: en-US` 的未认证 envelope 由 Nginx 转发后与直连 FastAPI 一致，整个 JSON
+  body 缺失也保持 HTTP 200、`code=500`；
+- Nginx、API 均在 SIGTERM 下以 exit 0 干净退出。
+
+随后仅替换 `MANAGER_API_UPSTREAM` 指向保留的 Java 容器并重建 Nginx 运行实例；`/xiaozhi/ota/`
+回滚探针的 response body 与直连 Java 按字节完全一致。此步骤证明回滚不需要删除 Java 服务、
+改数据库或双写，只需切换 upstream。Nginx 基础镜像未声明非 root USER，因此这里不虚构其
+non-root 属性；实际硬化证据是 read-only root、最小 tmpfs 和无持久写入。应用与迁移镜像则
+均以 UID 10001 运行。
+
+## 12. 证据文件
+
+- 逐接口矩阵：`docs/manager-api-fastapi-compatibility.md`
+- 迁移、切流与回滚说明：`docs/manager-api-fastapi-migration.md`
+- Java 路由清单：`main/manager-api-fastapi/compatibility/java-routes.json`
+- 三端调用清单：`main/manager-api-fastapi/compatibility/consumer-routes.json`
+- 154 路由未认证/非法请求面机器报告：
+  `main/manager-api-fastapi/compatibility/route-surface-results.json`
+- 154 路由已认证安全业务/校验机器报告：
+  `main/manager-api-fastapi/compatibility/authenticated-route-results.json`
+- 深度差分机器报告：`main/manager-api-fastapi/compatibility/contract-results.json`
+- 性能机器报告：`main/manager-api-fastapi/compatibility/performance-results.json`
+- 一键隔离脚本：`main/manager-api-fastapi/scripts/run-isolated-contract-tests.sh`
+- 未认证/非法请求面 runner：
+  `main/manager-api-fastapi/tests/compatibility/route_surface_runner.py`
+- 已认证安全业务/校验 runner：
+  `main/manager-api-fastapi/tests/compatibility/authenticated_route_runner.py`
+- 深度差分 runner：`main/manager-api-fastapi/tests/compatibility/differential_runner.py`
+- 外部 mock：`main/manager-api-fastapi/tests/compatibility/external_mock.py`
+- 集成测试：`main/manager-api-fastapi/tests/integration/test_isolated_runtime.py`
+- 容器静态断言：`main/manager-api-fastapi/tests/test_deployment_artifacts.py`
+- 容器网络 bridge：`main/manager-api-fastapi/tests/compatibility/tcp_proxy.py`
+- API/migration/Nginx 构建定义：`main/manager-api-fastapi/Dockerfile`、
+  `main/manager-api-fastapi/Dockerfile.migrations`、`main/manager-api-fastapi/Dockerfile.nginx`
+- Nginx runtime 配置：`main/manager-api-fastapi/deploy/nginx.conf`、
+  `main/manager-api-fastapi/deploy/nginx-entrypoint.sh`
+- Java Surefire：`main/manager-api/target/surefire-reports/`
+
+## 13. 当前结论
+
+Java 98、FastAPI 全量 139、隔离集成 7、未认证/非法请求面 154/154、已认证安全业务/校验
+154/154、深度差分 49/49、性能 480/0，以及 Web/Mobile 构建、xiaozhi-server compileall 和
+实际容器/Nginx 验证均按上述命令完成；各测试集合均为 0 failed、0 errors、0 skipped。原 Java
+服务和 Liquibase 历史均未删除。
+
+本地可安全执行的兼容、集成、构建、消费者和容器验证已经通过。每条 Java 路由虽已有两次
+全覆盖差分，但已认证 runner 有意不执行成功写入，所以不能将其表述为 154 条全部成功、错误
+和副作用生命周期均已深度验证；真实 RAGFlow、短信、语音克隆、声纹、模型、MQTT/MCP/WS
+及 ESP32 硬件因没有真实凭证或设备而未联调，也没有在本报告中描述为已通过。

docs/mcp-endpoint-enable.md

@@ -118,7 +118,7 @@ mcp_endpoint: ws://192.168.1.25:8004/mcp_endpoint/mcp/?token=def
 250705[__main__]-INFO-mcp接入点是        ws://192.168.1.25:8004/mcp_endpoint/mcp/?token=abc
 250705[__main__]-INFO-Websocket地址是    ws://192.168.1.25:8000/xiaozhi/v1/
 250705[__main__]-INFO-=======上面的地址是websocket协议地址，请勿用浏览器访问=======
-250705[__main__]-INFO-如想测试websocket请用谷歌浏览器打开test目录下的test_page.html
+250705[__main__]-INFO-如想测试websocket请启动digital-human模块，打开浏览器交互测试
 250705[__main__]-INFO-=============================================================
 ```
 

docs/mcp-endpoint-integration.md

@@ -23,7 +23,7 @@
 250705[__main__]-INFO-mcp接入点是        ws://192.168.1.25:8004/mcp_endpoint/mcp/?token=abc
 250705[__main__]-INFO-Websocket地址是    ws://192.168.1.25:8000/xiaozhi/v1/
 250705[__main__]-INFO-=======上面的地址是websocket协议地址，请勿用浏览器访问=======
-250705[__main__]-INFO-如想测试websocket请用谷歌浏览器打开test目录下的test_page.html
+250705[__main__]-INFO-如想测试websocket请启动digital-human模块，打开浏览器交互测试
 250705[__main__]-INFO-=============================================================
 ```
 

docs/mcp-vision-integration.md

@@ -58,7 +58,7 @@ docker restart xiaozhi-esp32-server
 2025-06-01 **** - 视觉分析接口是        http://192.168.4.7:8003/mcp/vision/explain
 2025-06-01 **** - Websocket地址是       ws://192.168.4.7:8000/xiaozhi/v1/
 2025-06-01 **** - =======上面的地址是websocket协议地址，请勿用浏览器访问=======
-2025-06-01 **** - 如想测试websocket请用谷歌浏览器打开test目录下的test_page.html
+2025-06-01 **** - 如想测试websocket请启动digital-human模块，打开浏览器交互测试
 2025-06-01 **** - =============================================================
 ```
 
@@ -133,7 +133,7 @@ docker restart xiaozhi-esp32-server
 2025-06-01 **** - 视觉分析接口是        http://192.168.4.7:8003/mcp/vision/explain
 2025-06-01 **** - Websocket地址是       ws://192.168.4.7:8000/xiaozhi/v1/
 2025-06-01 **** - =======上面的地址是websocket协议地址，请勿用浏览器访问=======
-2025-06-01 **** - 如想测试websocket请用谷歌浏览器打开test目录下的test_page.html
+2025-06-01 **** - 如想测试websocket请启动digital-human模块，打开浏览器交互测试
 2025-06-01 **** - =============================================================
 ```
 

docs/paddlespeech-deploy.md

@@ -91,7 +91,7 @@ TTS:
 ```py
 python app.py
 ```
-打开test目录下的test_page.html，测试连接和发送消息时paddlespeech端是否有输出日志
+启动`main/digital-human`下的`python start.py`后，打开`http://127.0.0.1:8006/index.html`，测试连接和发送消息时paddlespeech端是否有输出日志
 
 输出日志参考：
 ```

docs/readme/README_de.md

@@ -1,4 +1,4 @@
-[![Banners](docs/images/banner1.png)](https://github.com/xinnan-tech/xiaozhi-esp32-server)
+[![Banners](../images/banner1.png)](https://github.com/xinnan-tech/xiaozhi-esp32-server)
 
 <h1 align="center">Xiaozhi Backend-Service xiaozhi-esp32-server</h1>
 
@@ -10,14 +10,14 @@ Unterstützt MQTT+UDP-Protokoll, Websocket-Protokoll, MCP-Endpunkte und Stimmabd
 </p>
 
 <p align="center">
-<a href="./docs/FAQ.md">Häufige Fragen</a>
+<a href="../FAQ.md">Häufige Fragen</a>
 · <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/issues">Probleme melden</a>
-· <a href="./README.md#%E9%83%A8%E7%BD%B2%E6%96%87%E6%A1%A3">Deployment-Dokumentation</a>
+· <a href="../../README.md#%E9%83%A8%E7%BD%B2%E6%96%87%E6%A1%A3">Deployment-Dokumentation</a>
 · <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/releases">Release-Hinweise</a>
 </p>
 
 <p align="center">
-  <a href="./README.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-DFE0E5"></a>
+  <a href="../../README.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-DFE0E5"></a>
   <a href="./README_en.md"><img alt="README in English" src="https://img.shields.io/badge/English-DFE0E5"></a>
   <a href="./README_vi.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/Tiếng Việt-DFE0E5"></a>
   <a href="./README_de.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-DBEDFA"></a>
@@ -38,7 +38,7 @@ Geleitet vom Team von Professor Siyuan Liu (South China University of Technology
 </br>
 刘思源教授团队主导研发(华南理工大学)
 </br>
-<img src="./docs/images/hnlg.jpg" alt="South China University of Technology" width="50%">
+<img src="../images/hnlg.jpg" alt="South China University of Technology" width="50%">
 </p>
 
 ---
@@ -52,113 +52,98 @@ Möchten Sie die Nutzungseffekte sehen? Klicken Sie auf die Videos unten 🎥
 <table>
   <tr>
     <td>
-        <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
-         <picture>
+        <picture>
-           <img alt="响应速度感受" src="docs/images/demo9.png" />
+          <img alt="响应速度感受" src="docs/images/demo9.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1vchQzaEse" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1vchQzaEse" target="_blank">
-         <picture>
+        <picture>
-           <img alt="速度优化秘诀" src="docs/images/demo6.png" />
+          <img alt="速度优化秘诀" src="docs/images/demo6.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1C1tCzUEZh" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1WEcxzFEAT" target="_blank">
-         <picture>
+        <picture>
-           <img alt="复杂医疗场景" src="docs/images/demo1.png" />
+          <img alt="小智数字人 支持语音唤醒" src="docs/images/demo8.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1CKVz6UEuB" target="_blank">
-         <picture>
+        <picture>
-           <img alt="MQTT指令下发" src="docs/images/demo4.png" />
+          <img alt="设备呼叫设备，打电话" src="docs/images/demo0.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1C1tCzUEZh" target="_blank">
-         <picture>
+        <picture>
-           <img alt="声纹识别" src="docs/images/demo14.png" />
+          <img alt="复杂医疗场景" src="docs/images/demo1.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
   </tr>
   <tr>
     <td>
-        <a href="https://www.bilibili.com/video/BV1pNXWYGEx1" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
-         <picture>
+        <picture>
-           <img alt="控制家电开关" src="docs/images/demo5.png" />
+          <img alt="播放音乐查询天气播报新闻" src="docs/images/demo7.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
-         <picture>
-           <img alt="MCP接入点" src="docs/images/demo13.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-      <a href="https://www.bilibili.com/video/BV1TJ7WzzEo6" target="_blank">
-         <picture>
-           <img alt="多指令任务" src="docs/images/demo11.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
-         <picture>
-           <img alt="播放音乐" src="docs/images/demo7.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1Z8XuYZEAS" target="_blank">
-         <picture>
-           <img alt="天气插件" src="docs/images/demo8.png" />
-         </picture>
-        </a>
-    </td>
-  </tr>
-  <tr>
     <td>
       <a href="https://www.bilibili.com/video/BV12J7WzBEaH" target="_blank">
-         <picture>
+        <picture>
-           <img alt="实时打断" src="docs/images/demo10.png" />
+          <img alt="实时打断" src="docs/images/demo10.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
       <a href="https://www.bilibili.com/video/BV1Co76z7EvK" target="_blank">
-         <picture>
+        <picture>
-           <img alt="拍照识物品" src="docs/images/demo12.png" />
+          <img alt="拍照识物品" src="docs/images/demo12.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1pNXWYGEx1" target="_blank">
-         <picture>
+        <picture>
-           <img alt="自定义音色" src="docs/images/demo2.png" />
+          <img alt="控制家电开关" src="docs/images/demo5.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV12yA2egEaC" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1TJ7WzzEo6" target="_blank">
-         <picture>
+        <picture>
-           <img alt="使用粤语交流" src="docs/images/demo3.png" />
+          <img alt="多指令任务" src="docs/images/demo11.png" /></picture>
-         </picture>
+      </a>
-        </a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
+        <picture>
+          <img alt="MCP接入点" src="docs/images/demo13.png" /></picture>
+      </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV17LXWYvENb" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
-         <picture>
+        <picture>
-           <img alt="播报新闻" src="docs/images/demo0.png" />
+          <img alt="MQTT指令下发" src="docs/images/demo4.png" /></picture>
-         </picture>
+      </a>
-        </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
+        <picture>
+          <img alt="声纹识别" src="docs/images/demo14.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
+        <picture>
+          <img alt="自定义音色" src="docs/images/demo2.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV12yA2egEaC" target="_blank">
+        <picture>
+          <img alt="使用粤语交流" src="docs/images/demo3.png" /></picture>
+      </a>
     </td>
   </tr>
 </table>
@@ -175,17 +160,17 @@ Möchten Sie die Nutzungseffekte sehen? Klicken Sie auf die Videos unten 🎥
 
 ## Deployment-Dokumentation
 
-![Banners](docs/images/banner2.png)
+![Banners](../images/banner2.png)
 
 Dieses Projekt bietet zwei Bereitstellungsmethoden. Bitte wählen Sie basierend auf Ihren spezifischen Anforderungen:
 
 #### 🚀 Auswahl der Bereitstellungsmethode
 | Bereitstellungsmethode | Funktionen | Anwendungsszenarien | Deployment-Dokumente | Konfigurationsanforderungen | Video-Tutorials |
 |---------|------|---------|---------|---------|---------|
-| **Vereinfachte Installation** | Intelligenter Dialog, Einzel-Agenten-Verwaltung | Umgebungen mit geringer Konfiguration, Daten in Konfigurationsdateien gespeichert, keine Datenbank erforderlich | [①Docker-Version](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) / [②Quellcode-Deployment](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E5%8F%AA%E8%BF%90%E8%A1%8Cserver)| 2 Kerne 4GB bei Verwendung von `FunASR`, 2 Kerne 2GB bei allen APIs | - |
+| **Vereinfachte Installation** | Intelligenter Dialog, Einzel-Agenten-Verwaltung | Umgebungen mit geringer Konfiguration, Daten in Konfigurationsdateien gespeichert, keine Datenbank erforderlich | [①Docker-Version](../Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) / [②Quellcode-Deployment](../Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E5%8F%AA%E8%BF%90%E8%A1%8Cserver)| 2 Kerne 4GB bei Verwendung von `FunASR`, 2 Kerne 2GB bei allen APIs | - |
-| **Vollständige Modulinstallation** | Intelligenter Dialog, Mehrbenutzerverwaltung, Mehr-Agenten-Verwaltung, Intelligente Steuerkonsole-Bedienung | Vollständige Funktionserfahrung, Daten in Datenbank gespeichert |[①Docker-Version](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [②Quellcode-Deployment](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [③Quellcode-Deployment Auto-Update-Tutorial](./docs/dev-ops-integration.md) | 4 Kerne 8GB bei Verwendung von `FunASR`, 2 Kerne 4GB bei allen APIs| [Video-Tutorial für lokalen Quellcode-Start](https://www.bilibili.com/video/BV1wBJhz4Ewe) |
+| **Vollständige Modulinstallation** | Intelligenter Dialog, Mehrbenutzerverwaltung, Mehr-Agenten-Verwaltung, Intelligente Steuerkonsole-Bedienung | Vollständige Funktionserfahrung, Daten in Datenbank gespeichert |[①Docker-Version](../Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [②Quellcode-Deployment](../Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [③Quellcode-Deployment Auto-Update-Tutorial](../dev-ops-integration.md) | 4 Kerne 8GB bei Verwendung von `FunASR`, 2 Kerne 4GB bei allen APIs| [Video-Tutorial für lokalen Quellcode-Start](https://www.bilibili.com/video/BV1wBJhz4Ewe) |
 
-Häufige Fragen und entsprechende Tutorials finden Sie unter [diesem Link](./docs/FAQ.md)
+Häufige Fragen und entsprechende Tutorials finden Sie unter [diesem Link](../FAQ.md)
 
 > 💡 Hinweis: Unten ist eine Testplattform, die mit dem neuesten Code bereitgestellt wurde. Sie können bei Bedarf brennen und testen. Gleichzeitige Benutzer: 6, Daten werden täglich gelöscht.
 
@@ -212,8 +197,8 @@ Websocket-Schnittstellenadresse: wss://2662r3426b.vicp.fun/xiaozhi/v1/
 |:---:|:---:|:---:|
 | ASR (Spracherkennung) | FunASR (Lokal) | 👍XunfeiStreamASR (Xunfei-Streaming) |
 | LLM (Großes Modell) | glm-4-flash (Zhipu) | 👍qwen-flash (Alibaba Bailian) |
-| VLLM (Vision Large Model) | glm-4v-flash (Zhipu) | 👍qwen2.5-vl-3b-instructh (Alibaba Bailian) |
+| VLLM (Vision Large Model) | glm-4v-flash (Zhipu) | 👍qwen3.5-flash (Alibaba Bailian) |
-| TTS (Sprachsynthese) | ✅LinkeraiTTS (Lingxi-Streaming) | 👍HuoshanDoubleStreamTTS (Volcano-Streaming) |
+| TTS (Sprachsynthese) | EdgeTTS (Microsoft) | 👍HuoshanDoubleStreamTTS (Volcano-Streaming) |
 | Intent (Absichtserkennung) | function_call (Funktionsaufruf) | function_call (Funktionsaufruf) |
 | Memory (Gedächtnisfunktion) | mem_local_short (Lokales Kurzzeitgedächtnis) | mem_local_short (Lokales Kurzzeitgedächtnis) |
 
@@ -224,7 +209,7 @@ Dieses Projekt bietet die folgenden Testwerkzeuge, um Ihnen bei der Überprüfun
 
 | Werkzeugname | Standort | Verwendungsmethode | Funktionsbeschreibung |
 |:---:|:---|:---:|:---:|
-| Audio-Interaktionstesttool | main》xiaozhi-server》test》test_page.html | Direkt mit Google Chrome öffnen | Testet Audio-Wiedergabe- und Empfangsfunktionen, überprüft, ob die Python-seitige Audioverarbeitung normal ist |
+| Audio-Interaktionstesttool | main》digital-human》index.html | In `main/digital-human` `python start.py` ausführen und dann `http://127.0.0.1:8006/index.html` öffnen | Testet Audio-Wiedergabe- und Empfangsfunktionen, überprüft, ob die Python-seitige Audioverarbeitung normal ist |
 | Modell-Reaktionstesttool | main》xiaozhi-server》performance_tester.py | Ausführen `python performance_tester.py` | Testet die Reaktionsgeschwindigkeit von ASR (Spracherkennung), LLM (großes Modell), VLLM (Vision-Modell), TTS (Sprachsynthese) drei Kernmodulen |
 
 > 💡 Hinweis: Beim Testen der Modellgeschwindigkeit werden nur Modelle mit konfigurierten Schlüsseln getestet.
@@ -232,7 +217,7 @@ Dieses Projekt bietet die folgenden Testwerkzeuge, um Ihnen bei der Überprüfun
 ---
 ## Funktionsliste ✨
 ### Implementiert ✅
-![请参考-全模块安装架构图](docs/images/deploy2.png)
+![请参考-全模块安装架构图](../images/deploy2.png)
 | Funktionsmodul | Beschreibung |
 |:---:|:---|
 | Kernarchitektur | Basierend auf [MQTT+UDP-Gateway](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/main/docs/mqtt-gateway-integration.md), WebSocket und HTTP-Servern, bietet vollständiges Konsolenverwaltungs- und Authentifizierungssystem |
@@ -252,9 +237,9 @@ Dieses Projekt bietet die folgenden Testwerkzeuge, um Ihnen bei der Überprüfun
 
 ### In Entwicklung 🚧
 
-Um über spezifische Entwicklungsplanfortschritte zu erfahren, [klicken Sie hier](https://github.com/users/xinnan-tech/projects/3). Häufige Fragen und entsprechende Tutorials finden Sie unter [diesem Link](./docs/FAQ.md)
+Um über spezifische Entwicklungsplanfortschritte zu erfahren, [klicken Sie hier](https://github.com/users/xinnan-tech/projects/3). Häufige Fragen und entsprechende Tutorials finden Sie unter [diesem Link](../FAQ.md)
 
-Wenn Sie ein Softwareentwickler sind, finden Sie hier einen [Offenen Brief an Entwickler](docs/contributor_open_letter.md). Willkommen beim Beitritt!
+Wenn Sie ein Softwareentwickler sind, finden Sie hier einen [Offenen Brief an Entwickler](../contributor_open_letter.md). Willkommen beim Beitritt!
 
 ---
 
@@ -329,7 +314,7 @@ Tatsächlich kann jedes VLLM, das OpenAI-Schnittstellenaufrufe unterstützt, int
 | Typ | Plattformname | Verwendungsmethode | Preismodell | Hinweise |
 |:------:|:---------------:|:----:|:---------:|:--:|
 | Memory | mem0ai | Schnittstellenaufrufe | 1000 Mal/Monat Kontingent | |
-| Memory | [powermem](./docs/powermem-integration.md) | Lokale Zusammenfassung | Abhängig von LLM und DB | OceanBase Open Source, unterstützt intelligente Abfrage |
+| Memory | [powermem](../powermem-integration.md) | Lokale Zusammenfassung | Abhängig von LLM und DB | OceanBase Open Source, unterstützt intelligente Abfrage |
 | Memory | mem_local_short | Lokale Zusammenfassung | Kostenlos | |
 | Memory | nomem | Kein Gedächtnismodus | Kostenlos | |
 
@@ -357,13 +342,13 @@ Tatsächlich kann jedes VLLM, das OpenAI-Schnittstellenaufrufe unterstützt, int
 
 | Logo | Projekt/Unternehmen | Beschreibung |
 |:---:|:---:|:---|
-| <img src="./docs/images/logo_bailing.png" width="160"> | [Bailing Voice Dialogue Robot](https://github.com/wwbin2017/bailing) | Dieses Projekt wurde von [Bailing Voice Dialogue Robot](https://github.com/wwbin2017/bailing) inspiriert und auf dessen Basis implementiert |
+| <img src="../images/logo_bailing.png" width="160"> | [Bailing Voice Dialogue Robot](https://github.com/wwbin2017/bailing) | Dieses Projekt wurde von [Bailing Voice Dialogue Robot](https://github.com/wwbin2017/bailing) inspiriert und auf dessen Basis implementiert |
-| <img src="./docs/images/logo_tenclass.png" width="160"> | [Tenclass](https://www.tenclass.com/) | Dank an [Tenclass](https://www.tenclass.com/) für die Formulierung von Standardkommunikationsprotokollen, Multi-Geräte-Kompatibilitätslösungen und High-Concurrency-Szenario-Praxisdemonstrationen für das Xiaozhi-Ökosystem; für die Bereitstellung vollständiger technischer Dokumentationsunterstützung für dieses Projekt |
+| <img src="../images/logo_tenclass.png" width="160"> | [Tenclass](https://www.tenclass.com/) | Dank an [Tenclass](https://www.tenclass.com/) für die Formulierung von Standardkommunikationsprotokollen, Multi-Geräte-Kompatibilitätslösungen und High-Concurrency-Szenario-Praxisdemonstrationen für das Xiaozhi-Ökosystem; für die Bereitstellung vollständiger technischer Dokumentationsunterstützung für dieses Projekt |
-| <img src="./docs/images/logo_xuanfeng.png" width="160"> | [Xuanfeng Technology](https://github.com/Eric0308) | Dank an [Xuanfeng Technology](https://github.com/Eric0308) für den Beitrag des Funktionsaufruf-Frameworks, des MCP-Kommunikationsprotokolls und der plugin-basierten Aufrufmechanismus-Implementierungscode. Durch standardisiertes Befehlsplanungssystem und dynamische Erweiterungsfähigkeiten wird die Interaktionseffizienz und funktionale Erweiterbarkeit von Frontend-Geräten (IoT) erheblich verbessert |
+| <img src="../images/logo_xuanfeng.png" width="160"> | [Xuanfeng Technology](https://github.com/Eric0308) | Dank an [Xuanfeng Technology](https://github.com/Eric0308) für den Beitrag des Funktionsaufruf-Frameworks, des MCP-Kommunikationsprotokolls und der plugin-basierten Aufrufmechanismus-Implementierungscode. Durch standardisiertes Befehlsplanungssystem und dynamische Erweiterungsfähigkeiten wird die Interaktionseffizienz und funktionale Erweiterbarkeit von Frontend-Geräten (IoT) erheblich verbessert |
-| <img src="./docs/images/logo_junsen.png" width="160"> | [huangjunsen](https://github.com/huangjunsen0406) | Dank an [huangjunsen](https://github.com/huangjunsen0406) für den Beitrag des `Smart Control Console Mobile`-Moduls, das eine effiziente Steuerung und Echtzeit-Interaktion über mobile Geräte ermöglicht und die Betriebsbequemlichkeit und Verwaltungseffizienz des Systems in mobilen Szenarien erheblich verbessert |
+| <img src="../images/logo_junsen.png" width="160"> | [huangjunsen](https://github.com/huangjunsen0406) | Dank an [huangjunsen](https://github.com/huangjunsen0406) für den Beitrag des `Smart Control Console Mobile`-Moduls, das eine effiziente Steuerung und Echtzeit-Interaktion über mobile Geräte ermöglicht und die Betriebsbequemlichkeit und Verwaltungseffizienz des Systems in mobilen Szenarien erheblich verbessert |
-| <img src="./docs/images/logo_huiyuan.png" width="160"> | [Huiyuan Design](http://ui.kwd988.net/) | Dank an [Huiyuan Design](http://ui.kwd988.net/) für die Bereitstellung professioneller visueller Lösungen für dieses Projekt, unter Verwendung ihrer Design-Praxiserfahrung im Dienst von über tausend Unternehmen, um die Produktbenutzererfahrung dieses Projekts zu stärken |
+| <img src="../images/logo_huiyuan.png" width="160"> | [Huiyuan Design](http://ui.kwd988.net/) | Dank an [Huiyuan Design](http://ui.kwd988.net/) für die Bereitstellung professioneller visueller Lösungen für dieses Projekt, unter Verwendung ihrer Design-Praxiserfahrung im Dienst von über tausend Unternehmen, um die Produktbenutzererfahrung dieses Projekts zu stärken |
-| <img src="./docs/images/logo_qinren.png" width="160"> | [Xi'an Qinren Information Technology](https://www.029app.com/) | Dank an [Xi'an Qinren Information Technology](https://www.029app.com/) für die Vertiefung des visuellen Systems dieses Projekts und die Sicherstellung der Konsistenz und Erweiterbarkeit des Gesamtdesignstils in Multi-Szenario-Anwendungen |
+| <img src="../images/logo_qinren.png" width="160"> | [Xi'an Qinren Information Technology](https://www.029app.com/) | Dank an [Xi'an Qinren Information Technology](https://www.029app.com/) für die Vertiefung des visuellen Systems dieses Projekts und die Sicherstellung der Konsistenz und Erweiterbarkeit des Gesamtdesignstils in Multi-Szenario-Anwendungen |
-| <img src="./docs/images/logo_contributors.png" width="160"> | [Code-Mitwirkende](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors) | Dank an [alle Code-Mitwirkenden](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors), Ihre Bemühungen haben das Projekt robuster und leistungsfähiger gemacht. |
+| <img src="../images/logo_contributors.png" width="160"> | [Code-Mitwirkende](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors) | Dank an [alle Code-Mitwirkenden](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors), Ihre Bemühungen haben das Projekt robuster und leistungsfähiger gemacht. |
 
 
 <a href="https://star-history.com/#xinnan-tech/xiaozhi-esp32-server&Date">

docs/readme/README_en.md

@@ -1,4 +1,4 @@
-[![Banners](docs/images/banner1.png)](https://github.com/xinnan-tech/xiaozhi-esp32-server)
+[![Banners](../images/banner1.png)](https://github.com/xinnan-tech/xiaozhi-esp32-server)
 
 <h1 align="center">Xiaozhi Backend Service xiaozhi-esp32-server</h1>
 
@@ -10,14 +10,14 @@ Support for MQTT+UDP protocol, Websocket protocol, MCP access point, voiceprint
 </p>
 
 <p align="center">
-<a href="./docs/FAQ.md">FAQ</a>
+<a href="../FAQ.md">FAQ</a>
 · <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/issues">Report Issues</a>
-· <a href="./README.md#%E9%83%A8%E7%BD%B2%E6%96%87%E6%A1%A3">Deployment Docs</a>
+· <a href="../../README.md#%E9%83%A8%E7%BD%B2%E6%96%87%E6%A1%A3">Deployment Docs</a>
 · <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/releases">Release Notes</a>
 </p>
 
 <p align="center">
-  <a href="./README.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-DFE0E5"></a>
+  <a href="../../README.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-DFE0E5"></a>
   <a href="./README_en.md"><img alt="README in English" src="https://img.shields.io/badge/English-DBEDFA"></a>
   <a href="./README_vi.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/Tiếng Việt-DFE0E5"></a>
   <a href="./README_de.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-DFE0E5"></a>
@@ -38,7 +38,7 @@ Spearheaded by Professor Siyuan Liu's Team (South China University of Technology
 </br>
 刘思源教授团队主导研发（华南理工大学）
 </br>
-<img src="./docs/images/hnlg.jpg" alt="South China University of Technology" width="50%">
+<img src="../images/hnlg.jpg" alt="South China University of Technology" width="50%">
 </p>
 
 ---
@@ -52,113 +52,98 @@ Want to see the usage effects? Click the videos below 🎥
 <table>
   <tr>
     <td>
-        <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
-         <picture>
+        <picture>
-           <img alt="响应速度感受" src="docs/images/demo9.png" />
+          <img alt="响应速度感受" src="docs/images/demo9.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1vchQzaEse" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1vchQzaEse" target="_blank">
-         <picture>
+        <picture>
-           <img alt="速度优化秘诀" src="docs/images/demo6.png" />
+          <img alt="速度优化秘诀" src="docs/images/demo6.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1C1tCzUEZh" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1WEcxzFEAT" target="_blank">
-         <picture>
+        <picture>
-           <img alt="复杂医疗场景" src="docs/images/demo1.png" />
+          <img alt="小智数字人 支持语音唤醒" src="docs/images/demo8.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1CKVz6UEuB" target="_blank">
-         <picture>
+        <picture>
-           <img alt="MQTT指令下发" src="docs/images/demo4.png" />
+          <img alt="设备呼叫设备，打电话" src="docs/images/demo0.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1C1tCzUEZh" target="_blank">
-         <picture>
+        <picture>
-           <img alt="声纹识别" src="docs/images/demo14.png" />
+          <img alt="复杂医疗场景" src="docs/images/demo1.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
   </tr>
   <tr>
     <td>
-        <a href="https://www.bilibili.com/video/BV1pNXWYGEx1" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
-         <picture>
+        <picture>
-           <img alt="控制家电开关" src="docs/images/demo5.png" />
+          <img alt="播放音乐查询天气播报新闻" src="docs/images/demo7.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
-         <picture>
-           <img alt="MCP接入点" src="docs/images/demo13.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-      <a href="https://www.bilibili.com/video/BV1TJ7WzzEo6" target="_blank">
-         <picture>
-           <img alt="多指令任务" src="docs/images/demo11.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
-         <picture>
-           <img alt="播放音乐" src="docs/images/demo7.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1Z8XuYZEAS" target="_blank">
-         <picture>
-           <img alt="天气插件" src="docs/images/demo8.png" />
-         </picture>
-        </a>
-    </td>
-  </tr>
-  <tr>
     <td>
       <a href="https://www.bilibili.com/video/BV12J7WzBEaH" target="_blank">
-         <picture>
+        <picture>
-           <img alt="实时打断" src="docs/images/demo10.png" />
+          <img alt="实时打断" src="docs/images/demo10.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
       <a href="https://www.bilibili.com/video/BV1Co76z7EvK" target="_blank">
-         <picture>
+        <picture>
-           <img alt="拍照识物品" src="docs/images/demo12.png" />
+          <img alt="拍照识物品" src="docs/images/demo12.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1pNXWYGEx1" target="_blank">
-         <picture>
+        <picture>
-           <img alt="自定义音色" src="docs/images/demo2.png" />
+          <img alt="控制家电开关" src="docs/images/demo5.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV12yA2egEaC" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1TJ7WzzEo6" target="_blank">
-         <picture>
+        <picture>
-           <img alt="使用粤语交流" src="docs/images/demo3.png" />
+          <img alt="多指令任务" src="docs/images/demo11.png" /></picture>
-         </picture>
+      </a>
-        </a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
+        <picture>
+          <img alt="MCP接入点" src="docs/images/demo13.png" /></picture>
+      </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV17LXWYvENb" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
-         <picture>
+        <picture>
-           <img alt="播报新闻" src="docs/images/demo0.png" />
+          <img alt="MQTT指令下发" src="docs/images/demo4.png" /></picture>
-         </picture>
+      </a>
-        </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
+        <picture>
+          <img alt="声纹识别" src="docs/images/demo14.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
+        <picture>
+          <img alt="自定义音色" src="docs/images/demo2.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV12yA2egEaC" target="_blank">
+        <picture>
+          <img alt="使用粤语交流" src="docs/images/demo3.png" /></picture>
+      </a>
     </td>
   </tr>
 </table>
@@ -175,17 +160,17 @@ Want to see the usage effects? Click the videos below 🎥
 
 ## Deployment Documentation
 
-![Banners](docs/images/banner2.png)
+![Banners](../images/banner2.png)
 
 This project provides two deployment methods. Please choose based on your specific needs:
 
 #### 🚀 Deployment Method Selection
 | Deployment Method | Features | Applicable Scenarios | Deployment Docs | Configuration Requirements | Video Tutorials | 
 |---------|------|---------|---------|---------|---------|
-| **Simplified Installation** | Intelligent dialogue, single agent management | Low-configuration environments, data stored in config files, no database required | [①Docker Version](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) / [②Source Code Deployment](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E5%8F%AA%E8%BF%90%E8%A1%8Cserver)| 2 cores 4GB if using `FunASR`, 2 cores 2GB if all APIs | - | 
+| **Simplified Installation** | Intelligent dialogue, single agent management | Low-configuration environments, data stored in config files, no database required | [①Docker Version](../Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) / [②Source Code Deployment](../Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E5%8F%AA%E8%BF%90%E8%A1%8Cserver)| 2 cores 4GB if using `FunASR`, 2 cores 2GB if all APIs | - | 
-| **Full Module Installation** | Intelligent dialogue, multi-user management, multi-agent management, intelligent console interface operation | Complete functionality experience, data stored in database |[①Docker Version](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [②Source Code Deployment](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [③Source Code Deployment Auto-Update Tutorial](./docs/dev-ops-integration.md) | 4 cores 8GB if using `FunASR`, 2 cores 4GB if all APIs| [Local Source Code Startup Video Tutorial](https://www.bilibili.com/video/BV1wBJhz4Ewe) |
+| **Full Module Installation** | Intelligent dialogue, multi-user management, multi-agent management, intelligent console interface operation | Complete functionality experience, data stored in database |[①Docker Version](../Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [②Source Code Deployment](../Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [③Source Code Deployment Auto-Update Tutorial](../dev-ops-integration.md) | 4 cores 8GB if using `FunASR`, 2 cores 4GB if all APIs| [Local Source Code Startup Video Tutorial](https://www.bilibili.com/video/BV1wBJhz4Ewe) |
 
-For frequently asked questions and related tutorials, please refer to [this link](./docs/FAQ.md)
+For frequently asked questions and related tutorials, please refer to [this link](../FAQ.md)
 
 > 💡 Note: Below is a test platform deployed with the latest code. You can burn and test if needed. Concurrent users: 6, data will be cleared daily.
 
@@ -212,8 +197,8 @@ Websocket Interface Address: wss://2662r3426b.vicp.fun/xiaozhi/v1/
 |:---:|:---:|:---:|
 | ASR(Speech Recognition) | FunASR(Local) | 👍XunfeiStreamASR(Xunfei Streaming) |
 | LLM(Large Model) | glm-4-flash(Zhipu) | 👍qwen-flash(Alibaba Bailian) |
-| VLLM(Vision Large Model) | glm-4v-flash(Zhipu) | 👍qwen2.5-vl-3b-instructh(Alibaba Bailian) |
+| VLLM(Vision Large Model) | glm-4v-flash(Zhipu) | 👍qwen3.5-flash(Alibaba Bailian) |
-| TTS(Speech Synthesis) | ✅LinkeraiTTS(Lingxi streaming) | 👍HuoshanDoubleStreamTTS(Volcano Streaming) |
+| TTS(Speech Synthesis) | EdgeTTS(Microsoft) | 👍HuoshanDoubleStreamTTS(Volcano Streaming) |
 | Intent(Intent Recognition) | function_call(Function calling) | function_call(Function calling) |
 | Memory(Memory function) | mem_local_short(Local short-term memory) | mem_local_short(Local short-term memory) |
 
@@ -224,7 +209,7 @@ This project provides the following testing tools to help you verify the system
 
 | Tool Name | Location | Usage Method | Function Description |
 |:---:|:---|:---:|:---:|
-| Audio Interaction Test Tool | main》xiaozhi-server》test》test_page.html | Open directly with Google Chrome | Tests audio playback and reception functions, verifies if Python-side audio processing is normal |
+| Audio Interaction Test Tool | main》digital-human》index.html | Run `python start.py` in `main/digital-human`, then open `http://127.0.0.1:8006/index.html` | Tests audio playback and reception functions, verifies if Python-side audio processing is normal |
 | Model Response Test Tool | main》xiaozhi-server》performance_tester.py | Execute `python performance_tester.py` | Tests response speed of three core modules: ASR(speech recognition), LLM(large model), VLLM(vision model), TTS(speech synthesis) |
 
 > 💡 Note: When testing model speed, only models with configured keys will be tested.
@@ -232,7 +217,7 @@ This project provides the following testing tools to help you verify the system
 ---
 ## Feature List ✨
 ### Implemented ✅
-![请参考-全模块安装架构图](docs/images/deploy2.png)
+![请参考-全模块安装架构图](../images/deploy2.png)
 | Feature Module | Description |
 |:---:|:---|
 | Core Architecture | Based on [MQTT+UDP gateway](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/main/docs/mqtt-gateway-integration.md), WebSocket and HTTP servers, provides complete console management and authentication system |
@@ -252,9 +237,9 @@ This project provides the following testing tools to help you verify the system
 
 ### Under Development 🚧
 
-To learn about specific development plan progress, [click here](https://github.com/users/xinnan-tech/projects/3). For frequently asked questions and related tutorials, please refer to [this link](./docs/FAQ.md)
+To learn about specific development plan progress, [click here](https://github.com/users/xinnan-tech/projects/3). For frequently asked questions and related tutorials, please refer to [this link](../FAQ.md)
 
-If you are a software developer, here is an [Open Letter to Developers](docs/contributor_open_letter.md). Welcome to join!
+If you are a software developer, here is an [Open Letter to Developers](../contributor_open_letter.md). Welcome to join!
 
 ---
 
@@ -329,7 +314,7 @@ In fact, any VLLM that supports OpenAI interface calls can be integrated and use
 | Type | Platform Name | Usage Method | Pricing Model | Notes |
 |:------:|:---------------:|:----:|:---------:|:--:|
 | Memory | mem0ai | Interface calls | 1000 times/month quota | |
-| Memory | [powermem](./docs/powermem-integration.md) | Local summarization | Depends on LLM and DB | OceanBase open source, supports intelligent retrieval |
+| Memory | [powermem](../powermem-integration.md) | Local summarization | Depends on LLM and DB | OceanBase open source, supports intelligent retrieval |
 | Memory | mem_local_short | Local summarization | Free | |
 | Memory | nomem | No memory mode | Free | |
 
@@ -357,13 +342,13 @@ In fact, any VLLM that supports OpenAI interface calls can be integrated and use
 
 | Logo | Project/Company | Description |
 |:---:|:---:|:---|
-| <img src="./docs/images/logo_bailing.png" width="160"> | [Bailing Voice Dialogue Robot](https://github.com/wwbin2017/bailing) | This project is inspired by [Bailing Voice Dialogue Robot](https://github.com/wwbin2017/bailing) and implemented on its basis |
+| <img src="../images/logo_bailing.png" width="160"> | [Bailing Voice Dialogue Robot](https://github.com/wwbin2017/bailing) | This project is inspired by [Bailing Voice Dialogue Robot](https://github.com/wwbin2017/bailing) and implemented on its basis |
-| <img src="./docs/images/logo_tenclass.png" width="160"> | [Tenclass](https://www.tenclass.com/) | Thanks to [Tenclass](https://www.tenclass.com/) for formulating standard communication protocols, multi-device compatibility solutions, and high-concurrency scenario practice demonstrations for the Xiaozhi ecosystem; providing full-link technical documentation support for this project |
+| <img src="../images/logo_tenclass.png" width="160"> | [Tenclass](https://www.tenclass.com/) | Thanks to [Tenclass](https://www.tenclass.com/) for formulating standard communication protocols, multi-device compatibility solutions, and high-concurrency scenario practice demonstrations for the Xiaozhi ecosystem; providing full-link technical documentation support for this project |
-| <img src="./docs/images/logo_xuanfeng.png" width="160"> | [Xuanfeng Technology](https://github.com/Eric0308) | Thanks to [Xuanfeng Technology](https://github.com/Eric0308) for contributing function calling framework, MCP communication protocol, and plugin-based calling mechanism implementation code. Through standardized instruction scheduling system and dynamic expansion capabilities, it significantly improves the interaction efficiency and functional extensibility of frontend devices (IoT) |
+| <img src="../images/logo_xuanfeng.png" width="160"> | [Xuanfeng Technology](https://github.com/Eric0308) | Thanks to [Xuanfeng Technology](https://github.com/Eric0308) for contributing function calling framework, MCP communication protocol, and plugin-based calling mechanism implementation code. Through standardized instruction scheduling system and dynamic expansion capabilities, it significantly improves the interaction efficiency and functional extensibility of frontend devices (IoT) |
-| <img src="./docs/images/logo_junsen.png" width="160"> | [huangjunsen](https://github.com/huangjunsen0406) | Thanks to [huangjunsen](https://github.com/huangjunsen0406) for contributing the `Smart Control Console Mobile` module, which enables efficient control and real-time interaction across mobile devices, significantly enhancing the system's operational convenience and management efficiency in mobile scenarios. |
+| <img src="../images/logo_junsen.png" width="160"> | [huangjunsen](https://github.com/huangjunsen0406) | Thanks to [huangjunsen](https://github.com/huangjunsen0406) for contributing the `Smart Control Console Mobile` module, which enables efficient control and real-time interaction across mobile devices, significantly enhancing the system's operational convenience and management efficiency in mobile scenarios. |
-| <img src="./docs/images/logo_huiyuan.png" width="160"> | [Huiyuan Design](http://ui.kwd988.net/) | Thanks to [Huiyuan Design](http://ui.kwd988.net/) for providing professional visual solutions for this project, using their design practical experience serving over a thousand enterprises to empower this project's product user experience |
+| <img src="../images/logo_huiyuan.png" width="160"> | [Huiyuan Design](http://ui.kwd988.net/) | Thanks to [Huiyuan Design](http://ui.kwd988.net/) for providing professional visual solutions for this project, using their design practical experience serving over a thousand enterprises to empower this project's product user experience |
-| <img src="./docs/images/logo_qinren.png" width="160"> | [Xi'an Qinren Information Technology](https://www.029app.com/) | Thanks to [Xi'an Qinren Information Technology](https://www.029app.com/) for deepening this project's visual system, ensuring consistency and extensibility of overall design style in multi-scenario applications |
+| <img src="../images/logo_qinren.png" width="160"> | [Xi'an Qinren Information Technology](https://www.029app.com/) | Thanks to [Xi'an Qinren Information Technology](https://www.029app.com/) for deepening this project's visual system, ensuring consistency and extensibility of overall design style in multi-scenario applications |
-| <img src="./docs/images/logo_contributors.png" width="160"> | [Code Contributors](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors) | Thanks to [all code contributors](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors), your efforts have made the project more robust and powerful. |
+| <img src="../images/logo_contributors.png" width="160"> | [Code Contributors](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors) | Thanks to [all code contributors](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors), your efforts have made the project more robust and powerful. |
 
 
 <a href="https://star-history.com/#xinnan-tech/xiaozhi-esp32-server&Date">

docs/readme/README_pt_BR.md

@@ -1,4 +1,4 @@
-[![Banners](docs/images/banner1.png)](https://github.com/xinnan-tech/xiaozhi-esp32-server)
+[![Banners](../images/banner1.png)](https://github.com/xinnan-tech/xiaozhi-esp32-server)
 
 <h1 align="center">Serviço Backend Xiaozhi xiaozhi-esp32-server</h1>
 
@@ -10,14 +10,14 @@ Suporte ao protocolo MQTT+UDP, protocolo WebSocket, ponto de acesso MCP, reconhe
 </p>
 
 <p align="center">
-<a href="./docs/FAQ.md">Perguntas Frequentes</a>
+<a href="../FAQ.md">Perguntas Frequentes</a>
 · <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/issues">Reportar Problemas</a>
-· <a href="./README.md#%E9%83%A8%E7%BD%B2%E6%96%87%E6%A1%A3">Documentação de Implantação</a>
+· <a href="../../README.md#%E9%83%A8%E7%BD%B2%E6%96%87%E6%A1%A3">Documentação de Implantação</a>
 · <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/releases">Notas de Lançamento</a>
 </p>
 
 <p align="center">
-  <a href="./README.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-DFE0E5"></a>
+  <a href="../../README.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-DFE0E5"></a>
   <a href="./README_en.md"><img alt="README in English" src="https://img.shields.io/badge/English-DFE0E5"></a>
   <a href="./README_vi.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/Tiếng Việt-DFE0E5"></a>
   <a href="./README_de.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-DFE0E5"></a>
@@ -38,7 +38,7 @@ Liderado pela Equipe do Professor Siyuan Liu (Universidade de Tecnologia do Sul
 </br>
 刘思源教授团队主导研发（华南理工大学）
 </br>
-<img src="./docs/images/hnlg.jpg" alt="Universidade de Tecnologia do Sul da China (华南理工大学)" width="50%">
+<img src="../images/hnlg.jpg" alt="Universidade de Tecnologia do Sul da China (华南理工大学)" width="50%">
 </p>
 
 ---
@@ -52,113 +52,98 @@ Quer ver os efeitos de uso? Clique nos vídeos abaixo 🎥
 <table>
   <tr>
     <td>
-        <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
-         <picture>
+        <picture>
-           <img alt="Experiência de velocidade de resposta" src="docs/images/demo9.png" />
+          <img alt="响应速度感受" src="docs/images/demo9.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1vchQzaEse" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1vchQzaEse" target="_blank">
-         <picture>
+        <picture>
-           <img alt="Segredo da otimização de velocidade" src="docs/images/demo6.png" />
+          <img alt="速度优化秘诀" src="docs/images/demo6.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1C1tCzUEZh" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1WEcxzFEAT" target="_blank">
-         <picture>
+        <picture>
-           <img alt="Cenário médico complexo" src="docs/images/demo1.png" />
+          <img alt="小智数字人 支持语音唤醒" src="docs/images/demo8.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1CKVz6UEuB" target="_blank">
-         <picture>
+        <picture>
-           <img alt="Envio de comandos MQTT" src="docs/images/demo4.png" />
+          <img alt="设备呼叫设备，打电话" src="docs/images/demo0.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1C1tCzUEZh" target="_blank">
-         <picture>
+        <picture>
-           <img alt="Reconhecimento de impressão vocal" src="docs/images/demo14.png" />
+          <img alt="复杂医疗场景" src="docs/images/demo1.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
   </tr>
   <tr>
     <td>
-        <a href="https://www.bilibili.com/video/BV1pNXWYGEx1" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
-         <picture>
+        <picture>
-           <img alt="Controle de interruptores de eletrodomésticos" src="docs/images/demo5.png" />
+          <img alt="播放音乐查询天气播报新闻" src="docs/images/demo7.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
-         <picture>
-           <img alt="Ponto de acesso MCP" src="docs/images/demo13.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-      <a href="https://www.bilibili.com/video/BV1TJ7WzzEo6" target="_blank">
-         <picture>
-           <img alt="Tarefas com múltiplos comandos" src="docs/images/demo11.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
-         <picture>
-           <img alt="Reproduzir música" src="docs/images/demo7.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1Z8XuYZEAS" target="_blank">
-         <picture>
-           <img alt="Plugin de clima" src="docs/images/demo8.png" />
-         </picture>
-        </a>
-    </td>
-  </tr>
-  <tr>
     <td>
       <a href="https://www.bilibili.com/video/BV12J7WzBEaH" target="_blank">
-         <picture>
+        <picture>
-           <img alt="Interrupção em tempo real" src="docs/images/demo10.png" />
+          <img alt="实时打断" src="docs/images/demo10.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
       <a href="https://www.bilibili.com/video/BV1Co76z7EvK" target="_blank">
-         <picture>
+        <picture>
-           <img alt="Fotografar e identificar objetos" src="docs/images/demo12.png" />
+          <img alt="拍照识物品" src="docs/images/demo12.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1pNXWYGEx1" target="_blank">
-         <picture>
+        <picture>
-           <img alt="Timbre de voz personalizado" src="docs/images/demo2.png" />
+          <img alt="控制家电开关" src="docs/images/demo5.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV12yA2egEaC" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1TJ7WzzEo6" target="_blank">
-         <picture>
+        <picture>
-           <img alt="Comunicação em cantonês" src="docs/images/demo3.png" />
+          <img alt="多指令任务" src="docs/images/demo11.png" /></picture>
-         </picture>
+      </a>
-        </a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
+        <picture>
+          <img alt="MCP接入点" src="docs/images/demo13.png" /></picture>
+      </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV17LXWYvENb" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
-         <picture>
+        <picture>
-           <img alt="Transmissão de notícias" src="docs/images/demo0.png" />
+          <img alt="MQTT指令下发" src="docs/images/demo4.png" /></picture>
-         </picture>
+      </a>
-        </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
+        <picture>
+          <img alt="声纹识别" src="docs/images/demo14.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
+        <picture>
+          <img alt="自定义音色" src="docs/images/demo2.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV12yA2egEaC" target="_blank">
+        <picture>
+          <img alt="使用粤语交流" src="docs/images/demo3.png" /></picture>
+      </a>
     </td>
   </tr>
 </table>
@@ -175,17 +160,17 @@ Quer ver os efeitos de uso? Clique nos vídeos abaixo 🎥
 
 ## Documentação de Implantação
 
-![Banners](docs/images/banner2.png)
+![Banners](../images/banner2.png)
 
 Este projeto oferece dois métodos de implantação. Por favor, escolha de acordo com suas necessidades específicas:
 
 #### 🚀 Seleção do Método de Implantação
 | Método de Implantação | Funcionalidades | Cenários Aplicáveis | Documentação de Implantação | Requisitos de Configuração | Tutoriais em Vídeo |
 |---------|------|---------|---------|---------|---------|
-| **Instalação Simplificada** | Diálogo inteligente, gerenciamento de agente único | Ambientes de baixa configuração, dados armazenados em arquivos de configuração, sem necessidade de banco de dados | [①Versão Docker](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) / [②Implantação via Código-Fonte](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E5%8F%AA%E8%BF%90%E8%A1%8Cserver)| 2 núcleos 4GB se usar `FunASR`, 2 núcleos 2GB se todas APIs | - |
+| **Instalação Simplificada** | Diálogo inteligente, gerenciamento de agente único | Ambientes de baixa configuração, dados armazenados em arquivos de configuração, sem necessidade de banco de dados | [①Versão Docker](../Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) / [②Implantação via Código-Fonte](../Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E5%8F%AA%E8%BF%90%E8%A1%8Cserver)| 2 núcleos 4GB se usar `FunASR`, 2 núcleos 2GB se todas APIs | - |
-| **Instalação de Módulo Completo** | Diálogo inteligente, gerenciamento multiusuário, gerenciamento de múltiplos agentes, operação de interface do console inteligente | Experiência com funcionalidade completa, dados armazenados em banco de dados |[①Versão Docker](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [②Implantação via Código-Fonte](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [③Tutorial de Atualização Automática via Código-Fonte](./docs/dev-ops-integration.md) | 4 núcleos 8GB se usar `FunASR`, 2 núcleos 4GB se todas APIs| [Tutorial em Vídeo de Inicialização via Código-Fonte Local](https://www.bilibili.com/video/BV1wBJhz4Ewe) |
+| **Instalação de Módulo Completo** | Diálogo inteligente, gerenciamento multiusuário, gerenciamento de múltiplos agentes, operação de interface do console inteligente | Experiência com funcionalidade completa, dados armazenados em banco de dados |[①Versão Docker](../Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [②Implantação via Código-Fonte](../Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [③Tutorial de Atualização Automática via Código-Fonte](../dev-ops-integration.md) | 4 núcleos 8GB se usar `FunASR`, 2 núcleos 4GB se todas APIs| [Tutorial em Vídeo de Inicialização via Código-Fonte Local](https://www.bilibili.com/video/BV1wBJhz4Ewe) |
 
-Perguntas frequentes e tutoriais relacionados podem ser consultados [neste link](./docs/FAQ.md)
+Perguntas frequentes e tutoriais relacionados podem ser consultados [neste link](../FAQ.md)
 
 > 💡 Nota: Abaixo está uma plataforma de teste implantada com o código mais recente. Você pode gravar e testar se necessário. Usuários simultâneos: 6, os dados serão limpos diariamente.
 
@@ -212,8 +197,8 @@ Endereço da Interface WebSocket: wss://2662r3426b.vicp.fun/xiaozhi/v1/
 |:---:|:---:|:---:|
 | ASR(Reconhecimento de Fala) | FunASR(Local) | 👍XunfeiStreamASR(Xunfei Streaming) |
 | LLM(Modelo de Linguagem) | glm-4-flash(Zhipu) | 👍qwen-flash(Alibaba Bailian) |
-| VLLM(Modelo de Visão) | glm-4v-flash(Zhipu) | 👍qwen2.5-vl-3b-instructh(Alibaba Bailian) |
+| VLLM(Modelo de Visão) | glm-4v-flash(Zhipu) | 👍qwen3.5-flash(Alibaba Bailian) |
-| TTS(Síntese de Voz) | ✅LinkeraiTTS(Lingxi streaming) | 👍HuoshanDoubleStreamTTS(Volcano Streaming) |
+| TTS(Síntese de Voz) | EdgeTTS(Microsoft) | 👍HuoshanDoubleStreamTTS(Volcano Streaming) |
 | Intent(Reconhecimento de Intenção) | function_call(Chamada de função) | function_call(Chamada de função) |
 | Memory(Função de Memória) | mem_local_short(Memória local de curto prazo) | mem_local_short(Memória local de curto prazo) |
 
@@ -224,7 +209,7 @@ Este projeto fornece as seguintes ferramentas de teste para ajudá-lo a verifica
 
 | Nome da Ferramenta | Localização | Método de Uso | Descrição da Função |
 |:---:|:---|:---:|:---:|
-| Ferramenta de Teste de Interação por Áudio | main》xiaozhi-server》test》test_page.html | Abrir diretamente com Google Chrome | Testa as funções de reprodução e recepção de áudio, verifica se o processamento de áudio no lado Python está normal |
+| Ferramenta de Teste de Interação por Áudio | main》digital-human》index.html | Execute `python start.py` em `main/digital-human` e depois abra `http://127.0.0.1:8006/index.html` | Testa as funções de reprodução e recepção de áudio, verifica se o processamento de áudio no lado Python está normal |
 | Ferramenta de Teste de Resposta de Modelo | main》xiaozhi-server》performance_tester.py | Execute `python performance_tester.py` | Testa a velocidade de resposta dos três módulos principais: ASR(reconhecimento de fala), LLM(modelo de linguagem), VLLM(modelo de visão), TTS(síntese de voz) |
 
 > 💡 Nota: Ao testar a velocidade dos modelos, apenas os modelos com chaves configuradas serão testados.
@@ -232,7 +217,7 @@ Este projeto fornece as seguintes ferramentas de teste para ajudá-lo a verifica
 ---
 ## Lista de Funcionalidades ✨
 ### Implementado ✅
-![请参考-全模块安装架构图](docs/images/deploy2.png)
+![请参考-全模块安装架构图](../images/deploy2.png)
 | Módulo de Funcionalidade | Descrição |
 |:---:|:---|
 | Arquitetura Principal | Baseado em [gateway MQTT+UDP](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/main/docs/mqtt-gateway-integration.md), servidores WebSocket e HTTP, fornece sistema completo de gerenciamento de console e autenticação |
@@ -252,9 +237,9 @@ Este projeto fornece as seguintes ferramentas de teste para ajudá-lo a verifica
 
 ### Em Desenvolvimento 🚧
 
-Para conhecer o progresso específico do plano de desenvolvimento, [clique aqui](https://github.com/users/xinnan-tech/projects/3). Perguntas frequentes e tutoriais relacionados podem ser consultados [neste link](./docs/FAQ.md)
+Para conhecer o progresso específico do plano de desenvolvimento, [clique aqui](https://github.com/users/xinnan-tech/projects/3). Perguntas frequentes e tutoriais relacionados podem ser consultados [neste link](../FAQ.md)
 
-Se você é um desenvolvedor de software, aqui está uma [Carta Aberta aos Desenvolvedores](docs/contributor_open_letter.md). Seja bem-vindo a participar!
+Se você é um desenvolvedor de software, aqui está uma [Carta Aberta aos Desenvolvedores](../contributor_open_letter.md). Seja bem-vindo a participar!
 
 ---
 
@@ -329,7 +314,7 @@ Na verdade, qualquer VLLM que suporte chamadas via interface OpenAI pode ser int
 | Tipo | Nome da Plataforma | Método de Uso | Modelo de Preço | Observações |
 |:------:|:---------------:|:----:|:---------:|:--:|
 | Memória | mem0ai | Chamadas via interface | Cota de 1000 vezes/mês | |
-| Memória | [powermem](./docs/powermem-integration.md) | Resumo local | Depende do LLM e BD | OceanBase de código aberto, suporta busca inteligente |
+| Memória | [powermem](../powermem-integration.md) | Resumo local | Depende do LLM e BD | OceanBase de código aberto, suporta busca inteligente |
 | Memória | mem_local_short | Resumo local | Gratuito | |
 | Memória | nomem | Modo sem memória | Gratuito | |
 
@@ -357,13 +342,13 @@ Na verdade, qualquer VLLM que suporte chamadas via interface OpenAI pode ser int
 
 | Logo | Projeto/Empresa | Descrição |
 |:---:|:---:|:---|
-| <img src="./docs/images/logo_bailing.png" width="160"> | [Robô de Diálogo por Voz Bailing](https://github.com/wwbin2017/bailing) | Este projeto foi inspirado pelo [Robô de Diálogo por Voz Bailing](https://github.com/wwbin2017/bailing) e implementado com base nele |
+| <img src="../images/logo_bailing.png" width="160"> | [Robô de Diálogo por Voz Bailing](https://github.com/wwbin2017/bailing) | Este projeto foi inspirado pelo [Robô de Diálogo por Voz Bailing](https://github.com/wwbin2017/bailing) e implementado com base nele |
-| <img src="./docs/images/logo_tenclass.png" width="160"> | [Tenclass](https://www.tenclass.com/) | Agradecimentos à [Tenclass](https://www.tenclass.com/) por formular protocolos de comunicação padrão, soluções de compatibilidade multidispositivo e demonstrações práticas de cenários de alta concorrência para o ecossistema Xiaozhi; fornecendo suporte completo de documentação técnica para este projeto |
+| <img src="../images/logo_tenclass.png" width="160"> | [Tenclass](https://www.tenclass.com/) | Agradecimentos à [Tenclass](https://www.tenclass.com/) por formular protocolos de comunicação padrão, soluções de compatibilidade multidispositivo e demonstrações práticas de cenários de alta concorrência para o ecossistema Xiaozhi; fornecendo suporte completo de documentação técnica para este projeto |
-| <img src="./docs/images/logo_xuanfeng.png" width="160"> | [Xuanfeng Technology (玄凤科技)](https://github.com/Eric0308) | Agradecimentos à [Xuanfeng Technology](https://github.com/Eric0308) por contribuir com o framework de chamada de função, protocolo de comunicação MCP e implementação do mecanismo de chamada baseado em plugins. Através de um sistema padronizado de agendamento de instruções e capacidades de expansão dinâmica, melhora significativamente a eficiência de interação e extensibilidade funcional dos dispositivos de frontend (IoT) |
+| <img src="../images/logo_xuanfeng.png" width="160"> | [Xuanfeng Technology (玄凤科技)](https://github.com/Eric0308) | Agradecimentos à [Xuanfeng Technology](https://github.com/Eric0308) por contribuir com o framework de chamada de função, protocolo de comunicação MCP e implementação do mecanismo de chamada baseado em plugins. Através de um sistema padronizado de agendamento de instruções e capacidades de expansão dinâmica, melhora significativamente a eficiência de interação e extensibilidade funcional dos dispositivos de frontend (IoT) |
-| <img src="./docs/images/logo_junsen.png" width="160"> | [huangjunsen](https://github.com/huangjunsen0406) | Agradecimentos a [huangjunsen](https://github.com/huangjunsen0406) por contribuir com o módulo `Console de Controle Inteligente Mobile`, que permite controle eficiente e interação em tempo real em dispositivos móveis, melhorando significativamente a conveniência operacional e a eficiência de gerenciamento do sistema em cenários móveis. |
+| <img src="../images/logo_junsen.png" width="160"> | [huangjunsen](https://github.com/huangjunsen0406) | Agradecimentos a [huangjunsen](https://github.com/huangjunsen0406) por contribuir com o módulo `Console de Controle Inteligente Mobile`, que permite controle eficiente e interação em tempo real em dispositivos móveis, melhorando significativamente a conveniência operacional e a eficiência de gerenciamento do sistema em cenários móveis. |
-| <img src="./docs/images/logo_huiyuan.png" width="160"> | [Huiyuan Design (汇远设计)](http://ui.kwd988.net/) | Agradecimentos à [Huiyuan Design](http://ui.kwd988.net/) por fornecer soluções visuais profissionais para este projeto, utilizando sua experiência prática de design atendendo mais de mil empresas para potencializar a experiência do usuário deste produto |
+| <img src="../images/logo_huiyuan.png" width="160"> | [Huiyuan Design (汇远设计)](http://ui.kwd988.net/) | Agradecimentos à [Huiyuan Design](http://ui.kwd988.net/) por fornecer soluções visuais profissionais para este projeto, utilizando sua experiência prática de design atendendo mais de mil empresas para potencializar a experiência do usuário deste produto |
-| <img src="./docs/images/logo_qinren.png" width="160"> | [Xi'an Qinren Information Technology (西安勤人信息科技)](https://www.029app.com/) | Agradecimentos à [Xi'an Qinren Information Technology](https://www.029app.com/) por aprofundar o sistema visual deste projeto, garantindo consistência e extensibilidade do estilo de design geral em aplicações de múltiplos cenários |
+| <img src="../images/logo_qinren.png" width="160"> | [Xi'an Qinren Information Technology (西安勤人信息科技)](https://www.029app.com/) | Agradecimentos à [Xi'an Qinren Information Technology](https://www.029app.com/) por aprofundar o sistema visual deste projeto, garantindo consistência e extensibilidade do estilo de design geral em aplicações de múltiplos cenários |
-| <img src="./docs/images/logo_contributors.png" width="160"> | [Contribuidores de Código](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors) | Agradecimentos a [todos os contribuidores de código](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors), seus esforços tornaram o projeto mais robusto e poderoso. |
+| <img src="../images/logo_contributors.png" width="160"> | [Contribuidores de Código](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors) | Agradecimentos a [todos os contribuidores de código](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors), seus esforços tornaram o projeto mais robusto e poderoso. |
 
 
 <a href="https://star-history.com/#xinnan-tech/xiaozhi-esp32-server&Date">

docs/readme/README_vi.md

@@ -1,4 +1,4 @@
-[![Banners](docs/images/banner1.png)](https://github.com/xinnan-tech/xiaozhi-esp32-server)
+[![Banners](../images/banner1.png)](https://github.com/xinnan-tech/xiaozhi-esp32-server)
 
 <h1 align="center">Dịch vụ Backend Xiaozhi xiaozhi-esp32-server</h1>
 
@@ -10,14 +10,14 @@ Hỗ trợ giao thức MQTT+UDP, giao thức Websocket, điểm truy cập MCP,
 </p>
 
 <p align="center">
-<a href="./docs/FAQ.md">Câu hỏi thường gặp</a>
+<a href="../FAQ.md">Câu hỏi thường gặp</a>
 · <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/issues">Báo cáo vấn đề</a>
-· <a href="./README.md#%E9%83%A8%E7%BD%B2%E6%96%87%E6%A1%A3">Tài liệu triển khai</a>
+· <a href="../../README.md#%E9%83%A8%E7%BD%B2%E6%96%87%E6%A1%A3">Tài liệu triển khai</a>
 · <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/releases">Nhật ký cập nhật</a>
 </p>
 
 <p align="center">
-  <a href="./README.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-DFE0E5"></a>
+  <a href="../../README.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-DFE0E5"></a>
   <a href="./README_en.md"><img alt="README in English" src="https://img.shields.io/badge/English-DFE0E5"></a>
   <a href="./README_vi.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/Tiếng Việt-DBEDFA"></a>
   <a href="./README_de.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-DFE0E5"></a>
@@ -38,7 +38,7 @@ Spearheaded by Professor Siyuan Liu's Team (South China University of Technology
 </br>
 Được dẫn dắt bởi nhóm Giáo sư Lưu Tư Nguyên (Đại học Bách khoa Nam Trung Quốc)
 </br>
-<img src="./docs/images/hnlg.jpg" alt="华南理工大学" width="50%">
+<img src="../images/hnlg.jpg" alt="华南理工大学" width="50%">
 </p>
 
 ---
@@ -52,113 +52,98 @@ Muốn xem hiệu quả sử dụng? Hãy xem video 🎥
 <table>
   <tr>
     <td>
-        <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
-         <picture>
+        <picture>
-           <img alt="响应速度感受" src="docs/images/demo9.png" />
+          <img alt="响应速度感受" src="docs/images/demo9.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1vchQzaEse" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1vchQzaEse" target="_blank">
-         <picture>
+        <picture>
-           <img alt="速度优化秘诀" src="docs/images/demo6.png" />
+          <img alt="速度优化秘诀" src="docs/images/demo6.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1C1tCzUEZh" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1WEcxzFEAT" target="_blank">
-         <picture>
+        <picture>
-           <img alt="复杂医疗场景" src="docs/images/demo1.png" />
+          <img alt="小智数字人 支持语音唤醒" src="docs/images/demo8.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1CKVz6UEuB" target="_blank">
-         <picture>
+        <picture>
-           <img alt="MQTT指令下发" src="docs/images/demo4.png" />
+          <img alt="设备呼叫设备，打电话" src="docs/images/demo0.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1C1tCzUEZh" target="_blank">
-         <picture>
+        <picture>
-           <img alt="声纹识别" src="docs/images/demo14.png" />
+          <img alt="复杂医疗场景" src="docs/images/demo1.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
   </tr>
   <tr>
     <td>
-        <a href="https://www.bilibili.com/video/BV1pNXWYGEx1" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
-         <picture>
+        <picture>
-           <img alt="控制家电开关" src="docs/images/demo5.png" />
+          <img alt="播放音乐查询天气播报新闻" src="docs/images/demo7.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
-         <picture>
-           <img alt="MCP接入点" src="docs/images/demo13.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-      <a href="https://www.bilibili.com/video/BV1TJ7WzzEo6" target="_blank">
-         <picture>
-           <img alt="多指令任务" src="docs/images/demo11.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
-         <picture>
-           <img alt="播放音乐" src="docs/images/demo7.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1Z8XuYZEAS" target="_blank">
-         <picture>
-           <img alt="天气插件" src="docs/images/demo8.png" />
-         </picture>
-        </a>
-    </td>
-  </tr>
-  <tr>
     <td>
       <a href="https://www.bilibili.com/video/BV12J7WzBEaH" target="_blank">
-         <picture>
+        <picture>
-           <img alt="实时打断" src="docs/images/demo10.png" />
+          <img alt="实时打断" src="docs/images/demo10.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
       <a href="https://www.bilibili.com/video/BV1Co76z7EvK" target="_blank">
-         <picture>
+        <picture>
-           <img alt="拍照识物品" src="docs/images/demo12.png" />
+          <img alt="拍照识物品" src="docs/images/demo12.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1pNXWYGEx1" target="_blank">
-         <picture>
+        <picture>
-           <img alt="自定义音色" src="docs/images/demo2.png" />
+          <img alt="控制家电开关" src="docs/images/demo5.png" /></picture>
-         </picture>
+      </a>
-        </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV12yA2egEaC" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1TJ7WzzEo6" target="_blank">
-         <picture>
+        <picture>
-           <img alt="使用粤语交流" src="docs/images/demo3.png" />
+          <img alt="多指令任务" src="docs/images/demo11.png" /></picture>
-         </picture>
+      </a>
-        </a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
+        <picture>
+          <img alt="MCP接入点" src="docs/images/demo13.png" /></picture>
+      </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV17LXWYvENb" target="_blank">
+      <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
-         <picture>
+        <picture>
-           <img alt="播报新闻" src="docs/images/demo0.png" />
+          <img alt="MQTT指令下发" src="docs/images/demo4.png" /></picture>
-         </picture>
+      </a>
-        </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
+        <picture>
+          <img alt="声纹识别" src="docs/images/demo14.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
+        <picture>
+          <img alt="自定义音色" src="docs/images/demo2.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV12yA2egEaC" target="_blank">
+        <picture>
+          <img alt="使用粤语交流" src="docs/images/demo3.png" /></picture>
+      </a>
     </td>
   </tr>
 </table>
@@ -176,17 +161,17 @@ Khuyến nghị người dùng ưu tiên lựa chọn nhà cung cấp dịch v
 
 ## Tài liệu triển khai
 
-![Banners](docs/images/banner2.png)
+![Banners](../images/banner2.png)
 
 Dự án này cung cấp hai phương pháp triển khai, vui lòng chọn theo nhu cầu cụ thể của bạn:
 
 #### 🚀 Lựa chọn phương pháp triển khai
 | Phương pháp triển khai | Đặc điểm | Tình huống áp dụng | Tài liệu triển khai | Yêu cầu cấu hình | Video hướng dẫn |
 |---------|------|---------|---------|---------|---------|
-| **Cài đặt tối giản** | Đối thoại thông minh, quản lý đơn tác nhân | Môi trường cấu hình thấp, dữ liệu lưu trong tệp cấu hình, không cần cơ sở dữ liệu | [①Phiên bản Docker](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) / [②Triển khai mã nguồn](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E5%8F%AA%E8%BF%90%E8%A1%8Cserver)| 2 nhân 4GB nếu dùng `FunASR`, 2 nhân 2GB nếu toàn API | - |
+| **Cài đặt tối giản** | Đối thoại thông minh, quản lý đơn tác nhân | Môi trường cấu hình thấp, dữ liệu lưu trong tệp cấu hình, không cần cơ sở dữ liệu | [①Phiên bản Docker](../Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) / [②Triển khai mã nguồn](../Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E5%8F%AA%E8%BF%90%E8%A1%8Cserver)| 2 nhân 4GB nếu dùng `FunASR`, 2 nhân 2GB nếu toàn API | - |
-| **Cài đặt toàn bộ module** | Đối thoại thông minh, quản lý đa người dùng, quản lý đa tác nhân, bảng điều khiển thông minh | Trải nghiệm đầy đủ tính năng, dữ liệu lưu trong cơ sở dữ liệu |[①Phiên bản Docker](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [②Triển khai mã nguồn](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [③Hướng dẫn tự động cập nhật triển khai mã nguồn](./docs/dev-ops-integration.md) | 4 nhân 8GB nếu dùng `FunASR`, 2 nhân 4GB nếu toàn API| [Video hướng dẫn khởi động mã nguồn cục bộ](https://www.bilibili.com/video/BV1wBJhz4Ewe) |
+| **Cài đặt toàn bộ module** | Đối thoại thông minh, quản lý đa người dùng, quản lý đa tác nhân, bảng điều khiển thông minh | Trải nghiệm đầy đủ tính năng, dữ liệu lưu trong cơ sở dữ liệu |[①Phiên bản Docker](../Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [②Triển khai mã nguồn](../Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [③Hướng dẫn tự động cập nhật triển khai mã nguồn](../dev-ops-integration.md) | 4 nhân 8GB nếu dùng `FunASR`, 2 nhân 4GB nếu toàn API| [Video hướng dẫn khởi động mã nguồn cục bộ](https://www.bilibili.com/video/BV1wBJhz4Ewe) |
 
-Câu hỏi thường gặp và hướng dẫn liên quan, vui lòng tham khảo [liên kết này](./docs/FAQ.md)
+Câu hỏi thường gặp và hướng dẫn liên quan, vui lòng tham khảo [liên kết này](../FAQ.md)
 
 > 💡 Gợi ý: Dưới đây là nền tảng thử nghiệm được triển khai theo mã mới nhất, có thể flash để thử nghiệm nếu cần, đồng thời là 6, dữ liệu sẽ được xóa mỗi ngày,
 
@@ -213,8 +198,8 @@ Công cụ kiểm tra dịch vụ: https://2662r3426b.vicp.fun/test/
 |:---:|:---:|:---:|
 | ASR(Nhận dạng giọng nói) | FunASR(Local) | 👍XunfeiStreamASR(Xunfei Streaming) |
 | LLM(Mô hình lớn) | glm-4-flash(Zhipu) | 👍qwen-flash(Alibaba Bailian) |
-| VLLM(Mô hình lớn thị giác) | glm-4v-flash(Zhipu) | 👍qwen2.5-vl-3b-instructh(Alibaba Bailian) |
+| VLLM(Mô hình lớn thị giác) | glm-4v-flash(Zhipu) | 👍qwen3.5-flash(Alibaba Bailian) |
-| TTS(Tổng hợp giọng nói) | ✅LinkeraiTTS(Lingxi streaming) | 👍HuoshanDoubleStreamTTS(Volcano Streaming) |
+| TTS(Tổng hợp giọng nói) | EdgeTTS(Microsoft) | 👍HuoshanDoubleStreamTTS(Volcano Streaming) |
 | Intent(Nhận dạng ý định) | function_call(Gọi hàm) | function_call(Gọi hàm) |
 | Memory(Chức năng bộ nhớ) | mem_local_short(Bộ nhớ ngắn hạn cục bộ) | mem_local_short(Bộ nhớ ngắn hạn cục bộ) |
 
@@ -225,7 +210,7 @@ Dự án này cung cấp các công cụ kiểm tra sau để giúp bạn xác m
 
 | Tên công cụ | Vị trí | Phương pháp sử dụng | Mô tả chức năng |
 |:---:|:---|:---:|:---:|
-| Công cụ kiểm tra tương tác âm thanh | main》xiaozhi-server》test》test_page.html | Mở trực tiếp bằng trình duyệt Google Chrome | Kiểm tra chức năng phát và nhận âm thanh, xác minh xử lý âm thanh phía Python có bình thường không |
+| Công cụ kiểm tra tương tác âm thanh | main》digital-human》index.html | Chạy `python start.py` trong `main/digital-human`, sau đó mở `http://127.0.0.1:8006/index.html` | Kiểm tra chức năng phát và nhận âm thanh, xác minh xử lý âm thanh phía Python có bình thường không |
 | Công cụ kiểm tra phản hồi mô hình | main》xiaozhi-server》performance_tester.py | Thực hiện `python performance_tester.py` | Kiểm tra tốc độ phản hồi của ba module cốt lõi ASR(Nhận dạng giọng nói), LLM(Mô hình lớn), VLLM(Mô hình thị giác), TTS(Tổng hợp giọng nói) |
 
 > 💡 Gợi ý: Khi kiểm tra tốc độ mô hình, chỉ kiểm tra các mô hình đã cấu hình khóa.
@@ -233,7 +218,7 @@ Dự án này cung cấp các công cụ kiểm tra sau để giúp bạn xác m
 ---
 ## Danh sách tính năng ✨
 ### Đã thực hiện ✅
-![请参考-全模块安装架构图](docs/images/deploy2.png)
+![请参考-全模块安装架构图](../images/deploy2.png)
 | Module chức năng | Mô tả |
 |:---:|:---|
 | Kiến trúc cốt lõi | Dựa trên [cổng MQTT+UDP](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/main/docs/mqtt-gateway-integration.md), WebSocket, máy chủ HTTP, cung cấp hệ thống quản lý bảng điều khiển và xác thực hoàn chỉnh |
@@ -253,9 +238,9 @@ Dự án này cung cấp các công cụ kiểm tra sau để giúp bạn xác m
 
 ### Đang phát triển 🚧
 
-Muốn hiểu tiến độ kế hoạch phát triển cụ thể, [vui lòng nhấp vào đây](https://github.com/users/xinnan-tech/projects/3). Câu hỏi thường gặp và hướng dẫn liên quan, vui lòng tham khảo [liên kết này](./docs/FAQ.md)
+Muốn hiểu tiến độ kế hoạch phát triển cụ thể, [vui lòng nhấp vào đây](https://github.com/users/xinnan-tech/projects/3). Câu hỏi thường gặp và hướng dẫn liên quan, vui lòng tham khảo [liên kết này](../FAQ.md)
 
-Nếu bạn là một nhà phát triển phần mềm, đây có một [Lá thư mở gửi các nhà phát triển](docs/contributor_open_letter.md), chào mừng tham gia!
+Nếu bạn là một nhà phát triển phần mềm, đây có một [Lá thư mở gửi các nhà phát triển](../contributor_open_letter.md), chào mừng tham gia!
 
 ---
 
@@ -330,7 +315,7 @@ Trên thực tế, bất kỳ VLLM nào hỗ trợ gọi giao diện openai đ
 |   Loại   |      Tên nền tảng       | Phương pháp sử dụng |   Mô hình thu phí    | Ghi chú |
 |:------:|:---------------:|:----:|:---------:|:--:|
 | Memory |     mem0ai      | Gọi giao diện | Hạn mức 1000 lần/tháng |    |
-| Memory |     [powermem](./docs/powermem-integration.md)    | Tóm tắt cục bộ | Phụ thuộc vào LLM và DB |  OceanBase mã nguồn mở, hỗ trợ tìm kiếm thông minh  |
+| Memory |     [powermem](../powermem-integration.md)    | Tóm tắt cục bộ | Phụ thuộc vào LLM và DB |  OceanBase mã nguồn mở, hỗ trợ tìm kiếm thông minh  |
 | Memory | mem_local_short | Tóm tắt cục bộ |    Miễn phí     |    |
 | Memory |     nomem       | Chế độ không có bộ nhớ |    Miễn phí     |    |
 
@@ -358,13 +343,13 @@ Trên thực tế, bất kỳ VLLM nào hỗ trợ gọi giao diện openai đ
 
 | Logo | Dự án/Công ty | Mô tả |
 |:---:|:---:|:---|
-| <img src="./docs/images/logo_bailing.png" width="160"> | [Robot đối thoại giọng nói Bailing](https://github.com/wwbin2017/bailing) | Dự án này được lấy cảm hứng từ [Robot đối thoại giọng nói Bailing](https://github.com/wwbin2017/bailing) và được triển khai trên cơ sở đó |
+| <img src="../images/logo_bailing.png" width="160"> | [Robot đối thoại giọng nói Bailing](https://github.com/wwbin2017/bailing) | Dự án này được lấy cảm hứng từ [Robot đối thoại giọng nói Bailing](https://github.com/wwbin2017/bailing) và được triển khai trên cơ sở đó |
-| <img src="./docs/images/logo_tenclass.png" width="160"> | [Shifang Ronghai](https://www.tenclass.com/) | Cảm ơn [Shifang Ronghai](https://www.tenclass.com/) đã xây dựng giao thức truyền thông tiêu chuẩn, phương án tương thích đa thiết bị và mô phạm thực hành tình huống đồng thời cao cho hệ sinh thái Xiaozhi; cung cấp tài liệu hỗ trợ kỹ thuật toàn diện cho dự án này |
+| <img src="../images/logo_tenclass.png" width="160"> | [Shifang Ronghai](https://www.tenclass.com/) | Cảm ơn [Shifang Ronghai](https://www.tenclass.com/) đã xây dựng giao thức truyền thông tiêu chuẩn, phương án tương thích đa thiết bị và mô phạm thực hành tình huống đồng thời cao cho hệ sinh thái Xiaozhi; cung cấp tài liệu hỗ trợ kỹ thuật toàn diện cho dự án này |
-| <img src="./docs/images/logo_xuanfeng.png" width="160"> | [Xuanfeng Technology](https://github.com/Eric0308) | Cảm ơn [Xuanfeng Technology](https://github.com/Eric0308) đã đóng góp khung gọi hàm, giao thức truyền thông MCP và mã triển khai cơ chế gọi dạng plugin, thông qua hệ thống điều phối lệnh tiêu chuẩn hóa và khả năng mở rộng động, đã cải thiện đáng kể hiệu suất tương tác và khả năng mở rộng chức năng của thiết bị front-end(IoT) |
+| <img src="../images/logo_xuanfeng.png" width="160"> | [Xuanfeng Technology](https://github.com/Eric0308) | Cảm ơn [Xuanfeng Technology](https://github.com/Eric0308) đã đóng góp khung gọi hàm, giao thức truyền thông MCP và mã triển khai cơ chế gọi dạng plugin, thông qua hệ thống điều phối lệnh tiêu chuẩn hóa và khả năng mở rộng động, đã cải thiện đáng kể hiệu suất tương tác và khả năng mở rộng chức năng của thiết bị front-end(IoT) |
-| <img src="./docs/images/logo_junsen.png" width="160"> | [huangjunsen](https://github.com/huangjunsen0406) | Cảm ơn [huangjunsen](https://github.com/huangjunsen0406) đã đóng góp module `Bảng điều khiển thông minh di động`, thực hiện điều khiển hiệu quả và tương tác thời gian thực trên thiết bị di động đa nền tảng, cải thiện đáng kể sự tiện lợi vận hành và hiệu quả quản lý của hệ thống trong tình huống di động |
+| <img src="../images/logo_junsen.png" width="160"> | [huangjunsen](https://github.com/huangjunsen0406) | Cảm ơn [huangjunsen](https://github.com/huangjunsen0406) đã đóng góp module `Bảng điều khiển thông minh di động`, thực hiện điều khiển hiệu quả và tương tác thời gian thực trên thiết bị di động đa nền tảng, cải thiện đáng kể sự tiện lợi vận hành và hiệu quả quản lý của hệ thống trong tình huống di động |
-| <img src="./docs/images/logo_huiyuan.png" width="160"> | [Huiyuan Design](http://ui.kwd988.net/) | Cảm ơn [Huiyuan Design](http://ui.kwd988.net/) đã cung cấp giải pháp thị giác chuyên nghiệp cho dự án này, sử dụng kinh nghiệm thực tế thiết kế phục vụ hơn nghìn doanh nghiệp, trao quyền cho trải nghiệm người dùng sản phẩm của dự án này |
+| <img src="../images/logo_huiyuan.png" width="160"> | [Huiyuan Design](http://ui.kwd988.net/) | Cảm ơn [Huiyuan Design](http://ui.kwd988.net/) đã cung cấp giải pháp thị giác chuyên nghiệp cho dự án này, sử dụng kinh nghiệm thực tế thiết kế phục vụ hơn nghìn doanh nghiệp, trao quyền cho trải nghiệm người dùng sản phẩm của dự án này |
-| <img src="./docs/images/logo_qinren.png" width="160"> | [Xi'an Qinren Information Technology](https://www.029app.com/) | Cảm ơn [Xi'an Qinren Information Technology](https://www.029app.com/) đã làm sâu sắc hệ thống thị giác của dự án này, đảm bảo tính nhất quán và khả năng mở rộng của phong cách thiết kế tổng thể trong ứng dụng đa tình huống |
+| <img src="../images/logo_qinren.png" width="160"> | [Xi'an Qinren Information Technology](https://www.029app.com/) | Cảm ơn [Xi'an Qinren Information Technology](https://www.029app.com/) đã làm sâu sắc hệ thống thị giác của dự án này, đảm bảo tính nhất quán và khả năng mở rộng của phong cách thiết kế tổng thể trong ứng dụng đa tình huống |
-| <img src="./docs/images/logo_contributors.png" width="160"> | [Người đóng góp mã](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors) | Cảm ơn [tất cả người đóng góp mã](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors), sự cống hiến của bạn khiến dự án mạnh mẽ và vững chắc hơn. |
+| <img src="../images/logo_contributors.png" width="160"> | [Người đóng góp mã](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors) | Cảm ơn [tất cả người đóng góp mã](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors), sự cống hiến của bạn khiến dự án mạnh mẽ và vững chắc hơn. |
 
 
 <a href="https://star-history.com/#xinnan-tech/xiaozhi-esp32-server&Date">

docs/unified-fastapi-platform/README.md

@@ -0,0 +1,88 @@
+# 统一 FastAPI 平台开发计划
+
+状态：规划基线
+
+更新时间：2026-07-20
+
+## 1. 项目目标
+
+把 `manager-api-fastapi`、`manager-web` 和 `xiaozhi-server` 组织成同一套可版本化、可测试、
+可部署和可回滚的平台，同时保持当前用户可见功能、设备协议和已存数据可用。
+
+这里的“统一”指同一代码库、同一发布版本和同一公网入口，不要求所有职责运行在同一个
+Uvicorn worker。生产环境保留 API、实时连接和定时任务的独立进程边界，轻量环境可以使用
+单 worker 的 `all` 运行模式。
+
+## 2. 完成定义
+
+进入真实环境验收前，仓库必须同时满足：
+
+1. 管理端页面及其现有操作均由统一发行物提供。
+2. 管理 REST API、设备 OTA、WebSocket、Vision、MCP、IoT 和 MQTT 桥接协议均有自动化契约测试。
+3. 虚拟设备可以完成连接、绑定、对话、中断、工具调用、断线和重连的端到端流程。
+4. 所有 Provider 均完成接口适配和 Fake/契约验证；无需真实凭证的路径全部自动通过。
+5. MySQL、Redis、文件、配置热更新、jobs、升级和回滚均经过隔离集成测试。
+6. 统一 Docker/Compose 发行物可启动，健康检查、日志、指标和优雅停机可验证。
+7. 所有尚未验证的风险只依赖真实设备、真实外部服务或目标生产环境，并已列入交接清单。
+
+达到以上条件后，项目状态为 `RC / 等待真实环境验收`，不能提前表述为生产验收完成。
+
+## 3. 范围
+
+包含：
+
+- `manager-api-fastapi` 已有管理 API、数据库、Redis、文件和 jobs 能力。
+- `manager-web` 的构建、静态交付、PWA 和浏览器业务流程。
+- `xiaozhi-server` 的设备 WebSocket、音频会话、Provider、Vision、MCP、IoT、插件和网关桥接能力。
+- 本地轻量配置模式与数据库控制台模式，但共享一套实现，不保留重复路由。
+- CI、镜像、部署、可观测性、迁移、回滚和真实测试交接。
+
+不包含：
+
+- 改变现有业务规则或重新设计管理端产品体验。
+- 在没有凭证时声称云 Provider 已真实联调。
+- 把外部 MQTT/UDP gateway、RAGFlow 或云模型服务复制进本仓库。
+- 在没有真实 ESP32 和目标环境时批准生产上线。
+
+## 4. 不可破坏的兼容边界
+
+- 设备 OTA URL、请求头、响应字段及激活行为。
+- `/xiaozhi/v1/` 的 WebSocket 握手、文本消息、Opus 帧和 MQTT 桥接帧。
+- Device-ID、Client-ID、服务密钥和 HMAC Token 语义。
+- 已有数据库数据、用户权限、智能体配置、模型标识及文件资产。
+- 当前 Web、Mobile 和设备仍在使用的公开 API；内部自调用不属于兼容边界。
+- 已启用 Provider 的配置字段和可观察结果。
+
+## 5. 工作原则
+
+1. 先记录现状，再替换实现：没有特征测试的行为不得直接重写。
+2. 以可工作的纵向切片提交 PR，避免一次性迁移整个实时服务。
+3. 共享代码，隔离运行职责：API、realtime、jobs 可以使用同一镜像但独立启动。
+4. 新旧实现可并行对照且可回滚，删除旧入口必须是最后阶段。
+5. Provider 按能力族批量适配，默认不为每个供应商启动独立 Agent。
+6. 每个 PR 只有一个明确负责人和一个独立审阅角色。
+7. 自动化可以判断的事项不等待人工；真实环境不可替代的事项不得用 Mock 冒充通过。
+
+## 6. 文档导航
+
+- [目标架构](architecture.md)
+- [阶段路线图与 PR 队列](roadmap.md)
+- [多岗位 Agent 协作模型](agent-operating-model.md)
+- [质量门禁](quality-gates.md)
+- [架构与交付决策](decisions.md)
+- [风险登记册](risk-register.md)
+- [真实环境测试交接](real-environment-handoff.md)
+
+## 7. 当前基线
+
+- FastAPI 管理 API 已形成 154 条 Java 路由兼容基线和现有测试报告，但逐路由直接深度差分
+  目前只覆盖 21/154；其余成功路径和副作用证据必须在 M5 前补齐。
+- manager-web 的 i18n、unit、snapshot 和生产构建已有绿色记录。
+- xiaozhi-server 可通过 Python 语法编译，但缺少正式自动化单测和设备协议回归套件。
+- FastAPI、部署文档和脚本已作为集成分支基线提交；后续重构只通过目标为该分支的 PR 进入。
+- 真实 RAGFlow、短信、语音、MQTT/MCP 和 ESP32 尚未验收。
+
+项目状态以 [roadmap.md](roadmap.md) 的阶段门禁为唯一进度来源。
+
+开发期间以 `refactor/unified-fastapi-platform` 为长期集成分支。所有规划和实现 PR 均合入该分支，
+不会在纯 Agent 阶段向 `main` 创建 PR。

docs/unified-fastapi-platform/agent-operating-model.md

@@ -0,0 +1,118 @@
+# 多岗位 Agent 协作模型
+
+## 1. 岗位与责任
+
+| 岗位 | 主要责任 | 不负责 |
+| --- | --- | --- |
+| PM / 集成负责人 | 范围、优先级、依赖、PR 队列、风险、最终门禁 | 代替专项 Agent 编写所有业务实现 |
+| 架构负责人 | 接口边界、ADR、跨模块依赖、并发和状态模型 | 未经测试直接大规模搬迁代码 |
+| Realtime 工程 Agent | ASGI WebSocket、DeviceSession、音频队列和生命周期 | 修改管理业务规则 |
+| Backend 工程 Agent | 应用服务、配置、数据库、Redis、bootstrap | 修改设备协议 |
+| Provider 工程 Agent | 按能力族适配已有 Provider | 改变供应商可见配置语义 |
+| Frontend/交付 Agent | manager-web 构建、静态托管和路由 | 重做页面产品设计 |
+| Platform/SRE Agent | CI、镜像、Compose、健康、指标、升级回滚 | 在缺少证据时批准上线 |
+| QA Agent | 特征测试、差分、虚拟设备、E2E、性能和故障注入 | 为使测试变绿而放宽契约 |
+| 独立 Reviewer | 安全、兼容、并发、资源和证据审阅 | 与实现者共享同一结论来源 |
+
+## 2. 工作包准入
+
+分配给 Agent 前，工作包必须明确：
+
+- 目标和不在范围内的事项。
+- 允许修改的目录和禁止修改的公共接口。
+- 上游依赖及其版本/提交。
+- 必须新增或保持的测试。
+- 完成命令和预期证据。
+- 需要升级给 PM 的决策点。
+
+工作包模板：
+
+```text
+目标：
+用户可见结果：
+允许修改：
+禁止修改：
+输入契约：
+输出契约：
+必须运行：
+完成条件：
+已知风险：
+```
+
+## 3. 资源控制
+
+1. 默认使用一个实现 Agent；只有文件所有权互斥且确有关键路径收益时才并行。
+2. 同时活动的实现 Agent 不超过三个，另保留一个集成/审阅角色。
+3. 不为单个 Provider 启动一个 Agent；按能力族分组，出现特有失败时再拆分。
+4. 不让两个 Agent 重复做全仓审计。审阅 Agent 只读取 PR diff、契约和相关文件。
+5. 大型上下文按目录和接口裁剪；交接必须写入文档或 PR，不依赖聊天记忆。
+6. 长耗时集成、容器、性能测试只在相关代码变化、里程碑收口或夜间任务运行。
+7. 发现范围外缺陷时记录后移，不顺手扩张当前 PR。
+
+## 4. 文件所有权与冲突避免
+
+活动 PR 必须声明临时所有权：
+
+| 范围 | 默认岗位 |
+| --- | --- |
+| `app/realtime/**`、协议测试 | Realtime |
+| `app/application/**`、`app/domain/**` | Architecture/Backend |
+| `app/providers/**` | 对应 Provider 能力族 |
+| `app/api/**`、现有 routers/services | Backend |
+| `main/manager-web/**`、gateway 静态配置 | Frontend/交付 |
+| Docker、Compose、CI | Platform/SRE |
+| `tests/e2e/**`、虚拟设备、差分工具 | QA |
+| 本目录路线图、风险和交接文档 | PM/集成 |
+
+需要跨所有权修改时，先由当前所有者提供最小接口，再继续实现；禁止在合并阶段才发现公共接口冲突。
+
+## 5. 分支与 PR 规则
+
+- 长期集成分支：`refactor/unified-fastapi-platform`；纯 Agent 阶段的开发 PR 均以它为目标。
+- 工作分支命名：`platform/<milestone>-<short-topic>`。
+- 分支名、Commit 和 PR 标题遵守仓库禁用词要求。
+- Commit 使用结果导向格式，例如 `test: add device protocol characterization`。
+- 一个 PR 只交付一个计划工作包或一个可独立回滚的纵向切片。
+- PR 描述必须列出阶段、依赖、契约影响、验证命令、风险和回滚方法。
+- 实现者不得作为唯一 Reviewer；高风险协议、鉴权、迁移和并发 PR 必须有专项审阅。
+- 合并前同步最新目标分支并重新运行必需门禁。
+- 不允许未解释的 skip、仅本机通过、手工修改测试数据或把 Mock 结果描述成真实联调。
+- 未经项目所有者明确批准，不创建以 `main` 为目标的 PR。
+
+可选 PR 模板位于 `.github/PULL_REQUEST_TEMPLATE/unified-platform.md`。
+
+## 6. PR 生命周期
+
+```text
+Ready work package
+  -> implementation + local tests
+  -> draft PR + evidence
+  -> independent review
+  -> required CI gates
+  -> PM dependency/risk check
+  -> merge
+  -> roadmap evidence link
+```
+
+发生以下任一情况必须暂停并升级：
+
+- 需要改变设备公开协议或现有数据语义。
+- 需要真实凭证、真实设备或目标环境才能判断实现方向。
+- 同一测试在旧实现上也失败，且无法确定基线行为。
+- 依赖冲突要求删除现有 Provider。
+- PR 需要跨越两个以上尚未完成的里程碑。
+
+## 7. Agent 交接格式
+
+```text
+完成内容：
+变更文件：
+契约变化：无 / 具体说明
+执行过的命令与结果：
+未执行项目及原因：
+遗留风险：
+下一工作包可依赖的接口：
+建议 Reviewer 重点：
+```
+
+没有上述交接或可重复证据的工作不进入集成分支。

docs/unified-fastapi-platform/architecture.md

@@ -0,0 +1,141 @@
+# 目标架构
+
+## 1. 架构决策
+
+统一平台采用“模块化单体代码库、按职责运行”的结构：
+
+```text
+Public HTTP/WSS
+       |
+       v
+Gateway / static web
+  |          |                 |
+  |          |                 +--> /mcp/vision/explain
+  |          +--------------------> /xiaozhi/v1/  -> realtime
+  +-------------------------------> /xiaozhi/*    -> api
+
+api ----------- application services -------- database / redis / object files
+realtime ------ application services -------- provider adapters
+jobs ---------- application services -------- scheduled work
+```
+
+同一发布版本提供四个角色：
+
+| 角色 | 职责 | 扩缩容方式 |
+| --- | --- | --- |
+| `gateway` | manager-web、TLS、静态缓存、HTTP/WS 路由 | 无状态横向扩展 |
+| `api` | 管理 REST、OTA、文件和内部服务端 API | 多 worker/多副本 |
+| `realtime` | 设备 WebSocket、音频会话、Vision、Provider 和工具 | 按连接与模型容量扩展 |
+| `jobs` | 定时同步、清理和异步补偿 | Redis 租约保证单任务所有权 |
+
+开发环境可以用一个命令启动全部角色；生产环境不得要求 realtime 与 API 共享 worker。
+
+## 2. 建议代码边界
+
+```text
+main/manager-api-fastapi/
+├── app/
+│   ├── api/                 # HTTP 路由和请求适配
+│   ├── application/         # 用例服务；HTTP、WS、jobs 共用
+│   ├── domain/              # 稳定业务对象和接口
+│   ├── realtime/            # ASGI WebSocket、会话和协议
+│   ├── providers/           # VAD/ASR/LLM/VLLM/TTS/Memory/Intent/Tools
+│   ├── infrastructure/      # MySQL、Redis、文件、外部客户端
+│   └── jobs/
+├── web/                     # manager-web 构建集成或其产物约定
+├── tests/
+│   ├── unit/
+│   ├── contract/
+│   ├── integration/
+│   ├── protocol/
+│   └── e2e/
+└── deploy/
+```
+
+迁移期间允许现有目录继续存在；目录调整必须跟随可运行的纵向切片，不做只有移动文件的超大 PR。
+
+## 3. 关键内部接口
+
+### 3.1 应用服务
+
+Realtime 不再通过 HTTP 调用同一平台。以下能力通过应用服务接口复用：
+
+- 获取全局配置和设备专属 Agent 配置。
+- 设备绑定、激活、在线状态和通讯录查找。
+- 聊天记录、音频、摘要、标题和工具调用上报。
+- OTA、文件和参数读取。
+
+HTTP 只是这些服务的一个适配器。服务方法不接收 FastAPI `Request`，也不返回 HTTP Response。
+
+### 3.2 实时会话
+
+每个连接由一个 `DeviceSession` 拥有，至少包含：
+
+- 握手元数据与设备鉴权。
+- 有界输入/输出音频队列。
+- 文本协议路由。
+- VAD/ASR/LLM/TTS/工具调用任务。
+- 取消、超时、断线保存和资源关闭。
+
+使用 ASGI WebSocket 抽象，不让 Provider 依赖 Starlette 或 `websockets.ServerConnection`。
+
+### 3.3 Provider
+
+Provider 通过能力协议注册，配置标识保持现状。同步 SDK 必须通过受限线程池或专用执行器调用，
+禁止在事件循环中直接进行阻塞网络或长时间 CPU 工作。
+
+Provider 按以下能力族迁移：
+
+1. VAD + ASR。
+2. LLM + VLLM + Memory + Intent。
+3. TTS。
+4. Tools + MCP + IoT + 插件。
+
+本地 Torch/FunASR/Sherpa 等能力作为可选依赖组和镜像 profile，基础 API 镜像不强制加载模型。
+
+## 4. 配置与控制面
+
+- 数据库是完整模式下的配置事实来源。
+- Redis 保存有版本号的缓存，并通过 Pub/Sub 广播配置失效和控制事件。
+- worker 原子替换共享配置；现有会话可完成当前轮次，新会话使用新版本。
+- `server.secret`、SM2 密钥和其他必需系统参数由并发安全的 bootstrap 初始化。
+- 进程重启交给容器编排或服务管理器，业务代码不自行 fork、spawn 或 `os._exit()`。
+- 轻量模式使用文件配置适配器，但进入相同应用服务，不复制 OTA 或会话实现。
+
+## 5. 路由与兼容策略
+
+| 公共入口 | 所有者 | 迁移策略 |
+| --- | --- | --- |
+| `/` | manager-web | 构建产物由 gateway 托管，保留 PWA scope |
+| `/xiaozhi/*` | api | 保留当前调用方契约 |
+| `/xiaozhi/ota/` | api | 完整模式只保留数据库驱动实现 |
+| `/xiaozhi/v1/` | realtime | 保持设备协议，gateway 支持 Upgrade |
+| `/mcp/vision/explain` | realtime | 独立设备鉴权域，不继承管理用户鉴权 |
+
+迁移期可以继续监听 8000/8002/8003 作为兼容别名；最终公网地址由 gateway 统一，OTA 返回值和
+系统参数必须在切换前验证。
+
+## 6. 部署档位
+
+### Lite
+
+- 单 worker。
+- 文件或数据库配置。
+- 可将 API、realtime 和 jobs 放在同一进程用于本地体验。
+- 不作为生产容量结论的依据。
+
+### Production
+
+- gateway、API、realtime、jobs 独立进程或容器。
+- 共享 MySQL、Redis 和明确的持久化卷。
+- realtime 按模型内存和连接数单独扩容。
+- 发布时先摘流，等待连接排空，再终止旧实例。
+
+## 7. 架构完成门禁
+
+- 公开契约清单有可执行测试。
+- API 与 realtime 不通过环回 HTTP 互调。
+- 多 realtime worker 的配置更新能够广播到全部实例。
+- realtime 停止时不产生孤儿线程、遗留任务或自行启动的新进程。
+- Lite 与 Production 使用相同业务实现。
+- 旧 xiaozhi-server 入口只有在新实现通过全部自动门禁后才能删除。

docs/unified-fastapi-platform/decisions.md

@@ -0,0 +1,82 @@
+# 架构与交付决策
+
+本文件记录跨 PR 的稳定决策。普通实现 PR 不得顺手改变已接受决策；需要变更时，先提交新的
+决策记录并说明替代关系。
+
+## D001：统一代码库，按职责运行
+
+- 状态：Accepted
+- 决策：gateway、API、realtime 和 jobs 使用同一发布版本，但生产环境独立运行。
+- 原因：REST、长连接、模型内存和定时任务的扩缩容及故障边界不同。
+- 后果：允许 Lite 单 worker `all` 模式；生产容量不得由 Lite 推断。
+- 重新评估：有证据证明单进程能够满足模型内存、多 worker 配置一致性和故障隔离。
+
+## D002：只冻结外部行为
+
+- 状态：Accepted
+- 决策：设备、调用方、数据和已启用 Provider 的可观察行为保持；内部类、库、线程模型、目录和
+  自调用方式可以重构。
+- 原因：目标是保留现有功能，不保留实现偶然性。
+- 后果：manager-web 与后端可以协同调整内部接口，但设备固件契约必须保持。
+- 重新评估：产品所有者批准公开行为变更并提供迁移方案。
+
+## D003：特征测试先于 realtime 重构
+
+- 状态：Accepted
+- 决策：M1 的黄金报文、虚拟设备和 Fake Provider 是 ASGI 会话重构的前置条件。
+- 原因：xiaozhi-server 当前没有正式协议回归套件。
+- 后果：不能以“代码更整洁”为由跳过旧行为记录。
+- 重新评估：无。
+
+## D004：应用服务替代内部 HTTP 自调用
+
+- 状态：Accepted
+- 决策：完整模式下 API 与 realtime 共享应用服务端口，不通过环回 HTTP 调用自己。
+- 原因：减少密钥复制、网络重试和同进程/多进程语义差异。
+- 后果：HTTP router 只负责协议适配，长连接不持有数据库 Session。
+- 重新评估：跨语言或跨安全域部署成为明确需求。
+
+## D005：Redis 承担配置版本事件，不承担事实来源
+
+- 状态：Accepted
+- 决策：数据库是完整配置事实来源；Redis 缓存有版本的快照并广播失效/控制事件。
+- 原因：支持多 realtime worker 一致更新和 Java 回滚期兼容。
+- 后果：配置事件必须可观测，worker 必须暴露当前版本。
+- 重新评估：引入独立且受运维支持的消息系统。
+
+## D006：Provider 按能力族迁移
+
+- 状态：Accepted
+- 决策：按 VAD/ASR、LLM/VLLM/Memory/Intent、TTS、Tools/MCP/IoT 四组迁移。
+- 原因：限制 Agent 数量、统一契约并避免每个供应商重复搭建测试框架。
+- 后果：只有出现供应商特有阻塞时才拆分单独工作包。
+- 重新评估：某 Provider 需要独立进程或不可兼容的系统依赖。
+
+## D007：集成分支承载全部开发 PR
+
+- 状态：Accepted
+- 决策：纯 Agent 阶段所有 PR 目标为 `refactor/unified-fastapi-platform`。
+- 原因：项目所有者要求开发 PR 不进入主分支，并需要统一的长期集成点。
+- 后果：PM 负责持续同步上游并在每个里程碑重跑消费者与协议清单。
+- 重新评估：仅由项目所有者明确批准。
+
+## D008：真实环境是独立验收门
+
+- 状态：Accepted
+- 决策：ESP32、真实 Provider、MQTT/RAGFlow 和目标网络只能在 M8 判定。
+- 原因：Mock 和模拟不能证明硬件、供应商及生产网络事实。
+- 后果：M7 可以形成 RC，但不能发布正式版本或描述为生产通过。
+- 重新评估：所需真实资产已经安全接入自动化环境。
+
+## 新决策模板
+
+```text
+ID / 日期 / 状态
+背景：
+决策：
+备选方案：
+后果：
+验证方式：
+重新评估触发条件：
+Owner / 关联 PR：
+```

docs/unified-fastapi-platform/quality-gates.md

@@ -0,0 +1,117 @@
+# 质量门禁
+
+## 1. 原则
+
+自动测试负责证明“实现符合可观察的现有行为”；真实测试负责证明“设备、供应商和生产网络确实
+按预期工作”。两类证据不得互相替代。
+
+## 2. 测试层次
+
+| 层次 | 目标 | 典型内容 | 运行时机 |
+| --- | --- | --- | --- |
+| 静态 | 快速发现格式、类型、依赖问题 | Ruff、Mypy、前端 lint/type、配置校验 | 每次提交 |
+| 单元 | 验证纯逻辑与状态转换 | Token、协议解析、队列、配置版本、Provider DTO | 每次提交 |
+| 特征/契约 | 冻结现有可观察行为 | 旧服务黄金报文、API envelope、设备帧、Provider 请求 | 每个 PR |
+| 隔离集成 | 验证真实本地依赖 | MySQL、Redis、文件、jobs、Pub/Sub、事务 | 每个相关 PR |
+| 模拟 E2E | 验证用户和设备流程 | manager-web、虚拟设备、Fake Provider、统一 gateway | 每个里程碑 |
+| 差分 | 比较旧/新实现 | REST、OTA、WS 会话和副作用 | M1 起持续运行 |
+| 非功能 | 容量和恢复 | 多连接、背压、断线、摘流、资源泄漏、安全 | M6/M7 |
+| 真实环境 | 外部事实 | ESP32、云 Provider、MQTT/RAGFlow、目标部署 | M8 |
+
+## 3. CI 分层
+
+### Tier A：快速门禁
+
+目标是在常规 PR 中快速反馈，建议控制在 10 分钟内：
+
+- FastAPI Ruff、Mypy、unit/contract pytest。
+- manager-web i18n、unit、snapshot。
+- xiaozhi-server/迁移代码语法与导入检查。
+- 路由、消费者和生成文档一致性。
+- Secret 扫描和部署配置静态检查。
+
+从 P01 建立覆盖率基线后，变更行覆盖率不得低于 85%，协议解析和会话状态机的分支覆盖率
+不得低于 90%，全局覆盖率不得下降。覆盖率用于发现遗漏，不允许为了数字制造无行为价值的测试。
+
+### Tier B：PR 集成门禁
+
+- 隔离 MySQL/Redis。
+- manager-web 生产构建及浏览器关键路径。
+- 虚拟设备完整对话流程。
+- Fake Provider 覆盖成功、超时、断流、取消和错误映射。
+- API/realtime/jobs 镜像构建与 Compose readiness。
+- 修改范围对应的旧/新差分。
+
+### Tier C：里程碑门禁
+
+- 全量旧/新差分。
+- 多 realtime worker 配置广播。
+- 并发连接和 60 分钟模拟 soak。
+- 优雅摘流、进程终止、Redis/MySQL 短暂故障恢复。
+- 依赖漏洞、鉴权边界和恶意输入测试。
+- 支持架构的镜像构建或至少可重复的构建证明。
+
+Tier C 不在每个小 PR 重复运行，以节约资源；相关核心代码变化或阶段收口时必须运行。
+
+性能采用相同 runner 上的新旧实现相对比较。初始自动门槛为：
+
+- Fake Provider 下业务错误率为 0。
+- WebSocket 握手和控制消息 p95 回退不超过 15%。
+- 可完成会话吞吐回退不超过 10%。
+- 每个 realtime PR 运行 20 个虚拟连接、5 分钟；RC 运行 100 个虚拟连接、60 分钟。
+- 测试结束后 RSS、线程、async task、文件描述符和临时文件不得持续线性增长。
+
+这些指标只约束模拟回归，不代表真机容量结论；如固定测试机不足，PR 必须记录实际档位，不能
+静默降低门槛。
+
+## 4. 必须建立的协议场景
+
+虚拟设备测试至少覆盖：
+
+1. OTA 获取 WebSocket/MQTT 信息和未绑定激活码。
+2. WebSocket header 与 query 参数两种握手。
+3. hello、listen、abort、ping、iot、mcp、server 控制消息。
+4. Opus 音频输入、ASR 文本、LLM 流、TTS 文本及音频输出。
+5. 唤醒、连续对话、主动中断、无语音超时。
+6. 设备绑定前后的行为。
+7. Provider 超时、断流、无内容、限流和取消。
+8. 客户端断线、服务摘流和重连。
+9. MQTT gateway 16 字节桥接帧的编码与解码。
+10. 配置更新只影响约定的当前或后续会话。
+
+黄金数据必须脱敏、可提交且带版本说明。不能从一次偶然运行直接认定为规范；旧代码、文档和至少
+一个调用方必须交叉确认。
+
+## 5. PR 合并门禁
+
+所有 PR：
+
+- 计划工作包和文件所有权明确。
+- 新行为有测试，重构行为有特征/差分证据。
+- 相关 Tier A 全绿。
+- 无未解释 skip、xfail、warning 激增或生成文件漂移。
+- 文档和配置随行为同步。
+- 回滚方法明确。
+
+高风险 PR 额外要求：
+
+- 设备协议：协议 Reviewer + 虚拟设备差分。
+- 鉴权/密钥：Security Reviewer + 失败路径和密钥泄露检查。
+- 数据迁移：全新库、已有库、重复执行和回滚测试。
+- 并发/任务：取消、超时、资源关闭和故障注入。
+- Provider 公共接口：所有能力族契约测试通过。
+
+## 6. RC 自动化退出条件
+
+只有满足以下全部条件，才能转入真实测试：
+
+- 所有计划 PR P00-P12 已合并或明确取消并记录理由。
+- 公开兼容边界全部关联到自动测试。
+- 虚拟设备和 manager-web E2E 全绿。
+- 所有 Provider 适配器通过 Fake/契约矩阵。
+- 没有 P0/P1 内部缺陷；P2 风险有接受或后续方案。
+- 统一发行物在干净环境完成安装、升级和回滚。
+- 模拟负载下没有无界内存、线程、任务或文件增长。
+- 未验证项逐条映射到真实环境交接用例。
+
+满足这些条件代表“纯 Agent 阶段完成”，不代表真实 Provider 或硬件已经通过。

docs/unified-fastapi-platform/real-environment-handoff.md

@@ -0,0 +1,90 @@
+# 真实环境测试交接
+
+## 1. 何时交接
+
+只有 [质量门禁](quality-gates.md) 的 RC 自动化退出条件全部满足，才进入本清单。以下情况不属于
+真实环境阻塞，必须由开发阶段解决：
+
+- 本地依赖无法安装或镜像无法构建。
+- 虚拟设备协议不一致。
+- Fake Provider 成功/错误/取消契约失败。
+- 数据库、Redis、文件权限或配置广播失败。
+- 缺少测试脚本、日志字段或复现步骤。
+
+## 2. 外部资产
+
+| 资产 | 最低要求 | 提供方 |
+| --- | --- | --- |
+| ESP32 | 至少一台生产使用型号；记录固件版本 | Hardware QA |
+| 网络 | 局域网与公网 WSS；可控制弱网/断网 | Ops/QA |
+| 模型凭证 | 实际计划启用的 ASR、LLM、TTS，必要时 VLLM | Service owner |
+| MQTT/UDP | 受支持版本的 gateway、broker 和端口 | Integration/Ops |
+| RAGFlow | 受支持版本、测试数据集和访问凭证 | Knowledge owner |
+| 可选服务 | 短信、声纹、语音克隆、MCP、Memory | 对应服务 owner |
+| 目标主机 | 计划上线的 CPU/GPU/架构、Docker/Compose 或编排平台 | Ops |
+| 域名证书 | HTTPS/WSS 域名、证书和反向代理权限 | Ops |
+
+凭证不得写入 Issue、PR、测试产物或仓库；通过部署环境的 Secret 管理提供。
+
+## 3. 必测场景
+
+### 设备与音频
+
+- 首次启动、OTA、激活和绑定。
+- WebSocket 鉴权和长连接保持。
+- 唤醒、单轮/连续对话、打断、静音超时和重连。
+- 真实麦克风、扬声器、AEC、Opus 帧节奏和中文/非中文语音。
+- 弱网、高延迟、短时断网和服务滚动发布。
+
+### Provider
+
+- 每个计划启用 Provider 的成功、流式、空结果、超时、限流和凭证错误。
+- ASR 音频格式、TTS 音频参数、LLM 工具调用及取消行为。
+- 供应商控制台侧请求量、错误和费用符合预期。
+
+### 外部集成
+
+- MQTT/UDP 上下行音频与控制消息。
+- RAGFlow 上传、解析、检索、删除和故障补偿。
+- Vision 图片上传、鉴权、大小/格式限制和真实结果。
+- 按实际启用范围验证短信、声纹、语音克隆、MCP 和通讯录呼叫。
+
+### 部署
+
+- 全新安装、已有数据升级、滚动发布和回滚。
+- 非 root 文件权限、模型卷、上传卷和日志采集。
+- API、realtime、jobs 独立健康与告警。
+- 目标容量下的连接数、CPU/GPU、内存、带宽和响应时间。
+
+## 4. 证据格式
+
+每条真实用例记录：
+
+```text
+Case ID：
+日期/测试人：
+硬件与固件：
+服务版本/Commit：
+外部服务及版本：
+网络与部署环境：
+步骤：
+预期：
+实际：
+日志/指标/录屏位置：
+结果：Pass / Fail / Blocked
+缺陷链接：
+```
+
+敏感字段在上传前脱敏。失败必须能关联到服务器会话 ID、设备 ID 的脱敏标识和时间窗口。
+
+## 5. 上线判定
+
+生产批准至少要求：
+
+- 选定 ESP32/固件矩阵通过。
+- 实际启用的 Provider 和外部集成通过，不要求未启用供应商全部真实联调。
+- 目标环境升级与回滚演练通过。
+- 没有 P0/P1 缺陷。
+- 监控、告警、值守和回滚负责人明确。
+
+未提供的外部能力应标记为“未验收/不可启用”，不得以自动化 Mock 结果改为 Pass。

docs/unified-fastapi-platform/risk-register.md

@@ -0,0 +1,27 @@
+# 风险登记册
+
+| ID | 风险 | 概率/影响 | 缓解措施 | 触发升级条件 | Owner |
+| --- | --- | --- | --- | --- | --- |
+| R01 | xiaozhi-server 缺少正式协议测试，重构造成隐性漂移 | 高/高 | M1 先建立黄金报文、虚拟设备和旧/新差分 | 无法从旧代码和调用方确定行为 | QA + Realtime |
+| R02 | REST API worker 与实时模型共享进程导致内存和延迟失控 | 高/高 | 同代码库、独立运行角色；Lite 仅单 worker | 生产方案要求单进程多 worker | Architecture |
+| R03 | `websockets`、PyYAML 及重模型依赖冲突 | 高/高 | 统一锁文件、Provider extras、镜像 profile | 必须删除现有 Provider 才能解析 | Platform + Provider |
+| R04 | `server.secret`/SM2 首次初始化或轮换不一致 | 高/高 | 并发安全 bootstrap、单一事实来源、广播测试 | 任一 worker 使用不同密钥 | Backend + Security |
+| R05 | 配置热更新只到达部分 realtime worker | 中/高 | Redis 版本事件、ack/指标、全 worker 集成测试 | 版本长时间不一致 | Backend + SRE |
+| R06 | 线程、任务或 SDK 阻塞事件循环 | 高/高 | DeviceSession 所有权、有界执行器、soak/lag 指标 | 负载下 API/WS 延迟无界增长 | Realtime + QA |
+| R07 | manager-web Service Worker 缓存旧 API/资源 | 中/中 | 保留 scope、版本化资源、升级 E2E | 新旧前端混用造成不可恢复错误 | Frontend |
+| R08 | OTA 双实现或公网 URL/端口切换破坏旧固件 | 中/高 | 完整/轻量 profile、兼容别名、OTA 差分 | 需要升级固件才能连接 | Architecture + QA |
+| R09 | 本地模型文件、FFmpeg、libopus 和写目录未正确打包 | 高/中 | 显式卷、非 root 权限、profile 构建测试 | 干净容器无法启动选定能力 | Platform |
+| R10 | Mock 掩盖真实供应商流式和错误行为 | 高/高 | Fake 只证明契约；M8 真实矩阵单独验收 | 需要凭证才能决定公共设计 | QA + External QA |
+| R11 | MQTT/UDP gateway、RAGFlow 等外部项目版本漂移 | 中/高 | 固定支持版本、录制契约、真实交接清单 | 外部接口文档与实际不一致 | Integration |
+| R12 | 上游 `main` 持续变化导致长分支难以合并 | 高/中 | 小 PR、每次合并后变基、每阶段重跑调用方清单 | 冲突改变公共契约 | PM/集成 |
+| R13 | PR 并行过多造成重复实现和冲突 | 中/中 | 最多三个实现工作包、文件所有权、唯一负责人 | 两个 PR 修改同一协议核心 | PM/集成 |
+| R14 | 现有未跟踪 FastAPI 基线没有进入远端 | 高/高 | P00 优先提交并建立 PR | 后续 Agent 无稳定基线 | PM/集成 |
+
+## 风险处理规则
+
+- P0：立即停止受影响工作包，PM 和架构负责人决策。
+- P1：不得合并相关 PR，必须有修复或明确的外部阻塞证据。
+- P2：可以带风险进入后续阶段，但必须有 Owner、验证计划和截止阶段。
+- 外部阻塞：只有满足 [真实环境测试交接](real-environment-handoff.md) 的定义才能标记，不能把内部未完成项转嫁给真实测试。
+
+每个里程碑收口时重新评估概率、影响和 Owner；关闭风险必须附测试、PR 或决策记录链接。

docs/unified-fastapi-platform/roadmap.md

@@ -0,0 +1,90 @@
+# 阶段路线图与 PR 队列
+
+## 1. 里程碑
+
+| 阶段 | 目标 | 主要交付物 | 负责人角色 | 依赖 | 退出门禁 |
+| --- | --- | --- | --- | --- | --- |
+| M0 基线 | 建立可审阅的 FastAPI 与计划基线 | 当前实现、兼容报告、计划文档、首个 PR | PM/集成 | 无 | 基线测试可重复，变更范围清楚 |
+| M1 可执行契约 | 把“现有功能”转换成测试资产 | 协议清单、黄金报文、虚拟设备、Fake Provider | QA + Realtime | M0 | 旧服务完整模拟会话可重复 |
+| M2 统一发行入口 | 纳入 manager-web 与统一网关 | 前端构建、静态托管、路由、统一 Compose | Platform + Frontend | M0 | 页面/API/WS 路由冒烟通过 |
+| M3 共享核心 | 消除配置和业务能力的内部 HTTP 自调用 | bootstrap、应用服务接口、配置版本与广播 | Backend + Architecture | M1 | API/旧 realtime 均可使用共享接口 |
+| M4 ASGI 实时内核 | 建立不依赖真实 Provider 的新会话运行时 | WebSocket 适配、DeviceSession、背压、取消和鉴权 | Realtime | M1、M3 | Fake 全会话与旧协议一致 |
+| M5 Provider 迁移 | 接回全部现有能力 | 四个 Provider 能力族适配、契约测试 | Provider 专项 | M4 | 所有 Provider 可构造且契约通过 |
+| M6 平台硬化 | 达到可部署候选质量 | 多进程、优雅摘流、指标、安全、负载和故障测试 | Platform + QA | M2、M4、M5 | 自动质量门禁全部绿色 |
+| M7 切换准备 | 删除自动化范围内的未知项 | 新旧差分、升级/回滚演练、旧入口弃用方案 | PM + Reviewer | M6 | 只剩真实环境清单中的阻塞项 |
+| M8 真实验收 | 外部人员/环境介入 | ESP32、真实 Provider、MQTT/RAGFlow、目标环境报告 | External QA/Ops | M7 | 不属于纯 Agent 阶段 |
+
+## 2. 推荐 PR 队列
+
+PR 必须按可独立验证的纵向能力拆分。编号是计划标识，不是 GitHub 实际编号。
+
+| 计划 PR | 内容 | 建议目标分支 | 可并行关系 |
+| --- | --- | --- | --- |
+| P00 | 开发计划、Agent 协作和质量门禁 | `refactor/unified-fastapi-platform` | FastAPI 基线直接推送后创建 |
+| P01 | CI 快速门禁和测试目录重组 | `refactor/unified-fastapi-platform` | 与 P02 并行 |
+| P02 | manager-web 构建、gateway 路由和统一 Compose | 同上 | 与 P01 并行 |
+| P03 | 设备协议清单、黄金报文和虚拟设备 | 同上 | 与 P02 并行 |
+| P04 | 系统密钥 bootstrap、共享配置接口和版本事件 | P01 + P03 | 阻塞 P06 |
+| P05 | 聊天/设备配置等内部 HTTP 调用改为应用服务端口 | P04 | 可按用例拆成两个 PR |
+| P06 | ASGI WebSocket 握手、鉴权和协议适配层 | P03 + P04 | 与 P05 后半段并行 |
+| P07 | DeviceSession 生命周期、队列、取消和 Fake 对话链路 | P06 | 阻塞 Provider 迁移 |
+| P08-A | VAD/ASR Provider 适配 | P07 | 与 P08-B/C 并行 |
+| P08-B | LLM/VLLM/Memory/Intent 适配 | P07 | 与 P08-A/C 并行 |
+| P08-C | TTS Provider 适配 | P07 | 与 P08-A/B 并行 |
+| P09 | Tools/MCP/IoT/插件及 Vision | P08-B | 可与 P08 收尾并行 |
+| P10 | 配置广播、管理控制、优雅摘流与健康指标 | P07 + P08 | 与 P09 并行 |
+| P11 | 全栈模拟 E2E、新旧差分和负载/故障测试 | P02 + P09 + P10 | 集成收口 |
+| P12 | 发行、升级、回滚、弃用和真实测试交接 | P11 | 纯 Agent 最后一个 PR |
+
+所有开发 PR 默认以长期集成分支 `refactor/unified-fastapi-platform` 为目标。存在未合并依赖时使用
+堆叠 PR；依赖合并后及时变基到最新集成分支。纯 Agent 阶段不向 `main` 创建 PR；真实环境验收
+完成后，也只有在项目所有者明确批准时才讨论主分支集成。不得让多个 PR 同时修改同一协议核心文件。
+
+## 3. 建议容量分配
+
+以下比例用于分配 Agent 和审阅资源，不是完成度承诺：
+
+| 工作域 | 参考占比 | 原因 |
+| --- | ---: | --- |
+| manager-web 与 gateway | 15% | 构建已可用，主要缺静态交付和浏览器 E2E |
+| manager-api 深度兼容与共享服务 | 25% | 路由齐全，但成功写入、副作用和 bootstrap 仍需补强 |
+| realtime、会话与 Provider | 45% | 缺少协议测试，且存在线程、模型和长连接重构 |
+| CI、部署、安全与交接 | 15% | 需要从零建立 PR 门禁和统一发行证据 |
+
+容量应随风险登记和测试证据调整，不按代码行数机械分配。
+
+## 4. 并行执行窗口
+
+为控制资源和冲突，同一时间最多开放三个实现工作包：
+
+1. 一个核心依赖链工作包，例如 P04/P06/P07。
+2. 一个交付或前端工作包，例如 P02/P10。
+3. 一个测试/独立审阅工作包，例如 P03/P11。
+
+Provider 阶段允许三个能力族并行，但每个能力族只分配一个实现 Agent；共享接口由架构负责人
+预先冻结，任何接口变更先更新 ADR 和契约测试。
+
+## 5. 阶段状态规则
+
+每个阶段只有四种状态：
+
+- `Not started`：依赖未完成。
+- `Ready`：依赖完成且工作包说明已批准。
+- `In progress`：已有唯一负责人和活动 PR。
+- `Done`：PR 合并且退出门禁有证据链接。
+
+不得使用“代码写完”代替 `Done`。失败、跳过、未执行和缺少外部环境必须分别记录。
+
+## 6. 每周/每轮进度摘要
+
+```text
+当前阶段：
+已合并 PR：
+活动 PR（负责人 / 门禁）：
+本轮新增证据：
+阻塞项（内部 / 真实环境）：
+风险变化：
+下一轮最多三个工作包：
+```
+
+路线图由 PM/集成负责人维护；实现 Agent 只更新自己 PR 的证据和工作包状态。

docs/web-search-integration.md

@@ -0,0 +1,71 @@
+# 联网搜索插件使用指南
+
+## 功能简介
+
+联网搜索插件 `web_search` 支持在对话过程中实时联网搜索信息并返回结果。插件支持两个搜索源：秘塔（Metaso）和Tavily，用户可根据需要选择其中一个。
+
+## API Key申请指南
+
+目前我们适配了`秘塔搜索`和`Tavily搜索`。
+- Tavily搜索：每个月1000次免费额度。
+- 秘塔搜索：拥有较为优质的国内数据源。
+
+## API Key申请指南
+
+### 方式一：使用秘塔搜索
+
+- 访问 [秘塔搜索API](https://metaso.cn/search-api/api-keys)，注册并登录账号
+- 在API密钥管理页面，点击"创建新的Key"
+- 复制生成的API Key（以 `mk-` 为前缀），这是配置所需的关键信息
+
+### 方式二：使用Tavily搜索
+
+- 访问 [Tavily控制台](https://app.tavily.com/home)，注册并登录账号
+- 在控制台中创建API Key
+- 复制生成的API Key（以 `tvly-` 为前缀），这是配置所需的关键信息
+
+## 配置方式
+
+### 方式1. 使用智控台部署（推荐）
+
+- 登录智控台
+- 进入"配置角色"页面，选择要配置的智能体
+- 点击"编辑功能"按钮，在右侧参数配置区域找到"联网搜索"插件
+- 勾选"联网搜索"
+- 填入搜索源（`metaso`或`tavily`），并将对应的`API Key`填入配置项
+- 保存配置，再保存智能体配置
+
+### 方式2. 单模块xiaozhi-server部署
+
+在 `data/.config.yaml` 中配置：
+
+- 将搜索源填入 `provider`，可选值为 `metaso` 或 `tavily`
+- 将申请到的API Key填入 `api_key`
+
+```yaml
+plugins:
+  web_search:
+    provider: "metaso"
+    api_key: "你的API Key"
+```
+
+如需自定义返回结果数量和工具描述，可额外配置 `max_results` 和 `description`：
+
+```yaml
+plugins:
+  web_search:
+    provider: "metaso"
+    description: "联网搜索工具。当用户明确需要联网搜索问题时使用此工具。"
+    max_results: 5
+    api_key: "你的API Key"
+```
+
+同时在 `functions` 列表中确保已启用 `web_search`：
+
+```yaml
+plugins:
+  functions:
+    - web_search
+```
+
+配置完成后重启服务即可生效。

main/README.md

@@ -9,6 +9,7 @@
     *   [3.2. `manager-api` (管理后端 - Java Spring Boot实现)](#32-manager-api-管理后端---java-spring-boot实现)
     *   [3.3. `manager-web` (Web管理前端 - Vue.js实现)](#33-manager-web-web管理前端---vuejs实现)
     *   [3.4. `manager-mobile` (移动管理端 - uni-app+Vue3实现)](#34-manager-mobile-移动管理端---uni-appvue3实现)
+    *   [3.5. `digital-human` (数字人测试模块 - Python+Web实现)](#35-digital-human-数字人测试模块---pythonweb实现)
 4.  [数据流与交互机制](#4-数据流与交互机制)
 5.  [核心功能概要](#5-核心功能概要)
 6.  [部署与配置概述](#6-部署与配置概述)
@@ -67,6 +68,13 @@
     *   基于alova + @alova/adapter-uniapp实现网络请求，与manager-api无缝集成。
     *   使用pinia进行状态管理，确保数据一致性。
 
+6.  **`digital-human` (数字人测试模块 - Python+Web实现):**
+    这是一个独立的数字人测试模块，提供本地测试页面、前端交互资源、唤醒词运行时与事件桥能力，用于联调整个数字人交互链路。其主要能力包括：
+    *   提供浏览器端的数字人测试页面，用于验证音频播放、接收和交互流程。
+    *   集成本地唤醒词运行时，支持基于Sherpa-ONNX的关键词检测。
+    *   通过事件桥将页面状态与本地运行时打通，便于调试唤醒词触发与交互效果。
+    *   作为独立模块与`xiaozhi-server`、`manager-web`、`manager-api`并列，便于单独开发和部署。
+
 **高层交互流程概述:**
 
 *   **语音交互主线:** **ESP32设备**捕捉到用户语音后，通过**WebSocket**将音频数据实时传输给**`xiaozhi-server`**。`xiaozhi-server`完成一系列AI处理（VAD、ASR、LLM交互、TTS）后，再通过WebSocket将合成的语音回复发送回ESP32设备进行播放。所有与语音直接相关的实时交互均在此链路完成。
@@ -80,7 +88,8 @@ xiaozhi-esp32-server
   ├─ xiaozhi-server 8000 端口 Python语言开发 负责与esp32通信
   ├─ manager-web 8001 端口 Node.js+Vue开发 负责提供控制台的web界面
   ├─ manager-api 8002 端口 Java语言开发 负责提供控制台的api
-  └─ manager-mobile 跨平台移动应用 uni-app+Vue3开发 负责提供移动版智控台管理
+  ├─ manager-mobile 跨平台移动应用 uni-app+Vue3开发 负责提供移动版智控台管理
+  └─ digital-human 数字人测试模块 Python+Web实现 负责本地测试页面、唤醒词运行时与事件桥
 ```
 
 ---
@@ -366,6 +375,48 @@ xiaozhi-esp32-server
 
 ---
 
+### 3.5. `digital-human` (数字人测试模块 - Python+Web实现)
+
+`digital-human` 组件是一个独立的数字人测试模块，负责提供本地测试页面、页面资源、唤醒词运行时和事件桥能力。它主要用于联调整个数字人交互链路，帮助开发者验证页面交互、音频能力和本地唤醒词流程。
+
+*   **核心目标:**
+    *   提供独立的本地测试页面，用于验证数字人交互效果。
+    *   提供本地唤醒词运行时，支持关键词检测与事件上报。
+    *   为前端页面和本地运行时提供事件桥，打通测试链路。
+    *   以独立模块形式存在，便于单独开发、调试和部署。
+
+*   **核心技术栈:**
+    *   **Python 3:** 作为测试运行时的主要语言，负责启动本地服务、管理唤醒词运行时和事件桥。
+    *   **原生HTML/CSS/JavaScript:** 用于构建数字人测试页面与交互逻辑。
+    *   **Sherpa-ONNX:** 用于本地唤醒词检测。
+    *   **ThreadingHTTPServer / WebSocket桥接:** 用于承载测试页面、健康检查和本地事件通信。
+
+*   **关键实现细节:**
+
+    1.  **模块入口与页面资源:**
+        *   `start.py` 是模块启动入口，负责初始化测试运行时。
+        *   `index.html` 是数字人测试页面入口。
+        *   `js/`、`css/`、`images/`、`resources/` 目录提供页面脚本、样式和资源文件。
+
+    2.  **本地测试运行时:**
+        *   `wakeword_runtime/` 目录承载本地唤醒词运行时实现。
+        *   运行时负责配置加载、日志初始化、音频采集、关键词检测和服务生命周期管理。
+        *   模块默认通过本地HTTP服务暴露页面地址、事件桥地址和健康检查接口。
+
+    3.  **唤醒词检测链路:**
+        *   基于Sherpa-ONNX关键词检测模型，支持本地唤醒词触发。
+        *   模型文件和关键词配置位于 `wakeword_runtime/models/` 及相应配置文件中。
+        *   页面侧可结合事件桥观察唤醒词服务状态和触发结果。
+
+    4.  **调试与联调定位:**
+        *   启动后可通过浏览器访问本地页面，验证音频播放、接收和交互逻辑。
+        *   通过事件桥可以将唤醒词状态同步到页面，便于排查本地链路问题。
+        *   详细的模型下载、运行时配置和使用说明已整理在 `docs/digital-human-wakeword.md` 中。
+
+`digital-human` 的存在使得数字人相关能力可以脱离主服务独立验证，降低了页面调试、唤醒词联调和本地环境搭建的复杂度。
+
+---
+
 ## 4. 数据流与交互机制
 
 `xiaozhi-esp32-server` 系统通过各组件间定义清晰的数据流和交互协议来协同工作。主要的通信方式依赖于针对实时交互优化的WebSocket协议和适用于客户端-服务器请求的RESTful API。

main/README_en.md

@@ -9,6 +9,7 @@
     *   [3.2. `manager-api` (Management Backend - Java Spring Boot Implementation)](#32-manager-api-management-backend---java-spring-boot-implementation)
     *   [3.3. `manager-web` (Web Management Frontend - Vue.js Implementation)](#33-manager-web-web-management-frontend---vuejs-implementation)
     *   [3.4. `manager-mobile` (Mobile Management Console - uni-app Implementation)](#34-manager-mobile-mobile-management-console---uniapp-implementation)
+    *   [3.5. `digital-human` (Digital Human Test Module - Python+Web Implementation)](#35-digital-human-digital-human-test-module---pythonweb-implementation)
 4.  [Data Flow and Interaction Mechanisms](#4-data-flow-and-interaction-mechanisms)
 5.  [Key Features Summary](#5-key-features-summary)
 6.  [Deployment and Configuration Overview](#6-deployment-and-configuration-overview)
@@ -60,6 +61,21 @@ The `xiaozhi-esp32-server` system adopts a **distributed, multi-component collab
     *   (Potential functionality) Monitoring system operation status, viewing logs, troubleshooting, etc.
     *   Comprehensive interaction with all backend management functions provided by `manager-api`.
 
+5.  **`manager-mobile` (Mobile Management Console - uni-app Implementation):**
+    This is a cross-platform mobile management application based on uni-app v3 + Vue 3 + Vite, supporting App (Android & iOS) and WeChat Mini Program. Its main capabilities include:
+    *   Providing a convenient management interface on mobile devices, similar in functionality to manager-web but optimized for mobile platforms.
+    *   Supporting core functions such as user login, device management, and AI service configuration.
+    *   Cross-platform adaptation, allowing a single codebase to run on iOS, Android, and WeChat Mini Programs.
+    *   Integrating with `manager-api` through alova + `@alova/adapter-uniapp`.
+    *   Using pinia for state management to ensure data consistency.
+
+6.  **`digital-human` (Digital Human Test Module - Python+Web Implementation):**
+    This is an independent digital human test module that provides a local test page, frontend interaction resources, a wake word runtime, and an event bridge for end-to-end debugging of the digital human interaction flow. Its main capabilities include:
+    *   Providing a browser-based digital human test page for validating audio playback, audio reception, and interaction flow.
+    *   Integrating a local wake word runtime with keyword detection based on Sherpa-ONNX.
+    *   Bridging page state and the local runtime through an event bridge to simplify wake word debugging.
+    *   Existing as a standalone module alongside `xiaozhi-server`, `manager-web`, and `manager-api`, making independent development and deployment easier.
+
 **High-Level Interaction Flow Overview:**
 
 *   **Voice Interaction Main Line:** After the **ESP32 device** captures user voice, it transmits audio data in real-time to **`xiaozhi-server`** through **WebSocket**. After `xiaozhi-server` completes a series of AI processing (VAD, ASR, LLM interaction, TTS), it sends the synthesized voice response back to the ESP32 device for playback through WebSocket. All real-time interactions directly related to voice are completed in this link.
@@ -73,7 +89,8 @@ xiaozhi-esp32-server
   ├─ xiaozhi-server Port 8000 Python development Responsible for ESP32 communication
   ├─ manager-web Port 8001 Node.js+Vue development Responsible for providing web interface for console
   ├─ manager-api Port 8002 Java development Responsible for providing console API
-  └─ manager-mobile Cross-platform mobile application uni-app+Vue3 development Responsible for providing mobile console management
+  ├─ manager-mobile Cross-platform mobile application uni-app+Vue3 development Responsible for providing mobile console management
+  └─ digital-human Digital human test module Python+Web implementation Responsible for local test page, wake word runtime, and event bridge
 ```
 
 ---
@@ -257,6 +274,46 @@ The `manager-mobile` component is a cross-platform mobile management application
 
 `manager-mobile` provides users with a fully functional, smooth mobile management tool through the application of these technologies, allowing administrators to perform system management and configuration anytime, anywhere.
 
+### 3.5. `digital-human` (Digital Human Test Module - Python+Web Implementation)
+
+The `digital-human` component is an independent digital human test module responsible for providing a local test page, page resources, a wake word runtime, and an event bridge. It is primarily used to debug the complete digital human interaction flow and to validate frontend interaction, audio capability, and local wake word behavior.
+
+*   **Core Objectives:**
+    *   Provide an independent local test page for validating digital human interaction effects.
+    *   Provide a local wake word runtime for keyword detection and event reporting.
+    *   Provide an event bridge between the frontend page and the local runtime to connect the test flow.
+    *   Exist as a standalone module for easier independent development, debugging, and deployment.
+
+*   **Core Technologies:**
+    *   **Python 3:** Used for the local test runtime, service startup, wake word lifecycle management, and event bridge coordination.
+    *   **Native HTML/CSS/JavaScript:** Used to build the digital human test page and interaction logic.
+    *   **Sherpa-ONNX:** Used for local wake word keyword detection.
+    *   **ThreadingHTTPServer / WebSocket bridge:** Used to serve the local page, health check endpoint, and event communication.
+
+*   **Key Implementation Aspects:**
+
+    1.  **Module Entry and Page Resources:**
+        *   `start.py` is the module entry point responsible for starting the local test runtime.
+        *   `index.html` is the entry page for digital human testing.
+        *   The `js/`, `css/`, `images/`, and `resources/` directories provide frontend scripts, styles, and static resources.
+
+    2.  **Local Test Runtime:**
+        *   The `wakeword_runtime/` directory contains the local wake word runtime implementation.
+        *   The runtime is responsible for configuration loading, logging initialization, audio capture, keyword detection, and lifecycle management.
+        *   The module exposes a local page URL, event bridge URL, and health check endpoint through a local HTTP service.
+
+    3.  **Wake Word Detection Flow:**
+        *   Uses Sherpa-ONNX keyword detection models to support local wake word triggering.
+        *   Model files and keyword configurations are stored in `wakeword_runtime/models/` and related configuration files.
+        *   The page can observe runtime state and trigger results through the event bridge.
+
+    4.  **Debugging and Integration Positioning:**
+        *   After startup, developers can open the local page in a browser to validate playback, reception, and interaction logic.
+        *   The event bridge synchronizes wake word state to the page, which helps with local debugging.
+        *   Detailed model download, runtime configuration, and usage instructions are documented in `docs/digital-human-wakeword.md`.
+
+The `digital-human` module allows digital human related capabilities to be validated independently from the main service, reducing the complexity of page debugging, wake word integration, and local environment setup.
+
 ---
 
 ## 4. Data Flow and Interaction Mechanisms

main/digital-human/README.md

@@ -0,0 +1,46 @@
+本文档是开发类文档，如需部署小智服务端，[点击这里查看部署教程](../../README.md#%E9%83%A8%E7%BD%B2%E6%96%87%E6%A1%A3)
+
+如需查看一体机数字人落地部署、Kiosk 全屏启动和系统环境配置，[点击这里查看一体机部署指南](../../docs/all-in-one-digital-human-setup.md)
+
+如需查看唤醒词模型下载、运行时配置和详细使用说明，[点击这里查看唤醒词专题文档](../../docs/digital-human-wakeword.md)
+
+# 项目介绍
+
+digital-human 是独立的数字人测试模块，负责提供本地测试页面、前端交互资源、唤醒词运行时和事件桥能力，用于联调整个数字人交互链路。
+
+# 快速启动
+
+安装依赖：
+
+```bash
+pip install -r wakeword_runtime/requirements.txt
+```
+
+启动模块：
+
+```bash
+python start.py
+```
+
+# 访问地址
+
+启动后可访问：
+
+- 页面地址：http://127.0.0.1:8006/index.html
+- 事件桥地址：ws://127.0.0.1:8006/wakeword-ws
+- 健康检查：http://127.0.0.1:8006/health
+
+# 目录说明
+
+- `start.py`：模块启动入口
+- `index.html`：数字人测试页面入口
+- `wakeword_runtime`：本地唤醒词运行时与配置目录
+- `js`、`css`：页面前端脚本与样式
+- `images`、`resources`：页面资源文件
+
+# 相关文档
+
+- 一体机部署指南：适用于 x86 设备整机落地部署、Kiosk 展示和开机自启动配置
+	[../../docs/all-in-one-digital-human-setup.md](../../docs/all-in-one-digital-human-setup.md)
+- 唤醒词专题文档：适用于唤醒词模型下载、运行时配置和本地调试说明
+	[../../docs/digital-human-wakeword.md](../../docs/digital-human-wakeword.md)

main/digital-human/css/index.css

@@ -812,6 +812,20 @@ body {
     font-size: 14px;
 }
 
+.config-item textarea {
+    width: 100%;
+    padding: 12px;
+    border: 1px solid #40444b;
+    border-radius: 6px;
+    background: #40444b;
+    color: white;
+    min-height: 100px;
+    resize: vertical;
+    box-sizing: border-box;
+    font-family: inherit;
+    font-size: 14px;
+}
+
 .model-select {
     width: 100%;
     padding: 10px 40px 10px 14px;

main/digital-human/index.html

@@ -4,8 +4,8 @@
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>小智服务器测试页面</title>
+    <title>小智数字人页面</title>
-    <link rel="stylesheet" href="css/test_page.css?v=0205">
+    <link rel="stylesheet" href="css/index.css?v=0206">
     <script>
         // 检测是否使用file://协议打开
         if (window.location.protocol === 'file:') {
@@ -21,14 +21,14 @@
                 warningDiv.innerHTML = `
                     <h2>⚠️ 警告：请使用HTTP服务器打开此页面</h2>
                     <p>您当前使用的是本地文件方式打开页面（file://协议），这可能导致页面功能异常。</p>
-                    <p>您可以使用nginx映射启动测试页面，也可以请按照以下步骤使用python启动测试http服务：</p>
+                    <p>您可以使用nginx映射启动小智数字人页面，也可以请按照以下步骤启动测试运行时：</p>
                     <ol>
                         <li>打开命令行终端</li>
-                        <li>命令行进入到 xiaozhi-server/test 目录</li>
+                        <li>命令行进入到 digital-human 目录</li>
-                        <li>执行以下命令启动HTTP服务器：</li>
+                        <li>执行以下命令启动小智数字人页面运行时：</li>
                     </ol>
-                    <pre>python -m http.server 8006</pre>
+                    <pre>python start.py</pre>
-                    <p>然后在浏览器中访问：<strong>http://localhost:8006/test_page.html</strong></p>
+                    <p>然后在浏览器中访问：<strong>http://localhost:8006/index.html</strong></p>
                 `;
                 document.body.appendChild(warningDiv);
             });
@@ -137,6 +137,7 @@
             <div class="modal-body">
                 <div class="settings-tabs">
                     <button class="tab-btn active" data-tab="device">设备配置</button>
+                    <button class="tab-btn" data-tab="wakeword">唤醒词</button>
                     <button class="tab-btn" data-tab="mcp">MCP工具</button>
                     <button class="tab-btn" data-tab="other">数字人皮肤</button>
                 </div>
@@ -162,6 +163,15 @@
                                         placeholder="deviceName">
                                 </div>
                             </div>
+                            <div class="config-row">
+                                <div class="config-item">
+                                    <label for="emojiEnabled">情绪表情:</label>
+                                    <select id="emojiEnabled" class="model-select">
+                                        <option value="true">启用</option>
+                                        <option value="false" selected>禁用</option>
+                                    </select>
+                                </div>
+                            </div>
                         </div>
                     </div>
 
@@ -184,6 +194,37 @@
                     </div>
                 </div>
 
+                <div class="tab-content" id="wakewordTab">
+                    <div class="config-panel">
+                        <div class="control-panel">
+                            <div class="config-row">
+                                <div class="config-item">
+                                    <label for="wakewordEnabled">启用本地唤醒词:</label>
+                                    <select id="wakewordEnabled" class="model-select">
+                                        <option value="true">启用</option>
+                                        <option value="false">禁用</option>
+                                    </select>
+                                </div>
+                            </div>
+                            <div class="config-row">
+                                <div class="config-item">
+                                    <label for="wakewordWsUrl">唤醒词服务地址:</label>
+                                    <input type="text" id="wakewordWsUrl" placeholder="ws://127.0.0.1:8006/wakeword-ws">
+                                </div>
+                            </div>
+                            <div class="config-row">
+                                <div class="config-item">
+                                    <label for="wakewordList">唤醒词配置 (一行一个):</label>
+                                    <textarea id="wakewordList" placeholder="例如：&#10;小智小智&#10;你好小智"></textarea>
+                                </div>
+                            </div>
+                            <div class="modal-actions">
+                                <button type="button" class="btn-primary" id="applyWakewordBtn">应用唤醒词</button>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+
                 <div class="tab-content" id="mcpTab">
                     <!-- MCP 工具管理区域 -->
                     <div class="mcp-tools-container">

main/digital-human/js/app.js

@@ -3,6 +3,7 @@ import { checkOpusLoaded, initOpusEncoder } from './core/audio/opus-codec.js?v=0
 import { getAudioPlayer } from './core/audio/player.js?v=0205';
 import { checkMicrophoneAvailability, isHttpNonLocalhost } from './core/audio/recorder.js?v=0205';
 import { initMcpTools } from './core/mcp/tools.js?v=0205';
+import { startWakewordBridgeListener } from './core/network/wakeword-bridge.js?v=0205';
 import { uiController } from './ui/controller.js?v=0205';
 import { log } from './utils/logger.js?v=0205';
 
@@ -43,6 +44,8 @@ class App {
         await this.audioPlayer.start();
         // 初始化MCP工具
         initMcpTools();
+        // 初始化本地唤醒事件监听
+        startWakewordBridgeListener();
         // 检查麦克风可用性
         await this.checkMicrophoneAvailability();
         // 检查摄像头可用性
@@ -192,7 +195,7 @@ class App {
                     }
                     log('正在请求摄像头权限...', 'info');
                     this.cameraStream = await navigator.mediaDevices.getUserMedia({
-                        video: { width: 320, height: 240, facingMode: this.currentFacingMode },
+                        video: { width: 180, height: 240, facingMode: this.currentFacingMode },
                         audio: false
                     });
                     cameraVideo.srcObject = this.cameraStream;
@@ -274,7 +277,7 @@ class App {
                         return;
                     }
 
-                    canvas.width = video.videoWidth || 320;
+                    canvas.width = video.videoWidth || 180;
                     canvas.height = video.videoHeight || 240;
                     const ctx = canvas.getContext('2d');
                     ctx.drawImage(video, 0, 0, canvas.width, canvas.height);

main/digital-human/js/config/manager.js

@@ -1,5 +1,8 @@
 // 配置管理模块
 
+// 默认唤醒词列表
+export const DEFAULT_WAKE_WORDS = '你好小智\n你好小志\n小爱同学\n你好小鑫\n你好小新\n小美同学\n小龙小龙\n喵喵同学\n小滨小滨\n小冰小冰\n嘿你好呀';
+
 // 生成随机MAC地址
 function generateRandomMac() {
     const hexDigits = '0123456789ABCDEF';
@@ -19,6 +22,9 @@ export function loadConfig() {
     const deviceNameInput = document.getElementById('deviceName');
     const clientIdInput = document.getElementById('clientId');
     const otaUrlInput = document.getElementById('otaUrl');
+    const wakewordWsUrlInput = document.getElementById('wakewordWsUrl');
+    const wakewordEnabledInput = document.getElementById('wakewordEnabled');
+    const wakewordListInput = document.getElementById('wakewordList');
 
     // 从localStorage加载MAC地址，如果没有则生成新的
     let savedMac = localStorage.getItem('xz_tester_deviceMac');
@@ -43,6 +49,29 @@ export function loadConfig() {
     if (savedOtaUrl) {
         otaUrlInput.value = savedOtaUrl;
     }
+
+    const savedWakewordWsUrl = localStorage.getItem('xz_tester_wakewordWsUrl');
+    if (savedWakewordWsUrl !== null && wakewordWsUrlInput) {
+        wakewordWsUrlInput.value = savedWakewordWsUrl;
+    }
+
+    const savedWakewordEnabled = localStorage.getItem('xz_tester_wakewordEnabled');
+    if (savedWakewordEnabled !== null && wakewordEnabledInput) {
+        wakewordEnabledInput.value = savedWakewordEnabled;
+    }
+
+    const savedWakewordList = localStorage.getItem('xz_tester_wakewordList');
+    if (savedWakewordList !== null && wakewordListInput) {
+        wakewordListInput.value = savedWakewordList;
+    } else if (wakewordListInput) {
+        wakewordListInput.value = DEFAULT_WAKE_WORDS;
+    }
+
+    const emojiEnabledInput = document.getElementById('emojiEnabled');
+    const savedEmojiEnabled = localStorage.getItem('xz_tester_emojiEnabled');
+    if (savedEmojiEnabled !== null && emojiEnabledInput) {
+        emojiEnabledInput.value = savedEmojiEnabled;
+    }
 }
 
 // 保存配置
@@ -50,10 +79,26 @@ export function saveConfig() {
     const deviceMacInput = document.getElementById('deviceMac');
     const deviceNameInput = document.getElementById('deviceName');
     const clientIdInput = document.getElementById('clientId');
+    const wakewordWsUrlInput = document.getElementById('wakewordWsUrl');
+    const wakewordEnabledInput = document.getElementById('wakewordEnabled');
+    const wakewordListInput = document.getElementById('wakewordList');
 
     localStorage.setItem('xz_tester_deviceMac', deviceMacInput.value);
     localStorage.setItem('xz_tester_deviceName', deviceNameInput.value);
     localStorage.setItem('xz_tester_clientId', clientIdInput.value);
+    const emojiEnabledInput = document.getElementById('emojiEnabled');
+    if (emojiEnabledInput) {
+        localStorage.setItem('xz_tester_emojiEnabled', emojiEnabledInput.value);
+    }
+    if (wakewordEnabledInput) {
+        localStorage.setItem('xz_tester_wakewordEnabled', wakewordEnabledInput.value);
+    }
+    if (wakewordListInput) {
+        localStorage.setItem('xz_tester_wakewordList', wakewordListInput.value);
+    }
+    if (wakewordWsUrlInput && wakewordWsUrlInput.value.trim()) {
+        localStorage.setItem('xz_tester_wakewordWsUrl', wakewordWsUrlInput.value.trim());
+    }
 }
 
 // 获取配置值
@@ -62,12 +107,14 @@ export function getConfig() {
     const deviceMac = document.getElementById('deviceMac')?.value.trim() || '';
     const deviceName = document.getElementById('deviceName')?.value.trim() || '';
     const clientId = document.getElementById('clientId')?.value.trim() || '';
+    const emojiEnabled = document.getElementById('emojiEnabled')?.value !== 'false';
 
     return {
         deviceId: deviceMac,  // 使用MAC地址作为deviceId
         deviceName,
         deviceMac,
-        clientId
+        clientId,
+        emojiEnabled
     };
 }
 

main/digital-human/js/core/audio/recorder.js

@@ -203,17 +203,6 @@ export class AudioRecorder {
     async start() {
         if (this.isRecording) return false;
         try {
-            // Check if WebSocketHandler instance exists
-            const { getWebSocketHandler } = await import('../network/websocket.js?v=0205');
-            const wsHandler = getWebSocketHandler();
-            // If machine is speaking, send abort message
-            if (wsHandler && wsHandler.isRemoteSpeaking && wsHandler.currentSessionId) {
-                const abortMessage = { session_id: wsHandler.currentSessionId, type: 'abort', reason: 'wake_word_detected' };
-                if (this.websocket && this.websocket.readyState === WebSocket.OPEN) {
-                    this.websocket.send(JSON.stringify(abortMessage));
-                    log('已发送中止消息', 'info');
-                }
-            }
             if (!this.initEncoder()) {
                 log('无法开始录音: Opus编码器初始化失败', 'error');
                 return false;

main/digital-human/js/core/network/wakeword-bridge.js

@@ -0,0 +1,225 @@
+import { uiController } from '../../ui/controller.js?v=0205';
+import { log } from '../../utils/logger.js?v=0205';
+
+let wakewordSocket = null;
+let reconnectTimer = null;
+let reconnectAttempts = 0;
+let shouldReconnect = true;
+let wakewordRequestSeq = 0;
+let onNextBridgeConnectedCallback = null;
+
+const pendingWakewordRequests = new Map();
+
+export function startWakewordBridgeListener() {
+    if (wakewordSocket) {
+        return wakewordSocket;
+    }
+
+    shouldReconnect = true;
+    log('正在连接本地唤醒事件桥...', 'info');
+    tryConnect();
+    return wakewordSocket;
+}
+
+function tryConnect() {
+    const bridgeUrl = buildWakewordBridgeUrl();
+
+    try {
+        wakewordSocket = new WebSocket(bridgeUrl);
+        wakewordSocket.onopen = () => {
+            reconnectAttempts = 0;
+            log(`本地唤醒事件桥已连接: ${bridgeUrl}`, 'success');
+            // 连接成功后自动保存地址，刷新后仍能记住
+            localStorage.setItem('xz_tester_wakewordWsUrl', bridgeUrl);
+            const urlInput = document.getElementById('wakewordWsUrl');
+            if (urlInput) urlInput.value = bridgeUrl;
+        };
+
+        wakewordSocket.onerror = () => {
+            log(`本地唤醒事件桥连接失败: ${bridgeUrl}`, 'error');
+        };
+
+        wakewordSocket.onmessage = async (event) => {
+            try {
+                const message = parseWakewordBridgeMessage(event.data);
+                if (message.requestId && pendingWakewordRequests.has(message.requestId)) {
+                    settleWakewordRequest(message);
+                    return;
+                }
+
+                if (message.success === false) {
+                    log(`本地唤醒事件桥返回错误: ${message.error || '未知错误'}`, 'error');
+                    return;
+                }
+
+                if (message.type === 'bridge_connected') {
+                    log('本地唤醒监听已就绪', 'info');
+                    if (onNextBridgeConnectedCallback) {
+                        const cb = onNextBridgeConnectedCallback;
+                        onNextBridgeConnectedCallback = null;
+                        cb(message);
+                    }
+                    return;
+                }
+
+                if (message.type === 'service_ready') {
+                    log('本地唤醒服务已启动', 'info');
+                    return;
+                }
+
+                if (message.type === 'wakeword_config') {
+                    uiController.applyWakewordConfig(message.payload || {});
+                    log('已同步本地唤醒词配置', 'info');
+                    return;
+                }
+
+                if (message.type === 'service_stopping') {
+                    log('本地唤醒服务正在停止', 'warning');
+                    return;
+                }
+
+                if (message.type === 'wake_word_detected') {
+                    const wakeWord = message.payload?.wake_word || '唤醒词';
+                    log(`检测到本地唤醒事件: ${wakeWord}`, 'info');
+                    await uiController.triggerWakewordDial(wakeWord);
+                }
+            } catch (error) {
+                log(`解析本地唤醒事件失败: ${error.message}`, 'error');
+            }
+        };
+
+        wakewordSocket.onclose = () => {
+            if (wakewordSocket) {
+                wakewordSocket = null;
+            }
+
+            rejectAllWakewordRequests('本地唤醒事件桥已断开');
+
+            if (!shouldReconnect) {
+                return;
+            }
+
+            if (reconnectTimer) {
+                return;
+            }
+
+            reconnectAttempts += 1;
+            const delay = Math.min(1000 * reconnectAttempts, 5000);
+            log(`本地唤醒事件桥将在 ${delay}ms 后重连: ${bridgeUrl}`, 'warning');
+            reconnectTimer = window.setTimeout(() => {
+                reconnectTimer = null;
+                tryConnect();
+            }, delay);
+        };
+
+        return wakewordSocket;
+    } catch (error) {
+        log(`启动本地唤醒监听失败: ${error.message}`, 'error');
+        return null;
+    }
+}
+
+export function stopWakewordBridgeListener() {
+    shouldReconnect = false;
+
+    if (reconnectTimer) {
+        window.clearTimeout(reconnectTimer);
+        reconnectTimer = null;
+    }
+
+    if (!wakewordSocket) {
+        return;
+    }
+
+    wakewordSocket.onclose = null;
+    wakewordSocket.close();
+    wakewordSocket = null;
+}
+
+export function sendWakewordBridgeMessage(type, payload = {}, requestId = null) {
+    if (!wakewordSocket || wakewordSocket.readyState !== WebSocket.OPEN) {
+        log('本地唤醒事件桥未连接，无法发送消息', 'warning');
+        return false;
+    }
+
+    wakewordSocket.send(JSON.stringify({
+        type,
+        requestId,
+        payload,
+    }));
+    return true;
+}
+
+export function requestWakewordBridge(type, payload = {}, timeout = 5000) {
+    const requestId = `wakeword-${Date.now()}-${++wakewordRequestSeq}`;
+
+    return new Promise((resolve, reject) => {
+        const timer = window.setTimeout(() => {
+            pendingWakewordRequests.delete(requestId);
+            reject(new Error('本地唤醒服务响应超时'));
+        }, timeout);
+
+        pendingWakewordRequests.set(requestId, { resolve, reject, timer });
+
+        if (!sendWakewordBridgeMessage(type, payload, requestId)) {
+            window.clearTimeout(timer);
+            pendingWakewordRequests.delete(requestId);
+            reject(new Error('本地唤醒事件桥未连接'));
+        }
+    });
+}
+
+export function getWakewordBridgeUrl() {
+    if (wakewordSocket && wakewordSocket.url) {
+        return wakewordSocket.url;
+    }
+    return buildWakewordBridgeUrl();
+}
+
+export function onNextBridgeConnected(callback) {
+    onNextBridgeConnectedCallback = callback;
+}
+
+function buildWakewordBridgeUrl() {
+    const configured = localStorage.getItem('xz_tester_wakewordWsUrl');
+    if (configured && configured.trim()) {
+        return configured.trim();
+    }
+    return 'ws://127.0.0.1:8006/wakeword-ws';
+}
+
+function parseWakewordBridgeMessage(rawData) {
+    const message = JSON.parse(rawData);
+    return {
+        type: message.type || '',
+        requestId: message.requestId || null,
+        success: message.success !== false,
+        payload: message.payload || {},
+        error: message.error || null,
+    };
+}
+
+function settleWakewordRequest(message) {
+    const pendingRequest = pendingWakewordRequests.get(message.requestId);
+    if (!pendingRequest) {
+        return;
+    }
+
+    window.clearTimeout(pendingRequest.timer);
+    pendingWakewordRequests.delete(message.requestId);
+
+    if (message.success === false) {
+        pendingRequest.reject(new Error(message.error || '本地唤醒服务返回失败'));
+        return;
+    }
+
+    pendingRequest.resolve(message);
+}
+
+function rejectAllWakewordRequests(errorMessage) {
+    pendingWakewordRequests.forEach((pendingRequest) => {
+        window.clearTimeout(pendingRequest.timer);
+        pendingRequest.reject(new Error(errorMessage));
+    });
+    pendingWakewordRequests.clear();
+}

main/digital-human/js/core/network/websocket.js

@@ -34,7 +34,8 @@ export class WebSocketHandler {
                 device_mac: config.deviceMac,
                 token: config.token,
                 features: {
-                    mcp: true
+                    mcp: true,
+                    emoji: config.emojiEnabled
                 }
             };
 
@@ -70,6 +71,28 @@ export class WebSocketHandler {
         }
     }
 
+    _sendWakeupMessages(sessionId) {
+        if (!this.websocket || this.websocket.readyState !== WebSocket.OPEN) return;
+
+        // listen detect
+        this.websocket.send(JSON.stringify({
+            session_id: sessionId,
+            type: 'listen',
+            state: 'detect',
+            text: '嘿，你好呀'
+        }));
+        log('发送listen detect消息，唤醒词: 嘿，你好呀', 'info');
+
+        // listen start：开始监听
+        this.websocket.send(JSON.stringify({
+            session_id: sessionId,
+            type: 'listen',
+            state: 'start',
+            mode: 'auto'
+        }));
+        log('发送listen start消息', 'info');
+    }
+
     // 处理文本消息
     handleTextMessage(message) {
         if (message.type === 'hello') {
@@ -77,6 +100,9 @@ export class WebSocketHandler {
             window.cameraAvailable = true;
             log('连接成功，摄像头已可用', 'success');
             uiController.updateDialButton(true);
+
+            this._sendWakeupMessages(message.session_id);
+
             uiController.startAIChatSession();
         } else if (message.type === 'tts') {
             this.handleTTSMessage(message);

main/digital-human/js/ui/controller.js

@@ -2,7 +2,9 @@
 import { loadConfig, saveConfig } from '../config/manager.js?v=0205';
 import { getAudioPlayer } from '../core/audio/player.js?v=0205';
 import { getAudioRecorder } from '../core/audio/recorder.js?v=0205';
+import { requestWakewordBridge, stopWakewordBridgeListener, startWakewordBridgeListener, getWakewordBridgeUrl, onNextBridgeConnected } from '../core/network/wakeword-bridge.js?v=0205';
 import { getWebSocketHandler } from '../core/network/websocket.js?v=0205';
+import { log } from '../utils/logger.js?v=0205';
 
 // UI controller class
 class UIController {
@@ -14,6 +16,8 @@ class UIController {
         this.currentBackgroundIndex = localStorage.getItem('backgroundIndex') ? parseInt(localStorage.getItem('backgroundIndex')) : 0;
         this.backgroundImages = ['1.png', '2.png', '3.png'];
         this.dialBtnDisabled = false;
+        this.isConnecting = false;
+        this.lastWakewordDialTime = 0;
 
         // Bind methods
         this.init = this.init.bind(this);
@@ -25,6 +29,9 @@ class UIController {
         this.showModal = this.showModal.bind(this);
         this.hideModal = this.hideModal.bind(this);
         this.switchTab = this.switchTab.bind(this);
+        this.applyWakewordConfig = this.applyWakewordConfig.bind(this);
+        this.handleApplyWakeword = this.handleApplyWakeword.bind(this);
+        this.triggerWakewordDial = this.triggerWakewordDial.bind(this);
     }
 
     // Initialize
@@ -262,6 +269,11 @@ class UIController {
             });
         });
 
+        const applyWakewordBtn = document.getElementById('applyWakewordBtn');
+        if (applyWakewordBtn) {
+            applyWakewordBtn.addEventListener('click', this.handleApplyWakeword);
+        }
+
         // 点击模态框背景关闭（仅对特定模态框禁用此功能）
         const modals = document.querySelectorAll('.modal');
         modals.forEach(modal => {
@@ -512,6 +524,121 @@ class UIController {
         }
     }
 
+    applyWakewordConfig(config = {}) {
+        const wakewordEnabledInput = document.getElementById('wakewordEnabled');
+        const wakewordListInput = document.getElementById('wakewordList');
+
+        if (!wakewordEnabledInput || !wakewordListInput) {
+            return;
+        }
+
+        const wakeWords = Array.isArray(config.wakeWords)
+            ? config.wakeWords.filter(item => typeof item === 'string' && item.trim())
+            : [];
+
+        wakewordEnabledInput.value = config.enabled === false ? 'false' : 'true';
+        wakewordListInput.value = wakeWords.join('\n');
+        saveConfig();
+    }
+
+    async handleApplyWakeword() {
+        const wakewordEnabledInput = document.getElementById('wakewordEnabled');
+        const wakewordListInput = document.getElementById('wakewordList');
+        const wakewordWsUrlInput = document.getElementById('wakewordWsUrl');
+        if (!wakewordEnabledInput || !wakewordListInput) {
+            return;
+        }
+
+        const wakeWords = wakewordListInput.value
+            .split(/\r?\n/u)
+            .map(item => item.trim())
+            .filter(Boolean)
+            .filter((item, index, items) => items.indexOf(item) === index);
+
+        const payload = {
+            enabled: wakewordEnabledInput.value !== 'false',
+            wakeWords,
+        };
+
+        if (payload.enabled && payload.wakeWords.length === 0) {
+            this.addChatMessage('启用唤醒词时，至少需要填写一个唤醒词。', false);
+            return;
+        }
+
+        const applyWakewordBtn = document.getElementById('applyWakewordBtn');
+        if (applyWakewordBtn) {
+            applyWakewordBtn.disabled = true;
+            applyWakewordBtn.textContent = '应用中...';
+        }
+
+        try {
+            // 保存地址到 localStorage
+            if (wakewordWsUrlInput && wakewordWsUrlInput.value.trim()) {
+                localStorage.setItem('xz_tester_wakewordWsUrl', wakewordWsUrlInput.value.trim());
+            }
+
+            // 比较新地址和当前连接地址
+            const newWsUrl = localStorage.getItem('xz_tester_wakewordWsUrl');
+            const currentWsUrl = getWakewordBridgeUrl();
+            const urlChanged = newWsUrl !== currentWsUrl;
+
+            if (urlChanged) {
+                // 地址变了，先确认
+                const shouldRestart = window.confirm('地址已变更，是否继续？（将断开旧连接并重新连接）');
+                if (!shouldRestart) {
+                    // 恢复 localStorage 里的旧地址
+                    localStorage.setItem('xz_tester_wakewordWsUrl', currentWsUrl);
+                    this.addChatMessage('已取消地址变更。', false);
+                    return;
+                }
+
+                // 断开旧连接
+                stopWakewordBridgeListener();
+
+                // 启动新连接（自动用新地址）
+                startWakewordBridgeListener();
+
+                // 等 bridge_connected
+                await new Promise((resolve, reject) => {
+                    const timeout = setTimeout(() => {
+                        reject(new Error('连接新服务器超时'));
+                    }, 5000);
+
+                    onNextBridgeConnected(() => {
+                        clearTimeout(timeout);
+                        resolve();
+                    });
+                });
+
+                // 发配置和重启
+                await requestWakewordBridge('set_wakeword_config', payload);
+                this.applyWakewordConfig(payload);
+                await requestWakewordBridge('restart_wakeword_service');
+                this.addChatMessage('唤醒词配置已保存，唤醒词服务正在重启。', false);
+            } else {
+                // 地址没变：直接在当前连接操作
+                const response = await requestWakewordBridge('set_wakeword_config', payload);
+                this.applyWakewordConfig(response.payload || payload);
+
+                const shouldRestart = window.confirm('唤醒词已保存。是否现在重启唤醒词服务以立即生效？');
+                if (!shouldRestart) {
+                    this.addChatMessage('唤醒词配置已保存，可稍后手动重启服务后生效。', false);
+                    return;
+                }
+
+                await requestWakewordBridge('restart_wakeword_service');
+                this.addChatMessage('唤醒词配置已保存，唤醒词服务正在重启。', false);
+            }
+        } catch (error) {
+            this.addChatMessage(`应用唤醒词失败: ${error.message}`, false);
+        } finally {
+            if (applyWakewordBtn) {
+                applyWakewordBtn.disabled = false;
+                applyWakewordBtn.textContent = '应用唤醒词';
+            }
+        }
+    }
+
     // Start AI chat session after connection
     startAIChatSession() {
         this.addChatMessage('连接成功，开始聊天吧~😊', false);
@@ -550,47 +677,51 @@ class UIController {
 
     // Handle connect button click
     async handleConnect() {
-        console.log('handleConnect called');
+        const wsHandler = getWebSocketHandler();
-
+        if (this.isConnecting || (wsHandler && wsHandler.isConnected())) {
-        // Switch to device settings tab
+            log('连接已存在或正在进行，忽略本次拨号请求', 'info');
-        this.switchTab('device');
-
-        // Wait for DOM update
-        await new Promise(resolve => setTimeout(resolve, 50));
-
-        const otaUrlInput = document.getElementById('otaUrl');
-
-        console.log('otaUrl element:', otaUrlInput);
-
-        if (!otaUrlInput || !otaUrlInput.value) {
-            this.addChatMessage('请输入OTA服务器地址', false);
             return;
         }
 
-        const otaUrl = otaUrlInput.value;
+        this.isConnecting = true;
-        console.log('otaUrl value:', otaUrl);
+        console.log('handleConnect called');
-
-        // Update dial button state to connecting
-        const dialBtn = document.getElementById('dialBtn');
-        if (dialBtn) {
-            dialBtn.classList.add('dial-active');
-            dialBtn.querySelector('.btn-text').textContent = '连接中...';
-            dialBtn.disabled = true;
-        }
-
-        // Show connecting message
-        this.addChatMessage('正在连接服务器...', false);
-
-        const chatIpt = document.getElementById('chatIpt');
-        if (chatIpt) {
-            chatIpt.style.display = 'flex';
-        }
 
         try {
+            // Switch to device settings tab
+            this.switchTab('device');
+
+            // Wait for DOM update
+            await new Promise(resolve => setTimeout(resolve, 50));
+
+            const otaUrlInput = document.getElementById('otaUrl');
+
+            console.log('otaUrl element:', otaUrlInput);
+
+            if (!otaUrlInput || !otaUrlInput.value) {
+                this.addChatMessage('请输入OTA服务器地址', false);
+                return;
+            }
+
+            const otaUrl = otaUrlInput.value;
+            console.log('otaUrl value:', otaUrl);
+
+            // Update dial button state to connecting
+            const dialBtn = document.getElementById('dialBtn');
+            if (dialBtn) {
+                dialBtn.classList.add('dial-active');
+                dialBtn.querySelector('.btn-text').textContent = '连接中...';
+                dialBtn.disabled = true;
+            }
+
+            // Show connecting message
+            this.addChatMessage('正在连接服务器...', false);
+
+            const chatIpt = document.getElementById('chatIpt');
+            if (chatIpt) {
+                chatIpt.style.display = 'flex';
+            }
 
             // Get WebSocket handler instance
-            const wsHandler = getWebSocketHandler();
-
             // Register connection state callback BEFORE connecting
             wsHandler.onConnectionStateChange = (isConnected) => {
                 this.updateConnectionUI(isConnected);
@@ -670,9 +801,36 @@ class UIController {
                 dialBtn.classList.remove('dial-active');
                 console.log('Dial button state restored successfully');
             }
+        } finally {
+            this.isConnecting = false;
         }
     }
 
+    async triggerWakewordDial(wakeWord = '唤醒词') {
+        const wsHandler = getWebSocketHandler();
+        const now = Date.now();
+
+        if (wsHandler && wsHandler.isConnected()) {
+            log('页面已连接，忽略自动拨号', 'info');
+            return false;
+        }
+
+        if (this.isConnecting || this.dialBtnDisabled) {
+            log('页面正在连接中，忽略重复唤醒', 'info');
+            return false;
+        }
+
+        if (now - this.lastWakewordDialTime < 3000) {
+            log('唤醒触发过于频繁，忽略本次自动拨号', 'warning');
+            return false;
+        }
+
+        this.lastWakewordDialTime = now;
+        this.addChatMessage(`检测到唤醒词“${wakeWord}”，准备连接服务器...`, false);
+        await this.handleConnect();
+        return true;
+    }
+
     // Add MCP tool
     addMCPTool() {
         const mcpToolsList = document.getElementById('mcpToolsList');