deep-searcher/simplified_message_format.md

简化消息格式

概述

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

消息格式

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

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

消息类型

1. start - 开始消息

• 用途: 表示查询或操作的开始
• 示例:

{
    "type": "start",
    "content": "开始处理查询: 请写一篇关于Milvus向量数据库的报告"
}

2. info - 信息消息

• 用途: 表示处理过程中的信息、状态更新、迭代信息等
• 示例:

{
    "type": "info", 
    "content": "iteration 1: 正在搜索相关文档..."
}

3. answer - 答案消息

• 用途: 表示最终答案或重要结果
• 示例:

{
    "type": "answer",
    "content": "Milvus的详细报告: ..."
}

4. complete - 完成消息

• 用途: 表示操作完成
• 示例:

{
    "type": "complete",
    "content": "查询完成"
}

5. error - 错误消息

• 用途: 表示错误信息
• 示例:

{
    "type": "error",
    "content": "查询失败: 无法连接到数据库"
}

使用示例

后端使用

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("查询失败: 无法连接到数据库")

前端处理

// 处理消息流
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	流错误

代码更新

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

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

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

测试

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

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']}")