# Conversations（对话管理）

**模块：** `gateway/core/conversations/`

## 文档维护规范

0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现
1. **文档分层，链接代码** - 关键实现需标注代码文件路径；格式：`module/file.py:function_name`
2. **简洁快照，日志分离** - 只记录已确认的设计

---

## 模块职责

对话管理，包括：

- **对话管理**：管理用户和 Agent 的对话
- **消息历史存储**：存储和查询消息历史
- **消息队列和调度**：管理消息队列，调度 Agent 执行

---

## 核心概念

### Conversation（对话）

- **定义**：一个用户和一个 Agent 的永久对话
- **特点**：
  - 每个对话有独立的消息历史
  - 对话是永久的
  - 对话 ID 格式：`conversation:{trace_id}:{user_id}`

### 消息历史

- 每个对话的消息按时间顺序存储
- 包含用户消息和 Agent 回复
- 支持查询历史消息

### 消息队列

- 管理待处理的消息
- 支持消息调度
- 防止并发冲突

---

## 模块结构

```
gateway/core/conversations/
├── conversation_manager.py  # 对话管理
├── message_store.py         # 消息历史存储
└── message_queue.py         # 消息队列和调度
```

---

## 关键功能

### 对话管理

**实现位置：** `gateway/core/conversations/conversation_manager.py`

**职责：**
- 创建对话
- 查询对话信息
- 列出所有对话

### 消息历史存储

**实现位置：** `gateway/core/conversations/message_store.py`

**职责：**
- 存储消息
- 查询消息历史
- 消息持久化

### 消息队列和调度

**实现位置：** `gateway/core/conversations/message_queue.py`

**职责：**
- 消息入队
- 消息调度
- 调用 Agent 执行

---

## 两种 Agent 类型的对话管理

### 个人助理型 Agent

- 每个用户有独立的 Trace
- 每个用户有独立的对话
- 对话 ID：`conversation:trace-alice-001:user_alice`

### 数字员工型 Agent

- 所有用户共享一个 Trace
- 每个用户有独立的对话
- 对话 ID：`conversation:trace-receptionist:user_alice`
- Agent 可以查看所有对话的消息历史

---

## 相关文档

- [需求规划](../requirements.md)：对话管理需求
- [架构设计](../architecture.md)：模块在整体架构中的位置
- [两种 Agent 类型](../requirements.md#两种-agent-类型)：详细说明