İçeriğe geç
V1 dokümanları
Kurulum

SDK

opencode JS/TS SDK, sunucu ile etkileşmek için type-safe bir istemci sağlar. opencode’u programatik olarak kontrol etmek ve entegrasyonlar oluşturmak için kullanabilirsiniz.

Sunucu sayfasında nasıl çalıştığını görebilir, örnekler için topluluğun oluşturduğu projeler bölümüne bakabilirsiniz.


SDK’yı npm’den yükleyin:

Terminal
npm install @opencode-ai/sdk

Bir opencode örneği oluşturun:

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

const { client } = await createOpencode()

Bu, hem bir sunucu hem de bir istemci başlatır

Seçenekler

SeçenekTipAçıklamaVarsayılan
hostnamestringSunucu ana bilgisayar adı127.0.0.1
portnumberSunucu bağlantı noktası4096
signalAbortSignalİptal için durdurma sinyaliundefined
timeoutnumberSunucu başlatma için ms cinsinden zaman aşımı5000
configConfigYapılandırma nesnesi{}

Davranışı özelleştirmek için bir yapılandırma nesnesi iletebilirsiniz. Örnek yine de opencode.json dosyanızı alır, ancak yapılandırmayı satır içi olarak geçersiz kılabilir veya ekleyebilirsiniz:

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

Halihazırda çalışan bir opencode örneğiniz varsa, ona bağlanmak için bir istemci örneği oluşturabilirsiniz:

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

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

Seçenekler

SeçenekTipAçıklamaVarsayılan
baseUrlstringSunucunun URL’sihttp://localhost:4096
fetchfunctionÖzel fetch uygulamasıglobalThis.fetch
parseAsstringYanıt ayrıştırma yöntemiauto
responseStylestringDönüş stili: data veya fieldsfields
throwOnErrorbooleanDönüş yerine hata fırlatfalse

SDK, tüm API türleri için TypeScript tanımlarını içerir. Bunları doğrudan içe aktarın:

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

Tüm tipler, sunucunun OpenAPI spesifikasyonundan oluşturulur ve tipler dosyasında mevcuttur.


SDK, yakalayabileceğiniz ve işleyebileceğiniz hatalar fırlatabilir:

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

Bir JSON şeması ile format belirterek modelden yapılandırılmış JSON çıktısı isteyebilirsiniz. Model, şemanızla eşleşen doğrulanmış JSON’u döndürmek için bir StructuredOutput aracı kullanacaktır.

TypeScript
const result = await client.session.prompt({
  path: { id: sessionId },
  body: {
    parts: [{ type: "text", text: "Anthropic'i araştırın ve şirket bilgileri sağlayın" }],
    format: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          company: { type: "string", description: "Şirket adı" },
          founded: { type: "number", description: "Kuruluş yılı" },
          products: {
            type: "array",
            items: { type: "string" },
            description: "Ana ürünler",
          },
        },
        required: ["company", "founded"],
      },
    },
  },
})

// Yapılandırılmış çıktıya erişin
console.log(result.data.info.structured_output)
// { company: "Anthropic", founded: 2021, products: ["Claude", "Claude API"] }

TürAçıklama
textVarsayılan. Standart metin yanıtı (yapılandırılmış çıktı yok)
json_schemaSağlanan şema ile eşleşen doğrulanmış JSON döndürür

type: 'json_schema' kullanırken şunları sağlayın:

AlanTürAçıklama
type'json_schema'Gerekli. JSON şema modunu belirtir
schemaobjectGerekli. Çıktı yapısını tanımlayan JSON Şema nesnesi
retryCountnumberİsteğe bağlı. Doğrulama yeniden deneme sayısı (varsayılan: 2)

Model, tüm yeniden denemelerden sonra geçerli bir yapılandırılmış çıktı üretemezse, yanıt bir StructuredOutputError içerecektir:

TypeScript
if (result.data.info.error?.name === "StructuredOutputError") {
  console.error("Yapılandırılmış çıktı üretilemedi:", result.data.info.error.message)
  console.error("Denemeler:", result.data.info.error.retries)
}

  1. Açık açıklamalar sağlayın: Modelin hangi verileri çıkaracağını anlamasına yardımcı olmak için şema özelliklerinde
  2. required kullanın: Hangi alanların mevcut olması gerektiğini belirtmek için
  3. Şemaları odaklı tutun: Karmaşık iç içe geçmiş şemaların model tarafından doğru doldurulması daha zor olabilir
  4. Uygun retryCount ayarlayın: Karmaşık şemalar için artırın, basit olanlar için azaltın

SDK, tüm sunucu API’lerini type-safe bir istemci aracılığıyla sunar.


YöntemAçıklamaYanıt
global.health()Sunucu sağlığını ve sürümünü kontrol et{ healthy: true, version: string }

Örnekler

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

YöntemAçıklamaYanıt
app.log()Bir günlük girdisi yazboolean
app.agents()Tüm mevcut agent’ları listeleAgent[]

Örnekler

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

YöntemAçıklamaYanıt
project.list()Tüm projeleri listeleProject[]

Örnekler

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

YöntemAçıklamaYanıt
path.get()Mevcut yolu alPath

Örnekler

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

YöntemAçıklamaYanıt
config.get()Yapılandırma bilgisini alConfig
config.providers()Sağlayıcıları ve varsayılan modelleri listele{ providers: Provider[], default: { [key: string]: string } }

Örnekler

JavaScript
const config = await client.config.get()

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

YöntemAçıklamaNotlar
session.list()Oturumları listeleSession[] döndürür
session.get({ path })Oturum alSession döndürür
session.children({ path })Alt oturumları listeleSession[] döndürür
session.create({ body })Oturum oluşturSession döndürür
session.delete({ path })Oturum silboolean döndürür
session.update({ path, body })Oturum özelliklerini güncelleSession döndürür
session.init({ path, body })Uygulamayı analiz et ve AGENTS.md oluşturboolean döndürür
session.abort({ path })Çalışan bir oturumu iptal etboolean döndürür
session.share({ path })Oturum paylaşSession döndürür
session.unshare({ path })Oturum paylaşımını kaldırSession döndürür
session.summarize({ path, body })Oturumu özetleboolean döndürür
session.messages({ path })Oturumdaki mesajları listele{ info: Message, parts: Part[]}[] döndürür
session.message({ path })Mesaj ayrıntılarını al{ info: Message, parts: Part[]} döndürür
session.prompt({ path, body })İstem mesajı gönderbody.noReply: true UserMessage (yalnızca bağlam) döndürür. Varsayılan olarak AI yanıtıyla AssistantMessage döndürür. yapılandırılmış çıktı için body.outputFormat destekler
session.command({ path, body })Oturuma komut gönder{ info: AssistantMessage, parts: Part[]} döndürür
session.shell({ path, body })Bir kabuk komutu çalıştırAssistantMessage döndürür
session.revert({ path, body })Bir mesajı geri alSession döndürür
session.unrevert({ path })Geri alınan mesajları geri yükleSession döndürür
postSessionByIdPermissionsByPermissionId({ path, body })Bir izin isteğine yanıt verboolean döndürür

Örnekler

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

YöntemAçıklamaYanıt
find.text({ query })Dosyalarda metin arapath, lines, line_number, absolute_offset, submatches içeren eşleşme nesneleri dizisi
find.files({ query })Dosya ve dizinleri isme göre bulstring[] (yollar)
find.symbols({ query })Çalışma alanı sembollerini bulSymbol[]
file.read({ query })Bir dosyayı oku{ type: "raw" | "patch", content: string }
file.status({ query? })İzlenen dosyalar için durumu alFile[]

find.files birkaç isteğe bağlı sorgu alanını destekler:

  • type: "file" veya "directory"
  • directory: arama için proje kökünü geçersiz kılma
  • limit: maksimum sonuç (1-200)

Örnekler

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

YöntemAçıklamaYanıt
tui.appendPrompt({ body })İsteme metin ekleboolean
tui.openHelp()Yardım iletişim kutusunu açboolean
tui.openSessions()Oturum seçiciyi açboolean
tui.openThemes()Tema seçiciyi açboolean
tui.openModels()Model seçiciyi açboolean
tui.submitPrompt()Mevcut istemi gönderboolean
tui.clearPrompt()İstemi temizleboolean
tui.executeCommand({ body })Bir komut çalıştırboolean
tui.showToast({ body })Toast bildirimi gösterboolean

Örnekler

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

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

YöntemAçıklamaYanıt
auth.set({ ... })Kimlik bilgilerini ayarlaboolean

Örnekler

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

YöntemAçıklamaYanıt
event.subscribe()Sunucu tarafından gönderilen olay akışıSunucu tarafından gönderilen olay akışı

Örnekler

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