# OpenCode 对话功能实现路径

本文档旨在提供一个在 OpenCode 平台中实现对话功能的完整技术路径，涵盖会话管理、消息发送以及利用事件流（SSE）进行流式渲染的详细步骤和建议。

## 1. 核心概念回顾

在 OpenCode 中实现对话功能，主要依赖以下几个核心接口：

*   **`POST /session`**: 用于创建新的对话会话，获取 `sessionID`。
*   **`POST /session/:id/prompt_async`**: 用于异步发送用户消息到指定会话，服务器会立即返回，不等待 AI 响应完成。
*   **`GET /event`**: 作为 SSE（Server-Sent Events）接口，用于实时接收服务器产生的各类事件，包括 AI 消息的生成和更新。
*   **`GET /session/:id/message`**: 用于获取指定会话的历史消息记录。

## 2. 对话生命周期与接口调用顺序

以下是实现一个完整的流式对话功能的推荐流程：

### 步骤 1: 初始化 - 创建会话

在用户开始对话之前，需要为其创建一个新的会话。每个会话都有一个唯一的 `sessionID`，用于标识和管理该对话的上下文。

*   **接口**: `POST /session`
*   **用途**: 启动一个新的对话。
*   **请求体示例**: `{
    "title": "我的新对话"
}` (标题可选)
*   **响应**: 返回一个 `Session` 对象，其中包含 `id` 字段，即 `sessionID`。

```json
{
  "id": "some-session-id",
  "title": "我的新对话",
  "createdAt": "2023-01-01T12:00:00Z",
  "updatedAt": "2023-01-01T12:00:00Z"
}
```

### 步骤 2: 建立事件监听

为了实现 AI 响应的流式渲染，客户端需要连接到 `/event` 接口，持续监听服务器发出的事件。这将允许您实时接收 AI 生成的文本片段。

*   **接口**: `GET /event`
*   **用途**: 接收服务器发送的实时事件流（SSE）。
*   **机制**: 客户端建立一个持久的 HTTP 连接，服务器通过此连接推送事件。您需要一个支持 SSE 的客户端库来处理这个连接。
*   **过滤**: 客户端需要根据 `sessionID` 和 `messageID`（稍后从 `prompt_async` 的响应中获取或从事件流中识别）来过滤和处理相关事件。

**伪代码示例 (JavaScript)**:

```javascript
const eventSource = new EventSource('/event');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // 根据事件类型和 sessionID 过滤事件
  if (data.type === 'message.updated' && data.sessionID === currentSessionId) {
    // 处理消息更新事件，例如追加 AI 生成的文本片段到 UI
    console.log('Received message update:', data.message.parts);
    // 假设 data.message.parts[0].text 包含最新文本
    // updateUIWithStreamingText(data.message.parts[0].text);
  }
  // 其他事件处理，例如 message.created, session.updated 等
};

eventSource.onerror = (error) => {
  console.error('EventSource failed:', error);
  eventSource.close();
};
```

### 步骤 3: 发送用户消息

当用户输入消息后，通过 `prompt_async` 接口将其发送到服务器。这个接口会立即返回，不会阻塞客户端，让流式渲染可以同时进行。

*   **接口**: `POST /session/:id/prompt_async`
*   **用途**: 异步发送用户消息，触发 AI 响应生成。
*   **路径参数**: `:id` 为当前会话的 `sessionID`。
*   **请求体示例**: `{
    "parts": [
      { "text": "你好，OpenCode！" }
    ],
    "model": "your-model-id", // 可选，指定使用的模型
    "agent": "your-agent-id"  // 可选，指定使用的代理
}`
*   **响应**: `204 No Content`。这意味着服务器已接收请求并开始处理，但不会立即返回 AI 的完整响应。

**伪代码示例 (JavaScript)**:

```javascript
async function sendUserMessage(sessionId, messageText) {
  const response = await fetch(`/session/${sessionId}/prompt_async`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      parts: [{ text: messageText }]
    })
  });

  if (response.status === 204) {
    console.log('User message sent successfully, awaiting streaming response via /event.');
    // 此时前端可以显示用户消息，并准备接收 AI 的流式响应
  } else {
    console.error('Failed to send user message:', response.statusText);
  }
}
```

### 步骤 4: 处理流式响应与渲染

在步骤 2 中建立的 `/event` 监听器会接收到 AI 生成消息的实时更新。您需要解析这些事件，并将 AI 生成的文本片段逐步显示在用户界面上。

*   **事件类型**: 主要关注 `message.updated` 事件，其 `message` 字段会包含 `parts` 数组，其中包含 AI 正在生成的文本。
*   **渲染逻辑**: 每次收到新的文本片段时，将其追加到 AI 消息的显示区域，而不是替换。
*   **完成标志**: 当 AI 消息生成完成时，通常会有一个特定的事件或 `message.updated` 事件中的状态标志来指示。例如，当 `message.updated` 事件中的 `message.status` 变为 `completed` 或 `final` 时，表示流式输出结束。

### 步骤 5: 获取历史消息 (可选)

如果用户重新加载页面或需要查看之前的对话记录，可以使用此接口获取会话的所有历史消息。

*   **接口**: `GET /session/:id/message`
*   **用途**: 获取指定会话的所有消息。
*   **路径参数**: `:id` 为当前会话的 `sessionID`。
*   **查询参数**: `limit?` (可选) 用于限制返回的消息数量。
*   **响应**: 返回一个消息数组，每个元素包含 `info: Message` 和 `parts: Part[]`。

## 3. 完整流程图

```mermaid
graph TD
    A[用户打开应用] --> B{是否已有会话?}
    B -- 否 --> C[调用 POST /session]
    C --> D[获取 sessionID]
    B -- 是 --> D[使用现有 sessionID]
    D --> E[建立 GET /event SSE 连接]
    E --> F[用户输入消息]
    F --> G[调用 POST /session/:id/prompt_async]
    G --> H[前端显示用户消息]
    H --> I[通过 SSE 接收 message.updated 事件]
    I -- 文本片段 --> J[实时渲染 AI 响应]
    I -- 消息完成 --> K[AI 响应渲染完成]
    K --> F
    subgraph 历史消息
        L[用户请求历史消息] --> M[调用 GET /session/:id/message]
        M --> N[显示历史消息]
    end
```

## 4. 总结

在 OpenCode 中实现流式对话功能，关键在于**分离消息发送和消息接收**。通过 `POST /session/:id/prompt_async` 异步发送消息，并通过 `GET /event` 实时监听服务器的总线事件来获取 AI 生成的文本片段，从而实现流畅的流式问答体验。`GET /event` 接口是您实现流式渲染的正确选择，因为它提供了所有会话相关的实时更新，包括 AI 消息的逐字生成过程。