TTS 用例说明里的名字改成真存在的

说明里写的那个用例名仓库里没有，改成实际跑的那条。
三条 LLM 用例改成查请求体
2026-10-24 08:06:12 +00:00 · 2026-10-24 08:06:12 +00:00 · 2026-10-24 08:06:12 +00:00 · 2026-10-24 07:31:19 +00:00 · 2026-10-24 07:27:15 +00:00 · 2026-10-24 07:27:06 +00:00
50 changed files with 2330 additions and 223 deletions
@@ -20,24 +20,58 @@ jobs:
          python-version: '3.10'
          cache: 'pip'
          cache-dependency-path: 'main/xiaozhi-server/requirements.txt'
+      - name: Install system dependencies
+        run: |
+          # opuslib_next 是 ctypes 绑定，pip 装上的是纯 Python 包，真正的编解码
+          # 靠系统里的 libopus.so。runner 上默认没有，import 会失败，音频相关的
+          # 用例直接报错。正式镜像 Dockerfile-server-base 里也是装 libopus0 的
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends libopus0
      - name: Install dependencies
        working-directory: main/xiaozhi-server
        run: |
          pip install -r requirements.txt
          pip install pytest pytest-asyncio freezegun
-      - name: Run smoke test
+      - name: Prepare test config
        working-directory: main/xiaozhi-server
        run: |
-          if [ -f tests/test_smoke.py ]; then
-            pytest tests/test_smoke.py -x -q
-          else
-            echo "::warning::Slice 2 not done yet — tests/test_smoke.py missing"
-            exit 0
-          fi
+          # config/settings.py 在 import 期就要这个文件，缺了整套用例连收集都过不去。
+          # data/ 在 .gitignore 里，只能由这一步现造
+          mkdir -p data
+          printf '{}\n' > data/.config.yaml
+      - name: Run tests
+        working-directory: main/xiaozhi-server
+        run: |
+          # 要真凭据/真网络的用例由 tests/conftest.py 按 live_api 标记统一剔除，
+          # 剔掉的是哪几条会打在日志里
+          pytest tests/ -v

  java:
    name: Java (manager-api)
    runs-on: ubuntu-latest
+    # 三个 @SpringBootTest 要真连 MySQL 和 Redis，空库即可，Liquibase 会自己建表
+    services:
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: 123456
+          MYSQL_DATABASE: xiaozhi_esp32_server
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd="mysqladmin ping -h 127.0.0.1 -uroot -p123456"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=20
+      redis:
+        image: redis:8.0
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd="redis-cli ping"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=20
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
@@ -47,7 +81,12 @@ jobs:
          cache: 'maven'
      - name: Run tests
        working-directory: main/manager-api
-        run: mvn -B -q test -DfailIfNoTests=false
+        run: mvn -B test -DskipTests=false -DfailIfNoTests=false
+      - name: Check the integration tests really ran
+        working-directory: main/manager-api
+        # 守卫在依赖不齐时会把整类集成测试跳过，这里盯一下它们有没有真跑，
+        # 免得门禁被悄悄掏空
+        run: bash scripts/check-integration-tests.sh

  web:
    name: Vue (manager-web)
@@ -63,4 +102,6 @@ jobs:
        working-directory: main/manager-web
        run: |
          npm ci --no-audit --no-fund
+          npm run test:contract
          npm run test:unit
+          npm run build
@@ -16,3 +16,28 @@ Vue 3.x
 # 接口文档
 启动后打开：http://localhost:8002/xiaozhi/doc.html

+# 跑测试
+测试分两种：纯单元测试，和要真连 MySQL、Redis 的集成测试（`DeviceTest`、`loginControllerTest`、`ModelConfigPersistenceTest`）。
+
+集成测试需要先起好 MySQL 8 和 Redis 8。没起的时候这类测试整类跳过，不会让构建变红，日志里会写明缺的是哪个依赖。CI 上不一样：依赖连不上就直接让构建失败，不许跳过，免得门禁被悄悄掏空。
+
+本地用 Docker 起这两个依赖：
+
+```bash
+docker run -d --name xiaozhi-mysql -p 3306:3306 \
+  -e MYSQL_ROOT_PASSWORD=123456 -e MYSQL_DATABASE=xiaozhi_esp32_server mysql:8.0
+docker run -d --name xiaozhi-redis -p 6379:6379 redis:8.0
+```
+
+跑全部测试：
+
+```bash
+mvn -B test -DskipTests=false
+```
+
+只想编译、不跑测试：
+
+```bash
+mvn -B package -DskipTests=true
+```
+
@@ -32,7 +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>
+        <skipTests>false</skipTests>
        <argLine></argLine>
    </properties>

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# 检查那几个要连 MySQL 和 Redis 的集成测试是不是真的跑了。
+# 守卫要是哪天手滑把它们全跳过了，CI 必须红，不能安安静静少跑一半门禁。
+set -uo pipefail
+
+REPORT_DIR="${1:-target/surefire-reports}"
+
+WATCHED=(
+  "xiaozhi.modules.device.DeviceTest"
+  "xiaozhi.modules.model.service.impl.ModelConfigPersistenceTest"
+  "xiaozhi.modules.sys.loginControllerTest"
+)
+
+if [ ! -d "$REPORT_DIR" ]; then
+  echo "找不到测试报告目录：$REPORT_DIR"
+  exit 1
+fi
+
+missing=()
+for class in "${WATCHED[@]}"; do
+  count=0
+  for report in "$REPORT_DIR"/TEST-*.xml; do
+    [ -e "$report" ] || continue
+    name=$(sed -n 's/.*<testsuite[^>]*name="\([^"]*\)".*/\1/p' "$report" | head -1)
+    if [ "$name" = "$class" ]; then
+      count=$(sed -n 's/.*<testsuite[^>]*tests="\([0-9]*\)".*/\1/p' "$report" | head -1)
+      count=${count:-0}
+      break
+    fi
+  done
+  if [ "$count" -eq 0 ]; then
+    missing+=("$class")
+  else
+    echo "OK  $class 跑了 $count 条"
+  fi
+done
+
+if [ ${#missing[@]} -ne 0 ]; then
+  echo "这几个集成测试一条都没跑：${missing[*]}"
+  echo "守卫把门禁掏空了，构建必须失败"
+  exit 1
+fi
+
+echo "集成测试都跑过了"
@@ -324,7 +324,7 @@ public interface Constant {
    /**
     * 版本号
     */
-    public static final String VERSION = "0.9.7";
+    public static final String VERSION = "0.9.8";

    /**
     * 无效固件URL
@@ -19,8 +19,6 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;

-import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
-
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;
@@ -44,7 +42,6 @@ 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.entity.AgentTemplateEntity;
 import xiaozhi.modules.agent.dto.AgentTagDTO;
 import xiaozhi.modules.agent.entity.AgentTagEntity;
 import xiaozhi.modules.agent.service.AgentTagService;
@@ -52,7 +49,6 @@ import xiaozhi.modules.agent.service.AgentChatAudioService;
 import xiaozhi.modules.agent.service.AgentChatHistoryService;
 import xiaozhi.modules.agent.service.AgentChatSummaryService;
 import xiaozhi.modules.agent.service.AgentService;
-import xiaozhi.modules.agent.service.AgentTemplateService;
 import xiaozhi.modules.agent.vo.AgentChatHistoryUserVO;
 import xiaozhi.modules.agent.vo.AgentInfoVO;
 import xiaozhi.modules.security.user.SecurityUser;
@@ -65,7 +61,6 @@ public class AgentController {
    private static final long AUDIO_PLAY_TOKEN_EXPIRE_SECONDS = 300L;

    private final AgentService agentService;
-    private final AgentTemplateService agentTemplateService;
    private final AgentChatHistoryService agentChatHistoryService;
    private final AgentChatAudioService agentChatAudioService;
    private final AgentChatSummaryService agentChatSummaryService;
@@ -192,15 +187,6 @@ public class AgentController {
        return new Result<>();
    }

-    @GetMapping("/template")
-    @Operation(summary = "智能体模板模板列表")
-    @RequiresPermissions("sys:role:normal")
-    public Result<List<AgentTemplateEntity>> templateList() {
-        List<AgentTemplateEntity> list = agentTemplateService
-                .list(new QueryWrapper<AgentTemplateEntity>().orderByAsc("sort"));
-        return new Result<List<AgentTemplateEntity>>().ok(list);
-    }
-
    @GetMapping("/{id}/sessions")
    @Operation(summary = "获取智能体会话列表")
    @RequiresPermissions("sys:role:normal")
@@ -41,6 +41,17 @@ public class AgentTemplateController {
    
    private final AgentTemplateService agentTemplateService;
    
+    // 单独用 normal 权限（而非类级 superAdmin）是有意保留：
+    // 普通用户也需查询可用模板，与 /page 的管理入口分离，保持原行为契约。
+    @GetMapping
+    @Operation(summary = "智能体模板列表")
+    @RequiresPermissions("sys:role:normal")
+    public Result<List<AgentTemplateEntity>> getAgentTemplates() {
+        List<AgentTemplateEntity> list = agentTemplateService
+                .list(new QueryWrapper<AgentTemplateEntity>().orderByAsc("sort"));
+        return new Result<List<AgentTemplateEntity>>().ok(list);
+    }
+
    @GetMapping("/page")
    @Operation(summary = "获取模板分页列表")
    @RequiresPermissions("sys:role:superAdmin")
@@ -174,6 +174,9 @@ public class DeviceController {
    @Operation(summary = "获取设备通讯录")
    @RequiresPermissions("sys:role:normal")
    public Result<Object> getAddressBook(@PathVariable String macAddress) {
+        if (deviceService.getOwnedDeviceByMacAddress(macAddress) == null) {
+            return new Result<Object>().error(ErrorCode.DEVICE_NOT_EXIST);
+        }
        return new Result<Object>().ok(deviceAddressBookService.getAddressBookList(macAddress));
    }

@@ -192,9 +195,7 @@ public class DeviceController {
    @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())) {
+        if (deviceService.getOwnedDeviceByMacAddress(dto.getMacAddress()) == null) {
            return new Result<Void>().error("无权限操作该设备");
        }
        deviceAddressBookService.saveOrUpdate(dto.getMacAddress(), dto.getTargetMac(), dto.getAlias(), null);
@@ -205,9 +206,7 @@ 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())) {
+        if (deviceService.getOwnedDeviceByMacAddress(dto.getMacAddress()) == null) {
            return new Result<Void>().error("无权限操作该设备");
        }
        deviceAddressBookService.saveOrUpdate(dto.getMacAddress(), dto.getTargetMac(), null, dto.getHasPermission());
@@ -83,6 +83,16 @@ public interface DeviceService extends BaseService<DeviceEntity> {
     */
    DeviceEntity getDeviceByMacAddress(String macAddress);

+    /**
+     * 根据MAC地址获取当前登录用户名下的设备信息
+     * <p>
+     * 设备不存在或不属于当前用户时返回null，调用方无需再自行比对归属。
+     *
+     * @param macAddress MAC地址
+     * @return 当前用户名下的设备信息，不存在或无权限时返回null
+     */
+    DeviceEntity getOwnedDeviceByMacAddress(String macAddress);
+
    /**
     * 根据设备ID获取激活码
     * 
@@ -1,9 +1,13 @@
 package xiaozhi.modules.device.service.impl;

 import java.time.Instant;
+import java.util.ArrayList;
+import java.util.Comparator;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.stream.Collectors;

 import org.apache.commons.lang3.StringUtils;
@@ -18,6 +22,7 @@ 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.entity.DeviceEntity;
 import xiaozhi.modules.device.service.DeviceAddressBookService;
 import xiaozhi.modules.device.service.DeviceService;
 import xiaozhi.modules.sys.service.SysParamsService;
@@ -40,7 +45,11 @@ public class DeviceAddressBookServiceImpl implements DeviceAddressBookService {

    @Override
    public List<DeviceAddressBookEntity> getAddressBookList(String macAddress) {
-        return deviceAddressBookDao.getAddressBookList(macAddress);
+        List<DeviceAddressBookEntity> rows = assignUniqueAliases(deviceAddressBookDao.getAddressBookList(macAddress));
+        // 取名按固定顺序算完了，前端要看的是最近改过的排前面，放回去
+        rows.sort(Comparator
+                .comparing(DeviceAddressBookEntity::getUpdateDate, Comparator.nullsLast(Comparator.reverseOrder())));
+        return rows;
    }

    @Override
@@ -63,7 +72,7 @@ public class DeviceAddressBookServiceImpl implements DeviceAddressBookService {
        }

        // 主动呼叫模式
-        Map<String, String> callerBook = allBooks.get(callerMac.toLowerCase());
+        Map<String, String> callerBook = allBooks.get(bookKey(callerMac));
        if (callerBook == null) {
            return errorResult("未找到备注为'" + nickname + "'的设备");
        }
@@ -80,13 +89,16 @@ public class DeviceAddressBookServiceImpl implements DeviceAddressBookService {
        }

        // 获取目标设备如何称呼主叫方
-        Map<String, String> targetBook = allBooks.get(targetMac.toLowerCase());
+        Map<String, String> targetBook = allBooks.get(bookKey(targetMac));
        String callerNickname = null;
        if (targetBook != null) {
-            callerNickname = targetBook.get(callerMac.toLowerCase());
+            callerNickname = targetBook.get(bookKey(callerMac));
        }
        if (StringUtils.isBlank(callerNickname)) {
-            callerNickname = deviceService.getDeviceByMacAddress(callerMac).getAlias();
+            DeviceEntity callerDevice = deviceService.getDeviceByMacAddress(callerMac);
+            if (callerDevice != null) {
+                callerNickname = callerDevice.getAlias();
+            }
            if (StringUtils.isBlank(callerNickname)) {
                callerNickname = formatMacAsDeviceName(callerMac);
            }
@@ -100,32 +112,26 @@ public class DeviceAddressBookServiceImpl implements DeviceAddressBookService {
    @Override
    public void refreshCache() {
        Map<String, Map<String, String>> result = new HashMap<>();
-        List<DeviceAddressBookEntity> allRecords = deviceAddressBookDao.selectList(null);
+        List<DeviceAddressBookEntity> allRecords = assignUniqueAliases(deviceAddressBookDao.selectList(null));
        Map<String, String> reverseMap = new HashMap<>();

        for (DeviceAddressBookEntity entity : allRecords) {
-            String macA = entity.getMacAddress().toLowerCase();
-            String macB = entity.getTargetMac().toLowerCase();
-            String alias = entity.getAlias();
-            Boolean hasPermission = entity.getHasPermission();
+            String macA = bookKey(entity.getMacAddress());
+            String macB = bookKey(entity.getTargetMac());

            // 构建正向映射: 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);
-            }
+            Map<String, String> book = result.computeIfAbsent(macA, k -> new HashMap<>());
+            String permStr = (Boolean.TRUE.equals(entity.getHasPermission())) ? "1" : "0";
+            book.put(entity.getAlias(), macB + "|" + permStr);

-            // 构建反向记录用于查找B对A的称呼
-            if (alias != null && !alias.isEmpty()) {
-                reverseMap.put(macB + ":" + macA, alias);
-            }
+            // 构建反向记录用于查找B对A的称呼，用同一个去重后的名字，两边才对得上
+            reverseMap.put(macB + ":" + macA, entity.getAlias());
        }

        // 构建反向映射: B对A的映射 macA -> nickname
        for (DeviceAddressBookEntity entity : allRecords) {
-            String macA = entity.getMacAddress().toLowerCase();
-            String macB = entity.getTargetMac().toLowerCase();
+            String macA = bookKey(entity.getMacAddress());
+            String macB = bookKey(entity.getTargetMac());
            String aliasBtoA = reverseMap.get(macA + ":" + macB);
            if (aliasBtoA != null && !aliasBtoA.isEmpty()) {
                result.computeIfAbsent(macB, k -> new HashMap<>());
@@ -136,6 +142,54 @@ public class DeviceAddressBookServiceImpl implements DeviceAddressBookService {
        redisUtils.set(RedisKeys.getAddressBookKey(), result);
    }

+    /**
+     * 给每行算出一个不重名的称呼，返回排好序、alias 已写好的新列表
+     *
+     * 昵称在同一个人的通讯录里是索引，同名后写的会盖掉先写的，按昵称呼会呼错设备。
+     * 库里本来就有重名：空别名补出来的尾号称呼只有 256 种取值，一本通讯录十几条
+     * 没起名就撞上了。所以显示和呼叫都得走这一份，
+     * 不然前端看到的字和呼叫时用的名字对不上，用户照着点的名字呼不到人。
+     * 不改传入的那个列表：它是 DAO 刚查出来的，调用方还要按自己的顺序用
+     */
+    private List<DeviceAddressBookEntity> assignUniqueAliases(List<DeviceAddressBookEntity> rows) {
+        // 取名要靠先后定谁拿原名，而 selectList 不带 order by，返回顺序不保证。
+        // 排一次，同样的数据每次算出来的结果一样，缓存不会来回变。
+        // 按归一后的地址排：同一个人不管库里是哪种写法都排到一起，
+        // 后面两级比较器再分先后。同一本里 target_mac 不会重复（主键摆着），
+        // 所以顺序还是由这三个键定死的，不会掉回"跟着数据库返回顺序走"
+        List<DeviceAddressBookEntity> ordered = new ArrayList<>(rows);
+        ordered.sort(Comparator
+                .comparing((DeviceAddressBookEntity row) -> bookKey(row.getMacAddress()),
+                        Comparator.nullsFirst(Comparator.naturalOrder()))
+                // 权限排在地址前面：撞名时让对方准许呼我的那台先拿原名。
+                // 排在后面等于不起作用，两条地址不同时谁先谁后是地址定的，
+                // 没权限那条照样占住原名，用户照前端看到的名字呼叫命中的就是它，
+                // 界面上只会说没权限，怎么点都不通
+                .thenComparing(DeviceAddressBookEntity::getHasPermission,
+                        Comparator.nullsLast(Comparator.reverseOrder()))
+                .thenComparing(DeviceAddressBookEntity::getTargetMac, Comparator.nullsFirst(Comparator.naturalOrder())));
+
+        Map<String, Set<String>> takenByOwner = new HashMap<>();
+        for (DeviceAddressBookEntity row : ordered) {
+            // 建表时 alias 默认是空的，用户没起名就是空的，这是默认状态不是异常。
+            // 补个尾号称呼顶上，整条跳过的话接口照样返回成功，对方却再也呼不过来
+            String alias = StringUtils.isBlank(row.getAlias())
+                    ? formatMacAsDeviceName(row.getTargetMac())
+                    : row.getAlias();
+
+            // 加后缀的写法跟 generateUniqueAlias 保持一致，不搞两套命名规则
+            Set<String> taken = takenByOwner.computeIfAbsent(bookKey(row.getMacAddress()), k -> new HashSet<>());
+            String uniqueAlias = alias;
+            int suffix = 1;
+            while (taken.contains(uniqueAlias)) {
+                uniqueAlias = alias + suffix++;
+            }
+            taken.add(uniqueAlias);
+            row.setAlias(uniqueAlias);
+        }
+        return ordered;
+    }
+
    @Override
    public void updateAlias(String macAddress, String targetMac, String alias) {
        String finalAlias = generateUniqueAlias(macAddress, targetMac, alias);
@@ -154,14 +208,22 @@ 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();
+                DeviceEntity targetDevice = deviceService.getDeviceByMacAddress(targetMac);
+                if (targetDevice != null) {
+                    alias = targetDevice.getAlias();
+                }
+                // 设备登记了但用户没起过名，alias 建表就是 null，这是默认状态
+                // 不是异常。这时候落个 null 进去，缓存刷新会把整条跳过，
+                // 接口照样返回成功，对方却永远呼不过来
+                if (StringUtils.isBlank(alias)) {
+                    alias = formatMacAsDeviceName(targetMac);
+                }
            }
            // 检查重名
            alias = generateUniqueAlias(macAddress, targetMac, alias);
@@ -229,11 +291,27 @@ public class DeviceAddressBookServiceImpl implements DeviceAddressBookService {
        }
    }

+    /**
+     * 通讯录里当主人用的地址键
+     *
+     * <p>
+     * 写缓存、查缓存、算称呼都靠它分组，三处必须是同一个值。少归一一次，同一个人的两行
+     * 会被当成两个人：各自拿到同名，写进同一本时后者盖掉前者，一台设备直接从缓存里消失。
+     * 库里确实能出现这种数据——表是 utf8mb4_0900_ai_ci，主键 (mac_address, target_mac)
+     * 大小写不敏感，owner 只差大小写而 target 不同的话两行不撞
+     */
+    private static String bookKey(String macAddress) {
+        return macAddress == null ? null : macAddress.toLowerCase();
+    }
+
    private String formatMacAsDeviceName(String mac) {
        if (StringUtils.isBlank(mac) || mac.length() < 2) {
            return mac;
        }
-        String lastTwo = mac.substring(mac.length() - 2);
+        // MAC 本身不区分大小写，落库、查库走的都是小写化的值。
+        // 这里跟着小写化，不跟着的话同一个地址在两条路径上会算出两个称呼，
+        // 数据搬到智控台上看到的名字就叫不到人了
+        String lastTwo = mac.substring(mac.length() - 2).toLowerCase();
        return "尾号为" + lastTwo + "的设备";
    }

@@ -316,6 +316,12 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
        if (device == null) {
            return;
        }
+        // 后面删通讯录那步是按 mac_address 删的，不看 user_id。
+        // 设备本身因为带了 user_id 条件删不掉，通讯录却会照删不误，
+        // 任意登录用户知道对方的设备 id 就能把对方整本通讯录清空
+        if (userId == null || device.getUserId() == null || !device.getUserId().equals(userId)) {
+            return;
+        }
        String macAddress = device.getMacAddress();
        if (StringUtils.isNotBlank(device.getAgentId())) {
            // 清除智能体设备数量缓存
@@ -400,6 +406,29 @@ public class DeviceServiceImpl extends BaseServiceImpl<DeviceDao, DeviceEntity>
        return baseDao.selectOne(wrapper);
    }

+    @Override
+    public DeviceEntity getOwnedDeviceByMacAddress(String macAddress) {
+        if (StringUtils.isBlank(macAddress)) {
+            return null;
+        }
+        // 同一 MAC 可能有两行只差大小写，selectOne 会抛 TooManyResultsException
+        // 把整个读通讯录接口带崩。按 id 取第一条做归属校验，撞行不报错
+        QueryWrapper<DeviceEntity> wrapper = new QueryWrapper<>();
+        wrapper.eq("mac_address", macAddress).orderByAsc("id");
+        List<DeviceEntity> devices = baseDao.selectList(wrapper);
+        if (devices == null || devices.isEmpty()) {
+            return null;
+        }
+        DeviceEntity device = devices.get(0);
+        UserDetail user = SecurityUser.getUser();
+        // getUser() 在取不到 subject、principal 时返回的是空对象，不是 null，
+        // 所以这里不会拿到 null。匿名调用走的就是空对象那一条，id 是空的，比不上
+        if (device.getUserId() == null || !device.getUserId().equals(user.getId())) {
+            return null;
+        }
+        return device;
+    }
+
    private DeviceReportRespDTO.ServerTime buildServerTime() {
        DeviceReportRespDTO.ServerTime serverTime = new DeviceReportRespDTO.ServerTime();
        TimeZone tz = TimeZone.getDefault();
@@ -110,8 +110,8 @@ public class ModelConfigServiceImpl extends BaseServiceImpl<ModelConfigDao, Mode
        // 1. 参数验证
        validateEditParameters(modelType, provideCode, id, modelConfigBodyDTO);

-        // 2. 验证模型提供者
-        validateModelProvider(modelType, provideCode);
+        // 2. 验证模型提供者，使用注册类型的大小写
+        String registeredModelType = resolveModelType(modelType, provideCode);

        // 3. 获取原始配置（不经过敏感数据处理）
        ModelConfigEntity originalEntity = getOriginalConfigFromDb(id);
@@ -120,7 +120,7 @@ public class ModelConfigServiceImpl extends BaseServiceImpl<ModelConfigDao, Mode
        validateLlmConfiguration(modelConfigBodyDTO);

        // 5. 准备更新实体并处理敏感数据
-        ModelConfigEntity modelConfigEntity = prepareUpdateEntity(modelConfigBodyDTO, originalEntity, modelType, id);
+        ModelConfigEntity modelConfigEntity = prepareUpdateEntity(modelConfigBodyDTO, originalEntity, registeredModelType, id);

        // 6. 执行数据库更新
        modelConfigDao.updateById(modelConfigEntity);
@@ -136,9 +136,9 @@ public class ModelConfigServiceImpl extends BaseServiceImpl<ModelConfigDao, Mode
    public ModelConfigDTO add(String modelType, String provideCode, ModelConfigBodyDTO modelConfigBodyDTO) {
        validateAddParameters(modelType, provideCode, modelConfigBodyDTO);

-        validateModelProvider(modelType, provideCode);
+        String registeredModelType = resolveModelType(modelType, provideCode);

-        ModelConfigEntity modelConfigEntity = prepareAddEntity(modelConfigBodyDTO, modelType);
+        ModelConfigEntity modelConfigEntity = prepareAddEntity(modelConfigBodyDTO, registeredModelType);

        modelConfigDao.insert(modelConfigEntity);

@@ -283,13 +283,14 @@ public class ModelConfigServiceImpl extends BaseServiceImpl<ModelConfigDao, Mode
    }

    /**
-     * 验证模型提供者
+     * 验证模型提供者并获取注册类型，保留 TTS、Memory、Intent 等类型的大小写
     */
-    private void validateModelProvider(String modelType, String provideCode) {
+    private String resolveModelType(String modelType, String provideCode) {
        List<ModelProviderDTO> providerList = modelProviderService.getList(modelType, provideCode);
        if (CollectionUtil.isEmpty(providerList)) {
            throw new RenException(ErrorCode.MODEL_PROVIDER_NOT_EXIST);
        }
+        return providerList.get(0).getModelType();
    }

    /**
@@ -86,6 +86,7 @@ public class ShiroConfig {
        filterMap.put("/user/captcha", "anon");
        filterMap.put("/user/smsVerification", "anon");
        filterMap.put("/user/login", "anon");
+        filterMap.put("/user/refresh", "anon");
        filterMap.put("/user/pub-config", "anon");
        filterMap.put("/user/register", "anon");
        filterMap.put("/user/retrieve-password", "anon");
@@ -16,6 +16,7 @@ import org.springframework.web.bind.annotation.RestController;

 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
 import lombok.AllArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -110,6 +111,17 @@ public class LoginController {
        return sysUserTokenService.createToken(userDTO.getId());
    }

+    @PostMapping("/refresh")
+    @Operation(summary = "刷新token：用旧token换新token")
+    public Result<TokenDTO> refresh(HttpServletRequest request) {
+        String authorization = request.getHeader(Constant.AUTHORIZATION);
+        if (StringUtils.isBlank(authorization) || !authorization.startsWith("Bearer ")) {
+            throw new RenException(ErrorCode.UNAUTHORIZED);
+        }
+        String oldToken = authorization.replace("Bearer ", "");
+        return sysUserTokenService.refreshToken(oldToken);
+    }
+
    @PostMapping("/register")
    @Operation(summary = "注册")
    public Result<Void> register(@RequestBody LoginDTO login) {
@@ -21,4 +21,14 @@ public interface SysUserTokenDao extends BaseDao<SysUserTokenEntity> {
    SysUserTokenEntity getByUserId(Long userId);

    void logout(@Param("userId") Long userId, @Param("expireDate") Date expireDate);
+
+    /**
+     * 用旧 token 换新 token 的 CAS 更新：仅当旧 token 未过期且属于指定 user 时才覆盖。
+     * 返回受影响行数（0 表示条件不满足 = token 已被并发刷新或过期）。
+     */
+    int refreshTokenCAS(@Param("userId") Long userId,
+            @Param("oldToken") String oldToken,
+            @Param("newToken") String newToken,
+            @Param("newExpire") Date newExpire,
+            @Param("updateDate") Date updateDate);
 }
@@ -21,6 +21,13 @@ public interface SysUserTokenService extends BaseService<SysUserTokenEntity> {
     */
    Result<TokenDTO> createToken(Long userId);

+    /**
+     * 用旧token换新token，旧token立即失效
+     *
+     * @param oldToken 旧token字符串
+     */
+    Result<TokenDTO> refreshToken(String oldToken);
+
    SysUserDTO getUserByToken(String token);

    /**
@@ -2,7 +2,9 @@ package xiaozhi.modules.security.service.impl;

 import java.util.Date;

+import org.apache.commons.lang3.StringUtils;
 import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;

 import cn.hutool.core.date.DateUtil;
 import lombok.AllArgsConstructor;
@@ -81,6 +83,36 @@ public class SysUserTokenServiceImpl extends BaseServiceImpl<SysUserTokenDao, Sy
        return new Result<TokenDTO>().ok(tokenDTO);
    }

+    @Override
+    @Transactional
+    public Result<TokenDTO> refreshToken(String oldToken) {
+        if (StringUtils.isBlank(oldToken)) {
+            throw new RenException(ErrorCode.UNAUTHORIZED);
+        }
+        SysUserTokenEntity tokenEntity = baseDao.getByToken(oldToken);
+        if (tokenEntity == null) {
+            throw new RenException(ErrorCode.TOKEN_INVALID);
+        }
+        if (tokenEntity.getExpireDate().before(new Date())) {
+            throw new RenException(ErrorCode.UNAUTHORIZED);
+        }
+
+        // CAS 更新：并发场景下只有一个请求能匹配到该 oldToken，另一个返 0 行
+        String newToken = TokenGenerator.generateValue();
+        Date now = new Date();
+        Date expireTime = new Date(now.getTime() + EXPIRE * 1000L);
+        int affected = baseDao.refreshTokenCAS(tokenEntity.getUserId(), oldToken, newToken, expireTime, now);
+        if (affected == 0) {
+            throw new RenException(ErrorCode.TOKEN_INVALID);
+        }
+
+        TokenDTO dto = new TokenDTO();
+        dto.setToken(newToken);
+        dto.setExpire(EXPIRE);
+        dto.setClientHash(HttpContextUtils.getClientCode());
+        return new Result<TokenDTO>().ok(dto);
+    }
+
    @Override
    public SysUserDTO getUserByToken(String token) {
        SysUserTokenEntity userToken = baseDao.getByToken(token);
@@ -14,4 +14,12 @@
 	<update id="logout">
 		update sys_user_token set expire_date = #{expireDate} where user_id = #{userId}
 	</update>
+
+	<update id="refreshTokenCAS">
+		update sys_user_token
+		set token = #{newToken}, update_date = #{updateDate}, expire_date = #{newExpire}
+		where token = #{oldToken}
+		  and expire_date > NOW()
+		  and user_id = #{userId}
+	</update>
 </mapper>
@@ -44,7 +44,7 @@ class SensitiveDataUtilsTest {
    void maskMiddle_keeps_four_at_each_end_for_long_strings() {
        String masked = SensitiveDataUtils.maskMiddle("verylongapikeyvalue123");
        assertTrue(masked.startsWith("very"));
-        assertTrue(masked.endsWith("3123"));
+        assertTrue(masked.endsWith("e123"));
        assertTrue(masked.contains("****"));
        assertEquals("verylongapikeyvalue123".length(), masked.length());
    }
@@ -14,9 +14,14 @@ import java.util.Collections;
 import java.util.Date;
 import java.util.List;

+import org.apache.ibatis.builder.MapperBuilderAssistant;
+import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
 import org.springframework.test.util.ReflectionTestUtils;

+import com.baomidou.mybatisplus.core.MybatisConfiguration;
+import com.baomidou.mybatisplus.core.metadata.TableInfoHelper;
+
 import xiaozhi.modules.agent.dao.AgentCorrectWordMappingDao;
 import xiaozhi.modules.agent.entity.AgentCorrectWordMappingEntity;
 import xiaozhi.modules.correctword.dao.CorrectWordFileDao;
@@ -37,6 +42,20 @@ class CorrectWordFileServiceImplTest {
    private final CorrectWordFileServiceImpl service =
            new CorrectWordFileServiceImpl(fileDao, itemDao, mappingDao);

+    @BeforeAll
+    static void registerEntityMetadata() {
+        // 这条用例不起 Spring 上下文，MyBatis-Plus 的实体元数据没人注册，
+        // LambdaQueryWrapper 拼条件时找不到 lambda 缓存就抛异常。
+        // 全量跑的时候是前面的上下文测试顺带注册好的，单独跑就露馅。
+        // 这里自己补上，单独跑和跟着全量跑结果一样。
+        TableInfoHelper.initTableInfo(
+                new MapperBuilderAssistant(new MybatisConfiguration(), ""),
+                CorrectWordItemEntity.class);
+        TableInfoHelper.initTableInfo(
+                new MapperBuilderAssistant(new MybatisConfiguration(), ""),
+                CorrectWordFileEntity.class);
+    }
+
    @Test
    void getAllItemsByAgentId_returns_empty_list_when_no_mappings() {
        when(mappingDao.selectByAgentId(AGENT_ID)).thenReturn(Collections.emptyList());
@@ -3,6 +3,7 @@ package xiaozhi.modules.device;
 import java.util.HashMap;

 import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -15,6 +16,7 @@ import xiaozhi.common.exception.RenException;
 import xiaozhi.common.redis.RedisUtils;
 import xiaozhi.modules.sys.dto.SysUserDTO;
 import xiaozhi.modules.sys.service.SysUserService;
+import xiaozhi.testsupport.IntegrationTestEnvironment;

@Slf4j
@SpringBootTest
@@ -22,6 +24,11 @@ import xiaozhi.modules.sys.service.SysUserService;
@DisplayName("设备测试")
 public class DeviceTest {

+    @BeforeAll
+    static void checkDependencies() {
+        IntegrationTestEnvironment.requireDatabaseAndRedis();
+    }
+
    @Autowired
    private RedisUtils redisUtils;
    @Autowired
@@ -1,11 +1,15 @@
 package xiaozhi.modules.device.controller;

 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.mockStatic;
+import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;

+import java.util.List;
+
 import org.junit.jupiter.api.DisplayName;
 import org.junit.jupiter.api.Test;
 import org.mockito.MockedStatic;
@@ -15,7 +19,10 @@ import xiaozhi.common.redis.RedisUtils;
 import xiaozhi.common.user.UserDetail;
 import xiaozhi.common.utils.MessageUtils;
 import xiaozhi.common.utils.Result;
+import xiaozhi.modules.device.dto.DeviceAddressBookAliasDTO;
+import xiaozhi.modules.device.dto.DeviceAddressBookPermissionDTO;
 import xiaozhi.modules.device.dto.DeviceUpdateDTO;
+import xiaozhi.modules.device.entity.DeviceAddressBookEntity;
 import xiaozhi.modules.device.entity.DeviceEntity;
 import xiaozhi.modules.device.service.DeviceAddressBookService;
 import xiaozhi.modules.device.service.DeviceService;
@@ -26,6 +33,8 @@ import xiaozhi.modules.sys.service.SysParamsService;
 class DeviceControllerTest {

    private static final String DEVICE_ID = "device-id";
+    private static final String MAC = "00:11:22:33:44:55";
+    private static final String OTHER_MAC = "00:11:22:33:44:66";
    private static final long USER_ID = 1L;

    @Test
@@ -35,7 +44,7 @@ class DeviceControllerTest {
        DeviceEntity entity = ownedDevice();
        when(deviceService.selectById(DEVICE_ID)).thenReturn(entity);
        when(deviceService.updateById(entity)).thenReturn(false);
-        DeviceController controller = controller(deviceService);
+        DeviceController controller = controller(deviceService, mock(DeviceAddressBookService.class));

        DeviceUpdateDTO update = new DeviceUpdateDTO();
        update.setAutoUpdate(0);
@@ -54,10 +63,84 @@ class DeviceControllerTest {
        }
    }

-    private DeviceController controller(DeviceService deviceService) {
+    @Test
+    @DisplayName("读取他人设备通讯录时一律按设备不存在处理")
+    void addressBookOfDeviceOwnedByAnotherUserIsRejected() {
+        DeviceService deviceService = mock(DeviceService.class);
+        DeviceAddressBookService addressBookService = mock(DeviceAddressBookService.class);
+        when(deviceService.getOwnedDeviceByMacAddress(OTHER_MAC)).thenReturn(null);
+        DeviceController controller = controller(deviceService, addressBookService);
+
+        try (MockedStatic<MessageUtils> messageUtils = mockStatic(MessageUtils.class)) {
+            messageUtils.when(() -> MessageUtils.getMessage(ErrorCode.DEVICE_NOT_EXIST))
+                    .thenReturn("Device not exist");
+
+            Result<Object> result = controller.getAddressBook(OTHER_MAC);
+
+            assertEquals(ErrorCode.DEVICE_NOT_EXIST, result.getCode());
+            assertNull(result.getData());
+            verify(addressBookService, never()).getAddressBookList(OTHER_MAC);
+        }
+    }
+
+    @Test
+    @DisplayName("读取本机设备通讯录照常返回")
+    void addressBookOfOwnDeviceIsReturned() {
+        DeviceService deviceService = mock(DeviceService.class);
+        DeviceAddressBookService addressBookService = mock(DeviceAddressBookService.class);
+        List<DeviceAddressBookEntity> entries = List.of(new DeviceAddressBookEntity());
+        when(deviceService.getOwnedDeviceByMacAddress(MAC)).thenReturn(ownedDevice());
+        when(addressBookService.getAddressBookList(MAC)).thenReturn(entries);
+        DeviceController controller = controller(deviceService, addressBookService);
+
+        Result<Object> result = controller.getAddressBook(MAC);
+
+        assertEquals(0, result.getCode());
+        assertEquals(entries, result.getData());
+    }
+
+    @Test
+    @DisplayName("以他人设备名义改别名被拒")
+    void updateAliasOnDeviceOwnedByAnotherUserIsRejected() {
+        DeviceService deviceService = mock(DeviceService.class);
+        DeviceAddressBookService addressBookService = mock(DeviceAddressBookService.class);
+        when(deviceService.getOwnedDeviceByMacAddress(OTHER_MAC)).thenReturn(null);
+        DeviceController controller = controller(deviceService, addressBookService);
+
+        DeviceAddressBookAliasDTO dto = new DeviceAddressBookAliasDTO();
+        dto.setMacAddress(OTHER_MAC);
+        dto.setTargetMac(MAC);
+        dto.setAlias("office");
+
+        Result<Void> result = controller.updateAlias(dto);
+
+        assertEquals("无权限操作该设备", result.getMsg());
+        verify(addressBookService, never()).saveOrUpdate(OTHER_MAC, MAC, "office", null);
+    }
+
+    @Test
+    @DisplayName("以他人设备名义改权限被拒")
+    void updatePermissionOnDeviceOwnedByAnotherUserIsRejected() {
+        DeviceService deviceService = mock(DeviceService.class);
+        DeviceAddressBookService addressBookService = mock(DeviceAddressBookService.class);
+        when(deviceService.getOwnedDeviceByMacAddress(OTHER_MAC)).thenReturn(null);
+        DeviceController controller = controller(deviceService, addressBookService);
+
+        DeviceAddressBookPermissionDTO dto = new DeviceAddressBookPermissionDTO();
+        dto.setMacAddress(OTHER_MAC);
+        dto.setTargetMac(MAC);
+        dto.setHasPermission(true);
+
+        Result<Void> result = controller.updatePermission(dto);
+
+        assertEquals("无权限操作该设备", result.getMsg());
+        verify(addressBookService, never()).saveOrUpdate(OTHER_MAC, MAC, null, true);
+    }
+
+    private DeviceController controller(DeviceService deviceService, DeviceAddressBookService addressBookService) {
        return new DeviceController(
                deviceService,
-                mock(DeviceAddressBookService.class),
+                addressBookService,
                mock(RedisUtils.class),
                mock(SysParamsService.class));
    }
@@ -1,26 +1,47 @@
 package xiaozhi.modules.device.service.impl;

 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.mockStatic;
 import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;

+import java.util.Date;
+import java.util.ArrayList;
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicReference;

 import org.junit.jupiter.api.Test;
 import org.mockito.ArgumentCaptor;
+import org.mockito.MockedStatic;

+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.entity.DeviceEntity;
 import xiaozhi.modules.device.service.DeviceService;
 import xiaozhi.modules.sys.service.SysParamsService;

 class DeviceAddressBookServiceImplTest {

+    private static final String MAC = "00:11:22:33:44:55";
+    private static final String OTHER_MAC = "00:11:22:33:44:66";
+    private static final String THIRD_MAC = "00:11:22:33:44:77";
+    // 纯数字的 MAC 大小写化后跟原来一模一样，拿它造不出"只差大小写"的两行
+    private static final String HEX_MAC = "00:11:22:33:44:ab";
+
    @Test
    void newEntryUsesTheDedicatedAddressBookInsertMapping() {
        DeviceAddressBookDao addressBookDao = mock(DeviceAddressBookDao.class);
@@ -32,15 +53,363 @@ class DeviceAddressBookServiceImplTest {
        when(addressBookDao.selectOne(any())).thenReturn(null);
        when(addressBookDao.selectList(null)).thenReturn(List.of());

-        service.saveOrUpdate("00:11:22:33:44:55", "00:11:22:33:44:66", "living-room", true);
+        service.saveOrUpdate(MAC, OTHER_MAC, "living-room", true);

        ArgumentCaptor<DeviceAddressBookEntity> entityCaptor = ArgumentCaptor.forClass(DeviceAddressBookEntity.class);
        verify(addressBookDao).insertAddressBook(entityCaptor.capture());
        DeviceAddressBookEntity entity = entityCaptor.getValue();
-        assertEquals("00:11:22:33:44:55", entity.getMacAddress());
-        assertEquals("00:11:22:33:44:66", entity.getTargetMac());
+        assertEquals(MAC, entity.getMacAddress());
+        assertEquals(OTHER_MAC, entity.getTargetMac());
        assertEquals("living-room", entity.getAlias());
        assertTrue(entity.getHasPermission());
        verify(addressBookDao, never()).insert(any(DeviceAddressBookEntity.class));
    }
+
+    @Test
+    void blankAliasOnUnregisteredTargetFallsBackToMacSuffix() {
+        DeviceAddressBookDao addressBookDao = mock(DeviceAddressBookDao.class);
+        RedisUtils redisUtils = mock(RedisUtils.class);
+        DeviceService deviceService = mock(DeviceService.class);
+        SysParamsService sysParamsService = mock(SysParamsService.class);
+        DeviceAddressBookServiceImpl service = new DeviceAddressBookServiceImpl(
+                addressBookDao, redisUtils, deviceService, sysParamsService);
+        when(addressBookDao.selectOne(any())).thenReturn(null);
+        when(addressBookDao.selectList(null)).thenReturn(List.of());
+        when(deviceService.getDeviceByMacAddress(OTHER_MAC)).thenReturn(null);
+
+        service.saveOrUpdate(MAC, OTHER_MAC, null, true);
+
+        ArgumentCaptor<DeviceAddressBookEntity> entityCaptor = ArgumentCaptor.forClass(DeviceAddressBookEntity.class);
+        verify(addressBookDao).insertAddressBook(entityCaptor.capture());
+        DeviceAddressBookEntity entity = entityCaptor.getValue();
+        assertNotNull(entity.getAlias());
+        assertEquals("尾号为66的设备", entity.getAlias());
+        assertTrue(entity.getHasPermission());
+    }
+
+    @Test
+    void blankAliasOnRegisteredTargetWithoutNicknameFallsBackToMacSuffix() {
+        DeviceAddressBookDao addressBookDao = mock(DeviceAddressBookDao.class);
+        RedisUtils redisUtils = mock(RedisUtils.class);
+        DeviceService deviceService = mock(DeviceService.class);
+        SysParamsService sysParamsService = mock(SysParamsService.class);
+        DeviceAddressBookServiceImpl service = new DeviceAddressBookServiceImpl(
+                addressBookDao, redisUtils, deviceService, sysParamsService);
+        when(addressBookDao.selectOne(any())).thenReturn(null);
+        when(addressBookDao.selectList(null)).thenReturn(List.of());
+        DeviceEntity registered = new DeviceEntity();
+        registered.setMacAddress(OTHER_MAC);
+        registered.setAlias(null);
+        when(deviceService.getDeviceByMacAddress(OTHER_MAC)).thenReturn(registered);
+
+        service.saveOrUpdate(MAC, OTHER_MAC, null, true);
+
+        ArgumentCaptor<DeviceAddressBookEntity> entityCaptor = ArgumentCaptor.forClass(DeviceAddressBookEntity.class);
+        verify(addressBookDao).insertAddressBook(entityCaptor.capture());
+        assertEquals("尾号为66的设备", entityCaptor.getValue().getAlias(),
+                "登记了但没起名的设备落个空名，缓存刷新会跳过这条，对方永远呼不过来");
+    }
+
+    @Test
+    void refreshCacheKeepsEntriesWhoseAliasWasNeverFilledIn() {
+        DeviceAddressBookDao addressBookDao = mock(DeviceAddressBookDao.class);
+        RedisUtils redisUtils = mock(RedisUtils.class);
+        when(addressBookDao.selectList(null)).thenReturn(List.of(row(MAC, OTHER_MAC, null)));
+        DeviceAddressBookServiceImpl service = new DeviceAddressBookServiceImpl(
+                addressBookDao, redisUtils, mock(DeviceService.class), mock(SysParamsService.class));
+
+        service.refreshCache();
+
+        Map<String, String> book = cachedBook(service, redisUtils).get(MAC);
+        assertNotNull(book, "空别名整条被跳过，这条设备就再也呼不过来了");
+        assertEquals(OTHER_MAC + "|1", book.get("尾号为66的设备"));
+    }
+
+    @Test
+    void refreshCacheDisambiguatesTwoEntriesSharingAnAlias() {
+        DeviceAddressBookDao addressBookDao = mock(DeviceAddressBookDao.class);
+        RedisUtils redisUtils = mock(RedisUtils.class);
+        when(addressBookDao.selectList(null)).thenReturn(List.of(
+                row(MAC, OTHER_MAC, "客厅"),
+                row(MAC, THIRD_MAC, "客厅")));
+        DeviceAddressBookServiceImpl service = new DeviceAddressBookServiceImpl(
+                addressBookDao, redisUtils, mock(DeviceService.class), mock(SysParamsService.class));
+
+        service.refreshCache();
+
+        Map<String, String> book = cachedBook(service, redisUtils).get(MAC);
+        assertEquals(2, book.size(), "撞名的两台设备只留得下一台：" + book);
+        assertEquals(OTHER_MAC + "|1", book.get("客厅"));
+        assertEquals(THIRD_MAC + "|1", book.get("客厅1"));
+    }
+
+    @Test
+    void refreshCacheGivesTheSameResultWhateverOrderRowsComeBackIn() {
+        DeviceAddressBookEntity first = row(MAC, OTHER_MAC, "客厅");
+        DeviceAddressBookEntity second = row(MAC, THIRD_MAC, "客厅");
+
+        Map<String, String> inOrder = refreshAndRead(List.of(first, second));
+        Map<String, String> reversed = refreshAndRead(List.of(second, first));
+
+        assertEquals(inOrder, reversed, "同样的数据两次刷新结果不一样，缓存里的称呼会来回变");
+    }
+
+    /**
+     * 库里能同时存在两条 owner 只差大小写的行：表是 utf8mb4_0900_ai_ci，
+     * 主键 (mac_address, target_mac) 大小写不敏感，target 不同就不会撞。
+     * 这是同一个人，算称呼和写缓存都得按小写归成一本
+     */
+    @Test
+    void ownersDifferingOnlyInCaseShareOneBook() {
+        String upper = HEX_MAC.toUpperCase();
+        assertNotEquals(HEX_MAC, upper, "这个用例得真的造出大小写差异才有效");
+
+        Map<String, Map<String, String>> books = refreshAndReadAll(List.of(
+                row(upper, OTHER_MAC, "客厅"),
+                row(HEX_MAC, THIRD_MAC, "客厅")));
+
+        Map<String, String> book = books.get(HEX_MAC);
+        assertNotNull(book, "同一个人被算成了两个人：" + books.keySet());
+        assertEquals(2, book.size(), "两台设备只剩一台，另一台从缓存里消失了：" + book);
+        assertEquals(OTHER_MAC + "|1", book.get("客厅"));
+        assertEquals(THIRD_MAC + "|1", book.get("客厅1"));
+        assertEquals(1, books.size(), "两种写法的地址被拆成了两本：" + books.keySet());
+    }
+
+    @Test
+    void listAndCacheAgreeWhenOwnersDifferOnlyInCase() {
+        String upper = HEX_MAC.toUpperCase();
+        DeviceAddressBookDao addressBookDao = mock(DeviceAddressBookDao.class);
+        RedisUtils redisUtils = mock(RedisUtils.class);
+        when(addressBookDao.getAddressBookList(upper)).thenReturn(new ArrayList<>(List.of(
+                row(upper, OTHER_MAC, "客厅"), row(HEX_MAC, THIRD_MAC, "客厅"))));
+        when(addressBookDao.selectList(null)).thenReturn(List.of(
+                row(upper, OTHER_MAC, "客厅"), row(HEX_MAC, THIRD_MAC, "客厅")));
+        DeviceAddressBookServiceImpl service = new DeviceAddressBookServiceImpl(
+                addressBookDao, redisUtils, mock(DeviceService.class), mock(SysParamsService.class));
+
+        Map<String, String> shownToConsole = namesByTargetMac(service.getAddressBookList(upper));
+        assertEquals(2, shownToConsole.size(),
+                "接口按原值分组，同一个人的两台设备被算成一个，前端只能看到一台：" + shownToConsole);
+
+        service.refreshCache();
+        Map<String, String> callableNames = new HashMap<>();
+        cachedBook(service, redisUtils).get(HEX_MAC)
+                .forEach((name, macAndPerm) -> callableNames.put(name, macAndPerm.split("\\|")[0]));
+
+        assertEquals(shownToConsole, callableNames,
+                "接口按原值分组、缓存按小写分组，用户照前端看到的名字呼，命中的不是同一台设备");
+    }
+
+    @Test
+    void nameAssignmentDoesNotDependOnWhichSpellingOfTheOwnerCameBack() {
+        String upper = HEX_MAC.toUpperCase();
+        Map<String, String> expected = Map.of("客厅", OTHER_MAC + "|1", "客厅1", THIRD_MAC + "|1");
+
+        Map<String, String> lowerFirst = refreshAndRead(HEX_MAC, List.of(
+                row(HEX_MAC, OTHER_MAC, "客厅"), row(upper, THIRD_MAC, "客厅")));
+        Map<String, String> upperFirst = refreshAndRead(HEX_MAC, List.of(
+                row(upper, THIRD_MAC, "客厅"), row(HEX_MAC, OTHER_MAC, "客厅")));
+
+        assertEquals(expected, lowerFirst,
+                "同一个人的称呼取决于库里哪种写法先返回，刷新一次就换一次名字");
+        assertEquals(expected, upperFirst, "顺序反过来结果就该不一样：" + upperFirst);
+    }
+
+    @SuppressWarnings("unchecked")
+    private Map<String, Map<String, String>> refreshAndReadAll(List<DeviceAddressBookEntity> rows) {
+        DeviceAddressBookDao addressBookDao = mock(DeviceAddressBookDao.class);
+        RedisUtils redisUtils = mock(RedisUtils.class);
+        when(addressBookDao.selectList(null)).thenReturn(rows);
+        DeviceAddressBookServiceImpl service = new DeviceAddressBookServiceImpl(
+                addressBookDao, redisUtils, mock(DeviceService.class), mock(SysParamsService.class));
+
+        service.refreshCache();
+
+        return cachedBook(service, redisUtils);
+    }
+
+    private Map<String, String> refreshAndRead(List<DeviceAddressBookEntity> rows) {
+        return refreshAndRead(MAC, rows);
+    }
+
+    private Map<String, String> refreshAndRead(String owner, List<DeviceAddressBookEntity> rows) {
+        return refreshAndReadAll(rows).get(owner);
+    }
+
+    @SuppressWarnings("unchecked")
+    private Map<String, Map<String, String>> cachedBook(DeviceAddressBookServiceImpl service, RedisUtils redisUtils) {
+        ArgumentCaptor<Object> captor = ArgumentCaptor.forClass(Object.class);
+        verify(redisUtils).set(eq(RedisKeys.getAddressBookKey()), captor.capture());
+        return (Map<String, Map<String, String>>) captor.getValue();
+    }
+
+    private DeviceAddressBookEntity row(String macAddress, String targetMac, String alias) {
+        return row(macAddress, targetMac, alias, Boolean.TRUE);
+    }
+
+    private DeviceAddressBookEntity row(String macAddress, String targetMac, String alias, Boolean hasPermission) {
+        DeviceAddressBookEntity entity = new DeviceAddressBookEntity();
+        entity.setMacAddress(macAddress);
+        entity.setTargetMac(targetMac);
+        entity.setAlias(alias);
+        entity.setHasPermission(hasPermission);
+        return entity;
+    }
+
+    @Test
+    void listAndCacheHandOutTheSameNameForCollidingEntries() {
+        DeviceAddressBookDao addressBookDao = mock(DeviceAddressBookDao.class);
+        RedisUtils redisUtils = mock(RedisUtils.class);
+        // 两次 DAO 调用各给一份新行：取名会写回实体，共用同一份的话第二遍读到的是算过的名字
+        // 用可变列表，跟 MyBatis 实际返回的一致，免得排序那步先炸掉、断言根本没跑到
+        when(addressBookDao.getAddressBookList(MAC)).thenReturn(
+                new ArrayList<>(List.of(row(MAC, OTHER_MAC, "客厅"), row(MAC, THIRD_MAC, "客厅"))));
+        when(addressBookDao.selectList(null)).thenReturn(List.of(
+                row(MAC, OTHER_MAC, "客厅"), row(MAC, THIRD_MAC, "客厅")));
+        DeviceAddressBookServiceImpl service = new DeviceAddressBookServiceImpl(
+                addressBookDao, redisUtils, mock(DeviceService.class), mock(SysParamsService.class));
+
+        Map<String, String> shownToConsole = namesByTargetMac(service.getAddressBookList(MAC));
+        service.refreshCache();
+        Map<String, String> callableNames = new HashMap<>();
+        cachedBook(service, redisUtils).get(MAC)
+                .forEach((name, macAndPerm) -> callableNames.put(name, macAndPerm.split("\\|")[0]));
+
+        assertEquals(callableNames, shownToConsole,
+                "接口和缓存给的是两个名字，用户照前端看到的那个名字呼叫，命中的不是同一台设备");
+    }
+
+    @Test
+    void theCallableEntryKeepsThePlainNameWhenTwoCollide() {
+        DeviceAddressBookDao addressBookDao = mock(DeviceAddressBookDao.class);
+        RedisUtils redisUtils = mock(RedisUtils.class);
+        // OTHER_MAC 的 target_mac 排在前面，没权限的那条会先占住原名
+        when(addressBookDao.selectList(null)).thenReturn(List.of(
+                row(MAC, OTHER_MAC, "客厅", Boolean.FALSE),
+                row(MAC, THIRD_MAC, "客厅", Boolean.TRUE)));
+        DeviceAddressBookServiceImpl service = new DeviceAddressBookServiceImpl(
+                addressBookDao, redisUtils, mock(DeviceService.class), mock(SysParamsService.class));
+
+        service.refreshCache();
+
+        Map<String, String> book = cachedBook(service, redisUtils).get(MAC);
+        assertEquals(THIRD_MAC + "|1", book.get("客厅"),
+                "能呼的那台被挤到后缀名上了，用户照前端看到的名字点，界面只会说没权限");
+        assertEquals(OTHER_MAC + "|0", book.get("客厅1"));
+    }
+
+    @Test
+    void listFillsInBlankAliasesSoTheConsoleShowsWhatCanBeCalled() {
+        DeviceAddressBookDao addressBookDao = mock(DeviceAddressBookDao.class);
+        RedisUtils redisUtils = mock(RedisUtils.class);
+        when(addressBookDao.getAddressBookList(MAC)).thenReturn(new ArrayList<>(List.of(row(MAC, OTHER_MAC, null))));
+        DeviceAddressBookServiceImpl service = new DeviceAddressBookServiceImpl(
+                addressBookDao, redisUtils, mock(DeviceService.class), mock(SysParamsService.class));
+
+        List<DeviceAddressBookEntity> rows = service.getAddressBookList(MAC);
+
+        assertEquals("尾号为66的设备", rows.get(0).getAlias(),
+                "空别名原样返回的话前端回落显示设备名，用户照着那个名字呼叫却只会说找不到备注");
+    }
+
+    @Test
+    void anUppercaseMacGetsTheSameNameWhicheverPathAddsItToTheBook() {
+        // 兜底称呼只有这一处算法：存进去的时候算一次，之后接口和缓存里显示的
+        // 都是同一个字符串。不跟着小写化的话同一个地址在两条路径上算出两个称呼，
+        // 用户照着看到的名字呼过去，命中的不是自己刚存的那台
+        //
+        // 运行期这一侧：saveOrUpdate 传的是 DTO 原样过来的地址，大小写没归一
+        DeviceAddressBookDao addressBookDao = mock(DeviceAddressBookDao.class);
+        RedisUtils redisUtils = mock(RedisUtils.class);
+        DeviceService deviceService = mock(DeviceService.class);
+        when(addressBookDao.selectOne(any())).thenReturn(null);
+        when(addressBookDao.selectList(null)).thenReturn(List.of());
+        when(deviceService.getDeviceByMacAddress(anyString())).thenReturn(null);
+        DeviceAddressBookServiceImpl service = new DeviceAddressBookServiceImpl(
+                addressBookDao, redisUtils, deviceService, mock(SysParamsService.class));
+
+        service.saveOrUpdate(MAC, "ff:ee:dd:cc:bb:AB", null, true);
+
+        ArgumentCaptor<DeviceAddressBookEntity> entityCaptor = ArgumentCaptor.forClass(DeviceAddressBookEntity.class);
+        verify(addressBookDao).insertAddressBook(entityCaptor.capture());
+        assertEquals("尾号为ab的设备", entityCaptor.getValue().getAlias(),
+                "MAC 大小写不区分，末尾两位要跟着小写化，否则接口和呼叫那边算出来的称呼对不上");
+    }
+
+    /**
+     * 接口按最近改过的排前面
+     *
+     * <p>
+     * 智控台那条 Vue 是按 targetMac 把 alias 合进 allDevices 的，接口顺序被丢掉了，
+     * 这条现在对 console 没有效果。用例留着是把这个契约钉住：哪天当无用代码删了，
+     * 会有用例报出来，而不是静悄悄换掉接口的返回顺序
+     */
+    @Test
+    void listPutsTheMostRecentlyTouchedEntryFirst() {
+        DeviceAddressBookDao addressBookDao = mock(DeviceAddressBookDao.class);
+        RedisUtils redisUtils = mock(RedisUtils.class);
+        DeviceAddressBookEntity older = row(MAC, OTHER_MAC, "客厅");
+        older.setUpdateDate(new Date(1767321840000L));
+        DeviceAddressBookEntity newer = row(MAC, THIRD_MAC, "书房");
+        newer.setUpdateDate(new Date(1778000000000L));
+        DeviceAddressBookEntity neverTouched = row(MAC, "00:11:22:33:44:88", "阳台");
+        when(addressBookDao.getAddressBookList(MAC)).thenReturn(
+                new ArrayList<>(List.of(older, neverTouched, newer)));
+        DeviceAddressBookServiceImpl service = new DeviceAddressBookServiceImpl(
+                addressBookDao, redisUtils, mock(DeviceService.class), mock(SysParamsService.class));
+
+        List<DeviceAddressBookEntity> rows = service.getAddressBookList(MAC);
+
+        assertEquals(List.of("书房", "客厅", "阳台"), rows.stream().map(DeviceAddressBookEntity::getAlias).toList(),
+                "最近改过的应该排前面，没改过的排最后");
+    }
+
+
+    private Map<String, String> namesByTargetMac(List<DeviceAddressBookEntity> rows) {
+        Map<String, String> byAlias = new HashMap<>();
+        for (DeviceAddressBookEntity row : rows) {
+            byAlias.put(row.getAlias(), row.getTargetMac());
+        }
+        return byAlias;
+    }
+
+    @Test
+    void callByNicknameFallsBackToMacSuffixWhenCallerHasNoAlias() {
+        DeviceAddressBookDao addressBookDao = mock(DeviceAddressBookDao.class);
+        RedisUtils redisUtils = mock(RedisUtils.class);
+        DeviceService deviceService = mock(DeviceService.class);
+        SysParamsService sysParamsService = mock(SysParamsService.class);
+        DeviceAddressBookServiceImpl service = new DeviceAddressBookServiceImpl(
+                addressBookDao, redisUtils, deviceService, sysParamsService);
+
+        Map<String, Map<String, String>> books = new HashMap<>();
+        Map<String, String> callerBook = new HashMap<>();
+        callerBook.put("office", OTHER_MAC + "|1");
+        books.put(MAC, callerBook);
+        when(redisUtils.get(RedisKeys.getAddressBookKey())).thenReturn(books);
+        when(deviceService.getDeviceByMacAddress(MAC)).thenReturn(null);
+        when(sysParamsService.getValue("server.mqtt_manager_api", true)).thenReturn("127.0.0.1:1883");
+        when(sysParamsService.getValue(Constant.SERVER_MQTT_SECRET, true)).thenReturn("gateway-key");
+
+        // 网关是真的 http 调用，桩掉它，否则测试会往 127.0.0.1:1883 真发请求
+        AtomicReference<String> sentUrl = new AtomicReference<>();
+        AtomicReference<String> sentBody = new AtomicReference<>();
+        Map<String, Object> result;
+        try (MockedStatic<MqttGatewayAuthorization> gateway = mockStatic(MqttGatewayAuthorization.class)) {
+            gateway.when(() -> MqttGatewayAuthorization.postJson(
+                            anyString(), anyString(), anyString(), any(), anyInt()))
+                    .thenAnswer(invocation -> {
+                        sentUrl.set(invocation.getArgument(0));
+                        sentBody.set(invocation.getArgument(1));
+                        return "{\"status\":\"success\",\"message\":\"ok\"}";
+                    });
+            result = service.callByNickname(MAC, "office", false);
+        }
+
+        assertEquals("success", result.get("status"));
+        assertEquals("http://127.0.0.1:1883/api/call/request", sentUrl.get());
+        assertTrue(sentBody.get().contains("尾号为55的设备"),
+                "主叫方没登记也没起名时该退回尾号称呼：" + sentBody.get());
+    }
 }
@@ -0,0 +1,184 @@
+package xiaozhi.modules.device.service.impl;
+
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyList;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.mockStatic;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import java.util.List;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.mockito.MockedStatic;
+
+import com.baomidou.mybatisplus.core.conditions.update.UpdateWrapper;
+
+import xiaozhi.common.redis.RedisUtils;
+import xiaozhi.common.user.UserDetail;
+import xiaozhi.modules.device.dao.DeviceDao;
+import xiaozhi.modules.device.entity.DeviceEntity;
+import xiaozhi.modules.device.service.DeviceAddressBookService;
+import xiaozhi.modules.device.service.OtaService;
+import xiaozhi.modules.security.user.SecurityUser;
+import xiaozhi.modules.sys.service.SysParamsService;
+import xiaozhi.modules.sys.service.SysUserUtilService;
+
+@DisplayName("设备归属校验回归测试")
+class DeviceServiceImplTest {
+
+    private static final String MAC = "00:11:22:33:44:55";
+    private static final long USER_ID = 1L;
+    private static final long OTHER_USER_ID = 2L;
+
+    @Test
+    @DisplayName("设备属于当前用户时返回设备")
+    void deviceOwnedByCurrentUserIsReturned() {
+        DeviceEntity device = device(USER_ID);
+        DeviceServiceImpl service = serviceWithDeviceDao(daoReturning(device));
+
+        try (MockedStatic<SecurityUser> securityUser = mockStatic(SecurityUser.class)) {
+            securityUser.when(SecurityUser::getUser).thenReturn(user(USER_ID));
+
+            assertSame(device, service.getOwnedDeviceByMacAddress(MAC));
+        }
+    }
+
+    @Test
+    @DisplayName("设备属于他人时按查不到处理")
+    void deviceOwnedByAnotherUserIsHidden() {
+        DeviceServiceImpl service = serviceWithDeviceDao(daoReturning(device(OTHER_USER_ID)));
+
+        try (MockedStatic<SecurityUser> securityUser = mockStatic(SecurityUser.class)) {
+            securityUser.when(SecurityUser::getUser).thenReturn(user(USER_ID));
+
+            assertNull(service.getOwnedDeviceByMacAddress(MAC));
+        }
+    }
+
+    @Test
+    @DisplayName("设备未登记时按查不到处理")
+    void unregisteredDeviceIsHidden() {
+        DeviceServiceImpl service = serviceWithDeviceDao(daoReturning(List.of()));
+
+        try (MockedStatic<SecurityUser> securityUser = mockStatic(SecurityUser.class)) {
+            securityUser.when(SecurityUser::getUser).thenReturn(user(USER_ID));
+
+            assertNull(service.getOwnedDeviceByMacAddress(MAC));
+        }
+    }
+
+    @Test
+    @DisplayName("设备没有归属人时按查不到处理")
+    void unboundDeviceIsHidden() {
+        DeviceServiceImpl service = serviceWithDeviceDao(daoReturning(device(null)));
+
+        try (MockedStatic<SecurityUser> securityUser = mockStatic(SecurityUser.class)) {
+            securityUser.when(SecurityUser::getUser).thenReturn(user(USER_ID));
+
+            assertNull(service.getOwnedDeviceByMacAddress(MAC));
+        }
+    }
+
+    @Test
+    @DisplayName("没有登录用户时按查不到处理")
+    void anonymousCallerGetsNothing() {
+        DeviceServiceImpl service = serviceWithDeviceDao(daoReturning(device(USER_ID)));
+
+        // 匿名调用的实际形态：getUser() 返回空对象，id 是空的，不是返回 null
+        try (MockedStatic<SecurityUser> securityUser = mockStatic(SecurityUser.class)) {
+            securityUser.when(SecurityUser::getUser).thenReturn(new UserDetail());
+
+            assertNull(service.getOwnedDeviceByMacAddress(MAC));
+        }
+    }
+
+    @Test
+    @DisplayName("库里同一 MAC 有两行只差大小写时，取第一条做归属校验，不再抛异常")
+    void duplicateMacDifferingOnlyInCaseStillReturnsTheDevice() {
+        DeviceEntity first = device(USER_ID, "device-1");
+        DeviceEntity second = device(USER_ID, "device-2");
+        DeviceServiceImpl service = serviceWithDeviceDao(daoReturning(List.of(first, second)));
+
+        try (MockedStatic<SecurityUser> securityUser = mockStatic(SecurityUser.class)) {
+            securityUser.when(SecurityUser::getUser).thenReturn(user(USER_ID));
+
+            assertSame(first, service.getOwnedDeviceByMacAddress(MAC));
+        }
+    }
+
+    @Test
+    @DisplayName("解绑自己的设备时，通讯录跟着一起清")
+    void unbindOwnDeviceClearsItsAddressBook() {
+        DeviceDao dao = mock(DeviceDao.class);
+        when(dao.selectById("device-1")).thenReturn(device(USER_ID, "device-1"));
+        DeviceAddressBookService addressBookService = mock(DeviceAddressBookService.class);
+        DeviceServiceImpl service = serviceWithDao(dao, addressBookService);
+
+        service.unbindDevice(USER_ID, "device-1");
+
+        verify(dao).delete(any(UpdateWrapper.class));
+        verify(addressBookService).deleteByMacAddresses(List.of(MAC));
+    }
+
+    @Test
+    @DisplayName("解绑别人的设备时什么都不删，通讯录不能跟着没")
+    void unbindAnotherUsersDeviceDeletesNothing() {
+        DeviceDao dao = mock(DeviceDao.class);
+        when(dao.selectById("device-1")).thenReturn(device(OTHER_USER_ID, "device-1"));
+        DeviceAddressBookService addressBookService = mock(DeviceAddressBookService.class);
+        DeviceServiceImpl service = serviceWithDao(dao, addressBookService);
+
+        service.unbindDevice(USER_ID, "device-1");
+
+        verify(dao, never()).delete(any(UpdateWrapper.class));
+        verify(addressBookService, never()).deleteByMacAddresses(anyList());
+    }
+
+    private DeviceServiceImpl serviceWithDao(DeviceDao dao, DeviceAddressBookService addressBookService) {
+        // baseDao 由父类持有，子类内部赋给 this，测试类自己碰不到它
+        return new DeviceServiceImpl(
+                dao, mock(SysUserUtilService.class), mock(SysParamsService.class),
+                mock(RedisUtils.class), mock(OtaService.class), addressBookService) {
+            {
+                this.baseDao = dao;
+            }
+        };
+    }
+
+    private DeviceServiceImpl serviceWithDeviceDao(DeviceDao dao) {
+        return serviceWithDao(dao, mock(DeviceAddressBookService.class));
+    }
+
+    private DeviceDao daoReturning(DeviceEntity device) {
+        return daoReturning(List.of(device));
+    }
+
+    private DeviceDao daoReturning(List<DeviceEntity> rows) {
+        DeviceDao dao = mock(DeviceDao.class);
+        when(dao.selectList(any())).thenReturn(rows);
+        return dao;
+    }
+
+    private DeviceEntity device(Long userId) {
+        return device(userId, null);
+    }
+
+    private DeviceEntity device(Long userId, String id) {
+        DeviceEntity entity = new DeviceEntity();
+        entity.setId(id);
+        entity.setMacAddress(MAC);
+        entity.setUserId(userId);
+        return entity;
+    }
+
+    private UserDetail user(long id) {
+        UserDetail user = new UserDetail();
+        user.setId(id);
+        return user;
+    }
+}
@@ -0,0 +1,82 @@
+package xiaozhi.modules.model.service.impl;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+
+import java.util.UUID;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.transaction.annotation.Transactional;
+
+import cn.hutool.json.JSONObject;
+import xiaozhi.common.redis.RedisKeys;
+import xiaozhi.common.redis.RedisUtils;
+import xiaozhi.modules.model.dto.ModelConfigBodyDTO;
+import xiaozhi.modules.model.dto.ModelConfigDTO;
+import xiaozhi.modules.model.service.ModelConfigService;
+import xiaozhi.testsupport.IntegrationTestEnvironment;
+
+@SpringBootTest
+@ActiveProfiles("dev")
+@Transactional
+class ModelConfigPersistenceTest {
+
+    @BeforeAll
+    static void checkDependencies() {
+        IntegrationTestEnvironment.requireDatabaseAndRedis();
+    }
+
+    @Autowired
+    private ModelConfigService service;
+
+    @Autowired
+    private JdbcTemplate jdbc;
+
+    @Autowired
+    private RedisUtils redis;
+
+    @ParameterizedTest
+    @CsvSource({"tts,TTS", "memory,Memory", "intent,Intent"})
+    void preservesRegisteredTypeWhenAddingAndEditing(String requestedType, String registeredType) {
+        String id = UUID.randomUUID().toString().replace("-", "");
+        String providerCode = "test-" + id;
+        jdbc.update("INSERT INTO ai_model_provider (id, model_type, provider_code, name, fields) VALUES (?, ?, ?, ?, ?)",
+                id, registeredType, providerCode, "Persistence test provider", "[]");
+
+        ModelConfigBodyDTO body = new ModelConfigBodyDTO();
+        body.setId(id);
+        body.setModelCode(providerCode);
+        body.setModelName("Persistence test model");
+        body.setIsDefault(0);
+        body.setIsEnabled(1);
+        body.setSort(1);
+        body.setConfigJson(new JSONObject().set("type", providerCode));
+
+        ModelConfigDTO added = service.add(requestedType, providerCode, body);
+        assertEquals(registeredType, added.getModelType());
+        assertEquals(registeredType,
+                jdbc.queryForObject("SELECT model_type FROM ai_model_config WHERE id = ?", String.class, id));
+
+        String cacheKey = RedisKeys.getModelConfigById(id);
+        try {
+            redis.set(cacheKey, "cached model");
+            body.setModelName("Updated persistence test model");
+            ModelConfigDTO edited = service.edit(requestedType, providerCode, id, body);
+
+            assertEquals(registeredType, edited.getModelType());
+            assertEquals(registeredType,
+                    jdbc.queryForObject("SELECT model_type FROM ai_model_config WHERE id = ?", String.class, id));
+            assertEquals(body.getModelName(),
+                    jdbc.queryForObject("SELECT model_name FROM ai_model_config WHERE id = ?", String.class, id));
+            assertNull(redis.get(cacheKey));
+        } finally {
+            redis.delete(cacheKey);
+        }
+    }
+}
@@ -0,0 +1,120 @@
+package xiaozhi.modules.model.service.impl;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.mockStatic;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import java.util.List;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+import org.junit.jupiter.params.provider.ValueSource;
+import org.mockito.ArgumentCaptor;
+import org.mockito.MockedStatic;
+
+import xiaozhi.common.exception.ErrorCode;
+import xiaozhi.common.exception.RenException;
+import xiaozhi.common.redis.RedisUtils;
+import xiaozhi.common.utils.MessageUtils;
+import xiaozhi.modules.agent.dao.AgentDao;
+import xiaozhi.modules.model.dao.ModelConfigDao;
+import xiaozhi.modules.model.dto.ModelConfigBodyDTO;
+import xiaozhi.modules.model.dto.ModelConfigDTO;
+import xiaozhi.modules.model.dto.ModelProviderDTO;
+import xiaozhi.modules.model.entity.ModelConfigEntity;
+import xiaozhi.modules.model.service.ModelProviderService;
+
+class ModelConfigServiceImplTest {
+
+    private ModelConfigDao modelConfigDao;
+    private ModelProviderService modelProviderService;
+    private ModelConfigServiceImpl service;
+
+    @BeforeEach
+    void setUp() {
+        modelConfigDao = mock(ModelConfigDao.class);
+        modelProviderService = mock(ModelProviderService.class);
+        service = new ModelConfigServiceImpl(
+                modelConfigDao, modelProviderService, mock(RedisUtils.class), mock(AgentDao.class));
+    }
+
+    @ParameterizedTest
+    @CsvSource({
+            "vad, VAD", "asr, ASR", "tts, TTS", "llm, LLM", "vllm, VLLM",
+            "memory, Memory", "intent, Intent", "rag, RAG", "LLM, LLM"
+    })
+    void addPreservesRegisteredProviderModelType(String requestedType, String registeredType) {
+        registerProvider(requestedType, registeredType);
+
+        ModelConfigDTO result = service.add(requestedType, "test-provider", modelBody());
+
+        ArgumentCaptor<ModelConfigEntity> saved = ArgumentCaptor.forClass(ModelConfigEntity.class);
+        verify(modelConfigDao).insert(saved.capture());
+        assertEquals(registeredType, saved.getValue().getModelType());
+        assertEquals(registeredType, result.getModelType());
+    }
+
+    @ParameterizedTest
+    @CsvSource({
+            "vad, VAD", "asr, ASR", "tts, TTS", "llm, LLM", "vllm, VLLM",
+            "memory, Memory", "intent, Intent", "rag, RAG", "LLM, LLM"
+    })
+    void editPreservesRegisteredProviderModelType(String requestedType, String registeredType) {
+        registerProvider(requestedType, registeredType);
+        ModelConfigEntity original = new ModelConfigEntity();
+        original.setId("test-model");
+        original.setModelType(registeredType);
+        when(modelConfigDao.selectById("test-model")).thenReturn(original);
+
+        ModelConfigDTO result = service.edit(requestedType, "test-provider", "test-model", modelBody());
+
+        ArgumentCaptor<ModelConfigEntity> saved = ArgumentCaptor.forClass(ModelConfigEntity.class);
+        verify(modelConfigDao).updateById(saved.capture());
+        assertEquals(registeredType, saved.getValue().getModelType());
+        assertEquals(registeredType, result.getModelType());
+    }
+
+    @ParameterizedTest
+    @ValueSource(booleans = {false, true})
+    void rejectsUnknownProviderBeforeWriting(boolean editing) {
+        when(modelProviderService.getList("tts", "missing")).thenReturn(List.of());
+
+        try (MockedStatic<MessageUtils> messages = mockStatic(MessageUtils.class)) {
+            messages.when(() -> MessageUtils.getMessage(ErrorCode.MODEL_PROVIDER_NOT_EXIST))
+                    .thenReturn("Model provider does not exist");
+            RenException error = assertThrows(RenException.class, () -> {
+                if (editing) {
+                    service.edit("tts", "missing", "test-model", modelBody());
+                } else {
+                    service.add("tts", "missing", modelBody());
+                }
+            });
+            assertEquals(ErrorCode.MODEL_PROVIDER_NOT_EXIST, error.getCode());
+        }
+
+        verify(modelConfigDao, never()).insert(any(ModelConfigEntity.class));
+        verify(modelConfigDao, never()).updateById(any(ModelConfigEntity.class));
+    }
+
+    private void registerProvider(String requestedType, String registeredType) {
+        ModelProviderDTO provider = new ModelProviderDTO();
+        provider.setModelType(registeredType);
+        provider.setProviderCode("test-provider");
+        when(modelProviderService.getList(requestedType, "test-provider")).thenReturn(List.of(provider));
+    }
+
+    private ModelConfigBodyDTO modelBody() {
+        ModelConfigBodyDTO body = new ModelConfigBodyDTO();
+        body.setId("test-model");
+        body.setModelName("Test model");
+        body.setIsEnabled(1);
+        body.setSort(1);
+        return body;
+    }
+}
@@ -4,6 +4,7 @@ import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.mockito.Mockito.when;

+import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.test.context.SpringBootTest;
@@ -18,12 +19,18 @@ import xiaozhi.modules.security.dto.LoginDTO;
 import xiaozhi.modules.security.dto.SmsVerificationDTO;
 import xiaozhi.modules.sys.dto.RetrievePasswordDTO;
 import xiaozhi.modules.sys.service.SysUserService;
+import xiaozhi.testsupport.IntegrationTestEnvironment;

@Slf4j
@SpringBootTest
@ActiveProfiles("dev")
 class loginControllerTest {

+    @BeforeAll
+    static void checkDependencies() {
+        IntegrationTestEnvironment.requireDatabaseAndRedis();
+    }
+
    @Autowired
    LoginController loginController;

@@ -0,0 +1,149 @@
+package xiaozhi.testsupport;
+
+import java.io.IOException;
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.time.Duration;
+
+import org.junit.jupiter.api.Assumptions;
+import org.springframework.boot.env.YamlPropertySourceLoader;
+import org.springframework.core.env.ConfigurableEnvironment;
+import org.springframework.core.env.PropertySource;
+import org.springframework.core.env.PropertySourcesPropertyResolver;
+import org.springframework.core.env.StandardEnvironment;
+import org.springframework.core.io.ClassPathResource;
+import org.springframework.core.io.Resource;
+
+import io.lettuce.core.RedisClient;
+import io.lettuce.core.RedisURI;
+import io.lettuce.core.api.StatefulRedisConnection;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * 几个 @SpringBootTest 要真连 MySQL 和 Redis。本地没起这两个依赖时，
+ * 整类测试跳过，别让 Spring 上下文起不来变成一堆看不懂的报错；
+ * CI 里依赖必须真的在，探不通就直接让构建红。
+ */
+@Slf4j
+public final class IntegrationTestEnvironment {
+
+    /** 集成测试用的配置文件，跟应用本身读的是同一套 */
+    private static final String[] CONFIG_FILES = {"application.yml", "application-dev.yml"};
+
+    private static Boolean available;
+    private static String problem;
+
+    private IntegrationTestEnvironment() {
+    }
+
+    /**
+     * 放在要连库的测试类的 @BeforeAll 里。
+     * 本地依赖不齐就整类跳过，CI 里依赖不齐就直接失败。
+     */
+    public static void requireDatabaseAndRedis() {
+        String issue = probe();
+        if (issue == null) {
+            return;
+        }
+        if (isCi()) {
+            throw new IllegalStateException(
+                    "CI 环境里" + issue + "，这几个集成测试必须真的跑起来，不能跳过");
+        }
+        log.warn("跳过依赖 MySQL 和 Redis 的集成测试：{}", issue);
+        Assumptions.assumeTrue(false, issue);
+    }
+
+    /** GitHub Actions 上会带 CI=true */
+    public static boolean isCi() {
+        String value = System.getenv("CI");
+        if (value == null) {
+            return false;
+        }
+        String trimmed = value.trim();
+        return !trimmed.isEmpty() && !"false".equalsIgnoreCase(trimmed);
+    }
+
+    /** 依赖都齐返回 null，不齐返回缺什么 */
+    static synchronized String probe() {
+        if (available != null) {
+            return problem;
+        }
+        PropertySourcesPropertyResolver resolver = resolver();
+        StringBuilder issues = new StringBuilder();
+
+        String url = firstNonBlank(resolver.getProperty("spring.datasource.druid.url", ""),
+                resolver.getProperty("spring.datasource.url", ""));
+        String username = firstNonBlank(resolver.getProperty("spring.datasource.druid.username", ""),
+                resolver.getProperty("spring.datasource.username", ""));
+        String password = firstNonBlank(resolver.getProperty("spring.datasource.druid.password", ""),
+                resolver.getProperty("spring.datasource.password", ""));
+        if (url.isBlank()) {
+            issues.append("配置里找不到数据源地址；");
+        } else {
+            try {
+                DriverManager.setLoginTimeout(5);
+                try (Connection connection = DriverManager.getConnection(url, username, password)) {
+                    connection.isValid(3);
+                }
+            } catch (Exception e) {
+                issues.append("连不上 MySQL（").append(e.getMessage()).append("）；");
+            }
+        }
+
+        String redisHost = resolver.getProperty("spring.data.redis.host", "localhost");
+        int redisPort = resolver.getProperty("spring.data.redis.port", Integer.class, 6379);
+        String redisPassword = resolver.getProperty("spring.data.redis.password", "");
+        try {
+            RedisURI.Builder builder = RedisURI.builder()
+                    .withHost(redisHost)
+                    .withPort(redisPort)
+                    .withTimeout(Duration.ofSeconds(3));
+            if (redisPassword != null && !redisPassword.isBlank()) {
+                builder.withPassword(redisPassword.toCharArray());
+            }
+            RedisClient client = RedisClient.create(builder.build());
+            try {
+                StatefulRedisConnection<String, String> connection = client.connect();
+                connection.sync().ping();
+                connection.close();
+            } finally {
+                client.shutdown();
+            }
+        } catch (Exception e) {
+            issues.append("连不上 Redis（").append(e.getMessage()).append("）；");
+        }
+
+        if (issues.length() == 0) {
+            available = Boolean.TRUE;
+            problem = null;
+        } else {
+            available = Boolean.FALSE;
+            problem = issues.toString();
+        }
+        return problem;
+    }
+
+    /** 读应用自己那份配置，命令行上的 -D 参数优先级更高，跟应用保持一致 */
+    private static PropertySourcesPropertyResolver resolver() {
+        ConfigurableEnvironment environment = new StandardEnvironment();
+        YamlPropertySourceLoader loader = new YamlPropertySourceLoader();
+        for (String name : CONFIG_FILES) {
+            Resource resource = new ClassPathResource(name);
+            if (!resource.exists()) {
+                continue;
+            }
+            try {
+                for (PropertySource<?> source : loader.load(name, resource)) {
+                    environment.getPropertySources().addLast(source);
+                }
+            } catch (IOException e) {
+                log.warn("读配置 {} 失败：{}", name, e.getMessage());
+            }
+        }
+        return new PropertySourcesPropertyResolver(environment.getPropertySources());
+    }
+
+    private static String firstNonBlank(String first, String second) {
+        return first != null && !first.isBlank() ? first : (second == null ? "" : second);
+    }
+}
@@ -265,7 +265,7 @@ function showAbout() {
    title: t('settings.aboutApp', { appName: import.meta.env.VITE_APP_TITLE }),
    content: t('settings.aboutContent', {
      appName: import.meta.env.VITE_APP_TITLE,
-      version: '0.9.7',
+      version: '0.9.8',
    }),
    showCancel: false,
    confirmText: t('common.confirm'),
@@ -1,6 +1,7 @@
 import Fly from 'flyio/dist/npm/fly';
 import store from '../store/index';
 import Constant from '../utils/constant';
+import { getServiceUrl } from '../apis/api';
 import { goToPage, isNotNull, showDanger, showWarning } from '../utils/index';
 import i18n from '../i18n/index';

@@ -8,13 +9,98 @@ const fly = new Fly()
 // 设置超时
 fly.config.timeout = 30000

+// 独立 fly 实例给 silent refresh 用，避免任何回调链回到 sendRequest
+const refreshFly = new Fly()
+refreshFly.config.timeout = 30000
+
+// silent refresh：剩 1h 触发换 token，单飞锁避免并发
+const REFRESH_AHEAD_MS = 60 * 60 * 1000
+let refreshPromise = null
+
+function getTokenExpireAt() {
+    // 与 persistTokenExpireAt 同源读 localStorage（store 走的是 state.token 缓存，
+    // 刚写入 localStorage 后再走 store 拿不到补写的 _localStoredAt）
+    const raw = localStorage.getItem('token')
+    if (!raw) return 0
+    try {
+        const parsed = JSON.parse(raw)
+        if (!parsed || !parsed.expire) return 0
+        // login.vue 写入 store 时是 setToken(now)，token 对象里没有 createdAt；
+        // 用 _localStoredAt 作为本地落地时间基准
+        return (parsed._localStoredAt || 0) + parsed.expire * 1000
+    } catch (e) {
+        return 0
+    }
+}
+
+// 首次见到该 token 时记下落地时间；同步刷新 localStorage 与 store，保证两端一致
+function persistTokenExpireAt() {
+    const raw = localStorage.getItem('token')
+    if (!raw) return
+    try {
+        const parsed = JSON.parse(raw)
+        if (parsed && parsed.expire && !parsed._localStoredAt) {
+            parsed._localStoredAt = Date.now()
+            const next = JSON.stringify(parsed)
+            localStorage.setItem('token', next)
+            store.commit('setToken', next)
+        }
+    } catch (e) { /* ignore */ }
+}
+
+function shouldRefresh() {
+    persistTokenExpireAt()
+    const exp = getTokenExpireAt()
+    if (!exp) return false
+    return exp - Date.now() < REFRESH_AHEAD_MS
+}
+
+function doRefresh() {
+    // 直接走 fly.request，绕过 sendRequest，避免死循环触发 silent refresh
+    const raw = localStorage.getItem('token')
+    if (!raw) return Promise.reject(new Error('no token'))
+    let bearer
+    try {
+        bearer = JSON.parse(raw).token
+    } catch (e) {
+        return Promise.reject(e)
+    }
+    return refreshFly.request(getServiceUrl() + '/user/refresh', {}, {
+        method: 'POST',
+        headers: { Authorization: 'Bearer ' + bearer }
+    }).then((res) => {
+        const body = res && res.data
+        if (!body || (body.code !== 0 && body.code !== 'success')) {
+            throw new Error('refresh failed: ' + (body && body.msg))
+        }
+        const newDto = body.data
+        newDto._localStoredAt = Date.now()
+        store.commit('setToken', JSON.stringify(newDto))
+        return newDto
+    })
+}
+
+function triggerSilentRefresh() {
+    if (!refreshPromise) {
+        refreshPromise = doRefresh().catch((err) => {
+            store.commit('clearAuth')
+            goToPage(Constant.PAGE.LOGIN, true)
+            throw err
+        }).finally(() => {
+            refreshPromise = null
+        })
+    }
+    return refreshPromise
+}
+
 /**
 * Request服务封装
 */
 export default {
    sendRequest,
    reAjaxFun,
-    clearRequestTime
+    clearRequestTime,
+    triggerSilentRefresh
 }

 function sendRequest() {
@@ -37,30 +123,41 @@ function sendRequest() {
                acceptLanguage = 'en-US';
            }
            this._header['Accept-Language'] = acceptLanguage;
-            
-            if (isNotNull(store.getters.getToken)) {
-                this._header.Authorization = 'Bearer ' + (JSON.parse(store.getters.getToken)).token
+
+            const doSend = () => {
+                if (isNotNull(store.getters.getToken)) {
+                    this._header.Authorization = 'Bearer ' + (JSON.parse(store.getters.getToken)).token
+                }
+
+                // 打印请求信息
+                fly.request(this._url, this._data, {
+                    method: this._method,
+                    headers: this._header,
+                    responseType: this._responseType
+                }).then((res) => {
+                    const error = httpHandlerError(res, this._failCallback, this._networkFailCallback);
+                    if (error) {
+                        return
+                    }
+
+                    if (this._sucCallback) {
+                        this._sucCallback(res)
+                    }
+                }).catch((res) => {
+                    // 打印失败响应
+                    console.log('catch', res)
+                    httpHandlerError(res, this._failCallback, this._networkFailCallback)
+                })
            }

-            // 打印请求信息
-            fly.request(this._url, this._data, {
-                method: this._method,
-                headers: this._header,
-                responseType: this._responseType
-            }).then((res) => {
-                const error = httpHandlerError(res, this._failCallback, this._networkFailCallback);
-                if (error) {
-                    return
-                }
-
-                if (this._sucCallback) {
-                    this._sucCallback(res)
-                }
-            }).catch((res) => {
-                // 打印失败响应
-                console.log('catch', res)
-                httpHandlerError(res, this._failCallback, this._networkFailCallback)
-            })
+            // 剩 1h 内过期就先 silent refresh 再发，确保请求带新 token
+            if (shouldRefresh()) {
+                triggerSilentRefresh().then(doSend).catch(() => {
+                    // 触发 refresh 后被拦截跳登录，这里什么都不用做
+                })
+            } else {
+                doSend()
+            }
            return this
        },
        'success'(callback) {
@@ -77,7 +77,10 @@
      <el-form :model="formData.configJson" label-width="auto" label-position="left" class="custom-form">
        <div v-for="(row, rowIndex) in chunkedCallInfoFields" :key="rowIndex" class="form-row">
          <el-form-item v-for="field in row" :key="field.prop" :label="field.label" :prop="field.prop" style="flex: 1;">
-            <el-input v-model="formData.configJson[field.prop]" :placeholder="field.placeholder"
+            <el-input v-if="field.type === 'json-textarea'" v-model="formData.configJson[field.prop]" type="textarea"
+              :rows="3" :placeholder="field.placeholder" class="custom-input-bg">
+            </el-input>
+            <el-input v-else v-model="formData.configJson[field.prop]" :placeholder="field.placeholder"
              :type="field.type || 'text'" class="custom-input-bg" :show-password="field.type === 'password'">
            </el-input>
          </el-form-item>
@@ -161,7 +164,7 @@ export default {
          fields: JSON.parse(item.fields || '[]').map(f => ({
            label: f.label,
            prop: f.key,
-            type: f.type === 'password' ? 'password' : 'text',
+            type: f.type === 'dict' ? 'json-textarea' : f.type === 'password' ? 'password' : 'text',
            placeholder: `请输入${f.key}`
          }))
        }))
@@ -204,6 +207,24 @@ export default {
        return;
      }

+      // dict 字段必须解析为 JSON 对象再提交，否则会以字符串入库
+      for (const field of this.providerFields) {
+        if (field.type !== 'json-textarea') continue;
+        const raw = this.formData.configJson[field.prop];
+        if (!raw || typeof raw === 'object') continue;
+        try {
+          const parsed = JSON.parse(raw);
+          if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('not object');
+          }
+          this.formData.configJson[field.prop] = parsed;
+        } catch (e) {
+          this.$message.error('必须输入字典格式（如 {"key":"value"}）');
+          this.saving = false;
+          return;
+        }
+      }
+
      const submitData = {
        id: this.formData.id || '',
        modelName: this.formData.modelName || '',
@@ -330,6 +330,17 @@ export default {
        if (!configJson.hasOwnProperty(field.prop)) {
          configJson[field.prop] = "";
        } else if (field.type === "json-textarea") {
+          // 兼容已保存为 JSON 字符串的字典，避免再次序列化后无法编辑。
+          if (typeof configJson[field.prop] === "string") {
+            try {
+              const parsed = JSON.parse(configJson[field.prop]);
+              if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+                configJson[field.prop] = parsed;
+              }
+            } catch {
+              // 保留非法值的显示，由现有校验提示用户修正。
+            }
+          }
          this.$set(
            this.fieldJsonMap,
            field.prop,
@@ -22,6 +22,13 @@ Vue.config.productionTip = false
 // 注册Service Worker
 registerServiceWorker();

+// 应用启动时把 localStorage 里的 token 同步进 store，避免守卫放行后首次请求时
+// httpRequest 读到 state.token=null 而漏带 Authorization 头触发 401 跳登录
+const cachedToken = localStorage.getItem('token')
+if (cachedToken) {
+  store.commit('setToken', cachedToken)
+}
+
 // 创建Vue实例
 new Vue({
  router,
@@ -613,6 +613,8 @@ export default {
 .nav-panel {
  min-width: 242px;
  height: 100%;
+  box-sizing: border-box;
+  overflow-y: auto;
  border-right: 1px solid #ebeef5;
  background: linear-gradient(
      120deg,
@@ -629,6 +631,7 @@ export default {

 .nav-panel .el-menu-item {
  height: 50px;
+  flex-shrink: 0;
  background: #e9f0ff;
  line-height: 50px;
  border-radius: 4px 0 0 4px !important;
@@ -14,6 +14,10 @@ const functionDialogSource = await readFile(
  new URL('../src/components/FunctionDialog.vue', import.meta.url),
  'utf8',
 );
+const modelConfigSource = await readFile(
+  new URL('../src/views/ModelConfig.vue', import.meta.url),
+  'utf8',
+);

 test('address-book permission state consistently uses the target device MAC', () => {
  assert.match(
@@ -66,6 +70,74 @@ test('correct-word pagination maps the UI page size to the backend limit query',
  assert.doesNotMatch(correctWordApiSource, /pageSize: params\.pageSize/);
 });

+test('model navigation keeps its scrollable layout declarations', () => {
+  const navStyles = modelConfigSource.match(/\.nav-panel\s*\{([^}]*)\}/)?.[1];
+  const itemStyles = modelConfigSource.match(
+    /\.nav-panel\s+\.el-menu-item\s*\{([^}]*)\}/,
+  )?.[1];
+
+  assert.ok(navStyles, 'model navigation should define its layout');
+  assert.ok(itemStyles, 'model menu items should define their layout');
+  const wrapperStyles = modelConfigSource.match(/\.main-wrapper\s*\{([^}]*)\}/)?.[1];
+  assert.ok(wrapperStyles, 'model page wrapper should define its height');
+
+  assert.match(navStyles, /box-sizing:\s*border-box;/);
+  assert.match(navStyles, /overflow-y:\s*auto;/);
+  assert.match(navStyles, /display:\s*flex;/);
+  assert.match(navStyles, /flex-direction:\s*column;/);
+  assert.match(itemStyles, /flex-shrink:\s*0;/);
+  assert.match(wrapperStyles, /height:\s*calc\([^)]*vh[^)]*\)/);
+
+  // 断言只取第一条同名规则，后面再补一条就能盖掉上面三条，必须挡住
+  assert.equal(
+    (modelConfigSource.match(/\.nav-panel\s*\{/g) || []).length,
+    1,
+    'model navigation should keep a single rule',
+  );
+  assert.equal(
+    (modelConfigSource.match(/\.nav-panel\s+\.el-menu-item\s*\{/g) || []).length,
+    1,
+    'model menu items should keep a single rule',
+  );
+  // 复合选择器特异性更高，能直接盖掉可滚属性
+  assert.equal(
+    (modelConfigSource.match(/\.nav-panel[.:\[#][^{}]*\{/g) || []).length,
+    0,
+    'model navigation should not use composite selectors',
+  );
+
+  const styleSource = modelConfigSource.match(/<style[^>]*>([\s\S]*?)<\/style>/)?.[1];
+  assert.ok(styleSource, 'model config should define its styles');
+  const ruleSelectors = styleSource
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\/\/[^\n]*/g, '')
+    .split('}')
+    .map((chunk) => {
+      const open = chunk.indexOf('{');
+      return open < 0 ? null : chunk.slice(0, open).trim();
+    })
+    .filter((selector) => selector && !selector.startsWith('@'));
+
+  // 上面几条挡不住带伪类的后代选择器（.nav-panel .el-menu-item:hover），
+  // 它特异性一样更高，照样能盖掉可滚属性，所以把 nav 相关的选择器逐条列出来核对
+  assert.deepEqual(
+    ruleSelectors.filter((selector) => selector.includes('.nav-panel')).sort(),
+    [
+      '.nav-panel',
+      '.nav-panel .el-menu-item',
+      '.nav-panel .el-menu-item.is-active',
+      '.nav-panel .el-menu-item.is-active::before',
+      '::v-deep .nav-panel .el-menu-item.is-active .menu-text',
+    ].sort(),
+    'model navigation should keep its declared rules',
+  );
+  assert.deepEqual(
+    ruleSelectors.filter((selector) => selector.includes('.main-wrapper')),
+    ['.main-wrapper'],
+    'model page wrapper should keep a single rule',
+  );
+});
+
 test('function dialog footer stays above the expanding MCP tools section', () => {
  const mcpLayer = functionDialogSource.match(
    /\.mcp-access-point\s*\{[^}]*z-index:\s*(\d+);/s,
@@ -0,0 +1,79 @@
+import Vue from 'vue';
+import { parseComponent } from 'vue-template-compiler';
+import { describe, expect, it, vi } from 'vitest';
+import source from '../src/components/AddModelDialog.vue?raw';
+
+// The unit-test runner has no Vue SFC plugin. Load the real component's script
+// with its API and dialog dependencies stubbed; keep Vue's reactivity.
+const script = parseComponent(source).script.content
+  .replace(/^import .*;$/gm, '')
+  .replace('export default', 'return');
+const component = new Function('CustomDialog', 'Api', script)({}, {});
+
+function makeVm() {
+  const vm = new Vue({
+    ...component,
+    propsData: { visible: false, modelType: 'TTS' },
+  });
+  vm.$message = { error: vi.fn() };
+  vm.$t = (key) => key;
+  vm.providerFields = [
+    { label: '音量', prop: 'volume', type: 'json-textarea', placeholder: '请输入volume' },
+    { label: '密钥', prop: 'api_key', type: 'password', placeholder: '请输入api_key' },
+  ];
+  vm.formData.supplier = 'test-provider';
+  return vm;
+}
+
+function submitted(vm) {
+  let captured;
+  vm.$on('confirm', (data) => {
+    captured = data;
+  });
+  vm.confirm();
+  return captured;
+}
+
+describe('add dialog dict fields', () => {
+  it('parses valid JSON dict input into an object before submit', () => {
+    const vm = makeVm();
+    vm.formData.configJson = { volume: '{"speed":1,"volume":10}', api_key: 'sk-xxx' };
+
+    const data = submitted(vm);
+
+    expect(data.configJson.volume).toEqual({ speed: 1, volume: 10 });
+    expect(data.configJson.api_key).toBe('sk-xxx');
+    expect(vm.$message.error).not.toHaveBeenCalled();
+  });
+
+  it('blocks invalid JSON input and does not emit confirm', () => {
+    const vm = makeVm();
+    vm.formData.configJson = { volume: '{bad json', api_key: 'sk-xxx' };
+
+    expect(submitted(vm)).toBeUndefined();
+    expect(vm.$message.error).toHaveBeenCalled();
+  });
+
+  it.each(['[1,2]', 'null', '"text"', '1'])(
+    'blocks non-object JSON %s',
+    (value) => {
+      const vm = makeVm();
+      vm.formData.configJson = { volume: value, api_key: 'sk-xxx' };
+
+      expect(submitted(vm)).toBeUndefined();
+      expect(vm.$message.error).toHaveBeenCalled();
+    },
+  );
+
+  it('leaves empty strings and existing object values untouched', () => {
+    const vm = makeVm();
+    const obj = { speed: 2 };
+    vm.formData.configJson = { volume: obj, api_key: '' };
+
+    const data = submitted(vm);
+
+    expect(data.configJson.volume).toBe(obj);
+    expect(data.configJson.api_key).toBe('');
+    expect(vm.$message.error).not.toHaveBeenCalled();
+  });
+});
@@ -0,0 +1,98 @@
+import Vue from 'vue';
+import { parseComponent } from 'vue-template-compiler';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import source from '../src/components/ModelEditDialog.vue?raw';
+
+// The unit-test runner has no Vue SFC plugin. Load the real component's script
+// with its API and child-dialog dependencies stubbed; keep Vue's reactivity.
+const script = parseComponent(source).script.content
+  .replace(/^import .*;$/gm, '')
+  .replace('export default', 'return');
+const component = new Function('CustomDialog', 'Api', script)({}, {});
+
+let vm;
+let saved;
+
+function openModel(value) {
+  vm.processModelData({
+    id: 'test-model',
+    modelName: 'Test model',
+    configJson: { type: 'test-provider', prosody: value },
+  });
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vm = new Vue({
+    ...component,
+    propsData: { modelType: 'TTS', modelData: { id: 'test-model' } },
+  });
+  vm.$message = { error: vi.fn() };
+  vm.dynamicCallInfoFields = [{ prop: 'prosody', type: 'json-textarea' }];
+  saved = vi.fn();
+  vm.$on('save', saved);
+});
+
+afterEach(() => {
+  vm.$destroy();
+  vi.clearAllTimers();
+  vi.useRealTimers();
+});
+
+describe('stored dictionary fields', () => {
+  it('opens a JSON string as an editable dictionary instead of a quoted string', () => {
+    openModel('{"speed":1,"volume":10}');
+
+    expect(JSON.parse(vm.fieldJsonMap.prosody)).toEqual({ speed: 1, volume: 10 });
+    expect(vm.form.configJson.prosody).toEqual({ speed: 1, volume: 10 });
+  });
+
+  it('preserves a stored JSON string when saving without changes', () => {
+    openModel('{"speed":1,"volume":10}');
+    vm.handleSave();
+
+    expect(vm.$message.error).not.toHaveBeenCalled();
+    expect(saved.mock.calls[0][0].formData.configJson.prosody).toEqual({
+      speed: 1,
+      volume: 10,
+    });
+  });
+
+  it('keeps edits after saving and reopening the returned object', () => {
+    openModel('{"speed":1,"volume":10}');
+    vm.fieldJsonMap.prosody = '{"speed":2,"volume":5}';
+    vm.handleSave();
+    const config = saved.mock.calls[0][0].formData.configJson;
+
+    vm.resetForm();
+    openModel(JSON.parse(JSON.stringify(config.prosody)));
+    vm.handleSave();
+
+    expect(JSON.parse(vm.fieldJsonMap.prosody)).toEqual({ speed: 2, volume: 5 });
+    expect(saved.mock.calls[1][0].formData.configJson.prosody).toEqual({
+      speed: 2,
+      volume: 5,
+    });
+    expect(vm.$message.error).not.toHaveBeenCalled();
+  });
+
+  it('preserves nested values and masked secrets in existing dictionary objects', () => {
+    const value = { speed: 0, enabled: false, nested: { api_key: 'ab****yz' }, tags: ['a'] };
+    openModel(value);
+    vm.handleSave();
+
+    expect(saved.mock.calls[0][0].formData.configJson.prosody).toEqual(value);
+    expect(vm.$message.error).not.toHaveBeenCalled();
+  });
+
+  it.each(['not json', 'null', '[]', '1', 'true', '"text"'])(
+    'does not reinterpret %s as a dictionary',
+    (value) => {
+      openModel(value);
+
+      expect(JSON.parse(vm.fieldJsonMap.prosody)).toBe(value);
+      expect(vm.validateJson(vm.fieldJsonMap.prosody)).toBeNull();
+      expect(vm.$message.error).toHaveBeenCalled();
+    },
+  );
+});
@@ -6,7 +6,7 @@ from config.config_loader import load_config
 from config.settings import check_config_file
 from core.utils.cache.manager import cache_manager, CacheType

-SERVER_VERSION = "0.9.7"
+SERVER_VERSION = "0.9.8"
 _logger_initialized = False


@@ -8,7 +8,7 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
    from core.connection import ConnectionHandler
 from core.utils.dialogue import Message
-from core.utils.util import audio_to_data
+from core.utils.util import audio_to_data, audio_file_to_wav_bytes
 from core.providers.tts.dto.dto import SentenceType
 from core.utils.wakeup_word import WakeupWordsConfig
 from core.handle.sendAudioHandle import sendAudioMessage, send_tts_message
@@ -148,8 +148,13 @@ async def wakeupWordsResponse(conn: "ConnectionHandler"):
        # 获取当前音色
        voice = getattr(conn.tts, "voice", "default")

-        # 使用链接的sample_rate
-        wav_bytes = opus_datas_to_wav_bytes(tts_result, sample_rate=conn.sample_rate)
+        # 保留的 TTS 音频是文件路径而非 Opus 帧：直接转目标采样率 wav，跳过有损 Opus 往返
+        if isinstance(tts_result, str):
+            wav_bytes = await asyncio.to_thread(
+                audio_file_to_wav_bytes, tts_result, conn.sample_rate
+            )
+        else:
+            wav_bytes = opus_datas_to_wav_bytes(tts_result, sample_rate=conn.sample_rate)
        file_path = wakeup_words_config.generate_file_path(voice)
        with open(file_path, "wb") as f:
            f.write(wav_bytes)
@@ -10,12 +10,13 @@ import concurrent.futures
 from contextlib import AsyncExitStack
 from typing import Optional, List, Dict, Any

+import httpx2
 from mcp import ClientSession, StdioServerParameters, Implementation
 from mcp.client.session import SamplingFnT, ElicitationFnT, ListRootsFnT, LoggingFnT, MessageHandlerFnT
 from mcp.client.stdio import stdio_client
 from mcp.client.sse import sse_client
-from mcp.client.streamable_http import streamablehttp_client
-from mcp.shared.session import ProgressFnT
+from mcp.client.streamable_http import streamable_http_client
+from mcp.shared.dispatcher import ProgressFnT  # mcp 2.x：从 mcp.shared.session 移来

 from config.logger import setup_logging
 from core.utils.util import sanitize_tool_name
@@ -203,13 +204,21 @@ class ServerMCPClient:

                    if transport_type == "streamable-http" or transport_type == "http":
                        # 使用 Streamable HTTP 传输
-                        http_r, http_w, get_session_id = await stack.enter_async_context(
-                            streamablehttp_client(
+                        # mcp 2.x：headers/timeout 改由 http_client 承载，产出从 3 元组变为 2 元组
+                        http_client = httpx2.AsyncClient(
+                            headers=headers,
+                            timeout=httpx2.Timeout(
+                                self.config.get("timeout", 30),
+                                read=self.config.get("sse_read_timeout", 60 * 5),
+                            ),
+                        )
+                        stack.push_async_callback(http_client.aclose)
+
+                        http_r, http_w = await stack.enter_async_context(
+                            streamable_http_client(
                                url=self.config["url"],
-                                headers=headers,
-                                timeout=self.config.get("timeout", 30),
-                                sse_read_timeout=self.config.get("sse_read_timeout", 60 * 5),
-                                terminate_on_close=self.config.get("terminate_on_close", True)
+                                http_client=http_client,
+                                terminate_on_close=self.config.get("terminate_on_close", True),
                            )
                        )
                        read_stream, write_stream = http_r, http_w
@@ -144,6 +144,7 @@ class TTSProvider(TTSProviderBase):
        self.ws = None
        self.interface_type = InterfaceType.DUAL_STREAM
        self._monitor_task = None  # 监听任务引用
+        self._pending_prefix = ""
        self.appId = config.get("appid")
        self.access_token = config.get("access_token")
        self.cluster = config.get("cluster")
@@ -306,6 +307,9 @@ class TTSProvider(TTSProviderBase):
                if message.sentence_type == SentenceType.FIRST:
                    # 重置流式处理状态
                    self.reset_stream_state()
+                    # 重置 opus 流式编码器跨轮残留
+                    if hasattr(self, "opus_encoder") and self.opus_encoder:
+                        self.opus_encoder.reset_state()
                    # 初始化参数
                    try:
                        if not getattr(self.conn, "sentence_id", None): 
@@ -433,6 +437,9 @@ class TTSProvider(TTSProviderBase):
        logger.bind(tag=TAG).debug(f"关闭会话～～{session_id}")
        try:
            if self.ws:
+                # 句尾替换词滑动窗口残留先发出去
+                if self._pending_prefix:
+                    await self.text_to_speak(self._pending_prefix, None)
                header = Header(
                    message_type=FULL_CLIENT_REQUEST,
                    message_type_specific_flags=MsgTypeFlagWithEvent,
@@ -490,7 +497,6 @@ class TTSProvider(TTSProviderBase):
        try:
            while not self.conn.stop_event.is_set():
                try:
-                    # 确保 `recv()` 运行在同一个 event loop
                    msg = await self.ws.recv()
                    res = self.parser_response(msg)
                    self.print_response(res, "send_text res:")
@@ -500,17 +506,18 @@ class TTSProvider(TTSProviderBase):
                        logger.bind(tag=TAG).debug(f"链接关闭成功～～")
                        break

-                    # 只处理当前活跃会话的响应
+                    # 只处理当前活跃会话的响应；旧会话事件不影响当前 activate_session
                    if res.optional.sessionId and self.conn.sentence_id != res.optional.sessionId:
-                        # 如果是会话结束相关事件，即使会话ID不匹配也要重置状态
-                        if res.optional.event in [EVENT_SessionCanceled, EVENT_SessionFailed, EVENT_SessionFinished]:
-                            logger.bind(tag=TAG).debug(f"收到残余下行结束响应重置会话状态～～")
-                            self.activate_session = False
                        continue

                    if res.optional.event == EVENT_SessionCanceled:
                        logger.bind(tag=TAG).debug(f"释放服务端资源成功～～")
                        self.activate_session = False
+                    elif res.optional.event == EVENT_SessionFailed:
+                        logger.bind(tag=TAG).error(
+                            f"TTS 会话被服务端拒绝: {self.conn.sentence_id}"
+                        )
+                        self.activate_session = False
                    elif not self.resource_type and res.optional.event == EVENT_TTSSentenceStart:
                        json_data = json.loads(res.payload.decode("utf-8"))
                        self.tts_text = json_data.get("text", "")
@@ -538,6 +545,11 @@ class TTSProvider(TTSProviderBase):
                        logger.bind(tag=TAG).info(f"句子语音生成成功：{self.tts_text}")
                    elif res.optional.event == EVENT_SessionFinished:
                        logger.bind(tag=TAG).debug(f"会话结束～～")
+                        # 句尾冲刷流式 opus 编码器不足一帧的 PCM 残量
+                        if hasattr(self, "opus_encoder") and self.opus_encoder:
+                            self.wav_to_opus_data_audio_raw_stream(
+                                b"", is_end=True, callback=self.handle_opus
+                            )
                        self.activate_session = False
                        self._process_before_stop_play_files()
                        # 非复用模式下，会话结束后发送 FinishConnection
@@ -552,16 +564,14 @@ class TTSProvider(TTSProviderBase):
                    )
                    traceback.print_exc()
                    break
-            # 连接异常时关闭WebSocket
+        finally:
+            # 退出时关闭连接并清理引用
            if self.ws:
                try:
                    await self.ws.close()
                except:
                    pass
                self.ws = None
-        # 监听任务退出时清理引用
-        finally:
-            self.activate_session = False
            self._monitor_task = None

    async def send_event(
@@ -619,21 +629,23 @@ class TTSProvider(TTSProviderBase):
        # 解析结果
        # header
        header = response.header
-        num = 0b00001111
-        header.protocol_version = res[0] >> 4 & num
+        mask = 0b00001111
+        header.protocol_version = res[0] >> 4 & mask
        header.header_size = res[0] & 0x0F
-        header.message_type = (res[1] >> 4) & num
+        header.message_type = (res[1] >> 4) & mask
        header.message_type_specific_flags = res[1] & 0x0F
-        header.serialization_method = res[2] >> num
+        header.serialization_method = res[2] >> 4
        header.message_compression = res[2] & 0x0F
        header.reserved = res[3]
        #
-        offset = 4
+        offset = header.header_size * 4
        optional = response.optional
-        if header.message_type == FULL_SERVER_RESPONSE or AUDIO_ONLY_RESPONSE:
+        if header.message_type in (FULL_SERVER_RESPONSE, AUDIO_ONLY_RESPONSE):
            # read event
            if header.message_type_specific_flags == MsgTypeFlagWithEvent:
-                optional.event = int.from_bytes(res[offset:8], "big", signed=True)
+                optional.event = int.from_bytes(
+                    res[offset : offset + 4], "big", signed=True
+                )
                offset += 4
                if optional.event == EVENT_NONE:
                    return response
@@ -644,10 +656,11 @@ class TTSProvider(TTSProviderBase):
                    optional.response_meta_json, offset = self.read_res_content(
                        res, offset
                    )
-                elif (
-                    optional.event == EVENT_SessionStarted
-                    or optional.event == EVENT_SessionFailed
-                    or optional.event == EVENT_SessionFinished
+                elif optional.event in (
+                    EVENT_SessionStarted,
+                    EVENT_SessionFailed,
+                    EVENT_SessionFinished,
+                    EVENT_SessionCanceled,
                ):
                    optional.sessionId, offset = self.read_res_content(res, offset)
                    optional.response_meta_json, offset = self.read_res_content(
@@ -820,6 +833,13 @@ class TTSProvider(TTSProviderBase):
                        ):
                            self.wav_to_opus_data_audio_raw_stream(res.payload, callback=lambda opus_frame: audio_data.append(opus_frame))
                        elif res.optional.event == EVENT_SessionFinished:
+                            # 句尾冲刷流式 opus 编码器不足一帧的 PCM 残量
+                            if hasattr(self, "opus_encoder") and self.opus_encoder:
+                                self.wav_to_opus_data_audio_raw_stream(
+                                    b"",
+                                    is_end=True,
+                                    callback=lambda opus_frame: audio_data.append(opus_frame),
+                                )
                            break

                finally:
@@ -475,6 +475,21 @@ def opus_datas_to_wav_bytes(opus_datas, sample_rate=16000, channels=1):
                pass


+def audio_file_to_wav_bytes(audio_file_path, sample_rate=16000):
+    """音频文件直接转目标采样率的 wav 字节流，不经 Opus 编解码，避免有损"""
+    file_type = os.path.splitext(audio_file_path)[1]
+    if file_type:
+        file_type = file_type.lstrip(".")
+    with _ffmpeg_path_override():
+        audio = AudioSegment.from_file(
+            audio_file_path, format=file_type, parameters=["-nostdin"]
+        )
+    audio = audio.set_channels(1).set_frame_rate(sample_rate).set_sample_width(2)
+    buffer = BytesIO()
+    audio.export(buffer, format="wav")
+    return buffer.getvalue()
+
+
 def check_vad_update(before_config, new_config):
    if (
        new_config.get("selected_module") is None
@@ -5,6 +5,9 @@ python_files = ["test_*.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
 addopts = "-ra"
+markers = [
+    "live_api: 需要真凭据或真网络的用例，mock 模式下由 conftest 剔除并列出",
+]
 filterwarnings = [
    "ignore::DeprecationWarning",
 ]
@@ -7,36 +7,38 @@ numpy==1.26.4
 websockets==14.2
 #--------- 以下是可升级的依赖
 pyyml==0.0.2
-silero_vad==6.2.1
+silero_vad==6.2.3
 opuslib_next==1.3.1
 pydub==0.25.1
-funasr==1.2.7
+funasr==1.4.16
+# transformers>=5 要求 torch>=2.6，与本项目 torch 2.2.2 冲突（会禁用 PyTorch，fun_local 加载不了模型）
+transformers<5
 openai==2.8.1
-google-generativeai==0.8.5
+google-generativeai==0.8.6
 edge_tts==7.3.1
 httpx==0.28.1
-aiohttp==3.13.2
+aiohttp==3.14.5
 aiohttp_cors==0.8.1
-ormsgpack==1.12.0
+ormsgpack==1.12.2
 ruamel.yaml==0.18.16
 loguru==0.7.3
-requests==2.32.5
+requests==2.34.2
 cozepy==0.20.0
-mem0ai==1.0.0
+mem0ai==2.2.1
 powermem>=0.3.1
 bs4==0.0.2
-modelscope==1.39.1
-sherpa_onnx==1.12.29
-mcp==1.22.0
-cnlunar==0.2.4
+modelscope==1.40.2
+sherpa_onnx==1.13.8
+mcp==2.3.0
+cnlunar==0.2.5
 PySocks==1.7.1
-dashscope==1.25.2
+dashscope==1.27.7
 baidu-aip==4.16.13
 aioconsole==0.8.2
-markitdown==0.1.3
+markitdown==0.1.8
 mcp-proxy==0.12.0
-PyJWT==2.10.1
-psutil==7.1.3
+PyJWT==2.15.1
+psutil==7.2.2
 portalocker==3.2.0  # 暂留 3.x：4.x 与 qdrant-client<1.20 的 portalocker<4.0 约束冲突 (PR #3360)
 Jinja2==3.1.6
 vosk==0.3.45
@@ -47,10 +47,29 @@ if str(_PROJECT_ROOT) not in sys.path:
 # ---------------------------------------------------------------------------
 try:
    import opuslib_next  # noqa: F401
-except Exception:
+except Exception as _opus_import_error:
+    # opuslib_next 是 ctypes 绑定，pip 装上的是纯 Python 包，真正的编解码靠系统里的
+    # libopus.so。runner 上没装 libopus 时 import 会失败，这里换桩顶上。
+    # 桩只能撑住 import 链路，真要编解码得先把 libopus 装上
+    # （apt-get install libopus0，正式镜像 Dockerfile-server-base 里也是这么装的）。
+    print(
+        f"[conftest] opuslib_next 不可用，改用桩：{_opus_import_error}",
+        flush=True,
+    )
+
+    def _opus_unavailable(_self, *_args, **_kwargs):
+        raise RuntimeError(
+            "libopus 没装，Opus 编解码跑不了。"
+            "装法：apt-get install libopus0（正式镜像 Dockerfile-server-base 里也是这么装的）"
+        )
+
    _stub = types.ModuleType("opuslib_next")
-    _stub.Encoder = type("Encoder", (), {"__init__": lambda *a, **kw: None})
-    _stub.Decoder = type("Decoder", (), {"__init__": lambda *a, **kw: None})
+    _stub.Encoder = type(
+        "Encoder", (), {"__init__": lambda *a, **kw: None, "encode": _opus_unavailable}
+    )
+    _stub.Decoder = type(
+        "Decoder", (), {"__init__": lambda *a, **kw: None, "decode": _opus_unavailable}
+    )
    _stub.APPLICATION_AUDIO = 0
    _stub.OpusError = type("OpusError", (Exception,), {})
    _stub.constants = types.SimpleNamespace()
@@ -70,6 +89,13 @@ _CUSTOM_CONFIG = Path(os.environ["PYTEST_CONFIG_FILE"]) if os.environ.get(
    "PYTEST_CONFIG_FILE"
 ) else _DEFAULT_CUSTOM

+# data/.config.yaml 在 .gitignore 里，本地没这个文件时现造一个空的。
+# 项目里好几个模块 import 的时候就要读它（config/logger.py 的 setup_logging
+# 直接抛 FileNotFoundError），缺了整份用例会收集不起来。CI 里也是这么造的
+_DEFAULT_CUSTOM.parent.mkdir(parents=True, exist_ok=True)
+if not _DEFAULT_CUSTOM.exists():
+    _DEFAULT_CUSTOM.write_text("{}\n", encoding="utf-8")
+

 def _load_via_file_merge() -> dict:
    """纯文件合并：config.yaml + data/.config.yaml。和生产单模块部署一致。"""
@@ -323,35 +349,25 @@ def _install_mock_layer() -> None:

    asyncio.sleep = _fast_sleep  # type: ignore[assignment]

-    # 网络层 mock：如果真实 httpx 已加载，把它的 AsyncClient.send 替换成
+    # 网络层 mock：如果真实 httpx 已加载，把它的 send 替换成
    # 立即抛 ConnectError 的桩，触发 ``_should_retry`` 走到 ``raise``，
    # 但避免真发请求。Live 模式完全不安装这层。
    if not LIVE_API_TESTS:
        try:
-            import httpx as _httpx  # noqa: F401
+            import httpx as _httpx

-            class _FakeAsyncClient:
-                def __init__(self, *args, **kwargs):
-                    pass
+            async def _fake_async_send(self, request, **kwargs):
+                raise _httpx.ConnectError("MOCK: connect refused")

-                async def send(self, *args, **kwargs):
-                    raise _httpx.ConnectError("MOCK: connect refused")
+            def _fake_send(self, request, **kwargs):
+                raise _httpx.ConnectError("MOCK: connect refused")

-                async def aclose(self):
-                    return None
-
-            class _FakeClient:
-                def __init__(self, *args, **kwargs):
-                    pass
-
-                def send(self, *args, **kwargs):
-                    raise _httpx.ConnectError("MOCK: connect refused")
-
-                def close(self):
-                    return None
-
-            _httpx.AsyncClient = _FakeAsyncClient  # type: ignore[misc]
-            _httpx.Client = _FakeClient  # type: ignore[misc]
+            # 只换 send 这一个方法，不换整个类。有些库（openai 2.x 的
+            # SyncHttpxClientWrapper）继承 httpx.Client 再自己拼请求，
+            # 整个类被换掉的话它们继承到的是假类，拼请求时直接
+            # AttributeError，报错还完全看不出是 mock 层的问题
+            _httpx.AsyncClient.send = _fake_async_send  # type: ignore[assignment]
+            _httpx.Client.send = _fake_send  # type: ignore[assignment]
        except ImportError:
            pass

@@ -437,9 +453,57 @@ if not LIVE_API_TESTS:
 import pytest  # noqa: E402  (after conftest hooks so pytest is initialised)


+def is_ci() -> bool:
+    """GitHub Actions 上会带 CI=true"""
+    value = os.environ.get("CI")
+    if value is None:
+        return False
+    trimmed = value.strip()
+    return bool(trimmed) and trimmed.lower() != "false"
+
+
+def skip_or_fail(reason: str) -> None:
+    """本地缺东西就跳过，CI 里缺东西直接让 job 挂掉。
+
+    口径跟 manager-api 那边的 IntegrationTestEnvironment 一致：本地没起依赖的
+    机器上跳过就行，不该把构建从绿变成红；CI 里依赖必须真的在，缺了就失败，
+    不许静默跳过 —— 静默跳过等于门禁被掏空，还看不出来。
+    """
+    if is_ci():
+        raise RuntimeError(f"CI 环境里{reason}，这条用例必须真的跑起来，不能跳过")
+    pytest.skip(reason)
+
+
 def pytest_collection_modifyitems(config, items):
-    """Live 模式下：``live_api`` 标记的测试必须配齐密钥才能跑（否则 skip）。"""
+    """Mock 模式下：``live_api`` 标记的用例要真凭据或真网络，不收，并列出是哪几条。
+
+    以前是在 CI 命令行上用 ``-k`` 排除，看不出排掉了什么、为什么排。
+    改成打标记 + 这里统一剔除，日志里会一条条列出来，剔了什么一目了然。
+    """
    if LIVE_API_TESTS:
        return
-    # Mock 模式下不强行 skip：测试应该都能跑（用 shim）。
-    return
+
+    keep = []
+    drop = []
+    for item in items:
+        if "live_api" in item.keywords:
+            drop.append(item)
+        else:
+            keep.append(item)
+
+    if not drop:
+        return
+
+    print(
+        "\n[conftest] 下面这些用例要真凭据或真网络，mock 模式下不收：",
+        flush=True,
+    )
+    for item in drop:
+        print(f"[conftest]   - {item.nodeid}", flush=True)
+    print(
+        "[conftest] 真请求模式：export RUN_LIVE_API_TESTS=1 并配好凭据后再跑。\n",
+        flush=True,
+    )
+
+    config.hook.pytest_deselected(items=drop)
+    items[:] = keep
@@ -0,0 +1,136 @@
+"""Wakeup caching accepts both return forms of TTSProviderBase.to_tts."""
+
+import asyncio
+import math
+import struct
+import wave
+from io import BytesIO
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+import pytest
+
+
+@pytest.fixture
+def wakeup_runtime(tmp_path, monkeypatch):
+    # conftest supplies local configuration; no deployment config is required.
+    from config import settings
+
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(settings, "config_file_valid", True)
+    from core.handle import helloHandle
+    from core.providers.tts.base import TTSProviderBase
+    from core.utils.wakeup_word import WakeupWordsConfig
+
+    class LocalTTS(TTSProviderBase):
+        """Replace only remote synthesis; keep the real file and Opus conversion."""
+
+        def __init__(self, output_dir, delete_audio_file):
+            super().__init__({"output_dir": str(output_dir)}, delete_audio_file)
+            self.voice = "test-voice"
+            self.filename = output_dir / "retained.wav"
+            buffer = BytesIO()
+            with wave.open(buffer, "wb") as audio:
+                audio.setnchannels(1)
+                audio.setsampwidth(2)
+                audio.setframerate(22050)
+                audio.writeframes(
+                    b"".join(
+                        struct.pack(
+                            "<h", int(8000 * math.sin(2 * math.pi * 440 * i / 22050))
+                        )
+                        # 1.1s 源音频：给重采样留裕量，规避重采样器 off-by-one
+                        for i in range(int(22050 * 1.1))
+                    )
+                )
+            self.audio_bytes = buffer.getvalue()
+
+        def generate_filename(self):
+            return str(self.filename)
+
+        async def text_to_speak(self, text, output_file):
+            if output_file is not None:
+                Path(output_file).write_bytes(self.audio_bytes)
+            return self.audio_bytes
+
+    cache = WakeupWordsConfig()
+    monkeypatch.setattr(helloHandle, "wakeup_words_config", cache)
+    monkeypatch.setattr(helloHandle, "_wakeup_response_lock", asyncio.Lock())
+    return helloHandle, cache, LocalTTS
+
+
+@pytest.mark.parametrize("sample_rate", [16000, 24000])
+@pytest.mark.parametrize("delete_audio_file", [False, True])
+def test_wakeup_cache_accepts_retained_files_and_opus_frames(
+    tmp_path, wakeup_runtime, sample_rate, delete_audio_file
+):
+    helloHandle, wakeup_cache, LocalTTS = wakeup_runtime
+    tts = LocalTTS(tmp_path, delete_audio_file)
+    conn = SimpleNamespace(tts=tts, sample_rate=sample_rate)
+    tts.conn = conn
+
+    asyncio.run(helloHandle.wakeupWordsResponse(conn))
+
+    response = wakeup_cache.get_wakeup_response(tts.voice)
+    assert response is not None
+    assert response["text"] in helloHandle.WAKEUP_CONFIG["responses"]
+    with wave.open(response["file_path"], "rb") as audio:
+        assert audio.getnchannels() == 1
+        assert audio.getsampwidth() == 2
+        assert audio.getframerate() == sample_rate
+        assert audio.getnframes() >= sample_rate
+        assert any(audio.readframes(audio.getnframes()))
+    if not delete_audio_file:
+        assert tts.filename.read_bytes() == tts.audio_bytes
+    assert not helloHandle._wakeup_response_lock.locked()
+
+
+@pytest.mark.parametrize("tts_result", [None, []])
+def test_empty_synthesis_does_not_replace_cached_response(wakeup_runtime, tts_result):
+    helloHandle, wakeup_cache, _ = wakeup_runtime
+    wakeup_cache.generate_file_path = Mock()
+    wakeup_cache.update_wakeup_response = Mock()
+    conn = SimpleNamespace(tts=SimpleNamespace(to_tts=lambda _: tts_result))
+
+    asyncio.run(helloHandle.wakeupWordsResponse(conn))
+
+    wakeup_cache.generate_file_path.assert_not_called()
+    wakeup_cache.update_wakeup_response.assert_not_called()
+    assert not helloHandle._wakeup_response_lock.locked()
+
+
+def test_retained_file_skips_opus_roundtrip(wakeup_runtime, tmp_path, monkeypatch):
+    """保留文件路径必须直转 wav，不得经过 Opus 编解码。"""
+    from core.utils import util
+
+    helloHandle, wakeup_cache, LocalTTS = wakeup_runtime
+
+    def _forbid_opus(*_args, **_kwargs):
+        raise AssertionError("retained file path must not run Opus encoding")
+
+    monkeypatch.setattr(util, "pcm_to_data_stream", _forbid_opus)
+    tts = LocalTTS(tmp_path, False)
+    conn = SimpleNamespace(tts=tts, sample_rate=16000)
+    tts.conn = conn
+
+    asyncio.run(helloHandle.wakeupWordsResponse(conn))
+
+    assert wakeup_cache.get_wakeup_response(tts.voice) is not None
+
+
+def test_missing_retained_file_preserves_cache_and_releases_lock(wakeup_runtime):
+    helloHandle, wakeup_cache, _ = wakeup_runtime
+    wakeup_cache.generate_file_path = Mock()
+    wakeup_cache.update_wakeup_response = Mock()
+    conn = SimpleNamespace(
+        tts=SimpleNamespace(voice="test-voice", to_tts=lambda _: "missing.wav"),
+        sample_rate=16000,
+    )
+
+    with pytest.raises(FileNotFoundError):
+        asyncio.run(helloHandle.wakeupWordsResponse(conn))
+
+    wakeup_cache.generate_file_path.assert_not_called()
+    wakeup_cache.update_wakeup_response.assert_not_called()
+    assert not helloHandle._wakeup_response_lock.locked()
@@ -5,22 +5,13 @@ on disk. We only test:
 - the ValueError path for unknown names (no providers need to exist)
 - that the signature accepts *args / **kwargs (so all three modules work)

-NOTE: This test file is currently skipped at module level because importing
-`core.utils.intent` triggers `setup_logging()` at module load time, which
-requires `data/.config.yaml` to exist. That file is .gitignore'd and not
-present in CI. To enable this test suite, either:
-  1. Make `setup_logging()` lazy (move the call out of module-level scope).
-  2. Provide a stub `data/.config.yaml` in the test environment.
-Tracked as deferred-minor in progress.md.
+早先这个文件整份跳过，理由是导入 `core.utils.intent` 会触发
+`setup_logging()`，而它要 `data/.config.yaml` 在场。CI 里这个文件是现造的，
+本地跑 pytest 时 conftest 也会补上，所以那份跳过理由已经不成立了。
 """
 import pytest

-pytest.skip(
-    "setup_logging() at module import requires data/.config.yaml; skipped",
-    allow_module_level=True,
-)
-
-from core.utils import intent, llm, memory  # noqa: E402  (unreachable when skipped)
+from core.utils import intent, llm, memory


@pytest.mark.parametrize("factory,module_type", [
@@ -46,4 +37,4 @@ def test_create_instance_accepts_args_and_kwargs(factory, module_type):
    is variadic. We use a sentinel that will fail the path check.
    """
    with pytest.raises(ValueError):
-        factory("__missing__", "positional-arg", kwarg="value")
+        factory("__missing__", "positional-arg", kwarg="value")
@@ -1,26 +1,65 @@
-"""Test for the auto-import mechanism in plugins_func/loadplugins.py.
+"""插件自动导入机制的测试。

-We import a real subpackage (`plugins_func.functions`) and verify the
-import side-effect runs. This protects against accidentally deleting
-`auto_import_modules` from `app.py` startup code.
+``core/connection.py`` 启动时会调 ``auto_import_modules("plugins_func.functions")``，
+把 ``plugins_func/functions`` 下的模块逐个导入一遍。导入过程中各插件用
+``@register_function`` 把自己登记进注册表。这段自动导入万一被删掉，
+插件一个都不会被加载，工具链直接空掉，而且不报错，很难发现。这里守住这条链路。

-NOTE: This test is currently skipped because importing
-`plugins_func.functions` triggers heavy module imports (cache_manager,
-etc.) that may not initialise in the test environment. To enable this
-test, ensure `data/.config.yaml` exists in the test environment or refactor
-plugin discovery to be lazy.
+最后一条用例查的是 ``core/connection.py`` 的源码本身：自动导入这个动作做得对
+不对，跟连接模块有没有真的调它，是两回事，两条都要守。
+
+早先这个文件整份跳过，理由是自动导入会拉起一串重量级依赖。CI 里
+``data/.config.yaml`` 是现造的，那个理由已经不成立了。
 """
-import pytest
+import sys
+from pathlib import Path

-pytest.skip(
-    "plugins_func.functions import has side effects that need data/.config.yaml; skipped",
-    allow_module_level=True,
-)
-
-from plugins_func.functions import get_time  # noqa: F401  (unreachable when skipped)
+from plugins_func.loadplugins import auto_import_modules
+from plugins_func.register import all_function_registry


-def test_functions_package_importable():
-    """If this test runs, plugins_func.functions.__init__.py has been imported."""
-    import plugins_func.functions as fns
-    assert hasattr(fns, "get_time")
+def test_auto_import_loads_plugin_modules():
+    """自动导入跑完之后，插件模块应该已经在 sys.modules 里。"""
+    auto_import_modules("plugins_func.functions")
+
+    assert "plugins_func.functions.get_time" in sys.modules
+    assert "plugins_func.functions.get_weather" in sys.modules
+
+
+def test_auto_import_registers_plugin_functions():
+    """自动导入的时候，插件函数应该已经登记进注册表。"""
+    auto_import_modules("plugins_func.functions")
+
+    assert "get_lunar" in all_function_registry
+    assert "get_weather" in all_function_registry
+
+
+def test_connection_module_triggers_auto_import():
+    """core/connection.py 模块加载时那次自动导入得在
+
+    <p>
+    这行被删掉或者改成注释，插件一个都不会被加载：启动不报错，工具链空掉，
+    上面两条用例照样绿。这里查源码，盯住那一次调用。
+    """
+    import ast
+
+    source_path = Path(__file__).resolve().parents[2] / "core" / "connection.py"
+    tree = ast.parse(source_path.read_text(encoding="utf-8"))
+
+    imported_packages = []
+    for node in tree.body:
+        if not isinstance(node, ast.Expr) or not isinstance(node.value, ast.Call):
+            continue
+        call = node.value
+        func = call.func
+        name = func.id if isinstance(func, ast.Name) else getattr(func, "attr", "")
+        if name != "auto_import_modules":
+            continue
+        for arg in call.args:
+            if isinstance(arg, ast.Constant) and isinstance(arg.value, str):
+                imported_packages.append(arg.value)
+
+    assert "plugins_func.functions" in imported_packages, (
+        "core/connection.py 模块加载时的那次自动导入不见了，"
+        "插件不会被加载，工具链会空掉"
+    )
@@ -1,7 +1,8 @@
 """LLM 链路测试。

 Mock 模式（默认）：从 data/.config.yaml 拿配置构造真实 provider，
-网络调用走 conftest 注入的 shim —— 不发任何请求。
+网络那一段换成本文件里的假接口 —— provider 自己拼请求、自己解析
+流式回应那套代码照跑，只是不发真请求，也不需要真 key。
 Live 模式（``RUN_LIVE_API_TESTS=1``）：调真实 LLM provider，参考
 ``performance_tester_llm.py`` 的 ThreadPoolExecutor + 10s 超时模式。

@@ -18,6 +19,7 @@ Live 模式（``RUN_LIVE_API_TESTS=1``）：调真实 LLM provider，参考
 from __future__ import annotations

 import concurrent.futures
+import json
 import sys
 from pathlib import Path

@@ -30,41 +32,144 @@ from tests.conftest import (
    get_provider_type,
    get_selected_provider_name,
    has_real_key,
+    skip_or_fail,
 )

 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))

+# 假接口回的固定内容。够长，能看出是流式拼出来的。
+_MOCK_ANSWER = "这是 mock 出来的回应"
+
+
+@pytest.fixture(autouse=True)
+def _mock_chat_completions(monkeypatch):
+    """Mock 模式下给 chat/completions 装一个假的回应。
+
+    装在 httpx 这一层：provider 拼请求、走流式解析那套代码都是真的，
+    只有网络那一段是假的。这样不用真 key 也能验证这条链路。
+
+    发出去的请求体记在返回的列表里，用例要检查 provider 真的把这次对话
+    装进了请求里。
+    """
+    if LIVE_API_TESTS:
+        yield None
+        return
+
+    import httpx
+
+    stream_body = (
+        "data: "
+        + json.dumps(
+            {
+                "id": "chatcmpl-mock",
+                "object": "chat.completion.chunk",
+                "created": 1700000000,
+                "model": "mock-model",
+                "choices": [
+                    {
+                        "index": 0,
+                        "delta": {"role": "assistant", "content": _MOCK_ANSWER},
+                        "finish_reason": None,
+                    }
+                ],
+            },
+            ensure_ascii=False,
+        )
+        + "\n\n"
+        + "data: [DONE]\n\n"
+    ).encode("utf-8")
+
+    plain_body = json.dumps(
+        {
+            "id": "chatcmpl-mock",
+            "object": "chat.completion",
+            "created": 1700000000,
+            "model": "mock-model",
+            "choices": [
+                {
+                    "index": 0,
+                    "message": {"role": "assistant", "content": _MOCK_ANSWER},
+                    "finish_reason": "stop",
+                }
+            ],
+        },
+        ensure_ascii=False,
+    ).encode("utf-8")
+
+    sent_requests = []
+
+    def _fake_send(self, request, **kwargs):
+        content = getattr(request, "content", b"") or b""
+        sent_requests.append(content)
+        if b'"stream":true' in content.replace(b" ", b""):
+            payload = stream_body
+            headers = {"content-type": "text/event-stream"}
+        else:
+            payload = plain_body
+            headers = {"content-type": "application/json"}
+        response = httpx.Response(200, content=payload, headers=headers)
+        response.request = request
+        return response
+
+    monkeypatch.setattr(httpx.Client, "send", _fake_send)
+    yield sent_requests
+
+
+def _sent_body(requests):
+    """最后一次发出去的请求体。live 模式没有假接口，返回 None"""
+    if requests is None:
+        return None
+    assert requests, "provider 一次请求都没发出去"
+    return json.loads(requests[-1].decode("utf-8"))
+
+
+def _assert_request(body, provider, expected_contents):
+    """检查请求体：模型名在、这次对话在
+
+    <p>
+    只看回应非空的话，provider 把消息丢掉、自己编一句话回来，测试照样绿。
+    """
+    if body is None:
+        return
+    assert body.get("model"), "请求里得带上模型名"
+    expected_model = getattr(provider, "model_name", None)
+    if expected_model:
+        assert body["model"] == expected_model, "请求里的模型名跟配置对不上"
+    messages = body.get("messages") or []
+    assert messages, "请求里得带上对话"
+    contents = [message.get("content") for message in messages]
+    for text in expected_contents:
+        assert text in contents, f"请求里没有把「{text}」发出去"
+

 def _build_provider():
    name = get_selected_provider_name("LLM")
    if not name:
-        pytest.skip("selected_module.LLM 未设置")
+        skip_or_fail("selected_module.LLM 未设置")
    cfg = get_provider_config("LLM", name)
    if not cfg:
-        pytest.skip(f"LLM provider '{name}' 配置缺失")
+        skip_or_fail(f"LLM provider '{name}' 配置缺失")

-    # 任何模式下：key 是占位符 → skip。真请求需要真 key；mock 模式下
-    # 没有真 key 跑下去也会撞真 SDK 的网络栈（openai/edge_tts）报错。
+    # 任何模式下：key 是占位符 → 真请求没法发。mock 模式有假接口顶上，
+    # 但占位符本身是中文，httpx 拼 Authorization 头的时候会直接报编码错，
+    # 所以 mock 模式把它换成一把假的 ascii key
    if name == "CozeLLM":
        if any(x in cfg.get("bot_id", "") for x in ["你的"]) or any(
            x in cfg.get("user_id", "") for x in ["你的"]
        ):
-            pytest.skip("LLM 'CozeLLM' 的 bot_id/user_id 未配置")
+            skip_or_fail("LLM 'CozeLLM' 的 bot_id/user_id 未配置")
    elif name == "Ollama":
        if not cfg.get("model_name"):
-            pytest.skip("LLM 'Ollama' 的 model_name 未配置")
+            skip_or_fail("LLM 'Ollama' 的 model_name 未配置")
    elif not has_real_key(cfg, "api_key"):
        if LIVE_API_TESTS:
-            pytest.skip(f"LLM '{name}' 的 api_key 未配置")
-        else:
-            pytest.skip(
-                f"LLM '{name}' 的 api_key 是占位符（mock 模式不会真发请求）。"
-                "真请求模式：export RUN_LIVE_API_TESTS=1 并填真 key 后再跑。"
-            )
+            skip_or_fail(f"LLM '{name}' 的 api_key 未配置")
+        cfg = dict(cfg)
+        cfg["api_key"] = "mock-api-key"

    ptype = get_provider_type("LLM", name)
    if not ptype:
-        pytest.skip(f"LLM '{name}' 的 type 字段缺失")
+        skip_or_fail(f"LLM '{name}' 的 type 字段缺失")
    from core.utils.llm import create_instance

    return create_instance(ptype, cfg)
@@ -77,7 +182,7 @@ def _collect_with_timeout(provider, session_id: str, dialogue, timeout: float =
        return future.result(timeout=timeout)


-def test_llm_response_streams_non_empty() -> None:
+def test_llm_response_streams_non_empty(_mock_chat_completions) -> None:
    """response(session_id, dialogue) 应产生非空 token 流。"""
    provider = _build_provider()
    dialogue = [
@@ -89,21 +194,33 @@ def test_llm_response_streams_non_empty() -> None:
    full = "".join(chunks).strip()
    assert isinstance(full, str), f"LLM chunks join 应是 str，得到 {type(full).__name__}"
    assert full, f"LLM 返回空响应（provider={type(provider).__name__}）"
+    # 回的得是假接口给的那句，不是随便一个非空串
+    assert full == _MOCK_ANSWER
+    _assert_request(
+        _sent_body(_mock_chat_completions),
+        provider,
+        ["你是助手", "用一句话说 hi"],
+    )


-def test_llm_response_no_stream_returns_string() -> None:
+def test_llm_response_no_stream_returns_string(_mock_chat_completions) -> None:
    """response_no_stream 应返回非空字符串。"""
    provider = _build_provider()
    text = provider.response_no_stream("你是助手", "介绍一下北京").strip()

    assert isinstance(text, str), f"response_no_stream 应返回 str，得到 {type(text).__name__}"
    assert text, "response_no_stream 返回空字符串"
+    assert text == _MOCK_ANSWER
+    _assert_request(
+        _sent_body(_mock_chat_completions), provider, ["你是助手", "介绍一下北京"]
+    )


-def test_llm_dialogue_min_length_one_user() -> None:
+def test_llm_dialogue_min_length_one_user(_mock_chat_completions) -> None:
    """至少一条 user 消息的 dialogue 应能跑通。"""
    provider = _build_provider()
    dialogue = [{"role": "user", "content": "ping"}]
    chunks = _collect_with_timeout(provider, "s1", dialogue, timeout=10.0)

    assert "".join(chunks).strip(), "单 user 消息应返回内容"
+    _assert_request(_sent_body(_mock_chat_completions), provider, ["ping"])
@@ -8,7 +8,7 @@ Live 模式（``RUN_LIVE_API_TESTS=1``）：调真实 TTS provider。
    text_to_speak(text, output_file) -> 异步，把合成结果写到 output_file

 注意：
- 3 个构造测试不依赖云服务；第 4 个 test_tts_text_to_speak_writes_nonempty_file
+- 3 个构造测试不依赖云服务；第 4 个 test_tts_text_to_speak_writes_file
  才是真链路测试，会真发 HTTP。
 - Mock 模式下：第 4 个测试断言宽松 —— 文件存在即可（shim 创建空文件），
  不强求 size > 0。Live 模式下严格校验 size > 0。
@@ -81,9 +81,13 @@ def test_tts_provider_has_output_dir() -> None:
    assert provider.output_file, "output_file 不应为空"


+@pytest.mark.live_api
 def test_tts_text_to_speak_writes_file() -> None:
    """Mock 模式：断言 file 存在即可。Live 模式：断言 size > 0。

+    这条要连微软公网，runner 的出口 IP 会被风控挡掉，所以打了 live_api 标记：
+    mock 模式下由 conftest 统一剔除（会列出剔的是哪几条），live 模式下才收。
+
    参考 performance_tester_tts.py 的实现：
    - mock conn（sample_rate/audio_format/stop_event/client_abort/headers）
      和 opus_encoder（SimpleNamespace 占位即可）
Author	SHA1	Message	Date
hrz	1a4b8d76c5	TTS 用例说明里的名字改成真存在的说明里写的那个用例名仓库里没有，改成实际跑的那条。	2026-10-24 08:06:12 +00:00
hrz	57dffb23e9	三条 LLM 用例改成查请求体原来只看回应非空，provider 把消息丢掉、自己编一句回来，测试照样绿。现在检查请求里带了模型名和这次对话，回的内容也要跟假接口给的一致。	2026-10-24 08:06:12 +00:00
hrz	379185caed	盯住连接模块里那次插件自动导入原来两条用例自己调自动导入，连接模块里那行被删掉它们照样绿。加一条查源码的用例，盯住模块加载时那次调用本身还在。	2026-10-24 08:06:12 +00:00
hrz	03b7452daf	CI 里缺东西直接失败，不许静默跳过测试里原来有几处配置缺失就跳过的分支，CI 上会静悄悄跳掉，门禁看着是绿的其实没跑。加了个统一的守卫：本地缺东西照旧跳过，CI 里直接失败，口径跟 manager-api 的集成测试守卫一样。	2026-10-24 07:31:19 +00:00
hrz	aff47ee6de	要真凭据的用例打标记统一剔除 Edge TTS 那条要连微软公网，runner 的出口 IP 会被风控挡掉。以前在 CI 命令行上用 -k 排除，看不出排掉了什么。现在给它打 live_api 标记，由 conftest 统一剔除，日志里列出剔的是哪几条。	2026-10-24 07:27:15 +00:00
hrz	e3e043a9ed	几组用例不再整份跳过，真跑起来插件自动导入、三个 create_instance、LLM 链路这几组用例以前整份跳过，现在都真跑。LLM 那边装了个假接口，provider 拼请求和解析流式回应那套照跑，不发真请求也不用真 key。data/.config.yaml 缺的时候现造一个，免得用例收集不起来。	2026-10-24 07:27:06 +00:00
hrz	b3810fb7cb	本地没起库也能构建，CI 里集成测试不许跳过三个要连 MySQL 和 Redis 的集成测试加了守卫：依赖连不上就整类跳过，日志写明缺什么，构建照样是绿的；CI 上依赖不通就直接失败。另外加了一个门禁检查脚本和 CI 步骤，盯住这三个类有没有真跑，守卫哪天手滑把它们全跳过了，CI 必须变红。README 里补了本地怎么起依赖、怎么只编译不跑测试。	2026-10-24 06:30:22 +00:00
hrz	4eb586b597	给 runner 补上 libopus，修掉音频用例报错 opuslib_next 是 ctypes 绑定，真正编解码靠系统里的 libopus。runner 上默认没有，import 失败后测试里换上的是自己写的桩，桩里的编码器只有构造方法，一调就报错。正式镜像里是装了这个库的，CI 少了这一步。顺手把桩的报错改成一句人话，别再让人对着缺方法的报错猜根因。	2026-10-24 00:59:59 +00:00
hrz	49c908db56	让 CI 真正跑起三类测试并修掉挡路的测试缺陷之前 CI 只跑了一小部分，Java 那边的测试被 pom 里的开关整个跳过了。这条把它打开，并补上 MySQL、Redis 两个容器，Java、契约、Python 三类测试都在 CI 里真跑起来。另外修了两个挡路的地方：一条 Java 用例单跑会因为实体信息没注册而报错，现在自己注册；Python 的假网络层把整个 httpx 类换掉了，第三方库拼请求时报错，改成只换发请求那一步。	2026-10-24 00:46:53 +00:00
hrz	9bd668aebc	Merge pull request #3449 from TXyy2023/codex/issue-3050-preserve-model-type fix(manager-api): 保存模型时保留供应器登记的类型大小写	2026-10-23 22:17:36 +08:00
hrz	d027432432	Merge pull request #3458 from monsterlag/fix/issue-3064-b736 fix(manager-web): 修复短屏下模型配置知识库入口被裁剪	2026-10-23 21:53:42 +08:00
hrz	3972df6e4e	加固模型配置导航的契约测试原来的用例只取第一条样式规则，后面谁再补一条同名规则就能把滚动改回去，测试照样是绿的。这次把导航用到的样式选择器逐条列出来核对，外层容器也要求只能有一条规则，这样有人悄悄覆盖时测试会当场报错。	2026-10-23 13:39:19 +00:00
hrz	8f2dda09cf	Bump to 0.9.8 (#3469 )	2026-10-23 18:54:05 +08:00
hrz	d4ff9c5c17	修掉通讯录的两处越权（读 + 写），并补上三处空指针 (#3460 ) * 读取设备通讯录先验设备归属登录用户传任意 MAC 就能读到别人设备通讯录里的备注和称呼。归属判断收进一个方法，读取通讯录、改别名、改权限都走它，不属于当前用户的设备一律按查不到处理。 * 通讯录存别名不再空指针对方设备没登记时取备注会直接崩，整条权限授予请求跟着挂掉。取不到就退回尾号称呼，呼叫时主叫没登记也不再崩，顺手删掉一行调试打印。 * 解绑先验归属，通讯录别名不再落空解绑接口原来不核对设备归属，谁知道对方的设备 id 就能把那台设备的通讯录清空，设备本身倒是因为带了用户条件没删掉。现在先看归属，不是自己的直接不动。设备登记了但用户没起名时，别名会落成空，缓存刷新把整条跳过，对方再也呼不过来。改成和呼叫那处一样，两级判空都取不到才退回尾号称呼。顺带加了一条回填，把写进去的空值补上。呼叫那条测试原来会真发请求也没验到东西，改成桩掉网关直接看发出去的称呼。 * 通讯录空别名兜底，撞名加后缀缓存拼表之前，空别名先用尾号称呼顶上，不再整条跳过，用户没起名的设备也能被呼到。昵称在同一个人的通讯录里是索引，两台撞名时后写的会盖掉先写的，按昵称呼会呼错设备。加后缀区分，规则和存表时那套一致。取名靠先后，而查询不带排序，所以先按地址排一遍，同样的数据每次刷新结果一样。数据库没有排序保证，去重全靠顺序，所以这里先排再拼。迁移脚本不用动，运行时的兜底能管住它没覆盖到的行。 * 通讯录取名两条路径对上了后缀原来只写进缓存，接口直查库返回原值，同一份数据给的是两个名字。用户照控制台看到的名字呼叫，命中的不是同一台设备。把取名抽成一个方法，两边都走一遍。顺带把权限位排到地址前面，撞名时能呼的那台先拿原名，反过来用户怎么点都只会说没权限。迁移取末两位时改成跟着小写化，和运行期算出的是同一个称呼。 * 同一个人被拆成两本通讯录，一台设备消失两条记录的归属地址只差大小写时，会被算成两个人，各拿一个同名，写进同一本时后者盖掉前者，一台设备就从缓存里消失了。把归属地址归一抽成一个方法，算称呼、写缓存、查缓存都走它。 * 通讯录接口按最近改过的排前，这个约定有用例钉住智控台页面是按对方地址把备注合进去的，接口返回顺序它并不关心，所以现在这么排对界面没有效果。用例留着是防它被当无用代码删掉，删了会有用例报出来。 * 迁移串到别人的私名，撞车的组改走尾号称呼通讯录回填名字时，设备表里同一个 MAC 有两行（同一台被两个用户各登记一次）， MySQL 自己挑一行填进去，跟这行属于谁无关。改成只有一台时才取智控台名字，多台就退回按 MAC 末两位算的称呼。名字照样填上，缓存照样刷新，对方还是呼得到。补了 12 条在真库上跑的用例，另配一条排查重复 MAC 的语句。 * 去掉走不到的分支和没人用的桩，补上末尾换行 getUser() 取不到 subject 或 principal 时返回的是空对象，不是 null， user == null 走不到，删掉；用例改成桩空对象，测真正的匿名那条路。归属判断挪进 service 之后，controller 层四处 SecurityUser 的桩没人用了，删掉。四个文件末尾少了换行，补上。另加一条用例钉住判重分组的比较规则：只折叠大小写，不折叠分隔符。 * 移除回填通讯录别名的迁移，运行时已经兜住了这个迁移是本 PR 带进来的。它要把空别名刷成称呼，可运行时的兜底已经做了一样的事，而且覆盖得更宽：那边连纯空格、地址为空和不足两位的都管。删掉它，功能不受影响。删它有两条理由。一是重复。二是它按 MAC 去设备表取名字，而一个 MAC 在设备表里可能有多行——同一台设备被两个用户各登记一次就能造出来，这时候取到的是别人给自己设备起的名字。写在这里，是怕后来的人以为这个坑不存在。 * 归属校验撞到重复 MAC 不再报错库里同一 MAC 可能有两行只差大小写，selectOne 会抛 TooManyResultsException，把读通讯录接口整个带崩。改成 selectList 按 id 取第一条做归属校验，撞行时正常返回，不再报错。	2026-10-23 17:43:05 +08:00
wengzh	3709540efd	Merge pull request #3445 from xinnan-tech/fix/huoshan-double-stream-4-bugs-y15 huoshan_double_stream 修 4 个会话协议与监听竞态 bug	2026-10-23 17:37:05 +08:00
wengzh	333050ae2e	Merge pull request #3464 from xinnan-tech/chore/bump-deps-20261023 chore(deps): 批量升级 15 个依赖，适配 mcp 2.x	2026-10-23 17:05:05 +08:00
Sakura-RanChen	95ce49ffc9	删除 benchmark/ 下 3438~3441 回归验证脚本四处修复均已验证收敛，脚本不进 CI、裸跑依赖 manager-api，保留仅为仓库噪声；后续若再动 huoshan_double_stream 时以 pytest 覆盖	2026-10-23 17:04:52 +08:00
Sakura-RanChen	be75e7bd39	chore(deps): 批量升级 15 个依赖，适配 mcp 2.x 源 PR: #3426 #3427 #3428 #3429 剔除 4 项: - edge-tts 7.3.1->7.2.8 是降级 - powermem >=1.1.7 要求 Python>=3.11 - openai 3.29.0 与 powermem 冲突（powermem 要求 openai<3.0.0） - ruamel.yaml 0.19.1 与 hyperpyyaml 冲突 mcp 2.x 适配: streamablehttp_client 更名为 streamable_http_client，headers/timeout 改由 http_client 承载，产出从 3 元组变 2 元组，ProgressFnT 移到 mcp.shared.dispatcher	2026-10-23 15:15:50 +08:00
hrz	24fbf7eee2	登录 token 12h 静默失效补 silent refresh 接口 #3392 (#3402 ) * 登录 token 12h 静默失效补 silent refresh 接口 #3392 方案 A：后端 POST /xiaozhi/user/refresh（anon），旧 token 校验通过后强制覆盖为新 token 字符串，旧 token 在 DB 查不到即失效。前端 httpRequest 在 sendRequest 入口检查 token 剩余有效期，剩 1h 内触发 silent refresh（独立 fly 实例 + 单飞锁），成功后 setToken 替换并自动继续发送当前请求，失败走 clearAuth 跳登录。 * refreshToken 改 CAS 防并发 race + 拆前端副作用 #3392 P1：SysUserTokenDao 新增 refreshTokenCAS，条件 UPDATE（oldToken + 未过期 + userId），受影响 0 行抛 TOKEN_INVALID；refreshToken 改调它，避免读-改-写 race。P2：refreshToken 加 @Transactional；httpRequest.getTokenExpireAt 内的 localStorage.setItem 挪到独立 persistTokenExpireAt，由 shouldRefresh 入口调用。 * getTokenExpireAt 改读 localStorage 与持久化同源 #3392 pr01 三改：原代码 getTokenExpireAt 读 store（state.token 缓存），与 persistTokenExpireAt 写 localStorage 不同源，导致 _localStoredAt 缺失 → NaN → shouldRefresh 永 false → silent refresh 永不触发。修复：getTokenExpireAt 改读 localStorage，persistTokenExpireAt 同步刷 store，保证两端一致。e2e 已验证：注入 expire=1800 token → reload → role-config mount 触发 sendRequest → Network 抓到 POST /user/refresh 200 → localStorage token 被替换为新 12h token（含 _localStoredAt）。 * 应用启动同步 localStorage token 到 store #3392 PR #3402 扩展：守卫放行后首次 API 请求时，vuex state.token 还是 null，httpRequest 读 store 取不到 Authorization 头，会被后端 401 → clearAuth 跳登录。在 main.js 应用启动阶段就把 localStorage 里的 token commit 进 store，避免 race。不动 refresh 链路与其它业务文件。	2026-10-23 09:47:41 +08:00
monsterlag	855a64cbb9	fix(manager-web): keep model navigation scrollable on short screens	2026-10-22 04:06:52 +00:00
hrzandSakura-RanChen	fdf280f84a	模板 GET 入口迁回 AgentTemplateController #3395 (#3401 ) * 模板 GET 入口迁回 AgentTemplateController #3395 根因：AgentController 已存在 GET /agent/template/templateList，AgentTemplateController 缺显式 GET，于是路由虽通却跨 controller 暴露模板数据，且职责错位。修复：删 AgentController.templateList，同名 @GetMapping（无 path）落到 AgentTemplateController，权限 normal、orderByAsc sort、复用现有 service.list。验证：spring-boot 启动期无 Ambiguous；/agent/template、/page、/{id} 三路由均被 Shiro 一致拦截，权限/路径正确。 * 补 P2 注释说明 normal 权限反直觉是有意保留 #3395 在 getAgentTemplates 上方加 2 行注释，说明单独 normal 权限是为保持原行为契约（普通用户也能查可用模板），与类级 superAdmin 故意分离；非疏忽。无逻辑变更。 * 去除未使用引用 --------- Co-authored-by: Sakura-RanChen <1908198662@qq.com>	2026-10-22 11:42:48 +08:00
wengzh	498191519c	Merge pull request #3452 from xinnan-tech/py-test-wakeup Py test wakeup	2026-10-22 11:08:38 +08:00
wengzh	f614489d81	Merge pull request #3454 from xinnan-tech/web-test-json Web test json	2026-10-20 15:44:16 +08:00
Sakura-RanChen	6f958ee4a6	fix: 新增模型页面dict字段错误解析	2026-10-20 15:34:40 +08:00
TXyy2023	b226ee5430	fix(manager-web): decode stored dictionaries before editing (#3450 )	2026-10-20 11:53:02 +08:00
Sakura-RanChen	9c30b5e035	文件直接写入wav，无需经过二次编解码	2026-10-20 10:45:31 +08:00
TXyy2023	d531d04281	fix(tts): handle retained audio files in wakeup cache (#3451 )	2026-10-20 10:00:20 +08:00
Sakura-RanChen	d8f8a4a083	- 取消屏障保证：新连接创建前 _cancel_monitor_task 已等旧监听任务完全退出，旧任务不可能读新连接或误关新连接（check_huoshan_3440 动态断言覆盖） - mismatch 分支仅保留纯跳过，删除旧会话结束事件的复位遗留， activate_session 写入点收敛到会话生命周期（start / matched 结束 / close） - 删除 _session_start_future 启动确认机制：start_session 发送即返回， SessionFailed 由 monitor 记 error 并复位 activate_session，无挂起风险 - 回归脚本同步调整：3438 重写为新行为断言，3440 用屏障断言替换 snapshot 断言	2026-10-19 17:52:25 +08:00
TXyy2023	37d4330224	test(model): verify registered types with MySQL and Redis	2026-10-18 23:13:39 +08:00
TXyy2023	7873984f9f	fix(manager-api): preserve registered model type casing	2026-10-18 17:10:47 +08:00
hrz	6840210ea8	check_huoshan_3439 改 FIRST 分支行为断言原 test 用正则 grep 源码验存在性，pr02 复评指出这样测不到实际调用。改成起后台线程跑真 tts_text_priority_thread、构造 FIRST 消息入队、 run_coroutine_threadsafe patch 成立即完成的 future，最后断言 reset_stream_state 与 opus_encoder.reset_state 各被调一次。	2026-10-17 07:57:30 +08:00
hrz	0a54124d0d	huoshan_double_stream 修 3 处复评反馈 init 漏写 _pending_prefix 字段、start_session 用已弃用的 get_event_loop、finish_session 留着多余的 getattr 兜底。补字段、换 get_running_loop、去兜底，3 处都修了。	2026-10-17 07:57:26 +08:00
hrz	ddc441bc59	补 huoshan_double_stream 4 bug 复现脚本四个独立脚本各覆盖一个 issue：start_session 等 future 确认、句尾残留与编码器冲刷、monitor snapshot 隔离、parser_response 四处协议解析。共享 _huoshan_mock 构造一个绕开父类 init 的假 provider 实例。	2026-10-17 07:39:51 +08:00
hrz	9b7fb3e826	parser_response 四处二进制协议解析修正 serialization_method 错用掩码当移位数恒 0，改成 >>4；message_type 写 == FULL or AUDIO_ONLY_RESPONSE 优先级下恒真，改 in (...)；offset 硬编码 4 在 header_size>1 全错位，改成 header_size * 4；SessionCanceled 漏进协议分支被 else 误读，补进统一解析。	2026-10-17 07:39:51 +08:00
hrz	a6cdbf9410	监听任务用 snapshot 隔离跨连接旧 monitor 循环直接 self.ws.recv()，连接重建后旧任务读新下行；finally 无条件关 self.ws 误关新连接。改成入口绑 monitor_ws / monitor_task，recv 用 snapshot；旧 session 事件 continue 不再 reset 当前；finally 判 id 相同才关 ws / 清引用。	2026-10-17 07:39:51 +08:00
hrz	75fd5d8cc3	句尾替换词残留先发 + 会话结束冲刷编码器旧 finish_session 不发 _pending_prefix 残留，句尾替换词被扣时整段丢；monitor / to_tts 收 SessionFinished 不调 is_end=True 冲刷 opus 编码器，每句固定丢尾。改成 finish_session 开头先发残留，monitor / to_tts 调 is_end=True 冲刷，FIRST 同步重置。	2026-10-17 07:39:51 +08:00
hrz	6fe5630346	TTS 会话等 SessionStarted 确认旧逻辑 start_session 发完 StartSession 即返回；服务端鉴权失败或 14s 内 26005 时文本线程继续给死会话发文本，整轮无声。改成末尾 await 一个 future：monitor 读到 SessionStarted set True、读到 SessionFailed set False，超时报错让文本线程感知。	2026-10-17 07:39:50 +08:00