feat: 开发对话功能
This commit is contained in:
99
doc/OpenCode API 总结与对话功能接口分析.md
Normal file
99
doc/OpenCode API 总结与对话功能接口分析.md
Normal file
@@ -0,0 +1,99 @@
|
||||
# OpenCode API 总结与对话功能接口分析
|
||||
|
||||
## 1. API 总结表格
|
||||
|
||||
以下表格总结了 OpenCode 服务器暴露的 API 的用途、传参和返回值格式：
|
||||
|
||||
| 分类 | 方法 | 路径 | 描述 | 请求体/查询参数 | 响应 |
|
||||
|---|---|---|:-:|---|---|
|
||||
| **全局** | `GET` | `/global/health` | 获取服务器健康状态和版本 | 无 | `{ healthy: true, version: string }` |
|
||||
| | `GET` | `/global/event` | 获取全局事件（SSE 流） | 无 | 事件流 |
|
||||
| **项目** | `GET` | `/project` | 列出所有项目 | 无 | `Project[]` |
|
||||
| | `GET` | `/project/current` | 获取当前项目 | 无 | `Project` |
|
||||
| **路径和 VCS** | `GET` | `/path` | 获取当前路径 | 无 | `Path` |
|
||||
| | `GET` | `/vcs` | 获取当前项目的 VCS 信息 | 无 | `VcsInfo` |
|
||||
| **实例** | `POST` | `/instance/dispose` | 销毁当前实例 | 无 | `boolean` |
|
||||
| **配置** | `GET` | `/config` | 获取配置信息 | 无 | `Config` |
|
||||
| | `PATCH` | `/config` | 更新配置 | `Config` | `Config` |
|
||||
| | `GET` | `/config/providers` | 列出提供商和默认模型 | 无 | `{ providers: Provider[], default: { [key: string]: string } }` |
|
||||
| **提供商** | `GET` | `/provider` | 列出所有提供商 | 无 | `{ all: Provider[], default: {...}, connected: string[] }` |
|
||||
| | `GET` | `/provider/auth` | 获取提供商认证方式 | 无 | `{ [providerID: string]: ProviderAuthMethod[] }` |
|
||||
| | `POST` | `/provider/{id}/oauth/authorize` | 使用 OAuth 授权提供商 | 无 | `ProviderAuthAuthorization` |
|
||||
| | `POST` | `/provider/{id}/oauth/callback` | 处理提供商的 OAuth 回调 | 无 | `boolean` |
|
||||
| **会话** | `GET` | `/session` | 列出所有会话 | 无 | `Session[]` |
|
||||
| | `POST` | `/session` | 创建新会话 | `{ parentID?, title? }` | `Session` |
|
||||
| | `GET` | `/session/status` | 获取所有会话的状态 | 无 | `{ [sessionID: string]: SessionStatus }` |
|
||||
| | `GET` | `/session/:id` | 获取会话详情 | 无 | `Session` |
|
||||
| | `DELETE` | `/session/:id` | 删除会话及其所有数据 | 无 | `boolean` |
|
||||
| | `PATCH` | `/session/:id` | 更新会话属性 | `{ title? }` | `Session` |
|
||||
| | `GET` | `/session/:id/children` | 获取会话的子会话 | 无 | `Session[]` |
|
||||
| | `GET` | `/session/:id/todo` | 获取会话的待办事项列表 | 无 | `Todo[]` |
|
||||
| | `POST` | `/session/:id/init` | 分析应用并创建 AGENTS.md | `{ messageID, providerID, modelID }` | `boolean` |
|
||||
| | `POST` | `/session/:id/fork` | 在某条消息处分叉现有会话 | `{ messageID? }` | `Session` |
|
||||
| | `POST` | `/session/:id/abort` | 中止正在运行的会话 | 无 | `boolean` |
|
||||
| | `POST` | `/session/:id/share` | 分享会话 | 无 | `Session` |
|
||||
| | `DELETE` | `/session/:id/share` | 取消分享会话 | 无 | `Session` |
|
||||
| | `GET` | `/session/:id/diff` | 获取本次会话的差异 | `messageID?` | `FileDiff[]` |
|
||||
| | `POST` | `/session/:id/summarize` | 总结会话 | `{ providerID, modelID }` | `boolean` |
|
||||
| | `POST` | `/session/:id/revert` | 回退消息 | `{ messageID, partID? }` | `boolean` |
|
||||
| | `POST` | `/session/:id/unrevert` | 恢复所有已回退的消息 | 无 | `boolean` |
|
||||
| | `POST` | `/session/:id/permissions/:permissionID` | 响应权限请求 | `{ response, remember? }` | `boolean` |
|
||||
| **消息** | `GET` | `/session/:id/message` | 列出会话中的消息 | `limit?` | `{ info: Message, parts: Part[]}[]` |
|
||||
| | `POST` | `/session/:id/message` | 发送消息并等待响应 | `{ messageID?, model?, agent?, noReply?, system?, tools?, parts }` | `{ info: Message, parts: Part[]}` |
|
||||
| | `GET` | `/session/:id/message/:messageID` | 获取消息详情 | 无 | `{ info: Message, parts: Part[]}` |
|
||||
| | `POST` | `/session/:id/prompt_async` | 异步发送消息（不等待响应） | 与 `/session/:id/message` 相同 | `204 No Content` |
|
||||
| | `POST` | `/session/:id/command` | 执行斜杠命令 | `{ messageID?, agent?, model?, command, arguments }` | `{ info: Message, parts: Part[]}` |
|
||||
| | `POST` | `/session/:id/shell` | 运行 shell 命令 | `{ agent, model?, command }` | `{ info: Message, parts: Part[]}` |
|
||||
| **命令** | `GET` | `/command` | 列出所有命令 | 无 | `Command[]` |
|
||||
| **文件** | `GET` | `/find?pattern=<pat>` | 在文件中搜索文本 | `pattern` | 匹配对象数组 |
|
||||
| | `GET` | `/find/file?query=<q>` | 按名称查找文件和目录 | `query` | `string[]`（路径） |
|
||||
| | `GET` | `/find/symbol?query=<q>` | 查找工作区符号 | `query` | `Symbol[]` |
|
||||
| | `GET` | `/file?path=<path>` | 列出文件和目录 | `path` | `FileNode[]` |
|
||||
| | `GET` | `/file/content?path=<p>` | 读取文件 | `path` | `FileContent` |
|
||||
| | `GET` | `/file/status` | 获取已跟踪文件的状态 | 无 | `File[]` |
|
||||
| **工具（实验性）** | `GET` | `/experimental/tool/ids` | 列出所有工具 ID | 无 | `ToolIDs` |
|
||||
| | `GET` | `/experimental/tool?provider=<p>&model=<m>` | 列出指定模型的工具及其 JSON Schema | `provider, model` | `ToolList` |
|
||||
| **LSP、格式化器和 MCP** | `GET` | `/lsp` | 获取 LSP 服务器状态 | 无 | `LSPStatus[]` |
|
||||
| | `GET` | `/formatter` | 获取格式化器状态 | 无 | `FormatterStatus[]` |
|
||||
| | `GET` | `/mcp` | 获取 MCP 服务器状态 | 无 | `{ [name: string]: MCPStatus }` |
|
||||
| | `POST` | `/mcp` | 动态添加 MCP 服务器 | `{ name, config }` | MCP 状态对象 |
|
||||
| **代理** | `GET` | `/agent` | 列出所有可用的代理 | 无 | `Agent[]` |
|
||||
| **日志** | `POST` | `/log` | 写入日志条目 | `{ service, level, message, extra? }` | `boolean` |
|
||||
| **TUI** | `POST` | `/tui/append-prompt` | 向提示词追加文本 | 无 | `boolean` |
|
||||
| | `POST` | `/tui/open-help` | 打开帮助对话框 | 无 | `boolean` |
|
||||
| | `POST` | `/tui/open-sessions` | 打开会话选择器 | 无 | `boolean` |
|
||||
| | `POST` | `/tui/open-themes` | 打开主题选择器 | 无 | `boolean` |
|
||||
| | `POST` | `/tui/open-models` | 打开模型选择器 | 无 | `boolean` |
|
||||
| | `POST` | `/tui/submit-prompt` | 提交当前提示词 | 无 | `boolean` |
|
||||
| | `POST` | `/tui/clear-prompt` | 清除提示词 | 无 | `boolean` |
|
||||
| | `POST` | `/tui/execute-command` | 执行命令 | `{ command }` | `boolean` |
|
||||
| | `POST` | `/tui/show-toast` | 显示提示消息 | `{ title?, message, variant }` | `boolean` |
|
||||
| | `GET` | `/tui/control/next` | 等待下一个控制请求 | 无 | 控制请求对象 |
|
||||
| | `POST` | `/tui/control/response` | 响应控制请求 | `{ body }` | `boolean` |
|
||||
| **认证** | `PUT` | `/auth/:id` | 设置认证凭据 | 必须匹配提供商的数据结构 | `boolean` |
|
||||
| **事件** | `GET` | `/event` | 服务器发送事件流 | 无 | 服务器发送事件流 |
|
||||
| **文档** | `GET` | `/doc` | OpenAPI 3.1 规范 | 无 | 包含 OpenAPI 规范的 HTML 页面 |
|
||||
|
||||
## 2. 对话功能接口分析
|
||||
|
||||
根据您的需求，实现对话功能，最核心的接口是 **消息 (Message)** 类别下的 API。
|
||||
|
||||
具体来说，您应该使用以下接口：
|
||||
|
||||
* **`POST /session/:id/message`**: 这个接口用于**发送消息并等待响应**。这是实现对话功能最主要的接口，您可以通过它向 OpenCode 服务器发送用户输入的消息，并获取服务器返回的对话响应。请求体中可以包含 `messageID` (可选), `model` (可选), `agent` (可选), `noReply` (可选), `system` (可选), `tools` (可选), `parts` 等参数，返回 `{ info: Message, parts: Part[]}`，其中 `info` 包含消息的元数据，`parts` 包含消息的具体内容。
|
||||
|
||||
* **`GET /session/:id/message`**: 这个接口用于**列出会话中的消息**。在对话过程中，您可能需要获取历史消息记录以展示给用户或进行上下文管理。通过 `limit?` 查询参数可以限制返回的消息数量，返回 `{ info: Message, parts: Part[]}[]`。
|
||||
|
||||
* **`GET /session/:id/message/:messageID`**: 这个接口用于**获取消息详情**。如果您需要获取特定消息的详细信息，可以使用此接口，返回 `{ info: Message, parts: Part[]}`。
|
||||
|
||||
* **`POST /session/:id/prompt_async`**: 这个接口用于**异步发送消息（不等待响应）**。如果您希望发送消息后立即返回，不等待服务器的响应，可以使用此接口。这在某些场景下可能有助于提高用户体验，例如在后台处理耗时操作时。请求体与 `POST /session/:id/message` 相同，返回 `204 No Content`。
|
||||
|
||||
除了上述消息相关的接口，**会话 (Session)** 类别下的接口也至关重要，特别是：
|
||||
|
||||
* **`POST /session`**: 用于**创建新会话**。在开始新的对话之前，您需要创建一个会话。请求体可以包含 `parentID?` (可选) 和 `title?` (可选)，返回 `Session` 对象。
|
||||
|
||||
* **`GET /session`**: 用于**列出所有会话**。您可以获取当前用户的所有会话列表，以便用户选择或管理历史对话。
|
||||
|
||||
**总结：**
|
||||
|
||||
要实现对话功能，您首先需要通过 `POST /session` 创建一个会话，然后使用 `POST /session/:id/message` 发送用户消息并接收响应。同时，您可以使用 `GET /session/:id/message` 来获取历史消息，以维护对话上下文。`POST /session/:id/prompt_async` 可以用于异步发送消息，提升用户体验。
|
||||
149
doc/OpenCode 对话功能实现路径.md
Normal file
149
doc/OpenCode 对话功能实现路径.md
Normal file
@@ -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 消息的逐字生成过程。
|
||||
Reference in New Issue
Block a user