406 lines
11 KiB
Markdown
406 lines
11 KiB
Markdown
# Stream Manager 重构:从内容累积到事件流
|
|
|
|
## 问题分析
|
|
|
|
用户指出了一个关键问题:当前只有 `handleFinalAnswer` 在更新 stream,但其他事件(thinking、tool_call、tool_result 等)也应该推送到 stream。这样当用户刷新页面时,可以**恢复完整的输出过程**。
|
|
|
|
### 之前的问题 ❌
|
|
|
|
```go
|
|
// StreamInfo 只存储累积的内容
|
|
type StreamInfo struct {
|
|
SessionID string
|
|
RequestID string
|
|
Query string
|
|
Content string // ❌ 只有累积内容,丢失了事件流
|
|
KnowledgeReferences types.References
|
|
LastUpdated time.Time
|
|
IsCompleted bool
|
|
}
|
|
|
|
// UpdateStream 只能追加内容
|
|
func UpdateStream(ctx, sessionID, requestID string,
|
|
content string, references types.References) error
|
|
```
|
|
|
|
**问题:**
|
|
1. ❌ 只保存最终内容,没有保存事件流
|
|
2. ❌ 刷新页面后,只能看到累积的答案,看不到思考/工具调用过程
|
|
3. ❌ 无法重现完整的 Agent 执行过程
|
|
4. ❌ 用户体验差:刷新后丢失所有中间状态
|
|
|
|
## 改进方案 ✅
|
|
|
|
### 核心思想
|
|
|
|
**从存储内容到存储事件流** - 每个事件(thinking、tool_call、tool_result 等)都推送到stream,刷新时可以完整重放。
|
|
|
|
### 新的数据结构
|
|
|
|
```go
|
|
// StreamEvent 代表一个事件
|
|
type StreamEvent struct {
|
|
Type types.ResponseType // 事件类型
|
|
Content string // 事件内容
|
|
Done bool // 是否完成
|
|
Timestamp time.Time // 事件时间
|
|
Data map[string]interface{} // 附加数据
|
|
}
|
|
|
|
// StreamInfo 存储完整的事件流
|
|
type StreamInfo struct {
|
|
SessionID string
|
|
RequestID string
|
|
Query string
|
|
Events []StreamEvent // ✅ 完整的事件流
|
|
KnowledgeReferences types.References
|
|
LastUpdated time.Time
|
|
IsCompleted bool
|
|
}
|
|
```
|
|
|
|
### 新的接口
|
|
|
|
```go
|
|
type StreamManager interface {
|
|
// RegisterStream 注册新流
|
|
RegisterStream(ctx, sessionID, requestID, query string) error
|
|
|
|
// PushEvent 推送单个事件 ✅
|
|
PushEvent(ctx, sessionID, requestID string, event StreamEvent) error
|
|
|
|
// UpdateReferences 更新知识引用 ✅
|
|
UpdateReferences(ctx, sessionID, requestID string, references types.References) error
|
|
|
|
// CompleteStream 完成流
|
|
CompleteStream(ctx, sessionID, requestID string) error
|
|
|
|
// GetStream 获取流(用于刷新重放)✅
|
|
GetStream(ctx, sessionID, requestID string) (*StreamInfo, error)
|
|
}
|
|
```
|
|
|
|
## 实现详情
|
|
|
|
### 1. AgentStreamHandler - 推送所有事件
|
|
|
|
#### handleThought
|
|
|
|
```go
|
|
func (h *AgentStreamHandler) handleThought(...) error {
|
|
// 1. 发送 SSE
|
|
h.ginContext.SSEvent("message", response)
|
|
h.ginContext.Writer.Flush()
|
|
|
|
// 2. 推送事件到 stream(用于刷新重放)✅
|
|
h.streamManager.PushEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{
|
|
Type: types.ResponseTypeThinking,
|
|
Content: data.Content,
|
|
Done: data.Done,
|
|
Timestamp: time.Now(),
|
|
})
|
|
}
|
|
```
|
|
|
|
#### handleToolCall
|
|
|
|
```go
|
|
func (h *AgentStreamHandler) handleToolCall(...) error {
|
|
// 1. 发送 SSE
|
|
h.ginContext.SSEvent("message", response)
|
|
|
|
// 2. 推送事件到 stream(含工具调用详情)✅
|
|
h.streamManager.PushEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{
|
|
Type: types.ResponseTypeToolCall,
|
|
Content: fmt.Sprintf("Calling tool: %s", data.ToolName),
|
|
Timestamp: time.Now(),
|
|
Data: map[string]interface{}{
|
|
"tool_name": data.ToolName,
|
|
"arguments": data.Arguments,
|
|
},
|
|
})
|
|
}
|
|
```
|
|
|
|
#### handleToolResult
|
|
|
|
```go
|
|
func (h *AgentStreamHandler) handleToolResult(...) error {
|
|
// 1. 发送 SSE
|
|
h.ginContext.SSEvent("message", response)
|
|
|
|
// 2. 推送事件到 stream(含结果详情)✅
|
|
h.streamManager.PushEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{
|
|
Type: responseType,
|
|
Content: content,
|
|
Timestamp: time.Now(),
|
|
Data: map[string]interface{}{
|
|
"tool_name": data.ToolName,
|
|
"success": data.Success,
|
|
"output": data.Output,
|
|
"error": data.Error,
|
|
},
|
|
})
|
|
}
|
|
```
|
|
|
|
#### handleReflection
|
|
|
|
```go
|
|
func (h *AgentStreamHandler) handleReflection(...) error {
|
|
// 1. 发送 SSE
|
|
h.ginContext.SSEvent("message", response)
|
|
|
|
// 2. 推送事件到 stream ✅
|
|
h.streamManager.PushEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{
|
|
Type: "reflection",
|
|
Content: data.Content,
|
|
Timestamp: time.Now(),
|
|
})
|
|
}
|
|
```
|
|
|
|
#### handleFinalAnswer
|
|
|
|
```go
|
|
func (h *AgentStreamHandler) handleFinalAnswer(...) error {
|
|
// 1. 发送 SSE
|
|
h.ginContext.SSEvent("message", response)
|
|
|
|
// 2. 推送事件到 stream ✅
|
|
h.streamManager.PushEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{
|
|
Type: types.ResponseTypeAnswer,
|
|
Content: data.Content,
|
|
Done: data.Done,
|
|
Timestamp: time.Now(),
|
|
})
|
|
}
|
|
```
|
|
|
|
### 2. 刷新重放逻辑
|
|
|
|
#### 之前 ❌ - 只显示累积内容
|
|
|
|
```go
|
|
// 只发送累积的内容
|
|
if streamInfo.Content != "" {
|
|
c.SSEvent("message", &types.StreamResponse{
|
|
Content: streamInfo.Content, // ❌ 失去中间过程
|
|
})
|
|
}
|
|
```
|
|
|
|
#### 现在 ✅ - 完整重放事件流
|
|
|
|
```go
|
|
// 重放所有事件
|
|
if len(streamInfo.Events) > 0 {
|
|
logger.Debugf(ctx, "Replaying %d existing events", len(streamInfo.Events))
|
|
for _, evt := range streamInfo.Events {
|
|
c.SSEvent("message", &types.StreamResponse{
|
|
ID: message.RequestID,
|
|
ResponseType: evt.Type,
|
|
Content: evt.Content,
|
|
Done: evt.Done,
|
|
})
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. 实时监控新事件
|
|
|
|
#### 之前 ❌ - 监控内容增量
|
|
|
|
```go
|
|
// 计算内容差异
|
|
if len(latestStreamInfo.Content) > len(currentContent) {
|
|
newContent := latestStreamInfo.Content[len(currentContent):]
|
|
contentCh <- newContent
|
|
currentContent = latestStreamInfo.Content
|
|
}
|
|
```
|
|
|
|
#### 现在 ✅ - 监控新事件
|
|
|
|
```go
|
|
// 检测新事件
|
|
if len(latestStreamInfo.Events) > currentEventCount {
|
|
eventIndexCh <- currentEventCount
|
|
currentEventCount = len(latestStreamInfo.Events)
|
|
}
|
|
|
|
// 发送新事件
|
|
case startIdx := <-eventIndexCh:
|
|
for i := startIdx; i < len(latestStreamInfo.Events); i++ {
|
|
evt := latestStreamInfo.Events[i]
|
|
c.SSEvent("message", &types.StreamResponse{
|
|
ResponseType: evt.Type,
|
|
Content: evt.Content,
|
|
Done: evt.Done,
|
|
})
|
|
}
|
|
```
|
|
|
|
## 数据流对比
|
|
|
|
### 之前 ❌
|
|
|
|
```
|
|
Agent 执行
|
|
│
|
|
├─→ thinking event → SSE → 前端 (丢失)
|
|
├─→ tool_call event → SSE → 前端 (丢失)
|
|
├─→ tool_result event → SSE → 前端 (丢失)
|
|
└─→ final_answer event → SSE → 前端
|
|
└─→ UpdateStream(累积内容)
|
|
|
|
用户刷新 → GetStream → 只有累积内容 ❌
|
|
```
|
|
|
|
### 现在 ✅
|
|
|
|
```
|
|
Agent 执行
|
|
│
|
|
├─→ thinking event → SSE → 前端
|
|
│ └─→ PushEvent(thinking) ✅
|
|
├─→ tool_call event → SSE → 前端
|
|
│ └─→ PushEvent(tool_call) ✅
|
|
├─→ tool_result event → SSE → 前端
|
|
│ └─→ PushEvent(tool_result) ✅
|
|
└─→ final_answer event → SSE → 前端
|
|
└─→ PushEvent(final_answer) ✅
|
|
|
|
用户刷新 → GetStream → 完整事件流 ✅
|
|
→ 重放所有事件
|
|
```
|
|
|
|
## 优势总结
|
|
|
|
| 方面 | 之前 ❌ | 现在 ✅ |
|
|
|------|---------|---------|
|
|
| **事件保留** | 只保留最终内容 | 保留完整事件流 |
|
|
| **刷新体验** | 丢失中间过程 | 完整重放 |
|
|
| **思考过程** | 不可见 | 可见 |
|
|
| **工具调用** | 不可见 | 可见 |
|
|
| **错误调试** | 困难 | 容易(完整历史) |
|
|
| **用户体验** | 差 | 好 |
|
|
|
|
## 存储实现
|
|
|
|
### Memory Manager
|
|
|
|
```go
|
|
type memoryStreamInfo struct {
|
|
sessionID string
|
|
requestID string
|
|
query string
|
|
events []interfaces.StreamEvent // ✅ 事件数组
|
|
knowledgeReferences types.References
|
|
lastUpdated time.Time
|
|
isCompleted bool
|
|
}
|
|
|
|
func (m *MemoryStreamManager) PushEvent(..., event interfaces.StreamEvent) error {
|
|
stream.events = append(stream.events, event) // ✅ 追加事件
|
|
stream.lastUpdated = time.Now()
|
|
return nil
|
|
}
|
|
```
|
|
|
|
### Redis Manager
|
|
|
|
```go
|
|
type redisStreamInfo struct {
|
|
SessionID string `json:"session_id"`
|
|
RequestID string `json:"request_id"`
|
|
Query string `json:"query"`
|
|
Events []interfaces.StreamEvent `json:"events"` // ✅ 事件数组
|
|
KnowledgeReferences types.References `json:"knowledge_references"`
|
|
LastUpdated time.Time `json:"last_updated"`
|
|
IsCompleted bool `json:"is_completed"`
|
|
}
|
|
|
|
func (r *RedisStreamManager) PushEvent(..., event interfaces.StreamEvent) error {
|
|
info.Events = append(info.Events, event) // ✅ 追加事件
|
|
updatedData, _ := json.Marshal(info)
|
|
return r.client.Set(ctx, key, updatedData, r.ttl).Err()
|
|
}
|
|
```
|
|
|
|
## 使用场景
|
|
|
|
### 场景 1: 正常执行
|
|
|
|
1. Agent 执行过程中,每个事件同时:
|
|
- 发送 SSE 给前端(实时显示)
|
|
- PushEvent 到 stream(持久化)
|
|
|
|
### 场景 2: 刷新页面
|
|
|
|
1. 前端重新连接
|
|
2. GetStream 获取完整事件流
|
|
3. 重放所有事件
|
|
4. 继续监听新事件
|
|
|
|
### 场景 3: 断线重连
|
|
|
|
1. 客户端记录已接收的事件数量
|
|
2. 重连后从 `Events[lastIndex:]` 开始重放
|
|
3. 无缝恢复
|
|
|
|
## 前端适配
|
|
|
|
```typescript
|
|
// 刷新时恢复状态
|
|
const streamInfo = await api.getStream(sessionId, messageId);
|
|
|
|
// 重放所有历史事件
|
|
streamInfo.events.forEach(event => {
|
|
switch (event.type) {
|
|
case 'thinking':
|
|
showThinking(event.content);
|
|
break;
|
|
case 'tool_call':
|
|
showToolCall(event.data.tool_name, event.data.arguments);
|
|
break;
|
|
case 'tool_result':
|
|
showToolResult(event.data.tool_name, event.data.output);
|
|
break;
|
|
case 'answer':
|
|
showAnswer(event.content);
|
|
break;
|
|
}
|
|
});
|
|
|
|
// 继续监听新事件
|
|
connectSSE(sessionId, messageId);
|
|
```
|
|
|
|
## 性能考虑
|
|
|
|
### 内存占用
|
|
|
|
- 每个事件 ~100-500 bytes
|
|
- 典型的 Agent 执行 ~20-50 个事件
|
|
- 总计 ~2-25 KB per session
|
|
- 可接受
|
|
|
|
### Redis 存储
|
|
|
|
- JSON 序列化事件数组
|
|
- TTL 控制:默认 1 小时后自动清理
|
|
- 压缩:Redis 自动处理
|
|
|
|
### 优化策略
|
|
|
|
1. **事件限制**: 可选地限制最大事件数(如 1000个)
|
|
2. **压缩**: 对大量事件进行压缩
|
|
3. **分片**: 超大事件流可以分片存储
|
|
|
|
---
|
|
|
|
**重构完成时间**: 2025-10-31
|
|
**状态**: ✅ 完成,支持完整事件流重放
|
|
|