# 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` 可以用于异步发送消息，提升用户体验。