150 lines
6.6 KiB
Markdown
150 lines
6.6 KiB
Markdown
# 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 消息的逐字生成过程。
|