Merge pull request #3013 from xinnan-tech/version-num

Bump to 0.9.2

.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

@@ -5,6 +5,10 @@ on:
     tags:
       - 'v*.*.*'  # 只在以 v 开头的标签推送时触发，例如 v1.0.0
   workflow_dispatch:
+  workflow_run:
+    workflows: ["Build Base Image"]
+    types:
+      - completed
 
 jobs:
   release:
@@ -62,7 +66,7 @@ jobs:
           push: true
           tags: |
             ${{ 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
+          platforms: linux/amd64,linux/arm64
           cache-from: type=gha
           cache-to: type=gha,mode=max
           build-args: |
@@ -77,7 +81,7 @@ jobs:
           push: true
           tags: |
             ${{ 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
+          platforms: linux/amd64,linux/arm64
           cache-from: type=gha
           cache-to: type=gha,mode=max
           build-args: |

.gitignore

@@ -3,6 +3,9 @@ __pycache__/
 .idea/
 *.py[cod]
 *$py.class
+.vscode
+.claude
+AGENTS.md
 
 # C extensions
 *.so
@@ -182,4 +185,5 @@ uploadfile
 # Do not ignore env and json files inside manager-mobile
 !main/manager-mobile/**/env/
 !main/manager-mobile/**/.env*
-!main/manager-mobile/**/*.json
+!main/manager-mobile/**/*.json
+!main/xiaozhi-server/**/*.json

Dockerfile-server

@@ -1,36 +1,6 @@
-# 第一阶段：构建Python依赖
+# 生产镜像，仅包含应用代码
-FROM python:3.10-slim AS builder
+FROM ghcr.io/xinnan-tech/xiaozhi-esp32-server:server-base
 
-WORKDIR /app
-
-# 配置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
-
-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
-
-# 第二阶段：生产镜像
-FROM python:3.10-slim
-
-WORKDIR /opt/xiaozhi-esp32-server
-
-# 安装系统依赖
-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 --from=builder /usr/local/bin/mcp-proxy /usr/local/bin/mcp-proxy
-
-# 复制应用代码
 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,7 +7,7 @@ COPY main/manager-web .
 RUN npm run build
 
 # 第二阶段：构建Java后端
-FROM maven:3.9.4-eclipse-temurin-21 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
@@ -18,18 +18,19 @@ FROM bellsoft/liberica-runtime-container:jre-21-glibc
 
 # 安装Nginx和字体库
 RUN apk update && \
-    apk add --no-cache --repository=http://dl-cdn.alpinelinux.org/alpine/edge/testing/ \
+    apk add --no-cache --no-scripts \
         nginx \
         bash \
         fontconfig \
         ttf-dejavu \
-        msttcorefonts-installer \
+    && rm -rf /var/cache/apk/* \
-    && ACCEPT_EULA=Y apk add --no-cache msttcorefonts-installer \
+    && mkdir -p /run/nginx /var/log/nginx /var/tmp/nginx /etc/nginx/conf.d
-    && fc-cache -f -v \
+
-    && rm -rf /var/cache/apk/*
+# 复制项目自带的中文字体
+COPY main/manager-web/public/generator/static/fonts/*.ttf /usr/share/fonts/
 
 # 更新字体缓存
-RUN (printf 'YES\n' | update-ms-fonts || true) && fc-cache -f -v
+RUN fc-cache -f -v
 
 # 配置Nginx
 COPY docs/docker/nginx.conf /etc/nginx/nginx.conf

README.md

@@ -6,29 +6,25 @@
 本项目基于人机共生智能理论和技术研发智能终端软硬件体系<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接入点、声纹识别
+支持MQTT+UDP协议、Websocket协议、MCP接入点、声纹识别、知识库
 </p>
 
 <p align="center">
-<a href="./README_en.md">English</a>
+<a href="./docs/FAQ.md">常见问题</a>
-· <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="./README_en.md"><img alt="README in English" src="https://img.shields.io/badge/English-DFE0E5"></a>
+  <a href="./README_vi.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/Tiếng Việt-DFE0E5"></a>
+  <a href="./README_de.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-DFE0E5"></a>
+  <a href="./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/graphs/contributors">
-    <img alt="GitHub Contributors" src="https://img.shields.io/github/contributors/xinnan-tech/xiaozhi-esp32-server?logo=github" />
-  </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>
   <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>
@@ -188,8 +184,8 @@ Spearheaded by Professor Siyuan Liu's Team (South China University of Technology
 #### 🚀 部署方式选择
 | 部署方式 | 特点 | 适用场景 | 部署文档 | 配置要求 | 视频教程 | 
 |---------|------|---------|---------|---------|---------|
-| **最简化安装** | 智能对话、IOT、MCP、视觉感知 | 低配置环境，数据存储在配置文件，无需数据库 | [①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.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 | - | 
-| **全模块安装** | 智能对话、IOT、MCP接入点、声纹识别、视觉感知、OTA、智控台 | 完整功能体验，数据存储在数据库 |[①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) | 
+| **全模块安装** | 智能对话、多用户管理、多智能体管理、智控台界面操作 | 完整功能体验，数据存储在数据库 |[①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)
 
@@ -216,10 +212,10 @@ Websocket接口地址: wss://2662r3426b.vicp.fun/xiaozhi/v1/
 
 | 模块名称 | 入门全免费设置 | 流式配置 |
 |:---:|:---:|:---:|
-| ASR(语音识别) | FunASR(本地) | 👍FunASR(本地GPU模式) |
+| ASR(语音识别) | FunASR(本地) | 👍XunfeiStreamASR(讯飞流式) |
-| LLM(大模型) | ChatGLMLLM(智谱glm-4-flash) | 👍AliLLM(qwen3-235b-a22b-instruct-2507) 或 👍DoubaoLLM(doubao-1-5-pro-32k-250115) |
+| LLM(大模型) | glm-4-flash(智谱) | 👍qwen-flash(阿里百炼) |
-| VLLM(视觉大模型) | ChatGLMVLLM(智谱glm-4v-flash) | 👍QwenVLVLLM(千问qwen2.5-vl-3b-instructh) |
+| VLLM(视觉大模型) | glm-4v-flash(智谱) | 👍qwen2.5-vl-3b-instructh(阿里百炼) |
-| TTS(语音合成) | ✅LinkeraiTTS(灵犀流式) | 👍HuoshanDoubleStreamTTS(火山双流式语音合成) 或 👍AliyunStreamTTS(阿里云流式语音合成) |
+| TTS(语音合成) | ✅LinkeraiTTS(灵犀流式) | 👍HuoshanDoubleStreamTTS(火山流式) |
 | Intent(意图识别) | function_call(函数调用) | function_call(函数调用) |
 | Memory(记忆功能) | mem_local_short(本地短期记忆） | mem_local_short（本地短期记忆） |
 
@@ -246,8 +242,9 @@ Websocket接口地址: wss://2662r3426b.vicp.fun/xiaozhi/v1/
 | 声纹识别 | 支持多用户声纹注册、管理和识别，与ASR并行处理，实时识别说话人身份并传递给LLM进行个性化回应 |
 | 智能对话 | 支持多种LLM(大语言模型)，实现智能对话 |
 | 视觉感知 | 支持多种VLLM(视觉大模型)，实现多模态交互 |
-| 意图识别 | 支持LLM意图识别、Function Call函数调用，提供插件化意图处理机制 |
+| 意图识别 | 支持外挂的大模型意图识别、大模型自主函数调用，提供插件化意图处理机制 |
-| 记忆系统 | 支持本地短期记忆、mem0ai接口记忆，具备记忆总结功能 |
+| 记忆系统 | 支持本地短期记忆、mem0ai接口记忆、PowerMem智能记忆，具备记忆总结功能 |
+| 知识库 | 支持RAGFlow知识库，让大模型判断需要调度知识库后再回答 |
 | 工具调用 | 支持客户端IOT协议、客户MCP协议、服务端MCP协议、MCP接入点协议、自定义工具函数 |
 | 指令下发 | 依托MQTT协议，支持从智控台将MCP指令下发到ESP32设备 |
 | 管理后台 | 提供Web管理界面，支持用户管理、系统配置和设备管理；界面支持中文简体、中文繁体、英文显示 |
@@ -264,7 +261,7 @@ Websocket接口地址: wss://2662r3426b.vicp.fun/xiaozhi/v1/
 ---
 
 ## 产品生态 👬
-小智是一个生态，当你使用这个产品时，也可以看看其他在这个生态圈的[优秀项目](https://github.com/78/xiaozhi-esp32?tab=readme-ov-file#%E7%9B%B8%E5%85%B3%E5%BC%80%E6%BA%90%E9%A1%B9%E7%9B%AE)
+小智是一个生态，当你使用这个产品时，也可以看看其他在这个生态圈的[优秀项目](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)
 
 ---
 
@@ -273,7 +270,7 @@ Websocket接口地址: wss://2662r3426b.vicp.fun/xiaozhi/v1/
 
 | 使用方式 | 支持平台 | 免费平台 |
 |:---:|:---:|:---:|
-| openai 接口调用 | 阿里百炼、火山引擎豆包、深度求索、智谱ChatGLM、Gemini | 智谱ChatGLM、Gemini |
+| openai 接口调用 | 阿里百炼、火山引擎、DeepSeek、智谱、Gemini、科大讯飞 | 智谱、Gemini |
 | ollama 接口调用 | Ollama | - |
 | dify 接口调用 | Dify | - |
 | fastgpt 接口调用 | Fastgpt | - |
@@ -299,7 +296,7 @@ Websocket接口地址: wss://2662r3426b.vicp.fun/xiaozhi/v1/
 
 | 使用方式 | 支持平台 | 免费平台 |
 |:---:|:---:|:---:|
-| 接口调用 | EdgeTTS、火山引擎豆包TTS、腾讯云、阿里云TTS、阿里云流式TTS、CosyVoiceSiliconflow、TTS302AI、CozeCnTTS、GizwitsTTS、ACGNTTS、OpenAITTS、灵犀流式TTS、MinimaxTTS、火山双流式TTS | 灵犀流式TTS、EdgeTTS、CosyVoiceSiliconflow(部分) |
+| 接口调用 | 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 |
 
 ---
@@ -317,7 +314,7 @@ Websocket接口地址: wss://2662r3426b.vicp.fun/xiaozhi/v1/
 | 使用方式 | 支持平台 | 免费平台 |
 |:---:|:---:|:---:|
 | 本地使用 | FunASR、SherpaASR | FunASR、SherpaASR |
-| 接口调用 | DoubaoASR、Doubao流式ASR、FunASRServer、TencentASR、AliyunASR、Aliyun流式ASR、百度ASR、OpenAI ASR | FunASRServer |
+| 接口调用 | FunASRServer、火山引擎、科大讯飞、腾讯云、阿里云、百度云、OpenAI ASR | FunASRServer |
 
 ---
 
@@ -334,6 +331,7 @@ Websocket接口地址: wss://2662r3426b.vicp.fun/xiaozhi/v1/
 |   类型   |      平台名称       | 使用方式 |   收费模式    | 备注 |
 |:------:|:---------------:|:----:|:---------:|:--:|
 | Memory |     mem0ai      | 接口调用 | 1000次/月额度 |    |
+| Memory |     [powermem](./docs/powermem-integration.md)    | 本地总结 | 取决于LLM和DB |  OceanBase开源，支持智能检索  |
 | Memory | mem_local_short | 本地总结 |    免费     |    |
 | Memory |     nomem       | 无记忆模式 |    免费     |    |
 
@@ -349,6 +347,14 @@ Websocket接口地址: wss://2662r3426b.vicp.fun/xiaozhi/v1/
 
 ---
 
+### Rag 检索增强生成
+
+|   类型   |     平台名称      | 使用方式 |  收费模式   |          备注           |
+|:------:|:-------------:|:----:|:-------:|:---------------------:|
+| Rag |  ragflow   | 接口调用 | 根据切片、分词消耗的token收费 |    借助RagFlow的检索增强生成功能，提供更准确的对话回复     |
+
+---
+
 ## 鸣谢 🙏
 
 | Logo | 项目/公司 | 说明 |

README_de.md

@@ -0,0 +1,376 @@
+[![Banners](docs/images/banner1.png)](https://github.com/xinnan-tech/xiaozhi-esp32-server)
+
+<h1 align="center">Xiaozhi Backend-Service xiaozhi-esp32-server</h1>
+
+<p align="center">
+Dieses Projekt basiert auf der Theorie und Technologie der Mensch-Maschine-symbiotischen Intelligenz zur Entwicklung intelligenter Terminal-Hardware- und Software-Systeme<br/>und bietet Backend-Dienste für das Open-Source-Hardware-Projekt
+<a href="https://github.com/78/xiaozhi-esp32">xiaozhi-esp32</a><br/>
+Implementiert mit Python, Java und Vue gemäß dem <a href="https://ccnphfhqs21z.feishu.cn/wiki/M0XiwldO9iJwHikpXD5cEx71nKh">Xiaozhi-Kommunikationsprotokoll</a><br/>
+Unterstützt MQTT+UDP-Protokoll, Websocket-Protokoll, MCP-Endpunkte und Stimmabdruckerkennung
+</p>
+
+<p align="center">
+<a href="./docs/FAQ.md">Häufige Fragen</a>
+· <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/issues">Probleme melden</a>
+· <a href="./README.md#%E9%83%A8%E7%BD%B2%E6%96%87%E6%A1%A3">Deployment-Dokumentation</a>
+· <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/releases">Release-Hinweise</a>
+</p>
+
+<p align="center">
+  <a href="./README.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-DFE0E5"></a>
+  <a href="./README_en.md"><img alt="README in English" src="https://img.shields.io/badge/English-DFE0E5"></a>
+  <a href="./README_vi.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/Tiếng Việt-DFE0E5"></a>
+  <a href="./README_de.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-DBEDFA"></a>
+  <a href="./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/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">
+    <img alt="stars" src="https://img.shields.io/github/stars/xinnan-tech/xiaozhi-esp32-server?color=ffcb47&labelColor=black" />
+  </a>
+</p>
+
+<p align="center">
+Geleitet vom Team von Professor Siyuan Liu (South China University of Technology)
+</br>
+刘思源教授团队主导研发(华南理工大学)
+</br>
+<img src="./docs/images/hnlg.jpg" alt="South China University of Technology" width="50%">
+</p>
+
+---
+
+## Zielgruppe 👥
+
+Dieses Projekt erfordert ESP32-Hardware-Geräte zum Betrieb. Wenn Sie ESP32-bezogene Hardware erworben haben, erfolgreich eine Verbindung zu Brother Xias bereitgestelltem Backend-Service hergestellt haben und Ihren eigenen `xiaozhi-esp32`-Backend-Service unabhängig aufbauen möchten, dann ist dieses Projekt perfekt für Sie.
+
+Möchten Sie die Nutzungseffekte sehen? Klicken Sie auf die Videos unten 🎥
+
+<table>
+  <tr>
+    <td>
+        <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
+         <picture>
+           <img alt="响应速度感受" src="docs/images/demo9.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+        <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/BV1C1tCzUEZh" target="_blank">
+         <picture>
+           <img alt="复杂医疗场景" src="docs/images/demo1.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>
+  </tr>
+  <tr>
+    <td>
+        <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/BV1ZQKUzYExM" target="_blank">
+         <picture>
+           <img alt="MCP接入点" src="docs/images/demo13.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1TJ7WzzEo6" target="_blank">
+         <picture>
+           <img alt="多指令任务" src="docs/images/demo11.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+        <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
+         <picture>
+           <img alt="播放音乐" src="docs/images/demo7.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+        <a href="https://www.bilibili.com/video/BV1Z8XuYZEAS" target="_blank">
+         <picture>
+           <img alt="天气插件" src="docs/images/demo8.png" />
+         </picture>
+        </a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <a href="https://www.bilibili.com/video/BV12J7WzBEaH" target="_blank">
+         <picture>
+           <img alt="实时打断" src="docs/images/demo10.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+      <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/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>
+    <td>
+        <a href="https://www.bilibili.com/video/BV17LXWYvENb" target="_blank">
+         <picture>
+           <img alt="播报新闻" src="docs/images/demo0.png" />
+         </picture>
+        </a>
+    </td>
+  </tr>
+</table>
+
+---
+
+## Warnungen ⚠️
+
+1. Dieses Projekt ist Open-Source-Software. Diese Software hat keine kommerzielle Partnerschaft mit Drittanbieter-API-Dienstleistern (einschließlich, aber nicht beschränkt auf Spracherkennung, große Modelle, Sprachsynthese und andere Plattformen), mit denen sie sich verbindet, und bietet keine Garantie für deren Servicequalität oder finanzielle Sicherheit. Es wird empfohlen, dass Benutzer Dienstleister mit entsprechenden Geschäftslizenzen bevorzugen und deren Servicevereinbarungen und Datenschutzrichtlinien sorgfältig lesen. Diese Software hostet keine Kontoschlüssel, nimmt nicht an Geldströmen teil und trägt nicht das Risiko von Verlusten bei Guthaben-Aufladungen.
+
+2. Die Funktionalität dieses Projekts ist nicht vollständig und hat keine Netzwerksicherheitsbewertung bestanden. Bitte verwenden Sie es nicht in Produktionsumgebungen. Wenn Sie dieses Projekt zu Lernzwecken in einer öffentlichen Netzwerkumgebung bereitstellen, stellen Sie bitte sicher, dass notwendige Schutzmaßnahmen vorhanden sind.
+
+---
+
+## Deployment-Dokumentation
+
+![Banners](docs/images/banner2.png)
+
+Dieses Projekt bietet zwei Bereitstellungsmethoden. Bitte wählen Sie basierend auf Ihren spezifischen Anforderungen:
+
+#### 🚀 Auswahl der Bereitstellungsmethode
+| Bereitstellungsmethode | Funktionen | Anwendungsszenarien | Deployment-Dokumente | Konfigurationsanforderungen | Video-Tutorials |
+|---------|------|---------|---------|---------|---------|
+| **Vereinfachte Installation** | Intelligenter Dialog, Einzel-Agenten-Verwaltung | Umgebungen mit geringer Konfiguration, Daten in Konfigurationsdateien gespeichert, keine Datenbank erforderlich | [①Docker-Version](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) / [②Quellcode-Deployment](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E5%8F%AA%E8%BF%90%E8%A1%8Cserver)| 2 Kerne 4GB bei Verwendung von `FunASR`, 2 Kerne 2GB bei allen APIs | - |
+| **Vollständige Modulinstallation** | Intelligenter Dialog, Mehrbenutzerverwaltung, Mehr-Agenten-Verwaltung, Intelligente Steuerkonsole-Bedienung | Vollständige Funktionserfahrung, Daten in Datenbank gespeichert |[①Docker-Version](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [②Quellcode-Deployment](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [③Quellcode-Deployment Auto-Update-Tutorial](./docs/dev-ops-integration.md) | 4 Kerne 8GB bei Verwendung von `FunASR`, 2 Kerne 4GB bei allen APIs| [Video-Tutorial für lokalen Quellcode-Start](https://www.bilibili.com/video/BV1wBJhz4Ewe) |
+
+Häufige Fragen und entsprechende Tutorials finden Sie unter [diesem Link](./docs/FAQ.md)
+
+> 💡 Hinweis: Unten ist eine Testplattform, die mit dem neuesten Code bereitgestellt wurde. Sie können bei Bedarf brennen und testen. Gleichzeitige Benutzer: 6, Daten werden täglich gelöscht.
+
+```
+Adresse der intelligenten Steuerkonsole: https://2662r3426b.vicp.fun
+Adresse der intelligenten Steuerkonsole (H5): https://2662r3426b.vicp.fun/h5/index.html
+
+Service-Testtool: https://2662r3426b.vicp.fun/test/
+OTA-Schnittstellenadresse: https://2662r3426b.vicp.fun/xiaozhi/ota/
+Websocket-Schnittstellenadresse: wss://2662r3426b.vicp.fun/xiaozhi/v1/
+```
+
+#### 🚩 Konfigurationsbeschreibung und Empfehlungen
+> [!Note]
+> Dieses Projekt bietet zwei Konfigurationsschemata:
+>
+> 1. `Einstiegslevel Kostenlose Einstellungen`: Geeignet für den persönlichen und privaten Gebrauch, alle Komponenten verwenden kostenlose Lösungen, keine zusätzliche Zahlung erforderlich.
+>
+> 2. `Streaming-Konfiguration`: Geeignet für Demonstrationen, Schulungen, Szenarien mit mehr als 2 gleichzeitigen Benutzern usw. Verwendet Streaming-Verarbeitungstechnologie für schnellere Reaktionsgeschwindigkeit und bessere Erfahrung.
+>
+> Ab Version `0.5.2` unterstützt das Projekt Streaming-Konfiguration. Im Vergleich zu früheren Versionen ist die Reaktionsgeschwindigkeit um ca. `2,5 Sekunden` verbessert, was die Benutzererfahrung erheblich verbessert.
+
+| Modulname | Einstiegslevel Kostenlose Einstellungen | Streaming-Konfiguration |
+|:---:|:---:|:---:|
+| ASR (Spracherkennung) | FunASR (Lokal) | 👍XunfeiStreamASR (Xunfei-Streaming) |
+| LLM (Großes Modell) | glm-4-flash (Zhipu) | 👍qwen-flash (Alibaba Bailian) |
+| VLLM (Vision Large Model) | glm-4v-flash (Zhipu) | 👍qwen2.5-vl-3b-instructh (Alibaba Bailian) |
+| TTS (Sprachsynthese) | ✅LinkeraiTTS (Lingxi-Streaming) | 👍HuoshanDoubleStreamTTS (Volcano-Streaming) |
+| Intent (Absichtserkennung) | function_call (Funktionsaufruf) | function_call (Funktionsaufruf) |
+| Memory (Gedächtnisfunktion) | mem_local_short (Lokales Kurzzeitgedächtnis) | mem_local_short (Lokales Kurzzeitgedächtnis) |
+
+Wenn Sie sich um die Latenz jeder Komponente kümmern, lesen Sie bitte den [Xiaozhi-Komponenten-Leistungstestbericht](https://github.com/xinnan-tech/xiaozhi-performance-research). Sie können gemäß den Testmethoden im Bericht in Ihrer Umgebung tatsächlich testen.
+
+#### 🔧 Testwerkzeuge
+Dieses Projekt bietet die folgenden Testwerkzeuge, um Ihnen bei der Überprüfung des Systems und der Auswahl geeigneter Modelle zu helfen:
+
+| Werkzeugname | Standort | Verwendungsmethode | Funktionsbeschreibung |
+|:---:|:---|:---:|:---:|
+| Audio-Interaktionstesttool | main》xiaozhi-server》test》test_page.html | Direkt mit Google Chrome öffnen | Testet Audio-Wiedergabe- und Empfangsfunktionen, überprüft, ob die Python-seitige Audioverarbeitung normal ist |
+| Modell-Reaktionstesttool | main》xiaozhi-server》performance_tester.py | Ausführen `python performance_tester.py` | Testet die Reaktionsgeschwindigkeit von ASR (Spracherkennung), LLM (großes Modell), VLLM (Vision-Modell), TTS (Sprachsynthese) drei Kernmodulen |
+
+> 💡 Hinweis: Beim Testen der Modellgeschwindigkeit werden nur Modelle mit konfigurierten Schlüsseln getestet.
+
+---
+## Funktionsliste ✨
+### Implementiert ✅
+![请参考-全模块安装架构图](docs/images/deploy2.png)
+| Funktionsmodul | Beschreibung |
+|:---:|:---|
+| Kernarchitektur | Basierend auf [MQTT+UDP-Gateway](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/main/docs/mqtt-gateway-integration.md), WebSocket und HTTP-Servern, bietet vollständiges Konsolenverwaltungs- und Authentifizierungssystem |
+| Sprachinteraktion | Unterstützt Streaming-ASR (Spracherkennung), Streaming-TTS (Sprachsynthese), VAD (Sprachaktivitätserkennung), unterstützt mehrsprachige Erkennung und Sprachverarbeitung |
+| Stimmabdruckerkennung | Unterstützt Mehrbenutzer-Stimmabdruckregistrierung, -verwaltung und -erkennung, verarbeitet parallel mit ASR, Echtzeit-Sprecheridentitätserkennung und Weitergabe an LLM für personalisierte Antworten |
+| Intelligenter Dialog | Unterstützt mehrere LLM (große Sprachmodelle), implementiert intelligenten Dialog |
+| Visuelle Wahrnehmung | Unterstützt mehrere VLLM (Vision Large Models), implementiert multimodale Interaktion |
+| Absichtserkennung | Unterstützt LLM-Absichtserkennung, Function Call-Funktionsaufruf, bietet plugin-basierten Absichtsverarbeitungsmechanismus |
+| Gedächtnissystem | Unterstützt lokales Kurzzeitgedächtnis, mem0ai-Schnittstellengedächtnis, PowerMem intelligentes Gedächtnis, mit Gedächtniszusammenfassungsfunktion |
+| Wissensdatenbank | Unterstützt RAGFlow-Wissensdatenbank, ermöglicht großem Modell die Bewertung, ob Wissensdatenbank benötigt wird, bevor geantwortet wird |
+| Werkzeugaufruf | Unterstützt Client-IOT-Protokoll, Client-MCP-Protokoll, Server-MCP-Protokoll, MCP-Endpunktprotokoll, benutzerdefinierte Werkzeugfunktionen |
+| Befehlsübermittlung | Basierend auf MQTT-Protokoll, unterstützt die Übermittlung von MCP-Befehlen von der intelligenten Steuerkonsole an ESP32-Geräte |
+| Verwaltungs-Backend | Bietet Web-Verwaltungsoberfläche, unterstützt Benutzerverwaltung, Systemkonfiguration und Geräteverwaltung; Oberfläche unterstützt vereinfachtes Chinesisch, traditionelles Chinesisch und englische Anzeige |
+| Testwerkzeuge | Bietet Leistungstestwerkzeuge, Vision-Modell-Testwerkzeuge und Audio-Interaktionstestwerkzeuge |
+| Deployment-Unterstützung | Unterstützt Docker-Deployment und lokales Deployment, bietet vollständige Konfigurationsdateiverwaltung |
+| Plugin-System | Unterstützt funktionale Plugin-Erweiterungen, benutzerdefinierte Plugin-Entwicklung und Plugin-Hot-Loading |
+
+### In Entwicklung 🚧
+
+Um über spezifische Entwicklungsplanfortschritte zu erfahren, [klicken Sie hier](https://github.com/users/xinnan-tech/projects/3). Häufige Fragen und entsprechende Tutorials finden Sie unter [diesem Link](./docs/FAQ.md)
+
+Wenn Sie ein Softwareentwickler sind, finden Sie hier einen [Offenen Brief an Entwickler](docs/contributor_open_letter.md). Willkommen beim Beitritt!
+
+---
+
+## Produktökosystem 👬
+Xiaozhi ist ein Ökosystem. Wenn Sie dieses Produkt verwenden, können Sie sich auch andere [hervorragende Projekte](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) in diesem Ökosystem ansehen
+
+---
+
+## Liste der von diesem Projekt unterstützten Plattformen/Komponenten 📋
+### LLM-Sprachmodelle
+
+| Verwendungsmethode | Unterstützte Plattformen | Kostenlose Plattformen |
+|:---:|:---:|:---:|
+| OpenAI-Schnittstellenaufrufe | Alibaba Bailian, Volcano Engine Doubao, DeepSeek, Zhipu ChatGLM, Gemini | Zhipu ChatGLM, Gemini |
+| Ollama-Schnittstellenaufrufe | Ollama | - |
+| Dify-Schnittstellenaufrufe | Dify | - |
+| FastGPT-Schnittstellenaufrufe | FastGPT | - |
+| Coze-Schnittstellenaufrufe | Coze | - |
+| Xinference-Schnittstellenaufrufe | Xinference | - |
+| HomeAssistant-Schnittstellenaufrufe | HomeAssistant | - |
+
+Tatsächlich kann jedes LLM, das OpenAI-Schnittstellenaufrufe unterstützt, integriert und verwendet werden.
+
+---
+
+### VLLM-Vision-Modelle
+
+| Verwendungsmethode | Unterstützte Plattformen | Kostenlose Plattformen |
+|:---:|:---:|:---:|
+| OpenAI-Schnittstellenaufrufe | Alibaba Bailian, Zhipu ChatGLMVLLM | Zhipu ChatGLMVLLM |
+
+Tatsächlich kann jedes VLLM, das OpenAI-Schnittstellenaufrufe unterstützt, integriert und verwendet werden.
+
+---
+
+### TTS-Sprachsynthese
+
+| Verwendungsmethode | Unterstützte Plattformen | Kostenlose Plattformen |
+|:---:|:---:|:---:|
+| Schnittstellenaufrufe | EdgeTTS, Volcano Engine Doubao TTS, Tencent Cloud, Alibaba Cloud TTS, AliYun Stream TTS, CosyVoiceSiliconflow, TTS302AI, CozeCnTTS, GizwitsTTS, ACGNTTS, OpenAITTS, Lingxi Streaming TTS, MinimaxTTS, Volcano Dual-Stream TTS | Lingxi Streaming TTS, EdgeTTS, CosyVoiceSiliconflow (teilweise) |
+| Lokale Dienste | FishSpeech, GPT_SOVITS_V2, GPT_SOVITS_V3, Index-TTS, PaddleSpeech | Index-TTS, PaddleSpeech, FishSpeech, GPT_SOVITS_V2, GPT_SOVITS_V3 |
+
+---
+
+### VAD-Sprachaktivitätserkennung
+
+| Typ | Plattformname | Verwendungsmethode | Preismodell | Hinweise |
+|:---:|:---------:|:----:|:----:|:--:|
+| VAD | SileroVAD | Lokale Verwendung | Kostenlos | |
+
+---
+
+### ASR-Spracherkennung
+
+| Verwendungsmethode | Unterstützte Plattformen | Kostenlose Plattformen |
+|:---:|:---:|:---:|
+| Lokale Verwendung | FunASR, SherpaASR | FunASR, SherpaASR |
+| Schnittstellenaufrufe | DoubaoASR, Doubao Streaming ASR, FunASRServer, TencentASR, AliyunASR, Aliyun Streaming ASR, Baidu ASR, OpenAI ASR | FunASRServer |
+
+---
+
+### Voiceprint-Stimmabdruckerkennung
+
+| Verwendungsmethode | Unterstützte Plattformen | Kostenlose Plattformen |
+|:---:|:---:|:---:|
+| Lokale Verwendung | 3D-Speaker | 3D-Speaker |
+
+---
+
+### Memory-Gedächtnisspeicher
+
+| Typ | Plattformname | Verwendungsmethode | Preismodell | Hinweise |
+|:------:|:---------------:|:----:|:---------:|:--:|
+| Memory | mem0ai | Schnittstellenaufrufe | 1000 Mal/Monat Kontingent | |
+| Memory | [powermem](./docs/powermem-integration.md) | Lokale Zusammenfassung | Abhängig von LLM und DB | OceanBase Open Source, unterstützt intelligente Abfrage |
+| Memory | mem_local_short | Lokale Zusammenfassung | Kostenlos | |
+| Memory | nomem | Kein Gedächtnismodus | Kostenlos | |
+
+---
+
+### Intent-Absichtserkennung
+
+| Typ | Plattformname | Verwendungsmethode | Preismodell | Hinweise |
+|:------:|:-------------:|:----:|:-------:|:---------------------:|
+| Intent | intent_llm | Schnittstellenaufrufe | Basierend auf LLM-Preisen | Erkennt Absicht durch große Modelle, starke Allgemeingültigkeit |
+| Intent | function_call | Schnittstellenaufrufe | Basierend auf LLM-Preisen | Vervollständigt Absicht durch Funktionsaufruf großer Modelle, schnelle Geschwindigkeit, guter Effekt |
+| Intent | nointent | Kein Absichtsmodus | Kostenlos | Führt keine Absichtserkennung durch, gibt direkt Dialogergebnis zurück |
+
+---
+
+### Rag Retrieval Augmented Generation
+
+| Typ | Plattformname | Verwendungsmethode | Preismodell | Hinweise |
+|:------:|:-------------:|:----:|:-------:|:---------------------:|
+| Rag | ragflow | Schnittstellenaufrufe | Gebühren basierend auf Token-Verbrauch für Segmentierung und Tokenisierung | Nutzt RAGFlow's Retrieval-Augmented-Generation-Funktion für präzisere Dialogantworten |
+
+---
+
+## Danksagungen 🙏
+
+| Logo | Projekt/Unternehmen | Beschreibung |
+|:---:|:---:|:---|
+| <img src="./docs/images/logo_bailing.png" width="160"> | [Bailing Voice Dialogue Robot](https://github.com/wwbin2017/bailing) | Dieses Projekt wurde von [Bailing Voice Dialogue Robot](https://github.com/wwbin2017/bailing) inspiriert und auf dessen Basis implementiert |
+| <img src="./docs/images/logo_tenclass.png" width="160"> | [Tenclass](https://www.tenclass.com/) | Dank an [Tenclass](https://www.tenclass.com/) für die Formulierung von Standardkommunikationsprotokollen, Multi-Geräte-Kompatibilitätslösungen und High-Concurrency-Szenario-Praxisdemonstrationen für das Xiaozhi-Ökosystem; für die Bereitstellung vollständiger technischer Dokumentationsunterstützung für dieses Projekt |
+| <img src="./docs/images/logo_xuanfeng.png" width="160"> | [Xuanfeng Technology](https://github.com/Eric0308) | Dank an [Xuanfeng Technology](https://github.com/Eric0308) für den Beitrag des Funktionsaufruf-Frameworks, des MCP-Kommunikationsprotokolls und der plugin-basierten Aufrufmechanismus-Implementierungscode. Durch standardisiertes Befehlsplanungssystem und dynamische Erweiterungsfähigkeiten wird die Interaktionseffizienz und funktionale Erweiterbarkeit von Frontend-Geräten (IoT) erheblich verbessert |
+| <img src="./docs/images/logo_junsen.png" width="160"> | [huangjunsen](https://github.com/huangjunsen0406) | Dank an [huangjunsen](https://github.com/huangjunsen0406) für den Beitrag des `Smart Control Console Mobile`-Moduls, das eine effiziente Steuerung und Echtzeit-Interaktion über mobile Geräte ermöglicht und die Betriebsbequemlichkeit und Verwaltungseffizienz des Systems in mobilen Szenarien erheblich verbessert |
+| <img src="./docs/images/logo_huiyuan.png" width="160"> | [Huiyuan Design](http://ui.kwd988.net/) | Dank an [Huiyuan Design](http://ui.kwd988.net/) für die Bereitstellung professioneller visueller Lösungen für dieses Projekt, unter Verwendung ihrer Design-Praxiserfahrung im Dienst von über tausend Unternehmen, um die Produktbenutzererfahrung dieses Projekts zu stärken |
+| <img src="./docs/images/logo_qinren.png" width="160"> | [Xi'an Qinren Information Technology](https://www.029app.com/) | Dank an [Xi'an Qinren Information Technology](https://www.029app.com/) für die Vertiefung des visuellen Systems dieses Projekts und die Sicherstellung der Konsistenz und Erweiterbarkeit des Gesamtdesignstils in Multi-Szenario-Anwendungen |
+| <img src="./docs/images/logo_contributors.png" width="160"> | [Code-Mitwirkende](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors) | Dank an [alle Code-Mitwirkenden](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors), Ihre Bemühungen haben das Projekt robuster und leistungsfähiger gemacht. |
+
+
+<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>

README_en.md

@@ -6,29 +6,25 @@
 This project is based on human-machine symbiotic intelligence theory and technology to develop intelligent terminal hardware and software systems<br/>providing backend services for the open-source intelligent hardware project
 <a href="https://github.com/78/xiaozhi-esp32">xiaozhi-esp32</a><br/>
 Implemented using Python, Java, and Vue according to the <a href="https://ccnphfhqs21z.feishu.cn/wiki/M0XiwldO9iJwHikpXD5cEx71nKh">Xiaozhi Communication Protocol</a><br/>
-Supports MCP endpoints and voiceprint recognition
+Support for MQTT+UDP protocol, Websocket protocol, MCP access point, voiceprint recognition, and knowledge base
 </p>
 
 <p align="center">
-<a href="./README.md">中文</a>
+<a href="./docs/FAQ.md">FAQ</a>
-· <a href="./docs/FAQ.md">FAQ</a>
 · <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/issues">Report Issues</a>
 · <a href="./README.md#%E9%83%A8%E7%BD%B2%E6%96%87%E6%A1%A3">Deployment Docs</a>
 · <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/releases">Release Notes</a>
 </p>
+
 <p align="center">
+  <a href="./README.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-DFE0E5"></a>
+  <a href="./README_en.md"><img alt="README in English" src="https://img.shields.io/badge/English-DBEDFA"></a>
+  <a href="./README_vi.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/Tiếng Việt-DFE0E5"></a>
+  <a href="./README_de.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-DFE0E5"></a>
+  <a href="./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/graphs/contributors">
-    <img alt="GitHub Contributors" src="https://img.shields.io/github/contributors/xinnan-tech/xiaozhi-esp32-server?logo=github" />
-  </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>
   <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>
@@ -186,9 +182,10 @@ This project provides two deployment methods. Please choose based on your specif
 #### 🚀 Deployment Method Selection
 | Deployment Method | Features | Applicable Scenarios | Deployment Docs | Configuration Requirements | Video Tutorials | 
 |---------|------|---------|---------|---------|---------|
-| **Simplified Installation** | Intelligent dialogue, IOT, MCP, visual perception | Low-configuration environments, data stored in config files, no database required | [①Docker Version](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) / [②Source Code Deployment](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E5%8F%AA%E8%BF%90%E8%A1%8Cserver)| 2 cores 4GB if using `FunASR`, 2 cores 2GB if all APIs | - | 
+| **Simplified Installation** | Intelligent dialogue, single agent management | Low-configuration environments, data stored in config files, no database required | [①Docker Version](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) / [②Source Code Deployment](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E5%8F%AA%E8%BF%90%E8%A1%8Cserver)| 2 cores 4GB if using `FunASR`, 2 cores 2GB if all APIs | - | 
-| **Full Module Installation** | Intelligent dialogue, IOT, MCP endpoints, voiceprint recognition, visual perception, OTA, intelligent control console | Complete functionality experience, data stored in database |[①Docker Version](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [②Source Code Deployment](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [③Source Code Deployment Auto-Update Tutorial](./docs/dev-ops-integration.md) | 4 cores 8GB if using `FunASR`, 2 cores 4GB if all APIs| [Local Source Code Startup Video Tutorial](https://www.bilibili.com/video/BV1wBJhz4Ewe) | 
+| **Full Module Installation** | Intelligent dialogue, multi-user management, multi-agent management, intelligent console interface operation | Complete functionality experience, data stored in database |[①Docker Version](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [②Source Code Deployment](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [③Source Code Deployment Auto-Update Tutorial](./docs/dev-ops-integration.md) | 4 cores 8GB if using `FunASR`, 2 cores 4GB if all APIs| [Local Source Code Startup Video Tutorial](https://www.bilibili.com/video/BV1wBJhz4Ewe) |
 
+For frequently asked questions and related tutorials, please refer to [this link](./docs/FAQ.md)
 
 > 💡 Note: Below is a test platform deployed with the latest code. You can burn and test if needed. Concurrent users: 6, data will be cleared daily.
 
@@ -213,21 +210,22 @@ Websocket Interface Address: wss://2662r3426b.vicp.fun/xiaozhi/v1/
 
 | Module Name | Entry Level Free Settings | Streaming Configuration |
 |:---:|:---:|:---:|
-| ASR(Speech Recognition) | FunASR(Local) | 👍FunASRServer or 👍DoubaoStreamASR |
+| ASR(Speech Recognition) | FunASR(Local) | 👍XunfeiStreamASR(Xunfei Streaming) |
-| LLM(Large Model) | ChatGLMLLM(Zhipu glm-4-flash) | 👍DoubaoLLM(Volcano doubao-1-5-pro-32k-250115) |
+| LLM(Large Model) | glm-4-flash(Zhipu) | 👍qwen-flash(Alibaba Bailian) |
-| VLLM(Vision Large Model) | ChatGLMVLLM(Zhipu glm-4v-flash) | 👍QwenVLVLLM(Qwen qwen2.5-vl-3b-instructh) |
+| VLLM(Vision Large Model) | glm-4v-flash(Zhipu) | 👍qwen2.5-vl-3b-instructh(Alibaba Bailian) |
-| TTS(Speech Synthesis) | ✅LinkeraiTTS(Lingxi streaming) | 👍HuoshanDoubleStreamTTS(Volcano dual-stream speech synthesis) |
+| TTS(Speech Synthesis) | ✅LinkeraiTTS(Lingxi streaming) | 👍HuoshanDoubleStreamTTS(Volcano Streaming) |
 | Intent(Intent Recognition) | function_call(Function calling) | function_call(Function calling) |
 | Memory(Memory function) | mem_local_short(Local short-term memory) | mem_local_short(Local short-term memory) |
 
+If you are concerned about the latency of each component, please refer to the [Xiaozhi Component Performance Test Report](https://github.com/xinnan-tech/xiaozhi-performance-research), and test in your own environment following the test methods in the report.
+
 #### 🔧 Testing Tools
 This project provides the following testing tools to help you verify the system and choose suitable models:
 
 | Tool Name | Location | Usage Method | Function Description |
 |:---:|:---|:---:|:---:|
 | Audio Interaction Test Tool | main》xiaozhi-server》test》test_page.html | Open directly with Google Chrome | Tests audio playback and reception functions, verifies if Python-side audio processing is normal |
-| Model Response Test Tool 1 | main》xiaozhi-server》performance_tester.py | Execute `python performance_tester.py` | Tests response speed of three core modules: ASR(speech recognition), LLM(large model), TTS(speech synthesis) |
+| Model Response Test Tool | main》xiaozhi-server》performance_tester.py | Execute `python performance_tester.py` | Tests response speed of three core modules: ASR(speech recognition), LLM(large model), VLLM(vision model), TTS(speech synthesis) |
-| Model Response Test Tool 2 | main》xiaozhi-server》performance_tester_vllm.py | Execute `python performance_tester_vllm.py` | Tests VLLM(vision model) response speed |
 
 > 💡 Note: When testing model speed, only models with configured keys will be tested.
 
@@ -243,9 +241,10 @@ This project provides the following testing tools to help you verify the system
 | Intelligent Dialogue | Supports multiple LLM(large language models), implements intelligent dialogue |
 | Visual Perception | Supports multiple VLLM(vision large models), implements multimodal interaction |
 | Intent Recognition | Supports LLM intent recognition, Function Call function calling, provides plugin-based intent processing mechanism |
-| Memory System | Supports local short-term memory, mem0ai interface memory, with memory summarization functionality |
+| Memory System | Supports local short-term memory, mem0ai interface memory, PowerMem intelligent memory, with memory summarization functionality |
-| Command Delivery | Supports MCP command delivery to ESP32 devices via MQTT protocol from Smart Console |
+| Knowledge Base | Supports RAGFlow knowledge base, enabling LLM to judge whether to schedule the knowledge base after receiving the user's question, and then answer the question |
 | Tool Calling | Supports client IOT protocol, client MCP protocol, server MCP protocol, MCP endpoint protocol, custom tool functions |
+| Command Delivery | Supports MCP command delivery to ESP32 devices via MQTT protocol from Smart Console |
 | Management Backend | Provides Web management interface, supports user management, system configuration and device management; Supports Simplified Chinese, Traditional Chinese and English display |
 | Testing Tools | Provides performance testing tools, vision model testing tools, and audio interaction testing tools |
 | Deployment Support | Supports Docker deployment and local deployment, provides complete configuration file management |
@@ -253,20 +252,14 @@ This project provides the following testing tools to help you verify the system
 
 ### Under Development 🚧
 
-To learn about specific development plan progress, [click here](https://github.com/users/xinnan-tech/projects/3)
+To learn about specific development plan progress, [click here](https://github.com/users/xinnan-tech/projects/3). For frequently asked questions and related tutorials, please refer to [this link](./docs/FAQ.md)
 
 If you are a software developer, here is an [Open Letter to Developers](docs/contributor_open_letter.md). Welcome to join!
 
 ---
 
 ## Product Ecosystem 👬
-Xiaozhi is an ecosystem. When using this product, you can also check out other [excellent projects](https://github.com/78/xiaozhi-esp32?tab=readme-ov-file#%E7%9B%B8%E5%85%B3%E5%BC%80%E6%BA%90%E9%A1%B9%E7%9B%AE) in this ecosystem
+Xiaozhi is an ecosystem. When using this product, you can also check out other [excellent projects](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) in this ecosystem
-
-| Project Name | Project Address | Project Description |
-|:---------------------|:--------|:--------|
-| Xiaozhi Android Client | [xiaozhi-android-client](https://github.com/TOM88812/xiaozhi-android-client) | An Android and iOS voice dialogue application based on xiaozhi-server, supporting real-time voice interaction and text dialogue.<br/>Currently a Flutter version, connecting iOS and Android platforms. |
-| Xiaozhi Desktop Client | [py-xiaozhi](https://github.com/Huang-junsen/py-xiaozhi) | This project provides a Python-based AI client for beginners, allowing users to experience Xiaozhi AI functionality through code even without physical hardware conditions. |
-| Xiaozhi Java Server | [xiaozhi-esp32-server-java](https://github.com/joey-zhou/xiaozhi-esp32-server-java) | Xiaozhi open-source backend service Java version is a Java-based open-source project.<br/>It includes frontend and backend services, aiming to provide users with a complete backend service solution. |
 
 ---
 
@@ -275,13 +268,15 @@ Xiaozhi is an ecosystem. When using this product, you can also check out other [
 
 | Usage Method | Supported Platforms | Free Platforms |
 |:---:|:---:|:---:|
-| OpenAI interface calls | Alibaba Bailian, Volcano Engine Doubao, DeepSeek, Zhipu ChatGLM, Gemini | Zhipu ChatGLM, Gemini |
+| OpenAI interface calls | Alibaba Bailian, Volcano Engine, DeepSeek, Zhipu, Gemini, iFLYTEK | Zhipu, Gemini |
 | Ollama interface calls | Ollama | - |
 | Dify interface calls | Dify | - |
 | FastGPT interface calls | FastGPT | - |
 | Coze interface calls | Coze | - |
+| Xinference interface calls | Xinference | - |
+| HomeAssistant interface calls | HomeAssistant | - |
 
-In fact, any LLM that supports OpenAI interface calls can be integrated and used, including Xinference and HomeAssistant interfaces.
+In fact, any LLM that supports OpenAI interface calls can be integrated and used.
 
 ---
 
@@ -299,8 +294,8 @@ In fact, any VLLM that supports OpenAI interface calls can be integrated and use
 
 | Usage Method | Supported Platforms | Free Platforms |
 |:---:|:---:|:---:|
-| Interface calls | EdgeTTS, Volcano Engine Doubao TTS, Tencent Cloud, Alibaba Cloud TTS, AliYun Stream TTS, CosyVoiceSiliconflow, TTS302AI, CozeCnTTS, GizwitsTTS, ACGNTTS, OpenAITTS, Lingxi Streaming TTS, MinimaxTTS | Lingxi Streaming TTS, EdgeTTS, CosyVoiceSiliconflow(partial) |
+| Interface calls | EdgeTTS, iFLYTEK, Volcano Engine, Tencent Cloud, Alibaba Cloud and Bailian, CosyVoiceSiliconflow, TTS302AI, CozeCnTTS, GizwitsTTS, ACGNTTS, OpenAITTS, Lingxi Streaming TTS, MinimaxTTS | Lingxi Streaming TTS, EdgeTTS, CosyVoiceSiliconflow(partial) |
-| Local services | FishSpeech, GPT_SOVITS_V2, GPT_SOVITS_V3, MinimaxTTS | FishSpeech, GPT_SOVITS_V2, GPT_SOVITS_V3, MinimaxTTS |
+| Local services | FishSpeech, GPT_SOVITS_V2, GPT_SOVITS_V3, Index-TTS, PaddleSpeech | Index-TTS, PaddleSpeech, FishSpeech, GPT_SOVITS_V2, GPT_SOVITS_V3 |
 
 ---
 
@@ -317,7 +312,7 @@ In fact, any VLLM that supports OpenAI interface calls can be integrated and use
 | Usage Method | Supported Platforms | Free Platforms |
 |:---:|:---:|:---:|
 | Local use | FunASR, SherpaASR | FunASR, SherpaASR |
-| Interface calls | DoubaoASR, FunASRServer, TencentASR, AliyunASR | FunASRServer |
+| Interface calls | FunASRServer, Volcano Engine, iFLYTEK, Tencent Cloud, Alibaba Cloud, Baidu Cloud, OpenAI ASR | FunASRServer |
 
 ---
 
@@ -334,7 +329,9 @@ In fact, any VLLM that supports OpenAI interface calls can be integrated and use
 | Type | Platform Name | Usage Method | Pricing Model | Notes |
 |:------:|:---------------:|:----:|:---------:|:--:|
 | Memory | mem0ai | Interface calls | 1000 times/month quota | |
+| Memory | [powermem](./docs/powermem-integration.md) | Local summarization | Depends on LLM and DB | OceanBase open source, supports intelligent retrieval |
 | Memory | mem_local_short | Local summarization | Free | |
+| Memory | nomem | No memory mode | Free | |
 
 ---
 
@@ -344,6 +341,15 @@ In fact, any VLLM that supports OpenAI interface calls can be integrated and use
 |:------:|:-------------:|:----:|:-------:|:---------------------:|
 | Intent | intent_llm | Interface calls | Based on LLM pricing | Recognizes intent through large models, strong generalization |
 | Intent | function_call | Interface calls | Based on LLM pricing | Completes intent through large model function calling, fast speed, good effect |
+| Intent | nointent | No intent mode | Free | Does not perform intent recognition, directly returns dialogue result |
+
+---
+
+### Rag Retrieval-Augmented Generation
+
+| Type | Platform Name | Usage Method | Pricing Model | Notes |
+|:------:|:-------------:|:----:|:-------:|:---------------------:|
+| Rag | ragflow | Interface calls | Charged based on tokens consumed for slicing and word segmentation | Utilizes RagFlow's retrieval-augmented generation feature to provide more accurate dialog responses |
 
 ---
 

README_pt_BR.md

@@ -0,0 +1,376 @@
+[![Banners](docs/images/banner1.png)](https://github.com/xinnan-tech/xiaozhi-esp32-server)
+
+<h1 align="center">Serviço Backend Xiaozhi xiaozhi-esp32-server</h1>
+
+<p align="center">
+Este projeto é baseado na teoria e tecnologia de inteligência simbiótica humano-máquina para desenvolver sistemas inteligentes de hardware e software para terminais<br/>fornecendo serviços de backend para o projeto de hardware inteligente de código aberto
+<a href="https://github.com/78/xiaozhi-esp32">xiaozhi-esp32</a><br/>
+Implementado usando Python, Java e Vue de acordo com o <a href="https://ccnphfhqs21z.feishu.cn/wiki/M0XiwldO9iJwHikpXD5cEx71nKh">Protocolo de Comunicação Xiaozhi</a><br/>
+Suporte ao protocolo MQTT+UDP, protocolo WebSocket, ponto de acesso MCP, reconhecimento de impressão vocal e base de conhecimento
+</p>
+
+<p align="center">
+<a href="./docs/FAQ.md">Perguntas Frequentes</a>
+· <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/issues">Reportar Problemas</a>
+· <a href="./README.md#%E9%83%A8%E7%BD%B2%E6%96%87%E6%A1%A3">Documentação de Implantação</a>
+· <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/releases">Notas de Lançamento</a>
+</p>
+
+<p align="center">
+  <a href="./README.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-DFE0E5"></a>
+  <a href="./README_en.md"><img alt="README in English" src="https://img.shields.io/badge/English-DFE0E5"></a>
+  <a href="./README_vi.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/Tiếng Việt-DFE0E5"></a>
+  <a href="./README_de.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-DFE0E5"></a>
+  <a href="./README_pt_BR.md"><img alt="Português (Brasil)" src="https://img.shields.io/badge/Português (Brasil)-DBEDFA"></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/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">
+    <img alt="stars" src="https://img.shields.io/github/stars/xinnan-tech/xiaozhi-esp32-server?color=ffcb47&labelColor=black" />
+  </a>
+</p>
+
+<p align="center">
+Liderado pela Equipe do Professor Siyuan Liu (Universidade de Tecnologia do Sul da China)
+</br>
+刘思源教授团队主导研发（华南理工大学）
+</br>
+<img src="./docs/images/hnlg.jpg" alt="Universidade de Tecnologia do Sul da China (华南理工大学)" width="50%">
+</p>
+
+---
+
+## Público-Alvo 👥
+
+Este projeto requer dispositivos de hardware ESP32 para funcionar. Se você adquiriu hardware relacionado ao ESP32, conectou-se com sucesso ao serviço backend implantado pelo Brother Xia e deseja construir seu próprio serviço backend `xiaozhi-esp32` de forma independente, então este projeto é perfeito para você.
+
+Quer ver os efeitos de uso? Clique nos vídeos abaixo 🎥
+
+<table>
+  <tr>
+    <td>
+        <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
+         <picture>
+           <img alt="Experiência de velocidade de resposta" src="docs/images/demo9.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+        <a href="https://www.bilibili.com/video/BV1vchQzaEse" target="_blank">
+         <picture>
+           <img alt="Segredo da otimização de velocidade" src="docs/images/demo6.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+        <a href="https://www.bilibili.com/video/BV1C1tCzUEZh" target="_blank">
+         <picture>
+           <img alt="Cenário médico complexo" src="docs/images/demo1.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+        <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
+         <picture>
+           <img alt="Envio de comandos MQTT" src="docs/images/demo4.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+        <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
+         <picture>
+           <img alt="Reconhecimento de impressão vocal" src="docs/images/demo14.png" />
+         </picture>
+        </a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+        <a href="https://www.bilibili.com/video/BV1pNXWYGEx1" target="_blank">
+         <picture>
+           <img alt="Controle de interruptores de eletrodomésticos" src="docs/images/demo5.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+        <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
+         <picture>
+           <img alt="Ponto de acesso MCP" src="docs/images/demo13.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1TJ7WzzEo6" target="_blank">
+         <picture>
+           <img alt="Tarefas com múltiplos comandos" src="docs/images/demo11.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+        <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
+         <picture>
+           <img alt="Reproduzir música" src="docs/images/demo7.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+        <a href="https://www.bilibili.com/video/BV1Z8XuYZEAS" target="_blank">
+         <picture>
+           <img alt="Plugin de clima" src="docs/images/demo8.png" />
+         </picture>
+        </a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <a href="https://www.bilibili.com/video/BV12J7WzBEaH" target="_blank">
+         <picture>
+           <img alt="Interrupção em tempo real" src="docs/images/demo10.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1Co76z7EvK" target="_blank">
+         <picture>
+           <img alt="Fotografar e identificar objetos" src="docs/images/demo12.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+        <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
+         <picture>
+           <img alt="Timbre de voz personalizado" src="docs/images/demo2.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+        <a href="https://www.bilibili.com/video/BV12yA2egEaC" target="_blank">
+         <picture>
+           <img alt="Comunicação em cantonês" src="docs/images/demo3.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+        <a href="https://www.bilibili.com/video/BV17LXWYvENb" target="_blank">
+         <picture>
+           <img alt="Transmissão de notícias" src="docs/images/demo0.png" />
+         </picture>
+        </a>
+    </td>
+  </tr>
+</table>
+
+---
+
+## Avisos ⚠️
+
+1. Este projeto é um software de código aberto. Este software não possui parceria comercial com nenhum provedor de serviços de API de terceiros (incluindo, mas não se limitando a reconhecimento de fala, modelos de linguagem, síntese de voz e outras plataformas) com os quais se conecta, e não fornece nenhuma forma de garantia quanto à qualidade de serviço ou segurança financeira desses provedores. Recomenda-se que os usuários priorizem provedores de serviço com licenças comerciais relevantes e leiam cuidadosamente seus termos de serviço e políticas de privacidade. Este software não armazena nenhuma chave de conta, não participa de fluxos de fundos e não assume o risco de perda de fundos recarregados.
+
+2. A funcionalidade deste projeto não está completa e não passou por avaliação de segurança de rede. Por favor, não o utilize em ambientes de produção. Se você implantar este projeto para fins de aprendizado em um ambiente de rede pública, certifique-se de que as medidas de proteção necessárias estejam em vigor.
+
+---
+
+## Documentação de Implantação
+
+![Banners](docs/images/banner2.png)
+
+Este projeto oferece dois métodos de implantação. Por favor, escolha de acordo com suas necessidades específicas:
+
+#### 🚀 Seleção do Método de Implantação
+| Método de Implantação | Funcionalidades | Cenários Aplicáveis | Documentação de Implantação | Requisitos de Configuração | Tutoriais em Vídeo |
+|---------|------|---------|---------|---------|---------|
+| **Instalação Simplificada** | Diálogo inteligente, gerenciamento de agente único | Ambientes de baixa configuração, dados armazenados em arquivos de configuração, sem necessidade de banco de dados | [①Versão Docker](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) / [②Implantação via Código-Fonte](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E5%8F%AA%E8%BF%90%E8%A1%8Cserver)| 2 núcleos 4GB se usar `FunASR`, 2 núcleos 2GB se todas APIs | - |
+| **Instalação de Módulo Completo** | Diálogo inteligente, gerenciamento multiusuário, gerenciamento de múltiplos agentes, operação de interface do console inteligente | Experiência com funcionalidade completa, dados armazenados em banco de dados |[①Versão Docker](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [②Implantação via Código-Fonte](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [③Tutorial de Atualização Automática via Código-Fonte](./docs/dev-ops-integration.md) | 4 núcleos 8GB se usar `FunASR`, 2 núcleos 4GB se todas APIs| [Tutorial em Vídeo de Inicialização via Código-Fonte Local](https://www.bilibili.com/video/BV1wBJhz4Ewe) |
+
+Perguntas frequentes e tutoriais relacionados podem ser consultados [neste link](./docs/FAQ.md)
+
+> 💡 Nota: Abaixo está uma plataforma de teste implantada com o código mais recente. Você pode gravar e testar se necessário. Usuários simultâneos: 6, os dados serão limpos diariamente.
+
+```
+Endereço do Console de Controle Inteligente: https://2662r3426b.vicp.fun
+Endereço do Console de Controle Inteligente (H5): https://2662r3426b.vicp.fun/h5/index.html
+
+Ferramenta de Teste de Serviço: https://2662r3426b.vicp.fun/test/
+Endereço da Interface OTA: https://2662r3426b.vicp.fun/xiaozhi/ota/
+Endereço da Interface WebSocket: wss://2662r3426b.vicp.fun/xiaozhi/v1/
+```
+
+#### 🚩 Descrição e Recomendações de Configuração
+> [!Note]
+> Este projeto oferece dois esquemas de configuração:
+>
+> 1. `Configurações Gratuitas Nível Básico`: Adequado para uso pessoal e doméstico, todos os componentes utilizam soluções gratuitas, sem necessidade de pagamento adicional.
+>
+> 2. `Configuração de Streaming`: Adequado para demonstrações, treinamentos, cenários com mais de 2 usuários simultâneos, etc. Utiliza tecnologia de processamento em streaming para velocidade de resposta mais rápida e melhor experiência.
+>
+> A partir da versão `0.5.2`, o projeto suporta configuração de streaming. Em comparação com versões anteriores, a velocidade de resposta é melhorada em aproximadamente `2,5 segundos`, melhorando significativamente a experiência do usuário.
+
+| Nome do Módulo | Configurações Gratuitas Nível Básico | Configuração de Streaming |
+|:---:|:---:|:---:|
+| ASR(Reconhecimento de Fala) | FunASR(Local) | 👍XunfeiStreamASR(Xunfei Streaming) |
+| LLM(Modelo de Linguagem) | glm-4-flash(Zhipu) | 👍qwen-flash(Alibaba Bailian) |
+| VLLM(Modelo de Visão) | glm-4v-flash(Zhipu) | 👍qwen2.5-vl-3b-instructh(Alibaba Bailian) |
+| TTS(Síntese de Voz) | ✅LinkeraiTTS(Lingxi streaming) | 👍HuoshanDoubleStreamTTS(Volcano Streaming) |
+| Intent(Reconhecimento de Intenção) | function_call(Chamada de função) | function_call(Chamada de função) |
+| Memory(Função de Memória) | mem_local_short(Memória local de curto prazo) | mem_local_short(Memória local de curto prazo) |
+
+Se você está preocupado com o tempo de resposta de cada componente, consulte o [Relatório de Teste de Desempenho dos Componentes Xiaozhi](https://github.com/xinnan-tech/xiaozhi-performance-research), e teste em seu próprio ambiente seguindo os métodos de teste do relatório.
+
+#### 🔧 Ferramentas de Teste
+Este projeto fornece as seguintes ferramentas de teste para ajudá-lo a verificar o sistema e escolher modelos adequados:
+
+| Nome da Ferramenta | Localização | Método de Uso | Descrição da Função |
+|:---:|:---|:---:|:---:|
+| Ferramenta de Teste de Interação por Áudio | main》xiaozhi-server》test》test_page.html | Abrir diretamente com Google Chrome | Testa as funções de reprodução e recepção de áudio, verifica se o processamento de áudio no lado Python está normal |
+| Ferramenta de Teste de Resposta de Modelo | main》xiaozhi-server》performance_tester.py | Execute `python performance_tester.py` | Testa a velocidade de resposta dos três módulos principais: ASR(reconhecimento de fala), LLM(modelo de linguagem), VLLM(modelo de visão), TTS(síntese de voz) |
+
+> 💡 Nota: Ao testar a velocidade dos modelos, apenas os modelos com chaves configuradas serão testados.
+
+---
+## Lista de Funcionalidades ✨
+### Implementado ✅
+![请参考-全模块安装架构图](docs/images/deploy2.png)
+| Módulo de Funcionalidade | Descrição |
+|:---:|:---|
+| Arquitetura Principal | Baseado em [gateway MQTT+UDP](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/main/docs/mqtt-gateway-integration.md), servidores WebSocket e HTTP, fornece sistema completo de gerenciamento de console e autenticação |
+| Interação por Voz | Suporta ASR em streaming (reconhecimento de fala), TTS em streaming (síntese de voz), VAD (detecção de atividade vocal), suporta reconhecimento multilíngue e processamento de voz |
+| Reconhecimento de Impressão Vocal | Suporta registro, gerenciamento e reconhecimento de impressão vocal de múltiplos usuários, processa em paralelo com o ASR, reconhecimento de identidade do falante em tempo real e repassa ao LLM para respostas personalizadas |
+| Diálogo Inteligente | Suporta múltiplos LLM (modelos de linguagem de grande porte), implementa diálogo inteligente |
+| Percepção Visual | Suporta múltiplos VLLM (modelos de visão de grande porte), implementa interação multimodal |
+| Reconhecimento de Intenção | Suporta reconhecimento de intenção por LLM, Function Call (chamada de função), fornece mecanismo de processamento de intenção baseado em plugins |
+| Sistema de Memória | Suporta memória local de curto prazo, memória via interface mem0ai, memória inteligente PowerMem, com funcionalidade de resumo de memória |
+| Base de Conhecimento | Suporta base de conhecimento RAGFlow, permitindo que o LLM julgue se deve acionar a base de conhecimento após receber a pergunta do usuário, e então responda à pergunta |
+| Chamada de Ferramentas | Suporta protocolo IOT do cliente, protocolo MCP do cliente, protocolo MCP do servidor, protocolo de endpoint MCP, funções de ferramentas personalizadas |
+| Envio de Comandos | Suporta envio de comandos MCP para dispositivos ESP32 via protocolo MQTT a partir do Console Inteligente |
+| Backend de Gerenciamento | Fornece interface de gerenciamento Web, suporta gerenciamento de usuários, configuração do sistema e gerenciamento de dispositivos; Suporta exibição em Chinês Simplificado, Chinês Tradicional e Inglês |
+| Ferramentas de Teste | Fornece ferramentas de teste de desempenho, ferramentas de teste de modelo de visão e ferramentas de teste de interação por áudio |
+| Suporte à Implantação | Suporta implantação via Docker e implantação local, fornece gerenciamento completo de arquivos de configuração |
+| Sistema de Plugins | Suporta extensões de plugins funcionais, desenvolvimento de plugins personalizados e carregamento dinâmico de plugins |
+
+### Em Desenvolvimento 🚧
+
+Para conhecer o progresso específico do plano de desenvolvimento, [clique aqui](https://github.com/users/xinnan-tech/projects/3). Perguntas frequentes e tutoriais relacionados podem ser consultados [neste link](./docs/FAQ.md)
+
+Se você é um desenvolvedor de software, aqui está uma [Carta Aberta aos Desenvolvedores](docs/contributor_open_letter.md). Seja bem-vindo a participar!
+
+---
+
+## Ecossistema do Produto 👬
+Xiaozhi é um ecossistema. Ao utilizar este produto, você também pode conferir outros [projetos excelentes](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) neste ecossistema
+
+---
+
+## Lista de Plataformas/Componentes Suportados 📋
+### LLM Modelos de Linguagem
+
+| Método de Uso | Plataformas Suportadas | Plataformas Gratuitas |
+|:---:|:---:|:---:|
+| Chamadas via interface OpenAI | Alibaba Bailian, Volcano Engine, DeepSeek, Zhipu, Gemini, iFLYTEK | Zhipu, Gemini |
+| Chamadas via interface Ollama | Ollama | - |
+| Chamadas via interface Dify | Dify | - |
+| Chamadas via interface FastGPT | FastGPT | - |
+| Chamadas via interface Coze | Coze | - |
+| Chamadas via interface Xinference | Xinference | - |
+| Chamadas via interface HomeAssistant | HomeAssistant | - |
+
+Na verdade, qualquer LLM que suporte chamadas via interface openai pode ser integrado e utilizado.
+
+---
+
+### VLLM Modelos de Visão
+
+| Método de Uso | Plataformas Suportadas | Plataformas Gratuitas |
+|:---:|:---:|:---:|
+| Chamadas via interface OpenAI | Alibaba Bailian, Zhipu ChatGLMVLLM | Zhipu ChatGLMVLLM |
+
+Na verdade, qualquer VLLM que suporte chamadas via interface OpenAI pode ser integrado e utilizado.
+
+---
+
+### TTS Síntese de Voz
+
+| Método de Uso | Plataformas Suportadas | Plataformas Gratuitas |
+|:---:|:---:|:---:|
+| Chamadas via interface | EdgeTTS, iFLYTEK, Volcano Engine, Tencent Cloud, Alibaba Cloud e Bailian, CosyVoiceSiliconflow, TTS302AI, CozeCnTTS, GizwitsTTS, ACGNTTS, OpenAITTS, Lingxi Streaming TTS, MinimaxTTS | Lingxi Streaming TTS, EdgeTTS, CosyVoiceSiliconflow(parcial) |
+| Serviços locais | FishSpeech, GPT_SOVITS_V2, GPT_SOVITS_V3, Index-TTS, PaddleSpeech | Index-TTS, PaddleSpeech, FishSpeech, GPT_SOVITS_V2, GPT_SOVITS_V3 |
+
+---
+
+### VAD Detecção de Atividade Vocal
+
+| Tipo | Nome da Plataforma | Método de Uso | Modelo de Preço | Observações |
+|:---:|:---------:|:----:|:----:|:--:|
+| VAD | SileroVAD | Uso local | Gratuito | |
+
+---
+
+### ASR Reconhecimento de Fala
+
+| Método de Uso | Plataformas Suportadas | Plataformas Gratuitas |
+|:---:|:---:|:---:|
+| Uso local | FunASR, SherpaASR | FunASR, SherpaASR |
+| Chamadas via interface | FunASRServer, Volcano Engine, iFLYTEK, Tencent Cloud, Alibaba Cloud, Baidu Cloud, OpenAI ASR | FunASRServer |
+
+---
+
+### Reconhecimento de Impressão Vocal
+
+| Método de Uso | Plataformas Suportadas | Plataformas Gratuitas |
+|:---:|:---:|:---:|
+| Uso local | 3D-Speaker | 3D-Speaker |
+
+---
+
+### Armazenamento de Memória
+
+| Tipo | Nome da Plataforma | Método de Uso | Modelo de Preço | Observações |
+|:------:|:---------------:|:----:|:---------:|:--:|
+| Memória | mem0ai | Chamadas via interface | Cota de 1000 vezes/mês | |
+| Memória | [powermem](./docs/powermem-integration.md) | Resumo local | Depende do LLM e BD | OceanBase de código aberto, suporta busca inteligente |
+| Memória | mem_local_short | Resumo local | Gratuito | |
+| Memória | nomem | Modo sem memória | Gratuito | |
+
+---
+
+### Reconhecimento de Intenção
+
+| Tipo | Nome da Plataforma | Método de Uso | Modelo de Preço | Observações |
+|:------:|:-------------:|:----:|:-------:|:---------------------:|
+| Intenção | intent_llm | Chamadas via interface | Baseado no preço do LLM | Reconhece intenção através de modelos de linguagem, forte generalização |
+| Intenção | function_call | Chamadas via interface | Baseado no preço do LLM | Completa a intenção através de chamada de função do modelo de linguagem, velocidade rápida, bom resultado |
+| Intenção | nointent | Modo sem intenção | Gratuito | Não realiza reconhecimento de intenção, retorna diretamente o resultado do diálogo |
+
+---
+
+### RAG Geração Aumentada por Recuperação
+
+| Tipo | Nome da Plataforma | Método de Uso | Modelo de Preço | Observações |
+|:------:|:-------------:|:----:|:-------:|:---------------------:|
+| RAG | ragflow | Chamadas via interface | Cobrado com base nos tokens consumidos para fatiamento e segmentação de palavras | Utiliza o recurso de geração aumentada por recuperação do RagFlow para fornecer respostas de diálogo mais precisas |
+
+---
+
+## Agradecimentos 🙏
+
+| Logo | Projeto/Empresa | Descrição |
+|:---:|:---:|:---|
+| <img src="./docs/images/logo_bailing.png" width="160"> | [Robô de Diálogo por Voz Bailing](https://github.com/wwbin2017/bailing) | Este projeto foi inspirado pelo [Robô de Diálogo por Voz Bailing](https://github.com/wwbin2017/bailing) e implementado com base nele |
+| <img src="./docs/images/logo_tenclass.png" width="160"> | [Tenclass](https://www.tenclass.com/) | Agradecimentos à [Tenclass](https://www.tenclass.com/) por formular protocolos de comunicação padrão, soluções de compatibilidade multidispositivo e demonstrações práticas de cenários de alta concorrência para o ecossistema Xiaozhi; fornecendo suporte completo de documentação técnica para este projeto |
+| <img src="./docs/images/logo_xuanfeng.png" width="160"> | [Xuanfeng Technology (玄凤科技)](https://github.com/Eric0308) | Agradecimentos à [Xuanfeng Technology](https://github.com/Eric0308) por contribuir com o framework de chamada de função, protocolo de comunicação MCP e implementação do mecanismo de chamada baseado em plugins. Através de um sistema padronizado de agendamento de instruções e capacidades de expansão dinâmica, melhora significativamente a eficiência de interação e extensibilidade funcional dos dispositivos de frontend (IoT) |
+| <img src="./docs/images/logo_junsen.png" width="160"> | [huangjunsen](https://github.com/huangjunsen0406) | Agradecimentos a [huangjunsen](https://github.com/huangjunsen0406) por contribuir com o módulo `Console de Controle Inteligente Mobile`, que permite controle eficiente e interação em tempo real em dispositivos móveis, melhorando significativamente a conveniência operacional e a eficiência de gerenciamento do sistema em cenários móveis. |
+| <img src="./docs/images/logo_huiyuan.png" width="160"> | [Huiyuan Design (汇远设计)](http://ui.kwd988.net/) | Agradecimentos à [Huiyuan Design](http://ui.kwd988.net/) por fornecer soluções visuais profissionais para este projeto, utilizando sua experiência prática de design atendendo mais de mil empresas para potencializar a experiência do usuário deste produto |
+| <img src="./docs/images/logo_qinren.png" width="160"> | [Xi'an Qinren Information Technology (西安勤人信息科技)](https://www.029app.com/) | Agradecimentos à [Xi'an Qinren Information Technology](https://www.029app.com/) por aprofundar o sistema visual deste projeto, garantindo consistência e extensibilidade do estilo de design geral em aplicações de múltiplos cenários |
+| <img src="./docs/images/logo_contributors.png" width="160"> | [Contribuidores de Código](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors) | Agradecimentos a [todos os contribuidores de código](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors), seus esforços tornaram o projeto mais robusto e poderoso. |
+
+
+<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>

README_vi.md

@@ -0,0 +1,377 @@
+[![Banners](docs/images/banner1.png)](https://github.com/xinnan-tech/xiaozhi-esp32-server)
+
+<h1 align="center">Dịch vụ Backend Xiaozhi xiaozhi-esp32-server</h1>
+
+<p align="center">
+Dự án này dựa trên lý thuyết và công nghệ trí tuệ cộng sinh người-máy để phát triển hệ thống phần mềm và phần cứng thiết bị đầu cuối thông minh<br/>Cung cấp dịch vụ backend cho dự án phần cứng thông minh mã nguồn mở
+<a href="https://github.com/78/xiaozhi-esp32">xiaozhi-esp32</a><br/>
+Được triển khai bằng Python, Java, Vue theo <a href="https://ccnphfhqs21z.feishu.cn/wiki/M0XiwldO9iJwHikpXD5cEx71nKh">giao thức truyền thông Xiaozhi</a><br/>
+Hỗ trợ giao thức MQTT+UDP, giao thức Websocket, điểm truy cập MCP, nhận dạng giọng nói và kho tri thức
+</p>
+
+<p align="center">
+<a href="./docs/FAQ.md">Câu hỏi thường gặp</a>
+· <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/issues">Báo cáo vấn đề</a>
+· <a href="./README.md#%E9%83%A8%E7%BD%B2%E6%96%87%E6%A1%A3">Tài liệu triển khai</a>
+· <a href="https://github.com/xinnan-tech/xiaozhi-esp32-server/releases">Nhật ký cập nhật</a>
+</p>
+
+<p align="center">
+  <a href="./README.md"><img alt="简体中文版自述文件" src="https://img.shields.io/badge/简体中文-DFE0E5"></a>
+  <a href="./README_en.md"><img alt="README in English" src="https://img.shields.io/badge/English-DFE0E5"></a>
+  <a href="./README_vi.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/Tiếng Việt-DBEDFA"></a>
+  <a href="./README_de.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-DFE0E5"></a>
+  <a href="./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/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">
+    <img alt="stars" src="https://img.shields.io/github/stars/xinnan-tech/xiaozhi-esp32-server?color=ffcb47&labelColor=black" />
+  </a>
+</p>
+
+<p align="center">
+Spearheaded by Professor Siyuan Liu's Team (South China University of Technology)
+</br>
+Được dẫn dắt bởi nhóm Giáo sư Lưu Tư Nguyên (Đại học Bách khoa Nam Trung Quốc)
+</br>
+<img src="./docs/images/hnlg.jpg" alt="华南理工大学" width="50%">
+</p>
+
+---
+
+## Người dùng phù hợp 👥
+
+Dự án này cần được sử dụng cùng với thiết bị phần cứng ESP32. Nếu bạn đã mua phần cứng liên quan đến ESP32, đã thành công kết nối với dịch vụ backend do anh Xia triển khai, và muốn xây dựng dịch vụ backend `xiaozhi-esp32` riêng của mình, thì dự án này rất phù hợp với bạn.
+
+Muốn xem hiệu quả sử dụng? Hãy xem video 🎥
+
+<table>
+  <tr>
+    <td>
+        <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
+         <picture>
+           <img alt="响应速度感受" src="docs/images/demo9.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+        <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/BV1C1tCzUEZh" target="_blank">
+         <picture>
+           <img alt="复杂医疗场景" src="docs/images/demo1.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>
+  </tr>
+  <tr>
+    <td>
+        <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/BV1ZQKUzYExM" target="_blank">
+         <picture>
+           <img alt="MCP接入点" src="docs/images/demo13.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1TJ7WzzEo6" target="_blank">
+         <picture>
+           <img alt="多指令任务" src="docs/images/demo11.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+        <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
+         <picture>
+           <img alt="播放音乐" src="docs/images/demo7.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+        <a href="https://www.bilibili.com/video/BV1Z8XuYZEAS" target="_blank">
+         <picture>
+           <img alt="天气插件" src="docs/images/demo8.png" />
+         </picture>
+        </a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <a href="https://www.bilibili.com/video/BV12J7WzBEaH" target="_blank">
+         <picture>
+           <img alt="实时打断" src="docs/images/demo10.png" />
+         </picture>
+        </a>
+    </td>
+    <td>
+      <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/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>
+    <td>
+        <a href="https://www.bilibili.com/video/BV17LXWYvENb" target="_blank">
+         <picture>
+           <img alt="播报新闻" src="docs/images/demo0.png" />
+         </picture>
+        </a>
+    </td>
+  </tr>
+</table>
+
+---
+
+## Cảnh báo ⚠️
+
+1. Dự án này là phần mềm mã nguồn mở, phần mềm này không có quan hệ hợp tác thương mại với bất kỳ nhà cung cấp dịch vụ API bên thứ ba nào (bao gồm nhưng không giới hạn ở các nền tảng nhận dạng giọng nói, mô hình lớn, tổng hợp giọng nói, v.v.), và không đảm bảo chất lượng dịch vụ cũng như an toàn tài chính của họ.
+Khuyến nghị người dùng ưu tiên lựa chọn nhà cung cấp dịch vụ có giấy phép kinh doanh liên quan và đọc kỹ thỏa thuận dịch vụ và chính sách bảo mật của họ. Phần mềm này không lưu trữ bất kỳ khóa tài khoản nào, không tham gia vào luồng tiền và không chịu rủi ro mất tiền nạp.
+
+2. Chức năng của dự án này chưa hoàn thiện và chưa qua đánh giá bảo mật mạng, vui lòng không sử dụng trong môi trường sản xuất. Nếu bạn triển khai dự án này trong môi trường mạng công cộng để học tập, vui lòng thực hiện các biện pháp bảo vệ cần thiết.
+
+---
+
+## Tài liệu triển khai
+
+![Banners](docs/images/banner2.png)
+
+Dự án này cung cấp hai phương pháp triển khai, vui lòng chọn theo nhu cầu cụ thể của bạn:
+
+#### 🚀 Lựa chọn phương pháp triển khai
+| Phương pháp triển khai | Đặc điểm | Tình huống áp dụng | Tài liệu triển khai | Yêu cầu cấu hình | Video hướng dẫn |
+|---------|------|---------|---------|---------|---------|
+| **Cài đặt tối giản** | Đối thoại thông minh, quản lý đơn tác nhân | Môi trường cấu hình thấp, dữ liệu lưu trong tệp cấu hình, không cần cơ sở dữ liệu | [①Phiên bản Docker](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E5%8F%AA%E8%BF%90%E8%A1%8Cserver) / [②Triển khai mã nguồn](./docs/Deployment.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E5%8F%AA%E8%BF%90%E8%A1%8Cserver)| 2 nhân 4GB nếu dùng `FunASR`, 2 nhân 2GB nếu toàn API | - |
+| **Cài đặt toàn bộ module** | Đối thoại thông minh, quản lý đa người dùng, quản lý đa tác nhân, bảng điều khiển thông minh | Trải nghiệm đầy đủ tính năng, dữ liệu lưu trong cơ sở dữ liệu |[①Phiên bản Docker](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%B8%80docker%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [②Triển khai mã nguồn](./docs/Deployment_all.md#%E6%96%B9%E5%BC%8F%E4%BA%8C%E6%9C%AC%E5%9C%B0%E6%BA%90%E7%A0%81%E8%BF%90%E8%A1%8C%E5%85%A8%E6%A8%A1%E5%9D%97) / [③Hướng dẫn tự động cập nhật triển khai mã nguồn](./docs/dev-ops-integration.md) | 4 nhân 8GB nếu dùng `FunASR`, 2 nhân 4GB nếu toàn API| [Video hướng dẫn khởi động mã nguồn cục bộ](https://www.bilibili.com/video/BV1wBJhz4Ewe) |
+
+Câu hỏi thường gặp và hướng dẫn liên quan, vui lòng tham khảo [liên kết này](./docs/FAQ.md)
+
+> 💡 Gợi ý: Dưới đây là nền tảng thử nghiệm được triển khai theo mã mới nhất, có thể flash để thử nghiệm nếu cần, đồng thời là 6, dữ liệu sẽ được xóa mỗi ngày,
+
+```
+Địa chỉ bảng điều khiển thông minh: https://2662r3426b.vicp.fun
+Bảng điều khiển thông minh (phiên bản h5): https://2662r3426b.vicp.fun/h5/index.html
+
+Công cụ kiểm tra dịch vụ: https://2662r3426b.vicp.fun/test/
+Địa chỉ giao diện OTA: https://2662r3426b.vicp.fun/xiaozhi/ota/
+Địa chỉ giao diện Websocket: wss://2662r3426b.vicp.fun/xiaozhi/v1/
+```
+
+#### 🚩 Mô tả và khuyến nghị cấu hình
+> [!Note]
+> Dự án này cung cấp hai phương án cấu hình:
+>
+> 1. Cấu hình `Miễn phí hoàn toàn cho người mới`: Phù hợp với sử dụng gia đình cá nhân, tất cả các thành phần đều sử dụng phương án miễn phí, không cần thanh toán thêm.
+>
+> 2. `Cấu hình streaming`: Phù hợp với demo, đào tạo, hơn 2 đồng thời, v.v., sử dụng công nghệ xử lý streaming, tốc độ phản hồi nhanh hơn, trải nghiệm tốt hơn.
+>
+> Từ phiên bản `0.5.2`, dự án hỗ trợ cấu hình streaming, so với phiên bản đầu, tốc độ phản hồi cải thiện khoảng `2.5 giây`, cải thiện đáng kể trải nghiệm người dùng.
+
+| Tên module | Cài đặt miễn phí cho người mới | Cấu hình streaming |
+|:---:|:---:|:---:|
+| ASR(Nhận dạng giọng nói) | FunASR(Local) | 👍XunfeiStreamASR(Xunfei Streaming) |
+| LLM(Mô hình lớn) | glm-4-flash(Zhipu) | 👍qwen-flash(Alibaba Bailian) |
+| VLLM(Mô hình lớn thị giác) | glm-4v-flash(Zhipu) | 👍qwen2.5-vl-3b-instructh(Alibaba Bailian) |
+| TTS(Tổng hợp giọng nói) | ✅LinkeraiTTS(Lingxi streaming) | 👍HuoshanDoubleStreamTTS(Volcano Streaming) |
+| Intent(Nhận dạng ý định) | function_call(Gọi hàm) | function_call(Gọi hàm) |
+| Memory(Chức năng bộ nhớ) | mem_local_short(Bộ nhớ ngắn hạn cục bộ) | mem_local_short(Bộ nhớ ngắn hạn cục bộ) |
+
+Nếu bạn quan tâm đến thời gian của từng thành phần, vui lòng xem [Báo cáo kiểm tra hiệu suất các thành phần Xiaozhi](https://github.com/xinnan-tech/xiaozhi-performance-research), có thể kiểm tra thực tế trong môi trường của bạn theo phương pháp kiểm tra trong báo cáo.
+
+#### 🔧 Công cụ kiểm tra
+Dự án này cung cấp các công cụ kiểm tra sau để giúp bạn xác minh hệ thống và chọn mô hình phù hợp:
+
+| Tên công cụ | Vị trí | Phương pháp sử dụng | Mô tả chức năng |
+|:---:|:---|:---:|:---:|
+| Công cụ kiểm tra tương tác âm thanh | main》xiaozhi-server》test》test_page.html | Mở trực tiếp bằng trình duyệt Google Chrome | Kiểm tra chức năng phát và nhận âm thanh, xác minh xử lý âm thanh phía Python có bình thường không |
+| Công cụ kiểm tra phản hồi mô hình | main》xiaozhi-server》performance_tester.py | Thực hiện `python performance_tester.py` | Kiểm tra tốc độ phản hồi của ba module cốt lõi ASR(Nhận dạng giọng nói), LLM(Mô hình lớn), VLLM(Mô hình thị giác), TTS(Tổng hợp giọng nói) |
+
+> 💡 Gợi ý: Khi kiểm tra tốc độ mô hình, chỉ kiểm tra các mô hình đã cấu hình khóa.
+
+---
+## Danh sách tính năng ✨
+### Đã thực hiện ✅
+![请参考-全模块安装架构图](docs/images/deploy2.png)
+| Module chức năng | Mô tả |
+|:---:|:---|
+| Kiến trúc cốt lõi | Dựa trên [cổng MQTT+UDP](https://github.com/xinnan-tech/xiaozhi-esp32-server/blob/main/docs/mqtt-gateway-integration.md), WebSocket, máy chủ HTTP, cung cấp hệ thống quản lý bảng điều khiển và xác thực hoàn chỉnh |
+| Tương tác giọng nói | Hỗ trợ ASR streaming(Nhận dạng giọng nói), TTS streaming(Tổng hợp giọng nói), VAD(Phát hiện hoạt động giọng nói), hỗ trợ nhận dạng đa ngôn ngữ và xử lý giọng nói |
+| Nhận dạng vân giọng | Hỗ trợ đăng ký, quản lý và nhận dạng vân giọng đa người dùng, xử lý song song với ASR, nhận dạng danh tính người nói theo thời gian thực và truyền cho LLM để phản hồi cá nhân hóa |
+| Đối thoại thông minh | Hỗ trợ nhiều LLM(Mô hình ngôn ngữ lớn), thực hiện đối thoại thông minh |
+| Cảm nhận thị giác | Hỗ trợ nhiều VLLM(Mô hình lớn thị giác), thực hiện tương tác đa phương thức |
+| Nhận dạng ý định | Hỗ trợ nhận dạng ý định mô hình lớn gắn ngoài, gọi hàm tự chủ mô hình lớn, cung cấp cơ chế xử lý ý định dạng plugin |
+| Hệ thống bộ nhớ | Hỗ trợ bộ nhớ ngắn hạn cục bộ, bộ nhớ giao diện mem0ai, bộ nhớ thông minh PowerMem, có chức năng tóm tắt bộ nhớ |
+| Kho tri thức | Hỗ trợ kho tri thức RAGFlow, cho phép mô hình lớn đánh giá cần gọi kho tri thức trước khi trả lời |
+| Gọi công cụ | Hỗ trợ giao thức IOT phía client, giao thức MCP phía client, giao thức MCP phía server, giao thức điểm truy cập MCP, hàm công cụ tùy chỉnh |
+| Gửi lệnh | Dựa vào giao thức MQTT, hỗ trợ gửi lệnh MCP từ bảng điều khiển thông minh xuống thiết bị ESP32 |
+| Backend quản lý | Cung cấp giao diện quản lý Web, hỗ trợ quản lý người dùng, cấu hình hệ thống và quản lý thiết bị; giao diện hỗ trợ hiển thị tiếng Trung giản thể, tiếng Trung phồn thể, tiếng Anh |
+| Công cụ kiểm tra | Cung cấp công cụ kiểm tra hiệu suất, công cụ kiểm tra mô hình thị giác và công cụ kiểm tra tương tác âm thanh |
+| Hỗ trợ triển khai | Hỗ trợ triển khai Docker và triển khai cục bộ, cung cấp quản lý tệp cấu hình hoàn chỉnh |
+| Hệ thống plugin | Hỗ trợ mở rộng plugin chức năng, phát triển plugin tùy chỉnh và hot loading plugin |
+
+### Đang phát triển 🚧
+
+Muốn hiểu tiến độ kế hoạch phát triển cụ thể, [vui lòng nhấp vào đây](https://github.com/users/xinnan-tech/projects/3). Câu hỏi thường gặp và hướng dẫn liên quan, vui lòng tham khảo [liên kết này](./docs/FAQ.md)
+
+Nếu bạn là một nhà phát triển phần mềm, đây có một [Lá thư mở gửi các nhà phát triển](docs/contributor_open_letter.md), chào mừng tham gia!
+
+---
+
+## Hệ sinh thái sản phẩm 👬
+Xiaozhi là một hệ sinh thái, khi bạn sử dụng sản phẩm này, bạn cũng có thể xem các [dự án xuất sắc](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) khác trong hệ sinh thái này
+
+---
+
+## Danh sách nền tảng/thành phần được dự án này hỗ trợ 📋
+### LLM Mô hình ngôn ngữ
+
+| Phương pháp sử dụng | Nền tảng hỗ trợ | Nền tảng miễn phí |
+|:---:|:---:|:---:|
+| Gọi giao diện openai | Alibaba Bailian, Volcano Engine, DeepSeek, Zhipu, Gemini, iFlytek | Zhipu, Gemini |
+| Gọi giao diện ollama | Ollama | - |
+| Gọi giao diện dify | Dify | - |
+| Gọi giao diện fastgpt | Fastgpt | - |
+| Gọi giao diện coze | Coze | - |
+| Gọi giao diện xinference | Xinference | - |
+| Gọi giao diện homeassistant | HomeAssistant | - |
+
+Trên thực tế, bất kỳ LLM nào hỗ trợ gọi giao diện openai đều có thể truy cập sử dụng.
+
+---
+
+### VLLM Mô hình thị giác
+
+| Phương pháp sử dụng | Nền tảng hỗ trợ | Nền tảng miễn phí |
+|:---:|:---:|:---:|
+| Gọi giao diện openai | Alibaba Bailian, Zhipu ChatGLMVLLM | Zhipu ChatGLMVLLM |
+
+Trên thực tế, bất kỳ VLLM nào hỗ trợ gọi giao diện openai đều có thể truy cập sử dụng.
+
+---
+
+### TTS Tổng hợp giọng nói
+
+| Phương pháp sử dụng | Nền tảng hỗ trợ | Nền tảng miễn phí |
+|:---:|:---:|:---:|
+| Gọi giao diện | EdgeTTS, iFlytek, Volcano Engine, Tencent Cloud, Alibaba Cloud và Bailian, CosyVoiceSiliconflow, TTS302AI, CozeCnTTS, GizwitsTTS, ACGNTTS, OpenAITTS, Lingxi streaming TTS, MinimaxTTS | Lingxi streaming TTS, EdgeTTS, CosyVoiceSiliconflow(một phần) |
+| Dịch vụ cục bộ | FishSpeech, GPT_SOVITS_V2, GPT_SOVITS_V3, Index-TTS, PaddleSpeech | Index-TTS, PaddleSpeech, FishSpeech, GPT_SOVITS_V2, GPT_SOVITS_V3 |
+
+---
+
+### VAD Phát hiện hoạt động giọng nói
+
+| Loại  |   Tên nền tảng    | Phương pháp sử dụng | Mô hình thu phí | Ghi chú |
+|:---:|:---------:|:----:|:----:|:--:|
+| VAD | SileroVAD | Sử dụng cục bộ |  Miễn phí  |    |
+
+---
+
+### ASR Nhận dạng giọng nói
+
+| Phương pháp sử dụng | Nền tảng hỗ trợ | Nền tảng miễn phí |
+|:---:|:---:|:---:|
+| Sử dụng cục bộ | FunASR, SherpaASR | FunASR, SherpaASR |
+| Gọi giao diện | FunASRServer, Volcano Engine, iFlytek, Tencent Cloud, Alibaba Cloud, Baidu Cloud, OpenAI ASR | FunASRServer |
+
+---
+
+### Voiceprint Nhận dạng vân giọng
+
+| Phương pháp sử dụng | Nền tảng hỗ trợ | Nền tảng miễn phí |
+|:---:|:---:|:---:|
+| Sử dụng cục bộ | 3D-Speaker | 3D-Speaker |
+
+---
+
+### Memory Lưu trữ bộ nhớ
+
+|   Loại   |      Tên nền tảng       | Phương pháp sử dụng |   Mô hình thu phí    | Ghi chú |
+|:------:|:---------------:|:----:|:---------:|:--:|
+| Memory |     mem0ai      | Gọi giao diện | Hạn mức 1000 lần/tháng |    |
+| Memory |     [powermem](./docs/powermem-integration.md)    | Tóm tắt cục bộ | Phụ thuộc vào LLM và DB |  OceanBase mã nguồn mở, hỗ trợ tìm kiếm thông minh  |
+| Memory | mem_local_short | Tóm tắt cục bộ |    Miễn phí     |    |
+| Memory |     nomem       | Chế độ không có bộ nhớ |    Miễn phí     |    |
+
+---
+
+### Intent Nhận dạng ý định
+
+|   Loại   |     Tên nền tảng      | Phương pháp sử dụng |  Mô hình thu phí   |          Ghi chú           |
+|:------:|:-------------:|:----:|:-------:|:---------------------:|
+| Intent |  intent_llm   | Gọi giao diện | Thu phí theo LLM |    Nhận dạng ý định qua mô hình lớn, tính tổng quát mạnh     |
+| Intent | function_call | Gọi giao diện | Thu phí theo LLM | Hoàn thành ý định qua gọi hàm mô hình lớn, tốc độ nhanh, hiệu quả tốt |
+| Intent |    nointent   | Chế độ không có ý định |    Miễn phí     |    Không thực hiện nhận dạng ý định, trả về trực tiếp kết quả đối thoại     |
+
+---
+
+### Rag Tăng cường truy xuất thông tin
+
+|   Loại   |     Tên nền tảng      | Phương pháp sử dụng |  Mô hình thu phí   |          Ghi chú           |
+|:------:|:-------------:|:----:|:-------:|:---------------------:|
+| Rag |  ragflow   | Gọi giao diện | Thu phí theo token tiêu tốn của phân đoạn, phân từ |    Sử dụng chức năng tăng cường truy xuất của RagFlow, cung cấp phản hồi đối thoại chính xác hơn     |
+
+---
+
+## Lời cảm ơn 🙏
+
+| Logo | Dự án/Công ty | Mô tả |
+|:---:|:---:|:---|
+| <img src="./docs/images/logo_bailing.png" width="160"> | [Robot đối thoại giọng nói Bailing](https://github.com/wwbin2017/bailing) | Dự án này được lấy cảm hứng từ [Robot đối thoại giọng nói Bailing](https://github.com/wwbin2017/bailing) và được triển khai trên cơ sở đó |
+| <img src="./docs/images/logo_tenclass.png" width="160"> | [Shifang Ronghai](https://www.tenclass.com/) | Cảm ơn [Shifang Ronghai](https://www.tenclass.com/) đã xây dựng giao thức truyền thông tiêu chuẩn, phương án tương thích đa thiết bị và mô phạm thực hành tình huống đồng thời cao cho hệ sinh thái Xiaozhi; cung cấp tài liệu hỗ trợ kỹ thuật toàn diện cho dự án này |
+| <img src="./docs/images/logo_xuanfeng.png" width="160"> | [Xuanfeng Technology](https://github.com/Eric0308) | Cảm ơn [Xuanfeng Technology](https://github.com/Eric0308) đã đóng góp khung gọi hàm, giao thức truyền thông MCP và mã triển khai cơ chế gọi dạng plugin, thông qua hệ thống điều phối lệnh tiêu chuẩn hóa và khả năng mở rộng động, đã cải thiện đáng kể hiệu suất tương tác và khả năng mở rộng chức năng của thiết bị front-end(IoT) |
+| <img src="./docs/images/logo_junsen.png" width="160"> | [huangjunsen](https://github.com/huangjunsen0406) | Cảm ơn [huangjunsen](https://github.com/huangjunsen0406) đã đóng góp module `Bảng điều khiển thông minh di động`, thực hiện điều khiển hiệu quả và tương tác thời gian thực trên thiết bị di động đa nền tảng, cải thiện đáng kể sự tiện lợi vận hành và hiệu quả quản lý của hệ thống trong tình huống di động |
+| <img src="./docs/images/logo_huiyuan.png" width="160"> | [Huiyuan Design](http://ui.kwd988.net/) | Cảm ơn [Huiyuan Design](http://ui.kwd988.net/) đã cung cấp giải pháp thị giác chuyên nghiệp cho dự án này, sử dụng kinh nghiệm thực tế thiết kế phục vụ hơn nghìn doanh nghiệp, trao quyền cho trải nghiệm người dùng sản phẩm của dự án này |
+| <img src="./docs/images/logo_qinren.png" width="160"> | [Xi'an Qinren Information Technology](https://www.029app.com/) | Cảm ơn [Xi'an Qinren Information Technology](https://www.029app.com/) đã làm sâu sắc hệ thống thị giác của dự án này, đảm bảo tính nhất quán và khả năng mở rộng của phong cách thiết kế tổng thể trong ứng dụng đa tình huống |
+| <img src="./docs/images/logo_contributors.png" width="160"> | [Người đóng góp mã](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors) | Cảm ơn [tất cả người đóng góp mã](https://github.com/xinnan-tech/xiaozhi-esp32-server/graphs/contributors), sự cống hiến của bạn khiến dự án mạnh mẽ và vững chắc hơn. |
+
+
+<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>

docs/Deployment.md

@@ -80,7 +80,7 @@ xiaozhi-server
 打开命令行工具，使用`终端`或`命令行`工具 进入到你的`xiaozhi-server`，执行以下命令
 
 ```
-docker-compose up -d
+docker compose up -d
 ```
 
 执行完后，再执行以下命令，查看日志信息。
@@ -139,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
 ```
 
 请注意，以上命令，不是一股脑执行就成功的，你需要一步步执行，每一步执行完后，都检查一下输出的日志，查看是否成功。
@@ -267,7 +270,8 @@ LLM:
 6、[我说话很慢，停顿时小智老是抢话](./FAQ.md)<br/>
 ## 部署相关教程
 1、[如何自动拉取本项目最新代码自动编译和启动](./dev-ops-integration.md)<br/>
-2、[如何与Nginx集成](https://github.com/xinnan-tech/xiaozhi-esp32-server/issues/791)<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/>
@@ -275,11 +279,13 @@ LLM:
 4、[如何部署MCP接入点](./mcp-endpoint-enable.md)<br/>
 5、[如何接入MCP接入点](./mcp-endpoint-integration.md)<br/>
 6、[如何开启声纹识别](./voiceprint-integration.md)<br/>
-10、[新闻插件源配置指南](./newsnow_plugin_config.md)<br/>
+7、[新闻插件源配置指南](./newsnow_plugin_config.md)<br/>
+8、[天气插件使用指南](./weather-integration.md)<br/>
 ## 语音克隆、本地语音部署相关教程
-1、[如何部署集成index-tts本地语音](./index-stream-integration.md)<br/>
+1、[如何在智控台克隆音色](./huoshan-streamTTS-voice-cloning.md)<br/>
-2、[如何部署集成fish-speech本地语音](./fish-speech-integration.md)<br/>
+2、[如何部署集成index-tts本地语音](./index-stream-integration.md)<br/>
-3、[如何部署集成PaddleSpeech本地语音](./paddlespeech-deploy.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

@@ -355,6 +355,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
 ```
 
 请注意，以上命令，不是一股脑执行就成功的，你需要一步步执行，每一步执行完后，都检查一下输出的日志，查看是否成功。
@@ -468,7 +471,8 @@ ws://你电脑局域网的ip:8000/xiaozhi/v1/
 6、[我说话很慢，停顿时小智老是抢话](./FAQ.md)<br/>
 ## 部署相关教程
 1、[如何自动拉取本项目最新代码自动编译和启动](./dev-ops-integration.md)<br/>
-2、[如何与Nginx集成](https://github.com/xinnan-tech/xiaozhi-esp32-server/issues/791)<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/>
@@ -479,9 +483,10 @@ ws://你电脑局域网的ip:8000/xiaozhi/v1/
 7、[新闻插件源配置指南](./newsnow_plugin_config.md)<br/>
 8、[天气插件使用指南](./weather-integration.md)<br/>
 ## 语音克隆、本地语音部署相关教程
-1、[如何部署集成index-tts本地语音](./index-stream-integration.md)<br/>
+1、[如何在智控台克隆音色](./huoshan-streamTTS-voice-cloning.md)<br/>
-2、[如何部署集成fish-speech本地语音](./fish-speech-integration.md)<br/>
+2、[如何部署集成index-tts本地语音](./index-stream-integration.md)<br/>
-3、[如何部署集成PaddleSpeech本地语音](./paddlespeech-deploy.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

@@ -38,10 +38,10 @@ conda install conda-forge::ffmpeg
 
 | 模块名称 | 入门全免费设置 | 流式配置 |
 |:---:|:---:|:---:|
-| ASR(语音识别) | FunASR(本地) | 👍FunASR(本地GPU模式) |
+| ASR(语音识别) | FunASR(本地) | 👍XunfeiStreamASR(讯飞流式) |
-| LLM(大模型) | ChatGLMLLM(智谱glm-4-flash) | 👍AliLLM(qwen3-235b-a22b-instruct-2507) 或 👍DoubaoLLM(doubao-1-5-pro-32k-250115) |
+| LLM(大模型) | glm-4-flash(智谱) | 👍qwen-flash(阿里百炼) |
-| VLLM(视觉大模型) | ChatGLMVLLM(智谱glm-4v-flash) | 👍QwenVLVLLM(千问qwen2.5-vl-3b-instructh) |
+| VLLM(视觉大模型) | glm-4v-flash(智谱) | 👍qwen2.5-vl-3b-instructh(阿里百炼) |
-| TTS(语音合成) | ✅LinkeraiTTS(灵犀流式) | 👍HuoshanDoubleStreamTTS(火山双流式语音合成) 或 👍AliyunStreamTTS(阿里云流式语音合成) |
+| TTS(语音合成) | ✅LinkeraiTTS(灵犀流式) | 👍HuoshanDoubleStreamTTS(火山流式) |
 | Intent(意图识别) | function_call(函数调用) | function_call(函数调用) |
 | Memory(记忆功能) | mem_local_short(本地短期记忆） | mem_local_short（本地短期记忆） |
 
@@ -62,30 +62,35 @@ VAD:
 ### 7、部署相关教程
 1、[如何进行最简化部署](./Deployment.md)<br/>
 2、[如何进行全模块部署](./Deployment_all.md)<br/>
-2、[如何部署MQTT网关开启MQTT+UDP协议](./mqtt-gateway-integration.md)<br/>
+3、[如何部署MQTT网关开启MQTT+UDP协议](./mqtt-gateway-integration.md)<br/>
-3、[如何自动拉取本项目最新代码自动编译和启动](./dev-ops-integration.md)<br/>
+4、[如何自动拉取本项目最新代码自动编译和启动](./dev-ops-integration.md)<br/>
-4、[如何与Nginx集成](https://github.com/xinnan-tech/xiaozhi-esp32-server/issues/791)<br/>
+5、[如何与Nginx集成](https://github.com/xinnan-tech/xiaozhi-esp32-server/issues/791)<br/>
 
-### 8、编译固件相关教程
+### 9、编译固件相关教程
 1、[如何自己编译小智固件](./firmware-build.md)<br/>
 2、[如何基于虾哥编译好的固件修改OTA地址](./firmware-setting.md)<br/>
+3、[单模块部署如何配置固件OTA自动升级](./ota-upgrade-guide.md)<br/>
 
-### 8、拓展相关教程
+### 10、拓展相关教程
 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/>
+6、[MCP方法如何获取设备信息](./mcp-get-device-info.md)<br/>
-10、[新闻插件源配置指南](./newsnow_plugin_config.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/>
 
-### 9、语音克隆、本地语音部署相关教程
+### 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/>
 
-### 10、性能测试教程
+### 12、性能测试教程
 1、[各组件速度测试指南](./performance_tester.md)<br/>
 2、[定期公开测试结果](https://github.com/xinnan-tech/xiaozhi-performance-research)<br/>
 

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/docker-build.md

@@ -17,5 +17,5 @@ docker build -t xiaozhi-esp32-server:web_latest -f ./Dockerfile-web .
 # 编译完成后，可以使用docker-compose启动项目
 # docker-compose.yml你需要修改成自己编译的镜像版本
 cd main/xiaozhi-server
-docker-compose up -d
+docker compose up -d
 ```

docs/homeassistant-integration.md

@@ -97,7 +97,7 @@ http://homeassistant.local:8123
 
 使用管理员账号，登录`智控台`。在`智能体管理`，找到你的智能体，再点击`配置角色`。
 
-将意图识别设置成`函数调用`或`LLM意图识别`。这时你会看到右侧有一个`编辑功能`。点击`编辑功能`按钮，会弹出`功能管理`的框。
+将意图识别设置成`外挂的大模型意图识别`或`大模型自主函数调用`。这时你会看到右侧有一个`编辑功能`。点击`编辑功能`按钮，会弹出`功能管理`的框。
 
 在`功能管理`的框里，你需要勾选`HomeAssistant设备状态查询`和`HomeAssistant设备状态修改`。
 

docs/huoshan-streamTTS-voice-cloning.md

@@ -1,6 +1,6 @@
 # 智控台 火山双流式语音合成+音色克隆配置教程
 
-本教程分为3个阶段：准备阶段、配置阶段、克隆阶段、使用阶段。主要是介绍通过智控台配置火山双流式语音合成+音色克隆的过程。
+本教程分为4个阶段：准备阶段、配置阶段、克隆阶段、使用阶段。主要是介绍通过智控台配置火山双流式语音合成+音色克隆的过程。
 
 ## 第一阶段：准备阶段
 超级管理员先预先把火山引擎服务开通好，获取到App Id，Access Token。默认火上引擎会赠送一个音色资源。这个音色资源需要把它复制到本项目里。
@@ -23,6 +23,8 @@
 
 ### 2.将音色资源ID分配给系统账号
 
+使用超级管理员账号登录智控台，点击顶部`参数字典`，在下拉菜单中，点击`系统功能配置`页面。在页面上勾选`音色克隆`，点击保存配置。即可在顶部菜单看到`音色克隆`按钮。
+
 使用超级管理员账号登录智控台，点击顶部【音色克隆】、【音色资源】。
 
 点击新增按钮，在【平台名称】选择“火山双流式语音合成”；
@@ -46,7 +48,7 @@
 
 如果复刻成功，在列表里会看到对应的音色会变成“训练成功”状态。此时你可以点击【声音名称】栏的修改按钮，修改音色资源的名称，方便后期选择使用。
 
-## 第三阶段：使用阶段
+## 第四阶段：使用阶段
 
 点击顶部【智能体管理】，选择任意一个智能体，点击【配置角色】按钮。
 

docs/mcp-endpoint-enable.md

@@ -71,6 +71,7 @@ docker logs -f mcp-endpoint-server
 请你保留好上面两个`接口地址`，下一步要用到。
 
 # 2、全模块部署时，怎么配置MCP接入点
+首先，你要开启MCP接入点功能。在智控台，点击顶部`参数字典`，在下拉菜单中，点击`系统功能配置`页面。在页面上勾选`MCP接入点`，点击`保存配置`。在`角色配置`页面，点击`编辑功能`按钮，即可看到`mcp接入点`功能。
 
 如果你是全模块部署，使用管理员账号，登录智控台，点击顶部`参数字典`，选择`参数管理`功能。
 

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/mqtt-gateway-integration.md

@@ -11,12 +11,12 @@
 
 1、如果你是源码部署，你的`mqtt-websocket`地址是：
 ```
-ws://127.0.0.1:8000/xiaozhi/v1?from=mqtt_gateway
+ws://127.0.0.1:8000/xiaozhi/v1/?from=mqtt_gateway
 ```
 
 2、如果你是docker部署，你的`mqtt-websocket`地址是
 ```
-ws://你宿主机局域网IP:8000/xiaozhi/v1?from=mqtt_gateway
+ws://你宿主机局域网IP:8000/xiaozhi/v1/?from=mqtt_gateway
 ```
 
 ## 重要提示
@@ -53,7 +53,7 @@ cp config/mqtt.json.example config/mqtt.json
 {
     "production": {
         "chat_servers": [
-            "ws://127.0.0.1:8000/xiaozhi/v1?from=mqtt_gateway"
+            "ws://127.0.0.1:8000/xiaozhi/v1/?from=mqtt_gateway"
         ]
     },
     "debug": false,
@@ -76,6 +76,7 @@ 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一致，如果有域名就填域名。
 
@@ -85,6 +86,13 @@ MQTT_SIGNATURE_KEY=test   # MQTT签名密钥
 - 注意不要用简单的密码，比如`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网关
 ```
 # 启动服务
@@ -119,7 +127,7 @@ pm2 restart xz-mqtt
 ```
 192.168.0.7:8884
 ```
-4. 在智控台顶部，点击`参数管理`，搜索`server.mqtt_manager_api`，点击编辑，填入你在`.env`文件中设置的`PUBLIC_IP`+`:`+`UDP_PORT`。类似这样
+4. 在智控台顶部，点击`参数管理`，搜索`server.mqtt_manager_api`，点击编辑，填入你在`.env`文件中设置的`PUBLIC_IP`+`:`+`API_PORT`。类似这样
 ```
 192.168.0.7:8007
 ```
@@ -146,7 +154,7 @@ curl 'http://localhost:8002/xiaozhi/ota/' \
 pm2 logs xz-mqtt
 ```
 
-## 第三部分：全模块运行实现小智硬件MQTT+UDP连接
+## 第三部分：单模块运行xiaozhi-server实现小智硬件MQTT+UDP连接
 
 打开你的`data/.config.yaml`文件，在`server`下找到`mqtt_gateway`填入你在`.env`文件中设置的`PUBLIC_IP`+`:`+`MQTT_PORT`。类似这样
 ```
@@ -176,4 +184,4 @@ curl 'http://localhost:8002/xiaozhi/ota/' \
 唤醒后留意mqtt-gateway的日志，确认是否有连接成功的日志。
 ```
 pm2 logs xz-mqtt
-```
+```

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

@@ -0,0 +1,345 @@
+# PowerMem 记忆组件集成指南
+
+## 简介
+
+[PowerMem](https://www.powermem.ai/) 是由 OceanBase 开源的 Agent 记忆组件，通过本地 LLM 进行记忆总结和智能检索，为 AI 代理提供高效的记忆管理功能。
+
+费用说明：PowerMem 本身开源免费，实际费用取决于您选择的 LLM 和数据库：
+- 使用 SQLite + 免费 LLM（如智谱 glm-4-flash）= **完全免费**
+- 使用云端 LLM 或云端数据库 = 按对应服务收费
+
+> 💡 **最佳性能提示**：PowerMem 配合 OceanBase 使用可实现最大性能释放，SQLite 仅建议在资源不足的情况下使用。
+
+- **GitHub**: https://github.com/oceanbase/powermem
+- **官网**: https://www.powermem.ai/
+- **使用示例**: https://github.com/oceanbase/powermem/tree/main/examples
+
+## 功能特性
+
+- **本地总结**：通过 LLM 在本地进行记忆总结和提取
+- **用户画像**：通过 `UserMemory` 自动提取用户信息（姓名、职业、兴趣等），持续更新用户画像
+- **智能遗忘**：基于艾宾浩斯遗忘曲线，自动"遗忘"过时噪声信息
+- **多种存储后端**：支持 OceanBase（推荐，最佳性能）、SeekDB（推荐，AI应用存储一体）、PostgreSQL、SQLite（轻量备选）
+- **多种 LLM 支持**：通义千问、智谱（glm-4-flash 免费）、OpenAI 等
+- **智能检索**：基于向量搜索的语义检索能力
+- **私有部署**：完全支持本地私有化部署
+- **异步操作**：高效的异步记忆管理
+
+## 安装
+
+PowerMem 已添加到项目依赖中，如果需要手动安装：
+
+```bash
+pip install powermem
+```
+
+## 配置说明
+
+### 基础配置
+
+在 `config.yaml` 中配置 PowerMem：
+
+```yaml
+selected_module:
+  Memory: powermem
+
+Memory:
+  powermem:
+    type: powermem
+    # 是否启用用户画像功能
+    # 用户画像支持: oceanbase、seekdb、sqlite (powermem 0.3.0+)
+    enable_user_profile: true
+    
+    # ========== LLM 配置 ==========
+    llm:
+      provider: openai  # 可选: qwen, openai, zhipu 等
+      config:
+        api_key: 你的LLM API密钥
+        model: qwen-plus
+        # openai_base_url: https://api.openai.com/v1  # 可选，自定义服务地址
+    
+    # ========== Embedding 配置 ==========
+    embedder:
+      provider: openai  # 可选: qwen, openai 等
+      config:
+        api_key: 你的嵌入模型API密钥
+        model: text-embedding-v4
+        openai_base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
+        # embedding_dims: 1024  # 向量维度，非1536时需配置
+    
+    # ========== Database 配置 ==========
+    vector_store:
+      provider: sqlite  # 可选: oceanbase(推荐), seekdb(推荐), postgres, sqlite(轻量)
+      config: {}  # SQLite 无需额外配置
+```
+
+### 配置参数详解
+
+#### LLM 配置
+
+| 参数 | 说明 | 可选值 |
+|------|------|--------|
+| `llm.provider` | LLM 提供商 | `qwen`, `openai`, `zhipu` 等 |
+| `llm.config.api_key` | API 密钥 | - |
+| `llm.config.model` | 模型名称 | 根据提供商选择 |
+| `llm.config.openai_base_url` | 自定义服务地址（可选） | - |
+
+#### Embedding 配置
+
+| 参数 | 说明 | 可选值 |
+|------|------|--------|
+| `embedder.provider` | 嵌入模型提供商 | `qwen`, `openai` 等 |
+| `embedder.config.api_key` | API 密钥 | - |
+| `embedder.config.model` | 模型名称 | 根据提供商选择 |
+| `embedder.config.openai_base_url` | 自定义服务地址（可选） | - |
+
+#### Database 配置
+
+| 参数 | 说明 | 可选值 |
+|------|------|--------|
+| `vector_store.provider` | 存储后端类型 | `oceanbase`(推荐), `seekdb`(推荐), `postgres`, `sqlite`(轻量) |
+| `vector_store.config` | 数据库连接配置 | 根据 provider 设置 |
+
+### 记忆模式说明
+
+PowerMem 支持两种记忆模式：
+
+| 模式 | 配置 | 功能 | 存储要求 |
+|------|------|------|----------|
+| **普通记忆** | `enable_user_profile: false` | 对话记忆存储与检索 | 支持所有数据库 |
+| **用户画像** | `enable_user_profile: true` | 记忆 + 自动提取用户画像 | oceanbase、seekdb、sqlite |
+
+> 📌 **版本说明**：PowerMem 0.3.0+ 版本，用户画像功能支持 OceanBase、SeekDB、SQLite 三种存储后端。
+
+### 使用通义千问（推荐）
+
+1. 访问 [阿里云百炼平台](https://bailian.console.aliyun.com/) 注册账号
+2. 在 [API Key 管理](https://bailian.console.aliyun.com/?apiKey=1#/api-key) 页面获取 API 密钥
+3. 配置如下：
+
+```yaml
+Memory:
+  powermem:
+    type: powermem
+    enable_user_profile: true
+    llm:
+      provider: qwen
+      config:
+        api_key: sk-xxxxxxxxxxxxxxxx
+        model: qwen-plus
+    embedder:
+      provider: openai
+      config:
+        api_key: sk-xxxxxxxxxxxxxxxx
+        model: text-embedding-v4
+        openai_base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
+    vector_store:
+      provider: sqlite
+      config: {}
+```
+
+### 使用智谱免费 LLM（完全免费方案）
+
+智谱提供免费的 glm-4-flash 模型，配合 SQLite 可实现完全免费使用：
+
+1. 访问 [智谱AI开放平台](https://bigmodel.cn/) 注册账号
+2. 在 [API Keys](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) 页面获取 API 密钥
+3. 配置如下：
+
+```yaml
+Memory:
+  powermem:
+    type: powermem
+    enable_user_profile: true
+    llm:
+      provider: openai  # 使用 openai 兼容模式
+      config:
+        api_key: xxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxx
+        model: glm-4-flash
+        openai_base_url: https://open.bigmodel.cn/api/paas/v4/
+    embedder:
+      provider: openai
+      config:
+        api_key: xxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxx
+        model: embedding-3
+        openai_base_url: https://open.bigmodel.cn/api/paas/v4/
+    vector_store:
+      provider: sqlite
+      config: {}
+```
+
+### 使用 OpenAI
+
+```yaml
+Memory:
+  powermem:
+    type: powermem
+    enable_user_profile: true
+    llm:
+      provider: openai
+      config:
+        api_key: sk-xxxxxxxxxxxxxxxx
+        model: gpt-4o-mini
+        openai_base_url: https://api.openai.com/v1
+    embedder:
+      provider: openai
+      config:
+        api_key: sk-xxxxxxxxxxxxxxxx
+        model: text-embedding-3-small
+        openai_base_url: https://api.openai.com/v1
+    vector_store:
+      provider: sqlite
+      config: {}
+```
+
+### 使用 OceanBase（最佳性能方案）
+
+OceanBase 是 PowerMem 的最佳搭档，可实现最大性能释放：
+
+1. 部署 OceanBase 数据库（支持开源本地部署或使用云服务）
+   - 开源部署：https://github.com/oceanbase/oceanbase
+   - 云服务：https://www.oceanbase.com/
+2. 配置如下：
+
+```yaml
+Memory:
+  powermem:
+    type: powermem
+    enable_user_profile: true
+    llm:
+      provider: qwen
+      config:
+        api_key: sk-xxxxxxxxxxxxxxxx
+        model: qwen-plus
+    embedder:
+      provider: openai
+      config:
+        api_key: sk-xxxxxxxxxxxxxxxx
+        model: text-embedding-v4
+        openai_base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
+    vector_store:
+      provider: oceanbase
+      config:
+        host: 127.0.0.1
+        port: 2881
+        user: root@test
+        password: your_password
+        db_name: powermem
+        collection_name: memories  # 默认值
+        embedding_model_dims: 1536  # 嵌入向量维度，必需参数
+```
+
+## 设备记忆隔离
+
+PowerMem 会自动使用设备 ID（`device_id`）作为 `user_id` 进行记忆隔离。这意味着：
+
+- 每个设备拥有独立的记忆空间
+- 不同设备之间的记忆完全隔离
+- 同一设备的多次对话可以共享记忆上下文
+
+## 用户画像（UserMemory）
+
+PowerMem 提供 `UserMemory` 类，可自动从对话中提取用户画像信息。
+
+> 📌 **版本说明**：PowerMem 0.3.0+ 版本，用户画像功能支持 OceanBase、SeekDB、SQLite 三种存储后端。
+
+### 启用用户画像
+
+在配置中设置 `enable_user_profile: true` 即可启用：
+
+```yaml
+Memory:
+  powermem:
+    type: powermem
+    enable_user_profile: true  # 启用用户画像
+    llm:
+      provider: qwen
+      config:
+        api_key: sk-xxxxxxxxxxxxxxxx
+        model: qwen-plus
+    embedder:
+      provider: openai
+      config:
+        api_key: sk-xxxxxxxxxxxxxxxx
+        model: text-embedding-v4
+        openai_base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
+    vector_store:
+      provider: sqlite  # 用户画像支持: oceanbase、seekdb、sqlite
+      config: {}
+```
+
+### 用户画像能力
+
+| 能力 | 说明 |
+|------|------|
+| **信息提取** | 自动从对话中提取姓名、年龄、职业、兴趣等 |
+| **持续更新** | 随着对话进行，不断完善用户画像 |
+| **画像检索** | 将用户画像与记忆搜索结合，提升检索相关性 |
+| **智能遗忘** | 基于艾宾浩斯遗忘曲线，淡化过时信息 |
+
+### 工作原理
+
+启用用户画像后，小智在查询记忆时会自动返回：
+1. **用户画像**：用户的基本信息、兴趣爱好等
+2. **相关记忆**：与当前对话相关的历史记忆
+
+> ✅ **版本说明**：PowerMem 0.3.0+ 版本，用户画像功能支持 OceanBase、SeekDB、SQLite 三种存储后端。
+
+## 与其他记忆组件的对比
+
+| 特性 | PowerMem | mem0ai | mem_local_short |
+|------|----------|--------|-----------------|
+| 工作方式 | 本地总结 | 云端接口 | 本地总结 |
+| 存储位置 | 本地/云端DB | 云端 | 本地YAML |
+| 费用 | 取决于LLM和DB | 1000次/月免费 | 完全免费 |
+| 智能检索 | ✅ 向量搜索 | ✅ 向量搜索 | ❌ 全量返回 |
+| 用户画像 | ✅ UserMemory | ❌ | ❌ |
+| 智能遗忘 | ✅ 遗忘曲线 | ❌ | ❌ |
+| 私有部署 | ✅ 支持 | ❌ 仅云端 | ✅ 支持 |
+| 数据库支持 | OceanBase(推荐)/SeekDB/PostgreSQL/SQLite | - | YAML 文件 |
+
+## 常见问题
+
+### 1. API 密钥错误
+
+如果出现 `API key is required` 错误，请检查：
+- `llm_api_key` 和 `embedding_api_key` 是否正确填写
+- API 密钥是否有效
+
+### 2. 模型不存在
+
+如果出现模型不存在的错误，请确认：
+- `llm_model` 和 `embedding_model` 名称是否正确
+- 对应的模型服务是否已开通
+
+### 3. 连接超时
+
+如果出现连接超时，可以尝试：
+- 检查网络连接
+- 如果使用代理，配置 `llm_base_url` 和 `embedding_base_url`
+
+## 测试验证
+
+可以在虚拟环境中测试 PowerMem 是否正常工作：
+
+```bash
+# 激活虚拟环境
+source .venv/bin/activate
+
+# 测试 PowerMem 导入
+python -c "from powermem import AsyncMemory; print('PowerMem 导入成功')"
+
+# 测试 UserMemory 导入（用户画像功能）
+python -c "from powermem import UserMemory; print('UserMemory 导入成功')"
+```
+
+## 更多资源
+
+- [PowerMem 官方文档](https://www.powermem.ai/)
+- [PowerMem GitHub 仓库](https://github.com/oceanbase/powermem)
+- [PowerMem 使用示例](https://github.com/oceanbase/powermem/tree/main/examples)
+- [OceanBase 官网](https://www.oceanbase.com/)
+- [OceanBase GitHub](https://github.com/oceanbase/oceanbase)
+- [SeekDB GitHub](https://github.com/oceanbase/seekdb)（AI原生搜索数据库）
+- [阿里云百炼平台](https://bailian.console.aliyun.com/)
+

docs/ragflow-integration.md

@@ -0,0 +1,269 @@
+# ragflow 集成指南
+
+本教程主要是是两部分
+
+- 一、如何部署ragflow
+- 二、如何在智控台配置ragflow接口
+
+如果您对ragflow很熟悉，且已经部署了ragflow，可直接跳过第一部分，直接进入第二部分。但是如果你希望有人指导你部署ragflow，让它能够和`xiaozhi-esp32-server`共同使用`mysql`、`redis`基础服务，以减少资源成本，你需要从第一部分开始。
+
+# 第一部分 如何部署ragflow
+## 第一步， 确认mysql、redis是否可用
+
+ragflow需要依赖`mysql`数据库。如果你之前已经部署`智控台`，说明你已经安装了`mysql`。你可以共用它。
+
+你可以你试一下在宿主机使用`telnet`命令，看看能不能正常访问`mysql`的`3306`端口。
+``` shell
+telnet 127.0.0.1 3306
+
+telnet 127.0.0.1 6379
+```
+如果能访问到`3306`端口和`6379`端口，请忽略以下的内容，直接进入第二步。
+
+如果不能访问，你需要回忆一下，你的`mysql`是怎么安装的。
+
+如果你的mysql是通过自己使用安装包安装的，说明你的`mysql`做了网络隔离。你可能先解决访问`mysql`的`3306`端口这个问题。
+
+如果你`mysql`是通过本项目的`docker-compose_all.yml`安装的。你需要找一下你当时创建数据库的`docker-compose_all.yml`文件，修改以下的内容
+
+修改前
+``` yaml
+  xiaozhi-esp32-server-db:
+    ...
+    networks:
+      - default
+    expose:
+      - "3306:3306"
+  xiaozhi-esp32-server-redis:
+    ...
+    expose:
+      - 6379
+```
+
+修改后
+``` yaml
+  xiaozhi-esp32-server-db:
+    ...
+    networks:
+      - default
+    ports:
+      - "3306:3306"
+  xiaozhi-esp32-server-redis:
+    ...
+    ports:
+      - "6379:6379"
+```
+
+注意是将`xiaozhi-esp32-server-db`和`xiaozhi-esp32-server-redis`下面的`expose`改成`ports`。改完后，需要重新启动。以下是重启mysql的命令：
+
+``` shell
+# 进入你docker-compose_all.yml所在的文件夹，例如我的是xiaozhi-server
+cd xiaozhi-server
+docker compose -f docker-compose_all.yml down
+docker compose -f docker-compose.yml up -d
+```
+
+启动完后，在宿主机再使用`telnet`命令，看看能不能正常访问`mysql`的`3306`端口。
+``` shell
+telnet 127.0.0.1 3306
+
+telnet 127.0.0.1 6379
+```
+正常来说这样就可以访问的了。
+
+## 第二步， 创建数据库和表
+如果你的宿主机，能正常访问mysql数据库，那就在mysql上创建一个名字为`rag_flow`的数据库和`rag_flow`用户，密码为`infini_rag_flow`。
+
+``` sql
+-- 创建数据库
+CREATE DATABASE IF NOT EXISTS rag_flow CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
+-- 创建用户并授权
+CREATE USER IF NOT EXISTS 'rag_flow'@'%' IDENTIFIED BY 'infini_rag_flow';
+GRANT ALL PRIVILEGES ON rag_flow.* TO 'rag_flow'@'%';
+
+-- 刷新权限
+FLUSH PRIVILEGES;
+```
+
+## 第三步， 下载ragflow项目
+
+你需要在你电脑找一个文件夹，用来存放ragflow项目。例如我在`/home/system/xiaozhi`文件夹。
+
+你可以使用`git`命令，将ragflow项目下载到这个文件夹，本教程使用的是`v0.22.0`版本进行安装部署。
+```
+git clone https://ghfast.top/https://github.com/infiniflow/ragflow.git
+cd ragflow
+git checkout v0.22.0
+```
+下载完后，进入`docker`文件夹。
+``` shell
+cd docker
+```
+修改`ragflow/docker`文件夹下的`docker-compose.yml`文件，将`ragflow-cpu`和`ragflow-gpu`服务的`depends_on`配置去掉，用于解除`ragflow-cpu`服务对`mysql`的依赖。
+
+这是修改前：
+``` yaml
+  ragflow-cpu:
+    depends_on:
+      mysql:
+        condition: service_healthy
+    profiles:
+      - cpu
+  ...
+  ragflow-gpu:
+    depends_on:
+      mysql:
+        condition: service_healthy
+    profiles:
+      - gpu
+```
+这是修改后：
+``` yaml
+  ragflow-cpu:
+    profiles:
+      - cpu
+  ...
+  ragflow-gpu:
+    profiles:
+      - gpu
+```
+
+接着，修改`ragflow/docker`文件夹下的`docker-compose-base.yml`文件，去掉`mysql`和`redis`的配置。
+
+例如，删除前：
+``` yaml
+services:
+  minio:
+    image: quay.io/minio/minio:RELEASE.2025-06-13T11-33-47Z
+    ...
+  mysql:
+    image: mysql:8.0
+    ...
+  redis:
+    image: redis:6.2-alpine
+    ...
+```
+
+删除后
+``` yaml
+services:
+  minio:
+    image: quay.io/minio/minio:RELEASE.2025-06-13T11-33-47Z
+    ...
+```
+## 第四步，修改环境变量配置
+
+编辑`ragflow/docker`文件夹下的`.env`文件,找到以下配置，逐个搜索，逐个修改！逐个搜索，逐个修改！
+
+下面对于`.env`文件的修改，60%的人会忽略`MYSQL_USER`配置导致ragflow启动不成功，因此，需要强调三次：
+
+强调第一次：如果你的`.env`文件如果没有`MYSQL_USER`配置，请在配置文件增加这项！
+
+强调第二次：如果你的`.env`文件如果没有`MYSQL_USER`配置，请在配置文件增加这项！
+
+强调第三次：如果你的`.env`文件如果没有`MYSQL_USER`配置，请在配置文件增加这项！
+
+``` env
+# 端口设置
+SVR_WEB_HTTP_PORT=8008           # HTTP端口
+SVR_WEB_HTTPS_PORT=8009          # HTTPS端口
+# MySQL配置 - 修改为您本地MySQL的信息
+MYSQL_HOST=host.docker.internal  # 使用host.docker.internal让容器访问主机服务
+MYSQL_PORT=3306                  # 本地MySQL端口
+MYSQL_USER=rag_flow              # 上面创建的用户名，如果没有这项就增加这一项
+MYSQL_PASSWORD=infini_rag_flow   # 上面设置的密码
+MYSQL_DBNAME=rag_flow            # 数据库名称
+
+# Redis配置 - 修改为您本地Redis的信息
+REDIS_HOST=host.docker.internal  # 使用host.docker.internal让容器访问主机服务
+REDIS_PORT=6379                  # 本地Redis端口
+REDIS_PASSWORD=                  # 如果你的Redis没有设置密码，就按这样子填写，否则填写密码
+```
+
+注意，如果你的Redis没有设置密码，还要修改`ragflow/docker`文件夹下`service_conf.yaml.template`，将`infini_rag_flow`替换成空字符串。
+
+修改前
+``` shell
+redis:
+  db: 1
+  password: '${REDIS_PASSWORD:-infini_rag_flow}'
+  host: '${REDIS_HOST:-redis}:6379'
+```
+修改后
+``` shell
+redis:
+  db: 1
+  password: '${REDIS_PASSWORD:-}'
+  host: '${REDIS_HOST:-redis}:6379'
+```
+
+## 第五步，启动ragflow服务
+执行命令：
+``` shell
+docker-compose -f docker-compose.yml up -d
+```
+执行成功后，你可以使用`docker logs -n 20 -f docker-ragflow-cpu-1`命令，查看`docker-ragflow-cpu-1`服务的日志。
+
+如果日志中没有报错，说明ragflow服务启动成功。
+
+# 第五步，注册账号
+你可以在浏览器中访问`http://127.0.0.1:8008`，点击`Sign Up`，注册一个账号。
+
+注册成功后，你可以点击`Sign In`，登录到ragflow服务。如果你想关闭ragflow服务的注册服务，不想让其他人注册账号，你可以在`ragflow/docker`文件夹下的`.env`文件中，将`REGISTER_ENABLED`配置项设置为`0`。
+
+``` dotenv
+REGISTER_ENABLED=0
+```
+修改后，重启启动ragflow服务。
+``` shell
+docker-compose -f docker-compose.yml down
+docker-compose -f docker-compose.yml up -d
+```
+
+# 第六步，配置ragflow服务的模型
+你可以在浏览器中访问`http://127.0.0.1:8008`，点击`Sign In`，登录到ragflow服务。点击页面右上角的`头像`，进入设置页面。
+首先，在左侧导航栏中，点击`模型供应商`，进入到模型配置页面。在右侧的`可选模型`搜索框下，选择`LLM`，在列表选择你使用的模型供应商，点击`添加`，输入你的密钥；
+然后，选择`TEXT EMBEDDING`，在列表选择你使用的模型供应商，点击`添加`，输入你的密钥。
+最后，刷新一下页面，分别点击`设置默认模型`列表的LLM和Embedding，选择你使用的模型即可。请确认你的密钥开通了相应的服务，比如我是用的Embedding模型是xxx供应商的，需要去这个供应商官网查看这个模型是否需要购买资源包才能使用。
+
+
+# 第二部分 配置ragflow服务
+
+# 第一步 登录ragflow服务
+你可以在浏览器中访问`http://127.0.0.1:8008`，点击`Sign In`，登录到ragflow服务。
+
+然后点击右上角的`头像`，进入设置页面。在左侧导航栏中，点击`API`功能，然后点击"API Key"按钮。出现一个弹框，
+
+在弹框中，点击"Create new Key"按钮，生成一个API Key。复制这个`API Key`，你稍后会用到。
+
+# 第二步 配置到智控台
+确保你的智控台版本是`0.8.7`或以上。使用超级管理员账号登录到智控台。
+
+首先，你要先开启知识库功能。在顶部导航栏中，点击`参数字典`，在下拉菜单中，点击`系统功能配置`页面。在页面上勾选`知识库`，点击`保存配置`。即可在导航栏看到`知识库`功能。
+
+在顶部导航栏中，点击`模型配置`，在左侧导航栏中，点击`知识库`。在列表中找到`RAG_RAGFlow`，点击`编辑`按钮。
+
+在`服务地址`中，填写`http://你的ragflow服务的局域网IP:8008`，例如我的ragflow服务的局域网IP是`192.168.1.100`，那么我就填写`http://192.168.1.100:8008`。
+
+在`API密钥`中，填写之前复制的`API Key`。
+
+最后点击保存按钮。
+
+# 第二步 创建一个知识库
+使用超级管理员账号登录到智控台。在顶部导航栏中，点击`知识库`，在列表左下脚，点击`新增`按钮。填写一个知识库的名字和描述。点击保存。
+
+为了提高大模型对知识库的理解和召回能力，建议在创建知识库时，填写一个有意义的名字和描述。例如，如果你要创建一个关于`公司介绍`的知识库，那么知识库的名字可以是`公司介绍`，描述可以是`关于公司的相关信息例如公司基本信息、服务项目、联系电话、地址等。`。
+
+保存后，你可以在知识库列表中看到这个知识库。点击刚才创建的知识库的`查看`按钮，进入知识库详情页面。
+
+在知识库详情页面中，左下角点击`新增`按钮，可以上传文档到知识库。
+
+上传后，你可以在知识库详情页面中，看到上传的文档。此时可以点击文档的`解析`按钮，解析文档。
+
+解析完成后，你可以查看解析后的切片信息。你可以在知识库详情页面中，点击`召回测试`按钮，可以测试知识库的召回/检索功能。
+
+# 第三步 让小智使用ragflow知识库
+登录到智控台。在顶部导航栏中，点击`智能体`，找到你要配置的智能体，点击`配置角色`按钮。
+
+在意图识别左侧，点击`编辑功能`按钮，弹出一个弹框。在弹框中选择你要添加的知识库。保存即可。

docs/voiceprint-integration.md

@@ -28,7 +28,7 @@ telnet 127.0.0.1 3306
 
 如果不能访问，你需要回忆一下，你的`mysql`是怎么安装的。
 
-如果你的mysql是通过自己使用安装包安装的，说明你的`mysql`做了网络隔离。你可能先解访问`mysql`的`3306`端口这个问题。
+如果你的mysql是通过自己使用安装包安装的，说明你的`mysql`做了网络隔离。你可能先解决访问`mysql`的`3306`端口这个问题。
 
 如果你`mysql`是通过本项目的`docker-compose_all.yml`安装的。你需要找一下你当时创建数据库的`docker-compose_all.yml`文件，修改以下的内容
 
@@ -164,6 +164,8 @@ http://192.168.1.25:8005/voiceprint/health?key=abcd
 # 2、全模块部署时，怎么配置声纹识别
 
 ## 第一步 配置接口
+首先，你要开启声纹识别功能。在智控台，点击顶部`参数字典`，在下拉菜单中，点击`系统功能配置`页面。在页面上勾选`声纹识别`，点击`保存配置`。即可在新建智能体的卡片上看到`声纹识别`按钮。
+
 如果你是全模块部署，使用管理员账号，登录智控台，点击顶部`参数字典`，选择`参数管理`功能。
 
 然后搜索参数`server.voice_print`，此时，它的值应该是`null`值。

main/manager-api/rule/doc/测试验证/知识库模块全量集成测试报告.md

@@ -0,0 +1,45 @@
+# 知识库模块全量集成测试报告
+
+## 1. 测试背景
+针对 `KnowledgeBaseController` 和 `KnowledgeFilesController` 共 14 个接口进行了深度集成测试。主要解决了本地影子库与 RAGFlow 远程服务之间的状态对齐、数据反序列化兼容性以及批量操作逻辑安全性问题。
+
+## 2. 修复的核心 Bug 清单 (Hotfixes)
+
+| 模块 | 问题类型 | 修复方案 | 验证结果 |
+| :--- | :--- | :--- | :--- |
+| **DTO** | `positions` 反序列化失败 | 类型从 `List<Integer>` 提升为 `Object`，支持嵌套数组 | ✅ 已验证 |
+| **DTO** | 日期格式不兼容 | 针对 RAGFlow 的 RFC 1123 格式，将 `Date` 改为 `String` 透传 | ✅ 已验证 |
+| **请求** | 检索参数 `null` 拒绝 | 增加 `@JsonInclude(NON_NULL)`，跳过可选字段的空值序列化 | ✅ 已验证 |
+| **同步** | 状态自愈死锁 | 增加 `CANCEL/FAIL` 状态的 60s 低频同步机制，防止逻辑错误锁定 | ✅ 已验证 |
+| **逻辑** | 删除守卫逻辑错误 | 将拦截条件从 `status="1"` 修正为 `run="RUNNING"` | ✅ 已验证 |
+
+## 3. 全量接口测试统计
+
+### KnowledgeBaseController (7/7)
+- [x] 分页查询 (`GET /datasets`)
+- [x] 详情获取 (`GET /datasets/{id}`)
+- [x] 创建知识库 (`POST /datasets`)
+- [x] 修改配置 (`PUT /datasets/{id}`)
+- [x] 物理删除 (`DELETE /datasets/{id}`)
+- [x] 批量删除 (`DELETE /datasets/batch`)
+- [x] 模型列表获取 (`GET /datasets/rag-models`)
+
+### KnowledgeFilesController (7/7)
+- [x] 文档列表与同步 (`GET /datasets/{id}/documents`)
+- [x] 状态过滤查询 (`GET /datasets/{id}/documents/status/{s}`)
+- [x] 文档上传 (`POST /datasets/{id}/documents`)
+- [x] 触发解析 (`POST /datasets/{id}/chunks`)
+- [x] 切片详情 (`GET /datasets/{id}/documents/{docId}/chunks`)
+- [x] 召回测试 (`POST /datasets/{id}/retrieval-test`)
+- [x] 批量删除文档 (`DELETE /datasets/{id}/documents`)
+
+## 4. 自动化审计结论
+通过执行 `comprehensive_audit.ps1` 自动化脚本，模拟了“创建->上传->解析->同步->检索->删除”的完整生产链路。
+- **解析成功率**：100%
+- **数据准确性**：DTO 转换无异常，坐标及得分提取正常
+- **系统安全性**：解析中拦截机制生效
+- **结论**：**准生产就绪 (Production Ready)**
+
+---
+*报告生成时间：2026-02-13*
+*审核：dora--1206563805@qq.com*

main/manager-api/src/main/java/xiaozhi/common/config/RestTemplateConfig.java

@@ -2,7 +2,9 @@ package xiaozhi.common.config;
 
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.http.client.JdkClientHttpRequestFactory;
 import org.springframework.web.client.RestTemplate;
+import java.time.Duration;
 
 /**
  * RestTemplate配置
@@ -12,6 +14,8 @@ public class RestTemplateConfig {
 
     @Bean
     public RestTemplate restTemplate() {
-        return new RestTemplate();
+        JdkClientHttpRequestFactory factory = new JdkClientHttpRequestFactory();
+        factory.setReadTimeout(Duration.ofSeconds(30));
+        return new RestTemplate(factory);
     }
 }

main/manager-api/src/main/java/xiaozhi/common/config/SwaggerConfig.java

@@ -43,7 +43,7 @@ public class SwaggerConfig {
     public GroupedOpenApi oatApi() {
         return GroupedOpenApi.builder()
                 .group("ota")
-                .pathsToMatch("/ota/**")
+                .pathsToMatch("/ota/**", "/otaMag/**")
                 .build();
     }
 
@@ -79,6 +79,22 @@ public class SwaggerConfig {
                 .build();
     }
 
+    @Bean
+    public GroupedOpenApi knowledgeApi() {
+        return GroupedOpenApi.builder()
+                .group("knowledge")
+                .pathsToMatch("/datasets/**")
+                .build();
+    }
+
+    @Bean
+    public GroupedOpenApi botApi() {
+        return GroupedOpenApi.builder()
+                .group("bot")
+                .pathsToMatch("/api/v1/**")
+                .build();
+    }
+
     @Bean
     public OpenAPI customOpenAPI() {
         return new OpenAPI().info(new Info()

main/manager-api/src/main/java/xiaozhi/common/constant/Constant.java

@@ -141,6 +141,11 @@ public interface Constant {
      */
     String SERVER_MQTT_SECRET = "server.mqtt_signature_key";
 
+    /**
+     * WebSocket认证开关
+     */
+    String SERVER_AUTH_ENABLED = "server.auth.enabled";
+
     /**
      * 无记忆
      */
@@ -151,6 +156,11 @@ public interface Constant {
      */
     String VOICE_CLONE_HUOSHAN_DOUBLE_STREAM = "huoshan_double_stream";
 
+    /**
+     * RAG配置类型
+     */
+    String RAG_CONFIG_TYPE = "RAG";
+
     enum SysBaseParam {
         /**
          * ICP备案号
@@ -294,7 +304,7 @@ public interface Constant {
     /**
      * 版本号
      */
-    public static final String VERSION = "0.8.5";
+    public static final String VERSION = "0.9.2";
 
     /**
      * 无效固件URL

main/manager-api/src/main/java/xiaozhi/common/exception/ErrorCode.java

@@ -82,14 +82,6 @@ public interface ErrorCode {
     int DEVICE_ALREADY_ACTIVATED = 10063;
     // 默认模型删除错误
     int DEFAULT_MODEL_DELETE_ERROR = 10064;
-    // 设备相关错误码
-    int MAC_ADDRESS_ALREADY_EXISTS = 10090; // Mac地址已存在
-    // 模型相关错误码
-    int MODEL_PROVIDER_NOT_EXIST = 10091; // 供应器不存在
-    int LLM_NOT_EXIST = 10092; // 设置的LLM不存在
-    int MODEL_REFERENCED_BY_AGENT = 10093; // 该模型配置已被智能体引用，无法删除
-    int LLM_REFERENCED_BY_INTENT = 10094; // 该LLM模型已被意图识别配置引用，无法删除
-
     // 登录相关错误码
     int ADD_DATA_FAILED = 10065; // 新增数据失败
     int UPDATE_DATA_FAILED = 10066; // 修改数据失败
@@ -127,6 +119,10 @@ public interface ErrorCode {
     int VOICEPRINT_UNREGISTER_PROCESS_ERROR = 10090; // 声纹注销处理失败
     int VOICEPRINT_IDENTIFY_REQUEST_ERROR = 10091; // 声纹识别请求失败
 
+    int LLM_NOT_EXIST = 10092; // 设置的LLM不存在
+    int MODEL_REFERENCED_BY_AGENT = 10093; // 该模型配置已被智能体引用，无法删除
+    int LLM_REFERENCED_BY_INTENT = 10094; // 该LLM模型已被意图识别配置引用，无法删除
+
     // 服务端管理相关错误码
     int INVALID_SERVER_ACTION = 10095; // 无效服务端操作
     int SERVER_WEBSOCKET_NOT_CONFIGURED = 10096; // 未配置服务端WebSocket地址
@@ -198,4 +194,61 @@ public interface ErrorCode {
     int VOICE_CLONE_PREFIX = 10158; // 复刻音色前缀
     int VOICE_ID_ALREADY_EXISTS = 10159; // 音色ID已存在
     int VOICE_CLONE_HUOSHAN_VOICE_ID_ERROR = 10160; // 火山引擎音色ID格式错误
+
+    // 设备相关错误码
+    int MAC_ADDRESS_ALREADY_EXISTS = 10161; // Mac地址已存在
+    // 模型相关错误码
+    int MODEL_PROVIDER_NOT_EXIST = 10162; // 供应器不存在
+
+    // 知识库相关错误码
+    int Knowledge_Base_RECORD_NOT_EXISTS = 10163; // 知识库记录不存在
+    int RAG_CONFIG_NOT_FOUND = 10164; // RAG配置未找到
+    int RAG_CONFIG_TYPE_ERROR = 10165; // RAG配置类型错误
+    int RAG_DEFAULT_CONFIG_NOT_FOUND = 10166; // 默认RAG配置未找到
+    int RAG_API_ERROR = 10167; // RAG调用失败
+    int UPLOAD_FILE_ERROR = 10168; // 上传文件失败
+    int NO_PERMISSION = 10169; // 没有权限
+    int KNOWLEDGE_BASE_NAME_EXISTS = 10170; // 同名知识库已存在
+    int RAG_API_ERROR_URL_NULL = 10171; // RAG配置中base_url为空，请完善配置
+    int RAG_API_ERROR_API_KEY_NULL = 10172; // RAG配置中api_key为空，请完善配置
+    int RAG_API_ERROR_API_KEY_INVALID = 10173; // RAG配置中api_key包含占位符，请替换为实际的API密钥
+    int RAG_API_ERROR_URL_INVALID = 10174; // RAG配置中base_url格式不正确，请检查协议是否正确
+    int RAG_DATASET_ID_NOT_NULL = 10176; // RAG配置中dataset_id不能为空
+    int RAG_MODEL_ID_NOT_NULL = 10177; // RAG配置中model_id不能为空
+    int RAG_DATASET_ID_AND_MODEL_ID_NOT_NULL = 10178; // RAG配置中dataset_id和model_id不能为空
+    int RAG_FILE_NAME_NOT_NULL = 10179; // 文件名称不能为空
+    int RAG_FILE_CONTENT_EMPTY = 10180; // 文件内容不能为空
+
+    // 设备相关错误码（补充）
+    int MCA_NOT_NULL = 10175; // mac地址不能为空
+
+    // 音色克隆（补充）
+    int VOICE_CLONE_NAME_NOT_NULL = 10181; // 音色克隆名称不能为空
+    int VOICE_CLONE_AUDIO_NOT_FOUND = 10182; // 音色克隆音频不存在
+
+    // 智能体模板相关错误码(补充)
+    int AGENT_TEMPLATE_NOT_FOUND = 10183; // 默认智能体未找到
+
+    // 知识库适配器相关错误码
+    int RAG_ADAPTER_TYPE_NOT_SUPPORTED = 10184; // 不支持的适配器类型
+    int RAG_CONFIG_VALIDATION_FAILED = 10185; // RAG配置验证失败
+    int RAG_ADAPTER_CREATION_FAILED = 10186; // 适配器创建失败
+    int RAG_ADAPTER_INIT_FAILED = 10187; // 适配器初始化失败
+    int RAG_ADAPTER_CONNECTION_FAILED = 10188; // 适配器连接测试失败
+    int RAG_ADAPTER_OPERATION_FAILED = 10189; // 适配器操作失败
+    int RAG_ADAPTER_NOT_FOUND = 10190; // 适配器未找到
+    int RAG_ADAPTER_CACHE_ERROR = 10191; // 适配器缓存错误
+    int RAG_ADAPTER_TYPE_NOT_FOUND = 10192; // 适配器类型未找到
+
+    // 设备工具相关错误码
+    int DEVICE_ID_NOT_NULL = 10193; // 设备ID不能为空
+    int DEVICE_NOT_EXIST = 10194; // 设备不存在
+    int OTA_UPLOAD_COUNT_EXCEED = 10195; // OTA上传次数超过限制
+
+    // 智能体标签相关错误码
+    int AGENT_TAG_NAME_DUPLICATE = 10196; // 标签名称已存在
+    int AGENT_TAG_NAME_EMPTY = 10197; // 标签名称不能为空
+    int AGENT_TAG_NOT_EXIST = 10198; // 标签不存在
+
+    int RAG_DOCUMENT_PARSING_DELETE_ERROR = 10199; // 文档解析中，禁止删除
 }

main/manager-api/src/main/java/xiaozhi/common/exception/RenException.java

@@ -13,23 +13,25 @@ public class RenException extends RuntimeException {
     private String msg;
 
     public RenException(int code) {
+        super(MessageUtils.getMessage(code));
         this.code = code;
         this.msg = MessageUtils.getMessage(code);
     }
 
     public RenException(int code, String... params) {
+        super(MessageUtils.getMessage(code, params));
         this.code = code;
         this.msg = MessageUtils.getMessage(code, params);
     }
 
     public RenException(int code, Throwable e) {
-        super(e);
+        super(MessageUtils.getMessage(code), e);
         this.code = code;
         this.msg = MessageUtils.getMessage(code);
     }
 
     public RenException(int code, Throwable e, String... params) {
-        super(e);
+        super(MessageUtils.getMessage(code, params), e);
         this.code = code;
         this.msg = MessageUtils.getMessage(code, params);
     }

main/manager-api/src/main/java/xiaozhi/common/handler/FieldMetaObjectHandler.java

@@ -32,13 +32,23 @@ public class FieldMetaObjectHandler implements MetaObjectHandler {
 
         // 创建者
         strictInsertFill(metaObject, CREATOR, Long.class, user.getId());
-        // 创建时间
+        // 创建时间 - 支持createDate和createdAt两种字段名
-        strictInsertFill(metaObject, CREATE_DATE, Date.class, date);
+        if (metaObject.hasSetter(CREATE_DATE)) {
+            strictInsertFill(metaObject, CREATE_DATE, Date.class, date);
+        }
+        if (metaObject.hasSetter("createdAt")) {
+            strictInsertFill(metaObject, "createdAt", Date.class, date);
+        }
 
         // 更新者
         strictInsertFill(metaObject, UPDATER, Long.class, user.getId());
-        // 更新时间
+        // 更新时间 - 支持updateDate和updatedAt两种字段名
-        strictInsertFill(metaObject, UPDATE_DATE, Date.class, date);
+        if (metaObject.hasSetter(UPDATE_DATE)) {
+            strictInsertFill(metaObject, UPDATE_DATE, Date.class, date);
+        }
+        if (metaObject.hasSetter("updatedAt")) {
+            strictInsertFill(metaObject, "updatedAt", Date.class, date);
+        }
 
         // 数据标识
         strictInsertFill(metaObject, DATA_OPERATION, String.class, Constant.DataOperation.INSERT.getValue());
@@ -46,10 +56,17 @@ public class FieldMetaObjectHandler implements MetaObjectHandler {
 
     @Override
     public void updateFill(MetaObject metaObject) {
+        Date date = new Date();
+
         // 更新者
         strictUpdateFill(metaObject, UPDATER, Long.class, SecurityUser.getUserId());
-        // 更新时间
+        // 更新时间 - 支持updateDate和updatedAt两种字段名
-        strictUpdateFill(metaObject, UPDATE_DATE, Date.class, new Date());
+        if (metaObject.hasSetter(UPDATE_DATE)) {
+            strictUpdateFill(metaObject, UPDATE_DATE, Date.class, date);
+        }
+        if (metaObject.hasSetter("updatedAt")) {
+            strictUpdateFill(metaObject, "updatedAt", Date.class, date);
+        }
 
         // 数据标识
         strictInsertFill(metaObject, DATA_OPERATION, String.class, Constant.DataOperation.UPDATE.getValue());

main/manager-api/src/main/java/xiaozhi/common/redis/RedisKeys.java

@@ -152,4 +152,39 @@ public class RedisKeys {
     public static String getVoiceCloneAudioIdKey(String uuid) {
         return "voiceClone:audio:id:" + uuid;
     }
+
+    /**
+     * 获取知识库缓存key
+     */
+    public static String getKnowledgeBaseCacheKey(String datasetId) {
+        return "knowledge:base:" + datasetId;
+    }
+
+    /**
+     * 获取临时注册设备标记key
+     */
+    public static String getTmpRegisterMacKey(String deviceId) {
+        return "tmp_register_mac:" + deviceId;
+    }
+
+    /**
+     * OTA绑定设备
+     */
+    public static String getOtaActivationCode(String activationCode) {
+        return "ota:activation:code:" + activationCode;
+    }
+
+    /**
+     * OTA获取设备mac相关信息
+     */
+    public static String getOtaDeviceActivationInfo(String deviceId) {
+        return "ota:activation:data:" + deviceId;
+    }
+
+    /**
+     * OTA上传次数
+     */
+    public static String getOtaUploadCountKey(Long username) {
+        return "ota:upload:count:" + username;
+    }
 }

main/manager-api/src/main/java/xiaozhi/common/utils/SensitiveDataUtils.java

@@ -1,14 +1,15 @@
 package xiaozhi.common.utils;
 
-import cn.hutool.json.JSONObject;
-import org.apache.commons.lang3.StringUtils;
-
 import java.util.Arrays;
+import java.util.HashMap;
 import java.util.HashSet;
 import java.util.Map;
-import java.util.HashMap;
 import java.util.Set;
 
+import org.apache.commons.lang3.StringUtils;
+
+import cn.hutool.json.JSONObject;
+
 /**
  * 敏感数据处理工具类
  */
@@ -30,7 +31,7 @@ public class SensitiveDataUtils {
      * 隐藏字符串中间部分
      */
     public static String maskMiddle(String value) {
-        if (StringUtils.isBlank(value)) {
+        if (StringUtils.isBlank(value) || value.length() == 1) {
             return value;
         }
 

main/manager-api/src/main/java/xiaozhi/common/utils/Sm2DecryptUtil.java

@@ -12,28 +12,29 @@ import xiaozhi.modules.sys.service.SysParamsService;
  * 封装了重复的SM2解密、验证码提取和验证逻辑
  */
 public class Sm2DecryptUtil {
-    
+
     /**
      * 验证码长度
      */
     private static final int CAPTCHA_LENGTH = 5;
-    
+
     /**
      * 解密SM2加密内容，提取验证码并验证
+     * 
      * @param encryptedPassword SM2加密的密码字符串
-     * @param captchaId 验证码ID
+     * @param captchaId         验证码ID
-     * @param captchaService 验证码服务
+     * @param captchaService    验证码服务
-     * @param sysParamsService 系统参数服务
+     * @param sysParamsService  系统参数服务
      * @return 解密后的实际密码
      */
-    public static String decryptAndValidateCaptcha(String encryptedPassword, String captchaId, 
+    public static String decryptAndValidateCaptcha(String encryptedPassword, String captchaId,
-                                                 CaptchaService captchaService, SysParamsService sysParamsService) {
+            CaptchaService captchaService, SysParamsService sysParamsService) {
         // 获取SM2私钥
         String privateKeyStr = sysParamsService.getValue(Constant.SM2_PRIVATE_KEY, true);
         if (StringUtils.isBlank(privateKeyStr)) {
             throw new RenException(ErrorCode.SM2_KEY_NOT_CONFIGURED);
         }
-        
+
         // 使用SM2私钥解密密码
         String decryptedContent;
         try {
@@ -41,19 +42,20 @@ public class Sm2DecryptUtil {
         } catch (Exception e) {
             throw new RenException(ErrorCode.SM2_DECRYPT_ERROR);
         }
-        
+
         // 分离验证码和密码：前5位是验证码，后面是密码
         if (decryptedContent.length() > CAPTCHA_LENGTH) {
             String embeddedCaptcha = decryptedContent.substring(0, CAPTCHA_LENGTH);
             String actualPassword = decryptedContent.substring(CAPTCHA_LENGTH);
-            
+
-            // 验证嵌入的验证码是否正确
             boolean embeddedCaptchaValid = captchaService.validate(captchaId, embeddedCaptcha, true);
             if (!embeddedCaptchaValid) {
                 throw new RenException(ErrorCode.SMS_CAPTCHA_ERROR);
             }
-            
+
             return actualPassword;
+        } else if (decryptedContent.length() > 0) {
+            throw new RenException(ErrorCode.SMS_CAPTCHA_ERROR);
         } else {
             throw new RenException(ErrorCode.SM2_DECRYPT_ERROR);
         }

main/manager-api/src/main/java/xiaozhi/common/utils/ToolUtil.java

@@ -0,0 +1,89 @@
+package xiaozhi.common.utils;
+
+import cn.hutool.core.util.ReUtil;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.time.LocalDateTime;
+import java.time.ZoneId;
+import java.util.Date;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * 通用工具类
+ */
+public class ToolUtil {
+    private static final Logger logger = LoggerFactory.getLogger(ToolUtil.class);
+
+    /**
+     * 对象是否不为空(新增)
+     */
+    public static boolean isNotEmpty(Object o) {
+        return !isEmpty(o);
+    }
+
+    /**
+     * 对象是否为空
+     */
+    public static boolean isEmpty(Object o) {
+        if (o == null) {
+            return true;
+        }
+        if (o instanceof String) {
+            if (o.toString().trim().equals("")) {
+                return true;
+            }
+        } else if (o instanceof List) {
+            if (((List) o).size() == 0) {
+                return true;
+            }
+        } else if (o instanceof Map) {
+            if (((Map) o).size() == 0) {
+                return true;
+            }
+        } else if (o instanceof Set) {
+            if (((Set) o).size() == 0) {
+                return true;
+            }
+        } else if (o instanceof Object[]) {
+            if (((Object[]) o).length == 0) {
+                return true;
+            }
+        } else if (o instanceof int[]) {
+            if (((int[]) o).length == 0) {
+                return true;
+            }
+        } else if (o instanceof long[]) {
+            if (((long[]) o).length == 0) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * 对象组中是否存在空对象
+     */
+    public static boolean isOneEmpty(Object... os) {
+        for (Object o : os) {
+            if (isEmpty(o)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * 对象组中是否全是空对象
+     */
+    public static boolean isAllEmpty(Object... os) {
+        for (Object o : os) {
+            if (!isEmpty(o)) {
+                return false;
+            }
+        }
+        return true;
+    }
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/controller/AgentChatHistoryController.java

@@ -139,14 +139,14 @@ public class AgentChatHistoryController {
         // 从Redis获取agentId和sessionId
         String agentSessionInfo = (String) redisUtils.get(RedisKeys.getChatHistoryKey(uuid));
         if (StringUtils.isBlank(agentSessionInfo)) {
-            throw new RenException("下载链接已过期或无效");
+            throw new RenException(ErrorCode.DOWNLOAD_LINK_EXPIRED);
         }
 
         try {
             // 解析agentId和sessionId
             String[] parts = agentSessionInfo.split(":");
             if (parts.length != 2) {
-                throw new RenException("下载链接无效");
+                throw new RenException(ErrorCode.DOWNLOAD_LINK_INVALID);
             }
             String agentId = parts[0];
             String sessionId = parts[1];

main/manager-api/src/main/java/xiaozhi/modules/agent/controller/AgentController.java

@@ -42,8 +42,13 @@ import xiaozhi.modules.agent.dto.AgentMemoryDTO;
 import xiaozhi.modules.agent.dto.AgentUpdateDTO;
 import xiaozhi.modules.agent.entity.AgentEntity;
 import xiaozhi.modules.agent.entity.AgentTemplateEntity;
+import xiaozhi.modules.agent.dto.AgentTagDTO;
+import xiaozhi.modules.agent.entity.AgentTagEntity;
+import xiaozhi.modules.agent.service.AgentTagService;
 import xiaozhi.modules.agent.service.AgentChatAudioService;
 import xiaozhi.modules.agent.service.AgentChatHistoryService;
+import xiaozhi.modules.agent.service.AgentChatSummaryService;
+import xiaozhi.modules.agent.service.AgentContextProviderService;
 import xiaozhi.modules.agent.service.AgentPluginMappingService;
 import xiaozhi.modules.agent.service.AgentService;
 import xiaozhi.modules.agent.service.AgentTemplateService;
@@ -64,14 +69,21 @@ public class AgentController {
     private final AgentChatHistoryService agentChatHistoryService;
     private final AgentChatAudioService agentChatAudioService;
     private final AgentPluginMappingService agentPluginMappingService;
+    private final AgentContextProviderService agentContextProviderService;
+    private final AgentChatSummaryService agentChatSummaryService;
     private final RedisUtils redisUtils;
+    private final AgentTagService agentTagService;
 
     @GetMapping("/list")
     @Operation(summary = "获取用户智能体列表")
     @RequiresPermissions("sys:role:normal")
-    public Result<List<AgentDTO>> getUserAgents() {
+    public Result<List<AgentDTO>> getUserAgents(
+            @RequestParam(value = "keyword", required = false) String keyword,
+            @RequestParam(value = "searchType", defaultValue = "name") String searchType) {
         UserDetail user = SecurityUser.getUser();
-        List<AgentDTO> agents = agentService.getUserAgents(user.getId());
+
+        // 直接调用整合后的getUserAgents方法，无需再区分搜索和普通查询
+        List<AgentDTO> agents = agentService.getUserAgents(user.getId(), keyword, searchType);
         return new Result<List<AgentDTO>>().ok(agents);
     }
 
@@ -117,6 +129,27 @@ public class AgentController {
         return new Result<>();
     }
 
+    @PostMapping("/chat-summary/{sessionId}/save")
+    @Operation(summary = "根据会话ID生成聊天记录总结并保存（异步执行）")
+    public Result<Void> generateAndSaveChatSummary(@PathVariable String sessionId) {
+        try {
+            // 异步执行总结生成任务，立即返回成功响应
+            new Thread(() -> {
+                try {
+                    agentChatSummaryService.generateAndSaveChatSummary(sessionId);
+                    System.out.println("异步执行会话 " + sessionId + " 的聊天记录总结完成");
+                } catch (Exception e) {
+                    System.err.println("异步执行会话 " + sessionId + " 的聊天记录总结失败: " + e.getMessage());
+                }
+            }).start();
+
+            // 立即返回成功响应，不等待总结生成完成
+            return new Result<Void>().ok(null);
+        } catch (Exception e) {
+            return new Result<Void>().error("启动异步总结生成任务失败: " + e.getMessage());
+        }
+    }
+
     @PutMapping("/{id}")
     @Operation(summary = "更新智能体")
     @RequiresPermissions("sys:role:normal")
@@ -135,6 +168,8 @@ public class AgentController {
         agentChatHistoryService.deleteByAgentId(id, true, true);
         // 删除关联的插件
         agentPluginMappingService.deleteByAgentId(id);
+        // 删除关联的上下文源配置
+        agentContextProviderService.deleteByAgentId(id);
         // 再删除智能体
         agentService.deleteById(id);
         return new Result<>();
@@ -182,6 +217,7 @@ public class AgentController {
         List<AgentChatHistoryDTO> result = agentChatHistoryService.getChatHistoryBySessionId(id, sessionId);
         return new Result<List<AgentChatHistoryDTO>>().ok(result);
     }
+
     @GetMapping("/{id}/chat-history/user")
     @Operation(summary = "获取智能体聊天记录（用户）")
     @RequiresPermissions("sys:role:normal")
@@ -243,4 +279,50 @@ public class AgentController {
                 .body(audioData);
     }
 
+    @PostMapping("/tag")
+    @Operation(summary = "创建标签")
+    @RequiresPermissions("sys:role:normal")
+    public Result<AgentTagEntity> createTag(@RequestBody Map<String, String> params) {
+        String tagName = params.get("tagName");
+        if (StringUtils.isBlank(tagName)) {
+            return new Result<AgentTagEntity>().error("标签名称不能为空");
+        }
+        AgentTagEntity tag = agentTagService.saveTag(tagName);
+        return new Result<AgentTagEntity>().ok(tag);
+    }
+
+    @GetMapping("/tag/list")
+    @Operation(summary = "获取所有标签列表")
+    @RequiresPermissions("sys:role:normal")
+    public Result<List<AgentTagDTO>> getAllTags() {
+        List<AgentTagDTO> tags = agentTagService.getAllTags();
+        return new Result<List<AgentTagDTO>>().ok(tags);
+    }
+
+    @DeleteMapping("/tag/{id}")
+    @Operation(summary = "删除标签")
+    @RequiresPermissions("sys:role:normal")
+    public Result<Void> deleteTag(@PathVariable String id) {
+        agentTagService.deleteTag(id);
+        return new Result<Void>().ok(null);
+    }
+
+    @GetMapping("/{id}/tags")
+    @Operation(summary = "获取智能体的标签")
+    @RequiresPermissions("sys:role:normal")
+    public Result<List<AgentTagDTO>> getAgentTags(@PathVariable String id) {
+        List<AgentTagDTO> tags = agentTagService.getTagsByAgentId(id);
+        return new Result<List<AgentTagDTO>>().ok(tags);
+    }
+
+    @PutMapping("/{id}/tags")
+    @Operation(summary = "保存智能体的标签")
+    @RequiresPermissions("sys:role:normal")
+    public Result<Void> saveAgentTags(@PathVariable String id, @RequestBody Map<String, Object> params) {
+        List<String> tagIds = (List<String>) params.get("tagIds");
+        List<String> tagNames = (List<String>) params.get("tagNames");
+        agentTagService.saveAgentTags(id, tagIds, tagNames);
+        return new Result<Void>().ok(null);
+    }
+
 }

main/manager-api/src/main/java/xiaozhi/modules/agent/controller/AgentMcpAccessPointController.java

@@ -28,7 +28,7 @@ public class AgentMcpAccessPointController {
     /**
      * 获取智能体的Mcp接入点地址
      * 
-     * @param audioId 智能体id
+     * @param agentId 智能体id
      * @return 返回错误提醒或者Mcp接入点地址
      */
     @Operation(summary = "获取智能体的Mcp接入点地址")

main/manager-api/src/main/java/xiaozhi/modules/agent/dao/AgentContextProviderDao.java

@@ -0,0 +1,9 @@
+package xiaozhi.modules.agent.dao;
+
+import org.apache.ibatis.annotations.Mapper;
+import xiaozhi.common.dao.BaseDao;
+import xiaozhi.modules.agent.entity.AgentContextProviderEntity;
+
+@Mapper
+public interface AgentContextProviderDao extends BaseDao<AgentContextProviderEntity> {
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/dao/AgentTagDao.java

@@ -0,0 +1,24 @@
+package xiaozhi.modules.agent.dao;
+
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import xiaozhi.common.dao.BaseDao;
+import xiaozhi.modules.agent.entity.AgentTagEntity;
+
+import java.util.List;
+
+@Mapper
+public interface AgentTagDao extends BaseDao<AgentTagEntity> {
+
+    List<AgentTagEntity> selectByAgentId(@Param("agentId") String agentId);
+
+    List<AgentTagEntity> selectByAgentIds(@Param("agentIds") List<String> agentIds);
+
+    List<AgentTagEntity> selectAll();
+
+    List<String> selectAgentIdsByTagName(@Param("tagName") String tagName);
+
+    List<AgentTagEntity> selectByTagNames(@Param("tagNames") List<String> tagNames);
+
+    int batchInsert(@Param("list") List<AgentTagEntity> tagList);
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/dao/AgentTagRelationDao.java

@@ -0,0 +1,18 @@
+package xiaozhi.modules.agent.dao;
+
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import xiaozhi.common.dao.BaseDao;
+import xiaozhi.modules.agent.entity.AgentTagRelationEntity;
+
+import java.util.List;
+
+@Mapper
+public interface AgentTagRelationDao extends BaseDao<AgentTagRelationEntity> {
+
+    int deleteByAgentId(@Param("agentId") String agentId);
+
+    int insertRelation(AgentTagRelationEntity relation);
+
+    int batchInsertRelation(@Param("list") List<AgentTagRelationEntity> relations);
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/dao/AiAgentChatHistoryDao.java

@@ -1,6 +1,9 @@
 package xiaozhi.modules.agent.dao;
 
+import java.util.List;
+
 import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
 
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 
@@ -15,12 +18,6 @@ import xiaozhi.modules.agent.entity.AgentChatHistoryEntity;
  */
 @Mapper
 public interface AiAgentChatHistoryDao extends BaseMapper<AgentChatHistoryEntity> {
-    /**
-     * 根据智能体ID删除音频
-     *
-     * @param agentId 智能体ID
-     */
-    void deleteAudioByAgentId(String agentId);
 
     /**
      * 根据智能体ID删除聊天历史记录
@@ -35,4 +32,19 @@ public interface AiAgentChatHistoryDao extends BaseMapper<AgentChatHistoryEntity
      * @param agentId 智能体ID
      */
     void deleteAudioIdByAgentId(String agentId);
+
+    /**
+     * 根据智能体ID获取所有音频ID列表
+     *
+     * @param agentId 智能体ID
+     * @return 音频ID列表
+     */
+    List<String> getAudioIdsByAgentId(String agentId);
+
+    /**
+     * 批量删除音频
+     *
+     * @param audioIds 音频ID列表
+     */
+    void deleteAudioByIds(@Param("audioIds") List<String> audioIds);
 }

main/manager-api/src/main/java/xiaozhi/modules/agent/dto/AgentChatSummaryDTO.java

@@ -0,0 +1,45 @@
+package xiaozhi.modules.agent.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+/**
+ * 智能体聊天记录总结DTO
+ */
+@Data
+@Schema(description = "智能体聊天记录总结对象")
+public class AgentChatSummaryDTO {
+
+    @Schema(description = "会话ID")
+    private String sessionId;
+
+    @Schema(description = "智能体ID")
+    private String agentId;
+
+    @Schema(description = "总结内容")
+    private String summary;
+
+    @Schema(description = "总结状态")
+    private boolean success;
+
+    @Schema(description = "错误信息")
+    private String errorMessage;
+
+    public AgentChatSummaryDTO() {
+        this.success = true;
+    }
+
+    public AgentChatSummaryDTO(String sessionId, String agentId, String summary) {
+        this.sessionId = sessionId;
+        this.agentId = agentId;
+        this.summary = summary;
+        this.success = true;
+    }
+
+    public AgentChatSummaryDTO(String sessionId, String errorMessage) {
+        this.sessionId = sessionId;
+        this.errorMessage = errorMessage;
+        this.success = false;
+    }
+
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/dto/AgentDTO.java

@@ -1,9 +1,11 @@
 package xiaozhi.modules.agent.dto;
 
 import java.util.Date;
+import java.util.List;
 
 import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
+import xiaozhi.modules.agent.dto.AgentTagDTO;
 
 /**
  * 智能体数据传输对象
@@ -45,4 +47,7 @@ public class AgentDTO {
 
     @Schema(description = "设备数量", example = "10")
     private Integer deviceCount;
+
+    @Schema(description = "标签列表")
+    private List<AgentTagDTO> tags;
 }

main/manager-api/src/main/java/xiaozhi/modules/agent/dto/AgentTagDTO.java

@@ -0,0 +1,20 @@
+package xiaozhi.modules.agent.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import java.io.Serializable;
+import java.util.List;
+
+@Data
+@Schema(description = "智能体标签DTO")
+public class AgentTagDTO implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    @Schema(description = "标签ID")
+    private String id;
+
+    @Schema(description = "标签名称")
+    private String tagName;
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/dto/AgentUpdateDTO.java

@@ -1,6 +1,7 @@
 package xiaozhi.modules.agent.dto;
 
 import java.io.Serializable;
+import java.math.BigDecimal;
 import java.util.HashMap;
 import java.util.List;
 
@@ -41,6 +42,18 @@ public class AgentUpdateDTO implements Serializable {
     @Schema(description = "音色标识", example = "voice_02", nullable = true)
     private String ttsVoiceId;
 
+    @Schema(description = "音色语言", example = "普通话", nullable = true)
+    private String ttsLanguage;
+
+    @Schema(description = "TTS音量", example = "50", nullable = true)
+    private Integer ttsVolume;
+
+    @Schema(description = "TTS语速", example = "50", nullable = true)
+    private Integer ttsRate;
+
+    @Schema(description = "TTS音调", example = "50", nullable = true)
+    private Integer ttsPitch;
+
     @Schema(description = "记忆模型标识", example = "mem_model_02", nullable = true)
     private String memModelId;
 
@@ -69,6 +82,9 @@ public class AgentUpdateDTO implements Serializable {
     @Schema(description = "排序", example = "1", nullable = true)
     private Integer sort;
 
+    @Schema(description = "上下文源配置", nullable = true)
+    private List<ContextProviderDTO> contextProviders;
+
     @Data
     @Schema(description = "插件函数信息")
     public static class FunctionInfo implements Serializable {

main/manager-api/src/main/java/xiaozhi/modules/agent/dto/ContextProviderDTO.java

@@ -0,0 +1,19 @@
+package xiaozhi.modules.agent.dto;
+
+import java.io.Serializable;
+import java.util.Map;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+@Data
+@Schema(description = "上下文源配置DTO")
+public class ContextProviderDTO implements Serializable {
+    private static final long serialVersionUID = 1L;
+
+    @Schema(description = "URL地址")
+    private String url;
+
+    @Schema(description = "请求头")
+    private Map<String, Object> headers;
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/entity/AgentContextProviderEntity.java

@@ -0,0 +1,43 @@
+package xiaozhi.modules.agent.entity;
+
+import java.util.Date;
+import java.util.List;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import com.baomidou.mybatisplus.extension.handlers.JacksonTypeHandler;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+import xiaozhi.modules.agent.dto.ContextProviderDTO;
+
+@Data
+@TableName(value = "ai_agent_context_provider", autoResultMap = true)
+@Schema(description = "智能体上下文源配置")
+public class AgentContextProviderEntity {
+
+    @TableId(type = IdType.ASSIGN_UUID)
+    @Schema(description = "主键")
+    private String id;
+
+    @Schema(description = "智能体ID")
+    private String agentId;
+
+    @Schema(description = "上下文源配置")
+    @TableField(typeHandler = JacksonTypeHandler.class)
+    private List<ContextProviderDTO> contextProviders;
+
+    @Schema(description = "创建者")
+    private Long creator;
+
+    @Schema(description = "创建时间")
+    private Date createdAt;
+
+    @Schema(description = "更新者")
+    private Long updater;
+
+    @Schema(description = "更新时间")
+    private Date updatedAt;
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/entity/AgentEntity.java

@@ -1,5 +1,6 @@
 package xiaozhi.modules.agent.entity;
 
+import java.math.BigDecimal;
 import java.util.Date;
 
 import com.baomidou.mybatisplus.annotation.IdType;
@@ -45,6 +46,18 @@ public class AgentEntity {
     @Schema(description = "音色标识")
     private String ttsVoiceId;
 
+    @Schema(description = "音色语言")
+    private String ttsLanguage;
+
+    @Schema(description = "TTS音量")
+    private Integer ttsVolume;
+
+    @Schema(description = "TTS语速")
+    private Integer ttsRate;
+
+    @Schema(description = "TTS音调")
+    private Integer ttsPitch;
+
     @Schema(description = "记忆模型标识")
     private String memModelId;
 

main/manager-api/src/main/java/xiaozhi/modules/agent/entity/AgentTagEntity.java

@@ -0,0 +1,41 @@
+package xiaozhi.modules.agent.entity;
+
+import java.util.Date;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+@Data
+@TableName("ai_agent_tag")
+@Schema(description = "智能体标签")
+public class AgentTagEntity {
+
+    @TableId(type = IdType.ASSIGN_UUID)
+    @Schema(description = "主键")
+    private String id;
+
+    @Schema(description = "标签名称")
+    private String tagName;
+
+    @Schema(description = "排序")
+    private Integer sort;
+
+    @Schema(description = "创建者")
+    private Long creator;
+
+    @Schema(description = "创建时间")
+    private Date createdAt;
+
+    @Schema(description = "更新者")
+    private Long updater;
+
+    @Schema(description = "更新时间")
+    private Date updatedAt;
+
+    @Schema(description = "删除标记")
+    private Integer deleted;
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/entity/AgentTagRelationEntity.java

@@ -0,0 +1,41 @@
+package xiaozhi.modules.agent.entity;
+
+import java.util.Date;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+@Data
+@TableName("ai_agent_tag_relation")
+@Schema(description = "智能体标签关联")
+public class AgentTagRelationEntity {
+
+    @TableId(type = IdType.ASSIGN_UUID)
+    @Schema(description = "主键")
+    private String id;
+
+    @Schema(description = "智能体ID")
+    private String agentId;
+
+    @Schema(description = "标签ID")
+    private String tagId;
+
+    @Schema(description = "排序")
+    private Integer sort;
+
+    @Schema(description = "创建者")
+    private Long creator;
+
+    @Schema(description = "创建时间")
+    private Date createdAt;
+
+    @Schema(description = "更新者")
+    private Long updater;
+
+    @Schema(description = "更新时间")
+    private Date updatedAt;
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/entity/AgentTemplateEntity.java

@@ -1,6 +1,7 @@
 package xiaozhi.modules.agent.entity;
 
 import java.io.Serializable;
+import java.math.BigDecimal;
 import java.util.Date;
 
 import com.baomidou.mybatisplus.annotation.IdType;
@@ -64,6 +65,26 @@ public class AgentTemplateEntity implements Serializable {
      */
     private String ttsVoiceId;
 
+    /**
+     * 音色语言
+     */
+    private String ttsLanguage;
+
+    /**
+     * TTS音量
+     */
+    private Integer ttsVolume;
+
+    /**
+     * TTS语速
+     */
+    private Integer ttsRate;
+
+    /**
+     * TTS音调
+     */
+    private Integer ttsPitch;
+
     /**
      * 记忆模型标识
      */

main/manager-api/src/main/java/xiaozhi/modules/agent/service/AgentChatSummaryService.java

@@ -0,0 +1,15 @@
+package xiaozhi.modules.agent.service;
+
+/**
+ * 智能体聊天记录总结服务接口
+ */
+public interface AgentChatSummaryService {
+
+    /**
+     * 根据会话ID生成聊天记录总结并保存到智能体记忆
+     * 
+     * @param sessionId 会话ID
+     * @return 保存结果
+     */
+    boolean generateAndSaveChatSummary(String sessionId);
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/service/AgentContextProviderService.java

@@ -0,0 +1,25 @@
+package xiaozhi.modules.agent.service;
+
+import xiaozhi.common.service.BaseService;
+import xiaozhi.modules.agent.entity.AgentContextProviderEntity;
+
+public interface AgentContextProviderService extends BaseService<AgentContextProviderEntity> {
+    /**
+     * 根据智能体ID获取上下文源配置
+     * @param agentId 智能体ID
+     * @return 上下文源配置实体
+     */
+    AgentContextProviderEntity getByAgentId(String agentId);
+
+    /**
+     * 保存或更新上下文源配置
+     * @param entity 实体
+     */
+    void saveOrUpdateByAgentId(AgentContextProviderEntity entity);
+
+    /**
+     * 根据智能体ID删除上下文源配置
+     * @param agentId 智能体ID
+     */
+    void deleteByAgentId(String agentId);
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/service/AgentService.java

@@ -54,9 +54,11 @@ public interface AgentService extends BaseService<AgentEntity> {
      * 获取用户智能体列表
      *
      * @param userId 用户ID
+     * @param keyword 搜索关键词
+     * @param searchType 搜索类型（name - 按名称搜索，mac - 按MAC地址搜索）
      * @return 智能体列表
      */
-    List<AgentDTO> getUserAgents(Long userId);
+    List<AgentDTO> getUserAgents(Long userId, String keyword, String searchType);
 
     /**
      * 根据智能体ID获取设备数量
@@ -98,4 +100,6 @@ public interface AgentService extends BaseService<AgentEntity> {
      * @return 创建的智能体ID
      */
     String createAgent(AgentCreateDTO dto);
+
+
 }

main/manager-api/src/main/java/xiaozhi/modules/agent/service/AgentTagService.java

@@ -0,0 +1,25 @@
+package xiaozhi.modules.agent.service;
+
+import java.util.List;
+
+import xiaozhi.modules.agent.dto.AgentTagDTO;
+import xiaozhi.modules.agent.entity.AgentTagEntity;
+
+public interface AgentTagService {
+
+    AgentTagEntity saveTag(String tagName);
+
+    void deleteTag(String tagId);
+
+    List<AgentTagDTO> getTagsByAgentId(String agentId);
+
+    void saveAgentTags(String agentId, List<String> tagIds, List<String> tagNames);
+
+    void deleteAgentTags(String agentId);
+
+    List<AgentTagDTO> getTagsByAgentIds(List<String> agentIds);
+
+    List<AgentTagDTO> getAllTags();
+
+    List<String> getAgentIdsByTagName(String tagName);
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/service/biz/impl/AgentChatHistoryBizServiceImpl.java

@@ -17,6 +17,7 @@ import xiaozhi.modules.agent.entity.AgentChatHistoryEntity;
 import xiaozhi.modules.agent.entity.AgentEntity;
 import xiaozhi.modules.agent.service.AgentChatAudioService;
 import xiaozhi.modules.agent.service.AgentChatHistoryService;
+import xiaozhi.modules.agent.service.AgentChatSummaryService;
 import xiaozhi.modules.agent.service.AgentService;
 import xiaozhi.modules.agent.service.biz.AgentChatHistoryBizService;
 import xiaozhi.modules.device.entity.DeviceEntity;
@@ -36,6 +37,7 @@ public class AgentChatHistoryBizServiceImpl implements AgentChatHistoryBizServic
     private final AgentService agentService;
     private final AgentChatHistoryService agentChatHistoryService;
     private final AgentChatAudioService agentChatAudioService;
+    private final AgentChatSummaryService agentChatSummaryService;
     private final RedisUtils redisUtils;
     private final DeviceService deviceService;
 
@@ -50,7 +52,8 @@ public class AgentChatHistoryBizServiceImpl implements AgentChatHistoryBizServic
     public Boolean report(AgentChatHistoryReportDTO report) {
         String macAddress = report.getMacAddress();
         Byte chatType = report.getChatType();
-        Long reportTimeMillis = null != report.getReportTime() ? report.getReportTime() * 1000 : System.currentTimeMillis();
+        Long reportTimeMillis = null != report.getReportTime() ? report.getReportTime() * 1000
+                : System.currentTimeMillis();
         log.info("小智设备聊天上报请求: macAddress={}, type={} reportTime={}", macAddress, chatType, reportTimeMillis);
 
         // 根据设备MAC地址查询对应的默认智能体，判断是否需要上报
@@ -105,7 +108,8 @@ public class AgentChatHistoryBizServiceImpl implements AgentChatHistoryBizServic
     /**
      * 组装上报数据
      */
-    private void saveChatText(AgentChatHistoryReportDTO report, String agentId, String macAddress, String audioId, Long reportTime) {
+    private void saveChatText(AgentChatHistoryReportDTO report, String agentId, String macAddress, String audioId,
+            Long reportTime) {
         // 构建聊天记录实体
         AgentChatHistoryEntity entity = AgentChatHistoryEntity.builder()
                 .macAddress(macAddress)

main/manager-api/src/main/java/xiaozhi/modules/agent/service/impl/AgentChatHistoryServiceImpl.java

@@ -5,6 +5,7 @@ import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
 
+import cn.hutool.core.collection.ListUtil;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
@@ -18,6 +19,7 @@ import xiaozhi.common.constant.Constant;
 import xiaozhi.common.page.PageData;
 import xiaozhi.common.utils.ConvertUtils;
 import xiaozhi.common.utils.JsonUtils;
+import xiaozhi.common.utils.ToolUtil;
 import xiaozhi.modules.agent.Enums.AgentChatHistoryType;
 import xiaozhi.modules.agent.dao.AiAgentChatHistoryDao;
 import xiaozhi.modules.agent.dto.AgentChatHistoryDTO;
@@ -84,7 +86,15 @@ public class AgentChatHistoryServiceImpl extends ServiceImpl<AiAgentChatHistoryD
     @Transactional(rollbackFor = Exception.class)
     public void deleteByAgentId(String agentId, Boolean deleteAudio, Boolean deleteText) {
         if (deleteAudio) {
-            baseMapper.deleteAudioByAgentId(agentId);
+            // 分批删除音频,避免超时
+            List<String> audioIds = baseMapper.getAudioIdsByAgentId(agentId);
+            if (ToolUtil.isNotEmpty(audioIds)) {
+                // 每批删除1000条
+                List<List<String>> batch = ListUtil.split(audioIds, 1000);
+                batch.forEach(dataList->{
+                    baseMapper.deleteAudioByIds(dataList);
+                });
+            }
         }
         if (deleteAudio && !deleteText) {
             baseMapper.deleteAudioIdByAgentId(agentId);
@@ -107,7 +117,7 @@ public class AgentChatHistoryServiceImpl extends ServiceImpl<AiAgentChatHistoryD
                 // 添加此行，确保查询结果按照创建时间降序排列
                 // 使用id的原因：数据形式，id越大的创建时间就越晚，所以使用id的结果和创建时间降序排列结果一样
                 // id作为降序排列的优势，性能高，有主键索引，不用在排序的时候重新进行排除扫描比较
-                .orderByDesc(AgentChatHistoryEntity::getId); 
+                .orderByDesc(AgentChatHistoryEntity::getId);
 
         // 构建分页查询，查询前50页数据
         Page<AgentChatHistoryEntity> pageParam = new Page<>(0, 50);

main/manager-api/src/main/java/xiaozhi/modules/agent/service/impl/AgentChatSummaryServiceImpl.java

@@ -0,0 +1,423 @@
+package xiaozhi.modules.agent.service.impl;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import org.apache.commons.lang3.StringUtils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.stereotype.Service;
+
+import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
+
+import lombok.RequiredArgsConstructor;
+import xiaozhi.modules.agent.dto.AgentChatHistoryDTO;
+import xiaozhi.modules.agent.dto.AgentChatSummaryDTO;
+import xiaozhi.modules.agent.dto.AgentMemoryDTO;
+import xiaozhi.modules.agent.dto.AgentUpdateDTO;
+import xiaozhi.modules.agent.entity.AgentChatHistoryEntity;
+import xiaozhi.modules.agent.service.AgentChatHistoryService;
+import xiaozhi.modules.agent.service.AgentChatSummaryService;
+import xiaozhi.modules.agent.service.AgentService;
+import xiaozhi.modules.agent.vo.AgentInfoVO;
+import xiaozhi.modules.device.entity.DeviceEntity;
+import xiaozhi.modules.device.service.DeviceService;
+import xiaozhi.modules.llm.service.LLMService;
+import xiaozhi.modules.model.entity.ModelConfigEntity;
+import xiaozhi.modules.model.service.ModelConfigService;
+
+/**
+ * 智能体聊天记录总结服务实现类
+ * 实现Python端mem_local_short.py中的总结逻辑
+ */
+@Service
+@RequiredArgsConstructor
+public class AgentChatSummaryServiceImpl implements AgentChatSummaryService {
+
+    private static final Logger log = LoggerFactory.getLogger(AgentChatSummaryServiceImpl.class);
+
+    private final AgentChatHistoryService agentChatHistoryService;
+    private final AgentService agentService;
+    private final DeviceService deviceService;
+    private final LLMService llmService;
+    private final ModelConfigService modelConfigService;
+
+    // 总结规则常量
+    private static final int MAX_SUMMARY_LENGTH = 1800; // 最大总结长度
+    private static final Pattern JSON_PATTERN = Pattern.compile("\\{.*?\\}", Pattern.DOTALL);
+    private static final Pattern DEVICE_CONTROL_PATTERN = Pattern.compile("设备控制|设备操作|控制设备|设备状态",
+            Pattern.CASE_INSENSITIVE);
+    private static final Pattern WEATHER_PATTERN = Pattern.compile("天气|温度|湿度|降雨|气象", Pattern.CASE_INSENSITIVE);
+    private static final Pattern DATE_PATTERN = Pattern.compile("日期|时间|星期|月份|年份", Pattern.CASE_INSENSITIVE);
+
+    private AgentChatSummaryDTO generateChatSummary(String sessionId) {
+        try {
+            System.out.println("开始生成会话 " + sessionId + " 的聊天记录总结");
+
+            // 1. 根据sessionId获取聊天记录
+            List<AgentChatHistoryDTO> chatHistory = getChatHistoryBySessionId(sessionId);
+            if (chatHistory == null || chatHistory.isEmpty()) {
+                return new AgentChatSummaryDTO(sessionId, "未找到该会话的聊天记录");
+            }
+
+            // 2. 获取智能体信息
+            String agentId = getAgentIdFromSession(sessionId, chatHistory);
+            if (StringUtils.isBlank(agentId)) {
+                return new AgentChatSummaryDTO(sessionId, "无法获取智能体信息");
+            }
+
+            // 3. 提取关键对话内容
+            List<String> meaningfulMessages = extractMeaningfulMessages(chatHistory);
+            if (meaningfulMessages.isEmpty()) {
+                return new AgentChatSummaryDTO(sessionId, "没有有效的对话内容可总结");
+            }
+
+            // 4. 生成总结（generateSummaryFromMessages方法已包含长度限制逻辑）
+            String summary = generateSummaryFromMessages(meaningfulMessages, agentId);
+
+            log.info("成功生成会话 {} 的聊天记录总结，长度: {} 字符", sessionId, summary.length());
+            return new AgentChatSummaryDTO(sessionId, agentId, summary);
+
+        } catch (Exception e) {
+            log.error("生成会话 {} 的聊天记录总结时发生错误: {}", sessionId, e.getMessage());
+            return new AgentChatSummaryDTO(sessionId, "生成总结时发生错误: " + e.getMessage());
+        }
+    }
+
+    @Override
+    public boolean generateAndSaveChatSummary(String sessionId) {
+        try {
+            // 1. 生成总结
+            AgentChatSummaryDTO summaryDTO = generateChatSummary(sessionId);
+            if (!summaryDTO.isSuccess()) {
+                log.info("生成总结失败: {}", summaryDTO.getErrorMessage());
+                return false;
+            }
+
+            // 2. 获取设备信息（通过会话关联的设备）
+            DeviceEntity device = getDeviceBySessionId(sessionId);
+            if (device == null) {
+                log.info("未找到与会话 {} 关联的设备", sessionId);
+                return false;
+            }
+
+            // 3. 更新智能体记忆
+            AgentMemoryDTO memoryDTO = new AgentMemoryDTO();
+            memoryDTO.setSummaryMemory(summaryDTO.getSummary());
+
+            // 调用现有接口更新记忆
+            agentService.updateAgentById(device.getAgentId(),
+                    new AgentUpdateDTO() {
+                        {
+                            setSummaryMemory(summaryDTO.getSummary());
+                        }
+                    });
+
+            log.info("成功保存会话 {} 的聊天记录总结到智能体 {}", sessionId, device.getAgentId());
+            return true;
+
+        } catch (Exception e) {
+            log.error("保存会话 {} 的聊天记录总结时发生错误: {}", sessionId, e.getMessage());
+            return false;
+        }
+    }
+
+    /**
+     * 根据会话ID获取聊天记录
+     */
+    private List<AgentChatHistoryDTO> getChatHistoryBySessionId(String sessionId) {
+        try {
+            // 这里需要根据sessionId获取聊天记录
+            // 由于现有接口需要agentId，我们需要先找到关联的agentId
+            String agentId = findAgentIdBySessionId(sessionId);
+            if (StringUtils.isBlank(agentId)) {
+                return null;
+            }
+            return agentChatHistoryService.getChatHistoryBySessionId(agentId, sessionId);
+        } catch (Exception e) {
+            log.error("获取会话 {} 的聊天记录失败: {}", sessionId, e.getMessage());
+            return null;
+        }
+    }
+
+    /**
+     * 根据会话ID查找关联的智能体ID
+     */
+    private String findAgentIdBySessionId(String sessionId) {
+        try {
+            // 查询该会话的第一条记录获取agentId
+            QueryWrapper<AgentChatHistoryEntity> wrapper = new QueryWrapper<>();
+            wrapper.select("agent_id")
+                    .eq("session_id", sessionId)
+                    .last("LIMIT 1");
+
+            AgentChatHistoryEntity entity = agentChatHistoryService.getOne(wrapper);
+            return entity != null ? entity.getAgentId() : null;
+        } catch (Exception e) {
+            log.error("根据会话ID {} 查找智能体ID失败: {}", sessionId, e.getMessage());
+            return null;
+        }
+    }
+
+    /**
+     * 从会话中获取智能体ID
+     */
+    private String getAgentIdFromSession(String sessionId, List<AgentChatHistoryDTO> chatHistory) {
+        // 直接从数据库查询智能体ID
+        return findAgentIdBySessionId(sessionId);
+    }
+
+    /**
+     * 提取有意义的对话内容（只提取用户消息，排除AI回复）
+     */
+    private List<String> extractMeaningfulMessages(List<AgentChatHistoryDTO> chatHistory) {
+        List<String> meaningfulMessages = new ArrayList<>();
+
+        for (AgentChatHistoryDTO message : chatHistory) {
+            // 只处理用户消息（chatType = 1）
+            if (message.getChatType() != null && message.getChatType() == 1) {
+                String content = extractContentFromMessage(message);
+                if (isMeaningfulMessage(content)) {
+                    meaningfulMessages.add(content);
+                }
+            }
+        }
+
+        return meaningfulMessages;
+    }
+
+    /**
+     * 从消息中提取内容（处理JSON格式）
+     */
+    private String extractContentFromMessage(AgentChatHistoryDTO message) {
+        String content = message.getContent();
+        if (StringUtils.isBlank(content)) {
+            return "";
+        }
+
+        // 处理JSON格式内容（与前端ChatHistoryDialog.vue逻辑一致）
+        Matcher matcher = JSON_PATTERN.matcher(content);
+        if (matcher.find()) {
+            String jsonContent = matcher.group();
+            // 简化处理：提取JSON中的文本内容
+            return extractTextFromJson(jsonContent);
+        }
+
+        return content;
+    }
+
+    /**
+     * 从JSON中提取文本内容
+     */
+    private String extractTextFromJson(String jsonContent) {
+        // 简化处理：提取"content"字段的值
+        Pattern contentPattern = Pattern.compile("\"content\"\s*:\s*\"([^\"]*)\"");
+        Matcher matcher = contentPattern.matcher(jsonContent);
+        if (matcher.find()) {
+            return matcher.group(1);
+        }
+        return jsonContent;
+    }
+
+    /**
+     * 判断是否为有意义的消息
+     */
+    private boolean isMeaningfulMessage(String content) {
+        if (StringUtils.isBlank(content)) {
+            return false;
+        }
+
+        // 排除设备控制信息
+        if (DEVICE_CONTROL_PATTERN.matcher(content).find()) {
+            return false;
+        }
+
+        // 排除日期天气等无关内容
+        if (WEATHER_PATTERN.matcher(content).find() || DATE_PATTERN.matcher(content).find()) {
+            return false;
+        }
+
+        // 排除过短的消息
+        return content.length() >= 5;
+    }
+
+    /**
+     * 从消息生成总结
+     */
+    private String generateSummaryFromMessages(List<String> messages, String agentId) {
+        if (messages.isEmpty()) {
+            return "本次对话内容较少，没有需要总结的重要信息。";
+        }
+
+        // 构建完整的对话内容
+        StringBuilder conversation = new StringBuilder();
+        for (int i = 0; i < messages.size(); i++) {
+            conversation.append("消息").append(i + 1).append(": ").append(messages.get(i)).append("\n");
+        }
+
+        try {
+            // 获取当前智能体的历史记忆
+            String historyMemory = getCurrentAgentMemory(agentId);
+
+            // 调用LLM服务进行智能总结，传递agentId以获取正确的模型配置
+            String summary = callJavaLLMForSummaryWithHistory(conversation.toString(), historyMemory, agentId);
+
+            // 应用总结规则：限制最大长度
+            if (summary.length() > MAX_SUMMARY_LENGTH) {
+                summary = summary.substring(0, MAX_SUMMARY_LENGTH) + "...";
+            }
+
+            return summary;
+        } catch (Exception e) {
+            log.error("调用Java端LLM服务失败: {}", e.getMessage());
+            throw new RuntimeException("LLM服务不可用，无法生成聊天总结");
+        }
+    }
+
+    /**
+     * 获取当前智能体的历史记忆
+     */
+    private String getCurrentAgentMemory(String agentId) {
+        try {
+            if (StringUtils.isBlank(agentId)) {
+                return null;
+            }
+
+            // 获取智能体信息
+            AgentInfoVO agentInfo = agentService.getAgentById(agentId);
+            if (agentInfo == null) {
+                return null;
+            }
+
+            // 返回智能体的当前总结记忆
+            return agentInfo.getSummaryMemory();
+        } catch (Exception e) {
+            log.error("获取智能体历史记忆失败，agentId: {}, 错误: {}", agentId, e.getMessage());
+            return null;
+        }
+    }
+
+    /**
+     * 调用Java端LLM服务进行智能总结（支持历史记忆合并）
+     */
+    private String callJavaLLMForSummaryWithHistory(String conversation, String historyMemory, String agentId) {
+        try {
+            // 获取智能体配置，从中提取记忆总结的模型ID
+            String modelId = getMemorySummaryModelId(agentId);
+
+            if (StringUtils.isBlank(modelId)) {
+                log.info("未找到记忆总结的LLM模型配置，使用默认LLM服务");
+                return llmService.generateSummaryWithHistory(conversation, historyMemory, null, null);
+            }
+
+            // 使用指定的模型ID调用LLM服务（支持历史记忆合并）
+            String summary = llmService.generateSummaryWithHistory(conversation, historyMemory, null, modelId);
+
+            if (StringUtils.isNotBlank(summary) && !summary.equals("服务暂不可用") && !summary.equals("总结生成失败")) {
+                return summary;
+            }
+
+            throw new RuntimeException("Java端LLM服务返回异常: " + summary);
+
+        } catch (Exception e) {
+            log.error("调用Java端LLM服务异常，agentId: {}, 错误: {}", agentId, e.getMessage());
+            throw e;
+        }
+    }
+
+    /**
+     * 调用Java端LLM服务进行智能总结
+     */
+    private String callJavaLLMForSummary(String conversation, String agentId) {
+        try {
+            // 获取智能体配置，从中提取记忆总结的模型ID
+            String modelId = getMemorySummaryModelId(agentId);
+
+            if (StringUtils.isBlank(modelId)) {
+                log.info("未找到记忆总结的LLM模型配置，使用默认LLM服务");
+                return llmService.generateSummary(conversation);
+            }
+
+            // 使用指定的模型ID调用LLM服务
+            String summary = llmService.generateSummaryWithModel(conversation, modelId);
+
+            if (StringUtils.isNotBlank(summary) && !summary.equals("服务暂不可用") && !summary.equals("总结生成失败")) {
+                return summary;
+            }
+
+            throw new RuntimeException("Java端LLM服务返回异常: " + summary);
+
+        } catch (Exception e) {
+            log.error("调用Java端LLM服务异常，agentId: {}, 错误: {}", agentId, e.getMessage());
+            throw e;
+        }
+    }
+
+    /**
+     * 获取记忆总结的LLM模型ID
+     */
+    private String getMemorySummaryModelId(String agentId) {
+        try {
+            if (StringUtils.isBlank(agentId)) {
+                return null;
+            }
+
+            // 获取智能体信息
+            AgentInfoVO agentInfo = agentService.getAgentById(agentId);
+            if (agentInfo == null) {
+                return null;
+            }
+
+            // 获取智能体的记忆模型ID
+            String memModelId = agentInfo.getMemModelId();
+            if (StringUtils.isBlank(memModelId)) {
+                return null;
+            }
+
+            // 获取记忆模型配置
+            ModelConfigEntity memModelConfig = modelConfigService.getModelByIdFromCache(memModelId);
+            if (memModelConfig == null || memModelConfig.getConfigJson() == null) {
+                return null;
+            }
+
+            // 从记忆模型配置中提取对应的LLM模型ID
+            Map<String, Object> configMap = memModelConfig.getConfigJson();
+            String llmModelId = (String) configMap.get("llm");
+
+            if (StringUtils.isBlank(llmModelId)) {
+                // 如果记忆模型没有配置独立的LLM，则使用智能体的默认LLM模型
+                return agentInfo.getLlmModelId();
+            }
+
+            return llmModelId;
+        } catch (Exception e) {
+            log.error("获取记忆总结LLM模型ID失败，agentId: {}, 错误: {}", agentId, e.getMessage());
+            return null;
+        }
+    }
+
+    /**
+     * 根据会话ID获取设备信息
+     */
+    private DeviceEntity getDeviceBySessionId(String sessionId) {
+        try {
+            // 查询该会话的第一条记录获取macAddress
+            QueryWrapper<AgentChatHistoryEntity> wrapper = new QueryWrapper<>();
+            wrapper.select("mac_address")
+                    .eq("session_id", sessionId)
+                    .last("LIMIT 1");
+
+            AgentChatHistoryEntity entity = agentChatHistoryService.getOne(wrapper);
+            if (entity != null && StringUtils.isNotBlank(entity.getMacAddress())) {
+                return deviceService.getDeviceByMacAddress(entity.getMacAddress());
+            }
+            return null;
+        } catch (Exception e) {
+            log.error("根据会话ID {} 查找设备信息失败: {}", sessionId, e.getMessage());
+            return null;
+        }
+    }
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/service/impl/AgentContextProviderServiceImpl.java

@@ -0,0 +1,35 @@
+package xiaozhi.modules.agent.service.impl;
+
+import org.springframework.stereotype.Service;
+
+import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
+
+import xiaozhi.common.service.impl.BaseServiceImpl;
+import xiaozhi.modules.agent.dao.AgentContextProviderDao;
+import xiaozhi.modules.agent.entity.AgentContextProviderEntity;
+import xiaozhi.modules.agent.service.AgentContextProviderService;
+
+@Service
+public class AgentContextProviderServiceImpl extends BaseServiceImpl<AgentContextProviderDao, AgentContextProviderEntity> implements AgentContextProviderService {
+
+    @Override
+    public AgentContextProviderEntity getByAgentId(String agentId) {
+        return baseDao.selectOne(new QueryWrapper<AgentContextProviderEntity>().eq("agent_id", agentId));
+    }
+
+    @Override
+    public void saveOrUpdateByAgentId(AgentContextProviderEntity entity) {
+        AgentContextProviderEntity exist = getByAgentId(entity.getAgentId());
+        if (exist != null) {
+            entity.setId(exist.getId());
+            updateById(entity);
+        } else {
+            insert(entity);
+        }
+    }
+
+    @Override
+    public void deleteByAgentId(String agentId) {
+        baseDao.delete(new QueryWrapper<AgentContextProviderEntity>().eq("agent_id", agentId));
+    }
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/service/impl/AgentMcpAccessPointServiceImpl.java

@@ -147,6 +147,7 @@ public class AgentMcpAccessPointServiceImpl implements AgentMcpAccessPointServic
                                     List<String> result = toolsList.stream()
                                             .map(tool -> (String) tool.get("name"))
                                             .filter(name -> name != null)
+                                            .sorted()
                                             .collect(Collectors.toList());
                                     log.info("成功获取MCP工具列表，智能体ID: {}, 工具数量: {}", id, result.size());
                                     return result;

main/manager-api/src/main/java/xiaozhi/modules/agent/service/impl/AgentPluginMappingServiceImpl.java

@@ -1,16 +1,26 @@
 package xiaozhi.modules.agent.service.impl;
 
+import java.util.ArrayList;
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
 
+import org.apache.commons.lang3.StringUtils;
 import org.springframework.stereotype.Service;
 
 import com.baomidou.mybatisplus.core.conditions.update.UpdateWrapper;
 import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
 
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import xiaozhi.common.utils.JsonUtils;
 import xiaozhi.modules.agent.dao.AgentPluginMappingMapper;
 import xiaozhi.modules.agent.entity.AgentPluginMapping;
 import xiaozhi.modules.agent.service.AgentPluginMappingService;
+import xiaozhi.modules.knowledge.entity.KnowledgeBaseEntity;
+import xiaozhi.modules.knowledge.service.KnowledgeBaseService;
+import xiaozhi.modules.model.entity.ModelConfigEntity;
+import xiaozhi.modules.model.service.ModelConfigService;
 
 /**
  * @description 针对表【ai_agent_plugin_mapping(Agent与插件的唯一映射表)】的数据库操作Service实现
@@ -18,13 +28,73 @@ import xiaozhi.modules.agent.service.AgentPluginMappingService;
  */
 @Service
 @RequiredArgsConstructor
+@Slf4j
 public class AgentPluginMappingServiceImpl extends ServiceImpl<AgentPluginMappingMapper, AgentPluginMapping>
         implements AgentPluginMappingService {
     private final AgentPluginMappingMapper agentPluginMappingMapper;
+    private final KnowledgeBaseService knowledgeBaseService;
+    private final ModelConfigService modelConfigService;
 
     @Override
     public List<AgentPluginMapping> agentPluginParamsByAgentId(String agentId) {
-        return agentPluginMappingMapper.selectPluginsByAgentId(agentId);
+        List<AgentPluginMapping> list = agentPluginMappingMapper.selectPluginsByAgentId(agentId);
+        Map<String, List<KnowledgeBaseEntity>> knowledgeBaseMap = new HashMap<>();
+        Map<String, ModelConfigEntity> modelConfigMap = new HashMap<>();
+        for (int i = list.size() - 1; i >= 0; i--) {
+            AgentPluginMapping mapping = list.get(i);
+            if (StringUtils.isBlank(mapping.getProviderCode())) {
+                // 查询知识库插件参数
+                KnowledgeBaseEntity knowledgeBaseEntity = knowledgeBaseService.selectById(mapping.getPluginId());
+                if (knowledgeBaseEntity == null) {
+                    list.remove(i);
+                    continue;
+                }
+                ModelConfigEntity modelConfigEntity = modelConfigService
+                        .getModelByIdFromCache(knowledgeBaseEntity.getRagModelId());
+                if (modelConfigEntity == null) {
+                    list.remove(i);
+                    continue;
+                }
+                List<KnowledgeBaseEntity> knowledgeBaseList = knowledgeBaseMap.get(modelConfigEntity.getModelCode());
+                if (knowledgeBaseList == null) {
+                    knowledgeBaseList = new ArrayList<>();
+                }
+                modelConfigMap.put(modelConfigEntity.getModelCode(), modelConfigEntity);
+                knowledgeBaseList.add(knowledgeBaseEntity);
+                knowledgeBaseMap.put(modelConfigEntity.getModelCode(), knowledgeBaseList);
+                list.remove(i);
+            }
+        }
+        if (knowledgeBaseMap.size() > 0) {
+            for (String pluginCode : knowledgeBaseMap.keySet()) {
+                List<KnowledgeBaseEntity> knowledgeBaseList = knowledgeBaseMap.get(pluginCode);
+                if (knowledgeBaseList == null || knowledgeBaseList.isEmpty()) {
+                    continue;
+                }
+
+                AgentPluginMapping agentPluginMapping = new AgentPluginMapping();
+                agentPluginMapping.setAgentId(agentId);
+                agentPluginMapping.setPluginId(pluginCode);
+                agentPluginMapping.setProviderCode("search_from_" + pluginCode);
+                agentPluginMapping.setId(Long.valueOf(list.size() + 1));
+
+                Map<String, Object> paramInfo = new HashMap<>(4);
+                ModelConfigEntity modelConfigEntity = modelConfigMap.get(pluginCode);
+                paramInfo.put("base_url", modelConfigEntity.getConfigJson().getStr("base_url"));
+                paramInfo.put("api_key", modelConfigEntity.getConfigJson().getStr("api_key"));
+                paramInfo.put("dataset_ids",
+                        knowledgeBaseList.stream().map(KnowledgeBaseEntity::getDatasetId).toList());
+
+                String description = "如果用户询问与【"
+                        + String.join(",", knowledgeBaseList.stream().map(KnowledgeBaseEntity::getName).toList())
+                        + "】涵盖的主体范围相关内容时应调用本方法，用于查询：" + String.join(",",
+                                knowledgeBaseList.stream().map(KnowledgeBaseEntity::getDescription).toList());
+                paramInfo.put("description", description);
+                agentPluginMapping.setParamInfo(JsonUtils.toJsonString(paramInfo));
+                list.add(agentPluginMapping);
+            }
+        }
+        return list;
     }
 
     @Override

main/manager-api/src/main/java/xiaozhi/modules/agent/service/impl/AgentServiceImpl.java

@@ -5,6 +5,7 @@ import java.util.Date;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.UUID;
 import java.util.function.Function;
 import java.util.stream.Collectors;
@@ -28,18 +29,26 @@ import xiaozhi.common.service.impl.BaseServiceImpl;
 import xiaozhi.common.user.UserDetail;
 import xiaozhi.common.utils.ConvertUtils;
 import xiaozhi.common.utils.JsonUtils;
+import xiaozhi.common.utils.ToolUtil;
 import xiaozhi.modules.agent.dao.AgentDao;
+import xiaozhi.modules.agent.dao.AgentTagDao;
 import xiaozhi.modules.agent.dto.AgentCreateDTO;
 import xiaozhi.modules.agent.dto.AgentDTO;
+import xiaozhi.modules.agent.dto.AgentTagDTO;
 import xiaozhi.modules.agent.dto.AgentUpdateDTO;
+import xiaozhi.modules.agent.entity.AgentContextProviderEntity;
 import xiaozhi.modules.agent.entity.AgentEntity;
 import xiaozhi.modules.agent.entity.AgentPluginMapping;
+import xiaozhi.modules.agent.entity.AgentTagEntity;
 import xiaozhi.modules.agent.entity.AgentTemplateEntity;
 import xiaozhi.modules.agent.service.AgentChatHistoryService;
+import xiaozhi.modules.agent.service.AgentContextProviderService;
 import xiaozhi.modules.agent.service.AgentPluginMappingService;
 import xiaozhi.modules.agent.service.AgentService;
+import xiaozhi.modules.agent.service.AgentTagService;
 import xiaozhi.modules.agent.service.AgentTemplateService;
 import xiaozhi.modules.agent.vo.AgentInfoVO;
+import xiaozhi.modules.device.entity.DeviceEntity;
 import xiaozhi.modules.device.service.DeviceService;
 import xiaozhi.modules.model.dto.ModelProviderDTO;
 import xiaozhi.modules.model.dto.VoiceDTO;
@@ -54,6 +63,7 @@ import xiaozhi.modules.timbre.service.TimbreService;
 @AllArgsConstructor
 public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> implements AgentService {
     private final AgentDao agentDao;
+    private final AgentTagDao agentTagDao;
     private final TimbreService timbreModelService;
     private final ModelConfigService modelConfigService;
     private final RedisUtils redisUtils;
@@ -62,6 +72,8 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp
     private final AgentChatHistoryService agentChatHistoryService;
     private final AgentTemplateService agentTemplateService;
     private final ModelProviderService modelProviderService;
+    private final AgentContextProviderService agentContextProviderService;
+    private final AgentTagService agentTagService;
 
     @Override
     public PageData<AgentEntity> adminAgentList(Map<String, Object> params) {
@@ -81,10 +93,17 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp
 
         if (agent.getMemModelId() != null && agent.getMemModelId().equals(Constant.MEMORY_NO_MEM)) {
             agent.setChatHistoryConf(Constant.ChatHistoryConfEnum.IGNORE.getCode());
-            if (agent.getChatHistoryConf() == null) {
-                agent.setChatHistoryConf(Constant.ChatHistoryConfEnum.RECORD_TEXT_AUDIO.getCode());
-            }
         }
+        if (agent.getChatHistoryConf() == null) {
+            agent.setChatHistoryConf(Constant.ChatHistoryConfEnum.RECORD_TEXT_AUDIO.getCode());
+        }
+
+        // 查询上下文源配置
+        AgentContextProviderEntity contextProviderEntity = agentContextProviderService.getByAgentId(id);
+        if (contextProviderEntity != null) {
+            agent.setContextProviders(contextProviderEntity.getContextProviders());
+        }
+
         // 无需额外查询插件列表，已通过SQL查询出来
         return agent;
     }
@@ -117,38 +136,91 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp
     }
 
     @Override
-    public List<AgentDTO> getUserAgents(Long userId) {
+    public List<AgentDTO> getUserAgents(Long userId, String keyword, String searchType) {
-        QueryWrapper<AgentEntity> wrapper = new QueryWrapper<>();
+        QueryWrapper<AgentEntity> queryWrapper = new QueryWrapper<>();
-        wrapper.eq("user_id", userId);
+        queryWrapper.eq("user_id", userId).orderByDesc("created_at");
-        List<AgentEntity> agents = agentDao.selectList(wrapper);
-        return agents.stream().map(agent -> {
-            AgentDTO dto = new AgentDTO();
-            dto.setId(agent.getId());
-            dto.setAgentName(agent.getAgentName());
-            dto.setSystemPrompt(agent.getSystemPrompt());
 
-            // 获取 TTS 模型名称
+        // 如果有搜索关键词，根据搜索类型添加相应的查询条件
-            dto.setTtsModelName(modelConfigService.getModelNameById(agent.getTtsModelId()));
+        if (StringUtils.isNotBlank(keyword)) {
+            if ("mac".equals(searchType)) {
+                // 按MAC地址搜索：先搜索设备，再获取对应的智能体
+                List<DeviceEntity> devices = Optional
+                        .ofNullable(deviceService.searchDevicesByMacAddress(keyword, userId)).orElseGet(ArrayList::new);
+                // 获取设备对应的智能体ID列表
+                List<String> agentIds = devices.stream()
+                        .map(DeviceEntity::getAgentId)
+                        .distinct()
+                        .collect(Collectors.toList());
+                if (ToolUtil.isNotEmpty(agentIds)) {
+                    queryWrapper.in("id", agentIds);
+                } else {
+                    return new ArrayList<>();
+                }
+            } else {
+                // 按名称搜索（默认）：同时搜索智能体名称和标签名
+                List<String> tagAgentIds = agentTagService.getAgentIdsByTagName(keyword);
+                if (ToolUtil.isNotEmpty(tagAgentIds)) {
+                    queryWrapper.and(wrapper -> wrapper
+                            .like("agent_name", keyword)
+                            .or()
+                            .in("id", tagAgentIds));
+                } else {
+                    queryWrapper.like("agent_name", keyword);
+                }
+            }
+        }
 
-            // 获取 LLM 模型名称
+        // 执行查询
-            dto.setLlmModelName(modelConfigService.getModelNameById(agent.getLlmModelId()));
+        List<AgentEntity> agentEntities = baseDao.selectList(queryWrapper);
 
-            // 获取 VLLM 模型名称
+        // 转换为DTO并设置所有必要字段
-            dto.setVllmModelName(modelConfigService.getModelNameById(agent.getVllmModelId()));
+        return agentEntities.stream().map(this::buildAgentDTO).collect(Collectors.toList());
+    }
 
-            // 获取记忆模型名称
+    /**
-            dto.setMemModelId(agent.getMemModelId());
+     * 将AgentEntity转换为AgentDTO
+     */
+    private AgentDTO buildAgentDTO(AgentEntity agent) {
+        AgentDTO dto = new AgentDTO();
+        dto.setId(agent.getId());
+        dto.setAgentName(agent.getAgentName());
+        dto.setSystemPrompt(agent.getSystemPrompt());
 
-            // 获取 TTS 音色名称
+        // 获取 TTS 模型名称
-            dto.setTtsVoiceName(timbreModelService.getTimbreNameById(agent.getTtsVoiceId()));
+        dto.setTtsModelName(modelConfigService.getModelNameById(agent.getTtsModelId()));
 
-            // 获取智能体最近的最后连接时长
+        // 获取 LLM 模型名称
-            dto.setLastConnectedAt(deviceService.getLatestLastConnectionTime(agent.getId()));
+        dto.setLlmModelName(modelConfigService.getModelNameById(agent.getLlmModelId()));
 
-            // 获取设备数量
+        // 获取 VLLM 模型名称
-            dto.setDeviceCount(getDeviceCountByAgentId(agent.getId()));
+        dto.setVllmModelName(modelConfigService.getModelNameById(agent.getVllmModelId()));
-            return dto;
+
-        }).collect(Collectors.toList());
+        // 获取记忆模型名称
+        dto.setMemModelId(agent.getMemModelId());
+
+        // 获取 TTS 音色名称
+        dto.setTtsVoiceName(timbreModelService.getTimbreNameById(agent.getTtsVoiceId()));
+
+        // 获取智能体最近的最后连接时长
+        dto.setLastConnectedAt(deviceService.getLatestLastConnectionTime(agent.getId()));
+
+        // 获取设备数量
+        dto.setDeviceCount(getDeviceCountByAgentId(agent.getId()));
+
+        // 获取标签列表
+        List<AgentTagEntity> tags = agentTagDao.selectByAgentId(agent.getId());
+        if (ToolUtil.isNotEmpty(tags)) {
+            dto.setTags(tags.stream().map(this::convertTagToDTO).collect(Collectors.toList()));
+        }
+
+        return dto;
+    }
+
+    private AgentTagDTO convertTagToDTO(AgentTagEntity entity) {
+        AgentTagDTO dto = new AgentTagDTO();
+        dto.setId(entity.getId());
+        dto.setTagName(entity.getTagName());
+        return dto;
     }
 
     @Override
@@ -237,6 +309,18 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp
         if (dto.getTtsVoiceId() != null) {
             existingEntity.setTtsVoiceId(dto.getTtsVoiceId());
         }
+        if (dto.getTtsLanguage() != null) {
+            existingEntity.setTtsLanguage(dto.getTtsLanguage());
+        }
+        if (dto.getTtsVolume() != null) {
+            existingEntity.setTtsVolume(dto.getTtsVolume());
+        }
+        if (dto.getTtsRate() != null) {
+            existingEntity.setTtsRate(dto.getTtsRate());
+        }
+        if (dto.getTtsPitch() != null) {
+            existingEntity.setTtsPitch(dto.getTtsPitch());
+        }
         if (dto.getMemModelId() != null) {
             existingEntity.setMemModelId(dto.getMemModelId());
         }
@@ -331,6 +415,14 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp
             agentChatHistoryService.deleteByAgentId(existingEntity.getId(), true, false);
         }
 
+        // 更新上下文源配置
+        if (dto.getContextProviders() != null) {
+            AgentContextProviderEntity contextEntity = new AgentContextProviderEntity();
+            contextEntity.setAgentId(agentId);
+            contextEntity.setContextProviders(dto.getContextProviders());
+            agentContextProviderService.saveOrUpdateByAgentId(contextEntity);
+        }
+
         boolean b = validateLLMIntentParams(dto.getLlmModelId(), dto.getIntentModelId());
         if (!b) {
             throw new RenException(ErrorCode.LLM_INTENT_PARAMS_MISMATCH);
@@ -395,7 +487,20 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp
             entity.setIntentModelId(template.getIntentModelId());
             entity.setSystemPrompt(template.getSystemPrompt());
             entity.setSummaryMemory(template.getSummaryMemory());
-            entity.setChatHistoryConf(template.getChatHistoryConf());
+
+            // 根据记忆模型类型设置默认的chatHistoryConf值
+            if (template.getMemModelId() != null) {
+                if (template.getMemModelId().equals("Memory_nomem")) {
+                    // 无记忆功能的模型，默认不记录聊天记录
+                    entity.setChatHistoryConf(0);
+                } else {
+                    // 有记忆功能的模型，默认记录文本和语音
+                    entity.setChatHistoryConf(2);
+                }
+            } else {
+                entity.setChatHistoryConf(template.getChatHistoryConf());
+            }
+
             entity.setLangCode(template.getLangCode());
             entity.setLanguage(template.getLanguage());
         }
@@ -437,4 +542,5 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp
         agentPluginMappingService.saveBatch(toInsert);
         return entity.getId();
     }
-}
+
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/service/impl/AgentTagServiceImpl.java

@@ -0,0 +1,198 @@
+package xiaozhi.modules.agent.service.impl;
+
+import java.util.ArrayList;
+import java.util.Date;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.UUID;
+import java.util.stream.Collectors;
+
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
+
+import lombok.AllArgsConstructor;
+import xiaozhi.common.exception.ErrorCode;
+import xiaozhi.common.exception.RenException;
+import xiaozhi.common.service.impl.BaseServiceImpl;
+import xiaozhi.modules.agent.dao.AgentTagDao;
+import xiaozhi.modules.agent.dao.AgentTagRelationDao;
+import xiaozhi.modules.agent.dto.AgentTagDTO;
+import xiaozhi.modules.agent.entity.AgentTagEntity;
+import xiaozhi.modules.agent.entity.AgentTagRelationEntity;
+import xiaozhi.modules.agent.service.AgentTagService;
+
+@Service
+@AllArgsConstructor
+public class AgentTagServiceImpl extends BaseServiceImpl<AgentTagDao, AgentTagEntity> implements AgentTagService {
+
+    private final AgentTagRelationDao agentTagRelationDao;
+
+    @Override
+    public AgentTagEntity saveTag(String tagName) {
+        if (tagName == null || tagName.trim().isEmpty()) {
+            throw new RenException(ErrorCode.AGENT_TAG_NAME_EMPTY);
+        }
+
+        QueryWrapper<AgentTagEntity> wrapper = new QueryWrapper<>();
+        wrapper.eq("tag_name", tagName);
+        wrapper.eq("deleted", 0);
+        AgentTagEntity existTag = baseDao.selectOne(wrapper);
+        if (existTag != null) {
+            return existTag;
+        }
+
+        AgentTagEntity tag = new AgentTagEntity();
+        tag.setId(UUID.randomUUID().toString().replace("-", ""));
+        tag.setTagName(tagName);
+        tag.setSort(0);
+        tag.setCreatedAt(new Date());
+        tag.setUpdatedAt(new Date());
+        tag.setDeleted(0);
+        baseDao.insert(tag);
+        return tag;
+    }
+
+    @Override
+    public void deleteTag(String tagId) {
+        AgentTagEntity tag = baseDao.selectById(tagId);
+        if (tag != null) {
+            tag.setDeleted(1);
+            tag.setUpdatedAt(new Date());
+            baseDao.updateById(tag);
+        }
+    }
+
+    @Override
+    public List<AgentTagDTO> getTagsByAgentId(String agentId) {
+        List<AgentTagEntity> tags = baseDao.selectByAgentId(agentId);
+        return tags.stream().map(this::convertToDTO).collect(Collectors.toList());
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void saveAgentTags(String agentId, List<String> tagIds, List<String> tagNames) {
+        agentTagRelationDao.deleteByAgentId(agentId);
+
+        List<AgentTagEntity> currentTags = baseDao.selectByAgentId(agentId);
+        List<String> currentTagNames = currentTags.stream()
+                .map(AgentTagEntity::getTagName)
+                .collect(Collectors.toList());
+
+        List<String> allTagIds = new ArrayList<>();
+        List<String> newTagNames = new ArrayList<>();
+
+        if (tagNames != null && !tagNames.isEmpty()) {
+            Set<String> addedTagNames = new HashSet<>();
+            for (String tagName : tagNames) {
+                if (tagName == null || tagName.trim().isEmpty()) {
+                    throw new RenException(ErrorCode.AGENT_TAG_NAME_EMPTY);
+                }
+
+                if (currentTagNames.contains(tagName) || addedTagNames.contains(tagName)) {
+                    throw new RenException(ErrorCode.AGENT_TAG_NAME_DUPLICATE);
+                }
+                addedTagNames.add(tagName);
+                newTagNames.add(tagName);
+            }
+        }
+
+        List<AgentTagEntity> existTags = new ArrayList<>();
+        if (!newTagNames.isEmpty()) {
+            existTags = baseDao.selectByTagNames(newTagNames);
+        }
+
+        Map<String, AgentTagEntity> existTagMap = existTags.stream()
+                .collect(Collectors.toMap(AgentTagEntity::getTagName, t -> t, (a, b) -> a));
+
+        List<AgentTagEntity> tagsToInsert = new ArrayList<>();
+        for (String tagName : newTagNames) {
+            AgentTagEntity existTag = existTagMap.get(tagName);
+            if (existTag != null) {
+                allTagIds.add(existTag.getId());
+            } else {
+                AgentTagEntity tag = new AgentTagEntity();
+                tag.setId(UUID.randomUUID().toString().replace("-", ""));
+                tag.setTagName(tagName);
+                tag.setSort(0);
+                tag.setDeleted(0);
+                tag.setCreatedAt(new Date());
+                tag.setUpdatedAt(new Date());
+                tagsToInsert.add(tag);
+            }
+        }
+
+        if (!tagsToInsert.isEmpty()) {
+            baseDao.batchInsert(tagsToInsert);
+            for (AgentTagEntity tag : tagsToInsert) {
+                allTagIds.add(tag.getId());
+            }
+        }
+
+        if (tagIds != null && !tagIds.isEmpty()) {
+            List<AgentTagEntity> tagIdEntities = baseDao.selectBatchIds(tagIds);
+            for (AgentTagEntity tag : tagIdEntities) {
+                if (tag != null && (currentTagNames.contains(tag.getTagName()) ||
+                        newTagNames.contains(tag.getTagName()))) {
+                    throw new RenException(ErrorCode.AGENT_TAG_NAME_DUPLICATE);
+                }
+            }
+            allTagIds.addAll(tagIds);
+        }
+
+        if (allTagIds.isEmpty()) {
+            return;
+        }
+
+        List<AgentTagRelationEntity> relations = new ArrayList<>();
+        Date now = new Date();
+        int sort = 0;
+        for (String tagId : allTagIds) {
+            AgentTagRelationEntity relation = new AgentTagRelationEntity();
+            relation.setId(UUID.randomUUID().toString().replace("-", ""));
+            relation.setAgentId(agentId);
+            relation.setTagId(tagId);
+            relation.setSort(sort++);
+            relation.setCreatedAt(now);
+            relation.setUpdatedAt(now);
+            relations.add(relation);
+        }
+        agentTagRelationDao.batchInsertRelation(relations);
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void deleteAgentTags(String agentId) {
+        agentTagRelationDao.deleteByAgentId(agentId);
+    }
+
+    @Override
+    public List<AgentTagDTO> getTagsByAgentIds(List<String> agentIds) {
+        if (agentIds == null || agentIds.isEmpty()) {
+            return List.of();
+        }
+        List<AgentTagEntity> tags = baseDao.selectByAgentIds(agentIds);
+        return tags.stream().map(this::convertToDTO).collect(Collectors.toList());
+    }
+
+    @Override
+    public List<AgentTagDTO> getAllTags() {
+        List<AgentTagEntity> tags = baseDao.selectAll();
+        return tags.stream().map(this::convertToDTO).collect(Collectors.toList());
+    }
+
+    @Override
+    public List<String> getAgentIdsByTagName(String tagName) {
+        return baseDao.selectAgentIdsByTagName(tagName);
+    }
+
+    private AgentTagDTO convertToDTO(AgentTagEntity entity) {
+        AgentTagDTO dto = new AgentTagDTO();
+        dto.setId(entity.getId());
+        dto.setTagName(entity.getTagName());
+        return dto;
+    }
+}

main/manager-api/src/main/java/xiaozhi/modules/agent/service/impl/AgentTemplateServiceImpl.java

@@ -45,6 +45,10 @@ public class AgentTemplateServiceImpl extends ServiceImpl<AgentTemplateDao, Agen
     @Override
     public void updateDefaultTemplateModelId(String modelType, String modelId) {
         modelType = modelType.toUpperCase();
+        // 如果是rag模型，不需要更新
+        if (modelType.equals("RAG")) {
+            return;
+        }
 
         UpdateWrapper<AgentTemplateEntity> wrapper = new UpdateWrapper<>();
         switch (modelType) {

main/manager-api/src/main/java/xiaozhi/modules/agent/vo/AgentInfoVO.java

@@ -5,6 +5,7 @@ import com.baomidou.mybatisplus.extension.handlers.JacksonTypeHandler;
 import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
+import xiaozhi.modules.agent.dto.ContextProviderDTO;
 import xiaozhi.modules.agent.entity.AgentEntity;
 import xiaozhi.modules.agent.entity.AgentPluginMapping;
 
@@ -21,4 +22,7 @@ public class AgentInfoVO extends AgentEntity
     @Schema(description = "插件列表Id")
     @TableField(typeHandler = JacksonTypeHandler.class)
     private List<AgentPluginMapping> functions;
+
+    @Schema(description = "上下文源配置")
+    private List<ContextProviderDTO> contextProviders;
 }

main/manager-api/src/main/java/xiaozhi/modules/config/service/impl/ConfigServiceImpl.java

@@ -20,10 +20,12 @@ import xiaozhi.common.redis.RedisUtils;
 import xiaozhi.common.utils.ConvertUtils;
 import xiaozhi.common.utils.JsonUtils;
 import xiaozhi.modules.agent.dao.AgentVoicePrintDao;
+import xiaozhi.modules.agent.entity.AgentContextProviderEntity;
 import xiaozhi.modules.agent.entity.AgentEntity;
 import xiaozhi.modules.agent.entity.AgentPluginMapping;
 import xiaozhi.modules.agent.entity.AgentTemplateEntity;
 import xiaozhi.modules.agent.entity.AgentVoicePrintEntity;
+import xiaozhi.modules.agent.service.AgentContextProviderService;
 import xiaozhi.modules.agent.service.AgentMcpAccessPointService;
 import xiaozhi.modules.agent.service.AgentPluginMappingService;
 import xiaozhi.modules.agent.service.AgentService;
@@ -53,6 +55,7 @@ public class ConfigServiceImpl implements ConfigService {
     private final TimbreService timbreService;
     private final AgentPluginMappingService agentPluginMappingService;
     private final AgentMcpAccessPointService agentMcpAccessPointService;
+    private final AgentContextProviderService agentContextProviderService;
     private final VoiceCloneService cloneVoiceService;
     private final AgentVoicePrintDao agentVoicePrintDao;
 
@@ -73,7 +76,7 @@ public class ConfigServiceImpl implements ConfigService {
         // 查询默认智能体
         AgentTemplateEntity agent = agentTemplateService.getDefaultTemplate();
         if (agent == null) {
-            throw new RenException("默认智能体未找到");
+            throw new RenException(ErrorCode.AGENT_TEMPLATE_NOT_FOUND);
         }
 
         // 构建模块配置
@@ -84,6 +87,10 @@ public class ConfigServiceImpl implements ConfigService {
                 null,
                 null,
                 null,
+                null,
+                null,
+                null,
+                null,
                 agent.getVadModelId(),
                 agent.getAsrModelId(),
                 null,
@@ -91,6 +98,7 @@ public class ConfigServiceImpl implements ConfigService {
                 null,
                 null,
                 null,
+                null,
                 result,
                 isCache);
 
@@ -102,6 +110,15 @@ public class ConfigServiceImpl implements ConfigService {
 
     @Override
     public Map<String, Object> getAgentModels(String macAddress, Map<String, String> selectedModule) {
+        // 检查是否为管理控制台请求
+        String redisKey = RedisKeys.getTmpRegisterMacKey(macAddress);
+        Object isAdminRequest = redisUtils.get(redisKey);
+        
+        if (isAdminRequest != null && "true".equals(isAdminRequest)) {
+            // 管理控制台请求，返回getConfig的结果
+            redisUtils.delete(redisKey); // 使用后清理
+            return (Map<String, Object>) getConfig(true);
+        }
         // 根据MAC地址查找设备
         DeviceEntity device = deviceService.getDeviceByMacAddress(macAddress);
         if (device == null) {
@@ -110,27 +127,36 @@ public class ConfigServiceImpl implements ConfigService {
             if (StringUtils.isNotBlank(cachedCode)) {
                 throw new RenException(ErrorCode.OTA_DEVICE_NEED_BIND, cachedCode);
             }
-            throw new RenException(ErrorCode.OTA_DEVICE_NOT_FOUND, "not found device");
+            throw new RenException(ErrorCode.OTA_DEVICE_NOT_FOUND);
         }
 
         // 获取智能体信息
         AgentEntity agent = agentService.getAgentById(device.getAgentId());
         if (agent == null) {
-            throw new RenException("智能体未找到");
+            throw new RenException(ErrorCode.AGENT_NOT_FOUND);
         }
         // 获取音色信息
         String voice = null;
         String referenceAudio = null;
         String referenceText = null;
+        String language = null;
         TimbreDetailsVO timbre = timbreService.get(agent.getTtsVoiceId());
         if (timbre != null) {
             voice = timbre.getTtsVoice();
             referenceAudio = timbre.getReferenceAudio();
             referenceText = timbre.getReferenceText();
+            // 优先使用用户选择的语言，如果没有则使用音色支持的第一个语言
+            if (StringUtils.isNotBlank(agent.getTtsLanguage())) {
+                language = agent.getTtsLanguage();
+            } else if (StringUtils.isNotBlank(timbre.getLanguages())) {
+                language = timbre.getLanguages().split("、")[0].trim();
+            }
         } else {
             VoiceCloneEntity voice_print = cloneVoiceService.selectById(agent.getTtsVoiceId());
             if (voice_print != null) {
                 voice = voice_print.getVoiceId();
+                // 优先使用用户选择的语言，如果没有则使用默认值
+                language = StringUtils.isNotBlank(agent.getTtsLanguage()) ? agent.getTtsLanguage() : "普通话";
             }
         }
         // 构建返回数据
@@ -150,11 +176,11 @@ public class ConfigServiceImpl implements ConfigService {
         }
         result.put("chat_history_conf", chatHistoryConf);
         // 如果客户端已实例化模型，则不返回
-        String alreadySelectedVadModelId = (String) selectedModule.get("VAD");
+        String alreadySelectedVadModelId = selectedModule.get("VAD");
         if (alreadySelectedVadModelId != null && alreadySelectedVadModelId.equals(agent.getVadModelId())) {
             agent.setVadModelId(null);
         }
-        String alreadySelectedAsrModelId = (String) selectedModule.get("ASR");
+        String alreadySelectedAsrModelId = selectedModule.get("ASR");
         if (alreadySelectedAsrModelId != null && alreadySelectedAsrModelId.equals(agent.getAsrModelId())) {
             agent.setAsrModelId(null);
         }
@@ -177,6 +203,13 @@ public class ConfigServiceImpl implements ConfigService {
             mcpEndpoint = mcpEndpoint.replace("/mcp/", "/call/");
             result.put("mcp_endpoint", mcpEndpoint);
         }
+        
+        // 获取上下文源配置
+        AgentContextProviderEntity contextProviderEntity = agentContextProviderService.getByAgentId(agent.getId());
+        if (contextProviderEntity != null && contextProviderEntity.getContextProviders() != null && !contextProviderEntity.getContextProviders().isEmpty()) {
+            result.put("context_providers", contextProviderEntity.getContextProviders());
+        }
+
         // 获取声纹信息
         buildVoiceprintConfig(agent.getId(), result);
 
@@ -188,6 +221,10 @@ public class ConfigServiceImpl implements ConfigService {
                 voice,
                 referenceAudio,
                 referenceText,
+                language,
+                agent.getTtsVolume(),
+                agent.getTtsRate(),
+                agent.getTtsPitch(),
                 agent.getVadModelId(),
                 agent.getAsrModelId(),
                 agent.getLlmModelId(),
@@ -195,6 +232,7 @@ public class ConfigServiceImpl implements ConfigService {
                 agent.getTtsModelId(),
                 agent.getMemModelId(),
                 agent.getIntentModelId(),
+                null,
                 result,
                 true);
 
@@ -281,7 +319,7 @@ public class ConfigServiceImpl implements ConfigService {
     private void buildVoiceprintConfig(String agentId, Map<String, Object> result) {
         try {
             // 获取声纹接口地址
-            String voiceprintUrl = sysParamsService.getValue("server.voice_print", true);
+            String voiceprintUrl = sysParamsService.getValue(Constant.SERVER_VOICE_PRINT, true);
             if (StringUtils.isBlank(voiceprintUrl) || "null".equals(voiceprintUrl)) {
                 return;
             }
@@ -364,6 +402,10 @@ public class ConfigServiceImpl implements ConfigService {
             String voice,
             String referenceAudio,
             String referenceText,
+            String language,
+            Integer ttsVolume,
+            Integer ttsRate,
+            Integer ttsPitch,
             String vadModelId,
             String asrModelId,
             String llmModelId,
@@ -371,12 +413,14 @@ public class ConfigServiceImpl implements ConfigService {
             String ttsModelId,
             String memModelId,
             String intentModelId,
+            String ragModelId,
             Map<String, Object> result,
             boolean isCache) {
         Map<String, String> selectedModule = new HashMap<>();
 
-        String[] modelTypes = { "VAD", "ASR", "TTS", "Memory", "Intent", "LLM", "VLLM" };
+        String[] modelTypes = { "VAD", "ASR", "TTS", "Memory", "Intent", "LLM", "VLLM", "RAG" };
-        String[] modelIds = { vadModelId, asrModelId, ttsModelId, memModelId, intentModelId, llmModelId, vllmModelId };
+        String[] modelIds = { vadModelId, asrModelId, ttsModelId, memModelId, intentModelId, llmModelId, vllmModelId,
+                ragModelId };
         String intentLLMModelId = null;
         String memLocalShortLLMModelId = null;
 
@@ -400,6 +444,14 @@ public class ConfigServiceImpl implements ConfigService {
                         ((Map<String, Object>) model.getConfigJson()).put("ref_audio", referenceAudio);
                     if (referenceText != null)
                         ((Map<String, Object>) model.getConfigJson()).put("ref_text", referenceText);
+                    if (language != null)
+                        ((Map<String, Object>) model.getConfigJson()).put("language", language);
+                    if (ttsVolume != null)
+                        ((Map<String, Object>) model.getConfigJson()).put("ttsVolume", ttsVolume);
+                    if (ttsRate != null)
+                        ((Map<String, Object>) model.getConfigJson()).put("ttsRate", ttsRate);
+                    if (ttsPitch != null)
+                        ((Map<String, Object>) model.getConfigJson()).put("ttsPitch", ttsPitch);
 
                     // 火山引擎声音克隆需要替换resource_id
                     Map<String, Object> map = (Map<String, Object>) model.getConfigJson();

main/manager-api/src/main/java/xiaozhi/modules/device/controller/DeviceController.java

@@ -1,14 +1,11 @@
 package xiaozhi.modules.device.controller;
 
 import java.util.List;
+import java.util.Map;
 
 import org.apache.commons.lang3.StringUtils;
 import org.apache.shiro.authz.annotation.RequiresPermissions;
 import org.springframework.beans.BeanUtils;
-import org.springframework.http.HttpEntity;
-import org.springframework.http.HttpHeaders;
-import org.springframework.http.HttpMethod;
-import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -16,9 +13,6 @@ import org.springframework.web.bind.annotation.PutMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
-import org.springframework.web.client.RestTemplate;
-
-import com.fasterxml.jackson.databind.ObjectMapper;
 
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
@@ -30,6 +24,7 @@ import xiaozhi.common.user.UserDetail;
 import xiaozhi.common.utils.Result;
 import xiaozhi.modules.device.dto.DeviceManualAddDTO;
 import xiaozhi.modules.device.dto.DeviceRegisterDTO;
+import xiaozhi.modules.device.dto.DeviceToolsCallReqDTO;
 import xiaozhi.modules.device.dto.DeviceUnBindDTO;
 import xiaozhi.modules.device.dto.DeviceUpdateDTO;
 import xiaozhi.modules.device.entity.DeviceEntity;
@@ -44,16 +39,11 @@ public class DeviceController {
     private final DeviceService deviceService;
     private final RedisUtils redisUtils;
     private final SysParamsService sysParamsService;
-    private final RestTemplate restTemplate;
-    private final ObjectMapper objectMapper;
 
-    public DeviceController(DeviceService deviceService, RedisUtils redisUtils, SysParamsService sysParamsService,
+    public DeviceController(DeviceService deviceService, RedisUtils redisUtils, SysParamsService sysParamsService) {
-            RestTemplate restTemplate, ObjectMapper objectMapper) {
         this.deviceService = deviceService;
         this.redisUtils = redisUtils;
         this.sysParamsService = sysParamsService;
-        this.restTemplate = restTemplate;
-        this.objectMapper = objectMapper;
     }
 
     @PostMapping("/bind/{agentId}/{deviceCode}")
@@ -69,13 +59,15 @@ public class DeviceController {
     public Result<String> registerDevice(@RequestBody DeviceRegisterDTO deviceRegisterDTO) {
         String macAddress = deviceRegisterDTO.getMacAddress();
         if (StringUtils.isBlank(macAddress)) {
-            return new Result<String>().error(ErrorCode.NOT_NULL, "mac地址不能为空");
+            return new Result<String>().error(ErrorCode.MCA_NOT_NULL);
         }
         // 生成六位验证码
-        String code = String.valueOf(Math.random()).substring(2, 8);
+        String code;
-        String key = RedisKeys.getDeviceCaptchaKey(code);
+        String key;
         String existsMac = null;
         do {
+            code = String.valueOf(Math.random()).substring(2, 8);
+            key = RedisKeys.getDeviceCaptchaKey(code);
             existsMac = (String) redisUtils.get(key);
         } while (StringUtils.isNotBlank(existsMac));
 
@@ -93,87 +85,16 @@ public class DeviceController {
     }
 
     @PostMapping("/bind/{agentId}")
-    @Operation(summary = "转发POST请求到MQTT网关")
+    @Operation(summary = "设备在线接口")
     @RequiresPermissions("sys:role:normal")
     public Result<String> forwardToMqttGateway(@PathVariable String agentId, @RequestBody String requestBody) {
         try {
-            // 从系统参数中获取MQTT网关地址
+            return new Result<String>().ok(deviceService.getDeviceOnlineData(agentId));
-            String mqttGatewayUrl = sysParamsService.getValue("server.mqtt_manager_api", true);
-            if (StringUtils.isBlank(mqttGatewayUrl) || "null".equals(mqttGatewayUrl)) {
-                return new Result<>();
-            }
-
-            // 获取当前用户的设备列表
-            UserDetail user = SecurityUser.getUser();
-            List<DeviceEntity> devices = deviceService.getUserDevices(user.getId(), agentId);
-
-            // 构建deviceIds数组
-            java.util.List<String> deviceIds = new java.util.ArrayList<>();
-            for (DeviceEntity device : devices) {
-                String macAddress = device.getMacAddress() != null ? device.getMacAddress() : "unknown";
-                String groupId = device.getBoard() != null ? device.getBoard() : "GID_default";
-
-                // 替换冒号为下划线
-                groupId = groupId.replace(":", "_");
-                macAddress = macAddress.replace(":", "_");
-
-                // 构建mqtt客户端ID格式：groupId@@@macAddress@@@macAddress
-                String mqttClientId = groupId + "@@@" + macAddress + "@@@" + macAddress;
-                deviceIds.add(mqttClientId);
-            }
-
-            // 构建完整的URL
-            String url = "http://" + mqttGatewayUrl + "/api/devices/status";
-
-            // 设置请求头
-            HttpHeaders headers = new HttpHeaders();
-            headers.set("Content-Type", "application/json");
-
-            // 生成Bearer令牌
-            String token = generateBearerToken();
-            if (token == null) {
-                return new Result<String>().error("令牌生成失败");
-            }
-            headers.set("Authorization", "Bearer " + token);
-
-            // 构建请求体JSON
-            String jsonBody = "{\"clientIds\":" + objectMapper.writeValueAsString(deviceIds) + "}";
-            HttpEntity<String> requestEntity = new HttpEntity<>(jsonBody, headers);
-
-            // 发送POST请求
-            ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.POST, requestEntity, String.class);
-
-            // 返回响应
-            return new Result<String>().ok(response.getBody());
         } catch (Exception e) {
             return new Result<String>().error("转发请求失败: " + e.getMessage());
         }
     }
 
-    private String generateBearerToken() {
-        try {
-            // 获取当前日期，格式为yyyy-MM-dd
-            String dateStr = java.time.LocalDate.now()
-                    .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd"));
-
-            // 获取MQTT签名密钥
-            String signatureKey = sysParamsService.getValue("server.mqtt_signature_key", false);
-            if (StringUtils.isBlank(signatureKey)) {
-                return null;
-            }
-
-            // 将日期字符串与MQTT_SIGNATURE_KEY连接
-            String tokenContent = dateStr + signatureKey;
-
-            // 对连接后的字符串进行SHA256哈希计算
-            String token = org.apache.commons.codec.digest.DigestUtils.sha256Hex(tokenContent);
-
-            return token;
-        } catch (Exception e) {
-            return null;
-        }
-    }
-
     @PostMapping("/unbind")
     @Operation(summary = "解绑设备")
     @RequiresPermissions("sys:role:normal")
@@ -209,62 +130,33 @@ public class DeviceController {
         return new Result<>();
     }
 
-    @PostMapping("/commands/{deviceId}")
+    @PostMapping("/tools/list/{deviceId}")
-    @Operation(summary = "发送设备指令")
+    @Operation(summary = "获取设备工具列表")
     @RequiresPermissions("sys:role:normal")
-    public Result<String> sendDeviceCommand(@PathVariable String deviceId, @RequestBody String command) {
+    public Result<Object> getDeviceTools(@PathVariable String deviceId) {
-        try {
+        Object toolsData = deviceService.getDeviceTools(deviceId);
-            // 从系统参数中获取MQTT网关地址
+        if (toolsData == null) {
-            String mqttGatewayUrl = sysParamsService.getValue("server.mqtt_manager_api", true);
+            return new Result<Object>().error(ErrorCode.DEVICE_NOT_EXIST);
-            if (StringUtils.isBlank(mqttGatewayUrl) || "null".equals(mqttGatewayUrl)) {
-                return new Result<String>().error("MQTT网关地址未配置");
-            }
-
-            // 构建完整的URL
-            // 获取设备信息以构建mqttClientId
-            DeviceEntity deviceById = deviceService.selectById(deviceId);
-
-            if (!deviceById.getUserId().equals(SecurityUser.getUser().getId())) {
-                return new Result<String>().error("设备不存在");
-            }
-            String macAddress = deviceById != null ? deviceById.getMacAddress() : "unknown";
-            String groupId = deviceById != null ? deviceById.getBoard() : null;
-            if (groupId == null) {
-                groupId = "GID_default";
-            }
-            groupId = groupId.replace(":", "_");
-            macAddress = macAddress.replace(":", "_");
-
-            // 拼接为groupId@@@macAddress@@@deviceId格式
-            String mqttClientId = groupId + "@@@" + macAddress + "@@@" + macAddress;
-
-            String url = "http://" + mqttGatewayUrl + "/api/commands/" + mqttClientId;
-
-            // 设置请求头
-            HttpHeaders headers = new HttpHeaders();
-            headers.set("Content-Type", "application/json");
-
-            // 生成Bearer令牌
-            String dateStr = java.time.LocalDate.now()
-                    .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd"));
-            String signatureKey = sysParamsService.getValue("server.mqtt_signature_key", false);
-            if (StringUtils.isBlank(signatureKey)) {
-                return new Result<String>().error("MQTT签名密钥未配置");
-            }
-            String tokenContent = dateStr + signatureKey;
-            String token = org.apache.commons.codec.digest.DigestUtils.sha256Hex(tokenContent);
-            headers.set("Authorization", "Bearer " + token);
-
-            // 构建请求体
-            HttpEntity<String> requestEntity = new HttpEntity<>(command, headers);
-
-            // 发送POST请求
-            ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.POST, requestEntity, String.class);
-
-            // 返回响应
-            return new Result<String>().ok(response.getBody());
-        } catch (Exception e) {
-            return new Result<String>().error("发送指令失败: " + e.getMessage());
         }
+
+        return new Result<Object>().ok(toolsData);
+    }
+
+    @PostMapping("/tools/call/{deviceId}")
+    @Operation(summary = "调用设备工具")
+    @RequiresPermissions("sys:role:normal")
+    public Result<Object> callDeviceTool(@PathVariable String deviceId,
+            @Valid @RequestBody DeviceToolsCallReqDTO request) {
+        String toolName = request.getName();
+        Map<String, Object> arguments = request.getArguments();
+
+        Object result = deviceService.callDeviceTool(deviceId, toolName, arguments);
+        if (result == null) {
+            return new Result<Object>().error(ErrorCode.DEVICE_NOT_EXIST);
+        }
+
+        Result<Object> response = new Result<Object>();
+        response.setMsg("Tools called successfully");
+        return response.ok(result);
     }
 }

main/manager-api/src/main/java/xiaozhi/modules/device/controller/OTAMagController.java

@@ -7,7 +7,9 @@ import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
+import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.UUID;
 
 import org.apache.commons.lang3.StringUtils;
@@ -36,6 +38,7 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import xiaozhi.common.constant.Constant;
+import xiaozhi.common.exception.ErrorCode;
 import xiaozhi.common.page.PageData;
 import xiaozhi.common.redis.RedisKeys;
 import xiaozhi.common.redis.RedisUtils;
@@ -43,8 +46,11 @@ import xiaozhi.common.utils.Result;
 import xiaozhi.common.validator.ValidatorUtils;
 import xiaozhi.modules.device.entity.OtaEntity;
 import xiaozhi.modules.device.service.OtaService;
+import xiaozhi.modules.security.user.SecurityUser;
+import xiaozhi.modules.sys.enums.SuperAdminEnum;
+import xiaozhi.modules.sys.service.SysParamsService;
 
-@Tag(name = "设备管理", description = "OTA 相关接口")
+@Tag(name = "固件升级管理", description = "OTA 相关接口")
 @Slf4j
 @RestController
 @RequiredArgsConstructor
@@ -53,6 +59,7 @@ public class OTAMagController {
     private static final Logger logger = LoggerFactory.getLogger(OTAController.class);
     private final OtaService otaService;
     private final RedisUtils redisUtils;
+    private final SysParamsService sysParamsService;
 
     @GetMapping
     @Operation(summary = "分页查询 OTA 固件信息")
@@ -145,15 +152,11 @@ public class OTAMagController {
 
         // 检查下载次数
         String downloadCountKey = RedisKeys.getOtaDownloadCountKey(uuid);
-        Integer downloadCount = (Integer) redisUtils.get(downloadCountKey);
+        Integer downloadCount = (Integer) Optional.ofNullable(redisUtils.get(downloadCountKey)).orElse(0);
-        if (downloadCount == null) {
-            downloadCount = 0;
-        }
 
         // 如果下载次数超过3次，返回404
         if (downloadCount >= 3) {
-            redisUtils.delete(downloadCountKey);
+            redisUtils.delete(List.of(downloadCountKey, RedisKeys.getOtaIdKey(uuid)));
-            redisUtils.delete(RedisKeys.getOtaIdKey(uuid));
             logger.warn("Download limit exceeded for UUID: {}", uuid);
             return ResponseEntity.notFound().build();
         }
@@ -162,7 +165,17 @@ public class OTAMagController {
 
         try {
             // 获取固件信息
-            OtaEntity otaEntity = otaService.selectById(id);
+            OtaEntity otaEntity = null;
+            if (id.indexOf("file:") == 0) {
+                id = id.substring(5);
+                otaEntity = new OtaEntity();
+                otaEntity.setFirmwarePath(id);
+                otaEntity.setType("assets");
+                otaEntity.setVersion("1.0.0");
+            } else {
+                otaEntity = otaService.selectById(id);
+            }
+
             if (otaEntity == null || StringUtils.isBlank(otaEntity.getFirmwarePath())) {
                 logger.warn("Firmware not found or path is empty for ID: {}", id);
                 return ResponseEntity.notFound().build();
@@ -170,6 +183,7 @@ public class OTAMagController {
 
             // 获取文件路径 - 确保路径是绝对路径或正确的相对路径
             String firmwarePath = otaEntity.getFirmwarePath();
+            String originalFilename = otaEntity.getType() + "_" + otaEntity.getVersion();
             Path path;
 
             // 检查是否是绝对路径
@@ -203,7 +217,7 @@ public class OTAMagController {
             byte[] fileContent = Files.readAllBytes(path);
 
             // 设置响应头
-            String originalFilename = otaEntity.getType() + "_" + otaEntity.getVersion();
+
             if (firmwarePath.contains(".")) {
                 String extension = firmwarePath.substring(firmwarePath.lastIndexOf("."));
                 originalFilename += extension;
@@ -279,6 +293,42 @@ public class OTAMagController {
         }
     }
 
+    @PostMapping("/uploadAssetsBin")
+    @Operation(summary = "上传资源固件文件")
+    @RequiresPermissions("sys:role:normal")
+    public Result<String> uploadAssetsBin(@RequestParam("file") MultipartFile file) {
+        String otaUrl = sysParamsService.getValue(Constant.SERVER_OTA, true);
+        if (StringUtils.isBlank(otaUrl) || otaUrl.equals("null")) {
+            return new Result<String>().error(ErrorCode.OTA_URL_EMPTY);
+        }
+        logger.info("username:{},uploadAssetsBin size: {}", SecurityUser.getUser().getUsername(), file.getSize());
+        // 验证文件大小 (资源固件最大20MB)
+        if (file.getSize() > 20 * 1024 * 1024) {
+            return new Result<String>().error(ErrorCode.VOICE_CLONE_AUDIO_TOO_LARGE);
+        }
+        // 普通用户只能每天上传50次
+        if (SecurityUser.getUser().getSuperAdmin() == SuperAdminEnum.NO.value()) {
+            String uploadCountKey = RedisKeys.getOtaUploadCountKey(SecurityUser.getUser().getId());
+            Integer uploadCount = (Integer) Optional.ofNullable(redisUtils.get(uploadCountKey)).orElse(0);
+            if (uploadCount >= 50) {
+                return new Result<String>().error(ErrorCode.OTA_UPLOAD_COUNT_EXCEED);
+            }
+            // 增加上传次数
+            redisUtils.increment(RedisKeys.getOtaUploadCountKey(SecurityUser.getUser().getId()),
+                    RedisUtils.DEFAULT_EXPIRE);
+        }
+        Result<String> result = uploadFirmware(file);
+
+        // 生成资源文件路径
+        if (StringUtils.isNotBlank(result.getData())) {
+            String uuid = UUID.randomUUID().toString();
+            redisUtils.set(RedisKeys.getOtaIdKey(uuid), "file:" + result.getData());
+            String downloadUrl = otaUrl.replace("/ota/", "/otaMag/download/") + uuid;
+            result.setData(downloadUrl);
+        }
+        return result;
+    }
+
     private String calculateMD5(MultipartFile file) throws IOException, NoSuchAlgorithmException {
         MessageDigest md = MessageDigest.getInstance("MD5");
         byte[] digest = md.digest(file.getBytes());

main/manager-api/src/main/java/xiaozhi/modules/device/dto/DeviceToolsCallReqDTO.java

@@ -0,0 +1,15 @@
+package xiaozhi.modules.device.dto;
+
+import java.util.Map;
+
+import jakarta.validation.constraints.NotBlank;
+import lombok.Data;
+
+@Data
+public class DeviceToolsCallReqDTO {
+
+    @NotBlank(message = "工具名称不能为空")
+    private String name;
+
+    private Map<String, Object> arguments;
+}

main/manager-api/src/main/java/xiaozhi/modules/device/service/DeviceService.java

@@ -2,17 +2,22 @@ package xiaozhi.modules.device.service;
 
 import java.util.Date;
 import java.util.List;
+import java.util.Map;
 
 import xiaozhi.common.page.PageData;
 import xiaozhi.common.service.BaseService;
+import xiaozhi.modules.device.dto.DeviceManualAddDTO;
 import xiaozhi.modules.device.dto.DevicePageUserDTO;
 import xiaozhi.modules.device.dto.DeviceReportReqDTO;
 import xiaozhi.modules.device.dto.DeviceReportRespDTO;
-import xiaozhi.modules.device.dto.DeviceManualAddDTO;
 import xiaozhi.modules.device.entity.DeviceEntity;
 import xiaozhi.modules.device.vo.UserShowDeviceListVO;
 
 public interface DeviceService extends BaseService<DeviceEntity> {
+    /**
+     * 获取设备在线数据
+     */
+    String getDeviceOnlineData(String agentId);
 
     /**
      * 检查设备是否激活
@@ -83,6 +88,7 @@ public interface DeviceService extends BaseService<DeviceEntity> {
 
     /**
      * 获取这个智能体设备理的最近的最后连接时间
+     * 
      * @param agentId 智能体id
      * @return 返回设备最近的最后连接时间
      */
@@ -98,4 +104,33 @@ public interface DeviceService extends BaseService<DeviceEntity> {
      */
     void updateDeviceConnectionInfo(String agentId, String deviceId, String appVersion);
 
+    /**
+     * 生成WebSocket认证token
+     *
+     * @param clientId 客户端ID
+     * @param username 用户名(通常为deviceId)
+     * @return 认证token字符串
+     * @throws Exception 生成token时的异常
+     */
+    String generateWebSocketToken(String clientId, String username) throws Exception;
+
+    /**
+     * 根据MAC地址搜索设备
+     *
+     * @param macAddress MAC地址关键词
+     * @param userId     用户ID
+     * @return 设备列表
+     */
+    List<DeviceEntity> searchDevicesByMacAddress(String macAddress, Long userId);
+
+    /**
+     * 获取设备工具列表
+     */
+    Object getDeviceTools(String deviceId);
+
+    /**
+     * 调用设备工具
+     */
+    Object callDeviceTool(String deviceId, String toolName, Map<String, Object> arguments);
+
 }

main/manager-api/src/main/java/xiaozhi/modules/device/service/impl/DeviceServiceImpl.java

@@ -1,14 +1,20 @@
 package xiaozhi.modules.device.service.impl;
 
 import java.nio.charset.StandardCharsets;
+import java.security.InvalidKeyException;
+import java.security.NoSuchAlgorithmException;
 import java.time.Instant;
+import java.util.ArrayList;
 import java.util.Base64;
 import java.util.Date;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
+import java.util.Set;
 import java.util.TimeZone;
 import java.util.UUID;
+import java.util.stream.Collectors;
 
 import javax.crypto.Mac;
 import javax.crypto.spec.SecretKeySpec;
@@ -24,7 +30,18 @@ import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
 import com.baomidou.mybatisplus.core.conditions.update.UpdateWrapper;
 import com.baomidou.mybatisplus.core.metadata.IPage;
 
+import cn.hutool.core.date.DatePattern;
+import cn.hutool.core.date.DateUtil;
+import cn.hutool.core.map.MapUtil;
 import cn.hutool.core.util.RandomUtil;
+import cn.hutool.core.util.StrUtil;
+import cn.hutool.crypto.digest.DigestUtil;
+import cn.hutool.http.ContentType;
+import cn.hutool.http.Header;
+import cn.hutool.http.HttpRequest;
+import cn.hutool.json.JSONArray;
+import cn.hutool.json.JSONObject;
+import cn.hutool.json.JSONUtil;
 import jakarta.servlet.http.HttpServletRequest;
 import lombok.AllArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -38,6 +55,7 @@ import xiaozhi.common.service.impl.BaseServiceImpl;
 import xiaozhi.common.user.UserDetail;
 import xiaozhi.common.utils.ConvertUtils;
 import xiaozhi.common.utils.DateUtils;
+import xiaozhi.common.utils.ToolUtil;
 import xiaozhi.modules.device.dao.DeviceDao;
 import xiaozhi.modules.device.dto.DeviceManualAddDTO;
 import xiaozhi.modules.device.dto.DevicePageUserDTO;
@@ -86,16 +104,16 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
         if (StringUtils.isBlank(activationCode)) {
             throw new RenException(ErrorCode.ACTIVATION_CODE_EMPTY);
         }
-        String deviceKey = "ota:activation:code:" + activationCode;
+        String deviceKey = RedisKeys.getOtaActivationCode(activationCode);
         Object cacheDeviceId = redisUtils.get(deviceKey);
-        if (cacheDeviceId == null) {
+        if (ToolUtil.isEmpty(cacheDeviceId)) {
             throw new RenException(ErrorCode.ACTIVATION_CODE_ERROR);
         }
         String deviceId = (String) cacheDeviceId;
         String safeDeviceId = deviceId.replace(":", "_").toLowerCase();
-        String cacheDeviceKey = String.format("ota:activation:data:%s", safeDeviceId);
+        String cacheDeviceKey = RedisKeys.getOtaDeviceActivationInfo(safeDeviceId);
         Map<String, Object> cacheMap = (Map<String, Object>) redisUtils.get(cacheDeviceKey);
-        if (cacheMap == null) {
+        if (ToolUtil.isEmpty(cacheMap)) {
             throw new RenException(ErrorCode.ACTIVATION_CODE_ERROR);
         }
         String cachedCode = (String) cacheMap.get("activation_code");
@@ -131,19 +149,56 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
         deviceEntity.setLastConnectedAt(currentTime);
         deviceDao.insert(deviceEntity);
 
-        // 清理redis缓存
+        // 清理redis缓存、清除智能体设备数量缓存
-        redisUtils.delete(cacheDeviceKey);
+        redisUtils.delete(List.of(cacheDeviceKey, deviceKey, RedisKeys.getAgentDeviceCountById(agentId)));
-        redisUtils.delete(deviceKey);
-
-        // 添加：清除智能体设备数量缓存
-        redisUtils.delete(RedisKeys.getAgentDeviceCountById(agentId));
-
         return true;
     }
 
+    /**
+     * 获取设备在线数据
+     */
     @Override
-    public DeviceReportRespDTO checkDeviceActive(String macAddress, String clientId,
+    public String getDeviceOnlineData(String agentId) {
-            DeviceReportReqDTO deviceReport) {
+        // 从系统参数中获取MQTT网关地址
+        String mqttGatewayUrl = sysParamsService.getValue("server.mqtt_manager_api", true);
+        if (StringUtils.isBlank(mqttGatewayUrl) || "null".equals(mqttGatewayUrl)) {
+            return "";
+        }
+        // 构建完整的URL
+        String url = StrUtil.format("http://{}/api/devices/status", mqttGatewayUrl);
+
+        // 获取当前用户的设备列表
+        UserDetail user = SecurityUser.getUser();
+        List<DeviceEntity> devices = getUserDevices(user.getId(), agentId);
+
+        // 构建deviceIds数组
+        Set<String> deviceIds = devices.stream().map(o -> {
+            String macAddress = Optional.ofNullable(o.getMacAddress()).orElse("unknown").replace(":", "_");
+            String groupId = Optional.ofNullable(o.getBoard()).orElse("GID_default").replace(":", "_");
+            return StrUtil.format("{}@@@{}@@@{}", groupId, macAddress, macAddress);
+        }).collect(Collectors.toSet());
+
+        // 构建请求入参
+        Map<String, Set<String>> params = MapUtil
+                .builder(new HashMap<String, Set<String>>())
+                .put("clientIds", deviceIds).build();
+
+        if (ToolUtil.isNotEmpty(deviceIds)) {
+            // 发送请求
+            String resultMessage = HttpRequest.post(url)
+                    .header(Header.CONTENT_TYPE, ContentType.JSON.getValue())
+                    .header(Header.AUTHORIZATION, "Bearer " + generateBearerToken())
+                    .body(JSONUtil.toJsonStr(params))
+                    .timeout(10000) // 超时，毫秒
+                    .execute().body();
+            return resultMessage;
+        }
+        // 返回响应
+        return "";
+    }
+
+    @Override
+    public DeviceReportRespDTO checkDeviceActive(String macAddress, String clientId, DeviceReportReqDTO deviceReport) {
         DeviceReportRespDTO response = new DeviceReportRespDTO();
         response.setServer_time(buildServerTime());
 
@@ -169,7 +224,22 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
         DeviceReportRespDTO.Websocket websocket = new DeviceReportRespDTO.Websocket();
         // 从系统参数获取WebSocket URL，如果未配置则使用默认值
         String wsUrl = sysParamsService.getValue(Constant.SERVER_WEBSOCKET, true);
-        websocket.setToken("");
+
+        // 检查是否启用认证并生成token
+        String authEnabled = sysParamsService.getValue(Constant.SERVER_AUTH_ENABLED, true);
+        if ("true".equalsIgnoreCase(authEnabled)) {
+            try {
+                // 生成token
+                String token = generateWebSocketToken(clientId, macAddress);
+                websocket.setToken(token);
+            } catch (Exception e) {
+                log.error("生成WebSocket token失败: {}", e.getMessage());
+                websocket.setToken("");
+            }
+        } else {
+            websocket.setToken("");
+        }
+
         if (StringUtils.isBlank(wsUrl) || wsUrl.equals("null")) {
             log.error("WebSocket地址未配置，请登录智控台，在参数管理找到【server.websocket】配置");
             wsUrl = "ws://xiaozhi.server.com:8000/xiaozhi/v1/";
@@ -189,7 +259,7 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
 
         // 添加MQTT UDP配置
         // 从系统参数获取MQTT Gateway地址，仅在配置有效时使用
-        String mqttUdpConfig = sysParamsService.getValue(Constant.SERVER_MQTT_GATEWAY, false);
+        String mqttUdpConfig = sysParamsService.getValue(Constant.SERVER_MQTT_GATEWAY, true);
         if (mqttUdpConfig != null && !mqttUdpConfig.equals("null") && !mqttUdpConfig.isEmpty()) {
             try {
                 String groupId = deviceById != null && deviceById.getBoard() != null ? deviceById.getBoard()
@@ -339,8 +409,7 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
 
     private String getDeviceCacheKey(String deviceId) {
         String safeDeviceId = deviceId.replace(":", "_").toLowerCase();
-        String dataKey = String.format("ota:activation:data:%s", safeDeviceId);
+        return RedisKeys.getOtaDeviceActivationInfo(safeDeviceId);
-        return dataKey;
     }
 
     public DeviceReportRespDTO.Activation buildActivation(String deviceId, DeviceReportReqDTO deviceReport) {
@@ -379,7 +448,7 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
             redisUtils.set(dataKey, dataMap);
 
             // 写入反查激活码 key
-            String codeKey = "ota:activation:code:" + newCode;
+            String codeKey = RedisKeys.getOtaActivationCode(newCode);
             redisUtils.set(codeKey, deviceId);
         }
         return code;
@@ -479,6 +548,14 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
         redisUtils.delete(RedisKeys.getAgentDeviceCountById(dto.getAgentId()));
     }
 
+    @Override
+    public List<DeviceEntity> searchDevicesByMacAddress(String macAddress, Long userId) {
+        QueryWrapper<DeviceEntity> wrapper = new QueryWrapper<>();
+        wrapper.like("mac_address", macAddress);
+        wrapper.eq("user_id", userId);
+        return deviceDao.selectList(wrapper);
+    }
+
     /**
      * 生成MQTT密码签名
      * 
@@ -494,6 +571,40 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
         return Base64.getEncoder().encodeToString(signature);
     }
 
+    /**
+     * 生成WebSocket认证token 遵循Python端AuthManager的实现逻辑：token = signature.timestamp
+     * 
+     * @param clientId 客户端ID
+     * @param username 用户名 (通常为deviceId/macAddress)
+     * @return 认证token字符串
+     */
+    public String generateWebSocketToken(String clientId, String username)
+            throws NoSuchAlgorithmException, InvalidKeyException {
+        // 从系统参数获取密钥
+        String secretKey = sysParamsService.getValue(Constant.SERVER_SECRET, false);
+        if (StringUtils.isBlank(secretKey)) {
+            throw new IllegalStateException("WebSocket认证密钥未配置(server.secret)");
+        }
+
+        // 获取当前时间戳(秒)
+        long timestamp = System.currentTimeMillis() / 1000;
+
+        // 构建签名内容: clientId|username|timestamp
+        String content = String.format("%s|%s|%d", clientId, username, timestamp);
+
+        // 生成HMAC-SHA256签名
+        Mac hmac = Mac.getInstance("HmacSHA256");
+        SecretKeySpec keySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
+        hmac.init(keySpec);
+        byte[] signature = hmac.doFinal(content.getBytes(StandardCharsets.UTF_8));
+
+        // Base64 URL-safe编码签名(去除填充符=)
+        String signatureBase64 = Base64.getUrlEncoder().withoutPadding().encodeToString(signature);
+
+        // 返回格式: signature.timestamp
+        return String.format("%s.%d", signatureBase64, timestamp);
+    }
+
     /**
      * 构建MQTT配置信息
      * 
@@ -504,7 +615,7 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
     private DeviceReportRespDTO.MQTT buildMqttConfig(String macAddress, String groupId)
             throws Exception {
         // 从环境变量或系统参数获取签名密钥
-        String signatureKey = sysParamsService.getValue("server.mqtt_signature_key", false);
+        String signatureKey = sysParamsService.getValue("server.mqtt_signature_key", true);
         if (StringUtils.isBlank(signatureKey)) {
             log.warn("缺少MQTT_SIGNATURE_KEY，跳过MQTT配置生成");
             return null;
@@ -547,4 +658,218 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
 
         return mqtt;
     }
+
+    /**
+     * 生成BearerToken
+     */
+    private String generateBearerToken() {
+        try {
+            String dateStr = DateUtil.format(new Date(), DatePattern.NORM_DATE_PATTERN);
+            String signatureKey = sysParamsService.getValue(Constant.SERVER_MQTT_SECRET, false);
+            if (ToolUtil.isEmpty(signatureKey)) {
+                return null;
+            }
+            return DigestUtil.sha256Hex(dateStr + signatureKey);
+        } catch (Exception e) {
+            return null;
+        }
+    }
+
+    @Override
+    public Object getDeviceTools(String deviceId) {
+        // 从系统参数中获取MQTT网关地址
+        String mqttGatewayUrl = sysParamsService.getValue("server.mqtt_manager_api", true);
+        if (StringUtils.isBlank(mqttGatewayUrl) || "null".equals(mqttGatewayUrl)) {
+            return null;
+        }
+
+        // 获取设备信息
+        DeviceEntity device = baseDao.selectById(deviceId);
+        if (device == null) {
+            return null;
+        }
+
+        // 检查设备是否属于当前用户
+        UserDetail user = SecurityUser.getUser();
+        if (!device.getUserId().equals(user.getId())) {
+            return null;
+        }
+
+        // 构建clientId
+        String macAddress = Optional.ofNullable(device.getMacAddress()).orElse("unknown").replace(":", "_");
+        String groupId = Optional.ofNullable(device.getBoard()).orElse("GID_default").replace(":", "_");
+        String clientId = StrUtil.format("{}@@@{}@@@{}", groupId, macAddress, macAddress);
+
+        // 构建完整的URL
+        String url = StrUtil.format("http://{}/api/commands/{}", mqttGatewayUrl, clientId);
+
+        // 存储所有工具列表
+        List<Object> allTools = new ArrayList<>();
+        String cursor = null;
+
+        // 循环获取分页数据
+        while (true) {
+            // 构建params
+            Map<String, Object> paramsMap = MapUtil.builder(new HashMap<String, Object>())
+                    .put("withUserTools", true)
+                    .build();
+            // 如果有cursor，添加到请求参数中
+            if (StringUtils.isNotBlank(cursor)) {
+                paramsMap.put("cursor", cursor);
+            }
+
+            // 构建请求体
+            Map<String, Object> payload = MapUtil
+                    .builder(new HashMap<String, Object>())
+                    .put("jsonrpc", "2.0")
+                    .put("id", 2)
+                    .put("method", "tools/list")
+                    .put("params", paramsMap)
+                    .build();
+
+            Map<String, Object> requestBody = MapUtil
+                    .builder(new HashMap<String, Object>())
+                    .put("type", "mcp")
+                    .put("payload", payload)
+                    .build();
+
+            // 发送请求
+            String resultMessage = HttpRequest.post(url)
+                    .header(Header.CONTENT_TYPE, ContentType.JSON.getValue())
+                    .header(Header.AUTHORIZATION, "Bearer " + generateBearerToken())
+                    .body(JSONUtil.toJsonStr(requestBody))
+                    .timeout(10000) // 超时，毫秒
+                    .execute().body();
+
+            // 解析响应
+            if (StringUtils.isBlank(resultMessage)) {
+                break;
+            }
+
+            JSONObject jsonObject = JSONUtil.parseObj(resultMessage);
+            if (!jsonObject.getBool("success", false)) {
+                break;
+            }
+
+            JSONObject data = jsonObject.getJSONObject("data");
+            if (data == null) {
+                break;
+            }
+
+            // 获取当前页的工具列表
+            JSONArray tools = data.getJSONArray("tools");
+            if (tools != null && !tools.isEmpty()) {
+                allTools.addAll(tools);
+            }
+
+            // 获取下一页的cursor
+            String nextCursor = data.getStr("nextCursor");
+            if (StringUtils.isBlank(nextCursor)) {
+                // 没有下一页了
+                break;
+            }
+            cursor = nextCursor;
+        }
+
+        // 构建返回结果
+        if (allTools.isEmpty()) {
+            return null;
+        }
+
+        Map<String, Object> resultData = new HashMap<>();
+        resultData.put("tools", allTools);
+        return resultData;
+    }
+
+    @Override
+    public Object callDeviceTool(String deviceId, String toolName, Map<String, Object> arguments) {
+        // 从系统参数中获取MQTT网关地址
+        String mqttGatewayUrl = sysParamsService.getValue("server.mqtt_manager_api", true);
+        if (StringUtils.isBlank(mqttGatewayUrl) || "null".equals(mqttGatewayUrl)) {
+            return null;
+        }
+
+        // 获取设备信息
+        DeviceEntity device = baseDao.selectById(deviceId);
+        if (device == null) {
+            return null;
+        }
+
+        // 检查设备是否属于当前用户
+        UserDetail user = SecurityUser.getUser();
+        if (!device.getUserId().equals(user.getId())) {
+            return null;
+        }
+
+        // 构建clientId
+        String macAddress = Optional.ofNullable(device.getMacAddress()).orElse("unknown").replace(":", "_");
+        String groupId = Optional.ofNullable(device.getBoard()).orElse("GID_default").replace(":", "_");
+        String clientId = StrUtil.format("{}@@@{}@@@{}", groupId, macAddress, macAddress);
+
+        // 构建完整的URL
+        String url = StrUtil.format("http://{}/api/commands/{}", mqttGatewayUrl, clientId);
+
+        // 构建请求体
+        Map<String, Object> params = MapUtil
+                .builder(new HashMap<String, Object>())
+                .put("name", toolName)
+                .put("arguments", arguments)
+                .build();
+
+        Map<String, Object> payload = MapUtil
+                .builder(new HashMap<String, Object>())
+                .put("jsonrpc", "2.0")
+                .put("id", 2)
+                .put("method", "tools/call")
+                .put("params", params)
+                .build();
+
+        Map<String, Object> requestBody = MapUtil
+                .builder(new HashMap<String, Object>())
+                .put("type", "mcp")
+                .put("payload", payload)
+                .build();
+
+        // 发送请求
+        String resultMessage = HttpRequest.post(url)
+                .header(Header.CONTENT_TYPE, ContentType.JSON.getValue())
+                .header(Header.AUTHORIZATION, "Bearer " + generateBearerToken())
+                .body(JSONUtil.toJsonStr(requestBody))
+                .timeout(10000) // 超时，毫秒
+                .execute().body();
+
+        // 解析响应
+        if (StringUtils.isNotBlank(resultMessage)) {
+            cn.hutool.json.JSONObject jsonObject = JSONUtil.parseObj(resultMessage);
+            if (jsonObject.getBool("success", false)) {
+                cn.hutool.json.JSONObject data = jsonObject.getJSONObject("data");
+                if (data != null) {
+                    cn.hutool.json.JSONArray content = data.getJSONArray("content");
+                    if (content != null && content.size() > 0) {
+                        cn.hutool.json.JSONObject firstContent = content.getJSONObject(0);
+                        if (firstContent != null && "text".equals(firstContent.getStr("type"))) {
+                            String text = firstContent.getStr("text");
+                            if (StringUtils.isNotBlank(text)) {
+                                String trimmedText = text.trim();
+                                if (trimmedText.startsWith("{") || trimmedText.startsWith("[")) {
+                                    try {
+                                        return JSONUtil.parseObj(trimmedText);
+                                    } catch (Exception e) {
+                                        return trimmedText;
+                                    }
+                                } else if ("true".equals(trimmedText)) {
+                                    return true;
+                                } else if ("false".equals(trimmedText)) {
+                                    return false;
+                                } else {
+                                    return trimmedText;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        return null;
+    }
 }

main/manager-api/src/main/java/xiaozhi/modules/device/service/impl/OtaServiceImpl.java

@@ -66,7 +66,7 @@ public class OtaServiceImpl extends BaseServiceImpl<OtaDao, OtaEntity> implement
         // 同类固件只保留最新的一条
         List<OtaEntity> otaList = baseDao.selectList(queryWrapper);
         if (otaList != null && otaList.size() > 0) {
-            OtaEntity otaBefore = otaList.getFirst();
+            OtaEntity otaBefore = otaList.get(0);
             entity.setId(otaBefore.getId());
             baseDao.updateById(entity);
             return true;

main/manager-api/src/main/java/xiaozhi/modules/knowledge/config/KnowledgeBaseConfig.java

@@ -0,0 +1,22 @@
+package xiaozhi.modules.knowledge.config;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import xiaozhi.modules.knowledge.rag.KnowledgeBaseAdapterFactory;
+
+/**
+ * 知识库配置类
+ * 配置知识库相关的Bean
+ */
+@Configuration
+public class KnowledgeBaseConfig {
+
+    /**
+     * 提供KnowledgeBaseAdapterFactory的Bean实例
+     * @return KnowledgeBaseAdapterFactory实例
+     */
+    @Bean
+    public KnowledgeBaseAdapterFactory knowledgeBaseAdapterFactory() {
+        return new KnowledgeBaseAdapterFactory();
+    }
+}

main/manager-api/src/main/java/xiaozhi/modules/knowledge/config/RAGTaskConfig.java

@@ -0,0 +1,13 @@
+package xiaozhi.modules.knowledge.config;
+
+import org.springframework.context.annotation.Configuration;
+import org.springframework.scheduling.annotation.EnableScheduling;
+
+/**
+ * 知识库模块定时任务配置
+ * 启用 Spring Schedule 能力
+ */
+@Configuration
+@EnableScheduling
+public class RAGTaskConfig {
+}

main/manager-api/src/main/java/xiaozhi/modules/knowledge/controller/KnowledgeBaseController.java

@@ -0,0 +1,163 @@
+package xiaozhi.modules.knowledge.controller;
+
+import java.util.*;
+
+import org.apache.commons.lang3.StringUtils;
+import org.apache.shiro.authz.annotation.RequiresPermissions;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.AllArgsConstructor;
+import xiaozhi.common.exception.ErrorCode;
+import xiaozhi.common.exception.RenException;
+import xiaozhi.common.page.PageData;
+import xiaozhi.common.utils.Result;
+import xiaozhi.common.utils.ToolUtil;
+import xiaozhi.modules.knowledge.dto.KnowledgeBaseDTO;
+import xiaozhi.modules.knowledge.service.KnowledgeBaseService;
+import xiaozhi.modules.knowledge.service.KnowledgeManagerService;
+import xiaozhi.modules.model.entity.ModelConfigEntity;
+import xiaozhi.modules.security.user.SecurityUser;
+
+@AllArgsConstructor
+@RestController
+@RequestMapping("/datasets")
+@Tag(name = "知识库管理")
+public class KnowledgeBaseController {
+
+    private final KnowledgeBaseService knowledgeBaseService;
+    private final KnowledgeManagerService knowledgeManagerService;
+
+    @GetMapping
+    @Operation(summary = "分页查询知识库列表")
+    @RequiresPermissions("sys:role:normal")
+    public Result<PageData<KnowledgeBaseDTO>> getPageList(
+            @RequestParam(required = false) String name,
+            @RequestParam(required = false, defaultValue = "1") Integer page,
+            @RequestParam(required = false, defaultValue = "10") Integer page_size) {
+        // 获取当前登录用户ID
+        Long currentUserId = SecurityUser.getUserId();
+
+        KnowledgeBaseDTO knowledgeBaseDTO = new KnowledgeBaseDTO();
+        knowledgeBaseDTO.setName(name);
+        knowledgeBaseDTO.setCreator(currentUserId); // 设置创建者ID，用于权限过滤
+
+        PageData<KnowledgeBaseDTO> pageData = knowledgeBaseService.getPageList(knowledgeBaseDTO, page, page_size);
+        return new Result<PageData<KnowledgeBaseDTO>>().ok(pageData);
+    }
+
+    @GetMapping("/{dataset_id}")
+    @Operation(summary = "根据知识库ID获取知识库详情")
+    @RequiresPermissions("sys:role:normal")
+    public Result<KnowledgeBaseDTO> getByDatasetId(@PathVariable("dataset_id") String datasetId) {
+        // 获取当前登录用户ID
+        Long currentUserId = SecurityUser.getUserId();
+
+        KnowledgeBaseDTO knowledgeBaseDTO = knowledgeBaseService.getByDatasetId(datasetId);
+
+        // 检查权限：用户只能查看自己创建的知识库
+        if (knowledgeBaseDTO.getCreator() == null || !knowledgeBaseDTO.getCreator().equals(currentUserId)) {
+            throw new RenException(ErrorCode.NO_PERMISSION);
+        }
+
+        return new Result<KnowledgeBaseDTO>().ok(knowledgeBaseDTO);
+    }
+
+    @PostMapping
+    @Operation(summary = "创建知识库")
+    @RequiresPermissions("sys:role:normal")
+    public Result<KnowledgeBaseDTO> save(@RequestBody @Validated KnowledgeBaseDTO knowledgeBaseDTO) {
+        KnowledgeBaseDTO resp = knowledgeBaseService.save(knowledgeBaseDTO);
+        return new Result<KnowledgeBaseDTO>().ok(resp);
+    }
+
+    @PutMapping("/{dataset_id}")
+    @Operation(summary = "更新知识库")
+    @RequiresPermissions("sys:role:normal")
+    public Result<KnowledgeBaseDTO> update(@PathVariable("dataset_id") String datasetId,
+            @RequestBody @Validated KnowledgeBaseDTO knowledgeBaseDTO) {
+        // 获取当前登录用户ID
+        Long currentUserId = SecurityUser.getUserId();
+
+        // 先获取现有知识库信息以检查权限
+        KnowledgeBaseDTO existingKnowledgeBase = knowledgeBaseService.getByDatasetId(datasetId);
+
+        // 检查权限：用户只能更新自己创建的知识库
+        if (existingKnowledgeBase.getCreator() == null || !existingKnowledgeBase.getCreator().equals(currentUserId)) {
+            throw new RenException(ErrorCode.NO_PERMISSION);
+        }
+
+        // [FIX] 注入 ID，防止 Service 层找不到记录
+        knowledgeBaseDTO.setId(existingKnowledgeBase.getId());
+        knowledgeBaseDTO.setDatasetId(datasetId);
+        KnowledgeBaseDTO resp = knowledgeBaseService.update(knowledgeBaseDTO);
+        return new Result<KnowledgeBaseDTO>().ok(resp);
+    }
+
+    @DeleteMapping("/{dataset_id}")
+    @Operation(summary = "删除单个知识库")
+    @Parameter(name = "dataset_id", description = "知识库ID", required = true)
+    @RequiresPermissions("sys:role:normal")
+    public Result<Void> delete(@PathVariable("dataset_id") String datasetId) {
+        // 获取当前登录用户ID
+        Long currentUserId = SecurityUser.getUserId();
+
+        // 先获取现有知识库信息以检查权限
+        KnowledgeBaseDTO existingKnowledgeBase = knowledgeBaseService.getByDatasetId(datasetId);
+
+        // 检查权限：用户只能删除自己创建的知识库
+        if (existingKnowledgeBase.getCreator() == null || !existingKnowledgeBase.getCreator().equals(currentUserId)) {
+            throw new RenException(ErrorCode.NO_PERMISSION);
+        }
+
+        // [Architecture Fix] 通过编排层级联删除，防止孤儿数据并解决循环依赖
+        knowledgeManagerService.deleteDatasetWithFiles(datasetId);
+        return new Result<>();
+    }
+
+    @DeleteMapping("/batch")
+    @Operation(summary = "批量删除知识库")
+    @Parameter(name = "ids", description = "知识库ID列表，用逗号分隔", required = true)
+    @RequiresPermissions("sys:role:normal")
+    public Result<Void> deleteBatch(@RequestParam("ids") String ids) {
+        if (StringUtils.isBlank(ids)) {
+            throw new RenException(ErrorCode.PARAMS_GET_ERROR);
+        }
+
+        // 获取当前登录用户ID
+        Long currentUserId = SecurityUser.getUserId();
+        List<String> idList = Arrays.asList(ids.split(","));
+        List<KnowledgeBaseDTO> knowledgeBaseDTOs = Optional.ofNullable(knowledgeBaseService.getByDatasetIdList(idList))
+                .orElseGet(ArrayList::new);
+        if (ToolUtil.isNotEmpty(knowledgeBaseDTOs)) {
+            knowledgeBaseDTOs.forEach(item -> {
+                // 检查权限：用户只能删除自己创建的知识库
+                if (item.getCreator() == null || !item.getCreator().equals(currentUserId)) {
+                    throw new RenException(ErrorCode.NO_PERMISSION);
+                }
+                // [Architecture Fix] 通过编排层级联删除
+                knowledgeManagerService.deleteDatasetWithFiles(item.getDatasetId());
+            });
+        }
+        return new Result<>();
+    }
+
+    @GetMapping("/rag-models")
+    @Operation(summary = "获取RAG模型列表")
+    @RequiresPermissions("sys:role:normal")
+    public Result<List<ModelConfigEntity>> getRAGModels() {
+        List<ModelConfigEntity> result = knowledgeBaseService.getRAGModels();
+        return new Result<List<ModelConfigEntity>>().ok(result);
+    }
+}

main/manager-api/src/main/java/xiaozhi/modules/knowledge/controller/KnowledgeFilesController.java

@@ -0,0 +1,226 @@
+package xiaozhi.modules.knowledge.controller;
+
+import java.util.List;
+import java.util.Map;
+
+import org.apache.shiro.authz.annotation.RequiresPermissions;
+import org.springdoc.core.annotations.ParameterObject;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.AllArgsConstructor;
+import xiaozhi.common.exception.ErrorCode;
+import xiaozhi.common.exception.RenException;
+import xiaozhi.common.page.PageData;
+import xiaozhi.common.utils.Result;
+import xiaozhi.modules.knowledge.dto.KnowledgeBaseDTO;
+import xiaozhi.modules.knowledge.dto.KnowledgeFilesDTO;
+import xiaozhi.modules.knowledge.dto.document.ChunkDTO;
+import xiaozhi.modules.knowledge.dto.document.DocumentDTO;
+import xiaozhi.modules.knowledge.dto.document.RetrievalDTO;
+import xiaozhi.modules.knowledge.service.KnowledgeBaseService;
+import xiaozhi.modules.knowledge.service.KnowledgeFilesService;
+import xiaozhi.modules.security.user.SecurityUser;
+
+@AllArgsConstructor
+@RestController
+@RequestMapping("/datasets/{dataset_id}")
+@Tag(name = "知识库文档管理")
+public class KnowledgeFilesController {
+
+    private final KnowledgeFilesService knowledgeFilesService;
+    private final KnowledgeBaseService knowledgeBaseService;
+
+    /**
+     * 验证当前用户是否有权限操作指定知识库
+     * 
+     * @param datasetId 知识库ID
+     */
+    private void validateKnowledgeBasePermission(String datasetId) {
+        // 获取当前登录用户ID
+        Long currentUserId = SecurityUser.getUserId();
+
+        // 获取知识库信息
+        KnowledgeBaseDTO knowledgeBase = knowledgeBaseService.getByDatasetId(datasetId);
+
+        // 检查权限：用户只能操作自己创建的知识库
+        if (knowledgeBase.getCreator() == null || !knowledgeBase.getCreator().equals(currentUserId)) {
+            throw new RenException(ErrorCode.NO_PERMISSION);
+        }
+    }
+
+    @GetMapping("/documents")
+    @Operation(summary = "分页查询文档列表")
+    @RequiresPermissions("sys:role:normal")
+    public Result<PageData<KnowledgeFilesDTO>> getPageList(
+            @PathVariable("dataset_id") String datasetId,
+            @RequestParam(required = false) String name,
+            @RequestParam(required = false) String status,
+            @RequestParam(required = false, defaultValue = "1") Integer page,
+            @RequestParam(required = false, defaultValue = "10") Integer page_size) {
+        // 验证知识库权限
+        validateKnowledgeBasePermission(datasetId);
+
+        // 组装参数
+        KnowledgeFilesDTO knowledgeFilesDTO = new KnowledgeFilesDTO();
+        knowledgeFilesDTO.setDatasetId(datasetId);
+        knowledgeFilesDTO.setName(name);
+        knowledgeFilesDTO.setStatus(status);
+        PageData<KnowledgeFilesDTO> pageData = knowledgeFilesService.getPageList(knowledgeFilesDTO, page, page_size);
+        return new Result<PageData<KnowledgeFilesDTO>>().ok(pageData);
+    }
+
+    @GetMapping("/documents/status/{status}")
+    @Operation(summary = "根据状态分页查询文档列表")
+    @RequiresPermissions("sys:role:normal")
+    public Result<PageData<KnowledgeFilesDTO>> getPageListByStatus(
+            @PathVariable("dataset_id") String datasetId,
+            @PathVariable("status") String status,
+            @RequestParam(required = false, defaultValue = "1") Integer page,
+            @RequestParam(required = false, defaultValue = "10") Integer page_size) {
+        // 验证知识库权限
+        validateKnowledgeBasePermission(datasetId);
+        // 组装参数
+        KnowledgeFilesDTO knowledgeFilesDTO = new KnowledgeFilesDTO();
+        knowledgeFilesDTO.setDatasetId(datasetId);
+        knowledgeFilesDTO.setStatus(status);
+        PageData<KnowledgeFilesDTO> pageData = knowledgeFilesService.getPageList(knowledgeFilesDTO, page, page_size);
+        return new Result<PageData<KnowledgeFilesDTO>>().ok(pageData);
+    }
+
+    @PostMapping("/documents")
+    @Operation(summary = "上传文档到知识库")
+    @RequiresPermissions("sys:role:normal")
+    public Result<KnowledgeFilesDTO> uploadDocument(
+            @PathVariable("dataset_id") String datasetId,
+            @RequestParam("file") MultipartFile file,
+            @RequestParam(required = false) String name,
+            @RequestParam(required = false) String chunkMethod,
+            @RequestParam(required = false) String metaFields,
+            @RequestParam(required = false) String parserConfig) {
+
+        // 验证知识库权限
+        validateKnowledgeBasePermission(datasetId);
+
+        KnowledgeFilesDTO resp = knowledgeFilesService.uploadDocument(datasetId, file, name,
+                metaFields != null ? parseJsonMap(metaFields) : null,
+                chunkMethod,
+                parserConfig != null ? parseJsonMap(parserConfig) : null);
+        return new Result<KnowledgeFilesDTO>().ok(resp);
+    }
+
+    @DeleteMapping("/documents")
+    @Operation(summary = "批量删除文档")
+    @RequiresPermissions("sys:role:normal")
+    public Result<Void> delete(@PathVariable("dataset_id") String datasetId,
+            @RequestBody DocumentDTO.BatchIdReq req) {
+        // 验证知识库权限
+        validateKnowledgeBasePermission(datasetId);
+
+        knowledgeFilesService.deleteDocuments(datasetId, req);
+        return new Result<>();
+    }
+
+    @DeleteMapping("/documents/{document_id}")
+    @Operation(summary = "删除单个文档")
+    @RequiresPermissions("sys:role:normal")
+    public Result<Void> deleteSingle(@PathVariable("dataset_id") String datasetId,
+            @PathVariable("document_id") String documentId) {
+        // 验证知识库权限
+        validateKnowledgeBasePermission(datasetId);
+
+        DocumentDTO.BatchIdReq req = new DocumentDTO.BatchIdReq();
+        req.setIds(java.util.Collections.singletonList(documentId));
+        knowledgeFilesService.deleteDocuments(datasetId, req);
+        return new Result<>();
+    }
+
+    @PostMapping("/chunks")
+    @Operation(summary = "解析文档（切块）")
+    @RequiresPermissions("sys:role:normal")
+    public Result<Void> parseDocuments(@PathVariable("dataset_id") String datasetId,
+            @RequestBody Map<String, List<String>> requestBody) {
+        // 验证知识库权限
+        validateKnowledgeBasePermission(datasetId);
+
+        List<String> documentIds = requestBody.get("document_ids");
+        if (documentIds == null || documentIds.isEmpty()) {
+            return new Result<Void>().error("document_ids参数不能为空");
+        }
+
+        boolean success = knowledgeFilesService.parseDocuments(datasetId, documentIds);
+        if (success) {
+            return new Result<Void>();
+        } else {
+            return new Result<Void>().error("文档解析失败，文档可能正在处理中");
+        }
+    }
+
+    @GetMapping("/documents/{document_id}/chunks")
+    @Operation(summary = "列出指定文档的切片")
+    @RequiresPermissions("sys:role:normal")
+    public Result<ChunkDTO.ListVO> listChunks(
+            @PathVariable("dataset_id") String datasetId,
+            @PathVariable("document_id") String documentId,
+            @ParameterObject ChunkDTO.ListReq req) {
+
+        // 验证权限 (内部已包含知识库存在性校验与归属权校验)
+        validateKnowledgeBasePermission(datasetId);
+
+        // 设置默认值
+        if (req.getPage() == null)
+            req.setPage(1);
+        if (req.getPageSize() == null)
+            req.setPageSize(50);
+
+        // 调用服务层获取强类型切片列表
+        ChunkDTO.ListVO result = knowledgeFilesService.listChunks(datasetId, documentId, req);
+        return new Result<ChunkDTO.ListVO>().ok(result);
+    }
+
+    @PostMapping("/retrieval-test")
+    @Operation(summary = "召回测试")
+    @RequiresPermissions("sys:role:normal")
+    public Result<RetrievalDTO.ResultVO> retrievalTest(
+            @PathVariable("dataset_id") String datasetId,
+            @RequestBody RetrievalDTO.TestReq req) {
+
+        // 验证知识库权限
+        validateKnowledgeBasePermission(datasetId);
+
+        // 业务下沉逻辑：如果未指定知识库ID，则设为当前路径中的 datasetId
+        if (req.getDatasetIds() == null || req.getDatasetIds().isEmpty()) {
+            req.setDatasetIds(java.util.Arrays.asList(datasetId));
+        }
+
+        // [Reinforce] 强管控分页参数，防止 RAGFlow 端出现 Negative Slicing 报错
+        if (req.getPage() == null || req.getPage() < 1) {
+            req.setPage(1);
+        }
+        if (req.getPageSize() == null || req.getPageSize() < 1) {
+            req.setPageSize(100);
+        }
+
+        // 调用检索服务，返回强类型聚合对象
+        RetrievalDTO.ResultVO result = knowledgeFilesService.retrievalTest(req);
+        return new Result<RetrievalDTO.ResultVO>().ok(result);
+    }
+
+    /**
+     * 解析JSON字符串为Map对象
+     */
+    private Map<String, Object> parseJsonMap(String jsonString) {
+        try {
+            ObjectMapper objectMapper = new ObjectMapper();
+            return objectMapper.readValue(jsonString, new TypeReference<Map<String, Object>>() {
+            });
+        } catch (Exception e) {
+            throw new RuntimeException("解析JSON字符串失败: " + jsonString, e);
+        }
+    }
+}

main/manager-api/src/main/java/xiaozhi/modules/knowledge/dao/DocumentDao.java

@@ -0,0 +1,12 @@
+package xiaozhi.modules.knowledge.dao;
+
+import org.apache.ibatis.annotations.Mapper;
+import xiaozhi.common.dao.BaseDao;
+import xiaozhi.modules.knowledge.entity.DocumentEntity;
+
+/**
+ * 文档 DAO
+ */
+@Mapper
+public interface DocumentDao extends BaseDao<DocumentEntity> {
+}

main/manager-api/src/main/java/xiaozhi/modules/knowledge/dao/KnowledgeBaseDao.java

@@ -0,0 +1,35 @@
+package xiaozhi.modules.knowledge.dao;
+
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+
+import xiaozhi.common.dao.BaseDao;
+import xiaozhi.modules.knowledge.entity.KnowledgeBaseEntity;
+
+/**
+ * 知识库知识库
+ */
+@Mapper
+public interface KnowledgeBaseDao extends BaseDao<KnowledgeBaseEntity> {
+
+    /**
+     * 根据知识库ID删除相关的插件映射记录
+     * 
+     * @param knowledgeBaseId 知识库ID
+     */
+    void deletePluginMappingByKnowledgeBaseId(@Param("knowledgeBaseId") String knowledgeBaseId);
+
+    /**
+     * 通用维度原子更新知识库统计信息
+     * 
+     * @param datasetId  数据集ID
+     * @param docDelta   文档数增量
+     * @param chunkDelta 分块数增量
+     * @param tokenDelta Token数增量
+     */
+    void updateStatsAfterChange(@Param("datasetId") String datasetId,
+            @Param("docDelta") Integer docDelta,
+            @Param("chunkDelta") Long chunkDelta,
+            @Param("tokenDelta") Long tokenDelta);
+
+}

main/manager-api/src/main/java/xiaozhi/modules/knowledge/doc/RAGFlow_API接口分类表.md

@@ -0,0 +1,102 @@
+# RAGFlow API Interface Classification
+
+## 1. External APIs (三方接入体系)
+**Path Prefix:** `/api/v1`
+**Authentication:** API Key (`@token_required`)
+**Primary Use:** External system integration, SDK usage.
+
+| Interface Type | Python File Path | Class/Function Name | URL Pattern | Notes |
+|---|---|---|---|---|
+| **External** | `api/apps/sdk/session.py` | `agent_bot_completions` | `/api/v1/agentbots/<agent_id>/completions` | Agent Bot completion |
+| **External** | `api/apps/sdk/session.py` | `begin_inputs` | `/api/v1/agentbots/<agent_id>/inputs` | Get Agent Bot inputs |
+| **External** | `api/apps/sdk/agents.py` | `list_agents` | `/api/v1/agents` | List Agents |
+| **External** | `api/apps/sdk/agents.py` | `create_agent` | `/api/v1/agents` | Create Agent |
+| **External** | `api/apps/sdk/agents.py` | `update_agent` | `/api/v1/agents/<agent_id>` | Update Agent |
+| **External** | `api/apps/sdk/agents.py` | `delete_agent` | `/api/v1/agents/<agent_id>` | Delete Agent |
+| **External** | `api/apps/sdk/session.py` | `agent_completions` | `/api/v1/agents/<agent_id>/completions` | Agent completion |
+| **External** | `api/apps/sdk/session.py` | `create_agent_session` | `/api/v1/agents/<agent_id>/sessions` | Create Agent Session |
+| **External** | `api/apps/sdk/session.py` | `list_agent_session` | `/api/v1/agents/<agent_id>/sessions` | List Agent Sessions |
+| **External** | `api/apps/sdk/session.py` | `delete_agent_session` | `/api/v1/agents/<agent_id>/sessions` | Delete Agent Session |
+| **External** | `api/apps/sdk/session.py` | `agents_completion_openai_compatibility` | `/api/v1/agents_openai/<agent_id>/chat/completions` | OpenAI compatible Agent completion |
+| **External** | `api/apps/sdk/session.py` | `chatbot_completions` | `/api/v1/chatbots/<dialog_id>/completions` | Chatbot completion |
+| **External** | `api/apps/sdk/session.py` | `chatbots_inputs` | `/api/v1/chatbots/<dialog_id>/info` | Chatbot info |
+| **External** | `api/apps/sdk/chat.py` | `create` | `/api/v1/chats` | Create Chat |
+| **External** | `api/apps/sdk/chat.py` | `delete_chats` | `/api/v1/chats` | Delete Chat |
+| **External** | `api/apps/sdk/chat.py` | `list_chat` | `/api/v1/chats` | List Chats |
+| **External** | `api/apps/sdk/chat.py` | `update` | `/api/v1/chats/<chat_id>` | Update Chat |
+| **External** | `api/apps/sdk/session.py` | `chat_completion` | `/api/v1/chats/<chat_id>/completions` | Chat completion |
+| **External** | `api/apps/sdk/session.py` | `create` | `/api/v1/chats/<chat_id>/sessions` | Create Chat Session |
+| **External** | `api/apps/sdk/session.py` | `list_session` | `/api/v1/chats/<chat_id>/sessions` | List Chat Sessions |
+| **External** | `api/apps/sdk/session.py` | `delete` | `/api/v1/chats/<chat_id>/sessions` | Delete Chat Session |
+| **External** | `api/apps/sdk/session.py` | `update` | `/api/v1/chats/<chat_id>/sessions/<session_id>` | Update Chat Session |
+| **External** | `api/apps/sdk/session.py` | `chat_completion_openai_like` | `/api/v1/chats_openai/<chat_id>/chat/completions` | OpenAI compatible Chat completion |
+| **External** | `api/apps/sdk/dataset.py` | `create` | `/api/v1/datasets` | Create Dataset |
+| **External** | `api/apps/sdk/dataset.py` | `delete` | `/api/v1/datasets` | Delete Dataset |
+| **External** | `api/apps/sdk/dataset.py` | `list_datasets` | `/api/v1/datasets` | List Datasets |
+| **External** | `api/apps/sdk/dataset.py` | `update` | `/api/v1/datasets/<dataset_id>` | Update Dataset |
+| **External** | `api/apps/sdk/doc.py` | `parse` | `/api/v1/datasets/<dataset_id>/chunks` | Parse Document Chunks |
+| **External** | `api/apps/sdk/doc.py` | `stop_parsing` | `/api/v1/datasets/<dataset_id>/chunks` | Stop Parsing |
+| **External** | `api/apps/sdk/doc.py` | `upload` | `/api/v1/datasets/<dataset_id>/documents` | Upload Document |
+| **External** | `api/apps/sdk/doc.py` | `list_docs` | `/api/v1/datasets/<dataset_id>/documents` | List Documents |
+| **External** | `api/apps/sdk/doc.py` | `delete` | `/api/v1/datasets/<dataset_id>/documents` | Delete Document |
+| **External** | `api/apps/sdk/doc.py` | `update_doc` | `/api/v1/datasets/<dataset_id>/documents/<document_id>` | Update Document |
+| **External** | `api/apps/sdk/doc.py` | `download` | `/api/v1/datasets/<dataset_id>/documents/<document_id>` | Download Document |
+| **External** | `api/apps/sdk/doc.py` | `list_chunks` | `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks` | List Chunks |
+| **External** | `api/apps/sdk/doc.py` | `add_chunk` | `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks` | Add Chunk |
+| **External** | `api/apps/sdk/doc.py` | `update_chunk` | `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks/<chunk_id>` | Update Chunk |
+| **External** | `api/apps/sdk/dataset.py` | `knowledge_graph` | `/api/v1/datasets/<dataset_id>/knowledge_graph` | Knowledge Graph |
+| **External** | `api/apps/sdk/dataset.py` | `delete_knowledge_graph` | `/api/v1/datasets/<dataset_id>/knowledge_graph` | Delete Knowledge Graph |
+| **External** | `api/apps/sdk/doc.py` | `metadata_summary` | `/api/v1/datasets/<dataset_id>/metadata/summary` | Metadata Summary |
+| **External** | `api/apps/sdk/doc.py` | `metadata_batch_update` | `/api/v1/datasets/<dataset_id>/metadata/update` | Batch Update Metadata |
+| **External** | `api/apps/sdk/dataset.py` | `run_graphrag` | `/api/v1/datasets/<dataset_id>/run_graphrag` | Run GraphRAG |
+| **External** | `api/apps/sdk/dataset.py` | `run_raptor` | `/api/v1/datasets/<dataset_id>/run_raptor` | Run Raptor |
+| **External** | `api/apps/sdk/dataset.py` | `trace_graphrag` | `/api/v1/datasets/<dataset_id>/trace_graphrag` | Trace GraphRAG |
+| **External** | `api/apps/sdk/dataset.py` | `trace_raptor` | `/api/v1/datasets/<dataset_id>/trace_raptor` | Trace Raptor |
+| **External** | `api/apps/sdk/dify_retrieval.py` | `retrieval` | `/api/v1/dify/retrieval` | Dify Retrieval |
+| **External** | `api/apps/sdk/files.py` | `get_all_parent_folders` | `/api/v1/file/all_parent_folder` | Get All Parent Folders |
+| **External** | `api/apps/sdk/files.py` | `convert` | `/api/v1/file/convert` | File Convert |
+| **External** | `api/apps/sdk/files.py` | `create` | `/api/v1/file/create` | File Create |
+| **External** | `api/apps/sdk/files.py` | `download_attachment` | `/api/v1/file/download/<attachment_id>` | Download Attachment |
+| **External** | `api/apps/sdk/files.py` | `get` | `/api/v1/file/get/<file_id>` | Get File |
+| **External** | `api/apps/sdk/files.py` | `list_files` | `/api/v1/file/list` | List Files |
+| **External** | `api/apps/sdk/files.py` | `move` | `/api/v1/file/mv` | Move File |
+| **External** | `api/apps/sdk/files.py` | `get_parent_folder` | `/api/v1/file/parent_folder` | Get Parent Folder |
+| **External** | `api/apps/sdk/files.py` | `rename` | `/api/v1/file/rename` | Rename File |
+| **External** | `api/apps/sdk/files.py` | `rm` | `/api/v1/file/rm` | Remove File |
+| **External** | `api/apps/sdk/files.py` | `get_root_folder` | `/api/v1/file/root_folder` | Get Root Folder |
+| **External** | `api/apps/sdk/files.py` | `upload` | `/api/v1/file/upload` | Upload File |
+| **External** | `api/apps/sdk/doc.py` | `retrieval_test` | `/api/v1/retrieval` | Retrieval Test |
+| **External** | `api/apps/sdk/session.py` | `ask_about_embedded` | `/api/v1/searchbots/ask` | Searchbot Ask |
+| **External** | `api/apps/sdk/session.py` | `detail_share_embedded` | `/api/v1/searchbots/detail` | Searchbot Detail |
+| **External** | `api/apps/sdk/session.py` | `mindmap` | `/api/v1/searchbots/mindmap` | Searchbot Mindmap |
+| **External** | `api/apps/sdk/session.py` | `related_questions_embedded` | `/api/v1/searchbots/related_questions` | Searchbot Related Questions |
+| **External** | `api/apps/sdk/session.py` | `retrieval_test_embedded` | `/api/v1/searchbots/retrieval_test` | Searchbot Retrieval Test |
+| **External** | `api/apps/sdk/session.py` | `ask_about` | `/api/v1/sessions/ask` | Session Ask |
+| **External** | `api/apps/sdk/session.py` | `related_questions` | `/api/v1/sessions/related_questions` | Session Related Questions |
+| **External** | `api/apps/sdk/agents.py` | `webhook` | `/api/v1/webhook_test/<agent_id>` | Webhook Test |
+| **External** | `api/apps/sdk/agents.py` | `webhook_trace` | `/api/v1/webhook_trace/<agent_id>` | Webhook Trace |
+| **External** | `api/apps/sdk/doc.py` | `rm_chunk` | `/api/v1datasets/<dataset_id>/documents/<document_id>/chunks` | Remove Chunk |
+
+
+## 2. Internal APIs (内部前端体系)
+**Path Prefix:** `/v1/<app_name>` matches file `api/apps/<app_name>_app.py`
+**Authentication:** Session/Cookie (`@login_required`)
+**Primary Use:** RAGFlow Web Frontend.
+
+**Selected Core Interfaces:**
+
+| Interface Type | Python File Path | Class/Function Name | URL Pattern | Notes |
+|---|---|---|---|---|
+| Internal | `api/apps/user_app.py` | `login` | `/v1/user/login` | User Login (Frontend) |
+| Internal | `api/apps/user_app.py` | `log_out` | `/v1/user/logout` | User Logout |
+| Internal | `api/apps/user_app.py` | `user_add` | `/v1/user/register` | User Registration |
+| Internal | `api/apps/user_app.py` | `user_profile` | `/v1/user/info` | User Profile Info |
+| Internal | `api/apps/api_app.py` | `new_token` | `/v1/api/new_token` | Generate new API Token |
+| Internal | `api/apps/conversation_app.py` | `set_conversation` | `/v1/conversation/set` | Create/Update Conversation |
+| Internal | `api/apps/conversation_app.py` | `completion` | `/v1/conversation/completion` | Chat Conversation Completion |
+| Internal | `api/apps/kb_app.py` | `list_kbs` | `/v1/kb/list` | List Knowledge Bases |
+| Internal | `api/apps/kb_app.py` | `create` | `/v1/kb/create` | Create Knowledge Base |
+| Internal | `api/apps/document_app.py` | `upload` | `/v1/document/upload` | Upload Document to KB |
+| Internal | `api/apps/document_app.py` | `parse` | `/v1/document/parse` | Parse Document |
+
+*(For a complete list of all 200+ internal APIs, please refer to the `api_endpoints.txt` file or the full scan results)*

main/manager-api/src/main/java/xiaozhi/modules/knowledge/doc/RAGFlow_Agent_Dify接口详解.md

@@ -0,0 +1,279 @@
+# RAGFlow Agent 与 Dify 兼容接口详解 (Agent & Dify Compatibility)
+
+## 1. Dify 兼容检索 - `retrieval`
+**接口描述**: 模拟 Dify API 格式的知识库检索接口。此接口主要用于让现有的 Dify 客户端或系统能够方便地接入 RAGFlow 的知识库检索能力。它支持文本检索、混合检索以及通过元数据过滤文档。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/dify/retrieval`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| knowledge_id | string | 是 | - | **知识库 ID**。 |
+| query | string | 是 | - | **查询文本**。用户输入的检索问题。 |
+| use_kg | boolean | 否 | false | **使用知识图谱**。是否结合知识图谱进行检索。 |
+| retrieval_setting | object | 否 | {} | **检索配置**。包含相似度阈值和 Top-K。 |
+| metadata_condition | object | 否 | {} | **元数据过滤条件**。用于筛选特定文档。 |
+
+#### 参数详情 (Detail Objects)
+**retrieval_setting**:
+```json
+{
+  "score_threshold": 0.5, // 相似度阈值 (default: 0.0)
+  "top_k": 5              // 返回数量 (default: 1024)
+}
+```
+
+**metadata_condition**:
+```json
+{
+  "logic": "and", // 逻辑关系 (and/or)
+  "conditions": [
+    {
+      "name": "author",           // 字段名
+      "comparison_operator": "eq",// 运算符 (eq, ne, gt, lt 等)
+      "value": "Alice"            // 字段值
+    }
+  ]
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "records": [
+      {
+        "content": "RAGFlow 是一个基于深度文档理解的检索增强生成引擎...",
+        "score": 0.92,
+        "title": "RAGFlow_Introduction.pdf",
+        "metadata": {
+          "doc_id": "doc_uuid_123",
+          "author": "Alice",
+          "publish_year": "2024"
+        }
+      },
+      {
+        "content": "DeepDOC 模型能够精准识别复杂的表格结构...",
+        "score": 0.88,
+        "title": "DeepDOC_Tech_Report.pdf",
+        "metadata": {
+          "doc_id": "doc_uuid_456",
+          "author": "Bob"
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 2. 创建 Agent 会话 - `create_agent_session`
+**接口描述**: 创建一个新的 Agent 会话 (Session)。会话是用户与 Agent 交互的上下文容器，保存了历史对话记录和 DSL（领域特定语言）状态。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/agents/<agent_id>/sessions`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| agent_id | string | 是 | **Agent ID**。 |
+
+#### Query Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| user_id | string | 否 | **用户标识**。用于区分不同终端用户的会话。若不传，默认为当前 Tenant ID。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "session_uuid_new_123",
+    "agent_id": "agent_uuid_abc",
+    "user_id": "user_123",
+    "source": "agent",
+    "dsl": { ... }, // 完整的 Agent DSL 定义
+    "messages": [
+      {
+        "role": "assistant",
+        "content": "你好！我是你的智能助手，有什么可以帮你的吗？" // Prologue (开场白)
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 3. 获取 Agent 会话列表 - `list_agent_session`
+**接口描述**: 分页获取指定 Agent 下的会话列表。支持按 ID 或 User ID 过滤。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/agents/<agent_id>/sessions`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| agent_id | string | 是 | **Agent ID**。 |
+
+#### Query Parameters
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| page | int | 否 | 1 | **页码**。 |
+| page_size | int | 否 | 30 | **每页数量**。 |
+| orderby | string | 否 | "update_time" | **排序字段**。 |
+| desc | boolean | 否 | true | **是否降序**。 |
+| id | string | 否 | - | **会话 ID**。精确筛选。 |
+| user_id | string | 否 | - | **用户标识**。筛选特定用户的会话。 |
+| dsl | boolean | 否 | true | **包含 DSL**。是否在返回结果中包含完整的 DSL 结构 (数据量较大)。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": [
+    {
+      "id": "session_uuid_123",
+      "agent_id": "agent_uuid_abc",
+      "user_id": "user_123",
+      "create_time": 1715000000000,
+      "update_time": 1715000050000,
+      "source": "agent",
+      "messages": [
+        {
+          "role": "assistant",
+          "content": "Hi there!"
+        },
+        {
+          "role": "user",
+          "content": "What is RAG?"
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## 4. 删除 Agent 会话 - `delete_agent_session`
+**接口描述**: 批量删除 Agent 会话。
+**请求方法**: `DELETE`
+**接口地址**: `/api/v1/agents/<agent_id>/sessions`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| agent_id | string | 是 | **Agent ID**。 |
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| ids | array<string> | 否 | **会话 ID 列表**。若不传该参数，将尝试删除(或清空)该 Agent 下的所有会话（需谨慎）。 |
+
+**Request Example**:
+```json
+{
+  "ids": ["session_id_1", "session_id_2"]
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "success_count": 2,
+    "errors": []
+  }
+}
+```
+
+---
+
+## 5. Agent 对话 (流式) - `agent_completions`
+**接口描述**: 向 Agent 发送用户问题并获取回复。这是 Agent 交互的核心接口，支持 **Server-Sent Events (SSE)** 流式响应。Agent 会根据编排好的 DSL 流程执行（可能涉及多个节点、知识库检索、LLM 推理等），并实时推送执行过程和最终结果。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/agents/<agent_id>/completions`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| agent_id | string | 是 | **Agent ID**。 |
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| session_id | string | 是 | - | **会话 ID**。必须是 `create_agent_session` 返回的 ID。 |
+| question | string | 是 | - | **用户问题**。 |
+| stream | boolean | 否 | true | **是否流式响应**。强烈建议设为 `true` 以获得更好的用户体验。 |
+| return_trace | boolean | 否 | false | **返回执行轨迹**。如果为 `true`，流式响应中将包含各个节点的执行过程数据 (Trace)。 |
+
+### 响应参数 (Stream Response)
+**Content-Type**: `text/event-stream`
+
+响应是一个 SSE 流，每一行以 `data:` 开头，包含一个 JSON 对象。
+
+**Event Types**:
+- `message`: 普通文本消息片段。
+- `node_finished`: (当 `return_trace=true` 时) 节点执行完成事件，包含节点输出数据。
+- `message_end`: 消息结束。
+- `[DONE]`: 流结束标志。
+
+#### Stream Chunk Examples:
+
+**1. 文本生成片段 (message)**:
+```text
+data:{"code": 0, "message": "success", "data": {"content": "Hello", "reference": {}, "id": "msg_uuid_1"}, "event": "message"}
+
+data:{"code": 0, "message": "success", "data": {"content": " world", "reference": {}, "id": "msg_uuid_1"}, "event": "message"}
+```
+
+**2. 节点执行轨迹 (node_finished, return_trace=true)**:
+```text
+data:{"code": 0, "message": "success", "data": {"component_id": "retrieval_node_1", "content": "...", "trace": [...]}, "event": "node_finished"}
+```
+
+**3. 最终结束 (DONE)**:
+```text
+data:[DONE]
+```
+
+#### Non-Stream Response (stream=false)
+如果不使用流式响应，将等待 Agent 全流程执行完毕后一次性返回 JSON。
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "content": "Hello world! This is the final answer.",
+    "reference": {
+        "chunk_id_1": { ... } // 引用来源
+    },
+    "trace": [ ... ] // 如果 return_trace=true
+  }
+}
+```

main/manager-api/src/main/java/xiaozhi/modules/knowledge/doc/RAGFlow_Agent接口详解.md

@@ -0,0 +1,233 @@
+## 1. 获取 Agent 列表 - `list_agents`
+**接口描述**: 分页查询当前租户下的所有 Agent 列表，支持按 ID 或标题筛选。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/agents`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+无
+
+#### Query Parameters
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| page | int | 否 | 1 | 页码 |
+| page_size | int | 否 | 30 | 每页条数 |
+| orderby | string | 否 | update_time | 排序字段 (create_time, update_time, title) |
+| desc | boolean | 否 | True | 是否降序排列 (True: 降序, False: 升序) |
+| id | string | 否 | - | 按 Agent ID 精确筛选 |
+| title | string | 否 | - | 按 Agent 标题精确筛选 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": [
+    {
+      "id": "e0d34e2c-...",
+      "title": "My Assistant",
+      "description": "A helpful AI assistant",
+      "dsl": { ... }, // Agent 的 DSL 流程定义
+      "user_id": "tenant_123",
+      "avatar": "", // 头像 Base64 或 URL
+      "canvas_category": "Agent",
+      "create_time": 1715623400000,
+      "update_time": 1715624500000
+    }
+  ]
+}
+```
+
+---
+
+## 2. 创建 Agent - `create_agent`
+**接口描述**: 创建一个新的 Agent，必须包含标题和 DSL 定义。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/agents`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+无
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| title | string | 是 | - | Agent 的名称 (必须唯一) |
+| dsl | object | 是 | - | Agent 的流程定义 (节点、连线配置) |
+| description | string | 否 | - | Agent 的功能描述 |
+| avatar | string | 否 | - | Agent 头像 (Base64 字符串或 URL) |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": true
+}
+```
+
+---
+
+## 3. 更新 Agent - `update_agent`
+**接口描述**: 更新指定 Agent 的配置信息，支持增量更新（仅传递需要修改的字段）。
+**请求方法**: `PUT`
+**接口地址**: `/api/v1/agents/<agent_id>`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| agent_id | string | 是 | 要更新的 Agent ID |
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| title | string | 否 | - | 新的 Agent 名称 |
+| dsl | object | 否 | - | 新的 DSL 流程定义 |
+| description | string | 否 | - | 新的功能描述 |
+| avatar | string | 否 | - | 新的头像 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": true
+}
+```
+
+---
+
+## 4. 删除 Agent - `delete_agent`
+**接口描述**: 根据 ID 删除指定的 Agent。此操作不可恢复。
+**请求方法**: `DELETE`
+**接口地址**: `/api/v1/agents/<agent_id>`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| agent_id | string | 是 | 要删除的 Agent ID |
+
+#### Body Parameters (JSON)
+无
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": true
+}
+```
+
+---
+
+## 5. Webhook 测试触发 - `webhook`
+**接口描述**: 用于测试 Agent 的 Webhook 触发功能。该接口模拟外部系统调用，触发 Agent 按照配置的 "Begin" 节点逻辑开始执行。支持同步等待结果或流式返回（取决于 Agent 配置）。
+**请求方法**: `POST` (支持 GET/PUT/DELETE 等，取决于 Canvas 配置)
+**接口地址**: `/api/v1/webhook_test/<agent_id>`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| agent_id | string | 是 | Agent 的唯一标识符 |
+
+#### Query / Headers / Body Parameters
+**说明**: 此接口的参数完全动态，取决于 Agent 画布中 **"Begin" (开始)** 节点的 **Webhook** 配置。
+- 如果配置了 Query 参数验证，则需在 URL 中传递对应参数。
+- 如果配置了 Header 验证，则需传递对应 Header。
+- **Body**: 通常为 JSON 格式，包含 Agent 运行所需的变量（inputs）或上下文数据。
+
+**Body Example (JSON)**:
+```json
+{
+  "inputs": {
+    "topic": "AI Trends",
+    "style": "professional"
+  },
+  "query": "Start generation"
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json` (或 `text/event-stream`)
+
+**即时响应模式 (Immediately)**:
+```json
+{
+  "code": 0,
+  "data": {
+    "content": "生成的回答内容...",
+    "usage": { ... }
+  }
+}
+```
+
+**流式响应模式 (SSE)**:
+如果不使用 `webhook_test` 而是生产环境 `webhook` 且配置为 SSE，则返回流式数据。但在 `webhook_test` 接口中，通常配合 `webhook_trace` 进行异步调试。
+
+---
+
+## 6. Webhook 执行轨迹查询 - `webhook_trace`
+**接口描述**: 轮询查询 Agent 在 Webhook 测试触发后的执行日志和中间状态。采用长轮询或游标机制，实时获取执行进度。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/webhook_trace/<agent_id>`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| agent_id | string | 是 | Agent 的唯一标识符 |
+
+#### Query Parameters
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| since_ts | float | 否 | 当前时间 | 起始时间戳。返回此时间之后的日志事件。首次调用可不传（获取当前时间作为游标）。 |
+| webhook_id | string | 否 | - | Webhook 会话 ID。用于锁定特定的某次执行记录。首次轮询时不传，接口会返回新生成的 ID。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "webhook_id": "YWdlbnxxxx...",  // 当前追踪的会话 ID (加密串)
+    "finished": false,              // 执行是否已结束 (true/false)
+    "next_since_ts": 1715629999.5,  // 下一次轮询应使用的 since_ts
+    "events": [                     // 本次轮询获取到的新事件列表
+      {
+        "ts": 1715629998.1,
+        "event": "message",         // 事件类型: message, start_to_think, finished, error 等
+        "data": {
+            "content": "思考中...",
+            "reference": []
+        }
+      }
+    ]
+  }
+}
+```
+
+### 💡 最佳实践 (调试流程)
+1.  **初始化**: 调用 `GET /webhook_trace/<id>` (不带参数)，获取 `next_since_ts` (记为 `T0`)。
+2.  **触发**: 调用 `POST /webhook_test/<id>` 发送测试数据。
+3.  **首帧捕获**: 循环调用 `GET /webhook_trace/<id>?since_ts=T0`，直到返回 `webhook_id` (记为 `WID`) 和第一批 `events`。
+4.  **持续追踪**: 使用 `WID` 和响应中的 `next_since_ts` 持续轮询，直到 `data.finished == true`。

main/manager-api/src/main/java/xiaozhi/modules/knowledge/doc/RAGFlow_Chat_Completion接口详解.md

@@ -0,0 +1,164 @@
+# RAGFlow 对话交互接口详解 (Chat Completion & OpenAI Compatibility)
+
+## 5. 对话助手对话 (流式) - `chat_completion`
+**接口描述**: 发送问题给对话助手 (Assistant/Chat) 并获取回复。这是 RAGFlow 最核心的原生对话接口，支持 **Server-Sent Events (SSE)** 流式响应。它会根据助手绑定的知识库进行 RAG 检索生成。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/chats/<chat_id>/completions`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| chat_id | string | 是 | **助手 ID**。 |
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| session_id | string | 是 | - | **会话 ID**。从 `create_chat_session` 获取。 |
+| question | string | 是 | - | **用户问题**。 |
+| stream | boolean | 否 | true | **是否流式响应**。 |
+| quote | boolean | 否 | false | **返回引用**。是否在响应中包含检索到的引用片段。 |
+| doc_ids | string | 否 | - | **限定文档 ID**。多个 ID 用逗号分隔，仅检索指定文档。 |
+| metadata_condition | object | 否 | {} | **元数据过滤**。用于限定检索范围。 |
+
+### 响应参数 (Stream Response)
+**Content-Type**: `text/event-stream`
+
+每一行数据以 `data:` 开头，包含一个 JSON 对象。
+
+**Event Example**:
+```text
+data:{"code": 0, "message": "success", "data": {"answer": "Hello", "reference": {}}}
+
+data:{"code": 0, "message": "success", "data": {"answer": " world!", "reference": {}}}
+
+data:{"code": 0, "message": "success", "data": {"answer": "", "reference": {"chunk_1": {...}}}} // 引用数据
+```
+
+### 响应参数 (Non-Stream Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "answer": "Hello world! This is the generated response.",
+    "reference": {
+      "chunk_id_1": {
+        "content_with_weight": "Original text...",
+        "doc_name": "manual.pdf"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 6. OpenAI 兼容对话 - `chat_completion_openai_like`
+**接口描述**: 提供与 **OpenAI API (`/v1/chat/completions`)** 完全兼容的接口。允许开发者使用 LangChain、OpenAI Python SDK 或其他支持 OpenAI 协议的工具直接调用 RAGFlow，实现无缝迁移。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/chats_openai/<chat_id>/chat/completions`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| chat_id | string | 是 | **助手 ID**。在此上下文中充当 "Base URL" 的一部分。 |
+
+#### Body Parameters (JSON - OpenAI Standard)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| messages | array | 是 | **消息列表**。包含 `role` (system/user/assistant) 和 `content`。 |
+| model | string | 是 | **模型名称**。可以是任意非空字符串 (RAGFlow 会使用助手预设的模型)。 |
+| stream | boolean | 否 | **是否流式**。默认为 `true`。 |
+
+**Request Example**:
+```json
+{
+  "model": "ragflow_default",
+  "messages": [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "Explain quantum physics."}
+  ],
+  "stream": true
+}
+```
+
+### 响应参数 (Stream Response - OpenAI Format)
+**Content-Type**: `text/event-stream`
+
+严格遵循 OpenAI Chunk 格式：
+
+```text
+data: {"id": "chatcmpl-123", "object": "chat.completion.chunk", "created": 1715000000, "model": "model", "choices": [{"index": 0, "delta": {"role": "assistant", "content": ""}, "finish_reason": null}]}
+
+data: {"id": "chatcmpl-123", "object": "chat.completion.chunk", "created": 1715000001, "model": "model", "choices": [{"index": 0, "delta": {"content": "Quantum"}, "finish_reason": null}]}
+
+data: {"id": "chatcmpl-123", "object": "chat.completion.chunk", "created": 1715000002, "model": "model", "choices": [{"index": 0, "delta": {"content": " physics"}, "finish_reason": null}]}
+
+data: [DONE]
+```
+
+---
+
+## 7. 嵌入式 Chatbot 对话 - `chatbot_completions`
+**接口描述**: 专为 **嵌入式窗口 (Embed Window)** 设计的公开对话接口。它通常用于将 RAGFlow 助手作为客服窗口嵌入到第三方网站。与普通接口不同，它通过 `Authorization` Header 传递 **Beta Token** (即 API Key) 进行鉴权，且通常面向最终用户。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/chatbots/<dialog_id>/completions`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dialog_id | string | 是 | **助手 ID** (Dialog ID)。 |
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| question | string | 是 | - | **用户问题**。 |
+| stream | boolean | 否 | true | **是否流式**。 |
+| session_id | string | 否 | - | **会话 ID**。用于维持上下文。 |
+| quote | boolean | 否 | false | **返回引用**。 |
+
+### 响应参数 (Stream Response)
+**Content-Type**: `text/event-stream`
+
+与 `chat_completion` 类似，返回 RAGFlow 原生 SSE 格式。
+
+```text
+data:{"code": 0, "message": "success", "data": {"answer": "Here is the answer...", "reference": {}}}
+```
+
+---
+
+## 8. Chatbot 初始化信息 - `chatbots_inputs`
+**接口描述**: 获取嵌入式 Chatbot 的初始化配置信息。通常在前端组件加载时调用，用于展示助手的头像、名称、开场白 (Prologue) 等信息。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/chatbots/<dialog_id>/info`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dialog_id | string | 是 | **助手 ID**。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "title": "IT Support Bot",          // 助手名称
+    "avatar": "http://...",             // 头像 URL
+    "prologue": "Hi! How can I help?"   // 开场白
+  }
+}
+```

main/manager-api/src/main/java/xiaozhi/modules/knowledge/doc/RAGFlow_Chat_Session接口详解.md

@@ -0,0 +1,208 @@
+# RAGFlow 聊天助手会话管理接口详解 (Chat Assistant Session Management)
+
+## 1. 创建会话 - `create_chat_session`
+**接口描述**: 为指定的聊天助手 (Chat/Assistant) 创建一个新的会话。系统会自动加载该助手的开场白 (Prologue) 作为第一条消息。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/chats/<chat_id>/sessions`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| chat_id | string | 是 | **助手 ID** (Assistant/Dialog ID)。 |
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| name | string | 否 | "New session" | **会话名称**。 |
+| user_id | string | 否 | - | **用户标识**。用于区分不同终端用户的会话。 |
+
+**Request Example**:
+```json
+{
+  "name": "Consulting regarding RAG",
+  "user_id": "client_001"
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "session_uuid_123",
+    "chat_id": "chat_uuid_abc",
+    "name": "Consulting regarding RAG",
+    "user_id": "client_001",
+    "create_time": 1715000000000,
+    "create_date": "2024-05-01 10:00:00",
+    "update_time": 1715000000000,
+    "update_date": "2024-05-01 10:00:00",
+    "messages": [
+      {
+        "role": "assistant",
+        "content": "Hi! I am your AI assistant. How can I help you today?" // 自动加载的开场白
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 2. 获取会话列表 - `list_chat_session`
+**接口描述**: 分页获取指定助手下的会话列表。支持按名称或用户 ID 过滤。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/chats/<chat_id>/sessions`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| chat_id | string | 是 | **助手 ID**。 |
+
+#### Query Parameters
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| page | int | 否 | 1 | **页码**。 |
+| page_size | int | 否 | 30 | **每页数量**。 |
+| orderby | string | 否 | "create_time" | **排序字段**。 |
+| desc | boolean | 否 | true | **是否降序**。 |
+| name | string | 否 | - | **会话名称搜索**。 |
+| id | string | 否 | - | **会话 ID 精确筛选**。 |
+| user_id | string | 否 | - | **用户标识筛选**。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": [
+    {
+      "id": "session_uuid_123",
+      "chat_id": "chat_uuid_abc",
+      "name": "Consulting regarding RAG",
+      "user_id": "client_001",
+      "create_time": 1715000000000,
+      "create_date": "2024-05-01 10:00:00",
+      "update_time": 1715000050000,
+      "update_date": "2024-05-01 10:00:50",
+      "messages": [
+        {
+          "role": "assistant",
+          "content": "Hi! I am your AI assistant. How can I help you today?"
+        },
+        {
+          "role": "user",
+          "content": "What is RAGFlow?"
+        }
+      ]
+    },
+    {
+      "id": "session_uuid_456",
+      "chat_id": "chat_uuid_abc",
+      "name": "New session",
+      "user_id": "client_002",
+      "create_time": 1714900000000,
+      "create_date": "2024-04-30 09:00:00",
+      "update_time": 1714900000000,
+      "update_date": "2024-04-30 09:00:00",
+      "messages": [ ... ]
+    }
+  ]
+}
+```
+
+---
+
+## 3. 更新会话 - `update_chat_session`
+**接口描述**: 更新会话信息。目前主要用于 **重命名** 会话。注意：不能通过此接口修改消息记录 (`messages`)。
+**请求方法**: `PUT`
+**接口地址**: `/api/v1/chats/<chat_id>/sessions/<session_id>`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| chat_id | string | 是 | **助手 ID**。 |
+| session_id | string | 是 | **会话 ID**。 |
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| name | string | 否 | **新的会话名称**。不可为空字符串。 |
+
+**Request Example**:
+```json
+{
+  "name": "RAG Technical Discussion"
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": null
+}
+```
+
+---
+
+## 4. 删除会话 - `delete_chat_session`
+**接口描述**: 批量删除指定助手下的会话。
+**请求方法**: `DELETE`
+**接口地址**: `/api/v1/chats/<chat_id>/sessions`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| chat_id | string | 是 | **助手 ID**。 |
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| ids | array<string> | 否 | **待删除的会话 ID 列表**。若不传该参数，将尝试删除该助手下的**所有会话**（请极其谨慎使用）。 |
+
+**Request Example**:
+```json
+{
+  "ids": ["session_uuid_123", "session_uuid_456"]
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": null // 若全部删除成功
+}
+```
+
+**Response (部分成功时)**:
+```json
+{
+  "code": 0,
+  "message": "Partially deleted 1 sessions with 1 errors",
+  "data": {
+    "success_count": 1,
+    "errors": ["The chat doesn't own the session session_uuid_999"]
+  }
+}
+```

main/manager-api/src/main/java/xiaozhi/modules/knowledge/doc/RAGFlow_Chat接口详解.md

@@ -0,0 +1,213 @@
+## 1. 创建助手应用 - `create`
+**接口描述**: 创建一个新的对话助手（Chat Assistant）。支持配置关联知识库、LLM 模型参数、提示词（Prompt）以及开场白等高级设置。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/chats`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+无
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| name | string | 是 | - | 助手应用名称 (租户内唯一) |
+| avatar | string | 否 | - | 助手头像 (URL 或 Base64 字符串) |
+| description | string | 否 | "A helpful Assistant" | 助手的功能描述 |
+| dataset_ids | array | 否 | [] | 关联的知识库 ID 列表 (必须是当前租户有权限访问的知识库) |
+| llm | object | 否 | - | LLM 模型生成配置 (如模型名称、温度等) |
+| prompt | object | 否 | - | 提示词引擎与检索配置 (包含 System Prompt, Opener, Rerank 等) |
+
+**`llm` 对象详细结构**:
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| model_name | string | 是 | - | 模型名称 (例如: `deepseek-chat`, `gpt-4`, `qwen-turbo`) |
+| temperature | float | 否 | 0.1 | 温度系数 (0.0 ~ 1.0)，越高越随机，越低越确定 |
+| top_p | float | 否 | 0.3 | 核采样概率阈值 |
+| max_tokens | int | 否 | 512 | 单次回答的最大 Token 数限制 |
+| presence_penalty | float | 否 | 0.4 | 话题新鲜度惩罚 (-2.0 ~ 2.0)，正值鼓励讨论新话题 |
+| frequency_penalty | float | 否 | 0.7 | 频率惩罚 (-2.0 ~ 2.0)，正值减少重复词汇 |
+
+**`prompt` 对象详细结构**:
+*注意：此对象包含“提示词配置”与“检索策略配置”两部分。*
+
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| prompt | string | 否 | (内置默认提示词) | **System Prompt (系统提示词)**。给大模型的角色指令，例如 "你是一个客服..."。可使用变量占位符 `{knowledge}`。 |
+| opener | string | 否 | "Hi! I'm your assistant..." | **开场白**。用户进入对话窗口时，助手自动发送的第一条欢迎语。 |
+| show_quote | boolean | 否 | true | **显示引用**。回答中是否标注来源文档 (e.g., [1])。 |
+| variables | array | 否 | `[{"key": "knowledge", "optional": false}]` | **变量列表**。定义用于填充 System Prompt 的变量。`knowledge` 为保留变量，代表检索到的知识片段。 |
+| rerank_model | string | 否 | - | **重排序模型 ID**。配置后会对检索结果进行二次精排 (如 `BAAI/bge-reranker-v2-m3`)。 |
+| keywords_similarity_weight | float | 否 | 0.7 | **关键字权重** (0.0 ~ 1.0)。控制混合检索的比例。更接近 1.0 侧重关键字匹配，更接近 0.0 侧重向量语义匹配。 |
+| similarity_threshold | float | 否 | 0.2 | **相似度阈值** (0.0 ~ 1.0)。低于此相似度的文档块将被过滤，不喂给大模型。 |
+| top_n | int | 否 | 6 | **Top N**。最终截取并输入给大模型的文档块数量。 |
+| empty_response | string | 否 | "Sorry! No relevant..." | **空结果回复**。当没有检索到相关知识库内容时的兜底回复。 |
+| tts | boolean | 否 | false | **启用 TTS**。是否将助手的文本回答自动转为语音播放。 |
+| refine_multiturn | boolean | 否 | true | **多轮对话优化**。是否根据历史上下文重写用户问题 (Query Rewrite) 以提高检索准确率。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "e0d34e2c-1234-5678-9xxx-xxxxxxxxxxxx",
+    "name": "企业知识库助手",
+    "avatar": "http://example.com/avatar.png",
+    "description": "用于回答员工内部问题的 AI",
+    "dataset_ids": ["kb_123", "kb_456"],
+    "llm": {
+      "model_name": "deepseek-chat",
+      "temperature": 0.1,
+      "top_p": 0.3,
+      "max_tokens": 512,
+      "presence_penalty": 0.4,
+      "frequency_penalty": 0.7
+    },
+    "prompt": {
+      "prompt": "你是一个智能助手，请根据以下知识回答问题：\n{knowledge}",
+      "opener": "你好！有什么可以帮你的？",
+      "show_quote": true,
+      "variables": [
+        { "key": "knowledge", "optional": false }
+      ],
+      "rerank_model": "",
+      "keywords_similarity_weight": 0.7,
+      "similarity_threshold": 0.2,
+      "top_n": 8,
+      "empty_response": "抱歉，知识库中没有找到相关答案。",
+      "tts": false,
+      "refine_multiturn": true
+    },
+    "create_time": 1715623400000,
+    "update_time": 1715624500000
+  }
+}
+```
+
+---
+
+## 2. 获取助手列表 - `list_chat`
+**接口描述**: 获取当前租户下的所有助手应用列表。支持分页、排序及按名称/ID筛选。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/chats`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+无
+
+#### Query Parameters
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| page | int | 否 | 1 | 页码 |
+| page_size | int | 否 | 30 | 每页条数 |
+| orderby | string | 否 | create_time | 排序字段 (`create_time`, `update_time`) |
+| desc | boolean | 否 | true | 是否降序排列 (`true`: 降序, `false`: 升序) |
+| name | string | 否 | - | 按名称模糊搜索 (支持 partial match) |
+| id | string | 否 | - | 按 ID 精确筛选 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": [
+    {
+      "id": "e0d34e2c-...",
+      "name": "客服机器人",
+      "avatar": "http://...",
+      "datasets": [
+        {
+          "id": "kb_1",
+          "name": "产品手册",
+          "avatar": "",
+          "chunk_num": 100
+        }
+      ],
+      "llm": { ... },     // (结构同 create 接口响应)
+      "prompt": { ... },  // (结构同 create 接口响应)
+      "create_time": 1715623400000
+    }
+  ]
+}
+```
+
+---
+
+## 3. 更新助手配置 - `update`
+**接口描述**: 更新指定助手应用的配置信息。支持全量或增量更新部分字段。
+**请求方法**: `PUT`
+**接口地址**: `/api/v1/chats/<chat_id>`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| chat_id | string | 是 | 助手应用 ID |
+
+#### Body Parameters (JSON)
+*(以下所有字段均为可选，仅传递需要修改的字段即可)*
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| name | string | - | 新的助手名称 |
+| avatar | string | - | 新的头像 URL 或 Base64 |
+| dataset_ids | array | - | **全量替换**关联的知识库 ID 列表 |
+| llm | object | - | 更新 LLM 配置。需包含 `model_name`，其他字段覆盖更新。 |
+| prompt | object | - | 更新提示词配置。支持增量更新 (e.g. 只改 `opener`)。 |
+| show_quotation | boolean | - | 是否显示引用来源 (此字段直接位于根对象下，对应 prompt.show_quote) |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": null
+}
+```
+
+---
+
+## 4. 批量删除助手 - `delete_chats`
+**接口描述**: 批量删除一个或多个助手应用。
+**请求方法**: `DELETE`
+**接口地址**: `/api/v1/chats`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+无
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| ids | array<string> | 是 | 要删除的助手应用 ID 列表。**⚠️ 注意：若列表为空或不传，虽然后端有全量删除逻辑，但在实际业务中应严谨传递 ID。** |
+
+**Request Example**:
+```json
+{
+  "ids": ["chat_id_1001", "chat_id_1002"]
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+     "success_count": 2, // 成功删除的数量
+     "errors": []        // 失败原因列表 (如 ID 不存在)
+  }
+}
+```

main/manager-api/src/main/java/xiaozhi/modules/knowledge/doc/RAGFlow_Dataset接口详解.md

@@ -0,0 +1,420 @@
+## 1. 创建知识库 - `create`
+**接口描述**: 创建一个新的知识库（Dataset），用于存储和检索文档数据。支持配置嵌入模型（Embedding Model）、解析方法、权限范围等。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/datasets`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+无
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| name | string | 是 | - | **知识库名称**。在同一个租户（Tenant）内必须唯一。 |
+| avatar | string | 否 | "" | **知识库头像**。Base64 编码的图片字符串。 |
+| description | string | 否 | "" | **描述信息**。用于说明知识库的用途或内容概要。 |
+| embedding_model | string | 否 | (系统默认) | **嵌入模型名称** (例如 `BAAI/bge-large-zh-v1.5`)。若不传，则自动使用系统设置的默认 Embedding 模型。 |
+| permission | string | 否 | "me" | **可见权限**。`me`: 仅自己可见；`team`: 团队内所有成员可见。 |
+| chunk_method | string | 否 | "naive" | **默认分块解析方法**。当上传文件未指定解析方式时使用。可选值: `naive` (通用), `manual` (手动), `qa` (Q&A拆分), `table` (表格), `paper` (论文), `book` (书籍), `laws` (法律), `presentation` (PPT), `picture` (图片), `one` (单文档), `email` (邮件)。 |
+| parser_config | object | 否 | (见下文) | **解析器详细配置**。根据 `chunk_method` 的不同而变化。 |
+
+**`parser_config` 默认配置参数 (Naive 通用模式)**:
+| 参数名 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| chunk_token_num | int | 512 | **切片最大 Token 数**。超过该长度会被截断到下一块。 |
+| delimiter | string | "\\n" | **分段分隔符**。用于识别段落边界。 |
+| layout_recognize | string | "DeepDOC" | **布局识别模型**。用于处理复杂文档结构 (如 `DeepDOC` 或 `Simple`)。 |
+| html4excel | boolean | false | **Excel转HTML**。是否将 Excel 表格转为 HTML 格式进行解析。 |
+| auto_keywords | int | 0 | **自动关键词抽取**。0 表示不抽取；N>0 表示为每个切片抽取 N 个关键词。 |
+| auto_questions | int | 0 | **自动问题生成**。0 表示不生成；N>0 表示为每个切片生成 N 个相关问题。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "kb_uuid_12345678",
+    "name": "企业产品手册",
+    "avatar": "",
+    "tenant_id": "tenant_001",
+    "description": "存放所有产品相关的说明文档",
+    "embedding_model": "BAAI/bge-large-zh-v1.5",
+    "permission": "me",
+    "chunk_method": "naive",
+    "parser_config": {
+      "chunk_token_num": 512,
+      "delimiter": "\n",
+      "layout_recognize": "DeepDOC",
+      "html4excel": false,
+      "auto_keywords": 0,
+      "auto_questions": 0
+    },
+    "chunk_count": 0,
+    "document_count": 0,
+    "create_time": 1715623400000,
+    "update_time": 1715624500000
+  }
+}
+```
+
+---
+
+## 2. 删除知识库 - `delete`
+**接口描述**: 批量删除一个或多个知识库。删除知识库将连带删除其中的所有文档和索引数据，**不可恢复**。
+**请求方法**: `DELETE`
+**接口地址**: `/api/v1/datasets`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+无
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| ids | array<string> | 是 | **ID 列表**。指定要删除的知识库 ID。如果传递 `null`，则会**清空当前租户下所有**知识库（高危操作，请谨慎使用）。 |
+
+**Request Example**:
+```json
+{
+  "ids": ["kb_id_101", "kb_id_102"]
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "Successfully deleted 2 datasets, 0 failed...",
+  "data": {
+     "success_count": 2, // 成功删除的数量
+     "errors": []        // 失败的 ID 及原因列表
+  }
+}
+```
+
+---
+
+## 3. 获取知识库列表 - `list_datasets`
+**接口描述**: 获取当前用户（及团队）有权限访问的知识库列表。支持分页、排序和筛选。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/datasets`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+无
+
+#### Query Parameters
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| page | int | 否 | 1 | **页码**。从 1 开始。 |
+| page_size | int | 否 | 30 | **每页条数**。 |
+| orderby | string | 否 | "create_time" | **排序字段**。可选值: `create_time` (创建时间), `update_time` (更新时间), `document_count` (文档数)。 |
+| desc | boolean | 否 | true | **是否降序**。`true`: 降序 (最新的在前); `false`: 升序。 |
+| name | string | 否 | - | **名称筛选**。支持模糊匹配。 |
+| id | string | 否 | - | **ID 筛选**。精确匹配知识库 ID。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": [
+    {
+      "id": "kb_uuid_123",
+      "name": "HR 政策库",
+      "document_count": 12,    // 包含的文档数量
+      "token_num": 10240,      // 总 Token 数
+      "chunk_count": 150,      // 总切片数
+      "create_time": 1715623400000,
+      "permission": "team",
+      "embedding_model": "BAAI/bge-large-zh-v1.5"
+    }
+  ],
+  "total": 1 // 匹配查询条件的总记录数 (用户分页计算)
+}
+```
+
+---
+
+## 4. 更新知识库配置 - `update`
+**接口描述**: 更新指定知识库的配置信息。注意：如果知识库内已有解析过的切片，通常不允许修改嵌入模型 (`embedding_model`)。
+**请求方法**: `PUT`
+**接口地址**: `/api/v1/datasets/<dataset_id>`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | 知识库 ID |
+
+#### Body Parameters (JSON)
+*(以下所有字段均为可选，仅传递需要修改的字段即可)*
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| name | string | - | **新名称**。需保持租户内唯一。 |
+| avatar | string | - | **新头像**。Base64 字符串。 |
+| description | string | - | **新描述**。 |
+| permission | string | - | **新权限**。`me` 或 `team`。 |
+| embedding_model | string | - | **嵌入模型**。**注意**: 仅当知识库为空（chunk_count=0）时才允许修改。 |
+| chunk_method | string | - | **默认解析方法**。修改后将应用于后续新上传的文件 (旧文件解析方式不变)。 |
+| parser_config | object | - | **解析器配置**。全量覆盖旧配置 (结构参考 create 接口)。 |
+| pagerank | int | 0 | **PageRank 权重**。仅在使用 Elasticsearch 引擎且需调整图谱权重时设置。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+      "id": "kb_uuid_...",
+      "name": "新名称",
+      "update_time": 1715629999000,
+      ...
+  }
+}
+```
+
+---
+
+## 5. 获取知识图谱数据 - `knowledge_graph`
+**接口描述**: 获取知识库构建的知识图谱数据，包含节点（Nodes）和边（Edges），用于前端可视化展示（如 ECharts 力导向图）。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/datasets/<dataset_id>/knowledge_graph`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | 知识库 ID |
+
+#### Query Parameters
+无
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "graph": {
+      "nodes": [
+        {
+          "id": "node_1",
+          "label": "人工智能",      // 节点显示的文本
+          "pagerank": 0.05,       // PageRank 权重 (决定节点大小)
+          "color": "#fcb",        // 节点颜色
+          "img": ""               // 节点图标 (如有)
+        },
+        {
+          "id": "node_2",
+          "label": "机器学习",
+          "pagerank": 0.03,
+          "color": "#e2b"
+        }
+      ],
+      "edges": [
+        {
+          "source": "node_1",     // 起始节点 ID
+          "target": "node_2",     // 目标节点 ID
+          "weight": 0.8,          // 边权重 (决定连线粗细)
+          "label": "includes"     // 关系名称 (显示在连线上)
+        }
+      ]
+    },
+    "mind_map": {                 // 思维导图结构的保留字段 (通常用于脑图展示)
+        "root": {
+            "id": "root_node",
+            "children": [...]
+        }
+    }
+  }
+}
+```
+
+---
+
+## 6. 清空知识图谱数据 - `delete_knowledge_graph`
+**接口描述**: 删除指定知识库中已生成的知识图谱索引数据（包括所有实体节点和关系边）。
+**注意**: 此操作**不会**删除原始文档或普通的向量索引，仅仅是重置图谱结构。如果需要重新生成图谱，请再次调用 `chunk` 相关接口或使用 `run_graphrag`。
+**请求方法**: `DELETE`
+**接口地址**: `/api/v1/datasets/<dataset_id>/knowledge_graph`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | 知识库 ID |
+
+#### Body Parameters
+无
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": true
+}
+```
+
+---
+
+## 7. 运行/触发 GraphRAG 索引任务 - `run_graphrag`
+**接口描述**: 触发后台异步任务，对知识库中的文档进行 GraphRAG 索引构建。此过程会使用 LLM 抽取实体（Entities）和关系（Relationships），并构建全局社区摘要。
+**前提条件**: 知识库中必须包含已解析的文档。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/datasets/<dataset_id>/run_graphrag`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | 知识库 ID |
+
+#### Body Parameters (JSON)
+*(Body 可为空 `{}`, 后续版本将扩展以下配置参数)*
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| entity_types | array | ["organization", "person", "geo", "event"] | **(预留)** 指定要抽取的实体类型列表。 |
+| method | string | "light" | **(预留)** 构建模式: `light` (轻量级), `general` (标准), `complex` (深度)。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "graphrag_task_id": "task_uuid_12345678" // 异步任务 ID，用于后续追踪进度
+  }
+}
+```
+
+---
+
+## 8. 运行/触发 RAPTOR 递归摘要任务 - `run_raptor`
+**接口描述**: 触发后台异步任务，对知识库中的文档运行 RAPTOR (Recursive Abstractive Processing for Tree-Organized Retrieval) 算法。
+**功能说明**: 该算法会递归地对文档块进行聚类和摘要，生成多层级的树状索引，显著提升对长文档和复杂问题的回答能力。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/datasets/<dataset_id>/run_raptor`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | 知识库 ID |
+
+#### Body Parameters (JSON)
+*(Body 可为空 `{}`, 后续版本将扩展以下配置参数)*
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| max_cluster | int | 64 | **(预留)** 最大聚类数。 |
+| prompt | string | (内置摘要提示词) | **(预留)** 用于生成摘要的 Prompt。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "raptor_task_id": "task_uuid_87654321" // 异步任务 ID
+  }
+}
+```
+
+---
+
+## 9. 查询 GraphRAG 任务进度 - `trace_graphrag`
+**接口描述**: 查询指定知识库当前 **GraphRAG** 索引构建任务的实时状态。支持长轮询机制监测进度。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/datasets/<dataset_id>/trace_graphrag`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | 知识库 ID |
+
+#### Query Parameters
+无
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "task_uuid_12345678",        // 任务 ID
+    "doc_id": "doc_uuid_...",          // 当前正在处理的文档 ID (如果是多文档任务)
+    "from_page": 0,                    // 当前处理的起始页码
+    "to_page": 10,                     // 当前处理的结束页码
+    "progress": 0.45,                  // **总进度** (0.0 ~ 1.0)。0.0: 未开始/刚开始; 1.0: 完成; -1.0: 失败。
+    "progress_msg": "Extracting entities from chunk 25...", // **当前状态描述**。用于前端展示 Loading 提示。
+    "create_time": 1715623400000,
+    "update_time": 1715624500000
+  }
+}
+```
+
+---
+
+## 10. 查询 RAPTOR 任务进度 - `trace_raptor`
+**接口描述**: 查询指定知识库当前 **RAPTOR** 递归摘要任务的实时状态。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/datasets/<dataset_id>/trace_raptor`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | 知识库 ID |
+
+#### Query Parameters
+无
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "task_uuid_87654321",
+    "progress": 1.0,                   // 进度值。1.0 表示树构建完成。
+    "progress_msg": "Tree construction completed.", // 状态消息。
+    "create_time": 1715629000000
+  }
+}
+```

main/manager-api/src/main/java/xiaozhi/modules/knowledge/doc/RAGFlow_Document接口详解.md

@@ -0,0 +1,757 @@
+## 1. 上传文档 - `upload`
+**接口描述**: 向指定的知识库上传一个或多个文档文件。上传后，文档将立即被存入文件系统/对象存储，并在数据库中创建记录。默认解析状态为 `UNSTART` (未开始)，解析配置将继承自 KnowledgeBase 的默认设置。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/datasets/<dataset_id>/documents`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+**Content-Type**: `multipart/form-data`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | **知识库 ID**。指定文档归属的知识库。 |
+
+#### Form Data Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| file | file | 是 | **文件二进制流**。支持多文件上传 (Multiple Files)。<br>支持格式: PDF, DOCX, TXT, MD, CS, HTML, CSV, XLSX, PPTX 等。<br>单文件大小限制请参考系统配置 (默认通常为 10MB/100MB)。 |
+| parent_path | string | 否 | **父级目录路径**。类似于文件系统的文件夹结构，默认为 `/`。如果指定 (如 `/docs/v1/`)，文档将在该虚拟路径下列出。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": [
+    {
+      "id": "e457f92e3c0411ef8d4c0242ac120003",
+      "thumbnail": null,
+      "dataset_id": "d1234567890abcdef1234567890abcde",
+      "chunk_method": "naive",
+      "pipeline_id": null,
+      "parser_config": {
+        "chunk_token_num": 512,
+        "delimiter": "\\n",
+        "layout_recognize": "DeepDOC",
+        "html4excel": false,
+        "auto_keywords": 0,
+        "auto_questions": 0,
+        "topn_tags": 3,
+        "raptor": {
+          "use_raptor": false
+        },
+        "graphrag": {
+          "use_graphrag": false
+        }
+      },
+      "source_type": "local",
+      "type": "pdf",
+      "created_by": "user_id_123",
+      "name": "UserGuide_v2.pdf",
+      "location": "UserGuide_v2.pdf",
+      "size": 102400,
+      "token_count": 0,
+      "chunk_count": 0,
+      "progress": 0.0,
+      "progress_msg": "",
+      "process_begin_at": null,
+      "process_duration": 0.0,
+      "meta_fields": {},
+      "suffix": "pdf",
+      "run": "UNSTART",
+      "status": "1",
+      "create_time": 1715623400123,
+      "create_date": "2024-05-13 10:03:20",
+      "update_time": 1715623400123,
+      "update_date": "2024-05-13 10:03:20"
+    }
+  ]
+}
+```
+
+---
+
+## 2. 获取文档列表 - `list_docs`
+**接口描述**: 查询知识库下的文档列表。支持分页检索、关键词搜索、状态筛选等功能。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/datasets/<dataset_id>/documents`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | **知识库 ID**。 |
+
+#### Query Parameters
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| page | int | 否 | 1 | **页码**。从 1 开始计数。 |
+| page_size | int | 否 | 30 | **每页数量**。 |
+| orderby | string | 否 | "create_time" | **排序字段**。支持 `create_time` (创建时间), `name` (文件名), `size` (大小) 等。 |
+| desc | boolean | 否 | true | **是否降序**。`true` (最新/最大在前), `false` (最旧/最小在前)。 |
+| id | string | 否 | - | **精确筛选 ID**。仅返回指定 ID 的文档。 |
+| name | string | 否 | - | **精确筛选文件名**。仅返回指定名称的文档。 |
+| keywords | string | 否 | - | **模糊搜索**。匹配文档名称包含该关键词的记录。 |
+| suffix | array | 否 | - | **文件后缀筛选** (如 `pdf`, `docx`)。 |
+| run | array | 否 | - | **运行状态筛选**。可选值: `UNSTART`, `RUNNING`, `CANCEL`, `DONE`, `FAIL`。 |
+| create_time_from | int | 否 | 0 | **起始时间戳** (毫秒)。查询在此时间之后创建的文档。 |
+| create_time_to | int | 否 | 0 | **结束时间戳** (毫秒)。查询在此时间之前创建的文档。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "total": 128,
+    "docs": [
+      {
+        "id": "e457f92e3c0411ef8d4c0242ac120003",
+        "thumbnail": null,
+        "dataset_id": "d1234567890abcdef1234567890abcde",
+        "chunk_method": "naive",
+        "pipeline_id": null,
+        "parser_config": {
+          "chunk_token_num": 512,
+          "delimiter": "\\n",
+          "layout_recognize": "DeepDOC",
+          "html4excel": false,
+          "auto_keywords": 0,
+          "auto_questions": 0,
+          "topn_tags": 3,
+          "raptor": {
+            "use_raptor": false
+          },
+          "graphrag": {
+            "use_graphrag": false
+          }
+        },
+        "source_type": "local",
+        "type": "pdf",
+        "created_by": "user_id_123",
+        "name": "UserGuide_v2.pdf",
+        "location": "UserGuide_v2.pdf",
+        "size": 102400,
+        "token_count": 45000,
+        "chunk_count": 120,
+        "progress": 1.0,
+        "progress_msg": "Parsing finished",
+        "process_begin_at": "2024-05-13 10:05:00",
+        "process_duration": 45.2,
+        "meta_fields": {
+            "author": "RAGFlow Team",
+            "version": "2.0"
+        },
+        "suffix": "pdf",
+        "run": "DONE",
+        "status": "1",
+        "create_time": 1715623400123,
+        "create_date": "2024-05-13 10:03:20",
+        "update_time": 1715623450000,
+        "update_date": "2024-05-13 10:05:45"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 3. 更新文档信息 - `update_doc`
+**接口描述**: 更新文档的名称、状态或解析配置。
+**特别注意**: 如果修改了 `chunk_method` 或 `parser_config`，后端会自动将 `run` 状态重置为 `UNSTART`，并清除已有的 chunk 数据，等待重新解析。
+**请求方法**: `PUT`
+**接口地址**: `/api/v1/datasets/<dataset_id>/documents/<document_id>`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | **知识库 ID**。 |
+| document_id | string | 是 | **文档 ID**。 |
+
+#### Body Parameters (JSON)
+*(仅需传递要修改的字段)*
+
+| 参数名 | 类型 | 说明 |
+|---|---|---|
+| name | string | **新文档名称**。需包含文件后缀且不能改变原始文件类型 (如从 `.pdf` 改为 `.txt` 会导致错误)。 |
+| enabled | boolean | **启用/禁用**。`true`: 启用 (DEFAULT, 对应 status="1"); `false`: 禁用 (对应 status="0")。禁用后该文档不参与检索。 |
+| chunk_method | string | **解析方法**。可选值: `naive`, `manual`, `qa`, `table`, `paper`, `book`, `laws`, `presentation`, `picture`, `one`, `knowledge_graph`, `email`。 |
+| parser_config | object | **解析器详细配置**。应与 `chunk_method` 匹配。以下列出 `naive` (通用) 方法的完整配置参数。 |
+
+**parser_config (Naive 模式全量参数)**:
+| 参数名 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| chunk_token_num | int | 512 | **切片最大 Token 数**。 |
+| delimiter | string | "\\n" | **分段符**。支持转义字符。 |
+| layout_recognize | string | "DeepDOC" | **布局识别模型**。可选 `DeepDOC` 或 `Simple`。 |
+| html4excel | boolean | false | **Excel转HTML**。是否将 Excel 解析为 HTML 表格。 |
+| auto_keywords | int | 0 | **自动关键词数量**。0 表示不抽取。 |
+| auto_questions | int | 0 | **自动问题数量**。0 表示不生成。 |
+| topn_tags | int | 3 | **自动标签数量**。 |
+| raptor | object | `{ "use_raptor": false }` | **RAPTOR 配置**。设置 `use_raptor: true` 可开启递归摘要索引。 |
+| graphrag | object | `{ "use_graphrag": false }` | **GraphRAG 配置**。设置 `use_graphrag: true` 可开启图谱增强。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "e457f92e3c0411ef8d4c0242ac120003",
+    "thumbnail": null,
+    "dataset_id": "d1234567890abcdef1234567890abcde",
+    "chunk_method": "naive",
+    "pipeline_id": null,
+    "parser_config": {
+      "chunk_token_num": 1024,
+      "delimiter": "\\n",
+      "layout_recognize": "DeepDOC",
+      "html4excel": false,
+      "auto_keywords": 0,
+      "auto_questions": 0,
+      "topn_tags": 3,
+      "raptor": {
+        "use_raptor": false
+      },
+      "graphrag": {
+        "use_graphrag": false
+      }
+    },
+    "source_type": "local",
+    "type": "pdf",
+    "created_by": "user_id_123",
+    "name": "Renamed_Guide.pdf",
+    "location": "UserGuide_v2.pdf",
+    "size": 102400,
+    "token_count": 45000,
+    "chunk_count": 0,
+    "progress": 0.0,
+    "progress_msg": "",
+    "process_begin_at": null,
+    "process_duration": 0.0,
+    "meta_fields": {},
+    "suffix": "pdf",
+    "run": "UNSTART",
+    "status": "0",
+    "create_time": 1715623400123,
+    "create_date": "2024-05-13 10:03:20",
+    "update_time": 1715629999000,
+    "update_date": "2024-05-13 12:00:00"
+  }
+}
+```
+
+---
+
+## 4. 删除文档 - `delete`
+**接口描述**: 物理删除一个或多个文档。此操作不可恢复，将同时删除数据库记录、MinIO 中的源文件以及 Elasticsearch 中的所有相关切片索引。
+**请求方法**: `DELETE`
+**接口地址**: `/api/v1/datasets/<dataset_id>/documents`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | **知识库 ID**。 |
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| ids | array<string> | 是 | **文档 ID 列表**。必须指定要删除的文档 ID。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": null
+}
+```
+
+---
+
+## 5. 下载/预览原始文件 - `download`
+**接口描述**: 获取文档的原始二进制文件流。响应头将会包含 `Content-Disposition` 字段，指示浏览器以附件形式下载。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/datasets/<dataset_id>/documents/<document_id>`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | **知识库 ID**。 |
+| document_id | string | 是 | **文档 ID**。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/octet-stream`
+**Content-Disposition**: `attachment; filename="UserGuide_v2.pdf"`
+
+*(直接返回文件的二进制数据流)*
+
+
+## 6. 触发/重试文档解析 - `parse`
+**接口描述**: 手动触发文档的解析任务。通常在上传文件后、或修改了解析配置（如 `chunk_method`）后调用此接口。支持批量触发。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/datasets/<dataset_id>/chunks`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | **知识库 ID**。 |
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| document_ids | array<string> | 是 | **文档 ID 列表**。指定需要（重新）解析的文档 ID。 |
+
+**Request Example**:
+```json
+{
+    "document_ids": ["doc_id_1", "doc_id_2"]
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": null
+}
+```
+
+---
+
+## 7. 停止文档解析 - `stop_parsing`
+**接口描述**: 停止当前正在进行的文档解析任务。
+**请求方法**: `DELETE`
+**接口地址**: `/api/v1/datasets/<dataset_id>/chunks`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | **知识库 ID**。 |
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| document_ids | array<string> | 是 | **文档 ID 列表**。指定要停止解析的任务。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": null
+}
+```
+
+---
+
+## 8. 获取切片列表 - `list_chunks`
+**接口描述**: 获取指定文档已解析出的切片（Chunk）列表。支持分页和关键词搜索。返回结果包含文档的详细元数据和具体的切片内容。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | **知识库 ID**。 |
+| document_id | string | 是 | **文档 ID**。 |
+
+#### Query Parameters
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| page | int | 否 | 1 | **页码**。 |
+| page_size | int | 否 | 30 | **每页数量**。 |
+| keywords | string | 否 | - | **搜索关键词**。在切片内容中进行全文检索。 |
+| id | string | 否 | - | **精确切片 ID**。若指定，则只返回该 ID 对应的切片。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "total": 150,
+    "chunks": [
+      {
+        "id": "e457f92e3c0411ef8d4c0242ac120003_0",
+        "content": "RAGFlow 是一款基于深度文档理解的开源 RAG（检索增强生成）引擎。它旨在为各种规模的企业提供精简的 RAG 工作流。RAGFlow 结合了传统文档处理的稳健性与现代大语言模型（LLM）的生成能力，确保在处理复杂格式数据（如 PDF 表格、扫描件等）时依然能保持极高的召回率和准确性。",
+        "document_id": "doc_uuid_123",
+        "docnm_kwd": "RAGFlow_UserGuide_v2.pdf",
+        "important_keywords": ["RAGFlow", "开源", "深度文档理解", "LLM"],
+        "questions": ["什么是 RAGFlow?", "RAGFlow 的主要特点是什么?"],
+        "image_id": "",
+        "dataset_id": "kb_uuid_456",
+        "available": true,
+        "positions": [1]
+      },
+      {
+        "id": "e457f92e3c0411ef8d4c0242ac120003_1",
+        "content": "主要特性：\n1. **深度文档解析**：内置 DeepDOC 识别引擎，精准还原表格、段落结构。\n2. **多路召回**：支持关键词 + 向量的混合检索。\n3. **可视化编排**：提供基于 Graph 的工作流编排能力。",
+        "document_id": "doc_uuid_123",
+        "docnm_kwd": "RAGFlow_UserGuide_v2.pdf",
+        "important_keywords": ["DeepDOC", "混合检索", "可视化编排"],
+        "questions": [],
+        "image_id": "img_uuid_789",
+        "dataset_id": "kb_uuid_456",
+        "available": true,
+        "positions": [2]
+      }
+    ],
+    "doc": {
+        "id": "doc_uuid_123",
+        "name": "RAGFlow_UserGuide_v2.pdf",
+        "chunk_count": 150,
+        "token_count": 45000,
+        "chunk_method": "naive",
+        "run": "DONE",
+        "status": "1",
+        "progress": 1.0,
+        "progress_msg": "Parsing finished",
+        "process_begin_at": "2024-05-13 10:05:00",
+        "process_duration": 45.2,
+        "meta_fields": {
+             "author": "RAGFlow Team",
+             "version": "2.0"
+        },
+        "create_time": 1715623400123,
+        "create_date": "2024-05-13 10:03:20",
+        "update_time": 1715623450000,
+        "update_date": "2024-05-13 10:05:45",
+        "dataset_id": "kb_uuid_456"
+    }
+  }
+}
+```
+
+---
+
+## 9. 手动新增切片 - `add_chunk`
+**接口描述**: 向指定文档中手动添加一个新的切片。系统会自动计算该切片的向量嵌入 (Embedding)。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | **知识库 ID**。 |
+| document_id | string | 是 | **文档 ID**。 |
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| content | string | 是 | **切片内容**。手动输入的文本内容。 |
+| important_keywords | array<string> | 否 | **重要关键词**。用于关键词检索增强。 |
+| questions | array<string> | 否 | **预设问题**。用于 Q&A 检索模式增强。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "chunk": {
+        "id": "new_chunk_uuid_999",
+        "content": "这是管理员手动添加的一条补充切片，用于修正文档中缺失的关键信息。",
+        "document_id": "doc_uuid_123",
+        "docnm_kwd": "RAGFlow_UserGuide_v2.pdf",
+        "important_keywords": ["手动添加", "补充信息"],
+        "questions": ["如何手动添加切片?"],
+        "image_id": "",
+        "dataset_id": "kb_uuid_456",
+        "available": true,
+        "positions": []
+    }
+  }
+}
+```
+
+---
+
+## 10. 修改切片信息 - `update_chunk`
+**接口描述**: 修改已存在的切片内容、关键词、可用状态等。修改内容后，系统会自动重新计算向量。
+**请求方法**: `PUT`
+**接口地址**: `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks/<chunk_id>`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | **知识库 ID**。 |
+| document_id | string | 是 | **文档 ID**。 |
+| chunk_id | string | 是 | **切片 ID**。 |
+
+#### Body Parameters (JSON)
+*(以下字段均为可选，仅传递需修改的字段)*
+
+| 参数名 | 类型 | 说明 |
+|---|---|---|
+| content | string | **新的切片内容**。 |
+| important_keywords | array<string> | **更新关键词列表**。覆盖原有列表。 |
+| available | boolean | **启用/禁用**。`true`: 启用 (默认); `false`: 禁用 (检索时将忽略此切片)。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": null
+}
+```
+
+---
+
+## 11. 删除切片 - `rm_chunk`
+**接口描述**: 批量删除文档中的指定切片。
+**请求方法**: `DELETE`
+**接口地址**: `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | **知识库 ID**。 |
+| document_id | string | 是 | **文档 ID**。 |
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| chunk_ids | array<string> | 是 | **切片 ID 列表**。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "deleted 2 chunks",
+  "data": null
+}
+```
+
+
+## 12. 获取元数据摘要 - `metadata_summary`
+**接口描述**: 获取知识库中所有文档的元数据摘要信息。通常用于前端展示知识库的数据分布概况，例如不同文件类型的数量统计、文件状态分布等。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/datasets/<dataset_id>/metadata/summary`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | **知识库 ID**。 |
+
+#### Query Parameters
+无
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "summary": {
+      "total_doc_count": 120,
+      "total_token_count": 500000,
+      "file_type_distribution": {
+        "pdf": 80,
+        "docx": 30,
+        "txt": 10
+      },
+      "status_distribution": {
+        "1": 118, // 正常启用
+        "0": 2    // 禁用
+      },
+      "custom_metadata": {
+        "author": {
+            "Alice": 50,
+            "Bob": 30
+        },
+        "department": {
+            "HR": 20,
+            "Engineering": 100
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## 13. 批量更新元数据 - `metadata_batch_update`
+**接口描述**: 对知识库中的文档进行批量元数据修改。支持基于复杂的条件筛选文档，然后执行批量更新或删除元数据字段的操作。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/datasets/<dataset_id>/metadata/update`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| dataset_id | string | 是 | **知识库 ID**。 |
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| selector | object | 否 | **筛选器**。定义要更新哪些文档。如果不传，可能作用于全量文档（请谨慎）。 |
+| updates | array | 否 | **更新操作列表**。包含 `key` 和 `value`。 |
+| deletes | array | 否 | **删除操作列表**。包含 `key`。 |
+
+**Request Example (复杂场景)**:
+```json
+{
+  "selector": {
+    "document_ids": ["doc_id_101", "doc_id_102"],
+    "metadata_condition": {
+       "logic": "and",
+       "conditions": [
+          {"key": "author", "value": "OldName", "operator": "eq"},
+          {"key": "status", "value": "draft", "operator": "eq"}
+       ]
+    }
+  },
+  "updates": [
+    {"key": "author", "value": "Admin"},
+    {"key": "reviewed_by", "value": "ManagerA"}
+  ],
+  "deletes": [
+    {"key": "temp_tag"},
+    {"key": "draft_flag"}
+  ]
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "updated": 2,        // 实际更新成功的文档数量
+    "matched_docs": 2    // 匹配到的文档数量
+  }
+}
+```
+
+---
+
+## 14. 检索测试 (Hit Test) - `retrieval_test`
+**接口描述**: 在指定的知识库中进行模拟检索测试。此接口用于验证分段（Chunk）质量、检索参数（相似度阈值、Top K）的效果，是调试 RAG 效果的核心工具。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/retrieval`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+**注意**: 即使是简单的查询，由于包含较多配置参数，本接口也设计为 `POST` 请求。
+
+### 请求参数 (Request)
+#### Path Parameters
+无
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| dataset_ids | array<string> | 是 | - | **目标知识库 ID 列表**。支持跨多个知识库检索。 |
+| question | string | 是 | - | **用户查询问题**。 |
+| similarity_threshold | float | 否 | 0.2 | **相似度阈值**。低于此分数的 Chunk 将被过滤。 |
+| vector_similarity_weight | float | 否 | 0.3 | **向量权重**。混合检索时，向量检索结果的权重 (0~1)。剩余权重归于关键词检索。 |
+| top_k | int | 否 | 1024 | **初筛数量**。向量检索返回的候选切片数量。 |
+| rerank_id | string | 否 | - | **重排模型 ID**。若指定，将对检索结果进行 Rerank 二次排序。 |
+| highlight | boolean | 否 | true | **高亮匹配**。是否在返回内容中高亮关键词。 |
+| keyword | boolean | 否 | false | **关键词增强**。是否使用 LLM 提取问题关键词以增强检索。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "total": 15,
+    "chunks": [
+      {
+        "id": "e457f92e3c0411ef8d4c0242ac120003_12",
+        "content": "RAGFlow 支持多种文档解析模式，其中 DeepDOC 模式特别适合处理包含大量表格和扫描件的 PDF 文档。它使用深度学习模型识别文档布局，精准提取表格内容。",
+        "document_id": "doc_uuid_123",
+        "dataset_id": "kb_uuid_456",
+        "document_name": "RAGFlow_UserGuide_v2.pdf",
+        "document_keyword": "RAGFlow_UserGuide_v2.pdf",
+        "similarity": 0.88,
+        "vector_similarity": 0.85,
+        "term_similarity": 0.92,
+        "index": 12,
+        "highlight": "RAGFlow 支持多种<em>文档解析模式</em>，其中 <em>DeepDOC</em> 模式特别适合处理包含大量表格和扫描件的 PDF 文档。",
+        "important_keywords": ["DeepDOC", "PDF"],
+        "questions": ["DeepDOC 模式有什么用?"],
+        "image_id": "",
+        "positions": [12]
+      },
+      {
+        "id": "e457f92e3c0411ef8d4c0242ac120003_15",
+        "content": "如果文档主要由纯文本构成，建议使用 Naive 模式。该模式解析速度快，适合通用场景。",
+        "document_id": "doc_uuid_123",
+        "dataset_id": "kb_uuid_456",
+        "document_name": "RAGFlow_UserGuide_v2.pdf",
+        "document_keyword": "RAGFlow_UserGuide_v2.pdf",
+        "similarity": 0.45,
+        "vector_similarity": 0.40,
+        "term_similarity": 0.50,
+        "index": 15,
+        "highlight": "如果文档主要由纯文本构成，建议使用 <em>Naive</em> 模式。",
+        "important_keywords": ["Naive", "纯文本"],
+        "questions": [],
+        "image_id": "",
+        "positions": [15]
+      }
+    ],
+    "doc_aggs": [
+        {
+            "doc_name": "RAGFlow_UserGuide_v2.pdf",
+            "doc_id": "doc_uuid_123",
+            "count": 2
+        }
+    ]
+  }
+}
+```

main/manager-api/src/main/java/xiaozhi/modules/knowledge/doc/RAGFlow_File接口详解.md

@@ -0,0 +1,503 @@
+# RAGFlow 文件管理接口详解 (File Management API)
+
+## 1. 上传文件 - `upload`
+**接口描述**: 上传一个或多个文件到指定文件夹。支持多文件上传 (Multipart)。上传成功后，文件将存储在 MinIO/S3 中，并返回文件元数据列表。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/file/upload`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+**Content-Type**: `multipart/form-data`
+
+### 请求参数 (Request)
+#### Form Data Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| file | file | 是 | **文件二进制流**。支持多文件上传。 |
+| parent_id | string | 否 | **父级目录 ID**。如果省略，默认上传到根目录 (root)。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": [
+    {
+      "id": "e457f92e3c0411ef8d4c0242ac120003",
+      "parent_id": "root_folder_id_123",
+      "tenant_id": "tenant_uuid_456",
+      "created_by": "user_uuid_789",
+      "type": "pdf",
+      "name": "ProjectReport.pdf",
+      "location": "ProjectReport.pdf",
+      "size": 204800,
+      "source_type": "",
+      "create_time": 1715623400123,
+      "create_date": "2024-05-13 10:03:20",
+      "update_time": 1715623400123,
+      "update_date": "2024-05-13 10:03:20"
+    }
+  ]
+}
+```
+
+---
+
+## 2. 新建文件夹 - `create`
+**接口描述**: 在指定父目录下创建一个新的文件夹（逻辑目录）。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/file/create`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| name | string | 是 | **文件夹名称**。同一目录下不可重名。 |
+| parent_id | string | 否 | **父级目录 ID**。省略则默认为根目录。 |
+| type | string | 是 | **类型**。固定值为 `FOLDER` 创建文件夹。 |
+
+**Request Example**:
+```json
+{
+  "name": "Year2024_Reports",
+  "parent_id": "root_folder_id_123",
+  "type": "FOLDER"
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "folder_uuid_abc",
+    "parent_id": "root_folder_id_123",
+    "tenant_id": "tenant_uuid_456",
+    "created_by": "user_uuid_789",
+    "name": "Year2024_Reports",
+    "location": "",
+    "size": 0,
+    "type": "folder",
+    "source_type": "",
+    "create_time": 1715623500000,
+    "create_date": "2024-05-13 10:05:00",
+    "update_time": 1715623500000,
+    "update_date": "2024-05-13 10:05:00"
+  }
+}
+```
+
+---
+
+## 3. 获取文件列表 - `list_files`
+**接口描述**: 分页获取指定文件夹下的文件和子文件夹列表。支持按名称模糊搜索。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/file/list`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Query Parameters
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| parent_id | string | 否 | (Root) | **父级目录 ID**。指定要查看的目录 ID。 |
+| keywords | string | 否 | - | **搜索关键词**。按文件名模糊搜索。 |
+| page | int | 否 | 1 | **页码**。 |
+| page_size | int | 否 | 15 | **每页数量**。 |
+| orderby | string | 否 | "create_time" | **排序字段**。 |
+| desc | boolean | 否 | true | **是否降序**。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "total": 25,
+    "parent_folder": {
+      "id": "root_folder_id_123",
+      "parent_id": "",
+      "tenant_id": "tenant_uuid_456",
+      "created_by": "system",
+      "name": "ROOT",
+      "location": "",
+      "size": 0,
+      "type": "folder",
+      "source_type": "",
+      "create_time": 1710000000000,
+      "create_date": "2024-03-01 00:00:00",
+      "update_time": 1710000000000,
+      "update_date": "2024-03-01 00:00:00"
+    },
+    "files": [
+      {
+        "id": "folder_uuid_abc",
+        "parent_id": "root_folder_id_123",
+        "tenant_id": "tenant_uuid_456",
+        "created_by": "user_uuid_789",
+        "name": "Year2024_Reports",
+        "location": "",
+        "size": 0,
+        "type": "folder",
+        "source_type": "",
+        "create_time": 1715623500000,
+        "create_date": "2024-05-13 10:05:00",
+        "update_time": 1715623500000,
+        "update_date": "2024-05-13 10:05:00"
+      },
+      {
+        "id": "e457f92e3c0411ef8d4c0242ac120003",
+        "parent_id": "root_folder_id_123",
+        "tenant_id": "tenant_uuid_456",
+        "created_by": "user_uuid_789",
+        "name": "ProjectReport.pdf",
+        "location": "ProjectReport.pdf",
+        "size": 204800,
+        "type": "pdf",
+        "source_type": "",
+        "create_time": 1715623400123,
+        "create_date": "2024-05-13 10:03:20",
+        "update_time": 1715623400123,
+        "update_date": "2024-05-13 10:03:20"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 4. 获取文件流 (下载) - `get`
+**接口描述**: 通过文件 ID 下载文件内容。不同于获取元数据，该接口直接返回文件的二进制流（Octet-stream 或 Image 等）。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/file/get/<file_id>`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| file_id | string | 是 | **文件 ID**。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/octet-stream` (或具体 MIME 类型如 `image/png`)
+
+*(返回二进制文件流)*
+
+---
+
+## 5. 下载附件 - `download_attachment`
+**接口描述**: 这是一个通用的附件下载接口，通常用于系统内部引用或特定路径的下载。它使用 `attachment_id`（通常对应 MinIO 中的存储路径/Key）来检索文件。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/file/download/<attachment_id>`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| attachment_id | string | 是 | **附件 ID / 存储 Key**。通常对应底层存储的唯一标识符。 |
+
+#### Query Parameters
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| ext | string | 否 | "markdown" | **文件扩展名**。用于设置响应头中的 Content-Type。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/octet-stream` (或根据 ext 参数推断)
+
+*(返回二进制文件流)*
+
+
+## 6. 重命名文件/文件夹 - `rename`
+**接口描述**: 修改文件或文件夹的名称。对于文件，通常不允许修改扩展名（后缀）。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/file/rename`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| file_id | string | 是 | **目标文件/文件夹 ID**。 |
+| name | string | 是 | **新名称**。需符合文件命名规范，且同一目录下不可重名。 |
+
+**Request Example**:
+```json
+{
+  "file_id": "file_uuid_123",
+  "name": "New_Report_Final.pdf"
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": true
+}
+```
+
+---
+
+## 7. 移动文件/文件夹 - `move`
+**接口描述**: 批量移动文件或文件夹到指定的目录 (Move)。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/file/mv`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| src_file_ids | array<string> | 是 | **源文件/文件夹 ID 列表**。支持批量移动。 |
+| dest_file_id | string | 是 | **目标文件夹 ID**。必须是已存在的文件夹 ID。 |
+
+**Request Example**:
+```json
+{
+  "src_file_ids": ["file_id_1", "file_id_2"],
+  "dest_file_id": "folder_id_target"
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": true
+}
+```
+
+---
+
+## 8. 删除文件/文件夹 - `rm`
+**接口描述**: 批量删除文件或文件夹。如果是文件夹，将递归删除其下的所有内容。此操作不可恢复。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/file/rm`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| file_ids | array<string> | 是 | **待删除的文件/文件夹 ID 列表**。 |
+
+**Request Example**:
+```json
+{
+  "file_ids": ["file_uuid_to_delete_1", "folder_uuid_to_delete_2"]
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": true
+}
+```
+
+---
+
+## 9. 文件转知识库文档 - `convert`
+**接口描述**: 将已上传的文件（File）导入到指定的知识库（Dataset）中，转换为文档（Document）并进行解析。这是一个“文件 -> 知识库”的桥接操作。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/file/convert`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| file_ids | array<string> | 是 | **源文件 ID 列表**。必须是已存在于文件管理系统中的 ID。 |
+| kb_ids | array<string> | 是 | **目标知识库 ID 列表**。文件将被同时导入到这些知识库中。 |
+
+**Request Example**:
+```json
+{
+  "file_ids": ["file_uuid_pdf_1", "file_uuid_txt_2"],
+  "kb_ids": ["dataset_uuid_A"]
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": [
+    {
+      "id": "mapping_uuid_1",
+      "file_id": "file_uuid_pdf_1",
+      "document_id": "doc_uuid_created_in_kb_A",
+      "create_time": 1715623600123,
+      "create_date": "2024-05-13 10:06:40",
+      "update_time": 1715623600123,
+      "update_date": "2024-05-13 10:06:40"
+    },
+    {
+      "id": "mapping_uuid_2",
+      "file_id": "file_uuid_txt_2",
+      "document_id": "doc_uuid_created_in_kb_A",
+      "create_time": 1715623600124,
+      "create_date": "2024-05-13 10:06:40",
+      "update_time": 1715623600124,
+      "update_date": "2024-05-13 10:06:40"
+    }
+  ]
+}
+```
+
+
+## 10. 获取根目录信息 - `get_root_folder`
+**接口描述**: 获取当前用户的根目录文件夹信息。每个用户（Tenant）都有且仅有一个系统自动创建的根目录。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/file/root_folder`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Query Parameters
+无
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "root_folder": {
+      "id": "root_folder_id_123",
+      "parent_id": "",
+      "tenant_id": "tenant_uuid_456",
+      "created_by": "system",
+      "name": "ROOT",
+      "location": "",
+      "size": 0,
+      "type": "folder",
+      "source_type": "",
+      "create_time": 1710000000000,
+      "create_date": "2024-03-01 00:00:00",
+      "update_time": 1710000000000,
+      "update_date": "2024-03-01 00:00:00"
+    }
+  }
+}
+```
+
+---
+
+## 11. 获取父目录信息 - `get_parent_folder`
+**接口描述**: 获取指定文件或文件夹的直接父级目录信息。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/file/parent_folder`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Query Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| file_id | string | 是 | **当前文件/文件夹 ID**。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "parent_folder": {
+      "id": "root_folder_id_123",
+      "parent_id": "",
+      "tenant_id": "tenant_uuid_456",
+      "created_by": "system",
+      "name": "ROOT",
+      "location": "",
+      "size": 0,
+      "type": "folder",
+      "source_type": "",
+      "create_time": 1710000000000,
+      "create_date": "2024-03-01 00:00:00",
+      "update_time": 1710000000000,
+      "update_date": "2024-03-01 00:00:00"
+    }
+  }
+}
+```
+
+---
+
+## 12. 获取完整路径 (面包屑) - `get_all_parent_folders`
+**接口描述**: 获取指定文件或文件夹的所有上级目录列表，形成完整的路径链。返回的列表顺序通常是从根目录到直接父目录（有序）。此接口常用于前端展示“面包屑导航” (Breadcrumbs)。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/file/all_parent_folder`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Query Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| file_id | string | 是 | **目标文件/文件夹 ID**。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "parent_folders": [
+      {
+        "id": "root_folder_id_123",
+        "parent_id": "",
+        "tenant_id": "tenant_uuid_456",
+        "created_by": "system",
+        "name": "ROOT",
+        "location": "",
+        "size": 0,
+        "type": "folder",
+        "source_type": "",
+        "create_time": 1710000000000,
+        "create_date": "2024-03-01 00:00:00",
+        "update_time": 1710000000000,
+        "update_date": "2024-03-01 00:00:00"
+      },
+      {
+         "id": "folder_project_a_id",
+         "parent_id": "root_folder_id_123",
+         "tenant_id": "tenant_uuid_456",
+         "created_by": "user_id_001",
+         "name": "Project A Docs",
+         "location": "",
+         "size": 0,
+         "type": "folder",
+         "source_type": "",
+         "create_time": 1715000000000,
+         "create_date": "2024-05-01 09:00:00",
+         "update_time": 1715000000000,
+         "update_date": "2024-05-01 09:00:00"
+      }
+    ]
+  }
+}
+```

main/manager-api/src/main/java/xiaozhi/modules/knowledge/doc/RAGFlow_SearchBot_AgentBot接口详解.md

@@ -0,0 +1,228 @@
+# RAGFlow 搜索机器人 & AgentBot 接口详解 (SearchBot & AgentBot)
+
+## 1. 搜索机器人对话 - `ask_about_embedded`
+**接口描述**: 面向 **SearchBot (搜索机器人)** 的核心对话接口，通常用于嵌入式知识库问答场景。与普通 Chat 不同，它更侧重于从指定的 `kb_ids` 中直接检索答案，且鉴权使用 `Authorization: Bearer <Beta_Token>` (即 API Key)。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/searchbots/ask`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| question | string | 是 | - | **用户问题**。 |
+| kb_ids | array<string> | 是 | - | **知识库 ID 列表**。限定从哪些知识库中检索。 |
+| search_id | string | 否 | - | **搜索应用 ID**。如果指定，将使用该搜索应用的配置 (Search App Config)。 |
+
+**Request Example**:
+```json
+{
+  "question": "What is the refund policy?",
+  "kb_ids": ["dataset_uuid_1", "dataset_uuid_2"],
+  "search_id": "search_app_uuid_abc"
+}
+```
+
+### 响应参数 (Stream Response)
+**Content-Type**: `text/event-stream`
+
+```text
+data:{"code": 0, "message": "", "data": {"answer": "According to the ", "reference": {}}}
+
+data:{"code": 0, "message": "", "data": {"answer": "policy, refunds are processed within 7 days.", "reference": {"chunk_1": {"content_with_weight": "Refunds...", "doc_name": "policy.pdf"}}}}
+
+data:{"code": 0, "message": "", "data": true} // 结束标志
+```
+
+---
+
+## 2. 获取思维导图 - `mindmap`
+**接口描述**: 根据用户的查询或对话上下文，生成用于前端展示的思维导图数据结构。这通常用于帮助用户梳理复杂的搜索结果或知识结构。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/searchbots/mindmap`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| question | string | 是 | **用户问题/主题**。 |
+| kb_ids | array<string> | 是 | **知识库 ID 列表**。 |
+| search_id | string | 否 | **搜索应用 ID**。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "root": {
+      "text": "Refund Policy", // 根节点文本
+      "children": [
+        {
+          "text": "Conditions",
+          "children": [
+            { "text": "Product defect" },
+            { "text": "Shipping error" }
+          ]
+        },
+        {
+          "text": "Timeline",
+          "children": [
+            { "text": "7-14 business days" }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+---
+
+## 3. 获取相关推荐问题 - `related_questions_embedded`
+**接口描述**: 根据用户当前的问题，生成一组相关的推荐问题 (Suggest Questions)。常用于搜索结果页底部的“猜你想问”。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/searchbots/related_questions`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| question | string | 是 | **用户当前问题**。 |
+| search_id | string | 否 | **搜索应用 ID**。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": [
+    "How to apply for a refund online?",
+    "What items are non-refundable?",
+    "Contact customer support"
+  ]
+}
+```
+
+---
+
+## 4. 获取 AgentBot 输入项 - `begin_inputs`
+**接口描述**: 获取 **AgentBot** (嵌入式 Agent) 的初始化信息，特别是前置输入项 (Prolog/Inputs)。这用于在用户开始对话前，展示一个表单让用户输入必要信息（如姓名、邮箱、API Key 等），这些信息会被传递给 Agent 的 `Begin` 节点。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/agentbots/<agent_id>/inputs`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| agent_id | string | 是 | **Agent ID**。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "title": "Booking Assistant",
+    "avatar": "http://...",
+    "prologue": "Welcome! Please tell me your details.",
+    "inputs": { // `Begin` 节点定义的输入变量
+      "user_name": {
+        "type": "string",
+        "description": "Your Name",
+        "required": true
+      },
+      "email": {
+        "type": "string",
+        "description": "Contact Email",
+        "required": false
+      }
+    },
+    "mode": "chat"
+  }
+}
+```
+
+---
+
+## 5. AgentBot 对话交互 - `agent_bot_completions`
+**接口描述**: 面向 **AgentBot** 的嵌入式对话接口。与 `agent_completions` 类似，但它专为无需登录的 C 端用户设计，通过 API Key 鉴权。它支持完整的 Agent 流程执行和流式响应。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/agentbots/<agent_id>/completions`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| agent_id | string | 是 | **Agent ID**。 |
+
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| session_id | string | 是 | **会话 ID**。 |
+| inputs | object | 否 | **前置输入值**。对应 `begin_inputs` 中定义的变量，如 `{"user_name": "Alice"}`。 |
+| query | string | 否 | **用户输入**。 |
+| stream | boolean | 否 | **是否流式**。默认 `true`。 |
+
+**Request Example**:
+```json
+{
+  "session_id": "session_uuid_123",
+  "inputs": {
+    "user_name": "Bob"
+  },
+  "query": "I want to book a room.",
+  "stream": true
+}
+```
+
+### 响应参数 (Stream Response)
+**Content-Type**: `text/event-stream`
+
+```text
+data:{"event": "message", "data": {"content": "Hello Bob, ", "reference": {}}}
+
+data:{"event": "message", "data": {"content": "when do you want to check in?", "reference": {}}}
+```
+
+---
+
+## 6. Agent OpenAI 兼容接口 - `agents_completion_openai_compatibility`
+**接口描述**: 专门针对 Agent 的 **OpenAI 兼容** 接口。这使得外部工具可以像调用 OpenAI Chat Completion 一样调用 RAGFlow 配置好的复杂 Agent。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/agents_openai/<agent_id>/chat/completions`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Path Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| agent_id | string | 是 | **Agent ID**。 |
+
+#### Body Parameters (OpenAI Standard)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| messages | array | 是 | 包含 `role`, `content` 的消息数组。 |
+| model | string | 是 | 占位符，任意字符串。 |
+| stream | boolean | 否 | 默认 `true`。 |
+
+### 响应参数 (Stream Response - OpenAI Format)
+**Content-Type**: `text/event-stream`
+
+```text
+data: {"id": "agent-chat-uuid", "object": "chat.completion.chunk", "created": 1715000000, "model": "ragflow_agent", "choices": [{"index": 0, "delta": {"role": "assistant", "content": ""}, "finish_reason": null}]}
+
+data: {"id": "agent-chat-uuid", "object": "chat.completion.chunk", "created": 1715000001, "model": "ragflow_agent", "choices": [{"index": 0, "delta": {"content": "Processing your request..."}, "finish_reason": null}]}
+
+data: [DONE]
+```

main/manager-api/src/main/java/xiaozhi/modules/knowledge/doc/RAGFlow_Session_Extra接口详解.md

@@ -0,0 +1,168 @@
+# RAGFlow SearchBot 补充与通用会话接口详解 (Session Extras)
+
+## 1. 获取引用详情 - `detail_share_embedded`
+**接口描述**: 当用户点击 SearchBot 回复中的引用标号 (e.g., [1]) 时，调用此接口获取该引用的详细内容（包括原文片段、来源文档名等）。此接口通常用于前端展示“引用来源”侧边栏或弹窗。它使用 API Key (Beta Token) 进行鉴权。
+**请求方法**: `GET`
+**接口地址**: `/api/v1/searchbots/detail`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Query Parameters
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| search_id | string | 是 | **搜索应用/SearchBot ID**。此接口需要验证调用者是否有权访问该 SearchBot。 |
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": "search_app_uuid_123",
+    "title": "IT Knowledge Base",
+    "description": "Tech support search bot",
+    "kb_ids": ["kb_uuid_1", "kb_uuid_2"],
+    "search_config": {
+      "top_k": 5,
+      "similarity_threshold": 0.5
+    },
+    // 注意：此接口目前主要返回 Search App 的详情配置，
+    // 前端通常使用 search_config 或其他信息来辅助展示引用。
+    // 具体引用内容的文本通常已包含在 `ask` 接口的 `reference` 字段中。
+  }
+}
+```
+
+---
+
+## 2. SearchBot 检索测试 - `retrieval_test_embedded`
+**接口描述**: 面向 SearchBot 的**检索效果测试**接口。它不通过 LLM 生成答案，而是直接返回 RAG 检索到的文档片段 (`chunks`)。这用于调试 SearchBot 的检索参数（如相似度阈值、Top-K）是否合理。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/searchbots/retrieval_test`
+**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
+
+### 请求参数 (Request)
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| kb_id | string/array | 是 | - | **知识库 ID** (或列表)。支持单个 ID 字符串或 ID 列表。 |
+| question | string | 是 | - | **测试查询词**。 |
+| page | int | 否 | 1 | **页码**。 |
+| size | int | 否 | 30 | **每页数量**。 |
+| doc_ids | array<string> | 否 | - | **限定文档 ID**。仅在指定文档中检索。 |
+| similarity_threshold | float | 否 | 0.0 | **相似度阈值**。 |
+| top_k | int | 否 | 1024 | **Top-K 数量**。 |
+| highlight | boolean | 否 | false | **高亮匹配**。是否在返回内容中标记匹配关键词。 |
+
+**Request Example**:
+```json
+{
+  "kb_id": ["dataset_uuid_1"],
+  "question": "refund policy",
+  "top_k": 5,
+  "highlight": true
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "total": 12, // 命中总是
+    "chunks": [
+      {
+        "content_with_weight": "Refunds are processed within <em>7 days</em>...", // 支持高亮
+        "doc_name": "policy.pdf",
+        "doc_id": "doc_uuid_101",
+        "similarity": 0.92,
+        "img_id": ""
+      },
+      {
+        "content_with_weight": "Product return guidelines...",
+        "doc_name": "guidelines.docx",
+        "doc_id": "doc_uuid_102",
+        "similarity": 0.88
+      }
+    ],
+    "labels": [] // 如果启用了查询标签功能
+  }
+}
+```
+
+---
+
+## 3. 通用会话问答 - `ask_about`
+**接口描述**: **内部/测试用**的通用会话问答接口。与 `ask_embedded` 不同，此接口通常用于 RAGFlow 控制台内部的“调试”或“预览”功能，鉴权依赖用户的登录 Token (User Token)，且必须显式指定 `dataset_ids`。它不绑定特定的 Chat/Agent/SearchBot 配置。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/sessions/ask`
+**鉴权方式**: Header `Authorization: Bearer <USER_TOKEN>`
+
+### 请求参数 (Request)
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| question | string | 是 | **用户问题**。 |
+| dataset_ids | array<string> | 是 | **知识库 ID 列表**。必须是当前用户有权访问的知识库。 |
+
+**Request Example**:
+```json
+{
+  "question": "Summary of report",
+  "dataset_ids": ["dataset_uuid_internal_1"]
+}
+```
+
+### 响应参数 (Stream Response)
+**Content-Type**: `text/event-stream`
+
+```text
+data:{"code": 0, "message": "", "data": {"answer": "Here is the summary:", "reference": {}}}
+
+data:{"code": 0, "message": "", "data": {"answer": " The report indicates...", "reference": {}}}
+
+data:{"code": 0, "message": "", "data": true} // 结束
+```
+
+---
+
+## 4. 通用相关问题 - `related_questions`
+**接口描述**: **内部/测试用**的通用相关问题推荐接口。根据用户的问题和行业背景，利用 LLM 生成推荐问题。通常用于内部测试台。
+**请求方法**: `POST`
+**接口地址**: `/api/v1/sessions/related_questions`
+**鉴权方式**: Header `Authorization: Bearer <USER_TOKEN>`
+
+### 请求参数 (Request)
+#### Body Parameters (JSON)
+| 参数名 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| question | string | 是 | - | **原始问题/关键词**。 |
+| industry | string | 否 | "" | **行业背景** (e.g., "Finance", "Healthcare")。帮助 LLM 生成更专业的推荐。 |
+
+**Request Example**:
+```json
+{
+  "question": "Data privacy",
+  "industry": "IT"
+}
+```
+
+### 响应参数 (Response)
+**Content-Type**: `application/json`
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": [
+    "GDPR compliance checklist",
+    "Data encryption standards",
+    "User consent management"
+  ]
+}
+```

main/manager-api/src/main/java/xiaozhi/modules/knowledge/doc/RAGFlow_外部API清单_按文件分组.md

@@ -0,0 +1,98 @@
+# RAGFlow External API Reference (Grouped by File)
+
+## File: `api/apps/sdk/agents.py`
+| Function Name | URL Pattern | Notes |
+|---|---|---|
+| `list_agents` | `/api/v1/agents` | List Agents |
+| `create_agent` | `/api/v1/agents` | Create Agent |
+| `update_agent` | `/api/v1/agents/<agent_id>` | Update Agent |
+| `delete_agent` | `/api/v1/agents/<agent_id>` | Delete Agent |
+| `webhook` | `/api/v1/webhook_test/<agent_id>` | Webhook Test |
+| `webhook_trace` | `/api/v1/webhook_trace/<agent_id>` | Webhook Trace |
+
+## File: `api/apps/sdk/chat.py`
+| Function Name | URL Pattern | Notes |
+|---|---|---|
+| `create` | `/api/v1/chats` | Create Chat |
+| `delete_chats` | `/api/v1/chats` | Delete Chat |
+| `list_chat` | `/api/v1/chats` | List Chats |
+| `update` | `/api/v1/chats/<chat_id>` | Update Chat |
+
+## File: `api/apps/sdk/dataset.py`
+| Function Name | URL Pattern | Notes |
+|---|---|---|
+| `create` | `/api/v1/datasets` | Create Dataset |
+| `delete` | `/api/v1/datasets` | Delete Dataset |
+| `list_datasets` | `/api/v1/datasets` | List Datasets |
+| `update` | `/api/v1/datasets/<dataset_id>` | Update Dataset |
+| `knowledge_graph` | `/api/v1/datasets/<dataset_id>/knowledge_graph` | Knowledge Graph |
+| `delete_knowledge_graph` | `/api/v1/datasets/<dataset_id>/knowledge_graph` | Delete Knowledge Graph |
+| `run_graphrag` | `/api/v1/datasets/<dataset_id>/run_graphrag` | Run GraphRAG |
+| `run_raptor` | `/api/v1/datasets/<dataset_id>/run_raptor` | Run Raptor |
+| `trace_graphrag` | `/api/v1/datasets/<dataset_id>/trace_graphrag` | Trace GraphRAG |
+| `trace_raptor` | `/api/v1/datasets/<dataset_id>/trace_raptor` | Trace Raptor |
+
+## File: `api/apps/sdk/dify_retrieval.py`
+| Function Name | URL Pattern | Notes |
+|---|---|---|
+| `retrieval` | `/api/v1/dify/retrieval` | Dify Retrieval |
+
+## File: `api/apps/sdk/doc.py`
+| Function Name | URL Pattern | Notes |
+|---|---|---|
+| `parse` | `/api/v1/datasets/<dataset_id>/chunks` | Parse Document Chunks |
+| `stop_parsing` | `/api/v1/datasets/<dataset_id>/chunks` | Stop Parsing |
+| `upload` | `/api/v1/datasets/<dataset_id>/documents` | Upload Document |
+| `list_docs` | `/api/v1/datasets/<dataset_id>/documents` | List Documents |
+| `delete` | `/api/v1/datasets/<dataset_id>/documents` | Delete Document |
+| `update_doc` | `/api/v1/datasets/<dataset_id>/documents/<document_id>` | Update Document |
+| `download` | `/api/v1/datasets/<dataset_id>/documents/<document_id>` | Download Document |
+| `list_chunks` | `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks` | List Chunks |
+| `add_chunk` | `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks` | Add Chunk |
+| `update_chunk` | `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks/<chunk_id>` | Update Chunk |
+| `rm_chunk` | `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks` | Remove Chunk |
+| `metadata_summary` | `/api/v1/datasets/<dataset_id>/metadata/summary` | Metadata Summary |
+| `metadata_batch_update` | `/api/v1/datasets/<dataset_id>/metadata/update` | Batch Update Metadata |
+| `retrieval_test` | `/api/v1/retrieval` | Retrieval Test |
+
+## File: `api/apps/sdk/files.py`
+| Function Name | URL Pattern | Notes |
+|---|---|---|
+| `get_all_parent_folders` | `/api/v1/file/all_parent_folder` | Get All Parent Folders |
+| `convert` | `/api/v1/file/convert` | File Convert |
+| `create` | `/api/v1/file/create` | File Create |
+| `download_attachment` | `/api/v1/file/download/<attachment_id>` | Download Attachment |
+| `get` | `/api/v1/file/get/<file_id>` | Get File |
+| `list_files` | `/api/v1/file/list` | List Files |
+| `move` | `/api/v1/file/mv` | Move File |
+| `get_parent_folder` | `/api/v1/file/parent_folder` | Get Parent Folder |
+| `rename` | `/api/v1/file/rename` | Rename File |
+| `rm` | `/api/v1/file/rm` | Remove File |
+| `get_root_folder` | `/api/v1/file/root_folder` | Get Root Folder |
+| `upload` | `/api/v1/file/upload` | Upload File |
+
+## File: `api/apps/sdk/session.py`
+| Function Name | URL Pattern | Notes |
+|---|---|---|
+| `agent_bot_completions` | `/api/v1/agentbots/<agent_id>/completions` | Agent Bot completion |
+| `begin_inputs` | `/api/v1/agentbots/<agent_id>/inputs` | Get Agent Bot inputs |
+| `agent_completions` | `/api/v1/agents/<agent_id>/completions` | Agent completion |
+| `create_agent_session` | `/api/v1/agents/<agent_id>/sessions` | Create Agent Session |
+| `list_agent_session` | `/api/v1/agents/<agent_id>/sessions` | List Agent Sessions |
+| `delete_agent_session` | `/api/v1/agents/<agent_id>/sessions` | Delete Agent Session |
+| `agents_completion_openai_compatibility` | `/api/v1/agents_openai/<agent_id>/chat/completions` | OpenAI compatible Agent completion |
+| `chatbot_completions` | `/api/v1/chatbots/<dialog_id>/completions` | Chatbot completion |
+| `chatbots_inputs` | `/api/v1/chatbots/<dialog_id>/info` | Chatbot info |
+| `chat_completion` | `/api/v1/chats/<chat_id>/completions` | Chat completion |
+| `create` | `/api/v1/chats/<chat_id>/sessions` | Create Chat Session |
+| `list_session` | `/api/v1/chats/<chat_id>/sessions` | List Chat Sessions |
+| `delete` | `/api/v1/chats/<chat_id>/sessions` | Delete Chat Session |
+| `update` | `/api/v1/chats/<chat_id>/sessions/<session_id>` | Update Chat Session |
+| `chat_completion_openai_like` | `/api/v1/chats_openai/<chat_id>/chat/completions` | OpenAI compatible Chat completion |
+| `ask_about_embedded` | `/api/v1/searchbots/ask` | Searchbot Ask |
+| `detail_share_embedded` | `/api/v1/searchbots/detail` | Searchbot Detail |
+| `mindmap` | `/api/v1/searchbots/mindmap` | Searchbot Mindmap |
+| `related_questions_embedded` | `/api/v1/searchbots/related_questions` | Searchbot Related Questions |
+| `retrieval_test_embedded` | `/api/v1/searchbots/retrieval_test` | Searchbot Retrieval Test |
+| `ask_about` | `/api/v1/sessions/ask` | Session Ask |
+| `related_questions` | `/api/v1/sessions/related_questions` | Session Related Questions |

main/manager-api/src/main/java/xiaozhi/modules/knowledge/doc/README.md

@@ -0,0 +1,45 @@
+# RAGFlow API 接口文档索引 (Unofficial Detailed Guide)
+
+本文档汇集了 RAGFlow 核心模块的 API 详解。所有文档均遵循 **Zero Omissions (无省略)** 原则，全字段展开并包含中文注释。
+
+## 📚 1. 知识库与文档管理 (Knowledge & Documents)
+核心的数据管理模块，负责上传文件、解析文档与建立索引。
+
+- **[知识库管理 (Dataset)](./RAGFlow_Dataset接口详解.md)**
+  - 涵盖知识库的创建、列表查询、更新、删除等接口。
+- **[文档处理 (Document)](./RAGFlow_Document接口详解.md)**
+  - 涵盖文档的上传 (Upload)、解析配置更新 (Update)、解析状态查询 (Run Status)。
+  - **切片管理**: 解析后的 Chunk 列表查询、增删改查。
+  - **检索测试**: 直接对知识库进行召回测试 (Retrieval Test)。
+- **[文件管理 (File)](./RAGFlow_File接口详解.md)**
+  - 类似网盘的文件操作体系。
+  - **CRUD**: 上传、下载、列表。
+  - **目录**: 文件夹创建、面包屑导航 (`get_all_parent_folders`)。
+  - **操作**: 移动、重命名、删除、导入知识库 (`convert`).
+
+## 💬 2. 聊天助手 (Chat Assistant)
+RAGFlow 原生的对话助手体系，基于 Assistant (Dialog) 模型。
+
+- **[会话管理 (Chat Session)](./RAGFlow_Chat_Session接口详解.md)**
+  - 管理 `/chats/` 下的会话生命周期。
+  - 创建会话、获取历史记录、重命名、批量删除。
+- **[对话交互 (Chat Completion)](./RAGFlow_Chat_Completion接口详解.md)**
+  - **Core Chat**: 原生流式对话 (`/chats/<id>/completions`), 支持引用 (`quote`)。
+  - **OpenAI Compatible**: 完美兼容 OpenAI `/v1/chat/completions` 协议。
+  - **Embedded Bot**: 面向 C 端嵌入窗口的对话接口 (`/chatbots/`).
+
+## 🤖 3. Agent 与 机器人 (Agent & Bots)
+基于 Graph (DAG) 编排的复杂应用与各类机器人扩展。
+
+- **[Agent 与 Dify 兼容 (Agent & Dify)](./RAGFlow_Agent_Dify接口详解.md)**
+  - **Agent Session**: Agent 的会话管理与流式对话 (`agent_completions`)。
+  - **Dify Adapter**: 兼容 Dify 协议的检索接口 (`retrieval`).
+- **[SearchBot 与 AgentBot](./RAGFlow_SearchBot_AgentBot接口详解.md)**
+  - **SearchBot**: 纯搜索机器人，支持思维导图 (`mindmap`)、相关问题 (`related_questions`).
+  - **AgentBot**: 嵌入式 Agent，支持前置表单 (`begin_inputs`).
+  - **Agent OpenAI**: Agent 的 OpenAI 兼容接口。
+
+## 🛠️ 4. 其他 (Extras)
+- **[通用与补充接口 (Session Extras)](./RAGFlow_Session_Extra接口详解.md)**
+  - **引用详情**: 获取 SearchBot 引用来源 (`detail_share_embedded`).
+  - **通用问答**: 内部调试用的直接问答 (`ask_about`).

main/manager-api/src/main/java/xiaozhi/modules/knowledge/dto/DocumentDTO.java

@@ -0,0 +1,68 @@
+package xiaozhi.modules.knowledge.dto;
+
+import java.io.Serializable;
+import java.util.Date;
+import java.util.Map;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+/**
+ * 文档 DTO
+ */
+@Data
+@Schema(description = "知识库文档")
+public class DocumentDTO implements Serializable {
+    private static final long serialVersionUID = 1L;
+
+    @Schema(description = "本地ID")
+    private String id;
+
+    @Schema(description = "知识库ID")
+    private String datasetId;
+
+    @Schema(description = "RAGFlow文档ID")
+    private String documentId;
+
+    @Schema(description = "文档名称")
+    private String name;
+
+    @Schema(description = "文件大小")
+    private Long size;
+
+    @Schema(description = "文件类型")
+    private String type;
+
+    @Schema(description = "分块方法")
+    private String chunkMethod;
+
+    @Schema(description = "解析配置")
+    private Map<String, Object> parserConfig;
+
+    @Schema(description = "处理状态 (1:解析中 3:成功 4:失败)")
+    private Integer status;
+
+    @Schema(description = "错误信息")
+    private String error;
+
+    @Schema(description = "分块数量")
+    private Integer chunkCount;
+
+    @Schema(description = "Token数量")
+    private Long tokenCount;
+
+    @Schema(description = "是否启用")
+    private Integer enabled;
+
+    @Schema(description = "创建时间")
+    private Date createdAt;
+
+    @Schema(description = "更新时间")
+    private Date updatedAt;
+
+    @Schema(description = "上传进度 (虚拟字段)")
+    private Double progress;
+
+    @Schema(description = "缩略图/预览图 (虚拟字段)")
+    private String thumbnail;
+}

main/manager-api/src/main/java/xiaozhi/modules/knowledge/dto/KnowledgeBaseDTO.java

@@ -0,0 +1,70 @@
+package xiaozhi.modules.knowledge.dto;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.util.Date;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+@Data
+@Schema(description = "知识库知识库")
+public class KnowledgeBaseDTO implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    @Schema(description = "唯一标识")
+    private String id;
+
+    @Schema(description = "知识库ID")
+    private String datasetId;
+
+    @Schema(description = "RAG模型配置ID")
+    private String ragModelId;
+
+    @Schema(description = "知识库名称")
+    private String name;
+
+    @Schema(description = "知识库头像(Base64)")
+    private String avatar;
+
+    @Schema(description = "知识库描述")
+    private String description;
+
+    @Schema(description = "嵌入模型名称")
+    private String embeddingModel;
+
+    @Schema(description = "权限设置: me/team")
+    private String permission;
+
+    @Schema(description = "分块方法")
+    private String chunkMethod;
+
+    @Schema(description = "解析器配置(JSON String)")
+    private String parserConfig;
+
+    @Schema(description = "分块总数")
+    private Long chunkCount;
+
+    @Schema(description = "总Token数")
+    private Long tokenNum;
+
+    @Schema(description = "状态(0:禁用 1:启用)")
+    private Integer status;
+
+    @Schema(description = "创建者")
+    private Long creator;
+
+    @Schema(description = "创建时间")
+    private Date createdAt;
+
+    @Schema(description = "更新者")
+    private Long updater;
+
+    @Schema(description = "更新时间")
+    private Date updatedAt;
+
+    @Schema(description = "文档数量")
+    private Integer documentCount;
+}

main/manager-api/src/main/java/xiaozhi/modules/knowledge/dto/KnowledgeFilesDTO.java

@@ -0,0 +1,119 @@
+package xiaozhi.modules.knowledge.dto;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.util.Date;
+import java.util.Map;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import lombok.Data;
+
+@Data
+@Schema(description = "知识库文档")
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class KnowledgeFilesDTO implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+    @Schema(description = "唯一标识")
+    private String id;
+
+    @Schema(description = "文档ID")
+    private String documentId;
+
+    @Schema(description = "知识库ID")
+    private String datasetId;
+
+    @Schema(description = "文档名称")
+    private String name;
+
+    @Schema(description = "文档类型")
+    private String fileType;
+
+    @Schema(description = "文件大小（字节）")
+    private Long fileSize;
+
+    @Schema(description = "文件路径")
+    private String filePath;
+
+    @Schema(description = "解析进度 (0.0 ~ 1.0)")
+    private Double progress;
+
+    @Schema(description = "缩略图 (Base64 或 URL)")
+    private String thumbnail;
+
+    @Schema(description = "解析耗时 (单位: 秒)")
+    private Double processDuration;
+
+    @Schema(description = "来源类型 (local, s3, url 等)")
+    private String sourceType;
+
+    @Schema(description = "元数据字段 (Map 格式)")
+    private Map<String, Object> metaFields;
+
+    @Schema(description = "分块方法")
+    private String chunkMethod;
+
+    @Schema(description = "解析器配置")
+    private Map<String, Object> parserConfig;
+
+    @Schema(description = "可用状态 (1: 启用/正常, 0: 禁用/失效)")
+    private String status;
+
+    @Schema(description = "运行状态 (UNSTART/RUNNING/CANCEL/DONE/FAIL)")
+    private String run;
+
+    @Schema(description = "创建者")
+    private Long creator;
+
+    @Schema(description = "创建时间")
+    private Date createdAt;
+
+    @Schema(description = "更新者")
+    private Long updater;
+
+    @Schema(description = "更新时间")
+    private Date updatedAt;
+
+    @Schema(description = "分块数量")
+    private Integer chunkCount;
+
+    @Schema(description = "Token数量")
+    private Long tokenCount;
+
+    @Schema(description = "解析错误信息")
+    private String error;
+
+    // 文档解析状态常量定义
+    private static final Integer STATUS_UNSTART = 0;
+    private static final Integer STATUS_RUNNING = 1;
+    private static final Integer STATUS_CANCEL = 2;
+    private static final Integer STATUS_DONE = 3;
+    private static final Integer STATUS_FAIL = 4;
+
+    /**
+     * 获取文档解析状态码（基于run字段转换）
+     */
+    public Integer getParseStatusCode() {
+        if (run == null) {
+            return STATUS_UNSTART;
+        }
+
+        // RAGFlow根据run字段的值直接映射到对应的状态码
+        switch (run.toUpperCase()) {
+            case "RUNNING":
+                return STATUS_RUNNING;
+            case "CANCEL":
+                return STATUS_CANCEL;
+            case "DONE":
+                return STATUS_DONE;
+            case "FAIL":
+                return STATUS_FAIL;
+            case "UNSTART":
+            default:
+                return STATUS_UNSTART;
+        }
+    }
+
+}

main/manager-api/src/main/java/xiaozhi/modules/knowledge/dto/agent/AgentDTO.java

@@ -0,0 +1,421 @@
+package xiaozhi.modules.knowledge.dto.agent;
+
+import lombok.*;
+import io.swagger.v3.oas.annotations.media.Schema;
+import java.io.Serializable;
+import java.util.List;
+import java.util.Map;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import jakarta.validation.constraints.*;
+
+@Schema(description = "智能体 (Agent) 管理聚合 DTO")
+public class AgentDTO {
+
+    // ========== 1. Agent 管理 (CRUD) - 对应 RAGFlow_Agent接口详解 ==========
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "Agent 创建请求")
+    public static class CreateReq implements Serializable {
+        @Schema(description = "Agent 标题", requiredMode = Schema.RequiredMode.REQUIRED, example = "My Agent")
+        @NotBlank(message = "Agent 标题不能为空")
+        @JsonProperty("title")
+        private String title;
+
+        @Schema(description = "DSL 定义 (画布 JSON)", requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotNull(message = "DSL 定义不能为空")
+        @JsonProperty("dsl")
+        private Map<String, Object> dsl;
+
+        @Schema(description = "描述", example = "这是一个测试 Agent")
+        @JsonProperty("description")
+        private String description;
+
+        @Schema(description = "头像 URL", example = "http://example.com/avatar.png")
+        @JsonProperty("avatar")
+        private String avatar;
+    }
+
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "Agent 更新请求")
+    public static class UpdateReq implements Serializable {
+        @Schema(description = "Agent 标题", example = "Updated Agent")
+        @JsonProperty("title")
+        private String title;
+
+        @Schema(description = "DSL 定义 (画布 JSON)")
+        @JsonProperty("dsl")
+        private Map<String, Object> dsl;
+
+        @Schema(description = "描述")
+        @JsonProperty("description")
+        private String description;
+
+        @Schema(description = "头像 URL")
+        @JsonProperty("avatar")
+        private String avatar;
+    }
+
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "Agent 列表请求")
+    public static class ListReq implements Serializable {
+        @Schema(description = "页码", defaultValue = "1")
+        @JsonProperty("page")
+        @Builder.Default
+        private Integer page = 1;
+
+        @Schema(description = "每页大小", defaultValue = "10")
+        @JsonProperty("page_size")
+        @Builder.Default
+        private Integer pageSize = 10;
+
+        @Schema(description = "排序字段", defaultValue = "update_time")
+        @JsonProperty("orderby")
+        @Builder.Default
+        private String orderby = "update_time";
+
+        @Schema(description = "是否降序", defaultValue = "true")
+        @JsonProperty("desc")
+        @Builder.Default
+        private Boolean desc = true;
+
+        @Schema(description = "Agent ID 过滤")
+        @JsonProperty("id")
+        private String id;
+
+        @Schema(description = "标题模糊搜索")
+        @JsonProperty("title")
+        private String title;
+    }
+
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "Agent 响应对象")
+    public static class AgentVO implements Serializable {
+        @Schema(description = "Agent ID")
+        @JsonProperty("id")
+        private String id;
+
+        @Schema(description = "标题")
+        @JsonProperty("title")
+        private String title;
+
+        @Schema(description = "描述")
+        @JsonProperty("description")
+        private String description;
+
+        @Schema(description = "头像")
+        @JsonProperty("avatar")
+        private String avatar;
+
+        @Schema(description = "DSL 定义")
+        @JsonProperty("dsl")
+        private Map<String, Object> dsl;
+
+        @Schema(description = "创建者 ID")
+        @JsonProperty("user_id")
+        private String userId;
+
+        @Schema(description = "画布分类")
+        @JsonProperty("canvas_category")
+        private String canvasCategory;
+
+        @Schema(description = "创建时间 (时间戳)")
+        @JsonProperty("create_time")
+        private Long createTime;
+
+        @Schema(description = "更新时间 (时间戳)")
+        @JsonProperty("update_time")
+        private Long updateTime;
+    }
+
+    // ========== 2. Webhook 调试与追踪 - 对应 RAGFlow_Agent接口详解 ==========
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "Webhook 触发请求 (参数动态)")
+    public static class WebhookTriggerReq implements Serializable {
+        @Schema(description = "输入变量", requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotNull(message = "输入变量不能为空")
+        @JsonProperty("inputs")
+        private Map<String, Object> inputs;
+
+        @Schema(description = "查询词", example = "Hello")
+        @JsonProperty("query")
+        private String query;
+    }
+
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "Webhook 追踪请求")
+    public static class WebhookTraceReq implements Serializable {
+        @Schema(description = "时间戳游标", example = "1700000000.0")
+        @JsonProperty("since_ts")
+        private Double sinceTs;
+
+        @Schema(description = "Webhook ID")
+        @JsonProperty("webhook_id")
+        private String webhookId;
+    }
+
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "Webhook 追踪响应")
+    public static class WebhookTraceVO implements Serializable {
+        @Schema(description = "Webhook ID")
+        @JsonProperty("webhook_id")
+        private String webhookId;
+
+        @Schema(description = "是否结束")
+        @JsonProperty("finished")
+        private Boolean finished;
+
+        @Schema(description = "下一次查询的时间戳游标")
+        @JsonProperty("next_since_ts")
+        private Double nextSinceTs;
+
+        @Schema(description = "事件列表")
+        @JsonProperty("events")
+        private List<TraceEvent> events;
+
+        @Data
+        @Builder
+        @NoArgsConstructor
+        @AllArgsConstructor
+        @Schema(description = "追踪事件项")
+        public static class TraceEvent implements Serializable {
+            @Schema(description = "时间戳")
+            @JsonProperty("ts")
+            private Double ts;
+
+            @Schema(description = "事件类型")
+            @JsonProperty("event")
+            private String event;
+
+            @Schema(description = "事件数据")
+            @JsonProperty("data")
+            private Object data;
+        }
+    }
+
+    // ========== 3. Agent 会话 (Session) - 对应 RAGFlow_Agent_Dify接口详解 ==========
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "Session 创建请求")
+    public static class SessionCreateReq implements Serializable {
+        @Schema(description = "用户 ID")
+        @JsonProperty("user_id")
+        private String userId;
+    }
+
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "Session 列表请求")
+    public static class SessionListReq implements Serializable {
+        @Schema(description = "页码", defaultValue = "1")
+        @JsonProperty("page")
+        @Builder.Default
+        private Integer page = 1;
+
+        @Schema(description = "每页大小", defaultValue = "10")
+        @JsonProperty("page_size")
+        @Builder.Default
+        private Integer pageSize = 10;
+
+        @Schema(description = "排序字段", defaultValue = "create_time")
+        @JsonProperty("orderby")
+        @Builder.Default
+        private String orderby = "create_time";
+
+        @Schema(description = "是否降序", defaultValue = "true")
+        @JsonProperty("desc")
+        @Builder.Default
+        private Boolean desc = true;
+
+        @Schema(description = "Session ID")
+        @JsonProperty("id")
+        private String id;
+
+        @Schema(description = "用户 ID")
+        @JsonProperty("user_id")
+        private String userId;
+
+        @Schema(description = "是否返回 DSL")
+        @JsonProperty("dsl")
+        @Builder.Default
+        private Boolean dsl = false;
+    }
+
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "Session 批量删除请求")
+    public static class SessionBatchDeleteReq implements Serializable {
+        @Schema(description = "会话 ID 列表", requiredMode = Schema.RequiredMode.REQUIRED)
+        @JsonProperty("ids")
+        @NotEmpty(message = "ID列表不能为空")
+        private List<String> ids;
+    }
+
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "Session 响应对象")
+    public static class SessionVO implements Serializable {
+        @Schema(description = "Session ID")
+        @JsonProperty("id")
+        private String id;
+
+        @Schema(description = "Agent ID")
+        @JsonProperty("agent_id")
+        private String agentId;
+
+        @Schema(description = "用户 ID")
+        @JsonProperty("user_id")
+        private String userId;
+
+        @Schema(description = "来源")
+        @JsonProperty("source")
+        private String source;
+
+        @Schema(description = "DSL 定义")
+        @JsonProperty("dsl")
+        private Map<String, Object> dsl;
+
+        @Schema(description = "消息列表")
+        @JsonProperty("messages")
+        private List<Map<String, Object>> messages;
+    }
+
+    // ========== 4. Agent 对话 (Completion) - 对应 RAGFlow_Agent_Dify接口详解 ==========
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "Completion 对话请求")
+    public static class CompletionReq implements Serializable {
+        @Schema(description = "会话 ID", requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotBlank(message = "会话 ID 不能为空")
+        @JsonProperty("session_id")
+        private String sessionId;
+
+        @Schema(description = "用户问题")
+        @JsonProperty("question")
+        private String question;
+
+        @Schema(description = "是否流式返回", defaultValue = "true")
+        @JsonProperty("stream")
+        @Builder.Default
+        private Boolean stream = true;
+
+        @Schema(description = "是否返回追踪信息", defaultValue = "false")
+        @JsonProperty("return_trace")
+        @Builder.Default
+        private Boolean returnTrace = false;
+    }
+
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "Completion 对话响应")
+    public static class CompletionVO implements Serializable {
+        @Schema(description = "会话 ID")
+        @JsonProperty("id")
+        private String id;
+
+        @Schema(description = "回复内容")
+        @JsonProperty("content")
+        private String content;
+
+        @Schema(description = "引用来源")
+        @JsonProperty("reference")
+        private Map<String, Object> reference;
+
+        @Schema(description = "追踪信息")
+        @JsonProperty("trace")
+        private List<Object> trace;
+    }
+
+    // ========== 5. Dify 兼容检索 - 对应 RAGFlow_Agent_Dify接口详解 ==========
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "Dify 兼容检索请求")
+    public static class DifyRetrievalReq implements Serializable {
+        @Schema(description = "知识库 ID")
+        @JsonProperty("knowledge_id")
+        private String knowledgeId;
+
+        @Schema(description = "查询词")
+        @JsonProperty("query")
+        private String query;
+
+        @Schema(description = "检索设置")
+        @JsonProperty("retrieval_setting")
+        private Map<String, Object> retrievalSetting;
+
+        @Schema(description = "元数据过滤条件")
+        @JsonProperty("metadata_condition")
+        private Map<String, Object> metadataCondition;
+
+        @Schema(description = "是否使用知识图谱")
+        @JsonProperty("use_kg")
+        private Boolean useKg;
+    }
+
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "Dify 兼容检索响应")
+    public static class DifyRetrievalVO implements Serializable {
+        @Schema(description = "检索结果列表")
+        @JsonProperty("records")
+        private List<Record> records;
+
+        @Data
+        @Builder
+        @NoArgsConstructor
+        @AllArgsConstructor
+        @Schema(description = "检索记录")
+        public static class Record implements Serializable {
+            @Schema(description = "内容")
+            @JsonProperty("content")
+            private String content;
+
+            @Schema(description = "相似度分数")
+            @JsonProperty("score")
+            private Double score;
+
+            @Schema(description = "标题")
+            @JsonProperty("title")
+            private String title;
+
+            @Schema(description = "元数据")
+            @JsonProperty("metadata")
+            private Map<String, Object> metadata;
+        }
+    }
+}

main/manager-api/src/main/java/xiaozhi/modules/knowledge/dto/bot/BotDTO.java

@@ -0,0 +1,126 @@
+package xiaozhi.modules.knowledge.dto.bot;
+
+import lombok.*;
+import io.swagger.v3.oas.annotations.media.Schema;
+import java.io.Serializable;
+import java.util.List;
+import java.util.Map;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import jakarta.validation.constraints.*;
+
+@Schema(description = "外部机器人 (Bot) 聚合 DTO")
+public class BotDTO {
+
+    // ========== 1. SearchBot (检索机器人) ==========
+
+    // 对应 /api/v1/searchbots/ask
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "SearchBot 提问请求")
+    public static class SearchAskReq implements Serializable {
+        @Schema(description = "用户问题", requiredMode = Schema.RequiredMode.REQUIRED, example = "What is RAG?")
+        @NotBlank(message = "问题不能为空")
+        @JsonProperty("question")
+        private String question;
+
+        @Schema(description = "是否返回引用", defaultValue = "false")
+        @JsonProperty("quote")
+        @Builder.Default
+        private Boolean quote = false;
+
+        @Schema(description = "是否流式返回", defaultValue = "true")
+        @JsonProperty("stream")
+        @Builder.Default
+        private Boolean stream = true;
+    }
+
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "SearchBot 提问响应")
+    public static class SearchAskVO implements Serializable {
+        @Schema(description = "回答内容")
+        @JsonProperty("answer")
+        private String answer;
+
+        @Schema(description = "引用来源 (Value 结构通常对应 RetrievalDTO.HitVO)")
+        @JsonProperty("reference")
+        private Map<String, Object> reference;
+    }
+
+    // 对应 /api/v1/searchbots/related_questions
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "相关问题请求")
+    public static class RelatedQuestionReq implements Serializable {
+        @Schema(description = "用户问题", requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotBlank(message = "问题不能为空")
+        @JsonProperty("question")
+        private String question;
+    }
+
+    // 对应 /api/v1/searchbots/mindmap
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "思维导图请求")
+    public static class MindMapReq implements Serializable {
+        @Schema(description = "用户问题", requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotBlank(message = "问题不能为空")
+        @JsonProperty("question")
+        private String question;
+    }
+
+    // ========== 2. AgentBot (嵌入式 Agent) ==========
+
+    // 对应 /api/v1/agentbots/{id}/inputs
+    @Data
+    @Builder
+    @AllArgsConstructor
+    @Schema(description = "AgentBot 输入参数请求")
+    public static class AgentInputsReq implements Serializable {
+    }
+
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "AgentBot 输入参数定义响应")
+    public static class AgentInputsVO implements Serializable {
+        @Schema(description = "表单变量定义列表")
+        @JsonProperty("variables")
+        private List<Map<String, Object>> variables;
+    }
+
+    // 对应 /api/v1/agentbots/{id}/completions
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    @Schema(description = "AgentBot 对话请求")
+    public static class AgentCompletionReq implements Serializable {
+        @Schema(description = "输入参数值")
+        @JsonProperty("inputs")
+        private Map<String, Object> inputs;
+
+        @Schema(description = "用户查询", requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotBlank(message = "查询内容不能为空")
+        @JsonProperty("question")
+        private String question;
+
+        @Schema(description = "是否流式返回", defaultValue = "true")
+        @JsonProperty("stream")
+        @Builder.Default
+        private Boolean stream = true;
+
+        @Schema(description = "会话 ID")
+        @JsonProperty("session_id")
+        private String sessionId;
+    }
+}

main/manager-api/src/main/java/xiaozhi/modules/knowledge/dto/chat/ChatCompletionRequest.java

@@ -0,0 +1,50 @@
+package xiaozhi.modules.knowledge.dto.chat;
+
+import java.io.Serializable;
+import java.util.List;
+import java.util.Map;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+/**
+ * 聊天对话请求 DTO (OpenAI 兼容格式)
+ */
+@Data
+@Schema(description = "聊天对话请求")
+public class ChatCompletionRequest implements Serializable {
+
+    @Schema(description = "模型标识 (对应 agent_id 或 bot_id)", requiredMode = Schema.RequiredMode.REQUIRED)
+    @JsonProperty("model")
+    private String model;
+
+    @Schema(description = "对话消息列表", requiredMode = Schema.RequiredMode.REQUIRED)
+    @JsonProperty("messages")
+    private List<Message> messages;
+
+    @Schema(description = "是否流式返回", defaultValue = "false")
+    @JsonProperty("stream")
+    private Boolean stream = false;
+
+    @Schema(description = "温度系数 (0-1)", defaultValue = "0.7")
+    @JsonProperty("temperature")
+    private Double temperature;
+
+    @Schema(description = "Session ID (可选，用于延续会话)")
+    @JsonProperty("session_id")
+    private String sessionId;
+
+    @Schema(description = "其他RAGFlow特定参数 (可选)")
+    private Map<String, Object> extra;
+
+    @Data
+    public static class Message implements Serializable {
+        @Schema(description = "角色 (system, user, assistant)", requiredMode = Schema.RequiredMode.REQUIRED)
+        private String role;
+
+        @Schema(description = "内容", requiredMode = Schema.RequiredMode.REQUIRED)
+        private String content;
+    }
+}