تخطَّ إلى المحتوى
وثائق V1
التثبيت

مجموعة تطوير البرمجيات (SDK)

توفر SDK الخاصة بـ opencode لـ JS/TS عميلا آمنا للأنواع للتفاعل مع الخادم. استخدمها لبناء التكاملات والتحكم في opencode برمجيا.

اعرف المزيد حول كيفية عمل الخادم. للاطلاع على أمثلة، تفقد المشاريع التي أنشأها المجتمع.


ثبّت SDK من npm:

الطرفية
npm install @opencode-ai/sdk

أنشئ مثيلا من opencode:

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

const { client } = await createOpencode()

هذا يشغّل خادما وعميلا معا.

الخيارات

الخيارالنوعالوصفالافتراضي
hostnamestringاسم مضيف الخادم127.0.0.1
portnumberمنفذ الخادم4096
signalAbortSignalإشارة إلغاء للإيقافundefined
timeoutnumberمهلة بدء الخادم بالمللي ثانية5000
configConfigكائن الإعدادات{}

يمكنك تمرير كائن إعدادات لتخصيص السلوك. سيستمر المثيل في التقاط opencode.json لديك، لكن يمكنك تجاوز الإعدادات أو إضافة إعدادات مباشرة:

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

إذا كان لديك مثيل opencode يعمل بالفعل، يمكنك إنشاء مثيل عميل للاتصال به:

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

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

الخيارات

الخيارالنوعالوصفالافتراضي
baseUrlstringعنوان URL للخادمhttp://localhost:4096
fetchfunctionتنفيذ fetch مخصصglobalThis.fetch
parseAsstringطريقة تحليل الاستجابةauto
responseStylestringأسلوب الإرجاع: data أو fieldsfields
throwOnErrorbooleanرمي الأخطاء بدلا من إرجاعهاfalse

تتضمن SDK تعريفات TypeScript لجميع أنواع API. استوردها مباشرة:

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

جميع الأنواع مولّدة من مواصفات OpenAPI الخاصة بالخادم ومتاحة في ملف الأنواع.


يمكن أن ترمي SDK أخطاء يمكنك التقاطها ومعالجتها:

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

يمكنك طلب مخرجات JSON منظمة من النموذج عن طريق تحديد format مع مخطط JSON. سيستخدم النموذج أداة StructuredOutput لإرجاع JSON تم التحقق من صحته ومطابق للمخطط الخاص بك.

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

النوعالوصف
textالافتراضي. استجابة نصية قياسية (بدون مخرجات منظمة)
json_schemaيرجع JSON تم التحقق من صحته ومطابق للمخطط المقدم

عند استخدام type: 'json_schema'، يجب تقديم:

الحقلالنوعالوصف
type'json_schema'مطلوب. يحدد وضع مخطط JSON
schemaobjectمطلوب. كائن مخطط JSON الذي يحدد بنية الإخراج
retryCountnumberاختياري. عدد محاولات إعادة التحقق (الافتراضي: 2)

إذا فشل النموذج في إنتاج مخرجات منظمة صالحة بعد جميع المحاولات، ستتضمن الاستجابة StructuredOutputError:

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

  1. قدّم أوصافا واضحة في خصائص المخطط لمساعدة النموذج على فهم البيانات التي يجب استخراجها
  2. استخدم required لتحديد الحقول التي يجب أن تكون موجودة
  3. حافظ على تركيز المخططات - المخططات المتداخلة المعقدة قد تكون أصعب على النموذج لملئها بشكل صحيح
  4. عيّن retryCount مناسبا - قم بزيادته للمخططات المعقدة، وتقليله للمخططات البسيطة

توفر SDK جميع واجهات الخادم عبر عميل آمن للأنواع.


الطريقةالوصفالاستجابة
global.health()التحقق من صحة الخادم وإصداره{ healthy: true, version: string }

أمثلة

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

الطريقةالوصفالاستجابة
app.log()كتابة إدخال في السجلboolean
app.agents()سرد جميع الوكلاء المتاحينAgent[]

أمثلة

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

الطريقةالوصفالاستجابة
project.list()سرد جميع المشاريعProject[]

أمثلة

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

الطريقةالوصفالاستجابة
path.get()جلب المسار الحاليPath

أمثلة

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

الطريقةالوصفالاستجابة
config.get()جلب معلومات الإعداداتConfig
config.providers()سرد المزوّدين والنماذج الافتراضية{ providers: Provider[], default: { [key: string]: string } }

أمثلة

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

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

الطريقةالوصفملاحظات
session.list()سرد الجلساتيعيد Session[]
session.get({ path })جلب جلسةيعيد Session
session.children({ path })سرد الجلسات الفرعيةيعيد Session[]
session.create({ body })إنشاء جلسةيعيد Session
session.delete({ path })حذف جلسةيعيد boolean
session.update({ path, body })تحديث خصائص الجلسةيعيد Session
session.init({ path, body })تحليل التطبيق وإنشاء AGENTS.mdيعيد boolean
session.abort({ path })إيقاف جلسة قيد التشغيليعيد boolean
session.share({ path })مشاركة جلسةيعيد Session
session.unshare({ path })إلغاء مشاركة جلسةيعيد Session
session.summarize({ path, body })تلخيص جلسةيعيد boolean
session.messages({ path })سرد الرسائل في جلسةيعيد { info: Message, parts: Part[]}[]
session.message({ path })جلب تفاصيل الرسالةيعيد { info: Message, parts: Part[]}
session.prompt({ path, body })إرسال رسالة مطالبةbody.noReply: true يعيد UserMessage (للسياق فقط). الافتراضي يعيد AssistantMessage مع استجابة AI. يدعم body.outputFormat من أجل المخرجات المنظمة
session.command({ path, body })إرسال أمر إلى الجلسةيعيد { info: AssistantMessage, parts: Part[]}
session.shell({ path, body })تشغيل أمر shellيعيد AssistantMessage
session.revert({ path, body })التراجع عن رسالةيعيد Session
session.unrevert({ path })استعادة الرسائل المتراجع عنهايعيد Session
postSessionByIdPermissionsByPermissionId({ path, body })الاستجابة لطلب إذنيعيد boolean

أمثلة

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

الطريقةالوصفالاستجابة
find.text({ query })البحث عن نص داخل الملفاتمصفوفة من كائنات المطابقة مع path وlines وline_number وabsolute_offset وsubmatches
find.files({ query })العثور على الملفات والمجلدات بالاسمstring[] (مسارات)
find.symbols({ query })العثور على رموز مساحة العملSymbol[]
file.read({ query })قراءة ملف{ type: "raw" | "patch", content: string }
file.status({ query? })جلب حالة الملفات المتتبَّعةFile[]

يدعم find.files بعض حقول الاستعلام الاختيارية:

  • type: "file" أو "directory"
  • directory: تجاوز جذر المشروع لعملية البحث
  • limit: الحد الأقصى للنتائج (1–200)

أمثلة

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

الطريقةالوصفالاستجابة
tui.appendPrompt({ body })إلحاق نص بالمطالبةboolean
tui.openHelp()فتح مربع حوار المساعدةboolean
tui.openSessions()فتح محدد الجلساتboolean
tui.openThemes()فتح محدد السماتboolean
tui.openModels()فتح محدد النماذجboolean
tui.submitPrompt()إرسال المطالبة الحاليةboolean
tui.clearPrompt()مسح المطالبةboolean
tui.executeCommand({ body })تنفيذ أمرboolean
tui.showToast({ body })عرض إشعار toastboolean

أمثلة

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

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

الطريقةالوصفالاستجابة
auth.set({ ... })تعيين بيانات اعتماد المصادقةboolean

أمثلة

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

الطريقةالوصفالاستجابة
event.subscribe()تدفق أحداث مرسلة من الخادمتدفق أحداث مرسلة من الخادم

أمثلة

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