deep-searcher/simplified_message_format.md

# 简化消息格式

## 概述

为了简化前后端的消息通信，我们将原来的多种消息类型统一为简单的 `type` 和 `content` 格式。

## 消息格式

所有消息都遵循以下统一格式：

```json
{
    "type": "消息类型",
    "content": "消息内容",
    "timestamp": 时间戳,
    "metadata": {}
}
```

## 消息类型

### 1. start - 开始消息
- **用途**: 表示查询或操作的开始
- **示例**: 
```json
{
    "type": "start",
    "content": "开始处理查询: 请写一篇关于Milvus向量数据库的报告"
}
```

### 2. info - 信息消息
- **用途**: 表示处理过程中的信息、状态更新、迭代信息等
- **示例**:
```json
{
    "type": "info", 
    "content": "iteration 1: 正在搜索相关文档..."
}
```

### 3. answer - 答案消息
- **用途**: 表示最终答案或重要结果
- **示例**:
```json
{
    "type": "answer",
    "content": "Milvus的详细报告: ..."
}
```

### 4. complete - 完成消息
- **用途**: 表示操作完成
- **示例**:
```json
{
    "type": "complete",
    "content": "查询完成"
}
```

### 5. error - 错误消息
- **用途**: 表示错误信息
- **示例**:
```json
{
    "type": "error",
    "content": "查询失败: 无法连接到数据库"
}
```

## 使用示例

### 后端使用

```python
from deepsearcher.utils.message_stream import (
    send_start, send_info, send_answer, send_complete, send_error
)

# 发送开始消息
send_start("开始处理查询: 请写一篇关于Milvus的报告")

# 发送信息消息
send_info("iteration 1: 正在搜索相关文档...")
send_info("找到5个相关文档片段")

# 发送答案消息
send_answer("Milvus的详细报告: ...")

# 发送完成消息
send_complete("查询完成")

# 发送错误消息
send_error("查询失败: 无法连接到数据库")
```

### 前端处理

```javascript
// 处理消息流
function handleStreamMessage(data) {
    const message = JSON.parse(data);
    
    switch (message.type) {
        case 'start':
            console.log('开始:', message.content);
            break;
        case 'info':
            console.log('信息:', message.content);
            break;
        case 'answer':
            console.log('答案:', message.content);
            break;
        case 'complete':
            console.log('完成:', message.content);
            break;
        case 'error':
            console.error('错误:', message.content);
            break;
    }
}
```

## 优势

1. **简化格式**: 统一的消息格式，易于理解和处理
2. **类型清晰**: 5种基本类型覆盖所有使用场景
3. **易于扩展**: 可以轻松添加新的消息类型
4. **前端友好**: 前端处理逻辑更加简单
5. **调试方便**: 消息格式清晰，便于调试和日志记录

## 迁移说明

### 从旧格式迁移

| 旧类型 | 新类型 | 说明 |
|--------|--------|------|
| `search` | `info` | 搜索相关信息 |
| `think` | `info` | 思考过程信息 |
| `answer` | `answer` | 保持不变 |
| `complete` | `complete` | 保持不变 |
| `query_start` | `start` | 查询开始 |
| `query_error` | `error` | 查询错误 |
| `stream_error` | `error` | 流错误 |

### 代码更新

所有使用旧消息类型的代码都需要更新：

```python
# 旧代码
send_search("搜索内容...")
send_think("思考内容...")

# 新代码
send_info("搜索内容...")
send_info("思考内容...")
```

## 测试

可以使用以下方式测试消息格式：

```python
from deepsearcher.utils.message_stream import get_message_stream

# 获取消息流实例
message_stream = get_message_stream()

# 获取所有消息
messages = message_stream.get_messages_as_dicts()

# 验证格式
for msg in messages:
    assert 'type' in msg
    assert 'content' in msg
    assert 'timestamp' in msg
    print(f"类型: {msg['type']}, 内容: {msg['content']}")
```