SDK
Pakiet SDK JS/TS OpenCode zapewnia klienta z bezpiecznym typowaniem (type-safe) do interakcji z serwerem. Użyj go do budowania integracji i programowej kontroli OpenCode.
Dowiedz się więcej o działaniu serwera. Przykłady znajdziesz w projektach stworzonych przez społeczność.
Zainstaluj pakiet SDK z npm:
npm install @opencode-ai/sdkUtwórz instancję OpenCode:
import { createOpencode } from "@opencode-ai/sdk"
const { client } = await createOpencode()Spowoduje to uruchomienie zarówno serwera, jak i klienta.
Opcje
| Opcja | Typ | Opis | Domyślne |
|---|---|---|---|
hostname | string | Nazwa hosta serwera | 127.0.0.1 |
port | number | Port serwera | 4096 |
signal | AbortSignal | Sygnał przerwania w celu anulowania | undefined |
timeout | number | Limit czasu w ms dla uruchomienia serwera | 5000 |
config | Config | Obiekt konfiguracji | {} |
Można przekazać obiekt konfiguracyjny, aby dostosować zachowanie. Instancja nadal pobiera opencode.json, ale możesz zastąpić lub dodać konfigurację bezpośrednio:
import { createOpencode } from "@opencode-ai/sdk"
const opencode = await createOpencode({
hostname: "127.0.0.1",
port: 4096,
config: {
model: "anthropic/claude-sonnet-5-5",
},
})
console.log(`Server running at ${opencode.server.url}`)
opencode.server.close()Jeśli masz już działającą instancję OpenCode, możesz utworzyć instancję klienta, aby się z nią połączyć:
import { createOpencodeClient } from "@opencode-ai/sdk"
const client = createOpencodeClient({
baseUrl: "http://localhost:4096",
})Opcje
| Opcja | Typ | Opis | Domyślne |
|---|---|---|---|
baseUrl | string | Adres URL serwera | http://localhost:4096 |
fetch | function | Niestandardowa implementacja fetch | globalThis.fetch |
parseAs | string | Metoda parsowania odpowiedzi | auto |
responseStyle | string | Styl zwracania: data lub fields | fields |
throwOnError | boolean | Rzucaj błędy zamiast zwracać je | false |
Zestaw SDK zawiera definicje TypeScript dla wszystkich typów API. Zaimportuj je bezpośrednio:
import type { Session, Message, Part } from "@opencode-ai/sdk"Wszystkie typy są generowane na podstawie specyfikacji OpenAPI serwera i dostępne w pliku typów.
SDK może generować błędy, które można przechwycić i obsłużyć:
try {
await client.session.get({ path: { id: "invalid-id" } })
} catch (error) {
console.error("Failed to get session:", (error as Error).message)
}Możesz zażądać ustrukturyzowanych danych wyjściowych JSON od modelu, określając format za pomocą schematu JSON. Model użyje narzędzia StructuredOutput, aby zwrócić zweryfikowany kod JSON pasujący do Twojego schematu.
const result = await client.session.prompt({
path: { id: sessionId },
body: {
parts: [{ type: "text", text: "Research Anthropic and provide company info" }],
format: {
type: "json_schema",
schema: {
type: "object",
properties: {
company: { type: "string", description: "Company name" },
founded: { type: "number", description: "Year founded" },
products: {
type: "array",
items: { type: "string" },
description: "Main products",
},
},
required: ["company", "founded"],
},
},
},
})
// Access the structured output
console.log(result.data.info.structured_output)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }| Typ | Opis |
|---|---|
text | Domyślny. Standardowa odpowiedź tekstowa (brak ustrukturyzowanych danych) |
json_schema | Zwraca zweryfikowany JSON pasujący do dostarczonego schematu |
Używając type: 'json_schema', podaj:
| Pole | Typ | Opis |
|---|---|---|
type | 'json_schema' | Wymagane. Określa tryb schematu JSON |
schema | object | Wymagane. Obiekt JSON Schema definiujący strukturę wyjściową |
retryCount | number | Opcjonalne. Liczba ponownych prób walidacji (domyślnie: 2) |
Jeśli model nie wygeneruje prawidłowych ustrukturyzowanych danych wyjściowych po wszystkich próbach, odpowiedź będzie zawierać StructuredOutputError:
if (result.data.info.error?.name === "StructuredOutputError") {
console.error("Failed to produce structured output:", result.data.info.error.message)
console.error("Attempts:", result.data.info.error.retries)
}- Podawaj jasne opisy we właściwościach schematu, aby pomóc modelowi zrozumieć, jakie dane wyodrębnić
- Używaj
required, aby określić, które pola muszą być obecne - Zachowaj schematy skoncentrowane - złożone zagnieżdżone schematy mogą być trudniejsze dla modelu do poprawnego wypełnienia
- Ustaw odpowiedni
retryCount- zwiększ dla złożonych schematów, zmniejsz dla prostych
Zestaw SDK udostępnia wszystkie interfejsy API serwera za pośrednictwem klienta bezpiecznego typu.
| Metoda | Opis | Odpowiedź |
|---|---|---|
global.health() | Sprawdź stan i wersję serwera | { healthy: true, version: string } |
Przykłady
const health = await client.global.health()
console.log(health.data.version)| Metoda | Opis | Odpowiedź |
|---|---|---|
app.log() | Zapisz wpis logu | boolean |
app.agents() | Lista wszystkich dostępnych agentów | Agent[] |
Przykłady
// Write a log entry
await client.app.log({
body: {
service: "my-app",
level: "info",
message: "Operation completed",
},
})
// List available agents
const agents = await client.app.agents()| Metoda | Opis | Odpowiedź |
|---|---|---|
project.list() | Lista wszystkich projektów | Project[] |
Przykłady
// List all projects
const projects = await client.project.list()
| Metoda | Opis | Odpowiedź |
|---|---|---|
path.get() | Pobierz bieżącą ścieżkę | Path |
Przykłady
// Get current path information
const pathInfo = await client.path.get()| Metoda | Opis | Odpowiedź |
|---|---|---|
config.get() | Pobierz informacje o konfiguracji | Config |
config.providers() | Lista dostawców i modeli domyślnych | { providers: Provider[], default: { [key: string]: string } } |
Przykłady
const config = await client.config.get()
const { providers, default: defaults } = await client.config.providers()| Metoda | Opis | Uwagi |
|---|---|---|
session.list() | Lista sesji | Zwraca Session[] |
session.get({ path }) | Pobierz sesję | Zwraca Session |
session.children({ path }) | Lista sesji podrzędnych | Zwraca Session[] |
session.create({ body }) | Utwórz sesję | Zwraca Session |
session.delete({ path }) | Usuń sesję | Zwraca boolean |
session.update({ path, body }) | Aktualizuj właściwości sesji | Zwraca Session |
session.init({ path, body }) | Przeanalizuj aplikację i utwórz AGENTS.md | Zwraca boolean |
session.abort({ path }) | Przerwij trwającą sesję | Zwraca boolean |
session.share({ path }) | Udostępnij sesję | Zwraca Session |
session.unshare({ path }) | Cofnij udostępnianie sesji | Zwraca Session |
session.summarize({ path, body }) | Podsumuj sesję | Zwraca boolean |
session.messages({ path }) | Lista wiadomości w sesji | Zwraca { info: Message, parts: Part[]}[] |
session.message({ path }) | Pobierz szczegóły wiadomości | Zwraca { info: Message, parts: Part[]} |
session.prompt({ path, body }) | Wyślij wiadomość | body.noReply: true zwraca UserMessage (tylko kontekst). Domyślnie zwraca AssistantMessage z odpowiedzią AI |
session.command({ path, body }) | Wyślij polecenie do sesji | Zwraca { info: AssistantMessage, parts: Part[]} |
session.shell({ path, body }) | Uruchom polecenie shell | Zwraca AssistantMessage |
session.revert({ path, body }) | Cofnij wiadomość (revert) | Zwraca Session |
session.unrevert({ path }) | Przywróć cofnięte wiadomości | Zwraca Session |
postSessionByIdPermissionsByPermissionId({ path, body }) | Odpowiedz na żądanie uprawnienia | Zwraca boolean |
Przykłady
// Create and manage sessions
const session = await client.session.create({
body: { title: "My session" },
})
const sessions = await client.session.list()
// Send a prompt message
const result = await client.session.prompt({
path: { id: session.id },
body: {
model: { providerID: "anthropic", modelID: "claude-sonnet-5-5" },
parts: [{ type: "text", text: "Hello!" }],
},
})
// Inject context without triggering AI response (useful for plugins)
await client.session.prompt({
path: { id: session.id },
body: {
noReply: true,
parts: [{ type: "text", text: "You are a helpful assistant." }],
},
})| Metoda | Opis | Odpowiedź |
|---|---|---|
find.text({ query }) | Szukaj tekstu w plikach | Tablica obiektów dopasowania z path, lines, line_number, absolute_offset, submatches |
find.files({ query }) | Znajdź pliki i katalogi według nazwy | string[] (ścieżki) |
find.symbols({ query }) | Znajdź symbole w obszarze roboczym | Symbol[] |
file.read({ query }) | Odczytaj plik | { type: "raw" | "patch", content: string } |
file.status({ query? }) | Pobierz status śledzonych plików | File[] |
find.files obsługuje kilka opcjonalnych pól zapytania:
type:"file"lub"directory"directory: zastąp katalog główny projektu dla wyszukiwanialimit: maks. wyników (1–200)
Przykłady
// Search and read files
const textResults = await client.find.text({
query: { pattern: "function.*opencode" },
})
const files = await client.find.files({
query: { query: "*.ts", type: "file" },
})
const directories = await client.find.files({
query: { query: "packages", type: "directory", limit: 20 },
})
const content = await client.file.read({
query: { path: "src/index.ts" },
})| Metoda | Opis | Odpowiedź |
|---|---|---|
tui.appendPrompt({ body }) | Dołącz tekst do promptu | boolean |
tui.openHelp() | Otwórz okno pomocy | boolean |
tui.openSessions() | Otwórz selektor sesji | boolean |
tui.openThemes() | Otwórz selektor motywów | boolean |
tui.openModels() | Otwórz selektor modelu | boolean |
tui.submitPrompt() | Prześlij bieżący prompt | boolean |
tui.clearPrompt() | Wyczyść prompt | boolean |
tui.executeCommand({ body }) | Wykonaj polecenie | boolean |
tui.showToast({ body }) | Pokaż powiadomienie (toast) | boolean |
Przykłady
// Control TUI interface
await client.tui.appendPrompt({
body: { text: "Add this to prompt" },
})
await client.tui.showToast({
body: { message: "Task completed", variant: "success" },
})| Metoda | Opis | Odpowiedź |
|---|---|---|
auth.set({ ... }) | Ustaw poświadczenia uwierzytelniania | boolean |
Przykłady
await client.auth.set({
path: { id: "anthropic" },
body: { type: "api", key: "your-api-key" },
})| Metoda | Opis | Odpowiedź |
|---|---|---|
event.subscribe() | Strumień zdarzeń wysyłanych przez serwer | Strumień zdarzeń wysyłanych przez serwer |
Przykłady
// Listen to real-time events
const events = await client.event.subscribe()
for await (const event of events.stream) {
console.log("Event:", event.type, event.properties)
}