refactor(server): optimize KB retrieval and voice context

test2/后端改造清单.md

@@ -0,0 +1,216 @@
+# 后端改造清单
+
+> 目标：在**不修改 Redis 全局配置**、不影响其他服务的前提下，优先优化当前语音 + 知识库后端链路的延迟、稳定性和可维护性。
+
+## 一、改造原则
+
+- **不动全局配置**：不修改 Redis `maxmemory` / `maxmemory-policy` 等服务端级配置。
+- **先收敛链路，再做扩展**：优先减少重复上下文读取、重复检索、重复缓存逻辑。
+- **优先 P0**：先解决影响延迟和准确率的核心路径。
+- **可回退**：每一项改造都保留降级路径，避免影响线上。
+
+## 二、当前重点文件
+
+- `server/routes/chat.js`
+- `server/services/realtimeDialogRouting.js`
+- `server/services/toolExecutor.js`
+- `server/services/kbRetriever.js`
+- `server/services/redisClient.js`
+- `server/services/nativeVoiceGateway.js`
+- `server/services/contextKeywordTracker.js`
+- `server/services/fastAsrCorrector.js`
+- `server/services/contentSafeGuard.js`
+
+## 三、P0：必须先改
+
+### 1. 统一上下文装配入口
+
+- [ ] 抽出统一的上下文装配服务
+- [ ] 统一 Redis → MySQL 的读取顺序
+- [ ] 同一轮对话避免多次读历史消息
+- [ ] 统一文字链路与语音链路的上下文拼装规则
+
+**目标文件**
+
+- `server/routes/chat.js`
+- `server/services/realtimeDialogRouting.js`
+- `server/services/kbRetriever.js`
+
+**验收标准**
+
+- 同一 session 在一次请求链路里只装配一次上下文
+- 文字和语音的上下文结果一致
+
+---
+
+### 2. KB 检索从“全库扫描”改为“候选集检索”
+
+- [ ] 先根据关键词/意图分类出候选 collection
+- [ ] 再做 VikingDB 检索
+- [ ] 最后重排 topN 片段
+- [ ] 保留全库扫描兜底开关
+
+**目标文件**
+
+- `server/services/toolExecutor.js`
+- `server/services/kbRetriever.js`
+- `server/services/realtimeDialogRouting.js`
+
+**验收标准**
+
+- 检索 collection 数量可控
+- 平均延迟下降
+- 检索结果不明显变差
+
+---
+
+### 3. Redis 写入改为 pipeline / multi
+
+- [ ] `LPUSH + LTRIM + EXPIRE` 合并为一次往返
+- [ ] 保留写失败降级逻辑
+- [ ] 保留 TTL 机制
+
+**目标文件**
+
+- `server/services/redisClient.js`
+
+**验收标准**
+
+- 单次消息写入 Redis 往返次数减少
+- 现有 TTL 行为不变
+
+---
+
+### 4. 缓存层次明确化
+
+- [ ] 明确本地内存缓存只做短时减压
+- [ ] Redis 作为共享缓存
+- [ ] no-hit 结果只做短 TTL 去重，不长期存储
+- [ ] 缓存 key 规范化
+
+**目标文件**
+
+- `server/services/toolExecutor.js`
+- `server/services/redisClient.js`
+
+**验收标准**
+
+- 多实例时缓存行为可解释
+- key 命名与 TTL 规则统一
+
+---
+
+## 四、P1：建议尽快改
+
+### 5. 会话生命周期治理
+
+- [ ] 给 `chatSessions` 增加更明确的上限
+- [ ] 定时清理策略配置化
+- [ ] 超过阈值时自动淘汰最旧 session
+- [ ] 评估 session 状态是否需要下沉 Redis
+
+**目标文件**
+
+- `server/routes/chat.js`
+- `server/services/nativeVoiceGateway.js`
+
+**验收标准**
+
+- 长时间运行不明显涨内存
+- session 清理策略可观测
+
+---
+
+### 6. 预查询参数配置化
+
+- [ ] 把 early block / debounce / 最小长度提成配置项
+- [ ] 支持不同场景调参
+- [ ] 记录 prequery 命中率
+
+**目标文件**
+
+- `server/services/nativeVoiceGateway.js`
+
+**验收标准**
+
+- 不改代码可调整阈值
+- 误触发率下降
+
+---
+
+### 7. 结构化指标埋点
+
+- [ ] 路由命中率
+- [ ] Redis 命中率
+- [ ] DB fallback 次数
+- [ ] KB 检索耗时
+- [ ] 重排耗时
+- [ ] prequery 命中率
+
+**目标文件**
+
+- `server/services/realtimeDialogRouting.js`
+- `server/services/toolExecutor.js`
+- `server/services/kbRetriever.js`
+
+**验收标准**
+
+- 能按 session / route / tool 维度排查性能问题
+
+---
+
+## 五、P2：后续增强
+
+### 8. 安全与兜底一致性
+
+- [ ] 统一知识库 no-hit 的诚实兜底文案
+- [ ] 统一品牌保护文案
+- [ ] 避免不同入口返回不一致
+
+**目标文件**
+
+- `server/services/realtimeDialogRouting.js`
+- `server/services/contentSafeGuard.js`
+- `server/routes/chat.js`
+
+---
+
+### 9. 测试补强
+
+- [ ] Redis 读写单测
+- [ ] KB 检索与重排单测
+- [ ] 语音/文字链路回归测试
+- [ ] no-hit / 保护窗口 / 追问场景测试
+
+**目标文件**
+
+- `server/tests/test_redis_client.js`
+- `server/tests/test_kb_retriever.js`
+- `server/tests/test_kb_scenarios.js`
+- `server/tests/test_kb_prompt_compare.js`
+
+---
+
+## 六、建议实施顺序
+
+1. 上下文装配统一
+2. KB 候选集检索
+3. Redis pipeline
+4. 会话生命周期治理
+5. 预查询参数配置化
+6. 指标埋点
+7. 测试补强
+
+## 七、建议验收口径
+
+- **延迟**：核心查询链路 P50 明显下降
+- **稳定性**：Redis 断开时可自动降级
+- **一致性**：文字/语音链路输出策略一致
+- **安全性**：no-hit 与品牌保护回复统一
+- **可维护性**：关键阈值可配置，不依赖频繁改代码
+
+## 八、备注
+
+- 本清单只针对**应用层改造**。
+- 不包含 Redis 全局配置修改。
+- 若后续要做服务器级改动，需单独确认。