# SSE 进度事件结构文档

## 📖 概览

本文档说明如何在 OpenAPI Swagger 文档中查看和理解 SSE (Server-Sent Events) 进度流的事件结构。

## 🔍 在 OpenAPI 文档中查看

### 1. 访问 Swagger UI

启动服务后访问：
```
http://localhost:8087/api/docs
```

### 2. 查看 SSE 接口

在 Swagger UI 中找到以下接口：

- **Agent 进度流**: `GET /agent/progress/{session_id}`
- **Computer Agent 进度流**: `GET /computer/agent/progress/{session_id}`

### 3. 查看事件结构

在接口文档的 "Responses" 部分：

1. 点击 **200 响应** 展开详情
2. 在 **description** 中查看：
   - 📡 SSE 事件格式说明
   - 🔄 各种事件类型示例
   - 💡 JavaScript 使用示例

3. 在 **Schemas** 部分查找 `ProgressEventDoc` 获取完整的字段定义

## 📊 事件结构说明

### ProgressEventDoc

通过 SSE 流推送的核心事件结构：

```typescript
interface ProgressEventDoc {
  // 消息主类型
  message_type: "SessionPromptStart" | "SessionPromptEnd" | "AgentSessionUpdate" | "Heartbeat";
  
  // 消息子类型（作为 SSE 的 event 字段）
  sub_type: string;  // agent_message_chunk, tool_call, end_turn 等
  
  // ACP 消息的完整 JSON 载荷（作为 SSE 的 data 字段）
  payload: object;
  
  // 可选的请求 ID
  request_id?: string;
  
  // 时间戳（Unix 毫秒）
  timestamp: number;
}
```

### 常见子类型 (sub_type)

| sub_type | 说明 | payload 示例 |
|----------|------|-------------|
| `agent_message_chunk` | AI 响应文本片段 | `{"content":{"type":"text","text":"Hello"},"index":0}` |
| `agent_thought_chunk` | AI 思考过程片段 | `{"thinking":"正在分析...","is_complete":false}` |
| `tool_call` | 工具调用事件 | `{"tool_name":"read_file","tool_input":{"path":"test.rs"},"status":"started"}` |
| `tool_result` | 工具执行结果 | `{"tool_name":"read_file","tool_output":"...","status":"success"}` |
| `plan` | 执行计划 | `{"steps":[...],"current_step":1}` |
| `end_turn` | 对话轮次结束 | `{"reason":"complete","final_message":"Done"}` |
| `cancelled` | 任务被取消 | `{"reason":"user_request"}` |
| `error` | 错误事件 | `{"code":"EXECUTION_ERROR","message":"..."}` |

## 📡 SSE 原始格式

实际通过网络传输的 SSE 消息格式：

```
event: agent_message_chunk
data: {"content":{"type":"text","text":"正在分析您的请求..."},"index":0}

event: tool_call
data: {"tool_name":"read_file","tool_input":{"path":"src/main.rs"},"status":"started"}

event: tool_result
data: {"tool_name":"read_file","tool_output":"fn main() {...}","status":"success"}

event: end_turn
data: {"reason":"complete","final_message":"任务已完成"}
```

## 💻 客户端使用示例

### JavaScript / TypeScript

```typescript
// 1. 建立 SSE 连接
const eventSource = new EventSource('/agent/progress/session_123');

// 2. 监听特定事件类型
eventSource.addEventListener('agent_message_chunk', (event) => {
  const data = JSON.parse(event.data);
  console.log('AI 响应:', data.content.text);
  // 更新 UI 显示 AI 响应
});

eventSource.addEventListener('tool_call', (event) => {
  const data = JSON.parse(event.data);
  console.log(`工具调用: ${data.tool_name}`, data.tool_input);
  // 显示工具调用状态
});

eventSource.addEventListener('tool_result', (event) => {
  const data = JSON.parse(event.data);
  console.log(`工具结果: ${data.tool_name}`, data.tool_output);
  // 显示工具执行结果
});

eventSource.addEventListener('end_turn', (event) => {
  const data = JSON.parse(event.data);
  console.log('任务完成:', data.final_message);
  eventSource.close();  // 关闭连接
});

// 3. 错误处理
eventSource.onerror = (error) => {
  console.error('连接错误:', error);
  eventSource.close();
};

// 4. 监听所有消息（可选）
eventSource.onmessage = (event) => {
  console.log('收到消息:', event.data);
};
```

### Python

```python
import sseclient
import requests
import json

# 1. 建立 SSE 连接
response = requests.get(
    'http://localhost:8087/agent/progress/session_123',
    stream=True,
    headers={'Accept': 'text/event-stream'}
)

client = sseclient.SSEClient(response)

# 2. 处理事件
for event in client.events():
    if event.event == 'agent_message_chunk':
        data = json.loads(event.data)
        print(f"AI 响应: {data['content']['text']}")
    
    elif event.event == 'tool_call':
        data = json.loads(event.data)
        print(f"工具调用: {data['tool_name']}")
    
    elif event.event == 'end_turn':
        data = json.loads(event.data)
        print(f"任务完成: {data['final_message']}")
        break
```

### Rust

```rust
use eventsource_stream::Eventsource;
use futures_util::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let mut stream = client
        .get("http://localhost:8087/agent/progress/session_123")
        .send()
        .await?
        .bytes_stream()
        .eventsource();

    while let Some(event) = stream.next().await {
        match event {
            Ok(event) => {
                match event.event.as_str() {
                    "agent_message_chunk" => {
                        let data: serde_json::Value = serde_json::from_str(&event.data)?;
                        println!("AI 响应: {}", data["content"]["text"]);
                    }
                    "tool_call" => {
                        let data: serde_json::Value = serde_json::from_str(&event.data)?;
                        println!("工具调用: {}", data["tool_name"]);
                    }
                    "end_turn" => {
                        println!("任务完成");
                        break;
                    }
                    _ => {}
                }
            }
            Err(e) => {
                eprintln!("错误: {}", e);
                break;
            }
        }
    }

    Ok(())
}
```

## 🎯 完整工作流程

```
1. 发起对话
   POST /chat
   ↓
   返回 { session_id: "session_123" }

2. 建立 SSE 连接
   GET /agent/progress/session_123
   ↓
   EventSource 连接建立

3. 接收进度事件
   event: agent_message_chunk
   data: {...}
   ↓
   event: tool_call
   data: {...}
   ↓
   event: tool_result
   data: {...}
   ↓
   event: end_turn
   data: {...}

4. 关闭连接
   eventSource.close()
```

## 🔧 在 Swagger UI 中测试

虽然 Swagger UI 本身不支持直接测试 SSE 流，但你可以：

1. 使用浏览器开发者工具的 Network 标签
2. 使用 `curl` 命令：
   ```bash
   curl -N http://localhost:8087/agent/progress/session_123
   ```
3. 使用专门的 SSE 测试工具

## 📚 相关文档

- [OpenAPI 规范](http://localhost:8087/api/docs)
- [ACP (Agent Client Protocol) 协议文档](../specs/)
- [gRPC 架构文档](./grpc-architecture.md)

## ❓ FAQ

### Q: 为什么在 OpenAPI 中看不到具体的 data 字段？

A: 因为 SSE 是流式响应，OpenAPI 无法像普通 JSON 响应那样定义结构。我们通过以下方式提供文档：

1. **ProgressEventDoc** schema：定义了事件的完整结构
2. **接口 description**：提供详细的事件格式说明和示例
3. **本文档**：提供完整的使用指南

### Q: 如何知道有哪些可能的 sub_type？

A: 查看：
1. Swagger UI 中的接口描述部分
2. `ProgressEventDoc` schema 的 `sub_type` 字段注释
3. 本文档的"常见子类型"表格

### Q: payload 的具体结构在哪里定义？

A: `payload` 是透传的 ACP (Agent Client Protocol) 消息，具体结构取决于 `sub_type`。每种 `sub_type` 的 payload 结构在接口文档的示例中都有说明。

### Q: 如何处理错误？

A: SSE 流可能会发送 `error` 事件，同时监听 `EventSource.onerror` 来处理连接错误：

```javascript
eventSource.addEventListener('error', (event) => {
  const data = JSON.parse(event.data);
  console.error('业务错误:', data.code, data.message);
});

eventSource.onerror = (error) => {
  console.error('连接错误:', error);
};
```

## 📝 总结

- ✅ **在 Swagger UI 中查看**: `ProgressEventDoc` schema 和接口描述
- ✅ **事件格式**: SSE 标准格式，event = sub_type, data = payload
- ✅ **客户端支持**: JavaScript, Python, Rust 等都有成熟的 SSE 客户端库
- ✅ **类型安全**: 可以根据 `ProgressEventDoc` 定义生成 TypeScript 类型