SDK

Typesikker JS-klient for åpen kodeserver.

Åpenkoden JS/TS SDK gir en typesikker klient for samhandling med serveren. Brug den til at bygge integrasjoner og kontrollere opencode programmatisk.

Finn ut mer om hvordan serveren fungerer. For eksempler, tjek ut prosjektene bygget av fellesskapet.

Installation

Installer SDK fra npm:

npm install @opencode-ai/sdk

Opret klient

Opret en forekomst av opencode:

import { createOpencode } from "@opencode-ai/sdk"

const { client } = await createOpencode()

Dette starter både en server og en klient

Indstillinger

Alternativ	Skriv	Beskrivelse	Standard
`hostname`	`string`	Server vertsnavn	`127.0.0.1`
`port`	`number`	Serverport	`4096`
`signal`	`AbortSignal`	Avbryt signal for kansellering	`undefined`
`timeout`	`number`	Tidsavbrudd i ms for serverstart	`5000`
`config`	`Config`	Konfigurasjonsobjekt	`{}`

Konfig

Du kan sende et konfigurasjonsobjekt for at tilpasse virkemåten. Forekomsten henter fortsatt din opencode.json, men du kan overstyre eller tilføje til konfigurasjon inline:

import { createOpencode } from "@opencode-ai/sdk"

const opencode = await createOpencode({
  hostname: "127.0.0.1",
  port: 4096,
  config: {
    model: "anthropic/claude-3-5-sonnet-20241022",
  },
})

console.log(`Server running at ${opencode.server.url}`)

opencode.server.close()

Kun klient

Hvis du allerede har en kjørende forekomst av opencode, kan du oprete en klientforekomst for at koble til den:

import { createOpencodeClient } from "@opencode-ai/sdk"

const client = createOpencodeClient({
  baseUrl: "http://localhost:4096",
})

Indstillinger

Alternativ	Skriv inn	Beskrivelse	Standard
`baseUrl`	`string`	URL av serveren	`http://localhost:4096`
`fetch`	`function`	Egendefinert hentingimplementering	`globalThis.fetch`
`parseAs`	`string`	Svarparsingmetode	`auto`
`responseStyle`	`string`	Returstil: `data` eller `fields`	`fields`
`throwOnError`	`boolean`	Kast feil i stedet for retur	`false`

Typer

SDK inkluderer TypeScript-definisjoner for alle API-typer. Importer dem direkte:

import type { Session, Message, Part } from "@opencode-ai/sdk"

Alle typer er generert fra serverens OpenAPI-spesifikasjon og tilgængelig i types-filen.

Fejl

SDK kan gi feil som du kan fange opp og håndtere:

try {
  await client.session.get({ path: { id: "invalid-id" } })
} catch (error) {
  console.error("Failed to get session:", (error as Error).message)
}

Du kan anmode om struktureret JSON-output fra modellen ved at angive et format med et JSON-skema. Modellen vil bruge et StructuredOutput-værktøj til at returnere valideret JSON, der matcher dit skema.

Grundlæggende brug

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"] }

Outputformat-typer

Type	Beskrivelse
`text`	Standard. Standard tekstsvar (intet struktureret output)
`json_schema`	Returnerer valideret JSON, der matcher det angivne skema

JSON-skemaformat

Når du bruger type: 'json_schema', skal du angive:

Felt	Type	Beskrivelse
`type`	`'json_schema'`	Påkrævet. Angiver JSON-skematilstand
`schema`	`object`	Påkrævet. JSON-skemaobjekt, der definerer outputstrukturen
`retryCount`	`number`	Valgfri. Antal valideringsforsøg (standard: 2)

Fejlhåndtering

Hvis modellen ikke formår at producere gyldigt struktureret output efter alle forsøg, vil svaret inkludere en 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)
}

Bedste praksis

Giv klare beskrivelser i dine skemaegenskaber for at hjælpe modellen med at forstå, hvilke data der skal udtrækkes
Brug required til at angive, hvilke felter der skal være til stede
Hold skemaer fokuserede - komplekse indlejrede skemaer kan være sværere for modellen at udfylde korrekt
Indstil passende retryCount - øg for komplekse skemaer, sænk for enkle

API’er

SDK avslører alle server-APIer gjennom en typesikker klient.

Globalt

Metode	Beskrivelse	Svar
`global.health()`	Tjek serverhelse og versjon	`{ healthy: true, version: string }`

Eksempler

const health = await client.global.health()
console.log(health.data.version)

App

Metode	Beskrivelse	Svar
`app.log()`	Skriv en loggoppføring	`boolean`
`app.agents()`	Liste alle tilgængelige agenter	`Agent[]`

Eksempler

// 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()

Projekt

Metode	Beskrivelse	Svar
`project.list()`	Liste over alle prosjekter	`Prosjekt[]`
`project.current()`	Få nåværende prosjekt	`Prosjekt`

Eksempler

// List all projects
const projects = await client.project.list()

// Get current project
const currentProject = await client.project.current()

Sti

Metode	Beskrivelse	Svar
`path.get()`	Få nuværende bane	`Path`

Eksempler

// Get current path information
const pathInfo = await client.path.get()

Konfiguration

Metode	Beskrivelse	Svar
`config.get()`	Få konfigurasjonsinformasjon	`Config`
`config.providers()`	Liste leverandører og standardmodeller	`{ providers:` `Provider[], default: { [key: string]: string } }`

Eksempler

const config = await client.config.get()

const { providers, default: defaults } = await client.config.providers()

Sessioner

Metode	Beskrivelse	Noter
`session.list()`	Liste sessioner	Returnerer `Session[]`
`session.get({ path })`	Få session	Returnerer `Session`
`session.children({ path })`	Liste over barnesessioner	Returnerer `Session[]`
`session.create({ body })`	Opret session	Returnerer `Session`
`session.delete({ path })`	Slett session	Returnerer `boolean`
`session.update({ path, body })`	Opdater sessionegenskaper	Returnerer `Session`
`session.init({ path, body })`	Analyser appen og lag `AGENTS.md`	Returnerer `boolean`
`session.abort({ path })`	Avbryt en løpesession	Returnerer `boolean`
`session.share({ path })`	Del sessionen	Returnerer `Session`
`session.unshare({ path })`	Slutt at dele sessionen	Returnerer `Session`
`session.summarize({ path, body })`	Oppsummer sessionen	Returnerer `boolean`
`session.messages({ path })`	Liste meldinger i en session	Returnerer `{ info:` `Message, parts:` `Part[]}[]`
`session.message({ path })`	Få meldingsdetaljer	Returnerer `{ info:` `Message, parts:` `Part[]}`
`session.prompt({ path, body })`	Send melding	`body.noReply: true` returnerer UserMessage (kun kontekst). Standard returnerer `AssistantMessage` med AI svar. Understøtter `body.outputFormat` for struktureret output
`session.command({ path, body })`	Send kommando til session	Returnerer `{ info:` `AssistantMessage, parts:` `Part[]}`
`session.shell({ path, body })`	Kjør en shell-kommando	Returnerer `AssistantMessage`
`session.revert({ path, body })`	Tilbakestill en melding	Returnerer `Session`
`session.unrevert({ path })`	Gjenopret nulstillete meldinger	Returnerer `Session`
`postSessionByIdPermissionsByPermissionId({ path, body })`	Svar på en tillatelsesforespørsel	Returnerer `boolean`

Eksempler

// 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-3-5-sonnet-20241022" },
    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." }],
  },
})

Filer

Metode	Beskrivelse	Svar
`find.text({ query })`	Søk etter tekst i filer	En rekke matchobjekter med `path`, `lines`, `line_number`, `absolute_offset`, `submatches`
`find.files({ query })`	Finn filer og kataloger etter navn	`string[]` (baner)
`find.symbols({ query })`	Finn arbeidsområdesymboler	`Symbol[]`
`file.read({ query })`	Les en fil	`{ type: "raw" \| "patch", content: string }`
`file.status({ query? })`	Få status for sporede filer	`Fil[]`

find.files støtter nogle få valgfrie søkefelt:

type: "file" eller "directory"
directory: overstyr prosjektroten for søket
limit: maksimalt antall resultater (1–200)

Eksempler

// 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" },
})

TUI

Metode	Beskrivelse	Svar
`tui.appendPrompt({ body })`	Legg til tekst i ledeteksten	`boolean`
`tui.openHelp()`	Åpne hjelpedialogen	`boolean`
`tui.openSessions()`	Åpne sessionvelgeren	`boolean`
`tui.openThemes()`	Åpne temavelgeren	`boolean`
`tui.openModels()`	Åpne modellvelgeren	`boolean`
`tui.submitPrompt()`	Send inn nuværende ledetekst	`boolean`
`tui.clearPrompt()`	Fjern ledeteksten	`boolean`
`tui.executeCommand({ body })`	Utfør en kommando	`boolean`
`tui.showToast({ body })`	Vis toastvarsel	`boolean`

Eksempler

// Control TUI interface
await client.tui.appendPrompt({
  body: { text: "Add this to prompt" },
})

await client.tui.showToast({
  body: { message: "Task completed", variant: "success" },
})

Godkendelse

Metode	Beskrivelse	Svar
`auth.set({ ... })`	Angi autentiseringslegitimasjon	`boolean`

Eksempler

await client.auth.set({
  path: { id: "anthropic" },
  body: { type: "api", key: "your-api-key" },
})

Hændelser

Metode	Beskrivelse	Svar
`event.subscribe()`	Server-sendte hendelser stream	Server-sendte hendelser stream

Eksempler

// 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)
}