feat: 开发对话功能

doc/OpenCode 对话功能实现路径.md

@@ -0,0 +1,149 @@
+# 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 消息的逐字生成过程。