287 lines
20 KiB
Text
287 lines
20 KiB
Text
---
|
||
title: Сервер
|
||
description: Взаимодействуйте с сервером открытого кода через HTTP.
|
||
---
|
||
|
||
import config from "../../../../config.mjs"
|
||
export const typesUrl = `${config.github}/blob/dev/packages/sdk/js/src/gen/types.gen.ts`
|
||
|
||
Команда `opencode serve` запускает автономный HTTP-сервер, который предоставляет конечную точку OpenAPI, которую может использовать клиент с открытым кодом.
|
||
|
||
---
|
||
|
||
### Использование
|
||
|
||
```bash
|
||
opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]
|
||
```
|
||
|
||
#### Параметры
|
||
|
||
| Флаг | Описание | По умолчанию |
|
||
| ----- | ---------------------------------------------- | ------------ |
|
||
| `--port` | Port to listen on | `4096` |
|
||
| `--hostname` | Hostname to listen on | `127.0.0.1` |
|
||
| `--mdns` | Enable mDNS discovery | `false` |
|
||
| `--mdns-domain` | Custom domain name for mDNS service | `opencode.local` |
|
||
| `--cors` | Additional browser origins to allow | `[]` |
|
||
|
||
`--cors` можно передать несколько раз:
|
||
|
||
```bash
|
||
opencode serve --cors http://localhost:5173 --cors https://app.example.com
|
||
```
|
||
|
||
---
|
||
|
||
### Аутентификация
|
||
|
||
Установите `OPENCODE_SERVER_PASSWORD`, чтобы защитить сервер с помощью базовой аутентификации HTTP. Имя пользователя по умолчанию — `opencode` или установите `OPENCODE_SERVER_USERNAME`, чтобы переопределить его. Это относится как к `opencode serve`, так и к `opencode web`.
|
||
|
||
```bash
|
||
OPENCODE_SERVER_PASSWORD=your-password opencode serve
|
||
```
|
||
|
||
---
|
||
|
||
### Как это работает
|
||
|
||
Когда вы запускаете `opencode`, он запускает TUI и сервер. Где находится TUI
|
||
клиент, который общается с сервером. Сервер предоставляет спецификацию OpenAPI 3.1.
|
||
конечная точка. Эта конечная точка также используется для создания файла [SDK](/docs/sdk).
|
||
|
||
:::tip
|
||
Используйте сервер открытого кода для программного взаимодействия с открытым кодом.
|
||
:::
|
||
|
||
Эта архитектура позволяет открытому коду поддерживать несколько клиентов и позволяет программно взаимодействовать с открытым кодом.
|
||
|
||
Вы можете запустить `opencode serve`, чтобы запустить автономный сервер. Если у вас есть
|
||
TUI с открытым кодом запущен, `opencode serve` запустит новый сервер.
|
||
|
||
---
|
||
|
||
#### Подключиться к существующему серверу
|
||
|
||
Когда вы запускаете TUI, он случайным образом назначает порт и имя хоста. Вместо этого вы можете передать `--hostname` и `--port` [flags](/docs/cli). Затем используйте это для подключения к его серверу.
|
||
|
||
Конечную точку [`/tui`](#tui) можно использовать для управления TUI через сервер. Например, вы можете предварительно заполнить или запустить подсказку. Эта настройка используется плагинами OpenCode [IDE](/docs/ide).
|
||
|
||
---
|
||
|
||
## Спецификация
|
||
|
||
Сервер публикует спецификацию OpenAPI 3.1, которую можно просмотреть по адресу:
|
||
|
||
```
|
||
http://<hostname>:<port>/doc
|
||
```
|
||
|
||
For example, `http://localhost:4096/doc`. Use the spec to generate clients or inspect request and response types. Or view it in a Swagger explorer.
|
||
|
||
---
|
||
|
||
## API
|
||
|
||
Сервер открытого кода предоставляет следующие API.
|
||
|
||
---
|
||
|
||
### Глобальный
|
||
|
||
| Метод | Путь | Описание | Ответ |
|
||
| ----- | ----- | ------------------------------------------------ | ------------------ |
|
||
| `GET` | `/global/health` | Get server health and version | `{ healthy: true, version: string }` |
|
||
| `GET` | `/global/event` | Get global events (SSE stream) | Event stream |
|
||
|
||
---
|
||
|
||
### Проект
|
||
|
||
| Метод | Путь | Описание | Ответ |
|
||
| ----- | ----- | ----------------------- | -------------------------------------------- |
|
||
| `GET` | `/project` | List all projects | <a href={typesUrl}><code>Project[]</code></a> |
|
||
| `GET` | `/project/current` | Get the current project | <a href={typesUrl}><code>Project</code></a> |
|
||
|
||
---
|
||
|
||
### Путь и система контроля версий
|
||
|
||
| Метод | Путь | Описание | Ответ |
|
||
| ----- | ----- | -------------------------------------------- | ------------------------------------------- |
|
||
| `GET` | `/path` | Get the current path | <a href={typesUrl}><code>Path</code></a> |
|
||
| `GET` | `/vcs` | Get VCS info for the current project | <a href={typesUrl}><code>VcsInfo</code></a> |
|
||
|
||
---
|
||
|
||
### Пример
|
||
|
||
| Метод | Путь | Описание | Ответ |
|
||
| ----- | ----- | ------------------------- | ----- |
|
||
| `POST` | `/instance/dispose` | Dispose the current instance | `boolean` |
|
||
|
||
---
|
||
|
||
### Конфигурация
|
||
|
||
| Метод | Путь | Описание | Ответ |
|
||
| ----- | ----- | ----------------------------------------- | ---------------------------------------------------------------------------------------- |
|
||
| `GET` | `/config` | Get config info | <a href={typesUrl}><code>Config</code></a> |
|
||
| `PATCH` | `/config` | Update config | <a href={typesUrl}><code>Config</code></a> |
|
||
| `GET` | `/config/providers` | List providers and default models | `{ providers: `<a href={typesUrl}>Provider[]</a>`, default: { [key: string]: string } }` |
|
||
|
||
---
|
||
|
||
### Поставщик
|
||
|
||
| Метод | Путь | Описание | Ответ |
|
||
| ----- | ----- | ----------------------------------------------- | ----------------------------------------------------------------------------------- |
|
||
| `GET` | `/provider` | List all providers | `{ all: `<a href={typesUrl}>Provider[]</a>`, default: {...}, connected: string[] }` |
|
||
| `GET` | `/provider/auth` | Get provider authentication methods | `{ [providerID: string]: `<a href={typesUrl}>ProviderAuthMethod[]</a>` }` |
|
||
| `POST` | `/provider/{id}/oauth/authorize` | Authorize a provider using OAuth | <a href={typesUrl}><code>ProviderAuthAuthorization</code></a> |
|
||
| `POST` | `/provider/{id}/oauth/callback` | Handle OAuth callback for a provider | `boolean` |
|
||
|
||
---
|
||
|
||
### Сессии
|
||
|
||
| Метод | Путь | Описание | Примечания |
|
||
| ----- | ----- | -------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
||
| `GET` | `/session` | List all sessions | Returns <a href={typesUrl}><code>Session[]</code></a> |
|
||
| `POST` | `/session` | Create a new session | body: `{ parentID?, title? }`, returns <a href={typesUrl}><code>Session</code></a> |
|
||
| `GET` | `/session/status` | Get session status for all sessions | Returns `{ [sessionID: string]: `<a href={typesUrl}>SessionStatus</a>` }` |
|
||
| `GET` | `/session/:id` | Get session details | Returns <a href={typesUrl}><code>Session</code></a> |
|
||
| `DELETE` | `/session/:id` | Delete a session and all its data | Returns `boolean` |
|
||
| `PATCH` | `/session/:id` | Update session properties | body: `{ title? }`, returns <a href={typesUrl}><code>Session</code></a> |
|
||
| `GET` | `/session/:id/children` | Get a session's child sessions | Returns <a href={typesUrl}><code>Session[]</code></a> |
|
||
| `GET` | `/session/:id/todo` | Get the todo list for a session | Returns <a href={typesUrl}><code>Todo[]</code></a> |
|
||
| `POST` | `/session/:id/init` | Analyze app and create `AGENTS.md` | body: `{ messageID, providerID, modelID }`, returns `boolean` |
|
||
| `POST` | `/session/:id/fork` | Fork an existing session at a message | body: `{ messageID? }`, returns <a href={typesUrl}><code>Session</code></a> |
|
||
| `POST` | `/session/:id/abort` | Abort a running session | Returns `boolean` |
|
||
| `POST` | `/session/:id/share` | Share a session | Returns <a href={typesUrl}><code>Session</code></a> |
|
||
| `DELETE` | `/session/:id/share` | Unshare a session | Returns <a href={typesUrl}><code>Session</code></a> |
|
||
| `GET` | `/session/:id/diff` | Get the diff for this session | query: `messageID?`, returns <a href={typesUrl}><code>FileDiff[]</code></a> |
|
||
| `POST` | `/session/:id/summarize` | Summarize the session | body: `{ providerID, modelID }`, returns `boolean` |
|
||
| `POST` | `/session/:id/revert` | Revert a message | body: `{ messageID, partID? }`, returns `boolean` |
|
||
| `POST` | `/session/:id/unrevert` | Restore all reverted messages | Returns `boolean` |
|
||
| `POST` | `/session/:id/permissions/:permissionID` | Respond to a permission request | body: `{ response, remember? }`, returns `boolean` |
|
||
|
||
---
|
||
|
||
### Сообщения
|
||
|
||
| Метод | Путь | Описание | Примечания |
|
||
| ----- | ----- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| `GET` | `/session/:id/message` | List messages in a session | query: `limit?`, returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}[]` |
|
||
| `POST` | `/session/:id/message` | Send a message and wait for response | body: `{ messageID?, model?, agent?, noReply?, system?, tools?, parts }`, returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
|
||
| `GET` | `/session/:id/message/:messageID` | Get message details | Returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
|
||
| `POST` | `/session/:id/prompt_async` | Send a message asynchronously (no wait) | body: same as `/session/:id/message`, returns `204 No Content` |
|
||
| `POST` | `/session/:id/command` | Execute a slash command | body: `{ messageID?, agent?, model?, command, arguments }`, returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
|
||
| `POST` | `/session/:id/shell` | Run a shell command | body: `{ agent, model?, command }`, returns `{ info: `<a href={typesUrl}>Message</a>`, parts: `<a href={typesUrl}>Part[]</a>`}` |
|
||
|
||
---
|
||
|
||
### Команды
|
||
|
||
| Метод | Путь | Описание | Ответ |
|
||
| ----- | ----- | ------------------ | --------------------------------------------- |
|
||
| `GET` | `/command` | List all commands | <a href={typesUrl}><code>Command[]</code></a> |
|
||
|
||
---
|
||
|
||
### Файлы
|
||
|
||
| Метод | Путь | Описание | Ответ |
|
||
| ----- | ----- | ------------------------------------ | --------------------------------------------------------------------------------------------- |
|
||
| `GET` | `/find?pattern=<pat>` | Search for text in files | Array of match objects with `path`, `lines`, `line_number`, `absolute_offset`, `submatches` |
|
||
| `GET` | `/find/file?query=<q>` | Find files and directories by name | `string[]` (paths) |
|
||
| `GET` | `/find/symbol?query=<q>` | Find workspace symbols | <a href={typesUrl}><code>Symbol[]</code></a> |
|
||
| `GET` | `/file?path=<path>` | List files and directories | <a href={typesUrl}><code>FileNode[]</code></a> |
|
||
| `GET` | `/file/content?path=<p>` | Read a file | <a href={typesUrl}><code>FileContent</code></a> |
|
||
| `GET` | `/file/status` | Get status for tracked files | <a href={typesUrl}><code>File[]</code></a> |
|
||
|
||
#### `/find/file` параметры запроса
|
||
|
||
- `query` (обязательно) — строка поиска (нечеткое совпадение)
|
||
- `type` (необязательно) — ограничить результаты `"file"` или `"directory"`.
|
||
- `directory` (необязательно) — переопределить корень проекта для поиска.
|
||
- `limit` (необязательно) — максимальное количество результатов (1–200)
|
||
- `dirs` (необязательно) — устаревший флаг (`"false"` возвращает только файлы)
|
||
|
||
---
|
||
|
||
### Инструменты (Экспериментальные)
|
||
|
||
| Метод | Путь | Описание | Ответ |
|
||
| ----- | ----- | ---------------------------------------------- | -------------------------------------------- |
|
||
| `GET` | `/experimental/tool/ids` | List all tool IDs | <a href={typesUrl}><code>ToolIDs</code></a> |
|
||
| `GET` | `/experimental/tool?provider=<p>&model=<m>` | List tools with JSON schemas for a model | <a href={typesUrl}><code>ToolList</code></a> |
|
||
|
||
---
|
||
|
||
### LSP, форматтеры и MCP
|
||
|
||
| Метод | Путь | Описание | Ответ |
|
||
| ----- | ----- | ----------------------------------- | --------------------------------------------------------- |
|
||
| `GET` | `/lsp` | Get LSP server status | <a href={typesUrl}><code>LSPStatus[]</code></a> |
|
||
| `GET` | `/formatter` | Get formatter status | <a href={typesUrl}><code>FormatterStatus[]</code></a> |
|
||
| `GET` | `/mcp` | Get MCP server status | `{ [name: string]: `<a href={typesUrl}>MCPStatus</a>` }` |
|
||
| `POST` | `/mcp` | Add MCP server dynamically | body: `{ name, config }`, returns MCP status object |
|
||
|
||
---
|
||
|
||
### Агенты
|
||
|
||
| Метод | Путь | Описание | Ответ |
|
||
| ----- | ----- | ----------------------------- | ------------------------------------------- |
|
||
| `GET` | `/agent` | List all available agents | <a href={typesUrl}><code>Agent[]</code></a> |
|
||
|
||
---
|
||
|
||
### Ведение журнала
|
||
|
||
| Метод | Путь | Описание | Ответ |
|
||
| ----- | ----- | ---------------------------------------------------------------------- | ----- |
|
||
| `POST` | `/log` | Write log entry. Body: `{ service, level, message, extra? }` | `boolean` |
|
||
|
||
---
|
||
|
||
### ТУИ
|
||
|
||
| Метод | Путь | Описание | Ответ |
|
||
| ----- | ----- | ---------------------------------------------- | ------------------------- |
|
||
| `POST` | `/tui/append-prompt` | Append text to the prompt | `boolean` |
|
||
| `POST` | `/tui/open-help` | Open the help dialog | `boolean` |
|
||
| `POST` | `/tui/open-sessions` | Open the session selector | `boolean` |
|
||
| `POST` | `/tui/open-themes` | Open the theme selector | `boolean` |
|
||
| `POST` | `/tui/open-models` | Open the model selector | `boolean` |
|
||
| `POST` | `/tui/submit-prompt` | Submit the current prompt | `boolean` |
|
||
| `POST` | `/tui/clear-prompt` | Clear the prompt | `boolean` |
|
||
| `POST` | `/tui/execute-command` | Execute a command (`{ command }`) | `boolean` |
|
||
| `POST` | `/tui/show-toast` | Show toast (`{ title?, message, variant }`) | `boolean` |
|
||
| `GET` | `/tui/control/next` | Wait for the next control request | Control request object |
|
||
| `POST` | `/tui/control/response` | Respond to a control request (`{ body }`) | `boolean` |
|
||
|
||
---
|
||
|
||
### Авторизация
|
||
|
||
| Метод | Путь | Описание | Ответ |
|
||
| ----- | ----- | ------------------------------------------------------------------------------------------- | ----- |
|
||
| `PUT` | `/auth/:id` | Set authentication credentials. Body must match provider schema | `boolean` |
|
||
|
||
---
|
||
|
||
### События
|
||
|
||
| Метод | Путь | Описание | Ответ |
|
||
| ----- | ----- | ---------------------------------------------------------------------------------------------- | ------------------------------------ |
|
||
| `GET` | `/event` | Server-sent events stream. First event is `server.connected`, then bus events | Server-sent events stream |
|
||
|
||
---
|
||
|
||
### Документы
|
||
|
||
| Метод | Путь | Описание | Ответ |
|
||
| ----- | ----- | ------------------------ | -------------------------------------- |
|
||
| `GET` | `/doc` | OpenAPI 3.1 specification | HTML page with OpenAPI spec |
|