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