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。

{
  "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):

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):

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. 完整流程图

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 消息的逐字生成过程。

6.6 KiB Raw Blame History Unescape Escape