# AI客服智能体增强改造方案（渠道侧 / Java）

## 1. 改造定位

Java 渠道侧承担“用户体验与会话控制中枢”角色，核心职责：
- 分段消息发送（拟人化节奏）
- 打断处理（实时中断、无重复发送）
- 本地会话历史缓存（已送达真相）
- 全量消息异步上报（含人工阶段）

目标：让智能体能力在前端体验上可感知且可控。

---

## 2. 渠道侧总体设计

## 2.1 新增组件
1. `SegmentDispatcher`（消息调度器）
2. `InterruptManager`（打断管理器）
3. `DeliveredHistoryStore`（已送达历史存储）
4. `MessageReporter`（全量消息上报器）
5. `SessionModeManager`（机器人/人工状态管理）

## 2.2 会话状态机
- `BOT_ACTIVE`：机器人对话中
- `BOT_SENDING`：机器人分段发送中
- `INTERRUPTED`：发送被打断，等待新请求
- `HUMAN_ACTIVE`：人工接管

---

## 3. 核心流程设计

## 3.1 正常流程（无打断）
1. 用户消息进入渠道侧
2. 组装请求（`session_id + user_message + delivered_history`）调用中台
3. 收到 `segments[]`
4. `SegmentDispatcher` 按 `delay_after` 顺序发送
5. 每发送成功一段，写入 `DeliveredHistoryStore`
6. 异步上报每条消息（用户/机器人）

## 3.2 打断流程
1. 发送中收到新用户消息
2. `InterruptManager` 立即取消未发送段
3. 仅保留“已送达段”作为历史
4. 发起新请求，附带 `interrupted_segments`（可选）
5. 中台重新决策后返回新 `segments[]`

## 3.3 转人工流程
1. 渠道侧调用中台状态接口标记 `HUMAN_ACTIVE`
2. 后续消息不再调用智能体
3. 用户与人工消息继续异步上报中台（保证闭环数据）

---

## 4. 关键模块说明

## 4.1 SegmentDispatcher

职责：
- 顺序发送片段
- 尊重 `delay_after`
- 支持取消令牌（中断）

建议实现点：
- 每个 session 单独队列
- 每段发送前检查会话是否仍为 `BOT_SENDING`
- 失败重试最多 1 次（避免重复刷屏）

## 4.2 InterruptManager

职责：
- 监听用户新消息事件
- 取消当前发送任务
- 记录中断点（最后已送达 segment_id）

建议规则：
- 中断优先级高于发送
- 丢弃未送达段，不做补发

## 4.3 DeliveredHistoryStore（Redis）

建议键：`chat:{sessionId}:delivered`

建议字段：
- role（user/assistant/human）
- content
- timestamp
- segment_id（assistant可选）
- source（bot/human）

只存“已送达”消息，避免上下文污染。

## 4.4 MessageReporter

职责：
- 异步上报全量消息到中台历史服务
- 支持重试与死信队列

必须上报：
- 用户消息
- 机器人每个已送达段
- 人工客服消息
- 模式切换事件（bot->human/human->bot）

---

## 5. 请求与响应协议建议

## 5.1 渠道 -> 中台请求
```json
{
  "session_id": "sess_123",
  "user_message": "孩子五年级，数学不好",
  "history": [
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "您好"}
  ],
  "interrupted_segments": [
    {"segment_id": "seg_2", "content": "稍等，我查一下"}
  ]
}
```

## 5.2 中台 -> 渠道响应
```json
{
  "segments": [
    {"segment_id": "seg_3", "text": "好的，请问孩子具体是哪个知识点薄弱？", "delay_after": 800},
    {"segment_id": "seg_4", "text": "比如分数应用题还是几何？", "delay_after": 0}
  ]
}
```

---

## 6. 与中台协同的关键约束

1. 渠道侧只认 `segments[]`，不关心中台内部是 agent 还是 flow。
2. 必须使用“已送达历史”回传，不能用“计划发送历史”。
3. 打断后立即重发，不等待旧请求自然结束。
4. 人工模式下继续上报，保证中台记忆与分析完整。

---

## 7. 可观测性指标（渠道侧）

建议上报指标：
- `segment_send_latency_ms`
- `segment_drop_count`（中断丢弃）
- `interrupt_count`
- `resend_request_count`
- `bot_to_human_switch_count`
- `history_report_success_rate`

日志关键字段：
- session_id
- request_id
- segment_id
- mode
- interrupted_at

---

## 8. 分阶段实施建议（渠道侧）

## Phase 1
- 实现分段发送 + 本地已送达历史
- 接入中台 `segments` 协议

## Phase 2
- 打断管理上线（实时取消 + 重新请求）
- 全量消息上报链路上线

## Phase 3
- 人工接管状态机完善
- 失败重试、幂等、死信治理完善

---

## 9. 风险与应对

1. 重复发送风险
- 通过 `segment_id + session_id` 做幂等去重

2. 中断竞态（旧包晚到）
- 用 `request_id` / `generation_id` 校验，只消费最新响应

3. 历史错乱
- 仅以“已送达消息”入历史，不以“待发送消息”入历史

4. 上报积压
- 异步队列 + 批量上报 + 失败重试

---

## 10. 最终建议（渠道侧）

- 渠道侧的首要目标不是“更聪明”，而是“更稳定 + 更像人 + 可打断”。
- 只要分段、打断、历史上报三件事做稳，中台 Agent 的价值会显著放大。