refactor(reportHandle): 重构上报处理逻辑，适配多格式音频转换

1. 重命名参数与变量，明确上报类型与音频格式 2. 拆分PCM和Opus转WAV逻辑，分别处理不同输入格式 3. 移动校验逻辑到上报队列函数开头，提前拦截无效上报 4. 完善Opus转WAV的解码与资源释放流程
Merge pull request #3293 from xinnan-tech/refactor/mybatis-plus-single-source
2026-07-29 03:33:56 +08:00 · 2026-07-27 09:59:32 +08:00 · 2026-07-20 14:42:31 +08:00 · 2026-07-20 10:31:08 +08:00 · 2026-07-17 09:28:14 +08:00 · 2026-07-16 16:58:49 +08:00
265 changed files with 24908 additions and 16135 deletions
@@ -112,12 +112,17 @@ celerybeat.pid
 # Environments
 .env
 .venv
+/.venv-*/
 env/
 venv/
 ENV/
 env.bak/
 venv.bak/

+# Repository-local runtimes and package-manager caches
+/.runtime/
+/main/manager-web/.npm-cache/
+
 # Spyder project settings
 .spyderproject
 .spyproject
@@ -55,110 +55,95 @@ Spearheaded by Professor Siyuan Liu's Team (South China University of Technology
    <td>
      <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
        <picture>
-           <img alt="响应速度感受" src="docs/images/demo9.png" />
-         </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>
+          <img alt="速度优化秘诀" src="docs/images/demo6.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1WEcxzFEAT" target="_blank">
+        <picture>
+          <img alt="小智数字人 支持语音唤醒" src="docs/images/demo8.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1CKVz6UEuB" target="_blank">
+        <picture>
+          <img alt="设备呼叫设备，打电话" src="docs/images/demo0.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>
+          <img alt="复杂医疗场景" src="docs/images/demo1.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>
+          <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>
+          <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>
+          <img alt="拍照识物品" src="docs/images/demo12.png" /></picture>
+      </a>
+    </td>
+    <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/BV1TJ7WzzEo6" target="_blank">
+        <picture>
+          <img alt="多指令任务" src="docs/images/demo11.png" /></picture>
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
+        <picture>
+          <img alt="MCP接入点" src="docs/images/demo13.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
+        <picture>
+          <img alt="MQTT指令下发" src="docs/images/demo4.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
+        <picture>
+          <img alt="声纹识别" src="docs/images/demo14.png" /></picture>
      </a>
    </td>
    <td>
      <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
        <picture>
-           <img alt="自定义音色" src="docs/images/demo2.png" />
-         </picture>
+          <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>
+          <img alt="使用粤语交流" src="docs/images/demo3.png" /></picture>
      </a>
    </td>
  </tr>
@@ -65,6 +65,7 @@ VAD:
 3、[如何部署MQTT网关开启MQTT+UDP协议](./mqtt-gateway-integration.md)<br/>
 4、[如何自动拉取本项目最新代码自动编译和启动](./dev-ops-integration.md)<br/>
 5、[如何与Nginx集成](https://github.com/xinnan-tech/xiaozhi-esp32-server/issues/791)<br/>
+6、[修改代码后怎么编译自己的Docker镜像](./docker-build.md)<br/>

 ### 8、编译固件相关教程
 1、[如何自己编译小智固件](./firmware-build.md)<br/>
@@ -85,6 +86,7 @@ VAD:
 11、[如何集成PowerMem智能记忆](./powermem-integration.md)<br/>
 12、[如何配置天气插件查询天气](./weather-integration.md)<br/>
 13、[如何开启设备呼叫插件](./device-call-guide.md)<br/>
+14、[如何开启联网搜索功能](./web-search-integration.md)<br/>

 ### 10、数字人相关教程
 1、[数字人digital-human启动方法](./digital-human-wakeword.md)<br/>
@@ -1,21 +1,74 @@
 # 本地编译docker镜像方法

-现在本项目已经使用github自动编译docker功能，本文档是提供给有本地编译docker镜像需求的朋友准备的。
+现在本项目已经使用`github`的`自动编译docker镜像`功能，如果您拉取的是项目发行的镜像，您没有自己编译镜像的需求，那就忽略本文档。

-1、安装docker
-```
+如果您修改了源码，然后想采用`docker`的方式部署运行，可以参照以下步骤操作：
+
+## 1、环境准备
+
+安装docker：
+```bash
 sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
 ```
-2、编译docker镜像
-```
-#进入项目根目录
-# 编译server
-docker build -t xiaozhi-esp32-server:server_latest -f ./Dockerfile-server .
-# 编译web
-docker build -t xiaozhi-esp32-server:web_latest -f ./Dockerfile-web .

-# 编译完成后，可以使用docker-compose启动项目
-# docker-compose.yml你需要修改成自己编译的镜像版本
+## 2、编译镜像
+
+当你修改好代码后，需要编译新的镜像时，需要按照以下步骤操作：
+
+准备好你的`你的用户名`和`新的版本号`。
+- 这个`你的用户名`是你在`docker hub`注册的用户名，例如`xiaozhi`。当然，如果你不需要推送到`docker hub`，你可以自由定义。
+- 这个`新的版本号`是你编译的镜像版本，例如`1.2.3`，你可以根据需要自定义或者使用日期格式（例如`20260609`）主要是方便和现在运行的版本号做区分，同时也方便下次回忆你是什么时候构建的，不要和现在你本机运行的版本号相同。
+
+进入`xiaozhi-esp32-server`项目根目录，编译 server 和 web 两个镜像：
+
+```bash
+cd 项目根目录
+
+# 编译server镜像
+docker build -f Dockerfile-server -t 你的用户名/xiaozhi-esp32-server:新的版本号 .
+
+# 编译web镜像
+docker build -f Dockerfile-web -t 你的用户名/xiaozhi-esp32-server-web:新的版本号 .
+
+```
+
+## 3、修改docker-compose配置
+
+```bash
 cd main/xiaozhi-server
-docker compose up -d
+```
+
+编辑 `docker-compose_all.yml` 文件，将镜像版本替换为你刚才编译的版本：
+
+```yaml
+services:
+  xiaozhi-esp32-server:
+    image: 你的用户名/xiaozhi-esp32-server:新的版本号   # 修改为你的镜像地址
+    ...
+
+  xiaozhi-esp32-server-web:
+    image: 你的用户名/xiaozhi-esp32-server-web:新的版本号   #修改为你的镜像地址
+    ...
+```
+
+## 4、重启服务
+
+```bash
+# 停止旧容器
+docker compose -f docker-compose_all.yml down
+
+# 启动新容器
+docker compose -f docker-compose_all.yml up -d
+```
+
+## 5、验证
+
+查看日志确认服务启动正常：
+
+```bash
+# 查看server日志
+docker logs -f -n 50 xiaozhi-esp32-server
+
+# 查看web日志
+docker logs -f -n 50 xiaozhi-esp32-server-web
 ```
@@ -54,110 +54,95 @@ Möchten Sie die Nutzungseffekte sehen? Klicken Sie auf die Videos unten 🎥
    <td>
      <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
        <picture>
-           <img alt="响应速度感受" src="../images/demo9.png" />
-         </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="../images/demo6.png" />
-         </picture>
+          <img alt="速度优化秘诀" src="docs/images/demo6.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1WEcxzFEAT" target="_blank">
+        <picture>
+          <img alt="小智数字人 支持语音唤醒" src="docs/images/demo8.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1CKVz6UEuB" target="_blank">
+        <picture>
+          <img alt="设备呼叫设备，打电话" src="docs/images/demo0.png" /></picture>
      </a>
    </td>
    <td>
      <a href="https://www.bilibili.com/video/BV1C1tCzUEZh" target="_blank">
        <picture>
-           <img alt="复杂医疗场景" src="../images/demo1.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
-         <picture>
-           <img alt="MQTT指令下发" src="../images/demo4.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
-         <picture>
-           <img alt="声纹识别" src="../images/demo14.png" />
-         </picture>
+          <img alt="复杂医疗场景" src="docs/images/demo1.png" /></picture>
      </a>
    </td>
  </tr>
  <tr>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1pNXWYGEx1" target="_blank">
-         <picture>
-           <img alt="控制家电开关" src="../images/demo5.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
-         <picture>
-           <img alt="MCP接入点" src="../images/demo13.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-      <a href="https://www.bilibili.com/video/BV1TJ7WzzEo6" target="_blank">
-         <picture>
-           <img alt="多指令任务" src="../images/demo11.png" />
-         </picture>
-        </a>
-    </td>
    <td>
      <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
        <picture>
-           <img alt="播放音乐" src="../images/demo7.png" />
-         </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="../images/demo8.png" />
-         </picture>
-        </a>
-    </td>
-  </tr>
-  <tr>
    <td>
      <a href="https://www.bilibili.com/video/BV12J7WzBEaH" target="_blank">
        <picture>
-           <img alt="实时打断" src="../images/demo10.png" />
-         </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="../images/demo12.png" />
-         </picture>
+          <img alt="拍照识物品" src="docs/images/demo12.png" /></picture>
+      </a>
+    </td>
+    <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/BV1TJ7WzzEo6" target="_blank">
+        <picture>
+          <img alt="多指令任务" src="docs/images/demo11.png" /></picture>
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
+        <picture>
+          <img alt="MCP接入点" src="docs/images/demo13.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
+        <picture>
+          <img alt="MQTT指令下发" src="docs/images/demo4.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
+        <picture>
+          <img alt="声纹识别" src="docs/images/demo14.png" /></picture>
      </a>
    </td>
    <td>
      <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
        <picture>
-           <img alt="自定义音色" src="../images/demo2.png" />
-         </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="../images/demo3.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV17LXWYvENb" target="_blank">
-         <picture>
-           <img alt="播报新闻" src="../images/demo0.png" />
-         </picture>
+          <img alt="使用粤语交流" src="docs/images/demo3.png" /></picture>
      </a>
    </td>
  </tr>
@@ -54,110 +54,95 @@ Want to see the usage effects? Click the videos below 🎥
    <td>
      <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
        <picture>
-           <img alt="响应速度感受" src="../images/demo9.png" />
-         </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="../images/demo6.png" />
-         </picture>
+          <img alt="速度优化秘诀" src="docs/images/demo6.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1WEcxzFEAT" target="_blank">
+        <picture>
+          <img alt="小智数字人 支持语音唤醒" src="docs/images/demo8.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1CKVz6UEuB" target="_blank">
+        <picture>
+          <img alt="设备呼叫设备，打电话" src="docs/images/demo0.png" /></picture>
      </a>
    </td>
    <td>
      <a href="https://www.bilibili.com/video/BV1C1tCzUEZh" target="_blank">
        <picture>
-           <img alt="复杂医疗场景" src="../images/demo1.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
-         <picture>
-           <img alt="MQTT指令下发" src="../images/demo4.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
-         <picture>
-           <img alt="声纹识别" src="../images/demo14.png" />
-         </picture>
+          <img alt="复杂医疗场景" src="docs/images/demo1.png" /></picture>
      </a>
    </td>
  </tr>
  <tr>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1pNXWYGEx1" target="_blank">
-         <picture>
-           <img alt="控制家电开关" src="../images/demo5.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
-         <picture>
-           <img alt="MCP接入点" src="../images/demo13.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-      <a href="https://www.bilibili.com/video/BV1TJ7WzzEo6" target="_blank">
-         <picture>
-           <img alt="多指令任务" src="../images/demo11.png" />
-         </picture>
-        </a>
-    </td>
    <td>
      <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
        <picture>
-           <img alt="播放音乐" src="../images/demo7.png" />
-         </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="../images/demo8.png" />
-         </picture>
-        </a>
-    </td>
-  </tr>
-  <tr>
    <td>
      <a href="https://www.bilibili.com/video/BV12J7WzBEaH" target="_blank">
        <picture>
-           <img alt="实时打断" src="../images/demo10.png" />
-         </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="../images/demo12.png" />
-         </picture>
+          <img alt="拍照识物品" src="docs/images/demo12.png" /></picture>
+      </a>
+    </td>
+    <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/BV1TJ7WzzEo6" target="_blank">
+        <picture>
+          <img alt="多指令任务" src="docs/images/demo11.png" /></picture>
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
+        <picture>
+          <img alt="MCP接入点" src="docs/images/demo13.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
+        <picture>
+          <img alt="MQTT指令下发" src="docs/images/demo4.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
+        <picture>
+          <img alt="声纹识别" src="docs/images/demo14.png" /></picture>
      </a>
    </td>
    <td>
      <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
        <picture>
-           <img alt="自定义音色" src="../images/demo2.png" />
-         </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="../images/demo3.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV17LXWYvENb" target="_blank">
-         <picture>
-           <img alt="播报新闻" src="../images/demo0.png" />
-         </picture>
+          <img alt="使用粤语交流" src="docs/images/demo3.png" /></picture>
      </a>
    </td>
  </tr>
@@ -54,110 +54,95 @@ Quer ver os efeitos de uso? Clique nos vídeos abaixo 🎥
    <td>
      <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
        <picture>
-           <img alt="Experiência de velocidade de resposta" src="../images/demo9.png" />
-         </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="Segredo da otimização de velocidade" src="../images/demo6.png" />
-         </picture>
+          <img alt="速度优化秘诀" src="docs/images/demo6.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1WEcxzFEAT" target="_blank">
+        <picture>
+          <img alt="小智数字人 支持语音唤醒" src="docs/images/demo8.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1CKVz6UEuB" target="_blank">
+        <picture>
+          <img alt="设备呼叫设备，打电话" src="docs/images/demo0.png" /></picture>
      </a>
    </td>
    <td>
      <a href="https://www.bilibili.com/video/BV1C1tCzUEZh" target="_blank">
        <picture>
-           <img alt="Cenário médico complexo" src="../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="../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="../images/demo14.png" />
-         </picture>
+          <img alt="复杂医疗场景" src="docs/images/demo1.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="../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="../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="../images/demo11.png" />
-         </picture>
-        </a>
-    </td>
    <td>
      <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
        <picture>
-           <img alt="Reproduzir música" src="../images/demo7.png" />
-         </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="Plugin de clima" src="../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="../images/demo10.png" />
-         </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="Fotografar e identificar objetos" src="../images/demo12.png" />
-         </picture>
+          <img alt="拍照识物品" src="docs/images/demo12.png" /></picture>
+      </a>
+    </td>
+    <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/BV1TJ7WzzEo6" target="_blank">
+        <picture>
+          <img alt="多指令任务" src="docs/images/demo11.png" /></picture>
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
+        <picture>
+          <img alt="MCP接入点" src="docs/images/demo13.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
+        <picture>
+          <img alt="MQTT指令下发" src="docs/images/demo4.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
+        <picture>
+          <img alt="声纹识别" src="docs/images/demo14.png" /></picture>
      </a>
    </td>
    <td>
      <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
        <picture>
-           <img alt="Timbre de voz personalizado" src="../images/demo2.png" />
-         </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="Comunicação em cantonês" src="../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="../images/demo0.png" />
-         </picture>
+          <img alt="使用粤语交流" src="docs/images/demo3.png" /></picture>
      </a>
    </td>
  </tr>
@@ -54,110 +54,95 @@ Muốn xem hiệu quả sử dụng? Hãy xem video 🎥
    <td>
      <a href="https://www.bilibili.com/video/BV1FMFyejExX" target="_blank">
        <picture>
-           <img alt="响应速度感受" src="../images/demo9.png" />
-         </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="../images/demo6.png" />
-         </picture>
+          <img alt="速度优化秘诀" src="docs/images/demo6.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1WEcxzFEAT" target="_blank">
+        <picture>
+          <img alt="小智数字人 支持语音唤醒" src="docs/images/demo8.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1CKVz6UEuB" target="_blank">
+        <picture>
+          <img alt="设备呼叫设备，打电话" src="docs/images/demo0.png" /></picture>
      </a>
    </td>
    <td>
      <a href="https://www.bilibili.com/video/BV1C1tCzUEZh" target="_blank">
        <picture>
-           <img alt="复杂医疗场景" src="../images/demo1.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
-         <picture>
-           <img alt="MQTT指令下发" src="../images/demo4.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
-         <picture>
-           <img alt="声纹识别" src="../images/demo14.png" />
-         </picture>
+          <img alt="复杂医疗场景" src="docs/images/demo1.png" /></picture>
      </a>
    </td>
  </tr>
  <tr>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1pNXWYGEx1" target="_blank">
-         <picture>
-           <img alt="控制家电开关" src="../images/demo5.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
-         <picture>
-           <img alt="MCP接入点" src="../images/demo13.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-      <a href="https://www.bilibili.com/video/BV1TJ7WzzEo6" target="_blank">
-         <picture>
-           <img alt="多指令任务" src="../images/demo11.png" />
-         </picture>
-        </a>
-    </td>
    <td>
      <a href="https://www.bilibili.com/video/BV1VC96Y5EMH" target="_blank">
        <picture>
-           <img alt="播放音乐" src="../images/demo7.png" />
-         </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="../images/demo8.png" />
-         </picture>
-        </a>
-    </td>
-  </tr>
-  <tr>
    <td>
      <a href="https://www.bilibili.com/video/BV12J7WzBEaH" target="_blank">
        <picture>
-           <img alt="实时打断" src="../images/demo10.png" />
-         </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="../images/demo12.png" />
-         </picture>
+          <img alt="拍照识物品" src="docs/images/demo12.png" /></picture>
+      </a>
+    </td>
+    <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/BV1TJ7WzzEo6" target="_blank">
+        <picture>
+          <img alt="多指令任务" src="docs/images/demo11.png" /></picture>
+      </a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1ZQKUzYExM" target="_blank">
+        <picture>
+          <img alt="MCP接入点" src="docs/images/demo13.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1zUW5zJEkq" target="_blank">
+        <picture>
+          <img alt="MQTT指令下发" src="docs/images/demo4.png" /></picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.bilibili.com/video/BV1Exu3zqEDe" target="_blank">
+        <picture>
+          <img alt="声纹识别" src="docs/images/demo14.png" /></picture>
      </a>
    </td>
    <td>
      <a href="https://www.bilibili.com/video/BV1CDKWemEU6" target="_blank">
        <picture>
-           <img alt="自定义音色" src="../images/demo2.png" />
-         </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="../images/demo3.png" />
-         </picture>
-        </a>
-    </td>
-    <td>
-        <a href="https://www.bilibili.com/video/BV17LXWYvENb" target="_blank">
-         <picture>
-           <img alt="播报新闻" src="../images/demo0.png" />
-         </picture>
+          <img alt="使用粤语交流" src="docs/images/demo3.png" /></picture>
      </a>
    </td>
  </tr>
@@ -0,0 +1,71 @@
+# 联网搜索插件使用指南
+
+## 功能简介
+
+联网搜索插件 `web_search` 支持在对话过程中实时联网搜索信息并返回结果。插件支持两个搜索源：秘塔（Metaso）和Tavily，用户可根据需要选择其中一个。
+
+## API Key申请指南
+
+目前我们适配了`秘塔搜索`和`Tavily搜索`。
+- Tavily搜索：每个月1000次免费额度。
+- 秘塔搜索：拥有较为优质的国内数据源。
+
+## API Key申请指南
+
+### 方式一：使用秘塔搜索
+
+- 访问 [秘塔搜索API](https://metaso.cn/search-api/api-keys)，注册并登录账号
+- 在API密钥管理页面，点击"创建新的Key"
+- 复制生成的API Key（以 `mk-` 为前缀），这是配置所需的关键信息
+
+### 方式二：使用Tavily搜索
+
+- 访问 [Tavily控制台](https://app.tavily.com/home)，注册并登录账号
+- 在控制台中创建API Key
+- 复制生成的API Key（以 `tvly-` 为前缀），这是配置所需的关键信息
+
+## 配置方式
+
+### 方式1. 使用智控台部署（推荐）
+
+- 登录智控台
+- 进入"配置角色"页面，选择要配置的智能体
+- 点击"编辑功能"按钮，在右侧参数配置区域找到"联网搜索"插件
+- 勾选"联网搜索"
+- 填入搜索源（`metaso`或`tavily`），并将对应的`API Key`填入配置项
+- 保存配置，再保存智能体配置
+
+### 方式2. 单模块xiaozhi-server部署
+
+在 `data/.config.yaml` 中配置：
+
+- 将搜索源填入 `provider`，可选值为 `metaso` 或 `tavily`
+- 将申请到的API Key填入 `api_key`
+
+```yaml
+plugins:
+  web_search:
+    provider: "metaso"
+    api_key: "你的API Key"
+```
+
+如需自定义返回结果数量和工具描述，可额外配置 `max_results` 和 `description`：
+
+```yaml
+plugins:
+  web_search:
+    provider: "metaso"
+    description: "联网搜索工具。当用户明确需要联网搜索问题时使用此工具。"
+    max_results: 5
+    api_key: "你的API Key"
+```
+
+同时在 `functions` 列表中确保已启用 `web_search`：
+
+```yaml
+plugins:
+  functions:
+    - web_search
+```
+
+配置完成后重启服务即可生效。
@@ -20,7 +20,7 @@
        <java.version>21</java.version>
        <junit.version>5.10.1</junit.version>
        <druid.version>1.2.20</druid.version>
-        <mybatisplus.version>3.5.5</mybatisplus.version>
+        <mybatisplus.version>3.5.17</mybatisplus.version>
        <hutool.version>5.8.24</hutool.version>
        <jsoup.version>1.19.1</jsoup.version>
        <knife4j.version>4.6.0</knife4j.version>
@@ -32,6 +32,7 @@
        <liquibase-core.version>4.20.0</liquibase-core.version>
        <aliyun-sms-version>4.1.0</aliyun-sms-version>
        <okio-version>3.4.0</okio-version>
+        <skipTests>true</skipTests>
    </properties>

    <dependencies>
@@ -175,13 +176,13 @@
        </dependency>
        <dependency>
            <groupId>com.baomidou</groupId>
-            <artifactId>mybatis-plus-boot-starter</artifactId>
+            <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
            <version>${mybatisplus.version}</version>
        </dependency>
        <dependency>
-            <groupId>org.mybatis</groupId>
-            <artifactId>mybatis-spring</artifactId>
-            <version>3.0.3</version>
+            <groupId>com.baomidou</groupId>
+            <artifactId>mybatis-plus-jsqlparser-4.9</artifactId>
+            <version>${mybatisplus.version}</version>
        </dependency>
        <dependency>
            <groupId>cn.hutool</groupId>
@@ -275,7 +276,7 @@
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <configuration>
-                    <skipTests>true</skipTests>
+                    <skipTests>${skipTests}</skipTests>
                </configuration>
            </plugin>
        </plugins>
@@ -324,7 +324,7 @@ public interface Constant {
    /**
     * 版本号
     */
-    public static final String VERSION = "0.9.4";
+    public static final String VERSION = "0.9.5";

    /**
     * 无效固件URL
@@ -5,7 +5,7 @@ import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
 import java.util.Map;
-import java.util.function.BiConsumer;
+import java.util.function.BiFunction;

 import org.apache.ibatis.binding.MapperMethod;
 import org.apache.ibatis.logging.Log;
@@ -181,8 +181,9 @@ public abstract class BaseServiceImpl<M extends BaseMapper<T>, T> implements Bas
     * 执行批量操作
     */
    @SuppressWarnings("deprecation")
-    protected <E> boolean executeBatch(Collection<E> list, int batchSize, BiConsumer<SqlSession, E> consumer) {
-        return SqlHelper.executeBatch(this.currentModelClass(), this.log, list, batchSize, consumer);
+    protected <E> boolean executeBatch(Collection<E> list, int batchSize, BiFunction<SqlSession, E, Integer> operation) {
+        return SqlHelper.executeBatch(SqlHelper.sqlSessionFactory(this.currentModelClass()), this.log, list, batchSize,
+                operation);
    }

    @Override
@@ -209,7 +210,7 @@ public abstract class BaseServiceImpl<M extends BaseMapper<T>, T> implements Bas
        return executeBatch(entityList, batchSize, (sqlSession, entity) -> {
            MapperMethod.ParamMap<T> param = new MapperMethod.ParamMap<>();
            param.put(Constants.ENTITY, entity);
-            sqlSession.update(sqlStatement, param);
+            return sqlSession.update(sqlStatement, param);
        });
    }

@@ -0,0 +1,103 @@
+package xiaozhi.modules.agent.Enums;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.function.BiConsumer;
+import java.util.function.Function;
+
+import lombok.Getter;
+import xiaozhi.modules.agent.dto.AgentSnapshotDataDTO;
+import xiaozhi.modules.agent.dto.AgentUpdateDTO;
+import xiaozhi.modules.agent.entity.AgentEntity;
+
+@Getter
+public enum AgentSnapshotField {
+    AGENT_CODE("agentCode", AgentSnapshotDataDTO::getAgentCode, AgentUpdateDTO::getAgentCode,
+            (agent, data) -> agent.setAgentCode(data.getAgentCode())),
+    AGENT_NAME("agentName", AgentSnapshotDataDTO::getAgentName, AgentUpdateDTO::getAgentName,
+            (agent, data) -> agent.setAgentName(data.getAgentName())),
+    ASR_MODEL_ID("asrModelId", AgentSnapshotDataDTO::getAsrModelId, AgentUpdateDTO::getAsrModelId,
+            (agent, data) -> agent.setAsrModelId(data.getAsrModelId())),
+    VAD_MODEL_ID("vadModelId", AgentSnapshotDataDTO::getVadModelId, AgentUpdateDTO::getVadModelId,
+            (agent, data) -> agent.setVadModelId(data.getVadModelId())),
+    LLM_MODEL_ID("llmModelId", AgentSnapshotDataDTO::getLlmModelId, AgentUpdateDTO::getLlmModelId,
+            (agent, data) -> agent.setLlmModelId(data.getLlmModelId())),
+    SLM_MODEL_ID("slmModelId", AgentSnapshotDataDTO::getSlmModelId, AgentUpdateDTO::getSlmModelId,
+            (agent, data) -> agent.setSlmModelId(data.getSlmModelId())),
+    VLLM_MODEL_ID("vllmModelId", AgentSnapshotDataDTO::getVllmModelId, AgentUpdateDTO::getVllmModelId,
+            (agent, data) -> agent.setVllmModelId(data.getVllmModelId())),
+    TTS_MODEL_ID("ttsModelId", AgentSnapshotDataDTO::getTtsModelId, AgentUpdateDTO::getTtsModelId,
+            (agent, data) -> agent.setTtsModelId(data.getTtsModelId())),
+    TTS_VOICE_ID("ttsVoiceId", AgentSnapshotDataDTO::getTtsVoiceId, AgentUpdateDTO::getTtsVoiceId,
+            (agent, data) -> agent.setTtsVoiceId(data.getTtsVoiceId())),
+    TTS_LANGUAGE("ttsLanguage", AgentSnapshotDataDTO::getTtsLanguage, AgentUpdateDTO::getTtsLanguage,
+            (agent, data) -> agent.setTtsLanguage(data.getTtsLanguage())),
+    TTS_VOLUME("ttsVolume", AgentSnapshotDataDTO::getTtsVolume, AgentUpdateDTO::getTtsVolume,
+            (agent, data) -> agent.setTtsVolume(data.getTtsVolume())),
+    TTS_RATE("ttsRate", AgentSnapshotDataDTO::getTtsRate, AgentUpdateDTO::getTtsRate,
+            (agent, data) -> agent.setTtsRate(data.getTtsRate())),
+    TTS_PITCH("ttsPitch", AgentSnapshotDataDTO::getTtsPitch, AgentUpdateDTO::getTtsPitch,
+            (agent, data) -> agent.setTtsPitch(data.getTtsPitch())),
+    MEM_MODEL_ID("memModelId", AgentSnapshotDataDTO::getMemModelId, AgentUpdateDTO::getMemModelId,
+            (agent, data) -> agent.setMemModelId(data.getMemModelId())),
+    INTENT_MODEL_ID("intentModelId", AgentSnapshotDataDTO::getIntentModelId, AgentUpdateDTO::getIntentModelId,
+            (agent, data) -> agent.setIntentModelId(data.getIntentModelId())),
+    CHAT_HISTORY_CONF("chatHistoryConf", AgentSnapshotDataDTO::getChatHistoryConf, AgentUpdateDTO::getChatHistoryConf,
+            (agent, data) -> agent.setChatHistoryConf(data.getChatHistoryConf())),
+    SYSTEM_PROMPT("systemPrompt", AgentSnapshotDataDTO::getSystemPrompt, AgentUpdateDTO::getSystemPrompt,
+            (agent, data) -> agent.setSystemPrompt(data.getSystemPrompt())),
+    SUMMARY_MEMORY("summaryMemory", AgentSnapshotDataDTO::getSummaryMemory, AgentUpdateDTO::getSummaryMemory,
+            (agent, data) -> agent.setSummaryMemory(data.getSummaryMemory())),
+    LANG_CODE("langCode", AgentSnapshotDataDTO::getLangCode, AgentUpdateDTO::getLangCode,
+            (agent, data) -> agent.setLangCode(data.getLangCode())),
+    LANGUAGE("language", AgentSnapshotDataDTO::getLanguage, AgentUpdateDTO::getLanguage,
+            (agent, data) -> agent.setLanguage(data.getLanguage())),
+    SORT("sort", AgentSnapshotDataDTO::getSort, AgentUpdateDTO::getSort,
+            (agent, data) -> agent.setSort(data.getSort())),
+    FUNCTIONS("functions", AgentSnapshotDataDTO::getFunctions, AgentUpdateDTO::getFunctions, null),
+    CONTEXT_PROVIDERS("contextProviders", AgentSnapshotDataDTO::getContextProviders,
+            AgentUpdateDTO::getContextProviders, null),
+    CORRECT_WORD_FILE_IDS("correctWordFileIds", AgentSnapshotDataDTO::getCorrectWordFileIds,
+            AgentUpdateDTO::getCorrectWordFileIds, null),
+    TAG_NAMES("tagNames", AgentSnapshotDataDTO::getTagNames, AgentUpdateDTO::getTagNames, null);
+
+    private final String fieldName;
+    private final Function<AgentSnapshotDataDTO, Object> snapshotGetter;
+    private final Function<AgentUpdateDTO, Object> updateGetter;
+    private final BiConsumer<AgentEntity, AgentSnapshotDataDTO> restoreApplier;
+
+    AgentSnapshotField(String fieldName, Function<AgentSnapshotDataDTO, Object> snapshotGetter,
+            Function<AgentUpdateDTO, Object> updateGetter,
+            BiConsumer<AgentEntity, AgentSnapshotDataDTO> restoreApplier) {
+        this.fieldName = fieldName;
+        this.snapshotGetter = snapshotGetter;
+        this.updateGetter = updateGetter;
+        this.restoreApplier = restoreApplier;
+    }
+
+    public static List<String> names() {
+        return Arrays.stream(values()).map(AgentSnapshotField::getFieldName).toList();
+    }
+
+    public static String canonicalName(String fieldName) {
+        return "tags".equals(fieldName) ? TAG_NAMES.getFieldName() : fieldName;
+    }
+
+    public Object snapshotValue(AgentSnapshotDataDTO data) {
+        return data == null ? null : snapshotGetter.apply(data);
+    }
+
+    public Object updateValue(AgentUpdateDTO data) {
+        return data == null ? null : updateGetter.apply(data);
+    }
+
+    public boolean isRestorableAgentField() {
+        return restoreApplier != null;
+    }
+
+    public void applyTo(AgentEntity agent, AgentSnapshotDataDTO data) {
+        if (restoreApplier != null) {
+            restoreApplier.accept(agent, data);
+        }
+    }
+}
@@ -28,6 +28,8 @@ import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.AllArgsConstructor;
 import xiaozhi.common.constant.Constant;
+import xiaozhi.common.exception.ErrorCode;
+import xiaozhi.common.exception.RenException;
 import xiaozhi.common.page.PageData;
 import xiaozhi.common.redis.RedisKeys;
 import xiaozhi.common.redis.RedisUtils;
@@ -48,15 +50,10 @@ 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;
-import xiaozhi.modules.correctword.service.CorrectWordFileService;
 import xiaozhi.modules.agent.vo.AgentChatHistoryUserVO;
 import xiaozhi.modules.agent.vo.AgentInfoVO;
-import xiaozhi.modules.device.entity.DeviceEntity;
-import xiaozhi.modules.device.service.DeviceService;
 import xiaozhi.modules.security.user.SecurityUser;

@Tag(name = "智能体管理")
@@ -64,17 +61,39 @@ import xiaozhi.modules.security.user.SecurityUser;
@RestController
@RequestMapping("/agent")
 public class AgentController {
+    private static final long AUDIO_PLAY_TOKEN_EXPIRE_SECONDS = 300L;
+
    private final AgentService agentService;
    private final AgentTemplateService agentTemplateService;
-    private final DeviceService deviceService;
    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;
-    private final CorrectWordFileService correctWordFileService;
+
+    private void requireAgentPermission(String agentId) {
+        if (!agentService.checkAgentPermission(agentId, SecurityUser.getUserId())) {
+            throw new RenException(ErrorCode.NO_PERMISSION);
+        }
+    }
+
+    private String requireSessionAgent(String sessionId) {
+        String agentId = agentChatHistoryService.getAgentIdBySessionId(sessionId);
+        if (StringUtils.isBlank(agentId)) {
+            throw new RenException(ErrorCode.AGENT_NOT_FOUND);
+        }
+        agentService.getAgentById(agentId);
+        return agentId;
+    }
+
+    private String requireAudioPermission(String audioId) {
+        String agentId = agentChatHistoryService.getAgentIdByAudioId(audioId);
+        if (StringUtils.isBlank(agentId)) {
+            throw new RenException(ErrorCode.NO_PERMISSION);
+        }
+        requireAgentPermission(agentId);
+        return agentId;
+    }

    @GetMapping("/list")
    @Operation(summary = "获取用户智能体列表")
@@ -106,7 +125,7 @@ public class AgentController {
    @Operation(summary = "获取智能体详情")
    @RequiresPermissions("sys:role:normal")
    public Result<AgentInfoVO> getAgentById(@PathVariable("id") String id) {
-        AgentInfoVO agent = agentService.getAgentById(id);
+        AgentInfoVO agent = agentService.getAgentById(id, SecurityUser.getUserId());
        return ResultUtils.success(agent);
    }

@@ -120,20 +139,16 @@ public class AgentController {

    @PutMapping("/saveMemory/{macAddress}")
    @Operation(summary = "根据设备id更新智能体")
+    @RequiresPermissions("sys:role:normal")
    public Result<Void> updateByDeviceId(@PathVariable String macAddress, @RequestBody @Valid AgentMemoryDTO dto) {
-        DeviceEntity device = deviceService.getDeviceByMacAddress(macAddress);
-        if (device == null) {
-            return new Result<>();
-        }
-        AgentUpdateDTO agentUpdateDTO = new AgentUpdateDTO();
-        agentUpdateDTO.setSummaryMemory(dto.getSummaryMemory());
-        agentService.updateAgentById(device.getAgentId(), agentUpdateDTO);
-        return new Result<>();
+        agentService.updateAgentMemoryByDeviceMacAddress(macAddress, dto, SecurityUser.getUserId());
+        return new Result<Void>().ok(null);
    }

    @PostMapping("/chat-summary/{sessionId}/save")
    @Operation(summary = "根据会话ID生成聊天记录总结并保存（异步执行）")
    public Result<Void> generateAndSaveChatSummary(@PathVariable String sessionId) {
+        requireSessionAgent(sessionId);
        try {
            // 异步执行总结生成任务，立即返回成功响应
            new Thread(() -> {
@@ -155,6 +170,7 @@ public class AgentController {
    @PostMapping("/chat-title/{sessionId}/generate")
    @Operation(summary = "根据会话ID生成聊天标题")
    public Result<Void> generateAndSaveChatTitle(@PathVariable String sessionId) {
+        requireSessionAgent(sessionId);
        agentChatSummaryService.generateAndSaveChatTitle(sessionId);
        return new Result<Void>().ok(null);
    }
@@ -163,7 +179,7 @@ public class AgentController {
    @Operation(summary = "更新智能体")
    @RequiresPermissions("sys:role:normal")
    public Result<Void> update(@PathVariable String id, @RequestBody @Valid AgentUpdateDTO dto) {
-        agentService.updateAgentById(id, dto);
+        agentService.updateAgentById(id, dto, SecurityUser.getUserId());
        return new Result<>();
    }

@@ -171,18 +187,7 @@ public class AgentController {
    @Operation(summary = "删除智能体")
    @RequiresPermissions("sys:role:normal")
    public Result<Void> delete(@PathVariable String id) {
-        // 先删除关联的设备
-        deviceService.deleteByAgentId(id);
-        // 删除关联的聊天记录
-        agentChatHistoryService.deleteByAgentId(id, true, true);
-        // 删除关联的插件
-        agentPluginMappingService.deleteByAgentId(id);
-        // 删除关联的上下文源配置
-        agentContextProviderService.deleteByAgentId(id);
-        // 删除关联的替换词文件关联记录
-        correctWordFileService.deleteMappingsByAgentId(id);
-        // 再删除智能体
-        agentService.deleteById(id);
+        agentService.deleteAgentById(id, SecurityUser.getUserId());
        return new Result<>();
    }

@@ -205,6 +210,7 @@ public class AgentController {
    public Result<PageData<AgentChatSessionDTO>> getAgentSessions(
            @PathVariable("id") String id,
            @Parameter(hidden = true) @RequestParam Map<String, Object> params) {
+        requireAgentPermission(id);
        params.put("agentId", id);
        PageData<AgentChatSessionDTO> page = agentChatHistoryService.getSessionListByAgentId(params);
        return new Result<PageData<AgentChatSessionDTO>>().ok(page);
@@ -252,6 +258,7 @@ public class AgentController {
    @RequiresPermissions("sys:role:normal")
    public Result<String> getContentByAudioId(
            @PathVariable("id") String id) {
+        requireAudioPermission(id);
        // 查询聊天记录
        String data = agentChatHistoryService.getContentByAudioId(id);
        return new Result<String>().ok(data);
@@ -261,12 +268,13 @@ public class AgentController {
    @Operation(summary = "获取音频下载ID")
    @RequiresPermissions("sys:role:normal")
    public Result<String> getAudioId(@PathVariable("audioId") String audioId) {
+        requireAudioPermission(audioId);
        byte[] audioData = agentChatAudioService.getAudio(audioId);
        if (audioData == null) {
            return new Result<String>().error("音频不存在");
        }
        String uuid = UUID.randomUUID().toString();
-        redisUtils.set(RedisKeys.getAgentAudioIdKey(uuid), audioId);
+        redisUtils.set(RedisKeys.getAgentAudioIdKey(uuid), audioId, AUDIO_PLAY_TOKEN_EXPIRE_SECONDS);
        return new Result<String>().ok(uuid);
    }

@@ -322,6 +330,7 @@ public class AgentController {
    @Operation(summary = "获取智能体的标签")
    @RequiresPermissions("sys:role:normal")
    public Result<List<AgentTagDTO>> getAgentTags(@PathVariable String id) {
+        requireAgentPermission(id);
        List<AgentTagDTO> tags = agentTagService.getTagsByAgentId(id);
        return new Result<List<AgentTagDTO>>().ok(tags);
    }
@@ -330,9 +339,13 @@ public class AgentController {
    @Operation(summary = "保存智能体的标签")
    @RequiresPermissions("sys:role:normal")
    public Result<Void> saveAgentTags(@PathVariable String id, @RequestBody Map<String, Object> params) {
+        requireAgentPermission(id);
        List<String> tagIds = (List<String>) params.get("tagIds");
        List<String> tagNames = (List<String>) params.get("tagNames");
-        agentTagService.saveAgentTags(id, tagIds, tagNames);
+        AgentUpdateDTO dto = new AgentUpdateDTO();
+        dto.setTagIds(tagIds);
+        dto.setTagNames(tagNames);
+        agentService.updateAgentById(id, dto);
        return new Result<Void>().ok(null);
    }

@@ -0,0 +1,79 @@
+package xiaozhi.modules.agent.controller;
+
+import org.apache.shiro.authz.annotation.RequiresPermissions;
+import org.springdoc.core.annotations.ParameterObject;
+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.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import lombok.AllArgsConstructor;
+import xiaozhi.common.exception.RenException;
+import xiaozhi.common.page.PageData;
+import xiaozhi.common.user.UserDetail;
+import xiaozhi.common.utils.Result;
+import xiaozhi.modules.agent.dto.AgentSnapshotPageDTO;
+import xiaozhi.modules.agent.dto.AgentSnapshotRestoreDTO;
+import xiaozhi.modules.agent.service.AgentService;
+import xiaozhi.modules.agent.service.AgentSnapshotService;
+import xiaozhi.modules.agent.vo.AgentSnapshotVO;
+import xiaozhi.modules.security.user.SecurityUser;
+
+@Tag(name = "智能体快照")
+@AllArgsConstructor
+@RestController
+@RequestMapping("/agent/{agentId}/snapshots")
+public class AgentSnapshotController {
+    private final AgentSnapshotService agentSnapshotService;
+    private final AgentService agentService;
+
+    @GetMapping
+    @Operation(summary = "获取智能体快照列表")
+    @RequiresPermissions("sys:role:normal")
+    public Result<PageData<AgentSnapshotVO>> page(
+            @PathVariable String agentId,
+            @ParameterObject AgentSnapshotPageDTO params) {
+        checkPermission(agentId);
+        return new Result<PageData<AgentSnapshotVO>>().ok(agentSnapshotService.page(agentId, params));
+    }
+
+    @GetMapping("/{snapshotId}")
+    @Operation(summary = "获取智能体快照详情")
+    @RequiresPermissions("sys:role:normal")
+    public Result<AgentSnapshotVO> getSnapshot(@PathVariable String agentId, @PathVariable String snapshotId) {
+        checkPermission(agentId);
+        return new Result<AgentSnapshotVO>().ok(agentSnapshotService.getSnapshot(agentId, snapshotId));
+    }
+
+    @PostMapping("/{snapshotId}/restore")
+    @Operation(summary = "恢复智能体快照")
+    @RequiresPermissions("sys:role:normal")
+    public Result<Void> restore(@PathVariable String agentId, @PathVariable String snapshotId,
+            @RequestBody @Valid AgentSnapshotRestoreDTO request) {
+        checkPermission(agentId);
+        agentSnapshotService.restoreSnapshot(agentId, snapshotId, request.getCurrentStateToken());
+        return new Result<>();
+    }
+
+    @DeleteMapping("/{snapshotId}")
+    @Operation(summary = "删除智能体历史快照")
+    @RequiresPermissions("sys:role:normal")
+    public Result<Void> deleteSnapshot(@PathVariable String agentId, @PathVariable String snapshotId) {
+        checkPermission(agentId);
+        agentSnapshotService.deleteSnapshot(agentId, snapshotId);
+        return new Result<>();
+    }
+
+    private void checkPermission(String agentId) {
+        UserDetail user = SecurityUser.getUser();
+        if (user == null || !agentService.checkAgentPermission(agentId, user.getId())) {
+            throw new RenException("没有权限访问该智能体快照");
+        }
+    }
+}
@@ -36,4 +36,20 @@ public interface AgentDao extends BaseDao<AgentEntity> {
     * @param agentId 智能体ID
     */
    AgentInfoVO selectAgentInfoById(@Param("agentId") String agentId);
+
+    /**
+     * 锁定智能体主记录，用于串行化同一智能体的配置写入
+     *
+     * @param agentId 智能体ID
+     */
+    AgentEntity selectByIdForUpdate(@Param("agentId") String agentId);
+
+    /**
+     * 精确写入快照覆盖的智能体字段，包括目标快照中的 null 值。
+     * 不更新所属用户、创建信息等不属于快照的字段。
+     *
+     * @param agent 已应用目标快照的智能体
+     * @return 受影响行数
+     */
+    int updateSnapshotFields(@Param("agent") AgentEntity agent);
 }
@@ -0,0 +1,29 @@
+package xiaozhi.modules.agent.dao;
+
+import java.util.List;
+
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+
+import xiaozhi.common.dao.BaseDao;
+import xiaozhi.modules.agent.entity.AgentSnapshotEntity;
+
+@Mapper
+public interface AgentSnapshotDao extends BaseDao<AgentSnapshotEntity> {
+    Integer selectMaxVersionNo(@Param("agentId") String agentId);
+
+    AgentSnapshotEntity selectLatestSnapshot(@Param("agentId") String agentId);
+
+    AgentSnapshotEntity selectNextSnapshot(@Param("agentId") String agentId, @Param("versionNo") Integer versionNo);
+
+    int insertWithNextVersion(@Param("snapshot") AgentSnapshotEntity snapshot);
+
+    int deleteOlderThanKeepLimit(@Param("agentId") String agentId, @Param("keepLimit") int keepLimit);
+
+    List<AgentSnapshotEntity> selectLegacyRedactionBatch(@Param("afterId") String afterId,
+            @Param("limit") int limit,
+            @Param("targetRedactionVersion") int targetRedactionVersion);
+
+    int updateRedactedSnapshots(@Param("snapshots") List<AgentSnapshotEntity> snapshots,
+            @Param("redactionVersion") int redactionVersion);
+}
@@ -0,0 +1,40 @@
+package xiaozhi.modules.agent.dto;
+
+import java.io.Serializable;
+import java.util.List;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+@Data
+@Schema(description = "智能体快照数据")
+public class AgentSnapshotDataDTO implements Serializable {
+    private static final long serialVersionUID = 1L;
+
+    private String agentCode;
+    private String agentName;
+    private String asrModelId;
+    private String vadModelId;
+    private String llmModelId;
+    private String slmModelId;
+    private String vllmModelId;
+    private String ttsModelId;
+    private String ttsVoiceId;
+    private String ttsLanguage;
+    private Integer ttsVolume;
+    private Integer ttsRate;
+    private Integer ttsPitch;
+    private String memModelId;
+    private String intentModelId;
+    private Integer chatHistoryConf;
+    private String systemPrompt;
+    private String summaryMemory;
+    private String langCode;
+    private String language;
+    private Integer sort;
+    private List<AgentUpdateDTO.FunctionInfo> functions;
+    private List<ContextProviderDTO> contextProviders;
+    private List<String> correctWordFileIds;
+    private List<String> tagNames;
+    private List<AgentSnapshotTagDTO> tags;
+}
@@ -0,0 +1,28 @@
+package xiaozhi.modules.agent.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+@Data
+@Schema(description = "智能体快照分页查询参数")
+public class AgentSnapshotPageDTO {
+    @Schema(description = "当前页码，从1开始", example = "1")
+    private Integer page = 1;
+
+    @Schema(description = "每页数量", example = "10")
+    private Integer limit = 10;
+
+    @Schema(description = "版本锚点，只查询小于等于该版本号的历史快照", example = "20")
+    private Integer maxVersionNo;
+
+    public int pageOrDefault() {
+        return page == null || page < 1 ? 1 : page;
+    }
+
+    public int limitOrDefault() {
+        if (limit == null || limit < 1) {
+            return 10;
+        }
+        return limit;
+    }
+}
@@ -0,0 +1,13 @@
+package xiaozhi.modules.agent.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotBlank;
+import lombok.Data;
+
+@Data
+@Schema(description = "智能体快照恢复请求")
+public class AgentSnapshotRestoreDTO {
+    @NotBlank
+    @Schema(description = "预览时由服务端生成的当前配置状态指纹")
+    private String currentStateToken;
+}
@@ -0,0 +1,16 @@
+package xiaozhi.modules.agent.dto;
+
+import java.io.Serializable;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+@Data
+@Schema(description = "智能体快照标签")
+public class AgentSnapshotTagDTO implements Serializable {
+    private static final long serialVersionUID = 1L;
+
+    private String id;
+    private String tagName;
+    private Integer sort;
+}
@@ -4,9 +4,12 @@ import java.io.Serializable;
 import java.math.BigDecimal;
 import java.util.HashMap;
 import java.util.List;
+import java.util.Map;

+import com.fasterxml.jackson.core.type.TypeReference;
 import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
+import xiaozhi.common.utils.JsonUtils;

 /**
 * 智能体更新DTO
@@ -91,14 +94,49 @@ public class AgentUpdateDTO implements Serializable {
    @Schema(description = "替换词文件ID列表", nullable = true)
    private List<String> correctWordFileIds;

+    @Schema(description = "标签名称列表", nullable = true)
+    private List<String> tagNames;
+
+    @Schema(description = "标签ID列表", nullable = true)
+    private List<String> tagIds;
+
    @Data
    @Schema(description = "插件函数信息")
    public static class FunctionInfo implements Serializable {
+        private static final TypeReference<HashMap<String, Object>> PARAM_INFO_TYPE = new TypeReference<>() {
+        };
+
        @Schema(description = "插件ID", example = "plugin_01")
        private String pluginId;

        @Schema(description = "函数参数信息", nullable = true)
-        private HashMap<String, Object> paramInfo;
+        private HashMap<String, Object> paramInfo = new HashMap<>();
+
+        public void setParamInfo(Object paramInfo) {
+            this.paramInfo = normalizeParamInfo(paramInfo);
+        }
+
+        private static HashMap<String, Object> normalizeParamInfo(Object paramInfo) {
+            if (paramInfo == null) {
+                return new HashMap<>();
+            }
+            if (paramInfo instanceof String value) {
+                if (value.trim().isEmpty()) {
+                    return new HashMap<>();
+                }
+                return JsonUtils.parseObject(value, PARAM_INFO_TYPE);
+            }
+            if (paramInfo instanceof Map<?, ?> value) {
+                HashMap<String, Object> normalized = new HashMap<>();
+                value.forEach((key, val) -> {
+                    if (key != null) {
+                        normalized.put(String.valueOf(key), val);
+                    }
+                });
+                return normalized;
+            }
+            return JsonUtils.parseObject(JsonUtils.toJsonString(paramInfo), PARAM_INFO_TYPE);
+        }

        private static final long serialVersionUID = 1L;
    }
@@ -1,48 +0,0 @@
-package xiaozhi.modules.agent.dto;
-
-import lombok.Data;
-
-/**
- * MCP JSON-RPC 响应 DTO
- */
-@Data
-public class McpJsonRpcResponse {
-    private String jsonrpc = "2.0";
-    private Integer id;
-    private McpResult result;
-    private McpError error;
-
-    public McpJsonRpcResponse() {
-    }
-
-    @Data
-    public static class McpResult {
-        private String type;
-        private String message;
-        private String agent_id;
-        private McpTool[] tools;
-
-        public McpResult() {
-        }
-    }
-
-    @Data
-    public static class McpTool {
-        private String name;
-        private String description;
-        private Object inputSchema;
-
-        public McpTool() {
-        }
-    }
-
-    @Data
-    public static class McpError {
-        private Integer code;
-        private String message;
-        private Object data;
-
-        public McpError() {
-        }
-    }
-}
@@ -7,11 +7,11 @@ 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;
+import xiaozhi.modules.agent.typehandler.ContextProviderListTypeHandler;

@Data
@TableName(value = "ai_agent_context_provider", autoResultMap = true)
@@ -26,7 +26,7 @@ public class AgentContextProviderEntity {
    private String agentId;

    @Schema(description = "上下文源配置")
-    @TableField(typeHandler = JacksonTypeHandler.class)
+    @TableField(typeHandler = ContextProviderListTypeHandler.class)
    private List<ContextProviderDTO> contextProviders;

    @Schema(description = "创建者")
@@ -0,0 +1,53 @@
+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_snapshot")
+@Schema(description = "智能体配置快照")
+public class AgentSnapshotEntity {
+
+    @TableId(type = IdType.ASSIGN_UUID)
+    @Schema(description = "快照ID")
+    private String id;
+
+    @Schema(description = "智能体ID")
+    private String agentId;
+
+    @Schema(description = "所属用户ID")
+    private Long userId;
+
+    @Schema(description = "版本号")
+    private Integer versionNo;
+
+    @Schema(description = "快照数据JSON")
+    private String snapshotData;
+
+    @Schema(description = "变更字段JSON")
+    private String changedFields;
+
+    @Schema(description = "快照来源")
+    private String source;
+
+    @Schema(description = "恢复来源快照ID")
+    private String restoreFromSnapshotId;
+
+    @Schema(description = "恢复来源版本号")
+    private Integer restoreFromVersionNo;
+
+    @Schema(description = "创建者")
+    private Long creator;
+
+    @Schema(description = "创建时间")
+    private Date createdAt;
+
+    @Schema(description = "快照数据脱敏规则版本")
+    private Integer redactionVersion;
+}
@@ -1,6 +1,6 @@
 package xiaozhi.modules.agent.service;

-import com.baomidou.mybatisplus.extension.service.IService;
+import com.baomidou.mybatisplus.extension.repository.IRepository;

 import xiaozhi.modules.agent.entity.AgentChatAudioEntity;

@@ -11,7 +11,7 @@ import xiaozhi.modules.agent.entity.AgentChatAudioEntity;
 * @version 1.0, 2025/5/8
 * @since 1.0.0
 */
-public interface AgentChatAudioService extends IService<AgentChatAudioEntity> {
+public interface AgentChatAudioService extends IRepository<AgentChatAudioEntity> {
    /**
     * 保存音频数据
     *
@@ -3,7 +3,7 @@ package xiaozhi.modules.agent.service;
 import java.util.List;
 import java.util.Map;

-import com.baomidou.mybatisplus.extension.service.IService;
+import com.baomidou.mybatisplus.extension.repository.IRepository;

 import xiaozhi.common.page.PageData;
 import xiaozhi.modules.agent.dto.AgentChatHistoryDTO;
@@ -18,7 +18,7 @@ import xiaozhi.modules.agent.vo.AgentChatHistoryUserVO;
 * @version 1.0, 2025/4/30
 * @since 1.0.0
 */
-public interface AgentChatHistoryService extends IService<AgentChatHistoryEntity> {
+public interface AgentChatHistoryService extends IRepository<AgentChatHistoryEntity> {

    /**
     * 根据智能体ID获取会话列表
@@ -37,6 +37,14 @@ public interface AgentChatHistoryService extends IService<AgentChatHistoryEntity
     */
    List<AgentChatHistoryDTO> getChatHistoryBySessionId(String agentId, String sessionId);

+    /**
+     * 根据会话ID获取智能体ID
+     *
+     * @param sessionId 会话ID
+     * @return 智能体ID
+     */
+    String getAgentIdBySessionId(String sessionId);
+
    /**
     * 根据智能体ID删除聊天记录
     *
@@ -62,6 +70,14 @@ public interface AgentChatHistoryService extends IService<AgentChatHistoryEntity
     */
    String getContentByAudioId(String audioId);

+    /**
+     * 根据音频ID获取智能体ID
+     *
+     * @param audioId 音频ID
+     * @return 智能体ID
+     */
+    String getAgentIdByAudioId(String audioId);
+

    /**
     * 查询此音频id是否属于此智能体
@@ -2,7 +2,7 @@ package xiaozhi.modules.agent.service;

 import java.util.List;

-import com.baomidou.mybatisplus.extension.service.IService;
+import com.baomidou.mybatisplus.extension.repository.IRepository;

 import xiaozhi.modules.agent.entity.AgentPluginMapping;

@@ -10,7 +10,7 @@ import xiaozhi.modules.agent.entity.AgentPluginMapping;
 * @description 针对表【ai_agent_plugin_mapping(Agent与插件的唯一映射表)】的数据库操作Service
 * @createDate 2025-05-25 22:33:17
 */
-public interface AgentPluginMappingService extends IService<AgentPluginMapping> {
+public interface AgentPluginMappingService extends IRepository<AgentPluginMapping> {

    /**
     * 根据智能体id获取插件参数
@@ -7,6 +7,7 @@ import xiaozhi.common.page.PageData;
 import xiaozhi.common.service.BaseService;
 import xiaozhi.modules.agent.dto.AgentCreateDTO;
 import xiaozhi.modules.agent.dto.AgentDTO;
+import xiaozhi.modules.agent.dto.AgentMemoryDTO;
 import xiaozhi.modules.agent.dto.AgentUpdateDTO;
 import xiaozhi.modules.agent.entity.AgentEntity;
 import xiaozhi.modules.agent.vo.AgentInfoVO;
@@ -35,6 +36,15 @@ public interface AgentService extends BaseService<AgentEntity> {
     */
    AgentInfoVO getAgentById(String id);

+    /**
+     * 根据ID获取当前用户有权访问的智能体
+     *
+     * @param id     智能体ID
+     * @param userId 当前用户ID
+     * @return 智能体实体
+     */
+    AgentInfoVO getAgentById(String id, Long userId);
+
    /**
     * 插入智能体
     *
@@ -50,6 +60,13 @@ public interface AgentService extends BaseService<AgentEntity> {
     */
    void deleteAgentByUserId(Long userId);

+    /**
+     * 删除智能体及其关联数据
+     *
+     * @param agentId 智能体ID
+     */
+    void deleteAgent(String agentId);
+
    /**
     * 获取用户智能体列表
     *
@@ -93,6 +110,41 @@ public interface AgentService extends BaseService<AgentEntity> {
     */
    void updateAgentById(String agentId, AgentUpdateDTO dto);

+    /**
+     * 更新当前用户有权访问的智能体
+     *
+     * @param agentId 智能体ID
+     * @param dto     更新智能体所需的信息
+     * @param userId  当前用户ID
+     */
+    void updateAgentById(String agentId, AgentUpdateDTO dto, Long userId);
+
+    /**
+     * 根据设备MAC地址更新当前用户有权访问的智能体记忆
+     *
+     * @param macAddress 设备MAC地址
+     * @param dto        智能体记忆
+     * @param userId     当前用户ID
+     */
+    void updateAgentMemoryByDeviceMacAddress(String macAddress, AgentMemoryDTO dto, Long userId);
+
+    /**
+     * 删除当前用户有权访问的智能体
+     *
+     * @param agentId 智能体ID
+     * @param userId  当前用户ID
+     */
+    void deleteAgentById(String agentId, Long userId);
+
+    /**
+     * 更新智能体
+     *
+     * @param agentId        智能体ID
+     * @param dto            更新智能体所需的信息
+     * @param createSnapshot 是否创建配置快照
+     */
+    void updateAgentById(String agentId, AgentUpdateDTO dto, boolean createSnapshot);
+
    /**
     * 创建智能体
     *
@@ -0,0 +1,25 @@
+package xiaozhi.modules.agent.service;
+
+import xiaozhi.common.page.PageData;
+import xiaozhi.common.service.BaseService;
+import xiaozhi.modules.agent.dto.AgentSnapshotPageDTO;
+import xiaozhi.modules.agent.entity.AgentSnapshotEntity;
+import xiaozhi.modules.agent.vo.AgentSnapshotVO;
+
+public interface AgentSnapshotService extends BaseService<AgentSnapshotEntity> {
+    void createSnapshot(String agentId, String source);
+
+    PageData<AgentSnapshotVO> page(String agentId, AgentSnapshotPageDTO params);
+
+    AgentSnapshotVO getSnapshot(String agentId, String snapshotId);
+
+    void restoreSnapshot(String agentId, String snapshotId, String currentStateToken);
+
+    void deleteSnapshot(String agentId, String snapshotId);
+
+    Integer getCurrentVersionNo(String agentId);
+
+    void deleteByAgentId(String agentId);
+
+    long redactLegacySnapshots();
+}
@@ -1,6 +1,6 @@
 package xiaozhi.modules.agent.service;

-import com.baomidou.mybatisplus.extension.service.IService;
+import com.baomidou.mybatisplus.extension.repository.IRepository;

 import xiaozhi.modules.agent.entity.AgentTemplateEntity;

@@ -9,7 +9,7 @@ import xiaozhi.modules.agent.entity.AgentTemplateEntity;
 * @description 针对表【ai_agent_template(智能体配置模板表)】的数据库操作Service
 * @createDate 2025-03-22 11:48:18
 */
-public interface AgentTemplateService extends IService<AgentTemplateEntity> {
+public interface AgentTemplateService extends IRepository<AgentTemplateEntity> {

    /**
     * 获取默认模板
@@ -2,7 +2,7 @@ package xiaozhi.modules.agent.service.impl;

 import org.springframework.stereotype.Service;

-import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
+import com.baomidou.mybatisplus.spring.repository.CrudRepository;

 import xiaozhi.modules.agent.dao.AiAgentChatAudioDao;
 import xiaozhi.modules.agent.entity.AgentChatAudioEntity;
@@ -16,7 +16,7 @@ import xiaozhi.modules.agent.service.AgentChatAudioService;
 * @since 1.0.0
 */
@Service
-public class AgentChatAudioServiceImpl extends ServiceImpl<AiAgentChatAudioDao, AgentChatAudioEntity>
+public class AgentChatAudioServiceImpl extends CrudRepository<AiAgentChatAudioDao, AgentChatAudioEntity>
        implements AgentChatAudioService {
    @Override
    public String saveAudio(byte[] audioData) {
@@ -14,7 +14,7 @@ import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
 import com.baomidou.mybatisplus.core.metadata.IPage;
 import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
-import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
+import com.baomidou.mybatisplus.spring.repository.CrudRepository;

 import xiaozhi.common.constant.Constant;
 import xiaozhi.common.page.PageData;
@@ -39,7 +39,7 @@ import xiaozhi.modules.agent.vo.AgentChatHistoryUserVO;
 */
@Service
@RequiredArgsConstructor
-public class AgentChatHistoryServiceImpl extends ServiceImpl<AiAgentChatHistoryDao, AgentChatHistoryEntity>
+public class AgentChatHistoryServiceImpl extends CrudRepository<AiAgentChatHistoryDao, AgentChatHistoryEntity>
        implements AgentChatHistoryService {

    private final AgentChatTitleService agentChatTitleService;
@@ -88,6 +88,19 @@ public class AgentChatHistoryServiceImpl extends ServiceImpl<AiAgentChatHistoryD
        return ConvertUtils.sourceToTarget(historyList, AgentChatHistoryDTO.class);
    }

+    @Override
+    public String getAgentIdBySessionId(String sessionId) {
+        if (sessionId == null || sessionId.isBlank()) {
+            return null;
+        }
+        AgentChatHistoryEntity entity = baseMapper.selectOne(
+                new LambdaQueryWrapper<AgentChatHistoryEntity>()
+                        .select(AgentChatHistoryEntity::getAgentId)
+                        .eq(AgentChatHistoryEntity::getSessionId, sessionId)
+                        .last("LIMIT 1"));
+        return entity == null ? null : entity.getAgentId();
+    }
+
    @Override
    @Transactional(rollbackFor = Exception.class)
    public void deleteByAgentId(String agentId, Boolean deleteAudio, Boolean deleteText) {
@@ -176,6 +189,19 @@ public class AgentChatHistoryServiceImpl extends ServiceImpl<AiAgentChatHistoryD
        return agentChatHistoryEntity == null ? null : agentChatHistoryEntity.getContent();
    }

+    @Override
+    public String getAgentIdByAudioId(String audioId) {
+        if (audioId == null || audioId.isBlank()) {
+            return null;
+        }
+        AgentChatHistoryEntity entity = baseMapper.selectOne(
+                new LambdaQueryWrapper<AgentChatHistoryEntity>()
+                        .select(AgentChatHistoryEntity::getAgentId)
+                        .eq(AgentChatHistoryEntity::getAudioId, audioId)
+                        .last("LIMIT 1"));
+        return entity == null ? null : entity.getAgentId();
+    }
+
    @Override
    public boolean isAudioOwnedByAgent(String audioId, String agentId) {
        // 查询是否有指定音频id和智能体id的数据，如果有且只有一条说明此数据属性此智能体
@@ -118,7 +118,7 @@ public class AgentChatSummaryServiceImpl implements AgentChatSummaryService {
                        {
                            setSummaryMemory(summaryDTO.getSummary());
                        }
-                    });
+                    }, false);
                    log.info("成功保存会话 {} 的聊天记录总结到智能体 {}", sessionId, agentId);
                } else {
                    log.info("生成总结失败: {}", summaryDTO.getErrorMessage());
@@ -9,7 +9,7 @@ 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 com.baomidou.mybatisplus.spring.repository.CrudRepository;

 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -29,7 +29,7 @@ import xiaozhi.modules.model.service.ModelConfigService;
@Service
@RequiredArgsConstructor
@Slf4j
-public class AgentPluginMappingServiceImpl extends ServiceImpl<AgentPluginMappingMapper, AgentPluginMapping>
+public class AgentPluginMappingServiceImpl extends CrudRepository<AgentPluginMappingMapper, AgentPluginMapping>
        implements AgentPluginMappingService {
    private final AgentPluginMappingMapper agentPluginMappingMapper;
    private final KnowledgeBaseService knowledgeBaseService;
@@ -15,8 +15,8 @@ import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;

 import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
-import com.baomidou.mybatisplus.core.conditions.update.UpdateWrapper;
 import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.baomidou.mybatisplus.extension.repository.IRepository;

 import lombok.AllArgsConstructor;
 import xiaozhi.common.constant.Constant;
@@ -34,6 +34,7 @@ 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.AgentMemoryDTO;
 import xiaozhi.modules.agent.dto.AgentTagDTO;
 import xiaozhi.modules.agent.dto.AgentUpdateDTO;
 import xiaozhi.modules.agent.entity.AgentContextProviderEntity;
@@ -45,6 +46,7 @@ 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.AgentSnapshotService;
 import xiaozhi.modules.agent.service.AgentTagService;
 import xiaozhi.modules.agent.service.AgentTemplateService;
 import xiaozhi.modules.agent.vo.AgentInfoVO;
@@ -76,6 +78,7 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp
    private final AgentContextProviderService agentContextProviderService;
    private final AgentTagService agentTagService;
    private final CorrectWordFileService correctWordFileService;
+    private final AgentSnapshotService agentSnapshotService;

    @Override
    public PageData<AgentEntity> adminAgentList(Map<String, Object> params) {
@@ -92,6 +95,7 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp
        if (agent == null) {
            throw new RenException(ErrorCode.AGENT_NOT_FOUND);
        }
+        requireCurrentUserPermissionIfPresent(agent);

        if (agent.getMemModelId() != null && agent.getMemModelId().equals(Constant.MEMORY_NO_MEM)) {
            agent.setChatHistoryConf(Constant.ChatHistoryConfEnum.IGNORE.getCode());
@@ -109,11 +113,71 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp
        // 查询替换词文件ID列表
        List<String> correctWordFileIds = correctWordFileService.getAgentCorrectWordFileIds(id);
        agent.setCorrectWordFileIds(correctWordFileIds);
+        agent.setCurrentVersionNo(agentSnapshotService.getCurrentVersionNo(id));

        // 无需额外查询插件列表，已通过SQL查询出来
        return agent;
    }

+    @Override
+    public AgentInfoVO getAgentById(String id, Long userId) {
+        AgentInfoVO agent = getAgentById(id);
+        requireAgentPermission(agent, userId);
+        return agent;
+    }
+
+    private AgentEntity getAgentEntityOrThrow(String agentId) {
+        AgentEntity agent = agentDao.selectById(agentId);
+        if (agent == null) {
+            throw new RenException(ErrorCode.AGENT_NOT_FOUND);
+        }
+        return agent;
+    }
+
+    private boolean isCurrentUserSuperAdmin() {
+        UserDetail user = SecurityUser.getUser();
+        return user != null && Integer.valueOf(SuperAdminEnum.YES.value()).equals(user.getSuperAdmin());
+    }
+
+    private void requireCurrentUserPermissionIfPresent(AgentEntity agent) {
+        Long userId = SecurityUser.getUserId();
+        if (userId != null) {
+            requireAgentPermission(agent, userId);
+        }
+    }
+
+    private boolean hasAgentPermission(AgentEntity agent, Long userId) {
+        if (agent == null) {
+            return false;
+        }
+        if (isCurrentUserSuperAdmin()) {
+            return true;
+        }
+        return userId != null && userId.equals(agent.getUserId());
+    }
+
+    private void requireAgentPermission(AgentEntity agent, Long userId) {
+        if (!hasAgentPermission(agent, userId)) {
+            throw new RenException(ErrorCode.NO_PERMISSION);
+        }
+    }
+
+    private boolean hasDevicePermission(DeviceEntity device, Long userId) {
+        if (device == null) {
+            return false;
+        }
+        if (isCurrentUserSuperAdmin()) {
+            return true;
+        }
+        return userId != null && userId.equals(device.getUserId());
+    }
+
+    private void requireDevicePermission(DeviceEntity device, Long userId) {
+        if (!hasDevicePermission(device, userId)) {
+            throw new RenException(ErrorCode.NO_PERMISSION);
+        }
+    }
+
    @Override
    public boolean insert(AgentEntity entity) {
        // 如果ID为空，自动生成一个UUID作为ID
@@ -135,10 +199,30 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp
    }

    @Override
+    @Transactional(rollbackFor = Exception.class)
    public void deleteAgentByUserId(Long userId) {
-        UpdateWrapper<AgentEntity> wrapper = new UpdateWrapper<>();
-        wrapper.eq("user_id", userId);
-        baseDao.delete(wrapper);
+        List<AgentEntity> agents = baseDao.selectList(new QueryWrapper<AgentEntity>()
+                .select("id")
+                .eq("user_id", userId));
+        for (AgentEntity agent : agents) {
+            deleteAgent(agent.getId());
+        }
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void deleteAgent(String agentId) {
+        if (agentDao.selectByIdForUpdate(agentId) == null) {
+            return;
+        }
+        deviceService.deleteByAgentId(agentId);
+        agentChatHistoryService.deleteByAgentId(agentId, true, true);
+        agentPluginMappingService.deleteByAgentId(agentId);
+        agentContextProviderService.deleteByAgentId(agentId);
+        correctWordFileService.deleteMappingsByAgentId(agentId);
+        agentTagService.deleteAgentTags(agentId);
+        agentSnapshotService.deleteByAgentId(agentId);
+        deleteById(agentId);
    }

    @Override
@@ -254,33 +338,47 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp

    @Override
    public boolean checkAgentPermission(String agentId, Long userId) {
-        if (SecurityUser.getUser() == null || SecurityUser.getUser().getId() == null) {
-            return false;
-        }
-        // 获取智能体信息
-        AgentEntity agent = getAgentById(agentId);
-        if (agent == null) {
-            return false;
-        }
-
-        // 如果是超级管理员，直接返回true
-        if (SecurityUser.getUser().getSuperAdmin() == SuperAdminEnum.YES.value()) {
-            return true;
-        }
-
-        // 检查是否是智能体的所有者
-        return userId.equals(agent.getUserId());
+        AgentEntity agent = agentDao.selectById(agentId);
+        return hasAgentPermission(agent, userId);
    }

    // 根据id更新智能体信息
    @Override
    @Transactional(rollbackFor = Exception.class)
    public void updateAgentById(String agentId, AgentUpdateDTO dto) {
-        // 先查询现有实体
-        AgentEntity existingEntity = this.getAgentById(agentId);
-        if (existingEntity == null) {
+        updateAgentById(agentId, dto, true);
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void updateAgentById(String agentId, AgentUpdateDTO dto, Long userId) {
+        updateAgentById(agentId, dto, userId, true);
+    }
+
+    // 根据id更新智能体信息
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void updateAgentById(String agentId, AgentUpdateDTO dto, boolean createSnapshot) {
+        updateAgentById(agentId, dto, null, createSnapshot);
+    }
+
+    private void updateAgentById(String agentId, AgentUpdateDTO dto, Long userId, boolean createSnapshot) {
+        AgentEntity lockedAgent = agentDao.selectByIdForUpdate(agentId);
+        if (lockedAgent == null) {
            throw new RenException(ErrorCode.AGENT_NOT_FOUND);
        }
+        if (userId == null) {
+            requireCurrentUserPermissionIfPresent(lockedAgent);
+        } else {
+            requireAgentPermission(lockedAgent, userId);
+        }
+
+        // 锁定后查询现有实体和关联配置
+        AgentEntity existingEntity = this.getAgentById(agentId);
+        if (createSnapshot) {
+            int currentVersionNo = agentSnapshotService.getCurrentVersionNo(agentId);
+            agentSnapshotService.createSnapshot(agentId, currentVersionNo == 0 ? "initial" : "current");
+        }

        // 只更新提供的非空字段
        if (dto.getAgentName() != null) {
@@ -385,10 +483,10 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp
                    .toList();

            if (!toUpdate.isEmpty()) {
-                agentPluginMappingService.updateBatchById(toUpdate);
+                agentPluginMappingService.updateBatchById(toUpdate, IRepository.DEFAULT_BATCH_SIZE);
            }
            if (!toInsert.isEmpty()) {
-                agentPluginMappingService.saveBatch(toInsert);
+                agentPluginMappingService.saveBatch(toInsert, IRepository.DEFAULT_BATCH_SIZE);
            }

            // 5. 删除本次不在提交列表里的插件映射
@@ -397,7 +495,7 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp
                    .map(AgentPluginMapping::getId)
                    .toList();
            if (!toDelete.isEmpty()) {
-                agentPluginMappingService.removeBatchByIds(toDelete);
+                agentPluginMappingService.removeByIds(toDelete);
            }
        }

@@ -430,11 +528,42 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp
            correctWordFileService.saveAgentCorrectWords(agentId, dto.getCorrectWordFileIds());
        }

-        boolean b = validateLLMIntentParams(dto.getLlmModelId(), dto.getIntentModelId());
+        // 更新智能体标签
+        if (dto.getTagNames() != null || dto.getTagIds() != null) {
+            agentTagService.saveAgentTags(agentId, dto.getTagIds(), dto.getTagNames());
+        }
+
+        boolean b = validateLLMIntentParams(existingEntity.getLlmModelId(), existingEntity.getIntentModelId());
        if (!b) {
            throw new RenException(ErrorCode.LLM_INTENT_PARAMS_MISMATCH);
        }
        this.updateById(existingEntity);
+        if (createSnapshot) {
+            agentSnapshotService.createSnapshot(agentId, "config");
+        }
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void updateAgentMemoryByDeviceMacAddress(String macAddress, AgentMemoryDTO dto, Long userId) {
+        DeviceEntity device = deviceService.getDeviceByMacAddress(macAddress);
+        if (device == null || StringUtils.isBlank(device.getAgentId()) || dto == null) {
+            return;
+        }
+
+        requireDevicePermission(device, userId);
+
+        AgentUpdateDTO agentUpdateDTO = new AgentUpdateDTO();
+        agentUpdateDTO.setSummaryMemory(dto.getSummaryMemory());
+        updateAgentById(device.getAgentId(), agentUpdateDTO, userId, false);
+    }
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void deleteAgentById(String agentId, Long userId) {
+        AgentEntity agent = getAgentEntityOrThrow(agentId);
+        requireAgentPermission(agent, userId);
+        deleteAgent(agentId);
    }

    /**
@@ -490,10 +619,16 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp
            }

            entity.setTtsVoiceId(template.getTtsVoiceId());
+            entity.setTtsLanguage(defaultIfBlank(template.getTtsLanguage(),
+                    timbreModelService.getDefaultLanguageById(entity.getTtsVoiceId())));
            entity.setMemModelId(template.getMemModelId());
            entity.setIntentModelId(template.getIntentModelId());
            entity.setSystemPrompt(template.getSystemPrompt());
            entity.setSummaryMemory(template.getSummaryMemory());
+            if (Constant.MEMORY_NO_MEM.equals(entity.getMemModelId())
+                    || Constant.MEMORY_MEM_REPORT_ONLY.equals(entity.getMemModelId())) {
+                entity.setSummaryMemory("");
+            }

            // 根据记忆模型类型设置默认的chatHistoryConf值
            if (template.getMemModelId() != null) {
@@ -553,10 +688,15 @@ public class AgentServiceImpl extends BaseServiceImpl<AgentDao, AgentEntity> imp
            toInsert.add(mapping);
        }
        // 保存默认插件
-        agentPluginMappingService.saveBatch(toInsert);
+        agentPluginMappingService.saveBatch(toInsert, IRepository.DEFAULT_BATCH_SIZE);
+        agentSnapshotService.createSnapshot(entity.getId(), "initial");
        return entity.getId();
    }

+    private String defaultIfBlank(String value, String defaultValue) {
+        return StringUtils.isBlank(value) ? defaultValue : value;
+    }
+
    private String getDefaultLLMModelId() {
        try {
            List<ModelConfigEntity> llmConfigs = modelConfigService.getEnabledModelsByType("LLM");
@@ -0,0 +1,59 @@
+package xiaozhi.modules.agent.service.impl;
+
+import java.util.concurrent.TimeUnit;
+
+import org.springframework.beans.factory.SmartInitializingSingleton;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import xiaozhi.modules.agent.service.AgentSnapshotService;
+
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class AgentSnapshotRedactionRunner implements SmartInitializingSingleton {
+    static final long ROLLING_DEPLOYMENT_INITIAL_DELAY_MILLIS = 5_000;
+    static final long ROLLING_DEPLOYMENT_FIXED_DELAY_MILLIS = 15_000;
+
+    private final AgentSnapshotService agentSnapshotService;
+
+    @Override
+    public void afterSingletonsInstantiated() {
+        redactAndReport("startup");
+    }
+
+    @Scheduled(initialDelay = ROLLING_DEPLOYMENT_INITIAL_DELAY_MILLIS,
+            fixedDelay = ROLLING_DEPLOYMENT_FIXED_DELAY_MILLIS)
+    public void redactLateRollingDeploymentWrites() {
+        redactAndReport("rolling-deployment");
+    }
+
+    private void redactAndReport(String trigger) {
+        long startedAt = System.nanoTime();
+        try {
+            long migrated = agentSnapshotService.redactLegacySnapshots();
+            long durationMillis = TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - startedAt);
+            if (migrated > 0) {
+                log.warn("Agent snapshot legacy redaction trigger={} migrated={} durationMs={}. Rotate credentials "
+                        + "that may have appeared in historical snapshot URLs, cookies, sessions, or structured "
+                        + "headers.", trigger, migrated, durationMillis);
+            } else if ("startup".equals(trigger)) {
+                log.info("Agent snapshot legacy redaction startup pass completed: migrated=0 durationMs={}; "
+                        + "rolling-deployment compensation starts after {} ms and repeats every {} ms.",
+                        durationMillis, ROLLING_DEPLOYMENT_INITIAL_DELAY_MILLIS,
+                        ROLLING_DEPLOYMENT_FIXED_DELAY_MILLIS);
+            }
+        } catch (RuntimeException exception) {
+            if ("startup".equals(trigger)) {
+                log.error("Agent snapshot legacy redaction failed during startup; blocking application startup "
+                        + "before it can accept traffic.", exception);
+            } else {
+                log.error("Agent snapshot legacy redaction failed during rolling-deployment compensation; the "
+                        + "scheduler will retry on its next run.", exception);
+            }
+            throw exception;
+        }
+    }
+}
@@ -4,7 +4,7 @@ import org.springframework.stereotype.Service;

 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.core.conditions.update.UpdateWrapper;
-import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
+import com.baomidou.mybatisplus.spring.repository.CrudRepository;

 import xiaozhi.modules.agent.dao.AgentTemplateDao;
 import xiaozhi.modules.agent.entity.AgentTemplateEntity;
@@ -21,7 +21,7 @@ import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
 * @createDate 2025-03-22 11:48:18
 */
@Service
-public class AgentTemplateServiceImpl extends ServiceImpl<AgentTemplateDao, AgentTemplateEntity>
+public class AgentTemplateServiceImpl extends CrudRepository<AgentTemplateDao, AgentTemplateEntity>
        implements AgentTemplateService {

    /**
@@ -22,7 +22,7 @@ import org.springframework.util.MultiValueMap;
 import org.springframework.web.client.RestTemplate;

 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
-import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
+import com.baomidou.mybatisplus.spring.repository.CrudRepository;

 import lombok.extern.slf4j.Slf4j;
 import xiaozhi.common.constant.Constant;
@@ -46,7 +46,7 @@ import xiaozhi.modules.sys.service.SysParamsService;
 */
@Service
@Slf4j
-public class AgentVoicePrintServiceImpl extends ServiceImpl<AgentVoicePrintDao, AgentVoicePrintEntity>
+public class AgentVoicePrintServiceImpl extends CrudRepository<AgentVoicePrintDao, AgentVoicePrintEntity>
        implements AgentVoicePrintService {
    private final AgentChatAudioService agentChatAudioService;
    private final RestTemplate restTemplate;
@@ -0,0 +1,59 @@
+package xiaozhi.modules.agent.typehandler;
+
+import java.sql.CallableStatement;
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import java.sql.SQLException;
+import java.util.Collections;
+import java.util.List;
+
+import org.apache.commons.lang3.StringUtils;
+import org.apache.ibatis.type.BaseTypeHandler;
+import org.apache.ibatis.type.JdbcType;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+
+import xiaozhi.common.utils.JsonUtils;
+import xiaozhi.modules.agent.dto.ContextProviderDTO;
+
+/**
+ * JSON type handler for context providers.
+ *
+ * <p>Do not extend MyBatis-Plus {@code AbstractJsonTypeHandler}: its constructor and JSON handler
+ * contract changed in MyBatis-Plus 3.5.6. {@link BaseTypeHandler} is part of MyBatis itself and
+ * keeps this handler compatible with both 3.5.5 and newer MyBatis-Plus releases.</p>
+ */
+public class ContextProviderListTypeHandler extends BaseTypeHandler<List<ContextProviderDTO>> {
+    private static final TypeReference<List<ContextProviderDTO>> CONTEXT_PROVIDER_LIST_TYPE = new TypeReference<>() {
+    };
+
+    @Override
+    public void setNonNullParameter(PreparedStatement ps, int i, List<ContextProviderDTO> parameter,
+            JdbcType jdbcType) throws SQLException {
+        ps.setString(i, JsonUtils.toJsonString(parameter));
+    }
+
+    @Override
+    public List<ContextProviderDTO> getNullableResult(ResultSet rs, String columnName) throws SQLException {
+        return parseNullable(rs.getString(columnName));
+    }
+
+    @Override
+    public List<ContextProviderDTO> getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
+        return parseNullable(rs.getString(columnIndex));
+    }
+
+    @Override
+    public List<ContextProviderDTO> getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
+        return parseNullable(cs.getString(columnIndex));
+    }
+
+    private List<ContextProviderDTO> parseNullable(String json) {
+        if (StringUtils.isBlank(json)) {
+            return null;
+        }
+        List<ContextProviderDTO> providers = JsonUtils.parseObject(json, CONTEXT_PROVIDER_LIST_TYPE);
+        return providers == null ? Collections.emptyList() : providers;
+    }
+
+}
@@ -1,7 +1,5 @@
 package xiaozhi.modules.agent.vo;

-import com.baomidou.mybatisplus.annotation.TableField;
-import com.baomidou.mybatisplus.extension.handlers.JacksonTypeHandler;
 import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
@@ -20,7 +18,6 @@ import java.util.List;
 public class AgentInfoVO extends AgentEntity
 {
    @Schema(description = "插件列表Id")
-    @TableField(typeHandler = JacksonTypeHandler.class)
    private List<AgentPluginMapping> functions;

    @Schema(description = "上下文源配置")
@@ -28,4 +25,7 @@ public class AgentInfoVO extends AgentEntity

    @Schema(description = "替换词文件ID列表")
    private List<String> correctWordFileIds;
+
+    @Schema(description = "当前配置版本号")
+    private Integer currentVersionNo;
 }
@@ -0,0 +1,34 @@
+package xiaozhi.modules.agent.vo;
+
+import java.util.Date;
+import java.util.List;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+import xiaozhi.modules.agent.dto.AgentSnapshotDataDTO;
+
+@Data
+@Schema(description = "智能体配置快照")
+public class AgentSnapshotVO {
+    private String id;
+    private String agentId;
+    @Schema(description = "所属用户ID，表示该快照归属的智能体所有者")
+    private Long userId;
+    private Integer versionNo;
+    private List<String> changedFields;
+    private List<String> fieldOrder;
+    private String source;
+    @Schema(description = "恢复来源快照ID，仅恢复结果版本有值")
+    private String restoreFromSnapshotId;
+    @Schema(description = "恢复来源版本号，仅恢复结果版本有值")
+    private Integer restoreFromVersionNo;
+    @Schema(description = "创建者，表示触发本次快照写入的操作人")
+    private Long creator;
+    private Date createdAt;
+    private AgentSnapshotDataDTO snapshotData;
+    private AgentSnapshotDataDTO afterSnapshotData;
+    @Schema(description = "恢复预览对应的脱敏当前配置，仅详情接口有值")
+    private AgentSnapshotDataDTO currentSnapshotData;
+    @Schema(description = "恢复预览对应的当前配置状态指纹，仅详情接口有值")
+    private String currentStateToken;
+}
@@ -8,6 +8,7 @@ import org.apache.shiro.authz.annotation.RequiresPermissions;
 import org.springframework.beans.BeanUtils;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.PutMapping;
 import org.springframework.web.bind.annotation.RequestBody;
@@ -174,20 +175,26 @@ public class DeviceController {
        return new Result<Object>().ok(deviceAddressBookService.getAddressBookList(macAddress));
    }

-    @GetMapping("/address-book/lookup")
-    @Operation(summary = "根据昵称查找目标设备")
-    public Result<Map<String, String>> lookupByNickname(String callerMac, String nickname) {
-        Map<String, String> result = deviceAddressBookService.lookupByNickname(callerMac, nickname);
+    @GetMapping("/address-book/call")
+    @Operation(summary = "根据昵称发起呼叫")
+    public Result<Map<String, Object>> callByNickname(String callerMac, String nickname,
+            @RequestParam(required = false, defaultValue = "false") boolean answer) {
+        Map<String, Object> result = deviceAddressBookService.callByNickname(callerMac, nickname, answer);
        if (result == null) {
-            return new Result<Map<String, String>>().error("未找到对应设备");
+            return new Result<Map<String, Object>>().error("未找到对应设备");
        }
-        return new Result<Map<String, String>>().ok(result);
+        return new Result<Map<String, Object>>().ok(result);
    }

    @PutMapping("/address-book/alias")
    @Operation(summary = "更新设备通讯录别名")
    @RequiresPermissions("sys:role:normal")
    public Result<Void> updateAlias(@Valid @RequestBody DeviceAddressBookAliasDTO dto) {
+        UserDetail user = SecurityUser.getUser();
+        DeviceEntity callerDevice = deviceService.getDeviceByMacAddress(dto.getMacAddress());
+        if (callerDevice == null || !callerDevice.getUserId().equals(user.getId())) {
+            return new Result<Void>().error("无权限操作该设备");
+        }
        deviceAddressBookService.saveOrUpdate(dto.getMacAddress(), dto.getTargetMac(), dto.getAlias(), null);
        return new Result<Void>();
    }
@@ -196,14 +203,12 @@ public class DeviceController {
    @Operation(summary = "更新设备通讯录权限")
    @RequiresPermissions("sys:role:normal")
    public Result<Void> updatePermission(@Valid @RequestBody DeviceAddressBookPermissionDTO dto) {
+        UserDetail user = SecurityUser.getUser();
+        DeviceEntity callerDevice = deviceService.getDeviceByMacAddress(dto.getMacAddress());
+        if (callerDevice == null || !callerDevice.getUserId().equals(user.getId())) {
+            return new Result<Void>().error("无权限操作该设备");
+        }
        deviceAddressBookService.saveOrUpdate(dto.getMacAddress(), dto.getTargetMac(), null, dto.getHasPermission());
        return new Result<Void>();
    }
-
-    @GetMapping("/call/forward")
-    @Operation(summary = "转发呼叫请求到网关")
-    public Result<Map<String, Object>> forwardCallRequest(String callerMac, String targetMac, String callerNickname) {
-        Map<String, Object> result = deviceService.forwardCallRequest(callerMac, targetMac, callerNickname);
-        return new Result<Map<String, Object>>().ok(result);
-    }
 }
@@ -26,4 +26,9 @@ public interface DeviceAddressBookDao extends BaseMapper<DeviceAddressBookEntity
     * 更新权限
     */
    void updatePermission(@Param("macAddress") String macAddress, @Param("targetMac") String targetMac, @Param("hasPermission") Boolean hasPermission);
+
+    /**
+     * 批量删除设备相关的通讯录记录
+     */
+    void deleteByMacAddresses(@Param("macAddresses") List<String> macAddresses);
 }
@@ -1,27 +0,0 @@
-package xiaozhi.modules.device.dto;
-
-import io.swagger.v3.oas.annotations.media.Schema;
-import lombok.AllArgsConstructor;
-import lombok.Data;
-
-/**
- * 设备绑定的DTO
- * 
- * @author zjy
- * @since 2025-3-28
- */
-@Data
-@AllArgsConstructor
-@Schema(description = "设备连接头信息")
-public class DeviceBindDTO {
-
-    @Schema(description = "mac地址")
-    private String macAddress;
-
-    @Schema(description = "所属用户id")
-    private Long userId;
-
-    @Schema(description = "智能体id")
-    private String agentId;
-
-}
@@ -38,10 +38,15 @@ public interface DeviceAddressBookService {
    void refreshCache();

    /**
-     * 根据昵称查找目标设备信息
+     * 根据昵称发起呼叫
     * @param callerMac 主叫方MAC地址
     * @param nickname 被叫方昵称
-     * @return {targetMac: 目标MAC, callerNickname: 目标如何称呼主叫方}
+     * @param isAnswer 是否为接听模式（跳过权限检查）
     */
-    Map<String, String> lookupByNickname(String callerMac, String nickname);
+    Map<String, Object> callByNickname(String callerMac, String nickname, boolean isAnswer);
+
+    /**
+     * 批量删除设备相关的通讯录记录
+     */
+    void deleteByMacAddresses(List<String> macAddresses);
 }
@@ -138,10 +138,4 @@ public interface DeviceService extends BaseService<DeviceEntity> {
     */
    Object callDeviceTool(String deviceId, String toolName, Map<String, Object> arguments);

-    /**
-     * 转发呼叫请求到网关
-     * @return 网关响应 {status, message}
-     */
-    Map<String, Object> forwardCallRequest(String callerMac, String targetMac, String callerNickname);
-
    }
@@ -1,20 +1,26 @@
 package xiaozhi.modules.device.service.impl;

+import java.time.Instant;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.stream.Collectors;

 import org.apache.commons.lang3.StringUtils;
+import org.springframework.context.annotation.Lazy;
 import org.springframework.stereotype.Service;

 import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;

+import cn.hutool.json.JSONUtil;
+import xiaozhi.common.constant.Constant;
 import xiaozhi.common.redis.RedisKeys;
 import xiaozhi.common.redis.RedisUtils;
 import xiaozhi.modules.device.dao.DeviceAddressBookDao;
 import xiaozhi.modules.device.entity.DeviceAddressBookEntity;
 import xiaozhi.modules.device.service.DeviceAddressBookService;
 import xiaozhi.modules.device.service.DeviceService;
+import xiaozhi.modules.sys.service.SysParamsService;

@Service
 public class DeviceAddressBookServiceImpl implements DeviceAddressBookService {
@@ -22,12 +28,14 @@ public class DeviceAddressBookServiceImpl implements DeviceAddressBookService {
    private final DeviceAddressBookDao deviceAddressBookDao;
    private final RedisUtils redisUtils;
    private final DeviceService deviceService;
+    private final SysParamsService sysParamsService;

    public DeviceAddressBookServiceImpl(DeviceAddressBookDao deviceAddressBookDao, RedisUtils redisUtils,
-            DeviceService deviceService) {
+            @Lazy DeviceService deviceService, SysParamsService sysParamsService) {
        this.deviceAddressBookDao = deviceAddressBookDao;
        this.redisUtils = redisUtils;
        this.deviceService = deviceService;
+        this.sysParamsService = sysParamsService;
    }

    @Override
@@ -47,33 +55,46 @@ public class DeviceAddressBookServiceImpl implements DeviceAddressBookService {
    }

    @Override
-    public Map<String, String> lookupByNickname(String callerMac, String nickname) {
+    public Map<String, Object> callByNickname(String callerMac, String nickname, boolean isAnswer) {
        Map<String, Map<String, String>> allBooks = getAllAddressBooks();
+
+        if (isAnswer) {
+            return postToMqtt("/api/call/accept", Map.of("mac", callerMac), "接听");
+        }
+
+        // 主动呼叫模式
        Map<String, String> callerBook = allBooks.get(callerMac.toLowerCase());
        if (callerBook == null) {
-            return null;
+            return errorResult("未找到备注为'" + nickname + "'的设备");
        }
-        // 从缓存获取 targetMac，格式: "mac|permission"
        String targetMacWithPerm = callerBook.get(nickname);
        if (targetMacWithPerm == null) {
-            return null;
+            return errorResult("未找到备注为'" + nickname + "'的设备");
        }
-        // 解析 targetMac 和 permission
        String[] parts = targetMacWithPerm.split("\\|");
        String targetMac = parts[0];
        boolean hasPermission = parts.length > 1 && "1".equals(parts[1]);

-        Map<String, String> targetBook = allBooks.get(targetMac.toLowerCase());
-        if (targetBook == null) {
-            return null;
+        if (!hasPermission) {
+            return errorResult("呼叫失败，您没有权限呼叫该设备");
        }
-        // 检查双向关系：目标设备是否也添加了主叫方为联系人
-        String callerNickname = targetBook.get(callerMac.toLowerCase());
-        Map<String, String> result = new HashMap<>();
-        result.put("targetMac", targetMac);
-        result.put("callerNickname", callerNickname);
-        result.put("hasPermission", hasPermission ? "true" : "false");
-        return result;
+
+        // 获取目标设备如何称呼主叫方
+        Map<String, String> targetBook = allBooks.get(targetMac.toLowerCase());
+        String callerNickname = null;
+        if (targetBook != null) {
+            callerNickname = targetBook.get(callerMac.toLowerCase());
+        }
+        if (StringUtils.isBlank(callerNickname)) {
+            callerNickname = deviceService.getDeviceByMacAddress(callerMac).getAlias();
+            if (StringUtils.isBlank(callerNickname)) {
+                callerNickname = formatMacAsDeviceName(callerMac);
+            }
+        }
+
+        return postToMqtt("/api/call/request",
+                Map.of("caller_mac", callerMac, "target_mac", targetMac, "caller_nickname", callerNickname),
+                "呼叫");
    }

    @Override
@@ -81,43 +102,44 @@ public class DeviceAddressBookServiceImpl implements DeviceAddressBookService {
        Map<String, Map<String, String>> result = new HashMap<>();
        List<DeviceAddressBookEntity> allRecords = deviceAddressBookDao.selectList(null);
        Map<String, String> reverseMap = new HashMap<>();
-        Map<String, Boolean> permissionMap = new HashMap<>();
+
        for (DeviceAddressBookEntity entity : allRecords) {
            String macA = entity.getMacAddress().toLowerCase();
            String macB = entity.getTargetMac().toLowerCase();
            String alias = entity.getAlias();
            Boolean hasPermission = entity.getHasPermission();
+
+            // 构建正向映射: A对B的映射 nickname -> macB|permission
+            if (alias != null && !alias.isEmpty()) {
+                result.computeIfAbsent(macA, k -> new HashMap<>());
+                String permStr = (hasPermission != null && hasPermission) ? "1" : "0";
+                result.get(macA).put(alias, macB + "|" + permStr);
+            }
+
+            // 构建反向记录用于查找B对A的称呼
            if (alias != null && !alias.isEmpty()) {
-                // 反向记录: (macB, macA) = B对A的称呼
                reverseMap.put(macB + ":" + macA, alias);
            }
-            // 记录 A 对 B 是否有权限呼叫
-            permissionMap.put(macA + ":" + macB, hasPermission != null && hasPermission);
        }
+
+        // 构建反向映射: B对A的映射 macA -> nickname
        for (DeviceAddressBookEntity entity : allRecords) {
            String macA = entity.getMacAddress().toLowerCase();
            String macB = entity.getTargetMac().toLowerCase();
-            String aliasAtoB = entity.getAlias();
-            result.computeIfAbsent(macA, k -> new HashMap<>());
-            result.computeIfAbsent(macB, k -> new HashMap<>());
-            if (aliasAtoB != null && !aliasAtoB.isEmpty()) {
-                // A对B的映射: nickname -> macB|permission
-                Boolean perm = entity.getHasPermission();
-                String permStr = (perm != null && perm) ? "1" : "0";
-                result.get(macA).put(aliasAtoB, macB + "|" + permStr);
-            }
-            // B对A的映射: macA -> nickname（查反向记录）
            String aliasBtoA = reverseMap.get(macA + ":" + macB);
            if (aliasBtoA != null && !aliasBtoA.isEmpty()) {
+                result.computeIfAbsent(macB, k -> new HashMap<>());
                result.get(macB).put(macA, aliasBtoA);
            }
        }
+
        redisUtils.set(RedisKeys.getAddressBookKey(), result);
    }

    @Override
    public void updateAlias(String macAddress, String targetMac, String alias) {
-        deviceAddressBookDao.updateAlias(macAddress, targetMac, alias);
+        String finalAlias = generateUniqueAlias(macAddress, targetMac, alias);
+        deviceAddressBookDao.updateAlias(macAddress, targetMac, finalAlias);
        refreshCache();
    }

@@ -132,20 +154,23 @@ public class DeviceAddressBookServiceImpl implements DeviceAddressBookService {
        QueryWrapper<DeviceAddressBookEntity> wrapper = new QueryWrapper<>();
        wrapper.eq("mac_address", macAddress).eq("target_mac", targetMac);
        DeviceAddressBookEntity record = deviceAddressBookDao.selectOne(wrapper);
+        System.out.println("saveOrUpdate - mac=" + macAddress + ", targetMac=" + targetMac + ", alias=" + alias + ", record=" + (record == null ? "null" : "not null"));
        if (record == null) {
            DeviceAddressBookEntity entity = new DeviceAddressBookEntity();
            entity.setMacAddress(macAddress);
            entity.setTargetMac(targetMac);
-            // 如果 alias 为空，就用默认使用设备名称
+            // 如果 alias 为空，就默认使用设备名称
            if (StringUtils.isBlank(alias)) {
                alias = deviceService.getDeviceByMacAddress(targetMac).getAlias();
            }
+            // 检查重名
+            alias = generateUniqueAlias(macAddress, targetMac, alias);
            entity.setAlias(alias);
            entity.setHasPermission(hasPermission);
            deviceAddressBookDao.insert(entity);
        } else {
            if (alias != null) {
-                deviceAddressBookDao.updateAlias(macAddress, targetMac, alias);
+                updateAlias(macAddress, targetMac, alias);
            }
            if (hasPermission != null) {
                deviceAddressBookDao.updatePermission(macAddress, targetMac, hasPermission);
@@ -153,4 +178,81 @@ public class DeviceAddressBookServiceImpl implements DeviceAddressBookService {
        }
        refreshCache();
    }
+
+    @Override
+    public void deleteByMacAddresses(List<String> macAddresses) {
+        if (macAddresses == null || macAddresses.isEmpty()) {
+            return;
+        }
+        deviceAddressBookDao.deleteByMacAddresses(macAddresses);
+        refreshCache();
+    }
+
+    private Map<String, Object> errorResult(String message) {
+        Map<String, Object> result = new HashMap<>();
+        result.put("status", "error");
+        result.put("message", message);
+        return result;
+    }
+
+    private Map<String, Object> postToMqtt(String path, Map<String, Object> body, String action) {
+        Map<String, Object> result = new HashMap<>();
+        result.put("status", "error");
+
+        String mqttGatewayUrl = sysParamsService.getValue("server.mqtt_manager_api", true);
+        String mqttSignatureKey = sysParamsService.getValue(Constant.SERVER_MQTT_SECRET, true);
+
+        if (StringUtils.isBlank(mqttGatewayUrl) || "null".equals(mqttGatewayUrl)
+                || MqttGatewayAuthorization.isMissingSignatureKey(mqttSignatureKey)) {
+            result.put("message", action + "失败，网关配置缺失");
+            return result;
+        }
+
+        try {
+            String url = "http://" + mqttGatewayUrl + path;
+            String response = MqttGatewayAuthorization.postJson(
+                    url,
+                    JSONUtil.toJsonStr(body),
+                    mqttSignatureKey,
+                    Instant.now(),
+                    5000);
+
+            if (StringUtils.isNotBlank(response)) {
+                Map<String, Object> gwResult = JSONUtil.parseObj(response);
+                result.put("status", gwResult.get("status"));
+                result.put("message", gwResult.get("message"));
+            }
+            return result;
+        } catch (Exception e) {
+            result.put("message", action + "失败，请稍后再试");
+            return result;
+        }
+    }
+
+    private String formatMacAsDeviceName(String mac) {
+        if (StringUtils.isBlank(mac) || mac.length() < 2) {
+            return mac;
+        }
+        String lastTwo = mac.substring(mac.length() - 2);
+        return "尾号为" + lastTwo + "的设备";
+    }
+
+    private String generateUniqueAlias(String macAddress, String targetMac, String alias) {
+        QueryWrapper<DeviceAddressBookEntity> wrapper = new QueryWrapper<>();
+        wrapper.eq("mac_address", macAddress);
+        List<DeviceAddressBookEntity> existing = deviceAddressBookDao.selectList(wrapper);
+        List<String> existNames = existing.stream()
+                .map(DeviceAddressBookEntity::getAlias)
+                .filter(a -> a != null && !a.isEmpty())
+                .collect(Collectors.toList());
+        if (!existNames.contains(alias)) {
+            return alias;
+        }
+        int suffix = 1;
+        String newAlias;
+        while (existNames.contains(newAlias = alias + suffix)) {
+            suffix++;
+        }
+        return newAlias;
+    }
 }
@@ -6,6 +6,7 @@ import java.security.NoSuchAlgorithmException;
 import java.time.Instant;
 import java.util.ArrayList;
 import java.util.Base64;
+import java.util.Collections;
 import java.util.Date;
 import java.util.HashMap;
 import java.util.List;
@@ -30,15 +31,9 @@ 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;
@@ -63,6 +58,7 @@ import xiaozhi.modules.device.dto.DeviceReportReqDTO;
 import xiaozhi.modules.device.dto.DeviceReportRespDTO;
 import xiaozhi.modules.device.entity.DeviceEntity;
 import xiaozhi.modules.device.entity.OtaEntity;
+import xiaozhi.modules.device.service.DeviceAddressBookService;
 import xiaozhi.modules.device.service.DeviceService;
 import xiaozhi.modules.device.service.OtaService;
 import xiaozhi.modules.device.vo.UserShowDeviceListVO;
@@ -80,6 +76,7 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
    private final SysParamsService sysParamsService;
    private final RedisUtils redisUtils;
    private final OtaService otaService;
+    private final DeviceAddressBookService deviceAddressBookService;

    @Async
    public void updateDeviceConnectionInfo(String agentId, String deviceId, String appVersion) {
@@ -184,14 +181,7 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
                .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 postToMqttGateway(url, params);
        }
        // 返回响应
        return "";
@@ -301,24 +291,30 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
    @Override
    public List<UserShowDeviceListVO> getUserDeviceList(Long userId, String agentId) {
        List<DeviceEntity> devices = getUserDevices(userId, agentId);
-        return devices.stream().map(device -> {
+        return devices.stream().map(this::toUserShowDeviceListVO).toList();
+    }
+
+    private UserShowDeviceListVO toUserShowDeviceListVO(DeviceEntity device) {
        UserShowDeviceListVO vo = ConvertUtils.sourceToTarget(device, UserShowDeviceListVO.class);
        vo.setDeviceType(device.getBoard());
-            // 设置UTC时间戳供前端使用时区转换
-            if (device.getLastConnectedAt() != null) {
-                vo.setLastConnectedAtTimestamp(device.getLastConnectedAt().getTime());
-            }
+        vo.setBoard(device.getBoard());
+        vo.setCreateDateTimestamp(toTimestamp(device.getCreateDate()));
+        vo.setLastConnectedAtTimestamp(toTimestamp(device.getLastConnectedAt()));
        return vo;
-        }).toList();
+    }
+
+    private Long toTimestamp(Date date) {
+        return date == null ? null : date.getTime();
    }

    @Override
    public void unbindDevice(Long userId, String deviceId) {
-        // 先查询设备信息，获取agentId
+        // 先查询设备信息，获取agentId和macAddress
        DeviceEntity device = baseDao.selectById(deviceId);
        if (device == null) {
            return;
        }
+        String macAddress = device.getMacAddress();
        if (StringUtils.isNotBlank(device.getAgentId())) {
            // 清除智能体设备数量缓存
            redisUtils.delete(RedisKeys.getAgentDeviceCountById(device.getAgentId()));
@@ -328,6 +324,9 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
        wrapper.eq("user_id", userId);
        wrapper.eq("id", deviceId);
        baseDao.delete(wrapper);
+
+        // 删除设备相关的通讯录权限记录
+        deviceAddressBookService.deleteByMacAddresses(Collections.singletonList(macAddress));
    }

    @Override
@@ -346,9 +345,23 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>

    @Override
    public void deleteByAgentId(String agentId) {
+        // 先查询该智能体下的所有设备，获取mac地址用于删除通讯录记录
+        QueryWrapper<DeviceEntity> queryWrapper = new QueryWrapper<>();
+        queryWrapper.eq("agent_id", agentId);
+        List<DeviceEntity> devices = baseDao.selectList(queryWrapper);
+
+        // 删除设备
        UpdateWrapper<DeviceEntity> wrapper = new UpdateWrapper<>();
        wrapper.eq("agent_id", agentId);
        baseDao.delete(wrapper);
+
+        // 批量删除这些设备相关的所有通讯录权限记录
+        if (!devices.isEmpty()) {
+            List<String> macAddresses = devices.stream()
+                    .map(DeviceEntity::getMacAddress)
+                    .collect(Collectors.toList());
+            deviceAddressBookService.deleteByMacAddresses(macAddresses);
+        }
    }

    @Override
@@ -364,17 +377,11 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
                        .like(StringUtils.isNotBlank(dto.getKeywords()), "alias", dto.getKeywords()));
        // 循环处理page获取回来的数据，返回需要的字段
        List<UserShowDeviceListVO> list = page.getRecords().stream().map(device -> {
-            UserShowDeviceListVO vo = ConvertUtils.sourceToTarget(device, UserShowDeviceListVO.class);
+            UserShowDeviceListVO vo = toUserShowDeviceListVO(device);
            // 把最后修改的时间，改为简短描述的时间
            vo.setRecentChatTime(DateUtils.getShortTime(device.getUpdateDate()));
            sysUserUtilService.assignUsername(device.getUserId(),
                    vo::setBindUserName);
-            vo.setDeviceType(device.getBoard());
-            vo.setBoard(device.getBoard());
-            // 设置UTC时间戳供前端使用时区转换
-            if (device.getLastConnectedAt() != null) {
-                vo.setLastConnectedAtTimestamp(device.getLastConnectedAt().getTime());
-            }
            return vo;
        }).toList();
        // 计算页数
@@ -678,20 +685,13 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
        return mqtt;
    }

-    /**
-     * 生成BearerToken
-     */
-    private String generateBearerToken() {
-        try {
-            String dateStr = DateUtil.format(new Date(), DatePattern.NORM_DATE_PATTERN);
+    private String postToMqttGateway(String url, Object requestBody) {
        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;
-        }
+        return MqttGatewayAuthorization.postJson(
+                url,
+                JSONUtil.toJsonStr(requestBody),
+                signatureKey,
+                Instant.now());
    }

    @Override
@@ -752,13 +752,7 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
                    .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();
+            String resultMessage = postToMqttGateway(url, requestBody);

            // 解析响应
            if (StringUtils.isBlank(resultMessage)) {
@@ -849,13 +843,7 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
                .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();
+        String resultMessage = postToMqttGateway(url, requestBody);

        // 解析响应
        if (StringUtils.isNotBlank(resultMessage)) {
@@ -891,70 +879,4 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
        }
        return null;
    }
-
-    @Override
-    public Map<String, Object> forwardCallRequest(String callerMac, String targetMac, String callerNickname) {
-        Map<String, Object> result = new HashMap<>();
-        result.put("status", "error");
-        result.put("message", "网关配置缺失");
-
-        // 从系统参数获取网关配置
-        String mqttGatewayUrl = sysParamsService.getValue("server.mqtt_manager_api", true);
-        String mqttSignatureKey = sysParamsService.getValue("server.mqtt_signature_key", true);
-
-        if (StringUtils.isBlank(mqttGatewayUrl) || "null".equals(mqttGatewayUrl)) {
-            log.error("MQTT网关地址未配置");
-            result.put("message", "MQTT网关地址未配置");
-            return result;
-        }
-        if (StringUtils.isBlank(mqttSignatureKey) || "null".equals(mqttSignatureKey)) {
-            log.error("MQTT签名密钥未配置");
-            result.put("message", "MQTT签名密钥未配置");
-            return result;
-        }
-
-        // 生成token: SHA256(date + secret)
-        String dateStr = new java.text.SimpleDateFormat("yyyy-MM-dd").format(new Date());
-        try {
-            java.security.MessageDigest md = java.security.MessageDigest.getInstance("SHA-256");
-            byte[] hash = md.digest((dateStr + mqttSignatureKey).getBytes(StandardCharsets.UTF_8));
-            StringBuilder hexString = new StringBuilder();
-            for (byte b : hash) {
-                String hex = Integer.toHexString(0xff & b);
-                if (hex.length() == 1) {
-                    hexString.append('0');
-                }
-                hexString.append(hex);
-            }
-            String token = hexString.toString();
-
-            // 构建请求体
-            Map<String, Object> body = new HashMap<>();
-            body.put("caller_mac", callerMac);
-            body.put("target_mac", targetMac);
-            body.put("caller_nickname", callerNickname);
-
-            // 发送请求并获取响应
-            String url = "http://" + mqttGatewayUrl + "/api/call/request";
-            String response = cn.hutool.http.HttpRequest.post(url)
-                    .header("Authorization", "Bearer " + token)
-                    .header("Content-Type", "application/json")
-                    .body(JSONUtil.toJsonStr(body))
-                    .timeout(5000)
-                    .execute()
-                    .body();
-
-            // 解析网关响应
-            if (StringUtils.isNotBlank(response)) {
-                Map<String, Object> gwResult = JSONUtil.parseObj(response);
-                result.put("status", gwResult.get("status"));
-                result.put("message", gwResult.get("message"));
-            }
-            return result;
-        } catch (Exception e) {
-            log.error("转发呼叫请求失败: {}", e.getMessage());
-            result.put("message", "呼叫请求转发失败: " + e.getMessage());
-            return result;
-        }
-    }
 }
@@ -0,0 +1,111 @@
+package xiaozhi.modules.device.service.impl;
+
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.ZoneOffset;
+import java.util.List;
+import java.util.function.Function;
+
+import org.apache.commons.lang3.StringUtils;
+
+import cn.hutool.crypto.digest.DigestUtil;
+import cn.hutool.http.ContentType;
+import cn.hutool.http.Header;
+import cn.hutool.http.HttpRequest;
+import cn.hutool.http.HttpResponse;
+
+final class MqttGatewayAuthorization {
+
+    private static final int HTTP_UNAUTHORIZED = 401;
+    private static final int DEFAULT_TIMEOUT_MILLIS = 10000;
+
+    private MqttGatewayAuthorization() {
+    }
+
+    static String postJson(String url, String jsonBody, String signatureKey, Instant now) {
+        return postJson(url, jsonBody, signatureKey, now, DEFAULT_TIMEOUT_MILLIS);
+    }
+
+    static String postJson(String url, String jsonBody, String signatureKey, Instant now, int timeoutMillis) {
+        GatewayResponse response = executeWithDateFallback(
+                signatureKey,
+                now,
+                token -> executeRequest(url, jsonBody, token, timeoutMillis));
+
+        if (response.statusCode() < 200 || response.statusCode() >= 300) {
+            throw new GatewayRequestException(
+                    "MQTT Gateway request failed with HTTP status " + response.statusCode(),
+                    response.statusCode());
+        }
+        return response.body();
+    }
+
+    static List<String> generateDailyTokens(String signatureKey, Instant now) {
+        if (isMissingSignatureKey(signatureKey)) {
+            throw new GatewayRequestException("MQTT Gateway signature key is empty", null);
+        }
+
+        LocalDate utcDate = now.atZone(ZoneOffset.UTC).toLocalDate();
+        return List.of(
+                tokenFor(utcDate, signatureKey),
+                tokenFor(utcDate.minusDays(1), signatureKey),
+                tokenFor(utcDate.plusDays(1), signatureKey));
+    }
+
+    static GatewayResponse executeWithDateFallback(String signatureKey, Instant now,
+            Function<String, GatewayResponse> requestExecutor) {
+        GatewayResponse lastAuthenticationFailure = null;
+        for (String token : generateDailyTokens(signatureKey, now)) {
+            GatewayResponse response = requestExecutor.apply(token);
+            if (!isAuthenticationFailure(response.statusCode())) {
+                return response;
+            }
+            lastAuthenticationFailure = response;
+        }
+
+        Integer statusCode = lastAuthenticationFailure == null ? null : lastAuthenticationFailure.statusCode();
+        throw new GatewayRequestException(
+                "MQTT Gateway rejected all daily authorization tokens"
+                        + (statusCode == null ? "" : " (HTTP " + statusCode + ")"),
+                statusCode);
+    }
+
+    private static String tokenFor(LocalDate date, String signatureKey) {
+        return DigestUtil.sha256Hex(date + signatureKey);
+    }
+
+    private static boolean isAuthenticationFailure(int statusCode) {
+        return statusCode == HTTP_UNAUTHORIZED;
+    }
+
+    static boolean isMissingSignatureKey(String signatureKey) {
+        return StringUtils.isBlank(signatureKey) || "null".equalsIgnoreCase(signatureKey.trim());
+    }
+
+    private static GatewayResponse executeRequest(String url, String jsonBody, String token, int timeoutMillis) {
+        try (HttpResponse response = HttpRequest.post(url)
+                .header(Header.CONTENT_TYPE, ContentType.JSON.getValue())
+                .header(Header.AUTHORIZATION, "Bearer " + token)
+                .body(jsonBody)
+                .timeout(timeoutMillis)
+                .execute()) {
+            return new GatewayResponse(response.getStatus(), response.body());
+        }
+    }
+
+    record GatewayResponse(int statusCode, String body) {
+    }
+
+    static final class GatewayRequestException extends RuntimeException {
+        private final Integer statusCode;
+
+        GatewayRequestException(String message, Integer statusCode) {
+            super(message);
+            this.statusCode = statusCode;
+        }
+
+        Integer statusCode() {
+            return statusCode;
+        }
+    }
+}
@@ -38,10 +38,13 @@ public class UserShowDeviceListVO {
    @Schema(description = "最近对话时间")
    private String recentChatTime;

-    @Schema(description = "最后连接时间(UTC毫秒)")
+    @Schema(description = "最后连接时间戳（毫秒）", type = "string", example = "1783689702000")
    private Long lastConnectedAtTimestamp;

-    @Schema(description = "绑定时间")
+    @Schema(description = "绑定时间戳（毫秒）", type = "string", example = "1783689702000")
+    private Long createDateTimestamp;
+
+    @Schema(description = "绑定时间（兼容字段，请使用 createDateTimestamp）", deprecated = true)
    @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd HH:mm:ss", timezone = "UTC")
    private Date createDate;

@@ -1,68 +0,0 @@
-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;
-}
@@ -67,4 +67,7 @@ public class KnowledgeBaseDTO implements Serializable {

    @Schema(description = "文档数量")
    private Integer documentCount;
+
+    @Schema(description = "异常提示")
+    private String errorMessage;
 }
@@ -1,421 +0,0 @@
-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;
-        }
-    }
-}
@@ -1,126 +0,0 @@
-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;
-    }
-}
@@ -1,50 +0,0 @@
-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;
-    }
-}
@@ -1,523 +0,0 @@
-package xiaozhi.modules.knowledge.dto.chat;
-
-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.*;
-
-/**
- * 对话管理聚合 DTO
- * <p>
- * 容器类，内含对话助手、会话和消息的所有请求/响应对象。
- * </p>
- */
-@Schema(description = "对话管理聚合 DTO")
-public class ChatDTO {
-
-    // ========== 1. 对话助手 (Assistant/Bot) 相关 ==========
-
-    /**
-     * 提示词配置
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "提示词配置")
-    public static class PromptConfig implements Serializable {
-
-        @Schema(description = "系统提示词", example = "你是一个专业的客服助手...")
-        @JsonProperty("prompt")
-        private String systemPrompt;
-
-        @Schema(description = "开场白", example = "您好，我是您的智能助手，请问有什么可以帮您？")
-        private String opener;
-
-        @Schema(description = "空结果回复", example = "抱歉，我没有找到相关信息。")
-        @JsonProperty("empty_response")
-        private String emptyResponse;
-
-        @Schema(description = "是否展示引用", example = "true")
-        @JsonProperty("show_quote")
-        private Boolean quote;
-
-        @Schema(description = "是否启用 TTS", example = "false")
-        private Boolean tts;
-
-        @Schema(description = "相似度阈值 (0.0 - 1.0)", example = "0.2")
-        @JsonProperty("similarity_threshold")
-        private Float similarityThreshold;
-
-        @Schema(description = "关键词相似度权重 (0.0 - 1.0)", example = "0.7")
-        @JsonProperty("keywords_similarity_weight")
-        private Float vectorSimilarityWeight;
-
-        @Schema(description = "检索 Top N", example = "6")
-        @JsonProperty("top_n")
-        private Integer topK;
-
-        @Schema(description = "Rerank 模型", example = "rerank_model_001")
-        @JsonProperty("rerank_model")
-        private String rerankId;
-
-        @Schema(description = "是否启用多轮对话优化", example = "false")
-        @JsonProperty("refine_multiturn")
-        private Boolean refineMultigraph;
-
-        @Schema(description = "变量列表")
-        private List<Map<String, Object>> variables;
-    }
-
-    /**
-     * LLM 配置
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "LLM 模型配置")
-    public static class LLMConfig implements Serializable {
-
-        @NotBlank(message = "模型名称不能为空")
-        @Schema(description = "模型名称", requiredMode = Schema.RequiredMode.REQUIRED, example = "gpt-4")
-        @JsonProperty("model_name")
-        private String modelName;
-
-        @Schema(description = "温度参数 (0.0 - 2.0)", example = "0.7")
-        private Float temperature;
-
-        @Schema(description = "Top P 采样", example = "0.9")
-        @JsonProperty("top_p")
-        private Float topP;
-
-        @Schema(description = "最大 Token 数", example = "4096")
-        @JsonProperty("max_tokens")
-        private Integer maxTokens;
-
-        @Schema(description = "存在惩罚", example = "0.0")
-        @JsonProperty("presence_penalty")
-        private Float presencePenalty;
-
-        @Schema(description = "频率惩罚", example = "0.0")
-        @JsonProperty("frequency_penalty")
-        private Float frequencyPenalty;
-    }
-
-    /**
-     * 创建助手请求
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "创建助手请求")
-    public static class AssistantCreateReq implements Serializable {
-
-        @NotBlank(message = "助手名称不能为空")
-        @Schema(description = "助手名称", requiredMode = Schema.RequiredMode.REQUIRED, example = "智能客服助手")
-        private String name;
-
-        @Schema(description = "助手头像 (Base64 编码)", example = "")
-        private String avatar;
-
-        @Schema(description = "关联的知识库 ID 列表", example = "[\"kb_001\", \"kb_002\"]")
-        @JsonProperty("dataset_ids")
-        private List<String> datasetIds;
-
-        @Schema(description = "助手描述", example = "这是一个智能客服助手")
-        private String description;
-
-        @Schema(description = "LLM 模型配置")
-        @JsonProperty("llm")
-        private LLMConfig llm;
-
-        @Schema(description = "提示词配置")
-        @JsonProperty("prompt")
-        private PromptConfig promptConfig;
-    }
-
-    /**
-     * 更新助手请求
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "更新助手请求")
-    public static class AssistantUpdateReq implements Serializable {
-
-        @Schema(description = "助手名称", example = "智能客服助手 V2")
-        private String name;
-
-        @Schema(description = "助手头像 (Base64 编码)", example = "")
-        private String avatar;
-
-        @Schema(description = "关联的知识库 ID 列表", example = "[\"kb_001\", \"kb_002\"]")
-        @JsonProperty("dataset_ids")
-        private List<String> datasetIds;
-
-        @Schema(description = "助手描述", example = "这是一个智能客服助手")
-        private String description;
-
-        @Schema(description = "LLM 模型配置")
-        @JsonProperty("llm")
-        private LLMConfig llm;
-
-        @Schema(description = "提示词配置")
-        @JsonProperty("prompt")
-        private PromptConfig promptConfig;
-    }
-
-    /**
-     * 查询助手列表请求
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "查询助手列表请求")
-    public static class AssistantListReq implements Serializable {
-
-        @Schema(description = "页码 (从 1 开始)", example = "1")
-        private Integer page;
-
-        @Schema(description = "每页数量", example = "30")
-        @JsonProperty("page_size")
-        private Integer pageSize;
-
-        @Schema(description = "按名称过滤 (模糊匹配)", example = "客服")
-        private String name;
-
-        @Schema(description = "排序字段: create_time / update_time", example = "create_time")
-        private String orderby;
-
-        @Schema(description = "是否降序", example = "true")
-        private Boolean desc;
-
-        @Schema(description = "按 ID 精确筛选", example = "assistant_001")
-        private String id;
-    }
-
-    /**
-     * 助手详情 VO
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "助手详情 VO")
-    public static class AssistantVO implements Serializable {
-
-        @Schema(description = "助手 ID", example = "assistant_001")
-        private String id;
-
-        @Schema(description = "租户 ID", example = "tenant_001")
-        @JsonProperty("tenant_id")
-        private String tenantId;
-
-        @Schema(description = "助手名称", example = "智能客服助手")
-        private String name;
-
-        @Schema(description = "助手头像", example = "")
-        private String avatar;
-
-        @Schema(description = "关联的知识库 ID 列表")
-        @JsonProperty("dataset_ids")
-        private List<String> datasetIds;
-
-        @Schema(description = "关联的知识库列表 (详情)")
-        private List<SimpleDatasetVO> datasets;
-
-        @Schema(description = "助手描述")
-        private String description;
-
-        @Schema(description = "LLM 模型配置")
-        @JsonProperty("llm")
-        private LLMConfig llm;
-
-        @Schema(description = "提示词配置")
-        @JsonProperty("prompt")
-        private PromptConfig promptConfig;
-
-        @Schema(description = "创建时间 (时间戳)", example = "1700000000000")
-        @JsonProperty("create_time")
-        private Long createTime;
-
-        @Schema(description = "更新时间 (时间戳)", example = "1700000001000")
-        @JsonProperty("update_time")
-        private Long updateTime;
-    }
-
-    /**
-     * 删除助手请求
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "删除助手请求")
-    public static class AssistantDeleteReq implements Serializable {
-
-        @Schema(description = "要删除的助手 ID 列表", example = "[\"assistant_001\", \"assistant_002\"]")
-        private List<String> ids;
-    }
-
-    // ========== 2. 会话 (Session) 相关 ==========
-
-    /**
-     * 创建会话请求
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "创建会话请求")
-    public static class SessionCreateReq implements Serializable {
-
-        @Schema(description = "会话名称", example = "技术咨询会话")
-        private String name;
-
-        @Schema(description = "用户 ID", example = "user_001")
-        @JsonProperty("user_id")
-        private String userId;
-    }
-
-    /**
-     * 更新会话请求
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "更新会话请求")
-    public static class SessionUpdateReq implements Serializable {
-
-        @Schema(description = "会话名称", example = "技术咨询会话 - 更新")
-        private String name;
-    }
-
-    /**
-     * 查询会话列表请求
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "查询会话列表请求")
-    public static class SessionListReq implements Serializable {
-
-        @Schema(description = "助手 ID", example = "assistant_001")
-        @JsonProperty("assistant_id")
-        private String assistantId;
-
-        @Schema(description = "页码 (从 1 开始)", example = "1")
-        private Integer page;
-
-        @Schema(description = "每页数量", example = "30")
-        @JsonProperty("page_size")
-        private Integer pageSize;
-
-        @Schema(description = "按名称过滤", example = "技术")
-        private String name;
-
-        @Schema(description = "排序字段", example = "create_time")
-        private String orderby;
-
-        @Schema(description = "是否降序", example = "true")
-        private Boolean desc;
-
-        @Schema(description = "会话 ID 精确筛选", example = "session_001")
-        private String id;
-
-        @Schema(description = "用户标识筛选", example = "user_001")
-        @JsonProperty("user_id")
-        private String userId;
-    }
-
-    /**
-     * 会话详情 VO
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "会话详情 VO")
-    public static class SessionVO implements Serializable {
-
-        @Schema(description = "会话 ID", example = "session_001")
-        private String id;
-
-        @Schema(description = "助手 ID", example = "assistant_001")
-        @JsonProperty("chat_id")
-        private String chatId;
-
-        @Schema(description = "助手 ID (兼容旧版)", example = "assistant_001")
-        @JsonProperty("assistant_id")
-        private String assistantId;
-
-        @Schema(description = "会话名称", example = "技术咨询会话")
-        private String name;
-
-        @Schema(description = "创建时间 (时间戳)", example = "1700000000000")
-        @JsonProperty("create_time")
-        private Long createTime;
-
-        @Schema(description = "更新时间 (时间戳)", example = "1700000001000")
-        @JsonProperty("update_time")
-        private Long updateTime;
-
-        @Schema(description = "创建日期", example = "2024-05-01 10:00:00")
-        @JsonProperty("create_date")
-        private String createDate;
-
-        @Schema(description = "更新日期", example = "2024-05-01 10:00:00")
-        @JsonProperty("update_date")
-        private String updateDate;
-
-        @Schema(description = "用户 ID", example = "user_001")
-        @JsonProperty("user_id")
-        private String userId;
-
-        @Schema(description = "对话历史消息列表")
-        private List<Map<String, Object>> messages;
-    }
-
-    /**
-     * 删除会话请求
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "删除会话请求")
-    public static class SessionDeleteReq implements Serializable {
-
-        @Schema(description = "要删除的会话 ID 列表", example = "[\"session_001\", \"session_002\"]")
-        private List<String> ids;
-    }
-
-    // ========== 3. 消息/对话 (Completion) 相关 ==========
-
-    /**
-     * 发送消息请求
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "发送消息请求")
-    public static class CompletionReq implements Serializable {
-
-        @NotBlank(message = "问题内容不能为空")
-        @Schema(description = "用户问题", requiredMode = Schema.RequiredMode.REQUIRED, example = "请介绍一下你们的产品")
-        private String question;
-
-        @Schema(description = "是否使用流式响应 (SSE)", example = "true")
-        @Builder.Default
-        private Boolean stream = true;
-
-        @NotBlank(message = "会话 ID 不能为空")
-        @Schema(description = "会话 ID (可选，不传则创建新会话)", example = "session_001")
-        @JsonProperty("session_id")
-        private String sessionId;
-
-        @Schema(description = "是否展示引用", example = "true")
-        private Boolean quote;
-
-        @Schema(description = "指定检索的文档 ID 列表 (逗号分隔)", example = "doc_001,doc_002")
-        @JsonProperty("doc_ids")
-        private String docIds;
-
-        @Schema(description = "元数据过滤条件")
-        @JsonProperty("metadata_condition")
-        private Map<String, Object> metadataCondition;
-    }
-
-    /**
-     * 消息响应 VO
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "消息响应 VO")
-    public static class CompletionVO implements Serializable {
-
-        @Schema(description = "AI 回答内容")
-        private String answer;
-
-        @Schema(description = "引用信息")
-        private Reference reference;
-
-        @Schema(description = "会话 ID", example = "session_001")
-        @JsonProperty("session_id")
-        private String sessionId;
-
-        @Schema(description = "任务 ID (用于流式响应追踪)", example = "task_001")
-        @JsonProperty("task_id")
-        private String taskId;
-
-        /**
-         * 引用信息 (检索命中结果)
-         */
-        @Data
-        @NoArgsConstructor
-        @AllArgsConstructor
-        @Builder
-        @Schema(description = "引用信息")
-        public static class Reference implements Serializable {
-
-            @Schema(description = "命中的文档块列表")
-            private List<xiaozhi.modules.knowledge.dto.document.RetrievalDTO.HitVO> chunks;
-
-            @Schema(description = "文档聚合信息")
-            @JsonProperty("doc_aggs")
-            private List<DocAgg> docAggs;
-        }
-
-        /**
-         * 文档聚合信息
-         */
-        @Data
-        @NoArgsConstructor
-        @AllArgsConstructor
-        @Builder
-        @Schema(description = "文档聚合信息")
-        public static class DocAgg implements Serializable {
-
-            @Schema(description = "文档 ID", example = "doc_001")
-            @JsonProperty("doc_id")
-            private String docId;
-
-            @Schema(description = "文档名称", example = "产品手册.pdf")
-            @JsonProperty("doc_name")
-            private String docName;
-
-            @Schema(description = "命中次数", example = "3")
-            private Integer count;
-        }
-    }
-
-    /**
-     * 简易知识库 VO (用于 Assistant 列表)
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "简易知识库 VO")
-    public static class SimpleDatasetVO implements Serializable {
-        @Schema(description = "知识库 ID")
-        private String id;
-        @Schema(description = "知识库名称")
-        private String name;
-        @Schema(description = "头像")
-        private String avatar;
-        @Schema(description = "分块数量")
-        @JsonProperty("chunk_num")
-        private Integer chunkNum;
-    }
-}
@@ -1,79 +0,0 @@
-package xiaozhi.modules.knowledge.dto.common;
-
-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 = "通用扩展功能 DTO")
-public class CommonDTO {
-
-    // ========== 1. 引用详情 (detail_share_embedded) ==========
-
-    @Data
-    @Builder
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Schema(description = "引用详情请求")
-    public static class ReferenceDetailReq implements Serializable {
-        @Schema(description = "切片 ID", requiredMode = Schema.RequiredMode.REQUIRED)
-        @NotBlank(message = "切片 ID 不能为空")
-        @JsonProperty("chunk_id")
-        private String chunkId;
-
-        @Schema(description = "知识库 ID")
-        @JsonProperty("knowledge_id")
-        private String knowledgeId;
-    }
-
-    @Data
-    @Builder
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Schema(description = "引用详情响应")
-    public static class ReferenceDetailVO implements Serializable {
-        @Schema(description = "切片 ID")
-        @JsonProperty("chunk_id")
-        private String chunkId;
-
-        @Schema(description = "完整内容")
-        @JsonProperty("content_with_weight")
-        private String contentWithWeight;
-
-        @Schema(description = "文档名称")
-        @JsonProperty("doc_name")
-        private String docName;
-
-        @Schema(description = "图片 ID 列表")
-        @JsonProperty("img_id")
-        private String imageId; // 注意：RAGFlow 有时返回 String 有时返回 List，需根据实际情况确认，暂定 String 用于 ID
-
-        @Schema(description = "文档 ID")
-        @JsonProperty("doc_id")
-        private String docId;
-    }
-
-    // ========== 2. 通用问答 (ask_about) - 调试用 ==========
-
-    @Data
-    @Builder
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Schema(description = "通用问答请求 (调试用)")
-    public static class AskAboutReq implements Serializable {
-        @Schema(description = "用户问题", requiredMode = Schema.RequiredMode.REQUIRED, example = "What is this dataset about?")
-        @NotBlank(message = "问题不能为空")
-        @JsonProperty("question")
-        private String question;
-
-        @Schema(description = "数据集 ID 列表", requiredMode = Schema.RequiredMode.REQUIRED)
-        @NotEmpty(message = "数据集列表不能为空")
-        @JsonProperty("dataset_ids")
-        private List<String> datasetIds;
-    }
-
-    // 响应通常复用 String 或者简单的 Map 结构，视具体实现而定，暂不定义专用 VO
-}
@@ -1,363 +0,0 @@
-package xiaozhi.modules.knowledge.dto.file;
-
-import lombok.*;
-import io.swagger.v3.oas.annotations.media.Schema;
-import java.io.Serializable;
-import java.util.List;
-import com.fasterxml.jackson.annotation.JsonProperty;
-import jakarta.validation.constraints.*;
-import org.springframework.web.multipart.MultipartFile;
-
-/**
- * 文件管理聚合 DTO
- * <p>
- * 容器类，内含文件模块所有请求/响应对象的静态内部类定义。
- * </p>
- */
-@Schema(description = "文件管理聚合 DTO")
-public class FileDTO {
-
-    // ========== 请求类 ==========
-
-    /**
-     * 文件上传请求 (对应接口 1: upload)
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "文件上传请求")
-    public static class UploadReq implements Serializable {
-
-        @NotNull(message = "文件不能为空")
-        @Schema(description = "上传的文件", requiredMode = Schema.RequiredMode.REQUIRED)
-        private MultipartFile file;
-
-        @Schema(description = "父文件夹 ID (为空则上传到根目录)", example = "folder_001")
-        @JsonProperty("parent_id")
-        private String parentId;
-    }
-
-    /**
-     * 新建文件夹请求 (对应接口 2: create)
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "新建文件夹请求")
-    public static class CreateReq implements Serializable {
-
-        @NotBlank(message = "文件夹名称不能为空")
-        @Schema(description = "文件夹名称", requiredMode = Schema.RequiredMode.REQUIRED, example = "新建文件夹")
-        private String name;
-
-        @Schema(description = "父文件夹 ID (为空则创建在根目录)", example = "folder_001")
-        @JsonProperty("parent_id")
-        private String parentId;
-
-        @NotBlank(message = "类型不能为空")
-        @Schema(description = "类型: FOLDER", requiredMode = Schema.RequiredMode.REQUIRED, example = "FOLDER")
-        @Builder.Default
-        private String type = "FOLDER";
-    }
-
-    /**
-     * 重命名请求 (对应接口 6: rename)
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "重命名请求")
-    public static class RenameReq implements Serializable {
-
-        @NotBlank(message = "文件 ID 不能为空")
-        @Schema(description = "文件/文件夹 ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "file_001")
-        @JsonProperty("file_id")
-        private String fileId;
-
-        @NotBlank(message = "新名称不能为空")
-        @Schema(description = "新名称", requiredMode = Schema.RequiredMode.REQUIRED, example = "重命名后的文件")
-        private String name;
-    }
-
-    /**
-     * 移动请求 (对应接口 7: move)
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "移动请求")
-    public static class MoveReq implements Serializable {
-
-        @NotEmpty(message = "源文件 ID 列表不能为空")
-        @Schema(description = "源文件/文件夹 ID 列表", requiredMode = Schema.RequiredMode.REQUIRED, example = "[\"file_001\", \"file_002\"]")
-        @JsonProperty("src_file_ids")
-        private List<String> srcFileIds;
-
-        @NotBlank(message = "目标文件夹 ID 不能为空")
-        @Schema(description = "目标文件夹 ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "folder_002")
-        @JsonProperty("dest_file_id")
-        private String destFileId;
-    }
-
-    /**
-     * 批量删除请求 (对应接口 8: rm)
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "批量删除请求")
-    public static class RemoveReq implements Serializable {
-
-        @NotEmpty(message = "文件 ID 列表不能为空")
-        @Schema(description = "文件/文件夹 ID 列表", requiredMode = Schema.RequiredMode.REQUIRED, example = "[\"file_001\", \"file_002\"]")
-        @JsonProperty("file_ids")
-        private List<String> fileIds;
-    }
-
-    /**
-     * 导入知识库请求 (对应接口 9: convert)
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "导入知识库请求")
-    public static class ConvertReq implements Serializable {
-
-        @NotEmpty(message = "文件 ID 列表不能为空")
-        @Schema(description = "文件 ID 列表", requiredMode = Schema.RequiredMode.REQUIRED, example = "[\"file_001\", \"file_002\"]")
-        @JsonProperty("file_ids")
-        private List<String> fileIds;
-
-        @NotEmpty(message = "知识库 ID 列表不能为空")
-        @Schema(description = "目标知识库 ID 列表", requiredMode = Schema.RequiredMode.REQUIRED, example = "[\"kb_001\"]")
-        @JsonProperty("kb_ids")
-        private List<String> kbIds;
-    }
-
-    /**
-     * 列表查询请求 (对应接口 3: list_files)
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "列表查询请求")
-    public static class ListReq implements Serializable {
-
-        @Schema(description = "父文件夹 ID (为空则查询根目录)", example = "folder_001")
-        @JsonProperty("parent_id")
-        private String parentId;
-
-        @Schema(description = "关键词搜索", example = "文档")
-        private String keywords;
-
-        @Schema(description = "页码 (从 1 开始)", example = "1")
-        private Integer page;
-
-        @Schema(description = "每页数量", example = "30")
-        @JsonProperty("page_size")
-        private Integer pageSize;
-
-        @Schema(description = "排序字段: create_time / update_time / name / size", example = "create_time")
-        private String orderby;
-
-        @Schema(description = "是否降序", example = "true")
-        private Boolean desc;
-    }
-
-    // ========== 响应类 ==========
-
-    /**
-     * 文件/文件夹基础信息 VO
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "文件/文件夹基础信息")
-    public static class InfoVO implements Serializable {
-
-        @Schema(description = "文件/文件夹 ID", example = "file_001")
-        private String id;
-
-        @Schema(description = "父文件夹 ID", example = "folder_001")
-        @JsonProperty("parent_id")
-        private String parentId;
-
-        @Schema(description = "租户 ID", example = "tenant_001")
-        @JsonProperty("tenant_id")
-        private String tenantId;
-
-        @Schema(description = "创建者 ID", example = "user_001")
-        @JsonProperty("created_by")
-        private String createdBy;
-
-        @Schema(description = "类型: FOLDER / FILE", example = "FOLDER")
-        private String type;
-
-        @Schema(description = "名称", example = "我的文件夹")
-        private String name;
-
-        @Schema(description = "路径位置", example = "/root/folder")
-        private String location;
-
-        @Schema(description = "文件大小 (字节)", example = "1024")
-        private Long size;
-
-        @Schema(description = "来源类型", example = "local")
-        @JsonProperty("source_type")
-        private String sourceType;
-
-        @Schema(description = "创建时间 (时间戳)", example = "1700000000000")
-        @JsonProperty("create_time")
-        private Long createTime;
-
-        @Schema(description = "创建日期 (格式化)", example = "2024-01-15 10:30:00")
-        @JsonProperty("create_date")
-        private String createDate;
-
-        @Schema(description = "更新时间 (时间戳)", example = "1700000001000")
-        @JsonProperty("update_time")
-        private Long updateTime;
-
-        @Schema(description = "更新日期 (格式化)", example = "2024-01-15 11:00:00")
-        @JsonProperty("update_date")
-        private String updateDate;
-
-        @Schema(description = "文件扩展名", example = "pdf")
-        private String extension;
-    }
-
-    /**
-     * 列表响应 VO (对应接口 3: list_files)
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "文件列表响应")
-    public static class ListVO implements Serializable {
-
-        @Schema(description = "总记录数", example = "100")
-        private Long total;
-
-        @Schema(description = "当前父文件夹信息")
-        @JsonProperty("parent_folder")
-        private InfoVO parentFolder;
-
-        @Schema(description = "文件/文件夹列表")
-        private List<InfoVO> files;
-
-        @Schema(description = "面包屑导航路径")
-        private List<InfoVO> breadcrumb;
-    }
-
-    /**
-     * 转换结果项 VO (对应接口 9: convert)
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "文件转换结果项")
-    public static class ConvertVO implements Serializable {
-
-        @Schema(description = "转换记录 ID", example = "convert_001")
-        private String id;
-
-        @Schema(description = "源文件 ID", example = "file_001")
-        @JsonProperty("file_id")
-        private String fileId;
-
-        @Schema(description = "目标文档 ID", example = "doc_001")
-        @JsonProperty("document_id")
-        private String documentId;
-
-        @Schema(description = "创建时间 (时间戳)", example = "1700000000000")
-        @JsonProperty("create_time")
-        private Long createTime;
-
-        @Schema(description = "创建日期 (格式化)", example = "2024-01-15 10:30:00")
-        @JsonProperty("create_date")
-        private String createDate;
-
-        @Schema(description = "更新时间 (时间戳)", example = "1700000001000")
-        @JsonProperty("update_time")
-        private Long updateTime;
-
-        @Schema(description = "更新日期 (格式化)", example = "2024-01-15 11:00:00")
-        @JsonProperty("update_date")
-        private String updateDate;
-    }
-
-    /**
-     * 转换状态 VO (对应接口 10: get_convert_status)
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "文件转换状态")
-    public static class ConvertStatusVO implements Serializable {
-
-        @Schema(description = "转换状态: pending / processing / completed / failed", example = "completed")
-        private String status;
-
-        @Schema(description = "转换进度 (0.0 - 1.0)", example = "1.0")
-        private Float progress;
-
-        @Schema(description = "状态消息", example = "转换完成")
-        private String message;
-    }
-
-    /**
-     * 面包屑 VO (对应接口 12: all_parent_folder)
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "面包屑导航 (所有父文件夹)")
-    public static class BreadcrumbVO implements Serializable {
-
-        @Schema(description = "父文件夹列表 (从根到当前的路径)")
-        @JsonProperty("parent_folders")
-        private List<InfoVO> parentFolders;
-    }
-
-    /**
-     * 根目录信息 VO (对应接口 10: get_root_folder)
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "根目录信息")
-    public static class RootFolderVO implements Serializable {
-
-        @Schema(description = "根文件夹信息")
-        @JsonProperty("root_folder")
-        private InfoVO rootFolder;
-    }
-
-    /**
-     * 父目录信息 VO (对应接口 11: get_parent_folder)
-     */
-    @Data
-    @NoArgsConstructor
-    @AllArgsConstructor
-    @Builder
-    @Schema(description = "父目录信息")
-    public static class ParentFolderVO implements Serializable {
-
-        @Schema(description = "父文件夹信息")
-        @JsonProperty("parent_folder")
-        private InfoVO parentFolder;
-    }
-}
@@ -485,16 +485,11 @@ public class RAGFlowAdapter extends KnowledgeBaseAdapter {

    @Override
    public Integer getDocumentCount(String datasetId) {
-        try {
        DatasetDTO.InfoVO info = getDatasetInfo(datasetId);
        if (info != null && info.getDocumentCount() != null) {
            return info.getDocumentCount().intValue();
        }
        return 0;
-        } catch (Exception e) {
-            log.warn("获取文档数量失败: {}", e.getMessage());
-            return 0;
-        }
    }

    @Override
@@ -518,7 +513,7 @@ public class RAGFlowAdapter extends KnowledgeBaseAdapter {
            return null;
        } catch (Exception e) {
            log.warn("获取数据集信息失败: datasetId={}, error={}", datasetId, e.getMessage());
-            return null;
+            throw convertToRenException(e);
        }
    }

@@ -100,9 +100,9 @@ public class KnowledgeBaseServiceImpl extends BaseServiceImpl<KnowledgeBaseDao,
            }

            DatasetDTO.InfoVO datasetInfo = adapter.getDatasetInfo(dto.getDatasetId());
-
+            // getDatasetInfo 正常返回 null 表示远端确实不存在；异常时已抛出 RenException 由外层 catch 接管
            if (datasetInfo == null) {
-                // RAGFlow 端已删除 → 本地级联清理
+                // RAGFlow 端已确认删除 → 本地级联清理
                log.info("数据集 {} 在 RAGFlow 端不存在，执行本地清理", dto.getDatasetId());
                cleanupLocalDataset(dto.getDatasetId(), dto.getId());
                // 标记为已删除，让上层从列表中移除
@@ -145,8 +145,9 @@ public class KnowledgeBaseServiceImpl extends BaseServiceImpl<KnowledgeBaseDao,
            }

        } catch (Exception e) {
-            log.warn("同步数据集信息失败 {}: {}", dto.getName(), e.getMessage());
+            log.error("同步数据集信息失败 {}: {}", dto.getName(), e.getMessage());
            dto.setDocumentCount(0);
+            dto.setErrorMessage(e.getMessage());
        }
    }

@@ -529,7 +529,8 @@ public class KnowledgeFilesServiceImpl extends BaseServiceImpl<DocumentDao, Docu
            adapter.deleteDocument(datasetId, req);
            log.info("远程批量删除请求成功");
        } catch (Exception e) {
-            log.warn("远程删除请求部分或全部失败: {}", e.getMessage());
+            log.error("远程删除请求失败，中止本地清理以避免数据不一致: {}", e.getMessage());
+            throw new RenException(e.getMessage());
        }

        // 4. 原子化清理本地影子记录并同步统计数据
@@ -87,8 +87,7 @@ public class ShiroConfig {
        filterMap.put("/user/retrieve-password", "anon");
        // 将config路径使用server服务过滤器
        filterMap.put("/config/**", "server");
-        filterMap.put("/device/address-book/lookup", "server");
-        filterMap.put("/device/call/forward", "server");
+        filterMap.put("/device/address-book/call", "server");
        filterMap.put("/agent/chat-history/report", "server");
        filterMap.put("/agent/chat-history/download/**", "anon");
        filterMap.put("/agent/chat-summary/**", "server");
@@ -57,6 +57,14 @@ public interface TimbreService extends BaseService<TimbreEntity> {

    List<VoiceDTO> getVoiceNames(String ttsModelId, String voiceName);

+    /**
+     * 获取普通音色或克隆音色配置的首个有效语言。
+     *
+     * @param id 音色ID
+     * @return 默认语言；音色不存在或未配置有效语言时返回null
+     */
+    String getDefaultLanguageById(String id);
+
    /**
     * 根据ID获取音色名称
     * 
@@ -1,6 +1,7 @@
 package xiaozhi.modules.timbre.service.impl;

 import java.util.*;
+import java.util.regex.Pattern;
 import java.util.stream.Collectors;

 import org.apache.commons.lang3.StringUtils;
@@ -41,6 +42,8 @@ import xiaozhi.modules.voiceclone.entity.VoiceCloneEntity;
@Service
 public class TimbreServiceImpl extends BaseServiceImpl<TimbreDao, TimbreEntity> implements TimbreService {

+    private static final Pattern LANGUAGE_SEPARATOR = Pattern.compile("[、；;,，]");
+
    private final TimbreDao timbreDao;
    private final VoiceCloneDao voiceCloneDao;
    private final RedisUtils redisUtils;
@@ -158,6 +161,32 @@ public class TimbreServiceImpl extends BaseServiceImpl<TimbreDao, TimbreEntity>
        return CollectionUtil.isEmpty(voiceDTOs) ? null : voiceDTOs;
    }

+    @Override
+    public String getDefaultLanguageById(String id) {
+        if (StringUtils.isBlank(id)) {
+            return null;
+        }
+
+        TimbreEntity timbre = timbreDao.selectById(id);
+        if (timbre != null) {
+            return firstNonBlankLanguage(timbre.getLanguages());
+        }
+
+        VoiceCloneEntity voiceClone = voiceCloneDao.selectById(id);
+        return voiceClone == null ? null : firstNonBlankLanguage(voiceClone.getLanguages());
+    }
+
+    private String firstNonBlankLanguage(String languages) {
+        if (StringUtils.isBlank(languages)) {
+            return null;
+        }
+        return LANGUAGE_SEPARATOR.splitAsStream(languages)
+                .map(StringUtils::trimToNull)
+                .filter(Objects::nonNull)
+                .findFirst()
+                .orElse(null);
+    }
+
    /**
     * 处理是不是tts模型的id
     */
@@ -0,0 +1,15 @@
+-- 更新EdgeTTS供应器增加语速、音调、音量配置
+UPDATE `ai_model_provider`
+SET fields = '[{"key":"voice","label":"音色","type":"string"},{"key":"output_dir","label":"输出目录","type":"string"},{"key":"rate","label":"语速(-100~100)","type":"number"},{"key":"volume","label":"音量(0~100)","type":"number"},{"key":"pitch","label":"音调(-100~100)","type":"number"}]'
+WHERE id = 'SYSTEM_TTS_edge';
+
+UPDATE `ai_model_config` SET
+`remark` = 'EdgeTTS配置说明：
+1. 使用微软Edge TTS服务
+2. 支持多种语言和音色
+3. 免费使用，无需注册
+4. 需要网络连接
+5. 输出文件保存在tmp/目录
+6. 语速：-100~100，0为正常速度
+7. 音量：0~100，50为正常音量
+8. 音调：-100~100，0为正常音调' WHERE `id` = 'TTS_EdgeTTS';
@@ -0,0 +1,40 @@
+-- 修正、添加Minimax流式TTS音色
+delete from `ai_tts_voice` where tts_model_id = 'TTS_MinimaxStreamTTS';
+
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0001', 'TTS_MinimaxStreamTTS', '少女音', 'female-shaonv', '普通话', NULL, NULL, NULL, NULL, 1, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0002', 'TTS_MinimaxStreamTTS', '成熟女声', 'female-chengshu', '普通话', NULL, NULL, NULL, NULL, 2, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0003', 'TTS_MinimaxStreamTTS', '霸道少爷', 'badao_shaoye', '普通话', NULL, NULL, NULL, NULL, 3, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0004', 'TTS_MinimaxStreamTTS', '病娇弟弟', 'bingjiao_didi', '普通话', NULL, NULL, NULL, NULL, 4, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0005', 'TTS_MinimaxStreamTTS', '纯真学弟', 'chunzhen_xuedi', '普通话', NULL, NULL, NULL, NULL, 5, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0006', 'TTS_MinimaxStreamTTS', '冷淡学长', 'lengdan_xiongzhang', '普通话', NULL, NULL, NULL, NULL, 6, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0007', 'TTS_MinimaxStreamTTS', '甜美小玲', 'tianxin_xiaoling', '普通话', NULL, NULL, NULL, NULL, 7, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0008', 'TTS_MinimaxStreamTTS', '俏皮萌妹', 'qiaopi_mengmei', '普通话', NULL, NULL, NULL, NULL, 8, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0009', 'TTS_MinimaxStreamTTS', '妩媚御姐', 'wumei_yujie', '普通话', NULL, NULL, NULL, NULL, 9, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0010', 'TTS_MinimaxStreamTTS', '调教学妹', 'diadia_xuemei', '普通话', NULL, NULL, NULL, NULL, 10, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0011', 'TTS_MinimaxStreamTTS', '淡雅学姐', 'danya_xuejie', '普通话', NULL, NULL, NULL, NULL, 11, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0012', 'TTS_MinimaxStreamTTS', 'Santa Claus', 'Santa_Claus', '普通话', NULL, NULL, NULL, NULL, 12, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0013', 'TTS_MinimaxStreamTTS', 'Grinch', 'Grinch', '普通话', NULL, NULL, NULL, NULL, 13, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0014', 'TTS_MinimaxStreamTTS', '专业女主持', 'Cantonese_ProfessionalHost（F)', '粤语', "https://filecdn.minimax.chat/public/84589766-c651-477b-b320-36b89599f953.mp3", NULL, NULL, NULL, 14, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0015', 'TTS_MinimaxStreamTTS', '温柔女声', 'Cantonese_GentleLady', '粤语', "https://filecdn.minimax.chat/public/d391936d-d586-4dab-886c-a2a084a20920.mp3", NULL, NULL, NULL, 15, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0016', 'TTS_MinimaxStreamTTS', '专业男主持', 'Cantonese_ProfessionalHost（M)', '粤语', NULL, NULL, NULL, NULL, 16, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0017', 'TTS_MinimaxStreamTTS', '活泼男声', 'Cantonese_PlayfulMan', '粤语', NULL, NULL, NULL, NULL, 17, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0018', 'TTS_MinimaxStreamTTS', '可爱女孩', 'Cantonese_CuteGirl', '粤语', "https://filecdn.minimax.chat/public/ff96520a-ac12-491d-945e-d6337467eb7d.mp3", NULL, NULL, NULL, 18, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0019', 'TTS_MinimaxStreamTTS', '善良女声', 'Cantonese_KindWoman', '粤语', "https://filecdn.minimax.chat/public/78239a18-5e9c-4538-94f6-2f504c080374.mp3", NULL, NULL, NULL, 19, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0020', 'TTS_MinimaxStreamTTS', 'Crisp News Anchor', 'Cantonese_crisp_news_anchor_vv2', '粤语', 'https://cdn.hailuoai.video/open-hailuo-video-web/public_assets/741a5a4b-f42a-4a9b-ae83-3954d097ab73.mp3', NULL, NULL, NULL, 20, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0021', 'TTS_MinimaxStreamTTS', 'Pro Reporter', 'Cantonese_professional_reporter_vv2', '粤语', 'https://cdn.hailuoai.video/open-hailuo-video-web/public_assets/77afb86d-2cc4-4149-8c2e-e1174fa849d4.mp3', NULL, NULL, NULL, 21, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0022', 'TTS_MinimaxStreamTTS', 'Crisp Reporter', 'Cantonese_crisp_reporter_vv2', '粤语', 'https://cdn.hailuoai.video/open-hailuo-video-web/public_assets/4ad39a61-628e-481c-9d60-bfb7c36bceb8.mp3', NULL, NULL, NULL, 22, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0023', 'TTS_MinimaxStreamTTS', 'Articulate', 'Cantonese_Articulate_commentator_vv2', '粤语', 'https://cdn.hailuoai.video/open-hailuo-video-web/public_assets/9346601d-3035-4f9e-9b1c-0e03f30e5eef.mp3', NULL, NULL, NULL, 23, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0024', 'TTS_MinimaxStreamTTS', 'Warm Reporter', 'Cantonese_Warm_Reporter_vv2', '粤语', 'https://cdn.hailuoai.video/open-hailuo-video-web/public_assets/c651050e-d6a5-4653-b09e-5177bdc8b04c.mp3', NULL, NULL, NULL, 24, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0025', 'TTS_MinimaxStreamTTS', 'Energetic', 'Cantonese_energetic_commentator_vv2', '粤语', 'https://cdn.hailuoai.video/open-hailuo-video-web/public_assets/1fd1c461-71da-450d-91bb-45f819249b44.mp3', NULL, NULL, NULL, 25, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0026', 'TTS_MinimaxStreamTTS', 'Objective Narrator', 'Cantonese_objective_narrator_vv2', '粤语', 'https://cdn.hailuoai.video/open-hailuo-video-web/public_assets/463c5a68-a7b5-4fe9-85b6-d494dca74abb.mp3', NULL, NULL, NULL, 26, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0027', 'TTS_MinimaxStreamTTS', '沙哑男声', 'Cantonese_Narrator', '粤语', 'https://filecdn.minimax.chat/public/22e29cb0-0f5a-443a-9fa9-a32dabd55cf9.mp3', NULL, NULL, NULL, 27, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0028', 'TTS_MinimaxStreamTTS', 'News Anchor', 'Cantonese_news_anchor_vv2', '粤语', 'https://cdn.hailuoai.video/open-hailuo-video-web/public_assets/59b9ba49-47d4-48f1-b207-09c0e0769a1b.mp3', NULL, NULL, NULL, 28, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0029', 'TTS_MinimaxStreamTTS', '渊博学者', 'Cantonese_WiselProfessor', '粤语', 'https://filecdn.minimax.chat/public/8de234c4-64a7-4539-a316-c3b43ee1d0a9.mp3', NULL, NULL, NULL, 29, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0030', 'TTS_MinimaxStreamTTS', 'Resonant Host', 'Cantonese_resonant_host_vv2', '粤语', 'https://cdn.hailuoai.video/open-hailuo-video-web/public_assets/ec8fc0ce-6657-4c49-9bf0-3953a15046ec.mp3', NULL, NULL, NULL, 30, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0031', 'TTS_MinimaxStreamTTS', '冷漠员工', 'Cantonese_IndifferentStaff', '粤语', 'https://filecdn.minimax.chat/public/9686682c-3fc8-45f0-bd88-2a4692e1f63e.mp3', NULL, NULL, NULL, 31, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0032', 'TTS_MinimaxStreamTTS', 'Male News Anchor', 'Cantonese_Male_news_anchor_vv2', '粤语', 'https://cdn.hailuoai.video/open-hailuo-video-web/public_assets/2055ee8b-fb25-424c-b8cb-e2baf971e520.mp3', NULL, NULL, NULL, 32, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0033', 'TTS_MinimaxStreamTTS', 'History Narrator', 'Cantonese_casual_narrator_vv2', '粤语', 'https://cdn.hailuoai.video/open-hailuo-video-web/public_assets/c170f9e4-145d-4331-9910-1c3a0e6bbc3a.mp3', NULL, NULL, NULL, 33, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0034', 'TTS_MinimaxStreamTTS', 'Steady Reporter', 'Cantonese_Steady_reporter_vv2', '粤语', 'https://cdn.hailuoai.video/open-hailuo-video-web/public_assets/381cfee2-772d-4a73-b30c-7914aec05771.mp3', NULL, NULL, NULL, 34, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0035', 'TTS_MinimaxStreamTTS', 'Serious Commentator', 'Cantonese_serious_commentator_vv2', '粤语', 'https://cdn.hailuoai.video/open-hailuo-video-web/public_assets/57335c8a-32ea-475f-a198-b0de7fa1b126.mp3', NULL, NULL, NULL, 35, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0036', 'TTS_MinimaxStreamTTS', 'Podcast Host', 'Cantonese_podcast_host_vv2', '粤语', 'https://cdn.hailuoai.video/open-hailuo-video-web/public_assets/048b617f-e1f8-422c-89fb-fdbc6e303675.mp3', NULL, NULL, NULL, 36, NULL, NULL, NULL, NULL);
+INSERT INTO `ai_tts_voice` VALUES ('TTS_MinimaxStreamTTS_0037', 'TTS_MinimaxStreamTTS', 'Obj commentator', 'Cantonese_Objective_commentator_vv2', '粤语', 'https://cdn.hailuoai.video/open-hailuo-video-web/public_assets/a8f55e44-b726-4ba5-815a-f1b515ba57ef.mp3', NULL, NULL, NULL, 37, NULL, NULL, NULL, NULL);
@@ -0,0 +1,19 @@
+-- Add language configuration for local FunASR ASR.
+UPDATE `ai_model_provider`
+SET `fields` = '[{"key":"model_dir","label":"模型目录","type":"string"},{"key":"output_dir","label":"输出目录","type":"string"},{"key":"language","label":"识别语言","type":"string","default":"auto"}]'
+WHERE `id` = 'SYSTEM_ASR_FunASR';
+
+UPDATE `ai_model_config`
+SET `config_json` = JSON_SET(`config_json`, '$.language', 'auto')
+WHERE `id` = 'ASR_FunASR'
+AND JSON_EXTRACT(`config_json`, '$.language') IS NULL;
+
+-- Update the FunASR local model configuration description to mention the language option.
+UPDATE `ai_model_config`
+SET `remark` = 'FunASR本地模型配置说明：
+1. 需要下载模型文件到xiaozhi-server/models/SenseVoiceSmall目录
+2. 支持中日韩粤语音识别
+3. 本地推理，无需网络连接
+4. 待识别文件保存在tmp/目录
+5. “识别语言”字段控制识别语种：auto = 自动检测；如需限定只识别中文可设为 zh（en=英语、ja=日语、ko=韩语、yue=粤语）。'
+WHERE `id` = 'ASR_FunASR';
@@ -0,0 +1,20 @@
+-- liquibase formatted sql
+
+-- changeset tykechen:202607071530
+CREATE TABLE IF NOT EXISTS `ai_agent_snapshot` (
+    `id` VARCHAR(32) NOT NULL COMMENT '快照ID',
+    `agent_id` VARCHAR(32) NOT NULL COMMENT '智能体ID',
+    `user_id` BIGINT DEFAULT NULL COMMENT '所属用户ID',
+    `version_no` INT UNSIGNED NOT NULL COMMENT '版本号',
+    `snapshot_data` JSON NOT NULL DEFAULT (JSON_OBJECT()) COMMENT '快照数据',
+    `changed_fields` JSON DEFAULT NULL COMMENT '变更字段',
+    `source` VARCHAR(32) DEFAULT 'config' COMMENT '快照来源',
+    `restore_from_snapshot_id` VARCHAR(32) DEFAULT NULL COMMENT '恢复来源快照ID',
+    `restore_from_version_no` INT UNSIGNED DEFAULT NULL COMMENT '恢复来源版本号',
+    `creator` BIGINT DEFAULT NULL COMMENT '创建者',
+    `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `uk_agent_version` (`agent_id`, `version_no`),
+    INDEX `idx_agent_created_at` (`agent_id`, `created_at`),
+    INDEX `idx_snapshot_user_created_at` (`user_id`, `created_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='智能体配置快照表';
@@ -0,0 +1,8 @@
+-- liquibase formatted sql
+
+-- changeset tykechen:202607101200
+ALTER TABLE `ai_agent_snapshot`
+    ADD COLUMN `redaction_version` TINYINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '快照脱敏规则版本' AFTER `created_at`,
+    ADD INDEX `idx_snapshot_redaction_version_id` (`redaction_version`, `id`);
+
+-- rollback ALTER TABLE `ai_agent_snapshot` DROP INDEX `idx_snapshot_redaction_version_id`, DROP COLUMN `redaction_version`;
@@ -676,3 +676,38 @@ databaseChangeLog:
        - sqlFile:
            encoding: utf8
            path: classpath:db/changelog/202605251426.sql
+  - changeSet:
+      id: 202606231030
+      author: RanChen
+      changes:
+        - sqlFile:
+            encoding: utf8
+            path: classpath:db/changelog/202606231030.sql
+  - changeSet:
+      id: 202606261131
+      author: RanChen
+      changes:
+        - sqlFile:
+            encoding: utf8
+            path: classpath:db/changelog/202606261131.sql
+  - changeSet:
+      id: 202607011405
+      author: LauraGPT
+      changes:
+        - sqlFile:
+            encoding: utf8
+            path: classpath:db/changelog/202607011405.sql
+  - changeSet:
+      id: 202607071530
+      author: tykechen
+      changes:
+        - sqlFile:
+            encoding: utf8
+            path: classpath:db/changelog/202607071530.sql
+  - changeSet:
+      id: 202607101200
+      author: tykechen
+      changes:
+        - sqlFile:
+            encoding: utf8
+            path: classpath:db/changelog/202607101200.sql
@@ -25,9 +25,6 @@
        <result column="memModelId" property="memModelId"/>
        <result column="intentModelId" property="intentModelId"/>

-        <result column="functions" property="functions"
-                typeHandler="com.baomidou.mybatisplus.extension.handlers.JacksonTypeHandler"/>
-
        <result column="chatHistoryConf" property="chatHistoryConf"/>
        <result column="systemPrompt" property="systemPrompt"/>
        <result column="summaryMemory" property="summaryMemory"/>
@@ -38,6 +35,13 @@
        <result column="createdAt" property="createdAt"/>
        <result column="updater" property="updater"/>
        <result column="updatedAt" property="updatedAt"/>
+        <collection property="functions"
+                    ofType="xiaozhi.modules.agent.entity.AgentPluginMapping">
+            <id column="functionId" property="id"/>
+            <result column="functionAgentId" property="agentId"/>
+            <result column="pluginId" property="pluginId"/>
+            <result column="paramInfo" property="paramInfo"/>
+        </collection>
    </resultMap>

    <select id="selectAgentInfoById" resultMap="AgentInfoMap">
@@ -58,19 +62,6 @@
               a.tts_pitch         AS ttsPitch,
               a.mem_model_id      AS memModelId,
               a.intent_model_id   AS intentModelId,
-               COALESCE(
-                       (SELECT JSON_ARRAYAGG(
-                                       JSON_OBJECT(
-                                               'id', m.id,
-                                               'agentId', m.agent_id,
-                                               'pluginId', m.plugin_id,
-                                               'paramInfo', m.param_info
-                                       )
-                               )
-                        FROM ai_agent_plugin_mapping m
-                        WHERE m.agent_id = a.id),
-                       JSON_ARRAY()
-               )                   AS functions,
               a.chat_history_conf AS chatHistoryConf,
               a.system_prompt     AS systemPrompt,
               a.summary_memory    AS summaryMemory,
@@ -80,8 +71,50 @@
               a.creator,
               a.created_at        AS createdAt,
               a.updater,
-               a.updated_at        AS updatedAt
+               a.updated_at        AS updatedAt,
+               f.id                AS functionId,
+               f.agent_id          AS functionAgentId,
+               f.plugin_id         AS pluginId,
+               f.param_info        AS paramInfo
        FROM ai_agent a
+        LEFT JOIN ai_agent_plugin_mapping f ON f.agent_id = a.id
        WHERE a.id = #{agentId}
+        ORDER BY f.id ASC
    </select>
+
+    <select id="selectByIdForUpdate" resultType="xiaozhi.modules.agent.entity.AgentEntity">
+        SELECT *
+        FROM ai_agent
+        WHERE id = #{agentId}
+        FOR UPDATE
+    </select>
+
+    <update id="updateSnapshotFields">
+        UPDATE ai_agent
+        SET agent_code = #{agent.agentCode,jdbcType=VARCHAR},
+            agent_name = #{agent.agentName,jdbcType=VARCHAR},
+            asr_model_id = #{agent.asrModelId,jdbcType=VARCHAR},
+            vad_model_id = #{agent.vadModelId,jdbcType=VARCHAR},
+            llm_model_id = #{agent.llmModelId,jdbcType=VARCHAR},
+            slm_model_id = #{agent.slmModelId,jdbcType=VARCHAR},
+            vllm_model_id = #{agent.vllmModelId,jdbcType=VARCHAR},
+            tts_model_id = #{agent.ttsModelId,jdbcType=VARCHAR},
+            tts_voice_id = #{agent.ttsVoiceId,jdbcType=VARCHAR},
+            tts_language = #{agent.ttsLanguage,jdbcType=VARCHAR},
+            tts_volume = #{agent.ttsVolume,jdbcType=INTEGER},
+            tts_rate = #{agent.ttsRate,jdbcType=INTEGER},
+            tts_pitch = #{agent.ttsPitch,jdbcType=INTEGER},
+            mem_model_id = #{agent.memModelId,jdbcType=VARCHAR},
+            intent_model_id = #{agent.intentModelId,jdbcType=VARCHAR},
+            chat_history_conf = #{agent.chatHistoryConf,jdbcType=INTEGER},
+            system_prompt = #{agent.systemPrompt,jdbcType=LONGVARCHAR},
+            summary_memory = #{agent.summaryMemory,jdbcType=LONGVARCHAR},
+            lang_code = #{agent.langCode,jdbcType=VARCHAR},
+            language = #{agent.language,jdbcType=VARCHAR},
+            sort = #{agent.sort,jdbcType=INTEGER},
+            updater = #{agent.updater,jdbcType=BIGINT},
+            updated_at = #{agent.updatedAt,jdbcType=TIMESTAMP}
+        WHERE id = #{agent.id}
+    </update>
+
 </mapper>
@@ -0,0 +1,123 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
+<mapper namespace="xiaozhi.modules.agent.dao.AgentSnapshotDao">
+
+    <select id="selectMaxVersionNo" resultType="java.lang.Integer">
+        SELECT COALESCE(MAX(version_no), 0)
+        FROM ai_agent_snapshot
+        WHERE agent_id = #{agentId}
+    </select>
+
+    <select id="selectLatestSnapshot" resultType="xiaozhi.modules.agent.entity.AgentSnapshotEntity">
+        SELECT id,
+               agent_id       AS agentId,
+               user_id        AS userId,
+               version_no     AS versionNo,
+               snapshot_data  AS snapshotData,
+               changed_fields AS changedFields,
+               source,
+               restore_from_snapshot_id AS restoreFromSnapshotId,
+               restore_from_version_no  AS restoreFromVersionNo,
+               creator,
+               created_at     AS createdAt,
+               redaction_version AS redactionVersion
+        FROM ai_agent_snapshot
+        WHERE agent_id = #{agentId}
+        ORDER BY version_no DESC
+        LIMIT 1
+    </select>
+
+    <select id="selectNextSnapshot" resultType="xiaozhi.modules.agent.entity.AgentSnapshotEntity">
+        SELECT id,
+               agent_id       AS agentId,
+               user_id        AS userId,
+               version_no     AS versionNo,
+               snapshot_data  AS snapshotData,
+               changed_fields AS changedFields,
+               source,
+               restore_from_snapshot_id AS restoreFromSnapshotId,
+               restore_from_version_no  AS restoreFromVersionNo,
+               creator,
+               created_at     AS createdAt,
+               redaction_version AS redactionVersion
+        FROM ai_agent_snapshot
+        WHERE agent_id = #{agentId}
+          AND version_no &gt; #{versionNo}
+        ORDER BY version_no ASC
+        LIMIT 1
+    </select>
+
+    <insert id="insertWithNextVersion">
+        INSERT INTO ai_agent_snapshot (
+            id,
+            agent_id,
+            user_id,
+            version_no,
+            snapshot_data,
+            changed_fields,
+            source,
+            restore_from_snapshot_id,
+            restore_from_version_no,
+            creator,
+            created_at,
+            redaction_version
+        )
+        SELECT #{snapshot.id},
+               #{snapshot.agentId},
+               #{snapshot.userId},
+               COALESCE(MAX(version_no), 0) + 1,
+               #{snapshot.snapshotData},
+               #{snapshot.changedFields},
+               #{snapshot.source},
+               #{snapshot.restoreFromSnapshotId},
+               #{snapshot.restoreFromVersionNo},
+               #{snapshot.creator},
+               #{snapshot.createdAt},
+               #{snapshot.redactionVersion}
+        FROM ai_agent_snapshot
+        WHERE agent_id = #{snapshot.agentId}
+    </insert>
+
+    <delete id="deleteOlderThanKeepLimit">
+        DELETE FROM ai_agent_snapshot
+        WHERE agent_id = #{agentId}
+          AND id NOT IN (
+              SELECT id
+              FROM (
+                  SELECT id
+                  FROM ai_agent_snapshot
+                  WHERE agent_id = #{agentId}
+                  ORDER BY version_no DESC
+                  LIMIT #{keepLimit}
+              ) retained_snapshots
+          )
+    </delete>
+
+    <select id="selectLegacyRedactionBatch" resultType="xiaozhi.modules.agent.entity.AgentSnapshotEntity">
+        SELECT id,
+               snapshot_data AS snapshotData,
+               redaction_version AS redactionVersion
+        FROM ai_agent_snapshot
+        WHERE redaction_version &lt; #{targetRedactionVersion}
+          AND (#{afterId} IS NULL OR id &gt; #{afterId})
+        ORDER BY id ASC
+        LIMIT #{limit}
+    </select>
+
+    <update id="updateRedactedSnapshots">
+        UPDATE ai_agent_snapshot
+        SET snapshot_data = CASE id
+            <foreach collection="snapshots" item="snapshot">
+                WHEN #{snapshot.id} THEN #{snapshot.snapshotData}
+            </foreach>
+            ELSE snapshot_data
+            END,
+            redaction_version = #{redactionVersion}
+        WHERE redaction_version &lt; #{redactionVersion}
+          AND id IN
+          <foreach collection="snapshots" item="snapshot" open="(" separator="," close=")">
+              #{snapshot.id}
+          </foreach>
+    </update>
+
+</mapper>
@@ -25,4 +25,15 @@
        INSERT INTO ai_device_address_book (mac_address, target_mac, alias, has_permission, creator, create_date, updater, update_date)
        VALUES (#{macAddress}, #{targetMac}, #{alias}, #{hasPermission}, #{creator}, NOW(), #{updater}, NOW())
    </insert>
+
+    <delete id="deleteByMacAddresses">
+        DELETE FROM ai_device_address_book WHERE mac_address IN
+        <foreach collection="macAddresses" item="mac" open="(" separator="," close=")">
+            #{mac}
+        </foreach>
+        OR target_mac IN
+        <foreach collection="macAddresses" item="mac" open="(" separator="," close=")">
+            #{mac}
+        </foreach>
+    </delete>
 </mapper>
@@ -0,0 +1,200 @@
+package xiaozhi.common.service.impl;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.CALLS_REAL_METHODS;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.mockStatic;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.when;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+import java.util.function.BiFunction;
+
+import org.apache.ibatis.binding.MapperMethod;
+import org.apache.ibatis.executor.BatchResult;
+import org.apache.ibatis.mapping.MappedStatement;
+import org.apache.ibatis.session.ExecutorType;
+import org.apache.ibatis.session.SqlSession;
+import org.apache.ibatis.session.SqlSessionFactory;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.mockito.MockedStatic;
+import org.springframework.transaction.support.TransactionSynchronizationManager;
+
+import com.baomidou.mybatisplus.core.enums.SqlMethod;
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.baomidou.mybatisplus.core.toolkit.Constants;
+import com.baomidou.mybatisplus.extension.toolkit.SqlHelper;
+
+class BaseServiceImplTest {
+    private static final String INSERT_STATEMENT = TestMapper.class.getName() + ".insert";
+    private static final String UPDATE_STATEMENT = TestMapper.class.getName() + ".updateById";
+
+    private final TestService service = new TestService();
+
+    @AfterEach
+    void clearTransactionSynchronization() {
+        if (TransactionSynchronizationManager.isSynchronizationActive()) {
+            TransactionSynchronizationManager.clearSynchronization();
+        }
+    }
+
+    @Test
+    void insertBatchFlushesAtTheRequestedBatchSizeAndCommitsWithoutATransaction() {
+        SqlSessionFactory sqlSessionFactory = mock(SqlSessionFactory.class);
+        SqlSession sqlSession = mock(SqlSession.class);
+        when(sqlSessionFactory.openSession(ExecutorType.BATCH)).thenReturn(sqlSession);
+        when(sqlSession.insert(eq(INSERT_STATEMENT), any(TestEntity.class))).thenReturn(1);
+        when(sqlSession.flushStatements())
+                .thenReturn(List.of(batchResult(1, 1)), List.of(batchResult(1)));
+
+        TestEntity first = new TestEntity(1L);
+        TestEntity second = new TestEntity(2L);
+        TestEntity third = new TestEntity(3L);
+
+        try (MockedStatic<SqlHelper> sqlHelper = sqlHelperUsing(sqlSessionFactory)) {
+            assertTrue(service.insertBatch(List.of(first, second, third), 2));
+        }
+
+        verify(sqlSession).insert(INSERT_STATEMENT, first);
+        verify(sqlSession).insert(INSERT_STATEMENT, second);
+        verify(sqlSession).insert(INSERT_STATEMENT, third);
+        verify(sqlSession, times(2)).flushStatements();
+        verify(sqlSession).commit(true);
+        verify(sqlSession).close();
+    }
+
+    @Test
+    void updateBatchByIdPassesEachEntityAndReturnsSuccessfulFlushResult() {
+        SqlSessionFactory sqlSessionFactory = mock(SqlSessionFactory.class);
+        SqlSession sqlSession = mock(SqlSession.class);
+        when(sqlSessionFactory.openSession(ExecutorType.BATCH)).thenReturn(sqlSession);
+        when(sqlSession.update(eq(UPDATE_STATEMENT), any())).thenReturn(1);
+        when(sqlSession.flushStatements()).thenReturn(List.of(batchResult(1, 1)));
+
+        TestEntity first = new TestEntity(1L);
+        TestEntity second = new TestEntity(2L);
+
+        try (MockedStatic<SqlHelper> sqlHelper = sqlHelperUsing(sqlSessionFactory)) {
+            assertTrue(service.updateBatchById(List.of(first, second), 10));
+        }
+
+        ArgumentCaptor<Object> params = ArgumentCaptor.forClass(Object.class);
+        verify(sqlSession, times(2)).update(eq(UPDATE_STATEMENT), params.capture());
+        assertSame(first, entityFrom(params.getAllValues().get(0)));
+        assertSame(second, entityFrom(params.getAllValues().get(1)));
+        verify(sqlSession).flushStatements();
+    }
+
+    @Test
+    void batchCallbacksReturnActualAffectedRowCounts() {
+        SqlSession sqlSession = mock(SqlSession.class);
+        when(sqlSession.insert(eq(INSERT_STATEMENT), any(TestEntity.class))).thenReturn(3);
+        when(sqlSession.update(eq(UPDATE_STATEMENT), any())).thenReturn(2);
+        CallbackCapturingTestService capturingService = new CallbackCapturingTestService(sqlSession);
+        TestEntity entity = new TestEntity(1L);
+
+        assertTrue(capturingService.insertBatch(List.of(entity), 7));
+        assertEquals(7, capturingService.batchSize);
+        assertEquals(List.of(3), capturingService.affectedRows);
+
+        assertTrue(capturingService.updateBatchById(List.of(entity), 9));
+        assertEquals(9, capturingService.batchSize);
+        assertEquals(List.of(2), capturingService.affectedRows);
+    }
+
+    @Test
+    void emptyBatchesReturnFalseWithoutOpeningABatchSession() {
+        SqlSessionFactory sqlSessionFactory = mock(SqlSessionFactory.class);
+
+        try (MockedStatic<SqlHelper> sqlHelper = sqlHelperUsing(sqlSessionFactory)) {
+            assertFalse(service.insertBatch(List.of(), 10));
+            assertFalse(service.updateBatchById(List.of(), 10));
+        }
+
+        verifyNoInteractions(sqlSessionFactory);
+    }
+
+    @Test
+    void activeTransactionSynchronizationUsesTransactionAwareCommitAndLifecycle() {
+        SqlSessionFactory sqlSessionFactory = mock(SqlSessionFactory.class);
+        SqlSession sqlSession = mock(SqlSession.class);
+        when(sqlSessionFactory.openSession(ExecutorType.BATCH)).thenReturn(sqlSession);
+        when(sqlSession.insert(eq(INSERT_STATEMENT), any(TestEntity.class))).thenReturn(1);
+        when(sqlSession.flushStatements()).thenReturn(List.of(batchResult(1)));
+        TransactionSynchronizationManager.initSynchronization();
+
+        try (MockedStatic<SqlHelper> sqlHelper = sqlHelperUsing(sqlSessionFactory)) {
+            assertTrue(service.insertBatch(List.of(new TestEntity(1L)), 1));
+        }
+
+        verify(sqlSession).flushStatements();
+        verify(sqlSession).commit(false);
+        verify(sqlSession, never()).commit(true);
+        verify(sqlSession, never()).close();
+    }
+
+    @SuppressWarnings("deprecation")
+    private static MockedStatic<SqlHelper> sqlHelperUsing(SqlSessionFactory sqlSessionFactory) {
+        MockedStatic<SqlHelper> sqlHelper = mockStatic(SqlHelper.class, CALLS_REAL_METHODS);
+        sqlHelper.when(() -> SqlHelper.sqlSessionFactory(TestEntity.class)).thenReturn(sqlSessionFactory);
+        return sqlHelper;
+    }
+
+    private static BatchResult batchResult(int... updateCounts) {
+        BatchResult result = new BatchResult(mock(MappedStatement.class), "batch");
+        result.setUpdateCounts(updateCounts);
+        return result;
+    }
+
+    private static Object entityFrom(Object parameter) {
+        assertTrue(parameter instanceof MapperMethod.ParamMap<?>);
+        return ((Map<?, ?>) parameter).get(Constants.ENTITY);
+    }
+
+    private interface TestMapper extends BaseMapper<TestEntity> {
+    }
+
+    private record TestEntity(Long id) {
+    }
+
+    private static class TestService extends BaseServiceImpl<TestMapper, TestEntity> {
+        @Override
+        protected String getSqlStatement(SqlMethod sqlMethod) {
+            return switch (sqlMethod) {
+                case INSERT_ONE -> INSERT_STATEMENT;
+                case UPDATE_BY_ID -> UPDATE_STATEMENT;
+                default -> throw new IllegalArgumentException("Unexpected SQL method: " + sqlMethod);
+            };
+        }
+    }
+
+    private static class CallbackCapturingTestService extends TestService {
+        private final SqlSession sqlSession;
+        private int batchSize;
+        private List<Integer> affectedRows;
+
+        private CallbackCapturingTestService(SqlSession sqlSession) {
+            this.sqlSession = sqlSession;
+        }
+
+        @Override
+        protected <E> boolean executeBatch(Collection<E> list, int batchSize,
+                BiFunction<SqlSession, E, Integer> operation) {
+            this.batchSize = batchSize;
+            this.affectedRows = list.stream().map(entity -> operation.apply(sqlSession, entity)).toList();
+            return true;
+        }
+    }
+}
@@ -0,0 +1,44 @@
+package xiaozhi.modules.agent.dto;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+import org.junit.jupiter.api.Test;
+
+class AgentUpdateDTOTest {
+
+    @Test
+    void functionInfoAcceptsJsonStringParamInfo() {
+        AgentUpdateDTO.FunctionInfo info = new AgentUpdateDTO.FunctionInfo();
+
+        info.setParamInfo("{\"api_key\":\"abc\",\"max_results\":5}");
+
+        assertEquals("abc", info.getParamInfo().get("api_key"));
+        assertEquals(5, info.getParamInfo().get("max_results"));
+    }
+
+    @Test
+    void functionInfoNormalizesMapKeysToStrings() {
+        AgentUpdateDTO.FunctionInfo info = new AgentUpdateDTO.FunctionInfo();
+        Map<Object, Object> params = new LinkedHashMap<>();
+        params.put("api_key", "abc");
+        params.put(42, true);
+
+        info.setParamInfo(params);
+
+        assertEquals("abc", info.getParamInfo().get("api_key"));
+        assertEquals(true, info.getParamInfo().get("42"));
+    }
+
+    @Test
+    void functionInfoFallsBackToEmptyMapForBlankParamInfo() {
+        AgentUpdateDTO.FunctionInfo info = new AgentUpdateDTO.FunctionInfo();
+
+        info.setParamInfo(" ");
+
+        assertTrue(info.getParamInfo().isEmpty());
+    }
+}
@@ -0,0 +1,77 @@
+package xiaozhi.modules.agent.service.impl;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import java.lang.reflect.Method;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.springframework.beans.factory.SmartInitializingSingleton;
+import org.springframework.boot.test.system.CapturedOutput;
+import org.springframework.boot.test.system.OutputCaptureExtension;
+import org.springframework.scheduling.annotation.Scheduled;
+
+import xiaozhi.modules.agent.service.AgentSnapshotService;
+
+@ExtendWith(OutputCaptureExtension.class)
+class AgentSnapshotRedactionRunnerTest {
+
+    @Test
+    void startupRedactionRunsSynchronouslyAndReportsCompensationWindow(CapturedOutput output) {
+        assertTrue(SmartInitializingSingleton.class.isAssignableFrom(AgentSnapshotRedactionRunner.class));
+        AgentSnapshotService service = mock(AgentSnapshotService.class);
+        AgentSnapshotRedactionRunner runner = new AgentSnapshotRedactionRunner(service);
+        when(service.redactLegacySnapshots()).thenReturn(0L);
+
+        runner.afterSingletonsInstantiated();
+
+        verify(service).redactLegacySnapshots();
+        assertTrue(output.getAll().contains("startup pass completed"));
+        assertTrue(output.getAll().contains("starts after 5000 ms and repeats every 15000 ms"));
+    }
+
+    @Test
+    void startupRedactionFailureIsLoggedAndPropagatedToKeepStartupFailClosed(CapturedOutput output) {
+        AgentSnapshotService service = mock(AgentSnapshotService.class);
+        AgentSnapshotRedactionRunner runner = new AgentSnapshotRedactionRunner(service);
+        IllegalStateException failure = new IllegalStateException("database unavailable");
+        when(service.redactLegacySnapshots()).thenThrow(failure);
+
+        IllegalStateException thrown = assertThrows(IllegalStateException.class,
+                runner::afterSingletonsInstantiated);
+
+        assertSame(failure, thrown);
+        assertTrue(output.getAll().contains("blocking application startup before it can accept traffic"));
+    }
+
+    @Test
+    void rollingDeploymentRedactionReportsTriggerCountAndCredentialRotation(CapturedOutput output) {
+        AgentSnapshotService service = mock(AgentSnapshotService.class);
+        AgentSnapshotRedactionRunner runner = new AgentSnapshotRedactionRunner(service);
+        when(service.redactLegacySnapshots()).thenReturn(3L);
+
+        runner.redactLateRollingDeploymentWrites();
+
+        assertTrue(output.getAll().contains("trigger=rolling-deployment migrated=3"));
+        assertTrue(output.getAll().contains("Rotate credentials"));
+    }
+
+    @Test
+    void rollingDeploymentScheduleKeepsLegacyWriteExposureWindowShort() throws Exception {
+        Method method = AgentSnapshotRedactionRunner.class.getMethod("redactLateRollingDeploymentWrites");
+        Scheduled scheduled = method.getAnnotation(Scheduled.class);
+
+        assertNotNull(scheduled);
+        assertEquals(5_000, scheduled.initialDelay());
+        assertEquals(15_000, scheduled.fixedDelay());
+        assertTrue(scheduled.initialDelay() <= 10_000);
+        assertTrue(scheduled.fixedDelay() <= 30_000);
+    }
+}
@@ -0,0 +1,73 @@
+package xiaozhi.modules.agent.typehandler;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import java.util.List;
+
+import org.apache.ibatis.type.TypeHandler;
+import org.apache.ibatis.type.TypeHandlerRegistry;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+
+import xiaozhi.common.utils.JsonUtils;
+import xiaozhi.modules.agent.dto.ContextProviderDTO;
+
+class ContextProviderListTypeHandlerTest {
+
+    private final ContextProviderListTypeHandler handler = new ContextProviderListTypeHandler();
+
+    @Test
+    void myBatisCanInstantiateHandlerForListField() {
+        TypeHandler<?> typeHandler = new TypeHandlerRegistry().getInstance(List.class,
+                ContextProviderListTypeHandler.class);
+
+        assertInstanceOf(ContextProviderListTypeHandler.class, typeHandler);
+    }
+
+    @Test
+    void resultSetDeserializationKeepsContextProviderDtoElementType() throws Exception {
+        ResultSet resultSet = mock(ResultSet.class);
+        when(resultSet.getString("context_providers"))
+                .thenReturn("[{\"url\":\"https://example.com/context\",\"headers\":{\"Authorization\":\"Bearer token\"}}]");
+
+        List<ContextProviderDTO> providers = handler.getNullableResult(resultSet, "context_providers");
+
+        assertEquals(1, providers.size());
+        assertInstanceOf(ContextProviderDTO.class, providers.get(0));
+        assertEquals("https://example.com/context", providers.get(0).getUrl());
+        assertEquals("Bearer token", providers.get(0).getHeaders().get("Authorization"));
+    }
+
+    @Test
+    void sqlNullRemainsNull() throws Exception {
+        ResultSet resultSet = mock(ResultSet.class);
+
+        assertNull(handler.getNullableResult(resultSet, 1));
+    }
+
+    @Test
+    void serializesProviderListAsJson() throws Exception {
+        ContextProviderDTO provider = new ContextProviderDTO();
+        provider.setUrl("https://example.com/context");
+        PreparedStatement statement = mock(PreparedStatement.class);
+
+        handler.setNonNullParameter(statement, 1, List.of(provider), null);
+
+        ArgumentCaptor<String> json = ArgumentCaptor.forClass(String.class);
+        verify(statement).setString(eq(1), json.capture());
+        List<ContextProviderDTO> serialized = JsonUtils.parseObject(json.getValue(), new TypeReference<>() {
+        });
+        assertEquals(1, serialized.size());
+        assertEquals("https://example.com/context", serialized.get(0).getUrl());
+    }
+}
@@ -0,0 +1,87 @@
+package xiaozhi.modules.device.service.impl;
+
+import static org.junit.jupiter.api.Assertions.assertAll;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.time.Instant;
+import java.time.ZoneId;
+import java.util.Date;
+import java.util.List;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import xiaozhi.modules.device.entity.DeviceEntity;
+import xiaozhi.modules.device.vo.UserShowDeviceListVO;
+import xiaozhi.modules.security.config.WebMvcConfig;
+
+@DisplayName("设备时间序列化回归测试")
+class DeviceTimeSerializationTest {
+
+    @ParameterizedTest(name = "浏览器时区 {0}")
+    @ValueSource(strings = { "Asia/Shanghai", "America/Sao_Paulo" })
+    @DisplayName("#3280 绑定时间和最后连接时间在任意浏览器时区都表示同一时刻")
+    void serializedDeviceTimesDescribeTheSameInstantAcrossBrowserTimeZones(String browserTimeZone) {
+        Instant connectedAt = Instant.parse("2026-07-10T13:21:42Z");
+        DeviceEntity entity = new DeviceEntity();
+        entity.setCreateDate(Date.from(connectedAt));
+        entity.setLastConnectedAt(Date.from(connectedAt));
+
+        DeviceServiceImpl deviceService = serviceReturning(entity);
+        UserShowDeviceListVO device = deviceService.getUserDeviceList(1L, "agent-id").getFirst();
+
+        ObjectMapper objectMapper = new WebMvcConfig().jackson2HttpMessageConverter().getObjectMapper();
+        JsonNode payload = objectMapper.valueToTree(device);
+        Instant createDate = Instant.ofEpochMilli(
+                Long.parseLong(payload.path("createDateTimestamp").asText()));
+        Instant lastConnectedAt = Instant.ofEpochMilli(
+                Long.parseLong(payload.path("lastConnectedAtTimestamp").asText()));
+        ZoneId browserZone = ZoneId.of(browserTimeZone);
+
+        assertAll(
+                () -> assertTrue(payload.path("createDateTimestamp").isTextual(),
+                        "Long 时间戳必须遵循现有 JSON 契约序列化为字符串"),
+                () -> assertTrue(payload.path("lastConnectedAtTimestamp").isTextual(),
+                        "Long 时间戳必须遵循现有 JSON 契约序列化为字符串"),
+                () -> assertEquals(connectedAt, createDate,
+                        "createDateTimestamp 必须保留源时间点"),
+                () -> assertEquals(connectedAt, lastConnectedAt,
+                        "lastConnectedAtTimestamp 必须保留源时间点"),
+                () -> assertEquals(lastConnectedAt.atZone(browserZone).toLocalDateTime(),
+                        createDate.atZone(browserZone).toLocalDateTime(),
+                        "绑定时间和最后连接时间在同一浏览器中必须显示为相同的本地时间"),
+                () -> assertTrue(payload.path("createDate").isTextual(),
+                        "兼容字段 createDate 必须继续保留"));
+    }
+
+    @Test
+    @DisplayName("时间为空时新旧字段均保持 null")
+    void nullDeviceTimesRemainNull() {
+        DeviceEntity entity = new DeviceEntity();
+        DeviceServiceImpl deviceService = serviceReturning(entity);
+
+        UserShowDeviceListVO device = deviceService.getUserDeviceList(1L, "agent-id").getFirst();
+        ObjectMapper objectMapper = new WebMvcConfig().jackson2HttpMessageConverter().getObjectMapper();
+        JsonNode payload = objectMapper.valueToTree(device);
+
+        assertAll(
+                () -> assertTrue(payload.path("createDateTimestamp").isNull()),
+                () -> assertTrue(payload.path("lastConnectedAtTimestamp").isNull()),
+                () -> assertTrue(payload.path("createDate").isNull()));
+    }
+
+    private DeviceServiceImpl serviceReturning(DeviceEntity entity) {
+        return new DeviceServiceImpl(null, null, null, null, null, null) {
+            @Override
+            public List<DeviceEntity> getUserDevices(Long userId, String agentId) {
+                return List.of(entity);
+            }
+        };
+    }
+}
@@ -0,0 +1,180 @@
+package xiaozhi.modules.device.service.impl;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.io.IOException;
+import java.net.InetSocketAddress;
+import java.nio.charset.StandardCharsets;
+import java.time.Instant;
+import java.time.ZoneId;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.stream.Stream;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+import org.junit.jupiter.params.provider.NullAndEmptySource;
+import org.junit.jupiter.params.provider.ValueSource;
+
+import com.sun.net.httpserver.HttpExchange;
+import com.sun.net.httpserver.HttpHandler;
+import com.sun.net.httpserver.HttpServer;
+
+import cn.hutool.crypto.digest.DigestUtil;
+
+@DisplayName("MQTT Gateway 日期鉴权回归测试")
+class MqttGatewayAuthorizationTest {
+
+    private static final String SIGNATURE_KEY = "test-signature-key";
+    private static final Instant FIXED_INSTANT = Instant.parse("2026-07-14T00:30:00Z");
+
+    private HttpServer server;
+
+    @AfterEach
+    void stopServer() {
+        if (server != null) {
+            server.stop(0);
+        }
+    }
+
+    @Test
+    @DisplayName("以 UTC 日期生成当天、前一天和后一天三个候选 token")
+    void generatesUtcDateCandidates() {
+        List<String> tokens = MqttGatewayAuthorization.generateDailyTokens(SIGNATURE_KEY, FIXED_INSTANT);
+
+        assertEquals(List.of(
+                tokenFor("2026-07-14"),
+                tokenFor("2026-07-13"),
+                tokenFor("2026-07-15")), tokens);
+    }
+
+    @ParameterizedTest(name = "Gateway 时区 {0}")
+    @MethodSource("gatewayTimeZones")
+    @DisplayName("候选 token 覆盖上海和圣保罗 Gateway 的本地日期")
+    void coversGatewayLocalDate(String gatewayTimeZone, Instant now, int expectedTokenIndex) {
+        String gatewayDate = now.atZone(ZoneId.of(gatewayTimeZone)).toLocalDate().toString();
+        List<String> tokens = MqttGatewayAuthorization.generateDailyTokens(SIGNATURE_KEY, now);
+
+        assertEquals(tokenFor(gatewayDate), tokens.get(expectedTokenIndex));
+    }
+
+    @Test
+    @DisplayName("仅在 401 时按日期候选重试并保留请求体")
+    void retriesOnlyAuthenticationFailures() throws IOException {
+        AtomicInteger requestCount = new AtomicInteger();
+        List<String> authorizationHeaders = new ArrayList<>();
+        List<String> requestBodies = new ArrayList<>();
+        List<String> expectedTokens = MqttGatewayAuthorization.generateDailyTokens(SIGNATURE_KEY, FIXED_INSTANT);
+        startServer(exchange -> {
+            int attempt = requestCount.getAndIncrement();
+            authorizationHeaders.add(exchange.getRequestHeaders().getFirst("Authorization"));
+            requestBodies.add(new String(exchange.getRequestBody().readAllBytes(), StandardCharsets.UTF_8));
+            if (attempt == 0) {
+                respond(exchange, 401, "{\"error\":\"unauthorized\"}");
+            } else if (attempt == 1) {
+                respond(exchange, 401, "{\"error\":\"unauthorized\"}");
+            } else {
+                respond(exchange, 200, "{\"online\":true}");
+            }
+        });
+
+        String requestBody = "{\"clientIds\":[\"device-id\"]}";
+        String response = MqttGatewayAuthorization.postJson(
+                serverUrl(), requestBody, SIGNATURE_KEY, FIXED_INSTANT);
+
+        assertEquals("{\"online\":true}", response);
+        assertEquals(3, requestCount.get());
+        assertEquals(expectedTokens.stream().map(token -> "Bearer " + token).toList(), authorizationHeaders);
+        assertEquals(List.of(requestBody, requestBody, requestBody), requestBodies);
+    }
+
+    @ParameterizedTest(name = "HTTP {0}")
+    @ValueSource(ints = { 403, 500 })
+    @DisplayName("非 401 错误不重试且向上抛出")
+    void doesNotRetryNonAuthenticationFailure(int statusCode) throws IOException {
+        AtomicInteger requestCount = new AtomicInteger();
+        startServer(exchange -> {
+            requestCount.incrementAndGet();
+            exchange.getRequestBody().readAllBytes();
+            respond(exchange, statusCode, "{\"error\":\"request rejected\"}");
+        });
+
+        MqttGatewayAuthorization.GatewayRequestException exception = assertThrows(
+                MqttGatewayAuthorization.GatewayRequestException.class,
+                () -> MqttGatewayAuthorization.postJson(
+                        serverUrl(), "{}", SIGNATURE_KEY, FIXED_INSTANT));
+
+        assertEquals(statusCode, exception.statusCode());
+        assertEquals(1, requestCount.get());
+    }
+
+    @Test
+    @DisplayName("所有日期候选被拒绝时不把错误响应当作设备离线数据")
+    void propagatesAuthenticationFailureAfterAllCandidatesAreRejected() throws IOException {
+        AtomicInteger requestCount = new AtomicInteger();
+        startServer(exchange -> {
+            requestCount.incrementAndGet();
+            exchange.getRequestBody().readAllBytes();
+            respond(exchange, 401, "{\"error\":\"unauthorized\"}");
+        });
+
+        MqttGatewayAuthorization.GatewayRequestException exception = assertThrows(
+                MqttGatewayAuthorization.GatewayRequestException.class,
+                () -> MqttGatewayAuthorization.postJson(
+                        serverUrl(), "{}", SIGNATURE_KEY, FIXED_INSTANT));
+
+        assertEquals(401, exception.statusCode());
+        assertEquals(3, requestCount.get());
+    }
+
+    @ParameterizedTest(name = "密钥值 [{0}]")
+    @NullAndEmptySource
+    @ValueSource(strings = { " ", "null", " NULL " })
+    @DisplayName("缺少或占位签名密钥时在发起 HTTP 请求前失败")
+    void rejectsMissingSignatureKeyBeforeSendingRequest(String signatureKey) {
+        MqttGatewayAuthorization.GatewayRequestException exception = assertThrows(
+                MqttGatewayAuthorization.GatewayRequestException.class,
+                () -> MqttGatewayAuthorization.postJson(
+                        "http://127.0.0.1:1", "{}", signatureKey, FIXED_INSTANT));
+
+        assertNull(exception.statusCode());
+    }
+
+    private static Stream<Arguments> gatewayTimeZones() {
+        return Stream.of(
+                Arguments.of("Asia/Shanghai", Instant.parse("2026-07-13T17:30:00Z"), 2),
+                Arguments.of("America/Sao_Paulo", Instant.parse("2026-07-14T00:30:00Z"), 1));
+    }
+
+    private void startServer(HttpHandler handler) throws IOException {
+        server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
+        server.createContext("/mqtt", handler);
+        server.start();
+    }
+
+    private String serverUrl() {
+        assertTrue(server != null, "test server must be started");
+        return "http://127.0.0.1:" + server.getAddress().getPort() + "/mqtt";
+    }
+
+    private static void respond(HttpExchange exchange, int statusCode, String body) throws IOException {
+        byte[] bytes = body.getBytes(StandardCharsets.UTF_8);
+        exchange.getResponseHeaders().set("Content-Type", "application/json");
+        exchange.sendResponseHeaders(statusCode, bytes.length);
+        try (var output = exchange.getResponseBody()) {
+            output.write(bytes);
+        }
+    }
+
+    private static String tokenFor(String date) {
+        return DigestUtil.sha256Hex(date + SIGNATURE_KEY);
+    }
+}
@@ -0,0 +1,57 @@
+package xiaozhi.modules.timbre.service.impl;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import org.junit.jupiter.api.Test;
+
+import xiaozhi.common.redis.RedisUtils;
+import xiaozhi.modules.timbre.dao.TimbreDao;
+import xiaozhi.modules.timbre.entity.TimbreEntity;
+import xiaozhi.modules.voiceclone.dao.VoiceCloneDao;
+import xiaozhi.modules.voiceclone.entity.VoiceCloneEntity;
+
+class TimbreServiceImplTest {
+
+    @Test
+    void defaultLanguageUsesFirstValidRegularTimbreLanguageWithoutCloneQuery() {
+        TimbreDao timbreDao = mock(TimbreDao.class);
+        VoiceCloneDao voiceCloneDao = mock(VoiceCloneDao.class);
+        TimbreServiceImpl service = new TimbreServiceImpl(timbreDao, voiceCloneDao, mock(RedisUtils.class));
+        TimbreEntity timbre = new TimbreEntity();
+        timbre.setLanguages("，， ; 普通话；粤语");
+        when(timbreDao.selectById("voice-id")).thenReturn(timbre);
+
+        assertEquals("普通话", service.getDefaultLanguageById("voice-id"));
+
+        verify(voiceCloneDao, never()).selectById("voice-id");
+    }
+
+    @Test
+    void defaultLanguageFallsBackToCloneTimbre() {
+        TimbreDao timbreDao = mock(TimbreDao.class);
+        VoiceCloneDao voiceCloneDao = mock(VoiceCloneDao.class);
+        TimbreServiceImpl service = new TimbreServiceImpl(timbreDao, voiceCloneDao, mock(RedisUtils.class));
+        VoiceCloneEntity voiceClone = new VoiceCloneEntity();
+        voiceClone.setLanguages("、, English，中文");
+        when(voiceCloneDao.selectById("clone-id")).thenReturn(voiceClone);
+
+        assertEquals("English", service.getDefaultLanguageById("clone-id"));
+    }
+
+    @Test
+    void delimiterOnlyLanguageConfigurationReturnsNull() {
+        TimbreDao timbreDao = mock(TimbreDao.class);
+        VoiceCloneDao voiceCloneDao = mock(VoiceCloneDao.class);
+        TimbreServiceImpl service = new TimbreServiceImpl(timbreDao, voiceCloneDao, mock(RedisUtils.class));
+        TimbreEntity timbre = new TimbreEntity();
+        timbre.setLanguages(",，、；;;,,");
+        when(timbreDao.selectById("voice-id")).thenReturn(timbre);
+
+        assertNull(service.getDefaultLanguageById("voice-id"));
+    }
+}
@@ -69,6 +69,7 @@
    "build:quickapp-webview-huawei": "uni build -p quickapp-webview-huawei",
    "build:quickapp-webview-union": "uni build -p quickapp-webview-union",
    "type-check": "vue-tsc --noEmit",
+    "test:snapshot": "node --test src/pages/agent/components/agentSnapshotUtils.test.mjs src/pages/agent/components/agentSnapshotContracts.test.mjs",
    "openapi-ts-request": "openapi-ts",
    "prepare": "git init && husky",
    "lint": "eslint",
@@ -91,6 +91,9 @@ importers:
      pinia-plugin-persistedstate:
        specifier: 3.2.1
        version: 3.2.1(pinia@2.0.36(typescript@5.7.2)(vue@3.5.15(typescript@5.7.2)))
+      sm-crypto:
+        specifier: ^0.3.13
+        version: 0.3.14
      vue:
        specifier: ^3.4.21
        version: 3.5.15(typescript@5.7.2)
@@ -4719,6 +4722,9 @@ packages:
    resolution: {integrity: sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==}
    hasBin: true

+  jsbn@1.1.0:
+    resolution: {integrity: sha512-4bYVV3aAMtDTTu4+xsDYa6sy9GyJ69/amsu9sYF2zqjiEoZA5xJi3BrfX3uY+/IekIu7MwdObdbDWpoZdBv3/A==}
+
  jsdoc-type-pratt-parser@4.1.0:
    resolution: {integrity: sha512-Hicd6JK5Njt2QB6XYFS7ok9e37O8AYk3jTcppG4YVQnYjOemymvTcmc7OWsmq/Qqj5TdRFO5/x/tIPmBeRtGHg==}
    engines: {node: '>=12.0.0'}
@@ -6020,6 +6026,9 @@ packages:
    resolution: {integrity: sha512-bSiSngZ/jWeX93BqeIAbImyTbEihizcwNjFoRUIY/T1wWQsfsm2Vw1agPKylXvQTU7iASGdHhyqRlqQzfz+Htg==}
    engines: {node: '>=18'}

+  sm-crypto@0.3.14:
+    resolution: {integrity: sha512-sR7NuGAJH93Om8keAF2/rj1EqFzEiUey4aKGyDo3nQ2BiVqhgq8UkiIoIp5qhV9w4pG7qArhfqyewcG8AbhXbg==}
+
  source-map-js@1.2.1:
    resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
    engines: {node: '>=0.10.0'}
@@ -12652,6 +12661,8 @@ snapshots:
    dependencies:
      argparse: 2.0.1

+  jsbn@1.1.0: {}
+
  jsdoc-type-pratt-parser@4.1.0: {}

  jsdom@16.7.0:
@@ -14145,6 +14156,10 @@ snapshots:
      ansi-styles: 6.2.1
      is-fullwidth-code-point: 5.0.0

+  sm-crypto@0.3.14:
+    dependencies:
+      jsbn: 1.1.0
+
  source-map-js@1.2.1: {}

  source-map-support@0.5.21:
@@ -1,9 +1,9 @@
 <script setup lang="ts">
 import { onHide, onLaunch, onShow } from '@dcloudio/uni-app'
-import { watch, onMounted } from 'vue'
+import { onMounted, watch } from 'vue'
 import { usePageAuth } from '@/hooks/usePageAuth'
-import { useConfigStore } from '@/store'
 import { t } from '@/i18n'
+import { useConfigStore } from '@/store'
 import { useLangStore } from '@/store/lang'
 import 'abortcontroller-polyfill/dist/abortcontroller-polyfill-only'

@@ -37,7 +37,7 @@ function updateTabBarText() {
      success: () => {},
      fail: (err) => {
        console.log('设置首页tabBar文本失败:', err)
-      }
+      },
    })

    // 设置配网tabBar文本
@@ -47,7 +47,7 @@ function updateTabBarText() {
      success: () => {},
      fail: (err) => {
        console.log('设置配网tabBar文本失败:', err)
-      }
+      },
    })

    // 设置系统tabBar文本
@@ -57,9 +57,10 @@ function updateTabBarText() {
      success: () => {},
      fail: (err) => {
        console.log('设置系统tabBar文本失败:', err)
-      }
+      },
    })
-  } catch (error) {
+  }
+  catch (error) {
    console.log('更新tabBar文本时出错:', error)
  }
 }
@@ -2,7 +2,11 @@ import type {
  Agent,
  AgentCreateData,
  AgentDetail,
+  AgentSnapshot,
+  AgentSnapshotPageParams,
+  CorrectWordFile,
  ModelOption,
+  PageData,
  RoleTemplate,
 } from './types'
 import { http } from '@/http/request/alova'
@@ -100,7 +104,7 @@ export function getTTSVoices(ttsModelId: string, voiceName: string = '') {
 }

 // 更新智能体
-export function updateAgent(id: string, data: Partial<AgentDetail>) {
+export function updateAgent(id: string, data: Partial<AgentDetail> & { tagNames?: string[] }) {
  return http.Put(`/agent/${id}`, data, {
    meta: {
      ignoreAuth: false,
@@ -220,3 +224,63 @@ export function getAllLanguage(modelId: string) {
    },
  })
 }
+
+// 获取智能体历史版本列表
+export function getAgentSnapshots(agentId: string, params: AgentSnapshotPageParams) {
+  return http.Get<PageData<AgentSnapshot>>(`/agent/${agentId}/snapshots`, {
+    params,
+    meta: {
+      ignoreAuth: false,
+      toast: false,
+    },
+    cacheFor: {
+      expire: 0,
+    },
+  })
+}
+
+// 获取智能体历史版本详情
+export function getAgentSnapshot(agentId: string, snapshotId: string) {
+  return http.Get<AgentSnapshot>(`/agent/${agentId}/snapshots/${snapshotId}`, {
+    meta: {
+      ignoreAuth: false,
+      toast: false,
+    },
+    cacheFor: {
+      expire: 0,
+    },
+  })
+}
+
+// 恢复智能体历史版本
+export function restoreAgentSnapshot(agentId: string, snapshotId: string, currentStateToken: string) {
+  return http.Post(`/agent/${agentId}/snapshots/${snapshotId}/restore`, { currentStateToken }, {
+    meta: {
+      ignoreAuth: false,
+      toast: false,
+    },
+  })
+}
+
+// 删除智能体历史版本
+export function deleteAgentSnapshot(agentId: string, snapshotId: string) {
+  return http.Delete(`/agent/${agentId}/snapshots/${snapshotId}`, {
+    meta: {
+      ignoreAuth: false,
+      toast: false,
+    },
+  })
+}
+
+// 获取所有替换词文件
+export function getCorrectWordFiles() {
+  return http.Get<CorrectWordFile[]>('/correct-word/file/select', {
+    meta: {
+      ignoreAuth: false,
+      toast: false,
+    },
+    cacheFor: {
+      expire: 0,
+    },
+  })
+}
@@ -44,10 +44,12 @@ export interface AgentDetail {
  createdAt: string
  updater: string
  updatedAt: string
-  ttsLanguage: string
-  ttsVolume: number
-  ttsRate: number
-  ttsPitch: number
+  ttsLanguage: string | null
+  ttsVolume: number | null
+  ttsRate: number | null
+  ttsPitch: number | null
+  currentVersionNo?: number | null
+  tagNames?: string[]
  functions: AgentFunction[]
  contextProviders: Providers[]
 }
@@ -67,6 +69,51 @@ export interface AgentFunction {
  paramInfo: Record<string, string | number | boolean> | null
 }

+export interface PageData<T> {
+  list: T[]
+  total: number
+}
+
+export interface AgentSnapshotData extends Partial<AgentDetail> {
+  correctWordFileIds?: string[]
+  tagNames?: string[]
+  tags?: Array<{
+    tagName?: string
+    [key: string]: any
+  }>
+  [key: string]: any
+}
+
+export interface AgentSnapshot {
+  id: string
+  agentId: string
+  userId?: string
+  versionNo: number
+  changedFields?: string[]
+  fieldOrder?: string[]
+  source?: string
+  restoreFromSnapshotId?: string | null
+  restoreFromVersionNo?: number | null
+  currentStateToken?: string
+  currentSnapshotData?: AgentSnapshotData
+  creator?: string
+  createdAt?: string
+  snapshotData?: AgentSnapshotData
+  afterSnapshotData?: AgentSnapshotData
+}
+
+export interface AgentSnapshotPageParams {
+  page?: number
+  limit?: number
+  maxVersionNo?: number
+}
+
+export interface CorrectWordFile {
+  id: string
+  fileName: string
+  wordCount?: number
+}
+
 // 角色模板数据类型
 export interface RoleTemplate {
  id: string
@@ -78,6 +125,7 @@ export interface RoleTemplate {
  vllmModelId: string
  ttsModelId: string
  ttsVoiceId: string
+  ttsLanguage?: string | null
  memModelId: string
  intentModelId: string
  chatHistoryConf: number
@@ -71,6 +71,13 @@ export default {
  'home.inputPlaceholder': 'z.B. Kundenservice-Assistent, Sprachassistent, Wissens-F&A',
  'home.createError': 'Der Name muss zwischen 1 und 64 Zeichen lang sein.',
  'home.createNow': 'Jetzt erstellen',
+  'home.deleteConfirmTitle': 'Agent löschen',
+  'home.confirmDeleteAgent': 'Das Löschen kann nicht rückgängig gemacht werden. Geben Sie den Agentennamen "{agentName}" ein, um zu bestätigen.',
+  'home.deleteAgentNamePlaceholder': 'Agentennamen eingeben',
+  'home.deleteAgentNameMismatch': 'Der Agentenname stimmt nicht überein',
+  'home.deleteAgentPasteForbidden': 'Bitte geben Sie den Agentennamen manuell ein. Einfügen ist nicht erlaubt.',
+  'home.deleteAgentMissingInfo': 'Agenteninformationen konnten nicht bestätigt werden. Bitte aktualisieren und erneut versuchen.',
+  'home.deleteAgentSuccess': 'Agent erfolgreich gelöscht',
  'home.justNow': 'Gerade eben',
  'home.minutesAgo': 'Minuten her',
  'home.hoursAgo': 'Stunden her',
@@ -123,6 +130,7 @@ export default {
  'agent.saving': 'Wird gespeichert...',
  'agent.saveSuccess': 'Erfolgreich gespeichert',
  'agent.saveFail': 'Speichern fehlgeschlagen',
+  'agent.ttsOptionsLoadFailed': 'Die Sprachoptionen konnten nicht geladen werden. Die vorherigen Einstellungen wurden beibehalten.',
  'agent.loadFail': 'Laden fehlgeschlagen',
  'agent.pleaseInputAgentName': 'Bitte Agenten-Namen eingeben',
  'agent.pleaseInputRoleDescription': 'Bitte Rollenbeschreibung eingeben',
@@ -139,6 +147,92 @@ export default {
  'agent.speedHint': '-100=langsamst, 0=Standard, 100=schnellst',
  'agent.pitchHint': '-100=tiefst, 0=Standard, 100=höchst',

+  // Agent-Versionsverlauf
+  'agentSnapshot.title': 'Versionsverlauf',
+  'agentSnapshot.empty': 'Noch keine Versionen',
+  'agentSnapshot.emptyTip': 'Gespeicherte Konfigurationen erscheinen hier',
+  'agentSnapshot.version': 'Version',
+  'agentSnapshot.createdAt': 'Gespeichert am',
+  'agentSnapshot.source': 'Quelle',
+  'agentSnapshot.changedFields': 'Änderungen',
+  'agentSnapshot.view': 'Ansehen',
+  'agentSnapshot.restore': 'Wiederherstellen',
+  'agentSnapshot.delete': 'Löschen',
+  'agentSnapshot.loadMore': 'Mehr laden',
+  'agentSnapshot.detailTitle': 'Änderungsdetails',
+  'agentSnapshot.restorePreviewTitle': 'Wiederherstellungsvorschau',
+  'agentSnapshot.confirmRestore': 'Wiederherstellung bestätigen',
+  'agentSnapshot.currentVersion': 'Neuester Snapshot',
+  'agentSnapshot.beforeChange': 'Vorher',
+  'agentSnapshot.afterChange': 'Nachher',
+  'agentSnapshot.beforeRestore': 'Vor der Wiederherstellung',
+  'agentSnapshot.afterRestore': 'Nach der Wiederherstellung',
+  'agentSnapshot.configValue': 'Konfigurationswert',
+  'agentSnapshot.emptyValue': 'Keine',
+  'agentSnapshot.secretRedacted': 'Geheimnis verborgen',
+  'agentSnapshot.redactedValueChanged': 'Der Wert ist ausgeblendet, wurde aber geändert',
+  'agentSnapshot.noChangedContent': 'Keine anzeigbaren Änderungen',
+  'agentSnapshot.recordedChange': 'Bei der Aufzeichnung geändert',
+  'agentSnapshot.noRestoreNeeded': 'Die aktuelle Konfiguration entspricht bereits dieser Version',
+  'agentSnapshot.unsavedChangesTitle': 'Nicht gespeicherte Änderungen',
+  'agentSnapshot.unsavedChangesWarning': 'Beim Fortfahren werden die nicht gespeicherten Änderungen auf dieser Seite verworfen.',
+  'agentSnapshot.discardAndRestore': 'Verwerfen und wiederherstellen',
+  'agentSnapshot.restoreConfirm': 'Version #{version} wiederherstellen? Die aktuelle Konfiguration bleibt im Verlauf erhalten.',
+  'agentSnapshot.restoreMemoryWarning': 'Beim Wiederherstellen einer Version ohne Speicher wird der Chatverlauf dieses Agenten gelöscht. Bitte Risiko bestätigen.',
+  'agentSnapshot.restoreChatHistoryDestructiveWarning': 'Diese Wiederherstellung löscht den vorhandenen Chatverlauf dieses Agenten dauerhaft. Der Chatverlauf ist nicht in Konfigurations-Snapshots enthalten und kann nicht über den Versionsverlauf wiederhergestellt werden.',
+  'agentSnapshot.restoreSuccess': 'Version wurde wiederhergestellt',
+  'agentSnapshot.restoreFailed': 'Version konnte nicht wiederhergestellt werden',
+  'agentSnapshot.reloadAfterRestorePending': 'Die wiederhergestellte Konfiguration und die Tags werden neu geladen. Speichern ist bis zum Abschluss deaktiviert.',
+  'agentSnapshot.reloadAfterRestoreFailed': 'Die wiederhergestellte Konfiguration oder die Tags konnten nicht neu geladen werden. Speichern bleibt deaktiviert, damit veraltete Daten die Wiederherstellung nicht überschreiben. Bitte erneut versuchen.',
+  'agentSnapshot.retryReload': 'Neu laden',
+  'agentSnapshot.mutationBusy': 'Die Konfiguration wird gespeichert oder neu geladen. Bitte warten Sie, bevor Sie den Versionsverlauf öffnen oder eine Wiederherstellung starten.',
+  'agentSnapshot.deleteConfirm': 'Version #{version} löschen? Dies kann nicht rückgängig gemacht werden.',
+  'agentSnapshot.deleteSuccess': 'Version gelöscht',
+  'agentSnapshot.deleteFailed': 'Version konnte nicht gelöscht werden',
+  'agentSnapshot.fetchFailed': 'Versionsverlauf konnte nicht abgerufen werden',
+  'agentSnapshot.detailFailed': 'Versionsdetails konnten nicht abgerufen werden',
+  'agentSnapshot.correctWordCount': '{count} Ersatzwörter',
+  'agentSnapshot.source.config': 'Konfiguration gespeichert',
+  'agentSnapshot.source.current': 'Aktuelle Konfiguration',
+  'agentSnapshot.source.restore': 'Wiederhergestellt',
+  'agentSnapshot.source.initial': 'Initialversion',
+  'agentSnapshot.field.initial': 'Initialer Snapshot',
+  'agentSnapshot.field.agentCode': 'Agent-Code',
+  'agentSnapshot.field.agentName': 'Spitzname',
+  'agentSnapshot.field.asrModelId': 'Spracherkennung',
+  'agentSnapshot.field.vadModelId': 'Sprachaktivitätserkennung',
+  'agentSnapshot.field.llmModelId': 'Hauptsprachmodell',
+  'agentSnapshot.field.slmModelId': 'Kleines Sprachmodell',
+  'agentSnapshot.field.vllmModelId': 'Vision-Modell',
+  'agentSnapshot.field.ttsModelId': 'Text-zu-Sprache',
+  'agentSnapshot.field.ttsVoiceId': 'Stimme',
+  'agentSnapshot.field.ttsLanguage': 'Sprache',
+  'agentSnapshot.field.ttsVolume': 'Lautstärke',
+  'agentSnapshot.field.ttsRate': 'Geschwindigkeit',
+  'agentSnapshot.field.ttsPitch': 'Tonhöhe',
+  'agentSnapshot.field.memModelId': 'Speichermodus',
+  'agentSnapshot.field.intentModelId': 'Absichtserkennung',
+  'agentSnapshot.field.chatHistoryConf': 'Chatverlauf-Konfiguration',
+  'agentSnapshot.field.systemPrompt': 'Rollenbeschreibung',
+  'agentSnapshot.field.summaryMemory': 'Speicher',
+  'agentSnapshot.field.langCode': 'Sprachcode',
+  'agentSnapshot.field.language': 'Interaktionssprache',
+  'agentSnapshot.field.sort': 'Sortierung',
+  'agentSnapshot.field.functions': 'Plugins',
+  'agentSnapshot.field.contextProviders': 'Kontextquellen',
+  'agentSnapshot.field.correctWordFileIds': 'Ersatzwörter',
+  'agentSnapshot.field.tagNames': 'Agent-Labels',
+  'agentSnapshot.chatHistoryConf.none': 'Chatverlauf nicht aufzeichnen',
+  'agentSnapshot.chatHistoryConf.text': 'Text melden',
+  'agentSnapshot.chatHistoryConf.textVoice': 'Text und Sprache melden',
+  'agentSnapshot.model.Memory_nomem': 'Kein Speicher',
+  'agentSnapshot.model.Memory_mem_local_short': 'Lokaler Kurzzeitspeicher',
+  'agentSnapshot.model.Memory_mem0ai': 'Mem0AI-Speicher',
+  'agentSnapshot.model.Memory_mem_report_only': 'Nur melden',
+  'agentSnapshot.model.Intent_nointent': 'Keine Absichtserkennung',
+  'agentSnapshot.model.Intent_intent_llm': 'Externe LLM-Absichtserkennung',
+  'agentSnapshot.model.Intent_function_call': 'LLM-Funktionsaufruf',
+
  // Context provider dialog related
  'contextProviderDialog.title': 'Quelle bearbeiten',
  'contextProviderDialog.noContextApi': 'Keine Kontext-API',
@@ -71,6 +71,13 @@ export default {
  'home.inputPlaceholder': 'e.g. Customer Service Assistant, Voice Assistant, Knowledge Q&A',
  'home.createError': 'The name length must be between 1 and 64 characters',
  'home.createNow': 'Create Now',
+  'home.deleteConfirmTitle': 'Delete Agent',
+  'home.confirmDeleteAgent': 'Deletion cannot be undone. Type the agent name "{agentName}" to confirm.',
+  'home.deleteAgentNamePlaceholder': 'Enter agent name',
+  'home.deleteAgentNameMismatch': 'The agent name does not match',
+  'home.deleteAgentPasteForbidden': 'Please type the agent name manually. Pasting is not allowed.',
+  'home.deleteAgentMissingInfo': 'Unable to confirm agent information. Please refresh and try again.',
+  'home.deleteAgentSuccess': 'Agent deleted successfully',
  'home.justNow': 'Just now',
  'home.minutesAgo': 'minutes ago',
  'home.hoursAgo': 'hours ago',
@@ -123,6 +130,7 @@ export default {
  'agent.saving': 'Saving...',
  'agent.saveSuccess': 'Save successful',
  'agent.saveFail': 'Save failed',
+  'agent.ttsOptionsLoadFailed': 'Voice options could not be loaded. The previous voice settings were kept.',
  'agent.loadFail': 'Load failed',
  'agent.pleaseInputAgentName': 'Please input agent name',
  'agent.pleaseInputRoleDescription': 'Please input role description',
@@ -139,6 +147,92 @@ export default {
  'agent.speedHint': '-100=Slower, 0=Standard, 100=Faster',
  'agent.pitchHint': '-100=Lowest, 0=Standard, 100=Highest',

+  // Agent snapshots
+  'agentSnapshot.title': 'Version History',
+  'agentSnapshot.empty': 'No versions yet',
+  'agentSnapshot.emptyTip': 'Saved configs will appear here',
+  'agentSnapshot.version': 'Version',
+  'agentSnapshot.createdAt': 'Saved At',
+  'agentSnapshot.source': 'Source',
+  'agentSnapshot.changedFields': 'Changes',
+  'agentSnapshot.view': 'View',
+  'agentSnapshot.restore': 'Restore',
+  'agentSnapshot.delete': 'Delete',
+  'agentSnapshot.loadMore': 'Load More',
+  'agentSnapshot.detailTitle': 'Change Details',
+  'agentSnapshot.restorePreviewTitle': 'Restore Preview',
+  'agentSnapshot.confirmRestore': 'Confirm Restore',
+  'agentSnapshot.currentVersion': 'Latest Snapshot',
+  'agentSnapshot.beforeChange': 'Before',
+  'agentSnapshot.afterChange': 'After',
+  'agentSnapshot.beforeRestore': 'Before Restore',
+  'agentSnapshot.afterRestore': 'After Restore',
+  'agentSnapshot.configValue': 'Config Value',
+  'agentSnapshot.emptyValue': 'None',
+  'agentSnapshot.secretRedacted': 'Secret hidden',
+  'agentSnapshot.redactedValueChanged': 'The value is hidden, but it did change',
+  'agentSnapshot.noChangedContent': 'No displayable changes',
+  'agentSnapshot.recordedChange': 'Changed when recorded',
+  'agentSnapshot.noRestoreNeeded': 'The current configuration already matches this version',
+  'agentSnapshot.unsavedChangesTitle': 'Unsaved changes',
+  'agentSnapshot.unsavedChangesWarning': 'Continuing will discard the unsaved changes on this page.',
+  'agentSnapshot.discardAndRestore': 'Discard and restore',
+  'agentSnapshot.restoreConfirm': 'Restore to version #{version}? The current configuration will remain available in history.',
+  'agentSnapshot.restoreMemoryWarning': 'Restoring to a no-memory version will clear this agent\'s chat history. Please confirm the risk.',
+  'agentSnapshot.restoreChatHistoryDestructiveWarning': 'This restore will permanently delete this agent\'s existing chat history. Chat history is not included in configuration snapshots and cannot be recovered from version history.',
+  'agentSnapshot.restoreSuccess': 'Version restored',
+  'agentSnapshot.restoreFailed': 'Failed to restore version',
+  'agentSnapshot.reloadAfterRestorePending': 'Reloading the restored configuration and tags. Saving is disabled until this completes.',
+  'agentSnapshot.reloadAfterRestoreFailed': 'The restored configuration or tags could not be reloaded. Saving remains disabled to prevent stale data from overwriting the restore. Please retry.',
+  'agentSnapshot.retryReload': 'Reload',
+  'agentSnapshot.mutationBusy': 'The configuration is being saved or reloaded. Wait for it to finish before opening version history or restoring.',
+  'agentSnapshot.deleteConfirm': 'Delete version #{version}? This cannot be undone.',
+  'agentSnapshot.deleteSuccess': 'Version deleted',
+  'agentSnapshot.deleteFailed': 'Failed to delete version',
+  'agentSnapshot.fetchFailed': 'Failed to fetch versions',
+  'agentSnapshot.detailFailed': 'Failed to fetch version details',
+  'agentSnapshot.correctWordCount': '{count} replacement words',
+  'agentSnapshot.source.config': 'Config Save',
+  'agentSnapshot.source.current': 'Current Config',
+  'agentSnapshot.source.restore': 'Restored',
+  'agentSnapshot.source.initial': 'Initial Version',
+  'agentSnapshot.field.initial': 'Initial Snapshot',
+  'agentSnapshot.field.agentCode': 'Agent Code',
+  'agentSnapshot.field.agentName': 'Nickname',
+  'agentSnapshot.field.asrModelId': 'Speech Recognition',
+  'agentSnapshot.field.vadModelId': 'Voice Activity Detection',
+  'agentSnapshot.field.llmModelId': 'Main Language Model',
+  'agentSnapshot.field.slmModelId': 'Small Language Model',
+  'agentSnapshot.field.vllmModelId': 'Vision Model',
+  'agentSnapshot.field.ttsModelId': 'Text-to-Speech',
+  'agentSnapshot.field.ttsVoiceId': 'Voice',
+  'agentSnapshot.field.ttsLanguage': 'Language',
+  'agentSnapshot.field.ttsVolume': 'Volume',
+  'agentSnapshot.field.ttsRate': 'Speed',
+  'agentSnapshot.field.ttsPitch': 'Pitch',
+  'agentSnapshot.field.memModelId': 'Memory Mode',
+  'agentSnapshot.field.intentModelId': 'Intent Recognition',
+  'agentSnapshot.field.chatHistoryConf': 'Chat History Config',
+  'agentSnapshot.field.systemPrompt': 'Role Description',
+  'agentSnapshot.field.summaryMemory': 'Memory',
+  'agentSnapshot.field.langCode': 'Language Code',
+  'agentSnapshot.field.language': 'Interaction Language',
+  'agentSnapshot.field.sort': 'Sort',
+  'agentSnapshot.field.functions': 'Plugins',
+  'agentSnapshot.field.contextProviders': 'Context Sources',
+  'agentSnapshot.field.correctWordFileIds': 'Replacement Words',
+  'agentSnapshot.field.tagNames': 'Agent Tags',
+  'agentSnapshot.chatHistoryConf.none': 'Do not record chat history',
+  'agentSnapshot.chatHistoryConf.text': 'Report text',
+  'agentSnapshot.chatHistoryConf.textVoice': 'Report text and voice',
+  'agentSnapshot.model.Memory_nomem': 'No memory',
+  'agentSnapshot.model.Memory_mem_local_short': 'Local short memory',
+  'agentSnapshot.model.Memory_mem0ai': 'Mem0AI memory',
+  'agentSnapshot.model.Memory_mem_report_only': 'Report only',
+  'agentSnapshot.model.Intent_nointent': 'No intent recognition',
+  'agentSnapshot.model.Intent_intent_llm': 'External LLM intent recognition',
+  'agentSnapshot.model.Intent_function_call': 'LLM function calling',
+
  // Context provider dialog related
  'contextProviderDialog.title': 'Edit Source',
  'contextProviderDialog.noContextApi': 'No Context API',
@@ -1,23 +1,23 @@
+import type { Language } from '@/store/lang'
 import { ref } from 'vue'
 import { useLangStore } from '@/store/lang'
-import type { Language } from '@/store/lang'

+import de from './de'
+import en from './en'
+import pt_BR from './pt_BR'
+import vi from './vi'
 // 导入各个语言的翻译文件
 import zh_CN from './zh_CN'
-import en from './en'
 import zh_TW from './zh_TW'
-import de from './de'
-import vi from './vi'
-import pt_BR from './pt_BR'

 // 语言包映射
 const messages = {
-  zh_CN: zh_CN,
+  zh_CN,
  en,
-  zh_TW: zh_TW,
+  zh_TW,
  de,
  vi,
-  pt_BR: pt_BR,
+  pt_BR,
 }

 // 当前使用的语言
@@ -42,7 +42,7 @@ export function t(key: string, params?: Record<string, string | number>): string

  // 直接查找扁平键名
  if (langMessages && typeof langMessages === 'object' && key in langMessages) {
-    let value = langMessages[key]
+    const value = langMessages[key]
    if (typeof value === 'string') {
      // 处理参数替换
      if (params) {
@@ -71,6 +71,13 @@ export default {
  'home.inputPlaceholder': 'ex: Assistente de Atendimento, Assistente de Voz, Perguntas e Respostas',
  'home.createError': 'O comprimento do nome deve estar entre 1 e 64 caracteres',
  'home.createNow': 'Criar Agora',
+  'home.deleteConfirmTitle': 'Excluir Agente',
+  'home.confirmDeleteAgent': 'A exclusão não pode ser desfeita. Digite o nome do agente "{agentName}" para confirmar.',
+  'home.deleteAgentNamePlaceholder': 'Digite o nome do agente',
+  'home.deleteAgentNameMismatch': 'O nome do agente não corresponde',
+  'home.deleteAgentPasteForbidden': 'Digite o nome do agente manualmente. Colar não é permitido.',
+  'home.deleteAgentMissingInfo': 'Não foi possível confirmar as informações do agente. Atualize a página e tente novamente.',
+  'home.deleteAgentSuccess': 'Agente excluído com sucesso',
  'home.justNow': 'Agora mesmo',
  'home.minutesAgo': 'minutos atrás',
  'home.hoursAgo': 'horas atrás',
@@ -123,6 +130,7 @@ export default {
  'agent.saving': 'Salvando...',
  'agent.saveSuccess': 'Salvo com sucesso',
  'agent.saveFail': 'Falha ao salvar',
+  'agent.ttsOptionsLoadFailed': 'Não foi possível carregar as opções de voz. As configurações anteriores foram mantidas.',
  'agent.loadFail': 'Falha ao carregar',
  'agent.pleaseInputAgentName': 'Por favor, insira o nome do agente',
  'agent.pleaseInputRoleDescription': 'Por favor, insira a descrição do papel',
@@ -139,6 +147,92 @@ export default {
  'agent.speedHint': '-100=Slower, 0=Standard, 100=Faster',
  'agent.pitchHint': '-100=Lowest, 0=Standard, 100=Highest',

+  // Histórico de versões do agente
+  'agentSnapshot.title': 'Histórico de Versões',
+  'agentSnapshot.empty': 'Ainda sem versões',
+  'agentSnapshot.emptyTip': 'Configurações salvas aparecerão aqui',
+  'agentSnapshot.version': 'Versão',
+  'agentSnapshot.createdAt': 'Salvo em',
+  'agentSnapshot.source': 'Origem',
+  'agentSnapshot.changedFields': 'Alterações',
+  'agentSnapshot.view': 'Ver',
+  'agentSnapshot.restore': 'Restaurar',
+  'agentSnapshot.delete': 'Excluir',
+  'agentSnapshot.loadMore': 'Carregar Mais',
+  'agentSnapshot.detailTitle': 'Detalhes da Alteração',
+  'agentSnapshot.restorePreviewTitle': 'Prévia da Restauração',
+  'agentSnapshot.confirmRestore': 'Confirmar Restauração',
+  'agentSnapshot.currentVersion': 'Snapshot mais recente',
+  'agentSnapshot.beforeChange': 'Antes',
+  'agentSnapshot.afterChange': 'Depois',
+  'agentSnapshot.beforeRestore': 'Antes da Restauração',
+  'agentSnapshot.afterRestore': 'Depois da Restauração',
+  'agentSnapshot.configValue': 'Valor da Configuração',
+  'agentSnapshot.emptyValue': 'Nenhum',
+  'agentSnapshot.secretRedacted': 'Segredo oculto',
+  'agentSnapshot.redactedValueChanged': 'O valor está oculto, mas foi alterado',
+  'agentSnapshot.noChangedContent': 'Nenhuma alteração exibível',
+  'agentSnapshot.recordedChange': 'Alterado quando registrado',
+  'agentSnapshot.noRestoreNeeded': 'A configuração atual já corresponde a esta versão',
+  'agentSnapshot.unsavedChangesTitle': 'Alterações não salvas',
+  'agentSnapshot.unsavedChangesWarning': 'Continuar descartará as alterações não salvas desta página.',
+  'agentSnapshot.discardAndRestore': 'Descartar e restaurar',
+  'agentSnapshot.restoreConfirm': 'Restaurar para a versão #{version}? A configuração atual continuará disponível no histórico.',
+  'agentSnapshot.restoreMemoryWarning': 'Restaurar para uma versão sem memória limpará o histórico de chat deste agente. Confirme o risco.',
+  'agentSnapshot.restoreChatHistoryDestructiveWarning': 'Esta restauração excluirá permanentemente o histórico de chat existente deste agente. O histórico de chat não faz parte dos snapshots de configuração e não pode ser recuperado pelo histórico de versões.',
+  'agentSnapshot.restoreSuccess': 'Versão restaurada',
+  'agentSnapshot.restoreFailed': 'Falha ao restaurar versão',
+  'agentSnapshot.reloadAfterRestorePending': 'Recarregando a configuração e as tags restauradas. Não é possível salvar até a conclusão.',
+  'agentSnapshot.reloadAfterRestoreFailed': 'Não foi possível recarregar a configuração ou as tags restauradas. O salvamento permanece desativado para impedir que dados antigos sobrescrevam a restauração. Tente novamente.',
+  'agentSnapshot.retryReload': 'Recarregar',
+  'agentSnapshot.mutationBusy': 'A configuração está sendo salva ou recarregada. Aguarde a conclusão antes de abrir o histórico de versões ou restaurar.',
+  'agentSnapshot.deleteConfirm': 'Excluir versão #{version}? Esta ação não pode ser desfeita.',
+  'agentSnapshot.deleteSuccess': 'Versão excluída',
+  'agentSnapshot.deleteFailed': 'Falha ao excluir versão',
+  'agentSnapshot.fetchFailed': 'Falha ao buscar versões',
+  'agentSnapshot.detailFailed': 'Falha ao buscar detalhes da versão',
+  'agentSnapshot.correctWordCount': '{count} palavras de substituição',
+  'agentSnapshot.source.config': 'Configuração Salva',
+  'agentSnapshot.source.current': 'Configuração Atual',
+  'agentSnapshot.source.restore': 'Restaurado',
+  'agentSnapshot.source.initial': 'Versão Inicial',
+  'agentSnapshot.field.initial': 'Snapshot Inicial',
+  'agentSnapshot.field.agentCode': 'Código do Agente',
+  'agentSnapshot.field.agentName': 'Apelido',
+  'agentSnapshot.field.asrModelId': 'Reconhecimento de Fala',
+  'agentSnapshot.field.vadModelId': 'Detecção de Voz',
+  'agentSnapshot.field.llmModelId': 'Modelo Principal',
+  'agentSnapshot.field.slmModelId': 'Modelo Pequeno',
+  'agentSnapshot.field.vllmModelId': 'Modelo Visual',
+  'agentSnapshot.field.ttsModelId': 'Texto para Fala',
+  'agentSnapshot.field.ttsVoiceId': 'Voz',
+  'agentSnapshot.field.ttsLanguage': 'Idioma',
+  'agentSnapshot.field.ttsVolume': 'Volume',
+  'agentSnapshot.field.ttsRate': 'Velocidade',
+  'agentSnapshot.field.ttsPitch': 'Tonalidade',
+  'agentSnapshot.field.memModelId': 'Modo de Memória',
+  'agentSnapshot.field.intentModelId': 'Reconhecimento de Intenção',
+  'agentSnapshot.field.chatHistoryConf': 'Configuração do Histórico',
+  'agentSnapshot.field.systemPrompt': 'Descrição do Papel',
+  'agentSnapshot.field.summaryMemory': 'Memória',
+  'agentSnapshot.field.langCode': 'Código do Idioma',
+  'agentSnapshot.field.language': 'Idioma de Interação',
+  'agentSnapshot.field.sort': 'Ordenação',
+  'agentSnapshot.field.functions': 'Plugins',
+  'agentSnapshot.field.contextProviders': 'Fontes de Contexto',
+  'agentSnapshot.field.correctWordFileIds': 'Palavras de Substituição',
+  'agentSnapshot.field.tagNames': 'Tags do Agente',
+  'agentSnapshot.chatHistoryConf.none': 'Não registrar histórico de chat',
+  'agentSnapshot.chatHistoryConf.text': 'Reportar texto',
+  'agentSnapshot.chatHistoryConf.textVoice': 'Reportar texto e voz',
+  'agentSnapshot.model.Memory_nomem': 'Sem memória',
+  'agentSnapshot.model.Memory_mem_local_short': 'Memória curta local',
+  'agentSnapshot.model.Memory_mem0ai': 'Memória Mem0AI',
+  'agentSnapshot.model.Memory_mem_report_only': 'Apenas reportar',
+  'agentSnapshot.model.Intent_nointent': 'Sem reconhecimento de intenção',
+  'agentSnapshot.model.Intent_intent_llm': 'Reconhecimento por LLM externo',
+  'agentSnapshot.model.Intent_function_call': 'Chamada de função por LLM',
+
  // Diálogo de provedor de contexto
  'contextProviderDialog.title': 'Editar Fonte',
  'contextProviderDialog.noContextApi': 'Sem API de Contexto',
@@ -71,6 +71,13 @@ export default {
  'home.inputPlaceholder': 'ví dụ: Trợ lý chăm sóc khách hàng, Trợ lý giọng nói, Hỏi đáp kiến thức',
  'home.createError': 'Độ dài tên phải từ 1 đến 64 ký tự',
  'home.createNow': 'Tạo ngay',
+  'home.deleteConfirmTitle': 'Xóa đại lý',
+  'home.confirmDeleteAgent': 'Không thể hoàn tác sau khi xóa. Nhập tên đại lý "{agentName}" để xác nhận.',
+  'home.deleteAgentNamePlaceholder': 'Nhập tên đại lý',
+  'home.deleteAgentNameMismatch': 'Tên đại lý không khớp',
+  'home.deleteAgentPasteForbidden': 'Vui lòng nhập thủ công tên đại lý. Không được dán.',
+  'home.deleteAgentMissingInfo': 'Không thể xác nhận thông tin đại lý. Vui lòng tải lại rồi thử lại.',
+  'home.deleteAgentSuccess': 'Đã xóa đại lý thành công',
  'home.justNow': 'Vừa xong',
  'home.minutesAgo': 'phút trước',
  'home.hoursAgo': 'giờ trước',
@@ -123,6 +130,7 @@ export default {
  'agent.saving': 'Đang lưu...',
  'agent.saveSuccess': 'Lưu thành công',
  'agent.saveFail': 'Lưu thất bại',
+  'agent.ttsOptionsLoadFailed': 'Không thể tải tùy chọn giọng nói. Cấu hình giọng nói trước đó đã được giữ lại.',
  'agent.loadFail': 'Tải thất bại',
  'agent.pleaseInputAgentName': 'Vui lòng nhập tên đại lý',
  'agent.pleaseInputRoleDescription': 'Vui lòng nhập mô tả vai trò',
@@ -139,6 +147,92 @@ export default {
  'agent.speedHint': '-100=Slowest, 0=Standard, 100=Fastest',
  'agent.pitchHint': '-100=Lowest, 0=Standard, 100=Highest',

+  // Lịch sử phiên bản đại lý
+  'agentSnapshot.title': 'Lịch sử phiên bản',
+  'agentSnapshot.empty': 'Chưa có phiên bản',
+  'agentSnapshot.emptyTip': 'Cấu hình đã lưu sẽ xuất hiện ở đây',
+  'agentSnapshot.version': 'Phiên bản',
+  'agentSnapshot.createdAt': 'Thời gian lưu',
+  'agentSnapshot.source': 'Nguồn',
+  'agentSnapshot.changedFields': 'Thay đổi',
+  'agentSnapshot.view': 'Xem',
+  'agentSnapshot.restore': 'Khôi phục',
+  'agentSnapshot.delete': 'Xóa',
+  'agentSnapshot.loadMore': 'Tải thêm',
+  'agentSnapshot.detailTitle': 'Chi tiết thay đổi',
+  'agentSnapshot.restorePreviewTitle': 'Xem trước khôi phục',
+  'agentSnapshot.confirmRestore': 'Xác nhận khôi phục',
+  'agentSnapshot.currentVersion': 'Ảnh chụp mới nhất',
+  'agentSnapshot.beforeChange': 'Trước',
+  'agentSnapshot.afterChange': 'Sau',
+  'agentSnapshot.beforeRestore': 'Trước khôi phục',
+  'agentSnapshot.afterRestore': 'Sau khôi phục',
+  'agentSnapshot.configValue': 'Giá trị cấu hình',
+  'agentSnapshot.emptyValue': 'Không có',
+  'agentSnapshot.secretRedacted': 'Đã ẩn khóa bí mật',
+  'agentSnapshot.redactedValueChanged': 'Giá trị đã được ẩn nhưng thực sự đã thay đổi',
+  'agentSnapshot.noChangedContent': 'Không có thay đổi để hiển thị',
+  'agentSnapshot.recordedChange': 'Đã thay đổi khi ghi nhận',
+  'agentSnapshot.noRestoreNeeded': 'Cấu hình hiện tại đã khớp với phiên bản này',
+  'agentSnapshot.unsavedChangesTitle': 'Có thay đổi chưa lưu',
+  'agentSnapshot.unsavedChangesWarning': 'Tiếp tục sẽ hủy các thay đổi chưa lưu trên trang này.',
+  'agentSnapshot.discardAndRestore': 'Hủy thay đổi và khôi phục',
+  'agentSnapshot.restoreConfirm': 'Khôi phục về phiên bản #{version}? Cấu hình hiện tại sẽ vẫn có trong lịch sử.',
+  'agentSnapshot.restoreMemoryWarning': 'Khôi phục về phiên bản không có bộ nhớ sẽ xóa lịch sử trò chuyện của đại lý này. Vui lòng xác nhận rủi ro.',
+  'agentSnapshot.restoreChatHistoryDestructiveWarning': 'Thao tác khôi phục này sẽ xóa vĩnh viễn lịch sử trò chuyện hiện có của tác nhân. Lịch sử trò chuyện không nằm trong bản chụp cấu hình và không thể khôi phục từ lịch sử phiên bản.',
+  'agentSnapshot.restoreSuccess': 'Đã khôi phục phiên bản',
+  'agentSnapshot.restoreFailed': 'Khôi phục phiên bản thất bại',
+  'agentSnapshot.reloadAfterRestorePending': 'Đang tải lại cấu hình và thẻ đã khôi phục. Không thể lưu cho đến khi hoàn tất.',
+  'agentSnapshot.reloadAfterRestoreFailed': 'Không thể tải lại cấu hình hoặc thẻ đã khôi phục. Chức năng lưu vẫn bị tắt để tránh dữ liệu cũ ghi đè kết quả khôi phục. Vui lòng thử lại.',
+  'agentSnapshot.retryReload': 'Tải lại',
+  'agentSnapshot.mutationBusy': 'Cấu hình đang được lưu hoặc tải lại. Hãy đợi hoàn tất trước khi mở lịch sử phiên bản hoặc khôi phục.',
+  'agentSnapshot.deleteConfirm': 'Xóa phiên bản #{version}? Không thể hoàn tác thao tác này.',
+  'agentSnapshot.deleteSuccess': 'Đã xóa phiên bản',
+  'agentSnapshot.deleteFailed': 'Xóa phiên bản thất bại',
+  'agentSnapshot.fetchFailed': 'Lấy lịch sử phiên bản thất bại',
+  'agentSnapshot.detailFailed': 'Lấy chi tiết phiên bản thất bại',
+  'agentSnapshot.correctWordCount': '{count} từ thay thế',
+  'agentSnapshot.source.config': 'Lưu cấu hình',
+  'agentSnapshot.source.current': 'Cấu hình hiện tại',
+  'agentSnapshot.source.restore': 'Đã khôi phục',
+  'agentSnapshot.source.initial': 'Phiên bản khởi tạo',
+  'agentSnapshot.field.initial': 'Ảnh chụp ban đầu',
+  'agentSnapshot.field.agentCode': 'Mã đại lý',
+  'agentSnapshot.field.agentName': 'Biệt danh',
+  'agentSnapshot.field.asrModelId': 'Nhận dạng giọng nói',
+  'agentSnapshot.field.vadModelId': 'Phát hiện hoạt động giọng nói',
+  'agentSnapshot.field.llmModelId': 'Mô hình ngôn ngữ chính',
+  'agentSnapshot.field.slmModelId': 'Mô hình ngôn ngữ nhỏ',
+  'agentSnapshot.field.vllmModelId': 'Mô hình thị giác',
+  'agentSnapshot.field.ttsModelId': 'Tổng hợp giọng nói',
+  'agentSnapshot.field.ttsVoiceId': 'Giọng',
+  'agentSnapshot.field.ttsLanguage': 'Ngôn ngữ',
+  'agentSnapshot.field.ttsVolume': 'Âm lượng',
+  'agentSnapshot.field.ttsRate': 'Tốc độ',
+  'agentSnapshot.field.ttsPitch': 'Tone',
+  'agentSnapshot.field.memModelId': 'Chế độ bộ nhớ',
+  'agentSnapshot.field.intentModelId': 'Nhận dạng ý định',
+  'agentSnapshot.field.chatHistoryConf': 'Cấu hình lịch sử chat',
+  'agentSnapshot.field.systemPrompt': 'Mô tả vai trò',
+  'agentSnapshot.field.summaryMemory': 'Bộ nhớ',
+  'agentSnapshot.field.langCode': 'Mã ngôn ngữ',
+  'agentSnapshot.field.language': 'Ngôn ngữ tương tác',
+  'agentSnapshot.field.sort': 'Sắp xếp',
+  'agentSnapshot.field.functions': 'Plugin',
+  'agentSnapshot.field.contextProviders': 'Nguồn ngữ cảnh',
+  'agentSnapshot.field.correctWordFileIds': 'Từ thay thế',
+  'agentSnapshot.field.tagNames': 'Nhãn đại lý',
+  'agentSnapshot.chatHistoryConf.none': 'Không ghi lịch sử chat',
+  'agentSnapshot.chatHistoryConf.text': 'Gửi văn bản',
+  'agentSnapshot.chatHistoryConf.textVoice': 'Gửi văn bản và giọng nói',
+  'agentSnapshot.model.Memory_nomem': 'Không có bộ nhớ',
+  'agentSnapshot.model.Memory_mem_local_short': 'Bộ nhớ ngắn hạn cục bộ',
+  'agentSnapshot.model.Memory_mem0ai': 'Bộ nhớ Mem0AI',
+  'agentSnapshot.model.Memory_mem_report_only': 'Chỉ gửi báo cáo',
+  'agentSnapshot.model.Intent_nointent': 'Không nhận dạng ý định',
+  'agentSnapshot.model.Intent_intent_llm': 'Nhận dạng ý định LLM ngoài',
+  'agentSnapshot.model.Intent_function_call': 'Gọi hàm bằng LLM',
+
  // Context provider dialog related
  'contextProviderDialog.title': 'Chỉnh sửa nguồn',
  'contextProviderDialog.noContextApi': 'Không có API ngữ cảnh',
@@ -71,6 +71,13 @@ export default {
  'home.inputPlaceholder': '例如：客服助手、语音助理、知识问答',
  'home.createError': '名称长度必须在 1 到 64 个字符之间',
  'home.createNow': '立即创建',
+  'home.deleteConfirmTitle': '删除智能体',
+  'home.confirmDeleteAgent': '删除后无法恢复。请输入智能体名称“{agentName}”确认删除。',
+  'home.deleteAgentNamePlaceholder': '请输入智能体名称',
+  'home.deleteAgentNameMismatch': '输入的智能体名称不匹配',
+  'home.deleteAgentPasteForbidden': '请手动输入智能体名称，不允许粘贴',
+  'home.deleteAgentMissingInfo': '无法确认智能体信息，请刷新后重试',
+  'home.deleteAgentSuccess': '智能体删除成功',
  'home.justNow': '刚刚',
  'home.minutesAgo': '分钟前',
  'home.hoursAgo': '小时前',
@@ -123,6 +130,7 @@ export default {
  'agent.saving': '保存中...',
  'agent.saveSuccess': '保存成功',
  'agent.saveFail': '保存失败',
+  'agent.ttsOptionsLoadFailed': '语音选项加载失败，已保留原来的语音配置',
  'agent.loadFail': '加载失败',
  'agent.pleaseInputAgentName': '请输入智能体名称',
  'agent.pleaseInputRoleDescription': '请输入角色介绍',
@@ -139,6 +147,92 @@ export default {
  'agent.speedHint': '-100=最慢, 0=标准, 100=最快',
  'agent.pitchHint': '-100=最低, 0=标准, 100=最高',

+  // 智能体历史版本
+  'agentSnapshot.title': '历史版本',
+  'agentSnapshot.empty': '暂无历史版本',
+  'agentSnapshot.emptyTip': '保存配置后会生成历史版本',
+  'agentSnapshot.version': '版本',
+  'agentSnapshot.createdAt': '保存时间',
+  'agentSnapshot.source': '来源',
+  'agentSnapshot.changedFields': '变更内容',
+  'agentSnapshot.view': '查看',
+  'agentSnapshot.restore': '恢复',
+  'agentSnapshot.delete': '删除',
+  'agentSnapshot.loadMore': '加载更多',
+  'agentSnapshot.detailTitle': '变更详情',
+  'agentSnapshot.restorePreviewTitle': '恢复预览',
+  'agentSnapshot.confirmRestore': '确认恢复',
+  'agentSnapshot.currentVersion': '最新快照',
+  'agentSnapshot.beforeChange': '变化前',
+  'agentSnapshot.afterChange': '变化后',
+  'agentSnapshot.beforeRestore': '恢复前',
+  'agentSnapshot.afterRestore': '恢复后',
+  'agentSnapshot.configValue': '配置值',
+  'agentSnapshot.emptyValue': '无',
+  'agentSnapshot.secretRedacted': '密钥已隐藏',
+  'agentSnapshot.redactedValueChanged': '值已脱敏，但确有变化',
+  'agentSnapshot.noChangedContent': '无可显示变更',
+  'agentSnapshot.recordedChange': '记录时发生变更',
+  'agentSnapshot.noRestoreNeeded': '当前配置与目标版本相同，无需恢复',
+  'agentSnapshot.unsavedChangesTitle': '存在未保存修改',
+  'agentSnapshot.unsavedChangesWarning': '继续恢复会放弃当前页面中尚未保存的修改。',
+  'agentSnapshot.discardAndRestore': '放弃修改并恢复',
+  'agentSnapshot.restoreConfirm': '确定恢复到版本 #{version}？当前配置会保留在历史中。',
+  'agentSnapshot.restoreMemoryWarning': '恢复到无记忆版本会清空该智能体聊天记录，请确认风险。',
+  'agentSnapshot.restoreChatHistoryDestructiveWarning': '此恢复会永久删除该智能体现有的聊天记录。聊天记录不包含在配置快照中，删除后无法通过历史版本恢复。',
+  'agentSnapshot.restoreSuccess': '版本已恢复',
+  'agentSnapshot.restoreFailed': '版本恢复失败',
+  'agentSnapshot.reloadAfterRestorePending': '正在重新加载恢复后的配置和标签，完成前无法保存。',
+  'agentSnapshot.reloadAfterRestoreFailed': '无法重新加载恢复后的配置或标签。为防止旧数据覆盖恢复结果，保存已禁用，请重试。',
+  'agentSnapshot.retryReload': '重新加载',
+  'agentSnapshot.mutationBusy': '配置正在保存或重新加载，请完成后再打开历史版本或恢复。',
+  'agentSnapshot.deleteConfirm': '确定删除版本 #{version}？此操作不可撤销。',
+  'agentSnapshot.deleteSuccess': '历史版本已删除',
+  'agentSnapshot.deleteFailed': '历史版本删除失败',
+  'agentSnapshot.fetchFailed': '获取历史版本失败',
+  'agentSnapshot.detailFailed': '获取版本详情失败',
+  'agentSnapshot.correctWordCount': '共 {count} 个替换词',
+  'agentSnapshot.source.config': '配置保存',
+  'agentSnapshot.source.current': '当前配置',
+  'agentSnapshot.source.restore': '恢复结果',
+  'agentSnapshot.source.initial': '初始版本',
+  'agentSnapshot.field.initial': '初始快照',
+  'agentSnapshot.field.agentCode': '智能体编码',
+  'agentSnapshot.field.agentName': '助手昵称',
+  'agentSnapshot.field.asrModelId': '语音识别',
+  'agentSnapshot.field.vadModelId': '语音活动检测',
+  'agentSnapshot.field.llmModelId': '主语言模型',
+  'agentSnapshot.field.slmModelId': '小参数模型',
+  'agentSnapshot.field.vllmModelId': '视觉大模型',
+  'agentSnapshot.field.ttsModelId': '语音合成',
+  'agentSnapshot.field.ttsVoiceId': '声音音色',
+  'agentSnapshot.field.ttsLanguage': '对话语言',
+  'agentSnapshot.field.ttsVolume': '音量',
+  'agentSnapshot.field.ttsRate': '语速',
+  'agentSnapshot.field.ttsPitch': '音调',
+  'agentSnapshot.field.memModelId': '记忆模式',
+  'agentSnapshot.field.intentModelId': '意图识别',
+  'agentSnapshot.field.chatHistoryConf': '聊天记录配置',
+  'agentSnapshot.field.systemPrompt': '角色介绍',
+  'agentSnapshot.field.summaryMemory': '记忆',
+  'agentSnapshot.field.langCode': '语言编码',
+  'agentSnapshot.field.language': '交互语种',
+  'agentSnapshot.field.sort': '排序',
+  'agentSnapshot.field.functions': '插件',
+  'agentSnapshot.field.contextProviders': '上下文源',
+  'agentSnapshot.field.correctWordFileIds': '替换词',
+  'agentSnapshot.field.tagNames': '智能体标签',
+  'agentSnapshot.chatHistoryConf.none': '不记录聊天记录',
+  'agentSnapshot.chatHistoryConf.text': '上报文字',
+  'agentSnapshot.chatHistoryConf.textVoice': '上报文字+语音',
+  'agentSnapshot.model.Memory_nomem': '无记忆',
+  'agentSnapshot.model.Memory_mem_local_short': '本地短期记忆',
+  'agentSnapshot.model.Memory_mem0ai': 'Mem0AI 记忆',
+  'agentSnapshot.model.Memory_mem_report_only': '仅上报',
+  'agentSnapshot.model.Intent_nointent': '无意图识别',
+  'agentSnapshot.model.Intent_intent_llm': '外部大模型意图识别',
+  'agentSnapshot.model.Intent_function_call': '大模型函数调用',
+
  // 上下文源对话框相关
  'contextProviderDialog.title': '编辑源',
  'contextProviderDialog.noContextApi': '暂无上下文API',
@@ -92,6 +92,13 @@ export default {
  'home.inputPlaceholder': '例如：客服助手、語音助理、知識問答',
  'home.createError': '暱稱長度必須在 1 到 64 個字元之間。',
  'home.createNow': '立即創建',
+  'home.deleteConfirmTitle': '刪除智能體',
+  'home.confirmDeleteAgent': '刪除後無法復原。請輸入智能體名稱「{agentName}」確認刪除。',
+  'home.deleteAgentNamePlaceholder': '請輸入智能體名稱',
+  'home.deleteAgentNameMismatch': '輸入的智能體名稱不匹配',
+  'home.deleteAgentPasteForbidden': '請手動輸入智能體名稱，不允許貼上',
+  'home.deleteAgentMissingInfo': '無法確認智能體資訊，請重新整理後再試',
+  'home.deleteAgentSuccess': '智能體刪除成功',
  'home.justNow': '剛剛',
  'home.minutesAgo': '分鐘前',
  'home.hoursAgo': '小時前',
@@ -144,6 +151,7 @@ export default {
  'agent.saving': '儲存中...',
  'agent.saveSuccess': '儲存成功',
  'agent.saveFail': '儲存失敗',
+  'agent.ttsOptionsLoadFailed': '語音選項載入失敗，已保留原來的語音設定',
  'agent.loadFail': '加載失敗',
  'agent.pleaseInputAgentName': '請輸入助手暱稱',
  'agent.pleaseInputRoleDescription': '請輸入角色介紹',
@@ -160,6 +168,92 @@ export default {
  'agent.speedHint': '-100=最慢, 0=標準, 100=最快',
  'agent.pitchHint': '-100=最低, 0=標準, 100=最高',

+  // 智能體歷史版本
+  'agentSnapshot.title': '歷史版本',
+  'agentSnapshot.empty': '暫無歷史版本',
+  'agentSnapshot.emptyTip': '保存配置後會生成歷史版本',
+  'agentSnapshot.version': '版本',
+  'agentSnapshot.createdAt': '保存時間',
+  'agentSnapshot.source': '來源',
+  'agentSnapshot.changedFields': '變更內容',
+  'agentSnapshot.view': '查看',
+  'agentSnapshot.restore': '恢復',
+  'agentSnapshot.delete': '刪除',
+  'agentSnapshot.loadMore': '載入更多',
+  'agentSnapshot.detailTitle': '變更詳情',
+  'agentSnapshot.restorePreviewTitle': '恢復預覽',
+  'agentSnapshot.confirmRestore': '確認恢復',
+  'agentSnapshot.currentVersion': '最新快照',
+  'agentSnapshot.beforeChange': '變化前',
+  'agentSnapshot.afterChange': '變化後',
+  'agentSnapshot.beforeRestore': '恢復前',
+  'agentSnapshot.afterRestore': '恢復後',
+  'agentSnapshot.configValue': '配置值',
+  'agentSnapshot.emptyValue': '無',
+  'agentSnapshot.secretRedacted': '密鑰已隱藏',
+  'agentSnapshot.redactedValueChanged': '值已脫敏，但確有變化',
+  'agentSnapshot.noChangedContent': '無可顯示變更',
+  'agentSnapshot.recordedChange': '記錄時發生變更',
+  'agentSnapshot.noRestoreNeeded': '目前設定與目標版本相同，無需恢復',
+  'agentSnapshot.unsavedChangesTitle': '存在未儲存修改',
+  'agentSnapshot.unsavedChangesWarning': '繼續恢復會放棄目前頁面中尚未儲存的修改。',
+  'agentSnapshot.discardAndRestore': '放棄修改並恢復',
+  'agentSnapshot.restoreConfirm': '確定恢復到版本 #{version}？目前設定會保留在歷史中。',
+  'agentSnapshot.restoreMemoryWarning': '恢復到無記憶版本會清空該智能體聊天記錄，請確認風險。',
+  'agentSnapshot.restoreChatHistoryDestructiveWarning': '此恢復會永久刪除該智能體現有的聊天記錄。聊天記錄不包含在配置快照中，刪除後無法透過歷史版本恢復。',
+  'agentSnapshot.restoreSuccess': '版本已恢復',
+  'agentSnapshot.restoreFailed': '版本恢復失敗',
+  'agentSnapshot.reloadAfterRestorePending': '正在重新載入恢復後的配置和標籤，完成前無法儲存。',
+  'agentSnapshot.reloadAfterRestoreFailed': '無法重新載入恢復後的配置或標籤。為防止舊資料覆蓋恢復結果，儲存已停用，請重試。',
+  'agentSnapshot.retryReload': '重新載入',
+  'agentSnapshot.mutationBusy': '配置正在儲存或重新載入，請完成後再開啟歷史版本或恢復。',
+  'agentSnapshot.deleteConfirm': '確定刪除版本 #{version}？此操作不可復原。',
+  'agentSnapshot.deleteSuccess': '歷史版本已刪除',
+  'agentSnapshot.deleteFailed': '歷史版本刪除失敗',
+  'agentSnapshot.fetchFailed': '獲取歷史版本失敗',
+  'agentSnapshot.detailFailed': '獲取版本詳情失敗',
+  'agentSnapshot.correctWordCount': '共 {count} 個替換詞',
+  'agentSnapshot.source.config': '配置保存',
+  'agentSnapshot.source.current': '當前配置',
+  'agentSnapshot.source.restore': '恢復結果',
+  'agentSnapshot.source.initial': '初始版本',
+  'agentSnapshot.field.initial': '初始快照',
+  'agentSnapshot.field.agentCode': '智能體編碼',
+  'agentSnapshot.field.agentName': '助手暱稱',
+  'agentSnapshot.field.asrModelId': '語音識別',
+  'agentSnapshot.field.vadModelId': '語音活動檢測',
+  'agentSnapshot.field.llmModelId': '主語言模型',
+  'agentSnapshot.field.slmModelId': '小參數模型',
+  'agentSnapshot.field.vllmModelId': '視覺大模型',
+  'agentSnapshot.field.ttsModelId': '語音合成',
+  'agentSnapshot.field.ttsVoiceId': '聲音音色',
+  'agentSnapshot.field.ttsLanguage': '對話語言',
+  'agentSnapshot.field.ttsVolume': '音量',
+  'agentSnapshot.field.ttsRate': '語速',
+  'agentSnapshot.field.ttsPitch': '音調',
+  'agentSnapshot.field.memModelId': '記憶模式',
+  'agentSnapshot.field.intentModelId': '意圖識別',
+  'agentSnapshot.field.chatHistoryConf': '聊天記錄配置',
+  'agentSnapshot.field.systemPrompt': '角色介紹',
+  'agentSnapshot.field.summaryMemory': '記憶',
+  'agentSnapshot.field.langCode': '語言編碼',
+  'agentSnapshot.field.language': '交互語種',
+  'agentSnapshot.field.sort': '排序',
+  'agentSnapshot.field.functions': '插件',
+  'agentSnapshot.field.contextProviders': '上下文源',
+  'agentSnapshot.field.correctWordFileIds': '替換詞',
+  'agentSnapshot.field.tagNames': '智能體標籤',
+  'agentSnapshot.chatHistoryConf.none': '不記錄聊天記錄',
+  'agentSnapshot.chatHistoryConf.text': '上報文字',
+  'agentSnapshot.chatHistoryConf.textVoice': '上報文字+語音',
+  'agentSnapshot.model.Memory_nomem': '無記憶',
+  'agentSnapshot.model.Memory_mem_local_short': '本地短期記憶',
+  'agentSnapshot.model.Memory_mem0ai': 'Mem0AI 記憶',
+  'agentSnapshot.model.Memory_mem_report_only': '僅上報',
+  'agentSnapshot.model.Intent_nointent': '無意圖識別',
+  'agentSnapshot.model.Intent_intent_llm': '外部大模型意圖識別',
+  'agentSnapshot.model.Intent_function_call': '大模型函數調用',
+
  // 上下文源对话框相关
  'contextProviderDialog.title': '編輯源',
  'contextProviderDialog.noContextApi': '暫無上下文API',
@@ -1,5 +1,5 @@
 <script lang="ts" setup>
-import type { ConfigProviderThemeVars } from 'wot-design-uni'
+import type { ConfigProviderThemeVars } from 'wot-design-uni/components/wd-config-provider/types'

 const themeVars: ConfigProviderThemeVars = {
  // colorTheme: 'red',
@@ -38,10 +38,8 @@ onLoad(() => {
  <wd-tabbar
    v-if="customTabbarEnable"
    v-model="tabbarStore.curIdx"
-    bordered
-    safe-area-inset-bottom
-    placeholder
-    fixed
+
+    safe-area-inset-bottom bordered placeholder fixed
    @change="selectTabBar"
  >
    <block v-for="(item, idx) in tabbarList" :key="item.path">
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
wengzh	2a9f809700	refactor(reportHandle): 重构上报处理逻辑，适配多格式音频转换 1. 重命名参数与变量，明确上报类型与音频格式 2. 拆分PCM和Opus转WAV逻辑，分别处理不同输入格式 3. 移动校验逻辑到上报队列函数开头，提前拦截无效上报 4. 完善Opus转WAV的解码与资源释放流程	2026-07-27 09:59:32 +08:00
CGDandGitHub	7c58fa37b2	Merge pull request #3293 from xinnan-tech/refactor/mybatis-plus-single-source refactor(manager-api): consolidate MyBatis-Plus 3.5.17 integration	2026-07-20 14:42:31 +08:00
Tyke Chen	10a67c772f	refactor(manager-api): consolidate mybatis-plus 3.5.17 integration	2026-07-20 10:31:08 +08:00
CGDandGitHub	7e8e5d34b8	Merge pull request #3279 from xinnan-tech/fix/issue-3276-context-provider fix: 修复 ContextProviderListTypeHandler 多版本兼容问题	2026-07-17 09:28:14 +08:00
CGDandGitHub	c6bc20c05e	Merge pull request #3283 from xinnan-tech/fix/device-timezone-consistency fix: 修复跨时区场景下设备时间与在线状态异常	2026-07-16 16:58:49 +08:00
wengzhandGitHub	1998807b69	Merge pull request #3285 from xinnan-tech/py-aec perf: 优化相关逻辑减少重复计算	2026-07-14 16:36:16 +08:00
Sakura-RanChen	55c0495661	perf: 优化相关逻辑减少重复计算	2026-07-14 15:52:30 +08:00
Tyke Chen	dbeda01697	fix: 修复设备跨时区时间与在线状态	2026-07-14 10:08:23 +08:00
Tyke Chen	023dea2441	fix: 修复上下文源类型处理器兼容问题	2026-07-13 16:03:39 +08:00
CGDandGitHub	ad3fb4d8c8	Merge pull request #3278 from xinnan-tech/agent-snapshot-history-fixes fix: 完善智能体配置历史与恢复逻辑	2026-07-13 15:47:08 +08:00
3030332422	176785830a	update：修改部分样式	2026-07-13 15:44:06 +08:00
Tyke Chen	d78ecfce6f	Merge remote-tracking branch 'origin/main' into agent-snapshot-history-fixes	2026-07-10 20:26:30 +08:00
Tyke Chen	179281e49c	fix: harden agent snapshot restore flow	2026-07-10 20:21:44 +08:00
hrzandGitHub	bc1aa1a089	Merge pull request #3267 from xinnan-tech/fix-agent-idor fix: prevent agent IDOR access	2026-07-10 17:36:00 +08:00
wengzhandGitHub	c5b64c3ef0	Merge pull request #3270 from xinnan-tech/fix-voiceprint-dialogue-bug fix：修改提示词与说话人注入逻辑，减少模型回答带着说话人信息频率	2026-07-10 15:55:58 +08:00
DaGou12138	2aa6c5ee49	fix： 1.优化context注入方式，合并为一个system，解决qwen本地部署模型多system异常400问题	2026-07-10 15:05:02 +08:00
Tyke Chen	687b6db96b	fix: resolve mobile type and lint errors	2026-07-10 11:45:16 +08:00
Tyke Chen	a5aee109fe	feat: improve agent snapshot history	2026-07-10 11:44:35 +08:00
hrzandGitHub	8ec5851027	Merge pull request #3273 from xinnan-tech/agent-delete-name-confirm feat: 删除智能体前需要用户进行确认	2026-07-10 10:39:47 +08:00
Tyke Chen	48d629c79c	fix: localize agent deletion success message	2026-07-10 10:18:48 +08:00
wengzh	14e57a1add	fix(powermem): 修复用户配置启用状态的类型判断问题将配置的启用值统一转为小写字符串后判断是否为true，避免非布尔类型配置导致的判断失效	2026-07-10 10:06:07 +08:00
hrzandGitHub	634967b2fe	Merge pull request #3274 from xinnan-tech/i18n-duplicate-check test: 增加 i18n 重复 key 检测	2026-07-10 09:59:33 +08:00
Tyke Chen	e648453c67	fix: rename i18n check command	2026-07-10 09:55:53 +08:00
Tyke Chen	d11cfc6923	Merge remote-tracking branch 'origin/main' into fix-agent-idor # Conflicts: # main/manager-api/src/main/java/xiaozhi/modules/agent/controller/AgentController.java # main/manager-api/src/main/java/xiaozhi/modules/agent/service/AgentService.java # main/manager-api/src/main/java/xiaozhi/modules/agent/service/impl/AgentServiceImpl.java	2026-07-09 20:21:37 +08:00
DaGou12138	32fbbf92fe	Merge branch 'refs/heads/main' into fix-voiceprint-dialogue-bug	2026-07-09 16:56:22 +08:00
wengzhandGitHub	bd981aac79	Merge pull request #3275 from xinnan-tech/py-audio-aec feat: 服务端AEC功能	2026-07-09 16:24:03 +08:00
Sakura-RanChenandGitHub	adee070bb0	Merge branch 'main' into py-audio-aec	2026-07-09 15:51:01 +08:00
wengzhandGitHub	03ec3bac3f	Merge pull request #3271 from xinnan-tech/py-fix-bug Py fix bug	2026-07-09 15:36:59 +08:00
Tyke Chen	af5fbb5282	test: add i18n duplicate key check	2026-07-09 15:25:36 +08:00
Tyke Chen	9301c1889f	feat: require agent name confirmation before delete	2026-07-09 15:03:12 +08:00
hrzandGitHub	ef2ed07c1c	Merge pull request #3266 from xinnan-tech/agent-snapshot-history Add agent configuration history	2026-07-09 14:54:27 +08:00
Tyke Chen	1e2c4c6a28	fix: 修复智能体快照基线与查看逻辑	2026-07-09 11:16:07 +08:00
Sakura-RanChen	a32500a6a4	fix: 消除死锁隐患	2026-07-09 10:29:41 +08:00
hrz	772af6c918	Merge branch 'agent-snapshot-history' of https://github.com/xinnan-tech/xiaozhi-esp32-server into agent-snapshot-history	2026-07-08 17:46:50 +08:00
hrz	2a917c1e62	update:对齐i18n文件行数	2026-07-08 17:44:10 +08:00
Tyke Chen	c32fbe69c5	Remove wakeup word audio asset	2026-07-08 16:33:36 +08:00
DaGou12138	3b6e8f0e4b	fix： 1.优化声纹称呼人提示词和注入逻辑，减少次次都称呼的频率	2026-07-08 16:14:10 +08:00
Tyke Chen	aae2ef2152	fix: prevent agent IDOR access	2026-07-08 15:52:47 +08:00
Tyke Chen	c82b351457	Fix agent snapshot history issues	2026-07-08 15:15:26 +08:00
DaGou12138	04c10ef225	fix： 1.修改提示词与说话人注入，减少模型每次回答都带着说话人信息	2026-07-08 14:12:16 +08:00
Sakura-RanChen	0b8bb728e2	同步方法进行包装避免阻塞	2026-07-08 11:47:04 +08:00
mie	35ec3ba803	Add agent configuration history	2026-07-07 17:49:34 +08:00
wengzhandGitHub	8808b69303	Merge pull request #3265 from xinnan-tech/ha-muisc-timeout Ha muisc timeout	2026-07-07 16:25:12 +08:00
Sakura-RanChen	fc573a72ea	fix: 修复设备时间戳上报逻辑	2026-07-07 15:50:27 +08:00
Sakura-RanChen	59f6566cfb	同步工具异步化处理	2026-07-07 14:45:50 +08:00
Sakura-RanChen	d8c97a9f81	fix: 修复携程死锁	2026-07-06 16:44:41 +08:00
Sakura-RanChen	3d204fb181	feat: 服务端AEC功能 ref: 入口解码为pcm音频数据，vad和asr可直接使用	2026-07-06 16:21:24 +08:00
hrzandGitHub	209fd3fbc8	Merge pull request #3260 from xinnan-tech/test-funasr FunASR识别指定语言	2026-07-06 13:56:48 +08:00
3030332422	bc0ffd1bd3	update：修改sql文件，删去测试文件	2026-07-01 15:02:26 +08:00
hrzandGitHub	f0d61442b8	Merge pull request #3259 from xinnan-tech/update-theme 顶部下拉菜单图标间距调整	2026-06-30 18:45:14 +08:00
CGDandGitHub	e6c2fac7ec	Merge pull request #3255 from LauraGPT/funasr-language-option fix: allow configuring FunASR recognition language	2026-06-30 14:57:31 +08:00
zhifu gao	5a9b5af441	fix: add FunASR language config migration	2026-06-30 14:07:16 +08:00
欣南科技andGitHub	16e5dc8c78	Merge pull request #3258 from xinnan-tech/update-version update:Bump to 0.9.5	2026-06-30 13:10:18 +08:00
hrz	f77970dd7d	update:Bump to 0.9.5	2026-06-30 13:10:26 +08:00
zhuoqinglian	af3ca4f609	update: 顶部下拉菜单图标间距调整	2026-06-30 09:47:28 +08:00
hrzandGitHub	1ebfcd1f13	Merge pull request #3256 from xinnan-tech/update-theme 解决智能体管理查询不展示的问题&删除知识库旧版废弃文件	2026-06-30 09:36:42 +08:00
zhuoqinglian	3ca322961e	fix: 解决智能体管理查询不展示的问题	2026-06-30 09:22:05 +08:00
zhuoqinglian	0eb0a600a7	update: 删除知识库旧版废弃文件	2026-06-30 09:19:26 +08:00
wengzhandGitHub	3ed06a9e34	Merge pull request #3244 from xinnan-tech/base_prompt-update feat: 将系统提示词指令逻辑英文化，中文样本保留	2026-06-30 09:06:10 +08:00
LauraGPT	2fae96d60c	fix: allow configuring FunASR recognition language	2026-06-29 20:58:51 +00:00
wengzhandGitHub	67dde7cc47	Merge pull request #3254 from xinnan-tech/update-theme 智能体管理搜索恢复查询历史功能	2026-06-29 16:58:52 +08:00
zhuoqinglian	efedc18f02	update: 智能体管理搜索恢复查询历史功能	2026-06-29 16:01:14 +08:00
zhuoqinglian	0270de1844	update: 滚动条样式抽离复用	2026-06-29 15:42:52 +08:00
wengzhandGitHub	06b0ff139b	Merge pull request #3247 from xinnan-tech/update-theme Update theme	2026-06-26 17:58:18 +08:00
zhuoqinglian	799ea28d82	Merge branch 'main' into update-theme	2026-06-26 17:30:15 +08:00
zhuoqinglian	5a68252d22	update: 更新所有页面背景颜色	2026-06-26 17:28:06 +08:00
zhuoqinglian	97404e53fe	update: 顶部导航栏搜索放到首页	2026-06-26 17:26:16 +08:00
zhuoqinglian	b052158cee	feat: 完成导航菜单组件样式优化	2026-06-26 17:10:49 +08:00
zhuoqinglian	979ef24b79	update: 音色克隆多语言配置	2026-06-26 15:32:48 +08:00
zhuoqinglian	0f4f0f01fd	update: 音色克隆页面展现形式修改	2026-06-26 14:45:23 +08:00
wengzhandGitHub	18e1de4f45	Merge pull request #3245 from xinnan-tech/py-add-minimax-voice Py add minimax voice	2026-06-26 11:42:59 +08:00
Sakura-RanChen	aa846a096f	名称长度调整	2026-06-26 11:41:46 +08:00
Sakura-RanChen	a679412230	增加试听音色	2026-06-26 11:40:52 +08:00
3030332422	cf3e14bb07	feat: 将系统提示词指令逻辑英文化，中文样本保留	2026-06-26 11:06:18 +08:00
wengzhandGitHub	3a73a17253	Merge pull request #3243 from xinnan-tech/py-add-minnimax-voice 调整minimax音色	2026-06-26 10:50:26 +08:00
Sakura-RanChen	3b27ebcd35	调整minimax音色	2026-06-26 10:29:07 +08:00
wengzhandGitHub	fa6074d284	Merge pull request #3242 from xinnan-tech/update-theme Update theme	2026-06-25 17:29:55 +08:00
zhuoqinglian	d809cfcb01	Merge branch 'main' into update-theme	2026-06-25 17:27:40 +08:00
zhuoqinglian	eb2c09bbdc	feat: 完成聊天记录、修改密码页面样式改造	2026-06-25 17:26:52 +08:00
zhuoqinglian	2cf8f79482	update: 模型配置新增、编辑弹窗样式优化	2026-06-25 17:09:29 +08:00
zhuoqinglian	1c94844bb9	feat: 完成声纹管理页面样式改造	2026-06-25 09:18:38 +08:00
wengzhandGitHub	0c53b8f543	Merge pull request #3240 from xinnan-tech/update-theme Update theme	2026-06-24 17:58:13 +08:00
zhuoqinglian	1518dfca30	feat: 完成设备管理页面样式改造	2026-06-24 17:37:37 +08:00
zhuoqinglian	7529c500a4	feat: 完成音色克隆页面样式改造	2026-06-24 11:43:36 +08:00
zhuoqinglian	b6ed220e48	feat: 完成音色资源页面样式改造	2026-06-23 17:23:11 +08:00
wengzhandGitHub	b152c5dc23	Merge pull request #3239 from xinnan-tech/update-theme 模型配置页面样式调整	2026-06-23 16:31:30 +08:00
zhuoqinglian	04bfddf457	update: 按钮样式风格统一	2026-06-23 14:54:45 +08:00
zhuoqinglian	9d78ea29c3	Merge branch 'main' into update-theme	2026-06-23 14:15:57 +08:00
zhuoqinglian	f82f364189	feat: 完成模型配置页面样式改造	2026-06-23 14:15:32 +08:00
zhuoqinglian	9705149b2b	feat: 按钮组件新增add类型	2026-06-23 14:14:29 +08:00
wengzhandGitHub	7986148013	Merge pull request #3238 from xinnan-tech/py-add-edge-config 补充edge相关配置	2026-06-23 10:40:40 +08:00
Sakura-RanChen	19f5cb5b4f	补充edge相关配置	2026-06-23 10:37:48 +08:00
zhuoqinglian	ea48b948bf	update: 模型配置新增弹窗样式调整	2026-06-22 17:58:35 +08:00
zhuoqinglian	3c5ca9f143	update: 模型配置编辑弹窗样式调整	2026-06-22 17:31:09 +08:00
wengzhandGitHub	da72ecaa1b	Merge pull request #3235 from xinnan-tech/py-fix-tts fix: 超时情况不与activate_session同一判断条件导致的监听任务未清除问题	2026-06-22 11:21:03 +08:00
Sakura-RanChen	f297e1b648	fix: 超时情况不与activate_session同一判断条件导致的监听任务未清除问题	2026-06-22 11:16:25 +08:00
wengzhandGitHub	a1973e07b7	Merge pull request #3227 from xinnan-tech/update-theme feat: 完成字典管理页面样式改造	2026-06-18 16:57:49 +08:00
zhuoqinglian	cd58b2c3cb	Merge branch 'main' into update-theme	2026-06-18 16:55:33 +08:00
zhuoqinglian	a5be67d04b	feat: 完成字典管理页面样式改造	2026-06-18 16:49:15 +08:00
wengzhandGitHub	e6dc6187c8	Merge pull request #3226 from xinnan-tech/update-theme 页面样式改造	2026-06-18 16:39:41 +08:00
zhuoqinglian	7f4011f9de	feat: 完成字段管理页面样式改造	2026-06-18 16:37:42 +08:00
zhuoqinglian	211cf891af	Merge branch 'main' into update-theme	2026-06-18 10:26:57 +08:00
zhuoqinglian	89a1229b53	feat: 完成服务端管理页面样式改造	2026-06-18 10:26:06 +08:00
wengzhandGitHub	071ed99a32	Merge pull request #3224 from xinnan-tech/py-fix-bug fix: 通讯录页面时间不显示	2026-06-17 14:36:48 +08:00
Sakura-RanChen	ea14be27e6	fix: 通讯录页面时间不显示 fix: listen消息相关状态处理	2026-06-17 14:34:42 +08:00
zhuoqinglian	a834f163b7	feat: 完成替换词页面样式改造	2026-06-17 14:20:48 +08:00
zhuoqinglian	7849e6b030	update: 模板保存添加必填校验	2026-06-17 10:36:02 +08:00
wengzhandGitHub	0d869baaa0	Merge pull request #3223 from xinnan-tech/update-theme 页面样式调整	2026-06-16 17:01:10 +08:00
zhuoqinglian	164eb5481c	feat: 完成默认角色管理页面样式改造，并添加编辑保存弹窗	2026-06-16 16:58:44 +08:00
zhuoqinglian	969ee3cb12	feat: 完成字段管理页面样式改造	2026-06-16 16:18:12 +08:00
zhuoqinglian	ee54d87383	feat: 完成固件管理页面样式改造	2026-06-16 14:55:08 +08:00
wengzhandGitHub	849026c015	Merge pull request #3222 from xinnan-tech/update-theme Update theme	2026-06-16 10:42:24 +08:00
zhuoqinglian	e5bb3e7791	update: 优化表格组件，增加代码的复用性	2026-06-16 10:40:44 +08:00
zhuoqinglian	1ffc40e71d	feat: 完成用户管理页面样式改造	2026-06-16 10:39:52 +08:00
zhuoqinglian	45fd850757	update: 表格组件添加阴影效果	2026-06-16 09:46:25 +08:00
zhuoqinglian	8a5dac181e	update: 知识库顶部标题合并	2026-06-15 17:37:53 +08:00
zhuoqinglian	ecf20300ff	update: 通讯录初始化加载默认选中第一项	2026-06-15 17:16:50 +08:00
zhuoqinglian	74def844f0	Merge branch 'main' into update-theme	2026-06-15 17:05:28 +08:00
zhuoqinglian	a5a9bd1abe	fix: 修复element组件多语言切换不生效的问题	2026-06-15 17:05:04 +08:00
zhuoqinglian	2d9b915d51	feat: 完成参数管理页面改造	2026-06-15 15:44:09 +08:00
hrzandGitHub	5f87fc8361	Merge pull request #3204 from xinnan-tech/py-fix-calling 优化相关逻辑	2026-06-15 14:06:51 +08:00
zhuoqinglian	6859fdc90e	update: 系统功能配置图标大小优化	2026-06-15 11:27:12 +08:00
zhuoqinglian	b8ae0568e9	update: 系统功能配置页面适配调整	2026-06-15 11:23:31 +08:00
wengzhandGitHub	1dc6f143f3	Merge pull request #3219 from xinnan-tech/update-theme 完成系统功能页面样式改造	2026-06-12 14:43:23 +08:00
zhuoqinglian	67532dc230	update: 系统功能配置完善多语言	2026-06-12 14:23:25 +08:00
zhuoqinglian	b2876def99	Merge branch 'main' into update-theme	2026-06-12 14:14:59 +08:00
zhuoqinglian	0c73a8b6a4	feat: 完成系统功能页面样式改造	2026-06-12 14:13:21 +08:00
zhuoqinglian	c857a3164d	feat: 完成按钮组件抽离	2026-06-12 11:49:22 +08:00
hrzandGitHub	a964192eb0	Merge pull request #3213 from xinnan-tech/fix-knowledge-base-ragflow-bug #3212 修复知识库RAGFlow相关逻辑BUG	2026-06-12 11:15:35 +08:00
DaGou12138	32da03818e	#3212 fix： 1.修改知识库前端卡片提示样式，优化警示效果	2026-06-12 10:35:40 +08:00
DaGou12138	7f17e3e08e	Merge branch 'refs/heads/main' into fix-knowledge-base-ragflow-bug	2026-06-12 10:29:17 +08:00
DaGou12138	c237e1f323	Merge remote-tracking branch 'origin/fix-knowledge-base-ragflow-bug' into fix-knowledge-base-ragflow-bug	2026-06-12 09:51:03 +08:00
DaGou12138	087a202e31	#3212 fix： 1.优化知识库连接RAGFlow异常提示，修改前端卡片提示样式	2026-06-12 09:50:01 +08:00
hrz	4b1460d938	update:调整同步数据集错误日志的级别	2026-06-11 19:10:21 +08:00
hrz	f2aec524d2	del:无用类	2026-06-11 18:57:30 +08:00
wengzhandGitHub	1a97ca137c	Merge pull request #3215 from xinnan-tech/update-theme Update theme	2026-06-11 17:45:58 +08:00
zhuoqinglian	2b6f457ae6	update: 知识库页面间距优化	2026-06-11 17:44:17 +08:00
DaGou12138	3f4e0b4aa0	#3212 fix： 1.修复RAGFlow连接异常导致级联删除问题 2.修复RAGFlow获取数量逻辑问题 3.远程失败不再删除本地影子记录，避免产生RAGFlow端孤儿文档 4.优化前端提示语	2026-06-11 17:17:59 +08:00
DaGou12138	e30ded4de9	fix：删除知识库rag相关非必要实体	2026-06-11 16:08:17 +08:00
hrzandGitHub	07242a84ff	Merge pull request #3210 from xinnan-tech/fix-knowledge-base-web-bug fix：修复知识库模块弹框组件样式全局覆盖导致显示异常问题	2026-06-10 15:32:08 +08:00
DaGou12138	a2074dc0d8	fix：修复知识库模块弹框组件样式全局覆盖导致显示异常问题	2026-06-10 15:00:29 +08:00
zhuoqinglian	28b6c85650	fix: 修复弹窗展示位置异常的问题	2026-06-10 10:47:52 +08:00
wengzhandGitHub	af300138eb	Merge pull request #3209 from xinnan-tech/update-theme Update theme	2026-06-09 17:24:16 +08:00
zhuoqinglian	2bf5725048	update: 知识库页面复用弹窗、分页组件，同步修改样式	2026-06-09 17:22:18 +08:00
hrzandGitHub	3d73141788	Merge pull request #3206 from xinnan-tech/web_search-Document docs:新增联网搜索插件配置文档	2026-06-09 17:12:16 +08:00
hrz	945ab29bc3	add:增加联网搜索的教程和自编译docker镜像的教程	2026-06-09 17:11:35 +08:00
zhuoqinglian	fe0f7dcf75	feat: 完成分页组件抽离	2026-06-09 15:05:16 +08:00
zhuoqinglian	1a3ffbc8e2	feat: 完成弹窗组件抽离	2026-06-09 14:25:49 +08:00
3030332422	71278b1898	docs:新增联网搜索插件配置文档	2026-06-08 11:38:11 +08:00
zhuoqinglian	0173c7abe1	update: 知识库样式优化、添加多语言配置	2026-06-05 17:37:21 +08:00
zhuoqinglian	8a50eea4ce	update: 知识库整体页面样式调整	2026-06-03 16:49:08 +08:00
Sakura-RanChen	b9891bb795	优化相关逻辑	2026-06-03 16:13:03 +08:00
wengzhandGitHub	b903a88cd5	Merge pull request #3203 from xinnan-tech/mac-address-mask feat: mac地址添加马赛克功能	2026-06-03 14:41:34 +08:00
zhuoqinglian	f3fcf2fedf	feat: mac地址添加马赛克功能	2026-06-03 14:40:01 +08:00
欣南科技andGitHub	a825f0874c	Merge pull request #3202 from xinnan-tech/update-doc-video update:更新演示视频	2026-06-03 13:58:14 +08:00
hrz	8a5ca46418	update:更新演示视频	2026-06-03 13:56:34 +08:00