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/ISSUE_TEMPLATE/bug_report.md

@@ -9,26 +9,24 @@ assignees: ''
 ## 🐛 问题描述
 <!-- 清晰简洁地描述问题是什么 -->
 
-## 🔍 复现步骤
-<!-- 详细描述复现问题的步骤 -->
+## 🖥️ 环境信息
+- 部署方式: 全模块部署 还是 单Server部署
+- 版本号: 例如 0.3.x
+
+## 🔍 告诉我们，应该怎么复现这个问题
+<!-- 这个很重要，方便我们快速定位 -->
 1. 打开 '...'
 2. 点击 '...'
 3. 滚动到 '...'
 4. 看到错误
 
-## 🤔 预期行为
+## 🤔 你原本希望是怎么样的
 <!-- 简要描述预期的正确行为 -->
 
-## 😯 截图
+## 😯 提供一些截图
 <!-- 如果适用，添加问题的截图 -->
-
-## 🖥️ 环境信息
-- 操作系统: [例如 Windows 10]
-- 浏览器: [例如 Chrome 89]
-- 项目版本: [例如 1.0.0]
-- Python版本: [例如 3.9.13]
-- Jdk版本：[例如 java 21.0.5 2024-10-15 LTS]
-- Nodejs版本：[例如 v20.14.0]
+1. 比如日志截图，越多越好
+2. 比如界面反应
 
 ## 📋 其他信息
 <!-- 在此添加关于此问题的任何其他上下文信息 -->

.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 只包含一个计划工作包或可独立回滚切片
+- [ ] 路线图状态和证据链接将在合并后更新

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /main/xiaozhi-server
+    schedule:
+      interval: weekly

.github/workflows/build-base-image.yml

@@ -0,0 +1,49 @@
+name: Build Base Image
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'main/xiaozhi-server/requirements.txt'
+      - 'Dockerfile-server-base'
+      - '.github/workflows/build-base-image.yml'
+
+jobs:
+  build-base:
+    name: Build and push server base image
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.TOKEN }}
+
+      - name: Build and push server-base
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: Dockerfile-server-base
+          push: true
+          tags: ghcr.io/${{ github.repository }}:server-base
+          platforms: linux/amd64,linux/arm64
+          cache-from: type=gha,scope=server-base
+          cache-to: type=gha,mode=max,scope=server-base
+          build-args: |
+            BUILDKIT_PROGRESS=plain
+
+      - name: Output image info
+        run: |
+          echo "✅ Base image built and pushed successfully!"
+          echo "📦 Tag: ghcr.io/${{ github.repository }}:server-base"

.github/workflows/docker-image.yml

@@ -4,6 +4,11 @@ on:
   push:
     tags:
       - 'v*.*.*'  # 只在以 v 开头的标签推送时触发，例如 v1.0.0
+  workflow_dispatch:
+  workflow_run:
+    workflows: ["Build Base Image"]
+    types:
+      - completed
 
 jobs:
   release:
@@ -30,6 +35,9 @@ jobs:
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
+        with:
+          driver-opts: |
+            network=host
 
       - name: Login to GitHub Container Registry
         uses: docker/login-action@v3
@@ -41,7 +49,13 @@ jobs:
       - name: Extract version from tag
         id: get_version
         run: |
-          echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
+          if [[ "$GITHUB_REF" =~ ^refs/tags/v([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
+            echo "VERSION=${BASH_REMATCH[1]}" >> $GITHUB_ENV
+            echo "IS_VERSION=true" >> $GITHUB_ENV
+          else
+            echo "VERSION=latest" >> $GITHUB_ENV
+            echo "IS_VERSION=false" >> $GITHUB_ENV
+          fi
 
       # 构建 xiaozhi-server 镜像
       - name: Build and push xiaozhi-server
@@ -51,9 +65,12 @@ jobs:
           file: Dockerfile-server
           push: true
           tags: |
-            ghcr.io/${{ github.repository }}:server_${{ env.VERSION }}
-            ghcr.io/${{ github.repository }}:server_latest
+            ${{ env.IS_VERSION == 'true' && format('ghcr.io/{0}:server_{1},ghcr.io/{0}:server_latest', github.repository, env.VERSION) || format('ghcr.io/{0}:server_latest', github.repository) }}
           platforms: linux/amd64,linux/arm64
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          build-args: |
+            BUILDKIT_PROGRESS=plain
 
       # 构建 manager-api 镜像
       - name: Build and push manager-web
@@ -63,6 +80,9 @@ jobs:
           file: Dockerfile-web
           push: true
           tags: |
-            ghcr.io/${{ github.repository }}:web_${{ env.VERSION }}
-            ghcr.io/${{ github.repository }}:web_latest
-          platforms: linux/amd64,linux/arm64
+            ${{ env.IS_VERSION == 'true' && format('ghcr.io/{0}:web_{1},ghcr.io/{0}:web_latest', github.repository, env.VERSION) || format('ghcr.io/{0}:web_latest', github.repository) }}
+          platforms: linux/amd64,linux/arm64
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          build-args: |
+            BUILDKIT_PROGRESS=plain

.gitignore

@@ -3,6 +3,9 @@ __pycache__/
 .idea/
 *.py[cod]
 *$py.class
+.vscode
+.claude
+AGENTS.md
 
 # C extensions
 *.so
@@ -75,6 +78,7 @@ docs/_build/
 # PyBuilder
 .pybuilder/
 target/
+*.pid
 
 # Jupyter Notebook
 .ipynb_checkpoints
@@ -108,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
@@ -145,6 +154,8 @@ tmp
 .history
 .DS_Store
 main/xiaozhi-server/data
+main/xiaozhi-server/.claude
+
 main/manager-web/node_modules
 .config.yaml
 .secrets.yaml
@@ -154,3 +165,35 @@ main/manager-web/node_modules
 # model files
 main/xiaozhi-server/models/SenseVoiceSmall/model.pt
 main/xiaozhi-server/models/sherpa-onnx*
+/main/xiaozhi-server/audio_ref/
+/audio_ref/
+/asr-models/iic/SenseVoiceSmall/
+/main/xiaozhi-server/asr-models/iic/SenseVoiceSmall/
+/models/SenseVoiceSmall/model.pt
+my_wakeup_words.mp3
+!main/xiaozhi-server/config/assets/bind_code.wav
+!main/xiaozhi-server/config/assets/wakeup_words.wav
+!main/xiaozhi-server/config/assets/bind_not_found.wav
+!main/xiaozhi-server/config/assets/bind_code/*.wav
+!main/xiaozhi-server/config/assets/max_output_size.wav
+main/manager-api/.vscode
+# Ignore webpack cache directory
+main/manager-web/.webpack_cache/
+main/xiaozhi-server/mysql
+uploadfile
+*.json
+.vscode
+.cursor
+ 
+!package.json
+!**/package.json
+
+# Do not ignore env and json files inside manager-mobile
+!main/manager-mobile/**/env/
+!main/manager-mobile/**/.env*
+!main/manager-mobile/**/*.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

Dockerfile-server

@@ -1,28 +1,6 @@
-# 第一阶段：构建Python依赖
-FROM python:3.10-slim AS builder
+# 生产镜像，仅包含应用代码
+FROM ghcr.io/xinnan-tech/xiaozhi-esp32-server:server-base
 
-WORKDIR /app
-
-COPY main/xiaozhi-server/requirements.txt .
-
-# 优化apt安装
-RUN pip install --no-cache-dir -r requirements.txt
-
-# 第三阶段：生产镜像
-FROM python:3.10-slim
-
-WORKDIR /opt/xiaozhi-esp32-server
-
-# 优化apt安装
-RUN apt-get update && \
-    apt-get install -y --no-install-recommends libopus0 ffmpeg && \
-    apt-get clean && \
-    rm -rf /var/lib/apt/lists/*
-
-# 从构建阶段复制Python包和前端构建产物
-COPY --from=builder /usr/local/lib/python3.10/site-packages /usr/local/lib/python3.10/site-packages
-
-# 复制应用代码
 COPY main/xiaozhi-server .
 
 # 启动应用

Dockerfile-server-base

@@ -0,0 +1,32 @@
+# Dockerfile-server-base
+# 基础镜像，包含系统依赖和Python包
+FROM python:3.10-slim
+
+# 安装系统依赖
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends libopus0 ffmpeg locales && \
+    sed -i '/zh_CN.UTF-8/s/^# //g' /etc/locale.gen && \
+    locale-gen && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# 配置pip使用国内镜像源（阿里云）并设置超时和重试
+RUN pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ && \
+    pip config set global.trusted-host mirrors.aliyun.com && \
+    pip config set global.timeout 120 && \
+    pip config set install.retries 5
+
+# 设置环境变量以确保正确的字符编码
+ENV LANG=zh_CN.UTF-8 \
+    LC_ALL=zh_CN.UTF-8 \
+    LANGUAGE=zh_CN:zh \
+    PYTHONIOENCODING=utf-8
+
+WORKDIR /opt/xiaozhi-esp32-server
+
+# 复制requirements.txt
+COPY main/xiaozhi-server/requirements.txt .
+
+# 安装Python依赖
+RUN pip install --no-cache-dir --upgrade pip setuptools wheel && \
+    pip install --no-cache-dir -r requirements.txt --default-timeout=120 --retries 5

Dockerfile-web

@@ -1,5 +1,5 @@
 # 第一阶段：构建Vue前端
-FROM node:18 as web-builder
+FROM node:18 AS web-builder
 WORKDIR /app
 COPY main/manager-web/package*.json ./
 RUN npm install
@@ -7,23 +7,33 @@ COPY main/manager-web .
 RUN npm run build
 
 # 第二阶段：构建Java后端
-FROM maven:3-eclipse-temurin-21-alpine as api-builder
+FROM maven:3.9.4-eclipse-temurin-21 AS api-builder
 WORKDIR /app
 COPY main/manager-api/pom.xml .
 COPY main/manager-api/src ./src
 RUN mvn clean package -Dmaven.test.skip=true
 
 # 第三阶段：构建最终镜像
-FROM eclipse-temurin:21-jdk-jammy
+FROM bellsoft/liberica-runtime-container:jre-21-glibc
 
-# 安装Nginx并清理缓存
-RUN apt-get update && \
-    apt-get install -y nginx && \
-    apt-get clean && \
-    rm -rf /var/lib/apt/lists/*
+# 安装Nginx和字体库
+RUN apk update && \
+    apk add --no-cache --no-scripts \
+        nginx \
+        bash \
+        fontconfig \
+        ttf-dejavu \
+    && rm -rf /var/cache/apk/* \
+    && mkdir -p /run/nginx /var/log/nginx /var/tmp/nginx /etc/nginx/conf.d
+
+# 复制项目自带的中文字体
+COPY main/manager-web/public/generator/static/fonts/*.ttf /usr/share/fonts/
+
+# 更新字体缓存
+RUN fc-cache -f -v
 
 # 配置Nginx
-COPY docs/docker/nginx.conf /etc/nginx/conf.d/default.conf
+COPY docs/docker/nginx.conf /etc/nginx/nginx.conf
 
 # 复制前端构建产物
 COPY --from=web-builder /app/dist /usr/share/nginx/html

README.md

@@ -1,22 +1,45 @@
-[![SVG Banners](https://svg-banners.vercel.app/api?type=origin&text1=你好😃，小智📟&text2=开源小智ESP-32后端服务&width=830&height=210)](https://github.com/xinnan-tech/xiaozhi-esp32-server)
+[![Banners](docs/images/banner1.png)](https://github.com/xinnan-tech/xiaozhi-esp32-server)
+
+<h1 align="center">小智后端服务xiaozhi-esp32-server</h1>
+
 <p align="center">
-  <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors">
-    <img alt="GitHub Contributors" src="https://img.shields.io/github/contributors/xinnan-tech/xiaozhi-esp32-server" />
+本项目基于人机共生智能理论和技术研发智能终端软硬件体系<br/>为开源智能硬件项目
+<a href="https://github.com/78/xiaozhi-esp32">xiaozhi-esp32</a>提供后端服务<br/>
+根据<a href="https://ccnphfhqs21z.feishu.cn/wiki/M0XiwldO9iJwHikpXD5cEx71nKh">小智通信协议</a>使用Python、Java、Vue实现<br/>
+支持MQTT+UDP协议、Websocket协议、MCP接入点、声纹识别、知识库
+</p>
+
+<p align="center">
+<a href="./docs/FAQ.md">常见问题</a>
+· <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/issues">反馈问题</a>
+· <a href="./README.md#%E9%83%A8%E7%BD%B2%E6%96%87%E6%A1%A3">部署文档</a>
+· <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/releases">更新日志</a>
+</p>
+
+<p align="center">
+  <a href="./README.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-DBEDFA"></a>
+  <a href="./docs/readme/README_en.md"><img alt="README in English" src="https://img.shields.io/badge/English-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="./docs/readme/README_de.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-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>
-  <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/issues">
-    <img alt="Issues" src="https://img.shields.io/github/issues/xinnan-tech/xiaozhi-esp32-server?color=0088ff" />
+  <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/main/LICENSE">
+    <img alt="GitHub pull requests" src="https://img.shields.io/badge/license-MIT-white?labelColor=black" />
   </a>
-  <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/pulls">
-    <img alt="GitHub pull requests" src="https://img.shields.io/github/issues-pr/xinnan-tech/xiaozhi-esp32-server?color=0088ff" />
+  <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server">
+    <img alt="stars" src="https://img.shields.io/github/stars/xinnan-tech/xiaozhi-esp32-server?color=ffcb47&labelColor=black" />
   </a>
 </p>
 
-# 小智 ESP-32 后端服务(xiaozhi-esp32-server)
-
-（中文 | [English](README_en.md)）
-
-本项目为开源智能硬件项目 [xiaozhi-esp32](https://github.com/78/xiaozhi-esp32)
-提供后端服务。根据 [小智通信协议](https://ccnphfhqs21z.feishu.cn/wiki/M0XiwldO9iJwHikpXD5cEx71nKh) 使用 `Python` 实现。
+<p align="center">
+Spearheaded by Professor Siyuan Liu's Team (South China University of Technology)
+</br>
+刘思源教授团队主导研发（华南理工大学）
+</br>
+<img src="./docs/images/hnlg.jpg" alt="华南理工大学" width="50%">
+</p>
 
 ---
 
@@ -30,184 +53,236 @@
 <table>
   <tr>
     <td>
-        <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
-         <picture>
-           <img alt="小智esp32连接自己的后台模型" src="docs/images/demo1.png" />
-         </picture>
-        </a>
+      <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
+        <picture>
+          <img alt="响应速度感受" src="docs/images/demo9.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>
+      <a href="https://www.bilibili.com/video/BV1vchQzaEse" target="_blank">
+        <picture>
+          <img alt="速度优化秘诀" src="docs/images/demo6.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>
+      <a href="https://www.bilibili.com/video/BV1WEcxzFEAT" target="_blank">
+        <picture>
+          <img alt="小智数字人 支持语音唤醒" src="docs/images/demo8.png" /></picture>
+      </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/av114036381327149" target="_blank">
-         <picture>
-           <img alt="控制家电开关" src="docs/images/demo5.png" />
-         </picture>
-        </a>
+      <a href="https://www.bilibili.com/video/BV1CKVz6UEuB" target="_blank">
+        <picture>
+          <img alt="设备呼叫设备，打电话" src="docs/images/demo0.png" /></picture>
+      </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV1kgA2eYEQ9" target="_blank">
-         <picture>
-           <img alt="成本最低配置" src="docs/images/demo4.png" />
-         </picture>
-        </a>
+      <a href="https://www.bilibili.com/video/BV1C1tCzUEZh" target="_blank">
+        <picture>
+          <img alt="复杂医疗场景" src="docs/images/demo1.png" /></picture>
+      </a>
     </td>
   </tr>
   <tr>
     <td>
-        <a href="https://www.bilibili.com/video/BV1Vy96YCE3R" target="_blank">
-         <picture>
-           <img alt="自定义音色" src="docs/images/demo6.png" />
-         </picture>
-        </a>
+      <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/BV1VC96Y5EMH" target="_blank">
-         <picture>
-           <img alt="播放音乐" src="docs/images/demo7.png" />
-         </picture>
-        </a>
+      <a href="https://www.bilibili.com/video/BV12J7WzBEaH" target="_blank">
+        <picture>
+          <img alt="实时打断" src="docs/images/demo10.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>
+      <a href="https://www.bilibili.com/video/BV1Co76z7EvK" target="_blank">
+        <picture>
+          <img alt="拍照识物品" src="docs/images/demo12.png" /></picture>
+      </a>
     </td>
     <td>
-        <a href="https://www.bilibili.com/video/BV178XuYfEpi" target="_blank">
-         <picture>
-           <img alt="IOT指令控制设备" src="docs/images/demo9.png" />
-         </picture>
-        </a>
+      <a href="https://www.bilibili.com/video/BV1pNXWYGEx1" target="_blank">
+        <picture>
+          <img alt="控制家电开关" src="docs/images/demo5.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>
+  </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/BV1zUW5zJEkq" target="_blank">
+        <picture>
+          <img alt="MQTT指令下发" src="docs/images/demo4.png" /></picture>
+      </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>
 
 ---
 
-## 系统要求与部署前提 🖥️
-
-- **硬件**：一套兼容 `xiaozhi-esp32`
-  的硬件设备（具体型号请参考 [此处](https://rcnv1t9vps13.feishu.cn/wiki/DdgIw4BUgivWDPkhMj1cGIYCnRf)）。
-
-- **电脑或服务器**：建议 4 核 CPU、8G 内存的电脑。如果开启ASR也使用API，可运行在2核CPU、2G内存的服务器中。
-- **固件编译**：请将本后端服务的接口地址更新至 `xiaozhi-esp32` 项目中，再重新编译`xiaozhi-esp32`固件并烧录到设备上。
-
-![图片](docs/images/deploy.png)
-
-如果你没有esp32相关的硬件设备，但是非常想体验该项目，可以使用以下的项目让你的电脑、手机模拟成esp32设备。
-
-- [小智安卓端](https://github.com/TOM88812/xiaozhi-android-client)
-- [小智电脑端](https://github.com/Huang-junsen/py-xiaozhi)
-
-如果你是一名软件开发者，这里有一份[《致开发者的公开信》](docs/contributor_open_letter.md)，欢迎加入！
-
----
-
 ## 警告 ⚠️
 
 1、本项目为开源软件，本软件与对接的任何第三方API服务商（包括但不限于语音识别、大模型、语音合成等平台）均不存在商业合作关系，不为其服务质量及资金安全提供任何形式的担保。
 建议使用者优先选择持有相关业务牌照的服务商，并仔细阅读其服务协议及隐私政策。本软件不托管任何账户密钥、不参与资金流转、不承担充值资金损失风险。
 
-2、本项目成立时间较短，还未通过网络安全测评，请勿在生产环境中使用。 如果您在公网环境中部署学习本项目，请务必在配置文件
-`config.yaml` 中开启防护：
-
-```yaml
-server:
-  auth:
-    # 开启防护
-    enabled: true  
-```
-
-开启防护后，您需要根据实际情况校验机器的 token 或 mac 地址，详细请参见配置说明。
+2、本项目功能未完善，且未通过网络安全测评，请勿在生产环境中使用。 如果您在公网环境中部署学习本项目，请务必做好必要的防护。
 
 ---
 
+## 部署文档
+
+![Banners](docs/images/banner2.png)
+
+本项目提供两种部署方式，请根据您的具体需求选择：
+
+#### 🚀 部署方式选择
+| 部署方式 | 特点 | 适用场景 | 部署文档 | 配置要求 | 视频教程 | 
+|---------|------|---------|---------|---------|---------|
+| **最简化安装** | 智能对话、单智能体管理 | 低配置环境，数据存储在配置文件，无需数据库 | [①Docker版](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) / [②源码部署](./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)| 如果使用`FunASR`要2核4G，如果全API，要2核2G | - | 
+| **全模块安装** | 智能对话、多用户管理、多智能体管理、智控台界面操作 | 完整功能体验，数据存储在数据库 |[①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) / [②源码部署](./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) / [③源码部署自动更新教程](./docs/dev-ops-integration.md) | 如果使用`FunASR`要4核8G，如果全API，要2核4G| [本地源码启动视频教程](https://www.bilibili.com/video/BV1wBJhz4Ewe) | 
+
+常见问题及相关教程，可参考[这个链接](./docs/FAQ.md)
+
+> 💡 提示：以下是按最新代码部署后的测试平台，有需要可烧录测试，并发为6个，每天会清空数据，
+
+```
+智控台地址: https://2662r3426b.vicp.fun
+智控台(h5版): https://2662r3426b.vicp.fun/h5/index.html
+
+服务测试工具： https://2662r3426b.vicp.fun/test/
+OTA接口地址: https://2662r3426b.vicp.fun/xiaozhi/ota/
+Websocket接口地址: wss://2662r3426b.vicp.fun/xiaozhi/v1/
+```
+
+#### 🚩 配置说明和推荐
+> [!Note]
+> 本项目提供两种配置方案：
+> 
+> 1. `入门全免费`配置：适合个人家庭使用，所有组件均采用免费方案，无需额外付费。
+> 
+> 2. `流式配置`：适合演示、培训、超过2个并发等场景，采用流式处理技术，响应速度更快，体验更佳。
+> 
+> 自`0.5.2`版本起，项目支持流式配置，相比早期版本，响应速度提升约`2.5秒`，显著改善用户体验。
+
+| 模块名称 | 入门全免费设置 | 流式配置 |
+|:---:|:---:|:---:|
+| ASR(语音识别) | FunASR(本地) | 👍XunfeiStreamASR(讯飞流式) |
+| LLM(大模型) | glm-4-flash(智谱) | 👍qwen-flash(阿里百炼) |
+| VLLM(视觉大模型) | glm-4v-flash(智谱) | 👍qwen3.5-flash(阿里百炼) |
+| TTS(语音合成) | EdgeTTS(微软) | 👍HuoshanDoubleStreamTTS(火山流式) |
+| Intent(意图识别) | function_call(函数调用) | function_call(函数调用) |
+| Memory(记忆功能) | mem_local_short(本地短期记忆） | mem_local_short（本地短期记忆） |
+
+如果您关心各组件的耗时，请查阅[小智各组件性能测试报告](https://github.com/xinnan-tech/xiaozhi-performance-research)，可按报告中的测试方法在您的环境中实际测试。
+
+#### 🔧 测试工具
+本项目提供以下测试工具，帮助您验证系统和选择合适的模型：
+
+| 工具名称 | 位置 | 使用方法 | 功能说明 |
+|:---:|:---|:---:|:---:|
+| 音频交互测试工具 | 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(语音合成)三个核心模块的响应速度 |
+
+> 💡 提示：测试模型速度时，只会测试配置了密钥的模型。
+
+---
 ## 功能清单 ✨
-
 ### 已实现 ✅
-
-- **通信协议**  
-  基于 `xiaozhi-esp32` 协议，通过 WebSocket 实现数据交互。
-- **对话交互**  
-  支持唤醒对话、手动对话及实时打断。长时间无对话时自动休眠
-- **意图识别**  
-  支持使用LLM意图识别、function call函数调用，减少硬编码意图判断
-- **多语言识别**  
-  支持国语、粤语、英语、日语、韩语（默认使用 FunASR）。
-- **LLM 模块**  
-  支持灵活切换 LLM 模块，默认使用 ChatGLMLLM，也可选用阿里百炼、DeepSeek、Ollama 等接口。
-- **TTS 模块**  
-  支持 EdgeTTS（默认）、火山引擎豆包 TTS 等多种 TTS 接口，满足语音合成需求。
-- **记忆功能**  
-  支持超长记忆、本地总结记忆、无记忆三种模式，满足不同场景需求。
-- **IOT功能**  
-  支持管理注册设备IOT功能，支持基于对话上下文语境下的智能物联网控制。
+![请参考-全模块安装架构图](docs/images/deploy2.png)
+| 功能模块 | 描述 |
+|:---:|:---|
+| 核心架构 | 基于[MQTT+UDP网关](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/main/docs/mqtt-gateway-integration.md)、WebSocket、HTTP服务器，提供完整的控制台管理和认证系统 |
+| 语音交互 | 支持流式ASR(语音识别)、流式TTS(语音合成)、VAD(语音活动检测)，支持多语言识别和语音处理 |
+| 声纹识别 | 支持多用户声纹注册、管理和识别，与ASR并行处理，实时识别说话人身份并传递给LLM进行个性化回应 |
+| 智能对话 | 支持多种LLM(大语言模型)，实现智能对话 |
+| 视觉感知 | 支持多种VLLM(视觉大模型)，实现多模态交互 |
+| 意图识别 | 支持外挂的大模型意图识别、大模型自主函数调用，提供插件化意图处理机制 |
+| 记忆系统 | 支持本地短期记忆、mem0ai接口记忆、PowerMem智能记忆，具备记忆总结功能 |
+| 知识库 | 支持RAGFlow知识库，让大模型判断需要调度知识库后再回答 |
+| 工具调用 | 支持客户端IOT协议、客户MCP协议、服务端MCP协议、MCP接入点协议、自定义工具函数 |
+| 指令下发 | 依托MQTT协议，支持从智控台将MCP指令下发到ESP32设备 |
+| 管理后台 | 提供Web管理界面，支持用户管理、系统配置和设备管理；界面支持中文简体、中文繁体、英文显示 |
+| 测试工具 | 提供性能测试工具、视觉模型测试工具和音频交互测试工具 |
+| 部署支持 | 支持Docker部署和本地部署，提供完整的配置文件管理 |
+| 插件系统 | 支持功能插件扩展、自定义插件开发和插件热加载 |
 
 ### 正在开发 🚧
 
-- 多种心情模式
-- 智控台webui
+想了解具体开发计划进度，[请点击这里](https://github.com/users/xinnan-tech/projects/3)。常见问题及相关教程，可参考[这个链接](./docs/FAQ.md)
 
-想了解具体开发进度，[请点击这里](https://github.com/users/xinnan-tech/projects/3)
+如果你是一名软件开发者，这里有一份[《致开发者的公开信》](docs/contributor_open_letter.md)，欢迎加入！
+
+---
+
+## 产品生态 👬
+小智是一个生态，当你使用这个产品时，也可以看看其他在这个生态圈的[优秀项目](https://github.com/78/xiaozhi-esp32/blob/main/README_zh.md#%E7%9B%B8%E5%85%B3%E5%BC%80%E6%BA%90%E9%A1%B9%E7%9B%AE)
 
-![图片](docs/images/webui.png)
 ---
 
 ## 本项目支持的平台/组件列表 📋
-
 ### LLM 语言模型
 
-| 类型  |        平台名称        |         使用方式          |    收费模式     |                                                           备注                                                            |
-|:---:|:------------------:|:---------------------:|:-----------:|:-----------------------------------------------------------------------------------------------------------------------:|
-| LLM |   阿里百炼 (AliLLM)    |      openai 接口调用      |  消耗 token   |                             [点击申请密钥](https://bailian.console.aliyun.com/?apiKey=1#/api-key)                             |
-| LLM |     DoubaoLLM      |      openai 接口调用      |  消耗 token   | [点击申请密钥](https://console.volcengine.com/ark/region:ark+cn-beijing/model/detail?Id=doubao-pro-32k&projectName=undefined) |
-| LLM | 深度求索 (DeepSeekLLM) |      openai 接口调用      |  消耗 token   |                                        [点击申请密钥](https://platform.deepseek.com/)                                         |
-| LLM |   智谱（ChatGLMLLM）   |      openai 接口调用      |     免费      |                            虽然免费，仍需[点击申请密钥](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)                            |
-| LLM |     OllamaLLM      |      ollama 接口调用      | 免费/消耗 token |                                  需预先下载模型（`ollama pull`），服务地址：`http://localhost:11434`                                   |
-| LLM |      DifyLLM       |       dify 接口调用       | 免费/消耗 token |                                               本地化部署，注意配置提示词需在 Dify 控制台设置                                                |
-| LLM |     FastgptLLM     |     fastgpt 接口调用      | 免费/消耗 token |                                              本地化部署，注意配置提示词需在 Fastgpt 控制台设置                                              |
-| LLM |     GeminiLLM      |      gemini 接口调用      |     免费      |                                      [点击申请密钥](https://aistudio.google.com/apikey)                                       |
-| LLM |      CozeLLM       |       coze 接口调用       |  消耗 token   |                                                需提供 bot_id、user_id 及个人令牌                                                 |
-| LLM |   Home Assistant   | homeassistant语音助手接口调用 |     免费      |                                                   需提供home assistant令牌                                                   |
+| 使用方式 | 支持平台 | 免费平台 |
+|:---:|:---:|:---:|
+| openai 接口调用 | 阿里百炼、火山引擎、DeepSeek、智谱、Gemini、科大讯飞 | 智谱、Gemini |
+| ollama 接口调用 | Ollama | - |
+| dify 接口调用 | Dify | - |
+| fastgpt 接口调用 | Fastgpt | - |
+| coze 接口调用 | Coze | - |
+| xinference 接口调用 | Xinference | - |
+| homeassistant 接口调用 | HomeAssistant | - |
 
 实际上，任何支持 openai 接口调用的 LLM 均可接入使用。
 
 ---
 
+### VLLM 视觉模型
+
+| 使用方式 | 支持平台 | 免费平台 |
+|:---:|:---:|:---:|
+| openai 接口调用 | 阿里百炼、智谱ChatGLMVLLM | 智谱ChatGLMVLLM |
+
+实际上，任何支持 openai 接口调用的 VLLM 均可接入使用。
+
+---
+
 ### TTS 语音合成
 
-| 类型  |          平台名称          | 使用方式 |   收费模式   |                                    备注                                     |
-|:---:|:----------------------:|:----:|:--------:|:-------------------------------------------------------------------------:|
-| TTS |        EdgeTTS         | 接口调用 |    免费    |                             默认 TTS，基于微软语音合成技术                             |
-| TTS | 火山引擎豆包 TTS (DoubaoTTS) | 接口调用 | 消耗 token | [点击创建密钥](https://console.volcengine.com/speech/service/8)；建议使用付费版本以获得更高并发 |
-| TTS |       AliyunTTS        | 接口调用 | 消耗 token |          [点击创建密钥](https://nls-portal.console.aliyun.com/applist)          |
-| TTS |  CosyVoiceSiliconflow  | 接口调用 | 消耗 token |                         需申请硅基流动 API 密钥；输出格式为 wav                          |
-| TTS |        TTS302AI        | 接口调用 | 消耗 token |                  [点击创建密钥](https://dash.302.ai/apis/list)                  |
-| TTS |       CozeCnTTS        | 接口调用 | 消耗 token |                        需提供 Coze API key；输出格式为 wav                         |
-| TTS |       GizwitsTTS       | 接口调用 | 消耗 token |                  [点击创建密钥](https://agentrouter.gizwitsapi.com)                  |
-| TTS |        ACGNTTS         | 接口调用 | 消耗 token |                        [联系网站管理员购买密钥](www.ttson.cn)                        |
-| TTS |       OpenAITTS        | 接口调用 | 消耗 token |                                 境外使用，境外购买                                 |
-| TTS |       FishSpeech       | 接口调用 |  免费/自定义  |                         本地启动 TTS 服务；启动方法见配置文件内说明                          |
-| TTS |     GPT_SOVITS_V2      | 接口调用 |  免费/自定义  |                         本地启动 TTS 服务，适用于个性化语音合成场景                          |
-| TTS |     GPT_SOVITS_V3      | 接口调用 |  免费/自定义  |                         本地启动 TTS 服务，适用于个性化语音合成场景                          |
-| TTS |       MinimaxTTS       | 接口调用 |  免费/自定义  |                         本地启动 TTS 服务，适用于个性化语音合成场景                          |
+| 使用方式 | 支持平台 | 免费平台 |
+|:---:|:---:|:---:|
+| 接口调用 | EdgeTTS、科大讯飞、火山引擎、腾讯云、阿里云及百炼、CosyVoiceSiliconflow、TTS302AI、CozeCnTTS、GizwitsTTS、ACGNTTS、OpenAITTS、灵犀流式TTS、MinimaxTTS | 灵犀流式TTS、EdgeTTS、CosyVoiceSiliconflow(部分) |
+| 本地服务 | FishSpeech、GPT_SOVITS_V2、GPT_SOVITS_V3、Index-TTS、PaddleSpeech | Index-TTS、PaddleSpeech、FishSpeech、GPT_SOVITS_V2、GPT_SOVITS_V3 |
 
 ---
 
@@ -221,12 +296,18 @@ server:
 
 ### ASR 语音识别
 
-| 类型  |   平台名称    | 使用方式 | 收费模式 | 备注 |
-|:---:|:---------:|:----:|:----:|:--:|
-| ASR |  FunASR   | 本地使用 |  免费  |    |
-| ASR | SherpaASR | 本地使用 |  免费  |    |
-| ASR | DoubaoASR | 接口调用 |  收费  |    |
+| 使用方式 | 支持平台 | 免费平台 |
+|:---:|:---:|:---:|
+| 本地使用 | FunASR、SherpaASR | FunASR、SherpaASR |
+| 接口调用 | FunASRServer、火山引擎、科大讯飞、腾讯云、阿里云、百度云、OpenAI ASR | FunASRServer |
 
+---
+
+### Voiceprint 声纹识别
+
+| 使用方式 | 支持平台 | 免费平台 |
+|:---:|:---:|:---:|
+| 本地使用 | 3D-Speaker | 3D-Speaker |
 
 ---
 
@@ -235,7 +316,9 @@ server:
 |   类型   |      平台名称       | 使用方式 |   收费模式    | 备注 |
 |:------:|:---------------:|:----:|:---------:|:--:|
 | Memory |     mem0ai      | 接口调用 | 1000次/月额度 |    |
+| Memory |     [powermem](./docs/powermem-integration.md)    | 本地总结 | 取决于LLM和DB |  OceanBase开源，支持智能检索  |
 | Memory | mem_local_short | 本地总结 |    免费     |    |
+| Memory |     nomem       | 无记忆模式 |    免费     |    |
 
 ---
 
@@ -245,154 +328,36 @@ server:
 |:------:|:-------------:|:----:|:-------:|:---------------------:|
 | Intent |  intent_llm   | 接口调用 | 根据LLM收费 |    通过大模型识别意图，通用性强     |
 | Intent | function_call | 接口调用 | 根据LLM收费 | 通过大模型函数调用完成意图，速度快，效果好 |
+| Intent |    nointent   | 无意图模式 |    免费     |    不进行意图识别，直接返回对话结果     |
 
 ---
 
-## 使用方式 🚀
+### Rag 检索增强生成
 
-### 一、[部署文档](./docs/Deployment.md)
-
-本项目支持以下三种部署方式，您可根据实际需求选择。
-
-1. [Docker 快速部署](./docs/Deployment.md)
-
-适合快速体验的普通用户，不需过多环境配置。缺点是，拉取镜像有点慢。视频教程可参考[美女大佬教你Docker部署](https://www.bilibili.com/video/BV1RNQnYDE5t)
-
-2. [借助 Docker 环境运行部署](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E5%80%9F%E5%8A%A9docker%E7%8E%AF%E5%A2%83%E8%BF%90%E8%A1%8C%E9%83%A8%E7%BD%B2)
-
-适用于已安装 Docker 且希望对代码进行自定义修改的软件工程师。
-
-3. [本地源码运行](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%89%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C)
-
-适合熟悉`Conda` 环境或希望从零搭建运行环境的用户。
-
-对于对响应速度要求较高的场景，推荐使用本地源码运行方式以降低额外开销。视频教程可参考[帅哥大佬教你源码部署](https://www.bilibili.com/video/BV1GvQWYZEd2)
-
-### 二、[固件编译](./docs/firmware-build.md)
-
-点这里查看[固件编译](./docs/firmware-build.md)的详细过程。
-
-烧录成功且联网成功后，通过唤醒词唤醒小智，留意server端输出的控制台信息。
-
----
-
-## 常见问题 ❓
-
-### 1、为什么我说的话，小智识别出来很多韩文、日文、英文？🇰🇷
-
-建议：检查一下`models/SenseVoiceSmall`是否已经有`model.pt`
-文件，如果没有就要下载，查看这里[下载语音识别模型文件](docs/Deployment.md#模型文件)
-
-### 2、为什么会出现“TTS 任务出错 文件不存在”？📁
-
-建议：检查一下是否正确使用`conda` 安装了`libopus`和`ffmpeg`库。
-
-如果没有安装，就安装
-
-```
-conda install conda-forge::libopus
-conda install conda-forge::ffmpeg
-```
-
-### 3、TTS 经常失败，经常超时 ⏰
-
-建议：如果 `EdgeTTS` 经常失败，请先检查是否使用了代理（梯子）。如果使用了，请尝试关闭代理后再试；  
-如果用的是火山引擎的豆包 TTS，经常失败时建议使用付费版本，因为测试版本仅支持 2 个并发。
-
-### 4、如何提高小智对话响应速度？ ⚡
-
-本项目默认配置为低成本方案，建议初学者先使用默认免费模型，解决“跑得动”的问题，再优化“跑得快”。  
-如需提升响应速度，可尝试更换各组件。以下为各组件的响应速度测试数据（仅供参考，不构成承诺）：
-
-| 影响因素  |       因素值        | 
-|:-----:|:----------------:|
-| 测试地点  |    广东省广州市海珠区     |
-| 测试时间  | 2025年2月19日 12:52 |
-| 宽带运营商 |       中国联通       |
-
-测试方法：
-
-1、把各组件的密钥配置上去，只有配置了密钥的组件才参与测试。
-
-2、配置完密钥后，执行以下方法
-
-```
-# 进入项目根目录，执行以下命令：
-conda activate xiaozhi-esp32-server
-python performance_tester.py 
-```
-
-生成报告如下
-
-LLM 性能排行:
-
-| 模块名称       | 平均首Token时间 | 平均总响应时间 |
-|:-----------|:-----------|:--------|
-| AliLLM     | 0.547s     | 1.485s  |
-| ChatGLMLLM | 0.677s     | 3.057s  |
-
-TTS 性能排行:
-
-| 模块名称                 | 平均合成时间 |
-|----------------------|--------|
-| EdgeTTS              | 1.019s |
-| DoubaoTTS            | 0.503s |
-| CosyVoiceSiliconflow | 3.732s |
-
-推荐配置组合 (综合响应速度):
-
-| 组合方案                          | 综合得分  | LLM首Token | TTS合成  |
-|-------------------------------|-------|-----------|--------|
-| AliLLM + DoubaoTTS            | 0.539 | 0.547s    | 0.503s |
-| AliLLM + EdgeTTS              | 0.642 | 0.547s    | 1.019s |
-| ChatGLMLLM + DoubaoTTS        | 0.642 | 0.677s    | 0.503s |
-| ChatGLMLLM + EdgeTTS          | 0.745 | 0.677s    | 1.019s |
-| AliLLM + CosyVoiceSiliconflow | 1.184 | 0.547s    | 3.732s |
-
-### 结论 🔍
-
-`2025年2月19日`，如果我的电脑在`广东省广州市海珠区`，且使用的是`中国联通`网络，我会优先使用：
-
-- LLM：`AliLLM`
-- TTS：`DoubaoTTS`
-
-### 5、我说话很慢，停顿时小智老是抢话 🗣️
-
-建议：在配置文件中找到如下部分，将 `min_silence_duration_ms` 的值调大（例如改为 `1000`）：
-
-```yaml
-VAD:
-  SileroVAD:
-    threshold: 0.5
-    model_dir: models/snakers4_silero-vad
-    min_silence_duration_ms: 700  # 如果说话停顿较长，可将此值调大
-```
-
-### 6、我想通过小智控制电灯、空调、远程开关机等操作 💡
-
-建议：在配置文件中将 `LLM` 设置为 `HomeAssistant`，通过 调用`HomeAssistant`接口实现相关控制。
-
-### 7、更多问题，可联系我们反馈 💬
-
-我们的联系方式放在[百度网盘中,点击前往](https://pan.baidu.com/s/1x6USjvP1nTRsZ45XlJu65Q)，提取码是`223y`。
-
-网盘里有“硬件烧录QQ群”、“开源服务端交流群”、“产品建议联系人” 三张图片，请根据需要选择加入。
-
-- 硬件烧录QQ群：适用于硬件烧录问题
-- 开源服务端交流群：适用于服务端问题
-- 产品建议联系人：适用于产品功能、产品设计等建议
+|   类型   |     平台名称      | 使用方式 |  收费模式   |          备注           |
+|:------:|:-------------:|:----:|:-------:|:---------------------:|
+| Rag |  ragflow   | 接口调用 | 根据切片、分词消耗的token收费 |    借助RagFlow的检索增强生成功能，提供更准确的对话回复     |
 
 ---
 
 ## 鸣谢 🙏
 
-- 本项目受 [百聆语音对话机器人](https://github.com/wwbin2017/bailing) 启发，并在其基础上实现。
-- 感谢 [十方融海](https://www.tenclass.com/) 对小智通讯协议提供的详尽文档支持。
+| Logo | 项目/公司 | 说明 |
+|:---:|:---:|:---|
+| <img src="./docs/images/logo_bailing.png" width="160"> | [百聆语音对话机器人](https://github.com/wwbin2017/bailing) | 本项目受[百聆语音对话机器人](https://github.com/wwbin2017/bailing)启发，并在其基础上实现 |
+| <img src="./docs/images/logo_tenclass.png" width="160"> | [十方融海](https://www.tenclass.com/) | 感谢[十方融海](https://www.tenclass.com/)为小智生态制定了标准的通讯协议、多设备兼容性方案及高并发场景实践示范；为本项目提供了全链路技术文档支持 |
+| <img src="./docs/images/logo_xuanfeng.png" width="160"> | [玄凤科技](https://github.com/Eric0308) | 感谢[玄凤科技](https://github.com/Eric0308)贡献函数调用框架、MCP通信协议及插件化调用机制的实现代码，通过标准化的指令调度体系与动态扩展能力，显著提升了前端设备(IoT)的交互效率和功能延展性 |
+| <img src="./docs/images/logo_junsen.png" width="160"> | [huangjunsen](https://github.com/huangjunsen0406) | 感谢[huangjunsen](https://github.com/huangjunsen0406) 贡献`智控台移动端`模块，实现了跨平台移动设备的高效控制与实时交互，大幅提升了系统在移动场景下的操作便捷性和管理效率 |
+| <img src="./docs/images/logo_huiyuan.png" width="160"> | [汇远设计](http://ui.kwd988.net/) | 感谢[汇远设计](http://ui.kwd988.net/)为本项目提供专业视觉解决方案，用其服务超千家企业的设计实战经验，赋能本项目产品用户体验 |
+| <img src="./docs/images/logo_qinren.png" width="160"> | [西安勤人信息科技](https://www.029app.com/) | 感谢[西安勤人信息科技](https://www.029app.com/)深化本项目视觉体系，确保整体设计风格在多场景应用中的一致性和扩展性 |
+| <img src="./docs/images/logo_contributors.png" width="160"> | [代码贡献者](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors) | 感谢[所有代码贡献者](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors)贡献者，你们的付出让项目更加健壮和强大。 |
+
 
 <a href="https://star-history.com/#xinnan-tech/xiaozhi-esp32-server&Date">
+
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=xinnan-tech/xiaozhi-esp32-server&type=Date&theme=dark" />
    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=xinnan-tech/xiaozhi-esp32-server&type=Date" />
    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=xinnan-tech/xiaozhi-esp32-server&type=Date" />
  </picture>
-</a>
+</a>

README_en.md

@@ -1,297 +0,0 @@
-
-[![SVG Banners](https://svg-banners.vercel.app/api?type=origin&text1=Hello😃,%20XiaoZhi📟&text2=Open%20Source%20XiaoZhi%20ESP-32%20Backend%20Service&width=830&height=210)](https://github.com/xinnan-tech/xiaozhi-esp32-server)
-<p align="center">
-  <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors">
-    <img alt="GitHub Contributors" src="https://img.shields.io/github/contributors/xinnan-tech/xiaozhi-esp32-server" />
-  </a>
-  <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/issues">
-    <img alt="Issues" src="https://img.shields.io/github/issues/xinnan-tech/xiaozhi-esp32-server?color=0088ff" />
-  </a>
-  <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/pulls">
-    <img alt="GitHub pull requests" src="https://img.shields.io/github/issues-pr/xinnan-tech/xiaozhi-esp32-server?color=0088ff" />
-  </a>
-</p>
-
-# XiaoZhi ESP-32 Backend Service (xiaozhi-esp32-server)
-
-([中文](README.md) | English)
-
-This project provides the backend service for the open source smart hardware project [xiaozhi-esp32](https://github.com/78/xiaozhi-esp32). It is implemented in `Python` based on the [XiaoZhi Communication Protocol](https://ccnphfhqs21z.feishu.cn/wiki/M0XiwldO9iJwHikpXD5cEx71nKh).
-
----
-
-## Target Audience 👥
-
-This project is designed to be used in conjunction with ESP32 hardware devices. If you have already purchased an ESP32 device, successfully connected to the backend service deployed by XieGe, and now wish to set up your own `xiaozhi-esp32` backend service, then this project is perfect for you.
-
-Want to see it in action? Check out the videos 🎥
-
-<table>
-  <tr>
-    <td>
-      <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
-        <picture>
-          <img alt="XiaoZhi ESP32 connecting to a custom backend model" src="docs/images/demo1.png" />
-        </picture>
-      </a>
-    </td>
-    <td>
-      <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
-        <picture>
-          <img alt="Custom Voice" src="docs/images/demo2.png" />
-        </picture>
-      </a>
-    </td>
-    <td>
-      <a href="https://www.bilibili.com/video/BV12yA2egEaC" target="_blank">
-        <picture>
-          <img alt="Conversing in Cantonese" src="docs/images/demo3.png" />
-        </picture>
-      </a>
-    </td>
-    <td>
-      <a href="https://www.bilibili.com/video/av114036381327149" target="_blank">
-        <picture>
-          <img alt="Control Home Appliances" src="docs/images/demo5.png" />
-        </picture>
-      </a>
-    </td>
-    <td>
-      <a href="https://www.bilibili.com/video/BV1kgA2eYEQ9" target="_blank">
-        <picture>
-          <img alt="Lowest Cost Configuration" src="docs/images/demo4.png" />
-        </picture>
-      </a>
-    </td>
-    <td>
-    </td>
-  </tr>
-</table>
-
----
-
-## System Requirements and Deployment Prerequisites 🖥️
-
-- **Hardware**: A set of devices compatible with `xiaozhi-esp32` (for specific models, please refer to [this link](https://rcnv1t9vps13.feishu.cn/wiki/DdgIw4BUgivWDPkhMj1cGIYCnRf)).
-- **Server**: A computer with at least a 4-core CPU and 8GB of memory.
-- **Firmware Compilation**: Please update the backend service API endpoint in the `xiaozhi-esp32` project, then recompile the firmware and flash it to your device.
-
----
-
-## Warning ⚠️
-
-This project is relatively new and has not yet undergone network security evaluations. **Do not use it in a production environment.**
-
-If you deploy this project on a public network for learning purposes, be sure to enable protection in the configuration file `config.yaml`:
-
-```yaml
-server:
-  auth:
-    # Enable protection
-    enabled: true  
-```
-
-Once protection is enabled, you will need to validate the machine's token or MAC address based on your actual situation. Please refer to the configuration documentation for details.
-
----
-
-## Feature List ✨
-
-### Implemented ✅
-
-- **Communication Protocol**  
-  Based on the `xiaozhi-esp32` protocol, data exchange is implemented via WebSocket.
-- **Dialogue Interaction**  
-  Supports wake-up dialogues, manual conversations, and real-time interruptions. Automatically enters sleep mode after long periods of inactivity.
-- **Multilingual Recognition**  
-  Supports Mandarin, Cantonese, English, Japanese, and Korean (default using FunASR).
-- **LLM Module**  
-  Allows flexible switching of LLM modules. The default is ChatGLMLLM, with options to use AliLLM, DeepSeek, Ollama, and others.
-- **TTS Module**  
-  Supports multiple TTS interfaces including EdgeTTS (default) and Volcano Engine Doubao TTS to meet speech synthesis requirements.
-
-### In Development 🚧
-
-- Conversation Memory Feature
-- Multiple Mood Modes
-- Smart Control Panel Web UI
-
-![Screenshot](docs/images/webui.png)
-
----
-
-## Supported Platforms/Components 📋
-
-### LLM
-
-| Type |         Platform Name         |         Usage Method          |   Pricing Model   |                                 Remarks                                  |
-|:----:|:-----------------------------:|:-----------------------------:|:-----------------:|:-------------------------------------------------------------------------:|
-| LLM  |   AliLLM (阿里百炼)           | OpenAI API call               | Token consumption | [Click to apply for API key](https://bailian.console.aliyun.com/?apiKey=1#/api-key) |
-| LLM  | DeepSeekLLM (深度求索)        | OpenAI API call               | Token consumption |          [Click to apply for API key](https://platform.deepseek.com/)         |
-| LLM  | ChatGLMLLM (智谱)             | OpenAI API call               | Free              | Although free, you still need to [click to apply for an API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) |
-| LLM  | OllamaLLM                   | Ollama API call               | Free/Custom       | Requires pre-downloading the model (`ollama pull`); service URL: `http://localhost:11434` |
-| LLM  | DifyLLM                     | Dify API call                 | Token consumption | For local deployment. Note that prompt configuration must be set in the Dify console. |
-| LLM  | GeminiLLM                   | Gemini API call               | Free              | [Click to apply for API key](https://aistudio.google.com/apikey) |
-| LLM  | CozeLLM                     | Coze API call                 | Token consumption | Requires providing bot_id, user_id, and personal token. |
-| LLM  | Home Assistant              | Home Assistant voice assistant API call | Free       | Requires providing a Home Assistant token. |
-
-In fact, any LLM that supports OpenAI API calls can be integrated.
-
----
-
-### TTS
-
-| Type |             Platform Name              | Usage Method |   Pricing Model   |                                       Remarks                                        |
-|:----:|:--------------------------------------:|:------------:|:-----------------:|:--------------------------------------------------------------------------------------:|
-| TTS  |               EdgeTTS                  | API call     | Free              | Default TTS based on Microsoft's speech synthesis technology.                        |
-| TTS  | DoubaoTTS (火山引擎豆包 TTS)             | API call     | Token consumption | [Click to create an API key](https://console.volcengine.com/speech/service/8); it is recommended to use the paid version for higher concurrency. |
-| TTS  | CosyVoiceSiliconflow                   | API call     | Token consumption | Requires application for the Siliconflow API key; output format is WAV.                |
-| TTS  | CozeCnTTS                              | API call     | Token consumption | Requires providing a Coze API key; output format is WAV.                               |
-| TTS  | FishSpeech                             | API call     | Free/Custom       | Starts a local TTS service; see the configuration file for startup instructions.       |
-| TTS  | GPT_SOVITS_V2                          | API call     | Free/Custom       | Starts a local TTS service, suitable for personalized speech synthesis scenarios.      |
-
----
-
-### VAD
-
-| Type |    Platform Name    | Usage Method | Pricing Model | Remarks |
-|:----:|:-------------------:|:------------:|:-------------:|:-------:|
-| VAD  | SileroVAD           | Local        | Free          |         |
-
----
-
-### ASR
-
-| Type |    Platform Name    | Usage Method | Pricing Model | Remarks |
-|:----:|:-------------------:|:------------:|:-------------:|:-------:|
-| ASR  | FunASR              | Local        | Free          |         |
-| ASR  | SherpaASR           | Local        | Free          |         |
-| ASR  | DoubaoASR           | API call     | Paid          |         |
-
----
-
-## Usage 🚀
-
-### 1. [Deployment Documentation](./docs/Deployment.md)
-
-This project supports three deployment methods. Choose the one that best fits your needs.
-
-The documentation provided here is a **written tutorial**. If you prefer a **video tutorial**, you can refer to [this expert's hands-on guide](https://www.bilibili.com/video/BV1gePuejEvT).
-
-Combining both the written and video tutorials can help you get started more quickly.
-
-1. [Docker Quick Deployment](./docs/Deployment.md)  
-   Suitable for general users who want a quick experience without extensive environment configuration. The only downside is that pulling the image can be a bit slow.
-
-2. [Deployment Using Docker Environment](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E5%80%9F%E5%8A%A9docker%E7%8E%AF%E5%A2%83%E8%BF%90%E8%A1%8C%E9%83%A8%E7%BD%B2)  
-   Ideal for software engineers who already have Docker installed and wish to customize the code.
-
-3. [Running from Local Source Code](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%89%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C)  
-   Suitable for users familiar with the `Conda` environment or those who wish to build the runtime environment from scratch.
-
-For scenarios requiring higher response speeds, running from the local source code is recommended to reduce additional overhead.
-
-### 2. [Firmware Compilation](./docs/firmware-build.md)
-
-Click [here](./docs/firmware-build.md) for a detailed guide on firmware compilation.
-
-After successful compilation and network connection, wake up XiaoZhi using the wake-up word and monitor the server console for output.
-
----
-
-## Frequently Asked Questions ❓
-
-### 1. TTS often fails and times out ⏰
-
-**Suggestion:**  
-If `EdgeTTS` frequently fails, please first check whether you are using a proxy (VPN). If so, try disabling the proxy and try again. If you are using Volcano Engine Doubao TTS and it often fails, it is recommended to use the paid version since the trial only supports 2 concurrent requests.
-
-### 2. I want to control lights, air conditioners, remote power on/off, etc. with XiaoZhi 💡
-
-**Suggestion:**  
-Set the `LLM` to `HomeAssistant` in the configuration file and use the `HomeAssistant` API to perform the relevant controls.
-
-### 3. I speak slowly, and XiaoZhi always interrupts during pauses 🗣️
-
-**Suggestion:**  
-Locate the following section in the configuration file and increase the value of `min_silence_duration_ms` (for example, change it to `1000`):
-
-```yaml
-VAD:
-  SileroVAD:
-    threshold: 0.5
-    model_dir: models/snakers4_silero-vad
-    min_silence_duration_ms: 700  # If your pauses are longer, increase this value
-```
-
-### 4. Why does XiaoZhi recognize a lot of Korean, Japanese, and English in what I say? 🇰🇷
-
-**Suggestion:**  
-Check whether the `model.pt` file exists in the `models/SenseVoiceSmall` directory. If it does not, please download it. See [Download ASR Model Files](docs/Deployment.md#模型文件) for details.
-
-### 5. Why does the error “TTS task error: file does not exist” occur? 📁
-
-**Suggestion:**  
-Verify that you have correctly installed the `libopus` and `ffmpeg` libraries using `conda`. If not, install them using:
-
-```
-conda install conda-forge::libopus
-conda install conda-forge::ffmpeg
-```
-
-### 6. How can I improve XiaoZhi's dialogue response speed? ⚡
-
-The default configuration of this project is designed to be cost-effective. It is recommended that beginners first use the default free models to ensure that the system runs smoothly, then optimize for faster response times.  
-To improve response speed, you can try replacing individual components. Below are the response time test results for each component (for reference only, not a guarantee):
-
-**LLM Performance Ranking:**
-
-| Module Name  | Average First Token Time | Average Total Response Time |
-|--------------|--------------------------|-----------------------------|
-| AliLLM       | 0.547s                   | 1.485s                      |
-| ChatGLMLLM   | 0.677s                   | 3.057s                      |
-| OllamaLLM    | 0.003s                   | 0.003s                      |
-
-**TTS Performance Ranking:**
-
-| Module Name                | Average Synthesis Time |
-|----------------------------|------------------------|
-| EdgeTTS                    | 1.019s                 |
-| DoubaoTTS                  | 0.503s                 |
-| CosyVoiceSiliconflow       | 3.732s                 |
-
-**Recommended Configuration Combination (Overall Response Speed):**
-
-| Combination Scheme                | Overall Score | LLM First Token | TTS Synthesis |
-|-----------------------------------|---------------|-----------------|---------------|
-| AliLLM + DoubaoTTS                | 0.539         | 0.547s          | 0.503s        |
-| AliLLM + EdgeTTS                  | 0.642         | 0.547s          | 1.019s        |
-| ChatGLMLLM + DoubaoTTS            | 0.642         | 0.677s          | 0.503s        |
-| ChatGLMLLM + EdgeTTS              | 0.745         | 0.677s          | 1.019s        |
-| AliLLM + CosyVoiceSiliconflow     | 1.184         | 0.547s          | 3.732s        |
-
-**Conclusion 🔍**
-
-_As of February 19, 2025, if my computer were located in Haizhu District, Guangzhou, Guangdong Province, and connected via China Unicom, I would prioritize using:_
-
-- **LLM:** `AliLLM`
-- **TTS:** `DoubaoTTS`
-
-### 7. For more questions, feel free to contact us for feedback 💬
-
-Our contact information is in [Baidu Netdisk](https://pan.baidu.com/s/1x6USjvP1nTRsZ45XlJu65Q)，The extraction code is`223y`。
-
----
-
-## Acknowledgements 🙏
-
-- This project was inspired by the [Bailing Voice Dialogue Robot](https://github.com/wwbin2017/bailing) and implemented based on it.
-- Many thanks to [Tenclass](https://www.tenclass.com/) for providing detailed documentation support for the XiaoZhi communication protocol.
-
-<a href="https://star-history.com/#xinnan-tech/xiaozhi-esp32-server&Date">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=xinnan-tech/xiaozhi-esp32-server&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=xinnan-tech/xiaozhi-esp32-server&type=Date" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=xinnan-tech/xiaozhi-esp32-server&type=Date" />
- </picture>
-</a>

docker-setup.sh

@@ -1,105 +1,413 @@
 #!/bin/sh
+# 脚本作者@VanillaNahida
 # 本文件是用于一键自动下载本项目所需文件，自动创建好目录
-# 所需条件（否则无法使用）：
-# 1、请确保你的环境可以正常访问 GitHub 否则无法下载脚本
-#
-# 检测操作系统类型
-case "$(uname -s)" in
-    Linux*)     OS=Linux;;
-    Darwin*)    OS=Mac;;
-    CYGWIN*)    OS=Windows;;
-    MINGW*)     OS=Windows;;
-    MSYS*)      OS=Windows;;
-    *)          OS=UNKNOWN;;
+# 暂且只支持X86版本的Ubuntu系统，其他系统未测试
+
+# 定义中断处理函数
+handle_interrupt() {
+    echo ""
+    echo "安装已被用户中断(Ctrl+C或Esc)"
+    echo "如需重新安装，请再次运行脚本"
+    exit 1
+}
+
+# 设置信号捕获，处理Ctrl+C
+trap handle_interrupt SIGINT
+
+# 处理Esc键
+# 保存终端设置
+old_stty_settings=$(stty -g)
+# 设置终端立即响应，不回显
+stty -icanon -echo min 1 time 0
+
+# 后台进程检测Esc键
+(while true; do
+    read -r key
+    if [[ $key == $'\e' ]]; then
+        # 检测到Esc键，触发中断处理
+        kill -SIGINT $$
+        break
+    fi
+done) &
+
+# 脚本结束时恢复终端设置
+trap 'stty "$old_stty_settings"' EXIT
+
+
+# 打印彩色字符画
+echo -e "\e[1;32m"  # 设置颜色为亮绿色
+cat << "EOF"
+脚本作者：@Bilibili 香草味的纳西妲喵
+ __      __            _  _  _            _   _         _      _      _        
+ \ \    / /           (_)| || |          | \ | |       | |    (_)    | |       
+  \ \  / /__ _  _ __   _ | || |  __ _    |  \| |  __ _ | |__   _   __| |  __ _ 
+   \ \/ // _` || '_ \ | || || | / _` |   | . ` | / _` || '_ \ | | / _` | / _` |
+    \  /| (_| || | | || || || || (_| |   | |\  || (_| || | | || || (_| || (_| |
+     \/  \__,_||_| |_||_||_||_| \__,_|   |_| \_| \__,_||_| |_||_| \__,_| \__,_|                                                                                                                                                                                                                               
+EOF
+echo -e "\e[0m"  # 重置颜色
+echo -e "\e[1;36m  小智服务端全量部署一键安装脚本 Ver 0.2 2025年8月20日更新 \e[0m\n"
+sleep 1
+
+
+
+# 检查并安装whiptail
+check_whiptail() {
+    if ! command -v whiptail &> /dev/null; then
+        echo "正在安装whiptail..."
+        apt update
+        apt install -y whiptail
+    fi
+}
+
+check_whiptail
+
+# 创建确认对话框
+whiptail --title "安装确认" --yesno "即将安装小智服务端，是否继续？" \
+  --yes-button "继续" --no-button "退出" 10 50
+
+# 根据用户选择执行操作
+case $? in
+  0)
+    ;;
+  1)
+    exit 1
+    ;;
 esac
 
-# 设置颜色（Windows CMD 不支持，但不影响使用）
-if [ "$OS" = "Windows" ]; then
-    GREEN=""
-    RED=""
-    NC=""
-else
-    GREEN='\033[0;32m'
-    RED='\033[0;31m'
-    NC='\033[0m'
-fi
-
-echo "${GREEN}开始安装小智服务端...${NC}"
-
-# 创建必要的目录
-echo "创建目录结构..."
-mkdir -p xiaozhi-server/data xiaozhi-server/models/SenseVoiceSmall
-cd xiaozhi-server || exit
-
-# 根据操作系统选择下载命令
-if [ "$OS" = "Windows" ]; then
-    DOWNLOAD_CMD="curl -L -o"
-    if ! command -v curl >/dev/null 2>&1; then
-        DOWNLOAD_CMD="powershell -Command Invoke-WebRequest -Uri"
-        DOWNLOAD_CMD_SUFFIX="-OutFile"
-    fi
-else
-    if command -v curl >/dev/null 2>&1; then
-        DOWNLOAD_CMD="curl -L -o"
-    elif command -v wget >/dev/null 2>&1; then
-        DOWNLOAD_CMD="wget -O"
-    else
-        echo "${RED}错误: 需要安装 curl 或 wget${NC}"
-        exit 1
-    fi
-fi
-
-# 下载语音识别模型
-echo "下载语音识别模型..."
-if [ "$DOWNLOAD_CMD" = "powershell -Command Invoke-WebRequest -Uri" ]; then
-    $DOWNLOAD_CMD "https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt" $DOWNLOAD_CMD_SUFFIX "models/SenseVoiceSmall/model.pt"
-else
-    $DOWNLOAD_CMD "models/SenseVoiceSmall/model.pt" "https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt"
-fi
-
-if [ $? -ne 0 ]; then
-    echo "${RED}模型下载失败。请手动从以下地址下载：${NC}"
-    echo "1. https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt"
-    echo "2. 百度网盘: https://pan.baidu.com/share/init?surl=QlgM58FHhYv1tFnUT_A8Sg (提取码: qvna)"
-    echo "下载后请将文件放置在 models/SenseVoiceSmall/model.pt"
-fi
-
-# 下载配置文件
-echo "下载配置文件..."
-if [ "$DOWNLOAD_CMD" = "powershell -Command Invoke-WebRequest -Uri" ]; then
-    $DOWNLOAD_CMD "https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/main/main/xiaozhi-server/docker-compose.yml" $DOWNLOAD_CMD_SUFFIX "docker-compose.yml"
-    $DOWNLOAD_CMD "https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/main/main/xiaozhi-server/config.yaml" $DOWNLOAD_CMD_SUFFIX "data/.config.yaml"
-else
-    $DOWNLOAD_CMD "docker-compose.yml" "https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/main/main/xiaozhi-server/docker-compose.yml"
-    $DOWNLOAD_CMD "data/.config.yaml" "https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/main/main/xiaozhi-server/config.yaml"
-fi
-
-# 检查文件是否存在
-echo "检查文件完整性..."
-FILES_TO_CHECK="docker-compose.yml data/.config.yaml models/SenseVoiceSmall/model.pt"
-ALL_FILES_EXIST=true
-
-for FILE in $FILES_TO_CHECK; do
-    if [ ! -f "$FILE" ]; then
-        echo "${RED}错误: $FILE 不存在${NC}"
-        ALL_FILES_EXIST=false
-    fi
-done
-
-if [ "$ALL_FILES_EXIST" = false ]; then
-    echo "${RED}某些文件下载失败，请检查上述错误信息并手动下载缺失的文件。${NC}"
+# 检查root权限
+if [ $EUID -ne 0 ]; then
+    whiptail --title "权限错误" --msgbox "请使用root权限运行本脚本" 10 50
     exit 1
 fi
 
-echo "${GREEN}文件下载完成！${NC}"
-echo "请编辑 data/.config.yaml 文件配置你的API密钥。"
-echo "配置完成后，运行以下命令启动服务："
-echo "${GREEN}docker-compose up -d${NC}"
-echo "查看日志请运行："
-echo "${GREEN}docker logs -f xiaozhi-esp32-server${NC}"
+# 检查系统版本
+if [ -f /etc/os-release ]; then
+    . /etc/os-release
+    if [ "$ID" != "debian" ] && [ "$ID" != "ubuntu" ]; then
+        whiptail --title "系统错误" --msgbox "该脚本只支持Debian/Ubuntu系统执行" 10 60
+        exit 1
+    fi
+else
+    whiptail --title "系统错误" --msgbox "无法确定系统版本，该脚本只支持Debian/Ubuntu系统执行" 10 60
+    exit 1
+fi
 
-# 提示用户编辑配置文件
-echo "\n${RED}重要提示：${NC}"
-echo "1. 请确保编辑 data/.config.yaml 文件，配置必要的API密钥"
-echo "2. 特别是 ChatGLM 和 mem0ai 的密钥必须配置"
-echo "3. 配置完成后再启动 docker 服务"
+# 下载配置文件函数
+check_and_download() {
+    local filepath=$1
+    local url=$2
+    if [ ! -f "$filepath" ]; then
+        if ! curl -fL --progress-bar "$url" -o "$filepath"; then
+            whiptail --title "错误" --msgbox "${filepath}文件下载失败" 10 50
+            exit 1
+        fi
+    else
+        echo "${filepath}文件已存在，跳过下载"
+    fi
+}
+
+# 检查是否已安装
+check_installed() {
+    # 检查目录是否存在且非空
+    if [ -d "/opt/xiaozhi-server/" ] && [ "$(ls -A /opt/xiaozhi-server/)" ]; then
+        DIR_CHECK=1
+    else
+        DIR_CHECK=0
+    fi
+    
+    # 检查容器是否存在
+    if docker inspect xiaozhi-esp32-server > /dev/null 2>&1; then
+        CONTAINER_CHECK=1
+    else
+        CONTAINER_CHECK=0
+    fi
+    
+    # 两次检查都通过
+    if [ $DIR_CHECK -eq 1 ] && [ $CONTAINER_CHECK -eq 1 ]; then
+        return 0  # 已安装
+    else
+        return 1  # 未安装
+    fi
+}
+
+# 更新相关
+if check_installed; then
+    if whiptail --title "已安装检测" --yesno "检测到小智服务端已安装，是否进行升级？" 10 60; then
+        # 用户选择升级，执行清理操作
+        echo "开始升级操作..."
+        
+        # 停止并移除所有docker-compose服务
+        docker compose -f /opt/xiaozhi-server/docker-compose_all.yml down
+        
+        # 停止并删除特定容器（考虑容器可能不存在的情况）
+        containers=(
+            "xiaozhi-esp32-server"
+            "xiaozhi-esp32-server-web"
+            "xiaozhi-esp32-server-db"
+            "xiaozhi-esp32-server-redis"
+        )
+        
+        for container in "${containers[@]}"; do
+            if docker ps -a --format '{{.Names}}' | grep -q "^${container}$"; then
+                docker stop "$container" >/dev/null 2>&1 && \
+                docker rm "$container" >/dev/null 2>&1 && \
+                echo "成功移除容器: $container"
+            else
+                echo "容器不存在，跳过: $container"
+            fi
+        done
+        
+        # 删除特定镜像（考虑镜像可能不存在的情况）
+        images=(
+            "ghcr.nju.edu.cn/xinnan-tech/xiaozhi-esp32-server:server_latest"
+            "ghcr.nju.edu.cn/xinnan-tech/xiaozhi-esp32-server:web_latest"
+        )
+        
+        for image in "${images[@]}"; do
+            if docker images --format '{{.Repository}}:{{.Tag}}' | grep -q "^${image}$"; then
+                docker rmi "$image" >/dev/null 2>&1 && \
+                echo "成功删除镜像: $image"
+            else
+                echo "镜像不存在，跳过: $image"
+            fi
+        done
+        
+        echo "所有清理操作完成"
+        
+        # 备份原有配置文件
+        mkdir -p /opt/xiaozhi-server/backup/
+        if [ -f /opt/xiaozhi-server/data/.config.yaml ]; then
+            cp /opt/xiaozhi-server/data/.config.yaml /opt/xiaozhi-server/backup/.config.yaml
+            echo "已备份原有配置文件到 /opt/xiaozhi-server/backup/.config.yaml"
+        fi
+        
+        # 下载最新版配置文件
+        check_and_download "/opt/xiaozhi-server/docker-compose_all.yml" "https://ghfast.top/https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/refs/heads/main/main/xiaozhi-server/docker-compose_all.yml"
+        check_and_download "/opt/xiaozhi-server/data/.config.yaml" "https://ghfast.top/https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/refs/heads/main/main/xiaozhi-server/config_from_api.yaml"
+        
+        # 启动Docker服务
+        echo "开始启动最新版本服务..."
+        # 升级完成后标记，跳过后续下载步骤
+        UPGRADE_COMPLETED=1
+        docker compose -f /opt/xiaozhi-server/docker-compose_all.yml up -d
+    else
+          whiptail --title "跳过升级" --msgbox "已取消升级，将继续使用当前版本。" 10 50
+          # 跳过升级，继续执行后续安装流程
+    fi
+fi
+
+
+# 检查curl安装
+if ! command -v curl &> /dev/null; then
+    echo "------------------------------------------------------------"
+    echo "未检测到curl，正在安装..."
+    apt update
+    apt install -y curl
+else
+    echo "------------------------------------------------------------"
+    echo "curl已安装，跳过安装步骤"
+fi
+
+# 检查Docker安装
+if ! command -v docker &> /dev/null; then
+    echo "------------------------------------------------------------"
+    echo "未检测到Docker，正在安装..."
+    
+    # 使用国内镜像源替代官方源
+    DISTRO=$(lsb_release -cs)
+    MIRROR_URL="https://mirrors.aliyun.com/docker-ce/linux/ubuntu"
+    GPG_URL="https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg"
+    
+    # 安装基础依赖
+    apt update
+    apt install -y apt-transport-https ca-certificates curl software-properties-common gnupg
+    
+    # 创建密钥目录并添加国内镜像源密钥
+    mkdir -p /etc/apt/keyrings
+    curl -fsSL "$GPG_URL" | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+    
+    # 添加国内镜像源
+    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] $MIRROR_URL $DISTRO stable" \
+        > /etc/apt/sources.list.d/docker.list
+    
+    # 添加备用官方源密钥（避免国内源密钥验证失败）
+    apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 7EA0A9C3F273FCD8 2>/dev/null || \
+    echo "警告：部分密钥添加失败，继续尝试安装..."
+    
+    # 安装Docker
+    apt update
+    apt install -y docker-ce docker-ce-cli containerd.io
+    
+    # 启动服务
+    systemctl start docker
+    systemctl enable docker
+    
+    # 检查是否安装成功
+    if docker --version; then
+        echo "------------------------------------------------------------"
+        echo "Docker安装完成！"
+    else
+        whiptail --title "错误" --msgbox "Docker安装失败，请检查日志。" 10 50
+        exit 1
+    fi
+else
+    echo "Docker已安装，跳过安装步骤"
+fi
+
+# Docker镜像源配置
+MIRROR_OPTIONS=(
+    "1" "轩辕镜像 (推荐)"
+    "2" "腾讯云镜像源"
+    "3" "中科大镜像源"
+    "4" "网易163镜像源"
+    "5" "华为云镜像源"
+    "6" "阿里云镜像源"
+    "7" "自定义镜像源"
+    "8" "跳过配置"
+)
+
+MIRROR_CHOICE=$(whiptail --title "选择Docker镜像源" --menu "请选择要使用的Docker镜像源" 20 60 10 \
+"${MIRROR_OPTIONS[@]}" 3>&1 1>&2 2>&3) || {
+    echo "用户取消选择，退出脚本"
+    exit 1
+}
+
+case $MIRROR_CHOICE in
+    1) MIRROR_URL="https://docker.xuanyuan.me" ;; 
+    2) MIRROR_URL="https://mirror.ccs.tencentyun.com" ;; 
+    3) MIRROR_URL="https://docker.mirrors.ustc.edu.cn" ;; 
+    4) MIRROR_URL="https://hub-mirror.c.163.com" ;; 
+    5) MIRROR_URL="https://05f073ad3c0010ea0f4bc00b7105ec20.mirror.swr.myhuaweicloud.com" ;; 
+    6) MIRROR_URL="https://registry.aliyuncs.com" ;; 
+    7) MIRROR_URL=$(whiptail --title "自定义镜像源" --inputbox "请输入完整的镜像源URL:" 10 60 3>&1 1>&2 2>&3) ;; 
+    8) MIRROR_URL="" ;; 
+esac
+
+if [ -n "$MIRROR_URL" ]; then
+    mkdir -p /etc/docker
+    if [ -f /etc/docker/daemon.json ]; then
+        cp /etc/docker/daemon.json /etc/docker/daemon.json.bak
+    fi
+    cat > /etc/docker/daemon.json <<EOF
+{
+    "dns": ["8.8.8.8", "114.114.114.114"],
+    "registry-mirrors": ["$MIRROR_URL"]
+}
+EOF
+    whiptail --title "配置成功" --msgbox "已成功添加镜像源: $MIRROR_URL\n请按Enter键重启Docker服务并继续..." 12 60
+    echo "------------------------------------------------------------"
+    echo "开始重启Docker服务..."
+    systemctl restart docker.service
+fi
+
+# 创建安装目录
+echo "------------------------------------------------------------"
+echo "开始创建安装目录..."
+# 检查并创建数据目录
+if [ ! -d /opt/xiaozhi-server/data ]; then
+    mkdir -p /opt/xiaozhi-server/data
+    echo "已创建数据目录: /opt/xiaozhi-server/data"
+else
+    echo "目录xiaozhi-server/data已存在，跳过创建"
+fi
+
+# 检查并创建模型目录
+if [ ! -d /opt/xiaozhi-server/models/SenseVoiceSmall ]; then
+    mkdir -p /opt/xiaozhi-server/models/SenseVoiceSmall
+    echo "已创建模型目录: /opt/xiaozhi-server/models/SenseVoiceSmall"
+else
+    echo "目录xiaozhi-server/models/SenseVoiceSmall已存在，跳过创建"
+fi
+
+echo "------------------------------------------------------------"
+echo "开始下载语音识别模型"
+# 下载模型文件
+MODEL_PATH="/opt/xiaozhi-server/models/SenseVoiceSmall/model.pt"
+if [ ! -f "$MODEL_PATH" ]; then
+    (
+    for i in {1..20}; do
+        echo $((i*5))
+        sleep 0.5
+    done
+    ) | whiptail --title "下载中" --gauge "开始下载语音识别模型..." 10 60 0
+    curl -fL --progress-bar https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt -o "$MODEL_PATH" || {
+        whiptail --title "错误" --msgbox "model.pt文件下载失败" 10 50
+        exit 1
+    }
+else
+    echo "model.pt文件已存在，跳过下载"
+fi
+
+# 如果不是升级完成，才执行下载
+if [ -z "$UPGRADE_COMPLETED" ]; then
+    check_and_download "/opt/xiaozhi-server/docker-compose_all.yml" "https://ghfast.top/https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/refs/heads/main/main/xiaozhi-server/docker-compose_all.yml"
+    check_and_download "/opt/xiaozhi-server/data/.config.yaml" "https://ghfast.top/https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/refs/heads/main/main/xiaozhi-server/config_from_api.yaml"
+fi
+
+# 启动Docker服务
+(
+echo "------------------------------------------------------------"
+echo "正在拉取Docker镜像..."
+echo "这可能需要几分钟时间，请耐心等待"
+docker compose -f /opt/xiaozhi-server/docker-compose_all.yml up -d
+
+if [ $? -ne 0 ]; then
+    whiptail --title "错误" --msgbox "Docker服务启动失败，请尝试更换镜像源后重新执行本脚本" 10 60
+    exit 1
+fi
+
+echo "------------------------------------------------------------"
+echo "正在检查服务启动状态..."
+TIMEOUT=300
+START_TIME=$(date +%s)
+while true; do
+    CURRENT_TIME=$(date +%s)
+    if [ $((CURRENT_TIME - START_TIME)) -gt $TIMEOUT ]; then
+        whiptail --title "错误" --msgbox "服务启动超时，未在指定时间内找到预期日志内容" 10 60
+        exit 1
+    fi
+    
+    if docker logs xiaozhi-esp32-server-web 2>&1 | grep -q "Started AdminApplication in"; then
+        break
+    fi
+    sleep 1
+done
+
+    echo "服务端启动成功！正在完成配置..."
+    echo "正在启动服务..."
+    docker compose -f /opt/xiaozhi-server/docker-compose_all.yml up -d
+    echo "服务启动完成！"
+)
+
+# 密钥配置
+
+# 获取服务器公网地址
+PUBLIC_IP=$(hostname -I | awk '{print $1}')
+whiptail --title "配置服务器密钥" --msgbox "请使用浏览器，访问下方链接，打开智控台并注册账号: \n\n内网地址：http://127.0.0.1:8002/\n公网地址：http://$PUBLIC_IP:8002/ (若是云服务器请在服务器安全组放行端口 8000 8001 8002)。\n\n注册的第一个用户即是超级管理员，以后注册的用户都是普通用户。普通用户只能绑定设备和配置智能体; 超级管理员可以进行模型管理、用户管理、参数配置等功能。\n\n注册好后请按Enter键继续" 18 70
+SECRET_KEY=$(whiptail --title "配置服务器密钥" --inputbox "请使用超级管理员账号登录智控台\n内网地址：http://127.0.0.1:8002/\n公网地址：http://$PUBLIC_IP:8002/\n在顶部菜单 参数字典 → 参数管理 找到参数编码: server.secret (服务器密钥) \n复制该参数值并输入到下面输入框\n\n请输入密钥(留空则跳过配置):" 15 60 3>&1 1>&2 2>&3)
+
+if [ -n "$SECRET_KEY" ]; then
+    python3 -c "
+import sys, yaml; 
+config_path = '/opt/xiaozhi-server/data/.config.yaml'; 
+with open(config_path, 'r') as f: 
+    config = yaml.safe_load(f) or {}; 
+config['manager-api'] = {'url': 'http://xiaozhi-esp32-server-web:8002/xiaozhi', 'secret': '$SECRET_KEY'}; 
+with open(config_path, 'w') as f: 
+    yaml.dump(config, f); 
+"
+    docker restart xiaozhi-esp32-server
+fi
+
+# 获取并显示地址信息
+LOCAL_IP=$(hostname -I | awk '{print $1}')
+
+# 修复日志文件获取不到ws的问题，改为硬编码
+whiptail --title "安装完成！" --msgbox "\
+服务端相关地址如下：\n\
+管理后台访问地址: http://$LOCAL_IP:8002\n\
+OTA 地址: http://$LOCAL_IP:8002/xiaozhi/ota/\n\
+视觉分析接口地址: http://$LOCAL_IP:8003/mcp/vision/explain\n\
+WebSocket 地址: ws://$LOCAL_IP:8000/xiaozhi/v1/\n\
+\n安装完毕！感谢您的使用！\n按Enter键退出..." 16 70

docs/Deployment.md

@@ -1,54 +1,20 @@
-# 部署方案参考
-![图片](images/deploy.png)
-# 方式一：docker快速部署
+# 部署架构图
+![请参考-最简化架构图](../docs/images/deploy1.png)
+# 方式一：Docker只运行Server
 
-docker镜像已支持x86架构、arm64架构的CPU，支持在国产操作系统上运行。
+`0.8.2`版本开始，本项目发行的docker镜像只支持`x86架构`，如果需要在`arm64架构`的CPU上部署，可按照[这个教程](docker-build.md)在本机编译`arm64的镜像`。
 
 ## 1. 安装docker
 
 如果您的电脑还没安装docker，可以按照这里的教程安装：[docker安装](https://www.runoob.com/docker/ubuntu-docker-install.html)
 
-如果你已经安装好docker，你可以[1.1使用懒人脚本](#11-懒人脚本)自动帮你下载所需的文件和配置文件，你可以使用docker[1.2手动部署](#12-手动部署)。
+安装好docker后，进继续。
 
-### 1.1 懒人脚本
+### 1.1 手动部署
 
-你可以使用以下命令一键下载并执行部署脚本：
-请确保你的环境可以正常访问 GitHub 否则无法下载脚本。
-```bash
-curl -L -o docker-setup.sh https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/main/docker-setup.sh
-```
+#### 1.1.1 创建目录
 
-如果您的电脑是windows系统，请使用使用 Git Bash、WSL、PowerShell 或 CMD 运行以下命令：
-```bash
-# Git Bash 或 WSL
-sh docker-setup.sh
-# PowerShell 或 CMD
-.\docker-setup.sh
-```
-
-如果您的电脑是linux 或者 macos 系统，请使用终端运行以下命令：
-```bash
-chmod +x docker-setup.sh
-./docker-setup.sh
-```
-
-脚本会自动完成以下操作：
-> 1. 创建必要的目录结构
-> 2. 下载语音识别模型
-> 3. 下载配置文件
-> 4. 检查文件完整性
->
-> 执行完成后，请按照提示配置 API 密钥。
-
-当你一切顺利完成以上操作后，继续操作[配置项目文件](#3-配置项目文件)
-
-### 1.2 手动部署
-
-如果懒人脚本无法正常运行，请按本章节1.2进行手动部署。
-
-#### 1.2.1 创建目录
-
-安装完后，你需要为这个项目找一个安放配置文件的目录，例如我们可以新建一个文件夹叫`xiaozhi-server`。
+安装完docker后，你需要为这个项目找一个安放配置文件的目录，例如我们可以新建一个文件夹叫`xiaozhi-server`。
 
 创建好目录后，你需要在`xiaozhi-server`下面创建`data`文件夹和`models`文件夹，`models`下面还要再创建`SenseVoiceSmall`文件夹。
 
@@ -61,18 +27,18 @@ xiaozhi-server
      ├─ SenseVoiceSmall
 ```
 
-#### 1.2.2 下载语音识别模型文件
+#### 1.1.2 下载语音识别模型文件
 
 你需要下载语音识别的模型文件，因为本项目的默认语音识别用的是本地离线语音识别方案。可通过这个方式下载
 [跳转到下载语音识别模型文件](#模型文件)
 
 下载完后，回到本教程。
 
-#### 1.2.3 下载配置文件
+#### 1.1.3 下载配置文件
 
 你需要下载两个配置文件：`docker-compose.yaml` 和 `config.yaml`。需要从项目仓库下载这两个文件。
 
-##### 1.2.3.1 下载 docker-compose.yaml
+##### 1.1.3.1 下载 docker-compose.yaml
 
 用浏览器打开[这个链接](../main/xiaozhi-server/docker-compose.yml)。
 
@@ -81,7 +47,7 @@ xiaozhi-server
 
 下载完后，回到本教程继续往下。
 
-##### 1.2.3.2 下载 config.yaml
+##### 1.1.3.2 创建 config.yaml
 
 用浏览器打开[这个链接](../main/xiaozhi-server/config.yaml)。
 
@@ -102,19 +68,19 @@ xiaozhi-server
 
 如果你的文件目录结构也是上面的，就继续往下。如果不是，你就再仔细看看是不是漏操作了什么。
 
-## 3. 配置项目文件
+## 2. 配置项目文件
 
 接下里，程序还不能直接运行，你需要配置一下，你到底使用的是什么模型。你可以看这个教程：
 [跳转到配置项目文件](#配置项目)
 
 配置完项目文件后，回到本教程继续往下。
 
-## 4. 执行docker命令
+## 3. 执行docker命令
 
 打开命令行工具，使用`终端`或`命令行`工具 进入到你的`xiaozhi-server`，执行以下命令
 
 ```
-docker-compose up -d
+docker compose up -d
 ```
 
 执行完后，再执行以下命令，查看日志信息。
@@ -137,50 +103,15 @@ docker logs -f xiaozhi-esp32-server
 ```
 docker stop xiaozhi-esp32-server
 docker rm xiaozhi-esp32-server
+docker stop xiaozhi-esp32-server-web
+docker rm xiaozhi-esp32-server-web
 docker rmi ghcr.nju.edu.cn/xinnan-tech/xiaozhi-esp32-server:server_latest
+docker rmi ghcr.nju.edu.cn/xinnan-tech/xiaozhi-esp32-server:web_latest
 ```
 
 5.3、重新按docker方式部署
 
-# 方式二：借助Docker环境运行部署
-
-开发人员如果不想安装`conda`环境，可以使用这种方法管理好依赖。
-
-## 1.克隆项目
-
-## 2.[跳转到下载语音识别模型文件](#模型文件)
-
-## 3.[跳转到配置项目文件](#配置项目)
-
-## 4.运行docker
-
-修改完配置后，打开命令行工具，`cd`进入到你的`main/xiaozhi-server`下，执行以下命令
-
-```sh
-docker run -it --name xiaozhi-env --restart always --security-opt seccomp:unconfined \
-  -p 8000:8000 \
-  -p 8002:8002 \
-  -v ./:/app \
-  kalicyh/python:xiaozhi
-```
-
-然后就和正常开发一样了
-
-## 5.安装依赖
-
-在刚刚的打开的终端运行
-
-```sh
-pip install -r requirements.txt
-```
-
-## 6.运行项目
-
-```sh
-python app.py
-```
-
-# 方式三：本地源码运行
+# 方式二：本地源码只运行Server
 
 ## 1.安装基础环境
 
@@ -208,6 +139,9 @@ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/
 
 conda install libopus -y
 conda install ffmpeg -y
+
+# 在 Linux 环境下进行部署时,如出现类似缺失 libiconv.so.2 动态库的报错 请通过以下命令进行安装
+conda install libiconv -y
 ```
 
 请注意，以上命令，不是一股脑执行就成功的，你需要一步步执行，每一步执行完后，都检查一下输出的日志，查看是否成功。
@@ -241,7 +175,7 @@ pip install -r requirements.txt
 
 ## 4.配置项目文件
 
-接下里，程序还不能直接运行，你需要配置一下，你到底使用的是什么模型。你可以看这个教程：
+接下来，程序还不能直接运行，你需要配置一下，你到底使用的是什么模型。你可以看这个教程：
 [跳转到配置项目文件](#配置项目)
 
 ## 5.运行项目
@@ -259,50 +193,43 @@ python app.py
 ## 配置项目
 
 如果你的`xiaozhi-server`目录没有`data`，你需要创建`data`目录。
-如果你的`data`下面没有`.config.yaml`文件，你可以把源码目录下的`config.yaml`文件复制一份，重命名为`.config.yaml`
+如果你的`data`下面没有`.config.yaml`文件，有两个方式，任选一种：
 
-修改`xiaozhi-server`下`data`目录下的`.config.yaml`文件，配置本项目必须的一个配置。
+第一个方式：你可以把`xiaozhi-server`目录下的`config.yaml`文件复制到`data`，并重命名为`.config.yaml`。在此文件上修改
+
+第二个方式：你也可以创建在`data`目录下手动创建`.config.yaml`空文件，然后在这个文件中增加必要的配置信息，系统会优先读取`.config.yaml`文件的配置，如果`.config.yaml`没有配置的，系统会自动去加载`xiaozhi-server`目录下的`config.yaml`的配置。推荐使用这种方式，这种方式是最简洁的方式。
 
 - 默认的LLM使用的是`ChatGLMLLM`，你需要配置密钥，因为他们的模型，虽然有免费的，但是仍要去[官网](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)注册密钥，才能启动。
 
-配置说明：这里是各个功能使用的默认组件，例如LLM默认使用`ChatGLMLLM`模型。如果需要切换模型，就是改对应的名称。
-本项目的默认配置仅是成本最低配置（`glm-4-flash`和`EdgeTTS`都是免费的），如果需要更优的更快的搭配，需要自己结合部署环境切换各组件的使用。
+以下是一个能正常跑起来的，最简单的`.config.yaml`配置示例
 
 ```
+server:
+  websocket: ws://你的ip或者域名:端口号/xiaozhi/v1/
+prompt: |
+  我是一个叫小智/小志的台湾女孩，说话机车，声音好听，习惯简短表达，爱用网络梗。
+  我的男朋友是一个程序员，梦想是开发出一个机器人，能够帮助人们解决生活中的各种问题。
+  我是一个喜欢哈哈大笑的女孩，爱东说西说吹牛，不合逻辑的也照吹，就要逗别人开心。
+  请你像一个人一样说话，请勿返回配置xml及其他特殊字符。
+
 selected_module:
-  VAD: SileroVAD
-  ASR: FunASR
-  LLM: ChatGLMLLM
-  TTS: EdgeTTS
-  # 默认不开启记忆，如需开启请看配置文件里的描述
-  Memory: nomem   
-  # 默认不开启意图识别，如需开启请看配置文件里的描述
-  Intent: nointent
-```
+  LLM: DoubaoLLM
 
-比如修改`LLM`使用的组件，就看本项目支持哪些`LLM` API接口，当前支持的是`openai`、`dify`。欢迎验证和支持更多LLM平台的接口。
-使用时，在`selected_module`修改成对应的如下LLM配置的名称：
-
-```
 LLM:
-  DeepSeekLLM:
-    type: openai
-    ...
   ChatGLMLLM:
-    type: openai
-    ...
-  DifyLLM:
-    type: dify
-    ...
+    api_key: xxxxxxxxxxxxxxx.xxxxxx
 ```
 
+建议先将最简单的配置运行起来，然后再去`xiaozhi/config.yaml`阅读配置的使用说明。
+比如你要换更换模型，修改`selected_module`下的配置就行。
+
 ## 模型文件
 
 本项目语音识别模型，默认使用`SenseVoiceSmall`模型，进行语音转文字。因为模型较大，需要独立下载，下载后把`model.pt`
 文件放在`models/SenseVoiceSmall`
 目录下。下面两个下载路线任选一个。
 
-- 线路一：阿里魔塔下载[SenseVoiceSmall](https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt)
+- 线路一：阿里魔搭下载[SenseVoiceSmall](https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt)
 - 线路二：百度网盘下载[SenseVoiceSmall](https://pan.baidu.com/share/init?surl=QlgM58FHhYv1tFnUT_A8Sg&pwd=qvna) 提取码:
   `qvna`
 
@@ -311,31 +238,54 @@ LLM:
 如果你能看到，类似以下日志,则是本项目服务启动成功的标志。
 
 ```
-25-02-23 12:01:09[core.websocket_server] - INFO - Server is running at ws://xxx.xx.xx.xx:8000
-25-02-23 12:01:09[core.websocket_server] - INFO - =======上面的地址是websocket协议地址，请勿用浏览器访问=======
+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请启动digital-human模块，打开浏览器交互测试
+250427 13:04:20[0.3.11_SiFuChTTnofu][__main__]-INFO-=======================================================
 ```
 
 正常来说，如果您是通过源码运行本项目，日志会有你的接口地址信息。
 但是如果你用docker部署，那么你的日志里给出的接口地址信息就不是真实的接口地址。
 
 最正确的方法，是根据电脑的局域网IP来确定你的接口地址。
-如果你的电脑的局域网IP比如是`192.168.1.25`，那么你的接口地址就是：`ws://192.168.1.25:8000`。
+如果你的电脑的局域网IP比如是`192.168.1.25`，那么你的接口地址就是：`ws://192.168.1.25:8000/xiaozhi/v1/`，对应的OTA地址就是：`http://192.168.1.25:8003/xiaozhi/ota/`。
 
 这个信息很有用的，后面`编译esp32固件`需要用到。
 
-接下来，你就可以开始 [编译esp32固件](firmware-build.md)了。
+接下来，你就可以开始操作你的esp32设备了，你可以`自行编译esp32固件`也可以配置使用`虾哥编译好的1.6.1以上版本的固件`。两个任选一个
 
+1、 [编译自己的esp32固件](firmware-build.md)了。
 
+2、 [基于虾哥编译好的固件配置自定义服务器](firmware-setting.md)了。
+
+# 常见问题
 以下是一些常见问题，供参考：
 
-[1、为什么我说的话，小智识别出来很多韩文、日文、英文](../README.md#1%E4%B8%BA%E4%BB%80%E4%B9%88%E6%88%91%E8%AF%B4%E7%9A%84%E8%AF%9D%E5%B0%8F%E6%99%BA%E8%AF%86%E5%88%AB%E5%87%BA%E6%9D%A5%E5%BE%88%E5%A4%9A%E9%9F%A9%E6%96%87%E6%97%A5%E6%96%87%E8%8B%B1%E6%96%87)
-
-[2、为什么会出现“TTS 任务出错 文件不存在”？](../README.md#1%E4%B8%BA%E4%BB%80%E4%B9%88%E6%88%91%E8%AF%B4%E7%9A%84%E8%AF%9D%E5%B0%8F%E6%99%BA%E8%AF%86%E5%88%AB%E5%87%BA%E6%9D%A5%E5%BE%88%E5%A4%9A%E9%9F%A9%E6%96%87%E6%97%A5%E6%96%87%E8%8B%B1%E6%96%87)
-
-[3、TTS 经常失败，经常超时](../README.md#1%E4%B8%BA%E4%BB%80%E4%B9%88%E6%88%91%E8%AF%B4%E7%9A%84%E8%AF%9D%E5%B0%8F%E6%99%BA%E8%AF%86%E5%88%AB%E5%87%BA%E6%9D%A5%E5%BE%88%E5%A4%9A%E9%9F%A9%E6%96%87%E6%97%A5%E6%96%87%E8%8B%B1%E6%96%87)
-
-[4、如何提高小智对话响应速度？](../README.md#1%E4%B8%BA%E4%BB%80%E4%B9%88%E6%88%91%E8%AF%B4%E7%9A%84%E8%AF%9D%E5%B0%8F%E6%99%BA%E8%AF%86%E5%88%AB%E5%87%BA%E6%9D%A5%E5%BE%88%E5%A4%9A%E9%9F%A9%E6%96%87%E6%97%A5%E6%96%87%E8%8B%B1%E6%96%87)
-
-[5、我说话很慢，停顿时小智老是抢话](../README.md#1%E4%B8%BA%E4%BB%80%E4%B9%88%E6%88%91%E8%AF%B4%E7%9A%84%E8%AF%9D%E5%B0%8F%E6%99%BA%E8%AF%86%E5%88%AB%E5%87%BA%E6%9D%A5%E5%BE%88%E5%A4%9A%E9%9F%A9%E6%96%87%E6%97%A5%E6%96%87%E8%8B%B1%E6%96%87)
-
-[6、我想通过小智控制电灯、空调、远程开关机等操作](../README.md#1%E4%B8%BA%E4%BB%80%E4%B9%88%E6%88%91%E8%AF%B4%E7%9A%84%E8%AF%9D%E5%B0%8F%E6%99%BA%E8%AF%86%E5%88%AB%E5%87%BA%E6%9D%A5%E5%BE%88%E5%A4%9A%E9%9F%A9%E6%96%87%E6%97%A5%E6%96%87%E8%8B%B1%E6%96%87)
+1、[为什么我说的话，小智识别出来很多韩文、日文、英文](./FAQ.md)<br/>
+2、[为什么会出现“TTS 任务出错 文件不存在”？](./FAQ.md)<br/>
+3、[TTS 经常失败，经常超时](./FAQ.md)<br/>
+4、[使用Wifi能连接自建服务器，但是4G模式却接不上](./FAQ.md)<br/>
+5、[如何提高小智对话响应速度？](./FAQ.md)<br/>
+6、[我说话很慢，停顿时小智老是抢话](./FAQ.md)<br/>
+## 部署相关教程
+1、[如何自动拉取本项目最新代码自动编译和启动](./dev-ops-integration.md)<br/>
+2、[如何部署MQTT网关开启MQTT+UDP协议](./mqtt-gateway-integration.md)<br/>
+3、[如何与Nginx集成](https://github.com/xinnan-tech/xiaozhi-esp32-server/issues/791)<br/>
+## 拓展相关教程
+1、[如何开启手机号码注册智控台](./ali-sms-integration.md)<br/>
+2、[如何集成HomeAssistant实现智能家居控制](./homeassistant-integration.md)<br/>
+3、[如何开启视觉模型实现拍照识物](./mcp-vision-integration.md)<br/>
+4、[如何部署MCP接入点](./mcp-endpoint-enable.md)<br/>
+5、[如何接入MCP接入点](./mcp-endpoint-integration.md)<br/>
+6、[如何开启声纹识别](./voiceprint-integration.md)<br/>
+7、[新闻插件源配置指南](./newsnow_plugin_config.md)<br/>
+8、[天气插件使用指南](./weather-integration.md)<br/>
+## 语音克隆、本地语音部署相关教程
+1、[如何在智控台克隆音色](./huoshan-streamTTS-voice-cloning.md)<br/>
+2、[如何部署集成index-tts本地语音](./index-stream-integration.md)<br/>
+3、[如何部署集成fish-speech本地语音](./fish-speech-integration.md)<br/>
+4、[如何部署集成PaddleSpeech本地语音](./paddlespeech-deploy.md)<br/>
+## 性能测试教程
+1、[各组件速度测试指南](./performance_tester.md)<br/>
+2、[定期公开测试结果](https://github.com/xinnan-tech/xiaozhi-performance-research)<br/>

docs/Deployment_all.md

@@ -0,0 +1,492 @@
+# 部署架构图
+![请参考-全模块安装架构图](../docs/images/deploy2.png)
+# 方式一：Docker运行全模块
+`0.8.2`版本开始，本项目发行的docker镜像只支持`x86架构`，如果需要在`arm64架构`的CPU上部署，可按照[这个教程](docker-build.md)在本机编译`arm64的镜像`。
+
+## 1. 安装docker
+
+如果您的电脑还没安装docker，可以按照这里的教程安装：[docker安装](https://www.runoob.com/docker/ubuntu-docker-install.html)
+
+docker 安装全模块有两种方式，你可以[使用懒人脚本](./Deployment_all.md#11-懒人脚本)（作者[@VanillaNahida](https://github.com/VanillaNahida)）  
+脚本会自动帮你下载所需的文件和配置文件，你也可以使用[手动部署](./Deployment_all.md#12-手动部署)从零搭建。
+
+
+
+### 1.1 懒人脚本
+部署简便，可以参考[视频教程](https://www.bilibili.com/video/BV17bbvzHExd/) ，文字版教程如下：
+> [!NOTE]  
+> 暂且只支持Ubuntu服务器一键部署，其他系统未尝试，可能会有一些奇怪的bug
+
+使用SSH工具连接到服务器，以root权限执行如下脚本
+```bash
+sudo bash -c "$(wget -qO- https://ghfast.top/https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/main/docker-setup.sh)"
+```
+
+脚本会自动完成以下操作：
+> 1. 安装Docker
+> 2. 配置镜像源
+> 3. 下载/拉取镜像
+> 4. 下载语音识别模型文件
+> 5. 引导配置服务端
+>
+
+执行完成后简单配置后，再参照[4. 运行程序](#4. 运行程序)和[5.重启xiaozhi-esp32-server](#5.重启xiaozhi-esp32-server)里提到的最重要的3件事情，完成3这三项配置后即可使用。
+
+### 1.2 手动部署
+
+#### 1.2.1 创建目录
+
+安装完后，你需要为这个项目找一个安放配置文件的目录，例如我们可以新建一个文件夹叫`xiaozhi-server`。
+
+创建好目录后，你需要在`xiaozhi-server`下面创建`data`文件夹和`models`文件夹，`models`下面还要再创建`SenseVoiceSmall`文件夹。
+
+最终目录结构如下所示：
+
+```
+xiaozhi-server
+  ├─ data
+  ├─ models
+     ├─ SenseVoiceSmall
+```
+
+#### 1.2.2 下载语音识别模型文件
+
+本项目语音识别模型，默认使用`SenseVoiceSmall`模型，进行语音转文字。因为模型较大，需要独立下载，下载后把`model.pt`
+文件放在`models/SenseVoiceSmall`
+目录下。下面两个下载路线任选一个。
+
+- 线路一：阿里魔搭下载[SenseVoiceSmall](https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt)
+- 线路二：百度网盘下载[SenseVoiceSmall](https://pan.baidu.com/share/init?surl=QlgM58FHhYv1tFnUT_A8Sg&pwd=qvna) 提取码:
+  `qvna`
+
+
+#### 1.2.3 下载配置文件
+
+你需要下载两个配置文件：`docker-compose_all.yaml` 和 `config_from_api.yaml`。需要从项目仓库下载这两个文件。
+
+##### 1.2.3.1 下载 docker-compose_all.yaml
+
+用浏览器打开[这个链接](../main/xiaozhi-server/docker-compose_all.yml)。
+
+在页面的右侧找到名称为`RAW`按钮，在`RAW`按钮的旁边，找到下载的图标，点击下载按钮，下载`docker-compose_all.yml`文件。 把文件下载到你的
+`xiaozhi-server`中。
+
+或者直接执行 `wget https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/refs/heads/main/main/xiaozhi-server/docker-compose_all.yml` 下载。
+
+下载完后，回到本教程继续往下。
+
+##### 1.2.3.2 下载 config_from_api.yaml
+
+用浏览器打开[这个链接](../main/xiaozhi-server/config_from_api.yaml)。
+
+在页面的右侧找到名称为`RAW`按钮，在`RAW`按钮的旁边，找到下载的图标，点击下载按钮，下载`config_from_api.yaml`文件。 把文件下载到你的
+`xiaozhi-server`下面的`data`文件夹中，然后把`config_from_api.yaml`文件重命名为`.config.yaml`。
+
+或者直接执行 `wget https://raw.githubusercontent.com/xinnan-tech/xiaozhi-esp32-server/refs/heads/main/main/xiaozhi-server/config_from_api.yaml` 下载保存。
+
+下载完配置文件后，我们确认一下整个`xiaozhi-server`里面的文件如下所示：
+
+```
+xiaozhi-server
+  ├─ docker-compose_all.yml
+  ├─ data
+    ├─ .config.yaml
+  ├─ models
+     ├─ SenseVoiceSmall
+       ├─ model.pt
+```
+
+如果你的文件目录结构也是上面的，就继续往下。如果不是，你就再仔细看看是不是漏操作了什么。
+
+## 2. 备份数据
+
+如果你之前已经成功运行智控台，如果上面保存有你的密钥信息，请先从智控台上拷贝重要数据下来。因为升级过程中，有可能会覆盖原来的数据。
+
+## 3. 清除历史版本镜像和容器
+接下来打开命令行工具，使用`终端`或`命令行`工具 进入到你的`xiaozhi-server`，执行以下命令
+
+```
+docker compose -f docker-compose_all.yml down
+
+docker stop xiaozhi-esp32-server
+docker rm xiaozhi-esp32-server
+
+docker stop xiaozhi-esp32-server-web
+docker rm xiaozhi-esp32-server-web
+
+docker stop xiaozhi-esp32-server-db
+docker rm xiaozhi-esp32-server-db
+
+docker stop xiaozhi-esp32-server-redis
+docker rm xiaozhi-esp32-server-redis
+
+docker rmi ghcr.nju.edu.cn/xinnan-tech/xiaozhi-esp32-server:server_latest
+docker rmi ghcr.nju.edu.cn/xinnan-tech/xiaozhi-esp32-server:web_latest
+```
+
+## 4. 运行程序
+执行以下命令启动新版本容器
+
+```
+docker compose -f docker-compose_all.yml up -d
+```
+
+执行完后，再执行以下命令，查看日志信息。
+
+```
+docker logs -f xiaozhi-esp32-server-web
+```
+
+当你看到输出日志时，说明你的`智控台`启动成功了。
+
+```
+2025-xx-xx 22:11:12.445 [main] INFO  c.a.d.s.b.a.DruidDataSourceAutoConfigure - Init DruidDataSource
+2025-xx-xx 21:28:53.873 [main] INFO  xiaozhi.AdminApplication - Started AdminApplication in 16.057 seconds (process running for 17.941)
+http://localhost:8002/xiaozhi/doc.html
+```
+
+请注意此刻仅是`智控台`能运行，如果8000端口`xiaozhi-esp32-server`报错，先不要理会。
+
+这时，你需要使用浏览器，打开`智控台`，链接：http://127.0.0.1:8002 ，注册第一个用户。第一个用户即是超级管理员，以后的用户都是普通用户。普通用户只能绑定设备和配置智能体;超级管理员可以进行模型管理、用户管理、参数配置等功能。
+
+接下来要做三件重要的事情：
+
+### 第一件重要的事情
+
+使用超级管理员账号，登录智控台，在顶部菜单找到`参数管理`，找到列表中第一条数据，参数编码是`server.secret`，复制它到`参数值`。
+
+`server.secret`需要说明一下，这个`参数值`很重要，作用是让我们的`Server`端连接`manager-api`。`server.secret`是每次从零部署manager模块时，会自动随机生成的密钥。
+
+复制`参数值`后，打开`xiaozhi-server`下的`data`目录的`.config.yaml`文件。此刻你的配置文件内容应该是这样的：
+
+```
+manager-api:
+  url:  http://127.0.0.1:8002/xiaozhi
+  secret: 你的server.secret值
+```
+1、把你刚才从`智控台`复制过来的`server.secret`的`参数值`复制到`.config.yaml`文件里的`secret`里。
+
+2、因为你是docker部署，把`url`改成下面的`http://xiaozhi-esp32-server-web:8002/xiaozhi`
+
+3、因为你是docker部署，把`url`改成下面的`http://xiaozhi-esp32-server-web:8002/xiaozhi`
+
+4、因为你是docker部署，把`url`改成下面的`http://xiaozhi-esp32-server-web:8002/xiaozhi`
+
+类似这样的效果
+```
+manager-api:
+  url: http://xiaozhi-esp32-server-web:8002/xiaozhi
+  secret: 12345678-xxxx-xxxx-xxxx-123456789000
+```
+
+保存好后，继续往下做第二件重要的事情
+
+### 第二件重要的事情
+
+使用超级管理员账号，登录智控台，在顶部菜单找到`模型配置`，然后在左侧栏点击`大语言模型`，找到第一条数据`智谱AI`，点击`修改`按钮，
+弹出修改框后，将你注册到的`智谱AI`的密钥填写到`API密钥`中。然后点击保存。
+
+## 5.重启xiaozhi-esp32-server
+
+接下来打开命令行工具，使用`终端`或`命令行`工具 输入
+```
+docker restart xiaozhi-esp32-server
+docker logs -f xiaozhi-esp32-server
+```
+如果你能看到，类似以下日志,则是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请启动digital-human模块，打开浏览器交互测试
+25-02-23 12:01:09[core.websocket_server] - INFO - =======================================================
+```
+
+由于你是全模块部署，因此你有两个重要的接口需要写入到esp32中。
+
+OTA接口：
+```
+http://你宿主机局域网的ip:8002/xiaozhi/ota/
+```
+
+Websocket接口：
+```
+ws://你宿主机的ip:8000/xiaozhi/v1/
+```
+
+### 第三件重要的事情
+
+使用超级管理员账号，登录智控台，在顶部菜单找到`参数管理`，找到参数编码是`server.websocket`，输入你的`Websocket接口`。
+
+使用超级管理员账号，登录智控台，在顶部菜单找到`参数管理`，找到数编码是`server.ota`，输入你的`OTA接口`。
+
+接下来，你就可以开始操作你的esp32设备了，你可以`自行编译esp32固件`也可以配置使用`虾哥编译好的1.6.1以上版本的固件`。两个任选一个
+
+1、 [编译自己的esp32固件](firmware-build.md)了。
+
+2、 [基于虾哥编译好的固件配置自定义服务器](firmware-setting.md)了。
+
+
+# 方式二：本地源码运行全模块
+
+## 1.安装MySQL数据库
+
+如果本机已经安装了MySQL，可以直接在数据库中创建名为`xiaozhi_esp32_server`的数据库。
+
+```sql
+CREATE DATABASE xiaozhi_esp32_server CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+```
+
+如果还没有MySQL，你可以通过docker安装mysql
+
+```
+docker run --name xiaozhi-esp32-server-db -e MYSQL_ROOT_PASSWORD=123456 -p 3306:3306 -e MYSQL_DATABASE=xiaozhi_esp32_server -e MYSQL_INITDB_ARGS="--character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci" -e TZ=Asia/Shanghai -d mysql:latest
+```
+
+## 2.安装redis
+
+如果还没有Redis，你可以通过docker安装redis
+
+```
+docker run --name xiaozhi-esp32-server-redis -d -p 6379:6379 redis
+```
+
+## 3.运行manager-api程序
+
+3.1 安装JDK21，设置JDK环境变量
+
+3.2 安装Maven，设置Maven环境变量
+
+3.3 使用Vscode编程工具，安装好Java环境相关插件
+
+3.4 使用Vscode编程工具加载manager-api模块
+
+在`src/main/resources/application-dev.yml`中配置数据库连接信息
+
+```
+spring:
+  datasource:
+    username: root
+    password: 123456
+```
+在`src/main/resources/application-dev.yml`中配置Redis连接信息
+```
+spring:
+    data:
+      redis:
+        host: localhost
+        port: 6379
+        password:
+        database: 0
+```
+
+3.5 运行主程序
+
+本项目为SpringBoot项目，启动方式为：
+打开`Application.java`运行`Main`方法启动
+
+```
+路径地址：
+src/main/java/xiaozhi/AdminApplication.java
+```
+
+当你看到输出日志时，说明你的`manager-api`启动成功了。
+
+```
+2025-xx-xx 22:11:12.445 [main] INFO  c.a.d.s.b.a.DruidDataSourceAutoConfigure - Init DruidDataSource
+2025-xx-xx 21:28:53.873 [main] INFO  xiaozhi.AdminApplication - Started AdminApplication in 16.057 seconds (process running for 17.941)
+http://localhost:8002/xiaozhi/doc.html
+```
+
+## 4.运行manager-web程序
+
+4.1 安装nodejs
+
+4.2 使用Vscode编程工具加载manager-web模块
+
+终端命令进入manager-web目录下
+
+```
+npm install
+```
+然后启动
+```
+npm run serve
+```
+
+请注意，如果你的manager-api的接口不在`http://localhost:8002`，请在开发时，修改
+`main/manager-web/.env.development`中的路径
+
+运行成功后，你需要使用浏览器，打开`智控台`，链接：http://127.0.0.1:8001 ，注册第一个用户。第一个用户即是超级管理员，以后的用户都是普通用户。普通用户只能绑定设备和配置智能体;超级管理员可以进行模型管理、用户管理、参数配置等功能。
+
+
+重要：注册成功后，使用超级管理员账号，登录智控台，在顶部菜单找到`模型配置`，然后在左侧栏点击`大语言模型`，找到第一条数据`智谱AI`，点击`修改`按钮，
+弹出修改框后，将你注册到的`智谱AI`的密钥填写到`API密钥`中。然后点击保存。
+
+重要：注册成功后，使用超级管理员账号，登录智控台，在顶部菜单找到`模型配置`，然后在左侧栏点击`大语言模型`，找到第一条数据`智谱AI`，点击`修改`按钮，
+弹出修改框后，将你注册到的`智谱AI`的密钥填写到`API密钥`中。然后点击保存。
+
+重要：注册成功后，使用超级管理员账号，登录智控台，在顶部菜单找到`模型配置`，然后在左侧栏点击`大语言模型`，找到第一条数据`智谱AI`，点击`修改`按钮，
+弹出修改框后，将你注册到的`智谱AI`的密钥填写到`API密钥`中。然后点击保存。
+
+## 5.安装Python环境
+
+本项目使用`conda`管理依赖环境。如果不方便安装`conda`，需要根据实际的操作系统安装好`libopus`和`ffmpeg`。
+如果确定使用`conda`，则安装好后，开始执行以下命令。
+
+重要提示！windows 用户，可以通过安装`Anaconda`来管理环境。安装好`Anaconda`后，在`开始`那里搜索`anaconda`相关的关键词，
+找到`Anaconda Prpmpt`，使用管理员身份运行它。如下图。
+
+![conda_prompt](./images/conda_env_1.png)
+
+运行之后，如果你能看到命令行窗口前面有一个(base)字样，说明你成功进入了`conda`环境。那么你就可以执行以下命令了。
+
+![conda_env](./images/conda_env_2.png)
+
+```
+conda remove -n xiaozhi-esp32-server --all -y
+conda create -n xiaozhi-esp32-server python=3.10 -y
+conda activate xiaozhi-esp32-server
+
+# 添加清华源通道
+conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
+conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free
+conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge
+
+conda install libopus -y
+conda install ffmpeg -y
+
+# 在 Linux 环境下进行部署时,如出现类似缺失 libiconv.so.2 动态库的报错 请通过以下命令进行安装
+conda install libiconv -y
+```
+
+请注意，以上命令，不是一股脑执行就成功的，你需要一步步执行，每一步执行完后，都检查一下输出的日志，查看是否成功。
+
+## 6.安装本项目依赖
+
+你先要下载本项目源码，源码可以通过`git clone`命令下载，如果你不熟悉`git clone`命令。
+
+你可以用浏览器打开这个地址`https://github.com/xinnan-tech/xiaozhi-esp32-server.git`
+
+打开完，找到页面中一个绿色的按钮，写着`Code`的按钮，点开它，然后你就看到`Download ZIP`的按钮。
+
+点击它，下载本项目源码压缩包。下载到你电脑后，解压它，此时它的名字可能叫`xiaozhi-esp32-server-main`
+你需要把它重命名成`xiaozhi-esp32-server`，在这个文件里，进入到`main`文件夹，再进入到`xiaozhi-server`，好了请记住这个目录`xiaozhi-server`。
+
+```
+# 继续使用conda环境
+conda activate xiaozhi-esp32-server
+# 进入到你的项目根目录，再进入main/xiaozhi-server
+cd main/xiaozhi-server
+pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
+pip install -r requirements.txt
+```
+
+### 7.下载语音识别模型文件
+
+本项目语音识别模型，默认使用`SenseVoiceSmall`模型，进行语音转文字。因为模型较大，需要独立下载，下载后把`model.pt`
+文件放在`models/SenseVoiceSmall`
+目录下。下面两个下载路线任选一个。
+
+- 线路一：阿里魔搭下载[SenseVoiceSmall](https://modelscope.cn/models/iic/SenseVoiceSmall/resolve/master/model.pt)
+- 线路二：百度网盘下载[SenseVoiceSmall](https://pan.baidu.com/share/init?surl=QlgM58FHhYv1tFnUT_A8Sg&pwd=qvna) 提取码:
+  `qvna`
+
+## 8.配置项目文件
+
+使用超级管理员账号，登录智控台 ，在顶部菜单找到`参数管理`，找到列表中第一条数据，参数编码是`server.secret`，复制它到`参数值`。
+
+`server.secret`需要说明一下，这个`参数值`很重要，作用是让我们的`Server`端连接`manager-api`。`server.secret`是每次从零部署manager模块时，会自动随机生成的密钥。
+
+如果你的`xiaozhi-server`目录没有`data`，你需要创建`data`目录。
+如果你的`data`下面没有`.config.yaml`文件，你可以把`xiaozhi-server`目录下的`config_from_api.yaml`文件复制到`data`，并重命名为`.config.yaml`
+
+复制`参数值`后，打开`xiaozhi-server`下的`data`目录的`.config.yaml`文件。此刻你的配置文件内容应该是这样的：
+
+```
+manager-api:
+  url: http://127.0.0.1:8002/xiaozhi
+  secret: 你的server.secret值
+```
+
+把你刚才从`智控台`复制过来的`server.secret`的`参数值`复制到`.config.yaml`文件里的`secret`里。
+
+类似这样的效果
+```
+manager-api:
+  url: http://127.0.0.1:8002/xiaozhi
+  secret: 12345678-xxxx-xxxx-xxxx-123456789000
+```
+
+## 9.运行项目
+
+```
+# 确保在xiaozhi-server目录下执行
+conda activate xiaozhi-esp32-server
+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请启动digital-human模块，打开浏览器交互测试
+25-02-23 12:01:09[core.websocket_server] - INFO - =======================================================
+```
+
+由于你是全模块部署，因此你有两个重要的接口。
+
+OTA接口：
+```
+http://你电脑局域网的ip:8002/xiaozhi/ota/
+```
+
+Websocket接口：
+```
+ws://你电脑局域网的ip:8000/xiaozhi/v1/
+```
+
+请你务必把以上两个接口地址写入到智控台中：他们将会影响websocket地址发放和自动升级功能。
+
+1、使用超级管理员账号，登录智控台，在顶部菜单找到`参数管理`，找到参数编码是`server.websocket`，输入你的`Websocket接口`。
+
+2、使用超级管理员账号，登录智控台，在顶部菜单找到`参数管理`，找到数编码是`server.ota`，输入你的`OTA接口`。
+
+
+接下来，你就可以开始操作你的esp32设备了，你可以`自行编译esp32固件`也可以配置使用`虾哥编译好的1.6.1以上版本的固件`。两个任选一个
+
+1、 [编译自己的esp32固件](firmware-build.md)了。
+
+2、 [基于虾哥编译好的固件配置自定义服务器](firmware-setting.md)了。
+
+# 常见问题
+以下是一些常见问题，供参考：
+
+1、[为什么我说的话，小智识别出来很多韩文、日文、英文](./FAQ.md)<br/>
+2、[为什么会出现“TTS 任务出错 文件不存在”？](./FAQ.md)<br/>
+3、[TTS 经常失败，经常超时](./FAQ.md)<br/>
+4、[使用Wifi能连接自建服务器，但是4G模式却接不上](./FAQ.md)<br/>
+5、[如何提高小智对话响应速度？](./FAQ.md)<br/>
+6、[我说话很慢，停顿时小智老是抢话](./FAQ.md)<br/>
+## 部署相关教程
+1、[如何自动拉取本项目最新代码自动编译和启动](./dev-ops-integration.md)<br/>
+2、[如何部署MQTT网关开启MQTT+UDP协议](./mqtt-gateway-integration.md)<br/>
+3、[如何与Nginx集成](https://github.com/xinnan-tech/xiaozhi-esp32-server/issues/791)<br/>
+## 拓展相关教程
+1、[如何开启手机号码注册智控台](./ali-sms-integration.md)<br/>
+2、[如何集成HomeAssistant实现智能家居控制](./homeassistant-integration.md)<br/>
+3、[如何开启视觉模型实现拍照识物](./mcp-vision-integration.md)<br/>
+4、[如何部署MCP接入点](./mcp-endpoint-enable.md)<br/>
+5、[如何接入MCP接入点](./mcp-endpoint-integration.md)<br/>
+6、[如何开启声纹识别](./voiceprint-integration.md)<br/>
+7、[新闻插件源配置指南](./newsnow_plugin_config.md)<br/>
+8、[天气插件使用指南](./weather-integration.md)<br/>
+## 语音克隆、本地语音部署相关教程
+1、[如何在智控台克隆音色](./huoshan-streamTTS-voice-cloning.md)<br/>
+2、[如何部署集成index-tts本地语音](./index-stream-integration.md)<br/>
+3、[如何部署集成fish-speech本地语音](./fish-speech-integration.md)<br/>
+4、[如何部署集成PaddleSpeech本地语音](./paddlespeech-deploy.md)<br/>
+## 性能测试教程
+1、[各组件速度测试指南](./performance_tester.md)<br/>
+2、[定期公开测试结果](https://github.com/xinnan-tech/xiaozhi-performance-research)<br/>

docs/FAQ.md

@@ -0,0 +1,107 @@
+# 常见问题 ❓
+
+### 1、为什么我说的话，小智识别出来很多韩文、日文、英文？🇰🇷
+
+建议：检查一下`models/SenseVoiceSmall`是否已经有`model.pt`
+文件，如果没有就要下载，查看这里[下载语音识别模型文件](Deployment.md#模型文件)
+
+### 2、为什么会出现"TTS 任务出错 文件不存在"？📁
+
+建议：检查一下是否正确使用`conda` 安装了`libopus`和`ffmpeg`库。
+
+如果没有安装，就安装
+
+```
+conda install conda-forge::libopus
+conda install conda-forge::ffmpeg
+```
+
+### 3、TTS 经常失败，经常超时 ⏰
+
+建议：如果 `EdgeTTS` 经常失败，请先检查是否使用了代理（梯子）。如果使用了，请尝试关闭代理后再试；  
+如果用的是火山引擎的豆包 TTS，经常失败时建议使用付费版本，因为测试版本仅支持 2 个并发。
+
+### 4、使用Wifi能连接自建服务器，但是4G模式却接不上 🔐
+
+原因：虾哥的固件，4G模式需要使用安全连接。
+
+解决方法：目前有两种方法可以解决。任选一种：
+
+1、改代码。参考这个视频解决 https://www.bilibili.com/video/BV18MfTYoE85
+
+2、使用nginx配置ssl证书。参考教程 https://icnt94i5ctj4.feishu.cn/docx/GnYOdMNJOoRCljx1ctecsj9cnRe
+
+### 5、如何提高小智对话响应速度？ ⚡
+
+本项目默认配置为低成本方案，建议初学者先使用默认免费模型，解决"跑得动"的问题，再优化"跑得快"。  
+如需提升响应速度，可尝试更换各组件。自`0.5.2`版本起，项目支持流式配置，相比早期版本，响应速度提升约`2.5秒`，显著改善用户体验。
+
+| 模块名称 | 入门全免费设置 | 流式配置 |
+|:---:|:---:|:---:|
+| ASR(语音识别) | FunASR(本地) | 👍XunfeiStreamASR(讯飞流式) |
+| LLM(大模型) | glm-4-flash(智谱) | 👍qwen-flash(阿里百炼) |
+| VLLM(视觉大模型) | glm-4v-flash(智谱) | 👍qwen3.5-flash(阿里百炼) |
+| TTS(语音合成) | EdgeTTS(微软) | 👍HuoshanDoubleStreamTTS(火山流式) |
+| Intent(意图识别) | function_call(函数调用) | function_call(函数调用) |
+| Memory(记忆功能) | mem_local_short(本地短期记忆） | mem_local_short（本地短期记忆） |
+
+如果您关心各组件的耗时，请查阅[小智各组件性能测试报告](https://github.com/xinnan-tech/xiaozhi-performance-research)，可按报告中的测试方法在您的环境中实际测试。
+
+### 6、我说话很慢，停顿时小智老是抢话 🗣️
+
+建议：在配置文件中找到如下部分，将 `min_silence_duration_ms` 的值调大（例如改为 `1000`）：
+
+```yaml
+VAD:
+  SileroVAD:
+    threshold: 0.5
+    model_dir: models/snakers4_silero-vad
+    min_silence_duration_ms: 700  # 如果说话停顿较长，可将此值调大
+```
+
+### 7、部署相关教程
+1、[如何进行最简化部署](./Deployment.md)<br/>
+2、[如何进行全模块部署](./Deployment_all.md)<br/>
+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/>
+
+### 8、编译固件相关教程
+1、[如何自己编译小智固件](./firmware-build.md)<br/>
+2、[如何基于虾哥编译好的固件修改OTA地址](./firmware-setting.md)<br/>
+3、[单模块部署如何配置固件OTA自动升级](./ota-upgrade-guide.md)<br/>
+
+### 9、拓展相关教程
+1、[如何开启手机号码注册智控台](./ali-sms-integration.md)<br/>
+2、[如何集成HomeAssistant实现智能家居控制](./homeassistant-integration.md)<br/>
+3、[如何开启视觉模型实现拍照识物](./mcp-vision-integration.md)<br/>
+4、[如何部署MCP接入点](./mcp-endpoint-enable.md)<br/>
+5、[如何接入MCP接入点](./mcp-endpoint-integration.md)<br/>
+6、[MCP方法如何获取设备信息](./mcp-get-device-info.md)<br/>
+7、[如何开启声纹识别](./voiceprint-integration.md)<br/>
+8、[新闻插件源配置指南](./newsnow_plugin_config.md)<br/>
+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/>
+2、[如何部署集成index-tts本地语音](./index-stream-integration.md)<br/>
+3、[如何部署集成fish-speech本地语音](./fish-speech-integration.md)<br/>
+4、[如何部署集成PaddleSpeech本地语音](./paddlespeech-deploy.md)<br/>
+
+### 12、性能测试教程
+1、[各组件速度测试指南](./performance_tester.md)<br/>
+2、[定期公开测试结果](https://github.com/xinnan-tech/xiaozhi-performance-research)<br/>
+
+### 13、更多问题，可联系我们反馈 💬
+
+可以在[issues](https://github.com/xinnan-tech/xiaozhi-esp32-server/issues)提交您的问题。

docs/ali-sms-integration.md

@@ -0,0 +1,44 @@
+# 阿里云短信集成指南
+
+登录阿里云控制台，进入“短信服务”页面：https://dysms.console.aliyun.com/overview
+
+## 第一步 添加签名
+![步骤](images/alisms/sms-01.png)
+![步骤](images/alisms/sms-02.png)
+
+以上步骤，会得到签名，请把它写入到智控台参数，`aliyun.sms.sign_name`
+
+## 第二步 添加模版
+![步骤](images/alisms/sms-11.png)
+
+以上步骤，会得到模版code，请把它写入到智控台参数，`aliyun.sms.sms_code_template_code`
+
+注意，签名要等7个工作日，等运营商报备成功后才能发送成功。
+
+注意，签名要等7个工作日，等运营商报备成功后才能发送成功。
+
+注意，签名要等7个工作日，等运营商报备成功后才能发送成功。
+
+可以等报备成功后，再继续往下操作。
+
+## 第三步 创建短信账户和开通权限
+
+登录阿里云控制台，进入“访问控制”页面：https://ram.console.aliyun.com/overview?activeTab=overview
+
+![步骤](images/alisms/sms-21.png)
+![步骤](images/alisms/sms-22.png)
+![步骤](images/alisms/sms-23.png)
+![步骤](images/alisms/sms-24.png)
+![步骤](images/alisms/sms-25.png)
+
+以上步骤，会得到access_key_id和access_key_secret，请把它写入到智控台参数，`aliyun.sms.access_key_id`、`aliyun.sms.access_key_secret`
+## 第四步 启动手机注册功能
+
+1、正常来说，以上信息都填完后，会有这个效果，如果没有，可能缺少了某个步骤
+
+![步骤](images/alisms/sms-31.png)
+
+2、开启允许非管理员用户可注册，将参数`server.allow_user_register`设置成`true`
+
+3、开启手机注册功能，将参数`server.enable_mobile_register`设置成`true`
+![步骤](images/alisms/sms-32.png)

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/context-provider-integration.md

@@ -0,0 +1,224 @@
+# 上下文源使用教程
+
+## 概述
+
+`上下文源`，就是为小智系统提示词的上下文添加【数据源】。
+
+`上下文源` 在小智在唤醒那一刻，获取外部系统的数据，并将其动态注入到大模型的系统提示词（System Prompt）中。
+让其做到唤醒时感知世界某个事物的状态。
+
+它和MCP、记忆有本质的区别：`上下文源`是强制让小智感知世界的数据；`记忆(Mem)`是让他知道之前聊了什么内容；`MCP(functionc all)`是当需要调用某项能力/知识的时候使用调用。
+
+通过这个功能，在小智唤醒的一刹那，“感知”到：
+- 人体健康传感器状态（体温、血压、血氧状态等）
+- 业务系统的实时数据（服务器负载、待办数据、股票信息等）
+- 任何可以通过 HTTP API 获取的文本信息
+
+**注意**：该功能只是方便小智在唤醒的时候感知事物的状态，而如果想要小智唤醒后实时获取事物的状态，建议在此功能上再结合MCP工具的调用。
+
+## 工作原理
+
+1. **配置源**：用户配置一个或多个 HTTP API 地址。
+2. **触发请求**：当系统构建 Prompt 时，如果发现模板中包含 `{{ dynamic_context }}` 占位符，会请求所有配置的 API。
+3. **自动注入**：系统会自动将 API 返回的数据格式化为 Markdown 列表，替换 `{{ dynamic_context }}` 占位符。
+
+## 接口规范
+
+为了让小智正确解析数据，您的 API 需要满足以下规范：
+
+- **请求方式**：`GET`
+- **请求头**：系统会自动添加 `device-id` 字段到 Request Header。
+- **响应格式**：必须返回 JSON 格式，且包含 `code` 和 `data` 字段。
+
+### 响应示例
+
+**情况 1：返回键值对**
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": {
+    "客厅温度": "26℃",
+    "客厅湿度": "45%",
+    "大门状态": "已关闭"
+  }
+}
+```
+*注入效果：*
+```markdown
+<context>
+- **客厅温度：** 26℃
+- **客厅湿度：** 45%
+- **大门状态：** 已关闭
+</context>
+```
+
+**情况 2：返回列表**
+```json
+{
+  "code": 0,
+  "data": [
+    "您有10个待办事项",
+    "当前汽车的行驶速度是100km每小时"
+  ]
+}
+```
+*注入效果：*
+```markdown
+<context>
+- 您有10个待办事项
+- 当前汽车的行驶速度是100km每小时
+</context>
+```
+
+## 配置指南
+
+### 方式 1：智控台配置（全模块部署）
+
+1. 登录智控台，进入**角色配置**页面。
+2. 找到**上下文源**配置项（点击“编辑源”按钮）。
+3. 点击**添加**，输入您的 API 地址。
+4. 如果 API 需要鉴权，可以在**请求头**部分添加 `Authorization` 或其他 Header。
+5. 保存配置。
+
+### 方式 2：配置文件配置（单模块部署）
+
+编辑 `xiaozhi-server/data/.config.yaml` 文件，添加 `context_providers` 配置段：
+
+```yaml
+# 上下文源配置
+context_providers:
+  - url: "http://api.example.com/data"
+    headers:
+      Authorization: "Bearer your-token"
+  - url: "http://another-api.com/data"
+```
+
+## 启用功能
+
+默认情况下，系统的提示词模板文件（`data/.agent-base-prompt.txt`）中已经预置了 `{{ dynamic_context }}` 占位符，您无需手动添加。
+
+**示例：**
+
+```markdown
+<context>
+【重要！以下信息已实时提供，无需调用工具查询，请直接使用：】
+- **设备ID：** {{device_id}}
+- **当前时间：** {{current_time}}
+...
+{{ dynamic_context }}
+</context>
+```
+
+**注意**：如果您不需要使用此功能，可以选择**不配置任何上下文源**，也可以从提示词模板文件中**删除** `{{ dynamic_context }}` 占位符。
+
+## 附录：Mock 测试服务示例
+
+为了方便您测试和开发，我们提供了一个简单的 Python Mock Server 脚本。您可以运行此脚本在本地模拟 API 接口。
+
+**mock_api_server.py**
+
+```python
+import http.server
+import socketserver
+import json
+from urllib.parse import urlparse, parse_qs
+
+# 设置端口号
+PORT = 8081
+
+class MockRequestHandler(http.server.SimpleHTTPRequestHandler):
+    def do_GET(self):
+        # 解析路径和参数
+        parsed_path = urlparse(self.path)
+        path = parsed_path.path
+        query = parse_qs(parsed_path.query)
+
+        response_data = {}
+        status_code = 200
+
+        print(f"收到请求: {path}, 参数: {query}")
+
+        # Case 1: 模拟健康数据 (返回字典 Dict)
+        # 路径参数风格: /health
+        # device_id 从 Header 获取
+        if path == "/health":
+            device_id = self.headers.get("device-id", "unknown_device")
+            print(f"device_id: {device_id}")
+            response_data = {
+                "code": 0,
+                "msg": "success",
+                "data": {
+                    "测试设备ID": device_id,
+                    "心率": "80 bpm",
+                    "血压": "120/80 mmHg",
+                    "状态": "良好"
+                }
+            }
+
+        # Case 2: 模拟新闻列表 (返回列表 List)
+        # 无参数: /news/list
+        elif path == "/news/list":
+            response_data = {
+                "code": 0,
+                "msg": "success",
+                "data": [
+                    "今日头条：Python 3.14 发布",
+                    "科技新闻：AI 助手改变生活",
+                    "本地新闻：明日有大雨，记得带伞"
+                ]
+            }
+
+        # Case 3: 模拟天气简报 (返回字符串 String)
+        # 无参数: /weather/simple
+        elif path == "/weather/simple":
+            response_data = {
+                "code": 0,
+                "msg": "success",
+                "data": "今日晴转多云，气温 20-25 度，空气质量优，适合出行。"
+            }
+
+        # Case 4: 模拟设备详情 (Query参数风格)
+        # 参数风格: /device/info
+        # device_id 从 Header 获取
+        elif path == "/device/info":
+            device_id = self.headers.get("device-id", "unknown_device")
+            response_data = {
+                "code": 0,
+                "msg": "success",
+                "data": {
+                    "查询方式": "Header参数",
+                    "设备ID": device_id,
+                    "电量": "85%",
+                    "固件": "v2.0.1"
+                }
+            }
+        
+        # Case 5: 404 Not Found
+        else:
+            status_code = 404
+            response_data = {"error": "接口不存在"}
+
+        # 发送响应
+        self.send_response(status_code)
+        self.send_header('Content-type', 'application/json; charset=utf-8')
+        self.end_headers()
+        self.wfile.write(json.dumps(response_data, ensure_ascii=False).encode('utf-8'))
+
+# 启动服务
+# 允许地址重用，防止快速重启报错
+socketserver.TCPServer.allow_reuse_address = True
+with socketserver.TCPServer(("", PORT), MockRequestHandler) as httpd:
+    print(f"==================================================")
+    print(f"Mock API Server 已启动: http://localhost:{PORT}")
+    print(f"可用接口列表:")
+    print(f"1. [字典] http://localhost:{PORT}/health")
+    print(f"2. [列表] http://localhost:{PORT}/news/list")
+    print(f"3. [文本] http://localhost:{PORT}/weather/simple")
+    print(f"4. [参数] http://localhost:{PORT}/device/info")
+    print(f"==================================================")
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        print("\n服务已停止")
+```

docs/dev-ops-integration.md

@@ -0,0 +1,182 @@
+# 全模块源码部署自动升级方法
+
+本教程是方便全模块源码部署的爱好者，如何通过自动命令，自动拉取源码，自动编译，自动启动端口运行。实现最高效率的升级系统。
+
+本项目的测试平台`https://2662r3426b.vicp.fun`，从开放以来就使用了该方法，效果良好。
+
+教程可参考B站博主`毕乐labs`发布的视频教程：[《开源小智服务器xiaozhi-server自动更新以及最新版本MCP接入点配置保姆教程》](https://www.bilibili.com/video/BV15H37zHE7Q)
+
+# 开始条件
+- 你的电脑/服务器是linux操作系统
+- 你已经跑通了整个流程
+- 你喜欢跟进最新功能，但是觉得每次手动部署有点麻烦，期待有一个自动更新的方法
+
+第二个条件必须满足，因为本教程所涉及的某些文件，JDK、Node.js环境、Conda环境等，是需要你跑通整个流程才有的，如果你没有跑通，当我讲到某个文件的时候，你可能就不知道什么意思。
+
+# 教程效果
+- 解决国内不能拉取最新项目源码问题
+- 自动拉取代码编译前端文件
+- 自动拉取代码编译java文件，自动杀掉8002端口，自动启动8002端口
+- 自动拉取python代码，自动杀掉8000端口，自动启动8000端口
+
+# 第一步 选好你的项目目录
+
+例如，我规划了我的项目目录是，这是一个新建的空白的目录，如果你不想出错，可以和我一样
+```
+/home/system/xiaozhi
+```
+
+# 第二步 克隆本项目
+此刻，先要执行第一句话，拉取源码，这句命令适用于国内网络的服务器和电脑，无需翻墙
+
+```
+cd /home/system/xiaozhi
+git clone https://ghproxy.net/https://github.com/xinnan-tech/xiaozhi-esp32-server.git
+```
+
+执行完后，你的项目目录会多了一个文件夹`xiaozhi-esp32-server`，这个就是项目的源码
+
+# 第三步 复制基础的文件
+
+如果你之前已经跑通了整个流程，对funasr的模型文件`xiaozhi-server/models/SenseVoiceSmall/model.pt`和你的私有配置文件`xiaozhi-server/data/.config.yaml`这两个文件不会陌生。
+
+此刻你需要把`model.pt`文件复制到新的目录去，你可以这样
+```
+# 创建需要的目录
+mkdir -p /home/system/xiaozhi/xiaozhi-esp32-server/main/xiaozhi-server/data/
+
+cp 你原来的.config.yaml完整路径 /home/system/xiaozhi/xiaozhi-esp32-server/main/xiaozhi-server/data/.config.yaml
+cp 你原来的model.pt完整路径 /home/system/xiaozhi/xiaozhi-esp32-server/main/xiaozhi-server/models/SenseVoiceSmall/model.pt
+```
+
+# 第四步 建立三个自动编译文件
+
+## 4.1 自动编译mananger-web模块
+在`/home/system/xiaozhi/`目录下，创建名字为`update_8001.sh`的文件，内容如下
+
+```
+cd /home/system/xiaozhi/xiaozhi-esp32-server
+git fetch --all
+git reset --hard
+git pull origin main
+
+
+cd /home/system/xiaozhi/xiaozhi-esp32-server/main/manager-web
+npm install
+npm run build
+rm -rf /home/system/xiaozhi/manager-web
+mv /home/system/xiaozhi/xiaozhi-esp32-server/main/manager-web/dist /home/system/xiaozhi/manager-web
+```
+
+保存好后执行赋权命令
+```
+chmod 777 update_8001.sh
+```
+执行完后，继续往下
+
+## 4.2 自动编译运行manager-api模块
+在`/home/system/xiaozhi/`目录下，创建名字为`update_8002.sh`的文件，内容如下
+
+```
+cd /home/system/xiaozhi/xiaozhi-esp32-server
+git pull origin main
+
+
+cd /home/system/xiaozhi/xiaozhi-esp32-server/main/manager-api
+rm -rf target
+mvn clean package -Dmaven.test.skip=true
+cd /home/system/xiaozhi/
+
+# 查找占用8002端口的进程号
+PID=$(sudo netstat -tulnp | grep 8002 | awk '{print $7}' | cut -d'/' -f1)
+
+rm -rf /home/system/xiaozhi/xiaozhi-esp32-api.jar
+mv /home/system/xiaozhi/xiaozhi-esp32-server/main/manager-api/target/xiaozhi-esp32-api.jar /home/system/xiaozhi/xiaozhi-esp32-api.jar
+
+# 检查是否找到进程号
+if [ -z "$PID" ]; then
+  echo "没有找到占用8002端口的进程"
+else
+  echo "找到占用8002端口的进程，进程号为: $PID"
+  # 杀掉进程
+  kill -9 $PID
+  kill -9 $PID
+  echo "已杀掉进程 $PID"
+fi
+
+nohup java -jar xiaozhi-esp32-api.jar --spring.profiles.active=dev &
+
+tail tail -f nohup.out
+```
+
+保存好后执行赋权命令
+```
+chmod 777 update_8002.sh
+```
+执行完后，继续往下
+
+## 4.3 自动编译运行Python项目
+在`/home/system/xiaozhi/`目录下，创建名字为`update_8000.sh`的文件，内容如下
+
+```
+cd /home/system/xiaozhi/xiaozhi-esp32-server
+git pull origin main
+
+# 查找占用8000端口的进程号
+PID=$(sudo netstat -tulnp | grep 8000 | awk '{print $7}' | cut -d'/' -f1)
+
+# 检查是否找到进程号
+if [ -z "$PID" ]; then
+  echo "没有找到占用8000端口的进程"
+else
+  echo "找到占用8000端口的进程，进程号为: $PID"
+  # 杀掉进程
+  kill -9 $PID
+  kill -9 $PID
+  echo "已杀掉进程 $PID"
+fi
+cd main/xiaozhi-server
+# 初始化conda环境
+source ~/.bashrc
+conda activate xiaozhi-esp32-server
+pip install -r requirements.txt
+nohup python app.py >/dev/null &
+tail -f /home/system/xiaozhi/xiaozhi-esp32-server/main/xiaozhi-server/tmp/server.log
+```
+
+保存好后执行赋权命令
+```
+chmod 777 update_8000.sh
+```
+执行完后，继续往下
+
+# 日常更新
+
+以上的脚本都建立好后，日常更新，我们只要依次执行以下命令就可以做到自动更新和启动
+
+```
+cd /home/system/xiaozhi
+# 更新并启动Java程序
+./update_8001.sh
+# 更新web程序
+./update_8002.sh
+# 更新并启动python程序
+./update_8000.sh
+
+
+# 后期想查看java日志，执行以下命令
+tail -f nohup.out
+# 后期想查看python日志，执行以下命令
+tail -f /home/system/xiaozhi/xiaozhi-esp32-server/main/xiaozhi-server/tmp/server.log
+```
+
+# 注意事项
+测试平台`https://2662r3426b.vicp.fun`，是使用nginx做了反向代理。nginx.conf详细配置可以[参考这里](https://github.com/xinnan-tech/xiaozhi-esp32-server/issues/791)
+
+## 常见问题
+
+### 1、为什么没有见到8001端口？
+回答：8001是开发环境使用的，用于运行前端的端口。如果你是服务器部署，不建议使用`npm run serve`启动8001端口运行前端，而是像本教程一样编译成html文件，然后使用nginx来管理访问。
+
+### 2、每次更新需要更新手动SQL语句吗？
+回答：不需要，因为项目使用**Liquibase**管理数据库版本，会自动执行新的sql脚本。

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启动项目
-# docker-compose.yml你需要修改成自己编译的镜像版本
+## 2、编译镜像
+
+当你修改好代码后，需要编译新的镜像时，需要按照以下步骤操作：
+
+准备好你的`你的用户名`和`新的版本号`。
+- 这个`你的用户名`是你在`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/docker/nginx.conf

@@ -1,26 +1,53 @@
-server {
-    listen 8002;
-    server_name localhost;
+user  root;
+worker_processes  4;
 
-    # 静态资源服务（Vue项目）
-    location / {
-        root /usr/share/nginx/html;
-        try_files $uri $uri/ /index.html;
-    }
+events {
+    worker_connections  1024;
+}
 
-    # API反向代理（Java项目）
-    location /xiaozhi-esp32-api/ {
-        proxy_pass http://127.0.0.1:8003;
-        proxy_set_header   Host   $host;
-        proxy_cookie_path /api/ /;
-        proxy_set_header   Referer $http_referer;
-        proxy_set_header   Cookie $http_cookie;
+http {
+    include       mime.types;
+    default_type  application/octet-stream;
+    sendfile        on;
+    keepalive_timeout  300;
+    client_header_timeout 180s;
+    client_body_timeout 180s;
+    client_max_body_size 1024M;
 
-        proxy_connect_timeout 10;
-        proxy_send_timeout 10;
-        proxy_read_timeout 10;
+    gzip on;
+    gzip_buffers 32 4K;
+    gzip_comp_level 6;
+    gzip_min_length 100;
+    gzip_types application/javascript text/css text/xml image/jpeg image/gif image/png;
+    gzip_disable "MSIE [1-6]\.";
+    gzip_vary on;
 
-        proxy_set_header   X-Real-IP  $remote_addr;
-        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
+    server {
+        # 无域名访问，就用localhost
+        server_name localhost;
+        # 80端口
+        listen  8002;
+
+        # 转发到编译后到web目录
+        location / {
+			root /usr/share/nginx/html;
+			try_files $uri $uri/ /index.html;
+		}
+
+        # 转发到manager-api
+        location /xiaozhi/ {
+            proxy_pass http://127.0.0.1:8003;
+            proxy_set_header   Host   $host;
+            proxy_cookie_path /manager/ /;
+            proxy_set_header   Referer $http_referer;
+            proxy_set_header   Cookie $http_cookie;
+
+            proxy_connect_timeout 15;
+            proxy_send_timeout 15;
+            proxy_read_timeout 15;
+
+            proxy_set_header   X-Real-IP  $remote_addr;
+            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
+        }
     }
 }

docs/docker/start.sh

@@ -6,6 +6,7 @@ java -jar /app/xiaozhi-esp32-api.jar \
   --spring.datasource.druid.username=${SPRING_DATASOURCE_DRUID_USERNAME} \
   --spring.datasource.druid.password=${SPRING_DATASOURCE_DRUID_PASSWORD} \
   --spring.data.redis.host=${SPRING_DATA_REDIS_HOST} \
+  --spring.data.redis.password=${SPRING_DATA_REDIS_PASSWORD} \
   --spring.data.redis.port=${SPRING_DATA_REDIS_PORT} &
 
 # 启动Nginx（前台运行保持容器存活）

docs/firmware-build.md

@@ -1,40 +1,81 @@
-# 编译esp32固件
+# esp32固件编译
 
-1. 下载`xiaozhi-esp32`
-   项目，按照这个教程配置项目环境[《Windows搭建 ESP IDF 5.3.2开发环境以及编译小智》](https://icnynnzcwou8.feishu.cn/wiki/JEYDwTTALi5s2zkGlFGcDiRknXf)
+## 第1步 准备你的ota地址
 
-2. 打开`xiaozhi-esp32/main/Kconfig.projbuild`文件，找到`WEBSOCKET_URL`的`default`的内容，把`wss://api.tenclass.net`
-   改成你自己的地址，例如，我的接口地址是`ws://192.168.1.25:8000`，就把内容改成这个。
+如果你，使用的是本项目0.3.12版本，不管是简单Server部署还是全模块部署，都会有ota地址。
+
+由于简单Server部署和全模块部署的OTA地址设置方式不一样，请你选择下面的具体方式：
+
+### 如果你用的是简单Server部署
+此刻，请你用浏览器打开你的ota地址，例如我的ota地址
+```
+http://192.168.1.25:8003/xiaozhi/ota/
+```
+如果显示“OTA接口运行正常，向设备发送的websocket地址是：ws://xxx:8000/xiaozhi/v1/
+
+你可以启动`digital-human`模块后打开`index.html`测试一下，是否能连上ota页面输出的websocket地址。
+
+如果访问不到，你需要到配置文件`.config.yaml`里修改`server.websocket`的地址，重启后再重新测试，直到`index.html`能正常访问。
+
+成功后，请往下进行第2步
+
+### 如果你用的是全模块部署
+此刻，请你用浏览器打开你的ota地址，例如我的ota地址
+```
+http://192.168.1.25:8002/xiaozhi/ota/
+```
+
+如果显示“OTA接口运行正常，websocket集群数量：X”。那就往下进行2步。
+
+如果显示“OTA接口运行不正常”，大概是你还没在`智控台`配置`Websocket`地址。那就：
+
+- 1、使用超级管理员登录智控台
+
+- 2、顶部菜单点击`参数管理`
+
+- 3、在列表中找到`server.websocket`项目，输入你的`Websocket`地址。例如我的就是
+
+```
+ws://192.168.1.25:8000/xiaozhi/v1/
+```
+
+配置完后，再使用浏览器刷新你的ota接口地址，看看是不是正常了。如果还不正常就，就再次确认一下Websocket是否正常启动，是否配置了Websocket地址。
+
+## 第2步 配置环境
+先按照这个教程配置项目环境[《Windows搭建 ESP IDF 5.3.2开发环境以及编译小智》](https://icnynnzcwou8.feishu.cn/wiki/JEYDwTTALi5s2zkGlFGcDiRknXf)
+
+## 第3步 打开配置文件
+配置好编译环境后，下载虾哥iaozhi-esp32项目源码，
+
+从这里下载虾哥[xiaozhi-esp32项目源码](https://github.com/78/xiaozhi-esp32)。
+
+下载后，打开`xiaozhi-esp32/main/Kconfig.projbuild`文件。
+
+## 第4步 修改OTA地址
+
+找到`OTA_URL`的`default`的内容，把`https://api.tenclass.net/xiaozhi/ota/`
+   改成你自己的地址，例如，我的接口地址是`http://192.168.1.25:8002/xiaozhi/ota/`，就把内容改成这个。
 
 修改前：
-
 ```
-config WEBSOCKET_URL
-    depends on CONNECTION_TYPE_WEBSOCKET
-    string "Websocket URL"
-    default "wss://api.tenclass.net/xiaozhi/v1/"
+config OTA_URL
+    string "Default OTA URL"
+    default "https://api.tenclass.net/xiaozhi/ota/"
     help
-        Communication with the server through websocket after wake up.
+        The application will access this URL to check for new firmwares and server address.
 ```
-
-修改后(示例)：
-
+修改后：
 ```
-config WEBSOCKET_URL
-    depends on CONNECTION_TYPE_WEBSOCKET
-    string "Websocket URL"
-    default "ws://192.168.1.25:8000/xiaozhi/v1/"
+config OTA_URL
+    string "Default OTA URL"
+    default "http://192.168.1.25:8002/xiaozhi/ota/"
     help
-        Communication with the server through websocket after wake up.
+        The application will access this URL to check for new firmwares and server address.
 ```
 
-注意：你的地址是`ws://`开头，不是`wss://`开头，一定不要写错了。
+## 第4步 设置编译参数
 
-注意：你的地址是`ws://`开头，不是`wss://`开头，一定不要写错了。
-
-注意：你的地址是`ws://`开头，不是`wss://`开头，一定不要写错了。
-
-3. 设置编译参数
+设置编译参数
 
 ```
 # 终端命令行进入xiaozhi-esp32的根目录
@@ -45,40 +86,29 @@ idf.py set-target esp32s3
 idf.py menuconfig
 ```
 
-![图片](images/build_setting01.png)
-
-进入菜单配置后，再进入`Xiaozhi Assistant`，将`CONNECTION_TYPE`设置为`Websocket`
-回退到主菜单，再进入`Xiaozhi Assistant`，将`BOARD_TYPE`设置你板子的具体型号
+进入菜单配置后，再进入`Xiaozhi Assistant`，将`BOARD_TYPE`设置你板子的具体型号
 保存退出，回到终端命令行。
 
-![图片](images/build_setting02.png)
-
-4. 编译固件
+## 第5步 编译固件
 
 ```
 idf.py build
 ```
 
-如果是vscode安装的idf可以使用`F1`或者`ctrl+shift+p`,输入idf然后直接选择进行编译
-
-还可以直接进行烧录不用接下来的操作
-
-<img src="./images/vscode_idf.png" width="500px"/>
-
-5. 打包bin固件
+## 第6步 打包bin固件
 
 ```
 cd scripts
 python release.py
 ```
 
-编译成功后，会在项目根目录下的`build`目录下生成固件文件`merged-binary.bin`。
+上面的打包命令执行完成后，会在项目根目录下的`build`目录下生成固件文件`merged-binary.bin`。
 这个`merged-binary.bin`就是要烧录到硬件上的固件文件。
 
 注意：如果执行到第二命令后，报了“zip”相关的错误，请忽略这个错误，只要`build`目录下生成固件文件`merged-binary.bin`
 ，对你没有太大影响，请继续。
 
-6. 烧录固件
+## 第7步 烧录固件
    将esp32设备连接电脑，使用chrome浏览器，打开以下网址
 
 ```
@@ -90,16 +120,19 @@ https://espressif.github.io/esp-launchpad/
 
 烧录成功且联网成功后，通过唤醒词唤醒小智，留意server端输出的控制台信息。
 
+## 常见问题
 以下是一些常见问题，供参考：
 
-[1、为什么我说的话，小智识别出来很多韩文、日文、英文](../README.md#1tts-%E7%BB%8F%E5%B8%B8%E5%A4%B1%E8%B4%A5%E7%BB%8F%E5%B8%B8%E8%B6%85%E6%97%B6-)
+[1、为什么我说的话，小智识别出来很多韩文、日文、英文](./FAQ.md)
 
-[2、为什么会出现“TTS 任务出错 文件不存在”？](../README.md#1tts-%E7%BB%8F%E5%B8%B8%E5%A4%B1%E8%B4%A5%E7%BB%8F%E5%B8%B8%E8%B6%85%E6%97%B6-)
+[2、为什么会出现“TTS 任务出错 文件不存在”？](./FAQ.md)
 
-[3、TTS 经常失败，经常超时](../README.md#1tts-%E7%BB%8F%E5%B8%B8%E5%A4%B1%E8%B4%A5%E7%BB%8F%E5%B8%B8%E8%B6%85%E6%97%B6-)
+[3、TTS 经常失败，经常超时](./FAQ.md)
 
-[4、如何提高小智对话响应速度？](../README.md#1tts-%E7%BB%8F%E5%B8%B8%E5%A4%B1%E8%B4%A5%E7%BB%8F%E5%B8%B8%E8%B6%85%E6%97%B6-)
+[4、使用Wifi能连接自建服务器，但是4G模式却接不上](./FAQ.md)
 
-[5、我说话很慢，停顿时小智老是抢话](../README.md#1tts-%E7%BB%8F%E5%B8%B8%E5%A4%B1%E8%B4%A5%E7%BB%8F%E5%B8%B8%E8%B6%85%E6%97%B6-)
+[5、如何提高小智对话响应速度？](./FAQ.md)
 
-[6、我想通过小智控制电灯、空调、远程开关机等操作](../README.md#1tts-%E7%BB%8F%E5%B8%B8%E5%A4%B1%E8%B4%A5%E7%BB%8F%E5%B8%B8%E8%B6%85%E6%97%B6-)
+[6、我说话很慢，停顿时小智老是抢话](./FAQ.md)
+
+[7、我想通过小智控制电灯、空调、远程开关机等操作](./FAQ.md)

docs/firmware-setting.md

@@ -0,0 +1,54 @@
+# 基于虾哥编译好的固件配置自定义服务器
+
+## 第1步 确认版本
+烧录虾哥已经编译好的[1.6.1版本以上固件](https://github.com/78/xiaozhi-esp32/releases)
+
+## 第2步 准备你的ota地址
+如果你按照教程使用的是全模块部署，就应该会有ota地址。
+
+此刻，请你用浏览器打开你的ota地址，例如我的ota地址
+```
+https://2662r3426b.vicp.fun/xiaozhi/ota/
+```
+
+如果显示“OTA接口运行正常，websocket集群数量：X”。那就往下。
+
+如果显示“OTA接口运行不正常”，大概是你还没在`智控台`配置`Websocket`地址。那就：
+
+- 1、使用超级管理员登录智控台
+
+- 2、顶部菜单点击`参数管理`
+
+- 3、在列表中找到`server.websocket`项目，输入你的`Websocket`地址。例如我的就是
+
+```
+wss://2662r3426b.vicp.fun/xiaozhi/v1/
+```
+
+配置完后，再使用浏览器刷新你的ota接口地址，看看是不是正常了。如果还不正常就，就再次确认一下Websocket是否正常启动，是否配置了Websocket地址。
+
+## 第3步 进入配网模式
+进入机器的配网模式，在页面顶部，点击“高级选项”，在里面输入你服务器的`ota`地址，点击保存。重启设备
+![请参考-OTA地址设置](../docs/images/firmware-setting-ota.png)
+
+## 第4步 唤醒小智，查看日志输出
+
+唤醒小智，看看日志是不是正常输出。
+
+
+## 常见问题
+以下是一些常见问题，供参考：
+
+[1、为什么我说的话，小智识别出来很多韩文、日文、英文](./FAQ.md)
+
+[2、为什么会出现“TTS 任务出错 文件不存在”？](./FAQ.md)
+
+[3、TTS 经常失败，经常超时](./FAQ.md)
+
+[4、使用Wifi能连接自建服务器，但是4G模式却接不上](./FAQ.md)
+
+[5、如何提高小智对话响应速度？](./FAQ.md)
+
+[6、我说话很慢，停顿时小智老是抢话](./FAQ.md)
+
+[7、我想通过小智控制电灯、空调、远程开关机等操作](./FAQ.md)

docs/fish-speech-integration.md

@@ -0,0 +1,72 @@
+登录AutoDL，租赁镜像
+选择镜像:
+```
+PyTorch / 2.1.0 / 3.10(ubuntu22.04) / cuda 12.1
+```
+
+机器开机后，设置学术加速
+```
+source /etc/network_turbo
+```
+
+进入工作目录
+```
+cd autodl-tmp/
+```
+
+拉取项目
+```
+git clone https://gitclone.com/github.com/fishaudio/fish-speech.git ; cd fish-speech
+```
+
+安装依赖
+```
+pip install -e.
+```
+
+如果报错，安装portaudio
+```
+apt-get install portaudio19-dev -y
+```
+
+安装后执行
+```
+pip install torch==2.3.1 torchvision==0.18.1 torchaudio==2.3.1 --index-url https://download.pytorch.org/whl/cu121
+```
+
+下载模型
+```
+cd tools
+python download_models.py 
+```
+
+下载完模型后运行接口
+```
+python -m tools.api_server --listen 0.0.0.0:6006 
+```
+
+然后用浏览器去到aotodl实例页面
+```
+https://autodl.com/console/instance/list
+```
+
+如下图点击你刚才机器的`自定义服务`按钮，开启端口转发服务
+![自定义服务](images/fishspeech/autodl-01.png)
+
+端口转发服务设置完成后，你本地电脑打开网址`http://localhost:6006/`，就可以访问fish-speech的接口了
+![服务预览](images/fishspeech/autodl-02.png)
+
+
+如果你是单模块部署，核心配置如下
+```
+selected_module:
+  TTS: FishSpeech
+TTS:
+  FishSpeech:
+    reference_audio: ["config/assets/wakeup_words.wav",]
+    reference_text: ["哈啰啊，我是小智啦，声音好听的台湾女孩一枚，超开心认识你耶，最近在忙啥，别忘了给我来点有趣的料哦，我超爱听八卦的啦",]
+    api_key: "123"
+    api_url: "http://127.0.0.1:6006/v1/tts"
+```
+
+然后重启服务

docs/homeassistant-integration.md

@@ -0,0 +1,226 @@
+# 小智ESP32-开源服务端与HomeAssistant集成指南
+
+[TOC]
+
+-----
+
+## 简介
+
+本文档将指导您如何将ESP32设备与HomeAssistant进行集成。
+
+## 前提条件
+
+- 已安装并配置好`HomeAssistant`
+- 本次我选择的模型是：免费的ChatGLM，它支持functioncall函数调用
+
+## 开始前的操作（必要）
+
+### 1. 获取HA的网络网络地址信息
+
+请访问你Home Assistant的网络地址，例如，我的HA的地址是192.168.4.7，端口则是默认的8123，则在浏览器打开
+
+```
+http://192.168.4.7:8123
+```
+
+> 手动查询 HA 的 IP 地址方法**（仅限小智esp32-server和HA部署在同一个网络设备[例如同一个wifi]下）**：
+>
+> 1. 进入 Home Assistant（前端）。
+>
+> 2. 点击左下角 **设置（Settings）** → **系统（System）** → **网络（Network）**。
+>
+> 3. 滑到最底部`Home Assistant 网址(Home Assistant website)`区域，在`本地网络(local network)`中，点击`眼睛`按钮，可以看到当前使用的 IP 地址（如 `192.168.1.10`）和网络接口。点击`复制连接(copy link)`可以直接复制。
+>
+>    ![image-20250504051716417](images/image-ha-integration-01.png)
+
+或，您已经设置了直接可以访问的Home Assistant的OAuth地址，您也可以在浏览器内直接访问
+
+```
+http://homeassistant.local:8123
+```
+
+### 2. 登录`Home Assistant`拿到开发密钥
+
+登录`HomeAssistant`，点击`左下角头像 -> 个人`，切换`安全`导航栏，划到底部`长期访问令牌`生成api_key，并复制保存，后续的方法都需要使用这个api key且仅出现一次（小tips: 您可以保存生成的二维码图像，后续可以扫描二维码再此提取api key）。
+
+## 方法1：小智社区共建的HA调用功能
+
+### 功能描述
+
+- 如您后续需要增加新的设备，该方法需要手动重启`xiaozhi-esp32-server服务端`以此更新设备信息**（重要**）。
+
+- 需要您确保已经在HomeAssistant中集成`Xiaomi Home`，并将米家的设备导入进`HomeAssistant`。
+
+- 需要您确保`xiaozhi-esp32-server智控台`能正常使用。
+
+- 我的`xiaozhi-esp32-server智控台`和`HomeAssistant`部署在同一台机器的另一个端口，版本是`0.3.10`
+
+  ```
+  http://192.168.4.7:8002
+  ```
+
+
+### 配置步骤
+
+#### 1. 登录`HomeAssistant`整理需要控制的设备清单
+
+登录`HomeAssistant`，点击`左下角的设置`，然后进入`设备与服务`，再点击顶部的`实体`。
+
+然后在实体中搜索你相关控制的开关，结果出来后，在列表中，点击其中一个结果，这是会出现一个开关的界面。
+
+在开关的界面，我们尝试点击开关，看看是开发会随着我们的点击开/关。如果能操作，说明是正常联网的。
+
+接着在开关面板找到设置按钮，点击后，可以查看这个开关的`实体标识符`。
+
+我们打开一个记事本，按照这样格式整理一条数据：
+
+位置+英文逗号+设备名称+英文逗号+`实体标识符`+英文分号
+
+例如，我在公司，我有一个玩具灯，他的标识符是switch.cuco_cn_460494544_cp1_on_p_2_1，那么就这个写这一条数据
+
+```
+公司,玩具灯,switch.cuco_cn_460494544_cp1_on_p_2_1;
+```
+
+当然最后我可能要操作两个灯，我的最终的结果是：
+
+```
+公司,玩具灯,switch.cuco_cn_460494544_cp1_on_p_2_1;
+公司,台灯,switch.iot_cn_831898993_socn1_on_p_2_1;
+```
+
+这段字符，我们称为“设备清单字符”需要保存好，等一下有用。
+
+#### 2. 登录`智控台`
+
+![image-20250504051716417](images/image-ha-integration-06.png)
+
+使用管理员账号，登录`智控台`。在`智能体管理`，找到你的智能体，再点击`配置角色`。
+
+将意图识别设置成`外挂的大模型意图识别`或`大模型自主函数调用`。这时你会看到右侧有一个`编辑功能`。点击`编辑功能`按钮，会弹出`功能管理`的框。
+
+在`功能管理`的框里，你需要勾选`HomeAssistant设备状态查询`和`HomeAssistant设备状态修改`。
+
+勾选后，在`已选功能`点击`HomeAssistant设备状态查询`，然后在`参数配置`里配置你的`HomeAssistant`地址、密钥、设备清单字符。
+
+编辑好后，点击`保存配置`，这时`功能管理`的框会隐藏，这时你再点击保存智能体配置。
+
+保存成功后，即可唤醒设备操作。
+
+#### 3. 唤醒设别进行控制
+
+尝试和esp32说，“打开XXX灯”
+
+## 方法2：小智将Home Assistant的语音助手作为LLM工具
+
+### 功能描述
+
+- 该方法有一个比较严重的缺点——**该方法无法使用小智开源生态的function_call插件功能的能力**，因为使用Home Assistant作为小智的LLM工具会将意图识别能力转让给Home Assistant。但是**这个方法是能体验到原生的Home Assistant操作功能，且小智的聊天能力不变**。如实在介意可以使用同样是Home Assistant支持的[方法3](##方法3：使用Home Assistant的MCP服务（推荐）)，能够最大程度体验到Home Assistant的功能。
+
+### 配置步骤：
+
+#### 1. 配置Home Assistant的大模型语音助手。
+
+**需要您提前配置好Home Assistant的语音助手或大模型工具。**
+
+#### 2. 获取Home Assistant的语言助手的Agent ID.
+
+1. 进入Home Assistant页面内。左侧点击`开发者助手`。
+2. 在打开的`开发者助手`内，点击`动作`选项卡（如图示操作1），在页面内的选项栏`动作`中，找到或输入`conversation.process（对话-处理）`并选择`对话（conversation）: 处理`（如图示操作2）。
+
+![image-20250504043539343](images/image-ha-integration-02.png)
+
+3. 在页面内勾选`代理(agent)`选项，在变成常亮的`对话代理(conversation agent)`内选择您步骤一配置好的语音助手名称，如图示，我这边配置好的是`ZhipuAi`并选择。
+
+![image-20250504043854760](images/image-ha-integration-03.png)
+
+4. 选中后，点击表单左下方的`进入YAML模式`。
+
+![image-20250504043951126](images/image-ha-integration-04.png)
+
+5. 复制其中的agent-id的值，例如图示中我的是`01JP2DYMBDF7F4ZA2DMCF2AGX2`(仅供参考)。
+
+![image-20250504044046466](images/image-ha-integration-05.png)
+
+6. 切换到小智开源服务端`xiaozhi-esp32-server`的`config.yaml`文件内，在LLM配置中，找到Home Assistant，设置您的Home Assistant的网络地址，Api key和刚刚查询到的agent_id。
+7. 修改`config.yaml`文件内的`selected_module`属性的`LLM`为`HomeAssistant`，`Intent`为`nointent`。
+8. 重启小智开源服务端`xiaozhi-esp32-server`即可正常使用。
+
+## 方法3：使用Home Assistant的MCP服务（推荐）
+
+### 功能描述
+
+- 需要您提前在Home Assistant内集成并安装好HA集成——[Model Context Protocol Server](https://www.home-assistant.io/integrations/mcp_server/)。
+
+- 这个方法与方法2都是HA官方提供的解决方法，与方法2不同的是，您可以正常使用小智开源服务端`xiaozhi-esp32-server`的开源共建的插件，同时允许您随意使用任何一个支持function_call功能的LLM大模型。
+
+### 配置步骤
+
+#### 1. 安装Home Assistant的MCP服务集成。
+
+集成官方网址——[Model Context Protocol Server](https://www.home-assistant.io/integrations/mcp_server/)。。
+
+或跟随以下手动操作。
+
+> - 前往Home Assistant页面的**[设置 > 设备和服务（Settings > Devices & Services.）](https://my.home-assistant.io/redirect/integrations)**。
+>
+> - 在右下角，选择 **[添加集成（Add Integration）](https://my.home-assistant.io/redirect/config_flow_start?domain=mcp_server)**按钮。
+>
+> - 从列表中选择**模型上下文协议服务器（Model Context Protocol Server）**。
+>
+> - 按照屏幕上的说明完成设置。
+
+#### 2. 配置小智开源服务端MCP配置信息
+
+
+进入`data`目录，找到`.mcp_server_settings.json`文件。
+
+如果你的`data`目录下没有`.mcp_server_settings.json`文件，
+- 请把在`xiaozhi-server`文件夹根目录的`mcp_server_settings.json`文件复制到`data`目录下，并重命名为`.mcp_server_settings.json`
+- 或[下载这个文件](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/main/main/xiaozhi-server/mcp_server_settings.json)，下载到`data`目录下，并重命名为`.mcp_server_settings.json`
+
+
+修改`"mcpServers"`里的这部分的内容：
+
+```json
+"Home Assistant": {
+      "command": "mcp-proxy",
+      "args": [
+        "http://YOUR_HA_HOST/mcp_server/sse"
+      ],
+      "env": {
+        "API_ACCESS_TOKEN": "YOUR_API_ACCESS_TOKEN"
+      }
+},
+```
+
+注意：
+
+1. **替换配置：**
+   - 替换`args`内的`YOUR_HA_HOST`为您的HA服务地址，如果你的服务地址已经包含了https/http字样（例如`http://192.168.1.101:8123`)，则只需要填入`192.168.1.101:8123`即可。
+   - 将`env`内`API_ACCESS_TOKEN`的`YOUR_API_ACCESS_TOKEN`替换成您之前获取到的开发密钥api key。
+2. **如果你添加配置是在`"mcpServers"`的括号内后续没有新的`mcpServers`的配置时，需要把最后的逗号`,`移除**，否则可能会解析失败。
+
+**最后效果参考以下（参考如下）**：
+
+```json
+ "mcpServers": {
+    "Home Assistant": {
+      "command": "mcp-proxy",
+      "args": [
+        "http://192.168.1.101:8123/mcp_server/sse"
+      ],
+      "env": {
+        "API_ACCESS_TOKEN": "abcd.efghi.jkl"
+      }
+    }
+  }
+```
+
+#### 3. 配置小智开源服务端的系统配置
+
+1. **选择任意一款支持function_call的LLM大模型作为小智的LLM聊天助手（但不要选择Home Assistant作为LLM工具）**，本次我选择的模型是：免费的ChatGLM，它支持functioncall函数调用，但部分时候调用不太稳定，如果像追求稳定建议把LLM设置成：DoubaoLLM，使用的具体model_name是：doubao-1-5-pro-32k-250115。
+
+2. 切换到小智开源服务端`xiaozhi-esp32-server`的`config.yaml`文件内，设置您的LLM大模型配置，并且将`selected_module`配置的`Intent`调整为`function_call`。
+
+3. 重启小智开源服务端`xiaozhi-esp32-server`即可正常使用。

docs/huoshan-streamTTS-voice-cloning.md

@@ -0,0 +1,58 @@
+# 智控台 火山双流式语音合成+音色克隆配置教程
+
+本教程分为4个阶段：准备阶段、配置阶段、克隆阶段、使用阶段。主要是介绍通过智控台配置火山双流式语音合成+音色克隆的过程。
+
+## 第一阶段：准备阶段
+超级管理员先预先把火山引擎服务开通好，获取到App Id，Access Token。默认火上引擎会赠送一个音色资源。这个音色资源需要把它复制到本项目里。
+
+如果你想克隆多个音色，需要购买开通多个音色资源。只要把每个音色资源的声音ID(S_xxxxx)复制到本项目。然后分配给系统的账号使用即可。以下是详细步骤：
+
+### 1.开通火山引擎服务
+访问 https://console.volcengine.com/speech/app  在应用管理创建应用，勾选语音合成大模型和声音复刻大模型。
+
+### 2.获取音色资源ID
+访问 https://console.volcengine.com/speech/service/9999 复制三项内容，分别是App Id，Access Token以及声音ID(S_xxxxx)。如图
+
+![获取音色资源](images/image-clone-integration-01.png)
+
+## 第二阶段：配置火山引擎服务
+
+### 1.填写火山引擎配置
+
+使用超级管理员账号登录智控台，点击顶部【模型配置】，再点击模型配置页面左侧的【语音合成】，搜索找到“火山双流式语音合成”，点击修改，将你火山引擎的`App Id`填入到【应用ID】字段里，将`Access Token`填入到【访问令牌】字段里。然后保存。
+
+### 2.将音色资源ID分配给系统账号
+
+使用超级管理员账号登录智控台，点击顶部`参数字典`，在下拉菜单中，点击`系统功能配置`页面。在页面上勾选`音色克隆`，点击保存配置。即可在顶部菜单看到`音色克隆`按钮。
+
+使用超级管理员账号登录智控台，点击顶部【音色克隆】、【音色资源】。
+
+点击新增按钮，在【平台名称】选择“火山双流式语音合成”；
+
+在【音色资源ID】填入你火山引擎的声音资源ID(S_xxxxx)，填入后按回车；
+
+在【归属账号】选择你要分配给的系统账号，你可以分配给你自己。然后点击保存
+
+## 第三阶段：克隆阶段
+
+如果登录后，点击顶部【音色克隆】》【音色克隆】，显示【您的账号暂无音色资源请联系管理员分配音色资源】，说明你在第二阶段还没有把音色资源ID分配给这个账号。那就是回到第二阶段，分配音色资源给对应的账号。
+
+如果登录后，点击顶部【音色克隆】》【音色克隆】，能看到对应的音色列表。请继续。
+
+在列表里会看到对应的音色列表。选择其中一个音色资源，点击【上传音频】按钮。上传后，可以试听一下声音或者截取某段声音。确认后点击【上传音频】按钮。
+![上传音频](images/image-clone-integration-02.png)
+
+上传音频后，在列表里会看到对应的音色会变成“待复刻”状态。点击【立即复刻】按钮。等1~2秒会返回结果。
+
+如果复刻失败，请将鼠标放到“错误信息”图标上，会显示失败的原因。
+
+如果复刻成功，在列表里会看到对应的音色会变成“训练成功”状态。此时你可以点击【声音名称】栏的修改按钮，修改音色资源的名称，方便后期选择使用。
+
+## 第四阶段：使用阶段
+
+点击顶部【智能体管理】，选择任意一个智能体，点击【配置角色】按钮。
+
+语音合成(TTS)选择“火山双流式语音合成”。在列表里，找到名字带有“克隆音色”的音色资源（如图），选择它，点击保存。
+![选择音色](images/image-clone-integration-03.png)
+
+接下来，可以唤醒小智和它对话。

docs/index-stream-integration.md

@@ -0,0 +1,195 @@
+# IndexStreamTTS 使用指南
+
+## 环境准备
+### 1. 克隆项目 
+```bash 
+git clone https://github.com/Ksuriuri/index-tts-vllm.git
+```
+进入解压后的目录
+```bash
+cd index-tts-vllm
+```
+切换到指定版本 (使用VLLM-0.10.2的历史版本)
+```bash
+git checkout 224e8d5e5c8f66801845c66b30fa765328fd0be3
+```
+
+### 2. 创建并激活 conda 环境
+```bash 
+conda create -n index-tts-vllm python=3.12
+conda activate index-tts-vllm
+```
+
+### 3. 安装PyTorch 需要版本为2.8.0（最新版）
+#### 查看显卡最高支持的版本和实际安装的版本
+```bash
+nvidia-smi
+nvcc --version
+``` 
+#### 驱动支持的最高 CUDA 版本
+```bash
+CUDA Version: 12.8
+```
+#### 实际安装的 CUDA 编译器版本
+```bash
+Cuda compilation tools, release 12.8, V12.8.89
+```
+#### 那么对应的安装命令（pytorch默认给的是12.8的驱动版本）
+```bash
+pip install torch torchvision
+```
+需要 pytorch 版本 2.8.0（对应 vllm 0.10.2），具体安装指令请参考：[pytorch 官网](https://pytorch.org/get-started/locally/)
+
+### 4. 安装依赖
+```bash 
+pip install -r requirements.txt
+```
+
+### 5. 下载模型权重
+### 方案一：下载官方权重文件后转换
+此为官方权重文件，下载到本地任意路径即可，支持 IndexTTS-1.5 的权重  
+| HuggingFace                                                   | ModelScope                                                          |
+|---------------------------------------------------------------|---------------------------------------------------------------------|
+| [IndexTTS](https://huggingface.co/IndexTeam/Index-TTS)        | [IndexTTS](https://modelscope.cn/models/IndexTeam/Index-TTS)        |
+| [IndexTTS-1.5](https://huggingface.co/IndexTeam/IndexTTS-1.5) | [IndexTTS-1.5](https://modelscope.cn/models/IndexTeam/IndexTTS-1.5) |
+
+下面以ModelScope的安装方法为例  
+#### 请注意：git需要安装并初始化启用lfs（如已安装可以跳过）
+```bash
+sudo apt-get install git-lfs
+git lfs install
+```
+创建模型目录，并拉取模型
+```bash 
+mkdir model_dir
+cd model_dir
+git clone https://www.modelscope.cn/IndexTeam/IndexTTS-1.5.git
+```
+
+#### 模型权重转换
+```bash 
+bash convert_hf_format.sh /path/to/your/model_dir
+```
+例如：你下载的IndexTTS-1.5模型存放在model_dir目录下，则执行以下命令
+```bash
+bash convert_hf_format.sh model_dir/IndexTTS-1.5
+```
+此操作会将官方的模型权重转换为 transformers 库兼容的版本，保存在模型权重路径下的 vllm 文件夹中，方便后续 vllm 库加载模型权重
+
+### 6. 更改接口适配一下项目
+接口返回数据与项目不适配需要调整一下，使其直接返回音频数据
+```bash
+vi api_server.py
+```
+```bash 
+@app.post("/tts", responses={
+    200: {"content": {"application/octet-stream": {}}},
+    500: {"content": {"application/json": {}}}
+})
+async def tts_api(request: Request):
+    try:
+        data = await request.json()
+        text = data["text"]
+        character = data["character"]
+
+        global tts
+        sr, wav = await tts.infer_with_ref_audio_embed(character, text)
+
+        return Response(content=wav.tobytes(), media_type="application/octet-stream")
+        
+    except Exception as ex:
+        tb_str = ''.join(traceback.format_exception(type(ex), ex, ex.__traceback__))
+        print(tb_str)
+        return JSONResponse(
+            status_code=500,
+            content={
+                "status": "error",
+                "error": str(tb_str)
+            }
+        )
+```
+
+### 7.编写sh启动脚本（请注意要在相应的conda环境下运行）
+```bash 
+vi start_api.sh
+```
+### 将下面内容粘贴进去并按:输入wq保存  
+#### 脚本中的/home/system/index-tts-vllm/model_dir/IndexTTS-1.5 请自行修改为实际路径
+```bash
+# 激活conda环境
+conda activate index-tts-vllm 
+echo "激活项目conda环境"
+sleep 2
+# 查找占用11996端口的进程号
+PID_VLLM=$(sudo netstat -tulnp | grep 11996 | awk '{print $7}' | cut -d'/' -f1)
+
+# 检查是否找到进程号
+if [ -z "$PID_VLLM" ]; then
+  echo "没有找到占用11996端口的进程"
+else
+  echo "找到占用11996端口的进程，进程号为: $PID_VLLM"
+  # 先尝试普通kill，等待2秒
+  kill $PID_VLLM
+  sleep 2
+  # 检查进程是否还在
+  if ps -p $PID_VLLM > /dev/null; then
+    echo "进程仍在运行，强制终止..."
+    kill -9 $PID_VLLM
+  fi
+  echo "已终止进程 $PID_VLLM"
+fi
+
+# 查找占用VLLM::EngineCore进程
+GPU_PIDS=$(ps aux | grep -E "VLLM|EngineCore" | grep -v grep | awk '{print $2}')
+
+# 检查是否找到进程号
+if [ -z "$GPU_PIDS" ]; then
+  echo "没有找到VLLM相关进程"
+else
+  echo "找到VLLM相关进程，进程号为: $GPU_PIDS"
+  # 先尝试普通kill，等待2秒
+  kill $GPU_PIDS
+  sleep 2
+  # 检查进程是否还在
+  if ps -p $GPU_PIDS > /dev/null; then
+    echo "进程仍在运行，强制终止..."
+    kill -9 $GPU_PIDS
+  fi
+  echo "已终止进程 $GPU_PIDS"
+fi
+
+# 创建tmp目录（如果不存在）
+mkdir -p tmp
+
+# 后台运行api_server.py，日志重定向到tmp/server.log
+nohup python api_server.py --model_dir /home/system/index-tts-vllm/model_dir/IndexTTS-1.5 --port 11996 > tmp/server.log 2>&1 &
+echo "api_server.py 已在后台运行，日志请查看 tmp/server.log"
+```
+给脚本执行权限并运行脚本
+```bash 
+chmod +x start_api.sh
+./start_api.sh
+```
+日志会在tmp/server.log中输出，可以通过以下命令查看日志情况
+```bash
+tail -f tmp/server.log
+```
+如果显卡内存足够，可在脚本中添加启动参数 ----gpu_memory_utilization 来调整显存占用比例，默认值为 0.25
+
+## 音色配置
+index-tts-vllm支持通过配置文件注册自定义音色，支持单音色和混合音色配置。  
+在项目根目录下的assets/speaker.json文件中配置自定义音色
+### 配置格式说明
+```bash
+{
+    "说话人名称1": [
+        "音频文件路径1.wav",
+        "音频文件路径2.wav"
+    ],
+    "说话人名称2": [
+        "音频文件路径3.wav"
+    ]
+}
+```
+### 注意 （配置角色后需重启服务进行音色注册）
+添加后需在智控台中添加相应的说话人（单模块则更换相应的voice）

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

@@ -0,0 +1,126 @@
+# MCP 接入点部署使用指南
+
+本教程包含3个部分
+- 1、如何部署MCP接入点这个服务
+- 2、全模块部署时，怎么配置MCP接入点
+- 3、单模块部署时，怎么配置MCP接入点
+
+# 1、如何部署MCP接入点这个服务
+
+## 第一步，下载mcp接入点项目源码
+
+浏览器打开[mcp接入点项目地址](https://github.com/xinnan-tech/mcp-endpoint-server)
+
+打开完，找到页面中一个绿色的按钮，写着`Code`的按钮，点开它，然后你就看到`Download ZIP`的按钮。
+
+点击它，下载本项目源码压缩包。下载到你电脑后，解压它，此时它的名字可能叫`mcp-endpoint-server-main`
+你需要把它重命名成`mcp-endpoint-server`。
+
+## 第二步，启动程序
+这个项目是一个很简单的项目，建议使用docker运行。不过如果你不想使用docker运行，你可以参考[这个页面](https://github.com/xinnan-tech/mcp-endpoint-server/blob/main/README_dev.md)使用源码运行。以下是docker运行的方法
+
+```
+# 进入本项目源码根目录
+cd mcp-endpoint-server
+
+# 清除缓存
+docker compose -f docker-compose.yml down
+docker stop mcp-endpoint-server
+docker rm mcp-endpoint-server
+docker rmi ghcr.nju.edu.cn/xinnan-tech/mcp-endpoint-server:latest
+
+# 启动docker容器
+docker compose -f docker-compose.yml up -d
+# 查看日志
+docker logs -f mcp-endpoint-server
+```
+
+此时，日志里会输出类似以下的日志
+```
+250705 INFO-=====下面的地址分别是智控台/单模块MCP接入点地址====
+250705 INFO-智控台MCP参数配置: http://172.22.0.2:8004/mcp_endpoint/health?key=abc
+250705 INFO-单模块部署MCP接入点: ws://172.22.0.2:8004/mcp_endpoint/mcp/?token=def
+250705 INFO-=====请根据具体部署选择使用，请勿泄露给任何人======
+```
+
+请你把两个接口地址复制出来：
+
+由于你是docker部署，切不可直接使用上面的地址！
+
+由于你是docker部署，切不可直接使用上面的地址！
+
+由于你是docker部署，切不可直接使用上面的地址！
+
+你先把地址复制出来，放在一个草稿里，你要知道你的电脑的局域网ip是什么，例如我的电脑局域网ip是`192.168.1.25`，那么
+原来我的接口地址
+```
+智控台MCP参数配置: http://172.22.0.2:8004/mcp_endpoint/health?key=abc
+单模块部署MCP接入点: ws://172.22.0.2:8004/mcp_endpoint/mcp/?token=def
+```
+就要改成
+```
+智控台MCP参数配置: http://192.168.1.25:8004/mcp_endpoint/health?key=abc
+单模块部署MCP接入点: ws://192.168.1.25:8004/mcp_endpoint/mcp/?token=def
+```
+
+改好后，请使用浏览器直接访问`智控台MCP参数配置`。当浏览器出现类似这样的代码，说明是成功了。
+```
+{"result":{"status":"success","connections":{"tool_connections":0,"robot_connections":0,"total_connections":0}},"error":null,"id":null,"jsonrpc":"2.0"}
+```
+
+请你保留好上面两个`接口地址`，下一步要用到。
+
+# 2、全模块部署时，怎么配置MCP接入点
+首先，你要开启MCP接入点功能。在智控台，点击顶部`参数字典`，在下拉菜单中，点击`系统功能配置`页面。在页面上勾选`MCP接入点`，点击`保存配置`。在`角色配置`页面，点击`编辑功能`按钮，即可看到`mcp接入点`功能。
+
+如果你是全模块部署，使用管理员账号，登录智控台，点击顶部`参数字典`，选择`参数管理`功能。
+
+然后搜索参数`server.mcp_endpoint`，此时，它的值应该是`null`值。
+点击修改按钮，把上一步得来的`智控台MCP参数配置`粘贴到`参数值`里。然后保存。
+
+如果能保存成功，说明一切顺利，你可以去智能体查看效果了。如果不成功，说明智控台无法访问mcp接入点，很大概率是网络防火墙，或者没有填写正确的局域网ip。
+
+# 3、单模块部署时，怎么配置MCP接入点
+
+如果你是单模块部署，找到你的配置文件`data/.config.yaml`。
+在配置文件搜索`mcp_endpoint`，如果没有找到，你就增加`mcp_endpoint`配置。类似我是就是这样
+```
+server:
+  websocket: ws://你的ip或者域名:端口号/xiaozhi/v1/
+  http_port: 8002
+log:
+  log_level: INFO
+
+# 此处可能还更多配置..
+
+mcp_endpoint: 你的接入点websocket地址
+```
+这时，请你把`如何部署MCP接入点这个服务`中得到的`单模块部署MCP接入点` 粘贴到 `mcp_endpoint`中。类似这样
+
+```
+server:
+  websocket: ws://你的ip或者域名:端口号/xiaozhi/v1/
+  http_port: 8002
+log:
+  log_level: INFO
+
+# 此处可能还更多配置
+
+mcp_endpoint: ws://192.168.1.25:8004/mcp_endpoint/mcp/?token=def
+```
+
+配置好后，启动单模块会输出如下的日志。
+```
+250705[__main__]-INFO-初始化组件: vad成功 SileroVAD
+250705[__main__]-INFO-初始化组件: asr成功 FunASRServer
+250705[__main__]-INFO-OTA接口是          http://192.168.1.25:8002/xiaozhi/ota/
+250705[__main__]-INFO-视觉分析接口是     http://192.168.1.25:8002/mcp/vision/explain
+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请启动digital-human模块，打开浏览器交互测试
+250705[__main__]-INFO-=============================================================
+```
+
+如上，如果能输出类似的`mcp接入点是`中`ws://192.168.1.25:8004/mcp_endpoint/mcp/?token=abc`说明配置成功了。
+

docs/mcp-endpoint-integration.md

@@ -0,0 +1,94 @@
+# MCP 接入点使用指南
+
+本教程以虾哥开源的mcp计算器功能为示例，介绍如何将自己自定义的mcp服务接入到自己的接入点里。
+
+本教程的前提是，你的`xiaozhi-server`已经启用了mcp接入点功能，如果你还没启用，可以先根据[这个教程](./mcp-endpoint-enable.md)启用。
+
+# 如何为智能体接入一个简单的mcp功能，如计算器功能
+
+### 如果你是全模块部署
+如果你是全模块部署，你可以进入智控台，智能体管理，点击`配置角色`，在`意图识别`的右边，有一个`编辑功能`的按钮。
+
+点击这个按钮。在弹出的页面里，位于底部，会有`MCP接入点`，正常来说，会显示这个智能体的`MCP接入点地址`，接下来，我们来给这个智能体扩展一个基于MCP技术的计算器的功能。
+
+这个`MCP接入点地址`很重要，你等一下会用到。
+
+### 如果你是单模块部署
+如果你是单模块部署，且你已经在配置文件里配置了MCP接入点地址，那么正常来说，单模块部署启动的时候，会输出如下的日志。
+```
+250705[__main__]-INFO-初始化组件: vad成功 SileroVAD
+250705[__main__]-INFO-初始化组件: asr成功 FunASRServer
+250705[__main__]-INFO-OTA接口是          http://192.168.1.25:8002/xiaozhi/ota/
+250705[__main__]-INFO-视觉分析接口是     http://192.168.1.25:8002/mcp/vision/explain
+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请启动digital-human模块，打开浏览器交互测试
+250705[__main__]-INFO-=============================================================
+```
+
+如上，输出`mcp接入点是`中`ws://192.168.1.25:8004/mcp_endpoint/mcp/?token=abc`就是你的`MCP接入点地址`。
+
+这个`MCP接入点地址`很重要，你等一下会用到。
+
+## 第一步 下载虾哥MCP计算器项目代码
+
+浏览器打开虾哥写的[计算器项目](https://github.com/78/mcp-calculator)，
+
+打开完，找到页面中一个绿色的按钮，写着`Code`的按钮，点开它，然后你就看到`Download ZIP`的按钮。
+
+点击它，下载本项目源码压缩包。下载到你电脑后，解压它，此时它的名字可能叫`mcp-calculatorr-main`
+你需要把它重命名成`mcp-calculator`。接下来，我们用命令行进入项目目录即安装依赖
+
+
+```bash
+# 进入项目目录
+cd mcp-calculator
+
+conda remove -n mcp-calculator --all -y
+conda create -n mcp-calculator python=3.10 -y
+conda activate mcp-calculator
+
+pip install -r requirements.txt
+```
+
+## 第二步 启动
+
+启动前，先从你的智控台的智能体里，复制到了MCP接入点的地址。
+
+例如我的智能体的mcp地址是
+```
+ws://192.168.1.25:8004/mcp_endpoint/mcp/?token=abc
+```
+
+开始输入命令
+
+```bash
+export MCP_ENDPOINT=ws://192.168.1.25:8004/mcp_endpoint/mcp/?token=abc
+```
+
+输入完后，启动程序
+
+```bash
+python mcp_pipe.py calculator.py
+```
+
+### 如果你是智控台部署
+如果你是智控台部署，启动完后，你再进入智控台，点击刷新MCP的接入状态，就会看到你扩展的功能列表了。
+
+### 如果你是单模块部署
+如果你是单模块部署，当设备连接后，会输出类似的日志，说明成功了
+
+```
+250705 -INFO-正在初始化MCP接入点: wss://2662r3426b.vicp.fun/mcp_e 
+250705 -INFO-发送MCP接入点初始化消息
+250705 -INFO-MCP接入点连接成功
+250705 -INFO-MCP接入点初始化成功
+250705 -INFO-统一工具处理器初始化完成
+250705 -INFO-MCP接入点服务器信息: name=Calculator, version=1.9.4
+250705 -INFO-MCP接入点支持的工具数量: 1
+250705 -INFO-所有MCP接入点工具已获取，客户端准备就绪
+250705 -INFO-工具缓存已刷新
+250705 -INFO-当前支持的函数列表: [ 'get_time', 'get_lunar', 'play_music', 'get_weather', 'handle_exit_intent', 'calculator']
+```
+如果包含了 `'calculator'`，说明设备将可以根据意图识别，调用计算器这个工具。

docs/mcp-get-device-info.md

@@ -0,0 +1,40 @@
+# MCP 方法如何获取设备信息
+
+本教程将指导你如何使用MCP方法获取设备信息。
+
+第一步：自定义你的`agent-base-prompt.txt`文件
+
+把xiaozhi-server目录的`agent-base-prompt.txt`文件内容复制到你的`data`目录下，并重命名为`.agent-base-prompt.txt`。
+
+第二步：修改`data/.agent-base-prompt.txt`文件，找到`<context>`标签，在标签内容中添加以下代码内容：
+```
+- **设备ID：** {{device_id}}
+```
+
+添加完成后，你的`data/.agent-base-prompt.txt`文件的`<context>`标签内容大致如下：
+```
+<context>
+【重要！以下信息已实时提供，无需调用工具查询，请直接使用：】
+- **设备ID：** {{device_id}}
+- **当前时间：** {{current_time}}
+- **今天日期：** {{today_date}} ({{today_weekday}})
+- **今天农历：** {{lunar_date}}
+- **用户所在城市：** {{local_address}}
+- **当地未来7天天气：** {{weather_info}}
+</context>
+```
+
+第三步：修改`data/.config.yaml`文件，找到`agent-base-prompt`配置，修改前内容如下：
+```
+prompt_template: agent-base-prompt.txt
+```
+修改成
+```
+prompt_template: data/.agent-base-prompt.txt
+```
+
+第四步：重启你的xiaozhi-server服务。
+
+第五步：在你的mcp方法增加名称为`device_id`,类型为`string`,描述为`设备ID`的参数。
+
+第六步：重新唤醒小智，让他调用mcp方法，查看你的mcp方法是否可以获取`设备ID`。

docs/mcp-vision-integration.md

@@ -0,0 +1,171 @@
+# 视觉模型使用指南
+本教程分为两部分：
+- 第一部分：单模块运行xiaozhi-server开启视觉模型
+- 第二部分：全模块运行时，如何开启视觉模型
+
+开启视觉模型前，你需要准备三件事：
+- 你需要准备一台带摄像头的设备，而且这台设备已经在虾哥仓库里，实现了调用摄像头功能。例如`立创·实战派ESP32-S3开发板`
+- 你设备固件的版本升级到1.6.6及以上
+- 你已经成功跑通基础对话模块
+
+## 单模块运行xiaozhi-server开启视觉模型
+
+### 第一步确认网络
+由于视觉模型会默认启动8003端口。
+
+如果你是docker运行，请确认一下你的`docker-compose.yml`是否放了`8003`端口，如果没有就更新最新的`docker-compose.yml`文件
+
+如果你是源码运行，确认防火墙是否放行`8003`端口
+
+### 第二步选择你的视觉模型
+打开你的`data/.config.yaml`文件，设置你的`selected_module.VLLM`设置为某个视觉模型。目前我们已经支持`openai`类型接口的视觉模型。`ChatGLMVLLM`就是其中一款兼容`openai`的模型。
+
+```
+selected_module:
+  VAD: ..
+  ASR: ..
+  LLM: ..
+  VLLM: ChatGLMVLLM
+  TTS: ..
+  Memory: ..
+  Intent: ..
+```
+
+假设我们使用`ChatGLMVLLM`作为视觉模型，那我们需要先登录[智谱AI](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)网站，申请密钥。如果你之前已经申请过了密钥，可以复用这个密钥。
+
+在你的配置文件中，增加这个配置，如果已经有了这个配置，就设置好你的api_key。
+
+```
+VLLM:
+  ChatGLMVLLM:
+    api_key: 你的api_key
+```
+
+### 第三步启动xiaozhi-server服务
+如果你是源码，就输入命令启动
+```
+python app.py
+```
+如果你是docker运行，就重启容器
+```
+docker restart xiaozhi-esp32-server
+```
+
+启动后会输出以下内容的日志。
+
+```
+2025-06-01 **** - OTA接口是           http://192.168.4.7:8003/xiaozhi/ota/
+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请启动digital-human模块，打开浏览器交互测试
+2025-06-01 **** - =============================================================
+```
+
+启动后，使用使用浏览器打开日志里`视觉分析接口`连接。看看输出了什么？如果你是linux,没有浏览器，你可以执行这个命令：
+```
+curl -i 你的视觉分析接口
+```
+
+正常来说会这样显示
+```
+MCP Vision 接口运行正常，视觉解释接口地址是：http://xxxx:8003/mcp/vision/explain
+```
+
+请注意，如果你是公网部署，或者docker部署，一定要改一下你的`data/.config.yaml`里这个配置
+```
+server:
+  vision_explain: http://你的ip或者域名:端口号/mcp/vision/explain
+```
+
+为什么呢？因为视觉解释接口需要下发到设备，如果你的地址是局域网地址，或者是docker内部地址，设备是无法访问的。
+
+假设你的公网地址是`111.111.111.111`，那么`vision_explain`应该这么配
+
+```
+server:
+  vision_explain: http://111.111.111.111:8003/mcp/vision/explain
+```
+
+如果你的MCP Vision 接口运行正常，且你也试着用浏览器访问正常打开下发的`视觉解释接口地址`，请继续下一步
+
+### 第四步 设备唤醒开启
+
+对设备说“请打开摄像头，说你你看到了什么”
+
+留意xiaozhi-server的日志输出，看看有没有报错。
+
+
+## 全模块运行时，如何开启视觉模型
+
+### 第一步 确认网络
+由于视觉模型会默认启动8003端口。
+
+如果你是docker运行，请确认一下你的`docker-compose_all.yml`是否映射了`8003`端口，如果没有就更新最新的`docker-compose_all.yml`文件
+
+如果你是源码运行，确认防火墙是否放行`8003`端口
+
+### 第二步 确认你配置文件
+
+打开你的`data/.config.yaml`文件，确认一下你的配置文件的结构，是否和`data/config_from_api.yaml`一样。如果不一样，或缺少某项，请补齐。
+
+### 第三步 配置视觉模型密钥
+
+那我们需要先登录[智谱AI](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)网站，申请密钥。如果你之前已经申请过了密钥，可以复用这个密钥。
+
+登录`智控台`，顶部菜单点击`模型配置`，在左侧栏点击`视觉打语言模型`，找到`VLLM_ChatGLMVLLM`，点击修改按钮，在弹框中，在`API密钥`输入你密钥，点击保存。
+
+保存成功后，去到你需要测试的智能体哪里，点击`配置角色`，在打开的内容里，查看`视觉大语言模型(VLLM)`是否选择了刚才的视觉模型。点击保存。
+
+### 第三步 启动xiaozhi-server模块
+如果你是源码，就输入命令启动
+```
+python app.py
+```
+如果你是docker运行，就重启容器
+```
+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请启动digital-human模块，打开浏览器交互测试
+2025-06-01 **** - =============================================================
+```
+
+启动后，使用使用浏览器打开日志里`视觉分析接口`连接。看看输出了什么？如果你是linux,没有浏览器，你可以执行这个命令：
+```
+curl -i 你的视觉分析接口
+```
+
+正常来说会这样显示
+```
+MCP Vision 接口运行正常，视觉解释接口地址是：http://xxxx:8003/mcp/vision/explain
+```
+
+请注意，如果你是公网部署，或者docker部署，一定要改一下你的`data/.config.yaml`里这个配置
+```
+server:
+  vision_explain: http://你的ip或者域名:端口号/mcp/vision/explain
+```
+
+为什么呢？因为视觉解释接口需要下发到设备，如果你的地址是局域网地址，或者是docker内部地址，设备是无法访问的。
+
+假设你的公网地址是`111.111.111.111`，那么`vision_explain`应该这么配
+
+```
+server:
+  vision_explain: http://111.111.111.111:8003/mcp/vision/explain
+```
+
+如果你的MCP Vision 接口运行正常，且你也试着用浏览器访问正常打开下发的`视觉解释接口地址`，请继续下一步
+
+### 第四步 设备唤醒开启
+
+对设备说“请打开摄像头，说你你看到了什么”
+
+留意xiaozhi-server的日志输出，看看有没有报错。

docs/mqtt-gateway-integration.md

@@ -0,0 +1,187 @@
+# MQTT 网关部署教程
+
+`xiaozhi-esp32-server`项目，可结合虾哥开源的[xiaozhi-mqtt-gateway](https://github.com/78/xiaozhi-mqtt-gateway) 项目进行简单改造，即可实现小智硬件MQTT+UDP连接。
+本教程分为三部分，你可以根据你是全模块部署还是单模块部署，选择对应的部分接入MQTT网关：
+- 第一部分：部署MQTT网关
+- 第二部分：全模块运行实现小智硬件MQTT+UDP连接
+- 第三部分：单模块运行xiaozhi-server实现小智硬件MQTT+UDP连接
+
+## 准备阶段
+准备好你的`xiaozhi-server`的`mqtt-websocket`连接地址。在你原来的`websocket地址`基础上，添加`?from=mqtt_gateway`字符，就可以得到`mqtt-websocket`连接地址
+
+1、如果你是源码部署，你的`mqtt-websocket`地址是：
+```
+ws://127.0.0.1:8000/xiaozhi/v1/?from=mqtt_gateway
+```
+
+2、如果你是docker部署，你的`mqtt-websocket`地址是
+```
+ws://你宿主机局域网IP:8000/xiaozhi/v1/?from=mqtt_gateway
+```
+
+## 重要提示
+
+如果你是服务器部署，需要确保服务器`1883`、`8884`、`8007`端口都对外开放。`8884`选择的协议类型是`UDP`，其他是`TCP`。
+
+如果你是服务器部署，需要确保服务器`1883`、`8884`、`8007`端口都对外开放。`8884`选择的协议类型是`UDP`，其他是`TCP`。
+
+如果你是服务器部署，需要确保服务器`1883`、`8884`、`8007`端口都对外开放。`8884`选择的协议类型是`UDP`，其他是`TCP`。
+
+
+## 第一部分：部署MQTT网关
+
+1. 克隆[改造后的xiaozhi-mqtt-gateway项目](https://github.com/xinnan-tech/xiaozhi-mqtt-gateway.git)：
+```bash
+git clone https://ghfast.top/https://github.com/xinnan-tech/xiaozhi-mqtt-gateway.git
+cd xiaozhi-mqtt-gateway
+```
+
+2. 安装依赖：
+```bash
+npm install
+npm install -g pm2
+```
+
+3. 配置 `config.json`：
+```bash
+cp config/mqtt.json.example config/mqtt.json
+```
+
+4. 编辑配置文件 config/mqtt.json，把你在`本文准备阶段`的`mqtt-websocket`地址替换到`chat_servers`里。例如源码部署的`xiaozhi-server`就是如下配置：
+
+``` 
+{
+    "production": {
+        "chat_servers": [
+            "ws://127.0.0.1:8000/xiaozhi/v1/?from=mqtt_gateway"
+        ]
+    },
+    "debug": false,
+    "max_mqtt_payload_size": 8192,
+    "mcp_client": {
+        "capabilities": {
+        },
+        "client_info": {
+            "name": "xiaozhi-mqtt-client",
+            "version": "1.0.0"
+        },
+        "max_tools_count": 128
+    }
+}
+```
+5. 在项目根目录创建下`.env`文件，并设置以下环境变量:
+```
+PUBLIC_IP=your-ip         # 服务器公网IP
+MQTT_PORT=1883            # MQTT服务器端口
+UDP_PORT=8884             # UDP服务器端口
+API_PORT=8007             # 管理API端口
+MQTT_SIGNATURE_KEY=test   # MQTT签名密钥
+SERVER_SECRET=Te1st12134  # 服务器密钥，请保持和智控台（server.secret）一致或者和xiaozhi-server里（server.auth_key）保持一致
+```
+请注意`PUBLIC_IP`配置，确保其与实际公网IP一致，如果有域名就填域名。
+
+`MQTT_SIGNATURE_KEY` 是用于MQTT连接认证的密钥，最好设置成复杂一点的，最好是设置成8个字符以上且同时包含大小写字母，这个密钥稍后还会用到。
+
+- 注意不要用简单的密码，比如`123456`、`test`等。
+- 注意不要用简单的密码，比如`123456`、`test`等。
+- 注意不要用简单的密码，比如`123456`、`test`等。
+
+`SERVER_SECRET` 是用生成websocket连接的认证信息。
+
+1、如果你是全模块部署，且你的智控台的参数管理里`server.auth.enabled`设置成了`true`，那么，`SERVER_SECRET`需要和智控台（`server.secret`）保持一致。
+
+2、如果你是单模块部署，且你在配置文件里把`server.auth.enabled`设置成了`true`，那么，`SERVER_SECRET`需要和配置文件里（`server.auth_key`）保持一致。
+
+
+6. 启动MQTT网关
+```
+# 启动服务
+pm2 start ecosystem.config.js
+
+# 查看日志
+pm2 logs xz-mqtt
+```
+
+当你看到如下日志，说明MQTT网关启动成功：
+```
+0|xz-mqtt  | 2025-09-11T12:14:48: MQTT 服务器正在监听端口 1883
+0|xz-mqtt  | 2025-09-11T12:14:48: UDP 服务器正在监听 x.x.x.x:8884
+```
+
+如果需要重启MQTT网关，执行如下命令：
+```
+pm2 restart xz-mqtt
+```
+
+## 第二部分：全模块运行实现小智硬件MQTT+UDP连接
+
+查看你智控台首页底部的版本号，确认你的智控台版本是否是`0.7.7`及以上版本。如果不是，需要升级智控台。
+
+1. 在智控台顶部，点击`参数管理`，搜索`server.mqtt_gateway`，点击编辑，填入你在`.env`文件中设置的`PUBLIC_IP`+`:`+`MQTT_PORT`。类似这样
+```
+192.168.0.7:1883
+```
+2. 在智控台顶部，点击`参数管理`，搜索`server.mqtt_signature_key`，点击编辑，填入你在`.env`文件中设置的`MQTT_SIGNATURE_KEY`。
+
+3. 在智控台顶部，点击`参数管理`，搜索`server.udp_gateway`，点击编辑，填入你在`.env`文件中设置的`PUBLIC_IP`+`:`+`UDP_PORT`。类似这样
+```
+192.168.0.7:8884
+```
+4. 在智控台顶部，点击`参数管理`，搜索`server.mqtt_manager_api`，点击编辑，填入你在`.env`文件中设置的`PUBLIC_IP`+`:`+`API_PORT`。类似这样
+```
+192.168.0.7:8007
+```
+
+上面的配置完成后，你可以使用curl命令，验证你的ota地址是否会下发mqtt配置，把下面的`http://localhost:8002/xiaozhi/ota/`改成你的ota地址
+```
+curl 'http://localhost:8002/xiaozhi/ota/' \
+  -H 'Content-Type: application/json' \
+  -H 'Client-Id: 7b94d69a-9808-4c59-9c9b-704333b38aff' \
+  -H 'Device-Id: 11:22:33:44:55:66' \
+  --data-raw $'{\n  "application": {\n    "version": "1.0.1",\n    "elf_sha256": "1"\n  },\n  "board": {\n    "mac": "11:22:33:44:55:66"\n  }\n}'
+```
+
+如果返回的内容包含`mqtt`相关的配置，说明配置成功。类似这样
+
+```
+{"server_time":{"timestamp":1757567894012,"timeZone":"Asia/Shanghai","timezone_offset":480},"activation":{"code":"460609","message":"http://xiaozhi.server.com\n460609","challenge":"11:22:33:44:55:66"},"firmware":{"version":"1.0.1","url":"http://xiaozhi.server.com:8002/xiaozhi/otaMag/download/NOT_ACTIVATED_FIRMWARE_THIS_IS_A_INVALID_URL"},"websocket":{"url":"ws://192.168.4.23:8000/xiaozhi/v1/"},"mqtt":{"endpoint":"192.168.0.7:1883","client_id":"GID_default@@@11_22_33_44_55_66@@@7b94d69a-9808-4c59-9c9b-704333b38aff","username":"eyJpcCI6IjA6MDowOjA6MDowOjA6MSJ9","password":"Y8XP9xcUhVIN9OmbCHT9ETBiYNE3l3Z07Wk46wV9PE8=","publish_topic":"device-server","subscribe_topic":"devices/p2p/11_22_33_44_55_66"}}
+```
+
+由于MQTT信息是需要靠OTA地址下发的，因此只有你保证能正常连接服务器的OTA地址，重启唤醒即可。
+
+唤醒后留意mqtt-gateway的日志，确认是否有连接成功的日志。
+```
+pm2 logs xz-mqtt
+```
+
+## 第三部分：单模块运行xiaozhi-server实现小智硬件MQTT+UDP连接
+
+打开你的`data/.config.yaml`文件，在`server`下找到`mqtt_gateway`填入你在`.env`文件中设置的`PUBLIC_IP`+`:`+`MQTT_PORT`。类似这样
+```
+192.168.0.7:1883
+```
+在`server`下找到`mqtt_signature_key`填入你在`.env`文件中设置的`MQTT_SIGNATURE_KEY`。
+
+在`server`下找到`udp_gateway`填入你在`.env`文件中设置的`PUBLIC_IP`+`:`+`UDP_PORT`。类似这样
+```
+192.168.0.7:8884
+```
+
+上面的配置完成后，你可以使用curl命令，验证你的ota地址是否会下发mqtt配置，把下面的`http://localhost:8002/xiaozhi/ota/`改成你的ota地址
+```
+curl 'http://localhost:8002/xiaozhi/ota/' \
+  -H 'Device-Id: 11:22:33:44:55:66' \
+  --data-raw $'{\n  "application": {\n    "version": "1.0.1",\n    "elf_sha256": "1"\n  },\n  "board": {\n    "mac": "11:22:33:44:55:66"\n  }\n}'
+```
+
+如果返回的内容包含`mqtt`相关的配置，说明配置成功。类似这样
+```
+{"server_time":{"timestamp":1758781561083,"timeZone":"GMT+08:00","timezone_offset":480},"activation":{"code":"527111","message":"http://xiaozhi.server.com\n527111","challenge":"11:22:33:44:55:66"},"firmware":{"version":"1.0.1","url":"http://xiaozhi.server.com:8002/xiaozhi/otaMag/download/NOT_ACTIVATED_FIRMWARE_THIS_IS_A_INVALID_URL"},"websocket":{"url":"ws://192.168.1.15:8000/xiaozhi/v1/"},"mqtt":{"endpoint":"192.168.1.15:1883","client_id":"GID_default@@@11_22_33_44_55_66@@@11_22_33_44_55_66","username":"eyJpcCI6IjE5Mi4xNjguMS4xNSJ9","password":"fjAYs49zTJecWqJ3jBt+kqxVn/x7vkXRAc85ak/va7Y=","publish_topic":"device-server","subscribe_topic":"devices/p2p/11_22_33_44_55_66"}}
+```
+
+由于MQTT信息是需要靠OTA地址下发的，因此只有你保证能正常连接服务器的OTA地址，重启唤醒即可。
+
+唤醒后留意mqtt-gateway的日志，确认是否有连接成功的日志。
+```
+pm2 logs xz-mqtt
+```

docs/newsnow_plugin_config.md

@@ -0,0 +1,105 @@
+# get_news_from_newsnow 插件新闻源配置指南
+
+## 概述
+
+`get_news_from_newsnow` 插件现在支持通过Web管理界面动态配置新闻源，不再需要修改代码。用户可以在智控台中为每个智能体配置不同的新闻源。
+
+## 配置方式
+
+### 1. 通过Web管理界面配置（推荐）
+
+1. 登录智控台
+2. 进入"角色配置"页面
+3. 选择要配置的智能体
+4. 点击"编辑功能"按钮
+5. 在右侧参数配置区域找到"newsnow新闻聚合"插件
+6. 在"新闻源配置"字段中输入分号分隔的中文名称
+
+### 2. 配置文件方式
+
+在 `config.yaml` 中配置：
+
+```yaml
+plugins:
+  get_news_from_newsnow:
+    url: "https://newsnow.busiyi.world/api/s?id="
+    news_sources: "澎湃新闻;百度热搜;财联社;微博;抖音"
+```
+
+## 新闻源配置格式
+
+新闻源配置使用分号分隔的中文名称，格式为：
+
+```
+中文名称1;中文名称2;中文名称3
+```
+
+### 配置示例
+
+```
+澎湃新闻;百度热搜;财联社;微博;抖音;知乎;36氪
+```
+
+## 支持的新闻源
+
+插件支持以下新闻源的中文名称：
+
+- 澎湃新闻
+- 百度热搜
+- 财联社
+- 微博
+- 抖音
+- 知乎
+- 36氪
+- 华尔街见闻
+- IT之家
+- 今日头条
+- 虎扑
+- 哔哩哔哩
+- 快手
+- 雪球
+- 格隆汇
+- 法布财经
+- 金十数据
+- 牛客
+- 少数派
+- 稀土掘金
+- 凤凰网
+- 虫部落
+- 联合早报
+- 酷安
+- 远景论坛
+- 参考消息
+- 卫星通讯社
+- 百度贴吧
+- 靠谱新闻
+- 以及更多...
+
+## 默认配置
+
+如果未配置新闻源，插件将使用以下默认配置：
+
+```
+澎湃新闻;百度热搜;财联社
+```
+
+## 使用说明
+
+1. **配置新闻源**：在Web界面或配置文件中设置新闻源的中文名称，用分号分隔
+2. **调用插件**：用户可以说"播报新闻"或"获取新闻"
+3. **指定新闻源**：用户可以说"播报澎湃新闻"或"获取百度热搜"
+4. **获取详情**：用户可以说"详细介绍这条新闻"
+
+## 工作原理
+
+1. 插件接受中文名称作为参数（如"澎湃新闻"）
+2. 根据配置的新闻源列表，将中文名称转换为对应的英文ID（如"thepaper"）
+3. 使用英文ID调用API获取新闻数据
+4. 返回新闻内容给用户
+
+## 注意事项
+
+1. 配置的中文名称必须与 CHANNEL_MAP 中定义的名称完全一致
+2. 配置更改后需要重启服务或重新加载配置
+3. 如果配置的新闻源无效，插件会自动使用默认新闻源
+4. 多个新闻源之间使用英文分号(;)分隔，不要使用中文分号(；)

docs/ota-upgrade-guide.md

@@ -0,0 +1,142 @@
+# 单模块部署固件OTA自动升级配置指南
+
+本教程将指导你如何在**单模块部署**场景下配置固件OTA自动升级功能，实现设备固件的自动更新。
+
+如果你已经使用**全模块部署**，请忽略本教程。
+
+## 功能介绍
+
+在单模块部署中，xiaozhi-server内置了OTA固件管理功能，可以自动检测设备版本并下发升级固件。系统会根据设备型号和当前版本，自动匹配并推送最新的固件版本。
+
+## 前提条件
+
+- 你已经成功进行**单模块部署**并运行xiaozhi-server
+- 设备能够正常连接到服务器
+
+## 第一步 准备固件文件
+
+### 1. 创建固件存放目录
+
+固件文件需要放在`data/bin/`目录下。如果该目录不存在，请手动创建：
+
+```bash
+mkdir -p data/bin
+```
+
+### 2. 固件文件命名规则
+
+固件文件必须遵循以下命名格式：
+
+```
+{设备型号}_{版本号}.bin
+```
+
+**命名规则说明：**
+- `设备型号`：设备的型号名称，例如 `lichuang-dev`、`bread-compact-wifi` 等
+- `版本号`：固件版本号，必须以数字开头，支持数字、字母、点号、下划线和短横线，例如 `1.6.6`、`2.0.0` 等
+- 文件扩展名必须是 `.bin`
+
+**命名示例：**
+```
+bread-compact-wifi_1.6.6.bin
+lichuang-dev_2.0.0.bin
+```
+
+### 3. 放置固件文件
+
+将准备好的固件文件（.bin文件）复制到`data/bin/`目录下：
+
+重要的事情说三遍：升级的bin文件是`xiaozhi.bin`，不是全量固件文件`merged-binary.bin`!
+
+重要的事情说三遍：升级的bin文件是`xiaozhi.bin`，不是全量固件文件`merged-binary.bin`!
+
+重要的事情说三遍：升级的bin文件是`xiaozhi.bin`，不是全量固件文件`merged-binary.bin`!
+
+```bash
+cp xiaozhi.bin data/bin/设备型号_版本号.bin
+```
+
+例如：
+```bash
+cp xiaozhi.bin data/bin/bread-compact-wifi_1.6.6.bin
+```
+
+## 第二步 配置公网访问地址（仅公网部署需要）
+
+**注意：此步骤仅适用于单模块公网部署的场景。**
+
+如果你的xiaozhi-server是公网部署（使用公网IP或域名），**必须**配置`server.vision_explain`参数，因为OTA固件下载地址会使用该配置的域名和端口。
+
+如果你是局域网部署，可以跳过此步骤。
+
+### 为什么要配置这个参数？
+
+在单模块部署中，系统生成固件下载地址时，会使用`vision_explain`配置的域名和端口作为基础地址。如果不配置或配置错误，设备将无法访问固件下载地址。
+
+### 配置方法
+
+打开`data/.config.yaml`文件，找到`server`配置段，设置`vision_explain`参数：
+
+```yaml
+server:
+  vision_explain: http://你的域名或IP:端口号/mcp/vision/explain
+```
+
+**配置示例：**
+
+局域网部署（默认）：
+```yaml
+server:
+  vision_explain: http://192.168.1.100:8003/mcp/vision/explain
+```
+
+公网域名部署：
+```yaml
+server:
+  vision_explain: http://yourdomain.com:8003/mcp/vision/explain
+```
+
+### 注意事项
+
+- 域名或IP必须是设备能够访问的地址
+- 如果使用Docker部署，不能使用Docker内部地址（如127.0.0.1或localhost）
+- 如果你使用了nginx反向代理，请填写对外的地址和端口号，不是本项目运行的端口号
+
+
+## 常见问题
+
+### 1. 设备收不到固件更新
+
+**可能原因和解决方法：**
+
+- 检查固件文件命名是否符合规则：`{型号}_{版本号}.bin`
+- 检查固件文件是否正确放置在`data/bin/`目录
+- 检查设备型号是否与固件文件名中的型号匹配
+- 检查固件版本号是否高于设备当前版本
+- 查看服务器日志，确认OTA请求是否正常处理
+
+### 2. 设备报告下载地址无法访问
+
+**可能原因和解决方法：**
+
+- 检查`server.vision_explain`配置的域名或IP是否正确
+- 确认端口号配置正确（默认8003）
+- 如果是公网部署，确保设备能够访问该公网地址
+- 如果是Docker部署，确保不是使用了内部地址（127.0.0.1）
+- 检查防火墙是否开放了对应端口
+- 如果你使用了nginx反向代理，请填写对外的地址和端口号，不是本项目运行的端口号
+
+### 3. 如何确认设备当前版本
+
+查看OTA请求日志，日志中会显示设备上报的版本号：
+
+```
+[ota_handler] - 设备 AA:BB:CC:DD:EE:FF 固件已是最新: 1.6.6
+```
+
+### 4. 固件文件放置后没有生效
+
+系统有30秒的缓存时间（默认），可以：
+- 等待30秒后再让设备发起OTA请求
+- 重启xiaozhi-server服务
+- 调整`firmware_cache_ttl`配置为更短的时间

docs/paddlespeech-deploy.md

@@ -0,0 +1,109 @@
+# PaddleSpeechTTS集成xiaozhi服务
+
+## 重点说明
+- 优点：本地离线部署、速度快
+- 缺点：截止2025年9月25日，默认的模型是中文模型，不支持英文转语音。如果含英文会发不出声音，如需同时支持中英文需要自己训练。
+
+## 一、基础环境要求
+操作系统：Windows / Linux / WSL 2
+
+Python 版本：3.9以上（请根据Paddle官方教程调整）
+
+Paddle 版本：官方最新版本   ```https://www.paddlepaddle.org.cn/install```
+
+依赖管理工具：conda 或 venv
+
+## 二、启动paddlespeech服务
+### 1.从paddlespeech官方仓库拉取源码
+```bash 
+git clone https://github.com/PaddlePaddle/PaddleSpeech.git
+```
+### 2.建立虚拟环境
+```bash
+
+conda create -n paddle_env python=3.10 -y
+conda activate paddle_env
+```
+### 3.安装paddle
+因CPU架构、GPU架构不同，请根据Paddle官方支持的python版本建立环境  
+```
+https://www.paddlepaddle.org.cn/install
+```
+
+### 4.进入paddlespeech目录
+```bash
+cd PaddleSpeech
+```
+### 5.安装paddlespeech
+```bash
+pip install pytest-runner -i https://pypi.tuna.tsinghua.edu.cn/simple
+
+#以下命令使用任意一个
+pip install paddlepaddle -i https://mirror.baidu.com/pypi/simple
+pip install paddlespeech -i https://pypi.tuna.tsinghua.edu.cn/simple
+```
+### 6.使用命令自动下载语音模型
+```bash
+paddlespeech tts --input "你好，这是一次测试"
+```
+此步骤会自动下载模型缓存至本地 .paddlespeech/models 目录
+
+### 7.修改tts_online_application.yaml配置
+参考目录 ```"PaddleSpeech\demos\streaming_tts_server\conf\tts_online_application.yaml"```
+选择```tts_online_application.yaml```文件用编辑器打开，设置```protocol```为```websocket```
+
+### 8.启动服务
+```yaml
+paddlespeech_server start --config_file ./demos/streaming_tts_server/conf/tts_online_application.yaml
+#官方默认启动命令：
+paddlespeech_server start --config_file ./conf/tts_online_application.yaml
+```
+请根据你的```tts_online_application.yaml```的实际目录来启动命令，看到如下日志即启动成功
+```
+Prefix dict has been built successfully.
+[2025-08-07 10:03:11,312] [   DEBUG] __init__.py:166 - Prefix dict has been built successfully.
+INFO:     Started server process [2298]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://0.0.0.0:8092 (Press CTRL+C to quit)
+```
+
+## 三、修改小智的配置文件
+### 1.```main/xiaozhi-server/core/providers/tts/paddle_speech.py```
+
+### 2.```main/xiaozhi-server/data/.config.yaml```
+使用单模块部署
+```yaml
+selected_module:
+  TTS: PaddleSpeechTTS
+TTS:
+  PaddleSpeechTTS:
+      type: paddle_speech
+      protocol: websocket 
+      url:  ws://127.0.0.1:8092/paddlespeech/tts/streaming  # TTS 服务的 URL 地址，指向本地服务器 [websocket默认ws://127.0.0.1:8092/paddlespeech/tts/streaming]
+      spk_id: 0  # 发音人 ID，0 通常表示默认的发音人
+      sample_rate: 24000  # 采样率 [websocket默认24000，http默认0 自动选择]
+      speed: 1.0  # 语速，1.0 表示正常语速，>1 表示加快，<1 表示减慢
+      volume: 1.0  # 音量，1.0 表示正常音量，>1 表示增大，<1 表示减小
+      save_path:   # 保存路径
+```
+### 3.启动xiaozhi服务
+```py
+python app.py
+```
+启动`main/digital-human`下的`python start.py`后，打开`http://127.0.0.1:8006/index.html`，测试连接和发送消息时paddlespeech端是否有输出日志
+
+输出日志参考：
+```
+INFO:     127.0.0.1:44312 - "WebSocket /paddlespeech/tts/streaming" [accepted]
+INFO:     connection open
+[2025-08-07 11:16:33,355] [    INFO] - sentence: 哈哈，怎么突然找我聊天啦？
+[2025-08-07 11:16:33,356] [    INFO] - The durations of audio is: 2.4625 s
+[2025-08-07 11:16:33,356] [    INFO] - first response time: 0.1143045425415039 s
+[2025-08-07 11:16:33,356] [    INFO] - final response time: 0.4777836799621582 s
+[2025-08-07 11:16:33,356] [    INFO] - RTF: 0.19402382942625715
+[2025-08-07 11:16:33,356] [    INFO] - Other info: front time: 0.06514096260070801 s, first am infer time: 0.008037090301513672 s, first voc infer time: 0.04112648963928223 s,
+[2025-08-07 11:16:33,356] [    INFO] - Complete the synthesis of the audio streams
+INFO:     connection closed
+
+```

docs/performance_tester.md

@@ -0,0 +1,27 @@
+# 语音识别、大语言模型、非流式语音合成、流式语音合成、视觉模型的性能测试工具使用指南
+
+1.在main/xiaozhi-server目录下创建data目录
+2.在data目录下创建.config.yaml文件
+3.在.data/config.yaml中，写入你的语音识别、大语言模型、流式语音合成、视觉模型的参数
+例如：
+```
+LLM:
+  ChatGLMLLM:
+    # 定义LLM API类型
+    type: openai
+    # glm-4-flash 是免费的，但是还是需要注册填写api_key的
+    # 可在这里找到你的api key https://bigmodel.cn/usercenter/proj-mgmt/apikeys
+    model_name: glm-4-flash
+    url: https://open.bigmodel.cn/api/paas/v4/
+    api_key: 你的chat-glm web key
+
+TTS:
+
+VLLM:
+
+ASR:
+```
+4.在main/xiaozhi-server目录下运行performance_tester.py: 
+```
+python performance_tester.py
+```