# 后端改造清单

> 目标：在**不修改 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 全局配置修改。
- 若后续要做服务器级改动，需单独确认。